@cruxgarden/plasma-ui 0.2.4 → 0.5.0

package/dist/renderer.d.ts

@@ -21,6 +21,49 @@ export interface RendererSettings {
     highlight: number;
     /** Thin edge line strength. */
     edgeLine: number;
+    /** Slow iridescent sheen across the body of each surface. 0 = none. */
+    shimmer: number;
+    /** Colored bloom the plasma casts onto the background around it. 0 = none. */
+    glow: number;
+    /** How much the material tints what is seen through it. 0 = clear as water. */
+    wash: number;
+    /** Film grain over the background. 0 = none. */
+    grain: number;
+    /** Blur applied to the background only, in CSS px (0-40). Costs 8 extra blur passes when above 0. */
+    backgroundBlur: number;
+    /**
+     * What the canvas shows where there is no surface. "field" paints the
+     * background everywhere. "clear" leaves it transparent, so the canvas can
+     * sit above other content: only the surfaces, their shadows and rims are
+     * drawn, and what a surface refracts is the `background` source - usually a
+     * live canvas of the field beneath, sampled without swirl so it lines up.
+     */
+    ground: "field" | "clear";
+    /**
+     * Keep each frame in the drawing buffer after it is shown, so another
+     * provider can pass this canvas as its `background` and sample it. Off,
+     * the browser may clear the buffer after compositing and the sample reads
+     * blank. Fixed at creation.
+     */
+    preserveDrawingBuffer: boolean;
+    /** What the surfaces are made of. */
+    material: MaterialName;
+    /** Direction the one light comes from. Every opaque material reads it, so they agree. */
+    lightDir: [number, number, number];
+    /** Surface finish: 0 mirror, 1 chalk. Used by metal; the others carry their own. */
+    roughness: number;
+    /** How far the highlight stretches along the grain. 0 is isotropic. */
+    anisotropy: number;
+    /** How far the outline is displaced from the rounded box, in CSS px. 0 leaves it clean. */
+    edge: number;
+    /** Size of the displacement, in cycles per px. Small is billows, large is chips. */
+    edgeScale: number;
+    /** 0 rolls the displaced edge, 1 breaks it into flats and points. */
+    edgeSharpness: number;
+    /** How thick a panel is as a solid, in CSS px. Only the marched materials use it. */
+    thickness: number;
+    /** Surface tension: how hard the material pulls its own shape toward a bead. */
+    tension: number;
     /** 0 = watery and bouncy, 1 = thick and slow. */
     viscosity: number;
     /** How far the surface trails behind moving panels. 0 = no trailing. */
@@ -40,8 +83,30 @@ export interface RendererSettings {
     /** Background: CSS color, image URL, or a live img/canvas/video source (null for the procedural mood field). */
     background: BackgroundSource | null;
 }
+/**
+ * The materials a surface can be made of. `plasma` is the original and the
+ * default; the rest share its geometry, its springs and its fusing, and differ
+ * only in the composite pass — which is the whole reason they are cheap.
+ */
+export declare const MATERIALS: readonly ["plasma", "crystal", "metal", "mercury", "wood", "stone", "cloud"];
+export type MaterialName = (typeof MATERIALS)[number];
 /** Anything the background can be: a CSS color string, an image URL, or an element to sample (canvas and video update live). */
 export type BackgroundSource = string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap;
+/**
+ * Set on a surface's element from `register` until its form-in has finished
+ * (about half a second; never under reduced motion). Style the element's
+ * children off it to have the contents arrive after the material:
+ * `[data-plasma-forming] > * { opacity: 0 }` with a transition on opacity.
+ */
+export declare const FORMING_ATTR = "data-plasma-forming";
+/**
+ * Events a surface's element dispatches (bubbling, so a page can listen at
+ * the document): `plasmaforming` when the form-in starts, `plasmaformed`
+ * when it has settled — at once under reduced motion. `detail.id` is the
+ * surface id. `<Plasma onForming onFormed>` wraps them.
+ */
+export declare const FORMING_EVENT = "plasmaforming";
+export declare const FORMED_EVENT = "plasmaformed";
 export interface ShapeOptions {
     radius: number;
     lean: number;
@@ -55,6 +120,8 @@ export interface ShapeOptions {
     elevation?: number | null;
     /** When false, this surface never blends, bridges, or joins with others. Default true. */
     fuse?: boolean;
+    /** Snap only against surfaces carrying the same group. null groups with the other ungrouped surfaces. */
+    group?: string | null;
 }
 /** Handle returned by `register`, used by <Plasma>. */
 export interface JoinedSides {
@@ -96,6 +163,13 @@ export declare class PlasmaRenderer {
     private floatOK;
     /** True between webglcontextlost and webglcontextrestored: draw nothing. */
     private lost;
+    private warnedOverflow;
+    /**
+     * Set by destroy(). The canvas and its context outlive this renderer, so an
+     * async callback that lands afterwards would happily allocate on a context
+     * nothing can free it from.
+     */
+    private destroyed;
     private resizeSettle;
     /** Everything initGL() created, so destroy() can free it by hand. */
     private owned;
@@ -145,13 +219,22 @@ export declare class PlasmaRenderer {
     private loadBackground;
     configure(s: RendererSettings, immediate?: boolean): void;
     register(el: HTMLElement, o: ShapeOptions, onJoin?: (j: boolean) => void, onSides?: (sides: JoinedSides) => void): ShapeHandle;
-    /** Layout boxes of all shapes (lean removed; animating draggables report their destination). */
-    layoutBoxes(excludeId?: number, fusingOnly?: boolean): Box[];
+    /**
+     * Layout boxes of all shapes (lean removed; animating draggables report
+     * their destination). Pass `group` to see only the surfaces in that group;
+     * omit it - as any caller written before groups existed does - to see them all.
+     */
+    layoutBoxes(excludeId?: number, fusingOnly?: boolean, group?: string | null): Box[];
     private layoutBoxOf;
     /** Send a pulse through the material from a viewport point. */
     pulse(x: number, y: number, strength?: number): void;
     /** Raise the material's energy (brightens contours and color); it decays on its own. */
     bump(e: number): void;
+    /** Rebuild the shaders and uniform arrays for a new surface budget. */
+    private setMax;
+    private allocUniformArrays;
+    /** Delete every GL object this renderer created, leaving the canvas usable. */
+    private releaseGL;
     /**
      * Every GL object this renderer owns. A lost context invalidates all of
      * them, so creation lives here rather than in the constructor: the restore

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@cruxgarden/plasma-ui",
-  "version": "0.2.4",
+  "version": "0.5.0",
   "description": "Liquid panels for React, rendered in WebGL on canvas: every panel is one shared plasma - they fuse on contact, refract, and snap to a grid.",
   "main": "dist/index.js",
   "scripts": {
     "build": "esbuild src/index.ts --bundle --format=esm --jsx=automatic --target=es2020 --external:react --external:react-dom --outfile=dist/index.js && tsc",
     "build:site": "node site/build.mjs",
     "typecheck": "tsc --noEmit",
+    "typecheck:app": "tsc -p tsconfig.app.json",
+    "typecheck:react19": "npm i --no-save --no-audit --no-fund @types/react@19 @types/react-dom@19 && tsc -p tsconfig.app.json",
+    "format:check": "prettier --check site examples scripts",
     "test": "node --test tests/*.test.mjs",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run verify",
     "format": "prettier --write .",
-    "verify": "npm run typecheck && npm test && npm run build",
+    "check:docs": "node scripts/check-docs.mjs",
+    "verify": "npm run typecheck && npm run typecheck:app && npm run format:check && npm test && npm run build && npm run check:docs",
     "publish:patch": "npm version patch && npm publish && git push && git push --tags",
     "publish:minor": "npm version minor && npm publish && git push && git push --tags",
     "publish:major": "npm version major && npm publish && git push && git push --tags",