svelte-p5 0.3.0 → 0.4.0

package/README.md

@@ -8,6 +8,14 @@ Svelte 5 bindings for p5.js. This package is the primitive layer: a canvas wrapp
 pnpm add svelte-p5 p5
 ```
 
+To test a change that's merged on `main` but not yet released — or any specific commit — install the preview build from [pkg.pr.new](https://pkg.pr.new/):
+
+```bash
+pnpm add https://pkg.pr.new/edw1nzhao/svelte-p5/svelte-p5@main
+# or pin an exact SHA:
+pnpm add https://pkg.pr.new/edw1nzhao/svelte-p5/svelte-p5@<commit-sha>
+```
+
 ## `<P5Canvas>`
 
 Mounts a p5 sketch in instance mode, cleans it up on unmount.
@@ -91,11 +99,42 @@ What each does and when to reach for it lives in the [performance recipe](../../
 ## Type exports
 
 ```ts
-import type { SketchFn, P5CanvasProps, P5Bridge } from 'svelte-p5';
+import type { SketchFn, ExtendedP5, 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.
 
+### Typed instance extensions
+
+Sketches that install custom members on the instance (`p.myHelper = ...`) can type
+them instead of casting. `SketchFn<Ext>` types the instance inside the sketch as
+`p5 & Ext`, and `ExtendedP5<Ext>` names that same intersection for stores and
+variables that hold the bound instance:
+
+```ts
+interface AppSketchExt {
+	resetView(): void;
+	zoomLevel: number;
+}
+type AppP5 = ExtendedP5<AppSketchExt>;
+
+const sketch: SketchFn<AppSketchExt> = (p) => {
+	p.resetView = () => {
+		/* ... */
+	};
+	p.draw = () => {
+		/* p.zoomLevel is typed */
+	};
+};
+
+let instance: AppP5 | null = $state(null);
+```
+
+```svelte
+<P5Canvas {sketch} bind:instance />
+<!-- instance is inferred as AppP5 | null; instance?.resetView() type-checks -->
+```
+
 ## License
 
 MIT

package/dist/P5Canvas.svelte

@@ -1,7 +1,7 @@
-<script lang="ts">
+<script lang="ts" generics="Ext = unknown">
 	import { onMount } from 'svelte';
 	import type p5Type from 'p5';
-	import type { P5CanvasProps } from './types.js';
+	import type { ExtendedP5, P5CanvasProps } from './types.js';
 
 	let {
 		sketch,
@@ -9,7 +9,7 @@
 		class: className = '',
 		style = 'display: block; width: 100%; height: 100%;',
 		onReady
-	}: P5CanvasProps = $props();
+	}: P5CanvasProps<Ext> = $props();
 
 	let container: HTMLDivElement | null = null;
 
@@ -24,9 +24,12 @@
 			if (cancelled || !container) return;
 
 			const p5Ctor = mod.default;
-			local = new p5Ctor((p: p5Type) => sketch(p), container);
-			instance = local;
-			onReady?.(local);
+			// The sketch installs its Ext members during construction (p5 calls the
+			// sketch function synchronously inside the constructor), so by the time
+			// the instance is observable it is already the extended type.
+			local = new p5Ctor((p: p5Type) => sketch(p as ExtendedP5<Ext>), container);
+			instance = local as ExtendedP5<Ext>;
+			onReady?.(local as ExtendedP5<Ext>);
 		})();
 
 		return () => {

package/dist/P5Canvas.svelte.d.ts

@@ -1,4 +1,25 @@
 import type { P5CanvasProps } from './types.js';
-declare const P5Canvas: import("svelte").Component<P5CanvasProps, {}, "instance">;
-type P5Canvas = ReturnType<typeof P5Canvas>;
+declare function $$render<Ext = unknown>(): {
+    props: P5CanvasProps<Ext>;
+    exports: {};
+    bindings: "instance";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Ext = unknown> {
+    props(): ReturnType<typeof $$render<Ext>>['props'];
+    events(): ReturnType<typeof $$render<Ext>>['events'];
+    slots(): ReturnType<typeof $$render<Ext>>['slots'];
+    bindings(): "instance";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Ext = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Ext>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Ext>['props']>, ReturnType<__sveltets_Render<Ext>['events']>, ReturnType<__sveltets_Render<Ext>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Ext>['bindings']>;
+    } & ReturnType<__sveltets_Render<Ext>['exports']>;
+    <Ext = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<Ext>['props']> & {}): ReturnType<__sveltets_Render<Ext>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const P5Canvas: $$IsomorphicComponent;
+type P5Canvas<Ext = unknown> = InstanceType<typeof P5Canvas<Ext>>;
 export default P5Canvas;

package/dist/index.d.ts

@@ -1,4 +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 type { SketchFn, ExtendedP5, P5CanvasProps } from './types.js';
 export * from './utils/index.js';

package/dist/types.d.ts

@@ -2,20 +2,41 @@ 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.
+ *
+ * `Ext` types the members your sketch installs onto the instance
+ * (`p.myHelper = ...`). Inside the sketch the instance is typed as
+ * already-extended, because the sketch itself is what installs those
+ * members before anyone else can observe them:
+ *
+ * ```ts
+ * interface MyExt {
+ * 	resetView(): void;
+ * }
+ * const sketch: SketchFn<MyExt> = (p) => {
+ * 	p.resetView = () => { ... };
+ * 	p.draw = () => { ... };
+ * };
+ * ```
  */
-export type SketchFn = (p: p5) => void;
+export type SketchFn<Ext = unknown> = (p: p5 & Ext) => void;
+/**
+ * A p5 instance decorated with app-specific members (see {@link SketchFn}).
+ * Useful for typing stores or variables that hold the bound instance:
+ * `let instance: ExtendedP5<MyExt> | null`.
+ */
+export type ExtendedP5<Ext> = p5 & Ext;
 /**
  * Props accepted by the `<P5Canvas>` component.
  */
-export interface P5CanvasProps {
+export interface P5CanvasProps<Ext = unknown> {
     /** Your sketch function - assigns p.setup, p.draw, etc. */
-    sketch: SketchFn;
+    sketch: SketchFn<Ext>;
     /** Bindable: the p5 instance, available after mount. `null` before mount or after unmount. */
-    instance?: p5 | null;
+    instance?: ExtendedP5<Ext> | 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;
+    onReady?: (instance: ExtendedP5<Ext>) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-p5",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Svelte 5 + p5.js integration primitives — <P5Canvas> wrapper, rune bridge, and performance utilities",
   "keywords": [
     "svelte",