@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/host/resize/host.resize.service.services.ts

@@ -0,0 +1,392 @@
+import {
+  FLAPPY_UI_NETWORK_HOST_FIXED_HEIGHT_PX,
+  FLAPPY_UI_NETWORK_HOST_INSET_PX,
+  FLAPPY_VIEWPORT_VERTICAL_LAYOUT_GUTTER_PX,
+} from '../../../constants/constants';
+import { FLAPPY_HOST_STATS_SPLIT_GAP } from '../host.constants';
+import {
+  applyCanvasBackingSize,
+  applySimulationCanvasBounds,
+  resolveNetworkCanvasSizePx,
+} from '../host.canvas.service';
+import { FLAPPY_HOST_RESIZE_STYLE_TOKENS } from './host.resize.service.constants';
+import {
+  resolveMinimalMobileCanvasBounds,
+  resolveSimulationCanvasBounds,
+  resolveStatsPanelDimensions,
+} from './host.resize.service.utils';
+import type {
+  DeferredNetworkRedrawController,
+  ResponsiveViewportLayoutContext,
+  ResponsiveViewportSizingElements,
+  StatsPanelDimensions,
+} from './host.resize.service.types';
+
+/**
+ * Layout-application helpers for responsive host sizing.
+ *
+ * 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.
+ */
+
+/**
+ * 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.
+ *
+ * @param onNetworkResize - Callback after network resize.
+ * @returns Deferred redraw controller.
+ */
+export function createDeferredNetworkRedrawController(
+  onNetworkResize: () => void,
+): DeferredNetworkRedrawController {
+  let pendingNetworkRedrawRequest = false;
+
+  return {
+    requestNetworkRedrawAfterLayout: (): void => {
+      // Step 1: Skip duplicate redraw requests while one is already queued.
+      if (pendingNetworkRedrawRequest) {
+        return;
+      }
+      pendingNetworkRedrawRequest = true;
+
+      // Step 2: Wait two animation frames so flexbox layout has settled before redrawing.
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          pendingNetworkRedrawRequest = false;
+          onNetworkResize();
+        });
+      });
+    },
+  };
+}
+
+/**
+ * Applies the minimal mobile layout that hides the auxiliary panes.
+ *
+ * On the smallest viewports, the resize policy prioritizes the simulation canvas
+ * and temporarily hides the stats/network panel to preserve playable space.
+ *
+ * @param responsiveViewportSizingElements - Host elements participating in layout.
+ * @param responsiveViewportLayoutContext - Responsive layout context.
+ * @returns Nothing.
+ */
+export function applyMinimalMobileViewportLayout(
+  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+): void {
+  // Step 1: Arrange the split containers so gameplay occupies the full vertical budget.
+  responsiveViewportSizingElements.mainSplitContainer.style.flexDirection =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.columnDirection;
+  responsiveViewportSizingElements.mainSplitContainer.style.gap = `${FLAPPY_VIEWPORT_VERTICAL_LAYOUT_GUTTER_PX}px`;
+  responsiveViewportSizingElements.statsSplitContainer.style.flexDirection =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.rowDirection;
+  responsiveViewportSizingElements.statsSplitContainer.style.alignItems =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.flexStartAlignment;
+  responsiveViewportSizingElements.statsSplitContainer.style.height =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.autoSize;
+  responsiveViewportSizingElements.statsTableHost.style.order =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.primaryOrder;
+  responsiveViewportSizingElements.networkCanvasHost.style.order =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.secondaryOrder;
+
+  // Step 2: Hide the stats pane so the simulation canvas gets the full available height.
+  responsiveViewportSizingElements.statsContainer.style.display =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.hiddenDisplay;
+  responsiveViewportSizingElements.statsContainer.style.height =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.zeroSizePx;
+  responsiveViewportSizingElements.statsContainer.style.maxHeight =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.zeroSizePx;
+  responsiveViewportSizingElements.statsContainer.style.overflowY =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.hiddenOverflow;
+
+  // Step 3: Apply the simulation canvas backing size directly from the mobile viewport budget.
+  const mobileCanvasBounds = resolveMinimalMobileCanvasBounds(
+    responsiveViewportSizingElements.containerElement,
+    responsiveViewportLayoutContext,
+  );
+  applyCanvasBackingSize(
+    responsiveViewportSizingElements.canvas,
+    mobileCanvasBounds.availableWidthPx,
+    mobileCanvasBounds.availableHeightPx,
+  );
+}
+
+/**
+ * Applies the standard tablet and desktop layout and returns panel dimensions.
+ *
+ * This path keeps the auxiliary panes visible and resolves a balanced split
+ * between simulation and side-panel content.
+ *
+ * @param responsiveViewportSizingElements - Host elements participating in layout.
+ * @param responsiveViewportLayoutContext - Responsive layout context.
+ * @param deferredNetworkRedrawController - Deferred redraw controller.
+ * @returns Resolved stats panel dimensions.
+ */
+export function applyStandardViewportLayout(
+  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+  deferredNetworkRedrawController: DeferredNetworkRedrawController,
+): StatsPanelDimensions {
+  // Step 1: Restore the stats container and apply split orientation styles.
+  responsiveViewportSizingElements.statsContainer.style.display =
+    FLAPPY_HOST_RESIZE_STYLE_TOKENS.blockDisplay;
+  applySplitContainerLayoutStyles(
+    responsiveViewportSizingElements,
+    responsiveViewportLayoutContext,
+  );
+
+  // Step 2: Resolve the stats panel dimensions from the current viewport budget.
+  const statsPanelDimensions = resolveStatsPanelDimensions(
+    responsiveViewportLayoutContext,
+  );
+
+  // Step 3: Clamp the network panel height and queue a redraw when the height changed.
+  applyNetworkCanvasHostHeight(
+    responsiveViewportSizingElements.networkCanvasHost,
+    deferredNetworkRedrawController,
+  );
+
+  // Step 4: Apply the final stats container dimensions and scrolling rules.
+  applyStatsContainerDimensions(
+    responsiveViewportSizingElements.statsContainer,
+    responsiveViewportLayoutContext,
+    statsPanelDimensions,
+  );
+
+  return statsPanelDimensions;
+}
+
+/**
+ * Applies simulation and network canvas backing sizes for the active layout.
+ *
+ * Once panel dimensions are known, this helper updates both backing stores and
+ * triggers an immediate network redraw when the visualization canvas changed.
+ *
+ * @param responsiveViewportSizingElements - Host elements participating in layout.
+ * @param responsiveViewportLayoutContext - Responsive layout context.
+ * @param statsPanelDimensions - Resolved stats panel dimensions.
+ * @param onNetworkResize - Immediate network resize callback.
+ * @returns Nothing.
+ */
+export function applyResponsiveCanvasBounds(
+  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+  statsPanelDimensions: StatsPanelDimensions,
+  onNetworkResize: () => void,
+): void {
+  // Step 1: Resolve simulation canvas size from the remaining viewport budget.
+  const simulationCanvasBounds = resolveSimulationCanvasBounds(
+    responsiveViewportSizingElements.containerElement,
+    responsiveViewportLayoutContext,
+    statsPanelDimensions,
+  );
+  applySimulationCanvasBounds(
+    responsiveViewportSizingElements.canvas,
+    simulationCanvasBounds.availableWidthPx,
+    simulationCanvasBounds.availableHeightPx,
+  );
+
+  // Step 2: Resize the network canvas backing store and redraw immediately when it changed.
+  const { widthPx, heightPx } = resolveNetworkCanvasSizePx(
+    responsiveViewportSizingElements.networkCanvasHost,
+    FLAPPY_UI_NETWORK_HOST_INSET_PX,
+  );
+  if (
+    applyCanvasBackingSize(
+      responsiveViewportSizingElements.networkCanvas,
+      widthPx,
+      heightPx,
+    )
+  ) {
+    onNetworkResize();
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param containerElement - Width and height source.
+ * @param applyCanvasSize - Shared sizing callback.
+ * @param deferredNetworkRedrawController - Deferred redraw controller.
+ * @returns Nothing.
+ */
+export function installResponsiveViewportSizingListeners(
+  containerElement: HTMLElement,
+  applyCanvasSize: () => void,
+  deferredNetworkRedrawController: DeferredNetworkRedrawController,
+): void {
+  // Step 1: Run the first post-layout redraw after the initial sizing pass.
+  deferredNetworkRedrawController.requestNetworkRedrawAfterLayout();
+
+  // Step 2: Recompute layout on window resize.
+  window.addEventListener('resize', applyCanvasSize);
+
+  // Step 3: Observe host-size changes when ResizeObserver is available.
+  if (typeof ResizeObserver !== 'function') {
+    return;
+  }
+
+  const resizeObserver = new ResizeObserver(() => {
+    applyCanvasSize();
+    deferredNetworkRedrawController.requestNetworkRedrawAfterLayout();
+  });
+  resizeObserver.observe(containerElement);
+}
+
+/**
+ * Applies the split-container styles for the standard layout modes.
+ *
+ * This helper decides whether the main panels should stack or sit side-by-side,
+ * then applies the matching flexbox configuration.
+ *
+ * @param responsiveViewportSizingElements - Host elements participating in layout.
+ * @param responsiveViewportLayoutContext - Responsive layout context.
+ * @returns Nothing.
+ */
+function applySplitContainerLayoutStyles(
+  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+): void {
+  // Step 1: Configure the outer split direction based on landscape or stacked layout.
+  responsiveViewportSizingElements.mainSplitContainer.style.flexDirection =
+    responsiveViewportLayoutContext.useLandscapeSplitLayout
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.rowDirection
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.columnDirection;
+  responsiveViewportSizingElements.mainSplitContainer.style.gap = `${FLAPPY_VIEWPORT_VERTICAL_LAYOUT_GUTTER_PX}px`;
+
+  // Step 2: Configure the inner stats/network split and alignment.
+  responsiveViewportSizingElements.statsSplitContainer.style.flexDirection =
+    responsiveViewportLayoutContext.useLandscapeSplitLayout
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.columnDirection
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.rowDirection;
+  responsiveViewportSizingElements.statsSplitContainer.style.alignItems =
+    responsiveViewportLayoutContext.useLandscapeSplitLayout
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.stretchAlignment
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.flexStartAlignment;
+  responsiveViewportSizingElements.statsSplitContainer.style.height =
+    responsiveViewportLayoutContext.useLandscapeSplitLayout
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.fullSize
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.autoSize;
+  responsiveViewportSizingElements.statsSplitContainer.style.gap =
+    responsiveViewportLayoutContext.useNetworkOnlyPanel
+      ? '0'
+      : FLAPPY_HOST_STATS_SPLIT_GAP;
+
+  // Step 3: Apply stats/network ordering and flex rules for the chosen layout.
+  applyStatsPaneOrdering(
+    responsiveViewportSizingElements.statsTableHost,
+    responsiveViewportSizingElements.networkCanvasHost,
+    responsiveViewportLayoutContext,
+  );
+}
+
+/**
+ * Applies ordering and flex styles for stats and network panes.
+ *
+ * Compact layouts may hide the stats table or promote the network panel so the
+ * most informative content remains visible in constrained space.
+ *
+ * @param statsTableHost - Stats table host element.
+ * @param networkCanvasHost - Network canvas host element.
+ * @param responsiveViewportLayoutContext - Responsive layout context.
+ * @returns Nothing.
+ */
+function applyStatsPaneOrdering(
+  statsTableHost: HTMLElement,
+  networkCanvasHost: HTMLElement,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+): void {
+  // Step 1: Order the network panel first only for landscape split layouts.
+  if (responsiveViewportLayoutContext.useLandscapeSplitLayout) {
+    networkCanvasHost.style.order =
+      FLAPPY_HOST_RESIZE_STYLE_TOKENS.primaryOrder;
+    statsTableHost.style.order = FLAPPY_HOST_RESIZE_STYLE_TOKENS.secondaryOrder;
+  } else {
+    statsTableHost.style.order = FLAPPY_HOST_RESIZE_STYLE_TOKENS.primaryOrder;
+    networkCanvasHost.style.order =
+      FLAPPY_HOST_RESIZE_STYLE_TOKENS.secondaryOrder;
+  }
+
+  // Step 2: Collapse the stats table when the network-only compact panel is active.
+  statsTableHost.style.display =
+    responsiveViewportLayoutContext.useNetworkOnlyPanel
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.hiddenDisplay
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.blockDisplay;
+  statsTableHost.style.flex =
+    responsiveViewportLayoutContext.useNetworkOnlyPanel
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.autoFlex
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.fillFlex;
+  networkCanvasHost.style.flex =
+    responsiveViewportLayoutContext.useNetworkOnlyPanel
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.fullFlex
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.autoFlex;
+  networkCanvasHost.style.width =
+    responsiveViewportLayoutContext.useNetworkOnlyPanel
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.fullSize
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.autoSize;
+  networkCanvasHost.style.maxWidth = FLAPPY_HOST_RESIZE_STYLE_TOKENS.fullSize;
+}
+
+/**
+ * Applies the fixed network host height and queues redraw when it changes.
+ *
+ * The network panel uses a fixed-height target so the visualization remains
+ * readable and stable across layout transitions.
+ *
+ * @param networkCanvasHost - Network canvas host element.
+ * @param deferredNetworkRedrawController - Deferred redraw controller.
+ * @returns Nothing.
+ */
+function applyNetworkCanvasHostHeight(
+  networkCanvasHost: HTMLElement,
+  deferredNetworkRedrawController: DeferredNetworkRedrawController,
+): void {
+  // Step 1: Update the host height only when the fixed target changed.
+  if (
+    networkCanvasHost.offsetHeight === FLAPPY_UI_NETWORK_HOST_FIXED_HEIGHT_PX
+  ) {
+    return;
+  }
+
+  // Step 2: Apply the fixed host height and request a post-layout redraw.
+  networkCanvasHost.style.height = `${FLAPPY_UI_NETWORK_HOST_FIXED_HEIGHT_PX}px`;
+  deferredNetworkRedrawController.requestNetworkRedrawAfterLayout();
+}
+
+/**
+ * Applies the resolved dimensions and scrolling rules to the stats container.
+ *
+ * @param statsContainer - Stats host element.
+ * @param responsiveViewportLayoutContext - Responsive layout context.
+ * @param statsPanelDimensions - Resolved stats panel dimensions.
+ * @returns Nothing.
+ */
+function applyStatsContainerDimensions(
+  statsContainer: HTMLElement,
+  responsiveViewportLayoutContext: ResponsiveViewportLayoutContext,
+  statsPanelDimensions: StatsPanelDimensions,
+): void {
+  // Step 1: Apply the resolved stats panel height.
+  statsContainer.style.height = `${statsPanelDimensions.adjustedStatsPanelHeightPx}px`;
+  statsContainer.style.maxHeight = `${statsPanelDimensions.adjustedStatsPanelHeightPx}px`;
+
+  // Step 2: Apply width and scrolling rules that differ between landscape and stacked layouts.
+  statsContainer.style.width =
+    responsiveViewportLayoutContext.useLandscapeSplitLayout
+      ? `${statsPanelDimensions.resolvedStatsPanelWidthPx}px`
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.fullSize;
+  statsContainer.style.maxWidth =
+    responsiveViewportLayoutContext.useLandscapeSplitLayout
+      ? `${statsPanelDimensions.resolvedStatsPanelWidthPx}px`
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.fullSize;
+  statsContainer.style.overflowY =
+    responsiveViewportLayoutContext.useLandscapeSplitLayout
+      ? FLAPPY_HOST_RESIZE_STYLE_TOKENS.autoOverflow
+      : FLAPPY_HOST_RESIZE_STYLE_TOKENS.hiddenOverflow;
+}

package/test/examples/flappy_bird/browser-entry/host/resize/host.resize.service.ts

@@ -0,0 +1,132 @@
+import {
+  applyMinimalMobileViewportLayout,
+  applyResponsiveCanvasBounds,
+  applyStandardViewportLayout,
+  createDeferredNetworkRedrawController,
+  installResponsiveViewportSizingListeners,
+} from './host.resize.service.services';
+import { resolveResponsiveViewportLayoutContext } from './host.resize.service.utils';
+import type {
+  DeferredNetworkRedrawController,
+  ResponsiveViewportSizingElements,
+} from './host.resize.service.types';
+
+/**
+ * Top-level responsive sizing orchestration for the browser host.
+ *
+ * This module wires the host resize lifecycle together: gather the relevant DOM
+ * elements, run the initial layout pass, and keep canvas sizing synchronized with
+ * viewport changes over time.
+ */
+
+/**
+ * Installs responsive viewport sizing for simulation and network canvases.
+ *
+ * This is the public entrypoint used by host assembly. It captures the elements,
+ * creates the deferred redraw policy, runs the first layout pass, and installs
+ * ongoing resize listeners.
+ *
+ * @param canvas - Simulation canvas to resize.
+ * @param containerElement - Width/height source.
+ * @param mainSplitContainer - Main split panel host.
+ * @param statsContainer - Stats host element.
+ * @param statsSplitContainer - Stats split panel containing stats and network panes.
+ * @param statsTableHost - Stats table host element.
+ * @param networkCanvas - Network canvas.
+ * @param networkCanvasHost - Network host element.
+ * @param onNetworkResize - Callback after network resize.
+ * @returns Nothing.
+ */
+export function installResponsiveViewportSizing(
+  canvas: HTMLCanvasElement,
+  containerElement: HTMLElement,
+  mainSplitContainer: HTMLElement,
+  statsContainer: HTMLElement,
+  statsSplitContainer: HTMLElement,
+  statsTableHost: HTMLElement,
+  networkCanvas: HTMLCanvasElement,
+  networkCanvasHost: HTMLElement,
+  onNetworkResize: () => void,
+): void {
+  // Step 1: Capture the DOM elements involved in responsive host sizing.
+  const responsiveViewportSizingElements: ResponsiveViewportSizingElements = {
+    canvas,
+    containerElement,
+    mainSplitContainer,
+    statsContainer,
+    statsSplitContainer,
+    statsTableHost,
+    networkCanvas,
+    networkCanvasHost,
+  };
+
+  // Step 2: Create the deferred redraw controller used after layout-affecting changes.
+  const deferredNetworkRedrawController =
+    createDeferredNetworkRedrawController(onNetworkResize);
+
+  // Step 3: Build the shared sizing callback used by initial load and resize events.
+  const applyCanvasSize = (): void => {
+    applyResponsiveViewportSizing(
+      responsiveViewportSizingElements,
+      deferredNetworkRedrawController,
+      onNetworkResize,
+    );
+  };
+
+  // Step 4: Run the initial sizing pass and install resize observers.
+  applyCanvasSize();
+  installResponsiveViewportSizingListeners(
+    containerElement,
+    applyCanvasSize,
+    deferredNetworkRedrawController,
+  );
+}
+
+/**
+ * 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.
+ *
+ * @param responsiveViewportSizingElements - Host elements participating in layout.
+ * @param deferredNetworkRedrawController - Deferred redraw controller.
+ * @param onNetworkResize - Immediate network resize callback.
+ * @returns Nothing.
+ */
+function applyResponsiveViewportSizing(
+  responsiveViewportSizingElements: ResponsiveViewportSizingElements,
+  deferredNetworkRedrawController: DeferredNetworkRedrawController,
+  onNetworkResize: () => void,
+): void {
+  // Step 1: Measure the current viewport constraints and layout mode flags.
+  const responsiveViewportLayoutContext =
+    resolveResponsiveViewportLayoutContext(
+      responsiveViewportSizingElements.containerElement,
+      responsiveViewportSizingElements.statsContainer,
+      responsiveViewportSizingElements.networkCanvasHost,
+    );
+
+  // Step 2: Route the simplest mobile layout through the dedicated minimal-flow helper.
+  if (responsiveViewportLayoutContext.useMinimalMobileLayout) {
+    applyMinimalMobileViewportLayout(
+      responsiveViewportSizingElements,
+      responsiveViewportLayoutContext,
+    );
+    return;
+  }
+
+  // Step 3: Apply the desktop and tablet host layout and resolve stats panel dimensions.
+  const statsPanelDimensions = applyStandardViewportLayout(
+    responsiveViewportSizingElements,
+    responsiveViewportLayoutContext,
+    deferredNetworkRedrawController,
+  );
+
+  // Step 4: Resize the simulation and network canvases for the resolved layout.
+  applyResponsiveCanvasBounds(
+    responsiveViewportSizingElements,
+    responsiveViewportLayoutContext,
+    statsPanelDimensions,
+    onNetworkResize,
+  );
+}

package/test/examples/flappy_bird/browser-entry/host/resize/host.resize.service.types.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared contracts for responsive browser-host sizing.
+ *
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+export type ResponsiveViewportSizingElements = {
+  canvas: HTMLCanvasElement;
+  containerElement: HTMLElement;
+  mainSplitContainer: HTMLElement;
+  statsContainer: HTMLElement;
+  statsSplitContainer: HTMLElement;
+  statsTableHost: HTMLElement;
+  networkCanvas: HTMLCanvasElement;
+  networkCanvasHost: HTMLElement;
+};
+
+/**
+ * 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.
+ */
+export type DeferredNetworkRedrawController = {
+  requestNetworkRedrawAfterLayout: () => void;
+};
+
+/**
+ * Measured viewport and panel budgets for responsive layout.
+ *
+ * These values are the raw numeric inputs to the resize policy before any mode
+ * branching happens.
+ */
+export type ResponsiveViewportMeasurements = {
+  headerHeightPx: number;
+  nonNetworkStatsHeightPx: number;
+  hardMinimumSimulationHeightPx: number;
+  totalCanvasBudgetPx: number;
+  viewportWidthPx: number;
+  viewportHeightPx: number;
+};
+
+/**
+ * Layout-mode flags resolved from the current viewport.
+ *
+ * The host currently distinguishes between minimal mobile, landscape split, and
+ * compact network-only variants.
+ */
+export type ResponsiveViewportLayoutFlags = {
+  useMinimalMobileLayout: boolean;
+  useLandscapeSplitLayout: boolean;
+  useNetworkOnlyPanel: boolean;
+};
+
+/**
+ * Full responsive layout context shared across sizing helpers.
+ *
+ * This merges measurements and mode flags into the one context object used by
+ * the resize appliers.
+ */
+export type ResponsiveViewportLayoutContext = ResponsiveViewportMeasurements &
+  ResponsiveViewportLayoutFlags;
+
+/**
+ * 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.
+ */
+export type StatsPanelDimensions = {
+  adjustedStatsPanelHeightPx: number;
+  resolvedStatsPanelWidthPx: number;
+};
+
+/**
+ * Width and height bounds for the simulation canvas.
+ *
+ * These are the final pixel budgets the simulation canvas may consume for the
+ * current responsive layout.
+ */
+export type SimulationCanvasBounds = {
+  availableWidthPx: number;
+  availableHeightPx: number;
+};