@reicek/neataptic-ts 0.1.25 → 0.1.26

package/test/examples/flappy_bird/browser-entry/host/resize/README.md

@@ -23,6 +23,28 @@ flowchart LR
 
 ## browser-entry/host/resize/host.resize.service.ts
 
+### applyResponsiveViewportSizing
+
+```ts
+applyResponsiveViewportSizing(
+  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
+  deferredNetworkRedrawController: DeferredNetworkRedrawController,
+  onNetworkResize: () => void,
+): void
+```
+
+Applies responsive sizing to the simulation and network canvases.
+
+The resize flow is intentionally split into two branches: the minimal mobile
+path and the richer standard path used for tablet and desktop layouts.
+
+Parameters:
+- `responsiveViewportSizingElements` - - Host elements participating in layout.
+- `deferredNetworkRedrawController` - - Deferred redraw controller.
+- `onNetworkResize` - - Immediate network resize callback.
+
+Returns: Nothing.
+
 ### installResponsiveViewportSizing
 
 ```ts
@@ -58,28 +80,6 @@ Parameters:
 
 Returns: Nothing.
 
-### applyResponsiveViewportSizing
-
-```ts
-applyResponsiveViewportSizing(
-  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
-  deferredNetworkRedrawController: DeferredNetworkRedrawController,
-  onNetworkResize: () => void,
-): void
-```
-
-Applies responsive sizing to the simulation and network canvases.
-
-The resize flow is intentionally split into two branches: the minimal mobile
-path and the richer standard path used for tablet and desktop layouts.
-
-Parameters:
-- `responsiveViewportSizingElements` - - Host elements participating in layout.
-- `deferredNetworkRedrawController` - - Deferred redraw controller.
-- `onNetworkResize` - - Immediate network resize callback.
-
-Returns: Nothing.
-
 ## browser-entry/host/resize/host.resize.service.types.ts
 
 Shared contracts for responsive browser-host sizing.
@@ -88,13 +88,6 @@ The resize subsystem coordinates several DOM elements and several layout modes
 at once, so these types capture the measured viewport state, the active mode
 flags, and the grouped DOM handles needed by the appliers.
 
-### ResponsiveViewportSizingElements
-
-DOM elements that participate in responsive host sizing.
-
-Keeping the participating elements together makes the responsive helpers read
-as layout orchestration rather than long DOM parameter lists.
-
 ### DeferredNetworkRedrawController
 
 Deferred redraw controller used after layout-affecting changes.
@@ -102,12 +95,12 @@ Deferred redraw controller used after layout-affecting changes.
 The network panel redraw is deferred because flexbox and canvas sizing can
 settle over multiple animation frames.
 
-### ResponsiveViewportMeasurements
+### ResponsiveViewportLayoutContext
 
-Measured viewport and panel budgets for responsive layout.
+Full responsive layout context shared across sizing helpers.
 
-These values are the raw numeric inputs to the resize policy before any mode
-branching happens.
+This merges measurements and mode flags into the one context object used by
+the resize appliers.
 
 ### ResponsiveViewportLayoutFlags
 
@@ -116,19 +109,19 @@ Layout-mode flags resolved from the current viewport.
 The host currently distinguishes between minimal mobile, landscape split, and
 compact network-only variants.
 
-### ResponsiveViewportLayoutContext
+### ResponsiveViewportMeasurements
 
-Full responsive layout context shared across sizing helpers.
+Measured viewport and panel budgets for responsive layout.
 
-This merges measurements and mode flags into the one context object used by
-the resize appliers.
+These values are the raw numeric inputs to the resize policy before any mode
+branching happens.
 
-### StatsPanelDimensions
+### ResponsiveViewportSizingElements
 
-Resolved height and width budgets for the stats panel.
+DOM elements that participate in responsive host sizing.
 
-The stats panel dimensions are derived from the current viewport budget after
-minimum readable canvas space is reserved.
+Keeping the participating elements together makes the responsive helpers read
+as layout orchestration rather than long DOM parameter lists.
 
 ### SimulationCanvasBounds
 
@@ -137,6 +130,13 @@ Width and height bounds for the simulation canvas.
 These are the final pixel budgets the simulation canvas may consume for the
 current responsive layout.
 
+### StatsPanelDimensions
+
+Resolved height and width budgets for the stats panel.
+
+The stats panel dimensions are derived from the current viewport budget after
+minimum readable canvas space is reserved.
+
 ## browser-entry/host/resize/host.resize.service.constants.ts
 
 Shared constants for responsive host sizing.
@@ -144,12 +144,12 @@ Shared constants for responsive host sizing.
 These values keep the resize policy readable by naming the split ratio, the
 minimum positive dimension, and the CSS token bundle used by layout appliers.
 
-### FLAPPY_HOST_RESIZE_STYLE_TOKENS
+### FLAPPY_HOST_RESIZE_MIN_DIMENSION_PX
 
-Shared CSS tokens used by the host resize layout appliers.
+Minimum positive dimension enforced by resize math.
 
-Centralizing these string tokens reduces repetition across the responsive DOM
-style appliers.
+This prevents zero or negative canvas sizes from leaking into downstream
+layout and backing-store calculations.
 
 ### FLAPPY_HOST_RESIZE_SPLIT_RATIO
 
@@ -158,12 +158,12 @@ Split ratio used when dividing the viewport between simulation and stats.
 A value of `0.5` means the standard stacked layout begins from an even split
 before clamping against minimum-height constraints.
 
-### FLAPPY_HOST_RESIZE_MIN_DIMENSION_PX
+### FLAPPY_HOST_RESIZE_STYLE_TOKENS
 
-Minimum positive dimension enforced by resize math.
+Shared CSS tokens used by the host resize layout appliers.
 
-This prevents zero or negative canvas sizes from leaking into downstream
-layout and backing-store calculations.
+Centralizing these string tokens reduces repetition across the responsive DOM
+style appliers.
 
 ## browser-entry/host/resize/host.resize.service.services.ts
 
@@ -173,24 +173,6 @@ These helpers implement the actual responsive policy once the viewport has
 been measured: choose a layout mode, resize canvases, reorder panes, and
 trigger redraws when the network panel geometry changes.
 
-### createDeferredNetworkRedrawController
-
-```ts
-createDeferredNetworkRedrawController(
-  onNetworkResize: () => void,
-): DeferredNetworkRedrawController
-```
-
-Creates a deferred redraw controller that waits for layout to settle.
-
-Waiting two animation frames is a pragmatic way to avoid redrawing the network
-panel against transient intermediate layout sizes.
-
-Parameters:
-- `onNetworkResize` - - Callback after network resize.
-
-Returns: Deferred redraw controller.
-
 ### applyMinimalMobileViewportLayout
 
 ```ts
@@ -211,27 +193,25 @@ Parameters:
 
 Returns: Nothing.
 
-### applyStandardViewportLayout
+### applyNetworkCanvasHostHeight
 
 ```ts
-applyStandardViewportLayout(
-  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
-  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+applyNetworkCanvasHostHeight(
+  networkCanvasHost: HTMLElement,
   deferredNetworkRedrawController: DeferredNetworkRedrawController,
-): StatsPanelDimensions
+): void
 ```
 
-Applies the standard tablet and desktop layout and returns panel dimensions.
+Applies the fixed network host height and queues redraw when it changes.
 
-This path keeps the auxiliary panes visible and resolves a balanced split
-between simulation and side-panel content.
+The network panel uses a fixed-height target so the visualization remains
+readable and stable across layout transitions.
 
 Parameters:
-- `responsiveViewportSizingElements` - - Host elements participating in layout.
-- `responsiveViewportLayoutContext` - - Responsive layout context.
+- `networkCanvasHost` - - Network canvas host element.
 - `deferredNetworkRedrawController` - - Deferred redraw controller.
 
-Returns: Resolved stats panel dimensions.
+Returns: Nothing.
 
 ### applyResponsiveCanvasBounds
 
@@ -257,45 +237,64 @@ Parameters:
 
 Returns: Nothing.
 
-### installResponsiveViewportSizingListeners
+### applySplitContainerLayoutStyles
 
 ```ts
-installResponsiveViewportSizingListeners(
-  containerElement: HTMLElement,
-  applyCanvasSize: () => void,
-  deferredNetworkRedrawController: DeferredNetworkRedrawController,
+applySplitContainerLayoutStyles(
+  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
 ): void
 ```
 
-Installs window and container listeners for responsive host sizing.
+Applies the split-container styles for the standard layout modes.
 
-The host listens both to global window resizes and to container-specific size
-changes when `ResizeObserver` is available.
+This helper decides whether the main panels should stack or sit side-by-side,
+then applies the matching flexbox configuration.
 
 Parameters:
-- `containerElement` - - Width and height source.
-- `applyCanvasSize` - - Shared sizing callback.
-- `deferredNetworkRedrawController` - - Deferred redraw controller.
+- `responsiveViewportSizingElements` - - Host elements participating in layout.
+- `responsiveViewportLayoutContext` - - Responsive layout context.
 
 Returns: Nothing.
 
-### applySplitContainerLayoutStyles
+### applyStandardViewportLayout
 
 ```ts
-applySplitContainerLayoutStyles(
+applyStandardViewportLayout(
   responsiveViewportSizingElements: ResponsiveViewportSizingElements,
   responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
-): void
+  deferredNetworkRedrawController: DeferredNetworkRedrawController,
+): StatsPanelDimensions
 ```
 
-Applies the split-container styles for the standard layout modes.
+Applies the standard tablet and desktop layout and returns panel dimensions.
 
-This helper decides whether the main panels should stack or sit side-by-side,
-then applies the matching flexbox configuration.
+This path keeps the auxiliary panes visible and resolves a balanced split
+between simulation and side-panel content.
 
 Parameters:
 - `responsiveViewportSizingElements` - - Host elements participating in layout.
 - `responsiveViewportLayoutContext` - - Responsive layout context.
+- `deferredNetworkRedrawController` - - Deferred redraw controller.
+
+Returns: Resolved stats panel dimensions.
+
+### applyStatsContainerDimensions
+
+```ts
+applyStatsContainerDimensions(
+  statsContainer: HTMLElement,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+  statsPanelDimensions: StatsPanelDimensions,
+): void
+```
+
+Applies the resolved dimensions and scrolling rules to the stats container.
+
+Parameters:
+- `statsContainer` - - Stats host element.
+- `responsiveViewportLayoutContext` - - Responsive layout context.
+- `statsPanelDimensions` - - Resolved stats panel dimensions.
 
 Returns: Nothing.
 
@@ -321,42 +320,43 @@ Parameters:
 
 Returns: Nothing.
 
-### applyNetworkCanvasHostHeight
+### createDeferredNetworkRedrawController
 
 ```ts
-applyNetworkCanvasHostHeight(
-  networkCanvasHost: HTMLElement,
-  deferredNetworkRedrawController: DeferredNetworkRedrawController,
-): void
+createDeferredNetworkRedrawController(
+  onNetworkResize: () => void,
+): DeferredNetworkRedrawController
 ```
 
-Applies the fixed network host height and queues redraw when it changes.
+Creates a deferred redraw controller that waits for layout to settle.
 
-The network panel uses a fixed-height target so the visualization remains
-readable and stable across layout transitions.
+Waiting two animation frames is a pragmatic way to avoid redrawing the network
+panel against transient intermediate layout sizes.
 
 Parameters:
-- `networkCanvasHost` - - Network canvas host element.
-- `deferredNetworkRedrawController` - - Deferred redraw controller.
+- `onNetworkResize` - - Callback after network resize.
 
-Returns: Nothing.
+Returns: Deferred redraw controller.
 
-### applyStatsContainerDimensions
+### installResponsiveViewportSizingListeners
 
 ```ts
-applyStatsContainerDimensions(
-  statsContainer: HTMLElement,
-  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
-  statsPanelDimensions: StatsPanelDimensions,
+installResponsiveViewportSizingListeners(
+  containerElement: HTMLElement,
+  applyCanvasSize: () => void,
+  deferredNetworkRedrawController: DeferredNetworkRedrawController,
 ): void
 ```
 
-Applies the resolved dimensions and scrolling rules to the stats container.
+Installs window and container listeners for responsive host sizing.
+
+The host listens both to global window resizes and to container-specific size
+changes when `ResizeObserver` is available.
 
 Parameters:
-- `statsContainer` - - Stats host element.
-- `responsiveViewportLayoutContext` - - Responsive layout context.
-- `statsPanelDimensions` - - Resolved stats panel dimensions.
+- `containerElement` - - Width and height source.
+- `applyCanvasSize` - - Shared sizing callback.
+- `deferredNetworkRedrawController` - - Deferred redraw controller.
 
 Returns: Nothing.
 
@@ -367,27 +367,23 @@ Measurement and budget helpers for responsive host sizing.
 These functions convert live DOM dimensions into the numeric budgets used by
 the resize appliers.
 
-### resolveResponsiveViewportLayoutContext
+### resolveHeaderHeightPx
 
 ```ts
-resolveResponsiveViewportLayoutContext(
+resolveHeaderHeightPx(
   containerElement: HTMLElement,
-  statsContainer: HTMLElement,
-  networkCanvasHost: HTMLElement,
-): ResponsiveViewportLayoutContext
+): number
 ```
 
-Resolves responsive layout measurements and mode flags from the host DOM.
+Resolves the header canvas height, if present.
 
-This is the measurement root for the resize system: read the current viewport,
-reserve required minimums, then classify the active layout mode.
+The resize system subtracts the header from the total container height before
+budgeting the main panels.
 
 Parameters:
 - `containerElement` - - Width and height source.
-- `statsContainer` - - Stats host element.
-- `networkCanvasHost` - - Network host element.
 
-Returns: Responsive layout context.
+Returns: Header height in pixels.
 
 ### resolveMinimalMobileCanvasBounds
 
@@ -409,23 +405,27 @@ Parameters:
 
 Returns: Simulation canvas bounds.
 
-### resolveStatsPanelDimensions
+### resolveResponsiveViewportLayoutContext
 
 ```ts
-resolveStatsPanelDimensions(
-  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
-): StatsPanelDimensions
+resolveResponsiveViewportLayoutContext(
+  containerElement: HTMLElement,
+  statsContainer: HTMLElement,
+  networkCanvasHost: HTMLElement,
+): ResponsiveViewportLayoutContext
 ```
 
-Resolves the stats panel height and width budgets.
+Resolves responsive layout measurements and mode flags from the host DOM.
 
-The stats panel budget is computed after preserving a minimum readable region
-for the simulation canvas.
+This is the measurement root for the resize system: read the current viewport,
+reserve required minimums, then classify the active layout mode.
 
 Parameters:
-- `responsiveViewportLayoutContext` - - Responsive layout context.
+- `containerElement` - - Width and height source.
+- `statsContainer` - - Stats host element.
+- `networkCanvasHost` - - Network host element.
 
-Returns: Stats panel dimensions.
+Returns: Responsive layout context.
 
 ### resolveSimulationCanvasBounds
 
@@ -449,20 +449,20 @@ Parameters:
 
 Returns: Simulation canvas bounds.
 
-### resolveHeaderHeightPx
+### resolveStatsPanelDimensions
 
 ```ts
-resolveHeaderHeightPx(
-  containerElement: HTMLElement,
-): number
+resolveStatsPanelDimensions(
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+): StatsPanelDimensions
 ```
 
-Resolves the header canvas height, if present.
+Resolves the stats panel height and width budgets.
 
-The resize system subtracts the header from the total container height before
-budgeting the main panels.
+The stats panel budget is computed after preserving a minimum readable region
+for the simulation canvas.
 
 Parameters:
-- `containerElement` - - Width and height source.
+- `responsiveViewportLayoutContext` - - Responsive layout context.
 
-Returns: Header height in pixels.
+Returns: Stats panel dimensions.