@signal9/era-ui 3.15.0 → 3.16.0

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,4 @@
-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, 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,7 @@
 // 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 { 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/package.json

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