@1agh/maude 0.37.0 → 0.38.0

package/apps/studio/acp/plugin-bootstrap.ts

@@ -0,0 +1,115 @@
+// ACP session-scoped plugin auto-bootstrap (DDR-143).
+//
+// A Maude Desktop user with only Claude Code installed should get `/design:*`
+// working in the chat panel with ZERO manual install — no `npm i`, no `/plugin
+// marketplace add`, no `/reload-plugins`. (`/flow:*` auto-load is intentionally
+// disabled for now — 2026-07-03 — the chat ships design-only; the plumbing below
+// stays wired so restoring flow is a one-line change in computeSessionPlugins.)
+// We achieve that by handing
+// the ACP-spawned `claude` a session-scoped local plugin dir through the same
+// `_meta` seam the bootstrap brief uses: `_meta.claudeCode.options.plugins`.
+// The adapter spreads that into the SDK `query()` options (verified live —
+// Task-1 spike: an injected local plugin's command appears in the session's
+// `available_commands_update` with no install), and the SDK loads its commands/
+// agents/skills/hooks for that session only. NOTHING is written to `~/.claude`,
+// no package manager runs, no network is touched (DDR-126/128) — it's reversible
+// and per-session by construction.
+//
+// Three gates, ALL must hold for a plugin to be injected:
+//   1. NATIVE / BUNDLE context (guard #4, DDR-119/123). The web `maude design
+//      serve` (npm) path ships no plugin manifest (DDR-044) and its users have a
+//      terminal — never inject there. The signal is the manifest's presence on
+//      disk (DESIGN_PLUGIN_DIR/FLOW_PLUGIN_DIR non-null), which is true ONLY in
+//      the desktop Resources bundle or the dev tree; plus the desktop sidecar's
+//      MAUDE_DEV_SERVER_ROOT as an explicit stricter marker.
+//   2. BUNDLED FILES present — the per-plugin dir resolved (Task 2). Null on the
+//      npm/web layout ⇒ skip that plugin.
+//   3. NO-OP for power users (guard #3, hard). If the plugin is already installed
+//      via the marketplace OR enabled in the user's settings.json, it loads
+//      NATIVELY under the adapter's `settingSources:user` — injecting the bundled
+//      copy on top would double-register commands + risk version skew. So a
+//      `scanPlugins()` hit ⇒ skip that plugin. A pristine ~/.claude (the target
+//      non-power-user) reads as not-installed ⇒ inject.
+
+import { DESIGN_PLUGIN_DIR, FLOW_PLUGIN_DIR } from '../paths.ts';
+import { type PluginScan, scanPlugins } from '../readiness.ts';
+
+/**
+ * SDK plugin-load config (`@anthropic-ai/claude-agent-sdk` `SdkPluginConfig`).
+ * Defined locally: that SDK is a TRANSITIVE dep (reached only through the
+ * adapter), so we don't import its type surface directly. Shape pinned to
+ * sdk.d.ts:3766 — an adapter/SDK bump that changes it is caught by the
+ * presence-test in test/acp-session-plugins.test.ts.
+ */
+export interface SdkPluginConfig {
+  type: 'local';
+  path: string;
+  /** The SDK host (this bridge) owns MCP connections — don't read the plugin's .mcp.json. */
+  skipMcpDiscovery?: boolean;
+}
+
+export interface SessionPluginDeps {
+  /** Desktop bundle or dev tree; false on the npm web-serve path (guard #4). */
+  native: boolean;
+  /** Bundled `design` plugin dir, or null (npm/web layout). */
+  designDir: string | null;
+  /** Bundled `flow` plugin dir, or null (npm/web layout). */
+  flowDir: string | null;
+  /** ~/.claude registry+settings scan — a present plugin loads natively (no-op). */
+  scan: Pick<PluginScan, 'design' | 'flow'>;
+}
+
+/**
+ * Pure resolver — returns the `SdkPluginConfig[]` to inject (possibly empty).
+ * Exported for unit tests; the real wiring is {@link resolveSessionPlugins}.
+ */
+export function computeSessionPlugins(deps: SessionPluginDeps): SdkPluginConfig[] {
+  if (!deps.native) return [];
+  const out: SdkPluginConfig[] = [];
+  const add = (dir: string | null, alreadyPresent: boolean): void => {
+    // dir === null → not bundled in this layout (web/npm) → skip.
+    // alreadyPresent → loads natively → skip (no double-registration / skew).
+    if (dir && !alreadyPresent) out.push({ type: 'local', path: dir, skipMcpDiscovery: true });
+  };
+  add(deps.designDir, deps.scan.design);
+  // `/flow` auto-load is intentionally OFF for now (2026-07-03) — the chat ships
+  // design-only. `deps.flowDir` / `deps.scan.flow` stay resolved (harmless) so
+  // restoring it is a one-liner: re-add `add(deps.flowDir, deps.scan.flow)`.
+  return out;
+}
+
+/**
+ * Native/bundle context — true in the packaged desktop app (sidecar sets
+ * MAUDE_DEV_SERVER_ROOT, DDR-106) OR the dev tree (a bundled plugin manifest
+ * resolves on disk, so the feature is dogfoodable without building the `.app`).
+ * False on the npm `maude design serve` path: no MAUDE_DEV_SERVER_ROOT and no
+ * staged manifest (DDR-044) ⇒ both plugin dirs null.
+ *
+ * `MAUDE_NO_PLUGIN_BOOTSTRAP=1` is a hard opt-out: it reverts to the DDR-128
+ * detect-and-guide posture (no injection, the readiness `plugins` row shows the
+ * manual marketplace remediation). For a power user who wants to force the manual
+ * path, a locked-down deployment, or test isolation.
+ */
+export function isNativePluginContext(): boolean {
+  if (process.env.MAUDE_NO_PLUGIN_BOOTSTRAP === '1') return false;
+  return (
+    !!process.env.MAUDE_DEV_SERVER_ROOT || DESIGN_PLUGIN_DIR !== null || FLOW_PLUGIN_DIR !== null
+  );
+}
+
+/**
+ * Resolve the session-scoped plugins to inject for a fresh ACP session. Wires the
+ * real deps (native context, bundled dirs, live ~/.claude scan) into
+ * {@link computeSessionPlugins}. Empty array ⇒ inject nothing (the power-user /
+ * web no-op). Recomputed per bridge construction; stable across an adapter
+ * re-spawn because it's carried on the bridge's readonly options.
+ */
+export function resolveSessionPlugins(): SdkPluginConfig[] {
+  const scan = scanPlugins();
+  return computeSessionPlugins({
+    native: isNativePluginContext(),
+    designDir: DESIGN_PLUGIN_DIR,
+    flowDir: FLOW_PLUGIN_DIR,
+    scan: { design: scan.design, flow: scan.flow },
+  });
+}

package/apps/studio/acp/transcript.ts

@@ -44,10 +44,12 @@ function readLines(file: string): Array<Record<string, unknown>> {
   }
 }
 
-/** First user line, truncated — the chat's display title. */
+/** First user line, truncated — the chat's display title. Context-attachment
+ *  lines are stripped first, so a chat never titles itself `[maude-context …`
+ *  (the 2026-07-03 dogfood finding). */
 function deriveTitle(lines: Array<Record<string, unknown>>): string {
   const firstUser = lines.find((l) => l.role === 'user' && typeof l.text === 'string');
-  const text = (firstUser?.text as string) ?? '';
+  const text = stripContextBlock((firstUser?.text as string) ?? '');
   const trimmed = text.replace(/\s+/g, ' ').trim();
   return trimmed ? trimmed.slice(0, 60) : 'New chat';
 }
@@ -85,6 +87,34 @@ export function deleteChat(designRoot: string, chatId: string): boolean {
   }
 }
 
+/**
+ * UI-projection strip of the frozen chat-context a send attaches
+ * (feature-acp-context-hardening). PROJECTION ONLY — the on-disk jsonl keeps
+ * the raw prompt (it's the audit record of what steered the auto-approving
+ * agent); the rendered bubble/title shows just what the user typed. Handles
+ * both formats: the current TRAILING `[maude-context …]` (+ `[selected: …]`)
+ * bracket lines, and the legacy leading `<maude-context>` fence (2026-07-02,
+ * one release window). `role:'bootstrap'` brief entries are skipped by this
+ * reader by construction (only user/stop/agent roles are consumed below).
+ */
+function stripContextBlock(text: string): string {
+  let out = text;
+  if (out.startsWith('<maude-context')) {
+    const end = out.indexOf('</maude-context>');
+    if (end !== -1) out = out.slice(end + '</maude-context>'.length).replace(/^\s+/, '');
+  }
+  const i = out.indexOf('\n[maude-context ');
+  if (i !== -1) {
+    const tail = out.slice(i + 1);
+    // Only strip when the remainder is EXACTLY the context block (all lines are
+    // bracket lines) — a user merely quoting `[maude-context …]` mid-text stays.
+    if (/^\[maude-context [^\n]*\](\n\[selected:[^\n]*\])*\s*$/.test(tail)) {
+      out = out.slice(0, i).replace(/\s+$/, '');
+    }
+  }
+  return out;
+}
+
 /**
  * Convert the raw transcript into clean per-turn messages: user lines become
  * user messages; the agent updates between them aggregate into one assistant
@@ -108,7 +138,10 @@ export function readChatMessages(designRoot: string, chatId: string): ChatMessag
   for (const line of lines) {
     if (line.role === 'user' && typeof line.text === 'string') {
       flush();
-      messages.push({ role: 'user', parts: [{ type: 'text', text: line.text }] });
+      messages.push({
+        role: 'user',
+        parts: [{ type: 'text', text: stripContextBlock(line.text) }],
+      });
       continue;
     }
     if (line.role === 'stop') {

package/apps/studio/activity.ts

@@ -19,6 +19,9 @@ import type { Context } from './context.ts';
 /** Idle debounce — fs silence longer than this flips a file `active` → `idle`. */
 export const ACTIVITY_IDLE_MS = 3000;
 
+/** Default user-write suppression window (see ActivityOptions.suppressTtlMs). */
+export const SUPPRESS_TTL_MS = 2500;
+
 /** LRU cap on the per-file text stash used by the Task 7 region diff. */
 const STASH_CAP = 50;
 
@@ -104,6 +107,8 @@ export interface ActivityOptions {
   idleMs?: number;
   /** Disable the Task 7 per-artboard diff (file-level only). Default: enabled. */
   diff?: boolean;
+  /** Override the user-write suppression window (tests pass a small value). */
+  suppressTtlMs?: number;
 }
 
 export function createActivity(ctx: Context, opts: ActivityOptions = {}): Activity {
@@ -114,6 +119,18 @@ export function createActivity(ctx: Context, opts: ActivityOptions = {}): Activi
   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>();
+  // Phase 12.1 — writes the USER just made through the shell (drag / keyboard
+  // reorder, inspector CSS/text/attr edits + their undo/redo) must NOT light the
+  // "editing" rim: the overlay means "an agent works here" (DDR-029), and
+  // flashing it on the user's own direct manipulation reads as interference.
+  // The write path emits `activity:suppress` with the designRoot-relative path
+  // right before writing; EVERY fs:any for that file inside the TTL window is
+  // swallowed (RC2, rca/issue-canvas-hmr-optimistic-update-consistency — the
+  // old one-shot delete let the 2nd event of a same-file write burst through:
+  // slider drags and reorder spam produce several debounced fs:any per arm).
+  // The TTL bounds the mute so a crashed write can't silence a file forever.
+  const suppressTtlMs = opts.suppressTtlMs ?? SUPPRESS_TTL_MS;
+  const suppressed = new Map<string, number>();
 
   function emit(file: string) {
     const e = state[file];
@@ -191,15 +208,43 @@ export function createActivity(ctx: Context, opts: ActivityOptions = {}): Activi
 
   const off = ctx.bus.on('fs:any', (rel: string) => {
     if (!isCanvasFile(rel)) return;
+    const until = suppressed.get(rel);
+    if (until != null) {
+      if (Date.now() < until) {
+        // User-originated write window — keep the diff baseline fresh so the
+        // NEXT (agent) edit still region-scopes correctly, but skip the rim.
+        // The entry stays armed until the TTL expires or the writer disarms.
+        if (diffEnabled) void refineArtboards(rel);
+        return;
+      }
+      suppressed.delete(rel); // expired — clean up and fall through to mark()
+    }
     mark(rel);
     if (diffEnabled) void refineArtboards(rel);
   });
 
+  const offSuppress = ctx.bus.on('activity:suppress', (rel: string) => {
+    if (typeof rel !== 'string' || !rel) return;
+    suppressed.set(rel.replace(/\\/g, '/'), Date.now() + suppressTtlMs);
+  });
+
+  // The write path arms `activity:suppress` BEFORE the write (so it catches the
+  // debounced fs:any). If the write turns out to be a no-op or throws, it disarms
+  // via this event — otherwise a failed/spam reorder would swallow the NEXT
+  // genuine (agent / synced-peer) edit's rim (adversarial F2).
+  const offUnsuppress = ctx.bus.on('activity:unsuppress', (rel: string) => {
+    if (typeof rel !== 'string' || !rel) return;
+    suppressed.delete(rel.replace(/\\/g, '/'));
+  });
+
   function stop() {
     off();
+    offSuppress();
+    offUnsuppress();
     for (const t of idleTimers.values()) clearTimeout(t);
     idleTimers.clear();
     lastText.clear();
+    suppressed.clear();
   }
 
   return { state, mark, stop };

package/apps/studio/api.ts

@@ -10,10 +10,13 @@ import { renderBriefBoard, validateCanvasName } from './canvas-create.ts';
 import {
   CanvasEditError,
   editAttribute,
+  type MovePosition,
+  moveElement,
   removeAttribute,
   editText as runEditText,
 } from './canvas-edit.ts';
 import type { Context } from './context.ts';
+import { createHistory } from './history.ts';
 
 // Directories that never hold user-facing canvases. Exported so the
 // external-canvas watcher (`canvas-list-watch.ts`) shares one source instead of
@@ -180,6 +183,21 @@ export type EditOpResult =
   | { ok: true; delta: number }
   | { ok: false; status: number; error: string };
 
+/**
+ * Phase 12.1 (DDR-138) — result of a node-move reorder. Carries the re-settle
+ * hints the client uses to re-select the moved element through the positional
+ * `data-cd-id` churn: `movedId` (recomputed positional id == the post-reload DOM
+ * id, best-effort) and `semanticId` (the moved element's `data-dc-element`, which
+ * survives the move verbatim — the reliable key when present).
+ */
+export type ReorderOpResult =
+  | { ok: true; delta: number; movedId: string | null; semanticId: string | null; seq: number }
+  | { ok: false; status: number; error: string };
+
+export type ReorderRevertResult =
+  | { ok: true; dir: 'undo' | 'redo' }
+  | { ok: false; status: number; error: string };
+
 export interface Api {
   // File tree
   fileSlug(file: string): string;
@@ -221,6 +239,9 @@ export interface Api {
   saveAnnotations(file: string, svg: string): Promise<boolean>;
   // Phase 23 — content-addressed binary image write (drag-drop / paste / picker)
   saveAsset(bytes: Uint8Array): Promise<SaveAssetResult>;
+  // Persist a clipboard-pasted ACP composer image → runtime `_chat/attachments/`,
+  // returns an absolute path (Phase 31 follow-up — POST /_api/acp/attachment).
+  saveChatAttachment(bytes: Uint8Array): Promise<SaveAssetResult>;
   // Create a blank brief board from the browser (Phase 22 — POST /_api/canvas)
   createCanvas(input: {
     name?: unknown;
@@ -248,6 +269,24 @@ export interface Api {
     attr?: unknown;
     value?: unknown;
   }): Promise<EditOpResult>;
+  // Phase 12.1 (DDR-138) — node-move reorder (POST /_api/reorder). Main-origin
+  // only. Moves the element with data-cd-id `id` to `position` relative to
+  // `refId` (reparent-capable), snapshotting pre-move for /design:rollback.
+  reorder(input: {
+    canvas?: unknown;
+    id?: unknown;
+    refId?: unknown;
+    position?: unknown;
+  }): Promise<ReorderOpResult>;
+  // Undo/redo a prior reorder by seq (Cmd+Z from the canvas undo stack). Whole-
+  // file content swap from the in-memory revert log — immune to the positional
+  // data-cd-id churn a reorder causes (inverse-descriptor undo would go stale).
+  // Refuses (409) when the canvas changed since the reorder (external edit).
+  reorderRevert(input: {
+    canvas?: unknown;
+    seq?: unknown;
+    dir?: unknown;
+  }): Promise<ReorderRevertResult>;
   // Aggregate data
   buildIndexData(): Promise<unknown>;
   buildSystemData(dsName?: string | null): Promise<unknown>;
@@ -355,6 +394,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   const onAnnotationsChanged = hooks.onAnnotationsChanged;
   const { paths, cfg } = ctx;
 
+  // Phase 12.1 — in-memory reorder revert log (Cmd+Z for drag/keyboard moves).
+  // Whole-file {before, after} per reorder, keyed by a monotonic seq the client
+  // stores in its undo record. Ephemeral by design: a server restart drops it
+  // (undo answers 404 and the canvas stack entry is a no-op, honest failure).
+  const REORDER_LOG_CAP = 50;
+  const reorderLog = new Map<number, { abs: string; before: string; after: string }>();
+  let reorderSeq = 0;
+
   function fileSlug(file: string): string {
     return canvasSlugFromRel(file, paths.designRel);
   }
@@ -984,6 +1031,56 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return { ok: true, path: `assets/${name}` };
   }
 
+  // Phase 31 follow-up — persist an image pasted straight from the clipboard into
+  // the ACP composer (a screenshot has no path yet), so the chip can point Claude
+  // at a real file to Read. Sibling of saveAsset, but:
+  //   • writes under the RUNTIME `_chat/attachments/` (gitignored — DDR-115), not
+  //     the versioned `assets/`; pasted screenshots are ephemeral, not canvas media.
+  //   • returns an ABSOLUTE path — Claude runs with its own cwd, so a project-
+  //     relative string could miss; an absolute path always resolves.
+  // Same load-bearing caps as saveAsset (magic-byte sniff → no SVG/script, 10 MB,
+  // content-addressed name, shared session write budget). MAIN-ORIGIN ONLY at the
+  // route layer (the untrusted canvas can't reach it).
+  async function saveChatAttachment(bytes: Uint8Array): Promise<SaveAssetResult> {
+    if (!bytes || bytes.length === 0) return { ok: false, status: 400, error: 'empty body' };
+    if (bytes.length > ASSET_MAX_BYTES) {
+      return { ok: false, status: 413, error: 'attachment exceeds the 10 MB cap' };
+    }
+    const kind = sniffImageType(bytes);
+    if (!kind) {
+      return {
+        ok: false,
+        status: 415,
+        error: 'unsupported image type — png/jpeg/gif/webp only (SVG rejected)',
+      };
+    }
+    const sha8 = crypto.createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+    const name = `${sha8}.${kind}`;
+    const dir = path.join(paths.designRoot, '_chat', 'attachments');
+    const fileAbs = path.join(dir, name);
+    // Containment backstop — the name is content-addressed (no user input), assert anyway.
+    if (path.resolve(fileAbs) !== path.join(path.resolve(dir), name)) {
+      return { ok: false, status: 400, error: 'resolved attachment path escapes _chat dir' };
+    }
+    try {
+      if (!(await Bun.file(fileAbs).exists())) {
+        if (assetBytesWritten + bytes.length > ASSET_SESSION_BUDGET) {
+          return {
+            ok: false,
+            status: 429,
+            error: 'asset write budget exceeded for this server session',
+          };
+        }
+        await mkdir(dir, { recursive: true });
+        await Bun.write(fileAbs, bytes);
+        assetBytesWritten += bytes.length;
+      }
+    } catch (err) {
+      return { ok: false, status: 500, error: err instanceof Error ? err.message : 'write failed' };
+    }
+    return { ok: true, path: fileAbs };
+  }
+
   // Phase 22 — create a blank brief board from the browser file tree. Wired ONLY
   // on the main origin (server.ts startMainServer); the segregated canvas origin
   // (DDR-054) never exposes this — an untrusted canvas iframe must not be able to
@@ -1242,6 +1339,36 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   // 8-hex lowercase, the shape `computeId` (canvas-edit.ts) stamps on data-cd-id.
   const CD_ID_RE = /^[0-9a-f]{8}$/;
 
+  // RC1 (rca/issue-canvas-hmr-optimistic-update-consistency) — every inline
+  // edit is USER-originated (inspector CSS knobs, inline text, attr panel, and
+  // their undo/redo which re-POST the same endpoints), so it must not light the
+  // "agent works here" rim. Mirror the reorder pattern (below): arm the
+  // suppression BEFORE the write so it catches the debounced fs:any, disarm on
+  // a no-op (delta 0 = no write) or throw so a failed edit can't mute the next
+  // genuine agent edit's rim.
+  async function suppressedEdit(
+    abs: string,
+    run: () => Promise<{ delta: number; changed?: boolean }>,
+    errLabel: string
+  ): Promise<EditOpResult> {
+    const rel = path.relative(paths.designRoot, abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const res = await run();
+      // `changed === false` = the op collapsed to a no-op and nothing hit disk —
+      // NOT `delta === 0`, which an equal-length replacement also produces.
+      if (res.changed === false) ctx.bus.emit('activity:unsuppress', rel);
+      return { ok: true, delta: res.delta };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: 422,
+        error: err instanceof CanvasEditError ? err.message : errLabel,
+      };
+    }
+  }
+
   async function editCss(input: {
     canvas?: unknown;
     id?: unknown;
@@ -1265,16 +1392,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // Phase 12.3 — `reset: true` REMOVES the inline property (back to class /
     // inherited). No value needed; a missing key is a no-op (delta 0).
     if (input.reset === true) {
-      try {
-        const res = await removeAttribute(r.abs, id, `style.${camel}`);
-        return { ok: true, delta: res.delta };
-      } catch (err) {
-        return {
-          ok: false,
-          status: 422,
-          error: err instanceof CanvasEditError ? err.message : 'reset failed',
-        };
-      }
+      return suppressedEdit(
+        r.abs,
+        () => removeAttribute(r.abs, id, `style.${camel}`),
+        'reset failed'
+      );
     }
     const value = typeof input.value === 'string' ? input.value : '';
     if (!value.trim()) return { ok: false, status: 400, error: 'value required' };
@@ -1283,16 +1405,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // quotes/backslashes/newlines so it can never break out of the string, and
     // React accepts string values for every style prop — so `var(--accent)`,
     // `#fff`, `8px`, `700`, `1.5` all ride verbatim.
-    try {
-      const res = await editAttribute(r.abs, id, `style.${camel}`, JSON.stringify(value));
-      return { ok: true, delta: res.delta };
-    } catch (err) {
-      return {
-        ok: false,
-        status: 422,
-        error: err instanceof CanvasEditError ? err.message : 'edit failed',
-      };
-    }
+    return suppressedEdit(
+      r.abs,
+      () => editAttribute(r.abs, id, `style.${camel}`, JSON.stringify(value)),
+      'edit failed'
+    );
   }
 
   async function editText(input: {
@@ -1306,16 +1423,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
     if (typeof input.text !== 'string') return { ok: false, status: 400, error: 'text required' };
     if (input.text.length > 5000) return { ok: false, status: 413, error: 'text too long' };
-    try {
-      const res = await runEditText(r.abs, id, input.text);
-      return { ok: true, delta: res.delta };
-    } catch (err) {
-      return {
-        ok: false,
-        status: 422,
-        error: err instanceof CanvasEditError ? err.message : 'edit failed',
-      };
-    }
+    const text = input.text;
+    return suppressedEdit(r.abs, () => runEditText(r.abs, id, text), 'edit failed');
   }
 
   async function editAttr(input: {
@@ -1344,36 +1453,142 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
     // Phase 12.3 — `reset: true` REMOVES the custom attribute. No-op if absent.
     if (input.reset === true) {
-      try {
-        const res = await removeAttribute(r.abs, id, attr);
-        return { ok: true, delta: res.delta };
-      } catch (err) {
-        return {
-          ok: false,
-          status: 422,
-          error: err instanceof CanvasEditError ? err.message : 'reset failed',
-        };
-      }
+      return suppressedEdit(r.abs, () => removeAttribute(r.abs, id, attr), 'reset failed');
     }
     const value = typeof input.value === 'string' ? input.value : '';
     if (!value.trim()) return { ok: false, status: 400, error: 'value required' };
     if (value.length > 256) return { ok: false, status: 413, error: 'value too long' };
+    // Non-`style.` attr name → editAttribute writes a plain quoted JSX attribute.
+    // Pass the value RAW: editStringAttr quotes/escapes it itself (JSON.stringify
+    // on replace, escapeAttr on insert) — pre-stringifying here double-encoded
+    // the value (`data-x="\"ok\""`; knob-smoke finding, 2026-06-12).
+    return suppressedEdit(r.abs, () => editAttribute(r.abs, id, attr, value), 'edit failed');
+  }
+
+  // Phase 12.1 (DDR-138) — snapshot stack so a reorder is undoable via
+  // /design:rollback (a positional move has no value-inverse the edit-source
+  // undo command can re-apply, so it rides `_history` instead).
+  const history = createHistory(ctx);
+
+  const MOVE_POSITIONS = new Set(['before', 'after', 'inside-start', 'inside-end']);
+
+  async function reorder(input: {
+    canvas?: unknown;
+    id?: unknown;
+    refId?: unknown;
+    position?: unknown;
+    idIndex?: unknown;
+    refIndex?: unknown;
+  }): Promise<ReorderOpResult> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    const refId = typeof input.refId === 'string' ? input.refId.trim() : '';
+    if (!CD_ID_RE.test(refId)) {
+      return { ok: false, status: 400, error: 'invalid reference data-cd-id' };
+    }
+    const position = input.position;
+    if (typeof position !== 'string' || !MOVE_POSITIONS.has(position)) {
+      return { ok: false, status: 400, error: 'invalid position' };
+    }
+    // Occurrence index of a reused-component instance (which rendered copy). 0/absent
+    // for a normal element; moveElement maps it to the parent USAGE.
+    const idIndex = Number.isInteger(input.idIndex) ? (input.idIndex as number) : undefined;
+    const refIndex = Number.isInteger(input.refIndex) ? (input.refIndex as number) : undefined;
+    // A same-id move CAN be valid now: two instances of the same reused component
+    // resolve to DIFFERENT usage elements. Only bail when they're the same instance.
+    if (id === refId && (idIndex ?? 0) === (refIndex ?? 0)) {
+      return { ok: false, status: 422, error: 'cannot move an element relative to itself' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    // Arm the "user did this — don't light the agent-editing rim" suppression
+    // BEFORE the write so it catches the debounced fs:any. It's disarmed below if
+    // the move turns out to be a no-op or throws (adversarial F2 — else a
+    // failed/spam reorder would swallow the next genuine edit's rim).
+    ctx.bus.emit('activity:suppress', rel);
     try {
-      // Non-`style.` attr name → editAttribute writes a plain quoted JSX attribute.
-      // Pass the value RAW: editStringAttr quotes/escapes it itself (JSON.stringify
-      // on replace, escapeAttr on insert) — pre-stringifying here double-encoded
-      // the value (`data-x="\"ok\""`; knob-smoke finding, 2026-06-12).
-      const res = await editAttribute(r.abs, id, attr, value);
-      return { ok: true, delta: res.delta };
+      const before = await Bun.file(r.abs).text();
+      const res = await moveElement(r.abs, id, refId, position as MovePosition, idIndex, refIndex);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        // No-op move (the reparse-clean edit collapsed to the same source) — no
+        // write happened, so disarm the rim suppression and DON'T snapshot/log
+        // (adversarial F2 + F3: never deposit a _history blob for a non-write).
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, delta: 0, movedId: res.movedId, semanticId: res.semanticId, seq: 0 };
+      }
+      // A real write landed. Snapshot the pre-move source for /design:rollback
+      // (RELATIVE path → `_history/<slug>/`; the absolute path would mangle the
+      // slug slug.sh can't find) — best-effort. Log {before, after} under a seq so
+      // Cmd+Z can revert by whole-file swap (inverse descriptors go stale as
+      // positional ids churn).
+      try {
+        await history.writeSnapshot(rel, before, 'pre-reorder');
+      } catch {
+        /* snapshot is a safety net, not a gate */
+      }
+      const seq = ++reorderSeq;
+      reorderLog.set(seq, { abs: r.abs, before, after });
+      while (reorderLog.size > REORDER_LOG_CAP) {
+        const oldest = reorderLog.keys().next().value;
+        if (oldest === undefined) break;
+        reorderLog.delete(oldest);
+      }
+      return { ok: true, delta: res.delta, movedId: res.movedId, semanticId: res.semanticId, seq };
     } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel); // move threw, no write — disarm
       return {
         ok: false,
         status: 422,
-        error: err instanceof CanvasEditError ? err.message : 'edit failed',
+        error: err instanceof CanvasEditError ? err.message : 'reorder failed',
       };
     }
   }
 
+  async function reorderRevert(input: {
+    canvas?: unknown;
+    seq?: unknown;
+    dir?: unknown;
+  }): Promise<ReorderRevertResult> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const dir = input.dir;
+    if (dir !== 'undo' && dir !== 'redo') return { ok: false, status: 400, error: 'invalid dir' };
+    const seq = typeof input.seq === 'number' ? input.seq : Number.NaN;
+    const entry = Number.isInteger(seq) ? reorderLog.get(seq) : undefined;
+    if (!entry || entry.abs !== r.abs) {
+      return {
+        ok: false,
+        status: 404,
+        error: 'reorder not found (server restarted or log rotated)',
+      };
+    }
+    try {
+      const current = await Bun.file(r.abs).text();
+      const expect = dir === 'undo' ? entry.after : entry.before;
+      const write = dir === 'undo' ? entry.before : entry.after;
+      if (current !== expect) {
+        return {
+          ok: false,
+          status: 409,
+          error: 'canvas changed since this reorder — undo skipped',
+        };
+      }
+      const rel = path.relative(paths.designRoot, r.abs);
+      ctx.bus.emit('activity:suppress', rel);
+      try {
+        await Bun.write(r.abs, write);
+      } catch (e) {
+        ctx.bus.emit('activity:unsuppress', rel); // write failed — disarm the rim suppression
+        throw e;
+      }
+      return { ok: true, dir };
+    } catch {
+      return { ok: false, status: 500, error: 'revert failed' };
+    }
+  }
+
   async function saveCanvasState(file: string, state: Record<string, unknown>) {
     if (!state || typeof state !== 'object') return;
     const safe: Record<string, unknown> = {};
@@ -1778,11 +1993,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     loadAnnotations,
     saveAnnotations,
     saveAsset,
+    saveChatAttachment,
     createCanvas,
     deleteCanvas,
     editCss,
     editText,
     editAttr,
+    reorder,
+    reorderRevert,
     buildIndexData,
     buildSystemData,
     loadExportHistory,