Skip to content

refactor(core): split stack layout engine by concern#280

Merged
RtlZeroMemory merged 1 commit intomainfrom
codex/split-layout-stack
Mar 17, 2026
Merged

refactor(core): split stack layout engine by concern#280
RtlZeroMemory merged 1 commit intomainfrom
codex/split-layout-stack

Conversation

@RtlZeroMemory
Copy link
Copy Markdown
Owner

@RtlZeroMemory RtlZeroMemory commented Mar 17, 2026

Summary

  • Split packages/core/src/layout/kinds/stack.ts into internal modules.
  • Kept the public API unchanged.
  • No intended behavior change.

Why

  • Reduce the largest layout monolith before deeper runtime/layout refactors.

Validation

  • npm install
  • npm run lint
  • npm run typecheck
  • npm run build
  • node scripts/run-tests.mjs --scope packages --filter "packages/core/dist/layout/__tests__/"
  • node scripts/run-tests.mjs
  • npm run build:native
  • PTY run: stty rows 68 cols 300 then env -u NO_COLOR REZI_STARSHIP_EXECUTION_MODE=worker REZI_STARSHIP_DEBUG=1 REZI_STARSHIP_DEBUG_LOG=/tmp/starship-stack.log REZI_FRAME_AUDIT=1 REZI_FRAME_AUDIT_LOG=/tmp/rezi-frame-audit-stack.ndjson npx tsx packages/create-rezi/templates/starship/src/main.ts
  • node scripts/frame-audit-report.mjs /tmp/rezi-frame-audit-stack.ndjson --latest-pid

PTY/frame-audit evidence

  • Deterministic viewport reached 300x68 after startup negotiation; starship log recorded the route flow bridge -> engineering -> crew -> cargo, plus cycle-theme, cargo-sort-quantity, and quit commands.
  • Frame audit summary: records=17221, backend_submitted=818, worker_payload=818, worker_accepted=818, worker_completed=818.
  • hash_mismatch_backend_vs_worker=0 and missing_worker_payload=0.
  • Route summary: bridge submitted=306 completed=306, engineering submitted=443 completed=443, crew submitted=41 completed=41, cargo submitted=28 completed=28.
  • Native audit records were present throughout worker mode: native_summary_records=818, native_header_records=1636.

Summary by CodeRabbit

  • Refactor
    • Reorganized stack layout system with modularized components for improved maintainability.
    • Enhanced layout measurement and constraint planning to better support wrapping, alignment, and flex properties.
    • Public API signatures remain unchanged; internal architecture improved for stability.

@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 17, 2026

📝 Walkthrough

Walkthrough

This PR refactors the stack layout implementation from a monolithic 1987-line file into modularized components: separate modules for axis handling, constraint planning, layout rendering, measurement, wrapping, and shared utilities. The original stack.ts is reduced to minimal delegating code using a new invalid() error helper.

Changes

Cohort / File(s) Summary
Stack core refactoring
packages/core/src/layout/kinds/stack.ts
Removed ~1974 lines of inline layout logic (types, axis config, measure/layout/shift code, constraint planning, wrapping). Replaced with imports from stackParts modules and a new invalid(detail: string) helper for standardized fatal-error responses. measureStackKinds and layoutStackKinds now delegate to stackParts and use invalid() for error cases.
Axis module
packages/core/src/layout/kinds/stackParts/axis.ts
New module providing AxisConfig type and helper utilities. Exports ROW_AXIS and COL_AXIS configs, getAxisConfig() to map vnode kinds to axis, and dimension conversion functions (mainFromWH, crossFromWH, toWH, toXY) for axis-aware calculations.
Constraint planning
packages/core/src/layout/kinds/stackParts/constraintPlan.ts
New module implementing constraint-based sizing for main and cross axes. Introduces planConstraintMainSizes() (with legacy and advanced flex code paths) and planConstraintCrossSizes(). Handles spacers, absolute positioning, percent-based sizing, flex distribution, and rebalancing.
Layout and measurement
packages/core/src/layout/kinds/stackParts/layout.ts, measure.ts
New modules for rendering and measuring stack vnodes. layoutStack() handles wrapping, alignment, constraint passes, and child positioning. measureStack() computes layout dimensions with support for wrapping and constraint-based sizing. Both integrate with axis, constraint planning, and shared helpers.
Shared utilities and wrapping
packages/core/src/layout/kinds/stackParts/shared.ts, wrap.ts
shared.ts exports type aliases (MeasureNodeFn, StackVNode, LayoutNodeFn) and helpers for alignment resolution, axis-based measurement/layout, and layout-tree manipulation. wrap.ts provides wrapping line layout machinery with probeWrapChildMain(), computeWrapConstraintLine(), and rebalancing for near-full-percent children.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Poem

🐰 A rabbit's ode to modular grace:

Stack once towering, dense and tall,
Now split to modules, answering the call,
Axis, constraints, and wrapping lines,
Each file shines with purposeful designs,
From chaos blooms a cleaner space! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: refactoring the stack layout engine by splitting it into modular concerns.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/split-layout-stack
📝 Coding Plan
  • Generate coding plan for human review comments

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
packages/core/src/layout/kinds/stack.ts (1)

11-16: Consider importing the existing invalid() helper instead of duplicating it.

There's an identical invalid() function in packages/core/src/layout/validate/shared.ts (lines 11-13). To reduce code duplication and maintain consistency, consider importing it from there.

♻️ Proposed refactor
 import type { VNode } from "../../widgets/types.js";
 import type { LayoutTree } from "../engine/types.js";
 import type { Axis, Size } from "../types.js";
 import type { LayoutResult } from "../validateProps.js";
+import { invalid } from "../validate/shared.js";
 import { getAxisConfig } from "./stackParts/axis.js";
 import { layoutStack } from "./stackParts/layout.js";
 import { measureStack } from "./stackParts/measure.js";
 import type { LayoutNodeFn, MeasureNodeFn } from "./stackParts/shared.js";
 import { isStackVNode } from "./stackParts/shared.js";

-function invalid(detail: string): LayoutResult<never> {
-  return {
-    ok: false as const,
-    fatal: { code: "ZRUI_INVALID_PROPS" as const, detail },
-  };
-}
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/layout/kinds/stack.ts` around lines 11 - 16, Remove the
duplicated invalid() helper in stack.ts and import the existing invalid helper
from the validate/shared module instead: delete the local function
`invalid(detail: string): LayoutResult<never>` and add an import for the shared
`invalid` so calls in this file use the single shared implementation; ensure the
imported symbol matches the exported name in
`packages/core/src/layout/validate/shared.ts` and that `LayoutResult` typings
remain compatible, then run tests/typecheck to confirm no type regressions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/core/src/layout/kinds/stack.ts`:
- Around line 11-16: Remove the duplicated invalid() helper in stack.ts and
import the existing invalid helper from the validate/shared module instead:
delete the local function `invalid(detail: string): LayoutResult<never>` and add
an import for the shared `invalid` so calls in this file use the single shared
implementation; ensure the imported symbol matches the exported name in
`packages/core/src/layout/validate/shared.ts` and that `LayoutResult` typings
remain compatible, then run tests/typecheck to confirm no type regressions.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2dc7df38-0978-4ec1-a5ed-d913d7101fb7

📥 Commits

Reviewing files that changed from the base of the PR and between 407993c and a4652e4.

📒 Files selected for processing (7)
  • packages/core/src/layout/kinds/stack.ts
  • packages/core/src/layout/kinds/stackParts/axis.ts
  • packages/core/src/layout/kinds/stackParts/constraintPlan.ts
  • packages/core/src/layout/kinds/stackParts/layout.ts
  • packages/core/src/layout/kinds/stackParts/measure.ts
  • packages/core/src/layout/kinds/stackParts/shared.ts
  • packages/core/src/layout/kinds/stackParts/wrap.ts

@RtlZeroMemory RtlZeroMemory merged commit d4b23a1 into main Mar 17, 2026
32 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant