design-playbook 0.13.0 → 0.14.0

package/codex/AGENTS.md

@@ -36,10 +36,14 @@ python packages/design-playbook/codex/install_skills.py --force
 #   @packages/design-playbook/skills/design-playbook/SKILL.md
 ```
 
-Manual MCP (only if not using `codex plugin add`):
+Register MCP directly (fallback when `codex plugin add` is unavailable):
+
+`codex plugin add` depends on a healthy codex marketplace subsystem. If `codex doctor`
+or `codex plugin marketplace list` fails (e.g. a stale marketplace source path), register
+the servers directly in `~/.codex/config.toml` (or your `CODEX_HOME`):
 
 ```toml
-# ~/.codex/config.toml
+# ~/.codex/config.toml  (or $CODEX_HOME/config.toml)
 [mcp_servers.design-playbook-preview]
 command = "python"
 args = ["<abs>/packages/design-playbook/mcp/preview/server.py"]
@@ -50,6 +54,16 @@ args = ["<abs>/packages/design-playbook/mcp/evidence/server.py"]
 # evidence also needs: pip install playwright && playwright install chromium
 ```
 
+Verify: `codex mcp list` should list both. `preview*` needs a system Edge/Chrome (the
+adapter spawns it via `--app=`); `observe*` needs Playwright + Chromium.
+
+> **`preview*` silently skips when `preview_prototype` is absent.** If preview does not
+> appear, the orchestrator probed `tools/list`, found no `preview_prototype`, and skipped
+> G5 - this is designed skip behaviour, not a crash. Confirm the tool is registered
+> (`codex mcp list`) before treating it as a preview failure. Codex end-to-end preview
+> smoke is not yet validated (v0.4.4 deferred the codex E2E smoke; only evidence/G6 was
+> server-level smoked).
+
 ## Load order
 
 1. `skills/design-playbook/SKILL.md`

package/lib/index.js

@@ -0,0 +1,172 @@
+'use strict'
+/**
+ * design-playbook dsh plugin
+ *
+ * Registers two contributions on the DSH context:
+ *
+ * 1. A skill provider (ctx.skills) whose candidates are this package's
+ *    `skills/` directory. The plugin locates the directory via `__dirname`,
+ *    so no `!!js` expression and no cwd-dependent resolution is involved.
+ *
+ * 2. Six slash commands (ctx.commands) — `design-io`, `doctor`,
+ *    `run-review`, `run-status`, `ui-review`, `ux-spec` — that load the
+ *    matching `commands/<name>.md` prompt, substitute `$ARGUMENTS` with the
+ *    raw trailing input, and inject it as a user-role follow-up turn via
+ *    `agent.followup()`.
+ *
+ * The Cordis `!!js` evaluation scope provides no `require` (only Node globals
+ * plus ctx-provided values like dshHomePath/loader), so pointing a
+ * skill-filesystem customSkillDirs row at package resources via
+ * `require.resolve` does not work. The plugin route is the supported way for
+ * a package to contribute its own skills and commands.
+ *
+ * Requires `ctx.skills` (the skill registry from @deepseek-ai/dsh-skill),
+ * `ctx.commands` (from @deepseek-ai/dsh-commands), and `@deepseek-ai/dsh-llm`
+ * (a core DSH dependency, always present in a booted profile).
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const SKILLS_DIR = path.join(__dirname, '..', 'skills')
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands')
+
+/** Parse a minimal frontmatter block: `---\nkey: value\n...\n---\nbody`. */
+function parseSkillFile(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8')
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
+  if (!m) return null
+  const front = {}
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([a-zA-Z0-9-]+):\s*(.*)$/.exec(line)
+    if (kv) front[kv[1]] = kv[2]
+  }
+  return { meta: front, content: m[2].trim() }
+}
+
+/**
+ * Build a user-role message carrying one text block.
+ *
+ * @deepseek-ai/dsh-llm is a core DSH dependency, but it lives in the DSH
+ * installation's node_modules, not in this package's node_modules.
+ * require.resolve from this package may fail depending on hoisting; the
+ * fallback plain object has the same shape DSH's inbox reads
+ * ({ id, role, content, source }) and is safe in all runtimes.
+ * @param {string} text - the prepared prompt body.
+ * @returns {object} a user-role message.
+ */
+function createUserMessageFromPrompt(text) {
+  try {
+    const { createUserMessage } = require('@deepseek-ai/dsh-llm')
+    return createUserMessage({
+      content: [{ type: 'text', text }],
+      source: { kind: 'user' },
+    })
+  } catch {
+    const crypto = require('node:crypto')
+    return Object.freeze({
+      id: crypto.randomUUID(),
+      role: 'user',
+      content: [{ type: 'text', text }],
+      source: { kind: 'user' },
+    })
+  }
+}
+
+exports.name = 'design-playbook'
+exports.inject = ['skills', 'commands']
+
+// Exported for test_commands.js to avoid duplicating the helpers.
+exports.parseSkillFile = parseSkillFile
+exports.createUserMessageFromPrompt = createUserMessageFromPrompt
+
+/**
+ * The six slash commands this plugin registers. Each maps to a
+ * `commands/<name>.md` prompt file; the file's frontmatter `description`
+ * becomes the command's discovery metadata, and the body (with `$ARGUMENTS`
+ * substituted) is injected as a user follow-up turn.
+ */
+const COMMAND_NAMES = [
+  'design-io',
+  'doctor',
+  'run-review',
+  'run-status',
+  'ui-review',
+  'ux-spec',
+]
+
+exports.apply = function (ctx) {
+  // ---- skills provider (P1) ----
+  if (fs.existsSync(SKILLS_DIR)) {
+    ctx.skills.registerProvider(() => {
+      const candidates = fs
+        .readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => {
+          const skillPath = path.join(SKILLS_DIR, e.name, 'SKILL.md')
+          if (!fs.existsSync(skillPath)) return null
+          const parsed = parseSkillFile(skillPath)
+          if (!parsed) return null
+          const meta = parsed.meta
+          const name = meta.name
+          const description = meta.description
+          if (!name || !description) return null
+          return {
+            name,
+            description,
+            ...(meta.whenToUse ? { whenToUse: meta.whenToUse } : {}),
+            rank: 600, // bundled rank (matches skill-filesystem's bundled rank)
+            invocation: { modelInvocable: true, userInvocable: true },
+            source: 'bundled',
+            provider: 'design-playbook',
+            resourceBase: { kind: 'directory', path: path.join(SKILLS_DIR, e.name) },
+            locator: skillPath,
+            path: skillPath,
+          }
+        })
+        .filter(Boolean)
+
+      return {
+        name: 'design-playbook',
+        list: async () => candidates,
+        get: async (candidate) => {
+          const parsed = parseSkillFile(candidate.locator)
+          if (!parsed) return undefined
+          return { ...candidate, content: parsed.content }
+        },
+      }
+    })
+  }
+
+  // ---- commands (P2) ----
+  // Each command loads its prompt from commands/<name>.md, substitutes
+  // $ARGUMENTS, and injects the result as a user-role follow-up turn. The
+  // handler returns a CommandResult immediately — the actual model work
+  // happens in the turn opened by agent.followup().
+  if (ctx.commands && fs.existsSync(COMMANDS_DIR)) {
+    for (const name of COMMAND_NAMES) {
+      const filePath = path.join(COMMANDS_DIR, `${name}.md`)
+      if (!fs.existsSync(filePath)) continue
+      const parsed = parseSkillFile(filePath)
+      if (!parsed || !parsed.meta.description) continue
+
+      // Capture the parsed body once — the handler substitutes $ARGUMENTS
+      // on the already-parsed content instead of re-reading the file.
+      const promptBody = parsed.content
+      ctx.commands.register({
+        name,
+        description: parsed.meta.description,
+        handler: (invocation) => {
+          const prompt = promptBody.replace(/\$ARGUMENTS/g, invocation.rawInput)
+          const message = createUserMessageFromPrompt(prompt)
+          // followup() queues an ordinary turn and wakes the driver — a
+          // slash command is an explicit user action, so followup is the
+          // right boundary (not inject(), which seeds context without
+          // waking).
+          invocation.agent.followup(message)
+          return { kind: 'success' }
+        },
+      })
+    }
+  }
+}

package/mcp/evidence/capture_runtime.py

@@ -15,6 +15,7 @@ from typing import Any, Protocol
 
 from design_playbook.mcp.evidence import containment
 from design_playbook.mcp.evidence.capture_contract import parse_capture_contract
+from design_playbook.mcp.preview.util import _log
 
 CAPTURE_TYPES = frozenset({"screenshot", "a11y tree", "interaction trace"})
 ALLOWED_ARGUMENTS = frozenset(
@@ -33,10 +34,6 @@ ALLOWED_ARGUMENTS = frozenset(
 RUN_ROOT_ENV = "DESIGN_PLAYBOOK_RUN_ROOT"
 
 
-def _log(msg: str) -> None:
-    print(msg, file=sys.stderr, flush=True)
-
-
 class BrowserAdapter(Protocol):
     """Internal browser seam used by the capture runtime."""
 
@@ -167,7 +164,8 @@ def _resolve_artifact_path(artifact_path: str) -> Path:
     """
     result = containment.write_target(artifact_path, _run_root())
     if result.ok:
-        return result.path  # type: ignore[return-value]
+        assert result.path is not None  # ok implies path is set
+        return result.path
     raise ValueError(_reason_message(result.reason))
 
 
@@ -203,6 +201,106 @@ _REASON_MESSAGES = {
 }
 
 
+def _require_selector(action: dict, index: int, do: str) -> str:
+    """Extract and validate a required selector for an action."""
+    selector = action.get("selector")
+    if not isinstance(selector, str) or not selector:
+        raise ValueError(f"actions[{index}].selector required for {do}")
+    return selector
+
+
+def _action_click(page: Any, action: dict, index: int, do: str) -> None:
+    selector = _require_selector(action, index, do)
+    page.click(selector, timeout=10_000)
+
+
+def _action_fill(page: Any, action: dict, index: int, do: str) -> None:
+    selector = _require_selector(action, index, do)
+    value = action.get("value")
+    if value is None:
+        value = action.get("text", "")
+    if not isinstance(value, str):
+        raise ValueError(f"actions[{index}].value must be a string")
+    page.fill(selector, value, timeout=10_000)
+
+
+def _action_type(page: Any, action: dict, index: int, do: str) -> None:
+    selector = _require_selector(action, index, do)
+    value = action.get("value")
+    if value is None:
+        value = action.get("text", "")
+    if not isinstance(value, str):
+        raise ValueError(f"actions[{index}].value must be a string")
+    page.click(selector, timeout=10_000)
+    page.keyboard.type(value)
+
+
+def _action_press(page: Any, action: dict, index: int, do: str) -> None:
+    key = action.get("key") or action.get("value")
+    if not isinstance(key, str) or not key:
+        raise ValueError(f"actions[{index}].key required for press")
+    selector = action.get("selector")
+    if isinstance(selector, str) and selector:
+        page.press(selector, key, timeout=10_000)
+    else:
+        page.keyboard.press(key)
+
+
+def _action_wait_for_selector(page: Any, action: dict, index: int, do: str) -> None:
+    selector = _require_selector(action, index, do)
+    page.wait_for_selector(selector, timeout=10_000)
+
+
+def _action_wait_for_state(page: Any, action: dict, index: int, do: str) -> None:
+    state = action.get("state")
+    if not isinstance(state, str) or not state:
+        raise ValueError(f"actions[{index}].state required for wait_for_state")
+    selector = action.get("selector")
+    if isinstance(selector, str) and selector:
+        page.wait_for_selector(selector, timeout=10_000)
+    else:
+        page.wait_for_selector(
+            f'[data-state="{state}"]',
+            timeout=10_000,
+        )
+
+
+def _action_wait(page: Any, action: dict, index: int, do: str) -> None:
+    ms = action.get("ms")
+    if ms is None:
+        ms = action.get("timeout_ms", 200)
+    page.wait_for_timeout(int(ms))
+
+
+def _action_select_option(page: Any, action: dict, index: int, do: str) -> None:
+    selector = _require_selector(action, index, do)
+    value = action.get("value")
+    label = action.get("label")
+    if value is None and label is None:
+        raise ValueError(
+            f"actions[{index}].value or label required for select_option")
+    if value is not None:
+        page.select_option(selector, value=value, timeout=10_000)
+    else:
+        page.select_option(selector, label=label, timeout=10_000)
+
+
+# Action registry: do → handler. Each handler owns its validation + Playwright
+# call. Adding an action type means adding a function + one entry here, not an
+# elif branch in a 75-line function.
+_ACTION_HANDLERS: dict[str, Any] = {
+    "click": _action_click,
+    "fill": _action_fill,
+    "type": _action_type,
+    "press": _action_press,
+    "wait_for_selector": _action_wait_for_selector,
+    "wait_for_state": _action_wait_for_state,
+    "wait": _action_wait,
+    "sleep": _action_wait,
+    "select_option": _action_select_option,
+}
+
+
 def _run_actions(page: Any, actions: list[dict[str, Any]]) -> None:
     for i, action in enumerate(actions):
         if not isinstance(action, dict):
@@ -211,73 +309,10 @@ def _run_actions(page: Any, actions: list[dict[str, Any]]) -> None:
         if not isinstance(do, str) or not do.strip():
             raise ValueError(f"actions[{i}].do is required")
         do = do.strip().lower()
-        selector = action.get("selector")
-        if do == "click":
-            if not isinstance(selector, str) or not selector:
-                raise ValueError(f"actions[{i}].selector required for click")
-            page.click(selector, timeout=10_000)
-        elif do in ("fill", "type"):
-            if not isinstance(selector, str) or not selector:
-                raise ValueError(f"actions[{i}].selector required for {do}")
-            value = action.get("value")
-            if value is None:
-                value = action.get("text", "")
-            if not isinstance(value, str):
-                raise ValueError(f"actions[{i}].value must be a string")
-            if do == "fill":
-                page.fill(selector, value, timeout=10_000)
-            else:
-                page.click(selector, timeout=10_000)
-                page.keyboard.type(value)
-        elif do == "press":
-            key = action.get("key") or action.get("value")
-            if not isinstance(key, str) or not key:
-                raise ValueError(f"actions[{i}].key required for press")
-            if isinstance(selector, str) and selector:
-                page.press(selector, key, timeout=10_000)
-            else:
-                page.keyboard.press(key)
-        elif do == "wait_for_selector":
-            if not isinstance(selector, str) or not selector:
-                raise ValueError(
-                    f"actions[{i}].selector required for wait_for_selector"
-                )
-            page.wait_for_selector(selector, timeout=10_000)
-        elif do == "wait_for_state":
-            state = action.get("state")
-            if not isinstance(state, str) or not state:
-                raise ValueError(f"actions[{i}].state required for wait_for_state")
-            # Prefer explicit selector; else body[data-state].
-            if isinstance(selector, str) and selector:
-                page.wait_for_selector(selector, timeout=10_000)
-            else:
-                page.wait_for_selector(
-                    f'[data-state="{state}"]',
-                    timeout=10_000,
-                )
-        elif do in ("wait", "sleep"):
-            ms = action.get("ms")
-            if ms is None:
-                ms = action.get("timeout_ms", 200)
-            page.wait_for_timeout(int(ms))
-        elif do == "select_option":
-            # Native <select> — page.fill raises "Fill did not work on <select>";
-            # select_option drives <option> by value (or visible label) and
-            # fires change.
-            if not isinstance(selector, str) or not selector:
-                raise ValueError(
-                    f"actions[{i}].selector required for select_option")
-            value = action.get("value")
-            label = action.get("label")
-            if value is None and label is None:
-                raise ValueError(
-                    f"actions[{i}].value or label required for select_option")
-            if value is not None:
-                page.select_option(selector, value=value, timeout=10_000)
-            else:
-                page.select_option(selector, label=label, timeout=10_000)
-        else:
+        handler = _ACTION_HANDLERS.get(do)
+        if handler is None:
             raise ValueError(f"actions[{i}]: unsupported do={do!r}")
+        handler(page, action, i, do)
 
 
 def _read_observed_state(page: Any) -> str:
@@ -399,6 +434,36 @@ class PlaywrightBrowserAdapter:
                 browser.close()
 
 
+def _validate_runtime_object(args: dict[str, Any]) -> tuple[str, str, str, list[dict[str, Any]]]:
+    """Validate Runtime Object fields and return (url, cap_type, state, actions).
+
+    Owns the field-level validation that execute_capture_plan previously
+    interleaved with capture logic. Keeps url/type/state/actions validation
+    in one locality so the handler reads cleanly.
+    """
+    url = args.get("url")
+    cap_type = args.get("type")
+    state = args.get("state")
+    actions = args.get("actions")
+
+    if not isinstance(url, str) or not url.strip():
+        raise ValueError("url is required")
+    if not isinstance(cap_type, str) or cap_type not in CAPTURE_TYPES:
+        raise ValueError(
+            f'type must be one of {sorted(CAPTURE_TYPES)}; got {cap_type!r}'
+        )
+    if not isinstance(state, str) or not state.strip():
+        raise ValueError("state is required")
+    if actions is None:
+        actions = []
+    if not isinstance(actions, list):
+        raise ValueError("actions must be an array")
+    for i, a in enumerate(actions):
+        if not isinstance(a, dict):
+            raise ValueError(f"actions[{i}] must be an object")
+    return url, cap_type, state, actions
+
+
 def execute_capture_plan(
     args: dict[str, Any],
     browser_adapter: BrowserAdapter | None = None,
@@ -419,32 +484,14 @@ def execute_capture_plan(
         label = artifact if isinstance(artifact, str) else ""
         return _failed(label, str(exc))
 
-    url = args.get("url")
-    cap_type = args.get("type")
-    state = args.get("state")
-    actions = args.get("actions")
+    url, cap_type, state, actions = _validate_runtime_object(args)
     artifact_path = args.get("artifact_path")
     overwrite = args.get("overwrite", False)
 
-    if not isinstance(url, str) or not url.strip():
-        raise ValueError("url is required")
-    if not isinstance(cap_type, str) or cap_type not in CAPTURE_TYPES:
-        raise ValueError(
-            f'type must be one of {sorted(CAPTURE_TYPES)}; got {cap_type!r}'
-        )
-    if not isinstance(state, str) or not state.strip():
-        raise ValueError("state is required")
     if not isinstance(artifact_path, str) or not artifact_path.strip():
         raise ValueError("artifact_path is required")
     if not isinstance(overwrite, bool):
         raise ValueError("overwrite must be a boolean")
-    if actions is None:
-        actions = []
-    if not isinstance(actions, list):
-        raise ValueError("actions must be an array")
-    for i, a in enumerate(actions):
-        if not isinstance(a, dict):
-            raise ValueError(f"actions[{i}] must be an object")
 
     rel = artifact_path.strip()
     try:

package/mcp/preview/integrity.py

@@ -110,6 +110,30 @@ def prototype_html_digest(raw: bytes) -> str:
     return hashlib.sha256(normalized).hexdigest()
 
 
+def compute_binding_digest(
+    *, round_n: int, prototype_html_hash: str, report_ref: str,
+    summary: str, options: list[str],
+) -> dict[str, Any]:
+    """Build the binding record (canonical fields + SHA-256 digest).
+
+    Single source of truth for the binding shape — transaction.py uses it
+    to write, load_entry() uses it to validate on read, and
+    _valid_decision_entry() uses it for the G5 gate. Moving it here keeps
+    the write side and read side from drifting.
+    """
+    fields = {
+        "round": round_n,
+        "prototype_html_hash": prototype_html_hash,
+        "report_ref": report_ref,
+        "summary": summary,
+        "options": list(options),
+    }
+    canonical = json.dumps(
+        fields, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8")
+    return {"digest": hashlib.sha256(canonical).hexdigest(), **fields}
+
+
 def _round_from_name(name: str) -> int | None:
     match = _ARTIFACT_ROUND.match(name)
     return int(match.group(1)) if match else None
@@ -166,17 +190,14 @@ def _valid_decision_entry(path: Path) -> bool:
         and isinstance(outcome, dict)
     ):
         return False
-    fields = {
-        "round": binding["round"],
-        "prototype_html_hash": binding["prototype_html_hash"],
-        "report_ref": binding["report_ref"],
-        "summary": binding["summary"],
-        "options": binding["options"],
-    }
-    canonical = json.dumps(
-        fields, ensure_ascii=False, sort_keys=True, separators=(",", ":")
-    ).encode("utf-8")
-    return binding.get("digest") == hashlib.sha256(canonical).hexdigest()
+    expected = compute_binding_digest(
+        round_n=binding["round"],
+        prototype_html_hash=binding["prototype_html_hash"],
+        report_ref=binding["report_ref"],
+        summary=binding["summary"],
+        options=binding["options"],
+    )
+    return binding.get("digest") == expected["digest"]
 
 
 def inspect_preview(preview_dir: Path) -> PreviewSnapshot:

package/mcp/preview/review_session.py

@@ -774,7 +774,8 @@ def collect_review(
             if validated:
                 done.set()
 
-    server = HTTPServer(("127.0.0.1", 0), Handler)
+    _preview_port = int(os.environ.get("DESIGN_PLAYBOOK_PREVIEW_PORT", "0"))
+    server = HTTPServer(("127.0.0.1", _preview_port), Handler)
     port = server.server_address[1]
     thread = threading.Thread(
         target=server.serve_forever, name="dpb-preview-http", daemon=True

package/mcp/preview/server.py

@@ -86,7 +86,13 @@ def _tool_schema() -> dict[str, Any]:
 
 
 
-def handle_preview_prototype(args: dict[str, Any]) -> dict[str, Any]:
+def _validate_preview_args(args: dict[str, Any]) -> tuple[str | None, str | None, str, int, str, list[str]]:
+    """Validate preview prototype arguments.
+
+    Owns the field-level validation so the handler reads cleanly and the
+    validation shape is testable in isolation. Returns
+    (path_arg, html, summary, round_n, report_ref, options).
+    """
     path_arg = args.get("path")
     html = args.get("html")
     summary = args.get("summary")
@@ -106,6 +112,11 @@ def handle_preview_prototype(args: dict[str, Any]) -> dict[str, Any]:
         raise ValueError("html must be a string")
     if not isinstance(options, list) or not all(isinstance(o, str) for o in options):
         raise ValueError("options must be string[]")
+    return path_arg, html, summary, round_n, report_ref, options
+
+
+def handle_preview_prototype(args: dict[str, Any]) -> dict[str, Any]:
+    path_arg, html, summary, round_n, report_ref, options = _validate_preview_args(args)
 
     try:
         return run_preview_transaction(

package/mcp/preview/test_server_stdio.py

@@ -81,9 +81,9 @@ class PreviewMcpStdioTests(unittest.TestCase):
     def test_active_lock_returns_structured_error_over_stdio(self) -> None:
         html = "<html><body>locked</body></html>"
         options = ["确认通过", "需要修改"]
-        binding = transaction._binding(
+        binding = transaction.compute_binding_digest(
             round_n=1,
-            prototype_hash=prototype_html_digest(html.encode("utf-8")),
+            prototype_html_hash=prototype_html_digest(html.encode("utf-8")),
             report_ref="report.md", summary="review", options=options,
         )
         with tempfile.TemporaryDirectory() as tmp:

package/mcp/preview/test_transaction.py

@@ -561,9 +561,9 @@ class PreviewDecisionTransactionTests(unittest.TestCase):
             with self.subTest(binding_matches=binding_matches), tempfile.TemporaryDirectory() as tmp:
                 prototype = Path(tmp) / "round-1.html"
                 prototype.write_text("reviewed", encoding="utf-8")
-                digest = transaction._binding(
+                digest = transaction.compute_binding_digest(
                     round_n=1,
-                    prototype_hash=prototype_html_digest(
+                    prototype_html_hash=prototype_html_digest(
                         prototype.read_bytes()
                     ),
                     report_ref="report.md", summary="summary",

package/mcp/preview/test_versions.py

@@ -38,8 +38,8 @@ def _seed_round(
     *, confirmed: bool = True, feedback: str = "ok",
 ) -> dict:
     digest = prototype_html_digest(html.encode("utf-8"))
-    binding = transaction._binding(
-        round_n=round_n, prototype_hash=digest, report_ref="r.md",
+    binding = transaction.compute_binding_digest(
+        round_n=round_n, prototype_html_hash=digest, report_ref="r.md",
         summary="s", options=["确认通过", "需要修改"])
     entry = {
         "schema_version": 1,
@@ -501,8 +501,8 @@ class ForkTests(unittest.TestCase):
             src.mkdir()
             # path-mode style: decision entry but no round-N.html snapshot
             digest = prototype_html_digest(b"<html>x</html>")
-            binding = transaction._binding(
-                round_n=1, prototype_hash=digest, report_ref="r.md",
+            binding = transaction.compute_binding_digest(
+                round_n=1, prototype_html_hash=digest, report_ref="r.md",
                 summary="s", options=["确认通过", "需要修改"])
             entry = {
                 "schema_version": 1,

package/mcp/preview/transaction.py

@@ -7,7 +7,6 @@ and result construction for one Preview decision.
 from __future__ import annotations
 
 import errno
-import hashlib
 import json
 import os
 import tempfile
@@ -25,7 +24,11 @@ else:
 
 from design_playbook.mcp.preview.control import _format_feedback
 from design_playbook.mcp.preview.i18n import CONFIRM_LABELS
-from design_playbook.mcp.preview.integrity import evaluate_feedback_floor, prototype_html_digest
+from design_playbook.mcp.preview.integrity import (
+    compute_binding_digest,
+    evaluate_feedback_floor,
+    prototype_html_digest,
+)
 from design_playbook.mcp.preview.util import _now_iso
 
 BrowserCollector = Callable[[Path, str, list[str], int], dict[str, Any]]
@@ -40,19 +43,38 @@ def _preview_dir_for(path: Path | None) -> Path:
     return scratch
 
 
-def _ensure_prototype(path_arg: str | None, html: str | None, round_n: int,
-                      preview_dir: Path) -> Path:
+def _resolve_prototype(
+    path_arg: str | None, html: str | None, round_n: int,
+    preview_dir: Path,
+) -> tuple[Path, str]:
+    """Resolve prototype source to a path and compute its digest.
+
+    Single source for prototype resolution: path mode reads the file, html
+    mode computes from inline bytes. Returns (prototype_path, digest) so
+    callers can build the binding without re-reading. Does NOT write the
+    html file — that is _ensure_prototype's job.
+    """
     if path_arg:
-        p = Path(path_arg)
-        if not p.is_file():
+        prototype = Path(path_arg)
+        if not prototype.is_file():
             raise ValueError(f"prototype path does not exist: {path_arg}")
-        return p
+        return prototype, prototype_html_digest(prototype.read_bytes())
     if not html:
         raise ValueError("path or html is required")
-    preview_dir.mkdir(parents=True, exist_ok=True)
-    target = preview_dir / f"round-{round_n}.html"
-    target.write_text(html, encoding="utf-8")
-    return target
+    return (
+        preview_dir / f"round-{round_n}.html",
+        prototype_html_digest(html.encode("utf-8")),
+    )
+
+
+def _ensure_prototype(path_arg: str | None, html: str | None, round_n: int,
+                      preview_dir: Path) -> Path:
+    """Resolve and materialize the prototype file on disk."""
+    prototype, _ = _resolve_prototype(path_arg, html, round_n, preview_dir)
+    if not path_arg:
+        preview_dir.mkdir(parents=True, exist_ok=True)
+        prototype.write_text(html, encoding="utf-8")
+    return prototype
 
 
 def self_check_floor() -> None:
@@ -444,23 +466,6 @@ def json_text(value: dict[str, Any]) -> str:
     return json.dumps(value, ensure_ascii=False, indent=2) + "\n"
 
 
-def _binding(
-    *, round_n: int, prototype_hash: str, report_ref: str,
-    summary: str, options: list[str],
-) -> dict[str, Any]:
-    fields = {
-        "round": round_n,
-        "prototype_html_hash": prototype_hash,
-        "report_ref": report_ref,
-        "summary": summary,
-        "options": list(options),
-    }
-    canonical = json.dumps(
-        fields, ensure_ascii=False, sort_keys=True, separators=(",", ":")
-    ).encode("utf-8")
-    return {"digest": hashlib.sha256(canonical).hexdigest(), **fields}
-
-
 def load_entry(path: Path) -> dict[str, Any] | None:
     if not path.is_file():
         return None
@@ -483,9 +488,9 @@ def load_entry(path: Path) -> dict[str, Any] | None:
     binding_valid = False
     if isinstance(binding, dict):
         try:
-            expected = _binding(
+            expected = compute_binding_digest(
                 round_n=round_n,
-                prototype_hash=binding["prototype_html_hash"],
+                prototype_html_hash=binding["prototype_html_hash"],
                 report_ref=binding["report_ref"], summary=binding["summary"],
                 options=binding["options"],
             )
@@ -702,17 +707,11 @@ def run_preview_transaction(
     summary = summary.strip()
     report_ref = report_ref.strip()
     preview_dir = _preview_dir_for(Path(path_arg) if path_arg else None)
-    if path_arg:
-        prototype = Path(path_arg)
-        if not prototype.is_file():
-            raise ValueError(f"prototype path does not exist: {path_arg}")
-        prototype_hash = prototype_html_digest(prototype.read_bytes())
-    else:
-        if not html:
-            raise ValueError("path or html is required")
-        prototype_hash = prototype_html_digest(html.encode("utf-8"))
-    binding = _binding(
-        round_n=round_n, prototype_hash=prototype_hash,
+    _prototype, prototype_hash = _resolve_prototype(
+        path_arg, html, round_n, preview_dir,
+    )
+    binding = compute_binding_digest(
+        round_n=round_n, prototype_html_hash=prototype_hash,
         report_ref=report_ref, summary=summary, options=options,
     )
     entry_path = preview_dir / f"decision-round-{round_n}.json"
@@ -756,16 +755,18 @@ def _run_locked(
     decision_id: str,
 ) -> dict[str, Any]:
     entry_path = preview_dir / f"decision-round-{round_n}.json"
-    if path_arg:
-        prototype = Path(path_arg)
-        if not prototype.is_file():
-            raise ValueError(f"prototype path does not exist: {path_arg}")
-        prototype_hash = prototype_html_digest(prototype.read_bytes())
-    else:
-        if not html:
-            raise ValueError("path or html is required")
-        prototype_hash = prototype_html_digest(html.encode("utf-8"))
-        prototype = preview_dir / f"round-{round_n}.html"
+    # Re-resolve inside the lock to detect TOCTOU: if the path-mode file
+    # changed between run_preview_transaction and lock acquisition, the
+    # recomputed hash will not match binding["digest"].
+    _prototype, locked_hash = _resolve_prototype(
+        path_arg, html, round_n, preview_dir,
+    )
+    if locked_hash != prototype_hash:
+        raise TransactionConflict(
+            "prototype changed between binding and lock acquisition",
+            retryable=False, round_n=round_n, decision_id=decision_id,
+            artifact=str(_prototype),
+        )
 
     existing = load_entry(entry_path)
     if existing is not None:

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "design-playbook",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Design I/O for coding agents: controllable UI generation via declarations (spec/domain/craft/design/components/template) and contracts (skill/evaluator). Use for product UI—console, dashboard, agent-ops, CJK-first apps.",
   "keywords": [
     "pi-package",
+    "dsh-plugin",
+    "dsh-bundle",
     "ui",
     "ux",
     "design",
@@ -17,6 +19,7 @@
   ],
   "license": "MIT",
   "author": "Bandersnatch0x (https://github.com/Bandersnatch0x)",
+  "main": "lib/index.js",
   "homepage": "https://github.com/Bandersnatch0x/design-playbook",
   "repository": {
     "type": "git",
@@ -28,11 +31,13 @@
     "commands",
     "mcp",
     "scripts",
+    "lib",
     "design_playbook.py",
     "examples",
     "codex",
     "NOTICE",
-    "!**/__pycache__"
+    "!**/__pycache__",
+    "!lib/test_commands.js"
   ],
   "pi": {
     "skills": [
@@ -42,5 +47,10 @@
       "./commands"
     ],
     "image": "https://raw.githubusercontent.com/Bandersnatch0x/design-playbook/main/packages/design-playbook/showcase/screenshots/hero.png"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
   }
 }