@slowclap/rezi-core 0.1.0-fork.1

package/dist/binary/reader.js

@@ -0,0 +1,107 @@
+/**
+ * packages/core/src/binary/reader.ts — Bounds-checked binary buffer reader.
+ *
+ * Why: Provides safe, deterministic reading of little-endian binary data with
+ * automatic bounds validation. Every read operation validates available bytes
+ * before access, preventing buffer overflows and ensuring parse failures are
+ * caught early with precise offset reporting.
+ *
+ * Invariants:
+ *   - All multi-byte reads use little-endian byte order
+ *   - DataView is constructed with correct byteOffset to handle Uint8Array slices
+ *   - Offset advances only after successful validation
+ *   - ZrBinaryError thrown on any bounds/alignment violation
+ *
+ * @see docs/protocol/safety.md
+ */
+import { ZrBinaryError } from "./parseError.js";
+/**
+ * Bounds-checked binary reader with cursor tracking.
+ *
+ * Ownership: BinaryReader borrows the input buffer; caller retains ownership.
+ * The buffer must remain valid and unmodified for the reader's lifetime.
+ */
+export class BinaryReader {
+    bytes;
+    dv;
+    off = 0;
+    constructor(bytes) {
+        this.bytes = bytes;
+        this.dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    }
+    get offset() {
+        return this.off;
+    }
+    get byteLength() {
+        return this.bytes.byteLength;
+    }
+    get remaining() {
+        return this.byteLength - this.off;
+    }
+    /** Validate that offset is 4-byte aligned; throws ZR_MISALIGNED on violation. */
+    ensureAligned4(offset = this.off) {
+        if ((offset & 3) !== 0) {
+            throw new ZrBinaryError({
+                code: "ZR_MISALIGNED",
+                offset,
+                detail: "offset must be 4-byte aligned",
+            });
+        }
+    }
+    /** Advance cursor by len bytes without reading; validates bounds first. */
+    skip(len) {
+        if (!Number.isInteger(len) || len < 0) {
+            throw new Error(`BinaryReader.skip: len must be a non-negative integer (got ${String(len)})`);
+        }
+        this.ensureAvailable(len);
+        this.off += len;
+    }
+    /** Read unsigned 8-bit integer, advancing cursor by 1 byte. */
+    readU8() {
+        this.ensureAvailable(1);
+        const v = this.dv.getUint8(this.off);
+        this.off += 1;
+        return v;
+    }
+    /** Read unsigned 32-bit integer (little-endian), advancing cursor by 4 bytes. */
+    readU32() {
+        this.ensureAvailable(4);
+        const v = this.dv.getUint32(this.off, true);
+        this.off += 4;
+        return v;
+    }
+    /** Read signed 32-bit integer (little-endian), advancing cursor by 4 bytes. */
+    readI32() {
+        this.ensureAvailable(4);
+        const v = this.dv.getInt32(this.off, true);
+        this.off += 4;
+        return v;
+    }
+    /**
+     * Read len bytes as a subarray view, advancing cursor by len bytes.
+     * The returned Uint8Array shares the underlying buffer with the reader.
+     */
+    readBytes(len) {
+        if (!Number.isInteger(len) || len < 0) {
+            throw new Error(`BinaryReader.readBytes: len must be a non-negative integer (got ${String(len)})`);
+        }
+        this.ensureAvailable(len);
+        const out = this.bytes.subarray(this.off, this.off + len);
+        this.off += len;
+        return out;
+    }
+    /**
+     * Validate that n bytes are available from current cursor position.
+     * Throws ZR_TRUNCATED if buffer would be exceeded.
+     */
+    ensureAvailable(n) {
+        if (this.off + n > this.byteLength) {
+            throw new ZrBinaryError({
+                code: "ZR_TRUNCATED",
+                offset: this.off,
+                detail: `need ${n} byte(s) but only ${Math.max(0, this.byteLength - this.off)} remaining`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=reader.js.map

package/dist/binary/reader.js.map

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

package/dist/binary/writer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * packages/core/src/binary/writer.ts — Bounds-checked binary buffer writer.
+ *
+ * Why: Provides safe, deterministic writing of little-endian binary data with
+ * automatic capacity validation. Every write operation validates available space
+ * before mutation, preventing buffer overflows and ensuring build failures are
+ * caught early with precise offset reporting.
+ *
+ * Invariants:
+ *   - All multi-byte writes use little-endian byte order
+ *   - 4-byte alignment enforced for U32/I32 writes
+ *   - Padding bytes are explicitly zeroed (not left as garbage)
+ *   - ZrBinaryError thrown on any capacity/alignment violation
+ *
+ * @see docs/protocol/safety.md
+ */
+/**
+ * Bounds-checked binary writer with cursor tracking.
+ *
+ * Ownership: BinaryWriter owns its internal buffer. The buffer returned by
+ * finish() is a subarray view; caller should copy if the writer will be reused.
+ */
+export declare class BinaryWriter {
+    private readonly buf;
+    private readonly dv;
+    private off;
+    constructor(capacity: number);
+    get offset(): number;
+    get capacity(): number;
+    /** Write unsigned 8-bit integer, advancing cursor by 1 byte. */
+    writeU8(v: number): void;
+    /**
+     * Write unsigned 32-bit integer (little-endian), advancing cursor by 4 bytes.
+     * Requires cursor to be 4-byte aligned.
+     */
+    writeU32(v: number): void;
+    /**
+     * Write signed 32-bit integer (little-endian), advancing cursor by 4 bytes.
+     * Requires cursor to be 4-byte aligned.
+     */
+    writeI32(v: number): void;
+    /** Write raw bytes, advancing cursor by bytes.byteLength. */
+    writeBytes(bytes: Uint8Array): void;
+    /**
+     * Pad cursor to next 4-byte boundary with zero bytes.
+     * Required before writing U32/I32 values and for format compliance.
+     */
+    padTo4(): void;
+    /**
+     * Return the written portion of the buffer as a Uint8Array view.
+     * The returned view shares underlying memory with the writer.
+     */
+    finish(): Uint8Array;
+    /** Validate 4-byte alignment; throws ZR_MISALIGNED on violation. */
+    private ensureAligned4;
+    /** Validate that n bytes can be written; throws ZR_LIMIT if capacity exceeded. */
+    private ensureCanWrite;
+}
+//# sourceMappingURL=writer.d.ts.map

package/dist/binary/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/binary/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,GAAG,CAAK;gBAEJ,QAAQ,EAAE,MAAM;IAU5B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,gEAAgE;IAChE,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAMxB;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAOzB;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAOzB,6DAA6D;IAC7D,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAMnC;;;OAGG;IACH,MAAM,IAAI,IAAI;IASd;;;OAGG;IACH,MAAM,IAAI,UAAU;IAIpB,oEAAoE;IACpE,OAAO,CAAC,cAAc;IAUtB,kFAAkF;IAClF,OAAO,CAAC,cAAc;CASvB"}

package/dist/binary/writer.js

@@ -0,0 +1,114 @@
+/**
+ * packages/core/src/binary/writer.ts — Bounds-checked binary buffer writer.
+ *
+ * Why: Provides safe, deterministic writing of little-endian binary data with
+ * automatic capacity validation. Every write operation validates available space
+ * before mutation, preventing buffer overflows and ensuring build failures are
+ * caught early with precise offset reporting.
+ *
+ * Invariants:
+ *   - All multi-byte writes use little-endian byte order
+ *   - 4-byte alignment enforced for U32/I32 writes
+ *   - Padding bytes are explicitly zeroed (not left as garbage)
+ *   - ZrBinaryError thrown on any capacity/alignment violation
+ *
+ * @see docs/protocol/safety.md
+ */
+import { ZrBinaryError } from "./parseError.js";
+/**
+ * Bounds-checked binary writer with cursor tracking.
+ *
+ * Ownership: BinaryWriter owns its internal buffer. The buffer returned by
+ * finish() is a subarray view; caller should copy if the writer will be reused.
+ */
+export class BinaryWriter {
+    buf;
+    dv;
+    off = 0;
+    constructor(capacity) {
+        if (!Number.isInteger(capacity) || capacity < 0) {
+            throw new Error(`BinaryWriter: capacity must be a non-negative integer (got ${String(capacity)})`);
+        }
+        this.buf = new Uint8Array(capacity);
+        this.dv = new DataView(this.buf.buffer, this.buf.byteOffset, this.buf.byteLength);
+    }
+    get offset() {
+        return this.off;
+    }
+    get capacity() {
+        return this.buf.byteLength;
+    }
+    /** Write unsigned 8-bit integer, advancing cursor by 1 byte. */
+    writeU8(v) {
+        this.ensureCanWrite(1);
+        this.dv.setUint8(this.off, v & 0xff);
+        this.off += 1;
+    }
+    /**
+     * Write unsigned 32-bit integer (little-endian), advancing cursor by 4 bytes.
+     * Requires cursor to be 4-byte aligned.
+     */
+    writeU32(v) {
+        this.ensureAligned4(this.off);
+        this.ensureCanWrite(4);
+        this.dv.setUint32(this.off, v >>> 0, true);
+        this.off += 4;
+    }
+    /**
+     * Write signed 32-bit integer (little-endian), advancing cursor by 4 bytes.
+     * Requires cursor to be 4-byte aligned.
+     */
+    writeI32(v) {
+        this.ensureAligned4(this.off);
+        this.ensureCanWrite(4);
+        this.dv.setInt32(this.off, v | 0, true);
+        this.off += 4;
+    }
+    /** Write raw bytes, advancing cursor by bytes.byteLength. */
+    writeBytes(bytes) {
+        this.ensureCanWrite(bytes.byteLength);
+        this.buf.set(bytes, this.off);
+        this.off += bytes.byteLength;
+    }
+    /**
+     * Pad cursor to next 4-byte boundary with zero bytes.
+     * Required before writing U32/I32 values and for format compliance.
+     */
+    padTo4() {
+        const aligned = (this.off + 3) & ~3;
+        if (aligned === this.off)
+            return;
+        const pad = aligned - this.off;
+        this.ensureCanWrite(pad);
+        this.buf.fill(0x00, this.off, aligned);
+        this.off = aligned;
+    }
+    /**
+     * Return the written portion of the buffer as a Uint8Array view.
+     * The returned view shares underlying memory with the writer.
+     */
+    finish() {
+        return this.buf.subarray(0, this.off);
+    }
+    /** Validate 4-byte alignment; throws ZR_MISALIGNED on violation. */
+    ensureAligned4(offset) {
+        if ((offset & 3) !== 0) {
+            throw new ZrBinaryError({
+                code: "ZR_MISALIGNED",
+                offset,
+                detail: "offset must be 4-byte aligned",
+            });
+        }
+    }
+    /** Validate that n bytes can be written; throws ZR_LIMIT if capacity exceeded. */
+    ensureCanWrite(n) {
+        if (this.off + n > this.capacity) {
+            throw new ZrBinaryError({
+                code: "ZR_LIMIT",
+                offset: this.off,
+                detail: `write of ${n} byte(s) exceeds capacity ${this.capacity}`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/binary/writer.js.map

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

package/dist/constraints/expr.d.ts

@@ -0,0 +1,9 @@
+/**
+ * packages/core/src/constraints/expr.ts — Public expression entrypoint.
+ *
+ * Why: Provides parse-once objects with frozen AST metadata for frame-time reuse.
+ */
+import type { ConstraintExpr } from "./types.js";
+export declare function expr(source: string): ConstraintExpr;
+export declare function isConstraintExpr(value: unknown): value is ConstraintExpr;
+//# sourceMappingURL=expr.d.ts.map

package/dist/constraints/expr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr.d.ts","sourceRoot":"","sources":["../../src/constraints/expr.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,KAAK,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAgGrE,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CA+BnD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAQxE"}

package/dist/constraints/expr.js

@@ -0,0 +1,134 @@
+/**
+ * packages/core/src/constraints/expr.ts — Public expression entrypoint.
+ *
+ * Why: Provides parse-once objects with frozen AST metadata for frame-time reuse.
+ */
+import { collectWidgetRefUsages, detectIntrinsicRefs, detectSiblingAggregation, extractRefs, parse, } from "./parser.js";
+const EXPR_CACHE_MAX = 256;
+const EXPR_CACHE = new Map();
+function freezeScope(scope) {
+    if (scope.kind === "widget") {
+        return Object.freeze({ kind: "widget", id: scope.id });
+    }
+    return Object.freeze({ kind: scope.kind });
+}
+function freezeAst(node) {
+    switch (node.kind) {
+        case "number":
+            return Object.freeze({ kind: "number", value: node.value });
+        case "ref":
+            return Object.freeze({
+                kind: "ref",
+                scope: freezeScope(node.scope),
+                prop: node.prop,
+            });
+        case "unary":
+            return Object.freeze({
+                kind: "unary",
+                op: node.op,
+                operand: freezeAst(node.operand),
+            });
+        case "binary":
+            return Object.freeze({
+                kind: "binary",
+                op: node.op,
+                left: freezeAst(node.left),
+                right: freezeAst(node.right),
+            });
+        case "compare":
+            return Object.freeze({
+                kind: "compare",
+                op: node.op,
+                left: freezeAst(node.left),
+                right: freezeAst(node.right),
+            });
+        case "ternary":
+            return Object.freeze({
+                kind: "ternary",
+                condition: freezeAst(node.condition),
+                // biome-ignore lint/suspicious/noThenProperty: "then" is an AST field (not a Promise-like thenable).
+                then: freezeAst(node.then),
+                else: freezeAst(node.else),
+            });
+        case "call": {
+            const args = Object.freeze(node.args.map((arg) => freezeAst(arg)));
+            return Object.freeze({
+                kind: "call",
+                name: node.name,
+                args,
+            });
+        }
+        default:
+            return node;
+    }
+}
+function freezeReadonlySet(set) {
+    const snapshot = new Set(set);
+    const view = {
+        get size() {
+            return snapshot.size;
+        },
+        has(value) {
+            return snapshot.has(value);
+        },
+        forEach(callbackfn, thisArg) {
+            for (const value of snapshot) {
+                callbackfn.call(thisArg, value, value, view);
+            }
+        },
+        entries() {
+            return snapshot.entries();
+        },
+        keys() {
+            return snapshot.keys();
+        },
+        values() {
+            return snapshot.values();
+        },
+        [Symbol.iterator]() {
+            return snapshot[Symbol.iterator]();
+        },
+    };
+    return Object.freeze(view);
+}
+export function expr(source) {
+    const cached = EXPR_CACHE.get(source);
+    if (cached !== undefined) {
+        // Refresh simple LRU access order.
+        EXPR_CACHE.delete(source);
+        EXPR_CACHE.set(source, cached);
+        return cached;
+    }
+    const parsed = parse(source);
+    const ast = freezeAst(parsed);
+    const refs = freezeReadonlySet(extractRefs(ast));
+    const hasIntrinsic = detectIntrinsicRefs(ast);
+    const hasSiblingAggregation = detectSiblingAggregation(ast);
+    // Keep call-site analysis hot-path free by validating usage here once.
+    void collectWidgetRefUsages(ast);
+    const out = Object.freeze({
+        __brand: "ConstraintExpr",
+        source,
+        ast,
+        refs,
+        hasIntrinsic,
+        hasSiblingAggregation,
+    });
+    EXPR_CACHE.set(source, out);
+    while (EXPR_CACHE.size > EXPR_CACHE_MAX) {
+        const oldest = EXPR_CACHE.keys().next().value;
+        if (typeof oldest !== "string")
+            break;
+        EXPR_CACHE.delete(oldest);
+    }
+    return out;
+}
+export function isConstraintExpr(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const maybe = value;
+    return (maybe.__brand === "ConstraintExpr" &&
+        typeof maybe.source === "string" &&
+        maybe.ast !== undefined);
+}
+//# sourceMappingURL=expr.js.map

package/dist/constraints/expr.js.map

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

package/dist/constraints/graph.d.ts

@@ -0,0 +1,62 @@
+/**
+ * packages/core/src/constraints/graph.ts — Constraint dependency graph builder.
+ *
+ * Why: Builds and validates expression dependencies before evaluation.
+ */
+import type { RuntimeInstance } from "../runtime/commit.js";
+import type { InstanceId } from "../runtime/instance.js";
+import type { ConstraintExpr } from "./types.js";
+export type ConstraintNodeProp = "width" | "height" | "minWidth" | "maxWidth" | "minHeight" | "maxHeight" | "flexBasis" | "display";
+export type ConstraintNode = Readonly<{
+    key: string;
+    instanceId: InstanceId;
+    parentInstanceId: InstanceId | null;
+    widgetId: string | null;
+    prop: ConstraintNodeProp;
+    expr: ConstraintExpr;
+}>;
+export type CycleError = Readonly<{
+    code: "ZRUI_CIRCULAR_CONSTRAINT";
+    cycle: readonly string[];
+}>;
+export type InvalidConstraintError = Readonly<{
+    code: "ZRUI_INVALID_CONSTRAINT";
+    detail: string;
+}>;
+export type ConstraintGraphError = CycleError | InvalidConstraintError;
+export type ConstraintGraph = Readonly<{
+    nodes: readonly ConstraintNode[];
+    edges: ReadonlyMap<string, readonly string[]>;
+    order: readonly ConstraintNode[];
+    fingerprint: number;
+    requiresCommitRelayout: boolean;
+    hasDisplayConstraints: boolean;
+    constrainedInstanceIds: ReadonlySet<InstanceId>;
+    requiredRuntimeInstanceIds: ReadonlySet<InstanceId>;
+    intrinsicRuntimeInstanceIds: ReadonlySet<InstanceId>;
+    nodeByKey: ReadonlyMap<string, ConstraintNode>;
+    idToInstances: ReadonlyMap<string, readonly InstanceId[]>;
+    siblingIdToInstancesByParentId: ReadonlyMap<InstanceId | null, ReadonlyMap<string, readonly InstanceId[]>>;
+    instanceIdToWidgetId: ReadonlyMap<InstanceId, string>;
+}>;
+export type ConstraintGraphResult = Readonly<{
+    ok: true;
+    value: ConstraintGraph;
+}> | Readonly<{
+    ok: false;
+    fatal: ConstraintGraphError;
+}>;
+export type TopologicalSortResult = Readonly<{
+    ok: true;
+    value: readonly ConstraintNode[];
+}> | Readonly<{
+    ok: false;
+    fatal: CycleError;
+}>;
+export declare function topologicalSort(graph: Readonly<{
+    nodes: readonly ConstraintNode[];
+    edges: ReadonlyMap<string, readonly string[]>;
+    nodeByKey: ReadonlyMap<string, ConstraintNode>;
+}>): TopologicalSortResult;
+export declare function buildConstraintGraph(root: RuntimeInstance): ConstraintGraphResult;
+//# sourceMappingURL=graph.d.ts.map

package/dist/constraints/graph.d.ts.map

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