RtlZeroMemory · RtlZeroMemory · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026
@@ -58,6 +58,9 @@ jobs:
       - name: Check core portability
         run: npm run check:core-portability
 
+      - name: Check native vendor integrity
+        run: npm run check:native-vendor
+
       - name: Check Unicode pins (submodule sync)
         run: npm run check:unicode
 

@@ -55,7 +55,7 @@ Key pipeline files:
 - `packages/core/src/runtime/router/wheel.ts` — mouse wheel routing for scroll targets
 - `packages/core/src/renderer/renderToDrawlist/renderTree.ts` — stack-based DFS renderer
 - `packages/core/src/layout/dropdownGeometry.ts` — shared dropdown overlay geometry
-- `packages/core/src/drawlist/builder_v1.ts` — ZRDL binary drawlist builder
+- `packages/core/src/drawlist/builder.ts` — ZRDL binary drawlist builder (unified)
 
 ## Layout Engine Baseline (Current)
 
@@ -129,7 +129,7 @@ When core widget APIs change, JSX must be updated in the same change set.
 
 ### Drawlist writer codegen guardrail (MUST for ZRDL command changes)
 
-The v3/v4/v5 command writer implementation is code-generated. Never hand-edit
+The command writer implementation is code-generated. Never hand-edit
 `packages/core/src/drawlist/writers.gen.ts`.
 
 When changing drawlist command layout/opcodes/field widths/offsets:
@@ -170,6 +170,25 @@ node scripts/run-tests.mjs --filter "widget"
 2. If changing runtime, layout, or renderer code, also run integration tests.
 3. Run the full suite before committing.
 
+### Mandatory Live PTY Validation for UI Regressions
+
+For rendering/layout/theme regressions, do not stop at unit snapshots. Run the
+app in a real PTY and collect frame audit evidence yourself before asking a
+human to reproduce.
+
+Canonical runbook:
+
+- [`docs/dev/live-pty-debugging.md`](docs/dev/live-pty-debugging.md)
+
+Minimum required checks for UI regression work:
+
+1. Run target app/template in PTY with deterministic viewport.
+2. Exercise relevant routes/keys (for starship: `1..6`, `t`, `q`).
+3. Capture `REZI_FRAME_AUDIT` logs and analyze with
+   `node scripts/frame-audit-report.mjs ... --latest-pid`.
+4. Capture app-level debug snapshots (`REZI_STARSHIP_DEBUG=1`) when applicable.
+5. Include concrete evidence in your report (hash changes, route summary, key stages).
+
 ## Verification Protocol (Two-Agent Verification)
 
 When verifying documentation or code changes, split into two passes:

@@ -50,9 +50,9 @@ packages/core/src/
     renderToDrawlist/
       renderTree.ts           # Stack-based DFS renderer
   drawlist/
-    builder_v1.ts             # ZRDL binary drawlist builder (v1)
-    builder_v2.ts             # Drawlist builder v2 (cursor protocol)
-    builder_v3.ts             # Drawlist builder v3
+    builder.ts                # ZRDL binary drawlist builder (single unified version)
+    builderBase.ts            # Abstract base class for drawlist builder
+    writers.gen.ts            # Generated drawlist command writers (codegen)
   keybindings/
     manager.ts                # Modal keybinding system
     parser.ts                 # Key sequence parsing
@@ -505,6 +505,15 @@ result.toText();                   // Render to plain text for snapshots
 
 Test runner: `node:test`. Run all tests with `node scripts/run-tests.mjs`.
 
+For rendering regressions, add a live PTY verification pass and frame-audit
+evidence (not just snapshot/unit tests). Use:
+
+- [`docs/dev/live-pty-debugging.md`](docs/dev/live-pty-debugging.md)
+
+This runbook covers deterministic viewport setup, worker-mode PTY execution,
+route/theme key driving, and cross-layer log analysis (`REZI_FRAME_AUDIT`,
+`REZI_STARSHIP_DEBUG`, `frame-audit-report.mjs`).
+
 ## Skills (Repeatable Recipes)
 
 Project-level skills for both Claude Code and Codex:

@@ -163,7 +163,7 @@ source.
 - **Node.js 18+** with npm
 - **Rust toolchain** (for napi-rs compilation)
 - **C toolchain** (gcc, clang, or MSVC) for the Zireael engine
-- **Git submodules** initialized (`vendor/zireael` must be present)
+- **Git metadata available** (for vendor pin checks; full submodule checkout is needed when refreshing vendored engine sources)
 
 ### Build Command
 

@@ -35,9 +35,10 @@ cd Rezi
 git submodule update --init --recursive
 ```
 
-The `vendor/zireael` submodule contains the Zireael C engine source. It must be
-present for native addon builds, but is not required for TypeScript-only
-development.
+The `vendor/zireael` submodule tracks the upstream Zireael source and commit
+pin metadata. Native addon builds compile from the package-local snapshot at
+`packages/native/vendor/zireael`; submodule checkout is required when syncing
+or auditing vendored engine updates, but not for TypeScript-only development.
 
 Install all dependencies:
 

@@ -0,0 +1,176 @@
+# Live PTY UI Testing and Frame Audit Runbook
+
+This runbook documents how to validate Rezi UI behavior autonomously in a real
+terminal (PTY), capture end-to-end frame telemetry, and pinpoint regressions
+across core/node/native layers.
+
+Use this before asking a human for screenshots.
+
+## Why this exists
+
+Headless/unit tests catch many issues, but rendering regressions often involve:
+
+- terminal dimensions and capability negotiation
+- worker transport boundaries (core -> node worker -> native)
+- partial redraw/damage behavior across many frames
+
+The PTY + frame-audit workflow gives deterministic evidence for all of those.
+
+## Prerequisites
+
+From repo root:
+
+```bash
+cd /home/k3nig/Rezi
+npx tsc -b packages/core packages/node packages/create-rezi
+```
+
+## Canonical interactive run (Starship template)
+
+This enables:
+
+- app-level debug snapshots (`REZI_STARSHIP_DEBUG`)
+- cross-layer frame audit (`REZI_FRAME_AUDIT`)
+- worker execution path (`REZI_STARSHIP_EXECUTION_MODE=worker`)
+
+```bash
+cd /home/k3nig/Rezi
+: > /tmp/rezi-frame-audit.ndjson
+: > /tmp/starship.log
+
+env -u NO_COLOR \
+  REZI_STARSHIP_EXECUTION_MODE=worker \
+  REZI_STARSHIP_DEBUG=1 \
+  REZI_STARSHIP_DEBUG_LOG=/tmp/starship.log \
+  REZI_FRAME_AUDIT=1 \
+  REZI_FRAME_AUDIT_LOG=/tmp/rezi-frame-audit.ndjson \
+  npx tsx packages/create-rezi/templates/starship/src/main.ts
+```
+
+Key controls in template:
+
+- `1..6`: route switch (bridge/engineering/crew/comms/cargo/settings)
+- `t`: cycle theme
+- `q`: quit
+
+## Deterministic viewport (important)
+
+Many regressions are viewport-threshold dependent. Always test with a known
+size before comparing runs.
+
+For an interactive shell/PTY:
+
+```bash
+stty rows 68 cols 300
+```
+
+Then launch the app in that same PTY.
+
+## Autonomous PTY execution (agent workflow)
+
+When your agent runtime supports PTY stdin/stdout control:
+
+1. Start app in PTY mode (with env above).
+2. Send key sequences (`2`, `3`, `t`, `q`) through stdin.
+3. Wait between keys to allow frames to settle.
+4. Quit and analyze logs.
+
+Do not rely only on static test snapshots for visual regressions.
+
+## Frame audit analysis
+
+Use the built-in analyzer:
+
+```bash
+node scripts/frame-audit-report.mjs /tmp/rezi-frame-audit.ndjson --latest-pid
+```
+
+What to look for:
+
+- `backend_submitted`, `worker_payload`, `worker_accepted`, `worker_completed`
+  should stay aligned in worker mode.
+- `hash_mismatch_backend_vs_worker` should be `0`.
+- `top_opcodes` should reflect expected widget workload.
+- `route_summary` should show submissions for every exercised route.
+- `native_summary_records`/`native_header_records` confirm native debug pull
+  from worker path.
+
+If a log contains multiple app runs, always use `--latest-pid` (or `--pid=<n>`)
+to avoid mixed-session confusion.
+
+## Useful grep patterns
+
+```bash
+rg "runtime.command|runtime.fatal|shell.layout|engineering.layout|engineering.render|crew.render" /tmp/starship.log
+rg "\"stage\":\"table.layout\"|\"stage\":\"drawlist.built\"|\"stage\":\"frame.submitted\"|\"stage\":\"frame.completed\"" /tmp/rezi-frame-audit.ndjson
+```
+
+## Optional deep capture (drawlist bytes)
+
+Capture raw drawlist payload snapshots for diffing:
+
+```bash
+env \
+  REZI_FRAME_AUDIT=1 \
+  REZI_FRAME_AUDIT_DUMP_DIR=/tmp/rezi-drawlist-dumps \
+  REZI_FRAME_AUDIT_DUMP_MAX=20 \
+  REZI_FRAME_AUDIT_DUMP_ROUTE=crew \
+  npx tsx packages/create-rezi/templates/starship/src/main.ts
+```
+
+This writes paired `.bin` + `.json` files with hashes and metadata.
+
+## Native trace through frame-audit
+
+Native debug records are enabled by frame audit in worker mode. Controls:
+
+- `REZI_FRAME_AUDIT_NATIVE=1|0` (default on when frame audit is enabled)
+- `REZI_FRAME_AUDIT_NATIVE_RING=<bytes>` (ring size override)
+
+Look for stages such as:
+
+- `native.debug.header`
+- `native.drawlist.summary`
+- `native.frame.*`
+- `native.perf.*`
+
+## Triage playbook for common regressions
+
+### 1) “Theme only updates animated region”
+
+Check:
+
+1. `runtime.command` contains `cycle-theme`.
+2. `drawlist.built` hashes change after theme switch.
+3. `frame.submitted`/`frame.completed` continue for that route.
+
+If hashes do not change, bug is likely in view/theme resolution.
+If hashes change but screen does not, investigate native diff/damage path.
+
+### 2) “Table looks empty or only one row visible”
+
+Check `table.layout` record:
+
+- `bodyH`
+- `visibleRows`
+- `startIndex` / `endIndex`
+- table rect height
+
+If `bodyH` is too small, inspect parent layout/flex and sibling widgets
+(pagination or controls often steal height).
+
+### 3) “Worker mode renders differently from inline”
+
+Run both modes with identical viewport and compare audit summaries:
+
+- worker: `REZI_STARSHIP_EXECUTION_MODE=worker`
+- inline: `REZI_STARSHIP_EXECUTION_MODE=inline`
+
+If only worker diverges, focus on backend transport and worker audit stages.
+
+## Guardrails
+
+- Keep all instrumentation opt-in via env vars.
+- Never print continuous debug spam to stdout during normal app usage.
+- Write logs to files (`/tmp/...`) and inspect post-run.
+- Prefer deterministic viewport + scripted route/theme steps when verifying fixes.
@@ -144,6 +144,7 @@ Build, test, and CI automation scripts.
 | `docs.sh`                          | Documentation build/serve with automatic venv management. |
 | `guardrails.sh`                    | Repository hygiene checks for forbidden patterns (legacy scope/name, unresolved task markers, and synthetic-content markers). |
 | `check-core-portability.mjs`      | Scans `@rezi-ui/core` for prohibited Node.js imports. |
+| `check-native-vendor-integrity.mjs` | Verifies native vendor source wiring and `VENDOR_COMMIT.txt` pin consistency with `vendor/zireael`. |
 | `check-unicode-sync.mjs`          | Verifies Unicode table versions are consistent. |
 | `check-create-rezi-templates.mjs` | Validates scaffolding templates are up to date. |
 | `verify-native-pack.mjs`          | Checks native package contents before npm publish. |
@@ -152,9 +153,11 @@ Build, test, and CI automation scripts.
 ## vendor/zireael
 
 The Zireael C rendering engine, pinned as a git submodule. This is the upstream
-source used by `@rezi-ui/native` for compilation. The native package keeps its
-own vendored snapshot at `packages/native/vendor/zireael` as the compile-time
-source.
+reference tree. `@rezi-ui/native` compiles from the package-local snapshot at
+`packages/native/vendor/zireael` (see `packages/native/build.rs`).
+
+`packages/native/vendor/VENDOR_COMMIT.txt` must match the repo gitlink pointer
+for `vendor/zireael`; CI enforces this via `npm run check:native-vendor`.
 
 Initialize with:
 

@@ -66,6 +66,18 @@ npm run test:e2e
 npm run test:e2e:reduced
 ```
 
+## Live PTY Rendering Validation (for UI regressions)
+
+For terminal rendering/theme/layout regressions, run a live PTY session with
+frame-audit instrumentation in addition to normal tests.
+
+Use the dedicated runbook:
+
+- [Live PTY UI Testing and Frame Audit Runbook](live-pty-debugging.md)
+
+That guide includes deterministic viewport setup, worker-mode run commands,
+scripted key driving, and cross-layer telemetry analysis.
+
 ## Test Categories
 
 ### Unit Tests

@@ -24,6 +24,8 @@ Pinned drawlist version:
 
 Rezi currently emits ZRDL v1, and the engine accepts v1/v2.
 ZRDL v2 adds opcode `14` (`BLIT_RECT`).
+Style link reference fields (`linkUriRef`, `linkIdRef`) are stable across v1/v2:
+`0` means unset and positive values are 1-based string resource IDs.
 
 ## Event Batch (ZREV)
 

@@ -57,6 +57,23 @@ Commands are 4-byte aligned.
 - `FREE_*` invalidates that ID.
 - Draw commands referencing unknown IDs fail.
 
+## Style Payload Link References
+
+Text-bearing commands carry style fields that include hyperlink references:
+
+- `linkUriRef` (`u32`)
+- `linkIdRef` (`u32`)
+
+These fields use the same ID space as `DEF_STRING`/`FREE_STRING` and are
+**1-based**:
+
+- `0` means "no active link" (sentinel unset)
+- `N > 0` maps to string resource ID `N`
+
+Rezi encodes link references as `(internedIndex + 1)`, and Zireael resolves
+them as direct string IDs. This is part of the v1/v2 wire contract and does
+not introduce a new drawlist version.
+
 ## Codegen
 
 Command layouts are defined in `scripts/drawlist-spec.ts`.