@rezi-ui/node 0.1.0-alpha.3 → 0.1.0-alpha.31

package/README.md

@@ -1,17 +1,37 @@
 # @rezi-ui/node
 
-Node.js backend for Rezi. This package owns:
+Node.js/Bun backend for Rezi. This package owns:
 
-- worker-thread engine ownership (native engine is never called on the main thread)
+- configurable native engine execution mode (`auto` | `worker` | `inline`)
 - frame scheduling and buffer pooling
 - transfer of drawlists/events between core and the native addon
 
-Typical usage:
+Recommended usage:
 
 ```ts
-import { createApp, ui } from "@rezi-ui/core";
-import { createNodeBackend } from "@rezi-ui/node";
+import { createNodeApp } from "@rezi-ui/node";
 ```
 
-Docs: `https://rtlzeromemory.github.io/Rezi/`
+Use `createNodeApp({ initialState, config })` as the default path. It wires
+`@rezi-ui/core` and `@rezi-ui/node` with matched cursor protocol, event caps,
+and fps settings. `executionMode` defaults to `auto` (`fpsCap <= 30` -> inline,
+otherwise worker); set `executionMode: "worker"` or `"inline"` to force a mode.
 
+For development-time hot swapping, pass `hotReload` to `createNodeApp(...)`:
+- `viewModule` for widget-view apps
+- `routesModule` for route-managed apps
+
+`app.hotReload` exposes the controller for optional manual `reloadNow()` calls.
+
+`createNodeBackend()` is available when you need direct access to a backend
+instance (benchmarks/custom runners). Most apps should use `createNodeApp()`.
+
+Install:
+
+```bash
+npm i @rezi-ui/node
+# or
+bun add @rezi-ui/node
+```
+
+Docs: `https://rezitui.dev/docs`

package/dist/backend/emojiWidthPolicy.d.ts

@@ -0,0 +1,15 @@
+export type BackendEmojiWidthPolicy = "auto" | "wide" | "narrow";
+export type ResolvedEmojiWidthPolicy = "wide" | "narrow";
+/**
+ * Resolve backend emoji width policy and align core/native width models.
+ *
+ * Resolution order:
+ * 1) explicit `requested` ("wide"/"narrow")
+ * 2) explicit native override (`nativeConfig.widthPolicy|width_policy`)
+ * 3) env override (`ZRUI_EMOJI_WIDTH_POLICY`)
+ * 4) optional probe (CPR-based) when `ZRUI_EMOJI_WIDTH_PROBE=1`
+ * 5) deterministic default ("wide")
+ */
+export declare function resolveBackendEmojiWidthPolicy(requested: BackendEmojiWidthPolicy | undefined, nativeConfig: Readonly<Record<string, unknown>>): Promise<ResolvedEmojiWidthPolicy>;
+export declare function applyEmojiWidthPolicy(policy: ResolvedEmojiWidthPolicy): 0 | 1;
+//# sourceMappingURL=emojiWidthPolicy.d.ts.map

package/dist/backend/emojiWidthPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emojiWidthPolicy.d.ts","sourceRoot":"","sources":["../../src/backend/emojiWidthPolicy.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AACjE,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAoMzD;;;;;;;;;GASG;AACH,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,uBAAuB,GAAG,SAAS,EAC9C,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,OAAO,CAAC,wBAAwB,CAAC,CA8BnC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,GAAG,CAAC,GAAG,CAAC,CAG7E"}

package/dist/backend/emojiWidthPolicy.js

@@ -0,0 +1,229 @@
+import { ZrUiError, setTextMeasureEmojiPolicy } from "@rezi-ui/core";
+const NATIVE_WIDTH_POLICY_NARROW = 0;
+const NATIVE_WIDTH_POLICY_WIDE = 1;
+const PROBE_TIMEOUT_MS_DEFAULT = 80;
+const PROBE_GLYPHS = Object.freeze(["😀", "🚀", "🧪"]);
+const ENV_EMOJI_WIDTH_POLICY = "ZRUI_EMOJI_WIDTH_POLICY";
+const ENV_EMOJI_WIDTH_PROBE = "ZRUI_EMOJI_WIDTH_PROBE";
+let cachedProbePolicy = null;
+let cachedProbePromise = null;
+function normalizePolicy(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const value = raw.trim().toLowerCase();
+    if (value === "auto")
+        return "auto";
+    if (value === "wide")
+        return "wide";
+    if (value === "narrow")
+        return "narrow";
+    return null;
+}
+function nativeWidthPolicyToResolved(value) {
+    return value === NATIVE_WIDTH_POLICY_NARROW ? "narrow" : "wide";
+}
+function resolvedToNativeWidthPolicy(value) {
+    return value === "narrow" ? NATIVE_WIDTH_POLICY_NARROW : NATIVE_WIDTH_POLICY_WIDE;
+}
+function readNativeWidthPolicyValues(cfg) {
+    const parse = (value, key) => {
+        if (value === undefined)
+            return null;
+        if (typeof value !== "number" || !Number.isInteger(value) || (value !== 0 && value !== 1)) {
+            throw new ZrUiError("ZRUI_INVALID_PROPS", `createNodeBackend config mismatch: nativeConfig.${key} must be 0 (narrow) or 1 (wide).`);
+        }
+        return value;
+    };
+    const record = cfg;
+    return {
+        camel: parse(record.widthPolicy, "widthPolicy"),
+        snake: parse(record.width_policy, "width_policy"),
+    };
+}
+function readNativeWidthPolicyOverride(cfg) {
+    const values = readNativeWidthPolicyValues(cfg);
+    if (values.camel !== null && values.snake !== null && values.camel !== values.snake) {
+        throw new ZrUiError("ZRUI_INVALID_PROPS", `createNodeBackend config mismatch: nativeConfig.widthPolicy=${String(values.camel)} must match nativeConfig.width_policy=${String(values.snake)}.`);
+    }
+    const nativeValue = values.camel ?? values.snake;
+    if (nativeValue === null)
+        return null;
+    return nativeWidthPolicyToResolved(nativeValue);
+}
+function pushParsedCpr(buffer, out) {
+    let pending = buffer;
+    while (pending.length > 0) {
+        const esc = pending.indexOf("\x1b[");
+        if (esc < 0) {
+            if (pending.length > 128)
+                pending = pending.slice(-128);
+            break;
+        }
+        if (esc > 0) {
+            pending = pending.slice(esc);
+        }
+        const end = pending.indexOf("R", 2);
+        if (end < 0)
+            break;
+        const seq = pending.slice(0, end + 1);
+        pending = pending.slice(end + 1);
+        const body = seq.slice(2, seq.length - 1);
+        const sep = body.indexOf(";");
+        if (sep <= 0 || sep >= body.length - 1)
+            continue;
+        const rowText = body.slice(0, sep);
+        const colText = body.slice(sep + 1);
+        if (!/^\d+$/.test(rowText) || !/^\d+$/.test(colText))
+            continue;
+        const row = Number.parseInt(rowText, 10);
+        const col = Number.parseInt(colText, 10);
+        if (Number.isFinite(row) && Number.isFinite(col)) {
+            out.push({ row, col });
+        }
+    }
+    return pending;
+}
+async function probeGlyphWidthViaCpr(glyph, timeoutMs) {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY)
+        return null;
+    if (typeof stdin.setRawMode !== "function")
+        return null;
+    const wasRaw = stdin.isRaw === true;
+    let pending = "";
+    const cprs = [];
+    const onData = (chunk) => {
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        pending = pushParsedCpr(pending + text, cprs);
+    };
+    let timeout = null;
+    try {
+        stdin.on("data", onData);
+        stdin.resume();
+        if (!wasRaw)
+            stdin.setRawMode(true);
+        // Save cursor, move to a stable column, query CPR, print glyph, query CPR again, restore cursor.
+        await new Promise((resolve, reject) => {
+            stdout.write(`\x1b[s\x1b[999;1H\x1b[6n${glyph}\x1b[6n\x1b[u`, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+        await new Promise((resolve) => {
+            const done = () => {
+                if (timeout)
+                    clearTimeout(timeout);
+                timeout = null;
+                resolve();
+            };
+            timeout = setTimeout(done, timeoutMs);
+            const poll = () => {
+                if (cprs.length >= 2) {
+                    done();
+                    return;
+                }
+                setTimeout(poll, 2);
+            };
+            poll();
+        });
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+        stdin.off("data", onData);
+        if (!wasRaw) {
+            try {
+                stdin.setRawMode(false);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    const a = cprs[0];
+    const b = cprs[1];
+    if (!a || !b)
+        return null;
+    if (b.row !== a.row)
+        return null;
+    const delta = b.col - a.col;
+    if (delta === 1 || delta === 2)
+        return delta;
+    return null;
+}
+async function probeTerminalEmojiWidthPolicy(timeoutMs) {
+    const widths = [];
+    for (const glyph of PROBE_GLYPHS) {
+        const width = await probeGlyphWidthViaCpr(glyph, timeoutMs);
+        if (width !== null)
+            widths.push(width);
+    }
+    if (widths.length === 0)
+        return null;
+    if (widths.includes(1))
+        return "narrow";
+    return "wide";
+}
+async function probeTerminalEmojiWidthPolicyCached(timeoutMs) {
+    if (cachedProbePolicy !== null)
+        return cachedProbePolicy;
+    if (cachedProbePromise)
+        return cachedProbePromise;
+    cachedProbePromise = probeTerminalEmojiWidthPolicy(timeoutMs)
+        .then((probed) => {
+        if (probed !== null)
+            cachedProbePolicy = probed;
+        return probed;
+    })
+        .finally(() => {
+        cachedProbePromise = null;
+    });
+    return cachedProbePromise;
+}
+/**
+ * Resolve backend emoji width policy and align core/native width models.
+ *
+ * Resolution order:
+ * 1) explicit `requested` ("wide"/"narrow")
+ * 2) explicit native override (`nativeConfig.widthPolicy|width_policy`)
+ * 3) env override (`ZRUI_EMOJI_WIDTH_POLICY`)
+ * 4) optional probe (CPR-based) when `ZRUI_EMOJI_WIDTH_PROBE=1`
+ * 5) deterministic default ("wide")
+ */
+export async function resolveBackendEmojiWidthPolicy(requested, nativeConfig) {
+    const requestedPolicy = requested ?? "auto";
+    const nativeOverride = readNativeWidthPolicyOverride(nativeConfig);
+    if (requestedPolicy === "narrow" || requestedPolicy === "wide") {
+        if (nativeOverride !== null && nativeOverride !== requestedPolicy) {
+            throw new ZrUiError("ZRUI_INVALID_PROPS", `createNodeBackend config mismatch: emojiWidthPolicy=${requestedPolicy} must match nativeConfig.widthPolicy/width_policy=${nativeOverride === "narrow" ? 0 : 1}.`);
+        }
+        return requestedPolicy;
+    }
+    if (nativeOverride !== null)
+        return nativeOverride;
+    const envOverride = normalizePolicy(process.env[ENV_EMOJI_WIDTH_POLICY]);
+    if (envOverride === "wide" || envOverride === "narrow")
+        return envOverride;
+    /*
+      CPR probing is opt-in because it temporarily consumes stdin bytes while
+      collecting CPR responses, which can race startup-time key streams.
+    */
+    const probeEnabled = process.env[ENV_EMOJI_WIDTH_PROBE] === "1";
+    if (probeEnabled) {
+        const probed = await probeTerminalEmojiWidthPolicyCached(PROBE_TIMEOUT_MS_DEFAULT);
+        if (probed !== null)
+            return probed;
+    }
+    return "wide";
+}
+export function applyEmojiWidthPolicy(policy) {
+    setTextMeasureEmojiPolicy(policy);
+    return resolvedToNativeWidthPolicy(policy);
+}
+//# sourceMappingURL=emojiWidthPolicy.js.map

package/dist/backend/emojiWidthPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emojiWidthPolicy.js","sourceRoot":"","sources":["../../src/backend/emojiWidthPolicy.ts"],"names":[],"mappings":"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"}

package/dist/backend/nodeBackend.d.ts

@@ -15,10 +15,28 @@ export type NodeBackendConfig = Readonly<{
      * - "inline": single-thread inline backend (no worker-hop transport)
      */
     executionMode?: "auto" | "worker" | "inline";
+    /**
+     * @deprecated Prefer createNodeApp({ config: { fpsCap } }) so app/core and backend
+     * remain aligned by construction.
+     */
     fpsCap?: number;
+    /**
+     * @deprecated Prefer createNodeApp({ config: { maxEventBytes } }) so app/core and backend
+     * remain aligned by construction.
+     */
     maxEventBytes?: number;
-    /** Request drawlist v2 for native cursor support (default: false for compatibility) */
+    /**
+     * Request drawlist v2 for native cursor support (default: false for compatibility).
+     * @deprecated Prefer createNodeApp({ config: { useV2Cursor: true } }).
+     */
     useDrawlistV2?: boolean;
+    /**
+     * Explicit drawlist version request.
+     *
+     * Defaults to `5` (enables v3 style extensions + v4 canvas + v5 image commands).
+     * Set to `1`/`2` only for legacy protocol compatibility testing.
+     */
+    drawlistVersion?: 1 | 2 | 3 | 4 | 5;
     /**
      * Frame transport mode:
      * - "auto": prefer SAB mailbox transport when available, fallback to transfer.
@@ -35,6 +53,16 @@ export type NodeBackendConfig = Readonly<{
      * Keys are forwarded as-is (camelCase or snake_case accepted by the native parser).
      */
     nativeConfig?: Readonly<Record<string, unknown>>;
+    /**
+     * Emoji width policy used to keep core layout measurement and native rendering aligned.
+     * - "auto": use native/env overrides; optional probe when `ZRUI_EMOJI_WIDTH_PROBE=1`
+     *   then fallback to deterministic "wide"
+     * - "wide": emoji clusters consume 2 cells
+     * - "narrow": emoji clusters consume 1 cell
+     *
+     * This sets core text measurement policy and native `widthPolicy` together.
+     */
+    emojiWidthPolicy?: "auto" | "wide" | "narrow";
 }>;
 export type NodeBackendInternalOpts = Readonly<{
     config?: NodeBackendConfig;

package/dist/backend/nodeBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodeBackend.d.ts","sourceRoot":"","sources":["../../src/backend/nodeBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAEV,YAAY,EAKZ,cAAc,EAEf,MAAM,eAAe,CAAC;AAkCvB,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IAC7C,2CAA2C;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,EAAE,QAAQ,CACd,MAAM,CACJ,MAAM,EACN;QACE,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KAC5B,CACF,CACF,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAAC;AAwKpG,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,uBAA4B,GAAG,WAAW,CAq3BzF"}
+{"version":3,"file":"nodeBackend.d.ts","sourceRoot":"","sources":["../../src/backend/nodeBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAGV,YAAY,EAKZ,cAAc,EAGf,MAAM,eAAe,CAAC;AA6CvB,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IAC7C,2CAA2C;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CAC/C,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,EAAE,QAAQ,CACd,MAAM,CACJ,MAAM,EACN;QACE,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KAC5B,CACF,CACF,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAAC;AA4RpG,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,uBAA4B,GAAG,WAAW,CAy+BzF"}

package/dist/backend/nodeBackend.js

@@ -7,10 +7,26 @@
  * @see docs/backend/native.md
  */
 import { Worker } from "node:worker_threads";
-import { DEFAULT_TERMINAL_CAPS, FRAME_ACCEPTED_ACK_MARKER } from "@rezi-ui/core";
-import { ZR_DRAWLIST_VERSION_V1, ZR_DRAWLIST_VERSION_V2, ZR_ENGINE_ABI_MAJOR, ZR_ENGINE_ABI_MINOR, ZR_ENGINE_ABI_PATCH, ZR_EVENT_BATCH_VERSION_V1, ZrUiError, severityToNum, } from "@rezi-ui/core";
+import { BACKEND_DRAWLIST_V2_MARKER, BACKEND_DRAWLIST_VERSION_MARKER, BACKEND_FPS_CAP_MARKER, BACKEND_MAX_EVENT_BYTES_MARKER, BACKEND_RAW_WRITE_MARKER, DEFAULT_TERMINAL_CAPS, FRAME_ACCEPTED_ACK_MARKER, } from "@rezi-ui/core";
+import { ZR_DRAWLIST_VERSION_V2, ZR_DRAWLIST_VERSION_V5, ZR_ENGINE_ABI_MAJOR, ZR_ENGINE_ABI_MINOR, ZR_ENGINE_ABI_PATCH, ZR_EVENT_BATCH_VERSION_V1, ZrUiError, setTextMeasureEmojiPolicy, severityToNum, } from "@rezi-ui/core";
 import { FRAME_SAB_CONTROL_CONSUMED_SEQ_WORD, FRAME_SAB_CONTROL_HEADER_WORDS, FRAME_SAB_CONTROL_PUBLISHED_BYTES_WORD, FRAME_SAB_CONTROL_PUBLISHED_SEQ_WORD, FRAME_SAB_CONTROL_PUBLISHED_SLOT_WORD, FRAME_SAB_CONTROL_PUBLISHED_TOKEN_WORD, FRAME_SAB_CONTROL_WORDS_PER_SLOT, FRAME_SAB_SLOT_STATE_FREE, FRAME_SAB_SLOT_STATE_READY, FRAME_SAB_SLOT_STATE_WRITING, FRAME_TRANSPORT_SAB_V1, FRAME_TRANSPORT_TRANSFER_V1, FRAME_TRANSPORT_VERSION, } from "../worker/protocol.js";
+import { applyEmojiWidthPolicy, resolveBackendEmojiWidthPolicy } from "./emojiWidthPolicy.js";
 import { createNodeBackendInlineInternal } from "./nodeBackendInline.js";
+import { terminalProfileFromNodeEnv } from "./terminalProfile.js";
+const WIDTH_POLICY_KEY = "widthPolicy";
+const DEFAULT_NATIVE_LIMITS = Object.freeze({
+    // Align native validation caps with JS drawlist builder defaults.
+    //
+    // Native defaults are intentionally conservative; however, @rezi-ui/core's
+    // drawlist builders default to 2 MiB max drawlist bytes and large command
+    // budgets. Without overriding, moderately large frames (e.g. images/canvas)
+    // can fail with ZR_ERR_LIMIT (-3) at submit time.
+    outMaxBytesPerFrame: 2 * 1024 * 1024,
+    dlMaxTotalBytes: 2 * 1024 * 1024,
+    dlMaxCmds: 100_000,
+    dlMaxStrings: 10_000,
+    dlMaxBlobs: 10_000,
+});
 function deferred() {
     let resolve;
     let reject;
@@ -20,6 +36,28 @@ function deferred() {
     });
     return { promise, resolve, reject };
 }
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function mergeNativeLimits(nativeConfig) {
+    // biome-ignore lint/complexity/useLiteralKeys: bracket access is required by noPropertyAccessFromIndexSignature.
+    const limitsValue = nativeConfig["limits"];
+    const existingLimits = isPlainObject(limitsValue)
+        ? limitsValue
+        : null;
+    const limits = { ...(existingLimits ?? {}) };
+    const has = (camel) => {
+        const snake = camel.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`);
+        return (Object.prototype.hasOwnProperty.call(limits, camel) ||
+            Object.prototype.hasOwnProperty.call(limits, snake));
+    };
+    for (const [camel, value] of Object.entries(DEFAULT_NATIVE_LIMITS)) {
+        if (has(camel))
+            continue;
+        limits[camel] = value;
+    }
+    return Object.freeze({ ...nativeConfig, limits: Object.freeze(limits) });
+}
 function parsePositiveIntOr(n, fallback) {
     if (typeof n !== "number")
         return fallback;
@@ -42,9 +80,53 @@ function parsePositiveInt(n) {
         return null;
     return n;
 }
-function readNativeTargetFps(cfg) {
+function parseDrawlistVersion(v) {
+    if (v === undefined)
+        return null;
+    if (v === 1 || v === 2 || v === 3 || v === 4 || v === 5)
+        return v;
+    throw new ZrUiError("ZRUI_INVALID_PROPS", `createNodeBackend config mismatch: drawlistVersion must be one of 1, 2, 3, 4, 5 (got ${String(v)}).`);
+}
+function resolveRequestedDrawlistVersion(config) {
+    const explicitDrawlistVersion = parseDrawlistVersion(config.drawlistVersion);
+    const useDrawlistV2 = config.useDrawlistV2 === true;
+    if (explicitDrawlistVersion !== null) {
+        if (useDrawlistV2 && explicitDrawlistVersion < ZR_DRAWLIST_VERSION_V2) {
+            throw new ZrUiError("ZRUI_INVALID_PROPS", "createNodeBackend config mismatch: useDrawlistV2=true requires drawlistVersion >= 2.");
+        }
+        return explicitDrawlistVersion;
+    }
+    return useDrawlistV2 ? ZR_DRAWLIST_VERSION_V2 : ZR_DRAWLIST_VERSION_V5;
+}
+function parseBoundedPositiveIntOrThrow(name, value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    const parsed = parsePositiveInt(value);
+    if (parsed === null) {
+        throw new ZrUiError("ZRUI_INVALID_PROPS", `${name} must be a positive integer`);
+    }
+    if (parsed > max) {
+        throw new ZrUiError("ZRUI_INVALID_PROPS", `${name} must be <= ${String(max)}`);
+    }
+    return parsed;
+}
+function readNativeTargetFpsValues(cfg) {
     const targetFpsCfg = cfg;
-    return parsePositiveInt(targetFpsCfg.targetFps) ?? parsePositiveInt(targetFpsCfg.target_fps);
+    return {
+        camel: parsePositiveInt(targetFpsCfg.targetFps),
+        snake: parsePositiveInt(targetFpsCfg.target_fps),
+    };
+}
+function resolveTargetFps(fpsCap, nativeConfig) {
+    const values = readNativeTargetFpsValues(nativeConfig);
+    if (values.camel !== null && values.snake !== null && values.camel !== values.snake) {
+        throw new ZrUiError("ZRUI_INVALID_PROPS", `createNodeBackend config mismatch: nativeConfig.targetFps=${String(values.camel)} must match nativeConfig.target_fps=${String(values.snake)}.`);
+    }
+    const nativeTargetFps = values.camel ?? values.snake;
+    if (nativeTargetFps !== null && nativeTargetFps !== fpsCap) {
+        throw new ZrUiError("ZRUI_INVALID_PROPS", `createNodeBackend config mismatch: fpsCap=${String(fpsCap)} must match nativeConfig.targetFps/target_fps=${String(nativeTargetFps)}. Fix: set nativeConfig.targetFps (or target_fps) to ${String(fpsCap)}, or remove the override and use fpsCap only.`);
+    }
+    return fpsCap;
 }
 function safeErr(err) {
     return err instanceof Error ? err : new Error(String(err));
@@ -53,6 +135,10 @@ const DEBUG_QUERY_DEFAULT_RECORDS = 4096;
 const DEBUG_QUERY_MAX_RECORDS = 16384;
 const FRAME_SAB_SLOT_COUNT_DEFAULT = 8;
 const FRAME_SAB_SLOT_BYTES_DEFAULT = 1 << 20;
+const DEFAULT_FPS_CAP = 60;
+const MAX_SAFE_FPS_CAP = 1000;
+const DEFAULT_MAX_EVENT_BYTES = 1 << 20;
+const MAX_SAFE_EVENT_BYTES = 4 << 20;
 function copyInto(buf, bytes) {
     new Uint8Array(buf, 0, bytes.byteLength).set(bytes);
 }
@@ -132,7 +218,7 @@ function publishSabFrame(t, frameSeq, slotIndex, slotToken, byteLen) {
 }
 export function createNodeBackendInternal(opts = {}) {
     const cfg = opts.config ?? {};
-    const fpsCap = parsePositiveIntOr(cfg.fpsCap, 60);
+    const fpsCap = parseBoundedPositiveIntOrThrow("fpsCap", cfg.fpsCap, DEFAULT_FPS_CAP, MAX_SAFE_FPS_CAP);
     const requestedExecutionMode = cfg.executionMode ?? "auto";
     const executionMode = requestedExecutionMode === "inline"
         ? "inline"
@@ -144,8 +230,8 @@ export function createNodeBackendInternal(opts = {}) {
     if (executionMode === "inline") {
         return createNodeBackendInlineInternal(opts);
     }
-    const maxEventBytes = parsePositiveIntOr(cfg.maxEventBytes, 1 << 20);
-    const useDrawlistV2 = cfg.useDrawlistV2 === true;
+    const requestedDrawlistVersion = resolveRequestedDrawlistVersion(cfg);
+    const maxEventBytes = parseBoundedPositiveIntOrThrow("maxEventBytes", cfg.maxEventBytes, DEFAULT_MAX_EVENT_BYTES, MAX_SAFE_EVENT_BYTES);
     const frameTransportMode = cfg.frameTransport === "transfer" || cfg.frameTransport === "sab" ? cfg.frameTransport : "auto";
     const frameSabSlotCount = parsePositiveIntOr(cfg.frameSabSlotCount, FRAME_SAB_SLOT_COUNT_DEFAULT);
     const frameSabSlotBytes = parsePositiveIntOr(cfg.frameSabSlotBytes, FRAME_SAB_SLOT_BYTES_DEFAULT);
@@ -168,25 +254,25 @@ export function createNodeBackendInternal(opts = {}) {
     const nativeConfig = typeof cfg.nativeConfig === "object" &&
         cfg.nativeConfig !== null &&
         !Array.isArray(cfg.nativeConfig)
-        ? cfg.nativeConfig
-        : Object.freeze({});
-    const nativeTargetFps = readNativeTargetFps(nativeConfig) ?? fpsCap;
-    const initConfig = {
+        ? mergeNativeLimits(cfg.nativeConfig)
+        : mergeNativeLimits(Object.freeze({}));
+    const nativeTargetFps = resolveTargetFps(fpsCap, nativeConfig);
+    const initConfigBase = {
         ...nativeConfig,
-        // Keep native tick generation aligned with app/backend fpsCap unless
-        // explicitly overridden in nativeConfig.
+        // fpsCap is the single frame-scheduling knob; native target fps must align.
         targetFps: nativeTargetFps,
         // Negotiation pins (docs/16 + docs/01)
         requestedEngineAbiMajor: ZR_ENGINE_ABI_MAJOR,
         requestedEngineAbiMinor: ZR_ENGINE_ABI_MINOR,
         requestedEngineAbiPatch: ZR_ENGINE_ABI_PATCH,
-        requestedDrawlistVersion: useDrawlistV2 ? ZR_DRAWLIST_VERSION_V2 : ZR_DRAWLIST_VERSION_V1,
+        requestedDrawlistVersion: requestedDrawlistVersion,
         requestedEventBatchVersion: ZR_EVENT_BATCH_VERSION_V1,
         // Node worker runtime caps
         fpsCap,
         maxEventBytes,
         frameTransport: frameTransportWire,
     };
+    let initConfigResolved = null;
     let worker = null;
     let disposed = false;
     let started = false;
@@ -369,6 +455,26 @@ export function createNodeBackendInternal(opts = {}) {
                 return;
             }
             case "events": {
+                if (!Number.isInteger(msg.byteLen) || msg.byteLen < 0) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: invalid byteLen=${String(msg.byteLen)}`);
+                    failAll(fatal);
+                    return;
+                }
+                if (msg.byteLen > msg.batch.byteLength) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: byteLen=${String(msg.byteLen)} exceeds batch.byteLength=${String(msg.batch.byteLength)}`);
+                    failAll(fatal);
+                    return;
+                }
+                if (msg.byteLen > maxEventBytes) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: byteLen=${String(msg.byteLen)} exceeds maxEventBytes=${String(maxEventBytes)}`);
+                    failAll(fatal);
+                    return;
+                }
+                if (!Number.isInteger(msg.droppedSinceLast) || msg.droppedSinceLast < 0) {
+                    fatal = new ZrUiError("ZRUI_BACKEND_ERROR", `events: invalid droppedSinceLast=${String(msg.droppedSinceLast)}`);
+                    failAll(fatal);
+                    return;
+                }
                 const waiter = eventWaiters.shift();
                 if (waiter !== undefined) {
                     const buf = msg.batch;
@@ -526,6 +632,9 @@ export function createNodeBackendInternal(opts = {}) {
                     supportsScrollRegion: msg.supportsScrollRegion,
                     supportsCursorShape: msg.supportsCursorShape,
                     supportsOutputWaitWritable: msg.supportsOutputWaitWritable,
+                    supportsUnderlineStyles: msg.supportsUnderlineStyles,
+                    supportsColoredUnderlines: msg.supportsColoredUnderlines,
+                    supportsHyperlinks: msg.supportsHyperlinks,
                     sgrAttrsSupported: msg.sgrAttrsSupported,
                 };
                 cachedCaps = caps;
@@ -569,6 +678,21 @@ export function createNodeBackendInternal(opts = {}) {
             if (started)
                 return;
             if (worker === null) {
+                if (initConfigResolved === null) {
+                    const resolvedEmojiWidthPolicy = await resolveBackendEmojiWidthPolicy(cfg.emojiWidthPolicy, nativeConfig);
+                    const nativeWidthPolicy = applyEmojiWidthPolicy(resolvedEmojiWidthPolicy);
+                    initConfigResolved = {
+                        ...initConfigBase,
+                        widthPolicy: nativeWidthPolicy,
+                    };
+                }
+                else {
+                    // Keep core measurement policy deterministic across stop/start cycles.
+                    const widthPolicy = initConfigResolved[WIDTH_POLICY_KEY];
+                    if (typeof widthPolicy === "number") {
+                        setTextMeasureEmojiPolicy(widthPolicy === 0 ? "narrow" : "wide");
+                    }
+                }
                 startDef = deferred();
                 startSettled = false;
                 stopDef = null;
@@ -592,7 +716,7 @@ export function createNodeBackendInternal(opts = {}) {
                 worker.on("exit", (code) => {
                     handleWorkerExit(code);
                 });
-                send({ type: "init", config: initConfig });
+                send({ type: "init", config: initConfigResolved });
             }
             if (startDef === null)
                 throw new Error("NodeBackend: invariant violated (startDef is null)");
@@ -763,6 +887,10 @@ export function createNodeBackendInternal(opts = {}) {
             send({ type: "getCaps" });
             return d.promise;
         },
+        async getTerminalProfile() {
+            const caps = await backend.getCaps();
+            return terminalProfileFromNodeEnv(caps);
+        },
     };
     const debug = {
         debugEnable: (config) => enqueueDebug(async () => {
@@ -937,6 +1065,48 @@ export function createNodeBackendInternal(opts = {}) {
             return snapshot;
         }),
     };
-    return Object.assign(backend, { debug, perf });
+    const out = Object.assign(backend, { debug, perf });
+    Object.defineProperties(out, {
+        [BACKEND_DRAWLIST_V2_MARKER]: {
+            value: requestedDrawlistVersion >= ZR_DRAWLIST_VERSION_V2,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        [BACKEND_DRAWLIST_VERSION_MARKER]: {
+            value: requestedDrawlistVersion,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        [BACKEND_MAX_EVENT_BYTES_MARKER]: {
+            value: maxEventBytes,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        [BACKEND_FPS_CAP_MARKER]: {
+            value: fpsCap,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        [BACKEND_RAW_WRITE_MARKER]: {
+            value: ((text) => {
+                if (typeof text !== "string" || text.length === 0)
+                    return;
+                try {
+                    process.stdout.write(text);
+                }
+                catch {
+                    // Preserve backend determinism: clipboard write failures are non-fatal.
+                }
+            }),
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+    });
+    return out;
 }
 //# sourceMappingURL=nodeBackend.js.map