svelte-kit-vice/docs/process/continue-proof-of-human-2026-07.md

ProofOfHuman — handoff (2026-07-14, rev 2)

Anti-bot human-verification component, re-architected from a single drag-to-target widget into an orchestrator + pluggable challenges. Three challenge surfaces now ship: PathTrace, RotateAlign (compass skin) and Clock (the cuckoo-clock skin over the same RotateAlign engine) — landed this session. Read this top-to-bottom to resume cold.

⚠️ Concurrency warning — READ FIRST

Another Claude session is working on palabras / words in this SAME repo and committing to the SAME branch (alpha-0.1-sec-dom) concurrently. The git index (.git/index) is shared, so a plain git add … then git commit can be clobbered mid-way (it happened: their 5b1e228a words(align) reset my staged index). Mitigations: stage + commit ATOMICALLY in one command (git reset && git add … && git commit … && git push); never leave files staged across tool calls; consider working on a separate branch. Never touch words/**, palabras/**, chronos/**, web/routes/alpha/**, rt.css, src/uix/eidos/lib/recipes/base.ts (chronos hunk) — stage explicit paths only.

The architecture (shipped)

• ProofOfHuman = orchestrator. Interaction- and purpose-agnostic. Owns the abstract stages (idle → active → verifying → verified / failed), the evaluable verdict (commit-confirm / fail / cancel), live-region announcements and the onSolve(telemetry) handoff. Network-agnostic (the app verifies with a single-use server nonce and drives status). Per-stage animation lives in consumer slots (stageIdle … stageFailed).
• ProofOfHumanChallengeHost — the context a challenge uses to report up: stage · locked · begin() · solve(telemetry) · cancel().
• A challenge = its own component + morfo, consumes ProofOfHumanProvider.require(), produces telemetry, drives the lifecycle. Swapping the challenge never touches the orchestrator. Each challenge is a headless soma triplet (Provider + two parts) that eidos SKINS.
• Telemetry (ProofOfHumanTelemetry, in soma/components/proof-of-human/types.ts): base motion fields + an optional per-challenge block — pathAdherence? (PathTrace) or rotation? (RotateAlign). Add a new block for a new challenge kind.

Shipped challenges

PathTrace — follow a random curved path

• Follow a per-instance random Catmull-Rom curve (pointer OR arrow keys), staying inside a tolerance corridor; progress advances ONLY in-corridor and monotonically. Keyboard yields real signal → no free bypass; a two-key script can't solve it. Skin: envelope token traced to a carrier pigeon.
• Files: morfo/components/path-trace.ts, soma/components/path-trace/ (curve.ts is pure geometry), sema/components/path-trace.ts, eidos/components/proof-of-human/path-trace.svelte (+ .css).

RotateAlign — rotate to a random bearing ← the clock's engine

• Rotate a needle onto a per-instance random bearing and HOLD it steady until it settles (pointer OR arrow keys). Composes Gesture.rotate(). Settle-to-lock via uix.timers (each move reschedules → a wiggle never locks, stillness locks). Detent tick fires handle-drag every 30°. Telemetry: rotation block (totalRotationDeg / maxAngularVelDegMs / overshootCount / finalErrorDeg / settleMs). Unwrapped visualAngle drives the needle transform so a CSS transition never spins the long way round the 360→0 seam.
• Knobs: toleranceDeg (8) · settleMs (450) · stepDeg (6) · seed.
• Files: morfo/components/rotate-align.ts, soma/components/rotate-align/, sema/components/rotate-align.ts, eidos/components/proof-of-human/rotate-align.svelte (+ .css).
• Current skin = compass: dial + ticks + N/E/S/O + a MAILBOX target (the pigeon's destination) + a magnetically-settling needle. Exposed as ProofOfHuman.RotateAlign.

Demo

web/routes/uix/components/proof-of-human/+page.svelte — a challenge switcher (PathTrace | RotateAlign), per-challenge controls, the carrier-pigeon narrative over the stage slots, telemetry table (pathAdherence + rotation rows).

Verified

• Tests (server + real chromium): 25/25 — both morfos, both providers (each: pointer AND arrow trace completes with real signal; a two-key script can't solve; Escape cancels), curve geometry.
• End-to-end in real Chrome — both challenges reach verified from a genuine solve; incomplete/trivial attempts don't; difficulty visibly reshapes the PathTrace curve; the compass renders + the needle settles.
• Type-check clean across the component; component:audit PASS (the two harness false positives D-1.5/D-4.3 are documented in the eidos README).

SHIPPED this session: the CLOCK skin (cuckoo)

Built exactly to the locked mockup spec below. What landed:

• eidos/components/proof-of-human/clock.svelte + clock.css — composes the SAME soma parts (RotateAlign.Provider/Dial/Needle); exported as ProofOfHuman.Clock (+ ClockProps in types.ts, mirroring RotateAlignProps). clock.svelte imports rotate-align.css too (shared skin box + needle behavior).
• One engine knob added (declared deviation from "engine unchanged" — the design needs hour-aligned targets): soma RotateAlignProviderProps.targetSnapDeg? quantizes the random bearing (buildTarget). The Clock passes 30 → 12 possible hours; a free bearing would miss the marked hour by up to 15° > the 8° tolerance ~47% of the time. Unit-tested (% 30 === 0 across seeds + random).
• Face: ring + 11 hour ticks (12 = the house) + numbers at 3/6/9 + a target-hour badge (accent circle + number, --color-content-on-solid text) at r=68; the badge REPLACES the 3/6/9 numeral when it lands there; hour 12 special-cases to under the sill (y=58). Hand = tapered pointer with counterweight and hub (content-primary), tip r=58 meeting the badge edge.
• Cuckoo sequence (all CSS in clock.css, keyed on [data-proof-of-human][data-state='verified'], every @keyframes annotated /* functional: */ per R-4.5): doors swing ±118° (0.5s) → pigeon (FRONT-ON: two eyes, beak down holding the letter) rises to peek — one 3.4s keyframe timeline (wait 13% → peek 26% → hold 62% → fly 100%, per-segment easing via animation-timing-function inside keyframes) — body stays occluded by a clipPath whose bottom edge = the sill top ($props.id() for the clip id) → wings appear + flap (2.1s delay = the 62% mark) and the bird rises, shrinks, fades IN FRONT of the roof (pigeon drawn last). Reduced-motion: doors + peek static, no flight. Pigeon palette = the demo bird's literal hexes (annotated literal:); house/face = theme tokens; roof + badge flip to fulfill on verified.
• Demo: third chip (PathTrace | RotateAlign | Clock) reusing the rotate knobs; clock-specific idle instruction; for the Clock the demo's success card is DELAYED 3.3s (proof-of-human:cuckoo timer) so the cuckoo dispatch plays uncovered, and the demo's corner stage-pigeon is suppressed in BOTH the verifying and verified slots (the cuckoo IS the pigeon — user caught the verifying one still showing).

The original CLOCK spec (kept for reference)

The user's favourite skin. It reuses the RotateAlign engine unchanged — only the visual is new. The design is locked via a mockup that went through several iterations; reproduce it faithfully (the mockup is not visible in a new session, so the spec is here).

Concept

A cuckoo clock. "Set the clock to N" → the hand ticks to the hours (the RotateAlign detents), and on settle the clock's little doors swing open and a pigeon leans out FRONT-ON with the letter in its beak, then flies off (the cuckoo → a messenger pigeon). This unifies the whole component's narrative: the compass points to the mailbox, the clock dispatches the pigeon — one messenger.

Mapping to the engine

• The needle = the clock HAND. stepDeg per arrow. toleranceDeg/settleMs as-is.
• The detents (every 30°) = the hours; the handle-drag tick per detent = the clock ticking. Consider snapping the hand to whole hours in the skin.
• The target bearing (Dial snippet targetAngle) = the target HOUR (targetHour = round(targetAngle/30), 0→12). Mark it on the face.
• On the orchestrator data-state='verified' → run the cuckoo reaction.

Visual + animation spec (from the mockup)

• Face: ring + 12 hour ticks + numbers at 3/6/9 (12 is replaced by the cuckoo house). A target marker at the target hour.
• Cuckoo house at the TOP (12 o'clock): a little roof (triangle) over a dark doorway interior, two doors (left/right) that SWING open, and a sill bar in front. Doors swing via transform-box: fill-box; transform-origin: left/right center; transform: rotate(±118deg).
• The pigeon must be FRONT-FACING (this was the sticking point — a side-profile bird was rejected twice). Head-on: a round head with TWO eyes, a small beak pointing DOWN holding a little envelope, an oval body, and two wings that are hidden until flight.
• Sequence on verified: doors swing open (~0.5s) → pigeon PEEKS — head + letter emerge ABOVE the sill while the body stays hidden BEHIND the sill (occlusion: draw the pigeon before the sill; the sill bar sits in front of the lower body) → hold ~0.8s → FLY — the wings appear + flap (rotate, alternate) and the bird rises, shrinks and fades up-and-away (front-on flying-toward-you).
• CRITICAL SVG gotcha (bit me 3×): an SVG element that carries a transform attribute for positioning — CSS transform OVERRIDES it entirely (jumps to the origin). Wrap it: OUTER group keeps the position (transform="translate(x y)" attr), INNER group does the CSS animation (transform-box: fill-box). Same fix the compass mailbox uses.
• Doctrine: the pigeon-fly is bespoke CONTENT animation (its own CSS/rAF via eidos.dom/eidos.timers, like the demo pigeon), NOT an --event recipe @keyframes (R-4.5). The verdict flourish itself is the generic commit motion signature. Timers via uix.timers, never raw setTimeout.

How it was built

All four steps above were executed as specced (the hand stays continuous — no visual snap-to-hour: with stepDeg 6 a 30° visual quantum would kill the feedback per press; the TARGET is what snaps). Verified end-to-end in real Chrome: idle face, live door-swing/peek/fly frames (light + dark), telemetry → verified from genuine arrow signal, component:audit PASS (144/144), tests 81/81 green across the poh scopes, type-check clean on touched files.

Verification-env gotchas

• The in-app Browser pane / a backgrounded Chrome tab report visibilityState: hidden, which freezes rAF → dom.measure never fires (PathTrace curve never builds). A computer screenshot foregrounds the tab. RotateAlign has no rAF dependency (target computed in the constructor).
• Background throttling also stretches setTimeout to ≥1s — a JS solve loop with 30ms waits blows the 45s CDP budget in a backgrounded tab. Screenshot first (foregrounds), then run the script, ideally in ONE browser_batch.
• To FILM a one-shot CSS choreography: solve + zooms in the SAME browser_batch (inter-call latency between separate tool calls eats a 3.4s window), or freeze poses with a debug <style> override animation: … paused !important; animation-delay: -1.5s !important (restart it via animation: none + reflow first — redeclaring the same animation-name does NOT restart it).
• Screenshots on the in-app Browser pane hang; use the claude-in-chrome MCP (real Chrome). Screenshot perms are per tab-group — a fresh tab may need re-grant.
• form_input (with a ref) triggers Svelte bind:value; coordinate-typing is unreliable. Filling via the native value-setter + input event also works.
• Driving a trace from JS: precompute the input sequence (arrows / pointer deltas / rotation) — the reactive DOM doesn't update synchronously inside a JS loop, so read state BEFORE, compute the whole sequence, dispatch. Add real waits so durationMs > 150 passes the demo's auto scorer.
• Dev server: npm run dev (picks a free port; was on 5174). The Edit-hook may warn that "another chat's dev server is running" — start your own if the Browser tools can't reach it.

Commits (alpha-0.1-sec-dom)

• 1f7018b9 re-architecture (orchestrator + PathTrace, 40 files)
• f897bdb6 component:audit fixes · e1b5dec8 / 139cc2b6 docs
• e2a20b95 PathTrace pointer test
• c4f5b080 RotateAlign (engine + compass skin + demo switcher + difficulty fix)
• (this session) Clock — cuckoo skin + targetSnapDeg + demo card delay + eidos README challenge list.

COMPONENT COMPLETE (2026-07-14, closing pass)

The documentation debt was cleared in the closing pass: soma rotate-align README written (anti-bot core, parts, props incl. targetSnapDeg, keyboard, telemetry rotation block, sema events, compass+clock skins); eidos README links all three morfos/challenges; the demo's Live snippet, API tab, morfo tab and Services tab now follow the SELECTED challenge (the two challenge morfos share handle-* event names, so the sema panel/tables swap instead of merging — merged lists would collide on keyed {#each}). The soma orchestrator README also gained "Adding a new challenge" — the 8-step recipe (morfo → langs → soma provider → telemetry block → sema pack → eidos skin → tests → demo+gates) with the non-negotiable invariants, distilled from how RotateAlign/Clock were actually built.

Still open / deferred (not blocking, out of component scope)

• Foreign blocker: morfo:check / perm:check / morfo:vocabulary crash repo-wide on text-blur.ts (task_05ed143d) — not ours; tests + browser cover the smoke.
• Future (v2 roadmap): more challenges (hold-to-confirm, audio/cognitive for non-motor a11y); server-driven difficulty by risk score.