docs(guide,backend,readme): document inline screen mode + example app

- new centralized guide: docs/guide/screen-modes.md (usage, sizing,
  behavior, capability fallback, naming distinction vs executionMode)
- mkdocs nav, backend/node.md screen section, protocol/abi.md 1.3.0 pin,
  README feature visibility, CLAUDE.md examples/map updates
- examples/inline-status: runnable inline-mode app (spinner + progress +
  quit keys), verified end-to-end in a real terminal (tmux): scrollback
  preserved, live repaints, mid-run resize reflow, final frame left in
  scrollback with prompt restored below

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: RtlZeroMemory

CLAUDE.md

@@ -20,6 +20,7 @@ Current public templates:
 
 Repository examples:
 - `examples/hello-counter`
+- `examples/inline-status` (inline screen mode: scrollback-preserving region)
 - `examples/raw-draw-demo`
 - `examples/gallery`
 - `examples/regression-dashboard` (validation surface for layout/render/input regressions)
@@ -158,6 +159,7 @@ Practical defaults:
 - Do not hand-edit generated drawlist writers.
 - Prefer semantic widgets and recipe-driven styling over manual status rendering.
 - Prefer `ui.virtualList` for large collections.
+- Screen modes: `config.screen = { mode: "alt" | "inline", inlineRows }` selects alt-screen vs inline presentation (docs/guide/screen-modes.md). Distinct from `executionMode: "inline"` (engine-on-main-thread).
 
 ## Skills
 

README.md

@@ -20,12 +20,15 @@ Individual widgets carry explicit [stability tiers](docs/widgets/stability.md) (
 
 Dashboards, control planes, internal tools, log viewers, agent consoles, and developer workflows that need more than line-oriented output: multi-panel layouts, routed screens, focusable controls, forms, tables, overlays, and predictable behavior under keyboard and mouse input.
 
+Apps choose their presentation: full-screen on the alternate buffer, or **inline screen mode** — a bounded region on the primary screen with terminal scrollback preserved above it and the final frame left in scrollback on exit (the presentation style of agent CLIs, progress UIs, and REPLs). See the [Screen Modes guide](docs/guide/screen-modes.md).
+
 ## Why Rezi
 
 - A structured app model instead of a rendering loop you assemble yourself
 - A declarative widget API that does not require React
 - Native framebuffer diffing and terminal output through a fuzz-tested C engine
 - First-party widgets for forms, tables, trees, overlays, charts, file pickers, and command palettes
+- Full-screen and inline screen modes from the same widget API (`screen: { mode: "inline", inlineRows: 9 }`)
 - Reproducible rendering and input contracts, so application behavior is testable
 
 ## Example

docs/backend/node.md

@@ -65,6 +65,28 @@ if (app.isNoColor) {
 }
 ```
 
+Screen mode (alt vs inline):
+
+- `screen.mode` selects the terminal presentation: `"alt"` (default,
+  full-screen on the alternate buffer) or `"inline"` (a bounded region of
+  `screen.inlineRows` rows on the primary screen with scrollback preserved
+  above and the final frame left in scrollback on exit).
+- `screen.inlineRows` (1..1024) is required with `"inline"` and rejected
+  otherwise; the effective viewport is clamped to the live terminal height.
+- Unrelated to `executionMode: "inline"` (engine-on-main-thread); the two
+  options compose freely.
+- See the [Screen Modes guide](../guide/screen-modes.md) and
+  `examples/inline-status` for a runnable app.
+
+```ts
+const app = createNodeApp({
+  initialState: {},
+  config: {
+    screen: { mode: "inline", inlineRows: 9 },
+  },
+});
+```
+
 Emoji width policy:
 
 - `emojiWidthPolicy` keeps core text measurement and native rendering aligned.

docs/guide/screen-modes.md

@@ -0,0 +1,90 @@
+# Screen Modes
+
+Rezi apps can present in two terminal screen modes, selected at app creation:
+
+| Mode | Surface | Fits |
+| --- | --- | --- |
+| `"alt"` (default) | Full-screen on the alternate screen buffer | Dashboards, editors, full-screen TUIs |
+| `"inline"` | A bounded region on the primary screen | Status UIs, progress displays, REPLs, agent-style CLIs |
+
+In **alt mode** the app owns the whole terminal and the prior screen is
+restored on exit — the classic full-screen TUI experience.
+
+In **inline mode** the app renders a region of `inlineRows` rows at the
+current scroll position, the way tools like Ink-based CLIs present:
+
+- Terminal **scrollback stays visible above the region** while the app runs.
+- The region scrolls naturally with the session as it claims rows.
+- On exit, the **final frame remains in scrollback** and the shell prompt is
+  restored on a fresh line below it.
+- Repaints use relative cursor motion only — the engine never clears the
+  screen or addresses absolute rows, so content above the app is never
+  touched.
+
+## Enabling inline mode
+
+```ts
+import { createNodeApp } from "@rezi-ui/node";
+
+const app = createNodeApp({
+  initialState: {},
+  config: {
+    screen: { mode: "inline", inlineRows: 9 },
+  },
+});
+```
+
+`screen.inlineRows` (1..1024) is required in inline mode and rejected in alt
+mode. The effective viewport is clamped to the live terminal height and
+re-clamped on terminal resize.
+
+See [`examples/inline-status`](https://github.com/RtlZeroMemory/Rezi/tree/main/examples/inline-status)
+for a complete runnable app (spinner + progress bar + quit keys).
+
+## Layout and sizing
+
+The app's layout viewport in inline mode is `terminal columns x inlineRows`;
+resize events report that viewport, so layout, wrapping, and responsive
+breakpoints work unchanged.
+
+Size `inlineRows` to your content's height. Remember that container chrome
+consumes rows: `ui.panel(...)` adds two border rows plus padding, and stack
+gaps add one row per gap. The `examples/inline-status` panel (one status row,
+a progress bar, and a caption) needs 9 rows.
+
+## Behavior notes
+
+- **Capability fallback**: protocol images (kitty / sixel / iTerm2) require
+  absolute screen coordinates, so inline mode renders `ui.image(...)` through
+  the sub-cell blitter path instead. `ui.canvas(...)` blitters are unaffected.
+  Backend capability snapshots reflect this (`supportsScrollRegion` and image
+  protocol support read as unavailable).
+- **Terminal resize**: the engine re-anchors and repaints the region. As with
+  every inline-style CLI, the terminal's own reflow of *pre-resize scrollback*
+  can leave artifacts above the region; the app's region itself repaints
+  cleanly.
+- **Exiting**: prefer the repo's standard pattern of `await app.run()`
+  followed by `process.exit(0)` when the app holds timers or other live
+  handles (see `examples/gallery`).
+
+## Naming note: `screen.mode` vs `executionMode`
+
+These are independent options that compose freely:
+
+- `screen.mode: "alt" | "inline"` — what the app looks like in the terminal
+  (this page).
+- `executionMode: "auto" | "worker" | "inline"` — where the native engine
+  runs (worker thread vs main thread); see
+  [Worker model](../backend/worker-model.md).
+
+An inline-screen app can run on the worker path, and a full-screen app can
+run on the inline execution path.
+
+## Under the hood
+
+Inline mode is implemented by the Zireael engine (v1.4.0+, engine ABI 1.3.0)
+as a first-class screen mode: relative-motion emission (CR/CUU/CUD/CHA), LF
+row claims that scroll the region as one unit, and a scrollback-safe erase
+baseline. The Node backend forwards `screen` as native config keys
+(`plat.screenMode`, `inlineRows`); raw `nativeConfig` passthrough of those
+keys is also accepted, with the high-level `screen` option taking precedence.

docs/protocol/abi.md

@@ -8,14 +8,18 @@ engine pins.
 | Constant | Value | Notes |
 |---|---:|---|
 | `ZR_ENGINE_ABI_MAJOR` | `1` | Engine ABI major |
-| `ZR_ENGINE_ABI_MINOR` | `2` | Engine ABI minor |
+| `ZR_ENGINE_ABI_MINOR` | `3` | Engine ABI minor |
 | `ZR_ENGINE_ABI_PATCH` | `0` | Engine ABI patch |
 | `ZR_DRAWLIST_VERSION_V1` | `1` | ZRDL v1 |
 | `ZR_EVENT_BATCH_VERSION_V1` | `1` | ZREV v1 |
 | `ZR_UNICODE_VERSION_MAJOR` | `15` | Unicode major |
 | `ZR_UNICODE_VERSION_MINOR` | `1` | Unicode minor |
 | `ZR_UNICODE_VERSION_PATCH` | `0` | Unicode patch |
 
+Engine ABI `1.3.0` (Zireael v1.4.0) added inline screen mode: the
+`plat.screenMode` selector and the `inlineRows` field on the engine create
+and runtime configs. See [Screen Modes](../guide/screen-modes.md).
+
 ## Magic Values
 
 | Constant | Value | Meaning |

examples/inline-status/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "inline-status",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@rezi-ui/core": "0.1.0-beta.1",
+    "@rezi-ui/node": "0.1.0-beta.1"
+  }
+}

examples/inline-status/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Inline screen mode example.
+ *
+ * The app renders a 9-row region on the primary screen instead of the
+ * alternate screen: terminal scrollback stays visible above the region while
+ * the app runs, and the final frame remains in scrollback after exit with
+ * the shell prompt restored below it.
+ *
+ * Run: npx tsx examples/inline-status/src/index.ts
+ */
+import { defineWidget, ui, useInterval } from "@rezi-ui/core";
+import { createNodeApp } from "@rezi-ui/node";
+
+const SPINNER = ["|", "/", "-", "\\"] as const;
+const TICK_MS = 80;
+
+const app = createNodeApp<Record<string, never>>({
+  initialState: {},
+  config: {
+    screen: { mode: "inline", inlineRows: 9 },
+  },
+});
+
+const SyncPanel = defineWidget((_props: Record<string, never>, ctx) => {
+  const [tick, setTick] = ctx.useState(0);
+  const [percent, setPercent] = ctx.useState(0);
+
+  useInterval(
+    ctx,
+    () => {
+      setTick((value) => value + 1);
+      setPercent((value) => Math.min(100, value + 1));
+    },
+    TICK_MS,
+  );
+
+  const done = percent >= 100;
+  const spinner = done ? "*" : SPINNER[tick % SPINNER.length];
+  return ui.panel("Sync", [
+    ui.row({ gap: 1 }, [
+      ui.text(`${spinner} ${done ? "All chunks synced" : "Syncing chunks..."}`),
+      ui.spacer({ flex: 1 }),
+      ui.text(`${String(percent)}%`, { variant: "label" }),
+    ]),
+    ui.progress(percent / 100),
+    ui.text("scrollback stays above - press q to quit (frame stays visible)", {
+      variant: "caption",
+    }),
+  ]);
+});
+
+app.view(() => SyncPanel({}));
+
+app.keys({
+  q: () => void app.stop(),
+  escape: () => void app.stop(),
+  "ctrl+c": () => void app.stop(),
+});
+
+await app.run();
+process.exit(0);

examples/inline-status/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "lib": ["ES2022"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../../packages/core" }, { "path": "../../packages/node" }]
+}

mkdocs.yml

@@ -113,6 +113,7 @@ nav:
       - Animation: guide/animation.md
       - Runtime & Layout: guide/runtime-and-layout.md
       - Lifecycle & Updates: guide/lifecycle-and-updates.md
+      - Screen Modes: guide/screen-modes.md
       - Error Handling: guide/error-handling.md
       - Routing: guide/routing.md
       - Layout: guide/layout.md