@takazudo/zudo-doc 5.15.0 → 5.16.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.16.0] - 2026-09-02
+
+### Features
+
+- Added opt-in Markdown/MDX transclusion through `transclude`, plus independent `assetViewerIndexing` controls for search, llms.txt, and sitemap output. (`8145aae41`)
+- Generated asset-viewer pages can now be enumerated in sitemaps and indexed in search and llms outputs, with locale, base-path, exclusion, and bounded content-extraction handling. (`5da03612e`, `b48009d7e`, `3de313585`, `76b90bc48`)
+
+### Bug Fixes
+
+- Long unbroken titles now wrap across documentation, home, asset, version, and tag pages. (`f21c6b73d`)
+- Asset search excerpts now use bounded reads for large files. (`6c81a13b3`)
+- Asset links in llms outputs now honor the configured `siteUrl`. (`67482a1d5`)
+
+### Other Changes
+
+- Raised the optional `@takazudo/zudo-doc-history-server` peer floor to the already-published 5.15.0 release. (`01bd83bc7`)
+
 ## [5.15.0] - 2026-09-01
 
 ### Features

package/dist/asset-index-page/index.js

@@ -145,7 +145,7 @@ function createAssetIndexPageView(ctx) {
           /* @__PURE__ */ jsx("span", { class: "rounded-full border border-muted px-hsp-sm py-vsp-3xs text-fg", children: title }),
           /* @__PURE__ */ jsx("span", { class: "rounded-full border border-muted px-hsp-sm py-vsp-3xs text-muted", children: t("asset.indexBadge", locale) })
         ] }),
-        /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight", children: title }),
+        /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight break-words", children: title }),
         /* @__PURE__ */ jsxs("div", { "data-doc-metainfo": true, class: "mb-vsp-md flex flex-wrap items-center gap-x-hsp-md gap-y-vsp-2xs text-caption text-fg", children: [
           /* @__PURE__ */ jsx("span", { children: countLabel(tree.fileCount, fileCountLabel, fileCountSingleLabel) }),
           /* @__PURE__ */ jsx("span", { children: countLabel(folders, folderCountLabel, folderCountSingleLabel) }),

package/dist/asset-page/index.js

@@ -42,7 +42,7 @@ function AssetHeader({ asset, locale, badge, updatedLabel, linesLabel }) {
   const facet = facetLabel(asset, linesLabel);
   return /* @__PURE__ */ jsxs("header", { children: [
     /* @__PURE__ */ jsx(AssetEyebrow, { asset, badge }),
-    /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight", children: asset.name }),
+    /* @__PURE__ */ jsx("h1", { class: "mb-vsp-xs border-b border-fg pb-vsp-xs font-mono text-heading font-bold leading-tight break-words", children: asset.name }),
     /* @__PURE__ */ jsxs("div", { "data-doc-metainfo": true, class: "mb-vsp-md flex flex-wrap items-center gap-x-hsp-md gap-y-vsp-2xs text-caption text-fg", children: [
       asset.dir && /* @__PURE__ */ jsx("span", { children: asset.dir }),
       facet && /* @__PURE__ */ jsx("span", { children: facet }),

package/dist/config.d.ts

@@ -18,11 +18,13 @@
  * `zudoDoc()` SHALLOW-merges the user's fields over {@link DEFAULT_SETTINGS} —
  * top-level fields only (`{ ...DEFAULT_SETTINGS, ...user }`). A supplied nested
  * object (e.g. `colorMode`, `metaTags`) REPLACES the default wholesale; it is
- * NOT deep-merged key-by-key. This is safe because every nested config type is
- * all-required-fields, so a caller supplying one supplies all of its fields.
- * ONE exception: `FaviconConfig` is all-optional — wholesale replacement IS its
- * semantics (only the supplied slots emit a `<link rel="icon">`), and its
- * default is `undefined`, so there is nothing for a partial object to clobber.
+ * NOT deep-merged key-by-key. Nested config types that intentionally expose
+ * optional keys (such as `FrontmatterPreviewConfig` and
+ * `AssetViewerIndexingConfig`) get their per-key defaults at the read site;
+ * this shallow merge never fills nested keys. `FaviconConfig` is also
+ * all-optional — wholesale replacement IS its semantics (only the supplied
+ * slots emit a `<link rel="icon">`), and its default is `undefined`, so there
+ * is nothing for a partial object to clobber.
  * `zudoDoc()` also supplies the Wave-3 package defaults
  * (`buildDocsSchema`/`directiveVocabulary`/`translations`/`colorSchemes`/tag
  * vocabulary) unless overridden, and returns a **complete `ZfbConfig`** — the
@@ -65,7 +67,7 @@ import type { ZfbConfig, BundleConfig } from "@takazudo/zfb/config";
 import type { ZodType } from "zod";
 import type { DirectiveVocabulary, PresetTranslations, PresetTagVocabularyEntry } from "./preset.js";
 import type { ColorScheme } from "./color-scheme-utils.js";
-import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, HomeConfig, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig, FaviconConfig } from "./settings.js";
+import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, HomeConfig, AssetViewerIndexingConfig, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig, FaviconConfig } from "./settings.js";
 /** The `settings.claudeResources` block (or `false` when disabled). */
 type ClaudeResourcesConfig = {
     claudeDir: string;
@@ -188,6 +190,11 @@ export interface ZudoDocConfig {
      * @default true
      */
     mermaid?: boolean;
+    /**
+     * Enable transclusion of other Markdown/MDX files via `:::include`.
+     * @default false
+     */
+    transclude?: boolean;
     /**
      * Add `noindex,nofollow` to every page (for internal docs).
      * @default false
@@ -377,6 +384,8 @@ export interface ZudoDocConfig {
     assetViewerExclude?: string[];
     /** When `true` (and `assetViewer` is `true`), generate a listing page at `/<assetViewerRoutePrefix>/` showing every managed asset as a folder tree. No effect when `assetViewer` is `false`. @default false */
     assetViewerIndex?: boolean;
+    /** Per-output opt-in controls for indexing generated asset-viewer pages. Omitted keys are off; `false` disables all asset-page indexing. @default false */
+    assetViewerIndexing?: AssetViewerIndexingConfig | false;
     /**
      * Body-foot utility area (doc-history / view-source), or `false` to disable.
      * @default false

package/dist/config.js

@@ -53,6 +53,7 @@ const DEFAULT_SETTINGS = {
   defaultLocale: "en",
   locales: {},
   mermaid: true,
+  transclude: false,
   noindex: false,
   editUrl: false,
   githubUrl: false,
@@ -98,6 +99,7 @@ const DEFAULT_SETTINGS = {
   assetViewerRoutePrefix: "files",
   assetViewerExclude: [],
   assetViewerIndex: false,
+  assetViewerIndexing: false,
   bodyFootUtilArea: false,
   htmlPreview: void 0,
   versions: false,

package/dist/doc-content-header/index.js

@@ -20,7 +20,7 @@ function createDocContentHeader(ctx) {
     version
   }) {
     return /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold border-b border-fg pb-vsp-xs mb-vsp-xs", children: entry.data.title }),
+      /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold border-b border-fg pb-vsp-xs mb-vsp-xs break-words", children: entry.data.title }),
       docContentHeaderExtras?.({
         entry,
         slug,

package/dist/doc-page-shell/index.js

@@ -176,7 +176,7 @@ function createDocPageShell(ctx) {
              Fragment (not <div>) so children become direct children of
              <article class="zd-content">, picking up the flow-space rule. */
           /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold border-b border-fg pb-vsp-xs mb-vsp-xs", children: autoIndexLabel }),
+            /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold border-b border-fg pb-vsp-xs mb-vsp-xs break-words", children: autoIndexLabel }),
             metainfoSlot,
             description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", "data-doc-description": true, children: description }),
             /* @__PURE__ */ jsx(NavCardGrid, { children: autoIndexChildren ?? [] })

package/dist/home-page/index.js

@@ -117,7 +117,7 @@ function createHomePageView(ctx) {
               }
             ) : null,
             /* @__PURE__ */ jsxs("div", { children: [
-              /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-2xs", children: settings.siteName }),
+              /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-2xs break-words", children: settings.siteName }),
               /* @__PURE__ */ jsx("p", { class: "text-muted text-small mb-vsp-sm", children: settings.siteDescription }),
               /* @__PURE__ */ jsx("div", { class: "flex items-center justify-center lg:justify-start gap-hsp-md text-small", children: rowItems.map((item, index) => /* @__PURE__ */ jsxs(Fragment2, { children: [
                 index > 0 && /* @__PURE__ */ jsx("span", { class: "text-muted", children: "/" }),

package/dist/nav-indexing/versions-page-content.js

@@ -3,7 +3,7 @@ import { ChevronRight } from "../icons/index.js";
 function VersionsPageContent(props) {
   const { latestHref, versions, labels } = props;
   return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-lg", children: labels.pageTitle }),
+    /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-lg break-words", children: labels.pageTitle }),
     /* @__PURE__ */ jsxs("section", { class: "mb-vsp-xl", children: [
       /* @__PURE__ */ jsx("h2", { class: "text-title font-bold mb-vsp-xs", children: labels.latestTitle }),
       /* @__PURE__ */ jsx("p", { class: "text-small text-muted mb-vsp-sm", children: labels.latestDescription }),

package/dist/plugins/internal/asset-viewer/asset-pages.d.ts

@@ -0,0 +1,53 @@
+import type { AssetViewerIndexingConfig } from "../../../settings.js";
+/** The serialized asset-viewer settings shared by index consumers. */
+export interface AssetScanProjection {
+    assetViewer: boolean;
+    assetViewerIndexing: AssetViewerIndexingConfig | false;
+    assetViewerDir: string;
+    assetViewerRoutePrefix: string;
+    assetViewerExclude: readonly string[];
+    base: string;
+    /** Non-default locales, keyed by locale code. */
+    locales: Record<string, {
+        dir?: string;
+    }>;
+    /** Route prefixes whose generated pages exist only in the default locale. */
+    defaultLocaleOnlyPrefixes: readonly string[];
+}
+/** The asset-page output currently supported by a consumer. */
+export type AssetIndexConsumer = keyof AssetViewerIndexingConfig;
+/** Minimal normalized descriptor consumed by search, llms.txt, and sitemap. */
+export interface AssetPageDescriptor {
+    /** NFC-normalized POSIX path relative to `assetViewerDir`. */
+    path: string;
+    /** Base-prefixed, trailing-slashed generated asset-viewer URL. */
+    url: string;
+    /** Non-default locale segment; omitted for the default locale. */
+    locale?: string;
+    /** Whether the asset has a text-like extension understood by the viewer. */
+    isText: boolean;
+    /** Current byte size of the public asset. */
+    size: number;
+}
+export interface AssetPageDescriptorOptions {
+    /** Runtime project root injected by the zfb plugin wrapper. */
+    projectRoot: string;
+    /** Serialized projection from `zudoDocPreset()`. */
+    assetScan?: AssetScanProjection;
+    /** The output whose explicit indexing gate must be enabled. */
+    consumer: AssetIndexConsumer;
+}
+/**
+ * Scan the public asset directory and materialize one descriptor per emitted
+ * asset page. The default-locale descriptor is emitted first, followed by
+ * configured locales in object iteration order. Every descriptor URL is
+ * minted by `assetViewerHref()` so encoding, base, and trailing-slash rules
+ * cannot diverge between consumers.
+ *
+ * The descriptor path is intentionally synchronous. Search and llms.txt are
+ * synchronous build/dev paths, and `connect-adapter.ts` does not await a
+ * middleware's returned promise. Callers must pass the runtime `projectRoot`
+ * supplied by the plugin wrapper; it is never part of the serialized preset
+ * projection.
+ */
+export declare function collectAssetPageDescriptors(options: AssetPageDescriptorOptions): AssetPageDescriptor[];

package/dist/plugins/internal/asset-viewer/asset-pages.js

@@ -0,0 +1,98 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { extname, resolve } from "node:path";
+import { assetViewerHref } from "../../../asset-path/index.js";
+import { scanAssetsSync } from "./scan.js";
+const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  "js",
+  "ts",
+  "tsx",
+  "jsx",
+  "mjs",
+  "cjs",
+  "json",
+  "yaml",
+  "yml",
+  "toml",
+  "css",
+  "scss",
+  "html",
+  "md",
+  "mdx",
+  "sh",
+  "bash",
+  "py",
+  "rb",
+  "go",
+  "rs",
+  "java",
+  "kt",
+  "swift",
+  "c",
+  "h",
+  "cpp",
+  "hpp",
+  "cs",
+  "php",
+  "sql",
+  "xml",
+  "txt",
+  "log",
+  "csv",
+  "tsv",
+  "env",
+  "conf",
+  "ini"
+]);
+function hasBinaryPrefix(absPath) {
+  const fd = openSync(absPath, "r");
+  try {
+    const sample = Buffer.allocUnsafe(8 * 1024);
+    const bytesRead = readSync(fd, sample, 0, sample.length, 0);
+    return sample.subarray(0, bytesRead).includes(0);
+  } finally {
+    closeSync(fd);
+  }
+}
+function isTextAsset(absPath, path) {
+  const extension = extname(path).slice(1).toLowerCase();
+  if (extension.length !== 0 && !TEXT_EXTENSIONS.has(extension)) return false;
+  return !hasBinaryPrefix(absPath);
+}
+function isDefaultLocaleOnlyAsset(routePrefix, path, prefixes) {
+  const routePath = assetViewerHref({ base: "/", routePrefix, path });
+  return prefixes.some((prefix) => routePath.startsWith(prefix));
+}
+function hasConsumerGate(assetScan, consumer) {
+  const indexing = assetScan.assetViewerIndexing;
+  return assetScan.assetViewer === true && indexing !== false && typeof indexing === "object" && indexing !== null && indexing[consumer] === true;
+}
+function collectAssetPageDescriptors(options) {
+  const { projectRoot, assetScan, consumer } = options;
+  if (assetScan === void 0 || !hasConsumerGate(assetScan, consumer)) return [];
+  const dir = assetScan.assetViewerDir;
+  const routePrefix = assetScan.assetViewerRoutePrefix;
+  const base = assetScan.base;
+  const exclude = assetScan.assetViewerExclude ?? [];
+  const paths = scanAssetsSync(projectRoot, dir, exclude);
+  const assetRoot = resolve(projectRoot, "public", dir);
+  const descriptorFor = (path, locale) => ({
+    path,
+    url: assetViewerHref({ base, routePrefix, path, ...locale === void 0 ? {} : { locale } }),
+    ...locale === void 0 ? {} : { locale },
+    isText: isTextAsset(resolve(assetRoot, path), path),
+    size: statSync(resolve(assetRoot, path)).size
+  });
+  const descriptors = paths.map((path) => descriptorFor(path));
+  for (const locale of Object.keys(assetScan.locales ?? {})) {
+    for (const path of paths) {
+      if (isDefaultLocaleOnlyAsset(routePrefix, path, assetScan.defaultLocaleOnlyPrefixes ?? [])) {
+        continue;
+      }
+      descriptors.push(descriptorFor(path, locale));
+    }
+  }
+  return descriptors;
+}
+export {
+  collectAssetPageDescriptors
+};

package/dist/plugins/internal/asset-viewer/scan.d.ts

@@ -1,2 +1,19 @@
-/** Recursively enumerate safe, public assets in deterministic path order. */
+/**
+ * Recursively enumerate safe, public assets in deterministic path order.
+ *
+ * This synchronous implementation is the canonical walk. Search and llms.txt
+ * build/dev consumers are synchronous, while the routes setup hook already
+ * exposes an async `scanAssets()` contract. Keeping one walk here gives both
+ * boundaries identical symlink, exclusion, and collision behavior.
+ */
+export declare function scanAssetsSync(projectRoot: string, dir: string, exclude?: readonly string[]): string[];
+/**
+ * Async-compatible asset scan used by the routes setup hook.
+ *
+ * The route plugin's public lifecycle contract is async, but its scan itself
+ * is only filesystem enumeration. Delegating to the canonical sync walk keeps
+ * it behaviorally identical to `scanAssetsSync()` without introducing a
+ * second implementation (or a promise that synchronous middleware cannot
+ * consume).
+ */
 export declare function scanAssets(projectRoot: string, dir: string, exclude?: readonly string[]): Promise<string[]>;

package/dist/plugins/internal/asset-viewer/scan.js

@@ -1,11 +1,27 @@
-import { readdir, realpath, stat } from "node:fs/promises";
+import { readdirSync, realpathSync, statSync } from "node:fs";
 import { basename, relative, resolve, sep } from "node:path";
 import { matchExclude, normalizeAssetPath } from "../../../asset-path/index.js";
 function isWithin(root, candidate) {
   const rel = relative(root, candidate);
   return rel === "" || !rel.startsWith(`..${sep}`) && rel !== "..";
 }
-async function scanAssets(projectRoot, dir, exclude = []) {
+function finishScan(paths) {
+  paths.sort((a, b) => a.localeCompare(b, "en"));
+  const folded = /* @__PURE__ */ new Map();
+  for (const path of paths) {
+    const key = path.toLocaleLowerCase("en-US");
+    const existing = folded.get(key);
+    if (existing !== void 0) {
+      throw new Error(`[asset-viewer] case-insensitive or Unicode-normalized URL collision: ${existing} and ${path}`);
+    }
+    folded.set(key, path);
+    if (path === "client" || path.startsWith("client/")) {
+      console.warn(`[asset-viewer] reserved client/ asset path: ${path}`);
+    }
+  }
+  return paths;
+}
+function scanAssetsSync(projectRoot, dir, exclude = []) {
   const publicRoot = resolve(projectRoot, "public");
   const assetRoot = resolve(publicRoot, dir);
   if (!isWithin(publicRoot, assetRoot)) {
@@ -13,8 +29,8 @@ async function scanAssets(projectRoot, dir, exclude = []) {
   }
   let canonicalRoot;
   try {
-    const canonicalPublicRoot = await realpath(publicRoot);
-    canonicalRoot = await realpath(assetRoot);
+    const canonicalPublicRoot = realpathSync(publicRoot);
+    canonicalRoot = realpathSync(assetRoot);
     if (!isWithin(canonicalPublicRoot, canonicalRoot)) {
       throw new Error(`[asset-viewer] asset directory symlink escapes public/: ${dir}`);
     }
@@ -23,29 +39,29 @@ async function scanAssets(projectRoot, dir, exclude = []) {
     throw error;
   }
   const paths = [];
-  async function walk(absDir, relDir, canonicalAncestors) {
-    const canonicalDir = await realpath(absDir);
+  function walk(absDir, relDir, canonicalAncestors) {
+    const canonicalDir = realpathSync(absDir);
     if (!isWithin(canonicalRoot, canonicalDir)) {
       throw new Error(`[asset-viewer] symlink escapes public/${dir}: ${relDir || basename(absDir)}`);
     }
     if (canonicalAncestors.has(canonicalDir)) return;
     const nextAncestors = new Set(canonicalAncestors).add(canonicalDir);
-    const entries = await readdir(absDir, { withFileTypes: true });
+    const entries = readdirSync(absDir, { withFileTypes: true });
     entries.sort((a, b) => a.name.localeCompare(b.name, "en"));
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
       const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
       if (entry.name.endsWith(".meta.json")) continue;
       const absPath = resolve(absDir, entry.name);
-      const canonical = await realpath(absPath);
+      const canonical = realpathSync(absPath);
       if (!isWithin(canonicalRoot, canonical)) {
         throw new Error(`[asset-viewer] symlink escapes public/${dir}: ${relPath}`);
       }
       if (entry.isDirectory()) {
-        await walk(absPath, relPath, nextAncestors);
+        walk(absPath, relPath, nextAncestors);
       } else if (entry.isSymbolicLink()) {
-        const target = await stat(canonical);
-        if (target.isDirectory()) await walk(absPath, relPath, nextAncestors);
+        const target = statSync(canonical);
+        if (target.isDirectory()) walk(absPath, relPath, nextAncestors);
         else {
           const path = normalizeAssetPath(relPath);
           if (!matchExclude(path, exclude)) paths.push(path);
@@ -56,22 +72,13 @@ async function scanAssets(projectRoot, dir, exclude = []) {
       }
     }
   }
-  await walk(assetRoot, "", /* @__PURE__ */ new Set());
-  paths.sort((a, b) => a.localeCompare(b, "en"));
-  const folded = /* @__PURE__ */ new Map();
-  for (const path of paths) {
-    const key = path.toLocaleLowerCase("en-US");
-    const existing = folded.get(key);
-    if (existing !== void 0) {
-      throw new Error(`[asset-viewer] case-insensitive or Unicode-normalized URL collision: ${existing} and ${path}`);
-    }
-    folded.set(key, path);
-    if (path === "client" || path.startsWith("client/")) {
-      console.warn(`[asset-viewer] reserved client/ asset path: ${path}`);
-    }
-  }
-  return paths;
+  walk(assetRoot, "", /* @__PURE__ */ new Set());
+  return finishScan(paths);
+}
+async function scanAssets(projectRoot, dir, exclude = []) {
+  return scanAssetsSync(projectRoot, dir, exclude);
 }
 export {
-  scanAssets
+  scanAssets,
+  scanAssetsSync
 };

package/dist/plugins/internal/llms-txt/assets.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Materialize the shared asset-viewer descriptors for llms.txt output.
+ *
+ * The descriptor scanner owns the asset-viewer/indexing gates and URL rules;
+ * this adapter only reads the bounded text body needed by llms-full.txt.
+ * Keeping it separate from the emitter lets build and dev use precisely the
+ * same data preparation path.
+ */
+import { type AssetScanProjection } from "../asset-viewer/asset-pages.js";
+import { type LlmsAssetEntry } from "./types.js";
+export interface LlmsAssetLoadOptions {
+    /** Runtime project root supplied by the zfb plugin wrapper. */
+    projectRoot?: string;
+    /** Shared serialized asset-viewer projection from the preset. */
+    assetScan?: AssetScanProjection;
+    /** Optional canonical site origin, matching document-entry URL behavior. */
+    siteUrl?: string;
+}
+/**
+ * Collect and materialize all llms-indexed assets. Missing runtime inputs are
+ * treated as the legacy no-assets case so direct unit callers and consumers
+ * that do not run through zfb remain byte-compatible.
+ */
+export declare function loadLlmsAssetEntries(options: LlmsAssetLoadOptions): LlmsAssetEntry[];

package/dist/plugins/internal/llms-txt/assets.js

@@ -0,0 +1,65 @@
+import { closeSync, openSync, readSync } from "node:fs";
+import { resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import {
+  collectAssetPageDescriptors
+} from "../asset-viewer/asset-pages.js";
+import {
+  LLMS_ASSET_TEXT_CAP_BYTES
+} from "./types.js";
+function readTextPrefix(filePath) {
+  const sample = Buffer.alloc(LLMS_ASSET_TEXT_CAP_BYTES + 1);
+  const fd = openSync(filePath, "r");
+  try {
+    let offset = 0;
+    while (offset < sample.length) {
+      const bytesRead = readSync(fd, sample, offset, sample.length - offset, offset);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    const decoder = new StringDecoder("utf8");
+    return {
+      content: decoder.write(sample.subarray(0, offset)),
+      truncated: offset > LLMS_ASSET_TEXT_CAP_BYTES
+    };
+  } finally {
+    closeSync(fd);
+  }
+}
+function toLlmsAssetEntry(descriptor, projectRoot, assetScan, siteUrl) {
+  const url = siteUrl ? `${siteUrl.replace(/\/$/, "")}${descriptor.url}` : descriptor.url;
+  if (!descriptor.isText) {
+    return {
+      path: descriptor.path,
+      url,
+      ...descriptor.locale === void 0 ? {} : { locale: descriptor.locale },
+      isText: false
+    };
+  }
+  const body = readTextPrefix(
+    resolve(projectRoot, "public", assetScan.assetViewerDir, descriptor.path)
+  );
+  return {
+    path: descriptor.path,
+    url,
+    ...descriptor.locale === void 0 ? {} : { locale: descriptor.locale },
+    isText: true,
+    content: body.content,
+    truncated: body.truncated
+  };
+}
+function loadLlmsAssetEntries(options) {
+  const { projectRoot, assetScan, siteUrl } = options;
+  if (projectRoot === void 0 || assetScan === void 0) return [];
+  const descriptors = collectAssetPageDescriptors({
+    projectRoot,
+    assetScan,
+    consumer: "llmsTxt"
+  });
+  return descriptors.map(
+    (descriptor) => toLlmsAssetEntry(descriptor, projectRoot, assetScan, siteUrl)
+  );
+}
+export {
+  loadLlmsAssetEntries
+};

package/dist/plugins/internal/llms-txt/dev-middleware.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { LlmsTxtLocaleConfig, LlmsTxtSiteMeta } from "./types.js";
+import type { AssetScanProjection } from "../asset-viewer/asset-pages.js";
 /** Connect-style middleware signature — works as a Vite plugin middleware. */
 export type LlmsTxtNextFn = (err?: unknown) => void;
 export type LlmsTxtMiddleware = (req: IncomingMessage, res: ServerResponse, next: LlmsTxtNextFn) => void;
@@ -22,6 +23,10 @@ export interface LlmsTxtDevMiddlewareOptions extends LlmsTxtSiteMeta {
     defaultLocaleDir: string;
     /** Additional locales (e.g. `[{ code: "ja", dir: "src/content/docs-ja" }]`). */
     locales?: LlmsTxtLocaleConfig[];
+    /** Runtime project root; injected by the zfb plugin wrapper, never serialized in the preset. */
+    projectRoot?: string;
+    /** Shared asset-viewer projection; consumed by the asset indexing wave. */
+    assetScan?: AssetScanProjection;
 }
 /**
  * Build a dev-server middleware that responds to GET requests for

package/dist/plugins/internal/llms-txt/dev-middleware.js

@@ -1,3 +1,4 @@
+import { loadLlmsAssetEntries } from "./assets.js";
 import { generateLlmsFullTxt, generateLlmsTxt } from "./generate.js";
 import { loadDocEntries } from "./load.js";
 const LLMS_KIND_PATTERN = /^(?:\/(.+?))?\/(llms|llms-full)\.txt$/;
@@ -39,7 +40,14 @@ function createLlmsTxtDevMiddleware(options, logger) {
         base,
         siteUrl
       });
-      const body = match.kind === "llms" ? generateLlmsTxt(entries, meta) : generateLlmsFullTxt(entries, meta);
+      const assets = loadLlmsAssetEntries({
+        projectRoot: options.projectRoot,
+        assetScan: options.assetScan,
+        siteUrl
+      }).filter(
+        (asset) => match.locale === null ? asset.locale === void 0 : asset.locale === match.locale
+      );
+      const body = match.kind === "llms" ? generateLlmsTxt(entries, meta, assets) : generateLlmsFullTxt(entries, meta, assets);
       res.statusCode = 200;
       res.setHeader("Content-Type", "text/plain; charset=utf-8");
       res.end(body);

package/dist/plugins/internal/llms-txt/emit.js

@@ -1,7 +1,13 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { generateLlmsFullTxt, generateLlmsTxt } from "./generate.js";
+import { loadLlmsAssetEntries } from "./assets.js";
 import { loadDocEntries } from "./load.js";
+function assetsForLocale(assets, locale) {
+  return assets.filter(
+    (asset) => locale === null ? asset.locale === void 0 : asset.locale === locale
+  );
+}
 function emitLlmsTxt(options) {
   const {
     outDir,
@@ -11,10 +17,13 @@ function emitLlmsTxt(options) {
     siteDescription,
     defaultLocaleDir,
     locales = [],
-    logger
+    logger,
+    projectRoot,
+    assetScan
   } = options;
   const meta = { siteName, siteDescription };
   const written = [];
+  const assetEntries = loadLlmsAssetEntries({ projectRoot, assetScan, siteUrl });
   const defaultEntries = loadDocEntries({
     contentDir: defaultLocaleDir,
     locale: null,
@@ -24,8 +33,14 @@ function emitLlmsTxt(options) {
   mkdirSync(outDir, { recursive: true });
   const defaultIndexPath = join(outDir, "llms.txt");
   const defaultFullPath = join(outDir, "llms-full.txt");
-  writeFileSync(defaultIndexPath, generateLlmsTxt(defaultEntries, meta));
-  writeFileSync(defaultFullPath, generateLlmsFullTxt(defaultEntries, meta));
+  writeFileSync(
+    defaultIndexPath,
+    generateLlmsTxt(defaultEntries, meta, assetsForLocale(assetEntries, null))
+  );
+  writeFileSync(
+    defaultFullPath,
+    generateLlmsFullTxt(defaultEntries, meta, assetsForLocale(assetEntries, null))
+  );
   written.push(defaultIndexPath, defaultFullPath);
   logger?.info(
     `Generated llms.txt and llms-full.txt (${defaultEntries.length} pages)`
@@ -41,8 +56,9 @@ function emitLlmsTxt(options) {
     mkdirSync(localeDir, { recursive: true });
     const indexPath = join(localeDir, "llms.txt");
     const fullPath = join(localeDir, "llms-full.txt");
-    writeFileSync(indexPath, generateLlmsTxt(localeEntries, meta));
-    writeFileSync(fullPath, generateLlmsFullTxt(localeEntries, meta));
+    const localeAssets = assetsForLocale(assetEntries, code);
+    writeFileSync(indexPath, generateLlmsTxt(localeEntries, meta, localeAssets));
+    writeFileSync(fullPath, generateLlmsFullTxt(localeEntries, meta, localeAssets));
     written.push(indexPath, fullPath);
     logger?.info(
       `Generated ${code}/llms.txt and ${code}/llms-full.txt (${localeEntries.length} pages)`

package/dist/plugins/internal/llms-txt/generate.d.ts

@@ -9,14 +9,14 @@
  * Output format must remain byte-identical to the legacy Astro emitter
  * — the file shape is part of the project's public surface.
  */
-import type { LlmsDocEntry, LlmsTxtSiteMeta } from "./types.js";
+import { type LlmsAssetEntry, type LlmsDocEntry, type LlmsTxtSiteMeta } from "./types.js";
 /**
  * Slim index — site header followed by a markdown bullet per page with
  * `[title](url): description`.
  */
-export declare function generateLlmsTxt(entries: readonly LlmsDocEntry[], meta: LlmsTxtSiteMeta): string;
+export declare function generateLlmsTxt(entries: readonly LlmsDocEntry[], meta: LlmsTxtSiteMeta, assets?: readonly LlmsAssetEntry[]): string;
 /**
  * Full content concatenation — site header followed by every page's
  * stripped body separated by `---` rules.
  */
-export declare function generateLlmsFullTxt(entries: readonly LlmsDocEntry[], meta: LlmsTxtSiteMeta): string;
+export declare function generateLlmsFullTxt(entries: readonly LlmsDocEntry[], meta: LlmsTxtSiteMeta, assets?: readonly LlmsAssetEntry[]): string;