Skip to content

Write HTML. Render video. Built for agents.

8.3 KB
Raw Blame
import type { CanvasResolution } from "@hyperframes/parsers";
import type { RegistryItem } from "@hyperframes/core";
import type { BundleOptions } from "@hyperframes/core/compiler";
import type { ProjectHistory } from "./history/projectHistory.js";

/** Resolved info about a single project. */
export interface ResolvedProject {
  id: string;
  dir: string;
  title?: string;
  sessionId?: string;
}

/** Observable render job state, polled by the SSE progress handler. */
export interface RenderJobState {
  id: string;
  status: "rendering" | "complete" | "failed" | "cancelled";
  progress: number;
  stage?: string;
  outputPath: string;
  error?: string;
  audioLoweredDb?: number;
  /**
   * Optional abort hook set by the adapter. The cancel route calls this to
   * stop an in-flight render; adapters that can't abort may omit it (the
   * route still marks the job cancelled so the SSE stream terminates).
   */
  cancel?: () => void;
}

export interface MediaProcessingJobState {
  id: string;
  status: "processing" | "complete" | "failed";
  progress: number;
  stage?: string;
  inputAssetPath: string;
  outputAssetPath: string;
  outputPath: string;
  backgroundOutputAssetPath?: string;
  backgroundOutputPath?: string;
  error?: string;
  provider?: string;
  framesProcessed?: number;
  durationSeconds?: number;
  avgMsPerFrame?: number;
}

/** Lint result from the core linter. */
export interface LintResult {
  findings: Array<{
    code?: string;
    severity: string;
    message: string;
    file?: string;
    fixHint?: string;
  }>;
}

export interface ProjectLintResult {
  results: Array<{ file: string; result: LintResult }>;
}

export interface StudioSelectionTextField {
  key: string;
  label: string;
  value: string;
  tagName: string;
  source: "self" | "child" | "text-node";
}

export interface StudioSelectionSnapshot {
  schemaVersion: 1;
  projectId: string;
  compositionPath: string;
  sourceFile: string;
  currentTime: number;
  target: {
    id?: string | null;
    hfId?: string;
    selector?: string;
    selectorIndex?: number;
  };
  label: string;
  tagName: string;
  boundingBox: { x: number; y: number; width: number; height: number };
  textContent: string | null;
  dataAttributes: Record<string, string>;
  inlineStyles: Record<string, string>;
  computedStyles: Record<string, string>;
  textFields: StudioSelectionTextField[];
  capabilities: Record<string, boolean | string | undefined>;
  thumbnailUrl: string;
}

export interface StudioSelectionResponse {
  selection: StudioSelectionSnapshot | null;
  updatedAt: string | null;
}

/**
 * Adapter interface — injected by each consumer to handle host-specific behavior.
 * The shared API module calls these methods; each host (vite dev, CLI embedded)
 * provides its own implementation.
 */
export interface StudioApiAdapter {
  /** List all available projects. */
  listProjects(): Promise<ResolvedProject[]> | ResolvedProject[];

  /** Resolve a project ID (or session ID) to its directory. Returns null if not found. */
  resolveProject(id: string): Promise<ResolvedProject | null> | ResolvedProject | null;

  /**
   * Optional: the project's current history. A history refuses every call once its folder is replaced (a
   * deleted `.hyperframes`, a new project there), so keep them in `historyCache`, which reopens. Else routes 404.
   */
  history?: (project: ResolvedProject) => Promise<ProjectHistory | null> | ProjectHistory | null;

  /** Bundle a project directory into a single HTML string, forwarding `options` over the host's own. */
  bundle(
    projectDir: string,
    options?: Pick<BundleOptions, "stampHfIds" | "onRead">,
  ): Promise<string | null>;

  /** Optional: a cached `createProjectSignature(dir)`; preview caching checks builds against it. */
  getProjectSignature?: (projectDir: string) => string;
  invalidateProjectSignature?: (projectDir: string) => void;

  loadSharp?: () => Promise<typeof import("sharp").default>;

  /** Lint a single HTML string. */
  lint(
    html: string,
    opts?: { filePath?: string; isSubComposition?: boolean; compSrcPath?: string },
  ): Promise<LintResult> | LintResult;

  /**
   * Lint the complete project, including relationships between files. Official
   * adapters provide this; the single-file method remains as a compatibility
   * fallback for third-party adapters compiled against older releases.
   */
  lintProject?: (projectDir: string) => Promise<ProjectLintResult> | ProjectLintResult;

  /** URL to the hyperframe runtime JS (injected into preview HTML). */
  runtimeUrl: string;

  /**
   * Optional: post-process preview HTML before Studio augments it.
   * Useful when preview must mirror render-time compilation steps.
   */
  transformPreviewHtml?: (opts: {
    html: string;
    project: ResolvedProject;
    activeCompositionPath: string;
  }) => Promise<string> | string;

  /** Directory where render output files are stored. */
  rendersDir(project: ResolvedProject): string;

  /**
   * Start a render job. The adapter owns the async execution and must
   * update the returned RenderJobState object reactively.
   */
  startRender(opts: {
    project: ResolvedProject;
    outputPath: string;
    format: "mp4" | "webm" | "mov";
    /**
     * Frame rate as an exact rational. The HTTP layer (POST
     * `/projects/:id/render`) accepts either a JSON number (integer fps,
     * `30`) or a JSON string (ffmpeg-style rational, `"30000/1001"`); the
     * route normalizes both into `Fps` before invoking the adapter, so
     * adapter implementations only ever see the rational form.
     */
    fps: import("@hyperframes/core").Fps;
    quality: string;
    crf?: number;
    videoBitrate?: string;
    videoFrameFormat?: "auto" | "jpg" | "png";
    hdrMode?: "auto" | "force-hdr" | "force-sdr";
    jobId: string;
    /**
     * The triggering browser profile has telemetry disabled (localStorage
     * opt-out, DNT, dev build...). The CLI cannot observe any of that, so the
     * browser has to say so — without it the server emitted render outcomes
     * for a user who had opted out, under the CLI's own policy.
     */
    telemetryOptOut?: boolean;
    pageMotionBlur?: "off";
    /**
     * Optional output resolution preset. See `resolveDeviceScaleFactor` in
     * the producer for the integer-scale + aspect + HDR constraints.
     */
    outputResolution?: CanvasResolution;
    /** Entry file relative to projectDir (e.g. "compositions/intro.html"). Defaults to index.html. */
    composition?: string;
    /**
     * Composition-variable overrides ({variableId: value}), forwarded to the
     * producer's RenderConfig.variables and injected as window.__hfVariables —
     * the same channel `hyperframes render --variables` uses.
     */
    variables?: Record<string, unknown>;
    useGpu?: boolean;
    /**
     * Telemetry id of the browser user who triggered the render. Lets the
     * adapter attribute the server-emitted render_complete/render_error to
     * that user so the studio render funnel is joinable. Undefined for older
     * clients → falls back to the install's anonymous id.
     */
    distinctId?: string;
  }): RenderJobState;

  startBackgroundRemoval?: (opts: {
    project: ResolvedProject;
    inputPath: string;
    inputAssetPath: string;
    outputPath: string;
    outputAssetPath: string;
    backgroundOutputPath?: string;
    backgroundOutputAssetPath?: string;
    quality: "fast" | "balanced" | "best";
    device?: "auto" | "cpu" | "coreml" | "cuda";
    jobId: string;
  }) => MediaProcessingJobState;

  /** Optional: generate a thumbnail at the route's explicit output dimensions. */
  generateThumbnail?: (opts: {
    project: ResolvedProject;
    compPath: string;
    seekTime: number;
    width: number;
    height: number;
    outputWidth: number;
    outputHeight: number;
    previewUrl: string;
    selector?: string;
    format?: "jpeg" | "png";
    selectorIndex?: number;
    signal: AbortSignal;
  }) => Promise<Buffer | null>;

  /** Optional: resolve session ID to project (multi-project mode). */
  resolveSession?: (sessionId: string) => Promise<{ projectId: string; title: string } | null>;

  /** Optional: list all registry items (blocks + components) for the catalog. */
  listRegistryCatalog?(): Promise<RegistryItem[]>;

  /** Optional: install a registry item into a project directory. */
  installRegistryBlock?(opts: {
    project: ResolvedProject;
    blockName: string;
  }): Promise<{ written: string[]; block: RegistryItem }>;
}