@skinhub/viewer 0.2.0 → 0.2.1

package/EMBED.md

@@ -522,16 +522,18 @@ Honest list, so none of it is discovered late.
   and remove it on `ready`.
 - **Click-through.** See §9.
 - **Server-side rendering.** The viewer is WebGL; there is no server-rendered fallback image.
-- **Render to an image.** There is no `capture()` yet. If you need a PNG per item, that is a separate
-  service and is not built.
-- **Resolve an inspect link on its own.** `?i=` carries the item's *configuration* — float, seed,
-  StatTrak, name plate, stickers, charm — but not which weapon, so a raw-iframe integration still has
+- **Render to an image.** There is no `capture()`: the canvas runs without a preserved drawing buffer,
+  so a read from outside the render loop comes back blank. A PNG per item wants a render with no
+  browser tab open anyway, and that is a separate service and is not built.
+- **Resolve an inspect link on its own.** `?i=` carries the item's *configuration* - float, seed,
+  StatTrak, name plate, stickers, charm - but not which weapon, so a raw-iframe integration still has
   to send `?weapon=`/`?paint=` (or `?hash=`) alongside it.
   **This limit is the frame's, not the product's:** `@skinhub/viewer` takes an `inspectLink` prop and
   handles the whole thing, because it decodes host-side and resolves the `defindex` against its own
   weapon table before building the URL. If you are in React, you never see this.
-- **Show a sticker, charm, agent or collectible on its own.** The embed renders a weapon or a glove
-  today. The rest of our catalogue has pages on our site but is not yet embeddable.
+- **Draw two subjects at once.** One frame shows one thing - a weapon or glove, a sticker, a charm, a
+  collectible, or an operator (§2). An operator shown as the subject holds no weapon, and the four
+  standalone subjects ignore `?view=`, `?i=`, `?float=`, `?slot=` and the sticker slots.
 - **Style anything.** The frame is our document. `gizmocolor` and `gizmoshadow` are the only visual
   hooks.
 - **Two viewers cheaply.** Each frame is its own WebGL context. If you need a grid of them, drop

package/README.md

@@ -1,8 +1,9 @@
 # @skinhub/viewer
 
-The SkinHub CS2 skin viewer as a React component — any weapon, knife or glove, at any wear and seed,
-with stickers and a charm. The 3D runs in an iframe on our origin, so installing this pulls in no
-`three` and no assets. React is the only peer dependency.
+The SkinHub CS2 skin viewer as a React component - any weapon, knife or glove, at any wear and seed,
+with stickers and a charm, or a sticker, charm, collectible or agent on its own. The 3D runs in an
+iframe on our origin, so installing this pulls in no `three` and no assets. React is the only peer
+dependency.
 
 ```bash
 bun add @skinhub/viewer @skinhub/cdn
@@ -21,13 +22,23 @@ export default function Page() {
 }
 ```
 
-Or straight from a Steam inspect link — float, seed, StatTrak, name plate, stickers and charm all come
+Or straight from a Steam inspect link - float, seed, StatTrak, name plate, stickers and charm all come
 out of it:
 
 ```tsx
 <SkinViewer inspectLink={item.inspectLink} style={{ width: 640, height: 420 }} />
 ```
 
+A weapon is one of five things the viewer draws, and each of the other four is its own prop. They are
+drawn on their own, with no gun in the picture:
+
+```tsx
+<SkinViewer sticker={{ id: 37, wear: 0.2 }} />   // the real holo/foil shader, not an image on a plane
+<SkinViewer charm={{ id: 5 }} />
+<SkinViewer collectible={{ id: 874 }} />         // a pin, coin, medal or trophy
+<SkinViewer operator={{ id: 5036 }} />           // an agent, alone
+```
+
 Two things worth knowing up front:
 
 - **Give it a size.** It fills its container and has no intrinsic size; at 0 px you see nothing.
@@ -36,34 +47,44 @@ Two things worth knowing up front:
 
 ## Props
 
-One of `item` or `inspectLink` is required. Everything else is optional.
+Exactly one subject is required - `item`, `inspectLink`, `sticker`, `charm`, `collectible` or
+`operator`. Passing two, or none, is a type error. Everything else is optional.
 
 | prop | type | default | |
 |---|---|---|---|
-| `item` | `{ weapon \| defindex, paintIndex, float?, seed?, statTrak?, nameTag?, legacyModel?, stickers?, charm? }` | — | the item. `paintIndex: 0` is vanilla |
-| `inspectLink` | `string` | — | a masked Steam inspect link, instead of `item` |
+| `item` | `{ weapon \| defindex, paintIndex, float?, seed?, statTrak?, nameTag?, legacyModel?, stickers?, charm? }` | - | the item. `paintIndex: 0` is vanilla |
+| `inspectLink` | `string` | - | a masked Steam inspect link, instead of `item` |
+| `sticker` | `{ id, wear? }` | - | one sticker on nothing. `wear` is `0` (mint) to `1` |
+| `charm` | `{ id, pattern? }` | - | one charm. `pattern` is its colour template, not a different model |
+| `collectible` | `{ id }` | - | one pin, coin, medal or trophy. It has no other field |
+| `operator` | `{ id, pose? }` | - | one agent alone. `pose` is a main-menu clip name, `null` for their idle |
 | `origin` | `string` | `https://skinhub.gg` | where the embed is served. Read once, on mount |
 | `view` | `'gun' \| 'hands' \| 'agent'` | `'gun'` | item alone, first-person, or held by an operator |
-| `agent` | `{ id, pose? }` | default T | the operator, in `hands` and `agent` |
+| `agent` | `{ id, pose? }` | default T | who is *holding* the weapon, in `hands` and `agent`. `operator` is the agent shown alone |
 | `gloves` | `{ type, paintIndex, float?, seed? } \| null` | `null` | `null` is the wearer's own pair |
 | `settings` | `{ camera?, quality?, environment?, overlays? }` | see below | shallow-merged per group |
 | `interactions` | `{ orbit?, zoom?, dragStickers?, dragCharm? }` | orbit + zoom on | what the user may do |
 | `editingSlot` | `number` | `-1` | which sticker slot is open; `5` is the charm |
-| `onReady` | `() => void` | — | stopped loading — **a level, not an edge**: it fires again after every weapon or view change |
-| `onError` | `(error) => void` | — | `no-item`, `bad-inspect-link`, `unknown-weapon`, `unreachable`, `render-failed`, `protocol-mismatch`, `bad-message` |
-| `onChange` | `(item) => void` | — | the user dragged a sticker or the charm — **carries ids, not names**, see below |
-| `onResize` | `({ width, height, dpr }) => void` | — | the canvas box changed |
-| `onEditingSlotChange` | `(slot) => void` | — | |
-| `loading` / `fallback` | `ReactNode` | — | your skeleton, and your empty state on error |
+| `onReady` | `() => void` | - | stopped loading - **a level, not an edge**: it fires again after every weapon or view change |
+| `onError` | `(error) => void` | - | `no-item`, `bad-inspect-link`, `unknown-weapon`, `unreachable`, `render-failed`, `protocol-mismatch`, `bad-message` |
+| `onChange` | `(item) => void` | - | the user dragged a sticker or the charm - **carries ids, not names**, see below |
+| `onResize` | `({ width, height, dpr }) => void` | - | the canvas box changed |
+| `onEditingSlotChange` | `(slot) => void` | - | |
+| `loading` / `fallback` | `ReactNode` | - | your skeleton, and your empty state on error |
 | `className` / `style` / `title` | | | on the wrapper |
-| `handle` | `SkinViewerHandle` | — | from `useSkinViewer()` |
+| `handle` | `SkinViewerHandle` | - | from `useSkinViewer()` |
 
 `settings.environment.background` defaults to `'transparent'`, so the canvas composites over your page.
 `quality.bloomSpill` ships at `0` here. `MAP_NAMES` and `WEAPON_IDS` are exported as values for
 building pickers.
 
-Changing `float`, `seed`, `statTrak`, `nameTag`, `stickers` or `charm` updates **in place** — no
-reload, no flicker. Changing the weapon, paint index, legacy variant or view shows a loading cover.
+`view`, `agent`, `gloves` and `editingSlot` describe a weapon, and the other four subjects ignore them.
+`settings` and `interactions` apply to all six.
+
+Changing `float`, `seed`, `statTrak`, `nameTag`, `stickers` or `charm` updates **in place** - no
+reload, no flicker. Changing the weapon, paint index, legacy variant or view shows a loading cover. On
+the other four subjects `sticker.wear`, `charm.pattern` and `operator.pose` are the in-place ones; the
+id, and switching which subject you pass, reloads.
 
 ### Copying the item back out
 
@@ -79,7 +100,7 @@ the decoded `@skinhub/cdn` placement if you want to write database rows instead.
 ### `onChange` gives you ids, not names
 
 The embed has never seen the sticker catalogue, so the item it hands back has `stickers: [{ id: 5032,
-… }]` and no name or image. **`setItem(changed)` will therefore blank those out of your own UI** — a
+… }]` and no name or image. **`setItem(changed)` will therefore blank those out of your own UI** - a
 silent data loss in your state, with nothing to catch. Merge it into what you already hold instead:
 
 ```tsx
@@ -104,7 +125,7 @@ instance while developing:
 <SkinViewer item={item} origin="http://localhost:3000" />
 ```
 
-It is read once, at mount — it is the one prop that could only be applied by reloading the frame.
+It is read once, at mount - it is the one prop that could only be applied by reloading the frame.
 
 ## useSkinViewer()
 
@@ -123,31 +144,31 @@ viewer.reload()
 
 **A CORS error fetching the catalogue.** `cdn.skinhub.gg` does not send
 `access-control-allow-origin`, so a **browser** `fetch` for `data/skins.json` is blocked by the
-browser before your code sees it — it surfaces as a CORS failure rather than a status, so you cannot
+browser before your code sees it - it surfaces as a CORS failure rather than a status, so you cannot
 even catch it. Call `@skinhub/cdn` from your **server** (a route handler, `getServerSideProps`, an RSC)
 and pass the rows down. The files are 4–6 MB each, so you want them server-side regardless.
 
 **Nothing renders.** If the container is 0 px in one dimension you get an empty box; the component
 warns about that in development. Otherwise `onError` reports `unreachable` after 15 seconds, naming the
-URL it could not reach — that means the embed never answered, so check the origin is reachable from
+URL it could not reach - that means the embed never answered, so check the origin is reachable from
 this browser and that your page's `Content-Security-Policy` allows framing it (`frame-src`).
 
 **`onReady` fired but the picture is still covered.** `onReady` means "stopped loading" for the current
 identity, and it fires again after every weapon or view change. Treat it as a level, not an edge.
 
 **`protocol-mismatch`.** This package and the embed disagree about the wire. There is no back-compat
-window by design: update `@skinhub/viewer`, or reload the embed if it is the stale one — the error
+window by design: update `@skinhub/viewer`, or reload the embed if it is the stale one - the error
 message says which.
 
 ## More
 
-- **[Quick-start app](https://github.com/SkinHubgg/skinhub-quick-start)** — a working skin picker built
+- **[Quick-start app](https://github.com/SkinHubgg/viewer-quick-start)** - a working skin picker built
   on this and `@skinhub/cdn`, ending in an inspect link. The full example.
-- **[EMBED.md](./EMBED.md)** — the raw `<iframe>` URL and `postMessage` contract, for stacks that are
+- **[EMBED.md](./EMBED.md)** - the raw `<iframe>` URL and `postMessage` contract, for stacks that are
   not React. A PHP, Rails or plain-HTML page can interpolate an item into an `src` and be done; that
   path is first-class, not a fallback.
-- **[@skinhub/cdn](https://github.com/SkinHubgg/skinhub-cdn)** — the CS2 catalogue this pairs with:
+- **[@skinhub/cdn](https://github.com/SkinHubgg/skinhub-cdn)** - the CS2 catalogue this pairs with:
   skins, stickers, gloves, agents, and the inspect-link codec.
-- [Development and releasing](./CONTRIBUTING.md) — how the wire is kept in step with the embed.
+- [Development and releasing](./CONTRIBUTING.md) - how the wire is kept in step with the embed.
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@skinhub/viewer",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"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",