@botharness/pixel-avatar 0.8.0 → 0.9.0

package/README.md

@@ -25,5 +25,6 @@ const svg = pixelAvatarSvg(recipe); // 32×32 viewBox, crisp edges, no ids or sc
 - `REPLACE_PART_SLOTS`, `replacePartStart(recipe, slot)`: drawn `outfit`, `accessory`, `beard`, `glasses`, `nose`, `cheeks`, `petals` and `flowerBase` parts (front layer only). A drawn part replaces the built-in part pixel for pixel in the layer that part paints into, while the built-in choice stays saved underneath. `replacePartStart` flattens the worn built-in part for this recipe: pixels that are exactly an appearance color at a tone become that color slot, and the rest become fixed colors, so an unchanged copy renders identically. Drawn face parts never cover the speaking mouth, and drawn parts are hidden wherever the species or headwear hides the built-in part. A drawn accessory replacing a helmet or hood no longer hides the hair.
 - `emptyPartLayer`, `paintPartLayer`, `fillPartLayer`, `mirrorPartX`, `partLayer`, `partCells`, `createCustomPart`: drawing on dense layers, with pencil and eraser strokes, 4-connected flood fill and mirroring across the Avatar centerline.
 - `partLinePoints`, `partRectPoints`, `gradientPartLayer`, `ditherThreshold`, `noisePartLayer`, `shadePartLayer`: line (with 0°/45°/90° snap), rectangle (with square), tone gradient with 4×4 or 2×2 ordered dithering inside the start region, seeded ±1 tone noise, and a shade stroke that moves each colored cell one tone. All mirror, and all produce ordinary cells: the seed and the tool are not part of the part.
+- `AVATAR_PIECE_COLORS_V4`, `AVATAR_STRANDS`, `AVATAR_HEADPIECES`, `withPieces`, `withBuiltInHeadpiece`, `builtInHeadpiece`, `headpieceStart`: asset version 4. Bangs, back hair and a single `strand` each take an optional color (`bangsColor`, `backHairColor`, `strandColor`) that defaults to `hairColor`, like the side hair colors. The headpiece slot holds a built-in headpiece (ears, horns, halo or small head wings) or a Custom Part, worn together with any accessory. The base sits behind the hair and the rest in front, and the far side hides when the head turns. `withPieces` upgrades a recipe when the Human edits and moves an accessory that is now a headpiece into the empty headpiece slot. Saved recipes are never migrated on their own, so they keep rendering as before. `headpieceStart` flattens the worn headpiece into a Custom Part to start drawing from.
 - `faceCells`, `pixelSymbolCells`, `symbolArtCells`: pixels for [`@botharness/pixel-morph`](../morph).
 - `pixelAvatarSvg(recipe, { turns, classPrefix })`: optional pre-rendered head turns, and rig layer classes (`<prefix>-body`, `-head`, `-face`, `-gaze`, `-blink`) for CSS animation.

package/dist/index.d.ts

@@ -39,6 +39,22 @@ type AvatarSpecies = (typeof AVATAR_SPECIES)[number];
 /** Optional per-piece hair colors (asset version 2); an absent piece uses `hairColor`. */
 declare const AVATAR_PIECE_COLORS: readonly ["leftSideHairColor", "rightSideHairColor"];
 type AvatarPieceColor = (typeof AVATAR_PIECE_COLORS)[number];
+/**
+ * Asset version 4 adds a color for every other hair piece; an absent piece uses `hairColor`.
+ * `strandColor` colors the single strand (`strand`).
+ */
+declare const AVATAR_PIECE_COLORS_V4: readonly ["bangsColor", "backHairColor", "strandColor"];
+type AvatarPieceColorV4 = (typeof AVATAR_PIECE_COLORS_V4)[number];
+/** A single strand of hair standing up from the crown (asset version 4). */
+declare const AVATAR_STRANDS: readonly ["ahoge", "curl", "double"];
+type AvatarStrand = (typeof AVATAR_STRANDS)[number];
+/**
+ * Built-in headpieces (asset version 4), worn in the headpiece slot alongside an accessory and
+ * drawn partly behind the hair. The first five were accessories in earlier versions.
+ */
+declare const AVATAR_HEADPIECES: readonly ["catears", "bunnyears", "horseears", "horns", "halo", "wings"];
+type AvatarHeadpiece = (typeof AVATAR_HEADPIECES)[number];
+type V4Key = AvatarPieceColorV4 | 'strand';
 /** Part choices that exist only in asset version 2, added after every version 1 choice. */
 declare const AVATAR_PARTS_V2: {
   readonly outfit: readonly ["tee", "shirttie", "hoodie", "turtleneck", "sailor", "blazer", "overalls", "dress", "kimono", "cardigan", "maid", "jacket", "armor", "robe", "tunic", "cloak"];
@@ -72,7 +88,7 @@ type PixelAvatarRecipeV1 = Meta & {
 } & { [P in AvatarPart]: (typeof AVATAR_PARTS)[P][number] } & { [P in AvatarHairPart]?: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]?: number } & {
   species?: never;
   rightSideHair?: never;
-} & { [P in AvatarPieceColor | AvatarExtraPart]?: never } & { [P in CustomPartKey]?: never };
+} & { [P in AvatarPieceColor | AvatarExtraPart]?: never } & { [P in CustomPartKey]?: never } & { [P in V4Key]?: never };
 /**
  * Asset version 2: a species, the full split hair and geometry, a separate right side hair
  * (`sideHair` is then the left side) and optional per-side hair colors.
@@ -82,7 +98,7 @@ type PixelAvatarRecipeV2 = Meta & {
 } & { [P in AvatarPart]: (typeof AVATAR_PARTS_V2)[P][number] } & { [P in AvatarHairPart]: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]: number } & {
   species: AvatarSpecies;
   rightSideHair: (typeof AVATAR_HAIR_PARTS)['sideHair'][number];
-} & { [P in AvatarPieceColor]?: string } & { [P in AvatarExtraPart]?: (typeof AVATAR_EXTRA_PARTS)[P][number] } & { [P in CustomPartKey]?: never };
+} & { [P in AvatarPieceColor]?: string } & { [P in AvatarExtraPart]?: (typeof AVATAR_EXTRA_PARTS)[P][number] } & { [P in CustomPartKey]?: never } & { [P in V4Key]?: never };
 /** The recipe key that embeds the Custom Part worn in each slot. */
 declare const CUSTOM_PART_KEYS: {
   readonly headpiece: "headpiece";
@@ -107,7 +123,18 @@ type CustomPartKey = (typeof CUSTOM_PART_KEYS)[PartSlot];
 type PixelAvatarRecipeV3 = Omit<PixelAvatarRecipeV2, 'assetVersion' | CustomPartKey> & {
   assetVersion: 3;
 } & { [P in CustomPartKey]?: PixelCustomPart };
-type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+/**
+ * Asset version 4: version 2 with a color for every hair piece, a single `strand`, and the
+ * headpiece slot holding either a built-in headpiece or a Custom Part, with any number of
+ * Custom Parts worn (none included).
+ */
+type PixelAvatarRecipeV4 = Omit<PixelAvatarRecipeV2, 'assetVersion' | CustomPartKey | V4Key> & {
+  assetVersion: 4;
+} & { [P in Exclude<CustomPartKey, 'headpiece'>]?: PixelCustomPart } & {
+  headpiece?: PixelCustomPart | AvatarHeadpiece;
+  strand?: AvatarStrand;
+} & { [P in AvatarPieceColorV4]?: string };
+type PixelAvatarRecipe = PixelAvatarRecipeV1 | PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
 declare const DEFAULT_RECIPE: PixelAvatarRecipeV1;
 declare function isPixelAvatarRecipe(value: unknown): value is PixelAvatarRecipe;
 declare function canonicalRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
@@ -123,16 +150,29 @@ declare function hiddenChoices(recipe: PixelAvatarRecipe): readonly string[];
  * When the skin color is one of the previous species' suggested colors, it moves to the new
  * species' first suggestion; a custom color is kept.
  */
+declare function withSpecies(recipe: PixelAvatarRecipeV4, species: AvatarSpecies): PixelAvatarRecipeV4;
 declare function withSpecies(recipe: PixelAvatarRecipeV3, species: AvatarSpecies): PixelAvatarRecipeV3;
 declare function withSpecies(recipe: PixelAvatarRecipeV1 | PixelAvatarRecipeV2, species: AvatarSpecies): PixelAvatarRecipeV2;
-declare function withSpecies(recipe: PixelAvatarRecipe, species: AvatarSpecies): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+declare function withSpecies(recipe: PixelAvatarRecipe, species: AvatarSpecies): PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
 /**
  * Returns the recipe wearing `part` in `slot`, or with that slot's part taken off. The recipe
- * embeds its own copy; it is asset version 3 while it wears any part and version 2 otherwise.
+ * embeds its own copy; it is asset version 3 while it wears any part and version 2 otherwise,
+ * and a version 4 recipe stays version 4.
  */
-declare function withCustomPart(recipe: PixelAvatarRecipe, slot: PartSlot, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+declare function withCustomPart(recipe: PixelAvatarRecipeV4, slot: PartSlot, part: PixelCustomPart | undefined): PixelAvatarRecipeV4;
+declare function withCustomPart(recipe: PixelAvatarRecipe, slot: PartSlot, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
+/**
+ * Returns the recipe as asset version 4, keeping every choice. An accessory that is now a
+ * headpiece moves into the empty headpiece slot, freeing the accessory slot; call this only when
+ * the Human edits, so saved recipes keep rendering as they were.
+ */
+declare function withPieces(recipe: PixelAvatarRecipe): PixelAvatarRecipeV4;
+/** Returns the recipe as asset version 4 wearing a built-in headpiece, or none. */
+declare function withBuiltInHeadpiece(recipe: PixelAvatarRecipe, headpiece: AvatarHeadpiece | undefined): PixelAvatarRecipeV4;
+/** The built-in headpiece worn, if any. */
+declare function builtInHeadpiece(recipe: PixelAvatarRecipe): AvatarHeadpiece | undefined;
 /** `withCustomPart` for the headpiece slot. */
-declare function withHeadpiece(recipe: PixelAvatarRecipe, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3;
+declare function withHeadpiece(recipe: PixelAvatarRecipe, part: PixelCustomPart | undefined): PixelAvatarRecipeV2 | PixelAvatarRecipeV3 | PixelAvatarRecipeV4;
 /** The Custom Part worn in a slot, if any. */
 declare function wornPart(recipe: PixelAvatarRecipe, slot: PartSlot): PixelCustomPart | undefined;
 declare function detailedRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
@@ -330,6 +370,16 @@ declare function hairPieceStart(recipe: PixelAvatarRecipe, slot: HairPartSlot):
   front: PartCell[];
   back: PartCell[];
 };
+/**
+ * The headpiece as a Custom Part to start drawing from: the drawn headpiece worn, or the
+ * built-in headpiece flattened for this recipe in the front pose, its base on the back layer and
+ * the rest on the front layer, so an unchanged copy renders identically facing front.
+ */
+declare function headpieceStart(recipe: PixelAvatarRecipe): {
+  slot: 'headpiece';
+  front: PartCell[];
+  back: PartCell[];
+};
 /**
  * The part in a replacement slot as a Custom Part to start drawing from: the drawn part worn
  * there, or the built-in part flattened for this recipe in the front pose. Each pixel becomes a
@@ -391,5 +441,5 @@ declare function pixelSymbolCells(symbol: PixelSymbol, color: string): PixelCell
  */
 declare function symbolArtCells(rows: readonly string[], color: string): PixelCell$1[];
 //#endregion
-export { AVATAR_COLORS, AVATAR_EXTRA_PARTS, AVATAR_HAIR_PARTS, AVATAR_PARTS, AVATAR_PARTS_V2, AVATAR_PIECE_COLORS, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SPECIES, AVATAR_SPECIES_SWATCHES, AVATAR_SWATCHES, AVATAR_TURNS, type AvatarColor, type AvatarExtraPart, type AvatarHairPart, type AvatarPart, type AvatarPieceColor, type AvatarRange, type AvatarSpecies, CUSTOM_PART_KEYS, type CustomPartKey, DEFAULT_RECIPE, HAIR_PART_SLOTS, type HairPartSlot, MAX_PART_FIXED_COLORS, PART_LAYERS, PART_SLOTS, PART_TONES, PIXEL_SYMBOLS, type PartCell, type PartColor, type PartInk, type PartLayer, type PartLayerName, type PartSlot, type PartTone, type PixelAvatarRecipe, type PixelAvatarRecipeV1, type PixelAvatarRecipeV2, type PixelAvatarRecipeV3, type PixelAvatarSvgOptions, type PixelCell, type PixelCustomPart, type PixelFigureOptions, type PixelGrid, type PixelMouthState, type PixelSymbol, REPLACE_PART_SLOTS, type ReplacePartSlot, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, ditherThreshold, emptyPartLayer, faceCells, fillPartLayer, gradientPartLayer, hairPieceStart, hiddenChoices, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, isReplacePartSlot, mirrorPartX, noisePartLayer, paintPartLayer, partCells, partLayer, partLinePoints, partRectPoints, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, replacePartStart, seededRandom, seededRecipe, seededRecipeV2, shadePartLayer, symbolArtCells, withCustomPart, withHeadpiece, withSpecies, wornPart };
+export { AVATAR_COLORS, AVATAR_EXTRA_PARTS, AVATAR_HAIR_PARTS, AVATAR_HEADPIECES, AVATAR_PARTS, AVATAR_PARTS_V2, AVATAR_PIECE_COLORS, AVATAR_PIECE_COLORS_V4, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SPECIES, AVATAR_SPECIES_SWATCHES, AVATAR_STRANDS, AVATAR_SWATCHES, AVATAR_TURNS, type AvatarColor, type AvatarExtraPart, type AvatarHairPart, type AvatarHeadpiece, type AvatarPart, type AvatarPieceColor, type AvatarPieceColorV4, type AvatarRange, type AvatarSpecies, type AvatarStrand, CUSTOM_PART_KEYS, type CustomPartKey, DEFAULT_RECIPE, HAIR_PART_SLOTS, type HairPartSlot, MAX_PART_FIXED_COLORS, PART_LAYERS, PART_SLOTS, PART_TONES, PIXEL_SYMBOLS, type PartCell, type PartColor, type PartInk, type PartLayer, type PartLayerName, type PartSlot, type PartTone, type PixelAvatarRecipe, type PixelAvatarRecipeV1, type PixelAvatarRecipeV2, type PixelAvatarRecipeV3, type PixelAvatarRecipeV4, type PixelAvatarSvgOptions, type PixelCell, type PixelCustomPart, type PixelFigureOptions, type PixelGrid, type PixelMouthState, type PixelSymbol, REPLACE_PART_SLOTS, type ReplacePartSlot, builtInHeadpiece, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, ditherThreshold, emptyPartLayer, faceCells, fillPartLayer, gradientPartLayer, hairPieceStart, headpieceStart, hiddenChoices, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, isReplacePartSlot, mirrorPartX, noisePartLayer, paintPartLayer, partCells, partLayer, partLinePoints, partRectPoints, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, replacePartStart, seededRandom, seededRecipe, seededRecipeV2, shadePartLayer, symbolArtCells, withBuiltInHeadpiece, withCustomPart, withHeadpiece, withPieces, withSpecies, wornPart };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -333,6 +333,33 @@ const AVATAR_SPECIES = [
 ];
 /** Optional per-piece hair colors (asset version 2); an absent piece uses `hairColor`. */
 const AVATAR_PIECE_COLORS = ["leftSideHairColor", "rightSideHairColor"];
+/**
+* Asset version 4 adds a color for every other hair piece; an absent piece uses `hairColor`.
+* `strandColor` colors the single strand (`strand`).
+*/
+const AVATAR_PIECE_COLORS_V4 = [
+	"bangsColor",
+	"backHairColor",
+	"strandColor"
+];
+/** A single strand of hair standing up from the crown (asset version 4). */
+const AVATAR_STRANDS = [
+	"ahoge",
+	"curl",
+	"double"
+];
+/**
+* Built-in headpieces (asset version 4), worn in the headpiece slot alongside an accessory and
+* drawn partly behind the hair. The first five were accessories in earlier versions.
+*/
+const AVATAR_HEADPIECES = [
+	"catears",
+	"bunnyears",
+	"horseears",
+	"horns",
+	"halo",
+	"wings"
+];
 /** Part choices that exist only in asset version 2, added after every version 1 choice. */
 const AVATAR_PARTS_V2 = {
 	...AVATAR_PARTS,
@@ -410,17 +437,22 @@ function isPixelAvatarRecipe(value) {
 	const r = value;
 	const detailed = DETAIL_KEYS.filter((key) => Object.hasOwn(r, key)).length;
 	if (detailed !== 0 && detailed !== DETAIL_KEYS.length) return false;
+	const v4 = r["assetVersion"] === 4;
 	const v3 = r["assetVersion"] === 3;
-	const v2 = r["assetVersion"] === 2 || v3;
-	const worn = PART_KEY_ENTRIES.filter(([, key]) => Object.hasOwn(r, key));
-	if (v3 ? worn.length === 0 : worn.length !== 0) return false;
+	const v2 = r["assetVersion"] === 2 || v3 || v4;
+	const builtInHead = v4 && typeof r["headpiece"] === "string";
+	if (builtInHead && !AVATAR_HEADPIECES.includes(r["headpiece"])) return false;
+	const worn = PART_KEY_ENTRIES.filter(([slot, key]) => Object.hasOwn(r, key) && !(slot === "headpiece" && builtInHead));
+	if (v3 ? worn.length === 0 : !v4 && worn.length !== 0) return false;
+	const newer = [...AVATAR_PIECE_COLORS_V4, "strand"].filter((key) => Object.hasOwn(r, key));
+	if (newer.length !== 0 && (!v4 || !AVATAR_PIECE_COLORS_V4.every((key) => !Object.hasOwn(r, key) || typeof r[key] === "string" && /^#[\da-f]{6}$/iu.test(r[key])) || Object.hasOwn(r, "strand") && !AVATAR_STRANDS.includes(r["strand"]))) return false;
 	for (const [slot, key] of worn) {
 		const part = r[key];
 		if (!isPixelCustomPart(part) || part.slot !== slot) return false;
 	}
 	const pieces = AVATAR_PIECE_COLORS.filter((key) => Object.hasOwn(r, key));
 	const extras = Object.keys(AVATAR_EXTRA_PARTS).filter((key) => Object.hasOwn(r, key));
-	const v2Keys = v2 ? 2 + pieces.length + extras.length + worn.length : 0;
+	const v2Keys = v2 ? 2 + pieces.length + extras.length + worn.length + newer.length + (builtInHead ? 1 : 0) : 0;
 	if (Object.keys(r).length !== Object.keys(DEFAULT_RECIPE).length + detailed + v2Keys) return false;
 	if (v2 && (detailed === 0 || !AVATAR_SPECIES.includes(r["species"]) || !AVATAR_HAIR_PARTS.sideHair.includes(r["rightSideHair"]) || !pieces.every((key) => typeof r[key] === "string" && /^#[\da-f]{6}$/iu.test(r[key])) || !extras.every((key) => AVATAR_EXTRA_PARTS[key].includes(r[key])))) return false;
 	const catalog = v2 ? AVATAR_PARTS_V2 : AVATAR_PARTS;
@@ -445,9 +477,13 @@ function canonicalRecipe(recipe) {
 		canonical["rightSideHair"] = recipe.rightSideHair;
 		for (const key of AVATAR_PIECE_COLORS) if (recipe[key] !== void 0) canonical[key] = recipe[key].toLowerCase();
 		for (const key of Object.keys(AVATAR_EXTRA_PARTS)) if (recipe[key] !== void 0) canonical[key] = recipe[key];
-		if (recipe.assetVersion === 3) for (const [, key] of PART_KEY_ENTRIES) {
+		if (recipe.assetVersion === 3 || recipe.assetVersion === 4) for (const [, key] of PART_KEY_ENTRIES) {
 			const part = recipe[key];
-			if (part !== void 0) canonical[key] = canonicalCustomPart(part);
+			if (part !== void 0) canonical[key] = typeof part === "string" ? part : canonicalCustomPart(part);
+		}
+		if (recipe.assetVersion === 4) {
+			if (recipe.strand !== void 0) canonical["strand"] = recipe.strand;
+			for (const key of AVATAR_PIECE_COLORS_V4) if (recipe[key] !== void 0) canonical[key] = recipe[key].toLowerCase();
 		}
 	}
 	return canonical;
@@ -464,8 +500,12 @@ const HAIR_PIECES = [
 * the species or headwear changes back.
 */
 function hiddenChoices(recipe) {
+	const strand = recipe.strand && (recipe.species === "flower" || recipe.bangs !== "none") ? ["strand"] : [];
+	const bald = recipe.strand && recipe.bangs === "none" ? ["strand"] : [];
 	if (recipe.species === "flower") return [
 		...HAIR_PIECES,
+		...strand,
+		...typeof recipe.headpiece === "string" ? ["headpiece"] : [],
 		"outfit",
 		"accessory",
 		"eyes",
@@ -476,8 +516,9 @@ function hiddenChoices(recipe) {
 		...recipe.beard || wornPart(recipe, "beard") ? ["beard"] : []
 	];
 	const hidden = [];
-	if ((recipe.accessory === "helmet" || recipe.accessory === "hood") && !wornPart(recipe, "accessory")) hidden.push(...HAIR_PIECES);
+	if ((recipe.accessory === "helmet" || recipe.accessory === "hood") && !wornPart(recipe, "accessory")) hidden.push(...HAIR_PIECES, ...strand);
 	if (recipe.species === "dwarf") hidden.push("nose");
+	if (!hidden.includes("strand")) hidden.push(...bald);
 	return hidden;
 }
 function withSpecies(recipe, species) {
@@ -486,16 +527,12 @@ function withSpecies(recipe, species) {
 	const suggested = AVATAR_SPECIES_SWATCHES[previous].includes(recipe.skinColor.toLowerCase());
 	return {
 		...detailed,
-		assetVersion: recipe.assetVersion === 3 ? 3 : 2,
+		assetVersion: recipe.assetVersion === 1 ? 2 : recipe.assetVersion,
 		species,
 		rightSideHair: detailed.rightSideHair ?? detailed.sideHair,
 		skinColor: suggested && previous !== species ? AVATAR_SPECIES_SWATCHES[species][0] : recipe.skinColor
 	};
 }
-/**
-* Returns the recipe wearing `part` in `slot`, or with that slot's part taken off. The recipe
-* embeds its own copy; it is asset version 3 while it wears any part and version 2 otherwise.
-*/
 function withCustomPart(recipe, slot, part) {
 	const base = { ...recipe.assetVersion === 1 ? withSpecies(recipe, "human") : recipe };
 	const key = CUSTOM_PART_KEYS[slot];
@@ -504,19 +541,51 @@ function withCustomPart(recipe, slot, part) {
 		...part,
 		slot
 	});
+	if (recipe.assetVersion === 4) return base;
 	const wearing = PART_KEY_ENTRIES.some(([, k]) => base[k] !== void 0);
 	return {
 		...base,
 		assetVersion: wearing ? 3 : 2
 	};
 }
+const MOVED_HEADPIECES = AVATAR_HEADPIECES;
+/**
+* Returns the recipe as asset version 4, keeping every choice. An accessory that is now a
+* headpiece moves into the empty headpiece slot, freeing the accessory slot; call this only when
+* the Human edits, so saved recipes keep rendering as they were.
+*/
+function withPieces(recipe) {
+	if (recipe.assetVersion === 4) return recipe;
+	const base = {
+		...recipe.assetVersion === 1 ? withSpecies(recipe, "human") : recipe,
+		assetVersion: 4
+	};
+	if (base["headpiece"] === void 0 && MOVED_HEADPIECES.includes(recipe.accessory)) {
+		base["headpiece"] = recipe.accessory;
+		base["accessory"] = "none";
+	}
+	return base;
+}
+/** Returns the recipe as asset version 4 wearing a built-in headpiece, or none. */
+function withBuiltInHeadpiece(recipe, headpiece) {
+	const base = { ...withPieces(recipe) };
+	delete base["headpiece"];
+	if (headpiece !== void 0) base["headpiece"] = headpiece;
+	return base;
+}
+/** The built-in headpiece worn, if any. */
+function builtInHeadpiece(recipe) {
+	return typeof recipe.headpiece === "string" ? recipe.headpiece : void 0;
+}
 /** `withCustomPart` for the headpiece slot. */
 function withHeadpiece(recipe, part) {
 	return withCustomPart(recipe, "headpiece", part);
 }
 /** The Custom Part worn in a slot, if any. */
 function wornPart(recipe, slot) {
-	return recipe.assetVersion === 3 ? recipe[CUSTOM_PART_KEYS[slot]] : void 0;
+	if (recipe.assetVersion !== 3 && recipe.assetVersion !== 4) return void 0;
+	const part = recipe[CUSTOM_PART_KEYS[slot]];
+	return typeof part === "string" ? void 0 : part;
 }
 function detailedRecipe(recipe) {
 	if (recipe.bangs !== void 0) return recipe;
@@ -1659,6 +1728,39 @@ function hair(recipe, s, b) {
 		};
 	}
 }
+const STRANDS = {
+	ahoge: {
+		rows: [
+			"XX.",
+			".XX",
+			".XX"
+		],
+		dx: 0
+	},
+	curl: {
+		rows: [
+			".XX.",
+			"X..X",
+			"..XX",
+			".X.."
+		],
+		dx: -1
+	},
+	double: {
+		rows: [
+			"X...X",
+			".X.X.",
+			".X.X."
+		],
+		dx: -2
+	}
+};
+function strandMask(style, s) {
+	const { rows, dx } = STRANDS[style];
+	const top = 4 - rows.length;
+	const left = Math.round(C + s) + dx;
+	return (x, y) => rows[y - top]?.[x - left] === "X";
+}
 function detailedHair(recipe, s, b) {
 	const of = (style) => hair({
 		...recipe,
@@ -1673,8 +1775,11 @@ function detailedHair(recipe, s, b) {
 	const sideOf = (sign) => (x, y) => y > 7 && sign * (x + .5 - C - s) >= 7 && lengthen((sign < 0 ? side : right).front)(x, y);
 	const fringe = (x, y) => y <= 7 ? bangs.front(x, y) || back.front(x, y) : Math.abs(x + .5 - C - s) < 7 && bangs.front(x, y);
 	const behind = length === 0 ? back.back : lengthen(back.back);
+	const tuft = recipe.strand && recipe.bangs !== "none" ? strandMask(recipe.strand, s) : void 0;
+	const strand = tuft ? (x, y) => tuft(x, y) && !fringe(x, y) && !sideOf(-1)(x, y) && !sideOf(1)(x, y) : void 0;
 	return {
-		front: (x, y) => fringe(x, y) || sideOf(-1)(x, y) || sideOf(1)(x, y),
+		front: (x, y) => fringe(x, y) || sideOf(-1)(x, y) || sideOf(1)(x, y) || (strand?.(x, y) ?? false),
+		...strand ? { strand } : {},
 		sides: [sideOf(-1), sideOf(1)],
 		pieces: {
 			bangs: fringe,
@@ -2019,6 +2124,87 @@ function accessory(recipe, g, s, face) {
 			return;
 	}
 }
+/**
+* A built-in headpiece: the row that meets the head goes behind the hair, the rest in front.
+* Turned, the far side of a pair is hidden, like a turned ear.
+*/
+function drawHeadpiece(style, recipe, behind, front, s, far) {
+	const cx = Math.round(C + s);
+	const pair = (rows, left, right, y, pal, mirror = true) => {
+		const tips = rows.slice(0, -1);
+		if (far >= 0) {
+			sprite(behind, rows, cx + left, y, pal);
+			sprite(front, tips, cx + left, y, pal);
+		}
+		if (far <= 0) {
+			sprite(behind, rows, cx + right, y, pal, mirror);
+			sprite(front, tips, cx + right, y, pal, mirror);
+		}
+	};
+	switch (style) {
+		case "catears":
+			pair([
+				"X...",
+				"XX..",
+				"XPX.",
+				"XXXX"
+			], -9, 5, 2, {
+				X: recipe.hairColor,
+				P: "#f4a3b5"
+			});
+			return;
+		case "bunnyears":
+			pair([
+				"WW",
+				"WP",
+				"WP",
+				"WP",
+				"WW"
+			], -6, 4, 0, {
+				W: "#f4f1ec",
+				P: "#f4a3b5"
+			});
+			return;
+		case "horseears":
+			pair([
+				".X.",
+				"XPX",
+				"XPX",
+				"XXX"
+			], -9, 6, 1, {
+				X: shade(recipe.hairColor, .9),
+				P: "#f4a3b5"
+			}, false);
+			return;
+		case "horns":
+			pair([
+				".H",
+				"HH",
+				"Hh"
+			], -8, 6, 1, {
+				H: "#5b3a6e",
+				h: "#7d5694"
+			});
+			return;
+		case "halo": {
+			const ring = (x, y) => ellipse(C + s, 1.6, 6.5, 1.8)(x, y) && !ellipse(C + s, 1.6, 4.4, .8)(x, y);
+			paint(behind, (x, y) => ring(x, y) && y < 2, GOLD);
+			paint(front, (x, y) => ring(x, y) && y >= 2, GOLD);
+			return;
+		}
+		case "wings":
+			pair([
+				"W..",
+				"WW.",
+				"WwW",
+				".ww"
+			], -13, 10, 7, {
+				W: "#f4f1ec",
+				w: "#cfd6e2"
+			});
+			return;
+	}
+}
 const POINTED_EARS = {
 	goblin: {
 		rows: [
@@ -2205,7 +2391,7 @@ function renderFigure(recipe, yawDeg, options, omit) {
 	};
 	const masks = drawnHair.length === 0 ? builtin : {
 		...builtin,
-		front: (x, y) => piece("bangs")(x, y) || piece("leftSideHair")(x, y) || piece("rightSideHair")(x, y),
+		front: (x, y) => piece("bangs")(x, y) || piece("leftSideHair")(x, y) || piece("rightSideHair")(x, y) || (builtin.strand?.(x, y) ?? false),
 		sides: [piece("leftSideHair"), piece("rightSideHair")],
 		back: piece("backHair"),
 		...drawnHair.some((drawn) => drawn.slot === "backHair") ? { ties: [] } : {}
@@ -2244,6 +2430,9 @@ function renderFigure(recipe, yawDeg, options, omit) {
 	placeCells(back, inked("backHair"), false);
 	overlay(back, "petals");
 	if (headpiece) placeCells(back, headpiece.back);
+	const wornHead = flower ? void 0 : builtInHeadpiece(recipe);
+	const headFront = blank();
+	if (wornHead) drawHeadpiece(wornHead, recipe, back, headFront, s, turned ? d : 0);
 	const head = blank();
 	paint(head, face, skin);
 	const h = recipe.height ?? 0;
@@ -2295,8 +2484,10 @@ function renderFigure(recipe, yawDeg, options, omit) {
 	const shadeHair = (g) => {
 		const out = g.map((r) => [...r]);
 		const cells = g.flatMap((row, y) => row.flatMap((c, x) => c === hairColor ? [[x, y]] : []));
-		const xs = cells.map(([x]) => x);
-		const ys = cells.map(([, y]) => y);
+		const framed = cells.filter(([x, y]) => !builtin.strand?.(x, y));
+		const bounds = framed.length ? framed : cells;
+		const xs = bounds.map(([x]) => x);
+		const ys = bounds.map(([, y]) => y);
 		const left = Math.min(...xs);
 		const right = Math.max(...xs);
 		const top = Math.min(...ys);
@@ -2325,7 +2516,7 @@ function renderFigure(recipe, yawDeg, options, omit) {
 		}
 		const ring = mix$1(hairColor, WHITE, .45);
 		for (let x = Math.round(C + s) - 7; x <= Math.round(C + s) + 3; x++) {
-			const first = g.findIndex((row) => row[x] === hairColor);
+			const first = g.findIndex((row, y) => row[x] === hairColor && !builtin.strand?.(x, y));
 			if (first < 0) continue;
 			const y = first + 2 + Math.round(Math.abs(x + .5 - (C + s - 2)) / 4);
 			if (g[y]?.[x] === hairColor && x % 3 !== 0) out[y][x] = ring;
@@ -2338,6 +2529,7 @@ function renderFigure(recipe, yawDeg, options, omit) {
 	const crown = blank();
 	placeCells(crown, inked("all-front"), false);
 	if (headpiece) placeCells(crown, headpiece.front);
+	for (let y = 0; y < N; y++) for (let x = 0; x < N; x++) if (headFront[y][x]) crown[y][x] = headFront[y][x];
 	const figure = blank();
 	for (const layer of [
 		back,
@@ -2475,17 +2667,42 @@ function renderFigure(recipe, yawDeg, options, omit) {
 		], right.x + right.w, eyeTop + 5, { G: GOLD });
 	}
 	const full = clip(outline(figure));
-	AVATAR_PIECE_COLORS.forEach((key, i) => {
-		const color = recipe[key];
-		const mask = masks.sides?.[i];
-		if (color === void 0 || !mask || color.toLowerCase() === hairColor.toLowerCase()) return;
+	const variants = /* @__PURE__ */ new Map();
+	const recolor = (color) => {
+		const cached = variants.get(color.toLowerCase());
+		if (cached) return cached;
 		const variant = blank();
+		variants.set(color.toLowerCase(), variant);
 		const plain = {
 			...recipe,
 			hairColor: color
 		};
-		for (const k of AVATAR_PIECE_COLORS) delete plain[k];
+		for (const k of [...AVATAR_PIECE_COLORS, ...AVATAR_PIECE_COLORS_V4]) delete plain[k];
 		for (const cell of renderFigure(plain, yawDeg, {}, omit).cells) variant[cell.y][cell.x] = cell.c;
+		return variant;
+	};
+	if (recipe.assetVersion === 4) {
+		const over = (x, y) => !!crown[y]?.[x] || !!drawnOver[y]?.[x] || !!eyes[y]?.[x] || !!glasses[y]?.[x];
+		const hairAt = (x, y) => head[y]?.[x] === hairColor && !over(x, y);
+		const backAt = (x, y) => back[y]?.[x] !== void 0 && figure[y][x] === back[y][x];
+		const owners = [
+			[flower ? void 0 : recipe.backHairColor, (x, y) => masks.back(x, y) && backAt(x, y)],
+			[recipe.leftSideHairColor, (x, y) => !!masks.sides?.[0](x, y) && (hairAt(x, y) || backAt(x, y))],
+			[recipe.rightSideHairColor, (x, y) => !!masks.sides?.[1](x, y) && (hairAt(x, y) || backAt(x, y))],
+			[recipe.bangsColor, (x, y) => (builtin.pieces ? piece("bangs")(x, y) : false) && hairAt(x, y)],
+			[recipe.strandColor, (x, y) => (builtin.strand?.(x, y) ?? false) && hairAt(x, y)]
+		];
+		for (const [color, owns] of owners) {
+			if (color === void 0 || color.toLowerCase() === hairColor.toLowerCase()) continue;
+			const variant = recolor(color);
+			const near = (x, y) => owns(x - 1, y) || owns(x + 1, y) || owns(x, y - 1) || owns(x, y + 1);
+			for (let y = 0; y < N; y++) for (let x = 0; x < N; x++) if (full[y][x] && !over(x, y) && (owns(x, y) || !figure[y][x] && near(x, y))) full[y][x] = variant[y][x];
+		}
+	} else AVATAR_PIECE_COLORS.forEach((key, i) => {
+		const color = recipe[key];
+		const mask = masks.sides?.[i];
+		if (color === void 0 || !mask || color.toLowerCase() === hairColor.toLowerCase()) return;
+		const variant = recolor(color);
 		const near = (x, y) => mask(x, y) || mask(x - 1, y) || mask(x + 1, y) || mask(x, y - 1) || mask(x, y + 1);
 		for (let y = 0; y < N; y++) for (let x = 0; x < N; x++) if (full[y][x] && near(x, y) && !eyes[y][x] && !glasses[y][x]) full[y][x] = variant[y][x];
 	});
@@ -2560,6 +2777,57 @@ function hairPieceStart(recipe, slot) {
 		back: []
 	};
 }
+function cellSource(recipe) {
+	return (c) => {
+		for (const key of AVATAR_COLORS) for (const tone of [
+			0,
+			-1,
+			1,
+			-2,
+			2
+		]) if (TONES[tone](recipe[key].toLowerCase()) === c) return [key, tone];
+		return [c, 0];
+	};
+}
+/**
+* The headpiece as a Custom Part to start drawing from: the drawn headpiece worn, or the
+* built-in headpiece flattened for this recipe in the front pose, its base on the back layer and
+* the rest on the front layer, so an unchanged copy renders identically facing front.
+*/
+function headpieceStart(recipe) {
+	const worn = wornPart(recipe, "headpiece");
+	if (worn) return {
+		slot: "headpiece",
+		front: [...worn.front],
+		back: [...worn.back]
+	};
+	const style = builtInHeadpiece(recipe);
+	const behind = blank();
+	const over = blank();
+	if (style) drawHeadpiece(style, recipe, behind, over, 0, 0);
+	const source = cellSource(recipe);
+	const front = [];
+	const back = [];
+	for (let y = 0; y < 16; y++) for (let x = 0; x < N; x++) {
+		const c = over[y][x];
+		const b = behind[y][x];
+		if (c) front.push([
+			x,
+			y,
+			...source(c)
+		]);
+		if (b && b !== c) back.push([
+			x,
+			y,
+			...source(b)
+		]);
+	}
+	return {
+		slot: "headpiece",
+		front,
+		back
+	};
+}
 /**
 * The part in a replacement slot as a Custom Part to start drawing from: the drawn part worn
 * there, or the built-in part flattened for this recipe in the front pose. Each pixel becomes a
@@ -2577,16 +2845,7 @@ function replacePartStart(recipe, slot) {
 	const layer = slot === "glasses" ? "glasses" : slot === "nose" || slot === "cheeks" ? "features" : slot === "petals" ? "back" : slot === "outfit" || slot === "flowerBase" ? "body" : "figure";
 	const shown = renderFigure(recipe, 0, {}, /* @__PURE__ */ new Set()).grids[layer];
 	const without = renderFigure(recipe, 0, {}, new Set([slot])).grids[layer];
-	const source = (c) => {
-		for (const key of AVATAR_COLORS) for (const tone of [
-			0,
-			-1,
-			1,
-			-2,
-			2
-		]) if (TONES[tone](recipe[key].toLowerCase()) === c) return [key, tone];
-		return [c, 0];
-	};
+	const source = cellSource(recipe);
 	const front = [];
 	for (let y = 0; y < N; y++) for (let x = 0; x < N; x++) {
 		const c = shown[y][x];
@@ -3125,5 +3384,5 @@ function symbolArtCells(rows, color) {
 }
 
 //#endregion
-export { AVATAR_COLORS, AVATAR_EXTRA_PARTS, AVATAR_HAIR_PARTS, AVATAR_PARTS, AVATAR_PARTS_V2, AVATAR_PIECE_COLORS, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SPECIES, AVATAR_SPECIES_SWATCHES, AVATAR_SWATCHES, AVATAR_TURNS, CUSTOM_PART_KEYS, DEFAULT_RECIPE, HAIR_PART_SLOTS, MAX_PART_FIXED_COLORS, PART_LAYERS, PART_SLOTS, PART_TONES, PIXEL_SYMBOLS, REPLACE_PART_SLOTS, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, ditherThreshold, emptyPartLayer, faceCells, fillPartLayer, gradientPartLayer, hairPieceStart, hiddenChoices, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, isReplacePartSlot, mirrorPartX, noisePartLayer, paintPartLayer, partCells, partLayer, partLinePoints, partRectPoints, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, replacePartStart, seededRandom, seededRecipe, seededRecipeV2, shadePartLayer, symbolArtCells, withCustomPart, withHeadpiece, withSpecies, wornPart };
+export { AVATAR_COLORS, AVATAR_EXTRA_PARTS, AVATAR_HAIR_PARTS, AVATAR_HEADPIECES, AVATAR_PARTS, AVATAR_PARTS_V2, AVATAR_PIECE_COLORS, AVATAR_PIECE_COLORS_V4, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SPECIES, AVATAR_SPECIES_SWATCHES, AVATAR_STRANDS, AVATAR_SWATCHES, AVATAR_TURNS, CUSTOM_PART_KEYS, DEFAULT_RECIPE, HAIR_PART_SLOTS, MAX_PART_FIXED_COLORS, PART_LAYERS, PART_SLOTS, PART_TONES, PIXEL_SYMBOLS, REPLACE_PART_SLOTS, builtInHeadpiece, canonicalCustomPart, canonicalRecipe, createCustomPart, createSeededRecipe, createSeededRecipeV2, customPartId, detailedRecipe, ditherThreshold, emptyPartLayer, faceCells, fillPartLayer, gradientPartLayer, hairPieceStart, headpieceStart, hiddenChoices, isHairPartSlot, isPixelAvatarRecipe, isPixelCustomPart, isReplacePartSlot, mirrorPartX, noisePartLayer, paintPartLayer, partCells, partLayer, partLinePoints, partRectPoints, partToneColor, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, replacePartStart, seededRandom, seededRecipe, seededRecipeV2, shadePartLayer, symbolArtCells, withBuiltInHeadpiece, withCustomPart, withHeadpiece, withPieces, withSpecies, wornPart };
 //# sourceMappingURL=index.js.map