@dxos/plugin-deck 0.8.4-main.f5c0578 → 0.8.4-main.fcfe5033a5

package/src/operations/update-plank-size.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+import { UpdatePlankSize } from './definitions';
+import { updateActiveDeck } from './helpers';
+
+const handler: Operation.WithHandler<typeof UpdatePlankSize> = UpdatePlankSize.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+        updateActiveDeck(state, {
+          plankSizing: {
+            ...state.decks[state.activeDeck]?.plankSizing,
+            [input.id]: input.size,
+          },
+        }),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-popover.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.UpdatePopover> = LayoutOperation.UpdatePopover.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      yield* Capabilities.updateAtomValue(DeckCapabilities.EphemeralState, (state) => ({
+        ...state,
+        popoverOpen: input.state ?? Boolean(input.subject),
+        popoverKind: input.kind ?? 'base',
+        popoverTitle: input.kind === 'card' ? input.title : undefined,
+        popoverContentRef: input.subjectRef,
+        popoverContent:
+          typeof input.subject === 'string'
+            ? { component: input.subject, props: input.props }
+            : input.subject
+              ? { subject: input.subject }
+              : null,
+        popoverSide: input.side,
+        popoverAnchor: input.variant === 'virtual' ? input.anchor : state.popoverAnchor,
+        popoverAnchorId: input.variant !== 'virtual' ? input.anchorId : state.popoverAnchorId,
+      }));
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/update-sidebar.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/operation';
+
+import { DeckCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.UpdateSidebar> = LayoutOperation.UpdateSidebar.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const state = yield* Capabilities.getAtomValue(DeckCapabilities.State);
+      const next = input.state ?? state.sidebarState;
+      if (next !== state.sidebarState) {
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => ({
+          ...state,
+          sidebarState: next,
+        }));
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/translations.ts

@@ -4,64 +4,64 @@
 
 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.',
+        '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.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',
       },
     },
   },

package/src/types/Settings.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+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),
+  // TODO(burdon): Rename layoutMode? (e.g., bento | encapsulated?)
+  encapsulatedPlanks: Schema.optional(Schema.Boolean),
+}).pipe(Schema.mutable);
+export interface Settings extends Schema.Schema.Type<typeof Settings> {}

package/src/types/capabilities.ts

@@ -0,0 +1,35 @@
+//
+// 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 { type EphemeralDeckState, type DeckState, type StoredDeckState } from './schema';
+import * as Settings from './Settings';
+
+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,61 +44,75 @@ 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')),
   dialogOverlayClasses: Schema.optional(Schema.String),
   dialogOverlayStyle: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
   /** Data to be passed to the dialog Surface. */
-  dialogContent: Schema.optional(Schema.Any),
-
+  dialogContent: Schema.NullOr(Schema.Struct({ component: Schema.String, props: 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)),
+  popoverContent: Schema.NullOr(
+    Schema.Union(
+      Schema.Struct({ component: Schema.String, props: Schema.optional(Schema.Any) }),
+      Schema.Struct({ subject: Schema.Any }),
+    ),
+  ),
+  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 +128,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 +141,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

@@ -3,5 +3,6 @@
 //
 
 export * from './layoutAppliesTopbar';
-export * from './overscroll';
+export * from './plank-url-params';
+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/plank-url-params.test.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { deserializePlanks, serializePlanks, stripPlanks } from './plank-url-params';
+
+describe('serializePlanks', () => {
+  test('serializes active IDs as plank query params', ({ expect }) => {
+    const result = serializePlanks(['root/space1/types/doc/all/obj1', 'root/space1/types/doc/all/obj2'], '');
+    expect(result).toBe('?plank=%2Fspace1%2Ftypes%2Fdoc%2Fall%2Fobj1&plank=%2Fspace1%2Ftypes%2Fdoc%2Fall%2Fobj2');
+  });
+
+  test('returns empty string for empty active array with no existing params', ({ expect }) => {
+    expect(serializePlanks([], '')).toBe('');
+  });
+
+  test('preserves non-plank params', ({ expect }) => {
+    const result = serializePlanks(['root/space1/types/doc/all/obj1'], '?ref=abc');
+    expect(result).toContain('ref=abc');
+    expect(result).toContain('plank=');
+  });
+
+  test('preserves non-plank params when active array is empty', ({ expect }) => {
+    const result = serializePlanks([], '?ref=abc');
+    expect(result).toBe('?ref=abc');
+  });
+
+  test('replaces existing plank params', ({ expect }) => {
+    const result = serializePlanks(['root/space1/types/doc/all/obj2'], '?plank=%2Fspace1%2Ftypes%2Fdoc%2Fall%2Fobj1');
+    expect(result).not.toContain('obj1');
+    expect(result).toContain('obj2');
+  });
+});
+
+describe('deserializePlanks', () => {
+  test('deserializes plank query params to qualified IDs', ({ expect }) => {
+    const url = new URL(
+      'http://localhost/?plank=%2Fspace1%2Ftypes%2Fdoc%2Fall%2Fobj1&plank=%2Fspace1%2Ftypes%2Fdoc%2Fall%2Fobj2',
+    );
+    const result = deserializePlanks(url);
+    expect(result).toEqual(['root/space1/types/doc/all/obj1', 'root/space1/types/doc/all/obj2']);
+  });
+
+  test('returns empty array when no plank params', ({ expect }) => {
+    const url = new URL('http://localhost/?ref=abc');
+    expect(deserializePlanks(url)).toEqual([]);
+  });
+
+  test('preserves order', ({ expect }) => {
+    const url = new URL('http://localhost/?plank=%2Fa&plank=%2Fb&plank=%2Fc');
+    expect(deserializePlanks(url)).toEqual(['root/a', 'root/b', 'root/c']);
+  });
+});
+
+describe('stripPlanks', () => {
+  test('removes plank params', ({ expect }) => {
+    expect(stripPlanks('?plank=%2Fa&plank=%2Fb')).toBe('');
+  });
+
+  test('preserves non-plank params', ({ expect }) => {
+    expect(stripPlanks('?ref=abc&plank=%2Fa')).toBe('?ref=abc');
+  });
+
+  test('returns empty string when no params', ({ expect }) => {
+    expect(stripPlanks('')).toBe('');
+  });
+});
+
+describe('round-trip', () => {
+  test('serialize then deserialize returns original IDs', ({ expect }) => {
+    const ids = ['root/space1/types/doc/all/obj1', 'root/space1/types/doc/all/obj2'];
+    const search = serializePlanks(ids, '');
+    const url = new URL(`http://localhost/${search}`);
+    expect(deserializePlanks(url)).toEqual(ids);
+  });
+
+  test('handles special characters in IDs', ({ expect }) => {
+    const ids = ['root/!dxos:settings', 'root/~personal/types/doc/all/obj1'];
+    const search = serializePlanks(ids, '');
+    const url = new URL(`http://localhost/${search}`);
+    expect(deserializePlanks(url)).toEqual(ids);
+  });
+});

package/src/util/plank-url-params.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { fromUrlPath, toUrlPath } from '@dxos/app-toolkit';
+
+const PLANK_PARAM = 'plank';
+
+/**
+ * Serialize deck active qualified IDs into a URL search string.
+ * Preserves non-plank query params from the existing search string.
+ */
+export const serializePlanks = (active: readonly string[], existingSearch: string): string => {
+  const params = new URLSearchParams(existingSearch);
+  params.delete(PLANK_PARAM);
+  for (const id of active) {
+    params.append(PLANK_PARAM, toUrlPath(id));
+  }
+  return params.size > 0 ? `?${params.toString()}` : '';
+};
+
+/**
+ * Deserialize plank query params from a URL back to qualified graph IDs.
+ */
+export const deserializePlanks = (url: URL): string[] => {
+  return url.searchParams.getAll(PLANK_PARAM).map(fromUrlPath);
+};
+
+/**
+ * Strip plank query params from a search string, preserving all others.
+ */
+export const stripPlanks = (existingSearch: string): string => {
+  const params = new URLSearchParams(existingSearch);
+  params.delete(PLANK_PARAM);
+  return params.size > 0 ? `?${params.toString()}` : '';
+};