nudge-ui 0.2.4 → 0.2.6

package/dist/inspector/pageInspector.js

@@ -0,0 +1,335 @@
+/** Loads the inspector into a page without a host Adapter; everything a host normally supplies is derived from the live document. */
+import { bootstrapNudgeUi, configureNudgeUiRuntime, getNudgeUiRuntimeConfig, isCanvasRenderer, readNudgeUiEditorTarget, setInspectorOpen, unmountInspector, } from "./index.js";
+import { CANVAS_RENDERER_ATTR } from "./canvas/roleDetection.js";
+import { releaseLease } from "./canvas/workspaceLease.js";
+import { enablePageSurface } from "./canvas/pageSurface.js";
+import { setNudgeUiHostDevFlag } from "./runtime/devFlag.js";
+import { configureInspectorStorage } from "./runtime/inspectorStorage.js";
+import { configureSketchStorage } from "./sketch/persistence.js";
+import { preferAdoptedStylesheets } from "./runtime/ownedStylesheets.js";
+import { enableInspectionPerformanceDiagnostics } from "./inspection/performanceDiagnostics.js";
+import { installLazyRuntimeIdentity } from "./runtime/staticHtmlRuntimeIdentity.js";
+import { createTokenInventory } from "../css/token-inventory/inventory.js";
+export { createMirroredStorage } from "./runtime/inspectorStorage.js";
+export { isSketchDocument, isSketchHandoffRecord } from "./sketch/model.js";
+const MOUNT_ID = "nudge-ui-root";
+const LOADED_FLAG = "__NUDGE_UI_PAGE_INSPECTOR__";
+const COMPUTED_ROOT_ID = "computed:root";
+function isNudgeOwnedSheet(sheet) {
+    const owner = sheet.ownerNode;
+    return owner instanceof Element && owner.hasAttribute("data-nudge-ui");
+}
+function sheetId(sheet, index, base) {
+    const owner = sheet.ownerNode;
+    const viteId = owner instanceof HTMLElement ? owner.dataset.viteDevId : undefined;
+    if (viteId)
+        return viteId;
+    if (sheet.href) {
+        const url = new URL(sheet.href, base);
+        return url.origin === new URL(base).origin ? url.pathname : url.href;
+    }
+    return `inline-style-${index + 1}`;
+}
+function serializeRules(sheet) {
+    return Array.from(sheet.cssRules, (rule) => rule.cssText).join("\n");
+}
+async function collectSheet(sheet, index, base) {
+    const id = sheetId(sheet, index, base);
+    try {
+        return { id, content: serializeRules(sheet) };
+    }
+    catch {
+        if (!sheet.href)
+            return { id, readError: "stylesheet rules are not readable" };
+    }
+    try {
+        const response = await fetch(sheet.href, { mode: "cors", credentials: "omit" });
+        if (!response.ok)
+            return { id, readError: `HTTP ${response.status}` };
+        return { id, content: await response.text() };
+    }
+    catch {
+        return { id, readError: "cross-origin stylesheet without CORS access" };
+    }
+}
+/** Root custom properties missing from readable stylesheets: CORS-blocked sheets, rejected scoped rules, or JS-set variables. */
+function computedRootDeclarations(doc, definedNames) {
+    const declarations = [];
+    const view = doc.defaultView ?? window;
+    for (const element of [doc.documentElement, doc.body]) {
+        if (!element)
+            continue;
+        const style = view.getComputedStyle(element);
+        for (let index = 0; index < style.length; index += 1) {
+            const name = style.item(index);
+            if (!name.startsWith("--") || definedNames.has(name))
+                continue;
+            const value = style.getPropertyValue(name).trim();
+            if (!value)
+                continue;
+            definedNames.add(name);
+            declarations.push(`  ${name}: ${value};`);
+        }
+    }
+    return declarations.length > 0 ? `:root {\n${declarations.join("\n")}\n}` : null;
+}
+function mapDiagnostic(diagnostic) {
+    return {
+        code: diagnostic.code,
+        message: diagnostic.message,
+        module: diagnostic.module ?? diagnostic.artifact ?? "document",
+        ...(diagnostic.exportName !== undefined ? { exportName: diagnostic.exportName } : {}),
+    };
+}
+async function collectDocumentTokens(doc) {
+    const sheets = Array.from(doc.styleSheets).filter((sheet) => !isNudgeOwnedSheet(sheet));
+    const collected = await Promise.all(sheets.map((sheet, index) => collectSheet(sheet, index, doc.location.href)));
+    const inventory = createTokenInventory();
+    for (const [order, sheet] of collected.entries()) {
+        const artifact = {
+            buildTool: "browser",
+            id: sheet.id,
+            stage: "authored",
+            provenance: "project",
+            order,
+            ...(sheet.content !== undefined ? { content: sheet.content } : {}),
+            ...(sheet.readError ? {
+                diagnostics: [{
+                        code: "stylesheet-unreadable",
+                        message: `Stylesheet "${sheet.id}" could not be read: ${sheet.readError}`,
+                        module: sheet.id,
+                    }],
+            } : {}),
+        };
+        inventory.apply(artifact);
+    }
+    const definedNames = new Set(inventory.snapshot().definitions.map((definition) => definition.cssName));
+    const computed = computedRootDeclarations(doc, definedNames);
+    if (computed) {
+        inventory.apply({
+            buildTool: "browser",
+            id: COMPUTED_ROOT_ID,
+            stage: "authored",
+            provenance: "project",
+            order: -1,
+            content: computed,
+        });
+    }
+    const snapshot = inventory.snapshot();
+    return {
+        tokenCatalog: snapshot.definitions.map((definition) => ({
+            ...definition,
+            declarations: definition.declarations.map((declaration) => ({
+                id: declaration.id,
+                order: declaration.order,
+                value: declaration.value,
+                source: declaration.source,
+                important: declaration.important,
+                context: declaration.context,
+            })),
+        })),
+        tokens: snapshot.tokens,
+        tokenDiagnostics: snapshot.diagnostics.map(mapDiagnostic),
+        tokenGeneration: `browser:${snapshot.generation}`,
+    };
+}
+const NO_TOKENS = { tokenCatalog: [], tokens: [], tokenDiagnostics: [], tokenGeneration: "" };
+function runtimeConfig(tokens, unavailableReason) {
+    return {
+        projectId: `page:${location.origin}`,
+        host: "static-html",
+        framework: "HTML",
+        stylingSystem: "CSS custom properties",
+        capabilities: { canvas: !unavailableReason, componentSemantics: false, domNavigation: !unavailableReason },
+        features: { canvasIterations: false, mcp: false, ...(unavailableReason ? { sketch: false } : {}) },
+        ...(unavailableReason ? { inspectionUnavailableReason: unavailableReason } : {}),
+        componentContracts: [],
+        ...tokens,
+    };
+}
+function createMount() {
+    const mount = document.createElement("div");
+    mount.id = MOUNT_ID;
+    document.body.append(mount);
+    return mount;
+}
+/** Mounts the inspector and returns a toggle that fully unmounts and remounts it. */
+function mountPageInspector() {
+    let mount = null;
+    let removeIdentityListeners = null;
+    const enable = () => {
+        setNudgeUiHostDevFlag(true);
+        removeIdentityListeners = installLazyRuntimeIdentity(document);
+        mount = createMount();
+        bootstrapNudgeUi(mount);
+        setInspectorOpen(true);
+    };
+    const disable = (target) => {
+        unmountInspector();
+        removeIdentityListeners?.();
+        removeIdentityListeners = null;
+        releaseLease();
+        setInspectorOpen(false);
+        setNudgeUiHostDevFlag(false);
+        target.remove();
+        mount = null;
+    };
+    enable();
+    return () => {
+        if (mount)
+            disable(mount);
+        else
+            enable();
+    };
+}
+/** Replaces the page content with the iframe editor; the caller loads the inspector into its renderer frames. */
+function mountEditor(onRendererFrameLoad) {
+    // The editor never owns the tab title; it shows the application's own title.
+    const pageTitle = document.title;
+    document.head.replaceChildren();
+    document.body.replaceChildren();
+    for (const element of [document.documentElement, document.body]) {
+        element.removeAttribute("style");
+        element.removeAttribute("hidden");
+        element.removeAttribute("inert");
+    }
+    document.title = pageTitle;
+    const layout = new CSSStyleSheet();
+    layout.replaceSync(`html, body, #${MOUNT_ID} { display: block; width: 100%; height: 100%; margin: 0; overflow: hidden; }`);
+    document.adoptedStyleSheets = [layout];
+    // A parsed meta policy remains active even after the original head is removed.
+    document.addEventListener("securitypolicyviolation", (event) => {
+        if (event.disposition !== "enforce" || event.effectiveDirective !== "frame-src")
+            return;
+        if (getNudgeUiRuntimeConfig().inspectionUnavailableReason)
+            return;
+        configureNudgeUiRuntime(runtimeConfig(NO_TOKENS, "its security policy"));
+    });
+    setNudgeUiHostDevFlag(true);
+    const mount = createMount();
+    bootstrapNudgeUi(mount);
+    setInspectorOpen(true);
+    // Storage hydration can delay the controller mount; watch its host now.
+    const root = mount.shadowRoot ?? mount.attachShadow({ mode: "open" });
+    const frames = () => root.querySelectorAll(`iframe[${CANVAS_RENDERER_ATTR}]`);
+    const applicationDocument = (frame) => {
+        const frameDocument = frame.contentDocument;
+        return frameDocument && frameDocument.location.href !== "about:blank" ? frameDocument : null;
+    };
+    // A frame's `load` waits for every image, so renderers start once the DOM is ready.
+    const announced = new WeakSet();
+    const announceReadyDocuments = () => {
+        for (const frame of frames()) {
+            const frameDocument = applicationDocument(frame);
+            if (!frameDocument || frameDocument.readyState === "loading" || announced.has(frameDocument))
+                continue;
+            announced.add(frameDocument);
+            onRendererFrameLoad?.();
+        }
+    };
+    // Mirrors the primary application frame's title, which follows its navigation.
+    const syncApplicationTitle = () => {
+        for (const frame of frames()) {
+            const frameTitle = applicationDocument(frame)?.title;
+            if (frameTitle) {
+                if (document.title !== frameTitle)
+                    document.title = frameTitle;
+                return;
+            }
+        }
+    };
+    window.setInterval(() => {
+        announceReadyDocuments();
+        syncApplicationTitle();
+    }, 100);
+    // Script-built styles exist only in the application frames, not in this document.
+    const collectFrameTokens = (frame) => {
+        const frameDocument = applicationDocument(frame);
+        if (!frameDocument)
+            return;
+        void collectDocumentTokens(frameDocument).then((tokens) => {
+            if (getNudgeUiRuntimeConfig().inspectionUnavailableReason)
+                return;
+            if (tokens.tokenGeneration !== getNudgeUiRuntimeConfig().tokenGeneration) {
+                configureNudgeUiRuntime(runtimeConfig(tokens));
+            }
+        });
+    };
+    const watched = new WeakSet();
+    const watch = () => {
+        for (const frame of frames()) {
+            if (watched.has(frame))
+                continue;
+            watched.add(frame);
+            frame.addEventListener("load", () => collectFrameTokens(frame));
+            collectFrameTokens(frame);
+        }
+    };
+    new MutationObserver(watch).observe(root, { childList: true, subtree: true });
+    watch();
+}
+function exitEditor() {
+    location.replace(readNudgeUiEditorTarget(location.href) ?? location.href);
+}
+/** A second bundle copy in the same window toggles the first instance, whose stores own the UI. */
+export async function startPageInspector(options = {}) {
+    const target = window;
+    const loaded = target[LOADED_FLAG];
+    if (loaded) {
+        loaded.toggle();
+        return;
+    }
+    const editor = options.surface === "editor" && readNudgeUiEditorTarget(location.href) !== null;
+    let toggle = editor ? exitEditor : null;
+    target[LOADED_FLAG] = {
+        surface: editor ? "editor" : "page",
+        toggle: () => toggle?.(),
+        enablePerformanceDiagnostics: () => enableInspectionPerformanceDiagnostics(document),
+    };
+    if (options.storage)
+        configureInspectorStorage(options.storage);
+    if (options.sketchStorage)
+        configureSketchStorage(options.sketchStorage);
+    if (options.adoptStylesheets)
+        preferAdoptedStylesheets();
+    const tokens = options.unavailableReason ? NO_TOKENS : await collectDocumentTokens(document);
+    configureNudgeUiRuntime(runtimeConfig(tokens, options.unavailableReason));
+    if (editor) {
+        mountEditor(options.onRendererFrameLoad);
+    }
+    else {
+        if (!options.unavailableReason)
+            enablePageSurface();
+        toggle = mountPageInspector();
+    }
+    console.info(`[nudge-ui] Inspector loaded in ${editor ? "editor" : "page"} mode with ${tokens.tokenCatalog.length} tokens`
+        + (tokens.tokenDiagnostics.length > 0 ? ` and ${tokens.tokenDiagnostics.length} stylesheet diagnostics.` : "."), tokens.tokenDiagnostics);
+}
+/** Only acts inside an editor Canvas frame that has no renderer yet. */
+export function startCanvasRenderer(options = {}) {
+    const target = window;
+    if (!isCanvasRenderer() || target[LOADED_FLAG])
+        return;
+    target[LOADED_FLAG] = {
+        surface: "renderer",
+        toggle: () => undefined,
+        enablePerformanceDiagnostics: () => enableInspectionPerformanceDiagnostics(document),
+    };
+    if (options.adoptStylesheets)
+        preferAdoptedStylesheets();
+    setNudgeUiHostDevFlag(true);
+    installLazyRuntimeIdentity(document);
+    configureNudgeUiRuntime(runtimeConfig(NO_TOKENS));
+    bootstrapNudgeUi(createMount());
+    // Renderers inspect their own elements, so they need this document's tokens.
+    const collectTokens = () => {
+        void collectDocumentTokens(document).then((tokens) => {
+            if (tokens.tokenGeneration !== getNudgeUiRuntimeConfig().tokenGeneration) {
+                configureNudgeUiRuntime(runtimeConfig(tokens));
+            }
+        });
+    };
+    collectTokens();
+    if (document.readyState !== "complete")
+        window.addEventListener("load", collectTokens, { once: true });
+}

package/dist/inspector/projection/cssEscapes.d.ts

@@ -1,3 +1,2 @@
-/** CSS-string escaping for selectors assembled from runtime DOM metadata. */
 export declare function escapeCssString(value: string): string;
 export declare function escapeAttrValue(value: string): string;

package/dist/inspector/projection/cssEscapes.js

@@ -1,8 +1,6 @@
-/** CSS-string escaping for selectors assembled from runtime DOM metadata. */
 export function escapeCssString(value) {
-    // Keep ordinary source selectors readable and byte-compatible. Once a
-    // string contains a quote, backslash, or control character, hex-escape the
-    // complete value so punctuation cannot terminate the CSS string early.
+    // Keep ordinary selectors byte-compatible; a value containing a quote,
+    // backslash, or control character is hex-escaped whole to prevent an early string end.
     if (!/["\\\0-\x1f\x7f]/.test(value))
         return value;
     let escaped = "";

package/dist/inspector/projection/draftProjection.d.ts

@@ -3,7 +3,8 @@ import type { RenderedInstanceOverride } from "../changes/editModel.js";
 import { type StructuralChange } from "./structuralProjection.js";
 import type { ComponentOverride } from "../componentSemantics/types.js";
 import { type TextContentChangeRecord } from "../changes/types.js";
-import type { DraftContents } from "../changes/draftChanges.js";
+import type { DraftContents } from "../drafts/model.js";
+import { type RuntimeIdentityClaim } from "../runtime/runtimeIdentityClaims.js";
 export interface DraftProjectionSource extends DraftContents {
     readonly revision: number;
 }
@@ -14,7 +15,6 @@ export interface CompiledManagedStyles {
 export interface SerializedManagedStyles {
     readonly css: string;
 }
-/** A complete, read-only projection for one document-local runtime. */
 export interface DraftProjectionPlan<ManagedStyles> {
     readonly sourceRevision: number;
     readonly managedStyles: ManagedStyles;
@@ -22,9 +22,11 @@ export interface DraftProjectionPlan<ManagedStyles> {
     readonly structuralChanges: readonly StructuralChange[];
     readonly textContentChanges: readonly TextContentChangeRecord[];
     readonly componentOverrides: readonly ComponentOverride[];
+    /** Omitted by hold-to-view-original plans, which keep the attached identities. */
+    readonly runtimeIdentities?: readonly RuntimeIdentityClaim[];
 }
-/** Applies every projection dimension to one document-local runtime. */
 export interface DocumentProjectionAdapter<ManagedStyles> {
+    applyRuntimeIdentities(claims: readonly RuntimeIdentityClaim[]): void;
     applyStructural(changes: readonly StructuralChange[]): void;
     applyRenderedInstances(overrides: readonly RenderedInstanceOverride[]): void;
     applyText(changes: readonly TextContentChangeRecord[]): void;
@@ -32,12 +34,6 @@ export interface DocumentProjectionAdapter<ManagedStyles> {
     applyManagedStyles(styles: ManagedStyles): void;
 }
 export declare function compileDraftProjection(snapshot: DraftProjectionSource): DraftProjectionPlan<CompiledManagedStyles>;
-/**
- * Replaces one document projection in the required order.
- *
- * Structural intent is applied first because later rendered-instance evidence
- * can depend on the restored element order. Managed CSS is applied last so
- * selectors can use the document-local instance markers installed above.
- */
+/** Order matters: identities first (selectors resolve by them), then structural, then managed CSS last (selectors use the instance markers above). */
 export declare function applyDraftProjection<ManagedStyles>(adapter: DocumentProjectionAdapter<ManagedStyles>, plan: DraftProjectionPlan<ManagedStyles>): void;
 export declare function applyHostDraftProjection(plan: DraftProjectionPlan<CompiledManagedStyles>): void;

package/dist/inspector/projection/draftProjection.js

@@ -6,6 +6,7 @@ import { replaceComponentOverrideProjection } from "../componentSemantics/index.
 import { componentChangeToOverride } from "../componentSemantics/changeModel.js";
 import { isComponentChange } from "../changes/types.js";
 import { buildManagedStyleRules } from "../changes/managedStyleProjection.js";
+import { applyRuntimeIdentityClaims, collectRuntimeIdentityClaims, } from "../runtime/runtimeIdentityClaims.js";
 export function compileDraftProjection(snapshot) {
     const changes = [...snapshot.changes];
     const rules = buildManagedStyleRules(changes);
@@ -22,16 +23,13 @@ export function compileDraftProjection(snapshot) {
             .filter(isComponentChange)
             .map(componentChangeToOverride)
             .filter((override) => override !== null),
+        runtimeIdentities: collectRuntimeIdentityClaims(snapshot),
     };
 }
-/**
- * Replaces one document projection in the required order.
- *
- * Structural intent is applied first because later rendered-instance evidence
- * can depend on the restored element order. Managed CSS is applied last so
- * selectors can use the document-local instance markers installed above.
- */
+/** Order matters: identities first (selectors resolve by them), then structural, then managed CSS last (selectors use the instance markers above). */
 export function applyDraftProjection(adapter, plan) {
+    if (plan.runtimeIdentities)
+        adapter.applyRuntimeIdentities(plan.runtimeIdentities);
     adapter.applyStructural(plan.structuralChanges);
     adapter.applyRenderedInstances(plan.instanceOverrides);
     adapter.applyText(plan.textContentChanges);
@@ -39,6 +37,9 @@ export function applyDraftProjection(adapter, plan) {
     adapter.applyManagedStyles(plan.managedStyles);
 }
 const hostDocumentProjectionAdapter = {
+    applyRuntimeIdentities: (claims) => {
+        applyRuntimeIdentityClaims(document, claims);
+    },
     applyStructural: (changes) => {
         applyStructuralProjection(document, changes);
     },

package/dist/inspector/projection/managedStylesheet.d.ts

@@ -20,14 +20,8 @@ export interface PreviewResult {
 }
 export declare function ensureManagedSheet(): void;
 export declare function rulesToCssText(rules: StyleRule[]): string;
-/** Synchronous serialized view of the rules currently projected into the managed sheet. */
 export declare function getManagedSheetText(): string;
-/**
- * Replaces the managed sheet with the canonical projection. Keeping the
- * serialized rules authoritative avoids stale CSSStyleRule references when a
- * framework dev server reparses or reattaches style nodes during a render.
- */
+/** Serialized rules stay authoritative to avoid stale CSSStyleRule references when a framework reparses style nodes. */
 export declare function applyRules(rules: StyleRule[]): void;
-/** Verify what the browser painted after the managed sheet was projected. */
 export declare function verifyPreview(el: HTMLElement | null, property: string, requestedValue: string): PreviewResult;
 export declare function removeManagedSheet(): void;

package/dist/inspector/projection/managedStylesheet.js

@@ -2,6 +2,7 @@ import { getElementComputedStyle } from "../runtime/domRealm.js";
 import { notifyBrowserStylesheetChange } from "../inspection/browserCssInspectionRegistry.js";
 import { escapeAttrValue, escapeCssString } from "./cssEscapes.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
+import { adoptStylesheet, allowsStyleElements, releaseAdoptedStylesheet } from "../runtime/ownedStylesheets.js";
 export { escapeAttrValue, escapeCssString } from "./cssEscapes.js";
 const SHEET_ID = "nudge-ui-styles";
 let managedHeadGuardDocument = null;
@@ -25,6 +26,12 @@ function installManagedHeadGuard(doc) {
 }
 export function ensureManagedSheet() {
     const doc = document;
+    if (!allowsStyleElements(doc)) {
+        // Adopted sheets already cascade after every document stylesheet.
+        adoptStylesheet(doc, SHEET_ID, rulesToCssText(managedRules));
+        exposeManagedSheetText(doc);
+        return;
+    }
     // SAFETY: getElementById returns an Element; the managed style element is created as HTMLStyleElement when missing.
     let el = doc.getElementById(SHEET_ID);
     if (!el) {
@@ -35,9 +42,7 @@ export function ensureManagedSheet() {
     }
     let sheet = el.sheet;
     if (!sheet) {
-        // A browser may reject a newly-authored conditional rule (or a test DOM may
-        // not implement it). Recreate the managed element so later clear/revert
-        // operations can always recover instead of leaving history wedged.
+        // Recreate the element when the browser rejects the sheet so clear/revert can still recover.
         el.remove();
         el = doc.createElement("style");
         el.id = SHEET_ID;
@@ -53,8 +58,10 @@ export function ensureManagedSheet() {
         rehydrateManagedSheet(doc, el);
     }
     installManagedHeadGuard(doc);
+    exposeManagedSheetText(doc);
+}
+function exposeManagedSheetText(doc) {
     if (isNudgeUiDev() && doc.defaultView) {
-        // Keep the canonical CSS available to dev diagnostics.
         doc.defaultView.__nudgeUiGetManagedSheetText = getManagedSheetText;
     }
 }
@@ -88,18 +95,12 @@ export function rulesToCssText(rules) {
     }
     return lines.join("\n");
 }
-/** Canonical rules retained so a framework can rehydrate a moved style node. */
+/** Retained so a framework can rehydrate a moved style node. */
 let managedRules = [];
-/** Synchronous serialized view of the rules currently projected into the managed sheet. */
 export function getManagedSheetText() {
     return rulesToCssText(managedRules);
 }
-/**
- * Rehydrate the CSSOM after moving the managed style element in <head>.
- *
- * Some browsers replace the CSSStyleSheet when that element is reattached.
- * Rewriting the canonical text keeps the new sheet and the model aligned.
- */
+/** Some browsers replace the CSSStyleSheet when the style element is reattached, so rewrite the canonical text. */
 function rehydrateManagedSheet(doc, el) {
     const sheet = el.sheet;
     if (!sheet)
@@ -120,20 +121,25 @@ function rehydrateManagedSheet(doc, el) {
     failedRehydrationCssText = el.sheet.cssRules.length === rules.length ? null : cssText;
     notifyBrowserStylesheetChange(doc);
 }
-/**
- * Writes the canonical projection to the managed style element and retains a
- * copy for rehydration if a framework moves or reparses that element.
- */
 function rebuildSheetText(rules) {
-    // SAFETY: getElementById returns an Element; the managed style element is created as HTMLStyleElement when missing.
-    const el = document.getElementById(SHEET_ID);
-    if (!el)
-        return;
     const desired = rules.map((rule) => ({
         ...rule,
         declarations: { ...rule.declarations },
     }));
     const cssText = rulesToCssText(desired);
+    if (!allowsStyleElements(document)) {
+        const rulesChanged = rulesToCssText(managedRules) !== cssText;
+        managedRules = desired;
+        if (!rulesChanged)
+            return;
+        adoptStylesheet(document, SHEET_ID, cssText);
+        notifyBrowserStylesheetChange(document);
+        return;
+    }
+    // SAFETY: getElementById returns an Element; the managed style element is created as HTMLStyleElement when missing.
+    const el = document.getElementById(SHEET_ID);
+    if (!el)
+        return;
     const rulesChanged = rulesToCssText(managedRules) !== cssText;
     const shouldRetryDroppedRules = el.sheet !== null
         && el.sheet.cssRules.length !== desired.length
@@ -147,11 +153,7 @@ function rebuildSheetText(rules) {
         : null;
     notifyBrowserStylesheetChange(document);
 }
-/**
- * Replaces the managed sheet with the canonical projection. Keeping the
- * serialized rules authoritative avoids stale CSSStyleRule references when a
- * framework dev server reparses or reattaches style nodes during a render.
- */
+/** Serialized rules stay authoritative to avoid stale CSSStyleRule references when a framework reparses style nodes. */
 export function applyRules(rules) {
     ensureManagedSheet();
     const desired = [];
@@ -194,7 +196,6 @@ function hasImportantAuthorRule(el, property) {
     }
     return false;
 }
-/** Verify what the browser painted after the managed sheet was projected. */
 export function verifyPreview(el, property, requestedValue) {
     if (!el || !el.isConnected) {
         return { requestedValue, computedValue: "", status: "conflict", reason: "target-missing" };
@@ -237,6 +238,7 @@ export function removeManagedSheet() {
     const el = document.getElementById(SHEET_ID);
     if (el)
         el.remove();
+    releaseAdoptedStylesheet(document, SHEET_ID);
     managedRules = [];
     failedRehydrationCssText = null;
     notifyBrowserStylesheetChange(document);

package/dist/inspector/projection/renderedInstance.d.ts

@@ -18,50 +18,27 @@ export interface DocumentProjectionReport {
 export interface RenderedInstanceChangeDiagnostic extends DocumentProjectionReport {
     document: "Inspect" | `Canvas ${string}`;
 }
-/** Captures conservative, serializable identity at the moment of the action. */
 export declare function captureRenderedInstance(el: HTMLElement): RenderedInstanceRef | null;
-/**
- * Resolves exactly one element, or declines to apply. Occurrence documents the
- * captured placement, but structural previews can legitimately change it.
- * Evidence, narrowed by a recorded invocation when present, must therefore
- * identify one current candidate before an edit can be applied.
- */
+/** Occurrence documents captured placement, but structural previews can change it; evidence must identify exactly one current candidate. */
 export declare function resolveRenderedInstance(doc: Document, ref: RenderedInstanceRef): ResolutionResult;
-/**
- * Resolves a reference whose source position may have moved since capture.
- * A relocated site still renders matching authored evidence, so an evidence
- * miss there is reported as ambiguous rather than as proof of absence.
- */
+/** A relocated site still renders matching evidence, so an evidence miss is reported as ambiguous, not missing. */
 export declare function resolveMovedRenderedInstance(doc: Document, ref: RenderedInstanceRef): ResolutionResult;
-/**
- * Captures identity for a structural target. When evidence matches several
- * identical outputs, the nearest component invocation whose entire output is
- * this element can still identify it. Otherwise the evidence-only reference
- * is returned and resolves as ambiguous.
- */
+/** Falls back to the nearest component invocation when evidence matches several identical outputs. */
 export declare function captureStructuralTarget(el: HTMLElement): RenderedInstanceRef | null;
-/** Checks stable source/evidence fields without treating a post-move ordinal as identity. */
+/** Ignores the ordinal, which is not identity after a move. */
 export declare function matchesRenderedInstanceEvidence(el: HTMLElement, ref: RenderedInstanceRef): boolean;
-/** Builds an instance override without changing the element's transient edit scope. */
 export declare function buildRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
-/** Creates a serializable override for identity that was already validated. */
 export declare function buildRenderedInstanceOverrideForTarget(target: RenderedInstanceRef): RenderedInstanceOverride;
 export declare function createRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
-/** Returns an active transient target or the canonical target projected here. */
 export declare function getRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
 export declare function clearRenderedInstanceOverride(el: HTMLElement): RenderedInstanceOverride | null;
 export declare function instanceSelector(override: RenderedInstanceOverride): string | null;
-/** Extracts the distinct canonical targets which renderers must resolve. */
 export declare function collectRenderedInstanceOverrides(changes: ReadonlyArray<unknown>): RenderedInstanceOverride[];
-/**
- * The document-projection adapter only applies a new canonical snapshot. A
- * later reconciliation changes diagnostics but never starts a reapply loop.
- */
+/** A later reconciliation changes diagnostics but never starts a reapply loop. */
 export declare function applyRenderedInstanceProjection(doc: Document, overrides: ReadonlyArray<RenderedInstanceOverride>): DocumentProjectionReport[];
 /** Registers controller-owned overrides without projecting them into the editor shell. */
 export declare function setCanonicalRenderedInstanceOverrides(overrides: ReadonlyArray<RenderedInstanceOverride>): void;
 export declare function getRenderedInstanceProjectionReports(doc: Document): readonly DocumentProjectionReport[];
-/** Diagnostics arrive independently when a renderer reports or React reconciles. */
 export declare function subscribeRenderedInstanceDiagnostics(listener: () => void): () => void;
 export declare function getRenderedInstanceDiagnosticRevision(): number;
 export declare function recordCanvasRenderedInstanceProjectionReports(cardId: string, revision: number, reports: readonly DocumentProjectionReport[], projection?: FrameProjection): void;