agent-robot-avatar 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,7 +4,17 @@ All notable user-facing changes to Agent Robot Avatar are documented here.
 
 The project follows Semantic Versioning for public releases. Internal development build numbers are not part of the public version history.
 
-## [Unreleased]
+## [0.7.0] - 2026-10-29
+
+### Added
+
+- 188 skins in 17 series. Pick one by number with `skin="301"` or `setSkin(301)`; `setSkin(null)` goes back to the flat color.
+- Skin numbers are permanent: the series number plus two digits, so 305 is the fifth skin of series 3. New skins take the next free number, and numbers are never reused.
+- Every skin works with every expression and gesture, and its light follows the pointer.
+- `SKINS`, `SKIN_SERIES` and `SKIN_NAMES` list the skins, for building a skin picker.
+- Skin code loads only when a page uses a skin. `loadSkins()` loads it in advance.
+- `agent-robot-avatar/lite`: the same avatar without any skin code.
+- The demo has a Skin Gallery and a page with every skin.
 
 ## [0.6.0] - 2026-10-23
 

package/README.md

@@ -26,7 +26,7 @@ Built with SVG and vanilla JavaScript, it works as a native custom element with
 
 ## Live Demo
 
-[Open the interactive demo](https://cx-artlab.github.io/agent-robot-avatar/)
+[Open the interactive demo](https://cx-artlab.github.io/agent-robot-avatar/) · [Visit the Skin Gallery](https://cx-artlab.github.io/agent-robot-avatar/skins.html)
 
 ## Highlights
 
@@ -38,19 +38,14 @@ Built with SVG and vanilla JavaScript, it works as a native custom element with
 - Jelly-style drag deformation with elastic recovery
 - Press-and-hold squeeze and draggable spring antenna interactions
 - Programmatically controlled Agent states and expressions
-- Waiting, success, failure, warning, review, blocked, and system-error feedback
+- Expressions for waiting, success, failure, affirm, wary, inspect, angry, refuse, love and more
 - Reduced-motion support
 - Configurable sleep behavior
 - Adjustable head roundness
-- Optional antenna status flashing
+- 188 numbered skins in 17 series, with light that follows the pointer
+- A lite build without skins for the smallest pages
 - TypeScript declarations included
 
-## Embedded eyes (experimental)
-
-An independent, allocation-free C++11 eyes-only engine draws the same 18 expressions on robot and dev-board screens. Firmware examples cover 26 board and screen configurations across ESP32, ESP32-S3 and RP2040 — ST7789, ST7735, GC9A01 round, ILI9341/9342/9488, CO5300 AMOLED, ST7701S RGB panels and SSD1306/SH1106 OLEDs, including LilyGO, M5Stack, Waveshare, Seeed and Espressif boards. Every example compiles in CI; none is verified on real hardware yet, so please send a hardware report if you try one.
-
-See the [embedded guide](https://github.com/CX-ArtLab/agent-robot-avatar/tree/main/embedded) and [中文说明](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/embedded/README.zh-CN.md). The Web component's installation and behavior are unchanged.
-
 ## Install
 
 ```bash
@@ -75,6 +70,16 @@ Then add the component:
 
 No initialization code is required. The avatar enters its default idle behavior automatically.
 
+### Lite build
+
+For pages that never use skins, `agent-robot-avatar/lite` is the same avatar without any skin code:
+
+```js
+import 'agent-robot-avatar/lite';
+```
+
+In the lite build the `skin` attribute is ignored, and the console notes that skins need the full build.
+
 ## Basic usage
 
 ```js
@@ -89,15 +94,30 @@ avatar.reset();
 
 Available actions:
 
-`idle` · `bored` · `waiting-spin` · `waiting-wrap` · `waiting-wave` · `input` · `affirm` · `success` · `failure` · `wary` · `inspect` · `angry` · `refuse` · `surprise` · `love` · `random` · `sleep` · `wake`
-
-`waiting-wave` plays three 1.1-second waves: the eyes bob vertically with a staggered rhythm and amplitude of 10 SVG units, then settle. Use `startWaiting({ variant: 'wave' })` for seamless continuous waiting, and `stopWaiting()` to stop. It honors the component's reduced-motion setting and reports the canonical `waiting` action lifecycle.
-
-Action names describe what the avatar does. `refuse` shakes the head, for a request the Agent cannot or will not carry out; `failure` is for a task or connection that did not succeed; `wary` turns the head and gives a guarded up-and-down look, for an action that needs confirmation. Names from 0.5 (`send`, `warning`, `error`, `blocked` and others) still work with a console notice until 1.0; see the [upgrade table](CHANGELOG.md#upgrading-from-05x).
-
-`love` expresses affection or thanks: the two eyes lean together into a single heart, beat three times, then return.
-
-`random` plays a slot-machine spin: each eye rolls over a drum, then the left eye slows, bounces and settles, followed by the right. `slot` is an alias.
+| Action | Looks like | Use when |
+| --- | --- | --- |
+| `idle` | Blinks and glances around | Default state |
+| `bored` | Glances slowly from side to side | Nothing has happened for a while |
+| `waiting-spin` | Eyes circle from side to side | Waiting for a reply (default) |
+| `waiting-wrap` | Eyes slide out one side and back in the other | Waiting for a reply |
+| `waiting-wave` | Eyes bob up and down in turn | Waiting for a reply |
+| `input` | Eyes become blinking text cursors | The user is typing |
+| `affirm` | Nods | Got it, confirmed |
+| `success` | Happy, smiling eyes | Task completed |
+| `failure` | Head and eyes droop | Task or connection failed |
+| `wary` | Turns its head and gives a guarded up-and-down look | An action needs confirmation |
+| `inspect` | Narrows its eyes and scans up and down | Checking or reviewing something |
+| `angry` | Lowered, glaring eyes | Content blocked |
+| `refuse` | Shakes its head | Cannot or will not do the request |
+| `surprise` | Wide-open eyes | Something unexpected |
+| `love` | Eyes merge into a beating heart | Thanks, affection |
+| `random` | Eyes spin like slot-machine reels | Random pick, playful moment |
+| `sleep` | Closes its eyes and sleeps | No activity for a long time |
+| `wake` | Opens its eyes and wakes up | Activity resumes |
+
+Waiting actions play one round with `play()`. `startWaiting({ variant: 'spin' | 'wrap' | 'wave' })` loops until another action starts or `stopWaiting()` is called.
+
+Names from 0.5 (`send`, `warning`, `error`, `blocked`, `slot` and others) still work with a console notice until 1.0; see the [upgrade table](CHANGELOG.md#upgrading-from-05x).
 
 For a real Agent request lifecycle:
 
@@ -139,6 +159,7 @@ try {
 | `motion` | Motion policy: `auto`, `reduce`, or `full` |
 | `press-squeeze` | Center press-and-hold squeeze; set to `false` to disable |
 | `antenna-drag` | Antenna drag, spring return, and angry reaction; set to `false` to disable |
+| `skin` | Skin number, such as `301`; leave it out for the flat color |
 
 Common runtime controls:
 
@@ -151,6 +172,47 @@ avatar.setAntennaDrag(true);
 
 The avatar center begins the squeeze interaction. Moving more than 4 CSS pixels transfers the same pointer gesture to the existing head drag. Dragging the antenna uses the same pull limit as head dragging and ends with the existing angry reaction.
 
+## Skins · New in 0.7
+
+188 skins in 17 series, with light that follows the pointer. Every skin has a permanent number: the series number followed by two digits, so 305 is the fifth skin of series 3. Titles may be reworded later; numbers never change and are never reused.
+
+<img src="./assets/readme/skin-gallery.jpg" alt="Skin Gallery: featured skins, filters and search" width="100%">
+
+```html
+<agent-robot-avatar skin="301"></agent-robot-avatar>
+```
+
+```js
+avatar.setSkin(102);  // or '102'
+avatar.setSkin(null); // back to the flat color
+```
+
+See every skin with its number on the [all skins page](https://cx-artlab.github.io/agent-robot-avatar/materials/).
+
+| Series | Numbers |
+| --- | --- |
+| Glaze | 101–106 |
+| Ice glass | 201–206 |
+| Gummy | 301–312 |
+| Candy glass | 401–406 |
+| Acrylic | 501–512 |
+| Jelly | 601–612 |
+| Gradient | 701–712 |
+| Frosted glass | 801–806 |
+| Metal | 901–930 |
+| Gems and ceramics | 1001–1012 |
+| Wood | 1101–1106 |
+| Balls | 1201–1210 |
+| Clear and shimmer | 1301–1305 |
+| Fabric and leather | 1401–1412 |
+| Sweets and fruit | 1501–1512 |
+| Nature | 1601–1612 |
+| Patterns and tech | 1701–1717 |
+
+Skin painters download the first time a skin is used, so a page without skins never loads them. `await loadSkins()` loads them in advance. `SKINS` holds each skin’s Chinese and English titles and colors, `SKIN_SERIES` the series, and `SKIN_NAMES` every number.
+
+Every expression and gesture works with a skin. When the skin is removed, the `color` attribute applies again.
+
 ## Events and integration
 
 The component emits `face-state` for visual state changes and `action-state` for semantic action lifecycle changes.
@@ -165,6 +227,10 @@ Designed for modern browsers with support for ES Modules, Custom Elements, SVG,
 
 Automated browser tests cover Chromium, Firefox, and WebKit.
 
+## Hardware version (in development)
+
+A C++ version that shows the avatar's expressions on robot and dev-board screens (it draws only the eyes) is in development and not released yet. See the [hardware guide](https://github.com/CX-ArtLab/agent-robot-avatar/tree/main/embedded).
+
 ## Contributing
 
 Issues and pull requests are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) before submitting changes.
@@ -195,4 +261,3 @@ If this project is useful to you, you can buy me a coffee.
 
 <a href='https://ko-fi.com/P0E625WIOI' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
 
-

package/agent-robot-avatar-lite.js

@@ -0,0 +1,44 @@
+// The smallest build: every expression and gesture, without skins. The skin
+// attribute and setSkin() only explain where skins live, so a page written for
+// the full build keeps working with the plain avatar.
+import AgentRobotAvatar from './src/agent-robot-avatar-extension-host.js';
+import './src/agent-robot-avatar-actions.js';
+import './src/agent-robot-avatar-antenna.js';
+import './src/agent-robot-avatar-waiting.js';
+import './src/agent-robot-avatar-inspect.js';
+import './src/agent-robot-avatar-failure.js';
+import './src/agent-robot-avatar-love.js';
+import './src/agent-robot-avatar-random.js';
+import './src/agent-robot-avatar-head-roundness.js';
+import './src/agent-robot-avatar-gestures.js';
+import './src/agent-robot-avatar-runtime.js';
+import { VERSION } from './src/agent-robot-avatar-version.js';
+
+const proto = AgentRobotAvatar.prototype;
+let warned = false;
+function explain() {
+  if (warned) return;
+  warned = true;
+  console.warn('agent-robot-avatar: skins are not part of the lite build; import "agent-robot-avatar" instead of "agent-robot-avatar/lite" to use them.');
+}
+if (!proto.setSkin) {
+  proto._applySkinAttribute = function() { if (this.getAttribute('skin')) explain(); };
+  proto.setSkin = function(value = null) {
+    if (value !== null && value !== 'none') explain();
+    return this;
+  };
+  proto.getSkin = () => null;
+}
+
+// Elements already present in markup can upgrade while the core module is
+// loading, before runtime extensions finish installing their prototype hooks.
+if (typeof document !== 'undefined') {
+  document.querySelectorAll('agent-robot-avatar').forEach(avatar => avatar._resumeFrames?.());
+}
+
+if (typeof window !== 'undefined') {
+  window.AgentRobotAvatarVersion = VERSION;
+}
+
+export { AgentRobotAvatar, VERSION };
+export default AgentRobotAvatar;

package/agent-robot-avatar.js

@@ -8,6 +8,7 @@ import './src/agent-robot-avatar-love.js';
 import './src/agent-robot-avatar-random.js';
 import './src/agent-robot-avatar-head-roundness.js';
 import './src/agent-robot-avatar-gestures.js';
+import { SKIN_NAMES, SKINS, SKIN_SERIES, loadSkins } from './src/agent-robot-avatar-skins.js';
 import './src/agent-robot-avatar-runtime.js';
 import { VERSION } from './src/agent-robot-avatar-version.js';
 
@@ -23,5 +24,5 @@ if (typeof window !== 'undefined') {
   window.AgentRobotAvatarVersion = VERSION;
 }
 
-export { AgentRobotAvatar, VERSION };
+export { AgentRobotAvatar, SKIN_NAMES, SKINS, SKIN_SERIES, VERSION, loadSkins };
 export default AgentRobotAvatar;

package/index.d.ts

@@ -39,6 +39,63 @@ export type AgentRobotAvatarDeprecatedAction =
   | 'connection-error'
   | 'slot';
 
+/**
+ * Skin numbers for the `skin` attribute and `setSkin()`: the series number
+ * followed by two digits, so `305` is the fifth skin of series 3. A number is
+ * permanent; titles may be reworded, numbers never change and are never reused.
+ */
+export type AgentRobotAvatarSkin =
+  | '101' | '102' | '103' | '104' | '105' | '106' | '201' | '202' | '203' | '204' | '205' | '206'
+  | '301' | '302' | '303' | '304' | '305' | '306' | '307' | '308' | '309' | '310' | '311' | '312'
+  | '401' | '402' | '403' | '404' | '405' | '406' | '501' | '502' | '503' | '504' | '505' | '506'
+  | '507' | '508' | '509' | '510' | '511' | '512' | '601' | '602' | '603' | '604' | '605' | '606'
+  | '607' | '608' | '609' | '610' | '611' | '612' | '701' | '702' | '703' | '704' | '705' | '706'
+  | '707' | '708' | '709' | '710' | '711' | '712' | '801' | '802' | '803' | '804' | '805' | '806'
+  | '901' | '902' | '903' | '904' | '905' | '906' | '907' | '908' | '909' | '910' | '911' | '912'
+  | '913' | '914' | '915' | '916' | '917' | '918' | '919' | '920' | '921' | '922' | '923' | '924'
+  | '925' | '926' | '927' | '928' | '929' | '930' | '1001' | '1002' | '1003' | '1004' | '1005' | '1006'
+  | '1007' | '1008' | '1009' | '1010' | '1011' | '1012' | '1101' | '1102' | '1103' | '1104' | '1105' | '1106'
+  | '1201' | '1202' | '1203' | '1204' | '1205' | '1206' | '1207' | '1208' | '1209' | '1210' | '1301' | '1302'
+  | '1303' | '1304' | '1305' | '1401' | '1402' | '1403' | '1404' | '1405' | '1406' | '1407' | '1408' | '1409'
+  | '1410' | '1411' | '1412' | '1501' | '1502' | '1503' | '1504' | '1505' | '1506' | '1507' | '1508' | '1509'
+  | '1510' | '1511' | '1512' | '1601' | '1602' | '1603' | '1604' | '1605' | '1606' | '1607' | '1608' | '1609'
+  | '1610' | '1611' | '1612' | '1701' | '1702' | '1703' | '1704' | '1705' | '1706' | '1707' | '1708' | '1709'
+  | '1710' | '1711' | '1712' | '1713' | '1714' | '1715' | '1716' | '1717';
+
+/** Display information for one skin. */
+export interface AgentRobotAvatarSkinInfo {
+  /** The series id, such as `'glaze'` or `'metal'`. */
+  readonly series: string;
+  /** Chinese title. */
+  readonly title: string;
+  /** English title. */
+  readonly titleEn: string;
+  /** Representative colors, light to dark. */
+  readonly base: readonly string[];
+}
+
+/** A group of related skins, in gallery order. */
+export interface AgentRobotAvatarSkinSeries {
+  readonly id: string;
+  /** The first digits of every skin number in the series. */
+  readonly number: number;
+  readonly title: string;
+  readonly titleEn: string;
+  readonly skins: readonly AgentRobotAvatarSkin[];
+}
+
+/** Every skin number, in gallery order. */
+export declare const SKIN_NAMES: readonly AgentRobotAvatarSkin[];
+/** Titles and colors for every skin, by number. */
+export declare const SKINS: Readonly<Record<AgentRobotAvatarSkin, AgentRobotAvatarSkinInfo>>;
+/** The skin series, in gallery order. */
+export declare const SKIN_SERIES: readonly AgentRobotAvatarSkinSeries[];
+/**
+ * Skin painters download the first time a skin is used, so the first skin shows
+ * a moment after it is set. Await this to load them in advance.
+ */
+export declare function loadSkins(): Promise<void>;
+
 export type AgentRobotAvatarState =
   | 'idle'
   | 'happy'
@@ -114,6 +171,13 @@ export declare class AgentRobotAvatar extends HTMLElement {
   setAntennaDrag(enabled?: boolean): this;
   setHeadRoundness(value?: number): this;
   getHeadRoundness(): number;
+  /**
+   * Dresses the head in a numbered skin with light that follows the pointer.
+   * Same as the `skin` attribute; `null` or `'none'` returns to the flat color.
+   * Throws for an unknown number.
+   */
+  setSkin(skin?: AgentRobotAvatarSkin | number | 'none' | null): this;
+  getSkin(): AgentRobotAvatarSkin | null;
   noteActivity(wake?: boolean): void;
 
   addEventListener<K extends keyof AgentRobotAvatarEventMap>(

package/lite.d.ts

@@ -0,0 +1,5 @@
+// The lite build: the same avatar without skins. setSkin() keeps its type so a
+// page can switch builds, but it only logs that skins need the full build.
+export { AgentRobotAvatar, VERSION } from './index.js';
+export { default } from './index.js';
+export type * from './index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-robot-avatar",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A lightweight expressive robot avatar Web Component for AI agents and interactive applications.",
   "type": "module",
   "main": "./agent-robot-avatar.js",
@@ -14,6 +14,11 @@
       "types": "./index.d.ts",
       "import": "./agent-robot-avatar.js",
       "default": "./agent-robot-avatar.js"
+    },
+    "./lite": {
+      "types": "./lite.d.ts",
+      "import": "./agent-robot-avatar-lite.js",
+      "default": "./agent-robot-avatar-lite.js"
     }
   },
   "sideEffects": true,
@@ -21,21 +26,22 @@
     "dev": "node scripts/serve.mjs",
     "build:pages": "node scripts/build-pages.mjs",
     "check": "node scripts/check-source.mjs",
-    "test": "npm run check && npm run test:types && npm run test:release && npm run test:package && npm run test:waiting && npm run test:browser && npm run build:pages",
+    "test": "npm run check && npm run test:types && npm run test:release && npm run test:package && npm run test:waiting && npm run test:browser && npm run test:pages",
     "release:check": "npm test && npm publish --dry-run --ignore-scripts --tag latest",
     "prepublishOnly": "npm test && node scripts/check-publish-tag.mjs",
     "test:types": "tsc -p tsconfig.types.json",
     "test:release": "node --test tests/release.test.mjs",
     "test:package": "node --test tests/package.test.mjs",
     "test:waiting": "node --test tests/waiting-wave.test.mjs",
-    "test:browser": "playwright test"
+    "test:browser": "playwright test",
+    "test:pages": "node --test tests/pages-public.test.mjs"
   },
   "files": [
     "agent-robot-avatar.js",
+    "agent-robot-avatar-lite.js",
     "index.d.ts",
+    "lite.d.ts",
     "src/",
-    "assets/support/",
-    "docs/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -76,4 +82,3 @@
     "typescript": "7.0.2"
   }
 }
-

package/src/agent-robot-avatar-core.js

@@ -374,8 +374,11 @@ const AgentRobotAvatar = (() => {
       const near = Math.max(r.width, r.height) * 2.55;
       const dist = Math.hypot(dx, dy);
       const influence = clamp(1 - dist / near, 0, 1);
-      this._pointer.x = clamp(dx * .42, -48, 48);
-      this._pointer.y = clamp(dy * .38, -34, 34);
+      // Measure the pointer offset as if the avatar were demo-sized, so a large
+      // avatar does not look further than a small one for the same gesture.
+      const scale = Math.min(1, 120 / Math.max(1, r.width, r.height));
+      this._pointer.x = clamp(dx * .42 * scale, -48, 48);
+      this._pointer.y = clamp(dy * .38 * scale, -34, 34);
       this._pointer.active = influence > 0.001;
       this._pointer.influence = influence;
       this._pointer.lastMove = performance.now();

package/src/agent-robot-avatar-runtime.js

@@ -444,15 +444,18 @@ function ensureRuntime(instance) {
         if (record.attributeName === 'size') applySize(instance);
         if (record.attributeName === 'motion') motionChanged = true;
         if (record.attributeName === 'auto-sleep') autoSleepChanged = true;
+        if (record.attributeName === 'skin') instance._applySkinAttribute?.();
       }
       if (motionChanged) handleMotionChange(instance);
       if (autoSleepChanged) scheduleAutoSleep(instance);
     });
     instance._runtimeAttributeObserver.observe(instance, {
       attributes: true,
-      attributeFilter: ['size', 'motion', 'wake-on', 'auto-sleep'],
+      attributeFilter: ['size', 'motion', 'wake-on', 'auto-sleep', 'skin'],
     });
   }
+  // A skin set with setSkin() survives a reconnect; markup only applies when present.
+  if (instance.hasAttribute('skin')) instance._applySkinAttribute?.();
 
   if (typeof IntersectionObserver !== 'undefined') {
     instance._runtimeIntersectionObserver = new IntersectionObserver(entries => {

package/src/agent-robot-avatar-skin-patterns.js

@@ -0,0 +1,234 @@
+// Pattern tiles for skins. Each generator returns the tile size, an optional
+// pattern transform and the SVG markup of one tile, in the head's 240-unit
+// coordinates. Scattered patterns use a seeded random source so every avatar
+// shows the same tile.
+
+const rng = seed => {
+  let state = (seed % 2147483647) || 1;
+  return () => (state = state * 16807 % 2147483647) / 2147483647;
+};
+const n = value => Number(value.toFixed(2));
+const pick = (random, list) => list[Math.floor(random() * list.length) % list.length];
+
+// Repeats an element at the tile edges so scattered shapes wrap seamlessly.
+function wrap(size, x, y, r, draw) {
+  let out = '';
+  for (const dx of [-size, 0, size]) for (const dy of [-size, 0, size]) {
+    if (x + dx + r < 0 || x + dx - r > size || y + dy + r < 0 || y + dy - r > size) continue;
+    out += draw(x + dx, y + dy);
+  }
+  return out;
+}
+
+// Turns a point on the unit sphere, for the patterns drawn on balls.
+function rotate([x, y, z], [yaw, pitch, roll]) {
+  let c = Math.cos(yaw), s = Math.sin(yaw);
+  [x, z] = [x * c + z * s, -x * s + z * c];
+  c = Math.cos(pitch); s = Math.sin(pitch);
+  [y, z] = [y * c - z * s, y * s + z * c];
+  c = Math.cos(roll); s = Math.sin(roll);
+  [x, y] = [x * c - y * s, x * s + y * c];
+  return [x, y, z];
+}
+
+
+
+
+
+const PATTERNS = {
+  tartan({ colors: [a, b, c], size = 56 }) {
+    const bands = [[0, 18, a, .55], [26, 3, b, .8], [38, 2, c, .8], [44, 6, a, .35]];
+    let body = '';
+    for (const [x, w, color, o] of bands) {
+      body += `<rect x="${x}" width="${w}" height="${size}" fill="${color}" opacity="${o}"/><rect y="${x}" width="${size}" height="${w}" fill="${color}" opacity="${o}"/>`;
+    }
+    return { size: [size, size], body };
+  },
+  dots({ colors: [c], r = 5, size = 26, opacity = 1 }) {
+    const q = size / 4;
+    return { size: [size, size], body: `<circle cx="${q}" cy="${q}" r="${r}" fill="${c}" opacity="${opacity}"/><circle cx="${q * 3}" cy="${q * 3}" r="${r}" fill="${c}" opacity="${opacity}"/>` };
+  },
+  terrazzo({ colors, count = 44, size = 120, seed = 5 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < count; i++) {
+      const x = random() * size, y = random() * size, k = 2.5 + random() * 6, sides = 3 + Math.floor(random() * 3), color = pick(random, colors), turn = random() * Math.PI;
+      let d = '';
+      for (let j = 0; j < sides; j++) {
+        const a = turn + j / sides * Math.PI * 2, rr = k * (.6 + random() * .5);
+        d += `${j ? 'L' : 'M'}${n(Math.cos(a) * rr)} ${n(Math.sin(a) * rr)}`;
+      }
+      body += wrap(size, x, y, k, (px, py) => `<path d="${d}Z" fill="${color}" transform="translate(${n(px)} ${n(py)})"/>`);
+    }
+    return { size: [size, size], body };
+  },
+  marble({ colors: [a, b], seed = 21 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < 7; i++) {
+      const color = i % 3 === 2 ? b : a;
+      let x = -20, y = random() * 240, d = `M${n(x)} ${n(y)}`;
+      while (x < 260) {
+        const nx = x + 30 + random() * 40, ny = y + (random() - .5) * 70;
+        d += `Q${n(x + 15 + random() * 20)} ${n(y + (random() - .5) * 60)} ${n(nx)} ${n(ny)}`;
+        x = nx; y = ny;
+      }
+      body += `<path d="${d}" fill="none" stroke="${color}" stroke-width="${n(.6 + random() * 1.8)}" opacity="${n(.35 + random() * .35)}"/>`;
+      body += `<path d="${d}" fill="none" stroke="${color}" stroke-width="${n(5 + random() * 6)}" opacity=".07"/>`;
+    }
+    return { size: [240, 240], body };
+  },
+  pixel({ colors, cell = 10, size = 80, seed = 31, opacity = .9 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let y = 0; y < size; y += cell) for (let x = 0; x < size; x += cell) {
+      if (random() < .45) continue;
+      body += `<rect x="${x}" y="${y}" width="${cell}" height="${cell}" fill="${pick(random, colors)}" opacity="${opacity}"/>`;
+    }
+    return { size: [size, size], body };
+  },
+  confetti({ colors, count = 38, size = 120, seed = 37 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < count; i++) {
+      const x = random() * size, y = random() * size, color = pick(random, colors), turn = random() * 180, strip = random() < .5;
+      body += wrap(size, x, y, 6, (px, py) => strip
+        ? `<rect x="${n(px - 1.6)}" y="${n(py - 4)}" width="3.2" height="8" rx="1" fill="${color}" transform="rotate(${n(turn)} ${n(px)} ${n(py)})"/>`
+        : `<circle cx="${n(px)}" cy="${n(py)}" r="2.2" fill="${color}"/>`);
+    }
+    return { size: [size, size], body };
+  },
+  halftone({ colors: [c], step = 12, opacity = .7 }) {
+    let body = '';
+    for (let y = 6; y < 240; y += step) for (let x = 6 + ((y / step) % 2) * step / 2; x < 240; x += step) {
+      body += `<circle cx="${n(x)}" cy="${n(y)}" r="${n(.6 + 4.4 * (y / 240))}" fill="${c}" opacity="${opacity}"/>`;
+    }
+    return { size: [240, 240], body };
+  },
+  scatter({ colors, shapes, count = 12, size = 120, k = [6, 10], seed = 47 }) {
+    const random = rng(seed);
+    let body = '';
+    for (let i = 0; i < count; i++) {
+      const x = random() * size, y = random() * size, r = k[0] + random() * (k[1] - k[0]), turn = (random() - .5) * 70;
+      const shape = pick(random, shapes), color = colors[i % colors.length], accent = colors[(i + 1) % colors.length];
+      const art = SHAPES[shape](r, color, accent);
+      body += wrap(size, x, y, r * 1.3, (px, py) => `<g transform="translate(${n(px)} ${n(py)}) rotate(${n(turn)})">${art}</g>`);
+    }
+    return { size: [size, size], body };
+  },
+  grooves({ colors: [line, shadow], radius = 138, angles = [.5, -.45, .2] }) {
+    // A modern ball: rings of fine grooves wrapping the surface in three directions.
+    let body = '';
+    for (const axis of [[1, 0, 0], [0, 1, 0], [0, 0, 1]]) {
+      for (const lat of [-.42, 0, .42]) {
+        const pts = [];
+        for (let k = 0; k <= 72; k++) {
+          const a = k / 72 * Math.PI * 2, r = Math.cos(lat), h = Math.sin(lat);
+          const p = axis[0] ? [h, r * Math.cos(a), r * Math.sin(a)] : axis[1] ? [r * Math.cos(a), h, r * Math.sin(a)] : [r * Math.cos(a), r * Math.sin(a), h];
+          pts.push(rotate(p, angles));
+        }
+        let d = '';
+        pts.forEach(([x, y, z], i) => { d += `${i && z > 0 && pts[i - 1][2] > 0 ? 'L' : 'M'}${n(120 + x * radius)} ${n(120 + y * radius)}`; });
+        body += `<path d="${d}" fill="none" stroke="${shadow}" stroke-width="3" opacity=".6" transform="translate(.8 1)"/><path d="${d}" fill="none" stroke="${line}" stroke-width="1.6"/>`;
+      }
+    }
+    return { size: [240, 240], body };
+  },
+  // Balls: each is drawn once across the whole head instead of repeating.
+  basketball({ colors: [seam, grain] }) {
+    return {
+      size: [240, 240],
+      defs: tex => `<pattern id="${tex}" patternUnits="userSpaceOnUse" width="6" height="6"><circle cx="3" cy="3" r=".9" fill="${grain}" opacity=".32"/></pattern>`,
+      body: tex => `<rect width="240" height="240" fill="url(#${tex})"/><path d="M120 0V240M0 120H240M52 18Q100 120 52 222M188 18Q140 120 188 222" fill="none" stroke="#ffd2a6" stroke-width="2.4" stroke-linecap="round" opacity=".55" transform="translate(1.2 1.6)"/><path d="M120 0V240M0 120H240M52 18Q100 120 52 222M188 18Q140 120 188 222" fill="none" stroke="${seam}" stroke-width="3.4" stroke-linecap="round"/>`,
+    };
+  },
+
+
+
+
+
+  tennis({ colors: [seam, fuzz] }) {
+    return {
+      size: [240, 240],
+      defs: tex => `<pattern id="${tex}" patternUnits="userSpaceOnUse" width="7" height="7"><circle cx="1.5" cy="2" r=".7" fill="${fuzz}" opacity=".35"/><circle cx="5" cy="5.5" r=".6" fill="#ffffff" opacity=".3"/></pattern>`,
+      body: tex => `<rect width="240" height="240" fill="url(#${tex})"/><path d="M14 62C92 34 92 206 14 178M226 62C148 34 148 206 226 178" fill="none" stroke="#f7ffd0" stroke-width="6.5" stroke-linecap="round" opacity=".45" transform="translate(1 1.6)"/><path d="M14 62C92 34 92 206 14 178M226 62C148 34 148 206 226 178" fill="none" stroke="#4a6000" stroke-width="6.5" stroke-linecap="round" opacity=".38" transform="translate(-1 -1.6)"/><path d="M14 62C92 34 92 206 14 178M226 62C148 34 148 206 226 178" fill="none" stroke="${seam}" stroke-width="5" stroke-linecap="round"/>`,
+    };
+  },
+  baseball({ colors: [seam, stitch] }) {
+    const arc = (x0, cx) => {
+      let stitches = '';
+      for (let t = .06; t < .96; t += .055) {
+        const x = (1 - t) ** 2 * x0 + 2 * (1 - t) * t * cx + t * t * x0, y = (1 - t) ** 2 * 26 + 2 * (1 - t) * t * 120 + t * t * 214;
+        const dx = 2 * (1 - t) * (cx - x0) + 2 * t * (x0 - cx), dy = 2 * (1 - t) * 94 + 2 * t * 94, len = Math.hypot(dx, dy);
+        const nx = -dy / len * 5, ny = dx / len * 5, tx = dx / len * 2.2, ty = dy / len * 2.2;
+        stitches += `M${n(x - nx - tx)} ${n(y - ny - ty)}L${n(x)} ${n(y)}L${n(x + nx - tx)} ${n(y + ny - ty)}`;
+      }
+      return `<path d="M${x0} 26Q${cx} 120 ${x0} 214" fill="none" stroke="${seam}" stroke-width="1.3"/><path d="${stitches}" fill="none" stroke="${stitch}" stroke-width="2" stroke-linecap="round"/>`;
+    };
+    return { size: [240, 240], body: arc(44, 104) + arc(196, 136) };
+  },
+  cricket({ colors: [seam, stitch] }) {
+    // A raised seam arching over the forehead with three rows of stitches each side.
+    const y = (x, lift) => 84 - Math.sin(x / 240 * Math.PI) * 26 + lift;
+    const curve = lift => {
+      let d = '';
+      for (let x = -4; x <= 244; x += 8) d += `${x < 0 ? 'M' : 'L'}${x} ${n(y(x, lift))}`;
+      return d;
+    };
+    let rows = '';
+    for (const lift of [-11, -7, -3, 3, 7, 11]) {
+      for (let x = 2; x < 240; x += 6) rows += `M${x} ${n(y(x, lift))}l2.6 -1.2`;
+    }
+    return { size: [240, 240], body: `<path d="${curve(0)}" fill="none" stroke="${seam}" stroke-width="15" stroke-linecap="round" opacity=".55"/><path d="${curve(0)}" fill="none" stroke="${seam}" stroke-width="2"/><path d="${rows}" fill="none" stroke="${stitch}" stroke-width="1.5" stroke-linecap="round"/>` };
+  },
+
+
+
+
+
+
+
+
+
+  golf({ colors: [shade, shine], r = 5.6 }) {
+    const w = 15, h = w * Math.sqrt(3);
+    const dimple = (x, y) => `<circle cx="${n(x)}" cy="${n(y)}" r="${r}" fill="${shade}" opacity=".55"/><circle cx="${n(x + .9)}" cy="${n(y + 1)}" r="${n(r * .55)}" fill="${shine}" opacity=".8"/>`;
+    return { size: [w, n(h)], body: dimple(0, 0) + dimple(w, 0) + dimple(w / 2, h / 2) + dimple(0, h) + dimple(w, h) };
+  },
+  football({ colors: [lace, grain, seam] }) {
+    // Lying on its side: laces run along the top, stripes ring both ends.
+    let stitches = '';
+    for (let x = 90; x <= 150; x += 10) stitches += `M${x} 44V60`;
+    return {
+      size: [240, 240],
+      defs: tex => `<pattern id="${tex}" patternUnits="userSpaceOnUse" width="5" height="5"><circle cx="2.5" cy="2.5" r=".8" fill="${grain}" opacity=".35"/></pattern>`,
+      body: tex => `<rect width="240" height="240" fill="url(#${tex})"/>`
+        + `<path d="M-10 40Q120 62 250 40M-10 210Q120 188 250 210" fill="none" stroke="${seam}" stroke-width="1.4" opacity=".7"/>`
+        + `<g transform="translate(1 1.6)" opacity=".35"><path d="M84 52H156" stroke="#1a0800" stroke-width="2"/><path d="${stitches}" stroke="#1a0800" stroke-width="3.6" stroke-linecap="round"/></g>`
+        + `<path d="M84 52H156" stroke="${lace}" stroke-width="2"/><path d="${stitches}" stroke="${lace}" stroke-width="3.4" stroke-linecap="round"/>`
+        + `<path d="M34 20Q46 120 34 220M46 20Q58 120 46 220M206 20Q194 120 206 220M194 20Q182 120 194 220" fill="none" stroke="${lace}" stroke-width="5"/>`,
+    };
+  },
+};
+
+const SHAPES = {
+  leaf: (k, c, accent) => `<path d="M0 ${n(-k)}Q${n(.65 * k)} 0 0 ${n(k)}Q${n(-.65 * k)} 0 0 ${n(-k)}Z" fill="${c}"/><path d="M0 ${n(-.8 * k)}V${n(.9 * k)}" stroke="${accent}" stroke-width="${n(.08 * k)}"/>`,
+  blossom: (k, c, accent) => `${[0, 72, 144, 216, 288].map(a => `<ellipse cy="${n(-.5 * k)}" rx="${n(.3 * k)}" ry="${n(.45 * k)}" fill="${c}" transform="rotate(${a})"/>`).join('')}<circle r="${n(.2 * k)}" fill="${accent}"/>`,
+};
+
+// A generator may also return defs (for example a fine texture tile) that its
+// body refers to; both receive the texture id.
+// Generated tiles are cached per spec; ball layouts take a moment to work out.
+const tiles = new Map();
+function patternMarkup(id, spec) {
+  const make = PATTERNS[spec.kind];
+  if (!make) return '';
+  const key = JSON.stringify(spec);
+  if (!tiles.has(key)) tiles.set(key, make(spec));
+  const { size: [w, h], transform, body, defs } = tiles.get(key);
+  const tex = `${id}-texture`;
+  const inner = typeof body === 'function' ? body(tex) : body;
+  return `${defs ? defs(tex) : ''}<pattern id="${id}" patternUnits="userSpaceOnUse" width="${w}" height="${h}"${transform ? ` patternTransform="${transform}"` : ''}>${inner}</pattern>`;
+}
+
+export { PATTERNS, patternMarkup };