@cueplusplus/ui 0.18.2 → 0.20.0

package/dist/brand/particle-logo.js

@@ -0,0 +1,437 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { usePrefersReducedMotion } from "../instruments/_motion.js";
+import { useStill } from "../system/still.js";
+import { FAR, NEAR, TouchTrail, logoScale, modelView, normaliseColour, perspective, pickWaveColor, rasterise, sampleParticles, srgbToLinear, viewportAt } from "../lib/particle-field.js";
+import { FRAGMENT_SHADER, VERTEX_SHADER } from "../lib/particle-field-shaders.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/brand/particle-logo.tsx
+/**
+* The roles a wave sweeps through when no `waveColors` are given: the Look's own accent and
+* signal colours, read off the element at run time, so the waves are the theme's.
+*/
+const ROLE_COLOURS = [
+	"--cue-accent",
+	"--cue-info",
+	"--cue-busy",
+	"--cue-ok",
+	"--cue-warn",
+	"--cue-danger",
+	"--cue-stream",
+	"--cue-fg"
+];
+/** The Look's role colours as linear-light triples, read through the element's own cascade. */
+function rolePalette(element) {
+	const style = getComputedStyle(element);
+	return ROLE_COLOURS.map((name) => normaliseColour(style.getPropertyValue(name).trim())).filter((hex) => hex !== null).map(srgbToLinear);
+}
+function compile(gl, type, source) {
+	const shader = gl.createShader(type);
+	if (shader === null) return null;
+	gl.shaderSource(shader, source);
+	gl.compileShader(shader);
+	if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+		gl.deleteShader(shader);
+		return null;
+	}
+	return shader;
+}
+function build(gl, raster, sampled) {
+	const vertex = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
+	const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
+	if (vertex === null || fragment === null) return null;
+	const program = gl.createProgram();
+	gl.attachShader(program, vertex);
+	gl.attachShader(program, fragment);
+	gl.linkProgram(program);
+	gl.deleteShader(vertex);
+	gl.deleteShader(fragment);
+	if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+		gl.deleteProgram(program);
+		return null;
+	}
+	const vao = gl.createVertexArray();
+	gl.bindVertexArray(vao);
+	const buffers = [];
+	const attribute = (name, data, size, type, divisor) => {
+		const location = gl.getAttribLocation(program, name);
+		const buffer = gl.createBuffer();
+		buffers.push(buffer);
+		gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+		gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+		if (location < 0) return;
+		gl.enableVertexAttribArray(location);
+		gl.vertexAttribPointer(location, size, type, false, 0, 0);
+		gl.vertexAttribDivisor(location, divisor);
+	};
+	attribute("position", new Float32Array([
+		-.5,
+		.5,
+		0,
+		.5,
+		.5,
+		0,
+		-.5,
+		-.5,
+		0,
+		.5,
+		-.5,
+		0
+	]), 3, gl.FLOAT, 0);
+	attribute("uv", new Float32Array([
+		0,
+		0,
+		1,
+		0,
+		0,
+		1,
+		1,
+		1
+	]), 2, gl.FLOAT, 0);
+	attribute("pindex", sampled.indices, 1, gl.UNSIGNED_SHORT, 1);
+	attribute("offset", sampled.offsets, 3, gl.FLOAT, 1);
+	attribute("angle", sampled.angles, 1, gl.FLOAT, 1);
+	const elements = gl.createBuffer();
+	buffers.push(elements);
+	gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, elements);
+	gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, new Uint16Array([
+		0,
+		2,
+		1,
+		2,
+		3,
+		1
+	]), gl.STATIC_DRAW);
+	gl.bindVertexArray(null);
+	const image = gl.createTexture();
+	gl.bindTexture(gl.TEXTURE_2D, image);
+	gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+	gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, raster.width, raster.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array(raster.data.buffer));
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+	const touch = gl.createTexture();
+	gl.bindTexture(gl.TEXTURE_2D, touch);
+	gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, TouchTrail.SIZE, TouchTrail.SIZE, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+	const locations = /* @__PURE__ */ new Map();
+	const uniform = (name) => {
+		if (!locations.has(name)) locations.set(name, gl.getUniformLocation(program, name));
+		return locations.get(name);
+	};
+	return {
+		program,
+		vao,
+		buffers,
+		image,
+		touch,
+		count: sampled.count,
+		uniform
+	};
+}
+function release(gl, scene) {
+	for (const buffer of scene.buffers) gl.deleteBuffer(buffer);
+	gl.deleteVertexArray(scene.vao);
+	gl.deleteTexture(scene.image);
+	gl.deleteTexture(scene.touch);
+	gl.deleteProgram(scene.program);
+}
+/**
+* A mark drawn as a field of particles that wiggle, flip colour in sweeping waves and scatter
+* from the pointer — cueplusplus.com's hero logo, ported from three.js to raw WebGL2 with its
+* shaders unchanged (spec 2026-10-04-cue-site-verbatim §4.1).
+*
+* The camera, the mesh scale, the textures, the blending and the wave and touch timings are the
+* source's, copied: a 50° camera at z = 300, the mark 26% of the canvas's height, a wave every
+* 4–8s that sweeps in 2s and fades to white over 3s, a pointer trail that ages over 80 rendered
+* updates. It renders at about 30fps and costs nothing off screen or in a hidden tab.
+*
+* **Without WebGL2, or held still** (a thumbnail, or a reader who prefers reduced motion), it
+* draws the source image itself, still, at the same fit — a picture of the mark rather than of
+* the particles, which the docs say. A lost context draws the still until it is restored.
+*
+* Decorative: the canvas is hidden from assistive technology; name the mark on the element
+* around it.
+*
+* @example
+* <div role="img" aria-label="CUE++" className="h-[460px]">
+*   <ParticleLogo src="/logo.png" />
+* </div>
+*/
+const ParticleLogo = React.forwardRef(function ParticleLogo({ src, fit = "logo", containFill = .85, particleSize = .5, randomSpread = 2, skipRatio = 36, waveColors, className, style, ...props }, ref) {
+	const held = useStill();
+	const reduced = usePrefersReducedMotion();
+	const still = held || reduced;
+	const canvas = React.useRef(null);
+	const [failed, setFailed] = React.useState(false);
+	const [lost, setLost] = React.useState(false);
+	const paletteKey = (waveColors ?? []).join(",");
+	const drawStill = still || failed;
+	React.useEffect(() => {
+		if (drawStill) return;
+		const element = canvas.current;
+		if (element === null) return;
+		const gl = typeof WebGL2RenderingContext === "undefined" ? null : element.getContext("webgl2", {
+			antialias: true,
+			alpha: true,
+			premultipliedAlpha: true
+		});
+		if (gl === null) {
+			setFailed(true);
+			return;
+		}
+		const given = paletteKey === "" ? [] : paletteKey.split(",").map(srgbToLinear);
+		const varied = (colours) => colours.some((colour) => colour.join() !== colours[0].join());
+		let palette = varied(given) ? given : rolePalette(element);
+		if (palette.length === 0) palette = [[
+			1,
+			1,
+			1
+		]];
+		let disposed = false;
+		let contextLost = gl.isContextLost();
+		setLost(contextLost);
+		let scene = null;
+		let raster = null;
+		let raf = 0;
+		let visible = true;
+		const trail = new TouchTrail();
+		const touchCanvas = document.createElement("canvas");
+		touchCanvas.width = TouchTrail.SIZE;
+		touchCanvas.height = TouchTrail.SIZE;
+		const touchContext = touchCanvas.getContext("2d");
+		const pointer = {
+			x: 0,
+			y: 0
+		};
+		const onPointer = (event) => {
+			const box = element.getBoundingClientRect();
+			pointer.x = (event.clientX - box.left) / box.width * 2 - 1;
+			pointer.y = -((event.clientY - box.top) / box.height) * 2 + 1;
+		};
+		element.addEventListener("pointermove", onPointer);
+		const state = {
+			time: 0,
+			uTime: 0,
+			waving: false,
+			waveStart: 0,
+			waveDuration: 2,
+			nextWaveDelay: 5,
+			lastWaveEnd: -3,
+			direction: [1, 0],
+			position: 0,
+			waveTime: 0,
+			colour: palette[Math.floor(Math.random() * palette.length)],
+			previous: [
+				1,
+				1,
+				1
+			],
+			fade: 1
+		};
+		const resize = () => {
+			const dpr = Math.min(Math.max(window.devicePixelRatio || 1, 1), 2);
+			const width = Math.max(1, Math.round(element.clientWidth * dpr));
+			const height = Math.max(1, Math.round(element.clientHeight * dpr));
+			if (element.width !== width || element.height !== height) {
+				element.width = width;
+				element.height = height;
+			}
+			gl.viewport(0, 0, width, height);
+			return element.clientWidth / Math.max(1, element.clientHeight);
+		};
+		const frame = (delta) => {
+			if (scene === null || raster === null) return;
+			const s = state;
+			s.uTime += delta;
+			if (!s.waving) {
+				if (s.time - s.lastWaveEnd > s.nextWaveDelay) {
+					s.waving = true;
+					s.waveStart = s.time;
+					const angle = Math.random() * Math.PI * 2;
+					s.direction = [Math.cos(angle), Math.sin(angle)];
+					s.position = 0;
+					s.previous = [
+						s.colour[0] + (1 - s.colour[0]) * s.fade,
+						s.colour[1] + (1 - s.colour[1]) * s.fade,
+						s.colour[2] + (1 - s.colour[2]) * s.fade
+					];
+					s.colour = pickWaveColor(palette, s.colour);
+					s.nextWaveDelay = 4 + Math.random() * 4;
+				}
+			} else {
+				const progress = (s.time - s.waveStart) / s.waveDuration;
+				s.position = Math.min(progress * 1.3, 1.3);
+				s.waveTime = Math.min(progress, 1);
+				s.fade = 0;
+				if (progress >= 1) {
+					s.waving = false;
+					s.lastWaveEnd = s.time;
+					s.waveTime = 1;
+					s.position = 1.3;
+				}
+			}
+			if (!s.waving) s.fade = Math.min((s.time - s.lastWaveEnd) / 3, 1);
+			trail.age();
+			trail.draw(touchContext);
+			const aspect = resize();
+			const scale = logoScale(fit, aspect, raster.width, raster.height, containFill);
+			const viewport = viewportAt(aspect);
+			const x = pointer.x * viewport.width * .5 / (raster.width * scale) + .5;
+			const y = pointer.y * viewport.height * .5 / (raster.height * scale) + .5;
+			if (x >= -.2 && x <= 1.2 && y >= -.2 && y <= 1.2) trail.add(Math.max(0, Math.min(1, x)), Math.max(0, Math.min(1, y)));
+			gl.clearColor(0, 0, 0, 0);
+			gl.clear(gl.COLOR_BUFFER_BIT);
+			gl.disable(gl.DEPTH_TEST);
+			gl.enable(gl.BLEND);
+			gl.blendEquation(gl.FUNC_ADD);
+			gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+			gl.useProgram(scene.program);
+			gl.bindVertexArray(scene.vao);
+			gl.uniformMatrix4fv(scene.uniform("projectionMatrix"), false, perspective(50, aspect, NEAR, FAR));
+			gl.uniformMatrix4fv(scene.uniform("modelViewMatrix"), false, modelView(scale));
+			gl.uniform1f(scene.uniform("uTime"), s.uTime);
+			gl.uniform1f(scene.uniform("uRandom"), randomSpread);
+			gl.uniform1f(scene.uniform("uDepth"), .8);
+			gl.uniform1f(scene.uniform("uSize"), particleSize);
+			gl.uniform2f(scene.uniform("uTextureSize"), raster.width, raster.height);
+			gl.uniform2f(scene.uniform("uWaveDirection"), s.direction[0], s.direction[1]);
+			gl.uniform1f(scene.uniform("uWavePosition"), s.position);
+			gl.uniform1f(scene.uniform("uWaveTime"), s.waveTime);
+			gl.uniform3f(scene.uniform("uWaveColor"), ...s.colour);
+			gl.uniform3f(scene.uniform("uPrevColor"), ...s.previous);
+			gl.uniform1f(scene.uniform("uColorFade"), s.fade);
+			gl.activeTexture(gl.TEXTURE0);
+			gl.bindTexture(gl.TEXTURE_2D, scene.image);
+			gl.uniform1i(scene.uniform("uTexture"), 0);
+			gl.activeTexture(gl.TEXTURE1);
+			gl.bindTexture(gl.TEXTURE_2D, scene.touch);
+			gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, touchCanvas);
+			gl.generateMipmap(gl.TEXTURE_2D);
+			gl.uniform1i(scene.uniform("uTouch"), 1);
+			gl.drawElementsInstanced(gl.TRIANGLES, 6, gl.UNSIGNED_SHORT, 0, scene.count);
+			gl.bindVertexArray(null);
+		};
+		let last = performance.now();
+		let accumulated = 0;
+		const tick = () => {
+			const now = performance.now();
+			const delta = (now - last) / 1e3;
+			last = now;
+			if (!visible || document.hidden) {
+				raf = 0;
+				return;
+			}
+			raf = requestAnimationFrame(tick);
+			accumulated += delta;
+			state.time += delta;
+			if (accumulated < 1 / 30) return;
+			frame(accumulated);
+			accumulated = 0;
+		};
+		const start = () => {
+			if (raf !== 0 || disposed || contextLost || scene === null || !visible || document.hidden) return;
+			last = performance.now();
+			raf = requestAnimationFrame(tick);
+		};
+		const observer = typeof IntersectionObserver === "undefined" ? null : new IntersectionObserver(([entry]) => {
+			visible = entry?.isIntersecting ?? true;
+			start();
+		});
+		observer?.observe(element);
+		const onVisibility = () => start();
+		document.addEventListener("visibilitychange", onVisibility);
+		const buildScene = () => {
+			if (disposed || contextLost || raster === null) return;
+			scene = build(gl, raster, sampleParticles(raster, skipRatio));
+			if (scene === null) {
+				setFailed(true);
+				return;
+			}
+			start();
+		};
+		const onLost = (event) => {
+			event.preventDefault();
+			contextLost = true;
+			if (raf !== 0) cancelAnimationFrame(raf);
+			raf = 0;
+			scene = null;
+			setLost(true);
+		};
+		const onRestored = () => {
+			contextLost = false;
+			setLost(false);
+			buildScene();
+		};
+		element.addEventListener("webglcontextlost", onLost);
+		element.addEventListener("webglcontextrestored", onRestored);
+		const image = new Image();
+		image.crossOrigin = "anonymous";
+		image.onload = () => {
+			(image.decode?.() ?? Promise.resolve()).catch(() => {}).then(() => {
+				if (disposed) return;
+				raster = rasterise(image);
+				buildScene();
+			});
+		};
+		image.onerror = () => {
+			if (!disposed) setFailed(true);
+		};
+		image.src = src;
+		return () => {
+			disposed = true;
+			if (raf !== 0) cancelAnimationFrame(raf);
+			observer?.disconnect();
+			document.removeEventListener("visibilitychange", onVisibility);
+			element.removeEventListener("pointermove", onPointer);
+			element.removeEventListener("webglcontextlost", onLost);
+			element.removeEventListener("webglcontextrestored", onRestored);
+			if (scene !== null && !contextLost) release(gl, scene);
+			if (!element.isConnected) gl.getExtension("WEBGL_lose_context")?.loseContext();
+		};
+	}, [
+		drawStill,
+		src,
+		fit,
+		containFill,
+		particleSize,
+		randomSpread,
+		skipRatio,
+		paletteKey
+	]);
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "particle-logo",
+		className: cn("relative h-full w-full", className),
+		style,
+		...props,
+		children: [drawStill ? null : /* @__PURE__ */ jsx("canvas", {
+			ref: canvas,
+			"aria-hidden": "true",
+			"data-slot": "particle-logo-canvas",
+			className: "block h-full w-full",
+			style: {
+				background: "transparent",
+				touchAction: "none"
+			}
+		}), drawStill || lost ? /* @__PURE__ */ jsx("img", {
+			"data-slot": "particle-logo-still",
+			src,
+			alt: "",
+			"aria-hidden": "true",
+			className: "absolute inset-0 m-auto object-contain",
+			style: {
+				height: fit === "logo" ? "26%" : `${containFill * 100}%`,
+				width: "auto"
+			}
+		}) : null]
+	});
+});
+//#endregion
+export { ParticleLogo };

package/dist/brand/particle-mark.d.ts

@@ -0,0 +1,29 @@
+import * as React from "react";
+//#region src/brand/particle-mark.d.ts
+interface ParticleMarkProps extends React.ComponentPropsWithoutRef<"canvas"> {
+  /** The word the dots draw, short: a name or a mark. */
+  word: string;
+  /** Which scatter. Defaults to `1`. */
+  seed?: number;
+}
+/**
+ * A word drawn as a field of dots that drift and settle — a studio site's mark
+ * (spec 2026-10-02 §3.4). The dots are the accent, read from the canvas's own
+ * computed style, so they follow the Look.
+ *
+ * **It costs nothing at rest.** It animates only while its element is displayed,
+ * on screen and in a visible tab, and while {@link useStill} is false (a still
+ * thumbnail, or a reader who prefers reduced motion). Otherwise it draws one
+ * still frame. That frame is redrawn whenever any theme axis changes anywhere above
+ * it, the system colour scheme flips, a face finishes loading, or it resizes, so a
+ * paused mark is never left in an old palette. Unmounting disconnects every
+ * observer and cancels every frame.
+ *
+ * Decorative: hidden from assistive technology.
+ *
+ * @example
+ * <ParticleMark word="CUE" className="h-40 w-full" />
+ */
+declare function ParticleMark({ word, seed, ...canvasProps }: ParticleMarkProps): React.JSX.Element;
+//#endregion
+export { ParticleMark, ParticleMarkProps };

package/dist/brand/particle-mark.js

@@ -0,0 +1,137 @@
+"use client";
+import { seeded } from "./_motif-seed.js";
+import { usePrefersReducedMotion } from "../instruments/_motion.js";
+import { useStill } from "../system/still.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/brand/particle-mark.tsx
+/** The six axes a motif's colours follow (spec 2026-10-02 §3.4). */
+const AXES = [
+	"data-theme",
+	"data-font",
+	"data-mode",
+	"data-style",
+	"data-paint",
+	"data-density"
+];
+/**
+* A word drawn as a field of dots that drift and settle — a studio site's mark
+* (spec 2026-10-02 §3.4). The dots are the accent, read from the canvas's own
+* computed style, so they follow the Look.
+*
+* **It costs nothing at rest.** It animates only while its element is displayed,
+* on screen and in a visible tab, and while {@link useStill} is false (a still
+* thumbnail, or a reader who prefers reduced motion). Otherwise it draws one
+* still frame. That frame is redrawn whenever any theme axis changes anywhere above
+* it, the system colour scheme flips, a face finishes loading, or it resizes, so a
+* paused mark is never left in an old palette. Unmounting disconnects every
+* observer and cancels every frame.
+*
+* Decorative: hidden from assistive technology.
+*
+* @example
+* <ParticleMark word="CUE" className="h-40 w-full" />
+*/
+function ParticleMark({ word, seed = 1, ...canvasProps }) {
+	const ref = React.useRef(null);
+	const held = useStill();
+	const reduced = usePrefersReducedMotion();
+	const still = held || reduced;
+	React.useEffect(() => {
+		const canvas = ref.current;
+		if (canvas === null) return;
+		const ctx = canvas.getContext("2d");
+		if (ctx === null) return;
+		let frame = 0;
+		let visible = false;
+		let points = [];
+		const layout = () => {
+			const rect = canvas.getBoundingClientRect();
+			const scale = window.devicePixelRatio || 1;
+			canvas.width = Math.max(1, Math.round(rect.width * scale));
+			canvas.height = Math.max(1, Math.round(rect.height * scale));
+			const off = document.createElement("canvas");
+			off.width = canvas.width;
+			off.height = canvas.height;
+			const o = off.getContext("2d");
+			if (o === null) return;
+			o.fillStyle = getComputedStyle(canvas).getPropertyValue("--cue-accent").trim() || "currentColor";
+			const family = getComputedStyle(canvas).fontFamily;
+			o.font = `700 100px ${family}`;
+			const advance = o.measureText(word).width / 100;
+			const size = Math.min(canvas.height * .62, advance > 0 ? canvas.width * .9 / advance : canvas.height * .62);
+			o.font = `700 ${Math.round(size)}px ${family}`;
+			o.textAlign = "center";
+			o.textBaseline = "middle";
+			o.fillText(word, canvas.width / 2, canvas.height / 2);
+			const data = o.getImageData(0, 0, off.width, off.height).data;
+			const rand = seeded(seed);
+			const step = Math.max(3, Math.round(4 * scale));
+			points = [];
+			for (let y = 0; y < off.height; y += step) for (let x = 0; x < off.width; x += step) if (data[(y * off.width + x) * 4 + 3] > 128) points.push({
+				x,
+				y,
+				dx: (rand() - .5) * step,
+				dy: (rand() - .5) * step
+			});
+		};
+		const draw = (t) => {
+			ctx.clearRect(0, 0, canvas.width, canvas.height);
+			ctx.fillStyle = getComputedStyle(canvas).getPropertyValue("--cue-accent").trim() || "currentColor";
+			const size = Math.max(1, (window.devicePixelRatio || 1) * 1.4);
+			const k = still ? 0 : Math.sin(t / 900);
+			for (const p of points) ctx.fillRect(p.x + p.dx * k, p.y + p.dy * k, size, size);
+		};
+		const rendered = () => typeof canvas.checkVisibility === "function" ? canvas.checkVisibility() : canvas.getClientRects().length > 0;
+		const shown = () => rendered() && visible && document.visibilityState === "visible";
+		const tick = (t) => {
+			draw(t);
+			frame = shown() && !still ? requestAnimationFrame(tick) : 0;
+		};
+		const refresh = () => {
+			cancelAnimationFrame(frame);
+			frame = 0;
+			layout();
+			draw(0);
+			if (shown() && !still) frame = requestAnimationFrame(tick);
+		};
+		const intersection = new IntersectionObserver(([entry]) => {
+			visible = entry?.isIntersecting ?? false;
+			refresh();
+		});
+		intersection.observe(canvas);
+		const resize = new ResizeObserver(refresh);
+		resize.observe(canvas);
+		const axes = new MutationObserver(refresh);
+		axes.observe(document.documentElement, {
+			subtree: true,
+			attributes: true,
+			attributeFilter: AXES
+		});
+		const scheme = window.matchMedia("(prefers-color-scheme: dark)");
+		scheme.addEventListener("change", refresh);
+		document.addEventListener("visibilitychange", refresh);
+		document.fonts?.addEventListener?.("loadingdone", refresh);
+		refresh();
+		return () => {
+			cancelAnimationFrame(frame);
+			intersection.disconnect();
+			resize.disconnect();
+			axes.disconnect();
+			scheme.removeEventListener("change", refresh);
+			document.removeEventListener("visibilitychange", refresh);
+			document.fonts?.removeEventListener?.("loadingdone", refresh);
+		};
+	}, [
+		word,
+		seed,
+		still
+	]);
+	return /* @__PURE__ */ jsx("canvas", {
+		ref,
+		"aria-hidden": "true",
+		...canvasProps
+	});
+}
+//#endregion
+export { ParticleMark };

package/dist/brand/ribbon.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+//#region src/brand/ribbon.d.ts
+interface RibbonProps extends React.SVGProps<SVGSVGElement> {
+  /** Which ribbon: the same seed draws the same bands. Defaults to `1`. */
+  seed?: number;
+}
+/**
+ * A flowing ribbon of layered bands in the theme's own inks — the payments-page
+ * motif (spec 2026-10-02 §3.4). Five bezier bands cross the frame on a diagonal,
+ * each a gradient from the accent to the foreground's mix, so it reads in every
+ * theme and both modes. Decorative: hidden from assistive technology.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <Ribbon seed={3} className="h-64 w-full" />
+ */
+declare function Ribbon({ seed, ...svgProps }: RibbonProps): React.JSX.Element;
+//#endregion
+export { Ribbon, RibbonProps };

package/dist/brand/ribbon.js

@@ -0,0 +1,54 @@
+import { r2, seeded } from "./_motif-seed.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/brand/ribbon.tsx
+/**
+* A flowing ribbon of layered bands in the theme's own inks — the payments-page
+* motif (spec 2026-10-02 §3.4). Five bezier bands cross the frame on a diagonal,
+* each a gradient from the accent to the foreground's mix, so it reads in every
+* theme and both modes. Decorative: hidden from assistive technology.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <Ribbon seed={3} className="h-64 w-full" />
+*/
+function Ribbon({ seed = 1, ...svgProps }) {
+	const id = React.useId().replace(/:/gu, "");
+	const rand = seeded(seed);
+	const bands = Array.from({ length: 5 }, (_, i) => {
+		const y0 = r2(40 + i * 14 + rand() * 10);
+		const c1 = r2(rand() * 60 - 10);
+		const c2 = r2(70 + rand() * 40);
+		const y1 = r2(i * 8 + rand() * 12);
+		const w = r2(10 + rand() * 8);
+		return `M0 ${y0} C 30 ${c1} 60 ${c2} 100 ${y1} L 100 ${r2(y1 + w)} C 60 ${r2(c2 + w)} 30 ${r2(c1 + w)} 0 ${r2(y0 + w)} Z`;
+	});
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 100 100",
+		preserveAspectRatio: "none",
+		"aria-hidden": "true",
+		focusable: "false",
+		...svgProps,
+		children: [/* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsxs("linearGradient", {
+			id: `${id}-g`,
+			x1: "0",
+			y1: "0",
+			x2: "1",
+			y2: "1",
+			children: [/* @__PURE__ */ jsx("stop", {
+				offset: "0%",
+				stopColor: "var(--cue-accent)"
+			}), /* @__PURE__ */ jsx("stop", {
+				offset: "100%",
+				stopColor: "color-mix(in oklch, var(--cue-accent) 40%, var(--cue-fg))"
+			})]
+		}) }), bands.map((d, i) => /* @__PURE__ */ jsx("path", {
+			d,
+			fill: `url(#${id}-g)`,
+			opacity: r2(.35 + i * .12)
+		}, i))]
+	});
+}
+//#endregion
+export { Ribbon };