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

package/README.md

@@ -2,18 +2,16 @@
 Core runtime for the Shadow Shard Tools documentation stack. It gathers the shared themes, configuration objects, navigation helpers, typed content models, and browser-friendly utilities relied on by the site and generator projects.
 
 ## Contents
-- `configs`: Tailwind-friendly theme wiring plus code-language metadata (`CODE_LANGUAGE_CONFIG`, `stylesConfig`).
+- `configs`: Tailwind-friendly theme wiring plus code-language metadata (`CODE_LANGUAGE_CONFIG`).
 - `data`: File-system drivers for loading doc versions, category trees, and item payloads (`loadVersions`, `loadVersionData`, `buildTree`, etc.).
-- `themes`: Prebuilt light/dark `StyleTheme` definitions used by the Tailwind bridge.
+- `themes`: Prebuilt `StyleTheme` presets (currently `default`) used by the Tailwind bridge.
 - `types`: Source-of-truth TypeScript contracts for doc content, theme structures, and provider interfaces.
 - `utilities`: DOM, validation, string, and file helpers that the site and exporters share (e.g. `slugify`, `withBasePath`, `isValidImageUrl`).
 
 ## Usage
 ```ts
 import {
-  darkTheme,
-  lightTheme,
-  stylesConfig,
+  defaultTheme,
   loadVersions,
   loadVersionData,
   slugify,
@@ -25,6 +23,31 @@ import {
 import { CODE_LANGUAGE_CONFIG } from "@shadow-shard-tools/docs-core/configs/index.js";
 ```
 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`).
+
+### Config example
+Create `sst-docs.config.json` in your project root:
+```json
+{
+  "FS_DATA_PATH": "./public/SST-Docs/data",
+  "HEADER_BRANDING": {
+    "logoText": "SST Docs"
+  },
+  "HTML_GENERATOR_SETTINGS": {
+    "OUTPUT_DIRECTORY": "./dist/html",
+    "THEME": "default",
+    "SEPARATE_BUILD_FOR_HTML_GENERATOR": false
+  }
+}
+```
+Load and expose a browser-friendly subset:
+```ts
+import { loadSstDocsConfig, buildClientVisibleConfig, serializeClientConfigForBrowser } from "@shadow-shard-tools/docs-core/configs";
+
+const config = await loadSstDocsConfig();
+const clientConfig = buildClientVisibleConfig(config);
+const script = serializeClientConfigForBrowser(clientConfig); // inject into HTML to populate window.__SST_DOCS_CONFIG__
+```
 
 ## Development
 ```bash

package/dist/cjs/configs/clientConfig.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLIENT_CONFIG_GLOBAL = void 0;
+exports.buildClientVisibleConfig = buildClientVisibleConfig;
+exports.serializeClientConfigForBrowser = serializeClientConfigForBrowser;
+exports.exposeClientConfig = exposeClientConfig;
+exports.readClientConfig = readClientConfig;
+exports.DEFAULT_CLIENT_CONFIG_GLOBAL = "__SST_DOCS_CONFIG__";
+function buildClientVisibleConfig(config) {
+    return {
+        PUBLIC_DATA_PATH: config.PUBLIC_DATA_PATH,
+        HEADER_BRANDING: config.HEADER_BRANDING,
+        HTML_GENERATOR_THEME: config.HTML_GENERATOR_SETTINGS?.THEME,
+    };
+}
+function serializeClientConfigForBrowser(source, options) {
+    const payload = normalizeAndValidateClientConfigSource(source);
+    const globalName = options?.globalName ?? exports.DEFAULT_CLIENT_CONFIG_GLOBAL;
+    const spacing = options?.pretty ? 2 : undefined;
+    return `window.${globalName} = ${JSON.stringify(payload, null, spacing)};`;
+}
+function exposeClientConfig(source, options) {
+    const payload = normalizeAndValidateClientConfigSource(source);
+    const target = options?.target ??
+        globalThis;
+    if (!target) {
+        throw new Error("Unable to expose client config: no target global object was provided.");
+    }
+    const globalName = options?.globalName ?? exports.DEFAULT_CLIENT_CONFIG_GLOBAL;
+    target[globalName] = payload;
+    return payload;
+}
+function readClientConfig(globalName = exports.DEFAULT_CLIENT_CONFIG_GLOBAL) {
+    const globalObject = globalThis;
+    if (!globalObject) {
+        throw new Error("globalThis is not available in the current environment.");
+    }
+    const value = globalObject[globalName];
+    return assertClientConfig(value, globalName);
+}
+function normalizeAndValidateClientConfigSource(source) {
+    const normalized = isClientConfig(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));
+}
+function isStyleTheme(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"]));
+}

package/dist/cjs/configs/codeLanguagesConfig.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_LANGUAGE_CONFIG = void 0;
+exports.CODE_LANGUAGE_CONFIG = {
+    javascript: { name: "JavaScript", ext: "js" },
+    typescript: { name: "TypeScript", ext: "ts" },
+    python: { name: "Python", ext: "py" },
+    java: { name: "Java", ext: "java" },
+    csharp: { name: "C#", ext: "cs" },
+    cpp: { name: "C++", ext: "cpp" },
+    c: { name: "C", ext: "c" },
+    php: { name: "PHP", ext: "php" },
+    ruby: { name: "Ruby", ext: "rb" },
+    go: { name: "Go", ext: "go" },
+    rust: { name: "Rust", ext: "rs" },
+    swift: { name: "Swift", ext: "swift" },
+    kotlin: { name: "Kotlin", ext: "kt" },
+    scala: { name: "Scala", ext: "scala" },
+    html: { name: "HTML", ext: "html" },
+    css: { name: "CSS", ext: "css" },
+    scss: { name: "SCSS", ext: "scss" },
+    sass: { name: "Sass", ext: "sass" },
+    less: { name: "Less", ext: "less" },
+    json: { name: "JSON", ext: "json" },
+    xml: { name: "XML", ext: "xml" },
+    yaml: { name: "YAML", ext: "yml" },
+    toml: { name: "TOML", ext: "toml" },
+    sql: { name: "SQL", ext: "sql" },
+    bash: { name: "Bash", ext: "sh" },
+    powershell: { name: "PowerShell", ext: "ps1" },
+    dockerfile: { name: "Dockerfile", ext: "dockerfile" },
+    markdown: { name: "Markdown", ext: "md" },
+    latex: { name: "LaTeX", ext: "tex" },
+    plaintext: { name: "Plain Text", ext: "txt" },
+    text: { name: "Text", ext: "txt" },
+};

package/dist/cjs/configs/index.js

@@ -0,0 +1,20 @@
+"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.loadSstDocsConfigFromSync = exports.loadSstDocsConfigSync = exports.loadSstDocsConfigFrom = exports.loadSstDocsConfig = 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 sstDocsConfig_js_1 = require("./sstDocsConfig.js");
+Object.defineProperty(exports, "loadSstDocsConfig", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfig; } });
+Object.defineProperty(exports, "loadSstDocsConfigFrom", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfigFrom; } });
+Object.defineProperty(exports, "loadSstDocsConfigSync", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfigSync; } });
+Object.defineProperty(exports, "loadSstDocsConfigFromSync", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfigFromSync; } });
+Object.defineProperty(exports, "derivePublicDataPath", { enumerable: true, get: function () { return sstDocsConfig_js_1.derivePublicDataPath; } });
+Object.defineProperty(exports, "resolvePublicDataPath", { enumerable: true, get: function () { return sstDocsConfig_js_1.resolvePublicDataPath; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfig_js_1.SstDocsConfigError; } });
+Object.defineProperty(exports, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfig_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/sstDocsConfig.browser.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SstDocsConfigError = exports.SST_DOCS_CONFIG_FILENAME = exports.resolvePublicDataPath = exports.derivePublicDataPath = void 0;
+exports.loadSstDocsConfig = loadSstDocsConfig;
+exports.loadSstDocsConfigSync = loadSstDocsConfigSync;
+exports.loadSstDocsConfigFrom = loadSstDocsConfigFrom;
+exports.loadSstDocsConfigFromSync = loadSstDocsConfigFromSync;
+const 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, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SstDocsConfigError; } });
+function unsupported(method) {
+    throw new sstDocsConfigShared_js_1.SstDocsConfigError(`${method} is only available in a Node.js environment where the file system can be read.`);
+}
+async function loadSstDocsConfig(_configPath) {
+    return unsupported("loadSstDocsConfig");
+}
+function loadSstDocsConfigSync(_configPath) {
+    return unsupported("loadSstDocsConfigSync");
+}
+async function loadSstDocsConfigFrom(_configDir) {
+    return unsupported("loadSstDocsConfigFrom");
+}
+function loadSstDocsConfigFromSync(_configDir) {
+    return unsupported("loadSstDocsConfigFromSync");
+}

package/dist/cjs/configs/sstDocsConfig.js

@@ -0,0 +1,88 @@
+"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 = exports.resolvePublicDataPath = exports.derivePublicDataPath = void 0;
+exports.loadSstDocsConfig = loadSstDocsConfig;
+exports.loadSstDocsConfigSync = loadSstDocsConfigSync;
+exports.loadSstDocsConfigFrom = loadSstDocsConfigFrom;
+exports.loadSstDocsConfigFromSync = loadSstDocsConfigFromSync;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const app_root_path_1 = __importDefault(require("app-root-path"));
+const 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, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SstDocsConfigError; } });
+const APP_ROOT = app_root_path_1.default.path;
+async function loadSstDocsConfig(configPath) {
+    const { path: finalPath, contents } = await readConfigFile(configPath);
+    return (0, sstDocsConfigShared_js_1.parseConfigContents)(contents, finalPath);
+}
+function loadSstDocsConfigSync(configPath) {
+    const { path: finalPath, contents } = readConfigFileSync(configPath);
+    return (0, sstDocsConfigShared_js_1.parseConfigContents)(contents, finalPath);
+}
+async function loadSstDocsConfigFrom(configDir) {
+    const fullPath = (0, node_path_1.resolve)(configDir, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME);
+    return loadSstDocsConfig(fullPath);
+}
+function loadSstDocsConfigFromSync(configDir) {
+    const fullPath = (0, node_path_1.resolve)(configDir, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME);
+    return loadSstDocsConfigSync(fullPath);
+}
+async function readConfigFile(configPath) {
+    const searchPaths = getConfigSearchPaths(configPath);
+    const attempted = [];
+    for (const candidate of searchPaths) {
+        attempted.push(candidate);
+        try {
+            const contents = await (0, promises_1.readFile)(candidate, "utf-8");
+            return { path: candidate, contents };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT" || err.code === "EISDIR") {
+                continue;
+            }
+            throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Failed to read ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME} at ${candidate}: ${err.message}`);
+        }
+    }
+    throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Unable to locate ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME}. Tried: ${attempted.join(", ")}`);
+}
+function readConfigFileSync(configPath) {
+    const searchPaths = getConfigSearchPaths(configPath);
+    const attempted = [];
+    for (const candidate of searchPaths) {
+        attempted.push(candidate);
+        try {
+            const contents = (0, node_fs_1.readFileSync)(candidate, "utf-8");
+            return { path: candidate, contents };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT" || err.code === "EISDIR") {
+                continue;
+            }
+            throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Failed to read ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME} at ${candidate}: ${err.message}`);
+        }
+    }
+    throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Unable to locate ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME}. Tried: ${attempted.join(", ")}`);
+}
+function getConfigSearchPaths(configPath) {
+    const searchPaths = [];
+    if (configPath) {
+        const explicit = (0, node_path_1.resolve)(APP_ROOT, configPath);
+        searchPaths.push(explicit);
+        if (!explicit.endsWith(".json")) {
+            searchPaths.push((0, node_path_1.resolve)(explicit, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME));
+        }
+    }
+    else {
+        searchPaths.push((0, node_path_1.resolve)(APP_ROOT, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME));
+    }
+    return searchPaths;
+}

package/dist/cjs/configs/sstDocsConfigShared.js

@@ -0,0 +1,174 @@
+"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.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");
+exports.SST_DOCS_CONFIG_FILENAME = "sst-docs.config.json";
+class SstDocsConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SstDocsConfigError";
+    }
+}
+exports.SstDocsConfigError = SstDocsConfigError;
+function parseConfigContents(contents, sourcePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new SstDocsConfigError(`Failed to parse ${exports.SST_DOCS_CONFIG_FILENAME}: ${error.message}`);
+    }
+    return normalizeConfig(parsed, sourcePath);
+}
+function derivePublicDataPath(fsDataPath) {
+    const normalizedFsPath = (0, normalizeSystemPath_js_1.normalizeSystemPath)(fsDataPath.trim());
+    const posixPath = node_path_1.default.posix.normalize(normalizedFsPath || "/");
+    const segments = posixPath.split("/").filter(Boolean);
+    const publicIndex = segments.indexOf("public");
+    const publicSegments = publicIndex >= 0 ? segments.slice(publicIndex + 1) : segments;
+    if (publicSegments.length === 0) {
+        return "/";
+    }
+    const joined = `/${publicSegments.join("/")}`;
+    return joined.endsWith("/") ? joined : `${joined}/`;
+}
+function resolvePublicDataPath(baseUrl, config) {
+    const publicPath = typeof config === "string" ? config : config.PUBLIC_DATA_PATH;
+    const normalizedPublicPath = normalizePublicPath(publicPath);
+    if (!baseUrl || baseUrl.trim().length === 0) {
+        return normalizedPublicPath;
+    }
+    if (isAbsoluteUrl(baseUrl)) {
+        const url = new URL(baseUrl);
+        url.pathname = joinUrlPaths(url.pathname || "/", normalizedPublicPath);
+        return url.toString();
+    }
+    const parsedBase = new URL(baseUrl, "http://local.placeholder");
+    const joinedPath = joinUrlPaths(parsedBase.pathname || "/", normalizedPublicPath);
+    return `${joinedPath}${parsedBase.search}${parsedBase.hash}`;
+}
+function normalizePublicPath(value) {
+    const normalized = (0, normalizeSystemPath_js_1.normalizeSystemPath)(value.trim());
+    const posixPath = node_path_1.default.posix.normalize(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);
+    return joined.endsWith("/") ? joined : `${joined}/`;
+}
+function isAbsoluteUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        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 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 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 cloneTheme(theme) {
+    return JSON.parse(JSON.stringify(theme));
+}

package/dist/cjs/constants/alignmentClasses.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALIGNMENT_CLASSES = void 0;
+exports.ALIGNMENT_CLASSES = {
+    left: {
+        text: "text-left",
+        container: "mr-auto",
+    },
+    center: {
+        text: "text-center",
+        container: "mx-auto",
+    },
+    right: {
+        text: "text-right",
+        container: "ml-auto",
+    },
+};

package/dist/cjs/constants/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPACING_CLASSES = exports.ALIGNMENT_CLASSES = void 0;
+var alignmentClasses_js_1 = require("./alignmentClasses.js");
+Object.defineProperty(exports, "ALIGNMENT_CLASSES", { enumerable: true, get: function () { return alignmentClasses_js_1.ALIGNMENT_CLASSES; } });
+var spacingClasses_js_1 = require("./spacingClasses.js");
+Object.defineProperty(exports, "SPACING_CLASSES", { enumerable: true, get: function () { return spacingClasses_js_1.SPACING_CLASSES; } });

package/dist/cjs/constants/spacingClasses.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPACING_CLASSES = void 0;
+exports.SPACING_CLASSES = {
+    none: "",
+    small: "mb-4",
+    medium: "mb-6",
+    large: "mb-8",
+};