Skip to content

Commit fbc3c57

Browse files
matt2eclaude
andcommitted
refactor(navigation): remove the buzz://open locator codec
`buzz://open?target=<json>` is no longer a Buzz link anywhere in buzz-app. `parseBuzzLink` returns null for it, so in message content it is plain text like any other unknown host, and the OS ingress fails it as `invalid-target` through the same null check as `buzz://join` or `buzz://unknown` instead of a dedicated refusal. The codec itself is gone from targets.ts: `SharedTarget`, `parseSharedTarget`, `bindSharedTarget`, `targetLink` and `parseTargetLink`, along with the `shared` format in buzz-links.ts and the `LocatorScope` type it existed for; `OpenTarget` is now the only target shape and `parseOpenTarget` binds scopes directly. Behaviour change: existing in-app `buzz://open` links in old messages stop opening and lose their preview and channel label, and `@buzz/author` no longer exports the `SharedTarget` type. No in-repo plugin imported it. The `#buzz=` browser address, `parseOpenTarget` and browser-history.ts are untouched; they share the JSON target shape, not the URL codec. Copy link already emitted `buzz://message`, so its comment is the only change there. The original Buzz desktop client never had this form. It was introduced in PR #18, refused at the OS boundary in PR #208, and is now removed. MessageLink and ReferenceText keep their message and channel handling with the type narrowing simplified; channelForLink/channelLinkLabel drop the scope parameter they only used for locator community checks. Link Lab demonstrates the same in-app links with `buzz://channel/general` and a `buzz://message` thread link, and docs/deep-links.md, docs/plugin-architecture.md and the Link Lab README describe unknown hosts as rejected everywhere rather than in-app only. One negative test per parser layer pins the removal with a literal `buzz://open?target=…` string: parseBuzzLink returns null, deepLinkStep fails `invalid-target`, message-link-parts leaves it as plain text, and InlineLink renders it as text. The open PR #401 adds a test in entity-navigation.test.tsx that calls bindSharedTarget/parseTargetLink/targetLink; it will conflict with this commit and needs rewriting against parseOpenTarget when it lands. Co-Authored-By: Claude Fable 5.1 <[email protected]> Signed-off-by: Matt Toohey <[email protected]>
1 parent 40c32b4 commit fbc3c57

18 files changed

Lines changed: 110 additions & 304 deletions

‎docs/deep-links.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -29,20 +29,19 @@ digits, `_`, `-`, or `.`, without a leading dot or `..`. Query parameters outsid
2929
a form's grammar are ignored, with their values and any repeats, so a link that
3030
another client decorated still opens; a duplicated known parameter is rejected as
3131
ambiguous. The `channel` forms carry everything in the path and ignore any query.
32-
This leniency does not extend to `buzz://open?target=…` locators, which still
33-
require exactly one `target` key. The same forms work in message content.
32+
The same forms work in message content.
3433

3534
None carries a community, so each binds to the currently selected community and
3635
viewer, and fail `unavailable` when no community is selected or no identity is
37-
known. Every other link, including `buzz://open?target=…`, `buzz://join`,
38-
incomplete entity links, unknown hosts and oversize links, fails as
39-
`invalid-target` and shows "This destination couldn't open" with
40-
**Open Settings**. Unsupported links have no Retry action. Nothing is
41-
auto-joined. A valid address is never authorization: bound targets pass the same
42-
viewer, membership and channel checks as in-app navigation, so a link into a channel
43-
you cannot read still fails `denied`. The frontend expects the canonical lowercase
44-
`buzz:` scheme; the native URL parser can normalize scheme case before delivery,
45-
so uppercase OS input is not guaranteed to be rejected.
36+
known. Every other link, including `buzz://join`, incomplete entity links,
37+
unknown hosts and oversize links, fails as `invalid-target` and shows "This
38+
destination couldn't open" with **Open Settings**. Unsupported links have no
39+
Retry action. Nothing is auto-joined. A valid address is never authorization:
40+
bound targets pass the same viewer, membership and channel checks as in-app
41+
navigation, so a link into a channel you cannot read still fails `denied`. The
42+
frontend expects the canonical lowercase `buzz:` scheme; the native URL parser
43+
can normalize scheme case before delivery, so uppercase OS input is not
44+
guaranteed to be rejected.
4645

4746
The latest arriving link wins. Before readiness, one pending intent is retained;
4847
if identity or community is missing, select a community and use **Retry navigation**.
@@ -65,8 +64,9 @@ explicit Git sections report navigation failure, not an empty successful page.
6564
This deliberately omits the sender's community and identity: recipients must select
6665
the correct community before opening it. Original mobile Buzz requires a UUID
6766
channel identifier; named development channels are supported here but do not imply
68-
mobile compatibility. Existing `buzz://open` locators still preserve community
69-
context for in-app use and remain unsupported at the OS boundary.
67+
mobile compatibility. The app has no link form of its own beyond the Buzz ones:
68+
unknown `buzz://` hosts are rejected everywhere, staying plain text in message
69+
content and failing `invalid-target` at the OS boundary.
7070

7171
## Testing locally
7272

‎docs/plugin-architecture.md‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -486,22 +486,21 @@ into versioned route parameters. These are host-matched preview types through
486486
`@buzz/author`, not a cross-version runtime compatibility promise.
487487

488488
Browser `#buzz=` addresses and session history support reload and Back/Forward.
489-
`targetLink`/`parseTargetLink` define a `buzz://open` locator codec that omits the
490-
sender's viewer; `bindSharedTarget` pins it for an admitted recipient. Messages also
491-
recognize the Buzz link forms `buzz://channel/<id>`, `buzz://channel/<id>/<event>` and
492-
`buzz://message?channel=<id>&id=<event>&thread=<optional-root>`. Buzz links use the
493-
receiving conversation's community and viewer; `buzz://open` locators retain their
494-
community and use the recipient's viewer. Both pass through existing navigation
495-
admission and session ownership checks. Message targets open their
489+
Messages recognize the Buzz link forms `buzz://channel/<id>`,
490+
`buzz://channel/<id>/<event>` and
491+
`buzz://message?channel=<id>&id=<event>&thread=<optional-root>`. Buzz links carry
492+
no community: they bind to the receiving conversation's community and viewer and
493+
pass through existing navigation admission and session ownership checks. The app
494+
has no link form of its own; any other `buzz://` host is rejected everywhere,
495+
staying plain text in messages. Message targets open their
496496
verified thread, reveal the exact message after bounded history loading, and only
497497
then acknowledge navigation. Supplied root hints do not override verified events.
498498
Missing or unavailable messages report failure. Ingress adapters must reuse this
499499
validated target/completion lifecycle; notification clicks
500500
([notifications](notifications.md)) and OS-delivered deep links on desktop
501501
([OS deep links](deep-links.md)) do. The OS ingress accepts only the Buzz link
502-
forms and binds them to the selected community; any other OS link, `buzz://open`
503-
included, fails `invalid-target` through the same failure notice rather than being
504-
dropped.
502+
forms and binds them to the selected community; any other OS link fails
503+
`invalid-target` through the same failure notice rather than being dropped.
505504

506505
Drafts, reading geometry and sidebar view intent remain domain-owned, outside
507506
visit history. Saved sidebar preferences live in the relay session, not in the

‎src/bundled/link-lab/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,9 @@ it does not mark messages read. Other-community previews do not connect or switc
3232
communities on hover. Mentions with signed recipient IDs and unambiguous loaded
3333
names share the hover styling; known local agent identities use a robot icon.
3434
Known channel names in `#channel` text open through the same host link path.
35-
Both legacy channel/message links and versioned `buzz://open` links are supported.
35+
The Buzz link forms `buzz://channel/<id>`, `buzz://channel/<id>/<event>` and
36+
`buzz://message?channel=<id>&id=<event>[&thread=<root>]` are supported; any other
37+
`buzz://` host stays plain text.
3638
The host opens them through scoped navigation; message links reveal the selected
3739
message in its verified thread after bounded history loading. Missing targets
3840
report navigation failure. The lab only previews their appearance.

‎src/bundled/link-lab/index.tsx‎

Lines changed: 9 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@ import { Field } from "../../shared/design-system/ui/Field";
22
import { Input } from "../../shared/design-system/ui/Input";
33
import { useState } from "react";
44
import type { PluginModule } from "../../plugins/api";
5-
import { targetLink } from "../../features/navigation/targets";
65
import { InlineLink, linkKind } from "../links/InlineLink";
76
import styles from "./LinkLab.module.css";
87

@@ -11,21 +10,12 @@ export const apply: PluginModule["apply"] = (ctx) => {
1110
ctx.pages.register({ id: "link-lab", title: "Link Lab", component: LinkLab });
1211
};
1312

14-
const buzz = targetLink({ version: 1, kind: "home" });
15-
const legacyChannel = "buzz://channel/c89a3185-29c5-40db-8284-054536d98b09";
16-
const legacyMessage =
13+
// The Buzz link forms: a channel, a message, and a reply inside a thread.
14+
const general = "buzz://channel/general";
15+
const thread = `buzz://message?channel=general&id=${"2".repeat(64)}&thread=${"2".repeat(64)}`;
16+
const uuidChannel = "buzz://channel/c89a3185-29c5-40db-8284-054536d98b09";
17+
const uuidMessage =
1718
"buzz://message?channel=c89a3185-29c5-40db-8284-054536d98b09&id=9a77911a6e94147b1ce2cdb3c4e87046c67a29f29f3dd25626134621a5f6924b";
18-
const thread = targetLink({
19-
version: 1,
20-
kind: "conversation",
21-
scope: {
22-
viewer: "1".repeat(64),
23-
communityOrigin: "wss://buzz.block.builderlab.xyz",
24-
},
25-
channelId: "general",
26-
messageId: "2".repeat(64),
27-
threadRootId: "2".repeat(64),
28-
});
2919

3020
const serviceSamples = [
3121
["Figma", "https://www.figma.com/design/example"],
@@ -123,13 +113,13 @@ function LinkLab() {
123113
Buzz channels, messages and threads
124114
</span>
125115
<p>
126-
Head back to {preview(buzz, "Buzz")} or pick up{" "}
116+
Head back to {preview(general, "#general")} or pick up{" "}
127117
{preview(thread, "the design discussion")}.
128118
</p>
129119
<p>
130-
Older shared links work too: {preview(legacyChannel)},{" "}
131-
{preview(legacyMessage)}, and{" "}
132-
{preview(`${legacyMessage}&thread=${"2".repeat(64)}`)}.
120+
Bare links show their kind: {preview(uuidChannel)},{" "}
121+
{preview(uuidMessage)}, and{" "}
122+
{preview(`${uuidMessage}&thread=${"2".repeat(64)}`)}.
133123
</p>
134124
</section>
135125
<section>

‎src/bundled/links/InlineLink.test.tsx‎

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,18 @@ import { expect, it } from "vitest";
22
import { renderToStaticMarkup } from "react-dom/server";
33
import { LockIcon, TableIcon } from "../../shared/design-system/icons/index";
44
import styles from "../../shared/InlineReference.module.css";
5-
import { targetLink } from "../../features/navigation/targets";
65
import { InlineLink, LinkLabel, linkKind } from "./InlineLink";
76
import {
87
LinkLabelContext,
98
LinkContentContext,
109
LinkChannelPrivateContext,
1110
} from "../../features/conversation/LinkLabelContext";
1211

13-
it("identifies exact GitHub hosts, ordinary websites, and valid Buzz locators", () => {
12+
it("identifies exact GitHub hosts, ordinary websites, and Buzz entity links", () => {
1413
expect(linkKind("https://github.com/block/buzz")).toBe("github");
1514
expect(linkKind("https://github.com.example.com/block/buzz")).toBe("web");
1615
expect(linkKind("https://example.com/github.com")).toBe("web");
17-
expect(linkKind(targetLink({ version: 1, kind: "home" }))).toBe("buzz");
18-
expect(
19-
linkKind(
20-
targetLink({
21-
version: 1,
22-
kind: "conversation",
23-
scope: {
24-
viewer: "1".repeat(64),
25-
communityOrigin: "https://example.com",
26-
},
27-
channelId: "general",
28-
messageId: "2".repeat(64),
29-
threadRootId: "2".repeat(64),
30-
}),
31-
),
32-
).toBe("thread");
16+
expect(linkKind(`buzz://repo?owner=${"a".repeat(64)}&d=buzz`)).toBe("buzz");
3317
});
3418

3519
it.each([
@@ -63,6 +47,8 @@ it.each([
6347
"javascript:alert(1)",
6448
"data:text/html,hello",
6549
"buzz://unknown",
50+
// The retired in-app locator is an unknown host like any other.
51+
"buzz://open?target=%7B%22version%22%3A1%2C%22kind%22%3A%22home%22%7D",
6652
"not a URL",
6753
])("leaves unsupported destinations as plain text: %s", (href) => {
6854
expect(

‎src/features/conversation/MessageLink.tsx‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -71,14 +71,7 @@ export function MessageLink({
7171
const trigger = useRef<HTMLAnchorElement>(null);
7272
const internal = isBuzzLink(url);
7373
const parsed = internal ? parseBuzzLink(url) : null;
74-
const destination =
75-
parsed?.format === "legacy"
76-
? parsed
77-
: parsed?.format === "shared" &&
78-
parsed.target.kind === "conversation" &&
79-
scope?.slice(0, -65) === parsed.target.scope.communityOrigin
80-
? parsed.target
81-
: undefined;
74+
const destination = parsed?.format === "legacy" ? parsed : undefined;
8275
const preview =
8376
session && destination?.messageId
8477
? { channelId: destination.channelId, messageId: destination.messageId }

‎src/features/messages/MessageMarkdown.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -391,11 +391,11 @@ function PreparedMessageMarkdown({
391391
? sourceRow
392392
: { ...sourceRow, content: prepared.content };
393393
const renderLink = (url: string, label?: string, children?: ReactNode) => {
394-
const channel = channelForLink(url, scope, directory.channels);
394+
const channel = channelForLink(url, directory.channels);
395395
return (
396396
<MessageLink
397397
url={url}
398-
label={label ?? channelLinkLabel(url, scope, directory.channels)}
398+
label={label ?? channelLinkLabel(url, directory.channels)}
399399
registry={extensions?.links}
400400
onOpenLink={onOpenLink}
401401
session={session}

‎src/features/messages/ReferenceText.tsx‎

Lines changed: 4 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -51,36 +51,23 @@ export function useReferenceDirectory(
5151
};
5252
}
5353

54+
/** Buzz links carry no community, so they always name a channel in the receiving one. */
5455
export function channelForLink(
5556
url: string,
56-
scope: string | undefined,
5757
channels: readonly ChannelSummary[],
5858
) {
5959
const parsed = parseBuzzLink(url);
60-
const target =
61-
parsed?.format === "legacy"
62-
? parsed
63-
: parsed?.format === "shared" &&
64-
parsed.target.kind === "conversation" &&
65-
parsed.target.scope.communityOrigin === scope?.slice(0, -65)
66-
? parsed.target
67-
: undefined;
60+
const target = parsed?.format === "legacy" ? parsed : undefined;
6861
return target && channels.find((item) => item.id === target.channelId);
6962
}
7063

7164
export function channelLinkLabel(
7265
url: string,
73-
scope: string | undefined,
7466
channels: readonly ChannelSummary[],
7567
) {
76-
const channel = channelForLink(url, scope, channels);
68+
const channel = channelForLink(url, channels);
7769
const parsed = parseBuzzLink(url);
78-
const target =
79-
parsed?.format === "legacy"
80-
? parsed
81-
: parsed?.format === "shared" && parsed.target.kind === "conversation"
82-
? parsed.target
83-
: undefined;
70+
const target = parsed?.format === "legacy" ? parsed : undefined;
8471
return channel
8572
? `${channel.channelType === "dm" || target?.messageId ? "" : "#"}${channel.name}`
8673
: undefined;

‎src/features/messages/message-copy.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ export function messageCopyLink(
6363
...(row.threadRootId ? { threadRootId: row.threadRootId } : {}),
6464
});
6565
if (target.kind !== "conversation" || !target.messageId) return undefined;
66-
// Public Buzz links bind to the recipient's selected community. Scoped
67-
// buzz://open locators remain supported in-app, but cannot be shared to Buzz.
66+
// Buzz links carry no community or identity: they bind to the recipient's
67+
// selected community, so the sender's scope is deliberately left out.
6868
const params = new URLSearchParams({
6969
channel: target.channelId,
7070
id: target.messageId,

‎src/features/messages/message-link-parts.test.ts‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
import { expect, it } from "vitest";
22
import { messageLinkParts } from "./message-link-parts";
3-
import { targetLink } from "../navigation/targets";
43

5-
it("recognizes bare and wrapped Buzz channel, message, thread and shared links", () => {
4+
it("recognizes bare and wrapped Buzz channel, message and thread links", () => {
65
const urls = [
76
"buzz://channel/general",
87
`buzz://message?channel=general&id=${"a".repeat(64)}`,
98
`buzz://message?channel=general&id=${"a".repeat(64)}&thread=${"b".repeat(64)}`,
10-
targetLink({ version: 1, kind: "home" }),
119
];
1210
for (const url of urls) {
1311
for (const text of [url, `<${url}>`]) {
@@ -17,6 +15,19 @@ it("recognizes bare and wrapped Buzz channel, message, thread and shared links",
1715
}
1816
}
1917
});
18+
it("leaves the retired buzz://open locator as plain text, bare or wrapped", () => {
19+
const locator =
20+
"buzz://open?target=%7B%22version%22%3A1%2C%22kind%22%3A%22home%22%7D";
21+
for (const content of [
22+
`See ${locator}.`,
23+
`See <${locator}>.`,
24+
`See [home](${locator}).`,
25+
]) {
26+
const parts = messageLinkParts(content);
27+
expect(parts.some((part) => part.url)).toBe(false);
28+
expect(parts.map((part) => part.text).join("")).toBe(content);
29+
}
30+
});
2031
it("keeps Buzz links with unknown query parameters as links rather than plain text", () => {
2132
const url = `buzz://message?channel=general&id=${"a".repeat(64)}&foo=bar`;
2233
for (const text of [url, `<${url}>`, `[Reply](${url})`]) {

0 commit comments

Comments
 (0)