@bitcobblers/wod-wiki-lang 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,640 @@
+import { _ as ScriptRuntime, aq as MemoryType, q as IRuntimeBlock, as as MemoryValueOf, ac as DisplayState, at as RoundState, a1 as TimerState, X as IScriptRuntime, F as TypedMemoryReference, a5 as ButtonConfig, K as StackSnapshot } from './browserRuntimeNow-SxxdmtB7.cjs';
+export { az as createBrowserRuntimeNow, aE as getRuntimeNowMs, aH as runtimeNow } from './browserRuntimeNow-SxxdmtB7.cjs';
+import { IMetricSource, IOutputStatement, MetricContainer, TimeSpan } from '@bitcobblers/wod-wiki-core';
+import React$1, { ReactNode } from 'react';
+
+/**
+ * useRuntimeExecution - Custom React hook for managing ScriptRuntime execution
+ *
+ * Encapsulates execution logic, interval management, and lifecycle cleanup.
+ *
+ * Architecture Decision:
+ * - Fixed 20ms tick rate (50 ticks per second)
+ * - No speed control (removed for simplicity)
+ * - Automatic cleanup on unmount
+ * - Reusable across components
+ */
+
+/**
+ * Execution status states
+ */
+type ExecutionStatus = 'idle' | 'running' | 'paused' | 'completed' | 'error';
+/**
+ * Return type for useRuntimeExecution hook
+ */
+interface UseRuntimeExecutionReturn {
+    status: ExecutionStatus;
+    elapsedTime: number;
+    stepCount: number;
+    startTime: number | null;
+    start: () => void;
+    pause: () => void;
+    stop: () => void;
+    reset: () => void;
+    step: () => void;
+}
+/**
+ * Manages ScriptRuntime execution lifecycle with fixed 20ms tick rate
+ *
+ * @param runtime - The ScriptRuntime instance to execute (null if not ready)
+ * @returns Object with execution state and control methods
+ */
+declare const useRuntimeExecution: (runtime: ScriptRuntime | null) => UseRuntimeExecutionReturn;
+
+/**
+ * React hook to subscribe to a specific memory type on a block.
+ *
+ * Automatically subscribes when the block or type changes, and
+ * unsubscribes on cleanup. Returns the current value and updates
+ * reactively when behaviors modify the memory.
+ *
+ * @param block The runtime block to subscribe to (can be undefined)
+ * @param type The memory type to subscribe to
+ * @returns The current memory value or undefined
+ *
+ * @example
+ * ```tsx
+ * function TimerComponent({ block }: { block: IRuntimeBlock }) {
+ *   const timerState = useBlockMemory(block, 'time');
+ *
+ *   if (!timerState) return null;
+ *
+ *   return <div>Direction: {timerState.direction}</div>;
+ * }
+ * ```
+ */
+declare function useBlockMemory<T extends MemoryType>(block: IRuntimeBlock | undefined, type: T): MemoryValueOf<T> | undefined;
+/**
+ * Hook for subscribing to timer state from a block.
+ *
+ * @param block The runtime block
+ * @returns The current TimerState or undefined
+ */
+declare function useTimerState(block: IRuntimeBlock | undefined): TimerState | undefined;
+/**
+ * Hook for subscribing to round state from a block.
+ *
+ * @param block The runtime block
+ * @returns The current RoundState or undefined
+ */
+declare function useRoundState(block: IRuntimeBlock | undefined): RoundState | undefined;
+/**
+ * Hook for subscribing to display state from a block.
+ *
+ * @param block The runtime block
+ * @returns The current DisplayState or undefined
+ */
+declare function useDisplayState(block: IRuntimeBlock | undefined): DisplayState | undefined;
+/**
+ * Derived timer display values for UI rendering.
+ */
+interface TimerDisplayValues {
+    /** Total elapsed time in milliseconds */
+    elapsed: number;
+    /** Remaining time in milliseconds (for countdowns) */
+    remaining: number | undefined;
+    /** Whether the timer is currently running (not paused) */
+    isRunning: boolean;
+    /** Timer direction */
+    direction: 'up' | 'down';
+    /** Whether the timer has completed (countdown reached 0) */
+    isComplete: boolean;
+    /** Formatted time string (MM:SS or HH:MM:SS) */
+    formatted: string;
+}
+/**
+ * Hook for derived timer display values.
+ *
+ * Computes elapsed time, remaining time, and formatted display strings
+ * from the raw timer state. Uses requestAnimationFrame for smooth 60fps
+ * updates when the timer is running.
+ *
+ * Consolidated with useTimerElapsed - both now share calculateDuration utility.
+ *
+ * @param block The runtime block
+ * @returns Derived timer display values or null if no timer
+ *
+ * @example
+ * ```tsx
+ * function TimerDisplay({ block }: { block: IRuntimeBlock }) {
+ *   const display = useTimerDisplay(block);
+ *
+ *   if (!display) return <div>No timer</div>;
+ *
+ *   return (
+ *     <div>
+ *       <span>{display.formatted}</span>
+ *       {display.direction === 'down' && (
+ *         <span>{formatTime(display.remaining ?? 0)} remaining</span>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTimerDisplay(block: IRuntimeBlock | undefined): TimerDisplayValues | null;
+/**
+ * Derived round display values for UI rendering.
+ */
+interface RoundDisplayValues {
+    /** Current round number */
+    current: number;
+    /** Total rounds (undefined for unbounded) */
+    total: number | undefined;
+    /** Formatted round label (e.g., "Round 3 of 5") */
+    label: string;
+    /** Progress as a fraction 0-1 (undefined for unbounded) */
+    progress: number | undefined;
+}
+/**
+ * Hook for derived round display values.
+ *
+ * @param block The runtime block
+ * @returns Derived round display values or null if no rounds
+ */
+declare function useRoundDisplay(block: IRuntimeBlock | undefined): RoundDisplayValues | null;
+/**
+ * Hook for subscribing to the display metrics source from a block.
+ *
+ * Returns the `IMetricSource` interface from the block's `'metric:display'`
+ * memory entry (`DisplayMetricMemory`). The returned source provides
+ * precedence-resolved metric that update reactively when the underlying
+ * metric memory or runtime state changes.
+ *
+ * This is the primary hook for UI components that need to render metrics
+ * from a runtime block with proper origin precedence (user > runtime > compiler > parser).
+ *
+ * @param block The runtime block (can be undefined)
+ * @returns The IMetricSource for the block, or undefined if no metrics:display memory
+ *
+ * @example
+ * ```tsx
+ * function BlockView({ block }: { block: IRuntimeBlock }) {
+ *   const source = useFragmentSource(block);
+ *   if (!source) return null;
+ *
+ *   const metrics = source.getDisplayMetrics();
+ *   return <MetricVisualizer metric={metric} />;
+ * }
+ * ```
+ */
+declare function useFragmentSource(block: IRuntimeBlock | undefined): IMetricSource | undefined;
+
+/**
+ * Data structure returned by useOutputStatements hook
+ * Consolidated from separate implementations in runtime/hooks and clock/hooks
+ */
+interface OutputStatementsData {
+    /** All output statements sorted by start time */
+    outputs: IOutputStatement[];
+    /** Outputs indexed by ID for quick lookup */
+    byId: Map<number, IOutputStatement>;
+    /** Outputs indexed by sourceBlockKey */
+    byBlockKey: Map<string, IOutputStatement[]>;
+    /** Segment outputs (timed execution segments) */
+    segments: IOutputStatement[];
+    /** Completion outputs */
+    completions: IOutputStatement[];
+    /** Metric outputs */
+    metrics: IOutputStatement[];
+}
+/**
+ * React hook that subscribes to output statement updates from a runtime.
+ *
+ * Unified hook that works with or without a runtime parameter:
+ * - useOutputStatements() - uses runtime from context
+ * - useOutputStatements(runtime) - uses provided runtime parameter
+ *
+ * Returns enriched OutputStatementsData with indexed maps for performance.
+ * Consolidated from separate runtime/hooks and clock/hooks implementations.
+ *
+ * @param runtime Optional runtime instance. If not provided, uses context.
+ * @returns OutputStatementsData containing outputs and indexed maps
+ *
+ * @example
+ * ```tsx
+ * // With context (default)
+ * const data = useOutputStatements();
+ *
+ * // With explicit runtime parameter
+ * const data = useOutputStatements(myRuntime);
+ * ```
+ */
+declare function useOutputStatements(runtime?: IScriptRuntime | null): OutputStatementsData;
+/**
+ * Live Tier-2 (running-total) snapshot for display during an active session.
+ *
+ * Returns the analytics engine's current projection set — totals like total
+ * volume / distance / load, recomputed per segment. These values are ephemeral:
+ * they are shown live but never persisted; only the finalized values reach the
+ * records after the WOD completes. Reuses the output subscription as its change
+ * signal (the snapshot is replaced, not appended).
+ */
+declare function useLiveAnalytics(runtime?: IScriptRuntime | null): IOutputStatement[];
+/**
+ * Hook to get a specific output by ID
+ */
+declare function useOutputStatement(runtime: IScriptRuntime | null, id: number | null): IOutputStatement | undefined;
+/**
+ * Hook to get outputs for a specific block
+ */
+declare function useBlockOutputs(runtime: IScriptRuntime | null, blockKey: string | null): IOutputStatement[];
+/**
+ * Hook to compute output hierarchy (parent-child relationships) based on stackLevel
+ */
+declare function useOutputHierarchy(runtime: IScriptRuntime | null): Map<number, number>;
+
+/**
+ * React hook for subscribing to memory reference changes.
+ *
+ * This hook automatically manages the subscription lifecycle:
+ * - Subscribes when the component mounts or when memoryRef changes
+ * - Unsubscribes when the component unmounts or when memoryRef changes
+ * - Returns the current value and updates when the memory changes
+ *
+ * @param memoryRef The memory reference to subscribe to (can be undefined)
+ * @returns The current value from the memory reference, or undefined if not available
+ *
+ * @example
+ * ```tsx
+ * const runtime = useScriptRuntime();
+ * const timeSpansRef = runtime.memory.search({
+ *   type: 'timer-time-spans',
+ *   ownerId: blockKey
+ * })[0] as TypedMemoryReference<TimeSpan[]>;
+ *
+ * const timeSpans = useMemorySubscription(timeSpansRef);
+ * ```
+ */
+declare function useMemorySubscription<T>(memoryRef: TypedMemoryReference<T> | undefined): T | undefined;
+
+/**
+ * Result of the next-preview resolution.
+ *
+ * `metrics` contains the display metrics for the next child that
+ * will be pushed by the deepest block on the stack that has a
+ * `metrics:next` memory location.
+ */
+interface NextPreview {
+    /** Fragments describing the next child to be executed */
+    metrics: MetricContainer;
+    /** The block that owns this preview (the parent that will push the child) */
+    block: IRuntimeBlock;
+}
+/**
+ * Hook that resolves the "Up Next" preview from the runtime stack.
+ *
+ * Walks the stack from leaf (index 0) to root, finding the first block
+ * that has a non-empty `metrics:next` memory location. This gives the
+ * deepest (most specific) preview of what's coming next.
+ *
+ * The hook subscribes to `metrics:next` memory changes on all stack
+ * blocks, so it re-renders when the preview updates (e.g., after a
+ * child completes and the next child is queued).
+ *
+ * @returns NextPreview if any block has a next preview, or null
+ *
+ * @example
+ * ```tsx
+ * function UpNextCard() {
+ *   const preview = useNextPreview();
+ *   if (!preview) return <span>End of session</span>;
+ *
+ *   return <MetricSourceRow metric={preview.metrics} />;
+ * }
+ * ```
+ */
+declare function useNextPreview(): NextPreview | null;
+
+type FragmentSourceStatus = 'pending' | 'active' | 'completed' | 'failed' | 'skipped';
+interface FragmentSourceEntry {
+    source: IMetricSource;
+    depth: number;
+    isLeaf?: boolean;
+    isHeader?: boolean;
+    isLinked?: boolean;
+    status?: FragmentSourceStatus;
+    label?: string;
+    metricGroups?: any[];
+}
+/**
+ * Represents a timer on the stack with its owning block context.
+ */
+interface StackTimerEntry {
+    /** The block that owns this timer */
+    block: IRuntimeBlock;
+    /** The timer state from block memory */
+    timer: TimerState;
+    /** Whether this timer is pinned to the primary display */
+    isPinned: boolean;
+}
+/**
+ * Hook that scans the runtime stack for all blocks with timer memory.
+ * Returns timer entries ordered from bottom of stack (index 0) to top.
+ *
+ * Timer data is read directly from block memory via lock.getMemory('time').
+ * When a block is popped from the stack, its memory subscriptions are cleaned
+ * up automatically, and the stack event triggers a re-render here.
+ *
+ * @returns Array of stack timer entries
+ */
+declare function useStackTimers(): StackTimerEntry[];
+/**
+ * Determines which timer should be displayed as the primary (big) timer.
+ *
+ * Pin Resolution Strategy:
+ * 1. If the top-of-stack block is a Rest block, its timer is ALWAYS primary.
+ *    Rest countdowns should be front-and-center so users see time remaining.
+ * 2. Otherwise, find the LOWEST (root-closest) block with role === 'primary'.
+ *    This lets parent blocks (AMRAP, EMOM) keep their timer pinned while
+ *    child exercises execute beneath them.
+ * 3. If no pinned timer exists, use the leaf (top-of-stack) timer.
+ *
+ * @returns The primary timer entry, or undefined if no timers on stack
+ */
+declare function usePrimaryTimer(): StackTimerEntry | undefined;
+/**
+ * Returns all timers that are NOT the primary timer.
+ * These are displayed as secondary/context timers in the UI.
+ */
+declare function useSecondaryTimers(): StackTimerEntry[];
+/**
+ * Aggregates control buttons from all blocks on the stack.
+ *
+ * Button Resolution Strategy:
+ * - Collect pinned buttons (isPinned === true) from ALL stack levels
+ * - Collect non-pinned buttons from the TOP block only
+ * - Deduplicate by button ID (pinned take precedence)
+ *
+ * When a block is popped, its buttons are automatically removed because
+ * the stack subscription triggers a re-scan.
+ *
+ * @returns Array of active button configurations
+ */
+declare function useActiveControls(): ButtonConfig[];
+/**
+ * Represents a metrics source on the stack with layout context.
+ *
+ * Extends the generic FragmentSourceEntry with a block reference for
+ * runtime-specific scenarios (accessing memory, dispatching events).
+ */
+interface StackFragmentEntry extends FragmentSourceEntry {
+    /** The owning runtime block */
+    block: IRuntimeBlock;
+}
+/**
+ * Hook that converts the runtime stack into an array of IMetricSource entries.
+ *
+ * Each block on the stack with a `'metric:display'` memory entry produces a
+ * `StackFragmentEntry` containing the `IMetricSource` and layout context
+ * (depth, leaf status, label).
+ *
+ * This is the preferred way for UI components to access metrics data from
+ * the stack, replacing `useStackDisplayItems()` which returns `IDisplayItem[]`.
+ *
+ * @returns Array of stack metrics entries, or undefined if no blocks on stack
+ *
+ * @example
+ * ```tsx
+ * function StackView() {
+ *   const entries = useStackFragmentSources();
+ *   if (!entries) return null;
+ *
+ *   return entries.map(entry => (
+ *     <MetricVisualizer
+ *       key={entry.source.id}
+ *       metrics={entry.source.getDisplayMetrics()}
+ *     />
+ *   ));
+ * }
+ * ```
+ */
+declare function useStackFragmentSources(): StackFragmentEntry[] | undefined;
+/**
+ * Represents a display entry with list-based memory access.
+ *
+ * Replaces IMetricSource adapter with direct IMetric[][] access.
+ */
+interface StackDisplayEntry {
+    /** The owning runtime block */
+    block: IRuntimeBlock;
+    /** Display rows - each row is an array of metrics */
+    displayRows: MetricContainer[];
+    /** Display label from block */
+    label: string;
+    /** Nesting depth for indentation (0 = root level) */
+    depth: number;
+    /** Whether this is the leaf (most active) entry */
+    isLeaf: boolean;
+    /** Raw metrics groups from block memory (for backward compatibility) */
+    metricGroups?: readonly MetricContainer[];
+}
+/**
+ * Hook that reads list-based memory directly from runtime stack blocks.
+ *
+ * This is the Phase 3 UI migration hook that consumes the list-based memory
+ * API populated by Phase 2 behaviors. It subscribes to all 'metric:display'
+ * memory locations and returns display rows without requiring IMetricSource
+ * adapter layer.
+ *
+ * Each block can have multiple 'metric:display' memory locations (non-unique
+ * tags in list-based API), where each location stores IMetric[]. These
+ * are returned as displayRows: IMetric[][].
+ *
+ * @returns Array of stack display entries, or undefined if no blocks on stack
+ *
+ * @example
+ * ```tsx
+ * function StackView() {
+ *   const entries = useStackDisplayRows();
+ *   if (!entries) return null;
+ *
+ *   return entries.map(entry => (
+ *     <div key={entry.block.key.toString()}>
+ *       {entry.displayRows.map((row, idx) => (
+ *         <MetricSourceRow key={idx} metrics={row} />
+ *       ))}
+ *     </div>
+ *   ));
+ * }
+ * ```
+ */
+declare function useStackDisplayRows(): StackDisplayEntry[] | undefined;
+
+/**
+ * Hook that subscribes to stack snapshots via `runtime.subscribeToStack()`.
+ *
+ * Returns the latest StackSnapshot, which contains:
+ * - `blocks` — current stack (bottom-to-top)
+ * - `affectedBlock` — the block that was pushed/popped
+ * - `depth` — stack depth after the event
+ * - `clockTime` — runtime clock time at event
+ * - `type` — 'push' | 'pop' | 'clear' | 'initial'
+ *
+ * This is the primary hook for UI components that need to react to stack
+ * structural changes. For high-frequency timer updates, subscribe to
+ * block memory separately.
+ *
+ * @returns The latest StackSnapshot
+ *
+ * @example
+ * ```tsx
+ * function StackDisplay() {
+ *   const snapshot = useStackSnapshot();
+ *
+ *   return (
+ *     <div>
+ *       <p>Depth: {snapshot.depth}</p>
+ *       {snapshot.blocks.map(block => (
+ *         <div key={block.key.toString()}>{block.label}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useStackSnapshot(): StackSnapshot;
+/**
+ * Hook that returns the current stack blocks from the most recent snapshot.
+ * Convenience wrapper over useStackSnapshot().
+ *
+ * @returns Readonly array of blocks currently on the stack
+ */
+declare function useSnapshotBlocks(): readonly IRuntimeBlock[];
+/**
+ * Hook that returns the current (top) block on the stack from the snapshot.
+ * Returns undefined if the stack is empty.
+ *
+ * @returns The top block on the stack, or undefined if empty
+ */
+declare function useSnapshotCurrentBlock(): IRuntimeBlock | undefined;
+
+/**
+ * Result from useTimerElapsed hook.
+ */
+interface UseTimerElapsedResult {
+    elapsed: number;
+    isRunning: boolean;
+    timeSpans: readonly TimeSpan[];
+}
+/**
+ * Hook to calculate elapsed time for a timer block by key.
+ *
+ * This hook uses the unified TimerState from runtime memory to provide
+ * real-time elapsed time calculation. It polls for updates when the timer
+ * is running to show current time, but only subscribes to memory changes
+ * for start/stop/pause/resume events.
+ *
+ * ## When to Use This Hook
+ *
+ * Use this hook when your component receives a `blockKey: string` from the
+ * display stack system. This is the standard integration pattern for:
+ * - ClockAnchor
+ * - DigitalClock
+ * - Display stack consumers
+ *
+ * ## When to Use useTimerDisplay Instead
+ *
+ * If you have direct access to an `IRuntimeBlock` reference (e.g., from
+ * `runtime.stack.current()`), prefer `useTimerDisplay(block)` which provides
+ * formatted time strings and richer display values.
+ *
+ * ## Features
+ * - Zero polling for completed timers
+ * - Subscription-based updates for state changes
+ * - 60fps animation frame updates when running
+ *
+ * @param blockKey The block key to track elapsed time for
+ * @returns Object with elapsed time, running state, and time spans
+ *
+ * @example
+ * ```tsx
+ * // Display stack integration (this hook)
+ * function KeyBasedTimer({ blockKey }: { blockKey: string }) {
+ *   const { elapsed, isRunning } = useTimerElapsed(blockKey);
+ *   const formatted = formatMs(elapsed);
+ *   return <div className={isRunning ? 'running' : ''}>{formatted}</div>;
+ * }
+ *
+ * // Direct block access (use useTimerDisplay instead)
+ * function BlockTimer({ block }: { block: IRuntimeBlock }) {
+ *   const display = useTimerDisplay(block);
+ *   return <div>{display?.formatted}</div>;
+ * }
+ * ```
+ */
+declare function useTimerElapsed(blockKey: string): UseTimerElapsedResult;
+
+interface ScriptRuntimeProviderProps {
+    runtime: IScriptRuntime;
+    children: ReactNode;
+}
+/**
+ * Provides IScriptRuntime context to child components.
+ * Must wrap any components that need access to runtime memory or state.
+ *
+ * @example
+ * ```tsx
+ * const runtime = new ScriptRuntime();
+ * const script = parseWorkout('For Time: 30 Jumping Jacks');
+ * runtime.execute(script);
+ *
+ * return (
+ *   <ScriptRuntimeProvider runtime={runtime}>
+ *     <ClockAnchor blockKey="block-001" />
+ *   </ScriptRuntimeProvider>
+ * );
+ * ```
+ */
+declare const ScriptRuntimeProvider: React.FC<ScriptRuntimeProviderProps>;
+/**
+ * Hook to access the IScriptRuntime from context.
+ * Must be used within a ScriptRuntimeProvider.
+ *
+ * @throws Error if called outside ScriptRuntimeProvider
+ * @returns IScriptRuntime instance
+ */
+declare function useScriptRuntime(): IScriptRuntime;
+
+interface BlockTimerDisplayProps {
+    /** The runtime block to display timer for */
+    block: IRuntimeBlock | undefined;
+    /** Optional CSS class name */
+    className?: string;
+    /** Show round information if available */
+    showRounds?: boolean;
+    /** Compact mode for smaller displays */
+    compact?: boolean;
+}
+/**
+ * BlockTimerDisplay - Timer display using new behavior-based hooks.
+ *
+ * This component demonstrates the preferred pattern for displaying timer
+ * state from runtime blocks using the new useTimerDisplay and useRoundDisplay
+ * hooks.
+ *
+ * ## Features
+ * - 60fps animation for running timers
+ * - Automatic format detection (countdown vs countup)
+ * - Round display integration
+ * - Zero polling for completed timers
+ *
+ * ## Usage
+ *
+ * When you have direct access to an IRuntimeBlock (e.g., from the stack),
+ * use this component:
+ *
+ * \\\	sx
+ * const block = runtime.stack.current();
+ * return <BlockTimerDisplay block={block} showRounds />;
+ * \\\
+ *
+ * For display stack integration where you only have a blockKey string,
+ * continue using DigitalClock or ClockAnchor with useTimerElapsed.
+ *
+ * @see useTimerDisplay
+ * @see useRoundDisplay
+ */
+declare const BlockTimerDisplay: React$1.FC<BlockTimerDisplayProps>;
+
+export { BlockTimerDisplay, type BlockTimerDisplayProps, type ExecutionStatus, type FragmentSourceEntry, type FragmentSourceStatus, type NextPreview, type OutputStatementsData, type RoundDisplayValues, ScriptRuntimeProvider, type ScriptRuntimeProviderProps, type StackDisplayEntry, type StackFragmentEntry, type StackTimerEntry, type TimerDisplayValues, type UseRuntimeExecutionReturn, type UseTimerElapsedResult, useActiveControls, useBlockMemory, useBlockOutputs, useDisplayState, useFragmentSource, useLiveAnalytics, useMemorySubscription, useNextPreview, useOutputHierarchy, useOutputStatement, useOutputStatements, usePrimaryTimer, useRoundDisplay, useRoundState, useRuntimeExecution, useScriptRuntime, useSecondaryTimers, useSnapshotBlocks, useSnapshotCurrentBlock, useStackDisplayRows, useStackFragmentSources, useStackSnapshot, useStackTimers, useTimerDisplay, useTimerElapsed, useTimerState };