@exegia/corpora-ui 0.22.0 → 0.24.0

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

@@ -3,8 +3,14 @@
 import { motion, useReducedMotion } from "motion/react"
 import * as React from "react"
 
+import { useAtomValue, useSetAtom } from "jotai"
+
 import { cn } from "@/lib/utils"
 import { SCAFFOLD_EASE, SCAFFOLD_EDGE_GUTTER, SCAFFOLD_MORPH_DURATION } from "./constants"
+import {
+  scaffoldInspectorOpenAtom,
+  toggleScaffoldInspectorAtom,
+} from "./scaffold-atom"
 import { useScaffoldContext } from "./scaffold-context"
 import type { ScaffoldInspectorProps } from "./type"
 import { GlassContainer } from "@/components/ui/glasscn/glass-container.tsx"
@@ -23,8 +29,9 @@ export function ScaffoldInspector({
   className,
   ...rest
 }: ScaffoldInspectorProps): React.ReactElement {
-  const { inspectorOpen, inspectorWidth, toggleInspector } =
-    useScaffoldContext()
+  const { scaffoldId, inspectorWidth } = useScaffoldContext()
+  const inspectorOpen = useAtomValue(scaffoldInspectorOpenAtom(scaffoldId))
+  const toggleInspector = useSetAtom(toggleScaffoldInspectorAtom(scaffoldId))
   const reducedMotion = useReducedMotion()
 
   // Slide fully past the edge gutter and the drop shadow's blur radius.

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

@@ -10,7 +10,10 @@ import {
   SCAFFOLD_MORPH_DURATION,
   SCAFFOLD_PANEL_MIN_WIDTH,
 } from "./constants"
+import { useAtomValue } from "jotai"
+
 import { PanelMenuButton } from "./panel-menu-button.tsx"
+import { scaffoldPanelDimmedAtom } from "./scaffold-atom"
 import { useScaffoldContext } from "./scaffold-context"
 import type { ScaffoldPanelProps, TSubPanelPosition } from "./type"
 import { ScaffoldSubPanel } from "@/components/blocks/scaffold/scaffold-sub-panel.tsx"
@@ -33,13 +36,14 @@ export function ScaffoldPanel({
   sound = true,
   className,
 }: ScaffoldPanelProps): React.ReactElement {
-  const { hoveredPanelId } = useScaffoldContext()
+  const { scaffoldId } = useScaffoldContext()
   const reducedMotion = useReducedMotion()
 
-  // A hovered tab spotlights its own panel — every other id'd panel
-  // fades back so the pairing reads at a glance.
-  const dimmed =
-    id !== undefined && hoveredPanelId !== null && hoveredPanelId !== id
+  // A hovered tab spotlights its own panel — every other id'd panel fades
+  // back so the pairing reads at a glance. The per-panel atom keeps a hover
+  // moving between two tabs from re-rendering the panels that stay dimmed;
+  // the empty-key sentinel reads false for a panel without an `id`.
+  const dimmed = useAtomValue(scaffoldPanelDimmedAtom(scaffoldId, id ?? ""))
 
   const transition = {
     duration: reducedMotion ? 0 : SCAFFOLD_MORPH_DURATION,
@@ -78,7 +82,6 @@ export function ScaffoldPanel({
         // floor would overflow it.
         minWidth: id !== undefined ? SCAFFOLD_PANEL_MIN_WIDTH : 0,
         scaleX: 1,
-        flexDirection: isSwapped ? "column-reverse" : "column",
         // The hovered tab's panel keeps full opacity; the rest fade back
         // so the tab↔panel pairing reads at a glance. Inline (not a
         // class) because motion owns this element's opacity.
@@ -89,10 +92,15 @@ export function ScaffoldPanel({
       style={{ originX: 0.5 }}
       aria-label={name}
       className={cn(
-        "group/panel relative flex min-w-0 flex-1 flex-col w-full",
+        "group/panel relative flex w-full min-w-0 flex-1",
+        // Swap flips the direction as a class, NOT an animate target:
+        // flex-direction is discrete, so motion would apply it instantly —
+        // the flip lands in one commit and the children's `layout` FLIP is
+        // what glides the cards past each other.
+        isSwapped ? "flex-col-reverse" : "flex-col",
         className
       )}
-      layout={"size"}
+      layout
       data-slot="scaffold-panel"
       data-dimmed={dimmed ? "" : undefined}
       data-swapped={isSwapped ? "" : undefined}
@@ -102,7 +110,13 @@ export function ScaffoldPanel({
         {children}
       </ScaffoldSubPanel>
       {(onSwap || onCloseSecondary) && SecondaryPanel && (
-        <div className="relative flex h-2 items-center justify-center">
+        // `layout` keeps the seam glued to the moving boundary while the
+        // cards trade places around it.
+        <motion.div
+          layout
+          transition={transition}
+          className="relative flex h-2 items-center justify-center"
+        >
           <PanelMenuButton
             label={swapLabel}
             onClick={handleSwap}
@@ -112,7 +126,7 @@ export function ScaffoldPanel({
             swapped={isSwapped}
             sound={sound}
           />
-        </div>
+        </motion.div>
       )}
       {SecondaryPanel && (
         <ScaffoldSubPanel id="bottom" expanded={subPanelPosition === "bottom"}>

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

@@ -1,20 +1,41 @@
 "use client"
 
 import * as React from "react"
+import { useSetAtom } from "jotai"
 
 import { cn } from "@/lib/utils"
 import { SCAFFOLD_INSPECTOR_WIDTH } from "./constants"
+import {
+  projectScaffoldPropsAtom,
+  removeScaffoldInstance,
+  seedScaffoldInspectorAtom,
+  setScaffoldHandlersAtom,
+} from "./scaffold-atom"
 import { ScaffoldContext } from "./scaffold-context"
-import { usePanelVisibility } from "./use-panel-visibility"
-import type { ScaffoldContextValue, ScaffoldRootProps } from "./type"
+import type {
+  ScaffoldConfig,
+  ScaffoldContextValue,
+  ScaffoldHandlers,
+  ScaffoldRootProps,
+} from "./type"
 import type { ClassNameValue } from "tailwind-merge"
 
 /**
  * The scaffold's viewport: desktop backdrop + horizontal row of rail and
- * main region, and the provider for the shared inspector state. Fills its
- * container — size it from the outside (e.g. `h-svh` for a full page).
+ * main region, and the binding between this instance's props and its slice
+ * of the store. Fills its container — size it from the outside (e.g.
+ * `h-svh` for a full page).
+ *
+ * State lives in the store under `scaffoldId`; the context carries only the
+ * id and the drawer width, so its value never changes while the scaffold is
+ * mounted and parts subscribe to exactly the atoms they render from. A
+ * controlled `inspectorOpen` stays the source of truth: it is projected
+ * one-way into the store (so remote readers see current data), and the
+ * inspector actions report through `onInspectorOpenChange` instead of
+ * writing.
  */
 export function ScaffoldRoot({
+  scaffoldId: scaffoldIdProp,
   inspectorOpen: inspectorOpenProp,
   defaultInspectorOpen,
   onInspectorOpenChange,
@@ -23,42 +44,53 @@ export function ScaffoldRoot({
   children,
   ...rest
 }: ScaffoldRootProps): React.ReactElement {
-  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(
-    defaultInspectorOpen ?? false
-  )
-  const inspectorOpen = inspectorOpenProp ?? uncontrolledOpen
+  const generatedId = React.useId()
+  const scaffoldId = scaffoldIdProp ?? generatedId
   const background: ClassNameValue = `bg-linear-to-tr/increasing from-neutral-200 via-neutral-100 to-stone-200 dark:from-neutral-900 dark:via-neutral-950 dark:to-stone-950`
 
-  const setInspectorOpen = React.useCallback(
-    (open: boolean) => {
-      if (inspectorOpenProp === undefined) setUncontrolledOpen(open)
-      onInspectorOpenChange?.(open)
-    },
-    [inspectorOpenProp, onInspectorOpenChange]
+  const controlsInspector = inspectorOpenProp !== undefined
+  const config = React.useMemo<ScaffoldConfig>(
+    () => ({ controlsInspector }),
+    [controlsInspector]
+  )
+  const handlers = React.useMemo<ScaffoldHandlers>(
+    () => ({ onInspectorOpenChange }),
+    [onInspectorOpenChange]
   )
 
-  const toggleInspector = React.useCallback(
-    () => setInspectorOpen(!inspectorOpen),
-    [inspectorOpen, setInspectorOpen]
+  const project = useSetAtom(projectScaffoldPropsAtom(scaffoldId))
+  const publishHandlers = useSetAtom(setScaffoldHandlersAtom(scaffoldId))
+  const seedInspector = useSetAtom(seedScaffoldInspectorAtom(scaffoldId))
+
+  // Seed the uncontrolled inspector once per mount, before the projection —
+  // `defaultInspectorOpen` describes the mount, not every render. Layout
+  // effects so children read settled values in the same commit; primitive
+  // deps, so no loop guard is needed.
+  const [seed] = React.useState(
+    () => inspectorOpenProp ?? defaultInspectorOpen ?? false
   )
+  React.useLayoutEffect(() => {
+    if (!controlsInspector) seedInspector(seed)
+    // Mount-time seed only.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+  // Handlers before the projection — they must be in the store before any
+  // action can fire.
+  React.useLayoutEffect(() => {
+    publishHandlers(handlers)
+  }, [publishHandlers, handlers])
+  React.useLayoutEffect(() => {
+    project(config, inspectorOpenProp)
+  }, [project, config, inspectorOpenProp])
 
-  const panelVisibility = usePanelVisibility()
+  React.useEffect(() => {
+    if (scaffoldIdProp !== undefined) return
+    return () => removeScaffoldInstance(scaffoldId)
+  }, [scaffoldIdProp, scaffoldId])
 
   const value = React.useMemo<ScaffoldContextValue>(
-    () => ({
-      inspectorOpen,
-      inspectorWidth,
-      setInspectorOpen,
-      toggleInspector,
-      ...panelVisibility,
-    }),
-    [
-      inspectorOpen,
-      inspectorWidth,
-      setInspectorOpen,
-      toggleInspector,
-      panelVisibility,
-    ]
+    () => ({ scaffoldId, inspectorWidth }),
+    [scaffoldId, inspectorWidth]
   )
 
   return (

package/src/components/blocks/scaffold/scaffold-sub-panel.tsx

@@ -1,26 +1,28 @@
-
 import * as React from "react"
-import { motion, useReducedMotion } from "framer-motion"
+import { motion, useReducedMotion } from "motion/react"
 import { cn } from "@/lib/utils"
 import type { ScaffoldSubPanelProps } from "./type"
 import { subPanelVariant } from "@/components/blocks/scaffold/utils.ts"
 import { SCAFFOLD_EASE, SCAFFOLD_MORPH_DURATION } from "./constants"
 
 export function ScaffoldSubPanel({
-                                   className,
-                                   children,
-                                   variant = 'card',
-                                   primary = false,
-                                   expanded,
-                                   ...rest
-                                 }: ScaffoldSubPanelProps): React.ReactElement {
+  className,
+  children,
+  variant = "card",
+  primary = false,
+  expanded,
+  ...rest
+}: ScaffoldSubPanelProps): React.ReactElement {
   const reduce = useReducedMotion()
   // The primary card holds the flexible slot unless the panel says otherwise.
   const isExpanded = expanded ?? primary
 
   return (
     <motion.div
-      layout={"size"}
+      // Full `layout` (position + size), not `layout="size"`: a swap flips
+      // the panel's flex direction in a single commit, and only a position
+      // FLIP makes the two cards glide past each other instead of teleport.
+      layout
       id={`scaffold-sub-panel-${variant}`}
       // Grow is animated as a style, not a class flip — a class flip rides the
       // layout FLIP, which scales both cards into a swap-like morph. Animating

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

@@ -2,9 +2,15 @@
 
 import { useReducedMotion } from "motion/react"
 import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
 import { cn } from "@/lib/utils"
 import { SPRING_LAYOUT } from "@/lib/ease.ts"
+import {
+  scaffoldPanelHiddenAtom,
+  setScaffoldPanelHoveredAtom,
+  toggleScaffoldPanelAtom,
+} from "./scaffold-atom"
 import { useScaffoldContext } from "./scaffold-context"
 import type { ScaffoldTabProps } from "./type"
 import { segmentVariants } from "./utils"
@@ -32,13 +38,15 @@ export function ScaffoldTab({
   className,
   ...rest
 }: ScaffoldTabProps): React.ReactElement {
-  const { isPanelHidden, togglePanelVisibility, setPanelHovered } =
-    useScaffoldContext()
+  const { scaffoldId } = useScaffoldContext()
+  // The per-panel atom keeps this tab still while its siblings toggle; the
+  // empty-key sentinel reads false for a tab without a `panelId`.
+  const hidden = useAtomValue(scaffoldPanelHiddenAtom(scaffoldId, panelId ?? ""))
+  const togglePanel = useSetAtom(toggleScaffoldPanelAtom(scaffoldId))
+  const setPanelHovered = useSetAtom(setScaffoldPanelHoveredAtom(scaffoldId))
   const reduce = useReducedMotion()
   const transition = reduce ? { duration: 0 } : SPRING_LAYOUT
 
-  const hidden = panelId !== undefined && isPanelHidden(panelId)
-
   // A tab closed mid-hover never fires pointer-leave — release the
   // spotlight it holds so the canvas doesn't stay dimmed.
   React.useEffect(() => {
@@ -70,11 +78,7 @@ export function ScaffoldTab({
     >
       <Button
         aria-pressed={panelId !== undefined ? !hidden : undefined}
-        onClick={
-          panelId !== undefined
-            ? () => togglePanelVisibility(panelId)
-            : undefined
-        }
+        onClick={panelId !== undefined ? () => togglePanel(panelId) : undefined}
         size="sm"
         sound={sound}
         variant="ghost"

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

@@ -1,37 +1,77 @@
 import React, { type ComponentProps, type ReactElement, type ReactNode, } from "react"
 
-/** Inspector state shared by every scaffold part through ScaffoldContext. */
+/** Key of one scaffold's slice of the store. */
+export type ScaffoldInstanceId = string
+
+/** The identity every scaffold part shares through ScaffoldContext. State
+ * itself lives in the store — parts subscribe to the atoms they render from,
+ * so this value never changes identity while the scaffold is mounted. */
 export interface ScaffoldContextValue {
-  /** Whether the inspector drawer is currently shown. */
-  inspectorOpen: boolean
+  scaffoldId: ScaffoldInstanceId
   /** Drawer width in px — Actions reads it to slide out of the drawer's way. */
   inspectorWidth: number
-  setInspectorOpen: (open: boolean) => void
-  toggleInspector: () => void
+}
+
+/** One scaffold's whole state, as `useScaffoldState` returns it. A component
+ * that watches one field should subscribe to that field's atom instead. */
+export interface ScaffoldState {
+  /** Whether the inspector drawer is currently shown. */
+  inspectorOpen: boolean
   /** How many panels currently fit side by side, from the measured canvas
    * width at `SCAFFOLD_PANEL_MIN_WIDTH` per panel (1..`SCAFFOLD_PANEL_CAPACITY`). */
   panelCapacity: number
   /** Ids of id'd panels the scaffold is currently hiding — auto-hidden by
    * capacity pressure or toggled away from a tab. */
   hiddenPanelIds: readonly string[]
-  isPanelHidden: (id: string) => boolean
-  /** Show/hide an id'd panel. Showing past capacity auto-hides the
-   * least-recently-activated visible panel; the last visible one never hides. */
-  togglePanelVisibility: (id: string) => void
   /** Id of the panel whose tab the pointer is resting on — the canvas
    * spotlights it by fading every other id'd panel to 0.35 opacity. */
   hoveredPanelId: string | null
-  /** @internal Tabs report pointer enter/leave on their label. */
-  setPanelHovered: (id: string, hovered: boolean) => void
-  /** @internal Canvas reports its ordered panel ids. */
-  registerPanelIds: (ids: readonly string[]) => void
-  /** @internal Canvas reports its measured width. */
-  setCanvasWidth: (width: number) => void
+}
+
+/** Drive a scaffold by id from anywhere, as `useScaffoldActions` returns it. */
+export interface ScaffoldStateActions {
+  setInspectorOpen: (open: boolean) => void
+  toggleInspector: () => void
+  /** Show/hide an id'd panel. Showing past capacity auto-hides the
+   * least-recently-activated visible panel; the last visible one never hides. */
+  togglePanel: (panelId: string) => void
+  reset: () => void
+}
+
+/** @internal Which props currently control the scaffold — write gates for
+ * the action atoms, so the store never overwrites a prop. */
+export interface ScaffoldConfig {
+  controlsInspector: boolean
+}
+
+/** @internal The mounted root's callbacks, published into the store so
+ * action atoms can report changes wherever they were fired from. */
+export interface ScaffoldHandlers {
+  onInspectorOpenChange?: (open: boolean) => void
+}
+
+/** @internal Bookkeeping for responsive panel hiding.
+ * - `visibleOrder`: visible panel ids, least-recently-activated first — the
+ *   front is what capacity pressure evicts next.
+ * - `autoHidden`: panels the scaffold hid because the canvas shrank, most
+ *   recent last. They return on their own when room comes back.
+ * - `userHidden`: panels hidden by a tab press. They stay hidden until the
+ *   tab is pressed again, however wide the canvas grows. */
+export interface ScaffoldPanelVisibility {
+  visibleOrder: string[]
+  autoHidden: string[]
+  userHidden: string[]
 }
 
 export interface ScaffoldRootProps extends ComponentProps<"div"> {
-  /** Controlled inspector state — pair with `onInspectorOpenChange`, or
-   * spread `useScaffold().providerProps` instead of wiring by hand. */
+  /** Names this scaffold's slice of the store, so `useScaffoldState` /
+   * `useScaffoldActions` can drive it by id and its state outlives the
+   * component. Omitted, the root keys off `useId` and drops its state on
+   * unmount. `useScaffold().providerProps` carries one. */
+  scaffoldId?: ScaffoldInstanceId
+  /** Controlled inspector state — pair with `onInspectorOpenChange`. The
+   * prop stays the source of truth: store writes are gated off, and actions
+   * report through the callback instead. */
   inspectorOpen?: boolean
   /** Initial inspector state when uncontrolled. Closed by default. */
   defaultInspectorOpen?: boolean
@@ -182,6 +222,9 @@ export interface PanelMenuButtonProps extends PanelFloatingButtonProps {
 }
 
 export interface UseScaffoldOptions {
+  /** Names the scaffold's slice of the store. Omitted, the hook generates
+   * one and drops its state on unmount. */
+  scaffoldId?: ScaffoldInstanceId
   /** Initial inspector state. Closed by default. */
   defaultInspectorOpen?: boolean
   /** Fires on every inspector open/close. */
@@ -189,12 +232,15 @@ export interface UseScaffoldOptions {
 }
 
 export interface ScaffoldControls {
+  /** The id the hook and the root share — hand it to `useScaffoldState` /
+   * `useScaffoldActions` to drive the scaffold from elsewhere. */
+  scaffoldId: ScaffoldInstanceId
   inspectorOpen: boolean
   setInspectorOpen: (open: boolean) => void
   toggleInspector: () => void
   /** Spread onto Scaffold.Root. */
   providerProps: Pick<
     ScaffoldRootProps,
-    "inspectorOpen" | "onInspectorOpenChange"
+    "scaffoldId" | "defaultInspectorOpen" | "onInspectorOpenChange"
   >
 }

package/src/components/blocks/scaffold/use-scaffold-state.ts

@@ -0,0 +1,58 @@
+"use client"
+
+import { useMemo } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  resetScaffoldAtom,
+  scaffoldStateAtom,
+  setScaffoldInspectorOpenAtom,
+  toggleScaffoldInspectorAtom,
+  toggleScaffoldPanelAtom,
+} from "./scaffold-atom"
+import type {
+  ScaffoldInstanceId,
+  ScaffoldState,
+  ScaffoldStateActions,
+} from "./type"
+
+/**
+ * Read the scaffold registered under `scaffoldId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { inspectorOpen, hiddenPanelIds } = useScaffoldState("workspace")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on every
+ * change, hovers included. A component that reads one field should subscribe
+ * to that field's atom instead:
+ * `useAtomValue(scaffoldInspectorOpenAtom("workspace"))`.
+ */
+export function useScaffoldState(scaffoldId: ScaffoldInstanceId): ScaffoldState {
+  return useAtomValue(scaffoldStateAtom(scaffoldId))
+}
+
+/**
+ * Drive the scaffold registered under `scaffoldId` from anywhere. Writes
+ * only — the caller never re-renders when the scaffold changes, so this is
+ * what a command palette or a keyboard shortcut should reach for.
+ *
+ * ```tsx
+ * const scaffold = useScaffoldActions("workspace")
+ * <Button onClick={scaffold.toggleInspector}>Inspect</Button>
+ * ```
+ */
+export function useScaffoldActions(
+  scaffoldId: ScaffoldInstanceId
+): ScaffoldStateActions {
+  const setInspectorOpen = useSetAtom(setScaffoldInspectorOpenAtom(scaffoldId))
+  const toggleInspector = useSetAtom(toggleScaffoldInspectorAtom(scaffoldId))
+  const togglePanel = useSetAtom(toggleScaffoldPanelAtom(scaffoldId))
+  const reset = useSetAtom(resetScaffoldAtom(scaffoldId))
+
+  return useMemo(
+    () => ({ setInspectorOpen, toggleInspector, togglePanel, reset }),
+    [setInspectorOpen, toggleInspector, togglePanel, reset]
+  )
+}

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

@@ -1,7 +1,14 @@
 "use client"
 
-import { useCallback, useMemo, useState } from "react"
+import { useEffect, useId, useMemo } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
+import {
+  removeScaffoldInstance,
+  scaffoldInspectorOpenAtom,
+  setScaffoldInspectorOpenAtom,
+  toggleScaffoldInspectorAtom,
+} from "./scaffold-atom"
 import type { ScaffoldControls, UseScaffoldOptions } from "./type"
 
 /**
@@ -9,37 +16,41 @@ import type { ScaffoldControls, UseScaffoldOptions } from "./type"
  * (title-bar buttons, command palette, shortcuts). Spread the returned
  * `providerProps` onto `Scaffold.Root`; without this hook the root manages
  * the same state internally via `defaultInspectorOpen`.
+ *
+ * The hook and the root meet in the store: `providerProps` carries a
+ * `scaffoldId`, both sides read and write that instance's atoms, and
+ * `useScaffoldState` / `useScaffoldActions` reach the same slice from
+ * anywhere else by id. Unnamed scaffolds key off `useId` and are dropped on
+ * unmount; an explicit `scaffoldId` outlives its component.
  */
 export function useScaffold({
+  scaffoldId: scaffoldIdProp,
   defaultInspectorOpen,
   onInspectorChange,
 }: UseScaffoldOptions = {}): ScaffoldControls {
-  const [inspectorOpen, setOpenState] = useState(defaultInspectorOpen ?? false)
+  const generatedId = useId()
+  const scaffoldId = scaffoldIdProp ?? generatedId
 
-  const setInspectorOpen = useCallback(
-    (open: boolean) => {
-      setOpenState((prev) => {
-        if (prev !== open) onInspectorChange?.(open)
-        return open
-      })
-    },
-    [onInspectorChange]
-  )
+  const inspectorOpen = useAtomValue(scaffoldInspectorOpenAtom(scaffoldId))
+  const setInspectorOpen = useSetAtom(setScaffoldInspectorOpenAtom(scaffoldId))
+  const toggleInspector = useSetAtom(toggleScaffoldInspectorAtom(scaffoldId))
 
-  const toggleInspector = useCallback(
-    () => setInspectorOpen(!inspectorOpen),
-    [inspectorOpen, setInspectorOpen]
-  )
+  useEffect(() => {
+    if (scaffoldIdProp !== undefined) return
+    return () => removeScaffoldInstance(scaffoldId)
+  }, [scaffoldIdProp, scaffoldId])
 
-  const providerProps = useMemo(
+  const providerProps = useMemo<ScaffoldControls["providerProps"]>(
     () => ({
-      inspectorOpen,
-      onInspectorOpenChange: setInspectorOpen,
+      scaffoldId,
+      defaultInspectorOpen,
+      onInspectorOpenChange: onInspectorChange,
     }),
-    [inspectorOpen, setInspectorOpen]
+    [scaffoldId, defaultInspectorOpen, onInspectorChange]
   )
 
   return {
+    scaffoldId,
     inspectorOpen,
     setInspectorOpen,
     toggleInspector,

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

@@ -1,6 +1,9 @@
 import type { Variants } from "motion/react"
 import type { ClassNameValue } from "tailwind-merge"
-import type { TSubPanelVariant } from "@/components/blocks/scaffold/type.ts"
+import type {
+  ScaffoldPanelVisibility,
+  TSubPanelVariant,
+} from "@/components/blocks/scaffold/type.ts"
 import { EASE_OUT } from "@/lib/ease.ts"
 import {
   SCAFFOLD_CANVAS_GAP,
@@ -22,6 +25,47 @@ export function getPanelCapacity(width: number | null): number {
   return Math.max(1, Math.min(SCAFFOLD_PANEL_CAPACITY, fits))
 }
 
+/** @internal An untracked scaffold: nothing registered, nothing hidden. */
+export const EMPTY_SCAFFOLD_VISIBILITY: ScaffoldPanelVisibility = {
+  visibleOrder: [],
+  autoHidden: [],
+  userHidden: [],
+}
+
+/**
+ * @internal Fold the registered ids and current capacity into a settled
+ * visibility: prune departed panels, admit new ones, evict the
+ * least-recently-activated visible panels past capacity, and restore
+ * auto-hidden ones when room returns. Returns `prev` untouched when nothing
+ * changes, so callers can compare identities instead of contents.
+ */
+export function reconcileVisibility(
+  prev: ScaffoldPanelVisibility,
+  ids: readonly string[],
+  capacity: number
+): ScaffoldPanelVisibility {
+  const known = new Set(ids)
+  const visibleOrder = prev.visibleOrder.filter((id) => known.has(id))
+  const autoHidden = prev.autoHidden.filter((id) => known.has(id))
+  const userHidden = prev.userHidden.filter((id) => known.has(id))
+
+  const tracked = new Set([...visibleOrder, ...autoHidden, ...userHidden])
+  for (const id of ids) if (!tracked.has(id)) visibleOrder.push(id)
+
+  while (visibleOrder.length > capacity && visibleOrder.length > 1) {
+    autoHidden.push(visibleOrder.shift() as string)
+  }
+  while (visibleOrder.length < capacity && autoHidden.length > 0) {
+    visibleOrder.push(autoHidden.pop() as string)
+  }
+
+  const unchanged =
+    visibleOrder.join(" ") === prev.visibleOrder.join(" ") &&
+    autoHidden.join(" ") === prev.autoHidden.join(" ") &&
+    userHidden.join(" ") === prev.userHidden.join(" ")
+  return unchanged ? prev : { visibleOrder, autoHidden, userHidden }
+}
+
 /** Desktop backdrop the whole scaffold sits on — a soft warm-gray wash. */
 export const scaffoldBackgroundClass: ClassNameValue =
   "bg-linear-to-tr/increasing from-neutral-400 via-stone-200 to-neutral-300 dark:from-neutral-900 dark:via-neutral-950 dark:to-stone-950"