@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/definitions/load/expand/referenced.ts

@@ -0,0 +1,164 @@
+/**
+ * REFERENCE, DON'T COPY — the served form that ships each atom once.
+ *
+ * `expandRefs` specialises every Ref into an inline copy, so a shared button travels
+ * inside every definition that uses it, on every page load. This is the other form: the
+ * definition with its `Ref` nodes LEFT ALONE, plus one copy of each atom they name.
+ *
+ * Split from expand.ts 2026-08-30; the rules are unchanged.
+ */
+import type { UnoverseDefinition } from "../../model.js";
+import { loadDefinition } from "../load.js";
+import { inheritState } from "./inherit.js";
+import type { AnyNode } from "./refs.js";
+
+export function referencedDefinition(def: UnoverseDefinition, contextOrg?: string): UnoverseDefinition {
+  const defs: Record<string, AnyNode> = {};
+  const inherit: Record<string, unknown> = {};
+  // Depth-first over the tree, collecting each named atom ONCE. An atom may itself Ref
+  // another, so collected atoms are walked too — otherwise the client resolves an atom
+  // and finds a reference it was never sent.
+  const collect = (node: AnyNode | undefined): void => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) return node.forEach(collect);
+    if (node.type === "Ref" && typeof node.ref === "string") {
+      const name = node.ref;
+      if (!(name in defs)) {
+        // The referenced piece in its OWN referenced form, with its references merged up
+        // into the same flat map. The client threads `defs` through every recursion, so a
+        // Ref inside a referenced piece resolves against the same map. Storing these
+        // EXPANDED instead was the difference between product-card costing 17 KB + 173 KB
+        // and 17 KB + a handful: it references `document`, and an expanded document drags
+        // in every copy this exists to remove.
+        const piece =
+          loadDefinition(name, "atom", "referenced") ?? loadDefinition(name, "component", "referenced", contextOrg ?? def.org);
+        if (piece?.root) {
+          defs[name] = piece.root as AnyNode;
+          // Same inheritance as the expanded form. The client resolves the Ref itself here,
+          // but `defs` carries roots only — state never travels node-side, so it has to be
+          // merged onto the definition server-side or a referenced-mode host keeps the bug
+          // the expanded form no longer has.
+          inheritState(inherit, piece);
+          for (const [k, v] of Object.entries((piece.defs ?? {}) as Record<string, AnyNode>)) if (!(k in defs)) defs[k] = v;
+          collect(piece.root as AnyNode);
+        }
+      }
+    }
+    if (Array.isArray(node.children)) node.children.forEach(collect);
+    if (node.item) collect(node.item as AnyNode);
+    if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) collect(node.cases[k] as AnyNode);
+    if (node.frame) collect(node.frame as AnyNode);
+    if (node.fallback) collect(node.fallback as AnyNode);
+  };
+  // EVERY TREE THE DEFINITION SHIPS, not just `root`. A template's arrangements live in
+  // `layouts`, and they are the whole payload — a chat template's `root` is a stub. Walking
+  // `root` alone deduplicated nothing at all for templates: measured on bpp-chat,
+  // whose four layouts include the SAME 7 KB chrome file, the referenced form came back 11%
+  // smaller instead of the ~70% every component saw.
+  const trees = () => [def.root, ...Object.values(def.layouts ?? {})] as AnyNode[];
+  trees().forEach(collect);
+  if (Object.keys(inherit).length) def = { ...def, state: { ...inherit, ...((def.state as Record<string, unknown>) ?? {}) } };
+
+  // REPEATS ARE REFERENCES TOO, wherever they came from.
+  //
+  // Hoisting named atoms only fixes duplication that went through a `Ref`. A template
+  // composes its arrangements with `$include`, which is copied just as literally: a chat
+  // layout shipping four arrangements carried four copies of the same chrome, 35 KB of a
+  // 44 KB payload, and not one byte of it was an atom.
+  //
+  // So this is structural: any subtree appearing more than once becomes ONE entry plus
+  // references to it. Identical trees render identically, and the client resolves a
+  // parameterless reference by cloning, so nothing about meaning changes. Counted ACROSS
+  // the trees, because the repetition that matters most is one arrangement against another.
+  // SCOPED TO THIS DEFINITION, because `defs` is not this definition's map alone: every
+  // referenced piece merges ITS names up into the same flat namespace above. Generated
+  // names used to be a counter restarting at 0 for every definition, so a template's
+  // `shared:0` and a component's `shared:0` were the same key. The component's landed
+  // first, the template's store was skipped as "already there", and the template's chunk
+  // was handed a pointer to the component's — silently, since a collision looks exactly
+  // like a chunk already stored. Observed live 2026-08-23: bpp-chat's chrome resolved to
+  // bpp/text-chat's, so the `appWidth: chat` it carried never reached the client and the
+  // app sized wrong. Nothing errored; a chunk simply became a different chunk.
+  const hoisted = hoistRepeats(trees(), defs, `${def.org ? `${def.org}/` : ""}${def.name}`);
+  if (hoisted.length) {
+    const [root, ...layouts] = hoisted;
+    def = { ...def, root };
+    if (def.layouts) def.layouts = Object.fromEntries(Object.keys(def.layouts).map((k, i) => [k, layouts[i]]));
+  }
+
+  return Object.keys(defs).length ? ({ ...def, defs } as UnoverseDefinition) : def;
+}
+
+/**
+ * Replace every repeated subtree, across ALL of a definition's trees, with a reference to
+ * one copy. Returns the rewritten trees in the order given.
+ *
+ * Counting spans the whole set rather than each tree alone, because the duplication that
+ * dominates a template is one ARRANGEMENT against another: four layouts that each include
+ * the same chrome share nothing within themselves and everything between themselves.
+ *
+ * Top-down, so the LARGEST repeated tree is hoisted and its children ride inside it rather
+ * than being hoisted separately: hoisting a child first would leave the parent's copies
+ * differing only in that child's reference, and they would stop matching each other.
+ *
+ * `MIN` exists because a reference costs about 40 bytes; hoisting a 60-byte node makes the
+ * payload bigger and the tree harder to read for nothing.
+ */
+function hoistRepeats(roots: AnyNode[], defs: Record<string, AnyNode>, scope: string): AnyNode[] {
+  const MIN = 700; // bytes: comfortably larger than the reference that replaces it
+  const counts = new Map<string, number>();
+  const count = (node: unknown): void => {
+    if (Array.isArray(node)) return node.forEach(count);
+    if (!node || typeof node !== "object") return;
+    const n = node as AnyNode;
+    if (n.type && n.type !== "Ref") {
+      const j = JSON.stringify(n);
+      if (j.length >= MIN) counts.set(j, (counts.get(j) ?? 0) + 1);
+    }
+    for (const v of Object.values(n)) if (v && typeof v === "object") count(v);
+  };
+  roots.forEach(count);
+
+  const repeated = new Map<string, string>(); // serialized tree → its reference name
+  let i = 0;
+  // `shared:<definition>:<n>` — the definition segment is what makes a generated name mean
+  // ONE chunk in the flat map every referenced piece also writes into.
+  for (const [j, n] of counts) if (n > 1) repeated.set(j, `shared:${scope}:${(i++).toString(36)}`);
+  if (!repeated.size) return [];
+
+  const swap = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(swap);
+    if (!node || typeof node !== "object") return node;
+    const n = node as AnyNode;
+    if (n.type && n.type !== "Ref") {
+      const name = repeated.get(JSON.stringify(n));
+      if (name) {
+        // The first sighting becomes the stored copy, with ITS OWN repeats hoisted, so a
+        // shape repeated inside a repeated shape collapses too.
+        if (!(name in defs)) {
+          const stored = JSON.parse(JSON.stringify(n)) as AnyNode;
+          defs[name] = stored;
+          for (const [k, v] of Object.entries(stored)) if (v && typeof v === "object") stored[k] = swap(v) as AnyNode;
+        }
+        return { type: "Ref", ref: name };
+      }
+    }
+    for (const [k, v] of Object.entries(n)) if (v && typeof v === "object") n[k] = swap(v) as AnyNode;
+    return n;
+  };
+  // A whole tree can itself be a repeat (two arrangements that are the same), so the
+  // returned value is used rather than relying on in-place rewriting.
+  return roots.map((r) => swap(r) as AnyNode);
+}
+
+
+// ---- Folder composition: inline `{ "$include": "name" }` from sibling files ----
+//
+// A template can be a FOLDER (apps/chatlayout/) of multiple data files, so
+// UX pieces live in their own files (chatlayout + user-turn + …). Any
+// `{ "$include": "user-turn" }` node is replaced by the parsed content of
+// `<folder>/user-turn.{yaml,json}` (recursively). All UX stays as served data — the SDK
+// receives one fully-assembled tree.
+//
+// `$include` values are EXTENSION-LESS by design, so a partial can be converted from JSON
+// to YAML without touching any file that references it.

package/vendor/base/src/definitions/load/expand/refs.ts

@@ -0,0 +1,106 @@
+/**
+ * INLINING A REF: the remaps and the literals.
+ *
+ * A component composes an atom with `{ type: "Ref", ref: "button", props: {…}, with: {…} }`.
+ * `props` REMAPS the atom's field names onto the host's; `with` resolves them to LITERALS.
+ * Everything here is that one job — nothing in this file knows what a definition is.
+ *
+ * Split from expand.ts 2026-08-30 (it had grown five jobs); the rules are unchanged.
+ */
+
+export type AnyNode = Record<string, any>;
+
+// Remap `{{field}}` data-bindings embedded in STYLE values (e.g. a radial gauge's
+// `radial.at: "{{value}}"`, a progress bar's `width: "{{pct}}"`) — the style-side twin
+// of the bind/visibleWhen remap, so an atom whose look is data-driven is parameterizable.
+function remapStyleBindings(style: AnyNode, propMap: Record<string, string>): void {
+  for (const k of Object.keys(style)) {
+    const v = style[k];
+    if (typeof v === "string" && v.includes("{{")) {
+      style[k] = v.replace(/\{\{(\w[\w.]*)\}\}/g, (m, f) => (propMap[f] ? `{{${propMap[f]}}}` : m));
+    } else if (v && typeof v === "object") {
+      remapStyleBindings(v as AnyNode, propMap); // nested: radial.at, hover, etc.
+    }
+  }
+}
+
+export function remapFields(node: AnyNode, propMap: Record<string, string>): void {
+  // A NESTED `Ref` IS REMAPPED THROUGH ITS OWN `props`. The values of an inner reference's
+  // `props` are field names in THIS tree's scope, so the host's rename has to reach them:
+  // an atom that composes another atom (toggle-row and form-toggle both draw toggle-switch)
+  // otherwise hands the inner one the OUTER atom's prop name, which the host has just
+  // renamed away. The switch then tests an absent key and never draws its ON state — the
+  // control looks right, moves nothing, and says nothing. Same silence as the visibleWhen
+  // object form below, one level deeper.
+  if (node.type === "Ref" && node.props && typeof node.props === "object") {
+    for (const k of Object.keys(node.props as AnyNode)) {
+      const v = (node.props as AnyNode)[k];
+      if (typeof v === "string" && propMap[v]) (node.props as AnyNode)[k] = propMap[v];
+    }
+  }
+  if (node.bind) for (const k of Object.keys(node.bind)) if (propMap[node.bind[k]]) node.bind[k] = propMap[node.bind[k]];
+  if (typeof node.visibleWhen === "string" && propMap[node.visibleWhen]) node.visibleWhen = propMap[node.visibleWhen];
+  // THE OBJECT FORM REMAPS TOO. A guard is a guard whichever way it is written, and only
+  // the string form was carried across: an atom guarding on `{ field: "value", ne: "" }`
+  // kept testing its OWN prop name after the host remapped `value` to its field, so the
+  // guard read an absent key and the branch never showed. Silent, and it bit form-select
+  // the day it was written (2026-08-09).
+  if (node.visibleWhen && typeof node.visibleWhen === "object" && !Array.isArray(node.visibleWhen)) {
+    const g = node.visibleWhen as { field?: string };
+    if (typeof g.field === "string" && propMap[g.field]) g.field = propMap[g.field];
+  }
+  // `when` style variants are the same predicate wearing a different hat: an atom whose
+  // LOOK is data-driven (a switch track filling when `on` is true) must follow its host's
+  // field for the same reason.
+  const when = (node.style as AnyNode | undefined)?.when;
+  if (Array.isArray(when)) {
+    for (const v of when as { field?: string }[]) {
+      if (v && typeof v.field === "string" && propMap[v.field]) v.field = propMap[v.field];
+    }
+  }
+  if (node.style && typeof node.style === "object") remapStyleBindings(node.style as AnyNode, propMap);
+  if (Array.isArray(node.children)) node.children.forEach((c: AnyNode) => remapFields(c, propMap));
+  if (node.item) remapFields(node.item as AnyNode, propMap); // Each item subtree
+  if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) remapFields(node.cases[k] as AnyNode, propMap); // Switch branches
+}
+
+// Resolve an atom's bindings to LITERAL content (the Ref's `with` map). A bind entry
+// whose field is a `with` key becomes a hardcoded attribute; a visibleWhen guard on a
+// provided (truthy) key is satisfied statically and dropped; `{{key}}` style bindings
+// take the value. Keys the atom doesn't bind are ignored (harmless).
+/** Substitute `{{name}}` anywhere inside a style object, at any depth. */
+function applyStyleLiterals(style: unknown, lits: Record<string, unknown>): void {
+  if (Array.isArray(style)) return style.forEach((v) => applyStyleLiterals(v, lits));
+  if (!style || typeof style !== "object") return;
+  const s = style as AnyNode;
+  for (const k of Object.keys(s)) {
+    const v = s[k];
+    if (typeof v === "string" && v.includes("{{"))
+      s[k] = v.replace(/\{\{(\w[\w.]*)\}\}/g, (m, f) => (f in lits ? String(lits[f]) : m));
+    else if (v && typeof v === "object") applyStyleLiterals(v, lits);
+  }
+}
+
+export function applyLiterals(node: AnyNode, lits: Record<string, unknown>): void {
+  if (node.bind) {
+    for (const attr of Object.keys(node.bind)) {
+      const field = node.bind[attr];
+      if (typeof field === "string" && field in lits) {
+        node[attr] = lits[field];
+        delete node.bind[attr];
+      }
+    }
+    if (Object.keys(node.bind).length === 0) delete node.bind;
+  }
+  if (typeof node.visibleWhen === "string" && node.visibleWhen in lits) {
+    if (lits[node.visibleWhen]) delete node.visibleWhen; // statically satisfied
+    // falsy literal: keep the (now never-true) guard — the node stays hidden
+  }
+  // Style values may NEST (a radial's `at`, a `when` clause's `apply`), so this walks the
+  // whole style object rather than its top level — a `{{value}}` one level down survived
+  // and reached the renderer verbatim.
+  if (node.style && typeof node.style === "object") applyStyleLiterals(node.style as AnyNode, lits);
+  if (Array.isArray(node.children)) node.children.forEach((c: AnyNode) => applyLiterals(c, lits));
+  if (node.item) applyLiterals(node.item as AnyNode, lits);
+  if (node.cases && typeof node.cases === "object") for (const k of Object.keys(node.cases)) applyLiterals(node.cases[k] as AnyNode, lits);
+}

package/vendor/base/src/definitions/load/expand/walk.ts

@@ -0,0 +1,91 @@
+/**
+ * THE EXPANSION WALK: inline every `Ref`, gathering what the pieces carry up.
+ *
+ * One pass over a definition's tree. It calls into `refs.ts` to inline and remap, and into
+ * `inherit.ts` for the state and prop contracts an embedded piece hands its host.
+ *
+ * Split from expand.ts 2026-08-30; the rules are unchanged.
+ */
+import type { UnoverseDefinition } from "../../model.js";
+import { loadDefinition } from "../load.js";
+import { remapFields, applyLiterals, type AnyNode } from "./refs.js";
+import { inheritState, inheritProps, mergeInheritedProps } from "./inherit.js";
+
+export function expandNode(node: AnyNode, contextOrg?: string, inherit?: Record<string, unknown>, props?: Record<string, Record<string, unknown>>, scope: string[] = []): AnyNode {
+  if (node?.type === "Ref") {
+    // A Ref inlines an ATOM (the usual case, rx/atoms). It also resolves a COMPONENT
+    // as a fallback, so a template can embed a shared flat component (e.g. the
+    // ComposerBar chrome) the same way it embeds an atom — the one mechanism for fixed,
+    // always-present chrome. (A component's root is inlined as-is; flat components only.)
+    // The parent definition's org rides along so a bare ref inside an org's own tree
+    // resolves to that org's component when two orgs share the name.
+    //
+    // AND A BLOCK (2026-08-31) — a flat TEMPLATE with no manifest: `pair`, `feature`,
+    // `single`, `rail`, `stack`. §2 always said "a rich template may compose basic ones
+    // inside itself", and this is that sentence, by the mechanism already here rather than
+    // a new one. Inlining is exactly right for it: the block's `director:` places arrive in
+    // the composing page's tree BEFORE its sections compile, so they become real slots and
+    // the page addresses them by position along with its own. Nothing is mounted, nothing
+    // is nested at runtime — the page ends up with the tree it would have had if someone
+    // had drawn the block by hand, which is the point.
+    //
+    // Last in the chain deliberately: atoms and components are the common case, and a
+    // template sharing a name with either keeps the old resolution.
+    const atom =
+      loadDefinition(String(node.ref), "atom") ??
+      loadDefinition(String(node.ref), "component", "expanded", contextOrg) ??
+      loadDefinition(String(node.ref), "template", "expanded", contextOrg);
+    if (!atom?.root) return node; // unknown ref — leave the Ref (renders as a no-op)
+    inheritState(inherit ?? {}, atom);
+    if (props) inheritProps(props, atom, (node.props ?? {}) as Record<string, string>, (node.with ?? {}) as Record<string, unknown>, scope);
+    const root = JSON.parse(JSON.stringify(atom.root)) as AnyNode;
+    remapFields(root, (node.props ?? {}) as Record<string, string>);
+    if (node.with && typeof node.with === "object") applyLiterals(root, node.with as Record<string, unknown>);
+    if (node.visibleWhen) root.visibleWhen = node.visibleWhen;
+    // A Ref may override the atom's `action` — the per-host behaviour the atom can't carry
+    // (e.g. each wizard step's option sets different fields). Parallel to style/visibleWhen.
+    if (node.action) root.action = node.action;
+    if (node.style) root.style = { ...(root.style ?? {}), ...node.style };
+    // THE BLOCK'S OPENING (2026-09-02, blocks returned): a Ref carrying `children:` fills
+    // the inlined root with the CALLER's children — a `band` or `two-column` block styles
+    // the frame, the composing layout says what sits inside. Same override family as
+    // style/action above; a Ref without children keeps the block's own (a complete block).
+    if (Array.isArray(node.children) && node.children.length) root.children = node.children;
+    return expandNode(root, contextOrg, inherit, props, scope); // expand nested refs too
+  }
+  if (Array.isArray(node?.children)) node.children = node.children.map((c: AnyNode) => expandNode(c, contextOrg, inherit, props, scope));
+  // `Each` carries a per-item subtree in `item` (not `children`) — expand it too,
+  // so an atom `Ref` inside a repeated item is inlined like anywhere else.
+  // An `Each`'s `item` draws ONE ITEM, so everything inside it belongs to that
+  // array's item shape (see `inheritProps`).
+  const itemsField = node?.type === "Each" ? (node.bind as AnyNode | undefined)?.items : undefined;
+  if (node?.item) node.item = expandNode(node.item, contextOrg, inherit, props, typeof itemsField === "string" ? [...scope, itemsField] : scope);
+  // `Switch` carries its branches in `cases` (a value→subtree map) — expand each, so an
+  // atom `Ref` inside a Switch branch is inlined like anywhere else (else the branch
+  // renders blank). Parallel to children/item.
+  if (node?.cases && typeof node.cases === "object") {
+    for (const k of Object.keys(node.cases)) node.cases[k] = expandNode(node.cases[k] as AnyNode, contextOrg, inherit, props, scope);
+  }
+  // `ComponentSlot` carries chrome in `frame` (born when the slot matches) and `fallback`
+  // (shown when it doesn't) — both are real child slots, so an atom `Ref` inside them (e.g. a
+  // ✕ CloseButton on a rail/panel frame) must inline like anywhere else, else the Ref survives.
+  if (node?.frame) node.frame = expandNode(node.frame as AnyNode, contextOrg, inherit, props, scope);
+  if (node?.fallback) node.fallback = expandNode(node.fallback as AnyNode, contextOrg, inherit, props, scope);
+  return node;
+}
+
+
+export function expandRefs(def: UnoverseDefinition, contextOrg?: string): UnoverseDefinition {
+  // Whatever the tree embeds declares its own starting values; this is where they land on
+  // the slice those inlined nodes actually read (see `inheritState`). Merged AFTER the
+  // whole tree is walked, and beneath the def's own state, so nothing an author wrote is
+  // touched — including the v2 `state.view` compile, which runs before this.
+  const inherit: Record<string, unknown> = {};
+  // The atoms' own field contracts land here (see `inheritProps`), beneath whatever the
+  // host declared — merged after the walk, so authored props are never touched.
+  const fromAtoms: Record<string, Record<string, unknown>> = {};
+  if (def?.root) def.root = expandNode(def.root as AnyNode, contextOrg ?? def.org, inherit, fromAtoms);
+  if (Object.keys(inherit).length) def.state = { ...inherit, ...((def.state as Record<string, unknown>) ?? {}) };
+  mergeInheritedProps(def, fromAtoms);
+  return def;
+}