@braidlabs/core 0.1.1

package/src/compat/born-inert-scripts.js

@@ -0,0 +1,85 @@
+/**
+ * Born-inert scripts.
+ *
+ * Every script element created by fragment code (via the document facade's
+ * `createElement`/`createElementNS`) is neutralized at creation: its `type` attribute is set to
+ * `inert` before fragment code can attach content or insert it. This guarantees that no script
+ * reachable by fragment code can ever execute in the main JS context, no matter how it is
+ * inserted — even through code paths the boundary does not intercept synchronously.
+ *
+ * So that fragment code doesn't observe the neutralization, the script's `type` property and its
+ * `getAttribute`/`setAttribute` methods are shadowed to read and write the real type from/to the
+ * `data-script-type` attribute (the same attribute the gateway uses when neutralizing SSR
+ * content). The shadowing own-properties are removed before the script is activated.
+ */
+const nativeSetAttribute = Element.prototype.setAttribute;
+const nativeGetAttribute = Element.prototype.getAttribute;
+const nativeRemoveAttribute = Element.prototype.removeAttribute;
+const bornInertScripts = new WeakSet();
+export function makeScriptBornInert(script) {
+    nativeSetAttribute.call(script, 'type', 'inert');
+    bornInertScripts.add(script);
+    Object.defineProperties(script, {
+        type: {
+            configurable: true,
+            enumerable: true,
+            get() {
+                return nativeGetAttribute.call(this, 'data-script-type') ?? '';
+            },
+            set(value) {
+                nativeSetAttribute.call(this, 'data-script-type', String(value));
+            },
+        },
+        setAttribute: {
+            configurable: true,
+            writable: true,
+            value: function setAttribute(name, value) {
+                return nativeSetAttribute.call(this, String(name).toLowerCase() === 'type' ? 'data-script-type' : name, value);
+            },
+        },
+        getAttribute: {
+            configurable: true,
+            writable: true,
+            value: function getAttribute(name) {
+                return nativeGetAttribute.call(this, String(name).toLowerCase() === 'type' ? 'data-script-type' : name);
+            },
+        },
+    });
+}
+export function isBornInertScript(script) {
+    return bornInertScripts.has(script);
+}
+/**
+ * Removes the type-shadowing own-properties, leaving the script in the standard inert form
+ * (`type="inert"` plus the real type in `data-script-type`) that the script execution machinery
+ * understands. Used on the asynchronous (boundary observer) activation path, where the script is
+ * already attached to the fragment's DOM in inert form.
+ */
+export function removeBornInertShadowing(script) {
+    if (!bornInertScripts.has(script))
+        return;
+    delete script.type;
+    delete script.setAttribute;
+    delete script.getAttribute;
+    bornInertScripts.delete(script);
+}
+/**
+ * Fully reverts a born-inert script to the live form the application intended (real `type`
+ * attribute, no `data-script-type`). Used on the synchronous (stamped insertion) activation
+ * path, which re-neutralizes the script itself before performing the actual DOM insertion — the
+ * script is never attached to the DOM in live form.
+ */
+export function unwrapBornInertScriptToLive(script) {
+    if (!bornInertScripts.has(script))
+        return;
+    removeBornInertShadowing(script);
+    const realType = nativeGetAttribute.call(script, 'data-script-type');
+    nativeRemoveAttribute.call(script, 'data-script-type');
+    if (realType) {
+        nativeSetAttribute.call(script, 'type', realType);
+    }
+    else {
+        nativeRemoveAttribute.call(script, 'type');
+    }
+}
+//# sourceMappingURL=born-inert-scripts.js.map

package/src/compat/born-inert-scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"born-inert-scripts.js","sourceRoot":"","sources":["../../../../../libs/core/src/compat/born-inert-scripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC;AAC1D,MAAM,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC;AAC1D,MAAM,qBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,eAAe,CAAC;AAEhE,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAqB,CAAC;AAE1D,MAAM,UAAU,mBAAmB,CAAC,MAAyB;IAC3D,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAE7B,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE;QAC9B,IAAI,EAAE;YACJ,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,IAAI;YAChB,GAAG;gBACD,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,EAAE,CAAC;YACjE,CAAC;YACD,GAAG,CAAC,KAAa;gBACf,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACnE,CAAC;SACF;QACD,YAAY,EAAE;YACZ,YAAY,EAAE,IAAI;YAClB,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,SAAS,YAAY,CAAC,IAAY,EAAE,KAAa;gBACtD,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACjH,CAAC;SACF;QACD,YAAY,EAAE;YACZ,YAAY,EAAE,IAAI;YAClB,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,SAAS,YAAY,CAAC,IAAY;gBACvC,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC1G,CAAC;SACF;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAyB;IACzD,OAAO,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAyB;IAChE,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO;IAC1C,OAAQ,MAAc,CAAC,IAAI,CAAC;IAC5B,OAAQ,MAAc,CAAC,YAAY,CAAC;IACpC,OAAQ,MAAc,CAAC,YAAY,CAAC;IACpC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAyB;IACnE,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO;IAC1C,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACrE,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACvD,IAAI,QAAQ,EAAE,CAAC;QACb,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC;SAAM,CAAC;QACN,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/src/compat/document-facade.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A facade override for a single Document member, mirroring the shape of a property descriptor:
+ * either an accessor (`get`, optionally with `set`) or a data member (`value`, typically a method).
+ */
+export type FacadeOverride = {
+    get: () => unknown;
+    set?: (value: any) => void;
+    value?: never;
+} | {
+    value: unknown;
+    get?: never;
+    set?: never;
+};
+export type FacadeOverrides = Record<string, FacadeOverride>;
+/**
+ * Installs a virtualizing facade over the given realm document by splicing a Proxy into its
+ * prototype chain.
+ *
+ * The proxy classifies every property access on the document:
+ *
+ * - members with an override (classified `'virtualized'`) are redirected to the override, which
+ *   operates on the fragment's DOM in the main document,
+ * - members classified `'native'` pass through to the realm document's native behavior,
+ * - spec-defined Document members that are not classified also pass through, but log a one-time
+ *   dev-mode diagnostic so that unaudited API usage by fragments surfaces during development
+ *   instead of silently misbehaving,
+ * - anything else (application-defined expandos, symbols) passes through silently.
+ *
+ * Unlike patching individual properties, the proxy guarantees that *every* property access is
+ * observed, which turns "we forgot to patch X" from a silent wrong-document bug into an
+ * actionable diagnostic.
+ *
+ * Note that unlike `window` (whose prototype is immutable per the HTML spec), a Document
+ * instance has an ordinary, mutable [[Prototype]] slot, so splicing is safe cross-browser. Own
+ * properties of the document instance (e.g. the [LegacyUnforgeable] `location`) are unaffected.
+ *
+ * This patches the fragment's own realm document only — never the host
+ * page's document.
+ *
+ * @param realmDocument the fragment's realm iframe document to install the facade on
+ * @param overrides the virtualized member implementations (see `createDocumentOverrides`)
+ * @returns a function that uninstalls the facade and restores the original prototype chain
+ */
+export declare function installDocumentFacade(realmDocument: Document, overrides: FacadeOverrides): () => void;

package/src/compat/document-facade.js

@@ -0,0 +1,104 @@
+import { documentSurface } from './document-surface.generated.js';
+import { documentMemberClassification } from './document-member-classification.js';
+import { isDevMode } from '../config.js';
+/**
+ * Members inherited by Document from these interfaces always pass through to the realm document
+ * silently. DOM tree traversal and event dispatch are virtualized at other layers (the fragment
+ * boundary and the event system patches in `realm-patches.ts`).
+ */
+const inheritedInterfaces = new Set(['Node', 'EventTarget']);
+let lazyUnauditedDocumentMembers;
+/**
+ * Returns whether the given member is a spec-defined Document member that has not been audited
+ * for compat fragment contexts yet. Access to such members falls through to the realm document
+ * and triggers a dev-mode diagnostic.
+ */
+function isUnauditedDocumentMember(name) {
+    lazyUnauditedDocumentMembers ??= new Set(Object.keys(documentSurface).filter((member) => !(member in documentMemberClassification) && !inheritedInterfaces.has(documentSurface[member].from)));
+    return lazyUnauditedDocumentMembers.has(name);
+}
+/**
+ * Installs a virtualizing facade over the given realm document by splicing a Proxy into its
+ * prototype chain.
+ *
+ * The proxy classifies every property access on the document:
+ *
+ * - members with an override (classified `'virtualized'`) are redirected to the override, which
+ *   operates on the fragment's DOM in the main document,
+ * - members classified `'native'` pass through to the realm document's native behavior,
+ * - spec-defined Document members that are not classified also pass through, but log a one-time
+ *   dev-mode diagnostic so that unaudited API usage by fragments surfaces during development
+ *   instead of silently misbehaving,
+ * - anything else (application-defined expandos, symbols) passes through silently.
+ *
+ * Unlike patching individual properties, the proxy guarantees that *every* property access is
+ * observed, which turns "we forgot to patch X" from a silent wrong-document bug into an
+ * actionable diagnostic.
+ *
+ * Note that unlike `window` (whose prototype is immutable per the HTML spec), a Document
+ * instance has an ordinary, mutable [[Prototype]] slot, so splicing is safe cross-browser. Own
+ * properties of the document instance (e.g. the [LegacyUnforgeable] `location`) are unaffected.
+ *
+ * This patches the fragment's own realm document only — never the host
+ * page's document.
+ *
+ * @param realmDocument the fragment's realm iframe document to install the facade on
+ * @param overrides the virtualized member implementations (see `createDocumentOverrides`)
+ * @returns a function that uninstalls the facade and restores the original prototype chain
+ */
+export function installDocumentFacade(realmDocument, overrides) {
+    const originalPrototype = Object.getPrototypeOf(realmDocument);
+    const overrideMap = new Map(Object.entries(overrides));
+    const warnedMembers = new Set();
+    if (isDevMode()) {
+        for (const overriddenMember of overrideMap.keys()) {
+            if (documentMemberClassification[overriddenMember] !== 'virtualized') {
+                console.warn(`Braid compat: document facade override '${overriddenMember}' is not classified as 'virtualized' in document-member-classification.ts! Please classify it to keep the audit trail consistent.`);
+            }
+        }
+    }
+    function warnIfUnaudited(propertyName) {
+        if (isUnauditedDocumentMember(propertyName) && !warnedMembers.has(propertyName)) {
+            warnedMembers.add(propertyName);
+            console.warn(`Braid compat: a fragment accessed 'document.${propertyName}', which has not been audited for compat fragment contexts yet and falls through to the fragment's hidden realm document.\n` +
+                `If the fragment misbehaves in a way related to this API, please report it at https://github.com/braidjs/braid/issues`);
+        }
+    }
+    const facadeProxy = new Proxy(originalPrototype, {
+        get(target, property, receiver) {
+            if (typeof property === 'string') {
+                const override = overrideMap.get(property);
+                if (override) {
+                    return override.get ? override.get() : override.value;
+                }
+                if (isDevMode()) {
+                    warnIfUnaudited(property);
+                }
+            }
+            return Reflect.get(target, property, receiver);
+        },
+        set(target, property, value, receiver) {
+            if (typeof property === 'string') {
+                const override = overrideMap.get(property);
+                if (override) {
+                    if (override.set) {
+                        override.set(value);
+                        return true;
+                    }
+                    // read-only virtualized member: fail the assignment just like an assignment to a
+                    // non-writable property would (throws in strict mode, silently ignored otherwise)
+                    return false;
+                }
+                if (isDevMode()) {
+                    warnIfUnaudited(property);
+                }
+            }
+            return Reflect.set(target, property, value, receiver);
+        },
+    });
+    Object.setPrototypeOf(realmDocument, facadeProxy);
+    return function uninstallDocumentFacade() {
+        Object.setPrototypeOf(realmDocument, originalPrototype);
+    };
+}
+//# sourceMappingURL=document-facade.js.map

package/src/compat/document-facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-facade.js","sourceRoot":"","sources":["../../../../../libs/core/src/compat/document-facade.ts"],"names":[],"mappings":"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"}

package/src/compat/document-member-classification.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Classification of the Document API surface for compat fragment contexts (the WebIDL audit
+ * manifest for the document facade).
+ *
+ * Every entry records the result of auditing a Document member for use by application code
+ * running inside a compat fragment:
+ *
+ * - `'virtualized'` — the member is reimplemented by the document facade (see
+ *   `document-overrides.ts`) so that it operates on the fragment's DOM in the main document
+ *   (shadow root / `<braid-document>`) instead of the fragment's hidden realm iframe document.
+ *
+ * - `'native'` — the member was audited and the realm document's native behavior is the desired
+ *   behavior for fragments, so it intentionally passes through the facade untouched.
+ *
+ * Spec-defined Document members absent from this map have not been audited yet. They pass
+ * through to the realm document's native behavior, and the facade logs a dev-mode diagnostic
+ * when a fragment uses them, so unaudited API usage surfaces during development instead of
+ * failing silently — and feeds the compat fidelity telemetry the architecture calls for.
+ *
+ * Members inherited from Node and EventTarget always pass through silently — DOM tree traversal
+ * and event dispatch are virtualized at other layers (the fragment boundary and the event
+ * system patches in `realm-patches.ts`).
+ *
+ * Note: `location` is a [LegacyUnforgeable] own property of the document instance and can never
+ * be intercepted via the prototype chain, so it is intentionally not classified here. The compat
+ * realm iframe's `src` is set to the fragment's url, which makes the realm's native
+ * `document.location` correct for fragments.
+ */
+export type DocumentMemberClassification = 'virtualized' | 'native';
+export declare const documentMemberClassification: Readonly<Record<string, DocumentMemberClassification>>;

package/src/compat/document-member-classification.js

@@ -0,0 +1,64 @@
+export const documentMemberClassification = {
+    // --- virtualized: reimplemented against the fragment's DOM in the main document ---
+    // document metadata and state
+    title: 'virtualized',
+    readyState: 'virtualized',
+    currentScript: 'virtualized',
+    activeElement: 'virtualized',
+    // styles
+    styleSheets: 'virtualized',
+    adoptedStyleSheets: 'virtualized',
+    // document tree accessors (html/head/body are represented by braid-html/braid-head/braid-body custom elements)
+    documentElement: 'virtualized',
+    head: 'virtualized',
+    body: 'virtualized',
+    children: 'virtualized',
+    childElementCount: 'virtualized',
+    firstElementChild: 'virtualized',
+    lastElementChild: 'virtualized',
+    firstChild: 'virtualized',
+    lastChild: 'virtualized',
+    hasChildNodes: 'virtualized',
+    // querying
+    querySelector: 'virtualized',
+    querySelectorAll: 'virtualized',
+    getElementById: 'virtualized',
+    getElementsByClassName: 'virtualized',
+    getElementsByName: 'virtualized',
+    getElementsByTagName: 'virtualized',
+    getElementsByTagNameNS: 'virtualized',
+    // event dispatch (listeners registered via addEventListener are retargeted by the event system patches)
+    dispatchEvent: 'virtualized',
+    // node creation (nodes must be created in the main document so they can be attached to the fragment's DOM)
+    createElement: 'virtualized',
+    createElementNS: 'virtualized',
+    createAttributeNS: 'virtualized',
+    createCDATASection: 'virtualized',
+    createComment: 'virtualized',
+    createDocumentFragment: 'virtualized',
+    createEvent: 'virtualized',
+    createExpression: 'virtualized',
+    createNSResolver: 'virtualized',
+    createNodeIterator: 'virtualized',
+    createProcessingInstruction: 'virtualized',
+    createRange: 'virtualized',
+    createTextNode: 'virtualized',
+    createTreeWalker: 'virtualized',
+    // --- native: audited, the realm document's native behavior is correct for fragments ---
+    // the compat realm iframe is same-origin with the main document, so it shares the cookie jar
+    cookie: 'native',
+    // fragments must see the fragment's window (the realm iframe's window), not the main window
+    defaultView: 'native',
+    // the realm iframe's src is set to the fragment's url, so url-related members are correct natively
+    URL: 'native',
+    documentURI: 'native',
+    // document encoding/mode metadata of the realm document matches a standard html document
+    compatMode: 'native',
+    characterSet: 'native',
+    charset: 'native',
+    inputEncoding: 'native',
+    contentType: 'native',
+    // importNode deliberately creates nodes in the fragment's realm (used by the script execution machinery)
+    importNode: 'native',
+};
+//# sourceMappingURL=document-member-classification.js.map

package/src/compat/document-member-classification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-member-classification.js","sourceRoot":"","sources":["../../../../../libs/core/src/compat/document-member-classification.ts"],"names":[],"mappings":"AA8BA,MAAM,CAAC,MAAM,4BAA4B,GAA2D;IAClG,qFAAqF;IAErF,8BAA8B;IAC9B,KAAK,EAAE,aAAa;IACpB,UAAU,EAAE,aAAa;IACzB,aAAa,EAAE,aAAa;IAC5B,aAAa,EAAE,aAAa;IAE5B,SAAS;IACT,WAAW,EAAE,aAAa;IAC1B,kBAAkB,EAAE,aAAa;IAEjC,+GAA+G;IAC/G,eAAe,EAAE,aAAa;IAC9B,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,aAAa;IACnB,QAAQ,EAAE,aAAa;IACvB,iBAAiB,EAAE,aAAa;IAChC,iBAAiB,EAAE,aAAa;IAChC,gBAAgB,EAAE,aAAa;IAC/B,UAAU,EAAE,aAAa;IACzB,SAAS,EAAE,aAAa;IACxB,aAAa,EAAE,aAAa;IAE5B,WAAW;IACX,aAAa,EAAE,aAAa;IAC5B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,aAAa;IACrC,iBAAiB,EAAE,aAAa;IAChC,oBAAoB,EAAE,aAAa;IACnC,sBAAsB,EAAE,aAAa;IAErC,wGAAwG;IACxG,aAAa,EAAE,aAAa;IAE5B,2GAA2G;IAC3G,aAAa,EAAE,aAAa;IAC5B,eAAe,EAAE,aAAa;IAC9B,iBAAiB,EAAE,aAAa;IAChC,kBAAkB,EAAE,aAAa;IACjC,aAAa,EAAE,aAAa;IAC5B,sBAAsB,EAAE,aAAa;IACrC,WAAW,EAAE,aAAa;IAC1B,gBAAgB,EAAE,aAAa;IAC/B,gBAAgB,EAAE,aAAa;IAC/B,kBAAkB,EAAE,aAAa;IACjC,2BAA2B,EAAE,aAAa;IAC1C,WAAW,EAAE,aAAa;IAC1B,cAAc,EAAE,aAAa;IAC7B,gBAAgB,EAAE,aAAa;IAE/B,yFAAyF;IAEzF,6FAA6F;IAC7F,MAAM,EAAE,QAAQ;IAEhB,4FAA4F;IAC5F,WAAW,EAAE,QAAQ;IAErB,mGAAmG;IACnG,GAAG,EAAE,QAAQ;IACb,WAAW,EAAE,QAAQ;IAErB,yFAAyF;IACzF,UAAU,EAAE,QAAQ;IACpB,YAAY,EAAE,QAAQ;IACtB,OAAO,EAAE,QAAQ;IACjB,aAAa,EAAE,QAAQ;IACvB,WAAW,EAAE,QAAQ;IAErB,yGAAyG;IACzG,UAAU,EAAE,QAAQ;CACrB,CAAC"}

package/src/compat/document-overrides.d.ts

@@ -0,0 +1,44 @@
+import { FacadeOverrides } from './document-facade.js';
+/**
+ * Hooks provided by the fragment boundary. Nodes created via the facade are stamped with the
+ * fragment's boundary prototype, and scripts are neutralized at creation ("born inert").
+ */
+export interface DocumentBoundaryHooks {
+    stampNode(node: Node): void;
+    makeScriptBornInert(script: HTMLScriptElement): void;
+}
+/**
+ * Everything the document overrides need from the surrounding compat context.
+ *
+ * All dependencies are injected so that this module stays free of imports with side effects and
+ * can be exercised by unit tests outside of a browser.
+ */
+export interface DocumentOverridesContext {
+    /** The document of the fragment's hidden realm iframe. */
+    realmDocument: Document;
+    /** The main frame's document which owns the fragment's DOM. */
+    mainDocument: Document;
+    /** The `<braid-document>` element that acts as the fragment's virtual document element in the main DOM. */
+    braidDocumentElement: HTMLElement;
+    /** The shadow root of the `<fragment-slot>` element that contains the fragment's DOM. */
+    fragmentShadowRoot: ShadowRoot;
+    /** Whether the fragment's navigation is bound to the main window's navigation. */
+    boundNavigation: boolean;
+    /** Returns the virtualized readyState of the fragment's document. */
+    getRealmDocumentReadyState: () => DocumentReadyState;
+    /** Returns the inert clone (in the main DOM) of the script currently executing in the fragment's realm. */
+    getCurrentScript: () => HTMLScriptElement | undefined;
+    /** Boundary hooks; absent only in unit tests that exercise the overrides in isolation. */
+    boundary?: DocumentBoundaryHooks;
+}
+/**
+ * Creates the facade overrides that virtualize the Document API surface for a compat fragment.
+ *
+ * Each override redirects a Document member to operate on the fragment's DOM in the main
+ * document (the shadow root of `<fragment-slot>` and its `<braid-document>` element) instead of
+ * the hidden realm's document.
+ *
+ * Every member overridden here must be classified as `'virtualized'` in
+ * `document-member-classification.ts`.
+ */
+export declare function createDocumentOverrides(ctx: DocumentOverridesContext): FacadeOverrides;

package/src/compat/document-overrides.js

@@ -0,0 +1,225 @@
+import { rewriteQuerySelector } from '../utils/selector-helpers.js';
+/**
+ * Creates the facade overrides that virtualize the Document API surface for a compat fragment.
+ *
+ * Each override redirects a Document member to operate on the fragment's DOM in the main
+ * document (the shadow root of `<fragment-slot>` and its `<braid-document>` element) instead of
+ * the hidden realm's document.
+ *
+ * Every member overridden here must be classified as `'virtualized'` in
+ * `document-member-classification.ts`.
+ */
+export function createDocumentOverrides(ctx) {
+    const { realmDocument, mainDocument, braidDocumentElement, fragmentShadowRoot, boundNavigation } = ctx;
+    /**
+     * Elements created via the facade enter the fragment boundary at birth: scripts are
+     * neutralized before fragment code can arm them, and every created element is stamped so that
+     * operations on it are intercepted at the boundary rather than via global patches.
+     */
+    function admitCreatedElement(element) {
+        if (ctx.boundary) {
+            if (element instanceof HTMLScriptElement) {
+                ctx.boundary.makeScriptBornInert(element);
+            }
+            ctx.boundary.stampNode(element);
+        }
+        return element;
+    }
+    return {
+        title: {
+            get: function () {
+                return (
+                // https://html.spec.whatwg.org/multipage/dom.html#document.title
+                braidDocumentElement.querySelector('title')?.textContent?.trim() ?? '[braid fragment document]');
+            },
+            set: function (newTitle) {
+                const titleElement = braidDocumentElement.querySelector('title');
+                if (titleElement) {
+                    titleElement.textContent = newTitle;
+                }
+                if (boundNavigation) {
+                    mainDocument.title = newTitle;
+                }
+            },
+        },
+        readyState: {
+            get() {
+                return ctx.getRealmDocumentReadyState();
+            },
+        },
+        currentScript: {
+            get() {
+                return ctx.getCurrentScript();
+            },
+        },
+        // redirect getElementById to be a scoped braidDocumentElement.querySelector query
+        getElementById: {
+            value(id) {
+                return braidDocumentElement.querySelector(`[id="${id}"]`);
+            },
+        },
+        getElementsByClassName: {
+            value(names) {
+                return braidDocumentElement.getElementsByClassName(names);
+            },
+        },
+        getElementsByName: {
+            value(name) {
+                return braidDocumentElement.querySelector(`[name="${name}"]`);
+            },
+        },
+        getElementsByTagNameNS: {
+            value(namespaceURI, name) {
+                return braidDocumentElement.getElementsByTagNameNS(namespaceURI, name);
+            },
+        },
+        // redirect to mainDocument
+        activeElement: {
+            get: () => {
+                return (fragmentShadowRoot.activeElement ??
+                    (mainDocument.activeElement === mainDocument.body ? realmDocument.body : null));
+            },
+        },
+        styleSheets: {
+            get: () => {
+                return fragmentShadowRoot.styleSheets;
+            },
+        },
+        adoptedStyleSheets: {
+            get() {
+                return fragmentShadowRoot.adoptedStyleSheets;
+            },
+            set(value) {
+                fragmentShadowRoot.adoptedStyleSheets = value;
+            },
+        },
+        dispatchEvent: {
+            value(event) {
+                return braidDocumentElement.dispatchEvent(event);
+            },
+        },
+        childElementCount: {
+            get() {
+                return braidDocumentElement.childElementCount;
+            },
+        },
+        hasChildNodes: {
+            value() {
+                return braidDocumentElement.hasChildNodes();
+            },
+        },
+        children: {
+            get() {
+                return braidDocumentElement.children;
+            },
+        },
+        firstElementChild: {
+            get() {
+                return braidDocumentElement.firstElementChild;
+            },
+        },
+        firstChild: {
+            get() {
+                return braidDocumentElement.firstChild;
+            },
+        },
+        lastElementChild: {
+            get() {
+                return braidDocumentElement.lastElementChild;
+            },
+        },
+        lastChild: {
+            get() {
+                return braidDocumentElement.lastChild;
+            },
+        },
+        /**
+         * The following properties are references to special elements in a Document (html, head,
+         * body). The browser does not allow multiple instances of these elements within a Document,
+         * so we cannot render true <html>, <head>, <body> elements within the shadow root of a
+         * fragment.
+         *
+         * Instead, render custom elements (braid-html, braid-head, braid-body) that act like the
+         * html, head, and body. The tagName and nodeName properties of these custom elements are
+         * then patched to return "HTML", "HEAD", and "BODY", respectively.
+         *
+         * CSS selector queries that contain html/head/body tag selectors are rewritten to the
+         * custom elements.
+         */
+        querySelector: {
+            value(selector) {
+                return braidDocumentElement.querySelector(rewriteQuerySelector(selector));
+            },
+        },
+        querySelectorAll: {
+            value(selector) {
+                return braidDocumentElement.querySelectorAll(rewriteQuerySelector(selector));
+            },
+        },
+        getElementsByTagName: {
+            value(tagName) {
+                // The shadowRoot node itself does not have a getElementsByTagName method.
+                // For html, head, and body, rely on the rewritten querySelectorAll query.
+                // This will return a NodeList instead of an HTMLCollection, which will suffice for most use cases.
+                return braidDocumentElement.querySelectorAll(rewriteQuerySelector(tagName));
+            },
+        },
+        documentElement: {
+            get() {
+                return braidDocumentElement.querySelector('braid-html') ?? braidDocumentElement.firstElementChild;
+            },
+        },
+        head: {
+            get() {
+                return braidDocumentElement.querySelector('braid-head') ?? braidDocumentElement.firstElementChild;
+            },
+        },
+        body: {
+            get() {
+                return braidDocumentElement.querySelector('braid-body') ?? braidDocumentElement.firstElementChild;
+            },
+        },
+        // document.createElement & friends overrides: nodes must be created in the main document
+        // so that they can be attached to the fragment's DOM without adoption
+        ...Object.fromEntries([
+            'createAttributeNS',
+            'createCDATASection',
+            'createComment',
+            'createDocumentFragment',
+            'createEvent',
+            'createExpression',
+            'createNSResolver',
+            'createNodeIterator',
+            'createProcessingInstruction',
+            'createRange',
+            'createTextNode',
+            'createTreeWalker',
+        ].map((createProperty) => [
+            createProperty,
+            {
+                value: function compatCreateFn(...args) {
+                    return mainDocument[createProperty].apply(mainDocument, args);
+                },
+            },
+        ])),
+        createElement: {
+            value: function createElement(...[tagName, ...rest]) {
+                const element = Document.prototype.createElement.apply(
+                // create the element within the realm document if it contains a dash as it could be a
+                // custom element defined only in the fragment's realm
+                tagName.includes('-') ? realmDocument : mainDocument, [tagName, ...rest]);
+                return admitCreatedElement(element);
+            },
+        },
+        createElementNS: {
+            value: function createElementNS(...[namespaceURI, tagName, ...rest]) {
+                const element = Document.prototype.createElementNS.apply(
+                // create the element within the realm document if it contains a dash as it could be a
+                // custom element defined only in the fragment's realm
+                namespaceURI === 'http://www.w3.org/1999/xhtml' && tagName.includes('-') ? realmDocument : mainDocument, [namespaceURI, tagName, ...rest]);
+                return admitCreatedElement(element);
+            },
+        },
+    };
+}
+//# sourceMappingURL=document-overrides.js.map

package/src/compat/document-overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-overrides.js","sourceRoot":"","sources":["../../../../../libs/core/src/compat/document-overrides.ts"],"names":[],"mappings":"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"}

package/src/compat/document-surface.generated.d.ts

@@ -0,0 +1,21 @@
+/**
+ * GENERATED FILE — DO NOT EDIT!
+ *
+ * Generated by scripts/generate-document-surface.mjs from @webref/idl@3.82.1 in the
+ * Jefftopia/web-fragments fork and ported into Braid verbatim. To regenerate, run the fork's
+ * `pnpm generate:document-surface` and copy the result here.
+ *
+ * Enumerates the spec-defined API surface of the Document interface (including partials and mixins such as
+ * FontFaceSource, GeometryUtils, NonElementParentNode, DocumentOrShadowRoot, ParentNode, XPathEvaluatorBase, GlobalEventHandlers, ARIANotifyMixin)
+ * as well as the inherited Node and EventTarget interfaces.
+ */
+export interface DocumentSurfaceMember {
+    /** Whether the member is declared as a WebIDL attribute or operation. */
+    kind: 'attribute' | 'operation';
+    /** The interface or mixin that declares the member. */
+    from: string;
+}
+/**
+ * All named properties that browsers expose on a Document instance per the current browser specifications.
+ */
+export declare const documentSurface: Readonly<Record<string, DocumentSurfaceMember>>;