@aethervtt/shard-project 0.0.1

package/dist/reload.js

@@ -0,0 +1,247 @@
+import { AssetServerResource } from "@aethervtt/shard-assets";
+import {
+  allComponents,
+  beginRedefinition,
+  defineEvent,
+  endRedefinition,
+  findResource,
+  ShardError
+} from "@aethervtt/shard-core";
+import { ProcgenResource } from "@aethervtt/shard-procgen";
+import { pathOfEntity } from "@aethervtt/shard-scene";
+const ProjectReloaded = defineEvent("project/ProjectReloaded", {
+  description: "The project code was hot reloaded."
+});
+function sameLayout(a, b) {
+  if (a.version !== b.version || a.layout.length !== b.layout.length) return false;
+  for (let i = 0; i < a.layout.length; i++) {
+    const x = a.layout[i];
+    const y = b.layout[i];
+    if (x.name !== y.name || x.storage !== y.storage || x.stride !== y.stride || x.field.kind !== y.field.kind)
+      return false;
+  }
+  return true;
+}
+function asPlugin(mod) {
+  const plugin = mod.default;
+  if (!plugin || typeof plugin.build !== "function" || typeof plugin.name !== "string") {
+    throw new ShardError(
+      "project/entry-invalid",
+      "The project bundle has no plugin as its default export",
+      {
+        hint: "End the entry file with `export default project`, where project = defineProject({...})."
+      }
+    );
+  }
+  return plugin;
+}
+function createProjectReloader(app, options) {
+  let current = options.current;
+  const world = app.world;
+  const observerStops = /* @__PURE__ */ new Map();
+  const build = async (plugin) => {
+    const saved = /* @__PURE__ */ new Map();
+    for (const name of namespaceResources()) {
+      const def = findResource(name);
+      if (world.hasResource(def)) saved.set(def.id, [def, world.resource(def)]);
+    }
+    const stops = [];
+    const observe = world.observe.bind(world);
+    world.observe = (...args) => {
+      const stop = observe(...args);
+      stops.push(stop);
+      return stop;
+    };
+    try {
+      await app.loadPlugin(plugin);
+    } finally {
+      ;
+      world.observe = observe;
+      observerStops.set(plugin.name, stops);
+      for (const [id, [oldDef, value]] of saved) {
+        const def = findResource(oldDef.name) ?? oldDef;
+        if (def.id === id && def.reload !== "replace") world.insertResource(def, value);
+      }
+    }
+  };
+  const unload = (plugin) => {
+    for (const stop of observerStops.get(plugin.name) ?? []) stop();
+    observerStops.delete(plugin.name);
+    return app.unloadPlugin(plugin.name);
+  };
+  const namespaceResources = () => {
+    const out = [];
+    for (const def of world.registry.describe().resources) {
+      if (def.name.startsWith(`${options.namespace}/`)) out.push(def.name);
+    }
+    return out;
+  };
+  const plan = (changes) => {
+    const plans = [];
+    for (const change of changes) {
+      if (change.kind !== "component") continue;
+      const previous = change.previous;
+      const def = change.next;
+      if (sameLayout(previous, def)) {
+        plans.push({ def, previous });
+        continue;
+      }
+      const before = /* @__PURE__ */ new Map();
+      const after = /* @__PURE__ */ new Map();
+      const fields = new Set(def.layout.map((c) => c.name));
+      for (const table of world.allTables()) {
+        if (!table.hasId(def.id)) continue;
+        for (let row = 0; row < table.count; row++) {
+          const entity = table.entities[row];
+          const value = table.readComponent(previous, row);
+          let json = previous.serialize(value);
+          if (def.version > previous.version) json = def.upgrade(json, previous.version);
+          if (json && typeof json === "object" && !Array.isArray(json)) {
+            json = Object.fromEntries(Object.entries(json).filter(([k]) => fields.has(k)));
+          }
+          const errors = def.validate(json);
+          if (errors.length > 0) {
+            const where = pathOfEntity(world, entity) ?? `entity ${entity}`;
+            throw new ShardError(
+              "project/migration-failed",
+              `Can't migrate ${def.name} on ${where}: ${errors[0].message}`,
+              {
+                path: errors[0].path,
+                hint: "Bump the component version and convert the old value in `migrate`, or change the field back.",
+                details: errors
+              }
+            );
+          }
+          before.set(entity, value);
+          after.set(entity, def.deserialize(json));
+        }
+      }
+      plans.push({ def, previous, values: { before, after } });
+    }
+    return plans;
+  };
+  const apply = (plans, direction) => {
+    for (const p of plans) {
+      const def = direction === "forward" ? p.def : p.previous;
+      const values = p.values && (direction === "forward" ? p.values.after : p.values.before);
+      world.redefine(def, values && ((_, entity) => values.get(entity)));
+    }
+  };
+  const redefineOthers = (changes, direction) => {
+    for (const c of changes) {
+      if (c.kind === "component") continue;
+      world.redefine(direction === "forward" ? c.next : c.previous);
+    }
+  };
+  const systemSources = (plugin) => {
+    const out = /* @__PURE__ */ new Map();
+    for (const name of app.systemsOf(plugin.name)) {
+      const run = app.systemRun(name);
+      out.set(name, run ? run.toString() : "");
+    }
+    return out;
+  };
+  return {
+    get current() {
+      return current;
+    },
+    async reload(load) {
+      const start = performance.now();
+      const report = {
+        ok: false,
+        ms: 0,
+        migrated: [],
+        orphaned: [],
+        systems: { added: [], removed: [], changed: [] },
+        assets: { imported: [], failed: [] },
+        procgen: { regenerated: [] }
+      };
+      const finish = (error) => {
+        report.ms = performance.now() - start;
+        if (error !== void 0) {
+          const e = error instanceof ShardError ? error : new ShardError(
+            "project/reload-failed",
+            String(error?.message ?? error),
+            {
+              cause: error
+            }
+          );
+          report.error = {
+            code: e.code,
+            message: e.message,
+            ...e.path ? { path: e.path } : {},
+            ...e.hint ? { hint: e.hint } : {},
+            ...sourceOf(error) ? { source: sourceOf(error) } : {}
+          };
+          return report;
+        }
+        report.ok = true;
+        world.send(ProjectReloaded, report);
+        return report;
+      };
+      const before = new Set(
+        allComponents().filter((d) => d.name.startsWith(`${options.namespace}/`)).map((d) => d.name)
+      );
+      let changes;
+      let next;
+      beginRedefinition(options.namespace);
+      try {
+        next = asPlugin(await load());
+      } catch (err) {
+        for (const c of endRedefinition()) c.undo();
+        return finish(err);
+      }
+      changes = endRedefinition();
+      const redefined = new Set(changes.map((c) => c.name));
+      report.orphaned = [...before].filter((n) => !redefined.has(n)).sort();
+      let plans;
+      try {
+        plans = plan(changes);
+      } catch (err) {
+        for (const c of changes) c.undo();
+        return finish(err);
+      }
+      const oldSources = systemSources(current);
+      apply(plans, "forward");
+      redefineOthers(changes, "forward");
+      unload(current);
+      try {
+        await build(next);
+      } catch (err) {
+        unload(next);
+        apply(plans, "back");
+        redefineOthers(changes, "back");
+        for (const c of changes) c.undo();
+        await build(current);
+        return finish(err);
+      }
+      const newSources = systemSources(next);
+      current = next;
+      report.migrated = plans.filter((p) => p.values).map((p) => p.def.name);
+      for (const [name, src] of newSources) {
+        if (!oldSources.has(name)) report.systems.added.push(name);
+        else if (oldSources.get(name) !== src) report.systems.changed.push(name);
+      }
+      for (const name of oldSources.keys())
+        if (!newSources.has(name)) report.systems.removed.push(name);
+      const assets = world.tryResource(AssetServerResource);
+      if (assets) {
+        const scan = await assets.scan();
+        report.assets.imported = scan.imported;
+        report.assets.failed = scan.failed.map((f) => f.path);
+        report.procgen.regenerated = scan.imported.filter((p) => p.endsWith(".gen.json"));
+      }
+      const runtime = world.tryResource(ProcgenResource);
+      if (runtime) report.procgen.regenerated.push(...runtime.regenerateStale());
+      return finish();
+    }
+  };
+}
+function sourceOf(err) {
+  const source = err?.source;
+  return typeof source === "string" ? source : void 0;
+}
+export {
+  ProjectReloaded,
+  createProjectReloader
+};

package/dist/session.d.ts

@@ -0,0 +1,73 @@
+import type { MethodDef } from '@aethervtt/shard-protocol';
+import { type App, type Plugin } from '@aethervtt/shard-runtime';
+import { createProjectReloader, type ReloadReport } from './reload.js';
+type ModuleLoader = () => Promise<{
+    default?: unknown;
+}>;
+/** Parameter schemas of the `project.*` protocol methods (tools read them before a session exists). */
+export declare const ProjectMethodParams: {
+    'project.status': import("@aethervtt/shard-core").ComponentDef<{}>;
+    'project.reload': import("@aethervtt/shard-core").ComponentDef<{
+        readonly url: import("@aethervtt/shard-core").FieldType<string, "object">;
+        readonly error: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+    }>;
+};
+export interface ProjectStatus {
+    /** The current bundle's content hash and build time. */
+    bundle?: {
+        hash: string;
+        ms: number;
+    };
+    /** How many reloads have succeeded. */
+    reloads: number;
+    lastReload?: ReloadReport;
+    /** The last build or reload failure, if the latest attempt failed. */
+    error?: {
+        code: string;
+        message: string;
+        path?: string;
+        hint?: string;
+        source?: string;
+    };
+    /** Components the current code no longer defines (kept in the world). */
+    orphaned: string[];
+    watching: boolean;
+}
+/**
+ * One running project's code: the reloader plus what happened last (bundle, reload, error), served
+ * to tools as `project.status` / `project.reload`. Hosts feed it bundles; it never builds itself.
+ */
+export declare class ProjectSession {
+    readonly app: App;
+    readonly reloader: ReturnType<typeof createProjectReloader>;
+    private state;
+    private readonly listeners;
+    /** Set by the host: rebuilds and returns a loader for the new bundle. */
+    rebuild: (() => Promise<{
+        load: ModuleLoader;
+        hash: string;
+        ms: number;
+    }>) | undefined;
+    constructor(app: App, options: {
+        namespace: string;
+        current: Plugin;
+        bundle?: {
+            hash: string;
+            ms: number;
+        };
+    });
+    status(): ProjectStatus;
+    set watching(on: boolean);
+    onChange(listener: (status: ProjectStatus) => void): () => void;
+    /** Reloads from a freshly built bundle. Failures are logged and reported, never thrown. */
+    reload(load: ModuleLoader, bundle?: {
+        hash: string;
+        ms: number;
+    }): Promise<ReloadReport>;
+    /** Records a bundle that failed to build (the running code is unchanged). */
+    buildFailed(error: unknown): void;
+    private emit;
+    /** `project.status` and `project.reload`, for the protocol server. */
+    methods(): MethodDef[];
+}
+export {};

package/dist/session.js

@@ -0,0 +1,144 @@
+import { defineSchema, ShardError, t } from "@aethervtt/shard-core";
+import { AppControlResource, LogResource } from "@aethervtt/shard-runtime";
+import { createProjectReloader } from "./reload.js";
+const ProjectMethodParams = {
+  "project.status": defineSchema("protocol/ProjectStatusParams", {}),
+  "project.reload": defineSchema("protocol/ProjectReloadParams", {
+    url: t.string({ description: "Load this bundle URL instead of rebuilding (dev servers)." }),
+    error: t.json({
+      description: "A dev server reporting that the bundle failed to build: { code, message, source }."
+    })
+  })
+};
+class ProjectSession {
+  app;
+  reloader;
+  state = { reloads: 0, orphaned: [], watching: false };
+  listeners = /* @__PURE__ */ new Set();
+  /** Set by the host: rebuilds and returns a loader for the new bundle. */
+  rebuild;
+  constructor(app, options) {
+    this.app = app;
+    this.reloader = createProjectReloader(app, options);
+    if (options.bundle) this.state.bundle = options.bundle;
+  }
+  status() {
+    return structuredClone(this.state);
+  }
+  set watching(on) {
+    this.state.watching = on;
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /** Reloads from a freshly built bundle. Failures are logged and reported, never thrown. */
+  async reload(load, bundle) {
+    const report = await this.reloader.reload(load);
+    this.state.lastReload = report;
+    if (report.ok) {
+      this.state.reloads++;
+      const control = this.app.world.resource(AppControlResource);
+      if (control.pausedByError) {
+        control.paused = false;
+        control.pausedByError = false;
+      }
+      this.state.orphaned = report.orphaned;
+      delete this.state.error;
+      if (bundle) this.state.bundle = bundle;
+      this.app.world.resource(LogResource).info(
+        `Project reloaded in ${Math.round(report.ms)} ms${report.migrated.length ? ` (migrated ${report.migrated.join(", ")})` : ""}`
+      );
+    } else {
+      this.state.error = report.error;
+      this.app.world.resource(LogResource).error(
+        Object.assign(
+          new ShardError(report.error.code, report.error.message, {
+            path: report.error.path,
+            hint: report.error.hint
+          }),
+          { source: report.error.source }
+        )
+      );
+    }
+    this.emit();
+    return report;
+  }
+  /** Records a bundle that failed to build (the running code is unchanged). */
+  buildFailed(error) {
+    const e = error instanceof ShardError ? error : new ShardError("project/bundle-failed", String(error));
+    const source = error?.source;
+    this.state.error = {
+      code: e.code,
+      message: e.message,
+      ...e.path ? { path: e.path } : {},
+      ...e.hint ? { hint: e.hint } : {},
+      ...typeof source === "string" ? { source } : {}
+    };
+    this.app.world.resource(LogResource).error(error);
+    this.emit();
+  }
+  emit() {
+    const status = this.status();
+    for (const l of this.listeners) l(status);
+  }
+  /** `project.status` and `project.reload`, for the protocol server. */
+  methods() {
+    return [
+      {
+        name: "project.status",
+        description: "The project code: current bundle, reload count, the last reload report (migrated and orphaned components, systems added/removed/changed), and the last build or reload error with its source location.",
+        params: ProjectMethodParams["project.status"],
+        handler: () => this.status()
+      },
+      {
+        name: "project.reload",
+        description: "Rebuilds the project bundle and hot reloads it now (normally this happens on save). Returns the reload report.",
+        params: ProjectMethodParams["project.reload"],
+        handler: async (_ctx, p) => {
+          if (p.error) {
+            const e = p.error;
+            this.buildFailed(
+              Object.assign(
+                new ShardError(
+                  e.code ?? "project/bundle-failed",
+                  e.message ?? "The bundle failed to build",
+                  {
+                    path: e.path,
+                    hint: e.hint
+                  }
+                ),
+                { source: e.source }
+              )
+            );
+            return this.status();
+          }
+          if (p.url) {
+            const url = p.url;
+            return this.reload(() => import(
+              /* @vite-ignore */
+              url
+            ), { hash: url, ms: 0 });
+          }
+          if (!this.rebuild) {
+            throw new ShardError("project/no-bundler", "This host has no bundler to rebuild with", {
+              hint: 'Pass "url" with a built bundle.'
+            });
+          }
+          let built;
+          try {
+            built = await this.rebuild();
+          } catch (err) {
+            this.buildFailed(err);
+            throw err;
+          }
+          return this.reload(built.load, { hash: built.hash, ms: built.ms });
+        }
+      }
+    ];
+  }
+}
+export {
+  ProjectMethodParams,
+  ProjectSession
+};

package/dist/sourcemap.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Just enough source-map reading to turn a bundle stack frame back into `scripts/x.ts:line:col`.
+ * Works on every host (no Node APIs), so the browser runner and the CLI report errors the same way.
+ */
+export interface SourceMapData {
+    version: number;
+    sources: string[];
+    mappings: string;
+    sourceRoot?: string;
+}
+export interface SourcePosition {
+    source: string;
+    /** 1-based. */
+    line: number;
+    /** 1-based. */
+    column: number;
+}
+/** Decoded mappings: `lookup(line, column)` with 1-based generated positions. */
+export declare class SourceMap {
+    readonly sources: string[];
+    private readonly lines;
+    constructor(data: SourceMapData);
+    lookup(line: number, column: number): SourcePosition | undefined;
+}
+/** The inline source map in a bundle's text (`//# sourceMappingURL=data:...;base64,...`). */
+export declare function inlineSourceMap(code: string): SourceMap | undefined;
+/**
+ * The first stack frame of `error` inside the bundle at `bundleUrl`, mapped to project source and
+ * made relative (`scripts/main.ts:42:7`). Frames in dependencies (node_modules) are skipped.
+ */
+export declare function locateInBundle(error: unknown, bundleUrl: string, map: SourceMap, normalize?: (source: string) => string): string | undefined;

package/dist/sourcemap.js

@@ -0,0 +1,91 @@
+const B64 = new Map(
+  [..."ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"].map((c, i) => [c, i])
+);
+class SourceMap {
+  sources;
+  lines = [];
+  constructor(data) {
+    this.sources = data.sources.map((s) => data.sourceRoot ? `${data.sourceRoot}${s}` : s);
+    let source = 0;
+    let line = 0;
+    let sourceColumn = 0;
+    for (const text of data.mappings.split(";")) {
+      const segments = [];
+      let column = 0;
+      for (const segment of text.split(",")) {
+        if (segment === "") continue;
+        const values = decodeVlq(segment);
+        column += values[0];
+        if (values.length >= 4) {
+          source += values[1];
+          line += values[2];
+          sourceColumn += values[3];
+          segments.push({ column, source, line, sourceColumn });
+        }
+      }
+      this.lines.push(segments);
+    }
+  }
+  lookup(line, column) {
+    const segments = this.lines[line - 1];
+    if (!segments || segments.length === 0) return void 0;
+    let best;
+    for (const s of segments) {
+      if (s.column > column - 1) break;
+      best = s;
+    }
+    best ??= segments[0];
+    return {
+      source: this.sources[best.source],
+      line: best.line + 1,
+      column: best.sourceColumn + 1
+    };
+  }
+}
+function decodeVlq(text) {
+  const out = [];
+  let value = 0;
+  let shift = 0;
+  for (const char of text) {
+    const digit = B64.get(char);
+    value += (digit & 31) << shift;
+    if (digit & 32) {
+      shift += 5;
+    } else {
+      const negative = value & 1;
+      value >>>= 1;
+      out.push(negative ? -value : value);
+      value = 0;
+      shift = 0;
+    }
+  }
+  return out;
+}
+function inlineSourceMap(code) {
+  const m = /\/\/# sourceMappingURL=data:application\/json;(?:charset=utf-8;)?base64,([A-Za-z0-9+/=]+)\s*$/.exec(
+    code
+  );
+  if (!m) return void 0;
+  const json = new TextDecoder().decode(Uint8Array.from(atob(m[1]), (c) => c.charCodeAt(0)));
+  return new SourceMap(JSON.parse(json));
+}
+function locateInBundle(error, bundleUrl, map, normalize = (s) => s) {
+  const stack = error?.stack;
+  if (typeof stack !== "string") return void 0;
+  const file = bundleUrl.replace(/[?#].*$/, "");
+  for (const line of stack.split("\n")) {
+    const at = line.lastIndexOf(file);
+    if (at === -1) continue;
+    const m = /:(\d+):(\d+)/.exec(line.slice(at + file.length));
+    if (!m) continue;
+    const pos = map.lookup(Number(m[1]), Number(m[2]));
+    if (!pos || pos.source.includes("node_modules")) continue;
+    return `${normalize(pos.source)}:${pos.line}:${pos.column}`;
+  }
+  return void 0;
+}
+export {
+  SourceMap,
+  inlineSourceMap,
+  locateInBundle
+};

package/dist/templates.d.ts

@@ -0,0 +1,9 @@
+export type TemplateName = 'empty' | 'explorer';
+export interface TemplateOptions {
+    name: string;
+    template: TemplateName;
+    /** Version spec for `@aethervtt/shard-*` dependencies: `workspace:*` inside the Shard repo, a range otherwise. */
+    engineSpec: string;
+}
+/** Files for a new project, by project-relative path. */
+export declare function projectTemplate(options: TemplateOptions): Record<string, string>;