videoclaw 3.0.0-alpha.1

package/src/video/flow-character-library.ts

@@ -0,0 +1,342 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveProjectWorkspace } from './workspace.js';
+
+// Google Flow v1 Characters & Voices library (useapi.net). Mirrors the
+// seedance-asset-library pattern: register reusable identities once, persist the
+// returned refs to a project artifact, and resolve them at execution time into
+// the veo-useapi transport's `flow.ts --character` flags (Flow v1 character_1..7).
+//
+// Live-verified API quirks (the HTML docs are wrong on these):
+//   - POST /google-flow/characters REJECTS `email` in the body (account = token).
+//   - POST /google-flow/voices REQUIRES `email` in the body.
+//   - character_* routes through R2V, so realistic human faces are
+//     moderation-filtered (PUBLIC_ERROR_UNSAFE_GENERATION / INPUT_OTHER); this
+//     path is for stylized / mascot identities. Photoreal humans use Veo-I2V.
+
+interface FetchLikeResponse {
+  ok: boolean;
+  status: number;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}
+
+export type FetchLike = (input: string, init?: {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string | Uint8Array;
+}) => Promise<FetchLikeResponse>;
+
+const DEFAULT_BASE_URL = 'https://api.useapi.net/v1';
+
+export interface FlowLibraryClientOptions {
+  apiToken: string;
+  accountEmail: string;
+  baseUrl?: string;
+  /** Injectable fetch so tests run offline. Defaults to global fetch. */
+  fetchImpl?: FetchLike;
+  /** Injectable file reader (returns raw image bytes). Defaults to fs.readFile. */
+  readFileImpl?: (path: string) => Promise<Buffer>;
+}
+
+function mimeForPath(path: string): 'image/png' | 'image/jpeg' {
+  const ext = path.toLowerCase().split('.').pop();
+  if (ext === 'png') return 'image/png';
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg';
+  throw new Error(`Unsupported image format: .${ext}. Only PNG and JPEG are supported.`);
+}
+
+/**
+ * Thin client for the Google Flow v1 Characters/Voices + asset-upload endpoints.
+ * Pure transport — no fs/project knowledge beyond reading an image to upload.
+ */
+export class FlowLibraryClient {
+  private readonly apiToken: string;
+  private readonly accountEmail: string;
+  private readonly baseUrl: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly readFileImpl: (path: string) => Promise<Buffer>;
+
+  constructor(options: FlowLibraryClientOptions) {
+    const apiToken = options.apiToken?.trim();
+    if (!apiToken) throw new Error('Flow library requires an API token (USEAPI_API_TOKEN).');
+    if (!options.accountEmail?.trim()) throw new Error('Flow library requires an account email (USEAPI_ACCOUNT_EMAIL).');
+    this.apiToken = apiToken;
+    this.accountEmail = options.accountEmail.trim();
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.fetchImpl = options.fetchImpl ?? ((globalThis as { fetch?: FetchLike }).fetch as FetchLike);
+    this.readFileImpl = options.readFileImpl ?? (async (p) => Buffer.from(await readFile(p)));
+    if (typeof this.fetchImpl !== 'function') {
+      throw new Error('Flow library requires a fetch implementation (none injected and global fetch is unavailable).');
+    }
+  }
+
+  private authHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    return { Authorization: `Bearer ${this.apiToken}`, ...extra };
+  }
+
+  private async parse<T>(res: FetchLikeResponse, label: string): Promise<T> {
+    const text = await res.text();
+    let json: unknown = null;
+    try { json = JSON.parse(text); } catch { /* non-JSON body */ }
+    if (!res.ok) {
+      const err = (json as { error?: unknown })?.error;
+      const msg = typeof err === 'string' ? err : err ? JSON.stringify(err) : text.slice(0, 300);
+      throw new Error(`Flow ${label} failed (HTTP ${res.status}): ${msg}`);
+    }
+    return json as T;
+  }
+
+  /** Upload a local PNG/JPEG → returns its mediaGenerationId (for imageReference_*). */
+  async uploadImage(imagePath: string): Promise<string> {
+    let body: Buffer;
+    try {
+      body = await this.readFileImpl(imagePath); // injectable; real fs throws ENOENT for missing files
+    } catch (err) {
+      throw new Error(`Image file not found or unreadable: ${imagePath} (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const url = `${this.baseUrl}/google-flow/assets/${encodeURIComponent(this.accountEmail)}`;
+    const res = await this.fetchImpl(url, {
+      method: 'POST',
+      headers: this.authHeaders({ 'Content-Type': mimeForPath(imagePath) }),
+      body,
+    });
+    const json = await this.parse<{ mediaGenerationId?: string | { mediaGenerationId?: string } }>(res, 'asset upload');
+    const raw = json.mediaGenerationId;
+    const mediaId = typeof raw === 'object' ? raw?.mediaGenerationId : raw;
+    if (!mediaId) throw new Error(`Flow asset upload returned no mediaGenerationId for ${imagePath}.`);
+    return mediaId;
+  }
+
+  /**
+   * POST /google-flow/characters — NO email in body (account from token).
+   * Returns the saved character with its `character` ref string.
+   */
+  async createCharacter(params: {
+    displayName: string;
+    imageReference_1: string;
+    imageReference_2?: string;
+    voice?: string;
+    personalityNotes?: string;
+  }): Promise<{ entityId: string; character: string; voice?: string }> {
+    const url = `${this.baseUrl}/google-flow/characters`;
+    const res = await this.fetchImpl(url, {
+      method: 'POST',
+      headers: this.authHeaders({ 'Content-Type': 'application/json', Accept: 'application/json' }),
+      body: JSON.stringify(params),
+    });
+    return this.parse(res, 'create character');
+  }
+
+  /**
+   * POST /google-flow/voices — REQUIRES email in body. Returns the saved voice
+   * with its `voice` ref string (usable as referenceAudio or a character voice).
+   */
+  async createVoice(params: {
+    voice: string;
+    displayName: string;
+    dialog: string;
+    voicePerformance: string;
+  }): Promise<{ voice: string; baseVoice?: string; displayName?: string }> {
+    const url = `${this.baseUrl}/google-flow/voices`;
+    const res = await this.fetchImpl(url, {
+      method: 'POST',
+      headers: this.authHeaders({ 'Content-Type': 'application/json', Accept: 'application/json' }),
+      body: JSON.stringify({ email: this.accountEmail, ...params }),
+    });
+    return this.parse(res, 'create voice');
+  }
+}
+
+// ── Artifacts ───────────────────────────────────────────────────────────────
+
+/** One registered character in `flow-characters.json`. */
+export interface FlowCharacterEntry {
+  name: string;
+  entityId: string;
+  characterRef: string;   // value used as character_1..7
+  voice?: string;
+}
+
+export interface FlowCharactersArtifact {
+  schemaVersion: 1;
+  projectSlug: string;
+  generatedAt: string;
+  characters: FlowCharacterEntry[];
+}
+
+/** One registered custom voice in `flow-voices.json`. */
+export interface FlowVoiceEntry {
+  name: string;
+  voiceRef: string;       // value used as referenceAudio / character voice
+  baseVoice?: string;
+}
+
+export interface FlowVoicesArtifact {
+  schemaVersion: 1;
+  projectSlug: string;
+  generatedAt: string;
+  voices: FlowVoiceEntry[];
+}
+
+export interface FlowCharactersLookup {
+  characters: FlowCharacterEntry[];
+  characterRefByName: Map<string, string>;
+}
+
+/**
+ * Read `artifacts/flow-characters.json`. Returns an empty lookup when absent so
+ * the execution layer degrades gracefully (no `--character` flags) rather than
+ * failing. A present-but-malformed file is NOT swallowed (JSON.parse surfaces it).
+ */
+export async function readFlowCharacters(
+  workspaceRoot: string,
+  slug: string,
+): Promise<FlowCharactersLookup> {
+  const workspace = resolveProjectWorkspace(slug, workspaceRoot);
+  const path = join(workspace.artifactsDir, 'flow-characters.json');
+  if (!existsSync(path)) {
+    return { characters: [], characterRefByName: new Map() };
+  }
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as Partial<FlowCharactersArtifact>;
+  const characters: FlowCharacterEntry[] = Array.isArray(parsed.characters)
+    ? parsed.characters
+        .filter((c): c is FlowCharacterEntry => !!c && !!c.name && !!c.characterRef)
+        .map((c) => ({ name: c.name, entityId: c.entityId, characterRef: c.characterRef, voice: c.voice }))
+    : [];
+  const characterRefByName = new Map<string, string>();
+  for (const c of characters) characterRefByName.set(c.name, c.characterRef);
+  return { characters, characterRefByName };
+}
+
+/** Read `artifacts/flow-voices.json` → name -> voice ref (empty when absent). */
+export async function readFlowVoices(
+  workspaceRoot: string,
+  slug: string,
+): Promise<Map<string, string>> {
+  const workspace = resolveProjectWorkspace(slug, workspaceRoot);
+  const path = join(workspace.artifactsDir, 'flow-voices.json');
+  if (!existsSync(path)) return new Map();
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as Partial<FlowVoicesArtifact>;
+  const map = new Map<string, string>();
+  if (Array.isArray(parsed.voices)) {
+    for (const v of parsed.voices) {
+      if (v?.name && v?.voiceRef) map.set(v.name, v.voiceRef);
+    }
+  }
+  return map;
+}
+
+// ── Registration ──────────────────────────────────────────────────────────────
+
+export interface FlowCharacterInput {
+  /** Project-facing character name (matches a storyboard scene's `characters`). */
+  name: string;
+  /** 1-2 local image paths to upload, OR already-uploaded mediaGenerationIds. */
+  images: string[];
+  /** Optional voice: a system preset (e.g. "Charon") or a user voice ref. */
+  voice?: string;
+  /** Optional personality notes (≤2000 chars). */
+  personalityNotes?: string;
+  /** Optional display name override (defaults to `name`). */
+  displayName?: string;
+}
+
+/** True if a string is already an uploaded media ref rather than a local path. */
+function isMediaRef(s: string): boolean {
+  return s.startsWith('user:') || s.includes('-image:') || s.includes('mediaGenerationId');
+}
+
+/**
+ * Register characters with Google Flow and write `flow-characters.json`. Each
+ * input's images are uploaded (local paths) or used directly (existing refs),
+ * then bundled into a saved character. `generatedAt` is injected (callers stamp
+ * it) so this stays deterministic/testable.
+ */
+export async function registerFlowCharacters(opts: {
+  workspaceRoot: string;
+  slug: string;
+  characters: FlowCharacterInput[];
+  client: FlowLibraryClient;
+  generatedAt: string;
+}): Promise<FlowCharactersArtifact> {
+  const entries: FlowCharacterEntry[] = [];
+  for (const input of opts.characters) {
+    if (!input.images || input.images.length === 0) {
+      throw new Error(`Character "${input.name}" needs at least one image.`);
+    }
+    const mediaIds: string[] = [];
+    for (const img of input.images.slice(0, 2)) {
+      mediaIds.push(isMediaRef(img) ? img : await opts.client.uploadImage(img));
+    }
+    const created = await opts.client.createCharacter({
+      displayName: input.displayName ?? input.name,
+      imageReference_1: mediaIds[0],
+      imageReference_2: mediaIds[1],
+      voice: input.voice,
+      personalityNotes: input.personalityNotes,
+    });
+    entries.push({
+      name: input.name,
+      entityId: created.entityId,
+      characterRef: created.character,
+      voice: created.voice ?? input.voice,
+    });
+  }
+  const artifact: FlowCharactersArtifact = {
+    schemaVersion: 1,
+    projectSlug: opts.slug,
+    generatedAt: opts.generatedAt,
+    characters: entries,
+  };
+  const workspace = resolveProjectWorkspace(opts.slug, opts.workspaceRoot);
+  await mkdir(workspace.artifactsDir, { recursive: true });
+  await writeFile(
+    join(workspace.artifactsDir, 'flow-characters.json'),
+    `${JSON.stringify(artifact, null, 2)}\n`,
+    'utf-8',
+  );
+  return artifact;
+}
+
+export interface FlowVoiceInput {
+  name: string;
+  basePreset: string;       // a FLOW_VOICE_PRESETS value
+  dialog: string;
+  voicePerformance: string;
+}
+
+/** Register custom voices with Google Flow and write `flow-voices.json`. */
+export async function registerFlowVoices(opts: {
+  workspaceRoot: string;
+  slug: string;
+  voices: FlowVoiceInput[];
+  client: FlowLibraryClient;
+  generatedAt: string;
+}): Promise<FlowVoicesArtifact> {
+  const entries: FlowVoiceEntry[] = [];
+  for (const input of opts.voices) {
+    const created = await opts.client.createVoice({
+      voice: input.basePreset,
+      displayName: input.name,
+      dialog: input.dialog,
+      voicePerformance: input.voicePerformance,
+    });
+    entries.push({ name: input.name, voiceRef: created.voice, baseVoice: created.baseVoice ?? input.basePreset });
+  }
+  const artifact: FlowVoicesArtifact = {
+    schemaVersion: 1,
+    projectSlug: opts.slug,
+    generatedAt: opts.generatedAt,
+    voices: entries,
+  };
+  const workspace = resolveProjectWorkspace(opts.slug, opts.workspaceRoot);
+  await mkdir(workspace.artifactsDir, { recursive: true });
+  await writeFile(
+    join(workspace.artifactsDir, 'flow-voices.json'),
+    `${JSON.stringify(artifact, null, 2)}\n`,
+    'utf-8',
+  );
+  return artifact;
+}

package/src/video/flow-markers.ts

@@ -0,0 +1,330 @@
+/**
+ * Google Flow inline @-mention markers (useapi.net Google Flow API v1,
+ * blog 260609). Markers anchor a reference to a position in the prompt text:
+ *
+ *   POST /videos: @character_1..7, @referenceImage_1..7, @referenceAudio_1..5
+ *   POST /images: @character_1..7, @reference_1..10
+ *
+ * Case-INSENSITIVE and opt-in — a slot without a marker is always fine, but a
+ * marker without a matching body slot makes the API 400. There is NO
+ * `@referenceVideo_1` marker — V2V stays flag-only (`--ref-video`).
+ *
+ * Pure module: no I/O, no env, no provider calls.
+ */
+
+export type FlowMarkerFamily = 'character' | 'referenceImage' | 'referenceAudio' | 'reference';
+
+export interface FlowMarker {
+  family: FlowMarkerFamily;
+  /** 1-based slot index as written (out-of-range values are reported by the validators, not here). */
+  index: number;
+  /** The token exactly as matched in the prompt, e.g. '@Character_2'. */
+  raw: string;
+}
+
+// Ordering: keep the longer alternatives (referenceImage, referenceAudio)
+// before 'reference' so correctness does not depend on backtracking semantics
+// and the intent stays obvious. (JavaScript's backtracking engine would parse
+// '@referenceImage_1' correctly either way — after 'reference' fails on the
+// '_' it retries the longer alternative; only a non-backtracking engine like
+// RE2 would mis-parse.) The dedicated mis-parse test in
+// src/tests/flow-markers.test.ts pins the behavior.
+const FLOW_MARKER_RE = /@(referenceImage|referenceAudio|reference|character)_(\d+)\b/gi;
+
+const CANONICAL_FAMILY: Record<string, FlowMarkerFamily> = {
+  character: 'character',
+  referenceimage: 'referenceImage',
+  referenceaudio: 'referenceAudio',
+  reference: 'reference',
+};
+
+/** Per-family maximum slot index on POST /videos and POST /images. */
+const FAMILY_MAX: Record<FlowMarkerFamily, number> = {
+  character: 7,
+  referenceImage: 7,
+  referenceAudio: 5,
+  reference: 10,
+};
+
+/**
+ * Extract every Flow @-marker occurrence in order, duplicates included.
+ * Family is normalized to canonical camelCase regardless of input casing;
+ * `raw` keeps the token exactly as written.
+ */
+export function extractFlowMarkers(prompt: string): FlowMarker[] {
+  const markers: FlowMarker[] = [];
+  for (const match of prompt.matchAll(FLOW_MARKER_RE)) {
+    const family = CANONICAL_FAMILY[match[1].toLowerCase()];
+    markers.push({ family, index: Number.parseInt(match[2], 10), raw: match[0] });
+  }
+  return markers;
+}
+
+export interface FlowVideoMarkerSlots {
+  characterCount: number;
+  referenceImageCount: number;
+  referenceAudioCount: number;
+}
+
+export interface FlowImageMarkerSlots {
+  characterCount: number;
+  referenceCount: number;
+}
+
+/** Duplicate markers for one index are fine — report each distinct problem once. */
+function dedupe(errors: string[]): string[] {
+  return [...new Set(errors)];
+}
+
+function rangeError(marker: FlowMarker, family: FlowMarkerFamily): string {
+  return `${marker.raw}: index out of range — @${family}_N must satisfy 1 <= N <= ${FAMILY_MAX[family]}.`;
+}
+
+function slotError(marker: FlowMarker, family: FlowMarkerFamily, provided: number): string {
+  return `${marker.raw}: no matching ${family} slot — only ${provided} provided, so @${family}_${marker.index} would make the API 400.`;
+}
+
+/**
+ * Validate Flow @-markers in a VIDEO prompt (POST /videos grammar) against the
+ * body slots the caller intends to send. Returns human-readable error strings
+ * (empty = valid). Slots WITHOUT markers are never an error (markers are
+ * opt-in); duplicate markers for one index are fine.
+ */
+export function validateFlowVideoMarkers(prompt: string, slots: FlowVideoMarkerSlots): string[] {
+  const errors: string[] = [];
+  for (const marker of extractFlowMarkers(prompt)) {
+    switch (marker.family) {
+      case 'character':
+        if (marker.index < 1 || marker.index > FAMILY_MAX.character) {
+          errors.push(rangeError(marker, 'character'));
+        } else if (marker.index > slots.characterCount) {
+          errors.push(slotError(marker, 'character', slots.characterCount));
+        }
+        break;
+      case 'referenceImage':
+        if (marker.index < 1 || marker.index > FAMILY_MAX.referenceImage) {
+          errors.push(rangeError(marker, 'referenceImage'));
+        } else if (marker.index > slots.referenceImageCount) {
+          errors.push(slotError(marker, 'referenceImage', slots.referenceImageCount));
+        }
+        break;
+      case 'referenceAudio':
+        if (marker.index < 1 || marker.index > FAMILY_MAX.referenceAudio) {
+          errors.push(rangeError(marker, 'referenceAudio'));
+        } else if (marker.index > slots.referenceAudioCount) {
+          errors.push(slotError(marker, 'referenceAudio', slots.referenceAudioCount));
+        }
+        break;
+      case 'reference':
+        errors.push(
+          `${marker.raw}: @reference_N is an image-endpoint (POST /images) marker — in a video prompt use @referenceImage_${marker.index}.`,
+        );
+        break;
+    }
+  }
+  return dedupe(errors);
+}
+
+/**
+ * Validate Flow @-markers in an IMAGE prompt (POST /images grammar) against the
+ * body slots the caller intends to send. Same contract as the video validator.
+ * (The model x ref-count matrix intentionally lives with the callers, not here.)
+ */
+export function validateFlowImageMarkers(prompt: string, slots: FlowImageMarkerSlots): string[] {
+  const errors: string[] = [];
+  for (const marker of extractFlowMarkers(prompt)) {
+    switch (marker.family) {
+      case 'character':
+        if (marker.index < 1 || marker.index > FAMILY_MAX.character) {
+          errors.push(rangeError(marker, 'character'));
+        } else if (marker.index > slots.characterCount) {
+          errors.push(slotError(marker, 'character', slots.characterCount));
+        }
+        break;
+      case 'reference':
+        if (marker.index < 1 || marker.index > FAMILY_MAX.reference) {
+          errors.push(rangeError(marker, 'reference'));
+        } else if (marker.index > slots.referenceCount) {
+          errors.push(slotError(marker, 'reference', slots.referenceCount));
+        }
+        break;
+      case 'referenceImage':
+        errors.push(
+          `${marker.raw}: @referenceImage_N is a video-only marker — in an image prompt use @reference_${marker.index}.`,
+        );
+        break;
+      case 'referenceAudio':
+        errors.push(
+          `${marker.raw}: @referenceAudio_N is a video-only marker — image prompts have no audio reference slots.`,
+        );
+        break;
+    }
+  }
+  return dedupe(errors);
+}
+
+// ── Auto-injection: @Name tags → @character_N markers (veo-useapi) ───────────
+
+/**
+ * Same @-tag token pattern resolveAssetTags scans (prompt-rules.ts
+ * ASSET_TAG_RE): starts with a letter, then letters/digits/underscore/hyphen.
+ * Duplicated here (not imported) so this module stays dependency-free.
+ */
+const NAME_TAG_RE = /@([A-Za-z][\w-]*)/g;
+
+/**
+ * Tag names that are NOT character names: the Flow marker grammar itself
+ * (hand-authored `@character_2` etc. must pass through untouched) and the
+ * seedance `@imageN` positional-binding contract.
+ */
+const RESERVED_TAG_NAME_RE = /^(?:(?:character|referenceimage|referenceaudio|reference)_\d+|image\d+)$/i;
+
+/** POST /videos accepts at most 7 character body slots (`character_1..7`). */
+const FLOW_CHARACTER_SLOT_MAX = 7;
+
+export interface FlowCharacterSlotPlan {
+  /** Lowercased character name → 1-based slot index into `orderedRefs`. */
+  slotByLowerName: Map<string, number>;
+  /** The final characterRefs array — slot N is `orderedRefs[N-1]`. */
+  orderedRefs: string[];
+  /** Names (original casing, first occurrence) aligned with `orderedRefs`. */
+  orderedNames: string[];
+  /** Registered names beyond the 7-slot cap, in the order they were dropped. */
+  overflow: string[];
+}
+
+/**
+ * Plan the `character_1..7` body slots for one scene. The final array is the
+ * ordered union of:
+ *   1. `unique(sceneCharacters)` filtered/mapped via
+ *      `characterRefByName.get(name)` — EXACT-case lookup, verbatim the legacy
+ *      cast semantics, so a tagless prompt yields exactly today's
+ *      characterRefs list (byte-identical payload). A cast name that only
+ *      case-mismatches the registry ('clawbot' vs registered 'Clawbot') stays
+ *      unresolved, exactly as before this feature.
+ *   2. registered names appearing as `@Name` tags in `rawPrompt` (tag scan
+ *      order) that are not already included. TAG matching is case-INSENSITIVE
+ *      — tags are single tokens and `@clawbot` must resolve to a registered
+ *      'Clawbot' (the plan-mandated case-insensitivity applies to tags only).
+ * Capped at 7; registered names beyond the cap land in `overflow`.
+ * `orderedNames` keeps the casing of the first occurrence. Unregistered names
+ * are never slot candidates — they keep the descriptor-substitution path in
+ * resolveAssetTags.
+ *
+ * `slotByLowerName` is keyed by the lowercased FINAL ordered names: if two
+ * case-only-distinct cast names both carry refs (e.g. 'Bob' and 'BOB' both
+ * registered), both keep their slots in `orderedRefs`, but the lowercased
+ * injection key first-wins — a prompt tag cannot disambiguate
+ * case-only-distinct names (pathological; exact-case cast behavior is
+ * preserved either way).
+ */
+export function planFlowCharacterSlots(
+  rawPrompt: string,
+  sceneCharacters: string[],
+  characterRefByName: Map<string, string>,
+): FlowCharacterSlotPlan {
+  const slotByLowerName = new Map<string, number>();
+  const orderedRefs: string[] = [];
+  const orderedNames: string[] = [];
+  const overflow: string[] = [];
+  // Lowercased names that already went through slot planning (slotted OR
+  // overflowed) — consulted only by the TAG phase, so a tag never re-adds a
+  // character the cast already placed (regardless of casing).
+  const plannedLower = new Set<string>();
+
+  const addPlanned = (name: string, ref: string): void => {
+    plannedLower.add(name.toLowerCase());
+    if (orderedRefs.length >= FLOW_CHARACTER_SLOT_MAX) {
+      overflow.push(name);
+      return;
+    }
+    orderedRefs.push(ref);
+    orderedNames.push(name);
+    const lower = name.toLowerCase();
+    if (!slotByLowerName.has(lower)) slotByLowerName.set(lower, orderedRefs.length);
+  };
+
+  // CAST phase — EXACT matching, the legacy semantics verbatim:
+  // unique(sceneCharacters) filtered/mapped via characterRefByName.get(name).
+  // No trim, no case folding.
+  const seenCast = new Set<string>();
+  for (const name of sceneCharacters) {
+    if (seenCast.has(name)) continue;
+    seenCast.add(name);
+    const ref = characterRefByName.get(name);
+    if (ref === undefined) continue; // unregistered (exact) → not a slot candidate
+    addPlanned(name, ref);
+  }
+
+  // TAG phase — case-insensitive registry lookup for @Name tokens.
+  const refByLowerName = new Map<string, string>();
+  for (const [name, ref] of characterRefByName) {
+    const lower = name.trim().toLowerCase();
+    if (lower && !refByLowerName.has(lower)) refByLowerName.set(lower, ref);
+  }
+  for (const match of rawPrompt.matchAll(NAME_TAG_RE)) {
+    if (RESERVED_TAG_NAME_RE.test(match[1])) continue;
+    const tagName = match[1];
+    const lower = tagName.toLowerCase();
+    if (plannedLower.has(lower)) continue;
+    const ref = refByLowerName.get(lower);
+    if (ref === undefined) continue; // unregistered → not a slot candidate
+    addPlanned(tagName, ref);
+  }
+
+  return { slotByLowerName, orderedRefs, orderedNames, overflow };
+}
+
+/**
+ * Replace each `@Name` tag whose lowercased name is in `slotByLowerName` with
+ * the canonical lowercase `@character_N` marker. Duplicate mentions of one name
+ * all resolve to the SAME marker (one slot — the API dedup rule). Every other
+ * tag — unregistered names, `@imageN`, hand-authored Flow markers like
+ * `@character_2` — is untouched. `injected` lists `Name->@character_N` strings
+ * in order of first replacement. Tagless text comes back byte-identical.
+ */
+export function injectFlowCharacterMarkers(
+  text: string,
+  slotByLowerName: Map<string, number>,
+): { text: string; injected: string[] } {
+  const injected: string[] = [];
+  if (slotByLowerName.size === 0) {
+    return { text, injected };
+  }
+  const seenFirst = new Set<string>();
+  const out = text.replace(NAME_TAG_RE, (match, name: string) => {
+    if (RESERVED_TAG_NAME_RE.test(name)) {
+      return match; // hand-authored marker / @imageN — preserve verbatim
+    }
+    const lower = name.toLowerCase();
+    const slot = slotByLowerName.get(lower);
+    if (slot === undefined) {
+      return match; // not a planned character — resolveAssetTags handles it
+    }
+    if (!seenFirst.has(lower)) {
+      seenFirst.add(lower);
+      injected.push(`${name}->@character_${slot}`);
+    }
+    return `@character_${slot}`;
+  });
+  return { text: out, injected };
+}
+
+/**
+ * Remove every Flow @-marker token from `text`, collapsing the doubled
+ * whitespace left behind and trimming the ends. `stripped` lists the removed
+ * raw tokens in order. Text without markers comes back byte-identical.
+ */
+export function stripFlowMarkers(text: string): { text: string; stripped: string[] } {
+  const stripped: string[] = [];
+  if (extractFlowMarkers(text).length === 0) {
+    return { text, stripped }; // byte-identical when there is nothing to strip
+  }
+  const removed = text.replace(FLOW_MARKER_RE, (match) => {
+    stripped.push(match);
+    return '';
+  });
+  // Collapse doubled horizontal whitespace left by removal (newlines kept).
+  const collapsed = removed.replace(/[ \t]{2,}/g, ' ').replace(/[ \t]+(\n)/g, '$1').trim();
+  return { text: collapsed, stripped };
+}