shaderfont 0.0.0-stage → 0.5.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dongwoo Jeong
+
+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.ko.md

@@ -0,0 +1,63 @@
+# Shaderfont
+
+[English](./README.md)
+
+일반 웹 텍스트에 움직이는 재질과 드래그 효과를 붙이는 Web Component입니다. 기존 폰트를 그대로 쓰며, 텍스트를 선택·복사할 수 있습니다. 직접 편집하려면 `contenteditable="true"`를 넣습니다.
+
+## 사용
+
+```sh
+npm install shaderfont
+```
+
+브라우저에서 등록한 뒤 HTML에 넣습니다.
+
+```js
+import { registerShaderFont } from "shaderfont";
+
+const result = await registerShaderFont();
+if (!result.ok) throw new Error(result.error);
+```
+
+```html
+<shader-font shader="hologram" drag-effect="dissolve">
+  안녕하세요
+</shader-font>
+```
+
+`shader`에는 `noise`, `plasma`, `aurora`, `cyber`, `flame`, `waves` 같은 재질을 고릅니다. 디졸브는 선택한 글자만 서서히 가리고 선택을 해제하면 복구하며, 나머지 드래그 효과(`move`, `shake`, `elastic`)는 요소 전체를 움직입니다. `reveal-effect="burn"`으로 시간에 따른 등장도 넣을 수 있습니다. 각 효과는 `none`으로 끄고, 색상과 시간은 따로 조절합니다.
+
+## 동작 원리
+
+브라우저가 글자를 배치하고, CSS의 `background-clip: text`가 움직이는 무늬를 글자 안에만 보여 줍니다. 디졸브는 브라우저의 선택 범위(`Selection/Range`)를 읽어 해당 부분에 노이즈 마스크를 씌웁니다. 기본 렌더러는 Canvas 2D이며 `renderer="webgl"`을 고르면 절차적 재질과 마스크에 WebGL 2를 사용합니다. 홀로그램과 이동 효과는 CSS로 처리하며, 폰트 파일을 만들거나 METAFONT를 실행하지는 않습니다.
+
+루트 import는 SSR에서도 가능합니다. `registerShaderFont()`는 브라우저에서만 호출하고, 즉시 등록하는 `shaderfont/browser`도 브라우저에서만 사용합니다.
+
+### CSP와 색상
+
+인라인 스타일을 제한하는 사이트에서는 `<shader-font>`를 등록할 때 서버가 발급한 nonce를 전달합니다.
+
+```js
+const result = await registerShaderFont({ styleNonce: trustedNonce });
+if (!result.ok) throw new Error(result.error);
+```
+
+패키지는 스타일시트가 실제로 적용됐는지 확인합니다. 차단되면 `STYLES_BLOCKED`를 반환하며, 올바른 nonce로 다시 호출할 수 있습니다. DOM에서 임의의 nonce를 읽거나 CSP를 `unsafe-inline`으로 완화할 필요는 없습니다. 즉시 등록하는 `shaderfont/browser`에는 nonce 인자가 없으므로 CSP가 엄격한 페이지에서는 루트 등록 API를 사용합니다. 이미지도 제한한다면 절차적 재질과 디졸브·등장 마스크를 위해 `img-src`에 `data:`를 허용해야 합니다.
+
+색상 우선순위는 `primary`·`secondary`·`accent` 속성, 요소나 상위에서 지정한 `--sf-primary`·`--sf-secondary`·`--sf-accent` CSS 변수, 기본 밝은 팔레트 순서입니다. 페이지 테마가 바뀌어도 저장된 색상은 자동으로 덮지 않습니다. 어두운 배경에서는 `SHADER_FONT_PALETTES.find(p => p.name === "dark")`의 세 색을 요소 속성에 지정하고, 밝은 배경으로 돌아올 때 다시 밝은 팔레트를 지정하면 됩니다. 전역 흰색 변수가 글자에 직접 지정한 색을 덮지도 않습니다.
+
+## 데모
+
+저장소를 복제한 뒤 실행합니다.
+
+```sh
+npm run demo
+npm run check
+npm run check:browser
+```
+
+브라우저 검사는 로컬 Chrome에 엄격한 CSP를 적용해 nonce 실패·재시도, 밝고 어두운 색상, 홀로그램 애니메이션, 절차적 재질, 선택 디졸브, 타오르는 등장 효과와 움직임 줄이기를 확인합니다.
+
+[영어 데모](http://127.0.0.1:8766/demo/index.html)와 [한글 데모](http://127.0.0.1:8766/demo/index.ko.html)는 같은 설정과 편집 가능한 텍스트를 제공합니다.
+
+[MIT 라이선스](./LICENSE).

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# Shaderfont
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[한국어](./README.ko.md)
+
+A Web Component that adds animated materials and drag effects to ordinary DOM text. It uses your existing font and keeps text selectable and copyable. Add `contenteditable="true"` to edit it in place.
+
+## Use it
+
+```sh
+npm install shaderfont
+```
+
+Register it in the browser, then use the element in your HTML:
+
+```js
+import { registerShaderFont } from "shaderfont";
+
+const result = await registerShaderFont();
+if (!result.ok) throw new Error(result.error);
+```
+
+```html
+<shader-font shader="hologram" drag-effect="dissolve">
+  Hello
+</shader-font>
+```
+
+Choose a `shader` such as `noise`, `plasma`, `aurora`, `cyber`, `flame` or `waves`. Dissolve fades only the selected letters and restores them when you clear the selection. The other drag effects (`move`, `shake`, `elastic`) move the whole element. Set `reveal-effect="burn"` for a timed reveal. Each effect can be turned off with `none`; colors and timing are separate options.
+
+## How it works
+
+The browser lays out the text. CSS `background-clip: text` clips animated patterns to the letters, while dissolve reads the native `Selection/Range` and masks the selected part with noise. Canvas 2D is the default renderer; `renderer="webgl"` uses WebGL 2 for procedural materials and masks. Hologram and movement effects use CSS. The component does not generate font files or run METAFONT.
+
+The root import is safe for SSR. Call `registerShaderFont()` only in the browser; `shaderfont/browser` registers immediately and is browser-only.
+
+### CSP and colors
+
+On a site that disallows inline styles, pass the nonce supplied by your server **when registering** `<shader-font>`:
+
+```js
+const result = await registerShaderFont({ styleNonce: trustedNonce });
+if (!result.ok) throw new Error(result.error);
+```
+
+The package checks that its stylesheet actually loaded. A blocked style returns `STYLES_BLOCKED`; a later call with the right nonce can retry. Do not read an arbitrary nonce from the DOM or relax CSP with `unsafe-inline`. The immediate `shaderfont/browser` entry has no nonce parameter, so use the root registration API on strict-CSP pages. If your policy also restricts images, allow `data:` in `img-src` for procedural materials and dissolve/reveal masks.
+
+Colors follow this order: `primary`/`secondary`/`accent` attributes, then element or inherited `--sf-primary`/`--sf-secondary`/`--sf-accent` CSS variables, then the light palette. The package does not silently replace stored colors when the page changes theme. For a dark background, opt into `SHADER_FONT_PALETTES.find(p => p.name === "dark")` and set its three colors on the element; switch back to the light palette when needed. This also keeps an unrelated global white CSS variable from covering authored colors.
+
+## Try the demo
+
+Clone this repository and run:
+
+```sh
+npm run demo
+npm run check
+npm run check:browser
+```
+
+The browser check uses local Chrome and sends a strict CSP header. It covers nonce rejection/retry, light and dark colors, hologram animation, procedural material, selection dissolve, burn reveal and reduced motion.
+
+Open the [English demo](http://127.0.0.1:8766/demo/index.html) or [Korean demo](http://127.0.0.1:8766/demo/index.ko.html). Both have the same controls and editable text.
+
+[MIT license](./LICENSE).

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "shaderfont",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.4",
+  "type": "module",
+  "description": "Animated materials and selection effects on DOM text, with Canvas 2D and WebGL renderers.",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/srtdog64/shaderfont.git" },
+  "homepage": "https://github.com/srtdog64/shaderfont#readme",
+  "bugs": { "url": "https://github.com/srtdog64/shaderfont/issues" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "exports": {
+    ".": { "types": "./src/index.d.ts", "import": "./src/index.js", "default": "./src/index.js" },
+    "./options": { "types": "./src/options.d.ts", "import": "./src/options.js", "default": "./src/options.js" },
+    "./browser": { "types": "./src/browser.d.ts", "import": "./src/shader-font.js", "default": "./src/shader-font.js" }
+  },
+  "files": ["src", "README.md", "README.ko.md", "LICENSE"],
+  "sideEffects": ["./src/shader-font.js"],
+  "scripts": {
+    "check": "node --check src/core.js && node --check src/index.js && node --check src/options.js && node --check src/presets.js && node --check src/paint-layout.js && node --check src/selection-range.js && node --check src/selection-gesture.js && node --check src/selection-indicator.js && node --check src/webgl-surface.js && node --check src/material-core.js && node --check src/material-renderer.js && node --check src/mask-renderer.js && node --check src/reveal-core.js && node --check src/reveal-renderer.js && node --check src/shader-font-element.js && node --check demo/demo.js && node --check demo/copy.js && node --test",
+    "check:browser": "node tools/csp-browser-check.mjs",
+    "demo": "node tools/serve.mjs",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": { "playwright": "1.62.1" }
+}

package/src/browser.d.ts

@@ -0,0 +1,5 @@
+export class ShaderFont extends HTMLElement {
+  resetPosition(): void;
+  restartReveal(): void;
+}
+export function upgradeLegacyShaderfont(root?: ParentNode): ShaderFont[];

package/src/core.js

@@ -0,0 +1,316 @@
+import { ShaderPreset } from "./presets.js";
+export { ShaderPreset } from "./presets.js";
+
+const UINT32_MAX = 0xffffffff;
+
+export const GestureTag = Object.freeze({
+  IDLE: "idle",
+  PRESSED: "pressed",
+  ACTIVE: "active",
+  SELECTED: "selected",
+  RESTORING: "restoring"
+});
+
+export const DragEffect = Object.freeze({
+  NONE: "none",
+  DISSOLVE: "dissolve",
+  MOVE: "move",
+  SHAKE: "shake",
+  ELASTIC: "elastic"
+});
+
+const DRAG_EFFECTS = new Set(Object.values(DragEffect));
+const SHADER_PRESETS = new Set(Object.values(ShaderPreset));
+
+const ALLOWED_TRANSITIONS = Object.freeze({
+  [GestureTag.IDLE]: new Set([GestureTag.IDLE, GestureTag.PRESSED, GestureTag.RESTORING]),
+  [GestureTag.PRESSED]: new Set([GestureTag.IDLE, GestureTag.ACTIVE, GestureTag.RESTORING]),
+  [GestureTag.ACTIVE]: new Set([GestureTag.IDLE, GestureTag.SELECTED, GestureTag.RESTORING]),
+  [GestureTag.SELECTED]: new Set([GestureTag.IDLE, GestureTag.PRESSED, GestureTag.RESTORING]),
+  [GestureTag.RESTORING]: new Set([GestureTag.IDLE, GestureTag.PRESSED, GestureTag.RESTORING])
+});
+
+export function idleGesture() {
+  return Object.freeze({ tag: GestureTag.IDLE });
+}
+
+export function pressedGesture(mode, pointerId, startX, startY, baseX, baseY, effect = null) {
+  return Object.freeze({
+    tag: GestureTag.PRESSED,
+    mode,
+    effect: effect ?? (mode === "move" ? DragEffect.MOVE : DragEffect.DISSOLVE),
+    pointerId,
+    startX,
+    startY,
+    baseX,
+    baseY
+  });
+}
+
+export function resolveDragEffect(value, legacyInteraction = "select") {
+  if (DRAG_EFFECTS.has(value)) return value;
+  return legacyInteraction === "move" ? DragEffect.MOVE : DragEffect.DISSOLVE;
+}
+
+export function resolveShaderPreset(value) {
+  return SHADER_PRESETS.has(value) ? value : ShaderPreset.HOLOGRAM;
+}
+
+export function dissolveProgress(elapsedMs, durationMs) {
+  const elapsed = Math.max(0, Number(elapsedMs) || 0);
+  const duration = Math.max(1, Number(durationMs) || 1);
+  return clamp(elapsed / duration, 0, 1);
+}
+
+export function numberOption(value, fallback, minimum, maximum) {
+  if (value === null || value === undefined || String(value).trim() === "") return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? clamp(parsed, minimum, maximum) : fallback;
+}
+
+export function activeGesture(pressed) {
+  if (pressed.tag !== GestureTag.PRESSED) {
+    throw new TypeError(`activeGesture expects pressed, received ${pressed.tag}`);
+  }
+  return Object.freeze({ ...pressed, tag: GestureTag.ACTIVE });
+}
+
+export function selectedGesture(effect = DragEffect.DISSOLVE) {
+  return Object.freeze({ tag: GestureTag.SELECTED, effect });
+}
+
+export function restoringGesture(token) {
+  return Object.freeze({ tag: GestureTag.RESTORING, token });
+}
+
+export function assertGestureTransition(current, next) {
+  if (!ALLOWED_TRANSITIONS[current.tag]?.has(next.tag)) {
+    throw new Error(`Invalid shader-font gesture transition: ${current.tag} -> ${next.tag}`);
+  }
+  return next;
+}
+
+export function clamp(value, minimum, maximum) {
+  return Math.min(maximum, Math.max(minimum, value));
+}
+
+export function createElasticTransform(dx, dy, width) {
+  const safeWidth = Math.max(1, Number(width) || 1);
+  const safeDx = Number.isFinite(dx) ? dx : 0;
+  const safeDy = Number.isFinite(dy) ? dy : 0;
+  const distance = Math.hypot(safeDx, safeDy);
+  const amount = clamp(distance / (safeWidth * 0.58), 0, 1);
+  return Object.freeze({
+    x: clamp(safeDx * 0.14, -42, 42),
+    y: clamp(safeDy * 0.14, -30, 30),
+    scaleX: 1 + amount * 0.3,
+    scaleY: 1 - amount * 0.12,
+    rotate: clamp((safeDx / safeWidth) * 8, -5, 5),
+    amount
+  });
+}
+
+export function dampedSpringFactor(progress) {
+  const elapsed = clamp(Number(progress) || 0, 0, 1);
+  if (elapsed >= 1) return 0;
+  return Math.exp(-5.2 * elapsed) * Math.cos(elapsed * Math.PI * 5);
+}
+
+function smoothstep01(value) {
+  const t = clamp(value, 0, 1);
+  return t * t * (3 - 2 * t);
+}
+
+function quintic01(t) {
+  return t * t * t * (t * (t * 6 - 15) + 10);
+}
+
+function hash2(x, y, seed) {
+  let value = Math.imul((x | 0) ^ (seed | 0) ^ 0x68bc21eb, 0x27d4eb2d);
+  value ^= Math.imul((y | 0) ^ 0x02e5be93, 0x165667b1);
+  value ^= value >>> 15;
+  value = Math.imul(value, 0x85ebca6b);
+  value ^= value >>> 13;
+  return (value >>> 0) / UINT32_MAX;
+}
+
+function valueNoise(x, y, scale, seed) {
+  const px = x / scale;
+  const py = y / scale;
+  const ix = Math.floor(px);
+  const iy = Math.floor(py);
+  const fx = quintic01(px - ix);
+  const fy = quintic01(py - iy);
+  const a = hash2(ix, iy, seed);
+  const b = hash2(ix + 1, iy, seed);
+  const c = hash2(ix, iy + 1, seed);
+  const d = hash2(ix + 1, iy + 1, seed);
+  const top = a + (b - a) * fx;
+  const bottom = c + (d - c) * fx;
+  return top + (bottom - top) * fy;
+}
+
+function erosionNoise(x, y, baseScale, seed) {
+  const warpScale = baseScale * 1.7;
+  const warpX = (valueNoise(x + 43, y - 19, warpScale, seed ^ 0x27d4eb2d) - 0.5) * baseScale * 1.15;
+  const warpY = (valueNoise(x - 67, y + 31, warpScale, seed ^ 0x165667b1) - 0.5) * baseScale * 1.15;
+  const warpedX = x + warpX;
+  const warpedY = y + warpY;
+  const coarse = valueNoise(warpedX, warpedY, baseScale, seed);
+  const medium = valueNoise(warpedX + 131, warpedY - 79, Math.max(4, baseScale * 0.43), seed ^ 0x5bd1e995);
+  const fine = valueNoise(warpedX - 211, warpedY + 157, Math.max(2, baseScale * 0.18), seed ^ 0x85ebca6b);
+  return clamp(coarse * 0.54 + medium * 0.31 + fine * 0.15, 0, 1);
+}
+
+function validateMaskDimensions(width, height) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+    throw new RangeError("Mask dimensions must be positive integers");
+  }
+  if (width * height > 4_194_304) {
+    throw new RangeError("Mask dimensions exceed the 4-megapixel safety limit");
+  }
+}
+
+export function createErosionField(width, height, options = {}) {
+  validateMaskDimensions(width, height);
+  const seed = Number(options.seed ?? 0) | 0;
+  const baseScale = Math.max(10, Math.min(width, height) * 0.26);
+  const texture = new Float32Array(width * height);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      texture[y * width + x] = erosionNoise(x, y, baseScale, seed);
+    }
+  }
+  return texture;
+}
+
+export function hashText(text) {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+export function readingCoordinate(x, y, width, height, lineHeight, direction = "ltr") {
+  const safeWidth = Math.max(1, width);
+  const safeHeight = Math.max(1, height);
+  const safeLineHeight = clamp(lineHeight || safeHeight, 1, safeHeight);
+  const lineCount = Math.max(1, Math.ceil(safeHeight / safeLineHeight));
+  const line = clamp(Math.floor(y / safeLineHeight), 0, lineCount - 1);
+  const horizontal = clamp(x / Math.max(1, safeWidth - 1), 0, 1);
+  const withinLine = direction === "rtl" ? 1 - horizontal : horizontal;
+  return clamp((line + withinLine) / lineCount, 0, 1);
+}
+
+function alphaAt(signal, progress, feather) {
+  return Math.round(smoothstep01((signal - progress + feather) / (feather * 2)) * 255);
+}
+
+function normalizeRegions(width, height, regions) {
+  if (regions === undefined || regions === null) return [];
+  if (!Array.isArray(regions)) throw new TypeError("Mask regions must be an array");
+  return regions.flatMap(region => {
+    const x = Number(region?.x);
+    const y = Number(region?.y);
+    const regionWidth = Number(region?.width);
+    const regionHeight = Number(region?.height);
+    if (![x, y, regionWidth, regionHeight].every(Number.isFinite)) {
+      throw new TypeError("Mask region coordinates must be finite numbers");
+    }
+    if (regionWidth <= 0 || regionHeight <= 0) return [];
+    const left = clamp(x, 0, width);
+    const top = clamp(y, 0, height);
+    const right = clamp(x + regionWidth, 0, width);
+    const bottom = clamp(y + regionHeight, 0, height);
+    return right > left && bottom > top ? [{ left, top, right, bottom }] : [];
+  });
+}
+
+export function createMaskField(width, height, options = {}) {
+  validateMaskDimensions(width, height);
+  const selectedOnly = options.regions !== undefined && options.regions !== null;
+  const regions = normalizeRegions(width, height, options.regions);
+  const thresholds = new Float32Array(width * height);
+  thresholds.fill(Infinity);
+  const flow = options.flow ?? "reading";
+  const direction = options.direction === "rtl" || flow === "rtl" ? "rtl" : "ltr";
+  const lineHeight = clamp(Number(options.lineHeight ?? height), 1, height);
+  const roughness = clamp(Number(options.roughness ?? 0.26), 0, 0.48);
+  const feather = 0.025 + roughness * 0.08;
+  if (selectedOnly && regions.length === 0) return { width, height, thresholds, feather };
+  const seed = Number(options.seed ?? 0) | 0;
+  const texture = options.texture ?? createErosionField(width, height, { seed });
+  if (texture.length !== width * height) {
+    throw new RangeError("Erosion texture dimensions do not match the mask");
+  }
+  const erosionBand = clamp(0.34 + roughness * 1.35, 0.34, 0.98);
+
+  if (selectedOnly) {
+    const selectedErosionBand = 1.1 + roughness * 3;
+    const totalWidth = regions.reduce((sum, region) => sum + region.right - region.left, 0);
+    let precedingWidth = 0;
+    for (const region of regions) {
+      const firstX = Math.max(0, Math.ceil(region.left - 0.5));
+      const lastX = Math.min(width, Math.ceil(region.right - 0.5));
+      const firstY = Math.max(0, Math.ceil(region.top - 0.5));
+      const lastY = Math.min(height, Math.ceil(region.bottom - 0.5));
+      for (let y = firstY; y < lastY; y += 1) {
+        for (let x = firstX; x < lastX; x += 1) {
+          const index = y * width + x;
+          const distance = direction === "rtl" ? region.right - x - 0.5 : x + 0.5 - region.left;
+          const reading = (precedingWidth + distance) / totalWidth;
+          thresholds[index] = flow === "random" ? texture[index]
+            : (reading + selectedErosionBand * texture[index]) / (1 + selectedErosionBand);
+        }
+      }
+      precedingWidth += region.right - region.left;
+    }
+    // Spread burn times across the animation instead of concentrating them at mid-progress.
+    const bins = new Uint32Array(512);
+    let count = 0;
+    for (const threshold of thresholds) {
+      if (!Number.isFinite(threshold)) continue;
+      bins[Math.min(511, Math.floor(threshold * 512))] += 1;
+      count += 1;
+    }
+    const cumulative = new Uint32Array(512);
+    for (let bin = 1; bin < 512; bin += 1) cumulative[bin] = cumulative[bin - 1] + bins[bin - 1];
+    for (let index = 0; index < thresholds.length; index += 1) {
+      const threshold = thresholds[index];
+      if (!Number.isFinite(threshold)) continue;
+      const position = Math.min(511.999, threshold * 512);
+      const bin = Math.floor(position);
+      thresholds[index] = (cumulative[bin] + (position - bin) * bins[bin]) / count;
+    }
+  } else {
+    for (let y = 0; y < height; y += 1) {
+      for (let x = 0; x < width; x += 1) {
+        const index = y * width + x;
+        const reading = readingCoordinate(x, y, width, height, lineHeight, direction);
+        thresholds[index] = flow === "random" ? texture[index]
+          : (reading + erosionBand * texture[index]) / (1 + erosionBand);
+      }
+    }
+  }
+  return { width, height, thresholds, feather };
+}
+
+export function renderMaskAlpha(field, progress, output = new Uint8ClampedArray(field.width * field.height)) {
+  if (output.length !== field.thresholds.length) throw new RangeError("Mask output dimensions do not match the field");
+  const amount = clamp(Number(progress) || 0, 0, 1);
+  const thresholdProgress = amount * (1 + 2 * field.feather) - field.feather;
+  for (let index = 0; index < output.length; index += 1) {
+    const threshold = field.thresholds[index];
+    output[index] = !Number.isFinite(threshold) || amount === 0 ? 255
+      : amount === 1 ? 0 : alphaAt(threshold, thresholdProgress, field.feather);
+  }
+  return output;
+}
+
+export function createMaskAlpha(width, height, options = {}) {
+  const field = createMaskField(width, height, options);
+  const alpha = renderMaskAlpha(field, options.progress ?? 0);
+  return alpha;
+}

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export { SHADER_FONT_DEFAULTS, SHADER_FONT_PALETTES, SHADER_PRESETS, parseShaderFontOptions, shaderFontAttributes } from './options.js';
+export type { ShaderFontOptions } from './options.js';
+export function registerShaderFont(options?: { styleNonce?: string }): Promise<
+  | { ok: true }
+  | { ok: false; error: 'BROWSER_REQUIRED' | 'BROWSER_FEATURE_UNAVAILABLE' | 'INVALID_STYLE_NONCE' | 'STYLES_CONFLICT' | 'STYLES_BLOCKED' | 'REGISTRATION_FAILED'; cause?: string }
+>;

package/src/index.js

@@ -0,0 +1,25 @@
+export { SHADER_FONT_DEFAULTS, SHADER_FONT_PALETTES, SHADER_PRESETS, parseShaderFontOptions, shaderFontAttributes } from "./options.js";
+
+const STYLE_ERRORS = new Set(["INVALID_STYLE_NONCE", "STYLES_CONFLICT", "STYLES_BLOCKED"]);
+
+/** No DOM globals are evaluated until a browser explicitly requests effects. */
+export async function registerShaderFont({ styleNonce } = {}) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return { ok: false, error: "BROWSER_REQUIRED" };
+  }
+  if (typeof customElements === "undefined" || typeof HTMLElement === "undefined"
+      || typeof ResizeObserver === "undefined" || typeof MutationObserver === "undefined"
+      || typeof IntersectionObserver === "undefined" || typeof matchMedia !== "function") {
+    return { ok: false, error: "BROWSER_FEATURE_UNAVAILABLE" };
+  }
+  return import("./shader-font-element.js")
+    .then(module => {
+      module.registerShaderFontElement({ styleNonce });
+      return { ok: true };
+    })
+    .catch(cause => ({
+      ok: false,
+      error: STYLE_ERRORS.has(cause?.code) ? cause.code : "REGISTRATION_FAILED",
+      cause: cause instanceof Error ? cause.name : typeof cause
+    }));
+}

package/src/mask-renderer.js

@@ -0,0 +1,87 @@
+import { renderMaskAlpha } from "./core.js";
+
+import { createWebGLSurface, exportSurface, rendererError } from "./webgl-surface.js";
+
+const FRAGMENT_SHADER = `#version 300 es
+precision highp float;
+precision highp int;
+uniform highp sampler2D u_field;
+uniform int u_height;
+uniform float u_progress;
+uniform float u_feather;
+out vec4 fragColor;
+void main() {
+  // Field rows start at the top; the WebGL framebuffer starts at the bottom.
+  ivec2 pixel = ivec2(int(gl_FragCoord.x), u_height - 1 - int(gl_FragCoord.y));
+  float threshold = texelFetch(u_field, pixel, 0).r;
+  float alpha = 1.0;
+  if (threshold >= 0.0 && u_progress > 0.0) {
+    if (u_progress >= 1.0) alpha = 0.0;
+    else {
+      float progress = u_progress * (1.0 + 2.0 * u_feather) - u_feather;
+      float t = clamp((threshold - progress + u_feather) / (2.0 * u_feather), 0.0, 1.0);
+      alpha = t * t * (3.0 - 2.0 * t);
+    }
+  }
+  fragColor = vec4(1.0, 1.0, 1.0, alpha);
+}`;
+
+function canvasMask(canvas) {
+  const context = canvas.getContext("2d", { alpha: true });
+  if (!context) throw rendererError("CANVAS2D_UNAVAILABLE", "A Canvas 2D context is unavailable");
+  const image = context.createImageData(canvas.width, canvas.height);
+  image.data.fill(255);
+  const alpha = new Uint8ClampedArray(canvas.width * canvas.height);
+  return {
+    kind: "canvas2d", canvas,
+    render(field, progress) {
+      renderMaskAlpha(field, progress, alpha);
+      for (let index = 0; index < alpha.length; index += 1) image.data[index * 4 + 3] = alpha[index];
+      context.putImageData(image, 0, 0);
+      return exportSurface(canvas);
+    },
+    dispose() { canvas.width = canvas.height = 0; }
+  };
+}
+
+function webglMask(width, height, onContextLost) {
+  const surface = createWebGLSurface(width, height, FRAGMENT_SHADER, onContextLost);
+  const { gl } = surface;
+  let uploadedField = null;
+  try {
+    surface.texture();
+    gl.uniform1i(surface.uniform("u_field"), 0);
+    gl.uniform1i(surface.uniform("u_height"), height);
+    const progressUniform = surface.uniform("u_progress");
+    const featherUniform = surface.uniform("u_feather");
+    return {
+      kind: "webgl", canvas: surface.canvas, dispose: surface.dispose,
+      render(field, progress) {
+        if (uploadedField !== field) {
+          const thresholds = Float32Array.from(field.thresholds, value => Number.isFinite(value) ? value : -1);
+          gl.texImage2D(gl.TEXTURE_2D, 0, gl.R32F, field.width, field.height, 0, gl.RED, gl.FLOAT, thresholds);
+          if (gl.getError() !== gl.NO_ERROR) throw rendererError("WEBGL_TEXTURE_FAILED", "The mask field could not be uploaded");
+          uploadedField = field;
+        }
+        gl.uniform1f(progressUniform, progress);
+        gl.uniform1f(featherUniform, field.feather);
+        return surface.draw();
+      }
+    };
+  } catch (error) {
+    surface.dispose();
+    throw error;
+  }
+}
+
+/** The caller owns field geometry and time; this boundary only renders alpha. */
+export function createMaskRenderer(kind, width, height, onContextLost) {
+  if (kind !== "canvas2d" && kind !== "webgl") {
+    throw rendererError("INVALID_RENDERER", `Unknown mask renderer: ${kind}`);
+  }
+  if (kind === "webgl") return webglMask(width, height, onContextLost);
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  return canvasMask(canvas);
+}