@fungi.computer/sprite 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# Sprite (`@fungi.computer/sprite`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sprite presents a character document through a host-installed renderer, so a
+game or app can show an animated avatar without writing its own rendering layer.
+The host chooses local characters, renderer adapters, network origins, and asset
+limits. Each mounted player owns its current source and presentation lifetime.
+
+## Install or set up
+
+```sh
+npm install @fungi.computer/sprite
+```
+
+The package ships ESM only and depends on Effect, Zod, and
+[Cairn](../cairn/README.md) at runtime. React is an optional peer dependency,
+needed only for the `./react` entrypoint. The core entrypoint,
+`@fungi.computer/sprite`, exports the renderer-neutral player API.
+`@fungi.computer/sprite/react` exports the React provider and component.
+`@fungi.computer/sprite/video` exports the optional video renderer. `./avatar`
+supplies avatar descriptors and catalog-aware validation. `./ink` and
+`./mycelium` mount decorative drawings independently of the character player.
+Zdog support ships as the separate [Sprite Zdog](../sprite-zdog/README.md)
+package.
+
+## Quick start
+
+This illustrative React example configures the host's asset policy and lazy
+video renderer, then presents a character document:
+
+```tsx
+import { createSprite } from "@fungi.computer/sprite";
+import { Sprite, SpriteProvider } from "@fungi.computer/sprite/react";
+
+const service = createSprite({
+  assets: {
+    baseURL: window.location.href,
+    allowedOrigins: [window.location.origin],
+    maxBytes: 2_000_000,
+    maxTotalBytes: 4_000_000,
+    maxRequests: 4,
+  },
+  renderers: {
+    video: () => import("@fungi.computer/sprite/video"),
+  },
+});
+
+function Character() {
+  return (
+    <SpriteProvider service={service}>
+      <Sprite
+        src="/characters/my-avatar.json"
+        activity="idle"
+        role="img"
+        aria-label="My avatar"
+      />
+    </SpriteProvider>
+  );
+}
+```
+
+The package tests exercise player updates, React lifetime, and asset admission.
+See [`src/player.test.ts`](src/player.test.ts),
+[`src/react.test.tsx`](src/react.test.tsx), and
+[`src/assets.test.ts`](src/assets.test.ts).
+
+## Core concepts
+
+A character document has `version: 1`, a name, a renderer name, optional
+controls and poster, and renderer-specific `data`. The shared schema validates
+that envelope. The selected adapter validates its own data. A source is either a
+document URL or `{ local: "key" }` for a character installed by the host.
+
+`createSprite` creates a stable host service. The host supplies local
+characters, renderer loaders, and asset policy. A player selects one source and
+receives activity, expression, appearance, and render-style updates without
+replacing its host element. The React `Sprite` owns one player and disposes it
+when it unmounts. The imperative player exposes `set`, `pause`, `subscribe`, and
+asynchronous `dispose`.
+
+`renderStyle` applies one of the built-in SVG filters: `plain`, `pencil`,
+`manga`, `riso`, `halftone`, `blueprint`, `crt`, or `watercolor`. Each player
+owns its filter instance. Animated styles pause when the player is paused, is
+offscreen, the page is hidden, or reduced motion is requested.
+
+Remote documents and nested assets pass through one reader. The host sets
+allowed origins, the maximum bytes per response, total bytes per selection, and
+request count. Local characters need no remote asset policy. Video uses the
+configured `video` renderer and reads clip assets through that same path.
+
+The React `Sprite` takes `src`, optional `activity`, `expression`, `appearance`
+and `renderStyle`, plus ordinary attributes for its host `div`. Pass `paused` to
+suspend it and `onState` to observe player states. A direct `service` prop
+overrides `SpriteProvider`; one of them is required.
+
+### Saved avatars
+
+`@fungi.computer/sprite/avatar` defines the v1 descriptor: `v`, `character`,
+`appearance`, `expression` and `renderStyle`. `avatarEnvelopeSchema` checks only
+that envelope. Use `createAvatarSchema(catalog)` or `parseAvatar(data, catalog)`
+to also validate the selected character's controls and expressions. Sprite Zdog
+supplies a validator bound to its built-in catalog.
+
+### Decorative drawings
+
+`mountInkDrawing(host, { art, palette, ...options })` from `./ink` paints traced
+art with Canvas 2D. The palette is a callback; call the returned `redraw()`
+after a theme change and `destroy()` when the host leaves.
+
+`mountMycelium(host, { pixi, palette, ...options })` from `./mycelium` returns a
+Promise for a growing field with `pulse()` and `destroy()`. The host supplies
+Pixi 8 and the palette. Both drawings respect reduced motion and release their
+canvas and observers through `destroy()`.
+
+## API reference
+
+See the generated [Sprite API reference](docs/api/README.md). Import the
+renderer-neutral player API from `@fungi.computer/sprite`, the React provider
+and component from `@fungi.computer/sprite/react`, and the video adapter from
+`@fungi.computer/sprite/video`. The reference also covers `./avatar`; the
+decorative `./ink` and `./mycelium` contracts are described above.
+
+## Examples and checks
+
+The video workbench story presents a character with multiple clips and changes
+the activity to select a clip. Start the local Ladle workbench from the
+repository root with:
+
+```sh
+pnpm --filter @fungi.computer/sprite exec ladle serve
+```
+
+Run the package tests with:
+
+```sh
+pnpm --filter @fungi.computer/sprite test
+```
+
+## Limits and errors
+
+Sprite validates the shared document envelope, not renderer-specific data. The
+host must configure the renderer named by a served document and review its asset
+policy. Without an asset policy, remote origins are denied. Video codec support
+depends on the browser and the encoded file.
+
+The built-in render styles draw through an SVG filter. Reduced-motion
+preferences, pause state, offscreen status, and page visibility suspend styles
+that animate. A still frame remains. `poster` supplies a loading image, not a
+replacement for host asset limits.
+
+## Contribute and license
+
+Sprite is MIT licensed. See [`LICENSE`](LICENSE) and
+[`THIRD_PARTY_NOTICES`](THIRD_PARTY_NOTICES).

package/dist/assets.d.ts

@@ -0,0 +1,20 @@
+/** Host-owned admission and resource limits for published avatar artwork. */
+export type AssetPolicy = {
+    readonly baseURL: string;
+    readonly allowedOrigins: readonly string[];
+    /** Maximum bytes admitted for one response. */
+    readonly maxBytes: number;
+    /** Cumulative bytes admitted across one character selection. */
+    readonly maxTotalBytes: number;
+    /** Number of requests admitted for one character selection. */
+    readonly maxRequests: number;
+    readonly fetch?: typeof fetch;
+};
+/** Decoded transport bytes; adapters use these instead of opening their own URLs. */
+export type Asset = {
+    readonly url: string;
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    readonly contentType: string;
+};
+/** One policy-enforced path for documents and their nested native resources. */
+export declare function createAssetReader(policy: AssetPolicy): () => (reference: string, signal: AbortSignal, base?: string) => Promise<Asset>;

package/dist/assets.js

@@ -0,0 +1,83 @@
+/** One policy-enforced path for documents and their nested native resources. */
+export function createAssetReader(policy) {
+    for (const [name, limit] of Object.entries({
+        maxBytes: policy.maxBytes,
+        maxTotalBytes: policy.maxTotalBytes,
+        maxRequests: policy.maxRequests,
+    })) {
+        if (!Number.isSafeInteger(limit) || limit <= 0)
+            throw new Error(`Avatar ${name} must be a positive safe integer`);
+    }
+    const origins = new Set(policy.allowedOrigins.map((origin) => new URL(origin).origin));
+    const request = policy.fetch ?? globalThis.fetch;
+    return () => {
+        let totalBytes = 0;
+        let requests = 0;
+        return async (reference, signal, base = policy.baseURL) => {
+            const url = new URL(reference, base);
+            if (!["http:", "https:"].includes(url.protocol) ||
+                !origins.has(url.origin) ||
+                url.username ||
+                url.password) {
+                throw new Error(`Avatar asset is not admitted: ${url.origin}`);
+            }
+            requests += 1;
+            if (requests > policy.maxRequests)
+                throw new Error("Avatar asset request limit reached");
+            // Reject redirects before a browser can contact an unapproved destination.
+            const response = await request(url.href, { signal, redirect: "error" });
+            if (!response.ok)
+                throw new Error(`Avatar asset request failed: ${String(response.status)}`);
+            const declaredSize = Number(response.headers.get("content-length"));
+            if (declaredSize > policy.maxBytes ||
+                declaredSize > policy.maxTotalBytes - totalBytes) {
+                await response.body?.cancel();
+                throw new Error("Avatar asset exceeds the byte limit");
+            }
+            const reader = response.body?.getReader();
+            if (!reader)
+                throw new Error("Avatar asset has no response body");
+            const chunks = [];
+            let size = 0;
+            try {
+                for (;;) {
+                    signal.throwIfAborted();
+                    const chunk = await reader.read();
+                    if (chunk.done)
+                        break;
+                    size += chunk.value.byteLength;
+                    if (size > policy.maxBytes)
+                        throw new Error("Avatar asset exceeds the byte limit");
+                    if (chunk.value.byteLength > policy.maxTotalBytes - totalBytes)
+                        throw new Error("Avatar selection exceeds the total byte limit");
+                    totalBytes += chunk.value.byteLength;
+                    chunks.push(chunk.value);
+                }
+            }
+            catch (error) {
+                const cancellation = await reader.cancel().then(() => ({ kind: "cancelled" }), (cause) => ({
+                    kind: "failed",
+                    error: cause instanceof Error ? cause : new Error(String(cause)),
+                }));
+                if (cancellation.kind === "failed") {
+                    throw new AggregateError([error, cancellation.error], "Avatar asset read and cancellation failed", { cause: error });
+                }
+                throw error;
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            return {
+                url: url.href,
+                bytes,
+                contentType: response.headers.get("content-type") ?? "application/octet-stream",
+            };
+        };
+    };
+}

package/dist/avatar.d.ts

@@ -0,0 +1,152 @@
+import * as z from "zod";
+import type { Control } from "./controls.js";
+/**
+ * The closed v1 catalog of avatar characters. Adding a character is a new
+ * major version; this list is not meant to grow silently.
+ */
+export declare const avatarCharacters: readonly ["mushroom", "cat", "burger"];
+/** One character in the closed v1 avatar catalog. */
+export type AvatarCharacter = (typeof avatarCharacters)[number];
+/** A saved `agentColors` preference: shift an Agent's identity, or copy it. */
+export declare const agentColorsSchema: z.ZodEnum<{
+    shift: "shift";
+    keep: "keep";
+}>;
+/** Whether an Agent created from a member's avatar wears a shifted identity. */
+export type AgentColors = z.infer<typeof agentColorsSchema>;
+/**
+ * The Avatar v1 envelope: a closed character, up to 16 appearance values, a
+ * resting expression, and a render style. It is a complete snapshot, not a
+ * reference into character data, so it survives a later change to the
+ * catalog. This checks shape only; it does not know a character's real
+ * controls or expressions, so a bound catalog cannot validate against it by
+ * name alone. `createAvatarSchema`/`parseAvatar` build the catalog-refined
+ * schema a caller should actually parse untrusted data with; `sprite-zdog`'s
+ * `avatarSchema` is that schema, bound to the built-in catalog.
+ */
+export declare const avatarEnvelopeSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    character: z.ZodEnum<{
+        mushroom: "mushroom";
+        cat: "cat";
+        burger: "burger";
+    }>;
+    appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    expression: z.ZodString;
+    renderStyle: z.ZodEnum<{
+        plain: "plain";
+        pencil: "pencil";
+        manga: "manga";
+        riso: "riso";
+        halftone: "halftone";
+        blueprint: "blueprint";
+        crt: "crt";
+        watercolor: "watercolor";
+    }>;
+}, z.core.$strict>;
+/** A parsed, envelope-valid Avatar v1 descriptor. */
+export type Avatar = z.infer<typeof avatarEnvelopeSchema>;
+/** Pure per-character facts a catalog owner (e.g. `sprite-zdog`) supplies. */
+export type AvatarCatalogEntry = {
+    /** Every control the character's document declares. */
+    readonly controls: Readonly<Record<string, Control>>;
+    /** Every expression name the character's document declares. */
+    readonly expressions: readonly string[];
+    /** Controls that carry the character's identity colour, in priority order. */
+    readonly identitySlots: readonly string[];
+};
+/** Pure character facts for every avatar character, owned by its renderer. */
+export type AvatarCatalog = Readonly<Record<AvatarCharacter, AvatarCatalogEntry>>;
+/**
+ * Build the full avatar schema for a catalog: the envelope above, refined so
+ * every appearance key is one of the character's controls, every value is
+ * typed by that control, and the expression is one the character declares.
+ */
+export declare function createAvatarSchema(catalog: AvatarCatalog): z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    character: z.ZodEnum<{
+        mushroom: "mushroom";
+        cat: "cat";
+        burger: "burger";
+    }>;
+    appearance: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    expression: z.ZodString;
+    renderStyle: z.ZodEnum<{
+        plain: "plain";
+        pencil: "pencil";
+        manga: "manga";
+        riso: "riso";
+        halftone: "halftone";
+        blueprint: "blueprint";
+        crt: "crt";
+        watercolor: "watercolor";
+    }>;
+}, z.core.$strict>;
+/** Parse an unknown value into a catalog-valid Avatar v1 descriptor. */
+export declare function parseAvatar(data: unknown, catalog: AvatarCatalog): Avatar;
+/** A hexadecimal colour decomposed into hue (degrees), saturation, lightness. */
+export type Hsl = {
+    readonly h: number;
+    readonly s: number;
+    readonly l: number;
+};
+/** Encode HSL (hue in degrees, saturation/lightness in percent) as `#rrggbb`. */
+export declare function hexFromHsl(hue: number, saturation: number, lightness: number): string;
+/** Decode a `#rrggbb` colour into HSL (hue in degrees, saturation/lightness in percent). */
+export declare function hslFromHex(hex: unknown): Hsl;
+/** Shortest angular distance between two hues in degrees, 0 to 180. */
+export declare function hueDistance(a: number, b: number): number;
+/** Lower bound (degrees) every colour-shift step must clear, each direction. */
+export declare const AGENT_HUE_MIN_SHIFT = 40;
+/**
+ * A deterministic FNV-1a hash: the same seed always lands on the same value.
+ * A copy of `@fungi.computer/caps`'s `seedHash` so this package stays free of
+ * a React-package dependency; both must keep computing the same value.
+ */
+export declare function seedHash(seed: string): number;
+/**
+ * The hue-rotation step for `seed`, chosen against `hex`'s own realised
+ * result, not the idealised `hue + step` arithmetic: `shiftHue` rounds to a
+ * `#rrggbb` colour, and re-decoding that colour can land a few tenths of a
+ * degree short of an exact-degree step, which the 40-degree guarantee must
+ * still hold against. A step is only a candidate when rotating `hex` by it
+ * and reading the result's hue back out clears 40 degrees from `hex`'s own
+ * hue. When `avoid` carries other agents' identity hues, the candidate
+ * farthest from all of them (by minimum distance, scored on the same
+ * realised hue) is preferred; ties keep whichever candidate is nearest the
+ * seed's own deterministic default step, so an unconflicted seed keeps its
+ * usual look.
+ */
+export declare function agentHueStep(hex: string, seed: string, avoid?: readonly number[]): number;
+/** Rotate one hex colour's hue by `step` degrees, keeping its saturation and lightness. */
+export declare function shiftHue(hex: string, step: number): string;
+/**
+ * The mushroom's two identity controls for one seed: its cap and cap spots
+ * take a hue from the seed, so an Agent wears the same cap in every list it
+ * appears in. Kept byte-identical to the Sprite seen before avatars existed.
+ */
+export type AgentAppearance = Readonly<{
+    /** Cap colour as a hexadecimal CSS colour. */
+    cap: string;
+    /** Cap spot colour as a hexadecimal CSS colour. */
+    capSpot: string;
+}>;
+/** The pre-avatar mushroom identity colours for `seed`. */
+export declare function agentAppearance(seed: string): AgentAppearance;
+/**
+ * The avatar a Sprite presents when none is stored: the mushroom, in the same
+ * seeded cap colour Agents have always worn, at rest, undecorated. Every
+ * reader falls back to this so an existing Agent's look never changes.
+ */
+export declare function legacyAvatar(seed: string): Avatar;
+/**
+ * Derive an Agent's avatar from its creator's, for a catalog's character.
+ * `"keep"` hands back the member's look unchanged (their Agent is a visible
+ * copy, told apart only by name). `"shift"` resolves the member's full
+ * appearance against the catalog and rotates only the character's identity
+ * slots by one shared hue step, so accessories, face and drawing style carry
+ * over untouched. `avoid` lists hues already worn by the creator's other
+ * Agents so a new one does not land beside them. An achromatic primary
+ * identity colour has no hue to rotate, so its resolved appearance is kept.
+ */
+export declare function deriveAgentAvatar(member: Avatar, agentColors: AgentColors, seed: string, catalog: AvatarCatalog, avoid?: readonly number[]): Avatar;

package/dist/avatar.js

@@ -0,0 +1,228 @@
+import * as z from "zod";
+import { resolveAppearance } from "./controls.js";
+import { renderStyleSchema } from "./render-style.js";
+/**
+ * The closed v1 catalog of avatar characters. Adding a character is a new
+ * major version; this list is not meant to grow silently.
+ */
+export const avatarCharacters = ["mushroom", "cat", "burger"];
+/** A saved `agentColors` preference: shift an Agent's identity, or copy it. */
+export const agentColorsSchema = z.enum(["shift", "keep"]);
+const hexColor = z.string().regex(/^#[0-9a-f]{6}$/i);
+/** Appearance values a v1 avatar may carry: a hex colour, a number, or a flag. */
+const avatarAppearanceValue = z.union([hexColor, z.number(), z.boolean()]);
+const MAX_APPEARANCE_KEYS = 16;
+/**
+ * The Avatar v1 envelope: a closed character, up to 16 appearance values, a
+ * resting expression, and a render style. It is a complete snapshot, not a
+ * reference into character data, so it survives a later change to the
+ * catalog. This checks shape only; it does not know a character's real
+ * controls or expressions, so a bound catalog cannot validate against it by
+ * name alone. `createAvatarSchema`/`parseAvatar` build the catalog-refined
+ * schema a caller should actually parse untrusted data with; `sprite-zdog`'s
+ * `avatarSchema` is that schema, bound to the built-in catalog.
+ */
+export const avatarEnvelopeSchema = z.strictObject({
+    v: z.literal(1),
+    character: z.enum(avatarCharacters),
+    appearance: z
+        .record(z.string().min(1), avatarAppearanceValue)
+        .refine((appearance) => Object.keys(appearance).length <= MAX_APPEARANCE_KEYS, {
+        message: `Avatar appearance cannot exceed ${String(MAX_APPEARANCE_KEYS)} keys`,
+    }),
+    expression: z.string().min(1),
+    renderStyle: renderStyleSchema,
+});
+/**
+ * Build the full avatar schema for a catalog: the envelope above, refined so
+ * every appearance key is one of the character's controls, every value is
+ * typed by that control, and the expression is one the character declares.
+ */
+export function createAvatarSchema(catalog) {
+    return avatarEnvelopeSchema.superRefine((avatar, context) => {
+        const entry = catalog[avatar.character];
+        try {
+            resolveAppearance(entry.controls, avatar.appearance);
+        }
+        catch (error) {
+            context.addIssue({
+                code: "custom",
+                path: ["appearance"],
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (!entry.expressions.includes(avatar.expression)) {
+            context.addIssue({
+                code: "custom",
+                path: ["expression"],
+                message: `Unknown avatar expression for ${avatar.character}: ${avatar.expression}`,
+            });
+        }
+    });
+}
+/** Parse an unknown value into a catalog-valid Avatar v1 descriptor. */
+export function parseAvatar(data, catalog) {
+    return createAvatarSchema(catalog).parse(data);
+}
+/** Encode HSL (hue in degrees, saturation/lightness in percent) as `#rrggbb`. */
+export function hexFromHsl(hue, saturation, lightness) {
+    const s = saturation / 100;
+    const l = lightness / 100;
+    const a = s * Math.min(l, 1 - l);
+    const channel = (offset) => {
+        const k = (offset + hue / 30) % 12;
+        const value = l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+        return Math.round(255 * value)
+            .toString(16)
+            .padStart(2, "0");
+    };
+    return `#${channel(0)}${channel(8)}${channel(4)}`;
+}
+/** Decode a `#rrggbb` colour into HSL (hue in degrees, saturation/lightness in percent). */
+export function hslFromHex(hex) {
+    const parsed = hexColor.parse(hex);
+    const r = Number.parseInt(parsed.slice(1, 3), 16) / 255;
+    const g = Number.parseInt(parsed.slice(3, 5), 16) / 255;
+    const b = Number.parseInt(parsed.slice(5, 7), 16) / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    const delta = max - min;
+    if (delta === 0)
+        return { h: 0, s: 0, l: l * 100 };
+    const s = delta / (1 - Math.abs(2 * l - 1));
+    let h;
+    if (max === r)
+        h = (((g - b) / delta) % 6) * 60;
+    else if (max === g)
+        h = ((b - r) / delta + 2) * 60;
+    else
+        h = ((r - g) / delta + 4) * 60;
+    if (h < 0)
+        h += 360;
+    return { h, s: s * 100, l: l * 100 };
+}
+const normalizeHue = (hue) => ((hue % 360) + 360) % 360;
+/** Shortest angular distance between two hues in degrees, 0 to 180. */
+export function hueDistance(a, b) {
+    const diff = Math.abs(normalizeHue(a) - normalizeHue(b)) % 360;
+    return Math.min(diff, 360 - diff);
+}
+/** Lower bound (degrees) every colour-shift step must clear, each direction. */
+export const AGENT_HUE_MIN_SHIFT = 40;
+/** `agentHueStep`'s deterministic step range has exactly this many values. */
+const SHIFT_RANGE = 281;
+/**
+ * A deterministic FNV-1a hash: the same seed always lands on the same value.
+ * A copy of `@fungi.computer/caps`'s `seedHash` so this package stays free of
+ * a React-package dependency; both must keep computing the same value.
+ */
+export function seedHash(seed) {
+    let hash = 0x811c9dc5;
+    for (const unit of seed) {
+        hash ^= unit.codePointAt(0) ?? 0;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+/**
+ * The hue-rotation step for `seed`, chosen against `hex`'s own realised
+ * result, not the idealised `hue + step` arithmetic: `shiftHue` rounds to a
+ * `#rrggbb` colour, and re-decoding that colour can land a few tenths of a
+ * degree short of an exact-degree step, which the 40-degree guarantee must
+ * still hold against. A step is only a candidate when rotating `hex` by it
+ * and reading the result's hue back out clears 40 degrees from `hex`'s own
+ * hue. When `avoid` carries other agents' identity hues, the candidate
+ * farthest from all of them (by minimum distance, scored on the same
+ * realised hue) is preferred; ties keep whichever candidate is nearest the
+ * seed's own deterministic default step, so an unconflicted seed keeps its
+ * usual look.
+ */
+export function agentHueStep(hex, seed, avoid = []) {
+    const memberHue = hslFromHex(hex).h;
+    const fallbackStep = AGENT_HUE_MIN_SHIFT + (seedHash(seed) % SHIFT_RANGE);
+    const blocked = avoid.map(normalizeHue);
+    const realizedHue = (step) => hslFromHex(shiftHue(hex, step)).h;
+    const clearsMember = (step) => hueDistance(realizedHue(step), memberHue) >= AGENT_HUE_MIN_SHIFT;
+    const avoidScore = (step) => blocked.length === 0
+        ? 0
+        : Math.min(...blocked.map((hue) => hueDistance(realizedHue(step), hue)));
+    let bestStep;
+    let bestScore = -1;
+    let bestDistanceToFallback = Infinity;
+    for (let step = AGENT_HUE_MIN_SHIFT; step <= 360 - AGENT_HUE_MIN_SHIFT; step += 1) {
+        if (!clearsMember(step))
+            continue;
+        const score = avoidScore(step);
+        const distanceToFallback = Math.abs(step - fallbackStep);
+        if (bestStep === undefined ||
+            score > bestScore ||
+            (score === bestScore && distanceToFallback < bestDistanceToFallback)) {
+            bestStep = step;
+            bestScore = score;
+            bestDistanceToFallback = distanceToFallback;
+        }
+    }
+    if (bestStep === undefined)
+        throw new Error(`No colour-shift step clears ${String(AGENT_HUE_MIN_SHIFT)} degrees for ${hex}`);
+    return bestStep;
+}
+/** Rotate one hex colour's hue by `step` degrees, keeping its saturation and lightness. */
+export function shiftHue(hex, step) {
+    const { h, s, l } = hslFromHex(hex);
+    return hexFromHsl(normalizeHue(h + step), s, l);
+}
+/** The pre-avatar mushroom identity colours for `seed`. */
+export function agentAppearance(seed) {
+    const hue = seedHash(seed) % 360;
+    return { cap: hexFromHsl(hue, 68, 72), capSpot: hexFromHsl(hue, 70, 92) };
+}
+/**
+ * The avatar a Sprite presents when none is stored: the mushroom, in the same
+ * seeded cap colour Agents have always worn, at rest, undecorated. Every
+ * reader falls back to this so an existing Agent's look never changes.
+ */
+export function legacyAvatar(seed) {
+    return {
+        v: 1,
+        character: "mushroom",
+        appearance: agentAppearance(seed),
+        expression: "normal",
+        renderStyle: "plain",
+    };
+}
+/**
+ * Derive an Agent's avatar from its creator's, for a catalog's character.
+ * `"keep"` hands back the member's look unchanged (their Agent is a visible
+ * copy, told apart only by name). `"shift"` resolves the member's full
+ * appearance against the catalog and rotates only the character's identity
+ * slots by one shared hue step, so accessories, face and drawing style carry
+ * over untouched. `avoid` lists hues already worn by the creator's other
+ * Agents so a new one does not land beside them. An achromatic primary
+ * identity colour has no hue to rotate, so its resolved appearance is kept.
+ */
+export function deriveAgentAvatar(member, agentColors, seed, catalog, avoid = []) {
+    if (agentColors === "keep")
+        return { ...member };
+    const characterEntry = catalog[member.character];
+    const resolved = resolveAppearance(characterEntry.controls, member.appearance);
+    // Every identity slot whose control is a colour, with its resolved hex
+    // value already parsed (not asserted): the control's declared type is the
+    // contract, not the resolved value's runtime shape.
+    const identityHues = characterEntry.identitySlots.flatMap((slot) => {
+        const control = characterEntry.controls[slot];
+        return control?.type === "color"
+            ? [{ slot, hex: hexColor.parse(resolved[slot]) }]
+            : [];
+    });
+    const primary = identityHues[0];
+    if (!primary || hslFromHex(primary.hex).s === 0)
+        return { ...member, appearance: resolved };
+    const step = agentHueStep(primary.hex, seed, avoid);
+    const shiftedBySlot = new Map(identityHues.map(({ slot, hex }) => [slot, shiftHue(hex, step)]));
+    const appearance = Object.fromEntries(Object.entries(resolved).map(([key, value]) => [
+        key,
+        shiftedBySlot.get(key) ?? value,
+    ]));
+    return { ...member, appearance };
+}