From 148cba0c737e1bdf6810930e3cf2cf7280c3955e Mon Sep 17 00:00:00 2001 From: Navneet Chaudhary Date: Sat, 7 Nov 2026 01:32:11 +0530 Subject: [PATCH 1/2] feat: guard local drawn eye and mouth variants --- README.md | 2 + docs/CHARACTER_IMPORT.md | 22 ++++ docs/IMPLEMENTATION_PLAN.md | 3 +- docs/QUALITY_AUDIT.md | 2 +- src/character/avatar.ts | 7 +- src/character/drawn-variants.ts | 173 ++++++++++++++++++++++++++++++++ src/cli/index.ts | 26 ++++- tests/drawn-variants.test.ts | 103 +++++++++++++++++++ 8 files changed, 333 insertions(+), 5 deletions(-) create mode 100644 src/character/drawn-variants.ts create mode 100644 tests/drawn-variants.test.ts diff --git a/README.md b/README.md index 5ec9f50..9044b4b 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ The long-term goal: **generate artwork when necessary, animate and reuse it inde - Assisted single-PNG character onboarding through Rev2D landmarks, local rig build, review sheets, unapproved-by-default manifest, and starter scene. - Agent-guided landmark proposals: source-hash-bound task, optional **tested** Codex image-based suggestion, isolated geometry validation, visual overlay and explicit review/acceptance that revokes old rig approval. - Imported avatar asset provenance: source/spec/model/texture fingerprints checked by scene validation and render; untracked alternate imported pose models are refused. Force rebuild revokes approval before modifying art. Suspicious landmarks generate nonblocking geometry warnings. +- Guarded **local drawn eye/mouth variant** request, status and import commands using Rev2D masks and sprites. Imported drawings revoke approval and require a fresh visual review; no image generation happens automatically. - Agent-readable CLI output, tests and CI. **Not implemented yet:** fully automatic landmark placement or reliable one-click rigging, AI-generated arbitrary new pose rigs, convincing smooth bridges between unrelated meshes (especially crossed arms), automatic transcription/TTS, captions, B-roll and multiple actors. The arm-raise gesture is genuinely animated, but its artwork is still prototype-quality. Other pose families may require edited hard cuts. The pose manifest is capability metadata; visual poses become usable only after their rig files are generated, validated and inspected. @@ -42,6 +43,7 @@ npm run demo:directed # Apply edited camera framing and gradual punch-in npm run demo:gesture # Generate two-joint gesture rig and export edited 1080p demo npm run demo:gesture-cycle # Render continuous raise/lower cycles without cuts npm run demo:avatar # Import a freshly rendered flat PNG and create an unapproved rig + review sheets +# For a built imported avatar, see docs/CHARACTER_IMPORT.md for drawn-variant request/import ~~~ The sample uses Rev2D's own **Hana** rig from the pinned MIT-licensed upstream checkout; generated character rig JSON is not checked into this repository. The derived example video is separately attributed and licensed under the original Rev2D terms. diff --git a/docs/CHARACTER_IMPORT.md b/docs/CHARACTER_IMPORT.md index c2ca564..17412be 100644 --- a/docs/CHARACTER_IMPORT.md +++ b/docs/CHARACTER_IMPORT.md @@ -77,6 +77,28 @@ node dist/cli/index.js scene render avatars/portrait/preview-scene.json --out ou Scene validation also checks avatar-build.json against source.png, avatar.json, the built model and all generated textures. Changing any of them requires a new build and renewed review; stale files fail with AVATAR_ASSETS_STALE. Before approval, the scene intentionally fails with DEFAULT_POSE_NOT_APPROVED. The built model begins with one body pose family (neutral), not automatic pointing or crossed-arms artwork. Its provenance record covers that primary rig only: adding a different pose model to this imported actor is rejected until separate pose-model fingerprints are supported. Manually authored multi-pose characters remain available through the existing explicit rig workflow. +## Improve eyes and mouth with drawn variants (experimental) + +If the automatically deformed eyelids or mouth look smeared, use **Rev2D's existing drawn sprites**. This does not automatically create beautiful art: someone must supply a carefully edited copy of the original PNG. The renderer falls back to mesh deformation for shapes without an accepted drawing. + +~~~sh +node dist/cli/index.js character variants request avatars/portrait eyes_closed eyes_half mouth_a +node dist/cli/index.js character variants status avatars/portrait +~~~ + +The request produces `variant-requests/.mask.png` and `variant-requests/.prompt.txt` beside the original `source.png`. The mask's opaque black pixels must remain identical; only its editable, transparent area should be redrawn. Save each **full-size** corrected illustration as `variants/.png` (for example `variants/eyes_closed.png`). A person or an image generator with **explicit artwork/privacy permission** may produce these PNGs; **PuppetControl's variant commands make no external image requests**. + +After examining each candidate at full resolution, import only those exact IDs: + +~~~sh +node dist/cli/index.js character variants import avatars/portrait eyes_closed eyes_half mouth_a --reviewed-art +node dist/cli/index.js character variants status avatars/portrait +~~~ + +Import checks the drawing size, then delegates to Rev2D's mask, global shift/zoom and seam checks. It revokes every existing pose approval **before** touching model or texture assets; on success it re-renders `review/eyes.png`, `review/mouth.png` and `review/poses.png` and refreshes asset fingerprints. **It never auto-approves.** Inspect the output for face jumps, halos, duplicate lines and inconsistent colors, then explicitly reapprove in `character.json` if acceptable. + +An upstream import can partially accept images before rejecting another. On error, the character remains unapproved and the old provenance may intentionally be stale; rebuild with `character build avatars/portrait --force` if necessary, inspect again, and only then retry. Do not assume that a successful import means the new drawings look good. Automatic image generation, reliable facial polish and smooth unrelated-pose bridges remain separate goals. + ## Reproducible built-in demonstration ~~~sh diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index 22fd6c1..db36dca 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -77,7 +77,8 @@ - [x] Revoke existing approval before any --force build mutates Rev2D outputs, and fail closed on stale source/spec/model/texture fingerprints. - [x] Eliminate reproduced black edge artifacts caused by alpha-zero warped pixels in H.264: composite frames onto scene background, with a 60-frame before/after comparison. - [ ] Add pixel-level motion QA probes and a reviewable report; automated geometry warnings are not proof of visual quality. -- [ ] Wrap Rev2D's existing drawn closed-eye/mouth variants to reduce visible deformation artifacts without writing another mesh engine. +- [x] Wrap local Rev2D drawn eye/mouth variant request/status/import with explicit reviewed-art selection, approval revocation before import, post-import provenance refresh, and new review sheets. A real Hana avatar produced correct edit masks; unchanged fake drawings were rejected. +- [ ] Produce and visually approve high-quality closed/half eye and mouth artwork; demonstrate seamless real rendered transitions. A local, disposable hand-drawn closed/half eye trial now passes mask checks, but inspection still shows flat eyelids and doubled contours during fades; the rig stays unapproved. ## Acceptance benchmark diff --git a/docs/QUALITY_AUDIT.md b/docs/QUALITY_AUDIT.md index ef4fa9b..14d1081 100644 --- a/docs/QUALITY_AUDIT.md +++ b/docs/QUALITY_AUDIT.md @@ -73,7 +73,7 @@ Rev2D creates eye-white, iris, upper/lower lid, lash, crease and foreground-hair ## 6. Next milestones -1. Wrap Rev2D drawn-variant requests and imports as guarded PuppetControl CLI operations. Require explicit user/artwork permission and renewed review. No new mesh engine. +1. **Guarded local drawn-variant CLI added:** request/status/import supported by pinned Rev2D. Request masks for eyes_closed, eyes_half and mouth_a on a fresh 512×640 Hana import were generated and visually inspected. Importing an unchanged eyes_closed image correctly failed upstream with code `unchanged` and did not approve the character. A separate *throwaway* Hana project then accepted locally hand-procedurally-redrawn eyes_closed and eyes_half artwork (both with outsideDiff=0 and nearDiff=0); approval remained false. Actual eyes review frames showed the closed-eye lashes more continuous than the original mesh deformation, but a faint lower contour, too-flat half-open eyelids and double contours during fades remained. **These test drawings are not acceptable character art**, are only in ignored local .cache, and are not redistributed. No AI provider was used and no arbitrary-character quality claim follows. 2. Add image-based QA probes for rest-pose identity, blink/gaze/mouth activity, and head/neck discontinuities. Quantitative reports are triage, not automatic visual approval. 3. Build a diverse rights-cleared benchmark matrix: eye size, hair over face, accessories/glasses, different skin tones and line styles, opaque versus transparent backgrounds and constrained 3/4 views. Track success/failure on each, not just demos. 4. Only after a reliable single actor: improve body-pose transitions, synchronized multi-actor shots and user-facing authoring polish. diff --git a/src/character/avatar.ts b/src/character/avatar.ts index 2e46f1b..3674a85 100644 --- a/src/character/avatar.ts +++ b/src/character/avatar.ts @@ -148,7 +148,12 @@ export async function runRev2D(repo: string, args: string[], timeout = 120_000): // Return the upstream validator's precise diagnostics rather than hiding them. let output: CommandOutput = {}; try { output = JSON.parse(failure.stdout ?? "{}") as CommandOutput; } catch { /* not JSON */ } - const diagnosticText = output.diagnostics ? JSON.stringify(output.diagnostics).slice(0, 3500) : ""; + const rejected = Array.isArray(output.checks) ? output.checks + .filter((value) => !!value && typeof value === "object" && (value as { ok?: boolean }).ok === false) + .map((value) => ({ id: value.id, code: value.code, reason: value.reason, hint: value.hint })) : []; + const diagnosticText = Array.isArray(output.diagnostics) && output.diagnostics.length + ? JSON.stringify(output.diagnostics).slice(0, 3500) + : rejected.length ? JSON.stringify(rejected).slice(0, 3500) : ""; throw new AvatarWorkflowError( "REV2D_AVATAR_FAILED", [diagnosticText, failure.stderr, failure.message].filter(Boolean).join("\n").slice(0, 5000), diff --git a/src/character/drawn-variants.ts b/src/character/drawn-variants.ts new file mode 100644 index 0000000..6fce4a3 --- /dev/null +++ b/src/character/drawn-variants.ts @@ -0,0 +1,173 @@ +/** + * Guarded local artwork variant workflow for imported Rev2D avatars. + * + * The generated image itself is never sent to an AI provider by these calls. + * A successful import mutates the model/textures, invalidates previous visual + * approval, rebuilds review sheets, then refreshes exact asset fingerprints. + */ +import { open, readFile, stat } from "node:fs/promises"; +import { join } from "node:path"; +import { characterSchema } from "../scene/schemas.js"; +import { + AvatarWorkflowError, checkedPath, parsePngSize, pinnedRev2D, runRev2D, +} from "./avatar.js"; +import { + createAvatarBuildRecord, revokeAvatarApprovalBeforeBuild, + verifyAvatarBuildRecord, writeAvatarBuildRecord, +} from "./provenance.js"; + +export const DRAWN_VARIANT_IDS = [ + "eyes_closed", "eyes_half", "eyes_smile", + "mouth_a", "mouth_a_half", "mouth_i", "mouth_u", "mouth_e", "mouth_o", +] as const; + +const ALLOWED_VARIANTS = new Set(DRAWN_VARIANT_IDS); +const DEFAULT_VARIANTS = ["eyes_closed", "mouth_a"]; +const MAX_DRAWING_BYTES = 30 * 1024 * 1024; + +export function validateDrawnVariantIds( + requested: readonly string[], requireExplicit = false, +): string[] { + if (requireExplicit && requested.length === 0) { + throw new AvatarWorkflowError( + "VARIANT_IDS_REQUIRED", + "Select the exact reviewed artwork IDs to import; bulk importing all drawings is not allowed.", + ); + } + if (requested.length > DRAWN_VARIANT_IDS.length) { + throw new AvatarWorkflowError("VARIANT_IDS_INVALID", "Too many drawn variant IDs."); + } + const ids = requested.length ? requested : DEFAULT_VARIANTS; + if (ids.some((id) => !ALLOWED_VARIANTS.has(id)) || new Set(ids).size !== ids.length) { + throw new AvatarWorkflowError( + "VARIANT_IDS_INVALID", + "Unknown or duplicate variant ID. Supported: " + DRAWN_VARIANT_IDS.join(", "), + ); + } + return [...ids]; +} + +async function projectPaths(projectDir: string, root: string) { + const project = await checkedPath(root, projectDir); + if (!(await stat(project)).isDirectory()) { + throw new AvatarWorkflowError("AVATAR_PROJECT_REQUIRED", "Expected a built avatar project directory."); + } + return { + project, + manifestPath: await checkedPath(root, join(project, "character.json")), + }; +} + +async function verifiedImportedAvatar(projectDir: string, root: string) { + const paths = await projectPaths(projectDir, root); + const raw = await readFile(paths.manifestPath, "utf8"); + const manifest = characterSchema.parse(JSON.parse(raw) as unknown); + if (!manifest.provenance || !manifest.render?.modelPath || + manifest.poseFamilies.length !== 1 || + manifest.poseFamilies[0]?.modelPath !== manifest.render.modelPath) { + throw new AvatarWorkflowError( + "AVATAR_VARIANTS_UNSUPPORTED", + "Drawn variant import currently requires a single-pose character built with puppetctl character build.", + ); + } + const integrity = await verifyAvatarBuildRecord(paths.manifestPath, manifest.render.modelPath); + if (!integrity.valid) { + throw new AvatarWorkflowError(integrity.code, + "Avatar source/rig assets are stale: " + integrity.message + + ". Restore the verified build before modifying drawn variants."); + } + return { ...paths, manifest }; +} + +async function readDrawingSize(path: string): Promise<{ width: number; height: number }> { + const stats = await stat(path); + if (!stats.isFile() || stats.size < 24 || stats.size > MAX_DRAWING_BYTES) { + throw new AvatarWorkflowError("VARIANT_DRAWING_INVALID", "Drawing must be a PNG file under 30 MB."); + } + const handle = await open(path, "r"); + try { + const buffer = Buffer.alloc(24); + if ((await handle.read(buffer, 0, buffer.length, 0)).bytesRead !== buffer.length) { + throw new AvatarWorkflowError("VARIANT_DRAWING_INVALID", "Incomplete PNG header."); + } + return parsePngSize(buffer); + } finally { + await handle.close(); + } +} + +/** Prepare masks and prompts only; no generated texture or approval changes. */ +export async function requestDrawnVariants( + projectDir: string, requested: readonly string[] = [], root = process.cwd(), +) { + const ids = validateDrawnVariantIds(requested); + const { project } = await verifiedImportedAvatar(projectDir, root); + const backend = await pinnedRev2D(root); + const output: Record = await runRev2D(backend, ["avatar", "variants", "request", project, ...ids]); + return { + valid: true, status: "artwork-required", projectDir: project, variants: ids, + masks: ids.map((id) => join(project, "variant-requests", id + ".mask.png")), + prompts: ids.map((id) => join(project, "variant-requests", id + ".prompt.txt")), + backend: output, + next: "Draw full-size copies of source.png, editing ONLY the mask's transparent region. Save to variants/.png. Check image rights; these commands never upload artwork.", + }; +} + +/** Report backend state, including rejected/stale variants, even during recovery. */ +export async function statusDrawnVariants(projectDir: string, root = process.cwd()): Promise> { + const { project } = await projectPaths(projectDir, root); + const backend = await pinnedRev2D(root); + return runRev2D(backend, ["avatar", "variants", "status", project]); +} + +/** + * Import only explicitly selected, locally reviewed drawings. Never approve a + * rig here. If Rev2D partially mutates assets and then rejects art, the old + * build record intentionally stays stale, preventing unreviewed rendering. + */ +export async function importDrawnVariants( + projectDir: string, requested: readonly string[], root = process.cwd(), +) { + const ids = validateDrawnVariantIds(requested, true); + const { project, manifestPath, manifest } = await verifiedImportedAvatar(projectDir, root); + const source = await checkedPath(root, join(project, "source.png")); + const size = await readDrawingSize(source); + for (const id of ids) { + const drawing = await checkedPath(root, join(project, "variants", id + ".png")); + const drawnSize = await readDrawingSize(drawing); + if (size.width !== drawnSize.width || size.height !== drawnSize.height) { + throw new AvatarWorkflowError( + "VARIANT_SIZE_MISMATCH", + id + " must have exactly the source illustration's dimensions.", + ); + } + } + + const backend = await pinnedRev2D(root); + // IMPORTANT: revoke before Rev2D can touch model, layers or texture files. + await revokeAvatarApprovalBeforeBuild(manifestPath); + let imported: unknown; + try { + imported = await runRev2D(backend, ["avatar", "variants", "import", project, ...ids], 240_000); + await runRev2D(backend, ["avatar", "poses", project], 240_000); + const record = await createAvatarBuildRecord(project, manifest.render!.modelPath); + await writeAvatarBuildRecord(project, record); + } catch (error) { + throw new AvatarWorkflowError( + "VARIANT_IMPORT_REVIEW_REQUIRED", + (error instanceof Error ? error.message : String(error)) + + "\nThe avatar remains unapproved. Rev2D may have partially imported artwork; " + + "if fingerprints are now stale, rebuild with character build --force before retrying.", + ); + } + return { + valid: true, status: "review-required", approved: false, projectDir: project, + variants: ids, backend: imported, + review: { + eyes: join(project, "review", "eyes.png"), + mouth: join(project, "review", "mouth.png"), + poses: join(project, "review", "poses.png"), + }, + next: "Inspect the newly rendered review sheets for seams, color changes and facial jumps. Reapprove character.json explicitly only after visual QA.", + }; +} diff --git a/src/cli/index.ts b/src/cli/index.ts index 0f127df..8126ad2 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -14,6 +14,7 @@ import { AvatarWorkflowError, importAvatar, buildAvatar } from "../character/ava import { prepareLandmarkTask, stageLandmarks, acceptLandmarks } from "../character/landmarks.js"; import { proposeCodexLandmarks, codexExecutableForPlatform } from "../character/vision-codex.js"; import { verifyAvatarBuildRecord } from "../character/provenance.js"; +import { requestDrawnVariants, statusDrawnVariants, importDrawnVariants } from "../character/drawn-variants.js"; function print(value: unknown): void { process.stdout.write(JSON.stringify(value, null, 2) + "\n"); @@ -27,6 +28,9 @@ function usage(): never { " puppetctl character inspect \n" + " puppetctl character import --out --id \n" + " puppetctl character build [--force]\n" + + " puppetctl character variants request [variant-id ...]\n" + + " puppetctl character variants status \n" + + " puppetctl character variants import --reviewed-art\n" + " puppetctl character landmarks assist \n" + " puppetctl character landmarks propose --provider codex\n" + " puppetctl character landmarks stage --proposal \n" + @@ -47,7 +51,7 @@ async function run(): Promise { if (first === "--help" || first === "help") { process.stdout.write( "PuppetControl (experimental)\n" + - "Available: doctor, character inspect/import/build, landmark assist/propose/stage/accept, audio align, scene validate/plan, single-rig scene preview/render.\n" + + "Available: doctor, character inspect/import/build, drawn-variant request/status/import, landmark assist/propose/stage/accept, audio align, scene validate/plan, single-rig scene preview/render.\n" + "Not yet available: reliable one-click landmark inference, animated pose bridges, captions, automatic transcription/TTS.\n", ); return; @@ -72,7 +76,7 @@ async function run(): Promise { ffmpegAvailable: ffmpegFound, rev2dAvailable, codexCliAvailable, - availableFeatures: ["character-inspect", "scene-validate", "transition-policy", "rhubarb-cue-parsing", "rhubarb-align-if-installed", ...(rev2dAvailable ? ["assisted-png-avatar-import", "agent-landmark-proposal-staging", ...(codexCliAvailable ? ["optional-codex-vision-proposals"] : []), "avatar-review-sheets", "single-rig-preview", "single-rig-voice-render", "pose-family-hard-cut-render", "experimental-shot-framing"] : [])], + availableFeatures: ["character-inspect", "scene-validate", "transition-policy", "rhubarb-cue-parsing", "rhubarb-align-if-installed", ...(rev2dAvailable ? ["assisted-png-avatar-import", "local-drawn-variants", "agent-landmark-proposal-staging", ...(codexCliAvailable ? ["optional-codex-vision-proposals"] : []), "avatar-review-sheets", "single-rig-preview", "single-rig-voice-render", "pose-family-hard-cut-render", "experimental-shot-framing"] : [])], unavailableFeatures: ["animated-pose-bridges", "automatic-landmark-placement", "automatic-transcription", "text-to-speech", "multi-audio-mixing"], }); return; @@ -121,6 +125,24 @@ async function run(): Promise { return; } + if (first === "character" && second === "variants" && third) { + const [project, ...flags] = process.argv.slice(5); + if (!project) usage(); + if (third === "status" && flags.length === 0) { + print(await statusDrawnVariants(project)); + return; + } + if (third === "request") { + print(await requestDrawnVariants(project, flags)); + return; + } + if (third === "import" && flags.length >= 2 && flags[flags.length - 1] === "--reviewed-art") { + print(await importDrawnVariants(project, flags.slice(0, -1))); + return; + } + usage(); + } + if (first === "character" && second === "landmarks" && third) { const [project, ...flags] = process.argv.slice(5); if (!project) usage(); diff --git a/tests/drawn-variants.test.ts b/tests/drawn-variants.test.ts new file mode 100644 index 0000000..641f600 --- /dev/null +++ b/tests/drawn-variants.test.ts @@ -0,0 +1,103 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { createImportedCharacter, runRev2D } from "../src/character/avatar.js"; +import { createAvatarBuildRecord, writeAvatarBuildRecord } from "../src/character/provenance.js"; +import { + DRAWN_VARIANT_IDS, importDrawnVariants, requestDrawnVariants, validateDrawnVariantIds, +} from "../src/character/drawn-variants.js"; + +const projects: string[] = []; +afterEach(async () => { + await Promise.all(projects.splice(0).map((dir) => rm(dir, { recursive: true, force: true }))); +}); + +function pngHeader(width: number, height: number): Buffer { + const bytes = Buffer.alloc(24); + Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]).copy(bytes); + bytes.write("IHDR", 12, "ascii"); + bytes.writeUInt32BE(width, 16); + bytes.writeUInt32BE(height, 20); + return bytes; +} + +async function fixture() { + const dir = await mkdtemp(join(tmpdir(), "puppetcontrol-variants-")); + projects.push(dir); + await mkdir(join(dir, "textures")); + await mkdir(join(dir, "variants")); + await writeFile(join(dir, "source.png"), pngHeader(512, 640)); + await writeFile(join(dir, "avatar.json"), '{"format":"rev2d-avatar","name":"test","image":{"file":"source.png"}}'); + await writeFile(join(dir, "textures", "base.png"), "texture"); + await writeFile(join(dir, "test.r2d.json"), JSON.stringify({ + textures: [{ id: "base", path: "textures/base.png", width: 512, height: 640 }], + })); + const parameters = ["AngleX", "AngleY", "EyeBallX", "EyeBallY", "MouthOpen", "MouthForm"] + .map((id) => ({ id, min: -1, max: 1, default: 0 })); + const manifest = createImportedCharacter("test", { parameters }); + manifest.poseFamilies[0]!.approved = true; + await writeFile(join(dir, "character.json"), JSON.stringify(manifest)); + await writeAvatarBuildRecord(dir, await createAvatarBuildRecord(dir, "test.r2d.json")); + return dir; +} + +describe("local drawn avatar variants", () => { + it("defaults to only the two recommended variants", () => { + expect(validateDrawnVariantIds([])).toEqual(["eyes_closed", "mouth_a"]); + expect(DRAWN_VARIANT_IDS).toContain("mouth_o"); + expect(validateDrawnVariantIds(["eyes_closed", "eyes_half"])).toEqual(["eyes_closed", "eyes_half"]); + }); + + it("requires explicit IDs for imports and rejects unsupported, duplicate, and option-like IDs", () => { + expect(() => validateDrawnVariantIds([], true)).toThrowError(/exact reviewed artwork/); + for (const ids of [["eyes_closed", "eyes_closed"], ["--all"], ["../../art"], ["mouth_x"]]) { + expect(() => validateDrawnVariantIds(ids)).toThrowError(/variant ID/); + } + }); + + it("refuses stale imported avatar assets instead of laundering changed model bytes", async () => { + const dir = await fixture(); + const modelFile = join(dir, "test.r2d.json"); + const model = JSON.parse(await readFile(modelFile, "utf8")); + model.meta = { width: 512, height: 640 }; + await writeFile(modelFile, JSON.stringify(model)); + await expect(requestDrawnVariants(dir, ["eyes_closed"], dir)) + .rejects.toMatchObject({ code: "AVATAR_ASSETS_STALE" }); + const json = JSON.parse(await readFile(join(dir, "character.json"), "utf8")); + expect(json.poseFamilies[0].approved).toBe(true); + }); + + it("rejects mismatched illustration size BEFORE modifying the approved manifest", async () => { + const dir = await fixture(); + await writeFile(join(dir, "variants", "eyes_closed.png"), pngHeader(512, 600)); + await expect(importDrawnVariants(dir, ["eyes_closed"], dir)) + .rejects.toMatchObject({ code: "VARIANT_SIZE_MISMATCH" }); + const json = JSON.parse(await readFile(join(dir, "character.json"), "utf8")); + expect(json.poseFamilies[0].approved).toBe(true); + }); + + it("rejects missing selected drawings without revoking the original rig", async () => { + const dir = await fixture(); + await expect(importDrawnVariants(dir, ["mouth_a"], dir)).rejects.toThrow(); + const json = JSON.parse(await readFile(join(dir, "character.json"), "utf8")); + expect(json.poseFamilies[0].approved).toBe(true); + }); + + it("surfaces Rev2D drawing rejection codes and reasons even when diagnostics is empty", async () => { + const dir = await fixture(); + await mkdir(join(dir, "bin")); + await writeFile(join(dir, "bin", "rev2d.js"), [ + "process.stdout.write(JSON.stringify({", + " ok: false, diagnostics: [],", + " checks: [{ id: 'eyes_closed', ok: false, code: 'unchanged', reason: 'No pixels changed' }]", + "}));", + "process.exit(1);", + ].join("\n")); + await expect(runRev2D(dir, ["avatar", "variants", "import", dir])) + .rejects.toMatchObject({ + code: "REV2D_AVATAR_FAILED", + message: expect.stringContaining("unchanged"), + }); + }); +}); From a34696996f7c54ae999c20bd909dfb1c21e2ab89 Mon Sep 17 00:00:00 2001 From: Navneet Chaudhary Date: Sat, 7 Nov 2026 12:45:57 +0530 Subject: [PATCH 2/2] feat: add reviewed short-fade eye sprite experiment --- .agents/skills/puppetcontrol/SKILL.md | 13 +-- README.md | 1 + docs/CHARACTER_IMPORT.md | 8 ++ docs/IMPLEMENTATION_PLAN.md | 3 +- docs/QUALITY_AUDIT.md | 2 +- src/character/drawn-variants.ts | 39 ++++++- src/character/eye-short-fade.ts | 148 ++++++++++++++++++++++++++ src/cli/index.ts | 8 +- tests/eye-short-fade.test.ts | 121 +++++++++++++++++++++ 9 files changed, 328 insertions(+), 15 deletions(-) create mode 100644 src/character/eye-short-fade.ts create mode 100644 tests/eye-short-fade.test.ts diff --git a/.agents/skills/puppetcontrol/SKILL.md b/.agents/skills/puppetcontrol/SKILL.md index 0b4c8d5..150db50 100644 --- a/.agents/skills/puppetcontrol/SKILL.md +++ b/.agents/skills/puppetcontrol/SKILL.md @@ -13,11 +13,12 @@ Read repo-root AGENTS.md, docs/TECHNICAL_CONCEPT.md, and docs/CHARACTER_IMPORT.m 4. For optional image-model-generated landmarks, run `node dist/cli/index.js character landmarks propose --provider codex` only when the user accepts sending artwork to their configured Codex provider. The command produces a review candidate or diagnostic output, never an approved rig. Otherwise, for a manual agent task, run `node dist/cli/index.js character landmarks assist `. Open source.png, work/grid.png and work/landmark-agent-task.md. Fill the generated JSON proposal template with original source-pixel coordinates; do not guess from resized images. Read .cache/rev2d/docs/AVATAR.md. 5. Stage the proposal using `node dist/cli/index.js character landmarks stage --proposal `. Rev2D validates the isolated candidate and returns a work/overlay.png. **Actually inspect the overlay** before `character landmarks accept --candidate --reviewed`. Accepting replaces avatar.json with a backup and revokes all existing pose approvals. Never auto-pass --reviewed solely because a validator passed. 6. Build using node dist/cli/index.js character build (use --force if prior output exists). Inspect any geometryWarnings, particularly BODY_PIVOT_TOO_LOW and IRIS_LANDMARK_MISSING; these do not replace pixel inspection. Source/landmark/model/texture hashes are recorded in avatar-build.json and scene preflight rejects stale assets. Inspect every returned review/poses.png, turn.png, eyes.png and mouth.png. If incorrect, repair avatar.json and rebuild using --force; this resets the generated manifest and any edited scaffold. -7. A successful build intentionally leaves character.json with approved:false. A --force rebuild revokes approval *before* writing model/texture files, even if the rebuild later fails. Only after actual visual QA should an agent/user mark the neutral pose approved. If there are torn eyelids, missing areas, extra contours or identity drift, LEAVE IT UNAPPROVED and report what needs correction. -8. The generated preview-scene.json is editable. Use node dist/cli/index.js scene validate and scene plan before rendering. Preview PNG frames, inspect key timestamps, then render and inspect the MP4. -9. Within a compatible shared rig, semantic pose events may interpolate through validated parameter presets (the neutral-to-pointing demo uses shoulder and elbow controls). Distinct pose models require explicit scene camera cuts; an authored bridge is NOT implemented. Never silently crossfade meshes or call a body cut a smooth physical transition. -10. For speech, prepare WAV, install Rhubarb separately, and use node dist/cli/index.js audio align --out [--binary ]. Reference audio.path, audio.startMs and audio.cuesPath from the scene; review the actual mouth/audio timing. -11. Do not commit private character illustrations, full generated models, user voice recordings or secrets without checking redistribution rights. Demo:avatar generates pinned MIT-licensed sample artwork into ignored .cache. -12. State what actually rendered and which controls remain unsupported. Do not claim a flat PNG is automatically converted into production-quality animation without landmark review. +7. To test optional drawn eye/mouth variants on a built actor, request edit masks, locally supply reviewed `variants/.png`, and explicitly import. With reviewed closed+half eye drawings, `character variants import eyes_closed eyes_half --experimental-short-fade --reviewed-art` shortens fade windows but makes poses change faster and may still ghost; it is a visual experiment, never a default or automatic quality fix. The import revokes prior approval and refreshes provenance only after re-rendering review sheets. +8. A successful build intentionally leaves character.json with approved:false. A --force rebuild revokes approval *before* writing model/texture files, even if the rebuild later fails. Only after actual visual QA should an agent/user mark the neutral pose approved. If there are torn eyelids, missing areas, extra contours or identity drift, LEAVE IT UNAPPROVED and report what needs correction. +9. The generated preview-scene.json is editable. Use node dist/cli/index.js scene validate and scene plan before rendering. Preview PNG frames, inspect key timestamps, then render and inspect the MP4. +10. Within a compatible shared rig, semantic pose events may interpolate through validated parameter presets (the neutral-to-pointing demo uses shoulder and elbow controls). Distinct pose models require explicit scene camera cuts; an authored bridge is NOT implemented. Never silently crossfade meshes or call a body cut a smooth physical transition. +11. For speech, prepare WAV, install Rhubarb separately, and use node dist/cli/index.js audio align --out [--binary ]. Reference audio.path, audio.startMs and audio.cuesPath from the scene; review the actual mouth/audio timing. +12. Do not commit private character illustrations, full generated models, user voice recordings or secrets without checking redistribution rights. Demo:avatar generates pinned MIT-licensed sample artwork into ignored .cache. +13. State what actually rendered and which controls remain unsupported. Do not claim a flat PNG is automatically converted into production-quality animation without landmark review. Keep edits small and testable. Run npm run verify and inspect visual evidence for any animation/asset changes. \ No newline at end of file diff --git a/README.md b/README.md index 9044b4b..d061b9d 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ The long-term goal: **generate artwork when necessary, animate and reuse it inde - Agent-guided landmark proposals: source-hash-bound task, optional **tested** Codex image-based suggestion, isolated geometry validation, visual overlay and explicit review/acceptance that revokes old rig approval. - Imported avatar asset provenance: source/spec/model/texture fingerprints checked by scene validation and render; untracked alternate imported pose models are refused. Force rebuild revokes approval before modifying art. Suspicious landmarks generate nonblocking geometry warnings. - Guarded **local drawn eye/mouth variant** request, status and import commands using Rev2D masks and sprites. Imported drawings revoke approval and require a fresh visual review; no image generation happens automatically. +- An optional **experimental** short-fade profile for imported half/closed eye drawings; avoids prolonged duplicate lash outlines at the cost of faster pose changes, revokes approval and regenerates review sheets. - Agent-readable CLI output, tests and CI. **Not implemented yet:** fully automatic landmark placement or reliable one-click rigging, AI-generated arbitrary new pose rigs, convincing smooth bridges between unrelated meshes (especially crossed arms), automatic transcription/TTS, captions, B-roll and multiple actors. The arm-raise gesture is genuinely animated, but its artwork is still prototype-quality. Other pose families may require edited hard cuts. The pose manifest is capability metadata; visual poses become usable only after their rig files are generated, validated and inspected. diff --git a/docs/CHARACTER_IMPORT.md b/docs/CHARACTER_IMPORT.md index 17412be..f20ea00 100644 --- a/docs/CHARACTER_IMPORT.md +++ b/docs/CHARACTER_IMPORT.md @@ -95,6 +95,14 @@ node dist/cli/index.js character variants import avatars/portrait eyes_closed ey node dist/cli/index.js character variants status avatars/portrait ~~~ +For illustrations with **both** `eyes_closed` and `eyes_half` correctly drawn, there is an additional **opt-in experiment**: + +~~~sh +node dist/cli/index.js character variants import avatars/portrait eyes_closed eyes_half --experimental-short-fade --reviewed-art +~~~ + +The default import preserves Rev2D's native fades. The experimental switch shortens the eye-sprite crossfade windows to `EyeOpen 0.18–0.20` (closed to half) and `0.68–0.70` (half to mesh). This reduces double outlines in some frames, **but makes the eyelids pop more quickly**, and ghosting remains possible within the short transition windows. It requires both drawn eye shapes on both sides and refuses unsupported/smiling-eye setups. A later import **without** the flag returns to the native generated fades. This is not a production-quality guarantee. + Import checks the drawing size, then delegates to Rev2D's mask, global shift/zoom and seam checks. It revokes every existing pose approval **before** touching model or texture assets; on success it re-renders `review/eyes.png`, `review/mouth.png` and `review/poses.png` and refreshes asset fingerprints. **It never auto-approves.** Inspect the output for face jumps, halos, duplicate lines and inconsistent colors, then explicitly reapprove in `character.json` if acceptable. An upstream import can partially accept images before rejecting another. On error, the character remains unapproved and the old provenance may intentionally be stale; rebuild with `character build avatars/portrait --force` if necessary, inspect again, and only then retry. Do not assume that a successful import means the new drawings look good. Automatic image generation, reliable facial polish and smooth unrelated-pose bridges remain separate goals. diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index db36dca..18216b3 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -78,7 +78,8 @@ - [x] Eliminate reproduced black edge artifacts caused by alpha-zero warped pixels in H.264: composite frames onto scene background, with a 60-frame before/after comparison. - [ ] Add pixel-level motion QA probes and a reviewable report; automated geometry warnings are not proof of visual quality. - [x] Wrap local Rev2D drawn eye/mouth variant request/status/import with explicit reviewed-art selection, approval revocation before import, post-import provenance refresh, and new review sheets. A real Hana avatar produced correct edit masks; unchanged fake drawings were rejected. -- [ ] Produce and visually approve high-quality closed/half eye and mouth artwork; demonstrate seamless real rendered transitions. A local, disposable hand-drawn closed/half eye trial now passes mask checks, but inspection still shows flat eyelids and doubled contours during fades; the rig stays unapproved. +- [x] Test and expose an opt-in, validated short eye-sprite fade as a local derived-model experiment. Compare 13 actual Hana blink frames with native, immediate-switch and shortened fades: shorter fades visibly reduce double lashes at sampled midpoints, but introduce faster pose changes; never auto-approve. +- [ ] Produce and visually approve high-quality closed/half eye and mouth artwork; demonstrate seamless real rendered transitions across full blink playback and multiple character styles. The local proof drawing stays unapproved. ## Acceptance benchmark diff --git a/docs/QUALITY_AUDIT.md b/docs/QUALITY_AUDIT.md index 14d1081..caf168a 100644 --- a/docs/QUALITY_AUDIT.md +++ b/docs/QUALITY_AUDIT.md @@ -74,7 +74,7 @@ Rev2D creates eye-white, iris, upper/lower lid, lash, crease and foreground-hair ## 6. Next milestones 1. **Guarded local drawn-variant CLI added:** request/status/import supported by pinned Rev2D. Request masks for eyes_closed, eyes_half and mouth_a on a fresh 512×640 Hana import were generated and visually inspected. Importing an unchanged eyes_closed image correctly failed upstream with code `unchanged` and did not approve the character. A separate *throwaway* Hana project then accepted locally hand-procedurally-redrawn eyes_closed and eyes_half artwork (both with outsideDiff=0 and nearDiff=0); approval remained false. Actual eyes review frames showed the closed-eye lashes more continuous than the original mesh deformation, but a faint lower contour, too-flat half-open eyelids and double contours during fades remained. **These test drawings are not acceptable character art**, are only in ignored local .cache, and are not redistributed. No AI provider was used and no arbitrary-character quality claim follows. -2. Add image-based QA probes for rest-pose identity, blink/gaze/mouth activity, and head/neck discontinuities. Quantitative reports are triage, not automatic visual approval. +2. **Experimental fade mitigation tested:** a 13-frame 30fps Hana blink was rendered with native opacity blending, an immediate sprite switch and a shortened fade. The opt-in `--experimental-short-fade` importer now produces the shorter blend windows after Rev2D validates the derived model, regenerates review sheets and refreshes fingerprints. At sampled `EyeOpen=0.667`, the guarded import produced the exact same PNG hash as the clean short-fade experiment; the native frame visibly had double eye outlines. The short fade changes pose faster, and can still overlap shapes within the narrow transition windows. The rig remains **unapproved**. Add image-based QA probes for rest-pose identity, blink/gaze/mouth activity, and head/neck discontinuities. Quantitative reports are triage, not automatic visual approval. 3. Build a diverse rights-cleared benchmark matrix: eye size, hair over face, accessories/glasses, different skin tones and line styles, opaque versus transparent backgrounds and constrained 3/4 views. Track success/failure on each, not just demos. 4. Only after a reliable single actor: improve body-pose transitions, synchronized multi-actor shots and user-facing authoring polish. diff --git a/src/character/drawn-variants.ts b/src/character/drawn-variants.ts index 6fce4a3..ba07a9d 100644 --- a/src/character/drawn-variants.ts +++ b/src/character/drawn-variants.ts @@ -5,9 +5,11 @@ * A successful import mutates the model/textures, invalidates previous visual * approval, rebuilds review sheets, then refreshes exact asset fingerprints. */ -import { open, readFile, stat } from "node:fs/promises"; -import { join } from "node:path"; +import { open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises"; +import { randomUUID } from "node:crypto"; +import { dirname, join } from "node:path"; import { characterSchema } from "../scene/schemas.js"; +import { shortFadeDrawnEyes } from "./eye-short-fade.js"; import { AvatarWorkflowError, checkedPath, parsePngSize, pinnedRev2D, runRev2D, } from "./avatar.js"; @@ -24,6 +26,7 @@ export const DRAWN_VARIANT_IDS = [ const ALLOWED_VARIANTS = new Set(DRAWN_VARIANT_IDS); const DEFAULT_VARIANTS = ["eyes_closed", "mouth_a"]; const MAX_DRAWING_BYTES = 30 * 1024 * 1024; +const MAX_MODEL_BYTES = 20 * 1024 * 1024; export function validateDrawnVariantIds( requested: readonly string[], requireExplicit = false, @@ -121,12 +124,33 @@ export async function statusDrawnVariants(projectDir: string, root = process.cwd } /** - * Import only explicitly selected, locally reviewed drawings. Never approve a - * rig here. If Rev2D partially mutates assets and then rejects art, the old - * build record intentionally stays stale, preventing unreviewed rendering. + * Adjust only derived eye-opacity curves of a locally reviewed rig. + * The calling import operation revokes visual approval before writing. + * Validation and new fingerprints are required after this step. */ +async function applyExperimentalShortFade( + project: string, modelRelative: string, backend: string, +) { + const modelPath = await checkedPath(project, join(project, modelRelative)); + const file = await stat(modelPath); + if (!file.isFile() || file.size > MAX_MODEL_BYTES) { + throw new AvatarWorkflowError("EYE_SHORT_FADE_UNSUPPORTED", "Invalid or oversized Rev2D model."); + } + const transformed = shortFadeDrawnEyes(JSON.parse(await readFile(modelPath, "utf8")) as unknown); + const temporary = join(dirname(modelPath), ".puppetcontrol-shortfade-" + randomUUID() + ".r2d.json"); + try { + await writeFile(temporary, JSON.stringify(transformed.model), { flag: "wx" }); + await runRev2D(backend, ["validate", temporary]); + await rename(temporary, modelPath); + } finally { + await unlink(temporary).catch(() => undefined); + } + return { profile: "experimental-short-fade" as const, ...transformed.profile, changedBindings: transformed.changedBindings }; +} +/** Import reviewed artwork, leave unapproved; preserve stale hashes on a partial failure. */ export async function importDrawnVariants( projectDir: string, requested: readonly string[], root = process.cwd(), + options: { experimentalShortFade?: boolean } = {}, ) { const ids = validateDrawnVariantIds(requested, true); const { project, manifestPath, manifest } = await verifiedImportedAvatar(projectDir, root); @@ -147,8 +171,12 @@ export async function importDrawnVariants( // IMPORTANT: revoke before Rev2D can touch model, layers or texture files. await revokeAvatarApprovalBeforeBuild(manifestPath); let imported: unknown; + let profile: Awaited> | undefined; try { imported = await runRev2D(backend, ["avatar", "variants", "import", project, ...ids], 240_000); + if (options.experimentalShortFade) { + profile = await applyExperimentalShortFade(project, manifest.render!.modelPath, backend); + } await runRev2D(backend, ["avatar", "poses", project], 240_000); const record = await createAvatarBuildRecord(project, manifest.render!.modelPath); await writeAvatarBuildRecord(project, record); @@ -163,6 +191,7 @@ export async function importDrawnVariants( return { valid: true, status: "review-required", approved: false, projectDir: project, variants: ids, backend: imported, + ...(profile ? { eyeTransition: profile } : {}), review: { eyes: join(project, "review", "eyes.png"), mouth: join(project, "review", "mouth.png"), diff --git a/src/character/eye-short-fade.ts b/src/character/eye-short-fade.ts new file mode 100644 index 0000000..1cad0fe --- /dev/null +++ b/src/character/eye-short-fade.ts @@ -0,0 +1,148 @@ +/** + * Experimental short-fade profile for Rev2D's *drawn* half/closed eye sprites. + * + * The upstream engine linearly dissolves two complete eye illustrations across + * EyeOpen 0.12–0.2 and 0.6–0.7. Double lash lines become visible when their + * geometry differs. Narrowing the opacity windows reduces how long both drawings + * overlap, but deliberately trades smoothness for crispness. + * + * Never apply to a source or approved model in place. Callers must revoke visual + * approval, validate the derived model and regenerate review images and hashes. + */ +import { AvatarWorkflowError } from "./avatar.js"; + +type JsonRecord = Record; +type Rev2DBinding = { + id: string; + target: string; + params: string[]; + keys: Array<{ at: number[]; value: number }>; +}; + +export const SHORT_FADE_EYE_PROFILE = { + /** Fade from closed to half across this EyeOpen range. */ + closedToHalf: [0.18, 0.20], + /** Fade from half to mesh across this EyeOpen range. */ + halfToMesh: [0.68, 0.70], +} as const; + +export interface ShortFadeResult { + /** A NEW model object. Caller owns its publication and renewed review. */ + model: JsonRecord; + changedBindings: string[]; + profile: typeof SHORT_FADE_EYE_PROFILE; +} + +function unsupported(why: string): never { + throw new AvatarWorkflowError( + "EYE_SHORT_FADE_UNSUPPORTED", + "Cannot safely apply the optional short-fade policy: " + why + + ". Leave the upstream rig unchanged and inspect its review sheets.", + ); +} + +function isBinding(input: unknown): input is Rev2DBinding { + if (!input || typeof input !== "object" || Array.isArray(input)) return false; + const b = input as Partial; + return typeof b.id === "string" && + typeof b.target === "string" && + Array.isArray(b.params) && b.params.every((p) => typeof p === "string") && + Array.isArray(b.keys) && b.keys.length >= 2 && b.keys.every( + (key) => key && Array.isArray(key.at) && key.at.length === 1 && + typeof key.at[0] === "number" && Number.isFinite(key.at[0]) && + typeof key.value === "number" && Number.isFinite(key.value), + ); +} + +function points(entries: Array): Rev2DBinding["keys"] { + return entries.map(([at, value]) => ({ at: [at], value })); +} + +const expectedSprites = [ + ["sprite_eyes_closed_imageLeftShow", "EyeROpen"], + ["sprite_eyes_closed_imageRightShow", "EyeLOpen"], + ["sprite_eyes_half_imageLeftShow", "EyeROpen"], + ["sprite_eyes_half_imageRightShow", "EyeLOpen"], +] as const; + +function expectedParam(id: string): string | null { + if (id.includes("imageLeft") || id.startsWith("eyeR_")) return "EyeROpen"; + if (id.includes("imageRight") || id.startsWith("eyeL_")) return "EyeLOpen"; + return null; +} + +/** Pure transform, only on the known, fully supported two-eye sprite topology. */ +export function shortFadeDrawnEyes(input: unknown): ShortFadeResult { + if (!input || typeof input !== "object" || Array.isArray(input)) unsupported("invalid model JSON"); + const candidate = structuredClone(input) as JsonRecord; + const bindings = candidate.bindings; + if (!Array.isArray(bindings)) unsupported("missing bindings"); + // Other Rev2D bindings may control multi-parameter warps and structured + // vertex offsets rather than scalar opacity; preserve them untouched. + const eyeBindings: Rev2DBinding[] = []; + const byId = new Map(); + for (const value of bindings) { + if (!value || typeof value !== "object") continue; + const id = (value as { id?: unknown }).id; + if (typeof id !== "string") continue; + if (byId.has(id)) unsupported("duplicate binding " + id); + if (!isBinding(value)) { + if (id.startsWith("sprite_eyes_") || id.endsWith("UnderSprite")) unsupported("unsupported eye binding " + id); + continue; + } + byId.set(id, value); + eyeBindings.push(value); + } + if ([...byId.keys()].some((id) => id.startsWith("sprite_eyes_smile_"))) { + unsupported("the separate eyes_smile layering has not been checked with this profile"); + } + for (const [id, param] of expectedSprites) { + const binding = byId.get(id); + const partId = id.slice(0, -"Show".length); + if (!binding || binding.target !== "part:" + partId + ".opacity" || + binding.params.length !== 1 || binding.params[0] !== param) { + unsupported("missing or incompatible " + id + "; both reviewed half/closed variants are required"); + } + } + const underneath = eyeBindings.filter((b) => + /^eye[LR]_(?:white|ball|lower|upper|lowerRim|crease|upperRim)UnderSprite$/.test(b.id)); + for (const side of ["eyeL_", "eyeR_"]) { + if (underneath.filter((b) => b.id.startsWith(side)).length < 4) { + unsupported("incomplete eye-mesh hide controls for " + side); + } + } + for (const b of underneath) { + const param = expectedParam(b.id); + if (!param || b.params.length !== 1 || b.params[0] !== param || + b.target !== "part:" + b.id.slice(0, -"UnderSprite".length) + ".opacity") { + unsupported("incompatible eye mesh opacity control " + b.id); + } + const hidden = b.keys[0]!.value; + const visible = b.keys[b.keys.length - 1]!.value; + if (Math.abs(hidden) > 1e-5 || Math.abs(visible - 1) > 1e-5) { + unsupported("nonstandard eye mesh opacity limits for " + b.id); + } + } + + const [closedStart, closedEnd] = SHORT_FADE_EYE_PROFILE.closedToHalf; + const [openStart, openEnd] = SHORT_FADE_EYE_PROFILE.halfToMesh; + const changed: string[] = []; + for (const b of eyeBindings) { + if (b.id.startsWith("sprite_eyes_closed_") && b.id.endsWith("Show")) { + b.keys = points([[0, 1], [closedStart, 1], [closedEnd, 0], [1, 0]]); + } else if (b.id.startsWith("sprite_eyes_half_") && b.id.endsWith("Show")) { + b.keys = points([[0, 0], [closedStart, 0], [closedEnd, 1], + [openStart, 1], [openEnd, 0], [1, 0]]); + } else if (underneath.includes(b)) { + b.keys = points([[0, 0], [openStart, 0], [openEnd, 1], [1, 1]]); + } else { + continue; + } + changed.push(b.id); + } + // Fail closed if an upgraded Rev2D adds a different sprite curve not covered. + if (changed.filter((id) => id.endsWith("Show")).length !== expectedSprites.length) { + unsupported("not every known eye sprite can be transformed"); + } + return { model: candidate, changedBindings: changed, profile: SHORT_FADE_EYE_PROFILE }; +} diff --git a/src/cli/index.ts b/src/cli/index.ts index 8126ad2..8bda0e0 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -30,7 +30,7 @@ function usage(): never { " puppetctl character build [--force]\n" + " puppetctl character variants request [variant-id ...]\n" + " puppetctl character variants status \n" + - " puppetctl character variants import --reviewed-art\n" + + " puppetctl character variants import [--experimental-short-fade] --reviewed-art\n" + " puppetctl character landmarks assist \n" + " puppetctl character landmarks propose --provider codex\n" + " puppetctl character landmarks stage --proposal \n" + @@ -137,7 +137,11 @@ async function run(): Promise { return; } if (third === "import" && flags.length >= 2 && flags[flags.length - 1] === "--reviewed-art") { - print(await importDrawnVariants(project, flags.slice(0, -1))); + const requested = flags.slice(0, -1); + const shortFadeIndex = requested.indexOf("--experimental-short-fade"); + if (shortFadeIndex >= 0 && shortFadeIndex !== requested.length - 1) usage(); + const ids = shortFadeIndex >= 0 ? requested.slice(0, -1) : requested; + print(await importDrawnVariants(project, ids, process.cwd(), { experimentalShortFade: shortFadeIndex >= 0 })); return; } usage(); diff --git a/tests/eye-short-fade.test.ts b/tests/eye-short-fade.test.ts new file mode 100644 index 0000000..a7619b9 --- /dev/null +++ b/tests/eye-short-fade.test.ts @@ -0,0 +1,121 @@ +import { describe, expect, it } from "vitest"; +import { shortFadeDrawnEyes } from "../src/character/eye-short-fade.js"; + +type B = { id: string; target: string; params: string[]; keys: { at: number[]; value: number }[] }; +const values = (entries: Array<[number, number]>) => entries.map(([at, value]) => ({ at: [at], value })); +const sprite = (name: string, param: string, initial: number): B => ({ + id: name + "Show", target: "part:" + name + ".opacity", params: [param], + keys: values([[0, initial], [1, 0]]), +}); +function fixture() { + const bindings: B[] = [ + sprite("sprite_eyes_closed_imageLeft", "EyeROpen", 1), + sprite("sprite_eyes_closed_imageRight", "EyeLOpen", 1), + sprite("sprite_eyes_half_imageLeft", "EyeROpen", 1), + sprite("sprite_eyes_half_imageRight", "EyeLOpen", 1), + ]; + for (const [eye, param] of [["eyeR", "EyeROpen"], ["eyeL", "EyeLOpen"]]) { + for (const kind of ["white", "ball", "lower", "upper", "crease"]) { + const name = eye + "_" + kind; + bindings.push({ + id: name + "UnderSprite", target: "part:" + name + ".opacity", + params: [param], keys: values([[0, 0], [0.7, 1], [1, 1]]), + }); + } + } + bindings.push({ id: "mouthShape", target: "part:mouth.opacity", + params: ["MouthOpen"], keys: values([[0, 1], [1, 1]]) }); + return { meta: { name: "experimental", width: 512, height: 640 }, bindings }; +} + +function sample(keys: { at: number[]; value: number }[], x: number) { + if (x <= keys[0]!.at[0]!) return keys[0]!.value; + for (let i = 1; i < keys.length; i++) { + const a = keys[i - 1]!, b = keys[i]!; + if (x <= b.at[0]!) { + const fraction = (x - a.at[0]!) / (b.at[0]! - a.at[0]!); + return a.value + (b.value - a.value) * fraction; + } + } + return keys[keys.length - 1]!.value; +} + +describe("experimental short fade for reviewed eye sprites", () => { + it("returns a new model with only expected eye opacity bindings changed", () => { + const src = fixture(); + const before = structuredClone(src); + const result = shortFadeDrawnEyes(src); + const bindings = result.model.bindings as B[]; + expect(src).toEqual(before); + expect(result.model).not.toBe(src); + expect(result.changedBindings).toHaveLength(14); + expect(bindings.find((b) => b.id === "mouthShape")).toEqual(before.bindings.at(-1)); + for (const side of ["imageLeft", "imageRight"]) { + const closed = bindings.find((b) => b.id === "sprite_eyes_closed_" + side + "Show")!; + const half = bindings.find((b) => b.id === "sprite_eyes_half_" + side + "Show")!; + expect(sample(closed.keys, 0.167)).toBe(1); + expect(sample(half.keys, 0.167)).toBe(0); + expect(sample(half.keys, 0.5)).toBe(1); + expect(sample(half.keys, 0.667)).toBe(1); + expect(sample(half.keys, 0.833)).toBe(0); + expect(sample(closed.keys, 0.19)).toBeCloseTo(0.5, 7); + expect(sample(half.keys, 0.19)).toBeCloseTo(0.5, 7); + // It is a short fade, NOT a claim that transitions can never ghost. + } + expect(result.profile.closedToHalf).toEqual([0.18, 0.2]); + }); + + it("keeps both eyes fully hidden in drawn poses, and restores mesh outside the sprites", () => { + const model = shortFadeDrawnEyes(fixture()).model; + const mesh = (model.bindings as B[]).filter((b) => b.id.endsWith("UnderSprite")); + expect(mesh).toHaveLength(10); + for (const b of mesh) { + expect(sample(b.keys, 0.5)).toBe(0); + expect(sample(b.keys, 0.667)).toBe(0); + expect(sample(b.keys, 0.7)).toBe(1); + expect(sample(b.keys, 1)).toBe(1); + } + }); + + it("preserves upstream multi-parameter warp bindings even though their values are not scalars", () => { + const original = fixture(); + const warp = { + target: "warp:avatarWarp.offsets", params: ["AngleX", "AngleY"], + keys: [{ at: [-30, -30], value: { "264": [-0.01, 0.01] } }], + }; + const model = { ...original, bindings: [...original.bindings, warp] }; + const before = structuredClone(model); + const transformed = shortFadeDrawnEyes(model).model as { bindings: unknown[] }; + expect(model).toEqual(before); + expect(transformed.bindings.at(-1)).toEqual(warp); + }); + + it("refuses a missing half-eye sprite or incomplete mesh-hide rig", () => { + const a = fixture(); + a.bindings = a.bindings.filter((b) => b.id !== "sprite_eyes_half_imageRightShow"); + expect(() => shortFadeDrawnEyes(a)).toThrow(/half.*closed variants/); + const b = fixture(); + b.bindings = b.bindings.filter((entry) => !entry.id.startsWith("eyeR_") || entry.id.includes("white")); + expect(() => shortFadeDrawnEyes(b)).toThrow(/incomplete eye-mesh/); + }); + + it("refuses unknown eye smile layering, duplicate bindings or incorrect eye parameter mapping", () => { + const smile = fixture(); + smile.bindings.push(sprite("sprite_eyes_smile_imageLeft", "EyeRSmile", 1)); + expect(() => shortFadeDrawnEyes(smile)).toThrow(/eyes_smile/); + const duplicate = fixture(); + duplicate.bindings.push(duplicate.bindings[0]!); + expect(() => shortFadeDrawnEyes(duplicate)).toThrow(/duplicate/); + const mismatch = fixture(); + mismatch.bindings[0]!.params = ["EyeLOpen"]; + expect(() => shortFadeDrawnEyes(mismatch)).toThrow(/incompatible/); + }); + + it("refuses unsupported model layouts and nonstandard mesh-opacity values", () => { + expect(() => shortFadeDrawnEyes(null)).toThrow(/invalid model/); + expect(() => shortFadeDrawnEyes({ bindings: [] })).toThrow(/missing or incompatible/); + const invalid = fixture(); + invalid.bindings[4]!.keys[0]!.value = 0.1; + expect(() => shortFadeDrawnEyes(invalid)).toThrow(/nonstandard/); + }); +});