@bluepic/embed 0.4.0-next.99 → 0.5.1

package/dist/util/assetAuth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Credentials for the GATED brand-portal asset routes
+ * (`/api/public/campaigns/:uid/assets/:assetId/{download|preview|document}`).
+ *
+ * A protected campaign is unlocked either with its password or by signing in;
+ * the config and serial fetches already carry that proof, but the asset bytes
+ * are requested separately — by a `fetch()` (download, viewer parsing) or by a
+ * media element's `src` (audio, video, image), which cannot carry headers at
+ * all. This module is the ONE place that knows how to attach the proof to
+ * either kind of request, so the two can never drift apart:
+ *
+ *  - `assetRequestHeaders` → `X-Bluepic-Password` / `Authorization: Bearer …`
+ *  - `withAssetAuthQuery`  → `?password=…` / `?access_token=…`
+ *
+ * Prefer the headers wherever a `fetch()` is used; the query form exists only
+ * for `src` attributes. An empty auth object leaves headers and URLs untouched,
+ * so a public campaign behaves exactly as before.
+ */
+export type AssetAuth = {
+    /** The campaign password the visitor unlocked with, if any. */
+    password?: string;
+    /** The signed-in visitor's Auth0 access token, if any. */
+    accessToken?: string;
+};
+/** Query parameter names the API accepts for media `src` URLs. */
+export declare const ASSET_AUTH_QUERY_PASSWORD = "password";
+export declare const ASSET_AUTH_QUERY_ACCESS_TOKEN = "access_token";
+/** Headers for a `fetch()` of gated asset bytes. `{}` when nothing to attach. */
+export declare function assetRequestHeaders(auth?: AssetAuth | null): Record<string, string>;
+/**
+ * The same proof as query parameters, for `<img>`/`<video>`/`<audio>` sources
+ * that cannot carry headers. Returns `url` unchanged when there is nothing to
+ * attach. Existing query parameters (and a hash) are preserved.
+ */
+export declare function withAssetAuthQuery(url: string, auth?: AssetAuth | null): string;

package/dist/util/audioPreview.d.ts

@@ -0,0 +1,8 @@
+export declare function useAudioPlayback(): {
+    toggle: (src: string | (() => string | Promise<string>), mediaEl?: HTMLMediaElement) => Promise<void>;
+    stop: () => void;
+    playing: import("vue").Ref<boolean, boolean>;
+    loading: import("vue").Ref<boolean, boolean>;
+    progress: import("vue").Ref<number, number>;
+    ended: import("vue").Ref<boolean, boolean>;
+};

package/dist/util/batch/csv.d.ts

@@ -0,0 +1,58 @@
+import { Studio } from '@bluepic/types';
+import type { BatchRow } from './useBatchRows';
+import { type BatchColumnField } from './fields';
+/** The formats a CSV result link can point at, plus the prepopulated editor link. */
+export type BatchCsvFormat = Studio.UrlRenderFormat | 'template-link';
+/** Header of the result column. Stable: re-imports recognise and ignore it. */
+export declare const BATCH_CSV_RESULT_COLUMN = "bluepic_result";
+export interface BatchCsvOptions {
+    format: BatchCsvFormat;
+    /** `https://image.bluepic.io` / `https://image-staging.bluepic.io` (no trailing slash). */
+    urlRenderBaseUrl: string;
+    templateId: string;
+    /** Readable URL form when both are known: `/<orgSlug>/<alias>.<ext>`. */
+    orgSlug?: string;
+    templateAlias?: string | null;
+    /** Multi-canvas: the canvas the editor shows — becomes the extra path segment. */
+    canvasId?: string;
+    /** The editor's own URL without query (`https://template.bluepic.io/<slug>/<templateId>[/<canvas>]`). */
+    templateLinkBaseUrl: string;
+    /** `,` (default) or `;` for spreadsheets in `;` locales. */
+    delimiter?: ',' | ';';
+}
+export interface BatchCsvResult {
+    csv: string;
+    /** The per-row result links, in row order. */
+    links: string[];
+    /** Rows whose URL-render query exceeds the API's byte budget (1-based indices). */
+    overBudget: number[];
+    /** `bluepic_result` header + one binding key per data column. */
+    header: string[];
+}
+/** A binding value as a CSV cell: image objects become their src, other objects JSON. */
+export declare function cellValue(value: unknown): string;
+/** Path of the render URL: alias form when the team + alias are known, else the id form. */
+export declare function urlRenderPath(opts: Pick<BatchCsvOptions, 'templateId' | 'orgSlug' | 'templateAlias' | 'canvasId'>, ext: string): string;
+/** The result link for one row, or null when the format has no link (never happens today). */
+export declare function buildResultLink(row: BatchRow, columns: BatchColumnField[], opts: BatchCsvOptions): {
+    url: string;
+    overBudget: boolean;
+};
+/**
+ * The batch as a spreadsheet: one column per binding key (so a re-import maps
+ * 1:1), image values flattened to their src, and a last column with the
+ * result link per row. UTF-8 with BOM so Excel opens it correctly.
+ */
+export declare function buildBatchCsv(rows: BatchRow[], columns: BatchColumnField[], opts: BatchCsvOptions): BatchCsvResult;
+export interface PrewarmProgress {
+    done: number;
+    total: number;
+    failed: number;
+}
+/**
+ * Request every link once so the render lands in the API's cache (and is
+ * billed) now, not when a recipient first opens the sheet. Videos one at a
+ * time, images four at a time. `no-cors`: we only need the request to happen,
+ * not to read the bytes.
+ */
+export declare function prewarmLinks(links: string[], isVideo: boolean, onProgress?: (progress: PrewarmProgress) => void, signal?: AbortSignal): Promise<PrewarmProgress>;

package/dist/util/batch/export.d.ts

@@ -0,0 +1,92 @@
+import { type Template } from '@bluepic/types';
+import { imageFormats, videoFormats, type RenderRemoteOptions, type RenderRemoteVideoOptions } from '../export';
+import type { BatchRow } from './useBatchRows';
+export type BatchImageFormat = keyof typeof imageFormats;
+export type BatchVideoFormat = keyof typeof videoFormats;
+export type BatchFileFormat = BatchImageFormat | BatchVideoFormat;
+/** How exported files are named: by their 1-based index, or by a Text binding's value. */
+export type BatchNaming = {
+    kind: 'index';
+} | {
+    kind: 'binding';
+    key: string;
+};
+export interface BatchFileExportContext {
+    serial: Template.Serial;
+    campaignId: number;
+    templateId: string;
+    canvasId?: string;
+    /** Template name — the zip name and the index-naming prefix. */
+    name: string;
+    remoteOptions: RenderRemoteOptions;
+    remoteVideoOptions: RenderRemoteVideoOptions;
+    /**
+     * Called once per successfully rendered row with that row's data and the
+     * media it produced. The editor binds it to its per-output credit consumer,
+     * so each row is charged exactly once per session (and never twice for the
+     * same content) at the batch rate for that medium.
+     */
+    consumeOutput: (data: Record<string, unknown>, kind: 'image' | 'video') => Promise<void>;
+    /** Cooperative cancellation: checked before every row starts. */
+    signal?: AbortSignal;
+}
+export interface BatchExportProgress {
+    /** Rows finished (rendered + consumed). */
+    done: number;
+    total: number;
+    /** 0..1 progress inside the row being rendered (videos stream it; images jump). */
+    current: number;
+    /** 1-based index of the row being rendered. */
+    currentIndex: number;
+    /** Rows that threw (rendering or consuming) and were skipped. */
+    failed: number;
+}
+/** A row that did not make it into the output. `index` is 0-based (row 1 is index 0). */
+export interface BatchFailedRow {
+    index: number;
+    message: string;
+}
+export interface BatchFileExportResult {
+    /** One blob per exported file (a multi-frame template yields several per row). */
+    files: {
+        name: string;
+        blob: Blob;
+    }[];
+    /** The zip (or the single file) ready to hand out, plus its file name. */
+    output: {
+        blob: Blob;
+        fileName: string;
+    };
+    cancelled: boolean;
+    /**
+     * Rows missing from `output` because they threw. Successful rows were still
+     * consumed (charged) and packed; a failed row was never consumed.
+     */
+    failedRows: BatchFailedRow[];
+}
+/** Image rows render four at a time, videos strictly one after the other (decision 2026-09-02). */
+export declare const BATCH_IMAGE_CONCURRENCY = 4;
+export declare const BATCH_VIDEO_CONCURRENCY = 1;
+/** A file-system-safe base name from a binding value; empty when nothing usable remains. */
+export declare function sanitizeFileName(value: unknown): string;
+/** Base names for every row, unique (`name`, `name_2`, `name_3`, …). */
+export declare function batchFileBaseNames(rows: BatchRow[], naming: BatchNaming, prefix: string): string[];
+/**
+ * Render every row server-side and pack the results.
+ *
+ * Images go through the campaign render endpoint (which does not charge — the
+ * per-row `consumeOutput` does), videos through the video render service.
+ * Rows are rendered in order and isolated from each other: a row that throws
+ * is recorded in `failedRows` (never consumed, never packed) and the rest
+ * carry on, so one bad row cannot discard the already-charged good ones. Only
+ * when every row failed is there nothing to hand out, and the export throws.
+ */
+export declare function exportBatchFiles(rows: BatchRow[], format: BatchFileFormat, naming: BatchNaming, ctx: BatchFileExportContext, onProgress?: (progress: BatchExportProgress) => void): Promise<BatchFileExportResult>;
+/** One file stays a file; several become a zip named after the template. */
+export declare function packFiles(files: {
+    name: string;
+    blob: Blob;
+}[], zipBaseName: string): Promise<{
+    blob: Blob;
+    fileName: string;
+}>;

package/dist/util/batch/fields.d.ts

@@ -0,0 +1,22 @@
+import type { BluepicField, Template } from '@bluepic/types';
+/** A field as a batch-table column: the field plus where it came from. */
+export interface BatchColumnField {
+    field: BluepicField;
+    /** Stable key for the column (the field's first binding, else its index path). */
+    key: string;
+    /** Group breadcrumb the field lives in, for the header caption. */
+    groupPath: string[];
+    /** 1-based slide the field belongs to on multi-slide templates, else undefined. */
+    slide?: number;
+}
+/**
+ * Every value-bearing field of a serial as a flat column list. Groups are
+ * flattened (their children become columns, the group's description is kept
+ * as a breadcrumb); instructions are dropped.
+ */
+export declare function flattenBatchFields(serial: Template.Serial | undefined): BatchColumnField[];
+/** The binding keys a field writes, in model order. */
+export declare function bindingKeysOf(field: BluepicField): string[];
+export declare function isImageField(field: BluepicField): boolean;
+/** A Text binding a file name / CSV column can be derived from. */
+export declare function isTextField(field: BluepicField): boolean;

package/dist/util/batch/parseCSV.d.ts

@@ -0,0 +1,72 @@
+export type LocaleConfig = 'de' | 'en' | 'auto';
+export type CSVDelimiter = ',' | ';' | 'auto';
+type StringDescriptor = {
+    type: 'string';
+    value: string;
+};
+type NumberDescriptor = {
+    type: 'number';
+    value: number;
+    unit?: string;
+};
+type BooleanDescriptor = {
+    type: 'boolean';
+    value: boolean;
+};
+type DateDescriptor = {
+    type: 'date';
+    value: Date;
+    format: string;
+};
+type URLDescriptor = {
+    type: 'url';
+    value: string;
+    protocol: string;
+};
+type ColorDescriptor = {
+    type: 'color';
+    value: string;
+    rgb: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    hex: string;
+    hsl: {
+        h: number;
+        s: number;
+        l: number;
+    };
+    alpha: number;
+    format: 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'name' | 'keyword';
+};
+type JSONObjectDescriptor = {
+    type: 'json-object';
+    value: Record<string, unknown>;
+};
+type JSONArrayDescriptor = {
+    type: 'json-array';
+    value: unknown[];
+};
+type NullDescriptor = {
+    type: 'null';
+    value: null;
+};
+export type CellDescriptor = StringDescriptor | NumberDescriptor | BooleanDescriptor | DateDescriptor | URLDescriptor | ColorDescriptor | JSONObjectDescriptor | JSONArrayDescriptor | NullDescriptor;
+export type InferredTable = CellDescriptor[][];
+export declare function isString(cell: CellDescriptor): cell is StringDescriptor;
+export declare function isNumber(cell: CellDescriptor): cell is NumberDescriptor;
+export declare function isBoolean(cell: CellDescriptor): cell is BooleanDescriptor;
+export declare function isDate(cell: CellDescriptor): cell is DateDescriptor;
+export declare function isURL(cell: CellDescriptor): cell is URLDescriptor;
+export declare function isColor(cell: CellDescriptor): cell is ColorDescriptor;
+export declare function isJSONObject(cell: CellDescriptor): cell is JSONObjectDescriptor;
+export declare function isJSONArray(cell: CellDescriptor): cell is JSONArrayDescriptor;
+export declare function isNull(cell: CellDescriptor): cell is NullDescriptor;
+export declare function exampleUsage(inferredTable: InferredTable): void;
+export declare function inferredCellToString(cell: CellDescriptor): string;
+export declare function heuristicInferTable(rawTable: string[][], locale: LocaleConfig): InferredTable;
+export declare function detectCSVDelimiter(raw: string): ',' | ';';
+export declare function parseCSVRaw(raw: string, delimiter?: ',' | ';'): string[][];
+export declare function parseCSV(raw: string, locale: LocaleConfig, delimiter?: CSVDelimiter): InferredTable;
+export {};

package/dist/util/batch/useBatchRows.d.ts

@@ -0,0 +1,67 @@
+import { type Ref } from 'vue';
+/**
+ * Batch editor data model.
+ *
+ * A row is one set of binding values — exactly the object the live template
+ * and the renderer consume as `data` — plus a stable id. Ids (not indices) are
+ * what selection and the active row point at, so deleting or reordering rows
+ * never shifts the meaning of "row 3 is selected".
+ */
+export interface BatchRow {
+    id: string;
+    data: Record<string, unknown>;
+}
+/** Hard cap on rows per batch (decision 2026-09-02). */
+export declare const BATCH_MAX_ROWS = 1024;
+export interface UseBatchRowsOptions {
+    /** The bindings every row starts from (`serial.bindings`). */
+    seed: () => Record<string, unknown>;
+    /**
+     * sessionStorage key. Rows survive a reload / a canvas switch (the editor
+     * re-mounts per canvas) under it. Undefined = no persistence.
+     */
+    storageKey: Ref<string | undefined>;
+    /** Rows the host hands in (`v-model:batchRows`); take precedence over storage. */
+    initial?: BatchRow[];
+}
+export declare function useBatchRows(opts: UseBatchRowsOptions): {
+    rows: Ref<{
+        id: string;
+        data: Record<string, unknown>;
+    }[], BatchRow[] | {
+        id: string;
+        data: Record<string, unknown>;
+    }[]>;
+    activeRowId: Ref<string, string>;
+    activeIndex: import("vue").ComputedRef<number>;
+    activeRow: import("vue").ComputedRef<{
+        id: string;
+        data: Record<string, unknown>;
+    }>;
+    selectedIds: Ref<Set<string> & Omit<Set<string>, keyof Set<any>>, Set<string> | (Set<string> & Omit<Set<string>, keyof Set<any>>)>;
+    selectedRows: import("vue").ComputedRef<{
+        id: string;
+        data: Record<string, unknown>;
+    }[]>;
+    targetRows: import("vue").ComputedRef<{
+        id: string;
+        data: Record<string, unknown>;
+    }[]>;
+    allSelected: import("vue").ComputedRef<boolean>;
+    atCapacity: import("vue").ComputedRef<boolean>;
+    setActive: (id: string) => void;
+    activateOffset: (delta: number) => void;
+    addRow: (sourceId?: string) => BatchRow | undefined;
+    removeRows: (ids: string[]) => void;
+    moveRow: (id: string, delta: -1 | 1) => void;
+    toggleSelected: (id: string, on?: boolean) => void;
+    selectAll: (on: boolean) => void;
+    ensureRowsFrom: (fromIndex: number, count: number) => BatchRow[];
+    importRows: (datasets: Record<string, unknown>[], mode: "append" | "replace") => {
+        imported: number;
+        dropped: number;
+    };
+    replaceAll: (next: BatchRow[]) => void;
+    makeRow: (data?: Record<string, unknown>) => BatchRow;
+};
+export type BatchRowsModel = ReturnType<typeof useBatchRows>;

package/dist/util/cloneDeep.d.ts

@@ -3,11 +3,11 @@
  *
  * Uses the native `structuredClone`, which handles plain objects, arrays,
  * Dates, Maps, Sets, typed arrays and circular references. Vue reactive
- * proxies are unwrapped via `toRaw` first so the clone is a plain,
- * non-reactive copy (and to avoid cloning through reactivity metadata).
+ * proxies are unwrapped first — at every depth, see `toRawDeep` — so the
+ * clone is a plain, non-reactive copy.
  *
- * Note: `structuredClone` throws on non-cloneable values (functions, DOM
- * nodes, class instances with methods). All call sites clone JSON-like data
- * models, so this is safe here.
+ * Note: `structuredClone` still throws on genuinely non-cloneable values
+ * (functions, DOM nodes). All call sites clone JSON-like data models, so this
+ * is safe here.
  */
 export declare function cloneDeep<T>(value: T): T;

package/dist/util/cloudflareImages.d.ts

@@ -16,4 +16,11 @@ export declare function parseCloudflareImagesDeliveryUrl(src: string): {
 };
 export declare function uploadImage(apiBaseUrl: string, templateId: string, context: {
     field?: Template.Fields.BluepicField;
-}, blob: Blob, name: string, onUploadProgress: (uploaded: number, total: number) => void): Promise<any>;
+}, blob: Blob, name: string, onUploadProgress: (uploaded: number, total: number) => void): Promise<{
+    key: string;
+    type: string;
+    url: string;
+    uploadedAt: string;
+    imageId?: string | undefined;
+    deliveryBase?: string | undefined;
+}>;

package/dist/util/contextCapture.d.ts

@@ -1 +1,20 @@
+/**
+ * Everything the host app injects, flattened so a popup — which renders in a
+ * SEPARATE Vue app (see PopupProvider) — can be given the same context.
+ *
+ * APP-LEVEL PROVIDES ARE THE HALF THIS USED TO MISS, and they are the half
+ * that matters most. Vue builds a component's provides as
+ *
+ *     provides: parent ? parent.provides : Object.create(appContext.provides)
+ *
+ * so anything installed with `app.use(...)` or `app.provide(...)` — the router
+ * above all, but equally a store or an i18n instance — lives on
+ * `appContext.provides` and reaches components through the PROTOTYPE chain.
+ * `Object.assign` copies own properties only, so walking the parent chain
+ * never saw them: `useRouter()` inside any popup returned undefined, and every
+ * `router.push` in a dialog, drawer or toast silently did nothing.
+ *
+ * Merged FIRST, so a component-level `provide()` closer to the caller still
+ * wins over an app-level one of the same key.
+ */
 export declare function captureCurrentContext(): Record<string | symbol, any>;

package/dist/util/export.d.ts

@@ -1,4 +1,4 @@
-import { FieldsBridge, Render, Studio, Template } from '@bluepic/types';
+import { BillingV3, FieldsBridge, Render, Studio, Template } from '@bluepic/types';
 import { Ref } from 'vue';
 import { z } from '@hono/zod-openapi';
 import BxLiveTemplate from '../components/TemplateEditor/BxLiveTemplate.vue';
@@ -16,41 +16,56 @@ export declare const videoFormats: {
 export type RenderRemoteOptions = {
     apiBaseUrl: string;
     env: 'dev' | 'prod';
-    enforceFallbackService: boolean;
     bearerToken?: string;
     password?: string;
 };
 export declare function renderSerialRemote(campaignId: number, templateId: string, data: {
     [k: string]: unknown;
-}, width: number, height: number, framesX: number, framesY: number, format: keyof typeof imageFormats, opts: RenderRemoteOptions): Promise<Blob>;
+}, width: number, height: number, framesX: number, framesY: number, format: keyof typeof imageFormats, opts: RenderRemoteOptions, 
+/**
+ * Multi-canvas templates (canvases v2): the canvas to render. The server
+ * refetches the persisted serial (root = Default canvas) by templateId, so
+ * without this it would render the Default format regardless of what the
+ * user selected. OMITTED (not sent at all) when unset — the request stays
+ * byte-identical for single-format templates.
+ */
+canvasId?: string): Promise<Blob>;
+/** @deprecated Video renders go through the bx-studio-api campaign route now; kept so hosts passing it keep compiling. */
 export type RenderRemoteVideoOptions = {
     remoteVideoRenderBaseUrl: string;
 };
-export declare function renderVideoRemote(serial: Template.Serial, data: {
+/**
+ * Server-side video export via `POST {api}/api/public/render/campaign` with a
+ * video format. The API resolves the template's canvas/animation itself, picks
+ * the backend (elya first, the Cloudflare container fan-out as the fallback)
+ * and meters the credit once the render succeeds — so the client never charges
+ * a server-rendered video. The response is the render service's SSE
+ * (keyframe / encode_video progress, then `end{result}` with the hosted URL).
+ */
+export declare function renderVideoRemote(campaignId: number, templateId: string, data: {
     [k: string]: unknown;
-}, width: number, height: number, format: z.infer<typeof Render.videoFormatSchema>, duration: number, videoOpts: {
-    fps: number;
-    vcodec: z.infer<typeof Render.vcodecSchema>;
-    acodec: z.infer<typeof Render.acodecSchema>;
-    pix_fmt: z.infer<typeof Render.pixFmtSchema>;
-    audio: {
-        itsoffset: number;
-        src: string;
-    }[];
-}, options: RenderRemoteVideoOptions, onProgress: (progress: Render.RenderProgressEvent) => void): Promise<{
+}, format: z.infer<typeof Render.videoFormatSchema>, opts: RenderRemoteOptions, onProgress: (progress: Render.RenderProgressEvent) => void, 
+/** Multi-canvas: the selected canvas, omitted for single-format templates. */
+canvasId?: string): Promise<{
     files: string[];
     creditsConsumed: number;
 }>;
 export declare function renderSerialAsImages(bxLiveTemplateComponent: InstanceType<typeof BxLiveTemplate>, serial: Template.Serial, data: {
     [k: string]: unknown;
-}, format: keyof typeof imageFormats, campaignId: number, templateId: string, remoteOptions: RenderRemoteOptions, enforceServerSideRendering: boolean, watermark: boolean, sessionState: string): Promise<{
+}, format: keyof typeof imageFormats, campaignId: number, templateId: string, remoteOptions: RenderRemoteOptions, enforceServerSideRendering: boolean, watermark: boolean, sessionState: string, 
+/** Multi-canvas: the selected canvas — remote render only; the LOCAL path already renders the materialized `serial`. */
+canvasId?: string, 
+/** Local render only: see the option of the same name on `BxLiveTemplate.render`. */
+svgLoadWaitDelay?: number): Promise<{
     files: Blob[];
     renderLocation: RenderLocation;
     clientRenderFailed: boolean;
 }>;
 export declare function useTemplateExport(serial: Ref<Template.Serial | undefined>, data: Ref<{
     [k: string]: unknown;
-}>, exportOptions: Ref<z.infer<typeof Studio.campaignConfigSchema>['export']>, templateId: Ref<string | undefined>, name: Ref<string | undefined>, bxLiveTemplateComponentRef: Ref<InstanceType<typeof BxLiveTemplate> | undefined>, campaignId: Ref<number | undefined>, remoteOptions: RenderRemoteOptions, remoteVideoOptions: RenderRemoteVideoOptions, enforceServerSideRendering: Ref<boolean>, enforceVideoServerSideRendering: Ref<boolean>, timecode: Ref<number>, consumeCreditsOnRender: Ref<boolean>, watermark: Ref<boolean>, bridge: Ref<FieldsBridge>, preCacheLocalRendering: Ref<boolean>, 
+}>, exportOptions: Ref<z.infer<typeof Studio.campaignConfigSchema>['export']>, templateId: Ref<string | undefined>, name: Ref<string | undefined>, bxLiveTemplateComponentRef: Ref<InstanceType<typeof BxLiveTemplate> | undefined>, campaignId: Ref<number | undefined>, remoteOptions: RenderRemoteOptions, 
+/** @deprecated unused — video renders go through the API campaign route (see renderVideoRemote). */
+_remoteVideoOptions: RenderRemoteVideoOptions, enforceServerSideRendering: Ref<boolean>, enforceVideoServerSideRendering: Ref<boolean>, timecode: Ref<number>, consumeCreditsOnRender: Ref<boolean>, watermark: Ref<boolean>, bridge: Ref<FieldsBridge>, preCacheLocalRendering: Ref<boolean>, 
 /** Host-provided abstract analytics sink. When absent, all analytics calls are no-ops. */
 analytics: Ref<ExportAnalyticsSink | undefined>, 
 /**
@@ -58,13 +73,45 @@ analytics: Ref<ExportAnalyticsSink | undefined>,
  * already resolved by the caller. When undefined, we fall back to the
  * template's serial caption (today's behavior).
  */
-campaignCaption?: Ref<string | undefined>): {
+campaignCaption?: Ref<string | undefined>, 
+/**
+ * Multi-canvas templates (canvases v2): the id of the canvas the editor is
+ * showing. `serial` is already the MATERIALIZED serial for it (local renders
+ * need nothing extra); this only rides on the remote render request so the
+ * server materializes the same canvas from the serial it refetches.
+ * Undefined (the default) = single-format / Default canvas = today's payload.
+ */
+canvasId?: Ref<string | undefined>, 
+/**
+ * Milliseconds `renderSVG` sleeps between the serialized SVG's `load` event and
+ * drawing it (see `BxLiveTemplate.render`). Undefined = the raster default of
+ * 150ms, i.e. today's behaviour. A host can lower it to reclaim a flat per-render
+ * tax that matters most where renders are repeated — batch export, local video
+ * frames — at the risk of drawing before an engine has decoded the inlined
+ * fonts/images. Kept host-settable precisely so that trade-off can be measured
+ * rather than guessed.
+ */
+svgLoadWaitDelay?: Ref<number | undefined>): {
     triggerExport: () => Promise<void>;
+    consumeOutputFor: (rowData: {
+        [k: string]: unknown;
+    }, kind?: "image" | "video") => Promise<void>;
     preCacheLocalRender: () => Promise<void>;
     rendering: Ref<boolean, boolean>;
     videoRenderingProgress: Ref<number | undefined, number | undefined>;
 };
-export declare function consumeCredits(apiBaseUrl: string, env: 'dev' | 'prod', campaignId: number, templateId: string, sessionState: string, billingKey: number): Promise<void>;
+/**
+ * Report ONE delivered output to the server.
+ *
+ * The SDK names the surface (`usage`) and describes what it produced
+ * (`assets`) — it never sends, and never learns, a price. The rate table lives
+ * server-side in `@bluepic/types` (`BillingV3.calculateCenticreditConsumption`).
+ */
+export declare function consumeCredits(apiBaseUrl: string, env: 'dev' | 'prod', campaignId: number, templateId: string, sessionState: string, billingKey: number, 
+/** Which surface produced this. Omitted = a single editor export. */
+usage?: Studio.ConsumeRenderCreditsUsage, 
+/** One entry per delivered file — an array of one for a single export. */
+assets?: BillingV3.BillableUsageAsset[]): Promise<void>;
 export declare function hasMobileShareCapability(files: File[]): boolean;
 export declare function blobsToShareFiles(files: Blob[], baseName: string): File[];
 export declare function performDownload(files: Blob[], baseName: string): Promise<void>;

package/dist/util/fieldHints/chipAction.d.ts

@@ -0,0 +1,23 @@
+import type { BluepicField } from '@bluepic/types';
+/**
+ * What clicking a chip does.
+ *
+ * There is no per-field hint MODE — hints are simply on or off for the whole
+ * campaign (`config.hints`). What a chip does is inferred from the field itself:
+ *
+ * - `upload` — the field accepts a device upload. Clicking goes straight to the
+ *   file picker, which is the only thing anyone wants from a chip sitting on a
+ *   picture. Other sources stay one tap away through the field itself.
+ * - `focus`  — everything else, including image fields restricted to libraries.
+ *   The chip then does what the hitbox around it does: scroll the field into
+ *   view and focus its control, so the next keystroke already types into it.
+ */
+export type ChipAction = 'upload' | 'focus';
+export declare function fieldHasChip(fieldType: BluepicField['type']): boolean;
+/**
+ * `field.props` entries may be author expressions (functions) rather than
+ * literals, so a prop can only be read through the host's evaluator — the same
+ * `wrapFieldProps` treatment `FieldsList` gives every field component.
+ */
+export declare function readFieldProp<T>(value: T | (() => T), evaluate?: (fn: Function) => unknown): T | undefined;
+export declare function chipActionFor(field: BluepicField, evaluate?: (fn: Function) => unknown): ChipAction;

package/dist/util/fieldHints/fieldFocus.d.ts

@@ -0,0 +1,81 @@
+import { type InjectionKey } from 'vue';
+import type { BluepicField } from '@bluepic/types';
+/**
+ * Opens a field's own primary editing flow — for an image field, the "Select
+ * image" popup (or the device file picker, when that's all it offers).
+ *
+ * Registered BY the field component, because only it knows that flow. Having the
+ * overlay reproduce it would mean duplicating image libraries, cropping,
+ * background removal and auto-crop up there, and then watching the two copies
+ * drift.
+ */
+export type FieldActivator = () => void;
+/**
+ * Connects a hint on the preview to the field control that drives it.
+ *
+ * The two halves live far apart — the hint renders inside zoompinch's matrix
+ * slot, the control somewhere down a recursive `FieldsList` — so this is
+ * provided by `BxTemplateEditor` and injected at both ends rather than threaded
+ * through props.
+ *
+ * BOTH layouts register their elements here, because both end up focusing one:
+ * mobile mounts every swiper slide at once, so the control exists even while the
+ * swiper is still travelling to it. What differs is how it is brought on screen
+ * — desktop scrolls the panel, mobile swipes — and only `BxTemplateEditor` can
+ * do the latter, which is why `focus()` is a controller method and not just a
+ * lookup.
+ */
+export type FieldFocusController = {
+    register(field: BluepicField, el: HTMLElement | null): void;
+    focus(field: BluepicField): void;
+    /** Field components self-register; pass `null` on unmount. */
+    registerActivator(field: BluepicField, activate: FieldActivator | null): void;
+    /**
+     * Runs the field's own flow. Returns false when the field never registered
+     * one, so the caller can fall back to plain focus instead of doing nothing.
+     */
+    activate(field: BluepicField): boolean;
+};
+export declare const FIELD_FOCUS_KEY: InjectionKey<FieldFocusController>;
+export declare function provideFieldFocus(controller: FieldFocusController): void;
+/** Absent whenever the fields tree is rendered outside `BxTemplateEditor`. */
+export declare function useFieldFocus(): FieldFocusController | undefined;
+/** Marks the focused field for a moment so the eye can follow the jump. */
+export declare const FIELD_FOCUS_FLASH_CLASS = "bx-field-hint-target";
+/** Held while the pointer rests on the field's hitbox in the live preview. */
+export declare const FIELD_HOVER_CLASS = "bx-field-hint-hover";
+/**
+ * Scroll a field's control into view, flash it, and focus what you type into —
+ * falling back to whatever else in it can take focus.
+ *
+ * `block: 'nearest'` rather than 'center': the fields panel is a scroll
+ * container, and centering yanks the whole list even when the target was
+ * already comfortably visible.
+ *
+ * `scroll: false` for the MOBILE layout. Every slide is mounted at once inside
+ * swiper's transformed track, so a field that is off screen is off screen by
+ * TRANSFORM, not by scroll position — asking the browser to scroll it into view
+ * shifts the track's own scroller and leaves swiper's idea of the offset wrong.
+ * There, `slideTo` does the travelling and this only has to focus.
+ */
+export declare function revealFieldElement(el: HTMLElement | null | undefined, { scroll }?: {
+    scroll?: boolean;
+}): HTMLElement | undefined;
+/**
+ * The element/activator registry, keyed by the field object itself.
+ *
+ * A WeakMap (not a Map) because fields are plain objects off the serial — when
+ * the serial is swapped the old field objects should simply be collectable,
+ * with no unregister bookkeeping to get wrong.
+ */
+export declare function createFieldElementRegistry(): {
+    register(field: BluepicField, el: HTMLElement | null): void;
+    get(field: BluepicField): HTMLElement | undefined;
+    registerActivator(field: BluepicField, activate: FieldActivator | null): void;
+    activate(field: BluepicField): boolean;
+};
+/**
+ * Registers a field component's own editing flow for the lifetime of that
+ * component. A no-op outside `BxTemplateEditor`, where no controller is provided.
+ */
+export declare function useFieldActivator(field: () => BluepicField | undefined, activate: FieldActivator): void;