@sigrun/shared 0.1.2 → 0.2.0

package/dist/blocks/instance.js

@@ -1,51 +0,0 @@
-/**
- * The instance-key helpers the CHANNELS need (UI-blocks U3 Task 5, spec
- * §7.3): `canonicalJson` (the default `instanceKey`) and
- * `eventKeyWeb`/`eventKeyNode` (the wire `k` — sha256 hex of
- * `slug\0id\0key`). The server's copy lives in
- * `src/server/surfaces/instance.ts`; these are the DOM- and Node-safe
- * twins (WebCrypto's `crypto.subtle.digest` vs `node:crypto`), kept
- * byte-compatible by the shared canonical-JSON rule.
- *
- * The wire's purity rule holds: NO node: imports here — the Node flavor
- * is a separate module (`instance-node.ts`) so the webui never sees it.
- */
-/**
- * Canonical JSON: every object serializes with keys SORTED (recursive);
- * primitives and arrays serialize as usual. Two params objects equal up
- * to key order produce byte-identical strings — the same rule as the
- * server's `canonicalJson` (kept in sync by hand; both sides pin it by
- * test).
- */
-export function canonicalJson(value) {
-    if (Array.isArray(value)) {
-        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
-    }
-    if (typeof value === "object" && value !== null) {
-        const keys = Object.keys(value).sort();
-        const parts = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
-        return `{${parts.join(",")}}`;
-    }
-    return JSON.stringify(value);
-}
-/** The default instance key (spec §7.3): canonical JSON of the params. */
-export function instanceKey(params) {
-    return canonicalJson(params);
-}
-/** The hex encoding of a sha256 digest buffer. */
-function hex(buffer) {
-    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
-    let out = "";
-    for (const byte of bytes)
-        out += byte.toString(16).padStart(2, "0");
-    return out;
-}
-/**
- * The wire `k` for one surface instance (spec §7.3), WebCrypto flavor:
- * `sha256(slug + "\0" + id + "\0" + key)` hex. Async (the DOM digest is
- * promise-shaped); the Node twin (`instance-node.ts`) is sync.
- */
-export async function eventKeyWeb(slug, id, key) {
-    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode([slug, id, key].join("\u0000")));
-    return hex(digest);
-}

package/dist/blocks/lttb.d.ts

@@ -1,16 +0,0 @@
-/**
- * Largest-triangle-three-buckets downsampling (UI-blocks spec §5.4):
- * the display-side downsample channels apply to line and area series
- * (at most 2,000 points per series on the wire; a channel shows fewer).
- *
- * Pure: returns a fresh array of fresh tuples; never mutates `points`.
- */
-/**
- * Downsample `points` to at most `threshold` points, always keeping the
- * first and the last point. The interior is bucketed into `threshold -
- * 2` buckets; each bucket keeps the point forming the largest triangle
- * with the previously selected point and the next bucket's average —
- * which preserves visual shape (peaks and troughs) rather than
- * sampling on a fixed interval.
- */
-export declare function lttb(points: readonly (readonly [number, number])[], threshold: number): [number, number][];

package/dist/blocks/lttb.js

@@ -1,67 +0,0 @@
-/**
- * Largest-triangle-three-buckets downsampling (UI-blocks spec §5.4):
- * the display-side downsample channels apply to line and area series
- * (at most 2,000 points per series on the wire; a channel shows fewer).
- *
- * Pure: returns a fresh array of fresh tuples; never mutates `points`.
- */
-/**
- * Downsample `points` to at most `threshold` points, always keeping the
- * first and the last point. The interior is bucketed into `threshold -
- * 2` buckets; each bucket keeps the point forming the largest triangle
- * with the previously selected point and the next bucket's average —
- * which preserves visual shape (peaks and troughs) rather than
- * sampling on a fixed interval.
- */
-export function lttb(points, threshold) {
-    const count = points.length;
-    if (count === 0 || threshold <= 0)
-        return [];
-    if (threshold === 1)
-        return [[points[0][0], points[0][1]]];
-    if (threshold === 2) {
-        return [
-            [points[0][0], points[0][1]],
-            [count === 1 ? points[0][0] : points[count - 1][0],
-                count === 1 ? points[0][1] : points[count - 1][1]],
-        ];
-    }
-    if (threshold >= count) {
-        return points.map((point) => [point[0], point[1]]);
-    }
-    const sampled = [[points[0][0], points[0][1]]];
-    const bucketSize = (count - 2) / (threshold - 2);
-    for (let bucket = 0; bucket < threshold - 2; bucket++) {
-        const start = Math.floor(1 + bucket * bucketSize);
-        const end = Math.min(Math.floor(1 + (bucket + 1) * bucketSize), count - 1);
-        // The average of the NEXT bucket's points — the third corner of
-        // every candidate triangle. The last bucket averages the final
-        // point's window [count-1, count).
-        const nextStart = end;
-        const nextEnd = Math.min(Math.floor(1 + (bucket + 2) * bucketSize), count);
-        let avgX = 0;
-        let avgY = 0;
-        for (let i = nextStart; i < nextEnd; i++) {
-            avgX += points[i][0];
-            avgY += points[i][1];
-        }
-        avgX /= nextEnd - nextStart;
-        avgY /= nextEnd - nextStart;
-        const previous = sampled[sampled.length - 1];
-        let bestArea = -1;
-        let bestIndex = start;
-        for (let i = start; i < end; i++) {
-            // Twice the signed area of the triangle (previous, candidate,
-            // average) — the factor is constant, so abs is enough to rank.
-            const area = Math.abs((previous[0] - avgX) * (points[i][1] - previous[1]) -
-                (previous[0] - points[i][0]) * (avgY - previous[1]));
-            if (area > bestArea) {
-                bestArea = area;
-                bestIndex = i;
-            }
-        }
-        sampled.push([points[bestIndex][0], points[bestIndex][1]]);
-    }
-    sampled.push([points[count - 1][0], points[count - 1][1]]);
-    return sampled;
-}

package/dist/blocks/ops.d.ts

@@ -1,44 +0,0 @@
-/**
- * `applyOps` and `resolvePointer` (UI-blocks spec §4.2/§4.3): the single
- * applier every surface's data updates go through, and the pointer
- * reader bindings resolve with.
- *
- * Purity contract:
- *
- * - `applyOps` NEVER mutates its input — it clones along the touched
- *   path only (copy-on-write), so a batch of ops over a large document
- *   shares every untouched branch by reference with the input. The
- *   property suite pins this (frozen inputs, snapshot equality).
- * - Pointers are RFC 6901 with `~0` (`~`) and `~1` (`/`) escaping, plus
- *   the one extension (spec §4.2): a pointer starting `./` resolves
- *   against the passed `item` (a collection's item template), which
- *   only `resolvePointer` takes — the DATA side never sees `./`.
- * - A failing op throws `DataOpError` carrying the op's INDEX, so the
- *   caller (U3/U5) can treat it as the full-refetch signal (spec §16).
- */
-import type { JsonObject, JsonValue } from "../json.js";
-import type { DataOp } from "./types.js";
-/** An op that could not be applied; `opIndex` names which one failed. */
-export declare class DataOpError extends Error {
-    readonly opIndex: number;
-    constructor(opIndex: number, message: string);
-}
-/**
- * Apply a batch of `DataOp`s (spec §4.3) to `data`, returning a NEW
- * object. Pure: untouched branches are shared by reference with the
- * input; the input is never mutated. Ops apply sequentially — an
- * earlier op's write is visible to the next.
- *
- * Throws `DataOpError` (naming the op's index) on any op whose path
- * does not exist, or whose target is not an array where one is required.
- */
-export declare function applyOps(data: JsonObject, ops: readonly DataOp[]): JsonObject;
-/**
- * Resolve an RFC 6901 `pointer` against `data`; a pointer starting
- * `./` resolves against `item` instead (spec §4.2's one extension,
- * used inside collection item templates). A missing path — including a
- * path THROUGH a JSON null, and a malformed pointer (no `/` or `./`
- * prefix) — is `undefined`, never an error: "a binding to a missing
- * path renders as empty, never as an error".
- */
-export declare function resolvePointer(data: JsonValue, pointer: string, item?: JsonValue): JsonValue | undefined;

package/dist/blocks/ops.js

@@ -1,294 +0,0 @@
-/**
- * `applyOps` and `resolvePointer` (UI-blocks spec §4.2/§4.3): the single
- * applier every surface's data updates go through, and the pointer
- * reader bindings resolve with.
- *
- * Purity contract:
- *
- * - `applyOps` NEVER mutates its input — it clones along the touched
- *   path only (copy-on-write), so a batch of ops over a large document
- *   shares every untouched branch by reference with the input. The
- *   property suite pins this (frozen inputs, snapshot equality).
- * - Pointers are RFC 6901 with `~0` (`~`) and `~1` (`/`) escaping, plus
- *   the one extension (spec §4.2): a pointer starting `./` resolves
- *   against the passed `item` (a collection's item template), which
- *   only `resolvePointer` takes — the DATA side never sees `./`.
- * - A failing op throws `DataOpError` carrying the op's INDEX, so the
- *   caller (U3/U5) can treat it as the full-refetch signal (spec §16).
- */
-/** An op that could not be applied; `opIndex` names which one failed. */
-export class DataOpError extends Error {
-    opIndex;
-    constructor(opIndex, message) {
-        super(message);
-        this.name = "DataOpError";
-        this.opIndex = opIndex;
-    }
-}
-function isContainer(value) {
-    // `typeof null === "object"` — a JSON null is NOT a container; a path
-    // through it is a missing path (undefined), never a walk into it.
-    return Array.isArray(value) || (typeof value === "object" && value !== null);
-}
-/** Split an RFC 6901 pointer into unescaped reference tokens. */
-function pointerTokens(pointer) {
-    if (pointer === "")
-        return [];
-    if (!pointer.startsWith("/")) {
-        throw new Error(`invalid pointer: ${pointer}`);
-    }
-    return pointer
-        .slice(1)
-        .split("/")
-        .map((token) => token.replaceAll("~1", "/").replaceAll("~0", "~"));
-}
-/** Read `token` from a container; `undefined` when absent. */
-function readToken(container, token) {
-    if (Array.isArray(container)) {
-        if (!/^\d+$/.test(token))
-            return undefined;
-        const index = Number(token);
-        return index < container.length ? container[index] : undefined;
-    }
-    return Object.prototype.hasOwnProperty.call(container, token)
-        ? container[token]
-        : undefined;
-}
-/** Parse `key` as an array index valid INSIDE `array` (not for append). */
-function arrayIndex(array, key, pointer) {
-    if (!/^\d+$/.test(key)) {
-        throw new Error(`not an array index: ${pointer}`);
-    }
-    const index = Number(key);
-    if (index >= array.length) {
-        throw new Error(`index out of bounds: ${pointer}`);
-    }
-    return index;
-}
-/** Parse `key` as an array index valid for INSERTION (== length allowed). */
-function insertIndex(array, key, pointer) {
-    if (key === "-")
-        return array.length;
-    if (!/^\d+$/.test(key)) {
-        throw new Error(`not an array index: ${pointer}`);
-    }
-    const index = Number(key);
-    if (index > array.length) {
-        throw new Error(`index out of bounds: ${pointer}`);
-    }
-    return index;
-}
-/**
- * READ-ONLY walk: resolve the tokens before the last and return the
- * parent container plus the final token. Throws when any step is
- * missing or not a container.
- */
-function resolveParent(root, tokens, opIndex, pointer) {
-    let node = root;
-    for (let i = 0; i < tokens.length - 1; i++) {
-        if (!isContainer(node)) {
-            throw new DataOpError(opIndex, `path not found: ${pointer}`);
-        }
-        const next = readToken(node, tokens[i]);
-        if (next === undefined) {
-            throw new DataOpError(opIndex, `path not found: ${pointer}`);
-        }
-        node = next;
-    }
-    if (!isContainer(node)) {
-        throw new DataOpError(opIndex, `path not found: ${pointer}`);
-    }
-    return { parent: node, key: tokens[tokens.length - 1] };
-}
-/**
- * Clone-on-write rewrite: copies every container along `tokens` from
- * `data` down, hands the (fresh, cloned) final container to `mutate`,
- * and returns the new root. The input is never touched; branches off
- * the path are shared by reference with it.
- */
-function withWrite(data, tokens, mutate) {
-    const rootClone = { ...data };
-    let node = rootClone;
-    for (let i = 0; i < tokens.length - 1; i++) {
-        const child = readToken(node, tokens[i]);
-        if (child === undefined || !isContainer(child)) {
-            throw new Error(`path not found: /${tokens.join("/")}`);
-        }
-        const childClone = Array.isArray(child)
-            ? [...child]
-            : { ...child };
-        if (Array.isArray(node)) {
-            node[Number(tokens[i])] = childClone;
-        }
-        else {
-            node[tokens[i]] = childClone;
-        }
-        node = childClone;
-    }
-    mutate(node, tokens[tokens.length - 1]);
-    return rootClone;
-}
-/**
- * Apply a batch of `DataOp`s (spec §4.3) to `data`, returning a NEW
- * object. Pure: untouched branches are shared by reference with the
- * input; the input is never mutated. Ops apply sequentially — an
- * earlier op's write is visible to the next.
- *
- * Throws `DataOpError` (naming the op's index) on any op whose path
- * does not exist, or whose target is not an array where one is required.
- */
-export function applyOps(data, ops) {
-    let current = data;
-    for (let opIndex = 0; opIndex < ops.length; opIndex++) {
-        const op = ops[opIndex];
-        try {
-            current = applyOne(current, op, opIndex);
-        }
-        catch (error) {
-            if (error instanceof DataOpError)
-                throw error;
-            throw new DataOpError(opIndex, `${op.op} ${"path" in op ? op.path : ""}: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    return current;
-}
-function applyOne(data, op, opIndex) {
-    switch (op.op) {
-        case "set":
-            return opSet(data, op.path, op.value, opIndex);
-        case "remove":
-            return opRemove(data, op.path, opIndex);
-        case "insert":
-            return opInsert(data, op.path, op.value, opIndex);
-        case "move":
-            return opMove(data, op.from, op.path, opIndex);
-    }
-}
-/** `set`: assign at `path` (an existing array slot, or a created object member). */
-function opSet(data, path, value, opIndex) {
-    const tokens = pointerTokens(path);
-    if (tokens.length === 0) {
-        throw new DataOpError(opIndex, "set at the root is not allowed");
-    }
-    const { parent, key } = resolveParent(data, tokens, opIndex, path);
-    if (Array.isArray(parent)) {
-        arrayIndex(parent, key, path); // validate before cloning
-    }
-    return withWrite(data, tokens, (container, finalKey) => {
-        if (Array.isArray(container)) {
-            container[arrayIndex(container, finalKey, path)] = value;
-        }
-        else {
-            container[finalKey] = value;
-        }
-    });
-}
-/** `remove`: delete the member at `path` (shifting array elements). */
-function opRemove(data, path, opIndex) {
-    const tokens = pointerTokens(path);
-    if (tokens.length === 0) {
-        throw new DataOpError(opIndex, "remove at the root is not allowed");
-    }
-    const { parent, key } = resolveParent(data, tokens, opIndex, path);
-    if (Array.isArray(parent)) {
-        arrayIndex(parent, key, path); // throws (→ opIndex) when out of bounds
-    }
-    else if (!Object.prototype.hasOwnProperty.call(parent, key)) {
-        throw new DataOpError(opIndex, `path not found: ${path}`);
-    }
-    return withWrite(data, tokens, (container, finalKey) => {
-        if (Array.isArray(container)) {
-            container.splice(arrayIndex(container, finalKey, path), 1);
-        }
-        else {
-            delete container[finalKey];
-        }
-    });
-}
-/** `insert`: insert `value` into the array at `path` (`-` appends). */
-function opInsert(data, path, value, opIndex) {
-    const tokens = pointerTokens(path);
-    if (tokens.length === 0) {
-        throw new DataOpError(opIndex, `not an array: ${path}`);
-    }
-    const { parent } = resolveParent(data, tokens, opIndex, path);
-    if (!Array.isArray(parent)) {
-        throw new DataOpError(opIndex, `not an array: ${path}`);
-    }
-    return withWrite(data, tokens, (container, finalKey) => {
-        if (Array.isArray(container)) {
-            container.splice(insertIndex(container, finalKey, path), 0, value);
-        }
-    });
-}
-/**
- * `move`: remove the item at `from`, then insert it at `path` — a
- * reorder within one array or a move across arrays (spec §4.3: it
- * exists so reorders don't re-send the moved item). Both ends must be
- * array slots; the destination index is resolved against the
- * post-removal array.
- */
-function opMove(data, from, path, opIndex) {
-    const fromTokens = pointerTokens(from);
-    const toTokens = pointerTokens(path);
-    if (fromTokens.length === 0 || toTokens.length === 0) {
-        throw new DataOpError(opIndex, "move at the root is not allowed");
-    }
-    const source = resolveParent(data, fromTokens, opIndex, from);
-    if (!Array.isArray(source.parent)) {
-        throw new DataOpError(opIndex, `not an array: ${from}`);
-    }
-    const value = readToken(source.parent, source.key);
-    if (value === undefined) {
-        throw new DataOpError(opIndex, `path not found: ${from}`);
-    }
-    // Remove first: a move into the same array sees post-removal indices.
-    const removed = withWrite(data, fromTokens, (container, finalKey) => {
-        if (Array.isArray(container)) {
-            container.splice(arrayIndex(container, finalKey, from), 1);
-        }
-    });
-    const to = resolveParent(removed, toTokens, opIndex, path);
-    if (!Array.isArray(to.parent)) {
-        throw new DataOpError(opIndex, `not an array: ${path}`);
-    }
-    return withWrite(removed, toTokens, (container, finalKey) => {
-        if (Array.isArray(container)) {
-            container.splice(insertIndex(container, finalKey, path), 0, value);
-        }
-    });
-}
-/**
- * Resolve an RFC 6901 `pointer` against `data`; a pointer starting
- * `./` resolves against `item` instead (spec §4.2's one extension,
- * used inside collection item templates). A missing path — including a
- * path THROUGH a JSON null, and a malformed pointer (no `/` or `./`
- * prefix) — is `undefined`, never an error: "a binding to a missing
- * path renders as empty, never as an error".
- */
-export function resolvePointer(data, pointer, item) {
-    const base = pointer.startsWith("./") ? item : data;
-    if (base === undefined)
-        return undefined;
-    const rest = pointer.startsWith("./") ? pointer.slice(1) : pointer;
-    let tokens;
-    try {
-        tokens = pointerTokens(rest);
-    }
-    catch {
-        // A malformed binding renders empty — the render contract is
-        // undefined-never-throws (only `applyOps`, the server-side applier,
-        // reports bad pointers, as `DataOpError`).
-        return undefined;
-    }
-    let node = base;
-    for (const token of tokens) {
-        if (!isContainer(node))
-            return undefined;
-        const next = readToken(node, token);
-        if (next === undefined)
-            return undefined;
-        node = next;
-    }
-    return node;
-}

package/dist/blocks/text.d.ts

@@ -1,43 +0,0 @@
-/**
- * `toText` (UI-blocks spec §14.3): the deterministic plain-text
- * projection of a surface — headings, aligned tables, lists with
- * checkboxes and numbers, lanes as sections, charts as one summary
- * line per series. Used for the model's view of its own `show_blocks`
- * call, the default `fallback` text, extension unit tests, logs and
- * notifications.
- *
- * Determinism (spec §14.3): the same input, width and locale give the
- * same bytes, so model context stays cacheable. Three rules make that
- * hold:
- *
- * - object keys are visited in SCHEMA order, never insertion order —
- *   card slots, log lines, tree nodes and table cells are read through
- *   their named props, and anything rendered as JSON goes through
- *   `formatValue`'s sorted-key serializer;
- * - no clock reads in the render path: `TextOptions.timeZone` defaults
- *   to UTC (a datetime projection is stable across hosts; pass a zone
- *   to localize), and only the `relative` format consults `Date.now()`;
- * - unknown blocks render their `fallback`, else
- *   `[unsupported block: <type>]` (§4.4) — never a throw.
- */
-import type { Tree } from "./types.js";
-import type { JsonObject } from "../json.js";
-/** Options for `toText`: the width to wrap at, and the `Intl` locale. */
-export interface TextOptions {
-    /** Wrap target in columns (the §14.3 snapshots use 80 and 160). */
-    width: number;
-    /** BCP-47 locale for every `Intl` format. */
-    locale: string;
-    /**
-     * Time zone for datetime renders. Defaults to UTC inside `toText`
-     * (byte-stable projections across hosts); pass one to localize.
-     */
-    timeZone?: string;
-}
-/**
- * Render `tree` against `data` as plain text (spec §14.3).
- * Deterministic per (input, width, locale): the same arguments give the
- * same bytes. Unknown blocks render their `fallback`, else
- * `[unsupported block: <type>]`.
- */
-export declare function toText(tree: Tree, data: JsonObject, opts: TextOptions): string;