@pixerate/editor 0.24.0 → 0.26.0

package/dist/generation/index.d.ts

@@ -4,6 +4,8 @@ import { A as AgentToolProvider } from '../registry-BDe-vlv3.js';
 export { a as AgentTool, d as McpToolDefinition, e as McpToolResult } from '../registry-BDe-vlv3.js';
 import { S as SourceMapSegment } from '../sourcemap-DA1Evhrv.js';
 import { T as Template, P as PromptValues } from '../tokens-D7yXvUU6.js';
+import { S as StorageAdapter } from '../storage-BpFfspHm.js';
+export { a as MentionRoleSyntax, T as TextMention, f as findTextMentions, b as formatMentionText, s as setMentionRoleInText } from '../mention-text-CDnCFd3c.js';
 
 /**
  * Declarative descriptions of generative models (what a model accepts) and of
@@ -12,12 +14,45 @@ import { T as Template, P as PromptValues } from '../tokens-D7yXvUU6.js';
  * turned into JSON Schema for agents.
  */
 type GenerationMediaKind = 'image' | 'video' | 'audio' | 'text';
-/** What a reference input is used for. */
-type ReferenceRole = 'start_frame' | 'end_frame' | 'style_ref' | 'character_ref' | 'background_ref' | 'mask' | 'image_ref' | 'video_ref' | 'audio_ref';
-/** Every reference role, in a stable display order. */
-declare const REFERENCE_ROLES: readonly ReferenceRole[];
+/** 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<ReferenceRole, string>>;
+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[];
@@ -65,6 +100,12 @@ interface ReferenceRoleCapability {
     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. */
@@ -146,6 +187,10 @@ interface GenerationReference {
     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;
@@ -172,7 +217,10 @@ declare const GENERATION_REQUEST_FIELDS: readonly ["model", "prompt", "negativeP
 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 in {@link REFERENCE_ROLES} order. */
+/**
+ * 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[];
@@ -243,6 +291,27 @@ interface PlanOptions {
     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;
@@ -407,12 +476,6 @@ declare function createProvenance(options: CreateProvenanceOptions): GenerationP
 declare function serializeProvenance(provenance: GenerationProvenance): string;
 /** Parses and checks serialized provenance. Throws {@link ProvenanceParseError}. */
 declare function parseProvenance(input: string | unknown): GenerationProvenance;
-/**
- * A request that reproduces the recorded generation exactly: the planned
- * settings, model, seed and references that were sent, with the prompt as
- * resolved at the time (not re-resolved against today's templates).
- */
-declare function recreateRequest(provenance: GenerationProvenance): GenerationRequest;
 /**
  * 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.
@@ -528,6 +591,8 @@ interface ReferenceSlot {
     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;
@@ -551,4 +616,400 @@ declare function addReference(request: GenerationRequest, reference: GenerationR
 /** Returns a copy of `request` without the reference `id` in `role`. */
 declare function removeReference(request: GenerationRequest, role: ReferenceRole, id: string): GenerationRequest;
 
-export { AgentToolProvider, type BatchResolver, type BatchResolverOptions, type BooleanParamSpec, type CapabilityOverlay, type CapabilityPresentation, type CountCapability, type CreateProvenanceOptions, type DurationCapability, type EnumCapability, type EnumParamSpec, type EstimateContext, type ExtraParamSpec, GENERATION_REQUEST_FIELDS, type GenerateContext, type GenerationControl, type GenerationControlOption, type GenerationMediaKind, type GenerationMode, type GenerationParamValue, type GenerationPlan, type GenerationProvenance, 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 PlanError, type PlanOptions, type PlanStrategy, type PromptCapability, ProvenanceParseError, QUALITY_LADDER, REFERENCE_ROLES, REFERENCE_ROLE_LABELS, type ReferenceCapability, type ReferenceRole, type ReferenceRoleCapability, type ReferenceSlot, type SeedCapability, type TextFieldCapability, type TimingCapability, addReference, aspectRatioRank, capabilitiesToJsonSchema, createBatchResolver, createGenerationToolProvider, createProvenance, estimateJobProgress, expectedDurationFor, formatRemaining, getGenerationControls, getReferenceSlots, getRequestValue, mergeCapabilities, parseControlValue, parseProvenance, pinnedTemplatesToTemplates, planGenerationRequest, qualityRank, recreateRequest, removeReference, replayProvenancePrompt, resolutionMegapixels, resolutionRank, seedCapability, serializeProvenance, setRequestValue, snapToOption, supportedModes, supportedReferenceRoles, textFieldCapability };
+/**
+ * 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 };