@reicek/neataptic-ts 0.1.25 → 0.1.26

package/test/examples/flappy_bird/browser-entry/playback/README.md

@@ -95,13 +95,6 @@ These types describe the moving pieces of one playback episode: the public
 summary returned at the end, the mutable loop bookkeeping used while frames
 are streaming, and the session context mirrored locally in the browser.
 
-### PlaybackEpisodeSummary
-
-Public aggregate playback summary returned after one episode completes.
-
-The summary captures the headline outcomes of the just-finished population
-run without exposing all internal frame-by-frame details.
-
 ### PlaybackChampionChangedEvent
 
 Event emitted when the current playback champion changes.
@@ -109,13 +102,19 @@ Event emitted when the current playback champion changes.
 The event identifies which playback bird is currently highlighted as the red
 bird so the side-panel network view can stay synchronized with the renderer.
 
-### PlaybackMutableSummary
+### PlaybackEpisodeSummary
 
-Mutable playback summary extended with latest leader telemetry fallbacks.
+Public aggregate playback summary returned after one episode completes.
 
-During playback the browser may need temporary "latest known" values before
-the worker emits final aggregate statistics, so the mutable form carries both
-final fields and rolling fallbacks.
+The summary captures the headline outcomes of the just-finished population
+run without exposing all internal frame-by-frame details.
+
+### PlaybackIterationContext
+
+Shared dependencies and mutable state used by one playback iteration.
+
+Grouping these fields into one context object keeps the iteration services
+declarative and avoids long parameter lists across the playback loop.
 
 ### PlaybackLoopState
 
@@ -125,6 +124,14 @@ This is the browser-side state machine for the playback loop: how much
 simulation budget is being requested, whether the episode has finished, and
 what aggregate summary has been observed so far.
 
+### PlaybackMutableSummary
+
+Mutable playback summary extended with latest leader telemetry fallbacks.
+
+During playback the browser may need temporary "latest known" values before
+the worker emits final aggregate statistics, so the mutable form carries both
+final fields and rolling fallbacks.
+
 ### PlaybackSessionContext
 
 Shared mutable playback state mirrored locally while worker playback runs.
@@ -133,13 +140,6 @@ The worker remains the source of truth for simulation, but the browser keeps
 lightweight mirrored state for rendering, trail accumulation, and loop
 orchestration.
 
-### PlaybackIterationContext
-
-Shared dependencies and mutable state used by one playback iteration.
-
-Grouping these fields into one context object keeps the iteration services
-declarative and avoids long parameter lists across the playback loop.
-
 ## browser-entry/playback/playback.session.services.ts
 
 Session initialization and summary-folding helpers for playback.
@@ -149,23 +149,18 @@ These services answer three orchestration questions:
 2. What local mirror state should exist before the first worker snapshot?
 3. How should mutable loop state be folded back into a public summary?
 
-### resolvePlaybackViewportDimensions
+### createInitialPlaybackLoopState
 
 ```ts
-resolvePlaybackViewportDimensions(
-  canvas: HTMLCanvasElement,
-): { visibleWorldWidthPx: number; visibleWorldHeightPx: number; }
+createInitialPlaybackLoopState(): PlaybackLoopState
 ```
 
-Resolves the current visible playback viewport dimensions from the canvas.
-
-Playback sizing is derived from the live canvas rather than a hard-coded
-constant so resizing can flow into the worker/session boundary cleanly.
+Creates the mutable loop state used while processing playback steps.
 
-Parameters:
-- `canvas` - - Target playback canvas.
+This is the browser's running notebook for one episode: budget, completion
+flag, and the latest known aggregate outcome metrics.
 
-Returns: Visible world width and height in pixels.
+Returns: Initialized loop state and aggregate summary values.
 
 ### createInitialRenderState
 
@@ -199,19 +194,6 @@ playback frames are observed.
 
 Returns: Empty trail state for all birds.
 
-### createInitialPlaybackLoopState
-
-```ts
-createInitialPlaybackLoopState(): PlaybackLoopState
-```
-
-Creates the mutable loop state used while processing playback steps.
-
-This is the browser's running notebook for one episode: budget, completion
-flag, and the latest known aggregate outcome metrics.
-
-Returns: Initialized loop state and aggregate summary values.
-
 ### initializePlaybackSessionContext
 
 ```ts
@@ -233,43 +215,61 @@ Parameters:
 
 Returns: Session context shared across the playback loop.
 
-### syncPlaybackViewportDimensions
+### resolvePlaybackEpisodeSummary
 
 ```ts
-syncPlaybackViewportDimensions(
+resolvePlaybackEpisodeSummary(
+  summary: PlaybackMutableSummary,
+): PlaybackEpisodeSummary
+```
+
+Folds the mutable loop summary into the public playback summary shape.
+
+The public summary is intentionally smaller than the internal loop state. It
+exposes the outcome, not the browser's intermediate bookkeeping.
+
+Parameters:
+- `summary` - - Mutable loop summary accumulated during playback.
+
+Returns: Public playback episode summary.
+
+### resolvePlaybackViewportDimensions
+
+```ts
+resolvePlaybackViewportDimensions(
   canvas: HTMLCanvasElement,
-  renderState: PopulationRenderState,
-): void
+): { visibleWorldWidthPx: number; visibleWorldHeightPx: number; }
 ```
 
-Synchronizes the render state viewport fields with the current canvas size.
+Resolves the current visible playback viewport dimensions from the canvas.
 
-Playback can continue while the canvas size changes, so the browser refreshes
-its local viewport mirror rather than assuming dimensions stay fixed.
+Playback sizing is derived from the live canvas rather than a hard-coded
+constant so resizing can flow into the worker/session boundary cleanly.
 
 Parameters:
 - `canvas` - - Target playback canvas.
-- `renderState` - - Mutable render state updated in place.
 
-Returns: Nothing.
+Returns: Visible world width and height in pixels.
 
-### resolvePlaybackEpisodeSummary
+### syncPlaybackViewportDimensions
 
 ```ts
-resolvePlaybackEpisodeSummary(
-  summary: PlaybackMutableSummary,
-): PlaybackEpisodeSummary
+syncPlaybackViewportDimensions(
+  canvas: HTMLCanvasElement,
+  renderState: PopulationRenderState,
+): void
 ```
 
-Folds the mutable loop summary into the public playback summary shape.
+Synchronizes the render state viewport fields with the current canvas size.
 
-The public summary is intentionally smaller than the internal loop state. It
-exposes the outcome, not the browser's intermediate bookkeeping.
+Playback can continue while the canvas size changes, so the browser refreshes
+its local viewport mirror rather than assuming dimensions stay fixed.
 
 Parameters:
-- `summary` - - Mutable loop summary accumulated during playback.
+- `canvas` - - Target playback canvas.
+- `renderState` - - Mutable render state updated in place.
 
-Returns: Public playback episode summary.
+Returns: Nothing.
 
 ## browser-entry/playback/playback.loop.service.ts
 
@@ -295,135 +295,135 @@ Returns: Promise resolved on next animation frame.
 
 ## browser-entry/playback/playback.iteration.services.ts
 
-### runPlaybackLoop
+### applyPlaybackStepSnapshot
 
 ```ts
-runPlaybackLoop(
-  iterationContext: PlaybackIterationContext,
-): Promise<void>
+applyPlaybackStepSnapshot(
+  sessionContext: PlaybackSessionContext,
+  snapshot: EvolutionPlaybackStepSnapshot,
+): void
 ```
 
-Runs playback iterations until the worker reports that the episode is done.
+Applies the latest worker snapshot to render state and trail caches.
 
 Parameters:
-- `iterationContext` - - Shared loop dependencies and mutable playback state.
+- `sessionContext` - - Shared mutable playback session state.
+- `snapshot` - - Worker snapshot for the current playback batch.
 
 Returns: Nothing.
 
-### runPlaybackIteration
+### emitChampionChangedEvent
 
 ```ts
-runPlaybackIteration(
+emitChampionChangedEvent(
   iterationContext: PlaybackIterationContext,
-): Promise<void>
+): void
 ```
 
-Executes one playback iteration from viewport sync through render pacing.
+Emits a champion-changed event when the red-bird champion changes.
+
+The detector compares the newly resolved champion bird index against the
+previously displayed champion index. This keeps the side panel aligned with
+the red bird even when leadership changes because the old champion dies.
 
 Parameters:
 - `iterationContext` - - Shared loop dependencies and mutable playback state.
 
 Returns: Nothing.
 
-### requestPlaybackStepPayload
+### emitPlaybackChampionChanged
 
 ```ts
-requestPlaybackStepPayload(
-  iterationContext: PlaybackIterationContext,
-): Promise<{ requestId: number; snapshot: EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; }>
+emitPlaybackChampionChanged(
+  onChampionChanged: ((event: PlaybackChampionChangedEvent) => void) | undefined,
+  championBirdIndex: number,
+): void
 ```
 
-Requests one playback step batch from the evolution worker.
+Calls the optional playback champion-changed callback with a structured payload.
 
 Parameters:
-- `iterationContext` - - Shared loop dependencies and mutable playback state.
+- `onChampionChanged` - - Optional runtime callback.
+- `championBirdIndex` - - Current champion bird index.
 
-Returns: Worker playback step payload for the current iteration.
+Returns: Nothing.
 
-### applyPlaybackStepSnapshot
+### emitPlaybackFrameStats
 
 ```ts
-applyPlaybackStepSnapshot(
-  sessionContext: PlaybackSessionContext,
-  snapshot: EvolutionPlaybackStepSnapshot,
+emitPlaybackFrameStats(
+  iterationContext: PlaybackIterationContext,
+  playbackStepPayload: { requestId: number; snapshot: EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; },
 ): void
 ```
 
-Applies the latest worker snapshot to render state and trail caches.
+Resolves leader telemetry and emits the public frame-stats callback.
 
 Parameters:
-- `sessionContext` - - Shared mutable playback session state.
-- `snapshot` - - Worker snapshot for the current playback batch.
+- `iterationContext` - - Shared loop dependencies and mutable playback state.
+- `playbackStepPayload` - - Worker playback result for the current iteration.
 
 Returns: Nothing.
 
-### emitChampionChangedEvent
+### requestPlaybackStepPayload
 
 ```ts
-emitChampionChangedEvent(
+requestPlaybackStepPayload(
   iterationContext: PlaybackIterationContext,
-): void
+): Promise<{ requestId: number; snapshot: EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; }>
 ```
 
-Emits a champion-changed event when the red-bird champion changes.
-
-The detector compares the newly resolved champion bird index against the
-previously displayed champion index. This keeps the side panel aligned with
-the red bird even when leadership changes because the old champion dies.
+Requests one playback step batch from the evolution worker.
 
 Parameters:
 - `iterationContext` - - Shared loop dependencies and mutable playback state.
 
-Returns: Nothing.
+Returns: Worker playback step payload for the current iteration.
 
-### emitPlaybackFrameStats
+### runPlaybackIteration
 
 ```ts
-emitPlaybackFrameStats(
+runPlaybackIteration(
   iterationContext: PlaybackIterationContext,
-  playbackStepPayload: { requestId: number; snapshot: EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; },
-): void
+): Promise<void>
 ```
 
-Resolves leader telemetry and emits the public frame-stats callback.
+Executes one playback iteration from viewport sync through render pacing.
 
 Parameters:
 - `iterationContext` - - Shared loop dependencies and mutable playback state.
-- `playbackStepPayload` - - Worker playback result for the current iteration.
 
 Returns: Nothing.
 
-### updatePlaybackLoopCompletion
+### runPlaybackLoop
 
 ```ts
-updatePlaybackLoopCompletion(
-  loopState: PlaybackLoopState,
-  playbackStepPayload: { requestId: number; snapshot: EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; },
-): void
+runPlaybackLoop(
+  iterationContext: PlaybackIterationContext,
+): Promise<void>
 ```
 
-Updates the loop summary when the worker reports playback completion.
+Runs playback iterations until the worker reports that the episode is done.
 
 Parameters:
-- `loopState` - - Mutable playback loop state.
-- `playbackStepPayload` - - Worker playback result for the current iteration.
+- `iterationContext` - - Shared loop dependencies and mutable playback state.
 
 Returns: Nothing.
 
-### emitPlaybackChampionChanged
+### updatePlaybackLoopCompletion
 
 ```ts
-emitPlaybackChampionChanged(
-  onChampionChanged: ((event: PlaybackChampionChangedEvent) => void) | undefined,
-  championBirdIndex: number,
+updatePlaybackLoopCompletion(
+  loopState: PlaybackLoopState,
+  playbackStepPayload: { requestId: number; snapshot: EvolutionPlaybackStepSnapshot; instrumentation?: { activationCallsPerFrame: number; simulationStepsPerRaf: number; } | undefined; done: boolean; averagePipesPassed?: number | undefined; p90FramesSurvived?: number | undefined; winnerPipesPassed?: number | undefined; winnerFramesSurvived?: number | undefined; },
 ): void
 ```
 
-Calls the optional playback champion-changed callback with a structured payload.
+Updates the loop summary when the worker reports playback completion.
 
 Parameters:
-- `onChampionChanged` - - Optional runtime callback.
-- `championBirdIndex` - - Current champion bird index.
+- `loopState` - - Mutable playback loop state.
+- `playbackStepPayload` - - Worker playback result for the current iteration.
 
 Returns: Nothing.
 
@@ -516,6 +516,27 @@ Returns: Nothing.
 
 ## browser-entry/playback/playback.render.utils.ts
 
+### PlaybackBirdRenderStyle
+
+Pure render-style result for one bird body draw pass.
+
+### resolveBirdRenderStyle
+
+```ts
+resolveBirdRenderStyle(
+  birdIndex: number,
+  championBirdIndex: number,
+): PlaybackBirdRenderStyle
+```
+
+Resolves opacity, body color, and champion marker for one bird.
+
+Parameters:
+- `birdIndex` - - Index of the bird currently being rendered.
+- `championBirdIndex` - - Resolved champion index for the frame.
+
+Returns: Pure style payload used by the render service.
+
 ### resolveChampionBirdIndex
 
 ```ts
@@ -534,28 +555,26 @@ Parameters:
 
 Returns: Champion index or `-1` when no bird is alive.
 
-### resolveBirdRenderStyle
+## browser-entry/playback/playback.trail.utils.ts
+
+### clamp01
 
 ```ts
-resolveBirdRenderStyle(
-  birdIndex: number,
-  championBirdIndex: number,
-): PlaybackBirdRenderStyle
+clamp01(
+  value: number,
+): number
 ```
 
-Resolves opacity, body color, and champion marker for one bird.
-
-Parameters:
-- `birdIndex` - - Index of the bird currently being rendered.
-- `championBirdIndex` - - Resolved champion index for the frame.
-
-Returns: Pure style payload used by the render service.
+Clamps a number to the inclusive [0, 1] range.
 
-### PlaybackBirdRenderStyle
+The trail renderer combines several normalized fade factors, so keeping this
+utility local to the module makes the intent obvious: every opacity channel
+must remain safe for direct canvas alpha use.
 
-Pure render-style result for one bird body draw pass.
+Parameters:
+- `value` - - Candidate value.
 
-## browser-entry/playback/playback.trail.utils.ts
+Returns: Clamped value.
 
 ### pushChampionTrailPoint
 
@@ -607,31 +626,12 @@ Parameters:
 
 Returns: Nothing.
 
-Example:
-
-```ts
-const trailPoints = [{ frameIndex: 10, yPx: 140 }];
-pushTrailPoint(trailPoints, 11, 136, 2);
-```
-
-### clamp01
-
-```ts
-clamp01(
-  value: number,
-): number
-```
-
-Clamps a number to the inclusive [0, 1] range.
-
-The trail renderer combines several normalized fade factors, so keeping this
-utility local to the module makes the intent obvious: every opacity channel
-must remain safe for direct canvas alpha use.
-
-Parameters:
-- `value` - - Candidate value.
+Example:
 
-Returns: Clamped value.
+```ts
+const trailPoints = [{ frameIndex: 10, yPx: 140 }];
+pushTrailPoint(trailPoints, 11, 136, 2);
+```
 
 ### resolveEdgeOpacityFactor
 
@@ -718,6 +718,14 @@ Shared playback utility types for the browser-entry subsystem.
 These types support rendering concerns that cut across multiple playback
 helpers, such as edge-aware trail fading and cached parallax backgrounds.
 
+### PlaybackEdgeBounds
+
+Axis-aligned visible world bounds used for edge-aware trail fading.
+
+Trail rendering needs a quick answer to "is this point still visually inside
+the active world rectangle?" so fading logic can taper paths near the edges
+instead of drawing abrupt cutoffs.
+
 ### PlaybackStarfieldLayerSpec
 
 Declarative recipe for building one cached starfield parallax layer.
@@ -735,14 +743,6 @@ parallax backgrounds during playback.
 Separating the image type from the tile record lets the same starfield logic
 work with ordinary canvases and `OffscreenCanvas` when available.
 
-### PlaybackEdgeBounds
-
-Axis-aligned visible world bounds used for edge-aware trail fading.
-
-Trail rendering needs a quick answer to "is this point still visually inside
-the active world rectangle?" so fading logic can taper paths near the edges
-instead of drawing abrupt cutoffs.
-
 ## browser-entry/playback/playback.starfield.types.ts
 
 Starfield and parallax rendering contracts for playback backgrounds.
@@ -751,22 +751,12 @@ The playback view uses a cached layered starfield to add depth without paying
 a large per-frame rendering cost. These types define the tile, layer, and
 deterministic placement data needed for that effect.
 
-### StarTileImage
-
-Shared type contract for starfield tile rendering layers.
-
-A tile is pre-rendered and repeated horizontally to draw efficient
-parallax backgrounds during playback.
-
-### StarTile
-
-Shared type contract for starfield tile rendering layers.
+### CreateStarTileCanvasOptions
 
-A tile is pre-rendered and repeated horizontally to draw efficient
-parallax backgrounds during playback.
+Input contract for pre-rendering one deterministic starfield tile.
 
-Separating the image type from the tile record lets the same starfield logic
-work with ordinary canvases and `OffscreenCanvas` when available.
+The generated tile is cached and repeated horizontally during playback,
+so every field here affects both the visual look and the parallax cost.
 
 ### PlaybackStarfieldLayerSpec
 
@@ -775,13 +765,6 @@ Declarative recipe for building one cached starfield parallax layer.
 Each layer spec describes how dense, bright, blurred, and fast one visual
 depth plane should feel.
 
-### CreateStarTileCanvasOptions
-
-Input contract for pre-rendering one deterministic starfield tile.
-
-The generated tile is cached and repeated horizontally during playback,
-so every field here affects both the visual look and the parallax cost.
-
 ### StarfieldCanvasDimensions
 
 Normalized canvas dimensions used by browser and offscreen tile creation.
@@ -797,6 +780,23 @@ Deterministic placement and appearance for one rendered star sprite.
 Determinism matters here because cached starfield tiles should remain stable
 across redraws instead of sparkling randomly every frame.
 
+### StarTile
+
+Shared type contract for starfield tile rendering layers.
+
+A tile is pre-rendered and repeated horizontally to draw efficient
+parallax backgrounds during playback.
+
+Separating the image type from the tile record lets the same starfield logic
+work with ordinary canvases and `OffscreenCanvas` when available.
+
+### StarTileImage
+
+Shared type contract for starfield tile rendering layers.
+
+A tile is pre-rendered and repeated horizontally to draw efficient
+parallax backgrounds during playback.
+
 ## browser-entry/playback/playback.starfield.service.ts
 
 ### resolveStarfieldTiles
@@ -816,20 +816,20 @@ Returns: Ordered far/mid/near starfield tiles.
 
 ## browser-entry/playback/playback.starfield.services.ts
 
-### createStarTileCanvas
+### createCanvasSizeFallback
 
 ```ts
-createStarTileCanvas(
-  options: CreateStarTileCanvasOptions,
-): StarTileImage
+createCanvasSizeFallback(
+  canvasDimensions: StarfieldCanvasDimensions,
+): HTMLCanvasElement
 ```
 
-Pre-renders a deterministic tile that can be reused across animation frames.
+Creates a size-only fallback so non-browser tests can skip rendering safely.
 
 Parameters:
-- `options` - - Declarative drawing recipe for one parallax layer.
+- `canvasDimensions` - - Already-normalized pixel dimensions.
 
-Returns: Canvas image source containing the rendered star strip.
+Returns: Minimal canvas-shaped object cast to the compatible return type.
 
 ### createCompatibleCanvas
 
@@ -848,63 +848,63 @@ Parameters:
 
 Returns: Offscreen canvas when supported, otherwise a DOM canvas fallback.
 
-### resolveStarTileContext
+### createDocumentCanvasIfSupported
 
 ```ts
-resolveStarTileContext(
-  canvas: HTMLCanvasElement | OffscreenCanvas,
-): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null
+createDocumentCanvasIfSupported(
+  canvasDimensions: StarfieldCanvasDimensions,
+): HTMLCanvasElement | null
 ```
 
-Resolves the rendering context used for star tile pre-rendering.
+Creates a DOM canvas when document APIs are available.
 
 Parameters:
-- `canvas` - - Compatible canvas returned by the runtime-specific factory.
+- `canvasDimensions` - - Already-normalized pixel dimensions.
 
-Returns: A 2D drawing context when rendering is supported.
+Returns: DOM canvas instance or `null` when unavailable.
 
-### initializeStarTileContext
+### createOffscreenCanvasIfSupported
 
 ```ts
-initializeStarTileContext(
-  options: { tileContext: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D; canvas: HTMLCanvasElement | OffscreenCanvas; },
-): void
+createOffscreenCanvasIfSupported(
+  canvasDimensions: StarfieldCanvasDimensions,
+): OffscreenCanvas | null
 ```
 
-Clears the canvas and applies the neutral settings shared by all rendered stars.
+Creates an offscreen canvas when the current runtime supports it.
 
 Parameters:
-- `options` - - Context initialization dependencies.
+- `canvasDimensions` - - Already-normalized pixel dimensions.
 
-Returns: Nothing. The provided context is mutated in place.
+Returns: Offscreen canvas instance or `null` when unavailable.
 
-### renderSeededStars
+### createStarTileCanvas
 
 ```ts
-renderSeededStars(
-  options: { tileContext: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D; seededRandom: () => number; canvasOptions: CreateStarTileCanvasOptions; },
-): void
+createStarTileCanvas(
+  options: CreateStarTileCanvasOptions,
+): StarTileImage
 ```
 
-Draws all stars for one tile using a seeded random source.
+Pre-renders a deterministic tile that can be reused across animation frames.
 
 Parameters:
-- `options` - - Drawing context, seed source, and tile recipe.
+- `options` - - Declarative drawing recipe for one parallax layer.
 
-Returns: Nothing. The provided context is mutated in place.
+Returns: Canvas image source containing the rendered star strip.
 
-### resetStarTileContext
+### initializeStarTileContext
 
 ```ts
-resetStarTileContext(
-  tileContext: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+initializeStarTileContext(
+  options: { tileContext: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D; canvas: HTMLCanvasElement | OffscreenCanvas; },
 ): void
 ```
 
-Restores neutral drawing state so later canvas consumers start from defaults.
+Clears the canvas and applies the neutral settings shared by all rendered stars.
 
 Parameters:
-- `tileContext` - - 2D context used to render the star tile.
+- `options` - - Context initialization dependencies.
 
 Returns: Nothing. The provided context is mutated in place.
 
@@ -925,65 +925,65 @@ Parameters:
 
 Returns: Clamped integer dimensions safe for canvas allocation.
 
-### createOffscreenCanvasIfSupported
+### renderSeededStars
 
 ```ts
-createOffscreenCanvasIfSupported(
-  canvasDimensions: StarfieldCanvasDimensions,
-): OffscreenCanvas | null
+renderSeededStars(
+  options: { tileContext: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D; seededRandom: () => number; canvasOptions: CreateStarTileCanvasOptions; },
+): void
 ```
 
-Creates an offscreen canvas when the current runtime supports it.
+Draws all stars for one tile using a seeded random source.
 
 Parameters:
-- `canvasDimensions` - - Already-normalized pixel dimensions.
+- `options` - - Drawing context, seed source, and tile recipe.
 
-Returns: Offscreen canvas instance or `null` when unavailable.
+Returns: Nothing. The provided context is mutated in place.
 
-### createDocumentCanvasIfSupported
+### resetStarTileContext
 
 ```ts
-createDocumentCanvasIfSupported(
-  canvasDimensions: StarfieldCanvasDimensions,
-): HTMLCanvasElement | null
+resetStarTileContext(
+  tileContext: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+): void
 ```
 
-Creates a DOM canvas when document APIs are available.
+Restores neutral drawing state so later canvas consumers start from defaults.
 
 Parameters:
-- `canvasDimensions` - - Already-normalized pixel dimensions.
+- `tileContext` - - 2D context used to render the star tile.
 
-Returns: DOM canvas instance or `null` when unavailable.
+Returns: Nothing. The provided context is mutated in place.
 
-### createCanvasSizeFallback
+### resolveStarPlacement
 
 ```ts
-createCanvasSizeFallback(
-  canvasDimensions: StarfieldCanvasDimensions,
-): HTMLCanvasElement
+resolveStarPlacement(
+  options: { seededRandom: () => number; tileWidthPx: number; tileHeightPx: number; minSizePx: number; maxSizePx: number; minAlpha: number; maxAlpha: number; },
+): StarPlacement
 ```
 
-Creates a size-only fallback so non-browser tests can skip rendering safely.
+Resolves one deterministic star placement and appearance from the seeded RNG.
 
 Parameters:
-- `canvasDimensions` - - Already-normalized pixel dimensions.
+- `options` - - Random source and star placement bounds.
 
-Returns: Minimal canvas-shaped object cast to the compatible return type.
+Returns: Pixel location, square size, and alpha for one rendered star.
 
-### resolveStarPlacement
+### resolveStarTileContext
 
 ```ts
-resolveStarPlacement(
-  options: { seededRandom: () => number; tileWidthPx: number; tileHeightPx: number; minSizePx: number; maxSizePx: number; minAlpha: number; maxAlpha: number; },
-): StarPlacement
+resolveStarTileContext(
+  canvas: HTMLCanvasElement | OffscreenCanvas,
+): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null
 ```
 
-Resolves one deterministic star placement and appearance from the seeded RNG.
+Resolves the rendering context used for star tile pre-rendering.
 
 Parameters:
-- `options` - - Random source and star placement bounds.
+- `canvas` - - Compatible canvas returned by the runtime-specific factory.
 
-Returns: Pixel location, square size, and alpha for one rendered star.
+Returns: A 2D drawing context when rendering is supported.
 
 ## browser-entry/playback/playback.starfield.layer.services.ts
 
@@ -1155,40 +1155,6 @@ Request payload for one playback-step worker call.
 The browser asks the worker to advance simulation by a small batch of steps
 and to package the result for the current viewport dimensions.
 
-### ResolvePlaybackStepRequestInput
-
-Input used to resolve the next playback-step request and budget remainder.
-
-Playback uses a fractional frame budget so browser render cadence and worker
-simulation cadence can be smoothed together over time.
-
-### ResolvePlaybackStepRequestResult
-
-Output for the resolved playback-step request and frame-budget remainder.
-
-The resolved request records both the integer step batch to send now and the
-leftover fractional budget to carry into the next render tick.
-
-### resolvePlaybackStepRequest
-
-```ts
-resolvePlaybackStepRequest(
-  input: ResolvePlaybackStepRequestInput,
-): ResolvePlaybackStepRequestResult
-```
-
-Resolves step count and request payload for the next worker playback batch.
-
-This is the pacing bridge between browser rendering and worker simulation.
-Rather than sending a fixed step count every frame, the loop carries forward
-fractional remainder so long-term playback speed stays closer to the intended
-emulation rate.
-
-Parameters:
-- `input` - - Current frame budget and viewport dimensions.
-
-Returns: Request payload plus carried-over fractional frame budget.
-
 ### resolvePlaybackCompletionSummary
 
 ```ts
@@ -1237,3 +1203,37 @@ Parameters:
 - `leaderFramesSurvived` - - Current frame leader survived frames.
 
 Returns: Normalized per-frame HUD telemetry payload.
+
+### resolvePlaybackStepRequest
+
+```ts
+resolvePlaybackStepRequest(
+  input: ResolvePlaybackStepRequestInput,
+): ResolvePlaybackStepRequestResult
+```
+
+Resolves step count and request payload for the next worker playback batch.
+
+This is the pacing bridge between browser rendering and worker simulation.
+Rather than sending a fixed step count every frame, the loop carries forward
+fractional remainder so long-term playback speed stays closer to the intended
+emulation rate.
+
+Parameters:
+- `input` - - Current frame budget and viewport dimensions.
+
+Returns: Request payload plus carried-over fractional frame budget.
+
+### ResolvePlaybackStepRequestInput
+
+Input used to resolve the next playback-step request and budget remainder.
+
+Playback uses a fractional frame budget so browser render cadence and worker
+simulation cadence can be smoothed together over time.
+
+### ResolvePlaybackStepRequestResult
+
+Output for the resolved playback-step request and frame-budget remainder.
+
+The resolved request records both the integer step batch to send now and the
+leftover fractional budget to carry into the next render tick.