@hadoku/game-ui 0.0.0-stage → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/LICENSE +21 -0
  2. package/dist/chrome/HeaderLinks.d.ts +16 -0
  3. package/dist/chrome/HeaderLinks.js +24 -0
  4. package/dist/components/ActionButton.d.ts +9 -0
  5. package/dist/components/ActionButton.js +49 -0
  6. package/dist/components/Avatar.d.ts +43 -0
  7. package/dist/components/Avatar.js +53 -0
  8. package/dist/components/ConnectionBanner.css +77 -0
  9. package/dist/components/ConnectionBanner.d.ts +33 -0
  10. package/dist/components/ConnectionBanner.js +33 -0
  11. package/dist/components/Modal.css +69 -0
  12. package/dist/components/Modal.d.ts +12 -0
  13. package/dist/components/Modal.js +31 -0
  14. package/dist/components/OverPage.d.ts +4 -0
  15. package/dist/components/OverPage.js +21 -0
  16. package/dist/components/Popover.css +58 -0
  17. package/dist/components/Popover.d.ts +20 -0
  18. package/dist/components/Popover.js +63 -0
  19. package/dist/components/RadioCards.css +178 -0
  20. package/dist/components/RadioCards.d.ts +33 -0
  21. package/dist/components/RadioCards.js +41 -0
  22. package/dist/components/StatusPill.d.ts +16 -0
  23. package/dist/components/StatusPill.js +17 -0
  24. package/dist/components/connection-state.d.ts +32 -0
  25. package/dist/components/connection-state.js +5 -0
  26. package/dist/dom.d.ts +17 -0
  27. package/dist/dom.js +57 -0
  28. package/dist/front/Gallery.d.ts +22 -0
  29. package/dist/front/Gallery.js +48 -0
  30. package/dist/front/PatchNotesCard.d.ts +1 -0
  31. package/dist/front/PatchNotesCard.js +59 -0
  32. package/dist/front/camera.d.ts +80 -0
  33. package/dist/front/camera.js +120 -0
  34. package/dist/front/countdown.d.ts +2 -0
  35. package/dist/front/countdown.js +16 -0
  36. package/dist/front/discordChat.d.ts +22 -0
  37. package/dist/front/discordChat.js +52 -0
  38. package/dist/front/gallery.d.ts +13 -0
  39. package/dist/front/gallery.js +32 -0
  40. package/dist/front/gate.d.ts +23 -0
  41. package/dist/front/gate.js +55 -0
  42. package/dist/front/icons.d.ts +43 -0
  43. package/dist/front/icons.js +99 -0
  44. package/dist/front/patchNotes.d.ts +37 -0
  45. package/dist/front/patchNotes.js +95 -0
  46. package/dist/front/polls.d.ts +24 -0
  47. package/dist/front/polls.js +95 -0
  48. package/dist/front/shape.d.ts +11 -0
  49. package/dist/front/shape.js +52 -0
  50. package/dist/http.d.ts +28 -0
  51. package/dist/http.js +83 -0
  52. package/dist/idle.d.ts +2 -0
  53. package/dist/idle.js +7 -0
  54. package/dist/lazy.d.ts +9 -0
  55. package/dist/lazy.js +63 -0
  56. package/dist/popover.d.ts +13 -0
  57. package/dist/popover.js +39 -0
  58. package/dist/registered.d.ts +5 -0
  59. package/dist/registered.js +6 -0
  60. package/dist/restart-notice.d.ts +20 -0
  61. package/dist/restart-notice.js +54 -0
  62. package/dist/room/RoomShell.d.ts +116 -0
  63. package/dist/room/RoomShell.js +222 -0
  64. package/dist/room/SessionPrompt.d.ts +12 -0
  65. package/dist/room/SessionPrompt.js +54 -0
  66. package/dist/room/avatar.d.ts +31 -0
  67. package/dist/room/avatar.js +60 -0
  68. package/dist/room/look.css +13 -0
  69. package/dist/room/look.d.ts +35 -0
  70. package/dist/room/look.js +189 -0
  71. package/dist/room/seatsOpen.d.ts +7 -0
  72. package/dist/room/seatsOpen.js +37 -0
  73. package/dist/room/session.d.ts +26 -0
  74. package/dist/room/session.js +108 -0
  75. package/dist/room/socket-options.d.ts +33 -0
  76. package/dist/room/socket-options.js +40 -0
  77. package/dist/room/tab-id.d.ts +6 -0
  78. package/dist/room/tab-id.js +90 -0
  79. package/dist/room/whoami.d.ts +15 -0
  80. package/dist/room/whoami.js +48 -0
  81. package/dist/rooms/bundle-slot.fixture.d.ts +11 -0
  82. package/dist/rooms/bundle-slot.fixture.js +21 -0
  83. package/dist/rooms/game-clients.d.ts +12 -0
  84. package/dist/rooms/game-clients.js +30 -0
  85. package/dist/rooms/game-setup.d.ts +63 -0
  86. package/dist/rooms/game-setup.js +33 -0
  87. package/dist/rooms/relay-channel.d.ts +29 -0
  88. package/dist/rooms/relay-channel.js +123 -0
  89. package/dist/rooms/screen/RoomShell.d.ts +33 -0
  90. package/dist/rooms/screen/RoomShell.js +7 -0
  91. package/dist/screens/route.d.ts +143 -0
  92. package/dist/screens/route.js +359 -0
  93. package/dist/settings/Settings.d.ts +39 -0
  94. package/dist/settings/Settings.js +131 -0
  95. package/dist/settings/TrimScreen.d.ts +2 -0
  96. package/dist/settings/TrimScreen.js +29 -0
  97. package/dist/settings/settings.css +116 -0
  98. package/dist/settings/siteTrim.d.ts +3 -0
  99. package/dist/settings/siteTrim.js +9 -0
  100. package/dist/settings/trim-screen.css +30 -0
  101. package/dist/sound/index.d.ts +12 -0
  102. package/dist/sound/index.js +34 -0
  103. package/dist/stale-build.d.ts +16 -0
  104. package/dist/stale-build.js +59 -0
  105. package/dist/top-layer.css +22 -0
  106. package/dist/topLayer.d.ts +19 -0
  107. package/dist/topLayer.js +44 -0
  108. package/dist/usage.d.ts +5 -0
  109. package/dist/usage.js +17 -0
  110. package/dist/visible.d.ts +14 -0
  111. package/dist/visible.js +35 -0
  112. package/package.json +42 -4
  113. package/README.md +0 -3
@@ -0,0 +1,222 @@
1
+ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /*
3
+ * Watchparty's room around our table.
4
+ *
5
+ * The operator asked for this three times — *"we gotta connect this to my room
6
+ * and network system"* — and it was blocked, not ignored: until
7
+ * `@wolffm/watchparty-ui@0.39.0` the package exported only a whole-app
8
+ * `mount()` that brought its own React root, its own router, 6.76 MB of bundle
9
+ * and 34 inlined PNGs, and had no slot to put a table in (D17). `RoomChrome`
10
+ * is the export we asked them for, and it lands at **152 KB with zero inlined
11
+ * images**, importing nothing from their chunk graph.
12
+ *
13
+ * ## One chrome per page
14
+ *
15
+ * Their store and socket are module singletons, so a second `RoomChrome` on
16
+ * the same page would share — and then tear down — the first one's connection.
17
+ * That is why this mounts once, in `App`, and never per screen.
18
+ *
19
+ * ## The room is ours; only the art is theirs
20
+ *
21
+ * `roomOrigin` points the chrome's whole room socket — join, roster, identity,
22
+ * chat — at `cardtableOrigin()`: this app's own `/room` namespace
23
+ * (`games/magic/server/src/room/serve.ts`), behind cardtable's member gate, with the
24
+ * roster read from the same presence tracker our seats use. Watchparty never
25
+ * hears of a cardtable room, so it neither counts one nor holds a deploy for
26
+ * it. `serverOrigin` is still watchparty's, for the characters' names and art.
27
+ * Name, picture and character are the account's, resolved by our server.
28
+ *
29
+ * ## Identity comes from the fleet, not from us
30
+ *
31
+ * This used to call cardtable's own `/api/whoami`, which returns `{ userId,
32
+ * tier }` and no display name — so the app rendered `anon`, which is literally
33
+ * `ANON_USER_ID` from `@wolffm/prefs-client`, beside a chat column that knew
34
+ * the operator's real name. That is the same gap that left this app with no
35
+ * theme picker: it was hydrated from `tunnel-loopback-ui`, which scaffolds no
36
+ * UI, and the hydrator's chrome warning only fires for proxy apps
37
+ * (`docs/requests/HADOKU_SITE_GAME_TEMPLATE.md`).
38
+ *
39
+ * `whoami()` from `@wolffm/prefs-client` is the fleet's own, returns `name`,
40
+ * and shares one in-flight promise per page (`globalThis.__hadokuWhoami`) so
41
+ * several apps on a page do not each re-fetch it.
42
+ *
43
+ * We still do NOT invent an identity: if it fails the chrome is not mounted
44
+ * and the table renders alone, because a room that cannot say who you are is
45
+ * worse than no room.
46
+ */
47
+ import { useCallback, useRef, useState } from 'react';
48
+ import { createPortal } from 'react-dom';
49
+ import { RoomChrome } from '@wolffm/watchparty-ui/room-chrome';
50
+ import '@wolffm/watchparty-ui/room-chrome.css';
51
+ import { useHadokuTheme } from '@wolffm/themes';
52
+ import { ROOM_ID_RE } from '@wolffm/platform-wire/room-feed';
53
+ import { appId } from '@wolffm/ui-shell/app-id';
54
+ import { useRoomFrame } from '@wolffm/ui-shell/chrome/shell';
55
+ // The watchparty seam's two data answers — which origin serves their sprites,
56
+ // and which character this viewer picked — live in one module with the bundle
57
+ // evidence beside them. `watchpartyOrigin` used to be a private function here;
58
+ // it moved because `avatarSquareUrl` needs the same string and two derivations
59
+ // of one origin is how the chrome and the faces come to disagree about it.
60
+ import { watchpartyOrigin } from "./avatar.js";
61
+ import { useWhoami } from "./whoami.js";
62
+ /**
63
+ * The page's resolved theme, handed to the chrome as-is.
64
+ *
65
+ * ## Why the two disagreed, diagnosed rather than assumed (w20 §E)
66
+ *
67
+ * `RoomChrome` takes an optional `theme` prop. Left unset — which is what this
68
+ * file did until w20 — it resolves its OWN default from ITS OWN internal
69
+ * store, entirely independent of `HadokuThemeRoot` (quoted in full below).
70
+ * Measured live (a stub-`whoami` build served
71
+ * locally, `#/match/…`, no saved theme in either storage): the page resolved
72
+ * `data-theme="light"` on `.cardtable-chrome` while `.wp-room-chrome` sat at
73
+ * `data-theme="dark"` — two independent defaults, not a shared one that drifted.
74
+ * Passing our theme through removes the second default entirely; they cannot
75
+ * disagree once there is only one source.
76
+ *
77
+ * ## Why this casts instead of validating (w22 §G, found by hadoku_site)
78
+ *
79
+ * This used to filter through `THEMES` and answer `undefined` for a name it did
80
+ * not recognise. `undefined` is not a neutral value here — it is precisely what
81
+ * sends the chrome back to that second default, so the filter reintroduced the
82
+ * split-theme bug in the one case it was written to protect against.
83
+ *
84
+ * That case is unreachable today: one `@wolffm/themes` install (5.8.6), and
85
+ * `room-chrome.d.ts:3` imports `Theme` from it, so there is a single union. But
86
+ * watchparty-ui takes themes as a regular **dependency** (`^5.8.5`), not a peer,
87
+ * so a host outside that range resolves a second nested copy and two distinct
88
+ * unions exist. There, passing an unrecognised name through is strictly better
89
+ * than dropping it, and the shipped code is why — read out of the installed
90
+ * bundle, its fallback is:
91
+ *
92
+ * function Do(e) { if (e) return e; const t = ze().theme;
93
+ * return t && tn.includes(t) ? t : "dark"; }
94
+ *
95
+ * The prop is honoured VERBATIM, unvalidated, and lands on `data-theme` of the
96
+ * chrome's own `aside.wp-room-chrome` — never on the host document. Only a
97
+ * FALSY prop makes the chrome consult its own store and then hard-code `dark`.
98
+ * So an unknown name resolves against whichever `[data-theme=…]` palettes are
99
+ * loaded and otherwise falls to a neutral light base; `undefined` resolves to
100
+ * an actively wrong `dark`. `undefined` is the only value that cannot be
101
+ * ignored.
102
+ *
103
+ * Corrected against the installed bundle rather than taken on trust: the §G brief said
104
+ * `room-chrome.css` "styles only its own light/dark internals". It does not —
105
+ * it ships all 18 `[data-theme=…]` blocks under `@scope (.wp-room-chrome)`,
106
+ * with `:scope,:scope[data-theme=light]` as the fallback rule, the same 18 the
107
+ * host's `@wolffm/themes/src/style.css` carries unscoped. That changes the
108
+ * reason, not the fix: what makes the pass-through work is `if (e) return e`,
109
+ * not a gap in the chrome's own palettes.
110
+ *
111
+ * ## The trap, for whoever edits this next
112
+ *
113
+ * The cast is load-bearing twice, and only one half announces itself.
114
+ * `theme={theme}` fails typecheck — TS2322, because `useHadokuTheme()` types
115
+ * `theme` as `string` (the picker's families are data-driven) — which is what
116
+ * sends people looking for a validator in the first place. But
117
+ * `theme={filtered ?? undefined}` compiles cleanly and IS the defect. Only the
118
+ * type error is loud; the wrong fix is silent. The `Theme` return type below,
119
+ * with no `| undefined`, is what makes the silent half loud too: a re-added
120
+ * `?? undefined` stops compiling here instead of shipping a chrome that resolves
121
+ * its own theme.
122
+ */
123
+ export function watchpartyTheme(theme) {
124
+ // Total by construction — every name reaches the chrome, including one this
125
+ // install's union does not know. Never narrow this to `Theme | undefined`.
126
+ return theme;
127
+ }
128
+ /**
129
+ * A room key for one of our pods or matches, or null when the id is not a
130
+ * shape watchparty will accept.
131
+ *
132
+ * Null means "render the table with no room" — never a guessed or coerced key,
133
+ * because two ids that collapse to the same key would put two unrelated groups
134
+ * in one room, and they would each see the other's chat.
135
+ */
136
+ export function roomKeyFor(id) {
137
+ return ROOM_ID_RE.test(id) ? `${appId()}-${id}` : null;
138
+ }
139
+ /**
140
+ * This app's own origin, on whatever host serves this page — never
141
+ * hardcoded, so PPE (built with `CARDTABLE_BASE_PREFIX=/cardtable-ppe`) gets
142
+ * PPE's own origin rather than prod's. The same derivation
143
+ * `room/socket-options.ts`'s `defaultSocketPath` uses for the draft socket's
144
+ * path, here producing an ORIGIN string: `RoomChrome` derives its socket
145
+ * path, `/cardtable[-ppe]/socket.io/`, from its pathname, so passing the
146
+ * bare base is enough — no `roomSocketPath` override needed.
147
+ */
148
+ export function cardtableOrigin() {
149
+ const base = import.meta.env?.BASE_URL;
150
+ const prefix = typeof base === 'string' && base !== '' ? base : '/';
151
+ return `${globalThis.location.origin}${prefix}`.replace(/\/$/, '');
152
+ }
153
+ /**
154
+ * Wraps `children` in watchparty's room when there is a room to be in.
155
+ *
156
+ * Renders the children alone when there is no room id or when whoami failed. A
157
+ * table without chat is a degraded room; a table that will not draw because
158
+ * chat is down is an outage.
159
+ *
160
+ * The children mount ONCE, whatever the chrome does around them. Remounted, they
161
+ * lose everything they hold and open their sockets again: a match opened from a
162
+ * link joined on two sockets and hung up the first, and when the hang-up beat the
163
+ * second join the server saw the seat leave (`e2e/w69-name-card.spec.ts`, "nobody
164
+ * disconnected"); a joiner's room screen, drawn before its join and wrapped once
165
+ * the join let the chat in (`App.tsx`'s `useJoined`), dropped an open Room
166
+ * settings and connected its draft socket twice (`e2e/w83b-draft-rope.spec.ts`).
167
+ * So they are rendered through a portal from one place in this component's tree,
168
+ * into a node that moves into the chrome when it draws and out when it goes. That
169
+ * node and the slot holding it are both `.chrome-slot` (`display: contents`), and
170
+ * the chrome's rules for its content's own child reach through exactly those two
171
+ * (`@hadoku/ui-shell`'s `chrome.css`). While whoami is in flight on a room's route, before they have
172
+ * first mounted, they wait for it: their first frame is already inside.
173
+ */
174
+ export function RoomShell({ roomId, collapsible = true, inert = false, children, }) {
175
+ const who = useWhoami();
176
+ // Always inside `AppChrome`'s `HadokuThemeRoot` — see chrome/AppChrome.tsx,
177
+ // which mounts this component. `useHadokuTheme()` throws with no provider
178
+ // on purpose (a silent fallback is the bug this removes), so a caller that
179
+ // ever renders `RoomShell` outside the theme root takes that throw here.
180
+ const { theme } = useHadokuTheme();
181
+ const key = roomId === null ? null : roomKeyFor(roomId);
182
+ const roomFrameRef = useRoomFrame();
183
+ const [host] = useState(createHost);
184
+ const mounted = useRef(false);
185
+ const waiting = key !== null && who === 'pending';
186
+ if (!waiting)
187
+ mounted.current = true;
188
+ // One keyed element in every branch below, so React keeps the children; last, so the slot has
189
+ // taken the host in before their layout effects run.
190
+ const content = mounted.current ? createPortal(children, host, 'content') : null;
191
+ if (waiting)
192
+ return _jsx(_Fragment, { children: content });
193
+ if (key === null || who === null || who === 'pending')
194
+ return (_jsxs(_Fragment, { children: [_jsx(Slot, { host: host }, "bare"), content] }));
195
+ return (
196
+ /*
197
+ * Wave 89 §B: `data-collapsible` is this element's own, not a prop
198
+ * `RoomChrome` takes — `RoomChromeProps` (the installed `room-chrome.d.ts`)
199
+ * has nothing for a host to read or set the chat column's open state from
200
+ * outside. `live.css`'s portrait rules key the chat-sheet behaviour off
201
+ * this attribute rather than off `collapsible` turning the chrome's own
202
+ * "Hide chat" button on or off, because `collapsible` is a prop value, not
203
+ * a selector a stylesheet in another file can see — and only present at
204
+ * all when `collapsible` is true, i.e. a match route (`App.tsx`'s
205
+ * `route.kind !== 'room'`), never the room lobby (Settled 10: "the room
206
+ * lobby is unchanged").
207
+ */
208
+ _jsxs(_Fragment, { children: [_jsx("div", { className: "room-shell", "data-testid": "room-shell", "data-collapsible": collapsible ? '' : undefined, inert: inert || undefined, children: _jsxs(RoomChrome, { roomKey: key, serverOrigin: watchpartyOrigin(), roomOrigin: cardtableOrigin(), userType: who.tier, userId: who.userId, theme: watchpartyTheme(theme), collapsible: collapsible, children: [_jsx(Slot, { host: host }), _jsx("span", { hidden: true, ref: roomFrameRef })] }) }, "chrome"), content] }));
209
+ }
210
+ /** The node {@link RoomShell}'s children are drawn into: it takes no box of its own, so they lay out as its parent's. */
211
+ function createHost() {
212
+ const host = document.createElement('div');
213
+ host.className = 'chrome-slot';
214
+ return host;
215
+ }
216
+ /** Where the children stand now: the host is moved in when this mounts. */
217
+ function Slot({ host }) {
218
+ const place = useCallback((slot) => {
219
+ slot?.appendChild(host);
220
+ }, [host]);
221
+ return _jsx("div", { ref: place, className: "chrome-slot" });
222
+ }
@@ -0,0 +1,12 @@
1
+ import { type SessionState } from './session.js';
2
+ /** This tab's claim on `room`, for as long as the screen is in it. Null: no room, nothing to claim. */
3
+ export declare function useRoomSession(room: string | null, screen: string): {
4
+ state: SessionState | null;
5
+ take: () => void;
6
+ };
7
+ /** Whether the screen stands down for a question: it is not drawn, and the page behind is inert. */
8
+ export declare function sessionBlocks(state: SessionState | null): boolean;
9
+ export declare function SessionPrompt({ state, take }: {
10
+ state: SessionState | null;
11
+ take: () => void;
12
+ }): import("react").JSX.Element | null;
@@ -0,0 +1,54 @@
1
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /*
3
+ * The two questions of one live tab per player per room (`./session.ts`), each a modal over the dimmed,
4
+ * inert page that cannot be put away, only answered:
5
+ *
6
+ * - `held`: this account plays the room in another live tab. Yes takes it from there; no goes back
7
+ * to the front page without joining.
8
+ * - `taken`: another tab took it. The one answer takes it back, the same way.
9
+ *
10
+ * A question and its answers, nothing else (the operator's rule: no explanatory text).
11
+ */
12
+ import { useEffect, useState } from 'react';
13
+ import { ActionButton } from "../components/ActionButton.js";
14
+ import { Modal } from "../components/Modal.js";
15
+ import { navigate } from "../screens/route.js";
16
+ import { roomSession } from "./session.js";
17
+ /** This tab's claim on `room`, for as long as the screen is in it. Null: no room, nothing to claim. */
18
+ export function useRoomSession(room, screen) {
19
+ const [session, setSession] = useState(null);
20
+ const [state, setState] = useState(null);
21
+ useEffect(() => {
22
+ if (room === null) {
23
+ setSession(null);
24
+ setState(null);
25
+ return;
26
+ }
27
+ const opened = roomSession(room);
28
+ setSession(opened);
29
+ setState(opened.state());
30
+ const stop = opened.subscribe(() => setState(opened.state()));
31
+ return () => {
32
+ stop();
33
+ opened.close();
34
+ };
35
+ }, [room]);
36
+ // Another kind of screen in the same room (the room → its match): whether this account plays here may have changed.
37
+ useEffect(() => {
38
+ session?.reclaim();
39
+ }, [session, screen]);
40
+ return { state, take: () => session?.take() };
41
+ }
42
+ /** Whether the screen stands down for a question: it is not drawn, and the page behind is inert. */
43
+ export function sessionBlocks(state) {
44
+ return state === 'held' || state === 'taken';
45
+ }
46
+ export function SessionPrompt({ state, take }) {
47
+ if (state === 'held') {
48
+ return (_jsx(Modal, { title: "Play here instead?", testId: "session-ask", actions: _jsxs(_Fragment, { children: [_jsx(ActionButton, { action: "session-no", className: "button", "data-testid": "session-ask-no", onPress: () => navigate({ kind: 'lobby' }), children: "No" }), _jsx(ActionButton, { action: "session-yes", className: "button ct-modal__primary", "data-testid": "session-ask-yes", onPress: take, children: "Yes" })] }) }));
49
+ }
50
+ if (state === 'taken') {
51
+ return (_jsx(Modal, { title: "Open in another tab", testId: "session-taken", actions: _jsx(ActionButton, { action: "session-take-back", className: "button ct-modal__primary", "data-testid": "session-take-back", onPress: take, children: "Play here" }) }));
52
+ }
53
+ return null;
54
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Watchparty's server, on whatever origin serves this page. In production that
3
+ * is `https://hadoku.me/watchparty` — both apps sit behind the same edge — and
4
+ * their chrome talks to their server. It is derived rather than hardcoded so a
5
+ * page served from anywhere else never reaches production: the draft e2e runs
6
+ * against a local server, and the hardcoded origin sent its browsers to
7
+ * hadoku.me for sprites, whoami and client-log (8d71303, caught by that spec's
8
+ * off-host guard).
9
+ */
10
+ export declare function watchpartyOrigin(): string;
11
+ /**
12
+ * The image that draws one avatar, or null when there is nothing to draw.
13
+ *
14
+ * `square_<id>.png` under the chrome's own `serverOrigin` is watchparty's own
15
+ * media convention, not ours: every id in `@wolffm/rooms-protocol`'s `AVATAR_POOL` has
16
+ * one (checked 2026-11-01), and `@wolffm/prefs-client/avatar`'s `ResolvedAvatar`
17
+ * carries no URL for a `sprite` source by design — "the app that owns the art
18
+ * … owns its URL and revision" (its own `.d.ts`). So this stays the one place
19
+ * that builds the path, same-origin by construction (no host written down,
20
+ * so a local e2e stays local).
21
+ *
22
+ * Null for an absent, blank or over-long id rather than a URL ending
23
+ * `square_.png`, which is a 404 drawn as a broken image where the caller wanted
24
+ * a fallback. That is the client half of the rule the server states in
25
+ * `room/lobby.ts`'s `avatarIdOf`: an empty string must never become a request.
26
+ * The origin is read only when there is an id, so a face with none renders
27
+ * where there is no `location` (`react-dom/server`).
28
+ */
29
+ export declare function avatarSquareUrl(avatarId: string | null | undefined, origin?: string): string | null;
30
+ /** The same two-state reading the server does, so a client cannot send what it would refuse. */
31
+ export declare function normalizeAvatarId(v: unknown): string | null;
@@ -0,0 +1,60 @@
1
+ /*
2
+ * The viewer's watchparty avatar: where the id comes from, and what draws it.
3
+ *
4
+ * The operator: *"i noticed you're still not pulling in the watchparty selected
5
+ * avatars. why not?"* Because the last hop was never wired. `avatarId` is on
6
+ * `@wolffm/rooms-protocol`'s `RosterIdentity` and `LocalIdentity`, and
7
+ * `packages/room-store`'s `SerializedMember` has persisted it through our own
8
+ * room snapshot since it was written — but nothing in `apps/server/src` or
9
+ * `apps/ui/src` had ever read it, so it reached our room store and was dropped
10
+ * before it reached a seat.
11
+ *
12
+ * This file is the client half: "what URL draws it", the ONLY place that is
13
+ * spelled. Which character a member wears is their account's, resolved by the
14
+ * server (`packages/game-server/src/people.ts`'s `applyPerson`); prefs-api draws and
15
+ * keeps one for an account that never picked, so it is the same in every app.
16
+ */
17
+ import { AVATAR_ID_MAX } from '@wolffm/platform-wire/look';
18
+ /**
19
+ * Watchparty's server, on whatever origin serves this page. In production that
20
+ * is `https://hadoku.me/watchparty` — both apps sit behind the same edge — and
21
+ * their chrome talks to their server. It is derived rather than hardcoded so a
22
+ * page served from anywhere else never reaches production: the draft e2e runs
23
+ * against a local server, and the hardcoded origin sent its browsers to
24
+ * hadoku.me for sprites, whoami and client-log (8d71303, caught by that spec's
25
+ * off-host guard).
26
+ */
27
+ export function watchpartyOrigin() {
28
+ return `${globalThis.location.origin}/watchparty`;
29
+ }
30
+ /**
31
+ * The image that draws one avatar, or null when there is nothing to draw.
32
+ *
33
+ * `square_<id>.png` under the chrome's own `serverOrigin` is watchparty's own
34
+ * media convention, not ours: every id in `@wolffm/rooms-protocol`'s `AVATAR_POOL` has
35
+ * one (checked 2026-11-01), and `@wolffm/prefs-client/avatar`'s `ResolvedAvatar`
36
+ * carries no URL for a `sprite` source by design — "the app that owns the art
37
+ * … owns its URL and revision" (its own `.d.ts`). So this stays the one place
38
+ * that builds the path, same-origin by construction (no host written down,
39
+ * so a local e2e stays local).
40
+ *
41
+ * Null for an absent, blank or over-long id rather than a URL ending
42
+ * `square_.png`, which is a 404 drawn as a broken image where the caller wanted
43
+ * a fallback. That is the client half of the rule the server states in
44
+ * `room/lobby.ts`'s `avatarIdOf`: an empty string must never become a request.
45
+ * The origin is read only when there is an id, so a face with none renders
46
+ * where there is no `location` (`react-dom/server`).
47
+ */
48
+ export function avatarSquareUrl(avatarId, origin) {
49
+ const id = normalizeAvatarId(avatarId);
50
+ if (id === null)
51
+ return null;
52
+ return `${(origin ?? watchpartyOrigin()).replace(/\/$/, '')}/media/sprites/square_${encodeURIComponent(id)}.png`;
53
+ }
54
+ /** The same two-state reading the server does, so a client cannot send what it would refuse. */
55
+ export function normalizeAvatarId(v) {
56
+ if (typeof v !== 'string')
57
+ return null;
58
+ const id = v.trim();
59
+ return id === '' || id.length > AVATAR_ID_MAX ? null : id;
60
+ }
@@ -0,0 +1,13 @@
1
+ /*
2
+ * The overlay a person wears, laid over their face (`look.tsx`'s `FaceDecor`).
3
+ * The fleet's `.hc-av` box is `position: relative` in the flow; this one is
4
+ * taken out of it and placed on the face it follows, so the face's own layout
5
+ * is untouched. Its `left`, `top` and `--hc-sz` are set from that face.
6
+ * Two classes, because the fleet's sheet is injected after ours and its own
7
+ * `.hc-av { position: relative }` would otherwise win and leave it in the flow.
8
+ */
9
+ .hc-av.face-decor {
10
+ position: absolute;
11
+ z-index: 1;
12
+ pointer-events: none;
13
+ }
@@ -0,0 +1,35 @@
1
+ import { type CSSProperties } from 'react';
2
+ import { type AvatarCosmetics } from '@wolffm/prefs-client/cosmetics';
3
+ import type { Look } from '@wolffm/platform-wire/look';
4
+ import './look.css';
5
+ /** What a person wears, safe to draw, or undefined. */
6
+ export declare function wornOf(look: Look | undefined): AvatarCosmetics | undefined;
7
+ /** `--hc-base` for someone, re-rendering once their colour is known. */
8
+ export declare function usePersonColour(avatarId: string | undefined, look: Look | undefined): CSSProperties;
9
+ /**
10
+ * The overlay a person wears, laid over the face drawn just before it.
11
+ *
12
+ * Every face keeps its own `<img>` and the class that sizes it, so the overlay
13
+ * is placed on that image rather than wrapped around it: a hidden anchor marks
14
+ * the face, and the overlay is drawn beside it or outside its clipping ring
15
+ * (`decorHost`). The renderer places an overlay against a box of `--hc-sz`
16
+ * pixels; that is set from the face's laid-out size, again whenever it or the
17
+ * box around it resizes.
18
+ */
19
+ export declare const FaceDecor: import("react").NamedExoticComponent<{
20
+ avatarId: string | undefined;
21
+ look: Look | undefined;
22
+ }>;
23
+ /**
24
+ * A person's name, wearing their name effect, gradient and font. Someone who
25
+ * wears none of the three is plain text, in the colour and weight around it.
26
+ */
27
+ export declare const PlayerName: import("react").NamedExoticComponent<{
28
+ name: string;
29
+ face: {
30
+ id: string | null | undefined;
31
+ look?: Look | undefined;
32
+ };
33
+ className?: string;
34
+ testId?: string;
35
+ }>;
@@ -0,0 +1,189 @@
1
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /*
3
+ * A person's look on our screens: their avatar picture, the overlay they wear
4
+ * on it, and their name's effect, gradient and font.
5
+ *
6
+ * The operator, 2026-11-05: *"picture/character are the same thing and all
7
+ * over the entire site it's the same avatar. we must display all
8
+ * customizations everywhere."* So this is drawn with the fleet's own renderer
9
+ * (`@wolffm/prefs-client/cosmetics`), the one watchparty's chat and the avatar
10
+ * dialog use, and every face (`components/Avatar.tsx`) and name
11
+ * (`PlayerName`) goes through it.
12
+ *
13
+ * - What someone wears arrives with their face, resolved by our server
14
+ * (`packages/game-server/src/people.ts`), and is cleaned again here (`cleanWorn`), so
15
+ * an id this build's catalogue does not know draws nothing.
16
+ * - Colours derive from the person's own colour in `--hc-base`: their
17
+ * picture's average colour, else their character's (watchparty's
18
+ * `/api/characters`, the table they publish for code outside watchparty).
19
+ * - Every loop pauses while it is off screen (`hc-idle`): a standings list
20
+ * would otherwise keep animating rows nobody can see.
21
+ */
22
+ import { memo, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
23
+ import { createPortal } from 'react-dom';
24
+ import { cleanWorn, decorHtml, nameHtml, onPictureColour, pictureColour, readPictureColour } from '@wolffm/prefs-client/cosmetics';
25
+ import { watchpartyOrigin } from "./avatar.js";
26
+ import './look.css';
27
+ /** What a person wears, safe to draw, or undefined. */
28
+ export function wornOf(look) {
29
+ return cleanWorn(look?.cosmetics);
30
+ }
31
+ // ── Pausing what is off screen ───────────────────────────────────────────────
32
+ let observer = null;
33
+ function idleWhenHidden(el) {
34
+ if (typeof IntersectionObserver === 'undefined')
35
+ return () => undefined;
36
+ observer ??= new IntersectionObserver((entries) => {
37
+ for (const e of entries)
38
+ e.target.classList.toggle('hc-idle', !e.isIntersecting);
39
+ }, { rootMargin: '64px' });
40
+ observer.observe(el);
41
+ return () => observer?.unobserve(el);
42
+ }
43
+ // ── A person's colour ────────────────────────────────────────────────────────
44
+ const characterColours = new Map();
45
+ const colourListeners = new Set();
46
+ let charactersAsked = false;
47
+ /** Watchparty's character table, asked once per page: its `color` is the character's name colour. */
48
+ function askCharacters() {
49
+ if (charactersAsked || typeof fetch === 'undefined')
50
+ return;
51
+ charactersAsked = true;
52
+ fetch(`${watchpartyOrigin()}/api/characters`).then(async (res) => {
53
+ if (!res.ok)
54
+ return;
55
+ const table = (await res.json());
56
+ for (const set of table.sets ?? []) {
57
+ for (const c of set.characters ?? [])
58
+ if (typeof c.id === 'string' && typeof c.color === 'string')
59
+ characterColours.set(c.id, c.color);
60
+ }
61
+ for (const l of [...colourListeners])
62
+ l();
63
+ },
64
+ // No table: names draw in the colour around them (`--hc-base` falls back to currentColor).
65
+ () => undefined);
66
+ }
67
+ function onColours(listener) {
68
+ colourListeners.add(listener);
69
+ const stopPicture = onPictureColour(listener);
70
+ return () => {
71
+ colourListeners.delete(listener);
72
+ stopPicture();
73
+ };
74
+ }
75
+ /** Their picture's colour once it has been read, else their character's; undefined when neither is known. */
76
+ function personColour(avatarId, picture) {
77
+ return (picture === undefined ? null : pictureColour(picture)) ?? (avatarId === undefined ? undefined : characterColours.get(avatarId));
78
+ }
79
+ /** `--hc-base` for someone, re-rendering once their colour is known. */
80
+ export function usePersonColour(avatarId, look) {
81
+ const picture = look?.picture;
82
+ useEffect(() => {
83
+ askCharacters();
84
+ if (picture !== undefined)
85
+ void readPictureColour(picture);
86
+ }, [picture]);
87
+ const colour = useSyncExternalStore(onColours, () => personColour(avatarId, picture), () => undefined);
88
+ return colour === undefined ? {} : { '--hc-base': colour };
89
+ }
90
+ // ── The overlay on a face ────────────────────────────────────────────────────
91
+ /**
92
+ * Where an overlay is drawn: beside its face, or, when the face sits in a
93
+ * face-sized box that clips (a seat's round ring), just outside that box, so
94
+ * a crown above the head is not cut off. A clipping box larger than the face
95
+ * (a scrolling list, a card) is the page's own edge and is kept.
96
+ */
97
+ function decorHost(face) {
98
+ const size = Math.max(face.getBoundingClientRect().width, 1);
99
+ let host = null;
100
+ for (let box = face.parentElement; box !== null && box.parentElement !== null; box = box.parentElement) {
101
+ if (box.getBoundingClientRect().width > size * 1.6)
102
+ break;
103
+ const style = getComputedStyle(box);
104
+ // A face that turns away (a coin's sides) hides what it holds: its overlay stays inside it.
105
+ if (style.backfaceVisibility === 'hidden')
106
+ break;
107
+ if ([style.overflow, style.overflowX, style.overflowY].some((o) => o !== '' && o !== 'visible'))
108
+ host = box.parentElement;
109
+ }
110
+ return host;
111
+ }
112
+ /**
113
+ * The overlay a person wears, laid over the face drawn just before it.
114
+ *
115
+ * Every face keeps its own `<img>` and the class that sizes it, so the overlay
116
+ * is placed on that image rather than wrapped around it: a hidden anchor marks
117
+ * the face, and the overlay is drawn beside it or outside its clipping ring
118
+ * (`decorHost`). The renderer places an overlay against a box of `--hc-sz`
119
+ * pixels; that is set from the face's laid-out size, again whenever it or the
120
+ * box around it resizes.
121
+ */
122
+ export const FaceDecor = memo(function FaceDecor({ avatarId, look }) {
123
+ const anchor = useRef(null);
124
+ const ref = useRef(null);
125
+ const [host, setHost] = useState(null);
126
+ const worn = wornOf(look);
127
+ const html = worn?.overlay === undefined ? '' : decorHtml(worn);
128
+ const colour = usePersonColour(avatarId, look);
129
+ useLayoutEffect(() => {
130
+ const face = anchor.current?.previousElementSibling;
131
+ setHost(html === '' || !(face instanceof Element) ? null : decorHost(face));
132
+ }, [html]);
133
+ useLayoutEffect(() => {
134
+ const el = ref.current;
135
+ const face = anchor.current?.previousElementSibling;
136
+ if (el === null || !(face instanceof Element))
137
+ return;
138
+ // From boxes, not `offsetLeft`: the fallback mark is an SVG, which has none,
139
+ // and a scaled board (UI scale, the portrait fit) scales both boxes alike.
140
+ const fit = () => {
141
+ const parent = el.offsetParent instanceof HTMLElement ? el.offsetParent : document.documentElement;
142
+ const pr = parent.getBoundingClientRect();
143
+ const fr = face.getBoundingClientRect();
144
+ const scale = parent.offsetWidth > 0 ? pr.width / parent.offsetWidth : 1;
145
+ if (scale <= 0)
146
+ return;
147
+ el.style.left = `${(fr.left - pr.left) / scale - parent.clientLeft + parent.scrollLeft}px`;
148
+ el.style.top = `${(fr.top - pr.top) / scale - parent.clientTop + parent.scrollTop}px`;
149
+ el.style.setProperty('--hc-sz', `${fr.width / scale}px`);
150
+ };
151
+ fit();
152
+ const stopIdle = idleWhenHidden(el);
153
+ if (typeof ResizeObserver === 'undefined')
154
+ return stopIdle;
155
+ const ro = new ResizeObserver(fit);
156
+ ro.observe(face);
157
+ if (face.parentElement !== null)
158
+ ro.observe(face.parentElement);
159
+ if (host !== null)
160
+ ro.observe(host);
161
+ return () => {
162
+ ro.disconnect();
163
+ stopIdle();
164
+ };
165
+ }, [html, host]);
166
+ if (html === '')
167
+ return null;
168
+ const decor = _jsx("span", { ref: ref, className: "hc-av face-decor", style: colour, "aria-hidden": "true", "data-testid": "face-decor", dangerouslySetInnerHTML: { __html: html } });
169
+ return (_jsxs(_Fragment, { children: [_jsx("span", { ref: anchor, hidden: true }), host === null ? decor : createPortal(decor, host)] }));
170
+ });
171
+ // ── A name ───────────────────────────────────────────────────────────────────
172
+ /**
173
+ * A person's name, wearing their name effect, gradient and font. Someone who
174
+ * wears none of the three is plain text, in the colour and weight around it.
175
+ */
176
+ export const PlayerName = memo(function PlayerName({ name, face, className, testId }) {
177
+ const ref = useRef(null);
178
+ const worn = wornOf(face.look);
179
+ const dressed = worn !== undefined && (worn.effect !== undefined || worn.gradient !== undefined || worn.font !== undefined);
180
+ const colour = usePersonColour(face.id ?? undefined, face.look);
181
+ useEffect(() => {
182
+ const el = ref.current;
183
+ return el === null || !dressed ? undefined : idleWhenHidden(el);
184
+ }, [dressed]);
185
+ if (!dressed) {
186
+ return className === undefined && testId === undefined ? (_jsx(_Fragment, { children: name })) : (_jsx("span", { className: className, "data-testid": testId, children: name }));
187
+ }
188
+ return _jsx("span", { ref: ref, className: className, style: colour, "data-testid": testId, "data-dressed": "", dangerouslySetInnerHTML: { __html: nameHtml(name, worn) } });
189
+ });
@@ -0,0 +1,7 @@
1
+ /** When a room whose event starts at `scheduledFor` (ISO) opens its seats, in ms, while that is after `now`; null once open or for a room no event made. */
2
+ export declare function seatsShutUntil(scheduledFor: string | null, now: number): number | null;
3
+ /** `seatsShutUntil` against the browser's clock, redrawn each tick until the seats open. */
4
+ export declare function useSeatsShutUntil(scheduledFor: string | null): number | null;
5
+ export declare function SeatsOpenNote({ opensAt }: {
6
+ opensAt: number;
7
+ }): import("react").JSX.Element;