@pixerate/editor 0.135.0 → 0.137.0

package/dist/{pathfinder-D8KQ6blQ.d.cts → pathfinder-BHS4vQNm.d.cts}

@@ -1,5 +1,5 @@
 import { P as Point } from './brushTypes-C7N3EBK7.cjs';
-import { B as BezierPath, P as PolygonBooleanOperation, a as BezierPathInput, b as PolygonFillRule, c as BezierSegment, d as BezierContour } from './bezier-J8i4uqSH.cjs';
+import { B as BezierPath, P as PolygonBooleanOperation, a as BezierPathInput, b as PolygonFillRule, c as BezierSegment, d as BezierContour } from './bezier-CZ2AhjID.cjs';
 
 /**
  * Curve-preserving boolean operations (union, intersection, difference, xor and divide) on

package/dist/{pathfinder-Celbi3e6.d.ts → pathfinder-BVvTIBMo.d.ts}

@@ -1,5 +1,5 @@
 import { P as Point } from './brushTypes-C7N3EBK7.js';
-import { B as BezierPath, P as PolygonBooleanOperation, a as BezierPathInput, b as PolygonFillRule, c as BezierSegment, d as BezierContour } from './bezier-lNEOp0Jx.js';
+import { B as BezierPath, P as PolygonBooleanOperation, a as BezierPathInput, b as PolygonFillRule, c as BezierSegment, d as BezierContour } from './bezier-Dywv3Bw8.js';
 
 /**
  * Curve-preserving boolean operations (union, intersection, difference, xor and divide) on

package/dist/{pool-8JZGWHvR.d.ts → pool-CZQOrSXZ.d.ts}

@@ -1,4 +1,4 @@
-import { E as EffectProvider, a as EffectRenderRequest, b as EffectPixels } from './helpers-Coa4e2j_.js';
+import { E as EffectProvider, a as EffectRenderRequest, b as EffectPixels } from './helpers-C-RgeyvH.js';
 
 /**
  * `EffectRendererPool`: keeps a few live renderers, reused per effect, size and depth.

package/dist/{pool-BfuxBKTd.d.cts → pool-FjZZmZ80.d.cts}

@@ -1,4 +1,4 @@
-import { E as EffectProvider, a as EffectRenderRequest, b as EffectPixels } from './helpers-DHl28yLO.cjs';
+import { E as EffectProvider, a as EffectRenderRequest, b as EffectPixels } from './helpers-v6GMazzg.cjs';
 
 /**
  * `EffectRendererPool`: keeps a few live renderers, reused per effect, size and depth.

package/dist/provenance-DmlcgdzT.d.cts

@@ -0,0 +1,426 @@
+import { S as SourceMapSegment } from './sourcemap-C8AH3MBQ.cjs';
+import { P as PromptValues, T as Template } from './tokens-D7yXvUU6.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;
+
+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;
+};
+
+export { replayProvenancePrompt as $, REFERENCE_ROLE_NAME_REGEX as A, type BooleanParamSpec as B, type CreateProvenanceOptions as C, type DurationCapability as D, type EnumCapability as E, type ReferenceCapability as F, type GenerationProvenance as G, type ReferenceRoleCapability as H, type TimingCapability as I, aspectRatioRank as J, createProvenance as K, isReferenceRoleName as L, type ModelCapabilities as M, type NumberParamSpec as N, mediaTypeMatches as O, type PlanStrategy as P, QUALITY_LADDER as Q, type ReferenceRole as R, type SeedCapability as S, type TextFieldCapability as T, mergeCapabilities as U, normalizeReferenceRole as V, parseProvenance as W, pinnedTemplatesToTemplates as X, planGenerationRequest as Y, qualityRank as Z, referenceRoleLabel as _, type GenerationPlan as a, resolutionMegapixels as a0, resolutionRank as a1, seedCapability as a2, serializeProvenance as a3, snapToOption as a4, supportedModes as a5, supportedReferenceRoles as a6, textFieldCapability as a7, type GenerationRequest as b, type PlanAssetMention as c, type GenerationReference as d, type BuiltinReferenceRole as e, type CapabilityOverlay as f, type CapabilityPresentation as g, type CountCapability as h, type EnumParamSpec as i, type ExtraParamSpec as j, GENERATION_REQUEST_FIELDS as k, type GenerationMediaKind as l, type GenerationMode as m, type GenerationParamValue as n, PROVENANCE_FORMAT as o, PROVENANCE_VERSION as p, type PinnedTemplate as q, type PlanAdjustment as r, type PlanAdjustmentKind as s, type PlanError as t, type PlanOptions as u, type PromptCapability as v, ProvenanceParseError as w, REFERENCE_ROLES as x, REFERENCE_ROLE_ALIASES as y, REFERENCE_ROLE_LABELS as z };