@exegia/corpora-ui 0.20.0 → 0.22.0

package/src/components/blocks/shell/shell-fit-atom.ts

@@ -0,0 +1,243 @@
+/**
+ * Per-instance Jotai state for the shell's layout fit.
+ *
+ * Every atom is a module-level family keyed by a shell id, so one
+ * `ExegiaProvider` at the app root is enough: several shells coexist in one
+ * store without a provider each, and a title bar, a command palette or a
+ * layout test can drive one by id without holding its controller.
+ *
+ * Unlike the tree, this feature has no controlled props — the shell measures
+ * itself, nobody hands it a viewport. So, like `blocks/auth`'s coordination
+ * layer, there is no config atom, no projection and no owned-* loop guard.
+ * `useShellFit` is the only writer of `metrics`, and that write is silent by
+ * design: a resize is not an event an app subscribed to.
+ *
+ * The rule itself lives in `shell-metrics.ts` and is called from here, so the
+ * arithmetic has one home whether it is read through a hook or a store.
+ */
+import { atom } from "jotai"
+import type { Getter, Setter } from "jotai"
+
+import {
+  clampPanelWidth,
+  fitsPanel,
+  metricsEqual,
+  panelBounds,
+  type ShellMetrics,
+} from "./shell-metrics"
+import type {
+  ShellFitInstanceId,
+  ShellFitPanelBounds,
+  ShellFitSeed,
+  ShellFitState,
+} from "./type"
+
+/** An unmeasured shell. Zeroes read as "no layout yet", which the rule fails
+ * open on rather than hiding a panel over a reading it never took. */
+const NO_METRICS: ShellMetrics = {
+  rail: 0,
+  insetMin: 0,
+  panelMin: 0,
+  viewport: 0,
+  chrome: 0,
+}
+
+/** A panel that mounts at `--panel-width`. */
+const DEFAULT_SHELL_FIT_SEED: ShellFitSeed = { panelWidth: null }
+
+const NO_BOUNDS: ShellFitPanelBounds = { min: 0, max: 0 }
+
+/**
+ * A string-keyed atom family.
+ *
+ * `jotai/utils`' `atomFamily` is deprecated for Jotai v3, and we need only
+ * the string-keyed case with a `remove` — so this stays in-house rather than
+ * adding `jotai-family` as a second Jotai package to keep version-aligned.
+ * Dropping a key lets the store's WeakMap release that instance's state.
+ */
+type Family<AtomType> = ((id: ShellFitInstanceId) => AtomType) & {
+  remove: (id: ShellFitInstanceId) => void
+}
+
+/** Every family, so `removeShellFitInstance` can drop an id from all of them. */
+const families: { remove: (id: ShellFitInstanceId) => void }[] = []
+
+function keyed<AtomType>(create: (id: ShellFitInstanceId) => AtomType) {
+  const cache = new Map<ShellFitInstanceId, AtomType>()
+  const family = ((id: ShellFitInstanceId) => {
+    let instance = cache.get(id)
+    if (instance === undefined) {
+      instance = create(id)
+      cache.set(id, instance)
+    }
+    return instance
+  }) as Family<AtomType>
+  family.remove = (id: ShellFitInstanceId) => {
+    cache.delete(id)
+  }
+  families.push(family)
+  return family
+}
+
+function stateFamily<Value>(name: string, initialValue: Value) {
+  return keyed((id) => {
+    const instance = atom(initialValue)
+    instance.debugLabel = `shell-fit/${id}/${name}`
+    return instance
+  })
+}
+
+function readFamily<Value>(
+  name: string,
+  read: (get: Getter, id: ShellFitInstanceId) => Value
+) {
+  return keyed((id) => {
+    const instance = atom((get) => read(get, id))
+    instance.debugLabel = `shell-fit/${id}/${name}`
+    return instance
+  })
+}
+
+function actionFamily<Args extends unknown[]>(
+  name: string,
+  write: (
+    get: Getter,
+    set: Setter,
+    id: ShellFitInstanceId,
+    ...args: Args
+  ) => void
+) {
+  return keyed((id) => {
+    const instance = atom(null, (get, set, ...args: Args) =>
+      write(get, set, id, ...args)
+    )
+    instance.debugLabel = `shell-fit/${id}/${name}`
+    return instance
+  })
+}
+
+/** The shell's own measurement of its columns. `useShellFit` is the only
+ * writer; read `shellFitMeasuredAtom` to get it with the "no layout yet" case
+ * already resolved. */
+export const shellFitMetricsAtom = stateFamily<ShellMetrics>(
+  "metrics",
+  NO_METRICS
+)
+
+/** The width the user dragged to, before clamping — null while the panel sits
+ * at `--panel-width`. Read `shellFitPanelWidthAtom` for the width the panel
+ * actually renders at: clamping on read is what lets a narrowing viewport
+ * pull the panel down without forgetting the width they asked for. */
+export const shellFitRequestedWidthAtom = stateFamily<number | null>(
+  "requestedWidth",
+  null
+)
+
+const shellFitSeedAtom = stateFamily<ShellFitSeed>(
+  "seed",
+  DEFAULT_SHELL_FIT_SEED
+)
+const shellFitInitializedAtom = stateFamily<boolean>("initialized", false)
+
+/** The metrics, or null when the shell has no layout to report — a server
+ * render, a `display: none` host, a test with no layout engine. A zero is not
+ * a width, and treating it as one would pin the panel to nothing. */
+export const shellFitMeasuredAtom = readFamily<ShellMetrics | null>(
+  "measured",
+  (get, id) => {
+    const metrics = get(shellFitMetricsAtom(id))
+    return metrics.panelMin > 0 ? metrics : null
+  }
+)
+
+/** Whether the shell can hold a secondary panel at all. */
+export const shellFitFitsAtom = readFamily("fits", (get, id) =>
+  fitsPanel(get(shellFitMetricsAtom(id)))
+)
+
+/** The range a resize may land in. */
+export const shellFitPanelBoundsAtom = readFamily<ShellFitPanelBounds>(
+  "panelBounds",
+  (get, id) => {
+    const measured = get(shellFitMeasuredAtom(id))
+    return measured ? panelBounds(measured) : NO_BOUNDS
+  }
+)
+
+/** The width the secondary panel renders at, or null before the first
+ * measurement, where the caller falls back to `--panel-width`. */
+export const shellFitPanelWidthAtom = readFamily<number | null>(
+  "panelWidth",
+  (get, id) => {
+    const measured = get(shellFitMeasuredAtom(id))
+    if (!measured) return null
+    const requested = get(shellFitRequestedWidthAtom(id))
+    return clampPanelWidth(requested ?? measured.panelMin, measured)
+  }
+)
+
+/** The whole fit of one shell. This changes on every measurement, so a
+ * component that reads one field should subscribe to that field's atom
+ * instead: `useAtomValue(shellFitFitsAtom("app-shell"))`. */
+export const shellFitStateAtom = readFamily<ShellFitState>(
+  "state",
+  (get, id) => ({
+    metrics: get(shellFitMeasuredAtom(id)),
+    fits: get(shellFitFitsAtom(id)),
+    panelWidth: get(shellFitPanelWidthAtom(id)),
+    bounds: get(shellFitPanelBoundsAtom(id)),
+  })
+)
+
+/** @internal The measurement's way in. Silent, and inert when the numbers did
+ * not move — a resize event that changes nothing must not re-render a shell. */
+export const measureShellFitAtom = actionFamily<[metrics: ShellMetrics]>(
+  "measure",
+  (get, set, id, metrics) => {
+    if (metricsEqual(get(shellFitMetricsAtom(id)), metrics)) return
+    set(shellFitMetricsAtom(id), metrics)
+  }
+)
+
+/** Resize the secondary panel. Clamped on the way in, so a drag past the
+ * gutter parks at the bound instead of banking travel it has to give back —
+ * and a caller with no idea how wide the shell is can still ask for 900. */
+export const resizeShellPanelAtom = actionFamily<[width: number]>(
+  "resizePanel",
+  (get, set, id, width) => {
+    const measured = get(shellFitMeasuredAtom(id))
+    set(
+      shellFitRequestedWidthAtom(id),
+      measured ? clampPanelWidth(width, measured) : width
+    )
+  }
+)
+
+/** Back to the width the shell mounted with — `defaultPanelWidth`, or
+ * `--panel-width` when there was none. */
+export const resetShellPanelWidthAtom = actionFamily<[]>(
+  "resetPanelWidth",
+  (get, set, id) => {
+    set(shellFitRequestedWidthAtom(id), get(shellFitSeedAtom(id)).panelWidth)
+  }
+)
+
+/** @internal Seed the instance once. A seed describes the mount, not every
+ * render, so a `defaultPanelWidth` that arrives later never overwrites a
+ * width the user dragged to. */
+export const mountShellFitAtom = actionFamily<[seed: ShellFitSeed]>(
+  "mount",
+  (get, set, id, seed) => {
+    if (get(shellFitInitializedAtom(id))) return
+    set(shellFitInitializedAtom(id), true)
+    set(shellFitSeedAtom(id), seed)
+    set(shellFitRequestedWidthAtom(id), seed.panelWidth)
+  }
+)
+
+/** Drop every atom for `id`. `useShellFit` calls this on unmount for shells it
+ * keyed itself; an explicit `shellId` is the app's key and outlives its
+ * component, so a resized panel survives a route change. */
+export function removeShellFitInstance(id: ShellFitInstanceId): void {
+  for (const family of families) family.remove(id)
+}

package/src/components/blocks/shell/shell-layout.tsx

@@ -3,9 +3,7 @@
 import { MotionIcon } from "motion-icons-react"
 import * as React from "react"
 
-import {
-  AnimatedPanel
-} from "./animated-panel.tsx"
+import { AnimatedPanel } from "./animated-panel.tsx"
 import { cn } from "@/lib/utils"
 import type { ShellLayoutProps, ShellPanelControlProps } from "./type"
 import { TITLE_BAR_HEIGHT } from "./utils"
@@ -23,82 +21,86 @@ export function ShellLayout({
   defaultOpen,
   ...panelControlProps
 }: ShellLayoutProps): React.ReactElement {
-
   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`
 
   // Each panel seeds its own side's initial state (`defaultOpen ?? open`);
   // an explicit `defaultOpen` record — usually from useShellPanels — wins
   // per side.
   const initialOpen: ShellPanelControlProps["defaultOpen"] = {
-      ...(panels?.left && {
-        left: panels.left.defaultOpen ?? true,
-      }),
-      ...(panels?.right && {
-        right: panels.right.defaultOpen ?? false,
-      }),
-      ...defaultOpen,
-    }
-
+    ...(panels?.left && {
+      left: panels.left.defaultOpen ?? true,
+    }),
+    ...(panels?.right && {
+      right: panels.right.defaultOpen ?? false,
+    }),
+    ...defaultOpen,
+  }
 
   return (
     <AnimatedPanelProvider
       {...panelControlProps}
       defaultOpen={initialOpen}
-      className={cn("relative h-full min-h-0 pb-2", className, background)}
+      className={cn("relative h-full min-h-0 px-2 pb-2", className, background)}
       style={{
         paddingTop: variant === "desktop" ? TITLE_BAR_HEIGHT : 0,
       }}
     >
-      <AnimatedPanel
-        ariaLabel="Primary navigation"
-        collapsible="icon"
-        role="navigation"
-        variant="inset"
-      >
-        {panels?.left?.component}
-      </AnimatedPanel>
+      {panels?.left?.component && (
+        <AnimatedPanel
+          ariaLabel="Primary navigation"
+          collapsible="icon"
+          role="navigation"
+          variant="inset"
+        >
+          {panels?.left?.component}
+        </AnimatedPanel>
+      )}
 
-      <AnimatedPanelInset className="min-w-24">
-        <header className="flex h-12 items-center justify-between gap-2 border-b px-2">
-          <div className="flex min-w-0 items-center gap-2">
-            <AnimatedPanelTrigger>
-              {panels?.left?.trigger ?? (
+      <AnimatedPanelInset>
+        <header className="flex h-12 flex-row! items-center justify-between gap-2 border-b px-2">
+          {panels?.left?.component && (
+            <div className="flex min-w-0 flex-1 items-center gap-2">
+              <AnimatedPanelTrigger side="left">
                 <MotionIcon name="PanelLeft" size={24} animation="press" />
-              )}
-            </AnimatedPanelTrigger>
-          </div>
-          {header && <div className="flex flex-1 items-center">{header}</div>}
-          <div className="flex shrink-0 items-center gap-2">
-            <AnimatedPanelTrigger aria-label="Toggle panel" side="right">
-              {panels?.right?.trigger ?? (
+              </AnimatedPanelTrigger>
+            </div>
+          )}
+          {header && (
+            <div className="flex w-full flex-1 items-center">{header}</div>
+          )}
+          {panels?.right?.component && (
+            <div className="flex flex-1 items-center justify-end gap-2">
+              <AnimatedPanelTrigger aria-label="Toggle panel" side="right">
                 <MotionIcon
                   className="opacity-70"
                   name="PanelRight"
                   size={24}
                 />
-              )}
-            </AnimatedPanelTrigger>
-          </div>
+              </AnimatedPanelTrigger>
+            </div>
+          )}
         </header>
         <div className="min-h-24 flex-1 overflow-auto">{children}</div>
       </AnimatedPanelInset>
 
-      <AnimatedPanel
-        ariaLabel={panels?.right?.name ?? "Secondary panel"}
-        // Below md the panel is portal led over the page, so it carries the
-        // surface itself; the desktop rail keeps it on the inner panel.
-        className={cn(
-          "mr-2 bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-900",
-          "outline-offset-0.5 border-t-3 border-white outline-neutral-100 dark:inset-ring-black",
-          "rounded-lg shadow-md shadow-neutral-200 dark:shadow-neutral-950"
-        )}
-        collapsible="offcanvas"
-        role="complementary"
-        side="right"
-        variant="inset"
-      >
-        {panels?.right?.component}
-      </AnimatedPanel>
+      {panels?.right?.component && (
+        <AnimatedPanel
+          ariaLabel={panels.right.name ?? "Secondary panel"}
+          // Below md the panel is portal led over the page, so it carries the
+          // surface itself; the desktop rail keeps it on the inner panel.
+          className={cn(
+            "bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-900",
+            "outline-offset-0.5 border-t-3 border-white outline-neutral-100 dark:inset-ring-black",
+            "rounded-lg shadow-md shadow-neutral-200 dark:shadow-neutral-950"
+          )}
+          collapsible="offcanvas"
+          role="complementary"
+          side="right"
+          variant="inset"
+        >
+          {panels.right.component}
+        </AnimatedPanel>
+      )}
     </AnimatedPanelProvider>
   )
 }

package/src/components/blocks/shell/shell-metrics.ts

@@ -0,0 +1,79 @@
+/**
+ * The shell's layout arithmetic, as plain functions over px.
+ *
+ * Nothing here touches React or the DOM. This module IS the contract of who
+ * gets which column, which keeps the rule unit-testable on its own and lets
+ * the shell-fit atoms (`shellFitFitsAtom`, `shellFitPanelWidthAtom`) call it
+ * without restating it: `useShellFit` only supplies the measurements.
+ */
+
+/** The px the shell lays itself out with. Every field is measured from a CSS
+ * variable (see `SHELL_WIDTHS`), never hard-coded, so a consumer's override
+ * flows straight through the rule. */
+export interface ShellMetrics {
+  /** What the left rail occupies right now — its expanded width, its icon
+   * width, or 0 when there is no rail at all (or it is off canvas). */
+  rail: number
+  /** The floor the body refuses to go below. */
+  insetMin: number
+  /** The secondary panel's floor, which is also the width it opens at. */
+  panelMin: number
+  /** The viewport all three columns share. */
+  viewport: number
+  /** px the shell's own frame eats before any column gets a share: its
+   * padding, plus the gap between columns.
+   *
+   * Deliberately absent from `fitsPanel` — that rule is stated against the raw
+   * viewport — but subtracted from the resize ceiling, where ignoring it lets
+   * a full-width drag push the row past the shell by exactly this much. */
+  chrome: number
+}
+
+/** px the shell needs before a secondary panel can exist: the rail as it
+ * stands, plus the body and the panel at their own floors. */
+export function requiredWidth({ rail, insetMin, panelMin }: ShellMetrics) {
+  return rail + insetMin + panelMin
+}
+
+/**
+ * Whether the shell can hold a secondary panel at all. Strictly `<`: a shell
+ * that fits its columns exactly has no room left to give one.
+ *
+ * An unmeasurable shell fails open. A server render, a `display: none` host
+ * or a test environment with no layout engine all report 0, and a panel must
+ * never disappear over a reading the layout could not produce.
+ */
+export function fitsPanel(metrics: ShellMetrics) {
+  if (metrics.viewport <= 0 || metrics.panelMin <= 0) return true
+  return requiredWidth(metrics) < metrics.viewport
+}
+
+/** How wide the secondary panel may be: never under its own floor, never past
+ * the slack the body holds above its floor. `max` never drops below `min`, so
+ * a shell that does not fit reports a degenerate range instead of an inverted
+ * one — `fitsPanel` is what hides the panel, not a negative bound. */
+export function panelBounds(metrics: ShellMetrics) {
+  const { chrome, insetMin, panelMin, rail, viewport } = metrics
+  return {
+    min: panelMin,
+    max: Math.max(panelMin, viewport - chrome - rail - insetMin),
+  }
+}
+
+export function clampPanelWidth(width: number, metrics: ShellMetrics) {
+  const { min, max } = panelBounds(metrics)
+  return Math.min(Math.max(width, min), max)
+}
+
+/** Resizes fire per pointer move and per resize event, most of them landing
+ * on the same numbers — comparing fields keeps those from re-rendering the
+ * whole shell. */
+export function metricsEqual(a: ShellMetrics, b: ShellMetrics) {
+  return (
+    a.rail === b.rail &&
+    a.insetMin === b.insetMin &&
+    a.panelMin === b.panelMin &&
+    a.viewport === b.viewport &&
+    a.chrome === b.chrome
+  )
+}

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

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react"
+import type { ReactNode, RefObject } from "react"
 
 import {
   type ButtonHTMLAttributes,
@@ -7,6 +7,83 @@ import {
 } from "react"
 import type { HTMLMotionProps } from "motion/react"
 
+import type { ShellMetrics } from "./shell-metrics"
+
+// ---------------------------------------------------------------------------
+// Shell fit — the shell's measurement of itself, kept in Jotai atoms keyed by
+// `shellId` (see `shell-fit-atom.ts`). No atom imports here: this file stays
+// dependency-free so the types can travel without the store.
+// ---------------------------------------------------------------------------
+
+/** The key a shell's fit state is filed under. Pass your own to reach it from
+ * anywhere (`useShellFitState("app-shell")`); leave it out and the provider
+ * generates one that dies with it. */
+export type ShellFitInstanceId = string
+
+/** The range a secondary-panel resize may land in, in px. */
+export interface ShellFitPanelBounds {
+  min: number
+  max: number
+}
+
+/** What the shell measured of itself — readable by id through
+ * `useShellFitState`. */
+export interface ShellFitState {
+  /** The px the shell last measured, or null before its first measurement
+   * (a server render, a host with no layout). */
+  metrics: ShellMetrics | null
+  /** Whether the shell can hold a secondary panel. True while unmeasured, so
+   * a panel never flickers out over a reading that has not happened yet. */
+  fits: boolean
+  /** The secondary panel's width in px, already clamped to `bounds` — null
+   * before the first measurement, where the panel falls back to
+   * `--panel-width`. */
+  panelWidth: number | null
+  /** The range a resize may land in. */
+  bounds: ShellFitPanelBounds
+}
+
+/** Writes only — drive a shell's secondary panel by id through
+ * `useShellFitActions` without re-rendering when it moves. */
+export interface ShellFitActions {
+  /** Resize the secondary panel. Clamped on the way in, so a drag past the
+   * gutter parks at the bound instead of banking travel it has to give back. */
+  resizePanel: (width: number) => void
+  /** Back to the width the shell mounted with — `defaultPanelWidth`, or
+   * `--panel-width` when there was none. */
+  resetPanelWidth: () => void
+}
+
+/** What `useShellFit` hands the provider: the state, the actions and the id
+ * they are filed under. */
+export interface ShellFitController extends ShellFitState, ShellFitActions {
+  shellId: ShellFitInstanceId
+}
+
+export interface UseShellFitOptions {
+  /** File the fit under this id so it can be read elsewhere and outlive the
+   * shell. Generated (and dropped on unmount) when omitted. */
+  shellId?: ShellFitInstanceId
+  /** The element the shell's CSS variables live on (the provider wrapper). */
+  hostRef: RefObject<HTMLElement | null>
+  /** Whether the left rail is expanded right now — a render input, so a fold
+   * counts the moment React commits it rather than a frame later when the
+   * width animation has moved. */
+  railOpen: boolean
+  /** The width the secondary panel opens at, in px, instead of
+   * `--panel-width`. Read once, on mount. */
+  defaultPanelWidth?: number
+  /** Fired whenever a measurement lands on "no room": the shell uses it to
+   * retire the panel's open state instead of parking it. */
+  onUnfit?: () => void
+}
+
+/** @internal What an instance starts from, restored by `resetShellPanelWidthAtom`. */
+export interface ShellFitSeed {
+  /** The requested panel width at mount — null for `--panel-width`. */
+  panelWidth: number | null
+}
+
 export interface ShellAction {
   id: string
   label: string
@@ -60,14 +137,24 @@ export type ShellPanelControlProps = Pick<
   | "openMobile"
   | "defaultOpenMobile"
   | "onOpenMobileChange"
+  | "shellId"
+  | "defaultPanelWidth"
 >
 
 export interface UseShellPanelsOptions {
+  /** The id the shell's fit state is filed under. Name it to read the same
+   * shell from elsewhere (`useShellFitState("app-shell")`) and to keep a
+   * dragged panel width across a route change; otherwise the hook generates
+   * one that dies with it. */
+  shellId?: ShellFitInstanceId
   /** Initial desktop open state per side, merged over
    * `{ left: true, right: false }`. */
   defaultOpen?: AnimatedSidebarProviderProps["defaultOpen"]
   /** Initial mobile overlay state per side — every side starts closed. */
   defaultOpenMobile?: AnimatedSidebarProviderProps["defaultOpenMobile"]
+  /** The width the secondary panel opens at, in px, instead of
+   * `--panel-width`. */
+  defaultPanelWidth?: number
   /** Panel change event returning both the next open state and the side of
    * the panel the change comes from. Mobile overlay changes report the same
    * side as their desktop counterpart. */
@@ -75,14 +162,32 @@ export interface UseShellPanelsOptions {
 }
 
 export interface ShellPanelControls {
+  /** The id the shell's fit state is filed under — hand it to
+   * `useShellFitState` / `useShellFitActions` anywhere below `ExegiaProvider`. */
+  shellId: ShellFitInstanceId
+  /** The viewport cannot hold the secondary panel beside the rail and the
+   * body at their floors, so the shell has dropped the right panel and its
+   * trigger — UI outside the shell should stand down with them. Read straight
+   * out of the shell's fit atoms; it is only ever `true` once the shell is
+   * mounted and measured. */
+  isNarrow: boolean
+  /** The secondary panel's current width in px, or null until the shell has
+   * measured itself (the panel then sits at `--panel-width`). */
+  panelWidth: number | null
+  /** Resize the secondary panel from outside the shell — clamped to the room
+   * the shell has. */
+  resizePanel: (width: number) => void
   /** Live desktop open state, keyed by side. */
   open: Record<SidebarSide, boolean>
   /** Live mobile overlay state, keyed by side. */
   openMobile: Record<SidebarSide, boolean>
+  /** Refuses to OPEN the right panel while `isNarrow` — there is nothing on
+   * screen to open. Closing it always goes through. */
   setOpen: (open: boolean, side: SidebarSide) => void
   setOpenMobile: (open: boolean, side: SidebarSide) => void
   /** Desktop-only convenience — the in-shell triggers already pick the
-   * mobile state themselves when the viewport is narrow. */
+   * mobile state themselves when the viewport is narrow. Carries the same
+   * `isNarrow` refusal as `setOpen`. */
   toggle: (side: SidebarSide) => void
   /** Spread onto ShellLayout (or AnimatedPanelProvider directly). */
   providerProps: ShellPanelControlProps
@@ -98,7 +203,6 @@ export interface ShellLayoutProps extends ShellPanelControlProps {
   variant?: "web" | "desktop"
 }
 
-
 export type SidebarSide = "left" | "right"
 /** Open flags keyed by the side. Sides left out stay uncontrolled / at their
  * default — there is no per-side prop, the record IS the API. */
@@ -108,6 +212,10 @@ export type SidebarCollapsible = "offcanvas" | "icon" | "none"
 
 export interface AnimatedSidebarContextValue {
   isMobile: boolean
+  /** What the shell measured of itself: whether it can hold a secondary panel
+   * at all, how wide that panel is, and the range a resize may land in. The
+   * right panel and its trigger stand down when `fit.fits` is false. */
+  fit: ShellFitController
   layoutId: string
   /** Desktop open state, keyed by side. */
   open: Record<SidebarSide, boolean>
@@ -122,6 +230,14 @@ export interface AnimatedSidebarContextValue {
 }
 
 export interface AnimatedSidebarProviderProps extends HTMLAttributes<HTMLDivElement> {
+  /** The id this shell's fit state (whether a secondary panel fits, how wide
+   * it is) is filed under in the store. Name it to read or drive the shell
+   * from elsewhere and to keep a dragged width across a route change; omit it
+   * and the provider generates one that is dropped on unmount. */
+  shellId?: ShellFitInstanceId
+  /** The width the secondary panel opens at, in px, instead of
+   * `--panel-width`. Read once, on mount. */
+  defaultPanelWidth?: number
   /** Controlled desktop open state, keyed by the side. A side left undefined
    * stays uncontrolled. */
   open?: SidebarOpenState
@@ -133,13 +249,24 @@ export interface AnimatedSidebarProviderProps extends HTMLAttributes<HTMLDivElem
   /** Initial mobile overlay state — every side starts closed. */
   defaultOpenMobile?: SidebarOpenState
   onOpenMobileChange?: (open: boolean, side: SidebarSide) => void
+  /** Fires when the shell crosses the width a secondary panel needs (rail +
+   * body + panel at their floors). An imperative escape hatch for a consumer
+   * that mounts the provider on its own; anything under `ExegiaProvider` can
+   * subscribe by id instead with `useShellFitState(shellId).fits`. */
+  onNarrowChange?: (isNarrow: boolean) => void
   style?: SidebarProviderStyle
 }
 
 export type SidebarProviderStyle = CSSProperties & {
+  /** Left rail, expanded. */
   "--sidebar-width"?: string
+  /** Left rail, folded to icons. */
   "--sidebar-width-icon"?: string
   "--sidebar-width-mobile"?: string
+  /** The secondary panel's floor, and the width it opens at. */
+  "--panel-width"?: string
+  /** The body's floor — the secondary panel may never squeeze it past this. */
+  "--inset-min-width"?: string
 }
 
 export type AnimatedSidebarInsetProps = HTMLMotionProps<"main">