@exegia/corpora-ui 0.22.0 → 0.23.0

package/src/components/blocks/scaffold/__tests__/scaffold-atom.test.tsx

@@ -0,0 +1,210 @@
+import { describe, expect, mock, test } from "bun:test"
+import { createStore } from "jotai"
+
+import {
+  measureScaffoldCanvasAtom,
+  projectScaffoldPropsAtom,
+  registerScaffoldPanelIdsAtom,
+  removeScaffoldInstance,
+  resetScaffoldAtom,
+  scaffoldHiddenPanelIdsAtom,
+  scaffoldHoveredPanelIdAtom,
+  scaffoldInspectorOpenAtom,
+  scaffoldPanelCapacityAtom,
+  scaffoldPanelDimmedAtom,
+  scaffoldPanelHiddenAtom,
+  scaffoldStateAtom,
+  scaffoldVisibilityAtom,
+  setScaffoldHandlersAtom,
+  setScaffoldInspectorOpenAtom,
+  setScaffoldPanelHoveredAtom,
+  toggleScaffoldInspectorAtom,
+  toggleScaffoldPanelAtom,
+} from "../scaffold-atom"
+
+type Store = ReturnType<typeof createStore>
+
+let keys = 0
+/** A fresh instance per test — ids never collide, no cross-test state. */
+const instance = () => `scaffold-test-${keys++}`
+
+/** Register three panels on a canvas wide enough for all of them. */
+function mountThree(store: Store, id: string) {
+  store.set(registerScaffoldPanelIdsAtom(id), ["one", "two", "three"])
+  store.set(measureScaffoldCanvasAtom(id), 1200)
+}
+
+describe("scaffold panel visibility atoms", () => {
+  test("narrowing evicts the least-recently-activated panel; widening restores it", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual([])
+
+    // Two panels' worth of room.
+    store.set(measureScaffoldCanvasAtom(id), 700)
+    expect(store.get(scaffoldPanelCapacityAtom(id))).toBe(2)
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual(["one"])
+    expect(store.get(scaffoldPanelHiddenAtom(id, "one"))).toBe(true)
+    expect(store.get(scaffoldPanelHiddenAtom(id, "two"))).toBe(false)
+
+    // Room returns — the auto-hidden panel comes back by itself.
+    store.set(measureScaffoldCanvasAtom(id), 1200)
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual([])
+  })
+
+  test("showing a hidden panel past capacity trades places with the oldest visible one", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+    store.set(measureScaffoldCanvasAtom(id), 700)
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual(["one"])
+
+    store.set(toggleScaffoldPanelAtom(id), "one")
+    expect(store.get(scaffoldPanelHiddenAtom(id, "one"))).toBe(false)
+    expect(store.get(scaffoldPanelHiddenAtom(id, "two"))).toBe(true)
+  })
+
+  test("user-hidden panels stay hidden when the canvas widens; a press shows them again", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+
+    store.set(toggleScaffoldPanelAtom(id), "two")
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual(["two"])
+
+    store.set(measureScaffoldCanvasAtom(id), 1400)
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual(["two"])
+
+    store.set(toggleScaffoldPanelAtom(id), "two")
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual([])
+  })
+
+  test("the last visible panel refuses to hide; unknown ids are inert", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+    store.set(measureScaffoldCanvasAtom(id), 400)
+    expect(store.get(scaffoldPanelCapacityAtom(id))).toBe(1)
+    expect(store.get(scaffoldPanelHiddenAtom(id, "three"))).toBe(false)
+
+    store.set(toggleScaffoldPanelAtom(id), "three")
+    expect(store.get(scaffoldPanelHiddenAtom(id, "three"))).toBe(false)
+
+    store.set(toggleScaffoldPanelAtom(id), "nonexistent")
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual(["one", "two"])
+  })
+
+  test("departed panels are pruned from every list on re-registration", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+    store.set(toggleScaffoldPanelAtom(id), "two")
+
+    store.set(registerScaffoldPanelIdsAtom(id), ["one", "three"])
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual([])
+  })
+
+  test("a resize that lands on the same capacity leaves the visibility untouched", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+    const before = store.get(scaffoldVisibilityAtom(id))
+
+    // 1200 → 1000 both fit three panels.
+    store.set(measureScaffoldCanvasAtom(id), 1000)
+    expect(store.get(scaffoldVisibilityAtom(id))).toBe(before)
+  })
+})
+
+describe("scaffold hover atoms", () => {
+  test("hover spotlights one panel; a stale leave never clears a newer hover", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+
+    store.set(setScaffoldPanelHoveredAtom(id), "one", true)
+    expect(store.get(scaffoldPanelDimmedAtom(id, "one"))).toBe(false)
+    expect(store.get(scaffoldPanelDimmedAtom(id, "two"))).toBe(true)
+
+    // The pointer moved on before "one"'s leave fired.
+    store.set(setScaffoldPanelHoveredAtom(id), "two", true)
+    store.set(setScaffoldPanelHoveredAtom(id), "one", false)
+    expect(store.get(scaffoldHoveredPanelIdAtom(id))).toBe("two")
+
+    store.set(setScaffoldPanelHoveredAtom(id), "two", false)
+    expect(store.get(scaffoldHoveredPanelIdAtom(id))).toBe(null)
+    expect(store.get(scaffoldPanelDimmedAtom(id, "one"))).toBe(false)
+  })
+
+  test("the empty-key sentinel reads false however the scaffold moves", () => {
+    const store = createStore()
+    const id = instance()
+    store.set(setScaffoldPanelHoveredAtom(id), "one", true)
+    expect(store.get(scaffoldPanelDimmedAtom(id, ""))).toBe(false)
+    expect(store.get(scaffoldPanelHiddenAtom(id, ""))).toBe(false)
+  })
+})
+
+describe("scaffold inspector atoms", () => {
+  test("set and toggle report through the handler and write the store when uncontrolled", () => {
+    const store = createStore()
+    const id = instance()
+    const onInspectorOpenChange = mock(() => {})
+    store.set(setScaffoldHandlersAtom(id), { onInspectorOpenChange })
+
+    store.set(setScaffoldInspectorOpenAtom(id), true)
+    expect(store.get(scaffoldInspectorOpenAtom(id))).toBe(true)
+    expect(onInspectorOpenChange).toHaveBeenCalledWith(true)
+
+    // Setting the value it already holds is silent.
+    store.set(setScaffoldInspectorOpenAtom(id), true)
+    expect(onInspectorOpenChange).toHaveBeenCalledTimes(1)
+
+    store.set(toggleScaffoldInspectorAtom(id))
+    expect(store.get(scaffoldInspectorOpenAtom(id))).toBe(false)
+    expect(onInspectorOpenChange).toHaveBeenLastCalledWith(false)
+  })
+
+  test("a controlled inspector gates store writes; actions only report", () => {
+    const store = createStore()
+    const id = instance()
+    const onInspectorOpenChange = mock(() => {})
+    store.set(setScaffoldHandlersAtom(id), { onInspectorOpenChange })
+    store.set(projectScaffoldPropsAtom(id), { controlsInspector: true }, false)
+
+    store.set(setScaffoldInspectorOpenAtom(id), true)
+    expect(store.get(scaffoldInspectorOpenAtom(id))).toBe(false)
+    expect(onInspectorOpenChange).toHaveBeenCalledWith(true)
+
+    // The prop coming back around through the projection is what moves it.
+    store.set(projectScaffoldPropsAtom(id), { controlsInspector: true }, true)
+    expect(store.get(scaffoldInspectorOpenAtom(id))).toBe(true)
+  })
+})
+
+describe("scaffold instance lifecycle", () => {
+  test("reset restores every field; remove drops the id from every family", () => {
+    const store = createStore()
+    const id = instance()
+    mountThree(store, id)
+    store.set(measureScaffoldCanvasAtom(id), 700)
+    store.set(setScaffoldInspectorOpenAtom(id), true)
+    store.set(setScaffoldPanelHoveredAtom(id), "two", true)
+
+    store.set(resetScaffoldAtom(id))
+    expect(store.get(scaffoldStateAtom(id))).toEqual({
+      inspectorOpen: false,
+      panelCapacity: 3,
+      hiddenPanelIds: [],
+      hoveredPanelId: null,
+    })
+
+    // A removed id reads fresh atoms — state from before is gone.
+    mountThree(store, id)
+    store.set(measureScaffoldCanvasAtom(id), 700)
+    removeScaffoldInstance(id)
+    expect(store.get(scaffoldPanelCapacityAtom(id))).toBe(3)
+    expect(store.get(scaffoldHiddenPanelIdsAtom(id))).toEqual([])
+  })
+})

package/src/components/blocks/scaffold/index.ts

@@ -12,6 +12,21 @@ import { ScaffoldSubPanel } from "@/components/blocks/scaffold/scaffold-sub-pane
 
 export { useScaffoldContext } from "./scaffold-context"
 export { useScaffold } from "./use-scaffold"
+export { useScaffoldActions, useScaffoldState } from "./use-scaffold-state"
+export {
+  removeScaffoldInstance,
+  resetScaffoldAtom,
+  scaffoldHiddenPanelIdsAtom,
+  scaffoldHoveredPanelIdAtom,
+  scaffoldInspectorOpenAtom,
+  scaffoldPanelCapacityAtom,
+  scaffoldPanelDimmedAtom,
+  scaffoldPanelHiddenAtom,
+  scaffoldStateAtom,
+  setScaffoldInspectorOpenAtom,
+  toggleScaffoldInspectorAtom,
+  toggleScaffoldPanelAtom,
+} from "./scaffold-atom"
 export type * from "./type"
 export * from "./constants"
 

package/src/components/blocks/scaffold/scaffold-actions.tsx

@@ -3,8 +3,11 @@
 import { AnimatePresence, motion, useReducedMotion } from "motion/react"
 import * as React from "react"
 
+import { useAtomValue } from "jotai"
+
 import { cn } from "@/lib/utils"
 import { SCAFFOLD_EASE, SCAFFOLD_EDGE_GUTTER, SCAFFOLD_MORPH_DURATION } from "./constants"
+import { scaffoldInspectorOpenAtom } from "./scaffold-atom"
 import { useScaffoldContext } from "./scaffold-context"
 import type { ScaffoldActionsProps } from "./type"
 import { segmentVariants } from "./utils"
@@ -28,7 +31,8 @@ export function ScaffoldActions({
   children,
   ...rest
 }: ScaffoldActionsProps): React.ReactElement {
-  const { inspectorOpen, inspectorWidth } = useScaffoldContext()
+  const { scaffoldId, inspectorWidth } = useScaffoldContext()
+  const inspectorOpen = useAtomValue(scaffoldInspectorOpenAtom(scaffoldId))
   const reducedMotion = useReducedMotion()
   const transition = reducedMotion ? { duration: 0 } : SPRING_LAYOUT
 

package/src/components/blocks/scaffold/scaffold-atom.ts

@@ -0,0 +1,383 @@
+/**
+ * Scaffold state — Jotai atom families keyed by a scaffold id.
+ *
+ * Same layout as the tree (`components/composed/tree/tree-atom.ts`), the
+ * shell (`blocks/shell/shell-fit-atom.ts`) and the profile card: in-house
+ * `keyed()` families per field, write-only action atoms, a composed
+ * read-only state atom, and `removeScaffoldInstance` to drop an id from
+ * every family.
+ *
+ * The visibility bookkeeping (`visibleOrder` / `autoHidden` / `userHidden`)
+ * stays one atom on purpose — `reconcileVisibility` always settles the three
+ * lists together, so splitting them would only invite half-written states.
+ * The reconcile rule itself lives in `utils.ts`, and every action that moves
+ * an input (ids, capacity, a toggle) settles the visibility before it
+ * returns, so readers never see an interim state — the render-time settling
+ * the old `usePanelVisibility` hook needed has no equivalent here.
+ */
+
+import { atom } from "jotai"
+import type { Atom, Getter, Setter } from "jotai"
+
+import { SCAFFOLD_PANEL_CAPACITY } from "./constants"
+import type {
+  ScaffoldConfig,
+  ScaffoldHandlers,
+  ScaffoldInstanceId,
+  ScaffoldPanelVisibility,
+  ScaffoldState,
+} from "./type"
+import {
+  EMPTY_SCAFFOLD_VISIBILITY,
+  getPanelCapacity,
+  reconcileVisibility,
+} from "./utils"
+
+const DEFAULT_CONFIG: ScaffoldConfig = { controlsInspector: false }
+const NO_HANDLERS: ScaffoldHandlers = {}
+const NO_PANEL_IDS: readonly string[] = []
+
+// ── families ───────────────────────────────────────────────────────────────
+
+type Family<AtomType> = ((id: ScaffoldInstanceId) => AtomType) & {
+  remove: (id: ScaffoldInstanceId) => void
+}
+
+const families: { remove: (id: ScaffoldInstanceId) => void }[] = []
+
+function keyed<AtomType>(create: (id: ScaffoldInstanceId) => AtomType) {
+  const cache = new Map<ScaffoldInstanceId, AtomType>()
+  const family = ((id: ScaffoldInstanceId) => {
+    let instance = cache.get(id)
+    if (instance === undefined) {
+      instance = create(id)
+      cache.set(id, instance)
+    }
+    return instance
+  }) as Family<AtomType>
+  family.remove = (id: ScaffoldInstanceId) => {
+    cache.delete(id)
+  }
+  families.push(family)
+  return family
+}
+
+function stateFamily<Value>(name: string, initialValue: Value) {
+  return keyed((id) => {
+    const instance = atom(initialValue)
+    instance.debugLabel = `scaffold/${id}/${name}`
+    return instance
+  })
+}
+
+function readFamily<Value>(
+  name: string,
+  read: (get: Getter, id: ScaffoldInstanceId) => Value
+) {
+  return keyed((id) => {
+    const instance = atom((get) => read(get, id))
+    instance.debugLabel = `scaffold/${id}/${name}`
+    return instance
+  })
+}
+
+function actionFamily<Args extends unknown[]>(
+  name: string,
+  write: (
+    get: Getter,
+    set: Setter,
+    id: ScaffoldInstanceId,
+    ...args: Args
+  ) => void
+) {
+  return keyed((id) => {
+    const instance = atom(null, (get, set, ...args: Args) =>
+      write(get, set, id, ...args)
+    )
+    instance.debugLabel = `scaffold/${id}/${name}`
+    return instance
+  })
+}
+
+/** A family keyed by scaffold AND panel, so a tab or a panel subscribes to
+ * its own boolean and sits still when a sibling's changes — the per-node
+ * rule from the tree, at panel scale. Removal drops a whole scaffold. */
+function panelFamily<Value>(
+  name: string,
+  read: (get: Getter, id: ScaffoldInstanceId, panelId: string) => Value
+) {
+  const cache = new Map<ScaffoldInstanceId, Map<string, Atom<Value>>>()
+  const family = (id: ScaffoldInstanceId, panelId: string): Atom<Value> => {
+    let panels = cache.get(id)
+    if (panels === undefined) {
+      panels = new Map()
+      cache.set(id, panels)
+    }
+    let instance = panels.get(panelId)
+    if (instance === undefined) {
+      const created = atom((get) => read(get, id, panelId))
+      created.debugLabel = `scaffold/${id}/${panelId}/${name}`
+      panels.set(panelId, created)
+      instance = created
+    }
+    return instance
+  }
+  families.push({
+    remove: (id: ScaffoldInstanceId) => {
+      cache.delete(id)
+    },
+  })
+  return family
+}
+
+// ── primitives ─────────────────────────────────────────────────────────────
+
+export const scaffoldInspectorOpenAtom = stateFamily<boolean>(
+  "inspectorOpen",
+  false
+)
+
+/** @internal The canvas's ordered panel ids, as registered each render. */
+export const scaffoldPanelIdsAtom = stateFamily<readonly string[]>(
+  "panelIds",
+  NO_PANEL_IDS
+)
+
+/** @internal The capacity derived from the canvas's measured width — the
+ * derived number is stored, not the raw width, so resize storms only touch
+ * the store when a panel actually gains or loses room. */
+export const scaffoldMeasuredCapacityAtom = stateFamily<number | null>(
+  "measuredCapacity",
+  null
+)
+
+/** @internal The three visibility lists, settled as one value. */
+export const scaffoldVisibilityAtom = stateFamily<ScaffoldPanelVisibility>(
+  "visibility",
+  EMPTY_SCAFFOLD_VISIBILITY
+)
+
+export const scaffoldHoveredPanelIdAtom = stateFamily<string | null>(
+  "hoveredPanelId",
+  null
+)
+
+/** @internal */
+export const scaffoldConfigAtom = stateFamily<ScaffoldConfig>(
+  "config",
+  DEFAULT_CONFIG
+)
+
+/** @internal */
+export const scaffoldHandlersAtom = stateFamily<ScaffoldHandlers>(
+  "handlers",
+  NO_HANDLERS
+)
+
+// ── derived ────────────────────────────────────────────────────────────────
+
+/** How many panels fit side by side; the cap while the canvas is unmeasured. */
+export const scaffoldPanelCapacityAtom = readFamily(
+  "panelCapacity",
+  (get, id) =>
+    get(scaffoldMeasuredCapacityAtom(id)) ?? SCAFFOLD_PANEL_CAPACITY
+)
+
+/** Ids of panels currently hidden (auto + user), for tabs to reflect. */
+export const scaffoldHiddenPanelIdsAtom = readFamily<readonly string[]>(
+  "hiddenPanelIds",
+  (get, id) => {
+    const visibility = get(scaffoldVisibilityAtom(id))
+    return [...visibility.autoHidden, ...visibility.userHidden]
+  }
+)
+
+/** Whether one panel is hidden. A tab subscribes here and sits still while
+ * its siblings toggle. Empty `panelId` (a tab without one) reads false. */
+export const scaffoldPanelHiddenAtom = panelFamily(
+  "hidden",
+  (get, id, panelId) => {
+    if (panelId === "") return false
+    const visibility = get(scaffoldVisibilityAtom(id))
+    return (
+      visibility.autoHidden.includes(panelId) ||
+      visibility.userHidden.includes(panelId)
+    )
+  }
+)
+
+/** Whether one panel fades back while another panel's tab holds the
+ * spotlight. Moving the hover between two tabs re-renders those panels
+ * only — everyone else's boolean holds. */
+export const scaffoldPanelDimmedAtom = panelFamily(
+  "dimmed",
+  (get, id, panelId) => {
+    if (panelId === "") return false
+    const hovered = get(scaffoldHoveredPanelIdAtom(id))
+    return hovered !== null && hovered !== panelId
+  }
+)
+
+/** The whole state of one scaffold. This changes on every hover move, so a
+ * component that reads one field should subscribe to that field's atom
+ * instead: `useAtomValue(scaffoldInspectorOpenAtom("workspace"))`. */
+export const scaffoldStateAtom = readFamily<ScaffoldState>(
+  "state",
+  (get, id) => ({
+    inspectorOpen: get(scaffoldInspectorOpenAtom(id)),
+    panelCapacity: get(scaffoldPanelCapacityAtom(id)),
+    hiddenPanelIds: get(scaffoldHiddenPanelIdsAtom(id)),
+    hoveredPanelId: get(scaffoldHoveredPanelIdAtom(id)),
+  })
+)
+
+// ── visibility settling ────────────────────────────────────────────────────
+
+/** Re-settle the lists after any input moved. Inert when nothing changes —
+ * `reconcileVisibility` returns `prev` untouched then. */
+function settleVisibility(get: Getter, set: Setter, id: ScaffoldInstanceId) {
+  const prev = get(scaffoldVisibilityAtom(id))
+  const settled = reconcileVisibility(
+    prev,
+    get(scaffoldPanelIdsAtom(id)),
+    get(scaffoldPanelCapacityAtom(id))
+  )
+  if (settled !== prev) set(scaffoldVisibilityAtom(id), settled)
+}
+
+// ── actions: inspector ─────────────────────────────────────────────────────
+
+/** Reports through `onInspectorOpenChange` always; writes the store only
+ * when no `inspectorOpen` prop controls the root — the prop is truth then. */
+export const setScaffoldInspectorOpenAtom = actionFamily<[open: boolean]>(
+  "setInspectorOpen",
+  (get, set, id, open) => {
+    if (get(scaffoldInspectorOpenAtom(id)) === open) return
+    if (!get(scaffoldConfigAtom(id)).controlsInspector)
+      set(scaffoldInspectorOpenAtom(id), open)
+    get(scaffoldHandlersAtom(id)).onInspectorOpenChange?.(open)
+  }
+)
+
+export const toggleScaffoldInspectorAtom = actionFamily<[]>(
+  "toggleInspector",
+  (get, set, id) => {
+    set(setScaffoldInspectorOpenAtom(id), !get(scaffoldInspectorOpenAtom(id)))
+  }
+)
+
+// ── actions: panels ────────────────────────────────────────────────────────
+
+/** Show/hide an id'd panel. Showing past capacity auto-hides the
+ * least-recently-activated visible panel; the last visible one never hides. */
+export const toggleScaffoldPanelAtom = actionFamily<[panelId: string]>(
+  "togglePanel",
+  (get, set, id, panelId) => {
+    const ids = get(scaffoldPanelIdsAtom(id))
+    if (!ids.includes(panelId)) return
+    const prev = get(scaffoldVisibilityAtom(id))
+    const hidden =
+      prev.autoHidden.includes(panelId) || prev.userHidden.includes(panelId)
+    if (!hidden && prev.visibleOrder.length <= 1) return
+
+    const next: ScaffoldPanelVisibility = hidden
+      ? {
+          // Showing: newest activation — reconcile evicts the oldest
+          // visible panel if the canvas can't fit one more.
+          visibleOrder: [...prev.visibleOrder, panelId],
+          autoHidden: prev.autoHidden.filter((other) => other !== panelId),
+          userHidden: prev.userHidden.filter((other) => other !== panelId),
+        }
+      : {
+          visibleOrder: prev.visibleOrder.filter((other) => other !== panelId),
+          autoHidden: prev.autoHidden,
+          userHidden: [...prev.userHidden, panelId],
+        }
+    set(
+      scaffoldVisibilityAtom(id),
+      reconcileVisibility(next, ids, get(scaffoldPanelCapacityAtom(id)))
+    )
+  }
+)
+
+/** @internal Tabs report pointer enter/leave on their label. Leaving clears
+ * only its own id — a tab that unmounts mid-hover must not wipe out a hover
+ * the pointer has already moved on to. */
+export const setScaffoldPanelHoveredAtom = actionFamily<
+  [panelId: string, hovered: boolean]
+>("setPanelHovered", (get, set, id, panelId, hovered) => {
+  const prev = get(scaffoldHoveredPanelIdAtom(id))
+  if (hovered) {
+    if (prev !== panelId) set(scaffoldHoveredPanelIdAtom(id), panelId)
+    return
+  }
+  if (prev === panelId) set(scaffoldHoveredPanelIdAtom(id), null)
+})
+
+/** @internal Canvas reports its ordered panel ids each render. Inert when
+ * the ids did not move; otherwise the visibility settles in the same write. */
+export const registerScaffoldPanelIdsAtom = actionFamily<
+  [ids: readonly string[]]
+>("registerPanelIds", (get, set, id, ids) => {
+  const prev = get(scaffoldPanelIdsAtom(id))
+  if (prev.length === ids.length && prev.every((v, i) => v === ids[i])) return
+  set(scaffoldPanelIdsAtom(id), [...ids])
+  settleVisibility(get, set, id)
+})
+
+/** @internal Canvas reports its measured width. Only the derived capacity is
+ * stored, so resize storms settle to at most one visibility change. */
+export const measureScaffoldCanvasAtom = actionFamily<[width: number]>(
+  "measureCanvas",
+  (get, set, id, width) => {
+    const capacity = getPanelCapacity(width)
+    if (get(scaffoldMeasuredCapacityAtom(id)) === capacity) return
+    set(scaffoldMeasuredCapacityAtom(id), capacity)
+    settleVisibility(get, set, id)
+  }
+)
+
+// ── internal projections ───────────────────────────────────────────────────
+
+/** @internal Projection of the mounted root's controlled props. */
+export const projectScaffoldPropsAtom = actionFamily<
+  [config: ScaffoldConfig, inspectorOpen: boolean | undefined]
+>("projectProps", (_get, set, id, config, inspectorOpen) => {
+  set(scaffoldConfigAtom(id), config)
+  if (config.controlsInspector && inspectorOpen !== undefined)
+    set(scaffoldInspectorOpenAtom(id), inspectorOpen)
+})
+
+/** @internal */
+export const setScaffoldHandlersAtom = actionFamily<
+  [handlers: ScaffoldHandlers]
+>("setHandlers", (_get, set, id, handlers) => {
+  set(scaffoldHandlersAtom(id), handlers)
+})
+
+/** @internal Seed the uncontrolled inspector on mount without firing
+ * `onInspectorOpenChange`. */
+export const seedScaffoldInspectorAtom = actionFamily<[open: boolean]>(
+  "seedInspector",
+  (_get, set, id, open) => {
+    set(scaffoldInspectorOpenAtom(id), open)
+  }
+)
+
+// ── reset ──────────────────────────────────────────────────────────────────
+
+export const resetScaffoldAtom = actionFamily<[]>("reset", (_get, set, id) => {
+  set(scaffoldInspectorOpenAtom(id), false)
+  set(scaffoldPanelIdsAtom(id), NO_PANEL_IDS)
+  set(scaffoldMeasuredCapacityAtom(id), null)
+  set(scaffoldVisibilityAtom(id), EMPTY_SCAFFOLD_VISIBILITY)
+  set(scaffoldHoveredPanelIdAtom(id), null)
+  set(scaffoldConfigAtom(id), DEFAULT_CONFIG)
+  set(scaffoldHandlersAtom(id), NO_HANDLERS)
+})
+
+/** Forget a scaffold entirely — every family drops the key so the store can
+ * release its state. Call on teardown of a named instance. */
+export function removeScaffoldInstance(id: ScaffoldInstanceId): void {
+  for (const family of families) family.remove(id)
+}

package/src/components/blocks/scaffold/scaffold-canvas.tsx

@@ -2,8 +2,14 @@
 
 import { AnimatePresence } from "motion/react"
 import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
 import { cn } from "@/lib/utils"
+import {
+  measureScaffoldCanvasAtom,
+  registerScaffoldPanelIdsAtom,
+  scaffoldHiddenPanelIdsAtom,
+} from "./scaffold-atom"
 import { useScaffoldContext } from "./scaffold-context"
 import type { ScaffoldCanvasProps, ScaffoldPanelProps } from "./type"
 
@@ -26,19 +32,21 @@ export function ScaffoldCanvas({
   children,
   ...rest
 }: ScaffoldCanvasProps): React.ReactElement {
-  const { hiddenPanelIds, registerPanelIds, setCanvasWidth } =
-    useScaffoldContext()
+  const { scaffoldId } = useScaffoldContext()
+  const hiddenPanelIds = useAtomValue(scaffoldHiddenPanelIdsAtom(scaffoldId))
+  const registerPanelIds = useSetAtom(registerScaffoldPanelIdsAtom(scaffoldId))
+  const measureCanvas = useSetAtom(measureScaffoldCanvasAtom(scaffoldId))
   const ref = React.useRef<HTMLDivElement>(null)
 
   React.useLayoutEffect(() => {
     const element = ref.current
     if (!element || typeof ResizeObserver === "undefined") return
     const observer = new ResizeObserver(([entry]) =>
-      setCanvasWidth(entry.contentRect.width)
+      measureCanvas(entry.contentRect.width)
     )
     observer.observe(element)
     return () => observer.disconnect()
-  }, [setCanvasWidth])
+  }, [measureCanvas])
 
   const childArray = React.Children.toArray(children)
   const panelIds = childArray

package/src/components/blocks/scaffold/scaffold-context.ts

@@ -8,7 +8,9 @@ export const ScaffoldContext = React.createContext<ScaffoldContextValue | null>(
   null
 )
 
-/** Read the scaffold's shared state; must run under `Scaffold.Root`. */
+/** Read the scaffold's identity (`scaffoldId`, `inspectorWidth`); must run
+ * under `Scaffold.Root`. State itself lives in the store — subscribe to the
+ * atoms, or reach them by id through `useScaffoldState` / `useScaffoldActions`. */
 export function useScaffoldContext(): ScaffoldContextValue {
   const context = React.useContext(ScaffoldContext)
   if (!context) {