next-sketch 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reinan Br.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+<div align='center'>
+
+<h1>next-sketch</h1>
+
+[![npm version](https://img.shields.io/npm/v/next-sketch.svg)](https://www.npmjs.com/package/next-sketch)
+[![npm downloads](https://img.shields.io/npm/dm/next-sketch.svg)](https://www.npmjs.com/package/next-sketch)
+[![CI](https://github.com/reinanbr/next-sketch/actions/workflows/ci.yml/badge.svg)](https://github.com/reinanbr/next-sketch/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/next-sketch.svg)](https://www.npmjs.com/package/next-sketch)
+[![types](https://img.shields.io/npm/types/next-sketch.svg)](https://www.npmjs.com/package/next-sketch)
+[![license](https://img.shields.io/npm/l/next-sketch.svg)](LICENSE)
+
+<p>p5.js-style canvas sketches for React and Next.js — a headless hook plus a drop-in <code>&lt;CanvasSketch /&gt;</code> component. DPR-aware resizing, a requestAnimationFrame loop with <code>dt</code>/<code>time</code>/<code>frame</code>, normalized pointer/keyboard input, and full SSR safety, all in one dependency-free package.</p>
+
+</div>
+
+<hr>
+
+## Table of contents
+
+- [Why](#why)
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [API](#api)
+  - [`useCanvasSketch(options)`](#usecanvassketchoptions)
+  - [`<CanvasSketch />`](#canvassketch-)
+  - [`useThreeSketch(options)`](#usethreesketchoptions)
+  - [`<ThreeSketch />`](#threesketch-)
+  - [WebGL context budget](#webgl-context-budget)
+  - [`useInViewport(ref, options)`](#useinviewportref-options)
+  - [Utilities](#utilities)
+- [Next.js / SSR](#nextjs--ssr)
+- [License](#license)
+
+<hr>
+
+## Why
+
+Every hand-rolled canvas animation in React ends up rewriting the same plumbing: a
+`canvasRef`, a `devicePixelRatio`-aware resize handler, a `requestAnimationFrame` loop with
+manual `dt` bookkeeping, pointer coordinates translated through `getBoundingClientRect()`, and
+cleanup on unmount. `next-sketch` extracts that plumbing once so you can focus on `setup`/`draw`,
+the way you would in [p5.js](https://p5js.org) — but as an idiomatic React hook/component instead
+of a global-mode sketch.
+
+## Installation
+
+```sh
+npm install next-sketch
+```
+
+Requires React 18+. Works in any React app; the SSR-safety and `next/dynamic` friendliness make
+it a natural fit for Next.js specifically.
+
+## Quickstart
+
+```tsx
+import { CanvasSketch, randRange } from 'next-sketch';
+
+export default function Sketch() {
+  return (
+    <CanvasSketch
+      style={{ width: '100%', height: 400 }}
+      setup={({ ctx, width, height }) => {
+        // called once on mount, and again on every resize
+      }}
+      draw={({ ctx, width, height, dt, time, frame }) => {
+        ctx.fillStyle = '#0f172a';
+        ctx.fillRect(0, 0, width, height);
+        ctx.fillStyle = '#6366f1';
+        ctx.beginPath();
+        ctx.arc(width / 2 + Math.sin(time) * 100, height / 2, 20, 0, Math.PI * 2);
+        ctx.fill();
+      }}
+    />
+  );
+}
+```
+
+See [`examples/bouncing-particles.tsx`](examples/bouncing-particles.tsx) for a fuller example
+with particles, input, and a play/pause control.
+
+## API
+
+### `useCanvasSketch(options)`
+
+The headless engine. Returns a `canvasRef` to attach to your own `<canvas>`, plus imperative
+controls:
+
+```ts
+const { canvasRef, start, stop, reset, isRunning, running } = useCanvasSketch({
+  setup?: (info: SetupInfo) => void,
+  draw?: (info: DrawInfo) => void,
+  onPointerDown?: (info: PointerInfo) => void,
+  onPointerMove?: (info: PointerInfo) => void,
+  onPointerUp?: (info: PointerInfo) => void,
+  onKeyDown?: (event: KeyboardEvent) => void,
+  onKeyUp?: (event: KeyboardEvent) => void,
+  autoStart?: boolean, // default true
+});
+```
+
+- `SetupInfo` — `{ ctx, canvas, width, height }` (`width`/`height` in CSS pixels, already
+  DPR-normalized — draw as if `devicePixelRatio` were 1).
+- `DrawInfo` — `SetupInfo` plus `{ dt, time, frame }`: seconds since the last frame, seconds
+  since `start()`, and a frame counter. Both reset to zero on `reset()`.
+- `PointerInfo` — `{ x, y, event }`, `x`/`y` already localized to the canvas in CSS pixels.
+
+### `<CanvasSketch />`
+
+A thin `<canvas>` wrapper around the hook. Accepts the same options as props, plus `className`/
+`style`. Pass a `ref` to get a `CanvasSketchHandle` (`start`/`stop`/`reset`/`isRunning`) for
+building play/pause/reset UI without touching the hook directly.
+
+### `useThreeSketch(options)`
+
+The same engine as `useCanvasSketch`, but backed by [Three.js](https://threejs.org) instead of a
+2D context. `setup`/`draw` get `{ scene, camera, renderer, canvas, width, height }` (plus
+`dt`/`time`/`frame` in `draw`) instead of `ctx`; `renderer.render(scene, camera)` happens for you
+right after `draw` runs. Requires `three` as a peer dependency (`npm install three`) — it's not
+bundled, so sketches that only use the 2D engine pay nothing for it.
+
+```tsx
+import { ThreeSketch } from 'next-sketch';
+import * as THREE from 'three';
+
+<ThreeSketch
+  style={{ width: '100%', height: 400 }}
+  setup={({ scene }) => {
+    scene.add(new THREE.AmbientLight(0xffffff, 0.6));
+    const mesh = new THREE.Mesh(
+      new THREE.IcosahedronGeometry(1.5, 1),
+      new THREE.MeshStandardMaterial({ color: '#6366f1' }),
+    );
+    scene.add(mesh);
+  }}
+  draw={({ scene, dt }) => {
+    scene.children[1].rotation.y += dt;
+  }}
+/>
+```
+
+Unlike 2D canvas contexts, WebGL contexts are a scarce per-process browser resource — see
+[WebGL context budget](#webgl-context-budget) below, which `useThreeSketch` respects by default.
+
+On unmount, `useThreeSketch` disposes every geometry/material in the scene graph and calls
+`renderer.dispose()` + `renderer.forceContextLoss()`, so the context is actually freed rather than
+left for the garbage collector to get to eventually.
+
+### `<ThreeSketch />`
+
+A thin `<canvas>` wrapper around `useThreeSketch`, mirroring `<CanvasSketch />`: same
+`ref`-based `start`/`stop`/`reset`/`isRunning` handle, plus `className`/`style`.
+
+### WebGL context budget
+
+A page rendering several live 3D sketches at once (e.g. a gallery of animated previews) can hit
+the browser's per-process WebGL context limit — Chrome allows around 16, Safari's ceiling is
+often much lower. Past that limit, browsers silently evict the *oldest* context with no error;
+the canvas just goes blank. `useThreeSketch` guards against this automatically: each instance
+waits for a slot in a shared, module-level budget (default: 4 concurrent) before creating its
+renderer, and releases its slot on unmount.
+
+```ts
+import { configureWebglBudget, getWebglBudget } from 'next-sketch';
+
+configureWebglBudget(6); // raise/lower the app-wide cap
+getWebglBudget();        // -> { active: 2, max: 6 }
+```
+
+Opt a specific sketch out with `respectBudget: false` (e.g. for the one full, interactive
+simulation on a detail page, as opposed to a grid of decorative previews).
+
+### `useInViewport(ref, options)`
+
+```ts
+const wrapperRef = useRef<HTMLDivElement>(null);
+const inView = useInViewport(wrapperRef, { rootMargin: '200px', once: false });
+```
+
+Tracks whether an element is inside the viewport via `IntersectionObserver`, so you can mount an
+expensive sketch only while it's actually visible. With `once: true` (the default-ish choice for
+cheap 2D sketches) it stays `true` forever after the first intersection — no restart cost on
+scroll. With `once: false` it flips back to `false` when the element scrolls back out, which is
+what lets a `<ThreeSketch />` actually unmount and free its WebGL context budget slot in a long
+gallery page instead of accumulating contexts forever.
+
+### Utilities
+
+Small helpers factored out of the same duplicated math every canvas sketch ends up writing:
+
+```ts
+import { clamp, randRange, lerpColor } from 'next-sketch';
+
+clamp(value, min, max);              // -> number
+randRange(min, max);                 // -> number
+lerpColor([59,130,246], [239,68,68], t); // -> "rgb(r,g,b)"
+```
+
+## Next.js / SSR
+
+`useCanvasSketch`/`CanvasSketch` never touch `window`/`document` outside of effects, so they're
+safe to import in a Server Component tree. If you still prefer to opt a sketch fully out of SSR
+(e.g. it depends on `window` inside your own `draw` callback), wrap it the usual way:
+
+```tsx
+import dynamic from 'next/dynamic';
+const Sketch = dynamic(() => import('./Sketch'), { ssr: false });
+```
+
+## License
+
+MIT © [Reinan Br.](LICENSE)

package/dist/CanvasSketch.d.ts

@@ -0,0 +1,11 @@
+import type { CanvasSketchHandle, CanvasSketchOptions } from './types';
+export interface CanvasSketchProps extends CanvasSketchOptions {
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Drop-in `<canvas>` wired to useCanvasSketch. Pass `ref` to get imperative
+ * start()/stop()/reset()/isRunning() controls for building play/pause UI.
+ */
+export declare const CanvasSketch: import("react").ForwardRefExoticComponent<CanvasSketchProps & import("react").RefAttributes<CanvasSketchHandle>>;
+//# sourceMappingURL=CanvasSketch.d.ts.map

package/dist/CanvasSketch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasSketch.d.ts","sourceRoot":"","sources":["../src/CanvasSketch.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEvE,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,kHAQxB,CAAC"}

package/dist/CanvasSketch.js

@@ -0,0 +1,16 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanvasSketch = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const useCanvasSketch_1 = require("./useCanvasSketch");
+/**
+ * Drop-in `<canvas>` wired to useCanvasSketch. Pass `ref` to get imperative
+ * start()/stop()/reset()/isRunning() controls for building play/pause UI.
+ */
+exports.CanvasSketch = (0, react_1.forwardRef)(function CanvasSketch({ className, style, ...options }, ref) {
+    const { canvasRef, start, stop, reset, isRunning } = (0, useCanvasSketch_1.useCanvasSketch)(options);
+    (0, react_1.useImperativeHandle)(ref, () => ({ start, stop, reset, isRunning }), [start, stop, reset, isRunning]);
+    return (0, jsx_runtime_1.jsx)("canvas", { ref: canvasRef, className: className, style: style });
+});

package/dist/ThreeSketch.d.ts

@@ -0,0 +1,11 @@
+import type { ThreeSketchHandle, ThreeSketchOptions } from './types';
+export interface ThreeSketchProps extends ThreeSketchOptions {
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Drop-in `<canvas>` wired to useThreeSketch. Pass `ref` to get imperative
+ * start()/stop()/reset()/isRunning() controls for building play/pause UI.
+ */
+export declare const ThreeSketch: import("react").ForwardRefExoticComponent<ThreeSketchProps & import("react").RefAttributes<ThreeSketchHandle>>;
+//# sourceMappingURL=ThreeSketch.d.ts.map

package/dist/ThreeSketch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThreeSketch.d.ts","sourceRoot":"","sources":["../src/ThreeSketch.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAErE,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,gHAQvB,CAAC"}

package/dist/ThreeSketch.js

@@ -0,0 +1,16 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThreeSketch = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const useThreeSketch_1 = require("./useThreeSketch");
+/**
+ * Drop-in `<canvas>` wired to useThreeSketch. Pass `ref` to get imperative
+ * start()/stop()/reset()/isRunning() controls for building play/pause UI.
+ */
+exports.ThreeSketch = (0, react_1.forwardRef)(function ThreeSketch({ className, style, ...options }, ref) {
+    const { canvasRef, start, stop, reset, isRunning } = (0, useThreeSketch_1.useThreeSketch)(options);
+    (0, react_1.useImperativeHandle)(ref, () => ({ start, stop, reset, isRunning }), [start, stop, reset, isRunning]);
+    return (0, jsx_runtime_1.jsx)("canvas", { ref: canvasRef, className: className, style: style });
+});

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { useCanvasSketch } from './useCanvasSketch';
+export type { UseCanvasSketchResult } from './useCanvasSketch';
+export { CanvasSketch } from './CanvasSketch';
+export type { CanvasSketchProps } from './CanvasSketch';
+export { useThreeSketch } from './useThreeSketch';
+export type { UseThreeSketchResult } from './useThreeSketch';
+export { ThreeSketch } from './ThreeSketch';
+export type { ThreeSketchProps } from './ThreeSketch';
+export { useInViewport } from './useInViewport';
+export type { UseInViewportOptions } from './useInViewport';
+export { configureWebglBudget, getWebglBudget } from './webglBudget';
+export { clamp, randRange, lerpColor } from './utils';
+export type { RGB } from './utils';
+export type { SetupInfo, DrawInfo, PointerInfo, CanvasSketchOptions, CanvasSketchHandle, ThreeSetupInfo, ThreeDrawInfo, ThreeSketchOptions, ThreeSketchHandle, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACtD,YAAY,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AACnC,YAAY,EACV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lerpColor = exports.randRange = exports.clamp = exports.getWebglBudget = exports.configureWebglBudget = exports.useInViewport = exports.ThreeSketch = exports.useThreeSketch = exports.CanvasSketch = exports.useCanvasSketch = void 0;
+var useCanvasSketch_1 = require("./useCanvasSketch");
+Object.defineProperty(exports, "useCanvasSketch", { enumerable: true, get: function () { return useCanvasSketch_1.useCanvasSketch; } });
+var CanvasSketch_1 = require("./CanvasSketch");
+Object.defineProperty(exports, "CanvasSketch", { enumerable: true, get: function () { return CanvasSketch_1.CanvasSketch; } });
+var useThreeSketch_1 = require("./useThreeSketch");
+Object.defineProperty(exports, "useThreeSketch", { enumerable: true, get: function () { return useThreeSketch_1.useThreeSketch; } });
+var ThreeSketch_1 = require("./ThreeSketch");
+Object.defineProperty(exports, "ThreeSketch", { enumerable: true, get: function () { return ThreeSketch_1.ThreeSketch; } });
+var useInViewport_1 = require("./useInViewport");
+Object.defineProperty(exports, "useInViewport", { enumerable: true, get: function () { return useInViewport_1.useInViewport; } });
+var webglBudget_1 = require("./webglBudget");
+Object.defineProperty(exports, "configureWebglBudget", { enumerable: true, get: function () { return webglBudget_1.configureWebglBudget; } });
+Object.defineProperty(exports, "getWebglBudget", { enumerable: true, get: function () { return webglBudget_1.getWebglBudget; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "clamp", { enumerable: true, get: function () { return utils_1.clamp; } });
+Object.defineProperty(exports, "randRange", { enumerable: true, get: function () { return utils_1.randRange; } });
+Object.defineProperty(exports, "lerpColor", { enumerable: true, get: function () { return utils_1.lerpColor; } });

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+export interface SetupInfo {
+    ctx: CanvasRenderingContext2D;
+    canvas: HTMLCanvasElement;
+    /** CSS pixels — already DPR-normalized, matches what you'd draw with. */
+    width: number;
+    height: number;
+}
+export interface DrawInfo extends SetupInfo {
+    /** Seconds elapsed since the previous frame. */
+    dt: number;
+    /** Seconds elapsed since start() was called (resets on reset()). */
+    time: number;
+    /** Frame counter, resets on reset(). */
+    frame: number;
+}
+export interface PointerInfo {
+    /** Pointer position in CSS pixels, local to the canvas. */
+    x: number;
+    y: number;
+    event: PointerEvent;
+}
+export interface CanvasSketchOptions {
+    /** Called once after the canvas is mounted/sized, and again after every resize. */
+    setup?: (info: SetupInfo) => void;
+    /** Called every animation frame while running. */
+    draw?: (info: DrawInfo) => void;
+    onPointerDown?: (info: PointerInfo) => void;
+    onPointerMove?: (info: PointerInfo) => void;
+    onPointerUp?: (info: PointerInfo) => void;
+    onKeyDown?: (event: KeyboardEvent) => void;
+    onKeyUp?: (event: KeyboardEvent) => void;
+    /** Start the render loop automatically on mount. Default: true. */
+    autoStart?: boolean;
+}
+export interface CanvasSketchHandle {
+    start: () => void;
+    stop: () => void;
+    /** Stops the loop and resets time/frame back to zero (does not clear the canvas). */
+    reset: () => void;
+    isRunning: () => boolean;
+}
+export interface ThreeSetupInfo {
+    scene: import('three').Scene;
+    camera: import('three').PerspectiveCamera;
+    renderer: import('three').WebGLRenderer;
+    canvas: HTMLCanvasElement;
+    /** CSS pixels. */
+    width: number;
+    height: number;
+}
+export interface ThreeDrawInfo extends ThreeSetupInfo {
+    /** Seconds elapsed since the previous frame. */
+    dt: number;
+    /** Seconds elapsed since start() was called (resets on reset()). */
+    time: number;
+    /** Frame counter, resets on reset(). */
+    frame: number;
+}
+export interface ThreeSketchOptions {
+    /** Called once after scene/camera/renderer are created and sized, and again after every resize. */
+    setup?: (info: ThreeSetupInfo) => void;
+    /** Called every animation frame while running, right before renderer.render(scene, camera). */
+    draw?: (info: ThreeDrawInfo) => void;
+    onPointerDown?: (info: PointerInfo) => void;
+    onPointerMove?: (info: PointerInfo) => void;
+    onPointerUp?: (info: PointerInfo) => void;
+    onKeyDown?: (event: KeyboardEvent) => void;
+    onKeyUp?: (event: KeyboardEvent) => void;
+    /** Start the render loop automatically on mount. Default: true. */
+    autoStart?: boolean;
+    /** Default PerspectiveCamera field of view, in degrees. Default: 50. */
+    fov?: number;
+    near?: number;
+    far?: number;
+    /** Forwarded to `new THREE.WebGLRenderer(...)`. `canvas` is always set for you. */
+    rendererOptions?: Omit<import('three').WebGLRendererParameters, 'canvas'>;
+    /**
+     * Wait for a slot in the global WebGL context budget (see
+     * `configureWebglBudget`) before creating the renderer. Default: true.
+     * Browsers silently evict the oldest WebGL context once a per-process
+     * limit is hit (Safari's ceiling is notably lower than Chrome's), so a
+     * page rendering several live 3D previews at once needs this to avoid
+     * contexts going blank with no error.
+     */
+    respectBudget?: boolean;
+}
+export interface ThreeSketchHandle {
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    isRunning: () => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/useCanvasSketch.d.ts

@@ -0,0 +1,17 @@
+import type { CanvasSketchOptions } from './types';
+export interface UseCanvasSketchResult {
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    isRunning: () => boolean;
+    /** Re-renders when start()/stop() are called — handy for a play/pause button label. */
+    running: boolean;
+}
+/**
+ * Headless canvas render-loop engine: DPR-aware resize, requestAnimationFrame loop with
+ * dt/time/frame, and pointer/keyboard input normalized to canvas-local CSS-pixel coordinates.
+ * All DOM/window access happens inside effects, so it's safe to use during SSR.
+ */
+export declare function useCanvasSketch(options?: CanvasSketchOptions): UseCanvasSketchResult;
+//# sourceMappingURL=useCanvasSketch.d.ts.map

package/dist/useCanvasSketch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasSketch.d.ts","sourceRoot":"","sources":["../src/useCanvasSketch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,SAAS,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACrD,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,mBAAwB,GAAG,qBAAqB,CAkHxF"}

package/dist/useCanvasSketch.js

@@ -0,0 +1,112 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCanvasSketch = useCanvasSketch;
+const react_1 = require("react");
+/**
+ * Headless canvas render-loop engine: DPR-aware resize, requestAnimationFrame loop with
+ * dt/time/frame, and pointer/keyboard input normalized to canvas-local CSS-pixel coordinates.
+ * All DOM/window access happens inside effects, so it's safe to use during SSR.
+ */
+function useCanvasSketch(options = {}) {
+    const canvasRef = (0, react_1.useRef)(null);
+    const ctxRef = (0, react_1.useRef)(null);
+    const optionsRef = (0, react_1.useRef)(options);
+    optionsRef.current = options;
+    const rafRef = (0, react_1.useRef)(0);
+    const runningRef = (0, react_1.useRef)(false);
+    const lastTsRef = (0, react_1.useRef)(null);
+    const timeRef = (0, react_1.useRef)(0);
+    const frameRef = (0, react_1.useRef)(0);
+    const [running, setRunning] = (0, react_1.useState)(false);
+    const loop = (0, react_1.useCallback)((ts) => {
+        const canvas = canvasRef.current;
+        const ctx = ctxRef.current;
+        if (!canvas || !ctx)
+            return;
+        if (lastTsRef.current === null)
+            lastTsRef.current = ts;
+        const dt = (ts - lastTsRef.current) / 1000;
+        lastTsRef.current = ts;
+        timeRef.current += dt;
+        frameRef.current += 1;
+        const dpr = window.devicePixelRatio || 1;
+        const width = canvas.width / dpr;
+        const height = canvas.height / dpr;
+        optionsRef.current.draw?.({
+            ctx, canvas, width, height,
+            dt, time: timeRef.current, frame: frameRef.current,
+        });
+        rafRef.current = requestAnimationFrame(loop);
+    }, []);
+    const start = (0, react_1.useCallback)(() => {
+        if (runningRef.current)
+            return;
+        runningRef.current = true;
+        setRunning(true);
+        lastTsRef.current = null;
+        rafRef.current = requestAnimationFrame(loop);
+    }, [loop]);
+    const stop = (0, react_1.useCallback)(() => {
+        runningRef.current = false;
+        setRunning(false);
+        cancelAnimationFrame(rafRef.current);
+    }, []);
+    const reset = (0, react_1.useCallback)(() => {
+        stop();
+        timeRef.current = 0;
+        frameRef.current = 0;
+        lastTsRef.current = null;
+    }, [stop]);
+    const isRunning = (0, react_1.useCallback)(() => runningRef.current, []);
+    (0, react_1.useEffect)(() => {
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return;
+        ctxRef.current = ctx;
+        const resize = () => {
+            const rect = canvas.getBoundingClientRect();
+            const dpr = window.devicePixelRatio || 1;
+            const width = Math.max(1, Math.round(rect.width));
+            const height = Math.max(1, Math.round(rect.height));
+            canvas.width = width * dpr;
+            canvas.height = height * dpr;
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+            optionsRef.current.setup?.({ ctx, canvas, width, height });
+        };
+        resize();
+        const ro = new ResizeObserver(resize);
+        ro.observe(canvas);
+        const toLocal = (e) => {
+            const rect = canvas.getBoundingClientRect();
+            return { x: e.clientX - rect.left, y: e.clientY - rect.top, event: e };
+        };
+        const onPointerDown = (e) => optionsRef.current.onPointerDown?.(toLocal(e));
+        const onPointerMove = (e) => optionsRef.current.onPointerMove?.(toLocal(e));
+        const onPointerUp = (e) => optionsRef.current.onPointerUp?.(toLocal(e));
+        canvas.addEventListener('pointerdown', onPointerDown);
+        canvas.addEventListener('pointermove', onPointerMove);
+        canvas.addEventListener('pointerup', onPointerUp);
+        const onKeyDown = (e) => optionsRef.current.onKeyDown?.(e);
+        const onKeyUp = (e) => optionsRef.current.onKeyUp?.(e);
+        window.addEventListener('keydown', onKeyDown);
+        window.addEventListener('keyup', onKeyUp);
+        if (optionsRef.current.autoStart ?? true)
+            start();
+        return () => {
+            ro.disconnect();
+            canvas.removeEventListener('pointerdown', onPointerDown);
+            canvas.removeEventListener('pointermove', onPointerMove);
+            canvas.removeEventListener('pointerup', onPointerUp);
+            window.removeEventListener('keydown', onKeyDown);
+            window.removeEventListener('keyup', onKeyUp);
+            cancelAnimationFrame(rafRef.current);
+            runningRef.current = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return { canvasRef, start, stop, reset, isRunning, running };
+}

package/dist/useInViewport.d.ts

@@ -0,0 +1,19 @@
+export interface UseInViewportOptions {
+    /** Forwarded to IntersectionObserver. Default: '200px'. */
+    rootMargin?: string;
+    /**
+     * Once true, stays true forever after the first intersection (old
+     * "mount once" behavior — cheap sketches that shouldn't restart on
+     * every scroll in/out). Once false, tracks intersection continuously,
+     * which is what lets a WebGL sketch actually unmount and free its
+     * context budget slot when scrolled away. Default: false.
+     */
+    once?: boolean;
+}
+/**
+ * Tracks whether `ref`'s element is inside the viewport (+ rootMargin).
+ * Used to lazily mount expensive sketches (canvas/WebGL) only while
+ * they're actually visible.
+ */
+export declare function useInViewport(ref: React.RefObject<Element | null>, { rootMargin, once }?: UseInViewportOptions): boolean;
+//# sourceMappingURL=useInViewport.d.ts.map

package/dist/useInViewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInViewport.d.ts","sourceRoot":"","sources":["../src/useInViewport.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,EACpC,EAAE,UAAoB,EAAE,IAAY,EAAE,GAAE,oBAAyB,GAChE,OAAO,CAyBT"}

package/dist/useInViewport.js

@@ -0,0 +1,33 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useInViewport = useInViewport;
+const react_1 = require("react");
+/**
+ * Tracks whether `ref`'s element is inside the viewport (+ rootMargin).
+ * Used to lazily mount expensive sketches (canvas/WebGL) only while
+ * they're actually visible.
+ */
+function useInViewport(ref, { rootMargin = '200px', once = false } = {}) {
+    const [inView, setInView] = (0, react_1.useState)(false);
+    (0, react_1.useEffect)(() => {
+        const el = ref.current;
+        if (!el)
+            return undefined;
+        const obs = new IntersectionObserver((entries) => {
+            const isIntersecting = !!entries[0]?.isIntersecting;
+            if (isIntersecting) {
+                setInView(true);
+                if (once)
+                    obs.disconnect();
+            }
+            else if (!once) {
+                setInView(false);
+            }
+        }, { rootMargin });
+        obs.observe(el);
+        return () => obs.disconnect();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [ref.current, rootMargin, once]);
+    return inView;
+}

package/dist/useThreeSketch.d.ts

@@ -0,0 +1,25 @@
+import type { ThreeSketchOptions } from './types';
+export interface UseThreeSketchResult {
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    isRunning: () => boolean;
+    /** Re-renders when start()/stop() are called — handy for a play/pause button label. */
+    running: boolean;
+}
+/**
+ * Headless Three.js render-loop engine: same shape as useCanvasSketch
+ * (DPR-aware resize, requestAnimationFrame loop with dt/time/frame,
+ * normalized pointer/keyboard input), but hands your setup/draw callbacks
+ * a `scene`/`camera`/`renderer` instead of a 2D `ctx`.
+ *
+ * Unlike useCanvasSketch, WebGL contexts are a scarce per-process browser
+ * resource, so this hook (a) waits for a slot in the shared context budget
+ * before creating the renderer (see `configureWebglBudget`), and (b) fully
+ * disposes the scene graph and forces context loss on unmount, so a page
+ * that mounts/unmounts many of these (e.g. a gallery of live previews)
+ * doesn't leak contexts.
+ */
+export declare function useThreeSketch(options?: ThreeSketchOptions): UseThreeSketchResult;
+//# sourceMappingURL=useThreeSketch.d.ts.map

package/dist/useThreeSketch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThreeSketch.d.ts","sourceRoot":"","sources":["../src/useThreeSketch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAe,MAAM,SAAS,CAAC;AAG/D,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACrD,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,oBAAoB,CAgLrF"}

package/dist/useThreeSketch.js

@@ -0,0 +1,209 @@
+"use strict";
+'use client';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useThreeSketch = useThreeSketch;
+const react_1 = require("react");
+const THREE = __importStar(require("three"));
+const webglBudget_1 = require("./webglBudget");
+/**
+ * Headless Three.js render-loop engine: same shape as useCanvasSketch
+ * (DPR-aware resize, requestAnimationFrame loop with dt/time/frame,
+ * normalized pointer/keyboard input), but hands your setup/draw callbacks
+ * a `scene`/`camera`/`renderer` instead of a 2D `ctx`.
+ *
+ * Unlike useCanvasSketch, WebGL contexts are a scarce per-process browser
+ * resource, so this hook (a) waits for a slot in the shared context budget
+ * before creating the renderer (see `configureWebglBudget`), and (b) fully
+ * disposes the scene graph and forces context loss on unmount, so a page
+ * that mounts/unmounts many of these (e.g. a gallery of live previews)
+ * doesn't leak contexts.
+ */
+function useThreeSketch(options = {}) {
+    const canvasRef = (0, react_1.useRef)(null);
+    const optionsRef = (0, react_1.useRef)(options);
+    optionsRef.current = options;
+    const sceneRef = (0, react_1.useRef)(null);
+    const cameraRef = (0, react_1.useRef)(null);
+    const rendererRef = (0, react_1.useRef)(null);
+    const rafRef = (0, react_1.useRef)(0);
+    const runningRef = (0, react_1.useRef)(false);
+    const lastTsRef = (0, react_1.useRef)(null);
+    const timeRef = (0, react_1.useRef)(0);
+    const frameRef = (0, react_1.useRef)(0);
+    const [running, setRunning] = (0, react_1.useState)(false);
+    const [hasSlot, setHasSlot] = (0, react_1.useState)(false);
+    const loop = (0, react_1.useCallback)((ts) => {
+        const canvas = canvasRef.current;
+        const scene = sceneRef.current;
+        const camera = cameraRef.current;
+        const renderer = rendererRef.current;
+        if (!canvas || !scene || !camera || !renderer)
+            return;
+        if (lastTsRef.current === null)
+            lastTsRef.current = ts;
+        const dt = (ts - lastTsRef.current) / 1000;
+        lastTsRef.current = ts;
+        timeRef.current += dt;
+        frameRef.current += 1;
+        const width = canvas.clientWidth || 1;
+        const height = canvas.clientHeight || 1;
+        optionsRef.current.draw?.({
+            scene, camera, renderer, canvas, width, height,
+            dt, time: timeRef.current, frame: frameRef.current,
+        });
+        renderer.render(scene, camera);
+        rafRef.current = requestAnimationFrame(loop);
+    }, []);
+    const start = (0, react_1.useCallback)(() => {
+        if (runningRef.current)
+            return;
+        runningRef.current = true;
+        setRunning(true);
+        lastTsRef.current = null;
+        rafRef.current = requestAnimationFrame(loop);
+    }, [loop]);
+    const stop = (0, react_1.useCallback)(() => {
+        runningRef.current = false;
+        setRunning(false);
+        cancelAnimationFrame(rafRef.current);
+    }, []);
+    const reset = (0, react_1.useCallback)(() => {
+        stop();
+        timeRef.current = 0;
+        frameRef.current = 0;
+        lastTsRef.current = null;
+    }, [stop]);
+    const isRunning = (0, react_1.useCallback)(() => runningRef.current, []);
+    // Reserva um slot no orçamento global de contextos WebGL antes de criar
+    // qualquer coisa. Se não conseguir na hora, fica em espera e tenta de
+    // novo quando um slot se abrir (ver webglBudget.ts).
+    (0, react_1.useEffect)(() => {
+        if (!(optionsRef.current.respectBudget ?? true)) {
+            setHasSlot(true);
+            return undefined;
+        }
+        let granted = false;
+        const onGrant = () => { granted = true; setHasSlot(true); };
+        if ((0, webglBudget_1.acquireWebglSlot)(onGrant)) {
+            granted = true;
+            setHasSlot(true);
+        }
+        return () => {
+            if (granted)
+                (0, webglBudget_1.releaseWebglSlot)();
+            else
+                (0, webglBudget_1.cancelWebglSlotRequest)(onGrant);
+        };
+    }, []);
+    (0, react_1.useEffect)(() => {
+        if (!hasSlot)
+            return undefined;
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return undefined;
+        const renderer = new THREE.WebGLRenderer({
+            canvas,
+            antialias: true,
+            alpha: false,
+            ...optionsRef.current.rendererOptions,
+        });
+        const scene = new THREE.Scene();
+        const camera = new THREE.PerspectiveCamera(optionsRef.current.fov ?? 50, 1, optionsRef.current.near ?? 0.1, optionsRef.current.far ?? 1000);
+        camera.position.z = 5;
+        sceneRef.current = scene;
+        cameraRef.current = camera;
+        rendererRef.current = renderer;
+        const resize = () => {
+            const rect = canvas.getBoundingClientRect();
+            const width = Math.max(1, Math.round(rect.width));
+            const height = Math.max(1, Math.round(rect.height));
+            renderer.setPixelRatio(window.devicePixelRatio || 1);
+            renderer.setSize(width, height, false);
+            camera.aspect = width / height;
+            camera.updateProjectionMatrix();
+            optionsRef.current.setup?.({ scene, camera, renderer, canvas, width, height });
+        };
+        resize();
+        const ro = new ResizeObserver(resize);
+        ro.observe(canvas);
+        const toLocal = (e) => {
+            const rect = canvas.getBoundingClientRect();
+            return { x: e.clientX - rect.left, y: e.clientY - rect.top, event: e };
+        };
+        const onPointerDown = (e) => optionsRef.current.onPointerDown?.(toLocal(e));
+        const onPointerMove = (e) => optionsRef.current.onPointerMove?.(toLocal(e));
+        const onPointerUp = (e) => optionsRef.current.onPointerUp?.(toLocal(e));
+        canvas.addEventListener('pointerdown', onPointerDown);
+        canvas.addEventListener('pointermove', onPointerMove);
+        canvas.addEventListener('pointerup', onPointerUp);
+        const onKeyDown = (e) => optionsRef.current.onKeyDown?.(e);
+        const onKeyUp = (e) => optionsRef.current.onKeyUp?.(e);
+        window.addEventListener('keydown', onKeyDown);
+        window.addEventListener('keyup', onKeyUp);
+        if (optionsRef.current.autoStart ?? true)
+            start();
+        return () => {
+            ro.disconnect();
+            canvas.removeEventListener('pointerdown', onPointerDown);
+            canvas.removeEventListener('pointermove', onPointerMove);
+            canvas.removeEventListener('pointerup', onPointerUp);
+            window.removeEventListener('keydown', onKeyDown);
+            window.removeEventListener('keyup', onKeyUp);
+            cancelAnimationFrame(rafRef.current);
+            runningRef.current = false;
+            // Libera geometria/material/textura e força a perda do contexto —
+            // sem isso o contexto WebGL fica pendurado até o garbage collector
+            // decidir coletar o WebGLRenderer, o que pode nunca acontecer a
+            // tempo em uma galeria que monta/desmonta várias prévias.
+            scene.traverse((obj) => {
+                const mesh = obj;
+                mesh.geometry?.dispose?.();
+                const material = mesh.material;
+                if (Array.isArray(material))
+                    material.forEach((m) => m.dispose());
+                else
+                    material?.dispose?.();
+            });
+            renderer.dispose();
+            renderer.forceContextLoss();
+            sceneRef.current = null;
+            cameraRef.current = null;
+            rendererRef.current = null;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [hasSlot]);
+    return { canvasRef, start, stop, reset, isRunning, running };
+}

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function randRange(min: number, max: number): number;
+export type RGB = [number, number, number];
+/** Linearly interpolates between two RGB colors and returns an `rgb(...)` string. */
+export declare function lerpColor(a: RGB, b: RGB, t: number): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3C,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAM3D"}

package/dist/utils.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clamp = clamp;
+exports.randRange = randRange;
+exports.lerpColor = lerpColor;
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function randRange(min, max) {
+    return min + Math.random() * (max - min);
+}
+/** Linearly interpolates between two RGB colors and returns an `rgb(...)` string. */
+function lerpColor(a, b, t) {
+    const tt = clamp(t, 0, 1);
+    const r = Math.round(a[0] + (b[0] - a[0]) * tt);
+    const g = Math.round(a[1] + (b[1] - a[1]) * tt);
+    const bl = Math.round(a[2] + (b[2] - a[2]) * tt);
+    return `rgb(${r},${g},${bl})`;
+}

package/dist/webglBudget.d.ts

@@ -0,0 +1,25 @@
+type Listener = () => void;
+/**
+ * Ajusta o número máximo de contextos WebGL simultâneos que useThreeSketch
+ * respeita. Browsers descartam o contexto mais antigo silenciosamente ao
+ * estourar o teto do processo (Safari costuma ser bem mais restritivo que
+ * Chrome), então o padrão (4) é conservador para caber várias prévias na
+ * mesma página sem depender do limite exato de cada navegador.
+ */
+export declare function configureWebglBudget(max: number): void;
+export declare function getWebglBudget(): {
+    active: number;
+    max: number;
+};
+/**
+ * Reserva um slot no orçamento global. Retorna true se conseguiu na hora
+ * (o chamador deve chamar releaseWebglSlot() quando terminar). Se não
+ * houver slot livre, registra `onGrant` para ser chamado assim que um se
+ * abrir — o chamador decide o que fazer nesse momento (tipicamente tentar
+ * adquirir de novo).
+ */
+export declare function acquireWebglSlot(onGrant?: Listener): boolean;
+export declare function cancelWebglSlotRequest(onGrant: Listener): void;
+export declare function releaseWebglSlot(): void;
+export {};
+//# sourceMappingURL=webglBudget.d.ts.map

package/dist/webglBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webglBudget.d.ts","sourceRoot":"","sources":["../src/webglBudget.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAkB3B;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wBAAgB,cAAc,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAO5D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAE9D;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}

package/dist/webglBudget.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureWebglBudget = configureWebglBudget;
+exports.getWebglBudget = getWebglBudget;
+exports.acquireWebglSlot = acquireWebglSlot;
+exports.cancelWebglSlotRequest = cancelWebglSlotRequest;
+exports.releaseWebglSlot = releaseWebglSlot;
+let maxConcurrent = 4;
+let active = 0;
+const waiters = new Set();
+function notifyWaiters() {
+    while (active < maxConcurrent && waiters.size > 0) {
+        const listener = waiters.values().next().value;
+        waiters.delete(listener);
+        // Reserve the slot before calling out — the waiter is being granted
+        // exactly the capacity acquireWebglSlot() would have given it
+        // synchronously, so it must count against the budget the same way.
+        active += 1;
+        listener();
+    }
+}
+/**
+ * Ajusta o número máximo de contextos WebGL simultâneos que useThreeSketch
+ * respeita. Browsers descartam o contexto mais antigo silenciosamente ao
+ * estourar o teto do processo (Safari costuma ser bem mais restritivo que
+ * Chrome), então o padrão (4) é conservador para caber várias prévias na
+ * mesma página sem depender do limite exato de cada navegador.
+ */
+function configureWebglBudget(max) {
+    maxConcurrent = Math.max(1, max);
+    notifyWaiters();
+}
+function getWebglBudget() {
+    return { active, max: maxConcurrent };
+}
+/**
+ * Reserva um slot no orçamento global. Retorna true se conseguiu na hora
+ * (o chamador deve chamar releaseWebglSlot() quando terminar). Se não
+ * houver slot livre, registra `onGrant` para ser chamado assim que um se
+ * abrir — o chamador decide o que fazer nesse momento (tipicamente tentar
+ * adquirir de novo).
+ */
+function acquireWebglSlot(onGrant) {
+    if (active < maxConcurrent) {
+        active += 1;
+        return true;
+    }
+    if (onGrant)
+        waiters.add(onGrant);
+    return false;
+}
+function cancelWebglSlotRequest(onGrant) {
+    waiters.delete(onGrant);
+}
+function releaseWebglSlot() {
+    active = Math.max(0, active - 1);
+    notifyWaiters();
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "next-sketch",
+  "version": "0.2.0",
+  "description": "p5.js-style canvas sketches for React/Next.js — headless hooks plus drop-in <CanvasSketch>/<ThreeSketch> components, SSR-safe and DPR-aware, with an optional Three.js engine and a shared WebGL context budget.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "react",
+    "nextjs",
+    "canvas",
+    "sketch",
+    "p5js",
+    "animation",
+    "simulation",
+    "creative-coding",
+    "three",
+    "threejs",
+    "webgl",
+    "3d"
+  ],
+  "author": "ReinanBr",
+  "license": "MIT",
+  "homepage": "https://github.com/reinanbr/next-sketch#readme",
+  "bugs": {
+    "url": "https://github.com/reinanbr/next-sketch/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "three": ">=0.150.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/three": "^0.185.1",
+    "jest": "^30.0.0",
+    "jest-environment-jsdom": "^30.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "three": "^0.185.1",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.8.2"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reinanbr/next-sketch"
+  }
+}