@crowdedkingdoms/crowdyjs 17.6.0 → 17.7.0-dev.1

package/dist/grid-mods/grid-host-calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid-host-calls.d.ts","sourceRoot":"","sources":["../../src/grid-mods/grid-host-calls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;QAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACtF,aAAa,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,QAAQ,CAAC,CAAC,KAAK,EAAE;QACf,KAAK,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB,kBAAkB,CAAC,IAAI,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,KAAK,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE;QACN,MAAM,EAAE,SAAS,CAAC;QAClB,MAAM,EAAE,SAAS,CAAC;QAClB,KAAK,EAAE,QAAQ,CAAC;QAChB,SAAS,EAAE,YAAY,CAAC;KACzB,CAAC;IACF,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sEAAsE;AACtE,qBAAa,mBAAoB,SAAQ,KAAK;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM;gBAAV,EAAE,EAAE,MAAM,EAAE,MAAM,SAA+B;CAIvE;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CA4KhD"}

package/dist/grid-mods/grid-host-calls.js

@@ -0,0 +1,220 @@
+/** Thrown for a host call this game does not offer in the browser. */
+export class GridHostCallRefused extends Error {
+    constructor(fn, reason = 'not offered in the browser') {
+        super(`host call '${fn}' ${reason}`);
+        this.fn = fn;
+        this.name = 'GridHostCallRefused';
+    }
+}
+const SPATIAL_KINDS = new Set(['actor', 'client_event', 'server_event', 'text']);
+/**
+ * The page-side answer to every CLIENT host call in the platform catalog,
+ * through ordinary CrowdyJS confined to one grid (DN-10 §4). Hand the result
+ * to `PlayerCodeBroker({ onHostCall })`; the broker has already applied the
+ * allowlist, rate caps and chunk clamps, and answers `grid_info`, `emit_event`,
+ * `hud_set` and `overlay_draw` itself.
+ */
+export function createGridHostCalls(options) {
+    const { scope, client, local } = options;
+    const appId = scope.appId;
+    let gridChannels = null;
+    const ownChannels = () => (gridChannels ?? (gridChannels = scope.channels
+        .list()
+        .then((rows) => new Set(rows.map((row) => String(row.groupId))))
+        .catch(() => {
+        gridChannels = null;
+        return new Set();
+    })));
+    const channelAllowed = async (channelId) => options.channelFilter
+        ? options.channelFilter(channelId)
+        : (await ownChannels()).has(channelId);
+    const uuid = (args) => typeof args.uuidHex === 'string' && /^[0-9a-f]{64}$/i.test(args.uuidHex)
+        ? hexToAscii(args.uuidHex)
+        : (options.actorUuid ?? '0'.repeat(32));
+    return async ({ fn, args }) => {
+        switch (fn) {
+            case 'chunk_get': {
+                const [x, y, z] = coords(args.x, args.y, args.z);
+                scope.assertContains({ x, y, z });
+                const hit = local?.chunkVoxels?.(x, y, z);
+                if (hit !== undefined)
+                    return { voxelsBase64: hit?.voxelsBase64 ?? null };
+                const chunk = await client.chunks.get({
+                    appId,
+                    coordinates: { x: x.toString(), y: y.toString(), z: z.toString() },
+                });
+                return { voxelsBase64: chunk?.voxels ?? null };
+            }
+            case 'voxels_list': {
+                const [x, y, z] = coords(args.x, args.y, args.z);
+                scope.assertContains({ x, y, z });
+                return {
+                    voxels: await client.voxels.list({
+                        appId,
+                        coordinates: { x: x.toString(), y: y.toString(), z: z.toString() },
+                    }),
+                };
+            }
+            case 'actors_list':
+            case 'actors_list_radius': {
+                const [x, y, z] = coords(args.x, args.y, args.z);
+                scope.assertContains({ x, y, z });
+                if (!local?.actorsInChunk)
+                    throw new GridHostCallRefused(fn);
+                // Same clamps as the server host: radiusXz <= 3, radiusY <= 1, box-clipped.
+                const rXz = fn === 'actors_list' ? 0n : BigInt(clampInt(args.radiusXz ?? args.radius, 0, 3));
+                const rY = fn === 'actors_list' ? 0n : BigInt(clampInt(args.radiusY, 0, 1));
+                const box = scope.bounds;
+                const actors = [];
+                for (let cx = max(box.low.x, x - rXz); cx <= min(box.high.x, x + rXz); cx++)
+                    for (let cy = max(box.low.y, y - rY); cy <= min(box.high.y, y + rY); cy++)
+                        for (let cz = max(box.low.z, z - rXz); cz <= min(box.high.z, z + rXz); cz++)
+                            actors.push(...local.actorsInChunk(cx, cy, cz));
+                return { actors };
+            }
+            case 'voxel_set': {
+                const chunk = coords(args.chunkX, args.chunkY, args.chunkZ);
+                scope.assertContains({ x: chunk[0], y: chunk[1], z: chunk[2] });
+                const voxel = {
+                    x: Number(args.voxelX ?? 0),
+                    y: Number(args.voxelY ?? 0),
+                    z: Number(args.voxelZ ?? 0),
+                };
+                const voxelType = Number(args.voxelType ?? 0);
+                const state = typeof args.stateBase64 === 'string' ? args.stateBase64 : undefined;
+                if (local?.setVoxel) {
+                    return {
+                        ok: await local.setVoxel({
+                            chunk: { x: Number(chunk[0]), y: Number(chunk[1]), z: Number(chunk[2]) },
+                            ...voxel,
+                            voxelType,
+                            state,
+                        }),
+                    };
+                }
+                await client.voxels.update({
+                    appId,
+                    coordinates: { x: chunk[0].toString(), y: chunk[1].toString(), z: chunk[2].toString() },
+                    location: voxel,
+                    voxelType,
+                    ...(state ? { state } : {}),
+                });
+                return { ok: true };
+            }
+            case 'emit_spatial': {
+                const kind = String(args.kind ?? '');
+                if (!SPATIAL_KINDS.has(kind))
+                    throw new GridHostCallRefused(fn, 'has an unknown kind');
+                const [x, y, z] = coords(args.chunkX, args.chunkY, args.chunkZ);
+                const chunk = { x: x.toString(), y: y.toString(), z: z.toString() };
+                const payload = String(args.payloadBase64 ?? '');
+                const distance = Math.max(0, Math.min(8, Number(args.distance ?? 0) | 0));
+                const common = { chunk, uuid: uuid(args), distance };
+                if (kind === 'actor')
+                    return scope.send.actorUpdate({ ...common, state: payload });
+                if (kind === 'text') {
+                    return scope.send.text({ ...common, text: atob(payload) });
+                }
+                // client_event / server_event: [u16 eventType LE][state]
+                const bytes = base64Bytes(payload);
+                if (bytes.length < 2)
+                    throw new GridHostCallRefused(fn, 'needs a uint16 eventType prefix');
+                return scope.send.clientEvent({
+                    ...common,
+                    eventType: bytes[0] | (bytes[1] << 8),
+                    state: bytesBase64(bytes.subarray(2)),
+                });
+            }
+            case 'emit_channel': {
+                const channelId = String(args.channelId ?? '');
+                if (!(await channelAllowed(channelId))) {
+                    throw new GridHostCallRefused(fn, 'targets a channel outside this grid');
+                }
+                return scope.channels.send(channelId, uuid(args), String(args.payloadBase64 ?? ''));
+            }
+            case 'container_create':
+                return scope.model.create({
+                    typeKey: typeof args.typeName === 'string' ? args.typeName : undefined,
+                    displayName: typeof args.displayName === 'string' ? args.displayName : undefined,
+                    stateJson: JSON.stringify(args.state ?? args.properties ?? {}),
+                });
+            case 'container_get':
+                return scope.model.container(String(args.containerId));
+            case 'container_get_batch': {
+                const ids = Array.isArray(args.containerIds) ? args.containerIds.slice(0, 32) : [];
+                const found = await Promise.all(ids.map((id) => scope.model.container(String(id)).catch(() => null)));
+                return found.filter((c) => c != null);
+            }
+            case 'containers_list':
+                return scope.model.containers();
+            case 'container_delete':
+                return scope.model.delete(String(args.containerId));
+            case 'property_set':
+                return scope.model.set({
+                    containerId: String(args.containerId),
+                    propertyKey: String(args.key),
+                    valueJson: JSON.stringify(args.value ?? null),
+                });
+            case 'model_invoke':
+                if (!options.allowModelInvoke)
+                    throw new GridHostCallRefused(fn);
+                return client.gameModel.invoke({
+                    appId,
+                    functionName: String(args.functionName),
+                    selfContainerId: String(args.selfContainerId),
+                    paramsJson: JSON.stringify(args.params ?? {}),
+                    ...(typeof args.sessionId === 'string' ? { sessionId: args.sessionId } : {}),
+                });
+            case 'sessions_list':
+                return scope.sessions.list(typeof args.status === 'string' ? { status: args.status } : {});
+            case 'user_state_get':
+                return client.state.getOne(appId);
+            case 'user_state_set':
+                return client.state.update({
+                    appId,
+                    state: typeof args.stateBase64 === 'string' ? args.stateBase64 : null,
+                });
+            case 'pointer_clicks':
+                if (!local?.drainPointerClicks)
+                    throw new GridHostCallRefused(fn);
+                return local.drainPointerClicks();
+            default:
+                // edge_*, grid_state_*, avatar_state_get and grid_permission_check have
+                // no browser GraphQL surface yet: the server host answers them for
+                // SERVER mods.
+                throw new GridHostCallRefused(fn);
+        }
+    };
+}
+function coords(x, y, z) {
+    return [BigInt(x), BigInt(y), BigInt(z)];
+}
+function clampInt(value, lo, hi) {
+    const n = Number(value ?? lo);
+    return Number.isFinite(n) ? Math.max(lo, Math.min(hi, Math.trunc(n))) : lo;
+}
+function min(a, b) {
+    return a < b ? a : b;
+}
+function max(a, b) {
+    return a > b ? a : b;
+}
+function hexToAscii(hex) {
+    let out = '';
+    for (let i = 0; i < hex.length; i += 2)
+        out += String.fromCharCode(parseInt(hex.slice(i, i + 2), 16));
+    return out;
+}
+function base64Bytes(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function bytesBase64(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}

package/dist/grid-mods/index.d.ts

@@ -0,0 +1,3 @@
+export { createGridHostCalls, GridHostCallRefused, type GridHostCallsOptions, type GridHostLocal, } from './grid-host-calls.js';
+export { startGridMod, type GridModSpec, type WasmGridModSpec, type ProgramGridModSpec, type RunningGridMod, type StartGridModOptions, } from './mod-runtime.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/grid-mods/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/grid-mods/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC"}

package/dist/grid-mods/index.js

@@ -0,0 +1,2 @@
+export { createGridHostCalls, GridHostCallRefused, } from './grid-host-calls.js';
+export { startGridMod, } from './mod-runtime.js';

package/dist/grid-mods/mod-runtime.d.ts

@@ -0,0 +1,52 @@
+import { type PlayerCodePresentation } from '../player-runtime/player-code-broker.js';
+import type { GridProgramPort } from '../grid-program/protocol.js';
+import type { GridScope } from '../grid-scope.js';
+import { type GridHostCallsOptions, type GridHostLocal } from './grid-host-calls.js';
+/** A Rust CLIENT mod: platform-built WASM run in the tokenless glue worker. */
+export interface WasmGridModSpec {
+    kind: 'wasm';
+    moduleName: string;
+    artifact: ArrayBuffer;
+    artifactHash?: string;
+    fuelPerDispatch?: bigint;
+    tickIntervalMs?: number;
+    /** The platform glue worker URL (`@crowdedkingdoms/crowdyjs/player-glue-worker`). */
+    workerUrl: string | URL;
+}
+/** A JS grid program: player code on the far side of a MessagePort. */
+export interface ProgramGridModSpec {
+    kind: 'program';
+    moduleName: string;
+    /** The page's end of the channel whose other end the sandbox holds. */
+    port: GridProgramPort;
+    ttlSeconds?: number;
+}
+export type GridModSpec = WasmGridModSpec | ProgramGridModSpec;
+export interface StartGridModOptions {
+    spec: GridModSpec;
+    /** The grid, with its box (`client.grid(...)` after `mintToken()`, or passed in). */
+    scope: GridScope;
+    /** The page's CrowdyJS client (holds the player's app token). */
+    client: GridHostCallsOptions['client'];
+    /** ck-api endpoints, for grid programs. */
+    graphqlUrl?: string;
+    graphqlWsUrl?: string;
+    local?: GridHostLocal;
+    allowModelInvoke?: boolean;
+    onPresentation?: (presentation: PlayerCodePresentation) => void;
+    onStopped?: (reason: string) => void;
+}
+export interface RunningGridMod {
+    kind: GridModSpec['kind'];
+    moduleName: string;
+    stop(): void;
+}
+/**
+ * One way to run player code inside a grid, whatever it is written in (DN-10
+ * §4-5). Rust CLIENT mods get the full client host catalog through
+ * {@link createGridHostCalls}; JS grid programs get real CrowdyJS through a
+ * grid-token relay. Both are confined to `scope`'s grid, locally for UX and by
+ * the server for authority.
+ */
+export declare function startGridMod(options: StartGridModOptions): Promise<RunningGridMod>;
+//# sourceMappingURL=mod-runtime.d.ts.map

package/dist/grid-mods/mod-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod-runtime.d.ts","sourceRoot":"","sources":["../../src/grid-mods/mod-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC;CACzB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,IAAI,EAAE,eAAe,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAE/D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,qFAAqF;IACrF,KAAK,EAAE,SAAS,CAAC;IACjB,iEAAiE;IACjE,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACvC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAChE,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CA2CzB"}

package/dist/grid-mods/mod-runtime.js

@@ -0,0 +1,55 @@
+import { PlayerCodeBroker, } from '../player-runtime/player-code-broker.js';
+import { hostGridProgram } from '../grid-program/host.js';
+import { createGridHostCalls, } from './grid-host-calls.js';
+/**
+ * One way to run player code inside a grid, whatever it is written in (DN-10
+ * §4-5). Rust CLIENT mods get the full client host catalog through
+ * {@link createGridHostCalls}; JS grid programs get real CrowdyJS through a
+ * grid-token relay. Both are confined to `scope`'s grid, locally for UX and by
+ * the server for authority.
+ */
+export async function startGridMod(options) {
+    const { spec, scope } = options;
+    if (!scope.bounds)
+        await scope.mintToken();
+    const box = scope.bounds;
+    if (spec.kind === 'wasm') {
+        const broker = new PlayerCodeBroker({
+            workerUrl: spec.workerUrl,
+            grid: { low: box.low, high: box.high, gridId: scope.gridId },
+            moduleName: spec.moduleName,
+            artifactHash: spec.artifactHash,
+            fuelPerDispatch: spec.fuelPerDispatch,
+            tickIntervalMs: spec.tickIntervalMs,
+            onHostCall: createGridHostCalls({
+                scope,
+                client: options.client,
+                local: options.local,
+                allowModelInvoke: options.allowModelInvoke,
+            }),
+            onPresentation: options.onPresentation,
+            onCircuitOpen: (reason) => options.onStopped?.(reason),
+        });
+        await broker.start(spec.artifact);
+        return {
+            kind: 'wasm',
+            moduleName: spec.moduleName,
+            stop: () => broker.stop(),
+        };
+    }
+    if (!options.graphqlUrl || !options.graphqlWsUrl) {
+        throw new Error('a grid program needs graphqlUrl and graphqlWsUrl');
+    }
+    const host = await hostGridProgram({
+        port: spec.port,
+        scope,
+        graphqlUrl: options.graphqlUrl,
+        graphqlWsUrl: options.graphqlWsUrl,
+        ttlSeconds: spec.ttlSeconds,
+    });
+    return {
+        kind: 'program',
+        moduleName: spec.moduleName,
+        stop: () => host.stop(),
+    };
+}

package/dist/grid-program/host.d.ts

@@ -0,0 +1,88 @@
+import { type GridProgramPort } from './protocol.js';
+import type { GridScope } from '../grid-scope.js';
+/** A grid token as the host holds it. */
+export interface HeldGridToken {
+    token: string;
+    expiresAt: string | Date;
+    low: {
+        x: string;
+        y: string;
+        z: string;
+    };
+    high: {
+        x: string;
+        y: string;
+        z: string;
+    };
+}
+export interface GridProgramHostOptions {
+    /** The port to the program (the iframe's side of a MessageChannel). */
+    port: GridProgramPort;
+    appId: string;
+    gridId: string;
+    /** ck-api GraphQL HTTP endpoint (…/graphql). */
+    graphqlUrl: string;
+    /** ck-api GraphQL WebSocket endpoint (ws…/graphql). */
+    graphqlWsUrl: string;
+    /**
+     * Mint a grid token. Usually `() => scope.mintToken()` on the PAGE's client,
+     * which holds the player's app token; see {@link hostGridProgram}.
+     */
+    mintToken: () => Promise<HeldGridToken>;
+    /** Defaults to the global fetch / WebSocket. */
+    fetchImpl?: typeof fetch;
+    WebSocketImpl?: new (url: string, protocols?: string | string[]) => WebSocket;
+    /** Largest request body relayed (default 256 KiB). */
+    maxBodyBytes?: number;
+    /** Requests in flight at once (default 16). */
+    maxInFlight?: number;
+    /** WebSocket frames relayed per second per program (default 200). */
+    maxFramesPerSecond?: number;
+    /** Diagnostics for refusals (never receives the token). */
+    onRefused?: (reason: string) => void;
+}
+/**
+ * The page side of a grid program. It relays the program's CrowdyJS traffic
+ * to ck-api, attaching a GRID-SCOPED token the program never sees, so the
+ * server confines everything the program does to the grid (DN-10 §5). Local
+ * checks here are cheap refusals of obviously wrong traffic; the server is
+ * the authority.
+ */
+export declare class GridProgramHost {
+    private readonly options;
+    private held;
+    private minting;
+    private inFlight;
+    private readonly sockets;
+    private frameWindowStart;
+    private framesInWindow;
+    private stopped;
+    private readonly listener;
+    constructor(options: GridProgramHostOptions);
+    /** Mint the first token, announce the grid to the program, start relaying. */
+    start(): Promise<void>;
+    stop(): void;
+    private token;
+    private reply;
+    private refuse;
+    private onRequest;
+    private relayHttp;
+    private openSocket;
+    private relayFrame;
+}
+/**
+ * Host a grid program for one grid from the page's own client. Mints grid
+ * tokens through `scope.mintToken()` (the page holds the app token) and
+ * relays the program's traffic; returns the running host.
+ */
+export declare function hostGridProgram(options: {
+    port: GridProgramPort;
+    scope: GridScope;
+    graphqlUrl: string;
+    graphqlWsUrl: string;
+    ttlSeconds?: number;
+    onRefused?: (reason: string) => void;
+    fetchImpl?: typeof fetch;
+    WebSocketImpl?: GridProgramHostOptions['WebSocketImpl'];
+}): Promise<GridProgramHost>;
+//# sourceMappingURL=host.d.ts.map

package/dist/grid-program/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/grid-program/host.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IACxC,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,aAAa,CAAC,EAAE,KAAK,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,SAAS,CAAC;IAC9E,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAID;;;;;;GAMG;AACH,qBAAa,eAAe;IAYd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAXpC,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAEvB;gBAE2B,OAAO,EAAE,sBAAsB;IAE5D,8EAA8E;IACxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B,IAAI,IAAI,IAAI;YAOE,KAAK;IAYnB,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,MAAM;YAIA,SAAS;YAkBT,SAAS;YA4DT,UAAU;YA+BV,UAAU;CAqCzB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,aAAa,CAAC,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;CACzD,GAAG,OAAO,CAAC,eAAe,CAAC,CAsB3B"}

package/dist/grid-program/host.js

@@ -0,0 +1,231 @@
+import { parse } from 'graphql';
+import { GRID_PROGRAM_PROTOCOL_VERSION, GRID_PROGRAM_WS_PROTOCOL, } from './protocol.js';
+const REFRESH_MARGIN_MS = 60000;
+/**
+ * The page side of a grid program. It relays the program's CrowdyJS traffic
+ * to ck-api, attaching a GRID-SCOPED token the program never sees, so the
+ * server confines everything the program does to the grid (DN-10 §5). Local
+ * checks here are cheap refusals of obviously wrong traffic; the server is
+ * the authority.
+ */
+export class GridProgramHost {
+    constructor(options) {
+        this.options = options;
+        this.held = null;
+        this.minting = null;
+        this.inFlight = 0;
+        this.sockets = new Map();
+        this.frameWindowStart = 0;
+        this.framesInWindow = 0;
+        this.stopped = false;
+        this.listener = (event) => {
+            void this.onRequest(event.data);
+        };
+    }
+    /** Mint the first token, announce the grid to the program, start relaying. */
+    async start() {
+        const held = await this.token();
+        this.options.port.addEventListener('message', this.listener);
+        this.options.port.start?.();
+        this.reply({
+            t: 'hello',
+            v: GRID_PROGRAM_PROTOCOL_VERSION,
+            appId: this.options.appId,
+            gridId: this.options.gridId,
+            low: held.low,
+            high: held.high,
+        });
+    }
+    stop() {
+        this.stopped = true;
+        this.options.port.removeEventListener('message', this.listener);
+        for (const socket of this.sockets.values())
+            socket.close(1000, 'host stopped');
+        this.sockets.clear();
+    }
+    async token() {
+        const held = this.held;
+        if (held && new Date(held.expiresAt).getTime() - Date.now() > REFRESH_MARGIN_MS) {
+            return held;
+        }
+        this.minting ?? (this.minting = this.options.mintToken().finally(() => {
+            this.minting = null;
+        }));
+        this.held = await this.minting;
+        return this.held;
+    }
+    reply(message) {
+        if (this.stopped)
+            return;
+        this.options.port.postMessage(message);
+    }
+    refuse(reason) {
+        this.options.onRefused?.(reason);
+    }
+    async onRequest(raw) {
+        if (this.stopped || !raw || typeof raw !== 'object')
+            return;
+        const msg = raw;
+        switch (msg.t) {
+            case 'http':
+                return this.relayHttp(msg);
+            case 'ws-open':
+                return this.openSocket(msg);
+            case 'ws-send':
+                return this.relayFrame(msg);
+            case 'ws-close':
+                this.sockets.get(msg.sid)?.close(msg.code ?? 1000, msg.reason ?? '');
+                return;
+            default:
+                this.refuse('unknown message');
+        }
+    }
+    async relayHttp(msg) {
+        const fail = (message) => {
+            this.refuse(message);
+            this.reply({ t: 'http-error', id: msg.id, message });
+        };
+        if (!Number.isSafeInteger(msg.id) || typeof msg.body !== 'string') {
+            return fail('malformed request');
+        }
+        if (msg.body.length > (this.options.maxBodyBytes ?? 256 * 1024)) {
+            return fail('request body too large');
+        }
+        if (this.inFlight >= (this.options.maxInFlight ?? 16)) {
+            return fail('too many requests in flight');
+        }
+        let body;
+        try {
+            body = JSON.parse(msg.body);
+            if (typeof body.query !== 'string')
+                throw new Error('no query');
+            const ops = parse(body.query).definitions.filter((d) => d.kind === 'OperationDefinition');
+            if (ops.length !== 1 || ops[0].operation === 'subscription') {
+                throw new Error('one query or mutation per request');
+            }
+        }
+        catch (error) {
+            return fail(`refused: ${error.message}`);
+        }
+        this.inFlight += 1;
+        try {
+            const held = await this.token();
+            const response = await (this.options.fetchImpl ?? fetch)(this.options.graphqlUrl, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${held.token}`,
+                },
+                body: JSON.stringify({
+                    query: body.query,
+                    variables: body.variables ?? {},
+                    ...(typeof body.operationName === 'string'
+                        ? { operationName: body.operationName }
+                        : {}),
+                }),
+            });
+            this.reply({
+                t: 'http-result',
+                id: msg.id,
+                status: response.status,
+                body: await response.text(),
+            });
+        }
+        catch (error) {
+            this.reply({ t: 'http-error', id: msg.id, message: error.message });
+        }
+        finally {
+            this.inFlight -= 1;
+        }
+    }
+    async openSocket(msg) {
+        if (!Number.isSafeInteger(msg.sid) ||
+            this.sockets.has(msg.sid) ||
+            !Array.isArray(msg.protocols) ||
+            !msg.protocols.includes(GRID_PROGRAM_WS_PROTOCOL)) {
+            this.refuse('websocket open refused');
+            this.reply({ t: 'ws-closed', sid: msg.sid, code: 4400, reason: 'refused' });
+            return;
+        }
+        const Impl = this.options.WebSocketImpl ?? WebSocket;
+        const socket = new Impl(this.options.graphqlWsUrl, GRID_PROGRAM_WS_PROTOCOL);
+        this.sockets.set(msg.sid, socket);
+        socket.onopen = () => this.reply({ t: 'ws-opened', sid: msg.sid, protocol: socket.protocol });
+        socket.onmessage = (event) => this.reply({ t: 'ws-message', sid: msg.sid, data: String(event.data) });
+        socket.onerror = () => this.reply({ t: 'ws-error', sid: msg.sid, message: 'websocket error' });
+        socket.onclose = (event) => {
+            this.sockets.delete(msg.sid);
+            this.reply({
+                t: 'ws-closed',
+                sid: msg.sid,
+                code: event.code,
+                reason: event.reason,
+            });
+        };
+    }
+    async relayFrame(msg) {
+        const socket = this.sockets.get(msg.sid);
+        if (!socket || typeof msg.data !== 'string')
+            return;
+        const now = Date.now();
+        if (now - this.frameWindowStart >= 1000) {
+            this.frameWindowStart = now;
+            this.framesInWindow = 0;
+        }
+        if (++this.framesInWindow > (this.options.maxFramesPerSecond ?? 200)) {
+            this.refuse('websocket frame rate exceeded');
+            socket.close(4429, 'rate limited');
+            return;
+        }
+        let frame;
+        try {
+            frame = JSON.parse(msg.data);
+        }
+        catch {
+            this.refuse('malformed websocket frame');
+            return;
+        }
+        if (frame.type === 'connection_init') {
+            // The program's credentials are a placeholder: swap in the grid token.
+            const held = await this.token();
+            socket.send(JSON.stringify({
+                type: 'connection_init',
+                payload: {
+                    Authorization: `Bearer ${held.token}`,
+                    appId: this.options.appId,
+                    clientKind: 'grid-program',
+                },
+            }));
+            return;
+        }
+        socket.send(msg.data);
+    }
+}
+/**
+ * Host a grid program for one grid from the page's own client. Mints grid
+ * tokens through `scope.mintToken()` (the page holds the app token) and
+ * relays the program's traffic; returns the running host.
+ */
+export async function hostGridProgram(options) {
+    const host = new GridProgramHost({
+        port: options.port,
+        appId: options.scope.appId,
+        gridId: options.scope.gridId,
+        graphqlUrl: options.graphqlUrl,
+        graphqlWsUrl: options.graphqlWsUrl,
+        onRefused: options.onRefused,
+        fetchImpl: options.fetchImpl,
+        WebSocketImpl: options.WebSocketImpl,
+        mintToken: async () => {
+            const minted = await options.scope.mintToken(options.ttlSeconds);
+            return {
+                token: minted.token,
+                expiresAt: minted.expiresAt,
+                low: minted.lowChunk,
+                high: minted.highChunk,
+            };
+        },
+    });
+    await host.start();
+    return host;
+}