@joewinke/jatui 0.36.3 → 0.38.0

package/dist/artifact-blocks/history.js

@@ -0,0 +1,363 @@
+/**
+ * History scrubber model (mos-p9m3g, living artifacts phase 4).
+ *
+ * "What did this page look like yesterday at 9am?" A blocks page has two
+ * clocks, and the state at any instant is one reading of each:
+ *
+ *   LAYOUT  the artifact_versions row live at that instant (the highest
+ *           version created at or before it);
+ *   DATA    the artifact_data_history snapshot live at that instant (the
+ *           newest recorded at or before it — migration 20272490000210
+ *           captures every change of artifacts.data by trigger).
+ *
+ * This module is PURE (no db, no fetch): the history route resolves an
+ * instant with it on the server, and HistoryScrubber builds its timeline and
+ * diffs with it in the browser.
+ *
+ * Diffs are SHAPE-AWARE but never shape-dependent: a stats-shaped value
+ * (`cards[]` with label + numeric value) diffs as KPI deltas, a table-shaped
+ * value (`rows[]`) diffs as added / removed / changed rows, and anything
+ * else diffs as its changed numeric and text leaves. Data is untrusted: every
+ * reader here tolerates any JSON and caps what it reports.
+ */
+/** Mirrors the trigger's prune rule in drizzle/20272490000210 — keep both in
+ * step. The scrubber names where the trail ends with these. */
+export const HISTORY_RETENTION = {
+    maxSnapshots: 500,
+    maxAgeDays: 30,
+    maxBytes: 32 * 1024 * 1024,
+};
+function toMs(iso) {
+    const ms = Date.parse(iso);
+    return Number.isFinite(ms) ? ms : NaN;
+}
+/**
+ * Merge versions and snapshots into one chronological list (oldest first).
+ * Entries with an unparseable timestamp are dropped — a point the scrubber
+ * cannot place is a point it cannot honestly show. At equal instants a
+ * version sorts before a data change (a republish then a data push in the
+ * same second reads in that order).
+ */
+export function buildTimeline(versions, snapshots) {
+    const points = [];
+    for (const v of versions) {
+        const ms = toMs(v.createdAt);
+        if (Number.isFinite(ms))
+            points.push({ kind: "version", at: v.createdAt, ms, version: v.version });
+    }
+    for (const s of snapshots) {
+        const ms = toMs(s.at);
+        if (Number.isFinite(ms))
+            points.push({ kind: "data", at: s.at, ms, snapshotId: s.id });
+    }
+    return points.sort((a, b) => a.ms - b.ms ||
+        (a.kind === b.kind ? 0 : a.kind === "version" ? -1 : 1) ||
+        (a.version ?? 0) - (b.version ?? 0));
+}
+/**
+ * The page state live at `atMs`: the newest version created at or before it
+ * and the newest snapshot recorded at or before it. Before the first
+ * snapshot, snapshotId is null — the page showed its inline params (or the
+ * trail was pruned; the caller says which via `trailStart`).
+ */
+export function stateAt(versions, snapshots, atMs) {
+    let version = null;
+    let versionMs = -Infinity;
+    for (const v of versions) {
+        const ms = toMs(v.createdAt);
+        if (!(ms <= atMs))
+            continue;
+        if (ms > versionMs || (ms === versionMs && v.version > (version ?? 0))) {
+            version = v.version;
+            versionMs = ms;
+        }
+    }
+    let snap = null;
+    let snapMs = -Infinity;
+    // Snapshots arrive newest-first from the route; equal instants keep the
+    // first seen (the newest by seq).
+    for (const s of snapshots) {
+        const ms = toMs(s.at);
+        if (!(ms <= atMs))
+            continue;
+        if (ms > snapMs) {
+            snap = s;
+            snapMs = ms;
+        }
+    }
+    return {
+        version,
+        snapshotId: snap?.id ?? null,
+        dataAt: snap?.at ?? null,
+    };
+}
+/** The oldest instant the trail can answer for, or null with no snapshots. */
+export function trailStart(snapshots) {
+    let best = null;
+    let bestMs = Infinity;
+    for (const s of snapshots) {
+        const ms = toMs(s.at);
+        if (ms < bestMs) {
+            best = s.at;
+            bestMs = ms;
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// Diffs
+// ---------------------------------------------------------------------------
+/** Most entries any one diff list reports — the rest are counted, not listed. */
+const MAX_DIFF_ENTRIES = 50;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function own(obj, k) {
+    return Object.prototype.hasOwnProperty.call(obj, k) ? obj[k] : undefined;
+}
+/** Order-insensitive structural equality over plain JSON. */
+function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null)
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((el, i) => jsonEqual(el, b[i]));
+    }
+    if (isRecord(a) && isRecord(b)) {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        if (ka.length !== kb.length)
+            return false;
+        return ka.every((k) => own(b, k) !== undefined && jsonEqual(a[k], b[k]));
+    }
+    return false;
+}
+function finite(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function kpiCards(v) {
+    if (!isRecord(v))
+        return null;
+    const cards = own(v, "cards");
+    if (!Array.isArray(cards))
+        return null;
+    const out = new Map();
+    for (const c of cards) {
+        if (!isRecord(c))
+            return null;
+        const label = own(c, "label");
+        if (typeof label !== "string" || !label)
+            return null;
+        if (!out.has(label))
+            out.set(label, finite(own(c, "value")));
+    }
+    return out;
+}
+function diffKpis(then, now) {
+    const labels = [...now.keys(), ...[...then.keys()].filter((l) => !now.has(l))];
+    return labels.slice(0, MAX_DIFF_ENTRIES).map((label) => {
+        const t = then.has(label) ? (then.get(label) ?? null) : null;
+        const n = now.has(label) ? (now.get(label) ?? null) : null;
+        const delta = t !== null && n !== null ? n - t : null;
+        const pct = delta !== null && t !== null && t !== 0 ? delta / Math.abs(t) : null;
+        return { label, then: t, now: n, delta, pct };
+    });
+}
+/** Preferred identity columns for a table row, in order. */
+const ROW_KEY_CANDIDATES = ["id", "key", "slug", "name", "label", "title"];
+function tableRows(v) {
+    if (!isRecord(v))
+        return null;
+    const rows = own(v, "rows");
+    if (!Array.isArray(rows) || !rows.every(isRecord))
+        return null;
+    const cols = own(v, "columns");
+    const columns = Array.isArray(cols)
+        ? cols
+            .map((c) => (isRecord(c) ? own(c, "key") : undefined))
+            .filter((k) => typeof k === "string")
+        : [];
+    return { rows: rows, columns };
+}
+/** The column that identifies a row across both sides: the first candidate
+ * (then the first declared column) whose values are present and unique on
+ * BOTH sides. Null → rows are matched by position. */
+function rowKeyColumn(a, b, columns) {
+    const unique = (rows, col) => {
+        const seen = new Set();
+        for (const r of rows) {
+            const v = own(r, col);
+            if (typeof v !== "string" && typeof v !== "number")
+                return false;
+            const s = String(v);
+            if (seen.has(s))
+                return false;
+            seen.add(s);
+        }
+        return true;
+    };
+    for (const col of [...ROW_KEY_CANDIDATES, ...columns.slice(0, 1)]) {
+        if (unique(a, col) && unique(b, col))
+            return col;
+    }
+    return null;
+}
+function diffTable(then, now) {
+    const columns = now.columns.length ? now.columns : then.columns;
+    const col = rowKeyColumn(then.rows, now.rows, columns);
+    const keyOf = (r, i) => col ? String(own(r, col)) : `#${i + 1}`;
+    const thenMap = new Map(then.rows.map((r, i) => [keyOf(r, i), r]));
+    const nowMap = new Map(now.rows.map((r, i) => [keyOf(r, i), r]));
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const [k, r] of nowMap) {
+        const old = thenMap.get(k);
+        if (!old) {
+            added.push({ key: k, fields: [] });
+            continue;
+        }
+        const fields = [
+            ...new Set([...Object.keys(old), ...Object.keys(r)]),
+        ].filter((f) => !jsonEqual(own(old, f), own(r, f)));
+        if (fields.length)
+            changed.push({ key: k, fields });
+    }
+    for (const k of thenMap.keys()) {
+        if (!nowMap.has(k))
+            removed.push({ key: k, fields: [] });
+    }
+    const total = added.length + removed.length + changed.length;
+    let budget = MAX_DIFF_ENTRIES;
+    const take = (list) => {
+        const out = list.slice(0, Math.max(0, budget));
+        budget -= out.length;
+        return out;
+    };
+    return {
+        added: take(added),
+        removed: take(removed),
+        changed: take(changed),
+        truncated: Math.max(0, total - MAX_DIFF_ENTRIES),
+    };
+}
+function leaves(v, path, out, depth = 0) {
+    if (out.size > 2000 || depth > 12)
+        return;
+    if (v === null || ["string", "number", "boolean"].includes(typeof v)) {
+        out.set(path || "$", v);
+    }
+    else if (Array.isArray(v)) {
+        v.forEach((el, i) => leaves(el, `${path}[${i}]`, out, depth + 1));
+    }
+    else if (isRecord(v)) {
+        for (const k of Object.keys(v))
+            leaves(v[k], path ? `${path}.${k}` : k, out, depth + 1);
+    }
+}
+function diffLeaves(then, now) {
+    const a = new Map();
+    const b = new Map();
+    leaves(then, "", a);
+    leaves(now, "", b);
+    const all = [];
+    for (const p of new Set([...b.keys(), ...a.keys()])) {
+        const t = a.get(p);
+        const n = b.get(p);
+        if (t === n)
+            continue;
+        const tn = finite(t);
+        const nn = finite(n);
+        all.push({
+            path: p,
+            then: t,
+            now: n,
+            delta: tn !== null && nn !== null ? nn - tn : null,
+        });
+    }
+    return {
+        leaves: all.slice(0, MAX_DIFF_ENTRIES),
+        truncated: Math.max(0, all.length - MAX_DIFF_ENTRIES),
+    };
+}
+/**
+ * Diff two live-data blobs key by key (`then` → `now`). Keys are reported in
+ * `now`'s order, then keys only `then` had. A non-object side reads as {}.
+ */
+export function diffData(then, now) {
+    const a = isRecord(then) ? then : {};
+    const b = isRecord(now) ? now : {};
+    const keys = [
+        ...Object.keys(b),
+        ...Object.keys(a).filter((k) => own(b, k) === undefined),
+    ];
+    const out = [];
+    for (const key of keys) {
+        const t = own(a, key);
+        const n = own(b, key);
+        if (t === undefined) {
+            out.push({ key, status: "added" });
+        }
+        else if (n === undefined) {
+            out.push({ key, status: "removed" });
+        }
+        else if (jsonEqual(t, n)) {
+            out.push({ key, status: "same" });
+        }
+        else {
+            const kt = kpiCards(t);
+            const kn = kpiCards(n);
+            const tt = tableRows(t);
+            const tn = tableRows(n);
+            if (kt && kn) {
+                out.push({
+                    key,
+                    status: "changed",
+                    shape: "kpi",
+                    kpis: diffKpis(kt, kn),
+                });
+            }
+            else if (tt && tn) {
+                out.push({
+                    key,
+                    status: "changed",
+                    shape: "table",
+                    ...diffTable(tt, tn),
+                });
+            }
+            else {
+                out.push({
+                    key,
+                    status: "changed",
+                    shape: "value",
+                    ...diffLeaves(t, n),
+                });
+            }
+        }
+    }
+    return {
+        keys: out,
+        changedKeys: out.filter((d) => d.status !== "same").length,
+    };
+}
+/** "+4.2%", "−1,203", "0" — a signed delta for display (U+2212 minus). */
+export function formatDelta(delta, pct = null) {
+    const sign = delta > 0 ? "+" : delta < 0 ? "−" : "";
+    const abs = Math.abs(delta);
+    const num = abs.toLocaleString("en-US", { maximumFractionDigits: 2 });
+    const p = pct === null
+        ? ""
+        : ` (${sign}${Math.abs(pct * 100).toLocaleString("en-US", { maximumFractionDigits: 1 })}%)`;
+    return `${sign}${num}${p}`;
+}
+/** Parse a `?at=` query value: ISO-8601 or epoch ms. NaN when neither. */
+export function parseInstant(raw) {
+    if (raw === null || raw.trim() === "")
+        return NaN;
+    if (/^\d{10,16}$/.test(raw.trim()))
+        return Number(raw.trim());
+    return Date.parse(raw);
+}

package/dist/artifact-blocks/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `jatui/artifact-blocks` — ONE renderer for blocks artifacts, shared by MOS
+ * and the jat IDE (epic jatui-936iz; core jatui-vsuzi).
+ *
+ *   <BlocksArtifactView {artifactId} {version} {title} {summary} {byline}
+ *     {spec} adapter={host} {savedBlocks} {onSaveBlock} … />
+ *
+ * or the renderer alone: `<BlockRenderer {spec} {artifactId} {version}
+ * adapter={host} />`. Everything host-specific is the `HostAdapter`
+ * (types.ts); the contract is CONTRACT.md in this folder.
+ */
+export { default as BlocksArtifactView } from "./BlocksArtifactView.svelte";
+export { default as BlockRenderer } from "./BlockRenderer.svelte";
+export { default as BlockVerdict } from "./BlockVerdict.svelte";
+export { default as BlockComments } from "./BlockComments.svelte";
+export { default as CommentPill } from "./CommentPill.svelte";
+export { default as SectionTools } from "./SectionTools.svelte";
+export { default as FoldedRounds } from "./FoldedRounds.svelte";
+export { default as HistoryScrubber } from "./HistoryScrubber.svelte";
+export { default as Markdown } from "./Markdown.svelte";
+export { default as NoteComposer } from "./NoteComposer.svelte";
+export { default as PlainComposer } from "./PlainComposer.svelte";
+export { default as AttachmentChip } from "./AttachmentChip.svelte";
+export { registerBlocks, blockDef, allBlockDefs, validateBlocksSpec, } from "./registry.js";
+export { BUILTIN_BLOCKS, PENDING_BLOCK_TYPES, BLOCK_GROUPS } from "./builtins.js";
+export { default as markdownBlock } from "./blocks/markdown/block.js";
+export { markdownSchema, type MarkdownParams } from "./blocks/markdown/schema.js";
+export { urlSchema, optionalUrlSchema, linkUrlSchema, isSafeLinkUrl, isSafeResourceUrl, toneSchema, TONE_TOKENS, shortTextSchema, longTextSchema, isoDateSchema, shortTextList, type ToneToken, } from "./params.js";
+export { normalizeContractBlocks, blockLinkErrors, blockTasksOf, decisionExtras, decisionMetaSchema, decisionSectionsSchema, decisionPrimaryActionSchema, decisionTitleSchema, blockGroupSchema, DECISION_BODY_BUDGET, } from "./contractBlocks.js";
+export { renderBlockMarkdown, renderBlockMarkdownInline, looksLikeMarkdown, } from "./blocks/markdown/render.js";
+export { coerceBlocksSpec, reviewKey, ITEM_REVIEW_BLOCK_TYPES, isItemReviewBlock, isDecisionBlock, takesBlockVerdict, OTHER_ID, decisionCardsOf, verdictsFromBlocks, blockReviewStateOf, reviewItemsOf, BLOCKS_VOCABULARY, wordFor, countReviewUnits, pageReviewProgress, openReviewUnits, itemVerdictsOf, coerceSentAnswer, changedSinceSend, sentAnswerLine, type DecisionCard, type DecisionOption, type ReviewUnitLine, type ReviewUnitCounts, type ReviewProgressProps, type PageReviewProgress, type OpenReviewUnit, type ChangedSinceSend, } from "./review.js";
+export { resolveBlockParams, formatDataAge, normalizeDataPublish, serializedBytes, MAX_DATA_BYTES, type DataPublishMode, type ResolvedBlockParams, } from "./liveData.js";
+export { createLiveDataPoller, dataAgeLine, dataAgeTitle, type LiveDataPoller, } from "./liveDataPoller.js";
+export * from "./history.js";
+export { createOpenNav, revealUnit, type JumpUnit } from "./openNav.js";
+export { createPageReviewKeys, isPageChromeTarget } from "./pageReviewKeys.js";
+export { AUTO_SEND_DELAY_MS, createAutoSend } from "./autoSend.js";
+export { provideHostAdapter, hostAdapter, hostServices, HOST_ADAPTER_KEY, } from "./adapter.js";
+export { provideBlockListen, blockListen, BLOCK_LISTEN_KEY, type BlockListenContext, } from "./listen/context.js";
+export type * from "./types.js";

package/dist/artifact-blocks/index.js

@@ -0,0 +1,46 @@
+/**
+ * `jatui/artifact-blocks` — ONE renderer for blocks artifacts, shared by MOS
+ * and the jat IDE (epic jatui-936iz; core jatui-vsuzi).
+ *
+ *   <BlocksArtifactView {artifactId} {version} {title} {summary} {byline}
+ *     {spec} adapter={host} {savedBlocks} {onSaveBlock} … />
+ *
+ * or the renderer alone: `<BlockRenderer {spec} {artifactId} {version}
+ * adapter={host} />`. Everything host-specific is the `HostAdapter`
+ * (types.ts); the contract is CONTRACT.md in this folder.
+ */
+// Views
+export { default as BlocksArtifactView } from "./BlocksArtifactView.svelte";
+export { default as BlockRenderer } from "./BlockRenderer.svelte";
+export { default as BlockVerdict } from "./BlockVerdict.svelte";
+export { default as BlockComments } from "./BlockComments.svelte";
+export { default as CommentPill } from "./CommentPill.svelte";
+export { default as SectionTools } from "./SectionTools.svelte";
+export { default as FoldedRounds } from "./FoldedRounds.svelte";
+export { default as HistoryScrubber } from "./HistoryScrubber.svelte";
+export { default as Markdown } from "./Markdown.svelte";
+export { default as NoteComposer } from "./NoteComposer.svelte";
+export { default as PlainComposer } from "./PlainComposer.svelte";
+export { default as AttachmentChip } from "./AttachmentChip.svelte";
+// Catalog
+export { registerBlocks, blockDef, allBlockDefs, validateBlocksSpec, } from "./registry.js";
+export { BUILTIN_BLOCKS, PENDING_BLOCK_TYPES, BLOCK_GROUPS } from "./builtins.js";
+export { default as markdownBlock } from "./blocks/markdown/block.js";
+export { markdownSchema } from "./blocks/markdown/schema.js";
+// Params + the provider contract
+export { urlSchema, optionalUrlSchema, linkUrlSchema, isSafeLinkUrl, isSafeResourceUrl, toneSchema, TONE_TOKENS, shortTextSchema, longTextSchema, isoDateSchema, shortTextList, } from "./params.js";
+export { normalizeContractBlocks, blockLinkErrors, blockTasksOf, decisionExtras, decisionMetaSchema, decisionSectionsSchema, decisionPrimaryActionSchema, decisionTitleSchema, blockGroupSchema, DECISION_BODY_BUDGET, } from "./contractBlocks.js";
+// Markdown
+export { renderBlockMarkdown, renderBlockMarkdownInline, looksLikeMarkdown, } from "./blocks/markdown/render.js";
+// Review math
+export { coerceBlocksSpec, reviewKey, ITEM_REVIEW_BLOCK_TYPES, isItemReviewBlock, isDecisionBlock, takesBlockVerdict, OTHER_ID, decisionCardsOf, verdictsFromBlocks, blockReviewStateOf, reviewItemsOf, BLOCKS_VOCABULARY, wordFor, countReviewUnits, pageReviewProgress, openReviewUnits, itemVerdictsOf, coerceSentAnswer, changedSinceSend, sentAnswerLine, } from "./review.js";
+// Live data, history, navigation, keys
+export { resolveBlockParams, formatDataAge, normalizeDataPublish, serializedBytes, MAX_DATA_BYTES, } from "./liveData.js";
+export { createLiveDataPoller, dataAgeLine, dataAgeTitle, } from "./liveDataPoller.js";
+export * from "./history.js";
+export { createOpenNav, revealUnit } from "./openNav.js";
+export { createPageReviewKeys, isPageChromeTarget } from "./pageReviewKeys.js";
+export { AUTO_SEND_DELAY_MS, createAutoSend } from "./autoSend.js";
+// Host wiring
+export { provideHostAdapter, hostAdapter, hostServices, HOST_ADAPTER_KEY, } from "./adapter.js";
+export { provideBlockListen, blockListen, BLOCK_LISTEN_KEY, } from "./listen/context.js";

package/dist/artifact-blocks/listen/context.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Artifact blocks — the Listen context (origin mos-8vdg9; jatui-vsuzi).
+ *
+ * A block's own Listen control must know WHICH surface its segments live in,
+ * but blocks are generic components: the host owns that. In jatui the host
+ * hands its Listen control over as a snippet — `HostAdapter.listen` — which
+ * SectionTools renders with the block's coordinates ({ group, label,
+ * anchor }). jatui's own ListenControl fits inside it; MOS keeps its
+ * coordinate-based player.
+ *
+ * The adapter's `listen` is the default source; a host that wants Listen
+ * for only PART of a page (or a test mounting one block) can override it
+ * below any point with provideBlockListen(). Neither → no Listen control
+ * (share link, print).
+ */
+import { type Snippet } from "svelte";
+import type { BlockListenArgs } from "../types.js";
+export interface BlockListenContext {
+    /** Renders the host's Listen control for one block; null = none here. */
+    render: Snippet<[BlockListenArgs]> | null;
+}
+/**
+ * The context key itself, exported for tests that mount a block directly
+ * (mount(Component, { context: new Map([[BLOCK_LISTEN_KEY, …]]) })).
+ */
+export declare const BLOCK_LISTEN_KEY: symbol;
+/** Host-side: publish the Listen renderer to every block below. */
+export declare function provideBlockListen(ctx: BlockListenContext): void;
+/** Block-side: the Listen renderer, or null when this host offers none. */
+export declare function blockListen(): BlockListenContext | null;

package/dist/artifact-blocks/listen/context.js

@@ -0,0 +1,30 @@
+/**
+ * Artifact blocks — the Listen context (origin mos-8vdg9; jatui-vsuzi).
+ *
+ * A block's own Listen control must know WHICH surface its segments live in,
+ * but blocks are generic components: the host owns that. In jatui the host
+ * hands its Listen control over as a snippet — `HostAdapter.listen` — which
+ * SectionTools renders with the block's coordinates ({ group, label,
+ * anchor }). jatui's own ListenControl fits inside it; MOS keeps its
+ * coordinate-based player.
+ *
+ * The adapter's `listen` is the default source; a host that wants Listen
+ * for only PART of a page (or a test mounting one block) can override it
+ * below any point with provideBlockListen(). Neither → no Listen control
+ * (share link, print).
+ */
+import { getContext, setContext } from "svelte";
+const KEY = Symbol("artifact-blocks-listen");
+/**
+ * The context key itself, exported for tests that mount a block directly
+ * (mount(Component, { context: new Map([[BLOCK_LISTEN_KEY, …]]) })).
+ */
+export const BLOCK_LISTEN_KEY = KEY;
+/** Host-side: publish the Listen renderer to every block below. */
+export function provideBlockListen(ctx) {
+    setContext(KEY, ctx);
+}
+/** Block-side: the Listen renderer, or null when this host offers none. */
+export function blockListen() {
+    return getContext(KEY) ?? null;
+}

package/dist/artifact-blocks/liveData.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Live data for blocks artifacts (origin mos-0ninw, phase 3 of MOS epic
+ * mos-m1qrx).
+ *
+ * A blocks page publishes LAYOUT once; its NUMBERS move without a
+ * republish. The host keeps a per-artifact key→value data map (MOS:
+ * `artifacts.data`, `mos-artifact data`) — version-independent, so a cron
+ * or generator can refresh a dashboard while its layout stays put.
+ *
+ * The binding, on the HOST side (BlockRenderer):
+ *
+ *   - a block whose def declares `dataParam: "dataKey"` and whose params
+ *     set that key (e.g. `dataKey: "soak"`) renders from `data.soak`
+ *     INSTEAD of its inline params, once a value exists for that key;
+ *   - before the first data publish (or with the key absent), the block
+ *     renders its inline params — a fresh page is never blank, and a
+ *     publisher can push data at their own pace;
+ *   - the live value REPLACES the params object wholesale, then goes
+ *     through the same zod schema as publish-time params. Data is as
+ *     untrusted as params are: a value that fails the schema renders the
+ *     block's error card naming the dataKey — never a silent fallback to
+ *     stale inline numbers.
+ *
+ * This module is PURE (no db import): BlockRenderer renders it into the
+ * browser, a host's service and routes import it on the server. Storage is
+ * the host's.
+ */
+import type { ArtifactBlockDef } from "./types";
+/**
+ * Largest serialized artifacts.data accepted after a write. Generous for a
+ * real dashboard (thousands of table rows), small enough that a runaway
+ * generator cannot balloon a page's poll payload. The service enforces it
+ * inside the UPDATE itself — a write that would exceed the cap changes
+ * NOTHING (no partial merge, no data_updated_at bump).
+ */
+export declare const MAX_DATA_BYTES: number;
+export declare function serializedBytes(v: unknown): number;
+export type DataPublishMode = "merge" | "key" | "replace";
+interface NormalizedDataPublish {
+    mode: DataPublishMode;
+    key: string | null;
+    /** The value to store: the whole blob (merge/replace) or the key's value. */
+    value: unknown;
+}
+/**
+ * Validate + normalize a data publish. Throws with a message an agent can
+ * act on; the route turns that into a 400. `undefined` incoming data is a
+ * programmer error (the body always parses to something) and is refused like
+ * any other invalid input.
+ */
+export declare function normalizeDataPublish(input: {
+    data: unknown;
+    key?: unknown;
+    replace?: unknown;
+}): NormalizedDataPublish;
+export interface ResolvedBlockParams {
+    /** What the block renders: the live value when one exists, else inline. */
+    params: unknown;
+    /** The dataKey the block ASKED for (null when it did not opt in). */
+    dataKey: string | null;
+    /** True when the rendered params ARE the live value. */
+    fromData: boolean;
+}
+/**
+ * The dataParam binding. `def.dataParam` names the params field holding the
+ * data key; when that field names a key WITH a published value, the live
+ * value replaces the params wholesale. Everything else renders inline:
+ * no opt-in, no published value, or a key that exists only on the prototype
+ * chain (hasOwn guard).
+ */
+export declare function resolveBlockParams(def: Pick<ArtifactBlockDef, "dataParam"> | undefined, rawParams: unknown, data: Record<string, unknown>): ResolvedBlockParams;
+/**
+ * The subtle freshness line: "just now" → "42s ago" → "2m ago" → "3h ago" →
+ * "5d ago". Empty string when there is no data yet (the line does not render
+ * at all).
+ */
+export declare function formatDataAge(updatedAt: string | number | Date | null | undefined, now: number | Date): string;
+export {};