@videojs/spf 10.0.0-beta.30 → 10.0.0-beta.32

package/dist/default/playback/primitives/selection-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"selection-rules.js","names":[],"sources":["../../../../src/playback/primitives/selection-rules.ts"],"sourcesContent":["/**\n * The selection-rule substrate: the shape of a rule, and the two composers that\n * turn a list of them into a pick.\n *\n * Lives here rather than beside `switchVideoTrack` so both track-selection\n * behaviors can share rules. The simple `selectVideoTrack` variant exists\n * specifically to tree-shake the ABR path out, so importing a composer from\n * `behaviors/track-switching.ts` would drag the bandwidth estimator and quality\n * selection back in with it. These four have no dependencies at all — pure\n * generics over a candidate list — so either side can reach them freely.\n *\n * See `internal/design/spf/track-switching-model.md` for the model these\n * implement: a hard constraints pre-pass, then an ordered chain of soft\n * narrowing rules and rankers, with the pick as the first survivor.\n */\n\nimport type { CanPlayTrack } from '../../media/types';\n\n/**\n * Deps handed to each rule and to `applyRules`, mirroring a behavior's setup\n * deps so a rule reads from the same surfaces a behavior does. `context` is\n * optional — it's threaded through but absent on direct setup calls (and\n * unread by today's rules), so the whole deps object can pass straight through.\n */\nexport interface SelectionRuleDeps<State = unknown, Context = unknown, Config = unknown> {\n  state: State;\n  context?: Context;\n  config: Config;\n}\n\n/**\n * A selection rule narrows or reorders the candidate list. It reads the state,\n * context, and config it needs at apply time (tightly-coupled reads), so a\n * rule's `.get()`s subscribe the running effect to exactly what it consulted.\n * Returning an empty list means \"no match\" — the composer skips it, so a soft\n * filter never narrows the set to nothing. A ranker returns the list with its\n * pick at the head.\n */\nexport type SelectionRule<T, State = unknown, Context = unknown, Config = unknown> = (\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n) => readonly T[];\n\n/**\n * Apply rules to a candidate list in order; the pick is the first survivor.\n * Two responsibilities the rules don't carry: a rule that returns nothing is\n * skipped (fall-through — a preference never empties the set), and once one\n * survivor remains the chain stops (early-bail — later rules, including the\n * bandwidth ranker, never run, so the effect doesn't subscribe to their\n * signals while the choice is fixed).\n *\n * @param rules - Rules to apply, most authoritative first\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed through to each rule\n * @returns The surviving candidates, pick first\n */\nexport function applyRules<T, State, Context, Config>(\n  rules: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n  for (const rule of rules) {\n    const remaining = rule(current, deps);\n    if (remaining.length === 0) continue;\n    current = remaining;\n    if (current.length === 1) break;\n  }\n  return current;\n}\n\n/**\n * Apply hard constraints to a candidate list — the pre-pass that runs before the\n * rule chain. A constraint shares a rule's signature but its exclusion is\n * *hard*: it removes the unplayable (a codec the environment can't decode, a CDN\n * in failover cooldown) and a removed track is never attempted. Unlike\n * `applyRules`, this never skips an empty result and never early-bails — every\n * constraint always applies, and an empty survivor set is a real outcome\n * (\"nothing playable here\"), not a fall-through. Because each constraint only\n * removes, the order they run in can't change which tracks survive — though one\n * that also *reports* reads the list at its own position, so placement matters.\n *\n * @param constraints - Constraints to apply, in order\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed to each constraint\n * @returns The playable survivors (possibly empty)\n */\nexport function applyConstraints<T, State, Context, Config>(\n  constraints: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n  for (const constraint of constraints) current = constraint(current, deps);\n  return current;\n}\n\n/**\n * Whether two candidate sets hold the same tracks, by id.\n *\n * The `equals` both selection behaviors give their candidate-set `computed`. A\n * live playlist refresh swaps in a new presentation object carrying the same\n * variants, and a constraint's own inputs can churn without changing which\n * tracks survive; in both cases the set is unchanged and the reaction must not\n * re-fire. Compares by id rather than array identity for exactly that.\n */\nexport function sameCandidateSet<T extends { id: string }>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((track) => b.some((other) => other.id === track.id));\n}\n\n/**\n * What {@link excludeUnplayableTracks} reads off the config it is handed.\n *\n * Read through a cast rather than constraining the rule's `Config` generic, the\n * same way `screenResolutionCap` reads `screenResolution` off its state: a rule\n * composes into chains whose config types have nothing else in common, and\n * constraining the generic would make every one of those a weak-type mismatch.\n * Each engine defaults `canPlayTrack` to the DOM-bound probe; unwired means \"no\n * capability filtering\" and the constraint passes everything through.\n */\nexport interface CapabilityConstraintConfig {\n  canPlayTrack?: CanPlayTrack;\n}\n\n/**\n * Capability constraint — a *hard* filter for the {@link applyConstraints}\n * pre-pass. Removes renditions this environment can't decode, probed via the\n * injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`, plus the\n * container and encryption assertions that probe can't make). Constraining here\n * — before selection — means an unplayable variant is pruned upstream and never\n * picked, instead of surviving into the pipeline to fail late at\n * `createSourceBuffer`. That late throw stays as a defensive structural\n * guarantee; with this constraint it should rarely fire.\n *\n * Lives here rather than beside `switchVideoTrack` for the reason this module\n * exists: both the re-evaluating variant and the pinned `selectVideoTrack` apply\n * it, and reaching it through `behaviors/track-switching.ts` would drag the ABR\n * path into a composition that deliberately omits it.\n *\n * Passes everything through when there's no probe (a composition that didn't\n * wire one, or DOM-free tests). When it prunes *every* track, the empty result is\n * preserved (per `applyConstraints`) — \"nothing playable\" — which each consuming\n * behavior answers by clearing its selection; reporting the verdict is separate.\n */\nexport function excludeUnplayableTracks<T, State, Context, Config>(\n  tracks: readonly T[],\n  { config }: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  const canPlay = (config as CapabilityConstraintConfig | undefined)?.canPlayTrack;\n  if (!canPlay) return tracks;\n  return tracks.filter((track) => canPlay(track as Parameters<CanPlayTrack>[0]));\n}\n"],"mappings":";;;;;;;;;;;;;;AAwDA,SAAgB,WACd,OACA,QACA,MACc;CACd,IAAI,UAAU;CACd,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,YAAY,KAAK,SAAS,IAAI;EACpC,IAAI,UAAU,WAAW,GAAG;EAC5B,UAAU;EACV,IAAI,QAAQ,WAAW,GAAG;CAC5B;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;AAkBA,SAAgB,iBACd,aACA,QACA,MACc;CACd,IAAI,UAAU;CACd,KAAK,MAAM,cAAc,aAAa,UAAU,WAAW,SAAS,IAAI;CACxE,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,iBAA2C,GAAiB,GAA0B;CACpG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM,EAAE,CAAC;AAC7F;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,wBACd,QACA,EAAE,UACY;CACd,MAAM,UAAW,QAAmD;CACpE,IAAI,CAAC,SAAS,OAAO;CACrB,OAAO,OAAO,QAAQ,UAAU,QAAQ,KAAoC,CAAC;AAC/E"}
+{"version":3,"file":"selection-rules.js","names":[],"sources":["../../../../src/playback/primitives/selection-rules.ts"],"sourcesContent":["/**\n * The selection-rule substrate: the shape of a rule, and the two composers that turn a list of them into a pick.\n *\n * Lives here rather than beside `switchVideoTrack` so both track-selection behaviors can share rules. The simple\n * `selectVideoTrack` variant exists specifically to tree-shake the ABR path out, so importing a composer from\n * `behaviors/track-switching.ts` would drag the bandwidth estimator and quality selection back in with it. Nothing here\n * reaches past pure generics over a candidate list and small media-layer helpers, so either side can reach them\n * freely.\n *\n * See `internal/design/spf/track-switching-model.md` for the model these implement: a hard constraints pre-pass, then\n * an ordered chain of soft narrowing rules and rankers, with the pick as the first survivor.\n */\n\nimport type { CanPlayTrack } from '../../media/types';\nimport { getCodecFamilies, getCodecFamily } from '../../media/utils/tracks';\n\n/**\n * Deps handed to each rule and to `applyRules`, mirroring a behavior's setup deps so a rule reads from the same\n * surfaces a behavior does. `context` is optional — it's threaded through but absent on direct setup calls (and unread\n * by today's rules), so the whole deps object can pass straight through.\n */\nexport interface SelectionRuleDeps<State = unknown, Context = unknown, Config = unknown> {\n  state: State;\n  context?: Context;\n  config: Config;\n}\n\n/**\n * A selection rule narrows or reorders the candidate list. It reads the state, context, and config it needs at apply\n * time (tightly-coupled reads), so a rule's `.get()`s subscribe the running effect to exactly what it consulted.\n * Returning an empty list means \"no match\" — the composer skips it, so a soft filter never narrows the set to nothing.\n * A ranker returns the list with its pick at the head.\n */\nexport type SelectionRule<T, State = unknown, Context = unknown, Config = unknown> = (\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n) => readonly T[];\n\n/**\n * Apply rules to a candidate list in order; the pick is the first survivor. Two responsibilities the rules don't carry:\n * a rule that returns nothing is skipped (fall-through — a preference never empties the set), and once one survivor\n * remains the chain stops (early-bail — later rules, including the bandwidth ranker, never run, so the effect doesn't\n * subscribe to their signals while the choice is fixed).\n *\n * @param rules - Rules to apply, most authoritative first\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed through to each rule\n * @returns The surviving candidates, pick first\n */\nexport function applyRules<T, State, Context, Config>(\n  rules: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n\n  for (const rule of rules) {\n    const remaining = rule(current, deps);\n    if (remaining.length === 0) continue;\n\n    current = remaining;\n\n    if (current.length === 1) break;\n  }\n\n  return current;\n}\n\n/**\n * Apply hard constraints to a candidate list — the pre-pass that runs before the rule chain. A constraint shares a\n * rule's signature but its exclusion is _hard_: it removes the unplayable (a codec the environment can't decode, a CDN\n * in failover cooldown) and a removed track is never attempted. Unlike `applyRules`, this never skips an empty result\n * and never early-bails — every constraint always applies, and an empty survivor set is a real outcome (\"nothing\n * playable here\"), not a fall-through. Because each constraint only removes, the order they run in can't change which\n * tracks survive — though one that also _reports_ reads the list at its own position, so placement matters.\n *\n * @param constraints - Constraints to apply, in order\n * @param tracks - Candidate tracks\n * @param deps - The behavior's `{ state, context, config }`, passed to each constraint\n * @returns The playable survivors (possibly empty)\n */\nexport function applyConstraints<T, State, Context, Config>(\n  constraints: readonly SelectionRule<T, State, Context, Config>[],\n  tracks: readonly T[],\n  deps: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  let current = tracks;\n\n  for (const constraint of constraints) current = constraint(current, deps);\n\n  return current;\n}\n\n/**\n * Whether two candidate sets hold the same tracks, by id.\n *\n * The `equals` both selection behaviors give their candidate-set `computed`. A live playlist refresh swaps in a new\n * presentation object carrying the same variants, and a constraint's own inputs can churn without changing which tracks\n * survive; in both cases the set is unchanged and the reaction must not re-fire. Compares by id rather than array\n * identity for exactly that.\n */\nexport function sameCandidateSet<T extends { id: string }>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((track) => b.some((other) => other.id === track.id));\n}\n\n/**\n * What {@link excludeUnplayableTracks} reads off the config it is handed.\n *\n * Read through a cast rather than constraining the rule's `Config` generic, the same way `screenResolutionCap` reads\n * `screenResolution` off its state: a rule composes into chains whose config types have nothing else in common, and\n * constraining the generic would make every one of those a weak-type mismatch. Each engine defaults `canPlayTrack` to\n * the DOM-bound probe; unwired means \"no capability filtering\" and the constraint passes everything through.\n */\nexport interface CapabilityConstraintConfig {\n  canPlayTrack?: CanPlayTrack;\n}\n\n/**\n * Capability constraint — a _hard_ filter for the {@link applyConstraints} pre-pass. Removes renditions this\n * environment can't decode, probed via the injected `canPlayTrack` (codec → `MediaSource.isTypeSupported`, plus the\n * container and encryption assertions that probe can't make). Constraining here — before selection — means an\n * unplayable variant is pruned upstream and never picked, instead of surviving into the pipeline to fail late at\n * `createSourceBuffer`. That late throw stays as a defensive structural guarantee; with this constraint it should\n * rarely fire.\n *\n * Lives here rather than beside `switchVideoTrack` for the reason this module exists: both the re-evaluating variant\n * and the pinned `selectVideoTrack` apply it, and reaching it through `behaviors/track-switching.ts` would drag the ABR\n * path into a composition that deliberately omits it.\n *\n * Passes everything through when there's no probe (a composition that didn't wire one, or DOM-free tests). When it\n * prunes _every_ track, the empty result is preserved (per `applyConstraints`) — \"nothing playable\" — which each\n * consuming behavior answers by clearing its selection; reporting the verdict is separate.\n */\nexport function excludeUnplayableTracks<T, State, Context, Config>(\n  tracks: readonly T[],\n  { config }: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  const canPlay = (config as CapabilityConstraintConfig | undefined)?.canPlayTrack;\n  if (!canPlay) return tracks;\n\n  return tracks.filter((track) => canPlay(track as Parameters<CanPlayTrack>[0]));\n}\n\n/**\n * What {@link preferCodecFamilies} reads off the config it is handed — a cast view, for the same reason as\n * {@link CapabilityConstraintConfig}.\n */\nexport interface CodecPreferenceConfig {\n  preferredCodecs?: string[];\n}\n\n/**\n * The codec families {@link preferCodecFamilies} narrows to when the config carries no `preferredCodecs`: AVC (both its\n * 4CCs) and AAC. The default is deliberate rather than neutral — SPF implements no `SourceBuffer.changeType()`, so on a\n * mixed-codec source the _initial_ family choice is the one ABR lives inside for the whole source (see\n * `stickToSelectedCodecs` in `behaviors/track-switching.ts`), and AVC/AAC is the family pair with the broadest decode\n * support. The cost, equally deliberate: on a ladder whose higher rungs are HEVC-only (a common 4K shape), the default\n * caps quality at the top AVC rung — configure `preferredCodecs` (or pass `[]`) to trade the other way.\n */\nexport const DEFAULT_PREFERRED_CODECS: readonly string[] = ['avc1', 'avc3', 'mp4a'];\n\n/**\n * Codec-family preference — a _soft_ filter (scope) for a selection-rule chain; the `hevc-variant-selection` concern\n * from `internal/design/spf/track-switching-model.md`. Narrows to the tracks whose codec families are all in\n * `preferredCodecs` (family-compared, so entries may be 4CCs or full codec strings). Soft-filter semantics: a source\n * with no preferred-family rendition (an HEVC-only ladder under the AVC default) is left unnarrowed, and a track\n * without codecs never matches — on a ladder with no codecs anywhere (DOM-free tests) the rule is inert.\n *\n * `preferredCodecs` defaults to {@link DEFAULT_PREFERRED_CODECS}; explicitly pass `[]` to disable the preference while\n * keeping the rule composed.\n *\n * \"All families\" rather than \"any\" so a muxed rendition is judged as the unit it is: `hvc1,mp4a` must not count as\n * preferred just because its audio half matches.\n *\n * Lives here rather than beside `switchVideoTrack` for the module's usual reason: the pinned `selectVideoTrack` variant\n * can compose it without dragging the ABR path in.\n */\nexport function preferCodecFamilies<T, State, Context, Config>(\n  tracks: readonly T[],\n  { config }: SelectionRuleDeps<State, Context, Config>\n): readonly T[] {\n  const preferred = (config as CodecPreferenceConfig | undefined)?.preferredCodecs ?? DEFAULT_PREFERRED_CODECS;\n  if (!preferred.length) return tracks;\n\n  const preferredFamilies = new Set(preferred.map(getCodecFamily));\n\n  return tracks.filter((track) => {\n    const families = getCodecFamilies(track as { codecs?: string[] });\n\n    return !!families && families.every((family) => preferredFamilies.has(family));\n  });\n}\n"],"mappings":";;;;;;;;;;;;;AAiDA,SAAgB,WACd,OACA,QACA,MACc;CACd,IAAI,UAAU;CAEd,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,YAAY,KAAK,SAAS,IAAI;EACpC,IAAI,UAAU,WAAW,GAAG;EAE5B,UAAU;EAEV,IAAI,QAAQ,WAAW,GAAG;CAC5B;CAEA,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,iBACd,aACA,QACA,MACc;CACd,IAAI,UAAU;CAEd,KAAK,MAAM,cAAc,aAAa,UAAU,WAAW,SAAS,IAAI;CAExE,OAAO;AACT;;;;;;;;;AAUA,SAAgB,iBAA2C,GAAiB,GAA0B;CACpG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,UAAU,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM,EAAE,CAAC;AAC7F;;;;;;;;;;;;;;;;;AA8BA,SAAgB,wBACd,QACA,EAAE,UACY;CACd,MAAM,UAAW,QAAmD;CACpE,IAAI,CAAC,SAAS,OAAO;CAErB,OAAO,OAAO,QAAQ,UAAU,QAAQ,KAAoC,CAAC;AAC/E;;;;;;;;;AAkBA,MAAa,2BAA8C;CAAC;CAAQ;CAAQ;AAAM;;;;;;;;;;;;;;;;;AAkBlF,SAAgB,oBACd,QACA,EAAE,UACY;CACd,MAAM,YAAa,QAA8C,mBAAmB;CACpF,IAAI,CAAC,UAAU,QAAQ,OAAO;CAE9B,MAAM,oBAAoB,IAAI,IAAI,UAAU,IAAI,cAAc,CAAC;CAE/D,OAAO,OAAO,QAAQ,UAAU;EAC9B,MAAM,WAAW,iBAAiB,KAA8B;EAEhE,OAAO,CAAC,CAAC,YAAY,SAAS,OAAO,WAAW,kBAAkB,IAAI,MAAM,CAAC;CAC/E,CAAC;AACH"}

package/dist/default/playback/primitives/text-segment-load-pipeline.js

@@ -1,10 +1,9 @@
 //#region src/playback/primitives/text-segment-load-pipeline.ts
 /**
-* Base-step view of the loader's wiring, folded into `config` by
-* `createTextTrackSegmentLoaderActor` so base steps read it from the uniform passthrough
-* — present in both composition and standalone use. `config` is loose (`object`), so
-* assert the shape here (mirrors the v/a loader's `stepWiring`). The sink is the
-* structural {@link CueSink}, not the concrete actor.
+* Base-step view of the loader's wiring, folded into `config` by `createTextTrackSegmentLoaderActor` so base steps read
+* it from the uniform passthrough — present in both composition and standalone use. `config` is loose (`object`), so
+* assert the shape here (mirrors the v/a loader's `stepWiring`). The sink is the structural {@link CueSink}, not the
+* concrete actor.
 */
 function textStepWiring(deps) {
 	return deps.config;

package/dist/default/playback/primitives/text-segment-load-pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"text-segment-load-pipeline.js","names":[],"sources":["../../../../src/playback/primitives/text-segment-load-pipeline.ts"],"sourcesContent":["/**\n * The text-track **load pipeline** — the step vocabulary and base steps a text-segment\n * loader runs, the text mirror of `segment-load-pipeline`. Extracted from the loader\n * actor so the \"what\" (the composable steps) is separable from the \"how\" (scheduling).\n * A pipeline is a flat, ordered list of {@link TextLoadStep}s (text has a single op\n * type, so no per-type `Record`); the default is `resolveCues → dispatchCues`, and a\n * composition can insert its own steps (e.g. non-zero-PTS cue rebase) without the\n * loader knowing.\n *\n * The dispatch step reaches its cue sink through the structural {@link CueSink} seam\n * rather than the concrete `TextTracksActor` type — the loader folds the real actor\n * into `config`, and it satisfies the seam by structure — so this module names no\n * actor and stays DOM-free (generic over the cue type `C`).\n */\nimport type { AnySlotMap } from '../../core/composition/create-composition';\nimport type { Cue, Segment } from '../../media/types';\nimport type { AddCuesMessage } from './text-track-messages';\n\n// ============================================================================\n// SINK SEAM\n// ============================================================================\n\n/**\n * The structural view of a cue sink the base steps use — just the `send`\n * {@link dispatchCuesStep} needs. The concrete `TextTracksActor` satisfies it by\n * structure, so the pipeline names no actor.\n */\nexport interface CueSink<C extends Cue = Cue> {\n  send(message: AddCuesMessage<C>): void;\n}\n\n// ============================================================================\n// STEP MODEL\n// ============================================================================\n\n/**\n * Resolves a text-track segment URL into the array of cues it contains.\n *\n * \"Resolve\" because the fn covers both network fetch and parse into the\n * domain model. Host-agnostic — the concrete resolver (e.g. the\n * browser's native VTT resolver) is supplied at engine-assembly time,\n * so this stays DOM-free. A pure `url → cues` primitive (the text\n * analog of the v/a loader's `fetchBytes`); composition-awareness lives in\n * the injected {@link TextLoadStep}s, not here.\n */\nexport type TextTrackSegmentResolver<C extends Cue = Cue> = (url: string) => Promise<C[]>;\n\n/** Internal load-task descriptor — one segment fetch + dispatch unit. */\nexport interface TextLoadTask {\n  segment: Segment;\n  trackId: string;\n}\n\n/**\n * A text load in mid-pipeline — the text analog of the v/a loader's `Frame`.\n * `resolveCuesStep` fills `cues`; `dispatchCuesStep` sends them. `metadata` is\n * opaque header metadata a resolve step may attach for a later step to read\n * (e.g. relocation stashes the `X-TIMESTAMP-MAP` correlation here for its rebase\n * step). Typed `unknown` so the generic loader stays host-agnostic — the step\n * that reads it knows its concrete shape (mirrors `StepDeps.state`).\n */\nexport interface TextFrame<C extends Cue = Cue> {\n  readonly op: TextLoadTask;\n  cues?: C[];\n  metadata?: unknown;\n}\n\n/**\n * One stage of a text message pipeline — the text analog of the v/a loader's\n * `LoadStep`. Mutates the {@link TextFrame} in place and may be async; the runner\n * checks `signal.aborted` before each step and passes the actor's\n * {@link TextStepDeps} on every call, so a stateless step (`resolveCuesStep`) is a\n * plain value and a step that needs composition signals (relocation's cue rebase)\n * reads them from `deps` at call time.\n */\nexport type TextLoadStep<C extends Cue = Cue> = (\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n) => void | Promise<void>;\n\n/**\n * The uniform passthrough handed to each {@link TextLoadStep} — the composition triple,\n * the text analog of `StepDeps`. `state`/`context` are the composition signal maps;\n * `config` is the threaded config with the loader's wiring folded in (see\n * {@link textStepWiring} + `createTextTrackSegmentLoaderActor`). Typed loose: composition\n * steps read `state`; base steps read the folded wiring off `config`.\n */\nexport interface TextStepDeps {\n  state: AnySlotMap;\n  context: AnySlotMap;\n  config: object;\n}\n\n/**\n * Base-step view of the loader's wiring, folded into `config` by\n * `createTextTrackSegmentLoaderActor` so base steps read it from the uniform passthrough\n * — present in both composition and standalone use. `config` is loose (`object`), so\n * assert the shape here (mirrors the v/a loader's `stepWiring`). The sink is the\n * structural {@link CueSink}, not the concrete actor.\n */\nexport function textStepWiring<C extends Cue>(\n  deps: TextStepDeps\n): { textTracksActor: CueSink<C>; resolveSegment: TextTrackSegmentResolver<C> } {\n  return deps.config as { textTracksActor: CueSink<C>; resolveSegment: TextTrackSegmentResolver<C> };\n}\n\n/**\n * Builds the ordered step list, called **once per actor** (mirrors the v/a loader's\n * `MessagePipelines`, but text has a single op type so it's a flat array, not a\n * `Record`). The default ({@link DEFAULT_TEXT_MESSAGE_PIPELINES}) is\n * `resolveCues → dispatchCues`; a non-zero-PTS composition returns a list that\n * inserts a cue-rebase step (see `relocatingTextPipelines`), so the loader stays\n * oblivious to relocation.\n */\nexport type TextMessagePipelines<C extends Cue = Cue> = () => TextLoadStep<C>[];\n\n// ============================================================================\n// BASE STEPS\n// ============================================================================\n\n// Base steps are generic over the cue type `C` (generic arrow consts, not\n// `TextLoadStep<Cue>` values): each touches `C` — `frame.cues: C[]` and the\n// `C`-typed `textStepWiring<C>` — so a `Cue`-typed const wouldn't slot into a\n// `VTTCue` pipeline. A generic function assigns to any `TextLoadStep<C>`.\n\n/** Resolve the op's cues (via the injected host primitive) into the frame. The text analog of `fetchStep`. */\nexport const resolveCuesStep = async <C extends Cue>(\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n): Promise<void> => {\n  const cues = await textStepWiring<C>(deps).resolveSegment(frame.op.segment.url);\n  if (signal.aborted) return;\n  frame.cues = cues;\n};\n\n/** Dispatch the frame's cues to the TextTracksActor as `add-cues`. The text analog of `dispatchStep`. */\nexport const dispatchCuesStep = <C extends Cue>(\n  frame: TextFrame<C>,\n  _signal: AbortSignal,\n  deps: TextStepDeps\n): void => {\n  const { op } = frame;\n  textStepWiring<C>(deps).textTracksActor.send({\n    type: 'add-cues',\n    meta: {\n      trackId: op.trackId,\n      id: op.segment.id,\n      startTime: op.segment.startTime,\n      duration: op.segment.duration,\n    },\n    cues: frame.cues ?? [],\n  });\n};\n\n/** Tier 0 default: resolve then dispatch. No relocation vocabulary. */\nexport const DEFAULT_TEXT_MESSAGE_PIPELINES = <C extends Cue>(): TextLoadStep<C>[] => [\n  resolveCuesStep,\n  dispatchCuesStep,\n];\n"],"mappings":";;;;;;;;AAqGA,SAAgB,eACd,MAC8E;CAC9E,OAAO,KAAK;AACd;;AAsBA,MAAa,kBAAkB,OAC7B,OACA,QACA,SACkB;CAClB,MAAM,OAAO,MAAM,eAAkB,IAAI,CAAC,CAAC,eAAe,MAAM,GAAG,QAAQ,GAAG;CAC9E,IAAI,OAAO,SAAS;CACpB,MAAM,OAAO;AACf;;AAGA,MAAa,oBACX,OACA,SACA,SACS;CACT,MAAM,EAAE,OAAO;CACf,eAAkB,IAAI,CAAC,CAAC,gBAAgB,KAAK;EAC3C,MAAM;EACN,MAAM;GACJ,SAAS,GAAG;GACZ,IAAI,GAAG,QAAQ;GACf,WAAW,GAAG,QAAQ;GACtB,UAAU,GAAG,QAAQ;EACvB;EACA,MAAM,MAAM,QAAQ,CAAC;CACvB,CAAC;AACH;;AAGA,MAAa,uCAAyE,CACpF,iBACA,gBACF"}
+{"version":3,"file":"text-segment-load-pipeline.js","names":[],"sources":["../../../../src/playback/primitives/text-segment-load-pipeline.ts"],"sourcesContent":["/**\n * The text-track **load pipeline** — the step vocabulary and base steps a text-segment loader runs, the text mirror of\n * `segment-load-pipeline`. Extracted from the loader actor so the \"what\" (the composable steps) is separable from the\n * \"how\" (scheduling). A pipeline is a flat, ordered list of {@link TextLoadStep}s (text has a single op type, so no\n * per-type `Record`); the default is `resolveCues → dispatchCues`, and a composition can insert its own steps (e.g.\n * non-zero-PTS cue rebase) without the loader knowing.\n *\n * The dispatch step reaches its cue sink through the structural {@link CueSink} seam rather than the concrete\n * `TextTracksActor` type — the loader folds the real actor into `config`, and it satisfies the seam by structure — so\n * this module names no actor and stays DOM-free (generic over the cue type `C`).\n */\nimport type { AnySlotMap } from '../../core/composition/create-composition';\nimport type { Cue, Segment } from '../../media/types';\nimport type { AddCuesMessage } from './text-track-messages';\n\n// ============================================================================\n// SINK SEAM\n// ============================================================================\n\n/**\n * The structural view of a cue sink the base steps use — just the `send` {@link dispatchCuesStep} needs. The concrete\n * `TextTracksActor` satisfies it by structure, so the pipeline names no actor.\n */\nexport interface CueSink<C extends Cue = Cue> {\n  send(message: AddCuesMessage<C>): void;\n}\n\n// ============================================================================\n// STEP MODEL\n// ============================================================================\n\n/**\n * Resolves a text-track segment URL into the array of cues it contains.\n *\n * \"Resolve\" because the fn covers both network fetch and parse into the domain model. Host-agnostic — the concrete\n * resolver (e.g. the browser's native VTT resolver) is supplied at engine-assembly time, so this stays DOM-free. A pure\n * `url → cues` primitive (the text analog of the v/a loader's `fetchBytes`); composition-awareness lives in the\n * injected {@link TextLoadStep}s, not here.\n */\nexport type TextTrackSegmentResolver<C extends Cue = Cue> = (url: string) => Promise<C[]>;\n\n/** Internal load-task descriptor — one segment fetch + dispatch unit. */\nexport interface TextLoadTask {\n  segment: Segment;\n  trackId: string;\n}\n\n/**\n * A text load in mid-pipeline — the text analog of the v/a loader's `Frame`. `resolveCuesStep` fills `cues`;\n * `dispatchCuesStep` sends them. `metadata` is opaque header metadata a resolve step may attach for a later step to\n * read (e.g. relocation stashes the `X-TIMESTAMP-MAP` correlation here for its rebase step). Typed `unknown` so the\n * generic loader stays host-agnostic — the step that reads it knows its concrete shape (mirrors `StepDeps.state`).\n */\nexport interface TextFrame<C extends Cue = Cue> {\n  readonly op: TextLoadTask;\n  cues?: C[];\n  metadata?: unknown;\n}\n\n/**\n * One stage of a text message pipeline — the text analog of the v/a loader's `LoadStep`. Mutates the {@link TextFrame}\n * in place and may be async; the runner checks `signal.aborted` before each step and passes the actor's\n * {@link TextStepDeps} on every call, so a stateless step (`resolveCuesStep`) is a plain value and a step that needs\n * composition signals (relocation's cue rebase) reads them from `deps` at call time.\n */\nexport type TextLoadStep<C extends Cue = Cue> = (\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n) => void | Promise<void>;\n\n/**\n * The uniform passthrough handed to each {@link TextLoadStep} — the composition triple, the text analog of `StepDeps`.\n * `state`/`context` are the composition signal maps; `config` is the threaded config with the loader's wiring folded in\n * (see {@link textStepWiring} + `createTextTrackSegmentLoaderActor`). Typed loose: composition steps read `state`; base\n * steps read the folded wiring off `config`.\n */\nexport interface TextStepDeps {\n  state: AnySlotMap;\n  context: AnySlotMap;\n  config: object;\n}\n\n/**\n * Base-step view of the loader's wiring, folded into `config` by `createTextTrackSegmentLoaderActor` so base steps read\n * it from the uniform passthrough — present in both composition and standalone use. `config` is loose (`object`), so\n * assert the shape here (mirrors the v/a loader's `stepWiring`). The sink is the structural {@link CueSink}, not the\n * concrete actor.\n */\nexport function textStepWiring<C extends Cue>(\n  deps: TextStepDeps\n): { textTracksActor: CueSink<C>; resolveSegment: TextTrackSegmentResolver<C> } {\n  return deps.config as { textTracksActor: CueSink<C>; resolveSegment: TextTrackSegmentResolver<C> };\n}\n\n/**\n * Builds the ordered step list, called **once per actor** (mirrors the v/a loader's `MessagePipelines`, but text has a\n * single op type so it's a flat array, not a `Record`). The default ({@link DEFAULT_TEXT_MESSAGE_PIPELINES}) is\n * `resolveCues → dispatchCues`; a non-zero-PTS composition returns a list that inserts a cue-rebase step (see\n * `relocatingTextPipelines`), so the loader stays oblivious to relocation.\n */\nexport type TextMessagePipelines<C extends Cue = Cue> = () => TextLoadStep<C>[];\n\n// ============================================================================\n// BASE STEPS\n// ============================================================================\n\n// Base steps are generic over the cue type `C` (generic arrow consts, not\n// `TextLoadStep<Cue>` values): each touches `C` — `frame.cues: C[]` and the\n// `C`-typed `textStepWiring<C>` — so a `Cue`-typed const wouldn't slot into a\n// `VTTCue` pipeline. A generic function assigns to any `TextLoadStep<C>`.\n\n/** Resolve the op's cues (via the injected host primitive) into the frame. The text analog of `fetchStep`. */\nexport const resolveCuesStep = async <C extends Cue>(\n  frame: TextFrame<C>,\n  signal: AbortSignal,\n  deps: TextStepDeps\n): Promise<void> => {\n  const cues = await textStepWiring<C>(deps).resolveSegment(frame.op.segment.url);\n\n  if (signal.aborted) return;\n\n  frame.cues = cues;\n};\n\n/** Dispatch the frame's cues to the TextTracksActor as `add-cues`. The text analog of `dispatchStep`. */\nexport const dispatchCuesStep = <C extends Cue>(\n  frame: TextFrame<C>,\n  _signal: AbortSignal,\n  deps: TextStepDeps\n): void => {\n  const { op } = frame;\n\n  textStepWiring<C>(deps).textTracksActor.send({\n    type: 'add-cues',\n    meta: {\n      trackId: op.trackId,\n      id: op.segment.id,\n      startTime: op.segment.startTime,\n      duration: op.segment.duration,\n    },\n    cues: frame.cues ?? [],\n  });\n};\n\n/** Tier 0 default: resolve then dispatch. No relocation vocabulary. */\nexport const DEFAULT_TEXT_MESSAGE_PIPELINES = <C extends Cue>(): TextLoadStep<C>[] => [\n  resolveCuesStep,\n  dispatchCuesStep,\n];\n"],"mappings":";;;;;;;AAyFA,SAAgB,eACd,MAC8E;CAC9E,OAAO,KAAK;AACd;;AAoBA,MAAa,kBAAkB,OAC7B,OACA,QACA,SACkB;CAClB,MAAM,OAAO,MAAM,eAAkB,IAAI,CAAC,CAAC,eAAe,MAAM,GAAG,QAAQ,GAAG;CAE9E,IAAI,OAAO,SAAS;CAEpB,MAAM,OAAO;AACf;;AAGA,MAAa,oBACX,OACA,SACA,SACS;CACT,MAAM,EAAE,OAAO;CAEf,eAAkB,IAAI,CAAC,CAAC,gBAAgB,KAAK;EAC3C,MAAM;EACN,MAAM;GACJ,SAAS,GAAG;GACZ,IAAI,GAAG,QAAQ;GACf,WAAW,GAAG,QAAQ;GACtB,UAAU,GAAG,QAAQ;EACvB;EACA,MAAM,MAAM,QAAQ,CAAC;CACvB,CAAC;AACH;;AAGA,MAAa,uCAAyE,CACpF,iBACA,gBACF"}

package/dist/default/playback/primitives/track-types.js

@@ -2,22 +2,16 @@
 /**
 * **Per-type config bundles for per-type behavior variants.**
 *
-* Each `*_TYPE_CONFIG` constant names the per-type slot keys that
-* per-type-variant setup-shape helpers consume. Variants reference the
-* shared constant at their `defineBehavior` setup body rather than
-* constructing the config inline, so the per-type identity (which state
-* slot, which context slot, which discriminant) lives in one place per
+* Each `*_TYPE_CONFIG` constant names the per-type slot keys that per-type-variant setup-shape helpers consume.
+* Variants reference the shared constant at their `defineBehavior` setup body rather than constructing the config
+* inline, so the per-type identity (which state slot, which context slot, which discriminant) lives in one place per
 * type.
 *
-* Variants spread their composition-time `config` over the defaults so
-* engines can layer composition-supplied additions on top (e.g. a
-* custom fetch closure, a non-default segment resolver). Defaults
-* first, engine config second.
+* Variants spread their composition-time `config` over the defaults so engines can layer composition-supplied additions
+* on top (e.g. a custom fetch closure, a non-default segment resolver). Defaults first, engine config second.
 *
-* Helpers continue to consume their slice via the existing typed-key
-* generics (`<K extends SelectedTrackKey>` etc.); the extra fields on
-* the config object (carrying facets other helpers care about) are fine
-* under structural typing.
+* Helpers continue to consume their slice via the existing typed-key generics (`<K extends SelectedTrackKey>` etc.);
+* the extra fields on the config object (carrying facets other helpers care about) are fine under structural typing.
 */
 /**
 * Type-identity bundle for video-track-typed behaviors.
@@ -42,11 +36,9 @@ const AUDIO_TYPE_CONFIG = {
 	loaderKey: "audioSegmentLoaderActor"
 };
 /**
-* Type-identity bundle for text-track-typed behaviors. Text tracks have
-* no `SourceBufferActor` (MSE doesn't apply), so this bundle omits
-* `actorKey`. The `loaderKey` points at the text-track-segment-loader
-* actor (a `MessageActor` with continue-vs-preempt semantics, parallel
-* to v/a's `SegmentLoaderActor`).
+* Type-identity bundle for text-track-typed behaviors. Text tracks have no `SourceBufferActor` (MSE doesn't apply), so
+* this bundle omits `actorKey`. The `loaderKey` points at the text-track-segment-loader actor (a `MessageActor` with
+* continue-vs-preempt semantics, parallel to v/a's `SegmentLoaderActor`).
 *
 * @see loadTextTrackSegments, setupTextTrackActors
 */

package/dist/default/playback/primitives/track-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"track-types.js","names":[],"sources":["../../../../src/playback/primitives/track-types.ts"],"sourcesContent":["/**\n * **Per-type config bundles for per-type behavior variants.**\n *\n * Each `*_TYPE_CONFIG` constant names the per-type slot keys that\n * per-type-variant setup-shape helpers consume. Variants reference the\n * shared constant at their `defineBehavior` setup body rather than\n * constructing the config inline, so the per-type identity (which state\n * slot, which context slot, which discriminant) lives in one place per\n * type.\n *\n * Variants spread their composition-time `config` over the defaults so\n * engines can layer composition-supplied additions on top (e.g. a\n * custom fetch closure, a non-default segment resolver). Defaults\n * first, engine config second.\n *\n * Helpers continue to consume their slice via the existing typed-key\n * generics (`<K extends SelectedTrackKey>` etc.); the extra fields on\n * the config object (carrying facets other helpers care about) are fine\n * under structural typing.\n */\n\n/**\n * Type-identity bundle for video-track-typed behaviors.\n *\n * @see setupVideoBufferActors, loadVideoSegments\n */\nexport const VIDEO_TYPE_CONFIG = {\n  type: 'video',\n  selectedKey: 'selectedVideoTrackId',\n  actorKey: 'videoBufferActor',\n  loaderKey: 'videoSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for audio-track-typed behaviors.\n *\n * @see setupAudioBufferActors, loadAudioSegments\n */\nexport const AUDIO_TYPE_CONFIG = {\n  type: 'audio',\n  selectedKey: 'selectedAudioTrackId',\n  actorKey: 'audioBufferActor',\n  loaderKey: 'audioSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for text-track-typed behaviors. Text tracks have\n * no `SourceBufferActor` (MSE doesn't apply), so this bundle omits\n * `actorKey`. The `loaderKey` points at the text-track-segment-loader\n * actor (a `MessageActor` with continue-vs-preempt semantics, parallel\n * to v/a's `SegmentLoaderActor`).\n *\n * @see loadTextTrackSegments, setupTextTrackActors\n */\nexport const TEXT_TYPE_CONFIG = {\n  type: 'text',\n  selectedKey: 'selectedTextTrackId',\n  loaderKey: 'textTrackSegmentLoaderActor',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;AACb;;;;;;AAOA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;AACb;;;;;;;;;;AAWA,MAAa,mBAAmB;CAC9B,MAAM;CACN,aAAa;CACb,WAAW;AACb"}
+{"version":3,"file":"track-types.js","names":[],"sources":["../../../../src/playback/primitives/track-types.ts"],"sourcesContent":["/**\n * **Per-type config bundles for per-type behavior variants.**\n *\n * Each `*_TYPE_CONFIG` constant names the per-type slot keys that per-type-variant setup-shape helpers consume.\n * Variants reference the shared constant at their `defineBehavior` setup body rather than constructing the config\n * inline, so the per-type identity (which state slot, which context slot, which discriminant) lives in one place per\n * type.\n *\n * Variants spread their composition-time `config` over the defaults so engines can layer composition-supplied additions\n * on top (e.g. a custom fetch closure, a non-default segment resolver). Defaults first, engine config second.\n *\n * Helpers continue to consume their slice via the existing typed-key generics (`<K extends SelectedTrackKey>` etc.);\n * the extra fields on the config object (carrying facets other helpers care about) are fine under structural typing.\n */\n\n/**\n * Type-identity bundle for video-track-typed behaviors.\n *\n * @see setupVideoBufferActors, loadVideoSegments\n */\nexport const VIDEO_TYPE_CONFIG = {\n  type: 'video',\n  selectedKey: 'selectedVideoTrackId',\n  actorKey: 'videoBufferActor',\n  loaderKey: 'videoSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for audio-track-typed behaviors.\n *\n * @see setupAudioBufferActors, loadAudioSegments\n */\nexport const AUDIO_TYPE_CONFIG = {\n  type: 'audio',\n  selectedKey: 'selectedAudioTrackId',\n  actorKey: 'audioBufferActor',\n  loaderKey: 'audioSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for text-track-typed behaviors. Text tracks have no `SourceBufferActor` (MSE doesn't apply), so\n * this bundle omits `actorKey`. The `loaderKey` points at the text-track-segment-loader actor (a `MessageActor` with\n * continue-vs-preempt semantics, parallel to v/a's `SegmentLoaderActor`).\n *\n * @see loadTextTrackSegments, setupTextTrackActors\n */\nexport const TEXT_TYPE_CONFIG = {\n  type: 'text',\n  selectedKey: 'selectedTextTrackId',\n  loaderKey: 'textTrackSegmentLoaderActor',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;AACb;;;;;;AAOA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;AACb;;;;;;;;AASA,MAAa,mBAAmB;CAC9B,MAAM;CACN,aAAa;CACb,WAAW;AACb"}

package/dist/dev/core/actors/actor.d.ts

@@ -1,8 +1,8 @@
 import { Machine, MachineSnapshot } from "../machine.js";
 //#region src/core/actors/actor.d.ts
 /**
- * Complete actor snapshot: finite state + non-finite context.
- * Extends `MachineSnapshot` with context — the non-finite data managed by the actor.
+ * Complete actor snapshot: finite state + non-finite context. Extends `MachineSnapshot` with context — the non-finite
+ * data managed by the actor.
  */
 interface ActorSnapshot<State extends string, Context extends object> extends MachineSnapshot<State> {
   context: Context;
@@ -12,8 +12,8 @@ interface SignalActor<State extends string, Context extends object> extends Mach
 /**
  * A message-driven actor with no reactive snapshot.
  *
- * Use for actors that coordinate async work but have no state that external
- * consumers need to observe. Analogous to XState's `fromCallback`.
+ * Use for actors that coordinate async work but have no state that external consumers need to observe. Analogous to
+ * XState's `fromCallback`.
  */
 interface CallbackActor<Message extends {
   type: string;

package/dist/dev/core/actors/actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor.d.ts","names":[],"sources":["../../../../src/core/actors/actor.ts"],"mappings":";;;;;;UAeiB,cAAc,sBAAsB,gCAAgC,gBAAgB;EACnG,SAAS;;;UAIM,YAAY,sBAAsB,gCACzC,QAAQ,cAAc,OAAO;;;;;;;UAQtB,cAAc;EAAkB;;EAC/C,KAAK,SAAS;EACd"}
+{"version":3,"file":"actor.d.ts","names":[],"sources":["../../../../src/core/actors/actor.ts"],"mappings":";;;;;;UAciB,cAAc,sBAAsB,gCAAgC,gBAAgB;EACnG,SAAS;;;UAIM,YAAY,sBAAsB,gCAAgC,QACjF,cAAc,OAAO;;;;;;;UASN,cAAc;EAAkB;;EAC/C,KAAK,SAAS;EACd"}

package/dist/dev/core/actors/create-machine-actor.d.ts

@@ -1,9 +1,7 @@
 import { TaskLike } from "../tasks/task.js";
 import { SignalActor } from "./actor.js";
 //#region src/core/actors/create-machine-actor.d.ts
-/**
- * Minimal interface for any runner that can be used with createMachineActor.
- */
+/** Minimal interface for any runner that can be used with createMachineActor. */
 interface RunnerLike {
   schedule<Value = void, Err = unknown>(task: TaskLike<Value, Err>): Promise<Value>;
   abortAll(): void;
@@ -11,8 +9,7 @@ interface RunnerLike {
   whenSettled(callback: () => void): void;
 }
 /**
- * Context passed to message handlers.
- * `runner` is present and typed as the exact runner instance only when the
+ * Context passed to message handlers. `runner` is present and typed as the exact runner instance only when the
  * definition includes a runner factory.
  */
 type HandlerContext<UserState extends string, Context extends object, RunnerFactory extends (() => RunnerLike) | undefined> = {
@@ -20,9 +17,8 @@ type HandlerContext<UserState extends string, Context extends object, RunnerFact
   /** Context snapshot captured at dispatch time. Stale after any `setContext` call. */
   context: Context;
   /**
-   * Live untracked read of the current context. Use in async task closures that
-   * execute after the handler returns — e.g. `getCtx: getContext` passed to tasks
-   * scheduled on the runner, so each task reads the context committed by the
+   * Live untracked read of the current context. Use in async task closures that execute after the handler returns —
+   * e.g. `getCtx: getContext` passed to tasks scheduled on the runner, so each task reads the context committed by the
    * previous task rather than the stale snapshot from dispatch time.
    */
   getContext: () => Context;
@@ -30,17 +26,14 @@ type HandlerContext<UserState extends string, Context extends object, RunnerFact
 } & (RunnerFactory extends (() => infer R) ? {
   runner: R;
 } : object);
-/**
- * Definition for a single user-defined state.
- */
+/** Definition for a single user-defined state. */
 type ActorStateDefinition<UserState extends string, Context extends object, Message extends {
   type: string;
 }, RunnerFactory extends (() => RunnerLike) | undefined> = {
   /**
-   * When the actor's runner settles while in this state, automatically
-   * transition to this state. The framework owns the generation-token logic —
-   * re-registering after each `runner.schedule()` call so that
-   * `abortAll()` + reschedule correctly supersedes stale callbacks.
+   * When the actor's runner settles while in this state, automatically transition to this state. The framework owns the
+   * generation-token logic — re-registering after each `runner.schedule()` call so that `abortAll()` + reschedule
+   * correctly supersedes stale callbacks.
    */
   onSettled?: UserState;
   /** Message handlers active in this state. Messages with no handler are silently dropped. */
@@ -51,18 +44,18 @@ type ActorStateDefinition<UserState extends string, Context extends object, Mess
 /**
  * Full actor definition passed to `createMachineActor`.
  *
- * `UserState` is the set of domain-meaningful states. `'destroyed'` is always
- * added by the framework as the implicit terminal state — do not include it here.
+ * `UserState` is the set of domain-meaningful states. `'destroyed'` is always added by the framework as the implicit
+ * terminal state — do not include it here.
  */
 type ActorDefinition<UserState extends string, Context extends object, Message extends {
   type: string;
 }, RunnerFactory extends (() => RunnerLike) | undefined = undefined> = {
   /**
-   * Runner factory — called once at `createMachineActor()` time.
-   * The runner lives for the full actor lifetime and is destroyed with it.
+   * Runner factory — called once at `createMachineActor()` time. The runner lives for the full actor lifetime and is
+   * destroyed with it.
    *
    * @example
-   * runner: () => new SerialRunner()
+   *   runner: () => new SerialRunner();
    */
   runner?: RunnerFactory;
   /** Initial state. */
@@ -70,8 +63,8 @@ type ActorDefinition<UserState extends string, Context extends object, Message e
   /** Initial context. */
   context: Context;
   /**
-   * Per-state definitions. States with no definition silently drop all messages.
-   * All user-defined states must appear as keys in the `UserState` union.
+   * Per-state definitions. States with no definition silently drop all messages. All user-defined states must appear as
+   * keys in the `UserState` union.
    */
   states: Partial<Record<UserState, ActorStateDefinition<UserState, Context, Message, RunnerFactory>>>;
 };
@@ -84,41 +77,39 @@ interface MessageActor<State extends string, Context extends object, Message ext
 /**
  * Creates a message-driven actor from a declarative definition.
  *
- * The actor owns a reactive snapshot signal (state + context), an optional
- * runner, and dispatches incoming messages to per-state handlers. `'destroyed'`
- * is always the implicit terminal state — `destroy()` transitions there
+ * The actor owns a reactive snapshot signal (state + context), an optional runner, and dispatches incoming messages to
+ * per-state handlers. `'destroyed'` is always the implicit terminal state — `destroy()` transitions there
  * unconditionally and all subsequent `send()` calls are no-ops.
  *
- * When a state declares `onSettled`, the framework calls `runner.whenSettled()`
- * after the handler returns. The runner owns the generation-token logic — if
- * new tasks are scheduled before the current batch settles, the callback is
+ * When a state declares `onSettled`, the framework calls `runner.whenSettled()` after the handler returns. The runner
+ * owns the generation-token logic — if new tasks are scheduled before the current batch settles, the callback is
  * automatically superseded.
  *
  * @example
- * const actor = createMachineActor({
+ *   const actor = createMachineActor({
  *   runner: () => new SerialRunner(),
  *   initial: 'idle',
  *   context: {},
  *   states: {
- *     idle: {
- *       on: {
- *         load: (msg, { transition, runner }) => {
- *           segments.forEach(s => runner.schedule(new Task(...)));
- *           transition('loading');
- *         }
- *       }
- *     },
- *     loading: {
- *       onSettled: 'idle',
- *       on: {
- *         load: (msg, { runner }) => {
- *           runner.abortAll();
- *           segments.forEach(s => runner.schedule(new Task(...)));
- *         }
- *       }
- *     }
+ *   idle: {
+ *   on: {
+ *   load: (msg, { transition, runner }) => {
+ *   segments.forEach(s => runner.schedule(new Task(...)));
+ *   transition('loading');
+ *   }
+ *   }
+ *   },
+ *   loading: {
+ *   onSettled: 'idle',
+ *   on: {
+ *   load: (msg, { runner }) => {
+ *   runner.abortAll();
+ *   segments.forEach(s => runner.schedule(new Task(...)));
+ *   }
+ *   }
+ *   }
  *   }
- * });
+ *   });
  */
 declare function createMachineActor<UserState extends string, Context extends object, Message extends {
   type: string;

package/dist/dev/core/actors/create-machine-actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-machine-actor.d.ts","names":[],"sources":["../../../../src/core/actors/create-machine-actor.ts"],"mappings":";;;;;;UAYiB;EACf,SAAS,cAAc,eAAe,MAAM,SAAS,OAAO,OAAO,QAAQ;EAC3E;EACA;EACA,YAAY;;;;;;;KAYF,eACV,0BACA,wBACA,6BAA6B;EAE7B,aAAa,IAAI;;EAEjB,SAAS;;;;;;;EAOT,kBAAkB;EAClB,aAAa,MAAM;KAChB,mCAAkC;EAAM,QAAQ;;;;;KAKzC,qBACV,0BACA,wBACA;EAAkB;GAClB,6BAA6B;;;;;;;EAQ7B,YAAY;;EAEZ,QACG,KAAK,WAAW,cACf,SAAS,QAAQ;IAAW,MAAM;MAClC,KAAK,eAAe,WAAW,SAAS;;;;;;;;KAWlC,gBACV,0BACA,wBACA;EAAkB;GAClB,6BAA6B;;;;;;;;EAS7B,SAAS;;EAET,SAAS;;EAET,SAAS;;;;;EAKT,QAAQ,QAAQ,OAAO,WAAW,qBAAqB,WAAW,SAAS,SAAS;;;UAQrE,aAAa,sBAAsB,wBAAwB;EAAkB;WACpF,YAAY,OAAO;EAC3B,KAAK,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8CA,mBACd,0BACA,wBACA;EAAkB;GAClB,6BAA6B,qCAE7B,KAAK,gBAAgB,WAAW,SAAS,SAAS,iBACjD,aAAa,yBAAyB,SAAS"}
+{"version":3,"file":"create-machine-actor.d.ts","names":[],"sources":["../../../../src/core/actors/create-machine-actor.ts"],"mappings":";;;;UAUiB;EACf,SAAS,cAAc,eAAe,MAAM,SAAS,OAAO,OAAO,QAAQ;EAC3E;EACA;EACA,YAAY;;;;;;KAWF,eACV,0BACA,wBACA,6BAA6B;EAE7B,aAAa,IAAI;;EAEjB,SAAS;;;;;;EAMT,kBAAkB;EAClB,aAAa,MAAM;KAChB,mCAAkC;EAAM,QAAQ;;;KAGzC,qBACV,0BACA,wBACA;EAAkB;GAClB,6BAA6B;;;;;;EAO7B,YAAY;;EAEZ,QACG,KAAK,WAAW,cACf,SAAS,QAAQ;IAAW,MAAM;MAClC,KAAK,eAAe,WAAW,SAAS;;;;;;;;KAWlC,gBACV,0BACA,wBACA;EAAkB;GAClB,6BAA6B;;;;;;;;EAS7B,SAAS;;EAET,SAAS;;EAET,SAAS;;;;;EAKT,QAAQ,QAAQ,OAAO,WAAW,qBAAqB,WAAW,SAAS,SAAS;;;UAQrE,aACf,sBACA,wBACA;EAAkB;WACV,YAAY,OAAO;EAC3B,KAAK,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4CA,mBACd,0BACA,wBACA;EAAkB;GAClB,6BAA6B,qCAE7B,KAAK,gBAAgB,WAAW,SAAS,SAAS,iBACjD,aAAa,yBAAyB,SAAS"}

package/dist/dev/core/actors/create-machine-actor.js

@@ -4,41 +4,39 @@ import { createMachineCore } from "../machine.js";
 /**
 * Creates a message-driven actor from a declarative definition.
 *
-* The actor owns a reactive snapshot signal (state + context), an optional
-* runner, and dispatches incoming messages to per-state handlers. `'destroyed'`
-* is always the implicit terminal state — `destroy()` transitions there
+* The actor owns a reactive snapshot signal (state + context), an optional runner, and dispatches incoming messages to
+* per-state handlers. `'destroyed'` is always the implicit terminal state — `destroy()` transitions there
 * unconditionally and all subsequent `send()` calls are no-ops.
 *
-* When a state declares `onSettled`, the framework calls `runner.whenSettled()`
-* after the handler returns. The runner owns the generation-token logic — if
-* new tasks are scheduled before the current batch settles, the callback is
+* When a state declares `onSettled`, the framework calls `runner.whenSettled()` after the handler returns. The runner
+* owns the generation-token logic — if new tasks are scheduled before the current batch settles, the callback is
 * automatically superseded.
 *
 * @example
-* const actor = createMachineActor({
+*   const actor = createMachineActor({
 *   runner: () => new SerialRunner(),
 *   initial: 'idle',
 *   context: {},
 *   states: {
-*     idle: {
-*       on: {
-*         load: (msg, { transition, runner }) => {
-*           segments.forEach(s => runner.schedule(new Task(...)));
-*           transition('loading');
-*         }
-*       }
-*     },
-*     loading: {
-*       onSettled: 'idle',
-*       on: {
-*         load: (msg, { runner }) => {
-*           runner.abortAll();
-*           segments.forEach(s => runner.schedule(new Task(...)));
-*         }
-*       }
-*     }
+*   idle: {
+*   on: {
+*   load: (msg, { transition, runner }) => {
+*   segments.forEach(s => runner.schedule(new Task(...)));
+*   transition('loading');
 *   }
-* });
+*   }
+*   },
+*   loading: {
+*   onSettled: 'idle',
+*   on: {
+*   load: (msg, { runner }) => {
+*   runner.abortAll();
+*   segments.forEach(s => runner.schedule(new Task(...)));
+*   }
+*   }
+*   }
+*   }
+*   });
 */
 function createMachineActor(def) {
 	const runner = def.runner?.();

package/dist/dev/core/actors/create-machine-actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-machine-actor.js","names":[],"sources":["../../../../src/core/actors/create-machine-actor.ts"],"sourcesContent":["import { createMachineCore } from '../machine';\nimport { untrack, update } from '../signals/primitives';\nimport type { TaskLike } from '../tasks/task';\nimport type { ActorSnapshot, SignalActor } from './actor';\n\n// =============================================================================\n// Runner interfaces\n// =============================================================================\n\n/**\n * Minimal interface for any runner that can be used with createMachineActor.\n */\nexport interface RunnerLike {\n  schedule<Value = void, Err = unknown>(task: TaskLike<Value, Err>): Promise<Value>;\n  abortAll(): void;\n  destroy(): void;\n  whenSettled(callback: () => void): void;\n}\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * Context passed to message handlers.\n * `runner` is present and typed as the exact runner instance only when the\n * definition includes a runner factory.\n */\nexport type HandlerContext<\n  UserState extends string,\n  Context extends object,\n  RunnerFactory extends (() => RunnerLike) | undefined,\n> = {\n  transition: (to: UserState) => void;\n  /** Context snapshot captured at dispatch time. Stale after any `setContext` call. */\n  context: Context;\n  /**\n   * Live untracked read of the current context. Use in async task closures that\n   * execute after the handler returns — e.g. `getCtx: getContext` passed to tasks\n   * scheduled on the runner, so each task reads the context committed by the\n   * previous task rather than the stale snapshot from dispatch time.\n   */\n  getContext: () => Context;\n  setContext: (next: Context) => void;\n} & (RunnerFactory extends () => infer R ? { runner: R } : object);\n\n/**\n * Definition for a single user-defined state.\n */\nexport type ActorStateDefinition<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined,\n> = {\n  /**\n   * When the actor's runner settles while in this state, automatically\n   * transition to this state. The framework owns the generation-token logic —\n   * re-registering after each `runner.schedule()` call so that\n   * `abortAll()` + reschedule correctly supersedes stale callbacks.\n   */\n  onSettled?: UserState;\n  /** Message handlers active in this state. Messages with no handler are silently dropped. */\n  on?: {\n    [M in Message as M['type']]?: (\n      message: Extract<Message, { type: M['type'] }>,\n      ctx: HandlerContext<UserState, Context, RunnerFactory>\n    ) => void;\n  };\n};\n\n/**\n * Full actor definition passed to `createMachineActor`.\n *\n * `UserState` is the set of domain-meaningful states. `'destroyed'` is always\n * added by the framework as the implicit terminal state — do not include it here.\n */\nexport type ActorDefinition<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined = undefined,\n> = {\n  /**\n   * Runner factory — called once at `createMachineActor()` time.\n   * The runner lives for the full actor lifetime and is destroyed with it.\n   *\n   * @example\n   * runner: () => new SerialRunner()\n   */\n  runner?: RunnerFactory;\n  /** Initial state. */\n  initial: UserState;\n  /** Initial context. */\n  context: Context;\n  /**\n   * Per-state definitions. States with no definition silently drop all messages.\n   * All user-defined states must appear as keys in the `UserState` union.\n   */\n  states: Partial<Record<UserState, ActorStateDefinition<UserState, Context, Message, RunnerFactory>>>;\n};\n\n// =============================================================================\n// Live actor interface\n// =============================================================================\n\n/** Live actor instance returned by `createMachineActor`. */\nexport interface MessageActor<State extends string, Context extends object, Message extends { type: string }>\n  extends SignalActor<State, Context> {\n  send(message: Message): void;\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a message-driven actor from a declarative definition.\n *\n * The actor owns a reactive snapshot signal (state + context), an optional\n * runner, and dispatches incoming messages to per-state handlers. `'destroyed'`\n * is always the implicit terminal state — `destroy()` transitions there\n * unconditionally and all subsequent `send()` calls are no-ops.\n *\n * When a state declares `onSettled`, the framework calls `runner.whenSettled()`\n * after the handler returns. The runner owns the generation-token logic — if\n * new tasks are scheduled before the current batch settles, the callback is\n * automatically superseded.\n *\n * @example\n * const actor = createMachineActor({\n *   runner: () => new SerialRunner(),\n *   initial: 'idle',\n *   context: {},\n *   states: {\n *     idle: {\n *       on: {\n *         load: (msg, { transition, runner }) => {\n *           segments.forEach(s => runner.schedule(new Task(...)));\n *           transition('loading');\n *         }\n *       }\n *     },\n *     loading: {\n *       onSettled: 'idle',\n *       on: {\n *         load: (msg, { runner }) => {\n *           runner.abortAll();\n *           segments.forEach(s => runner.schedule(new Task(...)));\n *         }\n *       }\n *     }\n *   }\n * });\n */\nexport function createMachineActor<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined = undefined,\n>(\n  def: ActorDefinition<UserState, Context, Message, RunnerFactory>\n): MessageActor<UserState | 'destroyed', Context, Message> {\n  type FullState = UserState | 'destroyed';\n\n  const runner = def.runner?.() as RunnerLike | undefined;\n  const { snapshotSignal, getState, transition } = createMachineCore<FullState, ActorSnapshot<FullState, Context>>({\n    value: def.initial as FullState,\n    context: def.context,\n  });\n\n  const getContext = (): Context => untrack(() => snapshotSignal.get().context);\n\n  const setContext = (context: Context): void => {\n    update(snapshotSignal, { context });\n  };\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    send(message: Message): void {\n      const state = getState();\n      if (state === 'destroyed') return;\n      const stateDef = def.states[state as UserState];\n      const handler = stateDef?.on?.[message.type as keyof typeof stateDef.on] as\n        | ((msg: Message, ctx: HandlerContext<UserState, Context, RunnerFactory>) => void)\n        | undefined;\n      if (!handler) return;\n      handler(message, {\n        context: getContext(),\n        getContext,\n        transition: (to: UserState) => transition(to as FullState),\n        setContext,\n        ...(runner ? { runner } : {}),\n      } as HandlerContext<UserState, Context, RunnerFactory>);\n      // Register onSettled after the handler so we read the post-transition state.\n      const newState = getState();\n      if (newState !== 'destroyed') {\n        const newStateDef = def.states[newState as UserState];\n        if (newStateDef?.onSettled && runner) {\n          const targetState = newStateDef.onSettled as FullState;\n          runner.whenSettled(() => {\n            if (getState() !== newState) return;\n            transition(targetState);\n          });\n        }\n      }\n    },\n\n    destroy(): void {\n      if (getState() === 'destroyed') return;\n      runner?.destroy();\n      transition('destroyed');\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2JA,SAAgB,mBAMd,KACyD;CAGzD,MAAM,SAAS,IAAI,SAAS;CAC5B,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAgE;EAC/G,OAAO,IAAI;EACX,SAAS,IAAI;CACf,CAAC;CAED,MAAM,mBAA4B,cAAc,eAAe,IAAI,CAAC,CAAC,OAAO;CAE5E,MAAM,cAAc,YAA2B;EAC7C,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CACpC;CAEA,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EAEA,KAAK,SAAwB;GAC3B,MAAM,QAAQ,SAAS;GACvB,IAAI,UAAU,aAAa;GAE3B,MAAM,UADW,IAAI,OAAO,MACJ,EAAE,KAAK,QAAQ;GAGvC,IAAI,CAAC,SAAS;GACd,QAAQ,SAAS;IACf,SAAS,WAAW;IACpB;IACA,aAAa,OAAkB,WAAW,EAAe;IACzD;IACA,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;GAC7B,CAAsD;GAEtD,MAAM,WAAW,SAAS;GAC1B,IAAI,aAAa,aAAa;IAC5B,MAAM,cAAc,IAAI,OAAO;IAC/B,IAAI,aAAa,aAAa,QAAQ;KACpC,MAAM,cAAc,YAAY;KAChC,OAAO,kBAAkB;MACvB,IAAI,SAAS,MAAM,UAAU;MAC7B,WAAW,WAAW;KACxB,CAAC;IACH;GACF;EACF;EAEA,UAAgB;GACd,IAAI,SAAS,MAAM,aAAa;GAChC,QAAQ,QAAQ;GAChB,WAAW,WAAW;EACxB;CACF;AACF"}
+{"version":3,"file":"create-machine-actor.js","names":[],"sources":["../../../../src/core/actors/create-machine-actor.ts"],"sourcesContent":["import { createMachineCore } from '../machine';\nimport { untrack, update } from '../signals/primitives';\nimport type { TaskLike } from '../tasks/task';\nimport type { ActorSnapshot, SignalActor } from './actor';\n\n// =============================================================================\n// Runner interfaces\n// =============================================================================\n\n/** Minimal interface for any runner that can be used with createMachineActor. */\nexport interface RunnerLike {\n  schedule<Value = void, Err = unknown>(task: TaskLike<Value, Err>): Promise<Value>;\n  abortAll(): void;\n  destroy(): void;\n  whenSettled(callback: () => void): void;\n}\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * Context passed to message handlers. `runner` is present and typed as the exact runner instance only when the\n * definition includes a runner factory.\n */\nexport type HandlerContext<\n  UserState extends string,\n  Context extends object,\n  RunnerFactory extends (() => RunnerLike) | undefined,\n> = {\n  transition: (to: UserState) => void;\n  /** Context snapshot captured at dispatch time. Stale after any `setContext` call. */\n  context: Context;\n  /**\n   * Live untracked read of the current context. Use in async task closures that execute after the handler returns —\n   * e.g. `getCtx: getContext` passed to tasks scheduled on the runner, so each task reads the context committed by the\n   * previous task rather than the stale snapshot from dispatch time.\n   */\n  getContext: () => Context;\n  setContext: (next: Context) => void;\n} & (RunnerFactory extends () => infer R ? { runner: R } : object);\n\n/** Definition for a single user-defined state. */\nexport type ActorStateDefinition<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined,\n> = {\n  /**\n   * When the actor's runner settles while in this state, automatically transition to this state. The framework owns the\n   * generation-token logic — re-registering after each `runner.schedule()` call so that `abortAll()` + reschedule\n   * correctly supersedes stale callbacks.\n   */\n  onSettled?: UserState;\n  /** Message handlers active in this state. Messages with no handler are silently dropped. */\n  on?: {\n    [M in Message as M['type']]?: (\n      message: Extract<Message, { type: M['type'] }>,\n      ctx: HandlerContext<UserState, Context, RunnerFactory>\n    ) => void;\n  };\n};\n\n/**\n * Full actor definition passed to `createMachineActor`.\n *\n * `UserState` is the set of domain-meaningful states. `'destroyed'` is always added by the framework as the implicit\n * terminal state — do not include it here.\n */\nexport type ActorDefinition<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined = undefined,\n> = {\n  /**\n   * Runner factory — called once at `createMachineActor()` time. The runner lives for the full actor lifetime and is\n   * destroyed with it.\n   *\n   * @example\n   *   runner: () => new SerialRunner();\n   */\n  runner?: RunnerFactory;\n  /** Initial state. */\n  initial: UserState;\n  /** Initial context. */\n  context: Context;\n  /**\n   * Per-state definitions. States with no definition silently drop all messages. All user-defined states must appear as\n   * keys in the `UserState` union.\n   */\n  states: Partial<Record<UserState, ActorStateDefinition<UserState, Context, Message, RunnerFactory>>>;\n};\n\n// =============================================================================\n// Live actor interface\n// =============================================================================\n\n/** Live actor instance returned by `createMachineActor`. */\nexport interface MessageActor<\n  State extends string,\n  Context extends object,\n  Message extends { type: string },\n> extends SignalActor<State, Context> {\n  send(message: Message): void;\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a message-driven actor from a declarative definition.\n *\n * The actor owns a reactive snapshot signal (state + context), an optional runner, and dispatches incoming messages to\n * per-state handlers. `'destroyed'` is always the implicit terminal state — `destroy()` transitions there\n * unconditionally and all subsequent `send()` calls are no-ops.\n *\n * When a state declares `onSettled`, the framework calls `runner.whenSettled()` after the handler returns. The runner\n * owns the generation-token logic — if new tasks are scheduled before the current batch settles, the callback is\n * automatically superseded.\n *\n * @example\n *   const actor = createMachineActor({\n *   runner: () => new SerialRunner(),\n *   initial: 'idle',\n *   context: {},\n *   states: {\n *   idle: {\n *   on: {\n *   load: (msg, { transition, runner }) => {\n *   segments.forEach(s => runner.schedule(new Task(...)));\n *   transition('loading');\n *   }\n *   }\n *   },\n *   loading: {\n *   onSettled: 'idle',\n *   on: {\n *   load: (msg, { runner }) => {\n *   runner.abortAll();\n *   segments.forEach(s => runner.schedule(new Task(...)));\n *   }\n *   }\n *   }\n *   }\n *   });\n */\nexport function createMachineActor<\n  UserState extends string,\n  Context extends object,\n  Message extends { type: string },\n  RunnerFactory extends (() => RunnerLike) | undefined = undefined,\n>(\n  def: ActorDefinition<UserState, Context, Message, RunnerFactory>\n): MessageActor<UserState | 'destroyed', Context, Message> {\n  type FullState = UserState | 'destroyed';\n\n  const runner = def.runner?.() as RunnerLike | undefined;\n  const { snapshotSignal, getState, transition } = createMachineCore<FullState, ActorSnapshot<FullState, Context>>({\n    value: def.initial as FullState,\n    context: def.context,\n  });\n\n  const getContext = (): Context => untrack(() => snapshotSignal.get().context);\n\n  const setContext = (context: Context): void => {\n    update(snapshotSignal, { context });\n  };\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    send(message: Message): void {\n      const state = getState();\n      if (state === 'destroyed') return;\n\n      const stateDef = def.states[state as UserState];\n      const handler = stateDef?.on?.[message.type as keyof typeof stateDef.on] as\n        | ((msg: Message, ctx: HandlerContext<UserState, Context, RunnerFactory>) => void)\n        | undefined;\n      if (!handler) return;\n\n      handler(message, {\n        context: getContext(),\n        getContext,\n        transition: (to: UserState) => transition(to as FullState),\n        setContext,\n        ...(runner ? { runner } : {}),\n      } as HandlerContext<UserState, Context, RunnerFactory>);\n      // Register onSettled after the handler so we read the post-transition state.\n      const newState = getState();\n\n      if (newState !== 'destroyed') {\n        const newStateDef = def.states[newState as UserState];\n\n        if (newStateDef?.onSettled && runner) {\n          const targetState = newStateDef.onSettled as FullState;\n\n          runner.whenSettled(() => {\n            if (getState() !== newState) return;\n\n            transition(targetState);\n          });\n        }\n      }\n    },\n\n    destroy(): void {\n      if (getState() === 'destroyed') return;\n\n      runner?.destroy();\n      transition('destroyed');\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqJA,SAAgB,mBAMd,KACyD;CAGzD,MAAM,SAAS,IAAI,SAAS;CAC5B,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAAgE;EAC/G,OAAO,IAAI;EACX,SAAS,IAAI;CACf,CAAC;CAED,MAAM,mBAA4B,cAAc,eAAe,IAAI,CAAC,CAAC,OAAO;CAE5E,MAAM,cAAc,YAA2B;EAC7C,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CACpC;CAEA,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EAEA,KAAK,SAAwB;GAC3B,MAAM,QAAQ,SAAS;GACvB,IAAI,UAAU,aAAa;GAG3B,MAAM,UADW,IAAI,OAAO,MACJ,EAAE,KAAK,QAAQ;GAGvC,IAAI,CAAC,SAAS;GAEd,QAAQ,SAAS;IACf,SAAS,WAAW;IACpB;IACA,aAAa,OAAkB,WAAW,EAAe;IACzD;IACA,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;GAC7B,CAAsD;GAEtD,MAAM,WAAW,SAAS;GAE1B,IAAI,aAAa,aAAa;IAC5B,MAAM,cAAc,IAAI,OAAO;IAE/B,IAAI,aAAa,aAAa,QAAQ;KACpC,MAAM,cAAc,YAAY;KAEhC,OAAO,kBAAkB;MACvB,IAAI,SAAS,MAAM,UAAU;MAE7B,WAAW,WAAW;KACxB,CAAC;IACH;GACF;EACF;EAEA,UAAgB;GACd,IAAI,SAAS,MAAM,aAAa;GAEhC,QAAQ,QAAQ;GAChB,WAAW,WAAW;EACxB;CACF;AACF"}

package/dist/dev/core/actors/create-transition-actor.d.ts

@@ -4,13 +4,11 @@ import { Machine } from "../machine.js";
 /**
  * A reducer-shaped actor: `(context, message) => context`.
  *
- * No finite states — the snapshot carries `value: 'active' | 'destroyed'`
- * as a universal lifecycle marker rather than domain state. The interesting
- * state is entirely in the context, which is reactive via `snapshot`.
+ * No finite states — the snapshot carries `value: 'active' | 'destroyed'` as a universal lifecycle marker rather than
+ * domain state. The interesting state is entirely in the context, which is reactive via `snapshot`.
  *
- * Use this when the actor has context that needs to be reactive but no
- * meaningful state machine (e.g., a message-driven model with DOM side
- * effects). For actors that need per-state behavior, use `createMachineActor`.
+ * Use this when the actor has context that needs to be reactive but no meaningful state machine (e.g., a message-driven
+ * model with DOM side effects). For actors that need per-state behavior, use `createMachineActor`.
  */
 interface TransitionActor<Context extends object, Message extends {
   type: string;
@@ -20,18 +18,16 @@ interface TransitionActor<Context extends object, Message extends {
 /**
  * Creates a reducer-shaped actor from an initial context and a reducer function.
  *
- * The reducer receives the current context and a message and returns the next
- * context. Returning the same reference (by identity) skips the signal update —
- * so early-returning `context` unchanged is both the no-op and the optimization.
+ * The reducer receives the current context and a message and returns the next context. Returning the same reference (by
+ * identity) skips the signal update — so early-returning `context` unchanged is both the no-op and the optimization.
  *
- * Side effects (e.g. DOM mutations) may be performed inside the reducer.
- * They run synchronously before the signal is updated.
+ * Side effects (e.g. DOM mutations) may be performed inside the reducer. They run synchronously before the signal is
+ * updated.
  *
  * @example
- * const actor = createTransitionActor(
- *   { count: 0 },
- *   (context, message: { type: 'increment' }) => ({ count: context.count + 1 })
- * );
+ *   const actor = createTransitionActor({ count: 0 }, (context, message: { type: 'increment' }) => ({
+ *     count: context.count + 1,
+ *   }));
  */
 declare function createTransitionActor<Context extends object, Message extends {
   type: string;

package/dist/dev/core/actors/create-transition-actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-transition-actor.d.ts","names":[],"sources":["../../../../src/core/actors/create-transition-actor.ts"],"mappings":";;;;;;;;;;;;;;UAoBiB,gBAAgB,wBAAwB;EAAkB;WACjE,QAAQ,sCAAsC;EACtD,KAAK,SAAS;;;;;;;;;;;;;;;;;;iBAuBA,sBAAsB,wBAAwB;EAAkB;GAC9E,gBAAgB,SAChB,UAAU,SAAS,SAAS,SAAS,YAAY,UAChD,gBAAgB,SAAS"}
+{"version":3,"file":"create-transition-actor.d.ts","names":[],"sources":["../../../../src/core/actors/create-transition-actor.ts"],"mappings":";;;;;;;;;;;;UAkBiB,gBAAgB,wBAAwB;EAAkB;WAAwB,QACjG,sCAAsC;EAEtC,KAAK,SAAS;;;;;;;;;;;;;;;;iBAqBA,sBAAsB,wBAAwB;EAAkB;GAC9E,gBAAgB,SAChB,UAAU,SAAS,SAAS,SAAS,YAAY,UAChD,gBAAgB,SAAS"}

package/dist/dev/core/actors/create-transition-actor.js

@@ -4,18 +4,16 @@ import { createMachineCore } from "../machine.js";
 /**
 * Creates a reducer-shaped actor from an initial context and a reducer function.
 *
-* The reducer receives the current context and a message and returns the next
-* context. Returning the same reference (by identity) skips the signal update —
-* so early-returning `context` unchanged is both the no-op and the optimization.
+* The reducer receives the current context and a message and returns the next context. Returning the same reference (by
+* identity) skips the signal update — so early-returning `context` unchanged is both the no-op and the optimization.
 *
-* Side effects (e.g. DOM mutations) may be performed inside the reducer.
-* They run synchronously before the signal is updated.
+* Side effects (e.g. DOM mutations) may be performed inside the reducer. They run synchronously before the signal is
+* updated.
 *
 * @example
-* const actor = createTransitionActor(
-*   { count: 0 },
-*   (context, message: { type: 'increment' }) => ({ count: context.count + 1 })
-* );
+*   const actor = createTransitionActor({ count: 0 }, (context, message: { type: 'increment' }) => ({
+*     count: context.count + 1,
+*   }));
 */
 function createTransitionActor(initialContext, reducer) {
 	const { snapshotSignal, getState, transition } = createMachineCore({

package/dist/dev/core/actors/create-transition-actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-transition-actor.js","names":[],"sources":["../../../../src/core/actors/create-transition-actor.ts"],"sourcesContent":["import type { Machine } from '../machine';\nimport { createMachineCore } from '../machine';\nimport { untrack, update } from '../signals/primitives';\nimport type { ActorSnapshot } from './actor';\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * A reducer-shaped actor: `(context, message) => context`.\n *\n * No finite states — the snapshot carries `value: 'active' | 'destroyed'`\n * as a universal lifecycle marker rather than domain state. The interesting\n * state is entirely in the context, which is reactive via `snapshot`.\n *\n * Use this when the actor has context that needs to be reactive but no\n * meaningful state machine (e.g., a message-driven model with DOM side\n * effects). For actors that need per-state behavior, use `createMachineActor`.\n */\nexport interface TransitionActor<Context extends object, Message extends { type: string }>\n  extends Machine<ActorSnapshot<'active' | 'destroyed', Context>> {\n  send(message: Message): void;\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a reducer-shaped actor from an initial context and a reducer function.\n *\n * The reducer receives the current context and a message and returns the next\n * context. Returning the same reference (by identity) skips the signal update —\n * so early-returning `context` unchanged is both the no-op and the optimization.\n *\n * Side effects (e.g. DOM mutations) may be performed inside the reducer.\n * They run synchronously before the signal is updated.\n *\n * @example\n * const actor = createTransitionActor(\n *   { count: 0 },\n *   (context, message: { type: 'increment' }) => ({ count: context.count + 1 })\n * );\n */\nexport function createTransitionActor<Context extends object, Message extends { type: string }>(\n  initialContext: Context,\n  reducer: (context: Context, message: Message) => Context\n): TransitionActor<Context, Message> {\n  const { snapshotSignal, getState, transition } = createMachineCore<\n    'active' | 'destroyed',\n    ActorSnapshot<'active' | 'destroyed', Context>\n  >({ value: 'active', context: initialContext });\n\n  const getContext = (): Context => untrack(() => snapshotSignal.get().context);\n  const setContext = (context: Context): void => update(snapshotSignal, { context });\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    send(message: Message): void {\n      if (getState() === 'destroyed') return;\n      const context = getContext();\n      const newContext = reducer(context, message);\n      if (newContext !== context) setContext(newContext);\n    },\n\n    destroy(): void {\n      if (getState() === 'destroyed') return;\n      transition('destroyed');\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,sBACd,gBACA,SACmC;CACnC,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAG/C;EAAE,OAAO;EAAU,SAAS;CAAe,CAAC;CAE9C,MAAM,mBAA4B,cAAc,eAAe,IAAI,CAAC,CAAC,OAAO;CAC5E,MAAM,cAAc,YAA2B,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CAEjF,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EAEA,KAAK,SAAwB;GAC3B,IAAI,SAAS,MAAM,aAAa;GAChC,MAAM,UAAU,WAAW;GAC3B,MAAM,aAAa,QAAQ,SAAS,OAAO;GAC3C,IAAI,eAAe,SAAS,WAAW,UAAU;EACnD;EAEA,UAAgB;GACd,IAAI,SAAS,MAAM,aAAa;GAChC,WAAW,WAAW;EACxB;CACF;AACF"}
+{"version":3,"file":"create-transition-actor.js","names":[],"sources":["../../../../src/core/actors/create-transition-actor.ts"],"sourcesContent":["import type { Machine } from '../machine';\nimport { createMachineCore } from '../machine';\nimport { untrack, update } from '../signals/primitives';\nimport type { ActorSnapshot } from './actor';\n\n// =============================================================================\n// Definition types\n// =============================================================================\n\n/**\n * A reducer-shaped actor: `(context, message) => context`.\n *\n * No finite states — the snapshot carries `value: 'active' | 'destroyed'` as a universal lifecycle marker rather than\n * domain state. The interesting state is entirely in the context, which is reactive via `snapshot`.\n *\n * Use this when the actor has context that needs to be reactive but no meaningful state machine (e.g., a message-driven\n * model with DOM side effects). For actors that need per-state behavior, use `createMachineActor`.\n */\nexport interface TransitionActor<Context extends object, Message extends { type: string }> extends Machine<\n  ActorSnapshot<'active' | 'destroyed', Context>\n> {\n  send(message: Message): void;\n}\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Creates a reducer-shaped actor from an initial context and a reducer function.\n *\n * The reducer receives the current context and a message and returns the next context. Returning the same reference (by\n * identity) skips the signal update — so early-returning `context` unchanged is both the no-op and the optimization.\n *\n * Side effects (e.g. DOM mutations) may be performed inside the reducer. They run synchronously before the signal is\n * updated.\n *\n * @example\n *   const actor = createTransitionActor({ count: 0 }, (context, message: { type: 'increment' }) => ({\n *     count: context.count + 1,\n *   }));\n */\nexport function createTransitionActor<Context extends object, Message extends { type: string }>(\n  initialContext: Context,\n  reducer: (context: Context, message: Message) => Context\n): TransitionActor<Context, Message> {\n  const { snapshotSignal, getState, transition } = createMachineCore<\n    'active' | 'destroyed',\n    ActorSnapshot<'active' | 'destroyed', Context>\n  >({ value: 'active', context: initialContext });\n\n  const getContext = (): Context => untrack(() => snapshotSignal.get().context);\n  const setContext = (context: Context): void => update(snapshotSignal, { context });\n\n  return {\n    get snapshot() {\n      return snapshotSignal;\n    },\n\n    send(message: Message): void {\n      if (getState() === 'destroyed') return;\n\n      const context = getContext();\n      const newContext = reducer(context, message);\n\n      if (newContext !== context) setContext(newContext);\n    },\n\n    destroy(): void {\n      if (getState() === 'destroyed') return;\n\n      transition('destroyed');\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA0CA,SAAgB,sBACd,gBACA,SACmC;CACnC,MAAM,EAAE,gBAAgB,UAAU,eAAe,kBAG/C;EAAE,OAAO;EAAU,SAAS;CAAe,CAAC;CAE9C,MAAM,mBAA4B,cAAc,eAAe,IAAI,CAAC,CAAC,OAAO;CAC5E,MAAM,cAAc,YAA2B,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CAEjF,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EAEA,KAAK,SAAwB;GAC3B,IAAI,SAAS,MAAM,aAAa;GAEhC,MAAM,UAAU,WAAW;GAC3B,MAAM,aAAa,QAAQ,SAAS,OAAO;GAE3C,IAAI,eAAe,SAAS,WAAW,UAAU;EACnD;EAEA,UAAgB;GACd,IAAI,SAAS,MAAM,aAAa;GAEhC,WAAW,WAAW;EACxB;CACF;AACF"}