@oeave/bakery3 0.0.0-stage → 0.1.0

package/dist/devtools/index.d.ts

@@ -0,0 +1,536 @@
+import { Object3D, Scene, Camera } from 'three';
+import { a as BakeQuality, B as BakeTextureSize, e as BakeSpec, j as BakeBundle, Q as QualityPreset } from '../bake-DaOlenyx.js';
+import { CapturedScene, Bakery3, RenderOptions, RenderJob, CaptureOptions } from '../index.js';
+import { T as Timeline } from '../timeline-ChwgD7bT.js';
+import { BakeSession } from '../bake/index.js';
+import '../animation-B1h0Ryvj.js';
+import '../testRun-BIPXaVPb.js';
+import '../prepare-C5qVvaw4.js';
+
+/**
+ * The timeline panel: a floating strip, not an editor.
+ *
+ * The developer orbits their product with the mouse, presses ＋, scrubs,
+ * presses ＋ again, and presses Render video, without leaving the page. It is
+ * vanilla DOM and imports nothing but the timeline itself, so a plain three.js
+ * app and, through the thin wrapper in r3f/, a React app mount exactly the
+ * same panel.
+ *
+ *     import { mountTimelinePanel } from '@oeave/bakery3/devtools';
+ *
+ *     const panel = mountTimelinePanel({
+ *       timeline,
+ *       targets: [{ object: hero, label: 'hero' }],
+ *       onPlaybackChange: (active) => { controls.enabled = !active; },
+ *       onRenderVideo: (tl) => renderVideo(tl),
+ *     });
+ *
+ * `onPlaybackChange` is the one that matters. Orbit controls rewrite the
+ * camera every frame, so a timeline that owns the camera and controls that
+ * also own it fight, and the developer sees a stuttering preview. The host
+ * suspends them; capture still reads the camera the developer framed with the
+ * controls.
+ *
+ * `buildTimelineBody` is the same UI without the shell, because the dev panel
+ * (./devPanel.ts) shows it as its Video tab. `mountTimelinePanel` is the
+ * floating shell around that body.
+ */
+
+/** An object the developer can add a lane for. The label is what the picker
+ *  shows: a three `name` is often empty or generated, and "Mesh" three times
+ *  in a dropdown is not a choice anybody can make. */
+type TimelinePanelTarget = {
+    object: Object3D;
+    label: string;
+};
+/** What the host supplies. Only `timeline` is required; the Render-video
+ *  button appears only when there is something for it to call. */
+type TimelinePanelOptions = {
+    timeline: Timeline;
+    /** Objects offered in the "add track" picker. The camera is always there. */
+    targets?: TimelinePanelTarget[];
+    /** Shows the "Render video" button when given. */
+    onRenderVideo?: (timeline: Timeline) => void | Promise<void>;
+    /** Fired when the timeline takes the camera, and when it gives it back. */
+    onPlaybackChange?: (active: boolean) => void;
+    container?: HTMLElement;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    defaultOpen?: boolean;
+};
+/** The handle a host keeps. Small on purpose: the panel reads everything else
+ *  it needs off the timeline and its events, so there is no second copy of the
+ *  state to keep in sync. */
+type TimelinePanel = {
+    /** Rebuild the lanes, after loading a different scene, say. */
+    refresh(): void;
+    /** One line under the transport: "tracing frame 12/48". */
+    setStatus(message: string, tone?: 'info' | 'error'): void;
+    dispose(): void;
+};
+/**
+ * Attach the panel to the page.
+ *
+ * It appends one fixed-position element to `container` (the body by default)
+ * and owns nothing else: no globals, no stylesheet, no listener outside its
+ * own subtree and the timeline's events. `dispose()` puts the page back
+ * exactly as it was, which is what makes it safe to mount from a hot-reloading
+ * dev server.
+ */
+declare function mountTimelinePanel(options: TimelinePanelOptions): TimelinePanel;
+
+/**
+ * The dev panel: one floating thing that renders, films and bakes.
+ *
+ * A 48px mark in the corner of the developer's own app, which opens into a
+ * card with up to three tabs and a price. Four things about it are contracts
+ * and the rest is layout:
+ *
+ * 1. The cost is visible before the money is spent. Beside every primary
+ *    button is a quiet line, `98% compatible  ≈ $0.12`: hover the price for
+ *    what it is made of (`96 frames × $0.039`, at most $5.00), click the
+ *    figure for the objects that render differently. The price refreshes
+ *    when the settings change, when the tab changes, and when the scene
+ *    changes; never on a clock, so a price that has not moved is not fetched
+ *    again. A key or a balance that will refuse the render is said in the
+ *    status line then, not when Render is pressed.
+ * 2. Every refusal is in place. An object that cannot be baked appears in the
+ *    list with a ⚠ and its reason and fix on hover, next to the ones that
+ *    can. Nothing is silently missing.
+ * 3. Hold to compare. Pointer down shows the live scene, pointer up puts the
+ *    bake back, both within a frame and both lossless, because the session
+ *    keeps the patch and just switches it off.
+ * 4. The lock explains itself. Downloads are the one gated action, and the
+ *    locked state says what kind of key unlocks it and where to put it.
+ *
+ * A tab only exists if its options were supplied. A vanilla three app with
+ * no timeline gets a two-tab panel, not a Video tab that does nothing.
+ *
+ *     import { mountDevPanel } from '@oeave/bakery3/devtools';
+ *
+ *     const panel = mountDevPanel({
+ *       estimate: (request) => post('/api/estimate', request),
+ *       render: { onRender: (settings) => runRender(settings) },
+ *       bake: { session, onBake: (settings) => runBake(settings) },
+ *     });
+ */
+
+type DevPanelTab = 'render' | 'video' | 'bake';
+/** What the panel asks the host to price. */
+type DevPanelEstimateRequest = {
+    kind: 'render';
+    quality: string;
+    width: number;
+    height: number;
+} | {
+    kind: 'video';
+    quality: string;
+    width: number;
+    height: number;
+    frames: number;
+    fps: number;
+    format: 'mp4' | 'webm';
+} | {
+    kind: 'bake';
+    quality: BakeQuality;
+    textureSize: number;
+    objects: number;
+    texels: number;
+    /** The ticked objects, as objectIds. */
+    include: string[];
+};
+type DevPanelEstimate = {
+    /** The price beside the button. */
+    usd: number;
+    /** The most it can be charged: the breakdown's `at most` line. */
+    maximum?: number;
+    /**
+     * A line of your own under the breakdown, which already lists the
+     * settings, the count the price is made of (`96 frames × $0.039`) and the
+     * maximum: `on the local worker`.
+     */
+    detail?: string;
+    /** False when the price is exact rather than an estimate: no `≈`. */
+    approximate?: boolean;
+};
+/** One past artifact, as the host's history lists it. */
+type DevPanelHistoryEntry = {
+    id: string;
+    kind: DevPanelTab;
+    createdAt: string;
+    /** When `artifact` and `thumbnail` stop working (signed URLs do). The
+     *  panel's own history drops an entry then. */
+    expiresAt?: string;
+    cacheKey?: string;
+    cached?: boolean;
+    meta?: {
+        width?: number;
+        height?: number;
+        format?: string;
+        frames?: number;
+        fps?: number;
+        quality?: string;
+        textureSize?: number;
+        objects?: number;
+        skipped?: number;
+        /** What it was charged, in dollars. */
+        cost?: number;
+    };
+    thumbnail?: string;
+    artifact?: string;
+};
+/** What a finished action gives the panel to show. `entry` is what makes the
+ *  result's Download button real: downloads go through the same gated path
+ *  as history, never round an alternative route. */
+type DevPanelActionResult = {
+    url?: string;
+    meta?: string;
+    isVideo?: boolean;
+    entry?: DevPanelHistoryEntry;
+    /** The job's id, so the panel's own history does not list it twice. */
+    id?: string;
+    /** The output's size: the result area holds the image's shape before the
+     *  image has loaded, so nothing below it moves when it does. */
+    width?: number;
+    height?: number;
+    quality?: string;
+    format?: string;
+    frames?: number;
+    /** Dollars charged, for the history line. */
+    cost?: number;
+    /** Millisecond epoch at which `url` stops working. */
+    expiresAt?: number;
+};
+type DevPanelRenderSettings = {
+    quality: string;
+    width: number;
+    height: number;
+};
+type DevPanelRenderOptions = {
+    onRender: (settings: DevPanelRenderSettings) => void | DevPanelActionResult | Promise<void | DevPanelActionResult>;
+    qualities?: string[];
+    /** Long edges to offer. The short edge follows `aspect`. */
+    sizes?: number[];
+    /**
+     * Width ÷ height of the frame the host renders: 4/3 for a 640×480 room
+     * shot, or a function that reads the camera, so a wide viewport renders
+     * wide. Read each time the panel prices or renders. Defaults to 1, a
+     * square.
+     */
+    aspect?: number | (() => number);
+    defaultQuality?: string;
+    defaultSize?: number;
+};
+type DevPanelVideoSettings = DevPanelRenderSettings & {
+    format: 'mp4' | 'webm';
+    timeline: Timeline;
+};
+type DevPanelVideoOptions = {
+    timeline: Timeline;
+    targets?: TimelinePanelTarget[];
+    /**
+     * The live scene, read whenever `sceneVersion` reports a change.
+     *
+     * Supplying it lets the panel re-attach tracks whose objects were rebuilt
+     * (a variant swap, an r3f remount) instead of letting the timeline refuse at
+     * export. Without it the panel still works; stale tracks just survive until
+     * something else catches them.
+     */
+    scene?: () => Object3D | undefined;
+    /** Passed straight through to the timeline body: the orbit-controls
+     *  handshake that keeps the camera from being driven twice. */
+    onPlaybackChange?: (active: boolean) => void;
+    onRenderVideo: (settings: DevPanelVideoSettings) => void | DevPanelActionResult | Promise<void | DevPanelActionResult>;
+    qualities?: string[];
+    /** Long edges to offer. The short edge follows `aspect`. */
+    sizes?: number[];
+    /** As the Render tab's. Video sizes are rounded to even numbers, which is
+     *  what a video encoder takes. */
+    aspect?: number | (() => number);
+    formats?: Array<'mp4' | 'webm'>;
+    defaultQuality?: string;
+    defaultSize?: number;
+    defaultFormat?: 'mp4' | 'webm';
+};
+type DevPanelBakeSettings = {
+    quality: BakeQuality;
+    textureSize: BakeTextureSize;
+    /** The ticked boxes, as objectIds. */
+    include: string[];
+};
+type DevPanelBakeResult = {
+    /** Index of the generation the host added, when it added one. The panel
+     *  reads the session for everything else. */
+    generation?: number;
+    entry?: DevPanelHistoryEntry;
+};
+type DevPanelBakeOptions = {
+    session: BakeSession;
+    onBake: (settings: DevPanelBakeSettings) => void | DevPanelBakeResult | Promise<void | DevPanelBakeResult>;
+    qualities?: BakeQuality[];
+    sizes?: BakeTextureSize[];
+    defaultQuality?: BakeQuality;
+    defaultSize?: BakeTextureSize;
+};
+/** The shape of `bakery3.check()`, structurally, so the panel does not have
+ *  to import the compatibility analyzer to display its verdict. */
+type DevPanelCompatibility = {
+    score: number;
+    issues: Array<{
+        severity: string;
+        message: string;
+        /** `<Car>/<Body>/<Paint>`: the panel lists the issue under `Paint`. */
+        path?: string;
+        /** Linked beside the issue. */
+        docs?: string;
+    }>;
+};
+type DevPanelHistoryOptions = {
+    list: () => Promise<DevPanelHistoryEntry[]>;
+    /** Omit it and no download buttons are drawn at all, which is better than
+     *  a button that cannot work. */
+    download?: (entry: DevPanelHistoryEntry, part?: 'glb') => void | Promise<void>;
+};
+/**
+ * A render the panel shows in its jobs strip: what is tracing now and what
+ * waits behind it. A job in a terminal state is not drawn; what finished is
+ * the Recent list's to show. States use the protocol's RenderState names
+ * (`queued`, `preparing`, `rendering_preview`, `rendering`, `completed`,
+ * `failed`, `cancelled`) so an SDK job and a host's own queue read alike.
+ */
+type DevPanelJob = {
+    id: string;
+    label: string;
+    state: string;
+    /** Overall, 0–1. Omit for an honest indeterminate. */
+    progress?: number;
+    /** The renderer's own words: `48% of samples`, `frame 12/48`. */
+    detail?: string;
+    /** The low-sample preview, the moment it exists: the row's thumbnail
+     *  until `resultUrl` replaces it. */
+    previewUrl?: string;
+    resultUrl?: string;
+    seconds?: number;
+    /** Drawn as × on a job that is not finished. */
+    onCancel?: () => void;
+};
+/** What a tracked job's listeners receive: the union of RenderJob's payloads,
+ *  loosely, so the panel can read them without importing the client. */
+type TrackedJobPayload = {
+    percent?: number;
+    state?: string;
+    url?: string;
+    result?: {
+        url: string;
+        width?: number;
+        height?: number;
+        format?: string;
+        cost?: number;
+        expiresAt?: number;
+    };
+    error?: {
+        message?: string;
+    };
+    /** Every RenderJob payload carries the record; the strip does not read it,
+     *  but naming it keeps this an honest structural match for all five events. */
+    render?: unknown;
+};
+/**
+ * What `trackJob` needs from an SDK `RenderJob`, structurally, so the panel
+ * never imports the client and any object with these members works.
+ */
+type TrackableJob = {
+    id: string;
+    status: string;
+    progress: number;
+    previewUrl?: string;
+    on(event: 'progress' | 'preview' | 'complete' | 'failed' | 'cancelled', listener: (payload: TrackedJobPayload) => void): () => void;
+    cancel?(): void | Promise<void>;
+};
+type DevPanelOptions = {
+    container?: HTMLElement;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    defaultOpen?: boolean;
+    defaultTab?: DevPanelTab;
+    /** A name beside the mark in the header, for a host with a panel of its
+     *  own to tell apart. None by default: the mark says whose panel it is. */
+    title?: string;
+    /** Fired when the FAB is opened or the card collapsed. A host that
+     *  remounts the panel (switching scenes, say) uses it to come back open. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * A cheap fingerprint of what is in the scene: its objects, which of them
+     * are visible, their geometry and materials. When it changes, the price,
+     * the Bake tab's object list and the compatibility verdict follow, because
+     * a developer who just added a wall should not be looking at the price of
+     * the room without it.
+     *
+     * three.js has no event for most of that (a swapped geometry, a hidden
+     * mesh), so the panel compares this on animation frames a few times a
+     * second while it is open, and never while the tab is in the background.
+     * Keep it to a walk over the scene; it can be as approximate as you like.
+     */
+    sceneVersion?: () => string | number;
+    /**
+     * A cheap fingerprint of where things are: the camera's position, and the
+     * objects' if they move. How walled in the camera is moves a price, so a
+     * camera carried into a room is priced again, once it has come to rest. A
+     * view that never rests (an auto-rotating orbit, a scene that animates)
+     * keeps the price it had; `sceneVersion` still re-prices what is added to
+     * it meanwhile.
+     */
+    viewVersion?: () => string | number;
+    estimate?: (request: DevPanelEstimateRequest) => Promise<DevPanelEstimate | null> | DevPanelEstimate | null;
+    /**
+     * The free, local, offline compatibility check, shown beside the button as
+     * `98% compatible`, which opens the issues object by object. Read on open,
+     * when the scene changes and on every `refresh()`; returning `null` hides
+     * it.
+     */
+    compatibility?: () => DevPanelCompatibility | null;
+    history?: DevPanelHistoryOptions;
+    render?: DevPanelRenderOptions;
+    video?: DevPanelVideoOptions;
+    bake?: DevPanelBakeOptions;
+};
+type DevPanel = {
+    open(): void;
+    close(): void;
+    setTab(tab: DevPanelTab): void;
+    /** Re-read candidates, generations and history and repaint. */
+    refresh(): void;
+    /** Ask for a fresh estimate now. */
+    refreshCost(): void;
+    setStatus(message: string, tone?: 'info' | 'error' | 'ok'): void;
+    /** The host drives per-object progress:
+     *  `setProgress('Baking pedestal · 3/12', 3/12)`. `null` clears it. */
+    setProgress(text: string | null, fraction?: number): void;
+    /**
+     * The jobs strip, replaced wholesale. A host with its own queue (a local
+     * worker, a batch script) reports what is tracing now and what waits
+     * behind it. Finished jobs are dropped from the strip; with no active job
+     * it hides.
+     */
+    setJobs(jobs: DevPanelJob[]): void;
+    /**
+     * Follow an SDK render job into the strip (progress, the preview the
+     * moment it lands) with nothing to translate on the host's side. The row
+     * leaves the strip when the job ends; the untrack function detaches the
+     * listeners.
+     */
+    trackJob(job: TrackableJob, label?: string): () => void;
+    /**
+     * A row in the jobs strip from the moment an action starts, before there
+     * is a job to follow: `update()` says what is happening (capturing the
+     * scene, uploading), `follow()` hands the same row to the job once it
+     * exists, and `end()` takes it away. One row from the click to the result,
+     * where it would otherwise be a bar that vanishes and a row that appears.
+     */
+    startJob(label: string): DevPanelJobHandle;
+    dispose(): void;
+};
+/** What `startJob` returns. See there. */
+type DevPanelJobHandle = {
+    /** `state` names a step after the job itself is done (`applying`), which
+     *  keeps the row up while the action finishes. */
+    update(detail: string, progress?: number, state?: string): void;
+    follow(job: TrackableJob): void;
+    end(): void;
+};
+/**
+ * Mount the panel. Appends one fixed-position element to `container` (the
+ * body by default) and owns nothing else; `dispose()` puts the page back.
+ */
+declare function mountDevPanel(options: DevPanelOptions): DevPanel;
+
+/**
+ * `mountBakery3Devtools`: the panel, wired to your client, in one call.
+ *
+ * `mountDevPanel` underneath it takes callbacks and knows nothing about an
+ * account. This function supplies those callbacks from a `createBakery3()`
+ * client, so the estimate, render, video and bake plumbing is written once
+ * for a vanilla three.js app and for React alike (`<Bakery3Devtools />` is a
+ * shell over this same function, see ../r3f/Devtools.tsx).
+ *
+ *     import { createBakery3 } from '@oeave/bakery3';
+ *     import { mountBakery3Devtools } from '@oeave/bakery3/devtools';
+ *
+ *     const bakery3 = createBakery3({ token: mintToken });
+ *     const panel = mountBakery3Devtools({ bakery3, scene, camera, renderer });
+ *
+ * By default the Bake tab goes through `bakery3.bake()`: the same capture,
+ * upload and `/v1/bakes` round trip a render takes, with the bundle's
+ * textures coming back on signed URLs. A `bakeTransport` replaces that with
+ * a function of your own that turns a `BakeSpec` into a `BakeBundle` (a local
+ * worker, or a bake farm you already run), and nothing else about the panel
+ * changes.
+ */
+
+/** What turns a prepared bake into a bundle. See the file header. */
+type BakeTransport = (spec: BakeSpec, assets: CapturedScene['assets']) => Promise<BakeBundle>;
+/**
+ * The part of the client the panel uses.
+ *
+ * Structural rather than `Bakery3` itself so that a host wrapping the client
+ * (to add its own telemetry, or to swap in a fake in a test) is not shut out
+ * of the panel for it. A real `createBakery3()` satisfies it as-is.
+ */
+type Bakery3DevtoolsClient = Pick<Bakery3, 'check' | 'estimate' | 'renderVideo'> & {
+    /** One render, one job: the panel never asks for a set of cameras. */
+    render(options?: RenderOptions): Promise<RenderJob>;
+} & 
+/** Present on every real client; a host that fakes one and gives no
+ *  `bakeTransport` is told so when the Bake button is pressed. */
+Partial<Pick<Bakery3, 'bake'>>;
+type Bakery3DevtoolsOptions = {
+    bakery3: Bakery3DevtoolsClient;
+    /**
+     * The live scene the panel checks, prices, renders and bakes. Read each
+     * time it is used, so a getter works; the Bake tab's session belongs to the
+     * scene this is when the panel mounts.
+     */
+    scene: Scene;
+    /** Read each time it is used, so a getter can follow a camera that is
+     *  swapped (R3F does) without remounting the panel. Its aspect is the
+     *  aspect of every render and video the panel starts. */
+    camera: Camera;
+    /**
+     * The live `WebGLRenderer`, so the capture carries your color space and
+     * tone mapping instead of guessing them. Optional but wanted: an app that
+     * tone-maps and does not say so gets a render that is faithful to the
+     * manifest and not to the viewport.
+     */
+    renderer?: CaptureOptions['renderer'];
+    /** Where the panel mounts. Defaults to `document.body`. */
+    container?: HTMLElement;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    defaultQuality?: QualityPreset;
+    defaultOpen?: boolean;
+    defaultTab?: DevPanelTab;
+    /** A name beside the mark in the header. None by default. */
+    title?: string;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * The timeline the Video tab films. Without one the panel makes its own,
+     * empty, on the live scene and camera: frame a shot, press Keyframe camera,
+     * move the playhead and press it again.
+     */
+    timeline?: Timeline;
+    /** Objects offered in the timeline's "add track" picker. */
+    timelineTargets?: TimelinePanelTarget[];
+    /** Fired when the timeline takes the camera and when it gives it back.
+     *  Suspend your orbit controls here. */
+    onPlaybackChange?: (active: boolean) => void;
+    /** Your own bake worker instead of the hosted `/v1/bakes`. */
+    bakeTransport?: BakeTransport;
+    /** Where a bundle's relative uris resolve against, when it has any. */
+    bakeBaseUrl?: string;
+    /** Zero the realtime lights when a generation is applied. Off by default:
+     *  the session already replaces diffuse lighting with the lightmap (see
+     *  bake/shading.ts), so muting only removes the lamps' highlights. It is a
+     *  look to switch on from the panel, not a correction. */
+    muteLightsOnApply?: boolean;
+    history?: DevPanelHistoryOptions;
+};
+declare function mountBakery3Devtools(options: Bakery3DevtoolsOptions): DevPanel;
+
+export { type BakeTransport, type Bakery3DevtoolsClient, type Bakery3DevtoolsOptions, type DevPanel, type DevPanelActionResult, type DevPanelBakeOptions, type DevPanelBakeResult, type DevPanelBakeSettings, type DevPanelCompatibility, type DevPanelEstimate, type DevPanelEstimateRequest, type DevPanelHistoryEntry, type DevPanelHistoryOptions, type DevPanelJob, type DevPanelJobHandle, type DevPanelOptions, type DevPanelRenderOptions, type DevPanelRenderSettings, type DevPanelTab, type DevPanelVideoOptions, type DevPanelVideoSettings, type TimelinePanel, type TimelinePanelOptions, type TimelinePanelTarget, type TrackableJob, type TrackedJobPayload, mountBakery3Devtools, mountDevPanel, mountTimelinePanel };

package/dist/devtools/index.js

@@ -0,0 +1,15 @@
+export { mountBakery3Devtools, mountDevPanel, mountTimelinePanel } from '../chunk-54WJDN5R.js';
+import '../chunk-CX4WTVGH.js';
+import '../chunk-V3QINEEG.js';
+import '../chunk-APBOWWSV.js';
+import '../chunk-S4AJTLLN.js';
+import '../chunk-AF5BIELI.js';
+import '../chunk-TGFNQBKC.js';
+import '../chunk-HQTUFVMM.js';
+import '../chunk-4E5VV4QY.js';
+import '../chunk-W6WQ5UP7.js';
+import '../chunk-6NYR73Y7.js';
+import '../chunk-MD2U6S4N.js';
+import '../chunk-3G5QL4F4.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/devtools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/environments/index.d.ts

@@ -0,0 +1,93 @@
+import { Group, Object3D } from 'three';
+
+/**
+ * The implementation behind `@oeave/bakery3/environments`. `index.ts` lists
+ * what is public.
+ */
+
+declare const ENVIRONMENT_SHAPES: readonly ["sphere", "groundSphere", "floor"];
+declare const ENVIRONMENT_SHADERS: readonly ["gradient", "bands", "blobs", "horizon"];
+/**
+ * `dark`: an ink dome with colored light in it, over a dark, glossy ground,
+ * the brand's own look. `colorful`: the same ground under more of that light.
+ * `light`: a pale dome with soft color, over a warm matte ground.
+ */
+declare const ENVIRONMENT_MODES: readonly ["dark", "colorful", "light"];
+type EnvironmentShape = (typeof ENVIRONMENT_SHAPES)[number];
+type EnvironmentShader = (typeof ENVIRONMENT_SHADERS)[number];
+type EnvironmentMode = (typeof ENVIRONMENT_MODES)[number];
+type EnvironmentOptions = {
+    /**
+     * `sphere`: an inward-facing dome of `radius` around the origin.
+     * `groundSphere`: the same dome with its lower part flattened onto y = 0,
+     * so shadows land on it. `floor`: a disc of `radius` at y = 0 whose color
+     * and opacity fade with distance, so its edge never shows.
+     */
+    shape: EnvironmentShape;
+    shader: EnvironmentShader;
+    /**
+     * Which palette and ground the environment defaults to. `dark` unless told
+     * otherwise. A `palette` overrides the colors; the ground still follows
+     * the mode.
+     */
+    mode?: EnvironmentMode;
+    /**
+     * Two to four CSS hex colors, darkest first. Each shader has a default
+     * per mode. What each slot means:
+     *
+     * - `gradient`: bottom to top (center to rim on a floor)
+     * - `bands`: the base, then the band colors in turn
+     * - `blobs`: the base, then the blob colors in turn
+     * - `horizon`: the dome, the horizon ring, the key glow
+     */
+    palette?: string[];
+    /**
+     * Emission strength, in the units the renderer traces with: a dome at
+     * `1` emits the radiance an HDRI pixel of value 1 would. Meaningless for
+     * the `floor` shape, which is lit, not lit from. Defaults per mode: a dark
+     * dome needs its few bright patches to carry the whole scene, so it emits
+     * harder (`3` dark, `2.5` colorful, `1.2` light).
+     */
+    intensity?: number;
+    /** Dome or disc radius in meters. Default `12`. */
+    radius?: number;
+    /** Seeds blob placement and the key glow's side. Default `1`. */
+    seed?: number;
+    /**
+     * A phase, in seconds, baked into the shader when it is built: it turns
+     * the bands and rotates the blobs, and is the same number in the viewport
+     * and in the render. Default `0`.
+     */
+    time?: number;
+    /**
+     * Add a viewport-only fill light. The dome is a real light in the render,
+     * but a rasterizer takes no light from an emissive mesh, so without a fill
+     * a product under a dark dome previews black. The fill is a hemisphere
+     * light in the dome's own colors (sky and ground from the palette, white
+     * over warm ground in light mode), marked `userData.bakery3.exclude` so it
+     * never reaches the manifest. The two halves differ on the product on
+     * purpose (a flat two-tone fill live, the dome's own light in the render).
+     * The dome is the same in both; the glossy ground of a dark or colorful
+     * dome is not, because in the render it reflects the dome (a colorful
+     * horizon lays a band of its color across it) and a rasterizer reflects
+     * no mesh. Default `false`.
+     */
+    fill?: boolean;
+};
+/**
+ * The options an environment was built with, defaults filled in. The fill is
+ * not part of it: it is a viewport aid, not the environment.
+ */
+type EnvironmentSpec = Required<Omit<EnvironmentOptions, 'fill'>>;
+/**
+ * Build an environment. Returns a `Group` holding one mesh, named
+ * `bakery3-environment-<shape>-<shader>`, with the resolved options on
+ * `userData.bakery3Preset.environment`. The product stands at the origin,
+ * on y = 0.
+ */
+declare function createEnvironment(options: EnvironmentOptions): Group;
+/** The spec a `createEnvironment()` group was built with, or `undefined`
+ *  for anything else. */
+declare function environmentSpecOf(object: Object3D): EnvironmentSpec | undefined;
+
+export { ENVIRONMENT_MODES, ENVIRONMENT_SHADERS, ENVIRONMENT_SHAPES, type EnvironmentMode, type EnvironmentOptions, type EnvironmentShader, type EnvironmentShape, type EnvironmentSpec, createEnvironment, environmentSpecOf };