npm - motionloom - Versions diffs - 2.5.0 → 2.6.0 - Mend

motionloom 2.5.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/AGENTS.md +2 -0
package/CHANGELOG.md +52 -1
package/README.md +20 -8
package/SECURITY.md +6 -7
package/SKILL.md +5 -3
package/agent-card.json +4 -4
package/agent-surfaces.json +1 -1
package/bin/motionloom.mjs +5 -4
package/capability-registry.json +26 -26
package/dev-lab/public/action-library.js +899 -0
package/dev-lab/public/devlab.js +722 -0
package/dev-lab/public/index.html +163 -0
package/dev-lab/public/runtime-bridge.js +109 -0
package/docs/CHECKLIST.md +15 -2
package/docs/DEV-LAB-RUNTIME.md +160 -0
package/docs/DEV-LAB-STATE-TRANSITIONS.md +121 -0
package/docs/STATUS.md +3 -3
package/docs/releases/2.5.1.md +21 -0
package/docs/releases/2.6.0.md +38 -0
package/docs/releases/npm-publish-from-workstation.md +6 -6
package/package.json +12 -4
package/requirements.txt +1 -0
package/rig-adapter-registry.json +3 -3
package/schemas/browser-review-candidate.schema.json +37 -0
package/schemas/devlab-runtime.schema.json +140 -0
package/schemas/devlab-state-machine.schema.json +103 -0
package/scripts/capture-runtime-telemetry.py +16 -8
package/scripts/devlab.py +3 -10
package/scripts/docs-audit.py +13 -1
package/scripts/package-consumer-smoke.mjs +76 -0
package/scripts/review-hook.py +255 -19
package/scripts/runtime-adapters.mjs +28 -3
package/scripts/skill-doctor.py +27 -1
package/tests/runtime-harness/index.html +24 -0
package/tests/runtime-harness/main.jsx +111 -0
package/tests/scripts/run_tests.py +41 -0

package/dev-lab/public/index.html ADDED Viewed

@@ -0,0 +1,163 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self'; frame-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'" />
+  <title>MotionLoom Dev Lab</title>
+  <style>
+    :root { color-scheme:dark; --bg:#0d0f14; --panel:#151821; --panel2:#1b1f2a; --line:#303646; --line2:#41485b; --text:#eef1f6; --muted:#929aaa; --amber:#f5a524; --good:#52d49b; --bad:#ff7070; --blue:#77a9ff; --stage:#12151c; }
+    * { box-sizing:border-box; }
+    html,body { margin:0; min-height:100%; background:var(--bg); color:var(--text); font:14px/1.45 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif; }
+    button,input,select,textarea { font:inherit; }
+    button { border:1px solid var(--line2); border-radius:7px; padding:8px 11px; color:var(--text); background:#242936; cursor:pointer; }
+    button:hover:not(:disabled) { border-color:#616a80; background:#2b3140; }
+    button:active:not(:disabled) { transform:translateY(1px); }
+    button:disabled { cursor:not-allowed; opacity:.38; }
+    button.primary { color:#1b1305; background:var(--amber); border-color:var(--amber); font-weight:800; }
+    button.danger { color:#ffe9e9; border-color:#6f363b; background:#382126; }
+    button.active { border-color:var(--amber); box-shadow:0 0 0 1px var(--amber) inset; }
+    header { height:58px; display:flex; align-items:center; justify-content:space-between; padding:0 18px; border-bottom:1px solid var(--line); background:#12151c; gap:14px; }
+    .brand { display:flex; align-items:center; gap:12px; min-width:0; }
+    .brand strong { letter-spacing:.12em; font-size:12px; text-transform:uppercase; white-space:nowrap; }
+    .mode-badge { padding:4px 8px; border:1px solid var(--line2); border-radius:999px; color:var(--muted); font:11px ui-monospace,monospace; white-space:nowrap; }
+    .mode-badge.live { color:var(--good); border-color:#286b50; background:#10291f; }
+    .mode-badge.fallback { color:var(--amber); border-color:#6d5423; background:#2b2415; }
+    .header-right { display:flex; align-items:center; gap:10px; min-width:0; }
+    #timecode { color:var(--amber); font:12px ui-monospace,monospace; white-space:nowrap; }
+    .app { display:grid; grid-template-columns:220px minmax(0,1fr) 330px; height:calc(100vh - 58px); min-height:600px; }
+    nav,aside { min-width:0; background:var(--panel); overflow:auto; }
+    nav { border-right:1px solid var(--line); padding:16px 12px; }
+    aside { border-left:1px solid var(--line); padding:18px; }
+    .eyebrow,h2 { margin:0 0 10px; color:var(--muted); font:700 11px/1.3 ui-monospace,monospace; letter-spacing:.11em; text-transform:uppercase; }
+    #animations { display:flex; flex-direction:column; gap:6px; }
+    .animation-btn { width:100%; display:grid; grid-template-columns:10px 1fr auto; align-items:center; gap:8px; text-align:left; padding:9px 9px; border-color:transparent; background:transparent; }
+    .animation-btn:hover { background:#202431; }
+    .animation-btn.selected { border-color:#655224; background:#2c2519; }
+    .animation-dot { width:7px; height:7px; border-radius:50%; background:#596173; }
+    .animation-btn.visited .animation-dot { background:var(--good); }
+    .animation-name { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    .animation-meta { color:var(--muted); font:10px ui-monospace,monospace; }
+    .workbench { min-width:0; min-height:0; display:flex; flex-direction:column; padding:14px; gap:12px; }
+    .stage-shell { min-height:0; flex:1; border:1px solid var(--line); border-radius:10px; overflow:hidden; background:#0b0d12; position:relative; }
+    .stage { width:100%; height:100%; min-height:380px; display:flex; align-items:center; justify-content:center; position:relative; overflow:hidden; background-color:var(--stage); }
+    .stage.bg-checker { background-color:#161922; background-image:linear-gradient(45deg,#20242f 25%,transparent 25%),linear-gradient(-45deg,#20242f 25%,transparent 25%),linear-gradient(45deg,transparent 75%,#20242f 75%),linear-gradient(-45deg,transparent 75%,#20242f 75%); background-size:28px 28px; background-position:0 0,0 14px,14px -14px,-14px 0; }
+    .stage.bg-dark { background:#11141b; }
+    .stage.bg-light { background:#e7e8ec; }
+    .stage.bg-transparent { background:transparent; }
+    .stage.bg-project { background:radial-gradient(circle at 50% 40%,#202638 0,#11141b 58%,#0b0d12 100%); }
+    .stage-content { position:relative; width:100%; height:100%; min-height:380px; display:flex; align-items:center; justify-content:center; transform-origin:50% 50%; }
+    #frame { max-width:92%; max-height:calc(100% - 30px); object-fit:contain; user-select:none; -webkit-user-drag:none; }
+    #frame.pixelated { image-rendering:pixelated; image-rendering:crisp-edges; }
+    #runtime-frame { width:100%; height:100%; min-height:380px; border:0; background:transparent; }
+    .stage-overlay { pointer-events:none; position:absolute; inset:0; }
+    .overlay-grid { display:none; background-image:linear-gradient(#ffffff10 1px,transparent 1px),linear-gradient(90deg,#ffffff10 1px,transparent 1px); background-size:24px 24px; }
+    .overlay-grid.on { display:block; }
+    .overlay-bounds { display:none; inset:8%; border:1px dashed #78a8ff99; }
+    .overlay-bounds.on { display:block; }
+    .overlay-baseline { display:none; left:8%; right:8%; height:1px; background:#ffb12eaa; top:75%; box-shadow:0 0 0 1px #0004; }
+    .overlay-baseline.on { display:block; }
+    .overlay-pivot { display:none; width:14px; height:14px; left:50%; top:75%; transform:translate(-50%,-50%); border:1px solid #ff7676; border-radius:50%; }
+    .overlay-pivot::before,.overlay-pivot::after { content:""; position:absolute; background:#ff7676; }
+    .overlay-pivot::before { width:20px; height:1px; left:-4px; top:6px; }
+    .overlay-pivot::after { width:1px; height:20px; left:6px; top:-4px; }
+    .overlay-pivot.on { display:block; }
+    .stage-top { position:absolute; top:10px; left:12px; right:12px; z-index:4; display:flex; align-items:flex-start; justify-content:space-between; gap:10px; pointer-events:none; }
+    .stage-label,.stage-mode { padding:5px 8px; background:#0b0e14cc; border:1px solid #303646cc; border-radius:6px; font:10px ui-monospace,monospace; letter-spacing:.07em; }
+    .stage-label { color:var(--muted); }
+    .stage-mode { color:var(--amber); text-align:right; }
+    #empty { max-width:520px; color:var(--muted); text-align:center; padding:24px; }
+    .runtime-error { position:absolute; left:14px; bottom:14px; right:14px; z-index:5; display:none; padding:10px 12px; border:1px solid #774047; background:#301c21e8; color:#ffd5d5; border-radius:7px; font:12px ui-monospace,monospace; }
+    .runtime-error.on { display:block; }
+    .transport { border:1px solid var(--line); border-radius:10px; background:var(--panel); padding:10px 12px; }
+    .transport-row { display:flex; align-items:center; gap:7px; flex-wrap:wrap; }
+    .transport-row .spacer { flex:1; }
+    .speed-select,.bg-select { color:var(--text); background:#242936; border:1px solid var(--line2); border-radius:7px; padding:7px 9px; }
+    .timeline { margin-top:10px; }
+    input[type=range] { width:100%; accent-color:var(--amber); }
+    .timeline-meta { display:flex; justify-content:space-between; gap:12px; color:var(--muted); font:11px ui-monospace,monospace; }
+    .tool-row { display:flex; gap:7px; flex-wrap:wrap; margin-top:9px; padding-top:9px; border-top:1px solid #282d39; }
+    .tool-row button,.tool-row select { font-size:12px; padding:6px 8px; }
+    .inspector-title { margin:0; font-size:22px; line-height:1.2; }
+    #description { margin:6px 0 0; color:var(--muted); }
+    .meta-grid { display:grid; grid-template-columns:1fr 1fr; gap:7px; margin-top:14px; }
+    .pill { border:1px solid var(--line); border-radius:6px; background:#11141b; padding:8px; min-width:0; }
+    .pill b { display:block; color:var(--muted); font:10px ui-monospace,monospace; letter-spacing:.06em; }
+    .pill span { display:block; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; margin-top:2px; }
+    .runtime-state { margin:0; max-height:170px; overflow:auto; padding:10px; border:1px solid var(--line); border-radius:6px; background:#0f1117; color:#b9c0ce; white-space:pre-wrap; font:11px/1.4 ui-monospace,monospace; }
+    .check { display:flex; gap:9px; padding:9px 0; border-bottom:1px solid #272c37; }
+    .check input { accent-color:var(--good); margin-top:3px; }
+    .check small { color:var(--muted); display:block; margin-top:2px; }
+    textarea { width:100%; min-height:90px; resize:vertical; color:var(--text); background:#0f1117; border:1px solid var(--line); border-radius:6px; padding:9px; }
+    .review-actions { display:flex; gap:7px; flex-wrap:wrap; margin-top:10px; }
+    #status { margin-top:10px; font:11px/1.4 ui-monospace,monospace; }
+    .ok { color:var(--good); }.warn { color:var(--bad); }.info { color:var(--blue); }
+    .progress-note { margin-top:9px; color:var(--muted); font:11px ui-monospace,monospace; }
+    @media (max-width:1050px) { .app { grid-template-columns:180px minmax(0,1fr) 285px; } }
+    @media (max-width:820px) { header { height:auto; min-height:58px; flex-wrap:wrap; padding:10px 12px; } .app { height:auto; min-height:0; grid-template-columns:1fr; } nav { border-right:0; border-bottom:1px solid var(--line); } #animations { flex-direction:row; overflow:auto; } .animation-btn { width:auto; min-width:130px; } aside { border-left:0; border-top:1px solid var(--line); } .workbench { min-height:620px; } }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="brand"><strong>MotionLoom Dev Lab</strong><span class="mode-badge" id="mode-badge">LOADING</span></div>
+    <div class="header-right"><span id="timecode">00:00.000 / 00:00.000</span><button id="fullscreen" type="button">Fullscreen</button></div>
+  </header>
+  <div class="app">
+    <nav aria-label="Animation actions">
+      <div class="eyebrow">Animations</div>
+      <div id="animations"><span id="animation-empty" class="progress-note">Loading actions…</span></div>
+      <div id="review-progress" class="progress-note"></div>
+    </nav>
+    <main class="workbench">
+      <div class="stage-shell" id="stage-shell">
+        <div class="stage bg-checker" id="stage" data-snapshot>
+          <div class="stage-top"><div class="stage-label" id="stage-label">LOADING SCENE</div><div class="stage-mode" id="stage-mode"></div></div>
+          <div class="stage-content" id="stage-content">
+            <div class="empty" id="empty">Loading exact candidate evidence…</div>
+            <img id="frame" alt="Animation frame" hidden />
+            <iframe id="runtime-frame" title="Live animation runtime" hidden></iframe>
+          </div>
+          <div class="stage-overlay overlay-grid" id="overlay-grid"></div>
+          <div class="stage-overlay overlay-bounds" id="overlay-bounds"></div>
+          <div class="stage-overlay overlay-baseline" id="overlay-baseline"></div>
+          <div class="stage-overlay overlay-pivot" id="overlay-pivot"></div>
+          <div class="runtime-error" id="runtime-error"></div>
+        </div>
+      </div>
+      <section class="transport" aria-label="Animation playback controls">
+        <div class="transport-row">
+          <button id="step-back" type="button" title="Previous frame">−1f</button>
+          <button id="play" type="button">Play</button>
+          <button id="pause" type="button">Pause</button>
+          <button id="restart" type="button">Restart</button>
+          <button id="step-forward" type="button" title="Next frame">+1f</button>
+          <button id="loop" type="button">Loop</button>
+          <select id="speed" class="speed-select" aria-label="Playback speed"><option value="0.25">0.25×</option><option value="0.5">0.5×</option><option value="1" selected>1×</option><option value="2">2×</option></select>
+          <div class="spacer"></div>
+          <span id="framecode" class="animation-meta">Frame —</span>
+        </div>
+        <div class="timeline"><input id="scrubber" type="range" min="0" max="1000" value="0" aria-label="Animation progress" /><div class="timeline-meta"><span>0%</span><span id="progress-label">0.0%</span><span>100%</span></div></div>
+        <div class="tool-row">
+          <select id="background" class="bg-select" aria-label="Stage background"><option value="checker">Checker</option><option value="dark">Dark</option><option value="light">Light</option><option value="transparent">Transparent</option><option value="project">Project</option></select>
+          <button id="grid" type="button">Grid</button><button id="bounds" type="button">Bounds</button><button id="baseline" type="button">Baseline</button><button id="pivot" type="button">Pivot</button>
+          <button id="zoom-out" type="button">−</button><button id="zoom-reset" type="button">Fit</button><button id="zoom-in" type="button">+</button><span id="zoom-label" class="animation-meta">100%</span>
+        </div>
+      </section>
+    </main>
+    <aside>
+      <h1 class="inspector-title" id="title">Scene</h1><p id="description">Loading manifest and candidate binding.</p>
+      <div class="meta-grid" id="meta"></div>
+      <h2>Runtime inspector</h2><pre class="runtime-state" id="runtime-state">Waiting for runtime…</pre>
+      <h2>Quality checklist</h2><div id="checks"></div>
+      <h2>Fix notes</h2><textarea id="notes" placeholder="Describe a precise fix request, timing issue, visual defect, or confirmation…"></textarea>
+      <div class="review-actions"><button class="danger" id="request-changes" type="button">Request changes</button><button class="primary" id="confirm" type="button">Approve candidate</button><button id="reset" type="button">Reset review</button></div>
+      <div id="status"></div>
+    </aside>
+  </div>
+  <script src="/devlab.js" defer></script>
+  <script src="/action-library.js" defer></script>
+</body>
+</html>

package/dev-lab/public/runtime-bridge.js ADDED Viewed

@@ -0,0 +1,109 @@
+(() => {
+  const REQUEST_SOURCE = "motionloom-devlab";
+  const RESPONSE_SOURCE = "motionloom-runtime";
+  let adapter = null;
+  function asAnimations(value) {
+    return Array.isArray(value) ? value.map((item) => {
+      if (typeof item === "string") return { id: item, label: item };
+      return item && typeof item === "object" ? item : null;
+    }).filter(Boolean) : [];
+  }
+  async function invoke(command, payload = {}) {
+    if (!adapter) throw new Error("MotionLoom runtime adapter is not attached");
+    if (command === "handshake") {
+      const animations = typeof adapter.listAnimations === "function"
+        ? asAnimations(await adapter.listAnimations())
+        : asAnimations(adapter.animations);
+      return {
+        ready: adapter.ready !== false,
+        runtime: adapter.runtime || "unknown",
+        framework: adapter.framework || "unknown",
+        animations,
+        capabilities: {
+          selectAnimation: typeof adapter.selectAnimation === "function",
+          transition: typeof adapter.triggerTransition === "function",
+          play: typeof adapter.play === "function",
+          pause: typeof adapter.pause === "function",
+          restart: typeof adapter.restart === "function" || typeof adapter.seek === "function" || typeof adapter.setProgress === "function",
+          seek: typeof adapter.seek === "function" || typeof adapter.setProgress === "function",
+          step: typeof adapter.stepFrames === "function",
+          speed: typeof adapter.setSpeed === "function",
+          loop: typeof adapter.setLoop === "function",
+          state: typeof adapter.getState === "function"
+        },
+        state: typeof adapter.getState === "function" ? await adapter.getState() : {}
+      };
+    }
+    if (command === "listAnimations") {
+      return typeof adapter.listAnimations === "function"
+        ? asAnimations(await adapter.listAnimations())
+        : asAnimations(adapter.animations);
+    }
+    if (command === "selectAnimation") {
+      if (typeof adapter.selectAnimation !== "function") throw new Error("selectAnimation is not supported");
+      return adapter.selectAnimation(payload.id);
+    }
+    if (command === "triggerTransition") {
+      if (typeof adapter.triggerTransition !== "function") throw new Error("triggerTransition is not supported");
+      return adapter.triggerTransition({
+        id: payload.id,
+        from: payload.from,
+        to: payload.to,
+        trigger: payload.trigger,
+        payload: payload.payload && typeof payload.payload === "object" ? payload.payload : {}
+      });
+    }
+    if (command === "play" || command === "pause" || command === "setSpeed" || command === "setLoop" || command === "stepFrames") {
+      const method = command;
+      if (typeof adapter[method] !== "function") throw new Error(`${command} is not supported`);
+      if (command === "setSpeed") return adapter[method](payload.rate);
+      if (command === "setLoop") return adapter[method](Boolean(payload.enabled));
+      if (command === "stepFrames") return adapter[method](Number(payload.delta || 0));
+      return adapter[method]();
+    }
+    if (command === "restart") {
+      if (typeof adapter.restart === "function") return adapter.restart();
+      if (typeof adapter.seek === "function") return adapter.seek(0);
+      if (typeof adapter.setProgress === "function") return adapter.setProgress(0);
+      throw new Error("restart is not supported");
+    }
+    if (command === "seek") {
+      const progress = Math.max(0, Math.min(1, Number(payload.progress || 0)));
+      if (typeof adapter.seek === "function") return adapter.seek(progress);
+      if (typeof adapter.setProgress === "function") return adapter.setProgress(progress);
+      throw new Error("seek is not supported");
+    }
+    if (command === "getState") {
+      return typeof adapter.getState === "function" ? adapter.getState() : {};
+    }
+    throw new Error(`Unknown MotionLoom runtime command: ${command}`);
+  }
+  window.addEventListener("message", async (event) => {
+    const data = event.data;
+    if (!data || data.source !== REQUEST_SOURCE || !data.id || typeof data.command !== "string") return;
+    try {
+      const result = await invoke(data.command, data.payload || {});
+      event.source?.postMessage({ source: RESPONSE_SOURCE, id: data.id, ok: true, result }, "*");
+    } catch (error) {
+      event.source?.postMessage({
+        source: RESPONSE_SOURCE,
+        id: data.id,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error)
+      }, "*");
+    }
+  });
+  window.MotionLoomRuntimeBridge = {
+    attach(nextAdapter) {
+      if (!nextAdapter || typeof nextAdapter !== "object") throw new Error("A runtime adapter object is required");
+      adapter = nextAdapter;
+      window.parent?.postMessage({ source: RESPONSE_SOURCE, event: "attached" }, "*");
+      return nextAdapter;
+    },
+    detach() { adapter = null; }
+  };
+})();

package/docs/CHECKLIST.md CHANGED Viewed

@@ -8,6 +8,19 @@ A scene is only ready for the confirm-into-PR step when every item below passes.
 - [ ] Bone rotations follow parent-first order; no child rotates before its parent (body rigs).
 - [ ] No frame pops at loop seam — first and last frames are visually continuous (looping scenes).
+## Interactive Dev Lab runtime
+- [ ] Any candidate with runnable animation/action data exposes `src/output/<scene>/devlab-runtime.json` using `schemas/devlab-runtime.schema.json`; captured PNG checkpoints are fallback evidence, not a substitute for an available live runtime.
+- [ ] Every reviewable action/clip declared by the candidate (for example idle, walk, run, attack, state-machine animation, marker segment or project-specific action) is discoverable in Dev Lab without hard-coded action names.
+- [ ] The live candidate supports every control it declares: select action, play, pause, restart, normalized seek/scrub, frame step where meaningful, playback speed and loop. Unsupported controls are disabled and never simulated as a passing runtime feature.
+- [ ] Sprite-sequence playback renders the exact declared frame bytes; iframe runtimes expose the `runtime-bridge.js` controller and report current animation/time/progress/frame state where the runtime can provide it.
+- [ ] The stage is usable for visual inspection: selectable background, zoom/fit, fullscreen and optional grid/bounds/baseline/pivot overlays are available without altering candidate bytes.
+- [ ] `scripts/review-hook.py` hash-binds `devlab-runtime.json` plus every declared runtime file into the browser candidate. Path traversal, symlinked runtime files, missing files, duplicate action IDs and runtime byte drift fail closed.
+- [ ] If a hash-bound live runtime fails to load, Dev Lab says `LIVE RUNTIME UNAVAILABLE`, may show captured evidence for diagnosis, and blocks approval. It must never relabel snapshot fallback as live runtime.
+- [ ] When `review_policy.require_all_animations` is true, the user must inspect every `review_required` action before approval; a change request remains available at any time.
+- [ ] Deterministic snapshot capture drives the same `window.__lab.selectAnimation()` / `window.__lab.seek()` controller used by interactive review for live candidates.
+See [`DEV-LAB-RUNTIME.md`](DEV-LAB-RUNTIME.md) for the descriptor and runtime bridge contracts.
 ## Brand binding
 - [ ] Primary/accent colors come from `project-context.json` (or an explicit user override recorded in the spec).
 - [ ] Theme slots are used for every user-tunable color, never hardcoded hex inside the animation payload.
@@ -39,14 +52,14 @@ A scene is only ready for the confirm-into-PR step when every item below passes.
 - [ ] Every Agent/internal-skill/provider output used by the scene has a hash-bound generation receipt, control track and export manifest; no receipt stores secrets or self-asserts approval.
 - [ ] The selected artifact adapter is declared in `artifact-adapter-registry.json`; `scaffold` or `static-validated` status is not presented as runtime verification or production eligibility.
 - [ ] `runtime-candidate.json` binds the intake bundle to the matching asset identity, action-set and frame geometry/atlas/map contracts; mismatched refs or hashes block the candidate.
-- [ ] A rigmed or motion-capture candidate declares skeleton, sockets, action/event coverage, export target and adapter evidence in `rig-compatibility.json`.
+- [ ] A rigged or motion-capture candidate declares skeleton, sockets, action/event coverage, export target and adapter evidence in `rig-compatibility.json`.
 - [ ] Artifact Intake, runtime candidate and rig findings are present in the task handoff/Dev Lab rail and visibly retain `review_required` until the user records a decision.
 ## PR readiness
 - [ ] Snapshot PNGs exist for 0/50/100%.
 - [ ] `visual-truth.json` binds real baseline/candidate frames to source, manifest and available runtime/Motion IR hashes; `approval` remains `false`.
 - [ ] `motion-spec.json` is bound to the exact `project-context.json` hash (implements == planned).
-- [ ] Dev Lab URL tested on mobile viewport and desktop.
+- [ ] Dev Lab URL tested on mobile viewport and desktop, including live transport controls when `devlab-runtime.json` is present.
 - [ ] The production provenance check passes with `--mode production` and reports `production_eligible: true`.
 - [ ] If `manifest.json` declares `consistency_ref`, `quality-gate.py --require-asset-consistency` passes for its declared `consistency_kind`.
 - [ ] If `manifest.json` declares an Artifact Intake bundle, `quality-gate.py --require-artifact-intake` passes and the selected adapter/runtime evidence meets the requested mode.

package/docs/DEV-LAB-RUNTIME.md ADDED Viewed

@@ -0,0 +1,160 @@
+# Dev Lab live runtime contract
+Dev Lab is the human review surface for the exact MotionLoom candidate. Static 0/50/100 snapshots remain deterministic evidence, but they are not an interactive runtime. A scene that can expose live playback SHOULD add `devlab-runtime.json` beside `manifest.json` and `motion-spec.json`.
+The descriptor is scene-local and hash-bound by `scripts/review-hook.py`. Every path in `files`, `entrypoint`, and `animations[].frames` must be a relative path inside the scene directory. Path traversal, absolute paths, symlinked files, missing files, duplicate animation ids, or references outside `files` fail closed. The browser candidate records the resulting runtime bundle SHA-256; changing any declared runtime byte invalidates that candidate.
+## Sprite sequence example
+```json
+{
+  "schema_version": "1.0",
+  "mode": "sprite-sequence",
+  "files": [
+    "sprites/idle-00.png",
+    "sprites/idle-01.png",
+    "sprites/walk-00.png",
+    "sprites/walk-01.png"
+  ],
+  "default_animation": "idle",
+  "groups": [
+    { "id": "locomotion", "label": "Locomotion", "order": 10 },
+    { "id": "combat", "label": "Combat", "order": 20 }
+  ],
+  "animations": [
+    {
+      "id": "idle",
+      "label": "Idle",
+      "group": "locomotion",
+      "tags": ["stance", "loop"],
+      "fps": 8,
+      "frames": ["sprites/idle-00.png", "sprites/idle-01.png"],
+      "loop": true,
+      "review_required": true
+    },
+    {
+      "id": "walk",
+      "label": "Walk",
+      "group": "locomotion",
+      "tags": ["movement", "grounded"],
+      "fps": 12,
+      "frames": ["sprites/walk-00.png", "sprites/walk-01.png"],
+      "loop": true,
+      "review_required": true
+    }
+  ],
+  "controls": {
+    "play": true,
+    "pause": true,
+    "restart": true,
+    "seek": true,
+    "step": true,
+    "speed": true,
+    "loop": true
+  },
+  "viewport": {
+    "canvas_width": 1920,
+    "canvas_height": 1920,
+    "pixel_art": true,
+    "baseline_y": 1626,
+    "pivot": { "x": 940, "y": 1626 },
+    "background": "checker"
+  },
+  "review_policy": { "require_all_animations": true }
+}
+```
+Dev Lab renders the declared frame bytes directly and drives them with a real clock. Play, pause, restart, scrub, frame-step, loop and speed therefore operate on the same candidate frames that are being reviewed. Action names such as `idle`, `walk`, `run`, `attack`, `hurt` or project-specific clips are data, not hard-coded UI.
+## Large action libraries
+`animations` has no product-level fixed action vocabulary. A consumer can add `jump`, `dash`, `parry`, `skill-fireball`, `teleport-strike`, emotes, cinematic clips, state-machine entries, or any other valid action id and Dev Lab will expose it automatically.
+For larger character or UI sets, use optional `groups` plus `animations[].group` and `animations[].tags`. Dev Lab turns those fields into an Action Library with search, group chips, collapsible group sections, and filters for review-required, unreviewed, looping, and one-shot actions. Group metadata changes presentation only; it does not grant runtime capability or approval.
+Examples of useful project-defined groups are `locomotion`, `combat`, `skills`, `reactions`, `emotes`, or domain-specific categories. These names are not reserved by MotionLoom. Actions without a declared group remain visible under `Other` rather than being dropped.
+Search matches action id, label, group label, tags, and declared events. Filtering never weakens the review gate: hidden required actions still count as unreviewed until the user actually selects them. The selected action remains visible in the `Unreviewed` filter so the reviewer does not lose the current runtime context immediately after opening it.
+## Iframe runtime example
+Use `mode: "iframe"` when the candidate already has a browser runtime (for example Rive, Lottie, GSAP, Framer Motion, Three.js or a project-specific player). The descriptor adds an `entrypoint`, and that entrypoint exposes a controller through `runtime-bridge.js`:
+```html
+<script src="/runtime-bridge.js"></script>
+<script type="module">
+  const adapter = {
+    runtime: "example-player@1",
+    framework: "custom",
+    animations: [{ id: "idle", label: "Idle", loop: true }],
+    listAnimations() { return this.animations; },
+    selectAnimation(id) { /* select exact clip */ },
+    play() { /* play */ },
+    pause() { /* pause */ },
+    restart() { /* restart */ },
+    seek(progress) { /* normalized 0..1 */ },
+    stepFrames(delta) { /* optional */ },
+    setSpeed(rate) { /* optional */ },
+    setLoop(enabled) { /* optional */ },
+    triggerTransition(request) { /* optional: drive a real runtime state transition */ },
+    getState() { return { progress: 0, currentTime: 0, duration: 1, frame: 0, totalFrames: 60, state: "idle" }; }
+  };
+  MotionLoomRuntimeBridge.attach(adapter);
+</script>
+```
+The parent Dev Lab communicates by `postMessage`; the runtime never grants approval. If the live runtime cannot load or a declared control is unavailable, Dev Lab disables that control and shows an explicit live-runtime failure/fallback state. It must not relabel captured PNG evidence as live runtime.
+## State and transition review
+A candidate may additionally declare `devlab-state-machine.json` when the reviewer needs to test behavior across clips instead of inspecting each action in isolation. The state-machine file only participates in the candidate runtime hash when it is explicitly listed in `devlab-runtime.json.files`; undeclared state-machine bytes are not accepted as review evidence.
+A minimal portable contract can use `select-animation` transitions:
+```json
+{
+  "schema_version": "1.0",
+  "initial_state": "idle",
+  "states": [
+    { "id": "idle", "label": "Idle", "animation": "idle" },
+    { "id": "run", "label": "Run", "animation": "run" },
+    { "id": "attack", "label": "Attack", "animation": "attack" },
+    { "id": "hurt", "label": "Hurt", "animation": "hurt" }
+  ],
+  "transitions": [
+    { "id": "idle-run", "from": "idle", "to": "run", "mode": "select-animation", "review_required": true },
+    { "id": "run-attack", "from": "run", "to": "attack", "mode": "select-animation", "review_required": true },
+    { "id": "attack-hurt", "from": "attack", "to": "hurt", "mode": "select-animation", "review_required": true },
+    { "id": "hurt-idle", "from": "hurt", "to": "idle", "mode": "select-animation", "review_required": true }
+  ],
+  "sequences": [
+    {
+      "id": "combat-roundtrip",
+      "label": "Combat roundtrip",
+      "review_required": true,
+      "steps": [
+        { "transition": "idle-run", "wait_ms": 150 },
+        { "transition": "run-attack", "wait_ms": 150 },
+        { "transition": "attack-hurt", "wait_ms": 150 },
+        { "transition": "hurt-idle", "wait_ms": 150 }
+      ]
+    }
+  ],
+  "review_policy": {
+    "require_all_transitions": true,
+    "require_all_sequences": true
+  }
+}
+```
+`select-animation` is the portable lane for sprite/clip runtimes: the transition selects the target state's declared animation and may auto-play it. `runtime-trigger` is stricter and is intended for a real state machine such as a Rive state machine or a project-specific runtime. For that mode the iframe adapter must implement `triggerTransition(request)`. Dev Lab sends the declared trigger/payload and only counts the transition as inspected after the runtime reports the target state through `getState()`. It never silently downgrades a failed or unsupported `runtime-trigger` transition into a clip switch.
+The State/Transition Tester shows the current state, legal outgoing transitions, required transition coverage, declared review sequences and transition history. Review sequences execute their declared transition steps with bounded waits and may be stopped or reset by the reviewer. They are review helpers, not autonomous approval mechanisms.
+## Review semantics
+Dev Lab records which actions the reviewer actually selected. When `review_policy.require_all_animations` is true, approval is disabled until every `review_required` action has been inspected. When a state-machine contract is present, its `review_policy` can independently require all review-required transitions and review-required sequences before approval is enabled. A user may still request changes at any time.
+Review evidence records action, transition and sequence coverage plus runtime/state history. Playback success, transition success, runtime readiness, hashes, snapshots, telemetry and automated checks remain evidence only; `approved` is always an explicit user review decision.
+The deterministic snapshot harness continues to use `window.__lab.selectAnimation()` and `window.__lab.seek()`. For live candidates those calls drive the same runtime controller shown to the user; for legacy scenes without `devlab-runtime.json`, Dev Lab clearly enters `captured-evidence` mode and retains the older checkpoint viewer as a compatibility fallback.

package/docs/DEV-LAB-STATE-TRANSITIONS.md ADDED Viewed

@@ -0,0 +1,121 @@
+# Dev Lab state/transition tester
+MotionLoom Dev Lab can review more than isolated animation clips. A live candidate may also expose a state/transition contract so a reviewer can exercise flows such as `Idle -> Run -> Attack -> Hurt -> Idle` against the same candidate runtime.
+The state-machine contract is optional. When used, place `devlab-state-machine.json` beside `devlab-runtime.json` and list `devlab-state-machine.json` in the runtime descriptor's `files` array. This is mandatory: the state-machine bytes must participate in the candidate runtime bundle hash. Dev Lab ignores unbound state-machine data and blocks approval if a hash-bound state-machine contract is invalid.
+The schema is `schemas/devlab-state-machine.schema.json`.
+## Example
+```json
+{
+  "schema_version": "1.0",
+  "initial_state": "idle",
+  "states": [
+    { "id": "idle", "label": "Idle", "animation": "idle" },
+    { "id": "run", "label": "Run", "animation": "run" },
+    { "id": "attack", "label": "Attack", "animation": "attack" },
+    { "id": "hurt", "label": "Hurt", "animation": "hurt" }
+  ],
+  "transitions": [
+    {
+      "id": "start-run",
+      "label": "Start running",
+      "from": "idle",
+      "to": "run",
+      "trigger": "move",
+      "mode": "select-animation",
+      "auto_play": true,
+      "review_required": true
+    },
+    {
+      "id": "attack",
+      "from": "run",
+      "to": "attack",
+      "trigger": "attack",
+      "mode": "select-animation",
+      "auto_play": true,
+      "review_required": true
+    },
+    {
+      "id": "take-hit",
+      "from": "attack",
+      "to": "hurt",
+      "trigger": "hit",
+      "mode": "select-animation",
+      "auto_play": true,
+      "review_required": true
+    },
+    {
+      "id": "recover",
+      "from": "hurt",
+      "to": "idle",
+      "trigger": "recover",
+      "mode": "select-animation",
+      "auto_play": true,
+      "review_required": true
+    }
+  ],
+  "sequences": [
+    {
+      "id": "combat-cycle",
+      "label": "Combat cycle",
+      "review_required": true,
+      "steps": [
+        { "transition": "start-run", "wait_ms": 250 },
+        { "transition": "attack", "wait_ms": 450 },
+        { "transition": "take-hit", "wait_ms": 300 },
+        { "transition": "recover", "wait_ms": 200 }
+      ]
+    }
+  ],
+  "review_policy": {
+    "require_all_transitions": true,
+    "require_all_sequences": false
+  }
+}
+```
+## Transition modes
+`select-animation` is the portable mode. Dev Lab changes to the target state's declared animation through the existing live runtime controller and optionally starts playback. It is appropriate for sprite-sequence candidates and simple clip-oriented runtimes. This mode does not claim that a blend tree or engine state machine was exercised.
+`runtime-trigger` is for runtimes that own real state-machine behavior, such as a Rive state machine, a game-runtime adapter, or another project-specific player. The iframe adapter must expose `triggerTransition(request)` through `runtime-bridge.js` and `getState()` must expose an observable `state`/`currentState` or an animation that maps to a declared state. Dev Lab sends the exact transition request and verifies that the target state becomes observable before counting the transition as inspected. It never silently downgrades a `runtime-trigger` transition to a clip switch.
+Example adapter:
+```js
+MotionLoomRuntimeBridge.attach({
+  runtime: "game-preview@1",
+  framework: "custom",
+  animations: [
+    { id: "idle", label: "Idle", loop: true },
+    { id: "run", label: "Run", loop: true },
+    { id: "attack", label: "Attack", loop: false }
+  ],
+  triggerTransition(request) {
+    // Dispatch the real trigger/input into the runtime state machine.
+    // request: { id, from, to, trigger, payload }
+  },
+  getState() {
+    return {
+      state: "idle",
+      animation: "idle",
+      progress: 0,
+      currentTime: 0,
+      duration: 1
+    };
+  }
+});
+```
+## Review behavior
+The State Machine panel follows the runtime's current state, shows only transitions that are legal from that state (plus wildcard transitions), and records successful transition observations. Review sequences execute declared transitions in order; each wait is explicit and bounded.
+If `review_policy.require_all_transitions` is true, every transition with `review_required != false` must be exercised before Dev Lab allows approval. `require_all_sequences` applies the same rule to review-required sequences. Search/filtering in the Action Library cannot bypass these requirements.
+A transition is counted only after its command succeeds and the target state is observable. Unsupported runtime-trigger transitions remain disabled. A reviewer can always request changes without completing transition coverage.
+Transition execution, state observability, sequence completion, runtime hashes, snapshots, and automated smoke tests are evidence only. None of them grant `production_approved`, runtime approval, or visual approval. The final approval remains an explicit user action.

package/docs/STATUS.md CHANGED Viewed

@@ -4,7 +4,7 @@
 ## Current release posture
-MotionLoom's repository source and package manifest are prepared for **2.4.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 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 highest-value remaining evidence work is paired product evaluation across more real projects and verification of the 2.4.0 version–tag–GitHub Release–npm provenance chain. 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.