@skinhub/viewer 0.1.1

package/src/item.ts

@@ -0,0 +1,373 @@
+/**
+ * *** THE BRIDGE - an integrator's item into the frame's item, and back out again. ***
+ *
+ * This is the package's actual work. Everything else is an `<iframe>` and a message listener.
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** THE TWO VOCABULARIES, AND WHY WE DO NOT JUST PICK ONE. ***
+ *
+ * The frame speaks the renderer's names (`weaponType`) and the GAME's names (`sticker_id`,
+ * `offset_x`, `pattern`), because those are what the shader parameters, the WeaponPaints columns and
+ * the inspect codec all call the same six slots. That is right for the wire and wrong for a prop: an
+ * integrator writing `offset_x` in a React tree is writing protobuf into their view layer.
+ *
+ * So there are two, and exactly one file that knows both. A field renamed on either side breaks HERE,
+ * at compile time, rather than becoming a picture that is quietly missing a sticker.
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** AND THE PIECE THE FRAME CANNOT DO FOR ITSELF: AN INSPECT LINK'S IDENTITY. ***
+ *
+ * `?i=` carries an item's CONFIGURATION - float, seed, StatTrak, the plate, five stickers and the
+ * charm - and the frame decodes all of it. What it does not carry, for the frame, is WHICH WEAPON: a
+ * link says `defindex: 7` and the renderer wants `weapon_ak47`, and the app's own `SkinViewer`
+ * says so in a comment naming this package as the place the table lives:
+ *
+ *     "the 63-row table between them lives in `@skinhub/viewer`'s `src/weapons.ts` - an in-flight file
+ *      outside this app's dependency graph."
+ *
+ * Which makes `inspectLink` a first-class prop rather than a documented gap. This file resolves the
+ * identity here, on the host, and hands the frame both halves. An integrator never decodes a link to
+ * use us - That is stated as a requirement and it is the path the product exists for.
+ */
+
+import { buildInspectUrl, readInspectUrl } from '@skinhub/cdn/inspect'
+import { emptyKeychain, emptySticker, makeSkinPlacement, type SkinPlacement } from '@skinhub/cdn/placement'
+
+import type { FrameItem, PlacementSlots } from './protocol.js'
+import type { SkinViewerCharm, SkinViewerError, SkinViewerItem, SkinViewerSticker, ViewerSubject } from './types.js'
+import { defindexForWeaponId, normalizeWeaponId, weaponIdForDefindex } from './weapons.js'
+
+/** `sticker_id === 0` is how the wire says "this slot is empty". */
+const isPlaced = (placement: { sticker_id: number }) => placement.sticker_id > 0
+
+/** Six empty slots. Rebuilt per call because the caller mutates the copy it is handed. */
+const emptySlots = (): PlacementSlots => [
+	emptySticker(0),
+	emptySticker(1),
+	emptySticker(2),
+	emptySticker(3),
+	emptySticker(4),
+	emptyKeychain(),
+]
+
+/**
+ * The public sticker list and charm as the six-slot tuple the frame validates.
+ *
+ * *** ARRAY POSITION IS THE SLOT UNLESS A STICKER NAMES ITS OWN, *** which is what makes
+ * `stickers={[a, null, b]}` mean slots 0 and 2 - the shape a marketplace's own UI produces when a user
+ * has filled two of five holders. A sticker naming a slot outside `0..4` is dropped rather than
+ * wrapped, because a sixth sticker slot is the charm's and putting a sticker there would be a picture
+ * nobody asked for.
+ *
+ * RETURNS `undefined` WHEN THERE IS NOTHING PLACED, so an item with no stickers sends no `stickers`
+ * key at all and cannot disturb the frame's sticker draft. See `patch.ts`.
+ */
+export const toSlots = (
+	stickers: readonly (SkinViewerSticker | null)[] | undefined,
+	charm: SkinViewerCharm | null | undefined,
+): PlacementSlots | undefined => {
+	if ((!stickers || stickers.length === 0) && !charm) return undefined
+	const slots = emptySlots()
+
+	stickers?.forEach((sticker, index) => {
+		if (!sticker) return
+		const slot = sticker.slot ?? index
+		if (slot < 0 || slot > 4) return
+		slots[slot as 0 | 1 | 2 | 3 | 4] = {
+			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,
+			rotation: sticker.rotation ?? 0,
+			offset_x: sticker.offsetX ?? 0,
+			offset_y: sticker.offsetY ?? 0,
+		}
+	})
+
+	if (charm)
+		slots[5] = {
+			slot: 0,
+			sticker_id: charm.id,
+			// `pattern` IS the charm's seed - the keychain message is the sticker message reused, so the
+			// field it lands in is the one a sticker calls its pattern index.
+			pattern: charm.seed ?? 0,
+			offset_x: charm.offset?.[0] ?? 0,
+			offset_y: charm.offset?.[1] ?? 0,
+			offset_z: charm.offset?.[2] ?? 0,
+		}
+
+	return slots
+}
+
+/** The six-slot tuple back into the public shape - what `onChange` hands an integrator. */
+export const fromSlots = (
+	slots: PlacementSlots | undefined,
+): { stickers: SkinViewerSticker[]; charm: SkinViewerCharm | null } => {
+	if (!slots) return { stickers: [], charm: null }
+	const stickers = slots.slice(0, 5).flatMap((placement): SkinViewerSticker[] => {
+		const sticker = placement as PlacementSlots[0]
+		if (!isPlaced(sticker)) return []
+		return [
+			{
+				id: sticker.sticker_id,
+				slot: sticker.slot as SkinViewerSticker['slot'],
+				wear: sticker.wear,
+				rotation: sticker.rotation,
+				offsetX: sticker.offset_x,
+				offsetY: sticker.offset_y,
+			},
+		]
+	})
+	const keychain = slots[5]
+	const charm: SkinViewerCharm | null = isPlaced(keychain)
+		? {
+				id: keychain.sticker_id,
+				seed: keychain.pattern,
+				offset: [keychain.offset_x, keychain.offset_y, keychain.offset_z],
+			}
+		: null
+	return { stickers, charm }
+}
+
+/* ═════════════════════════════════════════════════════════════════════════════════════════════
+ * THE SUBJECT
+ * ═══════════════════════════════════════════════════════════════════════════════════════════ */
+
+export type ResolvedSubject =
+	| { item: FrameItem; inspectPayload: string | null; error: null }
+	/**
+	 * *** NO ITEM AND NO GUESS. *** Every failure here produces a null item, and `SkinViewer` then asks
+	 * the frame for its instruction card rather than letting it fall back to our default AK - which
+	 * would look exactly like a successful render of the wrong gun, and is the one outcome worth more
+	 * than all the rest of this file to avoid.
+	 */
+	| { item: null; inspectPayload: null; error: SkinViewerError }
+
+/**
+ * A `SkinPlacement` (whatever produced it) as the frame's item.
+ *
+ * Every field maps 1:1 with no rescaling: `g_vStickerNOffset` is `Range2(-0.5,-0.5, 0.5,0.5)` and the
+ * protobuf carries that range verbatim, so the offsets really are the same numbers.
+ */
+const fromPlacement = (placement: SkinPlacement, weaponType: string): FrameItem => {
+	const slots = emptySlots()
+	for (const sticker of placement.stickers ?? []) {
+		if (!isPlaced(sticker)) continue
+		const slot = sticker.slot
+		if (slot < 0 || slot > 4) continue
+		slots[slot as 0 | 1 | 2 | 3 | 4] = sticker
+	}
+	if (placement.keychain && isPlaced(placement.keychain)) slots[5] = placement.keychain
+
+	return {
+		weaponType,
+		paintIndex: placement.paintindex,
+		float: placement.paintwear,
+		seed: placement.paintseed,
+		// `stattrak` present is what makes an item StatTrak and `0` is a real count - see the prop's own
+		// doc for why this collapses to one field rather than two.
+		statTrak: placement.stattrak ? (placement.stattrak_count ?? 0) : false,
+		nameTag: placement.nametag ?? null,
+		stickers: slots,
+	}
+}
+
+/**
+ * *** THE ONE FUNCTION THE WHOLE PROP SURFACE FUNNELS THROUGH. *** Either arm of
+ * {@link ViewerSubject}, plus the runtime cases the types were supposed to prevent, into one item.
+ *
+ * IT IS PURE AND SYNCHRONOUS - no fetch, no React, no catalogue - which is what lets the component
+ * build the frame's URL in a `useState` initialiser and have the FIRST PAINT be the integrator's item
+ * rather than ours swapped a tick later.
+ */
+export const resolveSubject = (subject: Partial<ViewerSubject>): ResolvedSubject => {
+	const fail = (code: SkinViewerError['code'], message: string): ResolvedSubject => ({
+		item: null,
+		inspectPayload: null,
+		error: { code, message },
+	})
+
+	if (typeof subject.inspectLink === 'string' && subject.inspectLink.length > 0) {
+		let placement: SkinPlacement
+		try {
+			placement = readInspectUrl(subject.inspectLink)
+		} catch (cause) {
+			/*
+			 * MASKED LINKS ONLY, and this is where an integrator finds that out. The `S…A…D…` / `M…`
+			 * inventory and market forms carry no item data at all - they needed a Game Coordinator round
+			 * trip Valve has shut down - so there is nothing in them to render and no partial answer to
+			 * fall back to.
+			 */
+			return fail(
+				'bad-inspect-link',
+				`The inspect link did not decode: ${cause instanceof Error ? cause.message : String(cause)}. Only MASKED links (the long hex payload) carry item data; the S…A…D… and M… inventory forms needed a Game Coordinator round trip Valve has shut down and cannot be rendered by anyone.`,
+			)
+		}
+		const weaponType = weaponIdForDefindex(placement.defindex)
+		if (!weaponType)
+			return fail(
+				'unknown-weapon',
+				`The inspect link decoded, but defindex ${placement.defindex} is not a weapon this build of @skinhub/viewer has an id for. Pass \`item={{ weapon: '…', paintIndex: ${placement.paintindex} }}\` instead, or update the package.`,
+			)
+		return {
+			item: fromPlacement(placement, weaponType),
+			/*
+			 * THE ORIGINAL STRING IS KEPT AND FORWARDED AS `?i=` RATHER THAN RE-ENCODED. A round trip
+			 * through our own encoder would be a second implementation of the codec in the URL path, free
+			 * to disagree with the one the frame decodes with; forwarding the customer's own bytes means
+			 * the frame reads exactly what Valve wrote.
+			 */
+			inspectPayload: subject.inspectLink,
+			error: null,
+		}
+	}
+
+	const item = subject.item
+	if (!item || typeof item !== 'object')
+		return fail(
+			'no-item',
+			'No item. <SkinViewer> needs exactly one of `inspectLink` or `item` - in TypeScript that is a compile error, so this is JavaScript, an `any`, or data that had not arrived yet.',
+		)
+
+	const weapon = item.weapon ?? (typeof item.defindex === 'number' ? weaponIdForDefindex(item.defindex) : undefined)
+	if (!weapon)
+		return typeof item.defindex === 'number'
+			? fail(
+					'unknown-weapon',
+					`defindex ${item.defindex} is not a weapon this build of @skinhub/viewer has an id for. Pass \`weapon\` instead, or update the package.`,
+				)
+			: fail(
+					'no-item',
+					'`item` named no weapon. Pass either `weapon: "weapon_ak47"` (from `skin.weapon.id` on a @skinhub/cdn row) or `defindex: 7`.',
+				)
+
+	if (typeof item.paintIndex !== 'number')
+		return fail(
+			'no-item',
+			'`item.paintIndex` is required. `0` is the correct value for a vanilla item and renders the bare model.',
+		)
+
+	return {
+		item: {
+			// HUD aliases folded here rather than at the frame: `skins.json` gives the twenty VANILLA knife
+			// rows an `sfui_wpnhud_*` id, so `row.weapon.id` off a vanilla Bayonet is a HUD string. The
+			// renderer resolves both to the same GLB; folding here also makes the value we echo back in
+			// `onChange` the item id rather than the alias.
+			weaponType: normalizeWeaponId(weapon),
+			paintIndex: item.paintIndex,
+			...(item.legacyModel !== undefined && { legacyModel: item.legacyModel }),
+			...(item.float !== undefined && { float: item.float }),
+			...(item.seed !== undefined && { seed: item.seed }),
+			...(item.statTrak !== undefined && { statTrak: item.statTrak }),
+			...(item.nameTag !== undefined && { nameTag: item.nameTag }),
+			...(() => {
+				const slots = toSlots(item.stickers, item.charm)
+				return slots ? { stickers: slots } : {}
+			})(),
+		},
+		inspectPayload: null,
+		error: null,
+	}
+}
+
+/**
+ * The frame's item as the public one - what {@link SkinViewerProps.onChange} hands back.
+ *
+ * *** ALWAYS THE `{ weapon }` FORM, NEVER `{ defindex }`. *** The frame reports a `weaponType`, and
+ * turning it back into a number is a lookup that can fail for a weapon shipped after this package
+ * was built. An integrator who needs the number has `defindexForWeaponId` exported for it, where the
+ * failure is theirs to see rather than ours to hide.
+ */
+export const toPublicItem = (item: FrameItem): SkinViewerItem => {
+	const { stickers, charm } = fromSlots(item.stickers)
+	return {
+		weapon: item.weaponType,
+		paintIndex: item.paintIndex,
+		...(item.legacyModel !== undefined && { legacyModel: item.legacyModel }),
+		...(item.float !== undefined && { float: item.float }),
+		...(item.seed !== undefined && { seed: item.seed }),
+		...(item.statTrak !== undefined && { statTrak: item.statTrak }),
+		...(item.nameTag !== undefined && { nameTag: item.nameTag }),
+		stickers,
+		charm,
+	}
+}
+
+/* ═════════════════════════════════════════════════════════════════════════════════════════════
+ * BACK OUT AGAIN — AN ITEM AS AN INSPECT LINK
+ *
+ * *** THE RETURN JOURNEY, AND IT IS THE HALF THAT WAS MISSING. *** Everything above turns an
+ * integrator's item INTO a picture. A skin picker is not finished when it can show you the item; it is
+ * finished when it can hand you the link. Without these two functions every integrator writes the same
+ * forty lines against `@skinhub/cdn`'s placement API - and writes them from the same three facts that
+ * are easy to get wrong and silent when you do:
+ *
+ *   - `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.
+ *   - 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
+ * three facts `toSlots` already encodes, and having them written twice is how the two copies disagree.
+ * ═══════════════════════════════════════════════════════════════════════════════════════════ */
+
+/**
+ * A viewer item as a `SkinPlacement` — `@skinhub/cdn`'s decoded-inspect-link shape.
+ *
+ * Reach for this when you want the placement itself: to write WeaponPaints rows, to diff against a
+ * link you already hold, or to hand to another `@skinhub/cdn` helper. If you just want the link, use
+ * {@link toInspectLink}.
+ *
+ * *** THROWS ON A WEAPON WITH NO DEFINDEX, and that is the only honest answer. *** An inspect link
+ * identifies its item by number, so an id this build has no row for cannot be encoded at all. Returning
+ * a link with `defindex: 0` in it would produce a string that looks like a link, copies like a link and
+ * opens an empty CS2 inspect screen.
+ */
+export const toPlacement = (item: SkinViewerItem): SkinPlacement => {
+	const weapon = 'weapon' in item && item.weapon ? item.weapon : undefined
+	const defindex = weapon ? defindexForWeaponId(weapon) : item.defindex
+	if (typeof defindex !== 'number')
+		throw new Error(
+			`@skinhub/viewer: cannot build an inspect link for ${JSON.stringify(weapon)} — this build has no defindex for it. Pass \`defindex\` on the item, or update the package.`,
+		)
+
+	const slots = toSlots(item.stickers, item.charm) ?? emptySlots()
+	return makeSkinPlacement({
+		defindex,
+		paintindex: item.paintIndex,
+		paintseed: item.seed ?? 0,
+		paintwear: item.float ?? 0,
+		...(item.nameTag ? { nametag: item.nameTag } : {}),
+		// `statTrak: 0` is a counter that has not counted yet. `false` is no module at all.
+		stattrak: item.statTrak !== undefined && item.statTrak !== false,
+		stattrak_count: typeof item.statTrak === 'number' ? item.statTrak : 0,
+		stickers: slots.slice(0, 5) as SkinPlacement['stickers'],
+		keychain: slots[5],
+	} as SkinPlacement)
+}
+
+/**
+ * A viewer item as a masked Steam inspect link — the string a user pastes into the game.
+ *
+ *     <button onClick={() => navigator.clipboard.writeText(toInspectLink(item))}>Copy inspect link</button>
+ *
+ * The inverse of passing `inspectLink` to `<SkinViewer>`, and it round-trips: a link built here decodes
+ * back to the same item through {@link fromInspectLink}.
+ */
+export const toInspectLink = (item: SkinViewerItem): string => buildInspectUrl(toPlacement(item))
+
+/**
+ * A masked inspect link as a viewer item — what `<SkinViewer inspectLink={…} />` does internally,
+ * exposed for a host that wants the fields rather than the picture (to seed an editor from a link, or
+ * to read a float out of one).
+ *
+ * *** RETURNS `null` RATHER THAN THROWING ON A LINK IT CANNOT READ, *** because the input is usually
+ * something a user pasted, and a paste being wrong is an ordinary event rather than an exception.
+ */
+export const fromInspectLink = (link: string): SkinViewerItem | null => {
+	const resolved = resolveSubject({ inspectLink: link })
+	return resolved.item ? toPublicItem(resolved.item) : null
+}

package/src/link.ts

@@ -0,0 +1,33 @@
+/**
+ * *** THE PRIVATE CHANNEL BETWEEN THE HOOK AND THE COMPONENT. ***
+ *
+ * `useSkinViewer()` returns a handle; `<SkinViewer handle={…} />` fills it in. Something has to carry
+ * `reload` from the component that can do it to the object that exposes it, and carry `status` back
+ * the other way.
+ *
+ * *** A SYMBOL KEY RATHER THAN `__internal`, *** for one practical reason: a symbol does not appear in
+ * an editor's autocomplete on the handle, so the only members an integrator ever sees are the four
+ * documented ones. It is not hiding - anyone can reach it - it is keeping the public surface exactly
+ * as large as the documentation says it is.
+ *
+ * *** AND IT IS A MUTABLE OBJECT RATHER THAN A CALLBACK PROP, *** because the identity of the thing
+ * passed as `handle` must never change: it is a plain prop on a component that re-renders on every
+ * frame of a float drag, and a fresh object there would be one more thing to compare per frame.
+ */
+
+import type { SkinViewerError, ViewerStatus } from './types.js'
+
+export const LINK: unique symbol = Symbol('@skinhub/viewer/link')
+
+export type ViewerSnapshot = {
+	status: ViewerStatus
+	error: SkinViewerError | null
+	problems: readonly string[]
+}
+
+export type ViewerLink = {
+	/** Replaced by the mounted component; a no-op before mount and after unmount. */
+	reload: () => void
+	/** The component pushing its state up. Bails when nothing moved - see `useSkinViewer`. */
+	publish: (snapshot: ViewerSnapshot) => void
+}

package/src/protocol.ts

@@ -0,0 +1,241 @@
+/**
+ * *** THE HOST HALF OF THE WIRE. *** `@skinhub/viewer/protocol`.
+ *
+ * The frame's half is `app/frame/protocol.ts` inside the SkinHub app, which is a PRIVATE repository -
+ * it carries the renderer, the shader transcriptions and the export-fed material pipeline. That half
+ * is the specification. This is the same contract written from the other end of the channel.
+ *
+ * *** THE TWO FILES ARE NOT SHARED CODE AND CANNOT BE - and the reason is not that they now live in
+ * different repositories, it is what each one is MADE OF. *** The frame's half is typed in the
+ * renderer's own prop types and validates against the renderer's map list, its view enum and its
+ * placement defaults; a customer's bundle must not carry any of that. This half is typed in plain
+ * data and uses no vocabulary a customer cannot find documented in `EMBED.md`. Merging them means
+ * either shipping the renderer's surface to every integrator, or making the specification depend on a
+ * published package in order to describe itself.
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** SO THE DUPLICATION IS DELIBERATE - AND IT IS CHECKED BY A MACHINE, IN TWO PLACES. ***
+ *
+ *   1. `test/wire.test.ts`, HERE. Every name and every field this file puts on the wire is frozen in
+ *      a literal, and the literals are checked EXHAUSTIVE against the types, so a field cannot be
+ *      added to the wire without the freeze failing to compile. That is what makes an edit to this
+ *      file deliberate rather than incidental, and it is the moment you are told to go and change the
+ *      frame and bump {@link FRAME_PROTOCOL_VERSION}.
+ *
+ *   2. `app/frame/protocol.conformance.test.ts`, IN THE APP REPO - the only place both halves exist
+ *      at once. It feeds this file's own `hostMessage()` output through the frame's real validator and
+ *      requires ZERO rejected fields, feeds the frame's real events through {@link readFrameEvent},
+ *      and compares the two key sets at the type level. That is the check that actually catches drift,
+ *      because it exercises the frame's reader rather than a restatement of it.
+ *
+ * *** THE VERSION INTEGER IS THE BACKSTOP, NOT THE CHECK, and the difference is the whole point. ***
+ * A mismatch is terminal on both sides - the frame renders nothing and names which side is stale, this
+ * package stops sending - so a mismatch that HAPPENS is loud. But it only happens if somebody
+ * remembered to bump the integer. The failure the two checks above exist for is the other one: a field
+ * added to the frame, the integer left alone, both sides claiming `v: 1`, and the field silently
+ * dropped. A silently wrong render is worse than a blank frame with an explanation, and this project
+ * has been bitten by that class of failure repeatedly.
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** THE VOCABULARY HERE IS THE FRAME'S, NOT THE INTEGRATOR'S. ***
+ *
+ * `weaponType`, `sticker_id`, `offset_x` - the renderer's own names and the game's own field names.
+ * `item.ts` translates between this and `types.ts`, and that translation is the package's actual job:
+ * an integrator writing `offset_x` into a React tree is writing protobuf into their view layer.
+ *
+ * *** WHICH IS WHY THIS IS A SEPARATE ENTRY POINT AND NOT PART OF THE BARREL. *** It is exported at
+ * all because the wire is ALREADY public - `EMBED.md` §6 documents this envelope, this patch and these
+ * events in full, for the PHP / Vue / plain-`<script>` hosts the URL contract exists for - so
+ * withholding the TypeScript for a shape we publish in prose bought nothing, and made the conformance
+ * check above impossible to write. It carries no compatibility promise beyond the integer: it moves
+ * when the wire moves, which is the whole no-back-compat bargain. Reach for `SkinViewer` from the
+ * barrel unless you are writing a host in something that is not React.
+ */
+
+import type { KeychainPlacement, StickerPlacement } from '@skinhub/cdn/placement'
+
+/**
+ * The discriminator on every message in both directions.
+ *
+ * It exists because `window.postMessage` is a shared bus: React DevTools, Next's dev overlay, HMR,
+ * wallet extensions and analytics tags all post into and out of frames, and several post objects with
+ * a `type` field. Anything without this key is not ours and is dropped in silence.
+ */
+export const FRAME_CHANNEL = 'skinhub-viewer'
+
+/**
+ * The protocol version this package speaks.
+ *
+ * *** AN INTEGER, NOT A SEMVER RANGE, because there is no range: *** there is no back-compat window
+ * and never will be. Two integers either match or they do not, and the failure text can
+ * then say which side is behind.
+ *
+ * *** IT IS ALSO THE PACKAGE'S EXPIRY DATE, AND THAT IS THE INTENT. *** When we change the wire, every
+ * published copy of this package stops working loudly and at once. That is the cost of the no-back-compat
+ * decision and it is paid deliberately, in exchange for never shipping a viewer that renders a
+ * partly-understood item.
+ */
+export const FRAME_PROTOCOL_VERSION = 1
+
+/* ═════════════════════════════════════════════════════════════════════════════════════════════
+ * THE STATE, IN THE FRAME'S WORDS
+ * ═══════════════════════════════════════════════════════════════════════════════════════════ */
+
+/** Five stickers plus the charm in slot 5. The frame validates the SHAPE of this and nothing else. */
+export type PlacementSlots = [
+	StickerPlacement,
+	StickerPlacement,
+	StickerPlacement,
+	StickerPlacement,
+	StickerPlacement,
+	KeychainPlacement,
+]
+
+export type FrameItem = {
+	/** `weapon_ak47`, or a glove id. The key the renderer's model table resolves. */
+	weaponType: string
+	paintIndex: number
+	legacyModel?: boolean
+	float?: number
+	seed?: number
+	statTrak?: number | false
+	nameTag?: string | null
+	stickers?: PlacementSlots
+}
+
+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 }
+	overlays?: {
+		stickerGizmo?: boolean
+		charmGizmo?: boolean
+		gizmoStyle?: { color?: string; shadowColor?: string }
+	}
+}
+
+export type FrameInteractions = {
+	orbit?: boolean
+	zoom?: boolean
+	dragStickers?: boolean
+	dragCharm?: boolean
+}
+
+/** Everything `/frame` holds. One field per prop of the renderer that a host can set. */
+export type FrameState = {
+	item: FrameItem
+	view: 'gun' | 'hands' | 'agent'
+	agent: { id: number; pose?: string | null }
+	gloves: { type: string; paintIndex: number; float?: number; seed?: number } | null
+	settings: FrameSettings
+	interactions: FrameInteractions
+	editingSlot: number
+}
+
+/**
+ * A partial write over {@link FrameState}.
+ *
+ * *** EVERY OBJECT MERGES BY FIELD AND AN ABSENT KEY MEANS "LEAVE IT ALONE". *** That rule is not a
+ * convenience, it is the cheap-update contract: `{ item: { float } }` keeps `weaponType`, so the
+ * frame's loading gate - which is keyed on the identity VALUES - does not move. A patch that replaced
+ * rather than merged would blank the weapon on every float tick.
+ */
+export type FramePatch = {
+	item?: Partial<FrameItem>
+	view?: FrameState['view']
+	agent?: Partial<FrameState['agent']>
+	gloves?: FrameState['gloves']
+	settings?: FrameSettings
+	interactions?: FrameInteractions
+	editingSlot?: number
+}
+
+/* ═════════════════════════════════════════════════════════════════════════════════════════════
+ * THE MESSAGES
+ * ═══════════════════════════════════════════════════════════════════════════════════════════ */
+
+type Envelope = { channel: typeof FRAME_CHANNEL; v: number; from: 'host' | 'viewer' }
+
+export type HostMessage = (Envelope & { type: 'hello' }) | (Envelope & { type: 'set'; patch: FramePatch })
+
+export type FrameErrorCode = 'render-failed' | 'bad-inspect-link' | 'bad-message' | 'protocol-mismatch'
+export type FrameError = { code: FrameErrorCode; message: string }
+
+export type FrameEvent =
+	| (Envelope & { type: 'hello'; state: FrameState; problems: string[] })
+	| (Envelope & { type: 'ready' })
+	| (Envelope & { type: 'error'; error: FrameError })
+	| (Envelope & { type: 'change'; item: FrameItem })
+	| (Envelope & { type: 'editing-slot'; slot: number })
+	| (Envelope & { type: 'resize'; width: number; height: number; dpr: number })
+
+/** Stamps the envelope, so no call site can forget the channel, the version or the direction. */
+export const hostMessage = (patch?: FramePatch): HostMessage =>
+	patch
+		? { channel: FRAME_CHANNEL, v: FRAME_PROTOCOL_VERSION, from: 'host', type: 'set', patch }
+		: { channel: FRAME_CHANNEL, v: FRAME_PROTOCOL_VERSION, from: 'host', type: 'hello' }
+
+/* ═════════════════════════════════════════════════════════════════════════════════════════════
+ * READING WHAT COMES BACK
+ * ═══════════════════════════════════════════════════════════════════════════════════════════ */
+
+export type FrameEventReading =
+	/** Not ours - HMR, an extension, another library, or our own message echoing. Drop it silently. */
+	| { kind: 'ignore' }
+	/** Ours, and the versions disagree. Terminal. */
+	| { kind: 'mismatch'; error: FrameError }
+	| { kind: 'event'; event: FrameEvent }
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/**
+ * One arriving `MessageEvent.data`, classified.
+ *
+ * *** THE HOST SIDE CHECKS THE VERSION TOO, AND IT IS NOT REDUNDANT WITH THE FRAME'S CHECK. *** The
+ * frame only learns about a mismatch once the host has SENT something. A host that configures the
+ * viewer entirely from props and never changes them still receives `hello`, `ready` and `change` - and
+ * if the frame is newer, those payloads may have moved. Reading them anyway is how a stale package
+ * hands its user a `change` event with half an item in it, which is the exact failure mode
+ * the no-back-compat rule forbids. So a mismatch heard here is fatal here as well.
+ *
+ * `from: 'viewer'` IS CHECKED because both directions share one channel and both have a `hello`.
+ * Without it a host that also embeds another host's frame could read its own outbound traffic.
+ */
+export const readFrameEvent = (data: unknown): FrameEventReading => {
+	if (!isRecord(data) || data.channel !== FRAME_CHANNEL || data.from !== 'viewer') return { kind: 'ignore' }
+
+	if (data.v !== FRAME_PROTOCOL_VERSION)
+		return { kind: 'mismatch', error: { code: 'protocol-mismatch', message: versionMessage(data.v) } }
+
+	if (typeof data.type !== 'string') return { kind: 'ignore' }
+	/*
+	 * A VERB THIS BUILD DOES NOT HAVE, ON A VERSION IT DOES: only possible if the frame gained an event
+	 * without bumping the integer, which is our mistake and not the integrator's. Dropped rather than
+	 * reported, because there is nothing they could do about it and an error they cannot act on is
+	 * noise in their console.
+	 */
+	if (!KNOWN_EVENTS.has(data.type)) return { kind: 'ignore' }
+
+	return { kind: 'event', event: data as unknown as FrameEvent }
+}
+
+const KNOWN_EVENTS: ReadonlySet<string> = new Set(['hello', 'ready', 'error', 'change', 'editing-slot', 'resize'])
+
+/**
+ * The sentence a developer reads when the versions disagree - the whole of what the no-back-compat
+ * decision buys, so it names the DIRECTION rather than just the numbers.
+ *
+ * A PACKAGE BEHIND THE EMBED is the ordinary case and the one with an action attached: they installed
+ * `@skinhub/viewer` some months ago and we have shipped a protocol change since. Updating fixes it.
+ *
+ * A PACKAGE AHEAD OF THE EMBED means the embedded document is stale - almost always a cached
+ * `/frame` - so the action is a reload rather than an install. Telling somebody to update a package
+ * that is already newer would send them to the one place that cannot help.
+ */
+const versionMessage = (received: unknown): string => {
+	const seen = typeof received === 'number' ? received : JSON.stringify(received)
+	if (typeof received === 'number' && received < FRAME_PROTOCOL_VERSION)
+		return `@skinhub/viewer speaks protocol ${FRAME_PROTOCOL_VERSION} and the embed answered with ${seen}. The embedded page is out of date - it is cached, or the origin you pointed at is running an older build. Nothing has been rendered, deliberately: a partly-understood message would render a partly-correct item.`
+	return `@skinhub/viewer speaks protocol ${FRAME_PROTOCOL_VERSION} and the embed answered with ${seen}. This package is out of date - update @skinhub/viewer. Nothing has been rendered, deliberately: a partly-understood message would render a partly-correct item.`
+}