} style={{ ...style, borderRadius: \"50%\" }} />;\n}\n```\n\n**When to use `directDOM`:** decorative animated backgrounds, glow orbs, or any element where the animation should not trigger parent re-renders.\n**When not to use it:** when you need the `progress` value in React state (e.g. to drive other components).\n\nFor GPU-heavy scenes, cap animation updates with `maxFPS` (default `30`):\n\n```tsx\nuseGradient({\n type: \"radial\",\n animate: true,\n directDOM: true,\n cssAnimation: true, // compositor-driven path when supported\n webgl: true, // integrated WebGL mode in the same hook (no external libs)\n webglDprCap: 1.25, // reduce GPU load on high-DPR screens\n maxFPS: 24,\n});\n```\n```\n\n### useTimeline\n\n#### Single range per layer\n\nEach layer animates over one `start` → `end` scroll range. Flat keys on the layer object are the quickest API:\n\n```tsx\nimport { useTimeline } from \"@zuzjs/hooks\";\n\nfunction ScrollScene() {\n const { containerRef, layers, effects, layerStates, getLayerScrollRange } = useTimeline({\n mode: \"scroll\",\n sceneHeight: 2200,\n layers: [\n {\n id: \"intro\",\n start: 0,\n end: 0.25,\n opacity: { from: 0, to: 1 },\n y: [\"32px\", 0, \"easeOut\"],\n scale: { from: 0.96, to: 1 },\n },\n {\n id: \"expand\",\n start: 0.25,\n end: 0.8,\n opacity: { from: 0.7, to: 1 },\n borderRadius: [\"24px\", 0],\n perspective: [\"400px\", \"900px\"],\n rx: [\"12deg\", 0],\n ry: [\"-8deg\", 0],\n z: [\"-80px\", 0],\n scale3d: {\n x: { from: 0.92, to: 1 },\n y: { from: 0.92, to: 1 },\n z: { from: 1, to: 1 },\n },\n },\n {\n id: \"content\",\n start: 1,\n end: 0.8,\n opacity: { from: 1, to: 0 },\n },\n ],\n });\n\n const introRange = getLayerScrollRange(\"intro\");\n // introRange?.span = total scroll px consumed by the intro range\n\n return (\n
\n
\n Timeline-driven hero\n
\n
\n 3D transform scene\n
\n
\n expand active: {String(layerStates.expand.active)}\n {\" | intro px span: \"}{introRange?.span ?? 0}\n \n
\n );\n}\n```\n\n#### Multiple ranges per layer (`keyframes`)\n\nUse `keyframes` on a layer to chain several `start`/`end` ranges under the same ID. Each keyframe supports the same flat-key API as a single-range layer. Effects from each keyframe are applied in order — once a keyframe completes it holds its end state until the next one begins, giving seamless chaining.\n\n```tsx\nconst { containerRef, effects } = useTimeline({\n mode: \"scroll\",\n sceneHeight: 3000,\n layers: [\n {\n id: \"hero\",\n keyframes: [\n // Phase 1: enters from below while fading in\n { start: 0, end: 0.3, opacity: [0, 1], y: [\"60px\", 0, \"easeOut\"] },\n // Phase 2: scales down while drifting up\n { start: 0.3, end: 0.7, scale: [1, 0.85], y: [\"0px\", \"-40px\"] },\n // Phase 3: collapses and fades out\n { start: 0.7, end: 1.0, scale: [0.85, 0.1], opacity: [1, 0] },\n ],\n },\n ],\n});\n\nreturn (\n
\n);\n```\n\n`layers.hero` gives the overall 0→1 progress across the full `keyframes` timeline.\n`effects.hero` gives the merged CSS style for the currently active keyframe(s).\n\n#### Anchor references (`start`/`end` linked to other layers)\n\nYou can link `start`/`end` to another layer (or keyframe) instead of hardcoding numbers.\n\nSupported forms:\n\n- `\"hero\"` → defaults to `hero:end`\n- `\"hero:start\"` / `\"hero:end\"`\n- `\"hero#intro:end\"` (target keyframe by keyframe `id`)\n- `\"hero@0:start\"` (target keyframe by index)\n- `\"hero:end+0.03\"` / `\"hero:end-0.02\"` (offset in progress space)\n- `{ layerId: \"hero\", edge: \"end\", offset: 0.03 }`\n\n```tsx\nuseTimeline({\n mode: \"scroll\",\n interpolate: true,\n layers: [\n {\n id: \"heroGradient\",\n keyframes: [\n { id: \"shrink\", start: 1, end: 0.5, scale: [1, 0.3] },\n ],\n },\n {\n id: \"dashboard\",\n keyframes: [\n // Starts slightly after heroGradient ends, then eases in\n { start: \"heroGradient:end+0.03\", end: 0.78, y: [0, 200, \"easeOut\"] },\n ],\n },\n ],\n});\n```\n\nTip: if `start` and `end` resolve to the same point, the animation can look like a snap. Use an offset (`+0.02` to `+0.08`) or a larger range.\n\n#### Built-in debug overlay\n\nYou no longer need to render a debug panel in each page. Enable `debug: true` and `useTimeline` mounts a floating overlay on `document.body` automatically.\n\n```tsx\nuseTimeline({\n mode: \"scroll\",\n debug: process.env.NODE_ENV !== \"production\",\n // debugOverlay defaults to true\n // debugOverlay: false, // optional: disable built-in overlay\n layers: [...],\n});\n```\n\nThe overlay shows:\n\n- live `sceneHeight`, `viewportHeight`, `scrollTop`, `scrollProgress`\n- per-layer pixel ranges\n- px <-> progress conversions\n- **recommended offset hints** when a linked span is near-zero and likely to snap/flicker\n\n#### Apple-style reveal + stack example\n\nThis pattern reveals multiple objects in phases, then stacks/compresses them like a product scroll narrative.\n\n```tsx\nconst { containerRef, effects } = useTimeline({\n mode: \"scroll\",\n interpolate: true,\n lerpFactor: 0.08,\n layers: [\n {\n id: \"phone\",\n keyframes: [\n { id: \"enter\", start: 0.02, end: 0.2, opacity: [0, 1], y: [80, 0, \"easeOut\"], scale: [0.86, 1, \"easeOut\"] },\n { id: \"float\", start: \"phone#enter:end\", end: 0.48, y: [0, -18], ry: [0, -6], rx: [0, 4] },\n { id: \"stack\", start: \"cards#enter:end+0.02\", end: 0.85, y: [-18, -56], scale: [1, 0.88], opacity: [1, 0.95] },\n ],\n },\n {\n id: \"cards\",\n keyframes: [\n { id: \"enter\", start: \"phone#enter:end+0.02\", end: 0.58, opacity: [0, 1], y: [120, 0, \"easeOut\"], sx: [0.9, 1], sy: [0.9, 1] },\n { id: \"stack\", start: \"phone#stack:start\", end: 0.9, y: [0, 48], scale: [1, 0.84], opacity: [1, 0.82] },\n ],\n },\n {\n id: \"headline\",\n keyframes: [\n { start: 0, end: 0.16, opacity: [0, 1], y: [24, 0] },\n { start: \"phone#stack:start\", end: 0.92, opacity: [1, 0.1], y: [0, -40] },\n ],\n },\n ],\n});\n\nreturn (\n
\n \n
Powerful. Layered. Cinematic.
\n
\n {/* phone mock */}\n
\n
\n {/* card stack */}\n
\n
\n);\n```\n\n#### Smooth scroll mode (`interpolate`)\n\nBy default the playhead snaps directly to the scroll position on every frame. Set `interpolate: true` to lerp the playhead toward the scroll target — producing a smooth, inertia-like response:\n\n```tsx\nuseTimeline({\n mode: \"scroll\",\n interpolate: true,\n lerpFactor: 0.08, // 0.01 (very slow) → 0.5 (near-instant). Default: 0.1\n maxFPS: 45, // cap playhead state updates during scroll/lerp\n layers: [\n {\n id: \"hero\",\n entry: {\n duration: 800,\n delay: 80,\n opacity: [0, 1],\n y: [36, 0, \"easeOut\"],\n scale: [0.96, 1, \"easeOut\"],\n },\n keyframes: [\n { start: 0.08, end: 0.42, y: [0, -42] },\n ],\n },\n ],\n})\n```\n\n`entry` runs once per layer on mount and uses the same flat effect API as keyframes.\n\n#### Triggers\n\nEvery layer span, keyframe, and entry supports a `trigger` option that controls *when and how* the animation plays.\n\n##### Span / Keyframe trigger\n\n| Value | Behaviour |\n|---|---|\n| `\"timeline\"` (default) | Sticky chaining — once a span starts it holds its end-state until the next span takes over. Classic scroll timeline. |\n| `\"inView\"` | Active **only while** the playhead is inside this span's range. Reverses when you scroll back. |\n\n```tsx\n// Layer default — all keyframes on this layer reverse on scroll-back\n{\n id: \"card\",\n trigger: \"inView\",\n keyframes: [\n { start: 0.1, end: 0.3, y: [60, 0], opacity: [0, 1] },\n { start: 0.3, end: 0.6, scale: [1, 1.08] },\n ],\n}\n\n// Per-keyframe override — only this span reverses\n{\n id: \"badge\",\n keyframes: [\n { trigger: \"inView\", start: 0.2, end: 0.4, y: [40, 0] },\n { start: 0.4, end: 0.7, opacity: [1, 0] }, // sticky\n ],\n}\n```\n\n##### Entry trigger\n\n| Value | Behaviour |\n|---|---|\n| `\"mount\"` (default) | Runs **once** after the component mounts, then stops. |\n| `\"inView\"` | Progress is tied to the layer's scroll range — plays forward and **reverses** when you scroll back out. |\n\n```tsx\n// One-time mount animation (default)\n{\n id: \"hero\",\n entry: {\n duration: 700,\n y: [80, 0, \"$easing-spring\"], // $token → var(--easing-spring)\n opacity: [0, 1],\n },\n}\n\n// Reversible in-view entry — animates in/out as you scroll\n{\n id: \"feature\",\n start: 0.15,\n end: 0.45,\n entry: {\n trigger: \"inView\",\n y: [60, 0, \"easeOut\"], // inline tuple easing per property\n opacity: [0, 1],\n scale: [0.94, 1],\n },\n}\n```\n\n#### Value API\n\n`useTimeline` supports both forward ranges (`start: 0 → end: 0.5`) and reverse ranges (`start: 1 → end: 0.5`).\nUse `effects[layerId]` for auto-composed style output and `layers[layerId]` when you need direct 0→1 progress.\n\nFlat keys on a layer (or keyframe) accept `TransformValueEffect`:\n\n- **Object mode:** `{ from: \"24px\", to: 0, easing: \"easeOut\" }`\n- **Tuple mode:** `[\"24px\", 0, \"easeOut\"]`\n\nUnits are inferred from `from`/`to` — no separate `unit` field needed.\n\nEasing presets: `\"linear\"` | `\"easeIn\"` | `\"easeOut\"` | `\"easeInOut\"` or a custom `(t: number) => number`.\n\nIf easing is omitted, `useTimeline` defaults to `\"easeOut\"`.\n\n**Transform shorthand aliases** (work as flat keys or inside `transforms`):\n\n| Shorthand | CSS function |\n|---|---|\n| `x`, `y`, `z` | `translateX`, `translateY`, `translateZ` |\n| `rx`, `ry`, `rz` | `rotateX`, `rotateY`, `rotateZ` |\n| `sx`, `sy`, `sz` | `scaleX`, `scaleY`, `scaleZ` |\n| `skx`, `sky` | `skewX`, `skewY` |\n| `skew` | `skew(angle)` or `{ x, y }` pair |\n\n### useParallax\n\n### useParallax\n\n```tsx\nimport { useParallax } from \"@zuzjs/hooks\";\nimport { useRef } from \"react\";\n\nfunction GlowLayer() {\n const anchorRef = useRef
(null);\n const offset = useParallax(0.18, anchorRef);\n\n return (\n \n Floating glow layer\n
\n );\n}\n```\n\n`useParallax` and `useTimeline` automatically use `ScrollView`'s internal scroll container when mounted inside `ScrollView`, otherwise they use native window scroll.\n\nScroll updates are batched \\u2014 only one `requestAnimationFrame` is ever in flight at a time. Micro-changes below 0.5 px are skipped to avoid unnecessary re-renders.\n\n## Data and DB Usage\n\n### useDatabase\n\n```tsx\nimport { useDatabase } from \"@zuzjs/hooks\";\n\nfunction TodoStore() {\n const db = useDatabase({\n dbName: \"todos-db\",\n storeName: \"todos\",\n version: 1,\n keyPath: \"id\",\n });\n\n // db.add / db.get / db.update / db.remove pattern depends on your schema setup.\n return null;\n}\n```\n\n### DBProvider Hooks\n\n```tsx\nimport { DatabaseProvider, useDB, useWatchDB } from \"@zuzjs/hooks\";\n\nfunction Todos() {\n const db = useDB();\n useWatchDB(\"todos\", () => {\n // react to db mutations\n });\n return null;\n}\n```\n\n## Additional Exports\n\nThe package also exports related types and helpers, including:\n\n- Calendar and crop types: `CalendarMonthFormat`, `CalendarWeekdayFormat`, `CropShape`.\n- Keyboard and anchor enums: `KeyCode`, `AnchorType`.\n- Command and chart types: `Command`, `CommandActionProps`, `LineChartProps`, `DataPoint`.\n- DnD types: `DragSpec`, `DragProbe`, `DropSpec`, `DropProbe`.\n- DB provider utilities: `DatabaseProvider`, `DB_HEAL_BLOCKED_KEY`, `DB_HEAL_STATE_KEY`, `DB_HEALED_KEY`.\n- Timeline types: `TimelineLayer`, `TimelineKeyframe`, `TimelineLayerState`, `TimelineEffect`, `TimelineEasing`, `TimelineMode`, `TimelineOptions`, `TimelineTransformEffects`, `TransformValueEffect`, `TransformValueTuple`.\n- Gradient types: `UseGradientOptions`, `UseGradientResult`, `GradientType`, `GradientAnimation`, `GradientMotionPreset`, `GradientStop`, `OrbLayer`.\n\n## Notes\n\n- Hooks touching browser APIs must run in client-rendered environments.\n- Use TypeScript in your app to get strongly-typed options and return values for each hook.\n\n## License\n\nMIT","readmeFilename":"README.md"}