@tinkerlandai/indiana-iam 0.3.0 → 0.5.0

package/src/anchors.mjs

@@ -25,6 +25,7 @@ export function instrumentableSource(file, text) {
   );
 }
 export const anchorSelectorPattern =
+  // eslint-disable-next-line no-control-regex -- Reject control bytes in source anchors and navigation targets.
   /^[a-z][a-z0-9-]*\[(?:id|data-testid|data-test|data-qa|data-indiana-id)="(?:[^"\\\x00-\x1f\x7f]|\\["\\])*"\]$/;
 
 export function anchorSelector(node) {
@@ -35,6 +36,7 @@ export function anchorSelector(node) {
       typeof value !== "string" ||
       !value ||
       value.length > 256 ||
+      // eslint-disable-next-line no-control-regex -- Reject control bytes in source anchors and navigation targets.
       /[\x00-\x1f\x7f]/.test(value) ||
       redactLiteral(value) !== value
     )

package/src/build-options.d.ts

@@ -14,7 +14,7 @@ export type IndianaIamBuildOptions = {
   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. */

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

@@ -4,12 +4,14 @@ import { dependency } from "./dependencies.mjs";
 import { hashObject, identity, sealDocument, sha256 } from "./integrity.mjs";
 import { refreshRenderHashes } from "./render-index.mjs";
 import { documentNodes, storeDocumentNodes } from "./node-hashes.mjs";
+import {assertStaticSvg} from './svg-preview.mjs';
+import {rasterMime} from './source-media.mjs';
 
 /** Keep one CSS copy in the single IAM file; document hashes pin its content-addressed key. */
 export function shareDocumentStyles(manifest){
  const counts=new Map();for(const doc of manifest.documents)if(doc.css)counts.set(doc.css,(counts.get(doc.css)||0)+1);
  const styles=new Map((manifest.styles||[]).map(style=>[style.styleKey,style]));
- for(const doc of manifest.documents){if((counts.get(doc.css)||0)<2)continue;const hash=sha256(doc.css),styleKey='style_'+hash;styles.set(styleKey,{styleKey,sha256:hash,css:doc.css});doc.styleKeys=[styleKey];doc.css='';sealDocument(doc);}
+ for(const doc of manifest.documents){if(!doc.css||(counts.get(doc.css)||0)<2&&!doc.styleKeys?.length)continue;const hash=sha256(doc.css),styleKey='style_'+hash;styles.set(styleKey,{styleKey,sha256:hash,css:doc.css});doc.styleKeys=[...new Set([styleKey,...(doc.styleKeys??[])])];doc.css='';sealDocument(doc);}
  if(styles.size)manifest.styles=[...styles.values()];
  refreshRenderHashes(manifest);
 }
@@ -30,8 +32,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,13 +47,13 @@ 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, previewImage = 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);
-    const optimized = publicImage && optimizePublicImages;
+    const optimized = previewImage || publicImage && optimizePublicImages;
     const maxInput = optimized ? 4_194_304 : 1_048_576;
     if (!stat.isFile() || stat.size > maxInput || (optimized ? publicSourceBytes + stat.size > 33_554_432 : total + stat.size > 6_291_456) || inputs.size >= 128) throw new Error("Build style budget exceeded");
     const bytes = await fs.readFile(real);
@@ -113,14 +115,53 @@ 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|svg)$/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 svg=file.toLowerCase().endsWith('.svg');
+        const input=await read(file,false,source,true);let bytes=input.bytes,mime=svg?'image/svg+xml':types.get(path.extname(file).toLowerCase());
+        if(svg)assertStaticSvg(bytes);
+        if(!svg){const actual=rasterMime(bytes);if(!actual)throw Error('Referenced raster signature mismatch');if(actual!==mime)manifest.coverage.gaps.push({code:'REFERENCED_IMAGE_TYPE_SNIFFED',file,detail:'Raster signature differs from its extension; preview uses the verified inert media type.'});mime=actual;}
+        if(svg||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');
+          if(!metadata.width||!metadata.height||metadata.width*metadata.height>16777216)throw Error('Referenced image pixel budget exceeded');
+          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 and reviewed static SVG: auto-orient, fit inside 800x800, WebP quality 90; source bytes remain hashed. Lossy preview, not original pixels.'});
+        }
+        if(bytes.length>1_048_576||(total+=bytes.length)>6_291_456)throw Error('Referenced image output budget exceeded');
+        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 +169,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 +183,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

@@ -65,7 +65,7 @@ export async function finishBuildRelease({
   mounts,
   publicDirectory,
   rootFont = "",
-  omitSvgResources = false,
+  omitSvgResources = true,
   upload = {},
   strict = false,
   logger = console,
@@ -75,7 +75,7 @@ export async function finishBuildRelease({
     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) {
@@ -83,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();

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: _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/document-material.mjs

@@ -0,0 +1,180 @@
+import { documentNodes } from "./node-hashes.mjs";
+import { documentDom } from "./dom-payload.mjs";
+import { sha256, canonical } from "./integrity.mjs";
+const resourceHashes = new WeakMap();
+export function previewResourceHash(kind, value) {
+  let hashes = resourceHashes.get(value);
+  if (!hashes) {
+    hashes = new Map();
+    resourceHashes.set(value, hashes);
+  }
+  if (!hashes.has(kind))
+    hashes.set(
+      kind,
+      sha256("iam/preview-resource/v1\0" + canonical({ kind, value })),
+    );
+  return hashes.get(kind);
+}
+/** Pure selected-render material. Caller owns immutable-source verification and authorization. */
+export function documentMaterial(
+  manifest,
+  pageKey,
+  renderKey,
+  knownResources = [],
+) {
+  const route = manifest.routeTree.routes.find(
+    (route) => route.routeKey === pageKey,
+  );
+  if (!route) throw Error("Unknown IAM preview route");
+  const render = manifest.routeTree.renders.find(
+    (render) =>
+      render.routeKey === pageKey &&
+      render.renderKey === (renderKey ?? route.initialRenderKey),
+  );
+  if (!render) throw Error("Unknown IAM preview render");
+  const document = manifest.documents.find(
+    (document) => document.documentKey === render.documentKey,
+  );
+  if (!document) throw Error("Missing IAM preview document");
+  const concreteNodes = documentNodes(document);
+  const elementKeys = new Set(concreteNodes.map((node) => node.elementKey));
+  const ui = manifest.routeTree.ui;
+  const collections =
+    ui?.collections?.filter((row) => row.renderKey === render.renderKey) ?? [];
+  const fragmentKeys = new Set(
+    collections.flatMap((row) => row.cases.map((item) => item.fragmentKey)),
+  );
+  const fragments =
+    ui?.fragments?.filter((row) => fragmentKeys.has(row.fragmentKey)) ?? [];
+  for (const fragment of fragments)
+    for (const key of fragment.sourceElements) elementKeys.add(key);
+  const nodeIds = new Set(concreteNodes.map((node) => node.nodeId));
+  const elements = manifest.elements.filter((element) =>
+    elementKeys.has(element.elementKey),
+  );
+  const componentKeys = new Set(
+    elements.map((element) => element.componentKey),
+  );
+  const styles =
+    manifest.styles?.filter((style) =>
+      document.styleKeys?.includes(style.styleKey),
+    ) ?? [];
+  const resourceText = [
+    documentDom(document).html,
+    document.css,
+    ...styles.map((style) => style.css),
+  ].join("\n");
+  const assetKeys = new Set(
+    [...resourceText.matchAll(/iam-asset:([a-z0-9_]+)/g)].map(
+      (match) => match[1],
+    ),
+  );
+  const scopeRows = (rows) =>
+    rows
+      .filter(
+        (row) =>
+          row &&
+          typeof row === "object" &&
+          ("renderKey" in row
+            ? row.renderKey === render.renderKey
+            : "routeKey" in row && row.routeKey === pageKey),
+      )
+      .map((row) => {
+        if (!row || typeof row !== "object") return row;
+        const source =
+          "source" in row && typeof row.source === "number"
+            ? manifest.routeTree.sourcePool?.[row.source]
+            : undefined;
+        const scopeKey =
+          "scopeKey" in row && typeof row.scopeKey === "number"
+            ? manifest.routeTree.scopePool?.[row.scopeKey]
+            : undefined;
+        return {
+          ...row,
+          ...(source ? { source } : {}),
+          ...(scopeKey ? { scopeKey } : {}),
+        };
+      });
+  const attributes =
+    ui?.attributes?.filter((row) => row.renderKey === render.renderKey) ?? [];
+  const attributeSetKeys = new Set(attributes.map((row) => row.setKey));
+  const conditionKeys = new Set(
+    [
+      ...documentDom(document).html.matchAll(/data-iam-condition="([^"]+)"/g),
+    ].map((match) => match[1]),
+  );
+  const routeTree = {
+    format: manifest.routeTree.format,
+    schemaVersion: manifest.routeTree.schemaVersion,
+    profile: manifest.routeTree.profile,
+    roots: [pageKey],
+    routes: [route],
+    renders: [render],
+    targets: manifest.routeTree.targets.filter(
+      (target) => target.renderKey === render.renderKey,
+    ),
+    variables: scopeRows(manifest.routeTree.variables),
+    bindings: scopeRows(manifest.routeTree.bindings),
+    transitions: scopeRows(manifest.routeTree.transitions),
+    states: scopeRows(manifest.routeTree.states),
+    navigation: scopeRows(manifest.routeTree.navigation),
+    uncovered: scopeRows(manifest.routeTree.uncovered),
+    renderNavigation: manifest.routeTree.renderNavigation.filter(
+      (edge) => edge.fromRenderKey === render.renderKey,
+    ),
+    ...(ui
+      ? {
+          ui: {
+            schemaVersion: ui.schemaVersion,
+            conditions: ui.conditions.filter((row) =>
+              conditionKeys.has(row.conditionKey),
+            ),
+            tabs: ui.tabs.filter((row) => row.renderKey === render.renderKey),
+            regions:
+              ui.regions?.filter((row) => row.renderKey === render.renderKey) ??
+              [],
+            navigation: ui.navigation.filter((row) => row.routeKey === pageKey),
+            collections,
+            fragments,
+            attributes,
+            attributeSets:
+              ui.attributeSets?.filter((row) =>
+                attributeSetKeys.has(row.setKey),
+              ) ?? [],
+          },
+        }
+      : {}),
+  };
+  const known = new Set(knownResources);
+  const resourceRefs = [];
+  const missing = (kind, values) =>
+    values.filter((value) => {
+      const hash = previewResourceHash(kind, value);
+      resourceRefs.push({ kind, hash });
+      return !known.has(hash);
+    });
+  return {
+    document,
+    elements,
+    styles: missing("styles", styles),
+    assets: missing(
+      "assets",
+      manifest.assets.filter((asset) => assetKeys.has(asset.assetKey)),
+    ),
+    scripts: missing(
+      "scripts",
+      manifest.scripts?.filter(
+        (script) => script.scriptKey === document.scriptKey,
+      ) ?? [],
+    ),
+    resourceRefs,
+    components: manifest.components.filter((component) =>
+      componentKeys.has(component.componentKey),
+    ),
+    interactions: manifest.interactions.filter(
+      (interaction) =>
+        interaction.pageKey === pageKey && nodeIds.has(interaction.nodeId),
+    ),
+    routeTree,
+  };
+}

package/src/dom-payload-json.mjs

@@ -2,11 +2,11 @@
 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");
+  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 || typeof payload.data !== "string" || !payload.data.length || 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");
+  if (!value || Object.keys(value).sort().join(",") !== "html,nodes" || typeof value.html !== "string" || !value.html.isWellFormed() || !Array.isArray(value.nodes) || JSON.stringify(value) !== text) throw Error("Invalid expanded DOM payload");
   return value;
 }

package/src/dom-payload.mjs

@@ -1,7 +1,7 @@
 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) {
@@ -31,7 +31,7 @@ export function assertDomBudget(documents) {
   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");
+    if (!Number.isSafeInteger(total)) throw Error("Invalid expanded DOM size");
   }
 }
 
@@ -39,7 +39,7 @@ export function assertDomBudget(documents) {
 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;
+  if (raw.length < 16_384) 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;