@juspay/svelte-ui-components 4.32.1 → 4.33.0

package/dist/ThinkingOrb/ThinkingOrb.svelte

@@ -0,0 +1,344 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { attract, GRAVITY_DEFAULTS, type GravityPointer } from './orb/gravity';
+  import { paintFrame } from './orb/paint';
+  import { MODES } from './orb/modes';
+  import { prefersReducedMotion } from '../utils';
+  import { parseCssColor } from '../VoiceOrb/orbMath';
+  import type { Rgb } from '../types';
+  import type {
+    GravityOptions,
+    OrbState,
+    ThinkingOrbProperties,
+    ThinkingOrbSize
+  } from './properties';
+
+  let {
+    state: orbState = 'working',
+    size = 64,
+    speed = 1,
+    paused = false,
+    color,
+    dots = 1,
+    dotSize = 1,
+    gravity = false,
+    ariaLabel,
+    classes,
+    testId,
+    onfirstframe
+  }: ThinkingOrbProperties = $props();
+
+  const SIZES: readonly ThinkingOrbSize[] = [64, 32, 20];
+  const FALLBACK_TINT: Rgb = { r: 128, g: 128, b: 128 };
+  /** A fixed, representative instant a reduced-motion orb holds — any single
+   * frame works, since every mode is required to be non-blank at every `t`. */
+  const REDUCED_MOTION_INSTANT = 2.4;
+  /** The backing store never scales past this multiple of the CSS size, so a
+   * very-high-density display can't push the canvas past a sane pixel budget. */
+  const MAX_BACKING_SCALE = 2;
+
+  // <sui-thinking-orb> passes `state`/`size` straight from string/number
+  // attributes, so a value no mode or size knows about can reach here. Fall
+  // back rather than let a missing MODES entry leave nothing drawn.
+  const safeState: OrbState = $derived(Object.hasOwn(MODES, orbState) ? orbState : 'working');
+  const safeSize: ThinkingOrbSize = $derived(SIZES.includes(size) ? size : 64);
+  const density = $derived(Math.max(0.1, dots));
+  const dotScale = $derived(Math.max(0.1, dotSize));
+
+  /*
+   * Gravity is motion: under reduced motion it is switched off outright
+   * rather than merely un-animated, so a still frame never carries a pointer
+   * pull a user asked motion to not see.
+   */
+  const gravityOptions = $derived.by((): GravityOptions | null => {
+    if (!gravity || reducedMotion) {
+      return null;
+    }
+    return gravity === true ? GRAVITY_DEFAULTS : gravity;
+  });
+
+  let canvas: HTMLCanvasElement | null = $state(null);
+  /*
+   * `reducedMotion`/`onScreen`/`tabVisible` feed `shouldRun` below (a
+   * `$derived`), so they must be real `$state` for it to react when they
+   * change. `dark` is `$state` for the same reason `draw` below reads it
+   * synchronously inside the main `$effect` -- writing it must retrigger
+   * that effect, otherwise a theme flip while the loop is stopped (paused,
+   * or reduced motion, which paints exactly once) would leave the ink ramp
+   * on the wrong theme for as long as the orb stays still. `pointer` is a
+   * plain `let`, not `$state`: a still orb repaints explicitly on pointer
+   * events (see `repaintIfStill`), and a running orb's loop already reads
+   * the latest pointer every tick, so retriggering the whole effect on every
+   * pointer move would only tear down and restart the loop for nothing.
+   */
+  let reducedMotion = $state(prefersReducedMotion());
+  let onScreen = $state(true);
+  let tabVisible = $state(true);
+  let dark = $state(false);
+  let announcedFirstFrame = false;
+  let resolvedColorInput = '';
+  let resolvedTint: Rgb = FALLBACK_TINT;
+  let pointer: GravityPointer = null;
+  let animationHandle = 0;
+  /** The orb's own clock: speed-scaled seconds, starting at 0 on mount and
+   * advancing only while the loop actually runs (see the main `$effect`). A
+   * still orb simply stops touching it, so it holds the exact instant it
+   * stopped at with no extra bookkeeping. */
+  let clock = 0;
+
+  const shouldRun = $derived(!paused && !reducedMotion && onScreen && tabVisible);
+
+  /** What a still orb paints: the fixed instant under reduced motion, else
+   * whatever `clock` last reached. */
+  const heldInstant = (): number => (reducedMotion ? REDUCED_MOTION_INSTANT : clock);
+
+  /*
+   * Assigning an unparseable colour to `fillStyle` is a spec no-op, so the
+   * candidate is tried against two different backgrounds and the results
+   * compared -- agreement means the browser accepted and normalised it (see
+   * VoiceOrb.svelte, which uses the same trick).
+   */
+  const normalizeColor = (context: CanvasRenderingContext2D, value: string): string | null => {
+    if (value.length === 0) {
+      return null;
+    }
+    const previous = context.fillStyle;
+    context.fillStyle = '#000000';
+    context.fillStyle = value;
+    const onBlack = context.fillStyle;
+    context.fillStyle = '#ffffff';
+    context.fillStyle = value;
+    const onWhite = context.fillStyle;
+    context.fillStyle = previous;
+    return typeof onBlack === 'string' && onBlack === onWhite ? onBlack : null;
+  };
+
+  const readColorInput = (
+    target: HTMLCanvasElement
+  ): { declared: string; inherited: string; key: string } => {
+    const styles = getComputedStyle(target);
+    const declared = styles.getPropertyValue('--sui-thinking-orb-color').trim();
+    const inherited = styles.color.trim();
+    return { declared, inherited, key: `${declared}|${inherited}` };
+  };
+
+  /** `color` prop wins outright; otherwise re-read via getComputedStyle, cached by the raw input string. */
+  const resolveTint = (context: CanvasRenderingContext2D): Rgb => {
+    if (color) {
+      return color;
+    }
+    if (canvas === null) {
+      return resolvedTint;
+    }
+    const { declared, inherited, key } = readColorInput(canvas);
+    if (key === resolvedColorInput) {
+      return resolvedTint;
+    }
+    resolvedColorInput = key;
+    const normalized = normalizeColor(context, declared) ?? normalizeColor(context, inherited);
+    resolvedTint = (normalized === null ? null : parseCssColor(normalized)) ?? FALLBACK_TINT;
+    return resolvedTint;
+  };
+
+  /** A still orb has no running loop to pick up a moved pointer on its own,
+   * so gravity repaints it directly; a running orb's loop already paints the
+   * latest pointer every tick and needs no help here. */
+  const repaintIfStill = (): void => {
+    if (shouldRun || gravityOptions === null) {
+      return;
+    }
+    draw(heldInstant());
+  };
+
+  const trackPointer = (event: PointerEvent): void => {
+    if (canvas === null || !gravity) {
+      return;
+    }
+    const rect = canvas.getBoundingClientRect();
+    pointer = { x: event.clientX - rect.left, y: event.clientY - rect.top };
+    repaintIfStill();
+  };
+
+  const releasePointer = (): void => {
+    pointer = null;
+    repaintIfStill();
+  };
+
+  /** SSR renders with no `window`; the backing store is left at 1x until the
+   * component actually mounts in a browser and can ask it for a real ratio. */
+  const resolveBackingScale = (): number => {
+    if (typeof window === 'undefined') {
+      return 1;
+    }
+    return Math.min(MAX_BACKING_SCALE, window.devicePixelRatio ?? 1);
+  };
+
+  /** Paints one instant. `instant` is already speed-scaled seconds -- either
+   * the orb's own running `clock` or the fixed reduced-motion instant. Safe
+   * to call whether or not the loop is running. */
+  const draw = (instant: number): void => {
+    if (canvas === null) {
+      return;
+    }
+    const context = canvas.getContext('2d');
+    if (context === null) {
+      return;
+    }
+
+    const dpr = resolveBackingScale();
+    const backingPx = Math.round(safeSize * dpr);
+    if (canvas.width !== backingPx || canvas.height !== backingPx) {
+      canvas.width = backingPx;
+      canvas.height = backingPx;
+    }
+    context.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+    const frame = MODES[safeState](instant, { size: safeSize, density, dotScale });
+    const gOpts = gravityOptions;
+    const painted = gOpts === null ? frame : attract(frame, pointer, gOpts);
+    paintFrame(context, painted, { dark, tint: resolveTint(context) });
+
+    if (!announcedFirstFrame) {
+      announcedFirstFrame = true;
+      onfirstframe?.();
+    }
+  };
+
+  /*
+   * Re-runs whenever `shouldRun` or anything the leading `draw` reads changes
+   * (`safeState`, `safeSize`, `density`, `dotScale`, `gravityOptions`, `dark`,
+   * `color`, `reducedMotion`, ...) -- Svelte tracks every reactive read inside
+   * this body, including transitively through that synchronous `draw` call,
+   * so a prop change tears down the previous rAF (the cleanup below) and
+   * repaints from scratch with no dependency list to maintain by hand.
+   *
+   * `clock` itself is never read synchronously here, only inside the `loop`
+   * closure below, which runs later from `requestAnimationFrame` -- so
+   * advancing it never retriggers this effect. That's what lets `speed`
+   * change the clock's rate starting next tick with no jump and no loop
+   * restart: `loop` reads the live `speed` prop itself, every tick.
+   */
+  // eslint-disable-next-line no-restricted-syntax
+  $effect(() => {
+    // A still orb (paused, reduced motion or off screen) never touches
+    // `clock`, so it simply holds whatever instant it last reached -- no
+    // separate "was it frozen" bookkeeping needed. At least one frame is
+    // always painted, so the canvas is never blank.
+    draw(heldInstant());
+    if (!shouldRun) {
+      return;
+    }
+    // Reset on every (re)start of the loop, including a resume from
+    // stillness: the first tick after a (re)start must not count the time
+    // that passed before it, so it advances `clock` by zero and every tick
+    // after that measures real elapsed time again.
+    let previousFrameTime: number | null = null;
+    const loop = (frameTime: number): void => {
+      const deltaSeconds = previousFrameTime === null ? 0 : (frameTime - previousFrameTime) / 1000;
+      previousFrameTime = frameTime;
+      clock += deltaSeconds * speed;
+      draw(clock);
+      animationHandle = requestAnimationFrame(loop);
+    };
+    animationHandle = requestAnimationFrame(loop);
+    return () => cancelAnimationFrame(animationHandle);
+  });
+
+  onMount(() => {
+    if (canvas === null) {
+      return;
+    }
+
+    // Every optional platform API below follows the same shape: build it
+    // when the browser exposes the constructor/method it needs, otherwise
+    // leave the binding `null` so the optional-chaining calls below no-op.
+    let intersectionObserver: IntersectionObserver | null = null;
+    if (typeof IntersectionObserver !== 'undefined') {
+      intersectionObserver = new IntersectionObserver(([entry]) => {
+        onScreen = entry.isIntersecting;
+      });
+      intersectionObserver.observe(canvas);
+    }
+
+    const onVisibilityChange = (): void => {
+      tabVisible = document.visibilityState !== 'hidden';
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+
+    /*
+     * This repo's `ThemeSwitcher` stamps `data-theme="dark"` on
+     * `document.documentElement` -- one attribute on one element -- so a
+     * `MutationObserver` there alone catches every theme change. It exists
+     * only to keep `paintFrame`'s `dark` argument current: the tint colour
+     * itself comes from CSS, resolved in `resolveTint` above.
+     */
+    const readTheme = (): void => {
+      dark = document.documentElement.getAttribute('data-theme') === 'dark';
+    };
+    readTheme();
+    let themeObserver: MutationObserver | null = null;
+    if (typeof MutationObserver !== 'undefined') {
+      themeObserver = new MutationObserver(readTheme);
+      themeObserver.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['data-theme']
+      });
+    }
+
+    const onMotionChange = (event: MediaQueryListEvent): void => {
+      reducedMotion = event.matches;
+    };
+    let motionQuery: MediaQueryList | null = null;
+    if (typeof window.matchMedia === 'function') {
+      motionQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+      motionQuery.addEventListener('change', onMotionChange);
+    }
+
+    /*
+     * A still orb only repaints on its own when `dark` flips. A host that
+     * transitions its `color` (this repo's own layout fades `body` across a
+     * theme switch) leaves a just-frozen frame at the outgoing colour, with
+     * nothing else to redraw it. Re-read once the transition lands and
+     * repaint the same frozen instant if the resolved colour actually moved.
+     * A running orb re-reads every frame already and needs none of this.
+     */
+    const onColorTransitionEnd = (event: TransitionEvent): void => {
+      if (shouldRun || color || canvas === null) {
+        return;
+      }
+      if (event.propertyName !== 'color' && event.propertyName !== '--sui-thinking-orb-color') {
+        return;
+      }
+      if (readColorInput(canvas).key !== resolvedColorInput) {
+        draw(heldInstant());
+      }
+    };
+    document.addEventListener('transitionend', onColorTransitionEnd);
+
+    return () => {
+      intersectionObserver?.disconnect();
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+      document.removeEventListener('transitionend', onColorTransitionEnd);
+      themeObserver?.disconnect();
+      motionQuery?.removeEventListener('change', onMotionChange);
+    };
+  });
+</script>
+
+<!-- The canvas is a picture with a label, not a control: the pointer handlers
+     only feed the optional gravity effect and never act, so role="img" is
+     accurate. -->
+<!-- svelte-ignore a11y_no_interactive_element_to_noninteractive_role -->
+<canvas
+  bind:this={canvas}
+  role="img"
+  aria-label={ariaLabel ?? `${safeState.charAt(0).toUpperCase()}${safeState.slice(1)}…`}
+  class={classes}
+  data-pw={typeof testId === 'string' ? testId : null}
+  style:width={`${safeSize}px`}
+  style:height={`${safeSize}px`}
+  style:display="block"
+  onpointermove={trackPointer}
+  onpointerleave={releasePointer}
+  onpointercancel={releasePointer}
+></canvas>

package/dist/ThinkingOrb/ThinkingOrb.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { ThinkingOrbProperties } from './properties';
+declare const ThinkingOrb: import("svelte").Component<ThinkingOrbProperties, {}, "">;
+type ThinkingOrb = ReturnType<typeof ThinkingOrb>;
+export default ThinkingOrb;

package/dist/ThinkingOrb/orb/gravity.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pulls a frame's dots toward a pointer position, so an orb can feel alive
+ * under the cursor without any mode ever knowing pointers exist -- the same
+ * separation `paintFrame` keeps between a mode and the canvas.
+ */
+import type { Frame } from './types';
+/**
+ * Where gravity pulls toward, in the same coordinate space as a `Dot`.
+ * `null` means nothing is hovering, and gravity does nothing.
+ */
+export type GravityPointer = {
+    x: number;
+    y: number;
+} | null;
+/** How far gravity reaches (`radius`, px) and how hard it pulls at its centre (`strength`, px). */
+export type GravityOptions = {
+    radius: number;
+    strength: number;
+};
+/** A reach and pull tuned to read as a subtle few px of drift, never a snap to the cursor. */
+export declare const GRAVITY_DEFAULTS: GravityOptions;
+/**
+ * Returns a NEW `Frame` with every dot and stroke endpoint inside
+ * `options.radius` of `pointer` pulled toward it, the pull smoothly fading
+ * to nothing at the radius edge; marks outside are returned untouched. Each
+ * stroke endpoint moves by the same amount a dot at that point would, so a
+ * line stays attached to the nodes it joins. A `null` pointer is a no-op:
+ * `frame` is returned as-is. Never mutates `frame` or anything inside it.
+ */
+export declare const attract: (frame: Frame, pointer: GravityPointer, options: GravityOptions) => Frame;

package/dist/ThinkingOrb/orb/gravity.js

@@ -0,0 +1,64 @@
+/**
+ * Pulls a frame's dots toward a pointer position, so an orb can feel alive
+ * under the cursor without any mode ever knowing pointers exist -- the same
+ * separation `paintFrame` keeps between a mode and the canvas.
+ */
+import { easeOutCubic } from './space';
+/** A reach and pull tuned to read as a subtle few px of drift, never a snap to the cursor. */
+export const GRAVITY_DEFAULTS = {
+    radius: 32,
+    strength: 6
+};
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+/**
+ * Where one point ends up after `pointer` pulls on it. The pull is capped at
+ * the point's own distance from `pointer` -- without that cap, a point
+ * already close to the pointer (distance smaller than `strength`) would
+ * overshoot past it. Shared by dots and stroke endpoints so a line stays
+ * attached to the nodes it joins: each endpoint moves exactly as far as a
+ * dot sitting at that same spot would.
+ */
+const attractPoint = (point, pointer, options) => {
+    const dx = pointer.x - point.x;
+    const dy = pointer.y - point.y;
+    const distance = Math.hypot(dx, dy);
+    if (distance === 0 || distance >= options.radius) {
+        return point;
+    }
+    const proximity = clamp01(1 - distance / options.radius);
+    const pull = Math.min(easeOutCubic(proximity) * options.strength, distance);
+    const scale = pull / distance;
+    return { x: point.x + dx * scale, y: point.y + dy * scale };
+};
+const attractDot = (dot, pointer, options) => {
+    const moved = attractPoint(dot, pointer, options);
+    return moved.x === dot.x && moved.y === dot.y ? dot : { ...dot, x: moved.x, y: moved.y };
+};
+const attractStroke = (stroke, pointer, options) => {
+    const start = attractPoint({ x: stroke.x1, y: stroke.y1 }, pointer, options);
+    const end = attractPoint({ x: stroke.x2, y: stroke.y2 }, pointer, options);
+    if (start.x === stroke.x1 &&
+        start.y === stroke.y1 &&
+        end.x === stroke.x2 &&
+        end.y === stroke.y2) {
+        return stroke;
+    }
+    return { ...stroke, x1: start.x, y1: start.y, x2: end.x, y2: end.y };
+};
+/**
+ * Returns a NEW `Frame` with every dot and stroke endpoint inside
+ * `options.radius` of `pointer` pulled toward it, the pull smoothly fading
+ * to nothing at the radius edge; marks outside are returned untouched. Each
+ * stroke endpoint moves by the same amount a dot at that point would, so a
+ * line stays attached to the nodes it joins. A `null` pointer is a no-op:
+ * `frame` is returned as-is. Never mutates `frame` or anything inside it.
+ */
+export const attract = (frame, pointer, options) => {
+    if (pointer === null) {
+        return frame;
+    }
+    return {
+        dots: frame.dots.map((dot) => attractDot(dot, pointer, options)),
+        strokes: frame.strokes.map((stroke) => attractStroke(stroke, pointer, options))
+    };
+};

package/dist/ThinkingOrb/orb/modes/form.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The "form" modes: composing, breathing and shaping. Each one reads as a
+ * single evolving surface or ring rather than a swarm of independent points,
+ * so the motion stays legible down at 20px instead of dissolving into noise
+ * the way a large loose point cloud would.
+ *
+ * All three share one placement idiom: build each dot in its own object
+ * space (a band or ring parametrised by its index, deformed however that
+ * mode's intent calls for), spin the whole thing with `rotateY` for a sense
+ * of turning, tilt it with `rotateX` so it reads in 3D, then `project`. That
+ * split keeps "the shape's own motion" and "the camera's fixed angle on it"
+ * from tangling together in the per-dot math.
+ */
+import type { ModeFn } from '../types';
+/**
+ * A ribbon of dots looped once around the sphere on its own tilted great
+ * circle -- distinct from the spin axis -- rippling along its length like a
+ * travelling wave through cloth while the whole ribbon turns.
+ */
+export declare const composing: ModeFn;
+/**
+ * A single ring that swells and relaxes on a slow sine, with a faint,
+ * higher-harmonic wobble layered on top so its outline never reads as a
+ * perfectly static circle even at rest.
+ */
+export declare const breathing: ModeFn;
+/**
+ * A ring that morphs circle to triangle to square and back over a fixed
+ * cycle, each leg eased so the shape comes to rest at every corner instead
+ * of snapping into it -- which also makes the wrap from the last leg back to
+ * the first exactly continuous.
+ */
+export declare const shaping: ModeFn;

package/dist/ThinkingOrb/orb/modes/form.js

@@ -0,0 +1,201 @@
+/**
+ * The "form" modes: composing, breathing and shaping. Each one reads as a
+ * single evolving surface or ring rather than a swarm of independent points,
+ * so the motion stays legible down at 20px instead of dissolving into noise
+ * the way a large loose point cloud would.
+ *
+ * All three share one placement idiom: build each dot in its own object
+ * space (a band or ring parametrised by its index, deformed however that
+ * mode's intent calls for), spin the whole thing with `rotateY` for a sense
+ * of turning, tilt it with `rotateX` so it reads in 3D, then `project`. That
+ * split keeps "the shape's own motion" and "the camera's fixed angle on it"
+ * from tangling together in the per-dot math.
+ */
+import { easeInOutCubic, hashUnit, modeSizing, project, rotateX, rotateY, rotateZ } from '../space';
+const TWO_PI = Math.PI * 2;
+/** The shared "reads as a form inside a square" contract: radius as a share of `size`. */
+const FORM_RADIUS_RATIO = 0.4;
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+/** Nearer dots read as more saturated tint; `paintFrame` turns low ink into more of `tint`. */
+const depthToInk = (depth) => clamp01(1 - depth);
+/** Farther dots stay at partial opacity rather than fading to nothing, so no instant reads blank. */
+const depthToAlpha = (depth) => clamp01(0.5 + depth * 0.5);
+/** Nearer dots draw a touch larger, reinforcing the depth `paintFrame`'s draw order already implies. */
+const depthToRadiusFactor = (depth) => 0.7 + depth * 0.3;
+/** Builds one `Dot` from a projected point; `jitter` gives per-dot size variety from `hashUnit`. */
+const dotFrom = (projected, baseRadius, sizing, jitter) => ({
+    x: projected.x,
+    y: projected.y,
+    depth: projected.depth,
+    radius: sizing.radius(baseRadius) * depthToRadiusFactor(projected.depth) * jitter,
+    ink: depthToInk(projected.depth),
+    alpha: depthToAlpha(projected.depth)
+});
+/** Turns an object-space point into a placed, projected `Dot` via the shared spin/tilt/project steps. */
+const place = (point, spinAngle, tiltAngle, originPx, worldRadius, baseRadius, sizing, jitter) => {
+    const spun = rotateY(point, spinAngle);
+    const tilted = rotateX(spun, tiltAngle);
+    const projected = project(tilted, originPx, worldRadius);
+    return dotFrom(projected, baseRadius, sizing, jitter);
+};
+const EMPTY_STROKES = [];
+// --- composing ---------------------------------------------------------
+const RIBBON_BASE_COUNT = 260;
+const RIBBON_BASE_DOT_RADIUS = 2.2;
+const RIBBON_THREADS = { 64: 7, 32: 5, 20: 4 };
+const RIBBON_HALF_WIDTH = 0.4;
+/** The ribbon's own great circle sits tilted off the spin axis by this much,
+ * so spinning genuinely sweeps its width through the frame -- a band that
+ * happened to lie flat on the equator would look identical at every spin
+ * angle, since an equatorial ring is rotationally symmetric about that axis. */
+const RIBBON_AXIS_TILT = 0.68;
+const RIBBON_RIPPLE_WAVES = 3;
+const RIBBON_RIPPLE_SPEED = 1.15;
+const RIBBON_RIPPLE_AMPLITUDE = 0.5;
+const RIBBON_THREAD_JITTER = 0.1;
+const RIBBON_SPIN_SPEED = 0.48;
+const RIBBON_CAMERA_TILT = 0.45;
+/** Edge threads only dim toward the background; nothing here shrinks a dot's
+ * radius, so the ribbon keeps a full-width row of legible marks even where a
+ * combined ink/alpha/radius fade would collapse an edge row to a speck. */
+const RIBBON_EDGE_ALPHA_FLOOR = 0.5;
+const RIBBON_EDGE_INK_LIFT = 0.22;
+/**
+ * A ribbon of dots looped once around the sphere on its own tilted great
+ * circle -- distinct from the spin axis -- rippling along its length like a
+ * travelling wave through cloth while the whole ribbon turns.
+ */
+export const composing = (t, ctx) => {
+    const sizing = modeSizing(ctx.size, ctx.density, ctx.dotScale);
+    const worldRadius = ctx.size * FORM_RADIUS_RATIO;
+    const originPx = ctx.size / 2;
+    const threads = RIBBON_THREADS[ctx.size];
+    const perThread = Math.max(1, Math.ceil(sizing.count(RIBBON_BASE_COUNT) / threads));
+    const total = threads * perThread;
+    const dots = [];
+    for (let index = 0; index < total; index += 1) {
+        const thread = index % threads;
+        const step = Math.floor(index / threads);
+        // w ranges -1 (one edge thread) .. 0 (centre) .. 1 (other edge thread).
+        const w = threads > 1 ? (thread / (threads - 1)) * 2 - 1 : 0;
+        const u = (step / perThread) * TWO_PI;
+        const ripple = Math.sin(u * RIBBON_RIPPLE_WAVES + t * RIBBON_RIPPLE_SPEED) * RIBBON_RIPPLE_AMPLITUDE;
+        // A standard spherical parametrisation keeps every point exactly on a
+        // sphere of `worldRadius` regardless of `phi`, so the ribbon stays safely
+        // inside the canvas no matter how far the ripple bends it.
+        const phi = w * RIBBON_HALF_WIDTH + ripple;
+        const onSphere = {
+            x: Math.cos(phi) * Math.cos(u) * worldRadius,
+            y: Math.sin(phi) * worldRadius,
+            z: Math.cos(phi) * Math.sin(u) * worldRadius
+        };
+        const onAxis = rotateZ(onSphere, RIBBON_AXIS_TILT);
+        const jitter = 1 - RIBBON_THREAD_JITTER / 2 + hashUnit(index * 7 + 1) * RIBBON_THREAD_JITTER;
+        const placed = place(onAxis, t * RIBBON_SPIN_SPEED, RIBBON_CAMERA_TILT, originPx, worldRadius, RIBBON_BASE_DOT_RADIUS, sizing, jitter);
+        const edgeFeather = Math.abs(w);
+        dots.push({
+            ...placed,
+            ink: clamp01(placed.ink + edgeFeather * RIBBON_EDGE_INK_LIFT),
+            alpha: clamp01(placed.alpha * (1 - edgeFeather * (1 - RIBBON_EDGE_ALPHA_FLOOR)))
+        });
+    }
+    return { dots, strokes: EMPTY_STROKES };
+};
+// --- breathing -----------------------------------------------------------
+const BREATHING_BASE_COUNT = 210;
+const BREATHING_BASE_DOT_RADIUS = 1.7;
+/** Sits below composing/shaping's ~0.4: at the peak of its breath this ring
+ * already swells by its amplitude plus its shape wobble below, so a resting
+ * radius this much smaller still lands at about the same on-screen extent as
+ * its siblings' fixed radius, without the peak pushing past the canvas. */
+const BREATHING_WORLD_RADIUS_RATIO = 0.34;
+const BREATHING_AMPLITUDE = 0.09;
+const BREATHING_SPEED = 0.55;
+const BREATHING_SHAPE_HARMONIC = 5;
+const BREATHING_SHAPE_SPEED = 0.22;
+const BREATHING_SHAPE_AMPLITUDE = 0.035;
+const BREATHING_SPIN_SPEED = 0.12;
+const BREATHING_TILT = 0.62;
+/**
+ * A single ring that swells and relaxes on a slow sine, with a faint,
+ * higher-harmonic wobble layered on top so its outline never reads as a
+ * perfectly static circle even at rest.
+ */
+export const breathing = (t, ctx) => {
+    const sizing = modeSizing(ctx.size, ctx.density, ctx.dotScale);
+    const worldRadius = ctx.size * BREATHING_WORLD_RADIUS_RATIO;
+    const originPx = ctx.size / 2;
+    const count = sizing.count(BREATHING_BASE_COUNT);
+    const breathe = Math.sin(t * BREATHING_SPEED);
+    const dots = [];
+    for (let index = 0; index < count; index += 1) {
+        const angle = (index / count) * TWO_PI;
+        const wobble = Math.sin(angle * BREATHING_SHAPE_HARMONIC + t * BREATHING_SHAPE_SPEED) *
+            BREATHING_SHAPE_AMPLITUDE;
+        const radiusFactor = 1 + breathe * BREATHING_AMPLITUDE + wobble;
+        const point = {
+            x: Math.cos(angle) * radiusFactor * worldRadius,
+            y: 0,
+            z: Math.sin(angle) * radiusFactor * worldRadius
+        };
+        const jitter = 0.88 + hashUnit(index * 11 + 5) * 0.24;
+        dots.push(place(point, t * BREATHING_SPIN_SPEED, BREATHING_TILT, originPx, worldRadius, BREATHING_BASE_DOT_RADIUS, sizing, jitter));
+    }
+    return { dots, strokes: EMPTY_STROKES };
+};
+// --- shaping ---------------------------------------------------------------
+const SHAPING_BASE_COUNT = 210;
+const SHAPING_BASE_DOT_RADIUS = 1.7;
+const SHAPING_CYCLE_SECONDS = 12;
+// One full turn per morph cycle, so the shape and its orientation both land
+// back where they started at the same instant -- a true seamless loop.
+const SHAPING_SPIN_SPEED = (2 * Math.PI) / SHAPING_CYCLE_SECONDS;
+const SHAPING_TILT = 0.6;
+/** The radial distance of a regular `sides`-gon's straight edge at `angle`, circumradius 1. */
+const polygonRadius = (angle, sides) => {
+    const segment = TWO_PI / sides;
+    const half = segment / 2;
+    const wrapped = ((angle % segment) + segment) % segment;
+    return Math.cos(half) / Math.cos(wrapped - half);
+};
+const lerp = (from, to, amount) => from + (to - from) * amount;
+/**
+ * A ring that morphs circle to triangle to square and back over a fixed
+ * cycle, each leg eased so the shape comes to rest at every corner instead
+ * of snapping into it -- which also makes the wrap from the last leg back to
+ * the first exactly continuous.
+ */
+export const shaping = (t, ctx) => {
+    const sizing = modeSizing(ctx.size, ctx.density, ctx.dotScale);
+    const worldRadius = ctx.size * FORM_RADIUS_RATIO;
+    const originPx = ctx.size / 2;
+    const count = sizing.count(SHAPING_BASE_COUNT);
+    const cyclePos = (((t / SHAPING_CYCLE_SECONDS) % 1) + 1) % 1;
+    const phaseFloat = cyclePos * 3;
+    const phaseIndex = Math.min(2, Math.floor(phaseFloat));
+    const eased = easeInOutCubic(phaseFloat - phaseIndex);
+    const dots = [];
+    for (let index = 0; index < count; index += 1) {
+        const angle = (index / count) * TWO_PI;
+        const triangleR = polygonRadius(angle, 3);
+        const squareR = polygonRadius(angle, 4);
+        let radiusFactor;
+        if (phaseIndex === 0) {
+            radiusFactor = lerp(1, triangleR, eased);
+        }
+        else if (phaseIndex === 1) {
+            radiusFactor = lerp(triangleR, squareR, eased);
+        }
+        else {
+            radiusFactor = lerp(squareR, 1, eased);
+        }
+        const point = {
+            x: Math.cos(angle) * radiusFactor * worldRadius,
+            y: 0,
+            z: Math.sin(angle) * radiusFactor * worldRadius
+        };
+        const jitter = 0.9 + hashUnit(index * 17 + 9) * 0.2;
+        dots.push(place(point, t * SHAPING_SPIN_SPEED, SHAPING_TILT, originPx, worldRadius, SHAPING_BASE_DOT_RADIUS, sizing, jitter));
+    }
+    return { dots, strokes: EMPTY_STROKES };
+};