@almadar/ui 5.111.0 → 5.112.0

package/dist/GameAudioProvider-CPGwD49P.d.cts

@@ -0,0 +1,151 @@
+import React__default from 'react';
+import { AssetUrl } from '@almadar/core';
+
+/**
+ * Cross-cutting atom-level prop shapes shared across the design system.
+ */
+
+/**
+ * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
+ * names that every component in the design system understands.  Prefer this
+ * over a bare `string` for any `color` or `variant` prop.
+ */
+type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
+/**
+ * Concrete error-state shape read by display components (`error.message`,
+ * occasionally `error.stack`). Structurally assignable from the global `Error`,
+ * so existing call sites passing an `Error` keep working — this just gives the
+ * pattern extractor a readable field schema instead of the opaque `Error` global.
+ */
+type UiError = {
+    message: string;
+    name?: string;
+    code?: string;
+    stack?: string;
+};
+/**
+ * A labelled link/CTA used by marketing molecules (HeroSection, CTABanner,
+ * PricingCard) for their primary/secondary call-to-action props.
+ */
+type LinkAction = {
+    label: string;
+    href: string;
+};
+/** An image with its required alt text. */
+type ImageSource = {
+    src: AssetUrl;
+    alt: string;
+};
+/** A 2D point in canvas/layout coordinates. */
+type Point = {
+    x: number;
+    y: number;
+};
+/** A 2D rectangle in canvas coordinates (`w`/`h` = width/height). */
+type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+
+interface SoundEntry {
+    /** Single path or array of paths — array picks randomly on each play */
+    path: string | string[];
+    /** Volume 0–1 (multiplied by masterVolume; default 1) */
+    volume?: number;
+    /** Whether this sound loops (background music) */
+    loop?: boolean;
+    /** Number of concurrent Audio instances in the pool (default 1) */
+    poolSize?: number;
+    /** Start automatically on first user interaction */
+    autostart?: boolean;
+    /** Use crossfade transitions when played via playMusic() */
+    crossfade?: boolean;
+    /** Crossfade duration in ms (default 1500) */
+    crossfadeDurationMs?: number;
+}
+type AudioManifest = Record<string, SoundEntry>;
+interface GameAudioControls {
+    /** Play a sound effect (instant, pooled) */
+    play: (key: string) => void;
+    /** Stop all instances of a sound effect */
+    stop: (key: string) => void;
+    /** Stop all sounds including music */
+    stopAll: () => void;
+    /** Crossfade to a new music track */
+    playMusic: (key: string) => void;
+    /** Fade out and stop the current music */
+    stopMusic: (fadeDurationMs?: number) => void;
+    muted: boolean;
+    setMuted: (muted: boolean) => void;
+    masterVolume: number;
+    setMasterVolume: (volume: number) => void;
+}
+interface UseGameAudioOptions {
+    /** Sound definitions keyed by logical name */
+    manifest: AudioManifest;
+    /** Prefix prepended to all `path` values (default '') */
+    baseUrl?: string;
+    /** Start muted (default false) */
+    initialMuted?: boolean;
+    /** Master volume 0–1 (default 1) */
+    initialVolume?: number;
+}
+declare function useGameAudio({ manifest, baseUrl, initialMuted, initialVolume, }: UseGameAudioOptions): GameAudioControls;
+declare namespace useGameAudio {
+    var displayName: string;
+}
+
+/**
+ * GameAudioProvider
+ *
+ * Context provider that wires the audio system to the Almadar event bus.
+ * Wrap your game organism with this provider, then emit:
+ *
+ *   emit('UI:PLAY_SOUND', { key: 'footstep' })
+ *
+ * from anywhere inside the tree and the corresponding sound will play.
+ *
+ * The provider also exposes `muted`/`setMuted` and `masterVolume`/
+ * `setMasterVolume` via the `GameAudioContext` for toggle buttons.
+ *
+ * Closed-circuit props (`className`, `isLoading`, `error`) are
+ * accepted but intentionally unused — the provider renders only its children.
+ *
+ * @packageDocumentation
+ */
+
+type GameAudioContextValue = Pick<GameAudioControls, 'muted' | 'setMuted' | 'masterVolume' | 'setMasterVolume' | 'play' | 'playMusic' | 'stopMusic'>;
+declare const GameAudioContext: React__default.Context<GameAudioContextValue | null>;
+/**
+ * Access the game audio context.
+ * Must be called from within a `<GameAudioProvider>` tree.
+ */
+declare function useGameAudioContext(): GameAudioContextValue;
+/**
+ * Access the game audio context, or `null` when there is no `<GameAudioProvider>`
+ * ancestor. Lets a component stay self-contained (render standalone with a local
+ * fallback) — the provider is an implementation detail, never a hard precondition.
+ */
+declare function useGameAudioContextOptional(): GameAudioContextValue | null;
+interface GameAudioProviderProps {
+    /** Sound manifest — keys mapped to SoundEntry definitions */
+    manifest: AudioManifest;
+    /** Base URL prepended to all sound paths (default '') */
+    baseUrl?: string;
+    /** Children to render */
+    children: React__default.ReactNode;
+    /** Initial muted state */
+    initialMuted?: boolean;
+    /** Closed-circuit props (unused, accepted for runtime compatibility) */
+    className?: string;
+    isLoading?: boolean;
+    error?: UiError | null;
+}
+declare function GameAudioProvider({ manifest, baseUrl, children, initialMuted, }: GameAudioProviderProps): React__default.JSX.Element;
+declare namespace GameAudioProvider {
+    var displayName: string;
+}
+
+export { type AudioManifest as A, type ColorToken as C, GameAudioContext as G, type ImageSource as I, type LinkAction as L, type Point as P, type Rect as R, type SoundEntry as S, type UiError as U, type GameAudioContextValue as a, GameAudioProvider as b, type GameAudioProviderProps as c, useGameAudioContextOptional as d, type GameAudioControls as e, type UseGameAudioOptions as f, useGameAudio as g, useGameAudioContext as u };

package/dist/GameAudioProvider-CPGwD49P.d.ts

@@ -0,0 +1,151 @@
+import React__default from 'react';
+import { AssetUrl } from '@almadar/core';
+
+/**
+ * Cross-cutting atom-level prop shapes shared across the design system.
+ */
+
+/**
+ * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
+ * names that every component in the design system understands.  Prefer this
+ * over a bare `string` for any `color` or `variant` prop.
+ */
+type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
+/**
+ * Concrete error-state shape read by display components (`error.message`,
+ * occasionally `error.stack`). Structurally assignable from the global `Error`,
+ * so existing call sites passing an `Error` keep working — this just gives the
+ * pattern extractor a readable field schema instead of the opaque `Error` global.
+ */
+type UiError = {
+    message: string;
+    name?: string;
+    code?: string;
+    stack?: string;
+};
+/**
+ * A labelled link/CTA used by marketing molecules (HeroSection, CTABanner,
+ * PricingCard) for their primary/secondary call-to-action props.
+ */
+type LinkAction = {
+    label: string;
+    href: string;
+};
+/** An image with its required alt text. */
+type ImageSource = {
+    src: AssetUrl;
+    alt: string;
+};
+/** A 2D point in canvas/layout coordinates. */
+type Point = {
+    x: number;
+    y: number;
+};
+/** A 2D rectangle in canvas coordinates (`w`/`h` = width/height). */
+type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+
+interface SoundEntry {
+    /** Single path or array of paths — array picks randomly on each play */
+    path: string | string[];
+    /** Volume 0–1 (multiplied by masterVolume; default 1) */
+    volume?: number;
+    /** Whether this sound loops (background music) */
+    loop?: boolean;
+    /** Number of concurrent Audio instances in the pool (default 1) */
+    poolSize?: number;
+    /** Start automatically on first user interaction */
+    autostart?: boolean;
+    /** Use crossfade transitions when played via playMusic() */
+    crossfade?: boolean;
+    /** Crossfade duration in ms (default 1500) */
+    crossfadeDurationMs?: number;
+}
+type AudioManifest = Record<string, SoundEntry>;
+interface GameAudioControls {
+    /** Play a sound effect (instant, pooled) */
+    play: (key: string) => void;
+    /** Stop all instances of a sound effect */
+    stop: (key: string) => void;
+    /** Stop all sounds including music */
+    stopAll: () => void;
+    /** Crossfade to a new music track */
+    playMusic: (key: string) => void;
+    /** Fade out and stop the current music */
+    stopMusic: (fadeDurationMs?: number) => void;
+    muted: boolean;
+    setMuted: (muted: boolean) => void;
+    masterVolume: number;
+    setMasterVolume: (volume: number) => void;
+}
+interface UseGameAudioOptions {
+    /** Sound definitions keyed by logical name */
+    manifest: AudioManifest;
+    /** Prefix prepended to all `path` values (default '') */
+    baseUrl?: string;
+    /** Start muted (default false) */
+    initialMuted?: boolean;
+    /** Master volume 0–1 (default 1) */
+    initialVolume?: number;
+}
+declare function useGameAudio({ manifest, baseUrl, initialMuted, initialVolume, }: UseGameAudioOptions): GameAudioControls;
+declare namespace useGameAudio {
+    var displayName: string;
+}
+
+/**
+ * GameAudioProvider
+ *
+ * Context provider that wires the audio system to the Almadar event bus.
+ * Wrap your game organism with this provider, then emit:
+ *
+ *   emit('UI:PLAY_SOUND', { key: 'footstep' })
+ *
+ * from anywhere inside the tree and the corresponding sound will play.
+ *
+ * The provider also exposes `muted`/`setMuted` and `masterVolume`/
+ * `setMasterVolume` via the `GameAudioContext` for toggle buttons.
+ *
+ * Closed-circuit props (`className`, `isLoading`, `error`) are
+ * accepted but intentionally unused — the provider renders only its children.
+ *
+ * @packageDocumentation
+ */
+
+type GameAudioContextValue = Pick<GameAudioControls, 'muted' | 'setMuted' | 'masterVolume' | 'setMasterVolume' | 'play' | 'playMusic' | 'stopMusic'>;
+declare const GameAudioContext: React__default.Context<GameAudioContextValue | null>;
+/**
+ * Access the game audio context.
+ * Must be called from within a `<GameAudioProvider>` tree.
+ */
+declare function useGameAudioContext(): GameAudioContextValue;
+/**
+ * Access the game audio context, or `null` when there is no `<GameAudioProvider>`
+ * ancestor. Lets a component stay self-contained (render standalone with a local
+ * fallback) — the provider is an implementation detail, never a hard precondition.
+ */
+declare function useGameAudioContextOptional(): GameAudioContextValue | null;
+interface GameAudioProviderProps {
+    /** Sound manifest — keys mapped to SoundEntry definitions */
+    manifest: AudioManifest;
+    /** Base URL prepended to all sound paths (default '') */
+    baseUrl?: string;
+    /** Children to render */
+    children: React__default.ReactNode;
+    /** Initial muted state */
+    initialMuted?: boolean;
+    /** Closed-circuit props (unused, accepted for runtime compatibility) */
+    className?: string;
+    isLoading?: boolean;
+    error?: UiError | null;
+}
+declare function GameAudioProvider({ manifest, baseUrl, children, initialMuted, }: GameAudioProviderProps): React__default.JSX.Element;
+declare namespace GameAudioProvider {
+    var displayName: string;
+}
+
+export { type AudioManifest as A, type ColorToken as C, GameAudioContext as G, type ImageSource as I, type LinkAction as L, type Point as P, type Rect as R, type SoundEntry as S, type UiError as U, type GameAudioContextValue as a, GameAudioProvider as b, type GameAudioProviderProps as c, useGameAudioContextOptional as d, type GameAudioControls as e, type UseGameAudioOptions as f, useGameAudio as g, useGameAudioContext as u };

package/dist/TraitProvider-YkK6tXDw.d.cts

@@ -0,0 +1,236 @@
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import { ResolvedEntity, EventPayload, EntityRow, OrbitalSchema, BusEventSource, SExpr, ResolvedTrait, ResolvedTraitBinding } from '@almadar/core';
+import { AnyPatternConfig } from '@almadar/core/patterns';
+
+/**
+ * EntitySchemaContext
+ *
+ * Minimal context providing entity schema definitions (field metadata).
+ * This is NOT a data store — actual entity rows flow through the state
+ * machine's `@payload.data` binding on the emitting trait's fetch-success
+ * transition and land on the rendering component's `entity` prop.
+ *
+ * Replaces EntityStore's schema functionality without the mock data generation.
+ *
+ * @packageDocumentation
+ */
+
+interface EntitySchemaContextValue {
+    /** Entity definitions (schema metadata only) */
+    entities: Map<string, ResolvedEntity>;
+    /**
+     * Per-trait linkedEntity name. `ResolvedTrait` itself doesn't carry
+     * linkedEntity (it lives on `ResolvedTraitBinding` at the page-binding
+     * level), so OrbPreview pre-projects every page's trait bindings into
+     * a flat `traitName → entityName` map for the slot renderer.
+     *
+     * Used by SlotContentRenderer to resolve `entityDef` via
+     * `traitLinkedEntities.get(sourceTrait) → entities.get(...)` when the
+     * rendered pattern's `entity:` prop is a resolved value (V2 path)
+     * rather than a string entity-name. Without this lookup, form-section
+     * can't enrich its fields with entity field metadata (values enum,
+     * etc.) and an enum field renders as a plain text input. Closes VR3.
+     */
+    traitLinkedEntities: ReadonlyMap<string, string>;
+    /**
+     * Per-trait owning-orbital name. Same shape as `traitLinkedEntities`,
+     * built from `schema.orbitals[].traits[]`. UISlotRenderer uses this
+     * to wrap each slot's rendered subtree in `TraitScopeProvider` so
+     * descendant pure components (Button, etc.) emit qualified
+     * `UI:Orbital.Trait.EVENT` keys via the scoped useEventBus.
+     */
+    orbitalsByTrait: ReadonlyMap<string, string>;
+}
+interface EntitySchemaProviderProps {
+    /** Entity definitions from resolved schema */
+    entities: ResolvedEntity[];
+    /**
+     * Per-trait linkedEntity name, projected from every page's
+     * ResolvedTraitBinding. Optional for back-compat; when omitted,
+     * SlotContentRenderer's enrichment path can only follow the
+     * legacy V1 string-entity-name lookup.
+     */
+    traitLinkedEntities?: ReadonlyMap<string, string>;
+    /**
+     * Per-trait owning-orbital name. Required for the runtime path's
+     * trait-scoped event qualification (Button etc. emit qualified keys
+     * via TraitScopeProvider). Optional for back-compat with consumers
+     * that don't yet thread the orbital map through.
+     */
+    orbitalsByTrait?: ReadonlyMap<string, string>;
+    /** Children */
+    children: React__default.ReactNode;
+}
+/**
+ * Provides entity schema definitions to the component tree.
+ *
+ * This is a lightweight provider that only holds schema metadata (field definitions).
+ * Actual entity rows arrive via `@payload.data` on the rendering trait's
+ * success transition — they do NOT live in this context.
+ */
+declare function EntitySchemaProvider({ entities, traitLinkedEntities, orbitalsByTrait, children, }: EntitySchemaProviderProps): React__default.ReactElement;
+/**
+ * Access entity schema definitions.
+ * Use this for field metadata (form building, filter enrichment).
+ * Actual entity rows flow via `@payload.data` on the state machine's
+ * success transition — never read them from a context.
+ */
+declare function useEntitySchema(): EntitySchemaContextValue;
+/**
+ * Safe version of useEntitySchema that returns null when no provider is present.
+ * Used by UISlotRenderer which may render outside an EntitySchemaProvider (compiled mode).
+ */
+declare function useEntitySchemaOptional(): EntitySchemaContextValue | null;
+
+/** Wire-format client effect tuple from the server response. */
+type ClientEffectTuple = ['render-ui', string, AnyPatternConfig | null, ...SExpr[]] | ['navigate', string, ...SExpr[]] | ['notify', string, ...SExpr[]];
+interface OrbitalEventResponse {
+    success: boolean;
+    transitioned: boolean;
+    states: Record<string, string>;
+    /**
+     * Server-cascade events carried back in the response. Each entry has a
+     * `source: BusEventSource` stamped by the compiled handler (`emit ...
+     * { source: __ORBITAL_SOURCE }`) so the client can re-broadcast on the
+     * qualified `UI:Orbital.Trait.EVENT` bus key (gap #13).
+     */
+    emittedEvents?: Array<{
+        event: string;
+        payload?: EventPayload;
+        source?: BusEventSource;
+    }>;
+    data?: Record<string, EntityRow[]>;
+    clientEffects?: ClientEffectTuple[];
+    /**
+     * Same effects as `clientEffects`, paired with the trait that produced
+     * each one. When present, prefer this for trait attribution. Falls back
+     * to legacy `clientEffects` parsing on older servers.
+     */
+    clientEffectsByTrait?: Array<{
+        traitName: string;
+        effect: ClientEffectTuple;
+    }>;
+    error?: string;
+}
+interface ServerClientEffect {
+    type: 'render-ui' | 'navigate' | 'notify';
+    slot?: string;
+    pattern?: AnyPatternConfig;
+    route?: string;
+    params?: EventPayload;
+    message?: string;
+    /**
+     * Trait that emitted this effect. Used by `<TraitFrame>` to resolve
+     * `@trait.X` bindings. Undefined when the server didn't tag the effect
+     * (older servers that pre-date the per-trait sidecar).
+     */
+    traitName?: string;
+}
+/** Metadata about what the server returned, for debugger logging */
+interface ServerResponseMeta {
+    success: boolean;
+    clientEffects: number;
+    dataEntities: Record<string, number>;
+    /** Raw entity data from server response (for EntityStore advancement) */
+    data?: Record<string, EntityRow[]>;
+    emittedEvents: string[];
+    error?: string;
+}
+interface SendEventResult {
+    effects: ServerClientEffect[];
+    meta: ServerResponseMeta;
+}
+interface ServerBridgeContextValue {
+    connected: boolean;
+    sendEvent: (orbitalName: string, event: string, payload?: EventPayload) => Promise<SendEventResult>;
+}
+/**
+ * Transport adapter for ServerBridgeProvider. Decouples the bridge's
+ * cascade-rebroadcast / effect-parsing logic from its wire format.
+ *
+ * - The `serverUrl` mode (default) uses an HTTP transport that POSTs to
+ *   `/register`, `/unregister`, `/:orbital/events`. This is what canonical
+ *   playground-runtime (`tools/runtime-verify`) and apps/builder-server
+ *   speak.
+ * - The `transport` mode lets a consumer plug in a direct function-call
+ *   adapter — used by `<BrowserPlayground>` to invoke
+ *   `OrbitalServerRuntime.processOrbitalEvent` in-process, no HTTP, no
+ *   server. Both modes return the same `OrbitalEventResponse` shape so the
+ *   cascade-rebroadcast logic is identical downstream.
+ */
+interface ServerBridgeTransport {
+    register: (schema: OrbitalSchema) => Promise<boolean>;
+    unregister: () => Promise<void>;
+    sendEvent: (orbitalName: string, event: string, payload?: EventPayload) => Promise<OrbitalEventResponse>;
+}
+/**
+ * Access the server bridge. Returns a no-op stub when outside the provider.
+ */
+declare function useServerBridge(): ServerBridgeContextValue;
+interface ServerBridgeProviderProps {
+    schema: OrbitalSchema;
+    /** HTTP server URL (canonical playground-runtime / apps/builder-server). */
+    serverUrl?: string;
+    /**
+     * Custom transport adapter. Use this for in-process execution (e.g.
+     * `<BrowserPlayground>` invokes `OrbitalServerRuntime.processOrbitalEvent`
+     * directly). Mutually exclusive with `serverUrl`.
+     */
+    transport?: ServerBridgeTransport;
+    children: ReactNode;
+}
+declare function ServerBridgeProvider({ schema, serverUrl, transport: customTransport, children, }: ServerBridgeProviderProps): React.JSX.Element;
+
+/**
+ * TraitProvider Component
+ *
+ * Provides trait state machines to child components via React context.
+ *
+ * @packageDocumentation
+ */
+
+interface TraitInstance {
+    /** Trait name */
+    name: string;
+    /** Current state */
+    currentState: string;
+    /** Available events (can be triggered) */
+    availableEvents: string[];
+    /** Dispatch an event to the state machine */
+    dispatch: (eventKey: string, payload?: EventPayload) => void;
+    /** Check if an event can be dispatched */
+    canDispatch: (eventKey: string) => boolean;
+    /** Get the full trait definition */
+    trait: ResolvedTrait;
+}
+interface TraitContextValue {
+    /** All trait instances on this page */
+    traits: Map<string, TraitInstance>;
+    /** Get a trait instance by name */
+    getTrait: (name: string) => TraitInstance | undefined;
+    /** Dispatch an event to a specific trait */
+    dispatchToTrait: (traitName: string, eventKey: string, payload?: EventPayload) => void;
+    /** Check if an event can be dispatched to a trait */
+    canDispatch: (traitName: string, eventKey: string) => boolean;
+}
+declare const TraitContext: React__default.Context<TraitContextValue | null>;
+interface TraitProviderProps {
+    /** Trait bindings for this page */
+    traits: ResolvedTraitBinding[];
+    /** Entity map for context */
+    entities: Map<string, ResolvedEntity>;
+    /** Children to render */
+    children: React__default.ReactNode;
+}
+declare function TraitProvider({ traits: traitBindings, children, }: TraitProviderProps): React__default.ReactElement;
+/**
+ * Access the trait context from within the TraitProvider.
+ */
+declare function useTraitContext(): TraitContextValue;
+/**
+ * Access a specific trait instance.
+ */
+declare function useTrait(traitName: string): TraitInstance | undefined;
+
+export { type EntitySchemaContextValue as E, type SendEventResult as S, TraitContext as T, EntitySchemaProvider as a, type EntitySchemaProviderProps as b, type ServerBridgeContextValue as c, ServerBridgeProvider as d, type ServerBridgeProviderProps as e, type ServerBridgeTransport as f, type ServerClientEffect as g, type ServerResponseMeta as h, type TraitContextValue as i, type TraitInstance as j, TraitProvider as k, type TraitProviderProps as l, useEntitySchemaOptional as m, useServerBridge as n, useTrait as o, useTraitContext as p, useEntitySchema as u };