@pixerate/editor 0.23.0 → 0.25.0

package/dist/generation/index.d.cts

@@ -0,0 +1,1015 @@
+import { J as JsonSchema } from '../schema-DYDGdYL9.cjs';
+export { S as SchemaValidationError, v as validateJsonSchema } from '../schema-DYDGdYL9.cjs';
+import { A as AgentToolProvider } from '../registry-DnzpgY27.cjs';
+export { a as AgentTool, d as McpToolDefinition, e as McpToolResult } from '../registry-DnzpgY27.cjs';
+import { S as SourceMapSegment } from '../sourcemap-C8AH3MBQ.cjs';
+import { T as Template, P as PromptValues } from '../tokens-D7yXvUU6.cjs';
+import { S as StorageAdapter } from '../storage-BpFfspHm.cjs';
+export { a as MentionRoleSyntax, T as TextMention, f as findTextMentions, b as formatMentionText, s as setMentionRoleInText } from '../mention-text-CDnCFd3c.cjs';
+
+/**
+ * Declarative descriptions of generative models (what a model accepts) and of
+ * the requests sent to them. Everything here is plain data so capabilities can
+ * come from a server, be merged with local presentation overlays, and be
+ * turned into JSON Schema for agents.
+ */
+type GenerationMediaKind = 'image' | 'video' | 'audio' | 'text';
+/** The reference roles this library knows by name (labels, aliases, schema order). */
+type BuiltinReferenceRole = 'start_frame' | 'end_frame' | 'style_ref' | 'character_ref' | 'background_ref' | 'mask' | 'image_ref' | 'video_ref' | 'audio_ref';
+/**
+ * What a reference input (an asset) is used for. The built-in roles are
+ * listed in {@link REFERENCE_ROLES}; models may declare any other role name
+ * (e.g. `subject`, `pose`) in `references.roles`, which makes it valid for
+ * that model. Role names match {@link REFERENCE_ROLE_NAME_REGEX}.
+ */
+type ReferenceRole = BuiltinReferenceRole | (string & {});
+/** Valid role names: a letter, then letters, digits, `_` or `-`, not ending in `_` or `-`. */
+declare const REFERENCE_ROLE_NAME_REGEX: RegExp;
+/** True for a string usable as a role name. */
+declare function isReferenceRoleName(value: unknown): value is ReferenceRole;
+/** Every built-in reference role, in a stable display order. */
+declare const REFERENCE_ROLES: readonly BuiltinReferenceRole[];
+/** Human-readable default labels for reference roles. */
+declare const REFERENCE_ROLE_LABELS: Readonly<Record<BuiltinReferenceRole, string>>;
+/**
+ * Friendly role names accepted wherever a role is written by hand (asset
+ * mentions such as `@fox:style`, agent calls). A model that declares the
+ * alias itself (e.g. its own `style` role) keeps it; otherwise the alias maps
+ * to the built-in role. Keys are lower case.
+ */
+declare const REFERENCE_ROLE_ALIASES: Readonly<Record<string, BuiltinReferenceRole>>;
+/** Display label of a role: the model's label, the built-in label, or the name made readable. */
+declare function referenceRoleLabel(role: ReferenceRole, caps?: ModelCapabilities): string;
+/**
+ * Canonical role for a hand-written name: the name itself when the model
+ * declares it (or, without a model, when it is built in), else its alias
+ * ({@link REFERENCE_ROLE_ALIASES}, case-insensitive), else the trimmed name.
+ */
+declare function normalizeReferenceRole(role: string, caps?: ModelCapabilities): ReferenceRole;
+/**
+ * Whether `mediaType` (a MIME type such as `image/png`, or a media kind such
+ * as `image`) matches one of `accepts` (`image`, `image/*`, `image/png`).
+ * An empty or missing `accepts` accepts everything; an unknown media type
+ * only matches a missing `accepts`.
+ */
+declare function mediaTypeMatches(mediaType: string | undefined, accepts: readonly string[] | undefined): boolean;
+/** A choice from a fixed list. `options` order matters (low → high where it applies). */
+interface EnumCapability<T extends string | number = string> {
+    options: readonly T[];
+    default?: T;
+    /** Display labels by option value. */
+    labels?: Readonly<Record<string, string>>;
+}
+interface TextFieldCapability {
+    maxLength?: number;
+}
+interface PromptCapability extends TextFieldCapability {
+    /**
+     * Count the resolved prompt (templates expanded, variables substituted)
+     * against `maxLength` rather than the raw template text. Default `true`.
+     * Pass the resolved text to the planner as `resolvedPrompt`.
+     */
+    countResolved?: boolean;
+    /** The prompt must be non-empty. */
+    required?: boolean;
+}
+interface CountCapability {
+    /** Largest number of outputs per request. */
+    max: number;
+    /** Predefined choices; when given, requests snap to one of them. */
+    options?: readonly number[];
+    default?: number;
+}
+interface DurationCapability {
+    /** Seconds. */
+    min?: number;
+    max?: number;
+    /** Predefined choices; when given, requests snap to one of them. */
+    options?: readonly number[];
+    default?: number;
+    step?: number;
+}
+interface SeedCapability {
+    min?: number;
+    max?: number;
+}
+interface ReferenceRoleCapability {
+    /** Most references of this role. */
+    max: number;
+    /** Fewest references of this role (e.g. an image-to-video model needs a `start_frame`). */
+    min?: number;
+    label?: string;
+    description?: string;
+    /**
+     * Media accepted for this role: kinds (`image`), wildcards (`image/*`) or
+     * MIME types (`image/png`). Absent: anything. References whose
+     * `mediaType` does not match are dropped or rejected by the planner.
+     */
+    accepts?: readonly string[];
+}
+interface ReferenceCapability {
+    /** Supported roles and their per-role limits. Roles not listed are unsupported. */
+    roles: Partial<Readonly<Record<ReferenceRole, ReferenceRoleCapability>>>;
+    /** Most references across all roles. */
+    maxTotal?: number;
+}
+interface NumberParamSpec {
+    type: 'number' | 'integer';
+    min?: number;
+    max?: number;
+    step?: number;
+    default?: number;
+    label?: string;
+    description?: string;
+}
+interface EnumParamSpec {
+    type: 'enum';
+    options: readonly (string | number)[];
+    default?: string | number;
+    label?: string;
+    description?: string;
+}
+interface BooleanParamSpec {
+    type: 'boolean';
+    default?: boolean;
+    label?: string;
+    description?: string;
+}
+/** A model-specific parameter (`guidance`, `motion_strength`, `style`, …). */
+type ExtraParamSpec = NumberParamSpec | EnumParamSpec | BooleanParamSpec;
+/** Rough timing used for progress estimates (`expectedDurationFor`). */
+interface TimingCapability {
+    /** Fixed cost of one request in ms. */
+    baseMs: number;
+    /** Extra ms per output beyond the first. */
+    perItemMs?: number;
+    /** Extra ms per second of requested duration (video/audio). */
+    perSecondMs?: number;
+    /** Extra ms per megapixel of the requested resolution. */
+    perMegapixelMs?: number;
+}
+/** Presentation-only fields; overlays may set these (see `mergeCapabilities`). */
+interface CapabilityPresentation {
+    name?: string;
+    description?: string;
+    badges?: readonly string[];
+    icon?: string;
+    group?: string;
+}
+/** Everything a generative model accepts. Absent sections mean "unsupported". */
+interface ModelCapabilities extends CapabilityPresentation {
+    id: string;
+    media: GenerationMediaKind;
+    prompt?: PromptCapability;
+    /** Negative prompt support (`true` or limits). */
+    negativePrompt?: boolean | TextFieldCapability;
+    /** System prompt support (`true` or limits). */
+    systemPrompt?: boolean | TextFieldCapability;
+    /** E.g. `['1:1', '16:9', '9:16']`. */
+    aspectRatios?: EnumCapability<string>;
+    /** E.g. `['512x512', '1024x1024']`, `['720p', '1080p']` or `['1k', '2k', '4k']`, low → high. */
+    resolutions?: EnumCapability<string>;
+    /** Ordered low → high, e.g. `['draft', 'standard', 'high']`. */
+    quality?: EnumCapability<string>;
+    count?: CountCapability;
+    duration?: DurationCapability;
+    seed?: boolean | SeedCapability;
+    references?: ReferenceCapability;
+    /** Accepts a source to edit (`mode: 'edit'`). */
+    editing?: boolean;
+    /** Accepts a source plus a `mask` reference (`mode: 'inpaint'`). */
+    inpainting?: boolean;
+    params?: Readonly<Record<string, ExtraParamSpec>>;
+    timing?: TimingCapability;
+}
+interface GenerationReference {
+    /** Asset id (opaque to this library). */
+    id: string;
+    role: ReferenceRole;
+    url?: string;
+    /** MIME type or media kind, checked against the role's `accepts`. */
+    mediaType?: string;
+    /** Content hash of the asset when it was referenced (used by generation records). */
+    contentHash?: string;
+}
+type GenerationMode = 'generate' | 'edit' | 'inpaint';
+type GenerationParamValue = string | number | boolean;
+/** A request for one model. Every field is optional; the planner fills and fixes. */
+interface GenerationRequest {
+    model?: string;
+    prompt?: string;
+    negativePrompt?: string;
+    systemPrompt?: string;
+    aspectRatio?: string;
+    resolution?: string;
+    quality?: string;
+    count?: number;
+    /** Seconds. */
+    duration?: number;
+    seed?: number;
+    mode?: GenerationMode;
+    references?: GenerationReference[];
+    params?: Record<string, GenerationParamValue>;
+}
+/** Fields of {@link GenerationRequest} the planner knows about, in planning order. */
+declare const GENERATION_REQUEST_FIELDS: readonly ["model", "prompt", "negativePrompt", "systemPrompt", "aspectRatio", "resolution", "quality", "count", "duration", "seed", "mode", "references", "params"];
+/** Text field limits normalized from `boolean | TextFieldCapability`. */
+declare function textFieldCapability(value: boolean | TextFieldCapability | undefined): TextFieldCapability | null;
+/** Seed limits normalized from `boolean | SeedCapability`. */
+declare function seedCapability(value: boolean | SeedCapability | undefined): SeedCapability | null;
+/**
+ * Supported reference roles of a model: built-in roles in
+ * {@link REFERENCE_ROLES} order, then custom roles in declaration order.
+ */
+declare function supportedReferenceRoles(caps: ModelCapabilities): ReferenceRole[];
+/** Supported generation modes of a model. */
+declare function supportedModes(caps: ModelCapabilities): GenerationMode[];
+/** A partial model entry used to decorate (or add) models locally. */
+type CapabilityOverlay = Partial<ModelCapabilities> & {
+    id: string;
+};
+/**
+ * Merges server-reported capabilities with a local overlay. For models the
+ * server knows, every capability value comes from `remote`; the overlay only
+ * contributes presentation fields (`name`, `description`, `badges`, `icon`,
+ * `group`), filling in or replacing the remote ones. Overlay entries for
+ * models the server does not report are appended when they are complete
+ * (have a `media` kind). Remote order is kept; overlay-only models follow in
+ * overlay order.
+ */
+declare function mergeCapabilities(remote: readonly ModelCapabilities[], overlay?: readonly CapabilityOverlay[]): ModelCapabilities[];
+
+/**
+ * How the planner treats values the model does not support:
+ *
+ * - `error`: nothing is changed; every mismatch is an error.
+ * - `nearest`: snap to the closest supported value (ties go to the higher
+ *   value), clamp ranges, truncate lists, drop unsupported fields and
+ *   unsupported references.
+ * - `downgrade`: like `nearest`, but ties go to the lower value.
+ * - `upgrade`: like `nearest`, but never drops references the model cannot
+ *   use (that would lose intent), so those are errors.
+ *
+ * "Lower" means a narrower aspect ratio, fewer pixels, an earlier quality
+ * option, a smaller number.
+ */
+type PlanStrategy = 'error' | 'upgrade' | 'downgrade' | 'nearest';
+type PlanAdjustmentKind = 'snapped' | 'clamped' | 'truncated' | 'dropped' | 'defaulted';
+interface PlanAdjustment {
+    /** Request path, e.g. `aspectRatio`, `params.guidance`, `references.style_ref`. */
+    field: string;
+    from: unknown;
+    to: unknown;
+    reason: string;
+    kind: PlanAdjustmentKind;
+}
+interface PlanError {
+    field: string;
+    value: unknown;
+    message: string;
+}
+interface GenerationPlan {
+    /** `true` when there are no errors and `request` can be sent. */
+    ok: boolean;
+    /** The adjusted request (always a copy; the input is never mutated). */
+    request: GenerationRequest;
+    adjustments: PlanAdjustment[];
+    errors: PlanError[];
+    /** Model the plan was made for. */
+    model: string;
+    strategy: PlanStrategy;
+}
+interface PlanOptions {
+    /** Default `nearest`. */
+    strategy?: PlanStrategy;
+    /**
+     * The prompt with templates and variables resolved. Measured against
+     * `prompt.maxLength` when the model counts resolved text (the default).
+     */
+    resolvedPrompt?: string;
+    /** Fill missing fields that have a capability `default` (reported as `defaulted`). */
+    fillDefaults?: boolean;
+    /** Override whether references with unsupported roles may be dropped (default: `nearest` and `downgrade` only). */
+    dropUnsupportedReferences?: boolean;
+    /**
+     * Assets mentioned in the prompt (e.g. from `extractMentions(text, { details: true, roles: true })`
+     * joined with your asset library). They are appended to `request.references`
+     * and validated per role like any other reference. A mention without a role
+     * gets `defaultMentionRole`, or the first role of the model that accepts its
+     * media type (reported as `defaulted`).
+     */
+    mentions?: readonly PlanAssetMention[];
+    /** Role for mentions that have none (see `mentions`). */
+    defaultMentionRole?: ReferenceRole;
+}
+/** An asset mention handed to the planner (see {@link PlanOptions.mentions}). */
+interface PlanAssetMention {
+    /** Asset id. */
+    id: string;
+    role?: ReferenceRole | null;
+    mediaType?: string;
+    contentHash?: string;
+    url?: string;
+    /** The mention text, used in messages (default: the id). */
+    label?: string;
+}
+/** Numeric rank of an aspect ratio such as `16:9` (log of width / height). */
+declare function aspectRatioRank(value: string): number | undefined;
+/**
+ * Numeric rank of a resolution: `1024x768` (pixels), `720p` (16:9 pixels at
+ * that height) or `2k` (square of that many kibi-pixels). Log scale.
+ */
+declare function resolutionRank(value: string): number | undefined;
+/** Megapixels of a resolution string, when it can be parsed. */
+declare function resolutionMegapixels(value: string): number | undefined;
+/** Common quality names, low → high. Used to compare values missing from a model's options. */
+declare const QUALITY_LADDER: Readonly<Record<string, number>>;
+declare function qualityRank(value: string): number | undefined;
+/**
+ * Picks the option closest to `value` by `rank`. Ties go to the lower or
+ * higher rank. Returns `undefined` when `value` or no option can be ranked.
+ */
+declare function snapToOption<T>(value: unknown, options: readonly T[], rank: (value: any) => number | undefined, tie: 'lower' | 'higher'): T | undefined;
+/**
+ * Plans `request` against a model's capabilities before sending it: snaps
+ * enum values (aspect ratio, resolution, quality, count/duration choices) to
+ * the nearest supported option, clamps ranges, truncates text and reference
+ * lists over their limits, drops unsupported fields, and reports every change
+ * in `adjustments` and every unfixable problem in `errors`.
+ *
+ * Pure and deterministic: the input is not mutated and the same input always
+ * gives the same plan.
+ */
+declare function planGenerationRequest(request: GenerationRequest, caps: ModelCapabilities, options?: PlanOptions): GenerationPlan;
+
+/**
+ * JSON Schema for a request to one model: enums for choices, `minimum` /
+ * `maximum` for ranges, `maxItems` for reference lists and `description`s that
+ * spell out limits the schema cannot express (per-role reference counts,
+ * resolved-prompt length). Unsupported fields are absent and
+ * `additionalProperties` is `false`, so `validateJsonSchema` rejects them.
+ */
+declare function capabilitiesToJsonSchema(caps: ModelCapabilities): JsonSchema & {
+    type: 'object';
+};
+
+interface GenerateContext {
+    model: ModelCapabilities;
+    plan: GenerationPlan;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}
+interface EstimateContext {
+    model: ModelCapabilities;
+    plan: GenerationPlan;
+    signal?: AbortSignal;
+}
+interface GenerationToolProviderOptions {
+    /** Provider id (default `generation`). */
+    id?: string;
+    namespace?: string;
+    /** Models, or a function returning the current models (re-read on every list/call). */
+    models: readonly ModelCapabilities[] | (() => readonly ModelCapabilities[]);
+    /** Sends a planned request. Its resolved value is the tool result (e.g. `{ jobId }`). */
+    generate: (request: GenerationRequest, context: GenerateContext) => unknown | Promise<unknown>;
+    /** Optional cost/time estimate; adds the `estimate_generation` tool. */
+    estimate?: (request: GenerationRequest, context: EstimateContext) => unknown | Promise<unknown>;
+    /** Strategy used when the caller does not pass one (default `nearest`). */
+    defaultStrategy?: PlanStrategy;
+    /** Completed idempotency keys remembered (default 500, oldest evicted first). */
+    maxIdempotencyKeys?: number;
+    /** Lets the host signal that the model list changed. */
+    subscribe?: AgentToolProvider['subscribe'];
+}
+interface GenerationToolProvider extends AgentToolProvider {
+    /** Forgets remembered idempotency keys (all, or one). */
+    clearIdempotencyKeys(key?: string): void;
+}
+/**
+ * Exposes generation models to a `ToolRegistry`:
+ *
+ * - `list_models` (read-only): ids, presentation fields and per-model request schemas.
+ * - `plan_generation` (read-only): the adjusted request, adjustments and errors.
+ * - `estimate_generation` (read-only, only with `estimate`): your estimate for the planned request.
+ * - `generate` (destructive): plans, then calls `generate` with the adjusted
+ *   request. Requires an `idempotencyKey`: a retry with the same key and
+ *   arguments returns the first call's result (or joins it while in flight)
+ *   instead of generating again; the same key with different arguments is
+ *   rejected. Failed calls forget their key so they can be retried.
+ */
+declare function createGenerationToolProvider(options: GenerationToolProviderOptions): GenerationToolProvider;
+
+declare const PROVENANCE_FORMAT = "pixerate.generation-provenance";
+declare const PROVENANCE_VERSION = 1;
+/** The exact template body a generation used. */
+interface PinnedTemplate {
+    name: string;
+    templateId?: string;
+    /** Version id or version label the body came from (absent for unversioned templates). */
+    versionId?: string;
+    version?: string | number;
+    body: string;
+}
+/** Everything needed to explain and reproduce one generation. */
+interface GenerationProvenance {
+    format: typeof PROVENANCE_FORMAT;
+    version: typeof PROVENANCE_VERSION;
+    /** Raw prompt as typed, with `{{templates}}` and `{variables}`. */
+    rawPrompt: string;
+    /** Every template the prompt reached (recursively), pinned to the body used. */
+    templates: PinnedTemplate[];
+    /** Version bindings in effect (`{ templateName: versionId }`) for every pinned versioned template. */
+    bindings: Record<string, string>;
+    /** Variable values, or `null` when variables were left unresolved. */
+    values: PromptValues | null;
+    resolvedPrompt: string;
+    sourceMap: SourceMapSegment[];
+    modelId: string;
+    /** The planned (adjusted) request that was sent. */
+    request: GenerationRequest;
+    adjustments: PlanAdjustment[];
+    references: {
+        id: string;
+        role: ReferenceRole;
+    }[];
+    /** ISO timestamps. */
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** Ids of the outputs this generation produced. */
+    outputIds?: string[];
+    meta?: Record<string, unknown>;
+}
+interface CreateProvenanceOptions {
+    rawPrompt: string;
+    templates?: Template[];
+    /** Template version bindings (`{ templateName: versionIdOrVersion }`). */
+    bindings?: Record<string, string>;
+    values?: PromptValues;
+    model: string | ModelCapabilities;
+    /** The plan the request came from (its request and adjustments are recorded) … */
+    plan?: GenerationPlan;
+    /** … or the request that was sent. */
+    request?: GenerationRequest;
+    adjustments?: PlanAdjustment[];
+    /** Creation time (default `Date.now()`). */
+    createdAt?: Date | number | string;
+    startedAt?: Date | number | string;
+    completedAt?: Date | number | string;
+    outputIds?: string[];
+    meta?: Record<string, unknown>;
+    maxDepth?: number;
+}
+declare class ProvenanceParseError extends Error {
+    constructor(message: string);
+}
+/** Templates that reproduce the pinned bodies exactly (one single-version template each). */
+declare function pinnedTemplatesToTemplates(pinned: readonly PinnedTemplate[]): Template[];
+/**
+ * Records what produced an output: the raw prompt, the exact template bodies
+ * and versions it reached, variable values, the resolved prompt and its
+ * source map, the model, the planned settings and adjustments, and the
+ * references by role.
+ */
+declare function createProvenance(options: CreateProvenanceOptions): GenerationProvenance;
+/** Versioned JSON for storage next to an output. */
+declare function serializeProvenance(provenance: GenerationProvenance): string;
+/** Parses and checks serialized provenance. Throws {@link ProvenanceParseError}. */
+declare function parseProvenance(input: string | unknown): GenerationProvenance;
+/**
+ * Re-resolves the raw prompt against the pinned template bodies and values,
+ * e.g. to check a record or to open it in an editor with its source map.
+ */
+declare function replayProvenancePrompt(provenance: GenerationProvenance): {
+    text: string;
+    map: SourceMapSegment[];
+    matches: boolean;
+};
+
+interface BatchResolverOptions<K, V> {
+    /** Loads many keys at once. Keys missing from the map resolve to `undefined`. */
+    fetch: (keys: K[]) => Promise<Map<K, V>>;
+    /** Largest batch passed to `fetch` (default 50). */
+    maxBatch?: number;
+    /** How long to collect keys before fetching, in ms (default 0: the same tick). */
+    delayMs?: number;
+    /** Called once per failed batch. The batch's keys are recorded as resolved-empty. */
+    onError?: (error: unknown, keys: K[]) => void;
+}
+interface BatchResolver<K, V> {
+    /** Resolves one key, batched with other loads in the same window. Never rejects. */
+    load(key: K): Promise<V | undefined>;
+    loadMany(keys: readonly K[]): Promise<(V | undefined)[]>;
+    /** The settled value for a key, if it has been resolved. */
+    peek(key: K): V | undefined;
+    /** Whether a key has settled (found, missing or failed). */
+    has(key: K): boolean;
+    /** Whether a key's last fetch failed. */
+    failed(key: K): boolean;
+    /** Seeds a value without fetching. */
+    prime(key: K, value: V): void;
+    /** Forgets one key (or all) so the next `load` fetches again. */
+    clear(key?: K): void;
+    /** Fetches anything still waiting now, without waiting for `delayMs`. */
+    flush(): void;
+}
+/**
+ * Coalesces lookups (e.g. asset ids → thumbnails, template ids → bodies) into
+ * batched `fetch` calls: keys requested within `delayMs` share a batch of at
+ * most `maxBatch`, duplicate keys are fetched once, and results are cached.
+ * A failed batch resolves its keys to `undefined` and records them as
+ * resolved-empty (`failed(key)` is `true`) so one bad response does not cause
+ * a retry storm; `clear(key)` allows a retry.
+ */
+declare function createBatchResolver<K, V>(options: BatchResolverOptions<K, V>): BatchResolver<K, V>;
+
+interface JobProgressInput {
+    /** Start time (ms since epoch, `Date` or ISO string). */
+    startedAt: number | Date | string;
+    /** Current time (default `Date.now()`). */
+    now?: number | Date | string;
+    /** Expected total duration in ms. Without it progress eases towards 95%. */
+    expectedMs?: number;
+    /** The job finished. */
+    done?: boolean;
+}
+interface JobProgressEstimate {
+    /** 0–100. Never above 95 until `done`. */
+    percent: number;
+    /** E.g. `~2m left`, `~40s left`, `Almost done…`, `Starting…`, `Done`. */
+    label: string;
+    elapsedMs: number;
+    /** Estimated ms left (`undefined` without `expectedMs`). */
+    remainingMs?: number;
+    /** Running longer than expected. */
+    overdue: boolean;
+}
+/** Highest percentage shown before a job reports completion. */
+declare const MAX_PENDING_PERCENT = 95;
+/** `~45s left`, `~2m left`, `~1h 5m left`. Minutes and seconds round up. */
+declare function formatRemaining(ms: number): string;
+/**
+ * Progress for a job that reports no progress of its own: linear in elapsed
+ * time over `expectedMs`, held at 95% until `done` (so the bar never sits at
+ * 100% while still waiting), with a "~2m left" style label that turns into
+ * "Almost done…" near or past the expected end. Pure: pass `now` to test.
+ */
+declare function estimateJobProgress(input: JobProgressInput): JobProgressEstimate;
+/**
+ * Expected duration of a request from the model's `timing`: `baseMs`, plus
+ * `perItemMs` per output beyond the first, `perSecondMs` per second of
+ * duration and `perMegapixelMs` per megapixel of resolution. `undefined` when
+ * the model has no timing.
+ */
+declare function expectedDurationFor(caps: ModelCapabilities, request?: GenerationRequest): number | undefined;
+
+interface GenerationControlOption {
+    value: string | number;
+    label: string;
+}
+/**
+ * A UI control derived from capabilities. `key` is a request path:
+ * `aspectRatio`, `count`, `params.guidance`, …
+ */
+interface GenerationControl {
+    key: string;
+    label: string;
+    /** `select` for choices, `range` for bounded numbers, `number` for open numbers. */
+    kind: 'select' | 'range' | 'number' | 'textarea' | 'checkbox';
+    valueType: 'string' | 'number' | 'boolean';
+    options?: GenerationControlOption[];
+    min?: number;
+    max?: number;
+    step?: number;
+    maxLength?: number;
+    defaultValue?: string | number | boolean;
+    description?: string;
+}
+interface ReferenceSlot {
+    role: ReferenceRole;
+    label: string;
+    description?: string;
+    min: number;
+    max: number;
+    /** Media accepted for this role (see `ReferenceRoleCapability.accepts`). */
+    accepts?: string[];
+    references: GenerationReference[];
+    /** More references of this role fit (per role and in total). */
+    canAdd: boolean;
+}
+/**
+ * The settings controls a model supports, in display order. Excludes the
+ * prompt (edited by the prompt editor) and references (see
+ * {@link getReferenceSlots}).
+ */
+declare function getGenerationControls(caps: ModelCapabilities): GenerationControl[];
+/** Reads a request value by control key (`params.x` reads a param). */
+declare function getRequestValue(request: GenerationRequest, key: string): unknown;
+/** Returns a copy of `request` with `key` set (`undefined` or `''` removes it). */
+declare function setRequestValue(request: GenerationRequest, key: string, value: unknown): GenerationRequest;
+/** Parses a DOM control's string value into the control's value type. */
+declare function parseControlValue(control: GenerationControl, raw: string | boolean): string | number | boolean | undefined;
+/** Reference slots for every role the model accepts, filled from `request`. */
+declare function getReferenceSlots(caps: ModelCapabilities, request?: GenerationRequest): ReferenceSlot[];
+/** Returns a copy of `request` with a reference appended. */
+declare function addReference(request: GenerationRequest, reference: GenerationReference): GenerationRequest;
+/** Returns a copy of `request` without the reference `id` in `role`. */
+declare function removeReference(request: GenerationRequest, role: ReferenceRole, id: string): GenerationRequest;
+
+/**
+ * Stable JSON: object keys sorted, `undefined` members left out, so equal
+ * values always give the same string regardless of key order.
+ */
+declare function stableStringify(value: unknown): string;
+/**
+ * A short, stable, synchronous content hash (two independent 32-bit FNV-1a
+ * lanes over the UTF-16 code units, 16 hex digits, prefixed with `h1-`).
+ * It detects changes; it is not cryptographic, so do not use it to
+ * authenticate content.
+ */
+declare function hashText(text: string): string;
+/** {@link hashText} of the {@link stableStringify} form of `value`. */
+declare function hashValue(value: unknown): string;
+/**
+ * Hash of what a model accepts. Presentation fields (`name`, `description`,
+ * `badges`, `icon`, `group`) and `timing` are left out, so renaming a model or
+ * changing its progress estimate is not reported as a capability change.
+ */
+declare function hashCapabilities(caps: ModelCapabilities): string;
+
+/** A role a model accepts for asset mentions / references, for pickers. */
+interface AssetRoleOption {
+    role: ReferenceRole;
+    label: string;
+    description?: string;
+    min: number;
+    max: number;
+    accepts?: string[];
+}
+/** What the host knows about an asset (for planning, records and drift checks). */
+interface AssetInfo {
+    id: string;
+    label?: string;
+    /** MIME type or media kind (`image/png`, `image`). */
+    mediaType?: string;
+    /** Content hash; a change is reported as `asset-changed` drift. */
+    contentHash?: string;
+    url?: string;
+}
+/** Assets by id: a lookup function, a map, or a list. */
+type AssetLookup = ((id: string) => AssetInfo | null | undefined) | ReadonlyMap<string, AssetInfo> | readonly AssetInfo[];
+/** Normalizes an {@link AssetLookup} to a function. */
+declare function toAssetResolver(lookup: AssetLookup | undefined): ((id: string) => AssetInfo | undefined) | undefined;
+/** The roles a model accepts, with labels, limits and accepted media (inpainting adds `mask`). */
+declare function getAssetRoleOptions(caps: ModelCapabilities): AssetRoleOption[];
+type AssetMentionIssueCode = 'missing-role' | 'unsupported-role' | 'renamed-role' | 'media-mismatch' | 'too-many';
+interface AssetMentionIssue {
+    /** Index of the mention in the input. */
+    index: number;
+    id: string;
+    role?: ReferenceRole;
+    code: AssetMentionIssueCode;
+    /** `error` blocks generation under the `error` strategy; `warning` is fixed by planning. */
+    severity: 'error' | 'warning';
+    message: string;
+    /** The role the planner will use instead (`renamed-role`). */
+    suggestion?: ReferenceRole;
+}
+interface AssetMentionValidation {
+    ok: boolean;
+    issues: AssetMentionIssue[];
+    /** Mentions per (canonical) role. */
+    counts: Record<string, number>;
+    /** Roles below their `min`. */
+    missing: {
+        role: ReferenceRole;
+        min: number;
+        count: number;
+    }[];
+}
+/**
+ * Checks asset mentions against what a model accepts, per mention, for UI
+ * feedback (badges, popovers). Mirrors the planner: aliases (`style` →
+ * `style_ref`) are accepted with a `renamed-role` warning, unsupported roles,
+ * media types the role does not accept and mentions beyond a role's `max`
+ * are reported, and roles below their `min` are listed in `missing`.
+ */
+declare function validateAssetMentions(mentions: readonly PlanAssetMention[], caps: ModelCapabilities, options?: {
+    assets?: AssetLookup;
+}): AssetMentionValidation;
+/**
+ * Joins mentions (`{ handle, role }`, e.g. from `extractMentions(text, { details: true, roles: true })`)
+ * with your assets: each handle is looked up by id, then by label
+ * (case-insensitive). Mentions that are not assets are left out.
+ */
+declare function resolveAssetMentions(mentions: readonly {
+    handle: string;
+    role?: string | null;
+}[], assets: readonly AssetInfo[]): PlanAssetMention[];
+/** Built-in roles as picker options, for when no model is selected. */
+declare function defaultAssetRoleOptions(): AssetRoleOption[];
+/** An asset mention prepared for display as a chip. */
+interface AssetMentionChip {
+    /** Position among the chips. */
+    index: number;
+    /** Offset of the `@` in the text, when known (for `setMentionRoleInText`). */
+    start?: number;
+    handle: string;
+    asset: AssetInfo;
+    role?: ReferenceRole;
+    /** Display label of the role (the model's, else built-in). */
+    roleLabel?: string;
+    /** Problems with this mention for the model (`validateAssetMentions`). */
+    issues: AssetMentionIssue[];
+}
+/**
+ * Chips for the asset mentions among `mentions` (e.g. `findTextMentions(text)`
+ * from `@pixerate/editor/serializers`): each mention whose handle is an asset
+ * id or label, with its role label and the problems the model has with it.
+ */
+declare function describeAssetMentions(mentions: readonly {
+    handle: string;
+    role?: string | null;
+    start?: number;
+}[], assets: readonly AssetInfo[], caps?: ModelCapabilities): AssetMentionChip[];
+
+declare const GENERATION_RECORD_FORMAT = "pixerate.generation-record";
+declare const GENERATION_RECORD_VERSION = 1;
+/** How a record came about. */
+type GenerationRecordKind = 'generate' | 'recreate' | 'variation';
+/** A template the generation used, with a hash of the exact body. */
+interface RecordedTemplate {
+    name: string;
+    templateId?: string;
+    versionId?: string;
+    version?: string | number;
+    /** {@link hashText} of the body that was used. */
+    hash: string;
+}
+/** An asset the generation used, by role, with its content hash at the time. */
+interface RecordedAsset {
+    id: string;
+    role: ReferenceRole;
+    contentHash?: string;
+    mediaType?: string;
+    url?: string;
+}
+/**
+ * Everything needed to reproduce one generation. The prompt, templates,
+ * values, resolved prompt, source map, planned request and adjustments live
+ * in `provenance` (see `createProvenance`); the record adds hashes for
+ * change detection, the user's original settings, assets and lineage.
+ */
+interface GenerationRecord {
+    format: typeof GENERATION_RECORD_FORMAT;
+    version: typeof GENERATION_RECORD_VERSION;
+    id: string;
+    /** The record this one was recreated or varied from. */
+    parentId?: string;
+    kind: GenerationRecordKind;
+    provenance: GenerationProvenance;
+    /** One entry per template in `provenance.templates`, same order. */
+    templates: RecordedTemplate[];
+    /** {@link hashText} of `provenance.resolvedPrompt`. */
+    promptHash: string;
+    /** {@link hashCapabilities} of the model when the record was made (absent when only an id was known). */
+    capabilityHash?: string;
+    /** The request as the user set it, before planning (snapping, clamping, dropping). */
+    settings: GenerationRequest;
+    /** Strategy the request was planned with. */
+    strategy: PlanStrategy;
+    /** Seed used: the one the provider reported, else the planned one. */
+    seed?: number;
+    assets: RecordedAsset[];
+    /** Asset mentions that were planned as references (kept apart from `settings`). */
+    mentions?: PlanAssetMention[];
+    /** ISO timestamp (same as `provenance.createdAt`). */
+    createdAt: string;
+    updatedAt?: string;
+}
+interface CreateGenerationRecordOptions extends Omit<CreateProvenanceOptions, 'model' | 'plan' | 'request' | 'adjustments'> {
+    /** The model (needed for the capability hash and for planning when `plan` is absent). */
+    model: ModelCapabilities | string;
+    /** The user's settings before planning. */
+    request?: GenerationRequest;
+    /** The plan that was sent. Without it the request is planned here (needs capabilities). */
+    plan?: GenerationPlan;
+    /** Strategy for planning here, and recorded for recreating (default: the plan's, else `nearest`). */
+    strategy?: PlanStrategy;
+    /** Asset mentions to plan as references (see `PlanOptions.mentions`). */
+    mentions?: readonly PlanAssetMention[];
+    /** Fills in content hashes and media types of referenced assets. */
+    assets?: AssetLookup;
+    /** Seed the provider actually used, when it differs from the planned one (e.g. random). */
+    seed?: number;
+    id?: string;
+    parentId?: string;
+    kind?: GenerationRecordKind;
+}
+/** A unique record id (`crypto.randomUUID` when available). */
+declare function createGenerationRecordId(): string;
+/**
+ * Records a generation so it can be listed, explained and recreated. Builds
+ * the provenance (pinned template bodies, values, resolved prompt and source
+ * map, planned request, adjustments) and adds a hash per template body, the
+ * capability hash of the model, the user's original settings, the seed, the
+ * referenced assets with their roles and content hashes, and the parent
+ * record. Plans the request when no `plan` is given and `model` is a
+ * capability object.
+ */
+declare function createGenerationRecord(options: CreateGenerationRecordOptions): GenerationRecord;
+/** Returns a copy of `record` with outputs and completion time added (e.g. when the job finishes). */
+declare function completeGenerationRecord(record: GenerationRecord, update: {
+    outputIds?: string[];
+    completedAt?: Date | number | string;
+    seed?: number;
+    meta?: Record<string, unknown>;
+}): GenerationRecord;
+/** Versioned JSON for storage. */
+declare function serializeGenerationRecord(record: GenerationRecord): string;
+/** Parses and checks a serialized record. Throws `ProvenanceParseError`. */
+declare function parseGenerationRecord(input: string | unknown): GenerationRecord;
+/** True for a {@link GenerationRecord} (as opposed to bare provenance). */
+declare function isGenerationRecord(value: unknown): value is GenerationRecord;
+/**
+ * `exact`: the same resolved prompt (pinned template bodies), the planned
+ * settings that were sent, the same seed. `latest`: the raw prompt resolved
+ * against today's templates (latest versions) and the user's original
+ * settings planned against today's capabilities, with the same seed.
+ */
+type RecreateMode = 'exact' | 'latest';
+type DriftType = 'template-changed' | 'template-missing' | 'prompt-changed' | 'model-missing' | 'model-changed' | 'setting-unsupported' | 'setting-changed' | 'asset-missing' | 'asset-changed';
+interface DriftItem {
+    type: DriftType;
+    /** `error` items make `ok` false (the request cannot reproduce the record). */
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    /** Template name (template drift). */
+    template?: string;
+    /** Request path, e.g. `resolution`, `params.guidance`, `references` (setting drift). */
+    field?: string;
+    /** Asset id and role (asset drift). */
+    assetId?: string;
+    role?: ReferenceRole;
+    modelId?: string;
+    /** Recorded and current value, version or hash. */
+    from?: unknown;
+    to?: unknown;
+    /** Whether the change is in the returned request (`latest` mode), or only reported (`exact`). */
+    applied?: boolean;
+}
+interface RecreateOptions {
+    /** Current templates (to detect edits, and to resolve in `latest` mode). */
+    templates?: readonly Template[];
+    /** Current model capabilities: one model, or a list to find the record's model in. */
+    capabilities?: ModelCapabilities | readonly ModelCapabilities[];
+    /** Default `exact`. */
+    mode?: RecreateMode;
+    /** Current assets, to report missing or changed assets. */
+    assets?: AssetLookup;
+    /** Planning strategy (default: the record's). */
+    strategy?: PlanStrategy;
+}
+interface RecreateResult {
+    mode: RecreateMode;
+    /** No `error` drift and (when capabilities were given) the plan has no errors. */
+    ok: boolean;
+    /** The request to send (re-planned when capabilities were given). */
+    request: GenerationRequest;
+    /** The plan against current capabilities (absent without capabilities or when the model is gone). */
+    plan?: GenerationPlan;
+    rawPrompt: string;
+    resolvedPrompt: string;
+    sourceMap: SourceMapSegment[];
+    values: PromptValues | null;
+    /** Templates and bindings the prompt was resolved with. */
+    templates: Template[];
+    bindings: Record<string, string>;
+    drift: DriftItem[];
+    /** The record this request comes from. */
+    parentId: string;
+    kind: Exclude<GenerationRecordKind, 'generate'>;
+    /** Options for {@link createGenerationRecord} once the new generation has run. */
+    recordOptions: CreateGenerationRecordOptions;
+}
+/** Changes for {@link variationRequest}. */
+interface VariationOverrides {
+    /** New seed, `null` for none, or absent for a random one different from the record's. */
+    seed?: number | null;
+    /** Values merged over the recorded ones. */
+    values?: PromptValues;
+    /** Settings merged over the recreated request (`params` are merged too). */
+    settings?: Partial<GenerationRequest>;
+    /** A different raw prompt. */
+    rawPrompt?: string;
+    /** Random source in [0, 1) for the seed (default `Math.random`). */
+    random?: () => number;
+}
+/**
+ * Rebuilds the request of a recorded generation.
+ *
+ * - With a {@link GenerationRecord}: returns a {@link RecreateResult} with the
+ *   re-planned request and a drift report: templates edited or deleted since,
+ *   model capabilities changed or the model gone, settings no longer
+ *   supported (or, in `latest` mode, planned differently), assets missing or
+ *   changed. `mode: 'exact'` (default) reproduces the recorded prompt and
+ *   settings; `mode: 'latest'` uses current templates and re-plans the
+ *   original settings. Template edits are always reported; only `latest`
+ *   applies them.
+ * - With bare {@link GenerationProvenance} (the original API): returns the
+ *   planned request that was sent, with the prompt as resolved at the time.
+ */
+declare function recreateRequest(provenance: GenerationProvenance): GenerationRequest;
+declare function recreateRequest(record: GenerationRecord, options?: RecreateOptions): RecreateResult;
+/**
+ * A request for a variation of a recorded generation: the same prompt,
+ * settings and assets (as {@link recreateRequest} would rebuild them, `exact`
+ * mode by default) with a new seed (random within the model's range unless
+ * given) and any overrides. Setting drift is not reported for the fields you
+ * change; template, model and asset drift are.
+ */
+declare function variationRequest(record: GenerationRecord, overrides?: VariationOverrides, options?: RecreateOptions): RecreateResult;
+/** Short display labels for drift types (history panels, badges). */
+declare const DRIFT_TYPE_LABELS: Readonly<Record<DriftType, string>>;
+/** Drift items that block an exact reproduction (`severity: 'error'`). */
+declare function blockingDrift(drift: readonly DriftItem[]): DriftItem[];
+
+/** What the store indexes per record (kept in one index entry, so lists need no record reads). */
+interface GenerationRecordSummary {
+    id: string;
+    modelId: string;
+    kind: GenerationRecordKind;
+    parentId?: string;
+    createdAt: string;
+    /** Template names and ids used. */
+    templates: string[];
+    templateIds: string[];
+    /** Asset ids and roles used. */
+    assets: string[];
+    roles: ReferenceRole[];
+    /** First 160 characters of the resolved prompt, for lists. */
+    preview: string;
+}
+interface GenerationRecordFilter {
+    /** Model id(s). */
+    model?: string | readonly string[];
+    /** Template name or id. */
+    template?: string;
+    /** Asset id. */
+    asset?: string;
+    role?: ReferenceRole;
+    kind?: GenerationRecordKind;
+    parentId?: string;
+    /** Created at or after / before (exclusive). */
+    since?: Date | number | string;
+    until?: Date | number | string;
+    /** Case-insensitive text in the prompt preview. */
+    text?: string;
+    offset?: number;
+    limit?: number;
+}
+interface PruneOptions {
+    /** Keep at most this many records (newest first). */
+    maxRecords?: number;
+    /** Remove records created before this time. */
+    olderThan?: Date | number | string;
+    /** Records for which this returns `true` are never removed (they still count toward `maxRecords`). */
+    keep?: (summary: GenerationRecordSummary) => boolean;
+}
+interface GenerationRecordStoreOptions {
+    storage: Pick<StorageAdapter, 'get' | 'set' | 'remove'>;
+    /** Key prefix (default `pixerate.generation-records`). */
+    namespace?: string;
+    /** Prune to this many records after every `put`. */
+    maxRecords?: number;
+}
+interface GenerationRecordStore {
+    /** Adds or replaces a record. */
+    put(record: GenerationRecord): Promise<void>;
+    get(id: string): Promise<GenerationRecord | null>;
+    /** Records matching `filter`, newest first. Unreadable records are skipped. */
+    list(filter?: GenerationRecordFilter): Promise<GenerationRecord[]>;
+    /** Index entries matching `filter`, newest first (no record reads). */
+    summaries(filter?: GenerationRecordFilter): Promise<GenerationRecordSummary[]>;
+    remove(id: string): Promise<boolean>;
+    /** Removes records by count and age; returns the removed ids. */
+    prune(options: PruneOptions): Promise<string[]>;
+    clear(): Promise<void>;
+    /** Called after every change. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/** The index entry for a record. */
+declare function summarizeGenerationRecord(record: GenerationRecord): GenerationRecordSummary;
+/** True when `summary` matches every condition of `filter` (ignores `offset` / `limit`). */
+declare function matchesRecordFilter(summary: GenerationRecordSummary, filter?: GenerationRecordFilter): boolean;
+/**
+ * Persists generation records on a key/value `StorageAdapter`
+ * (`createMemoryStorage`, `createLocalStorageAdapter`, `createIndexedDbAdapter`,
+ * `createOpfsAdapter`). Each record is stored under its own key and a single
+ * index entry holds the summaries used for listing and filtering. Operations
+ * run one at a time, so concurrent `put`s do not lose index entries. The index
+ * is cached after the first read: use one store per storage namespace.
+ */
+declare function createGenerationRecordStore(options: GenerationRecordStoreOptions): GenerationRecordStore;
+
+export { AgentToolProvider, type AssetInfo, type AssetLookup, type AssetMentionChip, type AssetMentionIssue, type AssetMentionIssueCode, type AssetMentionValidation, type AssetRoleOption, type BatchResolver, type BatchResolverOptions, type BooleanParamSpec, type BuiltinReferenceRole, type CapabilityOverlay, type CapabilityPresentation, type CountCapability, type CreateGenerationRecordOptions, type CreateProvenanceOptions, DRIFT_TYPE_LABELS, type DriftItem, type DriftType, type DurationCapability, type EnumCapability, type EnumParamSpec, type EstimateContext, type ExtraParamSpec, GENERATION_RECORD_FORMAT, GENERATION_RECORD_VERSION, GENERATION_REQUEST_FIELDS, type GenerateContext, type GenerationControl, type GenerationControlOption, type GenerationMediaKind, type GenerationMode, type GenerationParamValue, type GenerationPlan, type GenerationProvenance, type GenerationRecord, type GenerationRecordFilter, type GenerationRecordKind, type GenerationRecordStore, type GenerationRecordStoreOptions, type GenerationRecordSummary, type GenerationReference, type GenerationRequest, type GenerationToolProvider, type GenerationToolProviderOptions, type JobProgressEstimate, type JobProgressInput, JsonSchema, MAX_PENDING_PERCENT, type ModelCapabilities, type NumberParamSpec, PROVENANCE_FORMAT, PROVENANCE_VERSION, type PinnedTemplate, type PlanAdjustment, type PlanAdjustmentKind, type PlanAssetMention, type PlanError, type PlanOptions, type PlanStrategy, type PromptCapability, ProvenanceParseError, type PruneOptions, QUALITY_LADDER, REFERENCE_ROLES, REFERENCE_ROLE_ALIASES, REFERENCE_ROLE_LABELS, REFERENCE_ROLE_NAME_REGEX, type RecordedAsset, type RecordedTemplate, type RecreateMode, type RecreateOptions, type RecreateResult, type ReferenceCapability, type ReferenceRole, type ReferenceRoleCapability, type ReferenceSlot, type SeedCapability, type TextFieldCapability, type TimingCapability, type VariationOverrides, addReference, aspectRatioRank, blockingDrift, capabilitiesToJsonSchema, completeGenerationRecord, createBatchResolver, createGenerationRecord, createGenerationRecordId, createGenerationRecordStore, createGenerationToolProvider, createProvenance, defaultAssetRoleOptions, describeAssetMentions, estimateJobProgress, expectedDurationFor, formatRemaining, getAssetRoleOptions, getGenerationControls, getReferenceSlots, getRequestValue, hashCapabilities, hashText, hashValue, isGenerationRecord, isReferenceRoleName, matchesRecordFilter, mediaTypeMatches, mergeCapabilities, normalizeReferenceRole, parseControlValue, parseGenerationRecord, parseProvenance, pinnedTemplatesToTemplates, planGenerationRequest, qualityRank, recreateRequest, referenceRoleLabel, removeReference, replayProvenancePrompt, resolutionMegapixels, resolutionRank, resolveAssetMentions, seedCapability, serializeGenerationRecord, serializeProvenance, setRequestValue, snapToOption, stableStringify, summarizeGenerationRecord, supportedModes, supportedReferenceRoles, textFieldCapability, toAssetResolver, validateAssetMentions, variationRequest };