@1agh/maude 0.37.0 → 0.38.0

package/apps/studio/hmr-broadcast.ts

@@ -63,11 +63,29 @@ export function createHmrBroadcaster(
   broadcast: (msg: HmrMessage) => void
 ): HmrBroadcaster {
   let pending: ReturnType<typeof setTimeout> | null = null;
-  let pendingMsg: HmrMessage | null = null;
+  // RC4 (rca/issue-canvas-hmr-optimistic-update-consistency) — one pending
+  // message PER FILE, plus a shared bucket for file-less messages (`hard` is
+  // global). The old single-slot pendingMsg meant a <50 ms multi-file burst
+  // (an agent turn touching several canvases) broadcast only the LAST file:
+  // every other open canvas missed its reload and sat stale until a manual
+  // hard refresh.
+  const GLOBAL_KEY = '\0global'; // NUL prefix — can't collide with an on-disk rel path
+  const pendingByKey = new Map<string, HmrMessage>();
+  // meta is the lightest signal — it doesn't trigger a reload, just re-fetches
+  // the sidecar. CSS still ranks above it so a same-window CSS write wins over
+  // a meta echo; hard tops everything.
+  const rank: Record<HmrMessage['mode'], number> = { meta: 0, css: 1, module: 2, hard: 3 };
 
   function flush() {
-    if (pendingMsg) broadcast(pendingMsg);
-    pendingMsg = null;
+    // A pending `hard` supersedes the per-file queue — every open canvas does a
+    // full reload anyway, so the softer messages would be redundant churn.
+    const hard = pendingByKey.get(GLOBAL_KEY);
+    if (hard?.mode === 'hard') {
+      broadcast(hard);
+    } else {
+      for (const msg of pendingByKey.values()) broadcast(msg);
+    }
+    pendingByKey.clear();
     pending = null;
   }
 
@@ -80,21 +98,11 @@ export function createHmrBroadcaster(
   }
 
   function enqueue(msg: HmrMessage) {
-    // Coalesce: hard > module > css. If a hard reload is queued, ignore any
-    // softer follow-up within the debounce window.
-    if (pendingMsg) {
-      // meta is the lightest signal — it doesn't trigger a reload, just
-      // re-fetches the sidecar. CSS still ranks above it so a same-window
-      // CSS write wins over a meta echo.
-      const rank: Record<HmrMessage['mode'], number> = { meta: 0, css: 1, module: 2, hard: 3 };
-      if (rank[msg.mode] < rank[pendingMsg.mode]) {
-        // Keep the existing (harder) message; just refresh the timer.
-      } else {
-        pendingMsg = msg;
-      }
-    } else {
-      pendingMsg = msg;
-    }
+    const key = msg.mode === 'hard' ? GLOBAL_KEY : (msg.file ?? GLOBAL_KEY);
+    const prev = pendingByKey.get(key);
+    // Same-key coalescing keeps the strongest mode (refreshing the payload for
+    // equal rank, so the latest version token wins).
+    if (!prev || rank[msg.mode] >= rank[prev.mode]) pendingByKey.set(key, msg);
     if (pending) clearTimeout(pending);
     pending = setTimeout(flush, DEBOUNCE_MS);
   }
@@ -109,7 +117,7 @@ export function createHmrBroadcaster(
       offAny();
       if (pending) clearTimeout(pending);
       pending = null;
-      pendingMsg = null;
+      pendingByKey.clear();
     },
   };
 }

package/apps/studio/http.ts

@@ -126,7 +126,7 @@ export function cspForCanvasShell(html: string, mainOrigin?: string): string {
 
 /**
  * CSRF guard for the main-origin source-write routes (edit-css / edit-text /
- * edit-attr). Those routes are reachable only from the shell, which is
+ * edit-attr / reorder). Those routes are reachable only from the shell, which is
  * same-origin — but `readJson` enforces no `Content-Type`, so a cross-site page
  * could otherwise forge a `text/plain` CORS *simple-request* POST to
  * `http://localhost:<port>/_api/edit-*` (no preflight) and drive a write into
@@ -188,9 +188,10 @@ interface CanvasCacheEntry {
   sig: string;
   etag: string;
   js: string;
-  /** Absolute paths of the relative `.css` imports inlined into this build —
+  /** Absolute paths of the relative imports inlined into this build (`.css` +
+   *  local `.tsx/.ts` modules, incl. unresolved extensionless candidates) —
    *  re-statted each request to recompute `sig` without re-reading the source. */
-  cssDeps: string[];
+  deps: string[];
 }
 const canvasCache = new Map<string, CanvasCacheEntry>();
 
@@ -214,34 +215,70 @@ const RUNTIME_BOOT_ID = `${Date.now().toString(36)}${Math.random().toString(36).
 // gets the stale bundle even after the HMR hard-reload. (DDR-067.)
 let CHROME_EPOCH = 0;
 
-/** Relative `.css` import specifiers in a canvas source → absolute paths (the
- *  files Bun.build inlines). Bare / virtual specifiers (`@maude/…`, npm) are
- *  skipped — only on-disk relative CSS affects the inlined output. Resolved
- *  paths are clamped to `designRoot`: a canvas source is attacker-influenced
- *  under linked mode (DDR-054), and these paths are `stat`-ed for mtime, so a
- *  `../../../etc/…` specifier must not let the freshness probe reach outside the
- *  design tree. Legit DS imports (`../../system/<ds>/…`) stay inside designRoot. */
-function cssDepsFromSource(source: string, canvasAbsPath: string, designRoot: string): string[] {
+/** Relative import specifiers in a canvas source → absolute paths (the files
+ *  Bun.build inlines): sibling `.css`, and — RC6 of
+ *  rca/issue-canvas-hmr-optimistic-update-consistency — imported local
+ *  `.tsx/.ts/.jsx/.js` modules, which are inlined exactly like CSS (only
+ *  RUNTIME_PACKAGES stay external, canvas-build.ts), so an edit to an imported
+ *  sibling must bust the mtime-keyed cache the same way. Extensionless
+ *  specifiers contribute EVERY resolution candidate (`.tsx`, `.ts`, …,
+ *  `index.tsx`); missing candidates stat as 0, so a dep file APPEARING later
+ *  also changes the signature. One level only — no transitive graph (the
+ *  import-graph HMR re-emit is a tracked follow-up). Bare / virtual specifiers
+ *  (`@maude/…`, npm) are skipped. Resolved paths are clamped to `designRoot`:
+ *  a canvas source is attacker-influenced under linked mode (DDR-054), and
+ *  these paths are `stat`-ed for mtime, so a `../../../etc/…` specifier must
+ *  not let the freshness probe reach outside the design tree. Legit DS imports
+ *  (`../../system/<ds>/…`) stay inside designRoot. */
+export function localDepsFromSource(
+  source: string,
+  canvasAbsPath: string,
+  designRoot: string
+): string[] {
   const dir = dirname(canvasAbsPath);
   const root = resolve(designRoot);
   const deps: string[] = [];
-  const re = /import\s+["']([^"']+\.css)["']/g;
-  let m: RegExpExecArray | null = re.exec(source);
-  while (m !== null) {
-    if (m[1].startsWith('.')) {
-      const abs = resolve(dir, m[1]);
-      if (abs === root || abs.startsWith(root + sep)) deps.push(abs);
+  const seen = new Set<string>();
+  const push = (abs: string) => {
+    if (abs !== root && !abs.startsWith(root + sep)) return; // clamp (DDR-054)
+    if (seen.has(abs)) return;
+    seen.add(abs);
+    deps.push(abs);
+  };
+  const specRes = [
+    /\bimport\s+["']([^"']+)["']/g, // side-effect: import './x.css'
+    /\bfrom\s+["']([^"']+)["']/g, // import … from / export … from
+    /\bimport\(\s*["']([^"']+)["']\s*\)/g, // dynamic import('./x')
+  ];
+  for (const re of specRes) {
+    for (let m = re.exec(source); m !== null; m = re.exec(source)) {
+      const spec = m[1];
+      if (!spec?.startsWith('.')) continue;
+      const base = resolve(dir, spec);
+      if (/\.(css|tsx|ts|jsx|js)$/i.test(spec)) {
+        push(base);
+      } else {
+        for (const cand of [
+          `${base}.tsx`,
+          `${base}.ts`,
+          `${base}.jsx`,
+          `${base}.js`,
+          resolve(base, 'index.tsx'),
+          resolve(base, 'index.ts'),
+        ])
+          push(cand);
+      }
     }
-    m = re.exec(source);
   }
   return deps;
 }
 
-/** mtime signature over the .tsx + its inlined CSS deps. A missing/unreadable
- *  file contributes 0 — a delete is itself a change, so the signature differs. */
-function canvasFreshnessSig(tsxAbsPath: string, cssDeps: string[]): string {
+/** mtime signature over the .tsx + every inlined relative dep (`.css` + local
+ *  modules). A missing/unreadable file contributes 0 — a delete is itself a
+ *  change (and a later create too), so the signature differs. */
+function canvasFreshnessSig(tsxAbsPath: string, deps: string[]): string {
   const parts: string[] = [];
-  for (const p of [tsxAbsPath, ...cssDeps]) {
+  for (const p of [tsxAbsPath, ...deps]) {
     const mt = Bun.file(p).lastModified;
     parts.push(`${p}@${Number.isFinite(mt) ? mt : 0}`);
   }
@@ -271,11 +308,11 @@ async function serveCanvasTsx(
   // HMR reload (mode:'module') re-served the stale inlined CSS — the edit only
   // surfaced once the .tsx itself changed (DDR-064 dogfooding finding).
   let cached = canvasCache.get(absPath);
-  const sig = canvasFreshnessSig(absPath, cached?.cssDeps ?? []);
+  const sig = canvasFreshnessSig(absPath, cached?.deps ?? []);
 
   if (!cached || cached.sig !== sig) {
     const source = await file.text();
-    const cssDeps = cssDepsFromSource(source, absPath, ctx.paths.designRoot);
+    const deps = localDepsFromSource(source, absPath, ctx.paths.designRoot);
     let result: Awaited<ReturnType<typeof buildCanvasModule>>;
     try {
       result = await buildCanvasModule(absPath, source, {
@@ -297,13 +334,13 @@ async function serveCanvasTsx(
     // Recompute the signature against the freshly-parsed deps — this very edit
     // may have added or removed a `.css` import.
     cached = {
-      sig: canvasFreshnessSig(absPath, cssDeps),
+      sig: canvasFreshnessSig(absPath, deps),
       // Fold in the boot id (restart) + chrome epoch (live edit) so a chrome
       // change busts the browser's cached transpile even when the canvas source
       // (hence result.etag) is unchanged. See RUNTIME_BOOT_ID / CHROME_EPOCH.
       etag: `${result.etag}-${RUNTIME_BOOT_ID}-${CHROME_EPOCH}`,
       js: result.js,
-      cssDeps,
+      deps,
     };
     canvasCache.set(absPath, cached);
     // Persist the locator map. Awaited so the inspector / Phase-12 layers
@@ -618,6 +655,42 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActiv
       });
     },
 
+    // Phase 31 follow-up — persist an image pasted straight into the ACP composer
+    // (a clipboard screenshot has no path), returning an absolute path the chip
+    // expands to so Claude can Read it. MAIN-ORIGIN ONLY: sameOriginWrite CSRF gate
+    // + deliberately absent from CANVAS_SAFE_API + startCanvasServer routes, so the
+    // untrusted canvas iframe is 403'd. The disk caps live in api.saveChatAttachment
+    // (magic-byte sniff / 10 MB / content-addressed name / session write budget).
+    '/_api/acp/attachment': async (req: Request) => {
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const declared = Number(req.headers.get('content-length') || '0');
+      if (Number.isFinite(declared) && declared > 10 * 1024 * 1024) {
+        return Response.json(
+          { ok: false, error: 'attachment exceeds the 10 MB cap' },
+          { status: 413, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      let bytes: Uint8Array;
+      try {
+        bytes = new Uint8Array(await req.arrayBuffer());
+      } catch {
+        return new Response('could not read request body', { status: 400 });
+      }
+      const result = await api.saveChatAttachment(bytes);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status ?? 400, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { path: result.path },
+        { status: 201, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     // Phase 9 Task 8 — offline-mode banner poll fallback. The linked-mode sync
     // runtime writes `_sync.json`; browser tabs also get live pushes over the
     // WS ('sync:status'). Returns `{ linked: false }` in solo mode.
@@ -1183,6 +1256,75 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActiv
       );
     },
 
+    '/_api/reorder': async (req: Request) => {
+      // Phase 12.1 (DDR-138) — node-move reorder. POST body
+      // { canvas, id, refId, position } → moves the element with data-cd-id `id`
+      // to `position` ('before'|'after'|'inside-start'|'inside-end') relative to
+      // `refId` (reparent-capable) via api.reorder → moveElement. Snapshots the
+      // pre-move source for /design:rollback. Same MAIN-ORIGIN-ONLY trust boundary
+      // as /_api/edit-css + /_api/edit-text + /_api/edit-attr: intentionally absent
+      // from CANVAS_SAFE_API + startCanvasServer's route allowlist (DDR-054) — the
+      // untrusted canvas iframe requests a reorder over the dgn:* bus and the shell
+      // (main origin) performs this privileged write.
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{
+        canvas?: unknown;
+        id?: unknown;
+        refId?: unknown;
+        position?: unknown;
+        idIndex?: unknown;
+        refIndex?: unknown;
+      }>(req, 8 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.reorder(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        {
+          ok: true,
+          delta: result.delta,
+          movedId: result.movedId,
+          semanticId: result.semanticId,
+          seq: result.seq,
+        },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
+    '/_api/reorder-revert': async (req: Request) => {
+      // Phase 12.1 follow-up — Cmd+Z / Cmd+Shift+Z for a reorder. POST body
+      // { canvas, seq, dir:'undo'|'redo' } → api.reorderRevert swaps the whole
+      // file back to the logged {before|after} content (id-churn-proof; refuses
+      // 409 when the canvas changed since). Same MAIN-ORIGIN-ONLY boundary as
+      // /_api/reorder — NOT in CANVAS_SAFE_API nor startCanvasServer's routes;
+      // the canvas undo stack requests it over the dgn bus, the shell writes.
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{ canvas?: unknown; seq?: unknown; dir?: unknown }>(
+        req,
+        8 * 1024
+      );
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.reorderRevert(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { ok: true, dir: result.dir },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_api/asset': async (req: Request) => {
       // Phase 23 — binary image upload from the canvas (drag-drop / paste / the
       // a11y file picker). POST raw image bytes → content-addressed write under

package/apps/studio/inspect.ts

@@ -1,6 +1,8 @@
 // Active-canvas state, selected-element tracking, and HTML injection
 // (inspector overlay + canvas runtime). See plan Task 7 + DDR-007.
 
+import path from 'node:path';
+
 import type { Context } from './context.ts';
 
 export interface SelectedElement {
@@ -32,6 +34,19 @@ export interface SelectedElement {
    * derives it server-side from `file` (stripping `<designRoot>/` prefix + `.tsx`).
    */
   canvas?: string;
+  /**
+   * Canvas-file mtime (ms) at capture — the drift-gate stamp
+   * (feature-acp-context-hardening). `data-cd-id` is POSITIONAL, not content
+   * identity, so a selection restored after another agent edited the canvas
+   * must not be trusted blindly. 0 = mtime unavailable.
+   */
+  canvas_mtime?: number;
+  /**
+   * Set on restore-from-`selections` when the canvas changed since capture
+   * (mtime mismatch). Consumers re-anchor via `data-dc-element`/selector or
+   * degrade to canvas-wide — never trust the positional id when stale.
+   */
+  stale?: boolean;
 }
 
 /**
@@ -47,6 +62,16 @@ export interface ActiveState {
   active: string | null;
   open_tabs: string[];
   selected: SelectedValue;
+  /**
+   * Per-canvas selection memory, keyed by canvas slug
+   * (feature-acp-context-hardening). Additive: `selected` above stays the
+   * ACTIVE canvas's mirror, so every legacy reader (prep.sh SEL_VALID,
+   * /design:edit step 3, handoff tooling) keeps working unchanged — the same
+   * back-compat philosophy as the Phase 4.1 obj→arr widening. Non-active
+   * entries carry `html: ''` (size cap — locators survive, the 4000-char
+   * payload doesn't multiply across N canvases).
+   */
+  selections: Record<string, SelectedValue>;
   last_change: string | null;
   session_started: string;
   active_comments?: unknown[];
@@ -71,6 +96,7 @@ const NEW = (): ActiveState => ({
   active: null,
   open_tabs: [],
   selected: null,
+  selections: {},
   last_change: null,
   session_started: new Date().toISOString(),
 });
@@ -113,24 +139,85 @@ export function createInspect(
       const raw = await Bun.file(ctx.paths.activeFile).text();
       const prev = JSON.parse(raw);
       Object.assign(state, prev, { session_started: new Date().toISOString() });
+      // Pre-selections _active.json (or a hand-edited one) → keep the invariant.
+      if (!state.selections || typeof state.selections !== 'object') state.selections = {};
     } catch {
       // first boot
     }
   }
 
+  /** Canvas-file mtime for the drift-gate stamp. `file` is repoRoot-relative
+   *  (designRel-prefixed, as the iframe reports it). Best-effort 0. Clamp to
+   *  designRoot: `file` originates in the (untrusted, DDR-054) canvas via the
+   *  origin-checked postMessage relay, and we `stat` it — a `../../../etc/…`
+   *  must not turn this into a filesystem existence/mtime oracle (defender S1;
+   *  mirrors localDepsFromSource's clamp). */
+  function mtimeFor(file: string): number {
+    try {
+      const rel = (file || '').replace(/^\/+/, '');
+      if (!rel) return 0;
+      const abs = path.resolve(ctx.paths.designRoot, path.relative(ctx.paths.designRel, rel));
+      const root = path.resolve(ctx.paths.designRoot);
+      if (abs !== root && !abs.startsWith(root + path.sep)) return 0;
+      const mt = Bun.file(abs).lastModified;
+      return Number.isFinite(mt) ? mt : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  /** Size cap for parked (non-active) selections — locators survive, the
+   *  4000-char outerHTML doesn't multiply across N canvases. */
+  function stripHtml(sel: SelectedValue): SelectedValue {
+    if (sel == null) return sel;
+    const strip = (e: SelectedElement): SelectedElement => ({ ...e, html: '' });
+    return Array.isArray(sel) ? sel.map(strip) : strip(sel);
+  }
+
+  /** Restore the incoming canvas's parked selection, drift-gated: a canvas
+   *  edited since capture gets `stale: true` on every element (positional
+   *  data-cd-id must not be trusted across another writer's edit). */
+  function restoreFor(file: string): SelectedValue {
+    const parked = state.selections[deriveCanvasSlug(file)];
+    if (parked == null) return null;
+    const current = mtimeFor(file);
+    const gate = (e: SelectedElement): SelectedElement =>
+      e.canvas_mtime && current && e.canvas_mtime !== current ? { ...e, stale: true } : e;
+    return Array.isArray(parked) ? parked.map(gate) : gate(parked);
+  }
+
   function setActive(file: string) {
     if (typeof file !== 'string') return;
     if (state.active === file) return;
+    // Park the outgoing canvas's selection (html-stripped) instead of losing
+    // it — the root fix for "switch canvas → agent loses my selection"
+    // (feature-acp-context-hardening).
+    if (state.active && state.selected != null) {
+      state.selections[deriveCanvasSlug(state.active)] = stripHtml(state.selected);
+    }
     state.active = file || null;
-    state.selected = null;
+    state.selected = file ? restoreFor(file) : null;
     state.last_change = new Date().toISOString();
     scheduleSave();
     ctx.bus.emit('active', state.active);
+    // Clients (StatusBar, shell halo, chat context chip) must see the restored
+    // selection, not assume the pre-switch null.
+    ctx.bus.emit('selected', state.selected);
   }
 
   function setOpenTabs(tabs: string[]) {
     if (!Array.isArray(tabs)) return;
     state.open_tabs = tabs.filter((t): t is string => typeof t === 'string');
+    // GC selection memory for closed canvases — a closed tab's parked
+    // selection has no consumer and would otherwise accrete forever. Keep the
+    // CURRENT active canvas too: the single-canvas shell sends `tabs` with only
+    // the incoming canvas BEFORE `active` parks the outgoing one, so without
+    // this the outgoing canvas's memory would depend on message ordering.
+    const keep = new Set(state.open_tabs.map((t) => deriveCanvasSlug(t)));
+    if (state.active) keep.add(deriveCanvasSlug(state.active));
+    for (const slug of Object.keys(state.selections)) {
+      if (!keep.has(slug)) delete state.selections[slug];
+    }
     state.last_change = new Date().toISOString();
     scheduleSave();
   }
@@ -151,6 +238,7 @@ export function createInspect(
       html: String(sel.html || '').slice(0, 4000),
       ts: new Date().toISOString(),
       v,
+      canvas_mtime: mtimeFor(file),
       ...(id ? { id, canvas: deriveCanvasSlug(file) } : {}),
     };
   }
@@ -158,6 +246,9 @@ export function createInspect(
   function setSelected(sel: SetSelectedInput) {
     if (sel == null) {
       state.selected = null;
+      // Explicit deselect clears the active canvas's parked memory too — a
+      // deliberate act, not a context loss.
+      if (state.active) delete state.selections[deriveCanvasSlug(state.active)];
     } else if (Array.isArray(sel)) {
       const enriched = sel
         .filter(
@@ -175,6 +266,22 @@ export function createInspect(
     } else {
       state.selected = null;
     }
+    // Write-through into the per-canvas memory (full payload incl. html — this
+    // IS the active canvas's rich copy). Keyed by the ACTIVE canvas, and only
+    // when the selection's own file matches it: the client gates select posts to
+    // `e.source === activeWin` (app.jsx), but an ACTIVE untrusted canvas (a peer's
+    // canvas reviewed in hub mode, DDR-054) could still claim `file: <another
+    // trusted canvas>` and plant it into that canvas's slot for later delivery to
+    // the auto-approving agent. A selection can only legitimately belong to the
+    // canvas the user is looking at, so a mismatched `file` is a cross-canvas
+    // plant — drop the write-through (attacker Finding 2 residual).
+    if (state.selected != null && state.active) {
+      const first = Array.isArray(state.selected) ? state.selected[0] : state.selected;
+      const activeSlug = deriveCanvasSlug(state.active);
+      if (first?.file && deriveCanvasSlug(first.file) === activeSlug) {
+        state.selections[activeSlug] = state.selected;
+      }
+    }
     state.last_change = new Date().toISOString();
     scheduleSave();
     ctx.bus.emit('selected', state.selected);

package/apps/studio/paths.ts

@@ -48,6 +48,38 @@ export const CLIENT_DIR: string = join(DEV_SERVER_ROOT, 'client');
 /** `<DEV_SERVER_ROOT>/dist/runtime/` — pre-built /_canvas-runtime/*.js bundles. */
 export const RUNTIME_BUNDLES_DIR: string = join(DIST_DIR, 'runtime');
 
+/**
+ * Absolute path to a bundled plugin's loadable tree (`commands/`, `agents/`,
+ * `skills/`, `hooks/`, `.claude-plugin/plugin.json`), or `null` when this layout
+ * doesn't ship it. Feeds the ACP session-scoped plugin auto-bootstrap
+ * (acp/plugin-bootstrap.ts → `_meta.claudeCode.options.plugins`, DDR-143).
+ *
+ * Resolved from DEV_SERVER_ROOT per DDR-045 (NEVER a local
+ * `dirname(fileURLToPath(import.meta.url))` — that's `/$bunfs/root` inside a
+ * compiled binary). Both the dev tree and the desktop `Resources/` bundle keep
+ * `plugins/` a sibling of `apps/studio/`, so `<root>/../../plugins/<p>` reaches
+ * it in either layout (`path.join` collapses the `..` segments):
+ *   • dev tree:            <repo>/apps/studio        → <repo>/plugins/design
+ *   • desktop Resources:   …/Resources/apps/studio   → …/Resources/plugins/design
+ *
+ * The npm tarball ships ONLY `plugins/<p>/templates` (+ dependencies.json;
+ * `plugins/flow/.claude-plugin/config.schema.json`) — NOT the plugin manifest
+ * (DDR-044 minimal surface). So we gate on `.claude-plugin/plugin.json`, not the
+ * dir: its ABSENCE under the npm-global / web-serve layout yields `null`, and
+ * the resolver skips injection there (those users have a terminal + the manual
+ * marketplace path). Only the dev tree and the staged desktop bundle carry it.
+ */
+export function pluginDirFrom(devServerRoot: string, plugin: 'design' | 'flow'): string | null {
+  const dir = join(devServerRoot, '..', '..', 'plugins', plugin);
+  return existsSync(join(dir, '.claude-plugin', 'plugin.json')) ? dir : null;
+}
+
+/** Bundled `design` plugin tree, or `null` (npm/web layout). See {@link pluginDirFrom}. */
+export const DESIGN_PLUGIN_DIR: string | null = pluginDirFrom(DEV_SERVER_ROOT, 'design');
+
+/** Bundled `flow` plugin tree, or `null` (npm/web layout). See {@link pluginDirFrom}. */
+export const FLOW_PLUGIN_DIR: string | null = pluginDirFrom(DEV_SERVER_ROOT, 'flow');
+
 /**
  * Whether we are running inside a `bun --compile` standalone binary
  * (true when `import.meta.url` resolves to bun's virtual filesystem).