@rickyzhangca/fpsr 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.0.1
+
+First public release.
+
+- ESM library for browser and Node.js targeting Factorio **2.1.11** (vanilla + Space Age + Elevated Rails + Quality)
+- Entry points: `@rickyzhangca/fpsr`, `@rickyzhangca/fpsr/planner`, `@rickyzhangca/fpsr/canvas`, `@rickyzhangca/fpsr/render-db`, `@rickyzhangca/fpsr/node`
+- Decode/encode blueprint strings, resolve connectivity, plan draw lists, and render to Canvas2D
+- Sprite atlases and render database are **not** bundled — load via `cdnAssets` or `localAssets` from your own pipeline output

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricky Zhang
+
+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,267 @@
+# fpsr
+
+Headless **Factorio 2.1.11** blueprint-string renderer for browser and Node.js.
+Decodes compressed blueprint strings, resolves connectivity-aware sprite variants
+(belts, pipes, walls, rails, trains, wires), plans a serializable draw list, and
+executes it on a Canvas2D backend.
+
+Supports vanilla plus **Space Age**, **Elevated Rails**, and **Quality** content
+from the official data packages.
+
+## Install
+
+```bash
+npm install @rickyzhangca/fpsr
+```
+
+For Node.js rendering, add the optional peer dependency:
+
+```bash
+npm install skia-canvas
+```
+
+The npm package ships **code only** — sprite atlases and the render database are
+not included (see [Asset hosting](#asset-hosting)).
+
+## Quick start (browser)
+
+```ts
+import { cdnAssets, createRenderer, decode } from "@rickyzhangca/fpsr";
+
+const doc = decode(blueprintString);
+const renderer = await createRenderer({
+  assets: cdnAssets("https://your-cdn.example.com/2.1.11"),
+});
+
+const { canvas } = await renderer.render(doc);
+document.body.appendChild(canvas as HTMLCanvasElement);
+```
+
+`createRenderer` loads the render database once, plans the draw list, sizes a
+canvas from blueprint bounds, and paints atlas sprites. Pass `blueprintPath` when
+rendering a nested blueprint book entry.
+
+### Large PNG export
+
+For full-resolution images that may exceed browser canvas limits, use the tiled
+PNG exporter. It renders bounded temporary canvases and feeds their rows into an
+incremental PNG encoder, so it never creates one canvas at the final dimensions:
+
+```ts
+const { blob, width, height } = await renderer.renderTiledPng(doc, {
+  pixelsPerTile: 64,
+  tileSize: 2048,
+  onProgress(event) {
+    console.log(event);
+  },
+});
+
+const link = document.createElement("a");
+link.href = URL.createObjectURL(blob);
+link.download = `blueprint-${width}x${height}.png`;
+link.click();
+URL.revokeObjectURL(link.href);
+```
+
+The exporter always produces lossless PNG. Canvas-based WebP export remains
+available through `render(...).toImageBlob({ type: "image/webp" })` for outputs
+that fit safely in one canvas.
+
+## Quick start (Node.js)
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { Canvas } from "skia-canvas";
+import { createRenderer, decode } from "@rickyzhangca/fpsr";
+import { localAssets } from "@rickyzhangca/fpsr/node";
+
+const doc = decode(blueprintString);
+const renderer = await createRenderer({
+  assets: localAssets("assets-out/2.1.11"),
+  createCanvas: (w, h) => new Canvas(w, h),
+});
+
+const { toPngBuffer } = await renderer.render(doc);
+await writeFile("out.png", await toPngBuffer());
+```
+
+`localAssets` reads schema-2 `manifest.json` and the selected `1x` or `2x`
+content-addressed render DB and atlas files from a pipeline output directory on
+disk. Asset sources default to `2x`; callers can set `assetTier` when creating a
+renderer. The render DB's `assetDensity` must match the selected tier or
+`createRenderer` throws `AssetDensityMismatchError`.
+
+## Package entry points
+
+| Import           | Contents                                                                 |
+| ---------------- | ------------------------------------------------------------------------ |
+| `@rickyzhangca/fpsr`           | Decode/encode, books, migrate, `createRenderer`, `cdnAssets`, core types |
+| `@rickyzhangca/fpsr/planner`   | `resolve`, `planDrawList`, draw-list helpers, belt/train/wire utilities  |
+| `@rickyzhangca/fpsr/canvas`    | `executeDrawList`, background painters, silhouette helpers               |
+| `@rickyzhangca/fpsr/render-db` | Full `RenderDb` / entity / terrain type surface                          |
+| `@rickyzhangca/fpsr/node`      | `localAssets` (filesystem; requires `skia-canvas`)                       |
+
+## Blueprint books
+
+```ts
+import { decode, listBlueprints, selectBlueprint } from "@rickyzhangca/fpsr";
+
+const doc = decode(bookString);
+const refs = listBlueprints(doc); // flattened tree with paths
+
+const bp = selectBlueprint(doc, [0, 2]); // third child of first entry
+```
+
+`selectBlueprint(doc)` without a path follows the book's `active_index` chain.
+
+## Pure planning (no assets)
+
+For tests, diff tooling, or custom backends, call the pure pipeline stages
+directly — no images or network required beyond loading the render DB named by
+`manifest.json`:
+
+```ts
+import { decode, migrateTo2x, selectBlueprint } from "@rickyzhangca/fpsr";
+import { planDrawList, resolve, serializeDrawList } from "@rickyzhangca/fpsr/planner";
+import renderDb from "./render-db.json" with { type: "json" };
+
+const bp = migrateTo2x(selectBlueprint(decode(source))); // optional; plan/resolve also migrate
+const { entities, warnings } = resolve(bp, renderDb);
+const list = planDrawList(bp, renderDb, { altMode: true });
+const snapshot = serializeDrawList(list); // stable JSON for fixtures
+```
+
+`serializeDrawList` rounds coordinates to four decimal places with stable key
+order for reviewable text diffs.
+
+## Backgrounds
+
+`RenderOptions.background` is a discriminated union:
+
+```ts
+await renderer.render(doc, { background: { type: "auto" } });
+await renderer.render(doc, { background: { type: "checkerboard" } });
+await renderer.render(doc, { background: { type: "space", planet: true, planetName: "nauvis" } });
+await renderer.render(doc, { background: { type: "terrain", name: "dirt" } });
+await renderer.render(doc, { background: { type: "none" } });
+```
+
+Unknown terrain names throw `UnknownTerrainBackgroundError` (they do not render
+as transparent).
+
+## AbortSignal
+
+`renderer.render` / `measure` / `renderTiledPng` honor `signal`. Asset loads via
+`cdnAssets` / `localAssets` accept `loadAtlasImage(i, tier, { signal })`.
+
+**Semantics:** aborting rejects only the waiting caller with `AbortError`. Shared
+in-flight fetches/decodes continue for other concurrent consumers of the same
+cache key. Aborted waits never poison a successful cache entry; genuine load
+failures clear the shared promise so a later call can retry.
+
+## API reference
+
+### Decoding
+
+| Export                  | Kind     | Description                                                       |
+| ----------------------- | -------- | ----------------------------------------------------------------- |
+| `decode`                | function | Parse a blueprint string or raw JSON string → `BlueprintDocument` |
+| `encode`                | function | Serialize a `BlueprintDocument` back to a blueprint string        |
+| `migrateTo2x`           | function | Migrate a 1.x `Blueprint` to 2.x shape (idempotent)               |
+| `migrateDocumentTo2x`   | function | Migrate every nested blueprint in a document / book               |
+| `BLUEPRINT_ADAPTERS`    | const    | Ordered 1.x→2.x adapter registry                                  |
+| `BlueprintAdapter`      | type     | `{ id, apply }` adapter entry                                     |
+| `BlueprintDecodeError`  | class    | Thrown when `decode` fails                                        |
+| `BlueprintDecodeReason` | type     | Error reason codes for decode failures                            |
+| `decodeVersion`         | function | Split encoded `version` into major/minor/patch                    |
+
+### Blueprint books
+
+| Export                  | Kind     | Description                                             |
+| ----------------------- | -------- | ------------------------------------------------------- |
+| `listBlueprints`        | function | Flatten a book tree → `BlueprintRef[]` with index paths |
+| `selectBlueprint`       | function | Select a nested blueprint by optional `number[]` path   |
+| `BlueprintSelectError`  | class    | Thrown when book navigation fails                       |
+| `BlueprintSelectReason` | type     | Error reason codes for selection failures               |
+
+### Planner (`@rickyzhangca/fpsr/planner`)
+
+| Export                    | Kind     | Description                                                                |
+| ------------------------- | -------- | -------------------------------------------------------------------------- |
+| `resolve`                 | function | `(bp, renderDb, opts?)` → `{ entities, warnings }`                         |
+| `planDrawList`            | function | `(bp, renderDb, opts?)` → `DrawList`                                       |
+| `planDrawListWithOptions` | function | Same as plan; returns `{ drawList, profile? }` when `profile: true`        |
+| `analyzePlan`             | function | `(bp, drawList, renderDb)` → resolve coverage + draw-list integrity checks |
+| `PlanOptions`             | type     | `altMode`, `beltEndings`, optional `profile`                               |
+| `serializeDrawList`       | function | Stable JSON serialization for fixtures                                     |
+
+### Rendering (`@rickyzhangca/fpsr`)
+
+| Export                          | Kind     | Description                                                          |
+| ------------------------------- | -------- | -------------------------------------------------------------------- |
+| `createRenderer`                | function | High-level async renderer (plan + load + paint)                      |
+| `cdnAssets` / `localAssets`     | function | HTTP / filesystem `AssetSource`                                      |
+| `MeasureOptions`                | type     | Layout-only options for `measure`                                    |
+| `RenderOptions`                 | type     | Public paint options (`background`, `altMode`, `showCoordinates`, …) |
+| `TiledPngOptions`               | type     | Full-resolution PNG options (no `profile` / canvas / maxOutputSize)  |
+| `RenderBackground`              | type     | Discriminated background mode                                        |
+| `AssetDensityMismatchError`     | class    | Thrown when render-db density does not match `assetTier`             |
+| `UnknownTerrainBackgroundError` | class    | Thrown for unknown `background: { type: "terrain", name }`           |
+| `Renderer`                      | type     | `{ measure, render, renderTiledPng, dispose }`                       |
+
+`Renderer.dispose()` clears renderer-owned icon/silhouette caches only. It does
+**not** call `AssetSource.dispose()` or close atlas images owned by the asset
+source — those remain the caller's responsibility.
+
+### Canvas (`@rickyzhangca/fpsr/canvas`)
+
+| Export                  | Kind     | Description                       |
+| ----------------------- | -------- | --------------------------------- |
+| `executeDrawList`       | function | Paint a `DrawList` onto a context |
+| `Canvas2DContextLike`   | type     | Minimal Canvas2D context          |
+| `drawTileCheckerboard`  | function | Tile-aligned checkerboard fill    |
+| `drawSpaceBackground`   | function | Procedural starfield              |
+| `drawTerrainBackground` | function | Named terrain patches             |
+
+### Blueprint / render-db types
+
+| Export               | Kind | Description                                    |
+| -------------------- | ---- | ---------------------------------------------- |
+| `BlueprintDocument`  | type | Exactly-one top-level wrapper (`blueprint`, …) |
+| `BlueprintBookEntry` | type | Exactly-one book-slot content key              |
+| `RenderDb`           | type | Pipeline-produced sprite/layer database        |
+| `FrameId`            | type | Numeric frame index into `RenderDb.frames`     |
+| `FrameMeta`          | type | Atlas frame trim and scale metadata            |
+
+## Asset hosting
+
+Rendering requires a content-addressed **render database** and packed **sprite
+atlases** in deterministic `1x` and `2x` tiers described by a schema-2
+`manifest.json`. These are generated from **your own game files** using the offline pipeline in this repository
+([`@fpsr/pipeline`](https://github.com/rickyzhangca/fpsr/tree/main/tools/pipeline)).
+
+They are **never redistributed** with the npm package or committed to git. Host
+them on private infrastructure (`cdnAssets`) or load from disk (`localAssets`).
+
+## Versioning
+
+- **npm package**: semver; breaking changes may land in 0.x.
+- **Render database schema**: version `2` (see `RenderDb` in source).
+- **Game target**: Factorio **2.1.11** exactly (vanilla + Space Age + Elevated
+  Rails + Quality).
+
+A new game version requires regenerating assets and may require a matching
+library release.
+
+## License
+
+**Source code** in this package is released under the [MIT License](LICENSE).
+
+**Factorio game assets** — all sprites, icons, and atlases are the property of
+**Wube Software Ltd.** They are not included in this package and must not be
+redistributed. Generate assets locally from a licensed Factorio installation via
+`@fpsr/pipeline`. The monorepo commits a metadata-only render-db test fixture (no
+pixel data); golden PNG test renders are not redistributed.
+
+_Factorio is a trademark of Wube Software Ltd. This project is not affiliated
+with or endorsed by Wube Software._

package/dist/abort-CrgARaZd.js

@@ -0,0 +1,43 @@
+//#region src/abort.ts
+/**
+* Abort helpers shared by asset sources and the renderer atlas cache.
+*
+* Semantics: aborting rejects only the waiting caller. Shared underlying work
+* continues for other concurrent consumers and is never cancelled by a waiter.
+*/
+function abortError(message = "Operation aborted") {
+	const error = new Error(message);
+	error.name = "AbortError";
+	return error;
+}
+function throwIfAborted(signal, message) {
+	if (!signal?.aborted) return;
+	if (typeof signal.throwIfAborted === "function") signal.throwIfAborted();
+	throw abortError(message);
+}
+/**
+* Race a shared promise against an AbortSignal without cancelling the shared work.
+*/
+function raceWithAbort(promise, signal) {
+	if (!signal) return promise;
+	throwIfAborted(signal);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener("abort", onAbort);
+			reject(abortError());
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			if (signal.aborted) reject(abortError());
+			else resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+//#endregion
+export { throwIfAborted as n, raceWithAbort as t };
+
+//# sourceMappingURL=abort-CrgARaZd.js.map

package/dist/abort-CrgARaZd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-CrgARaZd.js","names":[],"sources":["../src/abort.ts"],"sourcesContent":["/**\n * Abort helpers shared by asset sources and the renderer atlas cache.\n *\n * Semantics: aborting rejects only the waiting caller. Shared underlying work\n * continues for other concurrent consumers and is never cancelled by a waiter.\n */\n\nexport function abortError(message = \"Operation aborted\"): Error {\n  const error = new Error(message);\n  error.name = \"AbortError\";\n  return error;\n}\n\nexport function throwIfAborted(signal?: AbortSignal, message?: string): void {\n  if (!signal?.aborted) return;\n  if (typeof signal.throwIfAborted === \"function\") signal.throwIfAborted();\n  throw abortError(message);\n}\n\n/**\n * Race a shared promise against an AbortSignal without cancelling the shared work.\n */\nexport function raceWithAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {\n  if (!signal) return promise;\n  throwIfAborted(signal);\n  return new Promise<T>((resolve, reject) => {\n    const onAbort = () => {\n      signal.removeEventListener(\"abort\", onAbort);\n      reject(abortError());\n    };\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n    promise.then(\n      (value) => {\n        signal.removeEventListener(\"abort\", onAbort);\n        if (signal.aborted) reject(abortError());\n        else resolve(value);\n      },\n      (error) => {\n        signal.removeEventListener(\"abort\", onAbort);\n        reject(error);\n      },\n    );\n  });\n}\n"],"mappings":";;;;;;;AAOA,SAAgB,WAAW,UAAU,qBAA4B;CAC/D,MAAM,QAAQ,IAAI,MAAM,OAAO;CAC/B,MAAM,OAAO;CACb,OAAO;AACT;AAEA,SAAgB,eAAe,QAAsB,SAAwB;CAC3E,IAAI,CAAC,QAAQ,SAAS;CACtB,IAAI,OAAO,OAAO,mBAAmB,YAAY,OAAO,eAAe;CACvE,MAAM,WAAW,OAAO;AAC1B;;;;AAKA,SAAgB,cAAiB,SAAqB,QAAkC;CACtF,IAAI,CAAC,QAAQ,OAAO;CACpB,eAAe,MAAM;CACrB,OAAO,IAAI,SAAY,SAAS,WAAW;EACzC,MAAM,gBAAgB;GACpB,OAAO,oBAAoB,SAAS,OAAO;GAC3C,OAAO,WAAW,CAAC;EACrB;EACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,QAAQ,MACL,UAAU;GACT,OAAO,oBAAoB,SAAS,OAAO;GAC3C,IAAI,OAAO,SAAS,OAAO,WAAW,CAAC;QAClC,QAAQ,KAAK;EACpB,IACC,UAAU;GACT,OAAO,oBAAoB,SAAS,OAAO;GAC3C,OAAO,KAAK;EACd,CACF;CACF,CAAC;AACH"}

package/dist/assets-Dy4fqZBV.d.ts

@@ -0,0 +1,85 @@
+import { c as ImageSource, t as AssetLoadOptions } from "./host-DdX4g1YM.js";
+import { v as RenderDb } from "./render-db-BFQIspDB.js";
+import { t as AssetEvent } from "./profile-CTN1Q5SI.js";
+
+//#region src/assets.d.ts
+/**
+ * Pluggable atlas / render-db loader. Browser uses ImageBitmap; node uses
+ * skia-canvas Image (via fpsr/node).
+ *
+ * ## AbortSignal semantics
+ *
+ * `loadRenderDb` / `loadAtlasImage` accept an optional `signal` on the load
+ * options. Aborting rejects **only the waiting caller** with an `AbortError`.
+ * Shared in-flight network/decode work is **not** cancelled for other
+ * concurrent consumers of the same cache key. Aborted waits never write into
+ * or delete a successful cache entry; only genuine load failures clear the
+ * shared promise slot so a later call can retry.
+ */
+interface AssetSource {
+  loadRenderDb(tier?: AssetTier, options?: AssetLoadOptions): Promise<RenderDb>;
+  loadAtlasImage(index: number, tier?: AssetTier, options?: AssetLoadOptions): Promise<ImageSource>;
+  /**
+   * Optional: register canvas text fonts listed in the asset manifest (e.g. DejaVu).
+   * Missing fonts are ignored so renders still work with CSS fallbacks.
+   */
+  ensureFonts?(options?: AssetLoadOptions): Promise<void>;
+  /**
+   * Optional: release retained decoded images / clear caches.
+   * Ownership stays with the AssetSource caller — Renderer.dispose never invokes this.
+   */
+  dispose?(): void;
+}
+type AssetTier = "1x" | "2x";
+interface ManifestAtlas {
+  file: string;
+  w: number;
+  h: number;
+  sha256?: string;
+}
+interface ManifestFont {
+  file: string;
+  family: string;
+  sha256?: string;
+  bytes?: number;
+}
+interface AssetManifest {
+  schema: 2;
+  gameVersion: string;
+  mods: string[];
+  tiers: Record<AssetTier, AssetTierManifest>;
+  /** Optional bundled TTFs for canvas text (e.g. DejaVu Sans). */
+  fonts?: ManifestFont[];
+}
+interface AssetTierManifest {
+  density: 1 | 2;
+  atlases: ManifestAtlas[];
+  renderDb: {
+    file: string;
+    sha256: string;
+    bytes?: number;
+  };
+}
+interface CdnAssetsOptions {
+  /**
+   * Decode an atlas blob when `createImageBitmap` is unavailable (e.g. Node 22
+   * with fetch but no ImageBitmap). Required for node consumers of cdnAssets;
+   * browser builds ignore this when createImageBitmap exists.
+   */
+  decodeImage?: (blob: Blob, signal?: AbortSignal) => Promise<ImageSource>;
+  fetchImpl?: typeof fetch;
+  /** Maximum simultaneous bitmap decodes. Fetches remain concurrent. Default: 2. */
+  maxConcurrentDecodes?: number;
+  /** Optional sink for fetch/decode timing events (profiling). */
+  onAssetEvent?: (event: AssetEvent) => void;
+}
+/**
+ * Fetch-based AssetSource for CDN (or any HTTP) layouts:
+ *   {baseUrl}/manifest.json
+ *   {baseUrl}/{manifest.tiers[tier].renderDb.file}
+ *   {baseUrl}/{atlas.file}
+ */
+declare function cdnAssets(baseUrl: string, options?: CdnAssetsOptions): AssetSource;
+//#endregion
+export { CdnAssetsOptions as a, AssetTierManifest as i, AssetSource as n, ManifestFont as o, AssetTier as r, cdnAssets as s, AssetManifest as t };
+//# sourceMappingURL=assets-Dy4fqZBV.d.ts.map

package/dist/assets-Dy4fqZBV.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets-Dy4fqZBV.d.ts","names":[],"sources":["../src/assets.ts"],"mappings":";;;;;;;AAkBA;;;;;;;;;;;UAAiB,WAAA;EACf,YAAA,CAAa,IAAA,GAAO,SAAA,EAAW,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,QAAA;EACpE,cAAA,CAAe,KAAA,UAAe,IAAA,GAAO,SAAA,EAAW,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,WAAA;EAKpC;;;;EAAjD,WAAA,EAAa,OAAA,GAAU,gBAAA,GAAmB,OAAA;EANX;;;;EAW/B,OAAA;AAAA;AAAA,KAGU,SAAA;AAAA,UAEK,aAAA;EACf,IAAA;EACA,CAAA;EACA,CAAA;EACA,MAAA;AAAA;AAAA,UAGe,YAAA;EACf,IAAA;EACA,MAAA;EACA,MAAA;EACA,KAAA;AAAA;AAAA,UAGe,aAAA;EACf,MAAA;EACA,WAAA;EACA,IAAA;EACA,KAAA,EAAO,MAAA,CAAO,SAAA,EAAW,iBAAA;EAlBG;EAoB5B,KAAA,GAAQ,YAAA;AAAA;AAAA,UAGO,iBAAA;EACf,OAAA;EACA,OAAA,EAAS,aAAa;EACtB,QAAA;IACE,IAAA;IACA,MAAA;IACA,KAAA;EAAA;AAAA;AAAA,UAIa,gBAAA;EAzBf;;;;;EA+BA,WAAA,IAAe,IAAA,EAAM,IAAA,EAAM,MAAA,GAAS,WAAA,KAAgB,OAAA,CAAQ,WAAA;EAC5D,SAAA,UAAmB,KAAA;EA1BS;EA4B5B,oBAAA;EAxBc;EA0Bd,YAAA,IAAgB,KAAA,EAAO,UAAA;AAAA;;;;;;;iBAoFT,SAAA,CAAU,OAAA,UAAiB,OAAA,GAAU,gBAAA,GAAmB,WAAW"}

package/dist/canvas.d.ts

@@ -0,0 +1,98 @@
+import { c as ImageSource, s as ImageDataLike } from "./host-DdX4g1YM.js";
+import { h as FrameMeta, w as TerrainPatchBackground } from "./render-db-BFQIspDB.js";
+import { n as ExecuteDrawListOptions, r as ExecuteDrawListStats, t as Canvas2DContextLike } from "./types-CHgZBSra.js";
+import { c as perfMark, l as perfMeasure, p as DrawList, s as nowMs, u as TileFrame } from "./profile-CTN1Q5SI.js";
+
+//#region src/canvas2d/execute.d.ts
+/**
+ * Execute a sorted draw list against a Canvas2D context.
+ * `images[i]` is the atlas image for atlas index i.
+ */
+declare function executeDrawList(ctx: Canvas2DContextLike, list: DrawList, images: ImageSource[], opts: ExecuteDrawListOptions): void;
+//#endregion
+//#region src/icon-silhouette.d.ts
+/** Pixel radius for feMorphology-style alpha dilation on entity-info icons. */
+declare const ENTITY_INFO_SILHOUETTE_RADIUS_PX = 12;
+/** Soft blur applied after dilation to feather the silhouette edge. */
+declare const ENTITY_INFO_SILHOUETTE_BLUR_PX = 16;
+/** Total source-pixel padding around icon crops for spread + blur. */
+declare function entityInfoSilhouettePadPx(dilateRadius?: number, blurRadius?: number): number;
+interface ImageDataContext {
+  drawImage(image: ImageSource, dx: number, dy: number): void;
+  createImageData?(sw: number, sh: number): ImageDataLike;
+  getImageData(sx: number, sy: number, sw: number, sh: number): ImageDataLike;
+  putImageData(data: ImageDataLike, dx: number, dy: number): void;
+}
+interface SilhouetteCanvasLike {
+  width: number;
+  height: number;
+  getContext(type: "2d"): ImageDataContext | null;
+}
+/**
+ * Dilate and blur an isolated icon crop into a padded black silhouette image.
+ * Returns undefined when the canvas context cannot read/write ImageData.
+ */
+declare function bakeEntityInfoSilhouette(iconImage: ImageSource, iconWidth: number, iconHeight: number, createCanvas: (width: number, height: number) => SilhouetteCanvasLike, dilateRadius?: number, blurRadius?: number): ImageSource | undefined;
+//#endregion
+//#region src/coordinate-overlay.d.ts
+/**
+ * Draw map-space tile grid lines and coordinate labels over a rendered preview.
+ * Canvas (0,0) corresponds to `tileFrame.minX/minY`.
+ */
+declare function drawCoordinateOverlay(ctx: Canvas2DContextLike, tileFrame: TileFrame, pixelsPerTile: number, width: number, height: number, outputTileFrame?: TileFrame): void;
+//#endregion
+//#region src/checkerboard.d.ts
+/** Fill `width`×`height` with an axis-aligned checkerboard; one cell = `pixelsPerTile` px. */
+declare function drawTileCheckerboard(ctx: Canvas2DContextLike, width: number, height: number, pixelsPerTile: number, tileOffsetX?: number, tileOffsetY?: number): void;
+/** Paint an image on top of a tile-aligned checkerboard (for external reference PNGs). */
+declare function blitWithTileCheckerboard(canvas: {
+  width: number;
+  height: number;
+  getContext(type: "2d"): Canvas2DContextLike | null;
+}, image: ImageSource, width: number, height: number, pixelsPerTile: number): void;
+//#endregion
+//#region src/space-background.d.ts
+interface SpacePlanetDecoration {
+  frame: FrameMeta;
+  image: ImageSource;
+}
+interface DrawSpaceBackgroundOptions {
+  /** Optional starmap planet drawn bottom-left after the starfield. */
+  planet?: SpacePlanetDecoration;
+  /** Stable salt; selected planets use different skies while rerenders remain reproducible. */
+  seed?: number;
+  /** Full output dimensions and this viewport's offset within it (for tiled rendering). */
+  viewport?: {
+    x: number;
+    y: number;
+    fullWidth: number;
+    fullHeight: number;
+  };
+}
+/**
+ * Draw the space-platform planet peeking from the bottom-left, matching
+ * Factorio's backdrop offset ratios scaled to the canvas.
+ */
+declare function drawSpacePlanet(ctx: Canvas2DContextLike, width: number, height: number, planet: SpacePlanetDecoration, viewport?: DrawSpaceBackgroundOptions["viewport"]): void;
+/** Fill `width`×`height` with a layered deterministic starfield. */
+declare function drawSpaceBackground(ctx: Canvas2DContextLike, width: number, height: number, options?: DrawSpaceBackgroundOptions): void;
+//#endregion
+//#region src/terrain-background.d.ts
+interface DrawTerrainBackgroundOptions {
+  tileFrame: TileFrame;
+  pixelsPerTile: number;
+  frames: FrameMeta[];
+  images: ImageSource[];
+  background?: TerrainPatchBackground;
+  fallbackColor: [number, number, number, number];
+}
+/**
+ * Paint an infinite terrain plane anchored to absolute map coordinates.
+ * Only complete, untransformed Factorio patches are drawn. Larger regions may
+ * be subdivided into complete smaller authored patches, so every destination is
+ * covered exactly once and every texture edge keeps its intended orientation.
+ */
+declare function drawTerrainBackground(ctx: Canvas2DContextLike, width: number, height: number, options: DrawTerrainBackgroundOptions): void;
+//#endregion
+export { type Canvas2DContextLike, type DrawSpaceBackgroundOptions, type DrawTerrainBackgroundOptions, ENTITY_INFO_SILHOUETTE_BLUR_PX, ENTITY_INFO_SILHOUETTE_RADIUS_PX, type ExecuteDrawListOptions, type ExecuteDrawListStats, type SpacePlanetDecoration, bakeEntityInfoSilhouette, blitWithTileCheckerboard, drawCoordinateOverlay, drawSpaceBackground, drawSpacePlanet, drawTerrainBackground, drawTileCheckerboard, entityInfoSilhouettePadPx, executeDrawList, nowMs, perfMark, perfMeasure };
+//# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","names":[],"sources":["../src/canvas2d/execute.ts","../src/icon-silhouette.ts","../src/coordinate-overlay.ts","../src/checkerboard.ts","../src/space-background.ts","../src/terrain-background.ts"],"mappings":";;;;;;;;;AAyBA;iBAAgB,eAAA,CACd,GAAA,EAAK,mBAAA,EACL,IAAA,EAAM,QAAA,EACN,MAAA,EAAQ,WAAA,IACR,IAAA,EAAM,sBAAA;;;;cC1BK,gCAAA;;cAEA,8BAAA;;iBAGG,yBAAA,CACd,YAAA,WACA,UAA2C;AAAA,UAK5B,gBAAA;EACf,SAAA,CAAU,KAAA,EAAO,WAAA,EAAa,EAAA,UAAY,EAAA;EAC1C,eAAA,EAAiB,EAAA,UAAY,EAAA,WAAa,aAAA;EAC1C,YAAA,CAAa,EAAA,UAAY,EAAA,UAAY,EAAA,UAAY,EAAA,WAAa,aAAA;EAC9D,YAAA,CAAa,IAAA,EAAM,aAAA,EAAe,EAAA,UAAY,EAAA;AAAA;AAAA,UAuK/B,oBAAA;EACf,KAAA;EACA,MAAA;EACA,UAAA,CAAW,IAAA,SAAa,gBAAgB;AAAA;;;AA1L1C;;iBAiOgB,wBAAA,CACd,SAAA,EAAW,WAAA,EACX,SAAA,UACA,UAAA,UACA,YAAA,GAAe,KAAA,UAAe,MAAA,aAAmB,oBAAA,EACjD,YAAA,WACA,UAAA,YACC,WAAA;;;;;;;iBCzNa,qBAAA,CACd,GAAA,EAAK,mBAAA,EACL,SAAA,EAAW,SAAA,EACX,aAAA,UACA,KAAA,UACA,MAAA,UACA,eAAA,GAAiB,SAAA;;;;iBCjBH,oBAAA,CACd,GAAA,EAAK,mBAAmB,EACxB,KAAA,UACA,MAAA,UACA,aAAA,UACA,WAAA,WACA,WAAA;;iBAoBc,wBAAA,CACd,MAAA;EACE,KAAA;EACA,MAAA;EACA,UAAA,CAAW,IAAA,SAAa,mBAAA;AAAA,GAE1B,KAAA,EAAO,WAAW,EAClB,KAAA,UACA,MAAA,UACA,aAAA;;;UCOe,qBAAA;EACf,KAAA,EAAO,SAAA;EACP,KAAA,EAAO,WAAW;AAAA;AAAA,UAGH,0BAAA;;EAEf,MAAA,GAAS,qBAAqB;EJ7BxB;EI+BN,IAAA;EJ7BM;EI+BN,QAAA;IACE,CAAA;IACA,CAAA;IACA,SAAA;IACA,UAAA;EAAA;AAAA;;;;;iBAQY,eAAA,CACd,GAAA,EAAK,mBAAA,EACL,KAAA,UACA,MAAA,UACA,MAAA,EAAQ,qBAAA,EACR,QAAA,GAAW,0BAAA;;iBAiFG,mBAAA,CACd,GAAA,EAAK,mBAAA,EACL,KAAA,UACA,MAAA,UACA,OAAA,GAAU,0BAA0B;;;UC9BrB,4BAAA;EACf,SAAA,EAAW,SAAA;EACX,aAAA;EACA,MAAA,EAAQ,SAAA;EACR,MAAA,EAAQ,WAAA;EACR,UAAA,GAAa,sBAAA;EACb,aAAA;AAAA;;;;;;;iBASc,qBAAA,CACd,GAAA,EAAK,mBAAA,EACL,KAAA,UACA,MAAA,UACA,OAAA,EAAS,4BAA4B"}

package/dist/canvas.js

@@ -0,0 +1,3 @@
+import { d as bakeEntityInfoSilhouette, l as ENTITY_INFO_SILHOUETTE_BLUR_PX, n as perfMark, p as entityInfoSilhouettePadPx, r as perfMeasure, t as nowMs, u as ENTITY_INFO_SILHOUETTE_RADIUS_PX } from "./profile-DR4i6HDp.js";
+import { a as drawCoordinateOverlay, i as drawSpacePlanet, n as drawTerrainBackground, o as blitWithTileCheckerboard, r as drawSpaceBackground, s as drawTileCheckerboard, t as executeDrawList } from "./execute-CRZV5zw1.js";
+export { ENTITY_INFO_SILHOUETTE_BLUR_PX, ENTITY_INFO_SILHOUETTE_RADIUS_PX, bakeEntityInfoSilhouette, blitWithTileCheckerboard, drawCoordinateOverlay, drawSpaceBackground, drawSpacePlanet, drawTerrainBackground, drawTileCheckerboard, entityInfoSilhouettePadPx, executeDrawList, nowMs, perfMark, perfMeasure };