Links & Backlinks

Xudanu's typed, bidirectional, unbreakable connections between passages — the defining feature of Nelson-style hypertext. How to create them, render them, and navigate them consistently.

1. Nelson's Two-Connection Model

Xudanu implements Ted Nelson's fundamental distinction between two kinds of connections. They share the same HyperLink data model but serve opposite purposes. Getting this distinction straight is the single most important thing for new developers.

Figure 1: A transclusion (green) copies identical content between works. A content link (blue/red) connects different content with a typed relationship. A single document can have both.

2. The Data Model: HyperLink, HyperRef, Spans

Every connection — transclusion or typed link — is a HyperLink. A HyperLink has two (or more) named ends, conventionally "LeftEnd" (origin) and "RightEnd" (destination). Each end is a HyperRef that points at a specific span inside a specific work.

pub struct HyperLink {
    ends: HashMap<String, HyperRef>,   // "LeftEnd" → origin, "RightEnd" → destination
    link_types: Vec<u64>,             // empty = pure transclusion; non-empty = typed link
}

pub struct HyperRef {
    kind: HyperRefKind,             // "single" = a span inside one work
    work_context: Option<BeId>,        // which work this end points into
    excerpt: Option<Edition>,         // a copy of the span text (fallback for search)
    start_position: Option<i64>,       // canonical char offset (preferred)
    end_position: Option<i64>,         // canonical char offset (preferred)
    provenance_chain: Vec<ProvenanceHop>,
}

Wire operations

The client sends these op strings over the WebSocket. The opcodes live in protocol.rs:

3. Link Types & Their Visual Style

Five default types are pre-registered (see DEFAULT_LINK_TYPES in useTransclusion.ts and LINK_TYPE_STYLES in CollaborativeEditor.tsx). The colour and dash pattern are the contract — use them everywhere consistently.

Figure 2: Each type has a distinct dash pattern so overlapping links remain readable even without colour.

4. The Client API (crdt_sync.ts)

These are the methods on CrdtSyncClient you will use. All are async and go over the WebSocket.

// Create a link. ALWAYS pass { start, end } in the refs — they become
// start_position/end_position on the wire and are the canonical span.
const linkId = await client.linkCreate(
  originWorkId,
  destinationWorkId,
  { excerpt: sourceText, start: srcStart, end: srcEnd },        // origin_ref
  { excerpt: targetText, start: tgtStart, end: tgtEnd },        // destination_ref
);

// Assign a type (Comment=1, Reference=2, ...). Call right after linkCreate.
await client.linkSetTypes(linkId, [1]);   // now it's a Comment link

// Read
const links   = await client.linkListForWork(workId);  // LinkEntry[]
const one     = await client.linkGet(linkId);             // full payload w/ both refs
const types   = await client.linkTypeList();             // {type_id, name}[]

// Backlinks: who links INTO this work (incoming) and what it links to (outgoing)
const backlinks = await client.findBacklinks(workId);   // BacklinkEntry[]

// Fallback position search (used internally when a ref lacks stored coords)
const hits = await client.findExcerptPositions(workId, excerpt);

// Delete
await client.linkDelete(linkId);

Key payload shapes

interface LinkEntry {
  link_id: number; origin: number; destination: number;
  origin_ref: HyperRefPayload | null; destination_ref: HyperRefPayload | null;
  link_types?: number[];
  origin_title?: string; destination_title?: string;
  origin_archived?: boolean; destination_archived?: boolean;
}

interface HyperRefPayload {
  kind: string; work_context: number | null;
  excerpt: string | null;
  start_position?: number | null;   // ← read this to place the marker
  end_position?: number | null;
  provenance_chain?: ProvenanceHop[];
}

interface BacklinkEntry {
  source_work_id: number; link_id: number;
  link_type: string;   // "hyperlink_incoming" | "hyperlink_outgoing"
  excerpt?: string; title?: string;
}

5. The useTransclusion Hook

The hook manages both transclusion and typed-link state for the active work. Despite the name, it is the single home for all link UI flows. (A separate useContentLinks hook was proposed in the FR-4 spec; the functionality lives here instead.)

const t = useTransclusion();
// t.links       — LinkEntry[] for the current work
// t.markers     — TransclusionMarker[] ready to hand to <CollaborativeEditor>
// t.backlinks   — BacklinkEntry[] (populated by loadBacklinks)
// t.linkTypes   — {type_id, name}[]
// t.pendingLink — held source selection while the user picks a target

// 1. User selects text in the source document:
t.holdLinkSelection(workId, workTitle, selStart, selEnd, selText);

// 2. ...user navigates to the target document and selects target text...

// 3. Create the typed link:
const id = await t.createContentLink(
  client, targetWorkId, targetStart, targetEnd, targetText, typeId
);
// createContentLink calls linkCreate (with start/end) then linkSetTypes([typeId])

// Refresh data on work switch:
t.loadLinks(client, workId, works);     // builds t.markers (prefers stored spans)
t.loadBacklinks(client, workId);
t.loadLinkTypes(client);

6. Example A: Create a Typed Comment Link

Use case: A reviewer selects a passage in an essay and attaches a comment that lives in a separate notes document. This is the canonical two-part selection flow.

// Source work: "Essay" (0x10). Target work: "Reviewer notes" (0x20).
// The user selected chars 142..168 in the essay ("privacy is a human right")
// and chars 0..34 in the notes ("this claim is contested in case law").

t.holdLinkSelection(0x10, "Essay", 142, 168, "privacy is a human right");
// ...navigate to the notes document, select the target span...
await t.createContentLink(client, 0x20, 0, 34, "this claim is contested in case law", 1);
// typeId 1 = Comment (blue, dashed)

Figure 3: A Comment link in the origin document. The left margin shows a blue "C" bar; the passage has a blue dashed underline. Hovering reveals the target work, type, excerpt, a "Go to" button, and a red "Delete link" button.

7. Example B: Transclusion (Same Content, Two Places)

Use case: A quotation appears in a source canon work and is re-used verbatim in a newsletter. Transclusion keeps the two in sync and records provenance.

// Hold the source selection in the canon work (0x30)
t.holdSelection(0x30, "Canon", 200, 226, "privacy is a human right");
// ...navigate to the newsletter (0x40), click at the insertion point...
await t.placeTransclusion(client, 0x40, insertionPosition);
// No linkSetTypes call → link_types stays empty → rendered as a transclusion
// (hatched margin bar, inline resolved span, provenance chain).

Figure 4: A transclusion (left) shows the resolved text inline with a hatched margin bar. A typed link (right) underlines the existing text without copying it.

8. Example C: Backlinks — Who Links Into You

Use case: You open your essay and want to see everyone who has commented on or referenced it. Backlinks are the incoming half of the bidirectional graph.

// On work switch, AppShell already does this for you via the hook:
await t.loadBacklinks(client, workId);
// → t.backlinks is now BacklinkEntry[] with source_work_id, title, excerpt, link_type

// ...or call the client directly:
const incoming = (await client.findBacklinks(workId))
  .filter(b => b.link_type === "hyperlink_incoming");
incoming.forEach(b => console.log(`${b.title}: ${b.excerpt}`));

Figure 5: Outgoing links paint on the left margin; incoming backlinks paint on the right. The Connections panel lists both with arrows (← incoming, → outgoing).

9. Example D: Disagreement Links & Structured Dissent

Use case: Multiple authors contest a passage. Each attaches a Disagreement link to their counter-argument. Readers see all sides at the contested text.

// Reviewer 1 holds the contested passage and links their rebuttal
t.holdLinkSelection(essayId, "Essay", 142, 168, "privacy is a human right");
await t.createContentLink(client, rebuttalAId, s, e, "Doe 2021 disproves this", 3);

// Reviewer 2 links a different rebuttal to the SAME passage
t.holdLinkSelection(essayId, "Essay", 142, 168, "privacy is a human right");
await t.createContentLink(client, rebuttalBId, s, e, "the right is not absolute", 3);
// Both render as red underlines; FR-4.5 layers them so both stay visible.

Figure 6: Two Disagreement links on the same passage. They stack on the left margin and layer their underlines vertically so neither hides the other.

10. Example E: Profuse Overlapping Links + Density

Use case: A heavily-annotated legal clause accumulates many overlapping links. Rather than paint a mess, the canvas collapses 5+ overlapping links into a single density pill; clicking expands the cluster.

// 6 overlapping Comment links
// on the same sentence → one pill:
//
//  ┌──┐ privacy is a human right
//  │6 │ ████████████████████
//  └──┘
// click → expands to individual
// lane-stacked markers

// Top-right control toggles types.
// null filter = show all;
// a Set = only those types
// (transclusions always show).
filterMarkersByType(markers, new Set([3]));
// → only Disagreement links

Figure 7: Above the density threshold (5), overlapping links collapse to a single amber pill showing the count. The pure helpers assignLinkLanes, clusterOverlappingMarkers, and filterMarkersByType drive this (see link-markers.ts).

11. Rendering: How Markers Paint on the Canvas

CollaborativeEditor.drawOverlay() paints onto a canvas layered above the text. The link pass runs after attribution and transclusion passes:

1. Underline — a dashed/solid line beneath the linked span, colour + dash from LINK_TYPE_STYLES[linkTypeId]. Overlapping links offset by lane * 2px (FR-4.5).
2. Left margin bar — outgoing typed links, at x = lane * 4px. Provenance chains stack further right.
3. Right margin bar — incoming typed backlinks, at rect.width - 3 - lane*4.
4. Density pill — amber, count badge, when a cluster reaches 5+ links.
5. Hit zones — every marker registers a MarkerHitZone used by mouse-move (tooltip) and click (navigate / expand).
6. Description boxes — when a link has a description, a coloured box appears in the right margin showing the type label and description text.
7. Connecting lines — dotted lines drawn from each description box to the source text. Lines anchor to the underline position (bottom of the text), not the centre of the span. Overlapping links use lane separation so each connecting line stays distinguishable.

Figure 8: A marker is three things at once: a margin bar, an underline, and an invisible hit zone. All driven by the same TransclusionMarker record.

12. Span Migration: Links Survive Edits

A link's stored start_position/end_position are not fixed byte offsets — they are migrated whenever the text changes. When a user edits a work, the server walks every link touching that work and remaps each end's span through the edit delta. This is why stored coordinates beat excerpt re-search: they stay correct after edits, while a fresh excerpt search might land on a new copy of the same phrase.

Figure 9: migrate_link_spans_for_delta() in server.rs remaps link endpoints on every edit. Thirteen dedicated tests cover insert/delete/replace/inside-span cases.

13. Consistency Guidelines & Gotchas

• Always pass start/end when creating a link. The client now transmits them as start_position/end_position. Omitting them forces the brittle excerpt-search fallback (ambiguous on duplicate phrases).
• Always call linkSetTypes right after linkCreate for a content link. A link with empty link_types is a transclusion and renders with hatch bars, not typed underlines.
• Use the built-in type ids. Comment=1, Reference=2, Disagreement=3, Quotation=4, See Also=5. Don't invent client-side ids; custom types must be registered server-side via register_link_type first.
• Markers come from loadLinks, not hand-built. Let the hook resolve positions (stored span first, excerpt fallback second). Building TransclusionMarker objects yourself duplicates that logic.
• Direction is inferred from the work you're viewing. The same link is "outgoing" in its origin work and "incoming" in its destination work. Outgoing paints left; incoming paints right.
• Backlink count ≠ link count. find_backlinks dedupes per source work. Ten links from one reviewer show as one backlink entry.
• Render from data every frame. drawOverlay recomputes markers, lanes, and clusters each redraw — don't cache marker DOM. This keeps live multi-user edits correct.
• Archived works still link. A link endpoint may point at a soft-deleted (archived) work; the marker shows a "🗄 Archived work" notice in its tooltip. Don't drop the marker.

14. Source Code Map