CatsJuice/sticker-forge

CatsJuice profile

Latest recorded source activity: August 1, 2026 at 13:35

SkillsMP catalog refreshed: October 17, 2026 at 00:09

skills collected: 1

GitHub stars: 745
GitHub forks: 67

Repository README

Repository README source: README.md

Read the source README

Expand full README

# Sticker Forge Sticker Forge turns text or uploaded image artwork into a tactile WebGL sticker. Grab the real die-cut edge, drag it inward, and the sticker curls to reveal a satin back surface with depth-aware shadowing. The repository contains two deliverables: - an interactive builder in `app/`; - a framework-independent Web Component and imperative API in `lib/`. ## Run locally Node.js 22.13 or newer is required. ```bash npm install npm run dev ``` Build the hosted app and both reusable library bundles with: ```bash npm run build ``` The reusable files are emitted to `public/embed/`: - `sticker-forge.es.js` — an ES module that auto-registers `<sticker-forge>`; - `sticker-forge.iife.js` — a classic script exposing `window.StickerForge`; - `sticker-forge.d.ts` — public TypeScript declarations. ## GitHub Pages Pushes to `main` deploy a static export through the GitHub Pages workflow at `.github/workflows/deploy-pages.yml`. Build the same artifact locally with: ```bash npm run build:pages ``` The production Pages site uses `https://sticker.oooo.so`. Its DNS record is a `CNAME` for the `sticker` subdomain pointing to `catsjuice.github.io`. The provided peel sound is trimmed, converted to mono, lightly high-passed, and inlined into both JavaScript bundles, so it does not need to be copied or hosted as a separate asset. The untouched source recording remains in `lib/assets/`. ## Copy-paste Web Component Copy both the ES bundle and this markup into any page. The bundle registers the element automatically; the idempotent `defineStickerForge()` helper is also exported and returns immediately (`void`). ```html <script type="module" src="/embed/sticker-forge.es.js"></script> <sticker-forge id="sticker" style="display:block;width:640px;height:420px" ></sticker-forge> <script type="module"> await customElements.whenDefined("sticker-forge"); const sticker = document.querySelector("#sticker"); sticker.setOptions({ outline: { width: 18, color: "#ffffff" }, shadow: { opacity: 0.22, blur: 22, distance: 16, angle: 42 }, lighting: { direction: { x: -0.38, y: 0.52, z: 0.76 }, intensity: 0.8, ambient: 0.35, softness: 0.6, }, peel: { radius: 0.12, stiffness: 0.72, maxAngle: 3.55, release: "reset", }, sound: { enabled: true, volume: 0.68 }, back: { color: "#f7f5f2", gloss: 0.7, roughness: 0.3 }, material: { type: "holographic", intensity: 0.86, scale: 1, }, tilt: -3, }); // setSource() is async: the promise settles after the texture is ready. await sticker.setSource({ type: "text", text: "PEEL ME", color: "#19191d", fontFamily: "Arial Rounded MT Bold, Arial Black, sans-serif", fontWeight: 900, }); sticker.addEventListener("peelchange", (event) => { console.log("peel", event.detail.progress); }); </script> ``` See [`examples/embed.html`](examples/embed.html) for a complete standalone page. ## Imperative JavaScript API If a custom element does not fit the host framework, mount the renderer into a normal element. `createSticker()` is asynchronous and resolves to the control object; renderer events are dispatched from the target element. ```html <div id="sticker-target" style="width:640px;height:420px"></div> <script type="module"> import { createSticker } from "/embed/sticker-forge.es.js"; const target = document.querySelector("#sticker-target"); target.addEventListener("peelend", (event) => { console.log("released at", event.detail.progress); }); const sticker = await createSticker(target, { source: { type: "text", text: "PEEL ME", color: "#19191d" }, peel: { radius: 0.12, maxAngle: 3.55 }, sound: { enabled: true, volume: 0.68 }, }); // Call before permanently removing the target in an SPA. // sticker.destroy(); </script> ``` For classic scripts, load `sticker-forge.iife.js` and call `await StickerForge.createSticker(...)`, as demonstrated by the standalone example. ## Inputs Text sources accept `text`, `color`, `fontFamily`, and `fontWeight`. The engine waits for the requested browser font before rebuilding the texture. Image sources accept any browser-decodable image URL, including data URLs made from PNG, WebP, JPEG, GIF, AVIF, or SVG uploads: ```js await sticker.setSource({ type: "image", src: imageDataUrl, name: file.name }); ``` The engine inspects decoded pixel alpha. Transparent images use their alpha silhouette for the die-cut outline; fully opaque images use their rectangular image boundary. Legacy SVG sources also accept raw markup; pre-sanitization is not required: ```js await sticker.setSource({ type: "svg", svg: svgMarkup }); ``` SVG input is processed locally. The library always removes scripts, event attributes, `foreignObject`, and external URL references before rasterization. `sanitizeSvgMarkup(svgMarkup)` is exported when the sanitized markup itself is needed. ## API The custom element and the object returned by the awaited `createSticker()` promise expose the same control surface: ```ts setSource(source): Promise<void> setOptions(partialOptions): void reset(): void resize(): void getState(): StickerState destroy(): void ``` For the imperative API, listen on the target element passed to `createSticker()`. For the Web Component, listen on `<sticker-forge>`; its peel and error events bubble across the shadow boundary. | Event | `event.detail` | | --- | --- | | `ready` | Imperative target: `{ width, height }`; Web Component: no detail | | `peelstart` | `{ amount, progress, origin }` | | `peelchange` | `{ amount, progress, direction? }` | | `peelend` | `{ amount, progress, willReset }` | | `detachcomplete` | `{ progress: 1 }` | | `error` | `{ message }` | `amount` and `progress` are the same normalized value from `0` (flat) to `1` (fully lifted). `origin` and `direction` are `{ x, y }` points in sticker-local coordinates. `peel.radius` is normalized to the sticker's short side (`0.12` means 12%), while `peel.maxAngle` is expressed in radians. `lighting.direction` is a normalized view-space vector pointing from the sticker toward the incoming directional light; it drives surface shading and projected-shadow direction together. `lighting.intensity` supports `0..1.5`, while `lighting.ambient` and `lighting.softness` use `0..1`. Shadow blur/distance use CSS pixels, `tilt` is expressed in degrees, and `peel.grabWidth` uses CSS pixels at 100% scale and scales with the sticker. The bundled recording is treated as an audio sprite rather than a timeline. Sticker Forge separates its lift, light crackle, strong tear, and release material, compensates for their different levels, and drives randomized grains from the drag velocity and acceleration. A slow peel is sparse, a fast peel is denser and brighter, holding still is silent, and reattaching uses a quieter low-passed texture instead of reversed audio. `progress` is used only for the initial lift and final release events. Set `sound.enabled` to `false` or `sound.volume` to `0` to mute it. Provide `sound.src` to replace the bundled sound with another browser-decodable audio URL; custom recordings use a duration-relative generic slice profile. `setOptions()` deep-merges nested option groups. Prefer the awaitable `setSource()` when changing artwork; passing `source` through `setOptions()` starts the same rebuild but cannot be awaited. `destroy()` should be called before a single-page application permanently removes an imperative sticker instance. A disconnected `<sticker-forge>` cleans itself up automatically. ### Front materials Set `material.type` to `original`, `holographic`, `glitter`, or `reflective`. `original` is the default and uses the same front rendering as Sticker Forge before selectable finishes were introduced. The other three finishes are procedural, respond to the live surface normal while peeling, and remain deterministic in Gallery previews and recorded exports. Use `material.intensity` in the `0..1` range and `material.scale` to resize procedural detail. `material.seed` keeps glitter flakes and similar detail stable between frames. ## Rendering notes - Three.js manages the WebGL scene, camera, geometry, and depth buffer. - Custom shaders keep the attached region rigid and bend only the peel front. - Front and back materials render separately according to face orientation. - The shadow is projected from the deformed surface instead of being a static box or CSS shadow. - Source alpha drives both visual clipping and boundary hit testing, so empty corners of an SVG bounding box cannot be grabbed. - Rendering idles when the sticker is flat; DPR and mesh density are capped for predictable mobile performance. The measured reference-video timeline and calibration values live in [`docs/reference-analysis.md`](docs/reference-analysis.md).

Loading the repository README…

Skills in this repository

Web Developers

1 occupation categories · 100% classified

skill

occupation

description

updated

minitool-zip-builder

Web Developers

小红书小工具构建开发指南：把 H5 页面打包成符合容器规范的离线 zip。新建或改写小工具 / H5 页面、打包小工具 zip、处理端能力限制与容器 CSP 约束时使用。

Source text: Chinese

2026-08-01

Showing 1 of 1 collected skills.

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/CatsJuice/sticker-forge.