core: add root padding, responsive viewport, and layout diagnostics (#121)

* core: add root padding, responsive viewport hooks, and layout diagnostics

* runtime: plumb viewport snapshot through composite widget context

* core: fix viewport resize commit gating and full constraints

* core: make layout warnings opt-in in dev mode

Author: RtlZeroMemory

docs/guide/debugging.md

@@ -74,6 +74,18 @@ Overlay sections include:
 - Frame timing rows (`drawlistBytes`, `diffBytesEmitted`, `usDrawlist`, `usDiff`, `usWrite`)
 - Event routing breadcrumbs (last event kind, keybindings vs widget routing path, last action)
 
+## Quick Layout Overlay
+
+For quick in-app layout diagnostics (without the full inspector), toggle:
+
+```typescript
+app.debugLayout(true);  // enable
+app.debugLayout(false); // disable
+```
+
+When enabled, Rezi renders a live layout summary overlay with widget ids and
+resolved rects.
+
 ## Export Debug Bundle
 
 Exporting a debug bundle is deterministic for the same debug state and options.

docs/widgets/stack.md

@@ -17,16 +17,18 @@ ui.column({ gap: 1, p: 1 }, [ui.text("A"), ui.text("B")]);
 |---|---|---|---|
 | `id` | `string` | - | Optional identity (not focusable) |
 | `key` | `string` | - | Reconciliation key |
-| `gap` | `SpacingValue` | - | Spacing between children |
+| `gap` | `SpacingValue` | `1` | Spacing between children |
+| `reverse` | `boolean` | `false` | Reverse child visual order |
 | `align` | `"start" \| "center" \| "end" \| "stretch"` | `"start"` | Cross-axis alignment |
-| `justify` | `"start" \| "end" \| "center" \| "between" \| "around" \| "evenly"` | `"start"` | Main-axis distribution |
+| `justify` | `"start" \| "end" \| "center" \| "between" \| "around" \| "evenly"` (also CSS aliases: `"space-between"`, `"space-around"`, `"space-evenly"`) | `"start"` | Main-axis distribution |
 | `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl` | `SpacingValue` | - | Padding props |
 | `m`, `mx`, `my` | `SpacingValue` | - | Margin props |
-| `width`, `height` | `number \| \"auto\" \| \"${number}%\"` | - | Size constraints |
+| `width`, `height` | `number \| \"auto\" \| \"full\" \| \"${number}%\"` | - | Size constraints |
 | `minWidth`, `maxWidth`, `minHeight`, `maxHeight` | `number` | - | Size bounds (cells) |
 | `flex` | `number` | - | Main-axis flex in parent stack |
 | `aspectRatio` | `number` | - | Enforce width/height ratio |
-| `style` | `TextStyle` | - | Inherited style for children; bg fills rect |
+| `style` | `TextStyle` | - | Container style override; bg fills rect |
+| `inheritStyle` | `TextStyle` | - | Descendant default style without fill |
 
 ## Examples
 
@@ -57,10 +59,10 @@ ui.column({ height: 6, justify: "between" }, [
 
 Rezi also includes:
 
-- `ui.hstack(...)` — shorthand row with default `gap: 0`
-- `ui.vstack(...)` — shorthand column with default `gap: 0`
-- `ui.spacedHStack(...)` — shorthand row with default `gap: 1`
-- `ui.spacedVStack(...)` — shorthand column with default `gap: 1`
+- `ui.hstack(...)` — shorthand row with default `gap: 1`
+- `ui.vstack(...)` — shorthand column with default `gap: 1`
+- `ui.spacedHStack(...)` — shorthand row with default `gap: 1` (alias)
+- `ui.spacedVStack(...)` — shorthand column with default `gap: 1` (alias)
 
 ## Related
 

packages/core/src/app/__tests__/dirtyFlagPlan.test.ts

@@ -1,5 +1,5 @@
 import { assert, test } from "@rezi-ui/testkit";
-import { ui } from "../../index.js";
+import { defineWidget, ui } from "../../index.js";
 import { createApp } from "../createApp.js";
 import { encodeZrevBatchV1, flushMicrotasks, makeBackendBatch } from "./helpers.js";
 import { StubBackend } from "./stubBackend.js";
@@ -108,6 +108,59 @@ test("resize (DIRTY_LAYOUT) re-layouts without calling view", async () => {
   assert.equal(ctx.getViewCalls(), 1, "view NOT re-invoked for layout-only dirty");
 });
 
+test("debugLayout toggle marks view dirty and re-runs commit path", async () => {
+  const ctx = setup();
+  await bootstrap(ctx);
+
+  ctx.app.debugLayout(true);
+  await flushMicrotasks(10);
+
+  assert.equal(ctx.backend.requestedFrames.length, 2, "debug toggle submitted a frame");
+  assert.equal(ctx.getViewCalls(), 2, "debug toggle re-invoked view immediately");
+});
+
+test("resize re-invokes view when composite widgets read viewport", async () => {
+  const backend = new StubBackend();
+  let viewCalls = 0;
+  const app = createApp({ backend, initialState: {} });
+
+  const ViewportAware = defineWidget<{ key?: string }>((_props, ctx) => {
+    const vp = ctx.useViewport?.();
+    return ui.text(`vp:${String(vp?.width ?? 0)}x${String(vp?.height ?? 0)}`);
+  });
+
+  app.view(() => {
+    viewCalls++;
+    return ui.column({}, [ViewportAware({ key: "vp" })]);
+  });
+
+  await app.start();
+  backend.pushBatch(
+    makeBackendBatch({
+      bytes: encodeZrevBatchV1({
+        events: [{ kind: "resize", timeMs: 1, cols: 40, rows: 10 }],
+      }),
+    }),
+  );
+  await flushMicrotasks(10);
+  assert.equal(backend.requestedFrames.length, 1);
+  assert.equal(viewCalls, 1);
+  backend.resolveNextFrame();
+  await flushMicrotasks(5);
+
+  backend.pushBatch(
+    makeBackendBatch({
+      bytes: encodeZrevBatchV1({
+        events: [{ kind: "resize", timeMs: 2, cols: 80, rows: 20 }],
+      }),
+    }),
+  );
+  await flushMicrotasks(10);
+
+  assert.equal(backend.requestedFrames.length, 2, "second resize submitted a commit frame");
+  assert.equal(viewCalls, 2, "viewport-aware composite forced view re-run on resize");
+});
+
 test("first frame always runs full pipeline regardless of dirty flags", async () => {
   const ctx = setup();
   await ctx.app.start();

packages/core/src/app/createApp.ts

@@ -57,6 +57,11 @@ import {
   routeKeyEvent,
   setMode,
 } from "../keybindings/index.js";
+import {
+  type ResponsiveBreakpointThresholds,
+  normalizeBreakpointThresholds,
+} from "../layout/responsive.js";
+import type { Rect } from "../layout/types.js";
 import { PERF_ENABLED, perfMarkEnd, perfMarkStart, perfNow, perfRecord } from "../perf/perf.js";
 import type { EventTimeUnwrapState } from "../protocol/types.js";
 import { parseEventBatchV1 } from "../protocol/zrev_v1.js";
@@ -71,6 +76,8 @@ import { defaultTheme } from "../theme/defaultTheme.js";
 import { coerceToLegacyTheme } from "../theme/interop.js";
 import type { Theme } from "../theme/theme.js";
 import type { ThemeDefinition } from "../theme/tokens.js";
+import type { VNode } from "../widgets/types.js";
+import { ui } from "../widgets/ui.js";
 import { RawRenderer } from "./rawRenderer.js";
 import {
   type RuntimeBreadcrumbAction,
@@ -95,6 +102,8 @@ type ResolvedAppConfig = Readonly<{
   fpsCap: number;
   maxEventBytes: number;
   maxDrawlistBytes: number;
+  rootPadding: number;
+  breakpointThresholds: ResponsiveBreakpointThresholds;
   useV2Cursor: boolean;
   drawlistValidateParams: boolean;
   drawlistReuseOutputBuffer: boolean;
@@ -114,6 +123,8 @@ const DEFAULT_CONFIG: ResolvedAppConfig = Object.freeze({
   fpsCap: 60,
   maxEventBytes: 1 << 20 /* 1 MiB */,
   maxDrawlistBytes: 2 << 20 /* 2 MiB */,
+  rootPadding: 0,
+  breakpointThresholds: normalizeBreakpointThresholds(undefined),
   useV2Cursor: false,
   drawlistValidateParams: true,
   drawlistReuseOutputBuffer: true,
@@ -232,6 +243,29 @@ async function loadTerminalProfile(backend: RuntimeBackend): Promise<TerminalPro
   }
 }
 
+function buildLayoutDebugOverlay(rectById: ReadonlyMap<string, Rect>): VNode | null {
+  if (rectById.size === 0) return null;
+  const rows = [...rectById.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .slice(0, 18)
+    .map(([id, rect]) =>
+      ui.text(`${id}  ${String(rect.x)},${String(rect.y)}  ${String(rect.w)}x${String(rect.h)}`),
+    );
+  const panel = ui.box({ border: "single", title: `Layout (${String(rectById.size)})`, p: 1 }, [
+    ui.column({ gap: 0 }, rows),
+  ]);
+  return ui.layer({
+    id: "rezi.layout.debug.overlay",
+    zIndex: 2_000_000_000,
+    modal: false,
+    backdrop: "none",
+    closeOnEscape: false,
+    content: ui.column({ width: "100%", height: "100%", justify: "end", p: 1 }, [
+      ui.row({ width: "100%", justify: "start" }, [panel]),
+    ]),
+  });
+}
+
 /** Apply defaults to user-provided config, validating all values. */
 export function resolveAppConfig(config: AppConfig | undefined): ResolvedAppConfig {
   if (!config) return DEFAULT_CONFIG;
@@ -247,6 +281,11 @@ export function resolveAppConfig(config: AppConfig | undefined): ResolvedAppConf
     config.maxDrawlistBytes === undefined
       ? DEFAULT_CONFIG.maxDrawlistBytes
       : requirePositiveInt("maxDrawlistBytes", config.maxDrawlistBytes);
+  const rootPadding =
+    config.rootPadding === undefined
+      ? DEFAULT_CONFIG.rootPadding
+      : requireNonNegativeInt("rootPadding", config.rootPadding);
+  const breakpointThresholds = normalizeBreakpointThresholds(config.breakpoints);
   const useV2Cursor = config.useV2Cursor === true;
   const drawlistValidateParams =
     config.drawlistValidateParams === undefined
@@ -276,6 +315,8 @@ export function resolveAppConfig(config: AppConfig | undefined): ResolvedAppConf
     fpsCap,
     maxEventBytes,
     maxDrawlistBytes,
+    rootPadding,
+    breakpointThresholds,
     useV2Cursor,
     drawlistValidateParams,
     drawlistReuseOutputBuffer,
@@ -445,6 +486,7 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
   let mode: Mode | null = null;
   let drawFn: DrawFn | null = null;
   let viewFn: ViewFn<S> | null = null;
+  let debugLayoutEnabled = false;
 
   const hasInitialState = "initialState" in opts;
   let committedState: S = hasInitialState ? (opts.initialState as S) : (Object.freeze({}) as S);
@@ -557,6 +599,8 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
     backend,
     drawlistVersion,
     maxDrawlistBytes: config.maxDrawlistBytes,
+    rootPadding: config.rootPadding,
+    breakpointThresholds: config.breakpointThresholds,
     terminalProfile,
     useV2Cursor: config.useV2Cursor,
     ...(opts.config?.drawlistValidateParams === undefined
@@ -846,7 +890,12 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
           const prev = viewport;
           if (prev === null || prev.cols !== ev.cols || prev.rows !== ev.rows) {
             viewport = Object.freeze({ cols: ev.cols, rows: ev.rows });
-            markDirty(DIRTY_LAYOUT);
+            if (widgetRenderer.hasViewportAwareComposites()) {
+              widgetRenderer.invalidateCompositeWidgets();
+              markDirty(DIRTY_LAYOUT | DIRTY_VIEW);
+            } else {
+              markDirty(DIRTY_LAYOUT);
+            }
           }
         }
         if (ev.kind === "tick" && mode === "widget") {
@@ -1177,7 +1226,15 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
 
     const renderStart = perfNow();
     const submitToken = perfMarkStart("submit_frame");
-    const res = widgetRenderer.submitFrame(vf, snapshot, viewport, theme, hooks, plan);
+    const frameView: ViewFn<S> = debugLayoutEnabled
+      ? (state) => {
+          const root = vf(state);
+          const overlay = buildLayoutDebugOverlay(widgetRenderer.getRectByIdIndex());
+          if (!overlay) return root;
+          return ui.layers([root, overlay]);
+        }
+      : vf;
+    const res = widgetRenderer.submitFrame(frameView, snapshot, viewport, theme, hooks, plan);
     perfMarkEnd("submit_frame", submitToken);
     if (!res.ok) {
       fatalNowOrEnqueue(res.code, res.detail);
@@ -1363,6 +1420,18 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
       requestRenderFromRenderer();
     },
 
+    debugLayout(enabled?: boolean): boolean {
+      assertOperational("debugLayout");
+      if (mode === "raw") {
+        throwCode("ZRUI_MODE_CONFLICT", "debugLayout: not available in draw mode");
+      }
+      const next = enabled === undefined ? !debugLayoutEnabled : enabled === true;
+      if (next === debugLayoutEnabled) return debugLayoutEnabled;
+      debugLayoutEnabled = next;
+      requestViewFromRenderer();
+      return debugLayoutEnabled;
+    },
+
     start(): Promise<void> {
       assertOperational("start");
       assertNotReentrant("start");

packages/core/src/app/inspectorOverlayHelper.ts

@@ -253,6 +253,9 @@ export function createAppWithInspectorOverlay<S>(
       lastThemeInput = theme;
       app.setTheme(theme);
     },
+    debugLayout(enabled?: boolean): boolean {
+      return app.debugLayout(enabled);
+    },
     start(): Promise<void> {
       return app.start();
     },