@jini-ai/admin 0.3.10 → 0.4.0

package/dist/react/hooks/use-nav-sections.js

@@ -43,9 +43,9 @@ export const DEFAULT_NAV_SECTIONS_STORAGE_KEY = 'jini-admin-nav-sections';
  * Non-boolean entries are dropped individually rather than rejecting the whole map, so one bad key
  * cannot discard a user's other sections.
  */
-function readPersisted(storageKey) {
+function readPersisted(storageKey, storage) {
     try {
-        const raw = localStorage.getItem(storageKey);
+        const raw = storage.getItem(storageKey);
         if (raw === null)
             return {};
         const parsed = JSON.parse(raw);
@@ -62,9 +62,9 @@ function readPersisted(storageKey) {
         return {};
     }
 }
-function writePersisted(storageKey, state) {
+function writePersisted(storageKey, state, storage) {
     try {
-        localStorage.setItem(storageKey, JSON.stringify(state));
+        storage.setItem(storageKey, JSON.stringify(state));
     }
     catch {
         // Best-effort, exactly as in `use-sidebar-rail.ts`: a user who cannot persist still gets a
@@ -81,19 +81,19 @@ function writePersisted(storageKey, state) {
  * handful, fixed by the host's panel manifest, never user-variable.
  * @overallScore 100
  */
-export function useNavSections(storageKey = DEFAULT_NAV_SECTIONS_STORAGE_KEY) {
-    const [state, setState] = useState(() => readPersisted(storageKey));
-    const isOpen = useCallback((groupLabel) => state[groupLabel] ?? true, [state]);
-    const toggle = useCallback((groupLabel) => {
+export function useNavSections({ storage, events }, { storageKey = DEFAULT_NAV_SECTIONS_STORAGE_KEY } = {}) {
+    const [state, setState] = useState(() => readPersisted(storageKey, storage));
+    const isOpen = useCallback(({ groupLabel }) => state[groupLabel] ?? true, [state]);
+    const toggle = useCallback(({ groupLabel }) => {
         setState((current) => {
             // `?? true` here and in `isOpen` must agree: toggling a section that has never been stored
             // has to close it (it is currently rendered open), not open an already-open section — which
             // is what a bare `!current[label]` would do on the `undefined` first press.
             const next = { ...current, [groupLabel]: !(current[groupLabel] ?? true) };
-            writePersisted(storageKey, next);
+            writePersisted(storageKey, next, storage);
             return next;
         });
-    }, [storageKey]);
+    }, [storageKey, storage]);
     /** Cross-tab sync — two admin tabs should agree on the layout rather than diverging the moment
      *  either one collapses a section. Mirrors `useSidebarRail`'s listener, including treating a
      *  removed key (`newValue === null`, another tab clearing storage) as "no stored preference"
@@ -102,11 +102,11 @@ export function useNavSections(storageKey = DEFAULT_NAV_SECTIONS_STORAGE_KEY) {
         function onStorage(event) {
             if (event.key !== storageKey)
                 return;
-            setState(event.newValue === null ? {} : readPersisted(storageKey));
+            setState(event.newValue === null ? {} : readPersisted(storageKey, storage));
         }
-        window.addEventListener('storage', onStorage);
-        return () => window.removeEventListener('storage', onStorage);
-    }, [storageKey]);
+        events.addEventListener('storage', onStorage);
+        return () => events.removeEventListener('storage', onStorage);
+    }, [storageKey, storage, events]);
     return { isOpen, toggle };
 }
 //# sourceMappingURL=use-nav-sections.js.map

package/dist/react/hooks/use-sidebar-rail.d.ts

@@ -35,5 +35,11 @@ export interface SidebarRail {
  *
  * @complexity O(1) — one state read/write per toggle, no derived computation.
  */
-export declare function useSidebarRail(storageKey?: string, defaultCollapsed?: boolean): SidebarRail;
+export declare function useSidebarRail({ storage, events }: {
+    readonly storage: Pick<Storage, 'getItem' | 'setItem'>;
+    readonly events: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+}, { storageKey, defaultCollapsed }?: {
+    readonly storageKey?: string | undefined;
+    readonly defaultCollapsed?: boolean | undefined;
+}): SidebarRail;
 //# sourceMappingURL=use-sidebar-rail.d.ts.map

package/dist/react/hooks/use-sidebar-rail.js

@@ -32,9 +32,9 @@ export const DEFAULT_SIDEBAR_RAIL_STORAGE_KEY = 'jini-admin-sidebar-rail-collaps
  * it collapsed again on every reload, because their explicit `'0'` would be indistinguishable from
  * never having chosen. A stored value always wins over the default; only its absence defers.
  */
-function readPersisted(storageKey) {
+function readPersisted(storageKey, storage) {
     try {
-        const raw = localStorage.getItem(storageKey);
+        const raw = storage.getItem(storageKey);
         if (raw === null)
             return undefined;
         return raw === '1';
@@ -43,9 +43,9 @@ function readPersisted(storageKey) {
         return undefined;
     }
 }
-function writePersisted(storageKey, collapsed) {
+function writePersisted(storageKey, collapsed, storage) {
     try {
-        localStorage.setItem(storageKey, collapsed ? '1' : '0');
+        storage.setItem(storageKey, collapsed ? '1' : '0');
     }
     catch {
         // Best-effort — a user who cannot persist the preference still gets a working toggle for the
@@ -64,15 +64,15 @@ function writePersisted(storageKey, collapsed) {
  *
  * @complexity O(1) — one state read/write per toggle, no derived computation.
  */
-export function useSidebarRail(storageKey = DEFAULT_SIDEBAR_RAIL_STORAGE_KEY, defaultCollapsed = false) {
-    const [collapsed, setCollapsed] = useState(() => readPersisted(storageKey) ?? defaultCollapsed);
+export function useSidebarRail({ storage, events }, { storageKey = DEFAULT_SIDEBAR_RAIL_STORAGE_KEY, defaultCollapsed = false } = {}) {
+    const [collapsed, setCollapsed] = useState(() => readPersisted(storageKey, storage) ?? defaultCollapsed);
     const toggle = useCallback(() => {
         setCollapsed((current) => {
             const next = !current;
-            writePersisted(storageKey, next);
+            writePersisted(storageKey, next, storage);
             return next;
         });
-    }, [storageKey]);
+    }, [storageKey, storage]);
     /** Cross-tab sync: two admin tabs open side by side should agree on the rail state rather than
      *  silently diverging the moment either one is toggled. */
     useEffect(() => {
@@ -85,9 +85,9 @@ export function useSidebarRail(storageKey = DEFAULT_SIDEBAR_RAIL_STORAGE_KEY, de
             // collapsed-by-default host in every other one.
             setCollapsed(event.newValue === null ? defaultCollapsed : event.newValue === '1');
         }
-        window.addEventListener('storage', onStorage);
-        return () => window.removeEventListener('storage', onStorage);
-    }, [storageKey, defaultCollapsed]);
+        events.addEventListener('storage', onStorage);
+        return () => events.removeEventListener('storage', onStorage);
+    }, [storageKey, defaultCollapsed, events]);
     return { collapsed, toggle };
 }
 //# sourceMappingURL=use-sidebar-rail.js.map

package/dist/react/index.d.ts

@@ -41,7 +41,7 @@ export type { ConfirmDialogController, UseConfirmDialog } from './components/Con
 export { ConfirmDialogDefaultsProvider } from './components/ConfirmDialog/ConfirmDialog.hooks.js';
 export type { ConfirmDialogDefaults, ConfirmDialogDefaultsProviderProps, } from './components/ConfirmDialog/ConfirmDialog.hooks.js';
 export { DataTable } from './components/DataTable.js';
-export type { DataTableColumn, DataTableProps } from './components/DataTable.js';
+export type { DataTableColumn, DataTableColumnSort, DataTableProps, DataTableSortDirection, DataTableSortState, } from './components/DataTable.js';
 export { InteractiveHtmlEditor } from './components/InteractiveHtmlEditor/InteractiveHtmlEditor.js';
 export type { InteractiveHtmlEditorProps } from './components/InteractiveHtmlEditor/InteractiveHtmlEditor.js';
 export { RowMenu } from './components/RowMenu/RowMenu.js';
@@ -52,4 +52,6 @@ export { DEFAULT_SIDEBAR_RAIL_STORAGE_KEY, useSidebarRail } from './hooks/use-si
 export type { SidebarRail } from './hooks/use-sidebar-rail.js';
 export { DEFAULT_NAV_SECTIONS_STORAGE_KEY, useNavSections } from './hooks/use-nav-sections.js';
 export type { NavSections, NavSectionState } from './hooks/use-nav-sections.js';
+export * from './shell/index.js';
+export * from './entities/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.js

@@ -39,8 +39,9 @@ export { ConfirmDialog } from './components/ConfirmDialog/ConfirmDialog.js';
 // Host-wide `ConfirmDialog` defaults (today just a translated `cancelLabel`), set once at an app
 // root rather than passed at every call site — see `ConfirmDialogDefaultsProvider`'s doc comment.
 export { ConfirmDialogDefaultsProvider } from './components/ConfirmDialog/ConfirmDialog.hooks.js';
-// The list table. Deliberately has no sorting, pagination or row selection — see its file header
-// for the corpus evidence behind each omission.
+// The list table. Sorting is opt-in per column (`DataTableColumn.sort`); pagination and row
+// selection are still deliberately absent — see its file header for the corpus evidence behind
+// every one of these decisions.
 export { DataTable } from './components/DataTable.js';
 // Visual click-into-text editing surface for a bespoke HTML document, built on GrapesJS. See its
 // own file header for the styling-contract exception it carries (vendor CSS import) and the
@@ -53,4 +54,6 @@ export { RowMenu } from './components/RowMenu/RowMenu.js';
 export { Sidebar, useSidebar } from './components/Sidebar.js';
 export { DEFAULT_SIDEBAR_RAIL_STORAGE_KEY, useSidebarRail } from './hooks/use-sidebar-rail.js';
 export { DEFAULT_NAV_SECTIONS_STORAGE_KEY, useNavSections } from './hooks/use-nav-sections.js';
+export * from './shell/index.js';
+export * from './entities/index.js';
 //# sourceMappingURL=index.js.map

package/dist/react/kit/Kit.hooks.d.ts

@@ -0,0 +1,13 @@
+import type { ReactAdminKit } from './types.js';
+export declare const KitContext: import("react").Context<ReactAdminKit>;
+export declare function useKitComponent<K extends keyof ReactAdminKit>({ name }: {
+    name: K;
+}, _optional?: Record<string, never>): ReactAdminKit[K];
+export declare function useKitProvider({ kit }: {
+    kit?: Partial<ReactAdminKit>;
+}, _optional?: Record<string, never>): {
+    Button: import("react").ComponentType<import("./types.js").ButtonProps>;
+    Dialog: import("react").ComponentType<import("./types.js").DialogProps>;
+    TextField: import("react").ComponentType<import("./types.js").TextFieldProps>;
+};
+//# sourceMappingURL=Kit.hooks.d.ts.map

package/dist/react/kit/Kit.hooks.js

@@ -0,0 +1,10 @@
+import { createContext, useContext, useMemo } from 'react';
+import { nativeKit } from './native.js';
+export const KitContext = createContext(nativeKit);
+export function useKitComponent({ name }, _optional = {}) {
+    return useContext(KitContext)[name];
+}
+export function useKitProvider({ kit = {} }, _optional = {}) {
+    return useMemo(() => ({ ...nativeKit, ...kit }), [kit]);
+}
+//# sourceMappingURL=Kit.hooks.js.map

package/dist/react/kit/Native.hooks.d.ts

@@ -0,0 +1,38 @@
+import type { ChangeEvent, MouseEvent, SyntheticEvent } from 'react';
+import type { ButtonProps, DialogProps, TextFieldProps } from './types.js';
+export declare function useNativeButton(props: ButtonProps, _optional?: Record<string, never>): {
+    disabled: boolean;
+    onClick: () => void;
+    attrs: import("./types.js").KitAttrs;
+    children: import("react").ReactNode;
+    onPress?: () => void;
+    pending?: boolean;
+    variant?: "primary" | "secondary" | "danger";
+    type?: "button" | "submit";
+    ref?: import("react").Ref<HTMLButtonElement>;
+};
+export declare function useNativeTextField(props: TextFieldProps, _optional?: Record<string, never>): {
+    id: string;
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    attrs: import("./types.js").KitAttrs;
+    label: string;
+    value: string;
+    onValueChange: (value: string) => void;
+    disabled?: boolean;
+    type?: "text" | "password" | "search";
+    ref?: import("react").Ref<HTMLInputElement>;
+};
+export declare function useNativeDialog(props: DialogProps, _optional?: Record<string, never>): {
+    dialogRef: import("react").RefObject<HTMLDialogElement | null>;
+    titleId: string;
+    onCancel: (event: SyntheticEvent<HTMLDialogElement>) => void;
+    onClick: (event: MouseEvent<HTMLDialogElement>) => void;
+    attrs: import("./types.js").KitAttrs;
+    title: string;
+    open: boolean;
+    children: import("react").ReactNode;
+    onClose: () => void;
+    pending?: boolean;
+    ref?: import("react").Ref<HTMLDialogElement>;
+};
+//# sourceMappingURL=Native.hooks.d.ts.map

package/dist/react/kit/Native.hooks.js

@@ -0,0 +1,65 @@
+import { useEffect, useRef, useId, useImperativeHandle } from 'react';
+export function useNativeButton(props, _optional = {}) {
+    return {
+        ...props,
+        disabled: props.disabled === true || props.pending === true,
+        onClick: () => {
+            if (!props.disabled && !props.pending)
+                props.onPress?.();
+        },
+    };
+}
+export function useNativeTextField(props, _optional = {}) {
+    const generated = useId();
+    const id = props.attrs.id ?? generated;
+    return {
+        ...props,
+        id,
+        onChange: (event) => props.onValueChange(event.currentTarget.value),
+    };
+}
+export function useNativeDialog(props, _optional = {}) {
+    const dialogRef = useRef(null), trigger = useRef(null), titleId = useId();
+    useImperativeHandle(props.ref, () => dialogRef.current, []);
+    useEffect(() => {
+        const dialog = dialogRef.current;
+        if (!dialog || !props.open)
+            return;
+        trigger.current = document.activeElement;
+        // <dialog> may not support showModal() in tests/older browsers. Guard already-open
+        // calls, which throw InvalidStateError in real browsers, and fall back to open.
+        if (typeof dialog.showModal === 'function') {
+            if (!dialog.open)
+                dialog.showModal();
+        }
+        else
+            dialog.setAttribute('open', '');
+        // Focus Cancel/Close, the always-available action, rather than a destructive control.
+        const focus = dialog.querySelector('[data-jini-autofocus]') ?? dialog;
+        focus.focus();
+        return () => {
+            if (typeof dialog.close === 'function') {
+                if (dialog.open)
+                    dialog.close();
+            }
+            else
+                dialog.removeAttribute('open');
+            if (trigger.current instanceof HTMLElement)
+                trigger.current.focus();
+        };
+        // Deliberately keyed on open, not content: navigation while already open must
+        // not reopen the dialog or capture a different trigger for focus restoration.
+    }, [props.open]);
+    function onCancel(event) {
+        // Always prevented so the effect stays the single source of truth for open/closed.
+        event.preventDefault();
+        if (!props.pending)
+            props.onClose();
+    }
+    function onClick(event) {
+        if (!props.pending && event.target === event.currentTarget)
+            props.onClose();
+    }
+    return { ...props, dialogRef, titleId, onCancel, onClick };
+}
+//# sourceMappingURL=Native.hooks.js.map

package/dist/react/kit/index.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import type { ReactAdminKit, ButtonProps, TextFieldProps, DialogProps } from './types.js';
+export type { ReactAdminKit, ButtonProps, TextFieldProps, DialogProps, KitAttrs } from './types.js';
+export { KIT_CONTRACT_VERSION } from './types.js';
+export declare function KitProvider(props: {
+    kit?: Partial<ReactAdminKit>;
+    children: ReactNode;
+}, _optional?: Record<string, never>): import("react").JSX.Element;
+export declare const Button: import("react").ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+export declare const TextField: import("react").ForwardRefExoticComponent<Omit<TextFieldProps, "ref"> & import("react").RefAttributes<HTMLInputElement>>;
+export declare const Dialog: import("react").ForwardRefExoticComponent<Omit<DialogProps, "ref"> & import("react").RefAttributes<HTMLDialogElement>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/kit/index.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { KitContext, useKitComponent, useKitProvider } from './Kit.hooks.js';
+export { KIT_CONTRACT_VERSION } from './types.js';
+export function KitProvider(props, _optional = {}) {
+    const kit = useKitProvider(props);
+    return _jsx(KitContext.Provider, { value: kit, children: props.children });
+}
+export const Button = forwardRef(function Button(props, ref) {
+    const Component = useKitComponent({ name: 'Button' });
+    return _jsx(Component, { ...props, ref: ref });
+});
+export const TextField = forwardRef(function TextField(props, ref) {
+    const Component = useKitComponent({ name: 'TextField' });
+    return _jsx(Component, { ...props, ref: ref });
+});
+export const Dialog = forwardRef(function Dialog(props, ref) {
+    const Component = useKitComponent({ name: 'Dialog' });
+    return _jsx(Component, { ...props, ref: ref });
+});
+//# sourceMappingURL=index.js.map

package/dist/react/kit/native.d.ts

@@ -0,0 +1,3 @@
+import type { ReactAdminKit } from './types.js';
+export declare const nativeKit: ReactAdminKit;
+//# sourceMappingURL=native.d.ts.map

package/dist/react/kit/native.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { useNativeButton, useNativeDialog, useNativeTextField } from './Native.hooks.js';
+const NativeButton = forwardRef(function NativeButton(props, ref) {
+    const vm = useNativeButton({ ...props, ref });
+    return (_jsx("button", { ...vm.attrs, ref: vm.ref, type: vm.type ?? 'button', disabled: vm.disabled, "aria-busy": vm.pending, "data-jini-variant": vm.variant, onClick: vm.onClick, children: vm.children }));
+});
+const NativeTextField = forwardRef(function NativeTextField(props, ref) {
+    const vm = useNativeTextField({ ...props, ref });
+    return (_jsxs("label", { htmlFor: vm.id, children: [vm.label, _jsx("input", { ...vm.attrs, id: vm.id, ref: vm.ref, type: vm.type ?? 'text', value: vm.value, disabled: vm.disabled, onChange: vm.onChange })] }));
+});
+const NativeDialog = forwardRef(function NativeDialog(props, ref) {
+    const vm = useNativeDialog({ ...props, ref });
+    return (_jsxs("dialog", { ...vm.attrs, ref: vm.dialogRef, tabIndex: -1, "aria-labelledby": vm.titleId, "aria-busy": vm.pending, onCancel: vm.onCancel, onClick: vm.onClick, children: [_jsx("h2", { id: vm.titleId, children: vm.title }), vm.children] }));
+});
+export const nativeKit = Object.freeze({
+    Button: NativeButton,
+    Dialog: NativeDialog,
+    TextField: NativeTextField,
+});
+//# sourceMappingURL=native.js.map

package/dist/react/kit/types.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentType, ReactNode, Ref } from 'react';
+export type KitAttrs = {
+    readonly 'data-jini-part': string;
+    readonly id?: string;
+} & Readonly<Partial<Record<`data-${string}` | `aria-${string}`, string | number | boolean>>>;
+export interface ButtonProps {
+    readonly attrs: KitAttrs;
+    readonly children: ReactNode;
+    readonly onPress?: () => void;
+    readonly disabled?: boolean;
+    readonly pending?: boolean;
+    readonly variant?: 'primary' | 'secondary' | 'danger';
+    readonly type?: 'button' | 'submit';
+    readonly ref?: Ref<HTMLButtonElement>;
+}
+export interface TextFieldProps {
+    readonly attrs: KitAttrs;
+    readonly label: string;
+    readonly value: string;
+    readonly onValueChange: (value: string) => void;
+    readonly disabled?: boolean;
+    readonly type?: 'text' | 'password' | 'search';
+    readonly ref?: Ref<HTMLInputElement>;
+}
+export interface DialogProps {
+    readonly attrs: KitAttrs;
+    readonly title: string;
+    readonly open: boolean;
+    readonly children: ReactNode;
+    readonly onClose: () => void;
+    readonly pending?: boolean;
+    readonly ref?: Ref<HTMLDialogElement>;
+}
+export interface ReactAdminKit {
+    readonly Button: ComponentType<ButtonProps>;
+    readonly Dialog: ComponentType<DialogProps>;
+    readonly TextField: ComponentType<TextFieldProps>;
+}
+export declare const KIT_CONTRACT_VERSION = "1.0.0";
+//# sourceMappingURL=types.d.ts.map

package/dist/react/kit/types.js

@@ -0,0 +1,2 @@
+export const KIT_CONTRACT_VERSION = '1.0.0';
+//# sourceMappingURL=types.js.map

package/dist/react/overlay.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+export interface OverlayEntry {
+    readonly id: number;
+    readonly render: () => ReactNode;
+}
+export interface OverlayPort {
+    open<T>(required: {
+        render: (required: {
+            resolve: (value: T | null) => void;
+            cancel: () => void;
+        }) => ReactNode;
+    }, optional?: {
+        signal?: AbortSignal;
+    }): Promise<T | null>;
+}
+/** One active overlay per host. A second request rejects instead of stealing the first
+ * caller's promise; abort/dispose settle null and release every event listener. */
+export declare function createOverlayController(_required?: Record<string, never>, _optional?: Record<string, never>): {
+    getSnapshot: () => Readonly<{
+        entries: readonly OverlayEntry[];
+    }>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    open<T>({ render }: {
+        render: (required: {
+            resolve: (value: T | null) => void;
+            cancel: () => void;
+        }) => ReactNode;
+    }, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<T | null>;
+    cancel(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=overlay.d.ts.map

package/dist/react/overlay.js

@@ -0,0 +1,35 @@
+import { createControllerStore } from '../core/module/controller-store.js';
+/** One active overlay per host. A second request rejects instead of stealing the first
+ * caller's promise; abort/dispose settle null and release every event listener. */
+export function createOverlayController(_required = {}, _optional = {}) {
+    const store = createControllerStore({ initial: { entries: [] } });
+    let sequence = 0, cancelActive = null;
+    return {
+        getSnapshot: store.getSnapshot, subscribe: store.subscribe,
+        open({ render }, { signal } = {}) {
+            if (store.signal.aborted || signal?.aborted)
+                return Promise.resolve(null);
+            if (cancelActive)
+                return Promise.reject(new Error('An overlay is already open'));
+            return new Promise(resolve => {
+                let settled = false;
+                const finish = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    signal?.removeEventListener('abort', cancel);
+                    cancelActive = null;
+                    store.set({ patch: { entries: [] } });
+                    resolve(value);
+                };
+                const cancel = () => finish(null);
+                cancelActive = cancel;
+                signal?.addEventListener('abort', cancel, { once: true });
+                store.set({ patch: { entries: [{ id: ++sequence, render: () => render({ resolve: finish, cancel }) }] } });
+            });
+        },
+        cancel(_required = {}, _optional = {}) { cancelActive?.(); },
+        dispose(_required = {}, _optional = {}) { cancelActive?.(); store.dispose(); },
+    };
+}
+//# sourceMappingURL=overlay.js.map

package/dist/react/overlays.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+export interface OverlayEntry {
+    readonly id: number;
+    readonly render: () => ReactNode;
+}
+export interface OverlayPort {
+    open<T>(required: {
+        render: (required: {
+            resolve: (value: T | null) => void;
+            cancel: () => void;
+        }) => ReactNode;
+    }, optional?: {
+        signal?: AbortSignal;
+    }): Promise<T | null>;
+}
+/** One active overlay per host. A second request rejects instead of stealing the first
+ * caller's promise; abort/dispose settle null and release every event listener. */
+export declare function createOverlayController(_required?: Record<string, never>, _optional?: Record<string, never>): {
+    getSnapshot: () => Readonly<{
+        entries: readonly OverlayEntry[];
+    }>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    open<T>({ render, }: {
+        render: (required: {
+            resolve: (value: T | null) => void;
+            cancel: () => void;
+        }) => ReactNode;
+    }, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<T | null>;
+    cancel(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+export { OverlayHost } from './OverlayHost.js';
+export type { OverlayHostProps } from './OverlayHost.hooks.js';
+//# sourceMappingURL=overlays.d.ts.map

package/dist/react/overlays.js

@@ -0,0 +1,46 @@
+import { createControllerStore } from '../core/module/controller-store.js';
+/** One active overlay per host. A second request rejects instead of stealing the first
+ * caller's promise; abort/dispose settle null and release every event listener. */
+export function createOverlayController(_required = {}, _optional = {}) {
+    const store = createControllerStore({ initial: { entries: [] } });
+    let sequence = 0, cancelActive = null;
+    return {
+        getSnapshot: store.getSnapshot,
+        subscribe: store.subscribe,
+        open({ render, }, { signal } = {}) {
+            if (store.signal.aborted || signal?.aborted)
+                return Promise.resolve(null);
+            if (cancelActive)
+                return Promise.reject(new Error('An overlay is already open'));
+            return new Promise((resolve) => {
+                let settled = false;
+                const finish = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    signal?.removeEventListener('abort', cancel);
+                    cancelActive = null;
+                    store.set({ patch: { entries: [] } });
+                    resolve(value);
+                };
+                const cancel = () => finish(null);
+                cancelActive = cancel;
+                signal?.addEventListener('abort', cancel, { once: true });
+                store.set({
+                    patch: {
+                        entries: [{ id: ++sequence, render: () => render({ resolve: finish, cancel }) }],
+                    },
+                });
+            });
+        },
+        cancel(_required = {}, _optional = {}) {
+            cancelActive?.();
+        },
+        dispose(_required = {}, _optional = {}) {
+            cancelActive?.();
+            store.dispose();
+        },
+    };
+}
+export { OverlayHost } from './OverlayHost.js';
+//# sourceMappingURL=overlays.js.map

package/dist/react/shell/AdminShell.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import type { AdminShellProps } from './types.js';
+/**
+ * A host-composed admin layout with manifest navigation and a session gate.
+ * @param props Required host scope, ports, contributions, labels and slots; optional layout settings.
+ * @returns Loading/login/error UI or the authenticated sidebar, feature screen and pane slots.
+ */
+export declare function AdminShell(props: AdminShellProps): ReactNode;
+//# sourceMappingURL=AdminShell.d.ts.map

package/dist/react/shell/AdminShell.hooks.d.ts

@@ -0,0 +1,15 @@
+import { type Dispatch, type SetStateAction } from 'react';
+import type { AdminShellNavigationPort } from './types.js';
+/** Internal shell wiring: a route snapshot and host-installed SPA link interception. */
+export declare function useShellRoute(args: {
+    readonly navigation: AdminShellNavigationPort;
+    readonly base: string;
+}): string;
+/** Mobile overlay state, independent of the Sidebar's persisted desktop rail state. */
+export declare function useShellDrawer(args: {
+    readonly routePath: string;
+}): {
+    readonly open: boolean;
+    readonly setOpen: Dispatch<SetStateAction<boolean>>;
+};
+//# sourceMappingURL=AdminShell.hooks.d.ts.map

package/dist/react/shell/AdminShell.hooks.js

@@ -0,0 +1,27 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+/** Internal shell wiring: a route snapshot and host-installed SPA link interception. */
+export function useShellRoute(args) {
+    const { navigation, base } = args;
+    const subscribe = useCallback((onChange) => navigation.subscribe({ base, onChange }), [navigation, base]);
+    const read = useCallback(() => navigation.readRoute({ base }), [navigation, base]);
+    const routePath = useSyncExternalStore(subscribe, read, read);
+    useEffect(() => navigation.installLinkInterceptor({ base }), [navigation, base]);
+    return routePath;
+}
+/** Mobile overlay state, independent of the Sidebar's persisted desktop rail state. */
+export function useShellDrawer(args) {
+    const [open, setOpen] = useState(false);
+    useEffect(() => setOpen(false), [args.routePath]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape')
+                setOpen(false);
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [open]);
+    return { open, setOpen };
+}
+//# sourceMappingURL=AdminShell.hooks.js.map