@exegia/corpora-ui 0.19.0 → 0.21.0

package/dist-lib/components/blocks/scaffold/constants.d.ts

@@ -5,6 +5,11 @@ export declare const SCAFFOLD_INSPECTOR_WIDTH = 272;
 /** Most panels the canvas holds at once — omit Actions' `onAdd` when the
  * count reaches it so the Add segment hides. */
 export declare const SCAFFOLD_PANEL_CAPACITY = 3;
+/** Narrowest a panel may render, in px. When the canvas can't grant every
+ * panel this width, the scaffold hides panels until the rest fit. */
+export declare const SCAFFOLD_PANEL_MIN_WIDTH = 320;
+/** Gap in px between side-by-side panels on the canvas (`gap-2`). */
+export declare const SCAFFOLD_CANVAS_GAP = 8;
 /** Gap in px between the drawer/actions and the viewport edges. */
 export declare const SCAFFOLD_EDGE_GUTTER = 10;
 /** Vertical room in px reserved above the canvas for the actions cluster. */

package/dist-lib/components/blocks/scaffold/scaffold-canvas.d.ts

@@ -3,5 +3,7 @@ import * as React from "react";
 /**
  * The panel row below the action cluster: 8px gutters, 8px gaps, panels
  * side by side. Key each `Scaffold.Panel` child so closes animate out.
+ * Measures its own width and hides id'd panels (oldest activation first)
+ * whenever it can't grant each one `SCAFFOLD_PANEL_MIN_WIDTH`.
  */
 export declare function ScaffoldCanvas({ className, children, ...rest }: ScaffoldCanvasProps): React.ReactElement;

package/dist-lib/components/blocks/scaffold/scaffold-panel.d.ts

@@ -7,4 +7,4 @@ import * as React from "react";
  * the two cards with a layout morph — the strip glides up and grows into the
  * primary slot while the primary card shrinks down into the strip.
  */
-export declare function ScaffoldPanel({ children, SecondaryPanel, onSwap, onCloseSecondary, name, swapLabel, sound, className, }: ScaffoldPanelProps): React.ReactElement;
+export declare function ScaffoldPanel({ id, children, SecondaryPanel, onSwap, onCloseSecondary, name, swapLabel, sound, className, }: ScaffoldPanelProps): React.ReactElement;

package/dist-lib/components/blocks/scaffold/scaffold-tab.d.ts

@@ -5,5 +5,10 @@ import * as React from "react";
  * affordance. Render one per open panel as Actions children, keyed —
  * closes animate out of the pill. Omit `onClose` on the last remaining
  * panel's tab; the canvas keeps at least one panel open.
+ *
+ * With `panelId` (matching a `Scaffold.Panel`'s `id`), the tab also fronts
+ * that panel's visibility: a hidden panel dims its tab behind an eye-off
+ * icon, and pressing the label toggles the panel — showing one past
+ * capacity hides the least-recently-activated panel in its place.
  */
-export declare function ScaffoldTab({ children, onClose, closeLabel, sound, className, ...rest }: ScaffoldTabProps): React.ReactElement;
+export declare function ScaffoldTab({ children, panelId, onClose, closeLabel, sound, className, ...rest }: ScaffoldTabProps): React.ReactElement;

package/dist-lib/components/blocks/scaffold/type.d.ts

@@ -7,6 +7,25 @@ export interface ScaffoldContextValue {
     inspectorWidth: number;
     setInspectorOpen: (open: boolean) => void;
     toggleInspector: () => void;
+    /** 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;
 }
 export interface ScaffoldRootProps extends ComponentProps<"div"> {
     /** Controlled inspector state — pair with `onInspectorOpenChange`, or
@@ -41,6 +60,11 @@ export interface ScaffoldActionsProps extends MotionSafe<Omit<ComponentProps<"di
 }
 export type TScaffoldPanelChild<T extends ScaffoldSubPanelProps = ScaffoldSubPanelProps> = ReactElement<T, React.JSXElementConstructor<T>>;
 export interface ScaffoldPanelProps {
+    /** Stable id opting the panel into responsive hiding: the canvas hides
+     * id'd panels when it can't grant each `SCAFFOLD_PANEL_MIN_WIDTH`, and a
+     * `Scaffold.Tab` with the matching `panelId` reflects and toggles it.
+     * Omitted, the panel always renders. */
+    id?: string;
     /** The panel's content, rendered in a card with a drop shadow. */
     children: ReactNode;
     /** The panel's content, rendered in a card with a drop shadow. */
@@ -64,6 +88,10 @@ export interface ScaffoldPanelProps {
 export interface ScaffoldTabProps extends MotionSafe<Omit<ComponentProps<"div">, "children">> {
     /** The tab's label. */
     children?: ReactNode;
+    /** Id of the panel this tab fronts (`Scaffold.Panel`'s `id`). The tab
+     * then shows whether the panel is hidden and pressing its label toggles
+     * visibility — showing past capacity hides another panel in its place. */
+    panelId?: string;
     /** Renders the tab's close button. The button renders only while this
      * is present — omit it to pin the tab, e.g. on the last remaining
      * panel (the canvas keeps at least one open). */

package/dist-lib/components/blocks/scaffold/use-panel-visibility.d.ts

@@ -0,0 +1,19 @@
+export interface PanelVisibility {
+    /** How many panels currently fit side by side (1..capacity cap). */
+    panelCapacity: number;
+    /** Ids of panels currently hidden (auto + user), for tabs to reflect. */
+    hiddenPanelIds: readonly string[];
+    isPanelHidden: (id: string) => boolean;
+    togglePanelVisibility: (id: string) => void;
+    /** Id of the panel whose tab is hovered — the canvas spotlights it. */
+    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 each render. */
+    registerPanelIds: (ids: readonly string[]) => void;
+    /** @internal Canvas reports its measured width. */
+    setCanvasWidth: (width: number) => void;
+}
+/** Owns which panels are hidden as the canvas gains and loses room.
+ * Lives in `Scaffold.Root`; Canvas and Tab reach it through context. */
+export declare function usePanelVisibility(): PanelVisibility;

package/dist-lib/components/blocks/scaffold/utils.d.ts

@@ -1,6 +1,12 @@
 import { Variants } from 'motion/react';
 import { ClassNameValue } from 'tailwind-merge';
 import { TSubPanelVariant } from './type.ts';
+/**
+ * How many panels fit on a canvas of `width` px, granting each
+ * `SCAFFOLD_PANEL_MIN_WIDTH` plus the gaps between them. Clamped to
+ * [1, SCAFFOLD_PANEL_CAPACITY]; an unmeasured canvas (`null`) fits the cap.
+ */
+export declare function getPanelCapacity(width: number | null): number;
 /** Desktop backdrop the whole scaffold sits on — a soft warm-gray wash. */
 export declare const scaffoldBackgroundClass: ClassNameValue;
 /** Card surface shared by a panel's primary area and secondary strip. */

package/dist-lib/components/blocks/shell/__tests__/shell-fit-atom.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/blocks/shell/__tests__/shell-metrics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/blocks/shell/animated-panel-provider.d.ts

@@ -1,2 +1,2 @@
 import { AnimatedSidebarProviderProps } from './type';
-export declare function AnimatedPanelProvider({ children, open, defaultOpen, onOpenChange, openMobile, defaultOpenMobile, onOpenMobileChange, className, style, ...props }: AnimatedSidebarProviderProps): import("react").JSX.Element;
+export declare function AnimatedPanelProvider({ children, shellId, defaultPanelWidth, open, defaultOpen, onOpenChange, openMobile, defaultOpenMobile, onOpenMobileChange, onNarrowChange, className, style, ...props }: AnimatedSidebarProviderProps): import("react").JSX.Element;

package/dist-lib/components/blocks/shell/animated-panel.d.ts

@@ -1,2 +1,2 @@
 import { AnimatedSidebarProps } from './type';
-export declare function AnimatedPanel({ side, variant, collapsible, ariaLabel, children, className, panelClassName, style, ref, ...props }: AnimatedSidebarProps): import("react").JSX.Element;
+export declare function AnimatedPanel({ side, variant, collapsible, ariaLabel, children, className, panelClassName, style, ref, ...props }: AnimatedSidebarProps): import("react").JSX.Element | null;

package/dist-lib/components/blocks/shell/index.d.ts

@@ -1,6 +1,10 @@
 import { ShellLayout } from './shell-layout';
 export type * from './type';
+export * from './shell-metrics';
 export * from './use-shell-panels';
+export { useShellFit } from './use-shell-fit';
+export { useShellFitActions, useShellFitState } from './use-shell-fit-state';
+export { removeShellFitInstance, resetShellPanelWidthAtom, resizeShellPanelAtom, shellFitFitsAtom, shellFitMeasuredAtom, shellFitMetricsAtom, shellFitPanelBoundsAtom, shellFitPanelWidthAtom, shellFitRequestedWidthAtom, shellFitStateAtom, } from './shell-fit-atom';
 export * from './utils';
 export * from './animated-panel';
 export * from './animated-panel-inset';

package/dist-lib/components/blocks/shell/shell-fit-atom.d.ts

@@ -0,0 +1,68 @@
+import { ShellMetrics } from './shell-metrics';
+import { ShellFitInstanceId, ShellFitPanelBounds, ShellFitSeed, ShellFitState } from './type';
+/**
+ * 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;
+};
+/** 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 declare const shellFitMetricsAtom: Family<import('jotai').PrimitiveAtom<ShellMetrics> & {
+    init: ShellMetrics;
+}>;
+/** 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 declare const shellFitRequestedWidthAtom: Family<import('jotai').PrimitiveAtom<number | null> & {
+    init: number | null;
+}>;
+/** 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 declare const shellFitMeasuredAtom: Family<import('jotai').Atom<ShellMetrics | null>>;
+/** Whether the shell can hold a secondary panel at all. */
+export declare const shellFitFitsAtom: Family<import('jotai').Atom<boolean>>;
+/** The range a resize may land in. */
+export declare const shellFitPanelBoundsAtom: Family<import('jotai').Atom<ShellFitPanelBounds>>;
+/** The width the secondary panel renders at, or null before the first
+ * measurement, where the caller falls back to `--panel-width`. */
+export declare const shellFitPanelWidthAtom: Family<import('jotai').Atom<number | null>>;
+/** 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 declare const shellFitStateAtom: Family<import('jotai').Atom<ShellFitState>>;
+/** @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 declare const measureShellFitAtom: Family<import('jotai').WritableAtom<null, [metrics: ShellMetrics], void> & {
+    init: null;
+}>;
+/** 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 declare const resizeShellPanelAtom: Family<import('jotai').WritableAtom<null, [width: number], void> & {
+    init: null;
+}>;
+/** Back to the width the shell mounted with — `defaultPanelWidth`, or
+ * `--panel-width` when there was none. */
+export declare const resetShellPanelWidthAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** @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 declare const mountShellFitAtom: Family<import('jotai').WritableAtom<null, [seed: ShellFitSeed], void> & {
+    init: null;
+}>;
+/** 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 declare function removeShellFitInstance(id: ShellFitInstanceId): void;
+export {};

package/dist-lib/components/blocks/shell/shell-metrics.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare function requiredWidth({ rail, insetMin, panelMin }: ShellMetrics): number;
+/**
+ * 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 declare function fitsPanel(metrics: ShellMetrics): boolean;
+/** 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 declare function panelBounds(metrics: ShellMetrics): {
+    min: number;
+    max: number;
+};
+export declare function clampPanelWidth(width: number, metrics: ShellMetrics): number;
+/** 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 declare function metricsEqual(a: ShellMetrics, b: ShellMetrics): boolean;

package/dist-lib/components/blocks/shell/type.d.ts

@@ -1,5 +1,68 @@
-import { ReactNode, ButtonHTMLAttributes, CSSProperties, HTMLAttributes } from 'react';
+import { ReactNode, RefObject, ButtonHTMLAttributes, CSSProperties, HTMLAttributes } from 'react';
 import { HTMLMotionProps } from 'motion/react';
+import { ShellMetrics } from './shell-metrics';
+/** 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;
@@ -38,27 +101,53 @@ export type TPanelMap<Side extends TPanelSide = TPanelSide> = Partial<Record<Sid
  * AnimatedPanelProvider — every prop is keyed by side, there are no
  * explicit per-side props. `useShellPanels` produces the controlled subset
  * of these as `providerProps`. */
-export type ShellPanelControlProps = Pick<AnimatedSidebarProviderProps, "open" | "defaultOpen" | "onOpenChange" | "openMobile" | "defaultOpenMobile" | "onOpenMobileChange">;
+export type ShellPanelControlProps = Pick<AnimatedSidebarProviderProps, "open" | "defaultOpen" | "onOpenChange" | "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. */
     onPanelChange?: (open: boolean, side: TPanelSide) => void;
 }
 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;
@@ -80,6 +169,10 @@ export type SidebarVariant = "sidebar" | "floating" | "inset";
 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>;
@@ -93,6 +186,14 @@ export interface AnimatedSidebarContextValue {
     triggerRefs: Record<SidebarSide, React.RefObject<HTMLButtonElement | null>>;
 }
 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;
@@ -104,12 +205,23 @@ 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">;
 export interface AnimatedSidebarTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {

package/dist-lib/components/blocks/shell/use-shell-fit-state.d.ts

@@ -0,0 +1,25 @@
+import { ShellFitActions, ShellFitInstanceId, ShellFitState } from './type';
+/**
+ * Read the fit of the shell registered under `shellId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { fits, panelWidth } = useShellFitState("app-shell")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on every
+ * measurement. A component that reads one field should subscribe to that
+ * field's atom instead: `useAtomValue(shellFitFitsAtom("app-shell"))`.
+ */
+export declare function useShellFitState(shellId: ShellFitInstanceId): ShellFitState;
+/**
+ * Drive the secondary panel of the shell registered under `shellId` from
+ * anywhere. Writes only — the caller never re-renders when the shell moves,
+ * so this is what a command palette or a keyboard shortcut should reach for.
+ *
+ * ```tsx
+ * const shell = useShellFitActions("app-shell")
+ * <Button onClick={() => shell.resizePanel(480)}>Wide inspector</Button>
+ * ```
+ */
+export declare function useShellFitActions(shellId: ShellFitInstanceId): ShellFitActions;

package/dist-lib/components/blocks/shell/use-shell-fit.d.ts

@@ -0,0 +1,14 @@
+import { ShellFitController, UseShellFitOptions } from './type';
+/**
+ * Measures the shell and decides what the secondary panel may do: whether it
+ * exists at all, and how wide it may be dragged.
+ *
+ * The three things that move the answer are all observed here — the viewport
+ * (`resize`), the rail's fold (`railOpen`, a render input) and the user's own
+ * drag (`resizePanel`) — so no caller has to re-derive it. The measurement is
+ * the only thing this hook keeps to itself: the numbers land in the shell-fit
+ * atoms keyed by `shellId`, so anything under `ExegiaProvider` can read the
+ * verdict (`useShellFitState`) or move the panel (`useShellFitActions`)
+ * without holding this controller.
+ */
+export declare function useShellFit({ shellId: explicitId, hostRef, railOpen, defaultPanelWidth, onUnfit, }: UseShellFitOptions): ShellFitController;

package/dist-lib/components/blocks/shell/use-shell-panels.d.ts

@@ -5,5 +5,16 @@ import { ShellPanelControls, UseShellPanelsOptions } from './type';
  * callback. Spread the returned `providerProps` onto ShellLayout; the
  * setters and `toggle` are for UI that lives outside the shell (title-bar
  * buttons, command palette, shortcuts).
+ *
+ * The way back down is the store: `providerProps` carries a `shellId`, the
+ * shell files its measurement under it, and this hook reads `isNarrow` and
+ * `panelWidth` straight out of those atoms — so outside UI stands down with
+ * the panel instead of measuring `--sidebar-width` a second time. Name the
+ * `shellId` and any component below `ExegiaProvider` can do the same with
+ * `useShellFitState(shellId)`.
+ *
+ * Call it under the same `ExegiaProvider` as the shell it drives (or under
+ * none at all, on both sides): mounted above the provider it would read
+ * Jotai's default store while the shell writes to the provider's.
  */
-export declare function useShellPanels({ defaultOpen, defaultOpenMobile, onPanelChange, }?: UseShellPanelsOptions): ShellPanelControls;
+export declare function useShellPanels({ shellId: explicitId, defaultOpen, defaultOpenMobile, defaultPanelWidth, onPanelChange, }?: UseShellPanelsOptions): ShellPanelControls;

package/dist-lib/components/blocks/shell/utils.d.ts

@@ -29,6 +29,38 @@ export declare const SUBMENU_ITEM_VARIANTS: Variants;
 export declare const FOCUSABLE_SELECTOR: string;
 export declare const MOBILE_QUERY = "(max-width: 767px)";
 export declare const SIDEBAR_KEYBOARD_SHORTCUT = "b";
+/**
+ * The shell's layout contract, in px. Every entry lands on the provider's
+ * wrapper as a CSS variable, so a consumer overrides a column by restyling it
+ * rather than by passing a prop:
+ *
+ * | variable               | column                                    |
+ * | ---------------------- | ----------------------------------------- |
+ * | `--sidebar-width`      | left rail, expanded                       |
+ * | `--sidebar-width-icon` | left rail, folded to icons                |
+ * | `--panel-width`        | secondary panel: its floor AND its default |
+ * | `--inset-min-width`    | the body's floor                          |
+ *
+ * These are only the defaults. Every measurement resolves the live variable,
+ * so an override wins over the value written here.
+ */
+export declare const SHELL_WIDTHS: {
+    readonly "--sidebar-width": "256px";
+    readonly "--sidebar-width-icon": "56px";
+    readonly "--sidebar-width-mobile": "18rem";
+    readonly "--panel-width": "320px";
+    readonly "--inset-min-width": "360px";
+};
+/** The expanded width of a panel docked to `side`: the secondary panel opens
+ * at `--panel-width`, the primary rail at `--sidebar-width`. */
+export declare function expandedWidthVar(side: "left" | "right"): "var(--panel-width)" | "var(--sidebar-width)";
+/** Resolve a CSS length — `var()` included — to px inside `host`'s cascade.
+ * Custom properties inherit, so a throwaway probe mounted in `host` reads the
+ * very `--sidebar-width` the shell lays out with, including a value a
+ * consumer overrode on the provider. Returns 0 when `host` has no layout
+ * (server render, `display: none`), so callers must fail open on 0 rather
+ * than treat it as a real measurement. */
+export declare function resolveLength(host: HTMLElement, value: string): number;
 export declare const AnimatedSidebarContext: import('react').Context<AnimatedSidebarContextValue | null>;
 export declare const AnimatedSidebarPanelContext: import('react').Context<AnimatedSidebarPanelContextValue | null>;
 export declare function useAnimatedSidebar(): AnimatedSidebarContextValue;

package/dist-lib/components/composed/tree/__tests__/tree-atom.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/composed/tree/__tests__/tree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/composed/tree/__tests__/use-tree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/composed/tree/constants.d.ts

@@ -0,0 +1,35 @@
+import { Transition, Variants } from 'motion/react';
+/** `--ease-smooth-out` as a motion/react easing tuple. */
+export declare const TREE_EASE: readonly [0.22, 1, 0.36, 1];
+/** Branch open — `--duration-fast` territory (accordion open). */
+export declare const TREE_OPEN_DURATION = 0.25;
+/** Branch close — quicker than open, per open/close asymmetry. */
+export declare const TREE_CLOSE_DURATION = 0.15;
+/** Chevron flip and label fades. */
+export declare const TREE_MICRO_DURATION = 0.15;
+/** Sidebar rail label reveal/hide when `collapsed` flips. */
+export declare const TREE_COLLAPSE_DURATION = 0.2;
+/** The collapsed rail's width in px — one `h-10 rounded-xl` icon row, edge
+ * to edge. Kept in sync with the `w-10` resting class the rail falls back to
+ * before its expanded width has been measured. */
+export declare const RAIL_COLLAPSED_WIDTH = 40;
+/** Rail label text fade — starts as the width growth is finishing, so the
+ * label never reads as clipped mid-grow. */
+export declare const TREE_LABEL_REVEAL_DELAY = 0.01;
+/** A branch's children group: grows open with a soft stagger, folds shut
+ * faster. Height rides layout ("auto"), paint fades. */
+export declare const TREE_BRANCH_VARIANTS: Variants;
+/** Branch close — a plain target, NOT the "closed" variant label: a
+ * labeled exit orchestrates every variant child and AnimatePresence then
+ * waits on the whole subtree before unmounting. */
+export declare const TREE_BRANCH_EXIT: {
+    height: number;
+    opacity: number;
+    transition: {
+        duration: number;
+        ease: readonly [0.22, 1, 0.36, 1];
+    };
+};
+/** One row inside an opening branch — a short blurred rise. */
+export declare const TREE_ROW_VARIANTS: Variants;
+export declare const TREE_MICRO_TRANSITION: Transition;

package/dist-lib/components/composed/tree/index.d.ts

@@ -0,0 +1,6 @@
+export { Tree } from './tree';
+export { useTree } from './use-tree';
+export { useTreeActions, useTreeState } from './use-tree-state';
+export { moveNode, renameNode } from './utils';
+export { cancelTreeRenameAtom, collapseAllTreeNodesAtom, collapseTreeNodeAtom, expandAllTreeNodesAtom, expandTreeNodeAtom, moveTreeNodeAtom, removeTreeInstance, renameTreeNodeAtom, resetTreeAtom, revealTreeNodeAtom, selectTreeNodeAtom, setTreeCollapsedAtom, setTreeItemsAtom, startTreeRenameAtom, toggleTreeCollapsedAtom, toggleTreeNodeAtom, treeActiveIdAtom, treeCanMoveAtom, treeCanRenameAtom, treeCollapsedAtom, treeDraggedIdAtom, treeDropTargetAtom, treeExpandedIdsAtom, treeItemsAtom, treeRenamingIdAtom, treeSectionedAtom, treeSectionIdsAtom, treeStateAtom, } from './tree-atom';
+export type { TreeActions, TreeController, TreeControllerProps, TreeDataProps, TreeDropPosition, TreeDropTarget, TreeInstanceId, TreeNode, TreeProps, TreeState, TreeVariant, UseTreeOptions, } from './type';