feat(language): editor support for timing modes + deprecation hints

Author: a-baran-orhan

editors/vscode/syntaxes/posecode.tmLanguage.json

@@ -45,7 +45,7 @@
     },
     "constants": {
       "name": "constant.language.posecode",
-      "match": "\\b(ease-in-out|ease-in|ease-out|linear|neutral|standing|plank|hands|feet|humanoid)\\b"
+      "match": "\\b(flow|settle|drive|snap|linear|ease-in-out|ease-in|ease-out|neutral|standing|plank|hands|feet|humanoid)\\b"
     },
     "numbers": {
       "name": "constant.numeric.posecode",

packages/posecode-language/src/completion.ts

@@ -10,7 +10,7 @@ import {
   POSES,
   EFFECTORS,
   REACH_EFFECTORS,
-  EASINGS,
+  MODES,
   JOINT_NAMES,
   ACTION_NAMES,
   TOP_KEYWORDS,
@@ -80,7 +80,7 @@ export function getCompletions(
     case "pose":
       return POSES.map((p) => item(p, "pose"));
     case "easing":
-      return EASINGS.map((e) => item(e, "easing"));
+      return MODES.map((e) => item(e, "easing"));
     case "effector":
       return EFFECTORS.map((e) => item(e, "effector"));
     case "reach-effector":

packages/posecode-language/src/diagnostics.ts

@@ -5,8 +5,9 @@
  */
 
 import { parse, boneType } from "posecode-parser";
+import { LEGACY_MODE_ALIASES } from "./vocab.js";
 
-export type Severity = "error" | "warning";
+export type Severity = "error" | "warning" | "hint";
 
 export interface Diagnostic {
   /** 1-based source line. */
@@ -36,5 +37,21 @@ export function getDiagnostics(text: string): Diagnostic[] {
     });
   }
 
+  // Deprecation hints: legacy easing names still parse (via aliases) but nudge
+  // authors toward the canonical timing modes. Scanned lexically so the hint
+  // survives even when the rest of the document has errors.
+  const lines = text.split(/\r?\n/);
+  lines.forEach((lineText, idx) => {
+    const m = /^\s*step\s+"[^"]*"\s+[0-9.]+s\s+([\w-]+)\s*:/.exec(lineText);
+    const tok = m?.[1];
+    if (tok && tok !== "linear" && tok in LEGACY_MODE_ALIASES) {
+      diagnostics.push({
+        line: idx + 1,
+        severity: "hint",
+        message: `"${tok}" is deprecated; use "${LEGACY_MODE_ALIASES[tok]}"`,
+      });
+    }
+  });
+
   return diagnostics;
 }

packages/posecode-language/src/hover.ts

@@ -8,7 +8,7 @@ import { expandJoint, romFor, boneType } from "posecode-parser";
 import {
   JOINT_NAMES,
   ACTION_NAMES,
-  EASINGS,
+  MODES,
   KINDS,
   POSES,
   KEYWORD_DOCS,
@@ -73,8 +73,8 @@ export function getHover(
   if (keywordDoc) return md(`**${token}**: ${keywordDoc}`);
   if (KINDS.includes(token)) return md(`Movement kind **${token}**.`);
   if (POSES.includes(token)) return md(`Start pose **${token}**.`);
-  if ((EASINGS as readonly string[]).includes(token)) {
-    return md(`Easing **${token}**.`);
+  if ((MODES as readonly string[]).includes(token)) {
+    return md(`**${token}** — ${KEYWORD_DOCS[token] ?? "timing mode"}`);
   }
   return null;
 }

packages/posecode-language/src/index.ts

@@ -22,4 +22,5 @@ export {
   JOINT_NAMES,
   ACTION_NAMES,
   EASINGS,
+  MODES,
 } from "./vocab.js";

packages/posecode-language/src/vocab.ts

@@ -4,9 +4,16 @@
  * drift from what the language actually accepts.
  */
 
-import { JOINT_NAMES, ACTION_NAMES, EASINGS, EFFECTOR_NAMES } from "posecode-parser";
+import {
+  JOINT_NAMES,
+  ACTION_NAMES,
+  EASINGS,
+  MODES,
+  LEGACY_MODE_ALIASES,
+  EFFECTOR_NAMES,
+} from "posecode-parser";
 
-export { JOINT_NAMES, ACTION_NAMES, EASINGS };
+export { JOINT_NAMES, ACTION_NAMES, EASINGS, MODES, LEGACY_MODE_ALIASES };
 
 /** Movement kinds in the header (`posecode <kind> "..."`). */
 export const KINDS = ["exercise", "stretch", "posture"];
@@ -35,7 +42,12 @@ export const KEYWORD_DOCS: Record<string, string> = {
   pose: "Sets the starting pose: `pose start = standing | neutral | plank | supine | prone | seated`.",
   start: "Used in `pose start = <pose>`.",
   clip: 'Optional mocap clip: `clip "walk"`. A renderer with a matching retargeted animation plays it crossfaded over the procedural pose; others ignore it.',
-  step: 'A movement phase: `step "<name>" <Ns> <easing>:`.',
+  step: 'A movement phase: `step "<name>" <Ns> <mode>:` where mode is flow | settle | drive | snap | linear.',
+  flow: "Timing mode: pass through this pose with continuous velocity (flowing motion).",
+  settle: "Timing mode: decelerate to a genuine rest at this pose (a deliberate pause).",
+  drive: "Timing mode: accelerate from rest — the concentric effort of a rep.",
+  snap: "Timing mode: fast, near-immediate arrival — an accent.",
+  linear: "Timing mode: constant velocity — intentionally mechanical.",
   repeat: "How many times the movement loops.",
   "ground-lock": "Pins effectors (hands / feet) to the floor for this phase.",
   reach:

packages/posecode-language/test/language.test.ts

@@ -63,9 +63,9 @@ describe("getCompletions", () => {
     );
   });
 
-  it("suggests easings inside a step header", () => {
+  it("suggests timing modes inside a step header", () => {
     expect(onLine('  step "y" 2s ', 14)).toEqual(
-      expect.arrayContaining(["ease-in", "linear"]),
+      expect.arrayContaining(["flow", "settle", "linear"]),
     );
   });
 
@@ -104,3 +104,34 @@ describe("getHover", () => {
     expect(getHover("    ", 0, 2)).toBeNull();
   });
 });
+
+describe("timing modes (L2)", () => {
+  const modeDoc = ['posecode exercise "x"', "  rig humanoid", "  step \"A\" 1s "].join("\n");
+
+  it("completes timing modes after a step duration", () => {
+    const lineText = modeDoc.split("\n")[2]!;
+    const got = getCompletions(modeDoc, 2, lineText.length).map((i) => i.label);
+    expect(got).toEqual(
+      expect.arrayContaining(["flow", "settle", "drive", "snap", "linear"]),
+    );
+  });
+
+  it("hovers a mode", () => {
+    const doc = 'posecode exercise "x"\n  rig humanoid\n  step "A" 1s flow:';
+    const line = doc.split("\n")[2]!;
+    const h = getHover(doc, 2, line.indexOf("flow") + 1);
+    expect(h?.contents.toLowerCase()).toContain("flow");
+  });
+
+  it("flags a deprecated easing name with a hint", () => {
+    const doc = [
+      'posecode exercise "x"',
+      "  rig humanoid",
+      '  step "A" 1s ease-in-out:',
+      "    knees: flex 10",
+    ].join("\n");
+    const diags = getDiagnostics(doc);
+    const hint = diags.find((d) => d.severity === "hint");
+    expect(hint?.message).toContain("settle");
+  });
+});