svelte-p5-viz 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,132 @@
+# svelte-p5-viz
+
+> Visualization panel contract, registry, and scene-config types for [`svelte-p5`](../core). The load-bearing abstraction for composing canvas-based dashboards — by hand, or eventually through a no-code studio.
+
+```bash
+pnpm add svelte-p5-viz svelte-p5 p5
+```
+
+## What this is
+
+A set of TypeScript types and tiny runtime helpers that let multiple visualizations share one canvas, coordinate hover state, and serialize to JSON. It is deliberately thin: no actual visualization code ships in this package. Visualizations live in your app (or eventually in a separate viz-pack) and implement the contract below.
+
+```ts
+import type { VizPanel } from 'svelte-p5-viz';
+
+interface WordCloudData {
+	words: { text: string; weight: number }[];
+}
+interface WordCloudConfig {
+	minFontSize: number;
+	maxFontSize: number;
+}
+
+export const WordCloudPanel: VizPanel<WordCloudData, WordCloudConfig> = {
+	type: 'word-cloud',
+	defaultConfig: { minFontSize: 10, maxFontSize: 48 },
+	render(ctx, data, config) {
+		const { sk, bounds, mouse, highlights } = ctx;
+		// …draw into sk within bounds…
+		return { hover: null };
+	}
+};
+```
+
+A scene mounts N panels into a canvas, reads hover from each, surfaces tooltips and cross-highlighting through shared chrome. Because panels share a contract, chrome doesn't care which panel type is in any given slot.
+
+## The contract
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Scene runner  (your app, or a future studio runtime)       │
+│  ────────────                                               │
+│  Reads SceneConfig → resolves types via PanelRegistry →     │
+│  renders each panel into its Bounds → funnels hover into    │
+│  a shared SceneState → exposes hover to other panels via    │
+│  PanelContext.highlights                                    │
+└──────────────┬──────────────────────────────────────────────┘
+               │ VizPanel.render(ctx, data, config)
+               ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Your panel implementations                                 │
+│  Pure functions of (data, config, ctx) → PanelResult        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The four types that matter:
+
+- **`VizPanel<TData, TConfig>`** — the renderer. `type`, `defaultConfig`, and a `render(ctx, data, config)` method.
+- **`PanelContext`** — what the renderer receives: live `sk` instance, `bounds` rect, optional `mouse` position, and `highlights` from sibling panels.
+- **`PanelResult`** — what the renderer returns: at minimum a `hover: PanelHit | null`. Optional `overflow: boolean`.
+- **`PanelHit`** — `{ id, meta? }`. Two panels agreeing on the same `id` shape is how cross-highlighting works — no event bus required.
+
+## Scenes
+
+A `SceneConfig` is JSON-serializable. Today, you hand-write one and hand it to your app's scene runner. Tomorrow, a studio app will read and write them.
+
+```ts
+import type { SceneConfig } from 'svelte-p5-viz';
+
+const scene: SceneConfig = {
+	version: 1,
+	name: 'Speaker overview',
+	panels: [
+		{ id: 'cloud', type: 'word-cloud' },
+		{ id: 'timeline', type: 'timeline-track' }
+	],
+	layout: {
+		kind: 'split',
+		orientation: 'vertical',
+		position: 70,
+		first: 'cloud',
+		second: 'timeline'
+	}
+};
+```
+
+Layouts cover the three shapes every multi-panel canvas app ends up reinventing:
+
+- `{ kind: 'single', panel }` — full-bleed.
+- `{ kind: 'split', orientation, position, first, second }` — two-up with a divider.
+- `{ kind: 'grid', columns, gap, padding, panels }` — N-up grid.
+
+That's intentionally sparse. Arbitrary dock trees (tabs, nested splits, floating windows) are out of scope — for those use [`dockview`](https://dockview.dev/) or similar. Chrome for each of the three layouts lives in [`svelte-p5-components`](../components).
+
+## Registry
+
+```ts
+import { createPanelRegistry } from 'svelte-p5-viz';
+
+export const registry = createPanelRegistry();
+registry.register(WordCloudPanel);
+registry.register(TimelineTrackPanel);
+// registry.get('word-cloud')  → WordCloudPanel
+// registry.list()              → all of them
+```
+
+Use a single registry per scene runner. The runner's job is to look up each `PanelInstance.type`, instantiate it with merged config, and call `render(ctx, data, config)` inside the p5 draw loop.
+
+## Shared state
+
+Chrome that wants cross-panel hover / highlighting creates one `SceneState` per scene and threads it through `PanelContext`:
+
+```ts
+import { createSceneState } from 'svelte-p5-viz';
+
+const scene = createSceneState();
+// scene.hover       — current PanelHit across all panels
+// scene.highlights  — ids other panels should emphasize
+```
+
+Scene state is a Svelte 5 `$state` proxy — mutate it directly, Svelte handles reactivity.
+
+## What this package deliberately doesn't ship
+
+- **Any panel implementations.** Those belong in app code or a future `svelte-p5-viz-pack`.
+- **A scene runner.** One sample runner lives in [`svelte-p5-components`](../components/) as `<SceneRenderer>`; you can also write your own in ~30 lines.
+- **Runtime schema validation.** `VizPanel.schema` is typed as `unknown` so you can plug zod/valibot/arktype (or none). Validation is a studio concern, not a runtime one.
+- **Persistence.** Serializing a `SceneConfig` is `JSON.stringify`; loading is `JSON.parse`. That's the whole API.
+
+## Versioning
+
+`0.x` is unstable. Breaking changes bump the minor and are called out with `BREAKING CHANGE:` in the commit. The `version` field on `SceneConfig` will bump when the format itself changes, with a documented migration path.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { Bounds, PanelContext, PanelHit, PanelResult, VizPanel } from './types.js';
+export { createPanelRegistry, type PanelRegistry } from './registry.js';
+export type { GridSceneLayout, PanelInstance, SceneConfig, SceneLayout, SingleSceneLayout, SplitSceneLayout } from './scene.js';
+export { createSceneState, type SceneState } from './scene-state.svelte.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+// Registry
+export { createPanelRegistry } from './registry.js';
+// Reactive cross-panel state (for chrome wrappers)
+export { createSceneState } from './scene-state.svelte.js';

package/dist/registry.d.ts

@@ -0,0 +1,37 @@
+import type { VizPanel } from './types.js';
+/**
+ * Typed lookup table from panel `type` strings to panel implementations.
+ * A scene runner resolves a {@link PanelInstance} to a live panel through a
+ * registry; the studio discovers available panel types by listing one.
+ */
+export interface PanelRegistry {
+    /**
+     * Register a panel implementation. Throws if the `type` is already taken —
+     * duplicate types would be a silent correctness hazard in the no-code studio.
+     */
+    register<TData, TConfig>(panel: VizPanel<TData, TConfig>): void;
+    /** Look up a panel by its registered type. `undefined` if not registered. */
+    get(type: string): VizPanel | undefined;
+    /** Whether a panel with this type is registered. */
+    has(type: string): boolean;
+    /** Snapshot of all registered panels, in insertion order. */
+    list(): readonly VizPanel[];
+    /** Remove a panel implementation. Returns whether anything was removed. */
+    unregister(type: string): boolean;
+}
+/**
+ * Create an empty panel registry. A scene runner typically creates one at
+ * boot, calls {@link PanelRegistry.register} for each panel the app exposes,
+ * and hangs onto it for the session.
+ *
+ * @example
+ * ```ts
+ * import { createPanelRegistry } from 'svelte-p5-viz';
+ * import { WordCloudPanel, TimelineTrackPanel } from './panels';
+ *
+ * export const registry = createPanelRegistry();
+ * registry.register(WordCloudPanel);
+ * registry.register(TimelineTrackPanel);
+ * ```
+ */
+export declare function createPanelRegistry(): PanelRegistry;

package/dist/registry.js

@@ -0,0 +1,38 @@
+/**
+ * Create an empty panel registry. A scene runner typically creates one at
+ * boot, calls {@link PanelRegistry.register} for each panel the app exposes,
+ * and hangs onto it for the session.
+ *
+ * @example
+ * ```ts
+ * import { createPanelRegistry } from 'svelte-p5-viz';
+ * import { WordCloudPanel, TimelineTrackPanel } from './panels';
+ *
+ * export const registry = createPanelRegistry();
+ * registry.register(WordCloudPanel);
+ * registry.register(TimelineTrackPanel);
+ * ```
+ */
+export function createPanelRegistry() {
+    const panels = new Map();
+    return {
+        register(panel) {
+            if (panels.has(panel.type)) {
+                throw new Error(`[svelte-p5-viz] panel "${panel.type}" is already registered`);
+            }
+            panels.set(panel.type, panel);
+        },
+        get(type) {
+            return panels.get(type);
+        },
+        has(type) {
+            return panels.has(type);
+        },
+        list() {
+            return [...panels.values()];
+        },
+        unregister(type) {
+            return panels.delete(type);
+        }
+    };
+}

package/dist/scene-state.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { PanelHit } from './types.js';
+/**
+ * Reactive chrome-level state shared across all panels in a scene. Chrome
+ * wrappers read/write this; panels receive a read view via {@link PanelContext.highlights}.
+ *
+ * The ergonomics match Svelte 5's rune model — the returned object is a
+ * `$state` proxy; mutate it directly from chrome code.
+ */
+export interface SceneState {
+    /** The most-recently-reported hit across all panels this frame. */
+    hover: PanelHit | null;
+    /**
+     * Ids other panels should highlight. Populated by chrome when `hover`
+     * changes, cleared when `hover` goes null. Panels read a read-only snapshot
+     * via {@link PanelContext.highlights}.
+     */
+    highlights: string[];
+}
+/**
+ * Create a fresh reactive scene-state store. Call once per scene instance
+ * (typically inside a chrome wrapper's `$effect`).
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createSceneState } from 'svelte-p5-viz';
+ *
+ *   const scene = createSceneState();
+ *
+ *   function onPanelHit(hit) {
+ *     scene.hover = hit;
+ *     scene.highlights = hit ? [hit.id] : [];
+ *   }
+ * </script>
+ * ```
+ */
+export declare function createSceneState(): SceneState;

package/dist/scene-state.svelte.js

@@ -0,0 +1,25 @@
+/**
+ * Create a fresh reactive scene-state store. Call once per scene instance
+ * (typically inside a chrome wrapper's `$effect`).
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createSceneState } from 'svelte-p5-viz';
+ *
+ *   const scene = createSceneState();
+ *
+ *   function onPanelHit(hit) {
+ *     scene.hover = hit;
+ *     scene.highlights = hit ? [hit.id] : [];
+ *   }
+ * </script>
+ * ```
+ */
+export function createSceneState() {
+    const state = $state({
+        hover: null,
+        highlights: []
+    });
+    return state;
+}

package/dist/scene.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A panel placed in a scene. The `type` maps to a {@link VizPanel} in the
+ * registry; `config` is the per-instance override that gets shallow-merged
+ * over the panel's `defaultConfig`.
+ */
+export interface PanelInstance {
+    /** Scene-unique id. Layouts reference panels by this. */
+    readonly id: string;
+    /** Registered panel type (see {@link VizPanel.type}). */
+    readonly type: string;
+    /** Optional human-readable label for the no-code studio. */
+    readonly label?: string;
+    /** Per-instance config override. Missing keys fall back to the panel's defaultConfig. */
+    readonly config?: Record<string, unknown>;
+}
+/**
+ * Arrange panels in an equal-cell grid. `columns` fixes width; the number of
+ * rows is derived from the panel count.
+ */
+export interface GridSceneLayout {
+    readonly kind: 'grid';
+    /** Number of columns. Must be ≥ 1. */
+    readonly columns: number;
+    /** CSS gap (px) between cells. Default: 8. */
+    readonly gap?: number;
+    /** CSS padding (px) inside the canvas. Default: 0. */
+    readonly padding?: number;
+    /** Panel instance ids in reading order (row-major). */
+    readonly panels: readonly string[];
+}
+/**
+ * Two-panel split with a draggable divider. Consumers render the divider
+ * themselves (see `<SplitPane>` in svelte-p5-components); this type just
+ * captures the config.
+ */
+export interface SplitSceneLayout {
+    readonly kind: 'split';
+    readonly orientation: 'horizontal' | 'vertical';
+    /** Divider position as a percentage (0-100) from the top/left. */
+    readonly position: number;
+    /** Panel instance id in the first slot (top / left). */
+    readonly first: string;
+    /** Panel instance id in the second slot (bottom / right). */
+    readonly second: string;
+}
+/** A single panel filling the entire canvas. */
+export interface SingleSceneLayout {
+    readonly kind: 'single';
+    readonly panel: string;
+}
+export type SceneLayout = GridSceneLayout | SplitSceneLayout | SingleSceneLayout;
+/**
+ * A complete scene description — enough to reconstruct a visualization from
+ * JSON on disk, a URL hash, or a no-code studio export.
+ *
+ * The format is versioned so future non-backward-compatible additions can
+ * ship behind a migration step.
+ */
+export interface SceneConfig {
+    readonly version: 1;
+    /** Optional human-readable name (for tab titles, exports). */
+    readonly name?: string;
+    /** Panel definitions — referenced by id from the layout. */
+    readonly panels: readonly PanelInstance[];
+    /** How to arrange the panels spatially. */
+    readonly layout: SceneLayout;
+}

package/dist/scene.js

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

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+import type p5 from 'p5';
+/**
+ * A rectangular region in canvas coordinates. Chrome slices a canvas into
+ * these and hands them to panels; panels render inside them and nothing else.
+ */
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A hit emitted by a panel — what's currently under the pointer (or
+ * otherwise "selected" by the panel). Chrome surfaces it for tooltips,
+ * cross-highlighting, and scene-level selection state.
+ *
+ * `id` is the contract between panels: two panels agreeing on the same id
+ * (e.g. a speaker name, a turn number, a timestamp) is how cross-highlighting
+ * works without any bespoke event bus.
+ */
+export interface PanelHit {
+    /** Stable identifier. Panels that want to cross-highlight should agree on the id shape. */
+    readonly id: string;
+    /** Optional panel-specific payload. Consumers of the hit should treat this as untrusted and narrow it themselves. */
+    readonly meta?: unknown;
+}
+/**
+ * Everything a panel is handed on each render frame. Ambient state only —
+ * a panel should never need to reach outside the PanelContext for chrome
+ * concerns (bounds, mouse, highlights).
+ */
+export interface PanelContext {
+    /** Live p5 instance. Panels draw into its current renderer. */
+    readonly sk: p5;
+    /** The rectangle this panel owns for the frame. Don't draw outside it. */
+    readonly bounds: Bounds;
+    /** Pointer position in canvas coordinates, or `null` if the pointer is off-canvas. */
+    readonly mouse: {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Ids other panels emitted as hits (or hover) this frame. A panel that
+     * renders the same domain object should visually emphasise or dim items
+     * whose id matches an entry here. Read-only — write via the returned
+     * `PanelResult.hover`.
+     */
+    readonly highlights: ReadonlyArray<string>;
+}
+/**
+ * What a panel returns after drawing one frame. Only chrome-relevant state
+ * belongs here; app-specific side channels live in the panel's own instance
+ * state or in the shared data layer.
+ */
+export interface PanelResult {
+    /** What this panel is currently hovering over. `null` means nothing is under the cursor. */
+    readonly hover: PanelHit | null;
+    /** Signals that the panel's content overflowed its bounds — chrome can render an indicator. */
+    readonly overflow?: boolean;
+}
+/**
+ * The core contract. A panel is a stateless renderer for one kind of
+ * visualization. Instantiated once, called every frame with fresh
+ * data, config, and bounds.
+ *
+ * Panel implementations should avoid storing per-frame state on the panel
+ * itself; cache-worthy state (e.g. offscreen buffers) is fine, but anything
+ * time-varying belongs in the data the caller passes in.
+ *
+ * @template TData — the shape of data this panel renders
+ * @template TConfig — user-tunable knobs (colors, thresholds, modes)
+ */
+export interface VizPanel<TData = unknown, TConfig = unknown> {
+    /** Registry key. Must be unique across all panels a scene uses. */
+    readonly type: string;
+    /** Config used when a scene instance provides no override. Shallow-merged with per-instance config. */
+    readonly defaultConfig: TConfig;
+    /**
+     * Optional runtime schema for the config. Typed as `unknown` so the contract
+     * stays schema-library-agnostic — use zod, valibot, arktype, or plain JSON
+     * Schema. The no-code studio will inspect this to generate property panels.
+     */
+    readonly schema?: unknown;
+    /** Render one frame. Called from inside the p5 draw loop by a scene runner. */
+    render(ctx: PanelContext, data: TData, config: TConfig): PanelResult;
+    /** Optional cleanup hook — release p5.Graphics buffers or other owned resources here. */
+    dispose?(): void;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "svelte-p5-viz",
+  "version": "0.2.0",
+  "description": "Visualization panel contract, registry, and scene-config types for svelte-p5. Composable, no-code-ready building blocks for canvas-based dashboards.",
+  "keywords": [
+    "svelte",
+    "svelte5",
+    "p5",
+    "p5.js",
+    "visualization",
+    "dashboard",
+    "panel",
+    "no-code"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edw1nzhao/svelte-p5.git",
+    "directory": "packages/viz"
+  },
+  "homepage": "https://github.com/edw1nzhao/svelte-p5/tree/main/packages/viz#readme",
+  "bugs": {
+    "url": "https://github.com/edw1nzhao/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"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "svelte-package -o dist && publint",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "peerDependencies": {
+    "p5": ">=1.11.0 <3",
+    "svelte": "^5.0.0",
+    "svelte-p5": "workspace:^"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "catalog:",
+    "@sveltejs/vite-plugin-svelte": "catalog:",
+    "@types/p5": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "p5": "catalog:",
+    "publint": "catalog:",
+    "svelte": "catalog:",
+    "svelte-check": "catalog:",
+    "svelte-p5": "workspace:*",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
+  }
+}