@1agh/maude 1.4.6 → 1.5.1

package/apps/studio/bin/read-annotations.sh

@@ -1,11 +1,15 @@
 #!/usr/bin/env bash
-# read-annotations.sh — thin wrapper around read-annotations.mjs (the headless
-# SVG → JSON annotation reader). Reached via `maude design read-annotations`
-# (DDR-062), never a raw bin path. The reader is zero-dep Node, so we exec under
-# `node` (always present — maude itself runs on Node), not Bun.
+# read-annotations.sh — thin wrapper around read-annotations.mjs (the AI read
+# verb over the v2 board). Reached via `maude design read-annotations`
+# (DDR-062), never a raw bin path.
 #
 # Usage:
-#   read-annotations.sh <rel-path> [--root <repo>] [--canvas-state <path>]
+#   read-annotations.sh <rel-path> [--in <id>] [--type <t,…>] [--rects <path>] [--graph] [--full]
 #   (see read-annotations.mjs --help for the full contract)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# DDR-242 — the v2 board is read through the TS model: prefer bun (bundled with
+# the app), fall back to node (≥ 22.18 strips TS types natively).
+if command -v bun >/dev/null 2>&1; then
+  exec bun "$SCRIPT_DIR/read-annotations.mjs" "$@"
+fi
 exec node "$SCRIPT_DIR/read-annotations.mjs" "$@"

package/apps/studio/canvas-artifacts.ts

@@ -113,6 +113,15 @@ export function canvasArtifacts(input: { rel: string; paths: Paths }): CanvasArt
   });
   out.push({
     // Versioned — a real git rename on move, which is correct and expected.
+    // DDR-242: the annotations board.
+    abs: path.join(paths.designRoot, `${slug}.annotations.json`),
+    kind: 'slug-keyed',
+    rekey: true,
+    versioned: true,
+  });
+  out.push({
+    // A not-yet-migrated v1 sidecar travels with its canvas until the boot
+    // migration converts it (annotations/migrate-boot.ts).
     abs: path.join(paths.designRoot, `${slug}.annotations.svg`),
     kind: 'slug-keyed',
     rekey: true,

package/apps/studio/canvas-lib.tsx

@@ -265,6 +265,8 @@ const IS_WEBKIT =
 type DcPerfCounters = {
   artboardRenders: number;
   annotationRenders: number;
+  /** Annotation element nodes (re-)rendered — a drag should touch only what moves. */
+  annotationNodeRenders?: number;
   instrumented?: boolean;
 };
 
@@ -1428,7 +1430,17 @@ export function useViewportController(opts: ViewportControllerOptions): Viewport
     // receives events natively.
     const onPointerEnter = () => {
       try {
-        if (typeof window !== 'undefined' && document.activeElement !== host) {
+        const active = document.activeElement as HTMLElement | null;
+        // Never steal focus from something being TYPED into. An editor that
+        // mounts under a stationary pointer (double-click on a standalone
+        // text) makes the engine fire pointerenter on the host; focusing the
+        // host then blurred the editor, and blur commits — so the editor
+        // closed ~5 ms after it opened and a double-click never entered edit.
+        const typing =
+          !!active &&
+          active !== host &&
+          (active.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(active.tagName));
+        if (typeof window !== 'undefined' && active !== host && !typing) {
           host.focus({ preventScroll: true });
         }
       } catch {

package/apps/studio/canvas-shell.tsx

@@ -829,6 +829,12 @@ function CanvasCore({
         return;
       }
       if (t.closest('[data-dc-screen]')) return; // any part of an artboard
+      // Inside anything editable a double-click selects a WORD — the text
+      // editors of stickies / shape labels / texts sit over the world, not over
+      // an artboard, so this used to fit() and throw the view to the top-left
+      // mid-edit (user report 2026-09-30).
+      if (t.closest('[data-annot-editor], input, textarea, select')) return;
+      if ((t as HTMLElement).isContentEditable) return;
       e.preventDefault();
       controller.fit();
     };

package/apps/studio/client/app.jsx

@@ -130,6 +130,16 @@ import { acceptCanvasNotice } from '../canvas-notice-message.ts';
 import { ExportBadge, ExportPanel, ExportToast, useExportCenter } from './export-center.jsx';
 import { ReportBugDialog } from './report-bug.jsx';
 import { useWhatsNew, WhatsNewPanel, WhatsNewToast } from './whats-new.jsx';
+import {
+  collectDirPaths,
+  isDirOpen,
+  pruneDirs,
+  remapDirPrefix,
+  revealPath,
+  setDirOpen,
+  toggleSection as toggleSectionState,
+  useTreeExpansion,
+} from './tree-expansion.js';
 
 const USAGE_TOUR_STORE = 'mdcc-usage-tour-seen';
 // Phase 29 (E4) — the collab "rychlý kurz" is offered once after onboarding.
@@ -138,7 +148,6 @@ const COLLAB_TOUR_STORE = 'mdcc-collab-tour-seen';
 const SYSTEM_TAB = '__system__';
 const THEME_STORE = 'mdcc-theme';
 const SHOW_HIDDEN_STORE = 'mdcc-show-hidden';
-const SECTIONS_STORE = 'mdcc-sections-expanded';
 // DDR-171 — CSS panel vocabulary mode ('advanced' | 'designer'), read inside
 // CssKnobs.
 const CP_MODE_STORE = 'maude-cp-mode';
@@ -330,14 +339,14 @@ function readJsonStore(key, fallback) {
   }
 }
 
-// Section default-open: working sections (project + non-DS canvas groups)
-// open; meta sections (DS + runtime) collapsed. Users can override per-section
-// via the chevron; overrides persist in localStorage.
-function sectionDefaultOpen(g) {
-  if (g.kind === 'runtime') return false;
-  if (g.label === 'Design system') return false;
-  return true;
+// Section default-open: EVERY section starts collapsed (issue #124 — "default
+// should be collapsed"). The user's per-section choice is remembered per
+// project by useTreeExpansion (tree-expansion.js), next to the folder state.
+function sectionDefaultOpen() {
+  return false;
 }
+// Stable empty list for the Sidebar while the tree state hydrates.
+const EMPTY_GROUPS = [];
 
 // ---------- Utility ----------
 
@@ -2155,8 +2164,17 @@ function ExportDialog({
 const TREE_INDENT_BASE = 12;
 const TREE_INDENT_STEP = 16;
 
-function DirRow({ name, depth, defaultOpen, children, dirPath, drag, menu }) {
-  const [open, setOpen] = useState(defaultOpen);
+// Issue #124 — disclosure is CONTROLLED: `expansion` is App's tree state (see
+// tree-expansion.js), so a collapse outlives this row's unmount (dock-tab
+// switch, section toggle, reload). `forceOpen` = an active search; it shows
+// the hits without recording anything.
+function DirRow({ name, depth, children, dirPath, drag, menu, expansion, forceOpen }) {
+  const open = !!forceOpen || !!expansion?.isOpen(dirPath);
+  const setOpen = (v) => {
+    if (forceOpen) return; // search is showing hits — don't record a choice
+    const next = typeof v === 'function' ? v(open) : v;
+    if (next !== open) expansion?.setOpen(dirPath, next);
+  };
   // feature-file-tree-drag-drop-folders (Task 8) — a folder row IS the drop
   // target. `drag` is undefined for groups that can't accept a move (the
   // design-system group) — no handlers attach there, so the browser's default
@@ -2223,8 +2241,13 @@ function DirRow({ name, depth, defaultOpen, children, dirPath, drag, menu }) {
 // Split target: chevron toggles disclosure of the folder's contents; clicking
 // the folder name opens the SystemView focused on that DS (single SystemView
 // for now; the dsName is plumbed through so a future per-DS view can use it).
-function DsFolderRow({ name, dsName, depth, defaultOpen, active, onOpenSystem, children }) {
-  const [open, setOpen] = useState(defaultOpen);
+function DsFolderRow({ name, dsName, dirPath, depth, active, onOpenSystem, children, expansion, forceOpen }) {
+  const open = !!forceOpen || !!expansion?.isOpen(dirPath);
+  const setOpen = (v) => {
+    if (forceOpen) return; // search is showing hits — don't record a choice
+    const next = typeof v === 'function' ? v(open) : v;
+    if (next !== open) expansion?.setOpen(dirPath, next);
+  };
   return (
     <FileTreeItem label={name} expanded={open} selected={active}
       onToggle={() => setOpen(v => !v)} row={
@@ -2613,6 +2636,8 @@ function Tree({
   // feature-file-tree-drag-drop-folders (Task 9) — the shared row-menu
   // instance (useRowMenu()), undefined for groups that can't participate.
   menu,
+  // Issue #124 — App-level folder disclosure `{ isOpen, setOpen }`.
+  expansion,
 }) {
   const dirs = Object.keys(node)
     .filter((k) => k !== '_files')
@@ -2728,6 +2753,7 @@ function Tree({
             dirPath={childPath}
             drag={drag}
             menu={menu}
+            expansion={expansion}
           />
         );
         if (dsMatch && onOpenSystem) {
@@ -2736,8 +2762,10 @@ function Tree({
               key={d}
               name={d}
               dsName={dsMatch.name}
+              dirPath={childPath}
               depth={depth}
-              defaultOpen={true}
+              expansion={expansion}
+              forceOpen={hasSearch}
               active={activePath === SYSTEM_TAB && dsMatch.name === activeDsName}
               onOpenSystem={onOpenSystem}
             >
@@ -2750,8 +2778,9 @@ function Tree({
             key={d}
             name={d}
             depth={depth}
-            defaultOpen={true}
             dirPath={childPath}
+            expansion={expansion}
+            forceOpen={hasSearch}
             drag={drag}
             menu={drag ? menu : undefined}
           >
@@ -2809,6 +2838,8 @@ function Sidebar({
   showHidden,
   sectionsExpanded,
   onToggleSection,
+  // Issue #124 — App-level folder disclosure `{ isOpen, setOpen }`.
+  treeExpansion,
   onNewBoard,
   onDeleteBoard,
   onRefresh,
@@ -3264,6 +3295,7 @@ function Sidebar({
                     dirPath={g.fullPath}
                     drag={!isDs && g.kind === 'canvas' && !readOnly ? treeDrag : undefined}
                     menu={rowMenu}
+                    expansion={treeExpansion}
                   />
                 ) : (
                   <div className="st-tree-empty">{search ? 'No matches.' : 'Empty.'}</div>
@@ -10412,7 +10444,11 @@ function App() {
   const [openMenu, setOpenMenu] = useState(null);
   const [sidebarOpen, setSidebarOpen] = useState(() => readBoolStore(SIDEBAR_STORE, true));
   const [showHidden, setShowHidden] = useState(() => readBoolStore(SHOW_HIDDEN_STORE, false));
-  const [sectionsExpanded, setSectionsExpanded] = useState(() => readJsonStore(SECTIONS_STORE, {}));
+  // Issue #124 — folder + section disclosure of the Files panel, remembered
+  // per project on disk (tree-expansion.js). Absent ⇒ closed.
+  const treeExp = useTreeExpansion();
+  const updateTreeExp = treeExp.update;
+  const sectionsExpanded = treeExp.state.sections;
   const [helpOpen, setHelpOpen] = useState(false);
   const [reportBugOpen, setReportBugOpen] = useState(false);
 
@@ -11748,11 +11784,6 @@ function App() {
       localStorage.setItem(SHOW_HIDDEN_STORE, showHidden ? '1' : '0');
     } catch {}
   }, [showHidden]);
-  useEffect(() => {
-    try {
-      localStorage.setItem(SECTIONS_STORE, JSON.stringify(sectionsExpanded));
-    } catch {}
-  }, [sectionsExpanded]);
   useEffect(() => {
     try {
       localStorage.setItem(MINIMAP_STORE, minimapVisible ? '1' : '0');
@@ -11835,13 +11866,28 @@ function App() {
     } catch {}
   }, [layersMode]);
 
-  const toggleSection = useCallback((label, defaultOpen) => {
-    setSectionsExpanded((prev) => {
-      const cur = prev[label];
-      const isOpen = cur === undefined ? defaultOpen : cur;
-      return { ...prev, [label]: !isOpen };
-    });
-  }, []);
+  // #124 — forget folders that no longer exist (deleted, or moved outside
+  // Maude). ONCE per session, on the first loaded tree: pruning on every tree
+  // change would race a move's remap against the reload that follows it.
+  const treePruned = useRef(false);
+  useEffect(() => {
+    if (treePruned.current || !treeExp.ready || !treeLoaded || !groups.length) return;
+    treePruned.current = true;
+    const known = collectDirPaths(groups);
+    updateTreeExp((st) => pruneDirs(st, known));
+  }, [treeExp.ready, treeLoaded, groups, updateTreeExp]);
+
+  const toggleSection = useCallback(
+    (label) => updateTreeExp((st) => toggleSectionState(st, label)),
+    [updateTreeExp]
+  );
+  const treeExpansion = useMemo(
+    () => ({
+      isOpen: (dirPath) => isDirOpen(treeExp.state, dirPath),
+      setOpen: (dirPath, open) => updateTreeExp((st) => setDirOpen(st, dirPath, open)),
+    }),
+    [treeExp.state, updateTreeExp]
+  );
 
   const toggleTheme = useCallback(() => {
     setTheme((t) => (t === 'dark' ? 'light' : 'dark'));
@@ -12354,7 +12400,12 @@ function App() {
   // The `tabs` state stays as a 0-or-1 array so the rest of the plumbing
   // (iframesRef, comments push, WS `tabs` message) doesn't need refactoring.
   // ARTBOARDS slot in the menubar reads `tabs.length` and reports 0 or 1.
-  const openTab = useCallback((path) => {
+  // `reveal: false` for opens the USER didn't just ask for (URL restore on
+  // boot, the cloud first-canvas auto-open): nothing expands itself on launch
+  // (#124). Every other open reveals the canvas's row in the Files tree.
+  const openTab = useCallback((path, { reveal = true } = {}) => {
+    if (reveal && path && path !== SYSTEM_TAB)
+      updateTreeExp((st) => revealPath(st, groups, path));
     addressMode.current = 'push';
     setFocusedCommentId(null);
     setPreviewPath(null);
@@ -12372,12 +12423,12 @@ function App() {
     // Canvas-compile skeleton — cleared by the iframe's dgn:'loaded' message,
     // the onLoad fallback timer (legacy .html), or a hard 15s cap.
     if (path !== SYSTEM_TAB) setLoadingPath(path);
-  }, [activePath]);
+  }, [activePath, groups, updateTreeExp]);
 
   // Resolve URL identities against the loaded tree, including non-canvas previews.
   const openLinkedFile = useCallback((rel, mode = 'push') => {
     const path = groups.flatMap((g) => g.paths || []).find((p) => normalizeOpenPath(p, cfg.designRel) === rel);
-    if (path && CANVAS_EXT_RE.test(path)) openTab(path);
+    if (path && CANVAS_EXT_RE.test(path)) openTab(path, { reveal: false });
     else if (path && previewKind(basename(path))) onPreview(path);
     else {
       setTabs([]);
@@ -12482,7 +12533,7 @@ function App() {
     }
     if (!first) return;
     autoOpened.current = true;
-    openTab(first);
+    openTab(first, { reveal: false });
   }, [cfg.cloud, groups, tabs.length, openTab]);
 
   const openSystem = useCallback(
@@ -12849,6 +12900,9 @@ function App() {
         );
         const fromFile = `${designRel}/${j.fromRel}`;
         const toFile = `${designRel}/${j.toRel}`;
+        // #124 — a moved folder keeps its (and its subfolders') open state, and
+        // the destination opens so the moved row is visible.
+        updateTreeExp((st) => revealPath(remapDirPrefix(st, fromFile, toFile), groups, toFile));
         await loadTree();
         setTabs((prev) => prev.map((t) => (t.path === fromFile ? { path: toFile } : t)));
         setActivePath((prev) => (prev === fromFile ? toFile : prev));
@@ -12865,7 +12919,7 @@ function App() {
         return { ok: false, error: 'network error' };
       }
     },
-    [loadTree, cfg]
+    [loadTree, cfg, groups, updateTreeExp]
   );
 
   // feature-file-tree-drag-drop-folders (Task 4/9/12) — create a folder under
@@ -12887,6 +12941,8 @@ function App() {
           shellToast(`Could not create folder: ${error}`);
           return { ok: false, error };
         }
+        // #124 — open the parent so the new folder is visible (it starts closed).
+        updateTreeExp((st) => revealPath(st, groups, parentDir, { includeSelf: true }));
         await loadTree();
         return { ok: true, dir: j.dir };
       } catch (e) {
@@ -12895,7 +12951,7 @@ function App() {
         return { ok: false, error };
       }
     },
-    [loadTree]
+    [loadTree, groups, updateTreeExp]
   );
 
   // feature-file-tree-drag-drop-folders (dogfood follow-up) — delete a
@@ -12943,12 +12999,16 @@ function App() {
           shellToast(`Could not rename folder: ${j.error || `error ${r.status}`}`);
           return;
         }
+        // #124 — the renamed folder keeps its open state (and its subfolders').
+        const designRel = (cfg?.designRel || cfg?.designRoot || '.design').replace(/^\/+|\/+$/g, '');
+        const toDir = typeof j.toRel === 'string' ? `${designRel}/${j.toRel}` : `${parent}/${name}`;
+        updateTreeExp((st) => remapDirPrefix(st, dirPath, toDir));
         await loadTree();
       } catch (e) {
         shellToast(`Rename failed: ${e instanceof Error ? e.message : 'network error'}`);
       }
     },
-    [loadTree]
+    [loadTree, cfg, updateTreeExp]
   );
 
   // Plan T25/L04 — rename a canvas in place (its sidecars follow; an open tab
@@ -15674,7 +15734,9 @@ function App() {
         <Sidebar
           cloud={cfg.cloud}
           readOnly={viewerMode}
-          groups={groups}
+          // Held back until the remembered disclosure is read, so the first
+          // paint is the user's tree rather than an all-closed flash (#124).
+          groups={treeExp.ready ? groups : EMPTY_GROUPS}
           activePath={activePath}
           previewPath={previewPath}
           activeDsName={activePath === SYSTEM_TAB ? (systemData?.ds?.name ?? null) : null}
@@ -15691,6 +15753,7 @@ function App() {
           showHidden={showHidden}
           sectionsExpanded={sectionsExpanded}
           onToggleSection={toggleSection}
+          treeExpansion={treeExpansion}
           onNewBoard={createBoard}
           onDeleteBoard={deleteBoard}
           onMoveCanvas={moveCanvasReq}

package/apps/studio/client/hmr.mjs

@@ -69,7 +69,7 @@ function handle(evt) {
   }
   if (evt.type === 'fs:json' && evt.file) {
     // Phase 20 (DDR-049) — external edits to canvas `.meta.json` or
-    // `.annotations.svg` invalidate the iframe's in-memory undo stack
+    // `.annotations.json` invalidate the iframe's in-memory undo stack
     // (stale before/after snapshots would otherwise restore wrong state).
     // The iframe's UndoStackProvider self-echo-dampens our own PATCH-es
     // via window.__maude_last_meta_self_write_at, so we forward

package/apps/studio/client/panels/git-grouping.js

@@ -1,12 +1,12 @@
 // Pure grouping helpers for the Changes panel (GitPanel.jsx) — framework-free so
 // they unit-test without a DOM. DDR-115 follow-up: group changed files by parent
 // canvas + its supporting sidecars (same-stem `.meta.json`, slug-matched
-// `.annotations.svg`), mirroring the server's `expandSidecars` notion of "travels
+// `.annotations.json`), mirroring the server's `expandSidecars` notion of "travels
 // with the canvas" so the visual grouping is honest with what a unit commits.
 
 export const CANVAS_RE = /\.(tsx|html)$/i;
 export const META_RE = /\.meta\.json$/i;
-export const ANNOT_RE = /\.annotations\.svg$/i;
+export const ANNOT_RE = /\.annotations\.(?:svg|json)$/i;
 
 /** Display name for a file (last path segment, sidecar/canvas extension stripped). */
 export function baseName(p) {

package/apps/studio/client/tree-expansion.js

@@ -0,0 +1,217 @@
+// tree-expansion.js — which folders + sections of the Files panel are open
+// (issue #124).
+//
+// Before this, every folder row owned its own `useState(defaultOpen=true)`:
+// the tree started fully expanded and forgot every collapse the moment the row
+// unmounted — a dock-tab switch, a section toggle, a reload. The state now
+// lives ONCE at App level (so it outlives the rows) and is persisted per
+// project through `/_api/tree-state` (so it outlives the app).
+//
+// Rule: anything not recorded is CLOSED — folders and sections alike. Nothing
+// expands itself on boot; only the user does (a click, or explicitly opening a
+// canvas, which reveals its row). Search force-opens without recording.
+//
+// The helpers below are pure (state in → state out) so they are unit-testable
+// without a DOM; `useTreeExpansion` is the thin React wrapper App uses.
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export const EMPTY_TREE_STATE = Object.freeze({ dirs: [], sections: {} });
+
+// Pre-#124 section overrides lived only in origin-scoped localStorage. Read
+// once as a seed so an existing user's choices survive the move to disk.
+export const LEGACY_SECTIONS_STORE = 'mdcc-sections-expanded';
+
+const PERSIST_DEBOUNCE_MS = 250;
+const HYDRATE_TIMEOUT_MS = 3000;
+
+export function isDirOpen(state, dirPath) {
+  return !!dirPath && state.dirs.includes(dirPath);
+}
+
+export function isSectionOpen(state, label) {
+  return state.sections[label] === true;
+}
+
+export function setDirOpen(state, dirPath, open) {
+  if (!dirPath) return state;
+  const has = state.dirs.includes(dirPath);
+  if (has === !!open) return state;
+  const dirs = open ? [...state.dirs, dirPath].sort() : state.dirs.filter((d) => d !== dirPath);
+  return { ...state, dirs };
+}
+
+export function toggleDir(state, dirPath) {
+  return setDirOpen(state, dirPath, !isDirOpen(state, dirPath));
+}
+
+export function setSectionOpen(state, label, open) {
+  if (!label || state.sections[label] === !!open) return state;
+  return { ...state, sections: { ...state.sections, [label]: !!open } };
+}
+
+export function toggleSection(state, label) {
+  return setSectionOpen(state, label, !isSectionOpen(state, label));
+}
+
+/** The group (section) a repo-relative path lives in — longest `fullPath` wins. */
+export function groupForPath(groups, path) {
+  let best = null;
+  for (const g of groups || []) {
+    const root = g.fullPath;
+    if (!root || !(path === root || path.startsWith(root + '/'))) continue;
+    if (!best || root.length > best.fullPath.length) best = g;
+  }
+  return best;
+}
+
+/**
+ * Open everything needed to SEE `path`: its section, and every folder between
+ * the section root and the path. `includeSelf` also opens `path` itself (for a
+ * folder target — a new folder's parent, a move destination).
+ */
+export function revealPath(state, groups, path, { includeSelf = false } = {}) {
+  if (!path) return state;
+  const g = groupForPath(groups, path);
+  if (!g) return state;
+  let next = setSectionOpen(state, g.label, true);
+  const rest = path.slice(g.fullPath.length + 1);
+  if (!rest) return next;
+  const parts = rest.split('/');
+  const upto = includeSelf ? parts.length : parts.length - 1;
+  let cur = g.fullPath;
+  for (let i = 0; i < upto; i++) {
+    cur = `${cur}/${parts[i]}`;
+    next = setDirOpen(next, cur, true);
+  }
+  return next;
+}
+
+/** A folder moved/renamed `from` → `to`: carry its (and its subfolders') keys. */
+export function remapDirPrefix(state, from, to) {
+  if (!from || !to || from === to) return state;
+  let changed = false;
+  const dirs = state.dirs.map((d) => {
+    if (d === from) {
+      changed = true;
+      return to;
+    }
+    if (d.startsWith(from + '/')) {
+      changed = true;
+      return to + d.slice(from.length);
+    }
+    return d;
+  });
+  return changed ? { ...state, dirs: [...new Set(dirs)].sort() } : state;
+}
+
+/** Every folder path present in the loaded groups' trees. */
+export function collectDirPaths(groups) {
+  const out = new Set();
+  const walk = (node, base) => {
+    for (const k of Object.keys(node || {})) {
+      if (k === '_files') continue;
+      const p = `${base}/${k}`;
+      out.add(p);
+      walk(node[k], p);
+    }
+  };
+  for (const g of groups || []) if (g.fullPath) walk(g.tree, g.fullPath);
+  return out;
+}
+
+/** Drop keys for folders that no longer exist (deleted, moved outside Maude). */
+export function pruneDirs(state, known) {
+  const dirs = state.dirs.filter((d) => known.has(d));
+  return dirs.length === state.dirs.length ? state : { ...state, dirs };
+}
+
+export function normalizeClientState(raw) {
+  const o = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  const dirs = Array.isArray(o.dirs) ? [...new Set(o.dirs.filter((d) => typeof d === 'string' && d))].sort() : [];
+  const sections = {};
+  if (o.sections && typeof o.sections === 'object' && !Array.isArray(o.sections)) {
+    for (const [k, v] of Object.entries(o.sections)) if (typeof v === 'boolean') sections[k] = v;
+  }
+  return { dirs, sections };
+}
+
+function readLegacySections() {
+  try {
+    const v = JSON.parse(localStorage.getItem(LEGACY_SECTIONS_STORE) || 'null');
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * App-level owner of the tree state. `ready` flips once the stored state has
+ * been read (or the read failed) — App holds the tree back until then so the
+ * first paint is the remembered tree, not an all-closed flash. Writes are
+ * debounced and only start after hydration, so the initial empty state can
+ * never overwrite what is on disk.
+ */
+export function useTreeExpansion({ fetchImpl } = {}) {
+  const [state, setState] = useState(EMPTY_TREE_STATE);
+  const [ready, setReady] = useState(false);
+  const doFetch = fetchImpl || ((...a) => fetch(...a));
+  const fetchRef = useRef(doFetch);
+  fetchRef.current = doFetch;
+
+  useEffect(() => {
+    let cancelled = false;
+    // A stalled read (cell cold start, a hung proxy) must not keep the Files
+    // panel empty: after HYDRATE_TIMEOUT_MS the tree renders all-closed.
+    const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
+    const timer = setTimeout(() => ctrl?.abort(), HYDRATE_TIMEOUT_MS);
+    fetchRef
+      .current('/_api/tree-state', ctrl ? { signal: ctrl.signal } : undefined)
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`HTTP ${r.status}`))))
+      .then((raw) => {
+        if (cancelled) return;
+        let next = normalizeClientState(raw);
+        const stored = raw && typeof raw === 'object' && raw.sections && Object.keys(raw.sections).length;
+        if (!stored) {
+          const legacy = readLegacySections();
+          if (legacy) next = normalizeClientState({ ...next, sections: legacy });
+        }
+        setState(next);
+      })
+      .catch(() => {})
+      .finally(() => {
+        clearTimeout(timer);
+        if (!cancelled) setReady(true);
+      });
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+    };
+  }, []);
+
+  const skipFirst = useRef(true);
+  useEffect(() => {
+    if (!ready) return;
+    // The hydrating setState lands in the same commit as `ready`; that value
+    // came FROM disk, so writing it back is pointless.
+    if (skipFirst.current) {
+      skipFirst.current = false;
+      return;
+    }
+    const t = setTimeout(() => {
+      try {
+        fetchRef
+          .current('/_api/tree-state', {
+            method: 'POST',
+            headers: { 'content-type': 'text/plain' },
+            body: JSON.stringify(state),
+          })
+          .catch(() => {});
+      } catch {}
+    }, PERSIST_DEBOUNCE_MS);
+    return () => clearTimeout(t);
+  }, [ready, state]);
+
+  const update = useCallback((fn) => setState((s) => fn(s)), []);
+  return { state, ready, update };
+}