@hyperframes/inspector 0.0.0-stage → 0.8.152

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

@@ -0,0 +1,80 @@
+/**
+ * Native SVG url()/href references resolve by document order, bypassing JS scoping.
+ * Rename only colliding, natively referenced SVG ids; leave JS-only ids reachable
+ * by libraries that bypass the scoped selector shim. The first unrenamable element
+ * keeps the authored id (otherwise the first element does). Renamed elements retain
+ * data-hf-authored-id for script lookup compatibility.
+ */
+import { type SvgReferenceAlias } from "./svgSelectorAliases.js";
+/** Reused from `compositionScoping.ts`'s `AUTHORED_ROOT_ID_ATTR` in spirit —
+ *  same purpose (let a renamed id still resolve by its authored name), now
+ *  generalized from "the composition root" to any renamed descendant. */
+export declare const SVG_AUTHORED_ID_ATTR = "data-hf-authored-id";
+/** Structural shape both a linkedom/live-DOM `Element` and `Document`
+ *  satisfy — mirrors the narrow-interface pattern `mediaRenderIds.ts` and
+ *  `compositionAssembly.ts` already use so this module works unmodified
+ *  across the preview bundler and the render compiler. */
+interface SvgIdQueryable {
+    querySelectorAll(selector: string): Iterable<Element>;
+}
+/** One inlined composition instance, as seen in the ASSEMBLED document. */
+export interface SvgIdScope {
+    /** The element whose subtree holds this instance's content (the host). */
+    root: Element;
+    /**
+     * Document-unique prefix for ids renamed in this scope — the instance's
+     * runtime composition id. An empty namespace freezes IDs while still repairing references:
+     * an anonymous host has no identity to prefix with, the same guard
+     * `scopeCssToComposition` and `wrapScopedCompositionScript` apply.
+     */
+    namespace: string;
+    /** Root document references follow document order; instances prefer local definitions. */
+    referenceTarget?: "document";
+    /**
+     * Nested composition hosts inside `root` whose content belongs to their
+     * OWN scope. Their subtrees are skipped both when collecting this scope's
+     * ids and when rewriting its references.
+     */
+    exclude?: readonly Element[];
+    /**
+     * This instance's extracted `<style>` text (already removed from the DOM
+     * by the inline pipeline). Scanned for `url(#id)` references so a filter
+     * that is only applied from a stylesheet still counts as natively
+     * referenced. The caller rewrites these strings afterwards via
+     * `rewriteSvgIdReferencesInCss` with the returned map.
+     */
+    cssTexts?: readonly string[];
+}
+/**
+ * Rename every colliding, natively-referenced SVG id across the inlined
+ * composition instances in `scopes` and rewrite each instance's attribute
+ * references (`href`/`xlink:href`, any `url(#id)` funcref — including inside
+ * a `style` attribute) to match.
+ *
+ * Returns one old-id -> new-id map per scope, in the same order, so the
+ * caller can apply the identical substitution to that instance's separately
+ * extracted `<style>` text via `rewriteSvgIdReferencesInCss`, which this
+ * function never sees. Maps include inherited references whose original target
+ * was renamed elsewhere; scopes with local definitions keep their own mapping.
+ *
+ * `document` must be the ASSEMBLED document every scope root lives in: the
+ * collision census covers the whole thing, including ids the top-level
+ * document declares itself, since those collide with an inlined instance's
+ * ids just as two instances collide with each other.
+ */
+export declare function namespaceCollidingSvgIds(document: SvgIdQueryable, scopes: readonly SvgIdScope[], finalizedIds?: Set<Element>): Map<string, string>[];
+/**
+ * Apply the same id substitution `namespaceCollidingSvgIds` computed to a
+ * composition's `<style>` text.
+ *
+ * `<style>` content is extracted from the DOM and carried around as a raw
+ * string by the inline pipeline (see `inlineSubCompositions`'s
+ * `scopeSubStyle`), so it is never visited by the attribute walk. Both a bare
+ * `#id` selector (`#clip rect { fill: red }`, already scoped to the right
+ * instance by #556's composition-box prefix, but still naming the PRE-rename
+ * id) and a `url(#id)` declaration value need rewriting here, or a
+ * same-composition stylesheet rule silently stops matching the element whose
+ * id this module just changed.
+ */
+export declare function rewriteSvgIdReferencesInCss(css: string, idMap: ReadonlyMap<string, string>, references?: readonly SvgReferenceAlias[]): string;
+export {};

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

@@ -0,0 +1,30 @@
+export declare const SVG_REFERENCE_ALIASES_ATTR = "data-hf-svg-reference-aliases";
+export interface SvgReferenceAlias {
+    name: string;
+    localName: string;
+    namespaceURI: string | null;
+    before: string;
+    after: string;
+}
+interface IdSelectorAlias {
+    id: string;
+    replacement: string;
+}
+/**
+ * With `namespaces` (a live sheet's bindings) only prefixed attribute selectors are
+ * rewritten; without it they stay as authored and everything else is rewritten.
+ */
+export declare function rewriteSvgSelectors(selector: string, ids: readonly IdSelectorAlias[], references: readonly SvgReferenceAlias[], namespaces?: ReadonlyMap<string, string | null>): string;
+/** Metadata records actual writes; selectors still match current native attribute values. */
+export declare function readSvgReferenceAliases(root: {
+    querySelectorAll(selector: string): Iterable<Element>;
+    getAttribute?: (name: string) => string | null;
+}, attribute: string, includeDescendants?: boolean): SvgReferenceAlias[];
+export interface SvgSelectorAliases {
+    refresh(): void;
+    rewrite(selector: string, additional?: readonly IdSelectorAlias[]): string;
+}
+export declare function refreshSvgSelectorAliases(): void;
+/** Compiled scene scripts install once; refreshes stay with the runtime's lifecycle. */
+export declare function ensureSvgSelectorAliases(): void;
+export {};

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

@@ -0,0 +1,89 @@
+/**
+ * Timing Compiler
+ *
+ * Shared, pure HTML compilation that normalizes timing attributes.
+ * Works in both Node.js and browser without a DOM.
+ *
+ * Guarantees every timed element gets:
+ * - id on media elements when missing
+ * - data-end (computed from data-start + data-duration when possible)
+ * - data-has-audio on <video> elements (false for muted visual-only videos)
+ *
+ * For elements without data-duration (e.g. videos relying on source duration),
+ * this compiler identifies them as "unresolved" so the caller can provide
+ * durations via an environment-specific resolver (ffprobe, el.duration, etc.)
+ * and call injectDurations() to complete the compilation.
+ *
+ * Relative `data-start` (`intro`, `intro + 0.5`) is not numeric — leave
+ * `data-end` off so extract can resolve the id-ref later.
+ */
+import type { RateSpec } from "../speedRamp.js";
+export interface UnresolvedElement {
+    id: string;
+    tagName: string;
+    src?: string;
+    start: number;
+    end?: number;
+    duration?: number;
+    mediaStart: number;
+    playbackRate: RateSpec;
+    compositionSrc?: string;
+}
+export interface ResolvedDuration {
+    id: string;
+    duration: number;
+}
+export interface ResolvedMediaElement {
+    id: string;
+    tagName: string;
+    src?: string;
+    start: number;
+    duration: number;
+    mediaStart: number;
+    playbackRate: RateSpec;
+    loop: boolean;
+}
+export interface CompilationResult {
+    html: string;
+    unresolved: UnresolvedElement[];
+}
+export declare const MEDIA_DURATION_CLAMP_EPSILON_SECONDS = 0.05;
+export declare function shouldClampMediaDuration(declaredDuration: number, maxDuration: number): boolean;
+/**
+ * Whether compilation should shorten an authored media slot to its source.
+ *
+ * Non-looping video intentionally keeps an explicit longer slot: browsers and
+ * the render frame injector hold its final frame until that authored slot ends.
+ * Audio has no frame to hold, so its slot remains bounded by playable source.
+ */
+export declare function shouldClampResolvedMediaDuration(tagName: ResolvedMediaElement["tagName"], declaredDuration: number, maxDuration: number): boolean;
+/**
+ * Compile timing attributes in HTML.
+ *
+ * Phase 1 (static): Adds data-end where data-duration exists,
+ * adds data-has-audio on videos.
+ *
+ * Returns the compiled HTML and a list of elements that could not be
+ * resolved statically (missing data-duration). The caller should resolve
+ * these via ffprobe / el.duration and call injectDurations().
+ */
+export declare function compileTimingAttrs(html: string): CompilationResult;
+/**
+ * Inject resolved durations into compiled HTML.
+ *
+ * For each resolved element, adds data-duration and data-end attributes.
+ * Call this after resolving durations via ffprobe, el.duration, or
+ * GSAP timeline queries.
+ */
+export declare function injectDurations(html: string, resolutions: ResolvedDuration[]): string;
+/**
+ * Extract video/audio elements that already have data-duration set.
+ * Used by callers to validate declared durations against actual source durations.
+ */
+export declare function extractResolvedMedia(html: string): ResolvedMediaElement[];
+/**
+ * Clamp existing data-duration and data-end on media elements.
+ * For each resolution, replaces the declared duration with the clamped value
+ * and recomputes data-end accordingly.
+ */
+export declare function clampDurations(html: string, clamps: ResolvedDuration[]): string;

package/dist/types/core/src/generated/runtime-inline.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the pre-built hyperframe runtime IIFE as a string constant.
+ * This is the production-safe path: no esbuild, no file I/O,
+ * no import.meta.url arithmetic.
+ */
+export declare function getHyperframeRuntimeScript(): string;

package/dist/types/core/src/generated/svg-selector-aliases-inline.d.ts

@@ -0,0 +1,2 @@
+/** Returns the pre-built SVG selector alias installer IIFE as a string constant. */
+export declare function getSvgSelectorAliasesScript(): string;

package/dist/types/core/src/inline-scripts/pickerApi.d.ts

@@ -0,0 +1,32 @@
+export type HyperframePickerBoundingBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type HyperframePickerElementInfo = {
+    id: string | null;
+    tagName: string;
+    selector: string;
+    label: string;
+    boundingBox: HyperframePickerBoundingBox;
+    textContent: string | null;
+    src: string | null;
+    dataAttributes: Record<string, string>;
+};
+export type HyperframePickerApi = {
+    enable: () => void;
+    disable: () => void;
+    isActive: () => boolean;
+    getHovered: () => HyperframePickerElementInfo | null;
+    getSelected: () => HyperframePickerElementInfo | null;
+    getCandidatesAtPoint: (clientX: number, clientY: number, limit?: number) => HyperframePickerElementInfo[];
+    pickAtPoint: (clientX: number, clientY: number, index?: number) => HyperframePickerElementInfo | null;
+    pickManyAtPoint: (clientX: number, clientY: number, indexes?: number[]) => HyperframePickerElementInfo[];
+    describe?: (element: Element) => HyperframePickerElementInfo | null;
+};
+declare global {
+    interface Window {
+        __HF_PICKER_API?: HyperframePickerApi;
+    }
+}

package/dist/types/core/src/inline-scripts/runtimeContract.d.ts

@@ -0,0 +1,13 @@
+export declare const HYPERFRAME_RUNTIME_GLOBALS: {
+    readonly player: "__player";
+    readonly playerReady: "__playerReady";
+    readonly renderReady: "__renderReady";
+    readonly timelines: "__timelines";
+    readonly clipManifest: "__clipManifest";
+};
+export declare const HYPERFRAME_BRIDGE_SOURCES: {
+    readonly parent: "hf-parent";
+    readonly preview: "hf-preview";
+};
+export declare const HYPERFRAME_CONTROL_ACTIONS: readonly ["play", "pause", "seek", "set-muted", "set-playback-rate", "set-color-grading", "set-color-grading-compare", "enable-pick-mode", "disable-pick-mode"];
+export type HyperframeControlAction = (typeof HYPERFRAME_CONTROL_ACTIONS)[number];

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

@@ -0,0 +1,41 @@
+export declare const MEDIA_START_BASIS_ATTR = "data-hf-media-start-basis";
+export type MediaStartBasis = "local" | "global";
+export declare function readMediaStartBasis(value: string | null | undefined): MediaStartBasis;
+/** Resolve authored media time onto the root timeline. Nested media is local
+ * by default; only an explicit compatibility marker preserves a legacy
+ * root-global value. */
+export declare function resolveAbsoluteMediaStartSeconds(input: {
+    authoredStart: number;
+    hostStart: number;
+    basis?: string | null;
+}): number;
+/** The one rule for a media element's root-timeline start; the runtime and the CLI both call it.
+ * `hostStart` is the composition's origin. With no literal start, an auto-injected start, or an
+ * origin at 0 there is nothing for the basis to disambiguate, so ordinary resolution applies. */
+export declare function resolveMediaStartSeconds(input: MediaStartInput & {
+    ordinaryStart: () => number;
+}): number;
+/** True when the authored start is already root time, so no host offset applies. */
+export declare function isRootGlobalMediaStart(input: MediaStartInput): boolean;
+export interface MediaStartInput {
+    authoredStart: number | null;
+    hostStart: number;
+    hasAutoStart: boolean;
+    basis?: string | null;
+}
+/** A composition host's in-point; only a host with one shifts or cuts what it holds. */
+export declare function hostInPointSeconds(host: Pick<Element, "getAttribute">): number;
+/** Main-timeline time of a sub-composition's local t=0: its host's start minus its in-point. */
+export declare function compositionOriginSeconds(hostStart: number, host: Pick<Element, "getAttribute">): number;
+export interface HostSlot {
+    start: number;
+    end: number;
+}
+/** Each in-point host cuts the span to its own window. */
+export declare function cutToHostSlots(span: {
+    start: number;
+    end: number;
+}, hosts: readonly HostSlot[]): {
+    start: number;
+    end: number;
+};

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

@@ -0,0 +1 @@
+export { MIN_PLAYBACK_RATE, MAX_PLAYBACK_RATE } from "@hyperframes/parsers/media-duration";

package/dist/types/core/src/runtime/analytics.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime analytics — vendor-agnostic event emission via postMessage.
+ *
+ * The host application decides what to do with events: forward to PostHog,
+ * Mixpanel, Amplitude, a custom logger, or nothing at all.
+ */
+export type RuntimeAnalyticsEvent = "composition_loaded" | "composition_played" | "composition_paused" | "composition_seeked" | "composition_ended" | "element_picked" | "position_edit_fold_skipped" | "timeline_missing_pause" | "auto_marker_install_failed" | "custom_ease_install_failed" | "custom_ease_parse_failed" | "keyframe_ease_repair_failed";
+export type RuntimeAnalyticsProperties = Record<string, string | number | boolean | null>;
+/**
+ * Wire the analytics + performance bridge to the runtime's postMessage transport.
+ * Called once during runtime bootstrap from `init.ts`.
+ */
+export declare function initRuntimeAnalytics(postMessage: (payload: unknown) => void): void;
+/**
+ * Emit an analytics event through the bridge.
+ * The host app receives it via postMessage and forwards to its analytics provider.
+ */
+export declare function emitAnalyticsEvent(event: RuntimeAnalyticsEvent, properties?: RuntimeAnalyticsProperties): void;

package/dist/types/core/src/runtime/applyVariableBindings.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Declarative variable bindings — the no-script consumption channel for
+ * composition variables (values are fixed for the page's lifetime, so this is
+ * seek-safe and deterministic):
+ *
+ * - `data-var-src="id"` — sets the element's `src` from the variable value
+ *   (a URL string or an image value `{url}`). Only allowed on media elements
+ *   (img/video/audio/source) and only for safe URL protocols — a src on a
+ *   script-executing tag or a `javascript:`/`data:text/html` value is refused.
+ *   The authored src stays as the fallback when the variable resolves to nothing.
+ * - `data-var-text="id"` — sets the element's OWN text from a scalar variable
+ *   value. Elements with element children keep them: only the direct text
+ *   node is replaced, mirroring the SDK's setOwnText semantics — a text
+ *   binding must never delete nested clips or animation targets.
+ * - Every scalar variable (and a font value's family name) is applied as a
+ *   `--{id}` CSS custom property on its composition root, so CSS bindings
+ *   like `color: var(--accent)` respond to render/preview overrides instead
+ *   of only the persisted default.
+ *
+ * Values resolve against the element's owning composition — the same scope
+ * chain the color-grading runtime uses: `__hfVariablesByComp[compId]` for
+ * inlined sub-compositions, then the top-level merged `getVariables()`.
+ *
+ * Applied at init AND re-applied after the composition loader inlines
+ * external / template sub-compositions (their DOM and per-instance scoped
+ * values don't exist at init). Idempotent: re-applying writes the same
+ * values.
+ */
+/**
+ * Strip characters that could smuggle additional declarations or markup out of
+ * a var() substitution site. A scalar value folded into `background: var(--x)`
+ * or `background-image: url(var(--x))` must not be able to close the declaration
+ * and inject a new one (`red; background: url(//evil?data=…)`) — none of these
+ * characters is legal in a scalar variable value (string, number, color, font
+ * family), so removing them is lossless for real inputs and neutralizes the
+ * declaration/URL-exfiltration channel.
+ *
+ * Exported because the static compiler bakes the same scalars into a stylesheet
+ * at build time and has to reach the same result: a value that the runtime
+ * strips but a compile-time emit passes through would make the rendered MP4
+ * differ from the preview, which is the more dangerous of the two directions.
+ */
+export declare function sanitizeCssValue(value: string): string;
+/** The src an element loads, preview proxy aside: its bound variable's value, else its attribute. */
+export declare function unproxiedMediaSrc(el: Element): string | null;
+/** Applies the bindings in `doc`, or only those inside `within` and `within` itself. */
+export declare function applyVariableBindings(doc: Document, within?: Element): void;

package/dist/types/core/src/runtime/audioAutomationVolume.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The volume lane's gain for an element at a moment in its clip.
+ *
+ * Volume is not scheduled onto the gain AudioParam the way FX parameters are.
+ * The runtime rewrites that gain every tick from `data-volume` and the GSAP
+ * seeked value, which would erase a scheduled envelope within a frame — so the
+ * lane feeds the same per-tick path the probed `volumeKeyframes` already use,
+ * and the render still bakes it into the samples.
+ */
+import { type HfAutomationLane } from "../audioAutomation.js";
+/** The lane for `target` inside a `data-automation` value, or null when absent or unreadable. */
+export declare function laneFromAttr(raw: string, target?: string): HfAutomationLane | null;
+/**
+ * Gain the lane asks for at `relTime` clip-local seconds, or null when the
+ * element has no volume lane and the caller should fall back to its own rules.
+ */
+export declare function elementVolumeLaneGain(el: {
+    getAttribute?(name: string): string | null;
+}, relTime: number): number | null;

package/dist/types/core/src/runtime/authoredTiming.d.ts

@@ -0,0 +1,16 @@
+export type AuthoredTimingValue = string | number | null | undefined;
+export declare const AUTHORED_DURATION_ATTR = "data-hf-authored-duration";
+export declare const AUTHORED_END_ATTR = "data-hf-authored-end";
+export interface RawAuthoredTiming {
+    start?: AuthoredTimingValue;
+    duration?: AuthoredTimingValue;
+    authoredDuration?: AuthoredTimingValue;
+    end?: AuthoredTimingValue;
+    authoredEnd?: AuthoredTimingValue;
+}
+export interface AuthoredTimingWindow {
+    start: number;
+    duration: number | null;
+    end: number | null;
+}
+export declare function resolveAuthoredTimingWindow(values: RawAuthoredTiming): AuthoredTimingWindow | null;

package/dist/types/core/src/runtime/compositionDimension.d.ts

@@ -0,0 +1,5 @@
+/** A `data-width`/`data-height` length in CSS px as the stage lays it out, fractions kept. */
+export declare function parseLayoutDimension(value: string | null | undefined): number | null;
+/** The size the runtime reports to its host: whole px, read with `parseInt` as the renderer does. */
+export declare function parseCompositionDimension(value: string | null | undefined): number | null;
+export declare function findRootCompositionElement(doc?: ParentNode): HTMLElement | null;

package/dist/types/core/src/runtime/diagnostics.d.ts

@@ -0,0 +1,3 @@
+/** The named error readiness waits fail with once start-up or the render-ready publish throws; it stays set. */
+export declare function recordStartupError(error: unknown): void;
+export declare function swallow(label: string, error?: unknown): void;

package/dist/types/core/src/runtime/domRealm.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Realm-independent "what kind of node is this" tests for composition DOM.
+ *
+ * THE INVARIANT: the runtime never assumes the composition DOM was built by the
+ * same JavaScript realm the runtime is running in. It asks what a node IS (node
+ * type, namespace, tag name), never which window's constructor made it.
+ *
+ * Why that matters. `node instanceof HTMLElement` compares against the
+ * `HTMLElement` of the realm this module was loaded into, so it answers "which
+ * window built this node", not "what is this node". One document can hold
+ * elements from several realms at once, and a node keeps the prototype chain of
+ * whichever realm created it however it got there.
+ *
+ * MEASURED, in the Studio preview, on some loads: `<html>`, `<head>` and
+ * `<script>` carry the preview frame's prototypes while `<body>` and every
+ * element under it carry the editor window's. Tagging each realm's
+ * `Element.prototype` before any page script ran and reading the tag back off
+ * the live nodes is how that was established. NOT established: how the nodes
+ * come to be there. No `adoptNode`, `importNode` or `document.write` call was
+ * caught doing it, and the frame is populated by `src`/`srcdoc`, so treat the
+ * mechanism as an open question and the mixed realms as a fact.
+ *
+ * Either way `instanceof` does not throw and does not warn. It just returns
+ * false, forever, for every element in the composition, and every guard written
+ * as `if (!(node instanceof HTMLElement)) continue;` silently skips the whole
+ * document. A whole pass goes dark with no error: the timed-element visibility
+ * pass stops writing, so every scene paints on top of every other.
+ *
+ * `doc.defaultView.HTMLElement` is not a sufficient repair, which is why this
+ * module replaced two hand-rolled attempts at it. It fixes the case where the
+ * nodes belong to the document's own realm and still fails when they belong to
+ * a third one. A structural test has no such case to get wrong.
+ *
+ * Scope of ownership: these predicates own the RUNTIME's answer to "what kind of
+ * node is this", for HTML and SVG, which is everything a composition contains.
+ * `packages/studio` still hand-rolls its own checks in several places and is not
+ * covered by this module or by the lint guard that keeps `src/runtime` clean
+ * (`scripts/lint-runtime-preview-guards.ts`).
+ */
+/** Any element node, from any realm (HTML, SVG, MathML). Mirrors `instanceof Element`. */
+export declare function isElementNode(value: unknown): value is Element;
+/**
+ * An HTML element, from any realm. Mirrors `instanceof HTMLElement`, including
+ * its exclusion of SVG/MathML: "is an HTMLElement" and "is an element in the
+ * XHTML namespace" are the same set.
+ */
+export declare function isHtmlElement(value: unknown): value is HTMLElement;
+/** `<video>`, from any realm. Mirrors `instanceof HTMLVideoElement`. */
+export declare function isVideoElement(value: unknown): value is HTMLVideoElement;
+/** `<audio>`, from any realm. Mirrors `instanceof HTMLAudioElement`. */
+export declare function isAudioElement(value: unknown): value is HTMLAudioElement;
+/** `<video>` or `<audio>`, from any realm. Mirrors `instanceof HTMLMediaElement`. */
+export declare function isMediaElement(value: unknown): value is HTMLMediaElement;
+/** `<img>`, from any realm. Mirrors `instanceof HTMLImageElement`. */
+export declare function isImageElement(value: unknown): value is HTMLImageElement;
+/** `<canvas>`, from any realm. Mirrors `instanceof HTMLCanvasElement`. */
+export declare function isCanvasElement(value: unknown): value is HTMLCanvasElement;
+/** `<style>`, from any realm. Mirrors `instanceof HTMLStyleElement`. */
+export declare function isStyleElement(value: unknown): value is HTMLStyleElement;
+/** `<link>`, from any realm. Mirrors `instanceof HTMLLinkElement`. */
+export declare function isLinkElement(value: unknown): value is HTMLLinkElement;
+/**
+ * An element that carries a CSS `style` map: HTML **or** SVG. Position edits and
+ * transform writes apply to both (authored SVG `<text>`/shapes honour the CSS
+ * `translate` longhand exactly as HTML does).
+ */
+export declare function isStylableElement(value: unknown): value is HTMLElement | SVGElement;

package/dist/types/core/src/runtime/flattenedRoot.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared between the build-time bundler (htmlBundler) and the runtime
+ * composition loader: when a sub-composition's inner root is flattened into
+ * its host, these timing/identity attributes must be stripped and the
+ * authored id preserved as data — identical semantics in both worlds.
+ */
+export declare const FLATTENED_INNER_ROOT_STRIP_ATTRS: string[];
+/** Strip timing attrs, demote the authored id, and mark the flattened root. */
+export declare function markFlattenedInnerRoot(prepared: Element): void;

package/dist/types/core/src/runtime/getVariables.d.ts

@@ -0,0 +1,42 @@
+export declare function getVariables<T extends Record<string, unknown> = Record<string, unknown>>(): Partial<T>;
+export declare function warnUnknownEnumValues(declarer: Element | null | undefined, resolved: Record<string, unknown>, compositionId?: string): void;
+/** Test-only: clear the per-page dedupe set. */
+export declare function resetUnknownEnumWarnings(): void;
+/**
+ * Extract `{id: default}` map from an element's `data-composition-variables`
+ * attribute. Returns an empty object when the attribute is missing, the JSON
+ * is unparseable, or the payload isn't an array. Exported so the
+ * compositionLoader can compute the same defaults map for sub-comp instances.
+ */
+export declare function readDeclaredDefaults(root: Element | null): Record<string, unknown>;
+/**
+ * Define primitive-valued variables as CSS custom properties on `target`,
+ * recording the applied names so re-init/unmount can clear them. Empty
+ * strings are skipped — CSSOM setProperty("", …) REMOVES the property, and a
+ * blank default has no CSS meaning anyway.
+ */
+export declare function applyCssVariables(target: Element, variables: Record<string, unknown>): void;
+/** Keep only variables whose CSS custom property is not already defined. */
+export declare function filterVariablesIfAbsent(target: Element, variables: Record<string, unknown>, view: Window | null): Record<string, unknown>;
+/** Remove custom properties a previous applyCssVariables call defined. */
+export declare function clearAppliedCssVariables(target: Element): void;
+/**
+ * Imported figma components reference brand tokens as `var(--slug, literal)`.
+ * Define each declaring element's composition variables as CSS custom
+ * properties ON THAT ELEMENT — scoping by the cascade, so two compositions
+ * on one page can't clobber each other and a flattened sub-composition root
+ * correctly styles only its own subtree.
+ *
+ * Declared DEFAULTS are define-if-absent: a value the author already styled
+ * (stylesheet `:root` rule, compile-time emission, hand-written inline) wins
+ * over the declared default, preserving pre-existing conventions where a
+ * variable id coincides with an authored custom property. Render-time
+ * overrides (`--variables` → `window.__hfVariables`) always win — that's
+ * explicit user intent.
+ */
+export declare function injectCompositionCssVariables(doc: Document): void;
+/** Parse a host element's `data-variable-values` JSON attribute (per-instance
+ * sub-composition overrides). Shared by the runtime loader and the bundler. */
+export declare function parseHostVariableValues(host: Element): Record<string, unknown>;
+/** Render-time variable overrides (`hyperframes render --variables`). */
+export declare function readRenderOverrides(): Record<string, unknown>;

package/dist/types/core/src/runtime/globals.d.ts

@@ -0,0 +1,11 @@
+export interface HFDebugSurface {
+    __hfDebug?: boolean;
+    __HYPERFRAMES_DEBUG?: boolean;
+    __hf?: {
+        onSwallowed?: (event: {
+            label: string;
+            error: unknown;
+        }) => void;
+    };
+}
+export declare function getDebugSurface(): HFDebugSurface;

package/dist/types/core/src/runtime/inspectionTypes.d.ts

@@ -0,0 +1,68 @@
+export type Target = {
+    selector: string;
+    within?: string;
+} | {
+    hfId: string;
+    within?: string;
+} | {
+    ref: string;
+};
+export interface InspectRequest {
+    targets: Target[];
+    descendants?: boolean;
+    maxBytes?: number;
+    time?: number;
+    snippets?: string[];
+    offset?: number;
+    generation?: string;
+    debug?: boolean;
+}
+export interface ElementRef {
+    ref: string;
+    tag: string;
+    id: string;
+    hfId: string | null;
+    classes: string[];
+    composition: string | null;
+}
+export interface RuntimeAnimation {
+    stack: string | null;
+    properties: string[];
+    targets: ElementRef[];
+    localStart: number;
+    duration: number;
+    attachmentStacks: string[];
+}
+export interface RuntimeResult {
+    target: Target;
+    status: "found" | "missing" | "ambiguous" | "stale-ref" | "invalid-selector";
+    candidates: ElementRef[];
+    animations: RuntimeAnimation[];
+    elements: ElementRef[];
+    css: string[];
+    truncated: boolean;
+}
+export interface RuntimeQuery {
+    targets: Target[];
+    descendants: boolean;
+    cssRules: {
+        id: string;
+        selector: string;
+    }[];
+}
+export interface RuntimeResponse {
+    results: RuntimeResult[];
+    recorded: number;
+    recordLimitReached: boolean;
+    hooked: boolean;
+}
+export interface Snippet {
+    id: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    kind: string[];
+    targets: number[];
+    code: string;
+    uniqueInFile: boolean;
+}

package/dist/types/core/src/runtime/playbackRate.d.ts

@@ -0,0 +1,26 @@
+import { clampPlaybackRate } from "@hyperframes/parsers/media-duration";
+import { type RateSpec } from "../speedRamp.js";
+export declare const normalizePlaybackRate: typeof clampPlaybackRate;
+/** Parse a literal numeric timing attribute without accepting trailing units or garbage. */
+export declare function parseStrictFiniteTimingNumber(raw: string | null | undefined): number | null;
+export declare function readElementPlaybackRate(el: Pick<Element, "getAttribute">): number;
+/** A constant rate clamped to the shared range; a lane is already normalised by its parser. */
+export declare function normalizeRateSpec(spec: RateSpec | undefined): RateSpec;
+/** The clip's rate: its `rate` lane when present, otherwise the constant rate. */
+export declare function readElementRateSpec(el: Pick<Element, "getAttribute">): RateSpec;
+export declare function readMediaStart(el: Pick<Element, "getAttribute">): number;
+export declare function resolveNaturalMediaTimelineDuration(el: Pick<Element, "getAttribute">, sourceDuration: number): number | null;
+/**
+ * How long a media element occupies the timeline: an authored `data-duration` trim, otherwise
+ * the source's natural length adjusted for playback start and rate (lane-aware). `null` while
+ * the source has not reported a duration yet. The authored/pending decision is the shared
+ * parsers resolver's; only a `rate` lane's arithmetic stays here, because lanes live in core.
+ */
+export declare function resolveMediaElementDurationSeconds(el: Pick<Element, "getAttribute"> & {
+    duration: number;
+}): number | null;
+/** A timed `<img>` (`data-start` or `data-track-index`) gets the dropped-image default unless
+ *  trimmed by `data-duration` or `data-end`; a bare `<img>` is a static layer. `null` otherwise. */
+export declare function resolveTimedImageDurationSeconds(el: Element, startSeconds?: number): number | null;
+/** A constant rate goes through the shared arithmetic; a `rate` lane integrates over its points. */
+export declare function resolveNaturalMediaTimelineDurationFromValues(sourceDuration: number, mediaStart: number, playbackRate: RateSpec): number | null;