@pixerate/editor 0.24.0 → 0.25.0

package/dist/generation/index.js

@@ -8,8 +8,17 @@ import "../chunk-P6ODPZ4W.js";
 import {
   validateJsonSchema
 } from "../chunk-ARRTP33I.js";
+import {
+  findTextMentions,
+  formatMentionText,
+  setMentionRoleInText
+} from "../chunk-O5RYH2PG.js";
 
 // src/generation/capabilities.ts
+var REFERENCE_ROLE_NAME_REGEX = /^[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9])?$/;
+function isReferenceRoleName(value) {
+  return typeof value === "string" && value.length <= 64 && REFERENCE_ROLE_NAME_REGEX.test(value);
+}
 var REFERENCE_ROLES = [
   "start_frame",
   "end_frame",
@@ -32,6 +41,56 @@ var REFERENCE_ROLE_LABELS = {
   video_ref: "Video reference",
   audio_ref: "Audio reference"
 };
+var REFERENCE_ROLE_ALIASES = {
+  reference: "image_ref",
+  image: "image_ref",
+  style: "style_ref",
+  character: "character_ref",
+  background: "background_ref",
+  "start-frame": "start_frame",
+  "first-frame": "start_frame",
+  first_frame: "start_frame",
+  "end-frame": "end_frame",
+  "last-frame": "end_frame",
+  last_frame: "end_frame",
+  "style-ref": "style_ref",
+  "character-ref": "character_ref",
+  "background-ref": "background_ref",
+  "image-ref": "image_ref",
+  "video-ref": "video_ref",
+  "audio-ref": "audio_ref",
+  video: "video_ref",
+  audio: "audio_ref"
+};
+var isBuiltinRole = (role) => REFERENCE_ROLES.includes(role);
+function referenceRoleLabel(role, caps) {
+  const declared = caps?.references?.roles[role]?.label;
+  if (declared) return declared;
+  if (isBuiltinRole(role)) return REFERENCE_ROLE_LABELS[role];
+  const words = String(role).replace(/[_-]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function normalizeReferenceRole(role, caps) {
+  const name = String(role).trim();
+  if (caps ? !!caps.references?.roles[name] : isBuiltinRole(name)) return name;
+  const lower = name.toLowerCase();
+  if (caps?.references?.roles[lower]) return lower;
+  if (!caps && isBuiltinRole(lower)) return lower;
+  return REFERENCE_ROLE_ALIASES[lower] ?? (isBuiltinRole(lower) ? lower : name);
+}
+function mediaTypeMatches(mediaType, accepts) {
+  if (!accepts || accepts.length === 0) return true;
+  if (!mediaType) return false;
+  const type = mediaType.split(";")[0].trim().toLowerCase();
+  const kind = type.split("/")[0];
+  return accepts.some((entry) => {
+    const pattern = entry.trim().toLowerCase();
+    if (pattern === "*" || pattern === "*/*" || pattern === type) return true;
+    if (!pattern.includes("/")) return pattern === kind;
+    if (pattern.endsWith("/*")) return pattern.slice(0, -2) === kind;
+    return false;
+  });
+}
 var GENERATION_REQUEST_FIELDS = [
   "model",
   "prompt",
@@ -57,7 +116,11 @@ function seedCapability(value) {
 }
 function supportedReferenceRoles(caps) {
   const roles = caps.references?.roles ?? {};
-  return REFERENCE_ROLES.filter((role) => (roles[role]?.max ?? 0) > 0);
+  const builtin = REFERENCE_ROLES.filter((role) => (roles[role]?.max ?? 0) > 0);
+  const custom = Object.keys(roles).filter(
+    (role) => !isBuiltinRole(role) && isReferenceRoleName(role) && (roles[role]?.max ?? 0) > 0
+  );
+  return [...builtin, ...custom];
 }
 function supportedModes(caps) {
   const modes = ["generate"];
@@ -356,19 +419,80 @@ var Planner = class {
     if (role === "mask" && this.caps.inpainting) return { max: 1 };
     return void 0;
   }
+  /** Turns `options.mentions` into references (appended after the request's own). */
+  addMentions() {
+    const mentions = this.options.mentions;
+    if (!mentions?.length) return;
+    const refs = [...this.request.references ?? []];
+    for (const mention of mentions) {
+      if (!mention || typeof mention.id !== "string" || mention.id === "") continue;
+      let role = mention.role ?? void 0;
+      if (!role) {
+        role = this.options.defaultMentionRole ?? this.inferRole(mention.mediaType);
+        this.adjust(
+          `references.${role}`,
+          void 0,
+          role,
+          "defaulted",
+          `@${mention.label ?? mention.id} has no role; using ${role}.`
+        );
+      }
+      refs.push({
+        id: mention.id,
+        role,
+        ...mention.url !== void 0 ? { url: mention.url } : {},
+        ...mention.mediaType !== void 0 ? { mediaType: mention.mediaType } : {},
+        ...mention.contentHash !== void 0 ? { contentHash: mention.contentHash } : {}
+      });
+    }
+    this.request.references = refs;
+  }
+  /** First role of the model (other than `mask`) whose `accepts` matches `mediaType`. */
+  inferRole(mediaType) {
+    for (const role of supportedReferenceRoles(this.caps)) {
+      if (role === "mask") continue;
+      const cap = this.roleCapability(role);
+      if (cap && (mediaType === void 0 || mediaTypeMatches(mediaType, cap.accepts))) return role;
+    }
+    return "image_ref";
+  }
   planReferences() {
     const refs = this.request.references;
     const allowDrop = !this.strict && (this.options.dropUnsupportedReferences ?? (this.strategy === "nearest" || this.strategy === "downgrade"));
     const byRole = /* @__PURE__ */ new Map();
     const kept = [];
     const unsupported = /* @__PURE__ */ new Map();
-    for (const [index, ref] of (refs ?? []).entries()) {
-      if (!ref || typeof ref.id !== "string" || ref.id === "" || !REFERENCE_ROLES.includes(ref.role)) {
-        this.error(`references.${index}`, ref, "Each reference needs an `id` and a known `role`.");
+    for (const [index, original] of (refs ?? []).entries()) {
+      let ref = original;
+      if (!ref || typeof ref.id !== "string" || ref.id === "" || !isReferenceRoleName(ref.role)) {
+        this.error(`references.${index}`, ref, "Each reference needs an `id` and a valid `role`.");
         continue;
       }
       if (!this.roleCapability(ref.role)) {
-        unsupported.set(ref.role, (unsupported.get(ref.role) ?? 0) + 1);
+        const alias = normalizeReferenceRole(ref.role, this.caps);
+        if (alias !== ref.role && this.roleCapability(alias)) {
+          if (this.strict) {
+            this.error(`references.${ref.role}`, ref.role, `The model calls this role ${describe(alias)}.`);
+            continue;
+          }
+          this.adjust(
+            `references.${ref.role}`,
+            ref.role,
+            alias,
+            "snapped",
+            `Using the model's ${alias} role for ${describe(ref.role)}.`
+          );
+          ref = { ...ref, role: alias };
+        } else {
+          unsupported.set(ref.role, (unsupported.get(ref.role) ?? 0) + 1);
+          continue;
+        }
+      }
+      const cap = this.roleCapability(ref.role);
+      if (ref.mediaType !== void 0 && !mediaTypeMatches(ref.mediaType, cap.accepts)) {
+        const message = `${describe(ref.id)} is ${describe(ref.mediaType)}; ${ref.role} accepts ${list(cap.accepts ?? [])}.`;
+        if (allowDrop) this.adjust(`references.${ref.role}`, ref.id, void 0, "dropped", message);
+        else this.error(`references.${ref.role}`, ref.id, message);
         continue;
       }
       const group = byRole.get(ref.role) ?? [];
@@ -386,7 +510,10 @@ var Planner = class {
       else this.error(`references.${role}`, count, message);
     }
     const removed = /* @__PURE__ */ new Set();
-    for (const role of REFERENCE_ROLES) {
+    const custom = supportedReferenceRoles(this.caps).filter(
+      (role) => !REFERENCE_ROLES.includes(role)
+    );
+    for (const role of [...REFERENCE_ROLES, ...custom]) {
       const cap = this.roleCapability(role);
       const group = byRole.get(role) ?? [];
       if (!cap) continue;
@@ -525,6 +652,7 @@ var Planner = class {
     this.planDuration();
     this.planSeed();
     this.planMode();
+    this.addMentions();
     this.planReferences();
     this.planParams();
   }
@@ -642,7 +770,8 @@ function capabilitiesToJsonSchema(caps) {
     const limits = roles.map((role) => {
       const cap = caps.references?.roles[role] ?? { max: 1 };
       const min = cap.min ? `${cap.min}\u2013` : "up to ";
-      return `${role} (${cap.label ?? REFERENCE_ROLE_LABELS[role]}): ${min}${cap.max}`;
+      const accepts = "accepts" in cap && cap.accepts?.length ? `, ${cap.accepts.join("/")} only` : "";
+      return `${role} (${referenceRoleLabel(role, caps)}): ${min}${cap.max}${accepts}`;
     });
     const perRoleTotal = roles.reduce((sum, role) => sum + (caps.references?.roles[role]?.max ?? 1), 0);
     const maxItems = Math.min(caps.references?.maxTotal ?? Infinity, perRoleTotal);
@@ -655,7 +784,9 @@ function capabilitiesToJsonSchema(caps) {
         properties: {
           id: { type: "string", minLength: 1, description: "Asset id." },
           role: { type: "string", enum: roles },
-          url: { type: "string" }
+          url: { type: "string" },
+          mediaType: { type: "string", description: 'MIME type or media kind of the asset, e.g. "image/png".' },
+          contentHash: { type: "string" }
         },
         required: ["id", "role"],
         additionalProperties: false
@@ -682,9 +813,58 @@ function capabilitiesToJsonSchema(caps) {
   };
 }
 
+// src/generation/hash.ts
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => item === void 0 ? "null" : stableStringify(item)).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.keys(value).filter((key) => value[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+var FNV_PRIME = 16777619;
+function hashText(text) {
+  let a = 2166136261;
+  let b = 789454171;
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i);
+    a = Math.imul(a ^ unit & 255, FNV_PRIME);
+    a = Math.imul(a ^ unit >>> 8, FNV_PRIME);
+    b = Math.imul(b ^ unit >>> 8, FNV_PRIME);
+    b = Math.imul(b ^ unit & 255, FNV_PRIME);
+    b ^= b >>> 15;
+  }
+  a ^= a >>> 16;
+  a = Math.imul(a, 2246822507);
+  a ^= a >>> 13;
+  b ^= b >>> 16;
+  b = Math.imul(b, 3266489909);
+  b ^= b >>> 13;
+  const hex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+  return `h1-${hex(a)}${hex(b)}`;
+}
+function hashValue(value) {
+  return hashText(stableStringify(value));
+}
+var PRESENTATION_ONLY = /* @__PURE__ */ new Set(["name", "description", "badges", "icon", "group", "timing"]);
+function hashCapabilities(caps) {
+  const relevant = {};
+  for (const key of Object.keys(caps)) {
+    if (!PRESENTATION_ONLY.has(key)) relevant[key] = caps[key];
+  }
+  return hashValue(relevant);
+}
+
 // src/generation/tools.ts
 var STRATEGIES = ["nearest", "upgrade", "downgrade", "error"];
-var requestSchema = {
+function knownRoles(models) {
+  const roles = [...REFERENCE_ROLES];
+  for (const model of models) {
+    for (const role of supportedReferenceRoles(model)) if (!roles.includes(role)) roles.push(role);
+  }
+  return roles;
+}
+var requestSchemaFor = (roles) => ({
   type: "object",
   description: "Generation request. Call list_models for the fields each model supports; unsupported values are adjusted per `strategy`.",
   properties: {
@@ -704,8 +884,14 @@ var requestSchema = {
         type: "object",
         properties: {
           id: { type: "string", minLength: 1 },
-          role: { type: "string", enum: [...REFERENCE_ROLES] },
-          url: { type: "string" }
+          role: {
+            type: "string",
+            enum: [...roles],
+            description: "What the asset is used for. Each model lists the roles it accepts (list_models)."
+          },
+          url: { type: "string" },
+          mediaType: { type: "string", description: 'MIME type or media kind, e.g. "image/png".' },
+          contentHash: { type: "string" }
         },
         required: ["id", "role"],
         additionalProperties: false
@@ -714,20 +900,12 @@ var requestSchema = {
     params: { type: "object", additionalProperties: { type: ["string", "number", "boolean"] } }
   },
   additionalProperties: false
-};
+});
 var strategySchema = {
   type: "string",
   enum: STRATEGIES,
   description: "How to handle unsupported values: nearest (snap/clamp, ties up), downgrade (ties down), upgrade (ties up, never drops references), error (change nothing)."
 };
-function stableStringify(value) {
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-  if (value && typeof value === "object") {
-    const entries = Object.keys(value).filter((key) => value[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
-    return `{${entries.join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
-}
 function planFailure(plan) {
   return {
     isError: true,
@@ -746,13 +924,13 @@ function createGenerationToolProvider(options) {
   const defaultStrategy = options.defaultStrategy ?? "nearest";
   const maxKeys = Math.max(1, options.maxIdempotencyKeys ?? 500);
   const calls = /* @__PURE__ */ new Map();
-  const findModel = (id) => {
+  const findModel2 = (id) => {
     const model = readModels().find((m) => m.id === id);
     if (!model) throw new Error(`Unknown model "${String(id)}". Call list_models for the available ids.`);
     return model;
   };
   const plan = (args) => {
-    const model = findModel(args.model);
+    const model = findModel2(args.model);
     const request = { ...args.request ?? {}, model: model.id };
     return {
       model,
@@ -763,12 +941,13 @@ function createGenerationToolProvider(options) {
     };
   };
   const planInput = () => {
-    const ids = readModels().map((m) => m.id);
+    const models = readModels();
+    const ids = models.map((m) => m.id);
     return {
       type: "object",
       properties: {
         model: { type: "string", ...ids.length ? { enum: ids } : {}, description: "Model id from list_models." },
-        request: requestSchema,
+        request: requestSchemaFor(knownRoles(models)),
         strategy: strategySchema,
         resolvedPrompt: {
           type: "string",
@@ -1046,12 +1225,6 @@ function parseProvenance(input) {
     values: isRecord(data.values) ? data.values : null
   };
 }
-function recreateRequest(provenance) {
-  const request = clone(provenance.request);
-  request.model = provenance.modelId;
-  if (request.prompt === void 0) request.prompt = provenance.resolvedPrompt;
-  return request;
-}
 function replayProvenancePrompt(provenance) {
   const result = resolvePrompt(provenance.rawPrompt, pinnedTemplatesToTemplates(provenance.templates), {
     bindings: provenance.bindings,
@@ -1311,8 +1484,9 @@ function getReferenceSlots(caps, request = {}) {
     const references = refs.filter((ref) => ref.role === role);
     return {
       role,
-      label: cap.label ?? REFERENCE_ROLE_LABELS[role],
+      label: referenceRoleLabel(role, caps),
       ...cap.description ? { description: cap.description } : {},
+      ..."accepts" in cap && cap.accepts?.length ? { accepts: [...cap.accepts] } : {},
       min: cap.min ?? 0,
       max: cap.max,
       references,
@@ -1329,7 +1503,747 @@ function removeReference(request, role, id) {
   if (references.length === 0) delete next.references;
   return next;
 }
+
+// src/generation/assets.ts
+function toAssetResolver(lookup) {
+  if (!lookup) return void 0;
+  if (typeof lookup === "function") return (id) => lookup(id) ?? void 0;
+  if (lookup instanceof Map) return (id) => lookup.get(id);
+  const byId = new Map(lookup.map((asset) => [asset.id, asset]));
+  return (id) => byId.get(id);
+}
+function roleCap(caps, role) {
+  const cap = caps.references?.roles[role];
+  if (cap && cap.max > 0) return cap;
+  if (role === "mask" && caps.inpainting) return { max: 1 };
+  return void 0;
+}
+function getAssetRoleOptions(caps) {
+  const roles = supportedReferenceRoles(caps);
+  if (caps.inpainting && !roles.includes("mask")) roles.push("mask");
+  return roles.map((role) => {
+    const cap = roleCap(caps, role) ?? { max: 1 };
+    return {
+      role,
+      label: referenceRoleLabel(role, caps),
+      ...cap.description ? { description: cap.description } : {},
+      min: cap.min ?? 0,
+      max: cap.max,
+      ...cap.accepts?.length ? { accepts: [...cap.accepts] } : {}
+    };
+  });
+}
+function validateAssetMentions(mentions, caps, options = {}) {
+  const resolve = toAssetResolver(options.assets);
+  const issues = [];
+  const counts = {};
+  mentions.forEach((mention, index) => {
+    const id = mention.id;
+    const label = `@${mention.label ?? id}`;
+    if (!mention.role) {
+      issues.push({ index, id, code: "missing-role", severity: "warning", message: `${label} has no role.` });
+      return;
+    }
+    let role = mention.role;
+    if (!roleCap(caps, role)) {
+      const alias = normalizeReferenceRole(role, caps);
+      if (alias !== role && roleCap(caps, alias)) {
+        issues.push({
+          index,
+          id,
+          role,
+          code: "renamed-role",
+          severity: "warning",
+          suggestion: alias,
+          message: `${label}: this model calls "${role}" ${referenceRoleLabel(alias, caps)} (${alias}).`
+        });
+        role = alias;
+      } else {
+        issues.push({
+          index,
+          id,
+          role,
+          code: "unsupported-role",
+          severity: "error",
+          message: `${label}: ${caps.name ?? caps.id} does not accept ${referenceRoleLabel(role, caps).toLowerCase()} assets.`
+        });
+        return;
+      }
+    }
+    const cap = roleCap(caps, role);
+    const mediaType = mention.mediaType ?? resolve?.(id)?.mediaType;
+    if (mediaType !== void 0 && !mediaTypeMatches(mediaType, cap.accepts)) {
+      issues.push({
+        index,
+        id,
+        role,
+        code: "media-mismatch",
+        severity: "error",
+        message: `${label} is ${mediaType}; ${referenceRoleLabel(role, caps)} accepts ${(cap.accepts ?? []).join(", ")}.`
+      });
+      return;
+    }
+    counts[role] = (counts[role] ?? 0) + 1;
+    if (counts[role] > cap.max) {
+      issues.push({
+        index,
+        id,
+        role,
+        code: "too-many",
+        severity: "warning",
+        message: `${label}: at most ${cap.max} ${referenceRoleLabel(role, caps).toLowerCase()} asset(s); extra ones are left out.`
+      });
+    }
+  });
+  const missing = getAssetRoleOptions(caps).filter((option) => (counts[option.role] ?? 0) < option.min).map((option) => ({ role: option.role, min: option.min, count: counts[option.role] ?? 0 }));
+  return { ok: !issues.some((issue) => issue.severity === "error") && missing.length === 0, issues, counts, missing };
+}
+function resolveAssetMentions(mentions, assets) {
+  const byId = new Map(assets.map((asset) => [asset.id, asset]));
+  const byLabel = new Map(assets.filter((a) => a.label).map((asset) => [asset.label.toLowerCase(), asset]));
+  const result = [];
+  for (const mention of mentions) {
+    const asset = byId.get(mention.handle) ?? byLabel.get(mention.handle.toLowerCase());
+    if (!asset) continue;
+    result.push({
+      id: asset.id,
+      label: mention.handle,
+      ...mention.role ? { role: mention.role } : {},
+      ...asset.mediaType !== void 0 ? { mediaType: asset.mediaType } : {},
+      ...asset.contentHash !== void 0 ? { contentHash: asset.contentHash } : {},
+      ...asset.url !== void 0 ? { url: asset.url } : {}
+    });
+  }
+  return result;
+}
+function defaultAssetRoleOptions() {
+  return REFERENCE_ROLES.map((role) => ({ role, label: referenceRoleLabel(role), min: 0, max: 1 }));
+}
+function describeAssetMentions(mentions, assets, caps) {
+  const byId = new Map(assets.map((asset) => [asset.id, asset]));
+  const byLabel = new Map(assets.filter((a) => a.label).map((asset) => [asset.label.toLowerCase(), asset]));
+  const chips = [];
+  for (const mention of mentions) {
+    const asset = byId.get(mention.handle) ?? byLabel.get(mention.handle.toLowerCase());
+    if (!asset) continue;
+    const role = mention.role || void 0;
+    chips.push({
+      index: chips.length,
+      ...mention.start !== void 0 ? { start: mention.start } : {},
+      handle: mention.handle,
+      asset,
+      ...role ? { role, roleLabel: referenceRoleLabel(caps ? normalizeReferenceRole(role, caps) : role, caps) } : {},
+      issues: []
+    });
+  }
+  if (caps) {
+    const validation = validateAssetMentions(
+      chips.map((chip) => ({
+        id: chip.asset.id,
+        label: chip.handle,
+        ...chip.role ? { role: chip.role } : {},
+        ...chip.asset.mediaType ? { mediaType: chip.asset.mediaType } : {}
+      })),
+      caps
+    );
+    for (const issue of validation.issues) chips[issue.index].issues.push(issue);
+  }
+  return chips;
+}
+
+// src/generation/record.ts
+var GENERATION_RECORD_FORMAT = "pixerate.generation-record";
+var GENERATION_RECORD_VERSION = 1;
+var idCounter = 0;
+function createGenerationRecordId() {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (typeof uuid === "string") return `gen_${uuid}`;
+  idCounter = (idCounter + 1) % 1679616;
+  const random = Math.floor(Math.random() * 2 ** 48).toString(36).padStart(10, "0");
+  return `gen_${Date.now().toString(36)}${idCounter.toString(36).padStart(4, "0")}${random}`;
+}
+var clone2 = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
+function recordTemplates(pinned) {
+  return pinned.map((p) => ({
+    name: p.name,
+    ...p.templateId !== void 0 ? { templateId: p.templateId } : {},
+    ...p.versionId !== void 0 ? { versionId: p.versionId, version: p.version } : {},
+    hash: hashText(p.body)
+  }));
+}
+function recordAssets(references, lookup) {
+  const resolve = toAssetResolver(lookup);
+  return (references ?? []).map((ref) => {
+    const info = resolve?.(ref.id);
+    const contentHash = ref.contentHash ?? info?.contentHash;
+    const mediaType = ref.mediaType ?? info?.mediaType;
+    const url = ref.url ?? info?.url;
+    return {
+      id: ref.id,
+      role: ref.role,
+      ...contentHash !== void 0 ? { contentHash } : {},
+      ...mediaType !== void 0 ? { mediaType } : {},
+      ...url !== void 0 ? { url } : {}
+    };
+  });
+}
+function createGenerationRecord(options) {
+  const {
+    model,
+    request: settingsInput,
+    plan: planInput,
+    strategy: strategyInput,
+    mentions,
+    assets,
+    seed: seedInput,
+    id,
+    parentId,
+    kind,
+    ...provenanceOptions
+  } = options;
+  const caps = typeof model === "string" ? void 0 : model;
+  const settings = clone2(settingsInput ?? planInput?.request ?? {});
+  let plan = planInput;
+  if (!plan && caps) {
+    const resolved = resolvePrompt(options.rawPrompt, options.templates ?? [], {
+      bindings: options.bindings,
+      values: options.values,
+      maxDepth: options.maxDepth
+    });
+    plan = planGenerationRequest(settings, caps, {
+      strategy: strategyInput ?? "nearest",
+      resolvedPrompt: resolved.text,
+      ...mentions ? { mentions } : {}
+    });
+  }
+  const provenance = createProvenance({
+    ...provenanceOptions,
+    model,
+    ...plan ? { plan } : { request: settings }
+  });
+  const seed = seedInput ?? provenance.request.seed;
+  return {
+    format: GENERATION_RECORD_FORMAT,
+    version: GENERATION_RECORD_VERSION,
+    id: id ?? createGenerationRecordId(),
+    ...parentId !== void 0 ? { parentId } : {},
+    kind: kind ?? (parentId !== void 0 ? "recreate" : "generate"),
+    provenance,
+    templates: recordTemplates(provenance.templates),
+    promptHash: hashText(provenance.resolvedPrompt),
+    ...caps ? { capabilityHash: hashCapabilities(caps) } : {},
+    settings,
+    strategy: strategyInput ?? plan?.strategy ?? "nearest",
+    ...seed !== void 0 ? { seed } : {},
+    assets: recordAssets(provenance.request.references, assets),
+    ...mentions?.length ? { mentions: clone2([...mentions]) } : {},
+    createdAt: provenance.createdAt
+  };
+}
+function completeGenerationRecord(record, update) {
+  const next = clone2(record);
+  const now = new Date(update.completedAt ?? Date.now()).toISOString();
+  if (update.outputIds) next.provenance.outputIds = [...update.outputIds];
+  next.provenance.completedAt = now;
+  if (update.meta) next.provenance.meta = { ...next.provenance.meta ?? {}, ...clone2(update.meta) };
+  if (update.seed !== void 0) next.seed = update.seed;
+  next.updatedAt = now;
+  return next;
+}
+function serializeGenerationRecord(record) {
+  return JSON.stringify(record);
+}
+var isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+function parseGenerationRecord(input) {
+  let data = input;
+  if (typeof input === "string") {
+    try {
+      data = JSON.parse(input);
+    } catch {
+      throw new ProvenanceParseError("Generation record is not valid JSON.");
+    }
+  }
+  if (!isObject(data) || data.format !== GENERATION_RECORD_FORMAT) {
+    throw new ProvenanceParseError("Not a generation record.");
+  }
+  if (typeof data.version !== "number" || data.version > GENERATION_RECORD_VERSION) {
+    throw new ProvenanceParseError(`Unsupported generation record version ${JSON.stringify(data.version)}.`);
+  }
+  const checks = [
+    ["id", typeof data.id === "string" && data.id !== ""],
+    ["templates", Array.isArray(data.templates) && data.templates.every((t) => isObject(t) && typeof t.name === "string" && typeof t.hash === "string")],
+    ["assets", Array.isArray(data.assets) && data.assets.every((a) => isObject(a) && typeof a.id === "string" && typeof a.role === "string")],
+    ["settings", isObject(data.settings)],
+    ["promptHash", typeof data.promptHash === "string"],
+    ["createdAt", typeof data.createdAt === "string"]
+  ];
+  const bad = checks.find(([, ok]) => !ok);
+  if (bad) throw new ProvenanceParseError(`Invalid generation record field "${bad[0]}".`);
+  const provenance = parseProvenance(data.provenance);
+  return {
+    ...data,
+    kind: data.kind === "recreate" || data.kind === "variation" ? data.kind : "generate",
+    strategy: ["nearest", "upgrade", "downgrade", "error"].includes(data.strategy) ? data.strategy : "nearest",
+    provenance
+  };
+}
+function isGenerationRecord(value) {
+  return isObject(value) && value.format === GENERATION_RECORD_FORMAT;
+}
+var SKIPPED_SETTING_FIELDS = /* @__PURE__ */ new Set(["model", "prompt", "references", "params", "seed"]);
+function findModel(capabilities, modelId) {
+  if (!capabilities) return { given: false };
+  const list2 = Array.isArray(capabilities) ? capabilities : [capabilities];
+  return { given: true, caps: list2.find((m) => m.id === modelId) };
+}
+var sameValue = (a, b) => stableStringify(a) === stableStringify(b);
+var show = (value) => value === void 0 ? "unset" : typeof value === "string" ? `"${value}"` : JSON.stringify(value);
+var refKey = (ref) => `${ref.role}:${ref.id}`;
+function templateDrift(record, current, mode) {
+  if (!current) return [];
+  const byName = new Map(current.map((t) => [t.name, t]));
+  const drift = [];
+  for (const recorded of record.templates) {
+    const template = byName.get(recorded.name);
+    const fromVersion = recorded.version ?? recorded.versionId;
+    if (!template) {
+      drift.push({
+        type: "template-missing",
+        severity: "warning",
+        template: recorded.name,
+        from: fromVersion,
+        applied: false,
+        message: `Template "${recorded.name}" no longer exists; the recorded body is used.`
+      });
+      continue;
+    }
+    const body = getTemplateBody(template, {});
+    const hash = body === void 0 ? void 0 : hashText(body);
+    if (hash === recorded.hash) continue;
+    const latest = getLatestVersion(template);
+    const toVersion = template.versions?.length ? latest?.version ?? latest?.id : void 0;
+    const versions = fromVersion !== void 0 || toVersion !== void 0 ? ` (${fromVersion ?? "unversioned"} \u2192 ${toVersion ?? "unversioned"})` : "";
+    drift.push({
+      type: "template-changed",
+      severity: mode === "latest" ? "info" : "warning",
+      template: recorded.name,
+      from: { version: fromVersion, hash: recorded.hash },
+      to: { version: toVersion, hash },
+      applied: mode === "latest",
+      message: mode === "latest" ? `Template "${recorded.name}" changed since this generation${versions}; using the current version.` : `Template "${recorded.name}" changed since this generation${versions}; recreating with the recorded version.`
+    });
+  }
+  return drift;
+}
+function randomSeed(caps, previous, random) {
+  const cap = caps ? seedCapability(caps.seed) : {};
+  if (!cap) return void 0;
+  const min = Math.ceil(cap.min ?? 0);
+  const max = Math.floor(cap.max ?? 2 ** 31 - 1);
+  if (max < min) return min;
+  let seed = previous;
+  for (let attempt = 0; attempt < 8 && (seed === void 0 || seed === previous); attempt++) {
+    seed = min + Math.floor(random() * (max - min + 1));
+  }
+  if (seed === previous && max > min) seed = previous === max ? min : previous + 1;
+  return seed;
+}
+function rebuild(record, options, kind, overrides) {
+  const mode = options.mode ?? "exact";
+  const provenance = record.provenance;
+  const drift = templateDrift(record, options.templates, mode);
+  const rawPrompt = overrides?.rawPrompt ?? provenance.rawPrompt;
+  const values = overrides?.values !== void 0 ? { ...provenance.values ?? {}, ...overrides.values } : provenance.values ? clone2(provenance.values) : null;
+  const pinned = pinnedTemplatesToTemplates(provenance.templates);
+  let templates;
+  let bindings;
+  if (mode === "latest" && options.templates) {
+    const currentNames = new Set(options.templates.map((t) => t.name));
+    const fallback = pinned.filter((t) => !currentNames.has(t.name));
+    templates = [...options.templates.map((t) => ({ ...t })), ...fallback];
+    bindings = {};
+    for (const t of fallback) {
+      if (provenance.bindings[t.name] !== void 0) bindings[t.name] = provenance.bindings[t.name];
+    }
+  } else {
+    templates = pinned;
+    bindings = { ...provenance.bindings };
+  }
+  const resolved = resolvePrompt(rawPrompt, templates, { bindings, ...values ? { values } : {} });
+  const sourceMap = resolved.map.map((segment) => {
+    const { locked: _locked, ...rest } = segment;
+    return rest;
+  });
+  if (resolved.text !== provenance.resolvedPrompt && !overrides) {
+    drift.push({
+      type: "prompt-changed",
+      severity: "info",
+      from: provenance.resolvedPrompt,
+      to: resolved.text,
+      applied: true,
+      message: "The resolved prompt differs from the recorded one."
+    });
+  }
+  const base = clone2(mode === "exact" ? provenance.request : record.settings);
+  const recordedPlanned = provenance.request;
+  if (base.prompt === void 0 || base.prompt === provenance.resolvedPrompt) base.prompt = resolved.text;
+  else if (base.prompt === provenance.rawPrompt) base.prompt = rawPrompt;
+  if (mode === "latest" && record.mentions?.length) {
+    const plannedRole = new Map((recordedPlanned.references ?? []).map((ref) => [ref.id, ref.role]));
+    base.references = [
+      ...base.references ?? [],
+      ...record.mentions.map((m) => ({
+        id: m.id,
+        role: m.role || plannedRole.get(m.id) || "image_ref",
+        ...m.url !== void 0 ? { url: m.url } : {},
+        ...m.mediaType !== void 0 ? { mediaType: m.mediaType } : {},
+        ...m.contentHash !== void 0 ? { contentHash: m.contentHash } : {}
+      }))
+    ];
+  } else if (mode === "latest" && base.references === void 0 && recordedPlanned.references) {
+    base.references = clone2(recordedPlanned.references);
+  }
+  if (record.seed !== void 0) base.seed = record.seed;
+  base.model = provenance.modelId;
+  const { given, caps } = findModel(options.capabilities, provenance.modelId);
+  if (overrides) {
+    if (overrides.settings) {
+      const { params, ...rest } = overrides.settings;
+      Object.assign(base, clone2(rest));
+      if (params) base.params = { ...base.params ?? {}, ...clone2(params) };
+    }
+    if (overrides.seed === null) delete base.seed;
+    else base.seed = overrides.seed ?? randomSeed(caps, record.seed, overrides.random ?? Math.random);
+    if (base.seed === void 0) delete base.seed;
+  }
+  const resolveAsset = toAssetResolver(options.assets);
+  if (resolveAsset && base.references) {
+    const recordedById = new Map(record.assets.map((a) => [refKey(a), a]));
+    const kept = [];
+    for (const ref of base.references) {
+      const info = resolveAsset(ref.id);
+      if (!info) {
+        drift.push({
+          type: "asset-missing",
+          severity: "error",
+          assetId: ref.id,
+          role: ref.role,
+          message: `Asset "${ref.id}" (${ref.role}) is no longer available.`
+        });
+        continue;
+      }
+      const recordedHash = recordedById.get(refKey(ref))?.contentHash ?? ref.contentHash;
+      if (recordedHash !== void 0 && info.contentHash !== void 0 && recordedHash !== info.contentHash) {
+        drift.push({
+          type: "asset-changed",
+          severity: "warning",
+          assetId: ref.id,
+          role: ref.role,
+          from: recordedHash,
+          to: info.contentHash,
+          applied: true,
+          message: `Asset "${ref.id}" (${ref.role}) has changed since this generation.`
+        });
+      }
+      const next = { ...ref };
+      if (info.contentHash !== void 0) next.contentHash = info.contentHash;
+      if (next.mediaType === void 0 && info.mediaType !== void 0) next.mediaType = info.mediaType;
+      kept.push(next);
+    }
+    if (kept.length) base.references = kept;
+    else delete base.references;
+  }
+  let plan;
+  let request = base;
+  if (given && !caps) {
+    drift.push({
+      type: "model-missing",
+      severity: "error",
+      modelId: provenance.modelId,
+      message: `Model "${provenance.modelId}" is no longer available.`
+    });
+  } else if (caps) {
+    const capabilityHash = hashCapabilities(caps);
+    if (record.capabilityHash !== void 0 && record.capabilityHash !== capabilityHash) {
+      drift.push({
+        type: "model-changed",
+        severity: "warning",
+        modelId: caps.id,
+        from: record.capabilityHash,
+        to: capabilityHash,
+        message: `The capabilities of "${caps.name ?? caps.id}" changed since this generation.`
+      });
+    }
+    plan = planGenerationRequest(base, caps, {
+      strategy: options.strategy ?? record.strategy,
+      resolvedPrompt: resolved.text
+    });
+    request = plan.request;
+    const severity = mode === "exact" && !overrides ? "warning" : "info";
+    const type = mode === "exact" && !overrides ? "setting-unsupported" : "setting-changed";
+    const describeChange = (field, from, to) => {
+      const adjustment = plan.adjustments.find((a) => a.field === field || a.field.startsWith(`${field}.`));
+      drift.push({
+        type,
+        severity,
+        field,
+        from,
+        to,
+        applied: true,
+        message: type === "setting-unsupported" ? `${field} ${show(from)} is no longer supported; using ${show(to)}.${adjustment ? ` ${adjustment.reason}` : ""}` : `${field} was ${show(from)}, now ${show(to)}.${adjustment ? ` ${adjustment.reason}` : ""}`
+      });
+    };
+    if (!overrides) {
+      for (const field of GENERATION_REQUEST_FIELDS) {
+        if (SKIPPED_SETTING_FIELDS.has(field)) continue;
+        const from = recordedPlanned[field];
+        const to = request[field];
+        if (!sameValue(from, to)) describeChange(field, from, to);
+      }
+      const paramNames = /* @__PURE__ */ new Set([...Object.keys(recordedPlanned.params ?? {}), ...Object.keys(request.params ?? {})]);
+      for (const name of [...paramNames].sort()) {
+        const from = recordedPlanned.params?.[name];
+        const to = request.params?.[name];
+        if (!sameValue(from, to)) describeChange(`params.${name}`, from, to);
+      }
+      if (!sameValue(record.seed ?? recordedPlanned.seed, request.seed)) describeChange("seed", record.seed ?? recordedPlanned.seed, request.seed);
+      const missing = new Set(drift.filter((d) => d.type === "asset-missing").map((d) => `${d.role}:${d.assetId}`));
+      const fromRefs = (recordedPlanned.references ?? []).map(refKey).filter((key) => !missing.has(key));
+      const toRefs = (request.references ?? []).map(refKey);
+      if (!sameValue(fromRefs, toRefs)) describeChange("references", fromRefs, toRefs);
+    }
+    for (const error of plan.errors) {
+      drift.push({
+        type: "setting-unsupported",
+        severity: "error",
+        field: error.field,
+        from: error.value,
+        message: error.message
+      });
+    }
+  }
+  const ok = !drift.some((d) => d.severity === "error") && (plan ? plan.ok : true);
+  const recordOptions = {
+    rawPrompt,
+    templates,
+    bindings,
+    ...values ? { values } : {},
+    model: caps ?? provenance.modelId,
+    request,
+    ...plan ? { plan } : {},
+    strategy: options.strategy ?? record.strategy,
+    parentId: record.id,
+    kind
+  };
+  return {
+    mode,
+    ok,
+    request,
+    ...plan ? { plan } : {},
+    rawPrompt,
+    resolvedPrompt: resolved.text,
+    sourceMap,
+    values,
+    templates,
+    bindings,
+    drift,
+    parentId: record.id,
+    kind,
+    recordOptions
+  };
+}
+function recreateRequest(input, options) {
+  if (isGenerationRecord(input)) return rebuild(input, options ?? {}, "recreate");
+  const provenance = input;
+  const request = clone2(provenance.request);
+  request.model = provenance.modelId;
+  if (request.prompt === void 0) request.prompt = provenance.resolvedPrompt;
+  return request;
+}
+function variationRequest(record, overrides = {}, options = {}) {
+  return rebuild(record, options, "variation", overrides);
+}
+var DRIFT_TYPE_LABELS = {
+  "template-changed": "Template changed",
+  "template-missing": "Template deleted",
+  "prompt-changed": "Prompt changed",
+  "model-missing": "Model unavailable",
+  "model-changed": "Model changed",
+  "setting-unsupported": "Setting unsupported",
+  "setting-changed": "Setting changed",
+  "asset-missing": "Asset missing",
+  "asset-changed": "Asset changed"
+};
+function blockingDrift(drift) {
+  return drift.filter((d) => d.severity === "error");
+}
+
+// src/generation/store.ts
+var INDEX_VERSION = 1;
+var time = (value) => new Date(value).getTime();
+function summarizeGenerationRecord(record) {
+  const unique = (values) => [...new Set(values)];
+  return {
+    id: record.id,
+    modelId: record.provenance.modelId,
+    kind: record.kind,
+    ...record.parentId !== void 0 ? { parentId: record.parentId } : {},
+    createdAt: record.createdAt,
+    templates: unique(record.templates.map((t) => t.name)),
+    templateIds: unique(record.templates.flatMap((t) => t.templateId !== void 0 ? [t.templateId] : [])),
+    assets: unique(record.assets.map((a) => a.id)),
+    roles: unique(record.assets.map((a) => a.role)),
+    preview: record.provenance.resolvedPrompt.slice(0, 160)
+  };
+}
+function matchesRecordFilter(summary, filter = {}) {
+  if (filter.model !== void 0) {
+    const models = typeof filter.model === "string" ? [filter.model] : filter.model;
+    if (!models.includes(summary.modelId)) return false;
+  }
+  if (filter.template !== void 0 && !summary.templates.includes(filter.template) && !summary.templateIds.includes(filter.template)) {
+    return false;
+  }
+  if (filter.asset !== void 0 && !summary.assets.includes(filter.asset)) return false;
+  if (filter.role !== void 0 && !summary.roles.includes(filter.role)) return false;
+  if (filter.kind !== void 0 && summary.kind !== filter.kind) return false;
+  if (filter.parentId !== void 0 && summary.parentId !== filter.parentId) return false;
+  const created = time(summary.createdAt);
+  if (filter.since !== void 0 && created < time(filter.since)) return false;
+  if (filter.until !== void 0 && created >= time(filter.until)) return false;
+  if (filter.text !== void 0 && !summary.preview.toLowerCase().includes(filter.text.toLowerCase())) return false;
+  return true;
+}
+var newestFirst = (a, b) => time(b.createdAt) - time(a.createdAt) || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0);
+function createGenerationRecordStore(options) {
+  const storage = options.storage;
+  const ns = options.namespace ?? "pixerate.generation-records";
+  const indexKey = `${ns}:index`;
+  const recordKey = (id) => `${ns}:record:${id}`;
+  const listeners = /* @__PURE__ */ new Set();
+  let index = null;
+  let queue = Promise.resolve();
+  const run = (task) => {
+    const result = queue.then(task, task);
+    queue = result.catch(() => void 0);
+    return result;
+  };
+  const notify = () => listeners.forEach((listener) => listener());
+  const loadIndex = async () => {
+    if (index) return index;
+    const raw = await storage.get(indexKey);
+    let items = [];
+    if (raw) {
+      try {
+        const data = JSON.parse(raw);
+        if (data && Array.isArray(data.items)) {
+          items = data.items.filter((item) => item && typeof item.id === "string" && typeof item.createdAt === "string");
+        }
+      } catch {
+        items = [];
+      }
+    }
+    index = items;
+    return index;
+  };
+  const saveIndex = async (items) => {
+    await storage.set(indexKey, JSON.stringify({ version: INDEX_VERSION, items }));
+    index = items;
+  };
+  const select = (items, filter = {}) => {
+    const matched = items.filter((s) => matchesRecordFilter(s, filter)).sort(newestFirst);
+    const offset = Math.max(0, filter.offset ?? 0);
+    return matched.slice(offset, filter.limit !== void 0 ? offset + Math.max(0, filter.limit) : void 0);
+  };
+  const pruneLocked = async (prune) => {
+    const items = [...await loadIndex()].sort(newestFirst);
+    const removed = [];
+    const kept = [];
+    let candidates = 0;
+    const cutoff = prune.olderThan !== void 0 ? time(prune.olderThan) : void 0;
+    for (const item of items) {
+      if (prune.keep?.(item)) {
+        kept.push(item);
+        candidates++;
+        continue;
+      }
+      const tooOld = cutoff !== void 0 && time(item.createdAt) < cutoff;
+      const overLimit = prune.maxRecords !== void 0 && candidates >= Math.max(0, prune.maxRecords);
+      if (tooOld || overLimit) removed.push(item);
+      else {
+        kept.push(item);
+        candidates++;
+      }
+    }
+    if (removed.length === 0) return [];
+    await saveIndex(kept);
+    for (const item of removed) await storage.remove(recordKey(item.id));
+    return removed.map((item) => item.id);
+  };
+  return {
+    put: (record) => run(async () => {
+      const serialized = serializeGenerationRecord(record);
+      await storage.set(recordKey(record.id), serialized);
+      const items = (await loadIndex()).filter((item) => item.id !== record.id);
+      items.push(summarizeGenerationRecord(record));
+      await saveIndex(items);
+      if (options.maxRecords !== void 0) await pruneLocked({ maxRecords: options.maxRecords });
+      notify();
+    }),
+    get: (id) => run(async () => {
+      const raw = await storage.get(recordKey(id));
+      if (!raw) return null;
+      try {
+        return parseGenerationRecord(raw);
+      } catch {
+        return null;
+      }
+    }),
+    summaries: (filter) => run(async () => select(await loadIndex(), filter)),
+    list: (filter) => run(async () => {
+      const records = [];
+      for (const summary of select(await loadIndex(), filter)) {
+        const raw = await storage.get(recordKey(summary.id));
+        if (!raw) continue;
+        try {
+          records.push(parseGenerationRecord(raw));
+        } catch {
+        }
+      }
+      return records;
+    }),
+    remove: (id) => run(async () => {
+      const items = await loadIndex();
+      const next = items.filter((item) => item.id !== id);
+      if (next.length === items.length) return false;
+      await saveIndex(next);
+      await storage.remove(recordKey(id));
+      notify();
+      return true;
+    }),
+    prune: (prune) => run(async () => {
+      const removed = await pruneLocked(prune);
+      if (removed.length) notify();
+      return removed;
+    }),
+    clear: () => run(async () => {
+      const items = await loadIndex();
+      await saveIndex([]);
+      for (const item of items) await storage.remove(recordKey(item.id));
+      notify();
+    }),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
 export {
+  DRIFT_TYPE_LABELS,
+  GENERATION_RECORD_FORMAT,
+  GENERATION_RECORD_VERSION,
   GENERATION_REQUEST_FIELDS,
   MAX_PENDING_PERCENT,
   PROVENANCE_FORMAT,
@@ -1337,37 +2251,67 @@ export {
   ProvenanceParseError,
   QUALITY_LADDER,
   REFERENCE_ROLES,
+  REFERENCE_ROLE_ALIASES,
   REFERENCE_ROLE_LABELS,
+  REFERENCE_ROLE_NAME_REGEX,
   addReference,
   aspectRatioRank,
+  blockingDrift,
   capabilitiesToJsonSchema,
+  completeGenerationRecord,
   createBatchResolver,
+  createGenerationRecord,
+  createGenerationRecordId,
+  createGenerationRecordStore,
   createGenerationToolProvider,
   createProvenance,
+  defaultAssetRoleOptions,
+  describeAssetMentions,
   estimateJobProgress,
   expectedDurationFor,
+  findTextMentions,
+  formatMentionText,
   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,
+  setMentionRoleInText,
   setRequestValue,
   snapToOption,
+  stableStringify,
+  summarizeGenerationRecord,
   supportedModes,
   supportedReferenceRoles,
   textFieldCapability,
-  validateJsonSchema
+  toAssetResolver,
+  validateAssetMentions,
+  validateJsonSchema,
+  variationRequest
 };
 //# sourceMappingURL=index.js.map