feat(parser): timing modes with legacy easing aliases

Author: a-baran-orhan

packages/posecode-parser/src/index.ts

@@ -34,6 +34,7 @@ export function parse(source: string): ParseResult {
 export type {
   Axis,
   Easing,
+  TimingMode,
   EulerDeg,
   JointTarget,
   ReachTarget,
@@ -57,4 +58,4 @@ export {
   boneType,
 } from "./joints.js";
 export { romFor, clampAngle, eulerRomFor, type RomLimit, type EulerRom } from "./rom.js";
-export { EASINGS } from "./schema.js";
+export { EASINGS, MODES, LEGACY_MODE_ALIASES, normalizeMode } from "./schema.js";

packages/posecode-parser/src/parser.ts

@@ -8,6 +8,7 @@
 
 import { tokenize, TokenizeError, type Line, type Token } from "./tokenizer.js";
 import type { ParseError } from "./types.js";
+import { normalizeMode, MODES } from "./schema.js";
 
 export interface AstJointTarget {
   joint: string;
@@ -151,25 +152,32 @@ export function parseToAst(source: string): ParseAstResult {
       case "step": {
         const name = t[1];
         const dur = t[2];
-        const easing = word(t[3]);
+        const easingTok = word(t[3]);
+        const resolved = easingTok
+          ? normalizeMode(easingTok)
+          : { mode: null, legacy: false };
         const colon = t[4];
         if (
           name?.type !== "str" ||
           dur?.type !== "dur" ||
-          !easing ||
+          !easingTok ||
+          resolved.mode === null ||
           colon?.type !== "colon"
         ) {
           errors.push({
             line: ln.line,
-            message: 'expected `step "<name>" <duration> <easing>:`',
+            message:
+              resolved.mode === null && easingTok
+                ? `unknown timing mode "${easingTok}"; expected one of ${MODES.join(", ")}`
+                : 'expected `step "<name>" <duration> <mode>:`',
           });
           current = null;
           break;
         }
         current = {
           name: name.value,
           durationSec: parseDuration(dur.value),
-          easing,
+          easing: resolved.mode,
           targets: [],
           groundLock: [],
           reaches: [],

packages/posecode-parser/src/schema.ts

@@ -8,10 +8,32 @@
  */
 
 import { z } from "zod";
-import type { ParseError } from "./types.js";
+import type { ParseError, TimingMode } from "./types.js";
 import type { AstDoc } from "./parser.js";
 
-export const EASINGS = ["linear", "ease-in", "ease-out", "ease-in-out"] as const;
+export const MODES = ["flow", "settle", "drive", "snap", "linear"] as const;
+
+/** Deprecated easing names → canonical mode. Kept so existing docs never break. */
+export const LEGACY_MODE_ALIASES: Record<string, TimingMode> = {
+  "ease-in": "drive",
+  "ease-out": "settle",
+  "ease-in-out": "settle",
+  linear: "linear",
+};
+
+/** Back-compat: the old exported name, now the union of accepted written tokens. */
+export const EASINGS = [...MODES, "ease-in", "ease-out", "ease-in-out"] as const;
+
+/** Map a written token to a canonical mode + whether it was a legacy alias. */
+export function normalizeMode(raw: string): { mode: TimingMode | null; legacy: boolean } {
+  if ((MODES as readonly string[]).includes(raw)) {
+    return { mode: raw as TimingMode, legacy: false };
+  }
+  const alias = LEGACY_MODE_ALIASES[raw];
+  // "linear" is canonical, not a deprecation — only non-canonical aliases are legacy.
+  if (alias) return { mode: alias, legacy: raw !== "linear" };
+  return { mode: null, legacy: false };
+}
 
 const jointTargetSchema = z.object({
   joint: z.string().min(1),
@@ -35,7 +57,7 @@ const pinSchema = z.object({
 const stepSchema = z.object({
   name: z.string(),
   durationSec: z.number().positive(),
-  easing: z.enum(EASINGS),
+  easing: z.enum(MODES),
   targets: z.array(jointTargetSchema),
   groundLock: z.array(z.string()),
   reaches: z.array(reachSchema),

packages/posecode-parser/src/types.ts

@@ -11,7 +11,9 @@ export const POSECODE_VERSION = "0.1";
 
 export type Axis = "x" | "y" | "z";
 
-export type Easing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+export type TimingMode = "flow" | "settle" | "drive" | "snap" | "linear";
+/** @deprecated use TimingMode. Kept as an alias for one release. */
+export type Easing = TimingMode;
 
 /** Euler rotation in degrees, local to a bone's rest orientation. */
 export interface EulerDeg {

packages/posecode-parser/test/parse.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { parse } from "../src/index.js";
+import { parse, normalizeMode, MODES } from "../src/index.js";
 
 const PUSHUP = [
   'posecode exercise "Push-up"',
@@ -38,7 +38,7 @@ describe("parse", () => {
     const lower = ir!.phases[0]!;
     expect(lower.name).toBe("Lower");
     expect(lower.durationSec).toBe(2);
-    expect(lower.easing).toBe("ease-in");
+    expect(lower.easing).toBe("drive"); // legacy `ease-in` normalizes to canonical mode
     expect(lower.cue).toBe("Elbows ~45 from torso");
     expect(lower.groundLock.sort()).toEqual(["feet", "hands"]);
 
@@ -114,15 +114,15 @@ describe("parse", () => {
     expect(errors[0]!.message).toMatch(/header|must start/i);
   });
 
-  it("rejects an unknown easing", () => {
+  it("rejects an unknown timing mode", () => {
     const src = [
-      'posecode exercise "Bad easing"',
+      'posecode exercise "Bad mode"',
       "  rig humanoid",
       '  step "Move" 1s wobble:',
       "    elbows: flex 90",
     ].join("\n");
     const { errors } = parse(src);
-    expect(errors.some((e) => /easing/i.test(e.message))).toBe(true);
+    expect(errors.some((e) => /mode/i.test(e.message))).toBe(true);
   });
 
   it("parses turn and travel into the phase IR", () => {
@@ -267,3 +267,37 @@ describe("clip directive", () => {
     expect(errors[0]!.message).toContain("clip");
   });
 });
+
+describe("timing modes", () => {
+  it("accepts the canonical modes", () => {
+    for (const m of MODES) {
+      const src = `posecode exercise "x"\n  rig humanoid\n  step "s" 1s ${m}:\n    knees: flex 10\n`;
+      const { errors } = parse(src);
+      expect(errors).toEqual([]);
+    }
+  });
+
+  it("normalizes legacy easing names to canonical modes", () => {
+    expect(normalizeMode("ease-in")).toEqual({ mode: "drive", legacy: true });
+    expect(normalizeMode("ease-out")).toEqual({ mode: "settle", legacy: true });
+    expect(normalizeMode("ease-in-out")).toEqual({ mode: "settle", legacy: true });
+    expect(normalizeMode("linear")).toEqual({ mode: "linear", legacy: false });
+    expect(normalizeMode("flow")).toEqual({ mode: "flow", legacy: false });
+    expect(normalizeMode("bogus")).toEqual({ mode: null, legacy: false });
+  });
+
+  it("legacy documents still parse and carry a canonical mode", () => {
+    const src =
+      `posecode exercise "sq"\n  rig humanoid\n  step "Descend" 1s ease-in-out:\n    knees: flex 90\n`;
+    const { ir, errors } = parse(src);
+    expect(errors).toEqual([]);
+    expect(ir?.phases[0]?.easing).toBe("settle");
+  });
+
+  it("rejects an unknown mode with a clear error", () => {
+    const src = `posecode exercise "x"\n  rig humanoid\n  step "s" 1s wobble:\n    knees: flex 10\n`;
+    const { errors } = parse(src);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]!.message.toLowerCase()).toContain("mode");
+  });
+});