@anchrd/intel 0.59.0

package/ui/src/data/intel-data-provider/intel-data-provider.types.ts

@@ -0,0 +1,266 @@
+import type {
+  BoardGetInput,
+  BoardTaskCreateInput,
+  BoardTaskUpdateInput,
+  BoardUpdateInput,
+  BoardView,
+  DirectoryPersonList,
+} from "@contract/board.ts";
+import type { BundleImportResult } from "@contract/bundle.ts";
+import type { SessionUser } from "@contract/contract.ts";
+import type { FeedListResponse } from "@contract/feed.ts";
+import type {
+  ArchiveFlowInput,
+  CreateFlowInput,
+  Flow,
+  FlowDocument,
+  FlowList,
+  FlowPublishPreview,
+  FlowRequirements,
+  FlowValidation,
+  FlowVersionList,
+  ListFlowsInput,
+  PreviewFlowPublishInput,
+  PublishFlowInput,
+  PurgeFlowInput,
+  PurgeFlowResult,
+  RelationGraph,
+  RelationGraphScope,
+  SaveFlowVersionInput,
+  UpdateFlowInput,
+} from "@contract/flow.ts";
+import type {
+  CompleteFlowRunStepInput,
+  FlowRunHistory,
+  FlowRunList,
+  FlowRunStep,
+  ListFlowRunsInput,
+  StartFlowRunInput,
+} from "@contract/flow-run.ts";
+import type {
+  ArchiveNodeInput,
+  CreateNodeInput,
+  ListNodesInput,
+  Node,
+  NodeDocument,
+  NodeGraph,
+  NodeKind,
+  NodeLinkList,
+  NodeList,
+  NodeTable,
+  NodeVersionList,
+  PurgeNodeInput,
+  PurgeNodePreviewInput,
+  PurgeNodeResult,
+  ReindexResult,
+  ResolveNodeLinksInput,
+  ResolveNodeLinksResult,
+  SaveAttachmentInput,
+  SaveNodeVersionInput,
+  SearchInput,
+  SearchResult,
+  UpdateNodeInput,
+} from "@contract/node.ts";
+import type {
+  ResourceGrantList,
+  RevokeFlowGrantInput,
+  RevokeGrantInput,
+  RevokeGrantResult,
+  ShareFlowInput,
+  ShareInput,
+  ShareResult,
+} from "@contract/share.ts";
+import type {
+  AppendTableRowsInput,
+  AppendTableRowsResult,
+  DefineTableInput,
+  RedefineTableInput,
+} from "@contract/table.ts";
+import type { ToolCatalog, ToolServerCatalog } from "@contract/tool.ts";
+
+// One row of the shared tree. Nodes and Flows share the folder, not their nature (ADR-0004), so
+// this is a union that keeps each side's record whole — never a merged "node" that is a bit of both.
+// ⚠️ `openable` means "has something to expand that THIS reader may see" (#59) — not "is of a kind
+// that can be expanded". The difference is the whole point: an arrow on a row with nothing beneath
+// it promises content that expanding does not deliver.
+export type TreeEntry =
+  | {
+      type: "node";
+      id: string;
+      title: string;
+      kind: NodeKind;
+      openable: boolean;
+      node: Node;
+    }
+  | { type: "flow"; id: string; title: string; kind: "flow"; openable: boolean; flow: Flow };
+
+export interface IntelDataProvider {
+  getSession(): Promise<SessionUser>;
+  /**
+   * Rebuild the whole search index (`intel/admin`).
+   *
+   * ⚠️ Answers as soon as the work is QUEUED, not when it is done — `queued` counts the nodes that
+   * will be read again, and the index catches up behind it. A screen that said "finished" here
+   * would be reporting the wrong thing.
+   */
+  reindexNodes(): Promise<ReindexResult>;
+  /**
+   * One board, in one answer: its columns and every card the caller may see, without the card
+   * bodies (#648).
+   *
+   * ⚠️ **One call, not one per card.** A screen that fetched each card separately would look
+   * identical and is the reason this endpoint exists — the test that guards it counts requests
+   * rather than pixels.
+   */
+  getBoard(input: BoardGetInput): Promise<BoardView>;
+  updateBoard(input: BoardUpdateInput): Promise<BoardView>;
+  createBoardTask(input: BoardTaskCreateInput): Promise<BoardView>;
+  // Every write answers with the WHOLE board rather than the row it changed: a drag moves one card
+  // and shifts nothing else, but a column's contents are what the screen draws, and re-deriving
+  // them from a single row is where a second, quietly different truth would start.
+  updateBoardTask(boardId: string, input: BoardTaskUpdateInput): Promise<BoardView>;
+  /**
+   * Who a card on THIS board may be given to (#700, D70).
+   *
+   * ⚠️ Board-scoped, and the same query against two boards can give two different answers. Only
+   * people who can actually open this one are offered.
+   */
+  searchBoardAssignees(boardId: string, query: string): Promise<DirectoryPersonList>;
+  /**
+   * What the people already on cards are called (#258, #700).
+   *
+   * ⚠️ NOT board-scoped, unlike the search above: somebody whose access was withdrawn is still who
+   * the card belongs to, and a card that read as unassigned would be a worse answer than the truth.
+   * Ids that cannot be named are absent from the answer rather than reported.
+   */
+  resolveNames(ids: string[]): Promise<DirectoryPersonList>;
+  listNodes(input?: Partial<ListNodesInput>): Promise<NodeList>;
+  // One level of the shared tree: the documents and the flows filed in the same folder, in one
+  // sorted list. Per level rather than recursive, so opening a folder is what costs a request.
+  listTreeChildren(parentId: string | null): Promise<TreeEntry[]>;
+  getNode(nodeId: string): Promise<NodeDocument>;
+  createNodes(input: CreateNodeInput): Promise<Node>;
+  getNodeGraph(limit?: number): Promise<NodeGraph>;
+  listNodeLinks(nodeId: string): Promise<NodeLinkList>;
+  // The titles of the documents a text links to, for the reader. A target they may not see, or one
+  // that is gone, is absent from the answer — the two look the same on purpose (#41).
+  resolveNodeLinks(input: ResolveNodeLinksInput): Promise<ResolveNodeLinksResult>;
+  saveNode(input: SaveNodeVersionInput): Promise<NodeDocument>;
+  saveNodeAttachment(input: SaveAttachmentInput): Promise<NodeDocument>;
+  /**
+   * A file uploaded as itself, not as base64 in a JSON body (#821).
+   *
+   * ⚠️ The `File` is handed over rather than read: the browser streams it from disk, so a 50 MB
+   * upload never stands in memory here. `saveNodeAttachment` beside it does the opposite by
+   * construction, which is why it keeps the smaller limit and why this is what the tree uses.
+   */
+  saveNodeAttachmentBytes(input: {
+    nodeId: string;
+    baseVersionId: string | null;
+    file: File;
+    idempotencyKey: string;
+  }): Promise<NodeDocument>;
+  getNodeAttachment(nodeId: string): Promise<Blob>;
+  // One subtree — or one single node — as the zip bundle the server streams (#136). `null` is the
+  // root: the whole installation as this caller may read it.
+  exportNodeBundle(nodeId: string | null): Promise<Blob>;
+  // The same bundle shape for a single flow, through the flow's own export route.
+  exportFlowBundle(flowId: string): Promise<Blob>;
+  // A zip bundle — or a folder zipped on the client — as a new subtree under the target folder
+  // (#137). `nodeId` null files at the root. Always new nodes; the server is all-or-nothing.
+  importNodeBundle(input: {
+    nodeId: string | null;
+    zip: Blob;
+    idempotencyKey: string;
+  }): Promise<BundleImportResult>;
+  // A table as columns and rows. The CSV stays canonical — `getNode` still answers with it,
+  // which is what the download uses — and this is the same bytes read by the server's one reader.
+  getNodeTable(nodeId: string): Promise<NodeTable>;
+  defineTable(input: DefineTableInput): Promise<NodeTable>;
+  appendTableRows(input: AppendTableRowsInput): Promise<AppendTableRowsResult>;
+  // Changing the header of a table that already has one (#135). The mapping is explicit — every new
+  // column names the current one whose cells fill it, or `null` for an empty one — because a new
+  // header without it would reinterpret every stored row under names nobody matched to the old ones.
+  //
+  // ⚠️ `baseVersionId` is the `versionId` the mapping was written against, and the server refuses
+  // with `version_conflict` when the table has moved on. Not optional: a mapping onto a header
+  // somebody else has since changed would move the wrong cells, silently.
+  redefineTable(input: RedefineTableInput): Promise<NodeTable>;
+
+  // Walks the browser through the portal's OAuth flow without asking anybody anything: Gate is the
+  // identity provider Cloudflare Access consumes, so a signed-in person is already known there
+  // (#60). It navigates away — the caller renders no button for it and gets no answer back.
+  startPortalSignIn(returnTo?: string): void;
+  listNodeVersions(nodeId: string): Promise<NodeVersionList>;
+  updateNode(input: UpdateNodeInput): Promise<Node>;
+  archiveNode(input: ArchiveNodeInput): Promise<Node>;
+  // ⚠️ The one way across this seam after which nothing is really left (#457). The title comes back
+  // because nothing can look it up afterwards.
+  purgeNode(input: PurgeNodeInput): Promise<PurgeNodeResult>;
+  previewNodePurge(
+    input: PurgeNodePreviewInput,
+  ): Promise<import("@contract/node.ts").PurgeNodePreview>;
+  purgeFlow(input: PurgeFlowInput): Promise<PurgeFlowResult>;
+  searchNodes(input: SearchInput): Promise<SearchResult>;
+  listGrants(resourceId: string): Promise<ResourceGrantList>;
+  listEffectiveAccess(resourceId: string): Promise<import("@contract/share.ts").ResourceAccessList>;
+  // The grant, and what the grant does not cover: the documents the flows in this folder read that
+  // the new principal still cannot. A warning, never a refusal (ADR-0004 §4).
+  shareNode(input: ShareInput): Promise<ShareResult>;
+  revokeGrant(input: RevokeGrantInput): Promise<RevokeGrantResult>;
+  // The same four for one flow (#530). Separate calls rather than a widened `resourceId`, because
+  // the id names a different table on the other side and the routes are separate there too.
+  listFlowGrants(flowId: string): Promise<ResourceGrantList>;
+  listEffectiveFlowAccess(flowId: string): Promise<import("@contract/share.ts").ResourceAccessList>;
+  // ⚠️ `ShareResult.unrunnable` is only ever filled in here: a grant on one flow does not reach the
+  // flows it calls, and this is where that gets said.
+  shareFlow(input: ShareFlowInput): Promise<ShareResult>;
+  revokeFlowGrant(input: RevokeFlowGrantInput): Promise<RevokeGrantResult>;
+  listFlows(input?: ListFlowsInput): Promise<FlowList>;
+  getFlow(flowId: string): Promise<FlowDocument>;
+  // What a flow calls, read out of its graph. It answers a different question from `listTreeChildren`
+  // and deliberately gives a different answer: a shared sub-flow is listed under every caller.
+  listFlowCalls(flowId: string): Promise<FlowList>;
+  // Would this flow start for me, right now. A question, not an action: nothing is created (#72).
+  validateFlow(flowId: string): Promise<FlowValidation>;
+  // What accesses what, for one level of the shared tree: a folder for its contents, a flow for
+  // itself. ⚠️ Only nodes the signed-in user may see come back, and one they may not is absent
+  // altogether — never a placeholder, because the edge into one would already say that it exists.
+  getRelationGraph(scope: RelationGraphScope, limit?: number): Promise<RelationGraph>;
+  // What a flow touches: the documents and tools its graph names. Documents the signed-in user may
+  // not see are counted rather than named, and nothing here claims anybody may reach them.
+  getFlowRequirements(flowId: string): Promise<FlowRequirements>;
+  createFlow(input: CreateFlowInput): Promise<Flow>;
+  updateFlow(input: UpdateFlowInput): Promise<Flow>;
+  // Archive a flow or take it back out. An archived flow leaves the tree, stops being startable and
+  // stops resolving as another flow's callee; its versions stay untouched.
+  archiveFlow(input: ArchiveFlowInput): Promise<Flow>;
+  saveFlow(input: SaveFlowVersionInput): Promise<FlowDocument>;
+  listFlowVersions(flowId: string): Promise<FlowVersionList>;
+  // Which version each sub-flow call will take once published, and which of them publishing
+  // freezes. Read before publishing, so the author agrees to the pins rather than discovering them.
+  previewFlowPublish(input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
+  publishFlow(input: PublishFlowInput): Promise<Flow>;
+  startFlow(input: StartFlowRunInput): Promise<FlowRunStep>;
+  // What this flow has done, newest first, one page at a time. ⚠️ It carries what a run did and
+  // never what it produced: a run reads nodes with the rights of whoever started it, so its
+  // result is not automatically readable for everyone who may read the flow.
+  // The activity feed, newest first (#742). `before` is the previous answer's `nextCursor`,
+  // handed back unchanged; `actor` narrows it to one person or one agent.
+  listFeed(input: {
+    limit: number;
+    before?: string | undefined;
+    actor?: string | undefined;
+  }): Promise<FeedListResponse>;
+  listFlowRuns(input: ListFlowRunsInput): Promise<FlowRunList>;
+  getFlowRun(runId: string): Promise<FlowRunStep>;
+  // The drill-down behind one run: every step it took, and the call chain it belongs to.
+  getFlowRunSteps(runId: string): Promise<FlowRunHistory>;
+  completeFlowStep(input: CompleteFlowRunStepInput): Promise<FlowRunStep>;
+  // Reading the catalog is the whole of the tool surface here: calling a tool belongs to a flow
+  // or to the Intel MCP surface, not to the screen that shows what the portal offers.
+  listTools(): Promise<ToolCatalog>;
+  listToolServers(): Promise<ToolServerCatalog>;
+
+  logout(): Promise<void>;
+}

package/ui/src/data/query-client.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from "@tanstack/react-query";
+import { retryRequest } from "@/data/request-refusal/request-refusal.ts";
+
+/**
+ * The one query client the application runs on.
+ *
+ * ⚠️ It exists as a function rather than as the literal `new QueryClient()` that stood in `main.tsx`
+ * so the policy in it can be exercised by a test (#430). A default nothing renders under is a
+ * default nothing checks, and this one decides how long a screen stays on "Loading…".
+ *
+ * ⚠️ Flat, and without a `.unit.ts` of its own on purpose: the only thing to assert here is that the
+ * returned client carries `retryRequest`, and what that predicate DOES is already covered next door
+ * in `request-refusal.unit.ts` — twice over, because two screen tests render against this very
+ * client. A test that restated the wiring would be the "pure wiring" the repository rules exclude.
+ */
+export function createIntelQueryClient(): QueryClient {
+  return new QueryClient({ defaultOptions: { queries: { retry: retryRequest } } });
+}

package/ui/src/data/request-refusal/refusal-notice.tsx

@@ -0,0 +1,36 @@
+import type { Refusal } from "@/data/request-refusal/request-refusal.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+
+/**
+ * What a refusal is told with, on every surface that has one.
+ *
+ * ⚠️ A refusal is not a failure, and the difference is the whole of #430. Somebody whose share was
+ * revoked was left in front of "Loading…" — the worst answer of all, because it says the program is
+ * still working. They get a sentence and no retry button: the answer was final, and a button that
+ * changes nothing is an invitation to keep waiting.
+ *
+ * ⚠️ One sentence for `404`, whichever of its two reasons applies. Intel answers the same status
+ * for "no such node" and "not for you" on purpose — `requireVisible` in
+ * `packages/intel/src/nodes/nodes.ts` — and a screen that told them apart would undo that from the
+ * other side.
+ *
+ * ⚠️ One function rather than a block per branch, because two answers to one question on one
+ * surface IS #445. A screen's halves — the empty level, the selected item, the view beside it — are
+ * asked the same thing, and copies drift.
+ *
+ * ⚠️ **Why this became shared here and not one copy earlier.** `nodes.tsx` (#445) and `flows.tsx`
+ * (#557) each carried an identical version, and #557 wrote its reason on the second one: this
+ * repository builds an abstraction after the third time it hurts, not the second. #568 is the third
+ * time — `?view=graph` and `?view=runs` are the third and fourth surface asking for the same
+ * sentence — so what would have been a third copy is this file. The rule did not bend; it was met.
+ */
+export function RefusalNotice({ refusal }: { refusal: Refusal }) {
+  const i18n = useI18n();
+  return (
+    <div role="status" className="grid flex-1 place-items-center p-8 text-center text-sm">
+      <p className="max-w-sm text-muted-foreground">
+        {i18n.t(refusal === "no-permission" ? "common.noPermission" : "common.noAccess")}
+      </p>
+    </div>
+  );
+}

package/ui/src/data/request-refusal/request-refusal.ts

@@ -0,0 +1,51 @@
+import { IntelRequestError } from "@/data/intel-data-provider/intel-data-provider.ts";
+
+/**
+ * What a failed request already settles, as opposed to what it might answer differently next time.
+ *
+ * - `not-available` is Intel's `404`. It is deliberately the same answer for "there is no such node"
+ *   and "you may not reach this node" — `requireVisible` in `packages/intel/src/nodes/nodes.ts`, held
+ *   in place by "answers 404 for a foreign version and for an unreadable node" in `nodes.int.ts`.
+ *   A screen must therefore not guess between them either: one sentence covers both, and that is why
+ *   `no-permission` is a separate value rather than prose that could be shown for a `404` by mistake.
+ * - `no-permission` is a `403`. The server said the word itself, so repeating it reveals nothing.
+ * - `null` is everything else: a timeout, a `502`, a network that came back. Those are worth trying
+ *   again, and the screen keeps its retry button for them.
+ */
+export type Refusal = "not-available" | "no-permission";
+
+/** The HTTP status the data provider recorded, or `null` where the failure carried none. */
+export function statusOf(error: unknown): number | null {
+  return error instanceof IntelRequestError ? error.status : null;
+}
+
+export function refusalOf(error: unknown): Refusal | null {
+  switch (statusOf(error)) {
+    case 403:
+      return "no-permission";
+    case 404:
+      return "not-available";
+    default:
+      return null;
+  }
+}
+
+/**
+ * The retry policy every query in Intel runs under.
+ *
+ * ⚠️ A refusal is deterministic, and repeating it is what left the screen on "Loading…" after a
+ * share was revoked (#430). React Query's default is three retries with a growing delay, so a `404`
+ * kept the reader in front of a moving loading state for seconds — and a retry is **paused while
+ * the tab is unfocused** (`packages/intel/ui/CLAUDE.md`, #212), so "seconds" has no upper bound whenever
+ * the person looked somewhere else. The answer was there the whole time.
+ *
+ * ⚠️ `408` and `429` are the two `4xx` that DO change on their own — a timeout and a rate limit both
+ * say "not now" rather than "not you" — so they keep the retries. Everything else in the range is
+ * about this request as it was made, and making it again cannot alter that.
+ */
+export function retryRequest(failureCount: number, error: unknown): boolean {
+  const status = statusOf(error);
+  const deterministic =
+    status !== null && status >= 400 && status < 500 && status !== 408 && status !== 429;
+  return !deterministic && failureCount < 3;
+}

package/ui/src/data/sign-in/sign-in.ts

@@ -0,0 +1,97 @@
+// Sending somebody to sign in is the right answer to a 401 — but only ONCE. If the surface still
+// answers 401 after a successful sign-in, redirecting again produces a page that reloads forever:
+// Gate signs the person in, the interface asks, the answer is 401, and round it goes. From the
+// outside it looks like a broken deployment; from the inside every single step succeeded, which is
+// what makes it expensive to find (#118).
+//
+// It happens whenever a token is valid to Gate but not accepted by `/api/v1` — a session that
+// expires between the two calls, a bearer for a different audience, a service key that no longer
+// holds. The same fix landed in anchrd/agents first; this is its counterpart here.
+
+import type { SignIn, SignInDeps } from "./sign-in.types.ts";
+
+const Marker = "intel:last-sign-in";
+
+// Long enough to cover Gate's redirect chain, short enough that somebody who genuinely returns
+// hours later gets a fresh attempt rather than an error page.
+const LoopWindowMs = 30_000;
+
+export function createSignIn(deps: SignInDeps): SignIn {
+  return {
+    attempt() {
+      // ⚠️ Every unusable marker counts as "no recent attempt", never as "loop" — missing, damaged,
+      // and dated in the future all mean the same thing here. The last one is not hypothetical: a
+      // clock that jumps backwards (time zone, NTP) leaves a marker ahead of `now`, and reading a
+      // negative age as "just tried" would lock somebody out over the wrong wall clock. Refusing
+      // costs an error page; allowing costs one extra reload, so the doubt goes to allowing.
+      const last = Number(deps.read(Marker) ?? 0);
+      const age = deps.now() - last;
+      if (Number.isFinite(last) && last > 0 && age >= 0 && age < LoopWindowMs) return false;
+
+      deps.write(Marker, String(deps.now()));
+      deps.go(deps.loginPath(deps.currentPath()));
+      return true;
+    },
+  };
+}
+
+/**
+ * The same thing wired to the browser.
+ *
+ * ⚠️ `sessionStorage`, not `localStorage`: the window is about one sign-in journey, and a marker
+ * that outlives the tab would meet the next visit as if it were still mid-loop. Both throw rather
+ * than return null when storage is blocked, so both accesses are guarded — see `attempt`.
+ */
+export function createBrowserSignIn(loginPath: (returnTo?: string) => string): SignIn {
+  return createSignIn({
+    now: () => Date.now(),
+    read: (key) => {
+      try {
+        return window.sessionStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    write: (key, value) => {
+      try {
+        window.sessionStorage.setItem(key, value);
+      } catch {
+        // Nothing to do: without a marker the next 401 redirects once more. One extra reload beats
+        // an error page for somebody who could have been let in.
+      }
+    },
+    go: (url) => window.location.assign(url),
+    currentPath: () => `${window.location.pathname}${window.location.search}`,
+    loginPath,
+  });
+}
+
+/**
+ * What to do with a 401, across all of them at once (#130).
+ *
+ * ⚠️ The reason this is a guard and not a call to `attempt()` at each 401: a first load without a
+ * session fires several requests together — session, tree, flows — and every one of them answers
+ * 401. The first starts the redirect; the rest arrive while the browser is still on this page,
+ * find the marker the first one just wrote, and read it as "we already tried, this is a loop". It
+ * is not — it is this very sign-in, still in flight.
+ *
+ * Without `leaving`, the interface refuses itself before it can leave, and nobody reaches the
+ * login at all. That is worse than the loop this whole mechanism exists to prevent: a loop still
+ * eventually shows a login, a self-refusal never does.
+ */
+export function createSignInGuard(signIn: SignIn, onRefused: () => void): () => void {
+  let leaving = false;
+  // Latches for its own reason: once the surface has turned down a freshly issued credential,
+  // later 401s say nothing new, and repainting for each would flicker the screen once per request
+  // the page had in flight.
+  let refused = false;
+  return () => {
+    if (leaving || refused) return;
+    if (signIn.attempt()) {
+      leaving = true;
+      return;
+    }
+    refused = true;
+    onRefused();
+  };
+}

package/ui/src/data/sign-in/sign-in.types.ts

@@ -0,0 +1,15 @@
+export interface SignInDeps {
+  now(): number;
+  read(key: string): string | null;
+  write(key: string, value: string): void;
+  go(url: string): void;
+  currentPath(): string;
+  loginPath(returnTo?: string): string;
+}
+
+export interface SignIn {
+  // True when it sent the person away, false when it refused to because it just did. A caller that
+  // gets `false` must show something rather than wait — the redirect that would have explained
+  // itself is exactly what is not happening.
+  attempt(): boolean;
+}

package/ui/src/document-link/document-link.tsx

@@ -0,0 +1,114 @@
+import { createReactInlineContentSpec } from "@blocknote/react";
+import { DocumentLinkInlineType } from "@contract/node.ts";
+import { FileText, Link2Off } from "lucide-react";
+import { createContext, useContext } from "react";
+
+/**
+ * What a document link resolves to for the person reading it.
+ *
+ * ⚠️ `titles` holds only the documents this reader may see. A missing entry is the whole answer for
+ * both of the reasons an entry can be missing — the target is gone, or it is not theirs to reach —
+ * and nothing here may ever be given a way to tell those apart. `pending` exists so the editor can
+ * hold back the difference between "not resolved yet" and "does not resolve", which would otherwise
+ * flash a broken link at every reader for one render.
+ */
+export interface DocumentLinkResolution {
+  titles: ReadonlyMap<string, string>;
+  pending: boolean;
+  // The one word an unresolved link says. It travels in the context because a BlockNote inline
+  // element is rendered by the editor rather than by a view that could reach the i18n catalog.
+  unresolvedLabel: string;
+}
+
+const DocumentLinkContext = createContext<DocumentLinkResolution>({
+  titles: new Map(),
+  pending: false,
+  unresolvedLabel: "Unavailable document",
+});
+
+export const DocumentLinkProvider = DocumentLinkContext.Provider;
+
+export function useDocumentLinkResolution(): DocumentLinkResolution {
+  return useContext(DocumentLinkContext);
+}
+
+/**
+ * One document link inside the text (#41).
+ *
+ * ⚠️ The element stores the target's ID and nothing else. A stored title would be wrong the moment
+ * the target is renamed and a stored path the moment it is moved — and both would put a name into a
+ * document that any reader of it could then read, whether or not they may reach the target.
+ *
+ * ⚠️ An unresolved link says that it does not resolve and nothing more: no title, no path, no ID on
+ * screen, no hint of which of the two reasons applies. That is the whole of the leak this feature
+ * could have introduced, and the reason the broken form carries no data at all.
+ */
+export function DocumentLinkText({ nodeId }: { nodeId: string }) {
+  const { titles, pending, unresolvedLabel } = useDocumentLinkResolution();
+  const title = titles.get(nodeId);
+  if (title === undefined) {
+    return (
+      <span
+        data-document-link={pending ? "pending" : "unresolved"}
+        className={
+          pending
+            ? "inline-flex items-center gap-1 rounded-sm px-1 text-muted-foreground"
+            : "inline-flex items-center gap-1 rounded-sm bg-destructive/10 px-1 text-destructive line-through"
+        }
+      >
+        {pending ? null : <Link2Off aria-hidden="true" className="size-3.5" />}
+        {pending ? "…" : unresolvedLabel}
+      </span>
+    );
+  }
+  return (
+    <span
+      data-document-link="resolved"
+      data-node-id={nodeId}
+      className="inline-flex items-center gap-1 rounded-sm bg-muted px-1 text-foreground"
+    >
+      <FileText aria-hidden="true" className="size-3.5" />
+      {title}
+    </span>
+  );
+}
+
+export const documentLinkSpec = createReactInlineContentSpec(
+  {
+    type: DocumentLinkInlineType,
+    propSchema: { nodeId: { default: "" } },
+    // The link has no editable text of its own: what it reads is the target's title, and a title
+    // somebody could type over would stop following the target the first time they did (#41).
+    content: "none",
+  },
+  {
+    render: (props) => <DocumentLinkText nodeId={String(props.inlineContent.props.nodeId)} />,
+  },
+);
+
+/**
+ * The IDs a stored BlockNote document links to.
+ *
+ * The server reads the same thing out of the same content when the document is saved; this side
+ * needs it too, to ask which of them it may show a title for.
+ */
+export function documentLinkIds(blocks: unknown): string[] {
+  const found = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const entry of value) walk(entry);
+      return;
+    }
+    if (typeof value !== "object" || value === null) return;
+    const record = value as Record<string, unknown>;
+    if (record.type === DocumentLinkInlineType) {
+      const props = record.props as Record<string, unknown> | undefined;
+      const nodeId = props?.nodeId;
+      if (typeof nodeId === "string" && nodeId.length > 0) found.add(nodeId);
+    }
+    walk(record.content);
+    walk(record.children);
+  };
+  walk(blocks);
+  return [...found];
+}