@dxos/plugin-deck 0.8.4-main.9735255 → 0.8.4-main.9be5663bfe

package/src/translations.ts

@@ -4,66 +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',
-        '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':
+        '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 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',
-        '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',
-        'settings encapsulated planks label': 'Encapsulated planks',
-        '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 type Settings = Schema.Schema.Type<typeof Settings>;

package/src/types/capabilities.ts

@@ -5,27 +5,29 @@
 import { type Atom } from '@effect-atom/atom-react';
 import * as Effect from 'effect/Effect';
 
-import { Capability, Common } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
 import { invariant } from '@dxos/invariant';
 
-import { meta } from '../meta';
-import { type DeckEphemeralStateProps, type DeckSettingsProps, type DeckState, type DeckStateProps } from '../types';
+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<DeckSettingsProps>>(`${meta.id}/capability/settings`);
+  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<DeckStateProps>>(`${meta.id}/capability/state`);
+  export const State = Capability.make<Atom.Writable<StoredDeckState>>(`${meta.id}.capability.state`);
 
   /** Transient/ephemeral state (not persisted). */
-  export const EphemeralState = Capability.make<Atom.Writable<DeckEphemeralStateProps>>(
-    `${meta.id}/capability/ephemeral-state`,
+  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* Common.Capability.getAtomValue(State);
+      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

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

package/src/types/index.ts

@@ -5,3 +5,4 @@
 export * from './capabilities';
 export * from './events';
 export * from './schema';
+export * as Settings from './Settings';

package/src/types/schema.ts

@@ -4,53 +4,39 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Capability, Common } from '@dxos/app-framework';
-import { Operation } from '@dxos/operation';
+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 = `${meta.id}/plank-companion`;
-export const DECK_COMPANION_TYPE = `${meta.id}/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)),
-  // TODO(burdon): Rename layoutMode? (e.g., bento | encapsulated?)
-  encapsulatedPlanks: Schema.optional(Schema.Boolean),
-}).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>;
@@ -58,28 +44,32 @@ 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';
 };
 
 // Persisted plugin state (stored in KVS/localStorage).
-export const DeckStateSchema = Schema.Struct({
+export const StoredDeckState = Schema.Struct({
   sidebarState: Schema.Literal('closed', 'collapsed', 'expanded'),
   complementarySidebarState: Schema.Literal('closed', 'collapsed', 'expanded'),
   complementarySidebarPanel: Schema.optional(Schema.String),
@@ -88,37 +78,41 @@ export const DeckStateSchema = Schema.Struct({
   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 DeckStateProps = Schema.Schema.Type<typeof DeckStateSchema>;
+export type StoredDeckState = Schema.Schema.Type<typeof StoredDeckState>;
 
 // Transient/ephemeral plugin state (not persisted).
-export const DeckEphemeralStateSchema = Schema.Struct({
+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(Common.Label.annotations({ description: 'The title of the popover.' })),
+  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(Common.LayoutOperation.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),
-
   /** The identifier of a component to scroll into view when it is mounted. */
   scrollIntoView: Schema.optional(Schema.String),
 }).pipe(Schema.mutable);
-export type DeckEphemeralStateProps = Schema.Schema.Type<typeof DeckEphemeralStateSchema>;
+export type EphemeralDeckState = Schema.Schema.Type<typeof EphemeralDeckState>;
 
 // Combined state type (for convenience in components that need both).
-export type DeckPluginState = DeckStateProps & DeckEphemeralStateProps;
+export type DeckPluginState = StoredDeckState & EphemeralDeckState;
 
 export namespace DeckAction {
   const PartAdjustmentSchema = Schema.Union(
@@ -134,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,
@@ -147,74 +141,10 @@ 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,
   }) {}
 }
-
-/**
- * Operations for the Deck plugin.
- */
-export namespace DeckOperation {
-  const PartAdjustmentSchema = Schema.Union(
-    Schema.Literal('close').annotations({ description: 'Close the plank.' }),
-    Schema.Literal('companion').annotations({ description: 'Open the companion plank.' }),
-    Schema.Literal('solo').annotations({ description: 'Solo the plank.' }),
-    Schema.Literal('solo--fullscreen').annotations({ description: 'Fullscreen the plank.' }),
-    Schema.Literal('increment-start').annotations({ description: 'Move the plank towards the start of the deck.' }),
-    Schema.Literal('increment-end').annotations({ description: 'Move the plank towards the end of the deck.' }),
-  );
-  export type PartAdjustment = Schema.Schema.Type<typeof PartAdjustmentSchema>;
-
-  export const Adjust = Operation.make({
-    meta: {
-      key: `${meta.id}/operation/adjust`,
-      name: 'Adjust',
-      description: 'Adjust the layout of a plank.',
-    },
-    services: [Capability.Service],
-    schema: {
-      input: Schema.Struct({
-        id: Schema.String.annotations({ description: 'The id of the plank to adjust.' }),
-        type: PartAdjustmentSchema.annotations({ description: 'The type of adjustment to make.' }),
-      }),
-      output: Schema.Void,
-    },
-  });
-
-  export const UpdatePlankSize = Operation.make({
-    meta: {
-      key: `${meta.id}/operation/update-plank-size`,
-      name: 'Update Plank Size',
-      description: 'Update the size of a plank.',
-    },
-    services: [Capability.Service],
-    schema: {
-      input: Schema.Struct({
-        id: Schema.String.annotations({ description: 'The id of the plank to resize.' }),
-        size: Schema.Number.annotations({ description: 'The new size of the plank.' }),
-      }),
-      output: Schema.Void,
-    },
-  });
-
-  export const ChangeCompanion = Operation.make({
-    meta: {
-      key: `${meta.id}/operation/change-companion`,
-      name: 'Change Companion',
-      description: 'Change the companion plank for a primary plank.',
-    },
-    services: [Capability.Service],
-    schema: {
-      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,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type LayoutMode } from '../types';
+import { type LayoutMode } from '#types';
 
 export const layoutAppliesTopbar = (breakpoint: string, layoutMode?: LayoutMode) => {
   return (

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()}` : '';
+};