@1agh/maude 0.42.0 → 0.43.0

package/apps/studio/client/app.jsx

@@ -23,6 +23,8 @@ import { ReadinessDialog } from './panels/ReadinessList.jsx';
 import TimelinePanel from './panels/TimelinePanel.jsx';
 import { parseCompTimeline } from './panels/timeline-parse.js';
 import RepoBranchSwitcher from './panels/RepoBranchSwitcher.jsx';
+import StickerPicker from './panels/StickerPicker.jsx';
+import { PhotoKnobs } from './photo-knobs.jsx';
 import {
   appIsFirstRun,
   isNativeApp,
@@ -45,6 +47,8 @@ const THEME_STORE = 'mdcc-theme';
 const SHOW_HIDDEN_STORE = 'mdcc-show-hidden';
 const SECTIONS_STORE = 'mdcc-sections-expanded';
 const SIDEBAR_STORE = 'mdcc-sidebar-open';
+const MINIMAP_STORE = 'mdcc-minimap-visible';
+const ZOOMCTL_STORE = 'mdcc-zoomctl-visible';
 const CANVAS_EXT_RE = /\.(tsx|html?)$/i;
 // Bun's `define` substitutes this at build time (see build.ts); falls back when
 // the bundle is consumed in a context that hasn't run the build.
@@ -1648,6 +1652,8 @@ function Sidebar({
   dirtyByPath,
   project,
   gitBranch,
+  remoteSync,
+  onGetLatest,
 }) {
   const filteredGroups = useMemo(() => {
     if (!search) return groups;
@@ -1889,7 +1895,7 @@ function Sidebar({
       {/* Phase 29 (E4) — the project + draft switcher: a compact one-line dock that
           opens UPWARD, sitting directly above the GitHub identity avatar so the two
           form one bottom dock. Renders nothing until the project is a git repo. */}
-      <RepoBranchSwitcher project={project} liveBranch={gitBranch} />
+      <RepoBranchSwitcher project={project} liveBranch={gitBranch} remoteSync={remoteSync} onGetLatest={onGetLatest} />
       {/* Phase 28 (E3) — GitHub identity as a compact avatar docked at the BOTTOM:
           sign in, connected account + New/Pull/Share, sign out. Self-contained
           (owns its device-code + CreateProject dialogs). Renders nothing in browser. */}
@@ -2427,12 +2433,9 @@ function ViewDropdown({ panels, onToggle, onClose, onZoom, hasCanvas }) {
           <span className="st-dd-lead">
             <span className="st-dd-check">{p.checked ? <StIcon name="check" size={13} /> : null}</span>
             <span>{p.label}</span>
+            {p.phase ? <span className="st-dd-phase">{p.phase}</span> : null}
           </span>
-          {p.phase ? (
-            <span className="st-dd-phase">{p.phase}</span>
-          ) : p.shortcut ? (
-            <Kbd>{p.shortcut}</Kbd>
-          ) : null}
+          {p.shortcut ? <Kbd>{p.shortcut}</Kbd> : null}
         </button>
       ))}
       <div className="st-dd-sep" />
@@ -2740,6 +2743,7 @@ function Menubar({
     {
       id: 'timeline',
       label: 'Timeline',
+      shortcut: '⌘ ⇧ T',
       phase: hasComps ? 'video' : undefined,
       checked: timelineOpen,
       disabled: false,
@@ -3959,6 +3963,12 @@ function cssSplitUnit(v) {
 // is for the SAME element we already hold locally, preserve those fields instead
 // of clobbering them to empty (else the server round-trip wipes the custom-CSS /
 // custom-attr rows + computed readout right after selection).
+// feature-photo-editor — `photoKind`/`photoAsset` (dom-selection.ts) are the SAME
+// class of client-only DOM-derived field and belong in this list for the same
+// reason: without it, every server-pushed `selected`/`snapshot` restore (a canvas
+// switch, a reconnect, the persisted `_active.json` on boot — none of which carry
+// these fields) silently drops the Inspector's Photo tab until the next fresh
+// click re-derives it live — the "tab is there, then it's gone" flicker.
 function mergeSelClientFields(incoming, prev) {
   if (!incoming || Array.isArray(incoming) || Array.isArray(prev) || !prev) return incoming;
   if (!incoming.id || incoming.id !== prev.id) return incoming;
@@ -3968,6 +3978,8 @@ function mergeSelClientFields(incoming, prev) {
     computed: incoming.computed ?? prev.computed,
     customStyles: incoming.customStyles ?? prev.customStyles,
     attrs: incoming.attrs ?? prev.attrs,
+    photoKind: incoming.photoKind ?? prev.photoKind,
+    photoAsset: incoming.photoAsset ?? prev.photoAsset,
   };
 }
 
@@ -6072,6 +6084,31 @@ function ArtboardKnobs({ el, onResizeArtboard }) {
   );
 }
 
+// feature-photo-editor (Task 13/14) — derive the content-addressed photo asset a
+// DOM selection points at (an artboard `<img src="assets/<sha8>.<ext>">`). Prefers
+// the `photoAsset` the resolver stamped (dom-selection.ts), falling back to a scan
+// of the selection's src/html for a selection that reached the panel via a code
+// path predating that field. Returns null for a non-photo element.
+const PHOTO_ASSET_RE = /assets\/[0-9a-f]{8}\.[a-z0-9]+/i;
+function photoAssetOfSelection(el) {
+  if (!el || Array.isArray(el)) return null;
+  if (el.photoAsset) return el.photoAsset;
+  if ((el.tag || '').toLowerCase() !== 'img') return null;
+  const html = el.html || '';
+  // Once an edit is baked, the element's LIVE src is a `data:` URL (canvas-lib's
+  // PhotoPreviewBridge swaps it in directly) — it never matches PHOTO_ASSET_RE,
+  // so a REPLAYED/serialized selection (a WS resync, or the persisted
+  // `_active.json` restored on boot) that arrives without the dedicated
+  // `photoAsset` field would otherwise permanently lose the Photo tab for any
+  // already-edited photo. The element still carries the `data-photo-asset` tag
+  // the bridge stamped, and that DOES survive into an outerHTML snapshot — check
+  // it before falling back to the plain assets/<sha8> src scan.
+  const tagged = /data-photo-asset="([^"]+)"/.exec(html);
+  if (tagged) return tagged[1];
+  const m = PHOTO_ASSET_RE.exec(`${el.attrs?.src || ''} ${html}`);
+  return m ? m[0] : null;
+}
+
 function InspectorPanel({
   selected,
   onClose,
@@ -6092,6 +6129,16 @@ function InspectorPanel({
   onTabChange,
   width,
   resizing,
+  // feature-photo-editor (Task 13/15) — the Photo tab + its live-preview /
+  // bg-removal / undo channels. `photoSel` is the annotation-image target
+  // (threaded up separately since the annotation model has no DOM selection);
+  // an artboard `<img>` target is derived from `selected` instead.
+  photoSel,
+  photoRev,
+  onPhotoEdit,
+  onPhotoRemoveBackground,
+  onPhotoRecordEdit,
+  onPhotoUndoRedo,
 }) {
   // Tab is controllable from the parent (the guided tour drives it to 'css' /
   // 'layers' so a spotlight step lands on a real row) but falls back to local
@@ -6390,10 +6437,41 @@ function InspectorPanel({
   };
   // `selected` may be a single element, an array (multi-select), or null.
   const el = Array.isArray(selected) ? selected[0] : selected;
+  // feature-photo-editor (Task 13) — resolve the Photo-tab target. Priority: an
+  // annotation-image threaded up (`photoSel`, no DOM selection) → a Photo-ONLY
+  // panel; else a content-addressed artboard `<img>` selection → Photo alongside
+  // the normal tabs.
+  const photoTarget = photoSel
+    ? { asset: photoSel.asset, kind: 'annotation-image' }
+    : (() => {
+        const a = photoAssetOfSelection(el);
+        return a ? { asset: a, kind: 'artboard-img' } : null;
+      })();
+  const photoOnly = photoTarget?.kind === 'annotation-image';
+  // Cmd+Z / Cmd+Shift+Z (or Cmd+Y) while focus is still inside a Photo-tab
+  // slider — mirrors `onKnobKeyDown` above for the same reason: the window-
+  // level shortcut listener bails out whenever `document.activeElement` is an
+  // `<input>` (native text-undo would otherwise win), so a commit-then-Cmd+Z
+  // with the slider still focused needs its own forwarder here.
+  const onPhotoKnobKeyDown = (e) => {
+    if (!(e.metaKey || e.ctrlKey) || e.altKey) return;
+    const k = e.key.toLowerCase();
+    if (k === 'z') {
+      e.preventDefault();
+      onPhotoUndoRedo?.(e.shiftKey ? 'redo' : 'undo');
+    } else if (k === 'y') {
+      e.preventDefault();
+      onPhotoUndoRedo?.('redo');
+    }
+  };
+  // An annotation-image has no element tabs; force Photo. Otherwise honor the
+  // requested tab, but drop off a stale 'photo' tab when the new selection isn't
+  // photo-eligible (so switching from a photo to a normal element lands sanely).
+  const effTab = photoOnly ? 'photo' : tab === 'photo' && !photoTarget ? 'inspect' : tab;
   const tabBtn = (id, label, icon) => (
     <button
       type="button"
-      className={'st-rp-tab' + (tab === id ? ' is-active' : '')}
+      className={'st-rp-tab' + (effTab === id ? ' is-active' : '')}
       onClick={() => setTab(id)}
     >
       <StIcon name={icon} size={14} />
@@ -6409,9 +6487,16 @@ function InspectorPanel({
       data-tour="inspector"
     >
       <div className="st-rp-tabs" data-tour="inspector-tabs">
-        {tabBtn('inspect', 'Inspect', 'sliders')}
-        {tabBtn('layers', 'Layers', 'layers')}
-        {tabBtn('css', 'CSS', 'code')}
+        {photoOnly ? (
+          tabBtn('photo', 'Photo', 'image')
+        ) : (
+          <>
+            {tabBtn('inspect', 'Inspect', 'sliders')}
+            {tabBtn('layers', 'Layers', 'layers')}
+            {tabBtn('css', 'CSS', 'code')}
+            {photoTarget ? tabBtn('photo', 'Photo', 'image') : null}
+          </>
+        )}
         <button
           type="button"
           className="st-iconbtn"
@@ -6447,7 +6532,18 @@ function InspectorPanel({
         </div>
       ) : null}
       <div className="st-rp-body">
-        {!el ? (
+        {effTab === 'photo' && photoTarget ? (
+          <div onKeyDown={onPhotoKnobKeyDown}>
+            <PhotoKnobs
+              key={`${photoTarget.asset}:${photoRev ?? 0}`}
+              asset={photoTarget.asset}
+              ColorPicker={ColorPicker}
+              onEdit={(edit) => onPhotoEdit?.(photoTarget.asset, edit)}
+              onRemoveBackground={onPhotoRemoveBackground}
+              onRecordEdit={(before, after) => onPhotoRecordEdit?.(photoTarget.asset, before, after)}
+            />
+          </div>
+        ) : !el ? (
           <div className="st-rp-empty">
             {/* <p> wrapper — st-rp-empty is a flex column, bare text nodes +
                 kbd would stack as stretched flex items. */}
@@ -6455,7 +6551,7 @@ function InspectorPanel({
               Hold <Kbd>⌘</Kbd> inside the canvas and click an element to inspect it.
             </p>
           </div>
-        ) : tab === 'inspect' ? (
+        ) : effTab === 'inspect' ? (
           <>
             <div className="st-rp-hd">{el.selector || el.tag || 'element'}</div>
             <div className="st-insp-row">
@@ -6504,7 +6600,7 @@ function InspectorPanel({
             ) : null}
             <InspectComputed el={el} />
           </>
-        ) : tab === 'layers' ? (
+        ) : effTab === 'layers' ? (
           <>
             <div className="st-rp-hd">Layers{layersTree?.nodes?.length ? '' : ' · ancestry'}</div>
             {layersTree?.nodes?.length ? (
@@ -6855,7 +6951,9 @@ function App() {
   const [activeComps, setActiveComps] = useState([]);
   const [timelineFrame, setTimelineFrame] = useState(0);
   const [timelinePlaying, setTimelinePlaying] = useState(false);
-  const [timelineLoop, setTimelineLoop] = useState(true);
+  // Default off — looping is an explicit opt-in per session, not a surprise
+  // once the user presses Play (rca/issue-video-artboard-loop-defaults-on).
+  const [timelineLoop, setTimelineLoop] = useState(false);
   const [timelineMuted, setTimelineMuted] = useState(false);
   const [timelineVolume, setTimelineVolume] = useState(1);
   const [timelineHeight, setTimelineHeight] = useState(216);
@@ -6878,6 +6976,15 @@ function App() {
   useEffect(() => {
     timelineCompIdRef.current = timelineCompId;
   }, [timelineCompId]);
+  // rca/issue-video-artboard-frame-reset-on-edit — last known playhead, read
+  // from the `timeline-comps` handler below (which fires on every comp
+  // (re)mount, incl. a ⌘R hard iframe reload) to re-seed the fresh Player
+  // instance. A ref, not state, so the handler always sees the latest value
+  // without pulling `timelineFrame` into that big message-listener's deps.
+  const timelineFrameRef = useRef(0);
+  useEffect(() => {
+    timelineFrameRef.current = timelineFrame;
+  }, [timelineFrame]);
   // The DCArtboard id the timeline scoped to (from parseCompTimeline). Used for
   // /_api/comp-clips + every clip op so the enumerator targets the SAME comp the
   // rows came from — `timelineCompId` is the Player's `videocomp-N` id, which
@@ -6925,6 +7032,17 @@ function App() {
   // Inspector tab is lifted so View ▸ Layers can open the panel ON the Layers
   // tab (the menu item sat disabled as "Phase 12" long after the tab shipped).
   const [inspectorTab, setInspectorTab] = useState('inspect');
+  // feature-photo-editor (Task 13) — the annotation-image Photo-tab target,
+  // threaded up from the annotation layer's "Edit Photo…" (the annotation model
+  // has no DOM selection to ride, unlike an artboard `<img>`). `{ asset, strokeId }`
+  // or null. Cleared whenever a normal DOM selection arrives so the two never
+  // fight over the panel. The shell-side photo undo stack lives alongside it.
+  const [photoSel, setPhotoSel] = useState(null);
+  const photoUndoRef = useRef({ undo: [], redo: [] });
+  // Bumped by the Cmd+Z/Cmd+Shift+Z photo-undo handler below so the mounted
+  // PhotoKnobs (keyed on `asset:photoRev`) remounts and re-fetches the sidecar
+  // it just PUT, instead of drifting from its own stale local `edit` state.
+  const [photoRev, setPhotoRev] = useState(0);
   // feature-element-editing-robustness Stage C — auto-open the Inspector on the
   // CSS tab when a fresh single selection arrives AND no right panel is already
   // open. Preference-backed (default ON); disable it in the View menu. Refs keep
@@ -7113,8 +7231,8 @@ function App() {
   // persistent prefs broadcast to every open canvas iframe; presentMode is a
   // non-destructive "hide ALL chrome + shell, artboards only" overlay with an
   // Esc / floating-pill escape hatch back to the chrome.
-  const [minimapVisible, setMinimapVisible] = useState(true);
-  const [zoomCtlVisible, setZoomCtlVisible] = useState(true);
+  const [minimapVisible, setMinimapVisible] = useState(() => readBoolStore(MINIMAP_STORE, false));
+  const [zoomCtlVisible, setZoomCtlVisible] = useState(() => readBoolStore(ZOOMCTL_STORE, false));
   const [presentMode, setPresentMode] = useState(false);
   // P2/P3 (Plan C) — top-bar live state. (Zoom lives in the canvas toolbar pill,
   // so the top bar no longer mirrors it.)
@@ -7145,6 +7263,96 @@ function App() {
     [activePath]
   );
 
+  // ── feature-photo-editor — the Photo tab's three channels ─────────────────
+  // (1) live preview: broadcast the edit DOWN to the active canvas iframe, whose
+  //     canvas-lib `PhotoPreviewBridge` bakes the composite and swaps it directly
+  //     into the matching `<img>`/`<image>` element's src/href (iteration 2 — see
+  //     the bridge's own header comment for why it's a direct swap, not an
+  //     overlay). (2) undo: a shell-side stack (photo edits are sidecar writes,
+  //     not the canvas-side source-edit stack). (3) background removal: the
+  //     client-side @imgly ML flow (Task 12).
+  const onPhotoEdit = useCallback(
+    (asset, edit) => postToActiveCanvas({ dgn: 'photo-preview', asset, edit }),
+    [postToActiveCanvas]
+  );
+  const onPhotoRecordEdit = useCallback((asset, before, after) => {
+    photoUndoRef.current.undo.push({ asset, before, after });
+    photoUndoRef.current.redo.length = 0;
+  }, []);
+  // Pops the shell-side photo-undo stack, re-persists the reverted edit through
+  // the same PUT route PhotoKnobs itself uses, re-broadcasts it to the live
+  // preview, and bumps `photoRev` so the mounted PhotoKnobs (keyed on
+  // `asset:photoRev`) remounts and re-fetches instead of drifting from its own
+  // stale local state. Returns false (does nothing) when the requested stack is
+  // empty, so callers can fall through to the canvas's own undo stack.
+  const performPhotoUndo = useCallback(
+    (redo) => {
+      const stack = redo ? photoUndoRef.current.redo : photoUndoRef.current.undo;
+      if (!stack.length) return false;
+      const entry = stack.pop();
+      (redo ? photoUndoRef.current.undo : photoUndoRef.current.redo).push(entry);
+      const edit = (redo ? entry.after : entry.before) || {};
+      onPhotoEdit(entry.asset, edit);
+      fetch(`/_api/photo-edit?asset=${encodeURIComponent(entry.asset)}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(edit),
+      }).catch(() => {});
+      setPhotoRev((v) => v + 1);
+      return true;
+    },
+    [onPhotoEdit]
+  );
+  // Task 12 — magic background removal, entirely client-side (WASM/WebGPU via
+  // @imgly/background-removal — NEVER the -node native-addon variant, DDR-070).
+  // The lib is DYNAMICALLY imported so a session that never removes a background
+  // pays zero bundle cost (the lazy-bundle guarantee). Fetches the source bytes,
+  // runs the matte, uploads it content-addressed through the SAME /_api/asset lane
+  // drag-drop uses, and returns the new `assets/<sha8>.png` for PhotoEdit.
+  const onPhotoRemoveBackground = useCallback(
+    async (asset) => {
+      // Scan/shimmer reveal on the live photo while the ML pass runs, the same
+      // "something is actively happening here" language as the agent-edit
+      // artboard rim (artboard-activity-overlay.tsx) — but applied directly to
+      // the photo element itself (a `data-photo-busy` attribute + injected CSS
+      // mask sweep, inspect.ts) rather than a floating tracked overlay. A
+      // floating decoy is exactly the architecture DDR-161's addendum tore out
+      // for the live-edit preview (z-index/resize/hit-testing bugs); an
+      // attribute toggle on the real element sidesteps that whole class.
+      postToActiveCanvas({ dgn: 'photo-busy', asset, busy: true });
+      try {
+        const srcRes = await fetch(`/${asset.replace(/^\/+/, '')}`);
+        if (!srcRes.ok) return null;
+        const srcBlob = await srcRes.blob();
+        const { removeBackground } = await import('@imgly/background-removal');
+        // Inference is 100% CLIENT-SIDE (WASM/WebGPU) — the user's pixels NEVER
+        // leave the browser. Only the public model weights (~40 MB, identical for
+        // everyone) are fetched from IMG.LY's default host on first use; they're
+        // too large to bundle in the npm tarball (`resources.json` ships empty).
+        // Self-hosting those weights off the dev server for offline / air-gapped
+        // parity is the flagged Task-11 follow-up (a one-time download step) — until
+        // then the default host provides them, with no pixel-privacy exposure.
+        const matte = await removeBackground(srcBlob);
+        const up = await fetch('/_api/asset', {
+          method: 'POST',
+          headers: { 'content-type': matte.type || 'image/png' },
+          body: matte,
+        });
+        const j = await up.json().catch(() => ({}));
+        if (up.ok && j.path) return { maskAsset: j.path };
+        return null;
+      } catch (err) {
+        console.error('[photo] background removal failed', err);
+        return null;
+      } finally {
+        // Always clears, success or failure — an errored pass must not leave
+        // the shimmer stuck on the photo forever.
+        postToActiveCanvas({ dgn: 'photo-busy', asset, busy: false });
+      }
+    },
+    [postToActiveCanvas]
+  );
+
   // DDR-150 dogfood #7 — a file dragged from Finder and dropped on a shell area
   // with no drop target used to make the browser NAVIGATE AWAY to the file
   // (file:// replaces the app). Document-level guard: always cancel the default
@@ -7533,6 +7741,16 @@ function App() {
       localStorage.setItem(SECTIONS_STORE, JSON.stringify(sectionsExpanded));
     } catch {}
   }, [sectionsExpanded]);
+  useEffect(() => {
+    try {
+      localStorage.setItem(MINIMAP_STORE, minimapVisible ? '1' : '0');
+    } catch {}
+  }, [minimapVisible]);
+  useEffect(() => {
+    try {
+      localStorage.setItem(ZOOMCTL_STORE, zoomCtlVisible ? '1' : '0');
+    } catch {}
+  }, [zoomCtlVisible]);
 
   const toggleSection = useCallback((label, defaultOpen) => {
     setSectionsExpanded((prev) => {
@@ -7863,8 +8081,11 @@ function App() {
   useEffect(() => {
     if (gitStatus?.repo === false) return; // solo / non-git project — no remote
     refreshRemoteSync();
-    if (!changesOpen) return; // only keep polling while the panel is visible
-    const id = setInterval(refreshRemoteSync, 60000);
+    // Poll in the background too — not only while Changes is open — so the dock's
+    // "Get latest" nudge surfaces a teammate's publish proactively. Slower cadence
+    // when the panel is closed to stay network-polite (the ahead/behind probe is
+    // TTL-cached server-side, so a missed tick is cheap to re-issue).
+    const id = setInterval(refreshRemoteSync, changesOpen ? 60000 : 120000);
     return () => clearInterval(id);
   }, [gitStatus?.repo, changesOpen, refreshRemoteSync]);
 
@@ -8245,7 +8466,22 @@ function App() {
       // canvas must not be able to plant a selection with no user gesture. The
       // user can only click the visible active canvas, so a non-active source is
       // never a legitimate selection.
-      if (m.dgn === 'select' || m.dgn === 'select-set' || m.dgn === 'clear-select') {
+      //
+      // The SAME gate now covers the privileged SOURCE-WRITE relays — `edit-text`
+      // (inline text commit) and `apply-edit` (undo/redo re-application). Both
+      // ride into a main-origin `.tsx` rewrite; a write path is strictly more
+      // dangerous than a selection, yet was previously ungated (ethical-hacker
+      // F-B, DDR-160 follow-up). A background/synced untrusted canvas (DDR-054)
+      // must not drive a gestureless write into another canvas — and inline edits
+      // + Cmd+Z always originate in the ACTIVE canvas the user is looking at, so
+      // a non-active source is never legitimate here either.
+      if (
+        m.dgn === 'select' ||
+        m.dgn === 'select-set' ||
+        m.dgn === 'clear-select' ||
+        m.dgn === 'edit-text' ||
+        m.dgn === 'apply-edit'
+      ) {
         const activeWin =
           activePath && activePath !== SYSTEM_TAB
             ? iframesRef.current.get(activePath)?.contentWindow
@@ -8253,10 +8489,12 @@ function App() {
         if (e.source !== activeWin) return;
       }
       if (m.dgn === 'select' && m.selection) {
+        setPhotoSel(null); // a DOM selection supersedes an annotation-image Photo target
         wsSend({ type: 'select', selection: m.selection });
         setSelected(m.selection);
         maybeAutoOpenInspectorOnSelect(m.selection); // Stage C
       } else if (m.dgn === 'select-set') {
+        setPhotoSel(null);
         // Canvas multi-select. Payload shape:
         //   null              → empty selection
         //   Selection         → length-1 (back-compat with legacy single-element shape)
@@ -8280,6 +8518,7 @@ function App() {
           maybeAutoOpenInspectorOnSelect(payload); // Stage C
         }
       } else if (m.dgn === 'clear-select') {
+        setPhotoSel(null);
         wsSend({ type: 'clear-select' });
         setSelected(null);
       } else if (m.dgn === 'edit-text' && m.id) {
@@ -8301,7 +8540,15 @@ function App() {
         fetch('/_api/edit-text', {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ canvas: m.file, id: m.id, text: m.text ?? '' }),
+          body: JSON.stringify({
+            canvas: m.file,
+            id: m.id,
+            text: m.text ?? '',
+            // Context for editing `{variable}` text — which rendered instance +
+            // its pre-edit text, so the engine targets the right source string.
+            ...(typeof m.occurrence === 'number' ? { occurrence: m.occurrence } : {}),
+            ...(typeof m.before === 'string' ? { before: m.before } : {}),
+          }),
         })
           .then((r) => r.json().catch(() => ({})))
           .then((j) => {
@@ -8334,6 +8581,11 @@ function App() {
         } else {
           url = '/_api/edit-text';
           body = { canvas: m.canvas, id: m.id, text: value ?? '' };
+          // Undo/redo of a `{variable}` text edit needs to re-target the source
+          // string: the occurrence + the value currently on disk (`from` — the
+          // side we're replacing FROM). Harmless for literal text.
+          if (typeof m.occurrence === 'number') body.occurrence = m.occurrence;
+          if (typeof m.from === 'string') body.before = m.from;
         }
         editApplyChainRef.current = editApplyChainRef.current
           .catch(() => {})
@@ -8510,38 +8762,54 @@ function App() {
         const activeWin = activePath ? iframesRef.current.get(activePath)?.contentWindow : null;
         if (e.source === activeWin && typeof m.id === 'string') pasteStyleRef.current?.(m.id);
       } else if (m.dgn === 'insert-request') {
-        // Stage I3 — insert a synthesized div/text/image relative to `refId`.
+        // Stage I3 — insert a synthesized div/text/image relative to `refId`,
+        // OR — empty-artboard fallback (tool-palette "+ Element" on a fresh
+        // artboard with no elements yet) — as a child of `artboardId`. Exactly
+        // one of the two must be present; the artboardId variant only makes
+        // sense inside-start/inside-end (no sibling to be before/after).
         const activeWin = activePath ? iframesRef.current.get(activePath)?.contentWindow : null;
+        const hasRefId = typeof m.refId === 'string';
+        const hasArtboardId = typeof m.artboardId === 'string';
+        const okPosition =
+          m.position === 'before' ||
+          m.position === 'after' ||
+          m.position === 'inside-start' ||
+          m.position === 'inside-end';
         const okShape =
-          typeof m.refId === 'string' &&
+          hasRefId !== hasArtboardId &&
           (m.kind === 'div' || m.kind === 'text' || m.kind === 'image') &&
-          (m.position === 'before' ||
-            m.position === 'after' ||
-            m.position === 'inside-start' ||
-            m.position === 'inside-end');
+          okPosition &&
+          (!hasArtboardId || m.position === 'inside-start' || m.position === 'inside-end');
         if (e.source === activeWin && okShape) {
           insertElementShellRef.current?.(m.refId, m.position, m.kind, {
+            artboardId: hasArtboardId ? m.artboardId : undefined,
             src: typeof m.src === 'string' ? m.src : undefined,
             refIndex: Number.isInteger(m.refIndex) ? m.refIndex : undefined,
           });
         }
       } else if (m.dgn === 'insert-image-request') {
-        // Stage F/I3 — "Insert ▸ Image" from the canvas context menu. An image
-        // needs a contained asset src, so the shell opens the AssetPicker; the
-        // pick then drives insertElementShell(kind:'image'). Confused-deputy
-        // gated + pinned to the active canvas like the other request verbs.
+        // Stage F/I3 — "Insert ▸ Image" from the canvas context menu, or the
+        // tool-palette's empty-artboard fallback (`artboardId` in place of
+        // `refId`). An image needs a contained asset src, so the shell opens
+        // the AssetPicker; the pick then drives insertElementShell(kind:'image').
+        // Confused-deputy gated + pinned to the active canvas like the other
+        // request verbs.
         const activeWin = activePath ? iframesRef.current.get(activePath)?.contentWindow : null;
+        const hasRefId = typeof m.refId === 'string';
+        const hasArtboardId = typeof m.artboardId === 'string';
         const okShape =
-          typeof m.refId === 'string' &&
+          hasRefId !== hasArtboardId &&
           (m.position === 'before' ||
             m.position === 'after' ||
             m.position === 'inside-start' ||
-            m.position === 'inside-end');
+            m.position === 'inside-end') &&
+          (!hasArtboardId || m.position === 'inside-start' || m.position === 'inside-end');
         if (e.source === activeWin && okShape) {
           openAssetPickerRef.current?.({
             purpose: 'insert-image',
             canvas: activePath,
             refId: m.refId,
+            artboardId: hasArtboardId ? m.artboardId : undefined,
             position: m.position,
             refIndex: Number.isInteger(m.refIndex) ? m.refIndex : undefined,
           });
@@ -8573,6 +8841,27 @@ function App() {
             before: typeof m.before === 'string' ? m.before : null,
           });
         }
+      } else if (m.dgn === 'edit-annotation-photo-request') {
+        // feature-photo-editor (Task 17) — "Edit Photo…" on an annotation
+        // ImageStroke. The annotation model has no data-cd-id / DOM selection, so
+        // it can't ride the normal select path; instead the canvas posts its
+        // `assets/<sha8>.<ext>` href up and the shell opens the Photo-only tab on
+        // it. Same confused-deputy gate (DDR-054) + active-canvas pin as F3.
+        const activeWin = activePath ? iframesRef.current.get(activePath)?.contentWindow : null;
+        const asset = PHOTO_ASSET_RE.exec(typeof m.asset === 'string' ? m.asset : '')?.[0] || null;
+        if (e.source === activeWin && typeof m.id === 'string' && asset) {
+          setPhotoSel({ asset, strokeId: m.id });
+          openRightPanel('inspector');
+          setInspectorTab('photo');
+        }
+      } else if (m.dgn === 'open-sticker-picker') {
+        // Phase 4 (whiteboard-improvements) — the toolbar's Stickers button.
+        // Confused-deputy gated + pinned to the active canvas like the other
+        // request verbs above.
+        const activeWin = activePath ? iframesRef.current.get(activePath)?.contentWindow : null;
+        if (e.source === activeWin) {
+          openStickerPickerRef.current?.({ canvas: activePath });
+        }
       } else if (m.dgn === 'insert-artboard-request') {
         // Stage I4 — insert a new empty artboard from a screen-size preset.
         const activeWin = activePath ? iframesRef.current.get(activePath)?.contentWindow : null;
@@ -8609,7 +8898,12 @@ function App() {
         }
       } else if (m.dgn === 'open-inspector') {
         // Phase 12 — context-menu "Inspect" / tool-palette Inspect opens the right panel.
+        // feature-photo-editor (Task 16) — an optional `tab` lands the panel on a
+        // specific tab (the element "Edit Photo…" entry passes `tab: 'photo'`; the
+        // img is already selected via select-set, so the Photo tab derives its
+        // target from that selection's `photoAsset`).
         openRightPanel('inspector');
+        if (typeof m.tab === 'string') setInspectorTab(m.tab);
       } else if (m.dgn === 'present-enter') {
         // Canvas tool-palette "Presentation mode" button — Present Mode is a
         // shell-level state (hides the menubar / sidebar / panels), so the
@@ -8703,6 +8997,23 @@ function App() {
             height: Math.max(1, Math.round(Number(c.height) || 0)),
           }));
         setActiveComps(safe);
+        // rca/issue-video-artboard-frame-reset-on-edit — the SAME comp
+        // re-announcing means its Player just remounted (an edit-triggered
+        // HMR remount, or a ⌘R hard iframe reload that wiped video-comp.tsx's
+        // own module-scope frame mirror too). The shell's `timelineFrame`
+        // survives either way (this component doesn't remount) — push it back
+        // down so the fresh Player opens where the Timeline left off, instead
+        // of the poster-frame default. Skip on a genuinely new comp/canvas
+        // (no prior id, or frame still at its post-switch 0).
+        const prevCompId = timelineCompIdRef.current;
+        const stillPresent = prevCompId && safe.some((c) => c.id === prevCompId);
+        if (stillPresent && timelineFrameRef.current > 0) {
+          postToActiveCanvas({
+            dgn: 'timeline-seek',
+            frame: timelineFrameRef.current,
+            id: prevCompId,
+          });
+        }
       } else if (m.dgn === 'timeline-frame' && typeof m.frame === 'number') {
         // Live playhead mirror from the Player (preview scrub/playback).
         const activeWin =
@@ -8714,6 +9025,17 @@ function App() {
         // artboard's Player must not fight it for the readout (multi-comp canvas).
         if (m.id && timelineCompIdRef.current && m.id !== timelineCompIdRef.current) return;
         if (Number.isFinite(m.frame)) setTimelineFrame(Math.max(0, Math.round(m.frame)));
+      } else if (m.dgn === 'timeline-ended') {
+        // The Player stopped itself at the last frame (loop off) — resync the
+        // shell's Play/Pause button, which otherwise has no way to learn
+        // playback ended on its own (rca/issue-video-artboard-loop-defaults-on).
+        const activeWin =
+          activePath && activePath !== SYSTEM_TAB
+            ? iframesRef.current.get(activePath)?.contentWindow
+            : null;
+        if (e.source !== activeWin) return;
+        if (m.id && timelineCompIdRef.current && m.id !== timelineCompIdRef.current) return;
+        setTimelinePlaying(false);
       } else if (m.dgn === 'toggle-palette') {
         // ⌘K pressed while focus was inside the canvas iframe — the injected
         // inspector forwards the chord here since the iframe's keydown never
@@ -8726,6 +9048,8 @@ function App() {
         else if (m.id === 'inspector') toggleRightPanel('inspector');
         else if (m.id === 'assistant' && isNativeApp()) toggleRightPanel('assistant');
         else if (m.id === 'comments') toggleRightPanel('comments');
+        else if (m.id === 'changes') toggleRightPanel('changes');
+        else if (m.id === 'timeline') toggleTimeline();
         else if (m.id === 'export') setExportDialog({ mode: 'export' });
         else if (m.id === 'handoff') setExportDialog({ mode: 'handoff' });
       } else if (m.dgn === 'open-export') {
@@ -8736,6 +9060,11 @@ function App() {
           mode: 'export',
           scope: m.detail && typeof m.detail.scope === 'string' ? m.detail.scope : undefined,
         });
+      } else if (m.dgn === 'open-timeline-request') {
+        // Artboard-chrome context menu's "Open Timeline" (video-comp artboards
+        // only). Scope the Timeline to the right-clicked artboard, then open it.
+        if (typeof m.artboardId === 'string') setCanvasActiveArtboard(m.artboardId.slice(0, 120));
+        setTimelineOpen(true);
       } else if (m.dgn === 'loaded' && m.file) {
         // iframe finished loading — drop the compile skeleton, push current
         // comments + carry over focused pin if any
@@ -8885,6 +9214,7 @@ function App() {
     zoomCtlVisible,
     broadcastChrome,
     activePath,
+    postToActiveCanvas,
   ]);
 
   // Tell the active canvas iframe to drop any persistent selection (canvas
@@ -9269,6 +9599,7 @@ function App() {
         '/_api/insert-element',
         {
           refId,
+          artboardId: typeof opts.artboardId === 'string' ? opts.artboardId : undefined,
           position,
           kind,
           src: typeof opts.src === 'string' ? opts.src : undefined,
@@ -9474,8 +9805,11 @@ function App() {
           t.tagName === 'SELECT' ||
           t.isContentEditable);
       if (editable) return;
-      if (!activePath || activePath === SYSTEM_TAB) return;
+      // Suppress the WKWebView back-nav unconditionally once focus isn't editable —
+      // the activePath/SYSTEM_TAB check below is app logic, not default-action gating,
+      // so it must not gate preventDefault (that gap caused the desktop "Starting…" hang).
       e.preventDefault();
+      if (!activePath || activePath === SYSTEM_TAB) return;
       const one = Array.isArray(selected) ? (selected.length === 1 ? selected[0] : null) : selected;
       if (one?.artboardId && !one.id) deleteArtboardShell(one.artboardId);
     };
@@ -9491,6 +9825,16 @@ function App() {
   useEffect(() => {
     openAssetPickerRef.current = (req) => setAssetPickerReq(req);
   }, []);
+
+  // Phase 4 (whiteboard-improvements) — { canvas: activePath } when open, null
+  // when closed. Mirrors assetPickerReq's ref-indirection (the message
+  // listener below is set up with a minimal dep array, so it reaches a FRESH
+  // opener via a ref rather than needing setStickerPickerReq in its own deps).
+  const [stickerPickerReq, setStickerPickerReq] = useState(null);
+  const openStickerPickerRef = useRef(null);
+  useEffect(() => {
+    openStickerPickerRef.current = (req) => setStickerPickerReq(req);
+  }, []);
   const onAssetPicked = useCallback(
     (pickedPath) => {
       const req = assetPickerReq;
@@ -9506,6 +9850,7 @@ function App() {
       }
       if (req.purpose === 'insert-image') {
         insertElementShell(req.refId, req.position || 'after', 'image', {
+          artboardId: req.artboardId,
           src: pickedPath,
           refIndex: req.refIndex,
         });
@@ -9551,6 +9896,47 @@ function App() {
     },
     [assetPickerReq, insertElementShell, activePath, recordSourceEdit, postToActiveCanvas]
   );
+
+  // Phase 4 (whiteboard-improvements) — a bundled sticker has no project asset
+  // path yet (it lives in MAUDE's own STICKERS_DIR, main-origin-only per
+  // DDR-054), so re-upload its bytes through the SAME /_api/asset lane every
+  // other image source uses (content-addressed, canvas-origin-allowlisted) —
+  // then relay the resulting project-relative path down to the canvas exactly
+  // like replace-annotation-media above (the annotation model owns its own
+  // strokes; the shell performs no stroke write of its own).
+  const onStickerPicked = useCallback(
+    async (sticker) => {
+      const req = stickerPickerReq;
+      setStickerPickerReq(null);
+      if (!req || !sticker?.url) return;
+      // G3 security (DDR-152) — same re-check as onAssetPicked: the request
+      // captured the active canvas when the picker opened; abort rather than
+      // insert into whatever canvas happens to be active now.
+      if (req.canvas && req.canvas !== activePath) {
+        console.warn('[sticker-picker] active canvas changed since request — aborting');
+        return;
+      }
+      try {
+        const blob = await fetch(sticker.url).then((r) =>
+          r.ok ? r.blob() : Promise.reject(new Error(`HTTP ${r.status}`))
+        );
+        const res = await fetch('/_api/asset', {
+          method: 'POST',
+          headers: { 'content-type': blob.type || 'image/png' },
+          body: blob,
+        });
+        const j = await res.json().catch(() => ({}));
+        if (!res.ok || !j.path) {
+          console.warn('[sticker-picker]', j.error || `upload failed (HTTP ${res.status})`);
+          return;
+        }
+        postToActiveCanvas({ dgn: 'insert-sticker', path: j.path });
+      } catch {
+        console.warn('[sticker-picker] could not load or upload that sticker');
+      }
+    },
+    [stickerPickerReq, activePath, postToActiveCanvas]
+  );
   // Media-section "Replace…" (CssKnobs) → open the picker in replace mode with
   // the element's current src as the undo before-value (captured from the
   // Selection's `attrs.src`, not the resolved URL).
@@ -9654,8 +10040,19 @@ function App() {
           ) {
             return; // the timeline shortcuts effect claims it
           }
-          e.preventDefault();
           const redo = e.key === 'y' || e.key === 'Y' || e.shiftKey;
+          // feature-photo-editor — photo edits are sidecar writes (`/_api/photo-edit`),
+          // invisible to the canvas's own source-edit undo stack, so they need
+          // their own owner here. Claims the keypress only while the Photo tab
+          // is the one on screen AND it actually has something to undo/redo —
+          // otherwise falls through to the canvas stack as before. (Focus still
+          // inside a Photo-tab slider is handled separately by
+          // `onPhotoKnobKeyDown`, mirroring `onKnobKeyDown` for CSS knobs.)
+          if (inspectorTab === 'photo' && performPhotoUndo(redo)) {
+            e.preventDefault();
+            return;
+          }
+          e.preventDefault();
           postToActiveCanvas({ dgn: redo ? 'redo' : 'undo' });
           return;
         }
@@ -9713,6 +10110,12 @@ function App() {
         setExportDialog({ mode: 'handoff' });
         return;
       }
+      // Cmd+Shift+T — toggle the Timeline (video-comp scrub) dock.
+      if (meta && e.shiftKey && (e.key === 't' || e.key === 'T')) {
+        e.preventDefault();
+        toggleTimeline();
+        return;
+      }
       // Cmd+C / Ctrl+C — Phase 4.1 removed the shell-side comment-drop chord.
       // Canvas comment-drop is the `C` tool letter (press C in the canvas,
       // then click the element) or right-click "Add comment". Cmd+C now
@@ -9828,6 +10231,9 @@ function App() {
     clearActiveCanvasSelection,
     presentMode,
     exitPresent,
+    toggleTimeline,
+    inspectorTab,
+    performPhotoUndo,
   ]);
 
   const registerIframe = useCallback((path, el) => {
@@ -10120,6 +10526,8 @@ function App() {
             dirtyByPath={dirtyByPath}
             project={project}
             gitBranch={gitStatus?.branch}
+            remoteSync={remoteSync}
+            onGetLatest={gitGetLatest}
           />
           {sidebarOpen && (
             <PanelGrip
@@ -10202,6 +10610,12 @@ function App() {
               onResizeArtboard={resizeArtboardShell}
               editScope={editScope}
               onUndoRedo={(dir) => postToActiveCanvas({ dgn: dir })}
+              photoSel={photoSel}
+              photoRev={photoRev}
+              onPhotoEdit={onPhotoEdit}
+              onPhotoRemoveBackground={onPhotoRemoveBackground}
+              onPhotoRecordEdit={onPhotoRecordEdit}
+              onPhotoUndoRedo={(dir) => performPhotoUndo(dir === 'redo')}
               layersTree={layersTree}
               canvasFile={activePath}
               onSelectLayer={(n) =>
@@ -10665,6 +11079,9 @@ function App() {
           onClose={() => setAssetPickerReq(null)}
         />
       )}
+      {stickerPickerReq && (
+        <StickerPicker onPick={onStickerPicked} onClose={() => setStickerPickerReq(null)} />
+      )}
       {diffTarget && (
         <DiffView
           target={diffTarget}