glyphdust 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to **glyphdust** are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/), and the
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.1] — 2026-06-26
+
+Flexibility & polish release. Glyphdust is no longer scroll-and-hero only — it now
+drops into any box, plays without scroll, and ships tasteful presets you can override.
+**Defaults reproduce 0.2.0 exactly**, so upgrading is non-breaking.
+
+### Added
+
+- **`autoplay` driver** — time-based progress with no scroll choreography. Fits its
+  parent box and starts when scrolled into view (`playOnView`, default on). Options:
+  `duration`, `delay`, `loop`, `pingpong`, `playOnView`. Exposed
+  `computeAutoplayProgress()` for custom rigs.
+- **`preset` prop** — `"default" | "minimal" | "lively" | "glow"`: a tasteful bundle
+  of look + motion.
+- **`style` prop** — per-field overrides on top of the preset:
+  `size`, `blend` (`"normal" | "additive"`), `drift`, `sparkle`. Backed by new shader
+  uniforms (`uSizeScale`, `uDrift`, `uSparkle`); `additive` enables glow blending for
+  dark backgrounds.
+
+### Changed
+
+- Particles render finer and crisper on high-DPI screens: point-size base ×0.62,
+  clamp lowered to 4–5 px, and `devicePixelRatio` cap raised 2 → 3. (Validated on the
+  LINNO corporate site.)
+- Scroll follow no longer lags: stage progress is applied directly instead of an
+  internal lerp. Add inertia in your driver (e.g. Lenis) if you want it.
+
+### Fixed
+
+- No more blank gap when the **first keyframe is text** — particles now start in the
+  formed glyph and dissolve outward, instead of appearing only after the real text
+  fades.
+- `VERSION` export corrected (was a stale `"0.1.0"`).
+
+## [0.2.0] — 2026-06-23
+
+- Resolve to real DOM elements with pixel alignment; scrollbar & baseline fixes.
+
+## [0.1.0]
+
+- Initial public release: text → particles → glyph → real-text resolve, scroll-driven.

package/README.md

@@ -85,7 +85,34 @@ export function Hero() {
 - `domSelector` makes particles land exactly on an existing element's box and font — no jump on cross-fade.
 - `resolveToDom` on the final keyframe hands off from particles to crisp real text.
 
-### Drive it yourself (no scroll)
+### Just drop in text — no scroll choreography
+
+For anything that isn't a full-screen scroll hero, use the **`autoplay`** driver. It
+fits its parent box and plays once when it scrolls into view — drop it anywhere and it
+just animates:
+
+```tsx
+<div style={{ width: 480, height: 220 }}>
+  <GlyphDust
+    driver={{ type: "autoplay", duration: 3.5 }}   // loop / pingpong / delay too
+    preset="minimal"                                 // tasteful out of the box
+    keyframes={[
+      { type: "scatter" },
+      { type: "text", text: "glyphdust", dense: true },
+    ]}
+  />
+</div>
+```
+
+### Pick a look with presets (then tweak)
+
+```tsx
+<GlyphDust preset="glow" style={{ size: 1.2 }} keyframes={[/* … */]} />
+```
+
+`preset` is a tasteful starting point; `style` overrides just the fields you name.
+
+### Drive it yourself (manual)
 
 ```tsx
 const [p, setP] = useState(0); // 0 → 1 from time, GSAP, a slider, anything
@@ -105,7 +132,9 @@ const [p, setP] = useState(0); // 0 → 1 from time, GSAP, a slider, anything
 | prop | type | default | description |
 |---|---|---|---|
 | `keyframes` | `Keyframe[]` | — (required) | The animation timeline. Minimum 1; typically `text → scatter → text`. |
-| `driver` | `DriverConfig` | `{ type: "scroll" }` | Progress source: `scroll` or `manual`. |
+| `driver` | `DriverConfig` | `{ type: "scroll" }` | Progress source: `scroll`, `autoplay`, or `manual`. |
+| `preset` | `GlyphPreset` | `"default"` | Look/motion preset: `default`, `minimal`, `lively`, `glow`. |
+| `style` | `GlyphStyle` | — | Per-field overrides on top of `preset` (see below). |
 | `colors` | `GlyphColors` | see below | Particle ink / accent colors. |
 | `count` | `GlyphCount` | `{ desktop: 11000, mobile: 5200 }` | Particle count per device class. |
 | `timing` | `number[]` | even spacing | Normalized time `0..1` per keyframe (interpolation boundaries). Length must match `keyframes`. |
@@ -142,10 +171,35 @@ type Keyframe = TextKeyframe | ScatterKeyframe;
 ### Drivers
 
 ```ts
-{ type: "scroll", triggerHeight?: number }   // default triggerHeight: 2 (×100vh)
+{ type: "scroll", triggerHeight?: number }   // full-screen sticky hero. default triggerHeight: 2 (×100vh)
 { type: "manual", progress: number }         // you supply 0..1
+{ type: "autoplay",                          // time-based; fits its parent box
+  duration?: number,    // seconds for 0→1 (default 4)
+  delay?: number,       // start delay (default 0)
+  loop?: boolean,       // repeat (default false)
+  pingpong?: boolean,   // 0→1→0 when looping (default false)
+  playOnView?: boolean, // start when scrolled into view (default true)
+}
 ```
 
+`scroll` builds a tall sticky wrapper for a full-screen hero. `manual` and `autoplay`
+simply **fill their parent**, so you can place them in any sized container.
+
+### Presets & style
+
+```ts
+preset: "default" | "minimal" | "lively" | "glow"
+
+style: {
+  size?: number,                  // point-size multiplier (default 1)
+  blend?: "normal" | "additive",  // "additive" = glow, for dark backgrounds
+  drift?: number,                 // idle/scatter wander 0..1 (default 1; 0 = still)
+  sparkle?: number,               // sparkle strength 0..1 (default 1; 0 = off)
+}
+```
+
+`style` always wins over `preset`. Defaults reproduce the original look exactly.
+
 ### Colors
 
 ```ts
@@ -156,7 +210,7 @@ type Keyframe = TextKeyframe | ScatterKeyframe;
 
 ### Low-level helpers
 
-For custom rigs, the building blocks are exported too: `buildTextTargets`, `buildDenseTextTargets`, `buildVertexShader`, `FRAGMENT_SHADER`, `createScrollProgress`, `useScrollProgress`, `useReducedMotion`, `prefersReducedMotion`, `viewSizeAtZ0`, `buildGlyphFromDOM`, `computeScreenRect`.
+For custom rigs, the building blocks are exported too: `buildTextTargets`, `buildDenseTextTargets`, `buildVertexShader`, `FRAGMENT_SHADER`, `createScrollProgress`, `useScrollProgress`, `computeAutoplayProgress`, `useReducedMotion`, `prefersReducedMotion`, `viewSizeAtZ0`, `buildGlyphFromDOM`, `computeScreenRect`.
 
 ---
 
@@ -171,7 +225,7 @@ For custom rigs, the building blocks are exported too: `buildTextTargets`, `buil
 
 ## Status
 
-`0.1.0` — the component and API above are implemented and demoed (see [`examples/`](./examples)). Published from [LINNO](https://linno.co.jp). Semantic-versioned; expect minor API polish before `1.0`.
+`0.2.1` — the component and API above are implemented and demoed (see [`examples/`](./examples)) and [`CHANGELOG.md`](./CHANGELOG.md). Published from [LINNO](https://linno.co.jp). Semantic-versioned; expect minor API polish before `1.0`.
 
 ## License
 

package/dist/index.cjs

@@ -182,6 +182,8 @@ function buildVertexShader(keyframeCount) {
   uniform vec3 uPointer;
   uniform float uPointerActive;
   uniform float uSize;
+  uniform float uSizeScale;
+  uniform float uDrift;
   uniform float uPixelRatio;
 
 ${attributeDecls}
@@ -217,7 +219,7 @@ ${mixChain}
 
     // \u30A2\u30A4\u30C9\u30EB\u306E\u6F02\u3044\uFF08\u6574\u5217\u6642 settle / \u5B57\u5F62\u6642 form \u3067\u5F31\u3081\u308B\uFF09\u3002
     vSettle = uSettle;
-    float drift = (1.0 - uReduced) * (1.0 - uSettle * 0.9) * (1.0 - uForm);
+    float drift = (1.0 - uReduced) * (1.0 - uSettle * 0.9) * (1.0 - uForm) * uDrift;
     pos.x += sin(uTime * 0.35 + ph) * 0.06 * drift;
     pos.y += cos(uTime * 0.30 + ph * 1.7) * 0.06 * drift;
     pos.z += sin(uTime * 0.27 + ph * 2.3) * 0.06 * drift;
@@ -245,9 +247,11 @@ ${mixChain}
     float sizeVar = mix(0.55 + aSeed * 0.9, 0.72 + aSeed * 0.35, uSettle);
     // \u5B57\u5F62\u53CE\u675F\u6642\u306F\u96A3\u63A5\u7C92\u5B50\u3067\u9699\u9593\u3092\u57CB\u3081\u308B\u305F\u3081\u308F\u305A\u304B\u306B\u5927\u304D\u3081\uFF06\u5747\u4E00\u306B\u3002
     sizeVar = mix(sizeVar, 0.95 + aSeed * 0.18, uForm);
-    float s = uSize * sizeVar;
+    // \u9AD8 dpr \u74B0\u5883\u3067\u306F\u5C0F\u7C92\u30FB\u4E0A\u9650\u4F4E\u3081\u306E\u65B9\u304C\u30A8\u30C3\u30B8\u304C\u7DE0\u307E\u308A\u9AD8\u7CBE\u7D30\u306B\u898B\u3048\u308B
+    // \uFF08\u30B3\u30FC\u30DD\u30EC\u30FC\u30C8\u30B5\u30A4\u30C8\u5B9F\u88C5\u3067\u5B9F\u8A3C\u30020.62 \u3068 clamp 4\u301C5 \u304C\u6700\u3082\u300C\u971E\u307E\u306A\u3044\u300D\uFF09\u3002
+    float s = uSize * sizeVar * 0.62 * uSizeScale;
     gl_PointSize = s * uPixelRatio * (1.0 / -mvPosition.z);
-    gl_PointSize = clamp(gl_PointSize, 1.0, mix(7.0, 9.0, uForm) * uPixelRatio);
+    gl_PointSize = clamp(gl_PointSize, 1.0, mix(4.0, 5.0, uForm) * uPixelRatio);
   }
 `
   );
@@ -257,6 +261,7 @@ var FRAGMENT_SHADER = (
   `
   uniform vec3 uColorInk;
   uniform vec3 uColorAccent;
+  uniform float uSparkle;
 
   varying float vSeed;
   varying float vAccent;
@@ -278,7 +283,7 @@ var FRAGMENT_SHADER = (
 
     // \u4E00\u90E8\u306E\u7C92\u306B\u660E\u308B\u3044\u304D\u3089\u3081\u304D\uFF08\u98DB\u6563\u6642\u306B\u6620\u3048\u308B\uFF09\u3002\u6574\u5217\u6642\u306F\u63A7\u3048\u3081\u3002
     float spark = step(0.94, vSeed);
-    col = mix(col, uColorAccent, spark * mix(0.45, 0.15, vSettle));
+    col = mix(col, uColorAccent, spark * mix(0.45, 0.15, vSettle) * uSparkle);
 
     // \u5965\u884C\u304D\u3067\u6FC3\u6DE1\uFF08\u660E\u80CC\u666F\u3067\u306E\u8996\u8A8D\u6027\u78BA\u4FDD\u306E\u305F\u3081\u4E0B\u9650\u3092\u6301\u305F\u305B\u308B\uFF09\u3002
     float floorFade = mix(0.45, 0.78, vSettle);
@@ -412,6 +417,21 @@ function computeScreenRect(targets, viewportW, viewportH, visibleWorldW) {
   };
 }
 var DEFAULT_TRIGGER_HEIGHT = 2;
+function triangle(x) {
+  const t = x % 2;
+  return t <= 1 ? t : 2 - t;
+}
+function computeAutoplayProgress(elapsedSec, cfg) {
+  const duration = cfg.duration && cfg.duration > 0 ? cfg.duration : 4;
+  const delay = cfg.delay && cfg.delay > 0 ? cfg.delay : 0;
+  const t = elapsedSec - delay;
+  if (t <= 0) return 0;
+  const raw = t / duration;
+  if (cfg.loop) {
+    return cfg.pingpong ? triangle(raw) : raw % 1;
+  }
+  return clamp01(raw);
+}
 function clamp01(x) {
   return x < 0 ? 0 : x > 1 ? 1 : x;
 }
@@ -523,6 +543,7 @@ function GlyphPoints(props) {
     keyframes,
     count,
     colors,
+    style,
     cameraZ,
     cameraFov,
     pointer: pointerEnabled,
@@ -606,6 +627,9 @@ function GlyphPoints(props) {
       uPointer: { value: new THREE__namespace.Vector3(0, 0, 0) },
       uPointerActive: { value: 0 },
       uSize: { value: 1 },
+      uSizeScale: { value: style.size },
+      uDrift: { value: style.drift },
+      uSparkle: { value: style.sparkle },
       uPixelRatio: { value: 1 },
       uColorInk: { value: colors.ink.clone() },
       uColorAccent: { value: colors.accent.clone() }
@@ -803,9 +827,19 @@ function GlyphPoints(props) {
     const mat = matRef.current;
     if (!mat) return;
     const u = mat.uniforms;
-    u.uPixelRatio.value = Math.min(window.devicePixelRatio || 1, 2);
+    u.uPixelRatio.value = Math.min(window.devicePixelRatio || 1, 3);
     u.uSize.value = Math.min(size.height / 18, 26);
   }, [size]);
+  react.useEffect(() => {
+    const mat = matRef.current;
+    if (!mat) return;
+    const u = mat.uniforms;
+    u.uSizeScale.value = style.size;
+    u.uDrift.value = style.drift;
+    u.uSparkle.value = style.sparkle;
+    mat.blending = style.blend === "additive" ? THREE__namespace.AdditiveBlending : THREE__namespace.NormalBlending;
+    mat.needsUpdate = true;
+  }, [style.size, style.drift, style.sparkle, style.blend]);
   fiber.useFrame((state, delta) => {
     const p = pointsRef.current;
     const mat = matRef.current;
@@ -813,7 +847,7 @@ function GlyphPoints(props) {
     const u = mat.uniforms;
     const d = Math.min(delta, 0.05);
     const raw = THREE__namespace.MathUtils.clamp(getProgress(), 0, 1);
-    stage.current = THREE__namespace.MathUtils.lerp(stage.current, raw, 0.1);
+    stage.current = raw;
     const s = stage.current;
     let settle = 0;
     let burst = 0;
@@ -830,6 +864,11 @@ function GlyphPoints(props) {
     if (lastIsText && n >= 2) {
       form = smooth(times[n - 2] ?? 0, times[n - 1] ?? 1, s);
     }
+    const firstIsText = timeline.isText[0] === true;
+    if (firstIsText && n >= 2) {
+      const formStart = 1 - smooth(times[0] ?? 0, times[1] ?? 1, s);
+      form = Math.max(form, formStart);
+    }
     const guard = THREE__namespace.MathUtils.clamp(Math.max(settle, form), 0, 1);
     guardRef.current = guard;
     const swapped = raw >= timeline.swapAt ? 1 : 0;
@@ -880,7 +919,7 @@ function GlyphPoints(props) {
       uniforms,
       transparent: true,
       depthWrite: false,
-      blending: THREE__namespace.NormalBlending,
+      blending: style.blend === "additive" ? THREE__namespace.AdditiveBlending : THREE__namespace.NormalBlending,
       vertexShader,
       fragmentShader: FRAGMENT_SHADER
     }
@@ -894,6 +933,12 @@ var DEFAULT_COUNT_MOBILE = 5200;
 var DEFAULT_CAMERA_Z = 7;
 var DEFAULT_CAMERA_FOV = 42;
 var DEFAULT_DPR = [1, 1.75];
+var PRESETS = {
+  default: { size: 1, blend: "normal", drift: 1, sparkle: 1 },
+  minimal: { size: 0.92, blend: "normal", drift: 0.35, sparkle: 0 },
+  lively: { size: 1.05, blend: "normal", drift: 1.4, sparkle: 1.4 },
+  glow: { size: 1.1, blend: "additive", drift: 1.1, sparkle: 1.5 }
+};
 function clamp012(x) {
   return x < 0 ? 0 : x > 1 ? 1 : x;
 }
@@ -912,6 +957,8 @@ function GlyphDust(props) {
   const {
     keyframes,
     driver = { type: "scroll" },
+    preset = "default",
+    style,
     colors,
     count,
     dpr = DEFAULT_DPR,
@@ -935,15 +982,62 @@ function GlyphDust(props) {
   const resolveRef = react.useRef(null);
   const manualRef = react.useRef(0);
   if (driver.type === "manual") manualRef.current = clamp012(driver.progress);
+  const autoplay = driver.type === "autoplay" ? driver : null;
+  const playingRef = react.useRef(false);
+  const startMsRef = react.useRef(null);
+  const lastAutoRef = react.useRef(0);
+  react.useEffect(() => {
+    if (!autoplay) return;
+    if (autoplay.playOnView === false) {
+      playingRef.current = true;
+      return;
+    }
+    const el = wrapperRef.current;
+    if (el === null || typeof IntersectionObserver === "undefined") {
+      playingRef.current = true;
+      return;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        for (const e of entries) {
+          if (e.isIntersecting && !playingRef.current) {
+            playingRef.current = true;
+            startMsRef.current = null;
+          }
+        }
+      },
+      { threshold: 0.25 }
+    );
+    io.observe(el);
+    return () => io.disconnect();
+  }, [autoplay?.playOnView]);
   const getProgress = react.useCallback(() => {
     if (driver.type === "manual") return manualRef.current;
+    if (driver.type === "autoplay") {
+      if (!playingRef.current || typeof performance === "undefined") {
+        return lastAutoRef.current;
+      }
+      if (startMsRef.current === null) startMsRef.current = performance.now();
+      const elapsed = (performance.now() - startMsRef.current) / 1e3;
+      lastAutoRef.current = computeAutoplayProgress(elapsed, driver);
+      return lastAutoRef.current;
+    }
     const el = wrapperRef.current;
     if (el === null || typeof window === "undefined") return 0;
     const rect = el.getBoundingClientRect();
     const total = rect.height - window.innerHeight;
     if (total <= 0) return 0;
     return clamp012(-rect.top / total);
-  }, [driver.type]);
+  }, [driver]);
+  const resolvedStyle = react.useMemo(() => {
+    const base = PRESETS[preset] ?? PRESETS.default;
+    return {
+      size: style?.size ?? base.size,
+      blend: style?.blend ?? base.blend,
+      drift: style?.drift ?? base.drift,
+      sparkle: style?.sparkle ?? base.sparkle
+    };
+  }, [preset, style?.size, style?.blend, style?.drift, style?.sparkle]);
   const resolvedColors = react.useMemo(
     () => ({
       ink: new THREE__namespace.Color(colors?.ink ?? DEFAULT_INK),
@@ -980,6 +1074,7 @@ function GlyphDust(props) {
             keyframes,
             count: particleCount,
             colors: resolvedColors,
+            style: resolvedStyle,
             cameraZ,
             cameraFov,
             pointer: pointerEnabled,
@@ -1013,10 +1108,11 @@ function GlyphDust(props) {
       }
     ) : null
   ] });
-  if (driver.type === "manual") {
+  if (driver.type === "manual" || driver.type === "autoplay") {
     return /* @__PURE__ */ jsxRuntime.jsx(
       "div",
       {
+        ref: wrapperRef,
         className,
         style: { position: "relative", width: "100%", height: "100%" },
         children: scene
@@ -1048,7 +1144,7 @@ function GlyphDust(props) {
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.1";
 
 exports.DEFAULT_TRIGGER_HEIGHT = DEFAULT_TRIGGER_HEIGHT;
 exports.FRAGMENT_SHADER = FRAGMENT_SHADER;
@@ -1059,6 +1155,7 @@ exports.buildDenseTextTargets = buildDenseTextTargets;
 exports.buildGlyphFromDOM = buildGlyphFromDOM;
 exports.buildTextTargets = buildTextTargets;
 exports.buildVertexShader = buildVertexShader;
+exports.computeAutoplayProgress = computeAutoplayProgress;
 exports.computeScreenRect = computeScreenRect;
 exports.createScrollProgress = createScrollProgress;
 exports.glyphPositionAttribute = glyphPositionAttribute;