@bunnyland/ui-web 0.2.0

package/README.md

@@ -0,0 +1,211 @@
+# Bunnyland UI Web
+
+Shared Preact components, web UI assets, browser helpers, and gameplay display utilities for
+Bunnyland browser clients. The package is publish-ready as `@bunnyland/ui-web` and keeps its
+legacy browser globals intact while clients migrate incrementally.
+
+## Static Browser Clients
+
+Static clients can copy these assets into their served `assets/` directory:
+
+- `assets/bunnyland-ui.css`
+- `assets/bunnyland-ui.js`
+- `assets/bunnyland-api.js`
+- `assets/bunnyland-play.js`
+
+The JavaScript assets preserve the browser globals used by the existing clients:
+
+- `window.BunnylandUI`
+- `window.BunnylandApi`
+- `window.BunnylandPlay`
+
+## Vite, TypeScript, And Preact Clients
+
+Install the package and its deliberately small Preact peer dependency:
+
+```sh
+npm install @bunnyland/ui-web preact
+```
+
+Then import the typed helpers. Prefer narrow modules so Vite and Rollup can tree shake unrelated admin or player code:
+
+```ts
+import { requestSceneImage } from '@bunnyland/ui-web/api';
+import { filterActions } from '@bunnyland/ui-web/play';
+import { bindThemeSelect } from '@bunnyland/ui-web/theme';
+import { renderGalleryItems } from '@bunnyland/ui-web/player-widgets';
+import '@bunnyland/ui-web/assets/bunnyland-ui.css';
+```
+
+Use direct Preact imports for shared functional components and hooks; React and
+`preact/compat` are not required:
+
+```tsx
+import { render } from 'preact';
+import { useState } from 'preact/hooks';
+import {
+  Button,
+  Field,
+  Pane,
+  SearchSelect,
+  ThemeSelect,
+  Toolbar,
+  ToolbarRow,
+  useTheme,
+} from '@bunnyland/ui-web/preact';
+```
+
+`preact` is a peer dependency so each application owns one runtime and Vite can deduplicate
+it. The library build externalizes `preact` and `preact/hooks` rather than bundling a second
+copy. See the canonical [Bunnyland web design language](docs/developer/design-language.md)
+for component boundaries, interaction states, and migration rules.
+
+## Package Releases
+
+Stable GitHub releases publish the matching package version to the public npm registry with
+provenance. The release tag must exactly match `v<package.json version>`; for example,
+package version `0.2.0` is published from tag `v0.2.0`. The dedicated `publish.yml` workflow
+runs the complete package gate again before publishing.
+
+The first publication needs a granular npm automation token with access to the `@bunnyland`
+scope in the repository's `NPM_TOKEN` Actions secret. Once the package exists, configure its
+npm trusted publisher with organization `thalismind`, repository `bunnyland-ui-web`, workflow
+`publish.yml`, and the `npm publish` action. Then revoke the bootstrap token; the same
+workflow uses GitHub Actions OIDC and automatically attaches npm provenance.
+
+Consumers should pin an exact registry version:
+
+```sh
+npm install --save-exact @bunnyland/ui-web@0.2.0 preact
+```
+
+## Versioned Package Artifact
+
+Build a standalone npm tarball for local package inspection with:
+
+```sh
+npm ci
+npm run pack:artifact
+```
+
+The output is `artifacts/bunnyland-ui-web-<version>.tgz`. It contains `package.json`, typed
+`dist/` entry points, legacy `assets/`, source maps, and documentation, and has no dependency
+on an adjacent checkout. CI uploads this tarball for every checked revision as a diagnostic
+artifact. Release consumers use the exact published registry version, never an adjacent
+source directory or a checked-in tarball.
+
+## Themes
+
+The package owns the shared `--bl-*` CSS variables and theme selector helpers. Built-in
+palette names are:
+
+- `purple-blue`
+- `candy`
+- `earth`
+- `ocean`
+- `sunset`
+- `high-contrast`
+
+Each palette follows `prefers-color-scheme` by default. The shared client menu can force
+Dark or Light appearance, or return to Auto (System). Use `bindThemeSelect(select)` for
+palette selectors, `bindColorSchemeSelect(select)` for appearance selectors, and
+`setTheme(theme)` or `setColorScheme(scheme)` for direct changes. Old paired values such as
+`anime-light` continue to load as migration aliases (`candy` with Light forced). New colors
+should be added as CSS variables before clients depend on them.
+
+Deployments can add their own theme choices without changing this package:
+
+```ts
+import { registerThemeOptions } from '@bunnyland/ui-web/theme';
+
+registerThemeOptions([
+  { value: 'server-night', label: 'Server Night' },
+]);
+```
+
+Then serve CSS for the matching root class:
+
+```css
+:root.bl-theme-server-night {
+  color-scheme: dark;
+  --bl-bg: #101218;
+  --bl-surface: #202532;
+  --bl-text: #f0f4ff;
+  --bl-accent: #74c7ec;
+}
+```
+
+Static browser clients also read a `themes` array from deployment `config.json` and register
+those options automatically. Theme values must use lowercase letters, numbers, and hyphens so
+the value maps directly to `bl-theme-<value>`. Set `theme` in `config.json` to make one of
+those values the deployment default, or share a link with `?theme=<value>` to choose a theme
+from the URL.
+
+See [custom web themes](docs/admin/custom-web-themes.md) for the server-admin setup guide.
+
+## Widgets
+
+The framework-neutral widget helpers are split by audience:
+
+- `@bunnyland/ui-web/widgets`: common storage, escaping, and simple data helpers.
+- `@bunnyland/ui-web/player-widgets`: contextual player controls such as photo galleries.
+- `@bunnyland/ui-web/admin-widgets`: detailed admin/editor controls such as tag editors and search dropdowns.
+
+Framework-specific UI packages can wrap these behaviors in components without duplicating the underlying logic. Use narrow imports instead of the root package when a client only needs one audience-specific surface.
+
+Player clients should favor contextual, rich controls for interacting with the current room, visible entities, exits, inventory, queued actions, and images. Admin clients should favor detailed inspection and editing controls such as structured fields, sliders, selectors, tag editors, and lower-level component data. Keep those surfaces separate when adding reusable widgets.
+
+## Player live updates and disclosed facts
+
+`@bunnyland/ui-web/play` owns the shared remote-player update coordinator. It authenticates
+the character WebSocket in the first frame so claim secrets never appear in URLs, coalesces
+bursts into serialized refreshes, reconnects with backoff, and resumes the character-scoped
+recent-event fallback while disconnected. It deduplicates at-least-once event delivery by
+`event_id`, detects `stream_sequence` gaps, and refreshes the character projection after a
+gap or `resync`. Use one coordinator per claimed character rather than giving each panel its
+own socket or polling loop.
+
+Player activity renderers understand serialized `facts` entries with stable `key`, `text`,
+and numeric `detail`. Render the provided text in server order; do not reinterpret component
+state or apply a second client-side cutoff. Action controls likewise consume the serialized
+registry `actions` and `target_groups`. Missing metadata means an empty/disabled action state,
+not a static browser verb catalogue.
+
+## Storybook
+
+A component storybook renders the shared Preact foundation, theme selector, form controls,
+legacy widget helpers, and every semantic state as a live gallery. Build it with:
+
+```sh
+npm run storybook
+```
+
+That builds the package and writes `storybook-dist/`:
+
+- `index.html` — the live, interactive storybook (theme selector, tag editor, search dropdown, client menu).
+- `screenshots.html` — a gallery of one PNG per theme plus the client-menu overlay.
+- `screenshots/*.png` — the captured screenshots.
+- `storybook.zip` — an offline bundle of the HTML, CSS, JS, and screenshots.
+
+The capture uses Playwright's bundled Chromium (`npx playwright install chromium`) and falls
+back to a system Chrome via `STORYBOOK_BROWSER_CHANNEL` when the bundled browser is missing.
+
+CI publishes the `storybook-dist/` directory and `storybook.zip` as build artifacts and builds
+`Dockerfile.storybook` into an nginx image (`bunnyland-ui-web-storybook`) that serves the
+browsable storybook.
+
+## Checks
+
+Run:
+
+```sh
+npm run check
+```
+
+That runs ESLint, the Vite 8 library build, TypeScript declaration generation, Node test
+coverage, and the Preact component tests in a browser-like DOM.
+
+## License
+
+Licensed under the GNU Affero General Public License v3.0 or later. See
+[LICENSE](LICENSE).

package/assets/bunnyland-api.js

@@ -0,0 +1,345 @@
+(function () {
+  'use strict';
+
+  let playerAuthHeader = null;
+  let rotationTimer = null;
+  let browserClientId = typeof globalThis.crypto?.randomUUID === 'function'
+    ? globalThis.crypto.randomUUID()
+    : `web-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+  class ApiError extends Error {
+    constructor(message, status) {
+      super(message);
+      this.name = 'ApiError';
+      this.status = status;
+    }
+  }
+
+  function normalizeBase(url) {
+    return String(url || '').trim().replace(/\/$/, '');
+  }
+
+  function assertSameOriginBase(base) {
+    const normalized = normalizeBase(base);
+    const resolved = new URL(normalized || '/', location.href);
+    if (resolved.origin !== location.origin) {
+      throw new Error('Bunnyland browser connections must use the page origin');
+    }
+    return normalized;
+  }
+
+  function serverFromUrl() {
+    const configured = new URLSearchParams(location.search).get('server') || '';
+    return configured ? assertSameOriginBase(configured) : '';
+  }
+
+  function setServerInUrl(base) {
+    const url = new URL(location.href);
+    const normalized = assertSameOriginBase(base);
+    if (normalized) url.searchParams.set('server', normalized);
+    else url.searchParams.delete('server');
+    history.replaceState(null, '', url);
+  }
+
+  function truthyConfig(value) {
+    return value === true || value === 'true' || value === '1';
+  }
+
+  function mergedJsonHeaders(headers = null) {
+    return {
+      ...jsonHeaders(playerAuthHeader),
+      ...(headers || {}),
+    };
+  }
+
+  function scheduleRotation(base, status) {
+    if (rotationTimer) clearTimeout(rotationTimer);
+    if (!status?.rotate_after) return;
+    const delay = Math.max(0, (Number(status.rotate_after) * 1000) - Date.now());
+    rotationTimer = setTimeout(async () => {
+      try {
+        const next = await rotateAuth(base);
+        scheduleRotation(base, next);
+      } catch (_error) {
+        rotationTimer = null;
+      }
+    }, Math.min(delay, 2147483647));
+  }
+
+  async function authMe(base) {
+    const res = await fetch(`${assertSameOriginBase(base)}/auth/session`, {
+      credentials: 'include', headers: jsonHeaders(playerAuthHeader),
+    });
+    return parseJsonResponse(res);
+  }
+
+  async function login(base, username, password) {
+    const res = await fetch(`${assertSameOriginBase(base)}/auth/session`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: jsonHeaders(playerAuthHeader),
+      body: JSON.stringify({ username, password, delivery: 'cookie' }),
+    });
+    const status = await parseJsonResponse(res);
+    scheduleRotation(base, status);
+    return status;
+  }
+
+  async function rotateAuth(base) {
+    const res = await fetch(`${assertSameOriginBase(base)}/auth/session`, {
+      method: 'PATCH',
+      credentials: 'include',
+      headers: jsonHeaders(playerAuthHeader),
+    });
+    return parseJsonResponse(res);
+  }
+
+  async function logout(base) {
+    const res = await fetch(`${assertSameOriginBase(base)}/auth/session`, {
+      method: 'DELETE',
+      credentials: 'include',
+      headers: jsonHeaders(playerAuthHeader),
+    });
+    if (rotationTimer) clearTimeout(rotationTimer);
+    rotationTimer = null;
+    return parseJsonResponse(res);
+  }
+
+  async function ensurePlayerAuth(base) {
+    try {
+      const status = await authMe(base);
+      scheduleRotation(base, status);
+      return true;
+    } catch (_error) {
+      return promptPlayerAuth(base);
+    }
+  }
+
+  async function applyConfigToInput({ inputId = 'api-url', isConnected = () => false, connect = null } = {}) {
+    const config = await BunnylandUI.loadConfig();
+    const input = document.getElementById(inputId);
+    if (config.serverUrl && input && !isConnected()) input.value = config.serverUrl;
+    if (config.autoConnect && config.serverUrl && !isConnected() && connect) {
+      if (!truthyConfig(config.playerAuthRequired) || await ensurePlayerAuth(config.serverUrl)) {
+        connect(config.serverUrl);
+      }
+    }
+    return config;
+  }
+
+  function applyServerParam({ inputId = 'api-url', connect = null } = {}) {
+    const server = serverFromUrl();
+    if (!server) return '';
+    const input = document.getElementById(inputId);
+    if (input) input.value = server;
+    if (connect) connect(server);
+    return server;
+  }
+
+  function jsonHeaders(authHeader = null) {
+    return {
+      'Content-Type': 'application/json',
+      'X-Bunnyland-Client-Id': browserClientId,
+      ...(String(authHeader || '').startsWith('Bearer ') ? { Authorization: authHeader } : {}),
+    };
+  }
+
+  function adminHeaders(authHeader = null, contentType = null) {
+    const headers = { 'X-Bunnyland-Client-Id': browserClientId };
+    if (contentType) headers['Content-Type'] = contentType;
+    if (String(authHeader || '').startsWith('Bearer ')) {
+      headers.Authorization = authHeader;
+    }
+    return headers;
+  }
+
+  function claimHeaders(control = null) {
+    return {
+      ...jsonHeaders(playerAuthHeader),
+      'X-Bunnyland-Client-Id': control?.clientId || browserClientId,
+      ...(control?.claimSecret ? { 'X-Bunnyland-Claim-Secret': control.claimSecret } : {}),
+    };
+  }
+
+  async function parseJsonResponse(res) {
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) throw new ApiError(data.detail || `HTTP ${res.status}`, res.status);
+    return data;
+  }
+
+  async function sendJson(base, path, { method = 'GET', body = null, headers = null, promptAuth = true } = {}) {
+    const { data } = await sendJsonWithResponse(base, path, { method, body, headers, promptAuth });
+    return data;
+  }
+
+  async function sendJsonWithResponse(base, path, {
+    method = 'GET', body = null, headers = null, promptAuth = true,
+  } = {}) {
+    const currentHeaders = () => mergedJsonHeaders(headers);
+    let res = await fetch(`${assertSameOriginBase(base)}${path}`, {
+      method,
+      headers: currentHeaders(),
+      body,
+      credentials: 'include',
+    });
+    if (res.status === 401 && promptAuth) {
+      if (await promptPlayerAuth(base)) {
+        res = await fetch(`${assertSameOriginBase(base)}${path}`, {
+          method,
+          headers: currentHeaders(),
+          body,
+          credentials: 'include',
+        });
+      }
+    }
+    return { data: await parseJsonResponse(res), response: res };
+  }
+
+  async function promptPlayerAuth(base) {
+    const username = window.prompt('Bunnyland username');
+    if (!username) return null;
+    const password = window.prompt('Bunnyland password');
+    if (password == null) return null;
+    try {
+      await login(base, username, password);
+      return true;
+    } catch (error) {
+      window.alert(error.message || 'Login failed');
+      return false;
+    }
+  }
+
+  function setPlayerAuth(authHeader = null) {
+    playerAuthHeader = String(authHeader || '').startsWith('Bearer ') ? authHeader : null;
+  }
+
+  function getPlayerAuth() {
+    return playerAuthHeader;
+  }
+
+  function setClientId(clientId) {
+    const normalized = String(clientId || '').trim();
+    if (normalized) browserClientId = normalized;
+  }
+
+  function getClientId() {
+    return browserClientId;
+  }
+
+  async function sendAdmin(base, path, {
+    method = 'GET',
+    body = null,
+    prompt = true,
+    getAuth = () => null,
+  } = {}) {
+    const currentHeaders = () => jsonHeaders(getAuth());
+    let res = await fetch(`${assertSameOriginBase(base)}${path}`, {
+      method,
+      headers: currentHeaders(),
+      body,
+      credentials: 'include',
+    });
+    if (res.status === 401 && prompt) {
+      if (await promptPlayerAuth(base)) {
+        res = await fetch(`${assertSameOriginBase(base)}${path}`, {
+          method,
+          headers: currentHeaders(),
+          body,
+          credentials: 'include',
+        });
+      }
+    }
+    return parseJsonResponse(res);
+  }
+
+  async function uploadCharacterImage(base, characterId, purpose, file, {
+    prompt = true,
+    getAuth = () => null,
+  } = {}) {
+    const path = `/admin/media/character/${encodeURIComponent(characterId)}/${encodeURIComponent(purpose)}`;
+    const form = new FormData();
+    form.append('file', file);
+    const currentHeaders = () => adminHeaders(getAuth());
+    let res = await fetch(`${assertSameOriginBase(base)}${path}`, {
+      method: 'PUT',
+      headers: currentHeaders(),
+      body: form,
+      credentials: 'include',
+    });
+    if (res.status === 401 && prompt) {
+      if (await promptPlayerAuth(base)) {
+        res = await fetch(`${assertSameOriginBase(base)}${path}`, {
+          method: 'PUT',
+          headers: currentHeaders(),
+          body: form,
+          credentials: 'include',
+        });
+      }
+    }
+    return parseJsonResponse(res);
+  }
+
+  function socketUrl(base, path = '/admin/world/stream', _authHeader = null) {
+    const normalized = assertSameOriginBase(base);
+    return new URL(`${normalized}${path}`, location.href).href.replace(/^http/, 'ws');
+  }
+
+  function mediaUrl(base, url) {
+    if (!url) return '';
+    if (url.startsWith('data:')) return url;
+    if (/^https?:\/\//.test(url)) {
+      assertSameOriginBase(url);
+      return url;
+    }
+    return `${assertSameOriginBase(base)}${url}`;
+  }
+
+  async function requestSceneImage(base, characterId, control = null) {
+    void characterId;
+    if (!control?.claimId) throw new Error('A character claim is required');
+    return sendJson(base, `/play/claims/${encodeURIComponent(control.claimId)}/jobs`, {
+      method: 'POST',
+      headers: claimHeaders(control),
+      body: JSON.stringify({ kind: 'scene_image' }),
+    });
+  }
+
+  async function requestEventImage(base, recordId, extra = '') {
+    return sendJson(base, '/admin/world/generation-jobs', {
+      method: 'POST',
+      body: JSON.stringify({ kind: 'image', entity_id: recordId, purpose: 'event', extra }),
+    });
+  }
+
+  window.BunnylandApi = {
+    ApiError,
+    applyConfigToInput,
+    applyServerParam,
+    adminHeaders,
+    assertSameOriginBase,
+    authMe,
+    claimHeaders,
+    ensurePlayerAuth,
+    getClientId,
+    getPlayerAuth,
+    jsonHeaders,
+    login,
+    logout,
+    mediaUrl,
+    normalizeBase,
+    parseJsonResponse,
+    promptPlayerAuth,
+    requestEventImage,
+    requestSceneImage,
+    sendAdmin,
+    sendJson,
+    sendJsonWithResponse,
+    serverFromUrl,
+    setServerInUrl,
+    setClientId,
+    setPlayerAuth,
+    socketUrl,
+    rotateAuth,
+    uploadCharacterImage,
+  };
+}());