svelte-p5 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edwin Zhao
+
+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,101 @@
+# svelte-p5
+
+Svelte 5 bindings for p5.js. This package is the primitive layer: a canvas wrapper, a state bridge, and four small performance helpers. If you want the opinionated higher-level pieces (auto-resize, FPS readout, draggable windows), install [`svelte-p5-components`](../components) as well.
+
+## Install
+
+```bash
+pnpm add svelte-p5 p5
+```
+
+## `<P5Canvas>`
+
+Mounts a p5 sketch in instance mode, cleans it up on unmount.
+
+```svelte
+<script lang="ts">
+	import { P5Canvas } from 'svelte-p5';
+	import type p5 from 'p5';
+
+	const sketch = (p: p5) => {
+		p.setup = () => p.createCanvas(400, 400);
+		p.draw = () => {
+			p.background(240);
+			p.circle(p.mouseX, p.mouseY, 40);
+		};
+	};
+</script>
+
+<P5Canvas {sketch} />
+```
+
+The p5 instance is exposed as a bindable prop. Bind it when you need to call into the sketch from Svelte:
+
+```svelte
+<script lang="ts">
+	import { P5Canvas } from 'svelte-p5';
+	import type p5 from 'p5';
+
+	let instance = $state<p5 | null>(null);
+</script>
+
+<P5Canvas {sketch} bind:instance />
+<button onclick={() => instance?.redraw()}>Redraw</button>
+```
+
+`instance` is `null` before mount and after unmount, so guard with `?.`.
+
+## `createP5Bridge`
+
+A reactive object you can read and write from both sides. No subscriptions, no manual sync.
+
+```svelte
+<script lang="ts">
+	import { P5Canvas, createP5Bridge } from 'svelte-p5';
+	import type p5 from 'p5';
+
+	const bridge = createP5Bridge({ radius: 40, color: '#336699' });
+
+	const sketch = (p: p5) => {
+		p.setup = () => p.createCanvas(400, 400);
+		p.draw = () => {
+			p.background(240);
+			p.fill(bridge.state.color);
+			p.circle(p.mouseX, p.mouseY, bridge.state.radius);
+		};
+	};
+</script>
+
+<P5Canvas {sketch} />
+<input type="range" min="10" max="200" bind:value={bridge.state.radius} />
+<input type="color" bind:value={bridge.state.color} />
+```
+
+`bridge.state` is a `$state` proxy. Mutations on either side take effect on the next frame.
+
+For one or two fields you could just as well close over a plain `$state` variable. Reach for `createP5Bridge` when the state becomes a small struct you want to pass around as a single object.
+
+## Performance utilities
+
+Exported from the main entry (and from `./utils` for explicit imports):
+
+```ts
+import { disableFES, createColorCache, createFontAtlas, hitTest } from 'svelte-p5';
+
+disableFES(); // call once, before creating any p5 instance
+hitTest.rect(mouseX, mouseY, x, y, w, h);
+```
+
+What each does and when to reach for it lives in the [performance recipe](../../docs/recipes/performance.md).
+
+## Type exports
+
+```ts
+import type { SketchFn, P5CanvasProps, P5Bridge } from 'svelte-p5';
+```
+
+`SketchFn` is `(p: p5) => void`. `SketchFn`, not `Sketch`, because the components package exports a `<Sketch>` component and the collision would force aliased imports.
+
+## License
+
+MIT

package/dist/P5Canvas.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import type p5Type from 'p5';
+	import type { P5CanvasProps } from './types.js';
+
+	let {
+		sketch,
+		instance = $bindable(null),
+		class: className = '',
+		style = 'display: block; width: 100%; height: 100%;',
+		onReady
+	}: P5CanvasProps = $props();
+
+	let container: HTMLDivElement | null = null;
+
+	onMount(() => {
+		// Track the local instance so cleanup works even if `instance` is reassigned
+		// by the parent binding before the async import resolves.
+		let local: p5Type | null = null;
+		let cancelled = false;
+
+		(async () => {
+			const mod = await import('p5');
+			if (cancelled || !container) return;
+
+			const p5Ctor = mod.default;
+			local = new p5Ctor((p: p5Type) => sketch(p), container);
+			instance = local;
+			onReady?.(local);
+		})();
+
+		return () => {
+			cancelled = true;
+			try {
+				local?.remove();
+			} catch {
+				// p5.remove() can throw if the DOM is already gone during HMR; ignore.
+			}
+			local = null;
+			instance = null;
+		};
+	});
+</script>
+
+<div bind:this={container} class={className} {style}></div>

package/dist/P5Canvas.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { P5CanvasProps } from './types.js';
+declare const P5Canvas: import("svelte").Component<P5CanvasProps, {}, "instance">;
+type P5Canvas = ReturnType<typeof P5Canvas>;
+export default P5Canvas;

package/dist/createP5Bridge.svelte.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Bridge reactive Svelte state into a p5 sketch closure.
+ *
+ * Mutations from either side are seen by the other. Because p5's draw loop
+ * reads fields on every frame, you don't need effects or subscriptions —
+ * just read `bridge.state.foo` inside your sketch and write to it from
+ * Svelte UI.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { P5Canvas, createP5Bridge } from 'svelte-p5';
+ *   import type p5 from 'p5';
+ *
+ *   const bridge = createP5Bridge({ radius: 40, color: '#336699' });
+ *
+ *   const sketch = (p: p5) => {
+ *     p.setup = () => p.createCanvas(400, 400);
+ *     p.draw = () => {
+ *       p.background(240);
+ *       p.fill(bridge.state.color);
+ *       p.circle(p.mouseX, p.mouseY, bridge.state.radius);
+ *     };
+ *   };
+ * </script>
+ *
+ * <P5Canvas {sketch} />
+ * <input type="range" bind:value={bridge.state.radius} min="10" max="200" />
+ * ```
+ */
+export declare function createP5Bridge<T extends object>(initial: T): {
+    state: T;
+};
+export type P5Bridge<T extends object> = ReturnType<typeof createP5Bridge<T>>;

package/dist/createP5Bridge.svelte.js

@@ -0,0 +1,34 @@
+/**
+ * Bridge reactive Svelte state into a p5 sketch closure.
+ *
+ * Mutations from either side are seen by the other. Because p5's draw loop
+ * reads fields on every frame, you don't need effects or subscriptions —
+ * just read `bridge.state.foo` inside your sketch and write to it from
+ * Svelte UI.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { P5Canvas, createP5Bridge } from 'svelte-p5';
+ *   import type p5 from 'p5';
+ *
+ *   const bridge = createP5Bridge({ radius: 40, color: '#336699' });
+ *
+ *   const sketch = (p: p5) => {
+ *     p.setup = () => p.createCanvas(400, 400);
+ *     p.draw = () => {
+ *       p.background(240);
+ *       p.fill(bridge.state.color);
+ *       p.circle(p.mouseX, p.mouseY, bridge.state.radius);
+ *     };
+ *   };
+ * </script>
+ *
+ * <P5Canvas {sketch} />
+ * <input type="range" bind:value={bridge.state.radius} min="10" max="200" />
+ * ```
+ */
+export function createP5Bridge(initial) {
+    const state = $state(initial);
+    return { state };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { default as P5Canvas } from './P5Canvas.svelte';
+export { createP5Bridge, type P5Bridge } from './createP5Bridge.svelte.js';
+export type { SketchFn, P5CanvasProps } from './types.js';
+export * from './utils/index.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { default as P5Canvas } from './P5Canvas.svelte';
+export { createP5Bridge } from './createP5Bridge.svelte.js';
+// Re-export utils from the main entry for convenience — users doing
+// `import { disableFES } from 'svelte-p5'` get the same
+// helpers they'd get from `.../utils`. Tree-shakeable via `sideEffects: false`.
+export * from './utils/index.js';

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+import type p5 from 'p5';
+/**
+ * A p5 sketch function in instance mode. Called with the p5 instance;
+ * the function should assign `p.setup`, `p.draw`, etc. on it.
+ */
+export type SketchFn = (p: p5) => void;
+/**
+ * Props accepted by the `<P5Canvas>` component.
+ */
+export interface P5CanvasProps {
+    /** Your sketch function — assigns p.setup, p.draw, etc. */
+    sketch: SketchFn;
+    /** Bindable: the p5 instance, available after mount. `null` before mount or after unmount. */
+    instance?: p5 | null;
+    /** Optional class applied to the container div. */
+    class?: string;
+    /** Optional inline style on the container div. Defaults to `display: block; width: 100%; height: 100%;`. */
+    style?: string;
+    /** Called once, synchronously, when the p5 instance has been created and the sketch function has returned. */
+    onReady?: (instance: p5) => void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/colorCache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Lazy cache for CSS color strings.
+ *
+ * p5.color() allocates a p5.Color instance on every call (object + typed
+ * arrays + regex parse). Calling it in a draw loop — e.g. to colorize per
+ * speaker or per data-point — leaks a lot of garbage. Use a ColorCache to
+ * compute each color once and reuse the CSS string.
+ *
+ * @example
+ * ```ts
+ * const colors = createColorCache<string>();
+ * const forSpeaker = (id: string, hue: number) =>
+ *   colors.get(id, () => `hsl(${hue}, 80%, 60%)`);
+ *
+ * // in sketch:
+ * p.fill(forSpeaker(point.speaker, point.hue));
+ * ```
+ */
+export interface ColorCache<K = string> {
+    get(key: K, compute: () => string): string;
+    set(key: K, value: string): void;
+    has(key: K): boolean;
+    clear(): void;
+    readonly size: number;
+}
+export declare function createColorCache<K = string>(): ColorCache<K>;

package/dist/utils/colorCache.js

@@ -0,0 +1,25 @@
+export function createColorCache() {
+    const cache = new Map();
+    return {
+        get(key, compute) {
+            let v = cache.get(key);
+            if (v === undefined) {
+                v = compute();
+                cache.set(key, v);
+            }
+            return v;
+        },
+        set(key, value) {
+            cache.set(key, value);
+        },
+        has(key) {
+            return cache.has(key);
+        },
+        clear() {
+            cache.clear();
+        },
+        get size() {
+            return cache.size;
+        }
+    };
+}

package/dist/utils/disableFES.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Disable p5's Friendly Error System (FES) for production.
+ *
+ * FES validates arguments on every p5 API call (map, fill, stroke, text, etc.)
+ * via deep parameter checking + Levenshtein-distance typo detection. For
+ * sketches that make thousands of calls per frame, this adds 1-5% CPU overhead.
+ *
+ * Call this once, before instantiating any p5 sketch. The flag is read by
+ * p5's FES bootstrap as a bare global (`typeof IS_MINIFIED`), which in a
+ * browser means any property on `globalThis`/`window`.
+ *
+ * @see https://github.com/processing/p5.js/blob/main/src/core/friendly_errors/fes_core.js
+ */
+export declare function disableFES(): void;

package/dist/utils/disableFES.js

@@ -0,0 +1,16 @@
+/**
+ * Disable p5's Friendly Error System (FES) for production.
+ *
+ * FES validates arguments on every p5 API call (map, fill, stroke, text, etc.)
+ * via deep parameter checking + Levenshtein-distance typo detection. For
+ * sketches that make thousands of calls per frame, this adds 1-5% CPU overhead.
+ *
+ * Call this once, before instantiating any p5 sketch. The flag is read by
+ * p5's FES bootstrap as a bare global (`typeof IS_MINIFIED`), which in a
+ * browser means any property on `globalThis`/`window`.
+ *
+ * @see https://github.com/processing/p5.js/blob/main/src/core/friendly_errors/fes_core.js
+ */
+export function disableFES() {
+    globalThis.IS_MINIFIED = true;
+}

package/dist/utils/fontAtlas.d.ts

@@ -0,0 +1,30 @@
+import type p5 from 'p5';
+export interface FontAtlasOptions {
+    /** Font size in px. Default: 14 */
+    fontSize?: number;
+    /** Fill color (any CSS color string). Default: black */
+    fill?: string;
+    /** Padding around each glyph cell. Default: 4 */
+    padding?: number;
+}
+export interface FontAtlas {
+    /** The offscreen p5.Graphics buffer the strings are rendered into. */
+    readonly buffer: p5.Graphics;
+    /** Composite the pre-rendered string at (x, y). Returns false if the string wasn't in the atlas. */
+    draw(str: string, x: number, y: number): boolean;
+    /** Release the underlying buffer. Call in cleanup. */
+    dispose(): void;
+}
+/**
+ * Pre-render a fixed set of strings to an offscreen buffer **once**, then
+ * composite them each frame with `p5.image()`. This bypasses the OpenType.js
+ * path-rendering slow path that fires for every `p5.text()` call when you've
+ * `loadFont()`'d an OTF/TTF file — typically a 10-100× speedup for text-heavy
+ * sketches (word clouds, axis labels, small-multiples titles).
+ *
+ * Use for a fixed vocabulary (speaker names, category labels, axis ticks).
+ * Don't use for per-frame dynamic text — that defeats the point.
+ *
+ * @see https://github.com/processing/p5.js/blob/main/src/core/p5.Renderer2D.js
+ */
+export declare function createFontAtlas(sk: p5, strings: readonly string[], options?: FontAtlasOptions): FontAtlas;

package/dist/utils/fontAtlas.js

@@ -0,0 +1,53 @@
+/**
+ * Pre-render a fixed set of strings to an offscreen buffer **once**, then
+ * composite them each frame with `p5.image()`. This bypasses the OpenType.js
+ * path-rendering slow path that fires for every `p5.text()` call when you've
+ * `loadFont()`'d an OTF/TTF file — typically a 10-100× speedup for text-heavy
+ * sketches (word clouds, axis labels, small-multiples titles).
+ *
+ * Use for a fixed vocabulary (speaker names, category labels, axis ticks).
+ * Don't use for per-frame dynamic text — that defeats the point.
+ *
+ * @see https://github.com/processing/p5.js/blob/main/src/core/p5.Renderer2D.js
+ */
+export function createFontAtlas(sk, strings, options = {}) {
+    const { fontSize = 14, fill = '#000', padding = 4 } = options;
+    sk.textSize(fontSize);
+    const cellHeight = fontSize + padding * 2;
+    const widths = [];
+    let maxWidth = 0;
+    for (const s of strings) {
+        const w = sk.textWidth(s);
+        widths.push(w);
+        if (w > maxWidth)
+            maxWidth = w;
+    }
+    const atlasWidth = Math.max(1, Math.ceil(maxWidth + padding * 2));
+    const atlasHeight = Math.max(1, cellHeight * strings.length);
+    const buffer = sk.createGraphics(atlasWidth, atlasHeight);
+    buffer.clear();
+    buffer.textSize(fontSize);
+    buffer.fill(fill);
+    buffer.noStroke();
+    buffer.textAlign(sk.LEFT, sk.TOP);
+    const positions = new Map();
+    strings.forEach((s, i) => {
+        const y = i * cellHeight;
+        const w = (widths[i] ?? 0) + padding * 2;
+        buffer.text(s, padding, y + padding);
+        positions.set(s, { y, w, h: cellHeight });
+    });
+    return {
+        buffer,
+        draw(str, x, y) {
+            const cell = positions.get(str);
+            if (!cell)
+                return false;
+            sk.image(buffer, x, y, cell.w, cell.h, 0, cell.y, cell.w, cell.h);
+            return true;
+        },
+        dispose() {
+            buffer.remove();
+        }
+    };
+}

package/dist/utils/hitTest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Minimal hit-test helpers. These are tree-shakeable drop-ins for p5's
+ * built-in equivalents, with stricter types and no validation overhead.
+ */
+/** Is (px, py) inside the axis-aligned rectangle at (x, y, w, h)? */
+export declare const rect: (px: number, py: number, x: number, y: number, w: number, h: number) => boolean;
+/** Is (px, py) inside the circle centered at (cx, cy) with diameter d? */
+export declare const circle: (px: number, py: number, cx: number, cy: number, d: number) => boolean;
+/** Is (px, py) inside the axis-aligned ellipse at (cx, cy) with width w and height h? */
+export declare const ellipse: (px: number, py: number, cx: number, cy: number, w: number, h: number) => boolean;

package/dist/utils/hitTest.js

@@ -0,0 +1,14 @@
+/**
+ * Minimal hit-test helpers. These are tree-shakeable drop-ins for p5's
+ * built-in equivalents, with stricter types and no validation overhead.
+ */
+/** Is (px, py) inside the axis-aligned rectangle at (x, y, w, h)? */
+export const rect = (px, py, x, y, w, h) => px >= x && px <= x + w && py >= y && py <= y + h;
+/** Is (px, py) inside the circle centered at (cx, cy) with diameter d? */
+export const circle = (px, py, cx, cy, d) => Math.hypot(px - cx, py - cy) < d / 2;
+/** Is (px, py) inside the axis-aligned ellipse at (cx, cy) with width w and height h? */
+export const ellipse = (px, py, cx, cy, w, h) => {
+    const dx = (px - cx) / (w / 2);
+    const dy = (py - cy) / (h / 2);
+    return dx * dx + dy * dy < 1;
+};

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { disableFES } from './disableFES.js';
+export { createColorCache, type ColorCache } from './colorCache.js';
+export { createFontAtlas, type FontAtlas, type FontAtlasOptions } from './fontAtlas.js';
+export * as hitTest from './hitTest.js';

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export { disableFES } from './disableFES.js';
+export { createColorCache } from './colorCache.js';
+export { createFontAtlas } from './fontAtlas.js';
+export * as hitTest from './hitTest.js';

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "svelte-p5",
+  "version": "0.2.0",
+  "description": "Svelte 5 + p5.js integration primitives — <P5Canvas> wrapper, rune bridge, and performance utilities",
+  "keywords": [
+    "svelte",
+    "svelte5",
+    "p5",
+    "p5.js",
+    "creative-coding",
+    "canvas",
+    "visualization",
+    "generative-art"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edwinzhao/svelte-p5.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/edwinzhao/svelte-p5/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/edwinzhao/svelte-p5/issues"
+  },
+  "author": "Edwin Zhao",
+  "license": "MIT",
+  "type": "module",
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "default": "./dist/utils/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "svelte-package -o dist && publint",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "p5": ">=1.11.0 <3",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "catalog:",
+    "@sveltejs/vite-plugin-svelte": "catalog:",
+    "@types/p5": "catalog:",
+    "p5": "catalog:",
+    "publint": "catalog:",
+    "svelte": "catalog:",
+    "svelte-check": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}