@1agh/maude 0.27.0 → 0.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -41,13 +41,13 @@
     "prepublishOnly": "bash scripts/check-version-parity.sh && bash plugins/design/dev-server/bin/check-runtime-bundles.sh"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.27.0",
-    "@1agh/maude-darwin-x64": "0.27.0",
-    "@1agh/maude-linux-arm64": "0.27.0",
-    "@1agh/maude-linux-arm64-musl": "0.27.0",
-    "@1agh/maude-linux-x64": "0.27.0",
-    "@1agh/maude-linux-x64-musl": "0.27.0",
-    "@1agh/maude-win32-x64": "0.27.0"
+    "@1agh/maude-darwin-arm64": "0.28.1",
+    "@1agh/maude-darwin-x64": "0.28.1",
+    "@1agh/maude-linux-arm64": "0.28.1",
+    "@1agh/maude-linux-arm64-musl": "0.28.1",
+    "@1agh/maude-linux-x64": "0.28.1",
+    "@1agh/maude-linux-x64-musl": "0.28.1",
+    "@1agh/maude-win32-x64": "0.28.1"
   },
   "files": [
     "cli",
@@ -85,7 +85,7 @@
     "scaffold"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "^2.4.16",
     "@changesets/cli": "^2.27.10",
     "@playwright/test": "^1.60.0"
   },

package/plugins/design/dev-server/activity.ts

@@ -0,0 +1,256 @@
+// Canvas activity tracker (Phase 13 / DDR-029).
+//
+// Subscribes to the existing `fs:any` bus event, filters for canvas-shaped
+// files under <designRoot>, and maintains a per-file `active | idle` status with
+// a debounce: rapid saves stay `active`, ACTIVITY_IDLE_MS of fs silence flips a
+// file to `idle`. Every transition emits `activity:change` on the bus, which
+// ws.ts forwards to canvas iframes as `{ type: 'activity', … }`. The injected
+// canvas runtime (use-canvas-activity.tsx) turns that into a live "agent works
+// here" overlay on the affected artboards.
+//
+// Bun-native (DDR-009): setTimeout/clearTimeout + Bun.file for the Task 7 diff;
+// no node:fs reads where Bun.file works. Pure, fs-injected helpers (isCanvasFile
+// / diffArtboardIds) unit-test without touching disk.
+
+import path from 'node:path';
+
+import type { Context } from './context.ts';
+
+/** Idle debounce — fs silence longer than this flips a file `active` → `idle`. */
+export const ACTIVITY_IDLE_MS = 3000;
+
+/** LRU cap on the per-file text stash used by the Task 7 region diff. */
+const STASH_CAP = 50;
+
+// Mirrors api.ts SKIP_DIRS — directories that never hold user-facing canvases.
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.turbo',
+  'dist',
+  'build',
+  '.expo',
+  'coverage',
+  'dev-server',
+  '_history',
+]);
+
+/**
+ * True when a design-root-relative path is a user-facing canvas the overlay
+ * should light up. `.tsx` / `.html` only, minus:
+ *   - runtime artifacts + any `_`-prefixed file or directory (`_history/`,
+ *     `_draw/`, `_smoke/`, `_locator.json`, …),
+ *   - SKIP_DIRS segments (node_modules, dist, …),
+ *   - DS preview specimens under `system/<ds>/preview/**` — a critic editing a
+ *     preview emits a real `fs:any`, but those aren't canvases the user is
+ *     iterating on, so an overlay there is a false positive (plan Task 1 gotcha;
+ *     extended to `.tsx` specimens, not just the `.html` the plan named, because
+ *     the rationale is identical).
+ *
+ * Pure — no disk access. Accepts back-slash or forward-slash input.
+ */
+export function isCanvasFile(rel: string): boolean {
+  if (typeof rel !== 'string') return false;
+  const p = rel.replace(/\\/g, '/').replace(/^\/+/, '');
+  if (!p) return false;
+  const segs = p.split('/');
+  const base = segs[segs.length - 1] ?? '';
+  const dot = base.lastIndexOf('.');
+  const ext = dot >= 0 ? base.slice(dot).toLowerCase() : '';
+  if (ext !== '.tsx' && ext !== '.html') return false;
+  for (const s of segs) {
+    if (SKIP_DIRS.has(s)) return false;
+    if (s.startsWith('_')) return false;
+  }
+  if (/(^|\/)system\/[^/]+\/preview\//.test(p)) return false;
+  return true;
+}
+
+export interface ActivityEntry {
+  status: 'active' | 'idle';
+  /** ISO timestamp of the last transition. */
+  ts: string;
+  /**
+   * Artboard ids the change was scoped to (Task 7), or null when the change is
+   * file-level (every artboard in the file lights up). Always null on the first
+   * sight of a file (no baseline to diff against).
+   */
+  artboardIds: string[] | null;
+}
+
+export interface ActivityChange {
+  file: string;
+  status: 'active' | 'idle';
+  artboard_ids: string[] | null;
+  ts: string;
+}
+
+export interface Activity {
+  /** WS-open snapshot — keyed by design-root-relative canvas path. */
+  state: Record<string, ActivityEntry>;
+  /**
+   * Test seam — synchronously mark a file `active` (file-level) and schedule its
+   * idle flip. The live path calls this from the `fs:any` handler, then refines
+   * `artboardIds` asynchronously via the Task 7 diff.
+   */
+  mark(file: string): void;
+  /** Unsubscribe from the bus and clear all pending idle timers. */
+  stop(): void;
+}
+
+export interface ActivityOptions {
+  /** Override the idle debounce (tests pass a small value). */
+  idleMs?: number;
+  /** Disable the Task 7 per-artboard diff (file-level only). Default: enabled. */
+  diff?: boolean;
+}
+
+export function createActivity(ctx: Context, opts: ActivityOptions = {}): Activity {
+  const idleMs = opts.idleMs ?? ACTIVITY_IDLE_MS;
+  const diffEnabled = opts.diff !== false;
+
+  const state: Record<string, ActivityEntry> = {};
+  const idleTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  // Last-seen file text, for the Task 7 region diff. Insertion-ordered Map = LRU.
+  const lastText = new Map<string, string>();
+
+  function emit(file: string) {
+    const e = state[file];
+    if (!e) return;
+    const change: ActivityChange = {
+      file,
+      status: e.status,
+      artboard_ids: e.artboardIds,
+      ts: e.ts,
+    };
+    ctx.bus.emit('activity:change', change);
+  }
+
+  function scheduleIdle(file: string) {
+    const prev = idleTimers.get(file);
+    if (prev) clearTimeout(prev);
+    const t = setTimeout(() => {
+      idleTimers.delete(file);
+      const e = state[file];
+      if (!e || e.status === 'idle') return;
+      e.status = 'idle';
+      e.ts = new Date().toISOString();
+      // Idle carries no artboard scope — the whole file cross-fades out.
+      e.artboardIds = null;
+      emit(file);
+    }, idleMs);
+    idleTimers.set(file, t);
+  }
+
+  // Public + internal entry. Marks the file `active` file-level (preserving any
+  // artboardIds already refined this active window), refreshes the idle timer,
+  // and emits. Emits on the idle→active transition AND on every refresh-while-
+  // active (plan Task 2) — idempotent for the client, which only fades on idle.
+  function mark(file: string) {
+    const prev = state[file];
+    const carryIds = prev && prev.status === 'active' ? prev.artboardIds : null;
+    state[file] = { status: 'active', ts: new Date().toISOString(), artboardIds: carryIds };
+    scheduleIdle(file);
+    emit(file);
+  }
+
+  // Task 7 — refine the active file's artboardIds via a cheap region diff of the
+  // previous vs current file text. Best-effort: any read race / parse ambiguity
+  // leaves the file-level highlight in place. Runs at most once per fs:any (which
+  // fs-watch already debounces 50 ms), and never blocks the synchronous mark().
+  async function refineArtboards(file: string) {
+    if (!ctx.paths?.designRoot) return;
+    try {
+      const abs = path.join(ctx.paths.designRoot, file);
+      const next = await Bun.file(abs).text();
+      const prev = lastText.get(file);
+      stash(file, next);
+      if (prev == null) return; // first sight — no baseline, stay file-level
+      const ids = diffArtboardIds(prev, next);
+      if (!ids || ids.length === 0) return; // ambiguous / outside-region change
+      const e = state[file];
+      if (e && e.status === 'active') {
+        e.artboardIds = ids;
+        emit(file);
+      }
+    } catch {
+      /* read race, file gone, or designRoot unset in tests — stay file-level */
+    }
+  }
+
+  function stash(file: string, text: string) {
+    if (lastText.has(file)) lastText.delete(file);
+    lastText.set(file, text);
+    while (lastText.size > STASH_CAP) {
+      const oldest = lastText.keys().next().value;
+      if (oldest === undefined) break;
+      lastText.delete(oldest);
+    }
+  }
+
+  const off = ctx.bus.on('fs:any', (rel: string) => {
+    if (!isCanvasFile(rel)) return;
+    mark(rel);
+    if (diffEnabled) void refineArtboards(rel);
+  });
+
+  function stop() {
+    off();
+    for (const t of idleTimers.values()) clearTimeout(t);
+    idleTimers.clear();
+    lastText.clear();
+  }
+
+  return { state, mark, stop };
+}
+
+// ---------------------------------------------------------------------------
+// Task 7 helpers — pure, regex-bounded region diff. Exported for unit tests.
+
+/**
+ * Map each `<DCArtboard id="X">…</DCArtboard>` to its inner body text. Returns
+ * `null` when no artboard markers are found (the file can't be region-scoped, so
+ * the caller falls back to a file-level highlight). DCArtboards aren't nested in
+ * practice, so a non-greedy body match is sufficient — deliberately not AST-
+ * based (a TSX parser would mean a new dep, against DDR-009's zero-dep spirit).
+ */
+function extractArtboardRegions(src: string): Map<string, string> | null {
+  const re = /<DCArtboard\b[^>]*\bid=["']([^"']+)["'][^>]*>([\s\S]*?)<\/DCArtboard>/g;
+  const map = new Map<string, string>();
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: canonical regex-exec loop.
+  while ((m = re.exec(src)) !== null) {
+    map.set(m[1] as string, m[2] as string);
+  }
+  return map.size === 0 ? null : map;
+}
+
+/** The file with every artboard BODY stripped — what's left is the "shell". */
+function artboardSkeleton(src: string): string {
+  return src.replace(
+    /(<DCArtboard\b[^>]*\bid=["'][^"']+["'][^>]*>)[\s\S]*?(<\/DCArtboard>)/g,
+    '$1$2'
+  );
+}
+
+/**
+ * Ids of the `<DCArtboard>` blocks whose body changed between two file
+ * revisions, or `null` to signal "fall back to file-level" when:
+ *   - either revision has no parseable artboard markers, OR
+ *   - anything outside the artboard bodies changed (imports, opening-tag attrs,
+ *     artboard added/removed → the shell differs), OR
+ *   - nothing inside any artboard body changed.
+ */
+export function diffArtboardIds(prev: string, next: string): string[] | null {
+  const prevRegions = extractArtboardRegions(prev);
+  const nextRegions = extractArtboardRegions(next);
+  if (!prevRegions || !nextRegions) return null;
+  if (artboardSkeleton(prev) !== artboardSkeleton(next)) return null;
+  const ids = new Set([...prevRegions.keys(), ...nextRegions.keys()]);
+  const changed: string[] = [];
+  for (const id of ids) {
+    if (prevRegions.get(id) !== nextRegions.get(id)) changed.push(id);
+  }
+  return changed.length ? changed : null;
+}

package/plugins/design/dev-server/ai-banner.tsx

@@ -125,6 +125,10 @@ export function AiBanner(): JSX.Element | null {
 
     // postMessage relay path — parent sends `ai-activity` events.
     const onMessage = (e: MessageEvent) => {
+      // DDR-078 security follow-up: only the trusted embedding parent relays
+      // ai-activity. Reject canvas self-posts faking a "Claude is editing"
+      // banner. Standalone (no parent) uses the own-WS path below instead.
+      if (e.source !== window.parent || window.parent === window) return;
       const m = e.data as { dgn?: string; file?: string; entry?: AiEntry | null } | null;
       if (!m || typeof m !== 'object') return;
       if (m.dgn !== 'ai-activity') return;

package/plugins/design/dev-server/annotations-context-toolbar.tsx

@@ -36,12 +36,12 @@ import {
   IconAlignCenter,
   IconAlignLeft,
   IconAlignRight,
-  IconArrowNone,
   IconArrowheadCircle,
   IconArrowheadDiamond,
   IconArrowheadLine,
   IconArrowheadTriangle,
   IconArrowheadTriangleOutline,
+  IconArrowNone,
   IconBold,
   IconChevronDown,
   IconCornerPill,

package/plugins/design/dev-server/annotations-layer.tsx

@@ -23,8 +23,8 @@
 
 import {
   type CSSProperties,
-  type PointerEvent as ReactPointerEvent,
   createContext,
+  type PointerEvent as ReactPointerEvent,
   useCallback,
   useContext,
   useEffect,
@@ -39,13 +39,13 @@ import {
   ARROW_HEADS,
   type ArrowHead,
   type ArrowLineType,
-  type SvgPrimitive,
   arrowPrimitives,
+  type SvgPrimitive,
 } from './canvas-arrowheads.ts';
 import { IconLineThick, IconLineThin } from './canvas-icons.tsx';
 import { useViewportControllerContext, useWorldRefContext } from './canvas-lib.tsx';
 import { buildAnnotationStrokesRecord } from './commands/annotation-strokes-command.ts';
-import { type Tool, crossedDragThreshold } from './input-router.tsx';
+import { crossedDragThreshold, type Tool } from './input-router.tsx';
 import { AnnotationResizeOverlay } from './use-annotation-resize.tsx';
 import { useAnnotationSelectionOptional } from './use-annotation-selection.tsx';
 import { useAnnotationsVisibility } from './use-annotations-visibility.tsx';

package/plugins/design/dev-server/api.ts

@@ -3,7 +3,7 @@
 
 import crypto from 'node:crypto';
 import type { Dirent } from 'node:fs';
-import { readFile, readdir, stat as statp } from 'node:fs/promises';
+import { readdir, readFile, stat as statp } from 'node:fs/promises';
 import path from 'node:path';
 
 import type { Context } from './context.ts';

package/plugins/design/dev-server/artboard-activity-overlay.tsx

@@ -0,0 +1,67 @@
+/**
+ * @file       artboard-activity-overlay.tsx — Phase 13 / DDR-029 overlay.
+ * @scope      plugins/design/dev-server/artboard-activity-overlay.tsx
+ * @purpose    The "agent works here" chrome for a single artboard: an animated
+ *             rim + a top-right `editing — <label>` badge. Rendered by
+ *             `DCArtboard` as a world-coord sibling of the `<article>`, so it
+ *             pans/zooms with the artboard for free.
+ *
+ * Decorative — `aria-hidden` + `pointer-events:none`. All visual styling
+ * (border, pulse keyframes, reduced-motion fallback) lives in the inspector
+ * style block injected by `inspect.ts` (single injection point — DDR-029), so
+ * this component only places the box and toggles `data-fading` for the 200 ms
+ * cross-fade out when the file goes idle.
+ */
+
+import type { CSSProperties } from 'react';
+
+export interface OverlayRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export function ArtboardActivityOverlay({
+  rect,
+  label,
+  active,
+  color,
+}: {
+  rect: OverlayRect;
+  label: string;
+  /** true = editing now (pulse, opacity 1); false = idle, cross-fading out. */
+  active: boolean;
+  /**
+   * Per-agent presence color (Phase 13.2 / DDR-078). Overrides the default
+   * `--mdcc-activity` hue so each agent's rim + badge carry its own color.
+   * Omitted for manual / non-agent edits (default inspector blue).
+   */
+  color?: string;
+}) {
+  const style: CSSProperties = {
+    position: 'absolute',
+    left: rect.x,
+    top: rect.y,
+    width: rect.w,
+    height: rect.h,
+    pointerEvents: 'none',
+    // The injected CSS reads `var(--mdcc-activity)`; setting it here recolors the
+    // border, the ::after glow, and the badge background in one shot.
+    ...(color ? ({ '--mdcc-activity': color } as CSSProperties) : {}),
+  };
+  return (
+    <div
+      className="dc-activity-rim"
+      data-fading={active ? undefined : 'true'}
+      aria-hidden
+      style={style}
+    >
+      {/* Phase 13.3 — full-artboard scan beam (top→bottom sweep). Styled +
+          animated by the injected inspector CSS; this just mounts the cover. */}
+      <div className="dc-activity-scan" />
+      <span className="dc-activity-badge">editing — {label}</span>
+    </div>
+  );
+}
+ArtboardActivityOverlay.displayName = 'ArtboardActivityOverlay';

package/plugins/design/dev-server/bin/scenario-report.mjs

@@ -21,7 +21,7 @@
 //
 // Output: <run-dir>/report.md (or --out), zero external dependencies (node:fs only).
 
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 
 const PLATFORM_ORDER = ['web-desktop', 'web-mobile', 'ios-phone', 'ios-tablet', 'android-phone'];

package/plugins/design/dev-server/bin/server-up.sh

@@ -9,13 +9,17 @@
 #   $DESIGN_ROOT/_server.json   (PID + port the running server wrote)
 #   $DESIGN_ROOT/_server.log    (stdout/stderr of the spawned server)
 #
-# Runtime selection (DDR-020):
-#   - Default: bun + server.ts. Hard-fails when bun is not on $PATH.
-#   - --allow-legacy: opt-in fallback to node + server.mjs (debug only;
-#     no TSX canvas pipeline, no HMR). Sunset in DDR-020 Phase B.
+# Runtime selection (DDR-020 / DDR-009 / DDR-084), in priority order:
+#   - --allow-legacy: opt-in node + server.mjs (debug only; no TSX pipeline, no HMR).
+#   - compiled platform binary: the PRODUCTION runtime — embeds yjs + every dep, so
+#     it boots on a global @1agh/maude install where `bun server.ts` from source
+#     cannot. Path comes from MAUDE_DEV_SERVER_BIN (set by `maude design <verb>`) or
+#     the postinstall side-channel <pkgRoot>/cli/.platform-binary-path.
+#   - bun + server.ts: dev tree / fallback. MAUDE_FORCE_SOURCE=1 forces this.
 #
 # Output: prints the port on stdout. Diagnostic lines go to stderr.
-# Exit:   0 = server ready / 1 = start timeout or missing runtime / 2 = bad args.
+# Exit:   0 = server ready / 1 = start timeout or missing runtime / 2 = bad args /
+#         3 = dev-server runtime deps missing (yjs/y-protocols/lib0 — see preflight).
 
 REPO=""
 TIMEOUT=10
@@ -41,9 +45,15 @@ if [ -z "$REPO" ]; then
   REPO="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 fi
 
-# Resolve plugin root + pick a server runtime. DDR-020: bun + server.ts is
-# authoritative. Legacy node + server.mjs is sunset; available only behind
-# --allow-legacy (debug-only — no TSX canvas pipeline, no HMR).
+# Resolve plugin root + pick a server runtime.
+#   --allow-legacy → node + server.mjs (debug-only — no TSX pipeline, no HMR).
+#   compiled platform binary → the PRODUCTION runtime (DDR-009/DDR-084). It embeds
+#     yjs + every dev-server dep, so it boots on a global `@1agh/maude` install
+#     where `bun server.ts` from source CANNOT (the deps live in a nested
+#     package.json the npm tarball excludes — the historic yjs-at-boot crash).
+#     `maude design <verb>` resolves it and passes MAUDE_DEV_SERVER_BIN; a direct
+#     `bash server-up.sh` falls back to the postinstall side-channel.
+#   bun + server.ts → dev tree / fallback (DDR-020 made bun authoritative for source).
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 SERVER_TS="$PLUGIN_ROOT/dev-server/server.ts"
@@ -51,6 +61,37 @@ SERVER_MJS="$PLUGIN_ROOT/dev-server/server.mjs"
 if [ ! -f "$SERVER_TS" ]; then SERVER_TS="$SCRIPT_DIR/../server.ts"; fi
 if [ ! -f "$SERVER_MJS" ]; then SERVER_MJS="$SCRIPT_DIR/../server.mjs"; fi
 
+# Resolve the compiled binary: env (set by `maude design <verb>`) wins; else the
+# postinstall side-channel at <pkgRoot>/cli/.platform-binary-path (covers a direct
+# `bash server-up.sh` on a production install). MAUDE_FORCE_SOURCE=1 forces source.
+SERVER_BIN="${MAUDE_DEV_SERVER_BIN:-}"
+if [ -z "$SERVER_BIN" ] && [ "${MAUDE_FORCE_SOURCE:-0}" != "1" ]; then
+  # PLUGIN_ROOT=<pkgRoot>/plugins/design, so the side-channel is ../../cli.
+  # `head -n1` (parity with the Node readers' `.trim()`) tolerates a trailing newline.
+  SC="$PLUGIN_ROOT/../../cli/.platform-binary-path"
+  if [ -f "$SC" ]; then
+    CAND="$(head -n1 "$SC" 2>/dev/null)"
+    [ -n "$CAND" ] && [ -x "$CAND" ] && SERVER_BIN="$CAND"
+  fi
+fi
+# Structural allowlist (DDR-084 hardening): only spawn a path that LOOKS like the
+# compiled platform binary — basename `maude`/`maude.exe` inside a `maude-<slug>/`
+# dir. A poisoned side-channel file or an injected MAUDE_DEV_SERVER_BIN pointing
+# elsewhere is ignored (fall back to source), so the env/file can only DENY the
+# binary, never redirect the spawn to an arbitrary executable. Mirrors
+# isPlausiblePlatformBinary() in cli/commands/design.mjs.
+if [ -n "$SERVER_BIN" ]; then
+  _sbase="$(basename "$SERVER_BIN")"
+  _sparent="$(basename "$(dirname "$SERVER_BIN")")"
+  case "$_sbase:$_sparent" in
+    maude:maude-* | maude.exe:maude-*) : ;;
+    *)
+      echo "server-up.sh: ignoring dev-server binary outside the expected maude-<slug>/ layout ($SERVER_BIN) — falling back to source" >&2
+      SERVER_BIN=""
+      ;;
+  esac
+fi
+
 RUNTIME=""
 RUNTIME_CMD=""
 if [ $ALLOW_LEGACY -eq 1 ]; then
@@ -61,6 +102,10 @@ if [ $ALLOW_LEGACY -eq 1 ]; then
   RUNTIME="node"
   RUNTIME_CMD="node $SERVER_MJS"
   echo "server-up.sh: WARNING — running legacy server.mjs (no TSX canvas pipeline, no HMR). DDR-020 sunsets this in Phase B." >&2
+elif [ -n "$SERVER_BIN" ] && [ -x "$SERVER_BIN" ] && [ "${MAUDE_FORCE_SOURCE:-0}" != "1" ]; then
+  RUNTIME="binary"
+  RUNTIME_CMD="$SERVER_BIN"
+  echo "server-up.sh: using compiled dev-server binary ($SERVER_BIN)" >&2
 elif command -v bun >/dev/null 2>&1 && [ -f "$SERVER_TS" ]; then
   RUNTIME="bun"
   RUNTIME_CMD="bun $SERVER_TS"
@@ -106,10 +151,58 @@ if [ -f "$STATE" ]; then
   fi
 fi
 
+# Step 1.5 — dependency preflight (source `bun server.ts` path ONLY; runs on cold
+# start). The compiled binary embeds its deps, so this is skipped when RUNTIME=binary
+# — it only guards the source fallback. The dev-server's runtime deps live in a
+# NESTED package.json (plugins/design/dev-server/) that a global `@1agh/maude` npm
+# install or a fresh `git worktree` does NOT populate; a missing `yjs` (imported at
+# boot by sync/index.ts) crashes `bun server.ts` AFTER spawn → without this guard we
+# poll the full ${TIMEOUT}s and report a generic "start timeout", burying the cause
+# in _server.log and silently degrading the mandatory visual-sanity gate. Fail loud
+# NOW with a context-correct hint. No auto-install: boot-self-heal.ts (DDR-044)
+# dropped that, and the durable production fix is booting the compiled binary
+# (DDR-009/DDR-084), not a boot-time install. setup-ds Round-2 / DDR-083 + DDR-084.
+if [ "$RUNTIME" = "bun" ]; then
+  DEV_SERVER_DIR="$(cd "$(dirname "$SERVER_TS")" && pwd)"
+  _resolve_dep() {
+    # Mirror node/bun bare-specifier resolution: walk node_modules up to /.
+    # Handles both the dev-server-local install and a workspace-hoisted one.
+    local dep="$1" d="$DEV_SERVER_DIR"
+    while [ -n "$d" ] && [ "$d" != "/" ]; do
+      [ -e "$d/node_modules/$dep/package.json" ] && return 0
+      d="$(dirname "$d")"
+    done
+    return 1
+  }
+  MISSING_DEPS=""
+  for dep in yjs y-protocols lib0; do
+    _resolve_dep "$dep" || MISSING_DEPS="$MISSING_DEPS $dep"
+  done
+  if [ -n "$MISSING_DEPS" ]; then
+    {
+      echo "✗ dev-server runtime deps not installed:$MISSING_DEPS"
+      if [ -f "$DEV_SERVER_DIR/package.json" ]; then
+        # A manifest is present (local dev tree / checkout) — install resolves it.
+        echo "  → run: (cd \"$DEV_SERVER_DIR\" && bun install)   # or: pnpm install at the repo root"
+      else
+        # No manifest beside server.ts AND no compiled binary resolved → the
+        # '@1agh/maude' install is incomplete. The platform binary (which embeds
+        # these deps) is the production runtime — reinstall to get it.
+        echo "  (no dev-server package.json here and no compiled binary resolved — the"
+        echo "   '@1agh/maude' install is incomplete; the platform binary embeds these deps)"
+        echo "  → reinstall:  npm i -g @1agh/maude     (or: npm rebuild -g @1agh/maude)"
+      fi
+    } >&2
+    exit 3
+  fi
+fi
+
 # Step 2 — spawn.
 mkdir -p "$DESIGN_ROOT"
 echo "→ starting dev server: $RUNTIME_CMD --root $REPO" >&2
-if [ "$RUNTIME" = "bun" ]; then
+if [ "$RUNTIME" = "binary" ]; then
+  nohup "$SERVER_BIN" --root "$REPO" > "$DESIGN_ROOT/_server.log" 2>&1 &
+elif [ "$RUNTIME" = "bun" ]; then
   nohup bun "$SERVER_TS" --root "$REPO" > "$DESIGN_ROOT/_server.log" 2>&1 &
 elif [ "$RUNTIME" = "node" ]; then
   nohup node "$SERVER_MJS" --root "$REPO" > "$DESIGN_ROOT/_server.log" 2>&1 &

package/plugins/design/dev-server/bin/visual-sanity.sh

@@ -41,6 +41,9 @@
 #   2  bad args
 #   3  one or more specimen screenshots failed
 #   4  no specimens existed on disk (DS not scaffolded? typo?)
+#   5  dev-server runtime deps missing (yjs/y-protocols/lib0) — recovery is
+#      `bun install`, NOT skip-or-retry; distinct from a generic boot failure
+#      so the caller routes to the right hint (server-up.sh exit 3). DDR-083.
 
 DS=""
 SPECIMENS=""
@@ -142,18 +145,31 @@ echo "→ booting dev-server (timeout ${BOOT_TIMEOUT}s)" >&2
 PORT=$(bash "$SCRIPT_DIR/server-up.sh" --root "$ROOT_ABS" --timeout "$BOOT_TIMEOUT")
 SERVER_RC=$?
 if [ $SERVER_RC -ne 0 ] || [ -z "$PORT" ]; then
-  echo "✗ dev-server boot failed (server-up.sh exit $SERVER_RC); see $DESIGN_ROOT/_server.log" >&2
+  # server-up.sh exit 3 = the dev-server's runtime deps aren't installed. That's
+  # a distinct failure from a generic boot crash/timeout: the fix is `bun install`,
+  # not "skip or retry". Surface a dedicated status + exit code (5) so the caller
+  # routes to the right remediation instead of the boot-failed AskUserQuestion.
+  # The actionable hint already went to stderr from server-up.sh. DDR-083.
+  if [ $SERVER_RC -eq 3 ]; then
+    echo "✗ dev-server runtime deps missing — run \`bun install\` in the dev-server dir (see hint above)" >&2
+    VS_STATUS="server-deps-missing"
+    VS_EXIT=5
+  else
+    echo "✗ dev-server boot failed (server-up.sh exit $SERVER_RC); see $DESIGN_ROOT/_server.log" >&2
+    VS_STATUS="server-boot-failed"
+    VS_EXIT=1
+  fi
   cat > "$OUT_DIR/_manifest.json" <<EOF
 {
   "ds": "$DS",
   "ts": "$TS",
-  "status": "server-boot-failed",
+  "status": "$VS_STATUS",
   "server_up_rc": $SERVER_RC,
   "specimens_requested": $(printf '%s\n' "${SPEC_ARR[@]}" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | sed '/^$/d' | sed 's/.*/"&"/' | paste -sd, -),
   "specimens_captured": []
 }
 EOF
-  exit 1
+  exit $VS_EXIT
 fi
 echo "✓ dev-server on port $PORT" >&2