@1agh/maude 0.43.0 → 0.44.0

package/apps/studio/test/media-commit-chain.test.ts

@@ -0,0 +1,210 @@
+// media-commit-chain — the Phase-23 batch-drop no-loss guarantee, isolated
+// from React/DOM/real image decode timing so the race is testable
+// deterministically (no real timers — every "completion" is a microtask-tick
+// count, so the interleaving is exact and reproducible on every run).
+
+import { describe, expect, test } from 'bun:test';
+
+import { createMediaCommitChain } from '../media-commit-chain.ts';
+
+interface Item {
+  id: string;
+}
+
+const keyOf = (it: Item) => it.id;
+
+/** Resolve after exactly `n` microtask ticks (0 = next tick). */
+function afterTicks(n: number): Promise<void> {
+  let p: Promise<void> = Promise.resolve();
+  for (let i = 0; i < n; i++) p = p.then(() => undefined);
+  return p;
+}
+
+describe('media-commit-chain / no-loss under concurrent completions', () => {
+  test('a synchronous burst of N enqueues (worst case — zero timing gap) keeps all N', async () => {
+    let snapshot: Item[] = [];
+    const chain = createMediaCommitChain<Item>(() => snapshot, keyOf);
+    const committed: Item[][] = [];
+    const onCommit = (_before: readonly Item[], after: readonly Item[]) => {
+      committed.push(after as Item[]);
+      snapshot = after as Item[];
+    };
+
+    // All 8 fire back-to-back in the same synchronous tick — the exact shape
+    // of use-canvas-media-drop's batch-dispatch loop calling onImage/onMedia
+    // once per file, each kicking off its own independent async chain that
+    // (in the old, buggy code) raced on a shared strokesRef.current read.
+    const promises = Array.from({ length: 8 }, (_, i) =>
+      chain.enqueue(
+        (before) => ({ after: [...before, { id: `item-${i}` }], label: `add ${i}` }),
+        onCommit
+      )
+    );
+    await Promise.all(promises);
+
+    const final = committed[committed.length - 1];
+    expect(final.length).toBe(8);
+    expect(new Set(final.map((it) => it.id)).size).toBe(8);
+    for (let i = 0; i < 8; i++) {
+      expect(final.some((it) => it.id === `item-${i}`)).toBe(true);
+    }
+  });
+
+  test('staggered/shuffled resolution order still accumulates every item exactly once', async () => {
+    let snapshot: Item[] = [];
+    const chain = createMediaCommitChain<Item>(() => snapshot, keyOf);
+    const committed: Item[][] = [];
+    const onCommit = (_before: readonly Item[], after: readonly Item[]) => {
+      committed.push(after as Item[]);
+      snapshot = after as Item[];
+    };
+
+    // A fixed (non-random, so non-flaky) permutation of tick-depths — some
+    // items resolve in the same tick as others, some land in between,
+    // deliberately out of index order (index 4 resolves before index 0).
+    const tickCounts = [4, 0, 6, 2, 7, 1, 5, 3];
+    const promises = tickCounts.map((ticks, i) =>
+      afterTicks(ticks).then(() =>
+        chain.enqueue(
+          (before) => ({ after: [...before, { id: `item-${i}` }], label: `add ${i}` }),
+          onCommit
+        )
+      )
+    );
+    await Promise.all(promises);
+
+    const final = committed[committed.length - 1];
+    expect(final.length).toBe(8);
+    expect(new Set(final.map((it) => it.id)).size).toBe(8);
+  });
+
+  test('skip (mutate returns null) leaves the accumulator untouched', async () => {
+    let snapshot: Item[] = [];
+    const chain = createMediaCommitChain<Item>(() => snapshot, keyOf);
+    const committed: Item[][] = [];
+    const onCommit = (_before: readonly Item[], after: readonly Item[]) => {
+      committed.push(after as Item[]);
+      snapshot = after as Item[];
+    };
+
+    await chain.enqueue((before) => ({ after: [...before, { id: 'a' }] }), onCommit);
+    const skipped = await chain.enqueue(() => null, onCommit);
+    expect(skipped.map((it) => it.id)).toEqual(['a']);
+    expect(committed.length).toBe(1); // the skipped mutation never called onCommit
+  });
+
+  test('a lagging snapshot (render has not caught up yet) does not lose the prior commit', async () => {
+    // This is the regression caught live against a real dev server (Task 5):
+    // getSnapshot() (strokesRef.current in production) only catches up on
+    // React's NEXT render, which can take longer than the handful of
+    // microtask ticks this chain itself needs to settle a link and go idle.
+    // `rendered` here deliberately never updates on its own — it models a
+    // render that hasn't happened yet by the time the second file's upload
+    // resolves and enqueues.
+    const rendered: Item[] = [];
+    const chain = createMediaCommitChain<Item>(() => rendered, keyOf);
+    const commits: Array<{ after: readonly Item[] }> = [];
+    const onCommit = (_before: readonly Item[], after: readonly Item[]) => {
+      commits.push({ after });
+    };
+
+    await chain.enqueue((before) => ({ after: [...before, { id: 'video' }] }), onCommit);
+    // The chain is idle now (its one link has settled) — `rendered` is still
+    // [] (no render happened). The next enqueue must reconcile against what
+    // THIS chain last produced, not trust the stale empty snapshot.
+    const after = await chain.enqueue(
+      (before) => ({ after: [...before, { id: 'audio' }] }),
+      onCommit
+    );
+
+    expect(after.map((it) => it.id).sort()).toEqual(['audio', 'video']);
+  });
+
+  test('external edits made while idle (snapshot ahead of remembered) are preserved', async () => {
+    let snapshot: Item[] = [{ id: 'external' }];
+    const chain = createMediaCommitChain<Item>(() => snapshot, keyOf);
+    const commits: Array<{ before: readonly Item[]; after: readonly Item[] }> = [];
+    const onCommit = (before: readonly Item[], after: readonly Item[]) => {
+      commits.push({ before, after });
+    };
+
+    await chain.enqueue((before) => ({ after: [...before, { id: 'a' }] }), onCommit);
+    // Simulate a synchronous, non-chained edit that landed while idle (e.g. a
+    // pen stroke committed directly, its render already caught up) — the
+    // next chain link must see it via the fresh snapshot.
+    snapshot = [...snapshot, { id: 'a' }, { id: 'pen-stroke' }];
+    await chain.enqueue((before) => ({ after: [...before, { id: 'b' }] }), onCommit);
+
+    const last = commits[commits.length - 1];
+    expect(last.after.some((it) => it.id === 'pen-stroke')).toBe(true);
+    expect(last.after.some((it) => it.id === 'b')).toBe(true);
+  });
+
+  test('a snapshot with a STALE VALUE for a chain-owned id (not just a missing one) does not revert it', async () => {
+    // The real bug this closes: `fresh` (getSnapshot) can contain the SAME
+    // id the chain just committed, but with a stale value — e.g. an image
+    // stroke's optimistic (blob:) href is set via a separate, non-chain
+    // setState, and `fresh` catches up to THAT before it catches up to the
+    // chain's own later commit swapping it to the real href. Checking only
+    // "is the id present" (the previous implementation) treated this as
+    // "already rendered, trust fresh" and used the stale copy — silently
+    // reverting the swap, which then gets filtered out entirely as
+    // still-ephemeral at the persistence layer one level up. Confirmed live
+    // against a real dev server: a single 3-file drop lost exactly one file
+    // most of the time, always the one whose swap commit landed while
+    // `fresh` still only reflected its pre-swap optimistic value.
+    const snapshot: Item[] = [{ id: 'img-optimistic', href: 'blob:x' } as unknown as Item];
+    const chain = createMediaCommitChain<Item>(() => snapshot, keyOf);
+    const commits: Array<{ after: readonly Item[] }> = [];
+    const onCommit = (_before: readonly Item[], after: readonly Item[]) => {
+      commits.push({ after });
+    };
+
+    // The chain's own commit swaps the id to its real value...
+    await chain.enqueue(
+      (before) => ({
+        after: before.map((it) =>
+          it.id === 'img-optimistic' ? { ...it, href: 'assets/real.png' } : it
+        ),
+      }),
+      onCommit
+    );
+    // ...but `snapshot` (fresh) hasn't re-rendered to reflect that swap yet
+    // — it still shows the SAME id with the stale, optimistic href. This
+    // models the render lag, not a delete/re-add.
+
+    const after = await chain.enqueue(
+      (before) => ({ after: [...before, { id: 'sibling' }] }),
+      onCommit
+    );
+
+    const img = after.find((it) => it.id === 'img-optimistic') as unknown as { href: string };
+    expect(img?.href).toBe('assets/real.png');
+    expect(after.some((it) => it.id === 'sibling')).toBe(true);
+  });
+
+  test('commitBefore overrides the before passed to onCommit without affecting the accumulator', async () => {
+    const snapshot: Item[] = [{ id: 'optimistic' }];
+    const chain = createMediaCommitChain<Item>(() => snapshot, keyOf);
+    const commits: Array<{ before: readonly Item[]; after: readonly Item[] }> = [];
+    const onCommit = (before: readonly Item[], after: readonly Item[]) => {
+      commits.push({ before, after });
+    };
+
+    // Mirrors createImageFromFile's swap: "before" (accumulator) still
+    // contains the ephemeral optimistic entry, but the undo record's
+    // `before` should exclude it (undo removes the image outright instead
+    // of restoring a revoked blob: URL).
+    const after = await chain.enqueue(
+      (before) => ({
+        after: before.map((it) => (it.id === 'optimistic' ? { id: 'real' } : it)),
+        commitBefore: before.filter((it) => it.id !== 'optimistic'),
+      }),
+      onCommit
+    );
+
+    expect(after).toEqual([{ id: 'real' }]);
+    expect(commits[0].before).toEqual([]);
+    expect(commits[0].after).toEqual([{ id: 'real' }]);
+  });
+});

package/apps/studio/test/photo-bg-remove-validation.test.ts

@@ -0,0 +1,71 @@
+// photo-bg-remove.sh --asset validation — fix-photo-editor-followup-debt Task
+// 21. Drives the real bash script as a subprocess (mirrors annotate-write.test.ts's
+// spawn-a-bin pattern) against a temp design root, asserting the strict
+// `assets/<sha8>.<ext>` shape check (Task 1) rejects path traversal and
+// injection-shaped values with exit 2, while a well-formed reference proceeds
+// PAST validation (a missing on-disk asset then fails for a different, later
+// reason — exit 1 — proving the regex, not the filesystem check, isn't what
+// stopped it).
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const BIN = new URL('../bin/photo-bg-remove.sh', import.meta.url).pathname;
+
+let root: string;
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), 'photo-bg-remove-test-'));
+  mkdirSync(join(root, '.design'), { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+function run(asset: string): { code: number; err: string } {
+  const proc = Bun.spawnSync(['bash', BIN, '--asset', asset, '--root', root]);
+  return {
+    code: proc.exitCode,
+    err: new TextDecoder().decode(proc.stderr),
+  };
+}
+
+describe('photo-bg-remove.sh --asset validation', () => {
+  test('rejects path traversal', () => {
+    const res = run('assets/../../../etc/passwd');
+    expect(res.code).toBe(2);
+    expect(res.err).toContain('must look like assets/<sha8>.<ext>');
+  });
+
+  test('rejects an injection-shaped value (quotes/braces breaking out of the JSX splice)', () => {
+    const res = run('assets/aaaaaaaa.png" }; alert(1); ({ "y.png');
+    expect(res.code).toBe(2);
+  });
+
+  test('rejects backtick-embedded values', () => {
+    const res = run('assets/aaaaaaaa$(whoami).png');
+    expect(res.code).toBe(2);
+  });
+
+  test('rejects uppercase hex (sha8 is always lowercase in this codebase)', () => {
+    const res = run('assets/DEADBEEF.png');
+    expect(res.code).toBe(2);
+  });
+
+  test('rejects a bare prefix with no hex body', () => {
+    const res = run('assets/');
+    expect(res.code).toBe(2);
+  });
+
+  test('a well-formed reference proceeds past validation (fails later, not with exit 2)', () => {
+    const res = run('assets/deadbeef.png');
+    expect(res.code).not.toBe(2);
+    // No asset on disk under this temp root — fails at the existence check
+    // (exit 1), proving the regex accepted the shape and let it through.
+    expect(res.code).toBe(1);
+    expect(res.err).toContain('asset not found');
+  });
+});

package/apps/studio/test/readiness.test.ts

@@ -107,33 +107,35 @@ describe('readiness — plugin registry scan (web / manual path)', () => {
   });
 });
 
-// DDR-143 — on the native/desktop path the ACP session auto-loads the bundled
-// plugins, so the row is satisfied even against a pristine registry. This suite
-// runs in the dev tree, so the bundled plugin dirs resolve → native context is
-// on by default (no opt-out).
-describe('readiness — plugin auto-bootstrap (native, DDR-143)', () => {
-  test('pristine registry → present + "Auto-loaded" detail, no manual remediation', async () => {
+// DDR-143 / DDR-168 — on the native/desktop path the ACP session ALWAYS loads
+// the bundled plugins, so the row is satisfied even against a pristine
+// registry, AND even when a marketplace copy is also installed at the user
+// level (DDR-168 removed the old scan-gated no-op — the bundled copy wins
+// regardless of disk state). This suite runs in the dev tree, so the bundled
+// plugin dirs resolve → native context is on by default (no opt-out).
+describe('readiness — plugin auto-bootstrap (native, DDR-143/DDR-168)', () => {
+  test('pristine registry → present + "Bundled with this app" detail, no manual remediation', async () => {
     const item = await pluginsItem(fixtureClaudeDir({}));
     expect(item.status).toBe('present');
-    expect(item.detail).toContain('Auto-loaded');
+    expect(item.detail).toContain('Bundled with this app');
     expect(item.remediation).toBeUndefined();
   });
 
-  test('design NOT installed (flow-only registry) → still present (design is auto-loaded, no red wall)', async () => {
+  test('design NOT installed (flow-only registry) → still present (design is bundled, no red wall)', async () => {
     const item = await pluginsItem(
       fixtureClaudeDir({ markets: MARKET_OK, installed: INSTALLED_FLOW_ONLY })
     );
     expect(item.status).toBe('present');
-    expect(item.detail).toContain('Auto-loaded');
+    expect(item.detail).toContain('Bundled with this app');
     expect(item.remediation).toBeUndefined();
   });
 
-  test('design already installed → present, keeps the "is installed" detail (no auto-load framing)', async () => {
+  test('design ALSO installed on disk → present, STILL reads as bundled (DDR-168 — no more "is installed" framing)', async () => {
     const item = await pluginsItem(
       fixtureClaudeDir({ markets: MARKET_OK, installed: INSTALLED_DESIGN_ONLY })
     );
     expect(item.status).toBe('present');
-    expect(item.detail).toContain('installed');
+    expect(item.detail).toContain('Bundled with this app');
   });
 });
 

package/apps/studio/test/scaffold-design.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { scaffoldDesign } from '../scaffold-design.ts';
+
+// DDR-166 Phase 1 — scaffoldDesign() now seeds THREE canvases (Welcome +
+// the two onboarding reference canvases), embedded as escaped template
+// literals. A bug in that escaping (an unescaped backtick/${ from the
+// source .design/ui/*.tsx files) would silently truncate the written file
+// into broken JS at scaffold time — every future new project would boot to
+// a corrupt canvas. Exercise the REAL function against a REAL temp dir, not
+// a mock, so a truncation shows up as a parse failure below.
+describe('scaffoldDesign — onboarding canvas seeding', () => {
+  function scaffold() {
+    const dir = mkdtempSync(join(tmpdir(), 'maude-scaffold-test-'));
+    const result = scaffoldDesign(dir, 'Scaffold Test');
+    return { dir, result };
+  }
+
+  test('writes ok:true and all three seeded canvases + their meta sidecars', () => {
+    const { dir, result } = scaffold();
+    try {
+      expect(result.ok).toBe(true);
+      for (const name of ['Welcome', 'How to use Maude', 'How to make video']) {
+        expect(existsSync(join(dir, '.design', 'ui', `${name}.tsx`))).toBe(true);
+        expect(existsSync(join(dir, '.design', 'ui', `${name}.meta.json`))).toBe(true);
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('the two onboarding canvases are non-trivially sized (catches a silent truncation)', () => {
+    const { dir } = scaffold();
+    try {
+      const useMaude = readFileSync(join(dir, '.design', 'ui', 'How to use Maude.tsx'), 'utf8');
+      const makeVideo = readFileSync(join(dir, '.design', 'ui', 'How to make video.tsx'), 'utf8');
+      // Real sizes are ~30KB/~24KB; a truncated-at-the-first-unescaped-backtick
+      // bug would cut this down to a few hundred bytes at most.
+      expect(useMaude.length).toBeGreaterThan(10_000);
+      expect(makeVideo.length).toBeGreaterThan(10_000);
+      // Both files must close their own template structure — the default
+      // export is the last thing in each source file.
+      expect(useMaude.trim().endsWith('}')).toBe(true);
+      expect(makeVideo.trim().endsWith('}')).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('every seeded .tsx parses as valid TSX (Bun.Transpiler) and has exactly one default export', () => {
+    const { dir } = scaffold();
+    try {
+      const transpiler = new Bun.Transpiler({ loader: 'tsx' });
+      for (const name of ['Welcome', 'How to use Maude', 'How to make video']) {
+        const src = readFileSync(join(dir, '.design', 'ui', `${name}.tsx`), 'utf8');
+        expect(() => transpiler.transformSync(src)).not.toThrow();
+        expect(src).toMatch(/export default function \w+/);
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('every seeded meta.json is valid JSON with a matching artboards list', () => {
+    const { dir } = scaffold();
+    try {
+      // Welcome's meta nests artboards under sections[0] (the older, still-live
+      // convention); the two onboarding canvases use a top-level `artboards`.
+      const welcome = JSON.parse(
+        readFileSync(join(dir, '.design', 'ui', 'Welcome.meta.json'), 'utf8')
+      );
+      expect(welcome.sections[0].artboards.length).toBe(1);
+      for (const [name, count] of [
+        ['How to use Maude', 10],
+        ['How to make video', 7],
+      ] as const) {
+        const meta = JSON.parse(
+          readFileSync(join(dir, '.design', 'ui', `${name}.meta.json`), 'utf8')
+        );
+        expect(Array.isArray(meta.artboards)).toBe(true);
+        expect(meta.artboards.length).toBe(count);
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('the two onboarding canvases self-declare their own tokens — no system/maude/ import', () => {
+    // Real bug caught while authoring this feature: the canvases originally
+    // imported system/maude/colors_and_type.css + preview/_components.css,
+    // which do NOT exist on a brand-new project (system/ is empty until
+    // /design:setup-ds runs) — every var(--token) would resolve to nothing,
+    // silently rendering unstyled black-on-black. Assert the fix holds.
+    const { dir } = scaffold();
+    try {
+      for (const name of ['How to use Maude', 'How to make video']) {
+        const src = readFileSync(join(dir, '.design', 'ui', `${name}.tsx`), 'utf8');
+        // Check for the actual import STATEMENT, not just the path appearing
+        // in an explanatory doc comment (which legitimately mentions it).
+        expect(src).not.toContain('import "../system/maude');
+        // The self-contained token block must still be present.
+        expect(src).toContain('const TOKENS');
+        expect(src).toContain('--bg-0');
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('refuses to clobber an existing project (existing behavior, unchanged)', () => {
+    const { dir } = scaffold();
+    try {
+      const second = scaffoldDesign(dir, 'Scaffold Test');
+      expect(second.ok).toBe(false);
+      expect(second.error).toMatch(/already a Maude project/i);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/apps/studio/test/tour-overlay.test.tsx

@@ -8,6 +8,7 @@
 import { describe, expect, test } from 'bun:test';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { TourOverlay } from '../client/tour/overlay.jsx';
+import { QUICK_SETUP_TOUR } from '../client/tour/quick-setup-tour.js';
 
 const STEP = { target: '.x', title: 'Welcome', body: 'Body copy here' };
 
@@ -61,6 +62,21 @@ describe('TourOverlay', () => {
     expect(html).toContain('Working together');
   });
 
+  test('QUICK_SETUP_TOUR (DDR-166 plan, Phase 2 / T7) is a well-formed, renderable deck', () => {
+    expect(QUICK_SETUP_TOUR.length).toBeGreaterThan(1);
+    for (const step of QUICK_SETUP_TOUR) {
+      expect(typeof step.title).toBe('string');
+      expect(step.title.length).toBeGreaterThan(0);
+      expect(typeof step.body).toBe('string');
+      expect(step.body.length).toBeGreaterThan(0);
+    }
+    const html = renderToStaticMarkup(
+      <TourOverlay open steps={QUICK_SETUP_TOUR} onClose={() => {}} onComplete={() => {}} />
+    );
+    expect(html).toContain('mdcc-tour__title');
+    expect(html).toContain(`1 / ${QUICK_SETUP_TOUR.length}`);
+  });
+
   test('closed or empty renders nothing', () => {
     expect(
       renderToStaticMarkup(

package/apps/studio/tool-palette.tsx

@@ -360,16 +360,21 @@ export function ToolPalette() {
   // artboard itself (`resolveInsertAnchor`). Same request verbs the
   // context-menu's per-element "Insert ▸ …" already posts (`insert-request` /
   // `insert-image-request`, main-origin shell WRITES — DDR-054), extended with
-  // an `artboardId` field for the fallback case; a null anchor (no artboard on
-  // canvas at all) is still a no-op — nothing to insert into.
+  // an `artboardId` field for the fallback case; a null anchor is still a
+  // no-op for div/text (nothing to insert into) but NOT for image —
+  // feature-bulk-media-insert still posts `insert-image-request` with no
+  // refId/artboardId, so an artboard-less canvas opens the picker (in
+  // annotation-only mode, Task 7) instead of silently doing nothing.
   const insertViaPalette = (kind: 'div' | 'text' | 'image') => {
     setInsertOpen(false);
     const anchor = resolveInsertAnchor();
-    if (!anchor) return;
+    if (!anchor && kind !== 'image') return;
     const anchorFields =
-      'artboardId' in anchor
-        ? { artboardId: anchor.artboardId, position: anchor.position }
-        : { refId: anchor.refId, position: anchor.position };
+      anchor == null
+        ? {}
+        : 'artboardId' in anchor
+          ? { artboardId: anchor.artboardId, position: anchor.position }
+          : { refId: anchor.refId, position: anchor.position };
     try {
       if (kind === 'image') {
         window.parent.postMessage({ dgn: 'insert-image-request', ...anchorFields }, '*');

package/apps/studio/ui-prefs.ts

@@ -0,0 +1,130 @@
+// ui-prefs.ts — disk-backed UI / view preferences (feature-unified-settings-modal).
+//
+// The Settings modal's non-secret UI prefs (theme + the Canvas & View toggles)
+// persist here so they survive a restart AND a cleared browser localStorage
+// (the native WKWebView shell is the case that motivated an explicit on-disk
+// store rather than trusting localStorage alone). Stored GLOBALLY per user, not
+// per-project — these are user preferences, not canvas state — at
+// `~/.config/maude/prefs.json` (XDG-aware, same location discipline as
+// generation/keys.ts's keys.json and sync/hubs-config.ts's hubs.json).
+//
+// NON-SECRET by construction: this file only ever holds boolean/enum view
+// toggles. It is never versioned and never served to a canvas — the GET/POST
+// routes are MAIN-ORIGIN ONLY (privileged), like /_api/generate/prefs.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** The dockable shell panels the Layout tab can move between the two sides. */
+export const DOCK_PANEL_IDS = [
+  'tree',
+  'layers',
+  'inspector',
+  'comments',
+  'changes',
+  'assistant',
+] as const;
+export type DockPanelId = (typeof DOCK_PANEL_IDS)[number];
+export type DockSide = 'left' | 'right';
+export type PanelSides = Record<DockPanelId, DockSide>;
+
+export interface UiPrefs {
+  theme: 'light' | 'dark';
+  minimap: boolean;
+  zoom: boolean;
+  annotations: boolean;
+  autoOpenInspector: boolean;
+  /** Which side each dockable panel lives on (feature-configurable-panel-docking). */
+  panelSides: PanelSides;
+  /** Whether Layers is its own dockable panel or a tab inside the Inspector. */
+  layersMode: 'separate' | 'in-inspector';
+}
+
+// Defaults MUST agree with app.jsx's initial state (THEME default 'dark',
+// MINIMAP/ZOOMCTL false, annotations on, auto-open-inspector on) and with
+// use-chrome-visibility.tsx's provider defaults. Panel defaults mirror the
+// pre-docking shell: tree + layers on the left, everything else on the right;
+// Layers ships as its own panel (`separate`), docked left.
+export const PANEL_SIDES_DEFAULTS: PanelSides = {
+  tree: 'left',
+  layers: 'left',
+  inspector: 'right',
+  comments: 'right',
+  changes: 'right',
+  assistant: 'right',
+};
+export const UI_PREFS_DEFAULTS: UiPrefs = {
+  theme: 'dark',
+  minimap: false,
+  zoom: false,
+  annotations: true,
+  autoOpenInspector: true,
+  panelSides: { ...PANEL_SIDES_DEFAULTS },
+  layersMode: 'separate',
+};
+
+/** Resolve the on-disk path to prefs.json (mirrors keys.ts's XDG logic). */
+export function uiPrefsPath(): string {
+  if (process.env.MAUDE_UI_PREFS_PATH) return process.env.MAUDE_UI_PREFS_PATH;
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
+  return join(base, 'maude', 'prefs.json');
+}
+
+function coercePanelSides(raw: unknown): PanelSides {
+  const o =
+    raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+  const out = { ...PANEL_SIDES_DEFAULTS };
+  for (const id of DOCK_PANEL_IDS) {
+    if (o[id] === 'left' || o[id] === 'right') out[id] = o[id] as DockSide;
+  }
+  return out;
+}
+
+function coerce(raw: unknown): UiPrefs {
+  const o =
+    raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+  const bool = (v: unknown, d: boolean) => (typeof v === 'boolean' ? v : d);
+  return {
+    theme: o.theme === 'light' || o.theme === 'dark' ? o.theme : UI_PREFS_DEFAULTS.theme,
+    minimap: bool(o.minimap, UI_PREFS_DEFAULTS.minimap),
+    zoom: bool(o.zoom, UI_PREFS_DEFAULTS.zoom),
+    annotations: bool(o.annotations, UI_PREFS_DEFAULTS.annotations),
+    autoOpenInspector: bool(o.autoOpenInspector, UI_PREFS_DEFAULTS.autoOpenInspector),
+    panelSides: coercePanelSides(o.panelSides),
+    layersMode: o.layersMode === 'in-inspector' ? 'in-inspector' : UI_PREFS_DEFAULTS.layersMode,
+  };
+}
+
+/** Current UI prefs merged over the defaults (defaults when missing/unreadable). */
+export function readUiPrefs(): UiPrefs {
+  const path = uiPrefsPath();
+  if (!existsSync(path)) return { ...UI_PREFS_DEFAULTS };
+  try {
+    return coerce(JSON.parse(readFileSync(path, 'utf8')));
+  } catch {
+    return { ...UI_PREFS_DEFAULTS };
+  }
+}
+
+/**
+ * Persist a partial patch over the on-disk prefs (only the provided keys change;
+ * every other stored value is preserved). Returns the merged result. Best-effort
+ * — a write failure throws so the route can surface it.
+ */
+export function writeUiPrefs(patch: Partial<UiPrefs>): UiPrefs {
+  const cur = readUiPrefs();
+  // panelSides is deep-merged so a partial patch (one panel moved) preserves the
+  // other panels' sides instead of resetting them to defaults via coerce.
+  const merged: Partial<UiPrefs> = {
+    ...cur,
+    ...patch,
+    panelSides: { ...cur.panelSides, ...(patch.panelSides ?? {}) },
+  };
+  const next = coerce(merged);
+  const path = uiPrefsPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}

package/apps/studio/use-canvas-media-drop.tsx

@@ -302,8 +302,10 @@ export async function uploadAndAnnounceMedia(
 }
 
 /** World-px stagger between cascaded drop targets so a batch Finder drop
- * doesn't stack every clip on the exact same point. */
-const BATCH_DROP_CASCADE_PX = 28;
+ * doesn't stack every clip on the exact same point. Exported — the picker's
+ * batched "Add as annotation" insert (annotations-layer.tsx) reuses the same
+ * stagger so both entry points cascade identically. */
+export const BATCH_DROP_CASCADE_PX = 28;
 
 export function useCanvasMediaDrop(opts: {
   enabled: boolean;