@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,239 @@
+import { OrbitalSchema, EventPayload, OrbitalDefinition, SchemaMetadata, PersistenceAdapter, ServiceParams, PatternConfig, ResolvedPatternProps, EventSource, SExpr, EntityData, ViewerAuthority } from '@almadar/core';
+import { TraitState } from '@almadar/shell-runtime/client/trait-types';
+import { EventTransport, AccessTokenProvider } from '@almadar/shell-runtime/client/EventTransport';
+export { AccessTokenProvider } from '@almadar/shell-runtime/client/EventTransport';
+import '../verification-C5pTeMJv.js';
+import { S as ServerBridgeTransport } from '../ServerBridge-Bqsj-lOU.js';
+import { EntityBindingSource, AwaitingSkeletonSource } from '../providers/index.js';
+export { a as EntitySchemaContextValue, b as EntitySchemaProvider, c as EntitySchemaProviderProps, d as ServerBridgeContextValue, e as ServerBridgeProvider, u as useEntitySchema, f as useEntitySchemaOptional, g as useServerBridge } from '../ServerBridge-Bqsj-lOU.js';
+import { useUISlots } from '../context/index.js';
+import { PageCircuit } from '@almadar/core/kernel-wire';
+export { w as wrapCallbackForEvent } from '../wrapCallbackForEvent-B9QLbhxX.js';
+export { a as PERF_NAMESPACE, P as PerfEntry, c as clearPerf, p as perfEnd, b as perfStart, d as perfTime } from '../perf-Dr28-AgT.js';
+import { HostSignInRequest, HostSignInAnswer, HostConsentRequest, HostConsentAnswer } from '@almadar/shell-runtime/kernel/host';
+import React__default from 'react';
+import { SchemaLoader } from '@almadar/shell-runtime';
+import { KernelLoader } from '../providers/index.js';
+export { S as SlotHostManifest, a as SlotHostRegion, b as assertUniqueSlotsPerHost } from '../slot-host-CPzrxLo9.js';
+export { p as profilerOnRender, u as usePerfBuffer } from '../perf-CKiBKbkw.js';
+import '../useUISlots-CiobNFGb.js';
+import '@almadar/core/patterns';
+import '@almadar/shell-browser/kv';
+
+/** A program's type-contract stamp: the kernel refuses to register a program carrying neither field. */
+type ProgramStamp = Pick<OrbitalSchema, 'resolved' | 'typeContractVersion' | 'theme' | 'themes' | 'locales' | 'messages'>;
+/** The kernel's answer for the page: nothing mounts until it is ready. */
+type CircuitState = {
+    status: 'pending';
+} | {
+    status: 'ready';
+    page: PageCircuit;
+} | {
+    status: 'failed';
+    error: Error;
+};
+
+interface TraitStateMachineResult {
+    /** Current state for each trait. */
+    traitStates: Map<string, TraitState>;
+    getTraitState: (traitName: string) => TraitState | undefined;
+    /** Live per-trait binding surface for `EntityBindingContext`. */
+    entityBindingSource: EntityBindingSource;
+    /** Awaiting-server skeletons for `AwaitingSkeletonContext`. */
+    awaitingSkeletonSource: AwaitingSkeletonSource;
+    /** The kernel's answer for the page: pending until it answers, failed when it cannot. Nothing mounts before it is ready. */
+    circuit: CircuitState;
+    /** The theme key the server bound to this session with `theme/set`; `undefined` when none is and the declared themes apply. */
+    sessionTheme: string | undefined;
+}
+interface UseTraitStateMachineOptions {
+    /** The page the kernel answers the circuit of; absent: the initial page (or the page of `routePath`). */
+    page?: string;
+    onEventProcessed?: (eventKey: string, payload?: EventPayload) => void;
+    navigate?: (path: string, params?: Record<string, string>, crumb?: string) => void;
+    navigateBack?: () => void;
+    initPayload?: EventPayload;
+    /** The mounted page's identity; with `initPayload` it keys the once-per-mount lifecycle guard (Runtime Spec Clause 4.1). */
+    mountKey?: string;
+    /** The route the page is opened at; the kernel's mounts for it are what the hook runs (EXEC-ENDPOINT-3). */
+    routePath?: string;
+    /** The program's orbitals: the kernel is built from them. */
+    orbitals: readonly OrbitalDefinition[];
+    /** The program's `_metadata` (a compiled client program's operator sites and dispatch facts), handed to the kernel. */
+    metadata?: SchemaMetadata;
+    /** The program's type-contract stamp, carried into the browser kernel's registration. */
+    stamp?: ProgramStamp;
+    /** Caller-owned transport (server bridge). Omitted + `persistence` set =
+     *  offline preview (plan G7); omitted + no `persistence` = fully local,
+     *  nothing ever posts. */
+    transport?: EventTransport;
+    carriesCircuitState?: boolean;
+    /** Hold every dispatch until the transport's topology is known. */
+    awaitTopology?: boolean;
+    persistence?: PersistenceAdapter;
+    /** The browser store for `[persistent: x, browser]` entities (see `useCircuitKernel`). */
+    browserStore?: PersistenceAdapter;
+    callService?: (service: string, action: string, params?: ServiceParams) => Promise<EventPayload>;
+    debug?: boolean;
+    logContext?: {
+        behavior?: string;
+        orbitalName?: string;
+    };
+}
+declare function useTraitStateMachine(uiSlots: ReturnType<typeof useUISlots>, options: UseTraitStateMachineOptions): TraitStateMachineResult;
+
+/**
+ * One pattern within a slot's accumulated render-ui set, plus any
+ * caller-supplied props that should be merged on top.
+ */
+interface SlotPatternEntry {
+    /** `PatternConfig` normally; a bare `@trait.X` string is the
+     *  G-RUNTIME-025 whole-slot payload (`(render-ui main "@trait.X")`),
+     *  which `useSlotFlush`'s unwrap routes as a TraitFrame child reference. */
+    pattern: PatternConfig | string;
+    props: ResolvedPatternProps;
+}
+/**
+ * The originating trait + state for a slot write. Embedded in the
+ * `useUISlots` SlotContent's metadata so observers (verifier, debugger,
+ * cross-orbital tracer) can attribute every render to the trait that
+ * caused it.
+ */
+interface SlotSource extends EventSource {
+    trait: string;
+    state: string;
+    transition: string;
+    effects: SExpr[];
+}
+
+interface OrbPreviewProps {
+    /**
+     * The orbital schema. Accepts a JSON string or an `OrbitalSchema` object
+     * from `@almadar/core` (the validated `.orb` program type).
+     */
+    schema: string | OrbitalSchema;
+    /**
+     * Mock entity rows keyed by entity name. The `EntityData` type from
+     * `@almadar/core` is `Record<string, EntityRow[]>` where each row is a
+     * `{ id?: string } & Record<string, FieldValue>`.
+     */
+    mockData?: EntityData;
+    /** Preview container height. Default: '400px'. */
+    height?: string;
+    /**
+     * What the preview's slots lay out against. `contained` (default): the host's box, so overlays stay inside it.
+     * `page`: the preview is the host page (a served app), so overlays take the page's fixed layout and the dock pushes
+     * the body.
+     */
+    frame?: 'contained' | 'page';
+    /** CSS class for the outer container. */
+    className?: string;
+    /** Server URL for dual execution (e.g. "/api/orbitals"). When set, events are forwarded to the server. */
+    serverUrl?: string;
+    /**
+     * Custom transport for in-process execution. Mutually exclusive with
+     * `serverUrl`. Used by an in-process host to invoke
+     * `OrbitalServerRuntime.processOrbitalEvent` directly without HTTP.
+     */
+    transport?: ServerBridgeTransport;
+    /** Bearer token for `serverUrl` requests (see `ServerBridgeProviderProps.getAccessToken`). */
+    getAccessToken?: AccessTokenProvider;
+    /**
+     * Loads the initialised `@almadar/kernel`. Given, the preview runs its circuits on the kernel engine and installs the
+     * render evaluator from it (`KernelEngineProvider`); keep the function's identity stable across renders. Absent, the
+     * preview runs under whatever engine the host's own `KernelEngineProvider` selects.
+     */
+    kernelLoader?: KernelLoader;
+    /**
+     * How long (ms) to wait for the server bridge to connect before assuming
+     * it's unreachable and falling back to local-only execution. Default
+     * 5000 (unchanged unless you pass this). Widen it for a caller whose
+     * schema is large enough that the server's first `register()` genuinely
+     * takes longer than 5s (e.g. a 53-orbital organism measured ~14.5s in
+     * production) — see `TraitInitializer`'s `localFallbackTimeoutMs` doc.
+     */
+    localFallbackTimeoutMs?: number;
+    /**
+     * Initial page path to render (e.g. `/deals`). Resolves against the
+     * schema's `pages[]` to seed `currentPage` so the right orbital's traits
+     * mount on first render. Without this the playground falls back to the
+     * schema's first page binding (gap #13 Phase 5). runtime-verify uses this
+     * to walk DealCreate, NoteCompose, etc. on their owning pages.
+     */
+    initialPagePath?: string;
+    /**
+     * What the host's auth provider has resolved the viewer to be. An
+     * `access: authenticated` page mounts only on `authenticated`; any other
+     * resolved value sends the viewer to the app's `signIn` route. Omitted → the
+     * host offers no sign-in (`unavailable`).
+     */
+    authority?: ViewerAuthority;
+    /**
+     * Sandbox mode, for previews embedded in a host app (e.g. the studio
+     * canvas): the event bus stays context-local, navigation stays in memory
+     * (the host URL/history are never touched), in-app links are always
+     * intercepted, and external links open a new tab. Default false
+     * (standalone previews own the global bridge and sync `?page=`).
+     */
+    isolated?: boolean;
+    /**
+     * Scale the rendered content down (never up) so it fits the container
+     * without scrollbars. For fixed-intrinsic-size content (game canvases);
+     * leave off for flow layouts, which should keep their internal scroll.
+     * `'content'`: fit the rendered component itself (not the page around it)
+     * and center it — a thumbnail of one behavior.
+     */
+    fit?: boolean | 'content';
+    /**
+     * Called with the page path on every in-preview page switch (link click,
+     * navigate effect, `navigatesTo`), for a host that tracks the page in its
+     * own router. When set, it replaces the built-in `?page=` URL sync.
+     */
+    onPageChange?: (path: string) => void;
+    /**
+     * A registry theme key (`"<base>-<light|dark>"`) that replaces every
+     * orbital's declared theme — a host's explicit theme pick (the playground
+     * picker). Omitted → each page renders in its own orbital's theme.
+     */
+    themeOverride?: string;
+    /** Hold the preview's client ticks stopped (a canvas card the person has not played); clearing it resumes them. */
+    paused?: boolean;
+    /**
+     * Loads the behavior behind a `lazyPages` entry (`uses lazy`) when its page
+     * is opened. Without it, opening a lazy page shows a load error.
+     */
+    lazyLoader?: SchemaLoader;
+    /** Where `schema` was loaded from — a lazy page's `orbRef` resolves against it. */
+    schemaPath?: string;
+    /**
+     * Called with a path that matches none of this schema's pages — a lazily
+     * loaded behavior hands links back to the schema that imported it.
+     */
+    onUnmatchedNavigate?: (path: string) => void;
+    /**
+     * The host's own sign-in (`HOST_SIGN_IN_ROUTE`, `/login`): navigating there —
+     * including an `access: authenticated` page sending its viewer to
+     * `signIn: "/login"` — calls this with the return path instead of routing to a
+     * page. Omitted → the host offers no sign-in and nothing happens.
+     */
+    onSignIn?: (returnTo?: string) => void;
+    /**
+     * The host's session sign-out, run when the circuit asks `(auth/sign-out)`
+     * (a `host-ask` client effect). Omitted → the host offers no sign-out and the ask is refused by name.
+     */
+    onSignOut?: () => void;
+    /**
+     * The host's own sign-in, run when the circuit asks `(auth/sign-in { method … })` (a `host-ask` client effect whose
+     * answer returns to the asking trait). Omitted → the host offers no sign-in and the ask fails `unavailable`.
+     */
+    onSignInAsk?: (request: HostSignInRequest) => Promise<HostSignInAnswer>;
+    /** Answers `auth/consent` in place of the popup the web host opens: the shell's own authorize window. */
+    onConsentAsk?: (request: HostConsentRequest) => Promise<HostConsentAnswer>;
+}
+declare function OrbPreview({ schema, mockData, height, frame, className, serverUrl, transport, getAccessToken, kernelLoader, initialPagePath, isolated, fit, onPageChange, authority, localFallbackTimeoutMs, themeOverride, paused, lazyLoader, schemaPath, onUnmatchedNavigate, onSignIn, onSignOut, onSignInAsk, onConsentAsk, }: OrbPreviewProps): React__default.ReactElement;
+declare namespace OrbPreview {
+    var displayName: string;
+}
+
+export { OrbPreview, ServerBridgeTransport, useTraitStateMachine };
+export type { OrbPreviewProps, SlotPatternEntry, SlotSource, TraitStateMachineResult, UseTraitStateMachineOptions };

package/dist/runtime/index.js

@@ -0,0 +1,28 @@
+"use client";
+export { assertUniqueSlotsPerHost } from '../chunk-5QTYQTPS.js';
+export { EntitySchemaProvider, OrbPreview, ServerBridgeProvider, useEntitySchema, useEntitySchemaOptional, useServerBridge, useTraitStateMachine } 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';
+export { profilerOnRender, usePerfBuffer } from '../chunk-TUPZWTRE.js';
+import '../chunk-TZZBINQY.js';
+import '../chunk-4T3P43NS.js';
+import '../chunk-PCR37T3U.js';
+import '../chunk-UXLE3IPR.js';
+import '../chunk-ILZ7ORX7.js';
+export { PERF_NAMESPACE, clearPerf, perfEnd, perfStart, perfTime, wrapCallbackForEvent } from '../chunk-3VZ36ZKO.js';
+import '../chunk-PRXQGGCO.js';
+import '../chunk-VO2TTLS5.js';
+import '../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';

package/dist/slot-host-CPzrxLo9.d.ts

@@ -0,0 +1,48 @@
+import { UISlot } from '@almadar/core';
+
+/**
+ * Slot-host manifest types (Studio V4 §14, Part I1/I2).
+ *
+ * A "slot-host" is any shell that lays out named regions and mounts each
+ * one through `UISlotComponent` — e.g. a persona workspace declaring
+ * `sidebar`/`main`/`drawer`/... A manifest is the declarative region → slot
+ * binding for such a host: which compiler `UISlot` each region mounts, and
+ * whether the host's own stock content is replaced by slot content or the
+ * two are shown together (`UISlotComponent`'s `mode` prop). Substrate
+ * (lives in `@almadar/ui`, re-exported by `@almadar/sdk`) so any host — the
+ * studio's three persona shells or an embedding app — describes its
+ * regions the same way.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * One host region's binding to a compiler slot. Mirrors `UISlotComponent`'s
+ * `mode` prop exactly — a manifest is just that prop's value, keyed by
+ * region, declared as data instead of scattered across JSX call sites.
+ */
+interface SlotHostRegion {
+    slot: UISlot;
+    mode: "replace" | "append";
+}
+/**
+ * A host's full region map, keyed by the host's own region ids (e.g. a
+ * persona shell's `activityBar`/`sidebar`/`main`/...). `RegionId` is left
+ * generic so each host supplies its own literal union.
+ */
+interface SlotHostManifest<RegionId extends string = string> {
+    regions: Record<RegionId, SlotHostRegion>;
+}
+/**
+ * Guards the invariant a slot-host manifest depends on: each `UISlot` may
+ * be mounted by at most one region. Two regions sharing a slot would mount
+ * `UISlotComponent` twice for the same slot — the second mount clears/reads
+ * the same context entry the first one owns, so one of the two regions
+ * silently loses its content (or, for a portal slot, double-portals it).
+ * Throws naming the two offending regions so the host can find the
+ * conflict without re-deriving it from the manifest.
+ */
+declare function assertUniqueSlotsPerHost<RegionId extends string>(manifest: SlotHostManifest<RegionId>): void;
+
+export { assertUniqueSlotsPerHost as b };
+export type { SlotHostManifest as S, SlotHostRegion as a };