@oeave/bakery3 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,975 @@
+import { Scene, Camera, Texture, Object3D } from 'three';
+import { E as EnvironmentSpec, S as SceneManifest, V as Vec3, d as CompatibilityReport, j as BakeBundle, M as MaterialShaderSpec, k as ShaderSlot, h as CompatibilityIssue, Q as QualityPreset, O as OutputSpec, R as RenderSpec } from './bake-DZ-CJR6f.js';
+export { a as BakeQuality, i as BakeSettings, l as BakeSkip, e as BakeSpec, B as BakeTextureSize, m as BakeUv, n as BakedObject, F as FrameSequenceIndex, o as OutputFormat, p as ShaderGraph, q as ShaderGraphNode } from './bake-DZ-CJR6f.js';
+export { a as AnimationChannel, A as AnimationSpec, b as AnimationTarget } from './animation-B1h0Ryvj.js';
+import { y as AssetDescriptor, z as RenderState, D as RenderError, d as Bakery3Client, e as RenderRecord, v as RenderResult, c as Bakery3Error, C as CostEstimate, B as BatchProgress, E as BakeRecord, G as BakeResult, j as RenderSet, V as VariantsQuote, T as TestRunOptions, f as BatchOpenRequest, b as Batch, H as ClientOptions } from './testRun-20OARnQr.js';
+export { I as Bakery3ErrorCode, J as BatchAction, k as BatchAddRequest, l as BatchAddResponse, K as BatchCost, L as BatchCounts, m as BatchExportLine, n as BatchItemOutcome, o as BatchItemRecord, p as BatchItemRequest, q as BatchItemsPage, r as BatchPageRefused, a as BatchRecord, M as BatchState, N as BudgetedKind, O as ClientAuth, F as FlushOptions, P as MintedToken, R as Recorded, x as RenderBudgetExceeded, Q as RenderBudgetInit, s as RenderSetFailure, t as RenderSetImage, S as RenderSetRefusal, U as RenderSetRefused, i as RetryPolicy, w as TokenProvider, u as WaitOptions } from './testRun-20OARnQr.js';
+import { d as TrackTarget, T as Timeline, a as TimelineOptions } from './timeline-ChwgD7bT.js';
+export { A as AuthoredValue, E as Easing, K as Keyframe, O as OrbitOptions, P as PushSpec, S as SegmentOptions, e as TimelineEvent, f as TimelineJSON, b as Track, c as createTimeline } from './timeline-ChwgD7bT.js';
+import { P as PrepareBakeSettings } from './prepare-BtjY4G3q.js';
+export { B as BakeSimplifyInput } from './prepare-BtjY4G3q.js';
+
+/**
+ * What leaves the browser: a scene as one GLB plus a manifest.
+ *
+ * The SDK reads the live scene graph and writes one binary and one small
+ * manifest. The manifest holds everything glTF cannot say (camera, lights,
+ * color management, the environment, shader graphs, the compatibility report)
+ * and names every asset by its sha256. The only URL a manifest may carry is a
+ * preset environment on the preset library.
+ *
+ * Nothing here changes the caller's scene beyond the id stamps, and those are
+ * removed in a `finally`: a render must be invisible to the application that
+ * asked for it.
+ */
+
+/**
+ * What a capture is made from.
+ *
+ * By the time an HDRI is on `scene.environment` it has usually been through
+ * PMREM and is a GPU render target: the original equirectangular pixels are
+ * gone, and reading them back would give a blurred cubemap rather than the
+ * map the renderer wants. So the SDK asks to be told once, at load:
+ *
+ *     const hdri = await new RGBELoader().loadAsync('/studio.hdr');
+ *     rememberEnvironmentSource(hdri, '/studio.hdr');
+ *
+ * `@oeave/bakery3/r3f` does this automatically for drei's `<Environment files>`.
+ * Without it the render still happens; it falls back to the flat ambient term
+ * and says so in the compatibility report rather than guessing.
+ */
+type CaptureOptions = {
+    scene: Scene;
+    camera: Camera;
+    renderer?: {
+        outputColorSpace?: string;
+        toneMapping?: number;
+        toneMappingExposure?: number;
+    };
+    /**
+     * An HDRI to light with, when the SDK cannot recover the one in the scene.
+     * A URL the page can fetch, or the file's bytes.
+     */
+    environment?: string | ArrayBuffer;
+    /** Opaque application state, stored with the render. Never rendered. */
+    productState?: Record<string, unknown>;
+    /** Override the transparent-background default. */
+    background?: EnvironmentSpec['background'];
+};
+type CapturedScene = {
+    manifest: SceneManifest;
+    /** Every blob this manifest refers to, ready to be hashed against storage. */
+    assets: Array<AssetDescriptor & {
+        bytes: number;
+        data: ArrayBuffer;
+    }>;
+};
+
+/**
+ * gsap and Theatre.js, without a dependency on either.
+ *
+ * The adapters sample through, they do not translate. Neither library's eases
+ * are parsed, no plugin surface is reimplemented, nothing is inspected beyond
+ * "can this thing be told to go to time t". The adapter seeks the foreign
+ * timeline frame by frame and writes down where the named objects ended up.
+ *
+ * That is a trade. It loses the ability to re-time the result later, and it
+ * wins exactness: whatever gsap does (a custom ease, a stagger, a plugin
+ * nobody here has heard of) is what gets rendered, because the numbers came
+ * out of gsap itself.
+ *
+ * Both return a plain `Timeline`, so the panel, `seek()` and `renderVideo()`
+ * do not know or care where the motion came from.
+ */
+
+/** One property of one object to record. `'camera'` is allowed and behaves
+ *  the way it does everywhere else in the timeline. */
+type SampledTrack = {
+    object: TrackTarget;
+    property: string;
+    label?: string;
+};
+type AdapterOptions = {
+    /** Sampling rate. Also the timeline's own fps unless overridden at bake. */
+    fps?: number;
+    /** Seconds. Required when the foreign timeline cannot report its own. */
+    duration?: number;
+    /**
+     * What to record. Required, and there is no "everything" option: the adapter
+     * cannot ask gsap what it animates without reimplementing gsap, so a list it
+     * guessed would be a video quietly missing whatever was not guessed.
+     */
+    tracks: SampledTrack[];
+    /** Needed for any camera track: the pose is read off the live camera at
+     *  each sampled frame, not out of the source timeline. */
+    camera?: Camera;
+    scene?: Scene;
+};
+/**
+ * A gsap timeline or tween.
+ *
+ * `seek(t, suppressEvents)` is gsap 3's API; `time(t)` is the older shape and
+ * is still what a few wrappers expose, so both are tried. Events are
+ * suppressed where the library allows it: sampling should not fire your
+ * `onUpdate` two hundred times.
+ */
+declare function timelineFromGsap(gsapTimeline: unknown, options: AdapterOptions): Timeline;
+/**
+ * A Theatre.js sequence (`sheet.sequence`).
+ *
+ * Theatre drives time by assignment (`sequence.position = t`) rather than by a
+ * method, and reports its length on `.length` when the project defines one.
+ */
+declare function timelineFromTheatre(sequence: unknown, options: AdapterOptions): Timeline;
+
+type JobEvents = {
+    queued: {
+        render: RenderRecord;
+    };
+    preparing: {
+        render: RenderRecord;
+    };
+    preview: {
+        url: string;
+        render: RenderRecord;
+    };
+    progress: {
+        percent: number;
+        state: RenderState;
+        render: RenderRecord;
+    };
+    complete: {
+        result: RenderResult;
+        render: RenderRecord;
+    };
+    failed: {
+        error: Bakery3Error;
+        render: RenderRecord;
+    };
+    cancelled: {
+        render: RenderRecord;
+    };
+};
+/** How long to wait for a job, and when to stop waiting. */
+type JobResultOptions = {
+    /**
+     * Stops this wait: the promise rejects with the signal's reason. The job
+     * keeps polling while anything else still waits on it or listens to it,
+     * and the render itself is not cancelled.
+     */
+    signal?: AbortSignal;
+};
+/** What every job's record has: a render's and a bake's alike. */
+type JobRecord = {
+    id: string;
+    state: RenderState;
+    progress: number;
+    result?: unknown;
+    error?: RenderError;
+};
+/**
+ * The polling, the events and the waiting that a render job and a bake job
+ * share. Not public API: `RenderJob` and `BakeJob` are.
+ *
+ * Polling starts on the first `on()` or `result()`, and stops when the job
+ * ends, when `stop()` is called, or when nothing is waiting on it or
+ * listening to it any more (a later `on()` or `result()` picks it up again).
+ */
+declare abstract class PolledJob<R extends JobRecord, Out, E extends {
+    failed: unknown;
+    cancelled: unknown;
+}> {
+    readonly id: string;
+    protected record: R;
+    protected readonly client: Bakery3Client;
+    private readonly subscribers;
+    /** The last payload of each replayed event, for a listener added late. */
+    private readonly lastPayloads;
+    private pending;
+    /** `result()` calls still waiting. */
+    private waiting;
+    /** The running poll loop's switch, or null when no loop runs. */
+    private poller;
+    /** Set once the job has settled, for good: a terminal state or a verdict. */
+    private hasEnded;
+    /** "render" or "bake", for messages. */
+    protected abstract readonly jobNoun: 'render' | 'bake';
+    protected abstract readonly pollSchedule: readonly number[];
+    /** Events a late listener is handed the latest of. */
+    protected abstract readonly replayedEvents: ReadonlyArray<keyof E>;
+    /** One poll. */
+    protected abstract readRecord(signal: AbortSignal): Promise<R>;
+    /** The events a new record raises before any terminal handling. */
+    protected abstract observeRecord(record: R): void;
+    /** A completed record into its output; emits `complete`. May throw. */
+    protected abstract completeRecord(record: R): Promise<Out>;
+    /** The record under the payload's own name: `{ render }` or `{ bake }`. */
+    protected abstract recordPayload(record: R): object;
+    constructor(client: Bakery3Client, record: R);
+    get status(): RenderState;
+    get progress(): number;
+    /**
+     * Listen for an event. Starts polling if nothing has yet.
+     *
+     * A listener added after an event already fired is called with the latest
+     * one, on the next microtask: the latest `preview` and `progress`, and
+     * `complete`, `failed` or `cancelled` once the job has ended. Returns the
+     * unsubscribe function, so a React effect can clean up without a second
+     * API.
+     */
+    on<K extends keyof E>(event: K, listener: (payload: E[K]) => void): () => void;
+    /**
+     * The finished output. Starts polling if nothing has yet.
+     *
+     * Several callers may await the same job (a component, a devtools panel,
+     * an analytics hook) and share one polling loop. Rejects with a
+     * `Bakery3Error` when the job fails (after `failed` is emitted), with code
+     * `Cancelled` when it was cancelled, and with an `AbortError` when the wait
+     * was stopped by `stop()` or by `signal`.
+     */
+    result(options?: JobResultOptions): Promise<Out>;
+    /**
+     * Stop polling, here, now. The job is NOT cancelled on the server: it
+     * keeps running and is still charged, and `getRender(id)` or `getBake(id)`
+     * reads it later. A pending `result()` rejects with an `AbortError`, and a
+     * later `on()` or `result()` starts polling again.
+     *
+     * `cancel()` is the other one: it asks the server to stop the job, which
+     * then ends as `cancelled`.
+     */
+    stop(): void;
+    /** Apply a record read from the API, and settle if it is the last one. */
+    protected applyRecord(record: R): void;
+    protected emitEvent<K extends keyof E>(event: K, payload: E[K]): void;
+    private pendingOutcome;
+    private isWatched;
+    private startPolling;
+    private pollLoop;
+    /** Settle on the record's terminal state. Once. */
+    private settleEnd;
+    /** Emit `failed`, then reject. Every failure goes through here. */
+    private settleFailure;
+    private expiredError;
+}
+declare class RenderJob extends PolledJob<RenderRecord, RenderResult, JobEvents> {
+    protected readonly jobNoun = "render";
+    protected readonly pollSchedule: number[];
+    protected readonly replayedEvents: ReadonlyArray<keyof JobEvents>;
+    private previewSeen;
+    private lastState;
+    constructor(client: Bakery3Client, record: RenderRecord);
+    get previewUrl(): string | undefined;
+    /** The estimate this render was accepted under. */
+    get estimate(): CostEstimate | undefined;
+    /**
+     * Ask the server to stop the render. It ends as `cancelled`: `cancelled`
+     * is emitted and `result()` rejects with code `Cancelled`. To stop
+     * watching without stopping the render, call `stop()`.
+     */
+    cancel(): Promise<void>;
+    protected readRecord(signal: AbortSignal): Promise<RenderRecord>;
+    protected observeRecord(record: RenderRecord): void;
+    protected completeRecord(record: RenderRecord): Promise<RenderResult>;
+    protected recordPayload(record: RenderRecord): {
+        render: RenderRecord;
+    };
+}
+
+/**
+ * Upload only what the service does not already have.
+ *
+ * The whole flow, and the reason a second render feels instant:
+ *
+ *     hash locally  ->  which of these exist?  ->  PUT only the misses
+ *
+ *     First render   Uploaded: 148 MB
+ *     Camera moves   Uploaded: 2 KB
+ *     Texture change Uploaded: 6 MB
+ *
+ * Bytes go from the browser to object storage directly, on a presigned PUT.
+ * The control plane never touches them, so the upload runs as fast as the
+ * developer's connection allows.
+ */
+
+type UploadProgress = {
+    /** Assets that were already in storage: the cache hit. */
+    cached: number;
+    /** Assets uploaded this time. */
+    uploaded: number;
+    bytesUploaded: number;
+    bytesTotal: number;
+};
+
+/**
+ * One capture, many pictures: the pure pieces.
+ *
+ * A capture is one GLB with every finish inside it and a few KB of manifest.
+ * A picture of it is that manifest with another camera and another hidden
+ * list, and nothing else. `render({ cameras })`, `renderVariants()` and the
+ * catalog recorder all build their items from these, and they are exported
+ * from `@oeave/bakery3/catalog` so a recorder that writes `manifests.jsonl`
+ * instead of submitting builds exactly the same ones.
+ */
+
+type CatalogCamera = {
+    id: string;
+    position: Vec3;
+    target: Vec3;
+    /** Vertical field of view in degrees, as `PerspectiveCamera.fov`. */
+    fov: number;
+};
+type CatalogFinish = {
+    id: string;
+    /** Object names this finish shows. Anything another finish claims and this
+     *  one does not is hidden; anything no finish claims stays as it is. */
+    show: string[];
+};
+
+/**
+ * Many pictures from one call.
+ *
+ *     // every camera of the scene you have
+ *     const shots = await bakery3.render({ cameras: ['hero', 'front', 'detail'] });
+ *     const images = await shots.result();
+ *
+ *     // every variant, from every camera
+ *     const run = await bakery3.renderVariants({
+ *       key: 'fall-2026',
+ *       variants: products,
+ *       apply: (product) => configurator.show(product),
+ *       cameras: ['hero', 'front', 'detail'],
+ *       maxCost: 600,
+ *     });
+ *     await run.wait();
+ *     for await (const image of run.images()) save(image.variant, image.camera, image.url);
+ *
+ * Both record into a batch and hand back a `RenderSet`, so a set of three
+ * and a catalog of six thousand are the same object with the same
+ * guarantees: one ceiling for all of it, one poll for all of it, and a
+ * re-run that adopts what already rendered.
+ *
+ * What this file is careful about is the customer's machine. A catalog is
+ * recorded in a browser tab, and a tab that holds two hundred products, or
+ * two hundred exported GLBs, or six thousand result records, is a tab that
+ * dies at product 140 with nothing to show for it. So:
+ *
+ * - One variant resident. A variant is applied, captured, uploaded, turned
+ *   into items, flushed and let go of before the next is touched. The
+ *   exported GLB is the largest thing a run holds, and it holds one.
+ * - The list need not exist. `variants` is any iterable or async iterable: a
+ *   generator, a database cursor, a paged fetch. It is pulled one at a time
+ *   and never collected.
+ * - One capture, many pictures. Cameras and finishes multiply items, not
+ *   exports: each is the same few-KB manifest with another camera and
+ *   another hidden list (`variant.ts`).
+ * - Nothing uploads twice. Assets are content addressed; a variant that
+ *   changed no geometry uploads nothing, and one whose hashes this run has
+ *   already sent does not even ask.
+ * - Results are walked, not held. `images()` and `failures()` read the
+ *   ledger a page at a time by cursor. `result()` collects, and says so: it
+ *   is for a handful of cameras.
+ */
+
+/**
+ * A camera to photograph from:
+ *
+ * - a **name**: a camera in the scene with that `name`. Looked up again for
+ *   every variant, after `apply`, so a camera that ships inside a product's
+ *   own GLB, or rides a rig the variant moves, is read where it then stands.
+ * - a **Camera**: read as it stands at capture. Its `name` is its id.
+ * - a **declaration**: `{ id, position, target, fov }`, for a shot no camera
+ *   object exists for. Its aspect is the output's.
+ */
+type ViewCamera = string | Camera | CatalogCamera;
+/** What `apply` may hand back: how to undo it. Called before the next variant, and when a run stops. */
+type VariantCleanup = () => void | Promise<void>;
+type VariantProgress = BatchProgress & {
+    /** The variant just recorded. */
+    variant: string;
+    /** Variants recorded so far, this one included. */
+    variants: number;
+    /** Pictures recorded so far: variants × finishes × cameras. */
+    images: number;
+    /** What this variant's capture uploaded. Usually nothing after the first. */
+    upload?: UploadProgress;
+};
+
+declare function rememberEnvironmentSource(texture: Texture, source: string | ArrayBuffer, options?: {
+    preset?: boolean;
+}): void;
+
+/**
+ * The compatibility checker.
+ *
+ * three.js can express things the renderer cannot reproduce faithfully. Those
+ * are never rendered gray in silence: an unsupported material produces a
+ * named, located, actionable issue, and the developer decides.
+ *
+ * It runs entirely in the page and costs nothing, so "will my scene work?"
+ * can be answered before creating an account.
+ */
+
+type AnalyzeResult = CompatibilityReport & {
+    /** Triangles the exporter will write. Feeds the size warning and estimate. */
+    triangles: number;
+    /** Distinct textures found, and their largest dimension. */
+    textures: {
+        count: number;
+        maxDimension: number;
+    };
+    /** Distinct materials that emit light; see `SceneManifest.stats.emitters`. */
+    emitters: number;
+};
+declare function analyzeScene(root: Object3D): AnalyzeResult;
+
+/** What `await job.result()` gives back. */
+type BakeOutput = Omit<BakeResult, 'summary'> & {
+    /** The full bundle, uv arrays included, with every uri already a URL. */
+    bundle: BakeBundle;
+};
+type BakeJobEvents = {
+    queued: {
+        bake: BakeRecord;
+    };
+    progress: {
+        percent: number;
+        state: RenderState;
+        bake: BakeRecord;
+    };
+    complete: {
+        output: BakeOutput;
+        bake: BakeRecord;
+    };
+    failed: {
+        error: Bakery3Error;
+        bake: BakeRecord;
+    };
+    cancelled: {
+        bake: BakeRecord;
+    };
+};
+/**
+ * Polling starts on the first `on()` or `result()`; a listener added late
+ * hears the latest `progress` and how the bake ended. `stop()` stops watching
+ * and `cancel()` stops the bake, as for a render (see `RenderJob`).
+ */
+declare class BakeJob extends PolledJob<BakeRecord, BakeOutput, BakeJobEvents> {
+    protected readonly jobNoun = "bake";
+    protected readonly pollSchedule: number[];
+    protected readonly replayedEvents: ReadonlyArray<keyof BakeJobEvents>;
+    private readonly fetchImpl;
+    private lastState;
+    constructor(client: Bakery3Client, record: BakeRecord, fetchImpl?: typeof fetch);
+    /** The estimate this bake was accepted under. */
+    get estimate(): CostEstimate | undefined;
+    /**
+     * Ask the server to stop the bake. It ends as `cancelled`: `cancelled` is
+     * emitted and `result()` rejects with code `Cancelled`. To stop watching
+     * without stopping the bake, call `stop()`.
+     */
+    cancel(): Promise<void>;
+    protected readRecord(signal: AbortSignal): Promise<BakeRecord>;
+    protected observeRecord(record: BakeRecord): void;
+    protected completeRecord(record: BakeRecord): Promise<BakeOutput>;
+    protected recordPayload(record: BakeRecord): {
+        bake: BakeRecord;
+    };
+    /**
+     * bundle.json from storage, every uri replaced by its signed URL.
+     *
+     * A name the bundle uses that the control plane signed nothing for is a
+     * refusal here, with the name: never a bundle that quietly points at a
+     * texture the browser will 403 on ten seconds later.
+     */
+    private resolve;
+}
+
+/** The published version. Must equal the version in package.json. */
+declare const SDK_VERSION = "0.2.0";
+
+/**
+ * TSL to a renderer-neutral shader graph.
+ *
+ * A `MeshStandardNodeMaterial` is already a graph of small typed operations.
+ * This walks that live graph structurally and writes it down as the
+ * protocol's shader graph (see `protocol/shader.ts`), naming every
+ * node it cannot translate instead of skipping or approximating it.
+ *
+ * Structural, not nominal. Nothing here imports from three: `instanceof`
+ * would tie `check()` to `three/tsl`, which only exists from r167, and the
+ * checker must run for everyone. TSL nodes are recognized the way three
+ * recognizes them internally, by their `.type` string and their `isX` flags,
+ * which also keeps this working across three versions.
+ *
+ * Two things need more than structure:
+ *   - anonymous singletons (`positionWorld`, `time`) are recognized by uuid,
+ *     registered when the developer imports `@oeave/bakery3/tsl`
+ *   - `Fn()` calls are expanded by running their JS function, which works for
+ *     the pure composition functions TSL libraries are made of and fails
+ *     safely (a named issue, not a crash) for anything builder-dependent.
+ *
+ * Uniforms are baked to the value they held at capture. A still render is a
+ * snapshot of the application; `time`-driven shaders render the moment the
+ * button was pressed, and the report says so.
+ */
+
+/** A texture the graph samples; capture hashes its pixels and fills the id. */
+type ShaderTextureRef = {
+    texture: Texture;
+    /** Every graph node param waiting for this texture's asset hash. */
+    apply: (image: string) => void;
+};
+type ExtractedShader = {
+    /** Null when nothing was extractable at all. */
+    spec: MaterialShaderSpec | null;
+    /** Slot names that translated cleanly. */
+    supportedSlots: ShaderSlot[];
+    /** Slot names that had to be dropped, with why in `issues`. */
+    failedSlots: ShaderSlot[];
+    issues: Omit<CompatibilityIssue, 'path' | 'materialId' | 'materialName' | 'materialType'>[];
+    textures: ShaderTextureRef[];
+};
+/** The material properties this file reads, structurally. */
+type AnyNodeMaterial = {
+    uuid: string;
+    name?: string;
+    type?: string;
+    isNodeMaterial?: boolean;
+    isMeshStandardNodeMaterial?: boolean;
+    isMeshPhysicalNodeMaterial?: boolean;
+    isMeshBasicNodeMaterial?: boolean;
+    [key: string]: unknown;
+};
+declare function isNodeMaterial(material: unknown): material is AnyNodeMaterial;
+/**
+ * Extract one node material.
+ *
+ * Slots fail independently: a material whose color graph translates but
+ * whose roughness graph uses `dFdx` renders with the color graph and the
+ * static roughness value, and two issues say exactly that.
+ */
+declare function extractMaterialShader(material: AnyNodeMaterial): ExtractedShader;
+
+/**
+ * The active camera, in full.
+ *
+ * It is written out as data rather than referenced into the GLB by name
+ * because the live camera is often not in the graph the exporter walks: R3F
+ * holds the default camera outside the scene, drei's controls swap it, and a
+ * configurator often animates a camera that was never added as a child of
+ * anything.
+ */
+
+/**
+ * Depth of field, marked on a perspective camera as
+ * `camera.userData.bakery3 = { focus: { fStop: 2.8, target: [0, 0.4, 0] } }`.
+ *
+ * three has no aperture: its depth of field is a post-processing pass, so the
+ * render cannot read it off the camera and the developer says it here.
+ * `fStop` is a full-frame camera's f-number at the camera's own `fov`, so a
+ * smaller number blurs more. `target` is the world point that stays sharp
+ * and the render keeps it sharp through a clip as the camera moves;
+ * `distance` is a fixed focus distance in metres instead. One of the two.
+ */
+type CameraFocus = {
+    fStop: number;
+    target?: Vec3 | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    distance?: number;
+};
+
+/**
+ * Walking the scene: ids, runtime state, lights, and what to skip.
+ *
+ * Everything here reads the live graph and writes plain JSON. Nothing mutates
+ * the developer's scene except `stampIds`, which is reversed before the
+ * capture returns: a render must never leave a visible mark on the
+ * application it was called from.
+ */
+
+/**
+ * Which objects the exporter should skip.
+ *
+ * Not the same set as "hidden". A hidden object still ships in the GLB and is
+ * hidden per render, so a configurator toggling parts keeps hitting the asset
+ * cache. This is only for things that must never reach the renderer at all:
+ * helpers, gizmos, the developer's own opt-outs, and anything transient the
+ * app draws over the top.
+ */
+declare function shouldExclude(object: Object3D): boolean;
+
+/**
+ * @oeave/bakery3: ray trace the Three.js scene you're already rendering.
+ *
+ *     import { createBakery3 } from '@oeave/bakery3';
+ *
+ *     const bakery3 = createBakery3({
+ *       token: () => fetch('/api/bakery3-token', { method: 'POST' }).then(r => r.json()),
+ *     });
+ *
+ *     const job = await bakery3.render({ scene, camera, quality: 'studio' });
+ *     const image = await job.result();
+ *
+ * Everything else in this package exists to make those five lines true from
+ * inside a real application: no manual GLB export, no 3D suite, no dashboard
+ * upload, no re-creating configurator state.
+ *
+ * While you are still finding out whether this works at all, there is a
+ * shorter version that needs no server:
+ *
+ *     const bakery3 = createBakery3({ apiKey: 'bk_sk_…' });
+ *
+ * It renders, and it prints a console warning telling you to move the key
+ * behind a token endpoint before you ship: from a browser, `apiKey` is
+ * readable by every visitor.
+ */
+
+type Bakery3Options = ClientOptions & {
+    /**
+     * Defaults folded into every `render()`, `renderVideo()`, `estimate()` and
+     * variants run. Set once at the provider so a render button stays one
+     * line. A size given to a call replaces the default size as a whole.
+     */
+    defaults?: {
+        quality?: QualityPreset;
+        output?: Partial<OutputSpec>;
+        maxCost?: number;
+    };
+};
+type RenderOptions = Partial<CaptureOptions> & {
+    scene?: Scene;
+    camera?: Camera;
+    quality?: QualityPreset;
+    /**
+     * Leave both out for the preset's long edge in the camera's shape (a 16:9
+     * viewport renders 16:9). Give one and the other follows the camera's
+     * aspect; give both for exactly that size.
+     */
+    width?: number;
+    height?: number;
+    format?: OutputSpec['format'];
+    /** JPEG/WebP only, 1–100. */
+    imageQuality?: number;
+    /** Refuse the render rather than exceed this, in USD. */
+    maxCost?: number;
+    /** Ask for a low-sample preview. Defaults to the quality preset's own answer. */
+    preview?: boolean;
+    advanced?: RenderSpec['advanced'];
+    metadata?: Record<string, unknown>;
+    /** A resubmit with the same key returns the existing render, never a second
+     *  charge, which is what makes your own retry button safe. */
+    idempotencyKey?: string;
+    /**
+     * `high` puts this render ahead of the account's other waiting work in
+     * the same lane: the hero shot before the rest. It never jumps a lane, so
+     * a person waiting in a configurator still goes first.
+     */
+    priority?: RenderSpec['priority'];
+    /** Called while assets upload. Most renders after the first report 0 bytes. */
+    onUpload?: (progress: UploadProgress) => void;
+};
+/**
+ * `render()` from several cameras at once: one capture, one upload, one
+ * picture per camera. Everything else means what it means for one render,
+ * except `maxCost`, which is the ceiling for the whole set, and
+ * `idempotencyKey`, which names the set: a resubmit under the same key
+ * returns the same pictures and never a second charge.
+ */
+type RenderCamerasOptions = Omit<RenderOptions, 'camera' | 'priority'> & {
+    /** Names of cameras in the scene, Camera objects, or `{ id, position, target, fov }`. */
+    cameras: ViewCamera[];
+};
+/** How every picture of a variants run is traced: the same settings `render()` takes. */
+type PictureOptions = Pick<RenderOptions, 'scene' | 'quality' | 'width' | 'height' | 'format' | 'imageQuality' | 'preview' | 'advanced' | 'renderer' | 'environment' | 'productState' | 'background'>;
+/**
+ * Every variant, from every camera.
+ *
+ * A variant is whatever your configurator calls one: a row from the product
+ * database, a SKU, a `{ model, color }`. `apply` puts your scene in that
+ * state, exactly as a customer clicking would, and the SDK photographs it.
+ * One variant is resident at a time, and `variants` may be a generator or an
+ * async cursor, so neither the scene nor the list has to fit in memory.
+ */
+type RenderVariantsOptions<V> = PictureOptions & {
+    /**
+     * Names the run. Stable across re-runs: the same key re-opens the same
+     * run while it is unfinished, so a recorder that died at variant 140 is
+     * resumed by calling this again.
+     */
+    key: string;
+    name?: string;
+    /** An array, a generator, an async cursor. Pulled one at a time, never collected. */
+    variants: Iterable<V> | AsyncIterable<V>;
+    /**
+     * Put the scene in this variant's state. Return a function to undo it
+     * (remove the model, dispose what it held); it runs before the next
+     * variant is applied. Leave `apply` out when the variants differ only by
+     * `finishes`.
+     */
+    apply?: (variant: V) => void | VariantCleanup | Promise<void | VariantCleanup>;
+    /** Default: `variant.id`, `.sku` or `.key`, or the variant itself when it is a string. */
+    id?: (variant: V, index: number) => string;
+    /**
+     * Finishes that are all inside the model already, told apart by which
+     * objects show. Each becomes its own picture from the variant's one
+     * capture: no second export, no second upload.
+     */
+    finishes?: (variant: V) => CatalogFinish[] | undefined;
+    /** Default: the live camera. */
+    cameras?: ViewCamera[];
+    /** Echoed on every picture, its webhooks and the ledger, beside `variant`, `finish` and `camera`. */
+    metadata?: (variant: V) => Record<string, unknown>;
+    /**
+     * Appended to every picture's key as `@version`. A picture is adopted, at
+     * no cost, when its key already rendered, so bump this when the pictures
+     * must be traced again: a new room, a new look.
+     */
+    version?: string;
+    /** The ceiling for the whole run, in dollars. `quoteVariants()` gives the number to set it from. */
+    maxCost: number;
+    /** A ceiling for each picture, under the run's. One over it is refused alone. */
+    maxCostPerImage?: number;
+    /** `batch` (the default) never runs ahead of a person in a configurator. */
+    lane?: 'batch' | 'normal';
+    /** Fewer pictures at once than the plan allows. */
+    maxParallel?: number;
+    /** After every variant is recorded. For progress while they render, `run.wait({ onProgress })`. */
+    onProgress?: (progress: VariantProgress) => void;
+    /** Stops between variants. What was recorded stays admitted; call again to go on. */
+    signal?: AbortSignal;
+};
+/**
+ * What `capture()` returns: the manifest and the blobs it names, plus the
+ * ids the manifest uses, by object name, so a caller can build variants of
+ * one capture (hide these, look from there) without a second export.
+ */
+type Capture = CapturedScene & {
+    /**
+     * Object name → the id the manifest addresses it by (`hiddenObjectIds`,
+     * `transforms`, lights). Unnamed objects are absent; when two objects
+     * share a name the first in traversal order wins, so name what you mean
+     * to address.
+     */
+    objects: Record<string, string>;
+    /** What `uploadAssets()` uploaded, once it has run. */
+    upload?: UploadProgress;
+};
+/** The batch half of the SDK. */
+type BatchesApi = {
+    /**
+     * Open a batch, or re-open it: the same `key` returns the same batch
+     * while it is not terminal, and items already completed under their keys
+     * are adopted rather than rendered again.
+     */
+    open(request: BatchOpenRequest): Promise<Batch>;
+    /** A batch by id, with its latest counts. */
+    get(id: string): Promise<Batch>;
+};
+type EstimateOptions = {
+    scene?: Scene;
+    /**
+     * The camera the render would use. An interior is priced as one from
+     * where the camera stands (how much of it is walled in), so the default is
+     * the client's own camera.
+     */
+    camera?: Camera;
+    quality?: QualityPreset;
+    /** The same rule as `render()`: the camera's shape when left out. */
+    width?: number;
+    height?: number;
+    advanced?: RenderSpec['advanced'];
+    /** Quote a clip: how many frames. A frame in a clip costs less than a still. */
+    frames?: number;
+    /**
+     * Quote a bake instead of a render: the same `settings` `bake()` takes.
+     * The scene is read the way the bake reads it (the include list, a preset
+     * room, stand-ins from `simplify` and from `userData.bakery3.simplify`),
+     * so the quote is the one the bake is accepted under.
+     */
+    bake?: PrepareBakeSettings;
+};
+/**
+ * What `bake()` takes: the capture, plus what to bake and how well.
+ *
+ * `settings` is the same object `estimate({ bake })` takes, so a quote and
+ * the bake it prices cover the same objects. By default: every object that
+ * can hold a lightmap, at 1024², `standard` quality, seams hidden from the
+ * camera you pass.
+ */
+type BakeOptions = Partial<CaptureOptions> & {
+    scene?: Scene;
+    camera?: Camera;
+    settings?: PrepareBakeSettings;
+    /** Refuse the bake rather than exceed this, in USD. */
+    maxCost?: number;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+    onUpload?: (progress: UploadProgress) => void;
+};
+/** Everything `render()` takes, plus the move. */
+type RenderVideoOptions = RenderOptions & {
+    /** The motion to trace. Baked into the manifest at submit time. */
+    timeline: Timeline;
+    /** Overrides the timeline's own rate for this render only. */
+    fps?: number;
+    /**
+     * Default `'mp4'`. `'mp4'` and `'webm'` are opaque: no codec here carries
+     * alpha, and supporting it in one container only would mean the same
+     * manifest producing two visibly different videos.
+     *
+     * `'png-sequence'` keeps the alpha: every frame is the PNG a still of it
+     * would be (transparent background, the shadow in alpha), all of them in
+     * one uncompressed tar with `frames.json` first, for compositing the
+     * product between layers of your own. The result's `url` is the tar.
+     */
+    format?: 'mp4' | 'webm' | 'png-sequence';
+    /**
+     * `'png-sequence'` only: bits per channel, 16 (the default, as a still's
+     * PNG is) or 8, whose frames are less than half the size.
+     */
+    bitDepth?: 8 | 16;
+};
+type Bakery3 = {
+    /**
+     * Capture the current scene, upload what is missing, start the render.
+     *
+     * With `cameras`, the same capture photographed from each of them: one
+     * export, one upload, a `RenderSet` of pictures back.
+     *
+     *     const shots = await bakery3.render({ cameras: ['hero', 'front', 'detail'] });
+     *     const [hero, front, detail] = await shots.result();
+     *
+     * `result()` gives one picture per camera, in order, or rejects: with
+     * `RenderSetRefused` (its `refusals` name the cameras and the reasons)
+     * when a picture was turned down at submission, so a destructured array
+     * never shifts. Every picture is one size, in the first camera's shape.
+     */
+    render(options: RenderCamerasOptions): Promise<RenderSet>;
+    render(options?: RenderOptions): Promise<RenderJob>;
+    /**
+     * Every variant, from every camera, however many there are.
+     *
+     *     const run = await bakery3.renderVariants({
+     *       key: 'fall-2026',
+     *       variants: products,
+     *       apply: (product) => configurator.show(product),
+     *       cameras: ['hero', 'front', 'detail'],
+     *       maxCost: 600,
+     *     });
+     *     await run.wait();
+     *     for await (const image of run.images()) save(image);
+     *
+     * Resolves once every variant is recorded and the run is sealed; the
+     * pictures render on from there whether or not the page stays open.
+     * Calling it again with the same `key` resumes a recording that stopped
+     * and adopts every picture that already rendered.
+     */
+    renderVariants<V>(options: RenderVariantsOptions<V>): Promise<RenderSet>;
+    /**
+     * What `renderVariants()` would cost, to the picture: the same walk, with
+     * nothing uploaded, admitted or reserved.
+     *
+     * The pages are priced on a batch of their own, keyed `${key}:quote` and
+     * cancelled once the quote is in, never on the run's: the run's batch is
+     * opened by `renderVariants()`, with its `maxCost`, and nothing else.
+     * Pictures that already rendered under their keys are quoted as adopted,
+     * at nothing, so this is the price of a re-run too.
+     */
+    quoteVariants<V>(options: Omit<RenderVariantsOptions<V>, 'maxCost'> & {
+        maxCost?: number;
+    }): Promise<VariantsQuote>;
+    /**
+     * Look before paying: three variants (the first, the middle and the last
+     * of an array; the first three of anything else) from every camera and in
+     * every finish, at preview quality and a small size, in the ordinary lane
+     * so they come back in a minute. Same options as `renderVariants()`. The
+     * test has its own keys, so the real run never adopts these previews.
+     *
+     *     const test = await bakery3.testVariants(options);
+     *     for (const image of await test.result()) show(image.variant, image.camera, image.url);
+     */
+    testVariants<V>(options: Omit<RenderVariantsOptions<V>, 'maxCost'> & {
+        maxCost?: number;
+    }, test?: TestRunOptions): Promise<RenderSet>;
+    /** A set by id: after a reload, in another tab, from a webhook. */
+    getRenderSet(id: string): Promise<RenderSet>;
+    /**
+     * A timeline bound to the attached scene and camera.
+     *
+     *     const tl = bakery3.timeline({ duration: 4 });
+     *     tl.push({ object: 'camera', orbitY: 90 });
+     *     const job = await bakery3.renderVideo({ timeline: tl });
+     *
+     * The scene and camera are read from `attach()` when the timeline needs
+     * them, so one made before the attachment still drives the camera
+     * attached later. A camera move with no camera by then is refused.
+     */
+    timeline(options?: TimelineOptions): Timeline;
+    /**
+     * The same capture as `render()`, plus the baked timeline, as a video.
+     *
+     * A clip is priced by its frame count: one start-up floor, then every
+     * frame at a fraction of a still, because one session traces them all.
+     * `estimate({ frames })` gives the same quote the clip is accepted under,
+     * and `maxCost` is checked against it before anything uploads.
+     */
+    renderVideo(options: RenderVideoOptions): Promise<RenderJob>;
+    /**
+     * Path-traced lighting for the scene you are already rendering.
+     *
+     *     const job = await bakery3.bake();
+     *     const { bundle } = await job.result();
+     *     const session = createBakeSession({ scene });   // @oeave/bakery3/bake
+     *     await session.apply(session.addGeneration(bundle));
+     *
+     * The same capture as `render()`, the same asset upload, and a bundle of
+     * lightmaps back (one per object, or one atlas) with its textures on
+     * signed URLs the session loads directly.
+     */
+    bake(options?: BakeOptions): Promise<BakeJob>;
+    /** A bake by id, for fresh URLs after the old ones expired. */
+    getBake(id: string): Promise<BakeJob>;
+    /**
+     * A render by id: after a reload, in another tab, from a webhook. Its
+     * `result()` signs fresh URLs when the old ones have expired.
+     */
+    getRender(id: string): Promise<RenderJob>;
+    /** What this would cost, before anything expensive happens. */
+    estimate(options?: EstimateOptions): Promise<CostEstimate>;
+    /**
+     * Local, free, offline: what would and would not translate.
+     *
+     * No account needed and no bytes leave the browser, so "will my scene
+     * work?" can be answered before signing up.
+     */
+    check(scene?: Scene): CompatibilityReport;
+    /** The captured manifest, without rendering. For debugging, and for seeing exactly what leaves the browser. */
+    inspect(options?: RenderOptions): Promise<SceneManifest>;
+    /**
+     * The same capture `render()` starts from, handed back instead of
+     * submitted: the manifest, its assets, and the object ids by name. What a
+     * catalog recorder builds its variants from: one export per product,
+     * a few KB of manifest per still.
+     */
+    capture(options?: RenderOptions): Promise<Capture>;
+    /**
+     * Upload a capture's assets that storage does not already have. Once per
+     * capture; every manifest derived from it then names bytes that exist.
+     */
+    uploadAssets(capture: Pick<Capture, 'assets'>, onProgress?: (progress: UploadProgress) => void): Promise<UploadProgress>;
+    /** Batches: a declared body of work, admitted in pages, one poll for all of it. */
+    readonly batches: BatchesApi;
+    /** Point the SDK at the app's live scene and camera once, at mount. */
+    attach(context: {
+        scene: Scene;
+        camera: Camera;
+        renderer?: CaptureOptions['renderer'];
+    }): void;
+    readonly version: string;
+};
+declare function createBakery3(options?: Bakery3Options): Bakery3;
+
+export { type AdapterOptions, BakeBundle, BakeJob, type BakeJobEvents, type BakeOptions, type BakeOutput, type Bakery3, Bakery3Error, type Bakery3Options, Batch, BatchOpenRequest, BatchProgress, type BatchesApi, type CameraFocus, type Capture, type CaptureOptions, type CapturedScene, type CatalogCamera, type CatalogFinish, ClientOptions, CompatibilityIssue, CompatibilityReport, CostEstimate, type EstimateOptions, type ExtractedShader, type JobEvents, type JobResultOptions, MaterialShaderSpec, OutputSpec, PrepareBakeSettings, QualityPreset, type RenderCamerasOptions, RenderJob, type RenderOptions, RenderRecord, RenderResult, RenderSet, RenderState, type RenderVariantsOptions, type RenderVideoOptions, SDK_VERSION, type SampledTrack, SceneManifest, ShaderSlot, type ShaderTextureRef, TestRunOptions, Timeline, TimelineOptions, TrackTarget, type UploadProgress, type VariantCleanup, type VariantProgress, VariantsQuote, type ViewCamera, analyzeScene, createBakery3, extractMaterialShader, isNodeMaterial, rememberEnvironmentSource, shouldExclude, timelineFromGsap, timelineFromTheatre };