@kirchdev/duxt 0.1.0

package/app/utils/aside.ts

@@ -0,0 +1,16 @@
+import type { InjectionKey } from 'vue';
+
+/**
+ * A layout's answer to "is there room on the right?".
+ *
+ * `pages/[...slug].vue` draws the contents column, the aside's links and the
+ * page's provenance in one sticky column, and for almost every page that is
+ * right. A layout that fills the same side itself — `reference`, whose
+ * operations put the request client there — provides `false` and the page
+ * leaves the space alone.
+ *
+ * Provided rather than matched on a layout name: the layout is the only thing
+ * that knows what it draws, and a name in a list in the page is a rule that
+ * goes stale the first time a consumer ships a layout of their own.
+ */
+export const DUXT_ASIDE: InjectionKey<boolean> = Symbol('duxt-aside');

package/app/utils/changelog.ts

@@ -0,0 +1,182 @@
+/**
+ * What a release history needs beyond the pages the parser writes: the anchor a
+ * group is linked at, the colour it is drawn in, and the day it was cut.
+ *
+ * Here rather than in the components because TWO PLACES have to agree about an
+ * id — the heading `ChangelogGroup` draws, and the contents column built from
+ * the page's own AST (`generated-toc.ts`), which never sees that component
+ * render. A slug computed twice is a contents column whose links go nowhere.
+ *
+ * Named exports rather than auto-imports read from a test: the same reason
+ * `generated-sections.ts` gives, and the same tests.
+ */
+
+/**
+ * The anchor a group heading gets, or nothing when the name has no ASCII in it.
+ *
+ * Undefined rather than a fallback: a heading a component draws is not in the
+ * outline Content slugifies, so there is nothing upstream to fall back TO, and
+ * pointing every group of every release at `#` is worse than not linking one.
+ */
+export function changelogAnchor(name: string): string | undefined {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || undefined
+  );
+}
+
+/**
+ * The mark a release tool puts in FRONT of a heading, dropped.
+ *
+ * `\p{S}` is symbols — the `⚠` release-please writes on its breaking block, an
+ * emoji a hand-kept changelog opens a section with. LEADING ONLY: a name that
+ * uses a symbol anywhere else keeps it, so `C++ Support` survives, and a
+ * heading that is nothing BUT a mark comes back untouched rather than emptied.
+ *
+ * The stored name stays whole either way. This is what a label SHOWS — never
+ * what the filter matches, what the anchor is built from, or what travels as a
+ * prop — which is also why the mark is drawn away rather than parsed away: the
+ * file said it, and a site that wants it back overrides the component instead
+ * of the changelog.
+ */
+export function changelogLabel(name: string): string {
+  return name.replace(/^[\p{S}\s]+/u, '').trim() || name;
+}
+
+/** The classes one group is drawn with: a dot, a run of text, a filter chip. */
+export interface DuxtChangelogTone {
+  /** A filled dot — the group's identity wherever the name is already there. */
+  dot: string;
+  /**
+   * The NAME set in the tone, for the label a release page heads its group
+   * with.
+   *
+   * A separate value rather than the dot's colour reused, because a filled
+   * shape and a run of text do not clear contrast at the same lightness: the
+   * `500` a 6-pixel dot is drawn in is well under the floor for words.
+   *
+   * `700` / `400` is the most saturated pair the ramp offers that still clears
+   * AA on both grounds — measured, not picked: on white, `600` fails for four
+   * of the six hues (amber 3.2, emerald 3.7, cyan 3.7, sky 4.1), so the light
+   * side stops at `700`. The dark side has the room, which is why it takes
+   * `400` rather than the `300` the chip uses: on the page background it
+   * measures 7.0–11.5 and on a card 6.3–10.4, and it is the half a reader of a
+   * dark site actually sees.
+   */
+  text: string;
+  /** A tinted surface with a matching ring, for the filter chip. */
+  chip: string;
+}
+
+/**
+ * The palette, as `DuxtOpenApiMethod` builds one: Tailwind's ramp with a
+ * lighter text in dark mode, so every pair clears the contrast floor in both
+ * themes without adding six token pairs a consumer would have to override.
+ */
+const TONES: DuxtChangelogTone[] = [
+  {
+    dot: 'bg-emerald-500',
+    text: 'text-emerald-700 dark:text-emerald-400',
+    chip: 'bg-emerald-500/10 text-emerald-700 ring-emerald-500/30 dark:text-emerald-300'
+  },
+  {
+    dot: 'bg-sky-500',
+    text: 'text-sky-700 dark:text-sky-400',
+    chip: 'bg-sky-500/10 text-sky-700 ring-sky-500/30 dark:text-sky-300'
+  },
+  {
+    dot: 'bg-amber-500',
+    text: 'text-amber-700 dark:text-amber-400',
+    chip: 'bg-amber-500/10 text-amber-700 ring-amber-500/30 dark:text-amber-300'
+  },
+  {
+    dot: 'bg-violet-500',
+    text: 'text-violet-700 dark:text-violet-400',
+    chip: 'bg-violet-500/10 text-violet-700 ring-violet-500/30 dark:text-violet-300'
+  },
+  {
+    dot: 'bg-rose-500',
+    text: 'text-rose-700 dark:text-rose-400',
+    chip: 'bg-rose-500/10 text-rose-700 ring-rose-500/30 dark:text-rose-300'
+  },
+  {
+    dot: 'bg-cyan-500',
+    text: 'text-cyan-700 dark:text-cyan-400',
+    chip: 'bg-cyan-500/10 text-cyan-700 ring-cyan-500/30 dark:text-cyan-300'
+  }
+];
+
+/**
+ * The names that get the colour a reader expects, keyed by an English word the
+ * heading CONTAINS.
+ *
+ * A HINT, never a taxonomy — which is the whole difference from a mapping the
+ * parser would have needed. `sections-changelog.ts` takes group names verbatim
+ * because a fixed set fails silently on the first heading it does not know;
+ * here the failure is that a group is drawn cyan instead of green, and the
+ * fallback below still gives it a colour of its own. So the list stays short
+ * and covers what release-please and Keep a Changelog write, and a changelog
+ * kept in another language simply falls through to the hash.
+ */
+const BREAKING = /break|inkompat|incompat/i;
+
+const HINTS: [RegExp, number][] = [
+  [BREAKING, 4],
+  [/feat|added|neu/i, 0],
+  [/fix|bug|behoben/i, 2],
+  [/perf/i, 3],
+  [/doc/i, 1],
+  [/deprecat|remov|revert/i, 4],
+  [/depend|chore|build|ci|refactor|misc/i, 5]
+];
+
+/**
+ * A stable colour for a group name.
+ *
+ * The fallback is a hash rather than one grey for everything, because the point
+ * of the colour is that a reader scanning forty releases finds the same kind of
+ * change in the same colour every time — which a hash gives in any language,
+ * for any heading, with nothing configured.
+ */
+export function changelogTone(name: string): DuxtChangelogTone {
+  for (const [pattern, index] of HINTS) {
+    if (pattern.test(name)) return TONES[index]!;
+  }
+
+  let hash = 0;
+  for (const character of name) {
+    hash = (hash * 31 + character.codePointAt(0)!) % 0xffffffff;
+  }
+
+  return TONES[hash % TONES.length]!;
+}
+
+/**
+ * A release day, in the reader's language.
+ *
+ * `timeZone: 'UTC'` because the value is a calendar date and not a moment: read
+ * as local time, `2026-09-08` is the 7th for every reader west of Greenwich —
+ * and a different day on the server than in the browser, which is a hydration
+ * mismatch as well as a wrong date.
+ *
+ * Here rather than beside one of its callers because TWO of them draw it — the
+ * timeline on the overview and the meta row on the release page — and a date
+ * formatted in two places is two chances to print two different days for one
+ * release.
+ */
+export function changelogDate(
+  value: string | undefined,
+  locale: string
+): string | undefined {
+  if (!value) return undefined;
+
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return undefined;
+
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: 'medium',
+    timeZone: 'UTC'
+  }).format(date);
+}

package/app/utils/code-highlight.ts

@@ -0,0 +1,116 @@
+import { grammars as generated } from '#build/duxt-grammars.mjs';
+
+/**
+ * The generated map, annotated here rather than trusted from the declaration.
+ *
+ * `writeGrammars` writes both the module and its `.d.ts`, and the file cannot
+ * import Shiki's own types to describe itself with — so the shape is stated at
+ * the one place that uses it.
+ */
+const grammars = generated as Record<string, () => Promise<unknown>>;
+
+/**
+ * Highlight code the site builds at RUNTIME, with the themes the fences use.
+ *
+ * Content highlights every Markdown fence at build time, and three things on
+ * this site never pass through it: the package-manager block's command, which
+ * is assembled from a prop; the example bodies and responses the API reference
+ * derives from a schema; and the request samples the try-it client rewrites on
+ * every keystroke. All of them came out as flat grey text beside fences that
+ * were coloured, which reads as the highlighter being switched off.
+ *
+ * BUILT ON `shiki/core`, not on the bundled entry, because this one runs in the
+ * BROWSER too — the sample changes as the reader types, and the server cannot
+ * re-render it. The bundled entry carries every grammar Shiki ships; the core
+ * takes only what this site actually generates, plus the JavaScript regex
+ * engine, which is what keeps the WASM out of the chunk. Loaded on demand either
+ * way, and cached for the life of the process.
+ *
+ * THE GRAMMAR SET IS GENERATED, from the samples a site configured — see
+ * `writeGrammars` in `modules/config.ts`. It used to be three names hard-coded
+ * here, which was right while the samples were `curl` and `fetch` and wrong the
+ * moment `duxt.requestSamples` became a list a consumer writes: a Python sample
+ * needs a Python grammar, and nobody wants to ship one to a site that has no
+ * Python sample. Every language in the map is bytes a reader downloads, which is
+ * exactly why the map is not simply all of Shiki.
+ *
+ * `defaultColor: false` emits both themes as custom properties per token,
+ * matching how Content's own output is styled.
+ */
+type Highlighter = {
+  codeToHtml: (code: string, options: object) => string;
+};
+
+/**
+ * Spellings that are not grammar names.
+ *
+ * Shiki resolves its own aliases once a grammar is loaded, but the map above is
+ * keyed by the names the samples declare — so a `ts` fence has to be pointed at
+ * `typescript` before the lookup, not after it.
+ */
+const aliases: Record<string, string> = {
+  curl: 'bash',
+  js: 'typescript',
+  javascript: 'typescript',
+  sh: 'bash',
+  shell: 'bash',
+  ts: 'typescript'
+};
+
+let highlighter: Promise<Highlighter> | undefined;
+
+async function load(): Promise<Highlighter> {
+  const [{ createHighlighterCore }, { createJavaScriptRegexEngine }] =
+    await Promise.all([
+      import('shiki/core'),
+      import('shiki/engine/javascript')
+    ]);
+
+  return createHighlighterCore({
+    themes: [
+      import('shiki/themes/github-light.mjs'),
+      import('shiki/themes/github-dark.mjs')
+    ],
+    // Cast because the generated module is written by `writeGrammars` and
+    // cannot import Shiki's `LanguageRegistration` to type itself with — the
+    // values ARE those modules, which is what the loaders resolve to.
+    langs: Object.values(grammars).map((grammar) => grammar()) as Parameters<
+      typeof createHighlighterCore
+    >[0]['langs'],
+    engine: createJavaScriptRegexEngine()
+  }) as Promise<Highlighter>;
+}
+
+/**
+ * The language, when it is one this site generates and highlights.
+ *
+ * Undefined for everything else, which is how a block asks for plain text
+ * rather than for a grammar the core highlighter was never given: an unknown
+ * `lang` makes Shiki throw, and a response body labelled `xml` must not take
+ * the page with it.
+ */
+export function duxtCodeLang(lang?: string): string | undefined {
+  if (!lang) return undefined;
+
+  const value = lang.toLowerCase();
+  const resolved = aliases[value] ?? value;
+
+  return resolved in grammars ? resolved : undefined;
+}
+
+export async function highlightCode(
+  code: string,
+  lang = 'bash'
+): Promise<string> {
+  // One highlighter for the process: loading the grammars per call would repeat
+  // the most expensive part of this for every command on the page.
+  highlighter ??= load();
+
+  const shiki = await highlighter;
+
+  return shiki.codeToHtml(code, {
+    lang,
+    themes: { light: 'github-light', dark: 'github-dark' },
+    defaultColor: false
+  });
+}

package/app/utils/duxt-config.ts

@@ -0,0 +1,185 @@
+/**
+ * The layer's defaults, and how a consumer's config is merged over them.
+ *
+ * Nuxt merges app.config with defu, which CONCATENATES arrays: a consumer
+ * setting `navigation: [...]` would get its own entries plus the layer's, in
+ * that order, with no way to remove ours. Every list here would be unusable.
+ *
+ * So the layer ships no lists in app.config at all. It keeps them here and
+ * merges them itself, replacing arrays instead of appending to them — a
+ * consumer's list is the list. Objects still merge key by key, so overriding
+ * `footer.note` leaves `footer.columns` alone.
+ */
+export const duxtDefaults: DuxtConfig = {
+  // A placeholder, not a name. The layer cannot know what a site is called,
+  // and `title` is read by thirteen call sites — the title template, the 404,
+  // the brand, the OG card, schema.org, llms.txt and the feed — several of
+  // which interpolate it into a template literal and would print the word
+  // `undefined` rather than degrade. So a neutral, translated word stands in
+  // until a consumer sets its own. It names nobody, which is the whole test.
+  title: 'duxt.defaults.title',
+
+  // No `version`. The layer knows nothing about the state of somebody else's
+  // project, and a default made every site that extended it wear a number it
+  // had never set — in the hero pill and, for a site with at most one source,
+  // in the header badge beside the search. A site that has a version says so
+  // in its own `app.config.ts`; `DuxtVersion` draws nothing until it does.
+
+  navigation: [
+    // No `to`: the header resolves it to the first section, so the entry works
+    // whether or not the consumer's URLs carry a prefix.
+    //
+    // One entry where `sections` and `links` ship empty, because "Docs" names
+    // the INTERFACE and not a tree or a repository. The dropdown that used to
+    // sit beside it pointed at duxt's own tech stack — five links belonging to
+    // this project and to no site that extends it. It lives in
+    // `www/app/app.config.ts` now.
+    { label: 'duxt.defaults.navigation.docs', icon: 'lucide:book-open-text' }
+  ],
+
+  /**
+   * Empty, like `links` below — and for a reason one step further out.
+   *
+   * The section row names the top-level parts of a documentation TREE, and the
+   * tree belongs to the consumer. Shipping "Get started / Concepts / Guides /
+   * Reference" pointing at `/getting-started`, `/concepts`, … was the layer
+   * guessing at somebody else's folder names: a site whose docs are shaped
+   * differently got four tabs leading nowhere, and every one of them looked
+   * like a bug in duxt rather than a default it had never been told to change.
+   *
+   * Those labels were duxt's OWN documentation showing through the layer, so
+   * their translations left with them — `duxt.defaults.*` translates the interface
+   * layer draws, never content a site writes.
+   *
+   * Left empty, the row does not render and the sidebar falls back to the whole
+   * tree, which is the right shape for a site that has not split its docs into
+   * sections at all. duxt's own sections live in `www/app/app.config.ts`.
+   */
+  sections: [],
+
+  /**
+   * Empty, like `footer.legal`.
+   *
+   * These are the icon links on the right of the navbar, and they belong to
+   * whoever runs the site. Shipping duxt's own repository here gave a stranger
+   * extending the layer a GitHub icon pointing at somebody else's project —
+   * the same mistake the legal row already settled. kirchDev's own links live
+   * in `www/app/app.config.ts`, where they are an example rather than a
+   * default.
+   *
+   * Their i18n keys went with them. `duxt.defaults.*` translates the defaults
+   * the layer itself ships and nothing else — it is not a vocabulary for
+   * consumers to reach into. A consumer that did would depend on a key it
+   * cannot see being renamed, and i18n answers a missing key by printing the
+   * key, so the break would be silent. Consumers write a literal, their own
+   * key, or the record form; `www` is the worked example of the third.
+   */
+  links: [],
+
+  /** Which package managers a command block offers, in the order it shows them. */
+  packageManagers: ['pnpm', 'npm', 'yarn', 'bun'],
+
+  /** A flat docs tree gets a trail that only repeats its own section name. */
+  breadcrumb: true,
+
+  landing: {
+    // No badge, no headline, no description. A pill above the headline says
+    // something about the state of a project — "beta", "v2 is out" — and the
+    // headline and the paragraph under it say what the project IS. The layer
+    // knows none of the three. Those two were duxt's OWN marketing showing
+    // through every site that extended it; they live in `www/app/app.config.ts`
+    // now, in the record form, because the Nitro routes that read them have no
+    // i18n — see `server/utils/duxt-server-text.ts`.
+    //
+    // Unset, the h1 falls back to `title` and the paragraph does not render at
+    // all. Set `landing.badge`, `landing.headline` or `landing.description`
+    // and each appears.
+
+    // One action, and a generic one: "read the docs" is true of every site
+    // built on this layer. A second button pointing at duxt's own repository
+    // was not — see `links` above.
+    // No `to`, for the same reason the section row above ships empty: the
+    // layer knows that a site HAS documentation, never what its first page is
+    // called. The landing resolves it to the first section, or to `/`.
+    actions: [
+      {
+        label: 'duxt.defaults.landing.actions.docs',
+        icon: 'lucide:arrow-right'
+      }
+    ],
+    /**
+     * Empty, like `sections` and `links` above.
+     *
+     * The six cards that used to sit here described duxt — its source list, its
+     * git-native sourcing, its shadcn-vue base. That is duxt's own marketing
+     * copy, not a default another site would keep: a stranger extending the
+     * layer got a landing page selling somebody else's project.
+     *
+     * Their translations left with them — `duxt.defaults.*` translates the
+     * interface the layer draws, never content a site writes. duxt's own cards
+     * live in `www/app/app.config.ts`, where each one POINTS at the page that
+     * explains it, which the layer could never know.
+     *
+     * Left empty, the band does not render: the landing gates the whole section
+     * on `duxt.landing?.features?.length`.
+     */
+    features: []
+  },
+
+  /**
+   * Title only, no links — same reasoning as `links` above.
+   *
+   * "Star on GitHub" that stars duxt, an issue tracker that is not yours and a
+   * Discord that is somebody else's community are worse than an empty column.
+   * The block draws nothing until a consumer fills it.
+   *
+   * The title is the exception that stays: "Community" is interface text the layer
+   * draws itself, in every language it ships, and it is not anybody's link.
+   */
+  aside: {
+    title: 'duxt.defaults.aside.title'
+  }
+};
+
+type Plain = Record<string, unknown>;
+
+const isPlainObject = (value: unknown): value is Plain =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Merge objects key by key; an array on the left replaces the one on the right. */
+export function mergeDuxtConfig<T>(over: unknown, base: T): T {
+  if (Array.isArray(over)) return over as T;
+  if (over === undefined) return base;
+  if (!isPlainObject(over) || !isPlainObject(base)) return over as T;
+
+  const result: Plain = { ...base };
+  for (const [key, value] of Object.entries(over)) {
+    result[key] = mergeDuxtConfig(value, (base as Plain)[key]);
+  }
+
+  return result as T;
+}
+
+/**
+ * How many ROWS a band draws, which is not always one.
+ *
+ * The bands alternate — prose left, prose right, prose left — and the side is
+ * decided by position. A split try-it client is two rows inside one band, so
+ * counting bands puts every band after it on the side it just used. Counting
+ * rows is what keeps the page alternating across it.
+ *
+ * Pure, and here rather than in the component, because the page needs the
+ * answer BEFORE it renders the band: the offset of band four depends on how
+ * many rows bands one to three drew.
+ */
+export function duxtShowcaseRows(showcase: {
+  full?: boolean;
+  demo?: { type?: string; layout?: string };
+}): number {
+  const demo = showcase.demo;
+  if (demo?.type !== 'operation') return 1;
+
+  const layout = demo.layout ?? (showcase.full ? 'split' : 'panel');
+
+  return layout === 'split' ? 2 : 1;
+}

package/app/utils/duxt-text.ts

@@ -0,0 +1,135 @@
+/**
+ * A configured string that may also be a translation.
+ *
+ * Three shapes, because they serve three different consumers and none of them
+ * is served well by the other two:
+ *
+ *  - a LITERAL — `'Guide'` — for the single-language site, which is most of
+ *    them, and which must not have to learn i18n to name a navbar entry;
+ *  - a KEY — `'nav.guide'` — for the site that already has locale files and
+ *    wants the theme's own interface text to live in them;
+ *  - a RECORD — `{ 'en-GB': 'Guide', 'de-DE': 'Anleitung' }` — for the site
+ *    with two languages and eight labels, where creating and registering a
+ *    locale file per language costs more than it saves.
+ *
+ * A literal and a key are the same TYPE, and the difference between them is
+ * decided by whether the key is registered, never by a heuristic on the text.
+ */
+
+/** How a string is looked up. Returns undefined when nothing is registered. */
+export type DuxtTextLookup = (key: string) => string | undefined;
+
+/**
+ * Config keys whose values are prose.
+ *
+ * An allowlist rather than a walk over every string: `to`, `icon`, `variant`,
+ * `prefix` and `collection` are also strings, and running a URL through a
+ * translation lookup is how a link silently becomes something else.
+ */
+const TEXT_KEYS = new Set([
+  'badge',
+  'copyright',
+  'description',
+  'group',
+  'headline',
+  // A heading whose list is a sibling rather than a child, so it cannot be
+  // spelled `title` and be resolved by the entry above. A prose key added
+  // WITHOUT a line here does not fail — it renders its own locale record as
+  // JSON on the page, which is exactly how this one was found.
+  'highlightsTitle',
+  'label',
+  'title'
+]);
+
+/**
+ * A locale code, as a record's keys are written: `en`, `en-GB`, `zh-Hant-TW`.
+ *
+ * Needed because a text key may now hold something that is NOT a text: a badge
+ * is `{ label, icon, variant, to }`, and a record of locales is
+ * `{ 'en-GB': …, 'de-DE': … }`. Both are objects of strings, so the values
+ * cannot tell them apart — the KEYS can, and a config field whose keys are all
+ * locale codes is a locale record. `to` alone would match, which is why every
+ * key has to: `label` never will.
+ */
+const LOCALE_CODE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
+/** Whether a value is a text to resolve, rather than a tree to walk into. */
+function isTextValue(value: unknown): boolean {
+  if (typeof value === 'string') return true;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+
+  const entries = Object.entries(value);
+  return (
+    entries.length > 0 &&
+    entries.every(
+      ([key, entry]) => typeof entry === 'string' && LOCALE_CODE.test(key)
+    )
+  );
+}
+
+/** One value: key if one is registered, own language, base language, or as written. */
+export function resolveDuxtText(
+  value: unknown,
+  locale: string,
+  lookup: DuxtTextLookup
+): unknown {
+  if (typeof value === 'string') return lookup(value) ?? value;
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const record = value as Record<string, string>;
+    if (Object.values(record).some((entry) => typeof entry !== 'string')) {
+      return value;
+    }
+
+    // `pt-BR` falls back to any `pt-*` the record does carry, mirroring what
+    // the locale FILES already do — a record written for `pt-PT` should not
+    // leave a Brazilian reader with English.
+    const base = locale.split('-')[0];
+    const sameLanguage = Object.entries(record).find(
+      ([code]) => code.split('-')[0] === base
+    );
+
+    return record[locale] ?? sameLanguage?.[1] ?? Object.values(record)[0];
+  }
+
+  return value;
+}
+
+/** The same, over a whole config tree: only the keys above are touched. */
+export function resolveDuxtTexts<T>(
+  node: T,
+  locale: string,
+  lookup: DuxtTextLookup
+): T {
+  if (Array.isArray(node)) {
+    return node.map((entry) =>
+      resolveDuxtTexts(entry, locale, lookup)
+    ) as unknown as T;
+  }
+
+  if (!node || typeof node !== 'object') return node;
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(node)) {
+    // A text key may carry a structure instead — `badge` takes either a text or
+    // a whole badge — so the value decides, not the key alone.
+    result[key] =
+      TEXT_KEYS.has(key) && isTextValue(value)
+        ? resolveDuxtText(value, locale, lookup)
+        : resolveDuxtTexts(value, locale, lookup);
+  }
+
+  return result as T;
+}
+
+/**
+ * A text field where a plain string is required — an aria-label, a title
+ * attribute, a list key.
+ *
+ * The config type keeps `DuxtText` because that is what a consumer may WRITE;
+ * by the time a component reads the value, `useDuxtConfig` has resolved it.
+ * This states that narrowing without asserting it: an unresolved record yields
+ * undefined rather than `[object Object]` in the DOM.
+ */
+export const asText = (value: DuxtText | undefined): string | undefined =>
+  typeof value === 'string' ? value : undefined;