@filamind-app/core 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @filamind-app/core
+
+The shared foundation of the FilaMind suite — **framework-agnostic TypeScript** consumed by FilaMind 3d
+(web), FilaMind screen (touch), and FilaMind flow. Phase 0.
+
+## What's here
+| Module | Purpose |
+| --- | --- |
+| `provenance.ts` | `Stamped<T>` "never-lie" values (`value · ts · source · staleAfter`) + `isStale` / `freshness` |
+| `state/observable.ts` | a tiny framework-agnostic observable (consumers bind it to Pinia/signals) |
+| `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/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`) |
+| `session/session.ts` | **`FilaMindSession`** — the orchestrator: staged init (identify → capabilities → query/seed → subscribe), routes `notify_*`, owns the Klippy-aware `live`/stale gate |
+| `safety/write-arbiter.ts` | fail-closed **`WriteArbiter`** — the single chokepoint for every mutation; enforces safe-mode + a caller guard |
+| `identity/machine.ts` | `deriveMachineId` → stable `fm-<hash>` from `machine.system_info` (the roaming-settings key) |
+| `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 |
+| `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) |
+| `settings/settings.ts` | unified user settings (theme · locale · density · motif · reduced-motion): `SettingsStore` (patch/hydrate/reset/export/import), **`migrate()`** (versioned, enum-coercing — `import()` trusts no foreign JSON), `applySettings` (re-theme + RTL dir), persistence seam (Moonraker-DB / localStorage) |
+
+## Wiring (the consumer entry point)
+```ts
+import { MoonrakerClient, FilaMindSession, FULL_CONTROL } from '@filamind-app/core'
+
+const connector = new MoonrakerClient({ url: 'ws://printer.local:7125/websocket' })
+const session = new FilaMindSession(connector, {
+  subscriptions: FULL_CONTROL,
+  identify: { client_name: 'FilaMind 3d', version: '0.1.0', type: 'web' },
+})
+await session.start()
+
+// reactive, framework-agnostic — bind these to Pinia/signals/etc.
+session.live.subscribe((v) => {/* dim the UI when not trustworthy-live */})
+session.printer.objects.subscribe((o) => {/* render telemetry */})
+session.prompt.subscribe((ev) => {/* show a Klipper modal */})
+```
+
+## Scripts
+```bash
+npm install
+npm run type-check   # tsc --noEmit
+npm test             # vitest (76 pure-logic tests)
+npm run build        # tsup → dist/ (ESM + .d.ts)
+```
+
+## Notes
+- Consumed by the suite apps (FilaMind 3d / screen / flow) via the workspace in development.
+- Framework-agnostic on purpose: no Vue/React import in core. The reactive layer is a plain `Observable`;
+  Vue/Pinia adapts it on the consumer side.
+- Versions are pinned to current real latest-stable; bump deliberately at first real install.
+- GPL-3.0-or-later. FilaMind's own — no third-party project named (R1).
+
+## Credits
+
+Built and maintained by the DeltaFabs team:
+
+- abdelmonem awad - <eg2@live.com>
+- Ahmed bebars - <Ahmedbebars1@gmail.com>
+- Kareem Salama - <Golden.kiko@gmail.com>
+
+## License
+
+[GPL-3.0-or-later](LICENSE) © 2026 DeltaFabs team.

package/dist/index.d.ts

@@ -0,0 +1,515 @@
+type Source = 'live' | 'cache' | 'optimistic' | 'unknown';
+interface Stamped<T> {
+    value: T;
+    /** when this value arrived (ms epoch, client clock — Moonraker has no server timestamp) */
+    ts: number;
+    source: Source;
+    /** ms after `ts` when the value should be treated as stale (omit = never goes stale on its own) */
+    staleAfter?: number;
+}
+declare function stamp<T>(value: T, source?: Source, staleAfter?: number, now?: number): Stamped<T>;
+declare const UNKNOWN: Stamped<undefined>;
+declare function isStale(s: Stamped<unknown> | undefined, now?: number): boolean;
+/** UI hint a widget can map to a class: 'ok' | 'stale' | 'unknown'. */
+declare function freshness(s: Stamped<unknown> | undefined, now?: number): 'ok' | 'stale' | 'unknown';
+
+type Listener<T> = (value: T) => void;
+declare class Observable<T> {
+    private _value;
+    private listeners;
+    constructor(_value: T);
+    get value(): T;
+    set(v: T): void;
+    update(fn: (v: T) => T): void;
+    /** Subscribe and receive the current value immediately. Returns an unsubscribe fn. */
+    subscribe(fn: Listener<T>): () => void;
+    private emit;
+}
+
+type PrinterObjects = Record<string, Record<string, unknown>>;
+declare class PrinterState {
+    readonly objects: Observable<PrinterObjects>;
+    private pendingPatch;
+    private flushTimer;
+    private readonly coalesceMs;
+    constructor(coalesceMs?: number);
+    /** Seed from a printer.objects.query result. */
+    seed(objects: PrinterObjects): void;
+    /** Feed notify_status_update params: `[ { <object>: { <field>: value } }, eventtime ]`. */
+    applyNotify(params: unknown): void;
+    /** Force-apply any pending coalesced patch now (e.g. on tab focus). */
+    flush(): void;
+}
+/** Recursive merge of plain objects; arrays + primitives are replaced. Returns a new object. */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, patch: unknown): T;
+
+type ConnectionState = 'idle' | 'connecting' | 'identifying' | 'ready' | 'reconnecting' | 'closed';
+interface ConnectorCallbacks {
+    /** notify_* fan-out (e.g. notify_status_update, notify_gcode_response) */
+    onUpdate?: (method: string, params: unknown) => void;
+    onConnectProgress?: (state: ConnectionState) => void;
+    onError?: (err: Error) => void;
+    onReconnected?: () => void;
+}
+/** Objects subscription map: { "<object>": ["<field>", ...] | null } (null = all fields). */
+type SubscriptionMap = Record<string, string[] | null>;
+interface Connector {
+    readonly state: ConnectionState;
+    connect(): Promise<void>;
+    close(): void;
+    /** JSON-RPC request/response. */
+    call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Subscribe to printer objects; the impl remembers the set and restores it on reconnect. */
+    subscribe(objects: SubscriptionMap): Promise<void>;
+    upload(root: string, file: File, onProgress?: (pct: number) => void): Promise<void>;
+    download(path: string): Promise<Blob>;
+    setCallbacks(cb: ConnectorCallbacks): void;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogEntry {
+    ts: number;
+    level: LogLevel;
+    msg: string;
+    data?: unknown;
+}
+declare class Logger {
+    private readonly max;
+    private readonly sink?;
+    private ring;
+    constructor(max?: number, sink?: ((e: LogEntry) => void) | undefined);
+    log(level: LogLevel, msg: string, data?: unknown): void;
+    debug(msg: string, data?: unknown): void;
+    info(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
+    /** Snapshot of recent events (for the diagnostics bundle). */
+    recent(): LogEntry[];
+    clear(): void;
+}
+/** A no-op logger for when none is supplied. */
+declare const NULL_LOGGER: Logger;
+
+/** Minimal WebSocket surface the client uses — the DOM WebSocket satisfies it; tests fake it. */
+interface WebSocketLike {
+    send(data: string): void;
+    close(): void;
+    onopen: ((ev?: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((ev?: unknown) => void) | null;
+    onclose: ((ev?: unknown) => void) | null;
+}
+interface MoonrakerClientOptions {
+    /** ws(s)://host:port/websocket */
+    url: string;
+    requestTimeoutMs?: number;
+    maxBackoffMs?: number;
+    /** stop reconnecting after this many consecutive attempts → terminal 'closed' (default: unlimited) */
+    maxReconnectAttempts?: number;
+    wsFactory?: (url: string) => WebSocketLike;
+    logger?: Logger;
+}
+declare class MoonrakerClient implements Connector {
+    private readonly opts;
+    private ws?;
+    private _state;
+    private nextId;
+    private pending;
+    private cb;
+    private subs;
+    private backoff;
+    private reconnectAttempts;
+    private closedByUser;
+    private hasOpened;
+    private reconnectTimer?;
+    private readonly makeWs;
+    constructor(opts: MoonrakerClientOptions);
+    get state(): ConnectionState;
+    setCallbacks(cb: ConnectorCallbacks): void;
+    connect(): Promise<void>;
+    close(): void;
+    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>;
+    download(path: string): Promise<Blob>;
+    private httpBase;
+    private send;
+    private setState;
+    private restoreSubs;
+    private scheduleReconnect;
+    private failAll;
+    private onMessage;
+}
+
+declare const SUBSCRIPTION_CONTRACT_VERSION = 1;
+/** Status-only tier (farm overview / ambient screen): the minimum to show state + progress. */
+declare const NARROW_STATUS: SubscriptionMap;
+/** Full-control tier (the daily-driver UI): everything a control surface needs. */
+declare const FULL_CONTROL: SubscriptionMap;
+type SubscriptionTier = 'narrow' | 'full';
+declare function tier(t: SubscriptionTier): SubscriptionMap;
+/** Union of subscription maps (`null` = "all fields" wins). The single source for the
+ *  null-wins merge rule — consumers compose a baseline tier with widget-declared needs. */
+declare function mergeSubscriptions(...maps: SubscriptionMap[]): SubscriptionMap;
+
+type KlippyState = 'ready' | 'startup' | 'shutdown' | 'error' | 'disconnected';
+/** Map a Moonraker `server.info.klippy_state` string to a KlippyState (default: disconnected). */
+declare function deriveKlippyState(raw: unknown): KlippyState;
+/** Printer data is trustworthy as "live" only when Klippy is ready. */
+declare function isKlippyLive(state: KlippyState): boolean;
+
+type ButtonStyle = 'primary' | 'secondary' | 'warning';
+interface PromptButton {
+    label: string;
+    gcode?: string;
+    style?: ButtonStyle;
+}
+interface PromptDialog {
+    title?: string;
+    text: string[];
+    buttons: PromptButton[];
+    footer: PromptButton[];
+}
+type PromptEvent = {
+    type: 'show';
+    dialog: PromptDialog;
+} | {
+    type: 'end';
+} | null;
+declare class PromptParser {
+    private current;
+    /** Feed one notify_gcode_response line. Returns a PromptEvent at show/end, else null. */
+    feed(line: string): PromptEvent;
+}
+
+/** The single agent-event name FilaMind uses; everything else on the bus is ignored. */
+declare const FILAMIND_COMMAND_EVENT = "filamind:command";
+/** The views a screen-style surface can be told to show (matches the touch app's tabs). */
+declare const REMOTE_VIEWS: readonly ["status", "control", "settings"];
+type RemoteView = (typeof REMOTE_VIEWS)[number];
+declare const REMOTE_MESSAGE_LEVELS: readonly ["info", "warn"];
+type RemoteMessageLevel = (typeof REMOTE_MESSAGE_LEVELS)[number];
+/** A UI-only instruction sent from one surface to another. */
+type RemoteCommand = {
+    kind: 'navigate';
+    view: RemoteView;
+} | {
+    kind: 'message';
+    level: RemoteMessageLevel;
+    text: string;
+} | {
+    kind: 'locate';
+};
+/** The shape Moonraker delivers in notify_agent_event params[0]. */
+interface AgentEvent {
+    agent: string;
+    event: string;
+    data?: unknown;
+}
+/** Validate an arbitrary blob (from the broadcast bus) into a RemoteCommand, or null if it isn't one. */
+declare function parseCommand(raw: unknown): RemoteCommand | null;
+/** Parse Moonraker's notify_agent_event params (an array holding one event object) into an AgentEvent. */
+declare function parseAgentEvent(params: unknown): AgentEvent | null;
+/** Optional sender allow-list: an array of accepted agent names, or a predicate over the name. */
+type AgentAllow = readonly string[] | ((agent: string) => boolean);
+/** If an agent event is a (validated) FilaMind command from an allowed sender, hand it to the surface's
+ *  dispatcher. The allow-list is best-effort defence-in-depth: client_name is self-asserted, which is
+ *  WHY these commands must stay strictly UI-only and never reach the printer-write path. */
+declare function handleAgentCommand(ev: AgentEvent, dispatch: (cmd: RemoteCommand) => void, opts?: {
+    allowFrom?: AgentAllow;
+}): void;
+
+interface IdentifyInfo {
+    client_name: string;
+    version: string;
+    type: 'web' | 'display' | 'desktop' | 'bot' | 'agent';
+    url?: string;
+    access_token?: string;
+}
+interface SessionOptions {
+    /** the active subscription set (a tier or aggregateSubscriptions(active widgets)) */
+    subscriptions?: SubscriptionMap;
+    identify?: IdentifyInfo;
+    logger?: Logger;
+    /** Receive cross-surface agent events (notify_agent_event) — e.g. remote-control commands from
+     *  another FilaMind surface. Discrete (fired per event, never replayed), so no stale re-fire. */
+    onAgentEvent?: (ev: AgentEvent) => void;
+}
+declare class FilaMindSession {
+    private readonly connector;
+    private readonly opts;
+    readonly printer: PrinterState;
+    readonly klippy: Observable<KlippyState>;
+    readonly capabilities: Observable<string[]>;
+    /** true only when data is trustworthy as live (connected + Klippy ready). The UI dims when false. */
+    readonly live: Observable<boolean>;
+    readonly prompt: Observable<PromptEvent>;
+    private subs;
+    private readonly log;
+    private readonly prompts;
+    private bootstrapping;
+    constructor(connector: Connector, opts?: SessionOptions);
+    /** Set/replace the active subscription set (e.g. when the dashboard's widgets change). */
+    setSubscriptions(subs: SubscriptionMap): void;
+    start(): Promise<void>;
+    stop(): void;
+    /** Staged init — runs on first connect AND on reconnect AND on notify_klippy_ready.
+     *  Guarded so overlapping triggers (reconnect + klippy_ready) can't interleave two seeds. */
+    private bootstrap;
+    private onUpdate;
+    private handleGcodeResponse;
+    private setLive;
+}
+
+interface GuardResult {
+    ok: boolean;
+    reason?: string;
+}
+type WriteGuard = (action: string) => GuardResult;
+declare class WriteRefused extends Error {
+    readonly action: string;
+    constructor(action: string, reason: string);
+}
+declare class WriteArbiter {
+    /** caller supplies the live-trust check (Klippy ready + connection ready, not printing-locked, …) */
+    private readonly guard;
+    private readonly logger?;
+    readonly safeMode: Observable<boolean>;
+    constructor(
+    /** caller supplies the live-trust check (Klippy ready + connection ready, not printing-locked, …) */
+    guard?: WriteGuard, logger?: Logger | undefined);
+    setSafeMode(on: boolean, reason?: string): void;
+    /** Run a mutation through the gate. Throws WriteRefused if blocked. */
+    run<T>(action: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/** FNV-1a 32-bit hex — deterministic, dependency-free. */
+declare function fnv1a(s: string): string;
+/** Derive a stable `fm-<hash>` machine id from Moonraker. Falls back to `fm-unknown`. */
+declare function deriveMachineId(connector: Connector): Promise<string>;
+
+interface RestorePoint {
+    id: string;
+    /** what was snapshotted, e.g. 'printer.cfg' | 'settings' | 'config-templates' */
+    scope: string;
+    /** why, e.g. 'pre-config-save' | 'pre-plugin-install' | 'pre-migrate' */
+    trigger: string;
+    ts: number;
+    /** monotonic tiebreak so prune is deterministic even when two points share a ts (ms clock) */
+    seq: number;
+    reversible: boolean;
+    data: unknown;
+}
+interface RestoreStore {
+    list(machineId: string): Promise<RestorePoint[]>;
+    save(machineId: string, p: RestorePoint): Promise<void>;
+    remove(machineId: string, id: string): Promise<void>;
+}
+declare function memoryRestoreStore(): RestoreStore;
+declare class RestorePoints {
+    private readonly store;
+    private readonly machineId;
+    private readonly retention;
+    private seq;
+    constructor(store: RestoreStore, machineId: string, retention?: number);
+    snapshot(scope: string, trigger: string, data: unknown, reversible?: boolean): Promise<RestorePoint>;
+    list(): Promise<RestorePoint[]>;
+    get(id: string): Promise<RestorePoint | undefined>;
+    /** Keep only the newest `retention` points per scope. */
+    private prune;
+}
+
+type SurfaceTarget = '3d' | 'screen';
+interface WidgetDefinition {
+    id: string;
+    title: string;
+    icon?: string;
+    description?: string;
+    /** lazy component loader — the host framework (Vue) resolves it (kept as `unknown` here) */
+    component: () => Promise<unknown>;
+    defaultSize?: {
+        w: number;
+        h: number;
+    };
+    /** declared data needs, aggregated across active widgets to subscribe once */
+    subscriptions?: SubscriptionMap;
+    /** which surfaces this widget renders on (default: both) */
+    targets?: SurfaceTarget[];
+}
+declare function registerWidget(def: WidgetDefinition): void;
+declare function getWidget(id: string): WidgetDefinition | undefined;
+declare function getWidgets(target?: SurfaceTarget): WidgetDefinition[];
+/** The union of the given widgets' declared subscriptions (subscribe once). */
+declare function aggregateSubscriptions(ids: string[]): SubscriptionMap;
+/** Test/host helper — clear the registry. */
+declare function _resetRegistry(): void;
+
+interface ThemeTokens {
+    bg: string;
+    surface: string;
+    surface2: string;
+    border: string;
+    text: string;
+    textMuted: string;
+    primary: string;
+    primaryContrast: string;
+    secondary: string;
+    accent: string;
+    success: string;
+    warning: string;
+    danger: string;
+}
+type ThemeName = 'tutankhamun' | 'horus' | 'anubis';
+declare const themes: Record<ThemeName, ThemeTokens>;
+declare const DEFAULT_THEME: ThemeName;
+/** `{ "--fm-bg": "#0E0F12", ... }` for a theme. */
+declare function themeToCssVars(t: ThemeTokens): Record<string, string>;
+/** Apply a theme to an element (default: document root) by setting the `--fm-*` variables. */
+declare function applyTheme(name: ThemeName, el?: {
+    style: {
+        setProperty(p: string, v: string): void;
+    };
+}): void;
+
+interface LocaleMeta {
+    code: string;
+    /** endonym (shown in the language picker) */
+    name: string;
+    rtl: boolean;
+    dir: 'ltr' | 'rtl';
+}
+declare const LOCALES: readonly LocaleMeta[];
+declare const DEFAULT_LOCALE = "en";
+declare const RTL_LOCALES: readonly string[];
+declare function localeMeta(code: string): LocaleMeta | undefined;
+declare function isRtl(code: string): boolean;
+type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+/** CLDR plural category via the platform's Intl.PluralRules (handles ar/ru/pl/… correctly). */
+declare function pluralCategory(locale: string, n: number): PluralCategory;
+
+/** A nested catalog: { app: { name: "FilaMind 3d" }, job: { layers: { one, other } } }. */
+type Catalog = Record<string, unknown>;
+type Params = Record<string, string | number>;
+/**
+ * Translate `key` against `catalog` for `locale`. Plural: if the entry is an object
+ * (`{ one, other, … }`) and `params.count` is a number, the right CLDR form is chosen.
+ * Missing keys return the key itself (so gaps are visible, never blank).
+ */
+declare function translate(catalog: Catalog, key: string, params?: Params, locale?: string): string;
+/** Convenience holder for a (catalog, locale) pair. */
+declare class Translator {
+    catalog: Catalog;
+    locale: string;
+    constructor(catalog: Catalog, locale?: string);
+    t(key: string, params?: Params): string;
+}
+/** Backend strings travel as a message-code contract so the UI translates them. */
+interface BackendMessage {
+    code: string;
+    params?: Params;
+    /** server-side fallback text if the UI lacks the key */
+    message?: string;
+}
+declare function resolveMessage(catalog: Catalog, m: BackendMessage, locale?: string): string;
+
+interface CommandSenderOptions {
+    /** Stable agent name (pinned — a drifting name registers phantom duplicates on reconnect). */
+    client_name: string;
+    version: string;
+    /** Required: Moonraker documents `url` as mandatory for identify; omitting it can make a strict
+     *  host reject the agent identify, silently stranding the bus. */
+    url: string;
+    logger?: Logger;
+    /** Fires whenever readiness flips (connected+identified) — lets a UI gate its send affordances. */
+    onReadyChange?: (ready: boolean) => void;
+}
+declare class CommandSender {
+    private readonly connector;
+    private readonly opts;
+    private identified;
+    private identifying?;
+    private _ready;
+    private retryTimer?;
+    private retryDelayMs;
+    private readonly log;
+    constructor(connector: Connector, opts: CommandSenderOptions);
+    /** true only when the bus is connected AND identified — gate remote-control affordances on this. */
+    get ready(): boolean;
+    /** Open the agent connection and identify once. Call alongside the app's main session start. */
+    start(): Promise<void>;
+    /** Close the agent connection (call on app teardown so the socket doesn't linger). */
+    stop(): void;
+    /** Broadcast a UI-only command to the other FilaMind surfaces. Best-effort: a command issued
+     *  while the bus is down is dropped (logged), never queued/replayed — a stale "navigate" fired
+     *  minutes later would yank a screen unexpectedly. */
+    send(cmd: RemoteCommand): Promise<void>;
+    navigate(view: RemoteView): Promise<void>;
+    message(level: RemoteMessageLevel, text: string): Promise<void>;
+    locate(): Promise<void>;
+    /** Identify as an agent once per connection; single-flight so concurrent sends don't double-identify. */
+    private ensureIdentified;
+    private setIdentified;
+    /** Self-heal a transient identify failure while the socket stays up (Moonraker busy during a
+     *  klippy/print transition can time out identify without dropping the connection). Bounded backoff;
+     *  a genuine reconnect re-drives identify on its own, so we only retry while state is 'ready'. */
+    private scheduleRetry;
+    private clearRetry;
+    /** Recompute readiness (connected + identified) and notify on change. */
+    private refreshReady;
+}
+
+declare const SETTINGS_VERSION = 1;
+interface UserSettings {
+    /** schema version (for migration) */
+    version: number;
+    theme: ThemeName;
+    locale: string;
+    density: 'comfortable' | 'compact';
+    /** Pharaonic motif density (§10.4) */
+    motifDensity: 'off' | 'subtle' | 'full';
+    /** reduce animation/illustration for low-power or accessibility */
+    reducedMotion: boolean;
+}
+declare const DEFAULT_SETTINGS: UserSettings;
+/** Coerce an arbitrary (old / foreign / partial) blob into valid UserSettings — drops unknown keys,
+ *  validates every enum, stamps the current version. Used by hydrate() + import(). */
+declare function migrate(raw: unknown): UserSettings;
+/** App-provided persistence — the Moonraker-DB impl is keyed by machineUUID; tests use memory. */
+interface SettingsPersistence {
+    load(): Promise<Partial<UserSettings>>;
+    save(settings: UserSettings): Promise<void>;
+}
+declare function memoryPersistence(): SettingsPersistence;
+declare function localStoragePersistence(storageKey?: string): SettingsPersistence;
+/** Settings persisted in the printer's Moonraker database, so they roam across every FilaMind
+ *  surface on that printer (3d, screen, …) — the F10 remote-config substrate. */
+declare function moonrakerDbPersistence(connector: Connector): SettingsPersistence;
+/** Roam a (locally-persisted) SettingsStore across surfaces via a shared remote store: pull the
+ *  shared settings whenever the connection goes live (the shared copy wins on connect), and
+ *  write local changes back. Lets one surface (e.g. FilaMind 3d) reconfigure another (the screen). */
+declare function roamSettings(store: SettingsStore, remote: SettingsPersistence, live: Observable<boolean>): void;
+declare class SettingsStore {
+    private readonly persistence;
+    readonly settings: Observable<UserSettings>;
+    constructor(persistence?: SettingsPersistence, initial?: Partial<UserSettings>);
+    get value(): UserSettings;
+    /** Load persisted settings over the defaults (e.g. on app start). */
+    hydrate(): Promise<void>;
+    /** Change one or more settings + persist. */
+    patch(p: Partial<UserSettings>): void;
+    reset(): void;
+    export(): string;
+    import(json: string): void;
+}
+/** Apply theme to the DOM and return the text direction the app should set for the locale. */
+declare function applySettings(s: UserSettings, el?: {
+    style: {
+        setProperty(p: string, v: string): void;
+    };
+}): {
+    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 };