badgecraft 0.3.0

package/dist/vue.d.cts

@@ -0,0 +1,115 @@
+import * as vue from 'vue';
+import { PropType, App } from 'vue';
+import { a as BadgeMode, i as MaterialInput, f as FrameShape, F as FrameOptions, R as ReliefOptions, E as EnvironmentInput, T as ToneMapping, h as Interaction, B as BadgeOptions, I as IdleAnimation } from './types-CHM3-ZZV.cjs';
+export { b as BadgecraftHandle, c as BrushDirection, d as EnvironmentLight, e as EnvironmentPreset, g as ImageEnvironment, M as Material, j as MaterialPreset, k as MaterialSlot, P as ProceduralEnvironment, l as ProfileShape, m as ReliefRole } from './types-CHM3-ZZV.cjs';
+
+/**
+ * Vue 3 binding for badgecraft.
+ *
+ * ```vue
+ * <Badgecraft svg="/award.svg" metal="gold" :size="200" @ready="..." />
+ * ```
+ */
+declare const Badgecraft: vue.DefineComponent<vue.ExtractPropTypes<{
+    svg: {
+        type: PropType<string | SVGElement>;
+        required: true;
+    };
+    mode: PropType<BadgeMode>;
+    metal: PropType<MaterialInput>;
+    enamel: PropType<MaterialInput>;
+    base: PropType<MaterialInput>;
+    accent: PropType<MaterialInput>;
+    color: StringConstructor;
+    frame: PropType<FrameShape | FrameOptions | null>;
+    rim: NumberConstructor;
+    outline: PropType<number | "auto">;
+    fillHoles: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    relief: PropType<ReliefOptions>;
+    environment: PropType<EnvironmentInput>;
+    environmentRotation: NumberConstructor;
+    exposure: NumberConstructor;
+    toneMapping: PropType<ToneMapping>;
+    interaction: PropType<Interaction>;
+    tiltMax: NumberConstructor;
+    pose: PropType<BadgeOptions["pose"]>;
+    idle: PropType<IdleAnimation>;
+    locked: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    lockedColor: StringConstructor;
+    shadow: NumberConstructor;
+    quality: PropType<number | "auto">;
+    padding: NumberConstructor;
+    /** Width and height (number = px). Default 160. */
+    size: {
+        type: (StringConstructor | NumberConstructor)[];
+        default: number;
+    };
+    /** Accessible label. */
+    alt: StringConstructor;
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    ready: () => true;
+    error: (error: Error) => boolean;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    svg: {
+        type: PropType<string | SVGElement>;
+        required: true;
+    };
+    mode: PropType<BadgeMode>;
+    metal: PropType<MaterialInput>;
+    enamel: PropType<MaterialInput>;
+    base: PropType<MaterialInput>;
+    accent: PropType<MaterialInput>;
+    color: StringConstructor;
+    frame: PropType<FrameShape | FrameOptions | null>;
+    rim: NumberConstructor;
+    outline: PropType<number | "auto">;
+    fillHoles: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    relief: PropType<ReliefOptions>;
+    environment: PropType<EnvironmentInput>;
+    environmentRotation: NumberConstructor;
+    exposure: NumberConstructor;
+    toneMapping: PropType<ToneMapping>;
+    interaction: PropType<Interaction>;
+    tiltMax: NumberConstructor;
+    pose: PropType<BadgeOptions["pose"]>;
+    idle: PropType<IdleAnimation>;
+    locked: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    lockedColor: StringConstructor;
+    shadow: NumberConstructor;
+    quality: PropType<number | "auto">;
+    padding: NumberConstructor;
+    /** Width and height (number = px). Default 160. */
+    size: {
+        type: (StringConstructor | NumberConstructor)[];
+        default: number;
+    };
+    /** Accessible label. */
+    alt: StringConstructor;
+}>> & Readonly<{
+    onReady?: (() => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+}>, {
+    fillHoles: boolean;
+    locked: boolean;
+    size: string | number;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+/** `app.use(BadgecraftPlugin)` registers `<Badgecraft>` globally. */
+declare const BadgecraftPlugin: {
+    install(app: App): void;
+};
+
+export { BadgeMode, BadgeOptions, Badgecraft, BadgecraftPlugin, EnvironmentInput, FrameOptions, FrameShape, IdleAnimation, Interaction, MaterialInput, ReliefOptions, ToneMapping, Badgecraft as default };

package/dist/vue.d.ts

@@ -0,0 +1,115 @@
+import * as vue from 'vue';
+import { PropType, App } from 'vue';
+import { a as BadgeMode, i as MaterialInput, f as FrameShape, F as FrameOptions, R as ReliefOptions, E as EnvironmentInput, T as ToneMapping, h as Interaction, B as BadgeOptions, I as IdleAnimation } from './types-CHM3-ZZV.js';
+export { b as BadgecraftHandle, c as BrushDirection, d as EnvironmentLight, e as EnvironmentPreset, g as ImageEnvironment, M as Material, j as MaterialPreset, k as MaterialSlot, P as ProceduralEnvironment, l as ProfileShape, m as ReliefRole } from './types-CHM3-ZZV.js';
+
+/**
+ * Vue 3 binding for badgecraft.
+ *
+ * ```vue
+ * <Badgecraft svg="/award.svg" metal="gold" :size="200" @ready="..." />
+ * ```
+ */
+declare const Badgecraft: vue.DefineComponent<vue.ExtractPropTypes<{
+    svg: {
+        type: PropType<string | SVGElement>;
+        required: true;
+    };
+    mode: PropType<BadgeMode>;
+    metal: PropType<MaterialInput>;
+    enamel: PropType<MaterialInput>;
+    base: PropType<MaterialInput>;
+    accent: PropType<MaterialInput>;
+    color: StringConstructor;
+    frame: PropType<FrameShape | FrameOptions | null>;
+    rim: NumberConstructor;
+    outline: PropType<number | "auto">;
+    fillHoles: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    relief: PropType<ReliefOptions>;
+    environment: PropType<EnvironmentInput>;
+    environmentRotation: NumberConstructor;
+    exposure: NumberConstructor;
+    toneMapping: PropType<ToneMapping>;
+    interaction: PropType<Interaction>;
+    tiltMax: NumberConstructor;
+    pose: PropType<BadgeOptions["pose"]>;
+    idle: PropType<IdleAnimation>;
+    locked: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    lockedColor: StringConstructor;
+    shadow: NumberConstructor;
+    quality: PropType<number | "auto">;
+    padding: NumberConstructor;
+    /** Width and height (number = px). Default 160. */
+    size: {
+        type: (StringConstructor | NumberConstructor)[];
+        default: number;
+    };
+    /** Accessible label. */
+    alt: StringConstructor;
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    ready: () => true;
+    error: (error: Error) => boolean;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    svg: {
+        type: PropType<string | SVGElement>;
+        required: true;
+    };
+    mode: PropType<BadgeMode>;
+    metal: PropType<MaterialInput>;
+    enamel: PropType<MaterialInput>;
+    base: PropType<MaterialInput>;
+    accent: PropType<MaterialInput>;
+    color: StringConstructor;
+    frame: PropType<FrameShape | FrameOptions | null>;
+    rim: NumberConstructor;
+    outline: PropType<number | "auto">;
+    fillHoles: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    relief: PropType<ReliefOptions>;
+    environment: PropType<EnvironmentInput>;
+    environmentRotation: NumberConstructor;
+    exposure: NumberConstructor;
+    toneMapping: PropType<ToneMapping>;
+    interaction: PropType<Interaction>;
+    tiltMax: NumberConstructor;
+    pose: PropType<BadgeOptions["pose"]>;
+    idle: PropType<IdleAnimation>;
+    locked: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    lockedColor: StringConstructor;
+    shadow: NumberConstructor;
+    quality: PropType<number | "auto">;
+    padding: NumberConstructor;
+    /** Width and height (number = px). Default 160. */
+    size: {
+        type: (StringConstructor | NumberConstructor)[];
+        default: number;
+    };
+    /** Accessible label. */
+    alt: StringConstructor;
+}>> & Readonly<{
+    onReady?: (() => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+}>, {
+    fillHoles: boolean;
+    locked: boolean;
+    size: string | number;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+/** `app.use(BadgecraftPlugin)` registers `<Badgecraft>` globally. */
+declare const BadgecraftPlugin: {
+    install(app: App): void;
+};
+
+export { BadgeMode, BadgeOptions, Badgecraft, BadgecraftPlugin, EnvironmentInput, FrameOptions, FrameShape, IdleAnimation, Interaction, MaterialInput, ReliefOptions, ToneMapping, Badgecraft as default };

package/dist/vue.js

@@ -0,0 +1,87 @@
+import { cssSize, pickOptions } from './chunk-3OMN635U.js';
+import { Badgecraft } from './chunk-RRYBMB25.js';
+import { defineComponent, ref, onMounted, watch, onBeforeUnmount, h } from 'vue';
+
+var material = [String, Object];
+var bool = { type: Boolean, default: void 0 };
+var Badgecraft2 = defineComponent({
+  name: "Badgecraft",
+  props: {
+    svg: { type: [String, Object], required: true },
+    mode: String,
+    metal: material,
+    enamel: material,
+    base: material,
+    accent: material,
+    color: String,
+    frame: [String, Object],
+    rim: Number,
+    outline: [Number, String],
+    fillHoles: bool,
+    relief: Object,
+    environment: [String, Object],
+    environmentRotation: Number,
+    exposure: Number,
+    toneMapping: String,
+    interaction: String,
+    tiltMax: Number,
+    pose: Object,
+    idle: String,
+    locked: bool,
+    lockedColor: String,
+    shadow: Number,
+    quality: [Number, String],
+    padding: Number,
+    /** Width and height (number = px). Default 160. */
+    size: { type: [Number, String], default: 160 },
+    /** Accessible label. */
+    alt: String
+  },
+  emits: {
+    ready: () => true,
+    error: (error) => error instanceof Error
+  },
+  setup(props, { emit, expose }) {
+    const host = ref();
+    let badge = null;
+    const options = () => ({
+      ...pickOptions(props),
+      onReady: () => emit("ready"),
+      onError: (error) => emit("error", error)
+    });
+    onMounted(() => {
+      badge = new Badgecraft(host.value, options());
+    });
+    watch(options, (next) => badge?.setOptions(next), { deep: true });
+    onBeforeUnmount(() => {
+      badge?.destroy();
+      badge = null;
+    });
+    expose({
+      spin: (turns) => badge?.spin(turns),
+      glint: () => badge?.glint(),
+      toDataURL: (type, quality) => badge?.toDataURL(type, quality) ?? "",
+      toBlob: (type, quality) => badge?.toBlob(type, quality) ?? Promise.resolve(null),
+      instance: () => badge
+    });
+    return () => {
+      const dim = cssSize(props.size);
+      return h("div", {
+        ref: host,
+        role: "img",
+        "aria-label": props.alt,
+        style: { display: "inline-block", position: "relative", width: dim, height: dim }
+      });
+    };
+  }
+});
+var BadgecraftPlugin = {
+  install(app) {
+    app.component("Badgecraft", Badgecraft2);
+  }
+};
+var vue_default = Badgecraft2;
+
+export { Badgecraft2 as Badgecraft, BadgecraftPlugin, vue_default as default };
+//# sourceMappingURL=vue.js.map
+//# sourceMappingURL=vue.js.map

package/dist/vue.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vue/index.ts"],"names":["Badgecraft"],"mappings":"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","file":"vue.js","sourcesContent":["import {\n  defineComponent,\n  h,\n  onBeforeUnmount,\n  onMounted,\n  ref,\n  watch,\n  type App,\n  type PropType,\n} from 'vue'\nimport { Badgecraft as Badge } from '../badge'\nimport { cssSize, pickOptions } from '../option-keys'\nimport type {\n  BadgeMode,\n  BadgeOptions,\n  EnvironmentInput,\n  FrameOptions,\n  FrameShape,\n  IdleAnimation,\n  Interaction,\n  MaterialInput,\n  ReliefOptions,\n  ToneMapping,\n} from '../types'\n\nexport type * from '../types'\n\nconst material = [String, Object] as PropType<MaterialInput>\n// Booleans default to undefined so the library's own defaults apply.\nconst bool = { type: Boolean, default: undefined }\n\n/**\n * Vue 3 binding for badgecraft.\n *\n * ```vue\n * <Badgecraft svg=\"/award.svg\" metal=\"gold\" :size=\"200\" @ready=\"...\" />\n * ```\n */\nexport const Badgecraft = defineComponent({\n  name: 'Badgecraft',\n  props: {\n    svg: { type: [String, Object] as PropType<string | SVGElement>, required: true },\n    mode: String as PropType<BadgeMode>,\n    metal: material,\n    enamel: material,\n    base: material,\n    accent: material,\n    color: String,\n    frame: [String, Object] as PropType<FrameShape | FrameOptions | null>,\n    rim: Number,\n    outline: [Number, String] as PropType<number | 'auto'>,\n    fillHoles: bool,\n    relief: Object as PropType<ReliefOptions>,\n    environment: [String, Object] as PropType<EnvironmentInput>,\n    environmentRotation: Number,\n    exposure: Number,\n    toneMapping: String as PropType<ToneMapping>,\n    interaction: String as PropType<Interaction>,\n    tiltMax: Number,\n    pose: Object as PropType<BadgeOptions['pose']>,\n    idle: String as PropType<IdleAnimation>,\n    locked: bool,\n    lockedColor: String,\n    shadow: Number,\n    quality: [Number, String] as PropType<number | 'auto'>,\n    padding: Number,\n    /** Width and height (number = px). Default 160. */\n    size: { type: [Number, String], default: 160 },\n    /** Accessible label. */\n    alt: String,\n  },\n  emits: {\n    ready: () => true,\n    error: (error: Error) => error instanceof Error,\n  },\n  setup(props, { emit, expose }) {\n    const host = ref<HTMLDivElement>()\n    let badge: Badge | null = null\n\n    const options = (): BadgeOptions => ({\n      ...pickOptions(props as unknown as Record<string, unknown>),\n      onReady: () => emit('ready'),\n      onError: (error: Error) => emit('error', error),\n    })\n\n    onMounted(() => {\n      badge = new Badge(host.value!, options())\n    })\n    watch(options, (next) => badge?.setOptions(next), { deep: true })\n    onBeforeUnmount(() => {\n      badge?.destroy()\n      badge = null\n    })\n\n    expose({\n      spin: (turns?: number) => badge?.spin(turns),\n      glint: () => badge?.glint(),\n      toDataURL: (type?: string, quality?: number) => badge?.toDataURL(type, quality) ?? '',\n      toBlob: (type?: string, quality?: number) => badge?.toBlob(type, quality) ?? Promise.resolve(null),\n      instance: () => badge,\n    })\n\n    return () => {\n      const dim = cssSize(props.size)\n      return h('div', {\n        ref: host,\n        role: 'img',\n        'aria-label': props.alt,\n        style: { display: 'inline-block', position: 'relative', width: dim, height: dim },\n      })\n    }\n  },\n})\n\n/** `app.use(BadgecraftPlugin)` registers `<Badgecraft>` globally. */\nexport const BadgecraftPlugin = {\n  install(app: App) {\n    app.component('Badgecraft', Badgecraft)\n  },\n}\n\nexport default Badgecraft\n"]}

package/docs/cli.md

@@ -0,0 +1,146 @@
+# CLI, local Studio, and Node rendering
+
+## Interactive web Studio
+
+```sh
+npx badgecraft studio
+npx badgecraft studio --open
+npx badgecraft studio --port 8080
+```
+
+Open the printed URL to upload, drop, or paste an SVG, adjust materials and
+lighting, export PNG images, or copy code for a website. `--open` opens Google
+Chrome; you can also open the URL yourself in a WebGL2-capable browser. Node.js
+22+ is required. No source checkout or development dependencies are needed.
+
+The app is bundled in the package and works offline after installation. SVGs
+are read by the browser; the local server never receives them or serves your
+working directory. Valid drafts are saved in that browser's local storage.
+The hosted version is at https://parthjadhav.github.io/badgecraft/studio.html.
+
+The server listens on `127.0.0.1`, port 5199. If the default is occupied, it picks
+an available port and prints the URL. An explicitly requested occupied port
+fails with an explanation. Use `--port 0` to always pick an available port.
+Press Ctrl+C to stop. Use a consistent port to keep using the same saved draft
+(browser storage is tied to the URL's origin).
+
+Studio accepts SVGs up to 1 MiB and exports PNG at 512, 1024, or 2048 pixels.
+For WebP/JPEG or automation, use image conversion below.
+
+## Image conversion
+
+The CLI turns a self-contained SVG into a static badge image with the same
+WebGL2 renderer as the browser library. It runs locally; it does not upload
+artwork or fetch remote assets.
+
+## Install
+
+Use Node.js 22 or newer and install [Google Chrome](https://www.google.com/chrome/).
+Chrome is required only for image exports from Node or the CLI. Browser components
+use the visitor's WebGL2 browser and do not need a local Chrome installation.
+
+```sh
+# Run without a global installation
+npx badgecraft icon.svg --output badge.png
+
+# Or install globally
+npm install -g badgecraft
+badgecraft icon.svg --output badge.png
+```
+
+`playwright-core` controls your installed Chrome; installing this package does
+not download a browser or run an installation script. macOS, Windows, and Linux
+with Chrome are supported. On a minimal Linux machine, install Chrome's system
+libraries too. `npx playwright-core install chrome` is an alternative Chrome
+installer and may need administrator access.
+
+If Chrome is in a nonstandard location, pass `--chrome-path /path/to/chrome` or
+set `BADGECRAFT_CHROME_PATH`. Chrome runs headlessly with software WebGL, so
+no display server or dedicated GPU is needed. In containers where Chrome's
+sandbox cannot run, configure the container for Chrome sandboxing or explicitly
+pass `--no-sandbox`. Sandbox disabling is never the default.
+
+## Examples
+
+```sh
+# Creates icon.badge.png next to the SVG
+badgecraft icon.svg
+
+# A silver badge on a hexagonal backplate
+badgecraft icon.svg -o silver.png --metal silver --frame hexagon --size 1024
+
+# Copper under warm lighting
+badgecraft icon.svg -o copper.webp --metal copper --environment sunset
+
+# Opaque JPEG with a custom background and camera pose
+badgecraft icon.svg -o badge.jpg --background '#17191e' --yaw=-18 --pitch=-10
+
+# Pipe SVG in, pipe PNG out (diagnostics go to stderr)
+cat icon.svg | badgecraft - --output - > badge.png
+
+# Discover all 23 materials or view all options
+badgecraft --list-presets
+badgecraft --help
+```
+
+Use `--flag=-10` for negative numeric values. Values with spaces must be quoted.
+The output extension selects PNG, WebP, or JPEG; `--format` selects the format
+when stdout or a filename without an extension is used. `--format` and a filename
+extension must agree. PNG and WebP have transparent backgrounds by default.
+JPEG always has an opaque background (white unless customized).
+
+Existing files are protected unless `--force` is supplied. Parent directories
+are created automatically. A conversion error exits with status 1, writes an
+explanation to stderr, and does not create a new output file.
+
+Image size is square and limited to 16–2048 pixels. `--quality` controls the relief
+map resolution (64–2048); `--image-quality` controls WebP/JPEG compression (0–1).
+The render uses a fixed pose with animation and pointer interaction disabled.
+Software WebGL keeps rendering portable; byte-identical output across different
+Chrome versions and operating systems is not guaranteed.
+
+## Input and output boundaries
+
+Input must be an SVG file path or SVG markup on stdin, up to 10 MiB. Paths, fills,
+strokes, gradients, masks, clip paths, inline styles, and embedded images are
+supported by the underlying renderer. Embed images as data URLs and convert text
+to paths for consistent results on machines with different installed fonts.
+
+SVG scripts, event handlers, embedded HTML, and animations are removed. External
+resources are blocked, including CSS imports, fonts, images, and image-based
+lighting. CLI lighting accepts the five built-in environments. Conversions work
+offline once the npm package and Chrome are installed.
+
+The result is a raster image, not an editable vector SVG. Use the browser exports
+for interactive badges. A missing WebGL2 context fails explicitly instead of
+silently exporting the original flat SVG.
+
+## Node API
+
+```js
+import { readFile, writeFile } from 'node:fs/promises'
+import { renderBadge } from 'badgecraft/node'
+
+const svg = await readFile('icon.svg', 'utf8')
+const image = await renderBadge(svg, {
+  size: 1024,
+  format: 'png',
+  metal: { preset: 'gold', roughness: 0.25 },
+  frame: { shape: 'circle', padding: 0.2 },
+  relief: { depth: 0.06 },
+  environment: 'studio',
+  pose: { pitch: -5, yaw: -12 },
+})
+await writeFile('badge.png', image)
+```
+
+`renderBadge(svg, options)` returns a `Promise<Buffer>`. Its `RenderOptions` type
+includes the library's static badge options, plus `size`, `format`, `background`,
+`imageQuality`, `timeout`, `executablePath`, and `sandbox`. The SVG argument must
+be markup, not a URL. The Node entry is ESM; CommonJS callers can use
+`await import('badgecraft/node')`. Import only the browser entry in frontend
+bundles; Chrome and Node code are isolated in `badgecraft/node`.
+
+Each call creates and closes an isolated Chrome process. For a batch, process
+files sequentially or keep concurrency low to bound memory use. `timeout`
+defaults to 60 seconds for startup and separately 60 seconds for rendering.

package/docs/performance.md

@@ -0,0 +1,151 @@
+# Profiling and performance comparisons
+
+Use `pnpm perf:profile artifacts/profile` for a current-source run. The harness
+uses installed Google Chrome and saves raw samples, JSON summaries, and Chrome
+CPU profiles. Open `.cpuprofile` files in Chrome DevTools' Performance panel.
+It is development-only: published library code contains no profiling hooks.
+
+## Measured change: mesh clipping fast paths
+
+The first diagnostic profiles identified main-thread polygon clipping and
+allocation/GC as a startup bottleneck: seven gallery mesh builds plus uploads
+occupied 65.7 ms, with only 0.7 ms in texture upload calls. Cells wholly outside
+the silhouette now skip clipping; strictly positive interior cells emit the
+same two triangles directly. Contour cells, zero-distance vertices, and map
+borders retain the existing clipping/wall construction path.
+
+A subsequent diagnostic run measured 33.4 ms for those same seven mesh builds
+plus uploads (49% less synchronous wall time). These are diagnostic observations,
+not six-run component benchmarks. Uninstrumented paired timings confirm the
+small-gallery startup benefit in **all six pairs**, ranging from 6.6% to 13.4%.
+
+| Workload | Ready p50 before | Ready p50 after | Synchronized redraw p50 before | After |
+| --- | ---: | ---: | ---: | ---: |
+| One 320px badge | 122.7 ms | 117.3 ms | 3.28 ms | 3.53 ms |
+| Nine 110px badges | 165.4 ms | 148.9 ms | 9.48 ms | 9.68 ms |
+| 57 110px badges | 168.7 ms | 163.1 ms | 33.07 ms | 32.72 ms |
+| Nine 640px badges | 703.9 ms | 708.4 ms | 13.13 ms | 12.87 ms |
+
+These are nearest-rank p50 values across six runs, on Chrome 154.0.8037.57,
+ANGLE Metal, Apple M5 Pro. Redraw figures summarize each run's p50. No redraw
+speedup is claimed: only mesh construction changed. The large workload remains
+worker-bake dominated and showed no reliable readiness benefit. All outliers
+are retained, including candidate startup times of 210.4 ms for 57 badges and
+1186.0 ms for the large workload in the first pair. Inspect the raw paired data
+rather than assuming that a single summary quantile proves a universal gain.
+
+Evidence is saved locally in `artifacts/profile-ab/report.json`, with CPU
+profiles and event/query records in the same directory. Discovery captures are
+in `artifacts/profile-discovery` and `artifacts/profile-instrumented`; the former
+revealed the emulated-DPR gap and predates the worker execution timer. The full
+source reference is `artifacts/profile-baseline/src`.
+
+All **108 raw RGBA captures are byte-for-byte identical** between baseline and
+candidate at the verified backing dimensions. Six reference mesh cases also
+preserve every vertex/index byte and the face/wall split. All 23 unit tests,
+TypeScript checks, package builds, and the standalone Chrome interaction suite
+pass. Captures are in `artifacts/mesh-quality-before` and
+`artifacts/mesh-quality-after`.
+
+## Repeatable A/B measurement
+
+Save a complete source snapshot **before** editing library code:
+
+```sh
+pnpm build:worker
+mkdir -p artifacts/baseline
+cp -R src artifacts/baseline/
+# Make the optimization, then:
+pnpm perf:profile artifacts/comparison --baseline artifacts/baseline
+```
+
+The snapshot includes the generated worker bundle. Each server resolves all
+library source modules from its own revision; the same fixture drives both.
+Do not edit either source tree while a run is active. `PROFILE_ROUNDS` overrides
+the default six rounds; use one only for harness smoke tests, not speed claims.
+Run browser workloads sequentially and avoid other GPU-intensive work.
+
+The harness warms module transforms and shader disk caches for both variants,
+then alternates baseline/candidate order every round. Every measured case gets
+a fresh browser context and fresh library/worker caches. Workloads are one
+320px badge, nine 110px badges, 57 110px badges, and nine 640px badges. The many-
+badge case repeats the nine gallery styles (including locked badges), so it is
+not identical to the older benchmark's 48 added badges. Actual canvas dimensions
+and map resolutions are recorded and checked, along with GPU identity.
+
+Readiness is timed in-page from host creation through all `ready` promises;
+it excludes module download, Vite transformation, and automation polling.
+It means the library has baked and submitted the first image, not that a physical
+display has presented it. It is not a cold network-navigation measurement.
+
+Each uninstrumented workload records 60 frames after 15 warm-up frames:
+
+- `submitMs`: synchronous wall time for all badge draw calls, including canvas
+  copies and any implicit driver/browser waits. It is not GPU execution time.
+- `rafIntervalMs`: actual animation callback cadence, including browser scheduling.
+  This is measured separately from draw submission and is not inferred from it.
+- A separate synchronized pass records 45 frames after five warm-ups, with draw
+  time, a one-pixel GPU readback wait, and their total stored separately. This
+  stress measurement is not presented as interactive FPS and does not include
+  physical display presentation or guarantee completion of 2D compositing.
+
+Reports retain every sample, nearest-rank per-run quantiles, across-run ranges, and paired
+percentage changes. Negative changes mean improvement. Six rounds do not prove
+universal speedups; inspect outliers and the individual paired changes. Metadata
+includes Chrome version, OS/CPU, workload settings, and SHA-256 hashes of both
+source trees. Different machines or browser builds require a new paired run.
+
+## Diagnostic profiling
+
+Diagnostic runs happen **after** timing runs. They use method wrappers, a
+main-thread CDP sampling profiler, and asynchronous
+[WebGL timer queries](https://registry.khronos.org/webgl/extensions/EXT_disjoint_timer_query_webgl2/).
+Their numbers identify bottlenecks; the extra queries/wrappers can change GPU
+batching and must not be used as the end-to-end speed comparison.
+
+Recorded phases include renderer initialization, environment preparation,
+mesh construction plus upload, texture upload, material uniforms, canvas copies,
+and draw submission. Durations ending in `cpuWall` measure synchronous API wall
+time, which can include waiting. Nested phases overlap: do not sum them as if
+they were exclusive CPU categories. Environment-ready time is submission wall
+time, not completion of environment filtering on the GPU.
+
+A diagnostic-only worker shim records synchronous bake execution inside each
+worker. A listener registered before the library's completion handler separately
+records round-trip time, including queueing, transport and delivery. The shim
+adds startup overhead, so production readiness comes from uninstrumented runs.
+Worker jobs overlap; summing round-trip times does not give page startup time.
+Main-thread CPU profiles do not represent worker CPU stacks.
+
+GPU query results distinguish environment, relief, and shadow passes. Results
+are read only after yielding; disjoint results are discarded and unsupported or
+timed-out queries are reported explicitly. Query objects are deleted. These
+queries cover WebGL passes, not Canvas2D copying/compositing. CDP metrics also
+record heap and layout data; a single heap snapshot metric is not a leak test.
+Long tasks are assigned to the phase in which they started.
+
+## Quality protection
+
+```sh
+BADGE_BASELINE_DIR=artifacts/baseline pnpm test:quality artifacts/reference
+pnpm test:quality artifacts/current artifacts/reference
+pnpm test
+pnpm typecheck
+pnpm test:browser
+pnpm build
+```
+
+The quality harness supports complete `src/` snapshots as well as the older
+four-file rendering snapshot. It captures nine badge styles at actual backing
+sizes of 110, 400, and 640 pixels from four poses (108 images). It checks backing
+dimensions rather than trusting emulated DPR: Chrome's emulated 2× DPR did not
+increase `devicePixelContentBoxSize` in the original capture harness. These
+larger backing sizes exercise high-resolution rendering without claiming to
+test native display scaling behavior.
+
+Pixel thresholds, GPU/browser compatibility, blank-image checks and failures
+are recorded by `scripts/quality-check.mjs`. PNGs remain available for visual
+inspection. Mesh compatibility tests additionally hash complete vertex/index
+buffers from the pre-optimization implementation, including contours on grid
+vertices, holes, islands, map boundaries, and a dense mesh. Never regenerate
+those expected values merely to silence a failed optimization test.