@filamind-app/core 0.1.2 → 0.1.4

package/README.md

@@ -18,6 +18,7 @@ The shared foundation of the FilaMind suite — **framework-agnostic TypeScript*
 | `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()` |
+| `moonraker/rpc-types.ts` | **RPC type safety** — `RpcError` (keeps JSON-RPC `code`/`data`) · `MoonrakerMethods` typed-`call` result map · `NotifyEvent` + `parseNotifyEvent()` discriminated notify union |
 | `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`) |
 | `session/session.ts` | **`FilaMindSession`** — the orchestrator: staged init (identify → capabilities → query/seed → subscribe), routes `notify_*`, owns the Klippy-aware `live`/stale gate |

package/dist/index.d.ts

@@ -90,6 +90,85 @@ declare class Logger {
 /** A no-op logger for when none is supplied. */
 declare const NULL_LOGGER: Logger;
 
+/** A JSON-RPC error that keeps Moonraker's numeric `code` and optional `data` payload. */
+declare class RpcError extends Error {
+    readonly code?: number | undefined;
+    readonly data?: unknown | undefined;
+    constructor(message: string, code?: number | undefined, data?: unknown | undefined);
+}
+interface ServerInfo {
+    klippy_connected: boolean;
+    klippy_state: 'ready' | 'startup' | 'shutdown' | 'error' | 'disconnected';
+    components?: string[];
+    warnings?: string[];
+    [k: string]: unknown;
+}
+interface PrinterInfo {
+    state: 'ready' | 'startup' | 'shutdown' | 'error';
+    state_message: string;
+    hostname?: string;
+    software_version?: string;
+    [k: string]: unknown;
+}
+interface QueryResult {
+    eventtime: number;
+    status: Record<string, unknown>;
+}
+/** Result types for the methods the suite calls most. Unlisted methods still work via `call<T>()`. */
+interface MoonrakerMethods {
+    'server.info': ServerInfo;
+    'server.connection.identify': {
+        connection_id: number;
+    };
+    'printer.info': PrinterInfo;
+    'printer.objects.list': {
+        objects: string[];
+    };
+    'printer.objects.query': QueryResult;
+    'printer.objects.subscribe': QueryResult;
+    'printer.gcode.script': 'ok';
+    'printer.emergency_stop': 'ok';
+    'printer.restart': 'ok';
+    'printer.firmware_restart': 'ok';
+    'machine.system_info': {
+        system_info: Record<string, unknown>;
+    };
+    'machine.reboot': 'ok';
+    'machine.shutdown': 'ok';
+    'server.database.get_item': {
+        namespace: string;
+        key?: string;
+        value: unknown;
+    };
+    'server.database.post_item': {
+        namespace: string;
+        key?: string;
+        value: unknown;
+    };
+}
+/** A narrowed view of Moonraker's `notify_*` broadcasts (whose raw params are positional arrays). */
+type NotifyEvent = {
+    method: 'notify_status_update';
+    status: Record<string, unknown>;
+    eventtime: number;
+} | {
+    method: 'notify_gcode_response';
+    response: string;
+} | {
+    method: 'notify_klippy_ready';
+} | {
+    method: 'notify_klippy_shutdown';
+} | {
+    method: 'notify_klippy_disconnected';
+} | {
+    method: 'notify_agent_event';
+    agent: string;
+    event: string;
+    data: unknown;
+};
+/** Parse a raw (method, params) notify into a typed event, or null for an unhandled method. */
+declare function parseNotifyEvent(method: string, params: unknown): NotifyEvent | null;
+
 /** Minimal WebSocket surface the client uses — the DOM WebSocket satisfies it; tests fake it. */
 interface WebSocketLike {
     send(data: string): void;
@@ -130,6 +209,7 @@ declare class MoonrakerClient implements Connector {
     setCallbacks(cb: ConnectorCallbacks): void;
     connect(): Promise<void>;
     close(): void;
+    call<M extends keyof MoonrakerMethods>(method: M, params?: Record<string, unknown>): Promise<MoonrakerMethods[M]>;
     call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
     subscribe(objects: SubscriptionMap): Promise<void>;
     upload(root: string, file: File, onProgress?: (pct: number) => void): Promise<void>;
@@ -377,6 +457,42 @@ declare function aggregateSubscriptions(ids: string[]): SubscriptionMap;
 /** Test/host helper — clear the registry. */
 declare function _resetRegistry(): void;
 
+type SurfaceHint = 'dense-desktop' | 'thumb-phone' | 'big-touch';
+/** Derive the layout hint from the surface + viewport width (px). The touch screen is always
+ *  big-touch; the 3d web UI is dense on wide viewports and a single thumb column when narrow. */
+declare function surfaceHint(target: SurfaceTarget, viewportWidth: number): SurfaceHint;
+/** One slot in the shared dashboard definition. */
+interface DashboardSlot {
+    widgetId: string;
+    /** ascending display order; slots without it sort after ordered ones */
+    order?: number;
+    /** hide this widget on these hints (e.g. a dense-only widget hidden on thumb-phone) */
+    hideOn?: SurfaceHint[];
+}
+/** The single serializable dashboard definition (persisted in UserSettings, machineUUID-keyed). */
+interface DashboardLayout {
+    version: number;
+    slots: DashboardSlot[];
+}
+declare const DASHBOARD_LAYOUT_VERSION = 1;
+interface ResolvedDashboard {
+    hint: SurfaceHint;
+    columns: number;
+    /** the widgets to render, in order, already filtered for this hint */
+    widgets: WidgetDefinition[];
+}
+/**
+ * Adapt one layout definition + the available widgets to a surface hint.
+ *
+ * Slots are honoured first (ordered, minus those hidden on this hint); any registered widget the
+ * layout doesn't mention is appended (so newly added widgets still appear). A widget a slot hides
+ * on this hint stays hidden even though it is available. With no layout, all available widgets
+ * render in registry order.
+ */
+declare function resolveDashboard(layout: DashboardLayout | undefined, available: WidgetDefinition[], hint: SurfaceHint): ResolvedDashboard;
+/** Coerce an arbitrary blob into a valid DashboardLayout, or undefined. Used by settings migrate. */
+declare function coerceDashboardLayout(raw: unknown): DashboardLayout | undefined;
+
 interface ThemeTokens {
     bg: string;
     surface: string;
@@ -502,6 +618,8 @@ interface UserSettings {
     motifDensity: 'off' | 'subtle' | 'full';
     /** reduce animation/illustration for low-power or accessibility */
     reducedMotion: boolean;
+    /** the single per-surface dashboard definition (resolved per surface + viewport at render) */
+    dashboardLayout?: DashboardLayout;
 }
 declare const DEFAULT_SETTINGS: UserSettings;
 /** Coerce an arbitrary (old / foreign / partial) blob into valid UserSettings — drops unknown keys,
@@ -543,4 +661,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, 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 };
+export { type AgentAllow, type AgentEvent, type BackendMessage, type Catalog, CommandSender, type CommandSenderOptions, type ConnectionState, type Connector, type ConnectorCallbacks, DASHBOARD_LAYOUT_VERSION, DEFAULT_LOCALE, DEFAULT_SETTINGS, DEFAULT_THEME, type DashboardLayout, type DashboardSlot, 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, type MoonrakerMethods, NARROW_STATUS, NULL_LOGGER, type NotifyEvent, Observable, type Params, type PluralCategory, type PrinterInfo, type PrinterObjects, PrinterState, type PromptButton, type PromptDialog, type PromptEvent, PromptParser, type QueryResult, REMOTE_MESSAGE_LEVELS, REMOTE_VIEWS, RTL_LOCALES, type RemoteCommand, type RemoteMessageLevel, type RemoteView, type ResolvedDashboard, type RestorePoint, RestorePoints, type RestoreStore, RpcError, SETTINGS_VERSION, SUBSCRIPTION_CONTRACT_VERSION, type ServerInfo, type SessionOptions, type SettingsPersistence, SettingsStore, type Source, type Stamped, type SubscriptionMap, type SubscriptionTier, type SurfaceHint, type SurfaceTarget, type ThemeName, type ThemeTokens, Translator, UNKNOWN, type UserSettings, type WebSocketLike, type WidgetDefinition, WriteArbiter, type WriteGuard, WriteRefused, _resetRegistry, aggregateSubscriptions, applySettings, applyTheme, coerceDashboardLayout, deepMerge, deriveCandidates, deriveKlippyState, deriveMachineId, fnv1a, freshness, getWidget, getWidgets, handleAgentCommand, isKlippyLive, isRtl, isStale, localStoragePersistence, localeMeta, memoryPersistence, memoryRestoreStore, mergeSubscriptions, migrate, moonrakerDbPersistence, parseAgentEvent, parseCommand, parseNotifyEvent, pluralCategory, registerWidget, resolveDashboard, resolveMessage, resolveMoonrakerUrl, roamSettings, stamp, surfaceHint, themeToCssVars, themes, tier, translate };

package/dist/index.js

@@ -105,6 +105,51 @@ function deepMerge(target, patch) {
   return out;
 }
 
+// src/moonraker/rpc-types.ts
+var RpcError = class extends Error {
+  constructor(message, code, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.name = "RpcError";
+  }
+  code;
+  data;
+};
+function parseNotifyEvent(method, params) {
+  const arr = Array.isArray(params) ? params : [];
+  switch (method) {
+    case "notify_status_update":
+      return {
+        method: "notify_status_update",
+        status: arr[0] ?? {},
+        eventtime: typeof arr[1] === "number" ? arr[1] : 0
+      };
+    case "notify_gcode_response":
+      return {
+        method: "notify_gcode_response",
+        response: typeof arr[0] === "string" ? arr[0] : ""
+      };
+    case "notify_klippy_ready":
+      return { method: "notify_klippy_ready" };
+    case "notify_klippy_shutdown":
+      return { method: "notify_klippy_shutdown" };
+    case "notify_klippy_disconnected":
+      return { method: "notify_klippy_disconnected" };
+    case "notify_agent_event": {
+      const e = arr[0] ?? {};
+      return {
+        method: "notify_agent_event",
+        agent: typeof e.agent === "string" ? e.agent : "",
+        event: typeof e.event === "string" ? e.event : "",
+        data: e.data
+      };
+    }
+    default:
+      return null;
+  }
+}
+
 // src/moonraker/client.ts
 var defaultWsFactory = (url) => new WebSocket(url);
 var MoonrakerClient = class {
@@ -169,7 +214,7 @@ var MoonrakerClient = class {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
-        reject(new Error(`moonraker request timed out: ${method}`));
+        reject(new RpcError(`moonraker request timed out: ${method}`));
       }, this.opts.requestTimeoutMs ?? 1e4);
       this.pending.set(id, { resolve, reject, timer });
       this.send({ jsonrpc: "2.0", method, params, id });
@@ -246,7 +291,7 @@ var MoonrakerClient = class {
       if (!p) return;
       clearTimeout(p.timer);
       this.pending.delete(msg.id);
-      if (msg.error) p.reject(new Error(msg.error.message ?? "rpc error"));
+      if (msg.error) p.reject(new RpcError(msg.error.message ?? "rpc error", msg.error.code, msg.error.data));
       else p.resolve(msg.result);
       return;
     }
@@ -789,6 +834,58 @@ function _resetRegistry() {
   registry.clear();
 }
 
+// src/registry/dashboard-resolver.ts
+var COLUMNS = {
+  "dense-desktop": 3,
+  "thumb-phone": 1,
+  "big-touch": 2
+};
+function surfaceHint(target, viewportWidth) {
+  if (target === "screen") return "big-touch";
+  return viewportWidth < 640 ? "thumb-phone" : "dense-desktop";
+}
+var DASHBOARD_LAYOUT_VERSION = 1;
+var HINTS = ["dense-desktop", "thumb-phone", "big-touch"];
+function resolveDashboard(layout, available, hint) {
+  const byId = new Map(available.map((w) => [w.id, w]));
+  const slots = layout?.slots ?? [];
+  const hiddenHere = new Set(
+    slots.filter((s) => (s.hideOn ?? []).includes(hint)).map((s) => s.widgetId)
+  );
+  const used = /* @__PURE__ */ new Set();
+  const widgets = [];
+  for (const slot of [...slots].filter((s) => !(s.hideOn ?? []).includes(hint)).sort((a, b) => (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY))) {
+    const w = byId.get(slot.widgetId);
+    if (w && !used.has(w.id)) {
+      widgets.push(w);
+      used.add(w.id);
+    }
+  }
+  for (const w of available) {
+    if (!used.has(w.id) && !hiddenHere.has(w.id)) widgets.push(w);
+  }
+  return { hint, columns: COLUMNS[hint], widgets };
+}
+function coerceDashboardLayout(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const r = raw;
+  if (!Array.isArray(r.slots)) return void 0;
+  const slots = [];
+  for (const item of r.slots) {
+    if (!item || typeof item !== "object") continue;
+    const s = item;
+    if (typeof s.widgetId !== "string" || !s.widgetId) continue;
+    const slot = { widgetId: s.widgetId };
+    if (typeof s.order === "number" && Number.isFinite(s.order)) slot.order = s.order;
+    if (Array.isArray(s.hideOn)) {
+      const hideOn = s.hideOn.filter((h) => HINTS.includes(h));
+      if (hideOn.length) slot.hideOn = hideOn;
+    }
+    slots.push(slot);
+  }
+  return { version: DASHBOARD_LAYOUT_VERSION, slots };
+}
+
 // src/theme/tokens.ts
 var themes = {
   // flagship default — obsidian + gold + lapis + turquoise
@@ -1099,7 +1196,7 @@ var DENSITIES = /* @__PURE__ */ new Set(["comfortable", "compact"]);
 var MOTIFS = /* @__PURE__ */ new Set(["off", "subtle", "full"]);
 function migrate(raw) {
   const r = raw && typeof raw === "object" ? raw : {};
-  return {
+  const out = {
     version: SETTINGS_VERSION,
     theme: typeof r.theme === "string" && r.theme in themes ? r.theme : DEFAULT_SETTINGS.theme,
     locale: typeof r.locale === "string" && LOCALES.some((l) => l.code === r.locale) ? r.locale : DEFAULT_SETTINGS.locale,
@@ -1107,6 +1204,9 @@ function migrate(raw) {
     motifDensity: typeof r.motifDensity === "string" && MOTIFS.has(r.motifDensity) ? r.motifDensity : DEFAULT_SETTINGS.motifDensity,
     reducedMotion: typeof r.reducedMotion === "boolean" ? r.reducedMotion : DEFAULT_SETTINGS.reducedMotion
   };
+  const layout = coerceDashboardLayout(r.dashboardLayout);
+  if (layout) out.dashboardLayout = layout;
+  return out;
 }
 function memoryPersistence() {
   let store;
@@ -1221,6 +1321,7 @@ function applySettings(s, el) {
 }
 export {
   CommandSender,
+  DASHBOARD_LAYOUT_VERSION,
   DEFAULT_LOCALE,
   DEFAULT_SETTINGS,
   DEFAULT_THEME,
@@ -1239,6 +1340,7 @@ export {
   REMOTE_VIEWS,
   RTL_LOCALES,
   RestorePoints,
+  RpcError,
   SETTINGS_VERSION,
   SUBSCRIPTION_CONTRACT_VERSION,
   SettingsStore,
@@ -1250,6 +1352,7 @@ export {
   aggregateSubscriptions,
   applySettings,
   applyTheme,
+  coerceDashboardLayout,
   deepMerge,
   deriveCandidates,
   deriveKlippyState,
@@ -1271,12 +1374,15 @@ export {
   moonrakerDbPersistence,
   parseAgentEvent,
   parseCommand,
+  parseNotifyEvent,
   pluralCategory,
   registerWidget,
+  resolveDashboard,
   resolveMessage,
   resolveMoonrakerUrl,
   roamSettings,
   stamp,
+  surfaceHint,
   themeToCssVars,
   themes,
   tier,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@filamind-app/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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": {