Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skills/puppetcontrol/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Read repo-root AGENTS.md, docs/TECHNICAL_CONCEPT.md, and docs/CHARACTER_IMPORT.m
5. Stage the proposal using `node dist/cli/index.js character landmarks stage <project-dir> --proposal <proposal.json>`. Rev2D validates the isolated candidate and returns a work/overlay.png. **Actually inspect the overlay** before `character landmarks accept <project-dir> --candidate <returned-dir> --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 <project-dir> (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. To test optional drawn eye/mouth variants on a built actor, request edit masks, locally supply reviewed `variants/<id>.png`, and explicitly import. With reviewed closed+half eye drawings, `character variants import <project> 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. For a compatible imported avatar whose extracted lash warps look unnatural, optionally run `character eyes vectorize <project> --experimental`. This creates a **new provenance-tracked vector eyelid model**, preserves source drawings, revokes existing approval, and renders real 30 FPS blink evidence. It uses the eye-mask vertices for a continuously deforming line, not alpha-switching; styling still needs human review. See `docs/VECTOR_EYELIDS.md`.
8. For a compatible imported avatar whose extracted lash warps look unnatural, optionally run `character eyes vectorize <project> --experimental`. This creates a **new provenance-tracked vector eyelid model**, preserves source drawings, revokes existing approval, and renders real 30 FPS blink evidence. It uses the eye-mask vertices for a continuously deforming line, not alpha-switching. Derived rigs require fresh SHA-256-bound eyes/full/video evidence before `character approve`; if missing or stale, run `character eyes review <project>` and inspect the returned real frames. Neither evidence nor software can prove artistic acceptance or user consent. See `docs/VECTOR_EYELIDS.md`.
9. For a deliberately non-blended eye-art experiment, `character variants import <project> eyes_closed eyes_half --experimental-stepped-eyes --reviewed-art` selects only one complete eye appearance outside tiny threshold windows. It can remove ghosted doubled lashes but creates visible pose pops; do not call it seamless or automatically approve. See `docs/EYE_TRANSITIONS.md` and compare actual frames.
10. Before approving a verified imported rig, run `node dist/cli/index.js character qa blink <project-dir>` to generate an ordered 25-frame actual eyelid transition contact sheet (`blink-eyes.png` and `blink-full.png`); inspect EyeOpen=0.19 and 0.69 and the real eye artwork seams. The QA report flags motion stalls but never passes visual approval. Also run `character qa blink <project-dir> --timed` for a 36-frame synthetic 30 FPS video and review the actual moving result. Different fade policies may produce identical frames when their transition windows fall between sampled timestamps; see `docs/EYE_TIMING.md`.
11. 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 may an agent/user explicitly run `node dist/cli/index.js character approve <project-dir> --reviewed` (the flag is an acknowledgement, not evidence of review) to record neutral-pose approval. If there are torn eyelids, missing areas, extra contours or identity drift, LEAVE IT UNAPPROVED and report what needs correction.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The long-term goal: **generate artwork when necessary, animate and reuse it inde
- Local PNG pixel and ordered-frame QA (full frame or explicit region) reports RGB activity, unexpected transparency, candidate motion jumps and changed-control stalls; these metrics never auto-approve a rig.
- Import review can render a 25-frame parameter-sweep contact sheet and a separate **36-frame, 30 FPS synthetic timed-blink MP4** with motion warnings; see [Character Review](docs/CHARACTER_REVIEW.md) and [Time-domain Blink QA](docs/EYE_TIMING.md). The opt-in [stepped-eye experiment](docs/EYE_TRANSITIONS.md) removes sampled opacity ghosting but does not provide a seamless morph. The two modes even produced byte-identical frames in one real-time test.
- Imported flat-image actors start with narrower editable head/gaze motion limits; see [Look Motion](docs/LOOK_MOTION.md).
- Optional **experimental continuous vector eyelids** replace warped raster lash outlines with thin mask-following Rev2D mesh strips while keeping the iris clipped. This improves one real Hana sample without approval and requires artistic review; see [Vector Eyelids](docs/VECTOR_EYELIDS.md).
- Optional **experimental continuous vector eyelids** replace warped raster lash outlines with thin mask-following Rev2D mesh strips while keeping the iris clipped. This improves one real Hana sample without automatic approval. A **current-model SHA-256-bound eye/full/video proof** is required before explicit approval; use `character eyes review <project>` to refresh it. See [Vector Eyelids](docs/VECTOR_EYELIDS.md).
- Optional SHA-256 Rhubarb cue bindings can detect when audio or mouth-cue bytes are replaced after alignment; a bound scene fails validation/render instead of silently using stale lip sync.
- Agent-readable CLI output, tests and CI.

Expand Down
2 changes: 1 addition & 1 deletion docs/CHARACTER_REVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ For a genuinely deforming eyelid outline instead of alpha-switching whole-eye pi
node dist/cli/index.js character eyes vectorize avatars/portrait --experimental
~~~

It uses the existing Rev2D eye-white mask to deform upper/lower lashes continuously, keeps the iris clipped, preserves the previous model, writes new fingerprints, and revokes approval. Unlike the sprite transitions it simplifies the painted lashes; visually inspect the resulting video. See [VECTOR_EYELIDS.md](VECTOR_EYELIDS.md).
It uses the existing Rev2D eye-white mask to deform upper/lower lashes continuously, keeps the iris clipped, preserves the previous model, writes new fingerprints, and revokes approval. Unlike the sprite transitions it simplifies the painted lashes; visually inspect the resulting video. **The generated model requires a model-hash-bound eye/full/MP4 review proof before approval.** If evidence is missing, run `character eyes review <project>` and examine all fresh frames. See [VECTOR_EYELIDS.md](VECTOR_EYELIDS.md).

## 3. Inspect exact blink transition frames

Expand Down
1 change: 1 addition & 0 deletions docs/IMPLEMENTATION_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@
- [x] Test an optional stepped-eye visibility profile that removes sampled double-sprite ghosting at EyeOpen 0.19/0.69 on refined MIT Hana artwork, with a 25-frame A/B render, explicit abrupt-change warnings and local 45-frame end-to-end smoke video. The source remains unapproved; **this trades ghosting for pose popping**, not a seamless morph.
- [x] Add a 36-frame, 30 FPS time-domain blink QA export with deterministic synthetic timing, unique Rev2D state caching, and JSON motion warnings. The actual short-fade and stepped 30 FPS frames were SHA-256 identical for this one schedule, showing threshold tuning alone is insufficient. Four mesh/overlay variants failed visual QA and were not integrated.
- [x] Build an opt-in, provenance-verified **continuous vector eyelid** rig: replace distorted raster lash warps with curved vertex strips driven by Rev2D's existing eye mask, preserving iris clipping and source art. Inspect real 9-state, 30 FPS blink and head/gaze sweeps; 90-frame end-to-end H.264 export verified. The Hana experiment remains unapproved and artists may prefer their own lash styling.
- [x] Make derived vector rig approvals require a SHA-256-bound current-model full/eye/30 FPS MP4 review package. Reject stale/missing/tampered files and renamed vector geometry; add `character eyes review` recovery without changing approval. Real licensed Hana test regenerated evidence successfully and remained unapproved.
- [ ] 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.

## First video milestone — reproducible usable slice (2026-11-07)
Expand Down
16 changes: 16 additions & 0 deletions docs/VECTOR_EYELIDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,22 @@ The command requires a single-pose, provenance-verified imported Rev2D character

It deliberately **revokes previous approval before publishing** the new model. Its unique `*-vector-eyelids-<uuid>.r2d.json` file is validated and hashed, the manifest is updated to reference it, and the original model and original user artwork are preserved. A successful operation generates a private `outputs/qa/blink-review/<uuid>/blink-timed-30fps.mp4` plus eye/full contact sheets and motion warnings. It returns the exact paths.

### Current-model review evidence is required before approval

Old `review/poses.png`, `review/turn.png`, `review/eyes.png` and `review/mouth.png` may have been generated **before** vectorization. Their presence alone is insufficient evidence for the new eyelid rig.

The vectorize operation now writes `review/vector-eyelids-proof.json` only **after** a real timed Rev2D blink and full/eyes contact sheets have rendered. It copies those three artifacts to a unique `review/vector-eyes-<uuid>/` directory. The proof binds the **exact model SHA-256** from `avatar-build.json` to the SHA-256 hashes of all three review artifacts. `character approve --reviewed` refuses vector geometry without a matching proof, even if its model filename was manually changed.

If FFmpeg fails, review files are lost or a generated package becomes stale, rerun:

~~~powershell
node dist/cli/index.js character eyes review avatars/portrait
~~~

This regenerates only the review evidence for the current provenance-verified vector rig. It leaves the rig and its existing approval state unchanged; it never auto-approves. Inspect the newly returned full-frame and eye close-ups and the timed video **plus** the older head/turn/mouth sheets for unchanged regions before recording your own `--reviewed` acknowledgement.

A proof verifies exact bytes and which model produced the review package. It **does not** verify that a person actually looked at the images, that the images are visually acceptable, or that the model is suitable for other character styles.

The current mutation is a local, non-transactional pair of file replacements for the model reference and fingerprint record. An interrupted update can temporarily fail verification, **never implicitly approve** an avatar. Restore the previous verified project copy or explicitly rebuild with `character build ... --force` if that happens. Make a backup of your imported project before experimenting.

Do not combine the derived vector rig with subsequent drawn-eye variant imports without rebuilding the avatar first; Rev2D's upstream variant importer targets its original model filename.
Expand Down
9 changes: 6 additions & 3 deletions src/character/eyelid-vector-workflow.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import {
verifyAvatarBuildRecord, writeAvatarBuildRecord,
} from "./provenance.js";
import { createBlinkReview } from "./blink-review.js";
import { publishVectorReviewProof } from "./vector-review-evidence.js";
import { vectorizeImportedEyelids } from "./eyelid-vector.js";

const MAX_MODEL = 20_000_000;
Expand Down Expand Up @@ -118,10 +119,12 @@ export async function createVectorEyelidRig(
let review: Record<string, unknown>;
try {
const rendered = await createBlinkReview(project, { root, timed: true });
const proof = await publishVectorReviewProof(project, relModel, rendered, root);
review = {
video: rendered.timedVideo,
eyes: rendered.eyeSheet,
full: rendered.fullSheet,
video: proof.video,
eyes: proof.eyes,
full: proof.full,
proofFile: proof.proofFile,
report: rendered.reportPath,
};
} catch (cause) {
Expand Down
10 changes: 9 additions & 1 deletion src/character/review-approval.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { join, resolve } from "node:path";
import { AvatarWorkflowError, checkedPath } from "./avatar.js";
import { checkAvatarPoseCoverage, verifyAvatarBuildRecord } from "./provenance.js";
import { characterSchema, type Character } from "../scene/schemas.js";
import { requiresVectorReviewProof, verifyVectorReviewProof } from "./vector-review-evidence.js";

const REVIEW_FILES = ["poses.png", "turn.png", "eyes.png", "mouth.png"] as const;
const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
Expand Down Expand Up @@ -187,7 +188,11 @@ export async function approveImportedAvatar(
const { raw, character } = parseManifest(originalContents);
requireSupportedImportedAvatar(character);
await verifyCurrentBuild(characterPath, character);
const reviewArtifacts = await validateReviewArtifacts(project);
const reviewArtifacts = [
...await validateReviewArtifacts(project),
...(await requiresVectorReviewProof(project, character.render!.modelPath)
? await verifyVectorReviewProof(project, character.render!.modelPath) : []),
];

if (character.poseFamilies[0]!.approved) {
return {
Expand Down Expand Up @@ -224,6 +229,9 @@ export async function approveImportedAvatar(
// Recheck the exact build and review artifacts immediately before the atomic manifest swap.
await verifyCurrentBuild(characterPath, character);
await validateReviewArtifacts(project);
if (await requiresVectorReviewProof(project, character.render!.modelPath)) {
await verifyVectorReviewProof(project, character.render!.modelPath);
}
await rename(tempPath, characterPath);
} finally {
await unlink(tempPath).catch(() => undefined);
Expand Down
Loading
Loading