@codexo/exojs-tilemap 0.15.2 → 0.16.0

package/dist/esm/WangSet.js

@@ -1,81 +1,73 @@
+//#region src/WangSet.ts
 /**
- * Describes a Wang autotile set: a mapping from a neighbor bitmask to a
- * local tile ID within a specific tileset.
- *
- * Blob bitmask bit layout (powers of 2):
- * - Bit 0 (1):   Top-left
- * - Bit 1 (2):   Top
- * - Bit 2 (4):   Top-right
- * - Bit 3 (8):   Left
- * - Bit 4 (16):  Right
- * - Bit 5 (32):  Bottom-left
- * - Bit 6 (64):  Bottom
- * - Bit 7 (128): Bottom-right
- *
- * Diagonal (corner) bits are only set when both adjacent cardinal directions
- * are also set — reducing 256 raw combinations to 47 meaningful blob states.
- *
- * Edge bitmask bit layout:
- * - Bit 0 (1): Top
- * - Bit 1 (2): Right
- * - Bit 2 (4): Bottom
- * - Bit 3 (8): Left
- */
-class WangSet {
-    /** Index of the tileset that contains the Wang tiles. */
-    tilesetIndex;
-    /** The Wang mode: `'blob'` (8-neighbor) or `'edge'` (4-neighbor). */
-    type;
-    _map;
-    _members;
-    constructor(options) {
-        this.tilesetIndex = options.tilesetIndex;
-        this.type = options.type ?? 'blob';
-        if (options.blobMap instanceof Map) {
-            this._map = options.blobMap;
-        }
-        else {
-            const map = new Map();
-            for (const [k, v] of Object.entries(options.blobMap)) {
-                map.set(Number(k), v);
-            }
-            this._map = map;
-        }
-        // Members default to every variant tile ID the set can produce, so that any
-        // autotiled variant is recognised as part of the group (variant-stable
-        // membership). Explicit `members` (e.g. the base paint ID) are added on top.
-        const members = new Set(this._map.values());
-        if (options.members) {
-            for (const id of options.members)
-                members.add(id);
-        }
-        this._members = members;
-    }
-    /**
-     * Look up the local tile ID for a given neighbor bitmask.
-     * Returns `undefined` if the mask has no mapping in this set.
-     */
-    getTileId(mask) {
-        return this._map.get(mask);
-    }
-    /**
-     * Whether a local tile ID belongs to this Wang group. True for every variant
-     * the set produces plus any explicit {@link WangSetOptions.members}. Used as
-     * the default, variant-stable neighbour-membership test by {@link autoTile}
-     * and `refreshCell`.
-     */
-    isMember(localTileId) {
-        return this._members.has(localTileId);
-    }
-    /** Read-only view of the full bitmask → tile-ID mapping. */
-    get blobMap() {
-        return this._map;
-    }
-    /** Read-only view of the local tile IDs that count as group members. */
-    get members() {
-        return this._members;
-    }
-}
+* Describes a Wang autotile set: a mapping from a neighbor bitmask to a
+* local tile ID within a specific tileset.
+*
+* Blob bitmask bit layout (powers of 2):
+* - Bit 0 (1):   Top-left
+* - Bit 1 (2):   Top
+* - Bit 2 (4):   Top-right
+* - Bit 3 (8):   Left
+* - Bit 4 (16):  Right
+* - Bit 5 (32):  Bottom-left
+* - Bit 6 (64):  Bottom
+* - Bit 7 (128): Bottom-right
+*
+* Diagonal (corner) bits are only set when both adjacent cardinal directions
+* are also set - reducing 256 raw combinations to 47 meaningful blob states.
+*
+* Edge bitmask bit layout:
+* - Bit 0 (1): Top
+* - Bit 1 (2): Right
+* - Bit 2 (4): Bottom
+* - Bit 3 (8): Left
+*/
+var WangSet = class {
+	/** Index of the tileset that contains the Wang tiles. */
+	tilesetIndex;
+	/** The Wang mode: `'blob'` (8-neighbor) or `'edge'` (4-neighbor). */
+	type;
+	_map;
+	_members;
+	constructor(options) {
+		this.tilesetIndex = options.tilesetIndex;
+		this.type = options.type ?? "blob";
+		if (options.blobMap instanceof Map) this._map = options.blobMap;
+		else {
+			const map = /* @__PURE__ */ new Map();
+			for (const [k, v] of Object.entries(options.blobMap)) map.set(Number(k), v);
+			this._map = map;
+		}
+		const members = new Set(this._map.values());
+		if (options.members) for (const id of options.members) members.add(id);
+		this._members = members;
+	}
+	/**
+	* Look up the local tile ID for a given neighbor bitmask.
+	* Returns `undefined` if the mask has no mapping in this set.
+	*/
+	getTileId(mask) {
+		return this._map.get(mask);
+	}
+	/**
+	* Whether a local tile ID belongs to this Wang group. True for every variant
+	* the set produces plus any explicit {@link WangSetOptions.members}. Used as
+	* the default, variant-stable neighbour-membership test by {@link autoTile}
+	* and `refreshCell`.
+	*/
+	isMember(localTileId) {
+		return this._members.has(localTileId);
+	}
+	/** Read-only view of the full bitmask → tile-ID mapping. */
+	get blobMap() {
+		return this._map;
+	}
+	/** Read-only view of the local tile IDs that count as group members. */
+	get members() {
+		return this._members;
+	}
+};
 
+//#endregion
 export { WangSet };
-//# sourceMappingURL=WangSet.js.map
+//# sourceMappingURL=WangSet.js.map

package/dist/esm/WangSet.js.map

@@ -1 +1 @@
-{"version":3,"file":"WangSet.js","sources":["../../../src/WangSet.ts"],"sourcesContent":[null],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;AAsBG;MACU,OAAO,CAAA;;AAEF,IAAA,YAAY;;AAGZ,IAAA,IAAI;AAEH,IAAA,IAAI;AACJ,IAAA,QAAQ;AAEzB,IAAA,WAAA,CAAmB,OAAuB,EAAA;AACxC,QAAA,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY;QACxC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM;AAElC,QAAA,IAAI,OAAO,CAAC,OAAO,YAAY,GAAG,EAAE;AAClC,YAAA,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,OAAO;QAC7B;aAAO;AACL,YAAA,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB;AACrC,YAAA,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAiC,CAAC,EAAE;gBAC9E,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvB;AACA,YAAA,IAAI,CAAC,IAAI,GAAG,GAAG;QACjB;;;;AAKA,QAAA,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;AACnD,QAAA,IAAI,OAAO,CAAC,OAAO,EAAE;AACnB,YAAA,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,OAAO;AAAE,gBAAA,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACnD;AACA,QAAA,IAAI,CAAC,QAAQ,GAAG,OAAO;IACzB;AAEA;;;AAGG;AACI,IAAA,SAAS,CAAC,IAAY,EAAA;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;IAC5B;AAEA;;;;;AAKG;AACI,IAAA,QAAQ,CAAC,WAAmB,EAAA;QACjC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC;IACvC;;AAGA,IAAA,IAAW,OAAO,GAAA;QAChB,OAAO,IAAI,CAAC,IAAI;IAClB;;AAGA,IAAA,IAAW,OAAO,GAAA;QAChB,OAAO,IAAI,CAAC,QAAQ;IACtB;AACD;;;;"}
+{"version":3,"file":"WangSet.js","names":[],"sources":["../../src/WangSet.ts"],"sourcesContent":["/**\n * Options for constructing a {@link WangSet}.\n */\nexport interface WangSetOptions {\n  /** Which TileSet contains the Wang tiles (index into the layer's tilesets array). */\n  tilesetIndex: number;\n  /**\n   * Map from Wang bitmask to local tile ID within the tileset.\n   *\n   * For blob mode (8-neighbor), keys are 0-255; the 47 valid combinations\n   * of the blob encoding must be covered at minimum.\n   * For edge mode (4-neighbor), keys are 0-15.\n   *\n   * Accepts either a {@link ReadonlyMap} or a plain `Record<number, number>`.\n   */\n  blobMap: ReadonlyMap<number, number> | Record<number, number>;\n  /** Whether this is a blob (8-neighbor, default) or edge (4-neighbor) Wang set. */\n  type?: 'blob' | 'edge';\n  /**\n   * Extra local tile IDs that count as belonging to this Wang group, beyond\n   * the variant IDs already present as {@link blobMap} *values*.\n   *\n   * Membership is what {@link autoTile} / `refreshCell` use to decide whether a\n   * neighbouring cell is \"part of the terrain\". Because every value in\n   * `blobMap` is itself a member, group membership stays stable no matter which\n   * variant a cell currently shows - that is what makes incremental\n   * `refreshCell` correct. Add the *base* tile ID you paint with here if it is\n   * not already one of the blobMap variants.\n   */\n  members?: Iterable<number>;\n}\n\n/**\n * Describes a Wang autotile set: a mapping from a neighbor bitmask to a\n * local tile ID within a specific tileset.\n *\n * Blob bitmask bit layout (powers of 2):\n * - Bit 0 (1):   Top-left\n * - Bit 1 (2):   Top\n * - Bit 2 (4):   Top-right\n * - Bit 3 (8):   Left\n * - Bit 4 (16):  Right\n * - Bit 5 (32):  Bottom-left\n * - Bit 6 (64):  Bottom\n * - Bit 7 (128): Bottom-right\n *\n * Diagonal (corner) bits are only set when both adjacent cardinal directions\n * are also set - reducing 256 raw combinations to 47 meaningful blob states.\n *\n * Edge bitmask bit layout:\n * - Bit 0 (1): Top\n * - Bit 1 (2): Right\n * - Bit 2 (4): Bottom\n * - Bit 3 (8): Left\n */\nexport class WangSet {\n  /** Index of the tileset that contains the Wang tiles. */\n  public readonly tilesetIndex: number;\n\n  /** The Wang mode: `'blob'` (8-neighbor) or `'edge'` (4-neighbor). */\n  public readonly type: 'blob' | 'edge';\n\n  private readonly _map: ReadonlyMap<number, number>;\n  private readonly _members: ReadonlySet<number>;\n\n  public constructor(options: WangSetOptions) {\n    this.tilesetIndex = options.tilesetIndex;\n    this.type = options.type ?? 'blob';\n\n    if (options.blobMap instanceof Map) {\n      this._map = options.blobMap;\n    } else {\n      const map = new Map<number, number>();\n      for (const [k, v] of Object.entries(options.blobMap as Record<string, number>)) {\n        map.set(Number(k), v);\n      }\n      this._map = map;\n    }\n\n    // Members default to every variant tile ID the set can produce, so that any\n    // autotiled variant is recognised as part of the group (variant-stable\n    // membership). Explicit `members` (e.g. the base paint ID) are added on top.\n    const members = new Set<number>(this._map.values());\n    if (options.members) {\n      for (const id of options.members) members.add(id);\n    }\n    this._members = members;\n  }\n\n  /**\n   * Look up the local tile ID for a given neighbor bitmask.\n   * Returns `undefined` if the mask has no mapping in this set.\n   */\n  public getTileId(mask: number): number | undefined {\n    return this._map.get(mask);\n  }\n\n  /**\n   * Whether a local tile ID belongs to this Wang group. True for every variant\n   * the set produces plus any explicit {@link WangSetOptions.members}. Used as\n   * the default, variant-stable neighbour-membership test by {@link autoTile}\n   * and `refreshCell`.\n   */\n  public isMember(localTileId: number): boolean {\n    return this._members.has(localTileId);\n  }\n\n  /** Read-only view of the full bitmask → tile-ID mapping. */\n  public get blobMap(): ReadonlyMap<number, number> {\n    return this._map;\n  }\n\n  /** Read-only view of the local tile IDs that count as group members. */\n  public get members(): ReadonlySet<number> {\n    return this._members;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAuDA,IAAa,UAAb,MAAqB;;CAEnB,AAAgB;;CAGhB,AAAgB;CAEhB,AAAiB;CACjB,AAAiB;CAEjB,AAAO,YAAY,SAAyB;EAC1C,KAAK,eAAe,QAAQ;EAC5B,KAAK,OAAO,QAAQ,QAAQ;EAE5B,IAAI,QAAQ,mBAAmB,KAC7B,KAAK,OAAO,QAAQ;OACf;GACL,MAAM,sBAAM,IAAI,IAAoB;GACpC,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,QAAQ,OAAiC,GAC3E,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC;GAEtB,KAAK,OAAO;EACd;EAKA,MAAM,UAAU,IAAI,IAAY,KAAK,KAAK,OAAO,CAAC;EAClD,IAAI,QAAQ,SACV,KAAK,MAAM,MAAM,QAAQ,SAAS,QAAQ,IAAI,EAAE;EAElD,KAAK,WAAW;CAClB;;;;;CAMA,AAAO,UAAU,MAAkC;EACjD,OAAO,KAAK,KAAK,IAAI,IAAI;CAC3B;;;;;;;CAQA,AAAO,SAAS,aAA8B;EAC5C,OAAO,KAAK,SAAS,IAAI,WAAW;CACtC;;CAGA,IAAW,UAAuC;EAChD,OAAO,KAAK;CACd;;CAGA,IAAW,UAA+B;EACxC,OAAO,KAAK;CACd;AACF"}

package/dist/esm/WorkerSampledChunkSource.d.ts

@@ -0,0 +1,95 @@
+import type { ChunkSource } from './ChunkSource';
+import type { TileLayer } from './TileLayer';
+import type { ResolvedTile } from './types';
+/**
+ * Options for {@link createWorkerSampledChunkSource}.
+ * @advanced
+ */
+export interface WorkerSampledChunkSourceOptions {
+    /**
+     * Complete worker script source as a single self-contained string, Blob-URL'd
+     * into a real `Worker` at construction time - the same technique
+     * {@link import('@codexo/exojs').WorkletEffect} uses for AudioWorklet
+     * processors. No separate worker asset is fetched and no bundler-specific
+     * worker-import syntax is involved.
+     *
+     * Producing that string by hand-writing JavaScript into a template literal
+     * works but gives up type checking, linting and shared code. Prefer a build
+     * step that bundles a real module into a string: this repository's own
+     * examples are authored as `*.worker.ts` and imported through a `?worker`
+     * query, which is why they can `import` the sampling functions the main
+     * thread uses instead of restating them.
+     *
+     * Must implement this request/response protocol:
+     * - Request (received via `self.onmessage`):
+     *   `{ requestId: number; cx: number; cy: number; chunkWidth: number; chunkHeight: number }`.
+     * - Response, success (send via `self.postMessage`, transferring the
+     *   buffer for a zero-copy handoff - `postMessage(response, [response.values.buffer])`):
+     *   `{ requestId: number; values: Float64Array }`, `values.length ===
+     *   chunkWidth * chunkHeight`, row-major (`localTy * chunkWidth + localTx`),
+     *   one sampled value per tile in the requested chunk. Compute each tile's
+     *   absolute coordinate as `cx * chunkWidth + localTx` /
+     *   `cy * chunkHeight + localTy`.
+     * - Response, error (one request failed without crashing the worker):
+     *   `{ requestId: number; error: string }`.
+     *
+     * Your worker must reply to every request with exactly one success or
+     * error message bearing the same `requestId`. A request left unanswered
+     * leaves that chunk permanently unfetched - there is no timeout - since
+     * `ChunkStreamer` tracks it as still in flight and never retries it.
+     */
+    workerSource: string;
+    /**
+     * Posted to the worker once, before any chunk request, when present.
+     *
+     * The transport for whatever the sampler needs to know that is not per-chunk
+     * - a seed, a feature size, a cost knob. Without it those values would have
+     * to be interpolated into {@link WorkerSampledChunkSourceOptions.workerSource}
+     * as literals, which turns every parameter change into a source rebuild and a
+     * new `Worker`.
+     *
+     * `postMessage` delivery is ordered, so the worker is guaranteed to see this
+     * before the first request. Distinguish it from a chunk request by its own
+     * shape; requests carry a `requestId`.
+     */
+    initMessage?: unknown;
+    /**
+     * Convert a sampled value (and its absolute tile coordinate) into a
+     * resolved tile, or `null` for an empty cell. Always runs on the main
+     * thread - a `ResolvedTile` references a `TileSet`/`Texture`, neither of
+     * which can cross a `postMessage` boundary. Must be pure and
+     * deterministic, same requirement as
+     * {@link import('./SampledChunkSource').SampledChunkSourceOptions.mapValueToTile}.
+     */
+    mapValueToTile(value: number, tx: number, ty: number): ResolvedTile | null;
+}
+/**
+ * Build a {@link import('./ChunkStreamer').ChunkStreamer}-ready
+ * {@link ChunkSource} that samples off the main thread via a Web Worker -
+ * the async counterpart to
+ * {@link import('./SampledChunkSource').createSampledChunkSource}, for
+ * sampling functions expensive enough to want off-thread execution.
+ *
+ * Unlike the synchronous provider, sampling logic cannot be passed as a
+ * live function - functions cannot cross a `postMessage` boundary. Instead
+ * {@link WorkerSampledChunkSourceOptions.workerSource} is a self-contained
+ * worker script string; see its documentation for the protocol.
+ *
+ * The returned value's `destroy()` MUST be called when done with it (e.g.
+ * alongside your `ChunkStreamer.destroy()` call) - the underlying `Worker`
+ * is a real resource that leaks otherwise. `ChunkSource` itself has no
+ * lifecycle hook, so this is not automatic.
+ *
+ * Implementation note: `workerSource` is Blob-URL'd into a real `Worker`
+ * (`new Blob([workerSource])` → `URL.createObjectURL` → `new Worker(url)`) -
+ * the same technique {@link import('@codexo/exojs').WorkletEffect} already
+ * uses for AudioWorklet processors. This is bundler-agnostic (no special
+ * config needed in Vite/webpack/etc.) but requires a Content-Security-Policy
+ * that permits `blob:` in `worker-src` (or `script-src` as a fallback) if
+ * your deployment sets one.
+ * @advanced
+ */
+export declare const createWorkerSampledChunkSource: (layer: TileLayer, options: WorkerSampledChunkSourceOptions) => ChunkSource & {
+    destroy(): void;
+};
+//# sourceMappingURL=WorkerSampledChunkSource.d.ts.map

package/dist/esm/WorkerSampledChunkSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerSampledChunkSource.d.ts","sourceRoot":"","sources":["../../src/WorkerSampledChunkSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5C;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;CAC5E;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,8BAA8B,GAAI,OAAO,SAAS,EAAE,SAAS,+BAA+B,KAAG,WAAW,GAAG;IAAE,OAAO,IAAI,IAAI,CAAA;CA8F1I,CAAC"}

package/dist/esm/WorkerSampledChunkSource.js

@@ -0,0 +1,117 @@
+import { packTile } from "./types.js";
+
+//#region src/WorkerSampledChunkSource.ts
+const isWorkerErrorMessage = (message) => "error" in message;
+/**
+* Build a {@link import('./ChunkStreamer').ChunkStreamer}-ready
+* {@link ChunkSource} that samples off the main thread via a Web Worker -
+* the async counterpart to
+* {@link import('./SampledChunkSource').createSampledChunkSource}, for
+* sampling functions expensive enough to want off-thread execution.
+*
+* Unlike the synchronous provider, sampling logic cannot be passed as a
+* live function - functions cannot cross a `postMessage` boundary. Instead
+* {@link WorkerSampledChunkSourceOptions.workerSource} is a self-contained
+* worker script string; see its documentation for the protocol.
+*
+* The returned value's `destroy()` MUST be called when done with it (e.g.
+* alongside your `ChunkStreamer.destroy()` call) - the underlying `Worker`
+* is a real resource that leaks otherwise. `ChunkSource` itself has no
+* lifecycle hook, so this is not automatic.
+*
+* Implementation note: `workerSource` is Blob-URL'd into a real `Worker`
+* (`new Blob([workerSource])` → `URL.createObjectURL` → `new Worker(url)`) -
+* the same technique {@link import('@codexo/exojs').WorkletEffect} already
+* uses for AudioWorklet processors. This is bundler-agnostic (no special
+* config needed in Vite/webpack/etc.) but requires a Content-Security-Policy
+* that permits `blob:` in `worker-src` (or `script-src` as a fallback) if
+* your deployment sets one.
+* @advanced
+*/
+const createWorkerSampledChunkSource = (layer, options) => {
+	const mapValueToTile = options.mapValueToTile.bind(options);
+	const blob = new Blob([options.workerSource], { type: "application/javascript" });
+	const url = URL.createObjectURL(blob);
+	const worker = new Worker(url);
+	URL.revokeObjectURL(url);
+	if (options.initMessage !== void 0) worker.postMessage(options.initMessage);
+	let requestCounter = 0;
+	const pending = /* @__PURE__ */ new Map();
+	let destroyed = false;
+	const composePayload = (values, request) => {
+		const { cx, cy, chunkWidth, chunkHeight } = request;
+		const startTx = cx * chunkWidth;
+		const startTy = cy * chunkHeight;
+		let out = null;
+		for (let ty = startTy; ty < startTy + chunkHeight; ty++) for (let tx = startTx; tx < startTx + chunkWidth; tx++) {
+			if (layer.width !== void 0 && layer.height !== void 0 && (tx >= layer.width || ty >= layer.height)) continue;
+			const localIndex = (ty - startTy) * chunkWidth + (tx - startTx);
+			const value = values[localIndex];
+			if (value === void 0) continue;
+			const resolved = mapValueToTile(value, tx, ty);
+			if (!resolved) continue;
+			out ??= new Uint32Array(chunkWidth * chunkHeight);
+			const tilesetIndex = layer.tilesets.indexOf(resolved.tileset);
+			out[localIndex] = packTile(tilesetIndex, resolved.localTileId, resolved.transform);
+		}
+		return out === null ? null : {
+			width: chunkWidth,
+			height: chunkHeight,
+			tiles: out
+		};
+	};
+	worker.onmessage = (event) => {
+		const message = event.data;
+		const entry = pending.get(message.requestId);
+		if (!entry) return;
+		pending.delete(message.requestId);
+		if (isWorkerErrorMessage(message)) {
+			entry.reject(new Error(message.error));
+			return;
+		}
+		entry.resolve(composePayload(message.values, entry));
+	};
+	worker.onerror = (event) => {
+		const error = /* @__PURE__ */ new Error(`WorkerSampledChunkSource worker error: ${event.message}`);
+		for (const entry of pending.values()) entry.reject(error);
+		pending.clear();
+	};
+	return {
+		getChunk(cx, cy) {
+			if (destroyed) return Promise.reject(/* @__PURE__ */ new Error("WorkerSampledChunkSource: getChunk() called after destroy()."));
+			const chunkWidth = layer.chunkWidth;
+			const chunkHeight = layer.chunkHeight;
+			const requestId = ++requestCounter;
+			return new Promise((resolve, reject) => {
+				pending.set(requestId, {
+					resolve,
+					reject,
+					cx,
+					cy,
+					chunkWidth,
+					chunkHeight
+				});
+				const request = {
+					requestId,
+					cx,
+					cy,
+					chunkWidth,
+					chunkHeight
+				};
+				worker.postMessage(request);
+			});
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			const error = /* @__PURE__ */ new Error("WorkerSampledChunkSource destroyed.");
+			for (const entry of pending.values()) entry.reject(error);
+			pending.clear();
+			worker.terminate();
+		}
+	};
+};
+
+//#endregion
+export { createWorkerSampledChunkSource };
+//# sourceMappingURL=WorkerSampledChunkSource.js.map

package/dist/esm/WorkerSampledChunkSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerSampledChunkSource.js","names":[],"sources":["../../src/WorkerSampledChunkSource.ts"],"sourcesContent":["import type { ChunkPayload, ChunkSource } from './ChunkSource';\nimport type { TileLayer } from './TileLayer';\nimport type { ResolvedTile } from './types';\nimport { packTile } from './types';\n\n/**\n * Options for {@link createWorkerSampledChunkSource}.\n * @advanced\n */\nexport interface WorkerSampledChunkSourceOptions {\n  /**\n   * Complete worker script source as a single self-contained string, Blob-URL'd\n   * into a real `Worker` at construction time - the same technique\n   * {@link import('@codexo/exojs').WorkletEffect} uses for AudioWorklet\n   * processors. No separate worker asset is fetched and no bundler-specific\n   * worker-import syntax is involved.\n   *\n   * Producing that string by hand-writing JavaScript into a template literal\n   * works but gives up type checking, linting and shared code. Prefer a build\n   * step that bundles a real module into a string: this repository's own\n   * examples are authored as `*.worker.ts` and imported through a `?worker`\n   * query, which is why they can `import` the sampling functions the main\n   * thread uses instead of restating them.\n   *\n   * Must implement this request/response protocol:\n   * - Request (received via `self.onmessage`):\n   *   `{ requestId: number; cx: number; cy: number; chunkWidth: number; chunkHeight: number }`.\n   * - Response, success (send via `self.postMessage`, transferring the\n   *   buffer for a zero-copy handoff - `postMessage(response, [response.values.buffer])`):\n   *   `{ requestId: number; values: Float64Array }`, `values.length ===\n   *   chunkWidth * chunkHeight`, row-major (`localTy * chunkWidth + localTx`),\n   *   one sampled value per tile in the requested chunk. Compute each tile's\n   *   absolute coordinate as `cx * chunkWidth + localTx` /\n   *   `cy * chunkHeight + localTy`.\n   * - Response, error (one request failed without crashing the worker):\n   *   `{ requestId: number; error: string }`.\n   *\n   * Your worker must reply to every request with exactly one success or\n   * error message bearing the same `requestId`. A request left unanswered\n   * leaves that chunk permanently unfetched - there is no timeout - since\n   * `ChunkStreamer` tracks it as still in flight and never retries it.\n   */\n  workerSource: string;\n  /**\n   * Posted to the worker once, before any chunk request, when present.\n   *\n   * The transport for whatever the sampler needs to know that is not per-chunk\n   * - a seed, a feature size, a cost knob. Without it those values would have\n   * to be interpolated into {@link WorkerSampledChunkSourceOptions.workerSource}\n   * as literals, which turns every parameter change into a source rebuild and a\n   * new `Worker`.\n   *\n   * `postMessage` delivery is ordered, so the worker is guaranteed to see this\n   * before the first request. Distinguish it from a chunk request by its own\n   * shape; requests carry a `requestId`.\n   */\n  initMessage?: unknown;\n  /**\n   * Convert a sampled value (and its absolute tile coordinate) into a\n   * resolved tile, or `null` for an empty cell. Always runs on the main\n   * thread - a `ResolvedTile` references a `TileSet`/`Texture`, neither of\n   * which can cross a `postMessage` boundary. Must be pure and\n   * deterministic, same requirement as\n   * {@link import('./SampledChunkSource').SampledChunkSourceOptions.mapValueToTile}.\n   */\n  mapValueToTile(value: number, tx: number, ty: number): ResolvedTile | null;\n}\n\ninterface WorkerRequestMessage {\n  readonly requestId: number;\n  readonly cx: number;\n  readonly cy: number;\n  readonly chunkWidth: number;\n  readonly chunkHeight: number;\n}\n\ninterface WorkerSuccessMessage {\n  readonly requestId: number;\n  readonly values: Float64Array;\n}\n\ninterface WorkerErrorMessage {\n  readonly requestId: number;\n  readonly error: string;\n}\n\ntype WorkerResponseMessage = WorkerSuccessMessage | WorkerErrorMessage;\n\nconst isWorkerErrorMessage = (message: WorkerResponseMessage): message is WorkerErrorMessage => 'error' in message;\n\ninterface PendingRequest {\n  readonly resolve: (payload: ChunkPayload | null) => void;\n  readonly reject: (error: Error) => void;\n  readonly cx: number;\n  readonly cy: number;\n  readonly chunkWidth: number;\n  readonly chunkHeight: number;\n}\n\n/**\n * Build a {@link import('./ChunkStreamer').ChunkStreamer}-ready\n * {@link ChunkSource} that samples off the main thread via a Web Worker -\n * the async counterpart to\n * {@link import('./SampledChunkSource').createSampledChunkSource}, for\n * sampling functions expensive enough to want off-thread execution.\n *\n * Unlike the synchronous provider, sampling logic cannot be passed as a\n * live function - functions cannot cross a `postMessage` boundary. Instead\n * {@link WorkerSampledChunkSourceOptions.workerSource} is a self-contained\n * worker script string; see its documentation for the protocol.\n *\n * The returned value's `destroy()` MUST be called when done with it (e.g.\n * alongside your `ChunkStreamer.destroy()` call) - the underlying `Worker`\n * is a real resource that leaks otherwise. `ChunkSource` itself has no\n * lifecycle hook, so this is not automatic.\n *\n * Implementation note: `workerSource` is Blob-URL'd into a real `Worker`\n * (`new Blob([workerSource])` → `URL.createObjectURL` → `new Worker(url)`) -\n * the same technique {@link import('@codexo/exojs').WorkletEffect} already\n * uses for AudioWorklet processors. This is bundler-agnostic (no special\n * config needed in Vite/webpack/etc.) but requires a Content-Security-Policy\n * that permits `blob:` in `worker-src` (or `script-src` as a fallback) if\n * your deployment sets one.\n * @advanced\n */\nexport const createWorkerSampledChunkSource = (layer: TileLayer, options: WorkerSampledChunkSourceOptions): ChunkSource & { destroy(): void } => {\n  const mapValueToTile = options.mapValueToTile.bind(options);\n\n  const blob = new Blob([options.workerSource], { type: 'application/javascript' });\n  const url = URL.createObjectURL(blob);\n  const worker = new Worker(url);\n  URL.revokeObjectURL(url);\n\n  if (options.initMessage !== undefined) {\n    worker.postMessage(options.initMessage);\n  }\n\n  let requestCounter = 0;\n  const pending = new Map<number, PendingRequest>();\n  let destroyed = false;\n\n  const composePayload = (values: Float64Array, request: PendingRequest): ChunkPayload | null => {\n    const { cx, cy, chunkWidth, chunkHeight } = request;\n    const startTx = cx * chunkWidth;\n    const startTy = cy * chunkHeight;\n\n    let out: Uint32Array | null = null;\n    for (let ty = startTy; ty < startTy + chunkHeight; ty++) {\n      for (let tx = startTx; tx < startTx + chunkWidth; tx++) {\n        // Bounded-layer edge chunks may be smaller than a full chunk - same\n        // clamp createSampledChunkSource applies, computed here (not asked\n        // of the worker) since only this side knows the layer's bounds.\n        if (layer.width !== undefined && layer.height !== undefined && (tx >= layer.width || ty >= layer.height)) continue;\n\n        const localIndex = (ty - startTy) * chunkWidth + (tx - startTx);\n        const value = values[localIndex];\n        if (value === undefined) continue; // defensive: malformed/short values array\n        const resolved = mapValueToTile(value, tx, ty);\n        if (!resolved) continue;\n\n        out ??= new Uint32Array(chunkWidth * chunkHeight);\n        const tilesetIndex = layer.tilesets.indexOf(resolved.tileset);\n        out[localIndex] = packTile(tilesetIndex, resolved.localTileId, resolved.transform);\n      }\n    }\n\n    return out === null ? null : { width: chunkWidth, height: chunkHeight, tiles: out };\n  };\n\n  worker.onmessage = (event: MessageEvent<WorkerResponseMessage>): void => {\n    const message = event.data;\n    const entry = pending.get(message.requestId);\n    if (!entry) return; // stale/unknown requestId (e.g. arrived after destroy())\n    pending.delete(message.requestId);\n\n    if (isWorkerErrorMessage(message)) {\n      entry.reject(new Error(message.error));\n      return;\n    }\n\n    entry.resolve(composePayload(message.values, entry));\n  };\n\n  worker.onerror = (event: ErrorEvent): void => {\n    const error = new Error(`WorkerSampledChunkSource worker error: ${event.message}`);\n    for (const entry of pending.values()) {\n      entry.reject(error);\n    }\n    pending.clear();\n  };\n\n  return {\n    getChunk(cx: number, cy: number): Promise<ChunkPayload | null> {\n      if (destroyed) {\n        return Promise.reject(new Error('WorkerSampledChunkSource: getChunk() called after destroy().'));\n      }\n\n      const chunkWidth = layer.chunkWidth;\n      const chunkHeight = layer.chunkHeight;\n      const requestId = ++requestCounter;\n\n      return new Promise<ChunkPayload | null>((resolve, reject) => {\n        pending.set(requestId, { resolve, reject, cx, cy, chunkWidth, chunkHeight });\n        const request: WorkerRequestMessage = { requestId, cx, cy, chunkWidth, chunkHeight };\n        worker.postMessage(request);\n      });\n    },\n\n    destroy(): void {\n      if (destroyed) return;\n      destroyed = true;\n      const error = new Error('WorkerSampledChunkSource destroyed.');\n      for (const entry of pending.values()) {\n        entry.reject(error);\n      }\n      pending.clear();\n      worker.terminate();\n    },\n  };\n};\n"],"mappings":";;;AAwFA,MAAM,wBAAwB,YAAkE,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqC3G,MAAa,kCAAkC,OAAkB,YAAgF;CAC/I,MAAM,iBAAiB,QAAQ,eAAe,KAAK,OAAO;CAE1D,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,YAAY,GAAG,EAAE,MAAM,yBAAyB,CAAC;CAChF,MAAM,MAAM,IAAI,gBAAgB,IAAI;CACpC,MAAM,SAAS,IAAI,OAAO,GAAG;CAC7B,IAAI,gBAAgB,GAAG;CAEvB,IAAI,QAAQ,gBAAgB,QAC1B,OAAO,YAAY,QAAQ,WAAW;CAGxC,IAAI,iBAAiB;CACrB,MAAM,0BAAU,IAAI,IAA4B;CAChD,IAAI,YAAY;CAEhB,MAAM,kBAAkB,QAAsB,YAAiD;EAC7F,MAAM,EAAE,IAAI,IAAI,YAAY,gBAAgB;EAC5C,MAAM,UAAU,KAAK;EACrB,MAAM,UAAU,KAAK;EAErB,IAAI,MAA0B;EAC9B,KAAK,IAAI,KAAK,SAAS,KAAK,UAAU,aAAa,MACjD,KAAK,IAAI,KAAK,SAAS,KAAK,UAAU,YAAY,MAAM;GAItD,IAAI,MAAM,UAAU,UAAa,MAAM,WAAW,WAAc,MAAM,MAAM,SAAS,MAAM,MAAM,SAAS;GAE1G,MAAM,cAAc,KAAK,WAAW,cAAc,KAAK;GACvD,MAAM,QAAQ,OAAO;GACrB,IAAI,UAAU,QAAW;GACzB,MAAM,WAAW,eAAe,OAAO,IAAI,EAAE;GAC7C,IAAI,CAAC,UAAU;GAEf,QAAQ,IAAI,YAAY,aAAa,WAAW;GAChD,MAAM,eAAe,MAAM,SAAS,QAAQ,SAAS,OAAO;GAC5D,IAAI,cAAc,SAAS,cAAc,SAAS,aAAa,SAAS,SAAS;EACnF;EAGF,OAAO,QAAQ,OAAO,OAAO;GAAE,OAAO;GAAY,QAAQ;GAAa,OAAO;EAAI;CACpF;CAEA,OAAO,aAAa,UAAqD;EACvE,MAAM,UAAU,MAAM;EACtB,MAAM,QAAQ,QAAQ,IAAI,QAAQ,SAAS;EAC3C,IAAI,CAAC,OAAO;EACZ,QAAQ,OAAO,QAAQ,SAAS;EAEhC,IAAI,qBAAqB,OAAO,GAAG;GACjC,MAAM,OAAO,IAAI,MAAM,QAAQ,KAAK,CAAC;GACrC;EACF;EAEA,MAAM,QAAQ,eAAe,QAAQ,QAAQ,KAAK,CAAC;CACrD;CAEA,OAAO,WAAW,UAA4B;EAC5C,MAAM,wBAAQ,IAAI,MAAM,0CAA0C,MAAM,SAAS;EACjF,KAAK,MAAM,SAAS,QAAQ,OAAO,GACjC,MAAM,OAAO,KAAK;EAEpB,QAAQ,MAAM;CAChB;CAEA,OAAO;EACL,SAAS,IAAY,IAA0C;GAC7D,IAAI,WACF,OAAO,QAAQ,uBAAO,IAAI,MAAM,8DAA8D,CAAC;GAGjG,MAAM,aAAa,MAAM;GACzB,MAAM,cAAc,MAAM;GAC1B,MAAM,YAAY,EAAE;GAEpB,OAAO,IAAI,SAA8B,SAAS,WAAW;IAC3D,QAAQ,IAAI,WAAW;KAAE;KAAS;KAAQ;KAAI;KAAI;KAAY;IAAY,CAAC;IAC3E,MAAM,UAAgC;KAAE;KAAW;KAAI;KAAI;KAAY;IAAY;IACnF,OAAO,YAAY,OAAO;GAC5B,CAAC;EACH;EAEA,UAAgB;GACd,IAAI,WAAW;GACf,YAAY;GACZ,MAAM,wBAAQ,IAAI,MAAM,qCAAqC;GAC7D,KAAK,MAAM,SAAS,QAAQ,OAAO,GACjC,MAAM,OAAO,KAAK;GAEpB,QAAQ,MAAM;GACd,OAAO,UAAU;EACnB;CACF;AACF"}

package/dist/esm/autoTile.d.ts

@@ -11,7 +11,7 @@ export interface AutoTileOptions {
      *
      * If omitted, group membership defaults to {@link WangSet.isMember} on the
      * cell's `localTileId` (and a matching `tilesetIndex`). That default is
-     * *variant-stable* — every autotiled variant counts as a member — which is
+     * *variant-stable* - every autotiled variant counts as a member - which is
      * what makes {@link refreshCell} correct. If you supply a `matchFn` for use
      * with `refreshCell`, it MUST likewise be variant-stable (independent of the
      * currently-rendered variant), e.g. keyed on a separate logical-terrain grid
@@ -54,16 +54,20 @@ export interface AutoTileOptions {
  * combinations to 47 valid blob states).
  *
  * **Edge mode bitmask (bit positions):** Top=1, Right=2, Bottom=4, Left=8.
+ *
+ * @throws If `layer` is unbounded (no fixed width/height) - there is no
+ * "whole layer" to sweep. Use {@link refreshCell} to autotile an unbounded
+ * layer incrementally, one edited cell at a time.
  */
-export declare function autoTile(layer: TileLayer, wangSet: WangSet, options?: AutoTileOptions): void;
+export declare const autoTile: (layer: TileLayer, wangSet: WangSet, options?: AutoTileOptions) => void;
 /**
  * Incrementally re-autotile a single cell and its eight neighbours after an
  * edit, instead of re-running {@link autoTile} over the whole layer.
  *
  * A cell's blob/edge mask depends only on its immediate neighbours, so painting
  * or erasing cell `(x, y)` can change the variant of that cell and of the (up
- * to) eight cells that have it as a neighbour — but nothing further out. This
- * recomputes exactly that 3×3 neighbourhood, touching only the 1–4 chunks it
+ * to) eight cells that have it as a neighbour - but nothing further out. This
+ * recomputes exactly that 3×3 neighbourhood, touching only the 1-4 chunks it
  * spans (and rebuilding geometry only for chunks whose tiles actually change).
  * For a paint operation this is O(1) work versus `autoTile`'s O(width·height).
  *
@@ -80,4 +84,5 @@ export declare function autoTile(layer: TileLayer, wangSet: WangSet, options?: A
  * @param wangSet The Wang set to resolve variants from.
  * @param options Membership / border options (shared with {@link autoTile}).
  */
-export declare function refreshCell(layer: TileLayer, x: number, y: number, wangSet: WangSet, options?: AutoTileOptions): void;
+export declare const refreshCell: (layer: TileLayer, x: number, y: number, wangSet: WangSet, options?: AutoTileOptions) => void;
+//# sourceMappingURL=autoTile.d.ts.map

package/dist/esm/autoTile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoTile.d.ts","sourceRoot":"","sources":["../../src/autoTile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IACvF;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA0ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,SAAS,EAAE,SAAS,OAAO,EAAE,UAAU,eAAe,KAAG,IAuDxF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,SAAS,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,UAAU,eAAe,KAAG,IA0BjH,CAAC"}