@citisen/litearea 0.1.0

package/scripts/build-css.mjs

@@ -0,0 +1,35 @@
+/**
+ * Write the stylesheet out as a plain CSS file.
+ *
+ * The CSS is authored once, as a string in `src/styles.ts`, so that an editor can
+ * inject it with no CSS loader and no build step. A host that would rather link a
+ * file needs it as a file, and the alternative — a second copy maintained by hand —
+ * is a stylesheet that drifts from the one that is actually used. So the built ESM
+ * module is imported and its string is written here.
+ *
+ * Usage:
+ *   node scripts/build-css.mjs
+ */
+
+import { existsSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const built = join(root, 'dist', 'styles.js')
+
+if (!existsSync(built)) {
+  console.error('build-css: dist/styles.js is missing; run `npm run build` first')
+  process.exit(1)
+}
+
+const { LITEAREA_STYLES } = await import(pathToFileURL(built).href)
+
+if (typeof LITEAREA_STYLES !== 'string' || LITEAREA_STYLES.trim() === '') {
+  console.error('build-css: dist/styles.js did not export a stylesheet')
+  process.exit(1)
+}
+
+const target = join(root, 'dist', 'styles.css')
+writeFileSync(target, `${LITEAREA_STYLES.trimEnd()}\n`, 'utf8')
+console.log(`build-css: wrote ${String(LITEAREA_STYLES.length)} characters to dist/styles.css`)

package/scripts/release.mjs

@@ -0,0 +1,91 @@
+/**
+ * Maintainer-side release helper.
+ *
+ * Publishing is split in two on purpose: CI stages a tarball (see
+ * `.github/workflows/stage.yml`), and a human approves it here, where npm
+ * demands that human's 2FA. A compromised runner or a malicious commit can
+ * therefore stage but never publish.
+ *
+ * `npm stage` needs npm >= 11.6 (12 for the current subcommands) and Node 22.22
+ * / 24.15 / 26+, which the local Node may not satisfy. So rather than requiring
+ * a global npm upgrade, this delegates to `npx npm@12`, and borrows the system
+ * `git` for the OTP flow npm uses for a 2FA-gated web approval.
+ *
+ * Usage:
+ *   node scripts/release.mjs list [package]
+ *   node scripts/release.mjs view <stage-id>
+ *   node scripts/release.mjs approve <stage-id>
+ *   node scripts/release.mjs reject <stage-id>
+ *   node scripts/release.mjs download <stage-id> [--dry-run]
+ */
+
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const [, , subcommand, ...rest] = process.argv
+
+const PACKAGE_NAME = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).name
+const VERSION = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version
+
+/** npm CLI major to run; `npm stage` needs 12 for `list`/`approve`. */
+const NPM_SPEC = 'npm@12'
+
+const USAGE = `usage: node scripts/release.mjs <command> [args]
+
+  list [package]            staged versions (default: ${PACKAGE_NAME})
+  view <stage-id>           details of one staged version
+  approve <stage-id>        publish it — REQUIRES your 2FA
+  reject <stage-id>         discard it
+  download <stage-id>       fetch the staged tarball for inspection
+
+Nothing here publishes without an approval, which is the point: CI can only
+stage.`
+
+const KNOWN = new Set(['list', 'view', 'approve', 'reject', 'download'])
+
+if (subcommand === undefined || subcommand === '--help' || subcommand === '-h') {
+  console.log(USAGE)
+  process.exit(0)
+}
+if (!KNOWN.has(subcommand)) {
+  console.error(`release: unknown command "${subcommand}"\n\n${USAGE}`)
+  process.exit(2)
+}
+if (subcommand !== 'list' && rest.length === 0) {
+  console.error(`release: "${subcommand}" needs a stage-id\n\n${USAGE}`)
+  process.exit(2)
+}
+
+const args = [NPM_SPEC, 'stage', subcommand]
+if (subcommand === 'list') args.push(rest[0] ?? PACKAGE_NAME)
+else args.push(...rest)
+
+console.log(`release: npx ${args.join(' ')}`)
+if (subcommand === 'approve') {
+  console.log('release: approving publishes to the registry and requires your 2FA')
+}
+
+const result = spawnSync('npx', ['--yes', ...args], {
+  cwd: root,
+  stdio: 'inherit',
+  shell: process.platform === 'win32',
+})
+
+if (result.error !== undefined) {
+  if (result.error.code === 'ENOENT') {
+    console.error('release: npx not found on PATH — install Node.js')
+    process.exit(127)
+  }
+  throw result.error
+}
+const exitCode = result.status ?? 1
+
+if (exitCode === 0 && subcommand === 'list') {
+  console.log(`\nrelease: nothing is installable until a stage is approved.`)
+  console.log(`release: a local release runs \`npm run release -- approve <stage-id>\` from v${VERSION}.`)
+}
+
+process.exit(exitCode)

package/scripts/verify-package.mjs

@@ -0,0 +1,253 @@
+/**
+ * Exercise the BUILT package rather than the working tree.
+ *
+ * `npm run typecheck` and `npm run test` both read `src/`, so neither of them can
+ * notice a build that silently dropped an entry point, produced a declaration file
+ * with nothing in it, or failed to write the stylesheet. This is the gate that
+ * imports what would actually be installed and asserts it is all there.
+ *
+ * Usage:
+ *   node scripts/verify-package.mjs [path/to/dist]
+ *
+ * The optional path exists so an INSTALLED copy can be checked, which is the only
+ * way to be sure the tarball is complete rather than the checkout.
+ */
+
+import assert from 'node:assert/strict'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const dist = process.argv[2] ?? join(root, 'dist')
+const packageJson = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+
+/**
+ * Every entry point `package.json` promises, and where its declarations landed.
+ *
+ * The declarations come from `tsc` rather than from the JavaScript bundler, so they
+ * mirror the source tree: the root entry is one file, while `react` and `grammars`
+ * are directories with an `index.d.ts` in them. That extra level is the price of not
+ * depending on a declaration bundler that predates TypeScript 7, and it is encoded
+ * here so a change to the layout cannot pass unnoticed.
+ */
+const ENTRIES = [
+  { name: 'index', declarations: 'types/index.d.ts' },
+  { name: 'react', declarations: 'types/react/index.d.ts' },
+  { name: 'grammars', declarations: 'types/grammars/index.d.ts' },
+  { name: 'styles', declarations: 'types/styles.d.ts' },
+]
+
+/** The names the root entry must export. */
+const CORE_EXPORTS = [
+  'defineGrammar',
+  'defineVocabulary',
+  'defineCompletion',
+  'resolveGrammar',
+  'isResolvedGrammar',
+  'scan',
+  'inspect',
+  'complete',
+  'applyCompletion',
+  'resolveHover',
+  'diagnosticHover',
+  'buildSegments',
+  'fuzzyMatch',
+  'rank',
+  'highlightSegments',
+  'lineAt',
+  'lineStarts',
+  'wordInfoAt',
+  'clamp',
+  'LiteArea',
+  'createEditor',
+  'TextMirror',
+  'injectStyles',
+  'scopeClass',
+  'LITEAREA_STYLES',
+  'readSelection',
+  'writeSelection',
+  'replaceThroughPipeline',
+  'undoField',
+  'redoField',
+  'writeDocument',
+  'canEditThroughPipeline',
+]
+
+/** The names the grammars entry must export. */
+const GRAMMAR_EXPORTS = [
+  'dshFontQueryGrammar',
+  'dshSentryStyleGrammar',
+  'fontWeightWord',
+  'fontFaceWeights',
+  'quoteFontFamily',
+  'FONT_WEIGHT_WORDS',
+  'FONT_GENERIC_FAMILIES',
+]
+
+/** The names the React entry must export. */
+const REACT_EXPORTS = ['LiteAreaEditor']
+
+/** Report a failure the way the rest of the house scripts do. */
+function fail(message) {
+  console.error(`verify-package: ${message}`)
+  process.exit(1)
+}
+
+// ── every file the package promises is on disk ──────────────────────────────
+
+for (const entry of ENTRIES) {
+  for (const extension of ['js', 'cjs']) {
+    const file = join(dist, `${entry.name}.${extension}`)
+    if (!existsSync(file)) fail(`${entry.name}.${extension} is missing — run \`npm run build\``)
+    if (statSync(file).size === 0) fail(`${entry.name}.${extension} is empty`)
+  }
+  const declarations = join(dist, entry.declarations)
+  if (!existsSync(declarations)) {
+    fail(`${entry.declarations} is missing — run \`npm run build\``)
+  }
+  if (statSync(declarations).size === 0) fail(`${entry.declarations} is empty`)
+}
+
+const css = join(dist, 'styles.css')
+if (!existsSync(css)) fail('styles.css is missing — run `npm run build`')
+const cssText = readFileSync(css, 'utf8')
+/** The stylesheet without its comments, since the prose quotes selectors. */
+const cssRules = cssText.replace(/\/\*[\s\S]*?\*\//g, '')
+// The two classes that make the whole arrangement work. A stylesheet without them
+// would ship, install cleanly, and paint nothing.
+for (const selector of ['.litearea-input', '.litearea-layer', '.litearea-popup']) {
+  if (!cssText.includes(selector)) fail(`styles.css does not define ${selector}`)
+}
+
+// ── every scope the stylesheet names is actually painted ───────────────────
+//
+// The variables and the rules that spend them must agree, and they once did not: twenty-nine
+// scope variables were declared with no rule that used one, so the tokenizer painted the right
+// classes and every scope rendered in the inherited text colour. The editor had no syntax
+// colouring at all, the stylesheet looked complete, and the DOM was correct — which is also why
+// a browser check cannot catch it, because a colourless token is an ordinary thing to find.
+const declaredScopes = new Set(
+  [...cssRules.matchAll(/--litearea-scope-([a-z-]+)\s*:/g)].map((match) => match[1]),
+)
+const paintedScopes = new Set(
+  [...cssRules.matchAll(/\.litearea-scope-([a-z-]+)\s*\{/g)].map((match) => match[1]),
+)
+if (paintedScopes.size < 15) {
+  fail(`styles.css has only ${String(paintedScopes.size)} scope colour rules; the palette is not wired up`)
+}
+const unpainted = [...declaredScopes].filter((scope) => !paintedScopes.has(scope))
+if (unpainted.length > 0) {
+  fail(
+    `styles.css declares --litearea-scope-* for ${unpainted.join(', ')} with no rule that uses ` +
+      'them, so those scopes would paint in the inherited colour',
+  )
+}
+for (const scope of paintedScopes) {
+  if (!cssRules.includes(`.litearea-scope-${scope} { color: var(--litearea-scope-${scope}); }`)) {
+    fail(`.litearea-scope-${scope} does not spend its own variable`)
+  }
+}
+// A squiggle is only a squiggle if it is drawn by the browser, and only a stylesheet says how.
+for (const severity of ['error', 'warning']) {
+  if (!new RegExp(`\\.litearea-diag-${severity} \\{[^}]*text-decoration-style: wavy`).test(cssRules)) {
+    fail(`.litearea-diag-${severity} does not draw a wavy underline`)
+  }
+}
+if (cssRules.includes('.litearea-paint > span')) {
+  fail('.litearea-paint > span would outrank the severity classes and switch every squiggle off')
+}
+
+// ── the declarations describe the exports ──────────────────────────────────
+
+const declarations = readFileSync(join(dist, 'types', 'index.d.ts'), 'utf8')
+if (declarations.length < 500) {
+  fail(`types/index.d.ts looks truncated (${String(declarations.length)} bytes)`)
+}
+
+// ── the built modules really export what the declarations claim ────────────
+
+const core = await import(pathToFileURL(join(dist, 'index.js')).href)
+const missing = CORE_EXPORTS.filter((name) => core[name] === undefined)
+if (missing.length > 0) fail(`index.js does not export: ${missing.join(', ')}`)
+
+const grammars = await import(pathToFileURL(join(dist, 'grammars.js')).href)
+const missingGrammars = GRAMMAR_EXPORTS.filter((name) => grammars[name] === undefined)
+if (missingGrammars.length > 0) fail(`grammars.js does not export: ${missingGrammars.join(', ')}`)
+
+const react = await import(pathToFileURL(join(dist, 'react.js')).href)
+const missingReact = REACT_EXPORTS.filter((name) => react[name] === undefined)
+if (missingReact.length > 0) fail(`react.js does not export: ${missingReact.join(', ')}`)
+
+// ── the engine works from the built artifact, not just from source ─────────
+
+const grammar = grammars.dshSentryStyleGrammar()
+const inspection = core.inspect('running  circle  blue  turn   3\nbogus circle', grammar)
+assert.ok(inspection.tokens.length > 0, 'the built engine produced no tokens')
+assert.ok(
+  inspection.diagnostics.some((diagnostic) => diagnostic.code === 'vocabulary:state'),
+  'the built engine did not report the unknown state',
+)
+const completion = core.complete(inspection, grammar, {
+  text: 'running ',
+  caret: 'running '.length,
+  trigger: 'explicit',
+})
+assert.ok(completion !== undefined, 'the built engine offered no completion')
+assert.ok(completion.rows.length > 0, 'the built engine offered an empty completion')
+
+const segments = core.buildSegments(inspection.text, inspection)
+assert.equal(
+  segments.map((segment) => segment.text).join(''),
+  inspection.text,
+  'the built segmenter did not cover the document exactly',
+)
+
+// ── the package metadata points at real files ──────────────────────────────
+
+for (const [key, value] of Object.entries(packageJson.exports ?? {})) {
+  if (typeof value === 'string') {
+    if (!existsSync(join(root, value))) fail(`exports["${key}"] points at ${value}, which does not exist`)
+    continue
+  }
+  for (const condition of ['types', 'import', 'require']) {
+    const target = value[condition]
+    if (target === undefined) fail(`exports["${key}"] has no ${condition} condition`)
+    if (!existsSync(join(root, target))) {
+      fail(`exports["${key}"].${condition} points at ${target}, which does not exist`)
+    }
+  }
+}
+
+// ── the links a reader will click resolve, and will be published ───────────
+//
+// A README is rendered on the package page by npm, where a relative link only works if the
+// file it points at is in the tarball. `docs/grammar.md` was linked from the README and left
+// out of `files`, which is a link that resolves in a checkout and 404s for everyone who
+// installed the package — the kind of mistake that is invisible until a stranger hits it.
+
+const publishedRoots = new Set((packageJson.files ?? []).map((entry) => entry.split('/')[0]))
+
+for (const readme of ['README.md', 'README.zh.md']) {
+  const file = join(root, readme)
+  if (!existsSync(file)) continue
+  const text = readFileSync(file, 'utf8')
+  for (const match of text.matchAll(/\]\(([^)\s]+)\)/g)) {
+    const target = match[1]
+    if (target === undefined) continue
+    if (/^(https?:|mailto:|#)/.test(target)) continue
+    const [path] = target.split('#')
+    if (path === undefined || path === '') continue
+    if (!existsSync(join(root, path))) {
+      fail(`${readme} links to ${path}, which does not exist`)
+    }
+    const top = path.split('/')[0] ?? ''
+    if (top !== readme && !publishedRoots.has(top)) {
+      fail(`${readme} links to ${path}, which \`files\` does not publish — the link would 404 on npm`)
+    }
+  }
+}
+
+console.log(`verify-package: OK — ${String(ENTRIES.length)} entries, ${String(CORE_EXPORTS.length)} core exports`)
+console.log('verify-package: the built engine tokenizes, diagnoses, completes, and segments')
+console.log('verify-package: every relative README link resolves and is published')

package/src/core/complete.ts

@@ -0,0 +1,286 @@
+// ─── complete: turning a caret into a list, and a list into an edit ─────────
+//
+// Two pure functions, deliberately separated, because they fail in different
+// ways and only one of them is interesting to a user.
+//
+// `complete` answers "what could go here?" and returns rows. `applyCompletion`
+// answers "what does the document become?" and returns text plus a caret. Keeping
+// them apart is what makes the hard half — the interaction — testable in Node
+// without a browser, and it is why the two bugs that make a completer feel broken
+// have somewhere to live:
+//
+//   A SOURCE that swaps mid-typing loses the thread. The list opens over a family
+//   name, the user types `=` and it becomes a value list, and the row they were
+//   looking at is gone. So once a source has answered, it keeps answering for as long
+//   as it stays eligible, and the priority order only decides which source OPENS the
+//   list.
+//
+//   A range that does not grow leaves text behind. The range is recomputed from the
+//   caret on every filter, never reused: type `ru`, accept `running`, and the
+//   replacement must cover both letters. Holding the range resolved when the list
+//   opened replaces only the `r` and produces `running u` — a bug worth naming,
+//   because it is invisible in a test that only ever types one character before
+//   accepting.
+
+import type {
+  Completion,
+  CompletionContext,
+  CompletionSource,
+  CompletionTrigger,
+  Grammar,
+  Range,
+  SuggestionItem,
+} from './types.js'
+import type { Inspection } from './inspect.js'
+import { rank, type Ranked } from './rank.js'
+import { clamp, lineAt, lineStarts, scopeAt, tokenBefore, tokensOnLine, wordInfoAt } from './text.js'
+import { isResolvedGrammar, resolveGrammar, type ResolvedGrammar } from './scan.js'
+
+/** The most rows a completion will carry, so a huge catalogue cannot stall a list. */
+const DEFAULT_LIMIT = 100
+
+/** What the editor knows when it asks for a list. */
+export interface CompletionRequest {
+  text: string
+  caret: number
+  trigger: CompletionTrigger
+  /**
+   * The source that answered last time, when a list is already open.
+   *
+   * Passing it is what keeps a list stable while the user types: the same source answers
+   * again for as long as it stays eligible, so typing a character that makes a different
+   * source eligible does not swap the rows out from under the reader. Only the SOURCE is
+   * held — the range is recomputed from the caret every time, so it grows with the word.
+   */
+  previousSourceId?: string | undefined
+  /** The most rows to return. */
+  limit?: number
+}
+
+/**
+ * Resolve a completion for a caret.
+ *
+ * @param inspection - the current inspection of the document.
+ * @param grammar - the language.
+ * @param request - the caret, the trigger, and any list already open.
+ * @returns the range and the rows, or undefined when nothing applies.
+ */
+export function complete<State>(
+  inspection: Inspection<State>,
+  grammar: Grammar<State> | ResolvedGrammar<State>,
+  request: CompletionRequest,
+): Completion | undefined {
+  const resolved = isResolvedGrammar(grammar) ? grammar : resolveGrammar(grammar)
+  const sources = resolved.grammar.compose
+  if (sources === undefined || sources.length === 0) return undefined
+
+  const text = request.text
+  const caret = clamp(request.caret, 0, text.length)
+  const context = completionContext(inspection, resolved, caret, request.trigger)
+
+  const eligible = sources.filter((source) => source.when === undefined || source.when(context))
+  if (eligible.length === 0) return undefined
+
+  // ── which source, and over what range ────────────────────────────────────
+  // Ordered by priority, and the range comes from the winner because two sources
+  // disagreeing about the range have no coherent shared answer.
+  // ── which source ────────────────────────────────────────────────────────
+  // Priority decides which source OPENS the list; after that the source that answered
+  // keeps answering while it remains eligible, so the rows do not change identity under
+  // the reader's hands. The range is not part of this: it is computed fresh below, from
+  // the caret as it is now.
+  const ordered = [...eligible].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0))
+  const reopening =
+    request.previousSourceId === undefined
+      ? undefined
+      : ordered.find((source) => source.id === request.previousSourceId)
+  const winner = reopening ?? ordered[0]
+  if (winner === undefined) return undefined
+  const range = resolveRange(winner, context)
+
+  // ── the rows ─────────────────────────────────────────────────────────────
+  const merged: SuggestionItem[] = [...winner.items(context)]
+  for (const source of ordered) {
+    if (source === winner || source.merge !== true) continue
+    merged.push(...source.items(context))
+  }
+  if (merged.length === 0) return undefined
+
+  // The needle is what the user has typed INSIDE the range, which is the only reading
+  // that stays meaningful when the range is an entry rather than a word. It is clamped
+  // to the range at both ends: a caret can sit past the range — after the trailing space
+  // of an entry, say — and slicing to the caret there would pull a separator into the
+  // needle and filter the list by a character the user did not mean to search for.
+  const needleFrom = clamp(range.from, 0, caret)
+  const needleTo = clamp(caret, needleFrom, Math.max(range.to, needleFrom))
+  const needle = text.slice(needleFrom, needleTo)
+  const ranked: Ranked<SuggestionItem>[] = rank(merged, needle, {
+    label: (item) => item.label,
+    ...(merged.some((item) => item.filterText !== undefined)
+      ? { filterText: (item: SuggestionItem) => item.filterText ?? item.label }
+      : {}),
+    ...(merged.some((item) => item.sortText !== undefined)
+      ? { sortText: (item: SuggestionItem) => item.sortText }
+      : {}),
+  })
+  const limit = request.limit ?? DEFAULT_LIMIT
+
+  return {
+    range,
+    rows: ranked.slice(0, limit).map((entry) => ({
+      item: entry.item,
+      score: entry.score,
+      indices: entry.indices,
+    })),
+    needle,
+    sourceId: winner.id,
+  }
+}
+
+/** Resolve a source's range, whether it declared one or computes it. */
+function resolveRange<State>(
+  source: CompletionSource<State>,
+  context: CompletionContext<State>,
+): Range {
+  if (typeof source.range !== 'function') return source.range
+  const range = source.range(context)
+  return {
+    from: Math.min(range.from, range.to),
+    to: Math.max(range.from, range.to),
+  }
+}
+
+/**
+ * Build everything a completion source may look at.
+ * @param inspection - the current inspection.
+ * @param resolved - the resolved grammar.
+ * @param caret - the caret offset.
+ * @param trigger - how the list came to be open.
+ * @returns the context.
+ */
+function completionContext<State>(
+  inspection: Inspection<State>,
+  resolved: ResolvedGrammar<State>,
+  caret: number,
+  trigger: CompletionTrigger,
+): CompletionContext<State> {
+  const { text, tokens, diagnostics, state } = inspection
+  const line = lineAt(text, caret, lineStarts(text))
+  const lineTokens = tokensOnLine(tokens, line.number)
+  const word = wordInfoAt(text, caret, resolved.wordChars)
+  return {
+    text,
+    caret,
+    word,
+    line,
+    tokens,
+    diagnostics,
+    state,
+    scope: scopeAt(tokens, caret),
+    scopeBefore: tokenBefore(tokens, caret)?.scope,
+    // "First on line" means only whitespace precedes the caret, which is a question
+    // about the caret and not about the token under it: a caret in the indentation of
+    // a line that already has content is not first on that line. `lineTokens` is what
+    // tells the difference, so the tokens are read even though the answer looks like a
+    // string test.
+    firstOnLine: line.before.trim() === '' && !lineTokens.some((token) => token.to <= caret),
+    // "First word" additionally allows the rest of the word the caret is in, which is
+    // what keeps a line-head completion alive while the head is being typed.
+    firstWord: line.text.slice(0, Math.max(0, word.from - line.from)).trim() === '',
+    firstToken: lineTokens[0],
+    trigger,
+  }
+}
+
+/** An edit produced by accepting a row. */
+export interface AppliedCompletion {
+  /** The document after the edit. */
+  text: string
+  /** Where the caret belongs in it. */
+  caret: number
+  /**
+   * What changed, in the NEW document. The editor uses it to scroll the result
+   * into view and to describe the edit to a host.
+   */
+  range: Range
+  /**
+   * The offset the edit starts at in the ORIGINAL document.
+   *
+   * Exposed alongside `insert` because an editor must write only the range that
+   * changed. Assigning the whole recomputed `text` would be simpler and would throw
+   * away the browser's undo history, which is the one thing this library exists to
+   * protect.
+   */
+  from: number
+  /** The offset the edit ends at in the original document. */
+  to: number
+  /** The text written between those two offsets. */
+  insert: string
+}
+
+/**
+ * Apply a chosen row to a document.
+ *
+ * The row decides three things: what is written, whether it is written over the
+ * range or in front of it, and how much text follows it. `append` is the
+ * grammar's business and not the engine's — inviting another entry with a `, `
+ * is a fact about font stacks, and an engine that appended one by default would
+ * be guessing about every other language.
+ *
+ * @param text - the document.
+ * @param range - the range the list was opened over.
+ * @param item - the chosen row.
+ * @returns the resulting text, caret, and the edit that produced them.
+ */
+export function applyCompletion(text: string, range: Range, item: SuggestionItem): AppliedCompletion {
+  const from = clamp(Math.min(range.from, range.to), 0, text.length)
+  const to = clamp(Math.max(range.from, range.to), from, text.length)
+  const insert = item.insert ?? item.label
+  const append = item.append ?? ''
+  const offset = item.caretOffset ?? 0
+
+  if (item.mode === 'before') {
+    const head = text.slice(0, from)
+    // The whitespace in front of the existing entry belonged to the comma before
+    // it, so it is restored rather than doubled.
+    const gap = head !== '' && !/\s$/.test(head) ? ' ' : ''
+    const rest = text.slice(from).replace(/^\s+/, '')
+    const written = `${gap}${insert}${redundant(append, rest) ? '' : append}`
+    return {
+      text: `${head}${written}${rest}`,
+      caret: head.length + written.length + offset,
+      range: { from: head.length, to: head.length + written.length },
+      from,
+      to: from,
+      insert: written,
+    }
+  }
+
+  const head = text.slice(0, from)
+  const rest = text.slice(to)
+  const written = `${insert}${redundant(append, rest) ? '' : append}`
+  return {
+    text: `${head}${written}${rest}`,
+    caret: head.length + written.length + offset,
+    range: { from: head.length, to: head.length + written.length },
+    from,
+    to,
+    insert: written,
+  }
+}
+
+/**
+ * Whether an append would only repeat what the document already says.
+ *
+ * Accepting `running` immediately before an existing space must not produce two,
+ * and accepting a font family immediately before an existing `, ` must not add
+ * another comma. Whitespace is compared as whitespace rather than as the exact
+ * characters, so a tab counts as the space an append was reaching for.
+ * @param append - the row's `append` text.
+ * @param rest - the document immediately after the range.
+ * @returns whether the append should be left out.
+ */
+function redundant(append: string, rest: string): boolean {
+  if (append === '') return true
+  return append.trim() === '' ? /^\s/.test(rest) : rest.startsWith(append)
+}