@shadow-shard-tools/docs-core 1.0.18 → 1.0.19

package/README.md

@@ -25,6 +25,63 @@ import { CODE_LANGUAGE_CONFIG } from "@shadow-shard-tools/docs-core/configs/inde
 Everything ships as native ESM with TypeScript declarations in `dist/`. Install with `npm install @shadow-shard-tools/docs-core` (or link locally) and cherry-pick the helpers and contracts you need.
 CommonJS consumers can `require` the same subpaths via the conditional exports (built into `dist/cjs`).
 
+## API map (common imports)
+| Domain | Import from | Common exports |
+| --- | --- | --- |
+| Configs | `@shadow-shard-tools/docs-core/configs` | `loadSstDocsConfig`, `buildClientVisibleConfig`, `serializeClientConfigForBrowser`, `exposeClientConfig`, `readClientConfig`, `CODE_LANGUAGE_CONFIG` |
+| Data | `@shadow-shard-tools/docs-core/data` | `loadVersions`, `loadVersionData`, `buildTree`, `FsDataProvider`, `HttpDataProvider` |
+| Themes | `@shadow-shard-tools/docs-core/themes` | `defaultTheme`, `getThemePreset`, `AVAILABLE_THEME_PRESET_NAMES`, `StyleTheme` |
+| Utilities | `@shadow-shard-tools/docs-core/utilities` | `slugify`, `withBasePath`, `normalizeSystemPath`, `isValidImageUrl`, `createLogger` |
+| Types | `@shadow-shard-tools/docs-core/types` | `Content`, `Version`, `StyleTheme`, `SstDocsConfigFile`, `ResolvedSstDocsConfig`, `ClientVisibleSstDocsConfig` |
+
+## Quickstart recipes
+### Load config and expose client config
+```ts
+import {
+  buildClientVisibleConfig,
+  exposeClientConfig,
+  loadSstDocsConfig,
+  readClientConfig,
+  serializeClientConfigForBrowser,
+} from "@shadow-shard-tools/docs-core/configs";
+
+const config = await loadSstDocsConfig();
+const clientConfig = buildClientVisibleConfig(config);
+
+// Server-side: embed into HTML (pretty for readability while debugging)
+const clientScript = serializeClientConfigForBrowser(clientConfig, { pretty: true });
+// -> <script>{clientScript}</script>
+
+// Browser-side: attach and read from the global name (__SST_DOCS_CONFIG__ by default)
+exposeClientConfig(clientConfig);
+const cfg = readClientConfig();
+```
+
+### Load docs from FS/HTTP and build a tree
+```ts
+import path from "node:path";
+import {
+  FsDataProvider,
+  HttpDataProvider,
+  loadVersionData,
+  loadVersions,
+} from "@shadow-shard-tools/docs-core/data";
+
+// Local filesystem
+const fsProvider = new FsDataProvider();
+const dataRoot = path.resolve("./public/SST-Docs/data");
+const versions = await loadVersions(fsProvider, dataRoot);
+const versionRoot = `${dataRoot}/${versions[0]?.version ?? "current"}`;
+const { tree, items, standaloneDocs } = await loadVersionData(fsProvider, versionRoot);
+
+// Remote HTTP (e.g., CDN-hosted data)
+const httpProvider = new HttpDataProvider();
+const remoteRoot = "https://cdn.example.com/SST-Docs/data";
+const remoteVersions = await loadVersions(httpProvider, remoteRoot);
+const remoteVersionRoot = `${remoteRoot}/${remoteVersions[0]?.version ?? "current"}`;
+const { tree: remoteTree } = await loadVersionData(httpProvider, remoteVersionRoot);
+```
+
 ### Config example
 Create `sst-docs.config.json` in your project root:
 ```json

package/dist/cjs/configs/clientConfig.js

@@ -5,7 +5,25 @@ exports.buildClientVisibleConfig = buildClientVisibleConfig;
 exports.serializeClientConfigForBrowser = serializeClientConfigForBrowser;
 exports.exposeClientConfig = exposeClientConfig;
 exports.readClientConfig = readClientConfig;
+const zod_1 = require("zod");
+const styleThemeSchema_js_1 = require("../themes/styleThemeSchema.js");
 exports.DEFAULT_CLIENT_CONFIG_GLOBAL = "__SST_DOCS_CONFIG__";
+const headerBrandingSchema = zod_1.z
+    .object({
+    logoSrc: zod_1.z.string().optional(),
+    logoAlt: zod_1.z.string().optional(),
+    logoText: zod_1.z.string().optional(),
+})
+    .strict()
+    .optional()
+    .default({});
+const clientConfigSchema = zod_1.z
+    .object({
+    PUBLIC_DATA_PATH: zod_1.z.string(),
+    HEADER_BRANDING: headerBrandingSchema,
+    HTML_GENERATOR_THEME: styleThemeSchema_js_1.styleThemeSchema.optional(),
+})
+    .strict();
 function buildClientVisibleConfig(config) {
     return {
         PUBLIC_DATA_PATH: config.PUBLIC_DATA_PATH,
@@ -39,124 +57,22 @@ function readClientConfig(globalName = exports.DEFAULT_CLIENT_CONFIG_GLOBAL) {
     return assertClientConfig(value, globalName);
 }
 function normalizeAndValidateClientConfigSource(source) {
-    const normalized = isClientConfig(source)
+    const normalized = isClientConfigShape(source)
         ? source
         : buildClientVisibleConfig(source);
     return assertClientConfig(normalized);
 }
 function assertClientConfig(value, globalName = exports.DEFAULT_CLIENT_CONFIG_GLOBAL) {
-    if (!isClientConfig(value)) {
-        throw new Error(`Client config "${globalName}" is missing or malformed on globalThis.`);
-    }
-    return value;
-}
-function isClientConfig(value) {
-    if (!value || typeof value !== "object") {
-        return false;
-    }
-    const candidate = value;
-    const hasPublicPath = typeof candidate.PUBLIC_DATA_PATH === "string";
-    const hasBranding = isHeaderBranding(candidate.HEADER_BRANDING);
-    const hasTheme = candidate.HTML_GENERATOR_THEME === undefined ||
-        isStyleTheme(candidate.HTML_GENERATOR_THEME);
-    return hasPublicPath && hasBranding && hasTheme;
-}
-function isHeaderBranding(value) {
-    if (value === undefined)
-        return true;
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    return (["logoSrc", "logoAlt", "logoText"].every((key) => key in record ? typeof record[key] === "string" || record[key] === undefined : true));
+    const parsed = clientConfigSchema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    const message = parsed.error.issues
+        .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+        .join("; ");
+    throw new Error(`Client config "${globalName}" is missing or malformed on globalThis. ${message}`);
 }
-function isStyleTheme(value) {
+function isClientConfigShape(value) {
     if (!value || typeof value !== "object")
         return false;
-    const theme = value;
-    const stringProps = (obj, keys) => !!obj &&
-        typeof obj === "object" &&
-        keys.every((k) => typeof obj[k] === "string");
-    return (typeof theme.input === "string" &&
-        stringProps(theme.text, [
-            "logoText",
-            "documentTitle",
-            "breadcrumb",
-            "titleLevel1",
-            "titleLevel2",
-            "titleLevel3",
-            "titleAnchor",
-            "general",
-            "alternative",
-            "list",
-            "math",
-        ]) &&
-        stringProps(theme.hints, ["text", "key"]) &&
-        stringProps(theme.divider, ["border", "gradient", "text"]) &&
-        stringProps(theme.buttons, ["common", "small", "tabSmall", "tabSmallActive"]) &&
-        stringProps(theme.dropdown, ["container", "item", "itemActive"]) &&
-        stringProps(theme.messageBox, [
-            "info",
-            "warning",
-            "error",
-            "success",
-            "neutral",
-            "quote",
-        ]) &&
-        stringProps(theme.table, ["cornerCell", "headers", "rows", "border", "empty"]) &&
-        stringProps(theme.code, ["header", "language", "lines", "empty"]) &&
-        stringProps(theme.audioPlayer, [
-            "container",
-            "playButton",
-            "time",
-            "slider",
-            "sliderThumb",
-            "sliderTrackColor",
-            "sliderFillColor",
-        ]) &&
-        stringProps(theme.chart, [
-            "legendLabelColor",
-            "tooltipBg",
-            "tooltipTitleColor",
-            "tooltipBodyColor",
-            "tooltipBorderColor",
-            "axisTickColor",
-            "gridLineColor",
-        ]) &&
-        stringProps(theme.graph, ["background", "defaultCurve"]) &&
-        stringProps(theme.searchModal, [
-            "resultBackground",
-            "resultEmptyInputText",
-            "resultNoResultText",
-            "header",
-            "footer",
-            "borders",
-            "item",
-            "selectedItem",
-            "itemHeaderText",
-            "itemFoundSectionText",
-            "itemTags",
-        ]) &&
-        stringProps(theme.navigation, [
-            "row",
-            "rowActive",
-            "rowFocused",
-            "rowHover",
-            "hideOrShowHintsText",
-        ]) &&
-        stringProps(theme.category, [
-            "empty",
-            "cardBody",
-            "cardHeaderText",
-            "cardDescriptionText",
-        ]) &&
-        stringProps(theme.sections, [
-            "siteBackground",
-            "siteBorders",
-            "headerBackground",
-            "headerMobileBackground",
-            "sidebarBackground",
-            "documentHeaderBackground",
-            "contentBackground",
-        ]) &&
-        stringProps(theme.header, ["mobileNavigationToggle", "mobileMenuToggle"]));
+    return clientConfigSchema.safeParse(value).success;
 }

package/dist/cjs/configs/index.browser.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeClientConfigForBrowser = exports.readClientConfig = exports.exposeClientConfig = exports.DEFAULT_CLIENT_CONFIG_GLOBAL = exports.buildClientVisibleConfig = exports.SST_DOCS_CONFIG_FILENAME = exports.SstDocsConfigError = exports.resolvePublicDataPath = exports.derivePublicDataPath = exports.CODE_LANGUAGE_CONFIG = void 0;
+var codeLanguagesConfig_js_1 = require("./codeLanguagesConfig.js");
+Object.defineProperty(exports, "CODE_LANGUAGE_CONFIG", { enumerable: true, get: function () { return codeLanguagesConfig_js_1.CODE_LANGUAGE_CONFIG; } });
+var sstDocsConfigShared_js_1 = require("./sstDocsConfigShared.js");
+Object.defineProperty(exports, "derivePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.derivePublicDataPath; } });
+Object.defineProperty(exports, "resolvePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.resolvePublicDataPath; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SstDocsConfigError; } });
+Object.defineProperty(exports, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME; } });
+var clientConfig_js_1 = require("./clientConfig.js");
+Object.defineProperty(exports, "buildClientVisibleConfig", { enumerable: true, get: function () { return clientConfig_js_1.buildClientVisibleConfig; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_CONFIG_GLOBAL", { enumerable: true, get: function () { return clientConfig_js_1.DEFAULT_CLIENT_CONFIG_GLOBAL; } });
+Object.defineProperty(exports, "exposeClientConfig", { enumerable: true, get: function () { return clientConfig_js_1.exposeClientConfig; } });
+Object.defineProperty(exports, "readClientConfig", { enumerable: true, get: function () { return clientConfig_js_1.readClientConfig; } });
+Object.defineProperty(exports, "serializeClientConfigForBrowser", { enumerable: true, get: function () { return clientConfig_js_1.serializeClientConfigForBrowser; } });

package/dist/cjs/configs/sstDocsConfigShared.js

@@ -1,16 +1,15 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SstDocsConfigError = exports.SST_DOCS_CONFIG_FILENAME = void 0;
+exports.SST_DOCS_CONFIG_REFERENCE = exports.SstDocsConfigError = exports.SST_DOCS_CONFIG_FILENAME = void 0;
 exports.parseConfigContents = parseConfigContents;
 exports.derivePublicDataPath = derivePublicDataPath;
 exports.resolvePublicDataPath = resolvePublicDataPath;
 const themeRegistry_js_1 = require("../themes/themeRegistry.js");
-const node_path_1 = __importDefault(require("node:path"));
 const normalizeSystemPath_js_1 = require("../utilities/string/normalizeSystemPath.js");
+const zod_1 = require("zod");
 exports.SST_DOCS_CONFIG_FILENAME = "sst-docs.config.json";
+const DEFAULT_FS_DATA_PATH = "./public/SST-Docs/data";
+const DEFAULT_OUTPUT_DIRECTORY = "./dist/html";
 class SstDocsConfigError extends Error {
     constructor(message) {
         super(message);
@@ -18,6 +17,111 @@ class SstDocsConfigError extends Error {
     }
 }
 exports.SstDocsConfigError = SstDocsConfigError;
+exports.SST_DOCS_CONFIG_REFERENCE = [
+    {
+        key: "FS_DATA_PATH",
+        type: "string",
+        required: true,
+        default: DEFAULT_FS_DATA_PATH,
+        description: "Absolute or project-relative path to the docs data root (contains versions.json).",
+    },
+    {
+        key: "HEADER_BRANDING.logoSrc",
+        type: "string",
+        required: false,
+        description: "Optional logo image path/URL shown in the header.",
+    },
+    {
+        key: "HEADER_BRANDING.logoAlt",
+        type: "string",
+        required: false,
+        description: "Optional alt text for the logo image.",
+    },
+    {
+        key: "HEADER_BRANDING.logoText",
+        type: "string",
+        required: false,
+        description: "Optional text fallback when no logo image is provided.",
+    },
+    {
+        key: "HTML_GENERATOR_SETTINGS.OUTPUT_DIRECTORY",
+        type: "string",
+        required: true,
+        default: DEFAULT_OUTPUT_DIRECTORY,
+        description: "Where the HTML generator writes the output bundle.",
+    },
+    {
+        key: "HTML_GENERATOR_SETTINGS.THEME",
+        type: "string",
+        required: true,
+        default: themeRegistry_js_1.DEFAULT_THEME_PRESET,
+        description: `Theme preset name. Options: ${themeRegistry_js_1.AVAILABLE_THEME_PRESET_NAMES.join(", ")}.`,
+    },
+    {
+        key: "HTML_GENERATOR_SETTINGS.SEPARATE_BUILD_FOR_HTML_GENERATOR",
+        type: "boolean",
+        required: false,
+        default: "false",
+        description: "Whether to run a separate build for the HTML generator.",
+    },
+];
+const optionalTrimmedString = zod_1.z
+    .string()
+    .trim()
+    .transform((value) => (value.length > 0 ? value : undefined))
+    .optional();
+const HeaderBrandingSchema = zod_1.z
+    .object({
+    logoSrc: optionalTrimmedString,
+    logoAlt: optionalTrimmedString,
+    logoText: optionalTrimmedString,
+})
+    .strict()
+    .transform((value) => value);
+const HtmlGeneratorSettingsSchema = zod_1.z
+    .object({
+    OUTPUT_DIRECTORY: zod_1.z
+        .string()
+        .trim()
+        .min(1, {
+        message: `Set HTML_GENERATOR_SETTINGS.OUTPUT_DIRECTORY (default: "${DEFAULT_OUTPUT_DIRECTORY}")`,
+    })
+        .transform((val) => (0, normalizeSystemPath_js_1.normalizeSystemPath)(val)),
+    THEME: zod_1.z
+        .string()
+        .trim()
+        .min(1, {
+        message: `Set HTML_GENERATOR_SETTINGS.THEME (default: "${themeRegistry_js_1.DEFAULT_THEME_PRESET}")`,
+    })
+        .transform((value, ctx) => {
+        const normalized = value.toLowerCase();
+        if (!(0, themeRegistry_js_1.isThemePresetName)(normalized)) {
+            const options = themeRegistry_js_1.AVAILABLE_THEME_PRESET_NAMES.join(", ");
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `HTML_GENERATOR_SETTINGS.THEME must be one of: ${options} (default: "${themeRegistry_js_1.DEFAULT_THEME_PRESET}")`,
+            });
+            return zod_1.z.NEVER;
+        }
+        return cloneTheme((0, themeRegistry_js_1.getThemePreset)(normalized));
+    }),
+    SEPARATE_BUILD_FOR_HTML_GENERATOR: zod_1.z.boolean().default(false),
+})
+    .strict()
+    .transform((value) => value);
+const ConfigSchema = zod_1.z
+    .object({
+    FS_DATA_PATH: zod_1.z
+        .string()
+        .trim()
+        .min(1, {
+        message: `Provide FS_DATA_PATH (default: "${DEFAULT_FS_DATA_PATH}")`,
+    })
+        .transform((val) => (0, normalizeSystemPath_js_1.normalizeSystemPath)(val)),
+    HEADER_BRANDING: HeaderBrandingSchema.optional().transform((value) => value ?? {}),
+    HTML_GENERATOR_SETTINGS: HtmlGeneratorSettingsSchema.optional(),
+})
+    .strict();
 function parseConfigContents(contents, sourcePath) {
     let parsed;
     try {
@@ -26,11 +130,21 @@ function parseConfigContents(contents, sourcePath) {
     catch (error) {
         throw new SstDocsConfigError(`Failed to parse ${exports.SST_DOCS_CONFIG_FILENAME}: ${error.message}`);
     }
-    return normalizeConfig(parsed, sourcePath);
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new SstDocsConfigError(formatConfigValidationError(sourcePath, result.error));
+    }
+    const resolved = result.data;
+    return {
+        FS_DATA_PATH: resolved.FS_DATA_PATH,
+        PUBLIC_DATA_PATH: derivePublicDataPath(resolved.FS_DATA_PATH),
+        HEADER_BRANDING: resolved.HEADER_BRANDING,
+        HTML_GENERATOR_SETTINGS: resolved.HTML_GENERATOR_SETTINGS,
+    };
 }
 function derivePublicDataPath(fsDataPath) {
     const normalizedFsPath = (0, normalizeSystemPath_js_1.normalizeSystemPath)(fsDataPath.trim());
-    const posixPath = node_path_1.default.posix.normalize(normalizedFsPath || "/");
+    const posixPath = normalizePosixPath(normalizedFsPath || "/");
     const segments = posixPath.split("/").filter(Boolean);
     const publicIndex = segments.indexOf("public");
     const publicSegments = publicIndex >= 0 ? segments.slice(publicIndex + 1) : segments;
@@ -57,14 +171,14 @@ function resolvePublicDataPath(baseUrl, config) {
 }
 function normalizePublicPath(value) {
     const normalized = (0, normalizeSystemPath_js_1.normalizeSystemPath)(value.trim());
-    const posixPath = node_path_1.default.posix.normalize(normalized || "/");
+    const posixPath = normalizePosixPath(normalized || "/");
     const withLeading = posixPath.startsWith("/") ? posixPath : `/${posixPath}`;
     return withLeading.endsWith("/") ? withLeading : `${withLeading}/`;
 }
 function joinUrlPaths(base, child) {
     const normalizedBase = normalizePublicPath(base);
     const normalizedChild = normalizePublicPath(child).replace(/^\/+/, "");
-    const joined = node_path_1.default.posix.join(normalizedBase, normalizedChild);
+    const joined = normalizePosixPath(`${normalizedBase}${normalizedChild ? `/${normalizedChild}` : ""}`);
     return joined.endsWith("/") ? joined : `${joined}/`;
 }
 function isAbsoluteUrl(value) {
@@ -76,99 +190,43 @@ function isAbsoluteUrl(value) {
         return false;
     }
 }
-function normalizeConfig(value, sourcePath) {
-    if (!value || typeof value !== "object") {
-        throw new SstDocsConfigError(`Invalid configuration in ${sourcePath}: expected an object`);
-    }
-    const raw = value;
-    if (typeof raw.FS_DATA_PATH !== "string") {
-        throw new SstDocsConfigError(`Missing or invalid FS_DATA_PATH in ${sourcePath}`);
-    }
-    const fsDataPath = (0, normalizeSystemPath_js_1.normalizeSystemPath)(raw.FS_DATA_PATH.trim());
-    if (fsDataPath.length === 0) {
-        throw new SstDocsConfigError(`FS_DATA_PATH cannot be empty in ${sourcePath}`);
-    }
-    return {
-        FS_DATA_PATH: fsDataPath,
-        PUBLIC_DATA_PATH: derivePublicDataPath(fsDataPath),
-        HEADER_BRANDING: normalizeHeaderBranding(raw.HEADER_BRANDING, sourcePath),
-        HTML_GENERATOR_SETTINGS: normalizeHtmlGeneratorSettings(raw.HTML_GENERATOR_SETTINGS, sourcePath),
-    };
-}
-function normalizeHeaderBranding(value, sourcePath) {
-    if (value === undefined) {
-        return {};
-    }
-    if (!value || typeof value !== "object") {
-        throw new SstDocsConfigError(`HEADER_BRANDING must be an object in ${sourcePath}`);
-    }
-    const { logoSrc, logoAlt, logoText } = value;
-    return {
-        logoSrc: normalizeOptionalString(logoSrc, "logoSrc", sourcePath),
-        logoAlt: normalizeOptionalString(logoAlt, "logoAlt", sourcePath),
-        logoText: normalizeOptionalString(logoText, "logoText", sourcePath),
-    };
-}
-function normalizeOptionalString(value, key, sourcePath) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value !== "string") {
-        throw new SstDocsConfigError(`HEADER_BRANDING.${key} must be a string in ${sourcePath}`);
-    }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-function normalizeHtmlGeneratorSettings(value, sourcePath) {
-    if (value === undefined) {
-        return undefined;
-    }
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new SstDocsConfigError(`HTML_GENERATOR_SETTINGS must be an object in ${sourcePath}`);
-    }
-    const { OUTPUT_DIRECTORY, THEME, SEPARATE_BUILD_FOR_HTML_GENERATOR, } = value;
-    if (typeof OUTPUT_DIRECTORY !== "string") {
-        throw new SstDocsConfigError(`HTML_GENERATOR_SETTINGS.OUTPUT_DIRECTORY must be a string in ${sourcePath}`);
-    }
-    const outputDirectory = (0, normalizeSystemPath_js_1.normalizeSystemPath)(OUTPUT_DIRECTORY.trim());
-    if (outputDirectory.length === 0) {
-        throw new SstDocsConfigError(`HTML_GENERATOR_SETTINGS.OUTPUT_DIRECTORY cannot be empty in ${sourcePath}`);
-    }
-    if (THEME === undefined) {
-        throw new SstDocsConfigError(`HTML_GENERATOR_SETTINGS.THEME must be provided in ${sourcePath}`);
-    }
-    if (SEPARATE_BUILD_FOR_HTML_GENERATOR !== undefined &&
-        typeof SEPARATE_BUILD_FOR_HTML_GENERATOR !== "boolean") {
-        throw new SstDocsConfigError(`HTML_GENERATOR_SETTINGS.SEPARATE_BUILD_FOR_HTML_GENERATOR must be a boolean in ${sourcePath}`);
-    }
-    const resolvedTheme = resolveThemeConfiguration(THEME, sourcePath);
-    return {
-        OUTPUT_DIRECTORY: outputDirectory,
-        THEME: resolvedTheme,
-        SEPARATE_BUILD_FOR_HTML_GENERATOR: SEPARATE_BUILD_FOR_HTML_GENERATOR ?? false,
-    };
+function cloneTheme(theme) {
+    return JSON.parse(JSON.stringify(theme));
 }
-function resolveThemeConfiguration(value, sourcePath) {
-    if (typeof value !== "string") {
-        throw new SstDocsConfigError(`HTML_GENERATOR_SETTINGS.THEME must be a string preset in ${sourcePath}`);
-    }
-    const themeName = ensureThemePresetName(value, sourcePath, "HTML_GENERATOR_SETTINGS.THEME");
-    return cloneTheme((0, themeRegistry_js_1.getThemePreset)(themeName));
+function formatConfigValidationError(sourcePath, error) {
+    const lines = error.issues.map((issue) => {
+        const path = issue.path.join(".") || "config";
+        const defaultValue = defaultValueFor(path);
+        const hint = defaultValue ? ` (default: ${defaultValue})` : "";
+        return `${path}: ${issue.message}${hint}`;
+    });
+    return `Invalid configuration in ${sourcePath}:\n- ${lines.join("\n- ")}`;
 }
-function ensureThemePresetName(raw, sourcePath, propertyPath) {
-    if (raw === undefined || raw === null) {
-        return themeRegistry_js_1.DEFAULT_THEME_PRESET;
-    }
-    if (typeof raw !== "string") {
-        const options = themeRegistry_js_1.AVAILABLE_THEME_PRESET_NAMES.join(", ");
-        throw new SstDocsConfigError(`${propertyPath} must be one of: ${options} in ${sourcePath}`);
-    }
-    const normalized = raw.trim().toLowerCase();
-    if (!(0, themeRegistry_js_1.isThemePresetName)(normalized)) {
-        const options = themeRegistry_js_1.AVAILABLE_THEME_PRESET_NAMES.join(", ");
-        throw new SstDocsConfigError(`Unknown ${propertyPath} "${raw}" in ${sourcePath}. Supported presets: ${options}`);
-    }
-    return normalized;
+function defaultValueFor(path) {
+    return exports.SST_DOCS_CONFIG_REFERENCE.find((entry) => entry.key === path)?.default;
 }
-function cloneTheme(theme) {
-    return JSON.parse(JSON.stringify(theme));
+function normalizePosixPath(value) {
+    const sanitized = value.replace(/\\/g, "/");
+    const hasLeadingSlash = sanitized.startsWith("/");
+    const parts = sanitized.split("/");
+    const stack = [];
+    for (const part of parts) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..") {
+            if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+                stack.pop();
+            }
+            else if (!hasLeadingSlash) {
+                stack.push("..");
+            }
+            continue;
+        }
+        stack.push(part);
+    }
+    const normalized = stack.join("/");
+    if (hasLeadingSlash) {
+        return `/${normalized}`;
+    }
+    return normalized || ".";
 }

package/dist/cjs/data/buildTree.js

@@ -1,9 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildTree = buildTree;
-function convertCategory(raw, rawMap, docLookup, usedDocIds, included, visiting) {
+const logger_js_1 = require("../utilities/system/logger.js");
+function convertCategory(raw, rawMap, docLookup, usedDocIds, included, visiting, diagnostics, logger) {
     if (visiting.has(raw.id)) {
-        console.warn(`Detected circular category reference at ${raw.id}.`);
+        const message = `Detected circular category reference at ${raw.id}.`;
+        diagnostics.push({
+            code: "circular-category",
+            level: "warn",
+            message,
+            context: { categoryId: raw.id },
+        });
+        logger.warn(message);
         return null;
     }
     visiting.add(raw.id);
@@ -13,12 +21,26 @@ function convertCategory(raw, rawMap, docLookup, usedDocIds, included, visiting)
         const validDocs = docIds
             .map((rawId) => {
             if (typeof rawId !== "string" || rawId.length === 0) {
-                console.warn(`Invalid doc id in category ${raw.id}:`, rawId);
+                const message = `Invalid doc id in category ${raw.id}.`;
+                diagnostics.push({
+                    code: "invalid-doc-ref",
+                    level: "warn",
+                    message,
+                    context: { categoryId: raw.id, docId: rawId },
+                });
+                logger.warn(message);
                 return null;
             }
             const doc = docLookup.get(rawId);
             if (!doc) {
-                console.warn(`Doc id ${rawId} referenced in category ${raw.id} not found.`);
+                const message = `Doc id ${rawId} referenced in category ${raw.id} not found.`;
+                diagnostics.push({
+                    code: "missing-doc-ref",
+                    level: "warn",
+                    message,
+                    context: { categoryId: raw.id, docId: rawId },
+                });
+                logger.warn(message);
                 return null;
             }
             usedDocIds.add(rawId);
@@ -35,15 +57,29 @@ function convertCategory(raw, rawMap, docLookup, usedDocIds, included, visiting)
         const validChildren = childIds
             .map((rawChildId) => {
             if (typeof rawChildId !== "string" || rawChildId.length === 0) {
-                console.warn(`Invalid child category id in ${raw.id}:`, rawChildId);
+                const message = `Invalid child category id in ${raw.id}.`;
+                diagnostics.push({
+                    code: "invalid-child-ref",
+                    level: "warn",
+                    message,
+                    context: { categoryId: raw.id, childId: rawChildId },
+                });
+                logger.warn(message);
                 return null;
             }
             const childRaw = rawMap[rawChildId];
             if (!childRaw) {
-                console.warn(`Child category ${rawChildId} referenced in ${raw.id} not found.`);
+                const message = `Child category ${rawChildId} referenced in ${raw.id} not found.`;
+                diagnostics.push({
+                    code: "missing-child-ref",
+                    level: "warn",
+                    message,
+                    context: { categoryId: raw.id, childId: rawChildId },
+                });
+                logger.warn(message);
                 return null;
             }
-            return convertCategory(childRaw, rawMap, docLookup, usedDocIds, included, visiting);
+            return convertCategory(childRaw, rawMap, docLookup, usedDocIds, included, visiting, diagnostics, logger);
         })
             .filter((child) => child !== null);
         if (validChildren.length > 0) {
@@ -61,10 +97,12 @@ function convertCategory(raw, rawMap, docLookup, usedDocIds, included, visiting)
         children,
     };
 }
-function buildTree(rawMap, allDocs) {
+function buildTree(rawMap, allDocs, options) {
     const docLookup = new Map(allDocs.map((d) => [d.id, d]));
     const usedDocIds = new Set();
     const includedIds = new Set();
+    const diagnostics = [];
+    const logger = options?.logger ?? (0, logger_js_1.createLogger)("data:buildTree");
     const childCategoryIds = new Set();
     Object.values(rawMap).forEach((category) => {
         if (Array.isArray(category?.children)) {
@@ -86,8 +124,8 @@ function buildTree(rawMap, allDocs) {
         .map((rootCategory) => {
         if (includedIds.has(rootCategory.id))
             return null;
-        return convertCategory(rootCategory, rawMap, docLookup, usedDocIds, includedIds, new Set());
+        return convertCategory(rootCategory, rawMap, docLookup, usedDocIds, includedIds, new Set(), diagnostics, logger);
     })
         .filter((category) => category !== null);
-    return { tree, usedDocIds };
+    return { tree, usedDocIds, diagnostics };
 }

package/dist/cjs/data/fsDataProvider.browser.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fsDataProvider = exports.FsDataProvider = void 0;
+class FsDataProvider {
+    async readJson(_absPath) {
+        throw new Error("FsDataProvider is only available in Node.js environments where the file system can be read.");
+    }
+}
+exports.FsDataProvider = FsDataProvider;
+exports.fsDataProvider = FsDataProvider;