nudge-ui 0.2.0

package/dist/inspector/prompt/generatePrompt.js

@@ -0,0 +1,391 @@
+import { isComponentChange, isElementChange, isTextContentChange, isTokenChange } from "../changes/changesLog.js";
+import { canonicalizeChanges, changeKey, tokenReference } from "../changes/model.js";
+import { getAnyPreviewDiagnostic } from "../changes/previewDiagnostics.js";
+import { formatComponentPropBaseline, formatComponentPropValue, } from "../componentSemantics/changeModel.js";
+import { boundRuntimeEvidence, isRuntimeGeneratedSource, normalizeRuntimeTag, normalizeRuntimeText, } from "../runtime/staticHtmlRuntimeIdentity.js";
+import { getSourceCoordinatePolicy } from "../runtime/runtimeConfig.js";
+import { DEFAULT_CUSTOM_INSTRUCTIONS } from "./promptSettings.js";
+const EMPTY_SENTINEL = "<!-- No changes to export -->\n\nThe changes log is empty. Make a change in the Nudge UI inspector first.";
+function renderPrompt(sections, customInstructions) {
+    const lines = [
+        "# Requested design changes",
+    ];
+    for (const section of sections) {
+        const content = [...section.lines];
+        while (content.at(-1) === "")
+            content.pop();
+        lines.push("", `## ${section.heading}`, "", ...content);
+    }
+    const instructions = customInstructions.trim();
+    if (instructions) {
+        lines.push("", "## Custom instructions", "", instructions);
+    }
+    return lines.join("\n");
+}
+function groupElementChanges(changes) {
+    const map = new Map();
+    for (const change of changes) {
+        const instanceOverride = change.scope === "rendered-instance" ? change.instanceOverride : undefined;
+        const key = [
+            change.cid,
+            change.file,
+            change.line,
+            change.selector,
+            change.scope ?? "source-site",
+            instanceOverride?.id ?? "",
+            instanceOverride ? JSON.stringify(instanceOverride.target) : "",
+            change.state ?? "base",
+        ].join("\u0000");
+        let group = map.get(key);
+        if (!group) {
+            group = {
+                key,
+                cid: change.cid,
+                file: change.file,
+                line: change.source.line || change.line,
+                column: change.column ?? 0,
+                runtimeEvidence: change.runtimeEvidence,
+                instanceOverride,
+                changes: [],
+            };
+            map.set(key, group);
+        }
+        group.changes.push(change);
+    }
+    return [...map.values()];
+}
+function conflictSuffix(rec) {
+    const result = getAnyPreviewDiagnostic(changeKey(rec))?.result;
+    if (!result || result.status === "applied")
+        return "";
+    return ` — preview conflict: browser computed \`${result.computedValue || "(no value)"}\` (${result.reason ?? "cascade conflict"}); implement the requested value without assuming \`!important\``;
+}
+function elementChangeLine(rec) {
+    if (rec.newToken && rec.oldToken) {
+        return `- \`${rec.property}\`: \`${rec.oldToken.name}\` → \`${rec.newToken.name}\`${conflictSuffix(rec)}`;
+    }
+    if (rec.newToken) {
+        const before = rec.oldRawValue !== undefined ? `\`${rec.oldRawValue}\` → ` : "";
+        // Describe exactly the value the managed stylesheet wrote for this swap
+        // (adapter literal or var(cssName)); a bare var(name) would be invalid
+        // CSS for adapter tokens whose names are not custom-property names.
+        return `- \`${rec.property}\`: ${before}\`${tokenReference(rec.newToken)}\`${conflictSuffix(rec)}`;
+    }
+    if (rec.rawValue !== undefined) {
+        const before = rec.oldRawValue !== undefined ? `\`${rec.oldRawValue}\` → ` : "";
+        return `- \`${rec.property}\`: ${before}\`${rec.rawValue}\`${conflictSuffix(rec)}`;
+    }
+    return `- \`${rec.property}\`: (no value)`;
+}
+function sourceIntentLine(rec) {
+    if (!rec.sourceProperty || rec.sourceProperty === rec.property)
+        return null;
+    const authored = rec.sourceAuthoredValue ? `: ${rec.sourceAuthoredValue}` : "";
+    return `  - Source declaration (CSSOM): \`${rec.sourceProperty}${authored}\`; preview edit uses physical \`${rec.property}\``;
+}
+function tokenChangeLine(rec) {
+    return `- \`${rec.tokenName}\` (${rec.contextLabel}, ${rec.file}:${rec.line}): \`${rec.oldRawValue}\` → \`${rec.rawValue}\`${conflictSuffix(rec)}`;
+}
+function componentChangeLine(rec) {
+    const sourceGuidance = rec.authoredAs === "literal"
+        ? rec.property === "children"
+            ? "replace the literal child text"
+            : "replace the invocation prop literal"
+        : rec.authoredAs === "default"
+            ? "add the prop at this invocation"
+            : `preserve the authored ${rec.authoredAs} and update its source logic`;
+    const scope = rec.scope === "rendered-instance"
+        ? "this rendered item only"
+        : "all outputs at this source site";
+    return `- \`${rec.property}\`: \`${formatComponentPropBaseline(rec.before)}\` → \`${formatComponentPropValue(rec.after)}\` — ${sourceGuidance}; scope: ${scope}`;
+}
+function textAuthorshipGuidance(authoredAs) {
+    if (authoredAs === "literal")
+        return "replace the authored literal text";
+    if (authoredAs === "expression")
+        return "preserve the expression and update its source logic";
+    return "update the source that produces this rendered copy";
+}
+/** Keep arbitrary rendered copy valid inside the Markdown prompt. */
+function promptText(value) {
+    if (!/[`~\r\n]/.test(value))
+        return `\`${value}\``;
+    const longestTildeRun = Math.max(...(value.match(/~+/g) ?? [""]).map((run) => run.length));
+    const fence = "~".repeat(Math.max(3, longestTildeRun + 1));
+    return `${fence}text\n${value}\n${fence}`;
+}
+function textEvidenceLines(target) {
+    const sourceLabel = isRuntimeGeneratedSource(target.sourceSite.src)
+        ? `${target.sourceSite.cid} (source unknown; runtime-created DOM)`
+        : `${target.sourceSite.cid} (\`${target.sourceSite.src}\`)`;
+    const lines = [
+        `  - Source site: ${sourceLabel}`,
+    ];
+    const props = boundRuntimeEvidence(target.props);
+    const ariaLabel = boundRuntimeEvidence(target.ariaLabel);
+    if (props)
+        lines.push(`  - Props evidence: ${promptText(props)}`);
+    if (ariaLabel)
+        lines.push(`  - Accessible name evidence: ${promptText(ariaLabel)}`);
+    return lines;
+}
+function textScopeLines(change) {
+    const scope = change.scope === "source-site" ? "source site / all outputs" : "this rendered item only";
+    const lines = [`  - Scope: ${scope}`];
+    if (change.evidence) {
+        lines.push(`  - Semantic evidence: \`${change.evidence.componentName}.${change.evidence.property}\` at callsite \`${change.evidence.callsiteId}\` (${change.evidence.mountedCount} mounted outputs)`);
+    }
+    return lines;
+}
+function boundedEvidence(value) {
+    return boundRuntimeEvidence(value);
+}
+function sourceSiteLabel(ref) {
+    if (isRuntimeGeneratedSource(ref.sourceSite.src)) {
+        return `${ref.sourceSite.cid} (source unknown; runtime-created DOM)`;
+    }
+    return `${ref.sourceSite.cid} (${ref.sourceSite.src})`;
+}
+/** Compare durable rendered-instance identity without child-text evidence. */
+function structuralParentIdentityKey(ref) {
+    const { sourceSite, locator } = ref;
+    return JSON.stringify([
+        sourceSite.cid,
+        sourceSite.src,
+        locator.occurrence,
+        locator.props,
+        locator.ariaLabel ?? null,
+    ]);
+}
+function runtimeEvidenceLines(group) {
+    const evidence = group.runtimeEvidence;
+    if (!evidence)
+        return [];
+    const tagName = normalizeRuntimeTag(evidence.tagName) || "unknown";
+    const text = normalizeRuntimeText(evidence.text);
+    const ariaLabel = boundRuntimeEvidence(evidence.ariaLabel);
+    const props = boundRuntimeEvidence(evidence.props);
+    const lines = [
+        "  - Source: unknown; locate the JavaScript or template that creates this runtime DOM.",
+        `  - Rendered element: \`<${tagName}>\``,
+    ];
+    if (text)
+        lines.push(`  - Text evidence: ${promptText(text)}`);
+    if (ariaLabel)
+        lines.push(`  - Accessible name evidence: ${promptText(ariaLabel)}`);
+    if (props)
+        lines.push(`  - Props evidence: ${promptText(props)}`);
+    return lines;
+}
+/**
+ * Coordinate precision follows each element's identity origin, not the
+ * document's framework hint (ADR-0011 Stage 5). The active host Adapter
+ * declares which origins carry exact authored coordinates through the
+ * runtime configuration; hosts that declare nothing are exact everywhere.
+ */
+function hasExactAuthoredCoordinates(policy, cid, file) {
+    if (policy === null)
+        return true;
+    if (cid !== undefined && policy.exactCidPrefixes.some((prefix) => cid.startsWith(prefix))) {
+        return true;
+    }
+    return policy.exactFileExtensions.some((extension) => file.endsWith(extension));
+}
+/**
+ * Formats one source location for a prompt heading. Exact origins keep the
+ * authored column; line-only origins — and sites whose column is unknown —
+ * degrade to `file:line` rather than fabricating precision.
+ */
+function formatSourceLocation(policy, source) {
+    if (hasExactAuthoredCoordinates(policy, source.cid, source.file) && source.column > 0) {
+        return `${source.file}:${source.line}:${source.column}`;
+    }
+    return `${source.file}:${source.line}`;
+}
+function elementGroupSource(group, policy) {
+    if (group.runtimeEvidence) {
+        return group.runtimeEvidence.reason === "unannotated"
+            ? "source unknown; no authored location available"
+            : "source unknown; runtime-created DOM";
+    }
+    return formatSourceLocation(policy, group);
+}
+function renderedInstanceDescription(ref) {
+    const text = boundedEvidence(ref.locator.text);
+    const ariaLabel = boundedEvidence(ref.locator.ariaLabel ?? null);
+    const props = boundedEvidence(ref.locator.props);
+    const source = isRuntimeGeneratedSource(ref.sourceSite.src)
+        ? sourceSiteLabel(ref)
+        : ref.sourceSite.src;
+    if (text)
+        return `text ${promptText(text)} (${source})`;
+    if (ariaLabel)
+        return `the element named ${promptText(ariaLabel)} (${source})`;
+    if (props)
+        return `the element with props ${promptText(props)} (${source})`;
+    // With no semantic evidence, the ordinal is the only way to distinguish
+    // repeated outputs from the same source site.
+    return `rendered instance ${ref.locator.occurrence + 1} of ${sourceSiteLabel(ref)}`;
+}
+function structuralChangeLine(change) {
+    const target = renderedInstanceDescription(change.target);
+    if (change.kind === "delete") {
+        return `- Remove ${target} from the source.`;
+    }
+    const before = change.destination.before;
+    const sourceParent = sourceSiteLabel(change.source.parent);
+    const destinationParent = sourceSiteLabel(change.destination.parent);
+    if (structuralParentIdentityKey(change.source.parent) !== structuralParentIdentityKey(change.destination.parent)) {
+        return before
+            ? `- Move ${target} from ${sourceParent} into ${destinationParent}, before ${renderedInstanceDescription(before)}.`
+            : `- Move ${target} from ${sourceParent} into ${destinationParent}, at the end.`;
+    }
+    return before
+        ? `- Move ${target} before ${renderedInstanceDescription(before)} in ${destinationParent}.`
+        : `- Move ${target} to the end of ${destinationParent}.`;
+}
+function renderedInstanceKey(ref) {
+    const { sourceSite, locator } = ref;
+    return JSON.stringify([
+        sourceSite.cid,
+        sourceSite.src,
+        locator.props,
+        locator.text,
+        locator.ariaLabel ?? null,
+    ]);
+}
+/** Export final intent, not the gesture history required to replay the preview. */
+function canonicalizeStructuralChanges(changes) {
+    const historyByTarget = new Map();
+    changes.forEach((change, index) => {
+        const targetKey = renderedInstanceKey(change.target);
+        const history = historyByTarget.get(targetKey) ?? { changes: [], lastIndex: index };
+        history.changes.push(change);
+        history.lastIndex = index;
+        historyByTarget.set(targetKey, history);
+    });
+    const canonical = [];
+    const histories = [...historyByTarget.entries()]
+        .sort(([, a], [, b]) => a.lastIndex - b.lastIndex);
+    for (const [targetKey, history] of histories) {
+        const latest = history.changes.at(-1);
+        if (latest.kind === "delete") {
+            canonical.push(latest);
+            continue;
+        }
+        const moves = history.changes.filter((change) => change.kind === "move");
+        const first = moves[0];
+        const onlyTargetMoves = changes.every((candidate) => candidate.kind === "move"
+            && renderedInstanceKey(candidate.target) === targetKey);
+        const returnedToStart = moves.length > 1
+            && onlyTargetMoves
+            && first
+            && structuralParentIdentityKey(first.source.parent) === structuralParentIdentityKey(latest.destination.parent)
+            && first.presentation.fromIndex === latest.presentation.toIndex;
+        if (returnedToStart)
+            continue;
+        // The final destination is the useful handoff. Keep the first source
+        // context when the gesture crossed intermediate containers so the prompt
+        // describes the authored move rather than the drag history.
+        if (first && first !== latest && latest.kind === "move") {
+            canonical.push({
+                ...latest,
+                source: first.source,
+                presentation: {
+                    ...latest.presentation,
+                    sourceParentTag: first.presentation.sourceParentTag,
+                    fromIndex: first.presentation.fromIndex,
+                },
+            });
+        }
+        else {
+            canonical.push(latest);
+        }
+    }
+    return canonical;
+}
+export function generatePrompt(changes, frameworkHints, structuralChanges = [], customInstructions = DEFAULT_CUSTOM_INSTRUCTIONS) {
+    const deduplicated = canonicalizeChanges(changes);
+    const structuralIntent = canonicalizeStructuralChanges(structuralChanges);
+    if (deduplicated.length === 0 && structuralIntent.length === 0)
+        return EMPTY_SENTINEL;
+    const tokenChanges = deduplicated.filter(isTokenChange);
+    const componentChanges = deduplicated.filter(isComponentChange);
+    const textChanges = deduplicated.filter(isTextContentChange);
+    const elementChanges = deduplicated.filter(isElementChange);
+    const elementGroups = groupElementChanges(elementChanges);
+    const coordinatePolicy = getSourceCoordinatePolicy();
+    const sections = [];
+    if (tokenChanges.length > 0) {
+        sections.push({
+            heading: "Global token changes",
+            lines: tokenChanges.map(tokenChangeLine),
+        });
+    }
+    if (componentChanges.length > 0) {
+        const lines = [];
+        for (const change of componentChanges) {
+            const target = change.target;
+            const source = formatSourceLocation(coordinatePolicy, target);
+            lines.push(`### ${target.componentName} invocation (${source})`);
+            lines.push(componentChangeLine(change));
+            lines.push(`  - Component contract: \`${target.componentId}\``);
+            if (change.evidence) {
+                lines.push(`  - Rendered evidence: ${change.evidence.mountedCount} mounted outputs`);
+                if (change.evidence.props)
+                    lines.push(`    - Props evidence: ${promptText(boundedEvidence(change.evidence.props) ?? "")}`);
+                if (change.evidence.ariaLabel)
+                    lines.push(`    - Accessible name evidence: ${promptText(boundedEvidence(change.evidence.ariaLabel) ?? "")}`);
+                lines.push(`    - Before text: ${promptText(change.evidence.beforeText)}`);
+            }
+            lines.push("");
+        }
+        sections.push({ heading: "Component prop changes", lines });
+    }
+    if (elementGroups.length > 0) {
+        const lines = [];
+        for (const group of elementGroups) {
+            const state = group.changes[0]?.state ?? "base";
+            lines.push(`### ${group.cid} (${elementGroupSource(group, coordinatePolicy)}) · ${state}`);
+            if (group.instanceOverride) {
+                lines.push(`- Applies only to ${renderedInstanceDescription(group.instanceOverride.target)}.`);
+            }
+            lines.push(...runtimeEvidenceLines(group));
+            for (const change of group.changes) {
+                lines.push(elementChangeLine(change));
+                const intent = sourceIntentLine(change);
+                if (intent)
+                    lines.push(intent);
+            }
+            lines.push("");
+        }
+        sections.push({ heading: "Changes", lines });
+    }
+    if (textChanges.length > 0) {
+        const lines = [];
+        for (const change of textChanges) {
+            const runtimeCreated = isRuntimeGeneratedSource(change.target.sourceSite.src);
+            const textSource = runtimeCreated
+                ? "source unknown; runtime-created DOM"
+                : formatSourceLocation(coordinatePolicy, {
+                    cid: change.target.sourceSite.cid,
+                    file: change.source.file,
+                    line: change.source.line,
+                    column: change.source.column,
+                });
+            lines.push(`### ${change.source.component || change.target.sourceSite.cid} (${textSource})`);
+            lines.push(`- Rendered text: ${promptText(change.before)} → ${promptText(change.after)} — ${textAuthorshipGuidance(change.authoredAs)}`);
+            lines.push(...textScopeLines(change));
+            lines.push(...textEvidenceLines(change.target));
+            lines.push("");
+        }
+        sections.push({ heading: "Rendered text changes", lines });
+    }
+    if (structuralIntent.length > 0) {
+        sections.push({
+            heading: "Structural changes",
+            lines: structuralIntent.map(structuralChangeLine),
+        });
+    }
+    return renderPrompt(sections, customInstructions);
+}

package/dist/inspector/prompt/promptSettings.d.ts

@@ -0,0 +1,8 @@
+/** The default guidance included in every generated prompt. */
+export declare const DEFAULT_CUSTOM_INSTRUCTIONS = "Preserve existing tokens, logical properties, and CSS intent while applying these rendered changes.";
+declare function storageKey(projectId: string): string;
+/** Reads the project-scoped custom prompt instructions from browser storage. */
+export declare function loadCustomInstructions(projectId: string): string;
+/** Persists custom prompt instructions without making storage availability a prerequisite for editing. */
+export declare function saveCustomInstructions(projectId: string, instructions: string): void;
+export { storageKey as promptSettingsStorageKey };

package/dist/inspector/prompt/promptSettings.js

@@ -0,0 +1,28 @@
+/** The default guidance included in every generated prompt. */
+export const DEFAULT_CUSTOM_INSTRUCTIONS = "Preserve existing tokens, logical properties, and CSS intent while applying these rendered changes.";
+function storageKey(projectId) {
+    return `nudge-ui:${projectId}:prompt-settings`;
+}
+/** Reads the project-scoped custom prompt instructions from browser storage. */
+export function loadCustomInstructions(projectId) {
+    if (typeof localStorage === "undefined")
+        return DEFAULT_CUSTOM_INSTRUCTIONS;
+    try {
+        return localStorage.getItem(storageKey(projectId)) ?? DEFAULT_CUSTOM_INSTRUCTIONS;
+    }
+    catch {
+        return DEFAULT_CUSTOM_INSTRUCTIONS;
+    }
+}
+/** Persists custom prompt instructions without making storage availability a prerequisite for editing. */
+export function saveCustomInstructions(projectId, instructions) {
+    if (typeof localStorage === "undefined")
+        return;
+    try {
+        localStorage.setItem(storageKey(projectId), instructions);
+    }
+    catch {
+        // Storage can be disabled or full; the in-memory UI state still applies.
+    }
+}
+export { storageKey as promptSettingsStorageKey };

package/dist/inspector/runtime/devFlag.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Decides the shared dev gate from one bundler observation and one host
+ * observation. Pure so every precedence rule is unit-testable without a
+ * particular bundler present.
+ *
+ * Precedence: an explicit host flag wins (a compiler without a define must
+ * still be authoritative); otherwise the bundler define decides; with neither,
+ * development is assumed absent — the gate fails closed rather than guessing.
+ */
+export declare function resolveNudgeUiDev(bundlerDefinedDev: boolean | undefined, hostFlag: boolean | undefined): boolean;
+/**
+ * Records whether the host Adapter is running a development server (ADR-0002).
+ *
+ * Vite and the standalone esbuild pipeline statically replace
+ * `import.meta.env.DEV`, so their bundles need no runtime flag. Hosts whose
+ * compiler cannot supply that define — Next.js/SWC has no equivalent of Vite's
+ * `define` for `import.meta.env` — must call this before bootstrapping the
+ * inspector. Passing `undefined` clears the override and restores the static
+ * define as the sole authority.
+ *
+ * The flag is process-global state by design: every inspector Module shares
+ * one dev gate, and a host configures it once per document, not per Module.
+ */
+export declare function setNudgeUiHostDevFlag(value: boolean | undefined): void;
+/**
+ * Dev-phase gate shared by every inspector Module (ADR-0002).
+ */
+export declare function isNudgeUiDev(): boolean;

package/dist/inspector/runtime/devFlag.js

@@ -0,0 +1,50 @@
+/**
+ * Decides the shared dev gate from one bundler observation and one host
+ * observation. Pure so every precedence rule is unit-testable without a
+ * particular bundler present.
+ *
+ * Precedence: an explicit host flag wins (a compiler without a define must
+ * still be authoritative); otherwise the bundler define decides; with neither,
+ * development is assumed absent — the gate fails closed rather than guessing.
+ */
+export function resolveNudgeUiDev(bundlerDefinedDev, hostFlag) {
+    if (hostFlag !== undefined)
+        return hostFlag;
+    if (bundlerDefinedDev !== undefined)
+        return bundlerDefinedDev;
+    return false;
+}
+let hostDevFlag;
+/**
+ * Records whether the host Adapter is running a development server (ADR-0002).
+ *
+ * Vite and the standalone esbuild pipeline statically replace
+ * `import.meta.env.DEV`, so their bundles need no runtime flag. Hosts whose
+ * compiler cannot supply that define — Next.js/SWC has no equivalent of Vite's
+ * `define` for `import.meta.env` — must call this before bootstrapping the
+ * inspector. Passing `undefined` clears the override and restores the static
+ * define as the sole authority.
+ *
+ * The flag is process-global state by design: every inspector Module shares
+ * one dev gate, and a host configures it once per document, not per Module.
+ */
+export function setNudgeUiHostDevFlag(value) {
+    hostDevFlag = value;
+}
+/**
+ * Dev-phase gate shared by every inspector Module (ADR-0002).
+ */
+export function isNudgeUiDev() {
+    try {
+        // Under Vite (and the standalone esbuild build) this member expression is
+        // statically replaced, so the read cannot throw there. In a bundle whose
+        // compiler defines nothing — Next.js/SWC — `import.meta.env` is undefined
+        // and the bare property read throws a TypeError. A build-mode name (such
+        // as the landing demo's `nudge-demo`) must never widen this gate; the
+        // demo runtime opens it for its own document instead (ADR-0014).
+        return resolveNudgeUiDev(import.meta.env.DEV === true, hostDevFlag);
+    }
+    catch {
+        return resolveNudgeUiDev(undefined, hostDevFlag);
+    }
+}

package/dist/inspector/runtime/documentStylesheetOrder.d.ts

@@ -0,0 +1,19 @@
+import type { TokenCatalogDiagnostic, TokenDefinition } from "../../css/model/index.js";
+import type { NudgeUiRuntimeConfig } from "./runtimeConfig.js";
+/** Evidence collected from the browser's current stylesheet order. */
+export interface DocumentStylesheetOrderEvidence {
+    readonly projectPaths: readonly string[];
+    /** False when a sheet is cross-origin, inline, unloaded, or duplicated. */
+    readonly complete: boolean;
+}
+/** Reads same-origin stylesheet order without making directory order authoritative. */
+export declare function collectDocumentStylesheetOrder(document: Document): DocumentStylesheetOrderEvidence;
+/** Token catalog plus diagnostics produced by document-order reconciliation. */
+export interface DocumentTokenCatalogReconciliation {
+    readonly catalog: readonly TokenDefinition[];
+    readonly diagnostics: readonly TokenCatalogDiagnostic[];
+}
+/** Reorders duplicate declarations only when browser order evidence is complete. */
+export declare function reconcileDocumentTokenCatalog(catalog: readonly TokenDefinition[], evidence: DocumentStylesheetOrderEvidence): DocumentTokenCatalogReconciliation;
+/** Applies browser stylesheet evidence to a host runtime before bootstrap. */
+export declare function reconcileRuntimeWithDocumentStylesheets(runtime: NudgeUiRuntimeConfig, document: Document): NudgeUiRuntimeConfig;

package/dist/inspector/runtime/documentStylesheetOrder.js

@@ -0,0 +1,89 @@
+/** Reads same-origin stylesheet order without making directory order authoritative. */
+export function collectDocumentStylesheetOrder(document) {
+    const projectPaths = [];
+    let complete = true;
+    for (let index = 0; index < document.styleSheets.length; index += 1) {
+        // SAFETY: CSSStyleSheetList.item() returns a CSSStyleSheet or null.
+        const sheet = document.styleSheets.item(index);
+        if (!sheet)
+            continue;
+        try {
+            void sheet.cssRules;
+        }
+        catch {
+            complete = false;
+            continue;
+        }
+        const projectPath = stylesheetProjectPath(sheet.href, document);
+        if (!projectPath || projectPaths.includes(projectPath)) {
+            complete = false;
+            continue;
+        }
+        projectPaths.push(projectPath);
+    }
+    return { projectPaths, complete };
+}
+/** Reorders duplicate declarations only when browser order evidence is complete. */
+export function reconcileDocumentTokenCatalog(catalog, evidence) {
+    const ranks = new Map(evidence.projectPaths.map((path, index) => [path, index]));
+    const stride = Math.max(1, ...catalog.map((definition) => definition.declarations.length)) + 1;
+    const diagnostics = [];
+    const resolved = catalog.map((definition) => {
+        if (definition.declarations.length < 2)
+            return definition;
+        const declarations = definition.declarations.map((declaration, index) => {
+            const path = sourcePath(declaration);
+            return { declaration, index, path, rank: ranks.get(path) };
+        });
+        if (!evidence.complete || declarations.some((entry) => entry.rank === undefined)) {
+            diagnostics.push({
+                code: "token-order-unresolved",
+                message: `Kept ${definition.declarations.length} declarations of "${declarationName(definition)}" in discovery order because browser stylesheet order evidence was incomplete.`,
+                module: declarations.find((entry) => entry.rank === undefined)?.path || "document-css",
+            });
+            return definition;
+        }
+        // The incomplete-rank branch returned above, so these fallbacks are unreachable.
+        declarations.sort((left, right) => (left.rank ?? 0) - (right.rank ?? 0) || left.index - right.index);
+        return {
+            ...definition,
+            declarations: declarations.map(({ declaration, rank }, index) => ({
+                ...declaration,
+                order: (rank ?? 0) * stride + index,
+            })),
+        };
+    });
+    const changed = resolved.some((definition, index) => definition !== catalog[index]);
+    return { catalog: changed ? resolved : catalog, diagnostics };
+}
+/** Applies browser stylesheet evidence to a host runtime before bootstrap. */
+export function reconcileRuntimeWithDocumentStylesheets(runtime, document) {
+    const { catalog: tokenCatalog, diagnostics } = reconcileDocumentTokenCatalog(runtime.tokenCatalog, collectDocumentStylesheetOrder(document));
+    const tokenDiagnostics = diagnostics.length === 0
+        ? runtime.tokenDiagnostics
+        : [...runtime.tokenDiagnostics, ...diagnostics];
+    return tokenCatalog === runtime.tokenCatalog && tokenDiagnostics === runtime.tokenDiagnostics
+        ? runtime
+        : { ...runtime, tokenCatalog, tokenDiagnostics };
+}
+function sourcePath(declaration) {
+    const match = declaration.source.match(/^(.*):\d+$/);
+    return match?.[1] ?? "";
+}
+function declarationName(definition) {
+    return definition.cssName || definition.name;
+}
+function stylesheetProjectPath(href, document) {
+    if (!href)
+        return null;
+    try {
+        const url = new URL(href, document.baseURI);
+        const origin = document.defaultView?.location.origin;
+        if (origin && url.origin !== origin)
+            return null;
+        return decodeURIComponent(url.pathname).replace(/^\/+/, "");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/inspector/runtime/domRealm.d.ts

@@ -0,0 +1,4 @@
+/** DOM operations for elements that may belong to a same-origin Canvas frame. */
+export declare function getElementWindow(element: Element): Window;
+export declare function getElementComputedStyle(element: Element): CSSStyleDeclaration;
+export declare function isShadowRootInDocument(root: Node, doc: Document): root is ShadowRoot;

package/dist/inspector/runtime/domRealm.js

@@ -0,0 +1,11 @@
+/** DOM operations for elements that may belong to a same-origin Canvas frame. */
+export function getElementWindow(element) {
+    return element.ownerDocument.defaultView ?? window;
+}
+export function getElementComputedStyle(element) {
+    return getElementWindow(element).getComputedStyle(element);
+}
+export function isShadowRootInDocument(root, doc) {
+    const ShadowRootConstructor = doc.defaultView?.ShadowRoot;
+    return ShadowRootConstructor !== undefined && root instanceof ShadowRootConstructor;
+}