@tinkerlandai/indiana-iam 0.1.1 → 0.3.0

package/README.md

@@ -40,7 +40,14 @@ Point the visual SDK at the descriptor:
 
 `next dev` and other phases leave your config unchanged. Add `public/.well-known/indiana/` to `.gitignore`.
 
-## Vite and React Router
+No developer harness or business SDK npm dependency is needed. The public script above runs the visual runtime;
+Indiana owns authorization, immutable uploads and experiment publication.
+IAM does not discover or launch merchant harnesses, test scripts, agents, browsers or development servers. It does
+not import merchant modules to execute them. Source enumeration and optional Git commit labels use filesystem reads;
+the package starts no external commands and works without a Git executable. Developers' explicitly configured
+framework callbacks remain part of their normal build.
+
+## Vite, React Router and TanStack Router
 
 ```js
 // vite.config.mjs
@@ -49,14 +56,41 @@ import { indianaIam } from "@tinkerlandai/indiana-iam/vite";
 export default { plugins: [indianaIam()] };
 ```
 
+Use an ESM Vite config (`vite.config.mjs` or `vite.config.mts`, or a project with `"type": "module"`).
+CommonJS configs cannot `require` this ESM package.
+
 Client builds expose `import.meta.env.INDIANA_IAM_RELEASE_URL` and write the descriptor into the build output folder.
 Server builds are skipped.
 
+Browser apps use the single local module script in `index.html` to select reachable router and React root declarations.
+For multiple entry points, set `indianaIam({ entry: "src/main.tsx" })`, or pass `--entry src/main.tsx` to standalone generation.
+The path must stay inside the scanned root. Next.js uses its App/Pages root instead.
+
 ## Options
 
-Both integrations accept `{ enabled, name, strict, rootFont, omitSvgResources, logger, apiKey, baseUrl, upload }`;
+Both integrations accept `{ enabled, name, automaticAnchors, strict, rootFont, omitSvgResources, logger, apiKey, baseUrl, upload, client }`;
+browser applications additionally accept `entry`;
 `withIndianaIam` also takes `root`. By default a source the scanner cannot read prints a warning and the build continues without an IAM;
 `strict: true` fails the build instead. The same source always produces the same release ID and IAM bytes.
+If source changes during compilation, generation fails instead of publishing a descriptor for different code.
+
+## Target identity and release changes
+
+Framework builds reuse `id`, `data-testid`, `data-test`, `data-qa`, then `data-indiana-id`. When none is declared,
+the source loader adds a deterministic `data-indiana-id` to unambiguous native JSX in the build output and IAM.
+Source files stay unchanged; formatting, comments and unrelated sibling insertions preserve a leaf's marker.
+Set `automaticAnchors: false` to use only existing attributes.
+
+Repeated component instances, identical source sites, unknown props and duplicate DOM selectors cannot prove a
+unique target and remain read-only. React `key` contributes source evidence but is not a DOM selector or a global ID;
+dynamic keys are never evaluated a second time or exposed as customer identifiers. Supported routing and state
+coverage stays bounded and explicit.
+
+The visual runtime requests delivery for the page's exact IAM digest. Indiana rebinds saved changes only when the
+route, composition, target selector, element content and render uniqueness still match. Text changes also require
+unchanged subtree content. A failure excludes the whole experiment for that release; it does not renormalize
+variation weights or rewrite authored pins. Old deployments keep their own bindings during a rolling release.
+The Console reports incompatible references for review. Local extraction does not certify arbitrary runtime data.
 
 ## Other builds
 
@@ -67,12 +101,26 @@ indiana-iam prepare --root .
 indiana-iam anchor --root . --out <plan.json> [--apply]
 ```
 
-`anchor` adds reviewable `data-indiana-id` attributes to JSX elements so saved changes keep targeting the same elements
-across releases.
+Standalone generation uses existing attributes. Custom builds can pair `transformSourceForIam(code, relativeFile)`
+with `generateAppManifest({ root, automaticAnchors: true })`; use both on the same original source. `anchor` is an
+optional command for explicit source annotations. Next and Vite do not need that command or a harness.
 
 ## Scope
 
-Supported source: Next.js App Router and Pages Router, and React Router / single-root React apps built with Vite.
+Supported source: Next.js App Router and Pages Router, React Router / single-root React apps built with Vite,
+and statically generated TanStack file-route trees registered with `createRouter({ routeTree })`.
+React Router supports imported static path constants, inline `Component` functions and source-proven lazy import forwarding.
+TanStack reads the registered generated tree, including pathless layouts, index routes and simple `$param` paths;
+custom history/basepath and complex parameter patterns require separate adapters. Loaders, guards, retry/reload behavior
+and runtime data remain unobserved. Unsupported optional React paths are isolated as gaps.
+The complete validated IAM must fit within 8 MiB; oversized projections fail without emitting a truncated artifact.
+Large artifacts store sizeable HTML/preorder-map pairs as `domPayload` (`gzip-json-v1`), while keeping `html: ""`
+and `nodes: []` in that document's wire record. This lossless storage encoding preserves all source IDs, DOM values,
+HTML/DOM hashes and targets. The document hash pins its encoded storage body; decoding is local and bounded to
+8 MiB per payload and 32 MiB in aggregate. The final IAM file limit stays 8 MiB. Exported page HTML is expanded.
+Use the matching 0.3 generator, validator and viewer together. Indiana ingestion/viewer sources must be updated
+before uploading compressed artifacts; publishing this npm package alone does not deploy Indiana. The offline
+viewer uses the browser's built-in `DecompressionStream` and never fetches a decoder or merchant content.
 The scanner reads source files only; it never runs your build, imports your code or reads env files. Only the upload
 step calls Indiana, and only when a key is set.
 Values that look like credentials, tokens, emails or private URLs are removed, but review what your pages contain.
@@ -81,13 +129,61 @@ Values that look like credentials, tokens, emails or private URLs are removed, b
 
 Create a Key with only the `app-manifests:write` permission (Console → developer settings) and set it as
 `INDIANA_IAM_KEY` in your build environment. Each production build then registers the IAM, stores it through a
-server-signed URL and asks Indiana to validate it; the validated version becomes the environment's current version.
+server-signed URL and asks Indiana to validate it; the validated version becomes its client's current version.
 Rebuilding unchanged source only makes the existing version current again.
 
+An App environment can hold several clients, each a named build with its own current version: for example `web` and
+`web-dashboard`, or later `ios` and `android` apps. Set the `client` option (or `INDIANA_IAM_CLIENT`) to 1-40 lowercase
+letters, digits or hyphens starting with a letter; the default is `web`. A client keeps the platform of its first
+upload, and the same IAM bytes cannot be uploaded for two clients.
+
 - Uploads go to `https://tinker.cash`; set `INDIANA_IAM_BASE_URL` (or the `baseUrl` option) for another Indiana
   environment.
 - On Vercel only production deployments upload by default; `upload: "always"` uploads every build and
   `upload: false` never uploads.
 - A failed upload prints a warning and the build continues, unless `strict: true`.
 - The App's Owner or Admin must turn on the App page map first.
-- `INDIANA_IAM_KEY=<key> indiana-iam upload --file <manifest>` uploads a file generated elsewhere.
+- `INDIANA_IAM_KEY=<key> indiana-iam upload --file <manifest> [--client <key>]` uploads a file generated elsewhere.
+
+## App map annotations
+
+The Console App map groups pages into areas, shows recorded navigation, and opens a main-path workbench before
+opening a page editor. Thumbnails are static source projections. They do not execute authentication, data loaders,
+form submissions or application code.
+
+Optional static attributes preserve product intent that cannot be established from a URL alone:
+
+| Attribute                                          | Location                                 | Meaning                                                                                                           |
+| -------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `data-indiana-map-area`                            | Page root                                | Functional area label; otherwise the first URL segment groups the directory.                                      |
+| `data-indiana-map-flow`                            | Page root                                | Display name for the process containing this page.                                                                |
+| `data-indiana-map-kind="login"`                    | Page root                                | Declares an authentication page.                                                                                  |
+| `data-indiana-map-auth="public\|required"`         | Page root                                | Declares the page's access requirement. Omission remains unknown.                                                 |
+| `data-indiana-map-edge="step\|tab\|login\|return"` | An existing link or supported UI control | Classifies an existing recorded action. It never invents a destination or makes an unsupported action executable. |
+
+Use one consistent declaration on the outer page element. Native `role="tab"` also classifies a Tab control.
+A link Tab retains its exact destination URL, including query and fragment; a supported state-writing Tab remains
+an in-page action. Login and return links remain separate from ordinary steps. Unsupported actions appear as
+unknown outcomes. Authentication requirements are display declarations, not proof of a session or runtime access.
+
+```tsx
+<main
+  data-indiana-map-area="Workspace"
+  data-indiana-map-flow="Create project"
+  data-indiana-map-auth="required"
+>
+  <a href="/login?next=%2Fprojects" data-indiana-map-edge="login">
+    Sign in
+  </a>
+  <a href="/projects/configure" data-indiana-map-edge="step">
+    Continue
+  </a>
+  <a href="/projects?tab=activity" role="tab">
+    Activity
+  </a>
+</main>
+```
+
+An unambiguous source path can continue automatically until a branch or cycle. Explicit step links take precedence
+over ordinary navigation; login/return links and Tabs are inspected separately. A new IAM build is needed to add
+these annotations to an already uploaded version. Existing immutable versions are never rewritten.

package/assets/viewer.js

@@ -489,6 +489,44 @@ async function mountIamViewer(m, consoleContext) {
   }
   // Verify the compact source document first, then derive its exact v1 hashes.
   // Work is page-local and cancellable; hashes never become another saved authority.
+  /* BEGIN COMPRESSED DOM */
+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;
+}
+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;
+}
+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));
+}
+  /* END COMPRESSED DOM */
   /* BEGIN HTML DOM DERIVATION */
 function expandDomNodes(document, body) {
   if(document.nodeEncoding!=='html-preorder-v1'||document.nodeHashMode!=='derived-v1'||!document.sourceMappingsHash||document.nodes.length>12000)throw Error('Invalid HTML-derived DOM mode');
@@ -507,6 +545,14 @@ function expandDomNodes(document, body) {
 }
   /* END HTML DOM DERIVATION */
   async function expandNodeHashes(document,request) {
+    if (document.domPayload) {
+      const {hashes, ...body} = document;
+      if (await hash("iam/document/v1\0" + canonical(body)) !== hashes.document) throw Error("Compressed document hash mismatch");
+      const decoded = await documentDomBrowser(document);
+      if (await hash(decoded.html) !== hashes.html || await hash("iam/dom-map/v1\0" + canonical({rootNodeId: document.rootNodeId, nodes: decoded.nodes, sourceMappingsHash: document.sourceMappingsHash})) !== hashes.dom) throw Error("Expanded DOM hash mismatch");
+      const {domPayload, ...plain} = document;
+      document = {...plain, ...decoded};
+    }
     if(!Array.isArray(document.nodes)||document.nodes.length>12000)throw Error('Node hash budget');
     const nodes=expandDomNodes(document,new DOMParser().parseFromString('<!doctype html><html><body>'+document.html+'</body></html>','text/html').body),byId=new Map(nodes.map(node=>[node.nodeId,node]));
     if(byId.size!==nodes.length)throw Error('Duplicate node');
@@ -601,7 +647,8 @@ function expandDomNodes(document, body) {
     if (data.type === "open-page" && typeof data.routeKey === "string") {
       const next = m.pages.find(p => p.pageKey === data.routeKey);
       if (!next) return;
-      const variableRender=m.routeTree.variables.find(variable=>variable.variableKey===data.variableKey)?.renderKey??consoleContext?.catalog?.graph.variables.find(variable=>variable.id===data.variableKey)?.renderKey;
+      if(typeof data.renderKey==="string"&&!m.routeTree.renders.some(r=>r.routeKey===next.pageKey&&r.renderKey===data.renderKey))return;
+      const variableRender=typeof data.renderKey==="string"?data.renderKey:m.routeTree.variables.find(variable=>variable.variableKey===data.variableKey)?.renderKey??consoleContext?.catalog?.graph.variables.find(variable=>variable.id===data.variableKey)?.renderKey;
       const targetUrl=typeof data.url==="string"?data.url:(next.pageKey===page.pageKey?currentUrl:next.route);
       if (!doc || next.pageKey !== page.pageKey || variableRender && variableRender!==render?.renderKey || targetUrl!==currentUrl) openPage(next,targetUrl,variableRender);
       else consoleContext?.resume?.();
@@ -801,8 +848,14 @@ function expandDomNodes(document, body) {
   if (m.documents.length) {
     const initialRequest = {};
     pendingDocument = initialRequest;
-    m.documents = await Promise.all(m.documents.map(document => expandNodeHashes(document, initialRequest)));
+    const expandedBytes = m.documents.reduce((total, document) => total + (document.domPayload?.bytes ?? new TextEncoder().encode(JSON.stringify({html:document.html,nodes:document.nodes})).byteLength), 0);
+    if (!Number.isSafeInteger(expandedBytes) || expandedBytes > 33_554_432) throw Error("Expanded DOM aggregate byte budget exceeded");
+    // Sequential decoding bounds peak memory for a multi-route artifact.
+    const expandedDocuments = [];
+    for (const document of m.documents) expandedDocuments.push(await expandNodeHashes(document, initialRequest));
+    m.documents = expandedDocuments;
     pendingDocument = null;
+    renderNav();
   }
   openPage(page,consoleContext?.initialPage?.url??page.route,consoleContext?.initialPage?.renderKey??consoleContext?.catalog?.graph.variables.find(variable=>variable.id===consoleContext.initialPage?.variableKey)?.renderKey);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinkerlandai/indiana-iam",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Build-time Indiana App Manifest (IAM) generator for Next.js and Vite apps: scans source after the production build and writes the IAM and its release descriptor.",
   "license": "UNLICENSED",
   "repository": {
@@ -46,6 +46,8 @@
     "ajv": "6.15.0",
     "css-tree": "3.2.1",
     "jsdom": "26.1.0",
+    "magic-string": "0.30.21",
+    "pako": "3.0.2",
     "tailwind-merge": "3.7.0",
     "tailwindcss": "4.3.3",
     "typescript": "5.9.3"