@signal9/era-ui 1.24.0 → 1.25.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './ui/index.js';
 export * as OS from './os/index.js';
+export type { Point, Size, Rect, Insets, Frame, Workspace, WindowState, SnapZone, AppWindow, AppDefinition, AppComponent, AppProps } from './os/index.js';
 export { cn, tv, type PartProps, type VariantProps } from './utils/index.js';

package/dist/os/desktop.svelte

@@ -51,7 +51,10 @@
 	     over the chrome / menus / toasts / launcher that render below (outside it)
 	     at the document root. This is the whole layer contract in one line. -->
 	<div class="absolute inset-0 isolate">
-		{#each wm.windows as win (win.id)}
+		<!-- Only the active workspace paints; other workspaces' windows keep
+		     their state untouched and simply aren't in the tree. Keyed by id, so
+		     switching back remounts them exactly where they were. -->
+		{#each wm.activeWindows as win (win.id)}
 			<Window window={win} />
 		{/each}
 	</div>

package/dist/os/index.d.ts

@@ -1,4 +1,4 @@
-export { WindowManager, getWindowManager, setWindowManagerContext, type AppDefinition, type AppWindow, type AppComponent, type AppProps, type WindowState, type SnapZone } 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 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/taskbar.svelte

@@ -107,6 +107,24 @@
 		<LayoutGrid class="size-(--era-h-xs)" />
 	</Button>
 
+	<!-- Workspace switcher — appears only once there's something to switch
+	     between; a single-workspace desktop stays free of dead chrome. -->
+	{#if wm.workspaces.length > 1}
+		<div class="flex items-center gap-(--era-gap)">
+			{#each wm.workspaces as ws (ws.id)}
+				<Button
+					size="default"
+					active={wm.activeWorkspaceId === ws.id}
+					aria-label="Switch to workspace {ws.name}"
+					onclick={() => wm.switchWorkspace(ws.id)}
+				>
+					{ws.name}
+				</Button>
+			{/each}
+		</div>
+		<div class="h-1/2 w-px shrink-0 bg-divider-faded"></div>
+	{/if}
+
 	{#if pinned.length}
 		<div class="flex items-center gap-(--era-gap)">
 			{#each pinned as p (p.appId)}
@@ -118,10 +136,11 @@
 		<div class="h-1/2 w-px shrink-0 bg-divider-faded"></div>
 	{/if}
 
-	<!-- Running windows: real Buttons — `active` latches the focused window's
-	     pressed face (surface-aware for free), click focuses / minimises. -->
+	<!-- Running windows on the active workspace: real Buttons — `active` latches
+	     the focused window's pressed face (surface-aware for free), click
+	     focuses / minimises. -->
 	<div class="scrollbar-none flex min-w-0 flex-1 items-center gap-(--era-gap) overflow-x-auto">
-		{#each wm.windows as win (win.id)}
+		{#each wm.activeWindows as win (win.id)}
 			<Button
 				active={wm.focusedId === win.id && win.state !== 'minimized'}
 				onclick={() => wm.toggleMinimize(win.id)}

package/dist/os/window.svelte

@@ -13,27 +13,27 @@
 	const wm = getWindowManager();
 	const focused = $derived(wm.focusedId === win.id);
 
-	// Shell containment: a window can never become unrecoverable. The bar may not
-	// leave the TOP of the shell at all (y ≥ top inset), and on every other side
-	// at least wm.dragKeep px of the window must stay inside the work area (which
-	// excludes the taskbar — a strip hidden behind chrome would be just as lost).
-	// Clamped mid-drag the way neodrag's own bounds plugin does it: offset +
-	// proposed delta → clamp → re-propose the delta, so the cursor simply stops
-	// pulling at the fence instead of rubber-banding on release. Only a `drag`
-	// hook (width read live), and a STABLE plugin list — an inline array would
-	// change identity every render and make neodrag reconcile mid-session.
+	// Shell containment: a window can never become unrecoverable. The bar may
+	// not leave the TOP of the work area at all (y ≥ workArea.y), and on every
+	// other side at least wm.dragKeep px of the window must stay inside the
+	// work area (which excludes chrome — a strip hidden behind the taskbar
+	// would be just as lost). Clamped mid-drag the way neodrag's own bounds
+	// plugin does it: offset + proposed delta → clamp → re-propose the delta,
+	// so the cursor simply stops pulling at the fence instead of
+	// rubber-banding on release. Only a `drag` hook (width read live), and a
+	// STABLE plugin list — an inline array would change identity every render
+	// and make neodrag reconcile mid-session.
 	const shellClamp: Plugin = {
 		name: 'era:shell-clamp',
 		drag(ctx) {
-			const { width: W, height: H } = wm.bounds;
-			if (!W || !H) return;
-			const { top, right, bottom, left } = wm.insets;
+			const area = wm.workArea;
+			if (!area.width || !area.height) return;
 			const keep = wm.dragKeep;
 			const width = (ctx.rootNode as HTMLElement).offsetWidth;
 			const px = ctx.offset.x + (ctx.proposed.x ?? 0);
 			const py = ctx.offset.y + (ctx.proposed.y ?? 0);
-			const cx = Math.min(Math.max(px, left + keep - width), W - right - keep);
-			const cy = Math.min(Math.max(py, top), H - bottom - keep);
+			const cx = Math.min(Math.max(px, area.x + keep - width), area.x + area.width - keep);
+			const cy = Math.min(Math.max(py, area.y), area.y + area.height - keep);
 			ctx.propose(cx - ctx.offset.x, cy - ctx.offset.y);
 		}
 	};

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

@@ -1,5 +1,32 @@
 import { type Component } from 'svelte';
 import type { IconProps } from '@lucide/svelte';
+/** A point on the desktop plane. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A box's dimensions. */
+export interface Size {
+    width: number;
+    height: number;
+}
+/** A positioned box — a point plus its dimensions. */
+export interface Rect extends Point, Size {
+}
+/** Space reserved along each desktop edge (by chrome like the taskbar). */
+export interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** A window's placement: where it sits, and its explicit size once one has
+ *  been set (`null` = auto — the window is content-sized until the user or a
+ *  preset gives it real dimensions, so we never invent numbers). */
+export interface Frame {
+    pos: Point;
+    size: Size | 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';
@@ -18,10 +45,7 @@ export interface AppDefinition {
     icon?: Component<IconProps> | null;
     /** Body renderer. Omit for a chromeless/placeholder window. */
     component?: AppComponent;
-    defaultSize?: {
-        width: number;
-        height: number;
-    };
+    defaultSize?: Size;
     /** Only one live instance; opening again focuses the existing one. */
     singleton?: boolean;
     /** Show a resize grip (default true). */
@@ -34,84 +58,99 @@ export interface AppDefinition {
 export interface AppWindow {
     id: string;
     appId: string;
+    /** The workspace this window lives on. */
+    workspaceId: string;
     title: string;
     icon?: Component<IconProps> | null;
-    /** neodrag offset — bound straight to Pane.Root's `position`. */
-    pos: {
-        x: number;
-        y: number;
-    };
-    /** Explicit size once set — bound to Pane.Root's `size`. */
-    size: {
-        width: number;
-        height: number;
-    } | null;
+    /** Placement when 'normal' — bound straight to Pane.Root's `position`. */
+    pos: Point;
+    /** Explicit size once set — bound to Pane.Root's `size` (null = auto). */
+    size: Size | null;
     /** Stacking order within the desktop (higher = nearer the front). */
     z: number;
     state: WindowState;
-    /** Geometry snapshot to restore to after un-maximize / un-snap. */
-    restore: {
-        pos: {
-            x: number;
-            y: number;
-        };
-        size: {
-            width: number;
-            height: number;
-        } | null;
-    } | null;
+    /** Frame snapshot to restore to after un-maximize / un-snap. */
+    restore: Frame | null;
     component?: AppComponent;
     resizable: boolean;
     bodyClass?: string;
 }
+/** A named virtual desktop. Every window belongs to exactly one; only the
+ *  active workspace's windows are shown, the rest keep their geometry and
+ *  stacking untouched until switched back to. */
+export interface Workspace {
+    id: string;
+    name: string;
+}
 /**
- * The source of truth for the desktop: which windows exist, their geometry, and
- * their stacking / focus order. Everything visual (Desktop, Window, Taskbar,
- * Alt-Tab, …) is a pure view of this. Runes-based, shared via context.
+ * The source of truth for the desktop: which workspaces and windows exist,
+ * their geometry, and their stacking / focus order. Everything visual
+ * (Desktop, Window, Taskbar, Launcher, …) is a pure view of this. Runes-based,
+ * shared via context.
  */
 export declare class WindowManager {
     #private;
-    /** Every live window. Order is spawn order; paint order is by `z`. */
+    /** Every live window, across all workspaces. Order is spawn order; paint
+     *  order is by `z`; visibility is by workspace. */
     windows: AppWindow[];
     /** Registered app templates, keyed by id. */
     apps: Record<string, AppDefinition>;
+    /** The virtual desktops. Always at least one. */
+    workspaces: Workspace[];
+    /** Which workspace is on screen. */
+    activeWorkspaceId: string;
     /** Desktop viewport size — set by the Desktop host; drives maximize / snap. */
-    bounds: {
-        width: number;
-        height: number;
-    };
-    /** Edges reserved by chrome (the Taskbar registers its height as `bottom`).
-     *  The work area = bounds − insets; maximize and drag containment honour it. */
-    insets: {
-        top: number;
-        right: number;
-        bottom: number;
-        left: number;
-    };
-    /** Drag containment: a window's bar may never leave the top of the shell, and
-     *  at least this many px of it must stay reachable on every other side. */
+    bounds: Size;
+    /** Edges reserved by chrome (the Taskbar registers its footprint here).
+     *  The work area = bounds − insets; maximize, snap and drag containment
+     *  honour it. */
+    insets: Insets;
+    /** Drag containment: a window's bar may never leave the top of the work
+     *  area, and at least this many px of it must stay reachable on every
+     *  other side. */
     dragKeep: number;
-    /** The focused window = the top-most non-minimized one. */
+    /** The usable desktop: bounds minus reserved chrome. Everything that places
+     *  a window against "the screen" (maximize, snap, containment) uses this,
+     *  never raw bounds — a strip hidden behind chrome is as lost as one
+     *  off-screen. */
+    workArea: Rect;
+    /** The active workspace's windows — what the Desktop paints and the
+     *  Taskbar lists. */
+    activeWindows: AppWindow[];
+    /** The focused window = the top-most non-minimized one on the active
+     *  workspace. */
     focusedId: string | null;
     register(app: AppDefinition): void;
     registerMany(apps: AppDefinition[]): void;
-    /** Spawn a window for an app (or focus the existing one if it's a singleton). */
-    open(appId: string, overrides?: Partial<Pick<AppWindow, 'title' | 'pos' | 'size' | 'resizable'>>): string | null;
+    /** Spawn a window for an app (or focus the existing one if it's a
+     *  singleton — from any workspace; it is brought to the active one). */
+    open(appId: string, overrides?: Partial<Pick<AppWindow, 'title' | 'pos' | 'size' | 'resizable' | 'workspaceId'>>): string | null;
     close(id: string): void;
     /** Bring a window to the front (and un-minimize it if needed). */
     focus(id: string): void;
     minimize(id: string): void;
     /** Taskbar behaviour: focus if not focused, else minimize; restore if minimized. */
     toggleMinimize(id: string): void;
-    /** Fill the WORK AREA — bounds minus chrome insets, so a maximized window
-     *  doesn't hide under the taskbar (middle-click on the window's ×). Keeps the
-     *  first pre-maximize/pre-snap snapshot so restore returns to the true origin. */
+    /** Fill the work area (middle-click on the window's ×). Keeps the first
+     *  pre-maximize/pre-snap frame so restore returns to the true origin. */
     maximize(id: string): void;
     toggleMaximize(id: string): void;
-    /** Un-maximize / un-snap back to the pre-change geometry (or just un-minimize). */
+    /** Un-maximize / un-snap back to the pre-change frame (or just un-minimize). */
     restore(id: string): void;
-    /** Half / quadrant tiling against the desktop bounds. */
+    /** Half / quadrant tiling against the work area. */
     snap(id: string, zone: SnapZone): void;
+    /** Create a workspace (optionally switching to it) and return its id. */
+    addWorkspace(name?: string, { activate }?: {
+        activate?: boolean | undefined;
+    }): string;
+    /** Show a workspace. Windows on others keep their geometry and stacking. */
+    switchWorkspace(id: string): void;
+    /** Remove a workspace. Its windows migrate to the fallback (the active
+     *  workspace, or the first remaining one) — closing a desktop never
+     *  silently closes the work on it. The last workspace can't be removed. */
+    removeWorkspace(id: string): void;
+    /** Send a window to another workspace (it stays where it was on screen). */
+    moveToWorkspace(windowId: string, workspaceId: string): void;
 }
 export declare function setWindowManagerContext(wm: WindowManager): WindowManager;
 export declare function getWindowManager(): WindowManager;

package/dist/os/wm.svelte.js

@@ -1,29 +1,55 @@
 import { getContext, setContext } from 'svelte';
 const DEFAULT_SIZE = { width: 480, height: 320 };
 /**
- * The source of truth for the desktop: which windows exist, their geometry, and
- * their stacking / focus order. Everything visual (Desktop, Window, Taskbar,
- * Alt-Tab, …) is a pure view of this. Runes-based, shared via context.
+ * The source of truth for the desktop: which workspaces and windows exist,
+ * their geometry, and their stacking / focus order. Everything visual
+ * (Desktop, Window, Taskbar, Launcher, …) is a pure view of this. Runes-based,
+ * shared via context.
  */
 export class WindowManager {
-    /** Every live window. Order is spawn order; paint order is by `z`. */
+    /** Every live window, across all workspaces. Order is spawn order; paint
+     *  order is by `z`; visibility is by workspace. */
     windows = $state([]);
     /** Registered app templates, keyed by id. */
     apps = $state.raw({});
+    /** The virtual desktops. Always at least one. */
+    workspaces = $state([{ id: 'main', name: 'Main' }]);
+    /** Which workspace is on screen. */
+    activeWorkspaceId = $state('main');
     /** Desktop viewport size — set by the Desktop host; drives maximize / snap. */
     bounds = $state({ width: 0, height: 0 });
-    /** Edges reserved by chrome (the Taskbar registers its height as `bottom`).
-     *  The work area = bounds − insets; maximize and drag containment honour it. */
+    /** Edges reserved by chrome (the Taskbar registers its footprint here).
+     *  The work area = bounds − insets; maximize, snap and drag containment
+     *  honour it. */
     insets = $state({ top: 0, right: 0, bottom: 0, left: 0 });
-    /** Drag containment: a window's bar may never leave the top of the shell, and
-     *  at least this many px of it must stay reachable on every other side. */
+    /** Drag containment: a window's bar may never leave the top of the work
+     *  area, and at least this many px of it must stay reachable on every
+     *  other side. */
     dragKeep = 25;
     #z = 0;
     #seq = 0;
-    /** The focused window = the top-most non-minimized one. */
+    #wsSeq = 0;
+    /** The usable desktop: bounds minus reserved chrome. Everything that places
+     *  a window against "the screen" (maximize, snap, containment) uses this,
+     *  never raw bounds — a strip hidden behind chrome is as lost as one
+     *  off-screen. */
+    workArea = $derived.by(() => {
+        const { top, right, bottom, left } = this.insets;
+        return {
+            x: left,
+            y: top,
+            width: Math.max(0, this.bounds.width - left - right),
+            height: Math.max(0, this.bounds.height - top - bottom)
+        };
+    });
+    /** The active workspace's windows — what the Desktop paints and the
+     *  Taskbar lists. */
+    activeWindows = $derived.by(() => this.windows.filter((w) => w.workspaceId === this.activeWorkspaceId));
+    /** The focused window = the top-most non-minimized one on the active
+     *  workspace. */
     focusedId = $derived.by(() => {
         let top = null;
-        for (const w of this.windows) {
+        for (const w of this.activeWindows) {
             if (w.state === 'minimized')
                 continue;
             if (!top || w.z > top.z)
@@ -31,6 +57,7 @@ export class WindowManager {
         }
         return top?.id ?? null;
     });
+    /* ---------------- apps ---------------- */
     register(app) {
         this.apps = { ...this.apps, [app.id]: app };
     }
@@ -40,7 +67,9 @@ export class WindowManager {
     #find(id) {
         return this.windows.find((w) => w.id === id);
     }
-    /** Spawn a window for an app (or focus the existing one if it's a singleton). */
+    /* ---------------- windows ---------------- */
+    /** Spawn a window for an app (or focus the existing one if it's a
+     *  singleton — from any workspace; it is brought to the active one). */
     open(appId, overrides) {
         const app = this.apps[appId];
         if (!app)
@@ -48,19 +77,23 @@ export class WindowManager {
         if (app.singleton) {
             const existing = this.windows.find((w) => w.appId === appId);
             if (existing) {
+                existing.workspaceId = overrides?.workspaceId ?? this.activeWorkspaceId;
                 this.restore(existing.id);
                 return existing.id;
             }
         }
         const id = `${appId}#${++this.#seq}`;
-        // Cascade so stacked spawns don't land exactly on top of each other.
+        // Cascade from the work area's origin so stacked spawns don't land
+        // exactly on top of each other (or under top chrome).
         const n = this.windows.length % 8;
+        const { x, y } = this.workArea;
         const win = {
             id,
             appId,
+            workspaceId: overrides?.workspaceId ?? this.activeWorkspaceId,
             title: overrides?.title ?? app.title,
             icon: app.icon,
-            pos: overrides?.pos ?? { x: 48 + n * 28, y: 48 + n * 28 },
+            pos: overrides?.pos ?? { x: x + 48 + n * 28, y: y + 24 + n * 28 },
             size: overrides?.size ?? app.defaultSize ?? { ...DEFAULT_SIZE },
             z: ++this.#z,
             state: 'normal',
@@ -102,21 +135,17 @@ export class WindowManager {
         else
             this.focus(id);
     }
-    /** Fill the WORK AREA — bounds minus chrome insets, so a maximized window
-     *  doesn't hide under the taskbar (middle-click on the window's ×). Keeps the
-     *  first pre-maximize/pre-snap snapshot so restore returns to the true origin. */
+    /** Fill the work area (middle-click on the window's ×). Keeps the first
+     *  pre-maximize/pre-snap frame so restore returns to the true origin. */
     maximize(id) {
         const w = this.#find(id);
         if (!w)
             return;
         if (!w.restore)
             w.restore = { pos: { ...w.pos }, size: w.size ? { ...w.size } : null };
-        const { top, right, bottom, left } = this.insets;
-        w.pos = { x: left, y: top };
-        w.size = {
-            width: this.bounds.width - left - right,
-            height: this.bounds.height - top - bottom
-        };
+        const { x, y, width, height } = this.workArea;
+        w.pos = { x, y };
+        w.size = { width, height };
         w.state = 'maximized';
         this.focus(id);
     }
@@ -129,7 +158,7 @@ export class WindowManager {
         else
             this.maximize(id);
     }
-    /** Un-maximize / un-snap back to the pre-change geometry (or just un-minimize). */
+    /** Un-maximize / un-snap back to the pre-change frame (or just un-minimize). */
     restore(id) {
         const w = this.#find(id);
         if (!w)
@@ -142,33 +171,68 @@ export class WindowManager {
         w.state = 'normal';
         this.focus(id);
     }
-    /** Half / quadrant tiling against the desktop bounds. */
+    /** Half / quadrant tiling against the work area. */
     snap(id, zone) {
         const w = this.#find(id);
         if (!w)
             return;
-        const { width: W, height: H } = this.bounds;
+        const { x, y, width: W, height: H } = this.workArea;
         const halfW = Math.round(W / 2);
         const halfH = Math.round(H / 2);
         const rects = {
-            left: [0, 0, halfW, H],
-            right: [halfW, 0, W - halfW, H],
-            top: [0, 0, W, halfH],
-            bottom: [0, halfH, W, H - halfH],
-            'top-left': [0, 0, halfW, halfH],
-            'top-right': [halfW, 0, W - halfW, halfH],
-            'bottom-left': [0, halfH, halfW, H - halfH],
-            'bottom-right': [halfW, halfH, W - halfW, H - halfH]
+            left: { x, y, width: halfW, height: H },
+            right: { x: x + halfW, y, width: W - halfW, height: H },
+            top: { x, y, width: W, height: halfH },
+            bottom: { x, y: y + halfH, width: W, height: H - halfH },
+            'top-left': { x, y, width: halfW, height: halfH },
+            'top-right': { x: x + halfW, y, width: W - halfW, height: halfH },
+            'bottom-left': { x, y: y + halfH, width: halfW, height: H - halfH },
+            'bottom-right': { x: x + halfW, y: y + halfH, width: W - halfW, height: H - halfH }
         };
-        const [x, y, width, height] = rects[zone];
+        const rect = rects[zone];
         if (!w.restore) {
             w.restore = { pos: { ...w.pos }, size: w.size ? { ...w.size } : null };
         }
-        w.pos = { x, y };
-        w.size = { width, height };
+        w.pos = { x: rect.x, y: rect.y };
+        w.size = { width: rect.width, height: rect.height };
         w.state = 'normal';
         this.focus(id);
     }
+    /* ---------------- workspaces ---------------- */
+    /** Create a workspace (optionally switching to it) and return its id. */
+    addWorkspace(name, { activate = true } = {}) {
+        const id = `ws-${++this.#wsSeq}`;
+        this.workspaces.push({ id, name: name ?? `Workspace ${this.workspaces.length + 1}` });
+        if (activate)
+            this.activeWorkspaceId = id;
+        return id;
+    }
+    /** Show a workspace. Windows on others keep their geometry and stacking. */
+    switchWorkspace(id) {
+        if (this.workspaces.some((ws) => ws.id === id))
+            this.activeWorkspaceId = id;
+    }
+    /** Remove a workspace. Its windows migrate to the fallback (the active
+     *  workspace, or the first remaining one) — closing a desktop never
+     *  silently closes the work on it. The last workspace can't be removed. */
+    removeWorkspace(id) {
+        if (this.workspaces.length <= 1)
+            return;
+        this.workspaces = this.workspaces.filter((ws) => ws.id !== id);
+        if (this.activeWorkspaceId === id)
+            this.activeWorkspaceId = this.workspaces[0].id;
+        for (const w of this.windows) {
+            if (w.workspaceId === id)
+                w.workspaceId = this.activeWorkspaceId;
+        }
+    }
+    /** Send a window to another workspace (it stays where it was on screen). */
+    moveToWorkspace(windowId, workspaceId) {
+        const w = this.#find(windowId);
+        if (!w || !this.workspaces.some((ws) => ws.id === workspaceId))
+            return;
+        w.workspaceId = workspaceId;
+    }
 }
 const WM_KEY = Symbol('era-wm');
 export function setWindowManagerContext(wm) {

package/package.json

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