@tinkerlandai/indiana-iam 0.1.1 → 0.3.0

package/src/analyze.mjs

@@ -1,9 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { automaticSourceAnchors, anchorAttributes, sourceScriptKind } from "./anchors.mjs";
+import { sourceFiles } from "./source-files.mjs";
 import { dependency } from "./dependencies.mjs";
 import { assembleRouteTree, readVariables } from "./route-tree.mjs";
+import { sourceEntry } from "./source-entry.mjs";
 import { frameworkRoutes, externalImport } from "./framework-routes.mjs";
+import { sourceResolution } from "./source-resolution.mjs";
 import { routeIndexDigest, refreshRenderHashes } from "./render-index.mjs";
 import { storeDocumentNodes } from "./node-hashes.mjs";
 import { staticQuery } from "./static-query.mjs";
@@ -26,6 +29,28 @@ const { JSDOM } = dependency("jsdom").value;
 const UNKNOWN = Symbol("unknown");
 import { sensitiveName, redactLiteral, privateUrl } from "./privacy.mjs";
 const isUnknown = (value) => value === UNKNOWN;
+// React numeric styles use px except for unitless properties and CSS variables.
+const unitlessStyles = new Set("animationIterationCount aspectRatio borderImageOutset borderImageSlice borderImageWidth boxFlex boxFlexGroup boxOrdinalGroup columnCount columns flex flexGrow flexPositive flexShrink flexNegative flexOrder gridArea gridRow gridRowEnd gridRowSpan gridRowStart gridColumn gridColumnEnd gridColumnSpan gridColumnStart fontWeight lineClamp lineHeight opacity order orphans scale tabSize widows zIndex zoom fillOpacity floodOpacity stopOpacity strokeDasharray strokeDashoffset strokeMiterlimit strokeOpacity strokeWidth".split(" "));
+function staticStyle(value, unsupported) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    unsupported();
+    return "";
+  }
+  return Object.entries(value).flatMap(([key, raw]) => {
+    if (raw == null || typeof raw === "boolean" || raw === "") return [];
+    if (!/^(?:[a-zA-Z][a-zA-Z0-9]*|--[a-zA-Z0-9_-]+)$/.test(key) ||
+        !["string", "number"].includes(typeof raw) ||
+        (typeof raw === "number" && !Number.isFinite(raw)) ||
+        /[;{}<>\\]|url\s*\(|expression\s*\(|@import/i.test(String(raw))) {
+      unsupported();
+      return [];
+    }
+    const name = key.startsWith("--") ? key : key.replace(/[A-Z]/g, letter => "-" + letter.toLowerCase()).replace(/^ms-/, "-ms-");
+    const unprefixed = key.replace(/^(?:Webkit|Moz|ms|O)(?=[A-Z])/, "").replace(/^[A-Z]/, letter => letter.toLowerCase());
+    const unit = typeof raw === "number" && raw !== 0 && !key.startsWith("--") && !unitlessStyles.has(unprefixed) ? "px" : "";
+    return [name + ":" + String(raw).trim() + unit];
+  }).join(";");
+}
 const allowedTags = new Set(
   "main section article aside header footer nav div span p h1 h2 h3 h4 h5 h6 a button form label input select option textarea ul ol li dl dt dd table thead tbody tr th td caption fieldset legend details summary pre code blockquote strong em b i small s u mark time br hr img picture source svg path circle rect line polyline polygon ellipse g title".split(
     " ",
@@ -117,7 +142,8 @@ function functionFrom(node) {
   if (
     ts.isFunctionDeclaration(node) ||
     ts.isArrowFunction(node) ||
-    ts.isFunctionExpression(node)
+    ts.isFunctionExpression(node) ||
+    ts.isMethodDeclaration(node)
   )
     return node;
   if (ts.isCallExpression(node))
@@ -133,52 +159,11 @@ export async function analyze({
   maxFiles = 5000,
   maxBytes = 100_000_000,
   navigationPaths = [],
+  entry,
+  automaticAnchors = false,
 }) {
   root = await fs.realpath(root);
-  let files;
-  try {
-    files = execFileSync("git", ["-C", root, "ls-files", "-z"], {
-      encoding: "utf8",
-      maxBuffer: 8_000_000,
-      stdio: ["ignore", "pipe", "pipe"],
-    })
-      .split("\0")
-      .filter(Boolean);
-  } catch {
-    files = [];
-  }
-  // An authorized copied app can sit inside another repository's ignored
-  // verification directory. git succeeds there with an empty index; it must
-  // not silently turn a complete application into a zero-route manifest.
-  if (!files.length) {
-    async function walk(dir) {
-      for (const item of await fs.readdir(dir, { withFileTypes: true })) {
-        if (
-          item.name.startsWith(".") ||
-          ["node_modules", "dist", "build", "coverage"].includes(item.name)
-        )
-          continue;
-        const p = path.join(dir, item.name);
-        if (item.isDirectory()) await walk(p);
-        else if (item.isFile())
-          files.push(path.relative(root, p).split(path.sep).join("/"));
-      }
-    }
-    await walk(root);
-  }
-  files = files
-    .filter(
-      (file) =>
-        /\.(?:[cm]?[jt]sx?|css|mdx|json)$/.test(file) &&
-        !/(^|\/)(?:node_modules|\.next|\.git|\.indiana|api|server|secrets?)(\/|$)/.test(
-          file,
-        ) &&
-        !/(?:^|\/)(?:\.?env|credentials|secrets)(?:\.|\/)/i.test(file) &&
-        !file.startsWith('public/.well-known/indiana/')&&
-        !/(?:lock|package-lock)\.json$/.test(file),
-    )
-    .sort();
-  if (files.length > maxFiles) throw new Error("Source file budget exceeded");
+  const files = await sourceFiles(root, { maxFiles });
   const modules = new Map(),
     inventory = [],
     gaps = [],
@@ -232,12 +217,13 @@ export async function analyze({
       text,
       ts.ScriptTarget.Latest,
       true,
-      /\.jsx?$/.test(file) ? ts.ScriptKind.JSX : ts.ScriptKind.TSX,
+      sourceScriptKind(file, ts),
     );
     const module = {
       file,
       text,
       source,
+      anchors: automaticAnchors ? automaticSourceAnchors(file, source) : new Map(),
       bindings: new Map(),
       imports: new Map(),
       exports: new Map(),
@@ -268,6 +254,7 @@ export async function analyze({
       }
       if (ts.isFunctionDeclaration(statement) && (statement.name||statement.modifiers?.some(m=>m.kind===ts.SyntaxKind.DefaultKeyword)))
         module.bindings.set(statement.name?.text||'$default', statement);
+      if (ts.isEnumDeclaration(statement)) module.bindings.set(statement.name.text, statement);
       if (ts.isVariableStatement(statement))
         for (const d of statement.declarationList.declarations)
           if (ts.isIdentifier(d.name) && d.initializer)
@@ -366,10 +353,9 @@ export async function analyze({
     return binding(target,key,seen);
   }
   const componentDefs = new Map();
-  for (const module of modules.values())
-    for (const [symbol, node] of module.bindings) {
+  function registerComponent(module, symbol, node) {
       const fn = functionFrom(node);
-      if (!fn) continue;
+      if (!fn) return null;
       let hasJsx = false;
       function visit(n) {
         if (
@@ -381,7 +367,7 @@ export async function analyze({
         ts.forEachChild(n, visit);
       }
       visit(fn);
-      if (!hasJsx) continue;
+      if (!hasJsx) return null;
       const key = identity("component", { file: module.file, symbol }),
         ordinals = new Map();
       let ordinal = 0;
@@ -421,12 +407,21 @@ export async function analyze({
         source: loc,
         dependencies: [],
       });
-    }
-  for (const def of componentDefs.values()) {
+      return def;
+  }
+  for (const module of modules.values())
+    for (const [symbol, node] of module.bindings) registerComponent(module, symbol, node);
+  const resolution = sourceResolution({ ts, resolveModule, resolveBinding: binding });
+  const componentBinding = (module, name) => {
+    const ref = resolution.component(module, name);
+    if (ref?.wrapped) gap("LAZY_WRAPPER_UNOBSERVED", module.file, name + ": only the statically forwarded successful module is projected; retry/reload behavior is not executed");
+    return ref;
+  };
+  function collectComponentDependencies(def) {
     function collectDependencies(node) {
       if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
         const opening = ts.isJsxElement(node) ? node.openingElement : node,
-          ref = binding(def.module, opening.tagName.getText(def.module.source)),
+          ref = componentBinding(def.module, opening.tagName.getText(def.module.source)),
           target = ref && componentDefs.get(ref.module.file + "#" + ref.name);
         if (
           target &&
@@ -438,6 +433,20 @@ export async function analyze({
     }
     collectDependencies(def.fn);
   }
+  for (const def of componentDefs.values()) collectComponentDependencies(def);
+  const inlineNodes = new WeakMap(), inlineCounts = new Map();
+  function inlineComponent(module, node, route) {
+    if (inlineNodes.has(node)) return inlineNodes.get(node);
+    const group = module.file + "#" + route, occurrence = inlineCounts.get(group) ?? 0;
+    inlineCounts.set(group, occurrence + 1);
+    const symbol = "$route_" + hashObject("iam/inline-route-component/v1", { route, occurrence }).slice(0, 24);
+    module.bindings.set(symbol, node);
+    const def = registerComponent(module, symbol, node);
+    if (def) collectComponentDependencies(def);
+    const target = { file: module.file, symbol };
+    inlineNodes.set(node, target);
+    return target;
+  }
   function sourceLocation(module, node, symbol) {
     const loc = module.source.getLineAndCharacterOfPosition(
       node.getStart(module.source),
@@ -725,11 +734,16 @@ export async function analyze({
                 Object.hasOwn(Object(value), "stateInitial") &&
                 d.name.elements[0]
               ) {
-                const key = d.name.elements[0].name?.text;
+                const stateBinding = d.name.elements[0];
+                if (!ts.isBindingElement(stateBinding) || stateBinding.dotDotDotToken || !ts.isIdentifier(stateBinding.name)) {
+                  gap("STATE_BINDING_UNSUPPORTED", def.module.file, "Omitted, nested or rest state bindings have no named scalar value for UI simulation");
+                  continue;
+                }
+                const key = stateBinding.name.text;
                 ctx[key] = sensitiveName(key) ? UNKNOWN : value.stateInitial;
                 ctx.__iamStates.add(key);
                 ctx.__iamStateNodes[key] = d;
-                if (d.name.elements[1]?.name)
+                if (d.name.elements[1]?.name && !d.name.elements[1].dotDotDotToken && ts.isIdentifier(d.name.elements[1].name))
                   ctx.__iamSetters[d.name.elements[1].name.text] = key;
               }
             }
@@ -786,7 +800,10 @@ export async function analyze({
     !/^\/(?:[^/?#[\]\\\s]+\/)*[^/?#[\]\\\s]+$/.test(routing.basePath)
   )
     throw new Error("Invalid source basePath");
-  const compositions = frameworkRoutes({ modules, resolveModule, ts, sourceLocation, navigationPaths, gap });
+  const selection = await sourceEntry({ root, modules, resolveModule, ts, entry });
+  if (selection.htmlSource) inventory.push(selection.htmlSource);
+  inventory.sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+  const compositions = frameworkRoutes({ modules, ...selection, resolveModule, ts, sourceLocation, navigationPaths, gap, resolution, inlineComponent });
   const pageFiles = compositions.pageFiles;
   routing.framework = compositions.framework;
   if (compositions.routeSources) routing.routeSources = compositions.routeSources;
@@ -945,6 +962,20 @@ export async function analyze({
       const value = evalExpression(node, owner.module, ctx);
       return ["string", "boolean", "number"].includes(typeof value) ? { op: "const", value } : null;
     }
+    function uiExpressionType(expression, payload = {}) {
+      if (!expression) return undefined;
+      if (expression.op === "const") return typeof expression.value;
+      if (expression.op === "var") return ui.variables.find(variable => variable.variableKey === expression.key)?.valueType;
+      if (expression.op === "event") return payload[expression.key];
+      const type = child => uiExpressionType(child, payload);
+      if (expression.op === "not") return type(expression.arg) ? "boolean" : undefined;
+      if (expression.op === "classes") return expression.parts.every(part => type(part.when) === "boolean") ? "string" : undefined;
+      if (["all", "any"].includes(expression.op)) return expression.args.every(child => type(child) === "boolean") ? "boolean" : undefined;
+      const left = type(expression.left), right = type(expression.right);
+      if (["eq", "ne"].includes(expression.op)) return left && left === right ? "boolean" : undefined;
+      if (["add", "subtract"].includes(expression.op)) return left === "number" && right === "number" ? "number" : undefined;
+      return undefined;
+    }
     function uiHandler(initializer, owner, ctx) {
       let fn = initializer && ts.isJsxExpression(initializer) ? unwrap(initializer.expression) : null;
       if (fn && ts.isIdentifier(fn) && ctx.__iamPropHandlers.has(fn.text)) return ctx.__iamPropHandlers.get(fn.text);
@@ -966,8 +997,18 @@ export async function analyze({
       const payload = {};
       function eventInputs(e) { if (e.op === "event") payload[e.key] = e.key === "checked" ? "boolean" : "string"; for (const child of [e.arg, e.left, e.right, ...(e.args || []),...(e.parts||[]).map(part=>part.when)]) if (child) eventInputs(child); }
       eventInputs(value);
+      if (uiExpressionType(value, payload) !== ui.variables.find(variable => variable.variableKey === variableKey)?.valueType) return null;
       return { variableKey, value, payload };
     }
+    function unobservedValue(node, owner, instance) {
+      const source = sourceLocation(owner.module, node, owner.symbol);
+      const elementKey = identity("element", { component: owner.key, unobservedValue: node.getStart(owner.module.source) - owner.fn.getStart(owner.module.source) });
+      const nodeId = identity("node", { page: pageKey, element: elementKey, instance });
+      elements.set(elementKey, { elementKey, componentKey: owner.key, tag: "span", source, identityStrategy: "provisional_ast_ordinal", editableProperties: [], binding: "preview_only" });
+      record.set(nodeId, { elementKey, source, synthetic: true });
+      // Preserve an unknown child boundary. An empty projection must never prove that replacing text is safe.
+      return '<span data-iam-node="' + nodeId + '" hidden=""></span>';
+    }
     function renderExpr(node, owner, ctx, instance, depth) {
       node = unwrap(node);
       if (!node) return "";
@@ -1117,7 +1158,7 @@ export async function analyze({
             .join("");
         }
         gap("DYNAMIC_COLLECTION", m.file, node.expression.getText(m.source));
-        return "";
+        return unobservedValue(node, owner, instance);
       }
       if (!ts.isJsxElement(node) && !ts.isJsxSelfClosingElement(node)) {
         if (
@@ -1141,18 +1182,25 @@ export async function analyze({
           typeof value !== "boolean"
         )
           return escape(value);
-        if (isUnknown(value))
+        if (isUnknown(value)) {
           gap("DYNAMIC_VALUE", m.file, node.getText(m.source).slice(0, 100));
+          return unobservedValue(node, owner, instance);
+        }
         return "";
       }
       if (++renderedCount > 12000)
         throw new Error("Rendered node budget exceeded");
       const opening = ts.isJsxElement(node) ? node.openingElement : node,
         tag = opening.tagName.getText(m.source),
-        props = {}, uiHandlers = [], uiBindings = [], forwardedHandlers=[];
+        props = m.anchors.get(opening) ? { "data-indiana-id": m.anchors.get(opening) } : {}, uiHandlers = [], uiBindings = [], forwardedHandlers=[];
       for (const attr of opening.attributes.properties) {
         if (ts.isJsxSpreadAttribute(attr)) {
           const v = evalExpression(attr.expression, m, ctx);
+          if (isUnknown(v)) {
+            for (const attribute of anchorAttributes) delete props[attribute];
+            gap("UNKNOWN_ANCHOR_SPREAD", m.file, "Opaque spread may override element identity");
+            continue;
+          }
           if (v && typeof v === "object") {
             Object.assign(props, v);
             const inherited = forwarded.get(v);
@@ -1252,7 +1300,7 @@ export async function analyze({
         : props.children?.iamChildren || "";
       if (ctx[tag]?.iamChildren !== undefined) return ctx[tag].iamChildren;
       const routerPrimitive = externalImport(m, tag);
-      if (["react-router", "react-router-dom"].includes(routerPrimitive?.specifier) && routerPrimitive.name === "Outlet") return ctx.__iamOutlet?.iamChildren ?? "";
+      if (["react-router", "react-router-dom", "@tanstack/react-router"].includes(routerPrimitive?.specifier) && routerPrimitive.name === "Outlet") return ctx.__iamOutlet?.iamChildren ?? "";
       if (
         /^(?:ThemeProvider|Providers?|Analytics|TailwindIndicator|Toaster)$/.test(
           tag,
@@ -1267,7 +1315,7 @@ export async function analyze({
         props["data-iam-adapter"] = tag;
       }
       if (/^[A-Z]/.test(tag) && !intrinsicAlias) {
-        if (tag === "Link" || ["react-router", "react-router-dom"].includes(routerPrimitive?.specifier) && ["Link", "NavLink"].includes(routerPrimitive.name)) {
+        if (tag === "Link" || ["react-router", "react-router-dom", "@tanstack/react-router"].includes(routerPrimitive?.specifier) && ["Link", "NavLink"].includes(routerPrimitive.name)) {
           htmlTag = "a";
           if (typeof props.to === "string") props.href = props.to;
         }
@@ -1286,7 +1334,7 @@ export async function analyze({
             .filter((v) => typeof v === "string")
             .join(" ");
         } else {
-          const ref = binding(m, tag),
+          const ref = componentBinding(m, tag),
             target = ref && componentDefs.get(ref.module.file + "#" + ref.name);
           if (target) {
             const own = components.get(owner.key);
@@ -1313,40 +1361,30 @@ export async function analyze({
         }
       }
       if (!allowedTags.has(htmlTag)) return children;
-      const anchor = ["data-indiana-id", "data-testid", "id", "name"]
+      const anchor = anchorAttributes
         .map((key) =>
           typeof props[key] === "string" ? key + "=" + props[key] : null,
         )
         .find(Boolean);
       const ordinal = owner.ordinals.get(node) ?? 0,
-        explicitAnchor = anchor && !anchor.startsWith('name='),
-        elementKey = identity("element", {
+        explicitAnchor = Boolean(anchor);
+      let elementKey = identity("element", {
           component: owner.key,
           tag,
           anchor: explicitAnchor ? anchor : "jsx:" + ordinal,
         });
+      const source = sourceLocation(m, node, owner.symbol);
+      const prior = elements.get(elementKey);
+      if (prior && (prior.source.file !== source.file || prior.source.line !== source.line || prior.source.column !== source.column)) {
+        // Keep both concrete source sites. The DOM uniqueness check makes duplicate anchors read-only.
+        elementKey = identity("element", { component: owner.key, tag, anchor, ordinal });
+        gap("AMBIGUOUS_ELEMENT_ANCHOR", m.file, tag);
+      }
       const nodeId = identity("node", {
           page: pageKey,
           element: elementKey,
           instance,
-        }),
-        source = sourceLocation(m, node, owner.symbol);
-      const prior = elements.get(elementKey);
-      if (
-        explicitAnchor &&
-        prior &&
-        (prior.source.file !== source.file ||
-          prior.source.line !== source.line ||
-          prior.source.column !== source.column)
-      )
-        throw new Error(
-          "Ambiguous explicit element anchor " +
-            anchor +
-            " in " +
-            m.file +
-            ":" +
-            source.line,
-        );
+        });
       elements.set(elementKey, {
         elementKey,
         componentKey: owner.key,
@@ -1369,6 +1407,11 @@ export async function analyze({
       }
       for (const binding of uiBindings.filter(b => ["value", "checked", "disabled", "className"].includes(b.property))) {
         if(['value','checked'].includes(binding.property)&&!['input','select','textarea'].includes(htmlTag)){gap('UI_BINDING_TARGET_UNSUPPORTED',m.file,tag+': input property cannot be simulated on a non-input adapter');continue;}
+        const expectedType = ["checked", "disabled"].includes(binding.property) ? "boolean" : "string";
+        if (uiExpressionType(binding.value) !== expectedType) {
+          gap("UI_BINDING_TYPE_UNSUPPORTED", m.file, tag + "." + binding.property + ": source value cannot be represented by the typed UI simulation");
+          continue;
+        }
         ui.bindings.push({ bindingKey: identity("ui-binding", { node: nodeId, property: binding.property }), routeKey: pageKey, nodeId, elementKey, ...binding });
       }
       const sensitiveInput = htmlTag === "input" && (["password", "hidden"].includes(String(props.type).toLowerCase()) || sensitiveName(String(props.name || props.id || "")));
@@ -1380,6 +1423,12 @@ export async function analyze({
       }
       const attrs = { "data-iam-node": nodeId };
       for (const [key, value] of Object.entries(props)) {
+        if (key === "style") {
+          const css = staticStyle(value, () => gap("INLINE_STYLE_UNSUPPORTED", m.file,
+            "Inline style at line " + source.line + ": only static CSS values without resource URLs are reconstructed"));
+          if (css) attrs.style = css;
+          continue;
+        }
         if (isUnknown(value) || value == null || typeof value === "object")
           continue;
         if (["href", "src"].includes(key) && privateUrl(value)) {
@@ -1400,7 +1449,7 @@ export async function analyze({
             clipRule: "clip-rule",
           }[key] || key;
         if (
-          !/^(?:class|id|name|type|placeholder|value|title|alt|href|src|role|for|disabled|hidden|checked|width|height|viewBox|d|fill|stroke|stroke-width|stroke-linecap|stroke-linejoin|fill-rule|clip-rule|cx|cy|r|x|y|x1|x2|y1|y2|points|aria-[a-z-]+|data-indiana-id|data-testid|data-iam-(?:adapter|toggle))$/.test(
+          !/^(?:class|id|name|type|placeholder|value|title|alt|href|src|role|for|disabled|hidden|checked|width|height|viewBox|d|fill|stroke|stroke-width|stroke-linecap|stroke-linejoin|fill-rule|clip-rule|cx|cy|r|x|y|x1|x2|y1|y2|points|aria-[a-z-]+|data-indiana-id|data-indiana-map-(?:area|flow|kind|auth|edge)|data-testid|data-test|data-qa|data-iam-(?:adapter|toggle))$/.test(
             attr,
           )
         )
@@ -1442,16 +1491,24 @@ export async function analyze({
       );
     }
     function renderEntry(file, props, instance, symbol) {
-      const entryModule = modules.get(file), entryRef = entryModule && binding(entryModule, symbol ?? entryModule.defaultName);
+      const entryModule = modules.get(file), entryRef = entryModule && componentBinding(entryModule, symbol ?? entryModule.defaultName);
       const entryDef = entryRef && componentDefs.get(entryRef.module.file + "#" + entryRef.name);
-      if (!entryDef) { gap("PAGE_NO_JSX", file, "Composition entry has no inspectable JSX; null defaults are inert"); return ""; }
+      if (!entryDef) {
+        if (entryRef) {
+          const key = identity("component", { file: entryRef.module.file, symbol: entryRef.name });
+          if (!components.has(key)) components.set(key, { componentKey: key, file: entryRef.module.file, name: entryRef.name, source: sourceLocation(entryRef.module, entryRef.node, entryRef.name), dependencies: [] });
+        }
+        gap("PAGE_NO_JSX", file, "Composition entry has no inspectable JSX; null defaults are inert");
+        return "";
+      }
       return renderComponent(entryDef, props, instance, 0);
     }
     function renderBranch(branch) {
       let content = renderEntry(branch.file, {}, branch === composition.composition ? "page" : "slot-page:" + branch.file, branch.symbol);
       for (const layer of branch.layers) {
-        const props = { children: { iamChildren: content } };
-        if (routing.framework === "react-router") props.__iamOutlet = { iamChildren: content };
+        const props = ["react-router", "tanstack-router"].includes(routing.framework)
+          ? { __iamOutlet: { iamChildren: content } }
+          : { children: { iamChildren: content } };
         if (/^(?:src\/)?pages\/_app\.[jt]sx?$/.test(layer.file)) { props.Component = { iamChildren: content }; props.pageProps = {}; }
         for (const slot of layer.slots) {
           props[slot.name] = { iamChildren: renderBranch(slot.branch) };
@@ -1487,6 +1544,27 @@ export async function analyze({
     const dom = new JSDOM(
       "<!doctype html><html><body>" + html + "</body></html>",
     );
+    // JSX children may be forwarded more than once, and HTML repair may clone
+    // an invalid nested anchor. Each concrete occurrence needs a unique node;
+    // ambiguous copies remain preview-only and have no simulated state bridge.
+    const occurrences = new Map();
+    for (const element of dom.window.document.querySelectorAll("[data-iam-node]")) {
+      const id = element.getAttribute("data-iam-node");
+      const matches = occurrences.get(id) ?? [];
+      matches.push(element);
+      occurrences.set(id, matches);
+    }
+    for (const [original, matches] of occurrences) {
+      if (matches.length < 2) continue;
+      const rec = record.get(original);
+      if (!rec) throw Error("Unknown repeated source node");
+      gap("REPEATED_SOURCE_INSTANCE", rec.source.file, "Repeated forwarded children or HTML repair: copies are preview-only without a state bridge");
+      for (const [index, element] of matches.entries()) {
+        const id = identity("node", { page: pageKey, original, occurrence: index });
+        element.setAttribute("data-iam-node", id);
+        record.set(id, { ...rec, synthetic: true });
+      }
+    }
     const nodes = [];
     function collect(node, parentId, index) {
       if (node.nodeType !== 1 && node.nodeType !== 3) return null;
@@ -1712,7 +1790,7 @@ export async function analyze({
     schemaVersion: 2,
     producer: {
       name: "indiana-app-manifest-local",
-      version: "0.16.0",
+      version: "0.19.0",
       method: "typescript-ast-and-bounded-static-projection",
     },
     app: { name, platforms: ["web"] },

package/src/anchors.mjs

@@ -0,0 +1,127 @@
+import { dependency } from "./dependencies.mjs";
+import { sha256 } from "./integrity.mjs";
+import { redactLiteral } from "./privacy.mjs";
+
+export const anchorAttributes = [
+  "id",
+  "data-testid",
+  "data-test",
+  "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" &&
+    Buffer.byteLength(text) <= 1_000_000 &&
+    /\.[cm]?[jt]sx?$/.test(file) &&
+    !/(?:^|\/)(?:node_modules|\.next|\.git|\.indiana|api|server|secrets?)(?:\/|$)/.test(
+      file,
+    )
+  );
+}
+export const anchorSelectorPattern =
+  /^[a-z][a-z0-9-]*\[(?:id|data-testid|data-test|data-qa|data-indiana-id)="(?:[^"\\\x00-\x1f\x7f]|\\["\\])*"\]$/;
+
+export function anchorSelector(node) {
+  if (node.kind !== "element") return null;
+  for (const attribute of anchorAttributes) {
+    const value = node.attributes[attribute];
+    if (
+      typeof value !== "string" ||
+      !value ||
+      value.length > 256 ||
+      /[\x00-\x1f\x7f]/.test(value) ||
+      redactLiteral(value) !== value
+    )
+      continue;
+    const selector = `${node.tag}[${attribute}="${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"]`;
+    if (selector.length <= 512) return selector;
+  }
+  return null;
+}
+
+/** A semantic source fingerprint; never line numbers, absolute paths or sibling ordinals. */
+export function automaticSourceAnchors(file, source) {
+  if (!instrumentableSource(file, source.text)) return new Map();
+  const ts = dependency("typescript").value;
+  const candidates = [],
+    groups = new Map();
+  function owner(node) {
+    for (let parent = node.parent; parent; parent = parent.parent) {
+      if (!ts.isFunctionLike(parent)) continue;
+      if (parent.name && ts.isIdentifier(parent.name)) return parent.name.text;
+      if (
+        ts.isVariableDeclaration(parent.parent) &&
+        ts.isIdentifier(parent.parent.name)
+      )
+        return parent.parent.name.text;
+      if (
+        ts.isExportAssignment(parent.parent) ||
+        parent.modifiers?.some(
+          (modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword,
+        )
+      )
+        return "default";
+    }
+    return "module";
+  }
+  const shapes = new WeakMap();
+  function shape(node) {
+    if (shapes.has(node)) return shapes.get(node);
+    let value;
+    if (ts.isJsxText(node))
+      value = [node.kind, node.text.replace(/\s+/g, " ").trim()];
+    else if (
+      ts.isIdentifier(node) ||
+      ts.isStringLiteral(node) ||
+      ts.isNumericLiteral(node)
+    )
+      value = [node.kind, node.text];
+    else {
+      const children = [];
+      ts.forEachChild(node, (child) => {
+        if (!ts.isJsxText(child) || child.text.trim())
+          children.push(shape(child));
+      });
+      value = [node.kind, ...children];
+    }
+    const digest = sha256(JSON.stringify(value));
+    shapes.set(node, digest);
+    return digest;
+  }
+  function visit(node) {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const tag = opening.tagName.getText(source);
+      if (
+        /^[a-z][a-z0-9-]*$/.test(tag) &&
+        !["html", "head", "script", "style", "link", "meta"].includes(tag) &&
+        !opening.attributes.properties.some(
+          (attribute) =>
+            ts.isJsxAttribute(attribute) &&
+            anchorAttributes.includes(attribute.name.getText(source)),
+        )
+      ) {
+        const signature =
+          file.replaceAll("\\", "/") + "\0" + owner(node) + "\0" + shape(node);
+        const anchor =
+          "iam_" + sha256("iam/build-anchor/v1\0" + signature).slice(0, 32);
+        candidates.push({ opening, anchor });
+        groups.set(anchor, (groups.get(anchor) ?? 0) + 1);
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  // Identical source sites cannot be disambiguated by their position. Leave them read-only.
+  return new Map(
+    candidates
+      .filter((candidate) => groups.get(candidate.anchor) === 1)
+      .map(({ opening, anchor }) => [opening, anchor]),
+  );
+}

package/src/build-options.d.ts

@@ -4,6 +4,10 @@ import type { BuildLogger } from "./index.js";
 export type IndianaIamBuildOptions = {
   /** Set false to build without generating an IAM. */
   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). */
@@ -15,6 +19,9 @@ export type IndianaIamBuildOptions = {
   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. */