@skinhub/viewer 0.1.1 → 0.2.0

package/src/protocol.ts

@@ -121,9 +121,35 @@ export type FrameInteractions = {
 	dragCharm?: boolean
 }
 
-/** Everything `/frame` holds. One field per prop of the renderer that a host can set. */
+/**
+ * *** THE FRAME'S FIVE SUBJECT KINDS. *** `weapon` covers gloves too - a glove is a `weaponType`.
+ *
+ * NOTE THE WORD: the wire says `agent` where `types.ts` says `operator`. That is the translation this
+ * package exists to do (see `item.ts`'s header): the frame's own subject vocabulary has always called
+ * 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'
+
+/** 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 }
+
+/**
+ * Everything `/frame` holds. One field per prop of the renderer that a host can set.
+ *
+ * *** THE FIVE SUBJECTS ARE HELD AT ONCE AND `subject` PICKS ONE. *** A patch naming `sticker` does
+ * NOT make the sticker the subject - only `subject` does. That matters here in particular because this
+ * package restates its whole prop set on every render: if a group write switched the picture, a host
+ * holding both a weapon and a pin would flip between them on any render mentioning both.
+ */
 export type FrameState = {
+	subject: FrameSubjectKind
 	item: FrameItem
+	sticker: FrameSticker
+	charm: FrameCharm
+	collectible: FrameCollectible
 	view: 'gun' | 'hands' | 'agent'
 	agent: { id: number; pose?: string | null }
 	gloves: { type: string; paintIndex: number; float?: number; seed?: number } | null
@@ -141,7 +167,12 @@ export type FrameState = {
  * rather than merged would blank the weapon on every float tick.
  */
 export type FramePatch = {
+	/** The subject switch, and the only one - see {@link FrameState}. An IDENTITY change in every direction. */
+	subject?: FrameSubjectKind
 	item?: Partial<FrameItem>
+	sticker?: Partial<FrameSticker>
+	charm?: Partial<FrameCharm>
+	collectible?: Partial<FrameCollectible>
 	view?: FrameState['view']
 	agent?: Partial<FrameState['agent']>
 	gloves?: FrameState['gloves']

package/src/state.ts

@@ -31,8 +31,18 @@
  * So the diff is structural: a field is in the patch only if its VALUE moved.
  */
 
-import type { FrameInteractions, FrameItem, FramePatch, FrameSettings, PlacementSlots } from './protocol.js'
-import { resolveSubject } from './item.js'
+import type {
+	FrameCharm,
+	FrameCollectible,
+	FrameInteractions,
+	FrameItem,
+	FramePatch,
+	FrameSettings,
+	FrameSticker,
+	FrameSubjectKind,
+	PlacementSlots,
+} from './protocol.js'
+import { resolveStandalone, resolveSubject } from './item.js'
 import type { SkinViewerError, SkinViewerProps, ViewerGloves, ViewerView } from './types.js'
 
 /**
@@ -51,8 +61,23 @@ export type HelpReason = 'no-item' | 'bad-link' | 'unknown-weapon'
  * caller did not mention.
  */
 export type DesiredState = {
-	/** `null` when the props named no renderable item; {@link help} then says why. */
+	/**
+	 * WHICH OF THE FIVE IS ON SCREEN.
+	 *
+	 * *** THE ONE FIELD HERE THAT IS ALWAYS SET, AND THE EXCEPTION IS EARNED. *** Everything else in
+	 * this type obeys "absent means say nothing", because our defaults must not be frozen into somebody
+	 * else's URL. The subject cannot: going BACK to a weapon from a sticker has to be expressible, and a
+	 * diff can only express it if there is a value to compare against. So it is always resolved - and
+	 * {@link frameUrl} then declines to write `?subject=weapon`, which keeps the same promise in the one
+	 * place it can be kept.
+	 */
+	subject: FrameSubjectKind
+	/** `null` when the props named no renderable item, or named a subject that is not a weapon. */
 	item: FrameItem | null
+	/** Set only when {@link subject} names it. Same rule as `item`, one per standalone subject. */
+	sticker?: FrameSticker
+	charm?: FrameCharm
+	collectible?: FrameCollectible
 	/** The integrator's own inspect link, forwarded verbatim as `?i=`. See `item.ts`. */
 	inspectPayload: string | null
 	help: HelpReason | null
@@ -88,14 +113,9 @@ const HELP_FOR: Record<SkinViewerError['code'], HelpReason | null> = {
  * rather than a `TypeError`.
  */
 export const resolveState = (props: Partial<SkinViewerProps>): DesiredState => {
-	const subject = resolveSubject(props)
 	const settings = toFrameSettings(props.settings)
-
-	return {
-		item: subject.item,
-		inspectPayload: subject.inspectPayload,
-		help: subject.error ? HELP_FOR[subject.error.code] : null,
-		subjectError: subject.error,
+	/* Everything true of every subject. Hoisted so the two returns below cannot drift apart. */
+	const common = {
 		...(props.view !== undefined && { view: props.view }),
 		...(props.agent !== undefined && { agent: props.agent }),
 		...(props.gloves !== undefined && { gloves: props.gloves }),
@@ -103,6 +123,40 @@ export const resolveState = (props: Partial<SkinViewerProps>): DesiredState => {
 		...(props.interactions !== undefined && { interactions: { ...props.interactions } }),
 		...(props.editingSlot !== undefined && { editingSlot: props.editingSlot }),
 	}
+
+	/*
+	 * THE OTHER FOUR SUBJECTS FIRST, because each is named by its own prop and the weapon is the
+	 * fall-through. `item` stays null for them: there IS no weapon, and inventing one would put a rifle
+	 * into this package's URL that the frame would then hold behind a subject nobody is looking at.
+	 *
+	 * `agent` IS WRITTEN LAST for the operator, so `operator={{ pose }}` beats an `agent={{ pose }}` a
+	 * host also happened to pass. Two props answering one question is only reachable through the types'
+	 * back door, and the subject arm is the more specific statement.
+	 */
+	const standalone = resolveStandalone(props)
+	if (standalone)
+		return {
+			subject: standalone.subject,
+			item: null,
+			...(standalone.sticker && { sticker: standalone.sticker }),
+			...(standalone.charm && { charm: standalone.charm }),
+			...(standalone.collectible && { collectible: standalone.collectible }),
+			inspectPayload: null,
+			help: standalone.error ? HELP_FOR[standalone.error.code] : null,
+			subjectError: standalone.error,
+			...common,
+			...(standalone.agent && { agent: standalone.agent }),
+		}
+
+	const subject = resolveSubject(props)
+	return {
+		subject: 'weapon',
+		item: subject.item,
+		inspectPayload: subject.inspectPayload,
+		help: subject.error ? HELP_FOR[subject.error.code] : null,
+		subjectError: subject.error,
+		...common,
+	}
 }
 
 /**
@@ -160,6 +214,31 @@ export const frameUrl = (origin: string, desired: DesiredState): { src: string;
 
 	if (desired.help) params.set('help', desired.help)
 
+	/*
+	 * ── THE SUBJECT ──────────────────────────────────────────────────────────────────────────
+	 *
+	 * `?subject=` IS WRITTEN FOR EVERY NON-WEAPON AND NEVER FOR A WEAPON. Not writing it for the weapon
+	 * keeps this file's promise about defaults: `?subject=weapon` in a customer's `<iframe src>` would
+	 * be OUR default frozen into THEIR embed. Writing it for the other four is not the same thing - it
+	 * is the caller's own statement, and for the operator it is the only way to say it, because
+	 * `?agent=` on its own has always meant "who holds the weapon".
+	 *
+	 * The id params are what the frame reads back; `?sticker=`/`?charm=`/`?collectible=` each imply the
+	 * subject on their own, so the pair is redundant by design rather than by accident - a URL that says
+	 * the same thing twice cannot be half-copied into meaning something else.
+	 */
+	if (desired.subject !== 'weapon') params.set('subject', desired.subject)
+	if (desired.sticker) {
+		params.set('sticker', String(desired.sticker.id))
+		num(params, 'wear', desired.sticker.wear)
+	}
+	if (desired.charm) {
+		params.set('charm', String(desired.charm.id))
+		// `?pattern=` and not `?seed=` - on this URL `seed` is already the WEAPON's paint seed.
+		num(params, 'pattern', desired.charm.pattern)
+	}
+	if (desired.collectible) params.set('collectible', String(desired.collectible.id))
+
 	if (item) {
 		params.set('weapon', item.weaponType)
 		params.set('paint', String(item.paintIndex))
@@ -291,6 +370,46 @@ export const diffState = (previous: DesiredState, next: DesiredState): FramePatc
 		if (Object.keys(item).length > 0) patch.item = item
 	}
 
+	/*
+	 * ── THE OTHER FOUR SUBJECTS ───────────────────────────────────────────────────────────────
+	 *
+	 * A GROUP IS DIFFED EVEN WHEN THE SUBJECT DID NOT MOVE, so a `wear` drag on a sticker is one small
+	 * patch per tick and nothing else - the identical shape a `float` drag on a rifle has, and cheap for
+	 * the identical reason: the id is not in the patch, so nothing keyed on the id can move.
+	 *
+	 * THE SUBJECT IS DIFFED SEPARATELY AND CARRIES NO GROUP WITH IT. Switching to a sticker whose id has
+	 * not changed sends `{ subject: 'sticker' }` alone, because the frame still holds the id it was given
+	 * before - which is what makes flipping between two subjects cost one field.
+	 */
+	if (next.subject !== previous.subject) {
+		patch.subject = next.subject
+		changed = true
+	}
+	/*
+	 * *** FIELD BY FIELD, NOT WHOLE-GROUP, AND THE TEST BELOW IS WHY. *** Sending the whole group would
+	 * be correct on the wire - the frame merges by field either way - and would still break the
+	 * contract, because `coversCanvas` reads `sticker.id !== undefined` to decide whether to raise the
+	 * caller's `loading` slot. A `wear` drag that restated the id would raise it sixty times a second
+	 * over a picture the frame never covered, which from outside is indistinguishable from a reload.
+	 * The item above is diffed per field for the same reason; gloves are the one group sent wholesale,
+	 * and that is because a partial pair is a state the renderer cannot resolve.
+	 */
+	const sticker = diffGroup(previous.sticker, next.sticker)
+	if (sticker) {
+		patch.sticker = sticker
+		changed = true
+	}
+	const charm = diffGroup(previous.charm, next.charm)
+	if (charm) {
+		patch.charm = charm
+		changed = true
+	}
+	const collectible = diffGroup(previous.collectible, next.collectible)
+	if (collectible) {
+		patch.collectible = collectible
+		changed = true
+	}
+
 	if (next.view !== undefined && next.view !== previous.view) {
 		patch.view = next.view
 		changed = true
@@ -330,6 +449,26 @@ export const diffState = (previous: DesiredState, next: DesiredState): FramePatc
 	return changed ? patch : undefined
 }
 
+/**
+ * One flat group, per field. `undefined` when nothing moved, so the caller can skip the key entirely.
+ *
+ * A KEY THE NEXT RENDER DID NOT MENTION IS NOT DIFFED AWAY - there is no way to say "unset" over the
+ * 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 => {
+	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])) {
+			out[key] = next[key]
+			changed = true
+		}
+	return changed ? out : undefined
+}
+
 const glovesEqual = (a: ViewerGloves | null | undefined, b: ViewerGloves | null | undefined) => {
 	if (a === b) return true
 	if (!a || !b) return false
@@ -378,12 +517,24 @@ const overlaysEqual = (a: FrameSettings['overlays'], b: FrameSettings['overlays'
 	return a.stickerGizmo === b.stickerGizmo && a.charmGizmo === b.charmGizmo && shallowEqual(a.gizmoStyle, b.gizmoStyle)
 }
 
-/** True when a patch would cover the canvas - see {@link IDENTITY_FIELDS}. */
-export const coversCanvas = (patch: FramePatch, view: ViewerView | undefined): boolean => {
+/**
+ * True when a patch would cover the canvas - see {@link IDENTITY_FIELDS} and `CHEAP_FIELDS`.
+ *
+ * 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`.
+ */
+export const coversCanvas = (patch: FramePatch, next: Pick<DesiredState, 'subject' | 'view'>): 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
-	// The operator is identity in the `agent` view, where its `<Suspense>` tears the subtree down, and
-	// cheap in `hands`, where the arms are already mounted. The asymmetry is the renderer's, not ours.
-	if (patch.agent?.id !== undefined && view === 'agent') 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)
+		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
 }

package/src/types.ts

@@ -145,6 +145,17 @@ type ItemConfiguration = {
  * This list is the FIRST half. It is here, as a value, because {@link SkinViewerProps.loading} is
  * raised off its complement - see `SkinViewer.tsx`'s `isIdentityChange` - and because a contract an
  * integrator relies on should be readable without opening the renderer.
+ *
+ * *** AND THE SAME SPLIT FOR THE OTHER FOUR SUBJECTS, which is a shorter table because they are
+ * smaller items: ***
+ *
+ *   `sticker`      identity `id`, cheap `wear`
+ *   `charm`        identity `id`, cheap `pattern`
+ *   `collectible`  identity `id`, and NOTHING is cheap - there is no other field to change
+ *   `operator`     identity `id`, cheap `pose`
+ *
+ * *** 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.
  */
 export const CHEAP_FIELDS = ['float', 'seed', 'statTrak', 'nameTag', 'stickers', 'charm'] as const
 
@@ -180,6 +191,109 @@ export type SkinViewerItem = ItemConfiguration &
 		  }
 	)
 
+/* ═════════════════════════════════════════════════════════════════════════════════════════════
+ * THE OTHER FOUR SUBJECTS
+ *
+ * *** A WEAPON IS ONE OF FIVE THINGS THE VIEWER CAN SHOW, NOT THE ONLY ONE. *** Owner: *"Weapons and
+ * gloves only... why not? it's already working in our system, I want them all to be inspectable
+ * through the viewer."* A GLOVE IS NOT ON THIS LIST because a glove is a `weapon` id like any other
+ * (`'sporty_gloves'`) - it always was one of the arms above.
+ *
+ * *** YOU NAME ONE BY PASSING ITS PROP, AND EXACTLY ONE. *** See {@link ViewerSubject}: the same
+ * `?: never` enforcement the `inspectLink` / `item` pair already had, widened to six arms. There is no
+ * `kind` or `type` discriminator to get wrong, because the prop you passed IS the discriminator.
+ * ═══════════════════════════════════════════════════════════════════════════════════════════ */
+
+/**
+ * ONE STICKER, ON NOTHING - what `/sticker/:id` shows on our own site.
+ *
+ * *** NOT {@link SkinViewerSticker}, AND THE MISSING FIELDS ARE THE DIFFERENCE. *** That type is a
+ * sticker APPLIED to a weapon and carries a slot, a rotation and an offset; all three are statements
+ * about the sticker being ON something. Here the quad is the whole surface, so what is left is the id
+ * and how scratched it is.
+ *
+ * IT IS THE REAL SHADER AND NOT AN IMAGE ON A PLANE: holo, foil and glitter are functions of the view
+ * direction and of screen-space derivatives, so they exist only in 3D and only under lighting. That is
+ * the entire reason to embed a sticker rather than show your catalogue's icon.
+ */
+export type ViewerStickerSubject = {
+	/** `sticker_id` - the id in `@skinhub/cdn`'s `stickers.json`. */
+	id: number
+	/** Scratch, `0` (mint) to `1` (scraped off). Default `0`. Updates IN PLACE - see {@link CHEAP_FIELDS}. */
+	wear?: number
+}
+
+/**
+ * ONE CHARM, OFF THE GUN.
+ *
+ * It hangs in the pose its own model authors and does not swing: the physics exists to answer to how a
+ * rifle is being turned, and there is no rifle here. Everything that is the charm's own - its model,
+ * its per-id material, its template - is unchanged.
+ */
+export type ViewerCharmSubject = {
+	/** The id in `@skinhub/cdn`'s `keychains.json`. */
+	id: number
+	/**
+	 * The charm's template. NOT a variant: it drives a hue/saturation/brightness adjust on the charm's
+	 * own albedo, so two charms with the same `id` and a different value are the same model in different
+	 * colours. Default `0`. Updates IN PLACE.
+	 *
+	 * *** SPELLED `pattern` HERE AND `seed` ON {@link SkinViewerCharm}, WHICH IS DELIBERATE. *** On a
+	 * weapon the charm sits beside a paint `seed` and calling it a seed reads naturally; as a SUBJECT it
+	 * sits beside nothing, and `pattern` is what the wire, the game and the URL (`?pattern=`) all call
+	 * it. The one word that could not be reused in both places is `seed`, because on the URL that is
+	 * already the weapon's paint seed.
+	 */
+	pattern?: number
+}
+
+/**
+ * ONE PIN, COIN, MEDAL OR TROPHY.
+ *
+ * *** IT HAS NOTHING ELSE, AND THAT IS THE WHOLE TYPE. *** No float, no seed, no wear, no template, no
+ * pose: two copies of the same medal ARE the same object. If you are drawing controls for an embedded
+ * collectible, there is nothing to draw except the camera.
+ */
+export type ViewerCollectibleSubject = {
+	/** The item definition index in `@skinhub/cdn`'s `collectibles.json`. */
+	id: number
+}
+
+/**
+ * ONE OPERATOR, ALONE - the agent as the SUBJECT rather than as the person holding a weapon.
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** WHY THIS IS NOT {@link ViewerAgent}, WHEN IT NAMES THE SAME CATALOGUE ROW. ***
+ *
+ * They are two pictures, and the prop you pass is which one you get:
+ *
+ *   `agent={{ id }}`      WHO IS HOLDING IT. A modifier on the weapon subject, visible in the `hands`
+ *                         and `agent` views, ignored in `gun`. The weapon is what is being shown.
+ *   `operator={{ id }}`   THE PERSON IS WHAT IS BEING SHOWN. No weapon is drawn at all.
+ *
+ * A marketplace with an agent row in an inventory wants the second: they asked for Sir Bloody Darryl,
+ * and rendering him holding an AK-47 nobody named would be a picture of two items, one of them
+ * invented. (Our own site made the opposite call for its own routes, for a reason that does not carry:
+ * in the app there is always a weapon being configured, so `/agent/:id` folds into `?view=agent`
+ * rather than duplicating a surface. An embed has no such weapon.)
+ *
+ * PASSING BOTH IS NOT POSSIBLE for the subject - `?: never` - and passing `agent` ALONGSIDE `operator`
+ * simply does nothing, because there is no weapon for anyone to hold.
+ */
+export type ViewerOperatorSubject = {
+	/** An agent's item definition index; `5036` is the default Terrorist. */
+	id: number
+	/**
+	 * Which main-menu performance they play, by clip leaf name, or `null` (the default) for their
+	 * team's own knife idle - what CS2's main menu opens on.
+	 *
+	 * 285 leaves across 44 weapon families are reachable. THE WEAPON EACH CLIP HOLDS IS NOT DRAWN, so
+	 * `Look at gun` is an operator studying an empty hand; that is a property of the performance rather
+	 * than a defect. Updates IN PLACE - the clip is swapped on a rig that keeps running.
+	 */
+	pose?: string | null
+}
+
 /* ═════════════════════════════════════════════════════════════════════════════════════════════
  * PRESENTATION
  * ═══════════════════════════════════════════════════════════════════════════════════════════ */
@@ -188,6 +302,9 @@ export type SkinViewerItem = ItemConfiguration &
  * What the item is being shown ON. All three are the same item under the same lighting, finish,
  * stickers and charm - the difference is the camera and what is holding the weapon.
  *
+ * *** IT IS A PROPERTY OF THE WEAPON SUBJECT AND IS IGNORED BY THE OTHER FOUR. *** A sticker is not a
+ * way of showing a weapon, so there is nothing for it to choose between.
+ *
  *   `gun`     the item alone, orbitable, framed to the viewport. The default.
  *   `hands`   CS2's first-person viewmodel, driven by the game's own clips. Orbit is off here because
  *             there is nothing to orbit: the weapon is welded to the eye.
@@ -494,8 +611,34 @@ export type ViewerResize = { width: number; height: number; dpr: number }
  * was still `undefined` when the component mounted: the frame renders a short instruction card rather
  * than a blank box or - worse - our default AK-47, which would look like a successful render of the
  * wrong item. `onError` fires with `no-item` at the same time. See `SkinViewer.tsx`.
+ *
+ * *** AND IT IS SIX ARMS NOW RATHER THAN TWO, on exactly the same rule. *** A weapon, an inspect link
+ * and the four subjects above are six ways of naming ONE thing to render, and the same `?: never`
+ * enforcement covers all of them: passing two is an excess-property error, passing none is a
+ * missing-property error, and there is no `kind` discriminator anywhere because the prop you passed is
+ * the discriminator.
  */
-export type ViewerSubject = { inspectLink: string; item?: never } | { item: SkinViewerItem; inspectLink?: never }
+type SubjectArms = {
+	inspectLink: string
+	item: SkinViewerItem
+	sticker: ViewerStickerSubject
+	charm: ViewerCharmSubject
+	collectible: ViewerCollectibleSubject
+	operator: ViewerOperatorSubject
+}
+
+/** One arm present, the other five forbidden. Written once so six arms cannot disagree about five. */
+type OnlySubject<K extends keyof SubjectArms> = { [P in K]: SubjectArms[P] } & {
+	[P in Exclude<keyof SubjectArms, K>]?: never
+}
+
+export type ViewerSubject =
+	| OnlySubject<'inspectLink'>
+	| OnlySubject<'item'>
+	| OnlySubject<'sticker'>
+	| OnlySubject<'charm'>
+	| OnlySubject<'collectible'>
+	| OnlySubject<'operator'>
 
 export type SkinViewerProps = ViewerSubject & {
 	/* ── Presentation ──────────────────────────────────────────────────────────────────────── */