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

package/src/platform/live/draftLoader.ts

@@ -0,0 +1,265 @@
+/**
+ * Hosted preview for Crowdy Studio's game editor: the draft's content layer,
+ * loaded through the draft service worker and swapped into the running game.
+ *
+ * Started only for a player editing their own game on its hosted page (a
+ * dev server previews through Vite HMR instead). It registers the worker,
+ * answers the worker's questions from the draft store (the file list, a
+ * file's source, the export names of a host module), and imports a fresh
+ * generation of `src/game/content.ts` after each code change. Every outcome
+ * lands in the content host, which is what `preview_status` reads.
+ *
+ * Host modules come from `virtual:construct-draft-host`, a lazy registry the
+ * build writes (`constructDraftPlugin`): the framework, and every package the
+ * game's content imports. A draft can import only what that build bundles.
+ */
+import hostModules from 'virtual:construct-draft-host';
+
+import { previewErrorOf, type GameContentHost, type PreviewError } from './content';
+import { CONTENT_ENTRY, DRAFT_WORKER_FILE, draftModuleUrl } from './draftModules';
+import type { DraftChangeEvent, DraftStore } from './sdk';
+
+const CODE_FILE = /\.(ts|tsx|mts|js|mjs|json)$/;
+const RELOAD_DEBOUNCE_MS = 250;
+const CONTROL_TIMEOUT_MS = 5_000;
+
+type HostNamespace = Record<string, unknown>;
+
+declare global {
+  var __constructDraftHost: ((specifier: string) => Promise<HostNamespace>) | undefined;
+  var __constructDraftEnv: Record<string, unknown> | undefined;
+}
+
+interface WorkerQuestion {
+  type?: string;
+  request?: 'manifest' | 'source' | 'host';
+  generation?: number;
+  path?: string;
+  specifier?: string;
+  error?: PreviewError;
+}
+
+export interface DraftLoaderOptions {
+  /** The game's base URL path, with a trailing slash. */
+  base: string;
+  store: DraftStore;
+  content: GameContentHost;
+  /** What `import.meta.env` reads as in a draft module (the page's own). */
+  env: Record<string, unknown>;
+  log?: (line: string) => void;
+}
+
+function loadHost(specifier: string): Promise<HostNamespace> {
+  const load = hostModules[specifier];
+  if (!load) {
+    return Promise.reject(
+      new Error(
+        `${specifier} is not in this build of the game; a draft can import only what the published game bundles.`,
+      ),
+    );
+  }
+  return load() as Promise<HostNamespace>;
+}
+
+function waitForControl(timeoutMs: number): Promise<void> {
+  if (navigator.serviceWorker.controller) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      navigator.serviceWorker.removeEventListener('controllerchange', done);
+      reject(
+        new Error(
+          'The draft service worker did not take over this page; reload it to preview the draft.',
+        ),
+      );
+    }, timeoutMs);
+    function done(): void {
+      clearTimeout(timer);
+      navigator.serviceWorker.removeEventListener('controllerchange', done);
+      resolve();
+    }
+    navigator.serviceWorker.addEventListener('controllerchange', done);
+  });
+}
+
+export class DraftLoader {
+  private generation = 0;
+  private pendingRevision = 0;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private readonly workerErrors = new Map<number, PreviewError[]>();
+  private readonly offStore: () => void;
+  private readonly onMessage = (event: MessageEvent): void => {
+    void this.answer(event);
+  };
+  private disposed = false;
+
+  private constructor(
+    private readonly options: DraftLoaderOptions,
+    private readonly registration: ServiceWorkerRegistration,
+  ) {
+    navigator.serviceWorker.addEventListener('message', this.onMessage);
+    navigator.serviceWorker.startMessages();
+    this.offStore = options.store.subscribe((event) => this.onDraftChange(event));
+  }
+
+  /** Register the worker, take over the page, and load the draft's content once. */
+  static async start(options: DraftLoaderOptions): Promise<DraftLoader> {
+    if (!('serviceWorker' in navigator)) {
+      throw new Error(
+        'This browser cannot run service workers, so the hosted game cannot preview the draft.',
+      );
+    }
+    globalThis.__constructDraftHost = loadHost;
+    globalThis.__constructDraftEnv = options.env;
+    const registration = await navigator.serviceWorker.register(
+      `${options.base}${DRAFT_WORKER_FILE}`,
+      {
+        scope: options.base,
+        updateViaCache: 'none',
+      },
+    );
+    await navigator.serviceWorker.ready;
+    await waitForControl(CONTROL_TIMEOUT_MS);
+    const loader = new DraftLoader(options, registration);
+    loader.schedule(options.store.snapshot().revision, 0);
+    return loader;
+  }
+
+  /** Stop previewing; the worker unregisters, and the page keeps what it shows. */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.timer) clearTimeout(this.timer);
+    this.offStore();
+    navigator.serviceWorker.removeEventListener('message', this.onMessage);
+    void this.registration.unregister();
+  }
+
+  private onDraftChange(event: DraftChangeEvent): void {
+    const { content } = this.options;
+    content.noteRevision(event.revision);
+    const reload =
+      event.source === 'reload' ||
+      event.source === 'rebase' ||
+      event.changes.some((change) => CODE_FILE.test(change.path));
+    if (reload) {
+      this.schedule(event.revision, RELOAD_DEBOUNCE_MS);
+      return;
+    }
+    if (event.changes.length > 0) {
+      content.settleUnloaded(
+        event.revision,
+        `${event.changes.map((change) => change.path).join(', ')}: not code the running game loads; nothing to reload.`,
+      );
+    }
+  }
+
+  private schedule(revision: number, delayMs: number): void {
+    if (this.disposed) return;
+    this.pendingRevision = Math.max(this.pendingRevision, revision);
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.load();
+    }, delayMs);
+  }
+
+  private paths(): string[] {
+    return this.options.store
+      .snapshot()
+      .entries.filter((entry) => !entry.binary)
+      .map((entry) => entry.path);
+  }
+
+  private async load(): Promise<void> {
+    const { base, content, log, store } = this.options;
+    // Not listed yet: the store announces its first load, which schedules this again.
+    if (store.snapshot().entries.length === 0) return;
+    const revision = this.pendingRevision;
+    const generation = ++this.generation;
+    if (!this.paths().includes(CONTENT_ENTRY)) {
+      content.fail(
+        [
+          {
+            path: CONTENT_ENTRY,
+            message: `This game has no ${CONTENT_ENTRY}, so its hosted page cannot preview the draft. Update the game from the template.`,
+          },
+        ],
+        revision,
+      );
+      return;
+    }
+    let module: unknown;
+    try {
+      module = await import(/* @vite-ignore */ draftModuleUrl(base, generation, CONTENT_ENTRY));
+    } catch (error) {
+      if (generation !== this.generation) return;
+      const reported = this.workerErrors.get(generation);
+      content.fail(reported?.length ? reported : [previewErrorOf(error)], revision);
+      return;
+    } finally {
+      this.workerErrors.delete(generation);
+    }
+    // A newer generation is loading or loaded; this one is already stale.
+    if (generation !== this.generation || this.disposed) return;
+    const ok = await content.replace(module, revision);
+    log?.(
+      `draft preview: generation ${generation} (revision ${revision}) ${ok ? 'loaded' : 'failed'}`,
+    );
+  }
+
+  private async answer(event: MessageEvent): Promise<void> {
+    if (
+      event.source !== this.registration.active &&
+      event.source !== navigator.serviceWorker.controller
+    )
+      return;
+    const question = (event.data ?? {}) as WorkerQuestion;
+    if (question.type === 'construct-draft-error') {
+      if (question.generation !== undefined && question.error) {
+        const errors = this.workerErrors.get(question.generation) ?? [];
+        errors.push(question.error);
+        this.workerErrors.set(question.generation, errors);
+      }
+      return;
+    }
+    if (question.type !== 'construct-draft') return;
+    const port = event.ports[0];
+    if (!port) return;
+    try {
+      switch (question.request) {
+        case 'manifest':
+          port.postMessage({ ok: true, paths: this.paths() });
+          return;
+        case 'source': {
+          const path = String(question.path ?? '');
+          const result = await this.options.store.read([path]);
+          const file = result.files.find((candidate) => candidate.path === path);
+          port.postMessage(
+            file
+              ? { ok: true, source: file.content }
+              : {
+                  ok: false,
+                  message: `${path} is ${result.binary.includes(path) ? 'not a text file' : 'not in the draft'}.`,
+                },
+          );
+          return;
+        }
+        case 'host': {
+          const namespace = await loadHost(String(question.specifier ?? ''));
+          port.postMessage({ ok: true, names: Object.keys(namespace) });
+          return;
+        }
+        default:
+          port.postMessage({
+            ok: false,
+            message: `Unknown draft request ${String(question.request)}.`,
+          });
+      }
+    } catch (error) {
+      port.postMessage({
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/src/platform/live/draftModules.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  DraftTransformError,
+  draftModuleUrl,
+  errorModuleSource,
+  hostShimSource,
+  parseDraftUrl,
+  resolveSpecifier,
+  transformDraftModule,
+} from './draftModules';
+
+const BASE = '/the-construct/';
+const PATHS = new Set([
+  'src/game/content.ts',
+  'src/game/programs.ts',
+  'src/scenes/race/RaceScene.ts',
+  'src/scenes/race/index.ts',
+  'model/catalog.mjs',
+  'model/tracks.json',
+]);
+
+describe('parseDraftUrl', () => {
+  it('reads module, host and missing URLs under the base, and nothing else', () => {
+    expect(parseDraftUrl('/the-construct/__draft/g3/src/game/content.ts', BASE)).toEqual({
+      kind: 'module',
+      generation: 3,
+      path: 'src/game/content.ts',
+    });
+    expect(parseDraftUrl('/the-construct/__draft/host/three.js', BASE)).toEqual({
+      kind: 'host',
+      specifier: 'three',
+    });
+    expect(
+      parseDraftUrl(
+        `/the-construct/__draft/host/${encodeURIComponent('@crowdedkingdoms/construct/engine/GameScene')}.js`,
+        BASE,
+      ),
+    ).toEqual({ kind: 'host', specifier: '@crowdedkingdoms/construct/engine/GameScene' });
+    expect(parseDraftUrl('/the-construct/assets/index.js', BASE)).toBeNull();
+    expect(parseDraftUrl('/the-construct/dsh/index.html', BASE)).toBeNull();
+    expect(parseDraftUrl('/the-construct/__draft/g1/../../secrets', BASE)).toBeNull();
+    expect(parseDraftUrl('/the-construct/__draft/g1/src/%2E%2E/x.ts', BASE)).toBeNull();
+  });
+
+  it('round-trips a module URL', () => {
+    const url = draftModuleUrl(BASE, 7, 'src/scenes/race/RaceScene.ts');
+    expect(parseDraftUrl(url, BASE)).toEqual({
+      kind: 'module',
+      generation: 7,
+      path: 'src/scenes/race/RaceScene.ts',
+    });
+  });
+});
+
+describe('resolveSpecifier', () => {
+  it('resolves relative, alias and root paths the way Vite does here', () => {
+    expect(resolveSpecifier('./programs', 'src/game/content.ts', PATHS)).toEqual({
+      kind: 'draft',
+      path: 'src/game/programs.ts',
+    });
+    expect(resolveSpecifier('@/scenes/race', 'src/game/content.ts', PATHS)).toEqual({
+      kind: 'draft',
+      path: 'src/scenes/race/index.ts',
+    });
+    expect(resolveSpecifier('../../model/catalog.mjs', 'src/game/programs.ts', PATHS)).toEqual({
+      kind: 'draft',
+      path: 'model/catalog.mjs',
+    });
+    expect(resolveSpecifier('/model/tracks.json', 'src/game/programs.ts', PATHS)).toEqual({
+      kind: 'draft',
+      path: 'model/tracks.json',
+    });
+  });
+
+  it('sends bare and framework imports to the host, and reports what is missing', () => {
+    expect(resolveSpecifier('three', 'src/scenes/race/RaceScene.ts', PATHS)).toEqual({
+      kind: 'host',
+      specifier: 'three',
+    });
+    expect(
+      resolveSpecifier('@crowdedkingdoms/construct/engine/GameScene', 'src/game/content.ts', PATHS),
+    ).toEqual({
+      kind: 'host',
+      specifier: '@crowdedkingdoms/construct/engine/GameScene',
+    });
+    expect(resolveSpecifier('./nope', 'src/game/content.ts', PATHS)).toEqual({ kind: 'missing' });
+    expect(resolveSpecifier('../../../outside', 'src/game/content.ts', PATHS)).toEqual({
+      kind: 'missing',
+    });
+  });
+});
+
+describe('transformDraftModule', () => {
+  it('strips types, keeps line numbers, and rewrites every import', async () => {
+    const source = [
+      "import type { GameScene } from '@crowdedkingdoms/construct/engine/GameScene';",
+      "import { Scene } from 'three';",
+      "import { PROGRAMS } from './programs';",
+      'export const count: number = PROGRAMS.length;',
+      "export const later = () => import('@/scenes/race');",
+      'export const dev = import.meta.env.DEV;',
+      'if (import.meta.hot) import.meta.hot.accept();',
+      'export const scene: GameScene | null = new Scene() as unknown as GameScene;',
+    ].join('\n');
+    const code = await transformDraftModule({
+      source,
+      path: 'src/game/content.ts',
+      generation: 2,
+      base: BASE,
+      paths: PATHS,
+    });
+    expect(code).not.toContain('GameScene/');
+    expect(code).toMatch(/from ['"]\/the-construct\/__draft\/host\/three\.js['"]/);
+    expect(code).toMatch(/from ['"]\/the-construct\/__draft\/g2\/src\/game\/programs\.ts['"]/);
+    expect(code).toContain('import("/the-construct/__draft/g2/src/scenes/race/index.ts")');
+    expect(code).toContain('globalThis.__constructDraftEnv.DEV');
+    expect(code).toContain('if ((void 0))');
+    expect(code).not.toMatch(/: number|as unknown/);
+    expect(code.split('\n')).toHaveLength(source.split('\n').length);
+  });
+
+  it('serves JSON as a default export and refuses other files', async () => {
+    const json = await transformDraftModule({
+      source: '{"laps": 3}',
+      path: 'model/tracks.json',
+      generation: 1,
+      base: BASE,
+      paths: PATHS,
+    });
+    expect(json).toBe('export default {"laps":3};\n');
+    await expect(
+      transformDraftModule({
+        source: 'body{}',
+        path: 'src/style.css',
+        generation: 1,
+        base: BASE,
+        paths: PATHS,
+      }),
+    ).rejects.toThrow(/cannot be previewed/);
+  });
+
+  it('reports a syntax error with its file and line', async () => {
+    const failure = transformDraftModule({
+      source: 'export const a = 1;\nexport const b = ;\n',
+      path: 'src/game/programs.ts',
+      generation: 1,
+      base: BASE,
+      paths: PATHS,
+    });
+    await expect(failure).rejects.toBeInstanceOf(DraftTransformError);
+    await failure.catch((error: DraftTransformError) => {
+      expect(error.error).toMatchObject({ path: 'src/game/programs.ts', line: 2 });
+    });
+  });
+
+  it('points an unknown draft import at a module that explains itself', async () => {
+    const code = await transformDraftModule({
+      source: "import { x } from './gone';\nexport default x;\n",
+      path: 'src/game/content.ts',
+      generation: 1,
+      base: BASE,
+      paths: PATHS,
+    });
+    const url = /['"]([^'"]+missing[^'"]+)['"]/.exec(code)?.[1] ?? '';
+    expect(parseDraftUrl(url, BASE)).toEqual({
+      kind: 'missing',
+      importer: 'src/game/content.ts',
+      specifier: './gone',
+    });
+  });
+});
+
+describe('module sources', () => {
+  it('re-exports host names, reserved and default ones included', () => {
+    const code = hostShimSource('three', ['Scene', 'default', 'delete']);
+    expect(code).toContain('globalThis.__constructDraftHost("three")');
+    expect(code).toContain('export { __e0 as Scene };');
+    expect(code).toContain('export { __e1 as default };');
+    expect(code).toContain('export { __e2 as "delete" };');
+  });
+
+  it('throws with the location and keeps it for the preview status', () => {
+    const code = errorModuleSource({
+      path: 'src/a.ts',
+      line: 3,
+      column: 2,
+      message: 'Unexpected token',
+    });
+    expect(code).toContain('"src/a.ts:3:2: Unexpected token"');
+    expect(code).toContain(
+      'error.preview = {"path":"src/a.ts","line":3,"column":2,"message":"Unexpected token"}',
+    );
+  });
+});