# Render Module Data Flow

## What It Does
- Summary: Coordinates high-level sheet rendering and UI assembly: instantiates renderer services, creates sheet panels, computes viewport/scale, orchestrates data fetch (`getData`) and delegates rendering to `sheet`, `row`, and `cell` renderers. Manages virtualization, frozen panes, scroll synchronization and lifecycle events. See `src/spreadsheet/renderer/render.ts`.

## Entry Points (UI / Core)
- UI (Coordinator):
  - `Render.render()` — bootstrap UI: set active sheet, render ribbon/formula bar, create sheet panel, and call `renderSheet`.
  - `Render.refreshUI(args, address?, initLoad?, ...)` — main refresh entry that computes visible address ranges, requests `getData`, and routes responses to sheet renderer methods (`renderTable`, `refreshRowContent`, `refreshColumnContent`, `updateRowContent`, `updateColContent`).
  - `Render.refreshSheet(isOpen?, resize?, ...)` — re-create sheet DOM and re-calc top-left scroll position; calls `deInitProperties` and `checkTopLeftCell`.
  - `Render.setSheetPanelSize(colMinWidth?)` — measure container, compute `viewport` dimensions and scale factors (`scaleX`, `scaleY`) and set `rowCount`/`colCount`.
  - `Render.destroy()` — teardown and unregister renderer services.
- Core (Utilities / Coordination):
  - `Render.checkTopLeftCell(initLoad?, ...)` — reconciles `topLeftCell` vs `paneTopLeftCell`, computes `viewport.beforeFreeze*` offsets, and decides fresh vs virtualized refresh.
  - `Render.updateTopLeftScrollPosition(args)` — computes scroll offsets using `getRowsHeight`/`getColumnsWidth` when top-left/pane positions change.
  - `Render.instantiateRenderer()` — registers `cell`, `row`, `sheet` renderers in service locator.
  - Event hooks: listens for `spreadsheetDestroyed`, `moveOrDuplicateSheet`, `getUpdatedScrollPosition`.

## Core Logic Flow (ASCII)
User opens sheet or triggers refresh
         ↓
`Render.render()` builds panel and calls `renderSheet()` → service `sheet` renders panels
         ↓
`checkTopLeftCell()` computes viewport/top-left vs freeze offsets
         ↓
`refreshUI()` computes address range (virtualized or full), calls `getData(workbook, address)`
         ↓
`getData` returns cell map → `refreshUI` routes to `sheetModule.renderTable` or incremental refresh methods
         ↓
`sheet`/`row`/`cell` renderers update DOM, then `Render` runs post-render checks (`checkRowHeightChanged`, `checkTableWidth`), triggers `contentLoaded`/`dataBound` events

## Operations Handled (functions & notes)
- Viewport & virtualization:
  - Computes visible ranges using thresholds and `skipHiddenIdx`, adjusts for frozen rows/columns and finite scrolling.
  - Maintains `parent.viewport` (top/left/bottom/right indices, row/col counts, scale factors).
- Data fetch and routing:
  - Builds `address` string from computed start/end indexes and calls `getData`; guards against stale sheet index or canceled refresh.
  - Based on `args.refresh` routes the fetched `Map<string, CellModel>` to the appropriate sheet renderer API for full or partial updates.
- Layout & scaling:
  - `setSheetPanelSize` measures container, computes `scaleX/scaleY` when `enableScaling` is true, derives `viewport.rowCount/colCount` via `roundValue`.
  - `updateTopLeftScrollPosition` uses `getRowsHeight`/`getColumnsWidth` to set pixel offsets for top-left cell.
- Lifecycle & registration:
  - `instantiateRenderer` registers services `cell`, `row`, `sheet` for decoupled rendering.
  - `addEventListener`/`removeEventListener` hook into global spreadsheet events and manage cleanup.
- Helper utilities:
  - `decreaseHidden` adjusts virtualized start indexes skipping hidden rows/cols.
  - `removeSheet` cleans and removes old sheet DOM before full re-render.

## Validation & Safety
- Stale-response guard: `refreshUI` verifies sheet id/index after `getData` resolves to avoid applying data to outdated views.
- Freeze/top-left reconciliation: `checkTopLeftCell` ensures frozen-pane offsets are applied and `viewport.beforeFreeze*` are computed to avoid jumpy scrolls.
- Finite scrolling bounds: when scrollable range exceeds sheet limits, adjusts start indexes and uses `updateTranslate` to maintain correct translate offsets.
- Defensive teardown: `destroy` removes event listeners and nulls registered services to prevent leaks.

## Desired Outputs
- User-Facing:
  - Visible sheet UI: ribbon/formula bar (when applicable), sheet panel with `e-sheet` container, responsive viewport with virtualization and frozen panes.
  - Smooth scroll/resize behavior with correct row/column rendering as user pans or resizes window.
  - Incremental updates on edits/inserts that minimize DOM churn.
- System-Level:
  - Services: `serviceLocator` entries for `cell`, `row`, `sheet` renderers.
  - Viewport state: `parent.viewport` populated with `scaleX/scaleY`, `rowCount/colCount`, and index bounds used by renderer modules.
  - Events: triggers and listens to `beforeDataBound`, `contentLoaded`, `beforeVirtualContentLoaded`, `getUpdatedScrollPosition`, `moveOrDuplicateSheet`, `spreadsheetDestroyed`, `beforeContentLoaded`, `onContentScroll`.
  - DOM artifacts: top-level `e-sheet-panel`, `e-sheet`, and delegated `e-main-panel`, `e-row-header`, `e-column-header`, `e-sheet-content` created by `sheet` renderer.
  - Undo/Redo: high-level sheet operations that mutate model (e.g., `moveSheet`, `duplicateSheet`) are wrapped with `actionBegin`/`actionComplete` and should integrate with workbook undo/redo.

Notes: This module is the orchestration layer — minimal DOM work is done here; it focuses on computing ranges, fetching data, coordinating renderer services, and handling lifecycle/events.