@zpress/core 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Joggr
+Copyright (c) 2026 Joggr, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,63 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/joggrdocs/zpress/main/assets/banner.svg" alt="zpress" width="90%" />
+  <p><strong>Config loading, sync engine, and asset utilities for zpress.</strong></p>
+
+<a href="https://github.com/joggrdocs/zpress/actions/workflows/ci.yml"><img src="https://github.com/joggrdocs/zpress/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+<a href="https://www.npmjs.com/package/@zpress/core"><img src="https://img.shields.io/npm/v/@zpress/core" alt="npm version" /></a>
+<a href="https://github.com/joggrdocs/zpress/blob/main/LICENSE"><img src="https://img.shields.io/github/license/joggrdocs/zpress" alt="License" /></a>
+
+</div>
+
+## Install
+
+```bash
+npm install @zpress/core
+```
+
+## API
+
+### Config
+
+| Export         | Description                         |
+| -------------- | ----------------------------------- |
+| `defineConfig` | Type-safe config factory            |
+| `loadConfig`   | Load and validate `zpress.config.*` |
+
+### Sync Engine
+
+| Export           | Description                           |
+| ---------------- | ------------------------------------- |
+| `sync`           | Run the full sync pipeline            |
+| `resolveEntries` | Resolve glob patterns to page entries |
+| `loadManifest`   | Load a previously written manifest    |
+
+### Assets
+
+| Export              | Description              |
+| ------------------- | ------------------------ |
+| `generateAssets`    | Generate all asset files |
+| `generateBannerSvg` | Generate banner SVG      |
+| `generateIconSvg`   | Generate icon SVG        |
+| `generateLogoSvg`   | Generate logo SVG        |
+
+### Utilities
+
+| Export         | Description                 |
+| -------------- | --------------------------- |
+| `createPaths`  | Build resolved path helpers |
+| `hasGlobChars` | Check if a string has globs |
+
+## Usage
+
+```ts
+import { defineConfig, loadConfig, sync } from '@zpress/core'
+
+const config = defineConfig({
+  title: 'my-project',
+  sections: [{ text: 'Guide', from: 'docs/*.md' }],
+})
+```
+
+## License
+
+[MIT](https://github.com/joggrdocs/zpress/blob/main/LICENSE) - Joggr, Inc.

package/dist/index.d.ts

@@ -0,0 +1,967 @@
+/**
+ * Input configuration for asset generation, extracted from ZpressConfig.
+ */
+export declare interface AssetConfig {
+    readonly title: string;
+    readonly tagline: string | undefined;
+}
+
+/**
+ * Error produced during asset generation or file writing.
+ */
+export declare interface AssetError {
+    readonly _tag: 'AssetError';
+    readonly type: 'empty_title' | 'write_failed';
+    readonly message: string;
+}
+
+/**
+ * Convenience alias for asset operation results.
+ */
+export declare type AssetResult<T> = Result<T, AssetError>;
+
+/**
+ * Controls how an entry appears as a card on its parent section's
+ * auto-generated landing page.
+ *
+ * When present, the landing page uses workspace-style cards
+ * (icon + scope + name + description + tags + optional badge).
+ *
+ * @example
+ * ```ts
+ * card: {
+ *   icon: 'devicon:hono',
+ *   iconColor: 'api',
+ *   scope: 'apps/',
+ *   description: 'Hono REST API with RPC-typed routes',
+ *   tags: ['Hono', 'REST', 'Serverless'],
+ *   badge: { src: '/logos/vercel.svg', alt: 'Vercel' },
+ * }
+ * ```
+ */
+export declare interface CardConfig {
+    /**
+     * Iconify identifier for the card icon (e.g. 'devicon:hono').
+     */
+    icon?: string;
+    /**
+     * CSS class suffix for the icon color (maps to `.workspace-icon--{color}`).
+     */
+    iconColor?: string;
+    /**
+     * Scope label shown above the name (e.g. `"apps/"`).
+     */
+    scope?: string;
+    /**
+     * Short description shown on the card. Overrides auto-extracted description.
+     */
+    description?: string;
+    /**
+     * Technology tags shown at the bottom of the card.
+     */
+    tags?: string[];
+    /**
+     * Deploy badge image shown in the card header.
+     */
+    badge?: {
+        src: string;
+        alt: string;
+    };
+}
+
+/**
+ * Error produced during config validation in `defineConfig`.
+ */
+export declare interface ConfigError {
+    readonly _tag: 'ConfigError';
+    readonly type: 'empty_sections' | 'missing_field' | 'duplicate_prefix' | 'invalid_icon' | 'invalid_entry';
+    readonly message: string;
+}
+
+/**
+ * Create a `ConfigError` value.
+ *
+ * @param type - Error classification
+ * @param message - Human-readable description
+ * @returns A frozen `ConfigError` object
+ */
+export declare function configError(type: ConfigError['type'], message: string): ConfigError;
+
+/**
+ * Convenience alias for config validation results.
+ */
+export declare type ConfigResult<T> = readonly [ConfigError, null] | readonly [null, T];
+
+/**
+ * Create all derived project paths from a resolved directory.
+ */
+export declare function createPaths(dir: string): Paths;
+
+/**
+ * Type-safe config helper with validation.
+ *
+ * Validates the config structure and exits with a clear error message
+ * if any issues are found. This is the primary entry point for user-
+ * provided config — validation happens at the boundary.
+ *
+ * `defineConfig` is called in user config files (e.g. `zpress.config.ts`)
+ * where the return value is consumed by the c12 config loader, which
+ * expects a plain `ZpressConfig` object — not a `Result` tuple.
+ * Because this is the outermost user-facing boundary (not a library
+ * function), `process.exit(1)` is acceptable here: the user must fix
+ * their config before any downstream code can run.
+ *
+ * @param config - Raw zpress config object
+ * @returns The validated config (unchanged)
+ */
+export declare function defineConfig(config: ZpressConfig): ZpressConfig;
+
+/**
+ * A single node in the information architecture.
+ *
+ * What you provide determines what it is:
+ *
+ * **Page — explicit file**
+ * ```ts
+ * { text: 'Architecture', link: '/architecture', from: 'docs/architecture.md' }
+ * ```
+ *
+ * **Page — inline/generated content**
+ * ```ts
+ * { text: 'Overview', link: '/api/overview', content: '# API Overview\n...' }
+ * ```
+ *
+ * **Section — explicit children**
+ * ```ts
+ * { text: 'Guides', items: [ ... ] }
+ * ```
+ *
+ * **Section — auto-discovered from glob**
+ * ```ts
+ * { text: 'Guides', prefix: '/guides', from: 'docs/guides/*.md' }
+ * ```
+ *
+ * **Section — mix of explicit + auto-discovered**
+ * ```ts
+ * {
+ *   text: 'Guides',
+ *   prefix: '/guides',
+ *   from: 'docs/guides/*.md',
+ *   items: [
+ *     { text: 'Getting Started', link: '/guides/start', from: 'docs/intro.md' },
+ *   ],
+ * }
+ * ```
+ */
+export declare interface Entry {
+    /**
+     * Display text in sidebar and nav.
+     */
+    readonly text: string;
+    /**
+     * Output URL path.
+     * - Pages: exact URL (e.g. `"/guides/add-api-route"`)
+     * - Sections: optional — makes the section header clickable
+     */
+    readonly link?: UrlPath;
+    /**
+     * Content source — file path or glob, relative to repo root.
+     *
+     * - **No wildcards** → single file (e.g. `"docs/architecture.md"`)
+     * - **With wildcards** → auto-discover children (e.g. `"docs/guides/*.md"`)
+     */
+    readonly from?: FilePath | GlobPattern;
+    /**
+     * URL prefix for auto-discovered children.
+     * Used with glob `from` — each discovered file gets `prefix + "/" + slug`.
+     *
+     * @example
+     * `prefix: "/guides"` + file `add-api-route.md` → `/guides/add-api-route`
+     */
+    readonly prefix?: UrlPath;
+    /**
+     * Inline markdown or async content generator.
+     * For virtual pages that have no source `.md` file.
+     * Mutually exclusive with `from`.
+     */
+    readonly content?: string | (() => string | Promise<string>);
+    /**
+     * Child entries — pages and/or sub-sections.
+     */
+    readonly items?: readonly Entry[];
+    /**
+     * Make this section collapsible in the sidebar.
+     * Sections at depth > 1 are collapsible by default.
+     * Set to `false` to keep a deep section always-open.
+     */
+    readonly collapsible?: boolean;
+    /**
+     * Exclude globs, scoped to this entry's `from` glob.
+     */
+    readonly exclude?: readonly GlobPattern[];
+    /**
+     * Hide from sidebar. Page is still built and routable.
+     * Useful for pages that should exist but not clutter navigation.
+     */
+    readonly hidden?: boolean;
+    /**
+     * Frontmatter injected at build time.
+     * - On a page: applied to that page.
+     * - On a section: applied to all pages within.
+     */
+    readonly frontmatter?: Frontmatter;
+    /**
+     * How to derive `text` for auto-discovered children.
+     * - `"filename"` — kebab-to-title from filename (default)
+     * - `"heading"` — first `# heading` in the file
+     * - `"frontmatter"` — `title` field from YAML frontmatter, falls back to heading
+     */
+    readonly textFrom?: 'filename' | 'heading' | 'frontmatter';
+    /**
+     * Transform function applied to auto-derived text (from `textFrom`).
+     * Called after text derivation for glob-discovered and recursive children.
+     * Does NOT apply to entries with explicit `text` (those are already user-controlled).
+     *
+     * @param text - The derived text (from heading or filename)
+     * @param slug - The filename slug (without extension)
+     * @returns Transformed text for sidebar display
+     */
+    readonly textTransform?: (text: string, slug: string) => string;
+    /**
+     * Sort order for auto-discovered children.
+     * - `"alpha"` — alphabetical by derived text (default)
+     * - `"filename"` — alphabetical by filename
+     * - Custom comparator function
+     */
+    readonly sort?: 'alpha' | 'filename' | ((a: ResolvedPage, b: ResolvedPage) => number);
+    /**
+     * Enable recursive directory-based nesting for glob patterns.
+     * When true, directory structure under the glob base drives sidebar nesting:
+     * - The `indexFile` (default `"overview"`) in a directory becomes the section header page
+     * - Other `.md` files become children
+     * - Sub-directories become nested collapsible sections
+     *
+     * Requires `from` with a recursive glob (e.g. `"docs/**\/*.md"`) and `prefix`.
+     * @default false
+     */
+    readonly recursive?: boolean;
+    /**
+     * Filename (without extension) used as the section header page in each directory.
+     * Only meaningful when `recursive` is true.
+     * @default "overview"
+     */
+    readonly indexFile?: string;
+    /**
+     * Card display metadata for the parent section's auto-generated landing page.
+     *
+     * When present on child entries, the parent's landing page uses
+     * workspace-style cards instead of the default simple cards.
+     */
+    readonly card?: CardConfig;
+    /**
+     * Isolate this section into its own Rspress sidebar namespace.
+     *
+     * When `true`, the section's children appear under a dedicated sidebar
+     * keyed by `link` (e.g. `"/apps/"`) instead of the root `"/"` sidebar.
+     * This mirrors how the OpenAPI reference already works.
+     *
+     * Requires `link` to be set.
+     * @default false
+     */
+    readonly isolated?: boolean;
+}
+
+/**
+ * Explicit feature card for the home page.
+ *
+ * When `features` is provided on the config, these replace the
+ * auto-generated feature cards that are normally derived from
+ * top-level sections.
+ *
+ * @example
+ * ```ts
+ * {
+ *   text: 'Getting Started',
+ *   description: 'Everything you need to set up and start building.',
+ *   link: '/getting-started',
+ *   icon: 'pixelarticons:speed-fast',
+ * }
+ * ```
+ */
+export declare interface Feature {
+    /**
+     * Display title for the feature card.
+     */
+    readonly text: string;
+    /**
+     * Short description shown below the title.
+     */
+    readonly description: string;
+    /**
+     * Link target when the card is clicked.
+     */
+    readonly link?: string;
+    /**
+     * Iconify icon identifier (e.g. `"pixelarticons:speed-fast"`).
+     */
+    readonly icon?: string;
+}
+
+/**
+ * Relative file path from repo root (e.g. `"docs/guides/add-api-route.md"`)
+ */
+declare type FilePath = string;
+
+/**
+ * Rspress frontmatter fields injectable at build time.
+ */
+export declare interface Frontmatter {
+    readonly title?: string;
+    readonly titleTemplate?: string | boolean;
+    readonly description?: string;
+    readonly layout?: 'doc' | 'page' | 'home' | (string & {});
+    readonly sidebar?: boolean;
+    readonly aside?: boolean | 'left';
+    readonly outline?: false | number | [number, number] | 'deep';
+    readonly navbar?: boolean;
+    readonly editLink?: boolean;
+    readonly lastUpdated?: boolean;
+    readonly footer?: boolean;
+    readonly pageClass?: string;
+    readonly head?: readonly [string, Record<string, string>][];
+    /**
+     * Arbitrary extra fields merged into frontmatter.
+     */
+    readonly [key: string]: unknown;
+}
+
+/**
+ * Generate banner, logo, and icon SVGs, writing them to the public directory.
+ *
+ * For each asset:
+ * 1. If the file is missing or has the zpress-generated marker → write it
+ * 2. If the file exists without the marker → skip (user-customized)
+ *
+ * @param params - Config and target directory
+ * @returns Result containing the list of filenames written, or an error
+ */
+export declare function generateAssets(params: GenerateAssetsParams): Promise<AssetResult<readonly string[]>>;
+
+declare interface GenerateAssetsParams {
+    readonly config: AssetConfig;
+    readonly publicDir: string;
+}
+
+/**
+ * Generate a banner SVG from the project config.
+ *
+ * @param config - Title and optional tagline
+ * @returns Result containing the generated asset or an error
+ */
+export declare function generateBannerSvg(config: AssetConfig): AssetResult<GeneratedAsset>;
+
+/**
+ * A generated SVG asset ready to be written to disk.
+ */
+export declare interface GeneratedAsset {
+    readonly filename: string;
+    readonly content: string;
+}
+
+/**
+ * Generate an icon (favicon) SVG from the project config.
+ *
+ * @param config - Title (first character is used for the icon glyph)
+ * @returns Result containing the generated asset or an error
+ */
+export declare function generateIconSvg(config: AssetConfig): AssetResult<GeneratedAsset>;
+
+/**
+ * Generate a logo SVG from the project config.
+ *
+ * @param config - Title (tagline is ignored for logos)
+ * @returns Result containing the generated asset or an error
+ */
+export declare function generateLogoSvg(config: AssetConfig): AssetResult<GeneratedAsset>;
+
+/**
+ * Glob pattern (e.g. `"docs/guides/*.md"`)
+ */
+declare type GlobPattern = string;
+
+/**
+ * Returns true if the string contains glob metacharacters.
+ */
+export declare function hasGlobChars(s: string): boolean;
+
+/**
+ * Load zpress config at runtime via c12.
+ *
+ * Returns a `ConfigResult` tuple instead of calling `process.exit` — the
+ * CLI boundary is responsible for surfacing the error and exiting.
+ */
+export declare function loadConfig(dir: string): Promise<ConfigResult<ZpressConfig>>;
+
+/**
+ * Load the previous sync manifest from disk.
+ *
+ * @param outDir - Absolute path to the output directory
+ * @returns Parsed manifest, or `null` if no manifest exists
+ */
+export declare function loadManifest(outDir: string): Promise<Manifest | null>;
+
+/**
+ * Tracks output files for incremental sync and stale file cleanup.
+ */
+export declare interface Manifest {
+    /**
+     * Map of output relative path to entry metadata.
+     *
+     * @remarks Mutable — entries are accumulated during the sync pass as pages
+     * are copied. The manifest is built incrementally and then persisted to disk.
+     * Will be refactored to an immutable accumulator pattern alongside `SyncContext.manifest`.
+     */
+    files: Record<string, ManifestEntry>;
+    /**
+     * Timestamp of last sync.
+     */
+    readonly timestamp: number;
+}
+
+/**
+ * Metadata for a single output file tracked in the manifest.
+ */
+export declare interface ManifestEntry {
+    /**
+     * Repo-relative path to source file (undefined for virtual pages).
+     */
+    readonly source?: string;
+    /**
+     * Source file mtime in ms (for quick-check).
+     */
+    readonly sourceMtime?: number;
+    /**
+     * SHA-256 hex of the written output.
+     */
+    readonly contentHash: string;
+    /**
+     * Output path relative to .content/.
+     */
+    readonly outputPath: string;
+}
+
+export declare interface NavItem {
+    readonly text: string;
+    readonly link?: UrlPath;
+    readonly items?: readonly NavItem[];
+    readonly activeMatch?: string;
+}
+
+/**
+ * Configuration for OpenAPI spec integration.
+ */
+export declare interface OpenAPIConfig {
+    /**
+     * Path to openapi.json relative to repo root.
+     */
+    spec: FilePath;
+    /**
+     * URL prefix for API operation pages (e.g., '/api').
+     */
+    prefix: UrlPath;
+    /**
+     * Sidebar group title.
+     * @default 'API Reference'
+     */
+    title?: string;
+}
+
+/**
+ * Data for a single page to be written to the output directory.
+ */
+export declare interface PageData {
+    /**
+     * Absolute path to source .md (undefined for virtual pages).
+     */
+    readonly source?: string;
+    /**
+     * Inline content for virtual pages.
+     */
+    readonly content?: string | (() => string | Promise<string>);
+    /**
+     * Relative path inside .content/ (e.g. "guides/add-api-route.md").
+     */
+    readonly outputPath: string;
+    /**
+     * Merged frontmatter to inject.
+     */
+    readonly frontmatter: Frontmatter;
+}
+
+/**
+ * All user-project paths derived from a single root directory.
+ */
+export declare interface Paths {
+    readonly repoRoot: string;
+    readonly outputRoot: string;
+    readonly contentDir: string;
+    readonly publicDir: string;
+    readonly distDir: string;
+    readonly cacheDir: string;
+}
+
+/**
+ * Internal resolved node — produced by the resolver, consumed by copy + sidebar/nav generators.
+ */
+export declare interface ResolvedEntry {
+    readonly text: string;
+    readonly link?: string;
+    readonly collapsible?: boolean;
+    readonly hidden?: boolean;
+    /**
+     * @remarks Mutable — `injectLandingPages` may reassign items when
+     * promoting an overview child to section page. Will be refactored
+     * to immutable tree rebuild.
+     */
+    items?: readonly ResolvedEntry[];
+    /**
+     * Present on leaf pages (and section headers that are also pages).
+     *
+     * @remarks Mutable — `injectLandingPages` assigns virtual pages to sections
+     * that have a link but no page. Will be refactored to immutable tree rebuild
+     * when landing pages move to Vue components.
+     */
+    page?: PageData;
+    readonly card?: CardConfig;
+    /**
+     * When true, this section gets its own sidebar namespace keyed by `link`.
+     */
+    readonly isolated?: boolean;
+}
+
+/**
+ * A fully resolved page after the sync engine processes the config.
+ */
+export declare interface ResolvedPage {
+    /**
+     * Display text.
+     */
+    readonly text: string;
+    /**
+     * Output URL path.
+     */
+    readonly link: UrlPath;
+    /**
+     * Source file path (undefined for virtual pages).
+     */
+    readonly source?: FilePath;
+    /**
+     * Merged frontmatter.
+     */
+    readonly frontmatter: Frontmatter;
+}
+
+/**
+ * A fully resolved section.
+ */
+export declare interface ResolvedSection {
+    readonly text: string;
+    readonly link?: UrlPath;
+    readonly collapsible?: boolean;
+    readonly items: readonly (ResolvedPage | ResolvedSection)[];
+}
+
+/**
+ * Walk the Entry tree and produce a ResolvedEntry tree.
+ *
+ * Resolves globs, derives text, merges frontmatter, deduplicates.
+ * Returns a `SyncOutcome` tuple — the caller is responsible for
+ * surfacing errors and exiting.
+ *
+ * @param entries - Config entry tree to resolve
+ * @param ctx - Sync context (provides repo root, config, quiet flag)
+ * @param inheritedFrontmatter - Frontmatter inherited from parent entries
+ * @param depth - Current nesting depth (0 = top-level)
+ * @returns Result tuple containing resolved entry tree or the first sync error
+ */
+export declare function resolveEntries(entries: readonly Entry[], ctx: SyncContext, inheritedFrontmatter?: Frontmatter, depth?: number): Promise<readonly [SyncError, null] | readonly [null, ResolvedEntry[]]>;
+
+/**
+ * zpress — unified information architecture config.
+ *
+ * The IA tree IS the config. Each node defines what it is, where its
+ * content comes from, and where it sits in the sidebar — all in one place.
+ * Source `.md` files are never edited.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@zpress/core'
+ *
+ * export default defineConfig({
+ *   title: 'My Docs',
+ *   sections: [
+ *     {
+ *       text: 'Introduction',
+ *       items: [
+ *         { text: 'Architecture', link: '/architecture', from: 'docs/architecture.md' },
+ *         { text: 'Structure', link: '/structure', from: 'docs/structure.md' },
+ *       ],
+ *     },
+ *     {
+ *       text: 'Guides',
+ *       prefix: '/guides',
+ *       from: 'docs/guides/*.md',
+ *     },
+ *     {
+ *       text: 'API Reference',
+ *       items: [
+ *         { text: 'Overview', link: '/api/overview', content: '# API\n...' },
+ *         { text: 'Routes', link: '/api/routes', from: 'apps/api/docs/routes.md' },
+ *       ],
+ *     },
+ *   ],
+ * })
+ * ```
+ */
+/**
+ * Result type for error handling without exceptions.
+ *
+ * Success: `[null, value]`
+ * Failure: `[error, null]`
+ *
+ * @example
+ * ```ts
+ * const [error, value] = loadConfig(path)
+ * if (error) return [error, null]
+ * ```
+ */
+export declare type Result<T, E = Error> = readonly [E, null] | readonly [null, T];
+
+/**
+ * Rspress sidebar item shape.
+ *
+ * Constructed immutably by sidebar generators, then serialized to JSON.
+ */
+export declare interface SidebarItem {
+    readonly text: string;
+    readonly link?: string;
+    /**
+     * Rspress `collapsed` — set by sidebar generator from `collapsible`.
+     */
+    readonly collapsed?: boolean;
+    readonly items?: readonly SidebarItem[];
+}
+
+/**
+ * Mapping from repo-relative source path to content-relative output path.
+ */
+declare type SourceMap = ReadonlyMap<string, string>;
+
+export declare function sync(config: ZpressConfig, options: SyncOptions): Promise<SyncResult>;
+
+/**
+ * Context threaded through all sync operations.
+ */
+export declare interface SyncContext {
+    /**
+     * Absolute path to repo root.
+     */
+    readonly repoRoot: string;
+    /**
+     * Absolute path to .content/ output directory.
+     */
+    readonly outDir: string;
+    /**
+     * Resolved config.
+     */
+    readonly config: ZpressConfig;
+    /**
+     * Previous manifest (for incremental sync).
+     */
+    readonly previousManifest: Manifest | null;
+    /**
+     * Current manifest being built.
+     *
+     * @remarks Mutable during the sync pass — entries are added as pages are copied.
+     * Will be refactored to an immutable accumulator pattern in a future pass.
+     */
+    manifest: Manifest;
+    /**
+     * When true, suppress all log output during sync.
+     */
+    readonly quiet: boolean;
+    /**
+     * Mapping from repo-relative source paths to content-relative output paths.
+     * Used by the copy step to rewrite relative markdown links.
+     */
+    readonly sourceMap?: SourceMap;
+}
+
+/**
+ * Domain-specific error types for the sync engine.
+ *
+ * All sync operations return `Result<T, SyncError>` instead of throwing.
+ * Config validation returns `Result<T, ConfigError>`.
+ */
+/**
+ * Error produced by the sync engine during entry resolution, page copy, or sidebar generation.
+ */
+export declare interface SyncError {
+    readonly _tag: 'SyncError';
+    readonly type: 'missing_from' | 'missing_link' | 'file_not_found' | 'missing_content' | 'internal';
+    readonly message: string;
+}
+
+/**
+ * Create a `SyncError` value.
+ *
+ * @param type - Error classification
+ * @param message - Human-readable description
+ * @returns A frozen `SyncError` object
+ */
+export declare function syncError(type: SyncError['type'], message: string): SyncError;
+
+export declare interface SyncOptions {
+    /**
+     * Resolved project paths.
+     */
+    readonly paths: Paths;
+    /**
+     * When true, suppress all log output during sync.
+     */
+    readonly quiet?: boolean;
+}
+
+/**
+ * Convenience alias for sync operation results.
+ *
+ * Named `SyncOutcome` to avoid collision with the `SyncResult` interface
+ * in `sync/index.ts` (which represents the aggregate return value of a full sync pass).
+ */
+export declare type SyncOutcome<T> = readonly [SyncError, null] | readonly [null, T];
+
+export declare interface SyncResult {
+    readonly pagesWritten: number;
+    readonly pagesSkipped: number;
+    readonly pagesRemoved: number;
+    readonly elapsed: number;
+}
+
+/**
+ * URL path (e.g. `"/guides/add-api-route"`)
+ */
+declare type UrlPath = string;
+
+/**
+ * A named group of workspace items for custom workspace categories.
+ *
+ * Lets users define arbitrary groups beyond the built-in `apps` and `packages`
+ * (e.g. "Services", "Tools", "Integrations") that receive the same
+ * card/landing-page treatment.
+ *
+ * @example
+ * ```ts
+ * {
+ *   name: 'Integrations',
+ *   description: 'Third-party service connectors',
+ *   icon: 'pixelarticons:integration',
+ *   items: [
+ *     { text: 'Stripe', description: 'Payment processing', docsPrefix: '/integrations/stripe' },
+ *   ],
+ * }
+ * ```
+ */
+export declare interface WorkspaceGroup {
+    readonly name: string;
+    readonly description: string;
+    readonly icon: string;
+    readonly items: readonly WorkspaceItem[];
+    /**
+     * URL prefix override for the group's landing page.
+     * Defaults to `/${slugify(name)}` when omitted.
+     */
+    readonly link?: string;
+}
+
+/**
+ * A workspace item representing an app or package in the monorepo.
+ *
+ * Used as the single source of truth for workspace metadata — home page cards,
+ * landing page cards, and introduction bullets all derive from these arrays.
+ *
+ * @example
+ * ```ts
+ * {
+ *   text: 'API',
+ *   icon: 'devicon:hono',
+ *   iconColor: 'api',
+ *   description: 'Hono REST API serving all client applications with RPC-typed routes',
+ *   tags: ['hono', 'react', 'vercel'],
+ *   badge: { src: '/logos/vercel.svg', alt: 'Vercel' },
+ *   docsPrefix: '/apps/api',
+ * }
+ * ```
+ */
+export declare interface WorkspaceItem {
+    /**
+     * Display name (e.g. "API", "Console", "AI").
+     */
+    readonly text: string;
+    /**
+     * Main icon — Iconify identifier (e.g. "devicon:hono").
+     * Falls back to a default app or package icon when omitted.
+     */
+    readonly icon?: string;
+    /**
+     * CSS class suffix for icon color (maps to `.workspace-icon--{color}`).
+     */
+    readonly iconColor?: string;
+    /**
+     * Short description for cards and bullet lists.
+     */
+    readonly description: string;
+    /**
+     * Technology tags — kebab-case keys resolved by the UI TechTag component.
+     * Each tag maps to an Iconify icon and display label.
+     */
+    readonly tags?: readonly string[];
+    /**
+     * Deploy badge image for the card header.
+     */
+    readonly badge?: {
+        readonly src: string;
+        readonly alt: string;
+    };
+    /**
+     * Docs path prefix (e.g. "/apps/api"). Matches section entries and derives card links.
+     * Also used as the URL prefix for glob-discovered children.
+     */
+    readonly docsPrefix: string;
+    /**
+     * Content source — file path or glob, **relative to the workspace item's
+     * base path** (derived from `docsPrefix`).
+     *
+     * - `docsPrefix: "/apps/api"` + `from: "docs/*.md"` → resolves to `apps/api/docs/*.md`
+     * - **No wildcards** → single file (e.g. `"docs/overview.md"`)
+     * - **With wildcards** → auto-discover children (e.g. `"docs/*.md"`)
+     *
+     * @default "docs/*.md"
+     */
+    readonly from?: string;
+    /**
+     * Explicit child entries for this workspace item.
+     * Can be combined with `from` — explicit children override glob-discovered pages.
+     */
+    readonly items?: readonly Entry[];
+    /**
+     * Sort order for auto-discovered children.
+     * - `"alpha"` — alphabetical by derived text (default)
+     * - `"filename"` — alphabetical by filename
+     * - Custom comparator function
+     */
+    readonly sort?: Entry['sort'];
+    /**
+     * How to derive `text` for auto-discovered children.
+     * - `"filename"` — kebab-to-title from filename (default)
+     * - `"heading"` — first `# heading` in the file
+     * - `"frontmatter"` — `title` field from YAML frontmatter, falls back to heading
+     */
+    readonly textFrom?: Entry['textFrom'];
+    /**
+     * Transform function applied to auto-derived text (from `textFrom`).
+     */
+    readonly textTransform?: Entry['textTransform'];
+    /**
+     * Enable recursive directory-based nesting for glob patterns.
+     * Requires `from` with a recursive glob (e.g. `"apps/api/docs/**\/*.md"`).
+     * @default false
+     */
+    readonly recursive?: boolean;
+    /**
+     * Filename (without extension) used as the section header page in each directory.
+     * Only meaningful when `recursive` is true.
+     * @default "overview"
+     */
+    readonly indexFile?: string;
+    /**
+     * Exclude globs, scoped to this item's `from` glob.
+     */
+    readonly exclude?: readonly string[];
+    /**
+     * Make this item's section collapsible in the sidebar.
+     */
+    readonly collapsible?: boolean;
+    /**
+     * Frontmatter injected at build time for all pages under this workspace item.
+     */
+    readonly frontmatter?: Frontmatter;
+}
+
+export declare interface ZpressConfig {
+    /**
+     * Site title.
+     */
+    readonly title?: string;
+    /**
+     * Site meta description. Used as the hero headline on the home page.
+     */
+    readonly description?: string;
+    /**
+     * Path to a custom favicon file served from `.zpress/public/`.
+     * When omitted, defaults to the auto-generated `/icon.svg`.
+     */
+    readonly icon?: string;
+    /**
+     * Hero tagline displayed below the headline on the home page.
+     * When omitted, the tagline is not rendered.
+     */
+    readonly tagline?: string;
+    /**
+     * Workspace apps — deployable services that make up the platform.
+     * Single source of truth for app metadata used on the home page,
+     * landing pages, and introduction page.
+     */
+    readonly apps?: readonly WorkspaceItem[];
+    /**
+     * Workspace packages — shared libraries consumed by apps.
+     * Single source of truth for package metadata used on the home page,
+     * landing pages, and introduction page.
+     */
+    readonly packages?: readonly WorkspaceItem[];
+    /**
+     * Custom workspace groups — arbitrary named groups of workspace items.
+     * Each group receives the same card/landing-page treatment as apps and packages.
+     * Rendered after apps and packages, in array order.
+     */
+    readonly workspaces?: readonly WorkspaceGroup[];
+    /**
+     * Explicit feature cards for the home page.
+     *
+     * When provided, these replace the auto-generated feature cards
+     * that are normally derived from top-level sections.
+     * When omitted, features are auto-generated from sections with icons.
+     */
+    readonly features?: readonly Feature[];
+    /**
+     * The information architecture.
+     * Defines content sources, sidebar structure, and routing in a single tree.
+     */
+    readonly sections: readonly Entry[];
+    /**
+     * Top navigation bar.
+     * - `"auto"` — one nav item per top-level section
+     * - Array — explicit nav items
+     * @default "auto"
+     */
+    readonly nav?: 'auto' | readonly NavItem[];
+    /**
+     * Globs to exclude globally across all sources.
+     */
+    readonly exclude?: readonly GlobPattern[];
+    /**
+     * OpenAPI spec integration for interactive API docs.
+     */
+    readonly openapi?: OpenAPIConfig;
+}
+
+export { }

package/dist/index.mjs

@@ -90,11 +90,6 @@ function validateConfig(config) {
         featErr,
         null
     ];
-    const [navErr] = validateNav(config.nav);
-    if (navErr) return [
-        navErr,
-        null
-    ];
     return [
         null,
         config
@@ -227,29 +222,6 @@ function validateFeature(feature) {
     if (feature.icon && !feature.icon.includes(':')) return configError('invalid_icon', `Feature "${feature.text}": icon must be an Iconify identifier (e.g. "pixelarticons:speed-fast")`);
     return null;
 }
-function validateNav(nav) {
-    if ('auto' === nav || void 0 === nav) return [
-        null,
-        true
-    ];
-    const navError = nav.reduce((acc, item)=>{
-        if (acc) return acc;
-        return validateNavItem(item);
-    }, null);
-    if (navError) return [
-        navError,
-        null
-    ];
-    return [
-        null,
-        true
-    ];
-}
-function validateNavItem(item) {
-    if (!item.icon) return configError('missing_nav_icon', `NavItem "${item.text}": top-level nav items require an "icon" (Iconify identifier)`);
-    if (!item.icon.includes(':')) return configError('invalid_icon', `NavItem "${item.text}": icon must be an Iconify identifier (e.g. "pixelarticons:folder")`);
-    return null;
-}
 async function config_loadConfig(dir) {
     const { config } = await loadConfig({
         cwd: dir,
@@ -1457,7 +1429,7 @@ function buildFeatures(sections, repoRoot) {
     return Promise.all(sections.slice(0, 3).map(async (section, index)=>{
         const link = section.link ?? findFirstChildLink(section);
         const details = await extractSectionDescription(section, repoRoot);
-        const iconId = match(section.icon).with(P.nonNullable, (id)=>id).otherwise(()=>null);
+        const iconId = null;
         const iconColor = ICON_COLORS[index % ICON_COLORS.length];
         return {
             title: section.text,
@@ -2168,13 +2140,12 @@ function deduplicateByLink(entries) {
     });
     return result;
 }
-function buildSidebarEntry(entry, icon) {
+function buildSidebarEntry(entry) {
     if (entry.items && entry.items.length > 0) return {
         text: entry.text,
         items: generateSidebar(entry.items),
         ...maybeCollapsed(entry.collapsible),
-        ...maybeLink(entry.link),
-        ...maybeIcon(icon)
+        ...maybeLink(entry.link)
     };
     if (null === entry.link || void 0 === entry.link) {
         log.error(`[zpress] Leaf entry "${entry.text}" has no link — skipping`);
@@ -2184,33 +2155,28 @@ function buildSidebarEntry(entry, icon) {
     }
     return {
         text: entry.text,
-        link: entry.link,
-        ...maybeIcon(icon)
+        link: entry.link
     };
 }
-function generateSidebar(entries, icons) {
+function generateSidebar(entries) {
     const visible = entries.filter((e)=>!e.hidden);
     const pages = visible.filter((e)=>!e.items || 0 === e.items.length);
     const sections = visible.filter((e)=>e.items && e.items.length > 0);
     return [
         ...pages,
         ...sections
-    ].map((entry)=>{
-        const icon = resolveIcon(icons, entry.text);
-        return buildSidebarEntry(entry, icon);
-    });
+    ].map(buildSidebarEntry);
 }
-function buildNavEntry(entry, icon) {
+function buildNavEntry(entry) {
     const link = sidebar_resolveLink(entry);
     const children = resolveChildren(entry);
     return {
         text: entry.text,
         link,
-        ...maybeIcon(icon),
         ...maybeChildren(children)
     };
 }
-function generateNav(config, resolved, icons) {
+function generateNav(config, resolved) {
     if ('auto' !== config.nav && void 0 !== config.nav) return [
         ...config.nav
     ];
@@ -2220,7 +2186,7 @@ function generateNav(config, resolved, icons) {
     return [
         ...nonIsolated,
         ...isolated
-    ].map((entry)=>buildNavEntry(entry, icons.get(entry.text))).filter((item)=>void 0 !== item.link);
+    ].map(buildNavEntry).filter((item)=>void 0 !== item.link);
 }
 function sidebar_findFirstLink(entry) {
     if (entry.link) return entry.link;
@@ -2241,15 +2207,6 @@ function maybeLink(link) {
     };
     return {};
 }
-function maybeIcon(icon) {
-    if (icon) return {
-        icon
-    };
-    return {};
-}
-function resolveIcon(icons, text) {
-    if (icons) return icons.get(text);
-}
 function sidebar_resolveLink(entry) {
     if (entry.link) return entry.link;
     return sidebar_findFirstLink(entry);
@@ -2379,10 +2336,10 @@ function resolveTags(tags) {
         ...tags
     ];
 }
-function buildMultiSidebar(resolved, openapiSidebar, icons) {
+function buildMultiSidebar(resolved, openapiSidebar) {
     const rootEntries = resolved.filter((e)=>!e.isolated);
     const isolatedEntries = resolved.filter((e)=>e.isolated && e.link);
-    const docsSidebar = generateSidebar(rootEntries, icons);
+    const docsSidebar = generateSidebar(rootEntries);
     const childrenByLink = new Map(isolatedEntries.map((entry)=>{
         const link = entry.link;
         const items = resolveEntryItems(entry.items);
@@ -2394,23 +2351,19 @@ function buildMultiSidebar(resolved, openapiSidebar, icons) {
     const isolatedSidebar = Object.fromEntries(isolatedEntries.flatMap((entry)=>{
         const entryLink = entry.link;
         const children = resolveChildrenByLink(childrenByLink, entryLink);
-        const icon = icons.get(entry.text);
         const parentLink = resolveParentLink(entryLink);
         const parentEntry = match(parentLink).with(P.nonNullable, (pl)=>isolatedEntries.find((e)=>e.link === pl)).otherwise(()=>{});
         const isChild = null != parentEntry && parentEntry !== entry;
         const landing = {
             text: entry.text,
-            link: entryLink,
-            ...multi_maybeIcon(icon)
+            link: entryLink
         };
         const sidebarItems = match(isChild).with(true, ()=>{
             const pe = parentEntry;
             const peLink = pe.link;
-            const parentIcon = icons.get(pe.text);
             const parentLanding = {
                 text: pe.text,
-                link: peLink,
-                ...multi_maybeIcon(parentIcon)
+                link: peLink
             };
             const siblings = isolatedEntries.filter((sib)=>{
                 const sibLink = sib.link;
@@ -2480,12 +2433,6 @@ function resolveParentLink(entryLink) {
     if (segments) return segments;
     return null;
 }
-function multi_maybeIcon(icon) {
-    if (icon) return {
-        icon
-    };
-    return {};
-}
 function buildSidebarGroup(text, link, children, collapsed) {
     if (children.length > 0) return {
         text,
@@ -2522,7 +2469,6 @@ function synthesizeWorkspaceSections(config) {
             text: 'Apps',
             link: '/apps',
             isolated: true,
-            icon: 'pixelarticons:device-laptop',
             frontmatter: {
                 description: 'Deployable applications that make up the platform.'
             },
@@ -2532,7 +2478,6 @@ function synthesizeWorkspaceSections(config) {
             text: 'Packages',
             link: '/packages',
             isolated: true,
-            icon: 'pixelarticons:archive',
             frontmatter: {
                 description: 'Shared libraries and utilities consumed across apps and services.'
             },
@@ -2545,7 +2490,6 @@ function synthesizeWorkspaceSections(config) {
             text: group.name,
             link,
             isolated: true,
-            icon: group.icon,
             frontmatter: {
                 description: group.description
             },
@@ -2766,9 +2710,8 @@ async function sync(config, options) {
         skipped: 0
     }));
     const removed = await match(previousManifest).with(P.nonNullable, async (m)=>await cleanStaleFiles(outDir, m, ctx.manifest)).otherwise(()=>Promise.resolve(0));
-    const icons = buildIconMap(allSections);
-    const sortedSidebar = buildMultiSidebar(resolved, openapiSidebar, icons);
-    const nav = generateNav(config, resolved, icons);
+    const sortedSidebar = buildMultiSidebar(resolved, openapiSidebar);
+    const nav = generateNav(config, resolved);
     await promises.writeFile(node_path.resolve(outDir, '.generated/sidebar.json'), JSON.stringify(sortedSidebar, null, 2), 'utf8');
     await promises.writeFile(node_path.resolve(outDir, '.generated/nav.json'), JSON.stringify(nav, null, 2), 'utf8');
     await saveManifest(outDir, ctx.manifest);
@@ -2864,17 +2807,6 @@ async function copyAll(src, dest) {
         else await promises.copyFile(srcPath, destPath);
     }, Promise.resolve());
 }
-function buildIconMap(sections) {
-    return new Map(sections.flatMap((section)=>{
-        if (section.icon) return [
-            [
-                section.text,
-                section.icon
-            ]
-        ];
-        return [];
-    }));
-}
 function resolveQuiet(quiet) {
     if (null != quiet) return quiet;
     return false;

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@zpress/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
+  "description": "Config loading, sync engine, and asset utilities for zpress",
+  "keywords": [
+    "config",
+    "core",
+    "docs",
+    "zpress"
+  ],
+  "homepage": "https://github.com/joggrdocs/zpress/tree/main/packages/core#readme",
+  "bugs": "https://github.com/joggrdocs/zpress/issues",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,12 +22,13 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",