@hadoku/ui-shell 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 (52) hide show
  1. package/LICENSE +21 -0
  2. package/dist/app-id/index.d.ts +4 -0
  3. package/dist/app-id/index.js +14 -0
  4. package/dist/chrome/AppChrome.d.ts +9 -0
  5. package/dist/chrome/AppChrome.js +201 -0
  6. package/dist/chrome/chrome.css +336 -0
  7. package/dist/chrome/index.d.ts +3 -0
  8. package/dist/chrome/index.js +3 -0
  9. package/dist/chrome/matchMedia.d.ts +2 -0
  10. package/dist/chrome/matchMedia.js +51 -0
  11. package/dist/chrome/shell.d.ts +17 -0
  12. package/dist/chrome/shell.js +47 -0
  13. package/dist/chrome/trim.css +334 -0
  14. package/dist/components/Reveal.d.ts +20 -0
  15. package/dist/components/Reveal.js +38 -0
  16. package/dist/components/index.d.ts +1 -0
  17. package/dist/components/index.js +7 -0
  18. package/dist/components/reveal.css +110 -0
  19. package/dist/embed/index.d.ts +1 -0
  20. package/dist/embed/index.js +1 -0
  21. package/dist/embed/styles.d.ts +4 -0
  22. package/dist/embed/styles.js +49 -0
  23. package/dist/motion/index.d.ts +6 -0
  24. package/dist/motion/index.js +8 -0
  25. package/dist/settings/index.d.ts +1 -0
  26. package/dist/settings/index.js +1 -0
  27. package/dist/settings/ui-scale.d.ts +45 -0
  28. package/dist/settings/ui-scale.js +142 -0
  29. package/dist/sound/GainSlider.d.ts +6 -0
  30. package/dist/sound/GainSlider.js +15 -0
  31. package/dist/sound/index.d.ts +65 -0
  32. package/dist/sound/index.js +204 -0
  33. package/dist/sound/mix.d.ts +69 -0
  34. package/dist/sound/mix.js +117 -0
  35. package/dist/sound/mixer.d.ts +37 -0
  36. package/dist/sound/mixer.js +301 -0
  37. package/dist/sound/mute.d.ts +62 -0
  38. package/dist/sound/mute.js +250 -0
  39. package/dist/sound/queue.d.ts +32 -0
  40. package/dist/sound/queue.js +80 -0
  41. package/dist/theme/index.d.ts +18 -0
  42. package/dist/theme/index.js +41 -0
  43. package/dist/trim/index.d.ts +2 -0
  44. package/dist/trim/index.js +2 -0
  45. package/dist/trim/siteTrim.d.ts +23 -0
  46. package/dist/trim/siteTrim.js +91 -0
  47. package/dist/trim/trim.d.ts +72 -0
  48. package/dist/trim/trim.js +63 -0
  49. package/dist/usage/index.d.ts +32 -0
  50. package/dist/usage/index.js +84 -0
  51. package/package.json +70 -4
  52. package/README.md +0 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 hadoku-cardtable contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,4 @@
1
+ export declare function configureShell(config: {
2
+ appId: string;
3
+ }): void;
4
+ export declare function appId(): string;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The one identifier a game states about itself to the shell. Every storage
3
+ * key, custom event name and chat prefix the shell writes is built from it, so
4
+ * the values a game wrote before the shell existed do not change.
5
+ */
6
+ let configured;
7
+ export function configureShell(config) {
8
+ configured = config.appId;
9
+ }
10
+ export function appId() {
11
+ if (configured === undefined)
12
+ throw new Error('ui-shell: configureShell was never called');
13
+ return configured;
14
+ }
@@ -0,0 +1,9 @@
1
+ import { type ReactNode } from 'react';
2
+ import './chrome.css';
3
+ import './trim.css';
4
+ export interface AppChromeProps {
5
+ /** The shared header, as `App` authored it. Rendered inside the theme root. */
6
+ header: ReactNode;
7
+ children: ReactNode;
8
+ }
9
+ export declare function AppChrome({ header, children }: AppChromeProps): import("react").JSX.Element;
@@ -0,0 +1,201 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /*
3
+ * The app's chrome: everything above the screens, and the boundary anything
4
+ * that replaces it has to honour.
5
+ *
6
+ * cardtable was hydrated from `templates/tunnel-loopback-ui`, which scaffolds
7
+ * no UI at all, and the hydrator's "NO HADOKU CHROME" warning is gated on
8
+ * `isProxy && !isContained` — so a loopback-ui app never sees it. Nothing in
9
+ * the pipeline ever handed this app `HadokuThemeRoot` or `AppHeader`, and the
10
+ * operator found the two symptoms in one viewport: no theme selector anywhere,
11
+ * beside a watchparty chat column that WAS themed because `RoomChrome` reads
12
+ * `@wolffm/themes` itself. `docs/requests/HADOKU_SITE_GAME_TEMPLATE.md` is the
13
+ * ask that the next loopback-ui app not repeat it.
14
+ *
15
+ * This file is the fix, and it is deliberately thin: everything it renders
16
+ * belongs to the platform.
17
+ *
18
+ * =====================================================================
19
+ * THE CONTRACT — read this before swapping this file for the template
20
+ * =====================================================================
21
+ *
22
+ * hadoku_site's `templates/game` is meant to replace this hand-written
23
+ * wrapper. That swap is the whole reason this section exists: the boundary
24
+ * it has to land on is written down here, so the replacement is a diff
25
+ * against a stated contract rather than archaeology over six files. Wave 18
26
+ * §D is where it was written; the audit behind "known gaps" below was run
27
+ * then, and the line numbers are from that reading.
28
+ *
29
+ * ## The swap, done: it was a LAYOUT diff, not a migration (wave 21 §A)
30
+ *
31
+ * The operator, 2026-09-25: *"would be much better to use the child frontend
32
+ * header that is minted with the proper standard child app header that
33
+ * hadoku_site uses"*. Read against the reference before anything was designed
34
+ * — `~/srv/hadoku_site/templates/game/apps/ui/src/`, `templates/ui-app` and
35
+ * `templates/tunnel-contained` — and the answer was that we ALREADY mount the
36
+ * fleet's header: the same `AppHeader` from `@wolffm/task-ui-components`, with
37
+ * the same `@wolffm/task-ui-components/app-header.css` import, inside the same
38
+ * `HadokuThemeRoot`. There is no other header in the fleet to migrate to.
39
+ *
40
+ * What differed was where the header SITS. The fleet's header stylesheet sets
41
+ * no left/right/top spacing on purpose; in `templates/ui-app` and
42
+ * `templates/tunnel-contained` the buffer comes from the content wrapper the
43
+ * header is rendered inside (`padding: 2rem`). `templates/game` is the one
44
+ * template that renders `<AppHeader>` OUTSIDE that wrapper, and this app was
45
+ * written against `templates/game` — which is exactly why the bar had no edge
46
+ * buffer. `chrome.css` now carries that one rule, with the provenance of its
47
+ * value; see its `.cardtable-chrome > .app-header` block.
48
+ *
49
+ * ## The division
50
+ *
51
+ * `main.tsx` mounts and nothing else. `App.tsx` routes and authors the
52
+ * header. `chrome/` frames — it owns everything ABOVE the screens and
53
+ * nothing below them, and it knows what a pod, a room or a match is only in
54
+ * the sense that `chrome.css` has to name their dark roots (see the island
55
+ * seam below). Screens own themselves.
56
+ *
57
+ * ## What `chrome/` guarantees to whatever it wraps
58
+ *
59
+ * 1. **The theme tokens are defined and resolved.** `--color-*` and
60
+ * `--hdk-*` exist by the time a child paints, and `data-theme` is on
61
+ * <html> AND mirrored onto `.cardtable-chrome`, so a descendant resolves
62
+ * light/dark from either. `screens/screens.css` paints entirely from
63
+ * these. This is the designed channel between chrome and screens and the
64
+ * only one — there is no theme value on any prop today.
65
+ * 1. **`color-scheme` matches the theme**, via `data-dark-theme` on the
66
+ * container, so native controls and scrollbars are not the wrong half.
67
+ * 2. **One content region, and it grows.** `.cardtable-chrome__content` is a
68
+ * column flex item with `min-height: 0`, and its DIRECT CHILD is given
69
+ * `flex: 1 1 auto; min-height: 0`. A screen may assume it has the
70
+ * viewport minus the header and may scroll inside it; `screens.css`
71
+ * dropped its own `min-height: 100vh` on the strength of this.
72
+ * 3. **`window.matchMedia` exists** before any child effect runs
73
+ * (`ensureMatchMedia()`, at module load — `matchMedia.ts` has the
74
+ * upstream bug it absorbs). A wrapper that drops it takes the throw in
75
+ * every jsdom test that renders `App`, and in any embedder without the
76
+ * API.
77
+ * 4. **Exactly one chrome per page.** Watchparty's store and socket are
78
+ * module singletons; a second `RoomChrome` shares and then tears down the
79
+ * first one's connection. This wraps `RoomShell`, outside it, once.
80
+ *
81
+ * ## What a screen may assume
82
+ *
83
+ * Its own props, and the CSS tokens above. Nothing else. There is no chrome
84
+ * context, no chrome export a screen imports, and no global this file sets.
85
+ * `grep -r "from '../chrome" games/magic/ui/src/screens/` is empty and is meant to
86
+ * stay empty — that grep is the cheap half of this contract.
87
+ *
88
+ * ## What `chrome/` will pass down when a screen needs something
89
+ *
90
+ * A prop from `App.tsx`, or a context exported from this directory. Never a
91
+ * global, never a module singleton. Both candidates are already resolved
92
+ * above the screens and neither is asked for today:
93
+ *
94
+ * - **Identity.** `App.tsx` reads `useWhoami()` once and spends it on the
95
+ * header's `status` and `settingsProps`. `RoomShell` reads the same hook,
96
+ * and `whoami()` shares one in-flight promise per page
97
+ * (`globalThis.__hadokuWhoami`), so that is one identity path with two
98
+ * consumers rather than two paths. A screen that needs the viewer takes it
99
+ * as a prop; it does not call `whoami()` itself.
100
+ * - **Theme state.** `useHadokuTheme()` is read in `ChromeInner` and nowhere
101
+ * else in this repo. A screen that has to branch on light/dark takes
102
+ * `isDarkTheme` as a prop or reads `data-theme` in CSS.
103
+ *
104
+ * ## What a replacement wrapper must provide
105
+ *
106
+ * The five guarantees, plus the two seams this file carries that do not look
107
+ * like chrome at first glance:
108
+ *
109
+ * - **The island rules in `chrome.css`** (its last three blocks). The draft
110
+ * table and its neighbours paint from the TABLE's palette — `--bg`,
111
+ * `--ink` — which is dark on purpose, and they inherit their text colour.
112
+ * Letting `--color-text` reach them puts a light theme's dark ink on a
113
+ * permanently dark tile. Those rules are the seam between the themed frame
114
+ * and the table; a wrapper that drops them breaks the table in light mode,
115
+ * and the breakage is the chrome's.
116
+ * - **The header is a SLOT, not an import.** `App.tsx` authors `<AppHeader>`
117
+ * at the app root — the fleet's convention, and where its audit reads it —
118
+ * and this file slots it in INSIDE `HadokuThemeRoot`, the one place it is
119
+ * themeable. `<AppHeader>` renders the theme picker and the settings gear
120
+ * itself; neither is a prop and there is no slot to substitute one, which
121
+ * is the point. Its `title` is a NODE — a link home, with the <h1> inside
122
+ * it — and `chrome.css` owns the two rules that make that node stop
123
+ * looking like a link, plus the header's edge buffer. A wrapper that slots
124
+ * a different header in has to bring both.
125
+ *
126
+ * ## The game's settings ARE in the header's gear, through its slot
127
+ *
128
+ * Out of it from 2026-10-10 (a host's menu is not ours to fill, and embedded
129
+ * there is no header), back in on 2026-10-30 when the operator made the fleet's
130
+ * popout the one place for settings. `App.tsx` passes `CARDTABLE_SETTINGS_TABS`
131
+ * as `<AppHeader>`'s `appTabs`, the slot the fleet made for exactly this: tabs
132
+ * of the game's own after the site's, never reaching into the header's own markup.
133
+ * Embedded, `../settings/Settings.tsx`'s own gear stands in until watchparty
134
+ * draws the popout.
135
+ *
136
+ * ## Theming is NOT ours, and must not become ours
137
+ *
138
+ * `<HadokuThemeRoot>` owns the theme, its three persistence layers
139
+ * (sessionStorage for the pre-paint script, localStorage for the next cold
140
+ * load, the prefs row for cross-device) and the picker. There is no local
141
+ * `useTheme`, `themePrefs` or `themeConfig` in this repo and there must never
142
+ * be one — eight apps each carried a hand-copied `useTheme.ts` and they drifted
143
+ * on real behaviour (only one wrote localStorage, so the rest lost the theme on
144
+ * a browser restart). That is the entire reason the shared one exists.
145
+ *
146
+ * ## Known gaps — where the boundary is NOT clean
147
+ *
148
+ * Audited at wave 18. Lane D owned only `chrome/**`, `App.tsx`, `main.tsx`
149
+ * and `index.html`, so every one of these is reported here rather than
150
+ * fixed: each fix lives in a file the lane did not own. They are listed
151
+ * because a wrapper swap meets them, not because they are acceptable.
152
+ *
153
+ * 2. **`screens/route.ts` is a global-reading module singleton** — the hash
154
+ * router reads `globalThis.location.hash` (:290, :304), subscribes to
155
+ * `hashchange` on the global (:282, :285) and mints ids from
156
+ * `globalThis.crypto` (:254). Every screen imports `navigate` from it,
157
+ * and so does `App.tsx` (`useRoute`). It is deliberate and documented
158
+ * there, but it means a screen's navigation is not a prop, and a wrapper
159
+ * that owns routing has to meet it. The watchparty embed (D21) meets it
160
+ * with `routeInMemory`, which takes the router off the address bar.
161
+ * 3. **`rooms/RoomList.tsx` subscribes to `document.visibilitychange`** in
162
+ * the effect that drives its poll, to stop polling on a hidden tab.
163
+ * Page-visibility is the shell's fact, not a list's. (No line numbers:
164
+ * lane C is rewriting that file in this same wave.)
165
+ * 4. **`screens/tables.ts` (:127) and `screens/LobbyScreen.tsx` read
166
+ * `import.meta.env`** — `BASE_URL` for the api base, `DEV` for a
167
+ * dev-only affordance. Build-time, not runtime, and both optional-chain.
168
+ * Named so a wrapper that changes the base path knows where it is read.
169
+ * 5. **`chrome.css` reaches DOWN**, at its last blocks, naming
170
+ * `.app`, `.draft`, `.board`, `.deck`, `.deckrow`, `.rooms`, `.spectate`,
171
+ * `.conn`, `.prompt` and `.confirm`. That is this lane's
172
+ * own file and it is the island seam above — deliberate, but it is a
173
+ * coupling in the other direction and it is the thing to delete when
174
+ * those sheets move onto semantic tokens.
175
+ *
176
+ * What is NOT here, and must not move here: routing rules, the api base,
177
+ * room/match/draft state, and anything that knows a card. This file renders
178
+ * a frame.
179
+ */
180
+ import { useRef } from 'react';
181
+ import { HadokuThemeRoot, useHadokuTheme } from '@wolffm/themes';
182
+ import { ensureMatchMedia } from "./matchMedia.js";
183
+ import './chrome.css';
184
+ import './trim.css';
185
+ // Before anything from @wolffm/themes runs an effect: one of them calls
186
+ // `window.matchMedia` unguarded. See `matchMedia.ts` for why that is ours to
187
+ // absorb and what removes this again.
188
+ ensureMatchMedia();
189
+ export function AppChrome({ header, children }) {
190
+ // The provider mirrors `data-theme` onto this container as well as <html>,
191
+ // which is what lets the chrome be themed even when something above it owns
192
+ // the document.
193
+ const containerRef = useRef(null);
194
+ return (_jsx(HadokuThemeRoot, { containerRef: containerRef, children: _jsx(ChromeInner, { containerRef: containerRef, header: header, children: children }) }));
195
+ }
196
+ function ChromeInner({ containerRef, header, children, }) {
197
+ // From the provider above. There is one implementation of this in the fleet
198
+ // and this app is now a consumer of it rather than a fork of it.
199
+ const { isDarkTheme } = useHadokuTheme();
200
+ return (_jsxs("main", { ref: containerRef, className: "cardtable-chrome", "data-dark-theme": isDarkTheme ? 'true' : 'false', children: [header, _jsx("div", { className: "cardtable-chrome__content", children: children })] }));
201
+ }
@@ -0,0 +1,336 @@
1
+ /*
2
+ * The chrome's own layout. Colour comes from `@wolffm/themes` and nowhere else.
3
+ *
4
+ * Every colour below is a semantic token — a token names a ROLE, not a hue, and
5
+ * the light/dark pair resolves from `data-theme` on <html> (and on this
6
+ * container, which `HadokuThemeRoot` mirrors it onto). No hex literals, and no
7
+ * `var(--token, #fallback)` defaults: a fallback hides a broken token instead of
8
+ * failing loudly.
9
+ *
10
+ * `main.tsx` imports the four fleet stylesheets before this one, in that order,
11
+ * for exactly this reason — the tokens have to be defined before anything reads
12
+ * them, and ESM evaluates imports in source order.
13
+ */
14
+
15
+ /*
16
+ * A card over the page — a popover, a dialog, a peek. Zero specificity, so a
17
+ * component's own rule (a larger radius, another fill) wins without a fight.
18
+ */
19
+ :where(.ct-surface) {
20
+ border: 1px solid var(--color-border);
21
+ border-radius: var(--hdk-radius);
22
+ background: var(--color-bg-card);
23
+ color: var(--color-text);
24
+ box-shadow: var(--hdk-shadow-lg);
25
+ }
26
+
27
+ /* A round icon button in a head: the decks, the stats, the settings gear. */
28
+ .ct-round-button {
29
+ display: inline-flex;
30
+ flex: none;
31
+ align-items: center;
32
+ justify-content: center;
33
+ width: 32px;
34
+ height: 32px;
35
+ padding: 0;
36
+ border: 1px solid var(--color-border);
37
+ border-radius: 50%;
38
+ background: var(--color-bg-card);
39
+ color: var(--color-text-secondary);
40
+ }
41
+
42
+ .ct-round-button:hover,
43
+ .ct-round-button[aria-expanded='true'],
44
+ .ct-round-button:focus-visible {
45
+ color: var(--color-text);
46
+ }
47
+
48
+ /* Explicit colour-scheme per variant. "dark only" also tells Dark Reader to
49
+ keep its hands off a theme that is already dark. */
50
+ .cardtable-chrome[data-dark-theme='false'] {
51
+ color-scheme: light;
52
+ }
53
+
54
+ .cardtable-chrome[data-dark-theme='true'] {
55
+ color-scheme: dark only;
56
+ }
57
+
58
+ .cardtable-chrome {
59
+ display: flex;
60
+ flex-direction: column;
61
+ min-height: 100vh;
62
+ background-color: var(--color-bg);
63
+ color: var(--color-text);
64
+ transition:
65
+ background-color 0.3s ease,
66
+ color 0.3s ease;
67
+ }
68
+
69
+ /*
70
+ * The page never grows with its content on the front page, a room or a match:
71
+ * the chrome is the window's height, so the document cannot scroll and
72
+ * watchparty's room frame — its chat aside with it — is never stretched by a
73
+ * long deck list (the operator, 2026-10-10: *"the watchparty interface should
74
+ * not be affected by page length"*). A screen opts in by its shell, which marks
75
+ * the frame as it is drawn (`chrome/shell.ts`'s `data-shell`, never a `:has()`
76
+ * the page answers again on every change under it). The sound picker too, so its
77
+ * bin and its grid scroll independently (same day).
78
+ */
79
+ .cardtable-chrome[data-shell] {
80
+ height: 100dvh;
81
+ min-height: 0;
82
+ }
83
+
84
+ /*
85
+ * The room's chat is a column beside the screen, the window's height, in every room, whatever screen
86
+ * the room is on (the operator, 2026-11-07: "it shouldn't matter what room we're in. right side-bar
87
+ * must be consistent"): a draft pod's hub is no fitted screen, and its chat stopped where the hub did.
88
+ * Keyed on the frame, so the room's screen scrolls inside it, never the page. Only where the chat IS
89
+ * a column (watchparty's own breakpoint, 768px): narrower, it sits under the screen and the page
90
+ * scrolls the two together, as a phone's draft is built to (`draft.css`).
91
+ */
92
+ @media (min-width: 768px) {
93
+ .cardtable-chrome[data-room-frame] {
94
+ height: 100dvh;
95
+ min-height: 0;
96
+ }
97
+ }
98
+
99
+ /* The header is a fixed row; whatever the route renders takes the rest. The
100
+ direct-child rule is what lets both possible children grow — `.shell` on a
101
+ roomless route, and watchparty's `.wp-room-chrome-frame` on a room one, which
102
+ asks for `height: 100%` and would otherwise sit at content height.
103
+
104
+ A screen drawn into a room is one level further in: RoomShell keeps it mounted
105
+ while the chat comes and goes by drawing it into a node it moves between the
106
+ two (`packages/game-ui/src/room/RoomShell.tsx`). That node and the slot holding it are
107
+ `.chrome-slot`s, which take no box, and every rule here that addresses a
108
+ content's own child reaches through exactly those two. */
109
+ .chrome-slot {
110
+ display: contents;
111
+ }
112
+
113
+ .cardtable-chrome__content {
114
+ display: flex;
115
+ flex-direction: column;
116
+ flex: 1 1 auto;
117
+ min-height: 0;
118
+ }
119
+
120
+ .cardtable-chrome__content > *,
121
+ .cardtable-chrome__content > .chrome-slot > .chrome-slot > * {
122
+ flex: 1 1 auto;
123
+ min-height: 0;
124
+ }
125
+
126
+ /*
127
+ * The header bar's edge buffer, and where its numbers come from.
128
+ *
129
+ * The operator, 2026-09-26: *"the top header bar has no left, top, or right
130
+ * edge buffer. i would prefer if we reused the existing css that hadoku_site
131
+ * ships with child apps for the header bar specifically."*
132
+ *
133
+ * What the fleet ships for the header is exactly ONE stylesheet —
134
+ * `@wolffm/task-ui-components/app-header.css`, which `main.tsx` has imported
135
+ * since wave 18 — and it deliberately sets no left, right or top spacing at
136
+ * all: `.app-header` is `padding-bottom: 1rem`, `margin-bottom: 1.5rem` and a
137
+ * border-bottom, "full width of whatever column the app places it in" (its own
138
+ * comment). There is no second header stylesheet anywhere in hadoku_site:
139
+ * `grep -rn '\.app-header' ~/srv/hadoku_site --include=*.css` finds only
140
+ * `templates/ui-app/src/styles/index.css`, and only to say "no header styles
141
+ * here — AppHeader owns them".
142
+ *
143
+ * In every other child app that column is the app's own content wrapper, and
144
+ * the header sits INSIDE it: `templates/ui-app/src/App.tsx` and
145
+ * `templates/tunnel-contained/packages/ui/src/App.tsx` both render
146
+ * `<AppHeader>` inside `<div className="…">`, whose rule is
147
+ * `max-width: 1200px; margin: 0 auto; padding: 2rem`. That `2rem` is the
148
+ * fleet's child-app edge buffer, and it is the only value there is to reuse.
149
+ *
150
+ * `templates/game` — the reference for a game like this one — is the template
151
+ * that does NOT do it: it renders `<AppHeader>` as a direct child of the
152
+ * unpadded container, OUTSIDE its padded `.{{APP_ID}}` wrapper. That is the
153
+ * layout the operator reported, and the shell here was written against it.
154
+ *
155
+ * So: the fleet's value, on the fleet's element, with no wrapper element.
156
+ *
157
+ * The inline inset is `padding`, not `margin` (the operator, 2026-10-21: "we
158
+ * need to horizontaly go all the way with the top divider bar"): the title and
159
+ * the controls keep the fleet's 2rem, and the bar's border-bottom runs from one
160
+ * edge of the window to the other. The top is still `margin`; `margin-bottom`
161
+ * stays `app-header.css`'s 1.5rem, except beside the chat (watchparty's
162
+ * stylesheet closes it there) and on the match.
163
+ *
164
+ * What is NOT done here: re-insetting the content to match. `screens.css`'s
165
+ * `.shell` is `max-width: 1400px; padding: 24px`, so on a wide viewport the
166
+ * centred content and the full-bleed header do not share a left edge. That is
167
+ * pre-existing, `screens.css` is not this lane's, and the fleet's answer is one
168
+ * wrapper around both — which is where it should be fixed, not with a third
169
+ * number here.
170
+ */
171
+ .cardtable-chrome > .app-header {
172
+ margin-top: 2rem;
173
+ padding-inline: 2rem;
174
+ }
175
+
176
+ /*
177
+ * ONE page boundary, wherever the room's chat is drawn (wave 31 P6, widened
178
+ * 2026-10-10).
179
+ *
180
+ * The operator, wave 31: *"card table left boundary is slightly escaping the
181
+ * boundary set by the bar at the top… same thing goes for watchparty chat on
182
+ * the right."* And 2026-10-10: the chat's vertical separator *"should go all
183
+ * the way to the top and bottom, so touch the horizontal top bar seperator and
184
+ * the bottom of the page"*, and in a room the chat *"should respect the right
185
+ * side page boundary"*.
186
+ *
187
+ * The separator is `.wp-room-chrome`'s own `border-left`, on a column that is
188
+ * the full height of `.wp-room-chrome-frame`. Touching the bar's rule is
189
+ * watchparty's now (`@wolffm/watchparty-ui`'s `room-chrome.css`): it zeroes
190
+ * the header's bottom margin wherever a frame follows it, for every app. What
191
+ * stays here is the page's EDGE, which is ours: `__content` takes the bar's
192
+ * own `2rem` on the left, so the screen starts under the bar's title, and none
193
+ * on the right, so the chat runs to the window's edge (the operator,
194
+ * 2026-10-21: "the chat needs to go all the way to the edge of the screen").
195
+ *
196
+ * Keyed on the frame, not on a route's shell, so the room, the draft and the
197
+ * deck builder get it as the match always did; `.shell--match` stays because a
198
+ * match whose chrome did not mount (no identity) still wants the bar's edges
199
+ * and the whole height. The header itself does not move — see the next rule —
200
+ * only the gap BELOW it closes.
201
+ */
202
+ .cardtable-chrome[data-shell='match'] > .app-header {
203
+ margin-bottom: 0;
204
+ }
205
+
206
+ :is(.cardtable-chrome[data-shell='match'], .cardtable-chrome[data-room-frame]) > .cardtable-chrome__content {
207
+ padding-left: 2rem;
208
+ }
209
+
210
+ /* A match whose chat did not mount keeps a right edge of its own. */
211
+ .cardtable-chrome[data-shell='match']:not([data-room-frame]) > .cardtable-chrome__content {
212
+ padding-right: 2rem;
213
+ }
214
+
215
+ /* A fitted screen beside the chat starts on the bar's left edge, not 24px in
216
+ from it: `__content`'s inset above is the page's edge now, and `.shell`'s own
217
+ padding would put a second one inside it. The right side keeps its padding
218
+ as the gutter against the chat's separator. */
219
+ .wp-room-chrome-frame__content > .shell.shell--fit,
220
+ .wp-room-chrome-frame__content > .chrome-slot > .chrome-slot > .shell.shell--fit {
221
+ padding-left: 0;
222
+ }
223
+
224
+ /* A phone's edge is 16px, the bar's and the page's alike, and the chat is
225
+ below the screen rather than beside it, so the right needs no gutter of its
226
+ own: at 2rem plus that gutter a 390px room was 300px wide. */
227
+ @media (max-width: 600px) {
228
+ .cardtable-chrome > .app-header {
229
+ padding-inline: 16px;
230
+ }
231
+
232
+ :is(.cardtable-chrome[data-shell='match'], .cardtable-chrome[data-room-frame]) > .cardtable-chrome__content {
233
+ padding-left: 16px;
234
+ }
235
+
236
+ .cardtable-chrome[data-shell='match']:not([data-room-frame]) > .cardtable-chrome__content {
237
+ padding-right: 16px;
238
+ }
239
+
240
+ .wp-room-chrome-frame__content > .shell.shell--fit,
241
+ .wp-room-chrome-frame__content > .chrome-slot > .chrome-slot > .shell.shell--fit {
242
+ padding-right: 0;
243
+ }
244
+ }
245
+
246
+ /*
247
+ * The header does NOT move between routes.
248
+ *
249
+ * This used to zero `margin-top` on the match route, to give the board back
250
+ * the 2rem — the chrome is pinned to `100dvh` and every pixel above the table
251
+ * comes off it. The operator overruled that trade on 2026-09-27: *"match
252
+ * screen should be the same as lobby screen, the top bar shouldn't move. i
253
+ * understand it hurts the vertical space a bit, thats okay."* A header that
254
+ * jumps when you enter a match is worse than a slightly shorter table.
255
+ *
256
+ * `margin-bottom` stays zeroed on this route (the boundary rule above): that
257
+ * tightens the gap BELOW the bar without moving the bar itself, so it costs
258
+ * nothing the operator asked for and keeps the board what space remains.
259
+ */
260
+
261
+ /*
262
+ * "Card Table", top-left, is the way back to the entry page — the operator,
263
+ * 2026-09-26: *"'Card Table' at the top should be clickable and bring you back
264
+ * to the entry page."*
265
+ *
266
+ * `App.tsx` passes a real `<a href="#/">` as `AppHeader`'s node title, with the
267
+ * <h1> inside it. `AppHeader` wraps a node title in its own
268
+ * `.app-header__title`, which already carries the size, weight and colour — so
269
+ * all these two rules do is stop the anchor looking like a link and stop the
270
+ * heading bringing a UA font size and margin of its own.
271
+ */
272
+ .cardtable-chrome__home {
273
+ color: inherit;
274
+ text-decoration: none;
275
+ border-radius: var(--hdk-radius-sm);
276
+ }
277
+
278
+ .cardtable-chrome__home:hover {
279
+ text-decoration: underline;
280
+ }
281
+
282
+ .cardtable-chrome__home:focus-visible {
283
+ outline: none;
284
+ box-shadow: var(--hdk-shadow-focus);
285
+ }
286
+
287
+ .cardtable-chrome__home-name {
288
+ margin: 0;
289
+ font: inherit;
290
+ }
291
+
292
+ /*
293
+ * The table is a dark island inside a themed page, deliberately.
294
+ *
295
+ * `styles.css` is the DRAFT TABLE's stylesheet, and `rooms.css`, `board.css`,
296
+ * `live.css`, `prompts.css` and `spectate.css` are its neighbours. None of them
297
+ * is this lane's, and all of them paint from the TABLE's palette — `--bg`,
298
+ * `--bg-raised`, `--ink` — which is dark on purpose and for a reason that is
299
+ * not taste: a draft is read for forty-five minutes at a stretch, and the
300
+ * colour-pie hues are desaturated away from the printed ones so a pip reads as
301
+ * ours.
302
+ *
303
+ * Those surfaces set a background and INHERIT their text colour. So letting
304
+ * `--color-text` reach them would put a light theme's dark ink on a permanently
305
+ * dark tile — unreadable, and it would be the chrome that broke it.
306
+ *
307
+ * Hence this: the roots those stylesheets own re-assert their own palette, and
308
+ * everything around them — header, lobby chrome, pod bar, deck builder, footer
309
+ * — is themed. This list is the seam between the themed frame and the table,
310
+ * and it is the thing to extend when a new dark surface appears (or to delete,
311
+ * when those sheets move onto semantic tokens too).
312
+ *
313
+ * Each root spelled out, never one `:is()` list on the right: the browser files a rule under its
314
+ * rightmost class and tries it only on elements that carry it, and an `:is()` there is filed under
315
+ * nothing — tried on every element of the page at every restyle, 20,000 times in two seconds of a
316
+ * six-creature attack (`e2e/combat-perf.spec.ts`'s selector stats, 2026-10-23).
317
+ */
318
+ .cardtable-chrome .draft,
319
+ .cardtable-chrome .board,
320
+ .cardtable-chrome .deck,
321
+ .cardtable-chrome .rooms,
322
+ .cardtable-chrome .spectate {
323
+ background-color: var(--bg);
324
+ }
325
+
326
+ .cardtable-chrome .draft,
327
+ .cardtable-chrome .board,
328
+ .cardtable-chrome .deck,
329
+ .cardtable-chrome .deckrow,
330
+ .cardtable-chrome .rooms,
331
+ .cardtable-chrome .spectate,
332
+ .cardtable-chrome .conn,
333
+ .cardtable-chrome .prompt,
334
+ .cardtable-chrome .confirm {
335
+ color: var(--ink);
336
+ }
@@ -0,0 +1,3 @@
1
+ export * from './AppChrome.js';
2
+ export * from './matchMedia.js';
3
+ export * from './shell.js';
@@ -0,0 +1,3 @@
1
+ export * from "./AppChrome.js";
2
+ export * from "./matchMedia.js";
3
+ export * from "./shell.js";
@@ -0,0 +1,2 @@
1
+ /** Install the fallback if and only if the host has none. Safe to call twice. */
2
+ export declare function ensureMatchMedia(): void;
@@ -0,0 +1,51 @@
1
+ /*
2
+ * `window.matchMedia`, for the environments that do not have it.
3
+ *
4
+ * WHY THIS EXISTS
5
+ * ---------------
6
+ * `@wolffm/themes@5.8.5` treats `matchMedia` as optional in one place and
7
+ * mandatory in another. Its `prefersDark()` guards the call
8
+ * (`window.matchMedia ? … : false`), but the effect that follows the OS
9
+ * light/dark switch does not — `dist/useTheme.js:216` is a bare
10
+ * `window.matchMedia('(prefers-color-scheme: dark)')` inside a `useEffect`.
11
+ *
12
+ * jsdom has never implemented `matchMedia` (verified against the pinned
13
+ * jsdom 30.0.1: `typeof window.matchMedia === 'undefined'`), so the moment
14
+ * `AppChrome` mounted, every existing test that renders the real `App` —
15
+ * `screens/lobby.test.ts` and `components/DraftScreen.test.ts`, 26 cases —
16
+ * threw `window.matchMedia is not a function` in the passive-effect commit.
17
+ *
18
+ * This is an upstream oversight, not a test-only concern: any embedder without
19
+ * the API takes the same throw in the browser. Feature-detected and idempotent,
20
+ * so in every real browser it costs one `typeof` at module load and does
21
+ * nothing else. The fallback reports "no match", which is what a host with no
22
+ * media-query support can honestly say, and carries the listener surface the
23
+ * effect subscribes and unsubscribes on so the cleanup does not throw either.
24
+ *
25
+ * It is deliberately NOT a test fixture. Putting it in a vitest setup file
26
+ * would have made the specs pass while leaving the production path one
27
+ * un-polyfilled embedder away from the same crash, and would have needed the
28
+ * root `vitest.config.ts`, which this lane does not own.
29
+ *
30
+ * Remove it when @wolffm/themes guards that effect the way it guards
31
+ * `prefersDark`.
32
+ */
33
+ /** Install the fallback if and only if the host has none. Safe to call twice. */
34
+ export function ensureMatchMedia() {
35
+ const host = globalThis;
36
+ if (typeof host.matchMedia === 'function')
37
+ return;
38
+ host.matchMedia = (media) => ({
39
+ matches: false,
40
+ media,
41
+ onchange: null,
42
+ addEventListener: () => undefined,
43
+ removeEventListener: () => undefined,
44
+ // The deprecated pair as well: a consumer that feature-detects the modern
45
+ // one is fine, but one that falls back to `addListener` would find a
46
+ // half-built object and throw on the fallback path instead of the main one.
47
+ addListener: () => undefined,
48
+ removeListener: () => undefined,
49
+ dispatchEvent: () => false,
50
+ });
51
+ }