Skip to content

Write HTML. Render video. Built for agents.

26.9 KB
Raw Blame
import type { CompositionVariable, VariableValidationIssue } from "@hyperframes/core/variables";

/**
 * Cross-referenced variable usage for a whole composition: the per-script
 * static scans merged and compared against the declared schema.
 */
export interface VariableUsageReport {
  /** Variable ids read by composition scripts (static analysis, first-seen order). */
  usedIds: string[];
  /** Declared ids never read by any script. */
  unusedDeclarations: string[];
  /** Ids read by scripts but missing from data-composition-variables. */
  undeclaredReads: string[];
  /**
   * True when any script accesses variables opaquely (computed keys, escaping
   * values object…) — usedIds is then a lower bound and unusedDeclarations
   * may be false positives.
   */
  scanIncomplete: boolean;
}

// ─── Document model ───────────────────────────────────────────────────────────

/** Full DOM-level view of one editable element. Built by the SDK adaptation layer. */
export interface HyperFramesElement {
  readonly id: string;
  /**
   * Fully-qualified scoped id — host-chain prefix + leaf, separated by "/".
   * For top-level elements: scopedId === id.
   * For elements inside inlined sub-compositions: "hf-HOST/hf-LEAF" (any depth).
   * This is the canonical identifier to use in dispatch targets, getElement(),
   * find(), and override-set keys when addressing sub-composition elements.
   */
  readonly scopedId: string;
  readonly tag: string;
  readonly children: readonly HyperFramesElement[];
  /** camelCase property names — mirrors CSSStyleDeclaration convention */
  readonly inlineStyles: Readonly<Record<string, string>>;
  readonly classNames: readonly string[];
  /** All attributes except style, class, and data-hf-* (those are model-level) */
  readonly attributes: Readonly<Record<string, string>>;
  /** Display text for the SDK setText target, not a full descendant-text snapshot. */
  readonly text: string | null;
  // Timing — null when element has no data-start
  readonly start: number | null;
  readonly duration: number | null;
  readonly trackIndex: number | null;
  /** Phase 2: GSAP tween IDs whose target is this element */
  readonly animationIds: readonly string[];
}

/** The SDK's in-memory document. Built from ensureHfIds + linkedom DOM walk. */
export interface SdkDocument {
  readonly roots: readonly HyperFramesElement[];
  readonly gsapScript: string | null;
  readonly styles: string | null;
  readonly width: number | null;
  readonly height: number | null;
  readonly compositionDuration: number | null;
  /**
   * BUILD-TIME snapshot of the ensureHfIds-stamped HTML. Never updated after
   * mutations — use Composition.serialize() for the current document state.
   */
  readonly html: string;
}

// ─── Override-set (T3 embedded mode) ─────────────────────────────────────────

/**
 * Sparse map of `hfId.prop.path → value` overrides layered on top of the base template.
 * null value = removal marker (element or property deleted by user).
 * Examples: { "hf-x7k2.style.fontSize": "96px", "hf-y3a1.text": "Hello", "hf-z5k2": null }
 *
 * Font and image variable overrides store their object values under the var.{id} key:
 * { "var.brand-font": { name: "Roboto", source: "https://fonts.googleapis.com/…" } }
 */
/**
 * A set of variable overrides. The `Record<string, unknown>` member admits
 * object-valued variables (font/image). NOTE for SDK consumers: this widening
 * means code reading an OverrideSet value must narrow before assuming a scalar —
 * an object value will type-check anywhere `unknown` is accepted.
 */
export type OverrideSet = Record<
  string,
  string | number | boolean | Record<string, unknown> | null
>;

// ─── can() result ─────────────────────────────────────────────────────────────

/**
 * Structured result from can(op).
 *
 * `ok: true` — dispatch(op) will succeed.
 * `ok: false` — dispatch would be a no-op or error; `code` is stable for switch.
 *   Codes: E_TARGET_NOT_FOUND | E_NO_ROOT | E_NO_GSAP_TIMELINE | E_NO_GSAP_SCRIPT
 */
export type CanResult = { ok: true } | { ok: false; code: string; message: string; hint?: string };

// ─── Edit operations (F1: explicit target on every element op) ────────────────

export type HfId = string;

/** Every element op takes explicit target id(s). No selection-implicit mutation. */
export type EditOp =
  | { type: "setStyle"; target: HfId | HfId[]; styles: Record<string, string | null> }
  | { type: "setText"; target: HfId | HfId[]; value: string }
  | { type: "setAttribute"; target: HfId | HfId[]; name: string; value: string | null }
  | {
      type: "setTiming";
      target: HfId | HfId[];
      start?: number;
      duration?: number;
      trackIndex?: number;
      /** Default true: start/duration also apply to `data-link` partners. `false` edits the target alone and unlinks it. */
      linked?: boolean;
    }
  | { type: "setHold"; target: HfId | HfId[]; hold: ElasticHold }
  | { type: "moveElement"; target: HfId | HfId[]; x: number; y: number }
  | { type: "removeElement"; target: HfId | HfId[] }
  | {
      type: "addElement";
      /** Id of the parent element, or null to insert at the document body root. */
      parent: HfId | null;
      /** Zero-based sibling index at which to insert (append if >= childCount). */
      index: number;
      /** Single-root HTML fragment. Must not contain <script>. */
      html: string;
    }
  | {
      type: "reorderElements";
      /** Each entry sets inline zIndex on one element. Positioning is unchanged — z-index only takes effect on non-static elements, so the caller must ensure the target is positioned. */
      entries: Array<{ target: HfId; zIndex: number }>;
    }
  | { type: "setClassStyle"; selector: string; styles: Record<string, string | null> }
  | { type: "setCompositionMetadata"; width?: number; height?: number; duration?: number }
  | { type: "declareVariable"; declaration: CompositionVariable }
  | { type: "updateVariableDeclaration"; id: string; declaration: CompositionVariable }
  | { type: "removeVariableDeclaration"; id: string }
  | {
      type: "setVariableValue";
      id: string;
      value: string | number | boolean | FontValue | ImageValue;
    }
  // #2098 alias op — remove-by-id, kept for its shipped session.removeVariable().
  | { type: "removeVariable"; id: string }
  | { type: "addGsapTween"; target: HfId; tween: GsapTweenSpec }
  | { type: "setGsapTween"; animationId: string; properties: Partial<GsapTweenSpec> }
  | {
      type: "setGsapKeyframe";
      animationId: string;
      keyframeIndex: number;
      position?: number;
      value?: Record<string, unknown>;
      ease?: string;
    }
  | {
      type: "addGsapKeyframe";
      animationId: string;
      position: number;
      value: Record<string, unknown>;
    }
  | { type: "removeGsapKeyframe"; animationId: string; percentage: number }
  | { type: "removeGsapProperty"; animationId: string; property: string; from?: boolean }
  | { type: "removeGsapTween"; animationId: string }
  | { type: "removeAllKeyframes"; animationId: string }
  | {
      type: "convertToKeyframes";
      animationId: string;
      resolvedFromValues?: Record<string, number | string>;
    }
  | { type: "deleteAllForSelector"; selector: string }
  | {
      type: "materializeKeyframes";
      animationId: string;
      keyframes: Array<{
        percentage: number;
        properties: Record<string, number | string>;
        ease?: string;
      }>;
      easeEach?: string;
      resolvedSelector?: string;
    }
  | { type: "splitIntoPropertyGroups"; animationId: string }
  | {
      type: "splitAnimations";
      originalId: string;
      newId: string;
      splitTime: number;
      elementStart: number;
      elementDuration: number;
    }
  | { type: "addLabel"; name: string; position: number }
  | { type: "removeLabel"; name: string }
  | {
      type: "setArcPath";
      animationId: string;
      config: {
        enabled: boolean;
        autoRotate: boolean | number;
        segments: Array<{
          curviness?: number;
          cp1?: { x: number; y: number };
          cp2?: { x: number; y: number };
        }>;
      };
    }
  | {
      type: "updateArcSegment";
      animationId: string;
      segmentIndex: number;
      update: {
        curviness?: number;
        cp1?: { x: number; y: number };
        cp2?: { x: number; y: number };
      };
    }
  | { type: "removeArcPath"; animationId: string }
  | {
      type: "unrollDynamicAnimations";
      animationId: string;
      elements: Array<{
        selector: string;
        keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
        easeEach?: string;
      }>;
    }
  | {
      /** Insert a new keyframed tween for targetSelector at the given position/duration. */
      type: "addWithKeyframes";
      targetSelector: string;
      /** Timeline position in seconds. Number-only (unlike GsapTweenSpec.position, which also accepts label-relative strings). */
      position: number;
      duration: number;
      keyframes: KeyframeSpec[];
      ease?: string;
    }
  | {
      /**
       * Replace an existing tween (by animationId) with a new keyframed tween.
       * Equivalent to removeGsapTween + addWithKeyframes in one atomic op.
       * Position-derived tween IDs renumber after the remove; callers must
       * re-parse to discover the new ID.
       */
      type: "replaceWithKeyframes";
      animationId: string;
      targetSelector: string;
      /** Timeline position in seconds. Number-only (unlike GsapTweenSpec.position, which also accepts label-relative strings). */
      position: number;
      duration: number;
      keyframes: KeyframeSpec[];
      ease?: string;
    };

/**
 * A single keyframe entry for `addWithKeyframes` / `replaceWithKeyframes`.
 * Single source of truth — Studio-side mirrors (KeyframeEntry/KeyframeSpec) should
 * import this rather than redeclare the shape.
 */
export interface KeyframeSpec {
  percentage: number;
  properties: Record<string, number | string>;
  ease?: string;
  /** GSAP endpoint flag — emitted as numeric `_auto: 1`, not boolean. */
  auto?: boolean;
}

export interface ElasticHold {
  start: number;
  end: number;
  fill: "freeze" | "loop";
}

/**
 * Object value for a `font` variable (LOCKED §7 — object-valued, never a CSS string).
 * `name` is the CSS font-family value; `source` is the stylesheet URL to load.
 */
export interface FontValue {
  name: string;
  source: string;
}

/**
 * Object value for an `image` variable (LOCKED §7 — object-valued, never a CSS string).
 * `url` is the image src. Add explicit optional fields here as consumers need them —
 * an open `[key: string]: unknown` index signature was dropped because it let any
 * `{url}`-shaped object through and swallowed key typos.
 */
export interface ImageValue {
  url: string;
  alt?: string;
  fit?: "cover" | "contain" | "fill" | "none" | "scale-down";
}

export interface GsapTweenSpec {
  method: "from" | "to" | "fromTo" | "set";
  position?: number | string;
  duration?: number;
  ease?: string;
  fromProperties?: Record<string, unknown>;
  toProperties?: Record<string, unknown>;
  /** Tween values for 'from', 'to', and 'set'; destination values for 'fromTo'. */
  properties?: Record<string, unknown>;
  repeat?: number;
  yoyo?: boolean;
  stagger?: number | Record<string, unknown>;
}

// ─── Patch layer (F2: RFC 6902 frozen contract) ───────────────────────────────

/**
 * Emit-only subset of RFC 6902: the SDK never emits move/copy/test, and
 * applyPatches() ignores ops outside this subset. Hosts feeding patches back
 * must restrict themselves to add/remove/replace.
 */
export interface JsonPatchOp {
  op: "add" | "remove" | "replace";
  path: string;
  value?: unknown;
}

/**
 * Emitted by session.on('patch') after every committed change.
 * formatVersion bumps = breaking; hosts check once and reject unknown versions.
 */
export interface PatchEvent {
  readonly formatVersion: 1;
  readonly patches: readonly JsonPatchOp[];
  readonly inversePatches: readonly JsonPatchOp[];
  /** Re-emitted verbatim from the mutation entry. Use ORIGIN_APPLY_PATCHES to detect undo loops. */
  readonly origin: unknown;
  /** Semantic op names ('setStyle') — for analytics/history labels. Not versioned. */
  readonly opTypes: readonly string[];
}

// ─── Origin model (F4) ────────────────────────────────────────────────────────

/**
 * Reserved origin tag for applyPatches().
 * Host listeners MUST skip this origin to prevent undo loops:
 *   comp.on('patch', ({ origin }) => { if (origin === ORIGIN_APPLY_PATCHES) return; ... })
 *
 * A namespaced string (not a unique symbol) so the sentinel survives realm
 * boundaries — postMessage, structured clone, JSON — which T3 embedded hosts
 * may forward patch events across. The namespace prefix keeps collision risk
 * with host-chosen origins negligible.
 */
export const ORIGIN_APPLY_PATCHES = "@hyperframes/sdk:applyPatches" as const;

/** Default origin when none specified — UI-driven dispatch. */
export const ORIGIN_LOCAL = "local" as const;

// ─── Event types ─────────────────────────────────────────────────────────────

export interface PersistErrorEvent {
  error: { message: string; hint?: string; cause?: unknown };
}

// ─── Element query / snapshot (F1 query API) ─────────────────────────────────

/** Flat read-only snapshot returned by getElements() / getElement() */
export type ElementSnapshot = HyperFramesElement;

export interface FindQuery {
  tag?: string;
  text?: string;
  name?: string;
  track?: number;
  /** Filter to elements inside a specific sub-composition host (by host hf-id). */
  composition?: string;
}

// ─── Typed method sugar (F10) ─────────────────────────────────────────────────

/**
 * Proxy returned by comp.selection() — resolves getSelection() → explicit ops at call time.
 * Multi-select gets well-defined semantics: op applied per id within one batch.
 */
export interface SelectionProxy {
  readonly ids: readonly string[];
  setStyle(styles: Record<string, string | null>): void;
  setText(value: string): void;
  setAttribute(name: string, value: string | null): void;
  setTiming(
    timing: { start?: number; duration?: number; trackIndex?: number },
    opts?: { linked?: boolean },
  ): void;
  removeElement(): void;
}

/**
 * Curried element handle — holds only the id string, no stale-ref hazard.
 * comp.element('hf-x7k2').setStyle({ color: '#fff' })
 */
export interface ElementHandle {
  readonly id: string;
  setStyle(styles: Record<string, string | null>): void;
  setText(value: string): void;
  setAttribute(name: string, value: string | null): void;
  setTiming(
    timing: { start?: number; duration?: number; trackIndex?: number },
    opts?: { linked?: boolean },
  ): void;
  removeElement(): void;
}

// ─── Timing accessor types (WS-C) ─────────────────────────────────────────────

/**
 * Resolved timing snapshot for one element.
 * Labels are GSAP timeline label names whose numeric position falls within
 * [enterAt, exitAt] for this element. Parsed fresh on every call — never cached.
 */
export interface ElementTimingSnapshot {
  enterAt: number;
  exitAt: number;
  /** GSAP addLabel names active during this element's window. */
  labels: string[];
}

// ─── Composition (the main public surface, F10) ───────────────────────────────

/**
 * An open composition editing session.
 * Typed methods (docs page one) sugar over dispatch() — all validation in dispatch.
 * dispatch() is the advanced/agent layer (data-shaped ops, automation, replay).
 */
export interface Composition {
  // ── Typed methods (F10 layer 1) ────────────────────────────────────────────
  setStyle(id: HfId, styles: Record<string, string | null>): void;
  setText(id: HfId, value: string): void;
  setAttribute(id: HfId, name: string, value: string | null): void;
  /** Also moves `data-link` partners unless `{ linked: false }`, which edits `id` alone and unlinks it. */
  setTiming(
    id: HfId,
    timing: { start?: number; duration?: number; trackIndex?: number },
    opts?: { linked?: boolean },
  ): void;
  /** Frames `id` sits from its `data-sync-origin` partner, positive when late; null if unpaired or rates differ. */
  syncOffset(id: HfId, fps?: number): number | null;
  moveIntoSync(id: HfId): void;
  slipIntoSync(id: HfId): void;
  removeElement(id: HfId): void;
  /**
   * Insert an HTML fragment as a child of `parent` at `index` (WS-D).
   * Mints a stable hf-id against the live document's existing id set.
   * Returns the minted id of the inserted root element.
   * Inverse = removeElement of the returned id.
   */
  addElement(parent: HfId | null, index: number, html: string): HfId;
  setVariableValue(id: string, value: string | number | boolean | FontValue | ImageValue): void;
  /**
   * Current `default` value for a declared variable, or undefined if
   * undeclared/unset. Convenience over getVariableValues() (kept from #2098).
   *
   * `{ base: true }` returns the default as authored at open — BEFORE the
   * T3 override-set or any setVariableValue folded into the declaration.
   * Hosts replaying an undo that removes a `var.<id>` override should restore
   * this value. Ids declared mid-session fall through to the live default.
   */
  getVariableValue(
    id: string,
    opts?: { base?: boolean },
  ): string | number | boolean | FontValue | ImageValue | undefined;
  /**
   * Every declared variable's full schema (id/type/label/default/…), or [] when
   * none. Alias of getVariableDeclarations() (kept from #2098's surface).
   */
  listVariables(): CompositionVariable[];
  /** Remove a variable's declaration — alias of removeVariableDeclaration(). */
  removeVariable(id: string): void;
  /**
   * Declare a new variable in `data-composition-variables`. No-ops when the
   * id is already declared (see can() for the E_DUPLICATE_VARIABLE check);
   * creates the attribute when the composition has none yet.
   */
  declareVariable(declaration: CompositionVariable): void;
  /**
   * Replace an existing declaration wholesale (label, type, constraints,
   * default — the id itself is immutable; rename = remove + declare). When
   * the default changes to/from a scalar, the `--{id}` CSS compat custom
   * property on the root is kept in sync, mirroring setVariableValue.
   */
  updateVariableDeclaration(id: string, declaration: CompositionVariable): void;
  /**
   * Remove a declaration (and the last one removes the whole attribute).
   * Also clears the `--{id}` CSS compat custom property if present.
   */
  removeVariableDeclaration(id: string): void;
  /**
   * Read the typed variable declarations from `data-composition-variables`
   * (the canonical schema — same filter the render pipeline uses; malformed
   * entries are dropped). Read-only — does not dispatch.
   */
  getVariableDeclarations(): CompositionVariable[];
  /**
   * Resolve this composition's variable values: its declared defaults merged
   * with `overrides` (overrides win, undeclared override keys pass through).
   * Read-only — does not dispatch.
   *
   * Scope: reads THIS composition file's own declaration element, not a union of
   * every `[data-composition-variables]` in a bundled document. The runtime's
   * `getVariables()` additionally walks inlined sub-composition declarers because
   * it runs on the fully-bundled document; the SDK models one composition file,
   * so per-file scope is intentional (and is what Studio needs to predict a
   * single file's `--variables` payload). For the common single-`<html>`
   * composition the two agree; they diverge only when sub-comp declarers are
   * inlined into one document.
   */
  getVariableValues(overrides?: Record<string, unknown>): Record<string, unknown>;
  /**
   * Validate a values map against the declared schema. Returns undeclared /
   * type-mismatch / enum-out-of-range issues (same checks as the CLI's
   * `--strict-variables`). Read-only — does not dispatch.
   */
  validateVariableValues(values: Record<string, unknown>): VariableValidationIssue[];
  /**
   * Cross-reference the declared schema against a static scan of every inline
   * composition script (getVariables() reads). Read-only — does not dispatch.
   */
  getVariableUsage(): VariableUsageReport;
  /**
   * Apply variable values to the preview surface (ephemeral — never written
   * to the document; use setVariableValue to persist a default). Pass null to
   * restore declared defaults. No-op when the preview adapter doesn't
   * implement setPreviewVariables; returns whether the adapter handled it.
   */
  setPreviewVariables(values: Record<string, unknown> | null): boolean;
  /**
   * Read enter/exit times and GSAP labels for every timed element (WS-C).
   * Derives enterAt/exitAt using the same data-duration vs data-end preference
   * as handleSetTiming (data-duration wins; data-end − data-start as fallback).
   * Labels are parsed fresh from the GSAP script each call.
   * Read-only — does not dispatch.
   */
  getElementTimings(): Record<HfId, ElementTimingSnapshot>;
  /**
   * Apply a sparse timing map in a single batch (WS-C).
   * Dispatches one setTiming op per entry inside a batch so the history sees
   * one undo step. Skips entries for unknown ids silently.
   */
  setElementTiming(
    map: Record<HfId, { start?: number; duration?: number; trackIndex?: number }>,
  ): void;
  /**
   * Set an elastic hold window on an element (WS-C).
   * Thin typed wrapper over the existing setHold op — mirrors setVariableValue pattern.
   */
  setHold(id: HfId, hold: ElasticHold): void;
  /** Returns the newly-assigned tween ID */
  addGsapTween(target: HfId, tween: GsapTweenSpec): string;
  setGsapTween(animationId: string, properties: Partial<GsapTweenSpec>): void;
  removeGsapTween(animationId: string): void;
  /**
   * Add a keyframed tween. Typed wrapper over the addWithKeyframes op (mirrors
   * addGsapTween). Returns the newly-minted animationId, or "" if rejected.
   */
  addWithKeyframes(
    targetSelector: string,
    position: number,
    duration: number,
    keyframes: KeyframeSpec[],
    ease?: string,
  ): string;
  /**
   * Replace an existing keyframed tween. Typed wrapper over replaceWithKeyframes.
   * Returns the replacement's animationId (treat as NEW — position-derived IDs
   * renumber after the remove), or "" if rejected.
   */
  replaceWithKeyframes(
    animationId: string,
    targetSelector: string,
    position: number,
    duration: number,
    keyframes: KeyframeSpec[],
    ease?: string,
  ): string;
  undo(): void;
  redo(): void;
  canUndo(): boolean;
  canRedo(): boolean;

  // ── Query API (F1) ─────────────────────────────────────────────────────────
  getElements(): ElementSnapshot[];
  /** Top-level elements only, each carrying its full subtree — no id appears twice. */
  getRootElements(): ElementSnapshot[];
  getElement(id: HfId): ElementSnapshot | null;
  find(query: FindQuery): string[];
  /**
   * Every GSAP tween id parsed from the composition's script, regardless of
   * whether its target selector currently matches a live DOM element. See
   * parsedAnimationIds in document.ts for why this differs from the
   * per-element animationIds on ElementSnapshot.
   */
  getAllAnimationIds(): Set<string>;

  // ── Selection API ──────────────────────────────────────────────────────────
  /** Sugar: resolves getSelection() → explicit ops at call time */
  selection(): SelectionProxy;
  /** Curried handle — holds only the id, no stale-ref hazard */
  element(id: HfId): ElementHandle;
  getSelection(): string[];
  /** Replace the current selection; fires selectionchange. Pass [] to clear. */
  setSelection(ids: string[]): void;

  // ── Advanced / agent layer (F10 layer 2) ──────────────────────────────────
  dispatch(op: EditOp, opts?: { origin?: unknown }): void;
  batch(fn: () => void, opts?: { origin?: unknown }): void;
  /**
   * Dry-run validation — would dispatch(op) succeed?
   * Returns {ok:true} when dispatch would mutate the document, {ok:false,code,message} otherwise.
   * Use as a feature-detection gate: `const r = comp.can(op); if (!r.ok) return;`
   * addGsapTween / addLabel return {ok:false,code:'E_NO_GSAP_TIMELINE'} when the
   * script has no gsap.timeline() declaration to attach to.
   */
  can(op: EditOp): CanResult;

  // ── Events (one typed emitter — F10) ──────────────────────────────────────
  on(event: "change", handler: () => void): () => void;
  on(event: "selectionchange", handler: (ids: string[]) => void): () => void;
  on(event: "patch", handler: (event: PatchEvent) => void): () => void;
  on(event: "persist:error", handler: (event: PersistErrorEvent) => void): () => void;

  // ── Serialization ──────────────────────────────────────────────────────────
  /** stripRuntime removes an embedded preview-runtime script — for a host driving its own clock. */
  serialize(opts?: { stripRuntime?: boolean }): string;

  // ── T3 embedded-mode extras ────────────────────────────────────────────────
  /** Current override-set — serialize for host storage */
  getOverrides(): OverrideSet;
  /** Apply inverse patches from host undo stack; auto-tags origin: ORIGIN_APPLY_PATCHES */
  applyPatches(patches: readonly JsonPatchOp[], opts?: { origin?: unknown }): void;

  // ── Lifecycle ──────────────────────────────────────────────────────────────
  /** Drain the persist queue — resolves when any queued write is committed. No-op if no adapter. */
  flush(): Promise<void>;
  dispose(): void;
}