@kirchdev/duxt 0.3.4 → 0.3.5-dev-main.43-3310f4b

package/app/utils/changelog.ts

@@ -152,31 +152,3 @@ export function changelogTone(name: string): DuxtChangelogTone {
 
   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

@@ -52,9 +52,11 @@ const aliases: Record<string, string> = {
   curl: 'bash',
   js: 'typescript',
   javascript: 'typescript',
+  md: 'markdown',
   sh: 'bash',
   shell: 'bash',
-  ts: 'typescript'
+  ts: 'typescript',
+  yml: 'yaml'
 };
 
 let highlighter: Promise<Highlighter> | undefined;

package/app/utils/contributor-avatar.ts

@@ -0,0 +1,27 @@
+/**
+ * The picture beside a contributor's name, from the template a site configured.
+ *
+ * Here rather than beside either caller because TWO PLACES draw the same
+ * people — the meta column of a page (`DuxtPageInfo`) and the release history
+ * (`ChangelogReleases`) — and a template interpolated twice is two chances to
+ * show a face on one surface and a letter on the other.
+ *
+ * `duxt.contributors.avatarUrl` holds the whole URL with `{username}` in it, so
+ * a site pointing at a different forge, an avatar proxy or nothing at all is a
+ * config change rather than a component fork. UNDEFINED WHERE THERE IS NO
+ * HANDLE, which is the honest answer and not a placeholder: git only carries a
+ * username in a noreply address, and a guessed avatar is a picture of somebody
+ * else.
+ *
+ * A plain replacement, deliberately not an encoding pass: every caller here
+ * takes its username from `githubUsername`, which reads it out of an address
+ * GitHub itself issued.
+ */
+export function contributorAvatar(
+  template: string | undefined,
+  username: string | undefined
+): string | undefined {
+  if (!template || !username) return undefined;
+
+  return template.replace('{username}', username);
+}

package/app/utils/direction.ts

@@ -0,0 +1,43 @@
+/**
+ * Which way round the interface is drawn.
+ *
+ * `auto` is deliberately absent. i18n lets a locale declare it, but it is a
+ * per-element CONTENT heuristic — the browser guessing at a run of text — and
+ * not a layout direction. Chrome cannot be mirrored on "it depends", so the
+ * resolver below collapses it to `ltr` rather than carrying a third state that
+ * nothing downstream could act on.
+ */
+export type DuxtDirection = 'ltr' | 'rtl';
+
+/** The shape i18n hands back from `locales`: objects, or bare codes. */
+export type DuxtLocaleEntry =
+  | string
+  | { code: string; dir?: 'ltr' | 'rtl' | 'auto' };
+
+/**
+ * The direction the active locale declares, or left-to-right.
+ *
+ * THE DECLARATION IS THE ONLY SOURCE. The layer does not keep a list of
+ * right-to-left languages and does not guess from a script or a region: a
+ * locale is right-to-left because its entry says `dir: 'rtl'`, which is the
+ * one place a consumer adding a language can state it. Guessing would mean a
+ * consumer's own locale silently rendering mirrored — or, worse, silently not.
+ *
+ * Shared by `app.vue` and `error.vue` on purpose. The error page REPLACES the
+ * app shell rather than nesting inside it, so a direction computed inline in
+ * one of them is a direction the other does not have — which is precisely how
+ * `error.vue` came to set `lang` and never `dir`.
+ */
+export function localeDirection(
+  locales: readonly DuxtLocaleEntry[],
+  active: string
+): DuxtDirection {
+  const entry = locales.find(
+    (candidate) =>
+      (typeof candidate === 'string' ? candidate : candidate.code) === active
+  );
+
+  if (typeof entry !== 'object' || !entry) return 'ltr';
+
+  return entry.dir === 'rtl' ? 'rtl' : 'ltr';
+}

package/app/utils/duxt-config.ts

@@ -19,12 +19,55 @@ export const duxtDefaults: DuxtConfig = {
   // until a consumer sets its own. It names nobody, which is the whole test.
   title: 'duxt.defaults.title',
 
+  copy: {
+    models: [
+      {
+        label: 'duxt.page.copy.chatgpt',
+        icon: 'simple-icons:openai',
+        url: 'https://chatgpt.com/?q='
+      },
+      {
+        label: 'duxt.page.copy.claude',
+        icon: 'simple-icons:claude',
+        url: 'https://claude.ai/new?q='
+      }
+    ]
+  },
+  contributors: { avatarUrl: 'https://github.com/{username}.png?size=40' },
+  toc: { depth: 3, scrollOffset: 96 },
+  search: {
+    fuzzy: { threshold: 0.35, minMatchCharLength: 3, limit: 20 },
+    recentPages: 5
+  },
+  openapi: { exampleDepth: 6, schemaDepth: 8 },
+  // A policy, not a binding table. WHICH keys duxt listens to is the layer's
+  // and lives in `duxtShortcuts`; whether the unmodified ones are live at all
+  // is the site's, because only a site knows what else its pages put under a
+  // bare keystroke. One boolean rather than four rewritable rows: a consumer
+  // that could move `?` would have to move it in the handler, the sheet and
+  // the guards at once, and those three drifting apart is what this replaces.
+  shortcuts: { singleCharacter: true },
+
   // 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.
 
+  /**
+   * Empty, like `sections` and `links` below.
+   *
+   * An announcement is the SITE's own sentence — a release, a migration window,
+   * an outage — and a layer that shipped one would put its words at the top of
+   * every page extending it. Left empty the strip draws nothing at all: no
+   * banner, and no space held open for one.
+   *
+   * Written out rather than left absent so the key appears in the devtools
+   * Config panel, where a consumer meets it without reading the reference
+   * first — the same reason `sections` and `links` are spelled out below.
+   */
+  announcements: [],
+
   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.

package/app/utils/duxt-text.ts

@@ -38,6 +38,16 @@ const TEXT_KEYS = new Set([
   // JSON on the page, which is exactly how this one was found.
   'highlightsTitle',
   'label',
+  // A NAME, never an address. A source's display name and
+  // `duxt.organization.name` are both prose a site may translate; the strings
+  // beside them a reader might mistake for names — `collection`, `prefix`,
+  // `repo`, `slug` — are absent from this list and stay untouched, which is
+  // the whole reason it is an allowlist rather than a walk.
+  'name',
+  // An announcement's sentence. Neither `label` nor `description`, because it
+  // is the whole of what the banner says rather than a caption on something
+  // else — and it needs the line here for the same reason the entry above does.
+  'text',
   'title'
 ]);
 

package/app/utils/format-date.ts

@@ -0,0 +1,28 @@
+/**
+ * A date, in the reader's language — or nothing, where there is no readable one.
+ *
+ * One formatter for every date the theme prints, because a date formatted in
+ * two places is two chances to print two different days for one fact.
+ *
+ * `calendarDay` is the one decision a caller makes, and it is about what the
+ * value IS. A release date is a calendar day 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 — so it is pinned to UTC. A commit date IS a
+ * moment, and is left in the reader's own zone.
+ */
+export function formatDate(
+  value: string | undefined,
+  locale: string,
+  { calendarDay = false }: { calendarDay?: boolean } = {}
+): 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',
+    ...(calendarDay ? { timeZone: 'UTC' } : {})
+  }).format(date);
+}

package/app/utils/generated-sections.ts

@@ -65,6 +65,7 @@ export function withGeneratedSections(
     // answered for the consumer's list only.
     const taken = new Set(existing.map((entry) => entry.to).filter(Boolean));
     const entries: DuxtLink[] = [];
+    const listed: DuxtResolvedSource[][] = [];
 
     for (const declaration of declarations) {
       const meta = declaration[0]!.generated!;
@@ -74,7 +75,10 @@ export function withGeneratedSections(
       // the one this reader would be given: a section listed by hand is listed,
       // and the entry `to` resolves to is always one of these prefixes, so this
       // is the de-dupe by URL as well.
-      if (declaration.some((entry) => taken.has(entry.prefix))) continue;
+      if (declaration.some((entry) => taken.has(entry.prefix))) {
+        listed.push(declaration);
+        continue;
+      }
 
       const to = entryPath(declaration, base);
 
@@ -82,27 +86,79 @@ export function withGeneratedSections(
       entries.push({ label: meta.label, to, icon: meta.icon });
     }
 
-    return entries;
+    return { entries, moved: followReader(existing, listed, base) };
   };
 
   const navigation = entriesFor('navigation', config.navigation ?? []);
   const sections = entriesFor('sections', config.sections ?? []);
 
-  if (!navigation.length && !sections.length) return config;
+  if (
+    !navigation.entries.length &&
+    !sections.entries.length &&
+    !navigation.moved &&
+    !sections.moved
+  )
+    return config;
 
   return {
     ...config,
-    // Only the row that gains something is rewritten: an empty array where the
-    // config had `undefined` is a different value, and the header reads both.
-    ...(navigation.length
-      ? { navigation: [...(config.navigation ?? []), ...navigation] }
+    // Only the row that gains or moves something is rewritten: an empty array
+    // where the config had `undefined` is a different value, and the header
+    // reads both.
+    ...(navigation.entries.length || navigation.moved
+      ? {
+          navigation: [
+            ...(navigation.moved ?? config.navigation ?? []),
+            ...navigation.entries
+          ]
+        }
       : {}),
-    ...(sections.length
-      ? { sections: [...(config.sections ?? []), ...sections] }
+    ...(sections.entries.length || sections.moved
+      ? {
+          sections: [
+            ...(sections.moved ?? config.sections ?? []),
+            ...sections.entries
+          ]
+        }
       : {})
   };
 }
 
+/**
+ * A section listed by hand keeps its POSITION, and its URL follows the reader.
+ *
+ * Placing an entry by hand is how a consumer orders the row, and a `per-version`
+ * section written at the default version's URL would otherwise send a reader on
+ * `v2.x` to `v3.x` the moment they clicked it. So an entry whose `to` is one of
+ * the declaration's own prefixes is pointed at the edition the reader is on —
+ * the same answer the appended entry gets. An entry pointing anywhere else
+ * inside the section is a page the consumer chose, and stays where it points.
+ *
+ * `undefined` when nothing moved, so an untouched row keeps its identity.
+ */
+function followReader(
+  existing: DuxtLink[],
+  listed: DuxtResolvedSource[][],
+  base: string
+): DuxtLink[] | undefined {
+  let changed = false;
+
+  const moved = existing.map((entry) => {
+    const declaration = listed.find((candidate) =>
+      candidate.some((source) => source.prefix === entry.to)
+    );
+    if (!declaration) return entry;
+
+    const to = entryPath(declaration, base);
+    if (to === entry.to) return entry;
+
+    changed = true;
+    return { ...entry, to };
+  });
+
+  return changed ? moved : undefined;
+}
+
 /**
  * The manifest's generated entries, grouped into the declarations that made
  * them, in the order the site declared them.
@@ -171,11 +227,11 @@ const depth = (prefix: string) => (prefix ? prefix.split('/').length - 1 : 0);
  *
  * THE SHARED SLOT. Each type names its own layout and every type renders
  * through this one lookup, which is what stops two types inventing two
- * unrelated ways to escape the docs chrome. A type that names none renders in
- * the ordinary chrome, and the lookup answers `undefined`.
+ * unrelated ways to escape the docs layout. A type that names none renders in
+ * the ordinary docs layout, and the lookup answers `undefined`.
  *
  * Filtered to the sections that name a layout before the prefix match, so a
- * site whose types all render in the docs chrome does no work at all.
+ * site whose types all render in the docs layout does no work at all.
  */
 export function generatedLayout(
   path: string,

package/app/utils/generated-toc.ts

@@ -24,7 +24,7 @@ export interface DuxtGeneratedTocLink {
   children?: DuxtGeneratedTocLink[];
 }
 
-const HEADING = /^h([23])$/;
+const HEADING = /^h([2-6])$/;
 
 /**
  * A prop, whichever spelling it arrived in.
@@ -63,7 +63,11 @@ function text(node: unknown): string {
  * promoted to `##` by the parser — so inside a group it is one level further
  * in, or the column would claim both are siblings.
  */
-function walk(nodes: unknown[], inside: boolean): DuxtGeneratedTocLink[] {
+function walk(
+  nodes: unknown[],
+  inside: boolean,
+  maximumDepth: number
+): DuxtGeneratedTocLink[] {
   const links: DuxtGeneratedTocLink[] = [];
 
   for (const node of nodes) {
@@ -84,7 +88,7 @@ function walk(nodes: unknown[], inside: boolean): DuxtGeneratedTocLink[] {
       // The same words the heading itself draws — the anchor is still built
       // from the file's own name, so the two cannot point apart.
       if (id) links.push({ id, text: changelogLabel(name), depth: 2 });
-      links.push(...walk(children, true));
+      links.push(...walk(children, true, maximumDepth));
       continue;
     }
 
@@ -96,7 +100,7 @@ function walk(nodes: unknown[], inside: boolean): DuxtGeneratedTocLink[] {
     if (tag === 'changelog-releases') continue;
 
     const heading = HEADING.exec(tag);
-    if (heading) {
+    if (heading && Number(heading[1]) <= maximumDepth) {
       const id = props.id;
       if (typeof id === 'string' && id) {
         links.push({
@@ -108,20 +112,23 @@ function walk(nodes: unknown[], inside: boolean): DuxtGeneratedTocLink[] {
       continue;
     }
 
-    links.push(...walk(children, inside));
+    links.push(...walk(children, inside, maximumDepth));
   }
 
   return links;
 }
 
 /** The flat list nested the way `DuxtToc` draws it: one level of children. */
-export function generatedToc(body: unknown): DuxtGeneratedTocLink[] {
+export function generatedToc(
+  body: unknown,
+  maximumDepth = 3
+): DuxtGeneratedTocLink[] {
   const value = (body as { value?: unknown })?.value;
   if (!Array.isArray(value)) return [];
 
   const links: DuxtGeneratedTocLink[] = [];
 
-  for (const link of walk(value, false)) {
+  for (const link of walk(value, false, maximumDepth)) {
     const parent = links.at(-1);
 
     if (link.depth > 2 && parent) (parent.children ??= []).push(link);

package/app/utils/locale-path.ts

@@ -21,6 +21,22 @@ export function stripLocalePrefix(
   return documentPath.replace(/\/+$/, '') || (documentPath ? '/' : '');
 }
 
+/**
+ * The locale CODES out of an i18n locale list.
+ *
+ * `@nuxtjs/i18n` accepts a bare code or an object carrying one, and every place
+ * that strips a prefix — the composable, the layout middleware, the devtools
+ * path debugger — needs the plain list. Absent is an empty list: a site without
+ * the module has no prefixes to strip.
+ */
+export function localeCodesOf(
+  locales: readonly (string | { code: string })[] | undefined
+): string[] {
+  return (locales ?? []).map((entry) =>
+    typeof entry === 'string' ? entry : entry.code
+  );
+}
+
 /**
  * The same split, keeping the half that was thrown away.
  *
@@ -46,3 +62,30 @@ export function splitLocalePath(
 
   return { path };
 }
+
+/**
+ * The routes a MACHINE reads, which exist once for the whole site.
+ *
+ * `llms.txt`, `llms-full.txt`, `rss.xml` and the MCP server are server routes
+ * at the root. They are not pages, `@nuxtjs/i18n` knows nothing of them, and
+ * `localePath('/llms.txt')` therefore hands back `/de-DE/llms.txt` — a path
+ * that falls through to the catch-all page and 404s. That is what the landing
+ * page's framed `llms.txt` did in every locale: Nitro's error response carries
+ * `X-Frame-Options: DENY`, so the reader saw a broken frame rather than a 404.
+ *
+ * An explicit list, not "has a file extension": a version segment such as
+ * `v0.1.0` reads as one. And `…/page.md` is deliberately NOT on it — the
+ * raw-markdown middleware splits the locale off and serves the translation,
+ * so a localised `.md` link is the right link.
+ *
+ * Mirrors the root rows of `DEPLOYMENT_ROUTES` in `scripts/check-routes.ts`.
+ */
+const MACHINE_ROUTES = ['/llms.txt', '/llms-full.txt', '/rss.xml', '/mcp'];
+
+export function isMachineRoute(path: string): boolean {
+  const bare = path.split(/[?#]/)[0]!.replace(/\/+$/, '');
+
+  return MACHINE_ROUTES.some(
+    (route) => bare === route || (route === '/mcp' && bare.startsWith('/mcp/'))
+  );
+}

package/app/utils/navigation-tree.ts

@@ -1,5 +1,21 @@
 import type { ContentNavigationItem } from '@nuxt/content';
 
+/** Pages in reading order, with non-page groups expanded into their members. */
+export function flattenedNavigationPages(
+  items: ContentNavigationItem[]
+): ContentNavigationItem[] {
+  const pages: ContentNavigationItem[] = [];
+
+  for (const item of items) {
+    if (item.page !== false) pages.push(item);
+    if (item.children?.length) {
+      pages.push(...flattenedNavigationPages(item.children));
+    }
+  }
+
+  return pages;
+}
+
 /** Actual pages, including dotted version paths; folder wrappers are not pages. */
 export function navigationPagePaths(items: ContentNavigationItem[]): string[] {
   const paths = new Set<string>();
@@ -90,6 +106,14 @@ export function sectionItems(
  * Anything at or above the source's own prefix is one of those wrapper nodes,
  * not a page anyone navigates to — it showed up as an extra crumb on a
  * versioned URL that the unversioned one did not have.
+ *
+ * A `page: false` node on the chain is the same thing one level down: a group
+ * that exists to hold pages and has no route of its own — tfplugindocs'
+ * `subcategory` groups are the standing example, synthesised from frontmatter
+ * with no directory behind them. The walk still goes THROUGH such a node to
+ * reach the page; only the returned trail drops it, because `DuxtBreadcrumb`
+ * links every crumb but the last and `useDuxtBreadcrumb` emits the same trail
+ * as `BreadcrumbList` JSON-LD — so a group left in ships a 404 twice over.
  */
 export function trailBelowPrefix(
   tree: ContentNavigationItem[],
@@ -118,7 +142,33 @@ export function trailBelowPrefix(
 
   walk(tree, []);
 
-  return found.filter((item) => (item.path?.length ?? 0) > prefix.length);
+  return found.filter(
+    (item) => item.page !== false && (item.path?.length ?? 0) > prefix.length
+  );
+}
+
+/**
+ * The children a `::page-cards` block draws for a branch.
+ *
+ * The branch's own index carries the branch's path — Content emits it as a
+ * child — and is the page the cards sit on, so it is never a card.
+ *
+ * A `page: false` group is replaced by its members rather than dropped: the
+ * group has no route to link to, but the pages under it are exactly what the
+ * reader came for. `flattenedNavigationPages` is not the same thing and cannot
+ * stand in — it descends through real folders too, and a card for a folder is
+ * the point of a card grid.
+ */
+export function navigationCardItems(
+  branch: ContentNavigationItem | undefined,
+  base: string
+): ContentNavigationItem[] {
+  const expand = (items: ContentNavigationItem[]): ContentNavigationItem[] =>
+    items.flatMap((item) =>
+      item.page === false ? expand(item.children ?? []) : [item]
+    );
+
+  return expand(branch?.children ?? []).filter((child) => child.path !== base);
 }
 
 /**

package/app/utils/nearest-page.ts

@@ -19,8 +19,16 @@ export function nearestPages(
   const target = segments(wanted);
   if (!target.length) return [];
 
+  // ONE ROW PER PATH. A folder's index and the folder itself are both in the
+  // navigation under the same route, and the list offered the reader
+  // `Concepts /v0.2.0/concepts` twice.
+  const seen = new Set<string>();
+
   return candidates
     .filter((candidate) => candidate.path && candidate.path !== wanted)
+    .filter(
+      (candidate) => !seen.has(candidate.path) && seen.add(candidate.path)
+    )
     .map((candidate) => ({
       candidate,
       score: score(target, segments(candidate.path))

package/app/utils/openapi.ts

@@ -21,8 +21,6 @@ import type {
 } from '../../openapi-model';
 
 /** How deep an example is derived before it is called recursive enough. */
-const MAX_DEPTH = 6;
-
 /**
  * A schema's type, as the one word a table cell has room for.
  *
@@ -111,9 +109,10 @@ export function excluded(
 export function openApiExampleValue(
   schema: DuxtOpenApiSchema | undefined,
   direction: DuxtOpenApiDirection,
-  depth = 0
+  depth = 0,
+  maximumDepth = 6
 ): unknown {
-  if (!schema || schema.circular || depth > MAX_DEPTH) return null;
+  if (!schema || schema.circular || depth > maximumDepth) return null;
 
   if (schema.examples?.length) return schema.examples[0];
   if (schema.default !== undefined) return schema.default;
@@ -121,7 +120,8 @@ export function openApiExampleValue(
   if (schema.enum?.length) return schema.enum[0];
 
   const branch = schema.oneOf?.[0] ?? schema.anyOf?.[0];
-  if (branch) return openApiExampleValue(branch, direction, depth + 1);
+  if (branch)
+    return openApiExampleValue(branch, direction, depth + 1, maximumDepth);
 
   const declared = (schema.types ?? []).filter((type) => type !== 'null');
   const type =
@@ -149,24 +149,29 @@ export function openApiExampleValue(
         built[property.name] = openApiExampleValue(
           property.schema,
           direction,
-          depth + 1
+          depth + 1,
+          maximumDepth
         );
       }
 
       for (const merged of schema.allOf ?? []) {
         Object.assign(
           built,
-          openApiExampleValue(merged, direction, depth + 1) as Record<
-            string,
-            unknown
-          >
+          openApiExampleValue(
+            merged,
+            direction,
+            depth + 1,
+            maximumDepth
+          ) as Record<string, unknown>
         );
       }
 
       return built;
     }
     case 'array':
-      return [openApiExampleValue(schema.items, direction, depth + 1)];
+      return [
+        openApiExampleValue(schema.items, direction, depth + 1, maximumDepth)
+      ];
     case 'boolean':
       return true;
     case 'integer':