@bitcobblers/wod-wiki-lang 0.1.5 → 0.1.8

package/dist/index.d.cts

@@ -1880,6 +1880,58 @@ interface IRuntimeBlockStrategy {
     apply(builder: BlockBuilder, statements: ICodeStatement[], runtime: IRuntimeContext): void;
 }
 
+/**
+ * A subscription that receives runtime state updates.
+ *
+ * Implementations determine what happens with the data:
+ * - LocalRuntimeSubscription updates the workbench store (local UI)
+ * - ChromecastRuntimeSubscription serializes and sends over RPC transport
+ *
+ * Multiple subscriptions can be active simultaneously. The SubscriptionManager
+ * fans out stack snapshots and output statements to all registered subscriptions.
+ */
+interface IRuntimeSubscription {
+    /** Unique identifier for add/remove tracking */
+    readonly id: string;
+    /**
+     * Called when a stack mutation occurs (push/pop/clear/initial).
+     * The snapshot contains the full block list, the affected block, and timing.
+     */
+    onStackSnapshot(snapshot: StackSnapshot): void;
+    /**
+     * Called when an output statement is emitted (block unmount, milestone, etc.).
+     */
+    onOutput(output: IOutputStatement): void;
+    /**
+     * Clean up resources held by this subscription (unsubscribe listeners, close channels, etc.).
+     */
+    dispose(): void;
+}
+
+/**
+ * Chromecast-specific subscription interface that extends IRuntimeSubscription
+ * with analytics summary functionality.
+ *
+ * Only ChromecastRuntimeSubscription implements this interface — local
+ * subscriptions do not support analytics summary.
+ */
+interface ICastSubscription extends IRuntimeSubscription {
+    /**
+     * Send analytics summary with projection results to Chromecast review.
+     * Called by browser when workout completes to show focused review.
+     */
+    sendAnalyticsSummary(projections: Array<{
+        name: string;
+        value: number;
+        unit: string;
+        metricType?: string;
+    }>, totalDurationMs: number, completedSegments: number): void;
+}
+/**
+ * Type guard to check if a subscription supports Chromecast analytics.
+ */
+declare function isCastSubscription(s: IRuntimeSubscription): s is ICastSubscription;
+
 /**
  * Action that pushes a compiled block onto the runtime stack.
  * Used by behaviors to add child blocks for execution.
@@ -3005,6 +3057,274 @@ declare const PRODUCTION_STRATEGIES: readonly IRuntimeBlockStrategy[];
  */
 declare function createCompiler(strategies?: IRuntimeBlockStrategy[]): JitCompiler;
 
+type ExecutionStatus = 'idle' | 'executing' | 'paused' | 'completed' | 'error';
+type BlockType = 'workout' | 'group' | 'timer' | 'rounds' | 'effort' | 'exercise' | 'custom';
+type BlockStatus = 'pending' | 'active' | 'running' | 'complete' | 'error';
+type MemoryType = 'metric' | 'timer-state' | 'loop-state' | 'group-state' | 'handler' | 'span' | 'unknown';
+type MemoryGrouping = 'owner' | 'type' | 'none';
+interface MetricValue {
+    value: any;
+    unit?: string;
+    formatted: string;
+}
+/**
+ * Benchmarking metrics for runtime operations.
+ */
+interface BenchmarkMetrics {
+    snapshotCreationTime: number;
+    renderTime: number;
+    memoryUsage?: number;
+    frameRate?: number;
+}
+/**
+ * UI-friendly representation of IRuntimeBlock
+ */
+interface RuntimeStackBlock {
+    key: string;
+    blockType: BlockType;
+    parentKey?: string;
+    children: string[];
+    depth: number;
+    label: string;
+    color: string;
+    icon?: string;
+    isActive: boolean;
+    isComplete: boolean;
+    status: BlockStatus;
+    metric: Record<string, MetricValue>;
+    metrics?: MetricContainer;
+    metricGroups?: MetricContainer[];
+    sourceIds: number[];
+    lineNumber?: number;
+    metadata?: {
+        mountTime?: number;
+        executionTime?: number;
+        iterationCount?: number;
+    };
+}
+/**
+ * UI-friendly representation of memory allocation
+ */
+interface MemoryEntry {
+    id: string;
+    ownerId: string;
+    ownerLabel?: string;
+    type: MemoryType;
+    value: any;
+    valueFormatted: string;
+    label: string;
+    groupLabel?: string;
+    icon?: string;
+    lineNumber?: number;
+    isValid: boolean;
+    isHighlighted: boolean;
+    metadata?: {
+        createdAt?: number;
+        lastModified?: number;
+        accessCount?: number;
+    };
+    references?: string[];
+    referencedBy?: string[];
+}
+/**
+ * Immutable snapshot of runtime state for UI rendering
+ */
+interface ExecutionSnapshot {
+    stack: {
+        blocks: RuntimeStackBlock[];
+        activeIndex: number;
+        depth: number;
+        rootBlockKey?: string;
+    };
+    memory: {
+        entries: MemoryEntry[];
+        groupedByOwner: Map<string, MemoryEntry[]>;
+        groupedByType: Map<string, MemoryEntry[]>;
+        totalEntries: number;
+    };
+    status: ExecutionStatus;
+    metadata: {
+        stepCount: number;
+        elapsedTime: number;
+        lastEvent?: string;
+        lastEventTime?: number;
+        benchmarkMetrics?: BenchmarkMetrics;
+    };
+    timestamp: number;
+}
+/**
+ * Converts ScriptRuntime state to ExecutionSnapshot
+ */
+interface IRuntimeAdapter {
+    createSnapshot(runtime: any): ExecutionSnapshot;
+    extractStackBlocks(runtime: any): RuntimeStackBlock[];
+    extractMemoryEntries(runtime: any): MemoryEntry[];
+    groupMemoryEntries(entries: MemoryEntry[], groupBy: MemoryGrouping): Map<string, MemoryEntry[]>;
+}
+
+/**
+ * Adapter that converts ScriptRuntime state to UI-friendly ExecutionSnapshot
+ */
+declare class RuntimeAdapter implements IRuntimeAdapter {
+    /**
+     * Creates immutable snapshot of runtime state for UI rendering
+     */
+    createSnapshot(runtime: IScriptRuntime): ExecutionSnapshot;
+    /**
+     * Extracts RuntimeStackBlocks from runtime stack
+     */
+    extractStackBlocks(runtime: IScriptRuntime): RuntimeStackBlock[];
+    /**
+     * Extracts metrics from block's source statements for unified visualization
+     */
+    private extractBlockFragments;
+    /**
+     * Extracts MemoryEntries from runtime memory
+     */
+    extractMemoryEntries(runtime: IScriptRuntime): MemoryEntry[];
+    /**
+     * Generates a label for a memory entry from its type
+     */
+    private generateMemoryLabelFromType;
+    /**
+     * Groups memory entries by specified grouping strategy
+     */
+    groupMemoryEntries(entries: MemoryEntry[], groupBy: MemoryGrouping): Map<string, MemoryEntry[]>;
+    private determineExecutionStatus;
+    private mapBlockType;
+    private determineBlockStatus;
+    private findParentKey;
+    private findChildrenKeys;
+    private generateBlockLabel;
+    private getBlockColor;
+    private getBlockIcon;
+    private mapMemoryType;
+    private generateOwnerLabel;
+    private formatValue;
+    private generateMemoryLabel;
+    private generateGroupLabel;
+    private getMemoryIcon;
+}
+
+/**
+ * LocalRuntimeSubscription — a no-op subscription that simply receives
+ * stack snapshots and output statements without transforming them.
+ *
+ * This is the "identity" subscription: the SubscriptionManager fans out
+ * runtime events to all subscriptions, and the local one simply consumes
+ * them for any local-side effect (e.g., updating the workbench store).
+ *
+ * An optional callback can be provided for each event type to allow
+ * the consumer to react to state changes.
+ */
+declare class LocalRuntimeSubscription implements IRuntimeSubscription {
+    readonly id: string;
+    private onStackSnapshotCallback?;
+    private onOutputCallback?;
+    constructor(options?: {
+        id?: string;
+        onStackSnapshot?: (snapshot: StackSnapshot) => void;
+        onOutput?: (output: IOutputStatement) => void;
+    });
+    onStackSnapshot(snapshot: StackSnapshot): void;
+    onOutput(output: IOutputStatement): void;
+    dispose(): void;
+}
+
+/**
+ * Provides bidirectional event flow between runtime consumers.
+ *
+ * Implementations determine the transport:
+ * - LocalEventProvider dispatches directly to the local IScriptRuntime
+ * - ChromecastEventProvider sends/receives events over the RPC transport
+ *
+ * This abstracts away whether an event originates locally (button press)
+ * or remotely (Chromecast D-Pad) — the runtime processes both identically.
+ */
+interface IRuntimeEventProvider {
+    /**
+     * Dispatch an event to be processed by the runtime.
+     * For local: calls runtime.handle(event) directly.
+     * For chromecast: serializes and sends over the RPC channel.
+     */
+    dispatch(event: IEvent): void;
+    /**
+     * Listen for incoming events (from remote sources or the runtime event bus).
+     * Returns an unsubscribe function.
+     */
+    onEvent(handler: (event: IEvent) => void): Unsubscribe;
+    /**
+     * Clean up resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * LocalEventProvider — dispatches events directly to the local IScriptRuntime.
+ *
+ * - dispatch(event) → runtime.handle(event), which triggers the event bus
+ *   and executes resulting actions in a single turn.
+ * - onEvent(handler) → registers on the runtime event bus to receive
+ *   all events (using the 'global' callback registration path).
+ */
+declare class LocalEventProvider implements IRuntimeEventProvider {
+    private readonly runtime;
+    private static subscriptionCounter;
+    private unsubscribes;
+    private disposed;
+    constructor(runtime: IScriptRuntime);
+    dispatch(event: IEvent): void;
+    onEvent(handler: (event: IEvent) => void): Unsubscribe;
+    dispose(): void;
+}
+
+/**
+ * SubscriptionManager — fans out runtime stack and output events to
+ * multiple IRuntimeSubscription instances.
+ *
+ * Lifecycle:
+ * 1. Created when a runtime is initialized (by RuntimeLifecycleProvider)
+ * 2. Always holds a LocalRuntimeSubscription for the browser UI
+ * 3. ChromecastRuntimeSubscription added/removed via cast session lifecycle
+ * 4. Disposed when the runtime is disposed
+ *
+ * The manager subscribes once to the runtime's stack and output APIs,
+ * then iterates over all registered subscriptions for each event.
+ */
+declare class SubscriptionManager {
+    private readonly runtime;
+    private subscriptions;
+    private stackUnsub;
+    private outputUnsub;
+    private disposed;
+    constructor(runtime: IScriptRuntime);
+    /**
+     * Register a subscription. If a subscription with the same ID already exists,
+     * the old one is disposed and replaced.
+     *
+     * New subscriptions immediately receive the current stack state and any
+     * existing output statements to catch them up.
+     */
+    add(subscription: IRuntimeSubscription): void;
+    /**
+     * Remove and dispose a subscription by ID.
+     * Returns true if the subscription was found and removed.
+     */
+    remove(id: string): boolean;
+    /**
+     * Check if a subscription with the given ID is registered.
+     */
+    has(id: string): boolean;
+    /**
+     * Get the number of active subscriptions.
+     */
+    get count(): number;
+    /**
+     * Dispose all subscriptions and unsubscribe from the runtime.
+     */
+    dispose(): void;
+}
+
 /**
  * AST for the composed-calculation expression language (spec §2).
  *
@@ -4077,13 +4397,13 @@ declare function toStoredOutputStatement(output: IOutputStatement | OutputStatem
  * Auto-generated build version metadata.
  * Do not edit directly; updated by scripts/stamp-version.ts
  */
-declare const VERSION = "0.1.5";
-declare const GIT_SHA = "8c595e1";
-declare const BUILD_TIME = "2026-08-18T18:07:40.647Z";
+declare const VERSION = "0.1.8";
+declare const GIT_SHA = "52af1e3";
+declare const BUILD_TIME = "2026-08-18T18:19:06.086Z";
 declare const SEMVER: {
-    readonly version: "0.1.5";
-    readonly gitSha: "8c595e1";
-    readonly buildTime: "2026-08-18T18:07:40.647Z";
+    readonly version: "0.1.8";
+    readonly gitSha: "52af1e3";
+    readonly buildTime: "2026-08-18T18:19:06.086Z";
 };
 
-export { AbortSessionAction, type ActionDescriptor, type ActionPrimitive, AnalyticsContext, AnalyticsEngine, type AnalyticsProfileContext, type AnalyticsResult, AnalyticsTransformer, BUILD_TIME, BUILTIN_CALCS, BUNDLED_EFFORT_COUNT, BehaviorContext, BlockContext, BlockLifecycleOptions, CONSUMED_HINTS, CONSUMED_HINT_KEYS, type CalculationDefinition$1 as CalcDefinition, CalcEngine, type CalcOrigin, type CalcScope, type CalculationDefinition as CalculateBlockDefinition, type CalculateBlockParseError, type CalculateBlockParseResult, CalculateBlockProcessor, CalculationRegistry, CardioDialect, ClearChildrenAction, ClimbDialect, type ClimbGradeMetricValue, type ClimbGradeSystem, ClimbMetricType, CompileAndPushBlockAction, CompletionDecision, type CreateAnalyticsEngineOptions, type CreateAnalyticsEngineResult, CrossFitDialect, DAY, DEFAULT_UNRESOLVED_EFFORT_MET, DIM_LENGTH, DIM_MASS, DIM_TIME, DIM_ZERO, type DayRollup, DialectStack, type Dimension, type DurationPrimitive, EFFORT_DATA_METRIC_TYPE, EffortBlock, type EffortBlockConfig, type EffortPrimitive, EffortRegistrySource, EffortResolutionOptions, EffortResolver, EffortResolverOptions, EmitEventAction, EmitSystemOutputAction, ErrorAction, EventBus, type EventHandlerRegistration, ExecutionContext, type FuzzyCandidate, GIT_SHA, HabitsDialect, type HeadingPrimitive, IAnalyticsEngine, type IAnalyticsProfile, IBlockContext, IEffort, IEffortRegistry, IEffortResolver, IEvent, IEventBus, IJitCompiler, type ILookupTable, IMemoryLocation, IMemoryReference, type IMetricPresentationPolicy, INowProvider, IRealtimeProcessor, IRuntimeAction, IRuntimeBehavior, IRuntimeBlock, type IRuntimeBlockStrategy, IRuntimeClock, type IRuntimeFactory, IRuntimeStack, IScript, IScriptRuntime, ISummaryProcessor, InMemoryEffortRegistry, JitCompiler, type LapPrimitive, type LineLocator, type LogLevel, LookupRegistry, MdTimerRuntime, MemoryTag, MemoryTypeEnum, type MetricObjectPrimitive, type MetricPresentationSurface, type MetricPresentationToken, type MetricRenderKind, type MetricTone, MetricVisibility, type MockClock, NextAction, NextEvent, NextEventHandler, OutputEmitter, PREDEFINED_SOUNDS, PRODUCTION_STRATEGIES, type ParseOptions, PlaySoundAction, PopBlockAction, type PredefinedSoundName, ProjectionResult, type PropertyPrimitive, PushBlockAction, PushRestBlockAction, type QuantityPrimitive, RegisterEventHandlerAction, Registry, ResolvedEffort, type ResolvedEffortData, RestBlock, type RestBlockConfig, type RoundsPrimitive, RuntimeBlock, type RuntimeBlockOptions, RuntimeBuilder, type RuntimeButton, RuntimeClock, type RuntimeController, type RuntimeControls, RuntimeError, RuntimeFactory, type RuntimeLogEntry, RuntimeLogger, RuntimeMemory, type RuntimeMemoryLocation, RuntimeObservers, RuntimeStack, SEMVER, STANDARD_UNITS, STORE_CALCS, ScriptRuntime, type SegmentWithMetadata, SessionRootBlock, type SessionRootConfig, SnapshotClock, type SoundBehaviorConfig, type SoundCue, type SoundCueState, type SoundState, type SourceInput, type SpanList, StackObserver, StackSnapshot, StandardAnalyticsProfile, StartSessionAction, type StartSessionOptions, StartWorkoutAction, type StartWorkoutOptions, type SyntaxFacts, type SyntaxMeta, type SyntaxPrimitive, type SyntaxStatement, type TextPrimitive, ThrowError, ThrowErrorAction, TimeSpan, TimerState, TwoPassEffortResolutionProcess, TypedMemoryReference, type UnitDef$1 as UnitDef, type UnitMatch, UnitRegistry, UnitSet, UnitsDialect, UnregisterEventHandlerAction, Unsubscribe, UpdateNextPreviewAction, VERSION, WaitingToStartBlock, WhiteboardScript, WodDialect, YogaDialect, buildTooltip, bundledEfforts, index as calc, calculateElapsed, classifyStatements, closeCurrentSpan, commonFixtureSet, computeColumnLabel, computeLabel, computeWorkloadRollups, createAnalyticsEngineForBlock, createCalcEngine, createCompiler, createDialectStack, createLineLocator, createPolicy as createMetricPresentationPolicy, createMockClock, createParser, dailySessionLoads, dayBucket, dialectRegistry, dialectStack, evaluate, evaluateCalculateDefinitions, extractEffortData, extractMetrics, extractStatements, extractStatementsRaw, extractSyntaxFacts, findBestFuzzyMatch, fixtureBackSquat, fixtureBurpee, fixturePlank, fixtureRowing, fixtureRunning, fixtureUserCustom, fixtureUserOverride, formatDuration, metricsToLabel as fragmentsToLabel, fullFixtureSet, fuseUnits, fuseUnitsInMetrics, getAnalyticsFromLogs, getAnalyticsFromRuntime, getHints, hasHint, hintMetric, hintsToContainer, isTimeLikeMetric, isWithinThreshold, levenshteinDistance, metricPresentation, mutateTimerSpans, normalizeForFuzzy, openSpan, parseCalcLine, parseCalculateBlock, parseExpression, parseScript, readTimer, realtimeProcessorRegistry, resolveDominantOrigin, sharedParser, startSpan, strategyRegistry, summaryProcessorRegistry, toStoredOutputStatement, parser as whiteboardParser, whiteboardScript, whiteboardScriptLanguage };
+export { AbortSessionAction, type ActionDescriptor, type ActionPrimitive, AnalyticsContext, AnalyticsEngine, type AnalyticsProfileContext, type AnalyticsResult, AnalyticsTransformer, BUILD_TIME, BUILTIN_CALCS, BUNDLED_EFFORT_COUNT, BehaviorContext, BlockContext, BlockLifecycleOptions, CONSUMED_HINTS, CONSUMED_HINT_KEYS, type CalculationDefinition$1 as CalcDefinition, CalcEngine, type CalcOrigin, type CalcScope, type CalculationDefinition as CalculateBlockDefinition, type CalculateBlockParseError, type CalculateBlockParseResult, CalculateBlockProcessor, CalculationRegistry, CardioDialect, ClearChildrenAction, ClimbDialect, type ClimbGradeMetricValue, type ClimbGradeSystem, ClimbMetricType, CompileAndPushBlockAction, CompletionDecision, type CreateAnalyticsEngineOptions, type CreateAnalyticsEngineResult, CrossFitDialect, DAY, DEFAULT_UNRESOLVED_EFFORT_MET, DIM_LENGTH, DIM_MASS, DIM_TIME, DIM_ZERO, type DayRollup, DialectStack, type Dimension, type DurationPrimitive, EFFORT_DATA_METRIC_TYPE, EffortBlock, type EffortBlockConfig, type EffortPrimitive, EffortRegistrySource, EffortResolutionOptions, EffortResolver, EffortResolverOptions, EmitEventAction, EmitSystemOutputAction, ErrorAction, EventBus, type EventHandlerRegistration, ExecutionContext, type ExecutionSnapshot, type FuzzyCandidate, GIT_SHA, HabitsDialect, type HeadingPrimitive, IAnalyticsEngine, type IAnalyticsProfile, IBlockContext, type ICastSubscription, IEffort, IEffortRegistry, IEffortResolver, IEvent, IEventBus, IEventHandler, IJitCompiler, type ILookupTable, IMemoryLocation, IMemoryReference, type IMetricPresentationPolicy, INowProvider, IRealtimeProcessor, IRuntimeAction, IRuntimeBehavior, IRuntimeBlock, type IRuntimeBlockStrategy, IRuntimeClock, type IRuntimeFactory, IRuntimeStack, type IRuntimeSubscription, IScript, IScriptRuntime, ISummaryProcessor, InMemoryEffortRegistry, JitCompiler, type LapPrimitive, type LineLocator, LocalEventProvider, LocalRuntimeSubscription, type LogLevel, LookupRegistry, MdTimerRuntime, type MemoryEntry, MemoryTag, MemoryTypeEnum, type MetricObjectPrimitive, type MetricPresentationSurface, type MetricPresentationToken, type MetricRenderKind, type MetricTone, MetricVisibility, type MockClock, NextAction, NextEvent, NextEventHandler, OutputEmitter, PREDEFINED_SOUNDS, PRODUCTION_STRATEGIES, type ParseOptions, PlaySoundAction, PopBlockAction, type PredefinedSoundName, ProjectionResult, type PropertyPrimitive, PushBlockAction, PushRestBlockAction, type QuantityPrimitive, RegisterEventHandlerAction, Registry, ResolvedEffort, type ResolvedEffortData, RestBlock, type RestBlockConfig, type RoundsPrimitive, RuntimeAdapter, RuntimeBlock, type RuntimeBlockOptions, RuntimeBuilder, type RuntimeButton, RuntimeClock, type RuntimeController, type RuntimeControls, RuntimeError, RuntimeFactory, type RuntimeLogEntry, RuntimeLogger, RuntimeMemory, type RuntimeMemoryLocation, RuntimeObservers, RuntimeStack, SEMVER, STANDARD_UNITS, STORE_CALCS, ScriptRuntime, type SegmentWithMetadata, SessionRootBlock, type SessionRootConfig, SnapshotClock, type SoundBehaviorConfig, type SoundCue, type SoundCueState, type SoundState, type SourceInput, type SpanList, StackObserver, StackSnapshot, StandardAnalyticsProfile, StartSessionAction, type StartSessionOptions, StartWorkoutAction, type StartWorkoutOptions, SubscriptionManager, type SyntaxFacts, type SyntaxMeta, type SyntaxPrimitive, type SyntaxStatement, type TextPrimitive, ThrowError, ThrowErrorAction, TimeSpan, TimerState, TwoPassEffortResolutionProcess, TypedMemoryReference, type UnitDef$1 as UnitDef, type UnitMatch, UnitRegistry, UnitSet, UnitsDialect, UnregisterEventHandlerAction, Unsubscribe, UpdateNextPreviewAction, VERSION, WaitingToStartBlock, WhiteboardScript, WodDialect, YogaDialect, buildTooltip, bundledEfforts, index as calc, calculateElapsed, classifyStatements, closeCurrentSpan, commonFixtureSet, computeColumnLabel, computeLabel, computeWorkloadRollups, createAnalyticsEngineForBlock, createCalcEngine, createCompiler, createDialectStack, createLineLocator, createPolicy as createMetricPresentationPolicy, createMockClock, createParser, dailySessionLoads, dayBucket, dialectRegistry, dialectStack, evaluate, evaluateCalculateDefinitions, extractEffortData, extractMetrics, extractStatements, extractStatementsRaw, extractSyntaxFacts, findBestFuzzyMatch, fixtureBackSquat, fixtureBurpee, fixturePlank, fixtureRowing, fixtureRunning, fixtureUserCustom, fixtureUserOverride, formatDuration, metricsToLabel as fragmentsToLabel, fullFixtureSet, fuseUnits, fuseUnitsInMetrics, getAnalyticsFromLogs, getAnalyticsFromRuntime, getHints, hasHint, hintMetric, hintsToContainer, isCastSubscription, isTimeLikeMetric, isWithinThreshold, levenshteinDistance, metricPresentation, mutateTimerSpans, normalizeForFuzzy, openSpan, parseCalcLine, parseCalculateBlock, parseExpression, parseScript, readTimer, realtimeProcessorRegistry, resolveDominantOrigin, sharedParser, startSpan, strategyRegistry, summaryProcessorRegistry, toStoredOutputStatement, parser as whiteboardParser, whiteboardScript, whiteboardScriptLanguage };