@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/canvas-list-watch.ts

@@ -0,0 +1,177 @@
+// External-canvas list watcher.
+//
+// The browser file tree re-reads `/_index-data` only when it receives a
+// `canvas-list-update` WS message. Until now that message was emitted ONLY by
+// the dev-server's own create/delete API (`api.ts` createCanvas / deleteCanvas),
+// so a canvas written straight to disk by something OUTSIDE the server — the ACP
+// chat agent running `/design:new`, an agent `Write`, `git checkout`, a terminal
+// `cp`/`rm` — never refreshed the tree. The file landed on disk, `fs:any` fired,
+// the HMR/activity/git-status subscribers reacted, but the tree stayed stale
+// until a full page reload. See `.ai/logs/rca/issue-acp-new-canvas-not-in-filetree.md`.
+//
+// This is the symmetric server-side counterpart: subscribe to `fs:any`, and when
+// the set of openable canvas files under the configured canvas groups changes
+// (add or remove), emit the same `canvas-list-update` the API does. The client's
+// handler just calls `loadTree()` (a wholesale `/_index-data` re-read), so a
+// nudge is all that's required — the diff makes it precise enough to skip every
+// non-structural edit (a canvas body save, a `.meta.json` rewrite) and so avoid
+// thrashing the tree on every `/design:edit`.
+//
+// Bun-native (DDR-009); the canvas listing reuses `findHtmlFiles` and the slug
+// reuses `canvasSlugFromRel`, both from api.ts — the single source of truth that
+// also backs `/_index-data` and the UI create/delete emits (no duplicated
+// SKIP_DIRS / group rules to drift; DDR-115 runtime-state exclusions come along
+// for free because `findHtmlFiles` already skips `_`-prefixed + SKIP_DIRS paths).
+
+import path from 'node:path';
+
+import { canvasSlugFromRel, findHtmlFiles, SKIP_DIRS } from './api.ts';
+import type { Context } from './context.ts';
+
+/** Burst-collapse window. A new canvas writes both `.tsx` and `.meta.json`; a
+ * git checkout touches many files at once — one snapshot per quiet window. */
+export const CANVAS_LIST_DEBOUNCE_MS = 150;
+
+/**
+ * Cheap gate: is this `fs:any` path worth a (debounced) full recompute? True
+ * only for an openable canvas file (`.tsx` / `.html`) that lives under one of
+ * the configured canvas groups and carries no `_`-prefixed or SKIP_DIRS segment.
+ * A loose gate just means an occasional needless recompute — never a wrong emit,
+ * since `snapshot()` is authoritative. Input is design-root-relative (the shape
+ * fs-watch emits, e.g. `ui/project/Pricing.tsx`).
+ *
+ * Pure — no disk access. Accepts back-slash or forward-slash input.
+ */
+export function isCanvasCandidate(rel: string, groupPaths: string[]): boolean {
+  if (typeof rel !== 'string') return false;
+  const p = rel.replace(/\\/g, '/').replace(/^\/+/, '');
+  if (!p) return false;
+  const low = p.toLowerCase();
+  if (!low.endsWith('.tsx') && !low.endsWith('.html')) return false;
+  const segs = p.split('/');
+  for (const s of segs) {
+    if (!s) return false;
+    if (s.startsWith('_')) return false;
+    if (SKIP_DIRS.has(s)) return false;
+  }
+  return groupPaths.some((gp) => {
+    const g = gp.replace(/^\/+|\/+$/g, '');
+    return !!g && (p === g || p.startsWith(`${g}/`));
+  });
+}
+
+export interface CanvasListWatch {
+  /** Resolves once the initial canvas set has been seeded (no emit). */
+  readonly ready: Promise<void>;
+  /** Test seam — force a recompute + diff + emit. Serialized after the seed and
+   * any in-flight refresh, so a create observed between calls always diffs
+   * against the pre-create set. */
+  refresh(): Promise<void>;
+  /** Current known openable-canvas set (design-rel-prefixed). For assertions. */
+  readonly known: ReadonlySet<string>;
+  stop(): void;
+}
+
+export interface CanvasListWatchOptions {
+  debounceMs?: number;
+}
+
+export function createCanvasListWatch(
+  ctx: Context,
+  opts: CanvasListWatchOptions = {}
+): CanvasListWatch {
+  const debounceMs = opts.debounceMs ?? CANVAS_LIST_DEBOUNCE_MS;
+  // Mirror /_index-data's group set exactly (cfg.canvasGroups) — NOT api.ts's
+  // create-allowlist, which additionally permits cfg.newCanvasDir. On the
+  // default config newCanvasDir IS a group; a config pointing it outside
+  // canvasGroups would have the canvas absent from /_index-data too, so the
+  // watcher stays consistent with what the tree can actually show.
+  const groupPaths = (ctx.cfg.canvasGroups ?? []).map((g) => g.path);
+
+  // null = not yet seeded; the first refresh captures the baseline and emits
+  // nothing (canvases already on disk at boot aren't "added").
+  let known: Set<string> | null = null;
+  let chain: Promise<void> = Promise.resolve();
+  let pending: ReturnType<typeof setTimeout> | null = null;
+
+  async function snapshot(): Promise<Set<string>> {
+    const out = new Set<string>();
+    for (const g of ctx.cfg.canvasGroups ?? []) {
+      const groupAbs = path.join(ctx.paths.designRoot, g.path);
+      const groupRel = path.posix.join(ctx.paths.designRel, g.path);
+      let files: string[];
+      try {
+        files = await findHtmlFiles(groupAbs, groupRel);
+      } catch {
+        continue; // group dir missing / unreadable — treat as empty
+      }
+      for (const f of files) out.add(f);
+    }
+    return out;
+  }
+
+  function emit(action: 'added' | 'removed', rel: string) {
+    // `rel` from findHtmlFiles is designRel-prefixed (`.design/ui/X.tsx`); strip
+    // the prefix so the wire shape matches api.ts's group-relative emit
+    // (`ui/X.tsx`). The client IGNORES the payload entirely — it just re-reads
+    // /_index-data — so rel/slug are advisory only. SECURITY TRIPWIRE: any FUTURE
+    // consumer of this event must treat rel/slug as ATTACKER-CONTROLLED (agent /
+    // `git checkout`-authored filenames) and must NOT feed them to a
+    // render/open/build sink without re-validating against /_index-data.
+    const prefix = `${ctx.paths.designRel.replace(/^\/+|\/+$/g, '')}/`;
+    const relOut = rel.startsWith(prefix) ? rel.slice(prefix.length) : rel;
+    ctx.bus.emit('canvas-list-update', {
+      action,
+      rel: relOut,
+      slug: canvasSlugFromRel(rel, ctx.paths.designRel),
+    });
+  }
+
+  async function doRefresh(): Promise<void> {
+    const next = await snapshot();
+    if (known === null) {
+      known = next; // seed — no emit
+      return;
+    }
+    for (const rel of next) if (!known.has(rel)) emit('added', rel);
+    for (const rel of known) if (!next.has(rel)) emit('removed', rel);
+    known = next;
+  }
+
+  // Serialize every recompute through one chain so the boot-time seed always
+  // runs first and concurrent snapshots can't race a create into a missed diff.
+  function refresh(): Promise<void> {
+    chain = chain.then(doRefresh, doRefresh);
+    return chain;
+  }
+
+  const ready = refresh(); // seed at construction
+
+  function schedule() {
+    if (pending) clearTimeout(pending);
+    pending = setTimeout(() => {
+      pending = null;
+      void refresh();
+    }, debounceMs);
+  }
+
+  const off = ctx.bus.on('fs:any', (rel: string) => {
+    if (!isCanvasCandidate(rel, groupPaths)) return;
+    schedule();
+  });
+
+  function stop() {
+    off();
+    if (pending) clearTimeout(pending);
+    pending = null;
+  }
+
+  return {
+    ready,
+    refresh,
+    get known() {
+      return known ?? new Set<string>();
+    },
+    stop,
+  };
+}

package/apps/studio/canvas-shell.tsx

@@ -82,6 +82,7 @@ import {
   useAnnotationSelectionOptional,
 } from './use-annotation-selection.tsx';
 import { AnnotationsVisibilityProvider } from './use-annotations-visibility.tsx';
+import { ChromeVisibilityProvider, useChromeVisibility } from './use-chrome-visibility.tsx';
 import { useCollab } from './use-collab.tsx';
 import { useCursorModifiers } from './use-cursor-modifiers.tsx';
 import { useKeyboardDiscipline } from './use-keyboard-discipline.tsx';
@@ -302,6 +303,14 @@ const HALO_CSS = `
   -webkit-font-smoothing: subpixel-antialiased;
   font-smooth: always;
 }
+/* Phase 12 (DDR-103) — inline text editing: the element being edited carries an
+   accent ring + caret. plaintext-only contenteditable; commit writes to source. */
+[contenteditable].dc-text-editing {
+  outline: 2px solid var(--maude-hud-accent, #0d99ff);
+  outline-offset: 1px;
+  border-radius: 1px;
+  cursor: text;
+}
 `.trim();
 
 function ensureHaloStyles(): void {
@@ -322,6 +331,104 @@ function ensureHaloStyles(): void {
   document.head.appendChild(s);
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Layers tree (Phase 12 Task 4, DDR-103). The shell's Layers tab is a browsable
+// tree of the active artboard's stamped (`data-cd-id`) elements. We walk the
+// artboard subtree in the iframe, serialize a nested tree, and post it to the
+// shell; the shell renders it + posts back `select-by-id` / `highlight`.
+
+interface LayerNode {
+  id: string;
+  tag: string;
+  label: string;
+  type: string;
+  /** Occurrence index of this id within the artboard — matches the resolver's
+   *  `querySelectorAll([data-dc-screen=…] [data-cd-id=…])[index]`. */
+  index: number;
+  children: LayerNode[];
+}
+
+function kebabToTitle(s: string): string {
+  return s
+    .split('-')
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+// Human label: data-dc-element (Title Case) → aria-label → role → tag(.class).
+function layerLabel(el: Element): string {
+  const dc = el.getAttribute('data-dc-element');
+  if (dc) return kebabToTitle(dc);
+  const aria = el.getAttribute('aria-label');
+  if (aria) return aria.slice(0, 40);
+  const role = el.getAttribute('role');
+  if (role) return role;
+  const tag = el.tagName.toLowerCase();
+  const cls = realClasses(el).split(/\s+/).filter(Boolean)[0];
+  return cls ? `${tag}.${cls}` : tag;
+}
+
+function layerType(el: Element): string {
+  const tag = el.tagName.toLowerCase();
+  const role = el.getAttribute('role') ?? '';
+  const dc = el.getAttribute('data-dc-element') ?? '';
+  if (tag === 'button' || role === 'button' || /(^|-)(btn|cta|button)(-|$)/.test(dc))
+    return 'button';
+  if (/^h[1-6]$/.test(tag) || role === 'heading') return 'heading';
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') return 'input';
+  if (tag === 'img' || tag === 'svg' || tag === 'picture' || tag === 'video') return 'image';
+  if (tag === 'a') return 'link';
+  if (tag === 'ul' || tag === 'ol' || tag === 'li') return 'list';
+  if (tag === 'nav') return 'nav';
+  if (tag === 'form') return 'form';
+  if (tag === 'p' || tag === 'span' || tag === 'label') return 'text';
+  return 'box';
+}
+
+function serializeArtboardTree(root: Element): LayerNode[] {
+  const seen = new Map<string, number>();
+  function walk(el: Element): LayerNode[] {
+    const out: LayerNode[] = [];
+    for (const child of Array.from(el.children)) {
+      // Skip dev-server overlay chrome (pins, halos) that lives inside the artboard.
+      if (child.closest('.dgn-pin, .dc-cv-halo, .dc-cv-group-bbox')) continue;
+      const cd = child.getAttribute('data-cd-id');
+      if (cd) {
+        const idx = seen.get(cd) ?? 0;
+        seen.set(cd, idx + 1);
+        out.push({
+          id: cd,
+          tag: child.tagName.toLowerCase(),
+          label: layerLabel(child),
+          type: layerType(child),
+          index: idx,
+          children: walk(child),
+        });
+      } else {
+        // Unstamped wrapper — descend so its stamped descendants still surface.
+        out.push(...walk(child));
+      }
+    }
+    return out;
+  }
+  return walk(root);
+}
+
+function postLayersTree(artboardId: string | null | undefined): void {
+  if (typeof document === 'undefined' || !artboardId) return;
+  const root = document.querySelector(`[data-dc-screen="${CSS.escape(artboardId)}"]`);
+  if (!root) return;
+  try {
+    window.parent.postMessage(
+      { dgn: 'layers-tree', artboardId, tree: serializeArtboardTree(root) },
+      '*'
+    );
+  } catch {
+    /* detached / cross-origin */
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Shell
 
@@ -375,7 +482,9 @@ export function CanvasShell({
     <MaybeSelectionSetProvider>
       <AnnotationSelectionProvider>
         <AnnotationsVisibilityProvider>
-          <CanvasCore hostRef={hostRef}>{children}</CanvasCore>
+          <ChromeVisibilityProvider>
+            <CanvasCore hostRef={hostRef}>{children}</CanvasCore>
+          </ChromeVisibilityProvider>
         </AnnotationsVisibilityProvider>
       </AnnotationSelectionProvider>
     </MaybeSelectionSetProvider>
@@ -434,7 +543,7 @@ function CanvasCore({
     if (!host) return;
     const onDbl = (e: MouseEvent) => {
       const t = e.target as Element | null;
-      if (!t || !t.closest) return;
+      if (!t?.closest) return;
       // Floating chrome / overlays / drawn user content / any artboard
       // surface → leave alone. Only dblclick that lands on the canvas
       // background outside every artboard triggers `fit()`.
@@ -517,7 +626,7 @@ function CanvasCore({
   useEffect(() => {
     if (!collab) return;
     const first = selSet.selected[0];
-    if (!first || !first.selector) {
+    if (!first?.selector) {
       collab.publishAwareness({ selection: null });
       return;
     }
@@ -947,7 +1056,7 @@ function applyArtboardFollowers(): void {
 function buildRegistry(deps: {
   controller: ViewportControllerHandle | null;
   clearSelection: () => void;
-  selSet: { selected: Selection[] };
+  selSet: { selected: Selection[]; replace: (s: Selection | Selection[]) => void };
   distributeArtboards: (axis: 'x' | 'y') => void;
   alignArtboards: (mode: 'left' | 'right' | 'center-x' | 'top' | 'bottom' | 'center-y') => void;
   focusArtboard: (artboardId: string) => void;
@@ -1109,9 +1218,24 @@ function buildRegistry(deps: {
           id: 'inspect',
           label: 'Inspect',
           shortcut: '⌥I',
-          disabled: true,
-          onSelect: () => {
-            console.warn('[context-menu] TODO: tweaks panel for TSX canvases');
+          onSelect: (target) => {
+            // Phase 12 — select the right-clicked element + open the shell's
+            // right Inspector panel (Inspect / Layers / CSS). Was a disabled TODO
+            // before the inspector shipped.
+            if (target.el) {
+              selSet.replace(
+                hoverTargetToSelection({
+                  el: target.el,
+                  cdId: target.cdId ?? null,
+                  artboardId: target.artboardId ?? null,
+                } as HoverTarget)
+              );
+            }
+            try {
+              window.parent.postMessage({ dgn: 'open-inspector' }, '*');
+            } catch {
+              /* detached / cross-origin */
+            }
           },
         },
       ],
@@ -1248,6 +1372,13 @@ function CanvasRouter({
   const annotSel = useAnnotationSelection();
   const ctxMenu = useContextMenu();
   const undoStack = useUndoStack();
+  // Shell View-menu zoom bridge (dgn:'zoom') — same controller the zoom pill uses.
+  const zoomController = useViewportControllerContext();
+  // Shell View-menu chrome-visibility bridge (dgn:'view-chrome') — minimap /
+  // zoom-controls toggles + Presentation Mode. Drives the shared chrome store
+  // the floating chrome (DCMiniMap, DCZoomToolbar, ToolPalette, AnnotationsLayer)
+  // consumes.
+  const chromeCtx = useChromeVisibility();
 
   // Hover state drives the floating .dc-cv-halo--hover overlay. The overlay
   // itself reads getBoundingClientRect on every rAF tick to follow pan/zoom.
@@ -1312,6 +1443,87 @@ function CanvasRouter({
         void undoStack.redo();
         return;
       }
+      // Phase 12 Task 4 (DDR-103) — Layers-tree round-trip. select-by-id resolves
+      // the node + replaces the selection (which posts select-set back, updating
+      // the Inspect/CSS tabs + halos); highlight shows the transient hover halo;
+      // request-layers re-walks + posts the tree for an artboard.
+      if (m.dgn === 'select-by-id') {
+        const mm = m as { id?: string; artboardId?: string | null; index?: number };
+        if (mm.id) {
+          const target = resolveSelectionEl(document, {
+            id: mm.id,
+            artboardId: mm.artboardId,
+            index: mm.index,
+          });
+          if (target) {
+            selSet.replace(
+              hoverTargetToSelection({
+                el: target,
+                cdId: mm.id,
+                artboardId: mm.artboardId ?? null,
+              } as HoverTarget)
+            );
+            (target as HTMLElement).scrollIntoView?.({ block: 'nearest', behavior: 'smooth' });
+          }
+        }
+        return;
+      }
+      if (m.dgn === 'highlight') {
+        const mm = m as { id?: string; artboardId?: string | null; index?: number };
+        setHoverEl(
+          mm.id
+            ? resolveSelectionEl(document, {
+                id: mm.id,
+                artboardId: mm.artboardId,
+                index: mm.index,
+              })
+            : null
+        );
+        return;
+      }
+      // Phase 12.3 (W1.1) — optimistic inline-style apply. The CSS panel posts
+      // this on commit so the selected element updates INSTANTLY, before the
+      // edit-css → file-watcher HMR reload re-renders from source. `value` null/
+      // empty removes the property (the reset path). Purely a live-DOM preview;
+      // the authoritative value is whatever the reload renders from source.
+      // SECURITY (ethical-hacker A1/A2) — accept apply-style ONLY from the parent
+      // shell, never from a canvas self-post. The canvas iframe is untrusted
+      // (DDR-054); without this gate hostile canvas JS could repaint elements AND
+      // (paired with the reload echo-guard) suppress reloads to desync view/source.
+      // The reload-suppression timestamp now lives in _shell.html's closure (NOT a
+      // canvas-writable window global) — set there from the same parent-gated msg.
+      if (m.dgn === 'apply-style') {
+        if (e.source !== window.parent) return;
+        const mm = m as {
+          id?: string;
+          artboardId?: string | null;
+          index?: number;
+          prop?: string;
+          value?: string | null;
+        };
+        if (mm.id && mm.prop) {
+          const target = resolveSelectionEl(document, {
+            id: mm.id,
+            artboardId: mm.artboardId,
+            index: mm.index,
+          });
+          if (target) {
+            const style = (target as HTMLElement).style;
+            try {
+              // Live-DOM preview only; the reload renders the authoritative value.
+              if (mm.value == null || mm.value === '') style.removeProperty(mm.prop);
+              else style.setProperty(mm.prop, mm.value);
+            } catch {
+              /* invalid prop/value — ignore; the reload is the source of truth */
+            }
+          }
+        }
+        return;
+      }
+      if (m.dgn === 'request-layers') {
+        postLayersTree((m as { artboardId?: string }).artboardId ?? null);
+        return;
+      }
       // D9 — canvas-shell chrome follows the Maude chrome theme. The chrome's
       // `--maude-chrome-*` token family is keyed by `data-maude-theme` on the
       // iframe documentElement (see HUD_TOKENS_CSS). This attribute is
@@ -1325,10 +1537,113 @@ function CanvasRouter({
         }
         return;
       }
+      // Shell View-menu zoom items — route to the live viewport controller
+      // (the same methods the in-canvas zoom pill calls).
+      if (m.dgn === 'zoom' && zoomController) {
+        const op = (m as { op?: string }).op;
+        if (op === 'in') zoomController.zoomIn();
+        else if (op === 'out') zoomController.zoomOut();
+        else if (op === 'fit') zoomController.fit();
+        else if (op === 'actual') zoomController.reset();
+        return;
+      }
+      // Shell View-menu chrome toggles + Presentation Mode. Only the fields the
+      // shell sends are merged, so a `{ present: true }` enter keeps the user's
+      // individual minimap/zoom toggles for the eventual exit.
+      if (m.dgn === 'view-chrome' && chromeCtx) {
+        const mm = m as { minimap?: boolean; zoom?: boolean; present?: boolean };
+        const patch: { minimap?: boolean; zoom?: boolean; present?: boolean } = {};
+        if (typeof mm.minimap === 'boolean') patch.minimap = mm.minimap;
+        if (typeof mm.zoom === 'boolean') patch.zoom = mm.zoom;
+        if (typeof mm.present === 'boolean') patch.present = mm.present;
+        chromeCtx.setChrome(patch);
+        return;
+      }
     };
     window.addEventListener('message', onMessage);
     return () => window.removeEventListener('message', onMessage);
-  }, [selSet, annotSel, setTool, undoStack]);
+  }, [selSet, annotSel, setTool, undoStack, zoomController, chromeCtx]);
+
+  // Phase 12 (DDR-103) — double-click a LEAF-TEXT element (children all text
+  // nodes) to edit its copy in place. Commit (blur / Enter) posts `dgn:edit-text`
+  // to the shell, which calls the main-origin /_api/edit-text → editText writes
+  // the escaped JSXText to source; the file-watcher HMR reload re-renders from
+  // the persisted source. Esc restores the original. Mixed/expression elements
+  // are skipped (the engine would refuse them anyway — honest no-op).
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const host = hostRef.current;
+    if (!host) return;
+    let editing: HTMLElement | null = null;
+    let original = '';
+    const onBlur = (): void => commitEdit(true);
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        commitEdit(false);
+      } else if (e.key === 'Enter' && !e.shiftKey) {
+        e.preventDefault();
+        (e.currentTarget as HTMLElement | null)?.blur?.();
+      }
+    };
+    function teardown(elx: HTMLElement): void {
+      elx.removeAttribute('contenteditable');
+      elx.classList.remove('dc-text-editing');
+      elx.removeEventListener('blur', onBlur, true);
+      elx.removeEventListener('keydown', onKey, true);
+    }
+    function commitEdit(commit: boolean): void {
+      const elx = editing;
+      if (!elx) return;
+      editing = null;
+      const text = (elx.textContent ?? '').trim();
+      teardown(elx);
+      if (!commit) {
+        elx.textContent = original;
+        return;
+      }
+      if (text === original.trim()) return;
+      const cdId = elx.getAttribute('data-cd-id');
+      if (!cdId) return;
+      try {
+        window.parent.postMessage({ dgn: 'edit-text', id: cdId, file: deriveFile(), text }, '*');
+      } catch {
+        /* detached / cross-origin */
+      }
+    }
+    const onDbl = (e: MouseEvent): void => {
+      if (editing) return;
+      const t = e.target as HTMLElement | null;
+      const stamped = (t?.closest?.('[data-cd-id]') as HTMLElement | null) ?? null;
+      if (!stamped) return;
+      const kids = Array.from(stamped.childNodes);
+      if (kids.length === 0 || !kids.every((n) => n.nodeType === 3)) return; // leaf-text only
+      e.preventDefault();
+      e.stopPropagation();
+      editing = stamped;
+      original = stamped.textContent ?? '';
+      stamped.setAttribute('contenteditable', 'plaintext-only');
+      stamped.classList.add('dc-text-editing');
+      stamped.addEventListener('blur', onBlur, true);
+      stamped.addEventListener('keydown', onKey, true);
+      stamped.focus();
+      try {
+        const range = document.createRange();
+        range.selectNodeContents(stamped);
+        const sel = window.getSelection();
+        sel?.removeAllRanges();
+        sel?.addRange(range);
+      } catch {
+        /* selection API unavailable */
+      }
+    };
+    // Capture phase so we beat the fit-to-view dblclick handler.
+    host.addEventListener('dblclick', onDbl, true);
+    return () => {
+      host.removeEventListener('dblclick', onDbl, true);
+      if (editing) teardown(editing);
+    };
+  }, [hostRef]);
 
   // Cleanup any pending rAF on unmount.
   useEffect(
@@ -1363,6 +1678,8 @@ function CanvasRouter({
         const sel = hoverTargetToSelection(target);
         if (mode === 'replace') selSet.replace(sel);
         else selSet.add(sel);
+        // Phase 12 Task 4 — refresh the Layers tree for the selected artboard.
+        postLayersTree(target.artboardId);
       },
       onContextMenu: ({ clientX, clientY }) => {
         const target = resolveHoverTarget(document, clientX, clientY, { deep: true });
@@ -1754,7 +2071,7 @@ function HoverHalo({ el }: { el: Element | null }) {
       rafRef.current = null;
       const div = ref.current;
       const t = targetRef.current;
-      if (!div || !t || !t.isConnected) {
+      if (!div || !t?.isConnected) {
         if (div) div.style.display = 'none';
         return;
       }