@skinhub/viewer 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,573 @@
+/**
+ * *** `@skinhub/viewer` - THE PUBLIC PROP CONTRACT. ***
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** WHAT THIS PACKAGE IS, AND THE ONE SENTENCE THAT DECIDES EVERY QUESTION BELOW. ***
+ *
+ * The renderer is a page on our origin (`/frame`). This package renders an `<iframe>` at it and
+ * speaks its message protocol. Owner, 2026-08-15: *"the package is just a lightweight helper that
+ * translates the postMessages thing to actual props and state that the user can control."*
+ *
+ * *** SO THERE IS NO `three` HERE AND THERE NEVER WILL BE. *** The design rule is *"there is no raw
+ * npm renderer, ever."* An integrator installing this installs React bindings and a URL builder. The
+ * whole of the 3D - the models, the shaders, the compositing, the 19.7 GB asset export - stays on our
+ * side of the frame, which is what makes the logo enforceable and what removes every peer-dependency
+ * question about three.js at once.
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** THE RULE THIS FILE IS WRITTEN UNDER: nothing here may require knowing how SkinHub is built. ***
+ *
+ * Every name is either a word the CS2 economy already uses (`paintIndex`, `float`, `seed`,
+ * `defindex`, `statTrak`) or a word any 3D component uses (`view`, `camera`, `quality`, `bloom`).
+ * Nothing is named after a route, a store, a shader parameter or a file in our tree. A prop that only
+ * makes sense once you have read our source is a bug in this file.
+ *
+ * *** AND ONE COROLLARY WORTH STATING, because it is the difference between a wrapper and a leak: ***
+ * this file does NOT re-export `/frame`'s own vocabulary. The wire says `weaponType` and
+ * `PlacementSlots` in the game's field names (`sticker_id`, `offset_x`); an integrator says `weapon`
+ * and `{ id, offsetX }`. `item.ts` is the only place the two meet, and it is not exported for the
+ * public surface's sake - it is exported because a marketplace holding an inspect link needs the
+ * bridge in its own server code too.
+ */
+import type { CSSProperties, ReactNode } from 'react';
+import { LINK, type ViewerLink } from './link.js';
+import type { WeaponId } from './weapons.js';
+/**
+ * A sticker on one of the weapon's five slots.
+ *
+ * `offsetX`/`offsetY` are a DELTA on the slot's authored home, in the weapon's sticker UV space,
+ * clamped to +/-0.5 - the game's own `g_vStickerNOffset` range. Omitted means "where the weapon puts
+ * it", which is what an unmodified applied sticker looks like in game.
+ */
+export type SkinViewerSticker = {
+    /** `sticker_id` - the id in `@skinhub/cdn`'s `stickers.json`. */
+    id: number;
+    /**
+     * Which of the five slots, `0`..`4`. Omitted uses the sticker's position in the `stickers` array,
+     * which is what makes `stickers={[a, null, b]}` mean "slot 0 and slot 2".
+     */
+    slot?: 0 | 1 | 2 | 3 | 4;
+    /** Scratch, `0` (mint) to `1` (scraped off). Default `0`. */
+    wear?: number;
+    /** Degrees, any value; `370` renders as `10`. Default `0`. */
+    rotation?: number;
+    /** -0.5..0.5. Default `0` - the slot's authored position. */
+    offsetX?: number;
+    offsetY?: number;
+};
+/** A charm hanging off the weapon's charm anchor. Knives have no anchor and ignore this. */
+export type SkinViewerCharm = {
+    /** The id in `@skinhub/cdn`'s `keychains.json`. */
+    id: number;
+    /**
+     * The charm's template - its `pattern` on the wire. It is 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 `seed` are the same model in different colours. Default `0`.
+     */
+    seed?: number;
+    /**
+     * Displacement from the weapon's charm anchor, in the game's own `offset x/y/z`. Omitted hangs it
+     * where the weapon hangs it. Values outside the authored charm region are pulled back into it by
+     * the renderer rather than rejected.
+     *
+     * *** `readonly` IS AN INPUT CONVENIENCE AND AN OUTPUT NUISANCE, so it is worth stating: *** a
+     * mutable `[number, number, number]` assigns to this fine, which is what makes passing one in easy.
+     * Reading it back off an `onChange` item gives you the readonly type, so moving one axis needs a
+     * copy - `[...charm.offset]` - rather than an index write.
+     */
+    offset?: readonly [x: number, y: number, z: number];
+};
+/** The half of an item that is not its identity. Everything here updates IN PLACE - see {@link CHEAP_FIELDS}. */
+type ItemConfiguration = {
+    /**
+     * The finish. `1449` is AK-47 | AUTOEXEC, `0` is the correct value for a VANILLA item and renders
+     * the bare model rather than an error.
+     */
+    paintIndex: number;
+    /**
+     * Which mesh variant to load. Most finishes declare it themselves and this is then ignored; pass it
+     * when they do not, from `skin.legacy_model` on the `@skinhub/cdn` row you already have.
+     *
+     * IT IS IDENTITY AND NOT A DETAIL: both the weapon-space textures and the composite scale constants
+     * are authored per variant, so the wrong one is the wrong picture rather than a slightly different
+     * one. 1,182 of 2,161 catalogue rows are legacy.
+     */
+    legacyModel?: boolean;
+    /**
+     * Wear, `0`..`1`. `paintwear` on the wire; every marketplace calls it the float.
+     *
+     * NOT EVERY FINISH RUNS 0..1. A kit declares its own `wear_remap_min`/`wear_remap_max` and the
+     * renderer CLAMPS into that range rather than remapping, so `0.9` on a kit that stops at `0.4`
+     * renders at `0.4`. If you are drawing a float slider, take the kit's real range from
+     * `@skinhub/cdn` rather than assuming 0..1.
+     *
+     * Omitted renders at the kit's own best condition, which is the flattering example of the item.
+     */
+    float?: number;
+    /** The paint seed - which roll of the finish this is. Default `0`. */
+    seed?: number;
+    /**
+     * The StatTrak counter's value, or `false` for an item with no counter.
+     *
+     * ONE FIELD RATHER THAN A BOOLEAN AND A COUNT, because that is what the item is: the game has no
+     * StatTrak-with-no-count. `0` is a real, legal, freshly-minted counter and is NOT the same as
+     * `false`. Default `false`.
+     */
+    statTrak?: number | false;
+    /** The name plate's text, or `null`/omitted for no plate. Trimmed; the game shows 20 characters. */
+    nameTag?: string | null;
+    /**
+     * Up to five stickers. Array position is the slot unless a sticker names its own; `null` leaves a
+     * slot empty, so `[a, null, b]` is slots 0 and 2.
+     */
+    stickers?: readonly (SkinViewerSticker | null)[];
+    /** The charm, or `null`/omitted for none. */
+    charm?: SkinViewerCharm | null;
+};
+/**
+ * *** WHICH ITEM FIELDS UPDATE IN PLACE, WRITTEN DOWN AS A VALUE. ***
+ *
+ * The owner's requirement, verbatim: changing `float`, `seed`, `statTrak`, `nameTag`, the stickers or
+ * the charm *"must NOT reload the viewer - that's a must to make it feel just like in our website."*
+ * Changing the weapon or the paint kit *"shows nothing until the model has loaded, behind the loading
+ * card"*.
+ *
+ * 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.
+ */
+export declare const CHEAP_FIELDS: readonly ["float", "seed", "statTrak", "nameTag", "stickers", "charm"];
+/**
+ * *** WHICH WEAPON, SAID TWO WAYS, AND EXACTLY ONE OF THEM. ***
+ *
+ * An integrator holds a catalogue row (`weapon: 'weapon_ak47'`, which is `skin.weapon.id` on a
+ * `@skinhub/cdn` row) or a decoded inspect link (`defindex: 7`). Both are the AK-47.
+ *
+ * `?: never` ON THE OTHER MEMBER rather than a runtime check, for the same reason the top-level
+ * subject union uses it: an item naming a weapon two ways that disagree is a state with no sensible
+ * precedence rule, so it is made unrepresentable instead of arbitrated.
+ *
+ * `weapon` IS THE ONE TO REACH FOR. It needs no lookup and therefore cannot go stale; `defindex` is
+ * resolved against a checked-in 63-row table (see `weapons.ts`) and a number that table has never
+ * heard of reports `unknown-weapon` rather than rendering the wrong gun.
+ */
+export type SkinViewerItem = ItemConfiguration & ({
+    /**
+     * `'weapon_ak47'`, or a glove id (`'sporty_gloves'`). HUD aliases are accepted: `skins.json`
+     * gives the twenty VANILLA knife rows an `sfui_wpnhud_*` id, and that renders the knife here
+     * rather than failing, so `row.weapon.id` can be passed straight through.
+     */
+    weapon: WeaponId;
+    defindex?: never;
+} | {
+    /** `7` - the item definition index a decoded inspect link and a Steam inventory row carry. */
+    defindex: number;
+    weapon?: never;
+});
+/**
+ * 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.
+ *
+ *   `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.
+ *   `agent`   an operator holding the weapon, at conversational distance, orbitable.
+ *
+ * *** A VIEW CHANGE RELOADS. *** It rebuilds the rig, so it goes behind the loading card exactly as a
+ * weapon change does.
+ */
+export type ViewerView = 'gun' | 'hands' | 'agent';
+/** The person holding the weapon, in `hands` and `agent`. Ignored in `gun` - nobody is on screen. */
+export type ViewerAgent = {
+    /** An agent's item definition index; `5036` is the default Terrorist and the default here. */
+    id?: number;
+    /**
+     * Which main-menu performance they play, by clip leaf name, or `null` (the default) to let the
+     * WEAPON choose it - an AK gives the AK idle, an AWP re-poses on its own.
+     */
+    pose?: string | null;
+};
+/**
+ * What the operator has on their hands, or `null` for their own default pair.
+ *
+ * *** `null` IS NOT "BARE HANDS". *** Every agent ships a pair of their own and that is what `null`
+ * gets you. There is no way to render an operator with no gloves, because the game has no such state.
+ */
+export type ViewerGloves = {
+    /** `'sporty_gloves'`, `'specialist_gloves'`, … */
+    type: string;
+    paintIndex: number;
+    /** Default `0.06`, the kit's own best condition. */
+    float?: number;
+    seed?: number;
+};
+/**
+ * *** THE MAPS, AS A CLOSED UNION. *** The owner asked for this directly: `background` is
+ * *"'transparent' or a real map id, not a free string"*.
+ *
+ * WHAT THAT COSTS, said out loud rather than discovered: this list is a COPY of the app's own, so a
+ * map added to the export after this package was published is not typeable until the package is
+ * 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.
+ */
+export declare const MAP_NAMES: readonly ["Ancient", "Anubis", "Baggage", "Cache", "Dust II", "Inferno", "Italy", "Mirage", "Nuke", "Office", "Overpass", "Train", "Vertigo", "Warehouse"];
+export type MapName = (typeof MAP_NAMES)[number];
+export type TimeOfDay = 'Day' | 'Night';
+/**
+ * What is BEHIND the item.
+ *
+ * *** `'transparent'` IS THE DEFAULT AND IT IS THE WHOLE POINT OF AN EMBED. *** The frame paints no
+ * background of its own and mounts no video element, so the canvas composites straight over your
+ * page. Naming a map instead shows that map's video plate, which is a 30-60 MB download.
+ *
+ * TWO THINGS THAT SURPRISE PEOPLE, both stated in `EMBED.md` §9: bloom outside the item's outline is
+ * additive light with no alpha, so the halo reads weaker over your page than over a map (which is why
+ * {@link ViewerQualitySettings.bloomSpill} ships at `0` here); and a transparent iframe is still not
+ * click-through - it takes pointer events over its whole rectangle.
+ */
+export type ViewerBackground = 'transparent' | MapName;
+export type ViewerCameraSettings = {
+    /**
+     * Vertical field of view in degrees, `1`..`179`. Default `26` - a long lens, which is what keeps a
+     * rifle from looking bent. Changing it RE-FRAMES rather than zooms.
+     *
+     * Ignored in `hands`, which uses CS2's own `viewmodel_fov`. They are different quantities.
+     */
+    fov?: number;
+    /**
+     * A MULTIPLIER on the solved fit distance, `0.05`..`20`. Default `1`; `1.2` is 20% closer.
+     *
+     * NEVER A DISTANCE, because a fixed distance cannot be right in two differently-shaped containers -
+     * the camera fits the item to the canvas aspect, so the same AK sits at a different distance in a
+     * 3:4 card than on a full-bleed page.
+     */
+    defaultZoom?: number;
+};
+export type ViewerQualitySettings = {
+    /**
+     * CS2's bloom as a strength multiplier, `0`..`10`. Default `1` (the game's own look); `2` is heavy.
+     *
+     * *** `0` DISABLES IT OUTRIGHT *** - no post-processing chain is mounted and no offscreen target is
+     * allocated, so it is genuinely the cheaper path rather than the same path at zero strength. A page
+     * with a grid of viewers wants this off.
+     */
+    bloom?: number;
+    /**
+     * How much of the bloom is allowed past the item's outline, `0`..`10`. **Default `0` in the embed**,
+     * where our own site ships `1`.
+     *
+     * The default differs on purpose: a halo spreading onto the surrounding page is a house look on a
+     * full-bleed showcase, and a product page's layout did not ask for light leaking out of the canvas
+     * box. Opt in. Ignored while {@link bloom} is `0`.
+     */
+    bloomSpill?: number;
+    /**
+     * A CEILING on `devicePixelRatio`, `0.25`..`3`. Default `1.5`.
+     *
+     * *** THE SINGLE BIGGEST PERFORMANCE LEVER: `2` is four times the fragments of `1`. *** A page
+     * rendering a grid of viewers wants this low.
+     */
+    renderScale?: number;
+    /**
+     * Multisampling. Default `true`.
+     *
+     * *** ONLY REACHABLE WHILE {@link bloom} IS ABOVE `0`. *** With bloom off the scene renders straight
+     * to the canvas, whose antialiasing is fixed when the WebGL context is created; so `bloom: 0` with
+     * `antialias: false` is not an error and is not ignored either - it is antialiased anyway.
+     */
+    antialias?: boolean;
+    /**
+     * The item shadowing itself. Default `false`, which is the reference picture: the lighting rig was
+     * calibrated without it and there is no ground plane for a shadow to land on.
+     */
+    shadows?: boolean;
+};
+export type ViewerEnvironmentSettings = {
+    /**
+     * WHICH MAP'S LIGHT. Default `'Ancient'`; `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. ***
+     * Naming a map lights your item with the probe and sun CS2 bakes into that map's own menu scene.
+     * The common embed is `{ map: 'Mirage' }` with the default transparent background: Mirage's light,
+     * 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'`. */
+    background?: ViewerBackground;
+};
+/**
+ * *** OVERLAYS ARE A CATEGORY, NOT ONE FLAG, and they are INDEPENDENT of dragging. ***
+ *
+ * The sticker outline is an editing AFFORDANCE, not part of the item. Both combinations are
+ * legitimate and both are supported: dragging on with the gizmo hidden (invisible hit targets, your
+ * own UI drawing the guides), and the gizmo shown with dragging off (show where a sticker sits, let
+ * nobody move it). They must not be collapsed into one prop, which is why they live in different
+ * groups - see {@link ViewerInteractions}.
+ */
+export type ViewerOverlaySettings = {
+    /** The outline and handles on the OPEN sticker. Default `false`. */
+    stickerGizmo?: boolean;
+    /** The charm's billboard handle. Default `false`. */
+    charmGizmo?: boolean;
+    /** Colour and readability of the gizmo chrome, for a host with its own design. */
+    gizmoStyle?: {
+        /** Any CSS colour. */
+        color?: string;
+        /** The dark under-stroke that keeps the chrome readable over a pale kit. */
+        shadowColor?: string;
+    };
+};
+/**
+ * *** THE FOUR GROUPS ARE THE FOUR THE FRAME SPEAKS, AND NO MORE. ***
+ *
+ * The design notes also sketch `autoRotation` and `sound`. They are deliberately absent: the
+ * `/frame` protocol carries neither today, so a prop for them would be a prop that silently does
+ * nothing - which is worse than a missing feature, because it is a missing feature you cannot see.
+ * They arrive here in the same change that adds them to the wire, and the type is what forces that.
+ */
+export type ViewerSettings = {
+    camera?: ViewerCameraSettings;
+    quality?: ViewerQualitySettings;
+    environment?: ViewerEnvironmentSettings;
+    overlays?: ViewerOverlaySettings;
+};
+/**
+ * WHAT THE USER MAY DO WITH THE MOUSE. Orbiting and zooming are on; EDITING IS OFF.
+ *
+ * Editing defaults to off because a viewer that silently let a visitor move a sticker would
+ * desynchronise the host's own database without warning. Owner's brief: the integrator adds charms in
+ * their own UI, and we let the user move stickers *"if they enabled that"*.
+ */
+export type ViewerInteractions = {
+    /** Drag to turn the item, right-drag to pan. Default `true`. Always off in `hands`. */
+    orbit?: boolean;
+    /** Wheel to dolly. Default `true`. */
+    zoom?: boolean;
+    /**
+     * Let the user move and rotate a PLACED sticker. Default `false`.
+     *
+     * *** IF YOU TURN THIS ON, HANDLE {@link SkinViewerProps.onChange}, *** or you will not be able to
+     * save what your user did.
+     */
+    dragStickers?: boolean;
+    /** The same, for the charm. Default `false`. */
+    dragCharm?: boolean;
+};
+export type SkinViewerErrorCode = 
+/** A model, texture or index file failed to load, or the GL context was lost. UNRECOVERABLE. */
+'render-failed'
+/** The `inspectLink` did not decode - a bad CRC, a truncated body, or not a masked link at all. */
+ | 'bad-inspect-link'
+/** `defindex` named a weapon this build has no id for. Pass `weapon` instead, or upgrade. */
+ | 'unknown-weapon'
+/** Neither `inspectLink` nor `item` arrived at runtime. See {@link SkinViewerProps}. */
+ | 'no-item'
+/**
+ * *** THE EMBED NEVER ANSWERED. *** Nothing at {@link SkinViewerProps.origin} announced itself
+ * within {@link CONNECT_TIMEOUT_MS}, so there is no conversation and nothing has rendered.
+ *
+ * *** IT EXISTS BECAUSE THE BROWSER WILL NOT TELL US OTHERWISE. *** A cross-origin `<iframe>` fires
+ * `load` for a 404, a 500 and a corporate block page exactly as it does for the real thing, fires no
+ * `error` for any of them, and its document cannot be read. Without a timer the component would sit
+ * at `'connecting'` for ever showing an empty box - which is the single worst failure an integrator
+ * can be handed, because there is nothing at all to search for.
+ *
+ * The likely causes, in the order they actually happen: a network or corporate proxy blocking the
+ * origin, an `origin` prop pointing somewhere that does not serve `/frame`, or a
+ * `Content-Security-Policy` on the HOST page whose `frame-src` does not allow it.
+ *
+ * *** NOT PERMANENT. *** The iframe stays mounted underneath your `fallback`, so a slow connection
+ * that arrives late clears this by itself. `reload()` retries deliberately.
+ */
+ | 'unreachable'
+/**
+ * A field was rejected on the way in and DROPPED, naming its path. Not fatal: the field keeps its
+ * previous value and the rest of the update is applied. Nothing is ever coerced - `float: '0.3'` is
+ * rejected rather than parsed.
+ */
+ | 'bad-message'
+/**
+ * *** THE ONE TERMINAL FAILURE. *** This package and the embed do not speak the same protocol
+ * version, so the frame has rendered NOTHING - no canvas, no partial picture - and will ignore
+ * every later message. The message names which side is out of date. A
+ * silently wrong render is worse than a blank frame with an explanation.
+ */
+ | 'protocol-mismatch';
+export type SkinViewerError = {
+    code: SkinViewerErrorCode;
+    /** A sentence a developer can act on. Safe to show in a dev overlay; not localised. */
+    message: string;
+};
+/** The box the frame reported, on the `resize` event. See {@link SkinViewerProps.onResize}. */
+export type ViewerResize = {
+    width: number;
+    height: number;
+    dpr: number;
+};
+/**
+ * *** EXACTLY ONE OF `inspectLink` OR `item`, ENFORCED IN THE TYPES. ***
+ *
+ * Owner's requirement, and it is a TYPE requirement rather than a runtime one: *"a discriminated
+ * union, so a missing or doubled item is a compile error, not a runtime surprise."*
+ *
+ * `?: never` on the other member is what does it. Passing both is an excess-property error at the
+ * call site; passing neither is a missing-property error. An integrator holds one or the other - a
+ * link out of a trade offer, or the fields already in their database - and the state where both are
+ * present and disagree is one this package would have to invent a precedence rule for. There is no
+ * rule; there is no such call.
+ *
+ * *** AND WHEN THE TYPES ARE BYPASSED, THE VIEWER TEACHES. *** Plain JavaScript, an `any`, data that
+ * 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`.
+ */
+export type ViewerSubject = {
+    inspectLink: string;
+    item?: never;
+} | {
+    item: SkinViewerItem;
+    inspectLink?: never;
+};
+export type SkinViewerProps = ViewerSubject & {
+    /** Default `'gun'`. See {@link ViewerView}. */
+    view?: ViewerView;
+    /** Who is holding it, in the two views that have somebody holding it. See {@link ViewerAgent}. */
+    agent?: ViewerAgent;
+    /** What they have on their hands, or `null` for their own default pair. See {@link ViewerGloves}. */
+    gloves?: ViewerGloves | null;
+    /** Four groups, shallow-merged per group over our defaults. See {@link ViewerSettings}. */
+    settings?: ViewerSettings;
+    /** See {@link ViewerInteractions}. Orbiting and zooming are on, editing is off. */
+    interactions?: ViewerInteractions;
+    /**
+     * Which slot (`0`..`4`, or `5` for the charm) has its handles open, or `-1` for none.
+     *
+     * CONTROLLED WHEN PASSED, UNCONTROLLED WHEN NOT. The uncontrolled case is the one most integrators
+     * want: with `interactions.dragStickers` on, a click opens the sticker and this never appears in
+     * their code. Pass it when your own UI has a slot list that has to stay in step.
+     */
+    editingSlot?: number;
+    /** Fires when the USER opens a slot by clicking a sticker or the charm. */
+    onEditingSlotChange?: (slot: number) => void;
+    /**
+     * Fires when the viewer has STOPPED LOADING - the finish has reached the GPU and the item is on
+     * screen textured.
+     *
+     * *** IT IS A LEVEL, NOT AN EDGE. *** It fires again after every reload, because a weapon change or
+     * a view change raises the loading gate and lowers it again. It also fires if the render FAILED,
+     * because that is equally the moment to take your own placeholder down; use {@link onError} to tell
+     * the two apart.
+     */
+    onReady?: () => void;
+    /** See {@link SkinViewerError}. */
+    onError?: (error: SkinViewerError) => void;
+    /**
+     * The user moved a sticker or the charm - which only happens with `interactions.dragStickers` or
+     * `.dragCharm`. Fires on every pointer move during a drag.
+     *
+     * *** IT HANDS BACK A COMPLETE ITEM, NOT A DIFF. *** Store it verbatim and pass it straight back in
+     * as `item`. It never fires for your own prop changes; it is only ever the user talking.
+     *
+     * The returned item is always in the `{ weapon }` form, never `{ defindex }`, because that is what
+     * the frame reports and translating it back to a number would be a lookup that can fail.
+     */
+    onChange?: (item: SkinViewerItem) => void;
+    /**
+     * The frame's own box changed, throttled to one per animation frame.
+     *
+     * You own the box and the viewer fills it - but RESIZING CHANGES THE PICTURE, not just its scale:
+     * the camera fits the item to the canvas aspect, so animating a panel open beside the frame
+     * re-frames the item.
+     */
+    onResize?: (size: ViewerResize) => void;
+    /** On the wrapper element, which is `position: relative` and fills whatever you give it. */
+    className?: string;
+    style?: CSSProperties;
+    /** The `<iframe>`'s accessible name. Default `'SkinHub viewer'`; pass the item's name. */
+    title?: string;
+    /**
+     * *** DRAWN OVER THE IFRAME, NOT INSIDE IT, AND CLEARED ON `ready`. ***
+     *
+     * A React element cannot cross a `postMessage` boundary - there is no way to hand a node to a
+     * document on another origin - so this is composited on YOUR side, absolutely positioned over the
+     * frame. That is the honest implementation and it has one consequence worth knowing: an opaque node
+     * hides the frame's own loading card rather than replacing it.
+     *
+     * Omitted falls through to the frame's own, which is a reasonable default and is what the SkinHub
+     * app shows.
+     */
+    loading?: ReactNode;
+    /**
+     * Shown OVER the frame when the viewer cannot render - see {@link SkinViewerError}. A function gets
+     * the error, so you can tell a stale package apart from a lost GL context.
+     *
+     * Omitted leaves the frame's own card, which names the failure.
+     */
+    fallback?: ReactNode | ((error: SkinViewerError) => ReactNode);
+    /**
+     * Where `/frame` is served from. Default `'https://skinhub.gg'`.
+     *
+     * *** READ ONCE, AT MOUNT. *** Changing it later does nothing, deliberately: it is the one prop that
+     * could only be applied by reloading the frame, and a prop that quietly throws away the GL context
+     * is exactly the thing this component is built not to have. Call `reload()` from
+     * {@link useSkinViewer} if you really need to move a mounted viewer to another origin.
+     */
+    origin?: string;
+    /**
+     * The imperative handle from {@link useSkinViewer}. Props are state; the hook is verbs.
+     *
+     * A PLAIN PROP AND NOT `ref`, because `ref` on a component means "give me the DOM node" to every
+     * React developer alive, and handing them a `{ reload }` object instead of the `<div>` they asked
+     * for would be a surprise in the one place surprises are least welcome.
+     */
+    handle?: SkinViewerHandle;
+};
+/** What the viewer is doing, as {@link useSkinViewer} reports it. */
+export type ViewerStatus = 
+/** The frame has not announced itself yet. */
+'connecting'
+/** Loading an item - the first one, or a new one after an identity change. */
+ | 'loading'
+/** On screen and textured. */
+ | 'ready'
+/** An unrecoverable failure; `error` is set. */
+ | 'error';
+/**
+ * *** PROPS FOR STATE, A HOOK FOR VERBS. *** See {@link useSkinViewer}.
+ *
+ * `reload` is stable for the life of the hook. THE HANDLE OBJECT IS NOT - it is rebuilt when
+ * {@link status}, {@link error} or {@link problems} move, because that is how a React value
+ * re-renders the tree reading it. Put `viewer.reload` in a dependency array, not `viewer`.
+ */
+export type SkinViewerHandle = {
+    /** The private channel to the mounted component. See `link.ts`. */
+    readonly [LINK]: ViewerLink;
+    /**
+     * Tear the frame down and load it again from the item that is on screen NOW.
+     *
+     * *** THE ONLY THING IN THIS PACKAGE THAT REMOUNTS THE IFRAME, AND IT IS DELIBERATELY IMPERATIVE. ***
+     * Nothing you can pass as a prop reloads the viewer - that is the whole cheap-update contract - so
+     * the escape hatch for "the GL context died" or "the assets were re-published" has to be a verb.
+     */
+    reload: () => void;
+    /** What the viewer is doing. See {@link ViewerStatus}. */
+    status: ViewerStatus;
+    /** The last unrecoverable failure, or `null`. */
+    error: SkinViewerError | null;
+    /**
+     * Anything the frame could not read in the URL this package built for it.
+     *
+     * *** AN ENTRY HERE IS OUR BUG, NOT YOURS. *** You passed props; this package turned them into a
+     * query string; the frame is telling us which part of that string it did not accept. It is exposed
+     * rather than swallowed because the alternative is a picture that is quietly missing a field.
+     */
+    problems: readonly string[];
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}