badgecraft 0.3.0

package/cli/render.mjs

@@ -0,0 +1,87 @@
+import { readFile } from 'node:fs/promises'
+import { chromium } from 'playwright-core'
+
+/** Render SVG markup with the same WebGL2 renderer used by the browser library. */
+export async function renderBadge(svg, options = {}) {
+  const { size = 1024, format = 'png', background, imageQuality = 0.92,
+    timeout = 60000, executablePath = process.env.BADGECRAFT_CHROME_PATH ?? process.env.METALLIC_BADGE_CHROME_PATH,
+    sandbox = true, ...badgeOptions } = options
+  if (typeof svg !== 'string' || !svg.trim().startsWith('<')) throw new Error('Expected SVG markup.')
+  if (Buffer.byteLength(svg) > 10 * 1024 * 1024) throw new Error('SVG exceeds the 10 MiB input limit.')
+  if (!Number.isInteger(size) || size < 16 || size > 2048) throw new Error('size must be an integer from 16 to 2048.')
+  if (!['png', 'webp', 'jpeg'].includes(format)) throw new Error('format must be png, webp, or jpeg.')
+  if (!Number.isFinite(timeout) || timeout < 100 || timeout > 300000) throw new Error('timeout must be from 100 to 300000 milliseconds.')
+  if (!Number.isFinite(imageQuality) || imageQuality < 0 || imageQuality > 1) throw new Error('imageQuality must be from 0 to 1.')
+  if (background !== undefined && typeof background !== 'string') throw new Error('background must be a CSS color.')
+  // Image URLs are deliberately unsupported: conversions must not make network requests.
+  if (badgeOptions.environment !== undefined && !['studio', 'soft', 'sunset', 'night', 'neon'].includes(badgeOptions.environment)) {
+    throw new Error('environment must be studio, soft, sunset, night, or neon.')
+  }
+  const bundle = await readFile(new URL('../dist/cli-browser.js', import.meta.url), 'utf8')
+  let browser
+  try {
+    browser = await chromium.launch({
+      ...(executablePath ? { executablePath } : { channel: 'chrome' }),
+      headless: true,
+      chromiumSandbox: sandbox,
+      timeout,
+      args: ['--use-angle=swiftshader', '--enable-unsafe-swiftshader'],
+    })
+  } catch (error) {
+    throw new Error(`Could not start Google Chrome. Install Chrome or set BADGECRAFT_CHROME_PATH to its executable. In a container, configure Chrome sandboxing or explicitly pass --no-sandbox.\n${error.message}`, { cause: error })
+  }
+  let timer
+  try {
+    const render = async () => {
+      const context = await browser.newContext({ viewport: { width: size, height: size }, deviceScaleFactor: 1, serviceWorkers: 'block' })
+      // SVG styles can reference remote assets; never allow them to contact the network.
+      await context.route(/^(https?|file|ftp):/i, (route) => route.abort())
+      const page = await context.newPage()
+      page.setDefaultTimeout(timeout)
+      await page.setContent('<!doctype html><html><head><meta charset="utf-8"></head><body style="margin:0"><div id="badge" style="width:100vw;height:100vh"></div></body></html>')
+      await page.addScriptTag({ content: bundle })
+      return page.evaluate(async ({ svg, badgeOptions, size, format, background, imageQuality }) => {
+        const { Badgecraft, isSupported } = window.BadgecraftLibrary
+        if (!isSupported()) throw new Error('WebGL2 is unavailable in Chrome. Enable software WebGL support; a flat SVG fallback is not an export.')
+        if (background !== undefined && !CSS.supports('color', background)) throw new Error('background must be a valid CSS color.')
+        const badge = new Badgecraft(document.getElementById('badge'), { ...badgeOptions, svg, idle: 'none', interaction: 'none' })
+        try {
+          await badge.ready
+          // toDataURL forces a synchronous draw of the settled pose.
+          badge.toDataURL()
+          const canvas = document.createElement('canvas')
+          canvas.width = canvas.height = size
+          const ctx = canvas.getContext('2d')
+          if (format === 'jpeg') {
+            ctx.fillStyle = '#ffffff'
+            ctx.fillRect(0, 0, size, size)
+          }
+          if (background !== undefined) {
+            ctx.fillStyle = background
+            ctx.fillRect(0, 0, size, size)
+          }
+          ctx.drawImage(badge.canvas, 0, 0, size, size)
+          // Detect failed/empty artwork before a background can hide it.
+          const artwork = badge.canvas.getContext('2d').getImageData(0, 0, badge.canvas.width, badge.canvas.height).data
+          let visible = false
+          for (let i = 3; i < artwork.length; i += 4) if (artwork[i] > 0) { visible = true; break }
+          if (!visible) throw new Error('The SVG produced no visible artwork.')
+          const mime = `image/${format}`
+          const data = canvas.toDataURL(mime, imageQuality)
+          if (!data.startsWith(`data:${mime};base64,`)) throw new Error(`Chrome does not support ${format} export.`)
+          return data.slice(data.indexOf(',') + 1)
+        } finally {
+          badge.destroy()
+        }
+      }, { svg, badgeOptions, size, format, background, imageQuality })
+    }
+    const data = await Promise.race([
+      render(),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Rendering timed out after ${timeout} ms.`)), timeout) }),
+    ])
+    return Buffer.from(data, 'base64')
+  } finally {
+    clearTimeout(timer)
+    await browser.close()
+  }
+}

package/cli/studio.mjs

@@ -0,0 +1,98 @@
+import { createServer } from 'node:http'
+import { readFile, realpath } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { resolve, sep, extname } from 'node:path'
+import { parseArgs } from 'node:util'
+import { spawn } from 'node:child_process'
+
+const directory = fileURLToPath(new URL('../dist/studio/', import.meta.url))
+const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.hdr': 'application/octet-stream', '.png': 'image/png', '.jpg': 'image/jpeg', '.ico': 'image/x-icon' }
+
+// Serve only the installed app. Artwork is read inside the browser, never by this server.
+export async function startStudio({ port = 5199 } = {}) {
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Studio port must be an integer from 0 to 65535.')
+  const root = await realpath(directory)
+  await readFile(resolve(root, 'studio.html'))
+  const server = createServer(async (req, res) => {
+    const address = server.address()
+    const allowedHosts = [`127.0.0.1:${address.port}`, `localhost:${address.port}`]
+    res.setHeader('X-Content-Type-Options', 'nosniff')
+    res.setHeader('Cache-Control', 'no-store')
+    res.setHeader('Cross-Origin-Resource-Policy', 'same-origin')
+    if (!allowedHosts.includes(req.headers.host)) { res.writeHead(403).end('Forbidden'); return }
+    if (!['GET', 'HEAD'].includes(req.method)) { res.writeHead(405, { Allow: 'GET, HEAD' }).end(); return }
+    try {
+      const path = decodeURIComponent((req.url ?? '/').split('?')[0])
+      if (!path.startsWith('/') || /[\\\0]/.test(path) || path.split('/').includes('..')) {
+        res.writeHead(400).end('Invalid path'); return
+      }
+      const file = resolve(root, `.${path === '/' ? '/studio.html' : path}`)
+      if (!file.startsWith(root + sep) || !types[extname(file)]) { res.writeHead(404).end('Not found'); return }
+      const actual = await realpath(file)
+      if (!actual.startsWith(root + sep)) { res.writeHead(404).end('Not found'); return }
+      const data = await readFile(actual)
+      res.writeHead(200, { 'Content-Type': types[extname(file)], 'Content-Length': data.length })
+      res.end(req.method === 'HEAD' ? undefined : data)
+    } catch (error) {
+      const status = error instanceof URIError ? 400 : ['ENOENT', 'EISDIR', 'ENOTDIR'].includes(error.code) ? 404 : 500
+      res.writeHead(status).end(status === 500 ? 'Unable to read Studio asset' : 'Not found')
+    }
+  })
+  await new Promise((accept, reject) => {
+    server.once('error', reject)
+    server.listen(port, '127.0.0.1', () => { server.off('error', reject); accept() })
+  })
+  return { server, url: `http://127.0.0.1:${server.address().port}` }
+}
+
+async function openChrome(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.env.BADGECRAFT_CHROME_PATH || process.env.METALLIC_BADGE_CHROME_PATH || (process.platform === 'win32' ? `${process.env.PROGRAMFILES}\\Google\\Chrome\\Application\\chrome.exe` : 'google-chrome')
+  const args = process.platform === 'darwin' ? ['-a', 'Google Chrome', url] : [url]
+  await new Promise((accept, reject) => {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' })
+    child.once('error', reject)
+    if (process.platform === 'darwin') child.once('exit', (code) => code === 0 ? accept() : reject(new Error('Google Chrome could not be opened.')))
+    else child.once('spawn', () => { child.unref(); accept() })
+  })
+}
+
+export async function runStudio(argv) {
+  const { values } = parseArgs({ args: argv, options: {
+    port: { type: 'string', short: 'p' }, open: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } })
+  if (values.help) {
+    process.stdout.write(`badgecraft studio — upload, customize, export, and copy embed code
+
+Usage: badgecraft studio [options]
+  -p, --port <number>  Local port (default: 5199; 0 chooses an available port)
+      --open           Open Google Chrome
+  -h, --help           Show help
+
+Runs entirely on this computer. Artwork stays in your browser.
+Requires Node.js 22+ and a browser with WebGL2. No checkout or build tools needed.
+Press Ctrl+C to stop the server.
+`)
+    return
+  }
+  if (values.port !== undefined && !/^\d+$/.test(values.port)) throw new Error('--port must be an integer from 0 to 65535.')
+  let app
+  try { app = await startStudio(values.port === undefined ? {} : { port: Number(values.port) }) }
+  catch (error) {
+    if (error.code !== 'EADDRINUSE') throw error
+    if (values.port !== undefined) throw new Error(`Port ${values.port} is in use. Choose another --port, or use --port 0.`)
+    app = await startStudio({ port: 0 })
+  }
+  process.stdout.write(`Badgecraft Studio: ${app.url}/\nPress Ctrl+C to stop.\n`)
+  const stop = () => {
+    process.off('SIGINT', stop)
+    process.off('SIGTERM', stop)
+    app.server.close()
+    app.server.closeAllConnections()
+  }
+  process.once('SIGINT', stop)
+  process.once('SIGTERM', stop)
+  if (values.open) {
+    try { await openChrome(`${app.url}/`) }
+    catch { process.stderr.write(`Could not open Google Chrome. Open ${app.url}/ in your browser.\n`) }
+  }
+}

package/dist/badge-B-g_9WFj.d.ts

@@ -0,0 +1,79 @@
+import { b as BadgecraftHandle, B as BadgeOptions } from './types-CHM3-ZZV.js';
+
+/** One requestAnimationFrame loop for every badge on the page. */
+interface FrameTask {
+    /** Advance by `dt` seconds. Return true to keep receiving frames. */
+    frame(dt: number, now: number): boolean;
+}
+
+/**
+ * A badge rendered into `host`. Framework wrappers (React, Vue, the
+ * custom element) are thin layers over this class.
+ */
+declare class Badgecraft implements BadgecraftHandle, FrameTask {
+    readonly host: HTMLElement;
+    readonly canvas: HTMLCanvasElement;
+    /** Resolves once the badge has been baked and drawn; rejects if that fails. */
+    readonly ready: Promise<void>;
+    private ctx;
+    private options;
+    private resolved;
+    private renderer;
+    private maps;
+    private mapSize;
+    private pendingSize;
+    private env;
+    private fallbackImage;
+    private bakeToken;
+    private envToken;
+    private visible;
+    private destroyed;
+    private dirty;
+    private isReady;
+    private resolveReady;
+    private rejectReady;
+    private cleanups;
+    private pitch;
+    private yaw;
+    private hover;
+    private drag;
+    private coasting;
+    private spinning;
+    private time;
+    private shine;
+    private shineStart;
+    constructor(host: HTMLElement, options: BadgeOptions);
+    private ensureHostSize;
+    /** Merge new options. Only what changed is recomputed. */
+    update(partial: Partial<BadgeOptions>): void;
+    /** Replace all options. */
+    setOptions(options: BadgeOptions): void;
+    spin(turns?: number): void;
+    /** Sweep a highlight across the badge once. */
+    glint(): void;
+    toDataURL(type?: string, quality?: number): string;
+    toBlob(type?: string, quality?: number): Promise<Blob | null>;
+    destroy(): void;
+    private observe;
+    private resize;
+    private targetMapSize;
+    private rebuild;
+    private loadEnvironment;
+    private handleContextRestore;
+    private fail;
+    private markReady;
+    /** Without WebGL2, show the flat artwork. */
+    private loadFallback;
+    private paintFallback;
+    private invalidate;
+    private renderNow;
+    /** Scheduler callback: advance motion, redraw if needed. */
+    frame(dt: number): boolean;
+    private stopMotion;
+    private applyInteractionStyle;
+    private bindPointer;
+}
+/** Convenience factory. */
+declare function createBadge(host: HTMLElement, options: BadgeOptions): Badgecraft;
+
+export { Badgecraft as B, createBadge as c };

package/dist/badge-CCjUxNIG.d.cts

@@ -0,0 +1,79 @@
+import { b as BadgecraftHandle, B as BadgeOptions } from './types-CHM3-ZZV.cjs';
+
+/** One requestAnimationFrame loop for every badge on the page. */
+interface FrameTask {
+    /** Advance by `dt` seconds. Return true to keep receiving frames. */
+    frame(dt: number, now: number): boolean;
+}
+
+/**
+ * A badge rendered into `host`. Framework wrappers (React, Vue, the
+ * custom element) are thin layers over this class.
+ */
+declare class Badgecraft implements BadgecraftHandle, FrameTask {
+    readonly host: HTMLElement;
+    readonly canvas: HTMLCanvasElement;
+    /** Resolves once the badge has been baked and drawn; rejects if that fails. */
+    readonly ready: Promise<void>;
+    private ctx;
+    private options;
+    private resolved;
+    private renderer;
+    private maps;
+    private mapSize;
+    private pendingSize;
+    private env;
+    private fallbackImage;
+    private bakeToken;
+    private envToken;
+    private visible;
+    private destroyed;
+    private dirty;
+    private isReady;
+    private resolveReady;
+    private rejectReady;
+    private cleanups;
+    private pitch;
+    private yaw;
+    private hover;
+    private drag;
+    private coasting;
+    private spinning;
+    private time;
+    private shine;
+    private shineStart;
+    constructor(host: HTMLElement, options: BadgeOptions);
+    private ensureHostSize;
+    /** Merge new options. Only what changed is recomputed. */
+    update(partial: Partial<BadgeOptions>): void;
+    /** Replace all options. */
+    setOptions(options: BadgeOptions): void;
+    spin(turns?: number): void;
+    /** Sweep a highlight across the badge once. */
+    glint(): void;
+    toDataURL(type?: string, quality?: number): string;
+    toBlob(type?: string, quality?: number): Promise<Blob | null>;
+    destroy(): void;
+    private observe;
+    private resize;
+    private targetMapSize;
+    private rebuild;
+    private loadEnvironment;
+    private handleContextRestore;
+    private fail;
+    private markReady;
+    /** Without WebGL2, show the flat artwork. */
+    private loadFallback;
+    private paintFallback;
+    private invalidate;
+    private renderNow;
+    /** Scheduler callback: advance motion, redraw if needed. */
+    frame(dt: number): boolean;
+    private stopMotion;
+    private applyInteractionStyle;
+    private bindPointer;
+}
+/** Convenience factory. */
+declare function createBadge(host: HTMLElement, options: BadgeOptions): Badgecraft;
+
+export { Badgecraft as B, createBadge as c };

package/dist/chunk-3OMN635U.js

@@ -0,0 +1,44 @@
+// src/option-keys.ts
+var optionKeys = [
+  "svg",
+  "mode",
+  "metal",
+  "enamel",
+  "base",
+  "accent",
+  "color",
+  "frame",
+  "rim",
+  "outline",
+  "fillHoles",
+  "relief",
+  "environment",
+  "environmentRotation",
+  "exposure",
+  "toneMapping",
+  "interaction",
+  "tiltMax",
+  "pose",
+  "idle",
+  "locked",
+  "lockedColor",
+  "shadow",
+  "quality",
+  "padding",
+  "onReady",
+  "onError"
+];
+var optionKeySet = new Set(optionKeys);
+function pickOptions(source) {
+  const out = {};
+  for (const key of optionKeys) if (source[key] !== void 0) out[key] = source[key];
+  return out;
+}
+function cssSize(size, fallback = 160) {
+  const s = size ?? fallback;
+  return typeof s === "number" ? `${s}px` : s;
+}
+
+export { cssSize, optionKeySet, pickOptions };
+//# sourceMappingURL=chunk-3OMN635U.js.map
+//# sourceMappingURL=chunk-3OMN635U.js.map

package/dist/chunk-3OMN635U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/option-keys.ts"],"names":[],"mappings":";AAGO,IAAM,UAAA,GAAa;AAAA,EACxB,KAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA,KAAA;AAAA,EACA,SAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,aAAA;AAAA,EACA,qBAAA;AAAA,EACA,UAAA;AAAA,EACA,aAAA;AAAA,EACA,aAAA;AAAA,EACA,SAAA;AAAA,EACA,MAAA;AAAA,EACA,MAAA;AAAA,EACA,QAAA;AAAA,EACA,aAAA;AAAA,EACA,QAAA;AAAA,EACA,SAAA;AAAA,EACA,SAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF,CAAA;AAOO,IAAM,YAAA,GAAoC,IAAI,GAAA,CAAI,UAAU;AAG5D,SAAS,YAAY,MAAA,EAA+C;AACzE,EAAA,MAAM,MAA+B,EAAC;AACtC,EAAA,KAAA,MAAW,GAAA,IAAO,UAAA,EAAY,IAAI,MAAA,CAAO,GAAG,CAAA,KAAM,MAAA,EAAW,GAAA,CAAI,GAAG,CAAA,GAAI,MAAA,CAAO,GAAG,CAAA;AAClF,EAAA,OAAO,GAAA;AACT;AAEO,SAAS,OAAA,CAAQ,IAAA,EAAmC,QAAA,GAAW,GAAA,EAAa;AACjF,EAAA,MAAM,IAAI,IAAA,IAAQ,QAAA;AAClB,EAAA,OAAO,OAAO,CAAA,KAAM,QAAA,GAAW,CAAA,EAAG,CAAC,CAAA,EAAA,CAAA,GAAO,CAAA;AAC5C","file":"chunk-3OMN635U.js","sourcesContent":["import type { BadgeOptions } from './types'\n\n/** Every key of BadgeOptions, used by the framework wrappers to split props. */\nexport const optionKeys = [\n  'svg',\n  'mode',\n  'metal',\n  'enamel',\n  'base',\n  'accent',\n  'color',\n  'frame',\n  'rim',\n  'outline',\n  'fillHoles',\n  'relief',\n  'environment',\n  'environmentRotation',\n  'exposure',\n  'toneMapping',\n  'interaction',\n  'tiltMax',\n  'pose',\n  'idle',\n  'locked',\n  'lockedColor',\n  'shadow',\n  'quality',\n  'padding',\n  'onReady',\n  'onError',\n] as const satisfies readonly (keyof BadgeOptions)[]\n\n// Compile-time guard: adding an option without listing it here is a type error.\ntype Missing = Exclude<keyof BadgeOptions, (typeof optionKeys)[number]>\nconst exhaustive: Missing extends never ? true : Missing = true\nvoid exhaustive\n\nexport const optionKeySet: ReadonlySet<string> = new Set(optionKeys)\n\n/** Collect defined option values from an arbitrary props object. */\nexport function pickOptions(source: Record<string, unknown>): BadgeOptions {\n  const out: Record<string, unknown> = {}\n  for (const key of optionKeys) if (source[key] !== undefined) out[key] = source[key]\n  return out as unknown as BadgeOptions\n}\n\nexport function cssSize(size: number | string | undefined, fallback = 160): string {\n  const s = size ?? fallback\n  return typeof s === 'number' ? `${s}px` : s\n}\n"]}