@magelight/react 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,22 @@
+# @magelight/react
+
+Hooks over `@magelight/sdk` for pages hosted by Magelight UI.
+
+```tsx
+import { useChannel, useUIMode, useSend, HostGate } from '@magelight/react';
+
+function Config() {
+  const state = useChannel<{ volume: number }>('state', { volume: 50 });
+  const focused = useUIMode();
+  const send = useSend();
+  return (
+    <HostGate fallback={<p>Open this page inside Skyrim.</p>} minVersion={[0, 15]}>
+      <input type="range" value={state.volume} onChange={(e) => send('save', { volume: +e.target.value })} />
+      {focused ? 'keyboard is yours' : 'HUD mode'}
+    </HostGate>
+  );
+}
+```
+
+`useChannel(name, initial)` · `useHostData` (alias) · `useChannelEvent(name, fn)` · `useUIMode()` ·
+`useCapability(name)` · `useHost()` · `useSend()` · `<HostGate fallback outdated minVersion>`.

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { type ReactNode } from 'react';
+/**
+ * The latest payload on a channel (parsed), `initial` until one arrives.
+ * A payload that landed before mount is replayed on subscribe, so the
+ * first render after mount already has it.
+ */
+export declare function useChannel<T>(channel: string, initial: T): T;
+/** `useHostData` is `useChannel` under the name SeverActions' frontend used. */
+export declare const useHostData: typeof useChannel;
+/** Subscribe with a callback instead of state (for events, not state). */
+export declare function useChannelEvent<T>(channel: string, fn: (value: T) => void): void;
+/** true while this view holds UI mode (cursor up, keyboard to the page). */
+export declare function useUIMode(): boolean;
+/** `useCapability('textureImage')` — false with no host. */
+export declare function useCapability(name: string): boolean;
+/** Static host facts for render-time branching (`host.present`, version, ids). */
+export declare function useHost(): {
+    readonly present: boolean;
+    readonly info: import("@magelight/sdk").HostInfo;
+    readonly version: string;
+    readonly versionNumber: number;
+    readonly modId: string;
+    readonly viewName: string;
+    readonly viewId: number;
+    readonly dev: boolean;
+    can(capability: string): boolean;
+    atLeast(major: number, minor: number, patch?: number): boolean;
+    imageUrl(name: string): string;
+};
+/** Page → host, stable identity. */
+export declare function useSend(): (channel: string, payload?: unknown) => void;
+/**
+ * Renders children only on Magelight (or the mock in a browser); `fallback`
+ * elsewhere. `minVersion` = [major, minor, patch] gates on the host version
+ * and renders `outdated` (or `fallback`) when too old.
+ */
+export declare function HostGate(props: {
+    children: ReactNode;
+    fallback?: ReactNode;
+    outdated?: ReactNode;
+    minVersion?: [number, number, number?];
+}): ReactNode;

package/dist/index.js

@@ -0,0 +1,50 @@
+import { useEffect, useState } from 'react';
+import { bridge, host } from '@magelight/sdk';
+/**
+ * The latest payload on a channel (parsed), `initial` until one arrives.
+ * A payload that landed before mount is replayed on subscribe, so the
+ * first render after mount already has it.
+ */
+export function useChannel(channel, initial) {
+    const [value, setValue] = useState(initial);
+    useEffect(() => bridge.on(channel, setValue), [channel]);
+    return value;
+}
+/** `useHostData` is `useChannel` under the name SeverActions' frontend used. */
+export const useHostData = useChannel;
+/** Subscribe with a callback instead of state (for events, not state). */
+export function useChannelEvent(channel, fn) {
+    useEffect(() => bridge.on(channel, fn), [channel, fn]);
+}
+/** true while this view holds UI mode (cursor up, keyboard to the page). */
+export function useUIMode() {
+    const [on, setOn] = useState(false);
+    useEffect(() => bridge.onUIMode(setOn), []);
+    return on;
+}
+/** `useCapability('textureImage')` — false with no host. */
+export function useCapability(name) {
+    return host.can(name);
+}
+/** Static host facts for render-time branching (`host.present`, version, ids). */
+export function useHost() {
+    return host;
+}
+/** Page → host, stable identity. */
+export function useSend() {
+    return bridge.send;
+}
+/**
+ * Renders children only on Magelight (or the mock in a browser); `fallback`
+ * elsewhere. `minVersion` = [major, minor, patch] gates on the host version
+ * and renders `outdated` (or `fallback`) when too old.
+ */
+export function HostGate(props) {
+    var _a, _b, _c, _d;
+    if (!host.present)
+        return (_a = props.fallback) !== null && _a !== void 0 ? _a : null;
+    if (props.minVersion && !host.atLeast(props.minVersion[0], props.minVersion[1], (_b = props.minVersion[2]) !== null && _b !== void 0 ? _b : 0)) {
+        return (_d = (_c = props.outdated) !== null && _c !== void 0 ? _c : props.fallback) !== null && _d !== void 0 ? _d : null;
+    }
+    return props.children;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@magelight/react",
+  "version": "0.28.6",
+  "description": "React hooks for Magelight UI pages: useChannel, useUIMode, useCapability, HostGate.",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/Severause/MagelightUI.git", "directory": "packages/react" },
+  "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"
+  },
+  "peerDependencies": {
+    "@magelight/sdk": ">=0.28.6",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@magelight/sdk": "^0.28.6",
+    "@types/react": "^19.2.7",
+    "react": "^19.2.0",
+    "typescript": "~5.9.3"
+  }
+}