@almadar/shell-web 0.0.0-stage → 0.1.0

package/dist/providers/index.d.ts

@@ -0,0 +1,340 @@
+import React__default, { ReactNode } from 'react';
+import { EntityRow, EventPayload, EffectTrace, PageAccess, ViewerAuthority, RowSetRef } from '@almadar/core';
+export { ANONYMOUS_USER } from '@almadar/core';
+import '../EventBusProvider-CVwjkV_2.js';
+import { UIThemeDefinition } from '../core.js';
+import { b as UserData } from '../UserContext-DqWeZkUZ.js';
+export { U as UserContext, a as UserContextValue, c as UserProvider, d as UserProviderProps, u as useHasPermission, e as useHasRole, f as useUser, g as useUserForEvaluation } from '../UserContext-DqWeZkUZ.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, r as resetArbitraryClassStyles, u as useArbitraryClassStyles, g as useCurrentPagePath, h as useDesignTheme } from '../ArbitraryClassCompiler-Mzabq-UB.js';
+export { n as AwaitingSkeletonContext, A as AwaitingSkeletonSource, o as EntityBindingContext, E as EntityBindingSource, a as EntitySchemaContextValue, b as EntitySchemaProvider, c as EntitySchemaProviderProps, d as ServerBridgeContextValue, e as ServerBridgeProvider, p as ServerBridgeProviderProps, S as ServerBridgeTransport, T as TraitContext, f as TraitContextValue, g as TraitInstance, h as TraitProvider, i as TraitProviderProps, q as useAwaitingSkeleton, r as useEntityBindingSnapshot, u as useEntitySchema, j as useEntitySchemaOptional, k as useServerBridge, l as useTrait, m as useTraitContext } from '../ServerBridge-Cm1On51b.js';
+export { a as KernelEngineContext, b as KernelEngineProvider, c as KernelEngineProviderProps, K as KernelEngineValue, d as KernelLoaderMissingError, L as LanguageLoaderMissingError, S as SeedProgramLoaderMissingError, u as useKernelEngine } from '../KernelEngineContext-BOCQoFwk.js';
+export { b as KernelInstance, a as KernelLoader, K as KernelModule, L as LanguageLoader, S as SeedProgramLoader } from '../kernel-wire-B4S8pnP3.js';
+import '../verificationRegistry-CabxhfTv.js';
+export { G as GameAudioContext, a as GameAudioContextValue, b as GameAudioProvider, c as GameAudioProviderProps, u as useGameAudioContext, d as useGameAudioContextOptional } from '../GameAudioProvider-Cm9BnvmP.js';
+export { A as Avl3DConfig, a as Avl3DContext, b as Avl3DModelOverrides, u as useAvl3DConfig, c as useAvl3DPalette } from '../avl-3d-context-BIRKWpaL.js';
+export { AccessTokenProvider } from '@almadar/shell-runtime/client/EventTransport';
+import '../verification-C5pTeMJv.js';
+import '@almadar/shell-runtime/kernel/wire';
+import '../paintDispatch-ChW5mVuK.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;
+
+/**
+ * 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
+ * - UserProvider - the viewer `@user.x` bindings resolve against
+ *
+ * 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;
+    /**
+     * The signed-in viewer. Generated trait hooks read `@user.x` through
+     * `useUser()`, so without this every role gate takes its negative branch and
+     * every ownership-scoped list renders empty — silently, since `useUser()`
+     * falls back to anonymous rather than throwing
+     * (U-USERPROVIDER-MOUNTED-NOWHERE). Mounting the provider here means every
+     * host that already wraps its app in OrbitalProvider only has to pass the user.
+     */
+    user?: UserData | null;
+}
+/**
+ * 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, user, }: 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. Public and undeclared pages pass
+ * straight through — no auth wait, no gate.
+ *
+ * @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;
+}
+
+interface RowSetResolution {
+    rows: EntityRow[];
+    total: number;
+    /** No answer yet for the current data (first resolve, or a refresh in flight). */
+    loading: boolean;
+}
+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 { OrbitalProvider, PageAccessHost, RenderSlotProvider, RowSetResolverProvider, SelectionContext, SelectionProvider, UserData, VerificationProvider, mapServerEffectResults, useRenderSlot, useRowSetResolver, useRowSetResolverHandle, useSelection, useSelectionOptional };
+export type { OrbitalProviderProps, PageAccessHostProps, RenderSlotProviderProps, SelectionContextType, VerificationProviderProps };

package/dist/providers/index.js

@@ -0,0 +1,30 @@
+export { TraitContext, TraitProvider, useTrait, useTraitContext } from '../chunk-ZO6MXAS3.js';
+export { Avl3DContext, useAvl3DConfig, useAvl3DPalette } from '../chunk-EOWMARUB.js';
+export { AwaitingSkeletonContext, EntityBindingContext, EntitySchemaProvider, GameAudioContext, GameAudioProvider, KernelEngineContext, KernelEngineProvider, KernelLoaderMissingError, LanguageLoaderMissingError, OrbitalProvider, PageAccessHost, RenderSlotProvider, RowSetResolverProvider, SeedProgramLoaderMissingError, SelectionContext, SelectionProvider, ServerBridgeProvider, VerificationProvider, mapServerEffectResults, useAwaitingSkeleton, useEntityBindingSnapshot, useEntitySchema, useEntitySchemaOptional, useGameAudioContext, useGameAudioContextOptional, useKernelEngine, useRenderSlot, useRowSetResolver, useRowSetResolverHandle, useSelection, useSelectionOptional, useServerBridge } from '../chunk-GYTPOFVC.js';
+import '../chunk-YDNJLLG6.js';
+import '../chunk-KVQS4GXU.js';
+import '../chunk-L677XGY3.js';
+import '../chunk-FP3WIKTC.js';
+import '../chunk-42FY4RYA.js';
+import '../chunk-FAJDTHWC.js';
+import '../chunk-GAR5TQ5B.js';
+import '../chunk-SJGJJKBY.js';
+import '../chunk-DZ42OJQC.js';
+import '../chunk-P4LNHAFI.js';
+import '../chunk-TZZBINQY.js';
+import '../chunk-PC7K4SK7.js';
+import '../chunk-VFF5OO47.js';
+import '../chunk-DFNZUYX4.js';
+import '../chunk-B4BU77LT.js';
+import '../chunk-6P3MWXYE.js';
+import '../chunk-DYEKAA4L.js';
+import '../chunk-R5O5AUPI.js';
+import '../chunk-L2DEKY4J.js';
+export { DesignThemeProvider, useDesignTheme } from '../chunk-EQAMU2ZC.js';
+export { ANONYMOUS_USER, ARBITRARY_CLASS_STYLE_ID, ArbitraryClassCompilerProvider, CurrentPagePathContext, CurrentPagePathProvider, OrbitalThemeProvider, UserContext, UserProvider, resetArbitraryClassStyles, useArbitraryClassStyles, useCurrentPagePath, useHasPermission, useHasRole, useUser, useUserForEvaluation } from '../chunk-AILY3XPS.js';
+import '../chunk-3BBUBJFF.js';
+import '../chunk-YHMRX6YA.js';
+import '../chunk-MBQAMMSE.js';
+import '../chunk-A2LR6VQQ.js';
+import '../chunk-P4ZFUQFF.js';
+import '../chunk-G7DCAZ22.js';