@hyperframes/inspector 0.0.0-stage → 0.8.152

package/dist/types/core/src/colorGradingCurves.d.ts

@@ -0,0 +1,8 @@
+export type HfColorCurvePoint = readonly [input: number, output: number];
+export type HfHueCurvePoint = readonly [hueDegrees: number, delta: number];
+export declare const HF_COLOR_CURVE_LUT_SIZE = 1024;
+export declare const HF_COLOR_CURVE_MAX_POINTS = 16;
+/** Samples a shape-preserving cubic curve into a GPU-ready 1D lookup table. */
+export declare function compileHfColorCurve(points: readonly HfColorCurvePoint[], size?: number): Float32Array;
+/** Samples a periodic hue curve without duplicating the 0/360-degree texel. */
+export declare function compileHfHueCurve(points: readonly HfHueCurvePoint[], outputMin: number, outputMax: number, size?: number): Float32Array;

package/dist/types/core/src/colorLuts.d.ts

@@ -0,0 +1,24 @@
+export type CubeLutVec3 = readonly [number, number, number];
+export interface CubeLut3D {
+    title: string | null;
+    size: number;
+    domainMin: CubeLutVec3;
+    domainMax: CubeLutVec3;
+    data: Float32Array;
+}
+export interface PackedCubeLut2D {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+export interface ParseCubeLutOptions {
+    maxSize?: number;
+}
+export declare class CubeLutParseError extends Error {
+    readonly lineNumber: number | null;
+    constructor(message: string, lineNumber?: number | null);
+}
+export declare const DEFAULT_MAX_CUBE_LUT_SIZE = 64;
+export declare function parseCubeLut(input: string, options?: ParseCubeLutOptions): CubeLut3D;
+export declare function unitFloatToByte(value: number): number;
+export declare function packCubeLutToRgba8(lut: CubeLut3D): PackedCubeLut2D;

package/dist/types/core/src/compiler/assetPaths.d.ts

@@ -0,0 +1 @@
+export { CSS_URL_RE, PATH_ATTRS, isNonRelativeUrl, isPathInside, } from "@hyperframes/parsers/asset-paths";

package/dist/types/core/src/compiler/compositionAssembly.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Composition assembly decisions — the questions both assembly paths answer.
+ *
+ * A composition is assembled twice in this repo: `compiler/inlineSubCompositions.ts`
+ * assembles it for rendering (Node, linkedom, synchronous, emits strings) and
+ * `runtime/compositionLoader.ts` assembles it for mounting (browser, fetch, live
+ * DOM, executes scripts). Their I/O is genuinely different; their *decisions* are
+ * not. This module owns the decisions:
+ *
+ * - which nodes are a composition's asset sources, and in what order
+ * - which `<head>` elements hoist into the host document
+ * - the composition's scope identity (CSS scope, script scope, authored root id)
+ * - which nodes carry the composition's declared variable defaults
+ * - how nested `data-composition-src` hosts are enumerated
+ *
+ * It is deliberately DOM-free, filesystem-free and network-free: the runtime is
+ * bundled by esbuild into the IIFE published to a CDN, so anything reachable
+ * from `runtime/entry.ts` ships to every viewer. It takes narrow structural
+ * types instead of `Document`/`Element` for the same reason `compositionScoping.ts`
+ * takes strings — so both a linkedom document and a live browser document
+ * satisfy it without an `as T` cast at either call site.
+ */
+export declare function isJavaScriptType(el: AssemblyAttributed): boolean;
+export declare function executableScripts<TElement extends AssemblyAttributed>(node: AssemblyQueryable<TElement> | null | undefined): TElement[];
+/** The styles, scripts and links both paths extract, so the mounted copy must drop them. */
+export declare function extractedCompositionAssets<TElement extends AssemblyAttributed>(node: AssemblyQueryable<TElement>): TElement[];
+/**
+ * The compiler's nesting cap, enforced against the ancestry chain rather than a
+ * counter so a wide tree is not penalised for a deep sibling.
+ */
+export declare const MAX_SUB_COMPOSITION_DEPTH = 20;
+/** An element this module only ever reads attributes from. */
+export interface AssemblyAttributed {
+    getAttribute(name: string): string | null;
+}
+/** A node this module only ever searches with a CSS selector. */
+export interface AssemblyQueryable<TElement> {
+    querySelectorAll(selectors: string): Iterable<TElement>;
+}
+export interface CompositionAssemblyInput<TElement extends AssemblyAttributed> {
+    /**
+     * The composition's content: a `<template>`'s content when the composition is
+     * templated, the parsed document's `<body>` otherwise.
+     *
+     * Asset sources are collected from the WHOLE content node, never from the
+     * composition root alone. The canonical authored shape puts `<style>`/`<script>`
+     * as SIBLINGS of the root inside `<template>`; scanning only the root dropped a
+     * composition's entire stylesheet on mount while its render stayed correct.
+     */
+    contentNode: AssemblyQueryable<TElement>;
+    /**
+     * The parsed document's `<head>`, when the composition was loaded as a full
+     * HTML document. Omit it for an inline `<template>`, which has no head of its
+     * own.
+     */
+    head?: AssemblyQueryable<TElement> | null;
+    /**
+     * The parsed document's `<html>` element, when there is one. It is the first
+     * variable-default carrier; see `variableDefaultCarriers`.
+     */
+    documentElement?: TElement | null;
+    /**
+     * True when `contentNode` came from a `<template>`. A templated composition's
+     * `<head>` styles and scripts are not part of the composition — the template
+     * already carries everything it needs — so they are not collected.
+     */
+    hasTemplate: boolean;
+    /**
+     * The composition id the host asks this composition to mount as, or `null` for
+     * an anonymous host.
+     */
+    compositionId: string | null;
+}
+export interface CompositionAssemblyPlan<TElement extends AssemblyAttributed> {
+    /**
+     * The composition root inside `contentNode`. Matched on an EXACT id when the
+     * host names one — a template may intentionally use a different local id (a
+     * `captions-comp` host mounting a `captions` template), and flattening that
+     * fallback root changes the assembled DOM. Anonymous hosts fall back to the
+     * first root in the content.
+     */
+    innerRoot: TElement | null;
+    /**
+     * The id CSS is scoped to: the host's id when it names one, otherwise the id
+     * declared inside the content.
+     */
+    authoredCompositionId: string | null;
+    /**
+     * The id composition scripts are scoped to. It differs from
+     * `authoredCompositionId` only when a host names an id that no root inside the
+     * content declares: CSS stays on the host's id while scripts follow the id the
+     * content actually declares, so a script's self-referencing
+     * `querySelector('[data-composition-id="X"]')` still resolves.
+     */
+    scriptCompositionId: string | null;
+    /** The `id` attribute authored on the composition root, if any. */
+    authoredRootId: string | null;
+    /** `<style>` sources in injection order: head-sourced first, then content. */
+    styleSources: TElement[];
+    /**
+     * `<script>` sources in execution order: head-sourced first, then content. A
+     * head script (a GSAP CDN tag in a non-templated composition) has to run
+     * before the content scripts that call into it.
+     */
+    scriptSources: TElement[];
+    /** Head and content links to hoist into the host document. */
+    linkSources: TElement[];
+    /** Inert scripts the mounted root would leave behind; both paths mount them next to it. */
+    inertScriptsOutsideRoot: TElement[];
+    /**
+     * Nodes that may declare the composition's variable defaults, in precedence
+     * order — later wins. Full-document compositions declare on `<html>`;
+     * template/fragment compositions declare on the `[data-composition-id]` root
+     * div, because they have no `<html>` of their own. Callers read the declared
+     * defaults off each carrier and merge left to right.
+     */
+    variableDefaultCarriers: TElement[];
+}
+/**
+ * Answer, for one composition, where its assets come from, in what order, and
+ * how it is identified. Pure: it reads attributes and runs selectors, and does
+ * not mutate, fetch, or touch a filesystem.
+ */
+export declare function planCompositionAssembly<TElement extends AssemblyAttributed & AssemblyQueryable<TElement>>(input: CompositionAssemblyInput<TElement>): CompositionAssemblyPlan<TElement>;
+export type NestedHostSkipReason = "circular composition reference" | "nesting depth exceeded";
+export interface NestedCompositionHost<TElement> {
+    host: TElement;
+    src: string;
+}
+export interface NestedCompositionHosts<TElement> {
+    hosts: NestedCompositionHost<TElement>[];
+    skipped: {
+        src: string;
+        reason: NestedHostSkipReason;
+    }[];
+}
+/**
+ * Enumerate the sub-composition hosts nested inside a composition that has just
+ * been assembled, refusing the two shapes that do not terminate.
+ *
+ * `ancestry` is the chain down to and including the assembled composition's own
+ * `src`, so a top-level host is enumerated with `[itsOwnSrc]`.
+ */
+export declare function enumerateNestedCompositionHosts<TElement extends AssemblyAttributed>(assembledHost: AssemblyQueryable<TElement>, ancestry: readonly string[]): NestedCompositionHosts<TElement>;

package/dist/types/core/src/compiler/compositionScoping.d.ts

@@ -0,0 +1,28 @@
+export declare function scopeCssToComposition(css: string, compositionId: string, scopeSelectorOverride?: string, authoredRootId?: string | null, options?: {
+    compoundAuthoredRoot?: boolean;
+    scopeRootSelectors?: boolean;
+}): string;
+/** Drops repeats of an identical `@font-face` across the given style texts, keeping the last copy:
+ * the last matching rule is the one the browser uses, so a rule in between never gains precedence. */
+export declare function dedupeFontFaceRules(styleTexts: string[]): string[];
+export declare function scopedModulePrelude(timelineCompositionId: string, compositionSrc?: string | null): string;
+export declare function wrapScopedCompositionScript(source: string, compositionId: string, errorLabel?: string, scopeSelectorOverride?: string, timelineCompositionId?: string, authoredRootId?: string | null, compositionSrc?: string | null): string;
+export declare function wrapInlineScriptWithErrorBoundary(source: string, errorLabel: string): string;
+/**
+ * Build the statement that populates `window.__hfVariablesByComp` — the table
+ * the scoped `getVariables` above reads. Returns `null` when there are no
+ * per-instance values.
+ *
+ * The WRITER lives next to the READER (the scoped `getVariables` in
+ * `wrapScopedCompositionScript`) on purpose: every compile path that wraps the
+ * reader MUST also emit this writer before the sub-comp scripts run. The
+ * render compiler (`htmlCompiler`) inlined the reader scripts but never emitted
+ * the writer while the preview bundler (`htmlBundler`) did, so
+ * `getVariables()` returned `{}` only during render — parametrized sub-comps
+ * silently shipped blank/default text in the final MP4 while snapshot QA passed
+ * (issue #2064). Both callers now share this one builder so they can't drift.
+ *
+ * Values, keys and composition ids are all attacker-reachable, so the whole
+ * table goes through `jsonScriptLiteral` — see there for why.
+ */
+export declare function buildVariablesByCompScript(variablesByComp: Record<string, Record<string, unknown>>): string | null;

package/dist/types/core/src/compiler/externalScripts.d.ts

@@ -0,0 +1,8 @@
+export interface ExternalScriptAttributes {
+    integrity?: string;
+    crossorigin?: string;
+    type?: "module";
+}
+export declare function readExternalScriptAttributes(el: Element): ExternalScriptAttributes;
+/** Deduplicate scripts without discarding a nested composition's integrity requirement. */
+export declare function ensureExternalScriptTag(doc: Document, src: string, attributes?: ExternalScriptAttributes): void;

package/dist/types/core/src/compiler/htmlBundler.d.ts

@@ -0,0 +1,74 @@
+export { FLATTENED_INNER_ROOT_STRIP_ATTRS } from "../runtime/flattenedRoot.js";
+import { type MediaDurationProber } from "./htmlCompiler.js";
+export type BundledHostCompositionIdentity = {
+    authoredCompositionId: string | null;
+    runtimeCompositionId: string | null;
+};
+export declare function assignBundledRuntimeCompositionIds(hosts: Element[], counts?: Map<string, number>): Map<Element, BundledHostCompositionIdentity>;
+export declare function prepareFlattenedInnerRoot(innerRoot: Element): Element;
+export declare function parsesAsScript(source: string): boolean;
+export interface BundleScriptProvenance {
+    input: string;
+    output: string;
+    sourceMap: string;
+    sourceURL?: string;
+}
+export interface BundleOptions {
+    /** Optional source mapping for inspection; does not alter bundled HTML. */
+    scriptProvenance?: (script: BundleScriptProvenance) => void;
+    /** Project-relative HTML entry to bundle. Defaults to `index.html`. */
+    entryFile?: string;
+    stampHfIds?: boolean;
+    /** Optional media duration prober (e.g., ffprobe). If omitted, media durations are not resolved. */
+    probeMediaDuration?: MediaDurationProber;
+    /**
+     * How to handle the HyperFrames runtime <script> tag. Default: `"inline"`.
+     *
+     * - `"inline"` — embed the runtime IIFE body directly into the bundle. Produces
+     *   genuinely self-contained HTML. Right for CLI render output, validate,
+     *   snapshot, and any "ship a single .html file" use case.
+     * - `"placeholder"` — emit `<script ... src=""></script>` so the caller can
+     *   substitute it with a real URL via string replace. Used by the dev studio
+     *   server and vite preview to point at a local runtime endpoint, which keeps
+     *   the runtime cacheable across hot-reloads instead of re-inlining ~150 KB
+     *   on every change.
+     *
+     * The `HYPERFRAME_RUNTIME_URL` env var, when set, takes precedence over both
+     * modes and emits `<script ... src="<URL>">` directly.
+     */
+    runtime?: "inline" | "placeholder";
+    /**
+     * Inline .cube LUTs referenced from data-color-grading. Default: true for
+     * self-contained renders/exports. Studio preview disables this so the editor
+     * keeps showing project asset paths instead of giant data URLs.
+     */
+    inlineColorGradingLuts?: boolean;
+    /**
+     * Inline fonts, raster images (img/href/poster/srcset/CSS url()) and color grading LUTs as data
+     * URLs, up to the per-asset size ceiling. Default: true, for a genuinely self-contained bundle. Set
+     * false when the caller serves the project's own files alongside the bundle (e.g. a same-origin
+     * asset route): assets then keep their authored relative URL, which the caller resolves.
+     * `inlineColorGradingLuts` narrows LUTs further; it cannot inline a LUT this option excluded.
+     */
+    inlineAssets?: boolean;
+    /** Preview only: tag each scene's host, styles and scripts (`data-hf-scene`) so one can be swapped. */
+    sceneParts?: boolean;
+    /** Warn when the compiled HTML breaks the HyperFrames contract (default true). */
+    staticGuard?: boolean;
+    onRead?: (filePath: string) => void;
+}
+export declare function bundleToSingleHtml(projectDir: string, options?: BundleOptions): Promise<string>;
+/**
+ * Compile-time counterpart of the runtime's injectCompositionCssVariables:
+ * every element declaring data-composition-variables gets a scoped stylesheet
+ * rule so var(--slug, literal) references resolve during body parse. The
+ * runtime injection remains define-if-absent, so it won't double-apply.
+ *
+ * `variablesByComp` (host-merged sub-composition values, keyed by runtime
+ * composition id) adds one rule per scope — the flattened inner root loses
+ * its data-composition-id, so the host selector is the only stable anchor.
+ * Exported for the producer's render compiler, which inlines sub-compositions
+ * through the shared module rather than this bundler.
+ * Returns whether a style element was appended.
+ */
+export declare function emitRootCompositionVariableStyles(document: Document, variablesByComp?: Record<string, Record<string, unknown>>, overrides?: Record<string, unknown>): boolean;

package/dist/types/core/src/compiler/htmlCompiler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Callback to probe media duration. If not provided, media duration resolution is skipped.
+ * Return duration in seconds, or 0 if unknown.
+ */
+export type MediaDurationProber = (src: string) => Promise<number>;
+/**
+ * Compile HTML with full duration resolution.
+ *
+ * 1. Static pass: compileTimingAttrs() adds data-end where data-duration exists
+ * 2. For unresolved video/audio (no data-duration): probe via probeMediaDuration, inject durations
+ * 3. For pre-resolved audio: clamp data-duration to playable source when needed.
+ *    Explicit video slots are preserved and hold their final frame.
+ *
+ * @param rawHtml - The raw HTML string
+ * @param projectDir - The project directory for resolving relative paths
+ * @param probeMediaDuration - Optional callback to probe media duration (e.g., via ffprobe)
+ */
+export declare function compileHtml(rawHtml: string, projectDir: string, probeMediaDuration?: MediaDurationProber): Promise<string>;

package/dist/types/core/src/compiler/htmlDocument.d.ts

@@ -0,0 +1,23 @@
+export declare const RUNTIME_BOOTSTRAP_ATTR = "data-hyperframes-preview-runtime";
+export declare function isFullHtmlDocument(html: string): boolean;
+/**
+ * Parse a full HTML document or wrap a fragment so linkedom consistently puts
+ * fragment content under document.body.
+ */
+export declare function parseHTMLContent(html: string): Document;
+export declare function stripEmbeddedRuntimeScripts(html: string): string;
+export declare function isRuntimeFileUrl(src: string | null | undefined): boolean;
+export declare function escapeInlineScriptSource(source: string): string;
+export declare function findStartTags(html: string, name: string): number[];
+export declare function hasCompositionOutsideTemplates(html: string): boolean;
+/** Insert markup before the document's own `</head>`, `</body>` or `</template>`; null if it has none. */
+export declare function insertBeforeCloseTag(html: string, name: "head" | "body" | "template", markup: string): string | null;
+export declare function insertRuntimeTag(html: string, tag: string): string;
+/**
+ * Insert raw tag markup at the very start of `<head>`, ahead of every author
+ * script (inline or external). Falls back to just before `<body>`, then to the
+ * top of the document, for fragments that carry neither.
+ */
+export declare function injectTagsAtHeadStart(html: string, tags: string): string;
+export declare function injectScriptsAtHeadStart(html: string, scripts: readonly string[]): string;
+export declare function injectScriptsIntoHtml(html: string, headScripts: readonly string[], bodyScripts: readonly string[], stripEmbeddedRuntime?: boolean): string;

package/dist/types/core/src/compiler/importMaps.d.ts

@@ -0,0 +1,18 @@
+/** The subset of an import map a composition can declare. */
+export interface ImportMap {
+    imports?: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+}
+/**
+ * Parses a mounted composition's import map, rebasing each address the way its `src`/`href`
+ * attributes are rebased. Returns null for a map the browser would reject too.
+ */
+export declare function parseImportMap(json: string, rebase: (url: string) => string): ImportMap | null;
+/**
+ * A page has one import map, and it must precede every module script. Mounted compositions'
+ * maps merge into the page's own (created at the top of <head> if absent); the first mapping
+ * of a specifier wins and a conflicting later one is dropped with a warning.
+ */
+export declare function mergeImportMapsIntoDocument(doc: Document, maps: ImportMap[]): void;
+/** Emits what inlineSubCompositions collected from mounted files' module and import-map scripts. */
+export declare function emitMountedModuleScripts(doc: Document, importMaps: ImportMap[], moduleScripts: string[]): void;

package/dist/types/core/src/compiler/inlineSubCompositions.d.ts

@@ -0,0 +1,151 @@
+import { type ExternalScriptAttributes } from "./externalScripts.js";
+import { type ImportMap } from "./importMaps.js";
+import { type CompositionStyle } from "./scriptRuns.js";
+/**
+ * Shared sub-composition inlining logic.
+ *
+ * Both the core bundler (preview) and the producer compiler (render) need to
+ * inline sub-composition HTML referenced via `data-composition-src`. This
+ * module is the single source of truth for that transformation, eliminating
+ * divergence that previously caused bugs (e.g. producer not setting
+ * `data-composition-file`).
+ */
+import { type AssetExists } from "./rewriteSubCompPaths.js";
+/** Marks each scene whose nodes a script outside it names by selector, id or class: a swap would strand it. */
+export declare function refuseSwapsReachedByRootScripts(document: Document, rootScripts: string[]): void;
+export interface InlineSubCompositionsOptions {
+    /**
+     * Resolve the HTML content for a sub-composition given its `data-composition-src` value.
+     * Return `null` when the file cannot be found.
+     */
+    resolveHtml: (srcPath: string) => string | null;
+    /**
+     * Parse an HTML string into a Document. The returned object must expose
+     * standard DOM APIs (querySelector, querySelectorAll, body, head, etc.).
+     * Both linkedom's `parseHTML(...).document` and the core bundler's
+     * `parseHTMLContent(...)` satisfy this contract.
+     */
+    parseHtml: (html: string) => Document;
+    /**
+     * Identity map produced by `assignBundledRuntimeCompositionIds`.
+     * When provided, authoredCompositionId and runtimeCompositionId are read
+     * from this map instead of from the host element's attributes directly.
+     * The bundler uses this; the producer can omit it.
+     */
+    hostIdentityMap?: Map<Element, {
+        authoredCompositionId: string | null;
+        runtimeCompositionId: string | null;
+    }>;
+    /**
+     * When true, rewrite `url(...)` references in inline `style` attributes
+     * on sub-composition elements. The bundler enables this; the producer
+     * can skip it.
+     */
+    rewriteInlineStyles?: boolean;
+    /**
+     * Prepare the inner root element before injecting it into the host.
+     * The bundler's `prepareFlattenedInnerRoot` clones the element, strips
+     * timing attributes, and adds `data-hf-inner-root`. When omitted, the
+     * inner root's outerHTML is injected as-is.
+     */
+    flattenInnerRoot?: (innerRoot: Element) => Element;
+    /**
+     * When true, CSS selectors targeting the authored root use a compound
+     * selector (`[scope][root]`) instead of a descendant (`[scope] [root]`).
+     * Enable this in the producer path where the inner root merges onto
+     * the host element via innerHTML — both attributes end up on the same
+     * element and a descendant selector won't match.
+     */
+    compoundAuthoredRoot?: boolean;
+    /**
+     * Read declared variable defaults from a sub-composition's `<html>` element.
+     * The bundler passes `readDeclaredDefaults`; the producer can omit this.
+     */
+    readVariableDefaults?: (docElement: Element) => Record<string, unknown>;
+    /**
+     * Parse host-level variable overrides from `data-variable-values`.
+     * The bundler passes `parseHostVariableValues`; the producer can omit this.
+     */
+    parseHostVariables?: (host: Element) => Record<string, unknown>;
+    /**
+     * Build a CSS attribute selector for scoping, e.g.
+     * `[data-composition-id="my-comp"]`. Defaults to a simple implementation
+     * when not provided. The bundler passes `cssAttributeSelector` which
+     * handles escaping.
+     */
+    buildScopeSelector?: (compId: string) => string;
+    /**
+     * Error label prefix used in wrapped composition scripts.
+     * Defaults to `"[HyperFrames] composition script error:"`.
+     */
+    scriptErrorLabel?: string;
+    /**
+     * Probe for "does this project-root-relative path exist?". Supplied by
+     * callers that can see the filesystem so a sub-composition's SIBLING asset
+     * refs (`<link href="_shared.css">` next to the composition) resolve against
+     * its own directory instead of 404ing at the project root. Omit it and plain
+     * relative paths pass through unchanged. See `AssetExists`.
+     */
+    assetExists?: AssetExists;
+    /**
+     * Log a warning when a composition file cannot be resolved. `reason` is a
+     * short, human-readable explanation (e.g. "the file is empty (0 bytes or
+     * whitespace-only)") from `checkSubCompositionUsability` — present for
+     * every skip except when `resolveHtml` returns `null` (file not found,
+     * which callers detect themselves before calling `resolveHtml`).
+     * Defaults to `console.warn`.
+     */
+    onMissingComposition?: (srcPath: string, reason?: string) => void;
+    /** Tag each top-level host with `data-hf-scene` and report every part's scene, for preview swaps. */
+    tagScenes?: boolean;
+}
+export interface ExternalLink {
+    href: string;
+    rel: string;
+    crossorigin?: string;
+    media?: string;
+    title?: string;
+    type?: string;
+    disabled?: true;
+}
+/** Appends a hoisted link unless the document already has a live one it would duplicate. */
+export declare function ensureExternalLinkTag(doc: Document, link: ExternalLink): void;
+export interface InlineSubCompositionsResult {
+    styles: CompositionStyle[];
+    /** With `tagScenes`: the scene each entry of `styles` belongs to. */
+    styleScenes: string[];
+    scripts: string[];
+    externalScriptSrcs: string[];
+    scriptItems: Array<{
+        kind: "inline";
+        content: string;
+        scene?: string;
+    } | ({
+        kind: "external";
+        src: string;
+        scene?: string;
+    } & ExternalScriptAttributes)>;
+    /** May list one link more than once; `ensureExternalLinkTag` dedupes. */
+    externalLinks: ExternalLink[];
+    variablesByComp: Record<string, Record<string, unknown>>;
+    /** Mounted files' import maps, addresses rebased; emit with `emitMountedModuleScripts`. */
+    importMaps: ImportMap[];
+    /** Mounted files' inline module scripts, each already carrying its scoped `__hyperframes`. */
+    moduleScripts: string[];
+}
+/**
+ * Inline sub-compositions into a document. For each host element in `hosts`:
+ *
+ * 1. Resolve the sub-composition HTML via `options.resolveHtml`
+ * 2. Parse it, resolve template, body, or bare-fragment content
+ * 3. Find the inner `[data-composition-id]` root
+ * 4. Extract `<style>` elements, scope CSS, collect them
+ * 5. Extract `<script>` elements, wrap inline scripts, collect them
+ * 6. Collect external script `src` URLs for deduplication
+ * 7. Rewrite asset paths (and optionally inline-style asset URLs)
+ * 8. Copy dimension attrs from inner root to host if missing
+ * 9. Set `data-composition-file` on host
+ * 10. Remove `data-composition-src` from host
+ * 11. Inject the content into the host element
+ */
+export declare function inlineSubCompositions(document: Document, hosts: Element[], options: InlineSubCompositionsOptions): InlineSubCompositionsResult;

package/dist/types/core/src/compiler/rewriteSubCompPaths.d.ts

@@ -0,0 +1 @@
+export { rewriteAssetPath, rewriteAssetPaths, rewriteInlineStyleAssetUrls, rewriteCssAssetUrls, type AssetExists, } from "@hyperframes/parsers/asset-paths";

package/dist/types/core/src/compiler/scriptRuns.d.ts

@@ -0,0 +1,31 @@
+export interface InlineScriptRun {
+    members: Element[];
+    /** First later script that executes on its own; the merged run must stay before it. Null: end of body. */
+    anchor: Element | null;
+}
+/** Groups body scripts into runs of classic inline scripts split by any script that executes
+ * separately (src, module, or one the caller pins in place), so merging a run never reorders it past one. */
+export declare function inlineScriptRuns(scripts: readonly Element[], isPinned?: (el: Element) => boolean): InlineScriptRun[];
+export declare const AFTER_FONTS_SCRIPT_TYPE = "text/hf-after-fonts";
+export declare const AFTER_FONTS_SCRIPTS = "script[type=\"text/hf-after-fonts\"], script[type=\"text/hf-after-fonts+module\"]";
+export declare const AFTER_FONTS_CLAIM = "__hfAfterFontsClaimed";
+export declare const INLINED_FILE_ATTR = "data-hf-inlined-src";
+export declare const COMPOSITION_SOURCE_URL = "hyperframes-composition://body";
+export declare const DEFERRED_FILE = "[defer][src], [defer][data-hf-inlined-src]";
+/** Gives each body script a type the browser does not run, so the runtime can run it once web fonts are ready. */
+export declare function deferScriptsUntilFonts(document: Document, isFramework?: (el: Element) => boolean): void;
+export declare function typeAfterFonts(el: Element): string | null;
+/** Undefined for a type the browser never applies as CSS; `media="all"` and an empty title count as none. */
+export declare function cssStyleMergeKey(el: Element): string | undefined;
+export declare const UNCONDITIONAL_CSS_KEY: string;
+export declare function hasSameLink(scope: ParentNode, link: Element): boolean;
+/** Groups head styles into runs of adjacent styles with one merge key, so merging a run never reorders rules. */
+export declare function headStyleRuns(styles: readonly Element[], isPinned?: (el: Element) => boolean): Element[][];
+export interface CompositionStyle {
+    css: string;
+    media: string | null;
+    title: string | null;
+}
+export declare function compositionStyle(el: Element, css: string): CompositionStyle;
+/** One `<style>` per adjacent run of same-condition sheets, keeping each run's media and title. */
+export declare function styleElementsFor(document: Document, sheets: readonly CompositionStyle[], join: (css: string[]) => string): Element[];

package/dist/types/core/src/compiler/selectorIdTokens.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared low-level scanner: walk a CSS selector and replace whole-token
+ * `#id` occurrences that sit outside quotes and attribute-selector brackets.
+ *
+ * Extracted from `compositionScoping.ts`'s authored-root-id rewrite (the
+ * original, single-id version of this scan) so `svgIdNamespacing.ts` can
+ * reuse the exact same quote/bracket-tracking logic for its many-id rewrite
+ * instead of a second, drifting copy of the same state machine.
+ *
+ * Split into two small passes rather than one branch-heavy loop: first mark
+ * which offsets are outside a quoted string or an attribute-selector
+ * bracket (`markUnguardedOffsets`), then walk the selector once more,
+ * consulting that mask, to actually splice in replacements
+ * (`replaceSelectorIdTokens`). Each pass stays simple enough to read at a
+ * glance instead of one function juggling both jobs.
+ *
+ * The `#id` token is read as a CSS identifier per CSS Syntax Level 3
+ * (`decodeCssIdentifierAt`): `\.`-style and `\HEX `-style escapes are
+ * decoded before the id is compared against the candidate list, so a
+ * stylesheet spelling `#fx\.1` matches the element whose raw `id` attribute
+ * is `fx.1`. Callers emit replacement selectors through
+ * `escapeCssIdentifier`, the inverse operation.
+ */
+/**
+ * Read one CSS identifier starting at `start` and return its decoded value
+ * plus the offset just past it, or `null` when no identifier starts there.
+ * Follows the "consume an ident sequence" algorithm of CSS Syntax Level 3.
+ */
+export declare function decodeCssIdentifierAt(text: string, start: number): {
+    value: string;
+    end: number;
+} | null;
+/**
+ * Serialize `value` as a CSS identifier — the `CSS.escape()` algorithm from
+ * CSSOM, implemented here because Node has no `CSS` global. Every output is
+ * a valid `#ident` selector body that `decodeCssIdentifierAt` round-trips
+ * back to `value`.
+ */
+export declare function escapeCssIdentifier(value: string): string;
+/**
+ * Replace every whole-token `#id` in `selector` whose DECODED identifier is
+ * in `candidateIds`, skipping occurrences inside a quoted string or an
+ * attribute-selector bracket.
+ *
+ * Because the whole identifier is consumed before comparing, `#clip2` is
+ * never mistaken for `#clip`, and `#fx\.1` matches the candidate `fx.1`.
+ * `resolveReplacement` receives the matched (decoded) id and returns the
+ * full replacement text (including its own leading `#`, if any) to splice
+ * in.
+ */
+export declare function replaceSelectorIdTokens(selector: string, candidateIds: readonly string[], resolveReplacement: (matchedId: string) => string): string;
+export declare function escapeCssAttributeValue(value: string): string;
+type AttributeNamespace = {
+    kind: "any";
+} | {
+    kind: "none";
+} | {
+    kind: "named";
+    prefix: string;
+};
+export declare function parseAttributeSelector(predicate: string): {
+    name: string;
+    rawName: string;
+    namespace: AttributeNamespace;
+    operator: "=" | "~=" | "|=" | "^=" | "$=" | "*=";
+    value: string;
+    flag: string | undefined;
+} | null;
+export declare function replaceSelectorAttributeTokens(selector: string, rewrite: (predicate: string) => string): string;
+export {};

package/dist/types/core/src/compiler/standaloneEntry.d.ts

@@ -0,0 +1,2 @@
+export declare function isTemplateEntry(html: string): boolean;
+export declare function extractStandaloneEntryFromIndex(indexHtml: string, entryFile: string, entryHtml?: string): string | null;

package/dist/types/core/src/compiler/staticGuard.d.ts

@@ -0,0 +1,7 @@
+export type HyperframeStaticFailureReason = "missing_composition_id" | "missing_composition_dimensions" | "missing_timeline_registry" | "invalid_script_syntax" | "invalid_static_hyperframe_contract";
+export type HyperframeStaticGuardResult = {
+    isValid: boolean;
+    missingKeys: string[];
+    failureReason: HyperframeStaticFailureReason | null;
+};
+export declare function validateHyperframeHtmlContract(html: string): Promise<HyperframeStaticGuardResult>;