videoclaw 3.0.0-alpha.1

package/dist/video/flow-character-library.js

@@ -0,0 +1,211 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveProjectWorkspace } from './workspace.js';
+const DEFAULT_BASE_URL = 'https://api.useapi.net/v1';
+function mimeForPath(path) {
+    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 {
+    apiToken;
+    accountEmail;
+    baseUrl;
+    fetchImpl;
+    readFileImpl;
+    constructor(options) {
+        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.fetch;
+        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).');
+        }
+    }
+    authHeaders(extra = {}) {
+        return { Authorization: `Bearer ${this.apiToken}`, ...extra };
+    }
+    async parse(res, label) {
+        const text = await res.text();
+        let json = null;
+        try {
+            json = JSON.parse(text);
+        }
+        catch { /* non-JSON body */ }
+        if (!res.ok) {
+            const err = json?.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;
+    }
+    /** Upload a local PNG/JPEG → returns its mediaGenerationId (for imageReference_*). */
+    async uploadImage(imagePath) {
+        let body;
+        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(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) {
+        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) {
+        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');
+    }
+}
+/**
+ * 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, slug) {
+    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'));
+    const characters = Array.isArray(parsed.characters)
+        ? parsed.characters
+            .filter((c) => !!c && !!c.name && !!c.characterRef)
+            .map((c) => ({ name: c.name, entityId: c.entityId, characterRef: c.characterRef, voice: c.voice }))
+        : [];
+    const characterRefByName = new Map();
+    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, slug) {
+    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'));
+    const map = new Map();
+    if (Array.isArray(parsed.voices)) {
+        for (const v of parsed.voices) {
+            if (v?.name && v?.voiceRef)
+                map.set(v.name, v.voiceRef);
+        }
+    }
+    return map;
+}
+/** True if a string is already an uploaded media ref rather than a local path. */
+function isMediaRef(s) {
+    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) {
+    const entries = [];
+    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 = [];
+        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 = {
+        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;
+}
+/** Register custom voices with Google Flow and write `flow-voices.json`. */
+export async function registerFlowVoices(opts) {
+    const entries = [];
+    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 = {
+        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;
+}
+//# sourceMappingURL=flow-character-library.js.map

package/dist/video/flow-character-library.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-character-library.js","sourceRoot":"","sources":["../../src/video/flow-character-library.ts"],"names":[],"mappings":"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"}

package/dist/video/flow-markers.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function extractFlowMarkers(prompt: string): FlowMarker[];
+export interface FlowVideoMarkerSlots {
+    characterCount: number;
+    referenceImageCount: number;
+    referenceAudioCount: number;
+}
+export interface FlowImageMarkerSlots {
+    characterCount: number;
+    referenceCount: number;
+}
+/**
+ * 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 declare function validateFlowVideoMarkers(prompt: string, slots: FlowVideoMarkerSlots): string[];
+/**
+ * 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 declare function validateFlowImageMarkers(prompt: string, slots: FlowImageMarkerSlots): string[];
+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 declare function planFlowCharacterSlots(rawPrompt: string, sceneCharacters: string[], characterRefByName: Map<string, string>): FlowCharacterSlotPlan;
+/**
+ * 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 declare function injectFlowCharacterMarkers(text: string, slotByLowerName: Map<string, number>): {
+    text: string;
+    injected: string[];
+};
+/**
+ * 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 declare function stripFlowMarkers(text: string): {
+    text: string;
+    stripped: string[];
+};
+//# sourceMappingURL=flow-markers.d.ts.map

package/dist/video/flow-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-markers.d.ts","sourceRoot":"","sources":["../../src/video/flow-markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAE/F,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,oGAAoG;IACpG,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;CACb;AA0BD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAO/D;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAeD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAiC9F;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,MAAM,EAAE,CA+B9F;AAqBD,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oEAAoE;IACpE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EAAE,EACzB,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC,qBAAqB,CAmDvB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAsBtC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAYnF"}

package/dist/video/flow-markers.js

@@ -0,0 +1,278 @@
+/**
+ * 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.
+ */
+// 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 = {
+    character: 'character',
+    referenceimage: 'referenceImage',
+    referenceaudio: 'referenceAudio',
+    reference: 'reference',
+};
+/** Per-family maximum slot index on POST /videos and POST /images. */
+const FAMILY_MAX = {
+    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) {
+    const markers = [];
+    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;
+}
+/** Duplicate markers for one index are fine — report each distinct problem once. */
+function dedupe(errors) {
+    return [...new Set(errors)];
+}
+function rangeError(marker, family) {
+    return `${marker.raw}: index out of range — @${family}_N must satisfy 1 <= N <= ${FAMILY_MAX[family]}.`;
+}
+function slotError(marker, family, provided) {
+    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, slots) {
+    const errors = [];
+    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, slots) {
+    const errors = [];
+    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;
+/**
+ * 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, sceneCharacters, characterRefByName) {
+    const slotByLowerName = new Map();
+    const orderedRefs = [];
+    const orderedNames = [];
+    const overflow = [];
+    // 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();
+    const addPlanned = (name, ref) => {
+        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();
+    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();
+    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, slotByLowerName) {
+    const injected = [];
+    if (slotByLowerName.size === 0) {
+        return { text, injected };
+    }
+    const seenFirst = new Set();
+    const out = text.replace(NAME_TAG_RE, (match, name) => {
+        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) {
+    const stripped = [];
+    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 };
+}
+//# sourceMappingURL=flow-markers.js.map

package/dist/video/flow-markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-markers.js","sourceRoot":"","sources":["../../src/video/flow-markers.ts"],"names":[],"mappings":"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"}