@aethervtt/shard-runtime 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-runtime
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/app.d.ts

@@ -0,0 +1,113 @@
+import { type ComponentDef, type ResourceDef, type ScheduleLabel, type SystemConfig, type SystemDef, type SystemDescription, type SystemSetConfig, World } from '@aethervtt/shard-core';
+import type { Plugin } from './plugin.js';
+import type { Runner } from './runners.js';
+import { type StateDef } from './state.js';
+export interface AppOptions {
+    /** FixedUpdate rate. Default 60. */
+    fixedHz?: number;
+    /** Most FixedUpdate runs per frame; excess time is dropped. Default 5. */
+    maxFixedSteps?: number;
+    /** Clock for profiling, in ms. Defaults to `performance.now`. */
+    now?: () => number;
+    /** Seed for the `GlobalRng` resource. Default 0. */
+    seed?: number;
+}
+export interface AppDescription {
+    plugins: {
+        name: string;
+        dependencies: string[];
+    }[];
+    schedules: {
+        name: string;
+        systems: SystemDescription[];
+    }[];
+}
+type SystemInput = SystemDef<unknown> | SystemConfig;
+/**
+ * A protocol method a plugin contributes (`physics.raycast`). The protocol server serves every
+ * app method next to its built-in ones, so packages expose themselves without the protocol
+ * importing them.
+ */
+export interface AppMethod {
+    /** `<area>.<verb>`, e.g. `physics.raycast`. */
+    name: string;
+    description: string;
+    /** Parameter schema (`defineSchema`); the protocol validates params against it. */
+    params: ComponentDef;
+    handler(ctx: {
+        app: App;
+        world: World;
+    }, params: Record<string, unknown>): unknown;
+}
+/**
+ * Owns the world, plugins, and schedules, and runs frames. Hosts drive it with a runner
+ * (animation frame, headless, or manual `update` calls).
+ */
+export declare class App {
+    readonly world: World;
+    readonly fixedHz: number;
+    private readonly maxFixedSteps;
+    private readonly now;
+    private readonly plugins;
+    private readonly pending;
+    private readonly schedules;
+    private readonly systemNames;
+    private readonly states;
+    private readonly profiler;
+    private runner;
+    private initialized;
+    private startupDone;
+    private accumulator;
+    private readonly frameListeners;
+    private readonly appMethods;
+    /** The plugin whose `build` is running, so registrations can be attributed to it. */
+    private building;
+    private readonly owned;
+    constructor(options?: AppOptions);
+    /** Adds plugins. They build in dependency order during `init()`. */
+    addPlugin(...plugins: Plugin[]): this;
+    /** Adds protocol methods (see `AppMethod`). A second method with a taken name throws. */
+    addMethod(...methods: AppMethod[]): this;
+    /** Methods plugins added, in the order they were added. */
+    get methods(): readonly AppMethod[];
+    addSystems(schedule: ScheduleLabel, ...systems: SystemInput[]): this;
+    configureSets(schedule: ScheduleLabel, ...sets: SystemSetConfig[]): this;
+    private ownedBy;
+    /** A registered system's run function, by name (hot reload compares them). */
+    systemRun(name: string): ((...args: never[]) => unknown) | undefined;
+    /** Names of the systems a plugin registered. */
+    systemsOf(plugin: string): string[];
+    /**
+     * Removes a plugin from a running app: every system and set config it registered, and the plugin
+     * itself. Resources and entities stay. For hot reload; returns the removed system names.
+     */
+    unloadPlugin(name: string): string[];
+    /**
+     * Builds a plugin into an app that's already running (hot reload). Its systems set up on their
+     * first run. Startup systems it adds don't run: startup already happened.
+     */
+    loadPlugin(plugin: Plugin): Promise<void>;
+    insertResource<T>(def: ResourceDef<T>, value: T): this;
+    /** Registers a state machine. `OnEnter(initial)` runs at the start of the first frame. */
+    initState<T extends string>(state: StateDef<T>, initial?: NoInfer<T>): this;
+    setRunner(runner: Runner): this;
+    /** Builds plugins in dependency order, then awaits their `ready` hooks. */
+    init(): Promise<void>;
+    /** Initializes, then hands control to the runner (manual if none was set). */
+    run(): Promise<void>;
+    /** Runs one frame. `delta` is in seconds. */
+    update(delta: number): void;
+    /** Called after every frame with the number of frames completed. Returns an unsubscribe function. */
+    onFrame(listener: (frame: number) => void): () => void;
+    /**
+     * Runs any stepped frames requested through `AppControl` right now, at the fixed delta. For hosts
+     * without a frame loop (headless servers); loop-driven runners step one frame per tick instead.
+     */
+    pump(): void;
+    runSchedule(label: ScheduleLabel): void;
+    describe(): AppDescription;
+    private schedule;
+    private applyStateTransitions;
+    private dependencyError;
+}
+export {};

package/dist/app.js

@@ -0,0 +1,348 @@
+import {
+  First,
+  FixedUpdate,
+  Last,
+  PostUpdate,
+  PreUpdate,
+  Profiler,
+  ProfilerResource,
+  Rng,
+  Schedule,
+  ShardError,
+  Startup,
+  Update,
+  World
+} from "@aethervtt/shard-core";
+import { AppControl, AppControlResource } from "./control.js";
+import { Log, LogResource } from "./log.js";
+import { OnEnter, OnExit } from "./state.js";
+import { DisplayRate, FixedTime, GlobalRng, Time } from "./time.js";
+const FRAME_SCHEDULES = [Startup, First, PreUpdate, FixedUpdate, Update, PostUpdate, Last];
+const EPSILON = 1e-9;
+const TimePlugin = {
+  name: "core/time",
+  build(app) {
+    app.insertResource(Time, { delta: 0, elapsed: 0, frame: 0 });
+    app.insertResource(FixedTime, { step: 1 / app.fixedHz, elapsed: 0, alpha: 0, steps: 0 });
+    app.insertResource(DisplayRate, { hz: 60, periodMs: 1e3 / 60, source: "assumed" });
+  }
+};
+class App {
+  world = new World();
+  fixedHz;
+  maxFixedSteps;
+  now;
+  plugins = /* @__PURE__ */ new Map();
+  pending = [];
+  schedules = /* @__PURE__ */ new Map();
+  systemNames = /* @__PURE__ */ new Set();
+  states = [];
+  profiler = new Profiler();
+  runner;
+  initialized = false;
+  startupDone = false;
+  accumulator = 0;
+  frameListeners = /* @__PURE__ */ new Set();
+  appMethods = /* @__PURE__ */ new Map();
+  /** The plugin whose `build` is running, so registrations can be attributed to it. */
+  building;
+  owned = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.fixedHz = options.fixedHz ?? 60;
+    this.maxFixedSteps = options.maxFixedSteps ?? 5;
+    this.now = options.now ?? (() => performance.now());
+    this.world.insertResource(ProfilerResource, this.profiler);
+    this.world.insertResource(GlobalRng, new Rng(options.seed ?? 0));
+    const log = new Log();
+    log.now = () => this.world.tryResource(Time)?.elapsed ?? 0;
+    this.world.insertResource(LogResource, log);
+    this.world.insertResource(AppControlResource, new AppControl());
+    this.addPlugin(TimePlugin);
+  }
+  // --- building --------------------------------------------------------------
+  /** Adds plugins. They build in dependency order during `init()`. */
+  addPlugin(...plugins) {
+    for (const plugin of plugins) {
+      if (this.plugins.has(plugin.name)) {
+        throw new ShardError("app/duplicate-plugin", `Plugin "${plugin.name}" was added twice`);
+      }
+      this.plugins.set(plugin.name, plugin);
+      this.pending.push(plugin);
+    }
+    return this;
+  }
+  /** Adds protocol methods (see `AppMethod`). A second method with a taken name throws. */
+  addMethod(...methods) {
+    for (const method of methods) {
+      if (this.appMethods.has(method.name)) {
+        throw new ShardError("app/duplicate-method", `Method "${method.name}" was added twice`);
+      }
+      this.appMethods.set(method.name, method);
+    }
+    return this;
+  }
+  /** Methods plugins added, in the order they were added. */
+  get methods() {
+    return [...this.appMethods.values()];
+  }
+  addSystems(schedule, ...systems) {
+    const target = this.schedule(schedule);
+    for (const system of systems) {
+      const name = "system" in system ? system.system.name : system.name;
+      if (this.systemNames.has(name)) {
+        throw new ShardError("app/duplicate-system", `A system named "${name}" was already added`, {
+          hint: "System names must be unique across all schedules."
+        });
+      }
+      this.systemNames.add(name);
+      target.add(system);
+      this.ownedBy()?.systems.push({ schedule, name });
+    }
+    return this;
+  }
+  configureSets(schedule, ...sets) {
+    const target = this.schedule(schedule);
+    for (const set of sets) {
+      target.configureSet(set);
+      this.ownedBy()?.sets.push({ schedule, config: set });
+    }
+    return this;
+  }
+  ownedBy() {
+    if (this.building === void 0) return void 0;
+    let owned = this.owned.get(this.building);
+    if (!owned) {
+      owned = { systems: [], sets: [] };
+      this.owned.set(this.building, owned);
+    }
+    return owned;
+  }
+  /** A registered system's run function, by name (hot reload compares them). */
+  systemRun(name) {
+    for (const schedule of this.schedules.values()) {
+      for (const config of schedule.ordered()) {
+        if (config.system.name === name) return config.system.run;
+      }
+    }
+    return void 0;
+  }
+  /** Names of the systems a plugin registered. */
+  systemsOf(plugin) {
+    return this.owned.get(plugin)?.systems.map((s) => s.name) ?? [];
+  }
+  /**
+   * Removes a plugin from a running app: every system and set config it registered, and the plugin
+   * itself. Resources and entities stay. For hot reload; returns the removed system names.
+   */
+  unloadPlugin(name) {
+    const owned = this.owned.get(name);
+    this.plugins.delete(name);
+    this.owned.delete(name);
+    if (!owned) return [];
+    const bySchedule = /* @__PURE__ */ new Map();
+    const entry = (label) => {
+      let e = bySchedule.get(label);
+      if (!e) {
+        e = { systems: /* @__PURE__ */ new Set(), sets: /* @__PURE__ */ new Set() };
+        bySchedule.set(label, e);
+      }
+      return e;
+    };
+    for (const s of owned.systems) entry(s.schedule).systems.add(s.name);
+    for (const s of owned.sets) entry(s.schedule).sets.add(s.config);
+    for (const [label, e] of bySchedule) this.schedules.get(label)?.remove(e.systems, e.sets);
+    for (const s of owned.systems) this.systemNames.delete(s.name);
+    return owned.systems.map((s) => s.name);
+  }
+  /**
+   * Builds a plugin into an app that's already running (hot reload). Its systems set up on their
+   * first run. Startup systems it adds don't run: startup already happened.
+   */
+  async loadPlugin(plugin) {
+    if (this.plugins.has(plugin.name)) {
+      throw new ShardError("app/duplicate-plugin", `Plugin "${plugin.name}" is already loaded`, {
+        hint: "Unload it first (unloadPlugin)."
+      });
+    }
+    this.plugins.set(plugin.name, plugin);
+    this.building = plugin.name;
+    try {
+      plugin.build(this);
+    } finally {
+      this.building = void 0;
+    }
+    await plugin.ready?.(this);
+  }
+  insertResource(def, value) {
+    this.world.insertResource(def, value);
+    return this;
+  }
+  /** Registers a state machine. `OnEnter(initial)` runs at the start of the first frame. */
+  initState(state, initial = state.values[0]) {
+    this.world.insertResource(state.resource, { current: initial, next: void 0 });
+    this.states.push({ state, entered: false });
+    return this;
+  }
+  setRunner(runner) {
+    this.runner = runner;
+    return this;
+  }
+  /** Builds plugins in dependency order, then awaits their `ready` hooks. */
+  async init() {
+    if (this.initialized) return;
+    const built = [];
+    const builtNames = /* @__PURE__ */ new Set();
+    while (this.pending.length > 0) {
+      const index = this.pending.findIndex(
+        (p) => (p.dependencies ?? []).every((d) => builtNames.has(d))
+      );
+      if (index === -1) throw this.dependencyError(builtNames);
+      const [plugin] = this.pending.splice(index, 1);
+      this.building = plugin.name;
+      try {
+        plugin.build(this);
+      } finally {
+        this.building = void 0;
+      }
+      built.push(plugin);
+      builtNames.add(plugin.name);
+    }
+    for (const plugin of built) await plugin.ready?.(this);
+    this.initialized = true;
+  }
+  /** Initializes, then hands control to the runner (manual if none was set). */
+  async run() {
+    await this.init();
+    await this.runner?.(this);
+  }
+  // --- running ---------------------------------------------------------------
+  /** Runs one frame. `delta` is in seconds. */
+  update(delta) {
+    if (!this.initialized) {
+      throw new ShardError("app/not-initialized", "App.update() was called before init()", {
+        hint: "Await app.init() (or app.run()) first."
+      });
+    }
+    const world = this.world;
+    if (!this.startupDone) {
+      this.runSchedule(Startup);
+      this.startupDone = true;
+    }
+    this.applyStateTransitions();
+    world.updateEvents();
+    const time = world.resource(Time);
+    time.delta = delta;
+    time.elapsed += delta;
+    this.runSchedule(First);
+    this.runSchedule(PreUpdate);
+    const fixed = world.resource(FixedTime);
+    this.accumulator += delta;
+    let steps = 0;
+    while (this.accumulator + EPSILON >= fixed.step && steps < this.maxFixedSteps) {
+      fixed.elapsed += fixed.step;
+      this.runSchedule(FixedUpdate);
+      this.accumulator = Math.max(0, this.accumulator - fixed.step);
+      steps++;
+    }
+    if (this.accumulator + EPSILON >= fixed.step) this.accumulator %= fixed.step;
+    fixed.steps = steps;
+    fixed.alpha = Math.min(1, this.accumulator / fixed.step);
+    this.runSchedule(Update);
+    this.runSchedule(PostUpdate);
+    this.runSchedule(Last);
+    time.frame++;
+    for (const listener of this.frameListeners) listener(time.frame);
+  }
+  /** Called after every frame with the number of frames completed. Returns an unsubscribe function. */
+  onFrame(listener) {
+    this.frameListeners.add(listener);
+    return () => this.frameListeners.delete(listener);
+  }
+  /**
+   * Runs any stepped frames requested through `AppControl` right now, at the fixed delta. For hosts
+   * without a frame loop (headless servers); loop-driven runners step one frame per tick instead.
+   */
+  pump() {
+    const control = this.world.resource(AppControlResource);
+    while (control.pendingSteps > 0) {
+      try {
+        this.update(1 / this.fixedHz);
+      } catch (err) {
+        this.world.resource(LogResource).error(err);
+        control.paused = true;
+        control.pausedByError = true;
+        control.abort(err);
+        throw err;
+      }
+      control.stepped();
+    }
+  }
+  runSchedule(label) {
+    const schedule = this.schedules.get(label);
+    if (schedule && schedule.size > 0) {
+      schedule.run(this.world, { now: this.now, profiler: this.profiler });
+    }
+  }
+  // --- introspection ---------------------------------------------------------
+  describe() {
+    const order = [
+      ...FRAME_SCHEDULES.filter((l) => this.schedules.has(l)),
+      ...[...this.schedules.keys()].filter((l) => !FRAME_SCHEDULES.includes(l))
+    ];
+    return {
+      plugins: [...this.plugins.values()].map((p) => ({
+        name: p.name,
+        dependencies: [...p.dependencies ?? []]
+      })),
+      schedules: order.map((label) => ({
+        name: label.name,
+        systems: this.schedules.get(label).describe()
+      }))
+    };
+  }
+  // --- internals -------------------------------------------------------------
+  schedule(label) {
+    let schedule = this.schedules.get(label);
+    if (!schedule) {
+      schedule = new Schedule(label);
+      this.schedules.set(label, schedule);
+    }
+    return schedule;
+  }
+  applyStateTransitions() {
+    for (const driver of this.states) {
+      const value = this.world.resource(driver.state.resource);
+      if (!driver.entered) {
+        driver.entered = true;
+        this.runSchedule(OnEnter(driver.state, value.current));
+      }
+      const next = value.next;
+      value.next = void 0;
+      if (next === void 0 || next === value.current) continue;
+      this.runSchedule(OnExit(driver.state, value.current));
+      value.current = next;
+      this.runSchedule(OnEnter(driver.state, next));
+    }
+  }
+  dependencyError(built) {
+    for (const plugin of this.pending) {
+      for (const dep of plugin.dependencies ?? []) {
+        if (!this.plugins.has(dep)) {
+          return new ShardError(
+            "app/missing-plugin",
+            `Plugin "${plugin.name}" depends on "${dep}", which was never added`,
+            { hint: `Add the "${dep}" plugin before calling init().` }
+          );
+        }
+      }
+    }
+    const stuck = this.pending.map((p) => p.name).filter((n) => !built.has(n));
+    return new ShardError(
+      "app/plugin-cycle",
+      `Plugins depend on each other in a cycle: ${stuck.join(", ")}`
+    );
+  }
+}
+export {
+  App
+};

package/dist/control.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Frame control shared by every runner: pause, resume, and step exactly N frames. Stepped frames
+ * use the fixed delta, so seeded runs stay deterministic under stepping.
+ */
+export declare class AppControl {
+    paused: boolean;
+    /** Set when a failing frame paused the app, so a fix (e.g. a hot reload) can resume it. */
+    pausedByError: boolean;
+    /** Stepped frames ever requested / ever run. Both only grow; the difference is what's pending. */
+    private requested;
+    private completed;
+    private waiters;
+    get pendingSteps(): number;
+    /** Pauses the app and queues `frames` stepped frames; resolves once they've run. */
+    step(frames: number): Promise<void>;
+    /** A stepped frame threw: drops the pending steps and rejects everyone waiting on them. */
+    abort(error: unknown): void;
+    /** @internal Runners call this after running one stepped frame. */
+    stepped(): void;
+}
+export declare const AppControlResource: import("@aethervtt/shard-core").ResourceDef<AppControl>;

package/dist/control.js

@@ -0,0 +1,41 @@
+import { defineResource } from "@aethervtt/shard-core";
+class AppControl {
+  paused = false;
+  /** Set when a failing frame paused the app, so a fix (e.g. a hot reload) can resume it. */
+  pausedByError = false;
+  /** Stepped frames ever requested / ever run. Both only grow; the difference is what's pending. */
+  requested = 0;
+  completed = 0;
+  waiters = [];
+  get pendingSteps() {
+    return this.requested - this.completed;
+  }
+  /** Pauses the app and queues `frames` stepped frames; resolves once they've run. */
+  step(frames) {
+    this.paused = true;
+    if (frames <= 0) return Promise.resolve();
+    this.requested += frames;
+    const target = this.requested;
+    return new Promise((resolve, reject) => this.waiters.push({ target, resolve, reject }));
+  }
+  /** A stepped frame threw: drops the pending steps and rejects everyone waiting on them. */
+  abort(error) {
+    this.completed = this.requested;
+    for (const w of this.waiters.splice(0)) w.reject(error);
+  }
+  /** @internal Runners call this after running one stepped frame. */
+  stepped() {
+    if (this.pendingSteps === 0) return;
+    this.completed++;
+    while (this.waiters.length > 0 && this.waiters[0].target <= this.completed) {
+      this.waiters.shift().resolve();
+    }
+  }
+}
+const AppControlResource = defineResource("core/AppControl", {
+  description: "Pause, resume, and step the app. Runners honor it every frame."
+});
+export {
+  AppControl,
+  AppControlResource
+};

package/dist/display.d.ts

@@ -0,0 +1,19 @@
+/** Refresh rates displays ship with. A measurement within 4% of one snaps to it. */
+export declare const COMMON_RATES: number[];
+/** The nearest common rate within 4%, else the measurement rounded to a whole Hz. */
+export declare function snapRate(hz: number): number;
+/** The refresh rate a run of frame intervals (ms) shows: their median, snapped. */
+export declare function rateFromIntervals(intervals: ArrayLike<number>): number;
+/**
+ * Watches frame intervals after the startup probe. An app that can't keep up only ever shows
+ * slower intervals than the display's, so only faster ones count: a run of them (the window moved
+ * to a faster screen, or ProMotion left its idle rate) raises the rate. Allocates nothing.
+ */
+export declare class RefreshMeter {
+    periodMs: number;
+    private readonly run;
+    private count;
+    constructor(periodMs: number);
+    /** One frame interval in ms. Returns the new rate in Hz when it rose, else 0. */
+    sample(intervalMs: number): number;
+}

package/dist/display.js

@@ -0,0 +1,48 @@
+const COMMON_RATES = [24, 30, 48, 50, 60, 72, 75, 85, 90, 100, 120, 144, 165, 180, 240, 360];
+function snapRate(hz) {
+  let best = Math.round(hz);
+  let error = 0.04;
+  for (const rate of COMMON_RATES) {
+    const e = Math.abs(hz - rate) / rate;
+    if (e < error) {
+      error = e;
+      best = rate;
+    }
+  }
+  return best;
+}
+function rateFromIntervals(intervals) {
+  const sorted = Array.from(intervals).sort((a, b) => a - b);
+  const median = sorted[sorted.length >> 1];
+  return snapRate(1e3 / median);
+}
+const RUN = 20;
+class RefreshMeter {
+  periodMs;
+  run = new Float64Array(RUN);
+  count = 0;
+  constructor(periodMs) {
+    this.periodMs = periodMs;
+  }
+  /** One frame interval in ms. Returns the new rate in Hz when it rose, else 0. */
+  sample(intervalMs) {
+    if (intervalMs < 2 || intervalMs > this.periodMs * 0.85) {
+      this.count = 0;
+      return 0;
+    }
+    this.run[this.count++] = intervalMs;
+    if (this.count < RUN) return 0;
+    this.count = 0;
+    this.run.sort();
+    const hz = snapRate(1e3 / this.run[RUN >> 1]);
+    if (1e3 / hz >= this.periodMs * 0.95) return 0;
+    this.periodMs = 1e3 / hz;
+    return hz;
+  }
+}
+export {
+  COMMON_RATES,
+  RefreshMeter,
+  rateFromIntervals,
+  snapRate
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { App, type AppDescription, type AppMethod, type AppOptions } from './app.js';
+export { AppControl, AppControlResource } from './control.js';
+export { COMMON_RATES, RefreshMeter, rateFromIntervals, snapRate } from './display.js';
+export { Log, type LogEntry, type LogLevel, LogResource } from './log.js';
+export { definePlugin, type Plugin } from './plugin.js';
+export { type AnimationFrameOptions, animationFrameRunner, type HeadlessOptions, headlessRunner, type Runner, } from './runners.js';
+export { defineState, inState, OnEnter, OnExit, type StateDef, type StateValue, setState, } from './state.js';
+export { DisplayRate, type DisplayRateData, FixedTime, type FixedTimeData, GlobalRng, Time, type TimeData, } from './time.js';

package/dist/index.js

@@ -0,0 +1,45 @@
+import { App } from "./app.js";
+import { AppControl, AppControlResource } from "./control.js";
+import { COMMON_RATES, RefreshMeter, rateFromIntervals, snapRate } from "./display.js";
+import { Log, LogResource } from "./log.js";
+import { definePlugin } from "./plugin.js";
+import {
+  animationFrameRunner,
+  headlessRunner
+} from "./runners.js";
+import {
+  defineState,
+  inState,
+  OnEnter,
+  OnExit,
+  setState
+} from "./state.js";
+import {
+  DisplayRate,
+  FixedTime,
+  GlobalRng,
+  Time
+} from "./time.js";
+export {
+  App,
+  AppControl,
+  AppControlResource,
+  COMMON_RATES,
+  DisplayRate,
+  FixedTime,
+  GlobalRng,
+  Log,
+  LogResource,
+  OnEnter,
+  OnExit,
+  RefreshMeter,
+  Time,
+  animationFrameRunner,
+  definePlugin,
+  defineState,
+  headlessRunner,
+  inState,
+  rateFromIntervals,
+  setState,
+  snapRate
+};

package/dist/log.d.ts

@@ -0,0 +1,44 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    /** Monotonic sequence number, for subscribers that resume. */
+    seq: number;
+    level: LogLevel;
+    message: string;
+    /** App time in seconds when logged. */
+    time: number;
+    code?: string;
+    path?: string;
+    hint?: string;
+    /** Where in project source an error was thrown: `scripts/main.ts:42:7`. */
+    source?: string;
+    data?: unknown;
+}
+/**
+ * Structured log, kept as a ring buffer. Errors from systems, the GPU, and shaders land here, so
+ * tools (and agents) can read what happened without scraping a console.
+ */
+export declare class Log {
+    readonly capacity: number;
+    private readonly entries;
+    private readonly listeners;
+    private seq;
+    /** App time source; set by the app. */
+    now: () => number;
+    /**
+     * Adds fields to logged errors. Hosts that bundle project code set this to map stack frames back
+     * to project source (`source`).
+     */
+    annotate: ((error: unknown) => Partial<LogEntry> | undefined) | undefined;
+    constructor(capacity?: number);
+    log(level: LogLevel, message: string, extra?: Partial<Omit<LogEntry, 'seq' | 'level' | 'message' | 'time'>>): LogEntry;
+    debug(message: string, data?: unknown): LogEntry;
+    info(message: string, data?: unknown): LogEntry;
+    warn(message: string, data?: unknown): LogEntry;
+    /** Logs any thrown value; ShardErrors keep their code, path, and hint. */
+    error(error: unknown): LogEntry;
+    /** The last `count` entries at or above `level`, oldest first. */
+    tail(count?: number, level?: LogLevel): LogEntry[];
+    errors(count?: number): LogEntry[];
+    subscribe(listener: (entry: LogEntry) => void): () => void;
+}
+export declare const LogResource: import("@aethervtt/shard-core").ResourceDef<Log>;

package/dist/log.js

@@ -0,0 +1,68 @@
+import { defineResource, ShardError } from "@aethervtt/shard-core";
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+class Log {
+  capacity;
+  entries = [];
+  listeners = /* @__PURE__ */ new Set();
+  seq = 0;
+  /** App time source; set by the app. */
+  now = () => 0;
+  /**
+   * Adds fields to logged errors. Hosts that bundle project code set this to map stack frames back
+   * to project source (`source`).
+   */
+  annotate = void 0;
+  constructor(capacity = 500) {
+    this.capacity = capacity;
+  }
+  log(level, message, extra = {}) {
+    const entry = { seq: this.seq++, level, message, time: this.now(), ...extra };
+    this.entries.push(entry);
+    if (this.entries.length > this.capacity) this.entries.shift();
+    for (const listener of this.listeners) listener(entry);
+    return entry;
+  }
+  debug(message, data) {
+    return this.log("debug", message, data === void 0 ? {} : { data });
+  }
+  info(message, data) {
+    return this.log("info", message, data === void 0 ? {} : { data });
+  }
+  warn(message, data) {
+    return this.log("warn", message, data === void 0 ? {} : { data });
+  }
+  /** Logs any thrown value; ShardErrors keep their code, path, and hint. */
+  error(error) {
+    const extra = this.annotate?.(error) ?? {};
+    const own = error?.source;
+    if (typeof own === "string" && !extra.source) extra.source = own;
+    if (error instanceof ShardError) {
+      return this.log("error", error.message, {
+        code: error.code,
+        path: error.path,
+        hint: error.hint,
+        ...extra
+      });
+    }
+    return this.log("error", error instanceof Error ? error.message : String(error), extra);
+  }
+  /** The last `count` entries at or above `level`, oldest first. */
+  tail(count = 50, level = "debug") {
+    const min = LEVELS[level];
+    return this.entries.filter((e) => LEVELS[e.level] >= min).slice(-count);
+  }
+  errors(count = 20) {
+    return this.tail(count, "error");
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}
+const LogResource = defineResource("core/Log", {
+  description: "Structured log ring buffer: system, GPU, and shader errors land here."
+});
+export {
+  Log,
+  LogResource
+};

package/dist/plugin.d.ts

@@ -0,0 +1,18 @@
+import type { App } from './app.js';
+export interface Plugin {
+    /** Unique name, used for dependencies (`physics3d`, `core/time`). */
+    readonly name: string;
+    readonly dependencies?: readonly string[];
+    /**
+     * The modules (`import * as components from './components'`) or values whose definitions and
+     * registrations this plugin needs at runtime. Referencing them keeps them in a tree-shaken bundle
+     * (every package is `sideEffects: false`), so a scene that names a component finds it whenever the
+     * plugin that provides it is installed.
+     */
+    readonly provides?: readonly object[];
+    /** Registers resources, systems, and other plugins. Runs in dependency order. */
+    build(app: App): void;
+    /** Optional async setup (e.g. loading WASM), awaited before Startup. */
+    ready?(app: App): Promise<void> | void;
+}
+export declare function definePlugin(plugin: Plugin): Plugin;

package/dist/plugin.js

@@ -0,0 +1,6 @@
+function definePlugin(plugin) {
+  return plugin;
+}
+export {
+  definePlugin
+};

package/dist/runners.d.ts

@@ -0,0 +1,23 @@
+import type { App } from './app.js';
+/** Drives an initialized app. The app doesn't know which runner it has. */
+export type Runner = (app: App) => void | Promise<void>;
+export interface HeadlessOptions {
+    frames: number;
+    /** Seconds per frame. Default 1/60. A fixed delta makes runs reproducible. */
+    delta?: number;
+}
+/** Runs N frames as fast as possible with a fixed delta. For the CLI and tests. */
+export declare function headlessRunner(options: HeadlessOptions): Runner;
+export interface AnimationFrameOptions {
+    /** Longest delta passed to update, in seconds, e.g. after the tab was hidden. Default 0.25. */
+    maxDelta?: number;
+    /** Stops the loop when aborted. */
+    signal?: AbortSignal;
+    /**
+     * Time a few idle frames before the first update to measure the display's refresh rate into
+     * DisplayRate (about 12 refreshes: 0.1 s at 120 Hz). Default true.
+     */
+    measureRefresh?: boolean;
+}
+/** Runs a frame per `requestAnimationFrame`. For the browser and Studio. */
+export declare function animationFrameRunner(options?: AnimationFrameOptions): Runner;

package/dist/runners.js

@@ -0,0 +1,87 @@
+import { AppControlResource } from "./control.js";
+import { RefreshMeter, rateFromIntervals } from "./display.js";
+import { LogResource } from "./log.js";
+import { DisplayRate } from "./time.js";
+function headlessRunner(options) {
+  const delta = options.delta ?? 1 / 60;
+  return (app) => {
+    for (let i = 0; i < options.frames; i++) app.update(delta);
+  };
+}
+const PROBE_INTERVALS = 12;
+function probeRefresh() {
+  return new Promise((resolve) => {
+    if (document.hidden) return resolve(0);
+    const intervals = new Float64Array(PROBE_INTERVALS);
+    let last = -1;
+    let n = 0;
+    const tick = (t) => {
+      if (document.hidden) return resolve(0);
+      if (last >= 0) intervals[n++] = t - last;
+      last = t;
+      if (n < PROBE_INTERVALS) requestAnimationFrame(tick);
+      else resolve(rateFromIntervals(intervals));
+    };
+    requestAnimationFrame(tick);
+  });
+}
+function animationFrameRunner(options = {}) {
+  const maxDelta = options.maxDelta ?? 0.25;
+  return async (app) => {
+    const display = app.world.tryResource(DisplayRate);
+    if (display && options.measureRefresh !== false) {
+      const hz = await probeRefresh();
+      if (hz > 0) {
+        display.hz = hz;
+        display.periodMs = 1e3 / hz;
+        display.source = "measured";
+      }
+    }
+    const meter = new RefreshMeter(display?.periodMs ?? 1e3 / 60);
+    return new Promise((resolve) => {
+      let last;
+      let handle = 0;
+      const onVisibility = () => {
+        if (document.hidden) last = void 0;
+      };
+      const frame = (timestamp) => {
+        const delta = last === void 0 ? 0 : Math.min((timestamp - last) / 1e3, maxDelta);
+        if (display && last !== void 0) {
+          const hz = meter.sample(timestamp - last);
+          if (hz > 0) {
+            display.hz = hz;
+            display.periodMs = 1e3 / hz;
+            display.source = "measured";
+          }
+        }
+        last = timestamp;
+        const control = app.world.resource(AppControlResource);
+        try {
+          if (!control.paused) app.update(delta);
+          else if (control.pendingSteps > 0) {
+            app.update(1 / app.fixedHz);
+            control.stepped();
+          }
+        } catch (err) {
+          app.world.resource(LogResource).error(err);
+          control.paused = true;
+          control.pausedByError = true;
+          control.abort(err);
+          console.error(err);
+        }
+        handle = requestAnimationFrame(frame);
+      };
+      document.addEventListener("visibilitychange", onVisibility);
+      options.signal?.addEventListener("abort", () => {
+        cancelAnimationFrame(handle);
+        document.removeEventListener("visibilitychange", onVisibility);
+        resolve();
+      });
+      handle = requestAnimationFrame(frame);
+    });
+  };
+}
+export {
+  animationFrameRunner,
+  headlessRunner
+};

package/dist/state.d.ts

@@ -0,0 +1,20 @@
+import { type Condition, type ResourceDef, type ScheduleLabel, type World } from '@aethervtt/shard-core';
+export interface StateValue<T extends string> {
+    current: T;
+    /** Requested transition, applied at the start of the next frame. */
+    next: T | undefined;
+}
+export interface StateDef<T extends string> {
+    readonly kind: 'state';
+    readonly name: string;
+    readonly values: readonly T[];
+    readonly resource: ResourceDef<StateValue<T>>;
+    readonly enter: ReadonlyMap<T, ScheduleLabel>;
+    readonly exit: ReadonlyMap<T, ScheduleLabel>;
+}
+export declare function defineState<const T extends string>(name: string, values: readonly T[]): StateDef<T>;
+export declare function OnEnter<T extends string>(state: StateDef<T>, value: NoInfer<T>): ScheduleLabel;
+export declare function OnExit<T extends string>(state: StateDef<T>, value: NoInfer<T>): ScheduleLabel;
+export declare function inState<T extends string>(state: StateDef<T>, value: NoInfer<T>): Condition;
+/** Requests a transition. It applies at the start of the next frame (OnExit, then OnEnter). */
+export declare function setState<T extends string>(world: World, state: StateDef<T>, value: NoInfer<T>): void;

package/dist/state.js

@@ -0,0 +1,47 @@
+import {
+  condition,
+  defineResource,
+  defineSchedule,
+  ShardError
+} from "@aethervtt/shard-core";
+function defineState(name, values) {
+  if (values.length === 0) {
+    throw new ShardError("app/invalid-state", `State "${name}" needs at least one value`);
+  }
+  return {
+    kind: "state",
+    name,
+    values,
+    resource: defineResource(name, { description: `Current ${name} state` }),
+    enter: new Map(values.map((v) => [v, defineSchedule(`${name}:enter:${v}`)])),
+    exit: new Map(values.map((v) => [v, defineSchedule(`${name}:exit:${v}`)]))
+  };
+}
+function OnEnter(state, value) {
+  return state.enter.get(value) ?? invalid(state, value);
+}
+function OnExit(state, value) {
+  return state.exit.get(value) ?? invalid(state, value);
+}
+function inState(state, value) {
+  if (!state.values.includes(value)) invalid(state, value);
+  return condition(`inState(${state.name}=${value})`, (world) => {
+    return world.tryResource(state.resource)?.current === value;
+  });
+}
+function setState(world, state, value) {
+  if (!state.values.includes(value)) invalid(state, value);
+  world.resource(state.resource).next = value;
+}
+function invalid(state, value) {
+  throw new ShardError("app/invalid-state", `"${value}" is not a value of state "${state.name}"`, {
+    hint: `Use one of: ${state.values.join(", ")}.`
+  });
+}
+export {
+  OnEnter,
+  OnExit,
+  defineState,
+  inState,
+  setState
+};

package/dist/time.d.ts

@@ -0,0 +1,34 @@
+import { type Rng } from '@aethervtt/shard-core';
+export interface TimeData {
+    /** Seconds since the previous frame. */
+    delta: number;
+    /** Seconds since the app started. */
+    elapsed: number;
+    /** Frames completed, starting at 0 during the first frame. */
+    frame: number;
+}
+export interface FixedTimeData {
+    /** The fixed step in seconds (1 / hz). */
+    readonly step: number;
+    /** Simulated seconds advanced by FixedUpdate. */
+    elapsed: number;
+    /** Leftover accumulated time as a fraction of a step, for interpolating rendering. */
+    alpha: number;
+    /** FixedUpdate runs in the current frame. */
+    steps: number;
+}
+export declare const Time: import("@aethervtt/shard-core").ResourceDef<TimeData>;
+export declare const FixedTime: import("@aethervtt/shard-core").ResourceDef<FixedTimeData>;
+export interface DisplayRateData {
+    /** Refresh rate of the display the app runs on, in Hz. */
+    hz: number;
+    /** One refresh, in ms. */
+    periodMs: number;
+    /**
+     * measured: the frame runner timed it (at startup, raised later if frames come faster).
+     * assumed: 60 Hz, for headless runs and before a measurement.
+     */
+    source: 'measured' | 'assumed';
+}
+export declare const DisplayRate: import("@aethervtt/shard-core").ResourceDef<DisplayRateData>;
+export declare const GlobalRng: import("@aethervtt/shard-core").ResourceDef<Rng>;

package/dist/time.js

@@ -0,0 +1,19 @@
+import { defineResource } from "@aethervtt/shard-core";
+const Time = defineResource("core/Time", {
+  description: "Frame time. Read delta in Update systems."
+});
+const FixedTime = defineResource("core/FixedTime", {
+  description: "Fixed-step time. Read step in FixedUpdate systems; alpha for interpolation."
+});
+const DisplayRate = defineResource("core/DisplayRate", {
+  description: "The display's refresh rate, measured by the frame runner (60 Hz assumed headless). Frame budgets that should match the screen read periodMs."
+});
+const GlobalRng = defineResource("core/GlobalRng", {
+  description: "The app root random stream, seeded from AppOptions.seed. Fork it per system."
+});
+export {
+  DisplayRate,
+  FixedTime,
+  GlobalRng,
+  Time
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aethervtt/shard-runtime",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-core": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/runtime"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}