@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.1

package/lib/ui/useViewerStorage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which surface a wrapper renders, as far as storage is concerned.
+ *
+ * By wrapper rather than by slot: a game UI and its waiting room are both a
+ * player's, so a choice made in one is there in the other, and the two
+ * settings editors share a wrapper that is never told which slot it fills
+ * (§6.5). They never share a key, because the scenario editor is shown
+ * outside any session.
+ */
+export type ViewerStorageSurface = 'player' | 'session' | 'settings-editor' | 'presentation';
+/** What a wrapper tells {@link useViewerStorage} about where it is. */
+export interface ViewerStorageScope {
+    /**
+     * The `sessionKey` the host sent on `init` (§12.2). Undefined on a host
+     * that sends none, which keeps every value in memory rather than risk
+     * sharing it with another session on the same origin.
+     */
+    sessionKey: string | undefined;
+    surface: ViewerStorageSurface;
+    /** The participant's id, or the viewer's role where there is no participant. */
+    viewer: string;
+}
+/**
+ * Provided by every surface wrapper. Exported for the test helpers, which
+ * provide it without a host; game code reads it through {@link useViewerStorage}.
+ */
+export declare const ViewerStorageContext: import("react").Context<ViewerStorageScope | undefined>;
+/**
+ * State that this browser remembers for this viewer, like `useState` but kept
+ * across a reload.
+ *
+ * Namespaced by the run's `sessionKey`, the surface, and the viewer (the
+ * participant, or the viewer's role where there is none), so a value never
+ * leaks into another session that happens to give a team the same id, or to
+ * another participant sharing the device. A walkthrough has its own key, so
+ * a demonstration never touches the real session's values.
+ *
+ * Per browser, never shared: use it for a viewer's own preferences, such as a
+ * collapsed panel or a chosen tab, and context for anything the game needs.
+ * Every access is guarded, so a browser that blocks storage falls back to
+ * memory for the life of the page rather than throwing. Values are stored as
+ * JSON. Other tabs on the same surface follow a change.
+ *
+ * ```tsx
+ * const [collapsed, setCollapsed] = useViewerStorage('help-collapsed', false);
+ * ```
+ *
+ * @param key Names the value within this surface and viewer
+ * @param initial The value until one is stored, or a function returning it
+ * @returns The value and a setter, as `useState` returns them
+ */
+export declare function useViewerStorage<T>(key: string, initial: T | (() => T)): [T, (value: T | ((previous: T) => T)) => void];
+/** Drop every value held in memory. For tests. */
+export declare function clearViewerStorageMemory(): void;

package/lib/ui/useViewerStorage.js

@@ -0,0 +1,141 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+/**
+ * Provided by every surface wrapper. Exported for the test helpers, which
+ * provide it without a host; game code reads it through {@link useViewerStorage}.
+ */
+export const ViewerStorageContext = createContext(undefined);
+/** Values whose browser storage was unavailable, by namespaced key. */
+const memory = new Map();
+/** Every mounted hook, by namespaced key, so one write reaches the rest in the tab. */
+const subscribers = new Map();
+function storage() {
+    try {
+        return typeof window === 'undefined' ? null : window.localStorage;
+    }
+    catch {
+        // Reading the property itself throws where storage is blocked.
+        return null;
+    }
+}
+/** The browser storage key for one value: every part encoded, so none can forge another. */
+function namespaced(scope, key) {
+    const parts = [scope.sessionKey ?? '', scope.surface, scope.viewer, key];
+    return `sg:${parts.map(encodeURIComponent).join(':')}`;
+}
+function readRaw(name, persistent) {
+    if (memory.has(name))
+        return memory.get(name) ?? null;
+    if (!persistent)
+        return null;
+    try {
+        return storage()?.getItem(name) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeRaw(name, raw, persistent) {
+    if (persistent) {
+        try {
+            const store = storage();
+            if (store) {
+                store.setItem(name, raw);
+                memory.delete(name);
+                return;
+            }
+        }
+        catch {
+            // Quota, private mode, or a blocked origin: kept in memory instead.
+        }
+    }
+    memory.set(name, raw);
+}
+function parse(raw, fallback) {
+    if (raw === null)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+function notify(name) {
+    subscribers.get(name)?.forEach((listener) => listener());
+}
+/**
+ * State that this browser remembers for this viewer, like `useState` but kept
+ * across a reload.
+ *
+ * Namespaced by the run's `sessionKey`, the surface, and the viewer (the
+ * participant, or the viewer's role where there is none), so a value never
+ * leaks into another session that happens to give a team the same id, or to
+ * another participant sharing the device. A walkthrough has its own key, so
+ * a demonstration never touches the real session's values.
+ *
+ * Per browser, never shared: use it for a viewer's own preferences, such as a
+ * collapsed panel or a chosen tab, and context for anything the game needs.
+ * Every access is guarded, so a browser that blocks storage falls back to
+ * memory for the life of the page rather than throwing. Values are stored as
+ * JSON. Other tabs on the same surface follow a change.
+ *
+ * ```tsx
+ * const [collapsed, setCollapsed] = useViewerStorage('help-collapsed', false);
+ * ```
+ *
+ * @param key Names the value within this surface and viewer
+ * @param initial The value until one is stored, or a function returning it
+ * @returns The value and a setter, as `useState` returns them
+ */
+export function useViewerStorage(key, initial) {
+    const scope = useContext(ViewerStorageContext);
+    if (scope === undefined) {
+        throw new Error('useViewerStorage must be used inside a surface wrapper');
+    }
+    const name = namespaced(scope, key);
+    const persistent = scope.sessionKey !== undefined;
+    const fallback = useMemo(() => (typeof initial === 'function' ? initial() : initial), 
+    // The initial value is read once per key, as useState reads it once.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [name]);
+    const [value, setValue] = useState(() => parse(readRaw(name, persistent), fallback));
+    useEffect(() => {
+        const refresh = () => setValue(parse(readRaw(name, persistent), fallback));
+        refresh();
+        let listeners = subscribers.get(name);
+        if (!listeners) {
+            listeners = new Set();
+            subscribers.set(name, listeners);
+        }
+        listeners.add(refresh);
+        const onStorage = (event) => {
+            if (event.key === name || event.key === null)
+                refresh();
+        };
+        window.addEventListener('storage', onStorage);
+        return () => {
+            listeners.delete(refresh);
+            if (listeners.size === 0)
+                subscribers.delete(name);
+            window.removeEventListener('storage', onStorage);
+        };
+    }, [name, persistent, fallback]);
+    const set = useCallback((next) => {
+        const current = parse(readRaw(name, persistent), fallback);
+        const resolved = typeof next === 'function' ? next(current) : next;
+        let raw;
+        try {
+            raw = JSON.stringify(resolved) ?? 'null';
+        }
+        catch {
+            return;
+        }
+        writeRaw(name, raw, persistent);
+        notify(name);
+    }, [name, persistent, fallback]);
+    return [value, set];
+}
+/** Drop every value held in memory. For tests. */
+export function clearViewerStorageMemory() {
+    memory.clear();
+}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@seriousgaming/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-alpha.1",
+  "description": "SDK for building Serious Gaming games",
+  "homepage": "https://sdk.seriousgaming.com/",
+  "license": "Apache-2.0",
+  "author": "Redburn Technology Ltd",
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "type": "module",
+  "main": "lib/build/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/build/index.d.ts",
+      "import": "./lib/build/index.js"
+    },
+    "./ui": {
+      "types": "./lib/ui/index.d.ts",
+      "import": "./lib/ui/index.js"
+    },
+    "./ui/testing": {
+      "types": "./lib/ui/testing.d.ts",
+      "import": "./lib/ui/testing.js"
+    },
+    "./testing": {
+      "types": "./lib/testing/index.d.ts",
+      "import": "./lib/testing/index.js"
+    },
+    "./projection": {
+      "types": "./lib/projection.d.ts",
+      "import": "./lib/projection.js"
+    },
+    "./commands": {
+      "types": "./lib/commands.d.ts",
+      "import": "./lib/commands.js"
+    },
+    "./e2e": {
+      "types": "./lib/e2e.d.ts",
+      "import": "./lib/e2e.js"
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^24.19.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "@vitest/coverage-v8": "^5.0.3",
+    "ajv": "^8.20.0",
+    "jsdom": "^30.1.2",
+    "json-schema-to-typescript": "^16.0.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.3"
+  },
+  "peerDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json",
+    "generate": "json2ts -i ../schema.json -o build/resource-schema.ts --declareExternallyReferenced --style singleQuote",
+    "lint": "oxlint --max-warnings=0",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
 }