@hadoku/rooms-client 0.45.79 → 0.45.81

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.
@@ -0,0 +1,57 @@
1
+ import { type GameBundleContext, type GameEntry } from '@wolffm/rooms-protocol';
2
+ /**
3
+ * The absolute URL to import for a catalog `url`, or null when it would leave
4
+ * the page's origin. The catalog was validated already (server and browser);
5
+ * this re-checks against the REAL origin at the moment of import, because a
6
+ * dynamic `import()` resolves against the importing module's URL, not the
7
+ * page's — and the app bundle may be served from somewhere else.
8
+ */
9
+ export declare function resolveGameBundleUrl(url: string, pageOrigin: string): string | null;
10
+ /**
11
+ * What a bundle slot mounts: a catalog game, or a host's own built-in default
12
+ * activity. Both are a `GameBundleModule`; they differ only in where the
13
+ * module comes from. `load` is null when a catalog url would leave the page's
14
+ * origin.
15
+ */
16
+ export interface BundleActivity {
17
+ id: string;
18
+ name: string;
19
+ load: (() => Promise<unknown>) | null;
20
+ }
21
+ /** A `kind: 'module'` catalog entry as an activity: imported by URL. */
22
+ export declare function moduleActivity(entry: Extract<GameEntry, {
23
+ kind: 'module';
24
+ }>, pageOrigin: string): BundleActivity;
25
+ export interface GameBundleHandle {
26
+ /** Pass the bundle a new context. Held until mount resolves if it has not yet. */
27
+ update(ctx: GameBundleContext): void;
28
+ /** Unmount (now, or as soon as an in-flight mount resolves). Idempotent. */
29
+ dispose(): void;
30
+ /**
31
+ * Draw the bundle's settings into `el` (`MountedGameBundle.mountSettings`).
32
+ * Returns the cleanup, or null when the bundle has no settings, is not
33
+ * mounted, or threw. A throw is reported through `onSettingsError` and never
34
+ * takes the game down: a broken preferences panel is not a broken game.
35
+ */
36
+ mountSettings(el: HTMLElement): (() => void) | null;
37
+ }
38
+ interface MountGameBundleOptions<El> {
39
+ /** Resolves to the bundle's module namespace. */
40
+ load: () => Promise<unknown>;
41
+ el: El;
42
+ ctx: GameBundleContext;
43
+ onError: (message: string, cause?: unknown) => void;
44
+ /** Whether the mounted bundle offers settings: true once a bundle with
45
+ * `mountSettings` is mounted, false again when it goes away. */
46
+ onSettingsAvailable?: (available: boolean) => void;
47
+ onSettingsError?: (message: string, cause?: unknown) => void;
48
+ }
49
+ /**
50
+ * Load and mount a bundle into `el`. Returns at once; the mount is async.
51
+ *
52
+ * Generic over the element so tests can pass a plain object — the host never
53
+ * touches `el` itself, the bundle does.
54
+ */
55
+ export declare function mountGameBundle<El = HTMLElement>(opts: MountGameBundleOptions<El>): GameBundleHandle;
56
+ export {};
57
+ //# sourceMappingURL=bundle-host.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bundle-host.d.ts","sourceRoot":"","sources":["../src/bundle-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EAAE,KAAK,SAAS,EACvC,MAAM,wBAAwB,CAAC;AAuChC;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInF;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CACvC;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAGhH;AAED,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,MAAM,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC,4EAA4E;IAC5E,OAAO,IAAI,IAAI,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,EAAE,WAAW,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CACrD;AAED,UAAU,sBAAsB,CAAC,EAAE;IACjC,iDAAiD;IACjD,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,EAAE,EAAE,EAAE,CAAC;IACP,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD;qEACiE;IACjE,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9D;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,GAAG,WAAW,EAAE,IAAI,EAAE,sBAAsB,CAAC,EAAE,CAAC,GAAG,gBAAgB,CA0HpG"}
@@ -0,0 +1,197 @@
1
+ import { isGameBundleModule, isMountedGameBundle, } from '@wolffm/rooms-protocol';
2
+ /**
3
+ * Mounting a `kind: 'module'` game — the lifecycle half of a React
4
+ * `GameBundleSlot`, kept out of the component so its races are testable
5
+ * without a DOM. DOM-free and framework-free: a consumer wires its own
6
+ * element type and its own React slot around this.
7
+ *
8
+ * The bundle is code the host app has never seen, loaded at runtime, so every
9
+ * step that can fail reports through `onError` instead of throwing into
10
+ * React: a failed import, a module that does not export `mount`, a `mount`
11
+ * that throws or rejects or resolves to the wrong shape, an `update` that
12
+ * throws.
13
+ */
14
+ /**
15
+ * A root-relative path on the page's own origin, and nothing else.
16
+ *
17
+ * Absolute URLs are refused outright, not just cross-origin ones: the caller
18
+ * does not know the page's origin, so `https://hadoku.me/x` cannot be told
19
+ * apart from `https://evil.example/x` here. `//host/x` (protocol-relative) and
20
+ * `/\host/x` (browsers read the backslash as a slash) both leave the origin
21
+ * despite the leading `/`, which is why this resolves the path rather than
22
+ * just checking its first character.
23
+ *
24
+ * Duplicated (not imported) from watchparty's `packages/shared/src/gameCatalog.ts`:
25
+ * that package is app-specific and private, and this one must stay free of any
26
+ * watchparty dependency. Keep the two in sync by hand if either changes.
27
+ */
28
+ function isSameOriginPath(value) {
29
+ if (!value.startsWith('/') || value.startsWith('//'))
30
+ return false;
31
+ if (/[\\\s]/.test(value) || [...value].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f))
32
+ return false;
33
+ try {
34
+ return new URL(value, 'https://game-catalog.invalid').origin === 'https://game-catalog.invalid';
35
+ }
36
+ catch {
37
+ return false;
38
+ }
39
+ }
40
+ /**
41
+ * The absolute URL to import for a catalog `url`, or null when it would leave
42
+ * the page's origin. The catalog was validated already (server and browser);
43
+ * this re-checks against the REAL origin at the moment of import, because a
44
+ * dynamic `import()` resolves against the importing module's URL, not the
45
+ * page's — and the app bundle may be served from somewhere else.
46
+ */
47
+ export function resolveGameBundleUrl(url, pageOrigin) {
48
+ if (!isSameOriginPath(url))
49
+ return null;
50
+ const resolved = new URL(url, pageOrigin);
51
+ return resolved.origin === pageOrigin ? resolved.href : null;
52
+ }
53
+ /** A `kind: 'module'` catalog entry as an activity: imported by URL. */
54
+ export function moduleActivity(entry, pageOrigin) {
55
+ const href = resolveGameBundleUrl(entry.url, pageOrigin);
56
+ return { id: entry.id, name: entry.name, load: href ? () => import(/* @vite-ignore */ href) : null };
57
+ }
58
+ const describe = (e) => (e instanceof Error ? e.message : String(e));
59
+ /**
60
+ * Load and mount a bundle into `el`. Returns at once; the mount is async.
61
+ *
62
+ * Generic over the element so tests can pass a plain object — the host never
63
+ * touches `el` itself, the bundle does.
64
+ */
65
+ export function mountGameBundle(opts) {
66
+ let latest = opts.ctx;
67
+ let mounted = null;
68
+ let disposed = false;
69
+ let failed = false;
70
+ // Settings panels currently drawn, so they are removed BEFORE the bundle
71
+ // unmounts rather than whenever the popout next re-renders.
72
+ // One entry per open, even if a bundle hands back the same function twice.
73
+ const openSettings = new Set();
74
+ const settingsError = (message, cause) => opts.onSettingsError?.(message, cause);
75
+ const closeSettings = (open) => {
76
+ if (!openSettings.delete(open))
77
+ return;
78
+ try {
79
+ open.cleanup();
80
+ }
81
+ catch (e) {
82
+ settingsError(`the game's settings failed to close: ${describe(e)}`, e);
83
+ }
84
+ };
85
+ /** The bundle is going away: its settings first, then say so. */
86
+ const releaseSettings = (bundle) => {
87
+ for (const open of [...openSettings])
88
+ closeSettings(open);
89
+ if (bundle.mountSettings)
90
+ opts.onSettingsAvailable?.(false);
91
+ };
92
+ const teardown = (bundle) => {
93
+ releaseSettings(bundle);
94
+ try {
95
+ bundle.unmount();
96
+ }
97
+ catch (e) {
98
+ // Reported, not rethrown: the slot is going away either way, and an
99
+ // exception here would escape a React cleanup. Never over a first error.
100
+ if (!failed)
101
+ opts.onError(`unmount threw: ${describe(e)}`, e);
102
+ }
103
+ };
104
+ /** Report the first failure and take a half-working bundle down with it. */
105
+ const fail = (message, cause) => {
106
+ if (failed || disposed)
107
+ return;
108
+ failed = true;
109
+ const bundle = mounted;
110
+ mounted = null;
111
+ if (bundle)
112
+ teardown(bundle);
113
+ opts.onError(message, cause);
114
+ };
115
+ const update = (ctx) => {
116
+ latest = ctx;
117
+ if (!mounted || disposed)
118
+ return;
119
+ try {
120
+ mounted.update(ctx);
121
+ }
122
+ catch (e) {
123
+ fail(`the game failed to update: ${describe(e)}`, e);
124
+ }
125
+ };
126
+ void (async () => {
127
+ let mod;
128
+ try {
129
+ mod = await opts.load();
130
+ }
131
+ catch (e) {
132
+ fail(`could not load the game: ${describe(e)}`, e);
133
+ return;
134
+ }
135
+ if (disposed)
136
+ return;
137
+ if (!isGameBundleModule(mod)) {
138
+ fail('the game module does not export mount()');
139
+ return;
140
+ }
141
+ const mountedCtx = latest;
142
+ let result;
143
+ try {
144
+ // `as` is the narrowing the guard above proved; El is HTMLElement in the app.
145
+ result = await mod.mount(opts.el, mountedCtx);
146
+ }
147
+ catch (e) {
148
+ fail(`the game failed to start: ${describe(e)}`, e);
149
+ return;
150
+ }
151
+ if (!isMountedGameBundle(result)) {
152
+ fail('the game\'s mount() did not return { unmount, update }');
153
+ return;
154
+ }
155
+ if (disposed) {
156
+ teardown(result);
157
+ return;
158
+ }
159
+ mounted = result;
160
+ if (result.mountSettings)
161
+ opts.onSettingsAvailable?.(true);
162
+ // A context change that landed while mount was in flight.
163
+ if (latest !== mountedCtx)
164
+ update(latest);
165
+ })();
166
+ return {
167
+ update,
168
+ dispose() {
169
+ if (disposed)
170
+ return;
171
+ disposed = true;
172
+ if (mounted)
173
+ teardown(mounted);
174
+ mounted = null;
175
+ },
176
+ mountSettings(el) {
177
+ const bundle = mounted;
178
+ if (!bundle?.mountSettings || disposed)
179
+ return null;
180
+ let raw;
181
+ try {
182
+ raw = bundle.mountSettings(el);
183
+ }
184
+ catch (e) {
185
+ settingsError(`the game's settings failed to open: ${describe(e)}`, e);
186
+ return null;
187
+ }
188
+ if (typeof raw !== 'function') {
189
+ settingsError('the game\'s mountSettings() did not return a cleanup function');
190
+ return null;
191
+ }
192
+ const open = { cleanup: raw };
193
+ openSettings.add(open);
194
+ return () => closeSettings(open);
195
+ },
196
+ };
197
+ }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export { createRoomListClient, type FeedTarget, type PingReason, type PingSource, type RoomListClient, type RoomListDeps, type RoomListListener, type RoomListState, } from './roomList.js';
2
2
  export { createFeedPings, type ClientFeedWire, type FeedSocket, type FeedSocketDeps, type RoomFeedChanged, } from './feedSocket.js';
3
+ export { mountGameBundle, moduleActivity, resolveGameBundleUrl, type BundleActivity, type GameBundleHandle, } from './bundle-host.js';
3
4
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}
package/dist/index.js CHANGED
@@ -12,3 +12,4 @@
12
12
  */
13
13
  export { createRoomListClient, } from './roomList.js';
14
14
  export { createFeedPings, } from './feedSocket.js';
15
+ export { mountGameBundle, moduleActivity, resolveGameBundleUrl, } from './bundle-host.js';
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@hadoku/rooms-client",
3
- "version": "0.45.79",
4
- "gitHead": "ae0273d0c151500cc28413c59d34fe28ac4bdca4",
3
+ "version": "0.45.81",
4
+ "gitHead": "85d1bea7dbe3ab737020c997890af7e08ad9a851",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Browser-side room feed client: follow a room (or the room list) without polling for it.",
@@ -27,7 +27,7 @@
27
27
  "directory": "packages/rooms-client"
28
28
  },
29
29
  "dependencies": {
30
- "@wolffm/rooms-protocol": "npm:@hadoku/rooms-protocol@0.45.79"
30
+ "@wolffm/rooms-protocol": "npm:@hadoku/rooms-protocol@0.45.81"
31
31
  },
32
32
  "peerDependencies": {
33
33
  "react": ">=18",