@filamind-app/core 0.1.0 → 0.1.2

package/README.md

@@ -3,6 +3,11 @@
 The shared foundation of the FilaMind suite — **framework-agnostic TypeScript** consumed by FilaMind 3d
 (web), FilaMind screen (touch), and FilaMind flow. Phase 0.
 
+[![CI](https://github.com/filamind-app/filamind-core/actions/workflows/ci.yml/badge.svg)](https://github.com/filamind-app/filamind-core/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@filamind-app/core?color=111111&label=npm)](https://www.npmjs.com/package/@filamind-app/core)
+[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-111111.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-111111?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+
 ## What's here
 | Module | Purpose |
 | --- | --- |
@@ -11,6 +16,7 @@ The shared foundation of the FilaMind suite — **framework-agnostic TypeScript*
 | `state/printer.ts` | `PrinterState` — merge-patch from `notify_status_update`, **1 s coalescing + `motion_report` fast-path** |
 | `moonraker/connector.ts` | the backend-agnostic `Connector` seam (Moonraker first; remote/others later) |
 | `moonraker/client.ts` | `MoonrakerClient` — reconnecting JSON-RPC WS (**injectable socket**, backoff **+ jitter + max-attempts**), id-correlated, notify fan-out, re-subscribe on reconnect, **REST file channel** (`upload`/`download`) |
+| `moonraker/discovery.ts` | **zero-config endpoint discovery** — `resolveMoonrakerUrl()` races candidate endpoints (same-origin proxy / direct `:7125` / localhost) → first to open wins; runtime `override` short-circuits. Socket-injectable |
 | `moonraker/subscriptions.ts` | the **versioned** canonical subscription contract — `NARROW_STATUS` / `FULL_CONTROL` tiers + `tier()` |
 | `printer/klippy.ts` | the Klippy lifecycle (`ready`/`startup`/`shutdown`/`error`/`disconnected`) — tracked apart from the socket so a FIRMWARE_RESTART re-seeds instead of showing stale-as-live |
 | `printer/prompt-parser.ts` | parses Klipper's `// action:prompt_*` protocol into structured modal dialogs (`PromptParser`) |
@@ -20,7 +26,8 @@ The shared foundation of the FilaMind suite — **framework-agnostic TypeScript*
 | `backup/restore-points.ts` | reversible, retention-bounded **`RestorePoints`** (back-up-first substrate for config/flash/migrate) |
 | `observability/logger.ts` | pluggable ring-buffer `Logger` (the diagnostics-bundle source; replaces silent `catch {}`) |
 | `registry/widget-registry.ts` | the cross-surface widget/plugin registry + `aggregateSubscriptions` |
-| `theme/tokens.ts` | the exclusive Pharaonic themes (Tutankhamun · Horus · Anubis) as `--fm-*` design tokens |
+| `remote/commands.ts` · `remote/command-sender.ts` | the cross-surface command bus — **UI-only** commands (navigate / message / locate) over a Moonraker **agent** connection. `CommandSender` identifies as an agent, re-identifies on reconnect, is single-flight, and sanitizes control/bidi text; it is never a mutation path (those still go through `WriteArbiter`) |
+| `theme/tokens.ts` | the theme palettes as `--fm-*` design tokens — 3 signature Pharaonic themes (Tutankhamun · Horus · Anubis) + neutral **light** / **dark** |
 | `i18n/locale-meta.ts` | the 19 shipped locales `{ code, name, rtl, dir }` + RTL list + CLDR `pluralCategory` (`Intl.PluralRules`) |
 | `i18n/translator.ts` | framework-agnostic `translate` / `Translator` + the backend message-code contract (`resolveMessage`) |
 | `i18n/locales/*.json` | drop-in catalogs (en + ar shipped as proof, incl. the full Arabic plural set) |

package/dist/index.d.ts

@@ -143,6 +143,37 @@ declare class MoonrakerClient implements Connector {
     private onMessage;
 }
 
+/** A minimal view of `location` — the DOM Location satisfies it; tests pass a plain object. */
+interface LocationLike {
+    protocol?: string;
+    hostname?: string;
+}
+interface DiscoveryOptions {
+    /** Explicit runtime override (e.g. from settings). If set, it wins immediately — no probing. */
+    override?: string;
+    /** Candidate ws(s):// URLs to race. If omitted, they are derived from `location`. */
+    candidates?: string[];
+    /** Overall budget before discovery gives up (ms). Default 3000. */
+    timeoutMs?: number;
+    /** Injectable socket factory (tests / non-DOM). Default: `new WebSocket`. */
+    wsFactory?: (url: string) => WebSocketLike;
+    /** Source for deriving candidates. Default: `globalThis.location`. */
+    location?: LocationLike;
+}
+/**
+ * Ordered, de-duplicated candidate endpoints:
+ *  1. same-origin `/websocket` (the suite deploy reverse-proxies Moonraker here),
+ *  2. the page host on Moonraker's default `:7125` (direct, no proxy),
+ *  3. `localhost:7125` (on-printer / Tauri webview, whose origin is `tauri.localhost`).
+ */
+declare function deriveCandidates(location?: LocationLike): string[];
+/**
+ * Resolve a reachable Moonraker WebSocket URL. `override` wins immediately; otherwise the
+ * candidates are raced and the first socket to open wins (the rest are closed). Rejects if
+ * none open within `timeoutMs`.
+ */
+declare function resolveMoonrakerUrl(opts?: DiscoveryOptions): Promise<string>;
+
 declare const SUBSCRIPTION_CONTRACT_VERSION = 1;
 /** Status-only tier (farm overview / ambient screen): the minimum to show state + progress. */
 declare const NARROW_STATUS: SubscriptionMap;
@@ -361,7 +392,7 @@ interface ThemeTokens {
     warning: string;
     danger: string;
 }
-type ThemeName = 'tutankhamun' | 'horus' | 'anubis';
+type ThemeName = 'tutankhamun' | 'horus' | 'anubis' | 'light' | 'dark';
 declare const themes: Record<ThemeName, ThemeTokens>;
 declare const DEFAULT_THEME: ThemeName;
 /** `{ "--fm-bg": "#0E0F12", ... }` for a theme. */
@@ -512,4 +543,4 @@ declare function applySettings(s: UserSettings, el?: {
     dir: 'ltr' | 'rtl';
 };
 
-export { type AgentAllow, type AgentEvent, type BackendMessage, type Catalog, CommandSender, type CommandSenderOptions, type ConnectionState, type Connector, type ConnectorCallbacks, DEFAULT_LOCALE, DEFAULT_SETTINGS, DEFAULT_THEME, FILAMIND_COMMAND_EVENT, FULL_CONTROL, FilaMindSession, type IdentifyInfo, type KlippyState, LOCALES, type Listener, type LocaleMeta, type LogEntry, type LogLevel, Logger, MoonrakerClient, type MoonrakerClientOptions, NARROW_STATUS, NULL_LOGGER, Observable, type Params, type PluralCategory, type PrinterObjects, PrinterState, type PromptButton, type PromptDialog, type PromptEvent, PromptParser, REMOTE_MESSAGE_LEVELS, REMOTE_VIEWS, RTL_LOCALES, type RemoteCommand, type RemoteMessageLevel, type RemoteView, type RestorePoint, RestorePoints, type RestoreStore, SETTINGS_VERSION, SUBSCRIPTION_CONTRACT_VERSION, type SessionOptions, type SettingsPersistence, SettingsStore, type Source, type Stamped, type SubscriptionMap, type SubscriptionTier, type SurfaceTarget, type ThemeName, type ThemeTokens, Translator, UNKNOWN, type UserSettings, type WebSocketLike, type WidgetDefinition, WriteArbiter, type WriteGuard, WriteRefused, _resetRegistry, aggregateSubscriptions, applySettings, applyTheme, deepMerge, deriveKlippyState, deriveMachineId, fnv1a, freshness, getWidget, getWidgets, handleAgentCommand, isKlippyLive, isRtl, isStale, localStoragePersistence, localeMeta, memoryPersistence, memoryRestoreStore, mergeSubscriptions, migrate, moonrakerDbPersistence, parseAgentEvent, parseCommand, pluralCategory, registerWidget, resolveMessage, roamSettings, stamp, themeToCssVars, themes, tier, translate };
+export { type AgentAllow, type AgentEvent, type BackendMessage, type Catalog, CommandSender, type CommandSenderOptions, type ConnectionState, type Connector, type ConnectorCallbacks, DEFAULT_LOCALE, DEFAULT_SETTINGS, DEFAULT_THEME, type DiscoveryOptions, FILAMIND_COMMAND_EVENT, FULL_CONTROL, FilaMindSession, type IdentifyInfo, type KlippyState, LOCALES, type Listener, type LocaleMeta, type LocationLike, type LogEntry, type LogLevel, Logger, MoonrakerClient, type MoonrakerClientOptions, NARROW_STATUS, NULL_LOGGER, Observable, type Params, type PluralCategory, type PrinterObjects, PrinterState, type PromptButton, type PromptDialog, type PromptEvent, PromptParser, REMOTE_MESSAGE_LEVELS, REMOTE_VIEWS, RTL_LOCALES, type RemoteCommand, type RemoteMessageLevel, type RemoteView, type RestorePoint, RestorePoints, type RestoreStore, SETTINGS_VERSION, SUBSCRIPTION_CONTRACT_VERSION, type SessionOptions, type SettingsPersistence, SettingsStore, type Source, type Stamped, type SubscriptionMap, type SubscriptionTier, type SurfaceTarget, type ThemeName, type ThemeTokens, Translator, UNKNOWN, type UserSettings, type WebSocketLike, type WidgetDefinition, WriteArbiter, type WriteGuard, WriteRefused, _resetRegistry, aggregateSubscriptions, applySettings, applyTheme, deepMerge, deriveCandidates, deriveKlippyState, deriveMachineId, fnv1a, freshness, getWidget, getWidgets, handleAgentCommand, isKlippyLive, isRtl, isStale, localStoragePersistence, localeMeta, memoryPersistence, memoryRestoreStore, mergeSubscriptions, migrate, moonrakerDbPersistence, parseAgentEvent, parseCommand, pluralCategory, registerWidget, resolveMessage, resolveMoonrakerUrl, roamSettings, stamp, themeToCssVars, themes, tier, translate };

package/dist/index.js

@@ -270,6 +270,85 @@ function xhrUpload(url, form, onProgress) {
   });
 }
 
+// src/moonraker/discovery.ts
+var defaultWsFactory2 = (url) => new WebSocket(url);
+function deriveCandidates(location) {
+  const loc = location ?? globalThis.location ?? {};
+  const wsProto = loc.protocol === "https:" ? "wss" : "ws";
+  const host = loc.hostname && loc.hostname.length > 0 ? loc.hostname : "localhost";
+  return [
+    .../* @__PURE__ */ new Set([
+      `${wsProto}://${host}/websocket`,
+      `${wsProto}://${host}:7125/websocket`,
+      `ws://localhost:7125/websocket`
+    ])
+  ];
+}
+function resolveMoonrakerUrl(opts = {}) {
+  const override = opts.override?.trim();
+  if (override) return Promise.resolve(override);
+  const candidates = opts.candidates ?? deriveCandidates(opts.location);
+  if (candidates.length === 0) {
+    return Promise.reject(new Error("moonraker discovery: no candidate endpoints"));
+  }
+  const makeWs = opts.wsFactory ?? defaultWsFactory2;
+  const timeoutMs = opts.timeoutMs ?? 3e3;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let remaining = candidates.length;
+    const sockets = [];
+    const timer = setTimeout(finishFail, timeoutMs);
+    function cleanup() {
+      clearTimeout(timer);
+      for (const s of sockets) {
+        s.onopen = null;
+        s.onerror = null;
+        s.onclose = null;
+        try {
+          s.close();
+        } catch {
+        }
+      }
+    }
+    function finishOk(url) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(url);
+    }
+    function finishFail() {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new Error(`moonraker discovery: no endpoint responded (${candidates.join(", ")})`));
+    }
+    function lose() {
+      remaining -= 1;
+      if (remaining <= 0) finishFail();
+    }
+    for (const url of candidates) {
+      let s;
+      try {
+        s = makeWs(url);
+      } catch {
+        lose();
+        continue;
+      }
+      sockets.push(s);
+      let done = false;
+      const fail = () => {
+        if (!done) {
+          done = true;
+          lose();
+        }
+      };
+      s.onopen = () => finishOk(url);
+      s.onerror = fail;
+      s.onclose = fail;
+    }
+  });
+}
+
 // src/moonraker/subscriptions.ts
 var SUBSCRIPTION_CONTRACT_VERSION = 1;
 var NARROW_STATUS = {
@@ -759,6 +838,38 @@ var themes = {
     success: "#6E7C3A",
     warning: "#D98E2B",
     danger: "#8C1F1A"
+  },
+  // neutral light — a conventional bright UI for users who prefer it
+  light: {
+    bg: "#F7F8FA",
+    surface: "#FFFFFF",
+    surface2: "#EEF1F5",
+    border: "#D6DBE2",
+    text: "#1A1D23",
+    textMuted: "#5B6573",
+    primary: "#2563EB",
+    primaryContrast: "#FFFFFF",
+    secondary: "#64748B",
+    accent: "#0D9488",
+    success: "#15803D",
+    warning: "#B45309",
+    danger: "#DC2626"
+  },
+  // neutral dark — a conventional dark UI, distinct from the warm Pharaonic palettes
+  dark: {
+    bg: "#0F1115",
+    surface: "#171A21",
+    surface2: "#1F232C",
+    border: "#2C313C",
+    text: "#E6E8EC",
+    textMuted: "#9AA2AE",
+    primary: "#4F8EF7",
+    primaryContrast: "#0B0D11",
+    secondary: "#6B7280",
+    accent: "#14B8A6",
+    success: "#22A06B",
+    warning: "#E0A92E",
+    danger: "#E5484D"
   }
 };
 var DEFAULT_THEME = "tutankhamun";
@@ -1140,6 +1251,7 @@ export {
   applySettings,
   applyTheme,
   deepMerge,
+  deriveCandidates,
   deriveKlippyState,
   deriveMachineId,
   fnv1a,
@@ -1162,6 +1274,7 @@ export {
   pluralCategory,
   registerWidget,
   resolveMessage,
+  resolveMoonrakerUrl,
   roamSettings,
   stamp,
   themeToCssVars,

package/package.json

@@ -1,21 +1,33 @@
 {
   "name": "@filamind-app/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared foundation for the FilaMind suite — Moonraker client, reactive printer state, provenance-stamped values, design tokens, and the widget/plugin registry. Framework-agnostic TypeScript.",
   "license": "GPL-3.0-or-later",
-  "repository": { "type": "git", "url": "git+https://github.com/filamind-app/filamind-core.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/filamind-app/filamind-core.git"
+  },
   "homepage": "https://github.com/filamind-app/filamind-core#readme",
-  "bugs": { "url": "https://github.com/filamind-app/filamind-core/issues" },
+  "bugs": {
+    "url": "https://github.com/filamind-app/filamind-core/issues"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "sideEffects": false,
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts --format esm --dts --watch",