@maravilla-labs/platform 0.8.1 → 0.9.0

package/src/remote-client.ts

@@ -1,4 +1,4 @@
-import type { KvNamespace, KvListResult, Database, DbDocument, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, CreateManagedUserOptions, UserListFilter, UserListResponse, UpdateUserOptions, Relation, AddRelationOptions, ListRelationsOptions, PolicyExplain, CanCheck, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord } from './types.js';
+import type { KvNamespace, KvListResult, Database, DbDocument, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, CreateManagedUserOptions, UserListFilter, UserListResponse, UpdateUserOptions, Relation, AddRelationOptions, ListRelationsOptions, PolicyExplain, CanCheck, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord, BrowserClient, FramesClient, BrowserJobHandle, ScreenshotRequest, PdfRequest, FramesRenderRequest } from './types.js';
 import type { TransformsService, TranscodeOpts, ThumbnailOpts, ResizeOpts, OcrOpts, DocToPdfOpts, DocThumbnailOpts, DocConvertOpts, DocToMarkdownOpts, DocToHtmlOpts, DocReplaceImagesOpts, DocInsertQrCodeOpts, DocTemplateMergeOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
 import { RemoteMediaService } from './media.js';
 import { getRequestAuthHeader } from './request-scope.js';
@@ -1137,11 +1137,16 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   const policy = new RemotePolicyService();
   const workflows = new RemoteWorkflows(baseUrl, headers);
 
+  const browser = new RemoteBrowserClient(baseUrl, headers);
+  const frames = new RemoteFramesClient(baseUrl, headers);
+
   return {
     env: {
       KV: kvProxy,
       DB: db,
       STORAGE: storage,
+      BROWSER: browser,
+      FRAMES: frames,
     },
     media,
     realtime,
@@ -1151,6 +1156,70 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   };
 }
 
+/**
+ * Remote `platform.env.BROWSER` for development. Posts to the dev-server
+ * `/api/media/browser/*` routes and returns the same {@link BrowserJobHandle}
+ * shape the native runtime returns. Phase 1 plumbing — the worker marks
+ * the job `failed("not implemented")` immediately; clients can still
+ * exercise the full request → handle → poll cycle.
+ *
+ * @internal
+ */
+class RemoteBrowserClient implements BrowserClient {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  private async post(path: string, body: unknown): Promise<BrowserJobHandle> {
+    const res = await fetch(`${this.baseUrl}/api/media/browser${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...this.headers, ...getRequestAuthHeader() },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Browser error (${res.status}): ${text}`);
+    }
+    return res.json() as Promise<BrowserJobHandle>;
+  }
+
+  screenshot(request: ScreenshotRequest): Promise<BrowserJobHandle> {
+    return this.post('/screenshot', request);
+  }
+
+  pdf(request: PdfRequest): Promise<BrowserJobHandle> {
+    return this.post('/pdf', request);
+  }
+}
+
+/**
+ * Remote `platform.env.FRAMES` for development. Posts to the dev-server
+ * `/api/media/frames/render` route. Same plumbing stub story as
+ * {@link RemoteBrowserClient}.
+ *
+ * @internal
+ */
+class RemoteFramesClient implements FramesClient {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  async render(request: FramesRenderRequest): Promise<BrowserJobHandle> {
+    const res = await fetch(`${this.baseUrl}/api/media/frames/render`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...this.headers, ...getRequestAuthHeader() },
+      body: JSON.stringify(request),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Frames render error (${res.status}): ${text}`);
+    }
+    return res.json() as Promise<BrowserJobHandle>;
+  }
+}
+
 /**
  * Remote `platform.media.transforms` for development. Each method posts
  * to the dev-server's `/api/media/transforms/*` route and returns the

package/src/transforms.ts

@@ -24,6 +24,43 @@
 // consume this package client-side.
 import { sha256 } from '@noble/hashes/sha2';
 
+// ── Headless-browser + frames-render re-exports ─────────────────────────
+//
+// The contract types live in `@maravilla-labs/types` so the runtime crate
+// and downstream packages (adapter-core, app code) consume one canonical
+// shape. We re-export them through this module so app code that already
+// reaches for `@maravilla-labs/platform/transforms` for media-related
+// helpers also gets the browser / frames request types without a second
+// import.
+//
+// The methods themselves — `platform.env.BROWSER.screenshot(...)`,
+// `.pdf(...)`, `platform.env.FRAMES.render(...)` — are injected by the
+// runtime and typed by the `BrowserClient` / `FramesClient` interfaces
+// (declared in `@maravilla-labs/types`, re-exported below). All three
+// return a `BrowserJobHandle` whose `output_key` equals the
+// caller-supplied `target` storage key; poll status with
+// `platform.media.transforms.job(handle.id)`, then read the rendered
+// bytes from `platform.env.STORAGE`. See `BrowserClient.screenshot` /
+// `BrowserClient.pdf` / `FramesClient.render` for per-method JSDoc with
+// runnable examples; see
+// `docs/recipes/{screenshot-public-url,render-animated-title-card,og-image-from-own-page}.md`
+// for full walkthroughs.
+export type {
+  BrowserClient,
+  BrowserCookie,
+  BrowserJobHandle,
+  BrowserJobStatus,
+  BrowserViewport,
+  BrowserWaitFor,
+  FramesClient,
+  FramesCodec,
+  FramesRenderRequest,
+  PdfPageFormat,
+  PdfRequest,
+  ScreenshotFormat,
+  ScreenshotRequest,
+} from '@maravilla-labs/types';
+
 // ── Types — mirror `crates/platform/src/media/transforms/types.rs` ──────
 
 /** Video container targets supported by v1. */

package/src/types.ts

@@ -741,9 +741,9 @@ export interface Storage {
  * This is the main interface for accessing KV storage, database, and object storage operations.
  */
 export interface PlatformEnv {
-  /** 
+  /**
    * Key-Value storage namespaces. Access different KV namespaces by property name.
-   * 
+   *
    * @example
    * ```typescript
    * const userCache = platform.env.KV.users;
@@ -755,6 +755,19 @@ export interface PlatformEnv {
   DB: Database;
   /** Object/file storage interface */
   STORAGE: Storage;
+  /**
+   * Headless-browser screenshot / PDF render. Returns a job handle
+   * polled via the shared transforms job ledger. Phase 1 plumbing stub —
+   * the worker marks browser jobs `failed("not implemented")` until
+   * Task #2 lands the Chromium pipeline.
+   */
+  BROWSER: BrowserClient;
+  /**
+   * Deterministic HTML → MP4 / WebM render. Path-only: the renderer hits
+   * a route on the tenant's own deployment. Phase 1 plumbing stub —
+   * real implementation in Task #3.
+   */
+  FRAMES: FramesClient;
 }
 
 /**
@@ -805,7 +818,22 @@ export interface PresenceService {
 //
 // `AuthService` is also imported (not just re-exported) because the
 // `Platform` interface below references it within this module's scope.
-import type { AuthService } from '@maravilla-labs/types';
+import type { AuthService, BrowserClient, FramesClient } from '@maravilla-labs/types';
+export type {
+  BrowserClient,
+  FramesClient,
+  BrowserCookie,
+  BrowserJobHandle,
+  BrowserJobStatus,
+  BrowserViewport,
+  BrowserWaitFor,
+  FramesCodec,
+  FramesRenderRequest,
+  PdfPageFormat,
+  PdfRequest,
+  ScreenshotFormat,
+  ScreenshotRequest,
+} from '@maravilla-labs/types';
 export type {
   AuthUser,
   AuthCaller,

package/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts', 'src/config.ts', 'src/push.ts', 'src/events.ts'],
+  entry: ['src/index.ts', 'src/config.ts', 'src/push.ts', 'src/events.ts', 'src/mcp.ts'],
   format: ['esm'],
   dts: true,
   splitting: false,