@helix3/helix-sdk 0.1.1-helix3.20

package/dist/index.js

@@ -0,0 +1,704 @@
+import { isShellMessage, PROTOCOL_VERSION, } from './protocol';
+import { HelixMultiplayer } from './multiplayer';
+import { captureCanvas } from './camera';
+export { cropRectForAspect, captureCanvas } from './camera';
+// The multiplayer wire contract. Re-exported here so `@hypersoniclabs/helix-sdk` root consumers (and
+// classic node-resolution type imports, e.g. the backend minting RoomCredentialClaims) get it; bundler
+// consumers that want only the contract import the lighter '@hypersoniclabs/helix-sdk/multiplayer-contract'.
+export * from './multiplayer-contract';
+// Statuses where the player ends up owning the thing.
+const COMPLETED_STATUSES = new Set([
+    'Granted',
+    'Claimed',
+    'AlreadyOwned',
+]);
+const INIT_TIMEOUT_MS = 8000; // re-post helix:ready up to this long before falling back to standalone — a cold shell (Next route compile) can take >3s to mount its frame + reply
+const READY_RETRY_MS = 200; // re-post helix:ready this often until the shell answers (handshake race — see waitForInit)
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const DEBUG_LOG_MAX = 200; // bounded ring of recent log entries (overlay backfill + pre-init forward flush)
+// Reads/grants should resolve fast; a purchase may sit on the confirm popup, so
+// it uses the longer LOGIN_TIMEOUT_MS instead.
+const REQUEST_TIMEOUT_MS = 30 * 1000;
+// A photo upload (encode + multipart POST to R2) is slower than a read; give it
+// its own budget, shorter than the confirm-popup login window.
+const UPLOAD_TIMEOUT_MS = 60 * 1000;
+class HelixSdk {
+    shellOrigin = null;
+    session = null;
+    world = null;
+    initialized = false;
+    listeners = new Set();
+    debugEnabled = false;
+    debugRing = [];
+    debugListeners = new Set();
+    consoleHooked = false;
+    pendingLogins = new Map();
+    pendingRequests = new Map();
+    balanceListeners = new Set();
+    inventoryListeners = new Set();
+    avatarListeners = new Set();
+    // Performs the shell handshake. Call once at world start, before any other
+    // Helix API. Resolves with embedded=false if no shell answers (local dev).
+    async init() {
+        if (this.initialized)
+            return this.snapshot();
+        window.addEventListener('message', this.onMessage);
+        window.addEventListener('keydown', this.onKeyDown);
+        if (window.parent !== window) {
+            await this.waitForInit();
+        }
+        this.initialized = true;
+        return this.snapshot();
+    }
+    // Multiplayer (pillar D): Helix.multiplayer.joinRoom(). Reads the world_session token + world id off
+    // this singleton; the heavy Colyseus client is dynamically imported only on join.
+    multiplayer = new HelixMultiplayer({
+        isInitialized: () => this.initialized,
+        getToken: () => this.session?.token ?? null,
+        getWorldId: () => this.world?.id ?? null,
+    });
+    // Debug surface. A world's own console lives in its cross-origin iframe — invisible to DevTools / an
+    // automation harness attached to the shell, and to teammates without that frame selected. debug.log feeds
+    // a bounded ring an in-world overlay can render (onLog/recent), and — when the shell enabled debug
+    // (?debug) — is mirrored to the shell frame's console via helix:log. enableDebug() also hooks console.*
+    // so ALL world output is captured, not just explicit debug.log calls. enabled() is a fn (the flag flips
+    // at init, after the field initializer runs).
+    debug = {
+        enabled: () => this.debugEnabled,
+        log: (...args) => this.captureLog('info', args),
+        onLog: (cb) => {
+            this.debugListeners.add(cb);
+            return () => this.debugListeners.delete(cb);
+        },
+        recent: () => this.debugRing.slice(),
+    };
+    auth = {
+        getUser: async () => {
+            this.assertInitialized();
+            return this.session?.user ?? null;
+        },
+        isAuthenticated: () => {
+            this.assertInitialized();
+            return this.session !== null;
+        },
+        // Asks the shell to raise its login overlay. Resolves with the user after
+        // a successful login; rejects if the player dismisses it or no shell is
+        // present. World state is untouched either way — no reload happens.
+        requestLogin: () => {
+            this.assertInitialized();
+            if (this.session)
+                return Promise.resolve(this.session.user);
+            if (!this.shellOrigin) {
+                return Promise.reject(new Error('Helix: not embedded in a HELIX shell — login unavailable'));
+            }
+            const requestId = Math.random().toString(36).slice(2);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pendingLogins.delete(requestId);
+                    reject(new Error('Helix: login request timed out'));
+                }, LOGIN_TIMEOUT_MS);
+                this.pendingLogins.set(requestId, {
+                    resolve: (u) => {
+                        clearTimeout(timer);
+                        resolve(u);
+                    },
+                    reject: (e) => {
+                        clearTimeout(timer);
+                        reject(e);
+                    },
+                });
+                this.post({ type: 'helix:request-login', requestId }, this.shellOrigin);
+            });
+        },
+        // Fires on login and logout (user becomes null). Returns an unsubscribe fn.
+        onAuthChanged: (listener) => {
+            this.listeners.add(listener);
+            return () => this.listeners.delete(listener);
+        },
+    };
+    notify = {
+        show: (notification) => {
+            this.assertInitialized();
+            return this.postToShell({ type: 'helix:notify', notification });
+        },
+        success: (title, message) => this.notify.show({ kind: 'success', title, message }),
+        failure: (title, message) => this.notify.show({ kind: 'failure', title, message }),
+        notification: (title, message) => this.notify.show({ kind: 'notification', title, message }),
+        message: (title, message) => this.notify.show({ kind: 'message', title, message }),
+    };
+    prompts = {
+        set: (prompt) => {
+            this.assertInitialized();
+            return this.postToShell({ type: 'helix:set-interaction-prompt', prompt });
+        },
+        clear: (promptId) => {
+            this.assertInitialized();
+            return this.postToShell({ type: 'helix:clear-interaction-prompt', promptId });
+        },
+    };
+    device = {
+        openTablet: () => this.openDevice('tablet'),
+        openPhone: () => this.openDevice('phone'),
+    };
+    // World-scoped session token for direct platform API calls (used by later
+    // SDK modules; exposed for advanced cases). Null when unauthenticated.
+    getSessionToken() {
+        return this.session?.token ?? null;
+    }
+    // ─────────────────────────── wallet ───────────────────────────
+    wallet = {
+        // The player's current LIX + Coins balances.
+        getBalance: async () => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return { lix: 0, coins: 0 };
+            return this.request('wallet.getBalance');
+        },
+        // Fires after the wallet changes (e.g. a purchase settles). Returns an
+        // unsubscribe fn.
+        onBalanceChanged: (cb) => {
+            this.balanceListeners.add(cb);
+            return () => this.balanceListeners.delete(cb);
+        },
+    };
+    // ────────────────────────── marketplace ──────────────────────────
+    marketplace = {
+        // Request a server-settled purchase of a marketplace (catalog) item. The
+        // shell raises the confirm popup and settles; the world reacts to the result.
+        purchaseItem: (itemId) => this.purchase(`item:${itemId}`),
+        // Request a server-settled purchase of a product registered on the world.
+        purchaseProduct: (productId) => this.purchase(productId),
+        // Browse marketplace listings.
+        getListings: async (query) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return [];
+            return this.request('marketplace.getListings', query ?? {});
+        },
+        // Product/listing + the player's live balance + eligibility, in one call —
+        // for building a custom confirm UI (the built-in popup uses this internally).
+        getPurchaseContext: async (ref) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return null;
+            return this.request('iwp.getContext', { ref });
+        },
+    };
+    analytics = {
+        track: (eventName, input = {}) => this.trackAnalytics(eventName, input),
+    };
+    // ─────────────────────────── inventory ───────────────────────────
+    inventory = {
+        // Whether the current player owns at least one of an item. Works across
+        // worlds and creators (universal items) — the basis for VIP / season passes.
+        hasItem: async (itemId) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return false;
+            return this.request('inventory.hasItem', { itemId });
+        },
+        getQuantity: async (itemId) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return 0;
+            return this.request('inventory.getQuantity', { itemId });
+        },
+        // All items the current player owns.
+        getMyItems: async () => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return [];
+            return this.request('inventory.getMyItems');
+        },
+        // Equip an owned cosmetic item (visual).
+        equipItem: async (itemId) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return;
+            await this.request('inventory.equipItem', { itemId });
+        },
+        onInventoryChanged: (cb) => {
+            this.inventoryListeners.add(cb);
+            return () => this.inventoryListeners.delete(cb);
+        },
+    };
+    // Durable, per-world key–value storage (the Roblox DataStore analog). The
+    // right place for anything that must survive a session: player progress,
+    // settings, world state. Scoped to THIS world; namespace per-player data
+    // yourself (e.g. `player:${userId}`). Value-bearing writes should be made
+    // server-authoritatively. Free for every world (quotas + write rate limits
+    // apply). See https://docs3.helixgame.com/docs/platform-api/data-store
+    dataStore = {
+        // Read a durable value by key. Returns null if unset (or in preview mode,
+        // when the world is opened directly with no shell).
+        get: async (key) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return null;
+            return this.request('dataStore.get', { key });
+        },
+        // Create or overwrite a durable value. No-op in preview mode (read-only).
+        // Subject to the world's free-tier quotas and write rate limit; a rejected
+        // write surfaces as a thrown error (e.g. RateLimited / quota exceeded).
+        set: async (key, value) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return;
+            await this.request('dataStore.set', { key, value });
+        },
+        // Remove a durable value by key. No-op in preview mode.
+        delete: async (key) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return;
+            await this.request('dataStore.delete', { key });
+        },
+        // List stored keys, optionally filtered by prefix (e.g. `player:`). Returns
+        // keys only (fetch values with get), mirroring Roblox ListKeysAsync.
+        list: async (prefix) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return [];
+            return this.request('dataStore.list', { prefix });
+        },
+    };
+    // ─────────────────────────── camera ───────────────────────────
+    //
+    // The universal world camera's cloud side. Photo-mode UI + camera control live
+    // in the engine (which owns three.js + the render loop); the engine hands the
+    // captured pixels here to persist them to the player's account, where they show
+    // up in the phone's Gallery on any device (account-scoped, cross-device).
+    //
+    // `capture` is a pure DOM helper a world/engine can use to turn its rendered
+    // canvas into an encoded, aspect-cropped Blob; `savePhoto` is the shell-mediated
+    // upload. See https://docs3.helixgame.com/docs/platform-api/camera
+    camera = {
+        // True when running inside a HELIX shell (so a save can actually reach the
+        // account). False in local/preview — capture still works, cloud save no-ops.
+        available: () => {
+            this.assertInitialized();
+            return this.shellOrigin !== null;
+        },
+        // Encode a (already-rendered) canvas to a Blob, centre-cropped to `aspect`.
+        // Pure capture — no upload. The caller must render into the canvas in the
+        // same tick (WebGL clears its buffer between frames). Re-exported as
+        // `captureCanvas` for non-camera use.
+        capture: (canvas, opts) => captureCanvas(canvas, opts),
+        // Persist a captured photo to the player's account; it appears in the phone
+        // Gallery on every device, tagged with the world it was taken in (the shell
+        // stamps the world name authoritatively). Resolves null in preview mode
+        // (no shell) — never a fake success. Requires the `camera.capture` scope in
+        // the world manifest; a missing scope rejects.
+        savePhoto: async (image, meta) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return null;
+            const { bytes, contentType } = await toBytes(image, meta?.contentType);
+            return this.request('camera.savePhoto', { bytes, contentType, caption: meta?.caption, aspect: meta?.aspect ?? 'free' }, UPLOAD_TIMEOUT_MS);
+        },
+    };
+    // ─────────────────────────── avatar ───────────────────────────
+    avatar = {
+        openCreator: async () => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return false;
+            return this.request('avatar.openCreator');
+        },
+        getLoadout: async () => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return this.fetchAvatarLoadout();
+            try {
+                return await this.request('avatar.getLoadout');
+            }
+            catch {
+                return this.fetchAvatarLoadout();
+            }
+        },
+        updateLoadout: async (patch) => {
+            this.assertInitialized();
+            if (!this.shellOrigin)
+                return this.fetchAvatarLoadout(patch);
+            try {
+                const loadout = await this.request('avatar.updateLoadout', patch);
+                this.emitAvatarChanged();
+                return loadout;
+            }
+            catch {
+                const loadout = await this.fetchAvatarLoadout(patch);
+                if (loadout)
+                    this.emitAvatarChanged();
+                return loadout;
+            }
+        },
+        // The local player's equipped "universal avatar" — the single avatar a world
+        // renders for them (equipped → auto-equip first owned → default). Resolved by
+        // a DIRECT call to the platform's public equipped-avatar endpoint — no shell
+        // round-trip (the generic helix:request bridge is not implemented by the
+        // shells). The session supplies the player's own user id; the API base is
+        // Helix.multiplayer.configure({ apiBaseUrl }) else the session token's `iss`.
+        // Returns null for guests / outside a shell / on ANY resolution failure — the
+        // world falls back to its default body, never breaks.
+        getEquipped: async () => {
+            this.assertInitialized();
+            const user = this.session?.user;
+            const token = this.session?.token ?? null;
+            if (!user || token === null)
+                return null;
+            const apiBase = this.multiplayer.resolveApiBase(token);
+            if (apiBase === null)
+                return null;
+            try {
+                const res = await fetch(`${apiBase}/api/v1/universal-items/avatar/equipped/users/${encodeURIComponent(user.id)}`);
+                if (!res.ok)
+                    return null;
+                const dto = (await res.json());
+                if (!dto || (dto.source !== 'equipped' && dto.source !== 'auto' && dto.source !== 'default'))
+                    return null;
+                return {
+                    source: dto.source,
+                    inventoryItemId: typeof dto.inventoryItemId === 'string' ? dto.inventoryItemId : null,
+                    itemId: typeof dto.itemId === 'string' ? dto.itemId : null,
+                    glbUrl: typeof dto.glbUrl === 'string' ? dto.glbUrl : null,
+                    skeleton: typeof dto.skeleton === 'string' ? dto.skeleton : null,
+                };
+            }
+            catch {
+                return null;
+            }
+        },
+        onAvatarChanged: (cb) => {
+            this.avatarListeners.add(cb);
+            return () => this.avatarListeners.delete(cb);
+        },
+    };
+    // Shared purchase path. The SDK mints a stable idempotency key per attempt
+    // (reused by the shell across confirm-popup retries) and asks the shell to
+    // settle. Not embedded (local dev) → Unauthorized, never a fake success.
+    purchase(ref) {
+        this.assertInitialized();
+        if (!this.shellOrigin) {
+            return Promise.resolve({ status: 'Unauthorized', completed: false });
+        }
+        const idempotencyKey = this.newId();
+        return this.request('marketplace.purchase', { ref, idempotencyKey }, LOGIN_TIMEOUT_MS).then((raw) => ({
+            ...raw,
+            completed: COMPLETED_STATUSES.has(raw.status),
+        }));
+    }
+    async trackAnalytics(eventName, input) {
+        this.assertInitialized();
+        const token = this.session?.token ?? null;
+        const apiBase = this.multiplayer.resolveApiBase(token);
+        if (!apiBase)
+            return;
+        const body = {
+            event_name: eventName,
+            event_id: input.eventId ?? `sdk:${this.newId()}`,
+            occurred_at: new Date().toISOString(),
+            user_id: this.session?.user.id,
+            anonymous_id: this.session?.user.id ? undefined : `sdk:${this.newId()}`,
+            session_id: token ? `world:${this.session?.user.id ?? 'guest'}` : undefined,
+            platform: 'web',
+            source: 'client',
+            world_id: this.world?.id,
+            instance_id: input.instanceId ?? undefined,
+            item_id: input.itemId ?? undefined,
+            invite_id: input.inviteId ?? undefined,
+            referrer: input.referrer ?? undefined,
+            properties: this.safeAnalyticsProperties(input.properties),
+        };
+        const headers = { 'Content-Type': 'application/json' };
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        const res = await fetch(`${apiBase}/api/v1/analytics/events`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            keepalive: true,
+        });
+        if (!res.ok)
+            throw new Error(`Helix.analytics: collector responded ${res.status}`);
+    }
+    safeAnalyticsProperties(properties) {
+        if (!properties)
+            return undefined;
+        const out = {};
+        for (const [key, value] of Object.entries(properties)) {
+            if (value === undefined || /password|token|secret|authorization|cookie|payment|card|cvv|private_message|raw_chat|raw_voice|email/i.test(key)) {
+                continue;
+            }
+            out[key] = typeof value === 'string' && value.length > 256 ? `${value.slice(0, 253)}...` : value;
+        }
+        return Object.keys(out).length ? out : undefined;
+    }
+    openDevice(form) {
+        this.assertInitialized();
+        return this.postToShell({ type: 'helix:open-device', form });
+    }
+    onKeyDown = (event) => {
+        if (!this.initialized)
+            return;
+        if (event.key !== 'Escape' || event.repeat || event.defaultPrevented)
+            return;
+        const target = event.target;
+        const tag = target?.tagName?.toLowerCase();
+        const isTyping = target?.isContentEditable ||
+            tag === 'input' ||
+            tag === 'textarea' ||
+            tag === 'select';
+        if (isTyping)
+            return;
+        if (this.device.openTablet())
+            event.preventDefault();
+    };
+    // Generic shell-mediated request/response over postMessage.
+    request(method, payload, timeoutMs = REQUEST_TIMEOUT_MS) {
+        this.assertInitialized();
+        if (!this.shellOrigin) {
+            return Promise.reject(new Error('Helix: not embedded in a HELIX shell'));
+        }
+        const requestId = this.newId();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new Error(`Helix: ${method} timed out`));
+            }, timeoutMs);
+            this.pendingRequests.set(requestId, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.post({ type: 'helix:request', requestId, method, payload }, this.shellOrigin);
+        });
+    }
+    newId() {
+        const c = globalThis.crypto;
+        if (c?.randomUUID)
+            return c.randomUUID();
+        return Math.random().toString(36).slice(2) + Date.now().toString(36);
+    }
+    async fetchAvatarLoadout(patch) {
+        const token = this.session?.token ?? null;
+        if (token === null)
+            return null;
+        const apiBase = this.multiplayer.resolveApiBase(token);
+        if (apiBase === null)
+            return null;
+        try {
+            const res = await fetch(`${apiBase}/api/v1/universal-items/avatar/loadout/me`, {
+                method: patch ? 'PATCH' : 'GET',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    ...(patch ? { 'Content-Type': 'application/json' } : {}),
+                },
+                body: patch ? JSON.stringify(patch) : undefined,
+            });
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    emitAvatarChanged() {
+        for (const listener of this.avatarListeners)
+            listener();
+    }
+    snapshot() {
+        return {
+            embedded: this.shellOrigin !== null,
+            world: this.world,
+            user: this.session?.user ?? null,
+        };
+    }
+    assertInitialized() {
+        if (!this.initialized) {
+            throw new Error('Helix: call Helix.init() before using the SDK');
+        }
+    }
+    // Handshake: announce readiness and wait for the shell's helix:init reply. We RE-POST helix:ready until the
+    // shell answers (or we time out) because the shell may attach its message listener AFTER our first post — it
+    // registers in a post-hydration effect, and a lightweight world (no heavy assets, cached) can fire helix:ready
+    // before then, so a single post would be lost and we'd fall back to embedded=false. Retrying closes that race;
+    // the moment the shell answers (shellOrigin set) we stop, so a shell that's already listening sees just one post.
+    waitForInit() {
+        return new Promise((resolve) => {
+            const deadline = Date.now() + INIT_TIMEOUT_MS;
+            const ready = () => this.post({ type: 'helix:ready', protocolVersion: PROTOCOL_VERSION }, '*');
+            ready();
+            const check = () => {
+                if (this.shellOrigin || Date.now() >= deadline) {
+                    resolve();
+                    return;
+                }
+                ready();
+                setTimeout(check, READY_RETRY_MS);
+            };
+            setTimeout(check, READY_RETRY_MS);
+        });
+    }
+    onMessage = (event) => {
+        if (!isShellMessage(event.data))
+            return;
+        // First valid helix:init pins the shell origin; everything after must match it.
+        if (this.shellOrigin && event.origin !== this.shellOrigin)
+            return;
+        const msg = event.data;
+        switch (msg.type) {
+            case 'helix:init':
+                if (this.shellOrigin)
+                    return;
+                this.shellOrigin = event.origin;
+                this.world = msg.world;
+                this.setSession(msg.session);
+                if (msg.debug)
+                    this.enableDebug();
+                break;
+            case 'helix:session':
+                this.setSession(msg.session);
+                break;
+            case 'helix:login-result': {
+                const pending = this.pendingLogins.get(msg.requestId);
+                if (!pending)
+                    return;
+                this.pendingLogins.delete(msg.requestId);
+                if (msg.ok && this.session)
+                    pending.resolve(this.session.user);
+                else
+                    pending.reject(new Error(`Helix: login ${msg.reason ?? 'failed'}`));
+                break;
+            }
+            case 'helix:response': {
+                const pending = this.pendingRequests.get(msg.requestId);
+                if (!pending)
+                    return;
+                this.pendingRequests.delete(msg.requestId);
+                if (msg.ok)
+                    pending.resolve(msg.result);
+                else
+                    pending.reject(new Error(msg.error ?? 'Helix: request failed'));
+                break;
+            }
+            case 'helix:event': {
+                if (msg.event === 'balance-changed') {
+                    const b = msg.data ?? { lix: 0, coins: 0 };
+                    for (const l of this.balanceListeners)
+                        l(b);
+                }
+                else if (msg.event === 'inventory-changed') {
+                    for (const l of this.inventoryListeners)
+                        l();
+                }
+                else if (msg.event === 'avatar-changed' || msg.event === 'equipment-changed') {
+                    this.emitAvatarChanged();
+                }
+                break;
+            }
+        }
+    };
+    setSession(session) {
+        const before = this.session?.user.id ?? null;
+        this.session = session;
+        const after = session?.user.id ?? null;
+        if (before !== after) {
+            for (const listener of this.listeners)
+                listener(session?.user ?? null);
+        }
+    }
+    enableDebug() {
+        if (this.debugEnabled)
+            return;
+        this.debugEnabled = true;
+        this.hookConsole();
+        // Flush anything buffered before the shell turned debug on (e.g. early lifecycle logs).
+        if (this.shellOrigin)
+            for (const entry of this.debugRing)
+                this.post({ type: 'helix:log', entry }, this.shellOrigin);
+    }
+    // Capture ALL console output once debug is on (three.js warnings, SDK errors, uncaught logs) — not just
+    // explicit debug.log calls. Pass-through preserves normal console behaviour in the iframe.
+    hookConsole() {
+        if (this.consoleHooked || typeof console === 'undefined')
+            return;
+        this.consoleHooked = true;
+        const levels = ['log', 'info', 'warn', 'error', 'debug'];
+        const c = console;
+        for (const level of levels) {
+            const orig = c[level]?.bind(console);
+            if (!orig)
+                continue;
+            c[level] = (...args) => {
+                this.captureLog(level, args);
+                orig(...args);
+            };
+        }
+    }
+    captureLog(level, args) {
+        const entry = { level, args: args.map(stringifyArg), t: Date.now() };
+        this.debugRing.push(entry);
+        if (this.debugRing.length > DEBUG_LOG_MAX)
+            this.debugRing.shift();
+        for (const cb of this.debugListeners) {
+            try {
+                cb(entry);
+            }
+            catch {
+                /* a listener must never break logging */
+            }
+        }
+        if (this.debugEnabled && this.shellOrigin)
+            this.post({ type: 'helix:log', entry }, this.shellOrigin);
+    }
+    post(message, targetOrigin) {
+        window.parent.postMessage(message, targetOrigin);
+    }
+    postToShell(message) {
+        if (!this.shellOrigin)
+            return false;
+        this.post(message, this.shellOrigin);
+        return true;
+    }
+}
+// Normalize a captured image to a transferable ArrayBuffer + a content type for
+// the shell to upload. Accepts a Blob (browser capture), an ArrayBuffer, or a
+// Uint8Array. A Blob carries its own MIME; otherwise default to JPEG.
+async function toBytes(image, contentTypeOverride) {
+    if (typeof Blob !== 'undefined' && image instanceof Blob) {
+        return {
+            bytes: await image.arrayBuffer(),
+            contentType: contentTypeOverride || image.type || 'image/jpeg',
+        };
+    }
+    if (image instanceof Uint8Array) {
+        const copy = image.slice();
+        return { bytes: copy.buffer, contentType: contentTypeOverride || 'image/jpeg' };
+    }
+    // Remaining case is ArrayBuffer (the Blob branch above returns); the compound
+    // typeof-guard stops TS from negative-narrowing Blob, so assert it here.
+    return { bytes: image, contentType: contentTypeOverride || 'image/jpeg' };
+}
+// Serialize a console arg to a string the shell can print: strings as-is, Errors to their stack, other
+// objects to compact JSON (falling back to String() on cyclic/unserializable values).
+function stringifyArg(a) {
+    if (typeof a === 'string')
+        return a;
+    if (a instanceof Error)
+        return a.stack ?? `${a.name}: ${a.message}`;
+    try {
+        return typeof a === 'object' && a !== null ? JSON.stringify(a) : String(a);
+    }
+    catch {
+        return String(a);
+    }
+}
+// Worlds import this singleton: `import { Helix } from '@hypersoniclabs/helix-sdk'`.
+export const Helix = new HelixSdk();
+//# sourceMappingURL=index.js.map