宜博 / h3livestream

Requires login + emailVerified (M.10). Order matters and each step
undoes the previous one on failure: moderate (T26) before anything
else exists, so a rejected image leaves nothing behind; create the
garments row (source: user_paid) before spending, so the ledger entry
can carry relatedAssetId — a failed spend deletes it back out;
generation submission failure refunds and deletes it too. Reuses T8/
T9's submitGeneration whole, same M.7 dedupe cache, then rides the
same danceQueue/ensureDanceSchedule machinery /api/dance/pick (mode 1)
already uses — a paid entry only differs by carrying userId/
amountPaid, which mode 1's free entries don't set.

Async generation failure (job fails after this handler already
responded) is refunded from ensureDanceSchedule's existing "generating
-> failed" tick, gated on a findByRelatedAssetAndReason lookup so a
crash between that write and saveDanceState() persisting it can't
double-refund — a duplicate here is real money, not a cosmetic bug.

dance-mode2.test.js covers the full chain against a mock H3 Console:
login/verification/balance gates, a non-image upload rejected before
anything is spent, the happy path (spend -> auto-tag -> generate ->
lands in dance schedule, garments row has user_paid/ownerUserId/
appearanceDescriptor), and — via a second server pointed at a mock H3
that always fails submission — the async refund path, redelivered
twice to prove it's exactly-once.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

createCheckoutSession() is the seam (dev-plan-4.md §1.2 item 4): with
no STRIPE_SECRET_KEY set — no real test-mode key exists yet, the user
said "先做一个 mock，我明天再给你真实测试的 key" — POST
/api/credits/checkout returns a same-origin /api/credits/mock-checkout
URL that completes the topup itself, standing in for "redirected to
Stripe, paid, redirected back" so the whole checkout -> credited loop
(and T29's UI on top of it) can be built and tested today. With a key
set, it creates a real Stripe Checkout Session via plain REST (fetch,
no stripe SDK — this project has no dependencies at all) — untested
against a live account until the key lands.

POST /api/credits/webhook hand-rolls Stripe's documented HMAC-SHA256
signature scheme and refuses anything unsigned or unverifiable,
including every request while STRIPE_WEBHOOK_SECRET is unset (not just
badly-signed ones). Both the mock and real paths route through one
completeTopup() -> creditLedger.topup() (T23) so Stripe's guaranteed
at-least-once webhook delivery can't double-credit — verified in
credits.test.js by redelivering the same event id twice.

Also added creditBalance to GET /api/auth/me's response (T29's need)
instead of a dedicated balance endpoint — it's the same "logged-in
user's own state" this route already serves, and live.html/dance.html
already poll it after login.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

/api/admin/* accepted only the T6 ADMIN_PASSWORD cookie until now —
MVCP M.1/M.10's stated rule is users.role='admin' + a real session, and
M.2's credit_ledger needs a real admin identity to attribute manual
balance corrections to. isAdminAuthed() now accepts either path (the
ADMIN_PASSWORD channel stays as a fallback so nobody's locked out
before any role='admin' account exists by hand — dev-plan-4.md T30's
explicit requirement). New POST /api/admin/credit/adjust wraps the
new creditLedger.adjust() (db.js), which — unlike spend/refund — takes
either sign of delta and records actorUserId (null over the legacy
ADMIN_PASSWORD channel, which has no per-admin identity to attribute
to).

credit_ledger's actorUserId column needed an idempotent ALTER TABLE
guard (no migration framework exists anywhere in this project) since
the table's CREATE TABLE IF NOT EXISTS already shipped in T23 without
it. Also switched db.js to WAL journal mode — surfaced by two processes
legitimately touching the same data.sqlite at once in this session
(the long-running server + a test run) hitting "database is locked" on
the default rollback-journal mode; worth having before this bites in
production too, not just to unblock local test runs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

Both are pluggable seams (dev-plan-4.md §1.2 items 1-2), same shape as
T20's sendVerificationEmail: a fixed env var gates a real vendor call
that isn't implemented yet (none has been picked), and the no-vendor
path is what actually runs today.

describeGarmentImage() — mode 2 has no admin around to hand-write
garments.appearanceDescriptor the way admin_seed garments do, so it
needs *something* non-empty to fill that field; today that's a fixed
placeholder string, swapped for a real vision-model call once a
vendor's picked.

moderateGarmentImage() — the requirements doc flags image-content
moderation as vendor-TBD but never actually lists it as its own task;
this fills that gap. Every call writes a moderation_log row (new
dressup-store.js export, M.9 schema) regardless of which branch runs,
so the audit trail exists before a real vendor does. Default-permissive
when unconfigured — T2's upload endpoint already enforces the real
trust-boundary checks (magic-byte type check, 8MB cap, EXIF-stripped
re-encode); this only covers the *content* check, which nothing here
can perform without a vendor.

Neither is unit-tested standalone (server.js doesn't export internal
functions, matching sendVerificationEmail's existing precedent) — T27
integration-tests both through the actual upload endpoint.

Also adds pricing.js to the tmpdir file-copy list in every test that
spawns server.js in isolation — server.js now requires it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

credit_ledger (dev-plan-4.md T23; schema M.2) joins users/sessions in
the same SQLite db.js — architecture.md 1.4 named this as the other
half of why SQLite got picked in T18 ("扣积分 + 创建生成任务 + 扣减片段
配额" needs real atomicity, T18 only used the credential-storage half).
spend()/refund()/topup() each read-modify-write users.creditBalance
inside a transaction; spend() refuses to take a balance negative
(INSUFFICIENT_BALANCE) instead of allowing debt, and topup() dedupes
by paymentRef so a Stripe webhook's guaranteed at-least-once delivery
can't double-credit (T24 will rely on this).

pricing_config (M.12) stays a JSON file via a new pricing.js — it's
operator-edited config, not on the atomic spend path, so SQLite would
be over-engineering here; keyed by `key` rather than an id, hence its
own tiny module instead of store.js's createStore. Seeded with
placeholder credit amounts (dev-plan-4.md §1.2 item 3 — real numbers
are still TBD).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

Replaces the single "← 返回直播频道" link (which only pointed at
live.html) with two explicit links — 视频直播间 (live.html) and
跳舞直播间 (dance.html) — each opening in a new tab so the admin
doesn't lose their place in the library table.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

preload="none" left every row's player a plain black box until
clicked, giving no way to eyeball which clip is which without playing
it. Switch to preload="metadata" (browsers paint the first frame once
metadata loads, without playing) so the row itself doubles as a
thumbnail. Load it lazily via IntersectionObserver rather than
src'ing all 361 rows on page load — /lib/video/:id has no local cache
and re-proxies to H3 Console on every hit, so firing that many
requests at once would hammer it; only rows actually scrolled into
view pull their frame.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

Breaks down dressup-dance-room.md 9节第4条 (credit ledger, Stripe
topup, mode 2 paid garment upload — explicitly not mode 3, which is
period 5) into T23-T30 with acceptance criteria, estimates, and a
dependency graph, matching dev-plan.md/dev-plan-2.md/dev-plan-3.md's
format.

Key decisions:
- credit_ledger joins users/sessions in the same SQLite db.js (T18) —
  architecture.md 1.4 flagged this atomicity requirement explicitly,
  this is the other half of why SQLite got picked in period 3.
  pricing_config stays a JSON file (store.js) since it's not on that
  hot atomic path.
- Flags a real doc inconsistency: architecture.md's diagram labels
  fal.ai integration "period 5", but dressup-dance-room.md §8 item 10
  and §9 item 4 both say mode 2's fal.ai path belongs in period 4.
  Resolved in favor of the more specific/recent requirements doc.
- Flags an uncovered gap: §5 references an image-moderation vendor
  "TBD, see §8" but §8 has no matching item for it — added as an open
  question here (§1.2).
- Three genuinely external blockers (image moderation vendor, vision
  model vendor for auto-tagging, real Stripe API keys) are each
  designed around with a pluggable interface (same pattern as T20's
  sendVerificationEmail) so building isn't blocked on vendor picks —
  except the Stripe key itself, which only the user can supply.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

The modal (previous commit) meant an extra click and a popup just to
see the clip. Swap it for a native <video controls preload="none">
directly in the 预览 column — preload="none" keeps the 361-row table
from firing off thumbnails for every row on load, and clicking the
player's own play button starts it right there, no dialog involved.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

Reuses the existing nickname-modal/.nickname-box comic-panel look (a
new .auth-error line and a plain-text auth-link-btn are the only new
CSS) rather than inventing a second visual language. A "登录" topbar
button opens the modal (email/password, toggle between login/
register, cancel); once logged in it becomes "<nickname or email
prefix> · 退出".

Entirely optional, same as T19-T21 designed it: the modal's only
trigger is that one button, nothing forces it open, and free browsing/
voting keeps working on the plain viewer_uid cookie exactly as before.
Manually verified end to end against the real running server (Chrome):
register auto-logs in, an existing viewer_nickname cookie bound onto
the new account and shown in the button, logout reverts the UI.

auth-ui.test.js is a structural check (id/getElementById consistency,
all four /api/auth/* endpoints wired, modal starts hidden) since no
DOM/browser tooling is available to `node --test` here to render the
pages for a full interaction test.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Browsing a clip previously meant opening /lib/video/:id in a new tab
via the raw address link. Add a 预览 button per row that opens a
native <dialog> with an inline <video> player instead — closes on
Esc, backdrop click, or its own close button, and clears the src on
close so playback/buffering stops.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

live.html and dance.html already have independent scheduling pools
(architecture.md 2.1), distinguished by clips' channel field, but
admin.html rendered everything as one flat table with no way to tell
the two apart or scope edits to one room. Add a 视频直播间/跳舞直播间
tab switcher that filters the table by channel, lets manual adds pick
which room they land in, and lets existing rows be reclassified via
the edit form's new channel select (backed by server.js's existing
channel support on POST/PATCH /api/admin/library, committed in e96d689
as part of an unrelated concurrent session's work).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DUiYs6UjxDMkfvnjtsKFo

T20: register now also creates a kind='email_verify' session (24h TTL)
and calls sendVerificationEmail() — the one pluggable seam for a real
provider once one's chosen (dev-plan-3.md §1 flagged no vendor exists
yet). Outside production the register response carries a devVerifyUrl
so the whole loop is testable without a real inbox. GET
/api/auth/verify?token= flips emailVerified and revokes the token so
it can't be replayed.

T21: register reads any existing viewer_uid/viewer_nickname cookie
(live.html/dance.html's plain client-set identity, unrelated to this
session system) and carries it onto the new account as legacyUid/
nickname. Login pushes that legacyUid back onto the browser via
Set-Cookie — even from a clean browser with no viewer_uid cookie at
all — so logging into an account doesn't let someone dodge
per-viewer_uid vote limits by starting a fresh anonymous identity each
time. No history is rewritten, per dev-plan-3.md's explicit scope cut.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

POST /api/auth/register, POST /api/auth/login, POST /api/auth/logout,
and a debug GET /api/auth/me (T19's own acceptance criteria calls for
it explicitly). Passwords hashed with node:crypto's scryptSync (salt
stored alongside the hash, verified with timingSafeEqual) — still zero
new dependencies.

Sessions live in a separate user_session cookie from admin_session
(T6) — the two are unrelated systems, confirmed by a test that a user
session can't unlock /api/admin/*. Login and "email not registered"
return the identical 401 body so the endpoint can't be used to
enumerate registered emails.

Every test file that spawns server.js in an isolated tmpdir now also
copies db.js alongside it (dance-channel/dressup-generate/dressup-crud/
admin-pages-flow/uploads-route .test.js) — server.js requires db.js
unconditionally now, so those child processes were crashing silently
without it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

New db.js opens data.sqlite (node:sqlite's DatabaseSync — a Node 24
built-in, experimental but functional) and creates the users/sessions
tables per dressup-dance-room-mvcp.md M.1/M.10. Zero new npm
dependency: no bcrypt/argon2 (node:crypto's scryptSync covers password
hashing in T19), no better-sqlite3, no package.json needed.

Mirrors store.js's ergonomics (create/get/update, plain JS objects in
and out — booleans and the oauthProviders array marshalled to/from
SQLite's TEXT/INTEGER columns internally) rather than reaching for an
ORM. Exports the openDb/createUsersStore/createSessionsStore factories
alongside a default singleton so tests can point at an isolated tmp
file instead of the real data.sqlite (same pattern
dressup-generate.test.js uses for library.json).

data.sqlite is gitignored under the secrets section, not the "runtime
state" one — unlike library.json it holds real credential material
(password hashes, session tokens), not just regenerable content.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

h3ConsoleFetch blindly JSON.parses the response body regardless of
status code; a momentary non-JSON 500 from H3 Console during polling
(GET /v1/videos/:id) rejected the promise, which the poll loop let
propagate straight to the outer catch — permanently marking the job
"failed" even though the job was still fine on H3's side.

Hit this for real today: a 20-job batch's concurrent polling briefly
500'd H3 Console's HTTP layer, and all 20 jobs got marked failed
locally while every one of them was still queued/running on H3
(confirmed via direct GET /v1/videos/:id against the real console).

Now a failed poll attempt is swallowed and retried on the next tick,
bounded by the same wall-clock deadline as everything else (12aff60).
Only a genuine terminal status (done/error/failed/cancelled) or
deleted_at ends the job.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Breaks down dressup-dance-room.md 9节 phase 3 (dressup-dance-room.md
9节第3条: email login, bind anonymous viewer_uid to an account, no
credits/payment yet) into T18-T22 with acceptance criteria, work
estimates, and a dependency graph, same format as dev-plan.md/
dev-plan-2.md.

Key decisions: users/sessions land in SQLite per architecture.md 1.4's
own trigger condition (credential storage), using Node 24's built-in
node:sqlite + node:crypto scryptSync — zero new npm dependency, no
package.json needed. Flags one real gap the requirements doc's 待验证
list missed: no email-delivery vendor has been chosen, so T20 ships a
pluggable sendVerificationEmail() with a dev-mode bypass rather than
blocking on that decision.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Same hue-recolor approach as the first 10 (dev-plan.md's exit bar
needs >=30 garments given M.7's per-character-garment dedupe), batch
generation for the new 20 already submitted to H3.

Also stops tracking uploads/ — binary image/video content, not a good
git citizen, and this content is explicitly placeholder ("占位旗袍" /
"待替换") the user intends to replace wholesale later. The recipe
(characters/garments/dance-refs.json) stays tracked; the files they
point at don't.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Spawned server.js with cwd: __dirname (the real repo path, not an
isolated copy), so its own test.after() cleanup — rm -rf on
"uploads/" — wiped every real uploaded file in the repo on every
`node --test` run, not just what the test itself created. Discovered
after running the suite several times today silently deleted this
session's real character/garment/dance-ref source images (the
generated dance videos in library.json were unaffected — those proxy
from H3, not served from disk — but admin/dance.html thumbnails broke
until the images were re-uploaded).

Now spawns from an fs.mkdtempSync isolated copy and cleans up only
that tmpdir, matching the pattern already used correctly in
dressup-generate.test.js and dance-channel.test.js.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

The rebuild path for non-edited entries only carried `likes` forward
from the old record; playCount and lastPlayedAt were dropped, so any
clip not yet touched in admin.html had its play stats silently reset
to "never played" on every periodic sync (server.js runs this every
5 min). Now carries both forward when present, and leaves them absent
for a genuinely never-played clip rather than writing a false 0.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Same category as live-state.json/dance-state.json: rewritten by
ingest.js's periodic sync and by every clip play (playCount/
lastPlayedAt), so every commit touching it was just churn from
whoever last had the server running locally. File stays on disk,
just untracked going forward.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Records the 2026-09-02 real-H3 verification of T1-T10 (11 videos / 10
garments, the barefoot reference-video leak finding, the two bugs
found and fixed) and cross-references that T11-T17 (dev-plan-2.md)
landed the same day from a separate session, so the docs don't read
as stale the next time someone opens them.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

…ce refs, 11 generated videos

Real (non-test) content for T1-T10's asset libraries, entered through
the actual admin CRUD flow (admin-characters/garments/dance-refs.html
endpoints) rather than test fixtures: 1 default character, 10 garment
variants, 3 reference dance videos. Batch-generated through T9's
/api/admin/batch-gen against the real H3 Console — 11 dance videos
landed in library.json (one combo generated twice from a dedupe race
before the edited:true fix), all with characterId/garmentId/
refDanceVideoId traceability.

Quality note found while spot-checking: 3 of the 11 clips show bare
feet instead of the character reference's boots, and all three trace
back to the same dance-ref ("轻柔手势舞", sourced from the S1-spike's
control clip) — the reference video's own footwear leaks through
despite the prompt's explicit "weak_reference" instruction. Worth
avoiding barefoot reference footage when curating real dance-refs.

This doesn't yet hit dev-plan.md's phase-1 exit bar of >=30 videos
(that requires 30 garments given the M.7 per-character-garment dedupe
cap; this seeds 10) but is enough real content for dance.html's
wardrobe to have something to show.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

H3's 4 GPUs run one sharded model (H3-CONSOLE.md /v1/status), not 4
independent workers, so a batch of N jobs is served ~serially. The
poll loop's old fixed 200-iteration budget (~1000s at the 5s default
interval) didn't account for queue depth: submitting a 9-job batch hit
this live and 9/11 jobs got marked "generation timed out" locally
while still sitting healthy in H3's queue (queue_position confirmed
via GET /v1/videos/:id). Also treats H3's "cancelled" status as
terminal, matching "error"/"failed".

Recovered the wrongly-failed jobs by resetting them to "generating" in
generation-jobs.json (their h3JobId was already set, so
resumeDressupGenerations() picked them back up without resubmitting to
H3) rather than resubmitting and burning the queue further.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

ingest.js's syncLibrary() only carries a library entry forward as-is
when edited is true; otherwise its periodic auto-sync (every 5 min)
rebuilds the record from the raw H3 job and silently drops
channel/characterId/garmentId/refDanceVideoId. That broke the M.7
dedupe cache and would have let dance clips leak into the regular
live-channel pool once channel got wiped. Caught while running a real
batch generation: the second sync cycle stripped a clip's traceability
fields within 5 minutes of it landing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Backend (server.js):
- T11: dance.html gets its own schedule/queue state machine, persisted to
  dance-state.json (gitignored, same as live-state.json). Per MVCP M.8,
  the schedule stores videoId references rather than inlined clip
  snapshots like live's does, joining back to library.json at read time.
  Generalized pickBestIndexByStatus/extracted pickLeastPlayedClip so both
  channels' schedulers share the same selection logic instead of forking
  it; live's random-fill pool now excludes channel:"dance" clips (and
  vice versa) so the two channels' filler picks stay independent, which
  wasn't true before this (T8's dance clips could have leaked into
  live.html's filler).
- T12: GET /api/dance/wardrobe — public, unauthenticated list of active
  garments.
- T15: POST /api/dance/pick {garmentId, nickname?} — free path, always
  uses the configured default character, reuses submitGeneration (T8/T9)
  whole including its M.7 dedupe cache, then hands the result to
  danceQueue. In-flight generations are reconciled against generationJobs
  on each schedule tick rather than via a promise chain, so a pick
  request survives a server restart the same way T8's own jobs do.
- T17: separate danceViewers map and POST /api/dance/queue/vote/:id, so
  viewer counts and votes don't mix with live.html's.
- SCHEDULE_TICK_MS env var makes both channels' tick interval
  configurable so tests don't wait out a real 2s.

Frontend:
- dance.html (T13/T14/T16): reuses live.html's visual language via
  live.css, adds dance.css for the 9:16 boxed player and wardrobe grid.
  Left column is a 衣柜/传衣服/传人 tab set (only 衣柜 is wired up —
  the other two need accounts/credits, dev-plan-2.md 第三/四期); right
  column shows the queue with vote buttons instead of live.html's chat.
  Age-confirmation gate (5.1节) blocks the page on first visit via a
  cookie, non-dismissable by clicking the backdrop.

Tests: dance-channel.test.js spins up a mock H3 Console (same approach
as dressup-generate.test.js) to exercise wardrobe listing, pick
rejection/happy-path/dedupe, vote, and independent viewer counts
end to end.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Breaks down dev-plan.md's phase-2 scope (dressup-dance-room.md 9节
第2条: dance.html + 免费衣柜模式 + 去重缓存, no paid modes/accounts/
credits yet) into T11-T17 with acceptance criteria, work estimates,
and a dependency graph, same format as dev-plan.md's T1-T10.

Notes that dev-plan.md's own phase-1 exit criterion (batch-generate
>=30 seed videos with real assets) is still outstanding and is an
operational step, not blocking this plan but blocking the wardrobe
actually having content once T11-T17 land.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Deddn3sM3oQnmvqWSMb4y

Fetches characters/garments/dance-refs alongside the library on load
and joins each clip's characterId/garmentId/refDanceVideoId back to
their names, so an operator can see "谁的脸 + 谁的衣服 + 哪条参考视频"
per row (M.7). No composedImageId column — the one-step pipeline
never produces an intermediate composed image.

Extends the dressup-generate.test.js happy-path test to confirm the
join resolves real names, not just matching ids.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

POST /api/admin/batch-gen takes {characterId, garmentIds[],
refDanceVideoIds?[]}, expands to one job per garment (cross-producted
with refDanceVideoIds when given, else one random active dance-ref per
garment like the single-generate default), and submits each through
the same submitGeneration() helper the single POST /api/admin/generate
route now uses — so the M.7 dedupe cache (existing characterId+
garmentId combo) is honored per combo, not just per batch.
GET /api/admin/batch-gen/status?batchId= returns that batch's
generationJobs records for progress polling.

admin-batch-gen.html: pick one character, multiple garments, and
optionally pin specific reference dances; submits the batch, polls
status every 3s into a progress table, and lets failed rows be
retried individually via POST /api/admin/generate. Linked from the
other admin pages' nav.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

generateDanceVideo() takes a queued generationJobs record through
prompt build -> forward character/garment/dance-ref uploads to H3
Console's /v1/assets -> POST /v1/videos -> poll -> push a traced clip
into library.json (characterId/garmentId/refDanceVideoId). Mirrors
generateForPrompt's submit/poll/persist shape but keyed off the new
generationJobs store so a restart resumes any in-flight job by its
h3JobId, same as resumeGenerations() does for the live queue.

POST /api/admin/generate accepts characterId/garmentId (+ optional
refDanceVideoId, else a random active dance-ref is picked) and skips
straight to the cached clip if that character x garment combo was
already generated (M.7 dedupe). GET /api/admin/generate/:id polls job
status.

Tests spin up a mock H3 Console over HTTP so the full submit/poll/land
path runs offline. Also fixes two existing test fixtures
(dressup-crud, admin-pages-flow) that spawn server.js without copying
prompt-template.js — worked until T8 added the first require() of it
into server.js, at which point the spawned server silently failed to
boot.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

buildStage2Prompt() renders MVCP M.15's confirmed one-step six-section
template and enforces the two dynamic risks M.15.1 flagged: caps
appearanceDescriptor/garmentDescriptor at ~40 words each, and
truncates motionDescriptor if it alone would push detailed_description
past H6's 500-word cap (the only placeholder that lands in that
section).

Also fixes the footwear-drift the S1 spike found (model self-selected
shoes when the prompt didn't constrain them) — pins footwear to
<Picture 1> in both subject_definitions and retention_analysis, and
says <Picture 2> doesn't affect it. Propagated the same fix into the
M.15 template in the MVCP doc so the doc and the code don't drift.

Tests check the mechanical M.15.1 items that are checkable from the
rendered string (H1/H5/H6/H9) plus the truncation behavior and the
footwear fix. H13 (reference counts) is a submission-payload concern,
covered by T8's tests instead.

Table + inline edit + add-form pages matching admin.html's existing
conventions, wired to the T3-T5 CRUD API and T2's upload endpoints.
Cross-linked with admin.html and each other in the topbar.

No browser tooling available in this environment to render/click
through these, so admin-pages-flow.test.js exercises the exact API
call sequence each page's JS performs (login -> upload a real file ->
create with the returned URL -> list -> confirm the shape the table
renders), which is where a field-name mismatch would surface.

POST /api/admin/upload-video: mp4 magic-byte sniff (checks the ftyp
box, not offset-0 like images), 50MB cap, no re-encode needed (unlike
images, no EXIF/GPS concern for video). Reuses the multipart parser
and uploads/ layout from T2's image path via a shared placeInUploads
helper.

mountCrud() is a small generic GET-list/POST-create/PATCH/DELETE
router shared across the three entities (same shape, see MVCP
M.3/M.4/M.5) instead of copy-pasting the boilerplate three times.
Each entity fills in its own admin_seed-appropriate defaults on
create. characters additionally enforces the single-default-character
invariant (2 节) across create/update.

HTML admin pages for these come next.

Single shared password (.env ADMIN_PASSWORD) + in-memory HttpOnly
session cookie, no accounts/roles — MVCP M.1/M.10's real account
system supersedes this in period 3. Covers the existing
/api/admin/library/* routes (previously unauthenticated, see
architecture.md 1.2's tech-debt note) plus the new upload endpoint.

admin.html gets a fetch() interceptor that redirects to the new
admin-login.html on any 401 from /api/admin/*, rather than patching
every call site.

POST /api/admin/upload: hand-rolled multipart parser (no deps installed
in this project), real magic-byte sniffing (rejects extension-spoofed
files), 8MB cap, and EXIF/GPS stripping via a sips bmp round-trip
(macOS-native, no dependency — sips's direct jpeg->jpeg re-encode alone
does NOT strip EXIF, only the bmp intermediate does). GET /uploads/*
serves the result with a path-traversal guard.

forwardToH3Assets() is the T7/T8 hook for pushing a saved upload to H3
Console's own POST /v1/assets (found in the S1-S4 spike) — not covered
by the automated suite since it needs a live network call, same
treatment as the spike scripts.

S1: person+garment images directly into ref2va with attribute_transfer
produce correct face/outfit/motion in one call — no separate compose
step needed. S2: reference_video_urls has a real, strong effect on
output motion (A/B tested). S4: H3 Console's own POST /v1/assets
endpoint (undocumented until now) solves asset reachability without
exposing our own uploads/ publicly.

Evidence and scripts in spike/s1-s2-s4-2026-09-02/. Propagated the
one-step design into the requirements doc, MVCP design doc, the
architecture doc, and H3-CONSOLE.md; dev-plan.md's spike section
marked done and its task table updated accordingly.

Generic createStore(filePath) shared by characters.json/garments.json/
dance-refs.json, same full-read/full-write pattern as library.json.
Not yet wired into server.js routes — that's T3-T5.

Duration: fixed 10s (within H3's 4-15s hard constraint), frames=240 @ 24fps.

Prompt: follows the internal H3 prompt-writing methodology already sitting
in the repo (docs/h3skill.md, from a parallel session) — the "all-purpose
reference mode" six-section structure. Character appearance details are
auto-captioned from the Stage1 composed image (new composed_images.
appearanceDescriptor field); dance motion phrasing is admin-authored once
per reference video (new dance_refs.motionDescriptor field), since the
format requires concrete descriptors and forbids "as shown in the picture."

Flagged as needing a pass through h3skill.md's own 22-item mechanical
acceptance checklist before production use, not claimed as fully compliant.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SdtXTsDRz5QWMjvt1HBXLz