@tinkerlandai/indiana-iam 0.2.0 → 0.4.0

package/src/anchors.mjs

@@ -9,6 +9,11 @@ export const anchorAttributes = [
   "data-qa",
   "data-indiana-id",
 ];
+export function sourceScriptKind(file, ts) {
+  return /\.[cm]?ts$/.test(file)
+    ? ts.ScriptKind.TS
+    : /\.tsx$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JSX;
+}
 export function instrumentableSource(file, text) {
   return (
     typeof text === "string" &&

package/src/build-options.d.ts

@@ -6,17 +6,22 @@ export type IndianaIamBuildOptions = {
   enabled?: boolean;
   /** Reuse existing UI IDs and add build-only anchors for unambiguous native JSX (default: true). */
   automaticAnchors?: boolean;
+  /** Browser entry relative to root for apps with multiple source roots. */
+  entry?: string;
   /** App name recorded in the IAM; defaults to the root folder name. */
   name?: string;
   /** Fail the build when the IAM cannot be generated (default: warn and continue). */
   strict?: boolean;
   /** Font family declared by the compiled CSS that renders the root element. */
   rootFont?: string;
-  /** Drop inline SVG resources from compiled CSS instead of skipping the CSS. */
+  /** Drop inline SVG resources with a coverage gap instead of skipping the CSS (default: true). */
   omitSvgResources?: boolean;
   logger?: BuildLogger;
   /** Key holding only app-manifests:write; defaults to `INDIANA_IAM_KEY`. Without one the IAM is not uploaded. */
   apiKey?: string;
+  /** Client this build belongs to, such as `web` or `web-dashboard`; each client has its own current version.
+   * Defaults to `INDIANA_IAM_CLIENT` or `web`. */
+  client?: string;
   /** Indiana origin; defaults to `INDIANA_IAM_BASE_URL` or https://tinker.cash. */
   baseUrl?: string;
   /** "production" (default) skips Vercel preview deployments; "always" uploads every build; false never uploads. */

package/src/build-runtime.mjs

@@ -1,10 +1,13 @@
 import fs from "node:fs/promises";
 import { expandDomNodes } from './node-hashes.mjs';
+import {applySourceAttributes} from './source-attributes.mjs';
+import {applySourceCollections,markUnobservedData,checkedCollectionFragment} from './source-collections.mjs';
 // Only these two reviewed local assets form the executable preview runtime.
 const machine = await fs.readFile(new URL("../assets/state-machine.js", import.meta.url), "utf8");
+await fs.writeFile(new URL('./ui-state-machine.mjs', import.meta.url), '/* Generated from assets/state-machine.js by build-runtime.mjs. */\n'+machine);
 const controller = await fs.readFile(new URL("../assets/document-controller.js", import.meta.url), "utf8");
 if (!machine.includes("export function createStateMachine(")) throw new Error("Unexpected state runtime export");
-await fs.writeFile(new URL("../assets/document-runtime.js", import.meta.url), "/* Generated by scripts/build-runtime.mjs. */\n(() => {\n" + machine.replace("export function createStateMachine(", "function createStateMachine(") + "\n" + controller + "\n})();\n");
+await fs.writeFile(new URL("../assets/document-runtime.js", import.meta.url), "/* Generated by scripts/build-runtime.mjs. */\n(() => {\n" + machine.replace("export function createStateMachine(", "function createStateMachine(") + "\n" + [checkedCollectionFragment,applySourceAttributes,applySourceCollections,markUnobservedData].map(fn=>fn.toString()).join('\n')+'\n'+ controller + "\n})();\n");
 const viewerUrl=new URL('../assets/viewer.js',import.meta.url),viewer=await fs.readFile(viewerUrl,'utf8');
 if(!viewer.includes('/* BEGIN HTML DOM DERIVATION */'))throw Error('Missing DOM derivation asset boundary');
 await fs.writeFile(viewerUrl,viewer.replace(/\/\* BEGIN HTML DOM DERIVATION \*\/[\s\S]*?\/\* END HTML DOM DERIVATION \*\//,'/* BEGIN HTML DOM DERIVATION */\n'+expandDomNodes.toString()+'\n  /* END HTML DOM DERIVATION */'));

package/src/build-styles.mjs

@@ -30,8 +30,8 @@ function checkedMounts(mounts) {
 }
 
 /** Explicit public build inputs only. Never runs builds, reads env, downloads URLs or imports App code. */
-export async function attachBuildStyles(manifest, { root, files = [], publicFiles = [], optimizePublicImages = false, rootFont = "", omitSvgResources = false, mounts = nextStaticMounts() }) {
-  if (!Array.isArray(files) || files.length > 16 || !Array.isArray(publicFiles) || publicFiles.length > 128 || (!files.length && !publicFiles.length)) throw new Error("Choose up to 16 CSS files and 128 public assets");
+export async function attachBuildStyles(manifest, { root, files = [], publicFiles = [], referencedImages = false, optimizePublicImages = false, rootFont = "", omitSvgResources = false, mounts = nextStaticMounts() }) {
+  if (!Array.isArray(files) || files.length > 16 || !Array.isArray(publicFiles) || publicFiles.length > 128 || (!files.length && !publicFiles.length && !referencedImages)) throw new Error("Choose up to 16 CSS files and 128 public assets");
   if (rootFont && !/^[A-Za-z][A-Za-z0-9 _-]{0,63}$/.test(rootFont)) throw new Error("Invalid root font family");
   root = await fs.realpath(root);
   const cssTree = dependency("css-tree").value;
@@ -45,9 +45,9 @@ export async function attachBuildStyles(manifest, { root, files = [], publicFile
   const fileOf = pathname => { const mount = [...served].sort((a, b) => b.urlPath.length - a.urlPath.length).find(m => pathname.startsWith(m.urlPath)); if (!mount) throw new Error("CSS asset is outside the public build directories"); return mount.directory + "/" + pathname.slice(mount.urlPath.length); };
   const inputs = new Map(), assets = new Map(manifest.assets.map(a => [a.assetKey, a]));
   let total = 0, publicSourceBytes = 0;
-  async function read(file, publicImage = false) {
+  async function read(file, publicImage = false, sourceImage = false) {
     const absolute = path.resolve(root, file), real = await fs.realpath(absolute);
-    if ((await fs.lstat(absolute)).isSymbolicLink() || !allowed.some(base => real.startsWith(base + path.sep))) throw new Error("Asset must be inside a real public build directory");
+    if ((await fs.lstat(absolute)).isSymbolicLink() || !(sourceImage ? real.startsWith(root+path.sep) : allowed.some(base => real.startsWith(base + path.sep)))) throw new Error("Asset must be inside a real public build directory");
     const relative = path.relative(root, real).split(path.sep).join("/");
     if (inputs.has(relative)) return inputs.get(relative);
     const stat = await fs.stat(real);
@@ -113,14 +113,50 @@ export async function attachBuildStyles(manifest, { root, files = [], publicFile
       assets.set(key, {assetKey:key, sourceUrl, mime, bytes:bytes.length, sha256:digest, dataUrl:'data:'+mime+';base64,'+bytes.toString('base64')});
     }
   }
+  if(referencedImages){
+    const urls=[...new Set(manifest.documents.flatMap(doc=>documentNodes(doc).map(n=>n.attributes?.src).filter(v=>typeof v==='string'&&/^\/(?!\/)[A-Za-z0-9_./-]+\.(?:png|jpe?g|webp|gif)$/i.test(v))))].sort();
+    if(urls.length>128)throw Error('Referenced image budget exceeded');
+    for(const url of urls){
+      if(assets.size>=128)throw Error('Referenced image budget exceeded');
+      if([...assets.values()].some(a=>a.sourceUrl===url))continue;
+      const source=url.startsWith('/__iam_source__/'),file=source?url.slice('/__iam_source__/'.length):fileOf(url);
+      if(file.split('/').some(p=>!p||p==='..'||source&&p.startsWith('.'))||/(?:^|\/)(?:api|server|secrets?|credentials)(?:\/|\.)/i.test(file))continue;
+      try{
+        const input=await read(file,false,source);let bytes=input.bytes,mime=types.get(path.extname(file).toLowerCase());
+        const valid=mime==='image/png'?bytes.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10])):mime==='image/jpeg'?bytes[0]===255&&bytes[1]===216&&bytes[2]===255:mime==='image/webp'?bytes.subarray(0,4).toString()==='RIFF'&&bytes.subarray(8,12).toString()==='WEBP':/^GIF8[79]a$/.test(bytes.subarray(0,6).toString());
+        if(!valid)throw Error('Referenced raster signature mismatch');
+        if(bytes.length>65536){
+          const sharp=dependency('sharp').value;if(sharp.versions.sharp!=='0.35.5')throw Error('Pinned image encoder required');
+          const image=sharp(bytes,{limitInputPixels:16777216,failOn:'warning'}),metadata=await image.metadata();if((metadata.pages||1)!==1)throw Error('Animated source images require an explicit adapter');
+          bytes=await image.rotate().resize({width:800,height:800,fit:'inside',withoutEnlargement:true}).webp({quality:90,effort:4}).toBuffer();mime='image/webp';
+          manifest.coverage.gaps.push({code:'REFERENCED_IMAGE_PREVIEW_OPTIMIZED',file,detail:'Build preview profile for rasters over 64 KiB: auto-orient, fit inside 800x800, WebP quality 90; source bytes remain hashed. Lossy preview, not original pixels.'});
+        }
+        const digest=sha256(bytes),assetKey=identity('asset',{sourceUrl:url,mime,sha256:digest});assets.set(assetKey,{assetKey,sourceUrl:url,mime,bytes:bytes.length,sha256:digest,dataUrl:'data:'+mime+';base64,'+bytes.toString('base64')});
+      }catch(error){
+        // A missing reference is a fidelity gap. Unsafe files/budgets fail the packaging step.
+        if(error.code!=='ENOENT')throw error;
+        manifest.coverage.gaps.push({code:'REFERENCED_IMAGE_MISSING',file,detail:'Referenced raster is absent from the local public build; no network fetch performed.'});
+      }
+    }
+  }
   if (optimizePublicImages && publicFiles.length) manifest.coverage.gaps.push({code:'PUBLIC_IMAGES_OPTIMIZED', file:publicFiles[0], detail:'Explicit sharp 0.35.5 profile: auto-orient, fit inside 800x800 without enlargement, WebP quality 90 effort 4; metadata stripped. Source bytes hashed independently; not pixel-identical originals.'});
   const sheets = [], families = new Set();
   for (const file of [...new Set(files)].sort()) {
     if (!file.endsWith(".css")) throw new Error("Compiled CSS file required");
     const input = await read(file), ast = cssTree.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes), { parseCustomProperty: true });
     const urls = [];
+    // A build may retain a remote font import. Keep its local stylesheet, but
+    // never fetch or copy the external dependency into an offline projection.
+    cssTree.walk(ast, { visit: "Atrule", enter(node, item, list) {
+      if (node.name.toLowerCase() !== "import") return;
+      const target = node.prelude?.children?.first;
+      if (!["String", "Url"].includes(target?.type) || !/^(?:https?:)?\/\//i.test(target.value))
+        throw new Error("Precompile CSS imports before packaging");
+      list.remove(item);
+      if (!manifest.coverage.gaps.some(g => g.code === "BUILD_EXTERNAL_STYLESHEET_OMITTED" && g.file === input.relative))
+        manifest.coverage.gaps.push({ code: "BUILD_EXTERNAL_STYLESHEET_OMITTED", file: input.relative, detail: "External CSS import omitted without network access; local compiled styles retained. Remote fonts or rules remain unavailable." });
+    }});
     cssTree.walk(ast, node => {
-      if (node.type === "Atrule" && node.name.toLowerCase() === "import") throw new Error("Precompile CSS imports before packaging");
       if (node.type === "Atrule" && node.name.toLowerCase() === "font-face") node.block?.children.forEach(declaration => { if (declaration.type === "Declaration" && declaration.property === "font-family") families.add(cssTree.generate(declaration.value).replace(/^["']|["']$/g, "")); });
       if (node.type === "Url") urls.push(node);
     });
@@ -128,7 +164,7 @@ export async function attachBuildStyles(manifest, { root, files = [], publicFile
     sheets.push(cssTree.generate(ast));
   }
   if (rootFont && !families.has(rootFont)) throw new Error("Root font must exist in compiled font faces");
-  const css = sheets.join("\n") + "\n.iam-page{min-height:100vh}.iam-icon{display:inline-flex;align-items:center;justify-content:center;width:1.1em;height:1.1em}.iam-placeholder{padding:1rem;border:1px dashed #d4d4d4}" + (rootFont ? "\nbody{font-family:" + JSON.stringify(rootFont) + "," + JSON.stringify(rootFont + " Fallback") + ",sans-serif}" : "");
+  const css = sheets.join("\n") + "\n[hidden]{display:none!important}.iam-state{display:contents}.iam-page{min-height:100vh}.iam-icon{display:inline-flex;align-items:center;justify-content:center;width:1.1em;height:1.1em}.iam-placeholder{padding:1rem;border:1px dashed #d4d4d4}" + (rootFont ? "\nbody{font-family:" + JSON.stringify(rootFont) + "," + JSON.stringify(rootFont + " Fallback") + ",sans-serif}" : "");
   if (/<\/(?:style|script)/i.test(css)) throw new Error("HTML closing tag in compiled CSS");
   if (files.length) for (const doc of manifest.documents) { doc.css = css; sealDocument(doc); }
   // One content-addressed image in the envelope; DOM instances carry references.
@@ -142,6 +178,13 @@ export async function attachBuildStyles(manifest, { root, files = [], publicFile
       doc.html = doc.html.replaceAll('src="' + asset.sourceUrl + '"', 'src="' + reference + '"');
     }
     storeDocumentNodes(doc, nodes, new Map(manifest.elements.map(element => [element.elementKey, element])));
+    // Resource replacement changes element and ancestor hashes. Keep target
+    // fingerprints tied to the final document, never the pre-packaging HTML.
+    const finalNodes=documentNodes(doc);
+    for(const target of manifest.routeTree?.targets??[]){
+      if(target.routeKey!==doc.pageKey)continue;const node=finalNodes.find(n=>n.nodeId===target.nodeId);if(!node)continue;
+      target.contentHash=node.contentHash;if(target.subtreeHash!==undefined)target.subtreeHash=node.subtreeHash;
+    }
   }
   manifest.coverage.gaps = manifest.coverage.gaps.filter(g => g.code !== 'PUBLIC_ASSET_NOT_PACKAGED' || ![...assets.values()].some(a => g.detail.startsWith(a.sourceUrl + ':')));
   refreshRenderHashes(manifest);

package/src/build.mjs

@@ -27,10 +27,10 @@ async function guarded({ strict, logger }, action, what) {
  * Before compilation: scans source once per build and returns its release ID.
  * The same source and producer always get the same ID, so the page can embed its descriptor URL before the IAM exists.
  */
-export async function prepareBuildRelease({ root, name, automaticAnchors = true, strict = false, logger = console }) {
+export async function prepareBuildRelease({ root, name, entry, automaticAnchors = true, strict = false, logger = console }) {
   return guarded({ strict, logger }, async () => {
     root = await fs.realpath(root);
-    const analysis = await analyzeSource({ root, name, automaticAnchors });
+    const analysis = await analyzeSource({ root, name, entry, automaticAnchors });
     const releaseId = deriveReleaseId(analysis);
     process.env[STATE] = JSON.stringify({ root, releaseId, automaticAnchors });
     return { releaseId };
@@ -59,22 +59,23 @@ export async function finishBuildRelease({
   root,
   releaseId,
   name,
+  entry,
   automaticAnchors = true,
   cssDirectory,
   mounts,
   publicDirectory,
   rootFont = "",
-  omitSvgResources = false,
+  omitSvgResources = true,
   upload = {},
   strict = false,
   logger = console,
 }) {
   root = await fs.realpath(root);
   return guarded({ strict, logger }, async () => {
-    const analysis = await analyzeSource({ root, name, automaticAnchors });
+    const analysis = await analyzeSource({ root, name, entry, automaticAnchors });
     if (deriveReleaseId(analysis) !== releaseId) throw new Error("Source changed during the build; rebuild before publishing IAM");
     const css = cssDirectory ? await compiledCss(root, cssDirectory) : [];
-    const plain = () => generateAppManifest({ root, analysis, releaseId });
+    const plain = () => generateAppManifest({ root, analysis, releaseId, referencedImages:true, mounts });
     let result;
     if (!css.length) result = await plain();
     else if (css.length > MAX_BUILD_CSS) {
@@ -82,7 +83,7 @@ export async function finishBuildRelease({
       result = await plain();
     } else
       try {
-        result = await generateAppManifest({ root, analysis, releaseId, buildCss: css, mounts, rootFont, omitSvgResources });
+        result = await generateAppManifest({ root, analysis, releaseId, buildCss: css, referencedImages:true, mounts, rootFont, omitSvgResources });
       } catch (error) {
         report(logger, "warn", "compiled CSS skipped: " + (error instanceof Error ? error.message : String(error)));
         result = await plain();
@@ -104,11 +105,16 @@ export async function finishBuildRelease({
           serialized: result.serialized,
           digest: result.digest,
           label,
+          client: settings.client,
           apiKey: settings.apiKey,
           baseUrl: settings.baseUrl,
           fetch: upload.fetch,
         });
-        report(logger, "log", `IAM ${result.digest.slice(0, 12)} ${outcome.uploaded ? "uploaded" : "already uploaded"} as the current version (${label})`);
+        report(
+          logger,
+          "log",
+          `IAM ${result.digest.slice(0, 12)} ${outcome.uploaded ? "uploaded" : "already uploaded"} as the current version of client ${settings.client} (${label})`,
+        );
         return outcome.version;
       }, "IAM upload");
     else if (settings.missingKey && upload.upload !== false)

package/src/cli.mjs

@@ -10,9 +10,9 @@ import { planAnchors, applyAnchors } from "./instrument.mjs";
 import { buildLabel, uploadAppManifest, uploadSettings } from "./upload.mjs";
 
 const usage =
-  "Usage: indiana-iam generate --root <app> --out <new directory> [--name <name> --repository <url> --commit <sha> --release-id <uuid> --write-public-release --build-css <file>...]" +
+  "Usage: indiana-iam generate --root <app> --out <new directory> [--entry <source module> --name <name> --repository <url> --commit <sha> --release-id <uuid> --write-public-release --build-css <file>...]" +
   " | indiana-iam validate --file <manifest>" +
-  " | INDIANA_IAM_KEY=<key> indiana-iam upload --file <manifest> [--label <label> --base-url <url>]" +
+  " | INDIANA_IAM_KEY=<key> indiana-iam upload --file <manifest> [--client <key> --label <label> --base-url <url>]" +
   " | indiana-iam prepare --root <app>" +
   " | indiana-iam anchor --root <checkout> --out <new plan file> [--apply --primitive-map <file> --public-labels --forward-anchors]";
 
@@ -22,6 +22,7 @@ const { values, positionals } = parseArgs({
     root: { type: "string" },
     out: { type: "string" },
     name: { type: "string" },
+    entry: { type: "string" },
     repository: { type: "string" },
     commit: { type: "string" },
     file: { type: "string" },
@@ -39,6 +40,7 @@ const { values, positionals } = parseArgs({
     "public-labels": { type: "boolean", default: false },
     "forward-anchors": { type: "boolean", default: false },
     label: { type: "string" },
+    client: { type: "string" },
     "base-url": { type: "string" },
   },
 });
@@ -53,6 +55,7 @@ if (command === "generate") {
   const result = await generateAppManifest({
     root,
     name: values.name,
+    entry: values.entry,
     repository: values.repository || "",
     commit: values.commit || "",
     navigationPaths: (values["navigation-path"] || []).map((value) => JSON.parse(value)),
@@ -90,7 +93,7 @@ if (command === "generate") {
 } else if (command === "upload") {
   if (!values.file) throw new Error("upload requires --file");
   // The key is read from INDIANA_IAM_KEY only, so it stays out of shell history.
-  const settings = uploadSettings({ baseUrl: values["base-url"], upload: "always" });
+  const settings = uploadSettings({ baseUrl: values["base-url"], upload: "always", client: values.client });
   if (settings.missingKey) throw new Error("Set INDIANA_IAM_KEY to a key with only the app-manifests:write permission");
   const bytes = await fs.readFile(values.file),
     serialized = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
@@ -99,10 +102,13 @@ if (command === "generate") {
     serialized,
     digest: sha256(bytes),
     label: values.label || buildLabel(path.dirname(path.resolve(values.file))),
+    client: settings.client,
     apiKey: settings.apiKey,
     baseUrl: settings.baseUrl,
   });
-  console.log(JSON.stringify({ uploaded, version: { id: version.id, state: version.state, isCurrent: version.isCurrent } }, null, 2));
+  console.log(
+    JSON.stringify({ uploaded, version: { id: version.id, client: version.clientKey, state: version.state, isCurrent: version.isCurrent } }, null, 2),
+  );
 } else if (command === "prepare") {
   if (!values.root) throw new Error("prepare requires --root");
   console.log(JSON.stringify(await prepareRelease(values.root)));

package/src/component-registry.mjs

@@ -0,0 +1,229 @@
+/** Follow finite source selectors to their literal component registry, retaining alternatives as assumptions. */
+export function componentRegistry({
+  ts,
+  node,
+  module,
+  locals,
+  binding,
+  functionFrom,
+  value,
+  component,
+  variable,
+  location,
+  unknown,
+  imported,
+}) {
+  let steps = 0;
+  const choices = [],
+    variables = new Set(),
+    seen = new Set();
+  const unwrap = (n) => {
+    while (
+      n &&
+      (ts.isParenthesizedExpression(n) ||
+        ts.isAsExpression(n) ||
+        ts.isNonNullExpression(n) ||
+        ts.isSatisfiesExpression(n))
+    )
+      n = n.expression;
+    return n;
+  };
+  const localEnvironment = (fn, m, parent) => {
+    const env = new Map(parent);
+    if (ts.isBlock(fn.body))
+      for (const s of fn.body.statements)
+        if (ts.isVariableStatement(s))
+          for (const d of s.declarationList.declarations)
+            if (ts.isIdentifier(d.name))
+              env.set(d.name.text, { node: d.initializer, module: m, env });
+    return env;
+  };
+  const returns = (fn) =>
+    ts.isBlock(fn.body)
+      ? fn.body.statements
+          .filter((s) => ts.isReturnStatement(s))
+          .map((s) => s.expression)
+      : [fn.body];
+  function walk(raw, m, env, path = [], record = null, depth = 0) {
+    const n = unwrap(raw);
+    if (!n || depth > 24 || ++steps > 3000 || choices.length > 32) return;
+    if (!path.length && !(ts.isIdentifier(n) && env.has(n.text))) {
+      const c = component(n, m);
+      if (c) {
+        const optionValue =
+          typeof record?.key === "string" ? record.key : c.symbol;
+        choices.push({
+          component: c,
+          value: optionValue,
+          label:
+            typeof record?.label === "string"
+              ? record.label
+              : typeof record?.labelKey === "string"
+                ? record.labelKey
+                : c.symbol,
+          source: location(m, n, c.symbol),
+          scope: typeof record?.scope === "string" ? record.scope : null,
+        });
+        return;
+      }
+    }
+    const identity = m.file + ":" + n.pos + ":" + n.end + ":" + path.join("/");
+    if (seen.has(identity)) return;
+    seen.add(identity);
+    if (ts.isIdentifier(n)) {
+      const local = env.get(n.text);
+      if (local) {
+        walk(local.node, local.module, local.env, path, record, depth + 1);
+        return;
+      }
+      const ref = binding(m, n.text);
+      if (ref) walk(ref.node, ref.module, new Map(), path, record, depth + 1);
+      return;
+    }
+    if (ts.isPropertyAccessExpression(n)) {
+      walk(n.expression, m, env, [n.name.text, ...path], record, depth + 1);
+      return;
+    }
+    if (ts.isElementAccessExpression(n)) {
+      const key = value(n.argumentExpression, m);
+      walk(
+        n.expression,
+        m,
+        env,
+        [
+          typeof key === "number" || typeof key === "string"
+            ? String(key)
+            : "[]",
+          ...path,
+        ],
+        record,
+        depth + 1,
+      );
+      return;
+    }
+    if (
+      ts.isBinaryExpression(n) &&
+      [ts.SyntaxKind.QuestionQuestionToken, ts.SyntaxKind.BarBarToken].includes(
+        n.operatorToken.kind,
+      )
+    ) {
+      walk(n.left, m, env, path, record, depth + 1);
+      walk(n.right, m, env, path, record, depth + 1);
+      return;
+    }
+    if (ts.isConditionalExpression(n)) {
+      walk(n.whenTrue, m, env, path, record, depth + 1);
+      walk(n.whenFalse, m, env, path, record, depth + 1);
+      return;
+    }
+    if (ts.isArrayLiteralExpression(n)) {
+      const [key, ...rest] = path;
+      if (key === "[]")
+        for (const item of n.elements)
+          walk(item, m, env, rest, record, depth + 1);
+      else if (/^\d+$/.test(key ?? "") && n.elements[Number(key)])
+        walk(n.elements[Number(key)], m, env, rest, record, depth + 1);
+      return;
+    }
+    if (ts.isObjectLiteralExpression(n) && path.length) {
+      const [key, ...rest] = path,
+        fields = n.properties.filter(
+          (p) =>
+            ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p),
+        );
+      const field = fields.find((p) => p.name.text === key);
+      if (!field) return;
+      const meta = Object.fromEntries(
+        fields.flatMap((p) => {
+          if (!["key", "label", "labelKey", "scope"].includes(p.name.text))
+            return [];
+          const v = value(
+            ts.isPropertyAssignment(p) ? p.initializer : p.name,
+            m,
+          );
+          return typeof v === "string" ? [[p.name.text, v]] : [];
+        }),
+      );
+      walk(
+        ts.isPropertyAssignment(field) ? field.initializer : field.name,
+        m,
+        env,
+        rest,
+        Object.keys(meta).length ? meta : record,
+        depth + 1,
+      );
+      return;
+    }
+    if (ts.isCallExpression(n)) {
+      if (
+        ts.isPropertyAccessExpression(n.expression) &&
+        ["find", "filter"].includes(n.expression.name.text)
+      ) {
+        const fn = unwrap(n.arguments[0]);
+        if (
+          n.expression.name.text === "find" &&
+          fn &&
+          ts.isArrowFunction(fn) &&
+          ts.isBinaryExpression(unwrap(fn.body))
+        ) {
+          const comparison = unwrap(fn.body);
+          if (
+            comparison.operatorToken.kind ===
+            ts.SyntaxKind.EqualsEqualsEqualsToken
+          )
+            for (const side of [comparison.left, comparison.right])
+              if (ts.isIdentifier(side)) {
+                const key = variable(side.text);
+                if (key) variables.add(key);
+              }
+        }
+        walk(
+          n.expression.expression,
+          m,
+          env,
+          n.expression.name.text === "find" ? ["[]", ...path] : path,
+          record,
+          depth + 1,
+        );
+        return;
+      }
+      const callback = unwrap(n.arguments[0]);
+      if (
+        callback &&
+        (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) &&
+        imported(m, n.expression.getText(m.source))?.specifier === "react" &&
+        imported(m, n.expression.getText(m.source))?.name === "useMemo"
+      ) {
+        const local = localEnvironment(callback, m, env);
+        for (const returned of returns(callback))
+          walk(returned, m, local, path, record, depth + 1);
+        return;
+      }
+      if (ts.isIdentifier(n.expression)) {
+        const ref = binding(m, n.expression.text),
+          fn = ref && functionFrom(ref.node);
+        if (
+          fn &&
+          !fn.modifiers?.some((a) => a.kind === ts.SyntaxKind.AsyncKeyword)
+        ) {
+          const local = localEnvironment(fn, ref.module, new Map());
+          for (const returned of returns(fn))
+            walk(returned, ref.module, local, path, record, depth + 1);
+        }
+      }
+    }
+  }
+  const env = new Map(
+    [...locals].map(([key, init]) => [key, { node: init, module, env: null }]),
+  );
+  for (const entry of env.values()) entry.env = env;
+  walk(node, module, env);
+  const options = [
+    ...new Map(
+      choices.map((c) => [c.value + "\0" + c.component.key, c]),
+    ).values(),
+  ];
+  return options.length > 1 && options.length <= 32
+    ? { options, variableKey: variables.size === 1 ? [...variables][0] : null }
+    : null;
+}

package/src/dependencies.mjs

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
 
-/** Loads one of this package's pinned dependencies (sharp is an optional peer). */
+/** Loads one of this package's pinned dependencies including the image encoder. */
 export function dependency(name) {
   try {
     return { value: require(name), resolve: (path) => require.resolve(path) };
@@ -13,7 +13,7 @@ export function dependency(name) {
     )
       throw error;
     throw new Error(
-      `Missing ${name}. Reinstall @tinkerlandai/indiana-iam with its dependencies${name === "sharp" ? ", and install sharp 0.35.5 to optimize public images" : ""}.`,
+      `Missing ${name}. Reinstall @tinkerlandai/indiana-iam with its dependencies.`,
     );
   }
 }

package/src/dom-payload-browser.mjs

@@ -0,0 +1,28 @@
+import { checkedDomPayload, parsedDomPayload } from "./dom-payload-json.mjs";
+
+/** The viewer decodes locally; it never fetches content or executes merchant code. */
+export async function documentDomBrowser(document) {
+  const payload = checkedDomPayload(document);
+  if (!payload) return { html: document.html, nodes: document.nodes };
+  if (typeof DecompressionStream !== "function") throw Error("Compressed IAM requires DecompressionStream support");
+  const binary = atob(payload.data);
+  if (btoa(binary) !== payload.data) throw Error("Noncanonical compressed DOM base64");
+  const compressed = Uint8Array.from(binary, character => character.charCodeAt(0));
+  const stream = new ReadableStream({ start(controller) { controller.enqueue(compressed); controller.close(); } }).pipeThrough(new DecompressionStream("gzip"));
+  const reader = stream.getReader(), chunks = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      total += next.value.byteLength;
+      if (total > payload.bytes) throw Error("Expanded DOM byte budget exceeded");
+      chunks.push(next.value);
+    }
+  } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+  if (total !== payload.bytes) throw Error("Expanded DOM byte length mismatch");
+  const decoded = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) { decoded.set(chunk, offset); offset += chunk.byteLength; }
+  return parsedDomPayload(new TextDecoder("utf-8", { fatal: true }).decode(decoded));
+}

package/src/dom-payload-json.mjs

@@ -0,0 +1,12 @@
+/** Shared with the offline viewer. Encodings describe storage, never executable code. */
+export function checkedDomPayload(document) {
+  const payload = document.domPayload;
+  if (!payload) return null;
+  if (document.html !== "" || !Array.isArray(document.nodes) || document.nodes.length || Object.keys(payload).sort().join(",") !== "bytes,data,encoding" || payload.encoding !== "gzip-json-v1" || !Number.isSafeInteger(payload.bytes) || payload.bytes < 1 || payload.bytes > 8_388_608 || typeof payload.data !== "string" || !payload.data.length || payload.data.length > 11_184_812 || payload.data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(payload.data)) throw Error("Invalid compressed DOM payload");
+  return payload;
+}
+export function parsedDomPayload(text) {
+  const value = JSON.parse(text);
+  if (!value || Object.keys(value).sort().join(",") !== "html,nodes" || typeof value.html !== "string" || value.html.length > 2_000_000 || !value.html.isWellFormed() || !Array.isArray(value.nodes) || value.nodes.length > 12000 || JSON.stringify(value) !== text) throw Error("Invalid expanded DOM payload");
+  return value;
+}

package/src/dom-payload.mjs

@@ -0,0 +1,50 @@
+import { gzip, Inflate } from "pako";
+import { checkedDomPayload, parsedDomPayload } from "./dom-payload-json.mjs";
+
+export const MAX_EXPANDED_DOM_BYTES = 33_554_432;
+
+/** Lossless, local decoding with a declared and enforced output bound. */
+export function documentDom(document) {
+  const payload = checkedDomPayload(document);
+  if (!payload) return { html: document.html, nodes: document.nodes };
+  const compressed = Buffer.from(payload.data, "base64");
+  if (compressed.toString("base64") !== payload.data) throw Error("Noncanonical compressed DOM base64");
+  const inflater = new Inflate({ windowBits: 31, chunkSize: 32_768 });
+  const chunks = [];
+  let total = 0;
+  inflater.onData = chunk => {
+    total += chunk.byteLength;
+    if (total > payload.bytes) throw Error("Expanded DOM byte budget exceeded");
+    chunks.push(chunk);
+  };
+  if (!inflater.push(compressed, true) || inflater.err || !inflater.ended) throw Error("Invalid compressed DOM stream: " + inflater.msg);
+  if (inflater.strm.avail_in !== 0) throw Error("Trailing compressed DOM data");
+  if (total !== payload.bytes) throw Error("Expanded DOM byte length mismatch");
+  const decoded = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) { decoded.set(chunk, offset); offset += chunk.byteLength; }
+  return parsedDomPayload(new TextDecoder("utf-8", { fatal: true }).decode(decoded));
+}
+
+export function assertDomBudget(documents) {
+  let total = 0;
+  for (const document of documents) {
+    const payload = checkedDomPayload(document);
+    total += payload ? payload.bytes : Buffer.byteLength(JSON.stringify({ html: document.html, nodes: document.nodes }));
+    if (total > MAX_EXPANDED_DOM_BYTES) throw Error("Expanded DOM aggregate byte budget exceeded");
+  }
+}
+
+/** Only sizeable, beneficial payloads are compressed; the original IDs and values survive byte-for-byte. */
+export function packDocumentDom(document) {
+  if (document.domPayload) return false;
+  const raw = Buffer.from(JSON.stringify({ html: document.html, nodes: document.nodes }));
+  if (raw.length < 16_384 || raw.length > 8_388_608) return false;
+  const zipped = gzip(raw, { level: 9, header: { time: 0, os: 255 } });
+  const payload = { encoding: "gzip-json-v1", bytes: raw.length, data: Buffer.from(zipped).toString("base64") };
+  if (Buffer.byteLength(JSON.stringify(payload)) + 1024 >= raw.length) return false;
+  document.html = "";
+  document.nodes = [];
+  document.domPayload = payload;
+  return true;
+}