motionloom 2.5.1 → 2.6.1

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.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 an interactive browser-based Dev Lab review workbench. Dev Lab supports hash-bound live playback, arbitrary project-defined action libraries and optional state/transition review flows; generated frame sequences additionally use a machine-readable Frame Generation Lock plus fail-closed measured preflight so isolated source geometry is controlled before and after generation. 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, 2.6.0 added the richer Dev Lab review surface, and 2.6.1 adds proactive machine-readable frame-generation geometry control without weakening the human approval boundary. The highest-value next evidence work is consumer-project review of real action sets, transitions and generated frame sequences, 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/docs/releases/2.6.1.md

@@ -0,0 +1,57 @@
+# MotionLoom 2.6.1
+
+MotionLoom 2.6.1 closes the generated multi-frame consistency gap discovered during real Codex animation work. The release makes frame consistency proactive: the Agent binds one accepted identity/reference into a machine-readable Frame Generation Lock before producing later poses, then validates the real PNG bytes after every generated frame before any atlas is packed.
+
+## What changed
+
+### Frame Generation Lock before generation
+
+Generated frame sequences now have a provider-neutral contract in `schemas/frame-generation-lock.schema.json`. The lock records and verifies:
+
+- accepted identity/reference path and SHA-256;
+- exact canvas dimensions, alpha mode and color space;
+- camera/orientation and apparent character scale;
+- pivot and baseline/footline;
+- safe rectangle, transparent padding and geometry tolerances;
+- ordered frame ids, pose intent and one unique isolated output path per frame.
+
+Agents use `motionloom frame-generation-lock validate` before generation and `motionloom frame-generation-lock compose` (or `compose-all`) to build each provider-facing pose instruction from the same lock. This removes dependence on an Agent remembering or rewriting the geometry prose consistently across frame 2, frame 6 or frame 20.
+
+### Strict preflight after each generated frame
+
+`motionloom frame-set-preflight` is now a public CLI command. It re-measures actual PNG bytes and blocks shared/non-isolated source canvases, stale hashes, contamination, guard-band violations, pivot/footline drift and apparent-size drift beyond the declared tolerance.
+
+The default source policy is deliberately strict: generate one isolated source PNG per frame, validate it, and only then continue. For long actions (including six or more frames), a generated contact sheet or multi-pose sheet must not be cropped into production source frames. Atlas/sprite-sheet packing happens only after all isolated source frames pass.
+
+## Agent behavior
+
+`AGENTS.md` and the canonical Skill route Codex and other compatible Agents through this workflow automatically. The user does not need to remember to ask for equal scale, separate frames, padding, baseline consistency or pose-sheet avoidance.
+
+If one frame fails, the Agent regenerates or repairs that frame under the same lock. It must not silently resize previously accepted frames or weaken tolerances merely to make the set pass.
+
+## Verification
+
+PR #18 passed:
+
+- the dedicated Frame Generation Lock workflow;
+- MotionLoom Quality (including engine tests and cross-platform package checks);
+- Security Analysis / CodeQL;
+- Documentation and Package Hygiene.
+
+The dedicated regression suite covers stale reference hashes, duplicate outputs, pose-sheet policy, path escape, post-generation resize, public CLI composition and strict preflight.
+
+## Trust boundary
+
+This release improves source consistency and evidence quality; it does not change authority. A generator prompt, reference hash, frame lock, preflight pass, atlas pass, runtime render or signed evidence record does **not** create artist authorship, licence authority, production eligibility, production approval or user approval. Human review remains a separate bounded decision.
+
+## Updating a project
+
+After `motionloom@2.6.1` is published, update the project-local development dependency and refresh the managed Agent surface:
+
+```bash
+npm install --save-dev motionloom@2.6.1
+npx --no-install motionloom repair --yes
+npx --no-install motionloom status --json
+```
+
+For a generated multi-frame task, the Agent should then use the Frame Generation Lock before later frames and `frame-set-preflight` after each accepted frame.

package/examples/agent-consumer/frame-generation-lock/hero-walk-lock.json

@@ -0,0 +1,84 @@
+{
+  "schema_version": "0.1",
+  "lock_id": "hero-walk-v1",
+  "asset_identity": "character/hero-male",
+  "action_id": "walk",
+  "reference": {
+    "image": "asset-consistency/assets/hero-frame-00.png",
+    "sha256": "75ce90653a01a23bcfab1aef83647d6364d3edbf6e4a44b84c635338c12b9248",
+    "role": "accepted_frame_anchor"
+  },
+  "canvas": {
+    "width": 8,
+    "height": 8,
+    "color_space": "srgb",
+    "alpha_mode": "straight"
+  },
+  "geometry": {
+    "center_x": 4,
+    "pivot": { "x": 4, "y": 7, "space": "pixels" },
+    "footline_px": 6,
+    "safe_rect": { "x": 1, "y": 0, "width": 6, "height": 7 },
+    "min_padding_px": 1,
+    "target_alpha_bbox": { "width": 4, "height": 5 },
+    "tolerances": {
+      "pivot_px": 0.01,
+      "footline_px": 0.01,
+      "bbox_width_px": 0,
+      "bbox_height_px": 0
+    }
+  },
+  "appearance": {
+    "preserve": [
+      "same character identity and silhouette",
+      "same camera and left-to-right orientation",
+      "same palette, outline weight and apparent scale"
+    ],
+    "forbid": [
+      "second character or neighboring pose",
+      "background, shadow, text, prop or crop",
+      "camera change, mirror, recolor or post-generation resize"
+    ],
+    "pixel_art": {
+      "enabled": true,
+      "nearest_neighbor_only": true
+    }
+  },
+  "source_policy": {
+    "isolated_frames": true,
+    "max_frames_per_image": 1,
+    "allow_pose_sheet": false,
+    "allow_post_resize": false,
+    "reuse_reference": true
+  },
+  "frames": [
+    {
+      "frame_id": "walk.00",
+      "pose": "Contact-right: right foot forward on the shared footline, left leg trailing, natural counter-swing.",
+      "output": "frame-generation-lock/generated/hero-walk-00.png"
+    },
+    {
+      "frame_id": "walk.01",
+      "pose": "Passing: one leg passes beneath the upright body with compact stride and natural counter-swing.",
+      "output": "frame-generation-lock/generated/hero-walk-01.png"
+    },
+    {
+      "frame_id": "walk.02",
+      "pose": "Contact-left: left foot forward on the shared footline, right leg trailing, natural counter-swing.",
+      "output": "frame-generation-lock/generated/hero-walk-02.png"
+    },
+    {
+      "frame_id": "walk.03",
+      "pose": "Passing complement: opposite leg passes beneath the upright body; preserve the same body scale and baseline.",
+      "output": "frame-generation-lock/generated/hero-walk-03.png"
+    }
+  ],
+  "postflight": {
+    "frame_geometry": "asset-consistency/hero-walk-frame-geometry.json"
+  },
+  "trust": {
+    "authority": "ai_generated",
+    "review_only": true,
+    "approval": false
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionloom",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "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",
@@ -74,11 +76,11 @@
     "scripts/rive-package-gate.py",
     "schemas/rive-package-manifest.schema.json",
     "examples/agent-consumer/rive-package-gate",
-    "tests/scripts/test_rive_package_gate.py"
-    ,"scripts/build-ai-pilot.py"
-    ,"scripts/isolate-alpha-background.py"
-    ,"tests/scripts/test_ai_pilot_builder.py"
-    ,"tests/scripts/test_alpha_isolation.py"
+    "tests/scripts/test_rive_package_gate.py",
+    "scripts/build-ai-pilot.py",
+    "scripts/isolate-alpha-background.py",
+    "tests/scripts/test_ai_pilot_builder.py",
+    "tests/scripts/test_alpha_isolation.py"
   ],
   "keywords": [
     "animation",
@@ -182,9 +184,9 @@
     "artifact:intake": "node bin/motionloom.mjs artifact-intake intake --root . --registry artifact-adapter-registry.json --receipt examples/agent-consumer/artifact-intake/hero-motion-receipt.json --controls examples/agent-consumer/artifact-intake/hero-motion-controls.json --export-manifest examples/agent-consumer/artifact-intake/hero-motion-export.json --json",
     "runtime:candidate": "node bin/motionloom.mjs runtime-candidate validate --root . --input examples/agent-consumer/runtime-candidate/hero-walk-candidate.json --json",
     "rig:compatibility": "node bin/motionloom.mjs rig-compatibility validate --root . --registry rig-adapter-registry.json --input examples/agent-consumer/rig-compatibility/hero-walk-fixture-rig.json --json",
-    "rive:gate": "node bin/motionloom.mjs rive-package-gate --help"
-    ,"pilot:build": "node bin/motionloom.mjs pilot-build --help"
-    ,"alpha:isolate": "node bin/motionloom.mjs alpha-isolate --help"
+    "rive:gate": "node bin/motionloom.mjs rive-package-gate --help",
+    "pilot:build": "node bin/motionloom.mjs pilot-build --help",
+    "alpha:isolate": "node bin/motionloom.mjs alpha-isolate --help"
   },
   "dependencies": {
     "@lottiefiles/dotlottie-web": "^0.79.0",

package/references/multi-frame-asset-generation.md

@@ -0,0 +1,109 @@
+# Multi-frame asset generation discipline
+
+This contract applies whenever MotionLoom or an Agent creates two or more source frames for the same character, object, effect or other frame-based animation. It is automatic: the user should not have to ask for consistent frame geometry, isolated source frames or atlas hygiene.
+
+## Default source policy
+
+Generated source frames are **isolated-frame assets**, not a pose sheet.
+
+- Generate exactly one animation source frame per image/canvas by default.
+- For long actions (including actions with six or more frames), never ask an image generator for one contact sheet, sprite sheet or multi-pose canvas and then crop the poses out as production source frames.
+- Do not pack an atlas or sprite sheet until every isolated source frame has passed identity and frame-geometry validation.
+- Imported third-party atlases may still use the atlas contract; this rule is about Agent-generated source material.
+
+If a generator cannot preserve isolated source canvases reliably, regenerate in smaller isolated calls or use provider outputs that are already separate files. Do not convert one contaminated multi-pose canvas into accepted source frames merely because crops can be extracted from it.
+
+This avoids neighboring poses leaking into a crop, shared-canvas bleed, accidental partial limbs from adjacent frames and ambiguous ownership of opaque pixels.
+
+## Lock geometry before the second frame
+
+Before generating frame 2, establish one canonical geometry lock from the accepted identity/reference frame and keep it unchanged for the rest of the action:
+
+- exact canvas width and height;
+- transparent alpha mode and color space;
+- camera and left/right orientation;
+- target apparent character scale;
+- pivot point;
+- baseline / footline;
+- safe rectangle and transparent guard band;
+- palette/style/identity reference;
+- frame naming and action order.
+
+Create or update the matching `action-set` and `frame-geometry` contracts before continuing the sequence. The first accepted frame is the geometry anchor; later poses may move limbs, but they must not silently change canvas size, camera, character scale, pivot or baseline.
+
+For AI-generated frames, every subsequent generation request should carry the same locked identity reference and geometry requirements. When the image tool can accept an image reference, reuse the accepted identity/anchor frame rather than relying on prose alone.
+
+## Frame Generation Lock
+
+Do not rely on the Agent remembering the same geometry prose across many provider calls. Persist the generation-side constraints in `frame-generation-lock.json` using `schemas/frame-generation-lock.schema.json`.
+
+The lock binds:
+
+- the exact identity/accepted-frame reference path and SHA-256;
+- canvas dimensions, color space and alpha mode;
+- center, pivot, footline, safe rectangle and minimum transparent padding;
+- target measured alpha-bounds plus permitted width/height drift;
+- appearance features that must be preserved and changes that are forbidden;
+- a hard source policy of one isolated frame per image, no pose sheet and no post-generation resize;
+- every `frame_id`, its pose intent and its unique PNG output path;
+- the post-generation `frame-geometry` contract used by deterministic preflight;
+- a review-only trust boundary with `approval: false`.
+
+Before a provider call, validate the lock and compose the exact frame instruction from it:
+
+```bash
+motionloom frame-generation-lock validate \
+  --input src/output/<scene>/<action>-frame-generation-lock.json \
+  --root src/output/<scene> --json
+
+motionloom frame-generation-lock compose \
+  --input src/output/<scene>/<action>-frame-generation-lock.json \
+  --root src/output/<scene> --frame-id <action.frame-id> --json
+```
+
+For batch planning, `compose-all` emits one independent instruction per frame while preserving the same lock hash and reference hash. It does **not** authorize asking a provider for one multi-frame canvas; each returned instruction still represents one isolated source image.
+
+If the reference bytes change, an output path escapes the asset root, two frames target the same PNG, the lock permits a pose sheet/post-resize, or the trust boundary is weakened, validation fails closed before generation.
+
+## Validate incrementally
+
+Do not generate the complete action and only inspect it at the end. After each candidate frame:
+
+1. verify the image is an isolated source canvas rather than a shared pose sheet;
+2. verify exact canvas dimensions and alpha transparency;
+3. measure the real alpha bounding box from pixels;
+4. compare apparent size against the anchor within the declared `bbox_drift_tolerance_px`;
+5. verify pivot and footline tolerance;
+6. verify the alpha bounding box remains inside `safe_rect` with the declared `bleed_margin_px` guard band;
+7. reject unexpected opaque contamination;
+8. only then accept the frame and continue.
+
+Use:
+
+```bash
+motionloom frame-set-preflight \
+  --input src/output/<scene>/<action>-frame-geometry.json \
+  --root src/output/<scene> --json
+```
+
+The preflight is intentionally stricter than a visual warning: shared source images, non-isolated frame rectangles, scale drift beyond the declared tolerance, guard-band violations, pivot/footline drift, hash mismatch or other deterministic frame-geometry failures block the sequence.
+
+If one frame fails, regenerate or repair **that frame only** using the same generation lock. Do not silently rescale every previously accepted frame to match a bad frame, and do not weaken tolerances merely to make the set pass.
+
+## Apparent-size consistency
+
+Equal canvas dimensions are not enough. A 1920 × 1920 PNG can still contain a character that is 20% smaller than the previous frame. MotionLoom therefore treats measured alpha-bounds drift as a real source defect when it exceeds the declared tolerance.
+
+Pose motion can legitimately change the bounding box, so choose a tolerance that allows expected limb extension while preventing whole-character zoom drift. For actions with large reaches, jumps or weapons, lock the body pivot/footline and define a safe rectangle large enough for those poses instead of changing the character scale between frames.
+
+For pixel art, any intentional normalization step must preserve nearest-neighbor pixel density and the locked pivot/baseline. Large scale corrections should trigger regeneration rather than interpolation.
+
+## Packing happens last
+
+Only after every source frame passes preflight may the Agent build a sprite sheet or atlas. The packed result must then pass the atlas contract: no region overlap, no opaque pixels outside declared regions when required, explicit padding/extrusion, and no ambiguous neighboring-frame bleed.
+
+Source-frame acceptance and atlas acceptance are separate gates. A clean atlas cannot repair inconsistent source-frame scale, and consistent source frames do not prove the packed atlas is clean.
+
+## Agent decision rule
+
+When the user asks for an animation such as idle, walk, run, attack, hurt, jump or any project-defined multi-frame action, the Agent should apply this contract automatically. Do not ask the user whether they want frame consistency checks or a generation lock; they are part of the default MotionLoom workflow. Only ask the user when a genuine artistic decision is required, such as choosing between materially different silhouettes or motion intent.

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" } }
+      }
+    }
+  }
+}