motionloom 2.5.1 → 2.6.0

package/docs/STATUS.md

@@ -4,7 +4,7 @@
 
 ## Current release posture
 
-MotionLoom's repository source and package manifest carry **2.5.1 release metadata**. The publication state of the npm registry and GitHub Release/tag must be verified against the latest release workflow rather than inferred from this document. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance, a truthful code-authored runtime lane and a browser-based Dev Lab review contract. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
+MotionLoom's repository source and package manifest carry **2.6.0 release metadata**. The publication state of the npm registry and GitHub Release/tag must be verified against the latest release workflow rather than inferred from this document. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance, a truthful code-authored runtime lane and an interactive browser-based Dev Lab review workbench. Dev Lab now supports hash-bound live playback, arbitrary project-defined action libraries, and optional state/transition review flows in addition to deterministic snapshot evidence. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
 
 The repository is **engineering-ready for continued integration work**, not a universal production certification for every animation framework or every host project. CI status must be read from the latest GitHub Actions run, not inferred from historical audit prose.
 
@@ -16,7 +16,7 @@ The repository is **engineering-ready for continued integration work**, not a un
 | Rive, GSAP and Framer Motion | Adapter and fixture evidence | Framework-specific runtime adapters and smoke checks can render representative scenes through browser/runtime paths | Equivalent coverage to the Lottie path across arbitrary projects |
 | Project Memory | Contract and relocation evidence | Stable project identity, atomic persistence, integrity guard, freshness states and path rebinding after relocation | Automatic correctness of an Agent's inferred decision |
 | Semantic intelligence | Deterministic evaluation evidence | Project graph, provenance, Motion IR, continuity, fix-plan and adversarial/deep-stress contracts; bounded analyzer reports scan budgets and truncation | Human-level design judgment, external-project product-value evidence or guaranteed first-pass acceptance |
-| Dev Lab | Review infrastructure evidence | Identity-bound candidate loading, deterministic scrub/snapshot, user checklist and review export | A visual editor, automatic approval or PR authorization |
+| Dev Lab | Interactive review infrastructure evidence | Identity-bound candidate loading, live runtime playback controls, arbitrary Action Library discovery, state/transition and review-sequence testing, deterministic snapshots, user checklist and review export | A full visual authoring editor, automatic approval or PR authorization |
 
 ## Normative sources
 
@@ -30,4 +30,4 @@ Use the following order when sources disagree:
 
 ## Known next work
 
-The bounded analyzer has now been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The 2.5.0 version–tag–GitHub Release–npm chain has been verified against public metadata. The highest-value remaining evidence work is paired product evaluation across more real projects and repeating the same provenance verification for each new release. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert heuristic warnings into approval.
+The bounded analyzer has been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The 2.5.x publication chain established npm/GitHub release provenance, and 2.6.0 adds a substantially richer Dev Lab review surface without weakening the human approval boundary. The highest-value next evidence work is consumer-project review of real action sets and transitions, followed by paired product evaluation across more real projects and repeating the same provenance verification for each new release. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert runtime success or heuristic warnings into approval.

package/docs/releases/2.6.0.md

@@ -0,0 +1,38 @@
+# MotionLoom 2.6.0
+
+## Summary
+
+MotionLoom 2.6.0 turns Dev Lab from a mostly checkpoint-oriented browser reviewer into an interactive runtime review workbench. The release keeps deterministic snapshots as evidence, but adds a live runtime lane for real playback, scalable project-defined action sets, and optional state/transition review flows so a user can inspect behavior much closer to the target runtime before approving a candidate.
+
+## Added
+
+- Interactive Dev Lab transport controls for live candidates: play, pause, restart, normalized scrub, frame stepping, playback speed and loop control.
+- Stage inspection tools including fullscreen, zoom/fit, background selection, grid, bounds, baseline and pivot overlays; sprite candidates can opt into crisp pixel-art rendering.
+- Data-driven animation discovery from `devlab-runtime.json`. Action names such as `idle`, `walk`, `run`, `attack`, `jump`, skills, emotes or project-specific clips are not hard-coded into MotionLoom.
+- Scalable Action Library support with project-defined groups/categories, tags, search, collapsible sections and filters for review-required, unreviewed, looping and one-shot actions.
+- Optional hash-bound `devlab-state-machine.json` contract with explicit states, legal transitions, multi-step review sequences and independent transition/sequence review coverage.
+- Portable `select-animation` transitions for sprite/clip runtimes and strict `runtime-trigger` transitions for iframe runtimes through `triggerTransition(request)`.
+- Transition history and review evidence for inspected actions, transitions, sequences and observed runtime state.
+
+## Hardened
+
+- Live runtime files, descriptors and state-machine bytes are bound into the browser-review candidate hash when declared; runtime-byte drift invalidates the candidate.
+- Path traversal, absolute paths, symlink escapes, duplicate animation ids, undeclared runtime files and mismatched candidate/runtime animation sets fail closed.
+- A declared live runtime that cannot load is shown as `LIVE RUNTIME UNAVAILABLE`; captured snapshots remain inspectable for diagnosis but approval is blocked.
+- `runtime-trigger` transitions are counted only after the runtime reports the declared target state. MotionLoom never silently downgrades an unsupported runtime trigger into a clip switch.
+- Search, grouping and filters affect presentation only. Hidden required actions or transitions still count as unreviewed.
+- `runtime-bridge.js` is included in the npm package allowlist so installed-package iframe/state-machine review does not depend on source-checkout-only files.
+
+## Verified behavior
+
+The Dev Lab CI harness covers deterministic snapshots, live sprite playback, iframe runtime bridging, a four-action interactive dogfood set, a twelve-action Action Library fixture, sprite state transitions, real iframe runtime-trigger transitions and browser-security smoke tests. The state/transition fixtures exercise flows such as `Idle -> Run -> Attack -> Hurt -> Idle` and verify that completing runtime coverage does not create a user approval decision.
+
+The protected release workflow reruns documentation/package validation, Skill Doctor, the full regression harness, isolated installed-package consumer smoke and release traceability before npm publication.
+
+## Trust boundary
+
+MotionLoom 2.6.0 does not turn runtime success into visual approval, production approval or PR authorization. Playback controls, action coverage, transition coverage, runtime state, hashes, snapshots, telemetry and automated sequence completion are evidence only. `approved` remains an explicit user decision bound to the exact browser-review candidate.
+
+AI-generated or otherwise non-authoritative source assets retain their declared provenance and authority tier. Dev Lab review does not promote `ai_generated` material to `artist_authored`, `production_eligible` or `production_approved`.
+
+The native macOS/iOS companion remains an unsigned source alpha. npm publication and GitHub Release creation remain explicit maintainer release actions through the protected GitHub Actions workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionloom",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "type": "module",
   "packageManager": "pnpm@11.20.0",
   "description": "MotionLoom: project-aware animation Skill with Agent interoperability, graph, provenance, Motion IR, runtime telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, external evidence verification and Dev Lab review.",
@@ -36,6 +36,8 @@
     "requirements.txt",
     "dev-lab/public/index.html",
     "dev-lab/public/devlab.js",
+    "dev-lab/public/action-library.js",
+    "dev-lab/public/runtime-bridge.js",
     "tests/runtime-harness",
     "tests/evals",
     "tests/scripts/run_tests.py",

package/schemas/browser-review-candidate.schema.json

@@ -15,6 +15,43 @@
     "source_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
     "runtime": {"type": "string"},
     "checkpoints": {"type": "array", "items": {"type": "integer", "enum": [0, 50, 100]}},
+    "runtime_review": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["live", "mode", "checkpoints"],
+          "properties": {
+            "live": {"const": false},
+            "mode": {"const": "captured-evidence"},
+            "checkpoints": {"type": "array", "items": {"type": "integer", "enum": [0, 50, 100]}}
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["live", "mode", "descriptor", "bundle_sha256", "animations", "review_policy"],
+          "properties": {
+            "live": {"const": true},
+            "mode": {"enum": ["sprite-sequence", "iframe"]},
+            "descriptor": {"const": "devlab-runtime.json"},
+            "bundle_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+            "animations": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"}
+            },
+            "review_policy": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["require_all_animations"],
+              "properties": {"require_all_animations": {"type": "boolean"}}
+            }
+          }
+        }
+      ]
+    },
     "review_artifact": {"type": "string"},
     "requires_user_approval": {"type": "boolean"},
     "prepared_at": {"type": "string", "format": "date-time"},

package/schemas/devlab-runtime.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/devlab-runtime.schema.json",
+  "title": "MotionLoom Dev Lab live runtime descriptor",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "mode", "files", "animations", "default_animation", "controls", "review_policy"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "mode": { "enum": ["sprite-sequence", "iframe"] },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/relativePath" }
+    },
+    "entrypoint": { "$ref": "#/$defs/relativePath" },
+    "default_animation": { "$ref": "#/$defs/animationId" },
+    "groups": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/group" }
+    },
+    "animations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/animation" }
+    },
+    "controls": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["play", "pause", "restart", "seek", "step", "speed", "loop"],
+      "properties": {
+        "play": { "type": "boolean" },
+        "pause": { "type": "boolean" },
+        "restart": { "type": "boolean" },
+        "seek": { "type": "boolean" },
+        "step": { "type": "boolean" },
+        "speed": { "type": "boolean" },
+        "loop": { "type": "boolean" }
+      }
+    },
+    "viewport": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "canvas_width": { "type": "number", "exclusiveMinimum": 0 },
+        "canvas_height": { "type": "number", "exclusiveMinimum": 0 },
+        "pixel_art": { "type": "boolean" },
+        "baseline_y": { "type": "number" },
+        "pivot": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["x", "y"],
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" }
+          }
+        },
+        "background": { "enum": ["checker", "dark", "light", "transparent", "project"] }
+      }
+    },
+    "review_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["require_all_animations"],
+      "properties": {
+        "require_all_animations": { "type": "boolean" }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "mode": { "const": "iframe" } } },
+      "then": { "required": ["entrypoint"] }
+    },
+    {
+      "if": { "properties": { "mode": { "const": "sprite-sequence" } } },
+      "then": {
+        "properties": {
+          "animations": {
+            "items": {
+              "required": ["id", "fps", "frames", "loop"]
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "animationId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+    },
+    "groupId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+    },
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+"
+    },
+    "group": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": { "$ref": "#/$defs/groupId" },
+        "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "order": { "type": "integer", "minimum": -10000, "maximum": 10000 }
+      }
+    },
+    "animation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "loop"],
+      "properties": {
+        "id": { "$ref": "#/$defs/animationId" },
+        "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "group": { "$ref": "#/$defs/groupId" },
+        "tags": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 64 }
+        },
+        "fps": { "type": "number", "exclusiveMinimum": 0 },
+        "frames": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/relativePath" }
+        },
+        "loop": { "type": "boolean" },
+        "duration_s": { "type": "number", "exclusiveMinimum": 0 },
+        "review_required": { "type": "boolean", "default": true },
+        "events": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/devlab-state-machine.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://motionloom.dev/schemas/devlab-state-machine.schema.json",
+  "title": "MotionLoom Dev Lab state/transition review contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "initial_state", "states", "transitions", "review_policy"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "initial_state": { "$ref": "#/$defs/id" },
+    "states": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": { "$ref": "#/$defs/state" }
+    },
+    "transitions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 512,
+      "items": { "$ref": "#/$defs/transition" }
+    },
+    "sequences": {
+      "type": "array",
+      "maxItems": 64,
+      "items": { "$ref": "#/$defs/sequence" }
+    },
+    "review_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["require_all_transitions", "require_all_sequences"],
+      "properties": {
+        "require_all_transitions": { "type": "boolean" },
+        "require_all_sequences": { "type": "boolean" }
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+    },
+    "state": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "animation"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "animation": { "$ref": "#/$defs/id" },
+        "description": { "type": "string", "maxLength": 500 }
+      }
+    },
+    "transition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "from", "to", "mode"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "from": {
+          "oneOf": [
+            { "$ref": "#/$defs/id" },
+            { "const": "*" }
+          ]
+        },
+        "to": { "$ref": "#/$defs/id" },
+        "trigger": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "mode": { "enum": ["select-animation", "runtime-trigger"] },
+        "auto_play": { "type": "boolean", "default": true },
+        "review_required": { "type": "boolean", "default": true },
+        "wait_ms": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "payload": { "type": "object" }
+      }
+    },
+    "sequenceStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["transition"],
+      "properties": {
+        "transition": { "$ref": "#/$defs/id" },
+        "wait_ms": { "type": "integer", "minimum": 0, "maximum": 10000 }
+      }
+    },
+    "sequence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "steps"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "type": "string", "maxLength": 500 },
+        "review_required": { "type": "boolean", "default": false },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": { "$ref": "#/$defs/sequenceStep" }
+        }
+      }
+    }
+  }
+}