@p5-wrapper/common 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 P5 wrapper
+
+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,49 @@
+# @p5-wrapper/common
+
+Common types and utilities for use across p5 wrapper libraries.
+
+This package is the **source of truth** for the shared contracts and p5 instance
+lifecycle utilities used by every wrapper library in the
+[P5-wrapper](https://github.com/P5-wrapper) organisation.
+
+The library is deliberately **framework agnostic**: it imports no framework, and
+the only renderer-bound concept is the `OutputNode` type parameter on the props
+contract. Each ecosystem binds `OutputNode` to its own render output
+(`ReactNode` for React, `VNode` for Vue, embedded view nodes for Angular, and so
+on), which keeps the input props identical across all implementations.
+
+## Installation
+
+```bash
+pnpm add @p5-wrapper/common p5
+```
+
+`p5` is a peer dependency so that the consumer owns the `p5` version.
+
+## Build contract
+
+Published artefacts live in `dist/`:
+
+- `types` → `main.d.ts` (bundled via `vite-plugin-dts`)
+- `import` → `main.mjs` (ESM)
+- `require` → `main.cjs` (CJS)
+
+The `.mjs`/`.cjs` extensions are pinned (never derived from a Vite `[format]`
+placeholder) so the module format self-describes under `"type": "module"`. If
+you change the filenames, change the `exports` map in the `package.json` and the
+Vite config in the same commit.
+
+## Development
+
+| Command              | Action                                          |
+| :------------------- | :---------------------------------------------- |
+| `pnpm install`       | Install dependencies (updates the lock file).   |
+| `pnpm format`        | Format all files with Prettier.                 |
+| `pnpm format:check`  | Check formatting without writing.               |
+| `pnpm lint`          | Run ESLint (type-aware).                        |
+| `pnpm lint:fix`      | Run ESLint with autofix.                        |
+| `pnpm test`          | Run the Vitest suite.                           |
+| `pnpm test:coverage` | Run tests with coverage (what CI runs).         |
+| `pnpm test:watch`    | Watch mode.                                     |
+| `pnpm build`         | Clean, type check, and build the npm library.   |
+| `pnpm integrate`     | format:check → lint → test → build (CI mirror). |

package/dist/main.cjs

@@ -0,0 +1,7 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,s)=>(s=n==null?{}:e(i(n)),o(r||!n||!n.__esModule||!a.call(n,`default`)?t(s,`default`,{value:n,enumerable:!0}):s,n));let c=require("p5");c=s(c,1);let l=require("microdiff");l=s(l,1);var u=`canvas-container`;function d(e,t){return new c.default(e,t)}var f=`[P5Canvas] The error boundary was triggered. The error message was:`;function p(e){return e.trim().split(`
+`).map(e=>e.trim()).join(`
+`)}function m(e){return p(`
+      ${f}
+      
+      ${e}
+    `)}function h(e){return e instanceof Error?`${e.name}("${e.message}")`:typeof e==`symbol`?e.toString():typeof e==`string`?`String("${e}")`:typeof e==`number`?`Number(${e})`:typeof e==`bigint`?`BigInt(${e})`:e instanceof Array?`Array(${JSON.stringify([...e])})`:e instanceof Set?`Set(${JSON.stringify([...e])})`:Object.getPrototypeOf(e)===Object.prototype?`Object(${JSON.stringify(e)})`:`Unknown(${typeof e})`}function g(e){let t=m(h(e));console.error(t)}function _(e,t){return(0,l.default)(e,t).length===0}function v(e){e.current?.remove(),e.current=null}function y(e,t,n){return t.current===null?null:(v(e),d(n,t.current))}exports.CanvasContainerClassName=u,exports.createP5CanvasInstance=d,exports.logErrorBoundaryError=g,exports.p5=c.default,exports.propsAreEqual=_,exports.removeP5CanvasInstance=v,exports.updateP5CanvasInstance=y;

package/dist/main.d.ts

@@ -0,0 +1,48 @@
+import { default as p5_2 } from 'p5';
+
+export declare type CanvasContainer = HTMLDivElement;
+
+export declare const CanvasContainerClassName = "canvas-container";
+
+export declare interface CanvasContainerRef {
+    current: CanvasContainer | null;
+}
+
+export declare function createP5CanvasInstance<Props extends SketchProps>(sketch: Sketch<Props>, canvasContainer: CanvasContainer): P5CanvasInstance<Props>;
+
+export declare function logErrorBoundaryError(error: unknown): void;
+
+export { p5_2 as p5 }
+
+export declare type P5CanvasInstance<Props extends SketchProps = SketchProps> = p5_2 & {
+    updateWithProps?: (props: Props) => void;
+    [key: string]: unknown;
+};
+
+/** Ref to the active p5.js sketch instance controlling the canvas */
+export declare interface P5CanvasInstanceRef<Props extends SketchProps> {
+    current: P5CanvasInstance<Props> | null;
+}
+
+export declare type P5CanvasProps<Props extends SketchProps = SketchProps, OutputNode = unknown> = {
+    sketch?: Sketch<Props>;
+    updater?: Updater<Props>;
+    fallback?: () => OutputNode;
+    loading?: () => OutputNode;
+    error?: (error: unknown) => OutputNode;
+    children?: OutputNode;
+} & Props;
+
+export declare function propsAreEqual<Props extends SketchProps>(previous: Props, next: Props): boolean;
+
+export declare function removeP5CanvasInstance<Props extends SketchProps>(p5CanvasInstanceRef: P5CanvasInstanceRef<Props>): void;
+
+export declare type Sketch<Props extends SketchProps = SketchProps> = (instance: P5CanvasInstance<Props>) => void;
+
+export declare type SketchProps = Record<string, unknown>;
+
+export declare function updateP5CanvasInstance<Props extends SketchProps>(p5CanvasInstanceRef: P5CanvasInstanceRef<Props>, canvasContainerRef: CanvasContainerRef, sketch: Sketch<Props>): P5CanvasInstance<Props> | null;
+
+export declare type Updater<Props extends SketchProps = SketchProps> = (instance: P5CanvasInstance<Props>, props: Props) => void;
+
+export { }

package/dist/main.mjs

@@ -0,0 +1,46 @@
+import e from "p5";
+import t from "microdiff";
+//#region src/constants/CanvasContainerClassName.ts
+var n = "canvas-container";
+//#endregion
+//#region src/utils/createP5CanvasInstance.ts
+function r(t, n) {
+	return new e(t, n);
+}
+//#endregion
+//#region src/utils/logErrorBoundaryError.ts
+var i = "[P5Canvas] The error boundary was triggered. The error message was:";
+function a(e) {
+	return e.trim().split("\n").map((e) => e.trim()).join("\n");
+}
+function o(e) {
+	return a(`
+      ${i}
+      
+      ${e}
+    `);
+}
+function s(e) {
+	return e instanceof Error ? `${e.name}("${e.message}")` : typeof e == "symbol" ? e.toString() : typeof e == "string" ? `String("${e}")` : typeof e == "number" ? `Number(${e})` : typeof e == "bigint" ? `BigInt(${e})` : e instanceof Array ? `Array(${JSON.stringify([...e])})` : e instanceof Set ? `Set(${JSON.stringify([...e])})` : Object.getPrototypeOf(e) === Object.prototype ? `Object(${JSON.stringify(e)})` : `Unknown(${typeof e})`;
+}
+function c(e) {
+	let t = o(s(e));
+	console.error(t);
+}
+//#endregion
+//#region src/utils/propsAreEqual.ts
+function l(e, n) {
+	return t(e, n).length === 0;
+}
+//#endregion
+//#region src/utils/removeP5CanvasInstance.ts
+function u(e) {
+	e.current?.remove(), e.current = null;
+}
+//#endregion
+//#region src/utils/updateP5CanvasInstance.ts
+function d(e, t, n) {
+	return t.current === null ? null : (u(e), r(n, t.current));
+}
+//#endregion
+export { n as CanvasContainerClassName, r as createP5CanvasInstance, c as logErrorBoundaryError, e as p5, l as propsAreEqual, u as removeP5CanvasInstance, d as updateP5CanvasInstance };

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@p5-wrapper/common",
+  "description": "Common types and utilities for use across p5 wrapper libraries.",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "pnpm@12.3.4",
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "homepage": "https://github.com/P5-wrapper/common",
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "dist/*"
+  ],
+  "types": "./dist/main.d.ts",
+  "main": "./dist/main.cjs",
+  "module": "./dist/main.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.mjs",
+      "require": "./dist/main.cjs"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && pnpm build:library",
+    "build:library": "tsc --noEmit && vite build --config config/vite/vite.config.ts --mode lib",
+    "format": "pnpm prettier --write .",
+    "format:check": "pnpm prettier --check .",
+    "integrate": "pnpm format:check && pnpm lint && pnpm test && pnpm build",
+    "lint": "eslint --config config/eslint/eslint.config.ts",
+    "lint:fix": "pnpm lint --fix",
+    "prettier": "prettier --config config/prettier/prettier.json --ignore-path .gitignore --ignore-path config/prettier/.prettierignore",
+    "test": "vitest run --silent --config config/vite/vite.config.ts",
+    "test:coverage": "vitest run --silent --coverage --config config/vite/vite.config.ts",
+    "test:watch": "vitest watch --config config/vite/vite.config.ts"
+  },
+  "keywords": [
+    "p5",
+    "processing",
+    "typescript",
+    "shared",
+    "contracts"
+  ],
+  "author": {
+    "name": "James Robb",
+    "url": "https://github.com/jamesrweb",
+    "email": "47126579+jamesrweb@users.noreply.github.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/P5-wrapper/common.git"
+  },
+  "bugs": {
+    "url": "https://github.com/P5-wrapper/common/issues"
+  },
+  "dependencies": {
+    "microdiff": "^1.6.0"
+  },
+  "peerDependencies": {
+    "p5": ">= 2.0.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.1",
+    "@eslint/config-helpers": "^0.7.0",
+    "@eslint/js": "^10.0.1",
+    "@microsoft/api-extractor": "^7.59.0",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
+    "happy-dom": "^20.14.0",
+    "jiti": "^2.7.0",
+    "p5": "^2.3.2",
+    "prettier": "^3.9.6",
+    "rimraf": "^6.1.3",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.69.0",
+    "vite": "^8.2.2",
+    "vite-plugin-dts": "^5.1.0",
+    "vitest": "^5.0.0",
+    "vitest-canvas-mock": "^1.1.5"
+  }
+}