@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/providers/index.d.ts

@@ -0,0 +1,355 @@
+import React__default, { ReactNode } from 'react';
+import { EntityRow, EventPayload, EffectTrace, PageAccess, ViewerAuthority, RowSetRef } from '@almadar/core';
+export { ANONYMOUS_USER } from '@almadar/core';
+import '../EventBusProvider-BFFHfN4O.js';
+import { UIThemeDefinition } from '../core.js';
+export { A as ARBITRARY_CLASS_STYLE_ID, a as ArbitraryClassCompiler, b as ArbitraryClassCompilerProvider, c as ArbitraryClassCompilerProviderProps, C as CurrentPagePathContext, d as CurrentPagePathProvider, e as CurrentPagePathProviderProps, D as DesignThemeProvider, O as OrbitalThemeProvider, f as OrbitalThemeProviderProps, U as UserContext, g as UserContextValue, h as UserData, i as UserProvider, j as UserProviderProps, r as resetArbitraryClassStyles, u as useArbitraryClassStyles, k as useCurrentPagePath, l as useDesignTheme, m as useHasPermission, n as useHasRole, o as useUser, p as useUserForEvaluation } from '../ArbitraryClassCompiler-CO_iASBn.js';
+export { h as AwaitingSkeletonContext, A as AwaitingSkeletonSource, i as EntityBindingContext, E as EntityBindingSource, a as EntitySchemaContextValue, b as EntitySchemaProvider, c as EntitySchemaProviderProps, d as ServerBridgeContextValue, e as ServerBridgeProvider, j as ServerBridgeProviderProps, S as ServerBridgeTransport, k as useAwaitingSkeleton, l as useEntityBindingSnapshot, u as useEntitySchema, f as useEntitySchemaOptional, g as useServerBridge } from '../ServerBridge-Bqsj-lOU.js';
+export { a as KernelEngineContext, b as KernelEngineProvider, c as KernelEngineProviderProps, K as KernelEngineValue, d as KernelLoaderMissingError, u as useKernelEngine } from '../KernelEngineContext-CcxGYtlr.js';
+export { b as KernelInstance, a as KernelLoader, K as KernelModule } from '../kernel-wire-wNdAPfhJ.js';
+import '../verificationRegistry-CVrcxG1s.js';
+export { G as GameAudioContext, a as GameAudioContextValue, b as GameAudioProvider, c as GameAudioProviderProps, u as useGameAudioContext, d as useGameAudioContextOptional } from '../GameAudioProvider-ceM_n0ey.js';
+export { A as Avl3DConfig, a as Avl3DContext, b as Avl3DModelOverrides, u as useAvl3DConfig, c as useAvl3DPalette } from '../avl-3d-context-BycmO6tG.js';
+export { AccessTokenProvider } from '@almadar/shell-runtime/client/EventTransport';
+import '../verification-C5pTeMJv.js';
+import '@almadar/shell-runtime/kernel/os-port';
+import '@almadar/shell-browser/kv';
+import '../paintDispatch-CuJLsr9Y.js';
+import '../fx-CmQjnHmT.js';
+import 'lucide-react';
+import 'three';
+
+/**
+ * SelectionProvider - Manages selected entity state
+ *
+ * Separates selection state from the EventBusProvider to maintain
+ * clean architecture (event bus stays pure pub/sub).
+ *
+ * This provider:
+ * - Listens to UI:VIEW and UI:SELECT events to track selected entity
+ * - Listens to UI:CLOSE, UI:DESELECT, UI:CANCEL to clear selection
+ * - Provides the selected entity to any component that needs it
+ *
+ * @packageDocumentation
+ */
+
+interface SelectionContextType<T = EntityRow> {
+    /** The currently selected entity */
+    selected: T | null;
+    /** Manually set the selected entity */
+    setSelected: (entity: T | null) => void;
+    /** Clear the selection */
+    clearSelection: () => void;
+    /** Check if an entity is selected */
+    isSelected: (entity: T) => boolean;
+}
+declare const SelectionContext: React__default.Context<SelectionContextType<EntityRow> | null>;
+interface SelectionProviderProps {
+    children: ReactNode;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom comparison function for isSelected */
+    compareEntities?: (a: EntityRow, b: EntityRow) => boolean;
+}
+/**
+ * Provider component for selection state.
+ *
+ * Must be used within an EventBusProvider.
+ *
+ * @example
+ * ```tsx
+ * function OrderListPage() {
+ *   return (
+ *     <EventBusProvider>
+ *       <SelectionProvider debug={process.env.NODE_ENV === 'development'}>
+ *         <OrderTable />
+ *         <OrderDetailDrawer />
+ *       </SelectionProvider>
+ *     </EventBusProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SelectionProvider({ children, debug, compareEntities, }: SelectionProviderProps): React__default.JSX.Element;
+/**
+ * Hook to access selection state.
+ *
+ * @throws Error if used outside SelectionProvider
+ *
+ * @example
+ * ```tsx
+ * function OrderDetailDrawer() {
+ *   const { selected, clearSelection } = useSelection<Order>();
+ *
+ *   if (!selected) return null;
+ *
+ *   return (
+ *     <Drawer onClose={clearSelection}>
+ *       <OrderDetail order={selected} />
+ *     </Drawer>
+ *   );
+ * }
+ * ```
+ */
+declare function useSelection<T = EntityRow>(): SelectionContextType<T>;
+/**
+ * Hook to access selection state with fallback for components
+ * that may be used outside SelectionProvider.
+ *
+ * Returns null if no SelectionProvider is found.
+ */
+declare function useSelectionOptional<T = EntityRow>(): SelectionContextType<T> | null;
+
+/**
+ * EditorFocusContext — which editor holds keyboard focus, as React context. A focusable editor (CodeBlock) reports its own
+ * focus and blur here; the keyboard router reads it to pick the capture-table entry a keydown belongs to.
+ */
+
+interface EditorFocus {
+    /** The editor holding focus, or `null` when none does. */
+    focused: () => string | null;
+    focus: (editorId: string) => void;
+    /** Releases focus only when `editorId` still holds it, so a late blur never clears a newer focus. */
+    blur: (editorId: string) => void;
+}
+declare const EditorFocusProvider: React__default.FC<{
+    children: React__default.ReactNode;
+}>;
+/** Outside an `EditorFocusProvider` nothing is ever focused: the router targets `'shell'`. */
+declare function useEditorFocus(): EditorFocus;
+
+/**
+ * OrbitalProvider
+ *
+ * Unified provider that combines all required contexts for Orbital applications.
+ * Provides a single import for both Builder preview and compiled shell.
+ *
+ * Combines:
+ * - ThemeProvider - Theme and color mode management
+ * - EventBusProvider - Page-scoped event pub/sub
+ * - SelectionProvider - Selected entity tracking
+ *
+ * Entity data flows through props (via enrichFromResponse in ServerBridge),
+ * not through context. FetchedDataProvider has been removed.
+ *
+ * @packageDocumentation
+ */
+
+interface OrbitalProviderProps {
+    children: ReactNode;
+    /** Custom themes (merged with built-in themes) */
+    themes?: UIThemeDefinition[];
+    /** Default theme name */
+    defaultTheme?: string;
+    /** Default color mode */
+    defaultMode?: 'light' | 'dark' | 'system';
+    /** Optional target element ref for scoped theme application */
+    targetRef?: React__default.RefObject<HTMLElement>;
+    /** Skip ThemeProvider (use when already inside a themed container like shadow DOM) */
+    skipTheme?: boolean;
+    /** Enable debug logging for all providers */
+    debug?: boolean;
+    /** Initial fetched data */
+    /** @deprecated No longer used. Entity data flows through server response props. */
+    initialData?: Record<string, EntityRow[]>;
+    /**
+     * Enable Suspense mode. When true, UISlotRenderer wraps each slot in
+     * `<ErrorBoundary><Suspense>` with Skeleton fallbacks.
+     * Opt-in — existing isLoading prop pattern still works when false/absent.
+     */
+    suspense?: boolean;
+    /**
+     * Enable verification wiring for visual testing.
+     * When true, lifecycle events are recorded and exposed via
+     * `window.__orbitalVerification` for Playwright/automation.
+     * Default: true in development, false in production.
+     */
+    verification?: boolean;
+    /**
+     * Sandbox mode: the event bus stays context-local and does NOT register as
+     * the global bus. Set for studio previews embedded in a host app (so the
+     * preview's events don't clobber the host's global bus). Default false.
+     */
+    isolated?: boolean;
+}
+/**
+ * OrbitalProvider - Unified context provider for Orbital applications
+ *
+ * Wraps your application with all required providers in the correct order.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function App() {
+ *   return (
+ *     <OrbitalProvider>
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ *
+ * // With configuration
+ * function App() {
+ *   return (
+ *     <OrbitalProvider
+ *       defaultTheme="minimalist"
+ *       defaultMode="dark"
+ *       debug={process.env.NODE_ENV === 'development'}
+ *     >
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ *
+ * // With custom themes from schema
+ * import { THEMES } from './generated/theme-manifest';
+ *
+ * function App() {
+ *   return (
+ *     <OrbitalProvider themes={THEMES} defaultTheme="glass">
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function OrbitalProvider({ children, themes, defaultTheme, defaultMode, targetRef, skipTheme, debug, initialData, suspense, verification, isolated, }: OrbitalProviderProps): React__default.ReactElement;
+declare namespace OrbitalProvider {
+    var displayName: string;
+}
+
+/**
+ * RenderSlotContext — which UI slot the current subtree is rendering into.
+ *
+ * Default is 'main': a compiled app's page body renders patterns directly
+ * (no UISlotRenderer), so the absence of a provider IS the main slot. The
+ * exceptional hosts declare themselves: the runtime path's UISlotComponent
+ * provides its slot name per subtree; the compiled path's ModalSlot /
+ * DrawerSlot provide 'modal' / 'drawer'.
+ *
+ * Consumers gate slot-sensitive behavior on it — e.g. DetailPanel only
+ * feeds the loaded record's title into the nav-stack crumb from the routed
+ * 'main' slot (a modal or drawer must not relabel the page's crumb).
+ */
+
+interface RenderSlotProviderProps {
+    slot: string;
+    children: React__default.ReactNode;
+}
+declare const RenderSlotProvider: React__default.FC<RenderSlotProviderProps>;
+/** The slot name the calling component is rendering inside ('main' by default). */
+declare function useRenderSlot(): string;
+
+/**
+ * VerificationProvider
+ *
+ * Wires the verification registry to the event bus: intercepts the lifecycle events
+ * (`{traitName}:DISPATCH`, `{traitName}:{event}:SUCCESS`, `{traitName}:{event}:ERROR`) and records
+ * transitions via `recordTransition()`, then calls `bindEventBus()` and `bindTraitStateGetter()` to populate
+ * `window.__orbitalVerification` for Playwright/automation.
+ *
+ * @packageDocumentation
+ */
+
+interface VerificationProviderProps {
+    children: ReactNode;
+    /** Enable verification wiring (default: true in dev, false in prod) */
+    enabled?: boolean;
+    /** Optional trait state getter for compiled apps (maps traitName → currentState) */
+    traitStateGetter?: (traitName: string) => string | undefined;
+}
+/**
+ * Map the compiled path's raw `effectResults` bus payload (persist / fetch /
+ * call-service outcomes forwarded from the server) onto `EffectTrace[]`.
+ * Exported for unit testing — pure, no React/event-bus dependency.
+ *
+ * The server's `EffectResult` (`OrbitalServerRuntime.ts`) writes
+ * `entityType` — not `entity` — plus `action` / `data.id` / `success` /
+ * `denied`; reading only `er['entity']` (never populated) dropped all of
+ * that, so a denied or failed persist read back here as a plain 'executed'
+ * effect with no entity name.
+ */
+declare function mapServerEffectResults(effectResults: ReadonlyArray<EventPayload>): EffectTrace[];
+/**
+ * VerificationProvider — wires the verification registry to the event bus. Renders children unchanged.
+ */
+declare function VerificationProvider({ children, enabled, traitStateGetter, }: VerificationProviderProps): React__default.ReactElement;
+declare namespace VerificationProvider {
+    var displayName: string;
+}
+
+/**
+ * The page's declared `access`, enforced at the page boundary on both
+ * execution paths: an `access: authenticated` page's subtree (its whole trait
+ * circuit) mounts only once the host's auth provider has resolved an
+ * authenticated viewer, and is keyed by that viewer so a different user never
+ * inherits the previous user's circuit. Any other resolved authority sends the
+ * viewer to the app's declared `signIn` route. An `access: public` page mounts at
+ * once, whatever the authority. A page that declares no access mounts once the
+ * stored sign-in has settled, never anonymously while it restores.
+ *
+ * @packageDocumentation
+ */
+
+interface PageAccessHostProps {
+    /** The page's declared `access:` modifier; absent = no gate. */
+    access?: PageAccess;
+    /** What the host's auth provider has resolved the viewer to be. */
+    authority: ViewerAuthority;
+    /** The admitted viewer's identity; a change remounts the page subtree. */
+    viewerId?: string;
+    /** The app's `signIn:` route. */
+    signIn?: string;
+    /** The concrete path being opened — handed to `onDenied` as the return path. */
+    path: string;
+    /** Navigate a non-admitted viewer to `signIn`, carrying `returnTo`. */
+    onDenied: (signIn: string, returnTo: string) => void;
+    children: React__default.ReactNode;
+}
+declare function PageAccessHost({ access, authority, viewerId, signIn, path, onDenied, children, }: PageAccessHostProps): React__default.ReactElement | null;
+declare namespace PageAccessHost {
+    var displayName: string;
+}
+
+/** A row-set reference the kernel could not resolve; distinct from a resolve that answered with zero rows. */
+declare class RowSetResolveError extends Error {
+    readonly entityType: string;
+    constructor(entityType: string, cause: string);
+}
+interface RowSetResolution {
+    rows: EntityRow[];
+    total: number;
+    /** No answer yet for the current data (first resolve, or a refresh in flight). */
+    loading: boolean;
+    /** The resolve failed; `rows` is not an answer. Cleared when a later resolve is in flight. */
+    failure?: RowSetResolveError;
+}
+interface RowSetResolver {
+    resolve(ref: RowSetRef): RowSetResolution;
+    /** A write to `entityType` happened: re-resolve every held ref of that type. */
+    rowsChanged(entityType: string): void;
+    subscribe(listener: () => void): () => void;
+    /** Bumps whenever any resolution changes; render caches key on it. */
+    epoch(): number;
+}
+
+declare function RowSetResolverProvider({ resolver, children }: {
+    resolver: RowSetResolver;
+    children?: ReactNode;
+}): React.ReactElement;
+/** The resolver alone, without subscribing to its epoch: for writers (the repaint signal), not painters. */
+declare function useRowSetResolverHandle(): RowSetResolver | undefined;
+/** The resolver (or undefined) and its epoch; re-renders the caller when any resolution changes. */
+declare function useRowSetResolver(): {
+    resolver: RowSetResolver | undefined;
+    epoch: number;
+};
+
+export { EditorFocusProvider, OrbitalProvider, PageAccessHost, RenderSlotProvider, RowSetResolverProvider, SelectionContext, SelectionProvider, VerificationProvider, mapServerEffectResults, useEditorFocus, useRenderSlot, useRowSetResolver, useRowSetResolverHandle, useSelection, useSelectionOptional };
+export type { EditorFocus, OrbitalProviderProps, PageAccessHostProps, RenderSlotProviderProps, SelectionContextType, VerificationProviderProps };

package/dist/providers/index.js

@@ -0,0 +1,29 @@
+"use client";
+export { Avl3DContext, useAvl3DConfig, useAvl3DPalette } from '../chunk-EOWMARUB.js';
+export { AwaitingSkeletonContext, EntityBindingContext, EntitySchemaProvider, GameAudioContext, GameAudioProvider, KernelEngineContext, KernelEngineProvider, KernelLoaderMissingError, OrbitalProvider, PageAccessHost, RenderSlotProvider, RowSetResolverProvider, SelectionContext, SelectionProvider, ServerBridgeProvider, VerificationProvider, mapServerEffectResults, useAwaitingSkeleton, useEntityBindingSnapshot, useEntitySchema, useEntitySchemaOptional, useGameAudioContext, useGameAudioContextOptional, useKernelEngine, useRenderSlot, useRowSetResolver, useRowSetResolverHandle, useSelection, useSelectionOptional, useServerBridge } from '../chunk-LHP2TK7O.js';
+import '../chunk-57DC34LY.js';
+import '../chunk-SP5CDJ6K.js';
+import '../chunk-CPLN6NBQ.js';
+import '../chunk-HH5KSMH5.js';
+import '../chunk-REXYVBUO.js';
+import '../chunk-AGXD77SL.js';
+import '../chunk-TXAUOLWZ.js';
+import '../chunk-AB3X7QTE.js';
+import '../chunk-DZBQA2OW.js';
+import '../chunk-TUPZWTRE.js';
+import '../chunk-TZZBINQY.js';
+import '../chunk-4T3P43NS.js';
+import '../chunk-PCR37T3U.js';
+import '../chunk-UXLE3IPR.js';
+import '../chunk-ILZ7ORX7.js';
+import '../chunk-3VZ36ZKO.js';
+export { EditorFocusProvider, useEditorFocus } from '../chunk-PRXQGGCO.js';
+import '../chunk-VO2TTLS5.js';
+export { DesignThemeProvider, useDesignTheme } from '../chunk-UTDC2NEA.js';
+export { ANONYMOUS_USER, ARBITRARY_CLASS_STYLE_ID, ArbitraryClassCompilerProvider, CurrentPagePathContext, CurrentPagePathProvider, OrbitalThemeProvider, UserContext, UserProvider, resetArbitraryClassStyles, useArbitraryClassStyles, useCurrentPagePath, useHasPermission, useHasRole, useUser, useUserForEvaluation } from '../chunk-AE7VCQB6.js';
+import '../chunk-3BBUBJFF.js';
+import '../chunk-YHMRX6YA.js';
+import '../chunk-4YXBKHHM.js';
+import '../chunk-A2LR6VQQ.js';
+import '../chunk-P4ZFUQFF.js';
+import '../chunk-G7DCAZ22.js';