@djangocfg/widget-chat 0.1.1

package/src/core/content/incomplete-math.ts

@@ -0,0 +1,118 @@
+/**
+ * Hide an UNCLOSED `$$` from the math parser.
+ *
+ * ## The defect, measured
+ *
+ * streamdown completes half-arrived markdown so a bold run styles itself while
+ * the model is still typing it. Applied to math that behaviour is wrong rather
+ * than merely early: `complexity is $$O(n \log` renders a typeset `O(n log` —
+ * a DIFFERENT expression from the one being written, which then jumps to
+ * another as tokens land. A reader cannot tell an intermediate formula from a
+ * final one, so a plausible wrong formula is presented as an answer.
+ *
+ * ## Why not `parseIncompleteMarkdown: false`
+ *
+ * Because the flag is global, and completion is the whole reason this
+ * dependency was chosen. On this exact input set:
+ *
+ * | unclosed | flag on | flag off |
+ * |---|---|---|
+ * | `**important` | bold | plain |
+ * | `` `foo( `` | code | plain |
+ * | `[docs](` | link | plain |
+ * | `$$O(n \log` | KATEX ← the defect | plain |
+ *
+ * Turning it off fixes one row by breaking three. So completion stays on and
+ * the ONE construct where a premature guess is a lie gets neutralised here.
+ *
+ * ## How
+ *
+ * The last `$$` is escaped only when it opens a run nothing closes. Escaping
+ * (rather than deleting) is what keeps the literal `$$` visible: the user sees
+ * the characters the model has actually emitted, which is the honest state.
+ */
+
+/** The delimiter. Inline math uses the same one — `singleDollarTextMath` is off. */
+const DELIMITER = "$$";
+
+/**
+ * Escape a trailing unclosed `$$`, leaving balanced math untouched.
+ *
+ * Fenced code is skipped: `` ```sh\necho $$ `` is a shell PID, not an opening
+ * delimiter, and rewriting inside a fence would corrupt code the user copies.
+ */
+export function maskIncompleteMath(source: string): string {
+  const segments = splitOnFences(source);
+  let count = 0;
+
+  // Count across prose segments only — a `$$` inside a fence closes nothing.
+  for (const segment of segments) {
+    if (segment.fenced) continue;
+    count += occurrences(segment.text);
+  }
+
+  if (count % 2 === 0) return source;
+
+  // Odd ⇒ the LAST prose `$$` is the unclosed opener.
+  for (let i = segments.length - 1; i >= 0; i -= 1) {
+    const segment = segments[i];
+    if (!segment || segment.fenced) continue;
+    const at = segment.text.lastIndexOf(DELIMITER);
+    if (at === -1) continue;
+    segments[i] = {
+      fenced: false,
+      text: `${segment.text.slice(0, at)}\\$\\$${segment.text.slice(at + DELIMITER.length)}`,
+    };
+    break;
+  }
+
+  return segments.map((segment) => segment.text).join("");
+}
+
+interface Segment {
+  readonly fenced: boolean;
+  readonly text: string;
+}
+
+function occurrences(text: string): number {
+  let n = 0;
+  let from = 0;
+  for (;;) {
+    const at = text.indexOf(DELIMITER, from);
+    if (at === -1) return n;
+    n += 1;
+    from = at + DELIMITER.length;
+  }
+}
+
+/**
+ * Split into alternating prose and fenced-code segments.
+ *
+ * An UNCLOSED fence swallows the rest of the string — which is correct: while a
+ * fence is open, everything after it is code, including any `$$`.
+ */
+function splitOnFences(source: string): Segment[] {
+  const segments: Segment[] = [];
+  const fence = /^[ \t]*(?:```|~~~)/gm;
+  let cursor = 0;
+  let open: number | null = null;
+
+  for (let match = fence.exec(source); match !== null; match = fence.exec(source)) {
+    const lineEnd = source.indexOf("\n", match.index);
+    const after = lineEnd === -1 ? source.length : lineEnd + 1;
+
+    if (open === null) {
+      segments.push({ fenced: false, text: source.slice(cursor, match.index) });
+      open = match.index;
+      cursor = match.index;
+    } else {
+      segments.push({ fenced: true, text: source.slice(open, after) });
+      open = null;
+      cursor = after;
+    }
+  }
+
+  // A fence left open owns everything to the end.
+  segments.push({ fenced: open !== null, text: source.slice(cursor) });
+  return segments;
+}

package/src/core/content/index.ts

@@ -0,0 +1,9 @@
+// Pure decisions about a markdown string BEFORE it reaches a parser.
+//
+// Here rather than in content/ because none of it renders: these are string →
+// string functions with no React and no dependency on the parser, so they run
+// in microseconds and can be reasoned about without one.
+//
+// May import: utils.
+
+export { maskIncompleteMath } from "./incomplete-math";

package/src/core/draft-storage.ts

@@ -0,0 +1,62 @@
+/**
+ * What a persisted draft is worth keeping, as a pure decision.
+ *
+ * The effects that read and write live in `composer/use-draft-persistence.ts`;
+ * the RULES live here so they can be tested without a DOM. This workspace has
+ * no jsdom, so a rule that stays inside a hook is a rule nothing can assert.
+ */
+
+/** A draft larger than this is a paste, not typing, and belongs in a chip. */
+export const DRAFT_MAX_LENGTH = 100_000;
+
+const PREFIX = "djc.chat.draft:";
+
+/**
+ * The storage key for a room. Spelled like `store/use-speech-language.ts`, so
+ * chat's keys share one convention.
+ *
+ * Unversioned: the value is a plain string, so the only migration a version
+ * could gate is "it became structured" — and that wants a new prefix, leaving
+ * the old entries to expire with their session.
+ */
+export function draftStorageKey(room: string): string {
+  return PREFIX + room;
+}
+
+/**
+ * What to do with a value read back from storage.
+ *
+ * `null` for both "nothing stored" and "stored empty": an empty string would
+ * otherwise CLEAR a field the host had already seeded, which is the one
+ * outcome a restore must never produce. Over-long values are truncated rather
+ * than dropped — losing the tail of a long draft beats losing all of it.
+ */
+export function restoredDraft(stored: string | null): string | null {
+  if (stored === null || stored === "") return null;
+  return stored.length > DRAFT_MAX_LENGTH ? stored.slice(0, DRAFT_MAX_LENGTH) : stored;
+}
+
+/**
+ * Whether writing this text means storing it or removing the entry.
+ *
+ * Empty means REMOVE, which is what makes a send clear the draft with no
+ * send-specific branch: `send` resets the draft, the save path sees `""`, and
+ * the entry goes. Keeping an empty string instead would leave every sent room
+ * holding a useless entry forever.
+ */
+export function draftWrite(text: string): { readonly remove: true } | { readonly value: string } {
+  if (text === "") return { remove: true };
+  return { value: text.slice(0, DRAFT_MAX_LENGTH) };
+}
+
+/**
+ * Whether the save path may write yet.
+ *
+ * Before a room's restore has run, the draft still holds the PREVIOUS room's
+ * text (or the empty initial value). Writing then puts one room's draft under
+ * another's key, or erases a stored draft with the emptiness that precedes its
+ * own restore — the second is silent and destroys real work.
+ */
+export function mayPersist(restoredRoom: string | null, room: string): boolean {
+  return restoredRoom === room;
+}

package/src/core/events.ts

@@ -0,0 +1,88 @@
+/**
+ * What happens inside a chat, as data.
+ *
+ * The alternative this replaces is a prop threaded from the component that
+ * KNOWS a thing happened to the component that must react — through every layer
+ * between them, none of which cares. `ComposerQueue` needed the composer's
+ * field; the ask card needs the composer's focus; a host wants to know a prompt
+ * was taken back. Each on its own is one more prop on `<Chat>`, and the
+ * predecessor reached 83 of them that way.
+ *
+ * Modelled on `a typed transport`'s `IEventBus` — one typed map, no untyped
+ * escape hatch — but declared here rather than imported: the chat package must
+ * not depend on the transport to talk to itself.
+ */
+
+import type { Draft } from "./outbound";
+
+/**
+ * Every event, with its payload. `void` means the event carries nothing.
+ *
+ * Names are `subject:verb`, past tense: an event states what HAPPENED. A name
+ * in the imperative ("focus:composer") is a command wearing an event's clothes,
+ * and a bus that carries commands becomes a second, untyped API for the thing
+ * it is commanding.
+ */
+export interface ChatEventMap {
+  /** A queued prompt was taken back for editing; it has left the queue. */
+  "queue:taken": { readonly id: string; readonly draft: Draft };
+  /** A prompt was promoted past the running turn, which is now aborted. */
+  "queue:promoted": { readonly id: string };
+  /** A turn was sent. Carries what went out, not what comes back. */
+  "turn:sent": { readonly draft: Draft };
+}
+
+export type ChatEventName = keyof ChatEventMap;
+
+export type ChatEventHandler<E extends ChatEventName> = (payload: ChatEventMap[E]) => void;
+
+export type Unsubscribe = () => void;
+
+/** Names whose payload is `void`: emitted with no second argument. */
+export type VoidChatEvent = {
+  [E in ChatEventName]: ChatEventMap[E] extends void ? E : never;
+}[ChatEventName];
+
+export type DataChatEvent = Exclude<ChatEventName, VoidChatEvent>;
+
+export interface ChatEvents {
+  on<E extends DataChatEvent>(event: E, handler: ChatEventHandler<E>): Unsubscribe;
+  on<E extends VoidChatEvent>(event: E, handler: () => void): Unsubscribe;
+  emit<E extends DataChatEvent>(event: E, payload: ChatEventMap[E]): void;
+  emit<E extends VoidChatEvent>(event: E): void;
+}
+
+/**
+ * An in-memory bus, one per chat.
+ *
+ * Per chat and not module-scoped: two conversations open side by side must not
+ * hear each other's events, which a singleton cannot express. Created beside
+ * the store, handed down the same provider.
+ *
+ * Handlers are copied before dispatch, which fixes the listener list at the
+ * moment of the emit. A `Set` tolerates deleting the CURRENT entry mid-loop, so
+ * a one-shot unsubscribing itself is safe either way — the case that is not is
+ * one handler unsubscribing ANOTHER. Without the copy that second handler is
+ * silently skipped for this emit, which reads exactly like an event that never
+ * fired. Everyone listening when the event happened hears it.
+ */
+export function createChatEvents(): ChatEvents {
+  const handlers = new Map<ChatEventName, Set<(payload: never) => void>>();
+
+  function on(event: ChatEventName, handler: (payload: never) => void): Unsubscribe {
+    const set = handlers.get(event) ?? new Set();
+    handlers.set(event, set);
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  }
+
+  function emit(event: ChatEventName, payload?: unknown): void {
+    const set = handlers.get(event);
+    if (set === undefined) return;
+    for (const handler of [...set]) (handler as (p: unknown) => void)(payload);
+  }
+
+  return { on, emit } as ChatEvents;
+}

package/src/core/focus/index.ts

@@ -0,0 +1,10 @@
+// Which row is the transcript's single tab stop.
+//
+// The DOM part is three lines and lives in primitives/; the part that can be
+// wrong — which index a key selects, and what happens when the list shrinks
+// under a stale one — lives here where it is testable without a renderer.
+//
+// May import: utils.
+
+export { CHAT_ITEM_ATTR, clampIndex, isRovingKey, nextIndex } from "./roving";
+export type { RovingKey } from "./roving";

package/src/core/focus/roving.ts

@@ -0,0 +1,56 @@
+/**
+ * The transcript is ONE tab stop; arrows move within it.
+ *
+ * Without this, Tab walks every message, every tool card and every link before
+ * reaching the composer — so on a transcript of any length a keyboard user
+ * cannot reach the input at all. The APG calls it roving tabindex.
+ *
+ * The DOM part is three lines and lives in `primitives/`. What lives here is
+ * the part that can be wrong: which index a key selects.
+ */
+
+export const CHAT_ITEM_ATTR = "data-chat-item";
+
+/** Keys that move within the transcript, mapped to a target index. */
+export type RovingKey = "ArrowDown" | "ArrowUp" | "Home" | "End";
+
+export function isRovingKey(key: string): key is RovingKey {
+  return key === "ArrowDown" || key === "ArrowUp" || key === "Home" || key === "End";
+}
+
+/**
+ * Where a key moves the active row, or `null` when it moves nowhere.
+ *
+ * `null` — rather than "the same index" — is what lets the caller decide
+ * whether to call `preventDefault()`. Swallowing ArrowDown at the last row
+ * would stop the PAGE from scrolling, which is the browser behaviour a user at
+ * the end of a transcript is relying on.
+ */
+export function nextIndex(key: RovingKey, active: number, count: number): number | null {
+  if (count === 0) return null;
+
+  const last = count - 1;
+  // Clamped, never wrapped. Wrapping from the newest message to the first is
+  // disorienting in a transcript, where position carries meaning — MUI X Chat
+  // clamps here too.
+  const target =
+    key === "Home"
+      ? 0
+      : key === "End"
+        ? last
+        : Math.min(last, Math.max(0, active + (key === "ArrowDown" ? 1 : -1)));
+
+  return target === active ? null : target;
+}
+
+/**
+ * Keep the active index valid as the transcript grows and shrinks.
+ *
+ * Messages arrive while the user reads. An index that outlives its row leaves
+ * EVERY row with `tabIndex={-1}` — the transcript silently stops being
+ * reachable by Tab at all, and nothing about it looks broken.
+ */
+export function clampIndex(active: number, count: number): number {
+  if (count === 0) return 0;
+  return Math.min(count - 1, Math.max(0, active));
+}

package/src/core/group-parts.ts

@@ -0,0 +1,80 @@
+/**
+ * Collapse runs of same-kind parts into groups.
+ *
+ * A turn that thinks, calls four tools, thinks again and answers renders as six
+ * separate cards without this — the answer ends up below a wall of tool calls.
+ * Grouping puts the run behind one "Thinking" or "4 tools" affordance, which is
+ * what assistant-ui does and what makes a tool-heavy transcript readable.
+ *
+ * Only ADJACENT parts coalesce. Reordering to gather all tool calls together
+ * would misrepresent the turn: the sequence is the agent's reasoning, and
+ * "searched, then read what it found" is different information from "searched
+ * and read".
+ */
+
+import type { MessagePart } from "./parts";
+
+export type PartGroup =
+  /** A single part, rendered on its own. */
+  | { readonly kind: "single"; readonly key: string; readonly part: MessagePart }
+  /** Two or more adjacent parts of one type. */
+  | {
+      readonly kind: "run";
+      readonly key: string;
+      readonly type: MessagePart["type"];
+      readonly parts: readonly MessagePart[];
+    };
+
+/** Types worth collapsing. Text is never grouped — prose is the answer itself. */
+const GROUPABLE = new Set<MessagePart["type"]>(["reasoning", "tool"]);
+
+export function groupParts(parts: readonly MessagePart[]): readonly PartGroup[] {
+  const groups: PartGroup[] = [];
+  let run: MessagePart[] = [];
+
+  const flush = (): void => {
+    const first = run[0];
+    if (first === undefined) return;
+    groups.push(
+      run.length === 1
+        ? { kind: "single", key: first.id, part: first }
+        // Keyed on the FIRST member: a run that grows while streaming keeps its
+        // key, so the group does not remount on every new tool call.
+        : { kind: "run", key: first.id, type: first.type, parts: run },
+    );
+    run = [];
+  };
+
+  for (const part of parts) {
+    const previous = run[0];
+    const continues =
+      previous !== undefined && previous.type === part.type && GROUPABLE.has(part.type);
+    if (!continues) flush();
+    if (GROUPABLE.has(part.type)) {
+      run.push(part);
+      continue;
+    }
+    groups.push({ kind: "single", key: part.id, part });
+  }
+  flush();
+
+  return groups;
+}
+
+/**
+ * Should a group be open?
+ *
+ * Open while the run is still producing, collapsed once it settles — the user
+ * wants to watch a tool work and then get it out of the way. Derived rather
+ * than stored so it cannot disagree with the parts; a host that wants manual
+ * control layers its own state over this default.
+ */
+export function isGroupActive(group: PartGroup): boolean {
+  const parts = group.kind === "run" ? group.parts : [group.part];
+  return parts.some(
+    (part) =>
+      part.type === "tool" &&
+      (part.toolState.state === "input-streaming" ||
+        part.toolState.state === "input-available"),
+  );
+}

package/src/core/index.ts

@@ -0,0 +1,34 @@
+export * from "./parts";
+export * from "./group-parts";
+export * from "./adapter";
+export * from "./capabilities";
+export * from "./outbound";
+export * from "./tool-picks";
+// What a pick still wants. A rule about the DRAFT, so it ships with the model
+// rather than being re-derived at the surface that renders the hint.
+export * from "./tool-prompt";
+export { addToolPick, addToolPicks, removeToolPick, toggleToolPick } from "./tool-picks-set";
+export * from "./chunks";
+// Every adapter that mints a tool part owes the reader the same name, so the
+// rule ships with the model rather than being re-derived at each entry point.
+export * from "./tool-name";
+export * from "./transcript";
+export * from "./media";
+export * from "./tools";
+export * from "./recall";
+export * from "./voice";
+export * from "./queue";
+export * from "./focus";
+export * from "./scroll";
+export * from "./content";
+export * from "./draft-storage";
+export * from "./events";
+export * from "./reload-decision";
+// The host implements `AskReplace` and so must be able to name its return.
+// `composer/index.ts` states this barrel already carries it and declines to
+// re-export for that reason — the two must agree, or the type is reachable from
+// nowhere and every host writes its own union.
+export * from "./text-replace";
+// The mention URL scheme. Exported because `configureMentionScheme` is a host
+// call — the scheme is the host's product name, and nothing else can supply it.
+export * from "./links";

package/src/core/links/index.ts

@@ -0,0 +1,33 @@
+// Links, both directions: the ones this package WRITES into a message, and the
+// ones it READS back out of one.
+//
+// Together because they are one round trip. A picked tool is written as a
+// markdown link and parsed back on render, and `scheme.ts` owns both halves so
+// the shape can never disagree with itself. `prose.ts` handles the other kind —
+// ordinary web links the model or the user wrote — which are only ever read.
+//
+// Pure functions of a string, no React and no DOM: the chip decision and the
+// label are testable without rendering anything, which is what keeps them
+// honest while the renderer changes.
+
+export {
+  configureMentionScheme,
+  mentionScheme,
+  toolURL,
+  parse,
+  type ParsedMention,
+  type ParseResult,
+} from "./scheme";
+
+// Reading half only. A picked tool needs no preprocess step — the composer
+// writes the link itself, so the id is never recovered from prose.
+export { extractToolId } from "./tool-id";
+
+export {
+  isBareUrlLink,
+  isExternalHref,
+  linkChipLabel,
+  normalizeHref,
+  splitUrl,
+  type SplitUrl,
+} from "./prose";

package/src/core/links/prose.ts

@@ -0,0 +1,191 @@
+/**
+ * Which links in a message body read as a bare reference, and what a compact
+ * label for one looks like.
+ *
+ * A bare url and `[the docs](…)` are indistinguishable in the tree: both are an
+ * ordinary mdast `link`, and their hast properties are byte-identical. There is
+ * no autolink marker to read. The signal is the CHILD — an autolink's sole text
+ * child equals its url.
+ *
+ * Label shape adapted from the retired `@djangocfg/ui-tools`
+ * (`src/tools/forms/MarkdownEditor/url/detect.ts`) (`splitUrl`, `normalizeHref`,
+ * the Chrome-omnibox form). `truncateUrlLabel` is reworked here; `faviconUrl`
+ * does not come across — it would make a third-party request per link.
+ */
+
+const ELLIPSIS = "…";
+
+/** Default budget for a whole label. Wide enough for `domain/first/…/last`. */
+const DEFAULT_MAX_CHARS = 40;
+
+/** A url split into the parts a label is built from. */
+export interface SplitUrl {
+  /** Host without a leading `www.`. Empty when unparseable. */
+  readonly domain: string;
+  /** Path segments, empty ones dropped. */
+  readonly segments: readonly string[];
+  /** `#fragment` including the hash, or empty. */
+  readonly hash: string;
+  /** `mailto:` address without the scheme, or empty. */
+  readonly mail: string;
+}
+
+/** Prepend a scheme to a schemeless `www.` host so `URL` can parse it. */
+export function normalizeHref(raw: string): string {
+  if (/^www\./i.test(raw)) return `https://${raw}`;
+  return raw;
+}
+
+/**
+ * Split an href into the label's parts.
+ *
+ * The hash is its OWN field, not fused into the path: that is what lets a label
+ * shed a fragment before it sheds a path segment.
+ */
+export function splitUrl(href: string): SplitUrl {
+  if (/^mailto:/i.test(href)) {
+    const mail = href.slice("mailto:".length);
+    const at = mail.lastIndexOf("@");
+    return {
+      domain: at >= 0 ? mail.slice(at + 1) : "",
+      segments: [],
+      hash: "",
+      mail,
+    };
+  }
+  try {
+    const u = new URL(normalizeHref(href));
+    return {
+      domain: u.hostname.replace(/^www\./i, ""),
+      segments: `${u.pathname}${u.search}`.split("/").filter((s) => s.length > 0),
+      hash: u.hash,
+      mail: "",
+    };
+  } catch {
+    // A label is presentation and must not throw on a token `URL` refuses.
+    const noScheme = normalizeHref(href).replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+    const hashAt = noScheme.indexOf("#");
+    const body = hashAt >= 0 ? noScheme.slice(0, hashAt) : noScheme;
+    const slash = body.indexOf("/");
+    return {
+      domain: (slash >= 0 ? body.slice(0, slash) : body).replace(/^www\./i, ""),
+      segments: slash >= 0 ? body.slice(slash).split("/").filter((s) => s.length > 0) : [],
+      hash: hashAt >= 0 ? noScheme.slice(hashAt) : "",
+      mail: "",
+    };
+  }
+}
+
+/**
+ * Join a domain with the segments a candidate keeps.
+ *
+ * `…` claims something was dropped, so it is emitted only when `total` exceeds
+ * what was kept. An unconditional mark reads as correct while standing for
+ * nothing.
+ */
+function join(domain: string, kept: readonly string[], total: number, hash: string): string {
+  // The mark sits where the gap is: between two survivors, or leading when only
+  // the last survives. Always after `kept[0]` would read as `last/…`.
+  const marked =
+    total <= kept.length
+      ? [...kept]
+      : kept.length <= 1
+        ? [ELLIPSIS, ...kept]
+        : [kept[0] as string, ELLIPSIS, ...kept.slice(1)];
+  const body = marked.join("/");
+  return `${domain}${body === "" ? "" : `/${body}`}${hash}`;
+}
+
+/**
+ * A compact, Chrome-omnibox-style label for a url: the domain in full, the
+ * path's middle collapsed, the last segment kept.
+ *
+ * A fragment is shed before a path segment: the last segment names the PAGE, a
+ * fragment only locates a spot inside it. Fusing them into one string puts a
+ * long fragment on the last segment and forces every candidate over budget.
+ *
+ * The last resort truncates the last segment and KEEPS it. Never a bare
+ * `domain/…`, which identifies nothing when every link shares the domain.
+ */
+export function linkChipLabel(href: string, maxChars: number = DEFAULT_MAX_CHARS): string {
+  const { domain, segments, hash, mail } = splitUrl(href);
+
+  if (mail !== "") {
+    if (mail.length <= maxChars) return mail;
+    return `${ELLIPSIS}${mail.slice(mail.length - (maxChars - 1))}`;
+  }
+
+  const total = segments.length;
+  if (total === 0) {
+    const bare = `${domain}${hash}`;
+    return bare.length <= maxChars ? bare : domain;
+  }
+
+  const last = segments[total - 1] as string;
+  const first = segments[0] as string;
+  // Widest first, and at each width the fragment goes before a path segment
+  // does: `domain/cli/daemon/service` beats `domain/…/service#install-options`,
+  // because the segments name the page and the fragment only locates a spot
+  // inside it.
+  const kept: readonly (readonly string[])[] = [
+    segments,
+    total >= 3 ? [first, last] : segments,
+    [last],
+  ];
+  const candidates: readonly string[] = kept.flatMap((k) => [
+    join(domain, k, total, hash),
+    join(domain, k, total, ""),
+  ]);
+  for (const candidate of candidates) {
+    if (candidate.length <= maxChars) return candidate;
+  }
+
+  // Nothing fit, so the last segment is itself too long. Keep the page's own
+  // name, cut to what the domain leaves, so two links into the same domain
+  // still read differently. The leading mark is still conditional: a
+  // single-segment path dropped nothing, and claiming otherwise is the same
+  // lie `join` exists to prevent.
+  const lead = total > 1 ? `${ELLIPSIS}/` : "";
+  const room = Math.max(4, maxChars - domain.length - lead.length - 2);
+  return `${domain}/${lead}${last.slice(0, room)}${ELLIPSIS}`;
+}
+
+/**
+ * Whether an anchor is a BARE url — the reader faces the raw string, with no
+ * label the author chose.
+ *
+ * `text` is the anchor's sole text child, or undefined when the child is not a
+ * lone text node. A formatted label (`**…**`, inline code, several children)
+ * is never bare: the author who formatted a label meant it to read inline.
+ *
+ * The comparison runs on a normalised form so a schemeless `www.` host still
+ * matches: gfm rewrites the URL and leaves the text alone, so raw equality
+ * would fail on exactly the shape a model writes when it elides the scheme.
+ * One comparison rather than a second rule — one place to be wrong.
+ *
+ * A label that IS the url counts, though it is technically a markdown link.
+ * The rule is about what the READER faces, and that is the same either way.
+ */
+export function isBareUrlLink(href: string | undefined, text: string | undefined): boolean {
+  if (href === undefined || text === undefined) return false;
+  const label = text.trim();
+  if (label === "") return false;
+  return stripScheme(href) === stripScheme(label);
+}
+
+/** Drop a leading `http://` or `https://` and any trailing slash. */
+function stripScheme(value: string): string {
+  return value.replace(/^https?:\/\//i, "").replace(/\/+$/, "");
+}
+
+/**
+ * Whether an href is a web target a new tab makes sense for.
+ *
+ * An in-app scheme opened with `target="_blank"` spawns a blank tab
+ * the browser cannot navigate. This is about the navigation target, not about
+ * safety — `rehype-harden` already decides which protocols survive at all.
+ */
+export function isExternalHref(href: string | undefined): boolean {
+  if (href === undefined) return false;
+  return /^(https?|mailto|tel):/i.test(href);
+}