@skinhub/viewer 0.1.1

package/dist/protocol.d.ts

@@ -0,0 +1,231 @@
+/**
+ * *** 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 declare 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 declare const FRAME_PROTOCOL_VERSION = 1;
+/** 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;
+};
+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 declare const hostMessage: (patch?: FramePatch) => HostMessage;
+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;
+};
+/**
+ * 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 declare const readFrameEvent: (data: unknown) => FrameEventReading;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

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

package/dist/protocol.js

@@ -0,0 +1,128 @@
+/**
+ * *** 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.
+ */
+/**
+ * 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;
+/** Stamps the envelope, so no call site can forget the channel, the version or the direction. */
+export const hostMessage = (patch) => patch
+    ? { channel: FRAME_CHANNEL, v: FRAME_PROTOCOL_VERSION, from: 'host', type: 'set', patch }
+    : { channel: FRAME_CHANNEL, v: FRAME_PROTOCOL_VERSION, from: 'host', type: 'hello' };
+const isRecord = (value) => 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) => {
+    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 };
+};
+const KNOWN_EVENTS = 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) => {
+    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.`;
+};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAA;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA;AA8FvC,iGAAiG;AACjG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAkB,EAAe,EAAE,CAC9D,KAAK;IACJ,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE;IACzF,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AAatF,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CACrE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAErE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAAa,EAAqB,EAAE;IAClE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,KAAK,aAAa,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;IAE1G,IAAI,IAAI,CAAC,CAAC,KAAK,sBAAsB;QACpC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;IAEnG,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;IAC5D;;;;;OAKG;IACH,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;IAE3D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAA6B,EAAE,CAAA;AAC/D,CAAC,CAAA;AAED,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAA;AAElH;;;;;;;;;;GAUG;AACH,MAAM,cAAc,GAAG,CAAC,QAAiB,EAAU,EAAE;IACpD,MAAM,IAAI,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;IAC/E,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,GAAG,sBAAsB;QACpE,OAAO,mCAAmC,sBAAsB,gCAAgC,IAAI,qNAAqN,CAAA;IAC1T,OAAO,mCAAmC,sBAAsB,gCAAgC,IAAI,kKAAkK,CAAA;AACvQ,CAAC,CAAA"}

package/dist/state.d.ts

@@ -0,0 +1,107 @@
+/**
+ * *** PROPS → A URL, AND THEN PROPS → PATCHES. ***
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** THE TWO DOORS, AND WHY THIS PACKAGE USES BOTH RATHER THAN PICKING ONE. ***
+ *
+ * `/frame` can be driven by a query string or by `set` messages, and both go through the same
+ * applier on the far side. This package uses the URL for the FIRST render and messages for every
+ * render after it, and the split is not an optimisation - it is the only arrangement that gets both
+ * properties an integrator will judge us on:
+ *
+ *   THE FIRST PAINT IS THEIR ITEM, not ours swapped a tick later. A frame that booted on our default
+ *   AK and was corrected by a message would show the wrong gun for one round trip, on a product page.
+ *
+ *   NO LATER PROP CHANGE TOUCHES THE `src`. *** THIS IS THE LOAD-BEARING ONE. *** Rewriting `src`
+ *   reloads the document, which throws away the GL context, re-downloads the model and re-runs every
+ *   shader compile - i.e. it turns a float slider into a five-second stall. So the URL is built once,
+ *   frozen, and everything after it is a patch. See `SkinViewer.tsx`, where the same rule is enforced
+ *   on the element.
+ *
+ * ═════════════════════════════════════════════════════════════════════════════════════════════
+ * *** AND THE REASON {@link diffState} IS A DIFF RATHER THAN "SEND THE WHOLE STATE EVERY TIME". ***
+ *
+ * Sending everything would be correct - the frame's merge returns the SAME OBJECT when the values it
+ * is handed are the values it already has, so a restated `weaponType` costs nothing and does not
+ * reload. It would still be wrong, for one reason: `stickers` is an ARRAY WE REBUILD ON EVERY RENDER.
+ * The renderer holds its sticker draft against that array BY IDENTITY, so a fresh six-slot tuple
+ * arriving on every tick of somebody's float slider would re-seed the draft sixty times a second and
+ * fight the user's own drag. The frame's own protocol file warns about exactly this.
+ *
+ * So the diff is structural: a field is in the patch only if its VALUE moved.
+ */
+import type { FrameInteractions, FrameItem, FramePatch, FrameSettings } from './protocol.js';
+import type { SkinViewerError, SkinViewerProps, ViewerGloves, ViewerView } from './types.js';
+/**
+ * Why the frame is showing its instruction card instead of an item. See `SkinViewer.tsx` and the
+ * `?help=` note in `EMBED.md`.
+ */
+export type HelpReason = 'no-item' | 'bad-link' | 'unknown-weapon';
+/**
+ * Everything this package can tell the frame, resolved from one render's props.
+ *
+ * *** ABSENT MEANS "SAY NOTHING", NOT "USE THE DEFAULT", *** all the way down. An integrator who never
+ * passes `settings.quality.bloom` must not have `bloom=1` written into their URL, because then OUR
+ * default is frozen into THEIR embed and the day we change it their picture does not move. The
+ * defaults live in one place - the frame - and this file's job is to be quiet about everything the
+ * caller did not mention.
+ */
+export type DesiredState = {
+    /** `null` when the props named no renderable item; {@link help} then says why. */
+    item: FrameItem | null;
+    /** The integrator's own inspect link, forwarded verbatim as `?i=`. See `item.ts`. */
+    inspectPayload: string | null;
+    help: HelpReason | null;
+    subjectError: SkinViewerError | null;
+    view?: ViewerView;
+    agent?: {
+        id?: number;
+        pose?: string | null;
+    };
+    /** `undefined` says nothing; `null` is the wearer's OWN default pair, which is a real value. */
+    gloves?: ViewerGloves | null;
+    settings?: FrameSettings;
+    interactions?: FrameInteractions;
+    editingSlot?: number;
+};
+/**
+ * One render's props as {@link DesiredState}. Pure, synchronous, no React - so it can run in a
+ * `useState` initialiser during SSR as well as on every subsequent render.
+ *
+ * *** IT TAKES A `Partial<>` OF ITS OWN PROP TYPE ON PURPOSE. *** The types make a missing item a
+ * compile error; this function is what happens when the types were bypassed - plain JavaScript, an
+ * `any`, a query that had not resolved - and its whole value is that it has an answer for that case
+ * rather than a `TypeError`.
+ */
+export declare const resolveState: (props: Partial<SkinViewerProps>) => DesiredState;
+/**
+ * The initial `<iframe src>`, and the state that URL actually expressed.
+ *
+ * *** THE SECOND RETURN VALUE IS NOT BOOKKEEPING - IT IS THE BASELINE EVERY LATER PATCH IS MEASURED
+ * AGAINST. *** One field is deliberately NOT encodable: the stickers, which the query string can only
+ * carry inside an `?i=` payload. Rather than re-encode a placement into an inspect link here - a
+ * second implementation of a codec whose only job would be to disagree with the frame's decoder - the
+ * stickers are simply left out of the URL and reported as unsent, so the first diff after the frame
+ * announces itself carries them. They are a CHEAP field, so they arrive without a loading card, and
+ * in practice they arrive long before the model has finished downloading.
+ *
+ * When the integrator gave us an inspect link there is nothing to encode: their own payload goes
+ * through as `?i=` and carries the stickers with it.
+ */
+export declare const frameUrl: (origin: string, desired: DesiredState) => {
+    src: string;
+    expressed: DesiredState;
+};
+/**
+ * *** WHICH FIELDS RELOAD THE FRAME. *** `EMBED.md`'s cheap-vs-reload table, as a value.
+ *
+ * The component reads this to decide when to raise a caller's `loading` slot, so the slot is raised
+ * on exactly the changes that actually cover the canvas rather than on a guess. `view` and the agent
+ * are the same class but are not fields of the item, so they are handled beside it.
+ */
+export declare const IDENTITY_FIELDS: readonly ["weaponType", "paintIndex", "legacyModel"];
+/** `undefined` when nothing moved, which is what lets the component skip the `postMessage` entirely. */
+export declare const diffState: (previous: DesiredState, next: DesiredState) => FramePatch | undefined;
+/** True when a patch would cover the canvas - see {@link IDENTITY_FIELDS}. */
+export declare const coversCanvas: (patch: FramePatch, view: ViewerView | undefined) => boolean;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAkB,MAAM,eAAe,CAAA;AAE5G,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5F;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,gBAAgB,CAAA;AAElE;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B,kFAAkF;IAClF,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IACtB,qFAAqF;IACrF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IACvB,YAAY,EAAE,eAAe,GAAG,IAAI,CAAA;IACpC,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAC7C,gGAAgG;IAChG,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,YAAY,CAAC,EAAE,iBAAiB,CAAA;IAChC,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAcD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,CAAC,eAAe,CAAC,KAAG,YAgB9D,CAAA;AAqCD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,EAAE,SAAS,YAAY,KAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CA6DtG,CAAA;AAUD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,sDAIqB,CAAA;AAoBjD,wGAAwG;AACxG,eAAO,MAAM,SAAS,GAAI,UAAU,YAAY,EAAE,MAAM,YAAY,KAAG,UAAU,GAAG,SAuEnF,CAAA;AAkDD,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GAAI,OAAO,UAAU,EAAE,MAAM,UAAU,GAAG,SAAS,KAAG,OAO9E,CAAA"}