@slowclap/rezi-core 0.1.0-fork.1

package/dist/cursor/cursorState.js

@@ -0,0 +1,82 @@
+/**
+ * packages/core/src/cursor/cursorState.ts — Framework-level cursor state management.
+ *
+ * Why: Provides a unified cursor state API that widgets can drive. The cursor
+ * state is resolved per-frame and emitted as a SET_CURSOR command in v2 drawlists.
+ * When v2 is enabled, the engine displays the cursor natively, eliminating the
+ * need for "fake cursor" glyphs.
+ *
+ * Resolution policy:
+ *   - Single desired cursor state per frame
+ *   - Last writer wins (widgets called later in render override earlier ones)
+ *   - Focused input widgets automatically request cursor at their position
+ *   - Explicit hide() clears the cursor regardless of prior requests
+ *
+ * @see docs/protocol/abi.md
+ */
+/**
+ * Create a new cursor state collector.
+ *
+ * @param defaultShape - Default cursor shape if not specified (default: block)
+ * @param defaultBlink - Default blink state (default: true)
+ */
+export function createCursorStateCollector(defaultShape = 0, defaultBlink = true) {
+    let lastRequest = null;
+    return {
+        request(req) {
+            lastRequest = req;
+        },
+        resolve() {
+            if (lastRequest === null) {
+                // No cursor requests this frame
+                return null;
+            }
+            if (lastRequest.kind === "hide") {
+                return {
+                    x: -1,
+                    y: -1,
+                    shape: defaultShape,
+                    visible: false,
+                    blink: false,
+                };
+            }
+            return {
+                x: lastRequest.x,
+                y: lastRequest.y,
+                shape: lastRequest.shape,
+                visible: true,
+                blink: lastRequest.blink,
+            };
+        },
+        reset() {
+            lastRequest = null;
+        },
+    };
+}
+/**
+ * Compute cursor position for a text input widget.
+ *
+ * @param inputX - X position of the input field
+ * @param inputY - Y position of the input field
+ * @param cursorOffset - Character offset of cursor within the input value
+ * @param prefix - Optional prefix before the editable area (e.g., label)
+ * @returns Cursor position in screen coordinates
+ */
+export function computeInputCursorPosition(inputX, inputY, cursorOffset, prefix = 0) {
+    return {
+        x: inputX + prefix + cursorOffset,
+        y: inputY,
+    };
+}
+/**
+ * Default cursor shapes for different contexts.
+ */
+export const CURSOR_DEFAULTS = Object.freeze({
+    /** Input field cursor (blinking bar) */
+    input: { shape: 2, blink: true },
+    /** Selection cursor (blinking block) */
+    selection: { shape: 0, blink: true },
+    /** Static cursor (non-blinking underline) */
+    staticUnderline: { shape: 1, blink: false },
+});
+//# sourceMappingURL=cursorState.js.map

package/dist/cursor/cursorState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursorState.js","sourceRoot":"","sources":["../../src/cursor/cursorState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuCH;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,eAA4B,CAAC,EAC7B,YAAY,GAAG,IAAI;IAEnB,IAAI,WAAW,GAAyB,IAAI,CAAC;IAE7C,OAAO;QACL,OAAO,CAAC,GAAkB;YACxB,WAAW,GAAG,GAAG,CAAC;QACpB,CAAC;QAED,OAAO;YACL,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;gBACzB,gCAAgC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC;YAED,IAAI,WAAW,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAChC,OAAO;oBACL,CAAC,EAAE,CAAC,CAAC;oBACL,CAAC,EAAE,CAAC,CAAC;oBACL,KAAK,EAAE,YAAY;oBACnB,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,KAAK;iBACb,CAAC;YACJ,CAAC;YAED,OAAO;gBACL,CAAC,EAAE,WAAW,CAAC,CAAC;gBAChB,CAAC,EAAE,WAAW,CAAC,CAAC;gBAChB,KAAK,EAAE,WAAW,CAAC,KAAK;gBACxB,OAAO,EAAE,IAAI;gBACb,KAAK,EAAE,WAAW,CAAC,KAAK;aACzB,CAAC;QACJ,CAAC;QAED,KAAK;YACH,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAc,EACd,MAAc,EACd,YAAoB,EACpB,MAAM,GAAG,CAAC;IAEV,OAAO;QACL,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY;QACjC,CAAC,EAAE,MAAM;KACV,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C,wCAAwC;IACxC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAgB,EAAE,KAAK,EAAE,IAAI,EAAE;IAC/C,wCAAwC;IACxC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAgB,EAAE,KAAK,EAAE,IAAI,EAAE;IACnD,6CAA6C;IAC7C,eAAe,EAAE,EAAE,KAAK,EAAE,CAAgB,EAAE,KAAK,EAAE,KAAK,EAAE;CAC3D,CAAC,CAAC"}

package/dist/cursor/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * packages/core/src/cursor/index.ts — Cursor state module public API.
+ *
+ * Why: Re-exports cursor state management types and utilities for external use.
+ *
+ * @see docs/protocol/abi.md
+ */
+export { createCursorStateCollector, computeInputCursorPosition, CURSOR_DEFAULTS, type CursorRequest, type CursorStateCollector, } from "./cursorState.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cursor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cursor/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC"}

package/dist/cursor/index.js

@@ -0,0 +1,9 @@
+/**
+ * packages/core/src/cursor/index.ts — Cursor state module public API.
+ *
+ * Why: Re-exports cursor state management types and utilities for external use.
+ *
+ * @see docs/protocol/abi.md
+ */
+export { createCursorStateCollector, computeInputCursorPosition, CURSOR_DEFAULTS, } from "./cursorState.js";
+//# sourceMappingURL=index.js.map

package/dist/cursor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cursor/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,eAAe,GAGhB,MAAM,kBAAkB,CAAC"}

package/dist/debug/constants.d.ts

@@ -0,0 +1,100 @@
+/**
+ * packages/core/src/debug/constants.ts — Debug trace constants and mappings.
+ *
+ * Why: Provides numeric constants matching the C engine's debug enums and
+ * bidirectional mappings between numeric values and TypeScript string types.
+ * These constants ensure consistent encoding/decoding of debug records.
+ *
+ * C enums reference: include/zr/zr_debug.h
+ */
+import type { DebugCategory, DebugSeverity, PerfPhase } from "./types.js";
+export declare const DEBUG_CAT_NONE = 0;
+export declare const DEBUG_CAT_FRAME = 1;
+export declare const DEBUG_CAT_EVENT = 2;
+export declare const DEBUG_CAT_DRAWLIST = 3;
+export declare const DEBUG_CAT_ERROR = 4;
+export declare const DEBUG_CAT_STATE = 5;
+export declare const DEBUG_CAT_PERF = 6;
+/** Bitmask including all debug categories. */
+export declare const DEBUG_CAT_ALL: number;
+export declare const DEBUG_SEV_TRACE = 0;
+export declare const DEBUG_SEV_INFO = 1;
+export declare const DEBUG_SEV_WARN = 2;
+export declare const DEBUG_SEV_ERROR = 3;
+/** Drawlist validate summary record code (structured zr_debug_drawlist_record_t). */
+export declare const DEBUG_CODE_DRAWLIST_VALIDATE = 768;
+/** Drawlist execute summary record code (structured zr_debug_drawlist_record_t). */
+export declare const DEBUG_CODE_DRAWLIST_EXECUTE = 769;
+/** Raw drawlist byte-stream record code (payload may contain sensitive render bytes). */
+export declare const DEBUG_CODE_DRAWLIST_CMD = 770;
+export declare const PERF_PHASE_POLL = 0;
+export declare const PERF_PHASE_SUBMIT = 1;
+export declare const PERF_PHASE_PRESENT = 2;
+/** Size of zr_debug_record_header_t in bytes. */
+export declare const DEBUG_RECORD_HEADER_SIZE = 40;
+/** Size of zr_debug_frame_record_t in bytes. */
+export declare const DEBUG_FRAME_RECORD_SIZE = 56;
+/** Size of zr_debug_event_record_t in bytes. */
+export declare const DEBUG_EVENT_RECORD_SIZE = 32;
+/** Size of zr_debug_error_record_t in bytes. */
+export declare const DEBUG_ERROR_RECORD_SIZE = 120;
+/** Size of zr_debug_drawlist_record_t in bytes. */
+export declare const DEBUG_DRAWLIST_RECORD_SIZE = 48;
+/** Size of zr_debug_perf_record_t in bytes. */
+export declare const DEBUG_PERF_RECORD_SIZE = 24;
+/** Size of zr_debug_config_t in bytes. */
+export declare const DEBUG_CONFIG_SIZE = 32;
+/** Size of zr_debug_query_t in bytes. */
+export declare const DEBUG_QUERY_SIZE = 48;
+/** Size of zr_debug_query_result_t in bytes. */
+export declare const DEBUG_QUERY_RESULT_SIZE = 32;
+/** Size of zr_debug_stats_t in bytes. */
+export declare const DEBUG_STATS_SIZE = 32;
+/** Stable schema identifier for JSON debug bundles. */
+export declare const DEBUG_BUNDLE_SCHEMA_V1 = "rezi-debug-bundle-v1";
+/** Default maximum number of trace headers exported into a bundle. */
+export declare const DEBUG_BUNDLE_DEFAULT_MAX_RECORDS = 512;
+/** Default maximum payload bytes included per trace record. */
+export declare const DEBUG_BUNDLE_DEFAULT_MAX_PAYLOAD_BYTES = 4096;
+/** Default maximum payload bytes included across all records. */
+export declare const DEBUG_BUNDLE_DEFAULT_MAX_TOTAL_PAYLOAD_BYTES = 262144;
+/** Default maximum recent frame summaries included when available. */
+export declare const DEBUG_BUNDLE_DEFAULT_MAX_RECENT_FRAMES = 32;
+/**
+ * Convert a numeric category value to its string representation.
+ * Returns null if the value is not a valid category.
+ */
+export declare function categoryFromNum(num: number): DebugCategory | null;
+/**
+ * Convert a category string to its numeric value.
+ * Returns null if the string is not a valid category.
+ */
+export declare function categoryToNum(cat: DebugCategory): number | null;
+/**
+ * Convert a numeric severity value to its string representation.
+ * Returns null if the value is not a valid severity.
+ */
+export declare function severityFromNum(num: number): DebugSeverity | null;
+/**
+ * Convert a severity string to its numeric value.
+ * Returns null if the string is not a valid severity.
+ */
+export declare function severityToNum(sev: DebugSeverity): number | null;
+/**
+ * Convert a numeric performance phase to its string representation.
+ * Returns null if the value is not a valid phase.
+ */
+export declare function perfPhaseFromNum(num: number): PerfPhase | null;
+/**
+ * Create a category bitmask from an array of categories.
+ */
+export declare function categoriesToMask(categories: readonly DebugCategory[]): number;
+/**
+ * Extract categories from a bitmask.
+ */
+export declare function maskToCategories(mask: number): DebugCategory[];
+/**
+ * Check if a category is set in a bitmask.
+ */
+export declare function isCategoryInMask(mask: number, category: DebugCategory): boolean;
+//# sourceMappingURL=constants.d.ts.map

package/dist/debug/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/debug/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI1E,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,8CAA8C;AAC9C,eAAO,MAAM,aAAa,QAMH,CAAC;AAIxB,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,eAAe,IAAI,CAAC;AAIjC,qFAAqF;AACrF,eAAO,MAAM,4BAA4B,MAAS,CAAC;AAEnD,oFAAoF;AACpF,eAAO,MAAM,2BAA2B,MAAS,CAAC;AAElD,yFAAyF;AACzF,eAAO,MAAM,uBAAuB,MAAS,CAAC;AAI9C,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAIpC,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAI3C,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,mDAAmD;AACnD,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,+CAA+C;AAC/C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAIzC,0CAA0C;AAC1C,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAInC,uDAAuD;AACvD,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D,sEAAsE;AACtE,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,+DAA+D;AAC/D,eAAO,MAAM,sCAAsC,OAAO,CAAC;AAE3D,iEAAiE;AACjE,eAAO,MAAM,4CAA4C,SAAU,CAAC;AAEpE,sEAAsE;AACtE,eAAO,MAAM,sCAAsC,KAAK,CAAC;AAwBzD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAEjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAE/D;AAkBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAEjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAE/D;AAUD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAE9D;AAID;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAS7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAQ9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAI/E"}

package/dist/debug/constants.js

@@ -0,0 +1,183 @@
+/**
+ * packages/core/src/debug/constants.ts — Debug trace constants and mappings.
+ *
+ * Why: Provides numeric constants matching the C engine's debug enums and
+ * bidirectional mappings between numeric values and TypeScript string types.
+ * These constants ensure consistent encoding/decoding of debug records.
+ *
+ * C enums reference: include/zr/zr_debug.h
+ */
+/* --- Category Constants (match zr_debug_category_t) --- */
+export const DEBUG_CAT_NONE = 0;
+export const DEBUG_CAT_FRAME = 1;
+export const DEBUG_CAT_EVENT = 2;
+export const DEBUG_CAT_DRAWLIST = 3;
+export const DEBUG_CAT_ERROR = 4;
+export const DEBUG_CAT_STATE = 5;
+export const DEBUG_CAT_PERF = 6;
+/** Bitmask including all debug categories. */
+export const DEBUG_CAT_ALL = (1 << DEBUG_CAT_FRAME) |
+    (1 << DEBUG_CAT_EVENT) |
+    (1 << DEBUG_CAT_DRAWLIST) |
+    (1 << DEBUG_CAT_ERROR) |
+    (1 << DEBUG_CAT_STATE) |
+    (1 << DEBUG_CAT_PERF);
+/* --- Severity Constants (match zr_debug_severity_t) --- */
+export const DEBUG_SEV_TRACE = 0;
+export const DEBUG_SEV_INFO = 1;
+export const DEBUG_SEV_WARN = 2;
+export const DEBUG_SEV_ERROR = 3;
+/* --- Drawlist Record Codes (match zr_debug_code_t) --- */
+/** Drawlist validate summary record code (structured zr_debug_drawlist_record_t). */
+export const DEBUG_CODE_DRAWLIST_VALIDATE = 0x0300;
+/** Drawlist execute summary record code (structured zr_debug_drawlist_record_t). */
+export const DEBUG_CODE_DRAWLIST_EXECUTE = 0x0301;
+/** Raw drawlist byte-stream record code (payload may contain sensitive render bytes). */
+export const DEBUG_CODE_DRAWLIST_CMD = 0x0302;
+/* --- Performance Phase Constants --- */
+export const PERF_PHASE_POLL = 0;
+export const PERF_PHASE_SUBMIT = 1;
+export const PERF_PHASE_PRESENT = 2;
+/* --- Record Header Size --- */
+/** Size of zr_debug_record_header_t in bytes. */
+export const DEBUG_RECORD_HEADER_SIZE = 40;
+/* --- Payload Sizes --- */
+/** Size of zr_debug_frame_record_t in bytes. */
+export const DEBUG_FRAME_RECORD_SIZE = 56;
+/** Size of zr_debug_event_record_t in bytes. */
+export const DEBUG_EVENT_RECORD_SIZE = 32;
+/** Size of zr_debug_error_record_t in bytes. */
+export const DEBUG_ERROR_RECORD_SIZE = 120;
+/** Size of zr_debug_drawlist_record_t in bytes. */
+export const DEBUG_DRAWLIST_RECORD_SIZE = 48;
+/** Size of zr_debug_perf_record_t in bytes. */
+export const DEBUG_PERF_RECORD_SIZE = 24;
+/* --- Config/Query Sizes --- */
+/** Size of zr_debug_config_t in bytes. */
+export const DEBUG_CONFIG_SIZE = 32;
+/** Size of zr_debug_query_t in bytes. */
+export const DEBUG_QUERY_SIZE = 48;
+/** Size of zr_debug_query_result_t in bytes. */
+export const DEBUG_QUERY_RESULT_SIZE = 32;
+/** Size of zr_debug_stats_t in bytes. */
+export const DEBUG_STATS_SIZE = 32;
+/* --- Bundle Export Constants --- */
+/** Stable schema identifier for JSON debug bundles. */
+export const DEBUG_BUNDLE_SCHEMA_V1 = "rezi-debug-bundle-v1";
+/** Default maximum number of trace headers exported into a bundle. */
+export const DEBUG_BUNDLE_DEFAULT_MAX_RECORDS = 512;
+/** Default maximum payload bytes included per trace record. */
+export const DEBUG_BUNDLE_DEFAULT_MAX_PAYLOAD_BYTES = 4096;
+/** Default maximum payload bytes included across all records. */
+export const DEBUG_BUNDLE_DEFAULT_MAX_TOTAL_PAYLOAD_BYTES = 262_144;
+/** Default maximum recent frame summaries included when available. */
+export const DEBUG_BUNDLE_DEFAULT_MAX_RECENT_FRAMES = 32;
+/* --- Category Mapping --- */
+const CATEGORY_NUM_TO_STR = new Map([
+    [DEBUG_CAT_NONE, "none"],
+    [DEBUG_CAT_FRAME, "frame"],
+    [DEBUG_CAT_EVENT, "event"],
+    [DEBUG_CAT_DRAWLIST, "drawlist"],
+    [DEBUG_CAT_ERROR, "error"],
+    [DEBUG_CAT_STATE, "state"],
+    [DEBUG_CAT_PERF, "perf"],
+]);
+const CATEGORY_STR_TO_NUM = new Map([
+    ["none", DEBUG_CAT_NONE],
+    ["frame", DEBUG_CAT_FRAME],
+    ["event", DEBUG_CAT_EVENT],
+    ["drawlist", DEBUG_CAT_DRAWLIST],
+    ["error", DEBUG_CAT_ERROR],
+    ["state", DEBUG_CAT_STATE],
+    ["perf", DEBUG_CAT_PERF],
+]);
+/**
+ * Convert a numeric category value to its string representation.
+ * Returns null if the value is not a valid category.
+ */
+export function categoryFromNum(num) {
+    return CATEGORY_NUM_TO_STR.get(num) ?? null;
+}
+/**
+ * Convert a category string to its numeric value.
+ * Returns null if the string is not a valid category.
+ */
+export function categoryToNum(cat) {
+    return CATEGORY_STR_TO_NUM.get(cat) ?? null;
+}
+/* --- Severity Mapping --- */
+const SEVERITY_NUM_TO_STR = new Map([
+    [DEBUG_SEV_TRACE, "trace"],
+    [DEBUG_SEV_INFO, "info"],
+    [DEBUG_SEV_WARN, "warn"],
+    [DEBUG_SEV_ERROR, "error"],
+]);
+const SEVERITY_STR_TO_NUM = new Map([
+    ["trace", DEBUG_SEV_TRACE],
+    ["info", DEBUG_SEV_INFO],
+    ["warn", DEBUG_SEV_WARN],
+    ["error", DEBUG_SEV_ERROR],
+]);
+/**
+ * Convert a numeric severity value to its string representation.
+ * Returns null if the value is not a valid severity.
+ */
+export function severityFromNum(num) {
+    return SEVERITY_NUM_TO_STR.get(num) ?? null;
+}
+/**
+ * Convert a severity string to its numeric value.
+ * Returns null if the string is not a valid severity.
+ */
+export function severityToNum(sev) {
+    return SEVERITY_STR_TO_NUM.get(sev) ?? null;
+}
+/* --- Performance Phase Mapping --- */
+const PERF_PHASE_NUM_TO_STR = new Map([
+    [PERF_PHASE_POLL, "poll"],
+    [PERF_PHASE_SUBMIT, "submit"],
+    [PERF_PHASE_PRESENT, "present"],
+]);
+/**
+ * Convert a numeric performance phase to its string representation.
+ * Returns null if the value is not a valid phase.
+ */
+export function perfPhaseFromNum(num) {
+    return PERF_PHASE_NUM_TO_STR.get(num) ?? null;
+}
+/* --- Category Bitmask Helpers --- */
+/**
+ * Create a category bitmask from an array of categories.
+ */
+export function categoriesToMask(categories) {
+    let mask = 0;
+    for (const cat of categories) {
+        const num = categoryToNum(cat);
+        if (num !== null && num > 0) {
+            mask |= 1 << num;
+        }
+    }
+    return mask;
+}
+/**
+ * Extract categories from a bitmask.
+ */
+export function maskToCategories(mask) {
+    const result = [];
+    for (const [num, cat] of CATEGORY_NUM_TO_STR) {
+        if (num > 0 && (mask & (1 << num)) !== 0) {
+            result.push(cat);
+        }
+    }
+    return result;
+}
+/**
+ * Check if a category is set in a bitmask.
+ */
+export function isCategoryInMask(mask, category) {
+    const num = categoryToNum(category);
+    if (num === null || num === 0)
+        return false;
+    return (mask & (1 << num)) !== 0;
+}
+//# sourceMappingURL=constants.js.map

package/dist/debug/constants.js.map

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

package/dist/debug/debug.d.ts

@@ -0,0 +1,14 @@
+/**
+ * packages/core/src/debug/debug.ts — UI-level debug helpers.
+ *
+ * Why: Lightweight helpers for instrumenting widget trees during development.
+ * These are pure factories and do not perform I/O.
+ */
+import type { VNode } from "../widgets/types.js";
+export declare function debug(node: VNode, options?: {
+    showId?: boolean;
+}): VNode;
+export declare function inspect(value: unknown, options?: {
+    depth?: number;
+}): VNode;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug/debug.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAGjD,wBAAgB,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,KAAK,CAWxE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAG3E"}

package/dist/debug/debug.js

@@ -0,0 +1,54 @@
+/**
+ * packages/core/src/debug/debug.ts — UI-level debug helpers.
+ *
+ * Why: Lightweight helpers for instrumenting widget trees during development.
+ * These are pure factories and do not perform I/O.
+ */
+import { ui } from "../widgets/ui.js";
+export function debug(node, options) {
+    const id = getNodeId(node);
+    const label = options?.showId !== false && id ? ` ${id} ` : "";
+    return ui.box({
+        border: "single",
+        title: label,
+    }, [node]);
+}
+export function inspect(value, options) {
+    const text = formatValue(value, options?.depth ?? 3, 0);
+    return ui.text(text, { style: { dim: true } });
+}
+function formatValue(value, maxDepth, depth) {
+    if (depth > maxDepth)
+        return "...";
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "string")
+        return `"${value}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        const items = value.map((v) => formatValue(v, maxDepth, depth + 1));
+        return `[${items.join(", ")}]`;
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return "{}";
+        const pairs = entries.map(([k, v]) => `${k}: ${formatValue(v, maxDepth, depth + 1)}`);
+        return `{ ${pairs.join(", ")} }`;
+    }
+    return String(value);
+}
+function getNodeId(node) {
+    if ("props" in node) {
+        const id = node.props?.id;
+        if (typeof id === "string")
+            return id;
+    }
+    return null;
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/debug/debug.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAEtC,MAAM,UAAU,KAAK,CAAC,IAAW,EAAE,OAA8B;IAC/D,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/D,OAAO,EAAE,CAAC,GAAG,CACX;QACE,MAAM,EAAE,QAAQ;QAChB,KAAK,EAAE,KAAK;KACb,EACD,CAAC,IAAI,CAAC,CACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc,EAAE,OAA4B;IAClE,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,QAAgB,EAAE,KAAa;IAClE,IAAI,KAAK,GAAG,QAAQ;QAAE,OAAO,KAAK,CAAC;IAEnC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,KAAK,GAAG,CAAC;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAElF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QACpE,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IACjC,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC;QACjE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QACtF,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACnC,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,SAAS,CAAC,IAAW;IAC5B,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACpB,MAAM,EAAE,GAAI,IAAoC,CAAC,KAAK,EAAE,EAAE,CAAC;QAC3D,IAAI,OAAO,EAAE,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/debug/debugController.d.ts

@@ -0,0 +1,164 @@
+/**
+ * packages/core/src/debug/debugController.ts — Main debug trace controller.
+ *
+ * Why: Provides a unified interface for all debug tracing capabilities. Wraps
+ * the low-level engine debug API and coordinates the high-level analysis tools
+ * (FrameInspector, EventTrace, ErrorAggregator, StateTimeline).
+ *
+ * Architecture:
+ *   - Low-level: Proxies to the engine debug API via RuntimeBackend
+ *   - High-level: Manages analysis components that process debug records
+ *   - Subscriptions: Enables reactive updates when new records arrive
+ *
+ * Usage:
+ *   const debug = app.debug;
+ *   debug.enable({ minSeverity: 'info' });
+ *   const errors = debug.errors.all();
+ *   const frames = debug.frameInspector.getSnapshots(10);
+ */
+import type { TerminalCaps } from "../terminalCaps.js";
+import { type AggregatedError, type ErrorAggregator } from "./errorAggregator.js";
+import { type EventTrace } from "./eventTrace.js";
+import { type FrameInspector } from "./frameInspector.js";
+import { type StateTimeline } from "./stateTimeline.js";
+import type { DebugBundle, DebugBundleExportOptions, DebugConfig, DebugPayload, DebugQuery, DebugQueryResult, DebugRecord, DebugStats } from "./types.js";
+/**
+ * Debug record handler callback type.
+ */
+export type DebugRecordHandler = (record: DebugRecord) => void;
+/**
+ * Debug error handler callback type.
+ */
+export type DebugErrorHandler = (error: AggregatedError) => void;
+/**
+ * Debug event types for subscriptions.
+ */
+export type DebugEventType = "record" | "error";
+type TerminalCapsProvider = () => TerminalCaps | null | Promise<TerminalCaps | null>;
+/**
+ * Debug backend interface for engine communication.
+ * This is a subset of RuntimeBackend focused on debug operations.
+ */
+export interface DebugBackend {
+    /** Enable debug tracing with the given configuration. */
+    debugEnable(config: DebugConfig): Promise<void>;
+    /** Disable debug tracing. */
+    debugDisable(): Promise<void>;
+    /** Query debug records. Returns headers and query result. */
+    debugQuery(query: DebugQuery): Promise<{
+        headers: Uint8Array;
+        result: DebugQueryResult;
+    }>;
+    /** Get payload for a specific record. */
+    debugGetPayload(recordId: bigint): Promise<Uint8Array | null>;
+    /** Get debug statistics. */
+    debugGetStats(): Promise<DebugStats>;
+    /** Export all debug records to a buffer. */
+    debugExport(): Promise<Uint8Array>;
+    /** Reset (clear) debug records. */
+    debugReset(): Promise<void>;
+}
+/**
+ * Debug controller interface.
+ */
+export interface DebugController {
+    /**
+     * Enable debug tracing.
+     * @param config - Optional configuration overrides
+     */
+    enable(config?: Partial<DebugConfig>): Promise<void>;
+    /**
+     * Disable debug tracing.
+     */
+    disable(): Promise<void>;
+    /**
+     * Reset (clear) all debug records while keeping tracing enabled.
+     */
+    reset(): Promise<void>;
+    /**
+     * Query debug records from the engine.
+     * @param filter - Optional query filter
+     */
+    query(filter?: DebugQuery): Promise<readonly DebugRecord[]>;
+    /**
+     * Get the payload for a specific record.
+     * @param recordId - The record ID
+     */
+    getPayload<T extends DebugPayload>(recordId: bigint): Promise<T | null>;
+    /**
+     * Get debug statistics.
+     */
+    getStats(): Promise<DebugStats>;
+    /**
+     * Export all debug records to a buffer for offline analysis.
+     */
+    export(): Promise<Uint8Array>;
+    /**
+     * Export a deterministic, versioned JSON debug bundle.
+     */
+    exportBundle(options?: DebugBundleExportOptions): Promise<DebugBundle>;
+    /**
+     * Export the debug bundle as UTF-8 JSON bytes.
+     */
+    exportBundleBytes(options?: DebugBundleExportOptions): Promise<Uint8Array>;
+    /**
+     * Frame inspector for analyzing frame history.
+     */
+    readonly frameInspector: FrameInspector;
+    /**
+     * Event trace for tracking event flow.
+     */
+    readonly eventTrace: EventTrace;
+    /**
+     * Error aggregator for collecting errors.
+     */
+    readonly errors: ErrorAggregator;
+    /**
+     * State timeline for tracking state changes.
+     */
+    readonly stateTimeline: StateTimeline;
+    /**
+     * Subscribe to debug events.
+     * @param event - Event type: 'record' or 'error'
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    on(event: "record", handler: DebugRecordHandler): () => void;
+    on(event: "error", handler: DebugErrorHandler): () => void;
+    /**
+     * Whether debug tracing is currently enabled.
+     */
+    readonly enabled: boolean;
+    /**
+     * Current configuration (null if not enabled).
+     */
+    readonly config: DebugConfig | null;
+    /**
+     * Process a batch of debug record headers and payloads.
+     * Called internally by the app runtime.
+     */
+    processRecords(headers: Uint8Array, payloads: Map<bigint, Uint8Array>): void;
+}
+/**
+ * Options for creating a debug controller.
+ */
+export type CreateDebugControllerOptions = Readonly<{
+    /** Backend for engine communication (optional, enables backend features if provided) */
+    backend?: DebugBackend;
+    /** Initial configuration to apply on creation */
+    initialConfig?: DebugConfig;
+    /** Maximum frames to retain in frame inspector */
+    maxFrames?: number;
+    /** Maximum events to retain in event trace */
+    maxEvents?: number;
+    /** Maximum state changes to retain */
+    maxStateChanges?: number;
+    /** Optional provider used to snapshot terminal capabilities during bundle export. */
+    terminalCapsProvider?: TerminalCapsProvider;
+}>;
+/**
+ * Create a debug controller instance.
+ */
+export declare function createDebugController(options?: CreateDebugControllerOptions): DebugController;
+export {};
+//# sourceMappingURL=debugController.d.ts.map

package/dist/debug/debugController.d.ts.map

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