@crowdedkingdoms/construct 0.0.0 → 0.2.1-dev.1

package/README.md

@@ -1,3 +1,78 @@
 # @crowdedkingdoms/construct
 
-Placeholder. Install `@crowdedkingdoms/construct@dev` for real releases.
+The Construct framework: the Crowded Kingdoms platform layer and engine loop
+that [the-construct](https://github.com/CrowdedKingdoms/the-construct) starter
+and the games built on it share.
+
+| Layer | What it does |
+|---|---|
+| `engine/` | `GameLoop`, `SceneRouter`, `Input`, `Controls`, the `GameScene` contract |
+| `platform/` | Hosted sign-in and app entry (`AuthService`, `NetworkManager`), `GameSession`, World Stores presence and the pose codec, chat, voice, webcam, envScope storage |
+| `platform/exec/`, `platform/model/` | The game's world hub on ck-exec (`WorldHub`, one connection per page as `NetworkManager.worldHub`) and `ModelService`, which reads the pulse, programs and progression from it |
+| `platform/studio/` | The Crowdy Studio dock (the SERVER target as a ck-exec mod), grid claims and the world hub's claim registry (`GridService`), CLIENT mods for the player's grid and consented grid mods, the agent's player host |
+| `grid/` | JS grid programs (`GridProgramRunner`): player JavaScript with the full CrowdyJS SDK, sandboxed, relayed with a grid-scoped token |
+| `node/` | `security-headers` (site, `/dsh/`, `/grid-program.html`), `vite-plugins`, `construct-copy-dsh` |
+| `sandbox/boot` | The grid program sandbox bootstrap |
+
+It ships **TypeScript source** for Vite (it uses `?worker&url` and
+`import.meta.env`). Peer dependencies: `@crowdedkingdoms/crowdyjs` 17.7+ (17.12
+for `ModelService`, `GridService` and the Studio's SERVER target on ck-exec)
+and, for the Studio agent pane, `@crowdedkingdoms/crowdy-dsh` 0.4+.
+
+## Installing it
+
+Releases are on npm under one dist-tag per tier, and a game pins the exact
+version of its own tier, as it pins CrowdyJS:
+
+```bash
+npm install --save-exact @crowdedkingdoms/construct@dev   # a 0.2.0-dev.N build
+```
+
+`dev` is `X.Y.Z-dev.N`, `test` is `X.Y.Z-test.N`, and `prod` is `X.Y.Z` on
+`latest`. Each is published by the-construct's `publish-construct.yml` from a
+`construct/<tier>/vX.Y.Z` tag on a commit already in that tier's branch.
+
+## Using it in a game
+
+`ModelService` and `GridService` call a world hub on ck-exec with the endpoints
+the starter's `exec/construct` serves (`world`, `programs`, `progress`,
+`claims`, `record_claim`, `release_claim`). The defaults name the starter's hub,
+type `world` key `main`; a game whose hub has another name says so at boot:
+
+```ts
+import { configureWorldHub, GameSession, GameLoop } from '@crowdedkingdoms/construct';
+
+configureWorldHub({ nodeType: 'realm', key: 'main' });
+```
+
+- Set `VITE_GAME_NAME` for the Studio dock and boot card.
+- Serve `grid-program.html` (a one-line page whose module imports
+  `@crowdedkingdoms/construct/sandbox/boot`) and add it to
+  `build.rollupOptions.input`.
+- In `vite.config.ts`:
+
+```ts
+import { constructHeaderPlugins } from '@crowdedkingdoms/construct/node/vite-plugins';
+import {
+  dshSecurityHeaders,
+  gridProgramSecurityHeaders,
+  securityHeaders,
+} from '@crowdedkingdoms/construct/node/security-headers';
+
+plugins: constructHeaderPlugins({
+  dshHeaders: dshSecurityHeaders({ apiOrigins: [apiOrigin] }),
+  gridProgramHeaders: gridProgramSecurityHeaders(),
+}),
+```
+
+- `construct-copy-dsh` (in `predev` / `prebuild`) copies the agent harness
+  into `public/dsh/`.
+
+## Setup scripts
+
+`@crowdedkingdoms/construct/platform/onboarding/steps` provisions an app
+(org, app, access tier, redirect URIs, grid claim policy, your ck-exec code
+(`deployExec`: `execBuild` + `execDeploy`), a Game Model if you keep one, Studio
+Common Files, agent policy). Pass your own `exec` (manifest, crates, and a
+client holding your session on the app's datacenter), `blueprints` and
+`commonFiles`.

package/node/copy-dsh-web.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Put the Crowdy Studio agent harness where the page serves it.
+ *
+ * The harness (DeepSeek Harness web client + packed VFS image, ~13 MB) is
+ * published as `@crowdedkingdoms/crowdy-dsh`; its `dist/dsh-web/` is copied
+ * into the game's `public/dsh/` (the current working directory is the game)
+ * before `vite dev` / `vite build`. Run it as `construct-copy-dsh`. `public/dsh/` is
+ * gitignored: the artifact is versioned by the package, not by this template,
+ * and `public/dsh/BUILD.json` says exactly which build is being served.
+ *
+ *   DSH_WEB_DIR=/path/to/dist/dsh-web   use a locally built artifact instead
+ *   CONSTRUCT_SKIP_DSH=1                 leave public/dsh alone (no agent pane)
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const root = path.resolve(process.env.CONSTRUCT_APP_ROOT ?? process.cwd());
+const target = path.join(root, 'public', 'dsh');
+
+if (process.env.CONSTRUCT_SKIP_DSH === '1') {
+  console.log('copy-dsh-web: CONSTRUCT_SKIP_DSH=1, leaving public/dsh as is');
+  process.exit(0);
+}
+
+let source = process.env.DSH_WEB_DIR?.trim();
+let origin;
+if (source) {
+  source = path.resolve(source);
+  origin = `DSH_WEB_DIR=${source}`;
+} else {
+  const require = createRequire(path.join(root, 'package.json'));
+  let manifestPath;
+  try {
+    manifestPath = require.resolve('@crowdedkingdoms/crowdy-dsh/package.json');
+  } catch {
+    console.error(
+      'copy-dsh-web: @crowdedkingdoms/crowdy-dsh is not installed. Run `npm install`, or set ' +
+        'DSH_WEB_DIR to a locally built dist/dsh-web, or CONSTRUCT_SKIP_DSH=1 to build without the agent pane.',
+    );
+    process.exit(1);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  source = path.join(path.dirname(manifestPath), 'dist', 'dsh-web');
+  origin = `${manifest.name}@${manifest.version}`;
+}
+
+for (const required of ['index.html', 'BUILD.json', path.join('preview', 'vfs-image.tar.gz')]) {
+  if (!existsSync(path.join(source, required))) {
+    console.error(`copy-dsh-web: ${source} is not a harness artifact (missing ${required})`);
+    process.exit(1);
+  }
+}
+
+rmSync(target, { recursive: true, force: true });
+mkdirSync(path.dirname(target), { recursive: true });
+cpSync(source, target, { recursive: true });
+// A marker for anyone who finds public/dsh in a checkout and wonders.
+writeFileSync(
+  path.join(target, 'SOURCE.txt'),
+  `Copied by construct-copy-dsh from ${origin} on ${new Date().toISOString()}.\n` +
+    'Do not edit or commit: public/dsh is gitignored and regenerated before every dev/build.\n',
+);
+
+const stamp = JSON.parse(readFileSync(path.join(target, 'BUILD.json'), 'utf8'));
+console.log(
+  `copy-dsh-web: public/dsh <- ${origin} ` +
+    `(harness ${stamp.upstream?.tag ?? '?'}, CrowdyJS ${stamp.crowdyjs?.version ?? '?'}, ` +
+    `built ${stamp.builtAt ?? '?'})`,
+);

package/node/security-headers.d.mts

@@ -0,0 +1,23 @@
+export interface SecurityHeaderOptions {
+  /** Every API origin the bundle may dial (configured, or the SDK default). */
+  apiOrigins?: Array<string | null | undefined>;
+  /** Additional exact origins a fork needs in connect-src. No wildcards. */
+  extraConnectSrc?: string[];
+  /**
+   * Origins that may FRAME this game (the Crowdy Games shell, or a shell of your own).
+   * Empty (the default) renders `frame-ancestors 'none'`; the DSH pane always adds
+   * `'self'` beside them.
+   */
+  frameAncestors?: string[];
+}
+
+export function tierZoneWildcards(origins: Array<string | null | undefined>): string[];
+export function frameAncestorsSource(frameAncestors?: string[]): string;
+export function corpFor(options?: SecurityHeaderOptions): 'same-origin' | 'cross-origin';
+export function buildCsp(options?: SecurityHeaderOptions): string;
+export function buildDshCsp(options?: SecurityHeaderOptions): string;
+export function securityHeaders(options?: SecurityHeaderOptions): Record<string, string>;
+export function dshSecurityHeaders(options?: SecurityHeaderOptions): Record<string, string>;
+export function buildGridProgramCsp(): string;
+export function gridProgramSecurityHeaders(): Record<string, string>;
+export const ISOLATION_HEADERS: readonly string[];

package/node/security-headers.mjs

@@ -0,0 +1,243 @@
+/**
+ * Security headers for The Construct — used by the Vite dev/preview servers and
+ * documented for every hosting recipe in docs/HOSTING.md.
+ *
+ * Why a game needs these at all: Crowdy Studio CLIENT mods run untrusted player
+ * code in a same-origin worker and talk to the page through a SharedArrayBuffer
+ * + Atomics bridge. Browsers only expose SharedArrayBuffer to pages that are
+ * cross-origin isolated, which takes BOTH `Cross-Origin-Opener-Policy` and
+ * `Cross-Origin-Embedder-Policy`. Without them `crossOriginIsolated` is false,
+ * the worker cannot start, and the feature silently disappears. The CSP is the
+ * other half: it keeps the worker same-origin and the page's network reach
+ * limited to the API it was built for.
+ *
+ * The API origin moves at runtime: the shared client origin hands the client
+ * to the app's datacenter and then to a direct API instance, all under the
+ * same one-label zone (e.g. `ck.<tier>.example` -> `*.<tier>.example`). The
+ * connect-src therefore admits the configured origin plus that one-label
+ * wildcard, and nothing wider.
+ */
+
+function originOf(value) {
+  if (!value) return null;
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+/**
+ * `https://ck.prod.example.com` -> `https://*.prod.example.com` (and the wss:
+ * twin). Nothing for hosts with no parent zone (localhost, IPs).
+ */
+export function tierZoneWildcards(origins) {
+  const out = [];
+  for (const origin of origins) {
+    if (!origin) continue;
+    let url;
+    try {
+      url = new URL(origin);
+    } catch {
+      continue;
+    }
+    const labels = url.hostname.split('.');
+    if (labels.length < 3) continue;
+    if (/^[\d.]+$/.test(url.hostname)) continue;
+    const zone = labels.slice(1).join('.');
+    out.push(`https://*.${zone}`, `wss://*.${zone}`);
+  }
+  return out;
+}
+
+/**
+ * Build the Content-Security-Policy for the page and its same-origin workers.
+ *
+ * @param {{ apiOrigins?: Array<string | null | undefined>, extraConnectSrc?: string[] }} options
+ *   `apiOrigins` — every API origin the bundle may dial (the configured one, or
+ *   the SDK default). `extraConnectSrc` — additional exact origins a fork needs
+ *   (analytics beacon, its own backend). Keep this list exact; no `*`.
+ */
+export function buildCsp({ apiOrigins = [], extraConnectSrc = [], frameAncestors = [] } = {}) {
+  const configured = apiOrigins.map(originOf);
+  const wsTwins = configured
+    .filter(Boolean)
+    .map((origin) => origin.replace(/^http(s?):/, (_, secure) => `ws${secure}:`));
+  const connectSources = unique([
+    "'self'",
+    ...configured,
+    ...wsTwins,
+    ...tierZoneWildcards(configured),
+    ...extraConnectSrc,
+  ]);
+
+  return [
+    "default-src 'self'",
+    "base-uri 'none'",
+    "object-src 'none'",
+    // 'none' when self-hosted at the top level. When this game is FRAMED -- by the
+    // Crowdy Games shell (which the platform's content edge sets for you), or by a
+    // shell of your own -- name exactly that origin here (`frameAncestors`); a game
+    // that can be framed anywhere is a clickjacking surface.
+    `frame-ancestors ${frameAncestorsSource(frameAncestors)}`,
+    // 'wasm-unsafe-eval' lets the SDK instantiate WebAssembly (the Rust
+    // language worker and the player-mod runtime). It grants no JS eval.
+    "script-src 'self' 'wasm-unsafe-eval'",
+    // Monaco injects computed styles; three.js/pixi do not need this but the
+    // editor does.
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: blob:",
+    "font-src 'self' data:",
+    `connect-src ${connectSources.join(' ')}`,
+    // The glue worker and Monaco workers are same-origin module workers; blob:
+    // covers Vite's dev-mode worker wrappers.
+    "worker-src 'self' blob:",
+    // 'self' lets Crowdy Studio embed the same-origin in-browser DeepSeek Harness (/dsh/).
+    "frame-src 'self'",
+    "media-src 'self' blob:",
+    "manifest-src 'self'",
+  ].join('; ');
+}
+
+/**
+ * Build the Content-Security-Policy for the in-browser DeepSeek Harness (/dsh/*).
+ * The harness worker loads lowered module bodies with `new Function` and runs its
+ * own module system; its iframe is embedded by the game page ('self').
+ */
+export function buildDshCsp({ apiOrigins = [], extraConnectSrc = [], frameAncestors = [] } = {}) {
+  const configured = apiOrigins.map(originOf);
+  const wsTwins = configured
+    .filter(Boolean)
+    .map((origin) => origin.replace(/^http(s?):/, (_, secure) => `ws${secure}:`));
+  const connectSources = unique([
+    "'self'",
+    'blob:',
+    ...configured,
+    ...wsTwins,
+    ...tierZoneWildcards(configured),
+    ...extraConnectSrc,
+  ]);
+
+  return [
+    "default-src 'self'",
+    "base-uri 'none'",
+    "object-src 'none'",
+    // 'self' (the game page frames the pane) PLUS whoever frames the game: frame-ancestors
+    // is checked against EVERY ancestor, so under the Crowdy Games shell the pane's
+    // ancestors are the game and the shell, and 'self' alone would refuse it.
+    `frame-ancestors 'self'${frameAncestors.length ? ` ${frameAncestorsSource(frameAncestors)}` : ''}`,
+    "script-src 'self' 'unsafe-eval' 'unsafe-inline' blob:",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: blob:",
+    "font-src 'self' data:",
+    `connect-src ${connectSources.join(' ')}`,
+    "worker-src 'self' blob:",
+    "frame-src 'self'",
+    "media-src 'self' blob:",
+    "manifest-src 'self'",
+  ].join('; ');
+}
+
+/**
+ * Build the Content-Security-Policy for the JS grid program sandbox
+ * (`/grid-program.html`, framed by the game in `sandbox="allow-scripts"`).
+ * The program's code arrives as a blob module; it gets NO network at all
+ * (`connect-src 'none'`): everything it does crosses the MessagePort to the
+ * page, which relays it with a grid-scoped token (DN-10). No inline script,
+ * no eval, no workers, no frames, no forms.
+ */
+export function buildGridProgramCsp() {
+  return [
+    "default-src 'none'",
+    "base-uri 'none'",
+    "object-src 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'self'",
+    "script-src 'self' blob:",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: blob:",
+    "connect-src 'none'",
+    "worker-src 'none'",
+    "frame-src 'none'",
+  ].join('; ');
+}
+
+/** `frameAncestors` -> a CSP source list; `'none'` when nothing may frame the page. */
+export function frameAncestorsSource(frameAncestors = []) {
+  const origins = unique(frameAncestors.map(originOf));
+  return origins.length ? origins.join(' ') : "'none'";
+}
+
+/** `same-origin` unless somebody may frame the game, then `cross-origin` (see securityHeaders). */
+export function corpFor({ frameAncestors = [] } = {}) {
+  return frameAncestors.some((a) => originOf(a)) ? 'cross-origin' : 'same-origin';
+}
+
+/** Which powerful features the page (and only the page) may use. */
+export const PERMISSIONS_POLICY = 'camera=(self), microphone=(self)';
+
+/**
+ * The full header set. Apply to every response of the site (HTML, JS, worker
+ * scripts, wasm), not just index.html — a worker fetched without COEP breaks
+ * isolation for the page that spawned it.
+ */
+export function securityHeaders(options = {}) {
+  return {
+    'Cross-Origin-Opener-Policy': 'same-origin',
+    // `credentialless` rather than `require-corp`: it lets the page load
+    // cross-origin subresources without CORP headers by stripping credentials,
+    // which is what a static game on a CDN needs. Both values enable isolation.
+    'Cross-Origin-Embedder-Policy': 'credentialless',
+    // `same-origin` for a top-level game. A FRAMED game must say `cross-origin`:
+    // browsers enforce CORP on nested navigations too, so under the shell's COEP a
+    // `same-origin` document is refused with ERR_BLOCKED_BY_RESPONSE before
+    // frame-ancestors is even consulted. Measured 2026-09-13 in the shell e2e.
+    'Cross-Origin-Resource-Policy': corpFor(options),
+    'Content-Security-Policy': buildCsp(options),
+    // The page may use the camera and microphone (WebcamService / VoiceService);
+    // nothing embedded may. An explicit policy also stops a hosting default
+    // from silently denying either device.
+    'Permissions-Policy': PERMISSIONS_POLICY,
+    'Referrer-Policy': 'strict-origin-when-cross-origin',
+    'X-Content-Type-Options': 'nosniff',
+  };
+}
+
+/**
+ * Security headers for the in-browser DeepSeek Harness surface (/dsh/*).
+ */
+export function dshSecurityHeaders(options = {}) {
+  return {
+    'Cross-Origin-Opener-Policy': 'same-origin',
+    'Cross-Origin-Embedder-Policy': 'credentialless',
+    'Cross-Origin-Resource-Policy': corpFor(options),
+    'Content-Security-Policy': buildDshCsp(options),
+    'Permissions-Policy': PERMISSIONS_POLICY,
+    'Referrer-Policy': 'strict-origin-when-cross-origin',
+    'X-Content-Type-Options': 'nosniff',
+  };
+}
+
+/**
+ * Security headers for the JS grid program sandbox page. Same isolation as the
+ * game (a cross-origin-isolated page can only frame COEP documents), its own
+ * CSP, and no powerful features.
+ */
+export function gridProgramSecurityHeaders() {
+  return {
+    'Cross-Origin-Opener-Policy': 'same-origin',
+    'Cross-Origin-Embedder-Policy': 'credentialless',
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    'Content-Security-Policy': buildGridProgramCsp(),
+    'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
+    'Referrer-Policy': 'no-referrer',
+    'X-Content-Type-Options': 'nosniff',
+  };
+}
+
+/** The two headers that decide `crossOriginIsolated`; listed for docs/tests. */
+export const ISOLATION_HEADERS = ['Cross-Origin-Opener-Policy', 'Cross-Origin-Embedder-Policy'];

package/node/vite-plugins.d.mts

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite';
+
+export function constructHeaderPlugins(options: {
+  dshHeaders?: Record<string, string>;
+  gridProgramHeaders?: Record<string, string>;
+}): Plugin[];

package/node/vite-plugins.mjs

@@ -0,0 +1,102 @@
+/**
+ * Vite plugins every Construct game needs: path-scoped security headers for
+ * the two same-origin pages the game frames, the in-browser DeepSeek Harness
+ * (`/dsh/*`) and the JS grid program sandbox (`/grid-program.html`). The site
+ * headers (securityHeaders) are applied by Vite's `server.headers`; these
+ * override them for their own paths.
+ */
+
+/**
+ * @param {string} name
+ * @param {(pathname: string) => boolean} match
+ * @param {Record<string, string>} headers
+ * @param {{ keepGzipArchives?: boolean }} [options]
+ */
+function pathHeadersPlugin(name, match, headers, options = {}) {
+  /** @param {import('vite').ViteDevServer | import('vite').PreviewServer} server */
+  const attach = (server) => {
+    server.middlewares.use((req, res, next) => {
+      const pathname = (req.url ?? '').split('?')[0] ?? '';
+      if (match(pathname)) {
+        // The harness's packed VFS image is a .tar.gz its worker inflates with
+        // DecompressionStream. Vite's static server adds `Content-Encoding: gzip`
+        // for that suffix, so the browser would inflate it first and the worker
+        // would then fail on plain tar. Only that suffix is affected.
+        const isGzipArchive = options.keepGzipArchives && /\.gz$/i.test(pathname);
+        const origSetHeader = res.setHeader.bind(res);
+        res.setHeader = (header, value) => {
+          if (isGzipArchive && header.toLowerCase() === 'content-encoding') return res;
+          const pinned = headers[header];
+          return origSetHeader(header, pinned !== undefined ? pinned : value);
+        };
+        for (const [header, value] of Object.entries(headers)) origSetHeader(header, value);
+      }
+      next();
+    });
+  };
+  return { name, configureServer: attach, configurePreviewServer: attach };
+}
+
+/**
+ * The grid program sandbox is an OPAQUE origin (`sandbox="allow-scripts"`
+ * without allow-same-origin), so its module scripts are fetched in CORS mode
+ * with `Origin: null`. Answer those, and only those, with
+ * `Access-Control-Allow-Origin: null`. The API paths are left alone: the
+ * sandbox has `connect-src 'none'` and reaches the API only through the page.
+ * The files served this way are the game's public bundle.
+ */
+function sandboxModuleCorsPlugin() {
+  /** @param {import('vite').ViteDevServer | import('vite').PreviewServer} server */
+  const attach = (server) => {
+    server.middlewares.use((req, res, next) => {
+      const pathname = (req.url ?? '').split('?')[0] ?? '';
+      const isApi = /^\/(graphql|realtime|s2s|api)(\/|$)/.test(pathname);
+      if (req.headers.origin === 'null' && req.method === 'GET' && !isApi) {
+        const origSetHeader = res.setHeader.bind(res);
+        res.setHeader = (header, value) =>
+          header.toLowerCase() === 'access-control-allow-origin'
+            ? origSetHeader(header, 'null')
+            : origSetHeader(header, value);
+        origSetHeader('Access-Control-Allow-Origin', 'null');
+        origSetHeader('Vary', 'Origin');
+      }
+      next();
+    });
+  };
+  return {
+    name: 'construct-grid-program-module-cors',
+    configureServer: attach,
+    configurePreviewServer: attach,
+  };
+}
+
+/**
+ * Omit `dshHeaders` when the game already serves `/dsh/*` under its own policy.
+ *
+ * @param {{ dshHeaders?: Record<string, string>, gridProgramHeaders?: Record<string, string> }} options
+ * @returns {import('vite').Plugin[]}
+ */
+export function constructHeaderPlugins({ dshHeaders, gridProgramHeaders }) {
+  const plugins = [];
+  if (dshHeaders) {
+    plugins.push(
+      pathHeadersPlugin(
+        'construct-dsh-headers',
+        (p) => p.startsWith('/dsh/') || p === '/dsh',
+        dshHeaders,
+        { keepGzipArchives: true },
+      ),
+    );
+  }
+  if (gridProgramHeaders) {
+    plugins.push(
+      sandboxModuleCorsPlugin(),
+      pathHeadersPlugin(
+        'construct-grid-program-headers',
+        (p) => p.endsWith('/grid-program.html'),
+        gridProgramHeaders,
+      ),
+    );
+  }
+  return plugins;
+}

package/package.json

@@ -1,11 +1,56 @@
 {
   "name": "@crowdedkingdoms/construct",
-  "version": "0.0.0",
-  "description": "The Construct framework. Releases come from the-construct's CI (publish-construct.yml); this version is a placeholder.",
+  "version": "0.2.1-dev.1",
+  "description": "The Construct framework: the Crowded Kingdoms game platform layer (hosted sign-in, World Stores, voice/webcam/chat, Crowdy Studio dock, app and grid mods, grid programs) and engine loop, shared by the-construct starter and the games built on it. Ships TypeScript source for Vite.",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/CrowdedKingdoms/the-construct.git",
+    "url": "https://github.com/CrowdedKingdoms/the-construct.git",
     "directory": "packages/construct"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "./sandbox/boot.ts"
+  ],
+  "files": [
+    "src",
+    "node",
+    "sandbox",
+    "README.md"
+  ],
+  "bin": {
+    "construct-copy-dsh": "./node/copy-dsh-web.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./platform/onboarding/steps": {
+      "types": "./src/platform/onboarding/steps.d.mts",
+      "default": "./src/platform/onboarding/steps.mjs"
+    },
+    "./node/security-headers": {
+      "types": "./node/security-headers.d.mts",
+      "default": "./node/security-headers.mjs"
+    },
+    "./node/copy-dsh-web": "./node/copy-dsh-web.mjs",
+    "./node/vite-plugins": {
+      "types": "./node/vite-plugins.d.mts",
+      "default": "./node/vite-plugins.mjs"
+    },
+    "./sandbox/boot": "./sandbox/boot.ts",
+    "./engine/*": "./src/engine/*.ts",
+    "./platform/*": "./src/platform/*.ts",
+    "./grid/*": "./src/grid/*.ts"
+  },
+  "peerDependencies": {
+    "@crowdedkingdoms/crowdyjs": ">=17.7.0-dev.0 <18 || >=17.8.0-dev.0 <18 || >=17.9.0-dev.0 <18 || >=17.12.0-dev.0 <18",
+    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1"
+  },
+  "peerDependenciesMeta": {
+    "@crowdedkingdoms/crowdy-dsh": {
+      "optional": true
+    }
   }
 }

package/sandbox/boot.ts

@@ -0,0 +1,74 @@
+/**
+ * Runs INSIDE the JS grid program sandbox (`grid-program.html`, framed with
+ * `sandbox="allow-scripts"`: an opaque origin with `connect-src 'none'`).
+ *
+ * The page sends one `init` message carrying the program's source and a
+ * MessagePort. The program is loaded as a blob module and its default export
+ * is called with real CrowdyJS whose network is that port (the page relays it
+ * with a grid-scoped token the program never sees):
+ *
+ *   export default async function ({ client, grid, appId, gridId, box, log }) { … }
+ *
+ * Console output, errors and lifecycle are reported to the page, which shows
+ * them to the player and to the Studio agent (`grid_program_status`).
+ */
+import { createGridProgramClient } from '@crowdedkingdoms/crowdyjs/grid-program';
+
+import { GRID_PROGRAM_SOURCE, type GridProgramSandboxMessage } from '../src/grid/sandboxProtocol';
+
+const post = (message: GridProgramSandboxMessage) =>
+  window.parent.postMessage({ source: GRID_PROGRAM_SOURCE, ...message }, '*');
+
+const format = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  if (value instanceof Error) return value.stack ?? value.message;
+  try {
+    return JSON.stringify(value, (_k, v) => (typeof v === 'bigint' ? v.toString() : v));
+  } catch {
+    return String(value);
+  }
+};
+
+for (const level of ['log', 'info', 'warn', 'error'] as const) {
+  const original = console[level].bind(console);
+  console[level] = (...args: unknown[]) => {
+    original(...args);
+    post({ type: 'log', level, line: args.map(format).join(' ').slice(0, 2_000) });
+  };
+}
+window.addEventListener('error', (event) =>
+  post({ type: 'error', message: String(event.message) }),
+);
+window.addEventListener('unhandledrejection', (event) =>
+  post({ type: 'error', message: format((event as PromiseRejectionEvent).reason) }),
+);
+
+let started = false;
+window.addEventListener('message', (event) => {
+  if (event.source !== window.parent || started) return;
+  const data = event.data as { source?: string; type?: string; program?: string; path?: string };
+  if (data?.source !== GRID_PROGRAM_SOURCE || data.type !== 'init') return;
+  const port = event.ports[0];
+  if (!port || typeof data.program !== 'string') return;
+  started = true;
+  void (async () => {
+    const context = await createGridProgramClient(port);
+    const url = URL.createObjectURL(new Blob([data.program!], { type: 'text/javascript' }));
+    try {
+      const module = (await import(/* @vite-ignore */ url)) as {
+        default?: (ctx: unknown) => unknown;
+      };
+      if (typeof module.default !== 'function') {
+        throw new Error('a grid program must `export default` a function');
+      }
+      post({ type: 'started' });
+      await module.default({ ...context, log: (...args: unknown[]) => console.log(...args) });
+    } catch (error) {
+      post({ type: 'error', message: format(error) });
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+  })();
+});
+
+post({ type: 'ready' });