Skip to content

Commit d36df14

Browse files
matt2eclaude
andcommitted
feat(navigation): pages declare overlay route params that never enter history
Follow-up to cd78176, whose "presentation-only changes are written in place" rule keyed on the conversation `panel` field alone, so it covered exactly one dialog (channel Members). The Agents provider dialog, carried by the page route `{ provider }`, could still be pushed as a visit, so Back while it was open merely dismissed it. The rule is now generic: no dialog is ever a Back/Forward destination, and an open dialog never consumes Back. Design: presentation is an explicit notion on targets. `pageKey(target, overlay?)` strips a conversation's `panel` and, for page targets, the route params the page declares as `overlay` (`Page.route.overlay: readonly string[]`, next to `validate`); when only overlay keys remain the route is dropped, so the dialog shares its visit with the bare page. Keys apply to object params only. `createNavigationController` takes an `OverlayKeys` lookup and compares page keys through it, so it keeps a page's dialogs out of history without knowing the page. `createServices` constructs the pages registry first and supplies the lookup from the registered page's route. Pages registered after an open (plugin still starting) simply get the old push, as before. - `src/features/pages/service.ts` (FOUNDATION): adds the optional `route.overlay` field and rejects non-string-array values with the existing "Invalid page route contract" error. Edited under this task's explicit guidance that a page should declare the overlay param. - Agents declares `overlay: ["provider"]`. `setProviderKey` loses its `replace` parameter and always opens with `{ replace: true }`, matching the Members convention; the host forces it regardless. The address still carries the provider, so reload and legacy provider links restore the dialog. Note the page itself only ever closes the dialog today; the rule bites when a provider link is followed while already on Agents. - Settings is untouched; `returnTo` stays for `leaveSettings`. - Docs: the navigation-targets section states the generic rule and the `route.overlay` contract. Tests: controller case for a page overlay change forced to replace with `replace: false` (Back leaves the page, Forward restores it with the dialog, close replaces, a destination param still pushes, and the same params push without a declaration); targets case for key stripping, partial params and non-object params; pages-service case for overlay validation; App-level case in entity-navigation.test.tsx that boots real services with the Agents plugin and asserts opening the provider route leaves `history.length` and canGoForward unchanged, Back lands on the visit before Agents, and Forward returns with the provider route. Validation: `tsc --noEmit` clean; biome check on changed files clean; `vitest run src/features/navigation src/features/pages src/bundled/agents` 17 files, 287 passed; `src/app/entity-navigation` 13 passed. A combined run that also included App.profile, Settings, app navigation and ChannelsPage showed 435 passed / 6 failed, all 5 s timeouts in pre-existing App tests under a load average of 190 from other work on the machine; App.profile rerun alone 19/19 and navigation.test passed serially, so no regression was observed. Playwright channel-members: chromium 5/5, webkit 5/5. The nine agent-*/local-agent-*/owned-agent-* specs on chromium: 32/32. Not exercised: the native desktop app or a human walkthrough. Co-Authored-By: Claude Fable 5.1 <[email protected]> Signed-off-by: Matt Toohey <[email protected]>
1 parent cd78176 commit d36df14

12 files changed

Lines changed: 236 additions & 28 deletions

File tree

‎docs/plugin-architecture.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1221,9 +1221,11 @@ Members dialog without replacing its channel/message identity. Unknown panel
12211221
values are rejected; this is presentation state, never mutation or confirmation state.
12221222
A dialog is reflected in the address so reload and deep links restore it, but it
12231223
never creates a history visit: the host writes a target that differs from the
1224-
current visit only in `panel` with `replace`, whatever the caller passes, so a
1225-
page cannot push a dialog as a Back/Forward destination and Back always leaves
1226-
the page the dialog is on. Open and close it with `open(target, { replace: true })`.
1224+
current visit only in presentation (a conversation's `panel`, or the route params
1225+
a page declares as `overlay`, below) with `replace`, whatever the caller passes,
1226+
so a page cannot push a dialog as a Back/Forward destination and Back always
1227+
leaves the page the dialog is on. Open and close it with
1228+
`open(target, { replace: true })`.
12271229
`returnTo` names the id of an earlier visit to traverse back to instead of
12281230
opening anew (Settings uses it to leave a multi-section modal); when that visit
12291231
is not in the current chain the target opens as usual.
@@ -1258,9 +1260,14 @@ session-owned subtree; Channels demonstrates this boundary. Replacement revokes
12581260
the bound request synchronously without revoking static page authority or resetting
12591261
the caller's deadline. These are trusted-plugin lifecycle fences, not a sandbox.
12601262

1261-
`route: { version, validate }` opts a page
1262-
into versioned route parameters. These are host-matched preview types through
1263-
`@buzz/author`, not a cross-version runtime compatibility promise.
1263+
`route: { version, validate, overlay? }` opts a page
1264+
into versioned route parameters. `overlay` lists the param keys that present a
1265+
dialog over the page rather than a destination: a target differing from the
1266+
current visit only in those keys is written in place, and one whose params are
1267+
overlay keys alone shares its visit with the bare page. Keys apply to object
1268+
params only, and `validate` still admits the whole route. Agents declares
1269+
`overlay: ["provider"]` for its provider dialog. These are host-matched preview
1270+
types through `@buzz/author`, not a cross-version runtime compatibility promise.
12641271

12651272
Browser `#buzz=` addresses and session history support reload and Back/Forward.
12661273
Messages recognize the Buzz link forms `buzz://channel/<id>`,

‎src/app/entity-navigation.test.tsx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,51 @@ it.each(
385385
},
386386
);
387387

388+
// Agents declares `provider` as an overlay param: its provider dialog is page
389+
// state the address carries, never a Back/Forward destination of its own.
390+
it("keeps the Agents provider dialog out of history while its address restores it", async () => {
391+
const current = legacyPageFixture();
392+
await screen.findByRole("navigation", { name: "Pages" });
393+
await waitFor(() =>
394+
expect(current.navigation.snapshot().status).toBe("opened"),
395+
);
396+
const previous = current.navigation.snapshot().entry.id;
397+
const agents: OpenTarget = {
398+
version: 1,
399+
kind: "page",
400+
pluginId: "buzz.agents",
401+
pageId: "agents",
402+
};
403+
const provider: OpenTarget = {
404+
...agents,
405+
route: { version: 1, params: { provider: "test/echo" } },
406+
};
407+
act(() => {
408+
void current.navigation.open(agents);
409+
});
410+
await waitFor(() =>
411+
expect(current.navigation.snapshot().status).toBe("opened"),
412+
);
413+
const length = window.history.length;
414+
let result!: ReturnType<typeof current.navigation.open>;
415+
act(() => {
416+
result = current.navigation.open(provider, { replace: false });
417+
});
418+
expect(await result).toEqual({ status: "opened" });
419+
expect(current.navigation.snapshot().entry.target).toEqual(provider);
420+
expect(window.history.length).toBe(length);
421+
expect(current.navigation.snapshot().canGoForward).toBe(false);
422+
// Back leaves the Agents page; Forward brings it back with the dialog.
423+
act(() => current.navigation.back());
424+
await waitFor(() =>
425+
expect(current.navigation.snapshot().entry.id).toBe(previous),
426+
);
427+
act(() => current.navigation.forward());
428+
await waitFor(() =>
429+
expect(current.navigation.snapshot().entry.target).toEqual(provider),
430+
);
431+
});
432+
388433
// Reminder notifications without an openable message send a page target scoped
389434
// to the reminder's community; it must win over the community selected at click.
390435
it("opens a community-scoped page from another community, but not after leaving it", async () => {

‎src/app/services.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,12 +50,21 @@ export function createServices() {
5050
});
5151
const localAgents = createLocalAgents();
5252
const localActivity = createLocalAgentActivity();
53-
const navigationHost = provideNavigation(ctx);
53+
const pages = new PagesService(ctx);
54+
// A page's declared overlay params present a dialog, never a visit of their own.
55+
const navigationHost = provideNavigation(
56+
ctx,
57+
undefined,
58+
(target) =>
59+
pages
60+
.snapshot()
61+
.find((page) => page.key === `${target.pluginId}/${target.pageId}`)
62+
?.route?.overlay,
63+
);
5464
const navigation = navigationHost.navigation;
5565
const browser = new BrowserService(ctx);
5666
const shortcuts = new ShortcutsService(ctx, undefined, shortcutBindings);
5767
const decisions = new DecisionsService(ctx);
58-
const pages = new PagesService(ctx);
5968
const panels = new PanelsService(ctx);
6069
const accountActions = new AccountActionsService(ctx);
6170
const conversation = new ConversationService(ctx);

‎src/bundled/agents/AgentsPage.tsx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ export function AgentsPage({
192192
: undefined,
193193
)
194194
: localProviderKey;
195-
const setProviderKey = (provider?: string, replace = false) => {
195+
const setProviderKey = (provider?: string) => {
196196
if (!navigation || !navigator) {
197197
setLocalProviderKey(provider);
198198
return;
@@ -205,10 +205,10 @@ export function AgentsPage({
205205
navigator.snapshot().entry.id !== navigation.entryId
206206
)
207207
return;
208-
const target = agentProviderTarget(navigation.target, provider);
209-
void (replace
210-
? navigator.open(target, { replace: true })
211-
: navigator.open(target));
208+
// A dialog is never a Back/Forward destination; the host enforces this too.
209+
void navigator.open(agentProviderTarget(navigation.target, provider), {
210+
replace: true,
211+
});
212212
};
213213
const typeOf = (agent: Agent) =>
214214
types.find((type) => type.key === agent.type);
@@ -603,7 +603,7 @@ export function AgentsPage({
603603
<ProviderDialog
604604
type={types.find((type) => type.key === providerKey)}
605605
finalFocus={newAgentButton}
606-
onClose={() => setProviderKey(undefined, true)}
606+
onClose={() => setProviderKey(undefined)}
607607
/>
608608
)}
609609
</div>

‎src/bundled/agents/index.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ export const apply: PluginModule["apply"] = (ctx) => {
1313
route: {
1414
version: 1,
1515
validate: availableAgentProviderRoute,
16+
// The provider dialog is presentation over this page, never a visit.
17+
overlay: ["provider"],
1618
},
1719
component: ({ navigation }) => (
1820
<AgentsPage

‎src/features/navigation/controller.test.ts‎

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { afterEach, describe, expect, it, vi } from "vitest";
22
import { createNavigationController, NAVIGATION_ABORTED } from "./controller";
33
import { createMemoryHistory, homeTarget } from "./history";
4-
import type { OpenTarget } from "./targets";
4+
import type { OpenTarget, OverlayKeys } from "./targets";
55
const settings: OpenTarget = {
66
version: 1,
77
kind: "settings",
@@ -14,9 +14,9 @@ const page: OpenTarget = {
1414
pageId: "board",
1515
};
1616
const cleanups: (() => void)[] = [];
17-
function setup(capacity = 100) {
17+
function setup(capacity = 100, overlay?: OverlayKeys) {
1818
const history = createMemoryHistory(homeTarget, capacity);
19-
const host = createNavigationController(history);
19+
const host = createNavigationController(history, undefined, overlay);
2020
cleanups.push(host.dispose);
2121
return { host, navigation: host.navigation, history };
2222
}
@@ -272,6 +272,49 @@ describe("navigation attempts over one history driver", () => {
272272
nav.back();
273273
expect(nav.snapshot().entry.target).toEqual(conversation);
274274
});
275+
it("writes a page's declared overlay params in place, whatever the caller asks", async () => {
276+
const overlay: OverlayKeys = (target) =>
277+
target.pluginId === "test" ? ["dialog"] : undefined;
278+
const { host, navigation: nav } = setup(100, overlay);
279+
const dialog: OpenTarget = {
280+
...page,
281+
route: { version: 1, params: { dialog: "provider" } },
282+
};
283+
void nav.open(settings);
284+
void nav.open(page);
285+
const board = nav.snapshot().entry;
286+
const opened = nav.open(dialog, { replace: false });
287+
expect(nav.snapshot().entry.target).toEqual(dialog);
288+
expect(nav.snapshot().entry.id).not.toBe(board.id);
289+
expect(nav.snapshot().canGoForward).toBe(false);
290+
host.complete(nav.snapshot().attempt, { status: "opened" });
291+
await expect(opened).resolves.toEqual({ status: "opened" });
292+
// Back leaves the page; Forward restores it with the dialog its address carries.
293+
nav.back();
294+
expect(nav.snapshot().entry.target).toEqual(settings);
295+
nav.forward();
296+
expect(nav.snapshot().entry.target).toEqual(dialog);
297+
// Closing is written in place too.
298+
void nav.open(page);
299+
expect(nav.snapshot().canGoForward).toBe(false);
300+
nav.back();
301+
expect(nav.snapshot().entry.target).toEqual(settings);
302+
nav.forward();
303+
expect(nav.snapshot().entry.target).toEqual(page);
304+
// A destination param of the same page is still a new visit.
305+
void nav.open({
306+
...page,
307+
route: { version: 1, params: { dialog: "provider", item: "1" } },
308+
});
309+
nav.back();
310+
expect(nav.snapshot().entry.target).toEqual(page);
311+
// Without a declaration, the same params are a destination.
312+
const { navigation: plain } = setup();
313+
void plain.open(page);
314+
void plain.open(dialog, { replace: false });
315+
plain.back();
316+
expect(plain.snapshot().entry.target).toEqual(page);
317+
});
275318
it("uses driver-initiated traversal and bounds the memory driver without inventing history", () => {
276319
const { navigation: nav, history } = setup(2);
277320
void nav.open(settings);

‎src/features/navigation/controller.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import {
33
parseOpenTarget,
44
targetKey,
55
type OpenTarget,
6+
type OverlayKeys,
67
} from "./targets";
78
import type { NavigationEntry, NavigationHistory } from "./history";
89

@@ -71,10 +72,15 @@ export type Navigation = Readonly<{
7172
retry(): Promise<OpenResult>;
7273
}>;
7374

74-
/** The host alone receives completion/cancellation authority. Plugins get Navigation. */
75+
/**
76+
* The host alone receives completion/cancellation authority. Plugins get Navigation.
77+
* `overlay` names the route params a page presents as a dialog, so the controller
78+
* can keep that page's dialogs out of history without knowing the page.
79+
*/
7580
export function createNavigationController(
7681
history: NavigationHistory,
7782
timeoutMs = 15_000,
83+
overlay?: OverlayKeys,
7884
) {
7985
if (!Number.isFinite(timeoutMs) || timeoutMs < 1)
8086
throw new Error("Invalid open timeout");
@@ -279,7 +285,8 @@ export function createNavigationController(
279285
// and never let a page push a Back/Forward destination for it.
280286
const replace =
281287
options?.replace ||
282-
(!invalidAddress && pageKey(target) === pageKey(current.target));
288+
(!invalidAddress &&
289+
pageKey(target, overlay) === pageKey(current.target, overlay));
283290
if (replace) history.replace(target);
284291
else history.push(target);
285292
return active.promise;

‎src/features/navigation/service.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,12 @@ import {
99
} from "./controller";
1010
import { createBrowserHistory } from "./browser-history";
1111
import { createMemoryHistory } from "./history";
12-
import { targetKey, type JsonValue, type OpenTarget } from "./targets";
12+
import {
13+
targetKey,
14+
type JsonValue,
15+
type OpenTarget,
16+
type OverlayKeys,
17+
} from "./targets";
1318
import type { RelayData, RelaySnapshot } from "../relay/service";
1419

1520
export type PageNavigation = Readonly<{
@@ -34,9 +39,12 @@ declare module "@deepseek-ai/cordis" {
3439
export function provideNavigation(
3540
ctx: Context,
3641
host = typeof window === "undefined" ? undefined : window,
42+
overlay?: OverlayKeys,
3743
) {
3844
const controller = createNavigationController(
3945
host ? createBrowserHistory(host) : createMemoryHistory(),
46+
undefined,
47+
overlay,
4048
);
4149
ctx.provide("navigation", controller.navigation);
4250
const positions = new Map<string, JsonValue>();

‎src/features/navigation/targets.test.ts‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
import { describe, expect, it } from "vitest";
2-
import { parseOpenTarget, targetKey, type OpenTarget } from "./targets";
2+
import {
3+
pageKey,
4+
parseOpenTarget,
5+
targetKey,
6+
type OpenTarget,
7+
} from "./targets";
38
const viewer = "a".repeat(64);
49
const conversation = {
510
version: 1,
@@ -104,6 +109,33 @@ describe("open target boundary", () => {
104109
);
105110
},
106111
);
112+
it("keys a page without its declared overlay params, keeping the rest", () => {
113+
const base = {
114+
version: 1,
115+
kind: "page",
116+
pluginId: "a",
117+
pageId: "b",
118+
} as const;
119+
const overlay = () => ["dialog"];
120+
const dialog: OpenTarget = {
121+
...base,
122+
route: { version: 1, params: { dialog: "x" } },
123+
};
124+
expect(pageKey(dialog, overlay)).toBe(pageKey(base, overlay));
125+
expect(pageKey(dialog)).toBe(targetKey(dialog));
126+
expect(
127+
pageKey(
128+
{ ...base, route: { version: 1, params: { dialog: "x", item: "1" } } },
129+
overlay,
130+
),
131+
).toBe(pageKey({ ...base, route: { version: 1, params: { item: "1" } } }));
132+
// Overlay keys apply to object params only.
133+
const text: OpenTarget = {
134+
...base,
135+
route: { version: 1, params: "dialog" },
136+
};
137+
expect(pageKey(text, overlay)).toBe(targetKey(text));
138+
});
107139
it("bounds JSON bytes, depth, entries and non-JSON values; copies nested values", () => {
108140
const page = (params: unknown) => ({
109141
version: 1,

‎src/features/navigation/targets.ts‎

Lines changed: 33 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -217,16 +217,43 @@ export function parseOpenTarget(input: unknown): OpenTarget {
217217
}
218218
}
219219

220+
export type PageTarget = Extract<OpenTarget, { kind: "page" }>;
221+
/** Route param keys a page presents as a dialog over itself, not as a destination. */
222+
export type OverlayKeys = (page: PageTarget) => readonly string[] | undefined;
223+
220224
export function targetKey(target: OpenTarget): string {
221225
return JSON.stringify(parseOpenTarget(target));
222226
}
223227
/**
224-
* What a visit shows, without presentation such as a conversation's `panel`.
225-
* Targets sharing a page key are one visit: a dialog is never a history destination.
228+
* What a visit shows, without presentation: a conversation's `panel`, or the
229+
* route params a page declares as `overlay`. Targets sharing a page key are one
230+
* visit: a dialog is never a history destination.
226231
*/
227-
export function pageKey(target: OpenTarget): string {
232+
export function pageKey(target: OpenTarget, overlay?: OverlayKeys): string {
228233
const parsed = parseOpenTarget(target);
229-
if (parsed.kind !== "conversation") return JSON.stringify(parsed);
230-
const { panel: _panel, ...page } = parsed;
231-
return JSON.stringify(page);
234+
if (parsed.kind === "conversation") {
235+
const { panel: _panel, ...page } = parsed;
236+
return JSON.stringify(page);
237+
}
238+
if (parsed.kind === "page" && parsed.route) {
239+
const keys = overlay?.(parsed) ?? [];
240+
const { params } = parsed.route;
241+
if (
242+
keys.length &&
243+
params &&
244+
typeof params === "object" &&
245+
!Array.isArray(params)
246+
) {
247+
const { route, ...page } = parsed;
248+
const rest = Object.fromEntries(
249+
Object.entries(params).filter(([key]) => !keys.includes(key)),
250+
);
251+
return JSON.stringify(
252+
Object.keys(rest).length
253+
? { ...page, route: { ...route, params: rest } }
254+
: page,
255+
);
256+
}
257+
}
258+
return JSON.stringify(parsed);
232259
}

0 commit comments

Comments
 (0)