@skinhub/viewer 0.3.3 → 0.4.2

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,
@@ -215,6 +216,7 @@ export type ResolvedStandalone = {
 	sticker?: FrameSticker
 	charm?: FrameCharm
 	collectible?: FrameCollectible
+	pet?: FramePet
 	agent?: { id: number; pose?: string | null }
 	error: SkinViewerError | null
 }
@@ -251,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
 }
 

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

@@ -160,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.
@@ -301,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
  * ═══════════════════════════════════════════════════════════════════════════════════════════ */
@@ -371,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',
@@ -384,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.
@@ -466,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. ***
@@ -475,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'`. */
@@ -716,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. */
@@ -730,6 +854,7 @@ export type ViewerSubject =
 	| OnlySubject<'charm'>
 	| OnlySubject<'collectible'>
 	| OnlySubject<'operator'>
+	| OnlySubject<'pet'>
 
 export type SkinViewerProps = ViewerSubject & {
 	/* ── Presentation ──────────────────────────────────────────────────────────────────────── */

package/src/weapons.ts

@@ -16,7 +16,10 @@
  * it is derived from the export itself (`data/skins.json`, `weapon.weapon_id` → `weapon.id`,
  * generated 2026-08-15, verified: 63 distinct defindexes, no defindex mapping to two DIFFERENT
  * weapons — the 20 knives each carry a second `sfui_wpnhud_*` alias for their vanilla row, which
- * `getWeaponModelPath` already resolves to the same model).
+ * `getWeaponModelPath` already resolves to the same model). Plus one hand-added row, the C4
+ * (49 -> `weapon_c4`, since CS2 1.41.8.2 put stickers on it): the 2026-08-15 `skins.json` the other
+ * 63 came from predates the 1.41.8.2 export and has no C4. From that export on it carries a vanilla
+ * `weapon_c4` row with `weapon_id: 49`, so the row is derivable like the rest - 64 rows in all.
  *
  * The alternative is fetching a 4.4 MB `skins.json` to answer "what is 7", which would make the
  * inspect-link path — the one the product exists for — cost four megabytes before the first frame.
@@ -33,7 +36,7 @@
  *
  * This is `skin.weapon.id` in `@skinhub/cdn`'s `skins.json` rows, verbatim — so
  * `<SkinViewer weapon={row.weapon.id} paintIndex={…} />` typechecks against a catalogue row with no
- * conversion. Type it into an editor and autocomplete lists all 71.
+ * conversion. Type it into an editor and autocomplete lists all 72.
  */
 export const WEAPON_IDS = [
 	// Pistols
@@ -77,6 +80,8 @@ export const WEAPON_IDS = [
 	'weapon_xm1014',
 	// Other
 	'weapon_taser',
+	// The C4 - no finish, but stickers, a charm and a name tag since CS2 1.41.8.2. See the defindex table.
+	'weapon_c4',
 	// Knives
 	'weapon_bayonet',
 	'weapon_knife_butterfly',
@@ -117,7 +122,7 @@ export type KnownWeaponId = (typeof WEAPON_IDS)[number]
  * `'weapon_ak47'`.
  *
  * The `(string & {})` arm is deliberate and is not a widening mistake: it keeps autocomplete listing
- * the 71 known ids while still ACCEPTING an id this build has never heard of, so a new weapon in a
+ * the 72 known ids while still ACCEPTING an id this build has never heard of, so a new weapon in a
  * fresh export renders the day it ships rather than the day the package is upgraded. An unknown id
  * that the asset export also does not know resolves to no model, which surfaces as `unknown-weapon`.
  */
@@ -161,6 +166,16 @@ export const WEAPON_ID_BY_DEFINDEX: Readonly<Record<number, KnownWeaponId>> = {
 	38: 'weapon_scar20',
 	39: 'weapon_sg556',
 	40: 'weapon_ssg08',
+	/**
+	 * THE ONE ROW ADDED BY HAND, because the `skins.json` this table was derived from predates the
+	 * 1.41.8.2 export. From that export on, `skins.json` carries a vanilla C4 row (`weapon_id: 49`) and
+	 * this row is derivable like the other 63. CS2 1.41.8.2 (2026-09-22) gave the `c4` prefab
+	 * `weapon_supports_stickers`, so a stickered C4 is now a real item with an inspect link that says
+	 * `defindex: 49` - and without this row it resolved to `unknown-weapon`. `weapon_c4` is the item
+	 * definition's own `name` in `items_game.txt`, and the renderer's model table has carried it since
+	 * the same update.
+	 */
+	49: 'weapon_c4',
 	60: 'weapon_m4a1_silencer',
 	61: 'weapon_usp_silencer',
 	63: 'weapon_cz75a',