@hyperframes/inspector 0.0.0-stage → 0.8.152

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

@@ -0,0 +1,30 @@
+export declare const RUNTIME_PROTOCOL_VERSION: 1;
+export declare const RUNTIME_FILLER = "hf-runtime-filler";
+export declare const RUNTIME_PROTOCOL_CAPABILITIES: readonly ["seconds-time", "rational-fps", "seek-keep-playing", "composition-manifest-v1", "runtime-data", "play-range"];
+export type RuntimeProtocolFps = {
+    numerator: number;
+    denominator: number;
+};
+export type RuntimeProtocolV1 = {
+    protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
+    capabilities: readonly string[];
+    fps: RuntimeProtocolFps;
+};
+export type RuntimeProtocolInspection = {
+    status: "legacy";
+    fps: number;
+} | {
+    status: "supported";
+    fps: number;
+    metadata: RuntimeProtocolV1;
+} | {
+    status: "unsupported";
+    code: "unsupported_protocol_version" | "invalid_protocol_metadata";
+    receivedVersion: unknown;
+};
+export declare function runtimeProtocolFpsFromNumber(value: number): RuntimeProtocolFps;
+export declare function playRangeHoldTime(start: number, end: number, fps: number): number;
+export declare function runtimeProtocolFpsToNumber(value: unknown): number | null;
+export declare function runtimeProtocolMetadata(fps: number): RuntimeProtocolV1;
+export declare function frameDisplayScale(frame: HTMLElement): number | null;
+export declare function inspectRuntimeProtocol(value: unknown, legacyFps?: number): RuntimeProtocolInspection;

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

@@ -0,0 +1,3 @@
+/** Media elements swapped to their proxy, each with the src attribute it had before the swap. */
+export declare const swappedElements: WeakMap<Element, string | null>;
+export declare function unproxiedSrc(el: Element): string | null;

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

@@ -0,0 +1,14 @@
+/**
+ * Pure parser for the `data-start` timing expression grammar, shared by the
+ * browser runtime resolver (`createRuntimeStartTimeResolver`) and the Node-side
+ * video-frame extractor (`parseVideoElements`) so both agree on exactly what a
+ * relative reference means. No DOM/browser dependencies — safe to import in
+ * Node.
+ *
+ * Grammar (matches the docs' "Relative Timing" section):
+ *   - `"12.5"`            -> absolute seconds
+ *   - `"intro"`           -> start when clip `intro` ends
+ *   - `"intro + 2"`       -> 2s after `intro` ends
+ *   - `"intro - 0.5"`     -> 0.5s before `intro` ends (overlap)
+ */
+export { parseNumeric, parseStartExpression, type ReferenceExpression, } from "@hyperframes/parsers/composition-contract";

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

@@ -0,0 +1,21 @@
+import type { RuntimeTimelineLike } from "./types.js";
+import { type HostSlot } from "../mediaTiming.js";
+export declare function createRuntimeStartTimeResolver(params: {
+    timelineRegistry?: Record<string, Pick<RuntimeTimelineLike, "duration"> | undefined>;
+    includeAuthoredTimingAttrs?: boolean;
+    /**
+     * The document that reference lookups (`data-start="intro + 2"`) resolve
+     * against. Defaults to the global `document` — the runtime bundle's own
+     * realm. Hosts driving a composition in an IFRAME must pass that iframe's
+     * document, or every reference silently resolves against the host page.
+     */
+    documentRef?: Document;
+}): {
+    resolveStartForElement: (element: Element, fallback?: number) => number;
+    resolveDurationForElement: (element: Element) => number | null;
+    resolveMediaStartForElement: (element: Element) => number;
+    resolveHostStartForElement: (element: Element) => number;
+    resolveHostSlotsForElement: (element: Element) => HostSlot[];
+    isRootGlobalMediaStartForElement: (element: Element) => boolean;
+};
+export type { RuntimeTimelineLike } from "./types.js";

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

@@ -0,0 +1,3 @@
+import type { RuntimeTimelineLike } from "./types.js";
+/** A registered timeline's finite duration(); a partial, throwing or non-numeric entry reads as null. */
+export declare function readTimelineDurationSeconds(timeline: Pick<RuntimeTimelineLike, "duration"> | null | undefined): number | null;

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

@@ -0,0 +1,46 @@
+import { type AnimationValues } from "./timelineValues.js";
+import type { ElementRef, Target } from "./inspectionTypes.js";
+export interface TimelineRequest {
+    component?: Target;
+    at?: number;
+    range?: [number, number];
+    boundary?: number;
+    generation?: string;
+    offset?: number;
+}
+export interface TimedAnimation {
+    parent?: TimedAnimation;
+    timeline?: TimedAnimation;
+    _ease?: (progress: number) => number;
+    vars?: Record<string, unknown>;
+    targets?: () => unknown[];
+    getChildren?: (nested: boolean, tweens: boolean, timelines: boolean) => TimedAnimation[];
+    startTime(): number;
+    duration(): number;
+    totalDuration?(): number;
+    timeScale?(): number;
+    repeat?(): number;
+    repeatDelay?(): number;
+    yoyo?(): boolean;
+    paused?(): boolean;
+}
+export interface Interval {
+    start: number;
+    end: number;
+}
+export interface TimelineEvent extends Interval {
+    kind: "animation" | "item";
+    relation: string;
+    component: ElementRef | null;
+    targets: ElementRef[];
+    properties: string[];
+    values?: AnimationValues;
+    stack: string | null;
+}
+export interface TimelineRuntimeResult {
+    status: string;
+    candidates: ElementRef[];
+    events: TimelineEvent[];
+    warnings: string[];
+}
+export declare function inspectTimelineRuntime(q: TimelineRequest, roots: TimedAnimation[], scope: Element, describe: (el: Element) => ElementRef, origin: (a: TimedAnimation) => string | null, reserved: Set<string>, registry: Record<string, TimedAnimation>): TimelineRuntimeResult;

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

@@ -0,0 +1,15 @@
+export interface DeclaredValue {
+    kind: "literal" | "relative" | "expression" | "unknown";
+    value: number | string | null;
+}
+export interface AnimationValues {
+    basis: "authored-tween";
+    properties: Array<{
+        property: string;
+        from: DeclaredValue;
+        to: DeclaredValue;
+    }>;
+    ease: DeclaredValue;
+}
+/** Authored endpoints, never sampled values or inferred previous-tween state. */
+export declare function animationValues(vars: Record<string, unknown>, properties: string[]): AnimationValues;

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

@@ -0,0 +1,335 @@
+import type { HfColorGradingTarget } from "../colorGrading.js";
+import type { RuntimeAnalyticsEvent } from "./analytics.js";
+export type RuntimeJson = string | number | boolean | null | RuntimeJson[] | {
+    [key: string]: RuntimeJson;
+};
+import type { HyperframeControlAction } from "../inline-scripts/runtimeContract.js";
+import type { HyperframePickerElementInfo } from "../inline-scripts/pickerApi.js";
+import type { RuntimeProtocolV1 } from "./protocol.js";
+type RuntimeBridgeControlActionBase = HyperframeControlAction | "tick" | "set-volume" | "set-media-output-muted" | "set-native-media-sync-disabled" | "set-web-audio-media-disabled" | "set-idle-heartbeat" | "set-display-scale" | "set-root-duration" | "set-play-range" | "stop-media" | "flash-elements";
+type RuntimeBridgeControlMessageBase = {
+    source: "hf-parent";
+    type: "control";
+    action: RuntimeBridgeControlAction;
+    frame?: number;
+    timeSeconds?: number;
+    muted?: boolean;
+    volume?: number;
+    durationSeconds?: number;
+    startSeconds?: number | null;
+    endSeconds?: number | null;
+    disabled?: boolean;
+    slow?: boolean;
+    scale?: number;
+    playbackRate?: number;
+    target?: HfColorGradingTarget | string | null;
+    grading?: RuntimeJson;
+    compare?: RuntimeJson;
+    seekMode?: "drag" | "commit";
+};
+export type RuntimeStateMessage = {
+    source: "hf-preview";
+    type: "state";
+    frame: number;
+    currentTime: number;
+    ended: boolean;
+    isPlaying: boolean;
+    muted: boolean;
+    playbackRate: number;
+};
+export type RuntimeTimelineClipIdentity = {
+    id: string | null;
+    label: string;
+    start: number;
+    duration: number;
+    track: number;
+    kind: "video" | "audio" | "image" | "element" | "composition";
+    tagName: string | null;
+    compositionId: string | null;
+    parentCompositionId: string | null;
+    compositionSrc: string | null;
+    assetUrl: string | null;
+};
+export type RuntimeTimelineClip = RuntimeTimelineClipIdentity & {
+    zIndex: number;
+    stackingContextId: string | null;
+    compositionAncestors: string[];
+    nodePath: string | null;
+    playbackStart: number;
+    playbackRate: number;
+    timelineRole: string | null;
+    timelineLabel: string | null;
+    timelineGroup: string | null;
+    timelinePriority: number | null;
+};
+export type RuntimeTimelineScene = {
+    id: string;
+    label: string;
+    start: number;
+    duration: number;
+    thumbnailUrl: string | null;
+    avatarName: string | null;
+};
+export type RuntimeTimelineMessage = RuntimeProtocolV1 & {
+    source: "hf-preview";
+    type: "timeline";
+    compositionContractVersion: 1;
+    durationSeconds: number;
+    durationInFrames: number;
+    clips: RuntimeTimelineClip[];
+    scenes: RuntimeTimelineScene[];
+    compositionWidth: number;
+    compositionHeight: number;
+    /** Present when this runtime will post `assets-ready`; the value is whether
+     * the composition's assets have settled yet. Absent on older runtimes, whose
+     * parents must not wait for a message that never comes. */
+    assetsReady?: boolean;
+};
+export type RuntimeDiagnosticMessage = {
+    source: "hf-preview";
+    type: "diagnostic";
+    code: string;
+    details: Record<string, RuntimeJson>;
+};
+export type RuntimePickerElementInfo = HyperframePickerElementInfo;
+export type RuntimePickerHoveredMessage = {
+    source: "hf-preview";
+    type: "element-hovered";
+    elementInfo: RuntimePickerElementInfo;
+};
+export type RuntimePickerCandidatesMessage = {
+    source: "hf-preview";
+    type: "element-pick-candidates";
+    candidates: RuntimePickerElementInfo[];
+    selectedIndex: number;
+    point: {
+        x: number;
+        y: number;
+    };
+};
+export type RuntimePickerPickedMessage = {
+    source: "hf-preview";
+    type: "element-picked";
+    elementInfo: RuntimePickerElementInfo;
+};
+export type RuntimePickerPickedManyMessage = {
+    source: "hf-preview";
+    type: "element-picked-many";
+    elementInfos: RuntimePickerElementInfo[];
+};
+export type RuntimePickerCancelledMessage = {
+    source: "hf-preview";
+    type: "pick-mode-cancelled";
+};
+export type RuntimeStageSizeMessage = {
+    source: "hf-preview";
+    type: "stage-size";
+    width: number;
+    height: number;
+};
+/**
+ * Fired once per session when the runtime's attempt to play a timed media
+ * element is rejected with `NotAllowedError`. The parent (web component / host
+ * app) uses this as the signal to promote to parent-frame audio proxies —
+ * iframes lose autoplay privileges when the user gesture originated in the
+ * parent frame, so the host has to take over audible playback there.
+ */
+export type RuntimeMediaAutoplayBlockedMessage = {
+    source: "hf-preview";
+    type: "media-autoplay-blocked";
+};
+/**
+ * Posted by the runtime when `installRuntimeControlBridge` finishes registering
+ * its message listener — signals that subsequent control messages
+ * (`set-muted`, `set-volume`, `set-playback-rate`, etc.) will now be received
+ * and processed. The parent (web component / host app) listens for this and
+ * replays current playback state to repair any race where bridge messages
+ * were posted before the listener was installed. Emitted again on every iframe
+ * reload because the new runtime instance starts with no state.
+ */
+export type RuntimeReadyMessage = {
+    source: "hf-preview";
+    type: "ready";
+};
+/** Posted once per runtime instance, after the first timeline message, when
+ * the composition's media, images and fonts have settled (or timed out). It
+ * lets a parent that cannot read the iframe (opaque origin) gate playback. */
+export type RuntimeAssetsReadyMessage = {
+    source: "hf-preview";
+    type: "assets-ready";
+    timedOut: boolean;
+};
+export type RuntimeDataErrorMessage = {
+    source: "hf-preview";
+    type: "runtime-data-error";
+    channel: string;
+    requestId: number;
+    message: string;
+};
+export type RuntimeDataAppliedMessage = {
+    source: "hf-preview";
+    type: "runtime-data-applied";
+    channel: string;
+    requestId: number;
+};
+/**
+ * Analytics events emitted by the runtime.
+ *
+ * The host app receives these via postMessage and forwards to its analytics
+ * provider (PostHog, Mixpanel, Amplitude, custom logging, etc.).
+ * No analytics SDK runs inside this iframe.
+ */
+export type RuntimeAnalyticsMessage = {
+    source: "hf-preview";
+    type: "analytics";
+    event: RuntimeAnalyticsEvent;
+    properties: Record<string, string | number | boolean | null>;
+};
+/**
+ * Numeric performance metrics emitted by the runtime — scrub latency, sustained
+ * fps, dropped frames, decoder count, composition load time, media sync drift.
+ * The host aggregates per-session values (p50/p95) and forwards to its
+ * observability pipeline. Distinct from `analytics` events because perf data
+ * is continuous and numeric, not discrete.
+ */
+export type RuntimePerformanceMessage = {
+    source: "hf-preview";
+    type: "perf";
+    name: string;
+    value: number;
+    tags: Record<string, string | number | boolean | null>;
+};
+/** One audio group's live meter reading, polled from the transport each tick
+ *  while playing. A group id absent from `levels` is idle/unknown (no active
+ *  member) — the studio side treats that as "no reading", not zero. */
+export type RuntimeGroupLevelsMessage = {
+    source: "hf-preview";
+    type: "group-levels";
+    levels: Array<{
+        groupId: string;
+        level: number;
+        clipped: boolean;
+    }>;
+};
+export type RuntimeOutboundMessage = RuntimeStateMessage | RuntimeTimelineMessage | RuntimeDiagnosticMessage | RuntimePickerHoveredMessage | RuntimePickerCandidatesMessage | RuntimePickerPickedMessage | RuntimePickerPickedManyMessage | RuntimePickerCancelledMessage | RuntimeStageSizeMessage | RuntimeMediaAutoplayBlockedMessage | RuntimeReadyMessage | RuntimeAssetsReadyMessage | RuntimeDataErrorMessage | RuntimeDataAppliedMessage | RuntimeAnalyticsMessage | RuntimePerformanceMessage | RuntimeGroupLevelsMessage;
+export type HeldSeek = Promise<void> | void;
+export type RuntimePlayer = {
+    _timeline: RuntimeTimelineLike | null;
+    play: () => void;
+    pause: () => void;
+    seek: (timeSeconds: number, options?: {
+        keepPlaying?: boolean;
+    }) => HeldSeek;
+    renderSeek: (timeSeconds: number, options?: RuntimeSeekOptions) => void;
+    getTime: () => number;
+    getDuration: () => number;
+    isPlaying: () => boolean;
+    setPlaybackRate: (rate: number) => void;
+    getPlaybackRate: () => number;
+};
+export type RuntimeSeekOptions = {
+    suppressEvents?: boolean;
+    /**
+     * Subdivide the output frame grid this render seek quantizes onto. Integer >= 1;
+     * 1 (or absent) is the output frame grid. Motion-blur sub-frame sampling passes the
+     * engine's sub-frame tick count so a fractional sample time survives quantization.
+     */
+    subFrameDivisions?: number;
+    exact?: boolean;
+};
+export type RuntimeTimelineChildLike = {
+    targets?: () => unknown[];
+    vars?: unknown;
+    startTime?: () => number;
+    duration?: () => number;
+    data?: unknown;
+    parent?: RuntimeTimelineChildLike;
+    getChildren?: RuntimeTimelineLike["getChildren"];
+};
+/** A timeline or tween a composition script started, as a scene swap stops it. */
+export type SceneAnimation = {
+    targets?: () => unknown[];
+    duration?: () => number;
+    getChildren?: (nested?: boolean, tweens?: boolean, timelines?: boolean) => SceneAnimation[];
+    revert?: () => void;
+    kill?: () => void;
+    totalTime?: (timeSeconds?: number, suppressEvents?: boolean) => unknown;
+};
+export type RuntimeTimelineLike = {
+    play: () => void;
+    pause: () => void;
+    seek: (timeSeconds?: number, suppressEvents?: boolean) => unknown;
+    totalTime?: (timeSeconds?: number, suppressEvents?: boolean) => unknown;
+    totalDuration?: () => number;
+    progress?: (value?: number, suppressEvents?: boolean) => unknown;
+    time: () => number;
+    duration: () => number;
+    add: (timeline: RuntimeTimelineLike, startAtSeconds: number) => void;
+    paused: (paused?: boolean) => void;
+    timeScale?: (rate: number) => void;
+    set: (target: RuntimeGsapSetTarget, vars: RuntimeGsapSetVars, atSeconds?: number) => void;
+    getChildren?: (nested?: boolean, tweens?: boolean, timelines?: boolean, ignoreBeforeTime?: number) => RuntimeTimelineChildLike[];
+};
+export type RuntimeDeterministicAdapter = {
+    name: string;
+    discover: () => void;
+    seek: (ctx: {
+        time: number;
+        suppressEvents?: boolean;
+        pageAnimations?: () => Animation[];
+    }) => void;
+    pause: (ctx?: {
+        pageAnimations?: () => Animation[];
+    }) => void;
+    play?: () => void;
+    revert?: () => void;
+    /**
+     * Optional async readiness gate. If the adapter has outstanding async work
+     * (e.g. Three.js's `DefaultLoadingManager` still loading models/textures),
+     * return a promise that settles when the work is done. The runtime waits
+     * for the returned promise to settle before publishing
+     * `window.__renderReady = true`, so the engine doesn't capture empty
+     * frames while assets are still loading.
+     *
+     * Return `null` (or omit the method) when nothing is pending. The runtime
+     * calls this on every readiness-publish evaluation and tracks promise
+     * identity, so returning the same promise on repeated calls is the
+     * expected contract — return a fresh promise only when a new wait is
+     * actually needed (e.g. a new batch of items has been queued).
+     *
+     * Throwing or rejecting is safe: the runtime swallows the error and
+     * proceeds to publish (matching the existing failure-doesn't-block-render
+     * convention).
+     */
+    getReadyPromise?: () => PromiseLike<unknown> | null;
+    /**
+     * Optional duration auto-inference. Non-GSAP runtimes (CSS, WAAPI, Lottie)
+     * have no `window.__timelines` entry, so the runtime has no authored source
+     * of truth for total composition length unless the author sets
+     * `data-duration` on the root element. This hook lets an adapter report the
+     * longest end time it can discover from its own animations, so the runtime
+     * can fold it into the duration floor (see `resolveAdapterDurationFloorSeconds`
+     * in `init.ts`) and treat `data-duration` as optional rather than required.
+     *
+     * Return the inferred duration in seconds, or `null` when nothing usable
+     * was discovered (e.g. no animations yet, or an animation with unbounded /
+     * infinite iteration count that can't be resolved to a finite end time —
+     * those compositions must keep declaring `data-duration` explicitly).
+     *
+     * Called on every adapter-discovery cycle (same cadence as `discover`), so
+     * it's safe — and expected — to return a growing value as async work
+     * (Lottie JSON fetch, etc.) resolves.
+     */
+    getInferredDurationSeconds?: () => number | null;
+    getAnimationCycleEndSeconds?: () => number | null;
+};
+export type RuntimeGsapSetTarget = string | Element | Element[] | null;
+export type RuntimeGsapSetVars = Record<string, string | number | boolean | null | undefined>;
+type RuntimeDataControlFields = {
+    channel?: string;
+    payload?: unknown;
+    requestId?: number;
+};
+type RuntimeBridgeControlAction = RuntimeBridgeControlActionBase | "set-runtime-data" | "clear-runtime-data";
+export type RuntimeBridgeControlMessage = RuntimeBridgeControlMessageBase & RuntimeDataControlFields;
+export {};

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

@@ -0,0 +1,8 @@
+/**
+ * Resolve the composition-variable values an element should see: the scoped
+ * per-instance table for inlined sub-compositions, then the top-level merged
+ * getVariables(), then the raw render-injection global. Shared by every
+ * runtime consumer of variables (color grading, declarative bindings) so the
+ * scope chain can never diverge between channels.
+ */
+export declare function readVariablesForElement(element: Element): Record<string, unknown>;

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

@@ -0,0 +1,49 @@
+export declare function realpath(path: string): string;
+/**
+ * Reject paths that escape the `base` directory — including via symlinks.
+ *
+ * `path.resolve()` collapses `.`/`..` but does NOT dereference symlinks, so a
+ * plain prefix check (`resolved.startsWith(base + sep)`) can be defeated by a
+ * symlink that lives *inside* `base` but points outside it (e.g.
+ * `base/link -> /etc`). A downstream `readFileSync`/`writeFileSync`/`statSync`
+ * then follows that link to a file outside `base`. To close this we canonicalize
+ * both sides with `realpathSync.native` (the on-disk letter case too) before comparing.
+ *
+ * The target may not exist yet (e.g. creating a new file), so we canonicalize the
+ * deepest *existing* ancestor and re-attach the trailing not-yet-existing
+ * segments. Segments that don't exist cannot be symlinks at check time, so they
+ * can't redirect the path outside `base` right now. (A symlink swapped in between
+ * this check and the subsequent fs call is an inherent TOCTOU race this helper
+ * does not, and cannot by itself, defend against.)
+ *
+ * Lives at the package root rather than under `studio-api/` because callers span
+ * layers — `studio-api` routes, the `compiler`, the CLI, and the engine — and
+ * `compiler` sits below `studio-api` in the dependency graph, so it cannot import
+ * from there without a backwards edge.
+ */
+export declare function isSafePath(base: string, resolved: string): boolean;
+/**
+ * Resolve `relativePath` against `base` and return the absolute path only if it
+ * stays within `base` (after symlink resolution); otherwise return `null`.
+ *
+ * Prefer this over a bare `resolve()` followed by a separate `isSafePath()`
+ * check: collapsing the two into one call means a caller cannot resolve a
+ * project-relative path and then forget the containment guard — the gap that
+ * let the symlink-escape slip past several call sites historically.
+ */
+export declare function resolveWithinProject(base: string, relativePath: string): string | null;
+/** The project folder is gone, renamed or deleted while open; a write must not bring it back. */
+export declare class ProjectRootMissingError extends Error {
+    readonly root: string;
+    constructor(root: string);
+}
+export declare const isProjectRootMissing: (error: unknown) => boolean;
+/** True only when nothing is at `dir` any more; a folder that cannot be looked at (EACCES, EIO) is not gone. */
+export declare function folderGone(dir: string): boolean;
+/** The project folder's real path; ProjectRootMissingError when it is gone. */
+export declare function realProjectRoot(root: string): string;
+/**
+ * Creates `dir` below `root` one folder at a time, so a root moved away fails instead of reappearing.
+ * A `dir` outside `root` is created recursively, but only while `root` exists.
+ */
+export declare function mkdirWithinProject(root: string, dir: string): void;

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

@@ -0,0 +1,9 @@
+export declare const SCENE_PART_ATTR = "data-hf-scene";
+export declare const SCENE_PARTS_META = "hf-scene-parts";
+/** On a scene's top-level host: why the scene cannot be swapped in place, so edits to it reload. */
+export declare const SCENE_NO_SWAP_ATTR = "data-hf-scene-no-swap";
+/** Hashes of one preview document: everything outside the scene parts, and each scene's parts. */
+export interface SceneParts {
+    shared: string;
+    scenes: Record<string, string>;
+}

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

@@ -0,0 +1,59 @@
+/** A ramp is a `rate` lane in `data-automation`; `sourceTimeAt` is the one rate-to-time mapping consumers share. */
+import { type HfAutomationLane } from "./audioAutomation.js";
+/** A constant multiplier, or a lane whose `v` is the multiplier over clip-local time. */
+export type RateSpec = number | HfAutomationLane;
+/**
+ * The lane as seen from `dt` seconds into the clip: what a renderer sees after it trims the clip's start.
+ * A shaped segment (`curve`, `viaX`) cut in the middle is resampled, since its shape belongs to its left point.
+ */
+export declare function shiftRateLane(spec: RateSpec, dt: number): RateSpec;
+/** Speed multiplier at clip-local time `t`. */
+export declare function rateAt(spec: RateSpec, t: number): number;
+/** Source seconds consumed by clip-local time `t` (the integral of the rate). */
+export declare function sourceTimeAt(spec: RateSpec, t: number): number;
+/** Inverse of `sourceTimeAt`: the clip-local time at which `source` seconds have been consumed. */
+export declare function timeAtSourceTime(spec: RateSpec, source: number): number;
+/** The `rate` lane inside a `data-automation` attribute value, or null when absent or unreadable. */
+export declare function parseRateLane(raw: string | null | undefined): HfAutomationLane | null;
+/** A clip's rate: its `rate` lane when it has one, otherwise the constant. */
+export declare function resolveRateSpec(automationAttr: string | null | undefined, constant: number): RateSpec;
+/** The CapCut-style presets; `speedPresetLane` stretches one over a clip's duration. */
+export declare const SPEED_PRESETS: readonly [{
+    readonly id: "montage";
+    readonly label: "Montage";
+    readonly points: readonly [readonly [0, 0.9], readonly [0.15, 0.3], readonly [0.5, 2.5], readonly [0.85, 0.3], readonly [1, 0.9]];
+}, {
+    readonly id: "hero";
+    readonly label: "Hero";
+    readonly points: readonly [readonly [0, 1], readonly [0.25, 1.6], readonly [0.5, 0.25], readonly [0.75, 1.6], readonly [1, 1]];
+}, {
+    readonly id: "bullet";
+    readonly label: "Bullet";
+    readonly points: readonly [readonly [0, 3], readonly [0.4, 3], readonly [0.5, 0.15], readonly [0.6, 3], readonly [1, 3]];
+}, {
+    readonly id: "jump-cut";
+    readonly label: "Jump cut";
+    readonly points: readonly [readonly [0, 0.5], readonly [0.24, 0.5], readonly [0.26, 3], readonly [0.5, 3], readonly [0.52, 0.5], readonly [0.74, 0.5], readonly [0.76, 3], readonly [1, 3]];
+}, {
+    readonly id: "flash-in";
+    readonly label: "Flash in";
+    readonly points: readonly [readonly [0, 0.3], readonly [0.6, 0.6], readonly [1, 5]];
+}, {
+    readonly id: "flash-out";
+    readonly label: "Flash out";
+    readonly points: readonly [readonly [0, 5], readonly [0.4, 0.6], readonly [1, 0.3]];
+}, {
+    readonly id: "ramp-in";
+    readonly label: "Ramp in";
+    readonly points: readonly [readonly [0, 0.5], readonly [1, 1]];
+}, {
+    readonly id: "ramp-out";
+    readonly label: "Ramp out";
+    readonly points: readonly [readonly [0, 1], readonly [1, 0.5]];
+}, {
+    readonly id: "slowmo-middle";
+    readonly label: "Slow-mo middle";
+    readonly points: readonly [readonly [0, 1], readonly [number, 0.35], readonly [number, 0.35], readonly [1, 1]];
+}];
+export type SpeedPresetId = (typeof SPEED_PRESETS)[number]["id"];
+export declare function speedPresetLane(id: SpeedPresetId, clipDuration: number): HfAutomationLane;

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

@@ -0,0 +1,12 @@
+/**
+ * THE slug for composition-variable ids → CSS custom-property names. Shared
+ * by the figma importer (emits `var(--<slug>, literal)`) and the runtime
+ * (defines `--<slug>` from declared variables) — one function so the two
+ * sides can never drift. The slug is lossy (case-folded, symbol runs
+ * collapse to "-"), so distinct ids CAN collide; callers surface
+ * detectSlugCollisions() as a warning rather than silently merging.
+ */
+export declare function slugify(name: string): string;
+export declare function cssVariableName(id: string): string;
+/** Groups of distinct ids that collapse to the same CSS variable name. */
+export declare function detectSlugCollisions(ids: Iterable<string>): string[][];

package/dist/types/inspector/src/elementMap.d.ts

@@ -0,0 +1,33 @@
+import type { Page } from "puppeteer-core";
+
+export interface ElementNode {
+  index: number;
+  parent: number | null;
+  selector: string;
+  tag: string;
+  id: string;
+  hfId: string | null;
+  classes: string[];
+  composition: string | null;
+  compositionSrc: string | null;
+  text: string;
+  media: string | null;
+  relative: string;
+  groupSelector: string;
+  siblingMatchCount: number;
+  children: number[];
+}
+export interface ElementDom {
+  generation: string | null;
+  nodes: ElementNode[];
+  limitations: { canvas: number; iframes: number; shadowRoots: number };
+}
+export interface ElementMap {
+  text: string;
+  entries: { line: number; selectors: string[]; nodeIndices: number[] }[];
+  elementCount: number;
+  coveredCount: number;
+}
+export function collectElementDom(): ElementDom;
+export function formatElementMap(snapshot: ElementDom, options?: { file?: string }): ElementMap;
+export function createElementMap(page: Page, options?: { file?: string }): Promise<ElementMap>;