@aethervtt/shard-platform 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-platform
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import type { ShardError } from '@aethervtt/shard-core';
+import type { Workers } from './workers.js';
+/**
+ * Everything the engine needs from its host. The engine only talks to this interface;
+ * hosts (browser, Tauri, headless) provide an implementation at startup.
+ */
+export interface Platform {
+    readonly name: string;
+    readonly fs: PlatformFileSystem;
+    readonly storage: KeyValueStorage;
+    readonly clock: Clock;
+    readonly log: Logger;
+    /** Where sound goes: Web Audio in a browser or webview. Absent when headless (the audio plugin records voices instead). */
+    readonly audio?: AudioBackend;
+    /**
+     * Background threads: web workers in a browser or webview, `worker_threads` in Node. Made on
+     * first use. Absent on hosts without threads; `workersOf` falls back to running jobs inline.
+     */
+    readonly workers?: Workers;
+}
+export * from './workers.js';
+export type MouseButton = 'left' | 'middle' | 'right' | 'back' | 'forward';
+/**
+ * Raw input as the platform sees it. The input plugin drains these once per frame. `action` events
+ * are synthetic (injected by tests or agents) and go through the same stream so they're recorded
+ * and replayed like everything else.
+ */
+export type RawInputEvent = {
+    type: 'key';
+    code: string;
+    pressed: boolean;
+} | {
+    type: 'mouse-button';
+    button: MouseButton;
+    pressed: boolean;
+} | {
+    type: 'mouse-move';
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+} | {
+    type: 'wheel';
+    dx: number;
+    dy: number;
+} | {
+    type: 'touch';
+    id: number;
+    phase: 'start' | 'move' | 'end';
+    x: number;
+    y: number;
+} | {
+    type: 'gamepad';
+    index: number;
+    connected: boolean;
+    buttons: number[];
+    axes: number[];
+} | {
+    type: 'focus';
+    focused: boolean;
+} | {
+    type: 'action';
+    name: string;
+    pressed: boolean;
+    value?: number;
+}
+/** Typed characters, key repeats included; "\b" is a backspace. Text fields read these. */
+ | {
+    type: 'text';
+    text: string;
+};
+/** Where raw input comes from: DOM listeners in a browser or webview, nothing when headless. */
+export interface InputSource {
+    /** Appends events since the last drain (and polls devices like gamepads). */
+    drain(out: RawInputEvent[]): void;
+    dispose(): void;
+}
+export type FileChangeKind = 'create' | 'modify' | 'remove';
+export interface FileChangeEvent {
+    readonly kind: FileChangeKind;
+    readonly path: string;
+}
+export interface PlatformFileSystem {
+    /** False on hosts that can only read (for example a static web build). */
+    readonly writable: boolean;
+    readText(path: string): Promise<string>;
+    readBytes(path: string): Promise<Uint8Array>;
+    writeText(path: string, data: string): Promise<void>;
+    writeBytes(path: string, data: Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    /** Present only on hosts that can watch files. Returns an unsubscribe function. */
+    watch?(path: string, onChange: (event: FileChangeEvent) => void): Promise<() => void>;
+    /** Entries directly inside a directory; empty if it doesn't exist. Absent on hosts that can't list. */
+    list?(dir: string): Promise<DirEntry[]>;
+    /** Size and modification time, or undefined if the file doesn't exist. */
+    stat?(path: string): Promise<FileStat | undefined>;
+    /** Moves a file, creating the target's directory. Writable hosts only. */
+    move?(from: string, to: string): Promise<void>;
+    /** Deletes a file if it exists. Writable hosts only. */
+    remove?(path: string): Promise<void>;
+}
+export interface DirEntry {
+    /** Name within the directory (not a path). */
+    readonly name: string;
+    readonly kind: 'file' | 'dir';
+}
+export interface FileStat {
+    readonly size: number;
+    /** Modification time in milliseconds. */
+    readonly mtime: number;
+}
+/**
+ * The player's own data: saved games and settings, kept per user rather than in the project.
+ * Keys are paths (`saves/slot1.json`, `settings.json`). Node and Tauri write files under a user
+ * data folder, browsers use IndexedDB, and headless tests use `createMemoryStorage`.
+ */
+export interface KeyValueStorage {
+    /** The stored bytes, or undefined if nothing is stored under the key. */
+    read(key: string): Promise<Uint8Array | undefined>;
+    write(key: string, data: Uint8Array): Promise<void>;
+    /** Keys that start with `prefix`, sorted. */
+    list(prefix: string): Promise<string[]>;
+    /** Removes the key if it exists. */
+    delete(key: string): Promise<void>;
+}
+/** Storage that lives as long as the process: headless runs and tests. Writes are copied. */
+export declare function createMemoryStorage(): KeyValueStorage;
+export interface Clock {
+    /** Monotonic time in milliseconds. */
+    now(): number;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+}
+/** Encoded sound the backend decodes (or streams) itself. An imported `AudioClip` is one. */
+export interface AudioClipSource {
+    /** Asset guid, for logs. */
+    readonly id: string;
+    /** The file as imported (WAV, Ogg, MP3, FLAC). A new array means new contents. */
+    readonly bytes: Uint8Array;
+    /** `wav`, `vorbis`, `opus`, `mp3`, or `flac`. */
+    readonly codec: string;
+    /** Seconds. */
+    readonly duration: number;
+    /** Play through a media element instead of decoding it all up front (music). */
+    readonly stream: boolean;
+    /** Scale decoded samples so the peak is 1. */
+    readonly normalize: boolean;
+    /** Loop region in seconds; `loopEnd` 0 means the end of the clip. */
+    readonly loopStart: number;
+    readonly loopEnd: number;
+}
+export type AudioPanningModel = 'hrtf' | 'equal-power';
+export type AudioDistanceModel = 'inverse' | 'linear' | 'exponential';
+/** How a spatial voice pans and fades with distance: the parameters of a Web Audio PannerNode. */
+export interface AudioSpatialDesc {
+    readonly panning: AudioPanningModel;
+    readonly distanceModel: AudioDistanceModel;
+    readonly refDistance: number;
+    readonly maxDistance: number;
+    readonly rolloffFactor: number;
+}
+/** What changes while a voice plays. */
+export interface AudioVoiceParams {
+    /** Linear gain before the bus and distance: volume × occlusion. */
+    gain: number;
+    /** Playback rate (pitch × Doppler). */
+    pitch: number;
+    /** World position of a spatial voice (ignored for non-spatial ones). */
+    x: number;
+    y: number;
+    z: number;
+}
+export interface AudioVoiceDesc extends AudioVoiceParams {
+    readonly clip: AudioClipSource;
+    /** Bus name; the backend mixes it at the gain last given to `setBus`. */
+    readonly bus: string;
+    readonly loop: boolean;
+    /** Where playback starts, in seconds of clip time. */
+    readonly offset: number;
+    /** Null for non-spatial voices (UI, music). */
+    readonly spatial: AudioSpatialDesc | null;
+}
+export type AudioContextState = 'running' | 'suspended' | 'closed' | 'headless';
+/**
+ * Plays voices the audio plugin decides on. The plugin owns timing, voice limits, and virtual
+ * voices; a backend only makes the sound (or, headless, records it).
+ */
+export interface AudioBackend {
+    /** `web`, `headless`, ... */
+    readonly kind: string;
+    /** Browsers keep the context suspended until a user gesture; voices wait until then. */
+    readonly state: AudioContextState;
+    /** Returns an id for `update` and `stop`. */
+    play(voice: AudioVoiceDesc): number;
+    update(voice: number, params: AudioVoiceParams): void;
+    /** Stops a voice, fading out over `fade` seconds (default: at once). */
+    stop(voice: number, fade?: number): void;
+    /** The listener's world matrix (affine 3x4, row by row, as in core/GlobalTransform). */
+    setListener(matrix: ArrayLike<number>): void;
+    /** A bus's final gain: its volume, mute, ducking, and parents multiplied. */
+    setBus(name: string, gain: number): void;
+    /** Called with decode failures and other problems the plugin should log. */
+    onError?: (error: ShardError) => void;
+    dispose?(): void;
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+export * from "./workers.js";
+function createMemoryStorage() {
+  const data = /* @__PURE__ */ new Map();
+  return {
+    read: async (key) => {
+      const bytes = data.get(key);
+      return bytes?.slice();
+    },
+    write: async (key, bytes) => void data.set(key, bytes.slice()),
+    list: async (prefix) => [...data.keys()].filter((k) => k.startsWith(prefix)).sort(),
+    delete: async (key) => void data.delete(key)
+  };
+}
+export {
+  createMemoryStorage
+};

package/dist/workers.d.ts

@@ -0,0 +1,60 @@
+import type { Platform } from './index.js';
+export interface WorkerRunOptions {
+    /** Buffers that move to the worker instead of being copied. The caller can't use them after. */
+    readonly transfer?: readonly ArrayBuffer[];
+    /** `high` jobs start before every queued `normal` one. Default `normal`. */
+    readonly priority?: 'high' | 'normal';
+}
+/**
+ * A pool of background threads that run functions exported by ES modules. Results never depend on
+ * which worker ran a job; when order matters, callers apply results in the order they asked.
+ */
+export interface Workers {
+    /** Worker threads. 0 means jobs run inline on the calling thread. */
+    readonly size: number;
+    /**
+     * Runs `fn` from the module at `module` (a URL, such as
+     * `new URL('./worker.js', import.meta.url).href`) with `args`, and resolves with its result.
+     * Worker modules are plain JavaScript: they load in a worker without a bundler. Typed arrays
+     * in the result (the result itself or its own properties) move back instead of being copied.
+     * Rejects with `platform/worker-crashed` if the worker dies (the pool replaces it), or with the
+     * error the function threw.
+     */
+    run<T>(module: string, fn: string, args: readonly unknown[], options?: WorkerRunOptions): Promise<T>;
+    /** Stops every worker. Jobs still running or queued reject. */
+    dispose(): void;
+}
+/** What a host gives the pool for one worker thread. */
+export interface WorkerThread {
+    post(message: unknown, transfer: readonly ArrayBuffer[]): void;
+    /** Lets the host exit while this worker is idle (Node); optional. */
+    idle?(idle: boolean): void;
+    terminate(): void;
+}
+export interface WorkerThreadEvents {
+    message(message: unknown): void;
+    /** The worker died: an uncaught error, or it exited. */
+    exit(reason: string): void;
+}
+export interface WorkerPoolOptions {
+    size: number;
+    /** Starts one worker running `workerHostSource`. */
+    spawn(events: WorkerThreadEvents): WorkerThread;
+}
+/** The shared queue: a worker per slot, one job per worker at a time, FIFO with a priority lane. */
+export declare function createWorkerPool(options: WorkerPoolOptions): Workers;
+/**
+ * A pool of size 0: jobs run inline on the calling thread, each after an `await`. Hosts without
+ * threads and tests that turn workers off use it, and everything that uses a pool works the same.
+ */
+export declare function createInlineWorkers(): Workers;
+/** The platform's pool, or a shared inline one on hosts without threads. */
+export declare function workersOf(platform: Pick<Platform, 'workers'> | undefined): Workers;
+/** How many workers a host with `cores` logical cores gets: one per core but one, 1 to 8. */
+export declare function defaultWorkerCount(cores: number): number;
+/**
+ * The script every worker runs. It imports job modules on first use (cached), calls the export,
+ * and posts the result back, moving typed arrays in it. `node` reads `worker_threads`; `web`
+ * uses the worker global.
+ */
+export declare function workerHostSource(host: 'node' | 'web'): string;

package/dist/workers.js

@@ -0,0 +1,183 @@
+import { ShardError } from "@aethervtt/shard-core";
+function createWorkerPool(options) {
+  const slots = [];
+  const high = [];
+  const normal = [];
+  let nextId = 1;
+  let disposed = false;
+  const start = (slot) => {
+    const events = {
+      message: (message) => {
+        const reply = message;
+        const job = slot.job;
+        if (!job || job.id !== reply.id) return;
+        slot.job = void 0;
+        if (reply.ok) job.resolve(reply.result);
+        else job.reject(toError(reply.error));
+        pump();
+      },
+      exit: (reason) => {
+        if (slot.thread !== thread) return;
+        slot.thread = void 0;
+        const job = slot.job;
+        slot.job = void 0;
+        job?.reject(
+          new ShardError(
+            "platform/worker-crashed",
+            `A worker died running "${job.fn}": ${reason}`,
+            {
+              hint: "The pool started a replacement; the job can be retried.",
+              path: job.module
+            }
+          )
+        );
+        if (!disposed) pump();
+      }
+    };
+    const thread = options.spawn(events);
+    slot.thread = thread;
+    return thread;
+  };
+  const pump = () => {
+    for (const slot of slots) {
+      if (slot.job) continue;
+      const job = high.shift() ?? normal.shift();
+      if (!job) {
+        slot.thread?.idle?.(true);
+        continue;
+      }
+      const thread = slot.thread ?? start(slot);
+      slot.job = job;
+      thread.idle?.(false);
+      const { id, module, fn, args } = job;
+      try {
+        thread.post({ id, module, fn, args }, job.transfer);
+      } catch (err) {
+        slot.job = void 0;
+        job.reject(err);
+      }
+    }
+  };
+  for (let i = 0; i < options.size; i++) slots.push({ thread: void 0, job: void 0 });
+  return {
+    size: options.size,
+    run: (module, fn, args, opts = {}) => new Promise((resolve, reject) => {
+      if (disposed) {
+        reject(new ShardError("platform/workers-disposed", "The worker pool was disposed"));
+        return;
+      }
+      const job = {
+        id: nextId++,
+        module,
+        fn,
+        args,
+        transfer: opts.transfer ?? [],
+        resolve,
+        reject
+      };
+      (opts.priority === "high" ? high : normal).push(job);
+      pump();
+    }),
+    dispose: () => {
+      disposed = true;
+      const stopped = new ShardError("platform/workers-disposed", "The worker pool was disposed");
+      for (const job of [...high.splice(0), ...normal.splice(0)]) job.reject(stopped);
+      for (const slot of slots) {
+        slot.job?.reject(stopped);
+        slot.job = void 0;
+        slot.thread?.terminate();
+        slot.thread = void 0;
+      }
+    }
+  };
+}
+function toError(e) {
+  return new ShardError(e.code ?? "platform/worker-job-failed", e.message, {
+    hint: e.hint,
+    path: e.path
+  });
+}
+function createInlineWorkers() {
+  const modules = /* @__PURE__ */ new Map();
+  let disposed = false;
+  return {
+    size: 0,
+    run: async (module, fn, args) => {
+      if (disposed)
+        throw new ShardError("platform/workers-disposed", "The worker pool was disposed");
+      let mod = modules.get(module);
+      if (!mod) {
+        mod = import(
+          /* @vite-ignore */
+          module
+        );
+        modules.set(module, mod);
+      }
+      const f = (await mod)[fn];
+      if (typeof f !== "function") {
+        throw new ShardError("platform/worker-no-export", `"${module}" has no export "${fn}"`, {
+          hint: "Worker functions are named exports of the module passed to run()."
+        });
+      }
+      return await f(...args);
+    },
+    dispose: () => {
+      disposed = true;
+    }
+  };
+}
+let inline;
+function workersOf(platform) {
+  if (platform?.workers) return platform.workers;
+  inline ??= createInlineWorkers();
+  return inline;
+}
+function defaultWorkerCount(cores) {
+  return Math.max(1, Math.min(8, Math.floor(cores) - 1));
+}
+function workerHostSource(host) {
+  const body = `
+const modules = new Map()
+const load = (url) => {
+  let m = modules.get(url)
+  if (!m) { m = import(url); modules.set(url, m) }
+  return m
+}
+const transfers = (value) => {
+  const out = []
+  const add = (x) => {
+    if (ArrayBuffer.isView(x) && x.buffer instanceof ArrayBuffer && !out.includes(x.buffer)) out.push(x.buffer)
+  }
+  add(value)
+  if (value && typeof value === 'object' && !ArrayBuffer.isView(value)) for (const k of Object.keys(value)) add(value[k])
+  return out
+}
+const handle = async (msg, post) => {
+  const { id, module, fn, args } = msg
+  try {
+    const mod = await load(module)
+    const f = mod[fn]
+    if (typeof f !== 'function') {
+      throw Object.assign(new Error('"' + module + '" has no export "' + fn + '"'), { code: 'platform/worker-no-export' })
+    }
+    const result = await f(...args)
+    post({ id, ok: true, result }, transfers(result))
+  } catch (e) {
+    post({ id, ok: false, error: { code: e && e.code, message: String((e && e.message) || e), hint: e && e.hint, path: e && e.path } }, [])
+  }
+}
+`;
+  return host === "node" ? `${body}
+const { parentPort } = require('node:worker_threads')
+parentPort.on('message', (m) => handle(m, (r, t) => parentPort.postMessage(r, t)))
+` : `${body}
+self.onmessage = (e) => handle(e.data, (r, t) => self.postMessage(r, t))
+`;
+}
+export {
+  createInlineWorkers,
+  createWorkerPool,
+  defaultWorkerCount,
+  workerHostSource,
+  workersOf
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aethervtt/shard-platform",
+  "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/platform"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}