@takazudo/zudo-doc 5.13.1 → 5.14.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.14.0] - 2026-08-31
+
+### Features
+
+- Added the configurable Asset Viewer for files under `public/assets/`, with type-specific viewer pages, raw/download links, linked-from context, and `assetViewerDir`, `assetViewerRoutePrefix`, and `assetViewerExclude` settings. (`45dc50cdb`, `19b8f0599`, `e6e77f790`)
+- Added asset authoring entry points for markdown links, the `Asset` and `AssetCode` components, and image caption links, with URL-safe viewer paths and code excerpts. (`2b74f1da2`, `6f22ebb97`, `b883bff41`)
+- Added the opt-in Asset Index at `/files/`, with nested native disclosures, file-kind icons, viewer links, file metadata, expansion persistence, and the `assetViewerIndex` setting. (`debdd3cf8`, `bbf10483b`, `177028439`)
+- Added the package-owned `run-parallel` command for concurrent development tasks, with signal forwarding, descendant cleanup, and real failure-code propagation, replacing `npm-run-all2`. (`9402ff157`, `3ebfa6e9c`, `dab5d7e07`)
+- Added public `@takazudo/zudo-doc/frontmatter` parse and stringify helpers backed by YAML 1.2 parsing and YAML 1.1-safe serialization, removing the `gray-matter` and `js-yaml` 3 dependency chain. (`c07422672`, `49cfb1895`, `bd8ad5be9`)
+
+### Bug Fixes
+
+- Preserved the active navigation state when its header item moves into the overflow menu, while keeping exactly one visible `aria-current="page"`. (`81582a042`)
+- Restored deliberate right gutters in tree navigation rows. (`fa6a2074d`)
+- Retained package-default Asset Index translations when projects provide partial locale overrides. (`0b1958562`)
+- Kept Asset Index disclosure semantics native and aligned leaf-file icons with the first control column. (`295b3d8d0`, `35356dad4`)
+
+### Other Changes
+
+- Updated the zfb peer family to 2.14.0, `@takazudo/zdtp` to 0.4.14, and the doc-history-server peer floor to 5.13.1. (`dbe8553c7`, `038870c94`, `95a82f15f`)
+
 ## [5.13.1] - 2026-08-28
 
 ### Other Changes

package/bin/run-parallel.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// packages/zudo-doc/bin/run-parallel.mjs
+//
+// Runs several package.json scripts in parallel. Replaces the `run-p <task>...`
+// form this project used from npm-run-all2, which was removed because it was the
+// sole source of four security advisories (shell-quote quadratic-complexity DoS;
+// brace-expansion@2 DoS x3) that nothing else in the tree pulled.
+//
+// Only the literal-name form is supported -- `run-parallel a b c`. npm-run-all2's
+// globs (`dev:*`), flags, and `{@}` placeholders are deliberately NOT implemented;
+// every call site here and in generated projects uses the plain form.
+//
+// Behaviour was checked against npm-run-all2@7.0.2 rather than assumed. It matches
+// on the points that matter, and deviates on two, on purpose:
+//
+//   MATCHED
+//   - A task exiting NON-ZERO aborts every sibling. A task exiting ZERO does not
+//     (that is run-p's `--race`, off by default).
+//   - A task killed by a signal reports 128 + signum, per the POSIX convention
+//     Node documents for exit codes -- non-zero, so it aborts too.
+//   - Only the FIRST failure is reported; siblings killed by the resulting
+//     teardown stay quiet.
+//   - The failure line matches run-p's wording, because packages/zudo-doc/CLAUDE.md
+//     (#3129) quotes it verbatim as the signature of the accepted cascade:
+//         ERROR: "dev:dts" exited with 1.
+//
+//   DELIBERATELY DIFFERENT
+//   - Exit code: run-p ALWAYS exits 1 on failure. Its bin/common/bootstrap.js ends
+//     with `.then(() => process.exit(0), () => process.exit(1))`, discarding the
+//     code its own error object carries -- verified by running run-p 7.0.2 against
+//     a task exiting 2: it printed `exited with 2` and returned 1. This script
+//     propagates the real code instead, so a signal kill stays distinguishable
+//     (137 for SIGKILL) rather than flattening to 1. Both are non-zero, so the
+//     #3129 cascade behaves identically either way.
+//   - Trailing args: run-p silently swallowed them, which is why a separate
+//     `dev:network` script exists (#2940). Silently ignoring a flag the user
+//     clearly meant is exactly the "quiet lie" #3129 argues against, so this
+//     script fails loudly and names the remedy instead.
+//
+// The teardown cascade is the POINT, not a bug: root `pnpm dev` nests one of these
+// inside another, so a fatal `dev:dts` exit takes down the whole dev session loudly
+// rather than leaving a dead watcher emitting stale output. Do NOT add a
+// --continue-on-error equivalent; #3129 rejects it explicitly (frozen .d.ts files
+// typecheck cleanly against stale types).
+//
+// Two implementation choices that look incidental and are not:
+//
+//   1. Children are spawned WITHOUT `detached`, exactly as run-p did, so they stay
+//      in this process's group. That keeps terminal job control working and lets a
+//      child read the inherited TTY stdin: `zfb dev` is Vite-based and binds stdin
+//      for its keyboard shortcuts. A child in its own group is not the terminal's
+//      foreground group, so that same read raises SIGTTIN and stops it.
+//   2. Teardown walks the full descendant tree rather than signalling just the
+//      direct child. `pnpm run x` sits between us and the real watcher and does not
+//      reliably forward SIGTERM, so signalling only the child strands it. Orphaned
+//      watchers are not hypothetical here -- they accumulate until `inotify_init`
+//      fails with EMFILE (see the #3129 section).
+
+import { spawn, execFileSync } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Platform-reported numbers rather than a hand-copied table, so the 128+signum
+// arithmetic cannot drift from the host's actual signal set.
+const SIGNAL_NUMBERS = os.constants.signals;
+
+function usage(message) {
+  process.stderr.write(`ERROR: ${message}\n`);
+  process.stderr.write(
+    "Usage: run-parallel <script-name>...\n" +
+      "Only literal script names are supported: no globs, no flags, and no\n" +
+      "forwarded arguments. To pass flags to one script, run it directly:\n" +
+      "  <npm|pnpm|yarn|bun> run <script> -- <flags>\n",
+  );
+  process.exit(1);
+}
+
+const tasks = process.argv.slice(2);
+
+if (tasks.length === 0) {
+  usage("no scripts given.");
+}
+for (const task of tasks) {
+  // Reject anything resembling an npm-run-all2 feature that was not ported, so a
+  // stale `run-p --continue-on-error`, or a `pnpm dev -- --host 0.0.0.0` that used
+  // to be swallowed, fails loudly instead of being taken for a script name.
+  if (task.startsWith("-")) {
+    usage(`flags are not supported, got ${JSON.stringify(task)}.`);
+  }
+  if (task.includes("*")) {
+    usage(`glob patterns are not supported, got ${JSON.stringify(task)}.`);
+  }
+}
+
+/**
+ * Resolve the package-manager command used to run a script, mirroring how
+ * npm-run-all2 did it: prefer `npm_execpath` (set by every package manager while
+ * running a script), and run it through the current Node binary when it points at
+ * a JS file, since a `.cjs` shim is not directly executable everywhere.
+ */
+function resolveRunner() {
+  const execpath = process.env.npm_execpath;
+  if (execpath) {
+    if (/\.(c|m)?js$/.test(path.extname(execpath))) {
+      return { command: process.execPath, prefix: [execpath, "run"] };
+    }
+    return { command: execpath, prefix: ["run"] };
+  }
+  // Fallback covers all four package managers create-zudo-doc can scaffold.
+  const agent = process.env.npm_config_user_agent ?? "";
+  const name =
+    ["pnpm", "yarn", "bun"].find((pm) => agent.startsWith(pm)) ?? "npm";
+  return { command: name, prefix: ["run"] };
+}
+
+/**
+ * Collect a process and all of its descendants, parents before children, so a
+ * caller can signal the whole tree. Reads /proc directly on Linux (no subprocess,
+ * and this runs on a teardown path where spawning is least welcome) and falls back
+ * to `ps` elsewhere, notably macOS.
+ */
+function collectTree(rootPid) {
+  const childrenByParent = new Map();
+  const record = (pid, ppid) => {
+    if (!Number.isInteger(pid) || !Number.isInteger(ppid)) return;
+    const siblings = childrenByParent.get(ppid);
+    if (siblings) siblings.push(pid);
+    else childrenByParent.set(ppid, [pid]);
+  };
+
+  try {
+    if (process.platform === "linux") {
+      for (const entry of readdirSync("/proc")) {
+        if (!/^\d+$/.test(entry)) continue;
+        let stat;
+        try {
+          stat = readFileSync(`/proc/${entry}/stat`, "utf8");
+        } catch {
+          continue; // the process exited between readdir and read
+        }
+        // The comm field is parenthesised and may itself contain spaces or
+        // parentheses, so split after the LAST ')' rather than on whitespace.
+        const tail = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+        record(Number(entry), Number(tail[1]));
+      }
+    } else {
+      const out = execFileSync("ps", ["-Ao", "pid=,ppid="], {
+        encoding: "utf8",
+      });
+      for (const line of out.split("\n")) {
+        const [pid, ppid] = line.trim().split(/\s+/);
+        record(Number(pid), Number(ppid));
+      }
+    }
+  } catch {
+    // Enumeration failed; fall through and signal just the root below.
+  }
+
+  const ordered = [];
+  const walk = (pid) => {
+    ordered.push(pid);
+    for (const child of childrenByParent.get(pid) ?? []) walk(child);
+  };
+  walk(rootPid);
+  return ordered;
+}
+
+const runner = resolveRunner();
+
+/** @type {Map<string, import("node:child_process").ChildProcess>} */
+const running = new Map();
+let firstFailure = null;
+let tearingDown = false;
+let signalCount = 0;
+
+function signalTree(child, signal) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  // `pid` is undefined when the spawn itself failed. There is no tree to walk,
+  // and passing it through would print a bogus "could not signal pid undefined"
+  // line (or run `taskkill /pid undefined`) on an already-failing teardown.
+  if (child.pid === undefined) return;
+
+  if (process.platform === "win32") {
+    // Windows has no process groups to signal; taskkill /T walks the tree.
+    try {
+      execFileSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+        stdio: "ignore",
+      });
+    } catch {
+      // Already gone, or not ours to kill. Nothing actionable on teardown.
+    }
+    return;
+  }
+
+  // collectTree yields parents before children; reversing signals the deepest
+  // descendants first, so an intermediate `pnpm run x` is not left briefly
+  // holding a still-live grandchild it does not forward signals to.
+  for (const pid of collectTree(child.pid).reverse()) {
+    try {
+      process.kill(pid, signal);
+    } catch (error) {
+      // ESRCH just means it already exited, which is the common case in a tree
+      // that is collapsing anyway. Anything else is worth a line, but must never
+      // mask the original failure by throwing here.
+      if (error.code !== "ESRCH") {
+        process.stderr.write(
+          `run-parallel: could not signal pid ${pid}: ${error.code ?? error.message}\n`,
+        );
+      }
+    }
+  }
+}
+
+function tearDown(signal = "SIGTERM") {
+  if (tearingDown) return;
+  tearingDown = true;
+  for (const child of running.values()) signalTree(child, signal);
+}
+
+for (const task of tasks) {
+  const child = spawn(runner.command, [...runner.prefix, task], {
+    stdio: "inherit",
+    // No `detached` -- see the header note. Children share this process group so
+    // terminal job control works and they can read the inherited TTY stdin.
+  });
+  running.set(task, child);
+
+  child.on("error", (error) => {
+    running.delete(task);
+    if (!firstFailure) {
+      firstFailure = { task, code: 1 };
+      process.stderr.write(
+        `ERROR: "${task}" failed to start: ${error.message}\n`,
+      );
+    }
+    tearDown();
+    if (running.size === 0) process.exitCode = firstFailure.code;
+  });
+
+  child.on("close", (code, signal) => {
+    running.delete(task);
+    const exitCode =
+      code === null ? 128 + (SIGNAL_NUMBERS[signal] ?? 0) : code;
+
+    if (exitCode !== 0 && !firstFailure) {
+      firstFailure = { task, code: exitCode };
+      process.stderr.write(`ERROR: "${task}" exited with ${exitCode}.\n`);
+      tearDown();
+    }
+
+    if (running.size === 0) {
+      process.exitCode = firstFailure ? firstFailure.code : 0;
+    }
+  });
+}
+
+// A terminal-generated Ctrl+C already reached the children directly, since they
+// share this process group -- but a signal aimed at this pid alone did not, and
+// without forwarding it that case would leave every child running. Re-signalling
+// a child that is already dying is harmless (ESRCH is ignored above).
+for (const name of ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"]) {
+  process.on(name, () => {
+    signalCount += 1;
+    // Escalate if a second signal arrives: something is refusing to shut down,
+    // and hanging here would strand exactly the watchers this script exists to
+    // reap. `tearingDown` is reset so the second pass is not short-circuited.
+    const forwarded = signalCount > 1 ? "SIGKILL" : name;
+    tearingDown = false;
+    tearDown(forwarded);
+  });
+}

package/bin/tags-suggest-runner.ts

@@ -13,7 +13,11 @@ import { appendFile, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import matter from "gray-matter";
+import {
+  matter,
+  stringify as stringifyFrontmatter,
+  type ParsedFrontmatter,
+} from "@takazudo/zudo-doc/frontmatter";
 
 import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
 import {
@@ -266,11 +270,11 @@ function asStringArray(v: unknown): string[] {
 
 async function writeFrontmatterTags(
   filePath: string,
-  parsed: matter.GrayMatterFile<string>,
+  parsed: ParsedFrontmatter,
   nextTags: string[],
 ): Promise<void> {
   const data = { ...parsed.data, tags: nextTags };
-  const rebuilt = matter.stringify(parsed.content, data);
+  const rebuilt = stringifyFrontmatter(parsed.content, data);
   await writeFile(filePath, rebuilt, "utf-8");
 }
 

package/dist/asset-components/asset-card.d.ts

@@ -0,0 +1,10 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import { type AssetComponentContext } from "./shared.js";
+export interface AssetCardProps {
+    src: string;
+    description?: string;
+    title?: string;
+}
+export declare function createAssetCard(context: AssetComponentContext): ({ src, description, title, }: AssetCardProps) => JSX.Element | null;

package/dist/asset-components/asset-card.js

@@ -0,0 +1,91 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+import { assetRawHref, assetViewerHref } from "../asset-path/index.js";
+import {
+  AssetFileIcon,
+  assetComponentText,
+  formatAssetBytes,
+  formatAssetLanguage,
+  MissingAssetWarning,
+  resolveAssetEntry
+} from "./shared.js";
+function createAssetCard(context) {
+  return function AssetCard({
+    src,
+    description,
+    title
+  }) {
+    if (context.assetManifest === null) return null;
+    const resolved = resolveAssetEntry(src, context);
+    if (!resolved) {
+      return /* @__PURE__ */ jsx(MissingAssetWarning, { children: "Asset not found in the asset manifest" });
+    }
+    const { path, entry } = resolved;
+    const viewerHref = assetViewerHref({
+      base: context.base,
+      routePrefix: context.routePrefix,
+      path
+    });
+    const rawHref = assetRawHref({ base: context.base, dir: context.dir, path });
+    const details = [
+      formatAssetLanguage(entry.language),
+      formatAssetBytes(entry.bytes),
+      entry.lines === void 0 ? void 0 : assetComponentText(
+        context,
+        "asset.lines",
+        "{count} lines",
+        { count: entry.lines }
+      )
+    ].filter((value) => value !== void 0);
+    const finalDescription = description ?? entry.description;
+    return /* @__PURE__ */ jsx("article", { className: "rounded-lg border border-muted bg-surface px-hsp-lg py-vsp-sm", children: /* @__PURE__ */ jsxs("div", { className: "flex items-start gap-x-hsp-md", children: [
+      /* @__PURE__ */ jsx("span", { className: "flex h-icon-lg w-icon-lg shrink-0 items-center justify-center text-muted", children: /* @__PURE__ */ jsx(AssetFileIcon, { className: "h-icon-lg w-icon-lg" }) }),
+      /* @__PURE__ */ jsxs("div", { className: "min-w-0 flex-1", children: [
+        /* @__PURE__ */ jsxs("div", { className: "font-mono text-small text-fg", children: [
+          entry.dir ? /* @__PURE__ */ jsxs("span", { className: "text-muted", children: [
+            entry.dir,
+            "/"
+          ] }) : null,
+          /* @__PURE__ */ jsx("strong", { children: title ?? entry.name })
+        ] }),
+        /* @__PURE__ */ jsx("div", { className: "mt-vsp-3xs text-caption text-muted", children: details.join(" \xB7 ") }),
+        finalDescription ? /* @__PURE__ */ jsx("p", { className: "mt-vsp-xs text-small text-muted", children: finalDescription }) : null,
+        /* @__PURE__ */ jsxs("div", { className: "mt-vsp-xs flex gap-x-hsp-lg text-caption", children: [
+          /* @__PURE__ */ jsxs(
+            "a",
+            {
+              className: "text-accent hover:underline focus-visible:underline",
+              href: viewerHref,
+              children: [
+                assetComponentText(
+                  context,
+                  "asset.viewFullFile",
+                  "View full file"
+                ),
+                " \u2192"
+              ]
+            }
+          ),
+          /* @__PURE__ */ jsxs(
+            "a",
+            {
+              className: "text-accent hover:underline focus-visible:underline",
+              href: rawHref,
+              download: true,
+              children: [
+                assetComponentText(
+                  context,
+                  "asset.download",
+                  "Download"
+                ),
+                " \u2192"
+              ]
+            }
+          )
+        ] })
+      ] })
+    ] }) });
+  };
+}
+export {
+  createAssetCard
+};

package/dist/asset-components/asset-code.d.ts

@@ -0,0 +1,10 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import { type AssetComponentContext } from "./shared.js";
+export interface AssetCodeProps {
+    src: string;
+    lines?: string;
+    title?: string;
+}
+export declare function createAssetCode(context: AssetComponentContext): ({ src, lines, title, }: AssetCodeProps) => JSX.Element | null;

package/dist/asset-components/asset-code.js

@@ -0,0 +1,93 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+import { assetViewerHref } from "../asset-path/index.js";
+import {
+  AssetFileIcon,
+  assetComponentText,
+  MissingAssetWarning,
+  resolveAssetEntry
+} from "./shared.js";
+function parseRequestedLines(value) {
+  if (value === void 0) return null;
+  const match = /^(\d+)(?:-(\d*))?$/.exec(value);
+  if (!match) return null;
+  const start = Number(match[1]);
+  if (!Number.isSafeInteger(start) || start < 1) return null;
+  if (match[2] === void 0) return { start, end: start };
+  if (match[2] === "") return { start };
+  const end = Number(match[2]);
+  if (!Number.isSafeInteger(end) || end < 1) return null;
+  return { start, end };
+}
+function createAssetCode(context) {
+  return function AssetCode({
+    src,
+    lines,
+    title
+  }) {
+    if (context.assetManifest === null) return null;
+    const resolved = resolveAssetEntry(src, context);
+    const requested = parseRequestedLines(lines);
+    if (!resolved || !requested) {
+      return /* @__PURE__ */ jsx(MissingAssetWarning, { children: "Excerpt not built \u2014 check the `lines` attribute" });
+    }
+    const requestedEnd = requested.end ?? resolved.entry.lines;
+    if (requestedEnd === void 0) {
+      return /* @__PURE__ */ jsx(MissingAssetWarning, { children: "Excerpt not built \u2014 check the `lines` attribute" });
+    }
+    const key = `${resolved.path}#${requested.start}-${requestedEnd}`;
+    const excerpt = context.assetManifest.excerpts[key];
+    if (!excerpt) {
+      return /* @__PURE__ */ jsx(MissingAssetWarning, { children: "Excerpt not built \u2014 check the `lines` attribute" });
+    }
+    const viewerHref = assetViewerHref({
+      base: context.base,
+      routePrefix: context.routePrefix,
+      path: resolved.path,
+      fragment: excerpt.viewerLineAvailable ? `L${excerpt.startLine}` : void 0
+    });
+    const shown = Math.max(0, excerpt.endLine - excerpt.startLine + 1);
+    const rangeLabel = requested.end === void 0 ? `lines ${requested.start}\u2013end` : requested.start === requested.end ? `line ${requested.start}` : `lines ${requested.start}\u2013${requested.end}`;
+    return /* @__PURE__ */ jsxs("section", { className: "overflow-hidden rounded-lg border border-muted bg-surface", children: [
+      /* @__PURE__ */ jsxs("header", { className: "flex items-center justify-between gap-x-hsp-md border-b border-muted px-hsp-lg py-vsp-2xs text-caption", children: [
+        /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 items-center gap-x-hsp-xs font-mono text-fg", children: [
+          /* @__PURE__ */ jsx(AssetFileIcon, { className: "h-icon-sm w-icon-sm shrink-0" }),
+          /* @__PURE__ */ jsx("span", { children: title ?? resolved.path })
+        ] }),
+        /* @__PURE__ */ jsx("span", { className: "shrink-0 text-muted", children: rangeLabel })
+      ] }),
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: "overflow-x-auto bg-code-bg text-code-fg text-caption",
+          dangerouslySetInnerHTML: { __html: excerpt.html }
+        }
+      ),
+      /* @__PURE__ */ jsxs("footer", { className: "flex flex-wrap items-center justify-between gap-x-hsp-md gap-y-vsp-3xs border-t border-muted px-hsp-lg py-vsp-2xs text-caption text-muted", children: [
+        /* @__PURE__ */ jsx("span", { children: assetComponentText(
+          context,
+          "asset.showingLines",
+          "Showing {shown} of {total} lines",
+          { shown, total: excerpt.totalLines }
+        ) }),
+        /* @__PURE__ */ jsxs(
+          "a",
+          {
+            className: "text-accent hover:underline focus-visible:underline",
+            href: viewerHref,
+            children: [
+              assetComponentText(
+                context,
+                "asset.viewFullFile",
+                "View full file"
+              ),
+              " \u2192"
+            ]
+          }
+        )
+      ] })
+    ] });
+  };
+}
+export {
+  createAssetCode
+};

package/dist/asset-components/index.d.ts

@@ -0,0 +1,3 @@
+export { createAssetCard, type AssetCardProps } from "./asset-card.js";
+export { createAssetCode, type AssetCodeProps } from "./asset-code.js";
+export { AssetFileIcon, formatAssetBytes, type AssetComponentContext, } from "./shared.js";

package/dist/asset-components/index.js

@@ -0,0 +1,12 @@
+import { createAssetCard } from "./asset-card.js";
+import { createAssetCode } from "./asset-code.js";
+import {
+  AssetFileIcon,
+  formatAssetBytes
+} from "./shared.js";
+export {
+  AssetFileIcon,
+  createAssetCard,
+  createAssetCode,
+  formatAssetBytes
+};

package/dist/asset-components/shared.d.ts

@@ -0,0 +1,25 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import type { AssetIndexEntry, AssetManifest } from "../route-context-payload/types.js";
+export interface AssetComponentContext {
+    base: string;
+    assetManifest: AssetManifest | null;
+    routePrefix: string;
+    dir: string;
+    /** Locale-bound package translator. Omitted callers retain English fallbacks. */
+    t?: (key: string) => string;
+}
+export declare function assetComponentText(context: AssetComponentContext, key: string, fallback: string, values?: Record<string, string | number>): string;
+export declare function resolveAssetEntry(src: string, context: AssetComponentContext): {
+    path: string;
+    entry: AssetIndexEntry;
+} | null;
+export declare function formatAssetBytes(bytes: number): string;
+export declare function formatAssetLanguage(language: string | undefined): string;
+export declare function AssetFileIcon({ className, }: {
+    className?: string;
+}): JSX.Element;
+export declare function MissingAssetWarning({ children, }: {
+    children: string;
+}): JSX.Element;

package/dist/asset-components/shared.js

@@ -0,0 +1,89 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+import { decodeAuthoredHref } from "../asset-path/index.js";
+function assetComponentText(context, key, fallback, values = {}) {
+  let text = context.t?.(key) ?? fallback;
+  for (const [name, value] of Object.entries(values)) {
+    text = text.replace(`{${name}}`, String(value));
+  }
+  return text;
+}
+function resolveAssetEntry(src, context) {
+  if (context.assetManifest === null) return null;
+  const decoded = decodeAuthoredHref(src, {
+    base: context.base,
+    dir: context.dir
+  });
+  if (!decoded) return null;
+  const entry = context.assetManifest.entries.find(
+    (candidate) => candidate.path === decoded.path
+  );
+  return entry ? { path: decoded.path, entry } : null;
+}
+function formatAssetBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 1e3) {
+    return `${Math.max(0, Math.trunc(bytes))} B`;
+  }
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1e3;
+  let unit = units[0];
+  for (let index = 1; value >= 1e3 && index < units.length; index += 1) {
+    value /= 1e3;
+    unit = units[index];
+  }
+  return `${value >= 10 ? Math.round(value) : value.toFixed(1)} ${unit}`;
+}
+function formatAssetLanguage(language) {
+  if (!language) return "File";
+  const known = {
+    javascript: "JavaScript",
+    typescript: "TypeScript",
+    jsx: "JSX",
+    tsx: "TSX",
+    json: "JSON",
+    html: "HTML",
+    css: "CSS",
+    markdown: "Markdown"
+  };
+  return known[language.toLowerCase()] ?? language;
+}
+function AssetFileIcon({
+  className
+}) {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      className,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      "stroke-width": "2",
+      "stroke-linecap": "round",
+      "stroke-linejoin": "round",
+      "aria-hidden": "true",
+      children: [
+        /* @__PURE__ */ jsx("path", { d: "M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" }),
+        /* @__PURE__ */ jsx("path", { d: "M14 2v6h6" })
+      ]
+    }
+  );
+}
+function MissingAssetWarning({
+  children
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: "rounded border border-warning/30 bg-warning/5 px-hsp-lg py-vsp-xs text-small text-warning",
+      role: "status",
+      children
+    }
+  );
+}
+export {
+  AssetFileIcon,
+  MissingAssetWarning,
+  assetComponentText,
+  formatAssetBytes,
+  formatAssetLanguage,
+  resolveAssetEntry
+};