@skinhub/viewer 0.3.2 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@skinhub/viewer",
-	"version": "0.3.2",
+	"version": "0.4.2",
 	"description": "React wrapper for the SkinHub CS2 skin viewer embed — props in, postMessage out. No three.js, no renderer, no asset bundle; React is the only peer.",
 	"type": "module",
 	"main": "dist/index.js",
@@ -54,7 +54,7 @@
 		"react": ">=18"
 	},
 	"dependencies": {
-		"@skinhub/cdn": ">=0.1.3"
+		"@skinhub/cdn": ">=0.3.0"
 	},
 	"devDependencies": {
 		"@types/bun": "latest",

package/src/SkinViewer.tsx

@@ -200,8 +200,9 @@ export const SkinViewer = (props: SkinViewerProps) => {
 		 * whose query briefly returned `undefined` - must not record "no item" as the thing the frame is
 		 * showing, or the next real item would be diffed against a hole and sent in full for no reason.
 		 */
+		const previous = sent.current
 		sent.current = { ...next, item: next.item ?? sent.current.item }
-		if (coversCanvas(patch, next)) {
+		if (coversCanvas(patch, next, previous)) {
 			setStatus('loading')
 			// A NEW ITEM IS A NEW CHANCE. A lost GL context or a 404 on one model says nothing about the
 			// next one, so the fallback comes down and the frame is allowed to try. A protocol mismatch is

package/src/index.ts

@@ -6,14 +6,15 @@
  *     <SkinViewer item={{ weapon: 'weapon_ak47', paintIndex: 1449, float: 0.27 }} style={{ height: 420 }} />
  *     <SkinViewer inspectLink={tradeOffer.inspectLink} style={{ height: 420 }} />
  *
- * A weapon (or a glove) is one of SIX ways to name a subject, and each is its own prop:
+ * A weapon (or a glove) is one of SEVEN ways to name a subject, and each is its own prop:
  *
  *     <SkinViewer sticker={{ id: 37, wear: 0.2 }} />        one sticker, the real holo/foil shader
  *     <SkinViewer charm={{ id: 5 }} />                      one charm, off the gun
  *     <SkinViewer collectible={{ id: 874 }} />              one pin, coin, medal or trophy
  *     <SkinViewer operator={{ id: 5036 }} />                one agent, alone
+ *     <SkinViewer pet={{ id: 4, stage: 'hen' }} />          one chicken pet
  *
- * Exactly one of the six, enforced in the types - see `ViewerSubject`.
+ * Exactly one of the seven, enforced in the types - see `ViewerSubject`.
  *
  * The 3D is not in here. It is a page on our origin that this component embeds and drives over
  * `postMessage`, which is why installing this pulls in no `three`, no `@react-three/fiber` and no
@@ -60,6 +61,12 @@ export { fromInspectLink, toInspectLink, toPlacement } from './item.js'
 
 export type {
 	MapName,
+	PetBackdrop,
+	PetEffect,
+	PetHat,
+	PetLook,
+	PetNames,
+	PetStage,
 	SkinViewerCharm,
 	SkinViewerError,
 	SkinViewerErrorCode,
@@ -67,7 +74,6 @@ export type {
 	SkinViewerItem,
 	SkinViewerProps,
 	SkinViewerSticker,
-	TimeOfDay,
 	ViewerAgent,
 	ViewerBackground,
 	ViewerCameraSettings,
@@ -80,6 +86,7 @@ export type {
 	ViewerLocaleSettings,
 	ViewerOperatorSubject,
 	ViewerOverlaySettings,
+	ViewerPetSubject,
 	ViewerQualitySettings,
 	ViewerResize,
 	ViewerSettings,

package/src/item.ts

@@ -37,6 +37,7 @@ import type {
 	FrameCharm,
 	FrameCollectible,
 	FrameItem,
+	FramePet,
 	FrameSticker,
 	FrameSubjectKind,
 	PlacementSlots,
@@ -84,9 +85,13 @@ export const toSlots = (
 			slot,
 			sticker_id: sticker.id,
 			wear: sticker.wear ?? 0,
-			// The game treats an unset scale as 1 and an inspect link cannot carry `scale <= 0`. It is not
-			// on the public surface because nothing in CS2 sets it per sticker.
-			scale: 1,
+			// `scale` is not on the public surface because nothing in CS2 sets it per sticker, and 0 is
+			// how the wire says "no size chosen" - what the protobuf decodes to when the field is
+			// ABSENT, which is every item CS2's own sticker UI has ever made. The frame never reads it
+			// (its `stickerSlots.ts` takes `uvScale` from the weapon's markup and says so on line 9),
+			// and `@skinhub/cdn` >= 0.3.0 omits a non-positive scale from a link rather than refusing
+			// to build one - so a link built here now carries exactly what CS2 would carry.
+			scale: 0,
 			rotation: sticker.rotation ?? 0,
 			offset_x: sticker.offsetX ?? 0,
 			offset_y: sticker.offsetY ?? 0,
@@ -103,6 +108,10 @@ export const toSlots = (
 			offset_x: charm.offset?.[0] ?? 0,
 			offset_y: charm.offset?.[1] ?? 0,
 			offset_z: charm.offset?.[2] ?? 0,
+			// The sticker sealed inside a `Charm | Sticker Slab`. 0 is "nothing sealed", which is every
+			// charm this package can be handed: `SkinViewerCharm` has no field for it, because a slab is
+			// a distinct econ item rather than a property of a charm someone hangs on a gun.
+			wrapped_sticker: 0,
 		}
 
 	return slots
@@ -207,6 +216,7 @@ export type ResolvedStandalone = {
 	sticker?: FrameSticker
 	charm?: FrameCharm
 	collectible?: FrameCollectible
+	pet?: FramePet
 	agent?: { id: number; pose?: string | null }
 	error: SkinViewerError | null
 }
@@ -243,6 +253,37 @@ export const resolveStandalone = (props: Partial<ViewerSubject>): ResolvedStanda
 			? { subject: 'agent', agent: dropUndefined({ id: props.operator.id, pose: props.operator.pose }), error: null }
 			: bad('agent', 'operator', props.operator.id)
 
+	/* A PET CARRIES ITS WHOLE LOOK IN ONE GROUP - stage, colour group, seed, pose and the look sliders -
+	   and only the id is identity. `look` is copied so a host mutating its own object cannot change what
+	   the next diff compares against. */
+	if (props.pet)
+		return ok(props.pet.id)
+			? {
+					subject: 'pet',
+					pet: dropUndefined({
+						id: props.pet.id,
+						stage: props.pet.stage,
+						variant: props.pet.variant,
+						petSeed: props.pet.petSeed,
+						pose: props.pet.pose,
+						look: props.pet.look
+							? {
+									...(props.pet.look.attributes && { attributes: { ...props.pet.look.attributes } }),
+									...(props.pet.look.shape && { shape: { ...props.pet.look.shape } }),
+								}
+							: props.pet.look,
+						// The photo booth and the names (0.4.2). `names` copied for `look`'s reason.
+						hat: props.pet.hat,
+						backdrop: props.pet.backdrop,
+						light: props.pet.light,
+						effect: props.pet.effect,
+						names: props.pet.names ? { ...props.pet.names } : props.pet.names,
+						nameLabel: props.pet.nameLabel,
+					}),
+					error: null,
+				}
+			: bad('pet', 'pet', props.pet.id)
+
 	return null
 }
 
@@ -377,8 +418,10 @@ export const toPublicItem = (item: FrameItem): SkinViewerItem => {
  *
  *   - `stattrak: 0` is a REAL, freshly-minted counter and `false` is no module. One boolean and one
  *     count, not one nullable number.
- *   - an unset sticker `scale` is `1`, not `0`. The WeaponPaints row default is `0` meaning "default",
- *     and an encoder rejects `scale <= 0`, so passing it through produces a link that will not build.
+ *   - an unset sticker `scale` is `0`, meaning "no size chosen", and the encoder OMITS it rather than
+ *     refusing the link. `g_vStickerNScale` is an inverse uv scale authored 4.63..35.0, so 1 was never
+ *     an identity - it is a sticker five to thirty-five times too large, on a field the frame and the
+ *     game both ignore.
  *   - a charm's seed rides in `pattern`, because the keychain message is the sticker message reused.
  *
  * That list is the argument for these living here rather than in a docs snippet: they are the same

package/src/protocol.ts

@@ -134,7 +134,7 @@ export type FrameLocale = {
 export type FrameSettings = {
 	camera?: { fov?: number; defaultZoom?: number }
 	quality?: { bloom?: number; bloomSpill?: number; renderScale?: number; antialias?: boolean; shadows?: boolean }
-	environment?: { map?: string | null; timeOfDay?: string; rain?: boolean; background?: string }
+	environment?: { map?: string | null; rain?: boolean; background?: string }
 	overlays?: {
 		stickerGizmo?: boolean
 		charmGizmo?: boolean
@@ -158,12 +158,36 @@ export type FrameInteractions = {
  * the person an agent, and an integrator holding a weapon-modifier prop already named `agent` needs a
  * different word for the standalone picture. One rename, in one file.
  */
-export type FrameSubjectKind = 'weapon' | 'sticker' | 'charm' | 'collectible' | 'agent'
+export type FrameSubjectKind = 'weapon' | 'sticker' | 'charm' | 'collectible' | 'agent' | 'pet'
 
 /** The three standalone item groups, in the frame's words. An id, and at most one number. */
 export type FrameSticker = { id: number; wear?: number }
 export type FrameCharm = { id: number; pattern?: number }
 export type FrameCollectible = { id: number }
+/**
+ * One chicken pet (0.4.1). `id` is the `pet_definitions` row. Identity is `id` and, for a breed, a
+ * `stage` move between pullet and hen (the frame re-frames and says `ready` again); the rest update in
+ * place. `variant: null` lets the seed pick the colour group, `pose: null` is the idle.
+ */
+export type FramePet = {
+	id: number
+	stage?: 'egg' | 'chick' | 'pullet' | 'hen'
+	variant?: number | null
+	petSeed?: number
+	pose?: string | null
+	look?: { attributes?: Record<string, number>; shape?: Record<string, number> } | null
+	/*
+	 * THE PHOTO BOOTH AND THE NAMES (0.4.2) - all cheap, none of them identity. Plain strings on the wire;
+	 * the frame checks each against its own table and names a word it does not know (`types.ts` has the
+	 * unions). `names` REPLACES the held set rather than merging per stage.
+	 */
+	hat?: string | null
+	backdrop?: string | null
+	light?: string | null
+	effect?: string | null
+	names?: { chick?: string; pullet?: string; hen?: string } | null
+	nameLabel?: boolean
+}
 
 /**
  * Everything `/frame` holds. One field per prop of the renderer that a host can set.
@@ -179,6 +203,7 @@ export type FrameState = {
 	sticker: FrameSticker
 	charm: FrameCharm
 	collectible: FrameCollectible
+	pet: FramePet
 	view: 'gun' | 'hands' | 'agent'
 	agent: { id: number; pose?: string | null }
 	gloves: { type: string; paintIndex: number; float?: number; seed?: number } | null
@@ -217,6 +242,7 @@ export type FramePatch = {
 	sticker?: Partial<FrameSticker>
 	charm?: Partial<FrameCharm>
 	collectible?: Partial<FrameCollectible>
+	pet?: Partial<FramePet>
 	view?: FrameState['view']
 	agent?: Partial<FrameState['agent']>
 	gloves?: FrameState['gloves']

package/src/state.ts

@@ -38,6 +38,7 @@ import type {
 	FrameItem,
 	FrameLabels,
 	FramePatch,
+	FramePet,
 	FrameSettings,
 	FrameSticker,
 	FrameSubjectKind,
@@ -79,6 +80,7 @@ export type DesiredState = {
 	sticker?: FrameSticker
 	charm?: FrameCharm
 	collectible?: FrameCollectible
+	pet?: FramePet
 	/** The integrator's own inspect link, forwarded verbatim as `?i=`. See `item.ts`. */
 	inspectPayload: string | null
 	help: HelpReason | null
@@ -168,6 +170,7 @@ export const resolveState = (props: Partial<SkinViewerProps>): DesiredState => {
 			...(standalone.sticker && { sticker: standalone.sticker }),
 			...(standalone.charm && { charm: standalone.charm }),
 			...(standalone.collectible && { collectible: standalone.collectible }),
+			...(standalone.pet && { pet: standalone.pet }),
 			inspectPayload: null,
 			help: standalone.error ? HELP_FOR[standalone.error.code] : null,
 			subjectError: standalone.error,
@@ -290,6 +293,34 @@ export const frameUrl = (origin: string, desired: DesiredState): { src: string;
 		num(params, 'pattern', desired.charm.pattern)
 	}
 	if (desired.collectible) params.set('collectible', String(desired.collectible.id))
+	/*
+	 * THE PET, and its `?pose=` is the pet's clip: the frame reads `?pose=` as a pet clip whenever
+	 * `?pet=` is present, and an operator's pose has nothing to animate on a pet page. `?petseed=` and
+	 * not `?seed=` for the charm's reason - `seed` is the weapon's paint seed on this URL.
+	 */
+	if (desired.pet) {
+		const pet = desired.pet
+		params.set('pet', String(pet.id))
+		if (pet.stage) params.set('stage', pet.stage)
+		if (pet.variant !== undefined) params.set('variant', pet.variant === null ? '' : String(pet.variant))
+		num(params, 'petseed', pet.petSeed)
+		if (pet.pose) params.set('pose', pet.pose)
+		const look = petLookParam(pet.look)
+		if (look) params.set('look', look)
+		/* THE PHOTO BOOTH AND THE NAMES (0.4.2). `null` is written as the frame's explicit off (`none`, or an
+		   empty `?light=`) so a first paint says exactly what the prop says; absent says nothing. The names
+		   go per stage (`?chickname=`...), never `?name=`, which the frame reads against a stage the host
+		   may not have named - and only the named ones: a fresh frame's names are already none. */
+		if (pet.hat !== undefined) params.set('hat', pet.hat ?? 'none')
+		if (pet.backdrop !== undefined) params.set('backdrop', pet.backdrop ?? 'none')
+		if (pet.light !== undefined) params.set('light', pet.light?.replace(/^#/, '') ?? '')
+		if (pet.effect !== undefined) params.set('fx', pet.effect ?? 'none')
+		for (const stage of PET_NAMED_STAGES) {
+			const name = pet.names?.[stage]
+			if (name) params.set(`${stage}name`, name)
+		}
+		if (pet.nameLabel !== undefined) flag(params, 'namelabel', pet.nameLabel)
+	}
 
 	if (item) {
 		params.set('weapon', item.weaponType)
@@ -314,7 +345,7 @@ export const frameUrl = (origin: string, desired: DesiredState): { src: string;
 
 	if (desired.view) params.set('view', desired.view)
 	if (desired.agent?.id !== undefined) params.set('agent', String(desired.agent.id))
-	if (desired.agent?.pose) params.set('pose', desired.agent.pose)
+	if (desired.agent?.pose && !desired.pet?.pose) params.set('pose', desired.agent.pose)
 	if (desired.gloves !== undefined) params.set('glove', desired.gloves ? gloveParam(desired.gloves) : 'none')
 
 	const s = desired.settings
@@ -327,7 +358,6 @@ export const frameUrl = (origin: string, desired: DesiredState): { src: string;
 	flag(params, 'shadows', s?.quality?.shadows)
 	// `?map=none` is the calibrated reference rig, which is what `map: null` means on the prop.
 	if (s?.environment?.map !== undefined) params.set('map', s.environment.map ?? 'none')
-	if (s?.environment?.timeOfDay) params.set('time', s.environment.timeOfDay)
 	flag(params, 'rain', s?.environment?.rain)
 	if (s?.environment?.background) params.set('bg', s.environment.background)
 	flag(params, 'stickergizmo', s?.overlays?.stickerGizmo)
@@ -383,6 +413,15 @@ export const frameUrl = (origin: string, desired: DesiredState): { src: string;
 	return { src: `${origin.replace(/\/+$/, '')}/frame?${params.toString()}`, expressed }
 }
 
+/** `$ChickenHue:0.42,fatness:0.7` - the frame's `?look=`, keys sorted so one look is one URL. */
+const petLookParam = (look: FramePet['look']): string | null => {
+	const pairs = [...Object.entries(look?.attributes ?? {}), ...Object.entries(look?.shape ?? {})]
+		.filter(([, value]) => Number.isFinite(value))
+		.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+		.map(([key, value]) => `${key}:${Math.round(Math.min(Math.max(value, 0), 1) * 1000) / 1000}`)
+	return pairs.length ? pairs.join(',') : null
+}
+
 /** `type:paintIndex[:float[:seed]]` - one param and not four, because they are one item. */
 const gloveParam = (gloves: ViewerGloves) =>
 	[gloves.type, gloves.paintIndex, gloves.float, gloves.seed].filter(part => part !== undefined).join(':')
@@ -496,6 +535,13 @@ export const diffState = (previous: DesiredState, next: DesiredState): FramePatc
 		patch.collectible = collectible
 		changed = true
 	}
+	/* The pet's `look` is the one nested field in any standalone group, and a host rebuilds it on every
+	   render - so it is compared by value, or every render would post a `set`. */
+	const pet = diffGroup(previous.pet, next.pet, { look: petLookEqual, names: petNamesEqual })
+	if (pet) {
+		patch.pet = pet
+		changed = true
+	}
 
 	if (next.view !== undefined && next.view !== previous.view) {
 		patch.view = next.view
@@ -555,19 +601,34 @@ export const diffState = (previous: DesiredState, next: DesiredState): FramePatc
  * wire, and the alternative reading would make a conditional prop destructive. Same rule as
  * {@link diffSettings} one level in.
  */
-const diffGroup = <T extends object>(previous: T | undefined, next: T | undefined): Partial<T> | undefined => {
+const diffGroup = <T extends object>(
+	previous: T | undefined,
+	next: T | undefined,
+	/** Per-key equality for the rare nested field; everything else is `Object.is`. */
+	equal: { [K in keyof T]?: (a: T[K], b: T[K]) => boolean } = {},
+): Partial<T> | undefined => {
 	if (!next) return undefined
 	if (!previous) return { ...next }
 	const out: Partial<T> = {}
 	let changed = false
 	for (const key of Object.keys(next) as (keyof T)[])
-		if (!Object.is(previous[key], next[key])) {
+		if (!(equal[key] ?? Object.is)(previous[key], next[key])) {
 			out[key] = next[key]
 			changed = true
 		}
 	return changed ? out : undefined
 }
 
+const petLookEqual = (a: FramePet['look'], b: FramePet['look']) =>
+	a === b || (!!a && !!b && petLookParam(a) === petLookParam(b))
+
+/** The stages a pet can be named at, in order - the egg cannot be. */
+const PET_NAMED_STAGES = ['chick', 'pullet', 'hen'] as const
+
+/** `names` is the other nested pet field a host rebuilds every render - compared by value like `look`. */
+const petNamesEqual = (a: FramePet['names'], b: FramePet['names']) =>
+	a === b || (!!a && !!b && PET_NAMED_STAGES.every(stage => (a[stage] ?? '') === (b[stage] ?? '')))
+
 const glovesEqual = (a: ViewerGloves | null | undefined, b: ViewerGloves | null | undefined) => {
 	if (a === b) return true
 	if (!a || !b) return false
@@ -638,18 +699,48 @@ const localeEqual = (a: FrameSettings['locale'], b: FrameSettings['locale']) =>
  * IT TAKES THE WHOLE NEXT STATE rather than just the view, because one of the answers depends on which
  * SUBJECT the patch lands on: an operator's id covers under `subject: 'agent'` for the same reason it
  * covers under `view: 'agent'`, and does not under `hands`.
+ *
+ * AND THE PREVIOUS ONE, OPTIONALLY, for the pet's stage (see {@link drawnPetStage}): a stage patch only
+ * says the raw value moved, and whether the DRAWN stage moved depends on where it came from.
  */
-export const coversCanvas = (patch: FramePatch, next: Pick<DesiredState, 'subject' | 'view'>): boolean => {
+export const coversCanvas = (
+	patch: FramePatch,
+	next: Pick<DesiredState, 'subject' | 'view' | 'pet'>,
+	previous?: Pick<DesiredState, 'pet'>,
+): boolean => {
 	// A different KIND of subject is a different renderer. Always a reload, in every direction.
 	if (patch.subject !== undefined) return true
 	if (patch.view !== undefined) return true
 	if (patch.item && IDENTITY_FIELDS.some(field => patch.item?.[field] !== undefined)) return true
 	// An id is identity for all four standalone subjects; their second field (`wear`, `pattern`) is not.
-	if (patch.sticker?.id !== undefined || patch.charm?.id !== undefined || patch.collectible?.id !== undefined)
+	if (
+		patch.sticker?.id !== undefined ||
+		patch.charm?.id !== undefined ||
+		patch.collectible?.id !== undefined ||
+		patch.pet?.id !== undefined
+	)
 		return true
+	// A breed's stage is identity too: pullet and hen are one model, but the frame re-frames the bird
+	// and says `ready` again. Only when the drawn stage moves - anything else never gets that `ready`.
+	if (patch.pet?.stage !== undefined && previous && drawnPetStage(next.pet) !== drawnPetStage(previous.pet)) return true
 	// The operator is identity when they ARE the subject, and in the `agent` view, where their
 	// `<Suspense>` tears the subtree down; cheap in `hands`, where the arms are already mounted. The
 	// asymmetry is the renderer's, not ours.
 	if (patch.agent?.id !== undefined && (next.subject === 'agent' || next.view === 'agent')) return true
 	return false
 }
+
+/** The three breeds (`3` Catalana, `4` Silkie, `5` Polish) - the only pets with more than one stage. */
+const PET_BREED_IDS: readonly number[] = [3, 4, 5]
+
+/**
+ * *** THE STAGE THE FRAME WILL DRAW, OR `undefined` WHEN THE STAGE CANNOT CHANGE THE PICTURE. ***
+ *
+ * The frame clamps a stage to what the definition can be: an egg is only an egg, a chick only a chick,
+ * and a breed is a `pullet` or (anything else, or nothing) a `hen`. So `{ id: 3 }` -> `{ id: 3, stage:
+ * 'hen' }` is a patch that draws the same bird, and raising `loading` for it would wait for a `ready`
+ * that never comes. An id this package does not know is answered `undefined` for the same reason: a
+ * missed cover costs a few frames, a false one leaves the host's loading slot up for good.
+ */
+const drawnPetStage = (pet: FramePet | undefined) =>
+	pet && PET_BREED_IDS.includes(pet.id) ? (pet.stage === 'pullet' ? 'pullet' : 'hen') : undefined

package/src/types.ts

@@ -58,7 +58,14 @@ export type SkinViewerSticker = {
 	wear?: number
 	/** Degrees, any value; `370` renders as `10`. Default `0`. */
 	rotation?: number
-	/** -0.5..0.5. Default `0` - the slot's authored position. */
+	/**
+	 * How far from the slot's authored position to sit, in the game's own offset space. Default `0`.
+	 *
+	 * NOT bounded to -0.5..0.5, which this used to say. That range is the material editor's slider,
+	 * not a limit CS2 enforces - 160 of the 316 authored slots have legal area outside it. The real
+	 * bound is the weapon's authored `StickerMarkup` region, which is not a square, and the frame
+	 * applies it to a drag for you.
+	 */
 	offsetX?: number
 	offsetY?: number
 }
@@ -153,6 +160,8 @@ type ItemConfiguration = {
  *   `charm`        identity `id`, cheap `pattern`
  *   `collectible`  identity `id`, and NOTHING is cheap - there is no other field to change
  *   `operator`     identity `id`, cheap `pose`
+ *   `pet`          identity `id` and a breed's drawn `stage`, cheap `variant`, `petSeed`, `pose`, `look`,
+ *                  and (0.4.2) `hat`, `backdrop`, `light`, `effect`, `names`, `nameLabel`
  *
  * *** CHANGING WHICH SUBJECT YOU PASS IS ALWAYS AN IDENTITY CHANGE, *** in every direction: a weapon
  * and a pin are drawn by different renderers, so the picture is rebuilt from nothing.
@@ -294,6 +303,121 @@ export type ViewerOperatorSubject = {
 	pose?: string | null
 }
 
+/** A pet's growth stage - the item's `upgrade level` attribute, 0 egg .. 3 hen. */
+export type PetStage = 'egg' | 'chick' | 'pullet' | 'hen'
+
+/**
+ * The look sliders: per-key overrides over what the pet seed rolls, every value `0`..`1`. `attributes`
+ * is keyed by render attribute (`$ChickenHue`), `shape` by body characteristic (`fatness`). A key you do
+ * not pass is the seed's.
+ */
+export type PetLook = { attributes?: Record<string, number>; shape?: Record<string, number> }
+
+/**
+ * ONE CHICKEN PET (CS2 1.41.8.2) - what `/pet/:id` shows on our own site.
+ *
+ * `id` is the `pet_definitions` row, which is the `pet id` attribute on the item: `1` the egg, `2` the
+ * chick, `3` Catalana, `4` Silkie, `5` Polish. Everything else is how that pet looks:
+ *
+ *   `stage`    `'egg' | 'chick' | 'pullet' | 'hen'`. An egg is only an egg and a chick only a chick;
+ *              the three breeds are a pullet or a hen (the default). IDENTITY for a breed - see below.
+ *   `variant`  the colour group index, or `null` (default) to let the seed pick it. Updates IN PLACE.
+ *   `petSeed`  the `pet seed` attribute, a uint32. Default `0`. Updates IN PLACE. What a seed looks
+ *              like is our closest reconstruction of the game's rule and may differ slightly.
+ *   `pose`     a clip name from the pet's own model, or `null` (default) for its idle. IN PLACE. On the
+ *              egg only, `'chicknegg_hatch01'` / `'chicknegg_hatch02'` play the hatch (the shell breaks
+ *              and the chick climbs out; 02 is the shorter take). Any other pet idles on those two.
+ *   `look`     per-key overrides of the seed's roll - see {@link PetLook}. IN PLACE.
+ *
+ * IDENTITY IS `id` AND `stage`. A different id is a different model. A breed's pullet and hen are the
+ * same model, but the stage swaps the body proportions, so moving between them re-frames the bird:
+ * `loading` goes up and `onReady` fires again, the same as for a new id, only faster. A stage the pet
+ * cannot be (a hen for the egg) is drawn as the stage it can, and changes nothing. Everything else
+ * re-renders the bird already on screen.
+ */
+export type ViewerPetSubject = {
+	id: number
+	stage?: PetStage
+	variant?: number | null
+	petSeed?: number
+	pose?: string | null
+	look?: PetLook | null
+	/* ── The photo booth and the names (0.4.2). All update IN PLACE and none sends `onReady` again; only
+	   `backdrop` moves the camera (see there). ── */
+	/** A photo booth hat, or `null` (default) for none. Ignored on the egg, which has no head. */
+	hat?: PetHat | null
+	/**
+	 * The photo studio's paper backdrop behind the bird, by colour, or `null` (default) for none.
+	 *
+	 * IT MOVES THE CAMERA: switching one on seats the camera where the game's booth camera stands, frames
+	 * the bird looser (room for a hat and the effects) and limits a drag to 30 degrees either side of the
+	 * seat. A view you pinned (`settings.camera`) keeps its seat; the looser framing and the drag limit
+	 * still apply, centred on it. Switching it off gives the camera back.
+	 */
+	backdrop?: PetBackdrop | null
+	/**
+	 * The studio key light, six hex digits (`'ffe0c0'`, a leading `#` is accepted), or `null` (default) for
+	 * the booth's own warm white `fff2e6`. It lights the studio, so it only shows with a {@link backdrop}.
+	 */
+	light?: string | null
+	/**
+	 * A photo booth effect, replaying until you clear it, or `null` (default) for none. Not drawn on the egg.
+	 * The game offers `beam`, `lasers` and `sparks` from a pullet on; this draws what you ask for on a chick too.
+	 */
+	effect?: PetEffect | null
+	/**
+	 * The pet's names, one per growth stage, as the item stores them (the egg cannot be named). Each is cut to
+	 * 20 characters and loses `{ } < >`, as the game's own box does. A stage without a name goes by the
+	 * nearest named one - its own, then the younger stages, then the older ones. Passing `names` REPLACES
+	 * the set: send every stage you want kept.
+	 */
+	names?: PetNames | null
+	/** Draw the shown stage's name above the bird. Default `false`. */
+	nameLabel?: boolean
+}
+
+/** The ten photo booth hats, by the game's own names. */
+export type PetHat =
+	| 'helmet'
+	| 'armor'
+	| 'alien'
+	| 'banana'
+	| 'glasses'
+	| 'nose_glasses'
+	| 'party'
+	| 'sprout'
+	| 'top_hat'
+	| 'wizard_hat'
+
+/** The photo studio's paper colours. `wallpaper` exists in the game files but the booth never offers it. */
+export type PetBackdrop =
+	| 'grey'
+	| 'blue'
+	| 'green'
+	| 'purple'
+	| 'yellow'
+	| 'brown'
+	| 'red'
+	| 'black'
+	| 'sky'
+	| 'abstract'
+	| 'wallpaper'
+
+/** The nine photo booth effects, by the game's particle names (`lasers`, `feathers`). */
+export type PetEffect =
+	| 'explosion'
+	| 'lightning'
+	| 'fire'
+	| 'beam'
+	| 'lasers'
+	| 'sparks'
+	| 'confetti'
+	| 'bubbles'
+	| 'feathers'
+
+/** One name per stage - the item's `custom name attr` (chick), `... 2` (pullet) and `... 3` (hen). */
+export type PetNames = { chick?: string; pullet?: string; hen?: string }
+
 /* ═════════════════════════════════════════════════════════════════════════════════════════════
  * PRESENTATION
  * ═══════════════════════════════════════════════════════════════════════════════════════════ */
@@ -364,9 +488,17 @@ export type ViewerGloves = {
  * upgraded. That is the deliberate trade - the rule is *"no back-compat
  * boilerplate, upgrade when you need to"* - and the failure is legible either way: the frame reports
  * an unknown map in its `problems` and keeps the lighting it had.
+ *
+ * *** THREE NAMES MOVED IN 0.4.0 AND THAT IS THE RULE BEING CHARGED. *** There was a `timeOfDay`
+ * field beside {@link ViewerEnvironmentSettings.map}, and a map that had two videos was named by the
+ * PAIR. It is one field now: `'Ancient'` became `'Ancient (Day)'` and `'Ancient (Night)'`, and
+ * `'Train'` became `'Train (Night)'` - a correction as much as a rename, since `de_train` ships one
+ * vanity scene and that scene is night. An embed still passing `'Ancient'` reports an unknown map in
+ * `problems` and keeps the lighting it had, which is this list's documented failure and not a new one.
  */
 export const MAP_NAMES = [
-	'Ancient',
+	'Ancient (Day)',
+	'Ancient (Night)',
 	'Anubis',
 	'Baggage',
 	'Cache',
@@ -377,13 +509,12 @@ export const MAP_NAMES = [
 	'Nuke',
 	'Office',
 	'Overpass',
-	'Train',
+	'Train (Night)',
 	'Vertigo',
 	'Warehouse',
 ] as const
 
 export type MapName = (typeof MAP_NAMES)[number]
-export type TimeOfDay = 'Day' | 'Night'
 
 /**
  * What is BEHIND the item.
@@ -459,7 +590,7 @@ export type ViewerQualitySettings = {
 
 export type ViewerEnvironmentSettings = {
 	/**
-	 * WHICH MAP'S LIGHT. Default `'Ancient'`; `null` is our calibrated reference rig, which is what
+	 * WHICH MAP'S LIGHT. Default `'Dust II'`; `null` is our calibrated reference rig, which is what
 	 * every fidelity measurement behind this renderer was taken against.
 	 *
 	 * *** THIS IS THE LIGHT, {@link background} IS THE PICTURE, AND THEY ARE SEPARATE ON PURPOSE. ***
@@ -468,8 +599,6 @@ export type ViewerEnvironmentSettings = {
 	 * your page behind it.
 	 */
 	map?: MapName | null
-	/** Default `'Night'`. Falls back on its own for a map that has only one. */
-	timeOfDay?: TimeOfDay
 	/** Wet surfaces on maps whose own data says it rains. Default `true`. */
 	rain?: boolean
 	/** See {@link ViewerBackground}. Default `'transparent'`. */
@@ -709,6 +838,8 @@ type SubjectArms = {
 	charm: ViewerCharmSubject
 	collectible: ViewerCollectibleSubject
 	operator: ViewerOperatorSubject
+	/** Added in 0.4.1 - a seventh arm on the same rule. See {@link ViewerPetSubject}. */
+	pet: ViewerPetSubject
 }
 
 /** One arm present, the other five forbidden. Written once so six arms cannot disagree about five. */
@@ -723,6 +854,7 @@ export type ViewerSubject =
 	| OnlySubject<'charm'>
 	| OnlySubject<'collectible'>
 	| OnlySubject<'operator'>
+	| OnlySubject<'pet'>
 
 export type SkinViewerProps = ViewerSubject & {
 	/* ── Presentation ──────────────────────────────────────────────────────────────────────── */