glyphdust 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+import * as react from 'react';
+import { RefObject, ReactNode } from 'react';
+
+/**
+ * sampling.ts — 文字 → 粒子ターゲット座標の生成。
+ *
+ * オフスクリーン Canvas にテキストを描画し、塗りピクセルをサンプリングして
+ * 各粒子のワールド座標ターゲット（Float32Array, xyz × count）を作る。
+ * フォント非依存・任意文字対応（CJK 含む）。
+ *
+ * 2 つの戦略:
+ *  - {@link buildTextTargets}      … 通常密度。読める字形をフォールバック付きで生成。
+ *  - {@link buildDenseTextTargets} … 高密度・均一カバレッジ。穴の目立たないワードマーク向け。
+ *
+ * いずれも SSR セーフ（`document` 不在時は原点クラスタ or 空配列を返し、例外を投げない）。
+ */
+/** 0..1 を返す乱数生成器。テスト時に決定論的な関数を注入できる。 */
+type Random = () => number;
+/** {@link buildTextTargets} のオプション。 */
+interface TextTargetOptions {
+    /** Canvas2D の `font` 文字列（例 `"600 64px 'Noto Sans JP', sans-serif"`）。 */
+    font: string;
+    /** 字形を収める可視ワールド幅。canvas 幅 `cw` 全体がこの幅にマップされる。 */
+    worldW: number;
+    /** 行送り（px, canvas 座標）。複数行のとき行間に使う。 */
+    lineHeight: number;
+    /** ワールド y オフセット（上が +）。既定 0。 */
+    offsetY?: number;
+    /** ワールド x オフセット（右が +）。既定 0。 */
+    offsetX?: number;
+    /** z 方向の厚み。既定 0.18。 */
+    thickness?: number;
+    /** ピクセル走査間隔。大きいほど粗く高速。既定 2。 */
+    step?: number;
+    /** オフスクリーン canvas 幅。既定 1280。 */
+    cw?: number;
+    /** オフスクリーン canvas 高さ。既定 480。 */
+    ch?: number;
+    /** テキスト寄せ。DOM 見出しと重ねるときは `"left"`。既定 `"center"`。 */
+    align?: "center" | "left";
+    /** 乱数生成器（ジッタ・フォールバック用）。既定 `Math.random`。 */
+    random?: Random;
+}
+/** {@link buildDenseTextTargets} のオプション。 */
+interface DenseTextTargetOptions {
+    /** Canvas2D の `font` 文字列。 */
+    font: string;
+    /** 字形を収める可視ワールド幅。 */
+    worldW: number;
+    /** ワールド y オフセット（上が +）。既定 0。 */
+    offsetY?: number;
+    /** ワールド x オフセット（右が +）。既定 0。 */
+    offsetX?: number;
+    /** z 方向の厚み。既定 0.08（字形塗りにきっちり乗せる）。 */
+    thickness?: number;
+    /** ピクセル走査間隔。密に拾うため既定 1。 */
+    step?: number;
+    /** オフスクリーン canvas 幅。既定 1280。 */
+    cw?: number;
+    /** オフスクリーン canvas 高さ。既定 400。 */
+    ch?: number;
+    /** 行送りを `ch` 比で指定。既定 0.46。 */
+    lineHeightRatio?: number;
+    /** 乱数生成器。既定 `Math.random`。 */
+    random?: Random;
+}
+/**
+ * テキスト行をオフスクリーン canvas に描画し、塗りピクセルをワールド座標ターゲットへ変換する。
+ *
+ * 割り当ては「連番ベース + 乗算ハッシュ散らし」で、塗りピクセルを均しく巡回カバーする。
+ * 塗りが 0 のときは {@link fillScatterCluster} へフォールバック。
+ *
+ * @param count 粒子数（戻り値は `count * 3` の Float32Array）
+ * @param lines 描画する行（文言は呼び出し側が決める。本関数は文言非依存）
+ */
+declare function buildTextTargets(count: number, lines: string[], opts: TextTargetOptions): Float32Array;
+/**
+ * 高密度・均一カバレッジで字形をサンプリングする（穴の目立たないワードマーク用）。
+ *
+ * 細かい step で塗りピクセルを収集 → 一度だけ Fisher–Yates シャッフル → 粒子へ巡回割当。
+ * 各塗りピクセルに `floor/ceil(count / filled)` 個がほぼ均等に乗り、粗密ムラ・穴を防ぐ。
+ * ジッタ・z 厚みは小さめにして字形塗りにきっちり乗せる。
+ */
+declare function buildDenseTextTargets(count: number, lines: string[], opts: DenseTextTargetOptions): Float32Array;
+
+/**
+ * shaders.ts — THREE.Points 用の GLSL（頂点 / フラグメント）。
+ *
+ * 位置補間は「キーフレーム数」に依存するため、頂点シェーダは
+ * {@link buildVertexShader} で動的生成する（GLSL は属性の動的添字を許さないので
+ * 隣接キーフレーム間の `mix` 連鎖をアンロールして埋め込む）。
+ *
+ * 演出スカラ（burst / drift / settle / form / swap / resolve）は
+ * 「どのキーフレームが scatter か text か」を知る CPU 側（GlyphPoints, useFrame）が
+ * 毎フレーム算出して uniform で渡す。これでシェーダはキーフレーム数だけに依存し、
+ * 意味論を持たない。
+ *
+ * 属性（GlyphPoints が設定）:
+ *  - `aPos0 .. aPos{N-1}` … 各キーフレームのターゲット座標（vec3）
+ *  - `aSeed`              … 0..1 個体差シード（ドリフト位相・サイズ・きらめき）
+ *  - `aAccent`            … 0/1 アクセント色フラグ
+ *
+ * uniform（頂点）:
+ *  - `uTimes[N]`     … 各キーフレームの正規化時刻 0..1（補間区間の境界）
+ *  - `uStage`        … 進捗 0..1（位置補間に使う。CPU 側で easing 済みでも可）
+ *  - `uTime`         … アイドル漂い用の時計（秒）
+ *  - `uForm`         … 0..1 字形に締まった度合い（サイズ均一化・ドリフト停止）
+ *  - `uSettle`       … 0..1 整列ホールド度合い（ドリフト減衰・エッジ締め）
+ *  - `uBurst`        … 0..1 外向き飛散量（飛散区間中で上げる）
+ *  - `uSwap`         … 0..1 可視ゲート（最初のスワップ点まで 0）
+ *  - `uResolve`      … 0..1 フィナーレで実 DOM 文字へ受け渡す減衰
+ *  - `uReduced`      … 0/1 reduced-motion
+ *  - `uPointer`      … vec3 ワールド空間のポインタ位置
+ *  - `uPointerActive`… 0/1 ポインタ反発の有効化
+ *  - `uSize`         … 基準点サイズ
+ *  - `uPixelRatio`   … dpr
+ *
+ * uniform（フラグメント）:
+ *  - `uColorInk` / `uColorAccent` … 配色
+ */
+/** 位置ターゲット属性の接頭辞。`aPos0`, `aPos1`, ... */
+declare const GLYPH_POSITION_ATTRIBUTE_PREFIX = "aPos";
+/** キーフレーム番号 i に対応する位置属性名を返す。 */
+declare function glyphPositionAttribute(index: number): string;
+/**
+ * キーフレーム数 N に対応する頂点シェーダ文字列を生成する。
+ *
+ * 隣接キーフレーム間を `smoothRange(uTimes[k], uTimes[k+1], uStage)` で補間し、
+ * `mix` 連鎖でつなぐ。各区間の t は順次 0→1 になるため、uStage が区間 k にあるとき
+ * 先行区間は t=1（次キーフレームへ到達済み）・後続は t=0 となり、正しく k→k+1 を補間する。
+ *
+ * @param keyframeCount キーフレーム数（>= 1）
+ * @throws keyframeCount < 1 のとき
+ */
+declare function buildVertexShader(keyframeCount: number): string;
+/**
+ * フラグメントシェーダ。キーフレーム数に依存しないため定数。
+ * 円形ソフト点 + アクセント色 + きらめき + 奥行き濃淡。
+ */
+declare const FRAGMENT_SHADER = "\n  uniform vec3 uColorInk;\n  uniform vec3 uColorAccent;\n\n  varying float vSeed;\n  varying float vAccent;\n  varying float vDepth;\n  varying float vForm;\n  varying float vAlpha;\n  varying float vSettle;\n\n  void main() {\n    // \u5186\u5F62\u306E\u30BD\u30D5\u30C8\u306A\u70B9\u3002\u4E2D\u5FC3\u3067 1\u3001\u7E01\u3067 0\uFF08smoothstep \u306F edge0<edge1 \u5FC5\u9808\u306A\u306E\u3067\u53CD\u8EE2\u3057\u3066\u4F7F\u3046\uFF09\u3002\n    vec2 uv = gl_PointCoord - 0.5;\n    float r = length(uv);\n    float alpha = 1.0 - smoothstep(0.12, 0.5, r);\n    if (alpha < 0.02) discard;\n\n    // \u4E3B\u4F53\u306F\u30A4\u30F3\u30AF\u3001\u4E00\u90E8\u306E\u7C92\u3060\u3051\u30A2\u30AF\u30BB\u30F3\u30C8\u8272\u3002\u5B57\u5F62\u53CE\u675F\u6642\u306F\u3084\u3084\u63A7\u3048\u3081\u306B\u3002\n    float accentAmt = vAccent * mix(0.85, 0.55, vForm);\n    vec3 col = mix(uColorInk, uColorAccent, accentAmt);\n\n    // \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\n    float spark = step(0.94, vSeed);\n    col = mix(col, uColorAccent, spark * mix(0.45, 0.15, vSettle));\n\n    // \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\n    float floorFade = mix(0.45, 0.78, vSettle);\n    float depthFade = clamp(1.0 - (vDepth - 3.0) * 0.10, floorFade, 1.0);\n\n    // \u6574\u5217\u6642\u306F\u4E0D\u900F\u660E\u5BC4\u308A\u306B\u3057\u3066\u30A8\u30C3\u30B8\u3092\u7DE0\u3081\u308B\u3002\n    float a = alpha * depthFade * vAlpha;\n    a = mix(a, clamp(a * 1.3, 0.0, 1.0), vSettle);\n\n    gl_FragColor = vec4(col, a);\n  }\n";
+
+/**
+ * dom-overlay.ts — 実 DOM 文字との重ね合わせ／受け渡しのための幾何ユーティリティ。
+ *
+ *  - {@link viewSizeAtZ0}      … カメラから z=0 平面の可視ワールド幅・高さを求める（screen↔world 変換の素）。
+ *  - {@link buildGlyphFromDOM} … 指定セレクタの DOM 要素の矩形・フォントから粒子ターゲットを生成。
+ *                                粒子字形が実 DOM 文字とピクセル単位で重なる（クロスフェードで文字が動かない）。
+ *  - {@link computeScreenRect} … 粒子ターゲット群の world 範囲を screen(px) 矩形へ変換。
+ *                                フィナーレで実 DOM 文字を同位置・同サイズに合わせるのに使う。
+ *
+ * いずれも SSR セーフ（`document` / `window` 不在時は null を返す）。
+ * グローバル変数や固定イベント名には依存しない（配信方法は呼び出し側が決める）。
+ */
+
+/** z=0 平面における可視ワールド寸法。 */
+interface ViewSize {
+    worldW: number;
+    worldH: number;
+}
+/**
+ * カメラ（縦 fov / z=cameraZ）から、z=0 平面の可視ワールド幅・高さを返す。
+ * screen(px) → world 変換のスケール算出に使う（等方: `worldW/viewportW === worldH/viewportH`）。
+ */
+declare function viewSizeAtZ0(viewportW: number, viewportH: number, fovDeg: number, cameraZ: number): ViewSize;
+/** {@link buildGlyphFromDOM} のオプション。 */
+interface DomGlyphOptions {
+    /** 対象 DOM 要素のセレクタ（`document.querySelector`）。 */
+    selector: string;
+    /** カメラ縦 fov（度）。canvas が viewport 全面の sticky 前提。 */
+    fovDeg: number;
+    /** カメラ z 位置。 */
+    cameraZ: number;
+    /** CSS px に対する描画倍率（文字を太く拾うため高め）。既定 2。 */
+    resolution?: number;
+    /** ピクセル走査間隔。既定 2。 */
+    step?: number;
+    /** z 方向の厚み。既定 0.14。 */
+    thickness?: number;
+    /** ベースライン近似に使うアセント比（fontSize に対する）。既定 0.82。 */
+    ascentRatio?: number;
+    /** 乱数生成器（ジッタ用）。既定 `Math.random`。 */
+    random?: Random;
+}
+/**
+ * 指定セレクタの DOM 要素の画面矩形・computed フォントから粒子ターゲットを生成する。
+ * - 要素の rect / computed font をそのまま使い、同サイズのオフスクリーン Canvas に行を描画。
+ * - 各塗りピクセルを「画面座標(px)」→「ワールド座標(z=0平面)」へ変換。
+ *   → 粒子字形が DOM 要素とピタリ重なり、クロスフェード中に文字が動かない。
+ * - 要素が無い / 小さすぎる / 塗りが 0 のときは null（呼び出し側でフォールバック）。
+ *
+ * @param count 粒子数（戻り値は `count * 3` の Float32Array）
+ * @param lines 描画する行（要素のテキストを行分割したもの。文言は呼び出し側が決める）
+ */
+declare function buildGlyphFromDOM(count: number, lines: string[], opts: DomGlyphOptions): Float32Array | null;
+/** 画面座標（px・左上原点）での字形矩形。実 DOM 文字を重ねるのに使う。 */
+interface GlyphScreenRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    /** 中心 x。 */
+    cx: number;
+    /** 中心 y。 */
+    cy: number;
+}
+/**
+ * 粒子ターゲット群（world 座標）の範囲を screen(px) 矩形へ変換する。
+ * z=0 / 無回転前提（フィナーレは正面復帰している前提で成立）。
+ *
+ * @param targets `[x,y,z, ...]` の Float32Array（build*Targets の戻り値）
+ * @param viewportW / viewportH 画面ピクセル寸法
+ * @param visibleWorldW z=0 平面の可視ワールド幅（{@link viewSizeAtZ0} の `worldW`）
+ * @returns 字形矩形。targets が空などで算出不能なら null。
+ */
+declare function computeScreenRect(targets: Float32Array, viewportW: number, viewportH: number, visibleWorldW: number): GlyphScreenRect | null;
+
+/**
+ * drivers.ts — 進捗 0→1 の供給源。
+ *
+ *  - scroll  … sticky トリガー領域のスクロール量から進捗を算出（標準）。
+ *  - manual  … 呼び出し側が `progress` を注入（時間・GSAP・任意）。
+ *
+ * 進捗ゲッターは「毎フレーム呼ばれる純粋な関数」として表現する（useFrame から polling）。
+ * SSR セーフ（`window` 不在時は 0 を返す）。
+ */
+
+/** sticky トリガー領域の既定高さ（×100vh）。 */
+declare const DEFAULT_TRIGGER_HEIGHT = 2;
+/** スクロール連動ドライバ設定。 */
+interface ScrollDriverConfig {
+    type: "scroll";
+    /**
+     * sticky トリガー領域の高さ（×100vh）。大きいほど演出がゆっくり進む。既定 {@link DEFAULT_TRIGGER_HEIGHT}。
+     * （ラッパー要素の高さ生成に使う。進捗式自体は要素実寸から算出するため値に依存しない。）
+     */
+    triggerHeight?: number;
+}
+/** 手動ドライバ設定（progress を外部制御）。 */
+interface ManualDriverConfig {
+    type: "manual";
+    /** 0..1 の進捗。 */
+    progress: number;
+}
+/** ドライバ設定の合併型。 */
+type DriverConfig = ScrollDriverConfig | ManualDriverConfig;
+/**
+ * 要素の sticky スクロール進捗 0→1 を返すゲッターを作る。
+ * 進捗 = `-rect.top / (rect.height - innerHeight)`（要素上端が viewport 上端を通過し切るまでで 0→1）。
+ * SSR / 要素 null 時は 0。
+ */
+declare function createScrollProgress(element: HTMLElement | null): () => number;
+/**
+ * sticky トリガー要素の ref からスクロール進捗ゲッターを返す React フック。
+ * 返り値は ref を遅延参照する安定した関数（useFrame からそのまま polling できる）。
+ */
+declare function useScrollProgress(ref: RefObject<HTMLElement | null>): () => number;
+
+/**
+ * useReducedMotion.ts — `prefers-reduced-motion: reduce` の購読。
+ *
+ * 演出を無効化（静的フォールバック表示）すべきかの判定に使う。
+ * SSR では false から始め、マウント後にメディアクエリへ同期する（ハイドレーション不一致回避）。
+ */
+/** 現在 reduced-motion かを同期的に返す（イベント購読なし。imperative 用）。 */
+declare function prefersReducedMotion(): boolean;
+/**
+ * `prefers-reduced-motion: reduce` を購読する React フック。
+ * 変更にも追随する。SSR セーフ（初期 false → マウント後に同期）。
+ */
+declare function useReducedMotion(): boolean;
+
+/**
+ * types.ts — glyphdust の公開型。
+ */
+
+/**
+ * テキストキーフレーム。文字を粒子字形にする。
+ * 改行は `\n` で明示する（`"次のユーザーは、\n人じゃない。"`）。
+ */
+interface TextKeyframe {
+    type: "text";
+    /** 描画テキスト。`\n` で行分割。 */
+    text: string;
+    /** Canvas2D の `font` 文字列。未指定なら密度に応じた既定。 */
+    font?: string;
+    /** 字形を収める可視ワールド幅。未指定なら可視幅からの既定比率。 */
+    worldW?: number;
+    /** ワールド x オフセット（右が +）。 */
+    offsetX?: number;
+    /** ワールド y オフセット（上が +）。 */
+    offsetY?: number;
+    /**
+     * 実 DOM 要素のセレクタ。指定すると、その要素の矩形・フォントに
+     * ピクセル単位で重なる字形を生成する（クロスフェード中に文字が動かない）。
+     */
+    domSelector?: string;
+    /**
+     * フィナーレでこの字形を実 DOM 文字へ解決（粒子を消し実テキストへクロスフェード）。
+     * 通常は最終キーフレームに付ける。
+     */
+    resolveToDom?: boolean;
+    /** 高密度・均一サンプリング（穴の目立たないワードマーク向け）。 */
+    dense?: boolean;
+}
+/** 飛散キーフレーム。粒子をランダム雲へ拡散する。 */
+interface ScatterKeyframe {
+    type: "scatter";
+    /** 拡散半径の倍率。既定 1。 */
+    spread?: number;
+}
+/** キーフレーム（テキスト or 飛散）。 */
+type Keyframe = TextKeyframe | ScatterKeyframe;
+/** 配色。 */
+interface GlyphColors {
+    /** 主体色（多数の粒）。既定 `#1b2330`。 */
+    ink?: string;
+    /** アクセント色（少数の粒）。既定 `#0055ff`。 */
+    accent?: string;
+    /** アクセント色になる粒の割合 0..1。既定 0.18。 */
+    accentRatio?: number;
+}
+/** デバイス別の粒子数。 */
+interface GlyphCount {
+    /** デスクトップの粒子数。既定 11000。 */
+    desktop?: number;
+    /** モバイル（<=768px）の粒子数。既定 5200。 */
+    mobile?: number;
+}
+/** カメラ設定。 */
+interface GlyphCamera {
+    /** z 位置。既定 7。 */
+    z?: number;
+    /** 縦 fov（度）。既定 42。 */
+    fov?: number;
+}
+/** インタラクション設定。 */
+interface GlyphInteraction {
+    /** ポインタ追従（近傍反発）。既定 true。 */
+    pointer?: boolean;
+    /** ドラッグ回転（慣性つき）。既定 true。 */
+    drag?: boolean;
+}
+/** {@link GlyphDust} の props。 */
+interface GlyphDustProps {
+    /** キーフレーム列（最低 1、通常 text → scatter → text）。 */
+    keyframes: Keyframe[];
+    /** 進捗ドライバ。既定 `{ type: "scroll" }`。 */
+    driver?: DriverConfig;
+    /** 配色。 */
+    colors?: GlyphColors;
+    /** デバイス別粒子数。 */
+    count?: GlyphCount;
+    /** r3f Canvas の dpr 範囲。既定 `[1, 1.75]`。 */
+    dpr?: [number, number];
+    /** インタラクション設定。 */
+    interaction?: GlyphInteraction;
+    /** カメラ設定。 */
+    camera?: GlyphCamera;
+    /**
+     * 各キーフレームの正規化時刻 0..1（補間境界）。
+     * 未指定なら等間隔。長さは keyframes と一致させる。
+     */
+    timing?: number[];
+    /** reduced-motion / WebGL 不可時に描画するフォールバック（真っ白防止）。 */
+    fallback?: ReactNode;
+    /** ラッパーに付けるクラス名。 */
+    className?: string;
+}
+
+declare function GlyphDust(props: GlyphDustProps): react.JSX.Element;
+
+/**
+ * glyphdust — scroll-driven text → particles → glyph → real-text resolve
+ * for react-three-fiber.
+ *
+ * 公開 API はこのファイルから re-export する（Task-007）。
+ * 雛形段階のプレースホルダ。実装は Phase 1 (Task-002〜) で追加する。
+ */
+/** ライブラリのバージョン（package.json と一致させる）。 */
+declare const VERSION = "0.1.0";
+
+export { DEFAULT_TRIGGER_HEIGHT, type DenseTextTargetOptions, type DomGlyphOptions, type DriverConfig, FRAGMENT_SHADER, GLYPH_POSITION_ATTRIBUTE_PREFIX, type GlyphCamera, type GlyphColors, type GlyphCount, GlyphDust, type GlyphDustProps, type GlyphInteraction, type GlyphScreenRect, type Keyframe, type ManualDriverConfig, type Random, type ScatterKeyframe, type ScrollDriverConfig, type TextKeyframe, type TextTargetOptions, VERSION, type ViewSize, buildDenseTextTargets, buildGlyphFromDOM, buildTextTargets, buildVertexShader, computeScreenRect, createScrollProgress, glyphPositionAttribute, prefersReducedMotion, useReducedMotion, useScrollProgress, viewSizeAtZ0 };