@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -69,6 +69,27 @@ const request: PlaybackBackgroundRequest = {
 };
 ```
 
+### PlaybackBackgroundLayout
+
+Resolved vertical scene split used by playback background composition.
+
+The layout fixes the classic synthwave composition used by this demo: a tall
+sky band for layered starfield parallax and a compressed lower strip for the
+perspective grid. Caching this structure by viewport size keeps redraws cheap
+when the scene is otherwise stable.
+
+### PlaybackBackgroundLayoutFactory
+
+```ts
+PlaybackBackgroundLayoutFactory(): PlaybackBackgroundLayout
+```
+
+Zero-argument builder used to lazily construct one cached background layout.
+
+The cache service accepts a factory instead of raw data so callers can defer
+the slightly more expensive layout computation until a viewport-size cache
+miss actually occurs.
+
 ### PlaybackBackgroundRequest
 
 Minimal render input required to draw the playback background.
@@ -100,26 +121,13 @@ resolves the sky/lower-band split, vanishing point, and horizon styling once
 so the draw passes can stay orchestration-first and avoid repeating geometry
 math every frame.
 
-### PlaybackBackgroundLayout
-
-Resolved vertical scene split used by playback background composition.
-
-The layout fixes the classic synthwave composition used by this demo: a tall
-sky band for layered starfield parallax and a compressed lower strip for the
-perspective grid. Caching this structure by viewport size keeps redraws cheap
-when the scene is otherwise stable.
-
-### PlaybackBackgroundLayoutFactory
-
-```ts
-PlaybackBackgroundLayoutFactory(): PlaybackBackgroundLayout
-```
+### PlaybackHorizonLineRequest
 
-Zero-argument builder used to lazily construct one cached background layout.
+Draw request for the horizon divider line.
 
-The cache service accepts a factory instead of raw data so callers can defer
-the slightly more expensive layout computation until a viewport-size cache
-miss actually occurs.
+This narrow contract is the final handoff from layout math to the canvas
+stroke helper: world-space x extents, the pixel-snapped y position, and the
+resolved glow style needed for both line passes.
 
 ### PlaybackHorizonStyle
 
@@ -130,45 +138,36 @@ the luminous skyline separator common in synthwave and TRON-inspired poster
 art. Keeping those paint properties bundled makes it easier to reason about
 the horizon as one semantic effect instead of a pile of canvas state.
 
-### PlaybackHorizonLineRequest
-
-Draw request for the horizon divider line.
-
-This narrow contract is the final handoff from layout math to the canvas
-stroke helper: world-space x extents, the pixel-snapped y position, and the
-resolved glow style needed for both line passes.
-
 ## browser-entry/playback/background/playback.background.constants.ts
 
-### FLAPPY_BACKGROUND_SKY_HEIGHT_RATIO
+### FLAPPY_BACKGROUND_COMPOSITE_LIGHTER
 
-Background layout ratio reserved for the starfield sky band.
+Composite mode used when stacking glow-heavy starfield layers.
 
-The top band intentionally occupies most of the scene so the future ground
-layer can take over the lower strip without competing with the stars.
+The background currently resets to ordinary compositing for main passes, but
+this constant documents the additive blend mode used when glow layers need to
+visually accumulate rather than overwrite one another.
 
-### FLAPPY_BACKGROUND_MIN_VIEWPORT_DIMENSION_PX
+### FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER
 
-Minimum safe viewport dimension used by background render math (pixels).
+Composite mode used for standard opaque drawing passes.
 
-Canvas helpers in this module assume positive dimensions. Clamping tiny or
-temporarily zero-sized layouts to this floor prevents resize races from
-producing invalid cache keys or negative geometry.
+Most background passes should replace pixels normally so the scene remains
+predictable before selective glow passes are added on top.
 
-### FLAPPY_BACKGROUND_TILE_ROW_START_INDEX
+### FLAPPY_BACKGROUND_HORIZON_GLOW_ALPHA
 
-Index offset used to draw one extra tile before the visible left edge.
+Soft glow opacity applied during the horizon glow pass.
 
-Starting one tile early hides wrap seams when the parallax offset lands near
-a tile boundary and the camera reveals a sliver of content just off-screen.
+The glow is intentionally strong enough to read as neon, but still shy of a
+full opaque bloom so the crisp core line remains visible.
 
-### FLAPPY_BACKGROUND_TILE_ROW_BUFFER_COUNT
+### FLAPPY_BACKGROUND_HORIZON_GLOW_BLUR_PX
 
-Extra tile count rendered past the visible right edge for seamless wrap.
+Blur radius used to bloom the horizon divider glow (pixels).
 
-The starfield is drawn as repeated cached strips. One buffered strip beyond
-the viewport prevents empty columns from appearing while the parallax offset
-advances between frames.
+This is the main control for how far the horizon's light appears to bleed
+into the neighboring sky and ground bands.
 
 ### FLAPPY_BACKGROUND_HORIZON_HALF_THICKNESS_MULTIPLIER
 
@@ -178,71 +177,72 @@ The layout computes the horizon around the sky/lower-band seam, so this
 multiplier converts stroke thickness into the offset needed to center the
 divider on that seam rather than placing it fully below it.
 
-### FLAPPY_BACKGROUND_ODD_STROKE_DIVISOR
+### FLAPPY_BACKGROUND_HORIZON_LINE_THICKNESS_PX
 
-Divisor used to detect odd stroke widths for pixel snapping.
+Thickness of the neon horizon divider line (pixels).
 
-Canvas 2D strokes look soft when odd-width lines are left on whole pixels.
-This constant supports the classic half-pixel alignment check used to keep
-the horizon divider visually crisp.
+A slightly heavier stroke helps the divider remain legible against both the
+starfield and the bright grid below it.
 
-### FLAPPY_BACKGROUND_ODD_STROKE_ALIGNMENT_OFFSET_PX
+### FLAPPY_BACKGROUND_HORIZON_STYLE
 
-Pixel offset used to align odd-width strokes to the device pixel grid.
+Frozen neon paint bundle reused by the playback horizon renderer.
 
-Offsetting odd-width lines by half a pixel is a standard raster technique
-for reducing blur in canvas line rendering.
+Keeping this style object in the constants module prevents repeated
+allocation during every background frame while still keeping the palette
+centrally theme-owned.
 
-### FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER
+### FLAPPY_BACKGROUND_MIN_VIEWPORT_DIMENSION_PX
 
-Composite mode used for standard opaque drawing passes.
+Minimum safe viewport dimension used by background render math (pixels).
 
-Most background passes should replace pixels normally so the scene remains
-predictable before selective glow passes are added on top.
+Canvas helpers in this module assume positive dimensions. Clamping tiny or
+temporarily zero-sized layouts to this floor prevents resize races from
+producing invalid cache keys or negative geometry.
 
-### FLAPPY_BACKGROUND_COMPOSITE_LIGHTER
+### FLAPPY_BACKGROUND_ODD_STROKE_ALIGNMENT_OFFSET_PX
 
-Composite mode used when stacking glow-heavy starfield layers.
+Pixel offset used to align odd-width strokes to the device pixel grid.
 
-The background currently resets to ordinary compositing for main passes, but
-this constant documents the additive blend mode used when glow layers need to
-visually accumulate rather than overwrite one another.
+Offsetting odd-width lines by half a pixel is a standard raster technique
+for reducing blur in canvas line rendering.
 
-### FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR
+### FLAPPY_BACKGROUND_ODD_STROKE_DIVISOR
 
-Transparent shadow color used to reset canvas glow state.
+Divisor used to detect odd stroke widths for pixel snapping.
 
-Canvas shadow state is sticky, so explicit transparent resets prevent one
-glow-heavy pass from leaking blur into later solid fills or line work.
+Canvas 2D strokes look soft when odd-width lines are left on whole pixels.
+This constant supports the classic half-pixel alignment check used to keep
+the horizon divider visually crisp.
 
-### FLAPPY_BACKGROUND_HORIZON_LINE_THICKNESS_PX
+### FLAPPY_BACKGROUND_SKY_HEIGHT_RATIO
 
-Thickness of the neon horizon divider line (pixels).
+Background layout ratio reserved for the starfield sky band.
 
-A slightly heavier stroke helps the divider remain legible against both the
-starfield and the bright grid below it.
+The top band intentionally occupies most of the scene so the future ground
+layer can take over the lower strip without competing with the stars.
 
-### FLAPPY_BACKGROUND_HORIZON_GLOW_ALPHA
+### FLAPPY_BACKGROUND_TILE_ROW_BUFFER_COUNT
 
-Soft glow opacity applied during the horizon glow pass.
+Extra tile count rendered past the visible right edge for seamless wrap.
 
-The glow is intentionally strong enough to read as neon, but still shy of a
-full opaque bloom so the crisp core line remains visible.
+The starfield is drawn as repeated cached strips. One buffered strip beyond
+the viewport prevents empty columns from appearing while the parallax offset
+advances between frames.
 
-### FLAPPY_BACKGROUND_HORIZON_GLOW_BLUR_PX
+### FLAPPY_BACKGROUND_TILE_ROW_START_INDEX
 
-Blur radius used to bloom the horizon divider glow (pixels).
+Index offset used to draw one extra tile before the visible left edge.
 
-This is the main control for how far the horizon's light appears to bleed
-into the neighboring sky and ground bands.
+Starting one tile early hides wrap seams when the parallax offset lands near
+a tile boundary and the camera reveals a sliver of content just off-screen.
 
-### FLAPPY_BACKGROUND_HORIZON_STYLE
+### FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR
 
-Frozen neon paint bundle reused by the playback horizon renderer.
+Transparent shadow color used to reset canvas glow state.
 
-Keeping this style object in the constants module prevents repeated
-allocation during every background frame while still keeping the palette
-centrally theme-owned.
+Canvas shadow state is sticky, so explicit transparent resets prevent one
+glow-heavy pass from leaking blur into later solid fills or line work.
 
 ## browser-entry/playback/background/playback.background.services.ts
 
@@ -333,16 +333,16 @@ Returns: Immutable scene context shared by the private render helpers.
 
 ## browser-entry/playback/background/playback.background.draw.services.ts
 
-### paintPlaybackBackgroundBase
+### drawPlaybackBackgroundHorizon
 
 ```ts
-paintPlaybackBackgroundBase(
+drawPlaybackBackgroundHorizon(
   context: CanvasRenderingContext2D,
   sceneContext: PlaybackBackgroundSceneContext,
 ): void
 ```
 
-Paints the base background fill for the currently visible viewport.
+Draws the glowing horizon divider across the visible viewport.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
@@ -369,20 +369,20 @@ Parameters:
 
 Returns: Nothing.
 
-### drawPlaybackBackgroundHorizon
+### drawPlaybackHorizonLine
 
 ```ts
-drawPlaybackBackgroundHorizon(
+drawPlaybackHorizonLine(
   context: CanvasRenderingContext2D,
-  sceneContext: PlaybackBackgroundSceneContext,
+  request: PlaybackHorizonLineRequest,
 ): void
 ```
 
-Draws the glowing horizon divider across the visible viewport.
+Draws the glowing horizon divider using the provided neon style.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
-- `sceneContext` - - Derived scene geometry and style contract.
+- `request` - - Width, aligned y-position, and style for the divider.
 
 Returns: Nothing.
 
@@ -411,20 +411,20 @@ Parameters:
 
 Returns: Nothing.
 
-### drawPlaybackHorizonLine
+### paintPlaybackBackgroundBase
 
 ```ts
-drawPlaybackHorizonLine(
+paintPlaybackBackgroundBase(
   context: CanvasRenderingContext2D,
-  request: PlaybackHorizonLineRequest,
+  sceneContext: PlaybackBackgroundSceneContext,
 ): void
 ```
 
-Draws the glowing horizon divider using the provided neon style.
+Paints the base background fill for the currently visible viewport.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
-- `request` - - Width, aligned y-position, and style for the divider.
+- `sceneContext` - - Derived scene geometry and style contract.
 
 Returns: Nothing.
 
@@ -451,23 +451,6 @@ Parameters:
 
 Returns: Stable viewport-size cache key for the current frame.
 
-### resolvePlaybackBackgroundViewportCacheKey
-
-```ts
-resolvePlaybackBackgroundViewportCacheKey(
-  visibleWorldWidthPx: number,
-  visibleWorldHeightPx: number,
-): string
-```
-
-Resolves the stable viewport-size cache key used by background caches.
-
-Parameters:
-- `visibleWorldWidthPx` - - Current visible world width in pixels.
-- `visibleWorldHeightPx` - - Current visible world height in pixels.
-
-Returns: Cache key that changes whenever the page size changes.
-
 ### resolveCachedPlaybackBackgroundLayout
 
 ```ts
@@ -502,32 +485,24 @@ Parameters:
 
 Returns: Cached tile coverage count for the active viewport width.
 
-## browser-entry/playback/background/playback.background.utils.ts
-
-### resolvePlaybackBackgroundLayout
+### resolvePlaybackBackgroundViewportCacheKey
 
 ```ts
-resolvePlaybackBackgroundLayout(
+resolvePlaybackBackgroundViewportCacheKey(
+  visibleWorldWidthPx: number,
   visibleWorldHeightPx: number,
-): PlaybackBackgroundLayout
+): string
 ```
 
-Resolves the vertical split between the starfield sky and the future ground.
+Resolves the stable viewport-size cache key used by background caches.
 
 Parameters:
+- `visibleWorldWidthPx` - - Current visible world width in pixels.
 - `visibleWorldHeightPx` - - Current visible world height in pixels.
 
-Returns: Stable scene layout for the current frame.
-
-### resolvePlaybackHorizonStyle
-
-```ts
-resolvePlaybackHorizonStyle(): PlaybackHorizonStyle
-```
-
-Resolves the neon paint settings for the horizon divider.
+Returns: Cache key that changes whenever the page size changes.
 
-Returns: Reusable draw style for both the glow and crisp line passes.
+## browser-entry/playback/background/playback.background.utils.ts
 
 ### resolveAlignedHorizonYPx
 
@@ -546,6 +521,31 @@ Parameters:
 
 Returns: Pixel-snapped y-position for the stroke.
 
+### resolvePlaybackBackgroundLayout
+
+```ts
+resolvePlaybackBackgroundLayout(
+  visibleWorldHeightPx: number,
+): PlaybackBackgroundLayout
+```
+
+Resolves the vertical split between the starfield sky and the future ground.
+
+Parameters:
+- `visibleWorldHeightPx` - - Current visible world height in pixels.
+
+Returns: Stable scene layout for the current frame.
+
+### resolvePlaybackHorizonStyle
+
+```ts
+resolvePlaybackHorizonStyle(): PlaybackHorizonStyle
+```
+
+Resolves the neon paint settings for the horizon divider.
+
+Returns: Reusable draw style for both the glow and crisp line passes.
+
 ### resolveSafeBackgroundDimension
 
 ```ts