@buoy-gg/shared-ui 7.0.40 → 7.0.42

package/lib/module/sync/valuePath.js

@@ -1,330 +1 @@
-"use strict";
-
-/**
- * Addressing a single value inside cached data or a store — one implementation,
- * shared by every adapter that reads or merges.
- *
- * WHY. The most common measured write failure is not a wrong value, it is a
- * wrong DEPTH: ten of eleven `query` failures on the bench sent `{name: "x"}`
- * for a payload shaped `{item: {name}}`. That is not a missing instruction — the
- * system prompt says, verbatim, "if the value is {item:{name}} send
- * {"item":{"name":"test123"}}, never {name}" — and models that had just called
- * `getQueryData` still flattened it. The rule is being read past, not missed.
- *
- * So stop asking. `path: "item.name", value: "x"` has no depth to get wrong:
- * there is exactly one way to write it and the adapter builds the nested patch.
- * The same syntax on the READ side returns one slice instead of a payload that
- * gets cut off at the engine's 24,000-character cap, which is the other half of
- * the same problem — a caller cannot write a shape it was never able to see.
- *
- * Lists are addressed by IDENTITY, never by position. `lines[0]` is resolved to
- * the id of whatever is at index 0 right now and rewritten as an id-addressed
- * edit, because between the read and the write an item may have been removed and
- * index 0 is then a different row. A list whose items carry no stable id is
- * refused rather than guessed at — see keyedArrays.ts for why silently picking a
- * row is the failure mode that loses data.
- */
-import { identityField } from "./keyedArrays.js";
-const isPlainObject = v => typeof v === "object" && v !== null && !Array.isArray(v);
-/**
- * Where a field of this name actually lives, as a dotted path — breadth-first,
- * capped so a big payload cannot stall the walk.
- *
- * A wrong `path` is not the same mistake as a wrong depth, and `path` does not
- * prevent it. Measured on TWO cases in one run: grok wrote
- * `path: "item.name"` against the flat PokéAPI payload `{name, id, stats, …}`,
- * having generalised the shape from a different screen it had seen. The value it
- * wanted was at `name`, one segment, right there. A refusal that says so is a
- * one-turn recovery; a refusal that only lists the available fields makes the
- * caller re-derive it.
- */
-function findFieldPath(obj, key, maxNodes = 2000) {
-  const queue = [{
-    node: obj,
-    path: ""
-  }];
-  let seen = 0;
-  while (queue.length && seen < maxNodes) {
-    const {
-      node,
-      path
-    } = queue.shift();
-    seen++;
-    if (Array.isArray(node)) {
-      node.slice(0, 20).forEach((v, i) => queue.push({
-        node: v,
-        path: `${path}[${i}]`
-      }));
-    } else if (isPlainObject(node)) {
-      for (const [k, v] of Object.entries(node)) {
-        const p = path ? `${path}.${k}` : k;
-        if (k === key) return p;
-        if (isPlainObject(v) || Array.isArray(v)) queue.push({
-          node: v,
-          path: p
-        });
-      }
-    }
-  }
-  return undefined;
-}
-
-/**
- * "No field X here" plus, when the field exists somewhere else, the path that
- * would have worked. `leaf` is the segment the caller was ultimately after.
- */
-function missingFieldError(root, at, key, available, leaf) {
-  const elsewhere = findFieldPath(root, leaf ?? key);
-  const has = available.slice(0, 12).join(", ") || "(no fields)";
-  return elsewhere ? `No field "${key}" at "${at}" — did you mean path "${elsewhere}"? "${at}" has: ${has}.` : `No field "${key}" at "${at}". It has: ${has}.`;
-}
-
-/** Read a dotted field path inside one list item. */
-function fieldOf(item, field) {
-  let cur = item;
-  for (const seg of field.split(".")) {
-    if (!isPlainObject(cur)) return undefined;
-    cur = cur[seg];
-  }
-  return cur;
-}
-
-/**
- * `lines[0].addonIds`, `item.name`, `results[name=pikachu].url` → segments.
- *
- * Returns undefined for syntax it does not understand rather than doing
- * something approximate with it.
- */
-export function parsePath(path) {
-  if (!path.trim()) return undefined;
-  const out = [];
-  // Walk the string rather than splitting on ".", because a [field=value]
-  // selector may legitimately contain a dot ("results[url=a.b/c]").
-  let i = 0;
-  while (i < path.length) {
-    if (path[i] === ".") {
-      i++;
-      continue;
-    }
-    if (path[i] === "[") {
-      const end = path.indexOf("]", i);
-      if (end === -1) return undefined;
-      const inner = path.slice(i + 1, end);
-      if (/^\d+$/.test(inner)) out.push({
-        kind: "index",
-        index: Number(inner)
-      });else {
-        const eq = inner.indexOf("=");
-        if (eq <= 0) return undefined;
-        out.push({
-          kind: "match",
-          field: inner.slice(0, eq).trim(),
-          value: inner.slice(eq + 1).trim()
-        });
-      }
-      i = end + 1;
-      continue;
-    }
-    let j = i;
-    while (j < path.length && path[j] !== "." && path[j] !== "[") j++;
-    const key = path.slice(i, j);
-    if (!key) return undefined;
-    out.push({
-      kind: "key",
-      key
-    });
-    i = j;
-  }
-  return out.length ? out : undefined;
-}
-
-/** Read the value at `path`, or undefined if any step of it does not exist. */
-export function readPath(value, path) {
-  const segs = parsePath(path);
-  if (!segs) return {
-    ok: false,
-    error: `Could not read the path "${path}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`
-  };
-  let cur = value;
-  const walked = [];
-  for (const seg of segs) {
-    if (cur === null || cur === undefined) {
-      return {
-        ok: false,
-        error: `"${walked.join(".") || "(root)"}" is ${cur === null ? "null" : "not set"}, so there is nothing at "${path}".`
-      };
-    }
-    if (seg.kind === "key") {
-      if (!isPlainObject(cur)) return {
-        ok: false,
-        error: `"${walked.join(".") || "(root)"}" is not an object, so it has no field "${seg.key}".`
-      };
-      if (!(seg.key in cur)) {
-        const leafSeg = segs[segs.length - 1];
-        return {
-          ok: false,
-          error: missingFieldError(value, walked.join(".") || "(root)", seg.key, Object.keys(cur), leafSeg?.kind === "key" ? leafSeg.key : undefined)
-        };
-      }
-      cur = cur[seg.key];
-      walked.push(seg.key);
-    } else if (seg.kind === "index") {
-      if (!Array.isArray(cur)) return {
-        ok: false,
-        error: `"${walked.join(".") || "(root)"}" is not a list, so [${seg.index}] means nothing.`
-      };
-      cur = cur[seg.index];
-      walked.push(`[${seg.index}]`);
-    } else {
-      if (!Array.isArray(cur)) return {
-        ok: false,
-        error: `"${walked.join(".") || "(root)"}" is not a list, so [${seg.field}=${seg.value}] means nothing.`
-      };
-      const hit = cur.find(el => isPlainObject(el) && String(fieldOf(el, seg.field)) === seg.value);
-      if (hit === undefined) return {
-        ok: false,
-        error: `No item with ${seg.field}="${seg.value}" in "${walked.join(".") || "(root)"}".`
-      };
-      cur = hit;
-      walked.push(`[${seg.field}=${seg.value}]`);
-    }
-  }
-  return {
-    ok: true,
-    value: cur
-  };
-}
-
-/**
- * Build the merge patch that sets `path` to `value`, against the data as it is
- * now.
- *
- * The result is an ordinary merge patch, so it goes through the SAME typed-edit
- * guard as a hand-written one and gains no new powers — `path` is a way to say
- * the same thing without being able to get the depth wrong, not a way around
- * the rules. A list step becomes the id-addressed form, so the write stays
- * proof against a truncated read.
- */
-export function patchFromPath(current, path, value) {
-  const segs = parsePath(path);
-  if (!segs) return {
-    ok: false,
-    error: `Could not read the path "${path}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`
-  };
-  if (segs[0]?.kind !== "key") return {
-    ok: false,
-    error: `A path must start with a field name, not a list index — "${path}" does not say which list.`
-  };
-  const build = (node, at) => {
-    if (at >= segs.length) return {
-      ok: true,
-      patch: value
-    };
-    const seg = segs[at];
-    if (seg.kind === "key") {
-      // A field that does not exist is left for the typed-edit guard, which owns
-      // that decision — EXCEPT when there are more segments to walk, because
-      // then the caller is describing a shape that is not there at all and the
-      // guard's message ("no field named `item`") would not say where the value
-      // it wanted actually lives.
-      if (isPlainObject(node) && !(seg.key in node) && at + 1 < segs.length) {
-        const leafSeg = segs[segs.length - 1];
-        return {
-          ok: false,
-          error: missingFieldError(current, pathUpTo(segs, at), seg.key, Object.keys(node), leafSeg?.kind === "key" ? leafSeg.key : undefined)
-        };
-      }
-      const child = isPlainObject(node) ? node[seg.key] : undefined;
-      const inner = build(child, at + 1);
-      return inner.ok ? {
-        ok: true,
-        patch: {
-          [seg.key]: inner.patch
-        }
-      } : inner;
-    }
-    if (!Array.isArray(node)) {
-      return {
-        ok: false,
-        error: `"${pathUpTo(segs, at)}" is not a list, so "${path}" cannot be resolved. Read it first — \`shape\` on the read says what each field holds.`
-      };
-    }
-    const index = seg.kind === "index" ? seg.index : node.findIndex(el => isPlainObject(el) && String(fieldOf(el, seg.field)) === seg.value);
-    const item = index >= 0 ? node[index] : undefined;
-    const missing = seg.kind === "index" ? index < 0 || index >= node.length : index < 0;
-    if (missing) {
-      return {
-        ok: false,
-        error: seg.kind === "index" ? `"${pathUpTo(segs, at)}" has ${node.length} item(s), so there is nothing at [${seg.index}].` : `No item with ${seg.field}="${seg.value}" in "${pathUpTo(segs, at)}".`
-      };
-    }
-    /**
-     * A list of PRIMITIVES, addressed by index — `tags[0]` on
-     * `["alpha","beta"]`.
-     *
-     * The guard below used to be `!isPlainObject(item)`, which folded this in
-     * with a genuinely out-of-range index and answered `"tags" has 2 item(s),
-     * so there is nothing at [0]` — a sentence that contradicts itself, for the
-     * commonest index there is. A model reading the data, seeing two items and
-     * being told [0] and [1] are both empty has nowhere left to go.
-     *
-     * There is nothing to descend into on a string, so the index IS the leaf:
-     * rebuild the list with that one element replaced, exactly as the no-stable-id
-     * branch below does. Anything deeper genuinely cannot be resolved, and says so.
-     */
-    if (!isPlainObject(item)) {
-      if (at < segs.length - 1) {
-        return {
-          ok: false,
-          error: `"${pathUpTo(segs, at)}[${seg.kind === "index" ? seg.index : `${seg.field}=${seg.value}`}]" holds ${item === null ? "null" : typeof item}, not an object, so "${path}" cannot go any deeper. Set the item itself.`
-        };
-      }
-      const replaced = node.slice();
-      replaced[index] = value;
-      return {
-        ok: true,
-        patch: replaced
-      };
-    }
-    const inner = build(item, at + 1);
-    if (!inner.ok) return inner;
-    const idField = identityField(node);
-    // Positions move; ids do not. Prefer the addressed form whichever way the
-    // caller named the row.
-    if (idField) return {
-      ok: true,
-      patch: {
-        [String(item[idField])]: inner.patch
-      }
-    };
-
-    // No stable id — a Pokémon's `stats` are `{stat: {name}, base_stat}`, with
-    // nothing flat and unique on the item itself, and that is an ordinary shape
-    // rather than a broken one. Rebuild the whole list here instead of refusing.
-    //
-    // This is safe in a way the SAME array coming from a model is not: we are
-    // holding the current list in memory, so nothing is being reconstructed from
-    // a truncated read and no row can be dropped by omission. The caller still
-    // only named one value. What it cannot be is proof against the list changing
-    // between this call and the write, which addressing by id would be — so the
-    // id form stays preferred wherever one exists.
-    const next = node.slice();
-    next[index] = isPlainObject(inner.patch) ? {
-      ...item,
-      ...inner.patch
-    } : inner.patch;
-    return {
-      ok: true,
-      patch: next
-    };
-  };
-  const built = build(current, 0);
-  if (!built.ok) return built;
-  return {
-    ok: true,
-    patch: built.patch
-  };
-}
-function pathUpTo(segs, at) {
-  return segs.slice(0, at).map(s => s.kind === "key" ? s.key : s.kind === "index" ? `[${s.index}]` : `[${s.field}=${s.value}]`).join(".").replace(/\.\[/g, "[") || "(root)";
-}
+"use strict";import{identityField as A}from"./keyedArrays.js";const u=r=>typeof r==="object"&&r!==null&&!Array.isArray(r);function w(r,o,n=2e3){const e=[{node:r,path:""}];let d=0;while(e.length&&d<n){const{node:i,path:t}=e.shift();d++;if(Array.isArray(i)){i.slice(0,20).forEach((s,l)=>e.push({node:s,path:`${t}[${l}]`}))}else if(u(i)){for(const[s,l]of Object.entries(i)){const f=t?`${t}.${s}`:s;if(s===o)return f;if(u(l)||Array.isArray(l))e.push({node:l,path:f})}}}return void 0}function m(r,o,n,e,d){const i=w(r,d??n);const t=e.slice(0,12).join(", ")||"(no fields)";return i?`No field "${n}" at "${o}" \u2014 did you mean path "${i}"? "${o}" has: ${t}.`:`No field "${n}" at "${o}". It has: ${t}.`}function x(r,o){let n=r;for(const e of o.split(".")){if(!u(n))return void 0;n=n[e]}return n}export function parsePath(r){if(!r.trim())return void 0;const o=[];let n=0;while(n<r.length){if(r[n]==="."){n++;continue}if(r[n]==="["){const i=r.indexOf("]",n);if(i===-1)return void 0;const t=r.slice(n+1,i);if(/^\d+$/.test(t))o.push({kind:"index",index:Number(t)});else{const s=t.indexOf("=");if(s<=0)return void 0;o.push({kind:"match",field:t.slice(0,s).trim(),value:t.slice(s+1).trim()})}n=i+1;continue}let e=n;while(e<r.length&&r[e]!=="."&&r[e]!=="[")e++;const d=r.slice(n,e);if(!d)return void 0;o.push({kind:"key",key:d});n=e}return o.length?o:void 0}export function readPath(r,o){const n=parsePath(o);if(!n)return{ok:false,error:`Could not read the path "${o}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`};let e=r;const d=[];for(const i of n){if(e===null||e===void 0){return{ok:false,error:`"${d.join(".")||"(root)"}" is ${e===null?"null":"not set"}, so there is nothing at "${o}".`}}if(i.kind==="key"){if(!u(e))return{ok:false,error:`"${d.join(".")||"(root)"}" is not an object, so it has no field "${i.key}".`};if(!(i.key in e)){const t=n[n.length-1];return{ok:false,error:m(r,d.join(".")||"(root)",i.key,Object.keys(e),t?.kind==="key"?t.key:void 0)}}e=e[i.key];d.push(i.key)}else if(i.kind==="index"){if(!Array.isArray(e))return{ok:false,error:`"${d.join(".")||"(root)"}" is not a list, so [${i.index}] means nothing.`};e=e[i.index];d.push(`[${i.index}]`)}else{if(!Array.isArray(e))return{ok:false,error:`"${d.join(".")||"(root)"}" is not a list, so [${i.field}=${i.value}] means nothing.`};const t=e.find(s=>u(s)&&String(x(s,i.field))===i.value);if(t===void 0)return{ok:false,error:`No item with ${i.field}="${i.value}" in "${d.join(".")||"(root)"}".`};e=t;d.push(`[${i.field}=${i.value}]`)}}return{ok:true,value:e}}export function patchFromPath(r,o,n){const e=parsePath(o);if(!e)return{ok:false,error:`Could not read the path "${o}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`};if(e[0]?.kind!=="key")return{ok:false,error:`A path must start with a field name, not a list index \u2014 "${o}" does not say which list.`};const d=(t,s)=>{if(s>=e.length)return{ok:true,patch:n};const l=e[s];if(l.kind==="key"){if(u(t)&&!(l.key in t)&&s+1<e.length){const g=e[e.length-1];return{ok:false,error:m(r,k(e,s),l.key,Object.keys(t),g?.kind==="key"?g.key:void 0)}}const a=u(t)?t[l.key]:void 0;const $=d(a,s+1);return $.ok?{ok:true,patch:{[l.key]:$.patch}}:$}if(!Array.isArray(t)){return{ok:false,error:`"${k(e,s)}" is not a list, so "${o}" cannot be resolved. Read it first \u2014 \`shape\` on the read says what each field holds.`}}const f=l.kind==="index"?l.index:t.findIndex(a=>u(a)&&String(x(a,l.field))===l.value);const c=f>=0?t[f]:void 0;const j=l.kind==="index"?f<0||f>=t.length:f<0;if(j){return{ok:false,error:l.kind==="index"?`"${k(e,s)}" has ${t.length} item(s), so there is nothing at [${l.index}].`:`No item with ${l.field}="${l.value}" in "${k(e,s)}".`}}if(!u(c)){if(s<e.length-1){return{ok:false,error:`"${k(e,s)}[${l.kind==="index"?l.index:`${l.field}=${l.value}`}]" holds ${c===null?"null":typeof c}, not an object, so "${o}" cannot go any deeper. Set the item itself.`}}const a=t.slice();a[f]=n;return{ok:true,patch:a}}const h=d(c,s+1);if(!h.ok)return h;const y=A(t);if(y)return{ok:true,patch:{[String(c[y])]:h.patch}};const p=t.slice();p[f]=u(h.patch)?{...c,...h.patch}:h.patch;return{ok:true,patch:p}};const i=d(r,0);if(!i.ok)return i;return{ok:true,patch:i.patch}}function k(r,o){return r.slice(0,o).map(n=>n.kind==="key"?n.key:n.kind==="index"?`[${n.index}]`:`[${n.field}=${n.value}]`).join(".").replace(/\.\[/g,"[")||"(root)"}

package/lib/module/sync/valueShape.js

@@ -1,153 +1 @@
-"use strict";
-
-/**
- * A compact type sketch of a runtime value — one implementation, shared by every
- * adapter that hands data to a model.
- *
- * WHY. A model cannot write a well-formed item into a list it has never seen the
- * shape of, and we were not showing it. Measured on `cart/bag-still-zustand`: the
- * rendered prompt is 83,000 characters and the words `lineId`, `itemId`,
- * `sizeId`, `addonIds` and `unitPrice` appear in it ZERO times. Every model
- * "failing" that case invented a line shape because inventing was the only move
- * available. The zustand typed-edit guard would have caught the invention — but
- * only on a list that already holds an item, since it builds its template from
- * `list[0]`. On an EMPTY list there is no template, the guard has nothing to
- * compare against, and the invented shape is written silently.
- *
- * So the sketch has two jobs, and the second is the one that pays:
- *
- *   1. Say what the items in a list look like, so an addition can match.
- *   2. Say when NOTHING knows — an empty list's item shape is not merely
- *      unread, it is unknowable from runtime state, and the honest answer is to
- *      admit that rather than let a guess through unremarked.
- *
- * It is deliberately tiny. A sketch of a 120-line bag is the same size as a
- * sketch of a 2-line one, so unlike the data it survives the engine's 24,000-
- * character result cap — which is the whole point, because the cases where the
- * model most needs the shape are exactly the ones where the data got cut off.
- */
-
-const isPlainObject = v => typeof v === "object" && v !== null && !Array.isArray(v);
-
-/** Beyond this the sketch stops being cheaper to read than the data. */
-const MAX_DEPTH = 3;
-const MAX_KEYS = 24;
-/**
- * Hard caps on `listShapes`. MAX_DEPTH bounds how DEEP it goes; nothing bounded
- * how WIDE it went, and it walks every entry of every object at each permitted
- * level. A store holding a few hundred keyed records therefore produced a
- * "compact" sketch larger than the data it was standing in for — in a value
- * that rides in every prompt. Depth is not a size budget.
- */
-const MAX_LIST_PATHS = 40;
-const MAX_ENTRIES_VISITED = 600;
-
-/**
- * `{lineId: string, qty: number, addonIds: string[]}` — a one-line type for a
- * value, built from the value itself.
- *
- * An array is described by its FIRST item, because a list whose items disagree
- * is a list nothing can safely add to and the guard will say so anyway. An empty
- * array is `unknown[]`, which is the true answer and the one that matters: it
- * tells a reader that adding to this list is unchecked.
- */
-export function shapeOf(value, depth = 0) {
-  if (value === null) return "null";
-  if (Array.isArray(value)) {
-    if (!value.length) return "unknown[]";
-    if (depth >= MAX_DEPTH) return "…[]";
-    const inner = shapeOf(value[0], depth + 1);
-    return inner.includes(" ") || inner.endsWith("]") ? `(${inner})[]` : `${inner}[]`;
-  }
-  if (isPlainObject(value)) {
-    if (depth >= MAX_DEPTH) return "{…}";
-    const keys = Object.keys(value);
-    const shown = keys.slice(0, MAX_KEYS);
-    const body = shown.map(k => `${k}: ${shapeOf(value[k], depth + 1)}`).join(", ");
-    const more = keys.length > shown.length ? `, +${keys.length - shown.length} more` : "";
-    return `{${body}${more}}`;
-  }
-  const t = typeof value;
-  return t === "undefined" ? "undefined" : t === "function" ? "function" : t;
-}
-/**
- * Every list inside a value, with the shape of what goes in it.
- *
- * This is what a caller needs before adding to a list, and it is the part that
- * cannot be recovered from a truncated read of the data itself.
- *
- * A list with `item: undefined` is the warning case: it is empty, so its item
- * shape exists nowhere in the running app — not in the store, not in the
- * persisted copy, not in this sketch. Anything added to it goes in unchecked.
- */
-export function listShapes(value, path = "", out = [], depth = 0, budget = {
-  visited: 0
-}) {
-  if (depth > MAX_DEPTH) return out;
-  // Two independent stops: enough lists described, or enough of the value
-  // walked. The second is what a wide-but-shallow store hits.
-  if (out.length >= MAX_LIST_PATHS || budget.visited >= MAX_ENTRIES_VISITED) return out;
-  if (Array.isArray(value)) {
-    const first = value[0];
-    out.push({
-      path: path || "(root)",
-      length: value.length,
-      ...(value.length ? {
-        item: shapeOf(first)
-      } : {})
-    });
-    // One level into the items, so `lines[].addonIds` is reachable too.
-    if (value.length && isPlainObject(first)) {
-      for (const [k, v] of Object.entries(first)) {
-        if (++budget.visited >= MAX_ENTRIES_VISITED) break;
-        listShapes(v, path ? `${path}[].${k}` : `[].${k}`, out, depth + 1, budget);
-      }
-    }
-    return out;
-  }
-  if (isPlainObject(value)) {
-    for (const [k, v] of Object.entries(value)) {
-      if (++budget.visited >= MAX_ENTRIES_VISITED) break;
-      listShapes(v, path ? `${path}.${k}` : k, out, depth + 1, budget);
-    }
-  }
-  return out;
-}
-
-/** True when a sketch stopped early, so a caller can say so rather than imply completeness. */
-export function shapesWereTruncated(value) {
-  const budget = {
-    visited: 0
-  };
-  const out = listShapes(value, "", [], 0, budget);
-  return out.length >= MAX_LIST_PATHS || budget.visited >= MAX_ENTRIES_VISITED;
-}
-
-/**
- * The lists in a value that a caller could add to WITHOUT any way to know the
- * item shape. Empty by definition on a healthy value; non-empty means a write
- * into one of these paths cannot be checked by anything.
- */
-export function unshapedLists(value) {
-  return listShapes(value).filter(l => l.item === undefined).map(l => l.path);
-}
-
-/**
- * The sketch an adapter attaches to a read: the value's own type, plus the item
- * type of every list in it.
- *
- * Returns undefined when there is nothing worth saying (a scalar, or an object
- * holding no lists) so adapters can spread it and add no noise.
- */
-export function shapeSummary(value) {
-  if (value === undefined) return undefined;
-  const lists = listShapes(value);
-  const shape = shapeOf(value);
-  if (!lists.length && !isPlainObject(value) && !Array.isArray(value)) return undefined;
-  return lists.length ? {
-    shape,
-    lists
-  } : {
-    shape
-  };
-}
+"use strict";const c=n=>typeof n==="object"&&n!==null&&!Array.isArray(n);const h=3;const u=24;const y=40;const d=600;export function shapeOf(n,t=0){if(n===null)return"null";if(Array.isArray(n)){if(!n.length)return"unknown[]";if(t>=h)return"\u2026[]";const e=shapeOf(n[0],t+1);return e.includes(" ")||e.endsWith("]")?`(${e})[]`:`${e}[]`}if(c(n)){if(t>=h)return"{\u2026}";const e=Object.keys(n);const i=e.slice(0,u);const s=i.map(f=>`${f}: ${shapeOf(n[f],t+1)}`).join(", ");const o=e.length>i.length?`, +${e.length-i.length} more`:"";return`{${s}${o}}`}const r=typeof n;return r==="undefined"?"undefined":r==="function"?"function":r}export function listShapes(n,t="",r=[],e=0,i={visited:0}){if(e>h)return r;if(r.length>=y||i.visited>=d)return r;if(Array.isArray(n)){const s=n[0];r.push({path:t||"(root)",length:n.length,...n.length?{item:shapeOf(s)}:{}});if(n.length&&c(s)){for(const[o,f]of Object.entries(s)){if(++i.visited>=d)break;listShapes(f,t?`${t}[].${o}`:`[].${o}`,r,e+1,i)}}return r}if(c(n)){for(const[s,o]of Object.entries(n)){if(++i.visited>=d)break;listShapes(o,t?`${t}.${s}`:s,r,e+1,i)}}return r}export function shapesWereTruncated(n){const t={visited:0};const r=listShapes(n,"",[],0,t);return r.length>=y||t.visited>=d}export function unshapedLists(n){return listShapes(n).filter(t=>t.item===void 0).map(t=>t.path)}export function shapeSummary(n){if(n===void 0)return void 0;const t=listShapes(n);const r=shapeOf(n);if(!t.length&&!c(n)&&!Array.isArray(n))return void 0;return t.length?{shape:r,lists:t}:{shape:r}}

package/lib/module/sync/wireBudget.js

@@ -1,92 +1 @@
-"use strict";
-
-/**
- * Size guards for anything a tool puts on the sync wire.
- *
- * Every adapter faces the same problem: a snapshot is rebuilt and serialized
- * on the device's JS thread ~5x/sec while a dashboard watches, and one fat or
- * unserializable field can either freeze that thread or blow the emit layer's
- * budget — which drops the WHOLE snapshot and leaves the panel stale.
- *
- * Two rules make that safe, and both are easy to get subtly wrong, which is
- * why they live here instead of being copied per adapter:
- *
- *  1. NEVER measure by serializing. `JSON.stringify(value).length` is
- *     O(payload) and allocates the whole string — an unbounded cost to
- *     enforce a 16KB cap, i.e. the protection becomes the freeze. Walk with
- *     an early abort instead: the cost is O(limit) no matter how big the
- *     value, and a string costs a length read rather than a scan.
- *
- *  2. Only reach for `JSON.stringify` when the walk saw something that could
- *     actually make it throw. A value straight out of `JSON.parse` — which is
- *     what a network body or a stored string is — is a finite tree of plain
- *     values and can never throw, so the check is pure waste on the common
- *     path.
- */
-
-import { isJsonSerializable } from "../utils/typeHelpers.js";
-/**
- * Approximate JSON size, aborting as soon as `limit` is passed — O(limit),
- * never O(payload). Returns the bytes counted so far, so one walk can both
- * threshold ("over the per-field cap?") and accumulate ("how much of the
- * snapshot budget is left?").
- */
-export function approxJsonSize(value, limit) {
-  let bytes = 0;
-  let sawRepeat = false;
-  let sawBigInt = false;
-  const stack = [value];
-  const seen = new Set();
-  while (stack.length > 0) {
-    if (bytes > limit) return {
-      bytes,
-      sawRepeat,
-      sawBigInt
-    };
-    const v = stack.pop();
-    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2; // O(1), no scan
-    else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
-      if (seen.has(v)) {
-        sawRepeat = true;
-        continue;
-      }
-      seen.add(v);
-      if (Array.isArray(v)) {
-        bytes += 2 + v.length;
-        for (let i = 0; i < v.length; i++) stack.push(v[i]);
-      } else {
-        bytes += 2;
-        for (const k in v) {
-          bytes += k.length + 4;
-          stack.push(v[k]);
-        }
-      }
-    } else {
-      if (typeof v === "bigint") sawBigInt = true;
-      bytes += 4;
-    }
-  }
-  return {
-    bytes,
-    sawRepeat,
-    sawBigInt
-  };
-}
-
-/**
- * Should this value be withheld from the wire — too big, or unserializable?
- *
- * The ordering is the point: measure with the early-abort walk, and only pay
- * for `JSON.stringify` when the walk found a reason it might throw.
- */
-export function isOverWireBudget(value, limit) {
-  const walk = approxJsonSize(value, limit);
-  if (walk.bytes > limit) return true;
-  // A finished walk with no repeated reference and no bigint cannot throw.
-  //
-  // Not exhaustive even then: a `toJSON`/getter that throws is invisible to
-  // the walk, so callers handling hostile payloads should still guard their
-  // own conversion. `safeEmit` is the last backstop.
-  if (!walk.sawRepeat && !walk.sawBigInt) return false;
-  return !isJsonSerializable(value);
-}
+"use strict";import{isJsonSerializable as a}from"../utils/typeHelpers.js";export function approxJsonSize(s,i){let t=0;let o=false;let f=false;const r=[s];const l=new Set;while(r.length>0){if(t>i)return{bytes:t,sawRepeat:o,sawBigInt:f};const e=r.pop();if(e===null||e===void 0)t+=4;else if(typeof e==="string")t+=e.length+2;else if(typeof e==="number")t+=8;else if(typeof e==="boolean")t+=5;else if(typeof e==="object"){if(l.has(e)){o=true;continue}l.add(e);if(Array.isArray(e)){t+=2+e.length;for(let n=0;n<e.length;n++)r.push(e[n])}else{t+=2;for(const n in e){t+=n.length+4;r.push(e[n])}}}else{if(typeof e==="bigint")f=true;t+=4}}return{bytes:t,sawRepeat:o,sawBigInt:f}}export function isOverWireBudget(s,i){const t=approxJsonSize(s,i);if(t.bytes>i)return true;if(!t.sawRepeat&&!t.sawBigInt)return false;return!a(s)}