@caisual/kit 0.4.0 → 0.8.0

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 (54) hide show
  1. package/dist/kit.d.ts +2 -157
  2. package/dist/kit.js +1539 -59
  3. package/dist/node.d.ts +1 -77
  4. package/dist/node.js +341 -42
  5. package/dist/overlay.d.ts +1 -0
  6. package/dist/overlay.js +1846 -0
  7. package/dist/runtime.d.ts +1 -108
  8. package/dist/runtime.js +191 -41
  9. package/dist/server.d.ts +1 -71
  10. package/dist/server.js +1 -0
  11. package/dist/types/api.d.ts +25 -0
  12. package/dist/types/contracts/biglietto.d.ts +24 -0
  13. package/dist/types/contracts/device.d.ts +66 -0
  14. package/dist/types/contracts/firma.d.ts +21 -0
  15. package/dist/types/contracts/index.d.ts +10 -0
  16. package/dist/types/contracts/keys.d.ts +59 -0
  17. package/dist/types/contracts/manifest.d.ts +118 -0
  18. package/dist/types/contracts/overlay-boards.d.ts +3 -0
  19. package/dist/types/contracts/overlay.d.ts +215 -0
  20. package/dist/types/contracts/runtime.d.ts +70 -0
  21. package/dist/types/contracts/server-js.d.ts +11 -0
  22. package/dist/types/contracts/slug.d.ts +5 -0
  23. package/dist/types/contracts/token-crew.d.ts +21 -0
  24. package/dist/types/daily.d.ts +3 -0
  25. package/dist/types/errors.d.ts +6 -0
  26. package/dist/types/handshake.d.ts +26 -0
  27. package/dist/types/http.d.ts +3 -0
  28. package/dist/types/index.d.ts +217 -0
  29. package/dist/types/kit.d.ts +26 -0
  30. package/dist/types/node/index.d.ts +96 -0
  31. package/dist/types/node/websocket.d.ts +29 -0
  32. package/dist/types/overlay/boards.d.ts +48 -0
  33. package/dist/types/overlay/bridge.d.ts +3 -0
  34. package/dist/types/overlay/host-bridge.d.ts +58 -0
  35. package/dist/types/overlay/i18n.d.ts +122 -0
  36. package/dist/types/overlay/index.d.ts +9 -0
  37. package/dist/types/overlay/shortcut.d.ts +4 -0
  38. package/dist/types/overlay/styles.d.ts +1 -0
  39. package/dist/types/overlay/ui-model.d.ts +45 -0
  40. package/dist/types/overlay/ui.d.ts +80 -0
  41. package/dist/types/overlay/voice-panel.d.ts +13 -0
  42. package/dist/types/protocollo.d.ts +257 -0
  43. package/dist/types/runtime/index.d.ts +127 -0
  44. package/dist/types/server/index.d.ts +72 -0
  45. package/dist/types/session/index.d.ts +49 -0
  46. package/dist/types/session/resume.d.ts +13 -0
  47. package/dist/types/standalone.d.ts +14 -0
  48. package/dist/types/stanza/index.d.ts +3 -0
  49. package/dist/types/stanza/json.d.ts +18 -0
  50. package/dist/types/stanza/nucleo.d.ts +97 -0
  51. package/dist/types/stanza/tipi.d.ts +134 -0
  52. package/dist/types/stanza-client/index.d.ts +24 -0
  53. package/dist/types/voce/index.d.ts +124 -0
  54. package/package.json +10 -2
@@ -0,0 +1,66 @@
1
+ import type { ManifestRequires } from './manifest.js';
2
+ interface ProbeWebGlContext {
3
+ getExtension(name: string): {
4
+ loseContext(): void;
5
+ } | null;
6
+ }
7
+ interface ProbeCanvas {
8
+ getContext(name: string, options?: {
9
+ failIfMajorPerformanceCaveat?: boolean;
10
+ }): ProbeWebGlContext | null;
11
+ }
12
+ interface ProbeGpuDevice {
13
+ destroy?: () => void;
14
+ }
15
+ interface ProbeGpuAdapter {
16
+ requestDevice(): Promise<ProbeGpuDevice>;
17
+ }
18
+ interface ProbeGpu {
19
+ requestAdapter(): Promise<ProbeGpuAdapter | null>;
20
+ }
21
+ interface ProbeWebAssembly {
22
+ validate(bytes: Uint8Array): boolean;
23
+ Memory: new (descriptor: {
24
+ initial: number;
25
+ maximum: number;
26
+ shared: boolean;
27
+ }) => unknown;
28
+ }
29
+ export interface ProbeGlobals {
30
+ document: {
31
+ createElement(name: 'canvas'): ProbeCanvas;
32
+ };
33
+ navigator: {
34
+ gpu?: ProbeGpu;
35
+ deviceMemory?: number;
36
+ hardwareConcurrency?: number;
37
+ userAgentData?: {
38
+ mobile?: boolean;
39
+ };
40
+ userAgent?: string;
41
+ };
42
+ WebAssembly: ProbeWebAssembly;
43
+ crossOriginIsolated: boolean;
44
+ }
45
+ export interface DeviceReport {
46
+ webgl2: boolean;
47
+ webgpu: boolean;
48
+ wasm: boolean;
49
+ threads: boolean;
50
+ isolated: boolean;
51
+ gpu: 'hardware' | 'software' | 'none';
52
+ memoryMb: number | null;
53
+ cores: number | null;
54
+ mobile: boolean;
55
+ tier: 'low' | 'mid' | 'high';
56
+ }
57
+ export type CompatibilityLevel = 'ok' | 'slow' | 'unsupported';
58
+ export interface CompatibilityVerdict {
59
+ level: CompatibilityLevel;
60
+ missing: string[];
61
+ }
62
+ export declare function deviceTier(report: Omit<DeviceReport, 'tier'>): DeviceReport['tier'];
63
+ export declare function checkCompatibility(requires: ManifestRequires, report: DeviceReport): CompatibilityVerdict;
64
+ export declare function requiresAnything(requires: ManifestRequires): boolean;
65
+ export declare function probeDevice(globals?: Partial<ProbeGlobals>, timeoutMs?: number): Promise<DeviceReport>;
66
+ export {};
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Firma HMAC e codifiche del formato JWT compatto, condivise dai gettoni del portale.
3
+ *
4
+ * Il biglietto di gioco e il gettone della crew hanno campi diversi ma lo stesso
5
+ * involucro: tenerlo in un posto solo evita che i due si allontanino nei dettagli
6
+ * (padding, confronto a tempo costante, intestazione).
7
+ */
8
+ export declare const HEADER_JWT: {
9
+ readonly alg: 'HS256';
10
+ readonly typ: 'JWT';
11
+ };
12
+ /** Base64url senza padding, la codifica richiesta dal formato del biglietto. */
13
+ export declare function base64UrlEncode(bytes: Uint8Array): string;
14
+ export declare function base64UrlDecode(value: string): Uint8Array;
15
+ export declare function timingSafeEqualStrings(a: string, b: string): boolean;
16
+ export declare function firmaHmac(secret: string, value: string): Promise<string>;
17
+ export declare function codificaJwt(value: unknown): string;
18
+ export declare function oggetto(value: unknown): Record<string, unknown> | null;
19
+ /** Verifica la firma e decodifica; null se il gettone non ha la forma JWT attesa. */
20
+ export declare function apriJwt(token: string, secret: string): Promise<Record<string, unknown> | null>;
21
+ export declare function firmaJwt(payload: unknown, secret: string): Promise<string>;
@@ -0,0 +1,10 @@
1
+ export * from './keys.js';
2
+ export * from './manifest.js';
3
+ export * from './device.js';
4
+ export * from './runtime.js';
5
+ export * from './server-js.js';
6
+ export * from './slug.js';
7
+ export * from './biglietto.js';
8
+ export * from './token-crew.js';
9
+ export * from './overlay.js';
10
+ export * from './overlay-boards.js';
@@ -0,0 +1,59 @@
1
+ /** Costruttori condivisi delle chiavi degli artefatti di gioco. */
2
+ /** Numero progressivo della versione dentro un gioco. */
3
+ export type VersionNumber = number & {
4
+ readonly __brand: 'VersionNumber';
5
+ };
6
+ /**
7
+ * ## Perche' gli artefatti stanno in un bucket PRIVATO e separato
8
+ *
9
+ * Il bucket `caisual`, servito pubblicamente da `assets.caisual.com`, deve
10
+ * continuare a ospitare gli asset storici citati con URL assoluti dai giochi.
11
+ * L'HTML giocabile invece sta nel bucket privato `caisual-games`, accessibile
12
+ * soltanto tramite i binding dei nostri Worker.
13
+ *
14
+ * Pubblicare anche l'HTML su `assets.caisual.com` permetterebbe di aprirlo
15
+ * senza passare da `play`. Basterebbe cambiare hostname per aggirare la
16
+ * trasformazione di runtime, la CSP, `frame-ancestors` e la Permissions-Policy.
17
+ * Il bucket separato rende obbligatorio il passaggio dal Worker che applica
18
+ * queste difese.
19
+ */
20
+ /**
21
+ * ## Perche' lo slug sta DENTRO la chiave
22
+ *
23
+ * Il sottodominio da solo non isola gli oggetti. Se la chiave contenesse solo
24
+ * il numero di versione, questo URL potrebbe servire codice di un altro gioco
25
+ * dentro l'origine della vittima:
26
+ *
27
+ * https://vittima.caisual.app/rt/v1/<n-di-un-altro-gioco>/index.html
28
+ *
29
+ * Con `games/<slug>/<n>/...`, `play` prende lo slug dall'hostname e cerca solo
30
+ * sotto quel prefisso. I file dell'attaccante non esistono quindi nell'origine
31
+ * della vittima. Lo slug non cambia e la lapide ne impedisce il riuso, percio'
32
+ * la chiave resta stabile quanto l'id numerico.
33
+ */
34
+ /** Prefisso di tutto cio' che appartiene a uno slug. */
35
+ export declare function gamePrefix(slug: string): string;
36
+ /** Prefisso immutabile di una versione progressiva. */
37
+ export declare function gameVersionPrefix(slug: string, n: number): string;
38
+ /**
39
+ * Chiave di un file relativo dentro una versione.
40
+ * `path` deve essere gia' passato da `normalizeAssetPath`.
41
+ */
42
+ export declare function versionFileKey(slug: string, n: number, path: string): string;
43
+ export declare function artifactKey(slug: string, n: number): string;
44
+ export declare function coverKey(slug: string, n: number): string;
45
+ /** Manifest immutabile che descrive la versione servita da play. */
46
+ export declare function manifestKey(slug: string, n: number): string;
47
+ /**
48
+ * Normalizza il path richiesto dentro una versione e lo decodifica.
49
+ *
50
+ * La decodifica serve sia ai nomi con spazi o caratteri non ASCII, che il
51
+ * browser invia percent-encoded, sia alla sicurezza: la risalita va controllata
52
+ * DOPO la decodifica, altrimenti `%2e%2e` supererebbe il controllo.
53
+ *
54
+ * I segmenti vuoti vengono collassati invece di essere rifiutati. Il server
55
+ * storico faceva lo stesso e i giochi sono immutabili, quindi un riferimento
56
+ * come `src="assets//sprite.png"` deve continuare a funzionare. La cache usa la
57
+ * chiave normalizzata e non crea due copie per i doppi slash.
58
+ */
59
+ export declare function normalizeAssetPath(rawPath: string): string | null;
@@ -0,0 +1,118 @@
1
+ export type Platform = 'desktop' | 'mobile' | 'both';
2
+ export type Orientation = 'landscape' | 'portrait';
3
+ export type Input = 'keyboard' | 'mouse' | 'touch' | 'gamepad';
4
+ export type Visibility = 'public' | 'unlisted';
5
+ export type Voice = 'none' | 'room' | 'team' | 'proximity';
6
+ export interface ManifestPlayers {
7
+ min: number;
8
+ max: number;
9
+ }
10
+ export interface ManifestRole {
11
+ label?: string;
12
+ id: string;
13
+ min: number;
14
+ max?: number;
15
+ }
16
+ export interface ManifestTeams {
17
+ min: number;
18
+ max: number;
19
+ }
20
+ export interface ManifestMatchmaking {
21
+ defaults?: Record<string, string | number>;
22
+ key: string[];
23
+ timeoutMs: number;
24
+ }
25
+ export interface ManifestRequires {
26
+ webgl2: boolean;
27
+ webgpu: boolean;
28
+ wasm: boolean;
29
+ threads: boolean;
30
+ memoryMb: number | null;
31
+ performance: 'light' | 'medium' | 'heavy';
32
+ }
33
+ export interface ManifestSpectators {
34
+ delayMs: number;
35
+ }
36
+ export type BoardPeriod = 'daily' | 'all-time';
37
+ export type ModeExecution = 'local' | 'room';
38
+ export interface ManifestOverlay {
39
+ version: 1;
40
+ accent?: string;
41
+ }
42
+ export interface ManifestBoard {
43
+ label?: string;
44
+ periods?: BoardPeriod[];
45
+ source: 'client' | 'server';
46
+ }
47
+ export interface ManifestMode {
48
+ execution?: ModeExecution;
49
+ label?: string;
50
+ instructions?: string;
51
+ id: string;
52
+ players?: ManifestPlayers;
53
+ lobby?: boolean;
54
+ matchmaking?: ManifestMatchmaking;
55
+ }
56
+ export interface ModalitaRisolta {
57
+ players: ManifestPlayers;
58
+ lobby: boolean;
59
+ }
60
+ export type ManifestModalita = ModalitaRisolta & {
61
+ modes: ManifestMode[];
62
+ };
63
+ export declare function risolviModalita(manifest: ManifestModalita, mode: string | null): ModalitaRisolta;
64
+ export declare function risolviPresentazione(manifest: ManifestModalita & {
65
+ name?: string;
66
+ }, mode: string | null): {
67
+ execution: ModeExecution | null;
68
+ label: string;
69
+ instructions: string | null;
70
+ };
71
+ export declare function richiedeServer(manifest: Pick<Manifest, 'modes'>): boolean;
72
+ export declare function modalitaLocale(manifest: Pick<Manifest, 'modes'>, mode: string | null): boolean;
73
+ export interface Manifest {
74
+ overlay?: ManifestOverlay | null;
75
+ manifest: 1;
76
+ id: string;
77
+ name: string;
78
+ description: string;
79
+ cover: string | null;
80
+ screenshots: string[];
81
+ tags: string[];
82
+ language: string;
83
+ platform: Platform;
84
+ orientation: Orientation;
85
+ input: Input[];
86
+ visibility: Visibility;
87
+ network: string[];
88
+ isolated: boolean;
89
+ requires: ManifestRequires;
90
+ players: ManifestPlayers;
91
+ lobby: boolean;
92
+ persistent: boolean;
93
+ spectators: ManifestSpectators | null;
94
+ boards: Record<string, ManifestBoard>;
95
+ roles: ManifestRole[];
96
+ teams: ManifestTeams | null;
97
+ voice: Voice;
98
+ modes: ManifestMode[];
99
+ }
100
+ export type EsitoManifest = {
101
+ ok: true;
102
+ manifest: Manifest;
103
+ } | {
104
+ ok: false;
105
+ errori: string[];
106
+ };
107
+ export declare const TETTO_GIOCATORI = 24;
108
+ export declare const MASSIMO_SPETTATORI = 100;
109
+ export declare const RITARDO_SPETTATORI_MS = 3000;
110
+ export declare const MASSIMO_CLASSIFICHE = 32;
111
+ export declare function sorgenteClassifica(manifest: {
112
+ boards?: Record<string, ManifestBoard>;
113
+ }, board: string): 'client' | 'server';
114
+ /**
115
+ * Valida tutto il documento in un solo passaggio e restituisce tutti gli
116
+ * errori. Un agente puo' cosi' correggere il file senza tentativi ripetuti.
117
+ */
118
+ export declare function validaManifest(valore: unknown): EsitoManifest;
@@ -0,0 +1,3 @@
1
+ import type { Manifest } from './manifest.js';
2
+ export declare function overlayBoardError(manifest: Manifest, board: string, params: URLSearchParams): string | null;
3
+ export declare function overlayReadOrigin(origin: string | null, site: string | null, expected: string): boolean;
@@ -0,0 +1,215 @@
1
+ import { type Manifest } from './manifest.js';
2
+ export declare const OVERLAY_VERSION: 1;
3
+ export declare const OVERLAY_PANELS: readonly ['home', 'room', 'invite', 'friends', 'voice', 'boards'];
4
+ export type OverlayPanel = typeof OVERLAY_PANELS[number];
5
+ export type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'ended' | 'closed' | 'replaced';
6
+ export interface ReservedRect {
7
+ x: number;
8
+ y: number;
9
+ width: number;
10
+ height: number;
11
+ }
12
+ export interface OverlayView {
13
+ inputBlocked: boolean;
14
+ reservedRects: ReservedRect[];
15
+ shortcutEnabled?: boolean;
16
+ }
17
+ export interface OverlayConfiguration {
18
+ manifest: Manifest;
19
+ coverUrl: string | null;
20
+ invite: string | null;
21
+ }
22
+ export interface OverlayCapabilities {
23
+ local: boolean;
24
+ rooms: boolean;
25
+ overlay: boolean;
26
+ requestRole: boolean;
27
+ }
28
+ export interface OverlayPlayer {
29
+ id: string;
30
+ name: string;
31
+ guest: boolean;
32
+ role: string | null;
33
+ team: number | null;
34
+ ready: boolean;
35
+ connected: boolean;
36
+ }
37
+ export interface QueuedScore {
38
+ board: string;
39
+ player: string;
40
+ score: number;
41
+ day: string | null;
42
+ submittedAt: number;
43
+ }
44
+ export interface SessionResume {
45
+ version: 1;
46
+ code: string;
47
+ mode: string | null;
48
+ updatedAt: number;
49
+ }
50
+ export interface OverlayRoom {
51
+ code: string;
52
+ mode: string | null;
53
+ status: 'lobby' | 'countdown' | 'playing' | 'ended';
54
+ host: string | null;
55
+ you: string | null;
56
+ players: OverlayPlayer[];
57
+ countdownAt: number | null;
58
+ connection: ConnectionState;
59
+ closedCode: number | null;
60
+ limits: {
61
+ min: number;
62
+ max: number;
63
+ };
64
+ lobby: boolean;
65
+ persistent: boolean;
66
+ delayMs: number | null;
67
+ requestRole: boolean;
68
+ }
69
+ export interface OverlayVoicePeer {
70
+ id: string;
71
+ mic: boolean;
72
+ muted: boolean;
73
+ speaking: boolean;
74
+ volume: number;
75
+ }
76
+ export interface OverlayVoice {
77
+ mode: 'room' | 'team' | 'proximity';
78
+ state: 'off' | 'joining' | 'on' | 'reconnecting';
79
+ mic: boolean;
80
+ muted: boolean;
81
+ speaking: boolean;
82
+ peers: OverlayVoicePeer[];
83
+ }
84
+ export interface OverlaySessionState {
85
+ kind: 'boot' | 'home' | 'attaching' | 'matching' | 'local' | 'room' | 'watch';
86
+ id: string | null;
87
+ mode: string | null;
88
+ localStatus: 'playing' | 'ended' | null;
89
+ ready: boolean;
90
+ capabilities: OverlayCapabilities;
91
+ room: OverlayRoom | null;
92
+ waiting: {
93
+ players: number;
94
+ min: number;
95
+ max: number;
96
+ } | null;
97
+ resume: SessionResume | null;
98
+ resumeError: boolean;
99
+ voice?: OverlayVoice | null;
100
+ }
101
+ export interface OverlayOperations {
102
+ 'local.start': {
103
+ mode: string;
104
+ };
105
+ 'room.create': {
106
+ mode: string | null;
107
+ };
108
+ 'room.join': {
109
+ code?: string;
110
+ };
111
+ 'room.watch': {
112
+ code: string;
113
+ };
114
+ 'room.match': {
115
+ mode: string;
116
+ key?: Record<string, string | number>;
117
+ };
118
+ 'room.ready': {
119
+ ready: boolean;
120
+ };
121
+ 'room.role': {
122
+ role: string;
123
+ };
124
+ 'room.requestRole': {
125
+ role: string;
126
+ };
127
+ 'room.team': {
128
+ team: number;
129
+ };
130
+ 'room.start': Record<string, never>;
131
+ 'session.cancel': Record<string, never>;
132
+ 'session.leave': Record<string, never>;
133
+ 'session.disconnect': Record<string, never>;
134
+ 'session.resume': Record<string, never>;
135
+ 'overlay.view': OverlayView;
136
+ 'voice.join': Record<string, never>;
137
+ 'voice.mute': {
138
+ muted: boolean;
139
+ };
140
+ 'voice.leave': Record<string, never>;
141
+ 'voice.setVolume': {
142
+ playerId: string;
143
+ volume: number;
144
+ };
145
+ }
146
+ export type OverlayRequest = {
147
+ [K in keyof OverlayOperations]: {
148
+ type: 'caisual:overlay';
149
+ v: 1;
150
+ epoch: string;
151
+ requestId: string;
152
+ sessionId?: string | null;
153
+ op: K;
154
+ args: OverlayOperations[K];
155
+ };
156
+ }[keyof OverlayOperations];
157
+ export type OverlayResponse = {
158
+ type: 'caisual:overlay-response';
159
+ v: 1;
160
+ epoch: string;
161
+ requestId: string;
162
+ } & ({
163
+ ok: true;
164
+ } | {
165
+ ok: false;
166
+ error: {
167
+ code: string;
168
+ message: string;
169
+ };
170
+ });
171
+ export type OverlayEvent = {
172
+ type: 'caisual:overlay-state';
173
+ v: 1;
174
+ epoch: string;
175
+ seq: number;
176
+ serverTime: number;
177
+ state: OverlaySessionState;
178
+ } | {
179
+ type: 'caisual:overlay-shortcut';
180
+ v: 1;
181
+ epoch: string;
182
+ } | {
183
+ type: 'caisual:overlay-open';
184
+ v: 1;
185
+ epoch: string;
186
+ panel: OverlayPanel;
187
+ } | {
188
+ type: 'caisual:overlay-error';
189
+ v: 1;
190
+ epoch: string;
191
+ sessionId: string;
192
+ error: {
193
+ code: string;
194
+ message: string;
195
+ };
196
+ } | {
197
+ type: 'caisual:overlay-score';
198
+ v: 1;
199
+ epoch: string;
200
+ score: QueuedScore;
201
+ };
202
+ export interface OverlayHello {
203
+ v: 1;
204
+ epoch: string;
205
+ configuration: OverlayConfiguration;
206
+ }
207
+ export declare function overlayConfiguration(manifest: Manifest, coverUrl?: string | null, invite?: string | null): OverlayConfiguration;
208
+ export declare function record(value: unknown): Record<string, unknown> | null;
209
+ export declare function validOverlayHello(value: unknown): value is OverlayHello;
210
+ export declare function normalizeOverlayHello(value: unknown): OverlayHello | null;
211
+ export declare function validOverlayView(value: unknown): value is OverlayView;
212
+ export declare function validOverlayRequest(value: unknown): value is OverlayRequest;
213
+ export declare function validBoardDay(value: unknown): value is string;
214
+ export declare function validOverlaySessionState(value: unknown): value is OverlaySessionState;
215
+ export declare function validOverlayVoice(value: unknown): value is OverlayVoice;
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Contratto sulla forma degli URL di gioco, condiviso fra i due Worker.
3
+ *
4
+ * `portal` costruisce l'URL da mettere nell'iframe, `play` lo interpreta. Sono due
5
+ * Worker distinti su due domini distinti: se la forma dell'URL vivesse in
6
+ * entrambi, prima o poi divergerebbero e il sintomo sarebbe un 404 su tutti i
7
+ * giochi. Vive qui, una volta sola.
8
+ *
9
+ * ## Cos'e' la versione di runtime
10
+ *
11
+ * Prima di servirlo, `play` inietta nell'HTML del gioco il viewport, lo stile
12
+ * touch e lo script anti pinch-zoom: cose che nel sistema vecchio metteva la
13
+ * pagina padre entrando nel DOM dell'iframe, e che ora non puo' piu' fare
14
+ * perche' il gioco sta su un'altra origine.
15
+ *
16
+ * Il risultato di quell'iniezione finisce in cache. Se un domani cambiamo cosa
17
+ * iniettiamo senza cambiare niente altro, le cache continuerebbero a servire la
18
+ * versione vecchia della trasformazione su un artefatto che non e' cambiato, e
19
+ * non ci sarebbe modo di invalidarle se non a mano.
20
+ *
21
+ * Mettendo la versione nell'URL il problema sparisce: una trasformazione nuova
22
+ * e' `rt/v2`, cioe' un URL nuovo, e le due non si incontrano mai. L'artefatto su
23
+ * R2 resta intatto in entrambi i casi.
24
+ */
25
+ /** Versioni di runtime che sappiamo servire. Non se ne toglie mai una. */
26
+ declare const RUNTIME_VERSIONS: readonly ['v1'];
27
+ export type RuntimeVersion = (typeof RUNTIME_VERSIONS)[number];
28
+ export declare function isRuntimeVersion(value: string): value is RuntimeVersion;
29
+ /**
30
+ * Path di un file di gioco sull'origine di `play`.
31
+ * Forma: `/rt/{runtime}/{n}/{path}`.
32
+ *
33
+ * Lo slug NON sta nel path: sta nell'hostname. Vedi `playOrigin`.
34
+ */
35
+ export declare function playPath(n: number, path?: string, runtime?: RuntimeVersion): string;
36
+ /**
37
+ * Origine su cui gira un gioco: `https://<slug>.<dominio>`.
38
+ *
39
+ * Un'origine per slug, non per versione. La differenza conta: con
40
+ * un'origine per versione ogni improve creerebbe una partizione di storage
41
+ * nuova, e il giocatore perderebbe i progressi ogni volta che l'autore migliora
42
+ * il gioco. Con l'origine per slug le versioni condividono lo storage (che
43
+ * e' quello che ci si aspetta dallo stesso gioco) e giochi diversi no.
44
+ *
45
+ * Anche gli UUID v4 dei giochi storici sono slug validi, percio' conservano
46
+ * origine, storage e link esistenti.
47
+ */
48
+ export declare function playOrigin(slug: string, domain: string): string;
49
+ /**
50
+ * Le origini di play tutte insieme, per la CSP: `https://*.<dominio>`.
51
+ *
52
+ * Sta accanto a `playOrigin` apposta. Una pagina che mostra venti copertine
53
+ * punta a venti origini diverse, una per gioco, quindi nella CSP non si puo'
54
+ * elencarle: serve il carattere jolly. Tenendo le due funzioni vicine, se
55
+ * cambia la forma dell'origine si vede subito che va cambiata anche qui.
56
+ *
57
+ * L'alternativa sarebbe stata servire le copertine dall'app, ma sono oggetti
58
+ * immutabili gia' su R2 con la loro cache: farle passare da qui vorrebbe dire
59
+ * pagare una richiesta al Worker per ogni scheda di ogni griglia.
60
+ */
61
+ export declare function playOriginPattern(domain: string): string;
62
+ /**
63
+ * Estrae lo slug dall'hostname, o `null` se l'host non ha la forma attesa.
64
+ *
65
+ * `play` deve usare QUESTO slug per risolvere il gioco, mai uno preso dal path:
66
+ * e' l'unico modo perche' una versione di un altro gioco non possa
67
+ * essere servita nell'origine sbagliata.
68
+ */
69
+ export declare function slugFromHostname(hostname: string, domain: string): string | null;
70
+ export {};
@@ -0,0 +1,11 @@
1
+ export declare const MASSIMO_BYTE_SERVER_JS = 1000000;
2
+ /** Il modulo pubblico va risolto nel kit incluso insieme al sorgente del creatore. */
3
+ export declare function riscriviImportServerJs(sorgente: string): string;
4
+ export type EsitoServerJs = {
5
+ ok: true;
6
+ } | {
7
+ ok: false;
8
+ errori: string[];
9
+ };
10
+ /** Valida le regole che rendono server.js componibile come modulo singolo. */
11
+ export declare function validaServerJs(sorgente: string): EsitoServerJs;
@@ -0,0 +1,5 @@
1
+ /** Nomi che non possono diventare l'origine di un gioco. */
2
+ export declare const NOMI_RISERVATI: readonly ['www', 'api', 'app', 'play', 'live', 'multi', 'cdn', 'assets', 'static', 'mail', 'mx', 'ns1', 'ns2', 'autodiscover', '_dmarc', 'admin', 'login', 'account', 'auth', 'pay', 'secure', 'support', 'help', 'blog', 'status', 'dev', 'staging', 'test', 'caisual', 'shipz'];
3
+ /** Controlla solo la forma; i nomi riservati hanno un controllo separato. */
4
+ export declare function isValidSlug(value: string): boolean;
5
+ export declare function isReservedSlug(value: string): boolean;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Gettone della crew: apre il socket di presenza sul servizio live dal portale.
3
+ *
4
+ * Non porta un gioco perche' la crew attraversa tutti i giochi; il destinatario
5
+ * e' fisso, quindi un biglietto di gioco non puo' essere riusato qui e viceversa.
6
+ */
7
+ export interface TokenCrew {
8
+ sub: string;
9
+ name: string;
10
+ aud: 'crew';
11
+ iat: number;
12
+ exp: number;
13
+ }
14
+ export declare function firmaTokenCrew(input: {
15
+ sub: string;
16
+ name: string;
17
+ }, secret: string, now?: Date): Promise<string>;
18
+ /** Restituisce null senza distinguere quale controllo ha rifiutato il gettone. */
19
+ export declare function verificaTokenCrew(token: string, secret: string, atteso?: {
20
+ now?: Date;
21
+ }): Promise<TokenCrew | null>;
@@ -0,0 +1,3 @@
1
+ export declare function giornoUtc(ora: number): string;
2
+ export declare function calcolaSeed(gioco: string, giorno: string, subtle: SubtleCrypto): Promise<number>;
3
+ export declare function creaMulberry32(seed: number): () => number;
@@ -0,0 +1,6 @@
1
+ export type ErroreCaisual = Error & {
2
+ code: string;
3
+ };
4
+ export declare function creaErrore(code: string, message: string): ErroreCaisual;
5
+ export declare function erroreOffline(): ErroreCaisual;
6
+ export declare function codiceErrore(valore: unknown): unknown;
@@ -0,0 +1,26 @@
1
+ import { type OverlayHello } from './contracts/index.js';
2
+ export interface GenitoreHandshake {
3
+ postMessage(message: unknown, targetOrigin: string): void;
4
+ }
5
+ export interface FinestraHandshakeKit extends GenitoreHandshake {
6
+ readonly parent: GenitoreHandshake;
7
+ addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
8
+ removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
9
+ setTimeout(handler: () => void, timeout: number): number;
10
+ clearTimeout(id: number): void;
11
+ }
12
+ export interface EsitoHandshake {
13
+ overlay?: OverlayHello;
14
+ ticket: string;
15
+ live: string | null;
16
+ invite: string | null;
17
+ porta: MessagePort;
18
+ }
19
+ export type DestinatarioBiglietto = 'portal' | 'live';
20
+ /** Il limite evita che un gioco copiato aspetti un contenitore che non esiste. */
21
+ export declare function attendiHandshake(finestra: FinestraHandshakeKit, appOrigin: string, timeoutMs?: number): Promise<EsitoHandshake | null>;
22
+ export interface GestoreBiglietto {
23
+ ottieni(): Promise<string>;
24
+ rinnova(): Promise<string>;
25
+ }
26
+ export declare function creaGestoreBiglietto(ticketIniziale: string | null, porta: MessagePort, finestra: Pick<FinestraHandshakeKit, 'setTimeout' | 'clearTimeout'>, ora: () => number, timeoutMs?: number, aud?: DestinatarioBiglietto): GestoreBiglietto;
@@ -0,0 +1,3 @@
1
+ import type { GestoreBiglietto } from './handshake.js';
2
+ export type MetodoHttp = 'GET' | 'PUT' | 'POST' | 'DELETE';
3
+ export declare function creaRichiedente(origin: string, prefix: string, fetcher: typeof fetch, biglietto: GestoreBiglietto): <T>(path: string, metodo: MetodoHttp, corpo?: unknown, forzaRinnovo?: boolean) => Promise<T>;