# paratext/link

> Every export of paratext/link, with its signature and doc comment: LINK, supportsLink, linkFor, link.

Source: https://paratext.interlace.tools/docs/api/link

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`paratext/link` — OSC 8, and nothing else.

**Why this subpath exists.** `burgee`'s `--help` wanted a real hyperlink on a supporting
terminal and `Docs (https://x.dev)` on a pipe, and could not take the dependency: `help.ts`
is imported *statically* by `execute.ts`, so anything help reaches is in the cold-start
graph of `burgee foo --json` too, and paratext published nothing narrower than its 17,574 B
root, which runs `registerBuiltins()` at import. This entry is 2,337 B and registers
nothing — there is no registry in its graph. See spec.md R13.

**What it gives up, said plainly.** `link()` here reads {@link LINK} directly, so a caller
who corrected our guess by re-registering `link` on the global registry does not change
what this returns — that registry is the thing this module deliberately does not load. A
host that wants the registry's answer imports `paratext` and calls `emit(runtime, 'link',
…)`. The record itself is shared: `builtins.ts` re-exports it as `link`, so the capability
the registry ships and the one this subpath emits are one object, not two that drift.

`weight.test.ts` pins the reachability and the budget; `link.test.ts` pins the bytes and
the absent side effect.

```ts
import { LINK, supportsLink, linkFor, … } from 'paratext/link';
```

## Constants

### link

`link(text, url)` against the real process — the `ansi-escapes` and `terminal-link` shape,
for a caller with no `Runtime` of its own. The OSC 8 sequence where the terminal is
believed to understand it, `Docs (https://x.dev)` everywhere else; never raw OSC into a
pipe, never a bare `Docs` with the destination silently dropped.

```ts
const link: (text: string, url: string) => string;
```

### LINK

OSC 8 — a hyperlink. The widest support in this layer, and unusually semi-detectable: VTE
publishes its version and Windows Terminal sets a session variable.

The fallback is `text (url)`, not bare text: a link whose destination vanishes in a pipe
has lost the half that mattered. The optional group makes a link with no url just its text.

```ts
const LINK: Capability;
```

### linkFor

`link(text, url)` bound to a runtime you supply — the form a host should use. `burgee`'s
help renderer already carries a `Runtime`, and taking it as an argument means the whole
path is pure: a test is a two-line literal, and rendering help for somebody else's
terminal is the same call.

```ts
const linkFor: (runtime: Runtime) => (text: string, url: string) => string;
```

### supportsLink

Whether `runtime` is believed to render OSC 8.

For a renderer deciding *layout* rather than bytes — a help screen that prints a `Docs`
column only where the URL will not be repeated in parentheses. A caller that only wants
the string does not need this: {@link linkFor} already answers it. The guess itself is
`LINK.when`, and it is data a caller may replace.

```ts
const supportsLink: (runtime: Runtime) => boolean;
```