@crowdedkingdoms/construct 0.3.11-test.1 → 0.4.0-dev.1

package/src/platform/live/draftModules.ts

@@ -0,0 +1,263 @@
+/**
+ * How the draft service worker turns draft files into modules the page can
+ * import. Pure functions, shared by the worker and the tests.
+ *
+ * URLs, all under the game's base (`BASE`):
+ * - `BASE__draft/g<generation>/<repo path>`: a draft file as an ES module.
+ *   TypeScript is stripped (sucrase keeps line numbers, so stack traces point
+ *   at the draft file); every import is rewritten to another draft URL of the
+ *   same generation, a host shim, or a module that throws a clear error.
+ * - `BASE__draft/host/<specifier>.js`: a shim re-exporting the page's own
+ *   module for a bare or framework import, so a draft scene shares `three`,
+ *   the framework and its singletons with the running game.
+ * - `BASE__draft/missing/<specifier>`: an import the draft cannot satisfy.
+ *
+ * A new generation re-imports the whole draft graph under new URLs; the
+ * browser's module map caches the old one until the page reloads.
+ */
+// The pure-JS build: no WebAssembly (a `script-src 'self'` page cannot compile it) and no init.
+import { parse } from 'es-module-lexer/js';
+import { transform } from 'sucrase';
+
+import type { PreviewError } from './content';
+
+export const DRAFT_SEGMENT = '__draft/';
+/** The service worker's file name, next to the game's index.html. */
+export const DRAFT_WORKER_FILE = 'construct-draft-sw.js';
+/** The content entry every generation imports. */
+export const CONTENT_ENTRY = 'src/game/content.ts';
+
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.js', '.mjs', '.json'];
+const SCRIPT_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.js', '.mjs']);
+
+export type DraftRequest =
+  | { kind: 'module'; generation: number; path: string }
+  | { kind: 'host'; specifier: string }
+  | { kind: 'missing'; specifier: string; importer: string };
+
+/** What a pathname under the draft segment asks for, or null when it is not a draft URL. */
+export function parseDraftUrl(pathname: string, base: string): DraftRequest | null {
+  const prefix = `${base}${DRAFT_SEGMENT}`;
+  if (!pathname.startsWith(prefix)) return null;
+  const rest = pathname.slice(prefix.length);
+  const generation = /^g(\d+)\/(.+)$/.exec(rest);
+  if (generation) {
+    const path = decodeURIComponent(generation[2] ?? '');
+    if (!isDraftPath(path)) return null;
+    return { kind: 'module', generation: Number(generation[1]), path };
+  }
+  const host = /^host\/(.+)\.js$/.exec(rest);
+  if (host) return { kind: 'host', specifier: decodeURIComponent(host[1] ?? '') };
+  const missing = /^missing\/([^/]+)\/(.+)$/.exec(rest);
+  if (missing) {
+    return {
+      kind: 'missing',
+      importer: decodeURIComponent(missing[1] ?? ''),
+      specifier: decodeURIComponent(missing[2] ?? ''),
+    };
+  }
+  return null;
+}
+
+export function draftModuleUrl(base: string, generation: number, path: string): string {
+  return `${base}${DRAFT_SEGMENT}g${generation}/${path.split('/').map(encodeURIComponent).join('/')}`;
+}
+
+function hostShimUrl(base: string, specifier: string): string {
+  return `${base}${DRAFT_SEGMENT}host/${encodeURIComponent(specifier)}.js`;
+}
+
+function missingUrl(base: string, importer: string, specifier: string): string {
+  return `${base}${DRAFT_SEGMENT}missing/${encodeURIComponent(importer)}/${encodeURIComponent(specifier)}`;
+}
+
+/** A relative repository path with no traversal: what a draft URL may name. */
+function isDraftPath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    !path.startsWith('/') &&
+    !path.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+  );
+}
+
+function normalize(path: string): string | null {
+  const out: string[] = [];
+  for (const segment of path.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (out.length === 0) return null;
+      out.pop();
+    } else out.push(segment);
+  }
+  return out.join('/');
+}
+
+function extensionOf(path: string): string {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot) : '';
+}
+
+export type Resolution =
+  { kind: 'draft'; path: string } | { kind: 'host'; specifier: string } | { kind: 'missing' };
+
+/**
+ * Resolve an import written in a draft file: `./`, `../`, `/` and the
+ * template's `@/` (src/) alias name draft files; anything else is the host's.
+ * Extensions resolve as Vite does for this template.
+ */
+export function resolveSpecifier(
+  specifier: string,
+  importer: string,
+  paths: ReadonlySet<string>,
+): Resolution {
+  let target: string | null;
+  if (specifier.startsWith('./') || specifier.startsWith('../')) {
+    target = normalize(`${importer.slice(0, importer.lastIndexOf('/') + 1)}${specifier}`);
+  } else if (specifier.startsWith('@/')) {
+    target = normalize(`src/${specifier.slice(2)}`);
+  } else if (specifier.startsWith('/')) {
+    target = normalize(specifier.slice(1));
+  } else {
+    return { kind: 'host', specifier };
+  }
+  if (!target) return { kind: 'missing' };
+  const candidates = [
+    target,
+    ...RESOLVE_EXTENSIONS.map((extension) => `${target}${extension}`),
+    ...RESOLVE_EXTENSIONS.map((extension) => `${target}/index${extension}`),
+  ];
+  for (const candidate of candidates) {
+    if (paths.has(candidate)) return { kind: 'draft', path: candidate };
+  }
+  return { kind: 'missing' };
+}
+
+export class DraftTransformError extends Error {
+  constructor(
+    message: string,
+    readonly error: PreviewError,
+  ) {
+    super(message);
+    this.name = 'DraftTransformError';
+  }
+}
+
+/**
+ * A draft file as a module of generation `generation`. Throws a
+ * `DraftTransformError` carrying the file and line for a syntax error.
+ */
+export async function transformDraftModule(options: {
+  source: string;
+  path: string;
+  generation: number;
+  base: string;
+  paths: ReadonlySet<string>;
+}): Promise<string> {
+  const { source, path, generation, base, paths } = options;
+  const extension = extensionOf(path);
+  if (extension === '.json') {
+    try {
+      return `export default ${JSON.stringify(JSON.parse(source))};\n`;
+    } catch (error) {
+      throw new DraftTransformError(`${path}: ${(error as Error).message}`, {
+        path,
+        message: (error as Error).message,
+      });
+    }
+  }
+  if (!SCRIPT_EXTENSIONS.has(extension)) {
+    const message = `${path} cannot be previewed (${extension || 'no extension'}): only TypeScript, JavaScript and JSON load from the draft.`;
+    throw new DraftTransformError(message, { path, message });
+  }
+  let code = source;
+  if (extension === '.ts' || extension === '.tsx' || extension === '.mts') {
+    try {
+      code = transform(source, {
+        transforms: extension === '.tsx' ? ['typescript', 'jsx'] : ['typescript'],
+        disableESTransforms: true,
+        preserveDynamicImport: true,
+        production: true,
+        filePath: path,
+      }).code;
+    } catch (error) {
+      const loc = (error as { loc?: { line: number; column: number } }).loc;
+      const message = (error as Error).message;
+      throw new DraftTransformError(
+        `${path}${loc ? `:${loc.line}:${loc.column + 1}` : ''}: ${message}`,
+        {
+          path,
+          ...(loc ? { line: loc.line, column: loc.column + 1 } : {}),
+          message,
+        },
+      );
+    }
+  }
+  let imports: ReturnType<typeof parse>[0];
+  try {
+    [imports] = parse(code, path);
+  } catch (error) {
+    const idx = (error as { idx?: number }).idx;
+    const line = idx === undefined ? undefined : code.slice(0, idx).split('\n').length;
+    const message = (error as Error).message;
+    throw new DraftTransformError(`${path}${line ? `:${line}` : ''}: ${message}`, {
+      path,
+      ...(line ? { line } : {}),
+      message,
+    });
+  }
+  const rewriteSpecifier = (specifier: string): string => {
+    const resolution = resolveSpecifier(specifier, path, paths);
+    if (resolution.kind === 'draft') return draftModuleUrl(base, generation, resolution.path);
+    if (resolution.kind === 'host') return hostShimUrl(base, resolution.specifier);
+    return missingUrl(base, path, specifier);
+  };
+  // Back to front, so earlier offsets stay valid.
+  for (const entry of [...imports].sort((a, b) => b.s - a.s)) {
+    if (entry.d === -2) {
+      const after = code.slice(entry.e);
+      if (after.startsWith('.env')) {
+        code = `${code.slice(0, entry.s)}globalThis.__constructDraftEnv${code.slice(entry.e + 4)}`;
+      } else if (after.startsWith('.hot')) {
+        code = `${code.slice(0, entry.s)}(void 0)${code.slice(entry.e + 4)}`;
+      }
+      continue;
+    }
+    if (entry.n === undefined) continue;
+    const written = code.slice(entry.s, entry.e);
+    const quote = written[0] === '"' || written[0] === "'" || written[0] === '`' ? written[0] : '';
+    const url = rewriteSpecifier(entry.n);
+    code = `${code.slice(0, entry.s)}${quote ? JSON.stringify(url) : url}${code.slice(entry.e)}`;
+  }
+  return code;
+}
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const RESERVED = new Set(
+  'break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await arguments eval'.split(
+    ' ',
+  ),
+);
+
+/** A shim re-exporting the page's module for `specifier` with these export names. */
+export function hostShimSource(specifier: string, names: readonly string[]): string {
+  const lines = [`const m = await globalThis.__constructDraftHost(${JSON.stringify(specifier)});`];
+  names.forEach((name, index) => {
+    const local = `__e${index}`;
+    lines.push(`const ${local} = m[${JSON.stringify(name)}];`);
+    const exported =
+      name === 'default' || (IDENTIFIER.test(name) && !RESERVED.has(name))
+        ? name
+        : JSON.stringify(name);
+    lines.push(`export { ${local} as ${exported} };`);
+  });
+  return `${lines.join('\n')}\n`;
+}
+
+/** A module that fails to load with `error`, so the import names the file and line. */
+export function errorModuleSource(error: PreviewError): string {
+  const where = error.path
+    ? `${error.path}${error.line ? `:${error.line}${error.column ? `:${error.column}` : ''}` : ''}: `
+    : '';
+  return `const error = new Error(${JSON.stringify(`${where}${error.message}`)});\nerror.preview = ${JSON.stringify(error)};\nthrow error;\n`;
+}

package/src/platform/live/draftServiceWorker.ts

@@ -0,0 +1,176 @@
+/**
+ * The draft service worker: serves Crowdy Studio's game-editor draft as ES
+ * modules, so a hosted game previews edits without a build and without
+ * loosening its CSP (`script-src 'self'`: these are same-origin module URLs;
+ * nothing is evaluated from a string or a blob).
+ *
+ * It controls the game's pages (its scope is the game's base) because a
+ * service worker sees only the requests of the pages it controls, but it
+ * answers nothing outside `BASE__draft/`: navigations, the harness, the API
+ * and the game's own assets go to the network untouched. The page that
+ * imports a draft module answers for it (`./draftLoader`): sources, the
+ * generation's file list and the host's export names. A page that is not
+ * running the game editor never answers, and its requests fail.
+ *
+ * Bundled as a classic script by `constructDraftPlugin` (node/vite-plugins).
+ */
+import type { PreviewError } from './content';
+import {
+  DraftTransformError,
+  errorModuleSource,
+  hostShimSource,
+  parseDraftUrl,
+  transformDraftModule,
+  type DraftRequest,
+} from './draftModules';
+
+declare const self: ServiceWorkerGlobalScope;
+
+const ANSWER_TIMEOUT_MS = 10_000;
+const KEPT_GENERATIONS = 4;
+
+type PageAnswer =
+  | { ok: true; paths?: string[]; source?: string; names?: string[] }
+  | { ok: false; message: string };
+
+const base = new URL(self.registration.scope).pathname;
+const manifests = new Map<string, Promise<Set<string>>>();
+
+self.addEventListener('install', () => {
+  void self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+  if (url.origin !== self.location.origin || event.request.method !== 'GET') return;
+  const request = parseDraftUrl(url.pathname, base);
+  if (!request) return;
+  event.respondWith(answer(request, event.clientId));
+});
+
+async function ask(clientId: string, message: Record<string, unknown>): Promise<PageAnswer> {
+  const client = clientId ? await self.clients.get(clientId) : undefined;
+  if (!client) return { ok: false, message: 'No game page is waiting for this draft module.' };
+  const channel = new MessageChannel();
+  return new Promise<PageAnswer>((resolve) => {
+    const timer = setTimeout(() => {
+      channel.port1.close();
+      resolve({
+        ok: false,
+        message: 'The page did not answer for the draft (is the game editor open?).',
+      });
+    }, ANSWER_TIMEOUT_MS);
+    channel.port1.onmessage = (event: MessageEvent<PageAnswer>) => {
+      clearTimeout(timer);
+      channel.port1.close();
+      resolve(event.data);
+    };
+    client.postMessage({ type: 'construct-draft', ...message }, [channel.port2]);
+  });
+}
+
+function manifestOf(clientId: string, generation: number): Promise<Set<string>> {
+  const key = `${clientId}:${generation}`;
+  let manifest = manifests.get(key);
+  if (!manifest) {
+    manifest = ask(clientId, { request: 'manifest', generation }).then((reply) => {
+      if (!reply.ok || !reply.paths)
+        throw new Error(reply.ok ? 'The page sent no file list.' : reply.message);
+      return new Set(reply.paths);
+    });
+    manifest.catch(() => manifests.delete(key));
+    manifests.set(key, manifest);
+    while (manifests.size > KEPT_GENERATIONS)
+      manifests.delete(manifests.keys().next().value as string);
+  }
+  return manifest;
+}
+
+function moduleResponse(code: string, status = 200): Response {
+  return new Response(code, {
+    status,
+    headers: {
+      'Content-Type': 'text/javascript; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'Cross-Origin-Resource-Policy': 'same-origin',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  });
+}
+
+/** A module that throws, after telling the page what failed (it keeps the location). */
+async function failure(
+  clientId: string,
+  error: PreviewError,
+  generation?: number,
+): Promise<Response> {
+  const client = clientId ? await self.clients.get(clientId) : undefined;
+  client?.postMessage({ type: 'construct-draft-error', generation, error });
+  return moduleResponse(errorModuleSource(error));
+}
+
+async function answer(request: DraftRequest, clientId: string): Promise<Response> {
+  try {
+    switch (request.kind) {
+      case 'module': {
+        const paths = await manifestOf(clientId, request.generation);
+        if (!paths.has(request.path)) {
+          return failure(
+            clientId,
+            { path: request.path, message: `${request.path} is not in the draft.` },
+            request.generation,
+          );
+        }
+        const reply = await ask(clientId, {
+          request: 'source',
+          generation: request.generation,
+          path: request.path,
+        });
+        if (!reply.ok || reply.source === undefined) {
+          return failure(
+            clientId,
+            { path: request.path, message: reply.ok ? 'The page sent no source.' : reply.message },
+            request.generation,
+          );
+        }
+        const code = await transformDraftModule({
+          source: reply.source,
+          path: request.path,
+          generation: request.generation,
+          base,
+          paths,
+        });
+        return moduleResponse(code);
+      }
+      case 'host': {
+        const reply = await ask(clientId, { request: 'host', specifier: request.specifier });
+        if (!reply.ok || !reply.names) {
+          return failure(clientId, {
+            message: reply.ok
+              ? `The page sent no exports for ${request.specifier}.`
+              : `${request.specifier}: ${reply.message}`,
+          });
+        }
+        return moduleResponse(hostShimSource(request.specifier, reply.names));
+      }
+      case 'missing':
+        return failure(clientId, {
+          path: request.importer,
+          message: `Cannot find "${request.specifier}" in the draft (imported by ${request.importer}).`,
+        });
+    }
+  } catch (error) {
+    if (error instanceof DraftTransformError) {
+      return failure(
+        clientId,
+        error.error,
+        request.kind === 'module' ? request.generation : undefined,
+      );
+    }
+    return failure(clientId, { message: (error as Error).message ?? String(error) });
+  }
+}

package/src/platform/live/sdk.ts

@@ -0,0 +1,50 @@
+/**
+ * The game editor's slice of CrowdyJS 18.23 (`@crowdedkingdoms/crowdyjs/crowdy-studio`):
+ * the draft-store contract, the hosted store and its storage.
+ *
+ * The types are the SDK's own. The classes are looked up at runtime, so a page
+ * bundled with an SDK that predates them opens a bound project in the mod
+ * editor instead of failing to load.
+ */
+import * as studio from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+import type {
+  GitHubDraftTransport,
+  MountCrowdyStudioOptions,
+} from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+
+export type {
+  DraftChangeEvent,
+  DraftCommitResult,
+  DraftConflict,
+  DraftDeleteResult,
+  DraftEntry,
+  DraftErrorCode,
+  DraftPrecondition,
+  DraftReadResult,
+  DraftSnapshot,
+  DraftSource,
+  DraftStore,
+  DraftWriteResult,
+} from '@crowdedkingdoms/crowdyjs/crowdy-studio';
+
+/** What the Studio controller's `draftStore` option is given. */
+export type DraftProject = Parameters<NonNullable<MountCrowdyStudioOptions['draftStore']>>[0];
+
+/** The commit path of the SDK's GitHub transport (`game.crowdyStudioGitHub`). */
+export type DraftCommitTransport = Pick<GitHubDraftTransport, 'commitFiles'>;
+
+export type LiveCodeSdk = Pick<
+  typeof studio,
+  'GitHubDraftStore' | 'IndexedDbDraftOverlayStorage' | 'DraftError' | 'isRepoPath'
+>;
+
+/** The SDK's game-editor classes, or null when the installed SDK predates them. */
+export function liveCodeSdk(): LiveCodeSdk | null {
+  const sdk = studio as Partial<LiveCodeSdk>;
+  return typeof sdk.GitHubDraftStore === 'function' &&
+    typeof sdk.IndexedDbDraftOverlayStorage === 'function' &&
+    typeof sdk.DraftError === 'function' &&
+    typeof sdk.isRepoPath === 'function'
+    ? (sdk as LiveCodeSdk)
+    : null;
+}

package/src/platform/live/virtual.d.ts

@@ -0,0 +1,5 @@
+/** The lazy host-module registry `constructDraftPlugin` writes at build time (see draftLoader.ts). */
+declare module 'virtual:construct-draft-host' {
+  const modules: Readonly<Record<string, () => Promise<unknown>>>;
+  export default modules;
+}

package/src/platform/localLiveCode.ts

@@ -0,0 +1,11 @@
+/**
+ * A world without Buddy, for trying the game editor where no realtime cluster
+ * runs. Set `VITE_LOCAL_LIVE_CODE=1` on the dev server: the page skips the
+ * world join and the grid claim, and the world hub answers locally instead of
+ * dialling ck-exec. Off unless that flag is set. The game editor itself does
+ * not need it: `LIVE_DRAFT=1` turns the checkout into the draft.
+ */
+export function localLiveCode(): boolean {
+  const env = import.meta.env as { VITE_LOCAL_LIVE_CODE?: string } | undefined;
+  return env?.VITE_LOCAL_LIVE_CODE === '1';
+}