@plitzi/sdk-elements 0.38.2 → 0.38.3

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # @plitzi/sdk-elements
 
+## 0.38.3
+
+### Patch Changes
+
+- e047e1d: ## `plitzi upgrade`: a project brought up to its CLI
+
+  A project written by an older CLI had no way up but `plitzi create` in a scratch folder and a file-by-file comparison:
+  `skills update` brought the skills and nothing else, so the `check` and `shot` scripts they teach did not exist.
+  `plitzi upgrade` (also `update`) shows what this CLI writes today for what is the CLI's in the project, and `--write`
+  makes it. One part or several: `plitzi upgrade skills`, `plitzi upgrade files packages`.
+
+  - **`files`:** the CLI's machinery — `author.ts`, `main.ts`, the Playwright, TypeScript and lint configs, AGENTS.md. One
+    nobody changed since the CLI wrote it is replaced, a missing one added; one the project made its own is shown as a
+    diff and left, until `--take <file>` (or `all`). `plitzi create` now records what it wrote, by digest, in
+    `.plitzi/scaffold.json`; a project made before that sees every file that differs as its own.
+  - **`packages`:** `package.json` merged, never replaced — the scripts and dependencies it lacks added, `@plitzi/*`
+    raised to this version, then the install (`--no-install` to leave it). A script of the project's own stays.
+  - **`skills`:** `.claude/skills/plitzi-*` from the packages installed, each replaced whole, and the ones a newer CLI
+    writes added. `plitzi skills update` is `plitzi upgrade skills --write`.
+  - **`renames`:** a name a version renamed with no alias, at its file and line — `canTemplate` → `canSnippet`,
+    `authorTemplate` → `authorSnippet` and its kin (renamed only where imported from `@plitzi/sdk-authoring`) — renamed
+    with `--write`.
+
+  `npm run author` says when the skills or the CLI's files are older than the SDK installed, and `plitzi --version`
+  prints the CLI's.
+
+  ## Page checks that can be the definition of done
+
+  `inspectPage`, `plitzi check` and the scaffold's visual test failed pages that were whole, so an agent learnt to ignore
+  them:
+
+  - **A breakpoint hiding an element on purpose** — the desktop navigation on a phone, a bottom bar only a phone shows —
+    is no longer "not visible": an element whose `display` or `visibility` a breakpoint rule sets is checked at the width
+    it shows at.
+  - **A lazy image out of sight** waits whichever side it is out of: below the fold, as before, or beside the screen in a
+    carousel's track — cut off by any ancestor that clips, as the browser decides when to fetch it.
+  - **A plugin that draws nothing** says so: `drawsNothing: true` in its declaration (a clock that fires a flow), and its
+    handle is `boxless`, so no check waits for it on screen.
+
+  `plitzi check --json` and `PageReport` carry `issues` beside `problems`: each with its `code` (`element-hidden`,
+  `image-not-loaded`, `sideways-scroll`…), the `elementId` it is about and, in `check`, the `width`.
+
+  ## Authoring
+  - **A link's `content` names it.** `control-without-name` read only a link's `label`, so applying the
+    `content-attribute` suggestion as written turned every link into a warning.
+  - **`plitzi fix` writes `content-attribute`** where it has one reading: a button's or link's children that are only
+    `text(…)` and `fontAwesome({ icon })` become its own `content` and `icon` — the words kept as written, an import left
+    unused taken out. A child with an id, options or a class of the space's own stays, and is said. `npm run author`'s
+    `[fix]` line counts these too.
+  - **The recipes, the skill's examples and the catalog template** hold to the suggestions as well as the warnings, and
+    their tests say so: six recipes and the template wrote a link's or a button's words as a child.
+
+  ## Declared motion — in code, in the builder and over MCP
+
+  An element says how it arrives and whether it keeps moving with `motion`, and the SDK's stylesheet plays it — no
+  keyframes to write: `{ enter: 'fade-up', on: 'view' }` arrives as it scrolls into view, `{ enter: 'scale', stagger:
+60 }` brings its children one by one (a grid, a list's rows), `{ loop: 'float' }` keeps it moving. Enters: `fade`,
+  `fade-up`, `fade-down`, `slide-left`, `slide-right`, `scale`; loops: `float`, `pulse`, `spin`, `sway`; `duration`,
+  `delay`, `stagger` in ms. Opacity and the transforms only — an arrival on `translate`/`scale`, so it composes with an
+  element's own `transform` — a loop held until the page is live (`data-hydrated`), and none of it for a visitor who asked
+  for less motion. `view` follows the scroll where the browser has scroll timelines and plays on load where not.
+
+  - **Authoring:** `motion` on any factory; refused where it cannot play (`motion-invalid`, `motion-no-tag`), and carried
+    by `specFromSpace` and `compareSpaces`.
+  - **Builder:** a **Motion** tab in an element's tools: the presets as chips, a stage that plays the one pointed at (a
+    loop shown stronger than the page plays it, and saying so), when and how long, children one by one, and the choices
+    read back as a sentence — laid out side by side once the sidebar is wide enough. The canvas holds motion still while
+    editing; **▶** in the header (or **Play on the canvas** in the tab) plays it from the start, restarting what already
+    played, and an arrival tied to the scroll plays by the clock there, where it is usually in view already.
+  - **MCP:** `motion` on `upsertElement` and `patchElement`, checked the same way; the guide names the presets.
+  - **Schema:** `definition.motion` (`ElementMotion`, `@plitzi/sdk-shared/schema/motion` — the presets, `motionProblems`,
+    `motionAttributes`, `isMotionAnimation`, and each preset's frames, which the stylesheet is tested against), in both
+    init queries. **The platform's GraphQL schema has to declare `SpaceElementMotion`
+    before this version's builder or SDK queries it.**
+
+  ## Dev tools QA: x-ray and motion
+
+  The **QA** tab gains an **X-ray**: every element the document wires something to — bound to data, shown on a condition,
+  running a flow, moving, behind a flag — outlined in its colour and named on the page, read from the space's document by
+  the element's name; its legend counts each kind on the page and picks one to show alone. Beside **Pause**, **Slow**
+  plays every animation at a quarter of its speed and **Replay** plays the declared motion again from the start, without
+  reloading the page.
+
+  ## Plugins that draw
+
+  `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` (`@plitzi/plitzi-sdk`): a canvas sized to the device (at
+  most 2×), followed as it resizes, animating only while somebody can see it move — a live page, no reduced motion, the
+  tab in front, the canvas on screen — and one still frame otherwise (the builder included). `createShaderProgram`
+  compiles and links, and a shader that fails throws a `ShaderError` with the driver's log, printed as
+  `[plugin <type> "<id>"] fragment shader failed: …` instead of an empty canvas; `error` and `ready` say where it is.
+  `useReducedMotion` for the rest.
+
+  ## A space re-authored without a restart
+
+  A project's `npm run start:dev` restarts for its server code and its plugins only: a save to the space is re-authored
+  in a process of its own and every open page loads again (`server.reloadPages()` over an SSE endpoint, on with
+  `createServer({ devReload: true })` — never by `devMode` alone, since every open page holds a connection for it); an
+  edit authoring refuses is printed and the page keeps the last space that authored. A shutdown also ends WebSockets at
+  once (`1001`, going away) rather than waiting out the grace — the ten seconds a restart used to wait on an open page.
+
+  ## Checks and authoring, from the stripe.com experiment
+  - **A component's instance** is found by its own name: its root carries `data-plitzi-instance`, and the instance's
+    handle selects it — `inspectPage` no longer reports every named instance as missing.
+  - **Hidden at this width on purpose** — the burger on a desktop, the desktop menu on a phone — is listed apart
+    (`hiddenAtWidth`, and a dim line under `plitzi check`'s ✓) rather than as a problem.
+  - **An element whose every child is conditional** — four flyouts in one list, each opening on the state that names
+    it — is conditional too: at rest it shows nothing, and that is it working.
+  - **A carousel that scrolls by itself** (`overflow-x: auto`) is not the page scrolling sideways; the page's own pane
+    still is.
+  - **Templates:** `{{ state.faq ?? -1 }}` — a sign on the right of `??` — reads.
+  - **A plugin attribute named as an element field** (`variant`, `class`, `id`…) is warned about
+    (`plugin-attribute-reserved`): a factory never hands it to the plugin. A `variant` no class or type style declares is
+    `unknown-variant`.
+  - **Lists:** a list with `items` renders as the `<ul>` (or `<ol>`) its `subType` says — it was a `<div>` — with no
+    markers and the same spacing, so a page looks as it did; the builder offers the list type for it too. Its rows are
+    `<li>`s: `list-row-not-li` warns of one that is not — a plain container is made one by `fixSpace`, a link or a button
+    is wrapped — and the recipes, the catalog template and the docs write rows as `listItem`.
+  - **CSS:** `mask-size`, `mask-position`, `mask-repeat`, `mask-composite`, `-webkit-mask-image`,
+    `-webkit-background-clip`, `box-decoration-break` and `-webkit-box-decoration-break`.
+  - **`plitzi shot`:** `--clip <element>`, `--scroll-to <element>` and `--viewport`; `--frames` takes the same framing.
+  - **SVG from files:** `svgFile` and `svgFiles` (`@plitzi/sdk-authoring/node`) read a logo or a folder of them,
+    compacted (`compactSvg`, also on the main entry), instead of strings in the space's source.
+  - The plugin scaffolds say that an inline `style` on `RootElement` outranks the element's classes.
+
+- Updated dependencies [e047e1d]
+  - @plitzi/sdk-auth@0.38.3
+  - @plitzi/sdk-dev-tools@0.38.3
+  - @plitzi/sdk-event-bridge@0.38.3
+  - @plitzi/sdk-interactions@0.38.3
+  - @plitzi/sdk-navigation@0.38.3
+  - @plitzi/sdk-schema@0.38.3
+  - @plitzi/sdk-shared@0.38.3
+
 ## 0.38.2
 
 ### Patch Changes

package/dist/Element/RootElement.mjs

@@ -4,67 +4,75 @@ import n from "./helpers/renderStaticTag.mjs";
 import r from "./hooks/useRootElementInteractions.mjs";
 import { useMemo as i } from "react";
 import a from "@plitzi/sdk-shared/hooks/usePlitziServiceContext";
+import { motionAttributes as o } from "@plitzi/sdk-shared/schema/motion";
 //#region src/Element/RootElement.tsx
-var o = ({ ref: o, children: s, tag: c = "div", className: l = "", interactionTriggers: u, interactionCallbacks: d, style: f, ...p }) => {
-	let m = i(() => t(f), [f]), h = e(), g = a(), _ = g.settings.previewMode ?? !0, v = !!g.settings.debugMode;
-	if (h.plitziJsxSkipHOC) return n({
-		tag: c,
-		refProp: o,
-		style: m,
-		className: l,
-		otherProps: p,
-		children: s
+var s = ({ ref: s, children: c, tag: l = "div", className: u = "", interactionTriggers: d, interactionCallbacks: f, style: p, ...m }) => {
+	let h = i(() => t(p), [p]), g = e(), _ = a(), v = _.settings.previewMode ?? !0, y = !!_.settings.debugMode;
+	if (g.plitziJsxSkipHOC) return n({
+		tag: l,
+		refProp: s,
+		style: h,
+		className: u,
+		otherProps: m,
+		children: c
 	});
-	let { root: { baseElementId: y }, contexts: b } = g, x = b.InteractionsContext, { id: S, rootId: C, style: w, definition: { type: T, label: E, runtime: D, anchor: O } } = h, k = D === "server" ? { "data-rsc-id": S } : void 0, A = g.settings.testAttributes === !1 ? void 0 : { "data-plitzi-el": S }, j = !v && (_ || !T || C !== y) ? {} : {
-		"data-id": S,
-		"data-name": E || T || "unknown",
-		"data-root-id": C,
-		"data-type": T || "unknown",
+	let { root: { baseElementId: b }, contexts: x } = _, S = x.InteractionsContext, { id: C, rootId: w, style: T, plitziElementLayout: E, definition: { type: D, label: O, runtime: k, anchor: A, parentId: j, motion: M } } = g, N = o(M), P = k === "server" ? { "data-rsc-id": C } : void 0, F = E?.type === "component" && !j && E.rootId !== C ? E.rootId : void 0, I = _.settings.testAttributes === !1 ? void 0 : {
+		"data-plitzi-el": C,
+		...F === void 0 ? {} : { "data-plitzi-instance": F }
+	}, L = !y && (v || !D || w !== b) ? {} : {
+		"data-id": C,
+		"data-name": O || D || "unknown",
+		"data-root-id": w,
+		"data-type": D || "unknown",
 		"data-root-render-element": !0
 	};
-	if (!x) return n({
-		tag: c,
-		refProp: o,
+	if (!S) return n({
+		tag: l,
+		refProp: s,
 		style: {
-			...w,
-			...m
+			...T,
+			...h,
+			...N.style
 		},
-		className: l,
-		otherProps: p,
-		anchor: O,
-		params: j,
-		serverMarker: k,
-		testMarker: A,
-		children: s
+		className: u,
+		otherProps: m,
+		anchor: A,
+		params: L,
+		serverMarker: P,
+		motion: N.attributes,
+		testMarker: I,
+		children: c
 	});
-	let M = r({
-		elementContext: h,
-		InteractionsContext: x,
-		previewMode: _,
-		debugMode: v,
-		baseElementId: y,
-		className: l,
-		interactionTriggers: u,
-		interactionCallbacks: d,
-		otherProps: p,
-		ref: o
+	let R = r({
+		elementContext: g,
+		InteractionsContext: S,
+		previewMode: v,
+		debugMode: y,
+		baseElementId: b,
+		className: u,
+		interactionTriggers: d,
+		interactionCallbacks: f,
+		otherProps: m,
+		ref: s
 	});
 	return n({
-		tag: c,
-		refProp: M.nodeRef,
+		tag: l,
+		refProp: R.nodeRef,
 		style: {
-			...w,
-			...m
+			...T,
+			...h,
+			...N.style
 		},
-		className: M.className,
-		otherProps: p,
-		anchor: O,
-		params: j,
-		serverMarker: k,
-		testMarker: A,
-		events: M.events,
-		children: s
+		className: R.className,
+		otherProps: m,
+		anchor: A,
+		params: L,
+		serverMarker: P,
+		motion: N.attributes,
+		testMarker: I,
+		events: R.events,
+		children: c
 	});
 };
 //#endregion
-export { o as RootElement, o as default };
+export { s as RootElement, s as default };

package/dist/Element/helpers/renderStaticTag.d.ts

@@ -12,12 +12,18 @@ export type StaticTagProps = {
     serverMarker?: {
         'data-rsc-id': string;
     };
-    /** What an end-to-end test addresses this element by. Last in the spread: nothing may shadow it. */
+    /** The element's declared motion, as the `data-motion-*` the SDK's stylesheet plays (`motionAttributes`). */
+    motion?: Record<string, string>;
+    /**
+     * What an end-to-end test addresses this element by — and, on a component instance's root, the instance. Last in the
+     * spread: nothing may shadow it.
+     */
     testMarker?: {
         'data-plitzi-el': string;
+        'data-plitzi-instance'?: string;
     };
     events?: Record<string, unknown>;
     children?: ReactNode;
 };
-declare const renderStaticTag: ({ tag, refProp, style, className, otherProps, anchor, params, serverMarker, testMarker, events, children }: StaticTagProps) => ReactElement;
+declare const renderStaticTag: ({ tag, refProp, style, className, otherProps, anchor, params, serverMarker, motion, testMarker, events, children }: StaticTagProps) => ReactElement;
 export default renderStaticTag;

package/dist/Element/helpers/renderStaticTag.mjs

@@ -1,15 +1,16 @@
 import { createElement as e } from "react";
 //#region src/Element/helpers/renderStaticTag.ts
-var t = ({ tag: t = "div", refProp: n, style: r, className: i, otherProps: a, anchor: o, params: s, serverMarker: c, testMarker: l, events: u, children: d }) => t === "" ? d : e(t, {
+var t = ({ tag: t = "div", refProp: n, style: r, className: i, otherProps: a, anchor: o, params: s, serverMarker: c, motion: l, testMarker: u, events: d, children: f }) => t === "" ? f : e(t, {
 	ref: n,
 	style: r,
 	className: i,
 	...a,
 	...o ? { id: o } : {},
 	...s,
-	...u,
+	...l,
+	...d,
 	...c,
-	...l
-}, d);
+	...u
+}, f);
 //#endregion
 export { t as default };

package/dist/canvas/index.d.ts

@@ -0,0 +1,6 @@
+export { createShaderProgram, ShaderError } from './shaders';
+export { default as useAnimationFrame } from './useAnimationFrame';
+export { useCanvas2d, useWebGL, useWebGL2 } from './useCanvas';
+export { default as useReducedMotion } from './useReducedMotion';
+export type { AnimationFrameOptions, Frame } from './useAnimationFrame';
+export type { CanvasHandle, CanvasOptions, CanvasSize } from './useCanvas';

package/dist/canvas/index.mjs

@@ -0,0 +1,5 @@
+import { ShaderError as e, createShaderProgram as t } from "./shaders.mjs";
+import n from "./useReducedMotion.mjs";
+import r from "./useAnimationFrame.mjs";
+import { useCanvas2d as i, useWebGL as a, useWebGL2 as o } from "./useCanvas.mjs";
+export { e as ShaderError, t as createShaderProgram, r as useAnimationFrame, i as useCanvas2d, n as useReducedMotion, a as useWebGL, o as useWebGL2 };

package/dist/canvas/shaders.d.ts

@@ -0,0 +1,16 @@
+/** A shader that did not compile, or a program that did not link: what WebGL said, and which stage said it. */
+export declare class ShaderError extends Error {
+    readonly stage: 'vertex' | 'fragment' | 'link';
+    readonly log: string;
+    constructor(stage: ShaderError['stage'], log: string);
+}
+/**
+ * A vertex and a fragment shader, compiled and linked into a program — or a `ShaderError` carrying what the driver
+ * said. WebGL itself fails a shader in silence: `compileShader` returns nothing, the program draws nothing, and the
+ * canvas stays empty with no word of why (`rgb(196, 214, 255)` — integers, where GLSL ES 1.0 wants `196.0`). Thrown
+ * inside `useCanvas`, the error is printed with the element it belongs to and the loop stops.
+ */
+export declare const createShaderProgram: (gl: WebGLRenderingContext | WebGL2RenderingContext, { vertex, fragment }: {
+    vertex: string;
+    fragment: string;
+}) => WebGLProgram;

package/dist/canvas/shaders.mjs

@@ -0,0 +1,25 @@
+//#region src/canvas/shaders.ts
+var e = class extends Error {
+	stage;
+	log;
+	constructor(e, t) {
+		super(`${e === "link" ? "program failed to link" : `${e} shader failed`}: ${t.trim() || "no log given"}`), this.name = "ShaderError", this.stage = e, this.log = t;
+	}
+}, t = (t, n, r) => {
+	let i = t.createShader(n === "vertex" ? t.VERTEX_SHADER : t.FRAGMENT_SHADER);
+	if (!i) throw new e(n, "the context made no shader (it is lost)");
+	if (t.shaderSource(i, r), t.compileShader(i), t.getShaderParameter(i, t.COMPILE_STATUS) !== !0) {
+		let r = t.getShaderInfoLog(i) ?? "";
+		throw t.deleteShader(i), new e(n, r);
+	}
+	return i;
+}, n = (n, { vertex: r, fragment: i }) => {
+	let a = t(n, "vertex", r), o = t(n, "fragment", i), s = n.createProgram();
+	if (n.attachShader(s, a), n.attachShader(s, o), n.linkProgram(s), n.deleteShader(a), n.deleteShader(o), n.getProgramParameter(s, n.LINK_STATUS) !== !0) {
+		let t = n.getProgramInfoLog(s) ?? "";
+		throw n.deleteProgram(s), new e("link", t);
+	}
+	return s;
+};
+//#endregion
+export { e as ShaderError, n as createShaderProgram };

package/dist/canvas/useAnimationFrame.d.ts

@@ -0,0 +1,27 @@
+import { RefObject } from 'react';
+/** One frame: how long the animation has run, in ms — only while it ran — the time since the last frame, and its count. */
+export interface Frame {
+    time: number;
+    delta: number;
+    frame: number;
+}
+export interface AnimationFrameOptions {
+    /** Held still — bound to a hover, a state, a setting. */
+    paused?: boolean;
+    /** At most this many frames a second; every frame the screen draws when left out. */
+    fps?: number;
+    /** The element whose being on screen decides whether it runs: out of sight, nobody sees it move. */
+    target?: RefObject<Element | null>;
+}
+/**
+ * `onFrame` on every frame the screen draws — but only while somebody can see it move: on a page that is live (not
+ * edited in the builder, where a plugin is inert), for a visitor who did not ask for less motion, with the tab in front
+ * and the `target` on screen, and not `paused`. Everything a canvas plugin wrote by hand, each its own way, and the
+ * reason a hero animation kept a laptop's fan on behind a closed tab.
+ *
+ * `running` says which it is, so a plugin can draw one still frame when it is not.
+ */
+declare const useAnimationFrame: (onFrame: (frame: Frame) => void, { paused, fps, target }?: AnimationFrameOptions) => {
+    running: boolean;
+};
+export default useAnimationFrame;

package/dist/canvas/useAnimationFrame.mjs

@@ -0,0 +1,42 @@
+import e from "./useReducedMotion.mjs";
+import { useEffect as t, useRef as n, useState as r, useSyncExternalStore as i } from "react";
+import a from "@plitzi/sdk-shared/hooks/usePlitziServiceContext";
+//#region src/canvas/useAnimationFrame.ts
+var o = (e) => (document.addEventListener("visibilitychange", e), () => document.removeEventListener("visibilitychange", e)), s = () => document.visibilityState !== "hidden", c = (e) => {
+	let [n, i] = r(!0);
+	return t(() => {
+		let t = e?.current;
+		if (!t || typeof IntersectionObserver > "u") return;
+		let n = new IntersectionObserver((e) => i(e.some((e) => e.isIntersecting)));
+		return n.observe(t), () => n.disconnect();
+	}, [e]), n;
+}, l = (r, { paused: l = !1, fps: u, target: d } = {}) => {
+	let f = a().settings.previewMode ?? !0, p = e(), m = i(o, s, () => !1), h = c(d), g = f && !p && !l && m && h, _ = n(r);
+	t(() => {
+		_.current = r;
+	}, [r]);
+	let v = n({
+		time: 0,
+		frame: 0
+	});
+	return t(() => {
+		if (!g) return;
+		let e = u && u > 0 ? 1e3 / u : 0, t = 0, n, r = 0, i = (a) => {
+			let o = n === void 0 ? 0 : a - n;
+			if (n = a, r += o, r >= e) {
+				let t = e > 0 ? r : o;
+				r = e > 0 ? r % e : 0, v.current = {
+					time: v.current.time + t,
+					frame: v.current.frame + 1
+				}, _.current({
+					...v.current,
+					delta: t
+				});
+			}
+			t = requestAnimationFrame(i);
+		};
+		return t = requestAnimationFrame(i), () => cancelAnimationFrame(t);
+	}, [g, u]), { running: g };
+};
+//#endregion
+export { l as default };

package/dist/canvas/useCanvas.d.ts

@@ -0,0 +1,51 @@
+import { AnimationFrameOptions, Frame } from './useAnimationFrame';
+/** The canvas as it is laid out, in CSS pixels, and how many device pixels each of those holds. */
+export interface CanvasSize {
+    width: number;
+    height: number;
+    pixelRatio: number;
+}
+export interface CanvasOptions<C, S> extends Omit<AnimationFrameOptions, 'target'> {
+    /**
+     * Once per context — and again after a lost WebGL context comes back: buffers, programs, gradients. What it returns
+     * is handed to every `draw`. A `ShaderError` (see `createShaderProgram`) or anything else it throws is printed with
+     * the element it belongs to, and nothing is drawn.
+     */
+    setup?: (context: C, size: CanvasSize) => S;
+    /** One frame, in CSS pixels: a 2D context is already scaled to the device's pixels, a WebGL viewport set to them. */
+    draw: (context: C, frame: Frame & CanvasSize & {
+        state: S;
+    }) => void;
+    /** The most device pixels per CSS pixel drawn — a phone at 3 draws nine times a 1× screen's work for little to see. */
+    maxPixelRatio?: number;
+}
+export interface CanvasHandle {
+    /** For the `<canvas>`: `<canvas ref={ref} />`, inside the plugin's `RootElement`. */
+    ref: (canvas: HTMLCanvasElement | null) => void;
+    /** Whether a frame was drawn — until then, what the server rendered (a still image) is what to show. */
+    ready: boolean;
+    /** What failed — setup, a draw, a shader — when something did; the loop is stopped. */
+    error: string | undefined;
+    /** Whether it is animating, or holding the one still frame it drew. */
+    running: boolean;
+}
+type Canvas2dOptions<S> = CanvasOptions<CanvasRenderingContext2D, S> & {
+    attributes?: CanvasRenderingContext2DSettings;
+};
+type WebGLOptions<C, S> = CanvasOptions<C, S> & {
+    attributes?: WebGLContextAttributes;
+};
+/**
+ * A 2D canvas that animates: `draw(ctx, { time, width, height })` in CSS pixels, every frame it should.
+ *
+ * ```tsx
+ * const { ref } = useCanvas2d({ draw: (ctx, { time, width, height }) => { ctx.clearRect(0, 0, width, height); … } });
+ * return <RootElement className={className}><canvas ref={ref} /></RootElement>;
+ * ```
+ */
+export declare const useCanvas2d: <S = undefined>({ attributes, ...options }: Canvas2dOptions<S>) => CanvasHandle;
+/** A WebGL (1) canvas that animates; `setup` compiles with `createShaderProgram`, which says why a shader failed. */
+export declare const useWebGL: <S = undefined>({ attributes, ...options }: WebGLOptions<WebGLRenderingContext, S>) => CanvasHandle;
+/** The same over WebGL 2 — GLSL ES 3.00, where the browser has it; `error` says so where it does not. */
+export declare const useWebGL2: <S = undefined>({ attributes, ...options }: WebGLOptions<WebGL2RenderingContext, S>) => CanvasHandle;
+export {};

package/dist/canvas/useCanvas.mjs

@@ -0,0 +1,133 @@
+import e from "../Element/ElementContext.mjs";
+import t from "./useAnimationFrame.mjs";
+import { use as n, useCallback as r, useEffect as i, useRef as a, useState as o } from "react";
+//#region src/canvas/useCanvas.ts
+var s = (e) => `[plugin ${e?.definition?.type ?? "canvas"}${e?.id ? ` "${e.id}"` : ""}]`, c = (c, { setup: l, draw: u, maxPixelRatio: d = 2, paused: f, fps: p }) => {
+	let m = s(n(e)), h = a(null), [g, _] = o(null), [v, y] = o({
+		width: 0,
+		height: 0,
+		pixelRatio: 1
+	}), [b, x] = o(), [S, C] = o(!1), [w, T] = o(0), E = a(null), D = a({
+		acquire: c,
+		setup: l,
+		draw: u
+	});
+	i(() => {
+		D.current = {
+			acquire: c,
+			setup: l,
+			draw: u
+		};
+	}, [
+		c,
+		l,
+		u
+	]);
+	let O = r((e) => {
+		let t = e instanceof Error ? e.message : String(e);
+		console.error(`${m} ${t}`), x(t);
+	}, [m]), k = r((e) => {
+		h.current = e, _(e);
+	}, []);
+	i(() => {
+		if (!g) return;
+		let e = () => {
+			let e = g.getBoundingClientRect(), t = Math.min(window.devicePixelRatio || 1, d);
+			g.width = Math.max(1, Math.round(e.width * t)), g.height = Math.max(1, Math.round(e.height * t)), y({
+				width: e.width,
+				height: e.height,
+				pixelRatio: t
+			});
+		};
+		if (e(), typeof ResizeObserver > "u") return;
+		let t = new ResizeObserver(e);
+		return t.observe(g), () => t.disconnect();
+	}, [g, d]), i(() => {
+		if (!g) return;
+		let e = (e) => {
+			e.preventDefault(), E.current = null, C(!1);
+		}, t = () => T((e) => e + 1);
+		return g.addEventListener("webglcontextlost", e), g.addEventListener("webglcontextrestored", t), () => {
+			g.removeEventListener("webglcontextlost", e), g.removeEventListener("webglcontextrestored", t);
+		};
+	}, [g]), i(() => {
+		if (g && v.width !== 0 && b === void 0) try {
+			let e = D.current.acquire(g);
+			if (!e) {
+				O(/* @__PURE__ */ Error("the browser gave no drawing context (WebGL may be off)"));
+				return;
+			}
+			e.prepare(v);
+			let t = D.current.setup ? D.current.setup(e.context, v) : void 0;
+			E.current = {
+				handle: e,
+				state: t
+			};
+		} catch (e) {
+			O(e);
+		}
+	}, [
+		g,
+		v,
+		w,
+		b,
+		O
+	]);
+	let A = r((e) => {
+		let t = E.current;
+		if (t && b === void 0) try {
+			t.handle.prepare(v), D.current.draw(t.handle.context, {
+				...e,
+				...v,
+				state: t.state
+			}), C(!0);
+		} catch (e) {
+			E.current = null, O(e);
+		}
+	}, [
+		v,
+		b,
+		O
+	]), { running: j } = t(A, {
+		paused: f || b !== void 0,
+		fps: p,
+		target: h
+	});
+	return i(() => {
+		!j && v.width > 0 && A({
+			time: 0,
+			delta: 0,
+			frame: 0
+		});
+	}, [
+		j,
+		v,
+		w,
+		A
+	]), {
+		ref: k,
+		ready: S,
+		error: b,
+		running: j
+	};
+}, l = ({ attributes: e, ...t }) => c(r((t) => {
+	let n = t.getContext("2d", e);
+	return n && {
+		context: n,
+		prepare: ({ pixelRatio: e }) => n.setTransform(e, 0, 0, e, 0, 0)
+	};
+}, [e]), t), u = ({ attributes: e, ...t }) => c(r((t) => {
+	let n = t.getContext("webgl", e);
+	return n && {
+		context: n,
+		prepare: () => n.viewport(0, 0, t.width, t.height)
+	};
+}, [e]), t), d = ({ attributes: e, ...t }) => c(r((t) => {
+	let n = t.getContext("webgl2", e);
+	return n && {
+		context: n,
+		prepare: () => n.viewport(0, 0, t.width, t.height)
+	};
+}, [e]), t);
+//#endregion
+export { l as useCanvas2d, u as useWebGL, d as useWebGL2 };

package/dist/canvas/useReducedMotion.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether the visitor asked for less motion: their system's setting, or the QA tab's switch. What the CSS of a space
+ * already honours, for the motion a plugin draws itself. False on the server, which draws no motion either way.
+ */
+declare const useReducedMotion: () => boolean;
+export default useReducedMotion;

package/dist/canvas/useReducedMotion.mjs

@@ -0,0 +1,15 @@
+import { useSyncExternalStore as e } from "react";
+//#region src/canvas/useReducedMotion.ts
+var t = "(prefers-reduced-motion: reduce)", n = "plitzi-reduced-motion", r = () => typeof window.matchMedia == "function" && window.matchMedia(t).matches || document.documentElement.classList.contains(n), i = (e) => {
+	let n = typeof window.matchMedia == "function" ? window.matchMedia(t) : void 0;
+	n?.addEventListener("change", e);
+	let r = new MutationObserver(e);
+	return r.observe(document.documentElement, {
+		attributes: !0,
+		attributeFilter: ["class"]
+	}), () => {
+		n?.removeEventListener("change", e), r.disconnect();
+	};
+}, a = () => e(i, r, () => !1);
+//#endregion
+export { a as default };

package/dist/elements/structure/List/List.mjs

@@ -8,6 +8,7 @@ var i = ({ ref: e, className: i = "", subType: a = "ul", children: o, items: s =
 		case "controlled": return /* @__PURE__ */ r(n, {
 			ref: e,
 			className: i,
+			subType: a,
 			items: s,
 			itemKey: l,
 			children: o

package/dist/elements/structure/List/Settings.mjs

@@ -29,7 +29,7 @@ var a = ({ subType: a = "ul", source: o = "none", itemKey: s = "", onUpdate: c }
 				title: "The field of each item that names it, so a row stays with its item when the list is filtered.",
 				onChange: l("itemKey")
 			}),
-			o === "none" && /* @__PURE__ */ n(i, {
+			/* @__PURE__ */ n(i, {
 				label: "List Type",
 				value: a,
 				onChange: l("subType"),

package/dist/elements/structure/List/declaration.mjs

@@ -16,7 +16,7 @@ var n = e()({
 		definition: {
 			label: "List",
 			type: "list",
-			description: "Repeats a template (its listItem/link child) once per entry of a data array — the way to render a dynamic collection. Bind its items to a data source (e.g. an apiContainer response).",
+			description: "Repeats a template (its row: a listItem, or a container with subType \"li\") once per entry of a data array — the way to render a dynamic collection, as a <ul> (subType \"ol\" for a numbered one). Bind its items to a data source (e.g. an apiContainer response).",
 			items: [],
 			bindings: {},
 			styleSelectors: { base: "" },

package/dist/elements/structure/List/modes/ListControlled/ListControlled.d.ts

@@ -2,9 +2,11 @@ import { ReactNode, RefObject } from 'react';
 export type ListControlledProps<T = unknown> = {
     ref?: RefObject<HTMLElement>;
     className: string;
+    /** The list's own tag: a list of data is a list, and each row — an `<li>` — renders straight into it. */
+    subType?: 'ul' | 'ol';
     children: ReactNode;
     items: T[];
     itemKey?: string;
 };
-declare const ListControlled: ({ ref, className, children, items, itemKey }: ListControlledProps) => import('react').JSX.Element;
+declare const ListControlled: ({ ref, className, subType, children, items, itemKey }: ListControlledProps) => import('react').JSX.Element;
 export default ListControlled;

package/dist/elements/structure/List/modes/ListControlled/ListControlled.mjs

@@ -13,27 +13,28 @@ import m from "clsx";
 import h from "@plitzi/sdk-shared/dataSource/helpers/getSourceName";
 import g from "@plitzi/sdk-shared/dataSource/hooks/useRegisterSource";
 //#region src/elements/structure/List/modes/ListControlled/ListControlled.tsx
-var _ = ({ ref: _, className: v = "", children: y, items: b = [], itemKey: x }) => {
-	let { id: S, definition: { label: C } } = e(), w = h(i.sourceType, S), { settings: { previewMode: T } } = s(), E = o(() => Array.isArray(b) ? b : [], [b]), D = o(() => n(E, x), [E, x]), O = a(() => d({
-		item: c(E, "0", {}),
+var _ = ({ ref: _, className: v = "", subType: y = "ul", children: b, items: x = [], itemKey: S }) => {
+	let { id: C, definition: { label: w } } = e(), T = h(i.sourceType, C), { settings: { previewMode: E } } = s(), D = o(() => Array.isArray(x) ? x : [], [x]), O = o(() => n(D, S), [D, S]), k = a(() => d({
+		item: c(D, "0", {}),
 		index: 0
 	}).reduce((e, t) => [...e, {
 		path: t,
 		name: t
-	}], []), [E]), k = o(() => w ? { runtime: { sources: { [w]: { items: E } } } } : u, [w, E]);
+	}], []), [D]), A = o(() => T ? { runtime: { sources: { [T]: { items: D } } } } : u, [T, D]);
 	return g({
-		id: S,
-		source: w,
-		name: C || `List - ${S}`,
-		fields: O
+		id: C,
+		source: T,
+		name: w || `List - ${C}`,
+		fields: k
 	}), /* @__PURE__ */ p(t, {
 		ref: _,
-		className: m("plitzi-component__controlled-list", v, { "controlled-list--build-mode": !T }),
+		tag: y,
+		className: m("plitzi-component__controlled-list", v, { "controlled-list--build-mode": !E }),
 		children: [/* @__PURE__ */ f(l, {
 			inherit: "live",
-			name: `List:${S}`,
-			value: k,
-			children: E.map((e, t) => !y || Array.isArray(y) && y.length === 0 ? /* @__PURE__ */ f("div", {
+			name: `List:${C}`,
+			value: A,
+			children: D.map((e, t) => !b || Array.isArray(b) && b.length === 0 ? /* @__PURE__ */ f("div", {
 				className: "plitzi-component__controlled-list-item controlled-list--empty",
 				children: /* @__PURE__ */ f("div", {
 					className: "controlled-list-item__counter",
@@ -41,12 +42,12 @@ var _ = ({ ref: _, className: v = "", children: y, items: b = [], itemKey: x })
 				})
 			}, t) : /* @__PURE__ */ f(r, {
 				index: t,
-				isTemplate: t !== 0 && !T,
+				isTemplate: t !== 0 && !E,
 				record: e,
-				source: w,
-				children: y
-			}, D[t]))
-		}), !T && E.length === 0 && /* @__PURE__ */ f("div", {
+				source: T,
+				children: b
+			}, O[t]))
+		}), !E && D.length === 0 && /* @__PURE__ */ f("div", {
 			className: "controlled-list controlled-list--empty",
 			children: "This list does not contain any items"
 		})]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-elements",
-  "version": "0.38.2",
+  "version": "0.38.3",
   "license": "AGPL-3.0",
   "files": [
     "dist"
@@ -162,6 +162,30 @@
       "types": "./dist/Element/hooks/useScrollInteractions.d.ts",
       "import": "./dist/Element/hooks/useScrollInteractions.mjs"
     },
+    "./canvas": {
+      "types": "./dist/canvas/index.d.ts",
+      "import": "./dist/canvas/index.mjs"
+    },
+    "./canvas/index": {
+      "types": "./dist/canvas/index.d.ts",
+      "import": "./dist/canvas/index.mjs"
+    },
+    "./canvas/shaders": {
+      "types": "./dist/canvas/shaders.d.ts",
+      "import": "./dist/canvas/shaders.mjs"
+    },
+    "./canvas/useAnimationFrame": {
+      "types": "./dist/canvas/useAnimationFrame.d.ts",
+      "import": "./dist/canvas/useAnimationFrame.mjs"
+    },
+    "./canvas/useCanvas": {
+      "types": "./dist/canvas/useCanvas.d.ts",
+      "import": "./dist/canvas/useCanvas.mjs"
+    },
+    "./canvas/useReducedMotion": {
+      "types": "./dist/canvas/useReducedMotion.d.ts",
+      "import": "./dist/canvas/useReducedMotion.mjs"
+    },
     "./components/ElementAdvancedEditor": {
       "types": "./dist/components/ElementAdvancedEditor.d.ts",
       "import": "./dist/components/ElementAdvancedEditor.mjs"
@@ -1270,13 +1294,13 @@
   "dependencies": {
     "@plitzi/nexus": "^1.4.0",
     "@plitzi/plitzi-ui": "^1.6.29",
-    "@plitzi/sdk-auth": "0.38.2",
-    "@plitzi/sdk-dev-tools": "0.38.2",
-    "@plitzi/sdk-event-bridge": "0.38.2",
-    "@plitzi/sdk-interactions": "0.38.2",
-    "@plitzi/sdk-navigation": "0.38.2",
-    "@plitzi/sdk-schema": "0.38.2",
-    "@plitzi/sdk-shared": "0.38.2",
+    "@plitzi/sdk-auth": "0.38.3",
+    "@plitzi/sdk-dev-tools": "0.38.3",
+    "@plitzi/sdk-event-bridge": "0.38.3",
+    "@plitzi/sdk-interactions": "0.38.3",
+    "@plitzi/sdk-navigation": "0.38.3",
+    "@plitzi/sdk-schema": "0.38.3",
+    "@plitzi/sdk-shared": "0.38.3",
     "clsx": "^2.1.1",
     "immer": "^11.1.21"
   },