@anchrd/intel 0.59.0

package/ui/src/tools/tools.tsx

@@ -0,0 +1,546 @@
+import { serverOf, type ToolCapability, type ToolServer } from "@contract/tool.ts";
+import { useQuery } from "@tanstack/react-query";
+import { useRouterState } from "@tanstack/react-router";
+import {
+  AlertTriangle,
+  ChevronRight,
+  HelpCircle,
+  PlugZap,
+  ShieldOff,
+  Timer,
+  Wrench,
+} from "lucide-react";
+import * as React from "react";
+import { Button } from "@/components/ui/button";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
+import type { I18n } from "@/i18n/i18n.types.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+import { selectedFrom } from "@/router/selection-search.ts";
+
+interface ToolGroup {
+  // The handle the portal named, or `null` for the box holding what no named server carries.
+  handle: string | null;
+  label: string;
+  items: ToolCapability[];
+}
+
+/**
+ * The tools of one catalog, under the servers the portal itself named (#212).
+ *
+ * ⚠️ The grouping comes from `GET /api/v1/tools/servers`, never from the tool name alone. The name
+ * cannot say where the server part ends — `intel_flow_get` reads as `intel` + `flow_get` and as
+ * `intel_flow` + `get` — so this screen matches the portal's own handles with the same `serverOf`
+ * the delegation is cut with, longest match wins. The earlier reading, a cut at a separator, was
+ * shipped twice and was wrong twice: at `__` it put all 92 tools of the running installation in one
+ * box, because the portal writes a single underscore (#106), and at `_` it would break the first
+ * server whose slug carries one (#107, closed for that reason).
+ *
+ * ⚠️ A tool that matches no named handle is NOT dropped. It goes into its own box: the portal's
+ * management tools (`portal_list_servers`) live there, because the portal does not list itself as
+ * an upstream, and so does anything from a server the directory failed to mention. Hiding those
+ * would make the screen quietly disagree with `tools/list` — and the count on the lid is what the
+ * reader compares against the portal.
+ *
+ * The order is the portal's own: a group appears where its first tool appears, because the portal
+ * returns a server's tools together and sorting would replace its answer with a preference. Only
+ * the unattributed box is forced last — it is a remainder, not a server, and it must not lead.
+ */
+function groupByServer(
+  items: ToolCapability[],
+  servers: ToolServer[],
+  unlistedLabel: string,
+): ToolGroup[] {
+  const named = new Map(servers.map((server) => [server.handle, server.name]));
+  const groups = new Map<string, ToolGroup>();
+  const unlisted: ToolGroup = { handle: null, label: unlistedLabel, items: [] };
+  for (const item of items) {
+    const handle = serverOf(item.name, named.keys());
+    if (handle === null) {
+      unlisted.items.push(item);
+      continue;
+    }
+    // The server's display name, not its handle: `notion` is what the wire says, and what the
+    // portal calls it is what the reader knows it by.
+    const group = groups.get(handle) ?? { handle, label: named.get(handle) ?? handle, items: [] };
+    group.items.push(item);
+    groups.set(handle, group);
+  }
+  return unlisted.items.length > 0 ? [...groups.values(), unlisted] : [...groups.values()];
+}
+
+// Signed in to Intel is signed in to the portal, so the sign-in is attempted at most once per
+// visit. A second attempt after a refusal would be a redirect loop with an unchanging answer, and
+// the marker in the URL only survives until the next navigation — the browser session remembers it
+// instead (#60).
+//
+// ⚠️ It records that an attempt was STARTED, never that one was answered (#426). A sign-in that
+// crashed on the way leaves exactly the same note as one that came back, so nothing may read it as
+// a verdict about anybody: it only keeps the screen from walking in a circle on its own, and what
+// the reader is told comes from the marker in the URL instead. That is the whole distinction — the
+// note is never cleared to make a second attempt possible; the button is what makes one possible.
+const SignInAttemptKey = "intel.portal-sign-in-attempted";
+
+/**
+ * What came back from the silent walk — and "nothing" is one of the answers (#426).
+ *
+ * The marker in the URL is the only thing that ever says why the walk ended, and it is absent in two
+ * situations that look identical from here: the attempt never ran, or it broke before it could
+ * return. Neither is a decision about access, so neither may borrow the sentence that describes one
+ * — the rule `packages/intel/ui/CLAUDE.md` keeps from #350: **a missing statement is a reason to say less,
+ * never to refuse more.** Saying "no access" for `none` sent a reader hunting through portal
+ * policies while the sign-in had answered 500 (#425).
+ */
+type PortalAnswer = "refused" | "expired" | "failed" | "none";
+
+function portalAnswerOf(connectError: string | null): PortalAnswer {
+  if (connectError === null) return "none";
+  if (connectError === "portal_sign_in_expired") return "expired";
+  // The two codes Intel itself writes when somebody was actually turned away — by the portal, or by
+  // Gate before the portal was ever asked. Every other marker is machinery, not policy.
+  return connectError === "portal_sign_in_refused" || connectError === "permission_required"
+    ? "refused"
+    : "failed";
+}
+
+// Reading `sessionStorage` throws outright in a few privacy modes, so the guard is a try, not a
+// feature check. Losing the note costs one extra redirect, and the marker the refusal leaves in the
+// URL still ends the walk — it must never cost the screen.
+function attemptStore(): Storage | null {
+  try {
+    return typeof window === "undefined" ? null : window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+// The catalog is one live `tools/list` with the signed-in user's own portal token. Nothing here is
+// stored, mirrored or administered — the screen shows what the portal answers and nothing else.
+export function Tools() {
+  const { data } = useIntelRouterContext();
+  const i18n = useI18n();
+  const catalog = useQuery({ queryKey: ["tools"], queryFn: () => data.listTools() });
+  // The servers behind that same live list (D30). Its own query, and its own failure: a portal that
+  // answers tools but no directory still has a usable screen, it just has no boxes to put them in.
+  // ⚠️ No retry on this one, and that is a decision about the screen rather than about the request.
+  // The tools are held back until the directory has answered, so every further attempt is time
+  // somebody spends in front of the word "Loading" — and a retry does not even have to happen: a
+  // React Query retry is PAUSED while the tab is unfocused, so a screen waiting on one can stay
+  // "Loading" for as long as the reader is looking elsewhere. A portal that offers no directory
+  // answers the same 502 every time anyway; one attempt settles it, and what follows is the list
+  // plus the sentence saying why it is not sorted.
+  const servers = useQuery({
+    queryKey: ["tool-servers"],
+    queryFn: () => data.listToolServers(),
+    retry: false,
+  });
+  // A hit from the header search arrives as `?select=<tool name>`, and the row it names opens with
+  // the list. Nothing else about the row changes: it is still only a disclosure.
+  const requested = useRouterState({ select: (state) => selectedFrom(state.location.search) });
+  // The silent sign-in returns here with a marker when it failed. The value comes from outside
+  // and could carry provider detail, so it is never rendered — it is only compared against the
+  // codes Intel itself writes, to tell "you may not" from "the sign-in broke" (#93): the first is
+  // a sentence about access, the second must not masquerade as one.
+  const connectError =
+    typeof window === "undefined"
+      ? null
+      : new URLSearchParams(window.location.search).get("connectError");
+  const answer = portalAnswerOf(connectError);
+  // What the screen DID about that answer, which is a third thing beside the catalog and the marker.
+  //
+  // ⚠️ Only `none` starts undecided. `useEffect` runs after the paint, so a state that always began
+  // at `deciding` would push a "Loading" frame in front of all four notices — and three of them are
+  // already settled at the first render, because their answer stands in the URL. It would flash at
+  // exactly the readers who just arrived out of a redirect. `none` is the one that genuinely has to
+  // wait: its walk starts one tick after the catalog arrives, and "we do not know" in between is a
+  // sentence the screen takes back immediately.
+  const [walk, setWalk] = React.useState<"deciding" | "running" | "stopped">(
+    answer === "none" ? "deciding" : "stopped",
+  );
+
+  const startSignIn = React.useCallback(() => {
+    // ⚠️ `setItem`, and the marker is not cleared anywhere on this path. Pressing the button STARTS
+    // an attempt, which is the only thing the marker ever claims — clearing it would buy the click
+    // nothing (no code in this path reads it) and cost the next visit: an attempt that dies without
+    // ever coming back with a marker would be followed by a silent redirect nobody asked for, on a
+    // screen that has just said it does not understand what is happening. The second attempt this
+    // browser session owes its reader is this button, never a re-armed guard.
+    attemptStore()?.setItem(SignInAttemptKey, "1");
+    setWalk("running");
+    data.startPortalSignIn("/tools");
+  }, [data]);
+
+  // ⚠️ Nobody is asked to start this. The portal sign-in is a browser redirect, so the screen
+  // begins it itself the moment the catalog says there is no portal session yet — that is the whole
+  // of what replaced the "Connect the portal" button.
+  React.useEffect(() => {
+    if (!catalog.data) return;
+    const attempts = attemptStore();
+    if (catalog.data.portalConnected) {
+      // An answered sign-in frees the next one: when the token later expires beyond renewal, the
+      // same silent walk runs again rather than stopping at a screen.
+      attempts?.removeItem(SignInAttemptKey);
+      return;
+    }
+    if (answer !== "none" || attempts?.getItem(SignInAttemptKey)) {
+      setWalk("stopped");
+      return;
+    }
+    attempts?.setItem(SignInAttemptKey, "1");
+    setWalk("running");
+    data.startPortalSignIn("/tools");
+  }, [catalog.data, data, answer]);
+
+  return (
+    <div className="min-h-full p-8">
+      <div className="mx-auto w-full max-w-4xl space-y-5">
+        {catalog.isPending ? (
+          <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+        ) : catalog.isError ? (
+          // Unreachable is not empty: the portal did not answer, so Intel knows nothing about this
+          // user's tools rather than knowing there are none.
+          <Notice
+            alert
+            icon={<PlugZap aria-hidden="true" className="mx-auto size-8 text-destructive" />}
+            title={i18n.t("tools.unreachable")}
+            help={i18n.t("tools.unreachableHelp")}
+          >
+            <Button variant="outline" onClick={() => void catalog.refetch()}>
+              {i18n.t("common.retry")}
+            </Button>
+          </Notice>
+        ) : !catalog.data.portalConnected ? (
+          walk === "deciding" ? (
+            <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+          ) : walk === "running" ? (
+            <p className="text-sm text-muted-foreground">{i18n.t("tools.signingIn")}</p>
+          ) : (
+            <PortalNotice answer={answer} i18n={i18n} onRetry={startSignIn} />
+          )
+        ) : catalog.data.items.length === 0 ? (
+          <Notice
+            icon={<Wrench aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
+            title={i18n.t("tools.empty")}
+            help={i18n.t("tools.emptyHelp")}
+          />
+        ) : servers.isPending ? (
+          // The tools are here and the servers are not yet. Showing the flat list first and
+          // reshuffling it a moment later would be a screen that moves under the reader's hand.
+          <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+        ) : (
+          <ToolCatalogView
+            items={catalog.data.items}
+            servers={servers.isError ? [] : servers.data.items}
+            i18n={i18n}
+            requested={requested}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The end of the silent walk, in the words of whatever ended it — one sentence per answer, and no
+ * sentence shared between two of them (#426).
+ *
+ * ⚠️ Only `refused` is a statement about ACCESS, and only it is a dead end: there is nothing the
+ * reader could press that would change the answer, so nothing is offered. The other two are the
+ * machinery and the silence, and both are worth another attempt — which is the button the screen
+ * lacked entirely while the marker in `sessionStorage` made the first attempt the only one.
+ */
+function PortalNotice({
+  answer,
+  i18n,
+  onRetry,
+}: {
+  answer: PortalAnswer;
+  i18n: I18n;
+  onRetry: () => void;
+}) {
+  if (answer === "refused") {
+    return (
+      <Notice
+        alert
+        icon={<ShieldOff aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
+        title={i18n.t("tools.noAccess")}
+        help={i18n.t("tools.noAccessHelp")}
+      />
+    );
+  }
+  // Ran out of time on the consent screen. Nothing is broken and nobody was refused, so neither of
+  // the other sentences fits (#95).
+  if (answer === "expired") {
+    return (
+      <Notice
+        icon={<Timer aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
+        title={i18n.t("tools.connectExpired")}
+        help={i18n.t("tools.connectExpiredHelp")}
+      >
+        <Button variant="outline" onClick={onRetry}>
+          {i18n.t("tools.connectRetry")}
+        </Button>
+      </Notice>
+    );
+  }
+  // A marker that is neither of the two access answers is machinery, not policy: the sign-in broke
+  // before anyone could be allowed or refused. Saying "no access" here sent the last reader hunting
+  // through Access policies while the real fault sat in a failed client registration (#93).
+  if (answer === "failed") {
+    return (
+      <Notice
+        alert
+        icon={<PlugZap aria-hidden="true" className="mx-auto size-8 text-destructive" />}
+        title={i18n.t("tools.connectFailed")}
+        help={i18n.t("tools.connectFailedHelp")}
+      >
+        <Button variant="outline" onClick={onRetry}>
+          {i18n.t("tools.connectRetry")}
+        </Button>
+      </Notice>
+    );
+  }
+  // No marker at all, and an attempt already made in this browser session: it never came back. The
+  // screen says exactly that — not "no access", which is a decision nobody made here.
+  return (
+    <Notice
+      icon={<HelpCircle aria-hidden="true" className="mx-auto size-8 text-muted-foreground" />}
+      title={i18n.t("tools.connectUnknown")}
+      help={i18n.t("tools.connectUnknownHelp")}
+    >
+      <Button variant="outline" onClick={onRetry}>
+        {i18n.t("tools.connectRetry")}
+      </Button>
+    </Notice>
+  );
+}
+
+/**
+ * The catalog, under the portal's servers where there are any.
+ *
+ * ⚠️ No directory, no boxes — and the screen says why instead of inventing them. A portal that does
+ * not offer `portal_list_servers`, or whose answer Intel cannot read, makes `/tools/servers` fail,
+ * and every alternative to this sentence is a guess: a cut at an underscore, or the one box called
+ * "Company portal" that held all 92 tools of the running installation (#106). The tools are all
+ * here, in the order the portal answered them; only the grouping is missing.
+ */
+function ToolCatalogView({
+  items,
+  servers,
+  i18n,
+  requested,
+}: {
+  items: ToolCapability[];
+  servers: ToolServer[];
+  i18n: I18n;
+  requested: string | null;
+}) {
+  if (servers.length === 0) {
+    return (
+      <>
+        <section className="rounded-xl border border-dashed bg-card px-5 py-4">
+          <h2 className="text-sm font-semibold">{i18n.t("tools.ungrouped")}</h2>
+          <p className="mt-1 text-sm text-muted-foreground">{i18n.t("tools.ungroupedHelp")}</p>
+        </section>
+        {/* Open, not a lid: with no server to name, a closed box would hide the whole catalog
+            behind a word that says nothing. */}
+        <section className="overflow-hidden rounded-xl border bg-card shadow-sm">
+          <ToolRows items={items} i18n={i18n} requested={requested} />
+        </section>
+        <p className="text-xs text-muted-foreground">{i18n.t("tools.liveNote")}</p>
+      </>
+    );
+  }
+  return (
+    <>
+      <div className="space-y-3">
+        {groupByServer(items, servers, i18n.t("tools.originUnlisted")).map((group) => (
+          <ServerGroup
+            key={group.handle ?? ""}
+            group={group}
+            note={group.handle === null ? i18n.t("tools.originUnlistedHelp") : null}
+            i18n={i18n}
+            requested={requested}
+          />
+        ))}
+      </div>
+      <p className="text-xs text-muted-foreground">{i18n.t("tools.liveNote")}</p>
+    </>
+  );
+}
+
+function Notice({
+  icon,
+  title,
+  help,
+  alert,
+  children,
+}: {
+  icon: React.ReactNode;
+  title: string;
+  help: string;
+  alert?: boolean;
+  children?: React.ReactNode;
+}) {
+  return (
+    <section
+      {...(alert ? { role: "alert" } : {})}
+      className="rounded-xl border border-dashed bg-card p-12 text-center"
+    >
+      {icon}
+      <h2 className="mt-4 font-semibold">{title}</h2>
+      <p className="mx-auto mt-2 max-w-lg text-sm text-muted-foreground">{help}</p>
+      {children ? <div className="mt-5">{children}</div> : null}
+    </section>
+  );
+}
+
+// One server, one box, closed until asked. Closed is the point: a hundred rows spread over a
+// handful of servers is a list nobody reads, and which server a tool speaks to is the first thing
+// somebody wants to know about it (#99).
+function ServerGroup({
+  group,
+  note,
+  i18n,
+  requested,
+}: {
+  group: ToolGroup;
+  // Why this box exists at all, for the one box that is not a server. A group named by the portal
+  // needs no explanation; the remainder does, or it reads as a server called something odd.
+  note: string | null;
+  i18n: I18n;
+  requested: string | null;
+}) {
+  // A hit from the header search names a tool, not a server, and the box it sits in has to open
+  // with it — otherwise Enter on a hit lands on a screen where nothing happened.
+  const holdsRequested = group.items.some((item) => item.name === requested);
+  const destructive = group.items.filter((item) => item.annotations.destructiveHint).length;
+  // ⚠️ One key, not a `…One` beside a `…Many` (#605): the catalog carries a wording that fits every
+  // number, so nothing here branches on the count. The branch that used to stand here is what the
+  // rule in `packages/intel/ui/CLAUDE.md` forbids — it puts the inflection into the component and into
+  // every future language.
+  const count = i18n.t("tools.toolCount", { count: group.items.length });
+  // The badges beside the name read as one run-on word when a screen reader concatenates them
+  // ("wiki1 tool"), so the control says its own name instead of being read off its contents.
+  const spoken = [`${i18n.t("tools.origin")}: ${group.label}`, count];
+  if (destructive > 0) spoken.push(i18n.t("tools.destructiveCount", { count: destructive }));
+
+  return (
+    <Collapsible defaultOpen={holdsRequested} asChild>
+      <section className="overflow-hidden rounded-xl border bg-card shadow-sm">
+        <CollapsibleTrigger
+          aria-label={spoken.join(", ")}
+          className="group flex w-full items-center gap-3 px-5 py-4 text-left outline-none hover:bg-muted/50 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
+        >
+          <ChevronRight
+            aria-hidden="true"
+            className="size-4 shrink-0 text-muted-foreground transition-transform group-data-[state=open]:rotate-90"
+          />
+          <span className="min-w-0 flex-1">
+            <span className="block truncate text-sm font-semibold">{group.label}</span>
+          </span>
+          {/* Closed, the box hides every destructive badge inside it. The count says so on the lid
+              rather than making somebody open each server to find out. */}
+          {destructive > 0 && (
+            <span className="inline-flex shrink-0 items-center gap-1.5 rounded-full bg-destructive/10 px-2 py-0.5 text-xs text-destructive">
+              <AlertTriangle aria-hidden="true" className="size-3.5" />
+              {i18n.t("tools.destructiveCount", { count: destructive })}
+            </span>
+          )}
+          <span className="shrink-0 text-xs text-muted-foreground">{count}</span>
+        </CollapsibleTrigger>
+        <CollapsibleContent className="border-t">
+          {note && (
+            <p className="border-b bg-muted/50 px-5 py-3 text-xs text-muted-foreground">{note}</p>
+          )}
+          <ToolRows items={group.items} i18n={i18n} requested={requested} />
+        </CollapsibleContent>
+      </section>
+    </Collapsible>
+  );
+}
+
+// The rows themselves, with or without a box around them: the ungrouped screen shows the same list
+// without a lid, and duplicating it there is how the two would drift apart.
+function ToolRows({
+  items,
+  i18n,
+  requested,
+}: {
+  items: ToolCapability[];
+  i18n: I18n;
+  requested: string | null;
+}) {
+  return (
+    <ul className="divide-y">
+      {items.map((capability) => (
+        <li key={capability.name}>
+          <ToolEntry capability={capability} i18n={i18n} open={capability.name === requested} />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// One tool, one disclosure. The row is the only control in the list: it opens the schema and does
+// nothing else — enabling, sharing or permitting a tool happens in the portal, never here.
+function ToolEntry({
+  capability,
+  i18n,
+  open,
+}: {
+  capability: ToolCapability;
+  i18n: I18n;
+  open: boolean;
+}) {
+  return (
+    <Collapsible defaultOpen={open}>
+      <CollapsibleTrigger className="group flex w-full items-start gap-4 px-5 py-3 text-left outline-none hover:bg-muted/50 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring">
+        <ChevronRight
+          aria-hidden="true"
+          className="mt-0.5 size-4 shrink-0 text-muted-foreground transition-transform group-data-[state=open]:rotate-90"
+        />
+        <span className="min-w-0 flex-1">
+          <span className="flex flex-wrap items-center gap-2">
+            <span className="text-sm font-medium">{capability.title ?? capability.name}</span>
+            {capability.annotations.destructiveHint && (
+              <span className="inline-flex items-center gap-1.5 rounded-full bg-destructive/10 px-2 py-0.5 text-xs text-destructive">
+                <AlertTriangle aria-hidden="true" className="size-3.5" />
+                {i18n.t("tools.destructiveShort")}
+              </span>
+            )}
+          </span>
+          {/* The namespaced name is what a flow references, so it stays readable — but only where
+              it is not already the heading of the row. */}
+          {capability.title && (
+            <span className="mt-1 block truncate font-mono text-xs text-muted-foreground">
+              {capability.name}
+            </span>
+          )}
+        </span>
+      </CollapsibleTrigger>
+      {/* ⚠️ The description belongs here, not in the closed row. Held open it was the whole reason
+          the list could not be scanned: a paragraph per tool, a hundred times over. */}
+      <CollapsibleContent className="space-y-3 px-5 pb-4 pl-13">
+        {capability.description && (
+          <p className="text-xs text-muted-foreground">{capability.description}</p>
+        )}
+        <Schema label={i18n.t("tools.inputSchema")} value={capability.inputSchema} />
+        {capability.outputSchema && (
+          <Schema label={i18n.t("tools.outputSchema")} value={capability.outputSchema} />
+        )}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+function Schema({ label, value }: { label: string; value: Record<string, unknown> }) {
+  return (
+    <div>
+      <p className="text-xs font-medium">{label}</p>
+      <pre className="mt-1 max-h-80 overflow-auto rounded-md bg-muted p-3 text-xs">
+        {JSON.stringify(value, null, 2)}
+      </pre>
+    </div>
+  );
+}

package/ui/src/user-name/user-name.ts

@@ -0,0 +1,61 @@
+import type { SessionUser } from "@contract/contract.ts";
+import { useQuery } from "@tanstack/react-query";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+/**
+ * The signed-in person, from the one query the shell already makes.
+ *
+ * ⚠️ The same query key the user footer uses, so asking here costs no second request — and the two
+ * can never disagree about who is signed in.
+ */
+export function useSessionUser(): SessionUser | null {
+  const { data } = useIntelRouterContext();
+  const session = useQuery({ queryKey: ["session"], queryFn: () => data.getSession() });
+  return session.data ?? null;
+}
+
+/** What a person is CALLED, by the same rule the user footer follows: the name, or the address. */
+export function displayNameOf(user: SessionUser): string {
+  return user.name ?? user.email;
+}
+
+/**
+ * The display name behind a user id, WITHOUT a request — or `null` where this browser cannot say
+ * from what it already holds.
+ *
+ * ⚠️ It answers for exactly one id, and that is a choice rather than a limit: the signed-in
+ * person's, out of the session the shell already fetched. Intel CAN name a foreign id — the bundled
+ * resolution over `directory_resolve` does it (`#700`) — but not from here. A hook that resolved a
+ * single id would be called once per row and once per circle, and one screen would open one request
+ * per person instead of one for all of them.
+ *
+ * ⚠️ So a caller that needs foreign names asks for them where the ids are already in one place, and
+ * layers the two: this hook first, the resolved map second. `useAssigneeLabel` is the worked
+ * example.
+ *
+ * ⚠️ Never fall back to the id. An id under a name is not an answer to "who made this", it is the
+ * question again in smaller type — and it would leak an identifier onto a screen that has no reason
+ * to carry one. Callers show `node.someUser` instead (#258).
+ */
+export function useUserName(userId: string | null): string | null {
+  const me = useSessionUser();
+  if (userId === null || me === null || me.id !== userId) return null;
+  return displayNameOf(me);
+}
+
+/**
+ * The one or two letters that stand for a name in a circle.
+ *
+ * ⚠️ Lives here rather than beside the circle that first needed it: two surfaces now draw the same
+ * circle — the access summary and a task's assignee — and two copies of this would drift into two
+ * different abbreviations of the same person.
+ */
+export function initials(value: string): string {
+  const parts = value
+    .replace(/@.*$/, "")
+    .split(/[\s._+-]+/)
+    .filter(Boolean);
+  if (parts.length === 0) return "?";
+  if (parts.length === 1) return (parts[0]?.slice(0, 2) ?? "?").toUpperCase();
+  return `${parts[0]?.[0] ?? ""}${parts.at(-1)?.[0] ?? ""}`.toUpperCase();
+}

package/ui/src/verbatim/verbatim.tsx

@@ -0,0 +1,68 @@
+import { createReactBlockSpec } from "@blocknote/react";
+import { createContext, useContext } from "react";
+
+/**
+ * A piece of the document the editor cannot show, kept exactly as it was written (#826).
+ *
+ * ⚠️ **This is the frontmatter's way, generalised.** #657 gave the head its own path because
+ * `blocksToMarkdownLossy` had destroyed it: what the editor does not understand it rewrites into
+ * what it does, and `payload.markdown` is what the search reads. The head was the only construct
+ * with that protection; everything else the editor did not know still lost its shape on the first
+ * open-and-save, and nothing anywhere went red.
+ *
+ * ⚠️ **`raw` is the exact source text, never something parsed.** Whatever went in comes back out,
+ * byte for byte. A block that carried a parsed structure would turn every gap in the parser into
+ * data loss at the next save, which is the trap the head already avoids.
+ */
+export const VerbatimBlockType = "verbatim";
+
+const VERBATIM_PROPS = { raw: { default: "" } } as const;
+
+/**
+ * The one word the block says. It travels in a context for the same reason the head's two do: a
+ * block is rendered by the editor, not by a view that could reach the catalogue.
+ */
+const VerbatimContext = createContext<string>("Kept as written");
+
+export const VerbatimProvider = VerbatimContext.Provider;
+
+export function VerbatimBlock({ raw }: { raw: string }) {
+  const label = useContext(VerbatimContext);
+  return (
+    <div
+      // The editor owns the text around this; the block itself is not typed into. What is in here
+      // is the author's own text, and an editor that cannot draw it must not let anybody change it
+      // by accident either.
+      contentEditable={false}
+      data-verbatim=""
+      className="w-full overflow-x-auto rounded-md bg-muted/40 px-3 py-2"
+    >
+      {/* ⚠️ Named rather than silent, which is the whole difference to the state before: a piece
+          that vanishes without a word is what #826 is about. */}
+      <p className="mb-1 text-xs text-muted-foreground">{label}</p>
+      <pre className="whitespace-pre font-mono text-xs">
+        <code>{raw}</code>
+      </pre>
+    </div>
+  );
+}
+
+export const verbatimSpec = createReactBlockSpec(
+  {
+    type: VerbatimBlockType,
+    propSchema: VERBATIM_PROPS,
+    content: "none",
+  },
+  {
+    render: (props) => <VerbatimBlock raw={String(props.block.props.raw)} />,
+    // ⚠️ The net under `blocksToMarkdown`, for every path that does not go through it. Without a
+    // serialiser BlockNote falls back to the RENDERED DOM, and the label would end up in the
+    // document in place of the text. `<pre><code>` rather than a bare `<pre>`: measured in #657, a
+    // bare one survives the HTML export and is then dropped by the HTML-to-markdown step.
+    toExternalHTML: (props) => (
+      <pre>
+        <code>{String(props.block.props.raw)}</code>
+      </pre>
+    ),
+  },
+);