@thewhateverapp/tile-sdk 0.13.31 → 0.13.33

package/dist/spec/renderer/OverlayCue.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OverlayCue
+ *
+ * Renders a single overlay cue with placement and dismiss handling.
+ */
+import type { OverlayCue as OverlayCueType } from '../types';
+export interface OverlayCueRendererProps {
+    /** The cue to render */
+    cue: OverlayCueType;
+    /** Animation state */
+    isEntering?: boolean;
+    isExiting?: boolean;
+}
+export declare function OverlayCueRenderer({ cue, isEntering, isExiting, }: OverlayCueRendererProps): JSX.Element;
+/**
+ * Renders all visible cues from the runtime.
+ */
+export declare function OverlayCueContainer(): JSX.Element;
+export default OverlayCueRenderer;
+//# sourceMappingURL=OverlayCue.d.ts.map

package/dist/spec/renderer/OverlayCue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OverlayCue.d.ts","sourceRoot":"","sources":["../../../src/spec/renderer/OverlayCue.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAA+C,MAAM,UAAU,CAAC;AAI1G,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,GAAG,EAAE,cAAc,CAAC;IAEpB,sBAAsB;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA6GD,wBAAgB,kBAAkB,CAAC,EACjC,GAAG,EACH,UAAkB,EAClB,SAAiB,GAClB,EAAE,uBAAuB,GAAG,GAAG,CAAC,OAAO,CAgEvC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,GAAG,CAAC,OAAO,CAYjD;AAED,eAAe,kBAAkB,CAAC"}

package/dist/spec/renderer/OverlayCue.js

@@ -0,0 +1,161 @@
+/**
+ * OverlayCue
+ *
+ * Renders a single overlay cue with placement and dismiss handling.
+ */
+import React, { useEffect, useCallback, useState } from 'react';
+import { useOverlayRuntime } from '../runtime/OverlayRuntime';
+import { LayoutRenderer } from './LayoutRenderer';
+// =============================================================================
+// Placement Styles
+// =============================================================================
+function getTilePlacementStyles(placement) {
+    const styles = {
+        position: 'absolute',
+    };
+    // Lane positioning
+    switch (placement.lane) {
+        case 'top':
+            styles.top = placement.inset ?? 16;
+            styles.left = 0;
+            styles.right = 0;
+            break;
+        case 'center':
+            styles.top = '50%';
+            styles.left = '50%';
+            styles.transform = 'translate(-50%, -50%)';
+            break;
+        case 'bottom':
+            styles.bottom = placement.inset ?? 16;
+            styles.left = 0;
+            styles.right = 0;
+            break;
+    }
+    // Alignment
+    if (placement.lane !== 'center') {
+        switch (placement.align) {
+            case 'left':
+                styles.left = placement.inset ?? 16;
+                styles.right = 'auto';
+                break;
+            case 'right':
+                styles.left = 'auto';
+                styles.right = placement.inset ?? 16;
+                break;
+            case 'center':
+            default:
+                styles.display = 'flex';
+                styles.justifyContent = 'center';
+                break;
+        }
+    }
+    // Z-index
+    if (placement.zIndex !== undefined) {
+        styles.zIndex = placement.zIndex;
+    }
+    return styles;
+}
+function getFullPlacementStyles(placement) {
+    const styles = {
+        position: 'absolute',
+    };
+    // Position
+    if (placement.top !== undefined)
+        styles.top = placement.top;
+    if (placement.bottom !== undefined)
+        styles.bottom = placement.bottom;
+    if (placement.left !== undefined)
+        styles.left = placement.left;
+    if (placement.right !== undefined)
+        styles.right = placement.right;
+    // Dimensions
+    if (placement.width !== undefined) {
+        styles.width = typeof placement.width === 'number' ? placement.width : placement.width;
+    }
+    if (placement.height !== undefined) {
+        styles.height = typeof placement.height === 'number' ? placement.height : placement.height;
+    }
+    // Z-index
+    if (placement.zIndex !== undefined) {
+        styles.zIndex = placement.zIndex;
+    }
+    return styles;
+}
+function getPlacementStyles(placement) {
+    if ('lane' in placement) {
+        return getTilePlacementStyles(placement);
+    }
+    return getFullPlacementStyles(placement);
+}
+// =============================================================================
+// Animation Classes
+// =============================================================================
+function getAnimationClasses(isEntering, isExiting) {
+    if (isEntering) {
+        return 'animate-in fade-in slide-in-from-bottom-4 duration-300';
+    }
+    if (isExiting) {
+        return 'animate-out fade-out slide-out-to-bottom-4 duration-200';
+    }
+    return '';
+}
+// =============================================================================
+// Main Component
+// =============================================================================
+export function OverlayCueRenderer({ cue, isEntering = false, isExiting = false, }) {
+    const { dismissOverlay, time, spec } = useOverlayRuntime();
+    const [isDismissing, setIsDismissing] = useState(false);
+    const placement = cue.placement;
+    const placementStyles = getPlacementStyles(placement);
+    const animationClasses = getAnimationClasses(isEntering, isExiting || isDismissing);
+    // Handle dismiss
+    const handleDismiss = useCallback(() => {
+        setIsDismissing(true);
+        // Wait for exit animation
+        setTimeout(() => {
+            dismissOverlay(cue.id);
+        }, 200);
+    }, [cue.id, dismissOverlay]);
+    // Auto-dismiss based on policy
+    useEffect(() => {
+        if (!cue.dismiss)
+            return;
+        const policy = cue.dismiss;
+        // Check triggers
+        for (const trigger of policy.triggers) {
+            switch (trigger.type) {
+                case 'timeout': {
+                    const timeoutMs = trigger.delayMs ?? 5000;
+                    const timer = setTimeout(handleDismiss, timeoutMs);
+                    return () => clearTimeout(timer);
+                }
+                case 'tap':
+                    // Handled via onClick
+                    break;
+                case 'swipe':
+                    // Would need gesture handling - simplified for now
+                    break;
+                case 'action':
+                    // Dismiss on action is handled in ActionRouter
+                    break;
+            }
+        }
+    }, [cue.dismiss, handleDismiss]);
+    // Handle tap dismiss
+    const handleClick = useCallback(() => {
+        if (cue.dismiss?.triggers.some((t) => t.type === 'tap')) {
+            handleDismiss();
+        }
+    }, [cue.dismiss, handleDismiss]);
+    return (React.createElement("div", { "data-cue-id": cue.id, className: `overlay-cue ${animationClasses}`, style: placementStyles, onClick: handleClick },
+        React.createElement(LayoutRenderer, { node: cue.layout, nodeKey: cue.id })));
+}
+/**
+ * Renders all visible cues from the runtime.
+ */
+export function OverlayCueContainer() {
+    const { visibleCues } = useOverlayRuntime();
+    return (React.createElement("div", { className: "overlay-cue-container absolute inset-0 pointer-events-none" }, visibleCues.map((cue) => (React.createElement("div", { key: cue.id, className: "pointer-events-auto" },
+        React.createElement(OverlayCueRenderer, { cue: cue, isEntering: true }))))));
+}
+export default OverlayCueRenderer;

package/dist/spec/renderer/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Renderer Module Index
+ *
+ * Exports all renderer components and utilities.
+ */
+export { LayoutRenderer, LayoutTree, type LayoutRendererProps, } from './LayoutRenderer';
+export { resolveBindingPath, resolveBinding, resolveProps, resolvePropValue, createBindingContext, type BindingContext, } from './BindingResolver';
+export { CaptionTrackRenderer, useActiveCaption, type CaptionTrackProps, } from './CaptionTrack';
+export { OverlayCueRenderer, OverlayCueContainer, type OverlayCueRendererProps, } from './OverlayCue';
+//# sourceMappingURL=index.d.ts.map

package/dist/spec/renderer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spec/renderer/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,cAAc,EACd,UAAU,EACV,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAC"}

package/dist/spec/renderer/index.js

@@ -0,0 +1,13 @@
+/**
+ * Renderer Module Index
+ *
+ * Exports all renderer components and utilities.
+ */
+// Layout rendering
+export { LayoutRenderer, LayoutTree, } from './LayoutRenderer';
+// Binding resolution
+export { resolveBindingPath, resolveBinding, resolveProps, resolvePropValue, createBindingContext, } from './BindingResolver';
+// Caption rendering
+export { CaptionTrackRenderer, useActiveCaption, } from './CaptionTrack';
+// Overlay cue rendering
+export { OverlayCueRenderer, OverlayCueContainer, } from './OverlayCue';

package/dist/spec/runtime/ActionRouter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ActionRouter
+ *
+ * Routes spec actions to appropriate handlers.
+ */
+import type { Action, SpecEvent, SpecCommand } from '../types';
+import type { StateManager } from './StateManager';
+export interface ActionContext {
+    /** State manager for local state */
+    stateManager: StateManager;
+    /** Emit event to host */
+    emitEvent: (event: SpecEvent) => void;
+    /** Send command (internal) */
+    sendCommand?: (command: SpecCommand) => void;
+    /** Navigate to full page */
+    navigateToPage?: () => void;
+    /** Open a tile */
+    openTile?: (tileId: string) => void;
+    /** Dismiss current overlay */
+    dismissOverlay?: (overlayId: string) => void;
+}
+export interface ActionRouter {
+    execute(action: Action): Promise<void>;
+}
+/**
+ * Creates an action router for handling spec actions.
+ */
+export declare function createActionRouter(context: ActionContext): ActionRouter;
+/**
+ * Helper to check if a value is an action.
+ */
+export declare function isActionValue(value: unknown): value is Action;
+//# sourceMappingURL=ActionRouter.d.ts.map

package/dist/spec/runtime/ActionRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionRouter.d.ts","sourceRoot":"","sources":["../../../src/spec/runtime/ActionRouter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAc,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,YAAY,EAAE,YAAY,CAAC;IAE3B,yBAAyB;IACzB,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAEtC,8BAA8B;IAC9B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAE7C,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAE5B,kBAAkB;IAClB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC,8BAA8B;IAC9B,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CA+EvE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D"}

package/dist/spec/runtime/ActionRouter.js

@@ -0,0 +1,84 @@
+/**
+ * ActionRouter
+ *
+ * Routes spec actions to appropriate handlers.
+ */
+/**
+ * Creates an action router for handling spec actions.
+ */
+export function createActionRouter(context) {
+    const { stateManager, emitEvent, navigateToPage, openTile, dismissOverlay } = context;
+    const handlers = {
+        async emit(action) {
+            const payload = action.payload ?? {};
+            const event = payload.event;
+            const data = payload.data;
+            if (event) {
+                emitEvent({ type: event, payload: data });
+            }
+        },
+        async setState(action) {
+            const payload = action.payload ?? {};
+            const key = payload.key;
+            const value = payload.value;
+            if (key !== undefined) {
+                stateManager.setState(key, value);
+            }
+        },
+        async sequence(action) {
+            const actions = (action.payload?.actions ?? []);
+            for (const subAction of actions) {
+                await execute(subAction);
+            }
+        },
+        async openTile(action) {
+            const tileId = action.payload?.tileId;
+            if (tileId && openTile) {
+                openTile(tileId);
+            }
+        },
+        async openFull() {
+            if (navigateToPage) {
+                navigateToPage();
+            }
+        },
+        async navigate(action) {
+            const url = action.payload?.url;
+            const target = action.payload?.target ?? '_blank';
+            if (url) {
+                window.open(url, target);
+            }
+        },
+        async dismiss(action) {
+            const overlayId = action.payload?.overlayId;
+            if (overlayId && dismissOverlay) {
+                dismissOverlay(overlayId);
+            }
+        },
+        async fx(action) {
+            // Effects like confetti, sound, haptics
+            const effect = action.payload?.effect;
+            console.log('FX effect:', effect, action.payload);
+            // TODO: Implement actual effects
+        },
+    };
+    const execute = async (action) => {
+        const handler = handlers[action.$action];
+        if (handler) {
+            await handler(action);
+        }
+        else {
+            console.warn(`Unknown action type: ${action.$action}`);
+        }
+    };
+    return { execute };
+}
+/**
+ * Helper to check if a value is an action.
+ */
+export function isActionValue(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '$action' in value &&
+        typeof value.$action === 'string');
+}

package/dist/spec/runtime/OverlayRuntime.d.ts

@@ -0,0 +1,84 @@
+/**
+ * OverlayRuntime
+ *
+ * Main runtime provider for the overlay spec system.
+ * Manages state, time sync, and action routing.
+ */
+import { type ReactNode } from 'react';
+import type { OverlaySpec, SpecEvent, Action, OverlayCue } from '../types';
+import { type StateSnapshot } from './StateManager';
+import { type TimeState, type VideoTimeSource } from './TimeSync';
+export interface OverlayRuntimeContextValue {
+    /** The overlay spec */
+    spec: OverlaySpec;
+    /** Current time state */
+    time: TimeState;
+    /** Local state snapshot */
+    state: StateSnapshot;
+    /** Host-provided data */
+    data: Record<string, unknown>;
+    /** User context */
+    ctx: Record<string, unknown>;
+    /** Execute an action */
+    executeAction: (action: Action) => Promise<void>;
+    /** Get current state value */
+    getStateValue: (key: string) => unknown;
+    /** Set state value */
+    setStateValue: (key: string, value: unknown) => void;
+    /** Get visible overlay cues */
+    visibleCues: OverlayCue[];
+    /** Dismissed overlay IDs */
+    dismissedIds: Set<string>;
+    /** Dismiss an overlay */
+    dismissOverlay: (id: string) => void;
+}
+export interface OverlayRuntimeProps {
+    /** The overlay spec to render */
+    spec: OverlaySpec;
+    /** Video time source for sync */
+    timeSource?: VideoTimeSource | null;
+    /** Host-provided data bindings */
+    data?: Record<string, unknown>;
+    /** User context (userId, etc.) */
+    ctx?: Record<string, unknown>;
+    /** Event callback for host */
+    onEvent?: (event: SpecEvent) => void;
+    /** Navigate to page callback */
+    onNavigateToPage?: () => void;
+    /** Open tile callback */
+    onOpenTile?: (tileId: string) => void;
+    /** Children to render */
+    children?: ReactNode;
+}
+export declare function OverlayRuntime({ spec, timeSource, data, ctx, onEvent, onNavigateToPage, onOpenTile, children, }: OverlayRuntimeProps): JSX.Element;
+/**
+ * Hook to access the overlay runtime context.
+ */
+export declare function useOverlayRuntime(): OverlayRuntimeContextValue;
+/**
+ * Hook to get current time state.
+ */
+export declare function useRuntimeTime(): TimeState;
+/**
+ * Hook to get local state.
+ */
+export declare function useRuntimeState(): StateSnapshot;
+/**
+ * Hook to get host data.
+ */
+export declare function useRuntimeData<T = unknown>(key: string): T | undefined;
+/**
+ * Hook to execute actions.
+ */
+export declare function useRuntimeAction(): (action: Action) => Promise<void>;
+interface EvaluationContext {
+    state: StateSnapshot;
+    data: Record<string, unknown>;
+    ctx: Record<string, unknown>;
+}
+declare function resolveBinding(path: string, context: EvaluationContext): unknown;
+declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+declare function evaluateCondition(condition: unknown, context: EvaluationContext): boolean;
+export { evaluateCondition, resolveBinding, getNestedValue };
+export type { EvaluationContext };
+//# sourceMappingURL=OverlayRuntime.d.ts.map

package/dist/spec/runtime/OverlayRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OverlayRuntime.d.ts","sourceRoot":"","sources":["../../../src/spec/runtime/OverlayRuntime.tsx"],"names":[],"mappings":"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"}

package/dist/spec/runtime/OverlayRuntime.js

@@ -0,0 +1,216 @@
+/**
+ * OverlayRuntime
+ *
+ * Main runtime provider for the overlay spec system.
+ * Manages state, time sync, and action routing.
+ */
+import React, { createContext, useContext, useEffect, useMemo, useCallback, } from 'react';
+import { createStateManager, useSpecState } from './StateManager';
+import { createActionRouter } from './ActionRouter';
+import { useTimeSync, isTimeInWindow } from './TimeSync';
+const OverlayRuntimeContext = createContext(null);
+// =============================================================================
+// Provider Component
+// =============================================================================
+export function OverlayRuntime({ spec, timeSource = null, data = {}, ctx = {}, onEvent, onNavigateToPage, onOpenTile, children, }) {
+    // Create state manager
+    const stateManager = useMemo(() => createStateManager(spec.state?.local ?? {}), [spec.id] // Reset when spec ID changes
+    );
+    // Track dismissed overlays
+    const [dismissedIds, setDismissedIds] = React.useState(new Set());
+    const dismissOverlay = useCallback((id) => {
+        setDismissedIds((prev) => new Set([...prev, id]));
+    }, []);
+    // Get current state
+    const state = useSpecState(stateManager);
+    // Time sync
+    const time = useTimeSync(timeSource, spec.sync);
+    // Event emitter
+    const emitEvent = useCallback((event) => {
+        onEvent?.(event);
+    }, [onEvent]);
+    // Create action router
+    const actionRouter = useMemo(() => {
+        const actionContext = {
+            stateManager,
+            emitEvent,
+            navigateToPage: onNavigateToPage,
+            openTile: onOpenTile,
+            dismissOverlay,
+        };
+        return createActionRouter(actionContext);
+    }, [stateManager, emitEvent, onNavigateToPage, onOpenTile, dismissOverlay]);
+    // Execute action helper
+    const executeAction = useCallback(async (action) => {
+        await actionRouter.execute(action);
+    }, [actionRouter]);
+    // State accessors
+    const getStateValue = useCallback((key) => stateManager.getState(key), [stateManager]);
+    const setStateValue = useCallback((key, value) => stateManager.setState(key, value), [stateManager]);
+    // Calculate visible cues
+    const visibleCues = useMemo(() => {
+        const cues = spec.tracks?.overlays ?? [];
+        return cues.filter((cue) => {
+            // Check if dismissed
+            if (dismissedIds.has(cue.id)) {
+                return false;
+            }
+            // Check time window
+            const inWindow = isTimeInWindow(time.timeMs, cue.window?.startMs, cue.window?.endMs, spec.sync?.toleranceMs ?? 100);
+            if (!inWindow) {
+                return false;
+            }
+            // Check visibility condition
+            if (cue.visibleWhen) {
+                const visible = evaluateCondition(cue.visibleWhen, { state, data, ctx });
+                if (!visible) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }, [spec.tracks?.overlays, time.timeMs, spec.sync?.toleranceMs, state, data, ctx, dismissedIds]);
+    // Reset dismissed IDs when spec changes
+    useEffect(() => {
+        setDismissedIds(new Set());
+    }, [spec.id]);
+    const value = {
+        spec,
+        time,
+        state,
+        data,
+        ctx,
+        executeAction,
+        getStateValue,
+        setStateValue,
+        visibleCues,
+        dismissedIds,
+        dismissOverlay,
+    };
+    return (React.createElement(OverlayRuntimeContext.Provider, { value: value }, children));
+}
+// =============================================================================
+// Hooks
+// =============================================================================
+/**
+ * Hook to access the overlay runtime context.
+ */
+export function useOverlayRuntime() {
+    const context = useContext(OverlayRuntimeContext);
+    if (!context) {
+        throw new Error('useOverlayRuntime must be used within an OverlayRuntime provider');
+    }
+    return context;
+}
+/**
+ * Hook to get current time state.
+ */
+export function useRuntimeTime() {
+    const { time } = useOverlayRuntime();
+    return time;
+}
+/**
+ * Hook to get local state.
+ */
+export function useRuntimeState() {
+    const { state } = useOverlayRuntime();
+    return state;
+}
+/**
+ * Hook to get host data.
+ */
+export function useRuntimeData(key) {
+    const { data } = useOverlayRuntime();
+    return data[key];
+}
+/**
+ * Hook to execute actions.
+ */
+export function useRuntimeAction() {
+    const { executeAction } = useOverlayRuntime();
+    return executeAction;
+}
+function resolveBinding(path, context) {
+    const parts = path.split('.');
+    const scope = parts[0];
+    const key = parts.slice(1).join('.');
+    switch (scope) {
+        case 'local':
+            return context.state[key];
+        case 'data':
+            return getNestedValue(context.data, key);
+        case 'ctx':
+            return getNestedValue(context.ctx, key);
+        default:
+            return undefined;
+    }
+}
+function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key) => {
+        if (current && typeof current === 'object') {
+            return current[key];
+        }
+        return undefined;
+    }, obj);
+}
+function evaluateCondition(condition, context) {
+    if (typeof condition !== 'object' || condition === null) {
+        return Boolean(condition);
+    }
+    const cond = condition;
+    // Binding condition - check truthiness
+    if ('$bind' in cond) {
+        const value = resolveBinding(cond.$bind, context);
+        return Boolean(value);
+    }
+    // Comparison condition
+    if ('op' in cond && 'left' in cond && 'right' in cond) {
+        const left = resolveBindingValue(cond.left, context);
+        const right = resolveBindingValue(cond.right, context);
+        switch (cond.op) {
+            case 'eq':
+                return left === right;
+            case 'neq':
+                return left !== right;
+            case 'gt':
+                return left > right;
+            case 'gte':
+                return left >= right;
+            case 'lt':
+                return left < right;
+            case 'lte':
+                return left <= right;
+            case 'contains':
+                if (Array.isArray(left)) {
+                    return left.includes(right);
+                }
+                if (typeof left === 'string') {
+                    return left.includes(String(right));
+                }
+                return false;
+            default:
+                return false;
+        }
+    }
+    // Logical conditions
+    if ('and' in cond) {
+        const conditions = cond.and;
+        return conditions.every((c) => evaluateCondition(c, context));
+    }
+    if ('or' in cond) {
+        const conditions = cond.or;
+        return conditions.some((c) => evaluateCondition(c, context));
+    }
+    if ('not' in cond) {
+        return !evaluateCondition(cond.not, context);
+    }
+    return false;
+}
+function resolveBindingValue(value, context) {
+    if (typeof value === 'object' && value !== null && '$bind' in value) {
+        return resolveBinding(value.$bind, context);
+    }
+    return value;
+}
+// Export evaluation helpers for use in renderer
+export { evaluateCondition, resolveBinding, getNestedValue };

package/dist/spec/runtime/StateManager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * StateManager
+ *
+ * Manages local spec state with React integration.
+ */
+import type { StateConfig } from '../types';
+export type StateSnapshot = Record<string, unknown>;
+export interface StateManager {
+    getSnapshot(): StateSnapshot;
+    subscribe(listener: () => void): () => void;
+    setState(key: string, value: unknown): void;
+    getState(key: string): unknown;
+    reset(): void;
+}
+/**
+ * Creates a state manager for spec local state.
+ */
+export declare function createStateManager(initial?: StateConfig['local']): StateManager;
+/**
+ * Hook to use spec state in components.
+ */
+export declare function useSpecState(manager: StateManager): StateSnapshot;
+/**
+ * Hook to get a specific state value.
+ */
+export declare function useSpecStateValue<T = unknown>(manager: StateManager, key: string): T;
+/**
+ * Hook to get a state setter.
+ */
+export declare function useSpecStateSetter(manager: StateManager): (key: string, value: unknown) => void;
+//# sourceMappingURL=StateManager.d.ts.map

package/dist/spec/runtime/StateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateManager.d.ts","sourceRoot":"","sources":["../../../src/spec/runtime/StateManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,WAAW,IAAI,aAAa,CAAC;IAC7B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,WAAW,CAAC,OAAO,CAAM,GAAG,YAAY,CAkCnF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAMjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAGpF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAO/F"}