badgecraft 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.3.0
+
+- Rename the package from `metallic-badge` to `badgecraft`, since finishes now go well beyond metal. Install `badgecraft`, import `Badgecraft` (formerly `MetallicBadge`) from `badgecraft`, `badgecraft/react`, or `badgecraft/vue`, and use `<badge-craft>` in HTML (`defineBadgecraft` registers it under another tag). The CLI is `npx badgecraft`, its default output is `<input>.badge.png`, and it reads `BADGECRAFT_CHROME_PATH` (`METALLIC_BADGE_CHROME_PATH` still works). Saved Studio drafts carry over.
+- Redesign the website. The landing page leads with a live badge you can drag and restyle, explains the three-step flow, and mounts gallery badges only as they scroll into view.
+- Rebuild the Studio in React around three steps: artwork, finish, fine-tune. Samples are visual tiles, materials and frames are swatches, and advanced controls use plain-language labels in collapsed groups.
+- Add undo and redo (including for Reset), drop-anywhere SVG import, a code dialog with per-framework install steps, and a split PNG export button.
+- Keep the preview responsive by debouncing only the settings that trigger a bake; material and lighting changes apply instantly.
+- Add Studio controls for artwork inset and inner ring (under the frame picker), wire width, bevel, edge rounding, enamel fill and dome spread, smoothing, hole filling, tilt range, roll, icon colour, and locked colour. Export PNGs at 128 and 256 px too.
+- Preview relief changes live while dragging, with a fast low-resolution bake that sharpens when the slider rests.
+- Use Apple, Atlassian, Google, and Meta logo marks as the site's examples, and show framework icons on code tabs. The previous sample artwork now lives in development-only fixtures and is no longer published.
+- Migrate existing Studio drafts automatically.
+
+## 0.2.0
+
+- Launch the bundled web Studio with `npx metallic-badge studio`, with no checkout or build tools.
+- Upload SVG artwork, adjust materials, lighting, relief, frames, and pose, then export PNGs or copy integration code.
+- Add `--port` and optional `--open` in Google Chrome; the server binds only to this computer.
+- Offer a plain HTML/CDN embed alongside React, Vue, Web Component, and vanilla JavaScript snippets.
+- Publish the web Studio to GitHub Pages while keeping the source repository private.
+- Test the built editor, local server, and framework-free browser modules from the installed npm tarball.
+
+## 0.1.0
+
+- Render SVG artwork as physically based metallic and enamel badges with 23 material presets.
+- Use React, Vue, Web Components, or vanilla JavaScript with ESM, CommonJS, and TypeScript declarations.
+- Convert local or piped SVG files to PNG, WebP, or JPEG with the `metallic-badge` CLI.
+- Render images programmatically with `renderBadge` from `metallic-badge/node`.
+- Customize materials, frames, environments, pose, relief quality, and export background.
+- Try the local Studio for importing SVG, editing materials, copying integration snippets, and exporting images.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 badgecraft contributors
+
+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,406 @@
+# badgecraft
+
+Turn **any SVG** into a physically based, interactive **3D badge** in metal, enamel, candy paint, glitter, pearl or holographic finishes, like the Apple Fitness award medals. Strokes become polished metal wires, fills become glossy enamel, and the whole thing is lit by a real PBR material system: metalness, roughness, clear-coat, image-based reflections, iridescence, metallic flakes and brushed metal.
+
+Works with **React**, **Vue**, as a **Web Component** (Svelte, Angular, Solid, Astro, plain HTML), or from vanilla JS.
+
+**[Open the web Studio](https://parthjadhav.github.io/badgecraft/studio.html)** · Upload an SVG, tweak its materials and lighting, then download a PNG or copy code for your site.
+
+![Gallery](https://cdn.jsdelivr.net/npm/badgecraft@0.3.0/docs/gallery.jpg)
+
+```tsx
+import { Badgecraft } from 'badgecraft/react'
+
+<Badgecraft svg="/awards/new-year.svg" metal="gold" size={200} />
+```
+
+- **Any SVG in:** paths, text, gradients, `<use>`/`<symbol>`, `<style>` classes, clip paths, masks, `currentColor`, embedded images. The browser's own SVG renderer is used, so what you see in the SVG is what gets sculpted.
+- **Real materials:** GGX microfacet specular with multi-scattering, split-sum image-based lighting, clear-coat, thin-film iridescence, sparkle flakes and brushed metal. 23 presets (gold, rose-gold, silver, chrome, copper, candy, glitter, pearl, holographic…) or fully custom.
+- **Real 3D:** the relief is displaced geometry with a rounded edge and a back plate. Tilt it on hover, drag-spin it with inertia, or call `spin()`.
+- **Fast:** about 27 KB gzipped with no browser runtime dependencies. The Node CLI uses `playwright-core`. One shared WebGL2 context for any number of badges, and baking runs in a Web Worker. 57 badges render in about 0.3 s on an Apple M-series laptop.
+- **Safe everywhere:** SSR-safe imports, a sized placeholder on the server, a flat SVG fallback without WebGL2, `prefers-reduced-motion` respected, and badges exposed as `role="img"`.
+
+## Install
+
+```sh
+npm install badgecraft
+# or: pnpm add badgecraft / yarn add badgecraft / bun add badgecraft
+```
+
+Node.js 22+ is required for installation and the CLI. React (≥17) and Vue (≥3.3) are optional peer dependencies. Only install the one you use. Google Chrome is needed only for CLI/Node image exports.
+
+## Web Studio
+
+Use the [hosted Studio](https://parthjadhav.github.io/badgecraft/studio.html), or start the same app locally:
+
+```sh
+npx badgecraft studio
+# Optional: open Google Chrome automatically
+npx badgecraft studio --open
+# Choose a port (0 picks an available one)
+npx badgecraft studio --port 8080
+```
+
+Open the printed URL. Upload, drop, or paste an SVG; adjust metal, enamel, relief,
+lighting, frame, and pose; export a transparent PNG at 512, 1024, or 2048 pixels.
+Copy the finished recipe as React, Vue, Web Component, vanilla JS, or plain HTML
+with a CDN import. Artwork and saved drafts stay in your browser.
+
+The local app is included in the npm package: no checkout, build tools, or extra
+dependencies to install. It serves only on `127.0.0.1`; press Ctrl+C to stop it.
+After installation it can run offline. Browser rendering requires WebGL2.
+
+## CLI: SVG to badge image
+
+```sh
+npx badgecraft icon.svg --output badge.png --metal gold
+npx badgecraft icon.svg --output silver.webp --metal silver --frame circle
+```
+
+The CLI uses installed **Google Chrome** to render the same badge effect as
+the library. Export transparent PNG/WebP or JPEG, up to 2048 × 2048, with material,
+lighting, frame, background, and pose controls. It works with local files or piped
+SVG markup, without uploading artwork. Use `--help` for all flags.
+
+For scripted exports, import `renderBadge` from `badgecraft/node`.
+See the [CLI and Node API guide](https://unpkg.com/badgecraft@0.3.0/docs/cli.md) for setup, examples, and limitations.
+
+## Usage
+
+### Plain HTML — no build tools
+
+Paste this into an HTML page served by your site. Replace `src` with your SVG URL;
+the custom element handles rendering and interaction.
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/badgecraft@0.3.0/dist/element.js"></script>
+<badge-craft
+  src="/awards/star.svg"
+  metal="gold"
+  alt="Star award"
+  style="width:240px;height:240px"
+></badge-craft>
+```
+
+For a self-contained snippet with your SVG and custom settings, choose **HTML · CDN**
+in the Studio's code panel. CDN imports need internet access; bundled npm imports
+work with your site's own assets.
+
+### React
+
+```tsx
+import { useRef } from 'react'
+import { Badgecraft, type BadgecraftRef } from 'badgecraft/react'
+
+export function Award() {
+  const badge = useRef<BadgecraftRef>(null)
+  return (
+    <>
+      <Badgecraft
+        ref={badge}
+        svg="/awards/lightning.svg"
+        metal="gold"
+        base="onyx"
+        interaction="drag"
+        size={240}
+        alt="Lightning award"
+        onReady={() => console.log('ready')}
+      />
+      <button onClick={() => badge.current?.spin()}>Spin</button>
+    </>
+  )
+}
+```
+
+Props are the [options](#options) plus `size` (number = px, or any CSS length), `alt`, `className`, `style` and any `div` attribute. Changing props is cheap: only what changed is recomputed.
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Badgecraft } from 'badgecraft/vue'
+const badge = ref()
+</script>
+
+<template>
+  <Badgecraft ref="badge" svg="/awards/parks.svg" metal="silver" :size="240" idle="float" @ready="..." />
+  <button @click="badge.spin()">Spin</button>
+</template>
+```
+
+To register it globally, use `app.use(BadgecraftPlugin)`.
+
+### Web Component (any framework or plain HTML)
+
+```html
+<script type="module">
+  import 'badgecraft/element'
+</script>
+
+<badge-craft src="/awards/new-year.svg" metal="gold" style="width: 200px; height: 200px"></badge-craft>
+
+<!-- inline artwork, JSON for object options -->
+<badge-craft frame="hexagon" metal='{"preset":"gold","roughness":0.15}' relief='{"depth":0.06}'>
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 18 12 4l8 14z" /></svg>
+</badge-craft>
+```
+
+Attributes are kebab-case versions of the options (`tilt-max`, `tone-mapping`, `fill-holes`…). Object options accept JSON, or you can set `element.options = {...}` from JS. Events: `ready` and `error`. Methods: `spin()`, `glint()`, `toDataURL()`, `toBlob()`. Style the size with CSS (default 160×160).
+
+### Vanilla JS
+
+```ts
+import { Badgecraft } from 'badgecraft'
+
+const badge = new Badgecraft(document.querySelector('#award')!, { svg: svgMarkup, metal: 'rose-gold' })
+await badge.ready
+badge.update({ metal: 'silver' }) // merge options
+badge.spin(2)
+const png = await badge.toBlob()
+badge.destroy()
+```
+
+The host element needs a size. If it has none, it gets `160px` and `aspect-ratio: 1`.
+
+## How an SVG becomes a badge
+
+| SVG                                   | Badge                                                                        |
+| ------------------------------------- | ---------------------------------------------------------------------------- |
+| Strokes                               | Raised, round **metal wires** (the `metal` material)                         |
+| Fills                                 | Recessed, slightly domed **enamel pools** in the fill colour (gradients too) |
+| Areas enclosed by the artwork         | The **backplate** (`base` material), unless `fillHoles: false`               |
+| The silhouette                        | A **metal rim** (`rim`), a rounded edge and a solid back plate               |
+
+`mode: 'auto'` (the default) picks a sensible mapping:
+
+- Artwork with strokes, images or several colours → **cloisonné** (as above). Multi-colour art *without* strokes gets automatic wires around each shape (`outline: 'auto'`), so flat illustrations, flags and emoji work out of the box.
+- Single-colour artwork (logos, solid icons) → **embossed**: every shape becomes raised, bevelled metal.
+
+Wrap icons in a badge shape with `frame`: `'circle' | 'hexagon' | 'octagon' | 'shield' | 'square' | 'diamond' | 'star'`, or `{ shape, padding, innerRing, path }`.
+
+### Per-element control
+
+Annotate SVG elements (or groups) with data attributes:
+
+| Attribute                                             | Values                                   | Effect                                     |
+| ----------------------------------------------------- | ---------------------------------------- | ------------------------------------------ |
+| `data-material`                                       | `metal` `enamel` `base` `accent`         | Material slot for the element's fill and stroke |
+| `data-fill-material` / `data-stroke-material`         | same                                     | Slot for just the fill or the stroke       |
+| `data-relief`                                         | `raised` `inset` `flat` `none`           | Sculpting of the fill                      |
+| `data-stroke-relief`                                  | same                                     | Sculpting of the stroke (default `raised`) |
+
+```html
+<circle r="40" fill="#c6f400" data-fill-material="accent" />  <!-- candy-metal ring with accent="candy" -->
+<path d="…" fill="#fff" data-relief="raised" />               <!-- embossed metal numerals -->
+```
+
+## Options
+
+| Option                | Type                                                                      | Default     |
+| --------------------- | ------------------------------------------------------------------------- | ----------- |
+| `svg`                 | SVG markup, URL, data URL or `SVGElement`                                 | (required)  |
+| `mode`                | `'auto' \| 'cloisonne' \| 'embossed'`                                     | `'auto'`    |
+| `metal`               | [material](#materials): wires and rim                                     | `'gold'`    |
+| `enamel`              | material: fills (uses SVG colours)                                        | `'enamel'`  |
+| `base`                | material: backplate                                                       | `'onyx'`    |
+| `accent`              | material: for `data-material="accent"`                                    | `'silver'`  |
+| `color`               | value of `currentColor` in the SVG                                        | `'#ffffff'` |
+| `frame`               | badge shape around the artwork                                            | none        |
+| `rim`                 | outer metal rim width (fraction of badge, `0` = off)                      | `0.03`      |
+| `outline`             | wires around filled shapes (fraction), or `'auto'`                        | `'auto'`    |
+| `fillHoles`           | fill enclosed areas with the backplate                                    | `true`      |
+| `relief`              | [relief options](#relief)                                                 |             |
+| `environment`         | [environment](#lighting--environments) preset, custom lights, or HDR URL  | `'studio'`  |
+| `environmentRotation` | degrees                                                                   | `0`         |
+| `exposure`            | linear exposure                                                           | `1`         |
+| `toneMapping`         | `'neutral' \| 'aces' \| 'agx' \| 'none'`                                  | `'neutral'` |
+| `interaction`         | `'tilt'` (hover) `\| 'drag'` (spin with inertia) `\| 'none'`              | `'tilt'`    |
+| `tiltMax`             | max tilt in degrees                                                       | `18`        |
+| `pose`                | resting `{ pitch, yaw, roll }` in degrees (a slight 3/4 view shows the edge) | `{ pitch: -5, yaw: -8 }` |
+| `idle`                | `'none' \| 'float' \| 'shine'`                                            | `'none'`    |
+| `locked`              | flat grey outline for awards not yet earned                               | `false`     |
+| `lockedColor`         | colour of the locked outline                                              | `'#3a3a3c'` |
+| `shadow`              | contact shadow opacity (`0` = off)                                        | `0.35`      |
+| `quality`             | relief map resolution in px, or `'auto'` (matches display size)           | `'auto'`    |
+| `padding`             | space around the badge for tilting (fraction of canvas)                   | `0.06`      |
+| `onReady` / `onError` | callbacks                                                                 |             |
+
+Instance methods (also on the React ref, Vue ref and custom element): `spin(turns = 1)`, `glint()`, `toDataURL(type?, quality?)` and `toBlob(type?, quality?)`. The vanilla class adds `update(partial)`, `setOptions(all)`, `destroy()`, and `ready`, a promise that resolves after the first draw and rejects if the artwork can't be loaded or baked.
+
+Destroying a badge before its first draw rejects `ready` with an `AbortError`. Destruction cancels callbacks from pending work. `spin()` and `glint()` respect reduced motion and locked badges. Nonfinite numeric options use safe defaults; bounded material and geometry values are clamped.
+
+### Materials
+
+Every material slot takes a preset name, a full material, or a preset with overrides:
+
+```ts
+metal: 'rose-gold'
+metal: { preset: 'gold', roughness: 0.12, brushed: 0.4 }
+enamel: { metalness: 0.8, roughness: 0.25, clearcoat: 1 } // candy-paint enamel in SVG colours
+base: { preset: 'onyx', color: '#14233f' }
+```
+
+| Parameter                             | Meaning                                                                     |
+| ------------------------------------- | --------------------------------------------------------------------------- |
+| `color`                               | base colour; for metals, the specular (F0) tint                             |
+| `useSvgColor`                         | take the colour from the SVG (default for the enamel slot)                  |
+| `metalness`                           | 0 = dielectric (enamel, paint), 1 = metal                                   |
+| `roughness`                           | 0 = mirror … 1 = diffuse                                                    |
+| `clearcoat`, `clearcoatRoughness`     | glossy lacquer layer on top                                                 |
+| `ior`                                 | dielectric index of refraction (reflectance at normal incidence)            |
+| `iridescence`, `iridescenceThickness` | thin-film interference (oil slick, anodised, holographic)                   |
+| `flakes`, `flakeScale`                | sparkling metallic flakes                                                   |
+| `brushed`, `brushDirection`           | brushed streaks: `circular`, `radial`, `horizontal`, `vertical`             |
+| `emissive`                            | self-illumination of the base colour                                        |
+
+**Presets:** `gold`, `rose-gold`, `white-gold`, `matte-gold`, `brushed-gold`, `silver`, `brushed-silver`, `platinum`, `chrome`, `copper`, `bronze`, `brass`, `titanium`, `gunmetal`, `black-chrome`, `enamel`, `matte-enamel`, `candy`, `glitter`, `pearl`, `holographic`, `onyx`, `obsidian`. They're exported as `materials` if you want to build on them.
+
+### Relief
+
+```ts
+relief: {
+  depth: 0.05,         // max relief height (fraction of badge); wires are shaped as round tubes up to this
+  thickness: 0.03,     // back plate thickness
+  floor: 0.3,          // backplate height relative to wire tops
+  profile: 'round',    // wire cross-section: 'round' | 'soft' | 'chamfer'
+  bevel: 0.02,         // bevel width of raised (embossed) shapes
+  edge: 0.014,         // rounding of the outer edge
+  enamelLevel: 0.16,   // how full the enamel pools are
+  enamelDome: 0.12,    // doming of enamel (negative = concave)
+  domeWidth: 0.05,
+  smoothing: 0.9,
+  ao: 0.45,            // ambient occlusion in crevices
+}
+```
+
+### Lighting & environments
+
+Presets are procedural HDR studios: `studio` (default), `soft`, `sunset`, `night`, `neon`. You can also design your own lights or use an equirectangular HDR image:
+
+```ts
+environment: 'sunset'
+
+environment: {
+  top: '#7c7c80', horizon: '#2e2e32', bottom: '#121214',
+  lights: [
+    // azimuth 0 = behind the viewer (what the badge face reflects), elevation above the horizon
+    { azimuth: -40, elevation: 38, size: [70, 50], intensity: 4, color: '#fff6e8', softness: 0.7 },
+    { azimuth: 135, elevation: 30, size: 30, shape: 'circle', intensity: 3 },
+  ],
+}
+
+environment: { url: '/hdri/studio_small_08_1k.hdr', intensity: 1.2 } // .hdr (RGBE) or any image format
+```
+
+Environments are pre-filtered once per page (GGX importance sampling into a roughness mip chain plus a diffuse irradiance map) and shared by all badges.
+
+## Technology choices
+
+The goal was photoreal metal for **arbitrary** SVGs, cheap enough to show dozens on a page, in any framework.
+
+| Approach                                              | Verdict                                                                                                                                                                                                                                        |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CSS / SVG lighting filters (`feSpecularLighting`)     | Tiny and SSR-able, but not physically based: no environment reflections, and it looks like a 2010-era bevel.                                                                                                                                  |
+| three.js `SVGLoader` + `ExtrudeGeometry` + `MeshPhysicalMaterial` | Real PBR out of the box, but ~150 KB gzip. Triangulating arbitrary SVGs (strokes, holes, self-intersections, text) is fragile, there's no control over a cloisonné wire profile, and one context per badge hits the browser's ~16 WebGL-context limit. |
+| WebGPU                                                | The future, but not yet available everywhere.                                                                                                                                                                                                 |
+| **Chosen: SVG → distance-field relief bake + custom WebGL2 PBR** | **Robust for any SVG** (the browser rasterises it), **exact control** over the look, **~27 KB**, **one shared context** for unlimited badges, universal WebGL2 support.                                                                        |
+
+How it works:
+
+1. **Classify.** The SVG is attached to a hidden shadow root so the browser's style engine resolves classes, inheritance and `currentColor`. `<use>` is inlined, and every painted shape is assigned a relief role and a material slot.
+2. **Rasterise.** Four passes are rendered by the browser's SVG renderer: role masks, slot masks (colour-coded channels on black, so each channel is exact anti-aliased coverage that respects paint order) and the colour pass.
+3. **Bake** (in a Web Worker). Exact Euclidean distance transforms with sub-pixel edge points (Felzenszwalb–Huttenlocher, refined with Gustavson's anti-aliased edge model) produce a smooth height field: round tube wires sized from each wire's local width, domed enamel pools, a rounded outer edge, cavity occlusion and dilated colours.
+4. **Render** (WebGL2). A displaced grid mesh (front relief plus back plate) is shaded with GGX, multi-scatter energy compensation, split-sum IBL from pre-filtered environments, clear-coat, flakes, thin-film iridescence, brushed anisotropy and Khronos PBR Neutral tone mapping. Every badge draws through a single shared context into its own 2D canvas.
+
+## Performance notes
+
+- Baking is cached by artwork, options and resolution. Identical badges share GPU textures, and remounts within a few seconds (React StrictMode, route changes) reuse them.
+- `quality: 'auto'` bakes at roughly the badge's device-pixel size (256–1024 px) and re-bakes only if the badge grows a lot.
+- Static badges draw once. Only moving badges (hover, drag, spin, idle) draw per frame, and idle animation pauses off-screen.
+- Reflection highlights and flakes are filtered at pixel scale to reduce shimmer. The mirror environment level skips convolution; rough reflections still use the cached GGX mip chain. These refinements add no textures or draw passes.
+- Material, lighting and pose changes are just uniforms, so they're free to animate. Artwork and relief changes trigger a re-bake: about 5–15 ms of main-thread work (the browser rasterises the SVG), then the distance-field bake in a Web Worker (~75–100 ms at 512 px, ~0.4 s at 1024 px on an M-series laptop).
+
+## Limitations
+
+- SVGs are rendered as images, so **external resources** (linked images, web fonts) aren't loaded. Inline images as data URLs and convert text to paths (or accept system fonts).
+- Artwork is static: scripts, event handlers, embedded HTML, animation elements, and external SVG references are removed before classification.
+- Badges are square. Non-square artwork is centred.
+- WebGL2 is required for the 3D render. Without it, the flat SVG is shown.
+
+## Development
+
+The playground's landing page (`index.html`) and **Studio** (`studio.html`) are
+React apps in `playground/site/`. The Studio walks through three steps (artwork,
+finish, fine-tune) next to a live preview:
+
+- Open any landing-page example in the Studio with its full material and frame recipe.
+- Pick a sample, upload or drop an SVG anywhere on the page (up to 1 MB), or paste
+  SVG markup. Invalid edits show an error and keep the previous preview and saved draft.
+- Choose metals, enamels, backplates and frames from visual swatches. Advanced
+  material, depth, lighting and motion controls are grouped and collapsed.
+  Material sliders show actual preset values and can be restored individually.
+- Every change can be undone (⌘Z / Ctrl+Z, ⇧⌘Z / Ctrl+Y), including a full reset.
+- Copy complete React/TSX, Vue, Web Component, plain HTML or vanilla JS code. The
+  snippet includes your SVG, so it works without the playground's sample files.
+- Download a transparent PNG at 512, 1024 or 2048 pixels. Exports use the
+  configured resting pose, independent of preview motion and display density.
+- Valid drafts save locally in your browser. The Studio still works when local
+  storage is unavailable.
+
+The site's examples use the Apple, Atlassian, Google, and Meta logo marks in
+`playground/public/logos/` (trademarks of their owners, shown as sample artwork).
+
+`gallery.html` is a development render harness for `scripts/`
+(`?only=id,id&size=N&opts=<JSON>&light`). It and `test.html` use the artwork in
+`playground/fixtures/`, which the render-quality baselines depend on; neither is
+part of the published site.
+
+![Studio](https://cdn.jsdelivr.net/npm/badgecraft@0.3.0/docs/studio.jpg)
+
+```sh
+pnpm install
+pnpm dev             # playground at http://localhost:5199 (landing, studio, React, Vue, Web Component)
+pnpm test            # unit tests (distance transforms, bake)
+pnpm test:browser    # end-to-end checks in installed Google Chrome
+pnpm test:studio     # import, drafts, code, clipboard, export and mobile workflows
+pnpm test:bugbash    # adversarial API, loading, lifecycle and fallback regressions
+pnpm test:package    # build + ESM/CJS imports and React/Vue SSR checks
+pnpm test:cli        # real Chrome CLI and Node API export regressions
+pnpm test:tarball    # install/test the actual npm tarball in a clean project
+pnpm test:quality artifacts/reference # capture 108 reference images before a render edit
+pnpm test:quality artifacts/current artifacts/reference # compare after the edit
+pnpm benchmark       # five Chrome runs: timing, triangles, long tasks, idle/context checks
+pnpm perf:profile artifacts/profile # phase timings, GPU queries, CPU profiles, frame pacing
+pnpm typecheck
+pnpm doctor          # full React Doctor scan; complete 100/100 required
+pnpm verify          # types, unit tests, package build/SSR, CLI checks, Doctor 100
+pnpm build           # ESM + CJS + .d.ts + CLI renderer into dist/
+pnpm build:studio    # build the gallery and Studio into dist/studio/
+```
+
+See [profiling and paired A/B comparisons](https://unpkg.com/badgecraft@0.3.0/docs/performance.md) for baseline
+snapshots, measurement boundaries, raw evidence, and quality checks.
+
+Maintainers: see [release setup and publishing](https://github.com/ParthJadhav/badgecraft/blob/main/docs/releasing.md).
+
+## License
+
+MIT
+
+React Doctor runs `npx react-doctor@latest` without scan caches and requires network access. Missing or
+incomplete scans fail verification. The JSON report is saved in
+`node_modules/.cache/react-doctor/report.json`. Reviewed inline exceptions cover
+dedicated-worker messages and existing object-URL cleanup lifecycles.
+`doctor.config.json` excludes generated bundles; all
+authored source remains in the full scan.
+
+Run browser suites sequentially, after build commands have finished: rebuilding
+the worker while Vite is serving tests triggers a page reload. Screenshots from
+`pnpm test:studio` are saved in `artifacts/studio-check/`. See the
+[maintainer product review](https://github.com/ParthJadhav/badgecraft/blob/main/docs/product-opportunities.md) for the
+remaining opportunities and the reasons behind this Studio pass.
+
+The pnpm policy delays new releases for 24 hours, rejects trust downgrades, and
+blocks exotic transitive dependencies. Two exact, integrity-pinned tsup/Vitest
+dependencies have documented trust-policy exceptions; other versions remain checked.

package/cli/index.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { createReadStream } from 'node:fs'
+import { readFile, writeFile, mkdir, lstat, stat } from 'node:fs/promises'
+import { resolve, parse, extname, dirname } from 'node:path'
+import { renderBadge } from './render.mjs'
+
+const help = `badgecraft — turn an SVG into a badge image
+
+Usage:
+  badgecraft icon.svg [options]
+  badgecraft studio [--port 5199] [--open]
+  badgecraft icon.svg -o badge.png --metal gold --frame circle
+  cat icon.svg | badgecraft - -o badge.webp
+
+Options:
+  -o, --output <path>         Output file (default: <input>.badge.png); - for stdout
+  -s, --size <pixels>         Square image size, 16–2048 (default: 1024)
+  -m, --metal <preset>        Metal preset (default: gold)
+      --base <preset>         Backplate material (default: onyx)
+      --enamel <preset>       Fill material (default: enamel)
+      --frame <shape>         circle, hexagon, octagon, shield, square, diamond, star
+      --mode <mode>           auto, cloisonne, embossed
+      --environment <name>    studio, soft, sunset, night, neon
+      --background <color>    CSS color (default: transparent; JPEG: white)
+      --color <color>         SVG currentColor (default: white)
+      --format <format>       png, webp, jpeg (default: inferred from output)
+      --quality <number>      PNG/WebP/JPEG relief resolution, 64–2048 (default: auto)
+      --image-quality <0–1>   WebP/JPEG encoding quality (default: 0.92)
+      --pitch <degrees>       Pitch, -89–89 (default: -5)
+      --yaw <degrees>         Yaw, -180–180 (default: -8)
+      --roll <degrees>        Roll, -180–180 (default: 0)
+      --exposure <number>     Exposure, 0–16 (default: 1)
+      --no-shadow             Disable the drop shadow
+      --chrome-path <path>    Google Chrome executable (or BADGECRAFT_CHROME_PATH)
+      --no-sandbox            Disable Chrome sandbox in restricted containers only
+      --timeout <ms>          Startup/render timeout, 100–300000 (default: 60000)
+  -f, --force                 Overwrite an existing output file
+      --list-presets          List material presets
+  -h, --help                  Show this help
+  -v, --version               Show version
+
+Studio opens an interactive SVG editor locally. Run badgecraft studio --help.
+Image exports require Node.js 22+ and Google Chrome. Input must be a self-contained SVG
+(maximum 10 MiB). External resources are blocked. PNG/WebP preserve transparency.
+Lighting is rasterized; the output is not an editable vector SVG.
+`
+
+function number(value, name, lo, hi, integer = false) {
+  const n = value?.trim() ? Number(value) : NaN
+  if (!Number.isFinite(n) || n < lo || n > hi || (integer && !Number.isInteger(n))) {
+    throw new Error(`--${name} must be ${integer ? 'an integer' : 'a number'} from ${lo} to ${hi}.`)
+  }
+  return n
+}
+
+async function main() {
+  if (process.argv[2] === 'studio') {
+    const { runStudio } = await import('./studio.mjs')
+    return runStudio(process.argv.slice(3))
+  }
+  const strings = ['base', 'enamel', 'frame', 'mode', 'environment', 'background', 'color', 'format', 'quality', 'image-quality', 'pitch', 'yaw', 'roll', 'exposure', 'chrome-path', 'timeout']
+  const { values: args, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      ...Object.fromEntries(strings.map((key) => [key, { type: 'string' }])),
+      output: { type: 'string', short: 'o' }, size: { type: 'string', short: 's' }, metal: { type: 'string', short: 'm' },
+      force: { type: 'boolean', short: 'f' }, help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+      'no-shadow': { type: 'boolean' }, 'no-sandbox': { type: 'boolean' }, 'list-presets': { type: 'boolean' },
+    },
+  })
+  if (args.help) return process.stdout.write(help)
+  if (args.version) return process.stdout.write(`${JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version}\n`)
+  const { materials, framePaths, environments } = await import('../dist/index.js')
+  if (args['list-presets']) return process.stdout.write(`${Object.keys(materials).join('\n')}\n`)
+  if (positionals.length !== 1) throw new Error('Provide one SVG file, or - for stdin. Run badgecraft --help for usage.')
+  const input = positionals[0]
+  const parsed = parse(input)
+  const output = args.output ?? (input === '-' ? 'badge.png' : resolve(parsed.dir, `${parsed.name}.badge.png`))
+  if (input !== '-' && output !== '-' && resolve(input) === resolve(output)) throw new Error('The output path must differ from the input SVG.')
+  const extension = extname(output).slice(1).toLowerCase()
+  const format = args.format ?? (output === '-' || !extension ? 'png' : extension === 'jpg' ? 'jpeg' : extension)
+  if (!['png', 'webp', 'jpeg'].includes(format)) throw new Error('Use a .png, .webp, or .jpg output path, or --format png|webp|jpeg.')
+  if (args.format && extension && output !== '-' && extension !== format && !(extension === 'jpg' && format === 'jpeg')) {
+    throw new Error('The output extension must match --format.')
+  }
+  const options = { format }
+  for (const key of ['metal', 'base', 'enamel', 'frame', 'mode', 'environment']) {
+    if (args[key] === undefined) continue
+    const presets = key === 'frame' ? Object.keys(framePaths) : key === 'mode' ? ['auto', 'cloisonne', 'embossed'] : key === 'environment' ? Object.keys(environments) : Object.keys(materials)
+    if (!presets.includes(args[key])) throw new Error(`Unknown ${key} '${args[key]}'. Choose: ${presets.join(', ')}.`)
+    options[key] = args[key]
+  }
+  for (const [flag, key, lo, hi, integer] of [
+    ['size', 'size', 16, 2048, true], ['quality', 'quality', 64, 2048, true],
+    ['image-quality', 'imageQuality', 0, 1, false], ['exposure', 'exposure', 0, 16, false],
+    ['timeout', 'timeout', 100, 300000, true],
+  ]) if (args[flag] !== undefined) options[key] = number(args[flag], flag, lo, hi, integer)
+  for (const key of ['pitch', 'yaw', 'roll']) if (args[key] !== undefined) {
+    options.pose ??= {}
+    options.pose[key] = number(args[key], key, key === 'pitch' ? -89 : -180, key === 'pitch' ? 89 : 180)
+  }
+  for (const key of ['background', 'color']) if (args[key] !== undefined) options[key] = args[key]
+  if (args['chrome-path']) options.executablePath = args['chrome-path']
+  if (args['no-shadow']) options.shadow = 0
+  if (args['no-sandbox']) options.sandbox = false
+  if (output === '-' && process.stdout.isTTY) throw new Error('Refusing to write an image to your terminal. Redirect stdout to a file or pipe.')
+  if (input === '-' && process.stdin.isTTY) throw new Error('Pipe SVG markup into stdin, or provide a file path.')
+  const chunks = []
+  let bytes = 0
+  for await (const chunk of input === '-' ? process.stdin : createReadStream(input)) {
+    bytes += chunk.length
+    if (bytes > 10 * 1024 * 1024) throw new Error('SVG exceeds the 10 MiB input limit.')
+    chunks.push(chunk)
+  }
+  const svg = Buffer.concat(chunks).toString('utf8')
+  // Exclusive creation prevents accidental overwrite, including concurrent conversions.
+  // Render before opening the output so failures never leave empty files.
+  if (output !== '-') {
+    try {
+      const target = await lstat(output)
+      if (!args.force) throw new Error(`Output already exists: ${output}. Use --force to overwrite.`)
+      if (!target.isFile()) throw new Error('The output must be a regular file, not a symlink or directory.')
+      if (input !== '-') {
+        const source = await stat(input)
+        if (source.dev === target.dev && source.ino === target.ino) throw new Error('The output must not refer to the input SVG.')
+      }
+    } catch (error) { if (error.code !== 'ENOENT') throw error }
+  }
+  const image = await renderBadge(svg, options)
+  if (output === '-') {
+    await new Promise((resolve, reject) => process.stdout.write(image, (error) => error ? reject(error) : resolve()))
+  } else {
+    await mkdir(dirname(resolve(output)), { recursive: true })
+    await writeFile(output, image, { flag: args.force ? 'w' : 'wx' })
+    process.stderr.write(`Created ${output} (${options.size ?? 1024} × ${options.size ?? 1024}, ${format.toUpperCase()})\n`)
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`badgecraft: ${error.message}\n`)
+  process.exitCode = 1
+})

package/cli/render.d.ts

@@ -0,0 +1,20 @@
+import type { BadgeOptions, EnvironmentPreset } from '../dist/index.js'
+
+export interface RenderOptions extends Omit<BadgeOptions, 'svg' | 'onReady' | 'onError' | 'idle' | 'interaction' | 'environment'> {
+  /** Output width and height in pixels (16–2048). Default 1024. */
+  size?: number
+  format?: 'png' | 'webp' | 'jpeg'
+  /** CSS color. PNG/WebP default to transparent; JPEG defaults to white. */
+  background?: string
+  /** Lossy encoding quality (0–1). Default 0.92. */
+  imageQuality?: number
+  environment?: EnvironmentPreset
+  /** Milliseconds for Chrome startup and separately for rendering. Default 60000. */
+  timeout?: number
+  executablePath?: string
+  /** Disable only in containers that cannot run Chrome's sandbox. Default true. */
+  sandbox?: boolean
+}
+
+/** Convert self-contained SVG markup to a badge image. Requires Google Chrome. */
+export function renderBadge(svg: string, options?: RenderOptions): Promise<Buffer>