@almadar/ui 5.111.0 → 5.113.0

package/dist/lib/offline-executor.d.ts

@@ -1,239 +0,0 @@
-/**
- * Offline Effect Executor
- *
- * Enables client-only mode for applications that need to work without
- * server connectivity. Provides:
- * - Mock data providers for simulating server responses
- * - Local effect execution without server round-trip
- * - Sync queue for effects that need server persistence when back online
- *
- * Used by both Builder preview (offline mode) and compiled shells (PWA mode).
- *
- * @packageDocumentation
- */
-import type { EntityRow, FieldValue } from '@almadar/core';
-import type { ClientEffect, ClientEffectExecutorConfig, EventResponse } from '../types/renderer-types';
-/**
- * Effect that needs to be synced to server when online
- */
-export interface PendingSyncEffect {
-    /** Unique ID for this effect */
-    id: string;
-    /** Timestamp when effect was queued */
-    timestamp: number;
-    /** Effect type (persist, call-service, etc.) */
-    type: string;
-    /** Effect payload */
-    payload: Record<string, FieldValue>;
-    /** Number of retry attempts */
-    retries: number;
-    /** Maximum retries before giving up */
-    maxRetries: number;
-}
-/**
- * Configuration for offline executor
- */
-export interface OfflineExecutorConfig extends ClientEffectExecutorConfig {
-    /**
-     * Mock data provider for simulating fetch responses.
-     * Returns data for a given entity name.
-     */
-    mockDataProvider?: (entityName: string) => EntityRow[];
-    /**
-     * Whether to queue server effects for sync when online.
-     * Default: true
-     */
-    enableSyncQueue?: boolean;
-    /**
-     * Maximum number of effects to queue before dropping oldest.
-     * Default: 100
-     */
-    maxQueueSize?: number;
-    /**
-     * Callback when an effect is added to sync queue.
-     */
-    onEffectQueued?: (effect: PendingSyncEffect) => void;
-    /**
-     * Callback when sync queue changes.
-     */
-    onQueueChange?: (queue: PendingSyncEffect[]) => void;
-}
-/**
- * Offline executor state
- */
-export interface OfflineExecutorState {
-    /** Whether we're in offline mode */
-    isOffline: boolean;
-    /** Pending effects waiting for sync */
-    syncQueue: PendingSyncEffect[];
-    /** Number of effects processed locally */
-    localEffectsProcessed: number;
-    /** Number of effects synced to server */
-    effectsSynced: number;
-    /** Last sync attempt timestamp */
-    lastSyncAttempt?: number;
-    /** Last successful sync timestamp */
-    lastSuccessfulSync?: number;
-}
-/**
- * OfflineExecutor - Handles effects in offline/client-only mode.
- *
- * Features:
- * - Executes client effects immediately (render-ui, navigate, notify, emit)
- * - Queues server effects (persist, fetch, call-service) for later sync
- * - Provides mock data for fetch effects when offline
- * - Syncs queued effects when connection is restored
- *
- * @example
- * ```typescript
- * const executor = new OfflineExecutor({
- *   renderToSlot: (slot, pattern) => slotManager.render(slot, pattern),
- *   navigate: (path) => router.push(path),
- *   notify: (message, opts) => toast.show(message, opts),
- *   eventBus: { emit: (event, payload) => bus.emit(event, payload) },
- *   mockDataProvider: (entityName) => mockStore.getAll(entityName),
- * });
- *
- * // Process effects locally
- * const response = executor.processEventOffline('LOAD', { id: '123' });
- *
- * // When back online
- * await executor.syncPendingEffects(serverUrl);
- * ```
- */
-export declare class OfflineExecutor {
-    private config;
-    private state;
-    private storage;
-    constructor(config: OfflineExecutorConfig);
-    /**
-     * Check if we're online (browser API)
-     */
-    private checkOnline;
-    /**
-     * Handle going online
-     */
-    private handleOnline;
-    /**
-     * Handle going offline
-     */
-    private handleOffline;
-    /**
-     * Load sync queue from localStorage
-     */
-    private loadSyncQueue;
-    /**
-     * Save sync queue to localStorage
-     */
-    private saveSyncQueue;
-    /**
-     * Add an effect to the sync queue
-     */
-    private queueForSync;
-    /**
-     * Execute client effects immediately.
-     */
-    executeClientEffects(effects: ClientEffect[]): void;
-    /**
-     * Process an event in offline mode.
-     *
-     * Returns a simulated EventResponse with mock data.
-     * Client effects are executed immediately.
-     * Server effects are queued for sync.
-     */
-    processEventOffline(event: string, payload?: Record<string, FieldValue>, effects?: Array<FieldValue[]>): EventResponse;
-    /**
-     * Sync pending effects to server.
-     *
-     * @param serverUrl - Base URL for the orbital server
-     * @param authToken - Optional auth token for requests
-     * @returns Number of successfully synced effects
-     */
-    syncPendingEffects(serverUrl: string, authToken?: string): Promise<number>;
-    /**
-     * Get current executor state
-     */
-    getState(): OfflineExecutorState;
-    /**
-     * Get number of pending effects
-     */
-    getPendingCount(): number;
-    /**
-     * Clear the sync queue
-     */
-    clearQueue(): void;
-    /**
-     * Dispose the executor and clean up listeners
-     */
-    dispose(): void;
-}
-/**
- * Create an offline executor with sensible defaults.
- *
- * @example
- * ```typescript
- * const executor = createOfflineExecutor({
- *   renderToSlot: slotManager.render,
- *   navigate: router.push,
- *   notify: toast.show,
- *   eventBus: { emit: bus.emit },
- *   mockDataProvider: (entity) => store.getAll(entity),
- * });
- * ```
- */
-export declare function createOfflineExecutor(config: OfflineExecutorConfig): OfflineExecutor;
-/**
- * Options for useOfflineExecutor hook
- */
-export interface UseOfflineExecutorOptions extends OfflineExecutorConfig {
-    /** Server URL for syncing */
-    serverUrl?: string;
-    /** Auth token for server requests */
-    authToken?: string;
-    /** Auto-sync when coming back online */
-    autoSync?: boolean;
-}
-/**
- * Result of useOfflineExecutor hook
- */
-export interface UseOfflineExecutorResult {
-    /** Current executor state */
-    state: OfflineExecutorState;
-    /** Whether we're offline */
-    isOffline: boolean;
-    /** Number of pending effects */
-    pendingCount: number;
-    /** Execute client effects */
-    executeClientEffects: (effects: ClientEffect[]) => void;
-    /** Process event offline */
-    processEventOffline: (event: string, payload?: Record<string, FieldValue>, effects?: Array<FieldValue[]>) => EventResponse;
-    /** Manually trigger sync */
-    sync: () => Promise<number>;
-    /** Clear the queue */
-    clearQueue: () => void;
-}
-/**
- * React hook for offline effect execution.
- *
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { isOffline, pendingCount, processEventOffline, sync } = useOfflineExecutor({
- *     renderToSlot: slotManager.render,
- *     navigate: router.push,
- *     notify: toast.show,
- *     eventBus: { emit: bus.emit },
- *     serverUrl: '/api/orbitals',
- *     autoSync: true,
- *   });
- *
- *   return (
- *     <div>
- *       {isOffline && <Banner>Offline - {pendingCount} changes pending</Banner>}
- *       <button onClick={() => processEventOffline('SAVE', data)}>Save</button>
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useOfflineExecutor(options: UseOfflineExecutorOptions): UseOfflineExecutorResult;

package/dist/lib/orbitalsByTrait.d.ts

@@ -1,34 +0,0 @@
-/**
- * Build the `trait name → owning orbital` map used to form the qualified
- * `UI:<orbital>.<trait>.<event>` bus keys that trait state machines subscribe
- * to. Pure + dependency-free so it can be unit-tested without a React render.
- *
- * Critically, it backfills from the RESOLVED page bindings, not just the source
- * `schema.orbitals[].traits`. An auto-pulled sibling trait (e.g. an embedded
- * `@trait.X` calendar lifted into the orbital by the compiler's sibling-pull)
- * is absent from the source orbital's `traits[]`, so a source-only map misses
- * it — leaving its self-subscription unregistered and its own fetch-success
- * (e.g. `CalendarEventLoaded`) unheard, so the trait sticks in `loading`. A
- * pulled sibling lands in the same orbital as the page that references it, so
- * we backfill from the resolved page's owning orbital. Source-declared mappings
- * win; the IR only fills gaps.
- */
-export interface OrbitalsByTraitSchema {
-    orbitals?: ReadonlyArray<{
-        name: string;
-        traits?: ReadonlyArray<string | {
-            ref?: string;
-            name?: string;
-        }>;
-        pages?: ReadonlyArray<string | {
-            path?: string;
-        }>;
-    }>;
-}
-export interface ResolvedPageTraits {
-    /** Page route path, matched against the source orbital's page paths. */
-    path?: string;
-    /** Resolved trait names mounted on the page (includes pulled siblings). */
-    traitNames: readonly string[];
-}
-export declare function buildOrbitalsByTrait(schema: OrbitalsByTraitSchema | undefined, resolvedPages?: ReadonlyArray<ResolvedPageTraits>): Record<string, string>;

package/dist/lib/painter2d.d.ts

@@ -1,81 +0,0 @@
-/**
- * Painter2D — the portable 2D draw seam.
- *
- * A small verb set that every drawable atom paints through, so a scene stays a
- * pure descriptor tree with no `CanvasRenderingContext2D` reference of its own.
- * The web implementation (`createWebPainter`) wraps a `ctx`; a native platform
- * ships its own implementation of the SAME interface — that is the cross-platform
- * driver (draw-list over DOM overlays). This file is DOM-free: it is the shared
- * contract, importable by any target.
- *
- * Coordinates are PIXELS in the painter's current transform. Scene→pixel mapping
- * is the host projector's job (it maps a core `ScenePos` before calling here), so
- * the painter carries no scene/projection semantics.
- */
-/** An opaque, painter-owned handle to a resolved texture (web: a decoded image). */
-export interface TextureHandle {
-    readonly width: number;
-    readonly height: number;
-}
-/** Destination rectangle for a blit; `w`/`h` omitted → the source's natural size. */
-export interface BlitDest {
-    x: number;
-    y: number;
-    w?: number;
-    h?: number;
-}
-/** Source sub-rectangle within a texture (an atlas frame). Omitted → whole texture. */
-export interface BlitSrc {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}
-/** A polyline/polygon vertex in pixel space. */
-export interface PainterPoint {
-    x: number;
-    y: number;
-}
-export interface TextStyle {
-    color: string;
-    /** CSS font shorthand (e.g. `"12px sans-serif"`). */
-    font?: string;
-    align?: CanvasTextAlign;
-    baseline?: CanvasTextBaseline;
-}
-/** A drop shadow applied to subsequent draws until cleared. */
-export interface PainterShadow {
-    color: string;
-    blur: number;
-}
-/**
- * The verb set. Roughly the union of what `Canvas2D`'s draw passes call on a 2D
- * context, reframed as painter-neutral operations so the same drawable atoms
- * paint identically on web `ctx` and on a native surface.
- */
-export interface Painter2D {
-    /** Reset the surface to `width`×`height` logical px at device-pixel-ratio `dpr`. */
-    setViewport(width: number, height: number, dpr: number): void;
-    /** Clear the whole surface. */
-    clear(): void;
-    save(): void;
-    restore(): void;
-    translate(x: number, y: number): void;
-    scale(sx: number, sy: number): void;
-    rotate(radians: number): void;
-    /** Global alpha (0..1) for subsequent draws. */
-    setAlpha(alpha: number): void;
-    /** Drop shadow for subsequent draws; `null` clears it. */
-    setShadow(shadow: PainterShadow | null): void;
-    /** Resolve a texture URL to a handle, or `null` if not loaded yet (load is kicked off). */
-    resolveTexture(url: string): TextureHandle | null;
-    /** Blit a (sub-rect of a) texture to a destination rectangle. */
-    blit(tex: TextureHandle, dest: BlitDest, src?: BlitSrc): void;
-    fillRect(x: number, y: number, w: number, h: number, color: string): void;
-    strokeRect(x: number, y: number, w: number, h: number, color: string, lineWidth?: number): void;
-    fillPoly(points: readonly PainterPoint[], color: string): void;
-    strokePoly(points: readonly PainterPoint[], color: string, lineWidth?: number, closed?: boolean): void;
-    fillEllipse(cx: number, cy: number, rx: number, ry: number, color: string): void;
-    strokeEllipse(cx: number, cy: number, rx: number, ry: number, color: string, lineWidth?: number): void;
-    text(str: string, x: number, y: number, style: TextStyle): void;
-}

package/dist/lib/parseContentSegments.d.ts

@@ -1,42 +0,0 @@
-/**
- * Content Segment Parsing Utilities
- *
- * Parses rich content with code blocks and quiz tags into structured
- * segments for rendering. Detects orbital schemas in JSON code blocks
- * and marks them for JazariStateMachine rendering.
- */
-import type { OrbitalSchema } from '@almadar/core';
-/** Segment types for content rendering */
-export type ContentSegment = {
-    type: 'markdown';
-    content: string;
-} | {
-    type: 'code';
-    language: string;
-    content: string;
-} | {
-    type: 'orbital';
-    language: string;
-    content: string;
-    schema: OrbitalSchema;
-} | {
-    type: 'quiz';
-    question: string;
-    answer: string;
-};
-/**
- * Parse markdown content to extract code blocks.
- *
- * Splits markdown into segments of plain markdown and fenced code blocks.
- * JSON/orb code blocks containing orbital schemas are tagged as 'orbital'.
- */
-export declare function parseMarkdownWithCodeBlocks(content: string | undefined | null): ContentSegment[];
-/**
- * Parse content to extract all segments including quiz tags and code blocks.
- *
- * Supported tags:
- * - <question>q</question><answer>a</answer> — Quiz Q&A
- *
- * Also handles fenced code blocks (```language...```) with orbital detection.
- */
-export declare function parseContentSegments(content: string | undefined | null): ContentSegment[];

package/dist/lib/pattern-resolver.d.ts

@@ -1,88 +0,0 @@
-/**
- * Pattern Resolver
- *
- * Resolves pattern configurations to component information.
- * Uses the central pattern registry and component mapping from orbital-shared/patterns/.
- *
- * This is the shared logic used by both Builder's PatternRenderer and
- * the compiled shell's UISlotRenderer.
- *
- * @packageDocumentation
- */
-import type { PatternPropDef } from '@almadar/patterns';
-import type { PatternConfig, MappedPattern } from '../types/renderer-types';
-/**
- * Component mapping entry from component-mapping.json
- */
-interface ComponentMappingEntry {
-    component: string;
-    importPath: string;
-    category: string;
-    deprecated?: boolean;
-    replacedBy?: string;
-}
-/**
- * Pattern definition from registry.json
- */
-interface PatternDefinition {
-    type: string;
-    category: string;
-    description: string;
-    propsSchema?: Record<string, PatternPropDef>;
-}
-/**
- * Initialize the pattern resolver with mappings.
- * Called at app startup with data from JSON files.
- */
-export declare function initializePatternResolver(config: {
-    componentMapping: Record<string, ComponentMappingEntry>;
-    patternRegistry: Record<string, PatternDefinition>;
-}): void;
-/**
- * Set component mapping (alternative to full initialization).
- */
-export declare function setComponentMapping(mapping: Record<string, ComponentMappingEntry>): void;
-/**
- * Set pattern registry (alternative to full initialization).
- */
-export declare function setPatternRegistry(registry: Record<string, PatternDefinition>): void;
-/**
- * Resolve a pattern configuration to component information.
- *
- * @param config - Pattern configuration from render-ui effect
- * @returns Resolved pattern with component name, import path, and validated props
- * @throws Error if pattern type is unknown
- *
- * @example
- * ```typescript
- * const resolved = resolvePattern({
- *   type: 'entity-table',
- *   entity: 'Task',
- *   columns: ['title', 'status']
- * });
- * // resolved.component === 'DataTable'
- * // resolved.importPath === '@/components/organisms/DataTable'
- * ```
- */
-export declare function resolvePattern(config: PatternConfig): MappedPattern;
-/**
- * Check if a pattern type is known.
- */
-export declare function isKnownPattern(type: string): boolean;
-/**
- * Get all known pattern types.
- */
-export declare function getKnownPatterns(): string[];
-/**
- * Get patterns by category.
- */
-export declare function getPatternsByCategory(category: string): string[];
-/**
- * Get the component mapping for a pattern type.
- */
-export declare function getPatternMapping(type: string): ComponentMappingEntry | undefined;
-/**
- * Get the pattern definition from the registry.
- */
-export declare function getPatternDefinition(type: string): PatternDefinition | undefined;
-export {};

package/dist/lib/perf.d.ts

@@ -1,32 +0,0 @@
-/**
- * @almadar/ui/runtime — perf instrumentation
- *
- * Ring buffer of timing events for the canvas render path, plus mark/measure
- * helpers and a React.Profiler onRender callback. All gated behind
- * `createLogger('almadar:perf:canvas')` so production (LOG_LEVEL >= WARN)
- * skips both `performance.*` calls and the ring write.
- */
-import type { ProfilerOnRenderCallback } from 'react';
-export declare const PERF_NAMESPACE = "almadar:perf:canvas";
-export interface PerfEntry {
-    readonly name: string;
-    readonly durationMs: number;
-    readonly ts: number;
-    readonly detail?: Readonly<Record<string, unknown>>;
-}
-/**
- * Start a phase. Returns an opaque token; pass to {@link perfEnd}.
- * Returns -1 when the namespace is gated off, so call sites pay only one comparison.
- */
-export declare function perfStart(name: string): number;
-export declare function perfEnd(name: string, startToken: number, detail?: Record<string, unknown>): void;
-/** Synchronous wrapper that times a fn end-to-end. */
-export declare function perfTime<T>(name: string, fn: () => T, detail?: Record<string, unknown>): T;
-/**
- * React.Profiler `onRender` callback. Records `actualDuration` per commit.
- * Phase is `"mount" | "update" | "nested-update"`.
- */
-export declare const profilerOnRender: ProfilerOnRenderCallback;
-/** React hook: returns the current ring snapshot, re-renders on push. */
-export declare function usePerfBuffer(): readonly PerfEntry[];
-export declare function clearPerf(): void;

package/dist/lib/physicsPresets.d.ts

@@ -1,4 +0,0 @@
-export type { PhysicsPreset, PhysicsBody, PhysicsConstraint } from './physicsTypes';
-export { projectileMotion, pendulum, springOscillator } from './mechanics';
-import type { PhysicsPreset } from './physicsTypes';
-export declare const ALL_PRESETS: PhysicsPreset[];

package/dist/lib/physicsTypes.d.ts

@@ -1,43 +0,0 @@
-/**
- * Physics Preset Types
- *
- * Configuration for physics simulation presets.
- */
-export interface PhysicsBody {
-    id: string;
-    x: number;
-    y: number;
-    vx: number;
-    vy: number;
-    mass: number;
-    radius: number;
-    color: string;
-    fixed: boolean;
-}
-export interface PhysicsConstraint {
-    bodyA: number;
-    bodyB: number;
-    length: number;
-    stiffness: number;
-}
-export interface PhysicsPreset {
-    id: string;
-    name: string;
-    description: string;
-    domain: string;
-    gravity?: {
-        x: number;
-        y: number;
-    };
-    bodies: PhysicsBody[];
-    constraints?: PhysicsConstraint[];
-    backgroundColor?: string;
-    showVelocity?: boolean;
-    parameters: Record<string, {
-        value: number;
-        min: number;
-        max: number;
-        step: number;
-        label: string;
-    }>;
-}

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/puzzleObject.d.ts

@@ -1,41 +0,0 @@
-/**
- * puzzleObject — field accessors for reading Event-Handler puzzle-object data
- * off an `EntityRow`.
- *
- * The puzzle objects the kid configures arrive as `entity.objects` (an array of
- * `EntityRow`). These helpers narrow the weakly-typed fields the panel reads.
- * `RuleDefinition` / `RuleOption` are plain UI value DTOs, defined below.
- *
- * @packageDocumentation
- */
-import type { EntityWith } from '@almadar/core';
-/** A single Event-Handler puzzle rule: "when <event> then <action>". Plain value DTO. */
-export type RuleDefinition = {
-    whenEvent: string;
-    thenAction: string;
-};
-/** An option (event or action) selectable in a puzzle rule. Plain value DTO. */
-export interface RuleOption {
-    value: string;
-    label: string;
-}
-type PuzzleObjectRow = EntityWith<{
-    name?: string;
-    icon?: string;
-    states?: string[];
-    currentState?: string;
-    availableEvents?: RuleOption[];
-    availableActions?: RuleOption[];
-    rules?: RuleDefinition[];
-    maxRules?: number;
-}>;
-export declare function objId(o: PuzzleObjectRow): string;
-export declare function objName(o: PuzzleObjectRow): string;
-export declare function objIcon(o: PuzzleObjectRow): string;
-export declare function objStates(o: PuzzleObjectRow): string[];
-export declare function objCurrentState(o: PuzzleObjectRow): string;
-export declare function objAvailableEvents(o: PuzzleObjectRow): RuleOption[];
-export declare function objAvailableActions(o: PuzzleObjectRow): RuleOption[];
-export declare function objRules(o: PuzzleObjectRow): RuleDefinition[];
-export declare function objMaxRules(o: PuzzleObjectRow): number;
-export {};