@signal9/era-ui 3.15.0 → 3.17.0

package/dist/apps/notes/editor/bubble-toolbar.svelte

@@ -23,10 +23,16 @@
 
 <!-- md with xxs buttons, matching the app's other bars. It was sm + size="icon"
      — a 22px bar of 14px buttons around 10px glyphs, the smallest combination in
-     the ladder, which is why the formatting controls read as unhittable. -->
+     the ladder, which is why the formatting controls read as unhittable.
+
+     The border is a deliberate exception to "shadow, not border" (design rule 7):
+     this panel floats over the DOCUMENT, not over chrome, so on a light theme its
+     elevated fill sits on a page of nearly the same value and the shadow alone
+     leaves no discernible edge. border-divider-faded is the token'd hairline, so
+     it still tracks the surface rather than being a drawn-on line. -->
 <Bar
 	size="md"
-	class="w-max gap-(--era-xxs-inset-md) bg-elevated px-(--era-xxs-inset-md) shadow-lg glass-blur"
+	class="w-max gap-(--era-xxs-inset-md) border border-divider-faded bg-elevated px-(--era-xxs-inset-md) shadow-lg glass-blur"
 >
 	{#each items as item (item.mark)}
 		{@const Icon = item.icon}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from './ui/index.js';
 export * as OS from './os/index.js';
 export * as AI from './ai/index.js';
-export type { Point, Size, Rect, Insets, Frame, Workspace, WindowState, SnapZone, AppWindow, AppDefinition, AppComponent, AppProps } from './os/index.js';
+export type { Point, Size, Rect, Insets, Frame, Workspace, WindowState, JsonValue, WindowSnapshot, WorkspaceSnapshot, SnapZone, AppWindow, AppDefinition, AppComponent, AppProps } from './os/index.js';
 export { cn, tv, hotkeys, keys, parseKeybinding, matchKeyBindingPress, createKeybindingsHandler, formatKeybinding, isApplePlatform, modKey, type KeyBindingMap, type KeyBindingPress, type KeyBindingOptions, type PartProps, type VariantProps } from './utils/index.js';

package/dist/os/index.d.ts

@@ -1,4 +1,6 @@
-export { WindowManager, getWindowManager, setWindowManagerContext, type Point, type Size, type Rect, type Insets, type Frame, type AppDefinition, type AppWindow, type AppComponent, type AppProps, type WindowState, type SnapZone, type Workspace } from './wm.svelte.js';
+export { WindowManager, getWindowManager, setWindowManagerContext, type Point, type Size, type Rect, type Insets, type Frame, type AppDefinition, type AppWindow, type AppComponent, type AppProps, type WindowState, type JsonValue, type WindowSnapshot, type WorkspaceSnapshot, SNAPSHOT_VERSION, readSnapshot } from './wm.svelte.js';
+export { persistWorkspace, loadWorkspace, saveWorkspace, clearWorkspace, WORKSPACE_STORAGE_KEY } from './workspace-storage.svelte.js';
+export { type SnapZone, type Workspace } from './wm.svelte.js';
 export { NotificationService, getNotifications, setNotificationContext, type AppNotification, type NotifyOptions, type NotificationAction, type NotificationTone } from './notifications.svelte.js';
 export { LAYER } from './layers.js';
 export { default as Desktop } from './desktop.svelte';

package/dist/os/index.js

@@ -2,7 +2,9 @@
 // Two stores (window manager + notifications) shared via context, and the
 // components that render them: Desktop host, Window, Taskbar (with its
 // built-in command bar), Toaster, NotificationCenter.
-export { WindowManager, getWindowManager, setWindowManagerContext } from './wm.svelte.js';
+export { WindowManager, getWindowManager, setWindowManagerContext, SNAPSHOT_VERSION, readSnapshot } from './wm.svelte.js';
+export { persistWorkspace, loadWorkspace, saveWorkspace, clearWorkspace, WORKSPACE_STORAGE_KEY } from './workspace-storage.svelte.js';
+export {} from './wm.svelte.js';
 export { NotificationService, getNotifications, setNotificationContext } from './notifications.svelte.js';
 export { LAYER } from './layers.js';
 export { default as Desktop } from './desktop.svelte';

package/dist/os/wm.svelte.d.ts

@@ -27,6 +27,87 @@ export interface Frame {
     pos: Point;
     size: Size | null;
 }
+/**
+ * Anything that survives `JSON.parse(JSON.stringify(x))` unchanged.
+ *
+ * This is the whole serialization contract, enforced by the compiler instead of
+ * by a runtime schema. A `Date`, a `Map`, a function, `undefined` inside an
+ * array — none of them type-check here, so a snapshot that compiles is a
+ * snapshot that round-trips. It costs nothing at runtime and adds no dependency,
+ * which matters for a UI library: a schema package would land in every
+ * consumer's bundle to validate data era itself produced.
+ *
+ * The untrusted direction still needs real checking — see `readSnapshot`, which
+ * is where JSON from a file or localStorage is actually interrogated.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+/**
+ * Bumped whenever a snapshot's shape changes in a way older data cannot satisfy.
+ * `readSnapshot` refuses anything it does not recognise rather than guessing —
+ * a half-understood layout is worse than a fresh one.
+ */
+export declare const SNAPSHOT_VERSION = 1;
+/**
+ * One window, reduced to what a reload cannot reconstruct.
+ *
+ * Deliberately NOT a partial AppWindow. A live window holds a `component` and an
+ * `icon`, which are functions; those come from the app registry and are looked
+ * up again on restore by `appId`. Storing an id instead of a reference is also
+ * what lets a snapshot outlive a refactor of the app itself.
+ */
+export interface WindowSnapshot {
+    /** The registered app this window rehydrates from. */
+    appId: string;
+    /** The workspace it belongs to. */
+    workspaceId: string;
+    /** Placement when `state` is 'normal'. */
+    frame: Frame;
+    state: WindowState;
+    /** Where to land on un-maximize / un-snap; null if it was never moved. */
+    restore: Frame | null;
+    /** Stacking order within its workspace. */
+    z: number;
+    /** Only when the window was retitled away from its app's default. */
+    title?: string;
+    /**
+     * App-specific state — the note being edited, a scroll offset, a filter.
+     *
+     * The escape hatch every windowing system needs: era cannot know what an app
+     * considers worth keeping, so it carries the value verbatim and hands it back
+     * on restore. Typed JsonValue rather than `unknown`, so an app cannot stash
+     * something that silently fails to survive the round trip.
+     */
+    props?: JsonValue;
+}
+/** A whole desktop, exportable as one JSON document. */
+export interface WorkspaceSnapshot {
+    version: number;
+    /**
+     * Epoch milliseconds. A number, not an ISO string: timezone-free, sortable,
+     * and it cannot drift on a round trip through a formatter. Never used for
+     * logic — it exists so a human can tell two exports apart.
+     */
+    savedAt: number;
+    activeWorkspaceId: string;
+    workspaces: Workspace[];
+    windows: WindowSnapshot[];
+}
+/**
+ * Parse untrusted JSON into a snapshot, or return null.
+ *
+ * The counterpart to JsonValue. The compiler guarantees what era WRITES; this
+ * guards what it reads, which may be a hand-edited file, a stale localStorage
+ * entry, or a snapshot from a future version. It checks shape rather than
+ * trusting `as`, and refuses an unknown `version` outright — silently importing
+ * a layout you only half understand is worse than declining it.
+ *
+ * Individual windows are filtered, not fatal: one malformed entry should not
+ * cost the user the rest of the layout. applySnapshot() drops unknown appIds the
+ * same way, for the same reason.
+ */
+export declare function readSnapshot(json: string): WorkspaceSnapshot | null;
 export type WindowState = 'normal' | 'minimized' | 'maximized';
 /** Snap targets: the four edges (halves) or four corners (quadrants). */
 export type SnapZone = 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -57,6 +138,12 @@ export interface AppDefinition {
     /** Extra classes for the window body (Pane.Content) — e.g. `p-(--era-gap)`
      *  for a body of controls, or `p-0` for a full-bleed app. */
     bodyClass?: string;
+    /**
+     * Starting app state for every window spawned from this app — the value a
+     * window carries in its snapshot's `props`. An app reads it back off
+     * `window.props` (AppProps hands the whole record over).
+     */
+    props?: JsonValue;
     /** Extra title-bar controls, rendered immediately LEFT of the close button.
      *  For per-window affordances that belong on the chrome rather than in the
      *  body — a help/usage launcher, a pin, a view toggle. Assignable on the
@@ -86,6 +173,8 @@ export interface AppWindow {
     minimizable: boolean;
     bodyClass?: string;
     actions?: Snippet;
+    /** App-specific state, carried verbatim through a snapshot. */
+    props?: JsonValue;
 }
 /** A named virtual desktop. Every window belongs to exactly one; only the
  *  active workspace's windows are shown, the rest keep their geometry and
@@ -158,6 +247,26 @@ export declare class WindowManager {
      *  The Desktop calls this whenever the work area changes; chrome itself
      *  (the taskbar) never resizes with the viewport. */
     relayout(): void;
+    /**
+     * The whole desktop as one JSON-safe document.
+     *
+     * Reads every workspace and every window across ALL of them, not just the
+     * active one — a snapshot that only captured what was on screen would quietly
+     * drop the other workspaces the moment it was restored.
+     */
+    snapshot(): WorkspaceSnapshot;
+    /**
+     * Replace the desktop with a snapshot.
+     *
+     * Named applySnapshot, not restore: `restore(id)` already means "un-maximize
+     * this window", and one verb cannot mean both.
+     *
+     * Windows whose `appId` is no longer registered are SKIPPED rather than
+     * failing the whole restore: an app can be removed between export and import,
+     * and losing one window beats losing the layout. Same for a window pointing at
+     * a workspace the snapshot does not contain.
+     */
+    applySnapshot(snapshot: WorkspaceSnapshot): void;
     /** Half / quadrant tiling against the work area. */
     snap(id: string, zone: SnapZone): void;
     /** Create a workspace (optionally switching to it) and return its id. */

package/dist/os/wm.svelte.js

@@ -1,4 +1,80 @@
 import { getContext, setContext } from 'svelte';
+/**
+ * Bumped whenever a snapshot's shape changes in a way older data cannot satisfy.
+ * `readSnapshot` refuses anything it does not recognise rather than guessing —
+ * a half-understood layout is worse than a fresh one.
+ */
+export const SNAPSHOT_VERSION = 1;
+/**
+ * Parse untrusted JSON into a snapshot, or return null.
+ *
+ * The counterpart to JsonValue. The compiler guarantees what era WRITES; this
+ * guards what it reads, which may be a hand-edited file, a stale localStorage
+ * entry, or a snapshot from a future version. It checks shape rather than
+ * trusting `as`, and refuses an unknown `version` outright — silently importing
+ * a layout you only half understand is worse than declining it.
+ *
+ * Individual windows are filtered, not fatal: one malformed entry should not
+ * cost the user the rest of the layout. applySnapshot() drops unknown appIds the
+ * same way, for the same reason.
+ */
+export function readSnapshot(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const o = raw;
+    if (o.version !== SNAPSHOT_VERSION)
+        return null;
+    if (typeof o.activeWorkspaceId !== 'string')
+        return null;
+    if (!Array.isArray(o.workspaces) || !Array.isArray(o.windows))
+        return null;
+    const isPoint = (v) => typeof v === 'object' &&
+        v !== null &&
+        typeof v.x === 'number' &&
+        typeof v.y === 'number';
+    const isSize = (v) => typeof v === 'object' &&
+        v !== null &&
+        typeof v.width === 'number' &&
+        typeof v.height === 'number';
+    const isFrame = (v) => {
+        if (typeof v !== 'object' || v === null)
+            return false;
+        const f = v;
+        return isPoint(f.pos) && (f.size === null || isSize(f.size));
+    };
+    const workspaces = o.workspaces.filter((w) => typeof w === 'object' &&
+        w !== null &&
+        typeof w.id === 'string' &&
+        typeof w.name === 'string');
+    if (workspaces.length === 0)
+        return null;
+    const states = ['normal', 'minimized', 'maximized'];
+    const windows = o.windows.filter((w) => {
+        if (typeof w !== 'object' || w === null)
+            return false;
+        const x = w;
+        return (typeof x.appId === 'string' &&
+            typeof x.workspaceId === 'string' &&
+            typeof x.z === 'number' &&
+            states.includes(x.state) &&
+            isFrame(x.frame) &&
+            (x.restore === null || isFrame(x.restore)));
+    });
+    return {
+        version: SNAPSHOT_VERSION,
+        savedAt: typeof o.savedAt === 'number' ? o.savedAt : 0,
+        activeWorkspaceId: o.activeWorkspaceId,
+        workspaces,
+        windows
+    };
+}
 const DEFAULT_SIZE = { width: 480, height: 320 };
 /**
  * The source of truth for the desktop: which workspaces and windows exist,
@@ -106,7 +182,8 @@ export class WindowManager {
             resizable: overrides?.resizable ?? app.resizable ?? true,
             minimizable: app.minimizable ?? true,
             bodyClass: app.bodyClass,
-            actions: app.actions
+            actions: app.actions,
+            props: app.props
         };
         this.windows.push(win);
         return id;
@@ -205,6 +282,94 @@ export class WindowManager {
             }
         }
     }
+    /* -------------------------------------------------------------- */
+    /* Snapshot / restore                                             */
+    /* -------------------------------------------------------------- */
+    /**
+     * The whole desktop as one JSON-safe document.
+     *
+     * Reads every workspace and every window across ALL of them, not just the
+     * active one — a snapshot that only captured what was on screen would quietly
+     * drop the other workspaces the moment it was restored.
+     */
+    snapshot() {
+        return {
+            version: SNAPSHOT_VERSION,
+            savedAt: Date.now(),
+            activeWorkspaceId: this.activeWorkspaceId,
+            workspaces: this.workspaces.map((w) => ({ ...w })),
+            windows: this.windows.map((w) => {
+                const app = this.apps[w.appId];
+                const snap = {
+                    appId: w.appId,
+                    workspaceId: w.workspaceId,
+                    frame: { pos: { ...w.pos }, size: w.size ? { ...w.size } : null },
+                    state: w.state,
+                    restore: w.restore
+                        ? { pos: { ...w.restore.pos }, size: w.restore.size ? { ...w.restore.size } : null }
+                        : null,
+                    z: w.z
+                };
+                // Only record a title the user changed. Storing the app's own default
+                // would pin it, so renaming the app in code would not reach any
+                // window restored from an older snapshot.
+                if (app && w.title !== app.title)
+                    snap.title = w.title;
+                if (w.props !== undefined)
+                    snap.props = w.props;
+                return snap;
+            })
+        };
+    }
+    /**
+     * Replace the desktop with a snapshot.
+     *
+     * Named applySnapshot, not restore: `restore(id)` already means "un-maximize
+     * this window", and one verb cannot mean both.
+     *
+     * Windows whose `appId` is no longer registered are SKIPPED rather than
+     * failing the whole restore: an app can be removed between export and import,
+     * and losing one window beats losing the layout. Same for a window pointing at
+     * a workspace the snapshot does not contain.
+     */
+    applySnapshot(snapshot) {
+        this.windows = [];
+        this.workspaces = snapshot.workspaces.map((w) => ({ ...w }));
+        if (this.workspaces.length === 0)
+            this.workspaces = [{ id: 'w1', name: '1' }];
+        // A plain array, not a Set: there are a handful of workspaces, and a Set in
+        // a .svelte.ts file is a reactivity trap the lint rightly flags.
+        const known = this.workspaces.map((w) => w.id);
+        this.activeWorkspaceId = known.includes(snapshot.activeWorkspaceId)
+            ? snapshot.activeWorkspaceId
+            : this.workspaces[0].id;
+        let z = 0;
+        for (const s of snapshot.windows) {
+            const app = this.apps[s.appId];
+            if (!app || !known.includes(s.workspaceId))
+                continue;
+            this.windows.push({
+                id: `${s.appId}#${++this.#seq}`,
+                appId: s.appId,
+                workspaceId: s.workspaceId,
+                title: s.title ?? app.title,
+                icon: app.icon,
+                pos: { ...s.frame.pos },
+                size: s.frame.size ? { ...s.frame.size } : null,
+                z: (z = Math.max(z, s.z)),
+                state: s.state,
+                restore: s.restore,
+                component: app.component,
+                resizable: app.resizable ?? true,
+                minimizable: app.minimizable ?? true,
+                bodyClass: app.bodyClass,
+                actions: app.actions,
+                props: s.props ?? app.props
+            });
+        }
+        this.#z = z;
+        this.focusedId = this.activeWindows.at(-1)?.id ?? null;
+    }
     /** Half / quadrant tiling against the work area. */
     snap(id, zone) {
         const w = this.#find(id);

package/dist/os/workspace-storage.svelte.d.ts

@@ -0,0 +1,25 @@
+import { type WindowManager } from './wm.svelte.js';
+export declare const WORKSPACE_STORAGE_KEY = "era-ui:workspace";
+/** Read a saved snapshot and apply it. Returns whether anything was restored. */
+export declare function loadWorkspace(wm: WindowManager, key?: string): boolean;
+/** Write the current desktop. Returns false when storage rejected it. */
+export declare function saveWorkspace(wm: WindowManager, key?: string): boolean;
+export declare function clearWorkspace(key?: string): void;
+/**
+ * Restore on setup, then save whenever the desktop changes.
+ *
+ * Call from a component's script (it registers an `$effect`, so it needs a
+ * component context). The load is synchronous and happens immediately, before
+ * the first paint.
+ *
+ * Writes are debounced: dragging a window mutates `pos` on every pointer move,
+ * and serialising the whole desktop per frame would be pointless work. The
+ * trailing write always lands because the effect's teardown flushes a pending
+ * timer.
+ */
+export declare function persistWorkspace(wm: WindowManager, options?: {
+    key?: string;
+    debounce?: number;
+}): {
+    restored: boolean;
+};

package/dist/os/workspace-storage.svelte.js

@@ -0,0 +1,118 @@
+/**
+ * Persisting the desktop across reloads.
+ *
+ * WHY localStorage, and not something newer
+ * -----------------------------------------
+ * The payload is a few kB of JSON that must be read BEFORE the first paint. That
+ * one requirement rules out every modern alternative, because they are all async:
+ *
+ *   IndexedDB       async. Large, structured, transactional — none of which this
+ *                   needs, and the desktop would paint empty and then pop windows
+ *                   in a frame later.
+ *   OPFS            async, and built for large or binary files with real
+ *                   read/write handles. A 2kB JSON blob is not that.
+ *   Storage Buckets async, and still Chromium-only. Its actual feature is
+ *                   per-bucket eviction and quota policy, which matters when you
+ *                   have several independent stores to prioritise between. One
+ *                   layout snapshot is not that either.
+ *
+ * localStorage is synchronous, which here is the feature rather than the
+ * compromise: the snapshot is read and applied during setup, so the desktop's
+ * first paint is already the restored layout — no flash of an empty workspace.
+ *
+ * The genuinely modern piece worth adopting IS used: navigator.storage.persist()
+ * asks the browser to exempt this origin from eviction under storage pressure.
+ * Without it localStorage is "best effort" and can be cleared when the device is
+ * low on space. It is requested once, non-blocking, and its refusal is harmless.
+ */
+import { untrack } from 'svelte';
+import { readSnapshot } from './wm.svelte.js';
+export const WORKSPACE_STORAGE_KEY = 'era-ui:workspace';
+/** Read a saved snapshot and apply it. Returns whether anything was restored. */
+export function loadWorkspace(wm, key = WORKSPACE_STORAGE_KEY) {
+    if (typeof localStorage === 'undefined')
+        return false;
+    let raw = null;
+    try {
+        raw = localStorage.getItem(key);
+    }
+    catch {
+        return false; // private mode, or storage disabled
+    }
+    if (!raw)
+        return false;
+    // readSnapshot is the gate: this string is untrusted (hand-edited, stale, or
+    // written by a newer version), so it is validated rather than cast.
+    const snapshot = readSnapshot(raw);
+    if (!snapshot)
+        return false;
+    wm.applySnapshot(snapshot);
+    return true;
+}
+/** Write the current desktop. Returns false when storage rejected it. */
+export function saveWorkspace(wm, key = WORKSPACE_STORAGE_KEY) {
+    if (typeof localStorage === 'undefined')
+        return false;
+    try {
+        localStorage.setItem(key, JSON.stringify(wm.snapshot()));
+        return true;
+    }
+    catch {
+        // Quota exceeded or private mode. A layout is convenience state, so this
+        // stays silent — unlike the Notes store, where a failed save loses writing
+        // and the user has to be told.
+        return false;
+    }
+}
+export function clearWorkspace(key = WORKSPACE_STORAGE_KEY) {
+    try {
+        localStorage?.removeItem(key);
+    }
+    catch {
+        /* nothing to do — the goal was for it to be gone */
+    }
+}
+/**
+ * Restore on setup, then save whenever the desktop changes.
+ *
+ * Call from a component's script (it registers an `$effect`, so it needs a
+ * component context). The load is synchronous and happens immediately, before
+ * the first paint.
+ *
+ * Writes are debounced: dragging a window mutates `pos` on every pointer move,
+ * and serialising the whole desktop per frame would be pointless work. The
+ * trailing write always lands because the effect's teardown flushes a pending
+ * timer.
+ */
+export function persistWorkspace(wm, options = {}) {
+    const key = options.key ?? WORKSPACE_STORAGE_KEY;
+    const wait = options.debounce ?? 400;
+    const restored = loadWorkspace(wm, key);
+    // Ask for durable storage. Fire-and-forget: a refusal (or an engine without
+    // the API) just leaves the default best-effort behaviour.
+    void navigator?.storage?.persist?.().catch(() => { });
+    $effect(() => {
+        // Touch what a snapshot is made of, so the effect re-runs when any of it
+        // changes. Reading these is the subscription.
+        wm.windows.forEach((w) => {
+            void w.pos.x;
+            void w.pos.y;
+            void w.size?.width;
+            void w.size?.height;
+            void w.state;
+            void w.z;
+            void w.title;
+            void w.workspaceId;
+            void w.props;
+        });
+        void wm.workspaces.length;
+        void wm.activeWorkspaceId;
+        const timer = setTimeout(() => {
+            // untrack: snapshot() reads the same state this effect depends on, and
+            // re-reading it inside would re-subscribe on every write.
+            untrack(() => saveWorkspace(wm, key));
+        }, wait);
+        return () => clearTimeout(timer);
+    });
+    return { restored };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@signal9/era-ui",
-	"version": "3.15.0",
+	"version": "3.17.0",
 	"scripts": {
 		"dev": "vite dev --host",
 		"build": "vite build && npm run prepack",