@1agh/maude 0.60.5 → 0.60.7

package/apps/studio/test/comment-mount.test.ts

@@ -39,7 +39,16 @@ describe('comment-mount / MaybeToolProvider dedup', () => {
     const html = renderToStaticMarkup(
       createElement(MaybeToolProvider, null, createElement(ToolReader))
     );
-    // feature-4 (browse/move split) — the default boot tool is `browse`.
+    // DDR-223 — the default boot tool is `move` (edit mode).
+    expect(html).toContain('data-tool="move"');
+  });
+
+  test('forwards initial="browse" — the comment-mount specimen posture (DDR-223)', () => {
+    // buildCanvasTree passes this explicitly so bare DS specimens keep the
+    // DDR-187 alive posture + native cursors.
+    const html = renderToStaticMarkup(
+      createElement(MaybeToolProvider, { initial: 'browse' }, createElement(ToolReader))
+    );
     expect(html).toContain('data-tool="browse"');
   });
 });

package/apps/studio/test/hmr-broadcast.test.ts

@@ -60,14 +60,16 @@ describe('hmr-broadcast / classification', () => {
     h.stop();
   });
 
-  test('unrelated extensions are dropped', async () => {
+  test('unrelated extensions are dropped; media becomes an asset heal', async () => {
     const ctx = mkCtx();
     const got: HmrMessage[] = [];
     const h = createHmrBroadcaster(ctx, (m) => got.push(m));
-    ctx.bus.emit('fs:any', 'ui/screenshot.png');
-    ctx.bus.emit('fs:any', '_locator.json');
+    ctx.bus.emit('fs:any', 'ui/screenshot.png'); // media → asset heal (2026-08-15 RCA)
+    ctx.bus.emit('fs:any', '_locator.json'); // runtime state → dropped
     await awaitNextFlush();
-    expect(got).toHaveLength(0);
+    expect(got).toHaveLength(1);
+    expect(got[0]?.mode).toBe('asset');
+    expect(got[0]?.file).toBe('ui/screenshot.png');
     h.stop();
   });
 });

package/apps/studio/test/hmr-classify.test.ts

@@ -59,7 +59,24 @@ describe('classifyChange', () => {
 
   test('unrelated extensions → null', () => {
     expect(classifyChange('ui/notes.md', noSibling)).toBeNull();
-    expect(classifyChange('assets/logo.svg', noSibling)).toBeNull();
+    expect(classifyChange('assets/photo.png.part', noSibling)).toBeNull();
+    expect(classifyChange('system/x/assets/fonts/Gators-Bold.woff2', noSibling)).toBeNull();
+  });
+
+  test('media files → asset heal signal (2026-08-15 annotations-assets RCA)', () => {
+    // A synced-down media file landing on disk heals still-broken <img>/<image>
+    // elements in open canvases — no reload. Top-level assets/ and DS trees both.
+    for (const f of [
+      'assets/65c3a940.png',
+      'assets/807d7ba7.jpg',
+      'assets/logo.svg',
+      'assets/clip.mp4',
+      'system/alligators/assets/photos-cut/frame-helmet.jpg',
+    ]) {
+      const msg = classifyChange(f, noSibling);
+      expect(msg?.mode).toBe('asset');
+      expect(msg?.file).toBe(f);
+    }
   });
 
   test('backslash paths are normalised before classification', () => {

package/apps/studio/test/mode-toggle.test.tsx

@@ -0,0 +1,226 @@
+// mode-toggle — DDR-223 (issue #93). The preview/edit mode layer over the
+// DDR-187 browse/move tool split: boot posture, the mode⇄tool invariant
+// (arming a resting tool moves the mode; annotation tools are mode-neutral),
+// resetTool, read-only preview boot, and the palette's segmented toggle.
+//
+// Needs a live DOM (context callbacks fired via act) — register happy-dom +
+// drive a createRoot, same convention as browse-posture.test.tsx.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+  (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+});
+afterAll(() => {
+  GlobalRegistrator.unregister();
+});
+
+import { act, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { Tool } from '../input-router.tsx';
+import { _resetReadOnlyCache } from '../read-only-mode.ts';
+import { ToolPalette } from '../tool-palette.tsx';
+import { type CanvasMode, ToolProvider, useToolMode } from '../use-tool-mode.tsx';
+
+// Capture the live context value so tests can drive setMode/setTool/resetTool
+// directly and assert the resulting (tool, mode) pair.
+let ctx: ReturnType<typeof useToolMode> | null = null;
+function Capture() {
+  ctx = useToolMode();
+  return null;
+}
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+
+function mount(ui: ReactNode): void {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(ui);
+  });
+}
+
+afterEach(() => {
+  act(() => {
+    root?.unmount();
+  });
+  host?.remove();
+  root = null;
+  host = null;
+  ctx = null;
+  _resetReadOnlyCache();
+  setPageUrl('http://localhost/');
+});
+
+// happy-dom: `history.replaceState` does not update `location.search`; the
+// DetachedWindowAPI `setURL` is the supported seam.
+function setPageUrl(url: string): void {
+  (window as unknown as { happyDOM?: { setURL?: (u: string) => void } }).happyDOM?.setURL?.(url);
+}
+
+const pair = (): { tool: Tool; mode: CanvasMode } => ({
+  tool: ctx?.tool as Tool,
+  mode: ctx?.mode as CanvasMode,
+});
+
+describe('mode-toggle / boot posture (DDR-223)', () => {
+  test('default boot = edit with move armed', () => {
+    mount(
+      <ToolProvider>
+        <Capture />
+      </ToolProvider>
+    );
+    expect(pair()).toEqual({ tool: 'move', mode: 'edit' });
+  });
+
+  test('initial="browse" boots preview (comment-mount specimen posture)', () => {
+    mount(
+      <ToolProvider initial="browse">
+        <Capture />
+      </ToolProvider>
+    );
+    expect(pair()).toEqual({ tool: 'browse', mode: 'preview' });
+  });
+
+  test('read-only (?ro=1) boots preview/browse — the DDR-187 viewer posture', () => {
+    setPageUrl('http://localhost/?ro=1');
+    _resetReadOnlyCache();
+    mount(
+      <ToolProvider>
+        <Capture />
+      </ToolProvider>
+    );
+    expect(pair()).toEqual({ tool: 'browse', mode: 'preview' });
+  });
+});
+
+describe('mode-toggle / mode⇄tool invariant', () => {
+  test('setMode arms the resting tool both ways', () => {
+    mount(
+      <ToolProvider>
+        <Capture />
+      </ToolProvider>
+    );
+    act(() => ctx?.setMode('preview'));
+    expect(pair()).toEqual({ tool: 'browse', mode: 'preview' });
+    act(() => ctx?.setMode('edit'));
+    expect(pair()).toEqual({ tool: 'move', mode: 'edit' });
+  });
+
+  test('arming a resting tool moves the mode (V / tool-set / escape hatch)', () => {
+    mount(
+      <ToolProvider>
+        <Capture />
+      </ToolProvider>
+    );
+    act(() => ctx?.setTool('browse'));
+    expect(pair()).toEqual({ tool: 'browse', mode: 'preview' });
+    // The Cmd+click-in-browse escape hatch is a plain setTool('move') at its
+    // call site — the invariant is what turns it into a coherent mode flip.
+    act(() => ctx?.setTool('move'));
+    expect(pair()).toEqual({ tool: 'move', mode: 'edit' });
+  });
+
+  test('annotation tools are mode-neutral — pen in preview stays preview', () => {
+    mount(
+      <ToolProvider initial="browse">
+        <Capture />
+      </ToolProvider>
+    );
+    act(() => ctx?.setTool('pen'));
+    expect(pair()).toEqual({ tool: 'pen', mode: 'preview' });
+    act(() => ctx?.setTool('comment'));
+    expect(pair()).toEqual({ tool: 'comment', mode: 'preview' });
+  });
+
+  test('resetTool arms the CURRENT mode’s resting tool', () => {
+    mount(
+      <ToolProvider initial="browse">
+        <Capture />
+      </ToolProvider>
+    );
+    // Preview: drawing an annotation then resetting returns to browse (the
+    // alive posture) — never to move.
+    act(() => ctx?.setTool('pen'));
+    act(() => ctx?.resetTool());
+    expect(pair()).toEqual({ tool: 'browse', mode: 'preview' });
+    // Edit: byte-identical to the pre-DDR-223 hardcoded setTool('move').
+    act(() => ctx?.setMode('edit'));
+    act(() => ctx?.setTool('pen'));
+    act(() => ctx?.resetTool());
+    expect(pair()).toEqual({ tool: 'move', mode: 'edit' });
+  });
+});
+
+describe('mode-toggle / palette segmented toggle', () => {
+  const mountPalette = () =>
+    mount(
+      <ToolProvider>
+        <Capture />
+        <ToolPalette />
+      </ToolProvider>
+    );
+  const seg = (which: 'preview' | 'edit' | 'present'): HTMLButtonElement | null =>
+    document.querySelector(`[data-testid="palette-mode-${which}"]`);
+
+  test('renders three icon segments; Edit is pressed on boot; no browse/move tool buttons', () => {
+    mountPalette();
+    expect(seg('preview')).not.toBeNull();
+    expect(seg('edit')?.getAttribute('aria-pressed')).toBe('true');
+    expect(seg('preview')?.getAttribute('aria-pressed')).toBe('false');
+    // Owner steer 2026-08-15 — icon-only segments (lucide eye / pencil-ruler /
+    // presentation); the words live in aria-label/title.
+    expect(seg('preview')?.querySelector('svg')).not.toBeNull();
+    expect(seg('edit')?.querySelector('svg')).not.toBeNull();
+    expect(seg('present')?.querySelector('svg')).not.toBeNull();
+    // The segments ARE the resting-tool affordances — no separate Select /
+    // Browse buttons in the nav group.
+    expect(document.querySelector('[aria-label^="Select (V)"]')).toBeNull();
+    expect(document.querySelector('[aria-label^="Browse ("]')).toBeNull();
+    // Present moved INTO the toggle — exactly one presentation affordance, and
+    // it is the segment (the palette's right-end button is gone).
+    const present = document.querySelectorAll('[aria-label^="Presentation mode"]');
+    expect(present.length).toBe(1);
+    expect(present[0]).toBe(seg('present') as Element);
+    expect(seg('present')?.getAttribute('aria-pressed')).toBe('false');
+  });
+
+  test('clicking Preview flips the posture; insert (+) is edit-only', () => {
+    mountPalette();
+    expect(
+      document.querySelector('[aria-label="Insert element — Div, Text, or Image"]')
+    ).not.toBeNull();
+    act(() => {
+      seg('preview')?.click();
+    });
+    expect(pair()).toEqual({ tool: 'browse', mode: 'preview' });
+    expect(seg('preview')?.getAttribute('aria-pressed')).toBe('true');
+    expect(
+      document.querySelector('[aria-label="Insert element — Div, Text, or Image"]')
+    ).toBeNull();
+    // Draw tools stay available in preview (issue #93: annotations in preview).
+    expect(document.querySelector('[aria-label^="Pen (B)"]')).not.toBeNull();
+    // And the Edit segment arms move again.
+    act(() => {
+      seg('edit')?.click();
+    });
+    expect(pair()).toEqual({ tool: 'move', mode: 'edit' });
+  });
+
+  test('clicking the ACTIVE segment re-arms the resting tool', () => {
+    mountPalette();
+    act(() => {
+      seg('preview')?.click();
+    });
+    act(() => ctx?.setTool('pen'));
+    expect(pair()).toEqual({ tool: 'pen', mode: 'preview' });
+    act(() => {
+      seg('preview')?.click();
+    });
+    expect(pair()).toEqual({ tool: 'browse', mode: 'preview' });
+  });
+});

package/apps/studio/test/sync-asset-push.test.ts

@@ -14,6 +14,7 @@ import {
   isPushableAssetRel,
   listPushableAssets,
   pushAssets,
+  pushOneAsset,
   putTimeoutMs,
 } from '../sync/asset-push.ts';
 
@@ -837,10 +838,11 @@ describe('the runtime sweeps on change, not only at boot', () => {
   test('the fs watcher decides with isPushableAssetRel and schedules a sweep', () => {
     // The predicate gets the project's OWN canvas groups — with the default
     // set a custom-group project's shared module would answer canvas-owned
-    // and silently never schedule the sweep that uploads it.
-    expect(SYNC).toContain(
-      'if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) scheduleAssetSweep('
-    );
+    // and silently never schedule the sweep that uploads it. (Since the
+    // 2026-08-16 latency fix the same gate also feeds the fast lane; the
+    // sweep stays the reconciler.)
+    expect(SYNC).toContain('if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) {');
+    expect(SYNC).toContain('scheduleAssetSweep(linkedHub.url);');
   });
 
   test('bursts coalesce, and a change DURING a sweep is not lost', () => {
@@ -855,3 +857,112 @@ describe('the runtime sweeps on change, not only at boot', () => {
     expect(SYNC).toContain('if (assetSweepTimer !== null) clearTimeout(assetSweepTimer);');
   });
 });
+
+describe('pushOneAsset — the fast lane (2026-08-16 latency fix)', () => {
+  test('probes once via /_asset-probe, then PUTs the single file', async () => {
+    const designRoot = scratchDesignRoot();
+    mkdirSync(join(designRoot, 'assets'), { recursive: true });
+    writeFileSync(join(designRoot, 'assets/aaaaaaaa.png'), 'fresh sticker');
+
+    const calls: Array<{ method: string; url: string }> = [];
+    const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      const method = init?.method ?? 'GET';
+      calls.push({ method, url });
+      if (url.endsWith('/_asset-probe')) return Response.json({ present: [] });
+      return new Response('{"ok":true}', { status: 200 });
+    }) as typeof fetch;
+
+    const r = await pushOneAsset({
+      designRoot,
+      rel: 'assets/aaaaaaaa.png',
+      hubUrl: 'https://alligators.cloud.maude.sh/',
+      token: () => 'mau_tok',
+      fetchImpl,
+    });
+    expect(r).toEqual({ ok: true });
+    expect(calls.map((c) => `${c.method} ${c.url}`)).toEqual([
+      'POST https://alligators.cloud.maude.sh/_asset-probe',
+      'PUT https://alligators.cloud.maude.sh/assets/aaaaaaaa.png',
+    ]);
+  });
+
+  test('a file the hub already holds is skipped — the pull-echo guard', async () => {
+    // The fast lane fires off fs:any, and the asset PULL writes into assets/
+    // too — without this skip the lane would upload the hub's own bytes back.
+    const designRoot = scratchDesignRoot();
+    mkdirSync(join(designRoot, 'assets'), { recursive: true });
+    writeFileSync(join(designRoot, 'assets/aaaaaaaa.png'), 'pulled bytes');
+
+    let puts = 0;
+    const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith('/_asset-probe')) return Response.json({ present: ['assets/aaaaaaaa.png'] });
+      if (init?.method === 'PUT') puts += 1;
+      return new Response('{"ok":true}', { status: 200 });
+    }) as typeof fetch;
+
+    const r = await pushOneAsset({
+      designRoot,
+      rel: 'assets/aaaaaaaa.png',
+      hubUrl: 'https://alligators.cloud.maude.sh',
+      token: () => 'mau_tok',
+      fetchImpl,
+    });
+    expect(r).toEqual({ ok: true, skipped: true });
+    expect(puts).toBe(0);
+  });
+
+  test('DS-tree asset routes to /_asset-file/; non-pushable rels refuse; failures report', async () => {
+    const designRoot = scratchDesignRoot();
+    mkdirSync(join(designRoot, 'system/ds/assets'), { recursive: true });
+    writeFileSync(join(designRoot, 'system/ds/assets/mark.svg'), 'brand');
+
+    const urls: string[] = [];
+    const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith('/_asset-probe')) return Response.json({ present: [] });
+      if (init?.method === 'PUT') {
+        urls.push(url);
+        return new Response('refused', { status: 403 });
+      }
+      return new Response(null, { status: 404 });
+    }) as typeof fetch;
+
+    const r = await pushOneAsset({
+      designRoot,
+      rel: 'system/ds/assets/mark.svg',
+      hubUrl: 'https://hub.example.com',
+      token: () => 't',
+      fetchImpl,
+    });
+    expect(urls).toEqual(['https://hub.example.com/_asset-file/system/ds/assets/mark.svg']);
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain('403');
+
+    // Runtime state / config never enter the fast lane.
+    const refused = await pushOneAsset({
+      designRoot,
+      rel: '_history/x/old.png',
+      hubUrl: 'https://hub.example.com',
+      token: () => 't',
+      fetchImpl,
+    });
+    expect(refused.ok).toBe(false);
+    expect(refused.reason).toBe('not a pushable asset');
+  });
+
+  test('the runtime wires the fast lanes: push off fs:any, pull off reference files', () => {
+    // Same source-pin style as the sweep-trigger suite above.
+    expect(SYNC2).toContain('queueFastPush(rel');
+    expect(SYNC2).toMatch(/REFERENCE_FILE_RE\.test\(rel\)/);
+    expect(SYNC2).toContain('requestFastPull');
+    // stop() tears the lanes down.
+    expect(SYNC2).toContain('for (const t of fastPushTimers.values()) clearTimeout(t);');
+    expect(SYNC2).toContain('requestFastPull = null;');
+    // The cell never pushes — same guard as the sweep.
+    expect(SYNC2).toMatch(/if \(stopped \|\| cellPairing\) return; \/\/ the cell never pushes/);
+  });
+});
+
+const SYNC2 = readFileSync(join(import.meta.dir, '..', 'sync', 'index.ts'), 'utf8');

package/apps/studio/test/use-tool-mode.test.tsx

@@ -7,6 +7,7 @@ import { renderToStaticMarkup } from 'react-dom/server';
 import {
   DEFAULT_TOOLS,
   filterToolsForReadOnly,
+  MODE_DEFAULT_TOOL,
   ToolProvider,
   useToolMode,
   useToolModeOptional,
@@ -49,6 +50,11 @@ describe('use-tool-mode / static', () => {
     expect(Object.isFrozen(DEFAULT_TOOLS)).toBe(true);
   });
 
+  test('MODE_DEFAULT_TOOL — DDR-223 resting tools: preview→browse, edit→move', () => {
+    expect(MODE_DEFAULT_TOOL).toEqual({ preview: 'browse', edit: 'move' });
+    expect(Object.isFrozen(MODE_DEFAULT_TOOL)).toBe(true);
+  });
+
   test('cursors per tool (Phase 24 — ONE Kenney library for every tool + native fallback)', () => {
     const byId = Object.fromEntries(DEFAULT_TOOLS.map((t) => [t.id, t.cursor]));
     // Phase 24 — EVERY tool (incl. move) ships a Kenney data-URI SVG cursor that
@@ -97,16 +103,40 @@ describe('use-tool-mode / useToolModeOptional', () => {
 describe('use-tool-mode / SSR render', () => {
   test('ToolProvider with consumer renders without throwing', () => {
     function Consumer() {
-      const { tool } = useToolMode();
-      return <span data-tool={tool}>{tool}</span>;
+      const { tool, mode } = useToolMode();
+      return (
+        <span data-tool={tool} data-mode={mode}>
+          {tool}
+        </span>
+      );
     }
     const html = renderToStaticMarkup(
       <ToolProvider>
         <Consumer />
       </ToolProvider>
     );
-    // feature-4 — boot default is browse (the mock is alive until V is pressed).
+    // DDR-223 (issue #93) — boot posture is EDIT with the Move (select) tool
+    // armed; Preview (the DDR-187 alive posture) is one toggle away.
+    expect(html).toContain('data-tool="move"');
+    expect(html).toContain('data-mode="edit"');
+  });
+
+  test('ToolProvider initial="browse" boots the preview mode (comment-mount / specimens)', () => {
+    function Consumer() {
+      const { tool, mode } = useToolMode();
+      return (
+        <span data-tool={tool} data-mode={mode}>
+          {tool}
+        </span>
+      );
+    }
+    const html = renderToStaticMarkup(
+      <ToolProvider initial="browse">
+        <Consumer />
+      </ToolProvider>
+    );
     expect(html).toContain('data-tool="browse"');
+    expect(html).toContain('data-mode="preview"');
   });
 
   test('ToolProvider honors initial tool', () => {

package/apps/studio/tool-palette.tsx

@@ -16,7 +16,9 @@ import { useEffect, useRef, useState } from 'react';
 
 import {
   IconChevronDown,
+  IconEye,
   IconLetterA,
+  IconPencilRuler,
   IconPresentation,
   IconSquare,
   SHAPE_KIND_ICONS,
@@ -217,6 +219,10 @@ const PALETTE_CSS = `
   background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 14%, transparent);
   color: var(--maude-hud-accent, #d63b1f);
 }
+/* DDR-223 — Preview/Edit/Present segmented mode toggle at the head of the
+   palette (owner steer 2026-08-15: icon segments — lucide eye / pencil-ruler /
+   presentation). Standard 32 × 32 buttons; active state reuses the
+   aria-pressed tint + underbar. */
 /* Stage I3 tail — "+ Element" insert popover. A vertical labeled list (not the
    shape popover's icon grid): Div/Text/Image have no recognizable glyph on
    their own, and this is a rare, must-be-legible action, not a recalled tool. */
@@ -257,9 +263,12 @@ function ensurePaletteStyles(): void {
   document.head.appendChild(s);
 }
 
-// feature-4 (browse/move split) — Browse leads the nav group (it's the boot
-// default), then Move (the select tool, V), Hand, Comment.
-const NAV_TOOLS = ['browse', 'move', 'hand', 'comment'] as const;
+// DDR-223 — the Preview/Edit segments replace BOTH resting-tool buttons in
+// the nav group: `browse` is armed by the Preview segment, `move` by the Edit
+// segment (clicking the active segment re-arms it; V and Esc still arm move
+// directly). Annotation tools render in BOTH modes (issue #93: preview keeps
+// annotations).
+const NAV_TOOLS = ['hand', 'comment'] as const;
 // Phase 24 — the two rect/ellipse buttons collapse into one Shape tool (with a
 // kind popover); sticky/arrow/text/eraser keep their order. Wave H — section
 // joins the row (it was ⇧S-only before; users couldn't discover it).
@@ -324,7 +333,18 @@ export function resolveInsertAnchor(
 
 export function ToolPalette() {
   ensurePaletteStyles();
-  const { tool, setTool, tools, sticky, toggleSticky, shapeKind, setShapeKind } = useToolMode();
+  const {
+    tool,
+    setTool,
+    tools,
+    mode,
+    setMode,
+    resetTool,
+    sticky,
+    toggleSticky,
+    shapeKind,
+    setShapeKind,
+  } = useToolMode();
   const chrome = useChromeVisibility();
   const [mounted, setMounted] = useState(false);
   const [shapeOpen, setShapeOpen] = useState(false);
@@ -484,8 +504,65 @@ export function ToolPalette() {
     );
   };
 
+  // DDR-223 — the mode toggle, three segments (owner steer 2026-08-15, round
+  // 2): Preview (eye), Edit (pencil-ruler), Present (presentation) — icon-only,
+  // the words live in aria-label + title. Clicking the ACTIVE Preview/Edit
+  // segment re-arms that mode's resting tool (the "get me out of the pen tool"
+  // gesture — especially in preview, where browse has no palette button of its
+  // own). Present is the existing SHELL-level state (enter-only — the palette
+  // is hidden while presenting; exit is Esc or the floating pill); it moved
+  // here from the palette's right end so all three "ways of looking at the
+  // canvas" sit in one control.
+  const renderModeToggle = () => (
+    // biome-ignore lint/a11y/useSemanticElements: segmented control of buttons, not a form — fieldset semantics (and its default box styling) don't apply
+    <div className="dc-tp-group dc-tp-mode" role="group" aria-label="Canvas mode">
+      <button
+        type="button"
+        data-testid="palette-mode-preview"
+        aria-label="Preview mode — the mock is live; annotation tools stay on"
+        aria-pressed={mode === 'preview'}
+        title="Preview — the mock is live (buttons click); annotation tools stay on"
+        onClick={() => (mode === 'preview' ? resetTool() : setMode('preview'))}
+      >
+        <IconEye />
+      </button>
+      <button
+        type="button"
+        data-testid="palette-mode-edit"
+        aria-label="Edit mode — click selects & edits, like Figma (V)"
+        aria-pressed={mode === 'edit'}
+        title="Edit — click selects & edits, like Figma (V)"
+        onClick={() => (mode === 'edit' ? resetTool() : setMode('edit'))}
+      >
+        <IconPencilRuler />
+      </button>
+      <button
+        type="button"
+        data-testid="palette-mode-present"
+        aria-label="Presentation mode — hide all chrome (Esc to exit)"
+        aria-pressed={chrome?.present ?? false}
+        title="Presentation mode — hide all chrome (Esc to exit)"
+        onClick={() => {
+          // Present Mode is a SHELL-level state (it hides the menubar /
+          // sidebar / panels too), so the canvas iframe requests it from the
+          // parent shell, which flips on `.is-present` + broadcasts
+          // dgn:'view-chrome' back down.
+          try {
+            window.parent.postMessage({ dgn: 'present-enter' }, '*');
+          } catch {
+            /* detached / cross-origin */
+          }
+        }}
+      >
+        <IconPresentation />
+      </button>
+    </div>
+  );
+
   return (
     <div ref={containerRef} className="dc-tool-palette" role="toolbar" aria-label="Canvas tools">
+      {renderModeToggle()}
+      <div className="dc-tp-sep" />
       <div className="dc-tp-group">
         {navList.map((t) => (t ? renderToolButton(t.id, t.label, t.shortcut) : null))}
       </div>
@@ -505,7 +582,9 @@ export function ToolPalette() {
       ) : null}
       <div className="dc-tp-sep" />
       <div className="dc-tp-group">
-        {!readOnly && (
+        {/* DDR-223 — "+ Element" is a JSX WRITE, an edit-mode affordance;
+            stickers/export/present stay in both modes. */}
+        {!readOnly && mode === 'edit' && (
           <span className="dc-tp-insert">
             <button
               type="button"
@@ -575,25 +654,8 @@ export function ToolPalette() {
             ⬇
           </span>
         </button>
-        <button
-          type="button"
-          aria-label="Presentation mode — hide all chrome"
-          title="Presentation mode — hide all chrome (Esc to exit)"
-          onClick={() => {
-            // Present Mode is a SHELL-level state (it hides the menubar /
-            // sidebar / panels too), so the canvas iframe requests it from the
-            // parent shell, which flips on `.is-present` + broadcasts
-            // dgn:'view-chrome' back down. Enter-only — the palette is hidden
-            // while presenting; exit is Esc or the floating pill.
-            try {
-              window.parent.postMessage({ dgn: 'present-enter' }, '*');
-            } catch {
-              /* detached / cross-origin */
-            }
-          }}
-        >
-          <IconPresentation />
-        </button>
+        {/* DDR-223 addendum 2 — the Presentation button moved into the mode
+            toggle at the palette's head (third segment). */}
       </div>
     </div>
   );