@aethervtt/shard-mirror 0.0.0-stage → 0.2.0

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

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-mirror
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 @@
+export { createMirror, Mirror, type MirrorCounts, type MirrorOptions } from './mirror.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+import { createMirror, Mirror } from "./mirror.js";
+export {
+  Mirror,
+  createMirror
+};

package/dist/mirror.d.ts

@@ -0,0 +1,71 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+export interface MirrorOptions<D, K = string> {
+    /** The host's id for a document. Stable across revisions. */
+    key(doc: D): K;
+    /**
+     * The document's revision: a number that changes whenever the document does. An unchanged
+     * revision skips the document for one map lookup and one compare.
+     */
+    rev?(doc: D): number;
+    /** Without `rev`: whether a document changed since `prev` was applied. Never stringify here. */
+    equal?(prev: D, next: D): boolean;
+    /** Makes the entity (or the root of the entities) for a new document. `apply` runs next. */
+    spawn(doc: D, world: World): Entity;
+    /** Writes a new or changed document onto its entity. Write only the fields that moved. */
+    apply(entity: Entity, doc: D, world: World): void;
+    /**
+     * Takes a document's entity away (`key` is the document's). Default: `world.despawn` (the entity
+     * and its descendants).
+     */
+    despawn?(entity: Entity, world: World, key: K): void;
+}
+/** What one `sync`, `upsert` or `remove` did, for tests and `describe`. */
+export interface MirrorCounts {
+    spawned: number;
+    applied: number;
+    removed: number;
+}
+/**
+ * Keyed sync from a host's documents to entities (0055). `sync` walks the host's full list once:
+ * a document whose revision is unchanged costs one map lookup and one number compare, and nothing
+ * allocates when nothing changed. A host that knows what changed calls `upsert` and `remove`.
+ */
+export declare class Mirror<D, K = string> {
+    /** What the last call did. */
+    readonly last: MirrorCounts;
+    private readonly world;
+    private readonly options;
+    private readonly rows;
+    private readonly keys;
+    private pass;
+    /** Bound once, so the removal sweep allocates no closure. */
+    private readonly sweep;
+    constructor(world: World, options: MirrorOptions<D, K>);
+    /** Documents mirrored. */
+    get size(): number;
+    /**
+     * Applies the host's full list: spawns new documents, applies changed ones, and despawns the
+     * ones missing from `docs`.
+     */
+    sync(docs: readonly D[]): MirrorCounts;
+    /** Applies one document the host knows is new or changed (unchanged revisions are skipped). */
+    upsert(doc: D): Entity;
+    /** Despawns a document's entity. Returns whether it was mirrored. */
+    remove(key: K): boolean;
+    /** The entity mirroring a document. */
+    entity(key: K): Entity | undefined;
+    /**
+     * The host id for an entity or any of its descendants: a pick hit on a token's visual child
+     * resolves to the token's document.
+     */
+    keyOf(entity: Entity): K | undefined;
+    /** Every mirrored document's key, in the order they were first seen. */
+    keysInOrder(): K[];
+    /** Despawns every mirrored entity. */
+    clear(): void;
+    private create;
+    private update;
+    private drop;
+}
+/** A mirror of host documents onto `world` (0055). */
+export declare function createMirror<D, K = string>(world: World, options: MirrorOptions<D, K>): Mirror<D, K>;

package/dist/mirror.js

@@ -0,0 +1,146 @@
+import { ChildOf, ShardError } from "@aethervtt/shard-core";
+class Mirror {
+  /** What the last call did. */
+  last = { spawned: 0, applied: 0, removed: 0 };
+  world;
+  options;
+  rows = /* @__PURE__ */ new Map();
+  keys = /* @__PURE__ */ new Map();
+  pass = 0;
+  /** Bound once, so the removal sweep allocates no closure. */
+  sweep = (row, key) => {
+    if (row.mark !== this.pass) this.drop(key, row);
+  };
+  constructor(world, options) {
+    if (!options.rev && !options.equal) {
+      throw new ShardError(
+        "mirror/no-diff",
+        "A mirror needs `rev` or `equal` to tell what changed",
+        {
+          hint: "Pass rev: (doc) => doc.rev when documents carry a revision (cheapest), or equal(prev, next)."
+        }
+      );
+    }
+    this.world = world;
+    this.options = options;
+  }
+  /** Documents mirrored. */
+  get size() {
+    return this.rows.size;
+  }
+  /**
+   * Applies the host's full list: spawns new documents, applies changed ones, and despawns the
+   * ones missing from `docs`.
+   */
+  sync(docs) {
+    const last = this.last;
+    last.spawned = last.applied = last.removed = 0;
+    const pass = ++this.pass;
+    const { key, rev } = this.options;
+    let seen = 0;
+    for (let i = 0; i < docs.length; i++) {
+      const doc = docs[i];
+      const k = key(doc);
+      const row = this.rows.get(k);
+      if (row) {
+        if (row.mark === pass) duplicate(k);
+        row.mark = pass;
+        seen++;
+        if (rev ? row.rev !== rev(doc) : !this.options.equal(row.doc, doc)) this.update(row, doc);
+      } else {
+        this.create(k, doc).mark = pass;
+        seen++;
+      }
+    }
+    if (seen !== this.rows.size) this.rows.forEach(this.sweep);
+    return last;
+  }
+  /** Applies one document the host knows is new or changed (unchanged revisions are skipped). */
+  upsert(doc) {
+    const last = this.last;
+    last.spawned = last.applied = last.removed = 0;
+    const k = this.options.key(doc);
+    const row = this.rows.get(k);
+    if (!row) return this.create(k, doc).entity;
+    const rev = this.options.rev;
+    if (rev ? row.rev !== rev(doc) : !this.options.equal(row.doc, doc)) this.update(row, doc);
+    return row.entity;
+  }
+  /** Despawns a document's entity. Returns whether it was mirrored. */
+  remove(key) {
+    const last = this.last;
+    last.spawned = last.applied = last.removed = 0;
+    const row = this.rows.get(key);
+    if (!row) return false;
+    this.drop(key, row);
+    return true;
+  }
+  /** The entity mirroring a document. */
+  entity(key) {
+    return this.rows.get(key)?.entity;
+  }
+  /**
+   * The host id for an entity or any of its descendants: a pick hit on a token's visual child
+   * resolves to the token's document.
+   */
+  keyOf(entity) {
+    const world = this.world;
+    let e = entity;
+    while (e !== null && world.isAlive(e)) {
+      const k = this.keys.get(e);
+      if (k !== void 0) return k;
+      e = world.tryGet(e, ChildOf)?.parent ?? null;
+    }
+    return void 0;
+  }
+  /** Every mirrored document's key, in the order they were first seen. */
+  keysInOrder() {
+    return [...this.rows.keys()];
+  }
+  /** Despawns every mirrored entity. */
+  clear() {
+    const last = this.last;
+    last.spawned = last.applied = last.removed = 0;
+    this.pass++;
+    this.rows.forEach(this.sweep);
+  }
+  create(k, doc) {
+    const { spawn, apply, rev, equal } = this.options;
+    const entity = spawn(doc, this.world);
+    const row = { entity, rev: rev ? rev(doc) : 0, doc: equal ? doc : void 0, mark: 0 };
+    this.rows.set(k, row);
+    this.keys.set(entity, k);
+    apply(entity, doc, this.world);
+    this.last.spawned++;
+    return row;
+  }
+  update(row, doc) {
+    const { apply, rev, equal } = this.options;
+    if (rev) row.rev = rev(doc);
+    if (equal) row.doc = doc;
+    apply(row.entity, doc, this.world);
+    this.last.applied++;
+  }
+  drop(k, row) {
+    this.rows.delete(k);
+    this.keys.delete(row.entity);
+    const world = this.world;
+    if (world.isAlive(row.entity)) {
+      if (this.options.despawn) this.options.despawn(row.entity, world, k);
+      else world.despawn(row.entity);
+    }
+    this.last.removed++;
+  }
+}
+function duplicate(key) {
+  throw new ShardError("mirror/duplicate-key", `Two documents in one sync share the key ${key}`, {
+    hint: "Keys are the host ids of documents: each may appear once per list."
+  });
+}
+function createMirror(world, options) {
+  return new Mirror(world, options);
+}
+export {
+  Mirror,
+  createMirror
+};

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@aethervtt/shard-mirror",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "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.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/mirror"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
+  }
+}