@hypit/hypit 0.0.1 → 0.1.0

package/packages/audio-track-studio/src/activation.ts

@@ -0,0 +1,7 @@
+import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
+import { audioTrackStudioTrackCompanions } from "./index.js";
+
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createStudioTrackCompanionHostFacet(audioTrackStudioTrackCompanions)],
+};

package/packages/audio-track-studio/src/index.ts

@@ -0,0 +1,72 @@
+import { audioTrackModuleRef, audioTrackTypes } from "@hypit/audio-track";
+import type { AudioTrackProgram } from "@hypit/audio-track";
+import { compositionTypes } from "@hypit/composition";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
+import { artifactPreview, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+
+function projectAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const program = requiredSurfaceValue(context, "program") as AudioTrackProgram;
+  const items = program.items.map((item) => ({
+    id: item.id,
+    subjectId: item.subjectId,
+    startFrame: item.window.startFrame,
+    endFrameExclusive: item.window.endFrameExclusive,
+    stackOrder: Number.MIN_SAFE_INTEGER,
+    sourceTypes: [audioTrackTypes.clipSpec],
+    preview: artifactPreview("audio", item.source.artifact.resource),
+  }));
+  return childEntities(context, items, "audio-clip", "standard").map((entity, index) => {
+    const item = items[index]!;
+    const temporal = temporalLineageFor(context, item.id, "window");
+    const semanticSource = temporalSemanticSource(temporal);
+    return {
+      ...entity,
+      display: { ...entity.display, layers: [previewLayer(item.preview, "waveform")] },
+      ...(semanticSource?.id === undefined
+        ? {}
+        : { markerId: semanticSource.id }),
+      ...(temporal === undefined ? {} : { temporal }),
+    };
+  });
+}
+
+export const audioTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  {
+    id: "track", role: "track",
+    output: { type: compositionTypes.audioTrack, surface: "track", modules: [audioTrackModuleRef] },
+    family: "audio", tone: "green", icon: "waveform",
+    bindings: [
+      { name: "source" },
+      { name: "trim-start", writable: true },
+      { name: "trim-end", writable: true },
+      { name: "playback", writable: true },
+      { name: "min-rate", writable: true },
+      { name: "max-rate", writable: true },
+      { name: "gain", writable: true },
+      { name: "fade-in", writable: true },
+      { name: "fade-out", writable: true },
+    ],
+    inspector: [
+      {
+        binding: "playback", label: "Playback", domain: "how",
+        page: { id: "playback", label: "Playback" }, section: { id: "playback", label: "Playback" },
+        control: "select", options: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"],
+      },
+      ...(["trim-start", "trim-end"] as const).map((binding) => ({
+        binding, label: binding === "trim-start" ? "Trim Start" : "Trim End", domain: "how" as const,
+        page: { id: "playback", label: "Playback" }, section: { id: "trim", label: "Trim" }, control: "text" as const,
+      })),
+      ...(["min-rate", "max-rate", "gain"] as const).map((binding) => ({
+        binding, label: binding === "min-rate" ? "Minimum Rate" : binding === "max-rate" ? "Maximum Rate" : "Gain",
+        domain: "how" as const, page: { id: "mix", label: "Mix" }, section: { id: "mix", label: "Mix" },
+        control: "number" as const,
+      })),
+      ...(["fade-in", "fade-out"] as const).map((binding) => ({
+        binding, label: binding === "fade-in" ? "Fade In" : "Fade Out", domain: "when" as const,
+        page: { id: "fade", label: "Fade" }, section: { id: "fade", label: "Fade" }, control: "text" as const,
+      })),
+    ],
+    requiredValues: ["program"], project: projectAudio,
+    lane: { heightPx: 48 },
+  },
+];

package/packages/author-kit/README.md

@@ -0,0 +1,31 @@
+# `@hypit/hypit/author-kit`
+
+Small public framework API for an Author Package.
+
+It joins four stable authoring boundaries: nominal Module declarations, deterministic component
+handlers, sealed Graph Fragments and Markup Surface handlers. Domain facts still come from their
+owners—for example `@hypit/composition`, `@hypit/semantic-track` and `@hypit/spatial`. This package
+does not re-export the video vocabulary or turn those packages into one central object.
+
+`@hypit/hypit/author-kit` contains no registry, package search, installer, Runtime, Provider or Studio
+selection. Importing it makes no component visible. A project's Source explicitly selects an
+installed Author Package; the Host then consumes only the contribution exported by that package's
+declared activation entry.
+
+An external Author Package normally has one development dependency on the released `@hypit/hypit`
+Distribution. It imports this boundary from `@hypit/hypit/author-kit` and the relevant domain owners from
+subpaths such as `@hypit/hypit/composition`, compiles its activation to JavaScript, and publishes only its
+own built files and assets. At execution time the active Hypit Distribution supplies those exact
+public subpaths. This keeps one framework implementation in the process and prevents a component
+tarball from carrying private copies of Core.
+
+The Distribution includes the small package example at
+[`examples/minimal-author-package/packages/example-component`](../../examples/minimal-author-package/packages/example-component).
+Copy it into the video's `packages/`, give it the owner's package and Module name, and follow its
+README to select the installed Hypit release as its development dependency. It includes the Manifest,
+Surface, Fragment, Producer, activation, preview and TypeScript build configuration. It can stay in
+the project or be packed and installed in another project without changing its logical Module import.
+
+For a component that follows speech, [Ranking](../ranking/README.md) traces the complete semantic
+path from a Selection or Moment through projection, schedule and drawing to a Studio Companion.
+Its implementation illustrates those relationships; a new component owns its own visual behavior.

package/packages/author-kit/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@hypit/author-kit",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/author-kit/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Stable framework-facing author-package surface.
+ *
+ * Domain values stay with their owning packages; this module only joins the small set of framework
+ * interfaces needed to declare a Module, lower a Surface into a Fragment and provide deterministic
+ * handlers. It performs no discovery, registration, installation or execution.
+ */
+export {
+  canonicalize,
+  isResourceId,
+  sameType,
+} from "@hypit/protocol";
+export type {
+  BlobRef,
+  CanonicalValue,
+  ModuleManifest,
+  ModuleRef,
+  ProducerRef,
+  StoredValue,
+  TypeRef,
+  TypedRecord,
+  ValueSchema,
+} from "@hypit/protocol";
+
+export type {
+  ComponentPackage,
+  ProducerFacet,
+  ProducerHandler,
+  ProducerHandlerContext,
+  ProducerHandlerResult,
+  TypeValidatorFacet,
+  TypeValidatorHandler,
+} from "@hypit/component-kit";
+
+export {
+  sealGraphFragment,
+} from "@hypit/elaborator";
+export type {
+  FragmentOperation,
+  GraphFragment,
+} from "@hypit/elaborator";
+
+export {
+  assertAttributes,
+  assertEmptyElement,
+  assertExactAttributes,
+  createMarkupSurfaceHostFacet,
+  localName,
+  optionalTextAttribute,
+  textAttribute,
+} from "@hypit/markup";
+export type {
+  MarkupSurfaceHostFacetOptions,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceComponentDraft,
+  SurfaceRecordDraft,
+  SurfaceResolvedReference,
+} from "@hypit/markup";

package/packages/background-removal/README.md

@@ -0,0 +1,29 @@
+# @hypit/background-removal
+
+Declares one external image capability: turn an input image into an image with its background removed.
+Use it for a product, portrait or graphic that will be composited over another picture.
+
+```xml
+<import as="remove" from="@hypit/background-removal@1"/>
+<remove:Background id="cutout" source={portrait.image}/>
+```
+
+`source` accepts an image BlobArtifact, including an ordinary image file declaration or a generated
+image Output. `{cutout.image}` publishes one image BlobArtifact with transparency. Keep its actual
+dimensions when placing it in Media Track, or use Image Compose when a flattened still is wanted.
+
+The package declares the visual operation; the selected Endpoint implements it. The existing
+`@hypit/provider-kie` route uses
+[KIE Recraft Remove Background](https://docs.kie.ai/market/recraft/remove-background), sending
+`model: "recraft/remove-background"` and `input.image`. It follows the ordinary submit, poll and
+collect lifecycle and expects one image result. Another Provider can fulfill the same capability
+without changing the Source. This operation therefore needs no separate Recraft-specific author
+Model to use the existing KIE implementation.
+
+For a moving portrait, [Volcengine Matting](../volcengine-matting/README.md) provides
+`<matte:Portrait source={performance.video}/>` through HypiHub. Normalize its processed video
+before using it in a track.
+
+This capability handles still images. Moving-person background removal requires a video-capable
+operation and a result that preserves the changing silhouette and frame correspondence. Removing
+one portrait's background does not remove the background of a subsequently generated performance.

package/packages/background-removal/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@hypit/background-removal",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": { ".": "./src/index.ts" },
+  "hypit": { "activation": "./src/activation.ts" },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

package/packages/background-removal/src/activation.ts

@@ -0,0 +1,18 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  backgroundRemovalComponent, backgroundRemovalManifest,
+  backgroundRemovalModuleRef, decodeBackgroundRemovalSurface,
+  backgroundRemovalMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: backgroundRemovalManifest }],
+  components: [backgroundRemovalComponent],
+  hostFacets: [{ ...createMarkupSurfaceHostFacet({
+    module: backgroundRemovalModuleRef,
+    declaration: backgroundRemovalMarkupSurfaces.find((item) => item.name === "background")!, handler: decodeBackgroundRemovalSurface,
+  }) }],
+};
+export default hypitPackage;

package/packages/background-removal/src/component.ts

@@ -0,0 +1,32 @@
+import { plannedNeedInputs } from "@hypit/component-kit";
+import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+
+import { backgroundRemovalCapabilities, backgroundRemovalProducers } from "./manifest.js";
+import { backgroundRemovalRequest } from "./program.js";
+
+function blob(value: StoredValue | undefined) {
+  if (value?.kind !== "blob") throw new Error("Background Removal source must be a Blob Artifact.");
+  return value;
+}
+
+export const backgroundRemovalComponent = {
+  producers: [{
+    producer: backgroundRemovalProducers.request,
+    handler: ({ inputs }: ProducerHandlerContext) => ({
+      outputs: {}, needs: { image: backgroundRemovalRequest(blob(inputs.source?.value)) },
+    }),
+  }],
+  plannedNeeds: [{
+    producer: backgroundRemovalProducers.request,
+    port: "image",
+    capability: backgroundRemovalCapabilities.remove,
+    plan: ({ state, step }) => ({
+      constraints: {},
+      pendingInputs: plannedNeedInputs(state, step, { source: "image" }),
+    }),
+    present: (specification) => ({ fields: {}, references: {
+      image: specification.pendingInputs.filter((input) => input.role === "image").length,
+    } }),
+  }],
+} satisfies ComponentPackage;

package/packages/background-removal/src/fragment.ts

@@ -0,0 +1,18 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGraphFragment } from "@hypit/elaborator";
+
+import { backgroundRemovalProducers } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export const backgroundRemovalFragment = sealGraphFragment({
+  inputs: [{ name: "source", type: artifactTypes.blob }],
+  operations: [{
+    id: "image:remove-background", producer: backgroundRemovalProducers.request,
+    inputs: { source: input("source") }, result: { kind: "need", name: "image" },
+  }],
+  exports: [{
+    name: "image", type: artifactTypes.blob, root: operation("image:remove-background"),
+  }],
+});

package/packages/background-removal/src/index.ts

@@ -0,0 +1,6 @@
+export { backgroundRemovalComponent } from "./component.js";
+export { backgroundRemovalFragment } from "./fragment.js";
+export { backgroundRemovalCapabilities, backgroundRemovalDependency, backgroundRemovalManifest, backgroundRemovalMarkupSurfaces, backgroundRemovalModuleRef, backgroundRemovalProducers } from "./manifest.js";
+export { assertBackgroundRemovalRequest, backgroundRemovalRequest } from "./program.js";
+export { decodeBackgroundRemovalSurface } from "./surface.js";
+export type * from "./types.js";

package/packages/background-removal/src/manifest.ts

@@ -0,0 +1,45 @@
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import type { CapabilityRef, ModuleManifest, ProducerRef } from "@hypit/protocol";
+
+export const backgroundRemovalModuleRef = { name: "@hypit/background-removal", version: "1" } as const;
+export const backgroundRemovalCapabilities = {
+  remove: { module: backgroundRemovalModuleRef, name: "remove-background" },
+} satisfies Record<string, CapabilityRef>;
+export const backgroundRemovalProducers = {
+  request: { module: backgroundRemovalModuleRef, name: "request-background-removal" },
+} satisfies Record<string, ProducerRef>;
+
+export const backgroundRemovalMarkupSurfaces = [{
+    name: "background", tag: "Background", mode: "structured", outputs: [artifactTypes.blob],
+    vocabulary: {
+      summary: "Removes the background from one image Artifact and publishes the cut-out image.",
+      attributes: [
+        { name: "id", kind: "identifier", required: true,
+          summary: "Names this removal so its image can be referenced elsewhere in the Source." },
+        { name: "source", kind: "reference", required: true, accepts: [artifactTypes.blob],
+          summary: "Chooses the image whose background is removed." },
+      ],
+      ports: [
+        { name: "image", type: artifactTypes.blob,
+          summary: "The source image with its background removed." },
+      ],
+      example: `<remove:Background id="cutout" source={portrait.image}/>`,
+      notes: [
+        "The element is empty; it accepts no children and no text.",
+        "The package chooses no model, threshold or storage — the selected Endpoint fulfills the capability.",
+      ],
+    },
+  }] as const;
+
+
+export const backgroundRemovalManifest: ModuleManifest = {
+  format: "hypit.module@1", name: backgroundRemovalModuleRef.name, version: backgroundRemovalModuleRef.version,
+  dependencies: [artifactDependency], types: [],
+  capabilities: [{ name: backgroundRemovalCapabilities.remove.name, returns: artifactTypes.blob }],
+  producers: [{
+    name: backgroundRemovalProducers.request.name,
+    inputs: [{ name: "source", type: artifactTypes.blob }], outputs: [],
+    needs: [{ name: "image", capability: backgroundRemovalCapabilities.remove, returns: artifactTypes.blob }],
+  }],
+};
+export const backgroundRemovalDependency = { module: backgroundRemovalModuleRef } as const;

package/packages/background-removal/src/program.ts

@@ -0,0 +1,19 @@
+import { canonicalize, isResourceId } from "@hypit/protocol";
+
+import type { BackgroundRemovalRequest } from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function assertBackgroundRemovalRequest(value: BackgroundRemovalRequest): void {
+  assert(value.source.kind === "blob" && isResourceId(value.source.resource)
+    && Number.isSafeInteger(value.source.size) && value.source.size >= 0
+    && value.source.mediaType.startsWith("image/"), "Background Removal source must be an image Blob Artifact.");
+}
+
+export function backgroundRemovalRequest(source: BackgroundRemovalRequest["source"]): BackgroundRemovalRequest {
+  const value = { source };
+  assertBackgroundRemovalRequest(value);
+  return canonicalize(value) as unknown as BackgroundRemovalRequest;
+}

package/packages/background-removal/src/surface.ts

@@ -0,0 +1,27 @@
+import { artifactTypes } from "@hypit/artifact";
+import type { StructuredSurfaceHandler, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
+
+import { backgroundRemovalFragment } from "./fragment.js";
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+export const decodeBackgroundRemovalSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  const unknown = Object.keys(element.attributes).filter((name) => !["id", "source"].includes(name));
+  if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}.`);
+  if (element.children.some((child) => child.kind === "element" || child.value.trim())) throw new Error(`${element.name} must be empty.`);
+  const id = element.attributes.id;
+  if (typeof id !== "string" || !id.trim()) throw new Error(`${element.name}.id must be text.`);
+  const raw: MarkupAttributeValue | undefined = element.attributes.source;
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.source must be a reference.`);
+  const source = resolveReference(raw.path);
+  if (source === undefined || !sameType(source.type, artifactTypes.blob)) throw new Error(`${element.name}.source must be a Blob Artifact.`);
+  return {
+    records: [], fragments: [backgroundRemovalFragment],
+    components: [{
+      id: id.trim(), fragment: backgroundRemovalFragment.id, inputs: { source: source.ref },
+      outputs: { image: `${id.trim()}.image` }, range: element.range,
+    }],
+  };
+};

package/packages/background-removal/src/types.ts

@@ -0,0 +1,5 @@
+import type { BlobRef } from "@hypit/protocol";
+
+export type BackgroundRemovalRequest = {
+  readonly source: BlobRef;
+};

package/packages/browser-capture/README.md

@@ -0,0 +1,82 @@
+# `@hypit/browser-capture`
+
+Browser material capture for websites and authored HTML. The package owns browser lifecycle and file
+capture; the task owns navigation, page state and the material worth showing. It imports Puppeteer Core,
+the upstream browser installer and Sharp directly and has no dependency on Hypit Core, Runtime,
+Providers or graph types.
+
+The Distribution supplies `hypit capture screenshot` and `hypit capture run`. See `hypit capture --help`
+for command options. Puppeteer Core is a pinned Distribution dependency, so a plain video project
+needs no browser-library installation or private `node_modules` import path.
+`hypit capture install-browser` explicitly prepares the package's tested Chrome for Testing revision
+in the browser cache (`PUPPETEER_CACHE_DIR`, or `~/.cache/puppeteer`).
+`captureBrowserExecutablePath()` reports that path.
+The package pins Chrome 153.0.8010.12 for the native recording API; `installCaptureBrowser()` uses
+the upstream installer. Existing compatible browsers remain selectable through launch options.
+
+## Library
+
+`withCapture(options, task, onOutput?)` opens a browser, calls the async task, finishes open recordings
+and closes the browser. It returns every completed `CaptureOutput`; `onOutput` receives each saved
+file as it finishes. A task failure closes the browser while preserving earlier completed files.
+
+`CaptureOptions` accepts:
+
+- `launch`: ordinary Puppeteer `LaunchOptions`. The default viewport is 1280 × 720 at device scale 1;
+  `defaultViewport` replaces it. `channel` selects an installed Chrome channel, `executablePath`
+  selects a specific executable, and the default uses this package's tested Chrome for Testing.
+  `PUPPETEER_CACHE_DIR` selects the cache directory.
+- `timeoutMs`: operation and navigation timeout for the initial page. Omission keeps Puppeteer's
+  default; `0` disables that timeout. Scripts can configure other pages themselves.
+- `ffprobePath`: metadata reader for finished recordings; defaults to `ffprobe` on `PATH`.
+
+The task receives the ordinary Puppeteer `browser` and `page`, plus:
+
+```ts
+await screenshot({ path: "assets/screen.png", fullPage: true });
+await screenshot({ path: "assets/card.png", selector: "#card", omitBackground: true });
+const recording = await record({ path: "assets/demo.mp4", fps: 30 });
+// Perform this task's page interactions.
+const video = await recording.stop();
+```
+
+`screenshot` accepts Puppeteer's `ScreenshotOptions` with required `path`, no `encoding`, and optional
+`selector`. Selectors use Puppeteer syntax and wait for a visible element. Element, rectangular clip
+and full-page capture are separate choices. Dimensions come from the saved bytes, including device
+scale. PNG, JPEG and WebP follow Puppeteer's screenshot support.
+
+`record` accepts Puppeteer's native `RecordOptions` with required `path`, excluding `overwrite`.
+It uses `Page.record` on Chrome 153 or later. Chrome produces MP4; use an `.mp4` destination.
+`audio: true` includes page audio; the default is picture only. `fps` / `frameRate` specify the maximum
+capture rate, and `maxWidth` / `maxHeight` constrain output dimensions. These options pass through
+to Puppeteer. The helper defaults those upper bounds to the viewport's device-pixel dimensions.
+Chrome determines the recorded dimensions; device scale can enlarge a screenshot without enlarging
+the recording. Use the returned `width` and `height` for placement. No FFmpeg encoder is involved;
+`ffprobe` reads the completed file's actual dimensions,
+duration, frame rate and audio presence. `stop()` is idempotent and waits for the file to finish.
+
+Both functions accept an optional second `Page` argument for scripts using several pages. Returning
+finishes recordings started through `record`. Ordinary Puppeteer methods remain available; files
+written directly by a script are outside the helper's output list and overwrite behavior.
+
+Outputs include absolute `path`, `kind`, `url`, `width`, `height`, `format`, plus `duration`, `frameRate`
+and `hasAudio` for video when available. Helpers refuse overwrites; a failed capture removes only its
+own incomplete output. The CLI prints completed paths as work progresses; `--json` returns the
+complete output list as `hypit.capture@1`.
+
+## Project scripts
+
+A `.mjs` file exports a default async function receiving the session plus `args` and `log`.
+`hypit capture run task.mjs -- <arguments>` forwards arguments after `--` unchanged. `log` writes
+progress separately from JSON output. Optional `export const options` supplies `CaptureOptions`;
+explicit CLI browser options override it. Relative output paths follow the working directory, while
+`import.meta.url` can locate inputs beside the script. These are ordinary Node.js scripts with the
+caller's permissions.
+
+Waiting for lazy content, choosing a device profile, authentication and interacting with banners
+belong in those scripts through normal Puppeteer APIs. A simple screenshot waits for page load;
+`--wait-for` and `--wait-ms` add an authored readiness condition. The package does not interpret
+websites or silently rewrite page content.
+
+For a library import in an installed Distribution, use `@hypit/hypit/browser-capture`. The workspace package
+also exports the same API as `@hypit/browser-capture`.

package/packages/browser-capture/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hypit/browser-capture",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@puppeteer/browsers": "3.2.2",
+    "puppeteer-core": "25.10.0",
+    "sharp": "0.35.3"
+  }
+}

package/packages/browser-capture/src/browser.ts

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Browser, computeExecutablePath, install } from "@puppeteer/browsers";
+
+// Page.record uses Chrome's native recording protocol, introduced in Chrome 153.
+// This package owns its tested browser revision independently of other renderers.
+const chromeVersion = "153.0.8010.12";
+
+const cacheDirectory = () => process.env.PUPPETEER_CACHE_DIR ?? join(homedir(), ".cache", "puppeteer");
+
+export async function captureBrowserExecutablePath(): Promise<string> {
+  return computeExecutablePath({ browser: Browser.CHROME, buildId: chromeVersion, cacheDir: cacheDirectory() });
+}
+
+/** Explicit setup, using Puppeteer's cache configuration and upstream browser installer. */
+export async function installCaptureBrowser(): Promise<string> {
+  const installed = await install({ browser: Browser.CHROME, buildId: chromeVersion, cacheDir: cacheDirectory() });
+  return installed.executablePath;
+}