@almadar/ui 5.79.0 → 5.79.1

package/dist/lib/prepareSchemaForPreview.d.ts

@@ -1,71 +0,0 @@
-/**
- * prepareSchemaForPreview
- *
- * Single source of truth for the "give an Orbital schema a runnable preview"
- * pipeline. Used by both:
- *   * `<OrbPreview autoMock />` (the docs / MDX path)
- *   * `PlaygroundContent` (the interactive playground)
- *
- * Type signature in `@almadar/core` terms:
- *
- *   buildMockData          : OrbitalSchema → EntityData
- *   adjustSchemaForMockData: (OrbitalSchema, EntityData) → OrbitalSchema
- *   prepareSchemaForPreview: OrbitalSchema → { schema: OrbitalSchema, mockData: EntityData }
- *
- * Steps:
- *   1. `buildMockData` — for each orbital, generate (or pick up from
- *     `entity.instances`) `EntityRow[]` for that entity.
- *   2. `adjustSchemaForMockData` — flip two-state INIT machines so the data
- *      state is initial (e.g. `empty -> hasItems` becomes `hasItems` initial).
- *
- * @packageDocumentation
- */
-import type { OrbitalSchema, EntityData } from '@almadar/core';
-/**
- * Build mock entity rows (`EntityData`) for every orbital in the schema.
- *
- * For each orbital's entity:
- *   * If the entity has an `instances` array (from the schema author),
- *     use it as-is.
- *   * Otherwise generate 10 synthetic `EntityRow`s from the field
- *     definitions via `generateEntityRow`.
- *
- * @public
- */
-export declare function buildMockData(schema: OrbitalSchema): EntityData;
-/**
- * When mock data exists for a trait's linked entity, swap the state
- * machine's initial state to the state that also handles INIT (the "data
- * state"). This makes previews land directly in the populated UI.
- *
- * Behavior is per-trait:
- *   * Inline traits with two-state INIT patterns are rewritten.
- *   * String / object trait refs are left untouched (the resolver handles them).
- *   * Single-state INIT machines are left untouched.
- *
- * @public
- */
-export declare function adjustSchemaForMockData(schema: OrbitalSchema, mockData: EntityData): OrbitalSchema;
-/**
- * Result of `prepareSchemaForPreview`.
- *
- * @public
- */
-export interface PreparedPreviewSchema {
-    /** Schema with state machines flipped so data states are initial. */
-    schema: OrbitalSchema;
-    /** Mock entity rows keyed by entity name — pass to `OrbPreview.mockData`. */
-    mockData: EntityData;
-}
-/**
- * Run the full preview prep pipeline on a schema.
- *
- * Accepts either an already-parsed `OrbitalSchema` or a JSON string.
- * Returns `{ schema, mockData }` ready to feed `<OrbPreview>`.
- *
- * Functional signature:
- *   `OrbitalSchema | string → { schema: OrbitalSchema, mockData: EntityData }`
- *
- * @public
- */
-export declare function prepareSchemaForPreview(input: OrbitalSchema | string): PreparedPreviewSchema;

package/dist/lib/slot-definitions.d.ts

@@ -1,33 +0,0 @@
-/**
- * Slot Definitions
- *
- * Defines the available UI slots and their rendering behavior.
- * Slots are either inline (rendered in the component tree) or
- * portal (rendered to document.body via React Portal).
- *
- * @packageDocumentation
- */
-import type { UISlot, SlotDefinition } from '../types/renderer-types';
-/**
- * Definitions for all available UI slots.
- *
- * Inline slots render within the component hierarchy.
- * Portal slots render to document.body, breaking out of overflow containers.
- */
-export declare const SLOT_DEFINITIONS: Partial<Record<UISlot, SlotDefinition>> & Record<'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating', SlotDefinition>;
-/**
- * Get the slot definition for a slot name.
- */
-export declare function getSlotDefinition(slot: UISlot): SlotDefinition | undefined;
-/**
- * Check if a slot is a portal slot.
- */
-export declare function isPortalSlot(slot: string): boolean;
-/**
- * Get all inline slots.
- */
-export declare function getInlineSlots(): UISlot[];
-/**
- * All valid slot names.
- */
-export declare const ALL_SLOTS: UISlot[];

package/dist/lib/themeTokens.d.ts

@@ -1,55 +0,0 @@
-/**
- * themeTokens — runtime mirror of the orbital compiler's theme codegen.
- *
- * The compile path (orbital-rust/crates/orbital-shell-typescript/src/codegen/theme.rs)
- * reads `OrbitalDefinition.theme.tokens` and emits CSS custom-property
- * declarations into a `[data-theme="<name>-<mode>"]` block. The runtime
- * does not parse compiled CSS — it reads the same `tokens` object directly
- * and produces the same `{ '--color-primary': '…', '--radius-md': '…' }` map
- * that the compiler emits.
- *
- * Keeping the two paths byte-identical at the variable level is the contract:
- * editing tokens via the Studio Design System tab must produce the exact
- * same rendered result as editing them in source and running `orbital
- * compile`. The mapping rules here mirror `generate_tokens_css` /
- * `generate_tokens_css_dark` (theme.rs:122–351).
- *
- * Compile vs runtime difference (intentional):
- * - Compile emits the FULL set: schema overrides on top of defaults. This is
- *   needed because the compiled CSS replaces the theme entirely.
- * - Runtime emits ONLY the keys present in `tokens` (and `variants.dark`).
- *   Missing keys cascade from the parent `[data-theme]` rule on the document
- *   element. The provider scopes overrides to an orbital subtree without
- *   shadowing inherited defaults.
- *
- * @packageDocumentation
- */
-import type { ThemeDefinition, ThemeRef, ThemeTokens, ThemeVariant } from '@almadar/core';
-/** Resolved color mode. Mirrors `ThemeContext.resolvedMode`. */
-export type ThemeMode = 'light' | 'dark';
-/**
- * Convert `ThemeTokens` (+ optional dark variant) into a CSS custom-property
- * map keyed by variable name (e.g. `--color-primary`).
- *
- * Mapping rules (mirror theme.rs):
- * - `tokens.colors.<k>`     → `--color-<k>`
- * - `tokens.radii.<k>`      → `--radius-<k>`
- * - `tokens.spacing.<k>`    → `--space-<k>`
- * - `tokens.typography.<k>` → `--<k>` (keys already include their `font-`/
- *                                       `letter-`/`line-` prefix)
- * - `tokens.shadows.<k>`    → `--shadow-<k>` (schema key has no prefix)
- *
- * In `'dark'` mode, the `darkVariant` overrides are merged on top of the
- * base tokens per category — same precedence the Rust compiler uses
- * (`generate_tokens_css_dark`). Categories not present in `darkVariant` fall
- * back to the base tokens.
- */
-export declare function themeTokensToCssVars(tokens: ThemeTokens, mode?: ThemeMode, darkVariant?: ThemeVariant): Record<string, string>;
-/**
- * `ThemeRef` is `ThemeDefinition | string`. When it's a string, it's an
- * unresolved import reference (e.g. `"Ocean.theme"`) that should have been
- * inlined by the compiler's import phase before runtime. If we still see a
- * string here, the upstream resolution path didn't run — return `undefined`
- * rather than guess. `OrbitalThemeProvider` falls through to passthrough.
- */
-export declare function resolveThemeForRuntime(theme: ThemeRef | undefined): ThemeDefinition | undefined;

package/dist/lib/tickRegistry.d.ts

@@ -1,40 +0,0 @@
-/**
- * Tick Registry - Tracks scheduled tick executions for debugging
- *
- * @packageDocumentation
- */
-export interface TickExecution {
-    id: string;
-    traitName: string;
-    /** Tick name (display name) */
-    name: string;
-    /** Tick identifier */
-    tickName: string;
-    interval: number;
-    /** Last execution timestamp */
-    lastRun: number;
-    lastExecuted: number | null;
-    nextExecution: number | null;
-    /** Number of times this tick has run */
-    runCount: number;
-    executionCount: number;
-    /** Average execution time in ms */
-    executionTime: number;
-    /** Whether the tick is currently active */
-    active: boolean;
-    isActive: boolean;
-    /** Guard name if this tick has a guard */
-    guardName?: string;
-    /** Whether the guard passed on last evaluation */
-    guardPassed?: boolean;
-}
-type ChangeListener = () => void;
-export declare function registerTick(tick: TickExecution): void;
-export declare function updateTickExecution(id: string, timestamp: number): void;
-export declare function setTickActive(id: string, isActive: boolean): void;
-export declare function unregisterTick(id: string): void;
-export declare function getAllTicks(): TickExecution[];
-export declare function getTick(id: string): TickExecution | undefined;
-export declare function subscribeToTickChanges(listener: ChangeListener): () => void;
-export declare function clearTicks(): void;
-export {};

package/dist/lib/trait-binding-resolver.d.ts

@@ -1,57 +0,0 @@
-/**
- * Trait-binding resolver for the interpreted runtime path.
- *
- * When a pattern tree contains a string like `"@trait.ItemSearch"` or
- * `"@trait.ItemSearch.main"` inside a `children:` array (or a
- * `node`-typed prop), the `SlotContentRenderer` walker calls this
- * resolver to transform those string leaves into `<TraitFrame>` React
- * elements before rendering.
- *
- * This module only handles the INTERPRETED path — compiled apps bake
- * `<TraitFrame>` into JSX at build time via the TypeScript shell
- * codegen (`orbital-shell-typescript/src/backend.rs`). Both paths land
- * on the same component.
- *
- * Scope:
- *   - string values `"@trait.X[.slot]"` are replaced with
- *     `<TraitFrame traitName="X" slot={...} />`.
- *   - strings that don't match the `@trait.*` shape pass through
- *     verbatim (they may be `@entity.X` bindings resolved elsewhere,
- *     or plain text content).
- *   - recurses into arrays and objects so nested children are covered.
- *
- * @see docs/Almadar_Std_Gaps.md §3.8
- */
-import React from "react";
-import type { FieldValue } from "@almadar/core";
-export interface ResolveTraitBindingsContext {
-    /**
-     * Depth cap — the walker refuses to descend deeper than this to
-     * protect against deeply nested patterns (real or adversarial).
-     * Default 8; roughly matches the deepest layout trees seen in the
-     * std catalog plus head-room.
-     */
-    depth?: number;
-}
-/**
- * Walk a pattern-tree value, returning a structurally-identical tree
- * with `@trait.*` string leaves replaced by `<TraitFrame>` React
- * elements.
- *
- * The walker preserves insertion order of object keys and array
- * positions — it only transforms the narrow subset of string values
- * that match the `@trait.X[.slot]` form. Other strings are copied as-is.
- *
- * Call from `SlotContentRenderer` once per render, pointed at
- * `content.props` with `currentSlot` bound to the slot whose render-ui
- * is being composed.
- */
-type PatternTreeNode = FieldValue | React.ReactElement | undefined;
-export declare function resolveTraitBindingsInPattern(value: PatternTreeNode, ctx: ResolveTraitBindingsContext): PatternTreeNode;
-/**
- * Lower-level helper: is this string a `@trait.*` binding the resolver
- * would handle? Useful for consumers that need to treat the trait case
- * specially before handing the string back to the walker.
- */
-export declare function isTraitBinding(value: PatternTreeNode): value is string;
-export {};

package/dist/lib/traitRegistry.d.ts

@@ -1,34 +0,0 @@
-/**
- * Trait Registry - Tracks active traits and their state machines for debugging
- *
- * @packageDocumentation
- */
-export interface TraitTransition {
-    from: string;
-    to: string;
-    event: string;
-    guard?: string;
-}
-export interface TraitGuard {
-    name: string;
-    lastResult?: boolean;
-}
-export interface TraitDebugInfo {
-    id: string;
-    name: string;
-    currentState: string;
-    states: string[];
-    transitions: TraitTransition[];
-    guards: TraitGuard[];
-    transitionCount: number;
-}
-type ChangeListener = () => void;
-export declare function registerTrait(info: TraitDebugInfo): void;
-export declare function updateTraitState(id: string, newState: string): void;
-export declare function updateGuardResult(traitId: string, guardName: string, result: boolean): void;
-export declare function unregisterTrait(id: string): void;
-export declare function getAllTraits(): TraitDebugInfo[];
-export declare function getTrait(id: string): TraitDebugInfo | undefined;
-export declare function subscribeToTraitChanges(listener: ChangeListener): () => void;
-export declare function clearTraits(): void;
-export {};

package/dist/lib/verificationRegistry.d.ts

@@ -1,91 +0,0 @@
-/**
- * Verification Registry - Tracks runtime verification checks and transition traces
- *
- * Provides:
- * 1. A checklist of pass/fail checks (INIT has fetch, bridge connected, etc.)
- * 2. A full transition timeline with effect execution results
- * 3. ServerBridge health snapshot
- * 4. window.__orbitalVerification for Playwright/automation
- *
- * @packageDocumentation
- */
-import type { AssetLoadStatus, BridgeHealth, BusEvent, CheckStatus, EffectTrace, EventLogEntry, EventPayload, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
-export type { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary, };
-type ChangeListener = () => void;
-/**
- * Per-trait snapshot getter. Each generated trait logic hook (or
- * `useTraitStateMachine` trait binding) registers one on mount so the
- * verifier can read the live reducer state for that trait.
- */
-export type TraitSnapshotGetter = () => TraitStateSnapshot;
-export declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
-export declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
-export declare function getAllChecks(): VerificationCheck[];
-export declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
-export declare function getTransitions(): TransitionTrace[];
-export declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
-/**
- * Record a server response as a timeline entry.
- * Creates a synthetic transition entry with type "server-response" to show
- * what the server returned (clientEffects, data counts, emitted events).
- */
-export declare function recordServerResponse(orbitalName: string, event: string, response: Omit<ServerResponseTrace, "orbitalName" | "timestamp">): void;
-export declare function updateBridgeHealth(health: BridgeHealth): void;
-export declare function getBridgeHealth(): BridgeHealth | null;
-export declare function getSummary(): VerificationSummary;
-export declare function getSnapshot(): VerificationSnapshot;
-/**
- * Per-trait snapshot for the verifier.
- *
- * Iterates every registered trait getter and collects the live reducer
- * state. Empty until at least one trait hook calls `registerTraitSnapshot`.
- * A getter that throws is logged and skipped — one broken trait must not
- * poison the rest of the snapshot.
- */
-export declare function getTraitSnapshots(): TraitStateSnapshot[];
-export declare function subscribeToVerification(listener: ChangeListener): () => void;
-declare global {
-    interface Window {
-        __orbitalVerification?: OrbitalVerificationAPI;
-    }
-}
-/**
- * Wait for a transition matching the given event to appear.
- * Returns the trace or null on timeout.
- */
-export declare function waitForTransition(event: string, timeoutMs?: number): Promise<TransitionTrace | null>;
-/**
- * Bind the EventBus so automation can send events and log emissions.
- * Call this during app initialization.
- */
-export declare function bindEventBus(eventBus: {
-    emit: (type: string, payload?: EventPayload) => void;
-    onAny?: (listener: (event: BusEvent) => void) => () => void;
-}): void;
-/**
- * Bind a trait state getter so automation can query current states.
- */
-export declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
-/**
- * Register a per-trait snapshot provider. The generated trait logic hook
- * (or `useTraitStateMachine`) calls this once on mount, passing a getter
- * that reads the current reducer state via a ref. Returns an unregister
- * function for cleanup on unmount.
- *
- * Calling this twice for the same `traitName` replaces the previous
- * getter (e.g. page navigation remounts the trait; the new registration
- * wins).
- */
-export declare function registerTraitSnapshot(traitName: string, getter: TraitSnapshotGetter): () => void;
-/**
- * Register a canvas frame capture function.
- * Called by game organisms (IsometricCanvas, PlatformerCanvas, SimulationCanvas)
- * so the verifier can snapshot canvas content at checkpoints.
- */
-export declare function bindCanvasCapture(captureFn: () => string | null): void;
-/**
- * Update asset load status for canvas verification.
- * Game organisms call this when images load or fail.
- */
-export declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
-export declare function clearVerification(): void;

package/dist/lib/visualizer/browser.d.ts

@@ -1,48 +0,0 @@
-/**
- * Browser entry point for the Orbital Visualizer
- *
- * This file is bundled by esbuild to create a standalone browser script.
- * It exports the visualizer to the global `OrbitalVisualizer` object.
- */
-import { renderStateMachineToSvg, extractStateMachine, getEffectSummary, extractOutputsFromTransitions, type RenderOptions, type VisualizerConfig } from './index.js';
-import type { OrbitalSchema } from '@almadar/core';
-type SExpr = string | number | boolean | SExpr[];
-declare function formatSExprHumanReadable(expr: SExpr, indent?: number): string;
-interface BrowserRenderOptions extends RenderOptions {
-    config?: Partial<VisualizerConfig>;
-}
-/**
- * Render a state machine into a container element
- */
-declare function render(container: HTMLElement, data: OrbitalSchema | object, options?: BrowserRenderOptions): void;
-/**
- * Auto-initialize diagrams from data attributes
- */
-declare function init(): void;
-declare let pinnedTooltip: {
-    element: HTMLElement;
-    bundleId: string;
-} | null;
-/**
- * Render a state machine into a container element using DOM-based approach
- * This matches the React DomStateMachineVisualizer component
- */
-declare function renderDom(container: HTMLElement, data: OrbitalSchema | object, options?: BrowserRenderOptions): void;
-declare const OrbitalVisualizer: {
-    render: typeof render;
-    renderDom: typeof renderDom;
-    init: typeof init;
-    renderToSvg: typeof renderStateMachineToSvg;
-    extractStateMachine: typeof extractStateMachine;
-    getEffectSummary: typeof getEffectSummary;
-    extractOutputsFromTransitions: typeof extractOutputsFromTransitions;
-    formatSExprHumanReadable: typeof formatSExprHumanReadable;
-    CONFIG: VisualizerConfig;
-};
-declare global {
-    interface Window {
-        OrbitalVisualizer: typeof OrbitalVisualizer;
-        _pinnedTooltip: typeof pinnedTooltip;
-    }
-}
-export { OrbitalVisualizer };

package/dist/lib/visualizer/index.d.ts

@@ -1,144 +0,0 @@
-/**
- * Orbital State Machine Visualizer
- *
- * Renders SVG diagrams from Orbital schemas and Trait definitions.
- * Can be used in documentation, IDE previews, and other tools.
- */
-import type { Effect, OrbitalSchema, SExpr } from '@almadar/core';
-export interface VisualizerConfig {
-    nodeRadius: number;
-    nodeSpacing: number;
-    initialIndicatorOffset: number;
-    arrowSize: number;
-    colors: {
-        background: string;
-        node: string;
-        nodeBorder: string;
-        nodeText: string;
-        initialNode: string;
-        finalNode: string;
-        arrow: string;
-        arrowText: string;
-        effectText: string;
-        guardText: string;
-        initial: string;
-    };
-    fonts: {
-        node: string;
-        event: string;
-        effect: string;
-    };
-}
-export interface StateDefinition {
-    name: string;
-    isInitial?: boolean;
-    isFinal?: boolean;
-    description?: string;
-}
-export interface TransitionDefinition {
-    from: string;
-    to: string;
-    event: string;
-    guard?: SExpr | null;
-    effects?: Effect[];
-}
-export interface StateMachineDefinition {
-    states: StateDefinition[];
-    transitions: TransitionDefinition[];
-}
-export interface EntityDefinition {
-    name: string;
-    fields?: (string | {
-        name: string;
-    })[];
-}
-export interface RenderOptions {
-    title?: string;
-    entity?: EntityDefinition;
-}
-/** Position data for a state node in DOM layout */
-export interface DomStateNode {
-    id: string;
-    name: string;
-    x: number;
-    y: number;
-    radius: number;
-    isInitial: boolean;
-    isFinal: boolean;
-    description?: string;
-}
-/** Position data for a transition arrow */
-export interface DomTransitionPath {
-    id: string;
-    from: string;
-    to: string;
-    /** SVG path data for the curved arrow */
-    pathData: string;
-    /** Midpoint for label positioning */
-    labelX: number;
-    labelY: number;
-}
-/** Position data for a transition label with guard/effect details */
-export interface DomTransitionLabel {
-    id: string;
-    from: string;
-    to: string;
-    event: string;
-    x: number;
-    y: number;
-    /** Human-readable guard text (e.g., "if amount > 100") */
-    guardText?: string;
-    /** Human-readable effect texts */
-    effectTexts: string[];
-    /** Whether this transition has details to show in tooltip */
-    hasDetails: boolean;
-}
-/** Entity input box data */
-export interface DomEntityBox {
-    name: string;
-    fields: string[];
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/** Output effects box data */
-export interface DomOutputsBox {
-    outputs: string[];
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/** Complete DOM layout data for rendering */
-export interface DomLayoutData {
-    width: number;
-    height: number;
-    title?: string;
-    states: DomStateNode[];
-    paths: DomTransitionPath[];
-    labels: DomTransitionLabel[];
-    entity?: DomEntityBox;
-    outputs?: DomOutputsBox;
-    config: VisualizerConfig;
-}
-export declare const DEFAULT_CONFIG: VisualizerConfig;
-declare function formatGuard(guard: SExpr | null | undefined): string;
-export declare function getEffectSummary(effects: Effect[]): string;
-declare function extractOutputsFromTransitions(transitions: TransitionDefinition[]): string[];
-/**
- * Render a state machine to an SVG string.
- * Works in both browser and Node.js environments.
- */
-export declare function renderStateMachineToSvg(stateMachine: StateMachineDefinition, options?: RenderOptions, config?: VisualizerConfig): string;
-/**
- * Extract state machine from various data formats (Trait, Orbital, or raw)
- */
-export declare function extractStateMachine(data: OrbitalSchema | object): StateMachineDefinition | null;
-/**
- * Render a state machine to DOM layout data.
- * This is used by the DOM-based visualizer component for hybrid SVG/DOM rendering.
- * Unlike renderStateMachineToSvg, this returns structured data instead of an SVG string.
- */
-export declare function renderStateMachineToDomData(stateMachine: StateMachineDefinition, options?: RenderOptions, config?: VisualizerConfig): DomLayoutData;
-export { formatGuard, extractOutputsFromTransitions };

package/dist/lib/wrapCallbackForEvent.d.ts

@@ -1,16 +0,0 @@
-import type { PatternCallbackArg } from '@almadar/patterns';
-import type { EventPayload, EventPayloadValue } from '@almadar/core';
-/**
- * Build the runtime wrapper that turns a string-typed callback prop
- * (e.g. `onTabChange: "TAB_CHANGED"`) into a function the component can
- * invoke. The wrapper consumes the component's positional callback args
- * by name and dispatches an OBJECT payload `{ argName: value, ... }` so
- * the bus carries the trait's declared event payload, not a raw
- * positional spread. Mirrors the codegen wrapper in
- * `orbital-shell-typescript/src/codegen/pattern.rs` (C2 compiled path).
- *
- * Single-sourcing this logic across runtime and codegen (shared shape,
- * not shared code — codegen emits string source) is what keeps the two
- * paths from silently diverging on payload shape.
- */
-export declare function wrapCallbackForEvent(qualifiedEvent: string, callbackArgs: PatternCallbackArg[] | undefined, emit: (eventKey: string, payload?: EventPayload) => void): (...args: EventPayloadValue[]) => void;