@ui-manifest-json/core 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrainRidge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @ui-manifest-json/core
+
+The shared `UiManifest` schema — as TypeScript types — plus the framework-agnostic helpers every
+extractor builds on.
+
+**You don't usually install this directly.** [`@ui-manifest-json/angular`][ng] and
+[`@ui-manifest-json/react`][react] depend on it. Install it on its own when you're *consuming*
+manifests and want the types, or writing an extractor for another framework.
+
+```bash
+npm install @ui-manifest-json/core
+```
+
+## What's in it
+
+```ts
+import type { UiManifest, RouteNode, ComponentNode, DomNode } from '@ui-manifest-json/core';
+
+const manifest: UiManifest = JSON.parse(await readFile('ui-manifest.json', 'utf8'));
+```
+
+The full shape is documented field by field in [docs/schema.md][schema]. The types are the source of
+truth; that page is the tour.
+
+Three runtime helpers ship alongside the types:
+
+| Export | What it does |
+|---|---|
+| `resolveRouteDependencyTree` | Splices each component's template into its parent's where the child's tag appears, recursively, with component-boundary and cycle markers. Framework-agnostic: you supply a `matchFn` that decides which tag maps to which component. |
+| `resolveFullPaths` | Walks a nested route tree and annotates each node with the full path a URL must have to reach it, `baseHref` applied. |
+| `collectRepoProvenance` / `generatorProvenance` | Reads the commit, remote, branch, dirty state and app root out of the git working tree, and the build id out of CI. Best-effort: outside a git tree every field is simply absent, which means the manifest is unpinned rather than that anything failed. |
+
+## Schema version
+
+`SCHEMA_VERSION` is `"2.0"`. A manifest carries it as `schemaVersion`, and it is the one field to
+check before trusting the rest — v2 made `app.baseHref` and `app.routerMode` required, and without
+those a route path cannot be matched against a real URL at all.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+[ng]: https://www.npmjs.com/package/@ui-manifest-json/angular
+[react]: https://www.npmjs.com/package/@ui-manifest-json/react
+[schema]: https://github.com/BrainRidge/ui-manifest/blob/main/docs/schema.md

package/dist/full-path.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve every route's `fullPath` from the nested route tree.
+ *
+ * Framework-agnostic on purpose: Angular's `children`/`loadChildren` and React Router's nested
+ * `<Route>`/`children` produce the same `RouteNode` tree, so the join rule is the same and lives
+ * once. Both extractors call this after their own parsing.
+ */
+import type { RouteNode } from './types/route.js';
+/**
+ * Annotate `routes` (in place, recursively) with `fullPath`.
+ *
+ * `baseHref` is prepended so the result is what a URL actually looks like, not what the route
+ * config says — those differ for every app not served from the root, and the difference is
+ * invisible until a consumer tries to match a real URL and matches nothing.
+ *
+ * A wildcard gets no `fullPath` at all rather than an empty or synthesised one: it is a fallback,
+ * not a screen, and a consumer walking `fullPath` should skip it without having to know the
+ * convention.
+ *
+ * Note a wildcard's CHILDREN are still resolved. A `**` with children is unusual but legal, and the
+ * children are reachable even though the parent segment is not a location.
+ */
+export declare function resolveFullPaths(routes: RouteNode[], baseHref?: string): RouteNode[];
+//# sourceMappingURL=full-path.d.ts.map

package/dist/full-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"full-path.d.ts","sourceRoot":"","sources":["../src/full-path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAYlD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,QAAQ,SAAM,GAAG,SAAS,EAAE,CAYjF"}

package/dist/full-path.js

@@ -0,0 +1,38 @@
+/** Route paths that match anything and therefore identify nothing. */
+const WILDCARDS = new Set(['**', '*']);
+function join(parent, segment) {
+    const left = parent.replace(/\/+$/, '');
+    const right = segment.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (!right)
+        return left || '/';
+    return `${left}/${right}`;
+}
+/**
+ * Annotate `routes` (in place, recursively) with `fullPath`.
+ *
+ * `baseHref` is prepended so the result is what a URL actually looks like, not what the route
+ * config says — those differ for every app not served from the root, and the difference is
+ * invisible until a consumer tries to match a real URL and matches nothing.
+ *
+ * A wildcard gets no `fullPath` at all rather than an empty or synthesised one: it is a fallback,
+ * not a screen, and a consumer walking `fullPath` should skip it without having to know the
+ * convention.
+ *
+ * Note a wildcard's CHILDREN are still resolved. A `**` with children is unusual but legal, and the
+ * children are reachable even though the parent segment is not a location.
+ */
+export function resolveFullPaths(routes, baseHref = '/') {
+    const base = `/${baseHref.replace(/^\/+/, '').replace(/\/+$/, '')}`.replace(/^\/$/, '');
+    const walk = (nodes, parent) => {
+        for (const node of nodes) {
+            const segment = node.path ?? '';
+            const here = WILDCARDS.has(segment.trim()) ? parent : join(parent, segment);
+            if (!WILDCARDS.has(segment.trim()))
+                node.fullPath = here || '/';
+            if (node.children?.length)
+                walk(node.children, here);
+        }
+    };
+    walk(routes, base);
+    return routes;
+}

package/dist/index.d.ts

@@ -1,8 +1,15 @@
 export * from './types/dom.js';
+export * from './types/source.js';
+export * from './types/uncapturable.js';
 export * from './types/component.js';
 export * from './types/route.js';
+export * from './types/provenance.js';
 export * from './types/dependency-graph.js';
 export * from './types/manifest.js';
+export { resolveFullPaths } from './full-path.js';
+export { collectRepoProvenance, generatorProvenance } from './provenance.js';
+export type { CollectProvenanceOptions } from './provenance.js';
+export { collapseDom, enrichDom, controlTypeFor, selectorCandidatesFor, testidOf, TESTID_ATTRS } from './semantics.js';
 export { resolveRouteDependencyTree } from './resolve-tree.js';
 export type { MatchFn } from './resolve-tree.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,qBAAqB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACvH,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,6 +1,12 @@
 export * from './types/dom.js';
+export * from './types/source.js';
+export * from './types/uncapturable.js';
 export * from './types/component.js';
 export * from './types/route.js';
+export * from './types/provenance.js';
 export * from './types/dependency-graph.js';
 export * from './types/manifest.js';
+export { resolveFullPaths } from './full-path.js';
+export { collectRepoProvenance, generatorProvenance } from './provenance.js';
+export { collapseDom, enrichDom, controlTypeFor, selectorCandidatesFor, testidOf, TESTID_ATTRS } from './semantics.js';
 export { resolveRouteDependencyTree } from './resolve-tree.js';

package/dist/provenance.d.ts

@@ -0,0 +1,17 @@
+import type { GeneratorProvenance, RepoProvenance } from './types/provenance.js';
+export interface CollectProvenanceOptions {
+    /**
+     * Where the extractor is scanning. Becomes `appRoot`, relative to the repository root — and it
+     * is also the directory git is asked FROM, which matters more than it looks: `--dir` can point
+     * at a checkout that is not the one the command was run in, and asking git about the current
+     * directory would then pin the manifest to a completely unrelated repository's HEAD. That is the
+     * worst failure available here, because the result looks exactly like a correct pin.
+     */
+    targetDir: string;
+    /** Only a fallback origin for `appRoot` when the target is not in a git tree at all. */
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function collectRepoProvenance(options: CollectProvenanceOptions): RepoProvenance;
+export declare function generatorProvenance(name: string, version: string, passes: string[], env?: NodeJS.ProcessEnv): GeneratorProvenance;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoDjF,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,cAAc,CAsCvF;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EAAE,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,mBAAmB,CAGrB"}

package/dist/provenance.js

@@ -0,0 +1,104 @@
+/**
+ * Collect `RepoProvenance` from the git working tree, and `buildId` from CI.
+ *
+ * Every field is best-effort and every failure is silent-but-absent. This runs against arbitrary
+ * checkouts — a tarball with no `.git`, a shallow CI clone, a machine with no `git` on PATH — and
+ * none of those is an error: they mean the manifest is unpinned, which is a fact about the output
+ * rather than a failure to produce it. The one thing never done here is substituting a plausible
+ * value for a missing one: a branch name in place of a commit would look like a pin and move.
+ *
+ * `git` is invoked directly rather than via a dependency. It is one process per field, already on
+ * every machine that has a checkout to read, and the alternative is a dependency in a package whose
+ * whole appeal is that it has almost none.
+ */
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { relative } from 'node:path';
+/**
+ * Resolve symlinks, or return the path unchanged.
+ *
+ * `git rev-parse --show-toplevel` reports a REAL path, so on any platform where the checkout sits
+ * under a symlink the two disagree and `relative()` produces an escape-hatch path full of `..`.
+ * macOS makes this the common case rather than an edge one — `/tmp` and `/var` are both symlinks
+ * into `/private` — so a manifest generated in a temp checkout would report an `appRoot` naming
+ * the developer's filesystem instead of a subtree of the repo.
+ */
+function realpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path; // the directory may not exist yet; a non-resolvable path is not a failure here
+    }
+}
+/** Run one git command, or return undefined. Never throws, never prints. */
+function git(args, cwd) {
+    try {
+        const out = execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        });
+        const value = out.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The build identifier of the CI run, if this is one.
+ *
+ * Ordered by specificity, not popularity: a run id identifies one execution, where a build number
+ * can repeat across re-runs. Absent locally, which is correct — a developer's laptop has no build.
+ */
+function detectBuildId(env) {
+    return (env.GITHUB_RUN_ID ??
+        env.BUILD_BUILDID ?? // Azure Pipelines
+        env.CI_PIPELINE_ID ?? // GitLab
+        env.BUILDKITE_BUILD_ID ??
+        env.CIRCLE_WORKFLOW_ID ??
+        undefined);
+}
+export function collectRepoProvenance(options) {
+    const cwd = realpath(options.cwd);
+    const targetDir = realpath(options.targetDir);
+    // Every git question is asked from the SCANNED tree, not from the process's cwd — see
+    // `targetDir` above.
+    const root = git(['rev-parse', '--show-toplevel'], targetDir);
+    if (!root) {
+        // Not a git working tree. `appRoot` is still worth reporting relative to cwd — a consumer
+        // knowing which directory was scanned is useful even when it cannot know which commit.
+        const appRoot = relative(cwd, targetDir) || '.';
+        return { appRoot };
+    }
+    const commit = git(['rev-parse', 'HEAD'], targetDir);
+    // `--porcelain` is empty for a clean tree. Only meaningful once we know we have a commit:
+    // "dirty" without one says nothing a consumer can use.
+    const status = commit ? git(['status', '--porcelain'], targetDir) : undefined;
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], targetDir);
+    const provenance = {
+        remoteUrl: git(['remote', 'get-url', 'origin'], targetDir),
+        commit,
+        // Committer date, ISO 8601 strict. Not the author date: two commits can share an author date
+        // after a rebase, and what orders two manifests is when the code landed.
+        commitTime: commit ? git(['show', '-s', '--format=%cI', 'HEAD'], targetDir) : undefined,
+        // A detached HEAD reports "HEAD", which is not a branch name and should not be recorded as one.
+        branch: branch && branch !== 'HEAD' ? branch : undefined,
+        dirty: commit ? Boolean(status) : undefined,
+        appRoot: relative(root, targetDir) || '.',
+    };
+    // Absent, not null/empty: a consumer testing `if (provenance.commit)` should not have to also
+    // test for the empty string, and JSON with explicit nulls everywhere reads as though something
+    // failed rather than as though it was never available.
+    for (const key of Object.keys(provenance)) {
+        if (provenance[key] === undefined)
+            delete provenance[key];
+    }
+    return provenance;
+}
+export function generatorProvenance(name, version, passes, env = process.env) {
+    const buildId = detectBuildId(env);
+    return buildId ? { name, version, buildId, passes } : { name, version, passes };
+}

package/dist/semantics.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The pass that turns a raw parse tree into something a consumer can JOIN against a live DOM.
+ *
+ * Framework-agnostic on purpose: both extractors produce the same `DomNode` union, and every rule
+ * here reads only that union. Angular's parser and React's differ entirely in how they find a
+ * conditional; by the time a tree reaches this module the conditional is a `TemplateNode` either
+ * way.
+ *
+ * Three things happen here, and each removes work a consumer would otherwise have to do — wrongly,
+ * and once per consumer:
+ *
+ * **Static text is folded into its element.** A `<button>Sign In</button>` parses as an element
+ * with a text child. Keyed on its own, that button has no handle at all: no id, no name, no
+ * testid — which describes most buttons in most apps. Folding the text up is what makes it
+ * addressable. An interpolation is deliberately NOT folded: a key built from `{{ user.name }}`
+ * changes with the test data.
+ *
+ * **Ancestry is denormalized.** Every structural branch between the root and an element is copied
+ * onto that element as `conditionChain`. This is what lets the tree drop presentational wrappers
+ * without losing anything, and it is what turns "why is this field not on the page?" from a
+ * repository search into a field read.
+ *
+ * **Handles are enumerated, and their absence is reported.** `tokenStability: "none"` on a control
+ * means the source offers no stable way to address it. With a file and a line attached, that is
+ * the single most actionable line this whole format produces: *add a `data-testid` here*.
+ */
+import type { ControlType, DomNode, ElementNode, SelectorCandidate } from './types/dom.js';
+/**
+ * Drop presentational wrappers, splicing their children into their place.
+ *
+ * Safe only because `conditionChain` is denormalized onto every element: nothing downstream needs
+ * the ancestors this removes. Run BEFORE enrichment so text folding and uniqueness both see the
+ * final tree. Returns how many nodes went, because a consumer must be able to tell that the tree
+ * it is reading is not the DOM.
+ */
+export declare function collapseDom(nodes: DomNode[]): {
+    dom: DomNode[];
+    collapsed: number;
+};
+/** The attribute names a test-id may be spelled with, in the order a consumer should prefer. */
+export declare const TESTID_ATTRS: readonly ["data-testid", "data-test-id", "data-test", "data-qa", "data-cy"];
+export declare function testidOf(attrs: Record<string, string>): string | undefined;
+/**
+ * What a person can DO with this element.
+ *
+ * Driven off the tag and `type` rather than the role attribute, because the role is usually
+ * absent and the tag almost never is. `<input type="submit">` is a BUTTON — it is spelled as an
+ * input but it submits, and treating it as a textbox is how a submit control ends up expected to
+ * accept typing.
+ */
+export declare function controlTypeFor(el: string, attrs: Record<string, string>): ControlType | undefined;
+/** Every handle the SOURCE offers for this element, best first. Audit material, not a locator. */
+export declare function selectorCandidatesFor(node: ElementNode, staticText?: string): SelectorCandidate[];
+/**
+ * Walk a parsed tree and enrich every element in place.
+ *
+ * Returns every element it visited, in template order, so the caller can run whole-template passes
+ * (uniqueness) without walking again. Order is template order because two elements sharing a
+ * handle should collide in a stable order rather than whichever the walk happened to reach first.
+ */
+export declare function enrichDom(nodes: DomNode[]): ElementNode[];
+//# sourceMappingURL=semantics.d.ts.map

package/dist/semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics.d.ts","sourceRoot":"","sources":["../src/semantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EACK,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EACpE,MAAM,gBAAgB,CAAC;AAoCxB;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG;IAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CA4BnF;AAED,gGAAgG;AAChG,eAAO,MAAM,YAAY,6EAA8E,CAAC;AAExG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAM1E;AAKD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,GAAG,SAAS,CAwBjG;AAUD,kGAAkG;AAClG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAejG;AA2FD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAqEzD"}

package/dist/semantics.js

@@ -0,0 +1,325 @@
+/** Attributes that make an element addressable, and so make it worth keeping. */
+const MEANINGFUL_ATTRS = [
+    'id', 'name', 'placeholder', 'role', 'title', 'href', 'src', 'type', 'value', 'for',
+    'routerLink', 'formControlName', 'formGroupName', 'formArrayName',
+];
+/**
+ * A node that exists only to position other nodes.
+ *
+ * The rule is narrow on purpose. A `div` holding nothing but a class and OTHER ELEMENTS is
+ * layout; a `div` holding text is the text's element, and dropping it would leave the text with
+ * nothing to hang on — including, decisively, nothing for a `conditionChain` to be attached to.
+ * `<div class="error-message">{{ errorMessage }}</div>` under an `*ngIf` is the whole answer to
+ * "why is this not on the page?", and it looks exactly like a wrapper until you notice it wraps
+ * no element.
+ */
+function isPresentationalWrapper(node) {
+    const tag = node.el.toLowerCase();
+    if (tag !== 'div' && tag !== 'span')
+        return false;
+    if (node.el.includes('-'))
+        return false;
+    if (node.events.length || node.props.length)
+        return false;
+    if (node.refs?.length)
+        return false;
+    for (const key of Object.keys(node.attrs)) {
+        if (key === 'class' || key === 'style')
+            continue;
+        if (key.startsWith('aria-') || key.startsWith('data-'))
+            return false;
+        if (MEANINGFUL_ATTRS.includes(key))
+            return false;
+        return false;
+    }
+    // It must wrap at least one ELEMENT, and carry no text of its own.
+    const hasElementChild = node.children.some(c => c.type === 'element' || c.type === 'template');
+    const hasOwnText = node.children.some(c => c.type === 'text' || c.type === 'interpolation');
+    return hasElementChild && !hasOwnText;
+}
+/**
+ * Drop presentational wrappers, splicing their children into their place.
+ *
+ * Safe only because `conditionChain` is denormalized onto every element: nothing downstream needs
+ * the ancestors this removes. Run BEFORE enrichment so text folding and uniqueness both see the
+ * final tree. Returns how many nodes went, because a consumer must be able to tell that the tree
+ * it is reading is not the DOM.
+ */
+export function collapseDom(nodes) {
+    let collapsed = 0;
+    const rewrite = (list) => {
+        const out = [];
+        for (const node of list) {
+            if (node.type === 'template') {
+                node.children = rewrite(node.children);
+                for (const branch of node.branches ?? [])
+                    branch.children = rewrite(branch.children);
+                out.push(node);
+                continue;
+            }
+            if (node.type !== 'element') {
+                out.push(node);
+                continue;
+            }
+            node.children = rewrite(node.children);
+            if (isPresentationalWrapper(node)) {
+                collapsed += 1;
+                out.push(...node.children);
+                continue;
+            }
+            out.push(node);
+        }
+        return out;
+    };
+    return { dom: rewrite(nodes), collapsed };
+}
+/** The attribute names a test-id may be spelled with, in the order a consumer should prefer. */
+export const TESTID_ATTRS = ['data-testid', 'data-test-id', 'data-test', 'data-qa', 'data-cy'];
+export function testidOf(attrs) {
+    for (const name of TESTID_ATTRS) {
+        const value = attrs[name];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+/** Tags that are interactive by nature, so an element bearing one is a control even with no role. */
+const CONTROL_TAGS = new Set(['input', 'select', 'textarea', 'button', 'a', 'option']);
+/**
+ * What a person can DO with this element.
+ *
+ * Driven off the tag and `type` rather than the role attribute, because the role is usually
+ * absent and the tag almost never is. `<input type="submit">` is a BUTTON — it is spelled as an
+ * input but it submits, and treating it as a textbox is how a submit control ends up expected to
+ * accept typing.
+ */
+export function controlTypeFor(el, attrs) {
+    const tag = el.toLowerCase();
+    const type = (attrs.type ?? '').toLowerCase();
+    if (tag === 'a')
+        return 'link';
+    if (tag === 'button')
+        return 'button';
+    if (tag === 'textarea')
+        return 'textbox';
+    if (tag === 'select')
+        return attrs.multiple !== undefined ? 'listbox' : 'combobox';
+    if (tag === 'input') {
+        if (type === 'checkbox')
+            return 'checkbox';
+        if (type === 'radio')
+            return 'radio';
+        if (type === 'file')
+            return 'fileinput';
+        if (type === 'range')
+            return 'slider';
+        if (type === 'date' || type === 'datetime-local' || type === 'month' || type === 'week')
+            return 'datepicker';
+        // submit/button/reset/image are buttons wearing an input's tag.
+        if (type === 'submit' || type === 'button' || type === 'reset' || type === 'image')
+            return 'button';
+        return 'textbox';
+    }
+    const role = (attrs.role ?? '').toLowerCase();
+    if (role === 'button' || role === 'link' || role === 'checkbox' || role === 'radio'
+        || role === 'combobox' || role === 'listbox' || role === 'textbox' || role === 'tab'
+        || role === 'grid' || role === 'slider') {
+        return role;
+    }
+    return undefined;
+}
+function isControl(node) {
+    const tag = node.el.toLowerCase();
+    if (CONTROL_TAGS.has(tag))
+        return true;
+    if (node.attrs.role)
+        return true;
+    // A custom element wired to a click is a control however it is spelled.
+    return node.events.some(e => e.kind !== 'twoWayWriteback');
+}
+/** Every handle the SOURCE offers for this element, best first. Audit material, not a locator. */
+export function selectorCandidatesFor(node, staticText) {
+    const out = [];
+    const { attrs } = node;
+    const tag = node.el.toLowerCase();
+    const push = (by, value) => out.push({ by, value, unique: false, uniqueScope: 'template' });
+    const testid = testidOf(attrs);
+    if (testid)
+        push('testid', `[data-testid="${testid}"]`);
+    if (attrs.id)
+        push('id', `#${attrs.id}`);
+    if (attrs.name)
+        push('name', `${tag}[name="${attrs.name}"]`);
+    if (attrs['aria-label'])
+        push('aria', `${tag}[aria-label="${attrs['aria-label']}"]`);
+    if (attrs.placeholder)
+        push('placeholder', `${tag}[placeholder="${attrs.placeholder}"]`);
+    if (staticText)
+        push('text', staticText);
+    return out;
+}
+/**
+ * Mark which candidates are unique WITHIN THIS TEMPLATE.
+ *
+ * Scoped to the template and labelled as such, because that is the only claim a static pass can
+ * honestly make: one page is composed of a shell plus a route component, so a value unique in its
+ * own file can still collide once rendered. Saying `uniqueScope: "template"` is the difference
+ * between a weaker claim and a wrong one.
+ */
+function markUniqueness(elements) {
+    const counts = new Map();
+    for (const el of elements) {
+        for (const c of el.selectorCandidates ?? []) {
+            counts.set(`${c.by} ${c.value}`, (counts.get(`${c.by} ${c.value}`) ?? 0) + 1);
+        }
+    }
+    for (const el of elements) {
+        for (const c of el.selectorCandidates ?? []) {
+            c.unique = counts.get(`${c.by} ${c.value}`) === 1;
+        }
+    }
+}
+/**
+ * Does this element carry a stable handle, an expression-derived one, or none at all?
+ *
+ * `none` is the interesting answer and the reason this field exists: reported with a file and a
+ * line it becomes an actionable finding, where the same element simply missing from a join reads
+ * as noise.
+ */
+function tokenStabilityFor(node, staticText) {
+    const { attrs } = node;
+    if (testidOf(attrs) || attrs.id || attrs.name || attrs['aria-label'] || attrs.placeholder || staticText) {
+        return 'static';
+    }
+    const dynamic = node.props.find(p => p.name === 'id' || p.name === 'attr.id' || p.name === 'name' || p.name === 'attr.name'
+        || TESTID_ATTRS.some(t => p.name === t || p.name === `attr.${t}`));
+    if (dynamic)
+        return 'dynamic';
+    return isControl(node) ? 'none' : undefined;
+}
+/** The literal prefix of a dynamic handle, e.g. `[attr.id]="'tx-' + tx.id"`. */
+function tokenTemplateFor(node) {
+    const dynamic = node.props.find(p => p.name === 'id' || p.name === 'attr.id'
+        || TESTID_ATTRS.some(t => p.name === t || p.name === `attr.${t}`));
+    if (!dynamic)
+        return undefined;
+    const literal = /^\s*['"]([^'"]+)['"]\s*\+/.exec(dynamic.expr);
+    return literal ? `${literal[1]}{{*}}` : undefined;
+}
+/**
+ * An accessible name, and ONLY when the source actually declares one.
+ *
+ * Deliberately not falling back to `staticText`, which is the obvious version and is wrong. A
+ * consumer keys an element on the best handle it has, and an accessible name outranks raw text —
+ * so synthesising one from a caption turns `<button>Sign In</button>` into an `aria:Sign In` key,
+ * while a browser recording the same button (it has no `aria-label`) produces a `text:Sign In`
+ * one. The two never join, and they fail to join on exactly the elements whose only handle is
+ * their caption. `staticText` carries the caption; let the consumer decide what it is worth.
+ */
+function accessibleNameFor(node) {
+    return node.attrs['aria-label'] || node.attrs.title || undefined;
+}
+function isTruthyAttr(value) {
+    return value !== undefined && value !== 'false';
+}
+/** The gate a `TemplateNode` represents, as one link in a chain. */
+function linkFor(node, branch) {
+    return {
+        directive: node.structural,
+        expr: node.condition ?? '',
+        ...(branch ? { branch } : {}),
+        ...(node.source ? { source: node.source } : {}),
+    };
+}
+/** `@for`'s condition is written `item of items; track id` — split it back apart. */
+function repeatPartsOf(condition) {
+    if (!condition)
+        return {};
+    const match = /^\s*(\S+)\s+of\s+([^;]+?)\s*(?:;\s*track\s+(.+))?\s*$/.exec(condition);
+    if (!match)
+        return { over: condition.trim() || undefined };
+    return { varName: match[1], over: match[2]?.trim(), trackBy: match[3]?.trim() };
+}
+/**
+ * Walk a parsed tree and enrich every element in place.
+ *
+ * Returns every element it visited, in template order, so the caller can run whole-template passes
+ * (uniqueness) without walking again. Order is template order because two elements sharing a
+ * handle should collide in a stable order rather than whichever the walk happened to reach first.
+ */
+export function enrichDom(nodes) {
+    const seen = [];
+    const walk = (list, chain, repeat) => {
+        for (const node of list) {
+            if (node.type === 'template') {
+                const t = node;
+                const isFor = t.structural === '@for' || t.structural === '*ngFor' || t.structural === '.map()';
+                const parts = isFor ? repeatPartsOf(t.condition) : {};
+                const nextRepeat = isFor ? { ...parts, on: true } : repeat;
+                // The primary branch's children hang off `children`; every other branch off `branches`.
+                // `branches[0]` IS `children` for an @if/@switch, so walking both would visit the primary
+                // twice and give its elements a duplicated chain link.
+                walk(t.children, [...chain, linkFor(t)], nextRepeat);
+                for (const branch of (t.branches ?? []).slice(1)) {
+                    walk(branch.children, [...chain, linkFor(t, branch.label)], nextRepeat);
+                }
+                continue;
+            }
+            if (node.type !== 'element')
+                continue;
+            const el = node;
+            const staticParts = [];
+            let hasDynamicText = false;
+            for (const child of el.children) {
+                if (child.type === 'text' && child.value.trim())
+                    staticParts.push(child.value.trim());
+                if (child.type === 'interpolation')
+                    hasDynamicText = true;
+            }
+            const staticText = staticParts.join(' ').trim() || undefined;
+            if (staticText)
+                el.staticText = staticText;
+            if (hasDynamicText)
+                el.hasDynamicText = true;
+            const controlType = controlTypeFor(el.el, el.attrs);
+            if (controlType)
+                el.controlType = controlType;
+            const accessibleName = accessibleNameFor(el);
+            if (accessibleName)
+                el.accessibleName = accessibleName;
+            if (el.attrs.role)
+                el.role = el.attrs.role;
+            if (isTruthyAttr(el.attrs.required))
+                el.required = true;
+            if (el.el.includes('-'))
+                el.sourceRepresentation = el.el;
+            const stability = tokenStabilityFor(el, staticText);
+            if (stability)
+                el.tokenStability = stability;
+            const template = stability === 'dynamic' ? tokenTemplateFor(el) : undefined;
+            if (template)
+                el.tokenTemplate = template;
+            const candidates = selectorCandidatesFor(el, staticText);
+            if (candidates.length)
+                el.selectorCandidates = candidates;
+            if (chain.length) {
+                el.conditional = true;
+                el.conditionChain = chain;
+            }
+            if (repeat.on) {
+                el.repeated = true;
+                if (repeat.over)
+                    el.repeatOver = repeat.over;
+                if (repeat.varName)
+                    el.repeatVar = repeat.varName;
+                if (repeat.trackBy)
+                    el.repeatTrackBy = repeat.trackBy;
+            }
+            seen.push(el);
+            walk(el.children, chain, repeat);
+        }
+    };
+    walk(nodes, [], { on: false });
+    markUniqueness(seen);
+    return seen;
+}

package/dist/types/component.d.ts

@@ -1,4 +1,5 @@
 import type { DomNode } from './dom.js';
+import type { SourcePointer } from './source.js';
 export type PropertyBindingKind = 'decorator' | 'signal';
 /** An Angular @Input()/@Output() or input()/output() signal. */
 export interface PropertyBinding {
@@ -21,6 +22,15 @@ export interface ComponentNode {
     className: string;
     /** Repo-relative path to the file the component is defined in. */
     filePath: string;
+    /** The class declaration, with lines. `filePath` says which file; this says where in it. */
+    source?: SourcePointer;
+    /** The TEMPLATE, which for an external `templateUrl` is a different file entirely — and is
+     *  where every element's own pointer lands. Without this a consumer reading a component's
+     *  location gets the `.ts`, and every element in it points somewhere else. */
+    template?: {
+        source: SourcePointer;
+        inline: boolean;
+    };
     /** Angular only. */
     selector?: string;
     /** Angular only. */

package/dist/types/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/types/component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEzD,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,oDAAoD;IACpD,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,oDAAoD;IACpD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,iFAAiF;IACjF,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;CACjB"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/types/component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEzD,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;kFAE8E;IAC9E,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IACtD,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,oDAAoD;IACpD,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,oDAAoD;IACpD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,iFAAiF;IACjF,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;CACjB"}

package/dist/types/dom.d.ts

@@ -9,6 +9,7 @@
  *   control-flow detection) rather than a grammar built for the purpose. Best-effort — the
  *   underlying JS could always route around the pattern in a way that isn't detected.
  */
+import type { SourcePointer } from './source.js';
 export type Extraction = 'compiler' | 'heuristic';
 export interface BaseNode {
     extraction: Extraction;
@@ -17,6 +18,17 @@ export interface BaseNode {
 export interface BoundExpr {
     name: string;
     expr: string;
+    /**
+     * What kind of binding this is.
+     *
+     * `[(ngModel)]` desugars into a property AND an event, and in v2 the write-back was
+     * indistinguishable from a real handler — so a consumer counting handlers got 20 where the app
+     * had 7, and every two-way-bound input looked interactive twice. `twoWayWriteback` marks the
+     * generated half.
+     */
+    kind?: 'dom' | 'output' | 'twoWay' | 'twoWayWriteback';
+    /** Where the handler METHOD is declared — the `.ts` file, not the template. */
+    handler?: SourcePointer;
 }
 /**
  * `Child` is generic so the resolved dependency-graph tree (packages/core/src/types/
@@ -36,7 +48,61 @@ export interface ElementNode<Child = DomNode> extends BaseNode {
     /** Template reference variables (#ref). Angular only. */
     refs?: string[];
     children: Child[];
+    /** Where this element is written. */
+    source?: SourcePointer;
+    /** STATIC child text only, folded from `TextNode` children and trimmed. An interpolation is
+     *  never text: a key built from one changes with the test data. */
+    staticText?: string;
+    /** True when any child was an interpolation — so "no staticText" can be told apart from
+     *  "the text is dynamic". */
+    hasDynamicText?: boolean;
+    /** `static`: a stable handle exists. `dynamic`: a token-bearing attribute is an expression
+     *  (`[attr.id]="'tx-' + tx.id"`), and `tokenTemplate` carries the literal prefix. `none`: this
+     *  control has no stable handle at all — which is the most actionable thing this file says. */
+    tokenStability?: 'static' | 'dynamic' | 'none';
+    tokenTemplate?: string;
+    controlType?: ControlType;
+    /** The tag as WRITTEN, when it differs from what renders (`mat-select` -> a listbox). */
+    sourceRepresentation?: string;
+    role?: string;
+    accessibleName?: string;
+    required?: boolean;
+    /** True when any ancestor is a structural branch. */
+    conditional?: boolean;
+    /** Every gate between the template root and this element, outermost first. */
+    conditionChain?: ConditionLink[];
+    repeated?: boolean;
+    repeatOver?: string;
+    repeatVar?: string;
+    repeatTrackBy?: string;
+    /**
+     * Handles the SOURCE offers for this element — audit material, never a locator to drive.
+     *
+     * `unique` computed within one template is a weaker claim than a live DOM's uniqueness: the
+     * shell and the route component both render into one page, so a token unique in its own file
+     * can still collide once composed. `uniqueScope` says which claim is being made.
+     */
+    selectorCandidates?: SelectorCandidate[];
 }
+/** One structural gate, as written in the template. */
+export interface ConditionLink {
+    /** `*ngIf`, `@if`, `@for`, `@switch`, `@defer`, ... */
+    directive: string;
+    /** The guiding expression. Free text with no grammar — treat it as data. */
+    expr: string;
+    /** Which branch of a multi-branch construct this element sits in (`if`, `else if`, `else`,
+     *  a `@switch` case label, `empty`, `placeholder`). */
+    branch?: string;
+    source?: SourcePointer;
+}
+export interface SelectorCandidate {
+    by: 'testid' | 'id' | 'name' | 'aria' | 'role' | 'placeholder' | 'text' | 'css';
+    value: string;
+    unique: boolean;
+    uniqueScope: 'template' | 'route';
+}
+/** What a person can DO with this element, independent of how it is spelled. */
+export type ControlType = 'textbox' | 'combobox' | 'listbox' | 'checkbox' | 'radio' | 'button' | 'link' | 'datepicker' | 'fileinput' | 'slider' | 'grid' | 'tab' | 'other';
 export interface TextNode extends BaseNode {
     type: 'text';
     value: string;
@@ -61,6 +127,7 @@ export interface TemplateNode<Child = DomNode> extends BaseNode {
     branches?: TemplateBranch<Child>[];
     /** The primary/consequent branch's children, kept so every DomNode has a `children` array. */
     children: Child[];
+    source?: SourcePointer;
 }
 export type DomNode = ElementNode | TextNode | InterpolationNode | TemplateNode;
 //# sourceMappingURL=dom.d.ts.map

package/dist/types/dom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/types/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,mHAAmH;AACnH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,QAAQ;IAC5D,IAAI,EAAE,SAAS,CAAC;IAChB,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,wEAAwE;IACxE,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,qDAAqD;IACrD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,KAAK,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,QAAS,SAAQ,QAAQ;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,IAAI,EAAE,eAAe,CAAC;IACtB,8FAA8F;IAC9F,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,QAAQ,GACR,KAAK,GACL,MAAM,GACN,SAAS,GACT,QAAQ,GACR,SAAS,GACT,IAAI,GACJ,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,OAAO;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,KAAK,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,QAAQ;IAC7D,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,cAAc,CAAC;IAC3B,iGAAiG;IACjG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;IACnC,8FAA8F;IAC9F,QAAQ,EAAE,KAAK,EAAE,CAAC;CACnB;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,iBAAiB,GAAG,YAAY,CAAC"}
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/types/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,mHAAmH;AACnH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,iBAAiB,CAAC;IACvD,+EAA+E;IAC/E,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,QAAQ;IAC5D,IAAI,EAAE,SAAS,CAAC;IAChB,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,wEAAwE;IACxE,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,qDAAqD;IACrD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,KAAK,EAAE,CAAC;IAElB,qCAAqC;IACrC,MAAM,CAAC,EAAE,aAAa,CAAC;IASvB;uEACmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;iCAC6B;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;mGAE+F;IAC/F,cAAc,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,yFAAyF;IACzF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAOnB,qDAAqD;IACrD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC1C;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,KAAK,CAAC;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC;CACnC;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAC7E,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAErE,MAAM,WAAW,QAAS,SAAQ,QAAQ;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,IAAI,EAAE,eAAe,CAAC;IACtB,8FAA8F;IAC9F,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,QAAQ,GACR,KAAK,GACL,MAAM,GACN,SAAS,GACT,QAAQ,GACR,SAAS,GACT,IAAI,GACJ,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,OAAO;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,KAAK,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,QAAQ;IAC7D,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,cAAc,CAAC;IAC3B,iGAAiG;IACjG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;IACnC,8FAA8F;IAC9F,QAAQ,EAAE,KAAK,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,iBAAiB,GAAG,YAAY,CAAC"}

package/dist/types/manifest.d.ts

@@ -1,16 +1,95 @@
 import type { ComponentNode } from './component.js';
 import type { RouteNode } from './route.js';
 import type { RouteDependencyTree } from './dependency-graph.js';
-export declare const SCHEMA_VERSION = "1.0";
+import type { AppIdentity, Coverage, CoverageScope, GeneratorProvenance, Provenance, RepoProvenance } from './provenance.js';
+import type { Uncapturable } from './uncapturable.js';
+import type { SourcePointer } from './source.js';
+/**
+ * Bumped to "2.0" for the `app` block, whose two fields are REQUIRED — see `AppIdentity`. A
+ * consumer needs exactly one field to test to know whether the routes it is about to read can be
+ * matched against real URLs at all, and that field is this one.
+ */
+export declare const SCHEMA_VERSION = "2.0";
 export type Framework = 'angular' | 'react';
 export interface UiManifest {
     schemaVersion: typeof SCHEMA_VERSION;
     framework: Framework;
+    /** Where the app is served from. Required: without it every route in this file is unmatchable
+     *  against a real URL, silently. See {@link AppIdentity}. */
+    app: AppIdentity;
+    /** Which commit, which extractor, which passes. Non-diffable — ignore it when diffing, the same
+     *  as `generatedAt`.
+     *
+     *  Kept alongside the top-level `repo`/`generator` below rather than replaced by them: a
+     *  consumer written against the first 2.0 release reads this block, and breaking it would make
+     *  a field addition into a coordinated release. The two are the same objects. */
+    provenance: Provenance;
+    /**
+     * The same `provenance.repo` / `provenance.generator`, lifted to the top level.
+     *
+     * Both spellings exist on purpose. Nesting keeps the non-diffable data in one block a
+     * `jq 'del(.provenance)'` can drop whole; lifting is what consumers that require these fields
+     * read. `repo.remoteUrl` and `repo.appRoot` are optional on the nested copy (they are absent
+     * outside a git tree, which is information) and REQUIRED here — outside a git tree this pair is
+     * simply not emitted, so "present but hollow" never occurs.
+     */
+    repo?: RepoProvenance & {
+        remoteUrl: string;
+        appRoot: string;
+    };
+    generator?: GeneratorProvenance & {
+        generatedAt: string;
+    };
+    /** Whether a missing route means "deleted" or "not looked at". See {@link Coverage}. */
+    coverage: Coverage;
+    coverageScope?: CoverageScope;
     /** ISO timestamp of generation. Not diff-relevant on its own — consumers diffing two
      *  manifests should ignore this field, since it changes on every run even with no UI change. */
     generatedAt: string;
+    /**
+     * Whether presentational nodes were dropped.
+     *
+     * `"semantic"` means the tree is NOT the DOM: a wrapper carrying nothing but a class, with no
+     * events, no props and no handle, is folded away and its static text folded into its parent.
+     * That is a large reduction with no loss to any join, precisely because `conditionChain` is
+     * denormalized onto each element — nothing downstream needs the ancestors that were dropped.
+     */
+    nodePolicy?: 'semantic' | 'verbatim';
+    /** How many nodes `nodePolicy` removed, so a consumer knows the tree is not the DOM. */
+    collapsedNodeCount?: number;
     routes: RouteNode[];
+    /**
+     * Wildcard routes.
+     *
+     * Kept out of `routes[]` because a `**` matches every URL and so identifies none: given a page
+     * key it would fold every unmatched screen onto one node, which is worse than a miss.
+     */
+    fallbacks?: {
+        pattern: string;
+        redirectTo?: string;
+        source?: SourcePointer;
+    }[];
     components: ComponentNode[];
+    /**
+     * Which components render under each route — the shell above the router outlet included.
+     *
+     * References, never DOM: the elements live in `components[]` and are resolved once. Without
+     * this a consumer keying elements by page attributes the shell's navigation to no page at
+     * all, and "where is the sign-out button on this screen" answers "this screen has none".
+     */
+    routeTrees?: {
+        routePath: string;
+        rootComponent: string;
+        nodes: {
+            component: string;
+            via?: SourcePointer;
+            conditional: boolean;
+            repeated: boolean;
+            children: unknown[];
+        }[];
+    }[];
+    /** What the extractor could not statically resolve. See {@link Uncapturable}. */
+    uncapturable?: Uncapturable[];
     /** Present only when the extractor was run with dependency-graph resolution enabled. */
     dependencyGraph?: RouteDependencyTree[];
     /** Soft-failure notices, e.g. "routing pattern unresolved for src/App.tsx". Never used in

package/dist/types/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/types/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB;oGACgG;IAChG,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,wFAAwF;IACxF,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC;mGAC+F;IAC/F,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/types/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EACV,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,mBAAmB,EAAE,UAAU,EAAE,cAAc,EACtF,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB;iEAC6D;IAC7D,GAAG,EAAE,WAAW,CAAC;IACjB;;;;;qFAKiF;IACjF,UAAU,EAAE,UAAU,CAAC;IACvB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,cAAc,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,SAAS,CAAC,EAAE,mBAAmB,GAAG;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,wFAAwF;IACxF,QAAQ,EAAE,QAAQ,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;oGACgG;IAChG,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACrC,wFAAwF;IACxF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,aAAa,CAAA;KAAE,EAAE,CAAC;IAC/E,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,aAAa,CAAC;YAAC,WAAW,EAAE,OAAO,CAAC;YAAC,QAAQ,EAAE,OAAO,CAAC;YAChF,QAAQ,EAAE,OAAO,EAAE,CAAA;SAAE,EAAE,CAAC;KAClC,EAAE,CAAC;IACJ,iFAAiF;IACjF,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,wFAAwF;IACxF,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC;mGAC+F;IAC/F,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB"}

package/dist/types/manifest.js

@@ -1 +1,6 @@
-export const SCHEMA_VERSION = '1.0';
+/**
+ * Bumped to "2.0" for the `app` block, whose two fields are REQUIRED — see `AppIdentity`. A
+ * consumer needs exactly one field to test to know whether the routes it is about to read can be
+ * matched against real URLs at all, and that field is this one.
+ */
+export const SCHEMA_VERSION = '2.0';

package/dist/types/provenance.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Where a manifest came from: which app, which commit, which extractor run.
+ *
+ * v1 could answer "what does this UI contain" but not "which build is this" — so two manifests
+ * could only ever be compared against each other, never against a deployed thing. Everything here
+ * exists to make a manifest self-locating.
+ *
+ * **This whole block is non-diffable**, in the same sense `generatedAt` already is: `commit` and
+ * `buildId` change on every run even when the UI does not. `jq 'del(.generatedAt, .provenance)'`
+ * restores a document whose every remaining field changes only when the UI's structure does. That
+ * is why it is a segregated top-level block rather than fields sprinkled through `routes` and
+ * `components`.
+ */
+/** How the app's router turns a route path into a URL. */
+export type RouterMode = 'path' | 'hash';
+/**
+ * Where the app is served from, which is what decides whether a route path matches a real URL.
+ *
+ * Both fields are REQUIRED, and that is deliberate. Omitting either does not produce an error in
+ * any consumer — it produces a silent, total miss. An app served under `/portal/` renders
+ * `/portal/dashboard`; a manifest that says `dashboard` matches nothing, on every route, and looks
+ * exactly like a manifest for an app that simply has little in it. `useHash: true` fails the same
+ * way. A field whose absence is indistinguishable from a wrong answer has to be required.
+ */
+export interface AppIdentity {
+    /**
+     * The app's base path, from Angular's `<base href>` / `APP_BASE_HREF`, or React Router's
+     * `basename`. `"/"` when the app is served from the root — which is the common case, and is a
+     * real answer rather than a default standing in for "unknown".
+     */
+    baseHref: string;
+    /** `"hash"` for `useHash: true` / `HashRouter`, which puts the entire route after a `#`. */
+    routerMode: RouterMode;
+    /** How `baseHref`/`routerMode` were established. `"detected"` means read out of the source;
+     *  `"configured"` means the caller supplied them; `"default"` means neither, and the values are
+     *  the conventional ones — which a consumer should treat as a weaker claim. */
+    confidence: 'detected' | 'configured' | 'default';
+}
+/** The commit the source was in when the manifest was generated. */
+export interface RepoProvenance {
+    /** `origin`'s URL, as git reports it. Absent outside a git working tree. */
+    remoteUrl?: string;
+    /** Full commit sha. Absent outside a git working tree, and deliberately NOT defaulted to a
+     *  branch name: a branch moves, so a manifest pinned to one is not pinned at all. Its absence
+     *  marks the output as unpinned, which is information a consumer can act on. */
+    commit?: string;
+    /** Committer timestamp, ISO 8601. From git, never from a clock: it is what orders two manifests
+     *  that arrive out of sequence, and a generation timestamp would order them by when they were
+     *  uploaded rather than by which describes newer code. */
+    commitTime?: string;
+    branch?: string;
+    /** True when the working tree had uncommitted changes — so `commit` describes *most* of what was
+     *  extracted, not all of it. Silently reporting a commit for a dirty tree is how a manifest comes
+     *  to describe code that was never committed anywhere. */
+    dirty?: boolean;
+    /** The scanned directory, relative to the repository root. Every `filePath` in the manifest is
+     *  relative to this, so a consumer can reconstruct a repo-relative path without guessing. */
+    appRoot?: string;
+}
+/** Which extractor produced this, and what it actually ran. */
+export interface GeneratorProvenance {
+    name: string;
+    version: string;
+    /** The CI run that produced it, when one did (`GITHUB_RUN_ID` and friends). */
+    buildId?: string;
+    /**
+     * Analysis passes that ran, e.g. `["routes", "components", "dom", "dependency-graph"]`.
+     *
+     * The point is negative information: a consumer must be able to tell "this component has no DOM
+     * tree" from "the DOM pass never ran". Without it, every optional field is ambiguous between
+     * "absent" and "not looked for", and a consumer either re-runs unnecessarily or trusts a gap.
+     */
+    passes: string[];
+}
+export interface Provenance {
+    repo: RepoProvenance;
+    generator: GeneratorProvenance;
+}
+/**
+ * Whether this manifest describes the whole app or a named part of it.
+ *
+ * Load-bearing for anything that merges manifests over time. Given only a manifest that lacks a
+ * route, a consumer cannot tell whether the route was DELETED or merely not covered by this run —
+ * and guessing "not covered" means a deleted route lives forever, while guessing "deleted" throws
+ * away a real one. `"full"` is a claim that absence means deletion; `"partial"` is a claim that it
+ * does not, and `coverageScope` says what was actually looked at.
+ */
+export type Coverage = 'full' | 'partial';
+export interface CoverageScope {
+    routes?: string[];
+    paths?: string[];
+}
+//# sourceMappingURL=provenance.d.ts.map

package/dist/types/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/types/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,UAAU,EAAE,UAAU,CAAC;IACvB;;mFAE+E;IAC/E,UAAU,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;CACnD;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;oFAEgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;8DAE0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;8DAE0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;iGAC6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/dist/types/provenance.js

@@ -0,0 +1,14 @@
+/**
+ * Where a manifest came from: which app, which commit, which extractor run.
+ *
+ * v1 could answer "what does this UI contain" but not "which build is this" — so two manifests
+ * could only ever be compared against each other, never against a deployed thing. Everything here
+ * exists to make a manifest self-locating.
+ *
+ * **This whole block is non-diffable**, in the same sense `generatedAt` already is: `commit` and
+ * `buildId` change on every run even when the UI does not. `jq 'del(.generatedAt, .provenance)'`
+ * restores a document whose every remaining field changes only when the UI's structure does. That
+ * is why it is a segregated top-level block rather than fields sprinkled through `routes` and
+ * `components`.
+ */
+export {};

package/dist/types/route.d.ts

@@ -1,18 +1,57 @@
+import type { SourcePointer } from './source.js';
+/**
+ * One guard on a route.
+ *
+ * v2 emitted a bare name. A name cannot be opened, so "what gates this route?" was answerable
+ * only as far as "something called authGuard" — and the follow-up, which is the one that matters
+ * when a test cannot reach a screen, needed a repository search to answer.
+ */
+export interface RouteGuard {
+    name: string;
+    kind: 'function' | 'class';
+    source?: SourcePointer;
+}
 export interface RouteGuards {
-    canActivate?: string[];
-    canDeactivate?: string[];
+    canActivate?: RouteGuard[];
+    canActivateChild?: RouteGuard[];
+    canDeactivate?: RouteGuard[];
+    canMatch?: RouteGuard[];
 }
 export type ReactRoutingPattern = 'jsx-routes' | 'router-config' | 'file-based';
 export interface RouteNode {
+    /** This route's own segment, exactly as written in the source. */
     path: string;
+    /**
+     * The full path a URL must have to reach this route: every ancestor's `path` joined with this
+     * one, `baseHref` applied, and leading/trailing slashes normalised.
+     *
+     * Derivable by a consumer from the tree — but doing it here means one implementation instead of
+     * one per consumer, and it removes a specific way to get it wrong: two `''` children under
+     * different parents are the same `path` and different `fullPath`s, so a consumer keying on
+     * `path` silently collides them.
+     *
+     * Absent for a route that cannot BE a URL — a bare `**` wildcard matches every path and so
+     * identifies none, and giving it a `fullPath` would invite a consumer to treat it as a screen.
+     */
+    fullPath?: string;
     /** The resolved lazy-loaded target, e.g. Angular's loadComponent or a React <Route element>. */
     component?: {
         module: string;
         export: string;
+        source?: SourcePointer;
+    };
+    loadComponent?: {
+        module: string;
+        export: string;
+        source?: SourcePointer;
     };
     redirectTo?: string;
     pathMatch?: string;
     guards?: RouteGuards;
+    /** Query parameters this route reads. */
+    queryParamKeys?: string[];
+    /** Where the route object literal is written. */
+    source?: SourcePointer;
     children?: RouteNode[];
     /** React only, set at the tree root: which detection strategy produced this tree. */
     routingPattern?: ReactRoutingPattern;

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,SAAS,CAAC,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,qFAAqF;IACrF,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAC3B,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,UAAU,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,UAAU,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,SAAS,CAAC,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,aAAa,CAAC;KACxB,CAAC;IACF,aAAa,CAAC,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,aAAa,CAAC;KACxB,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iDAAiD;IACjD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,qFAAqF;IACrF,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC"}

package/dist/types/source.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where in the repository a thing is declared.
+ *
+ * v2 emitted routes, components and elements but never said *where they came from*, so every
+ * "where is this declared?" answer a consumer could give was "somewhere in this file" — and for a
+ * 400-line template that is not an answer, it is a re-read. Line numbers are the single biggest
+ * thing this block adds, and they cost nothing to produce: Angular's `parseTemplate()` and the
+ * TypeScript AST both carry positions on every node already.
+ *
+ * `blobOid` is the quietly valuable field. A git blob sha survives a rename, so a pointer stays
+ * resolvable after a refactor that a path alone would strand. Absent until the extractor is asked
+ * to shell out to git per file, which it is not today.
+ */
+export interface SourcePointer {
+    /** Repo-relative, forward slashes, no `..` segment. Relative to the repository root — NOT to
+     *  `repo.appRoot` — so a consumer can hand it to a repository API without re-joining anything. */
+    path: string;
+    /** A class, method or guard name. An identifier, never free text. */
+    symbol?: string;
+    /** 1-based, like an editor shows and unlike every parser that produces it. */
+    startLine?: number;
+    endLine?: number;
+    blobOid?: string;
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/types/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/types/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;sGACkG;IAClG,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types/source.js

@@ -0,0 +1 @@
+export {};

package/dist/types/uncapturable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What the extractor could NOT statically resolve.
+ *
+ * This is not optional bookkeeping. When a consumer sees an element at runtime that no manifest
+ * declares, there are two causes — the manifest is stale, or the app injects that DOM — and they
+ * need opposite actions. This list is the only thing that tells them apart. Without it, every such
+ * finding is undiagnosable and a manifest covering 70% of an app looks complete.
+ *
+ * `diagnostics[]` is still emitted alongside and still carries the same notices as free text; this
+ * is the same information given a shape a consumer can branch on.
+ */
+export type UncapturableKind = 'dynamicComponentOutlet' | 'innerHTML' | 'runtimeRoute' | 'unresolvedLazyChunk' | 'thirdPartyWebComponent' | 'iframe' | 'dynamicSelector' | 'unresolvedApiUrl' | 'templateParseError' | 'unsupportedTemplateNode';
+export interface Uncapturable {
+    kind: UncapturableKind;
+    /** The component (or route) whose extraction is incomplete because of this. */
+    affects?: string;
+    /** Free text, for a person. */
+    detail?: string;
+    source?: import('./source.js').SourcePointer;
+}
+//# sourceMappingURL=uncapturable.d.ts.map

package/dist/types/uncapturable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uncapturable.d.ts","sourceRoot":"","sources":["../../src/types/uncapturable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,WAAW,GACX,cAAc,GACd,qBAAqB,GACrB,wBAAwB,GACxB,QAAQ,GACR,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GACpB,yBAAyB,CAAC;AAE9B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,aAAa,CAAC;CAC9C"}

package/dist/types/uncapturable.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,9 +1,25 @@
 {
   "name": "@ui-manifest-json/core",
-  "version": "0.1.0",
-  "description": "Shared JSON schema types and dependency-tree resolver for ui-manifest extractors.",
+  "version": "0.3.0",
+  "description": "Shared JSON schema types and framework-agnostic helpers for ui-manifest extractors.",
+  "keywords": [
+    "ui-manifest",
+    "schema",
+    "types",
+    "ast",
+    "static-analysis"
+  ],
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrainRidge/ui-manifest.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/BrainRidge/ui-manifest/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/BrainRidge/ui-manifest/issues"
+  },
   "engines": {
     "node": ">=20.6.0"
   },