@magelight/sdk 0.28.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Severause
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @magelight/sdk
+
+Typed page bridge for [Magelight UI](../../README.md), the Ultralight-based web UI host for
+Skyrim SE/AE. Framework-agnostic; `@magelight/react` adds hooks on top.
+
+```ts
+import { host, bridge, channel } from '@magelight/sdk';
+
+if (host.present) console.log(`running on Magelight ${host.version} as ${host.modId}/${host.viewName}`);
+
+// host → page: whatever the mod sends with InteropCall(view, 'state', json)
+const state = channel<{ volume: number }>('state');
+state.on((s) => render(s));          // replayed if it arrived before this line
+
+// page → host: reaches the listener the mod registered as 'save'
+bridge.send('save', { volume: 70 }); // objects are JSON-encoded, strings pass through
+
+bridge.onUIMode((on) => on ? input.focus() : input.blur());
+```
+
+- **`host`** — `present`, `version`, `versionNumber`, `modId`, `viewName`, `viewId`, `dev`,
+  `can('textureImage')`, `atLeast(0, 15)`, `imageUrl(name)`.
+- **`bridge.on / send / onRaw / pending / onUIMode`**, **`channel<T>(name)`**, **`ready()`**.
+- **Pre-mount replay** — the host buffers any channel payload until someone subscribes, so a
+  payload sent from `ViewDomReady` is never lost to a late React mount.
+- **Browser mock** — with no host present the SDK installs `window.magelight` itself and a
+  floating panel to dispatch payloads / watch sends, so `vite dev` works on the page alone.
+  Opt out with `window.__MAGELIGHT_NO_MOCK__ = true` before the SDK loads.
+
+Host side: any channel with no `window.<channel>` shim routes into the page core, so a mod
+needs no page-side registration for host → page traffic; page → host still needs
+`RegisterJSListenerEx(view, channel, …)` (or Papyrus `RegisterListener`).

package/dist/bridge.d.ts

@@ -0,0 +1,37 @@
+import { host } from './host';
+import type { Handler, PageCore, Unsubscribe } from './types';
+/**
+ * The page core: the host's `window.magelight` in the game, a mock in a
+ * plain browser (set `window.__MAGELIGHT_NO_MOCK__ = true` before the SDK
+ * loads to opt out, e.g. under another host that has its own bridge).
+ */
+export declare function ensureCore(): PageCore;
+/**
+ * Parse what the host sent on a channel. Objects arrive as JSON text
+ * (`InteropCall(view, channel, json)`); plain strings pass through when
+ * they are not JSON. Mirrors what SeverActions' bridge learned in the
+ * field: never throw on a payload, log and return the raw text.
+ */
+export declare function parsePayload<T = unknown>(raw: string): T;
+export declare const bridge: {
+    /** page → host. Objects are JSON-encoded; strings pass through. */
+    send(channel: string, payload?: unknown): void;
+    /** host → page. Payloads that arrived before this call are replayed at once. */
+    on<T = unknown>(channel: string, fn: Handler<T>): Unsubscribe;
+    /** raw text variant of `on` */
+    onRaw(channel: string, fn: Handler<string>): Unsubscribe;
+    /** how many payloads wait on a channel nobody subscribed to yet */
+    pending(channel: string): number;
+    /** true while this view holds UI mode (cursor up, keyboard to the page) */
+    onUIMode(fn: Handler<boolean>): Unsubscribe;
+};
+/** A typed channel handle: `const state = channel<State>('state'); state.on(s => …); state.send(...)` */
+export declare function channel<T = unknown>(name: string): {
+    name: string;
+    on(fn: Handler<T>): Unsubscribe;
+    send(payload?: unknown): void;
+    readonly pending: number;
+};
+/** Tell the host-side mod the page is mounted (a plain send on `ready`; register a listener for it). */
+export declare function ready(detail?: unknown): void;
+export { host };

package/dist/bridge.js

@@ -0,0 +1,82 @@
+import { host } from './host';
+import { installMock } from './mock';
+let core;
+/**
+ * The page core: the host's `window.magelight` in the game, a mock in a
+ * plain browser (set `window.__MAGELIGHT_NO_MOCK__ = true` before the SDK
+ * loads to opt out, e.g. under another host that has its own bridge).
+ */
+export function ensureCore() {
+    if (core)
+        return core;
+    if (typeof window === 'undefined')
+        throw new Error('@magelight/sdk needs a window');
+    if (window.magelight)
+        return (core = window.magelight);
+    if (window.__MAGELIGHT_NO_MOCK__) {
+        throw new Error('@magelight/sdk: no host and the mock is disabled');
+    }
+    return (core = installMock());
+}
+/**
+ * Parse what the host sent on a channel. Objects arrive as JSON text
+ * (`InteropCall(view, channel, json)`); plain strings pass through when
+ * they are not JSON. Mirrors what SeverActions' bridge learned in the
+ * field: never throw on a payload, log and return the raw text.
+ */
+export function parsePayload(raw) {
+    if (raw === '')
+        return '';
+    const c = raw[0];
+    if (c === '{' || c === '[' || c === '"' || c === '-' || (c >= '0' && c <= '9') || raw === 'true' || raw === 'false' || raw === 'null') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            /* not JSON after all */
+        }
+    }
+    return raw;
+}
+export const bridge = {
+    /** page → host. Objects are JSON-encoded; strings pass through. */
+    send(channel, payload) {
+        ensureCore().send(channel, payload);
+    },
+    /** host → page. Payloads that arrived before this call are replayed at once. */
+    on(channel, fn) {
+        return ensureCore().on(channel, (raw) => fn(parsePayload(raw)));
+    },
+    /** raw text variant of `on` */
+    onRaw(channel, fn) {
+        return ensureCore().on(channel, fn);
+    },
+    /** how many payloads wait on a channel nobody subscribed to yet */
+    pending(channel) {
+        return ensureCore().pending(channel);
+    },
+    /** true while this view holds UI mode (cursor up, keyboard to the page) */
+    onUIMode(fn) {
+        return ensureCore().on('__uimode', (raw) => fn(raw === '1'));
+    },
+};
+/** A typed channel handle: `const state = channel<State>('state'); state.on(s => …); state.send(...)` */
+export function channel(name) {
+    return {
+        name,
+        on(fn) {
+            return bridge.on(name, fn);
+        },
+        send(payload) {
+            bridge.send(name, payload);
+        },
+        get pending() {
+            return bridge.pending(name);
+        },
+    };
+}
+/** Tell the host-side mod the page is mounted (a plain send on `ready`; register a listener for it). */
+export function ready(detail) {
+    bridge.send('ready', detail);
+}
+export { host };

package/dist/host.d.ts

@@ -0,0 +1,24 @@
+import type { HostInfo } from './types';
+/**
+ * Who is hosting this page. Read lazily: the host installs its globals
+ * before any page script runs, but a module evaluated in a plain browser
+ * (or under PrismaUI) sees `present === false`.
+ */
+export declare const host: {
+    readonly present: boolean;
+    readonly info: HostInfo;
+    readonly version: string;
+    readonly versionNumber: number;
+    readonly modId: string;
+    readonly viewName: string;
+    readonly viewId: number;
+    readonly dev: boolean;
+    /** `host.can('textureImage')` — 0/absent = no */
+    can(capability: string): boolean;
+    /** at least `major.minor.patch` */
+    atLeast(major: number, minor: number, patch?: number): boolean;
+    /** URL of a host-registered texture image (`RegisterTextureImage` name) */
+    imageUrl(name: string): string;
+};
+/** Convenience: `if (isMagelight()) document.documentElement.classList.add('host-magelight')` */
+export declare function isMagelight(): boolean;

package/dist/host.js

@@ -0,0 +1,62 @@
+const absent = {
+    version: '',
+    versionNumber: 0,
+    viewId: 0,
+    modId: '',
+    viewName: '',
+    capabilities: {},
+    dev: false,
+    runtimeUrl: '',
+};
+function read() {
+    return typeof window !== 'undefined' ? window.__MAGELIGHT__ : undefined;
+}
+/**
+ * Who is hosting this page. Read lazily: the host installs its globals
+ * before any page script runs, but a module evaluated in a plain browser
+ * (or under PrismaUI) sees `present === false`.
+ */
+export const host = {
+    get present() {
+        return read() !== undefined;
+    },
+    get info() {
+        var _a;
+        return (_a = read()) !== null && _a !== void 0 ? _a : absent;
+    },
+    get version() {
+        return this.info.version;
+    },
+    get versionNumber() {
+        return this.info.versionNumber;
+    },
+    get modId() {
+        return this.info.modId;
+    },
+    get viewName() {
+        return this.info.viewName;
+    },
+    get viewId() {
+        return this.info.viewId;
+    },
+    get dev() {
+        return this.info.dev;
+    },
+    /** `host.can('textureImage')` — 0/absent = no */
+    can(capability) {
+        var _a;
+        return ((_a = this.info.capabilities[capability]) !== null && _a !== void 0 ? _a : 0) > 0;
+    },
+    /** at least `major.minor.patch` */
+    atLeast(major, minor, patch = 0) {
+        return this.versionNumber >= major * 10000 + minor * 100 + patch;
+    },
+    /** URL of a host-registered texture image (`RegisterTextureImage` name) */
+    imageUrl(name) {
+        return this.info.runtimeUrl ? `${this.info.runtimeUrl}images/${name}.imgsrc` : '';
+    },
+};
+/** Convenience: `if (isMagelight()) document.documentElement.classList.add('host-magelight')` */
+export function isMagelight() {
+    return host.present;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { host, isMagelight } from './host';
+export { bridge, channel, ready, parsePayload, ensureCore } from './bridge';
+export { installMock } from './mock';
+export type { HostInfo, PageCore, Handler, Unsubscribe } from './types';
+export type { MockOptions } from './mock';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { host, isMagelight } from './host';
+export { bridge, channel, ready, parsePayload, ensureCore } from './bridge';
+export { installMock } from './mock';

package/dist/mock.d.ts

@@ -0,0 +1,16 @@
+import type { HostInfo, PageCore } from './types';
+/**
+ * A stand-in `window.magelight` for a plain browser: lets you develop a
+ * page with `vite dev`, inject payloads on any channel from a floating
+ * panel, and see what the page sent. Installed by `ensureCore()` when no
+ * host is present; never installed in the game.
+ */
+export interface MockOptions {
+    /** show the floating panel (default: true when a document exists) */
+    panel?: boolean;
+    /** pretend to be this host (default: a dev host with every capability) */
+    info?: Partial<HostInfo>;
+    /** called for every page → host send */
+    onSend?: (channel: string, payload: string) => void;
+}
+export declare function installMock(opts?: MockOptions): PageCore;

package/dist/mock.js

@@ -0,0 +1,134 @@
+export function installMock(opts = {}) {
+    var _a;
+    const subs = {};
+    const buf = {};
+    const sent = [];
+    const info = {
+        // Pretend to be a current host: version gates (host.atLeast, HostGate
+        // minVersion) must pass so version-gated pages can be iterated in the
+        // browser. Override with opts.info to test the gate UI itself.
+        version: '99.0.0-mock',
+        versionNumber: 990000,
+        viewId: 1,
+        modId: 'Mock',
+        viewName: 'dev',
+        // The canonical capability set (matches the host's kNames list, 0.28.4).
+        // Values are the browser-mock truth: no GPU/VR/native powers, the
+        // always-on page/logic capabilities on, the browser's own network open
+        // (loopback / networkPolicy). `mock` flags the mock itself.
+        capabilities: { gpu: 0, textureImage: 0, clipPathHole: 0, pause: 1, events: 1, clipboard: 1,
+            networkDeny: 0, sessions: 1, manifest: 1, http: 0, vr: 0, hotkeys: 1, evaljs: 1,
+            pagebridge: 1, cutout: 0, hibernate: 0, inspector: 0, ime: 0, loopback: 1,
+            escapeCapture: 0, viewOrder: 0, scrollStep: 0, networkPolicy: 1, mock: 1 },
+        dev: true,
+        runtimeUrl: '',
+        ...opts.info,
+    };
+    const core = {
+        send(channel, payload) {
+            var _a;
+            const a = payload == null ? '' : typeof payload === 'string' ? payload : JSON.stringify(payload);
+            sent.push({ channel, payload: a });
+            (_a = opts.onSend) === null || _a === void 0 ? void 0 : _a.call(opts, channel, a);
+            log(`→ ${channel}(${a.length > 120 ? a.slice(0, 120) + '…' : a})`);
+        },
+        on(channel, fn) {
+            var _a;
+            ((_a = subs[channel]) !== null && _a !== void 0 ? _a : (subs[channel] = [])).push(fn);
+            const b = buf[channel];
+            if (b) {
+                delete buf[channel];
+                // Host parity: one throwing handler does not kill the rest of the
+                // buffer or propagate into the subscribe call site.
+                for (const arg of b) {
+                    try {
+                        fn(arg);
+                    }
+                    catch (e) {
+                        console.error(`[magelight mock] replay for ${channel} threw`, e);
+                    }
+                }
+            }
+            return () => core.off(channel, fn);
+        },
+        off(channel, fn) {
+            const s = subs[channel];
+            if (!s)
+                return;
+            const i = s.indexOf(fn);
+            if (i >= 0)
+                s.splice(i, 1);
+        },
+        _dispatch(channel, arg) {
+            var _a;
+            const s = subs[channel];
+            if (!s || !s.length) {
+                ((_a = buf[channel]) !== null && _a !== void 0 ? _a : (buf[channel] = [])).push(arg);
+                return;
+            }
+            for (const fn of s) {
+                try {
+                    fn(arg);
+                }
+                catch (e) {
+                    console.error(`[magelight mock] handler for ${channel} threw`, e);
+                }
+            }
+        },
+        pending(channel) {
+            var _a;
+            return ((_a = buf[channel]) !== null && _a !== void 0 ? _a : []).length;
+        },
+    };
+    window.__MAGELIGHT__ = info;
+    window.magelight = core;
+    window.__MAGELIGHT_MOCK__ = { sent, core };
+    let logEl = null;
+    function log(line) {
+        var _a;
+        if (logEl) {
+            const d = document.createElement('div');
+            d.textContent = line;
+            logEl.prepend(d);
+            while (logEl.childElementCount > 40)
+                (_a = logEl.lastElementChild) === null || _a === void 0 ? void 0 : _a.remove();
+        }
+    }
+    const wantPanel = (_a = opts.panel) !== null && _a !== void 0 ? _a : typeof document !== 'undefined';
+    if (wantPanel) {
+        const mount = () => {
+            if (!document.body || document.getElementById('__ml_mock'))
+                return;
+            const root = document.createElement('div');
+            root.id = '__ml_mock';
+            root.innerHTML =
+                `<style>#__ml_mock{position:fixed;right:8px;bottom:8px;z-index:2147483000;width:340px;font:12px/1.4 system-ui,sans-serif;` +
+                    `background:#1e1e1e;color:#ddd;border:1px solid #555;border-radius:6px;box-shadow:0 4px 18px #0008}` +
+                    `#__ml_mock header{padding:6px 10px;background:#2c2c2c;border-radius:6px 6px 0 0;cursor:pointer;display:flex;justify-content:space-between}` +
+                    `#__ml_mock .b{padding:8px 10px;display:none}#__ml_mock.open .b{display:block}` +
+                    `#__ml_mock input,#__ml_mock textarea{width:100%;box-sizing:border-box;background:#111;color:#eee;border:1px solid #444;border-radius:3px;padding:4px;font:12px monospace;margin:2px 0}` +
+                    `#__ml_mock textarea{height:70px}#__ml_mock button{margin-top:4px;padding:4px 10px;background:#3a5;color:#fff;border:0;border-radius:3px;cursor:pointer}` +
+                    `#__ml_mock .log{margin-top:8px;max-height:140px;overflow:auto;font:11px monospace;color:#9c9;border-top:1px solid #333;padding-top:4px}</style>` +
+                    `<header><span>Magelight mock host</span><span>▴</span></header><div class="b">` +
+                    `<input placeholder="channel (e.g. pageData)"><textarea placeholder='payload (JSON or text)'></textarea>` +
+                    `<button>Dispatch to page</button><div class="log"></div></div>`;
+            document.body.appendChild(root);
+            const header = root.querySelector('header');
+            header.addEventListener('click', () => root.classList.toggle('open'));
+            const [chan] = Array.from(root.querySelectorAll('input'));
+            const ta = root.querySelector('textarea');
+            root.querySelector('button').addEventListener('click', () => {
+                if (!chan.value)
+                    return;
+                core._dispatch(chan.value, ta.value);
+                log(`← ${chan.value}(${ta.value.length} chars)`);
+            });
+            logEl = root.querySelector('.log');
+        };
+        if (document.readyState === 'loading')
+            document.addEventListener('DOMContentLoaded', mount);
+        else
+            mount();
+    }
+    return core;
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+/** What the host installs as `window.__MAGELIGHT__` at window-object-ready. */
+export interface HostInfo {
+    /** "0.15.0" */
+    version: string;
+    /** MAJOR*10000 + MINOR*100 + PATCH — compare against this, never parse the string */
+    versionNumber: number;
+    viewId: number;
+    /** "" for views created through the v1-v3 API */
+    modId: string;
+    viewName: string;
+    /** 1 = supported, 0 = not (see docs/PUBLIC_FRAMEWORK_PLAN.md §6 for the names) */
+    capabilities: Record<string, number>;
+    /** Magelight.json devMode: hot reload, F5, F12 inspector, error overlay */
+    dev: boolean;
+    /** file:///.../Data/SKSE/Plugins/Magelight/ — images live under images/<name>.imgsrc */
+    runtimeUrl: string;
+}
+/** The two verbs the host installs as `window.magelight` (the page core). */
+export interface PageCore {
+    send(channel: string, payload?: unknown): void;
+    on(channel: string, fn: (arg: string) => void): () => void;
+    off(channel: string, fn: (arg: string) => void): void;
+    _dispatch(channel: string, arg: string): void;
+    pending(channel: string): number;
+}
+declare global {
+    interface Window {
+        __MAGELIGHT__?: HostInfo;
+        magelight?: PageCore;
+        __mlNative?: (viewId: string, channel: string, arg: string) => void;
+    }
+}
+export type Handler<T> = (value: T) => void;
+export type Unsubscribe = () => void;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@magelight/sdk",
+  "version": "0.28.6",
+  "description": "Typed page bridge for Magelight UI (Skyrim SE/AE web UI host): host detection, channels with pre-mount replay, capabilities, browser mock.",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/Severause/MagelightUI.git", "directory": "packages/sdk" },
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "keywords": ["skyrim", "skse", "ultralight", "magelight", "ui"],
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  }
+}