vectorvesper 1.2.0 → 2.0.1

package/dist/hooks.json

@@ -0,0 +1,886 @@
+{
+  "version": "1.0.0",
+  "engineVersion": "0.3.0",
+  "generatedAt": "2026-07-26T08:44:11.000Z",
+  "contractLevel": "lean",
+  "hooks": [
+    {
+      "contractLevel": "lean",
+      "name": "useAdaptiveQuality",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "governor",
+      "tier": "free",
+      "tagline": "Device capability fused with live frame health — the complete quality signal.",
+      "problem": "Measured frame health is the truth but is blind for the first seconds; device signals guess instantly but never learn. Using either alone gets one of those wrong.",
+      "summary": "Probes the device once (WebGL2, GPU renderer string, memory, cores, reduced-motion) and fuses that with the live AnimationBudget as `tier = max(deviceTier, budgetTier)`. The device tier is a FLOOR, and that is the whole point: without it, weak devices oscillate forever — degrade, frames recover because you degraded, upgrade, jank, degrade. A software renderer stays a software renderer. `reasons` explains the device verdict.",
+      "signature": "useAdaptiveQuality(): AdaptiveState",
+      "options": [],
+      "returns": [
+        {
+          "name": "tier",
+          "type": "0 | 1 | 2",
+          "description": "Effective tier — max(deviceTier, budgetTier). Consume THIS one."
+        },
+        {
+          "name": "label",
+          "type": "\"high\" | \"medium\" | \"low\"",
+          "description": "Human-readable form of `tier`."
+        },
+        {
+          "name": "deviceTier",
+          "type": "0 | 1 | 2",
+          "description": "Static floor from the one-time hardware probe."
+        },
+        {
+          "name": "budgetTier",
+          "type": "0 | 1 | 2",
+          "description": "Live measured tier from AnimationBudget."
+        },
+        {
+          "name": "reasons",
+          "type": "string[]",
+          "description": "Why the device tier is what it is, e.g. [\"mobile-class GPU\"]. For HUDs and support."
+        },
+        {
+          "name": "reducedMotion",
+          "type": "boolean",
+          "description": "Whether the user asked for reduced motion."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useAdaptiveQuality } from \"@vectorvesper/motion/react\";\n\nexport function Scene() {\n  const { tier, reducedMotion } = useAdaptiveQuality();\n  if (reducedMotion) return <Poster />;\n  return tier === 0 ? <FullScene /> : <LightScene />;\n}",
+      "whenNotToUse": [
+        {
+          "when": "You have no WebGL, canvas or heavy effects on the page.",
+          "instead": "Skip it. The device probe creates a throwaway WebGL2 context to read the renderer string, which is not worth paying for on a page of text and CSS transitions."
+        },
+        {
+          "when": "You only need to respect prefers-reduced-motion.",
+          "instead": "Use `matchMedia(\"(prefers-reduced-motion: reduce)\")` directly."
+        },
+        {
+          "when": "You want to react to load only, ignoring the device.",
+          "instead": "Use `useAnimationBudget`. This hook deliberately clamps to a device floor and will not report tier 0 on a machine it judged weak, no matter how clean the frames are."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/adaptive-quality",
+      "labUrl": "https://vectorvesper.dev/lab/adaptive-quality",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "ownsTransform": false,
+        "conflictsWith": [],
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": true
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useAnimationBudget",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "governor",
+      "tier": "free",
+      "tagline": "A live quality tier from measured frame health, so effects can shed themselves.",
+      "problem": "A page looks fine on the machine it was built on and janks on the device it ships to, and nothing in the code knows the difference.",
+      "summary": "Measures real frame intervals on the shared conductor and collapses them into a coarse tier every effect can consume. Hysteresis is asymmetric on purpose: degrading is fast (users feel jank within a second), recovering takes 8 seconds of clean frames, so quality never flaps. Since v0.3 the thresholds are relative to the measured display refresh rate, so 70fps on a 120Hz panel correctly reads as degraded.",
+      "signature": "useAnimationBudget(): BudgetState",
+      "options": [],
+      "returns": [
+        {
+          "name": "tier",
+          "type": "0 | 1 | 2",
+          "description": "0 healthy, 1 shed extras, 2 survival mode. Consume this."
+        },
+        {
+          "name": "label",
+          "type": "\"high\" | \"medium\" | \"low\"",
+          "description": "Human-readable form of `tier`."
+        },
+        {
+          "name": "avgFrameMs",
+          "type": "number",
+          "description": "Rolling average frame interval in milliseconds."
+        },
+        {
+          "name": "slowRatio",
+          "type": "number",
+          "description": "Share of recent frames below the degradation line (~90% of display rate), 0..1."
+        },
+        {
+          "name": "headroom",
+          "type": "number",
+          "description": "Milliseconds still free in the current frame, smoothed. Negative means already over budget."
+        },
+        {
+          "name": "workMs",
+          "type": "number",
+          "description": "Milliseconds the motion runtime itself spent last frame. Everything else belongs to the browser, React or third-party scripts."
+        },
+        {
+          "name": "frameBudgetMs",
+          "type": "number",
+          "description": "One presented frame at the detected display rate."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useAnimationBudget } from \"@vectorvesper/motion/react\";\n\nexport function Hero() {\n  const { tier } = useAnimationBudget();\n  return (\n    <section>\n      {tier === 0 && <ExpensiveParticleLayer />}\n      <HeroContent />\n    </section>\n  );\n}",
+      "whenNotToUse": [
+        {
+          "when": "You want to gate a one-time expensive mount.",
+          "instead": "Use `useSafeToMount`. It answers \"may I mount now?\" once and latches, rather than giving you a value that keeps changing."
+        },
+        {
+          "when": "You need to know about the device before any frames have been measured.",
+          "instead": "Use `useAdaptiveQuality`, which fuses a static device probe with this budget. The budget alone is blind for its first ~40 frames."
+        },
+        {
+          "when": "You only need to respect prefers-reduced-motion.",
+          "instead": "Use a plain `matchMedia(\"(prefers-reduced-motion: reduce)\")` check. Starting a frame-measurement loop for an accessibility preference is disproportionate."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/animation-budget",
+      "labUrl": "https://vectorvesper.dev/lab/animation-budget",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "ownsTransform": false,
+        "conflictsWith": [],
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useImageTrail",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "effect",
+      "tier": "free",
+      "tagline": "Images spawn along the pointer's path and fade — the award-site gallery flourish.",
+      "problem": "The tutorial version creates a DOM node per pointer move and lets the garbage collector deal with it, which is exactly the allocation pattern that produces stutter.",
+      "summary": "A fixed pool of `<img>` nodes is created once and recycled. Each flight is animated with the Web Animations API, so there is no rAF loop and nothing is allocated per move — the oldest flight is simply cancelled and reused. Spawns are distance-gated, not event-gated, so the spacing stays even at any pointer speed. Fails open (does nothing) on touch devices and under reduced motion.",
+      "signature": "useImageTrail<T>(options: UseImageTrailOptions): { ref }",
+      "options": [
+        {
+          "name": "images",
+          "type": "string[]",
+          "default": "—",
+          "required": true,
+          "description": "Image sources, cycled in order. Preload or serve them small; a cold fetch mid-trail shows as a gap."
+        },
+        {
+          "name": "size",
+          "type": "number",
+          "default": "160",
+          "required": false,
+          "description": "Rendered width of each trail image in px. Height is automatic."
+        },
+        {
+          "name": "spacing",
+          "type": "number",
+          "default": "90",
+          "required": false,
+          "description": "Pointer distance between spawns in px. Lower is denser and more expensive."
+        },
+        {
+          "name": "life",
+          "type": "number",
+          "default": "900",
+          "required": false,
+          "description": "Flight duration in ms."
+        },
+        {
+          "name": "maxActive",
+          "type": "number",
+          "default": "10",
+          "required": false,
+          "description": "Pool size, i.e. maximum simultaneously visible images. This is a hard ceiling on cost."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<T | null>",
+          "description": "Attach to the container. The hook sets its position and overflow, and restores both on unmount."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useImageTrail } from \"@vectorvesper/motion/react\";\n\nexport function Gallery() {\n  const { ref } = useImageTrail<HTMLElement>({\n    images: [\"/a.jpg\", \"/b.jpg\", \"/c.jpg\"],\n  });\n  return <section ref={ref} className=\"relative h-[70vh]\">Move your cursor</section>;\n}",
+      "whenNotToUse": [
+        {
+          "when": "You want a single image that follows the cursor.",
+          "instead": "Use `useSensorBus` and write `transform` on one element. A pool and a spawn scheduler for one node is all overhead."
+        },
+        {
+          "when": "The site's primary audience is on mobile.",
+          "instead": "Use a scroll-triggered gallery reveal. This hook does nothing without a fine pointer, so mobile users would see an empty hero."
+        },
+        {
+          "when": "The images are content the user needs to see.",
+          "instead": "Use a real gallery grid. Trail images are decorative, `aria-hidden`, and visible for under a second each."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/image-trail",
+      "labUrl": "https://vectorvesper.dev/lab/image-trail",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "ownsTransform": false,
+        "conflictsWith": [
+          "A container with `overflow: visible` required — the hook sets overflow hidden to clip the trail."
+        ],
+        "usesPointer": true,
+        "usesScroll": false,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useLazyScene",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "gate",
+      "tier": "free",
+      "tagline": "Mount a heavy scene when it's near the viewport, the thread is idle, and frames are healthy.",
+      "problem": "A WebGL canvas three screens down initialises during page load, competing with the content the user is actually looking at.",
+      "summary": "Three gates in sequence: an IntersectionObserver with a generous rootMargin so the scene is ready just before it is seen; an idle-callback so it doesn't land mid-scroll; and a scroll-velocity check that defers while the user is actively moving. Optionally waits for the frame budget to recover, with a 3-second fail-open so a permanently busy page still eventually renders. Once mounted it stays mounted.",
+      "signature": "useLazyScene<T>(options?: UseLazySceneOptions): { ref, ready }",
+      "options": [
+        {
+          "name": "rootMargin",
+          "type": "string",
+          "default": "\"200px\"",
+          "required": false,
+          "description": "IntersectionObserver margin. Larger mounts earlier and wastes more when the user never scrolls there."
+        },
+        {
+          "name": "requireIdle",
+          "type": "boolean",
+          "default": "true",
+          "required": false,
+          "description": "Wait for requestIdleCallback (1500ms timeout) so mounting doesn't land in a busy frame."
+        },
+        {
+          "name": "deferWhileLow",
+          "type": "boolean",
+          "default": "false",
+          "required": false,
+          "description": "Also wait for the AnimationBudget to leave tier 2, capped at 3 seconds so it always fails open."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<T | null>",
+          "description": "Attach to the placeholder element. It must occupy real space or the observer never fires."
+        },
+        {
+          "name": "ready",
+          "type": "boolean",
+          "description": "False until every gate passes, then true for the rest of the mount."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useLazyScene } from \"@vectorvesper/motion/react\";\n\nexport function SceneSection() {\n  const { ref, ready } = useLazyScene<HTMLDivElement>();\n  return (\n    <div ref={ref} className=\"min-h-[60vh]\">\n      {ready ? <HeavyWebGLCanvas /> : <ScenePoster />}\n    </div>\n  );\n}",
+      "whenNotToUse": [
+        {
+          "when": "The content is above the fold.",
+          "instead": "Use `useSafeToMount`, which gates purely on frame headroom. Viewport gating is meaningless for something already on screen."
+        },
+        {
+          "when": "You only need to defer the JavaScript bundle.",
+          "instead": "Use `next/dynamic` or `React.lazy` alone. This hook gates the mount, not the download, and adds a runtime for a problem the bundler already solves."
+        },
+        {
+          "when": "You want a simple entrance animation when something scrolls into view.",
+          "instead": "Use a bare IntersectionObserver or a CSS scroll-driven animation. This hook is about deferring expensive work, not about revealing things."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/lazy-scene",
+      "labUrl": "https://vectorvesper.dev/lab/lazy-scene",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "ownsTransform": false,
+        "conflictsWith": [],
+        "usesPointer": false,
+        "usesScroll": true,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useMagneticIntent",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "interaction",
+      "tier": "free",
+      "tagline": "A magnetic button that starts reaching before the cursor gets there.",
+      "problem": "Every magnetic-button tutorial reacts to hover, so the element only starts moving once the cursor has already arrived — which is exactly too late to feel alive.",
+      "summary": "Engagement is max(PointerIntent confidence, proximity falloff), so the element begins reaching while the cursor is still on its way — the pre-touch that makes award-site buttons feel intentional. Writes only `transform`, and restores the previous inline transform exactly on unmount. Fails open to a perfectly normal element on touch-only devices and under reduced motion.",
+      "signature": "useMagneticIntent<T>(options?: MagneticOptions): { ref, active }",
+      "options": [
+        {
+          "name": "strength",
+          "type": "number",
+          "default": "12",
+          "required": false,
+          "description": "Maximum translation in px at full engagement."
+        },
+        {
+          "name": "reach",
+          "type": "number",
+          "default": "90",
+          "required": false,
+          "description": "Distance from centre, in px, where proximity pull begins."
+        },
+        {
+          "name": "damp",
+          "type": "number",
+          "default": "12",
+          "required": false,
+          "description": "Damping responsiveness. Higher tracks tighter, lower feels heavier."
+        },
+        {
+          "name": "scale",
+          "type": "number",
+          "default": "1.04",
+          "required": false,
+          "description": "Scale at full engagement. 1 disables scaling."
+        },
+        {
+          "name": "intent",
+          "type": "boolean",
+          "default": "true",
+          "required": false,
+          "description": "Use trajectory prediction for pre-attraction. False falls back to proximity only."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<T | null>",
+          "description": "Attach to the element. The hook owns its inline transform while mounted."
+        },
+        {
+          "name": "active",
+          "type": "boolean",
+          "description": "Whether the effect actually engaged. False on touch-only devices and under reduced motion."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useMagneticIntent } from \"@vectorvesper/motion/react\";\n\nexport function Cta() {\n  const { ref } = useMagneticIntent<HTMLButtonElement>();\n  return <button ref={ref}>Get started</button>;\n}",
+      "whenNotToUse": [
+        {
+          "when": "You want a simple hover lift or scale.",
+          "instead": "Use a CSS transition on transform. It runs on the compositor, costs no JavaScript, and needs no runtime at all."
+        },
+        {
+          "when": "The target is a primary action on a touch-first product.",
+          "instead": "Use a plain button with a clear pressed state. This hook is inert without a fine pointer, so on mobile you would be shipping the setup cost for nothing."
+        },
+        {
+          "when": "You need many magnetic elements in one dense grid.",
+          "instead": "Use one shared pointer-driven effect over the container. Each instance retains its own PointerIntent, and dozens of independent predictors is the wrong shape."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/magnetic-intent",
+      "labUrl": "https://vectorvesper.dev/lab/magnetic-element",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "ownsTransform": true,
+        "conflictsWith": [
+          "Anything else writing the same element's transform — framer-motion `animate`, GSAP tweens, Tailwind `hover:scale-*`, CSS transitions on transform.",
+          "A parent that also transforms during the same interaction, which compounds the offset."
+        ],
+        "usesPointer": true,
+        "usesScroll": false,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useNumberTicker",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "effect",
+      "tier": "free",
+      "tagline": "Animate a number to its target without re-rendering anything.",
+      "problem": "The obvious implementation re-renders the component sixty times a second to change one string, dragging every sibling through reconciliation for a counter.",
+      "summary": "Writes `textContent` directly on the target node from the shared frame loop, so React renders exactly once regardless of how far the number travels. Damping is frame-rate-independent, so it feels identical at 30 and 120fps, and it snaps and stops when close enough rather than easing forever. Enforces tabular figures so digits don't wobble the layout, and jumps straight to the target under reduced motion.",
+      "signature": "useNumberTicker<T>(value: number, options?: UseNumberTickerOptions): { ref }",
+      "options": [
+        {
+          "name": "k",
+          "type": "number",
+          "default": "6",
+          "required": false,
+          "description": "Damping responsiveness. Higher arrives faster and snappier; 6 is a smooth deceleration."
+        },
+        {
+          "name": "format",
+          "type": "Intl.NumberFormatOptions",
+          "default": "—",
+          "required": false,
+          "description": "Standard Intl options — currency, percent, decimal places, compact notation."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "default": "browser locale",
+          "required": false,
+          "description": "e.g. \"en-US\", \"de-DE\". Defaults to the user's locale."
+        },
+        {
+          "name": "prefix",
+          "type": "string",
+          "default": "\"\"",
+          "required": false,
+          "description": "Prepended to the formatted output, e.g. \"+\"."
+        },
+        {
+          "name": "suffix",
+          "type": "string",
+          "default": "\"\"",
+          "required": false,
+          "description": "Appended to the formatted output, e.g. \"%\" or \" ms\"."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<T | null>",
+          "description": "Attach to the element that displays the number. Its text content is owned by the hook."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useNumberTicker } from \"@vectorvesper/motion/react\";\n\nexport function Stat({ value }: { value: number }) {\n  const { ref } = useNumberTicker<HTMLSpanElement>(value);\n  return <span ref={ref} />;\n}",
+      "whenNotToUse": [
+        {
+          "when": "The number changes once and the animation is decorative.",
+          "instead": "Render it. A count-up on a static figure adds a frame loop and delays the fact the user came for."
+        },
+        {
+          "when": "You need the animated value in JavaScript, not just on screen.",
+          "instead": "Use `damp()` from the core in your own frame callback. This hook writes to the DOM and deliberately never surfaces the intermediate value to React."
+        },
+        {
+          "when": "It's a countdown timer or a clock.",
+          "instead": "Use a `setInterval` and render the formatted string. Those need to be exact at each step, and easing toward a time reads as broken."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/number-ticker",
+      "labUrl": "https://vectorvesper.dev/lab/number-ticker",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "ownsTransform": false,
+        "conflictsWith": [
+          "Rendering children into the same element — the hook overwrites its textContent every frame."
+        ],
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "usePointerIntent",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "interaction",
+      "tier": "free",
+      "tagline": "Know the pointer is coming 100–300ms before it arrives, and pre-warm.",
+      "problem": "Expensive hover states start their work at the moment of hover, so the first 200ms of every interaction is the user watching something load.",
+      "summary": "Casts the pointer's smoothed trajectory forward from the SensorBus and measures time-to-impact against the element's inflated rect. Confidence rises as impact nears; being inside is confidence 1. Enter/exit hysteresis keeps the boolean calm. Use it to start the video, compile the shader or fetch the preview before the cursor lands.",
+      "signature": "usePointerIntent<T>(options?: UsePointerIntentOptions): UsePointerIntentReturn<T>",
+      "options": [
+        {
+          "name": "horizon",
+          "type": "number",
+          "default": "0.5",
+          "required": false,
+          "description": "Look-ahead in seconds. Larger fires earlier and guesses more."
+        },
+        {
+          "name": "extend",
+          "type": "number",
+          "default": "12",
+          "required": false,
+          "description": "Rect inflation in px — how generous the target is."
+        },
+        {
+          "name": "minSpeed",
+          "type": "number",
+          "default": "80",
+          "required": false,
+          "description": "Below this pointer speed (px/s) prediction is off. Hover still counts."
+        },
+        {
+          "name": "enter",
+          "type": "number",
+          "default": "0.35",
+          "required": false,
+          "description": "Confidence needed to gain intent."
+        },
+        {
+          "name": "exit",
+          "type": "number",
+          "default": "0.18",
+          "required": false,
+          "description": "Confidence below which intent is lost. Keep it under `enter`."
+        },
+        {
+          "name": "dynamic",
+          "type": "boolean",
+          "default": "false",
+          "required": false,
+          "description": "Re-measure the element every frame while it is being approached. For carousels and animating targets; costs a layout read."
+        },
+        {
+          "name": "onChange",
+          "type": "(intent: boolean) => void",
+          "default": "—",
+          "required": false,
+          "description": "Fires on each intent transition, without needing the re-render."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<T | null>",
+          "description": "Attach to the target element."
+        },
+        {
+          "name": "intent",
+          "type": "boolean",
+          "description": "Hysteresis-gated. Safe to render on — it changes rarely, not per frame."
+        },
+        {
+          "name": "confidenceRef",
+          "type": "RefObject<number>",
+          "description": "Smoothed 0..1, updated per frame with no re-render. Read inside frame callbacks."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { usePointerIntent } from \"@vectorvesper/motion/react\";\n\nexport function PreviewCard() {\n  const { ref, intent } = usePointerIntent<HTMLDivElement>();\n  return (\n    <article ref={ref}>\n      {intent && <WarmVideoPreview />}   {/* mounts before the cursor arrives */}\n      <CardContent />\n    </article>\n  );\n}",
+      "whenNotToUse": [
+        {
+          "when": "The hover state is cheap — a colour change, an underline, a small transform.",
+          "instead": "Use CSS `:hover`. Predicting a repaint costs more than the repaint, and CSS runs off the main thread."
+        },
+        {
+          "when": "You are on a touch device.",
+          "instead": "Use `useLazyScene` or intersection-based warming. There is no pointer trajectory to extrapolate from a tap, so prediction has nothing to work with."
+        },
+        {
+          "when": "You need to know the pointer actually entered.",
+          "instead": "Use `onMouseEnter`. This hook fires on approach by design and will fire for pointers that pass by without landing."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/pointer-intent",
+      "labUrl": "https://vectorvesper.dev/lab/pointer-intent",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "ownsTransform": false,
+        "conflictsWith": [],
+        "usesPointer": true,
+        "usesScroll": false,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useSafeToMount",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "gate",
+      "tier": "free",
+      "tagline": "Hold an expensive mount until the main thread can actually absorb it.",
+      "problem": "An expensive component mounts during hydration, when the thread is already saturated, and its cost lands on top of the worst moment of the page's life.",
+      "summary": "Watches the frame loop and returns `true` only after a run of frames with real headroom to spare. One-way: once true it never goes back to false, because a component that unmounted itself the moment it made the page slow would oscillate forever. A hardware core-count floor short-circuits the whole check on very weak devices.",
+      "signature": "useSafeToMount(options?: UseSafeToMountOptions): boolean",
+      "options": [
+        {
+          "name": "minHeadroomMs",
+          "type": "number",
+          "default": "6",
+          "required": false,
+          "description": "Free time each qualifying frame must have left. Measured against the detected display rate, so 6 is about a third of a 60Hz frame and about three quarters of a 120Hz one — the same threshold means the same thing everywhere."
+        },
+        {
+          "name": "requiredCleanFrames",
+          "type": "number",
+          "default": "3",
+          "required": false,
+          "description": "Consecutive qualifying frames needed before the gate opens."
+        },
+        {
+          "name": "minCores",
+          "type": "number",
+          "default": "4",
+          "required": false,
+          "description": "Logical CPU cores below which the gate never opens at all. Permanent — cores do not improve while the page is open."
+        }
+      ],
+      "returns": [
+        {
+          "name": "safe",
+          "type": "boolean",
+          "description": "False until the thread is measurably calm, then true forever within this mount."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useSafeToMount } from \"@vectorvesper/motion/react\";\n\nexport function Dashboard() {\n  const canMount = useSafeToMount();\n  return canMount ? <AnalyticsChart /> : <ChartSkeleton />;\n}",
+      "whenNotToUse": [
+        {
+          "when": "The component is below the fold or off-screen.",
+          "instead": "Use `useLazyScene`, which adds viewport proximity and an idle-callback gate. Frame headroom alone will happily mount something nobody can see."
+        },
+        {
+          "when": "You want to keep tuning a scene that is already running.",
+          "instead": "Use `useAnimationBudget` or `useAdaptiveQuality`. This hook answers \"may I mount?\" once and latches; it will never tell you to scale back later."
+        },
+        {
+          "when": "The expensive thing is a network request or a bundle, not main-thread work.",
+          "instead": "Use `next/dynamic`, `React.lazy`, or a plain import. This measures CPU headroom, not bandwidth, and will happily mount a 2MB download on a healthy frame."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/safe-to-mount",
+      "labUrl": "https://vectorvesper.dev/lab/safe-to-mount",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "ownsTransform": false,
+        "conflictsWith": [],
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useSensorBus",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "sensor",
+      "tier": "free",
+      "tagline": "One set of pointer, scroll and viewport listeners for the whole page.",
+      "problem": "Ten effects that each attach their own pointermove and scroll listeners, and each compute their own velocity, do ten times the work to answer one question.",
+      "summary": "Retains a page-wide singleton that attaches passive listeners once and computes smoothed derivatives once per frame, in the conductor's input lane — before any consumer runs. Consumers READ a live snapshot during their own frame work. There are no per-event callbacks; the frame loop is the delivery mechanism. Lifecycle is ref-counted, so listeners detach when the last consumer unmounts.",
+      "signature": "useSensorBus(): SensorBus",
+      "options": [],
+      "returns": [
+        {
+          "name": "bus",
+          "type": "SensorBus",
+          "description": "Stable singleton reference. Read `bus.state.pointer` / `.scroll` / `.viewport` inside a frame callback. The reference never changes, so it is safe in a deps array."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { useSensorBus } from \"@vectorvesper/motion/react\";\nimport { getConductor } from \"@vectorvesper/motion\";\n\nexport function Follower() {\n  const ref = useRef<HTMLDivElement>(null);\n  const bus = useSensorBus();\n\n  useEffect(() => getConductor().subscribe(\"render\", () => {\n    const { x, y } = bus.state.pointer;\n    if (ref.current) ref.current.style.transform = `translate3d(${x}px, ${y}px, 0)`;\n  }), [bus]);\n\n  return <div ref={ref} className=\"fixed top-0 left-0 size-4 rounded-full bg-white\" />;\n}",
+      "whenNotToUse": [
+        {
+          "when": "You need a single isolated hover or click on one element.",
+          "instead": "Use plain `onMouseEnter` / `onClick` props. The bus is for continuous, page-wide values read every frame — a one-off discrete event is cheaper as a normal handler."
+        },
+        {
+          "when": "You need the pointer position inside a React render to drive layout.",
+          "instead": "Use local `useState` with a throttled handler and accept the re-renders. The bus deliberately does not re-render, so it cannot drive conditional JSX."
+        },
+        {
+          "when": "You need sub-frame input samples for drawing (high-rate stylus, signature pads).",
+          "instead": "Attach a dedicated `pointermove` listener and use `getCoalescedEvents()`. The bus is rAF-locked by design and reports one sample per frame."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/sensor-bus",
+      "labUrl": "https://vectorvesper.dev/lab/sensor-bus",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "ownsTransform": false,
+        "conflictsWith": [],
+        "usesPointer": true,
+        "usesScroll": true,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    },
+    {
+      "contractLevel": "lean",
+      "name": "useVideoScrubber",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "media",
+      "tier": "free",
+      "tagline": "Drive a video timeline from scroll or pointer, without the seek stutter.",
+      "problem": "Setting `video.currentTime` on every scroll event queues seeks faster than the decoder can serve them, and the result stutters — worst on Safari, worst on the demo you filmed.",
+      "summary": "Seek discipline is the whole product: never issue a seek while one is in flight, skip sub-frame deltas, use `fastSeek` for large jumps, and throttle adaptively when the decoder is measurably struggling. Also handles iOS priming (a muted play/pause round trip so Safari actually buffers), records and restores the video's attributes exactly, and stops seeking entirely when the track is off screen.",
+      "signature": "useVideoScrubber<TTrack>(options?: UseVideoScrubberOptions): UseVideoScrubberReturn<TTrack>",
+      "options": [
+        {
+          "name": "driver",
+          "type": "\"scroll\" | \"pointer\" | \"manual\"",
+          "default": "\"scroll\"",
+          "required": false,
+          "description": "What drives progress. Fixed for the instance lifetime."
+        },
+        {
+          "name": "mapping",
+          "type": "\"auto\" | \"pin\" | \"cross\"",
+          "default": "\"auto\"",
+          "required": false,
+          "description": "\"pin\" for tall sticky tracks (the Apple pattern), \"cross\" for a track passing through the viewport, \"auto\" picks pin above ~1.2 viewports."
+        },
+        {
+          "name": "smooth",
+          "type": "number",
+          "default": "8",
+          "required": false,
+          "description": "Damping responsiveness. 0 is instant. Forced to 0 under reduced motion."
+        },
+        {
+          "name": "pointerAxis",
+          "type": "\"x\" | \"y\"",
+          "default": "\"x\"",
+          "required": false,
+          "description": "Which axis of the track maps to progress, pointer driver only."
+        },
+        {
+          "name": "onProgress",
+          "type": "(progress: number, time: number) => void",
+          "default": "—",
+          "required": false,
+          "description": "Fires per frame when smoothed progress changes. Deduplicated."
+        }
+      ],
+      "returns": [
+        {
+          "name": "videoRef",
+          "type": "RefObject<HTMLVideoElement | null>",
+          "description": "Attach to the `<video>` element."
+        },
+        {
+          "name": "trackRef",
+          "type": "RefObject<TTrack | null>",
+          "description": "Attach to the element whose geometry defines progress. Defaults to the video's parent."
+        },
+        {
+          "name": "progressRef",
+          "type": "RefObject<number>",
+          "description": "Smoothed 0..1, updated per frame with no re-render."
+        },
+        {
+          "name": "scrubberRef",
+          "type": "RefObject<VideoScrubber | null>",
+          "description": "The controller. Use `.set(progress)` for the manual driver."
+        }
+      ],
+      "quickStart": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function ScrollScrub() {\n  const { videoRef, trackRef } = useVideoScrubber<HTMLDivElement>();\n  return (\n    <div ref={trackRef} style={{ height: \"300vh\" }}>\n      <div style={{ position: \"sticky\", top: 0, height: \"100vh\" }}>\n        <video ref={videoRef} src=\"/clip.mp4\" muted playsInline />\n      </div>\n    </div>\n  );\n}",
+      "whenNotToUse": [
+        {
+          "when": "You want a video that simply plays when it scrolls into view.",
+          "instead": "Use an IntersectionObserver and call `play()`. Scrubbing machinery for straight playback is pure overhead."
+        },
+        {
+          "when": "The sequence is short and you control the frames.",
+          "instead": "Preload an image sequence and swap `src`, or use a sprite sheet. For under ~60 frames this avoids the decoder entirely and cannot stutter."
+        },
+        {
+          "when": "You need frame-exact stepping for an editor or review tool.",
+          "instead": "Use `requestVideoFrameCallback` directly. This hook smooths and skips sub-frame deltas on purpose, which is the opposite of what frame-exact work needs."
+        }
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/video-scrubber",
+      "labUrl": "https://vectorvesper.dev/lab/video-scrubber",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent."
+      },
+      "runtime": {
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "ownsTransform": false,
+        "conflictsWith": [
+          "Any other code setting `video.currentTime`, or calling play() on the same element.",
+          "Smooth-scroll libraries that lie about scroll position (verify the mapping if you use one)."
+        ],
+        "usesPointer": true,
+        "usesScroll": true,
+        "usesWebGL": false
+      },
+      "upgrade": "This is the lean contract: enough to use the hook correctly. The full contract adds real-world recipes with code, accumulated dos and don'ts, scheduling detail for composing several effects on one page, and links to the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+    }
+  ]
+}