@pieai/swimmer-avatar-kit 0.2.0 → 0.4.0

package/README.md

@@ -20,6 +20,29 @@ React Three Fiber consumers also install compatible React and R3F versions:
 pnpm add react @react-three/fiber
 ```
 
+## Compact portraits
+
+Use the same avatar identity in DOM UI without opening one WebGL context per
+chip. The pure portrait helpers complete the recipe and preserve its palette,
+species, body silhouette, eyes, mouth, facial mark, and dressed state.
+
+```ts
+import {
+  createAvatarPortraitDataUrl,
+  randomRecipe,
+} from "@pieai/swimmer-avatar-kit";
+
+const recipe = randomRecipe("user-42");
+const src = createAvatarPortraitDataUrl(recipe, {
+  size: 96,
+  title: "Ada's avatar",
+});
+```
+
+Use the returned URL in `<img src>`, CSS, canvas, or a native bridge. Use
+`createAvatarPortraitSvg` when the caller needs the raw SVG. Both functions are
+framework-neutral and deterministic; the host still owns storage and alt text.
+
 ## React Three Fiber
 
 ```tsx
@@ -104,7 +127,7 @@ identity policy.
 
 | Entry point | Purpose | Runtime |
 | --- | --- | --- |
-| `@pieai/swimmer-avatar-kit` | Recipes, metadata, build/update/dispose | Three.js |
+| `@pieai/swimmer-avatar-kit` | Recipes, compact portraits, build/update/dispose | Pure SVG + Three.js |
 | `@pieai/swimmer-avatar-kit/materials` | Gloss materials and studio environment | Browser/WebGL |
 | `@pieai/swimmer-avatar-kit/react-three-fiber` | `<Avatar />` adapter | React + R3F |
 

package/dist/avatar.js

@@ -1,6 +1,7 @@
 import { createGlossFace } from "../vendor/kindergrimm/src/gloss/gface.js";
 import { buildGloss } from "../vendor/kindergrimm/src/gloss/grig.js";
 import { completeRecipe, EXPRESSIONS } from "./recipe.js";
+import { withAvatarQuality } from "./kindergrimm-quality.js";
 const expressionIds = new Set(EXPRESSIONS);
 function disposeGeometries(root) {
     const geometries = new Set();
@@ -17,9 +18,9 @@ export function buildAvatar(recipe, options) {
         throw new TypeError("buildAvatar requires a materialFor function.");
     }
     const completedRecipe = completeRecipe(recipe);
-    const built = buildGloss(completedRecipe, {
+    const built = withAvatarQuality(options.quality, () => buildGloss(completedRecipe, {
         materialFor: options.materialFor,
-    });
+    }));
     const life = createGlossFace(built, { gaze: options.gaze ?? true });
     const restY = Number(built.head.userData.restY ?? built.L.cy);
     let elapsedSeconds = 0;

package/dist/avatar.js.map

@@ -1 +1 @@
-{"version":3,"file":"avatar.js","sourceRoot":"","sources":["../src/avatar.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"avatar.js","sourceRoot":"","sources":["../src/avatar.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { buildAvatar } from "./avatar.js";
+export { createAvatarPortraitDataUrl, createAvatarPortraitSvg } from "./portrait.js";
+export type { AvatarPortraitOptions } from "./portrait.js";
 export { assertAvatarRecipe, AVATAR_RECIPE_SCHEMA, AVATAR_RECIPE_VERSION, cloneAvatarRecipe, completeRecipe, createAvatarRecipe, createAvatarRecipeDocument, deserializeAvatarRecipe, EXPRESSIONS, fillRecipe, PALETTES, parseAvatarRecipeDocument, PARTS, randomRecipe, rerollPart, serializeAvatarRecipe, SPECIES, } from "./recipe.js";
-export type { AvatarBounds, AvatarBuildOptions, AvatarBuildStats, AvatarExpression, AvatarHandle, AvatarMaterialFor, AvatarOption, AvatarPaletteOption, AvatarPartRecipe, AvatarRecipe, AvatarRecipeDocument, AvatarRecipeDocumentV1, AvatarSeed, } from "./types.js";
+export type { AvatarBounds, AvatarBuildOptions, AvatarBuildStats, AvatarExpression, AvatarHandle, AvatarMaterialFor, AvatarOption, AvatarPaletteOption, AvatarPartRecipe, AvatarRecipe, AvatarRecipeDocument, AvatarRecipeDocumentV1, AvatarQuality, AvatarSeed, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { buildAvatar } from "./avatar.js";
+export { createAvatarPortraitDataUrl, createAvatarPortraitSvg } from "./portrait.js";
 export { assertAvatarRecipe, AVATAR_RECIPE_SCHEMA, AVATAR_RECIPE_VERSION, cloneAvatarRecipe, completeRecipe, createAvatarRecipe, createAvatarRecipeDocument, deserializeAvatarRecipe, EXPRESSIONS, fillRecipe, PALETTES, parseAvatarRecipeDocument, PARTS, randomRecipe, rerollPart, serializeAvatarRecipe, SPECIES, } from "./recipe.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,uBAAuB,EACvB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,yBAAyB,EACzB,KAAK,EACL,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,OAAO,GACR,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAErF,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,0BAA0B,EAC1B,uBAAuB,EACvB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,yBAAyB,EACzB,KAAK,EACL,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,OAAO,GACR,MAAM,aAAa,CAAC"}

package/dist/kindergrimm-quality.d.ts

@@ -0,0 +1,2 @@
+import type { AvatarQuality } from "./types.js";
+export declare function withAvatarQuality<T>(quality: AvatarQuality | undefined, build: () => T): T;

package/dist/kindergrimm-quality.js

@@ -0,0 +1,28 @@
+// Kindergrimm's runtime is intentionally vendored as JavaScript. Keep its
+// untyped quality hook behind this small, typed adapter rather than leaking a
+// vendor module into the public API or changing the vendor for compatibility.
+// @ts-expect-error The imported donor module has no declaration file by design.
+import * as vendorShape from "../vendor/kindergrimm/src/gloss/gshape.js";
+const shapeQuality = vendorShape;
+const DETAIL_BY_QUALITY = {
+    full: 1,
+    compact: 0.2,
+};
+function detailFor(quality) {
+    if (quality === undefined)
+        return DETAIL_BY_QUALITY.full;
+    if (Object.hasOwn(DETAIL_BY_QUALITY, quality))
+        return DETAIL_BY_QUALITY[quality];
+    throw new RangeError(`Unknown avatar quality: ${String(quality)}`);
+}
+export function withAvatarQuality(quality, build) {
+    const previousDetail = shapeQuality.glossDetail();
+    shapeQuality.setGlossDetail(detailFor(quality));
+    try {
+        return build();
+    }
+    finally {
+        shapeQuality.setGlossDetail(previousDetail);
+    }
+}
+//# sourceMappingURL=kindergrimm-quality.js.map

package/dist/kindergrimm-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kindergrimm-quality.js","sourceRoot":"","sources":["../src/kindergrimm-quality.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,OAAO,KAAK,WAAW,MAAM,2CAA2C,CAAC;AAOzE,MAAM,YAAY,GAAG,WAA+C,CAAC;AACrE,MAAM,iBAAiB,GAAkC;IACvD,IAAI,EAAE,CAAC;IACP,OAAO,EAAE,GAAG;CACb,CAAC;AAEF,SAAS,SAAS,CAAC,OAAkC;IACnD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,iBAAiB,CAAC,IAAI,CAAC;IACzD,IAAI,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC;QAAE,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACjF,MAAM,IAAI,UAAU,CAAC,2BAA2B,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAI,OAAkC,EAAE,KAAc;IACrF,MAAM,cAAc,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;IAClD,YAAY,CAAC,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,OAAO,KAAK,EAAE,CAAC;IACjB,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/dist/portrait.d.ts

@@ -0,0 +1,14 @@
+import type { AvatarRecipe } from "./types.js";
+export interface AvatarPortraitOptions {
+    /** Raster display size. The SVG keeps a 100 × 100 viewBox. */
+    size?: number;
+    /** Optional accessible name embedded as an SVG title. */
+    title?: string;
+}
+/**
+ * Render a deterministic compact portrait from the same completed recipe as
+ * the 3D avatar. The result is pure SVG: no DOM, React, canvas, or WebGL.
+ */
+export declare function createAvatarPortraitSvg(input: AvatarRecipe, options?: AvatarPortraitOptions): string;
+/** A browser-ready data URL for `<img src>`, CSS, canvas, or native bridges. */
+export declare function createAvatarPortraitDataUrl(recipe: AvatarRecipe, options?: AvatarPortraitOptions): string;

package/dist/portrait.js

@@ -0,0 +1,167 @@
+import { completeRecipe, PALETTES } from "./recipe.js";
+const DEFAULT_SIZE = 96;
+const MIN_SIZE = 16;
+const MAX_SIZE = 1024;
+const INK = "#20312d";
+const PAPER = "#fff8e8";
+function escapeXml(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        if (character === "&")
+            return "&amp;";
+        if (character === "<")
+            return "&lt;";
+        if (character === ">")
+            return "&gt;";
+        if (character === '"')
+            return "&quot;";
+        return "&apos;";
+    });
+}
+function paramsFor(recipe, partId) {
+    const value = recipe.parts[partId]?.params;
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringParam(params, key, fallback) {
+    return typeof params[key] === "string" ? params[key] : fallback;
+}
+function booleanParam(params, key) {
+    return params[key] === true;
+}
+function numberParam(params, key, fallback) {
+    const value = params[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function portraitSize(size) {
+    if (size === undefined)
+        return DEFAULT_SIZE;
+    if (!Number.isFinite(size))
+        throw new TypeError("Avatar portrait size must be finite.");
+    return Math.round(Math.min(MAX_SIZE, Math.max(MIN_SIZE, size)));
+}
+function paletteColors(recipe) {
+    const palette = PALETTES.find((candidate) => candidate.id === recipe.palette) ?? PALETTES[0];
+    if (!palette)
+        return ["#cfc6d9", "#7b7bb0", "#f5c48a"];
+    const length = Math.max(1, palette.colors.length);
+    const index = Math.min(recipe.colorIx ?? 0, length - 1);
+    const primary = palette.colors[index] ?? palette.colors[0] ?? "#cfc6d9";
+    return [
+        primary,
+        palette.colors[(index + 1) % length] ?? primary,
+        palette.colors[(index + 2) % length] ?? primary,
+    ];
+}
+function crestMarkup(species, accent, secondary) {
+    if (species === "cat") {
+        return `<path d="M22 32 28 6 44 29ZM56 29 72 6 78 32Z" fill="${accent}" stroke="${INK}" stroke-width="4" stroke-linejoin="round"/><path d="m28 15 4 13h7zm44 0-4 13h-7z" fill="${secondary}"/>`;
+    }
+    if (species === "bunny") {
+        return `<rect x="25" y="2" width="17" height="39" rx="9" fill="${accent}" stroke="${INK}" stroke-width="4" transform="rotate(-7 33.5 21.5)"/><rect x="58" y="2" width="17" height="39" rx="9" fill="${accent}" stroke="${INK}" stroke-width="4" transform="rotate(7 66.5 21.5)"/><path d="M33 10v23M67 10v23" stroke="${secondary}" stroke-width="5" stroke-linecap="round"/>`;
+    }
+    if (species === "bear") {
+        return `<circle cx="25" cy="25" r="14" fill="${accent}" stroke="${INK}" stroke-width="4"/><circle cx="75" cy="25" r="14" fill="${accent}" stroke="${INK}" stroke-width="4"/><circle cx="25" cy="25" r="6" fill="${secondary}"/><circle cx="75" cy="25" r="6" fill="${secondary}"/>`;
+    }
+    if (species === "robot") {
+        return `<path d="M50 23V10" stroke="${INK}" stroke-width="5" stroke-linecap="round"/><circle cx="50" cy="8" r="6" fill="${secondary}" stroke="${INK}" stroke-width="3"/><rect x="22" y="17" width="13" height="15" rx="5" fill="${accent}" stroke="${INK}" stroke-width="4"/><rect x="65" y="17" width="13" height="15" rx="5" fill="${accent}" stroke="${INK}" stroke-width="4"/>`;
+    }
+    if (species === "monster") {
+        return `<path d="M25 31 17 8l23 19m35 4 8-23-23 19" fill="${secondary}" stroke="${INK}" stroke-width="4" stroke-linejoin="round"/>`;
+    }
+    if (species === "slime") {
+        return `<path d="M24 32Q28 8 39 27 50 3 61 27 72 8 76 32Z" fill="${accent}" stroke="${INK}" stroke-width="4" stroke-linejoin="round"/>`;
+    }
+    if (species === "rock") {
+        return `<path d="m30 31 8-21 12 13 11-16 10 24Z" fill="${accent}" stroke="${INK}" stroke-width="4" stroke-linejoin="round"/>`;
+    }
+    if (species === "humanoid") {
+        return `<path d="M21 35Q25 7 50 8t29 27Q67 23 50 28 35 20 21 35Z" fill="${accent}" stroke="${INK}" stroke-width="4"/>`;
+    }
+    return `<path d="m50 5 7 15 17 2-12 12 3 17-15-8-15 8 3-17-12-12 17-2Z" fill="${secondary}" stroke="${INK}" stroke-width="4" stroke-linejoin="round"/>`;
+}
+function headMarkup(body) {
+    if (body === "sphere") {
+        return `<ellipse cx="50" cy="52" rx="36" ry="33" fill="url(#avatar-head)" stroke="${INK}" stroke-width="4"/>`;
+    }
+    if (body === "rock") {
+        return `<path d="M18 35 31 19l26-5 24 17 5 27-15 25-34 3-23-20Z" fill="url(#avatar-head)" stroke="${INK}" stroke-width="4" stroke-linejoin="round"/>`;
+    }
+    if (body === "drop") {
+        return `<path d="M50 13C42 27 16 46 16 63c0 18 14 27 34 27s34-9 34-27C84 46 58 27 50 13Z" fill="url(#avatar-head)" stroke="${INK}" stroke-width="4"/>`;
+    }
+    return `<rect x="14" y="20" width="72" height="67" rx="18" fill="url(#avatar-head)" stroke="${INK}" stroke-width="4"/>`;
+}
+function eyeMarkup(style, wink, secondary) {
+    const left = wink
+        ? `<path d="M29 50q7 7 14 0" fill="none" stroke="${INK}" stroke-width="5" stroke-linecap="round"/>`
+        : eyeShape(style, 36, secondary);
+    return `${left}${eyeShape(style, 64, secondary)}`;
+}
+function eyeShape(style, x, secondary) {
+    if (style === "happy") {
+        return `<path d="M${x - 7} 52q7-8 14 0" fill="none" stroke="${INK}" stroke-width="5" stroke-linecap="round"/>`;
+    }
+    if (style === "sleepy") {
+        return `<path d="M${x - 8} 51q8 5 16 0" fill="none" stroke="${INK}" stroke-width="5" stroke-linecap="round"/>`;
+    }
+    if (style === "box" || style === "slab") {
+        return `<rect x="${x - 8}" y="43" width="16" height="14" rx="4" fill="${INK}"/><rect x="${x - 3}" y="46" width="6" height="5" rx="2" fill="${secondary}"/>`;
+    }
+    return `<ellipse cx="${x}" cy="50" rx="8" ry="10" fill="${INK}"/><circle cx="${x + 2}" cy="47" r="3" fill="${PAPER}"/>`;
+}
+function mouthMarkup(style, secondary) {
+    if (style === "flat") {
+        return `<path d="M42 69h16" stroke="${INK}" stroke-width="5" stroke-linecap="round"/>`;
+    }
+    if (style === "zig") {
+        return `<path d="m38 68 7-5 6 8 6-8 6 5" fill="none" stroke="${INK}" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>`;
+    }
+    if (style === "cat") {
+        return `<path d="M50 64v4m0 0q-8 8-13 0m13 0q8 8 13 0" fill="none" stroke="${INK}" stroke-width="4" stroke-linecap="round"/>`;
+    }
+    if (style === "grin") {
+        return `<path d="M36 64q14 18 28 0Z" fill="${PAPER}" stroke="${INK}" stroke-width="4" stroke-linejoin="round"/><path d="M43 67v6m7-7v10m7-9v6" stroke="${secondary}" stroke-width="2"/>`;
+    }
+    return `<path d="M38 65q12 13 24 0" fill="none" stroke="${INK}" stroke-width="5" stroke-linecap="round"/>`;
+}
+function markMarkup(style, side, secondary) {
+    const x = side < 0 ? 28 : 72;
+    if (style === "spot") {
+        return `<circle cx="${x}" cy="35" r="9" fill="${secondary}" opacity=".72"/>`;
+    }
+    if (style === "scar") {
+        return `<path d="m${x - 5} 35 10 16m-9-10 7-4m-4 10 7-4" stroke="${secondary}" stroke-width="3" stroke-linecap="round"/>`;
+    }
+    if (style === "sutures") {
+        return `<path d="m${x - 7} 35 14 17m-11-12 7-4m-3 9 7-4m-3 9 6-3" stroke="${secondary}" stroke-width="3" stroke-linecap="round"/>`;
+    }
+    return "";
+}
+/**
+ * Render a deterministic compact portrait from the same completed recipe as
+ * the 3D avatar. The result is pure SVG: no DOM, React, canvas, or WebGL.
+ */
+export function createAvatarPortraitSvg(input, options = {}) {
+    const recipe = completeRecipe(input);
+    const size = portraitSize(options.size);
+    const species = recipe.species ?? "wildcard";
+    const body = recipe.body ?? "cube";
+    const [primary, accent, secondary] = paletteColors(recipe);
+    const eyeParams = paramsFor(recipe, "eyes");
+    const mouthParams = paramsFor(recipe, "mouth");
+    const markParams = paramsFor(recipe, "mark");
+    const frameParams = paramsFor(recipe, "frame");
+    const eyeStyle = stringParam(eyeParams, "style", "bead");
+    const mouthStyle = stringParam(mouthParams, "style", "smile");
+    const markStyle = stringParam(markParams, "style", "none");
+    const markSide = numberParam(markParams, "side", 1);
+    const dressed = booleanParam(frameParams, "dressed");
+    const title = options.title ? `<title>${escapeXml(options.title)}</title>` : "";
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 100 100" role="img" data-avatar-seed="${recipe.seed}" data-avatar-species="${escapeXml(species)}" data-avatar-palette="${escapeXml(recipe.palette ?? "unknown")}">${title}<defs><linearGradient id="avatar-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="${secondary}"/><stop offset="1" stop-color="${accent}"/></linearGradient><linearGradient id="avatar-head" x1="0" y1="0" x2=".75" y2="1"><stop stop-color="${PAPER}" stop-opacity=".58"/><stop offset=".18" stop-color="${primary}"/><stop offset="1" stop-color="${accent}"/></linearGradient></defs><rect width="100" height="100" rx="50" fill="url(#avatar-bg)"/><circle cx="50" cy="49" r="44" fill="${PAPER}" opacity=".46"/><ellipse cx="50" cy="88" rx="30" ry="6" fill="${INK}" opacity=".2"/>${crestMarkup(species, accent, secondary)}${dressed ? `<path d="M25 86q25-18 50 0v10H25Z" fill="${secondary}" stroke="${INK}" stroke-width="4"/>` : ""}${headMarkup(body)}${markMarkup(markStyle, markSide, secondary)}${eyeMarkup(eyeStyle, booleanParam(eyeParams, "wink"), secondary)}${mouthMarkup(mouthStyle, secondary)}<path d="M28 31q18-13 39-2" fill="none" stroke="${PAPER}" stroke-width="5" stroke-linecap="round" opacity=".48"/></svg>`;
+}
+/** A browser-ready data URL for `<img src>`, CSS, canvas, or native bridges. */
+export function createAvatarPortraitDataUrl(recipe, options = {}) {
+    return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(createAvatarPortraitSvg(recipe, options))}`;
+}
+//# sourceMappingURL=portrait.js.map

package/dist/portrait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portrait.js","sourceRoot":"","sources":["../src/portrait.ts"],"names":[],"mappings":"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"}

package/dist/react-three-fiber.d.ts

@@ -1,16 +1,18 @@
 import { type ThreeElements } from "@react-three/fiber";
 import type { Group } from "three";
 import { type AvatarMaterialLibrary } from "./materials.js";
-import type { AvatarHandle, AvatarRecipe } from "./types.js";
+import type { AvatarHandle, AvatarQuality, AvatarRecipe } from "./types.js";
 export type AvatarProps = Omit<ThreeElements["group"], "children" | "ref"> & {
     recipe: AvatarRecipe;
     gaze?: boolean;
+    quality?: AvatarQuality;
     materialLibrary?: AvatarMaterialLibrary;
     onBuilt?: (avatar: AvatarHandle) => void;
 };
 export declare const Avatar: import("react").ForwardRefExoticComponent<Omit<import("@react-three/fiber/dist/declarations/src/core/utils.js").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils.js").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils.js").Overwrite<Group<import("three").Object3DEventMap>, import("@react-three/fiber").MathProps<Group<import("three").Object3DEventMap>> & import("@react-three/fiber").ReactProps<Group<import("three").Object3DEventMap>> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<Group<import("three").Object3DEventMap>, typeof Group>, "object">>>, "children" | "ref"> & {
     recipe: AvatarRecipe;
     gaze?: boolean;
+    quality?: AvatarQuality;
     materialLibrary?: AvatarMaterialLibrary;
     onBuilt?: (avatar: AvatarHandle) => void;
 } & import("react").RefAttributes<AvatarHandle>>;

package/dist/react-three-fiber.js

@@ -3,7 +3,7 @@ import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef, us
 import { useFrame, useThree } from "@react-three/fiber";
 import { buildAvatar } from "./avatar.js";
 import { acquireStudioMaterialLibrary } from "./materials.js";
-export const Avatar = forwardRef(function Avatar({ recipe, gaze = true, materialLibrary, onBuilt, ...groupProps }, forwardedRef) {
+export const Avatar = forwardRef(function Avatar({ recipe, gaze = true, quality, materialLibrary, onBuilt, ...groupProps }, forwardedRef) {
     const { gl } = useThree();
     const [ownedLibrary, setOwnedLibrary] = useState(null);
     const [avatar, setAvatar] = useState(null);
@@ -29,6 +29,7 @@ export const Avatar = forwardRef(function Avatar({ recipe, gaze = true, material
             return;
         const next = buildAvatar(recipe, {
             gaze,
+            ...(quality === undefined ? {} : { quality }),
             materialFor: activeLibrary.materialFor,
         });
         avatarRef.current = next;
@@ -42,7 +43,7 @@ export const Avatar = forwardRef(function Avatar({ recipe, gaze = true, material
             setObject(null);
             next.dispose();
         };
-    }, [activeLibrary, gaze, recipe]);
+    }, [activeLibrary, gaze, quality, recipe]);
     useFrame((_, deltaSeconds) => {
         avatarRef.current?.update(deltaSeconds);
     });

package/dist/react-three-fiber.js.map

@@ -1 +1 @@
-{"version":3,"file":"react-three-fiber.js","sourceRoot":"","sources":["../src/react-three-fiber.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"react-three-fiber.js","sourceRoot":"","sources":["../src/react-three-fiber.tsx"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -14,6 +14,8 @@ export interface AvatarRecipe {
     parts: Record<string, AvatarPartRecipe>;
 }
 export type AvatarSeed = number | string;
+/** Geometry density for a rendered avatar; the recipe and silhouette stay the same. */
+export type AvatarQuality = "full" | "compact";
 export type AvatarExpression = "idle" | "happy" | "angry" | "sad" | "surprised";
 export interface AvatarOption {
     id: string;
@@ -41,6 +43,8 @@ export interface AvatarBounds {
 export interface AvatarBuildOptions {
     materialFor: AvatarMaterialFor;
     gaze?: boolean;
+    /** Defaults to `full` for backwards-compatible high-detail output. */
+    quality?: AvatarQuality;
 }
 export interface AvatarHandle {
     readonly object: Group;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pieai/swimmer-avatar-kit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shared procedural 3D avatar recipes, Three.js runtime, and React Three Fiber adapter for PieAI products.",
   "keywords": [
     "avatar",
@@ -24,8 +24,8 @@
     "vendor",
     "README.md",
     "NOTICE.md",
-    "UPSTREAM.md",
-    "upstream-lock.json",
+    "donors-individual.md",
+    "donors-individual-lock.json",
     "LICENSE"
   ],
   "type": "module",
@@ -52,8 +52,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@pieai/doc-gov": "0.9.3",
-    "@pieai/pro-gov": "0.9.3",
+    "@pieai/doc-gov": "0.9.9",
+    "@pieai/pro-gov": "0.9.9",
     "@react-three/fiber": "9.6.1",
     "@types/node": "24.13.2",
     "@types/react": "19.2.17",
@@ -92,7 +92,7 @@
     "test:package-consumer": "node scripts/test-package-consumer.mjs",
     "host-links:check": "node scripts/verify-host-links.mjs",
     "vendor:verify": "node scripts/verify-vendor.mjs",
-    "upstream:check": "node scripts/check-upstream.mjs",
+    "donors-individual:check": "node scripts/check-donors-individual.mjs",
     "verify": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm vendor:verify && pnpm test && pnpm build",
     "verify:release": "pnpm verify && pnpm docs:check && pnpm test:package-consumer",
     "doc-gov": "doc-gov",

package/UPSTREAM.md

@@ -1,47 +0,0 @@
-# Kindergrimm Upstream Maintenance
-
-SwimmerAvatarKit owns the stable product contract; Kindergrimm remains the art
-generator upstream. An upstream change is never merged automatically.
-
-## Check for updates
-
-```bash
-pnpm upstream:check
-```
-
-The command compares the pinned commit in `upstream-lock.json` with the current
-tip of Kindergrimm's `main` branch. It exits successfully when they match and
-fails with both commit IDs when review is needed. The scheduled GitHub workflow
-runs the same read-only check weekly.
-
-## Review and import an update
-
-1. Clone Kindergrimm into a temporary directory and check out the candidate
-   commit. Do not add it as a mutable Git submodule.
-2. Review the full range from the pinned commit to the candidate, especially
-   `src/gloss/**`, `src/rng.js`, recipe shape, material callback arguments,
-   returned rig fields, and browser-only API use.
-3. Replace only the imported dependency closure under
-   `vendor/kindergrimm/`. Keep `src/gloss/gloss.js` and
-   `src/gloss/gcrowd.js` excluded unless the package contract deliberately
-   changes.
-4. Do not repair compatibility inside vendored JavaScript. Adapt the typed
-   boundary under `src/**` and add regression tests.
-5. Update the commit metadata and Git blob hashes in `upstream-lock.json`, then
-   run `pnpm vendor:verify` before any other test.
-6. Run `pnpm verify`, `pnpm docs:check`, and inspect `pnpm pack --dry-run`.
-7. Choose semver from the public package impact, not from the upstream commit
-   label. A compatible art/bug refresh is normally a patch; changed recipes or
-   APIs may require a minor or major release.
-8. Merge the reviewed package change, then publish only through the trusted
-   GitHub Actions workflow. Products upgrade to that released version in their
-   own PRs.
-
-This creates a deliberate two-step buffer:
-
-```text
-Kindergrimm update -> reviewed SwimmerAvatarKit release -> product dependency update
-```
-
-An upstream bug fix can therefore be adopted quickly without giving an
-unreviewed external commit authority over every PieAI product.

package/upstream-lock.json

@@ -1,38 +0,0 @@
-{
-  "schemaVersion": 1,
-  "repository": "https://github.com/albertobeiz/kindergrimm.git",
-  "defaultBranch": "main",
-  "commit": "811214c6dd5de18cc20335cd3d4ab0a06e45ffd4",
-  "commitDate": "2026-08-21T12:51:30+02:00",
-  "importedAt": "2026-08-22",
-  "license": "Unlicense",
-  "excludedEntrypoints": ["src/gloss/gcrowd.js", "src/gloss/gloss.js"],
-  "files": {
-    "LICENSE": "c290d5a44ba844c2aa271e3be836c25176fe1f8b",
-    "src/gloss/catmullClark.js": "3fa76213faa27595836365a451218fb650529fc5",
-    "src/gloss/gface.js": "f0e90be3039ddd93adb06254943985ee1a37e0d4",
-    "src/gloss/gform.js": "c07865a29b7741fa454238a724e330f05f0f0747",
-    "src/gloss/ghair.js": "bfb35aa765415f9d2fe4f14b6dd5cf947ecece4b",
-    "src/gloss/glayout.js": "21667e34b7f486b89608698abe2527a9dc565c26",
-    "src/gloss/gmedia.js": "aef88b617f3f694b1051237055fd5edcd8be546e",
-    "src/gloss/gpalette.js": "31d1fd17decc8a8f779aa06288bf2fe057aec9dd",
-    "src/gloss/gparts/blush.js": "daed9e66e45b918569490be71392858fa5e502ec",
-    "src/gloss/gparts/body.js": "5f15d76362ec47dc24846a3eacb5f5ba6a435484",
-    "src/gloss/gparts/brows.js": "d646a477b73de7e7d0fa4443848aff9d5c328f45",
-    "src/gloss/gparts/crest.js": "fb5470509ff75ad2d03addc4d9ba02109f7f5521",
-    "src/gloss/gparts/eyes.js": "9188e13c0df544620d951ecf5b0dba05b59ab55b",
-    "src/gloss/gparts/frame.js": "957727c53a6f9f9c4bd95399378ae3cdaa5a1423",
-    "src/gloss/gparts/hair.js": "b962f6fe0e30bbed537054b4fa0d6193052e5b87",
-    "src/gloss/gparts/hat.js": "27fbc817ab9797dd706bde93913dccbdfebb2c48",
-    "src/gloss/gparts/index.js": "82fc74c3c2cec69e11b28bfebbdee2df60dc3052",
-    "src/gloss/gparts/mark.js": "046143fdedab6bc03c0e7495338b342cef5c4fc9",
-    "src/gloss/gparts/mouth.js": "1d6cdcb271b002b37469c985517764aed1647091",
-    "src/gloss/gparts/nose.js": "82683b6bda2bb2fcae9b833686aaf9a10c039e52",
-    "src/gloss/gparts/specs.js": "780de9e2584f68eb34c199756c1fc045187f0159",
-    "src/gloss/grig.js": "2bc489a2bf05d9299a56bca808522a9e2f5fdf49",
-    "src/gloss/gshape.js": "c44e0b43ddfebef130d7ec8d6be26f4e9b4e7448",
-    "src/gloss/gspecies.js": "1805c18339956068354a6c85c1ca93d39e1758f1",
-    "src/gloss/gtexture.js": "00a4c3ddc46496357f7232ea6f68ff537a432697",
-    "src/rng.js": "5a6e8fe001552cf8ae860d70318e1c85da58baec"
-  }
-}