badgecraft 0.3.0

package/docs/render-quality.md

@@ -0,0 +1,220 @@
+# Rendering quality verification
+
+For phase-level CPU/worker/GPU profiling and alternating full-source A/B runs,
+see [Performance measurement](performance.md). The updated quality harness
+verifies actual backing dimensions at 110, 400, and 640 pixels. Earlier captures
+configured with emulated 2× DPR still had 1× backing canvases in Chrome, so they
+did not establish high-DPI coverage; the new larger-backing captures address
+that rendering-test gap without claiming native display-scaling coverage.
+
+## Tilted texture detail (2026-09-28)
+
+Badge surface, colour, and material-weight mipmaps now use anisotropic filtering,
+capped at 2× or the device limit. This retains more detail along the uncompressed
+axis when a badge tilts. The optional extension is reacquired after context
+restoration; devices without it keep trilinear filtering. Environment filtering,
+map sizes, geometry, supersampling, and draw counts stay the same. The cap bounds
+texture sampling cost without allocating additional textures or render passes.
+The texture parameters follow the [Khronos extension specification](https://registry.khronos.org/webgl/extensions/EXT_texture_filter_anisotropic/).
+
+The dedicated reference check renders eight material styles at 160px, with yaw
+angles of 45°, 65°, and 80°. It compares 1× and capped 2× filtering to the same
+baked maps and geometry rendered into a 1280px canvas and downsampled to 160px.
+Premultiplied RGBA mean squared error fell by **14.1% overall**, with improvements
+in all 24 cases on Chrome/ANGLE Metal. This measures agreement with a higher
+resolution rendering of this renderer, not physical ground truth or temporal
+stability. The general quality harness also captured 108 nonblank images at
+110, 400, and 640 pixels across front, tilted, grazing, and back poses.
+
+The initial 4× candidate was tested with three-round and six-round full-source
+A/B runs. Both had substantial timing drift. A shorter same-context comparison
+then found a repeatable cost on small tilted badges, so the final cap was reduced
+to 2×. The exploratory reports remain in `profile/`, `profile-confirm/`, and
+`filter-cost.json`; they describe the rejected 4× candidate.
+
+For the final 2× cap, a same-context test alternated filtering modes for four
+rounds, rendering nine badges per frame. Each run used five warm-up frames and
+25 measured frames, a ±5° yaw sweep, and GPU readback. Median redraw costs:
+
+| Size / centre pose | Trilinear | Capped 2× |
+| --- | ---: | ---: |
+| 110px / 0° yaw | 11.45 ms | 11.35 ms |
+| 110px / 65° yaw | 8.65 ms | 8.65 ms |
+| 640px / 0° yaw | 12.05 ms | 13.15 ms |
+| 640px / 65° yaw | 13.40 ms | 13.00 ms |
+
+The largest observed median increase was 1.10 ms for nine large near-front
+badges; tilted cases were flat or faster. These local Chrome 154 / Apple M5 Pro
+measurements remain noisy and do not establish performance on mobile GPUs.
+Raw runs and the executable probe are saved as `filter-cost-2x.json` and
+`filter-cost.mjs` in the artifact directory. This lower cap retains most of the
+4× candidate's reference-error improvement while bounding texture sampling.
+
+Validation: 23 unit tests, TypeScript, ESM/CommonJS/declaration builds, all Chrome
+interaction checks (including the unavailable-extension fallback), 108 image
+captures, and all 24 higher-resolution reference cases passed.
+
+Reproduce the targeted quality measurement:
+
+```sh
+node scripts/filter-quality.mjs artifacts/filter-quality
+```
+
+Local before/after images, the source snapshot, and measurement reports are in
+`artifacts/render-quality/`. `comparison.png` shows matching tilted and grazing
+views. The existing pixel-equivalence thresholds are intentionally not used to
+accept this appearance change; the earlier captures remain intact.
+
+## Shadow geometry and repeatable regression checks (2026-09-28)
+
+The planar shadow now uses two triangles instead of a 192 × 192 grid
+(73,728 triangles). Its shader, texture, projection, and perspective-correct
+UV interpolation are unchanged. This removes redundant vertex processing
+without reducing badge relief geometry, texture resolution, supersampling,
+or material shading. Shadow vertex/index storage falls from 740,360 to 44
+bytes per shared renderer.
+
+Five sequential Chrome runs per version on the Apple M5 Pro, using a saved
+renderer source snapshot and the same instrumented harness:
+
+| Measurement (median across runs) | Before | After |
+| --- | ---: | ---: |
+| Forced redraw of all 57 badges | 35.3 ms | 32.5 ms |
+| 95th-percentile redraw | 39.2 ms | 34.1 ms |
+| Submitted triangles per redraw | 12,185,282 | 8,056,626 |
+| Indexed draw calls per redraw | 225 | 225 |
+| Observed gallery readiness | 207.4 ms | 213.5 ms |
+| Add 48 badges | 46.3 ms | 48.4 ms |
+| WebGL contexts | 1 | 1 |
+| Indexed draws during 300 ms idle window | 0 | 0 |
+
+The redraw median improved by 7.9%, with 33.9% fewer submitted triangles.
+Loading measurements were slightly slower; this change targets rendering,
+not loading. Both versions had timing outliers, so these are local observations,
+not universal performance guarantees. Full samples are saved locally in
+`artifacts/performance-before.json` and `artifacts/performance-after.json`.
+The benchmark reports page-wide long tasks (including forced synchronous
+redraws), draw counts, submitted triangles, workload settings, Chrome version,
+and GPU identity. It fails on browser errors, extra contexts, or idle drawing.
+Instrumentation runs only in the development harness and adds no library cost.
+
+That quality run compared 108 canvas captures: nine styles, 110px/1×,
+200px with emulated 2× (actually 200px backing), and 320px/1×, each viewed from
+the front, tilted, grazing, and back.
+All comparisons passed. The worst mean premultiplied RGBA difference was
+0.00025 on a 0–255 scale. Comparisons use premultiplied colour to avoid treating
+invisible RGB changes in transparent pixels as visible errors. Each image must
+have mean error ≤ 0.1, no more than 0.1% of pixels differing by over 2 levels,
+and no channel difference over 16. These tolerances permit GPU interpolation
+rounding, not intentional appearance changes. The harness also rejects blank
+images, WebGL errors, browser errors, dimension changes, and mismatched Chrome
+versions or GPU identities when present in the reference.
+
+Capture a reference **before** a rendering edit, then compare afterwards:
+
+```sh
+pnpm test:quality artifacts/quality-before
+pnpm test:quality artifacts/quality-after artifacts/quality-before
+```
+
+Each directory contains PNGs for inspection, raw RGBA buffers, and a JSON
+report. Keep the reference separate from the output. Both this check and
+`pnpm benchmark` accept `BADGE_BASELINE_DIR` containing `renderer.ts`,
+`shaders.ts`, `environment.ts`, and `materials.ts` from the earlier revision.
+This source override covers only those four modules; other source changes
+require captures from the actual baseline checkout. The capture harness uses
+internal development fields to force visibility and pose; it is not a public API.
+Quality references should be recaptured deliberately on the same Chrome/GPU,
+never silently updated to make a failed comparison pass.
+
+Validation: 17 unit tests, TypeScript, package builds, the Chrome interaction
+suite, and all 108 pixel comparisons. One hover assertion failed while the
+interaction and capture suites ran concurrently; the complete standalone
+interaction rerun passed. Run browser workloads sequentially for performance
+measurements. No public API or intended appearance change.
+
+## Supersampled anti-aliasing
+
+The renderer now shades at twice the output width and height, then downsamples
+with high-quality canvas filtering. This supplements MSAA with four shading
+samples per output pixel, smoothing internal metal wires and highlights as
+well as the silhouette. Brushing, flakes, and specular normal filtering retain
+the final output pixel footprint so supersampling does not reintroduce shimmer.
+The supersampled longest dimension is capped at 2048 pixels (or the GPU's lower
+renderbuffer limit); large canvases progressively receive less supersampling.
+Public canvas and PNG export dimensions are unchanged. Map resolution and
+geometry are unchanged by this pass.
+
+Chrome screenshots: `artifacts/aa-before.png` and `artifacts/aa-after.png`.
+All 17 unit tests, browser checks, TypeScript checks, and package builds pass.
+Five local benchmark runs measured 36.8 ms median redraw and 40.8 ms median
+95th-percentile redraw for all 57 badges, versus the earlier geometry run's
+30.1 ms and 31.2 ms. Gallery readiness was 225.9 ms, adding 48 badges took
+48.6 ms, and the renderer still used one context with no settled draw calls.
+These runs are local observations rather than a controlled performance guarantee.
+
+
+## Contour geometry and wire refinement
+
+The relief now uses a per-artwork mesh clipped to the baked silhouette. Shared,
+subpixel-refined contour intersections weld adjacent triangles; an explicit
+metal side wall joins the front and back. This removes the torn, sawtooth edge
+that appeared when a displaced square grid was discarded at grazing angles.
+Silhouette coverage comes from WebGL multisampling instead of a second alpha
+cut through the front/back seam. Mesh subdivisions follow map resolution, up to
+384 per axis; the previous shared relief grid used 192 at every size. Shadow
+rendering retains its shared grid. Geometry is cached with the artwork textures
+and released with them, including on context restoration.
+
+Wire-radius estimates are smoothed at a consistent scale relative to artwork
+size, reducing ripples in ring highlights without blurring SVG colour masks.
+No public options changed. Each unlocked medal adds one side-wall draw, and
+cached meshes use additional GPU memory; small gallery badges still share one
+WebGL context and stop drawing when settled.
+
+Validation: 17 unit tests, including closed-mesh topology for circles, holes,
+disconnected islands, exact-grid contours and map boundaries; Chrome browser
+checks; TypeScript; ESM/CommonJS/declaration builds. Front and grazing-angle
+gold/silver screenshots were inspected. Local evidence is in
+`artifacts/edge-before.png`, `artifacts/edge-after.png`,
+`artifacts/front-smoothed.png`, and `artifacts/silver-back.png`.
+
+Five Chrome runs of the geometry change measured medians of 221.2 ms gallery
+readiness, 48.9 ms to add 48 badges, 30.1 ms for a forced redraw of all 57,
+and 31.2 ms for the 95th-percentile redraw. These are local measurements on the
+same machine described below, not a controlled speedup claim. The wire-radius
+filter was adjusted after this benchmark; it affects baking, not draw cost.
+
+## Earlier material and lighting work
+
+The studio preset now uses more defined softboxes, with dark gaps between them to give polished metal contrast. Gold is slightly smoother; onyx is darker and cooler. Enamel retains its SVG colour beneath a separate clearcoat reflection.
+
+The shader accounts for the dielectric index contrast beneath lacquer, attenuates light crossing the coat twice, and lights broad multiple scattering with diffuse irradiance. Normal derivatives soften highlights smaller than a pixel. Flakes blend into the surface instead of adding unbounded light, and converge toward a smooth reflection when too small to resolve. Layering and filtering follow the principles described in [Filament's material model](https://google.github.io/filament/main/filament.html).
+
+The mirror environment level now resamples directly instead of running the GGX convolution. That material-only revision left mesh density, map resolution, texture count, draw passes, worker baking, caches, and idle scheduling unchanged. The contour geometry revision above supersedes its mesh and draw-pass counts.
+
+## Measured performance
+
+Five sequential runs per version in Google Chrome 154.0.8037.57, ANGLE Metal on Apple M5 Pro. The table contains medians across runs. Nine 110px gallery badges load first; 48 more are added. Redraw timing forces all 57 badges to rotate, includes a synchronous GPU readback, and measures 45 frames after five warm-up frames.
+
+| Measurement | Before | After |
+| --- | ---: | ---: |
+| Gallery readiness | 254.7 ms | 240.7 ms |
+| Add 48 badges | 48.6 ms | 48.7 ms |
+| Redraw all 57 badges | 32.2 ms | 31.8 ms |
+| 95th-percentile redraw | 37.8 ms | 34.0 ms |
+| WebGL contexts | 1 | 1 |
+
+These local measurements show comparable performance, not a universal speed guarantee. One after-run had a 59.6 ms redraw median; the other four were 31.6–31.8 ms. The workload deliberately redraws every badge and forces synchronization; it is not the cost of hovering a single badge. Static badges make zero draw calls after settling.
+
+Run `pnpm benchmark` to repeat. `node scripts/benchmark.mjs output.json` also saves the results. For an A/B comparison, `BADGE_BASELINE_DIR` can point to a directory containing the earlier `shaders.ts`, `renderer.ts`, `environment.ts`, and `materials.ts`; the harness serves those files without modifying working sources.
+
+## Verification
+
+- Unit tests and TypeScript checks pass.
+- Chrome checks cover gallery rendering, hover/drag restoration, material and environment updates, HDR loading, PNG export, React, Vue, custom elements, and the non-WebGL fallback.
+- Browser instrumentation confirms a single WebGL context for 57 badges and no draws while settled.
+- Screenshots inspected at 1× and 2× pixel density, including enlarged and tilted badges.
+- ESM, CommonJS, and declaration builds pass.
+
+The default look changes, including darker onyx and quieter subpixel glitter. Existing material and lighting overrides remain available; no public options changed.

package/package.json

@@ -0,0 +1,163 @@
+{
+  "name": "badgecraft",
+  "version": "0.3.0",
+  "description": "Interactive 3D badges from any SVG, in metal, enamel, glitter, pearl and more, for React, Vue, Web Components and JavaScript, with a web Studio and image export CLI.",
+  "keywords": [
+    "badge",
+    "svg",
+    "webgl",
+    "pbr",
+    "metal",
+    "enamel",
+    "achievement",
+    "award",
+    "react",
+    "vue",
+    "web-component",
+    "cli",
+    "png",
+    "webp",
+    "svg-to-png"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "./dist/element.js",
+    "./dist/element.cjs",
+    "./src/element/index.ts"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
+    "./vue": {
+      "import": {
+        "types": "./dist/vue.d.ts",
+        "default": "./dist/vue.js"
+      },
+      "require": {
+        "types": "./dist/vue.d.cts",
+        "default": "./dist/vue.cjs"
+      }
+    },
+    "./element": {
+      "import": {
+        "types": "./dist/element.d.ts",
+        "default": "./dist/element.js"
+      },
+      "require": {
+        "types": "./dist/element.d.cts",
+        "default": "./dist/element.cjs"
+      }
+    },
+    "./package.json": "./package.json",
+    "./node": {
+      "types": "./cli/render.d.ts",
+      "import": "./cli/render.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "cli",
+    "docs/*.jpg",
+    "docs/cli.md",
+    "docs/performance.md",
+    "docs/render-quality.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build:worker": "node scripts/build-worker.mjs",
+    "build": "npm run build:worker && tsup && node scripts/build-cli-browser.mjs && npm run build:studio",
+    "dev": "npm run build:worker && vite playground",
+    "typecheck": "npm run build:worker && tsc --noEmit",
+    "test": "npm run build:worker && vitest run",
+    "test:browser": "npm run build:worker && node scripts/browser-check.mjs",
+    "test:studio": "npm run build:worker && node scripts/studio-check.mjs",
+    "test:bugbash": "npm run build:worker && node scripts/bugbash-check.mjs",
+    "test:package": "npm run build && node scripts/package-check.mjs",
+    "benchmark": "npm run build:worker && node scripts/benchmark.mjs",
+    "perf:profile": "npm run build:worker && node scripts/profile.mjs",
+    "prepublishOnly": "npm run verify",
+    "test:quality": "npm run build:worker && node scripts/quality-check.mjs",
+    "doctor": "node scripts/react-doctor.mjs",
+    "verify": "npm run typecheck && npm test && npm run test:package && npm run test:cli && npm run doctor",
+    "prepack": "npm run build",
+    "test:cli": "node --test test/cli.test.mjs test/studio-server.test.mjs",
+    "test:tarball": "node scripts/tarball-check.mjs",
+    "build:studio": "vite build playground",
+    "test:studio:built": "node scripts/studio-check.mjs --built"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "vue": ">=3.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "@vitejs/plugin-vue": "^6.0.9",
+    "esbuild": "^0.28.2",
+    "playwright": "^1.63.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2",
+    "vue": "^3.5.43"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "playwright-core": "1.63.0"
+  },
+  "author": "Parth Jadhav",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ParthJadhav/badgecraft.git"
+  },
+  "homepage": "https://parthjadhav.github.io/badgecraft/",
+  "bugs": {
+    "url": "https://github.com/ParthJadhav/badgecraft/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "pnpm@11.10.0",
+  "bin": {
+    "badgecraft": "./cli/index.mjs"
+  }
+}