@maravilla-labs/types 0.8.0 → 0.8.3

package/index.d.ts

@@ -294,6 +294,207 @@ export interface Storage {
      */
     getMetadata(key: string): Promise<StorageMetadata>;
 }
+/** Output image format for browser screenshots. */
+export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
+/** Page-size preset for browser PDF renders. */
+export type PdfPageFormat = 'A4' | 'A3' | 'Letter' | 'Legal' | 'Tabloid';
+/** Video codec for deterministic frame renders. */
+export type FramesCodec = 'h264' | 'vp9';
+/** Lifecycle state of a browser / frames job. Mirrors transforms `JobStatus`. */
+export type BrowserJobStatus = 'pending' | 'running' | 'complete' | 'failed';
+/** Viewport (CSS pixels) the headless browser launches with. */
+export interface BrowserViewport {
+    width: number;
+    height: number;
+}
+/**
+ * "Wait until" predicate before the screenshot / PDF capture fires.
+ * Set at most one of `selector`, `network_idle`, or `ms`; the worker
+ * picks the first non-null in that order.
+ */
+export interface BrowserWaitFor {
+    /** CSS selector that must resolve before the capture fires. */
+    selector?: string;
+    /** Wait for the network to go idle (~500ms with no in-flight requests). */
+    network_idle?: boolean;
+    /** Sleep for this many milliseconds then capture. Capped at ~30s by the worker. */
+    ms?: number;
+}
+/** Cookie pre-installed on the browser context before navigation. */
+export interface BrowserCookie {
+    name: string;
+    value: string;
+    domain?: string;
+}
+/**
+ * Request shape for `platform.env.BROWSER.screenshot(...)`.
+ *
+ * Exactly one of `url` (public URL — SSRF-gated by the worker) or `path`
+ * (relative path resolved against the tenant's deployment via loopback
+ * to Delivery) must be set.
+ */
+export interface ScreenshotRequest {
+    /** Public URL. Worker blocks loopback / RFC1918 / link-local after DNS. */
+    url?: string;
+    /** Path on the tenant's own deployment, e.g. `/dashboard`. */
+    path?: string;
+    viewport?: BrowserViewport;
+    wait_for?: BrowserWaitFor;
+    /** Capture the full scrollable page rather than the viewport. */
+    full_page?: boolean;
+    /** Defaults to `"png"` server-side when omitted. */
+    format?: ScreenshotFormat;
+    /** JPEG / WebP quality 1–100. Ignored for PNG. */
+    quality?: number;
+    cookies?: BrowserCookie[];
+    /** Extra HTTP headers applied to every navigation request. */
+    headers?: Record<string, string>;
+    /** Storage key where the PNG / JPEG / WebP is written. Required. */
+    target: string;
+}
+/**
+ * Request shape for `platform.env.BROWSER.pdf(...)`. Same `url`/`path`
+ * discipline as {@link ScreenshotRequest}.
+ */
+export interface PdfRequest {
+    url?: string;
+    path?: string;
+    /** Defaults to `"A4"` server-side when omitted. */
+    format?: PdfPageFormat;
+    landscape?: boolean;
+    /** Render CSS background colour / images. Defaults `true` server-side. */
+    print_background?: boolean;
+    cookies?: BrowserCookie[];
+    headers?: Record<string, string>;
+    target: string;
+}
+/**
+ * Request shape for `platform.env.FRAMES.render(...)`.
+ *
+ * Path-only on purpose: the renderer drives one of the tenant's own
+ * deployment routes (which is expected to import `@maravilla/frames`
+ * and call `defineTimeline({...})`) frame-by-frame via CDP
+ * `HeadlessExperimental.beginFrame`.
+ */
+export interface FramesRenderRequest {
+    /** Path on the tenant's deployment, e.g. `/render/intro-card?title=Hi`. */
+    path: string;
+    /** Frames per second. Must be ≥ 1; worker caps the upper bound. */
+    fps: number;
+    /** Total clip duration in milliseconds. */
+    duration_ms: number;
+    /** Output width (CSS pixels). Doubles as the browser viewport width. */
+    width: number;
+    /** Output height. */
+    height: number;
+    /** Storage key of an optional audio track ffmpeg mixes in. */
+    audio?: string;
+    /** Defaults to `"h264"` server-side when omitted. */
+    codec?: FramesCodec;
+    /** Constant Rate Factor for the encoder. Worker picks a default when unset. */
+    crf?: number;
+    /** Storage key the MP4 / WebM is written to. Required — no auto-generation. */
+    target: string;
+}
+/**
+ * Handle returned by every BROWSER / FRAMES method. `output_key` is the
+ * caller-supplied `target` and is known up front; status updates as the
+ * worker progresses through the shared transforms job ledger.
+ */
+export interface BrowserJobHandle {
+    id: string;
+    src_key: string;
+    output_key: string;
+    status: BrowserJobStatus;
+}
+/**
+ * Headless-browser surface exposed as `platform.env.BROWSER`.
+ */
+export interface BrowserClient {
+    /**
+     * Capture a screenshot of a public URL or one of the tenant's own
+     * routes. Returns a {@link BrowserJobHandle} whose `output_key` equals
+     * the caller-supplied `request.target` and is known up front — poll
+     * `platform.media.transforms.job(handle.id)` for status, then fetch
+     * the bytes from `platform.env.STORAGE` once the job completes.
+     *
+     * Exactly one of `request.url` or `request.path` must be set.
+     * `url` mode is gated by an SSRF block-list applied after DNS
+     * resolution; `path` mode loopback-routes to the tenant's own
+     * deployment.
+     *
+     * @param request `url` (public, SSRF-gated) or `path` (own deployment),
+     *   plus optional `viewport`, `wait_for`, `format`, `cookies`,
+     *   `headers`, and the required `target` storage key.
+     * @returns A handle to poll. `output_key` is `request.target`.
+     *
+     * @example
+     * ```ts
+     * const handle = await platform.env.BROWSER.screenshot({
+     *   url: 'https://example.com',
+     *   viewport: { width: 1280, height: 720 },
+     *   target: 'shots/example.png',
+     * });
+     * ```
+     */
+    screenshot(request: ScreenshotRequest): Promise<BrowserJobHandle>;
+    /**
+     * Render the target page to a PDF. Same `url` xor `path` discipline
+     * as {@link BrowserClient.screenshot}.
+     *
+     * @param request `url` or `path`, plus optional `format` (page-size
+     *   preset), `landscape`, `print_background`, `cookies`, `headers`,
+     *   and the required `target` storage key.
+     * @returns A handle to poll. `output_key` is `request.target`.
+     *
+     * @example
+     * ```ts
+     * const handle = await platform.env.BROWSER.pdf({
+     *   path: '/invoices/INV-1042',
+     *   format: 'A4',
+     *   print_background: true,
+     *   target: 'invoices/INV-1042.pdf',
+     * });
+     * ```
+     */
+    pdf(request: PdfRequest): Promise<BrowserJobHandle>;
+}
+/**
+ * Deterministic-video surface exposed as `platform.env.FRAMES`.
+ */
+export interface FramesClient {
+    /**
+     * Render one of the tenant's own deployment routes to MP4 / WebM,
+     * frame-accurately. The route is expected to import
+     * `@maravilla-labs/frames` and call `defineTimeline({...})` at load
+     * time — the worker drives `window.__mvFrames.applyState(t)` once
+     * per frame and captures via CDP `HeadlessExperimental.beginFrame`,
+     * piping PNG frames into ffmpeg.
+     *
+     * Same render against the same route is deterministic — two
+     * back-to-back renders produce byte-identical output (modulo
+     * already-stripped muxer metadata).
+     *
+     * @param request `path` on the tenant's deployment, `fps`,
+     *   `duration_ms`, `width`, `height`, optional `audio` storage key,
+     *   `codec` (`h264` default, `vp9` for WebM), optional `crf`, and
+     *   the required `target` storage key.
+     * @returns A handle to poll. `output_key` is `request.target`.
+     *
+     * @example
+     * ```ts
+     * const handle = await platform.env.FRAMES.render({
+     *   path: '/render/hello',
+     *   fps: 30,
+     *   duration_ms: 2000,
+     *   width: 1280,
+     *   height: 720,
+     *   target: 'renders/hello.mp4',
+     * });
+     * ```
+     */
+    render(request: FramesRenderRequest): Promise<BrowserJobHandle>;
+}
 /**
  * Authenticated user record from the platform auth service.
  */
@@ -969,6 +1170,10 @@ export interface Platform {
         KV: KvStore;
         DB: Database;
         STORAGE: Storage;
+        /** Headless-browser screenshot / PDF — Phase 1 stub, real impl in Task #2. */
+        BROWSER: BrowserClient;
+        /** Deterministic HTML → MP4 / WebM render — Phase 1 stub, real impl in Task #3. */
+        FRAMES: FramesClient;
     };
 }
 /**

package/index.ts

@@ -338,6 +338,232 @@ export interface Storage {
   getMetadata(key: string): Promise<StorageMetadata>;
 }
 
+// ════════════════════════════════════════════════════════════════════
+// Headless browser + deterministic-video render
+// ════════════════════════════════════════════════════════════════════
+//
+// Same JobHandle / polling model as the existing media-transforms surface
+// (`@maravilla-labs/platform`'s `transforms.ts`): every mutating method
+// returns a {@link BrowserJobHandle} the caller polls until the status is
+// terminal. Phase 1 wires the contract surface end-to-end — the underlying
+// worker returns `failed("not implemented")` until Task #2 and Task #3
+// implement the Chromium + ffmpeg pipelines.
+
+/** Output image format for browser screenshots. */
+export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
+
+/** Page-size preset for browser PDF renders. */
+export type PdfPageFormat = 'A4' | 'A3' | 'Letter' | 'Legal' | 'Tabloid';
+
+/** Video codec for deterministic frame renders. */
+export type FramesCodec = 'h264' | 'vp9';
+
+/** Lifecycle state of a browser / frames job. Mirrors transforms `JobStatus`. */
+export type BrowserJobStatus = 'pending' | 'running' | 'complete' | 'failed';
+
+/** Viewport (CSS pixels) the headless browser launches with. */
+export interface BrowserViewport {
+  width: number;
+  height: number;
+}
+
+/**
+ * "Wait until" predicate before the screenshot / PDF capture fires.
+ * Set at most one of `selector`, `network_idle`, or `ms`; the worker
+ * picks the first non-null in that order.
+ */
+export interface BrowserWaitFor {
+  /** CSS selector that must resolve before the capture fires. */
+  selector?: string;
+  /** Wait for the network to go idle (~500ms with no in-flight requests). */
+  network_idle?: boolean;
+  /** Sleep for this many milliseconds then capture. Capped at ~30s by the worker. */
+  ms?: number;
+}
+
+/** Cookie pre-installed on the browser context before navigation. */
+export interface BrowserCookie {
+  name: string;
+  value: string;
+  domain?: string;
+}
+
+/**
+ * Request shape for `platform.env.BROWSER.screenshot(...)`.
+ *
+ * Exactly one of `url` (public URL — SSRF-gated by the worker) or `path`
+ * (relative path resolved against the tenant's deployment via loopback
+ * to Delivery) must be set.
+ */
+export interface ScreenshotRequest {
+  /** Public URL. Worker blocks loopback / RFC1918 / link-local after DNS. */
+  url?: string;
+  /** Path on the tenant's own deployment, e.g. `/dashboard`. */
+  path?: string;
+  viewport?: BrowserViewport;
+  wait_for?: BrowserWaitFor;
+  /** Capture the full scrollable page rather than the viewport. */
+  full_page?: boolean;
+  /** Defaults to `"png"` server-side when omitted. */
+  format?: ScreenshotFormat;
+  /** JPEG / WebP quality 1–100. Ignored for PNG. */
+  quality?: number;
+  cookies?: BrowserCookie[];
+  /** Extra HTTP headers applied to every navigation request. */
+  headers?: Record<string, string>;
+  /** Storage key where the PNG / JPEG / WebP is written. Required. */
+  target: string;
+}
+
+/**
+ * Request shape for `platform.env.BROWSER.pdf(...)`. Same `url`/`path`
+ * discipline as {@link ScreenshotRequest}.
+ */
+export interface PdfRequest {
+  url?: string;
+  path?: string;
+  /** Defaults to `"A4"` server-side when omitted. */
+  format?: PdfPageFormat;
+  landscape?: boolean;
+  /** Render CSS background colour / images. Defaults `true` server-side. */
+  print_background?: boolean;
+  cookies?: BrowserCookie[];
+  headers?: Record<string, string>;
+  target: string;
+}
+
+/**
+ * Request shape for `platform.env.FRAMES.render(...)`.
+ *
+ * Path-only on purpose: the renderer drives one of the tenant's own
+ * deployment routes (which is expected to import `@maravilla/frames`
+ * and call `defineTimeline({...})`) frame-by-frame via CDP
+ * `HeadlessExperimental.beginFrame`.
+ */
+export interface FramesRenderRequest {
+  /** Path on the tenant's deployment, e.g. `/render/intro-card?title=Hi`. */
+  path: string;
+  /** Frames per second. Must be ≥ 1; worker caps the upper bound. */
+  fps: number;
+  /** Total clip duration in milliseconds. */
+  duration_ms: number;
+  /** Output width (CSS pixels). Doubles as the browser viewport width. */
+  width: number;
+  /** Output height. */
+  height: number;
+  /** Storage key of an optional audio track ffmpeg mixes in. */
+  audio?: string;
+  /** Defaults to `"h264"` server-side when omitted. */
+  codec?: FramesCodec;
+  /** Constant Rate Factor for the encoder. Worker picks a default when unset. */
+  crf?: number;
+  /** Storage key the MP4 / WebM is written to. Required — no auto-generation. */
+  target: string;
+}
+
+/**
+ * Handle returned by every BROWSER / FRAMES method. `output_key` is the
+ * caller-supplied `target` and is known up front; status updates as the
+ * worker progresses through the shared transforms job ledger.
+ */
+export interface BrowserJobHandle {
+  id: string;
+  src_key: string;
+  output_key: string;
+  status: BrowserJobStatus;
+}
+
+/**
+ * Headless-browser surface exposed as `platform.env.BROWSER`.
+ */
+export interface BrowserClient {
+  /**
+   * Capture a screenshot of a public URL or one of the tenant's own
+   * routes. Returns a {@link BrowserJobHandle} whose `output_key` equals
+   * the caller-supplied `request.target` and is known up front — poll
+   * `platform.media.transforms.job(handle.id)` for status, then fetch
+   * the bytes from `platform.env.STORAGE` once the job completes.
+   *
+   * Exactly one of `request.url` or `request.path` must be set.
+   * `url` mode is gated by an SSRF block-list applied after DNS
+   * resolution; `path` mode loopback-routes to the tenant's own
+   * deployment.
+   *
+   * @param request `url` (public, SSRF-gated) or `path` (own deployment),
+   *   plus optional `viewport`, `wait_for`, `format`, `cookies`,
+   *   `headers`, and the required `target` storage key.
+   * @returns A handle to poll. `output_key` is `request.target`.
+   *
+   * @example
+   * ```ts
+   * const handle = await platform.env.BROWSER.screenshot({
+   *   url: 'https://example.com',
+   *   viewport: { width: 1280, height: 720 },
+   *   target: 'shots/example.png',
+   * });
+   * // poll handle.id via platform.media.transforms.job(...)
+   * ```
+   */
+  screenshot(request: ScreenshotRequest): Promise<BrowserJobHandle>;
+  /**
+   * Render the target page to a PDF. Same `url` xor `path` discipline
+   * as {@link BrowserClient.screenshot}.
+   *
+   * @param request `url` or `path`, plus optional `format` (page-size
+   *   preset), `landscape`, `print_background`, `cookies`, `headers`,
+   *   and the required `target` storage key.
+   * @returns A handle to poll. `output_key` is `request.target`.
+   *
+   * @example
+   * ```ts
+   * const handle = await platform.env.BROWSER.pdf({
+   *   path: '/invoices/INV-1042',
+   *   format: 'A4',
+   *   print_background: true,
+   *   target: 'invoices/INV-1042.pdf',
+   * });
+   * ```
+   */
+  pdf(request: PdfRequest): Promise<BrowserJobHandle>;
+}
+
+/**
+ * Deterministic-video surface exposed as `platform.env.FRAMES`.
+ */
+export interface FramesClient {
+  /**
+   * Render one of the tenant's own deployment routes to MP4 / WebM,
+   * frame-accurately. The route is expected to import
+   * `@maravilla-labs/frames` and call `defineTimeline({...})` at load
+   * time — the worker drives `window.__mvFrames.applyState(t)` once
+   * per frame and captures via CDP `HeadlessExperimental.beginFrame`,
+   * piping PNG frames into ffmpeg.
+   *
+   * Same render against the same route is deterministic — two
+   * back-to-back renders produce byte-identical output (modulo
+   * already-stripped muxer metadata).
+   *
+   * @param request `path` on the tenant's deployment, `fps`,
+   *   `duration_ms`, `width`, `height`, optional `audio` storage key,
+   *   `codec` (`h264` default, `vp9` for WebM), optional `crf`, and
+   *   the required `target` storage key.
+   * @returns A handle to poll. `output_key` is `request.target`.
+   *
+   * @example
+   * ```ts
+   * const handle = await platform.env.FRAMES.render({
+   *   path: '/render/hello',
+   *   fps: 30,
+   *   duration_ms: 2000,
+   *   width: 1280,
+   *   height: 720,
+   *   target: 'renders/hello.mp4',
+   * });
+   * ```
+   */
+  render(request: FramesRenderRequest): Promise<BrowserJobHandle>;
+}
+
 // ════════════════════════════════════════════════════════════════════
 // Auth, Stewardship, Resources, Circles, Groups, Relations
 // ════════════════════════════════════════════════════════════════════
@@ -1136,6 +1362,10 @@ export interface Platform {
     KV: KvStore;
     DB: Database;
     STORAGE: Storage;
+    /** Headless-browser screenshot / PDF — Phase 1 stub, real impl in Task #2. */
+    BROWSER: BrowserClient;
+    /** Deterministic HTML → MP4 / WebM render — Phase 1 stub, real impl in Task #3. */
+    FRAMES: FramesClient;
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/types",
-  "version": "0.8.0",
+  "version": "0.8.3",
   "description": "TypeScript definitions for Maravilla Runtime platform APIs",
   "main": "index.ts",
   "types": "index.ts",