Janady13/thatstupidcomputer / apps/web/src/animation/stage/CharacterStage.tsx

1import { useEffect, useId, useRef, useState, type KeyboardEvent, type PointerEvent } from 'react'; 2import { Character } from '../rive/Character'; 3import { useMedia } from '../core/useMedia'; 4import type { ActionName, CharacterSlug } from '../mobile/types'; 5import { beginDrag, boundsFor, cancelDrag, createStage, dragTo, endDrag, hasStageWork, issueCommand, normalizedPosition, resizeStage, stageStatus, tickStage, type StageCommand, type EngineStatus, type Point } from './engine.mjs'; 6import './stage.css'; 7 8export type StageReason = 'command' | 'drag' | 'drop' | 'complete' | 'resize' | 'pause' | 'ready'; 9export interface StageStatus extends Omit<EngineStatus, 'pose'> { pose: ActionName; reason: StageReason; ready: boolean; paused: boolean } 10export interface CharacterStageProps { 11 character: CharacterSlug; 12 action?: ActionName; 13 paused?: boolean; 14 attitudeEnabled?: boolean; 15 command?: StageCommand; 16 replay?: number; 17 onStatus?: (status: StageStatus) => void; 18 /** Observe user-generated stage intents. Do not echo these back as commands. */ 19 onCommand?: (command: StageCommand) => void; 20 onError?: (error: unknown) => void; 21 label?: string; 22 className?: string; 23} 24type PointerSession = { id: number; offset: Point; lastTime: number }; 25type Controls = { submit(command: StageCommand, internal?: boolean): void; startPointer(event: PointerEvent<HTMLButtonElement>): void; movePointer(event: PointerEvent<HTMLButtonElement>): void; finishPointer(cancelled?: boolean): void; keyboard(event: KeyboardEvent<HTMLButtonElement>): void; tap(event: PointerEvent<HTMLDivElement>): void; sync(): void; notify(reason: StageReason): void; loaded(character: CharacterSlug, failed?: boolean, error?: unknown): void }; 26 27/** One clipped stage; one finite translation loop; the Character owns its own joints. */ 28export function CharacterStage(props: CharacterStageProps) { 29 const stageRef = useRef<HTMLDivElement>(null); 30 const actorRef = useRef<HTMLDivElement>(null); 31 const handleRef = useRef<HTMLButtonElement>(null); 32 const latest = useRef(props); latest.current = props; 33 const engine = useRef(createStage()); 34 const controls = useRef<Controls | null>(null); 35 const pointer = useRef<PointerSession | null>(null); 36 const pending = useRef<StageCommand | null>(null); 37 const seen = useRef<string | number | null>(null); 38 const previousCharacter = useRef(props.character); 39 const reduced = useMedia('(prefers-reduced-motion: reduce)', true); 40 const restrictions = useRef({ paused: !!props.paused, reduced, visible: false, intersects: false, measured: false, characterReady: null as CharacterSlug | null }); 41 const [restricted, setRestricted] = useState(true); 42 const [motionPose, setMotionPose] = useState<ActionName | null>(null); 43 const [hidden, setHidden] = useState(false); 44 const [grabbed, setGrabbed] = useState(false); 45 const [poseReplay, setPoseReplay] = useState(0); 46 const helpId = useId(); 47 48 useEffect(() => { 49 const stage = stageRef.current, actor = actorRef.current, handle = handleRef.current; 50 if (!stage || !actor || !handle) return; 51 let frame = 0, last = 0, disposed = false, serial = 0; 52 let currentPose: ActionName | null = null; 53 let currentHidden = false; 54 let keyboardGrab = false; 55 const ready = () => restrictions.current.measured && restrictions.current.characterReady === latest.current.character; 56 const blocked = () => { const value = restrictions.current; return value.paused || value.reduced || !value.visible || !value.intersects || !ready(); }; 57 const notify = (reason: StageReason) => { 58 if (disposed) return; 59 const status = stageStatus(engine.current); 60 latest.current.onStatus?.({ ...status, pose: status.pose || latest.current.action || 'Idle', reason, ready: ready(), paused: blocked() }); 61 }; 62 const paint = () => { 63 const state = engine.current; 64 actor.style.left = '0px'; actor.style.top = '0px'; actor.style.bottom = 'auto'; 65 actor.style.transform = `translate3d(${state.x.toFixed(3)}px, ${state.y.toFixed(3)}px, 0)`; 66 actor.style.visibility = state.visible ? 'visible' : 'hidden'; 67 stage.dataset.phase = state.phase; 68 actor.dataset.x = state.x.toFixed(3); actor.dataset.y = state.y.toFixed(3); 69 const pose = state.active?.pose || null; 70 actor.dataset.action = pose || latest.current.action || 'Idle'; 71 if (pose !== currentPose) { currentPose = pose; setMotionPose(pose); } 72 if (!state.visible !== currentHidden) { currentHidden = !state.visible; setHidden(currentHidden); } 73 }; 74 const stopFrame = () => { if (frame) cancelAnimationFrame(frame); frame = 0; last = 0; }; 75 const schedule = () => { if (!disposed && !frame && !blocked() && hasStageWork(engine.current)) frame = requestAnimationFrame(advance); }; 76 const advance = (now: number) => { 77 frame = 0; 78 if (disposed || blocked()) { last = 0; return; } 79 const dt = last ? (now - last) / 1000 : 0; 80 last = now; 81 const oldRevision = engine.current.revision; 82 engine.current = tickStage(engine.current, dt); 83 paint(); 84 if (engine.current.revision !== oldRevision) notify(engine.current.active ? 'command' : 'complete'); 85 if (hasStageWork(engine.current)) schedule(); else last = 0; 86 }; 87 const releaseCapture = () => { 88 const session = pointer.current; pointer.current = null; 89 if (session) { try { if (handle.hasPointerCapture(session.id)) handle.releasePointerCapture(session.id); } catch { /* Detached/cancelled capture is already released. */ } } 90 }; 91 const finishPointer = (cancelled = false) => { 92 if (!pointer.current && !keyboardGrab && engine.current.phase !== 'dragging') return; 93 engine.current = cancelled ? cancelDrag(engine.current) : endDrag(engine.current); 94 keyboardGrab = false; releaseCapture(); setGrabbed(false); 95 paint(); notify('drop'); schedule(); 96 }; 97 const submit = (command: StageCommand, internal = false) => { 98 if (disposed) return; 99 if (internal) latest.current.onCommand?.(command); 100 pending.current = null; 101 if (command.kind !== 'cancel' && blocked()) { pending.current = command; notify('pause'); return; } 102 keyboardGrab = false; stopFrame(); 103 engine.current = issueCommand(engine.current, command); 104 releaseCapture(); setGrabbed(false); 105 setPoseReplay(value => value + 1); 106 paint(); notify('command'); schedule(); 107 }; 108 const internal = (kind: StageCommand['kind'], target?: StageCommand['target']) => submit({ id: `stage-${helpId}-${++serial}`, kind, ...(target === undefined ? {} : { target }) }, true); 109 const sync = () => { 110 if (disposed) return; 111 const halted = blocked(); setRestricted(halted); 112 if (halted) { stopFrame(); finishPointer(true); } 113 else if (pending.current) { const command = pending.current; pending.current = null; submit(command); } 114 else schedule(); 115 notify('pause'); 116 }; 117 const measure = () => { 118 if (disposed) return; 119 if (pointer.current || keyboardGrab) finishPointer(true); 120 const width = stage.clientWidth, height = stage.clientHeight; 121 const actorWidth = actor.offsetWidth, actorHeight = actor.offsetHeight; 122 engine.current = resizeStage(engine.current, { width, height, actorWidth, actorHeight }); 123 restrictions.current.measured = width > 0 && height > 0 && actorWidth > 0 && actorHeight > 0; 124 paint(); notify('resize'); sync(); 125 }; 126 controls.current = { 127 submit, finishPointer, sync, notify, 128 loaded(character, failed = false, error) { 129 if (character !== latest.current.character) return; 130 restrictions.current.characterReady = failed ? null : character; 131 sync(); notify('ready'); 132 if (failed) latest.current.onError?.(error); 133 }, 134 startPointer(event) { 135 if (blocked() || !event.isPrimary || event.button !== 0 || pointer.current) return; 136 event.preventDefault(); event.stopPropagation(); 137 try { handle.setPointerCapture(event.pointerId); } catch { return; } 138 handle.focus({ preventScroll: true }); 139 pending.current = null; keyboardGrab = false; stopFrame(); 140 engine.current = beginDrag(engine.current); 141 const rect = stage.getBoundingClientRect(); 142 pointer.current = { id: event.pointerId, offset: { x: event.clientX - rect.left - engine.current.x, y: event.clientY - rect.top - engine.current.y }, lastTime: event.timeStamp }; 143 setGrabbed(true); paint(); notify('drag'); 144 }, 145 movePointer(event) { 146 const session = pointer.current; 147 if (!session || session.id !== event.pointerId || blocked()) return; 148 event.preventDefault(); event.stopPropagation(); 149 const rect = stage.getBoundingClientRect(); 150 engine.current = dragTo(engine.current, { x: event.clientX - rect.left - session.offset.x, y: event.clientY - rect.top - session.offset.y }, (event.timeStamp - session.lastTime) / 1000); 151 session.lastTime = event.timeStamp; paint(); 152 }, 153 keyboard(event) { 154 if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', ' ', 'Escape'].includes(event.key)) return; 155 event.preventDefault(); event.stopPropagation(); 156 if (event.key === 'Escape') { finishPointer(true); return; } 157 if (blocked()) return; 158 if (event.key === ' ') { 159 if (event.repeat) return; 160 if (keyboardGrab) finishPointer(); 161 else { pending.current = null; stopFrame(); engine.current = beginDrag(engine.current); keyboardGrab = true; setGrabbed(true); paint(); notify('drag'); } 162 return; 163 } 164 if (keyboardGrab && event.key.startsWith('Arrow')) { 165 const amount = event.shiftKey ? 8 : 24; 166 const point = { x: engine.current.x + (event.key === 'ArrowLeft' ? -amount : event.key === 'ArrowRight' ? amount : 0), y: engine.current.y + (event.key === 'ArrowUp' ? -amount : event.key === 'ArrowDown' ? amount : 0) }; 167 engine.current = dragTo(engine.current, point); paint(); return; 168 } 169 if (keyboardGrab) finishPointer(true); 170 if (event.key === 'Home' || event.key === 'ArrowDown') internal('home'); 171 else if (event.key === 'End') internal('walkTo', 1); 172 else if (event.key === 'ArrowUp') internal('jump'); 173 else internal('walkTo', normalizedPosition(engine.current).x + (event.key === 'ArrowLeft' ? -0.12 : 0.12)); 174 }, 175 tap(event) { 176 if (event.target !== stage || blocked() || !event.isPrimary || event.button !== 0) return; 177 const bounds = boundsFor(engine.current.size), rect = stage.getBoundingClientRect(); 178 const span = bounds.maxX - bounds.minX; 179 internal('walkTo', span > 0 ? (event.clientX - rect.left - engine.current.size.actorWidth / 2 - bounds.minX) / span : 0.5); 180 }, 181 }; 182 const visibility = () => { restrictions.current.visible = document.visibilityState !== 'hidden'; sync(); }; 183 const blur = () => finishPointer(true); 184 restrictions.current.visible = document.visibilityState !== 'hidden'; 185 let resizeObserver: ResizeObserver | undefined; 186 let intersection: IntersectionObserver | undefined; 187 if (typeof ResizeObserver === 'function') { resizeObserver = new ResizeObserver(measure); resizeObserver.observe(stage); resizeObserver.observe(actor); } 188 else window.addEventListener('resize', measure); 189 if (typeof IntersectionObserver === 'function') { 190 intersection = new IntersectionObserver(entries => { restrictions.current.intersects = entries.some(entry => entry.isIntersecting); sync(); }, { threshold: 0.01 }); 191 intersection.observe(stage); 192 } else restrictions.current.intersects = true; 193 document.addEventListener('visibilitychange', visibility); window.addEventListener('blur', blur); 194 measure(); 195 return () => { disposed = true; controls.current = null; stopFrame(); releaseCapture(); resizeObserver?.disconnect(); intersection?.disconnect(); document.removeEventListener('visibilitychange', visibility); window.removeEventListener('resize', measure); window.removeEventListener('blur', blur); }; 196 }, [helpId]); 197 198 useEffect(() => { restrictions.current.paused = !!props.paused; restrictions.current.reduced = reduced; controls.current?.sync(); }, [props.paused, reduced]); 199 useEffect(() => { 200 if (previousCharacter.current === props.character) return; 201 previousCharacter.current = props.character; 202 restrictions.current.characterReady = null; 203 controls.current?.finishPointer(true); 204 controls.current?.submit({ id: `character-${props.character}`, kind: 'cancel' }); 205 controls.current?.sync(); 206 }, [props.character]); 207 useEffect(() => { 208 if (!props.command || seen.current === props.command.id) return; 209 seen.current = props.command.id; controls.current?.submit(props.command); 210 }, [props.command]); 211 212 const action = motionPose || props.action || 'Idle'; 213 return <div ref={stageRef} className={`tsc-character-stage ${props.className || ''}`} data-testid="character-stage" data-reduced-motion={reduced ? 'true' : 'false'} onPointerUp={event => controls.current?.tap(event)}> 214 <div ref={actorRef} className="tsc-character-stage__actor" data-testid="stage-actor" data-action={action}> 215 <div className="tsc-character-stage__art" aria-hidden="true"> 216 <Character character={props.character} action={action} paused={restricted || hidden} attitudeEnabled={props.attitudeEnabled} replay={poseReplay + (props.replay || 0)} travel={false} onReady={() => controls.current?.loaded(props.character)} onError={error => controls.current?.loaded(props.character, true, error)} /> 217 </div> 218 <button ref={handleRef} type="button" className="tsc-character-stage__handle" data-testid="stage-actor-handle" aria-label={props.label || `Move ${props.character.replaceAll('-', ' ')}`} aria-describedby={helpId} aria-pressed={grabbed} aria-disabled={restricted} tabIndex={hidden ? -1 : 0} onPointerDown={event => controls.current?.startPointer(event)} onPointerMove={event => controls.current?.movePointer(event)} onPointerUp={event => { event.stopPropagation(); if (pointer.current?.id === event.pointerId) controls.current?.finishPointer(); }} onPointerCancel={event => { if (pointer.current?.id === event.pointerId) controls.current?.finishPointer(true); }} onLostPointerCapture={event => { if (pointer.current?.id === event.pointerId) controls.current?.finishPointer(true); }} onKeyDown={event => controls.current?.keyboard(event)} onClick={event => { event.preventDefault(); event.stopPropagation(); }} onBlur={() => controls.current?.finishPointer(true)}> 219 <span className="tsc-stage-sr-only">Move character</span> 220 </button> 221 </div> 222 <span id={helpId} className="tsc-stage-sr-only">Drag the character, or press Space to pick up and drop. Arrow keys move a held character; Shift makes smaller steps. When not held, Left and Right walk, Up jumps, Down or Home returns to center, and End walks right. Escape releases. Movement stops when paused or reduced motion is enabled.</span> 223 </div>; 224} 225