@dxos/plugin-deck 0.8.4-main.b97322e → 0.8.4-main.bcb3aa67d6

package/src/translations.ts

@@ -4,64 +4,79 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Deck',
-        'main header label': 'Main header',
-        'open navigation sidebar label': 'Open sidebar',
-        'collapse navigation sidebar label': 'Minimize sidebar',
-        'open complementary sidebar label': 'Open context sidebar',
-        'close complementary sidebar label': 'Minimize context sidebar',
-        'sidebar title': 'Navigation sidebar',
-        'complementary sidebar title': 'Context sidebar',
-        'plugin error message': 'Content failed to render.',
-        'content fallback message': 'Unsupported',
-        'content fallback description':
+        'plugin.name': 'Deck',
+        'settings.title': 'Deck settings',
+        'main-header.label': 'Main header',
+        'open-navigation-sidebar.label': 'Open sidebar',
+        'collapse-navigation-sidebar.label': 'Minimize sidebar',
+        'open-complementary-sidebar.label': 'Open context sidebar',
+        'close-complementary-sidebar.label': 'Minimize context sidebar',
+        'sidebar.title': 'Navigation sidebar',
+        'complementary-sidebar.title': 'Context sidebar',
+        'plugin-error.message': 'Content failed to render.',
+        'content-fallback.message': 'Unsupported',
+        'content-fallback.description':
           'No plugin had a response for the address you navigated to. Double-check the URL, and ensure you’ve enabled a plugin that supports the object.',
-        'toggle fullscreen label': 'Toggle fullscreen',
-        'settings show hints label': 'Show hints',
-        'settings native redirect label': 'Enable native url redirect (experimental)',
-        'settings new plank position start label': 'Start',
-        'settings new plank position end label': 'End',
-        'select new plank positioning placeholder': 'Select new plank positioning',
-        'select new plank positioning label': 'New plank positioning',
-        'undo available label': 'Click to undo previous action.',
-        'undo action label': 'Undo',
-        'undo action alt': 'Undo previous action',
-        'undo close label': 'Dismiss',
-        'error fallback message': 'Unable to open this item',
-        'plank heading fallback label': 'Untitled',
-        'actions menu label': 'Options',
-        'settings deck label': 'Disable deck',
-        'pending heading': 'Loading…',
-        'insert plank label': 'Open',
-        'resize label': 'Drag to resize',
-        'pin start label': 'Pin to the left sidebar',
-        'pin end label': 'Pin to the right sidebar',
-        'increment start label': 'Move to the left',
-        'increment end label': 'Move to the right',
-        'show deck plank label': 'Return to deck',
-        'show solo plank label': 'Maximize',
-        'exit fullscreen label': 'Exit fullscreen',
-        'show fullscreen plank label': 'Fullscreen',
-        'close label': 'Close',
-        'minify label': 'Minify',
-        'open companion label': 'Open companion',
-        'close companion label': 'Close companion',
-        'settings overscroll label': 'Plank scrolling',
-        'select overscroll placeholder': 'Select plank scrolling behavior',
-        'settings overscroll centering label': 'Centering',
-        'settings overscroll none label': 'None',
-        'settings enable statusbar label': 'Show status bar',
-        'settings enable deck label': 'Enable Deck',
-        'close current label': 'Close current plank',
-        'close others label': 'Close other planks',
-        'close all label': 'Close all planks',
-        'companion plank heading fallback label': 'Related',
+        'toggle-fullscreen.label': 'Toggle fullscreen',
+        'settings.show-hints.label': 'Show hints',
+        'settings.show-hints.description': 'Show helpful tips and keyboard shortcut hints in the interface.',
+        'settings.native-redirect.label': 'Enable native url redirect',
+        'settings.native-redirect.description': 'Redirect supported URLs to the native desktop application.',
+        'settings.new-plank-position.start.label': 'Start',
+        'settings.new-plank-position.end.label': 'End',
+        'select-new-plank-positioning.placeholder': 'Select new plank positioning',
+        'select-new-plank-positioning.label': 'New plank positioning',
+        'select-new-plank-positioning.description':
+          'Choose whether newly opened planks appear at the start or end of the deck.',
+        'undo-available.label': 'Click to undo previous action.',
+        'undo-action.label': 'Undo',
+        'undo-action.alt': 'Undo previous action',
+        'undo-close.label': 'Dismiss',
+        'error-fallback.message': 'Unable to open this object',
+        'plank-heading-fallback.label': 'Untitled',
+        'actions-menu.label': 'Options',
+        'settings.deck.label': 'Disable deck',
+        'pending.heading': 'Loading…',
+        'insert-plank.label': 'Open',
+        'resize.label': 'Drag to resize',
+        'pin-start.label': 'Pin to the left sidebar',
+        'pin-end.label': 'Pin to the right sidebar',
+        'increment-start.label': 'Move to the left',
+        'increment-end.label': 'Move to the right',
+        'show-deck-plank.label': 'Return to deck',
+        'show-solo-plank.label': 'Maximize',
+        'exit-fullscreen.label': 'Exit fullscreen',
+        'show-fullscreen-plank.label': 'Fullscreen',
+        'close.label': 'Close',
+        'minify.label': 'Minify',
+        'open-companion.label': 'Open companion',
+        'close-companion.label': 'Close companion',
+        'settings.overscroll.label': 'Plank scrolling',
+        'settings.overscroll.description': 'Control how planks behave when scrolled to the edge of the deck.',
+        'select-overscroll.placeholder': 'Select plank scrolling behavior',
+        'settings.overscroll.centering.label': 'Centering',
+        'settings.overscroll.none.label': 'None',
+        'settings.enable-statusbar.label': 'Show status bar',
+        'settings.enable-statusbar.description': 'Display a status bar at the bottom of the application.',
+        'settings.enable-deck.label': 'Enable Deck',
+        'settings.enable-deck.description': 'Display multiple panels side by side instead of one at a time.',
+        'settings.encapsulated-planks.label': 'Encapsulated planks',
+        'settings.encapsulated-planks.description': 'Render each plank inside its own isolated container.',
+        'close-current.label': 'Close current plank',
+        'close-others.label': 'Close other planks',
+        'close-all.label': 'Close all planks',
+        'close-navigation-sidebar.button': 'Close',
+        'companion-plank-heading-fallback.label': 'Related',
+        'settings.new-plank-position-start.label': 'Start',
+        'settings.new-plank-position-end.label': 'End',
+        'settings.overscroll-centering.label': 'Centering',
+        'settings.overscroll-none.label': 'None',
       },
     },
   },

package/src/types/Settings.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+// TODO(Zan): In the future we should consider adding new planks adjacent to the attended plank.
+export const NewPlankPositions = ['start', 'end'] as const;
+export type NewPlankPositioning = (typeof NewPlankPositions)[number];
+
+export const OverScrollToProps = ['none', 'centering'] as const;
+export type Overscroll = (typeof OverScrollToProps)[number];
+
+export const Settings = Schema.Struct({
+  showHints: Schema.optional(Schema.Boolean),
+  enableDeck: Schema.optional(Schema.Boolean),
+  enableStatusbar: Schema.optional(Schema.Boolean),
+  enableNativeRedirect: Schema.optional(Schema.Boolean),
+  newPlankPositioning: Schema.optional(Schema.Literal(...NewPlankPositions)),
+  overscroll: Schema.optional(Schema.Literal(...OverScrollToProps)),
+  // TODO(burdon): Rename layoutMode? (e.g., bento | encapsulated?)
+  encapsulatedPlanks: Schema.optional(Schema.Boolean),
+}).pipe(Schema.mutable);
+export type Settings = Schema.Schema.Type<typeof Settings>;

package/src/types/capabilities.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+
+import { meta } from '#meta';
+import * as Settings from './Settings';
+import { type EphemeralDeckState, type DeckState, type StoredDeckState } from './schema';
+
+export namespace DeckCapabilities {
+  export const Settings = Capability.make<Atom.Writable<Settings.Settings>>(`${meta.id}.capability.settings`);
+
+  /** Persisted state (stored in KVS/localStorage). */
+  export const State = Capability.make<Atom.Writable<StoredDeckState>>(`${meta.id}.capability.state`);
+
+  /** Transient/ephemeral state (not persisted). */
+  export const EphemeralState = Capability.make<Atom.Writable<EphemeralDeckState>>(
+    `${meta.id}.capability.ephemeral-state`,
+  );
+
+  /** Get the current active deck from state. */
+  export const getDeck = (): Effect.Effect<DeckState, Error, Capability.Service> =>
+    Effect.gen(function* () {
+      const state = yield* Capabilities.getAtomValue(State);
+      const deck = state.decks[state.activeDeck];
+      invariant(deck, `Deck not found: ${state.activeDeck}`);
+      return deck;
+    });
+}

package/src/types/events.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ActivationEvent } from '@dxos/app-framework';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+
+import { meta } from '#meta';
+
+import { DeckCapabilities } from './capabilities';
+
+export namespace DeckEvents {
+  export const StateReady: ActivationEvent.ActivationEvent = AppActivationEvents.createStateEvent(
+    `${meta.id}.state-ready`,
+  );
+
+  /** Fired when DeckSettings capability is ready. */
+  export const SettingsReady: ActivationEvent.ActivationEvent = AppActivationEvents.createSettingsEvent(
+    DeckCapabilities.Settings.identifier,
+  );
+}

package/src/types/index.ts

@@ -2,4 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './capabilities';
+export * from './events';
 export * from './schema';
+export * as Settings from './Settings';

package/src/types/schema.ts

@@ -2,52 +2,41 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
-import { LayoutAction } from '@dxos/app-framework';
+import { Label, LayoutOperation } from '@dxos/app-toolkit';
 import { type DeepReadonly } from '@dxos/util';
 
-import { meta } from '../meta';
+import { meta } from '#meta';
 
-export { ATTENDABLE_PATH_SEPARATOR } from '@dxos/react-ui-attention';
+export * as Settings from './Settings';
 
-export const PLANK_COMPANION_TYPE = 'dxos.org/plugin/deck/plank-companion';
-export const DECK_COMPANION_TYPE = 'dxos.org/plugin/deck/deck-companion';
+export { PLANK_COMPANION_TYPE, DECK_COMPANION_TYPE } from '@dxos/app-toolkit';
 
-// TODO(Zan): In the future we should consider adding new planks adjacent to the attended plank.
-export const NewPlankPositions = ['start', 'end'] as const;
-export type NewPlankPositioning = (typeof NewPlankPositions)[number];
-
-export const OverscrollOptions = ['none', 'centering'] as const;
-export type Overscroll = (typeof OverscrollOptions)[number];
-
-export type Part = 'solo' | 'deck' | 'complementary';
+export type Part = 'solo' | 'multi' | 'complementary';
 export type ResolvedPart = Part | 'solo-primary' | 'solo-companion';
 
-export const DeckSettingsSchema = Schema.Struct({
-  showHints: Schema.optional(Schema.Boolean),
-  enableDeck: Schema.optional(Schema.Boolean),
-  enableStatusbar: Schema.optional(Schema.Boolean),
-  enableNativeRedirect: Schema.optional(Schema.Boolean),
-  newPlankPositioning: Schema.optional(Schema.Literal(...NewPlankPositions)),
-  overscroll: Schema.optional(Schema.Literal(...OverscrollOptions)),
-}).pipe(Schema.mutable);
-export type DeckSettingsProps = Schema.Schema.Type<typeof DeckSettingsSchema>;
-
 export const PlankSizing = Schema.Record({ key: Schema.String, value: Schema.Number });
 export type PlankSizing = Schema.Schema.Type<typeof PlankSizing>;
 
-// State of an individual deck.
 export const DeckState = Schema.Struct({
   /** If false, the deck has not yet left solo mode and new planks should be soloed. */
   initialized: Schema.Boolean,
+  /** Item IDs of planks currently displayed in multi-mode. */
   active: Schema.mutable(Schema.Array(Schema.String)),
-  // TODO(wittjosiah): Piping into both mutable and optional caused invalid typescript output.
-  activeCompanions: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.String }))),
+  /** Item IDs of planks that have been closed; used for state persistence and reopening. */
   inactive: Schema.mutable(Schema.Array(Schema.String)),
+  /** Item ID of the single plank displayed in solo or fullscreen mode. */
   solo: Schema.optional(Schema.String),
+  /** Whether the solo plank is displayed in fullscreen mode (no heading or sidebars). */
   fullscreen: Schema.Boolean,
+  /** Persisted plank widths in rem, keyed by item ID. */
   plankSizing: Schema.mutable(PlankSizing),
+  /** Whether the companion pane is visible alongside the active plank(s). */
+  companionOpen: Schema.Boolean,
+  /** Which companion variant to display when the companion pane is open. */
+  companionVariant: Schema.optional(Schema.String),
+  /** Persisted companion frame widths in rem, keyed by frame ID. */
   companionFrameSizing: Schema.mutable(PlankSizing),
 });
 export type DeckState = Schema.Schema.Type<typeof DeckState>;
@@ -55,32 +44,44 @@ export type DeckState = Schema.Schema.Type<typeof DeckState>;
 export const defaultDeck: DeckState = {
   initialized: false,
   active: [],
-  activeCompanions: {},
   inactive: [],
   solo: undefined,
   fullscreen: false,
   plankSizing: {},
+  companionOpen: false,
+  companionVariant: undefined,
   companionFrameSizing: {},
 };
 
-const LayoutMode = Schema.Literal('deck', 'solo', 'solo--fullscreen');
+//
+// Layout
+//
+
+const LayoutMode = Schema.Literal('multi', 'solo', 'solo--fullscreen');
 export type LayoutMode = Schema.Schema.Type<typeof LayoutMode>;
 export const isLayoutMode = (value: any): value is LayoutMode => Schema.is(LayoutMode)(value);
-
 export const getMode = (deck: DeckState | DeepReadonly<DeckState>): LayoutMode => {
   if (deck.solo) {
     return deck.fullscreen ? 'solo--fullscreen' : 'solo';
   }
 
-  return 'deck';
+  return 'multi';
 };
 
-// State of the deck plugin.
-export const DeckPluginState = Schema.Struct({
+// Persisted plugin state (stored in KVS/localStorage).
+export const StoredDeckState = Schema.Struct({
   sidebarState: Schema.Literal('closed', 'collapsed', 'expanded'),
   complementarySidebarState: Schema.Literal('closed', 'collapsed', 'expanded'),
   complementarySidebarPanel: Schema.optional(Schema.String),
+  activeDeck: Schema.String,
+  previousDeck: Schema.String,
+  decks: Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.mutable(DeckState) })),
+  previousMode: Schema.mutable(Schema.Record({ key: Schema.String, value: LayoutMode })),
+}).pipe(Schema.mutable);
+export type StoredDeckState = Schema.Schema.Type<typeof StoredDeckState>;
 
+// Transient/ephemeral plugin state (not persisted).
+export const EphemeralDeckState = Schema.Struct({
   dialogOpen: Schema.Boolean,
   dialogType: Schema.optional(Schema.Literal('default', 'alert')),
   dialogBlockAlign: Schema.optional(Schema.Literal('start', 'center', 'end')),
@@ -88,28 +89,25 @@ export const DeckPluginState = Schema.Struct({
   dialogOverlayStyle: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
   /** Data to be passed to the dialog Surface. */
   dialogContent: Schema.optional(Schema.Any),
-
   popoverOpen: Schema.Boolean,
   popoverSide: Schema.optional(Schema.Literal('top', 'right', 'bottom', 'left')),
   popoverAnchor: Schema.optional(Schema.Any),
   popoverAnchorId: Schema.optional(Schema.String),
+  popoverKind: Schema.optional(Schema.Literal('base', 'card')),
+  popoverTitle: Schema.optional(Label.annotations({ description: 'The title of the popover.' })),
+  /** Ref of the subject to be passed to the popover Surface. */
+  popoverContentRef: Schema.optional(Schema.String),
   /** Data to be passed to the popover Surface. */
   popoverContent: Schema.optional(Schema.Any),
-
-  toasts: Schema.mutable(Schema.Array(LayoutAction.Toast)),
+  toasts: Schema.mutable(Schema.Array(LayoutOperation.Toast)),
   currentUndoId: Schema.optional(Schema.String),
-
-  activeDeck: Schema.String,
-  previousDeck: Schema.String,
-  decks: Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.mutable(DeckState) })),
-  previousMode: Schema.mutable(Schema.Record({ key: Schema.String, value: LayoutMode })),
-  deck: Schema.mutable(DeckState),
-
   /** The identifier of a component to scroll into view when it is mounted. */
   scrollIntoView: Schema.optional(Schema.String),
 }).pipe(Schema.mutable);
+export type EphemeralDeckState = Schema.Schema.Type<typeof EphemeralDeckState>;
 
-export type DeckPluginState = Schema.Schema.Type<typeof DeckPluginState>;
+// Combined state type (for convenience in components that need both).
+export type DeckPluginState = StoredDeckState & EphemeralDeckState;
 
 export namespace DeckAction {
   const PartAdjustmentSchema = Schema.Union(
@@ -125,12 +123,12 @@ export namespace DeckAction {
   export type Adjustment = Schema.Schema.Type<typeof Adjustment>;
 
   // An atomic transaction to apply to the deck, describing which element to move to which location.
-  export class Adjust extends Schema.TaggedClass<Adjust>()(`${meta.id}/action/adjust`, {
+  export class Adjust extends Schema.TaggedClass<Adjust>()(`${meta.id}.action.adjust`, {
     input: Adjustment,
     output: Schema.Void,
   }) {}
 
-  export class UpdatePlankSize extends Schema.TaggedClass<UpdatePlankSize>()(`${meta.id}/action/update-plank-size`, {
+  export class UpdatePlankSize extends Schema.TaggedClass<UpdatePlankSize>()(`${meta.id}.action.update-plank-size`, {
     input: Schema.Struct({
       id: Schema.String,
       size: Schema.Number,
@@ -138,9 +136,8 @@ export namespace DeckAction {
     output: Schema.Void,
   }) {}
 
-  export class ChangeCompanion extends Schema.TaggedClass<ChangeCompanion>()(`${meta.id}/action/change-companion`, {
+  export class ChangeCompanion extends Schema.TaggedClass<ChangeCompanion>()(`${meta.id}.action.change-companion`, {
     input: Schema.Struct({
-      primary: Schema.String,
       companion: Schema.Union(Schema.String, Schema.Null),
     }),
     output: Schema.Void,

package/src/util/index.ts

@@ -4,4 +4,5 @@
 
 export * from './layoutAppliesTopbar';
 export * from './overscroll';
+export * from './sanitize-persisted-state';
 export * from './set-active';

package/src/util/layoutAppliesTopbar.ts

@@ -2,11 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type LayoutMode } from '../types';
+import { type LayoutMode } from '#types';
 
 export const layoutAppliesTopbar = (breakpoint: string, layoutMode?: LayoutMode) => {
   return (
-    document.body.getAttribute('data-platform') === 'win' &&
+    document.body.getAttribute('data-platform') === 'windows' &&
     breakpoint === 'desktop' &&
     layoutMode !== 'solo--fullscreen'
   );

package/src/util/overscroll.ts

@@ -56,14 +56,14 @@ export const calculateOverscroll = (
   }
   if (planksCount === 1) {
     const overscrollPadding =
-      'max(0px, calc(((100dvw - var(--dx-main-sidebarWidth) - var(--dx-main-complementaryWidth) - (var(--dx-main-contentFirstWidth) + 1px)) / 2)))';
+      'max(0px, calc(((100dvw - var(--main-sidebar-width) - var(--main-complementary-width) - (var(--main-content-first-width) + 1px)) / 2)))';
     return { paddingInlineStart: overscrollPadding, paddingInlineEnd: overscrollPadding };
   } else {
     return {
       paddingInlineStart:
-        'max(0px, calc(((100dvw - (var(--dx-main-contentFirstWidth) + 1px)) / 2) - var(--dx-main-sidebarWidth)))',
+        'max(0px, calc(((100dvw - (var(--main-content-first-width) + 1px)) / 2) - var(--main-sidebar-width)))',
       paddingInlineEnd:
-        'max(0px, calc(((100dvw - (var(--dx-main-contentLastWidth) + 1px)) / 2) - var(--dx-main-complementaryWidth)))',
+        'max(0px, calc(((100dvw - (var(--main-content-last-width) + 1px)) / 2) - var(--main-complementary-width)))',
     };
   }
 };

package/src/util/sanitize-persisted-state.test.ts

@@ -0,0 +1,79 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { defaultDeck, type DeckState, type StoredDeckState } from '#types';
+
+import { sanitizePersistedState } from './sanitize-persisted-state';
+
+const makeState = (decks: Record<string, Partial<DeckState>>): StoredDeckState => ({
+  sidebarState: 'expanded',
+  complementarySidebarState: 'collapsed',
+  complementarySidebarPanel: undefined,
+  activeDeck: Object.keys(decks)[0] ?? 'default',
+  previousDeck: 'default',
+  decks: Object.fromEntries(Object.entries(decks).map(([id, overrides]) => [id, { ...defaultDeck, ...overrides }])),
+  previousMode: {},
+});
+
+describe('sanitizePersistedState', () => {
+  test('returns same reference when no cleanup needed', ({ expect }) => {
+    const state = makeState({ default: {} });
+    expect(sanitizePersistedState(state)).toBe(state);
+  });
+
+  test('clears fullscreen on any deck', ({ expect }) => {
+    const state = makeState({ ws1: { fullscreen: true } });
+    const result = sanitizePersistedState(state);
+    expect(result.decks.ws1?.fullscreen).toBe(false);
+  });
+
+  test('clears active for solo-mode decks', ({ expect }) => {
+    const state = makeState({ ws1: { solo: 'item-a', active: ['item-b', 'item-c'] } });
+    const result = sanitizePersistedState(state);
+    expect(result.decks.ws1?.active).toEqual([]);
+    expect(result.decks.ws1?.solo).toBe('item-a');
+  });
+
+  test('preserves active for deck-mode decks (no solo)', ({ expect }) => {
+    const state = makeState({ ws1: { active: ['item-a', 'item-b'], initialized: true } });
+    const result = sanitizePersistedState(state);
+    expect(result).toBe(state);
+  });
+
+  test('does not clear active when it is already empty', ({ expect }) => {
+    const state = makeState({ ws1: { solo: 'item-a', active: [] } });
+    expect(sanitizePersistedState(state)).toBe(state);
+  });
+
+  test('cleans multiple decks independently', ({ expect }) => {
+    const state = makeState({
+      ws1: { solo: 'item-a', active: ['item-b'] },
+      ws2: { active: ['item-c'], initialized: true },
+      ws3: { fullscreen: true, solo: 'item-d', active: ['item-e'] },
+    });
+    const result = sanitizePersistedState(state);
+
+    // ws1: solo with active → active cleared.
+    expect(result.decks.ws1?.active).toEqual([]);
+    expect(result.decks.ws1?.solo).toBe('item-a');
+
+    // ws2: deck mode, no solo → untouched.
+    expect(result.decks.ws2?.active).toEqual(['item-c']);
+
+    // ws3: fullscreen + solo with active → both cleared.
+    expect(result.decks.ws3?.fullscreen).toBe(false);
+    expect(result.decks.ws3?.active).toEqual([]);
+    expect(result.decks.ws3?.solo).toBe('item-d');
+  });
+
+  test('does not mutate the original state', ({ expect }) => {
+    const state = makeState({ ws1: { solo: 'item-a', active: ['item-b'], fullscreen: true } });
+    const originalActive = [...state.decks.ws1!.active];
+    sanitizePersistedState(state);
+    expect(state.decks.ws1?.active).toEqual(originalActive);
+    expect(state.decks.ws1?.fullscreen).toBe(true);
+  });
+});

package/src/util/sanitize-persisted-state.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type StoredDeckState } from '#types';
+
+/**
+ * Sanitizes persisted deck state on startup.
+ *
+ * Persisted state may contain values that are inappropriate to restore across sessions:
+ *
+ * - **Fullscreen**: Cleared unconditionally to prevent the user from getting stuck in fullscreen
+ *   mode if the app was closed (or crashed) while fullscreen was active.
+ *
+ * - **Active planks in solo-mode decks**: When a deck is in solo mode, any items in `active`
+ *   represent planks that were kept mounted (hidden) during the session for fast deck↔solo
+ *   switching. After a restart these planks would need to fully remount anyway, so retaining
+ *   them only adds unnecessary load. Clearing `active` for solo-mode decks avoids rendering
+ *   stale planks in the background on startup.
+ *
+ * Returns a new state object if any changes were made, or the original state if clean.
+ */
+export const sanitizePersistedState = (state: StoredDeckState): StoredDeckState => {
+  let needsUpdate = false;
+  const cleanedDecks = { ...state.decks };
+
+  for (const [id, deck] of Object.entries(cleanedDecks)) {
+    if (!deck) {
+      continue;
+    }
+
+    let updated = false;
+    let cleanedDeck = deck;
+
+    if (deck.fullscreen) {
+      cleanedDeck = { ...cleanedDeck, fullscreen: false };
+      updated = true;
+    }
+
+    if (deck.solo && deck.active.length > 0) {
+      cleanedDeck = { ...cleanedDeck, active: [] };
+      updated = true;
+    }
+
+    if (updated) {
+      cleanedDecks[id] = cleanedDeck;
+      needsUpdate = true;
+    }
+  }
+
+  return needsUpdate ? { ...state, decks: cleanedDecks } : state;
+};