@repraze/kernelkit 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/vite/index.js

@@ -0,0 +1,242 @@
+/// <reference types="node" />
+/**
+ * Vite plugins shared by the suite's sites (Node-side: no React, nothing here reaches the browser).
+ *
+ * ```ts
+ * import {docsMetaPlugin, faviconPlugin, spaFallback, suiteSourceConditions, themeScriptPlugin} from "@repraze/kernelkit/vite";
+ * ```
+ *
+ * `vite` is only imported for its types; `typescript` is loaded lazily by docsMetaPlugin / extractFunction.
+ */
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { copyFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { themeScript } from "../provider/theme.js";
+/**
+ * Inline the kit's pre-paint theme script into index.html, so the stored mode, contrast, accent and radius
+ * apply before first paint. Replaces the marker comment, or goes first in <head> when there is none.
+ */
+export function themeScriptPlugin({ storageKey, defaults, marker = "<!-- kernelkit:theme-script -->", prelude, }) {
+    const source = [prelude, themeScript({ storageKey, defaults })].filter(Boolean).join("\n");
+    return {
+        name: "kernelkit-theme-script",
+        transformIndexHtml: (html) => html.includes(marker)
+            ? html.replace(marker, `<script>${source}</script>`)
+            : { html, tags: [{ tag: "script", children: source, injectTo: "head-prepend" }] },
+    };
+}
+// ─── favicon ────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Serve (dev) and emit (build) `favicon.svg` from the brand mark's SVG, so the icon never drifts from the
+ * logo. Link it with `href="%BASE_URL%favicon.svg"` so it works under a Pages base path.
+ */
+export function faviconPlugin(svg, fileName = "favicon.svg") {
+    const source = typeof svg === "function" ? svg() : svg;
+    return {
+        name: "kernelkit-favicon",
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.url?.split("?")[0]?.endsWith(`/${fileName}`)) {
+                    res.setHeader("Content-Type", "image/svg+xml");
+                    res.end(source);
+                    return;
+                }
+                next();
+            });
+        },
+        generateBundle() {
+            this.emitFile({ type: "asset", fileName, source });
+        },
+    };
+}
+// ─── SPA fallback ───────────────────────────────────────────────────────────────────────────────
+/** GitHub Pages has no SPA rewrites: copy index.html to 404.html so deep links load the app. */
+export function spaFallback() {
+    return {
+        name: "kernelkit-spa-fallback",
+        apply: "build",
+        async writeBundle({ dir }) {
+            if (dir) {
+                await copyFile(join(dir, "index.html"), join(dir, "404.html"));
+            }
+        },
+    };
+}
+// ─── linked suite packages ──────────────────────────────────────────────────────────────────────
+/** Is `node_modules/<name>` a symlink (npm link, a workspace), looking up from `root`? */
+function isLinked(name, root) {
+    for (let dir = resolve(root);; dir = dirname(dir)) {
+        try {
+            return lstatSync(join(dir, "node_modules", name)).isSymbolicLink();
+        }
+        catch {
+            // not installed here: look in the parent
+        }
+        if (dirname(dir) === dir) {
+            return false;
+        }
+    }
+}
+const DEDUPE = ["react", "react-dom", "@base-ui/react", "cmdk", "lucide-react"];
+/**
+ * For each suite package (`@repraze/kernelkit`…) that is symlinked into node_modules (`npm link`, a
+ * workspace): serve it from its TypeScript sources (its `@repraze/source` exports condition), unbundled,
+ * so edits there hot-reload; dedupe React-context packages, since a linked package sits outside this tree.
+ * Installed from npm: nothing changes, its built dist is used and pre-bundled like any dependency.
+ */
+export function suiteSourceConditions(packages, options = {}) {
+    const { dedupe = DEDUPE, condition = "@repraze/source" } = options;
+    return {
+        name: "kernelkit-suite-source-conditions",
+        enforce: "pre",
+        config(config) {
+            const linked = packages.filter((name) => isLinked(name, config.root ?? process.cwd()));
+            if (!linked.length) {
+                return undefined;
+            }
+            return {
+                resolve: { conditions: [condition, ...DEFAULT_CLIENT_CONDITIONS], dedupe },
+                optimizeDeps: { exclude: linked },
+            };
+        },
+    };
+}
+/** Vite's `defaultClientConditions`, inlined so this module needs no runtime import of vite. */
+const DEFAULT_CLIENT_CONDITIONS = ["module", "browser", "development|production"];
+// ─── docs manifest and demo sources ─────────────────────────────────────────────────────────────
+const require = createRequire(import.meta.url);
+let typescript;
+/** TypeScript, loaded on first use (the sites already have it): only docs sites pay for it. */
+const ts = () => (typescript ??= require("typescript"));
+/** Static value of a string/number expression: literals, no-substitution templates, "a" + "b". */
+function literal(node) {
+    const t = ts();
+    if (t.isStringLiteral(node) || t.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    if (t.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    if (t.isParenthesizedExpression(node)) {
+        return literal(node.expression);
+    }
+    if (t.isBinaryExpression(node) && node.operatorToken.kind === t.SyntaxKind.PlusToken) {
+        const a = literal(node.left);
+        const b = literal(node.right);
+        return a !== undefined && b !== undefined ? `${a}${b}` : undefined;
+    }
+    return undefined;
+}
+/** A docs page's manifest entry, read from its `defineDoc({...})` call without running it. */
+export function readDocMeta(file, slug, source = readFileSync(file, "utf8")) {
+    const t = ts();
+    const sf = t.createSourceFile(file, source, t.ScriptTarget.Latest, true);
+    let meta;
+    const visit = (node) => {
+        if (!meta &&
+            t.isCallExpression(node) &&
+            t.isIdentifier(node.expression) &&
+            node.expression.text === "defineDoc" &&
+            node.arguments[0] &&
+            t.isObjectLiteralExpression(node.arguments[0])) {
+            const props = {};
+            for (const p of node.arguments[0].properties) {
+                if (t.isPropertyAssignment(p) && t.isIdentifier(p.name)) {
+                    props[p.name.text] = literal(p.initializer);
+                }
+            }
+            if (typeof props.title !== "string" || typeof props.category !== "string") {
+                throw new Error(`${file}: defineDoc needs literal "title" and "category" (read at build time)`);
+            }
+            meta = {
+                slug,
+                title: props.title,
+                category: props.category,
+                description: typeof props.description === "string" ? props.description : "",
+                ...(typeof props.order === "number" ? { order: props.order } : {}),
+            };
+        }
+        t.forEachChild(node, visit);
+    };
+    visit(sf);
+    if (!meta) {
+        throw new Error(`${file}: no defineDoc({...}) call found`);
+    }
+    return meta;
+}
+/** Each top-level function or const of a file, by name, as written (without `export `). */
+export function extractFunctions(source, fileName = "doc.tsx") {
+    const t = ts();
+    const sf = t.createSourceFile(fileName, source, t.ScriptTarget.Latest, true, t.ScriptKind.TSX);
+    const out = {};
+    const text = (node) => source.slice(node.getStart(sf), node.getEnd()).replace(/^export /, "");
+    for (const statement of sf.statements) {
+        if (t.isFunctionDeclaration(statement) && statement.name) {
+            out[statement.name.text] = text(statement);
+        }
+        else if (t.isVariableStatement(statement)) {
+            for (const decl of statement.declarationList.declarations) {
+                if (t.isIdentifier(decl.name)) {
+                    out[decl.name.text] = text(statement);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * A demo's own source: its declaration from `export function Name` (or `export const Name`) to its
+ * closing brace, parsed with TypeScript, so code after it (a `Notes()` helper, constants) stays out.
+ */
+export function extractFunction(source, name) {
+    return extractFunctions(source)[name] ?? "";
+}
+const META_ID = "virtual:docs-meta";
+const META_RESOLVED = `\0${META_ID}`;
+const SOURCES_QUERY = "demo-sources";
+/**
+ * The docs build step, for `@repraze/kernelkit/docs`:
+ * - `virtual:docs-meta`: title, category, description and order of every page in `docsDir`, read
+ *   statically from its `defineDoc({...})` call, so the nav and search don't pull every page's demos into
+ *   the main bundle;
+ * - `<page>.tsx?demo-sources`: `{functions}`, each demo's own source for its Code tab (see extractFunction).
+ *
+ * Types: add `@repraze/kernelkit/vite/client` to the site's tsconfig `types`.
+ */
+export function docsMetaPlugin(docsDir) {
+    const dir = resolve(docsDir);
+    return {
+        name: "kernelkit-docs-meta",
+        enforce: "pre",
+        resolveId: (id) => (id === META_ID ? META_RESOLVED : undefined),
+        load(id) {
+            if (id === META_RESOLVED) {
+                const files = readdirSync(dir).filter((f) => f.endsWith(".tsx"));
+                const metas = files.map((f) => {
+                    const file = join(dir, f);
+                    this.addWatchFile(file);
+                    return readDocMeta(file, f.replace(/\.tsx$/, ""));
+                });
+                return `export default ${JSON.stringify(metas)};`;
+            }
+            const [file = "", query = ""] = id.split("?");
+            if (query.split("&").includes(SOURCES_QUERY)) {
+                this.addWatchFile(file);
+                const functions = extractFunctions(readFileSync(file, "utf8"), file);
+                return { code: `export default ${JSON.stringify({ functions })};`, moduleType: "js" };
+            }
+            return undefined;
+        },
+        // a docs page added, removed or retitled → refresh the manifest
+        handleHotUpdate({ file, server }) {
+            if (file.startsWith(dir)) {
+                const mod = server.moduleGraph.getModuleById(META_RESOLVED);
+                if (mod) {
+                    server.moduleGraph.invalidateModule(mod);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B;;;;;;;;GAQG;AACH,OAAO,EAAC,SAAS,EAAE,WAAW,EAAE,YAAY,EAAC,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAC,QAAQ,EAAC,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AAKjD,OAAO,EAAC,WAAW,EAAkB,MAAM,sBAAsB,CAAC;AAelE;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAC9B,UAAU,EACV,QAAQ,EACR,MAAM,GAAG,iCAAiC,EAC1C,OAAO,GACgB;IACvB,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,EAAC,UAAU,EAAE,QAAQ,EAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzF,OAAO;QACH,IAAI,EAAE,wBAAwB;QAC9B,kBAAkB,EAAE,CAAC,IAAI,EAAE,EAAE,CACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YACjB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,MAAM,WAAW,CAAC;YACpD,CAAC,CAAC,EAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAC,CAAC,EAAC;KACxF,CAAC;AACN,CAAC;AAED,mGAAmG;AAEnG;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAA4B,EAAE,QAAQ,GAAG,aAAa;IAChF,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACvD,OAAO;QACH,IAAI,EAAE,mBAAmB;QACzB,eAAe,CAAC,MAAM;YAClB,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;gBACtC,IAAI,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,CAAC;oBACnD,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;oBAC/C,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAChB,OAAO;gBACX,CAAC;gBACD,IAAI,EAAE,CAAC;YACX,CAAC,CAAC,CAAC;QACP,CAAC;QACD,cAAc;YACV,IAAI,CAAC,QAAQ,CAAC,EAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAC,CAAC,CAAC;QACrD,CAAC;KACJ,CAAC;AACN,CAAC;AAED,mGAAmG;AAEnG,gGAAgG;AAChG,MAAM,UAAU,WAAW;IACvB,OAAO;QACH,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,OAAO;QACd,KAAK,CAAC,WAAW,CAAC,EAAC,GAAG,EAAC;YACnB,IAAI,GAAG,EAAE,CAAC;gBACN,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;YACnE,CAAC;QACL,CAAC;KACJ,CAAC;AACN,CAAC;AAED,mGAAmG;AAEnG,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,IAAY,EAAE,IAAY;IACxC,KAAK,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC;YACD,OAAO,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACL,yCAAyC;QAC7C,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;YACvB,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;AACL,CAAC;AASD,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAkB,EAAE,UAA8B,EAAE;IACtF,MAAM,EAAC,MAAM,GAAG,MAAM,EAAE,SAAS,GAAG,iBAAiB,EAAC,GAAG,OAAO,CAAC;IACjE,OAAO;QACH,IAAI,EAAE,mCAAmC;QACzC,OAAO,EAAE,KAAK;QACd,MAAM,CAAC,MAAM;YACT,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACvF,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACjB,OAAO,SAAS,CAAC;YACrB,CAAC;YACD,OAAO;gBACH,OAAO,EAAE,EAAC,UAAU,EAAE,CAAC,SAAS,EAAE,GAAG,yBAAyB,CAAC,EAAE,MAAM,EAAC;gBACxE,YAAY,EAAE,EAAC,OAAO,EAAE,MAAM,EAAC;aAClC,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC;AAED,gGAAgG;AAChG,MAAM,yBAAyB,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,wBAAwB,CAAC,CAAC;AAElF,mGAAmG;AAEnG,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,IAAI,UAAiC,CAAC;AACtC,+FAA+F;AAC/F,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,UAAU,KAAK,OAAO,CAAC,YAAY,CAAc,CAAC,CAAC;AAErE,kGAAkG;AAClG,SAAS,OAAO,CAAC,IAAmB;IAChC,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC;IACf,IAAI,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,+BAA+B,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IACD,IAAI,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,OAAO,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;QACnF,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACvE,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAWD,8FAA8F;AAC9F,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;IACvF,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC;IACf,MAAM,EAAE,GAAG,CAAC,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzE,IAAI,IAA+B,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,IAAa,EAAE,EAAE;QAC5B,IACI,CAAC,IAAI;YACL,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC;YACxB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC;YAC/B,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,WAAW;YACpC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;YACjB,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAChD,CAAC;YACC,MAAM,KAAK,GAAgD,EAAE,CAAC;YAC9D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;gBAC3C,IAAI,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;oBACtD,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;gBAChD,CAAC;YACL,CAAC;YACD,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACxE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,uEAAuE,CAAC,CAAC;YACpG,CAAC;YACD,IAAI,GAAG;gBACH,IAAI;gBACJ,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,WAAW,EAAE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;gBAC3E,GAAG,CAAC,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;aACnE,CAAC;QACN,CAAC;QACD,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,IAAI,CAAC,IAAI,EAAE,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,kCAAkC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,QAAQ,GAAG,SAAS;IACjE,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC;IACf,MAAM,EAAE,GAAG,CAAC,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/F,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,CAAC,IAAa,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACvG,KAAK,MAAM,SAAS,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC;QACpC,IAAI,CAAC,CAAC,qBAAqB,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;YACvD,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/C,CAAC;aAAM,IAAI,CAAC,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1C,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,eAAe,CAAC,YAAY,EAAE,CAAC;gBACxD,IAAI,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC5B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC1C,CAAC;YACL,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,IAAY;IACxD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,OAAO,GAAG,mBAAmB,CAAC;AACpC,MAAM,aAAa,GAAG,KAAK,OAAO,EAAE,CAAC;AACrC,MAAM,aAAa,GAAG,cAAc,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO;QACH,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,KAAK;QACd,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/D,IAAI,CAAC,EAAE;YACH,IAAI,EAAE,KAAK,aAAa,EAAE,CAAC;gBACvB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;gBACjE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;oBAC1B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;oBACxB,OAAO,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;gBACtD,CAAC,CAAC,CAAC;gBACH,OAAO,kBAAkB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC;YACtD,CAAC;YACD,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC3C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;gBACxB,MAAM,SAAS,GAAG,gBAAgB,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;gBACrE,OAAO,EAAC,IAAI,EAAE,kBAAkB,IAAI,CAAC,SAAS,CAAC,EAAC,SAAS,EAAC,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAC,CAAC;YACtF,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,gEAAgE;QAChE,eAAe,CAAC,EAAC,IAAI,EAAE,MAAM,EAAC;YAC1B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;gBAC5D,IAAI,GAAG,EAAE,CAAC;oBACN,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;gBAC7C,CAAC;YACL,CAAC;QACL,CAAC;KACJ,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@repraze/kernelkit",
-    "version": "0.1.0-alpha.3",
+    "version": "0.1.0-alpha.4",
     "description": "Modern, techy React components: every shadcn component on Base UI, Tailwind v4 and cva, themed by TermiColor.",
     "keywords": [
         "react",
@@ -56,7 +56,26 @@
             "types": "./dist/provider/theme.d.ts",
             "default": "./dist/provider/theme.js"
         },
+        "./docs": {
+            "@repraze/source": "./src/docs/index.ts",
+            "types": "./dist/docs/index.d.ts",
+            "default": "./dist/docs/index.js"
+        },
+        "./site": {
+            "@repraze/source": "./src/site/index.ts",
+            "types": "./dist/site/index.d.ts",
+            "default": "./dist/site/index.js"
+        },
+        "./vite": {
+            "@repraze/source": "./src/vite/index.ts",
+            "types": "./dist/vite/index.d.ts",
+            "default": "./dist/vite/index.js"
+        },
+        "./vite/client": {
+            "types": "./src/vite/client.d.ts"
+        },
         "./styles.css": "./src/styles/kernelkit.css",
+        "./site.css": "./src/styles/site.css",
         "./package.json": "./package.json"
     },
     "files": [
@@ -83,7 +102,11 @@
         "input-otp": "^1.5.0",
         "react-resizable-panels": "^4.19.1",
         "@tanstack/react-virtual": "^3.14.26",
-        "@shadcn/react": "^0.3.1"
+        "@shadcn/react": "^0.3.1",
+        "@fontsource-variable/geist": "^5.2.0",
+        "@fontsource-variable/jetbrains-mono": "^5.2.0",
+        "typescript": ">=5.0",
+        "vite": ">=7.0"
     },
     "peerDependenciesMeta": {
         "recharts": {
@@ -115,6 +138,18 @@
         },
         "@shadcn/react": {
             "optional": true
+        },
+        "@fontsource-variable/geist": {
+            "optional": true
+        },
+        "@fontsource-variable/jetbrains-mono": {
+            "optional": true
+        },
+        "typescript": {
+            "optional": true
+        },
+        "vite": {
+            "optional": true
         }
     },
     "dependencies": {
@@ -141,6 +176,7 @@
         "input-otp": "^1.5.0",
         "react-resizable-panels": "^4.19.1",
         "@tanstack/react-virtual": "^3.14.26",
-        "@shadcn/react": "^0.3.1"
+        "@shadcn/react": "^0.3.1",
+        "vite": "^8.3.6"
     }
 }

package/src/components/search-dialog.tsx

@@ -84,4 +84,17 @@ function SearchFooter({className, ...props}: React.ComponentProps<"div">) {
     );
 }
 
-export {SearchDialog, SearchFooter, SearchItem};
+/**
+ * The suite's search filter for `<Command filter={substringFilter}>`: a plain substring match (prefix
+ * matches rank first). cmdk's default fuzzy match finds "t…a…b" in nearly every title.
+ */
+function substringFilter(value: string, search: string, keywords?: string[]) {
+    const haystack = [value, ...(keywords ?? [])].join(" ").toLowerCase();
+    const needle = search.trim().toLowerCase();
+    if (haystack.startsWith(needle)) {
+        return 1;
+    }
+    return haystack.includes(needle) ? 0.5 : 0;
+}
+
+export {SearchDialog, SearchFooter, SearchItem, substringFilter};

package/src/docs/doc-kit.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import {
+    CodeBlock,
+    CodeBlockActions,
+    CodeBlockContent,
+    CodeBlockCopyButton,
+    CodeBlockHeader,
+    CodeBlockTitle,
+} from "@repraze/kernelkit/components/code-block";
+import {Table, TableBody, TableCell, TableHead, TableHeader, TableRow} from "@repraze/kernelkit/components/table";
+import {Tabs, TabsContent, TabsList, TabsTrigger} from "@repraze/kernelkit/components/tabs";
+import {useHighlightedCode} from "@repraze/kernelkit/hooks/use-highlighted-code";
+import {cn} from "cn";
+import type * as React from "react";
+
+export interface PropRow {
+    name: string;
+    type: string;
+    default?: string;
+    description?: string;
+}
+
+export interface DemoDef {
+    title: string;
+    description?: string;
+    component: React.ComponentType;
+    /** Preview frame: "center" (default), "start" (top-left), "full" (no padding), "tall". */
+    layout?: "center" | "start" | "full" | "tall";
+}
+
+/** A docs page: one `defineDoc({...})` per file in the site's docs folder (read statically by docsMetaPlugin). */
+export interface DocDef<Category extends string = string> {
+    title: string;
+    category: Category;
+    description: string;
+    /** A link badge after the category in the page header: the primitive it wraps, the source file it documents. */
+    source?: {label: string; href: string};
+    demos: DemoDef[];
+    props?: {component: string; rows: PropRow[]}[];
+    /** Freeform content after the demos. */
+    notes?: React.ComponentType;
+    /** The notes' own h2 sections (`id` on each), listed in the table of contents after the demos. */
+    sections?: {id: string; title: string}[];
+    /** Sort order inside the category (lower first, default 50). */
+    order?: number;
+}
+
+export interface DocEntry<Category extends string = string> extends DocDef<Category> {
+    slug: string;
+    /** Source of each demo's own function, by demo index. */
+    demoSources: string[];
+}
+
+/**
+ * Declare a docs page. The site narrows the categories once:
+ *
+ * ```ts
+ * export const CATEGORIES = ["Foundations", "Components"] as const;
+ * export const defineDoc = (doc: DocDef<(typeof CATEGORIES)[number]>) => doc;
+ * ```
+ */
+export function defineDoc<Category extends string>(doc: DocDef<Category>): DocDef<Category> {
+    return doc;
+}
+
+export function slugify(text: string) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+
+/** A highlighted, copyable code sample (the kit's CodeBlock), titled with its language by default. */
+export function Code({
+    code,
+    language = "tsx",
+    title,
+    className,
+}: {
+    code: string;
+    language?: string;
+    title?: string;
+    className?: string;
+}) {
+    const lines = useHighlightedCode(code, language);
+    return (
+        <CodeBlock className={className}>
+            <CodeBlockHeader>
+                <CodeBlockTitle>{title ?? language}</CodeBlockTitle>
+                <CodeBlockActions>
+                    <CodeBlockCopyButton value={code} />
+                </CodeBlockActions>
+            </CodeBlockHeader>
+            <CodeBlockContent className="max-h-[480px] text-[13px]">
+                {lines.map((line, i) => (
+                    <span key={i} className="block min-h-lh">
+                        {line}
+                    </span>
+                ))}
+            </CodeBlockContent>
+        </CodeBlock>
+    );
+}
+
+const layoutClass: Record<NonNullable<DemoDef["layout"]>, string> = {
+    center: "flex min-h-56 items-center justify-center p-8",
+    start: "flex min-h-56 items-start justify-start p-8",
+    full: "overflow-hidden",
+    tall: "flex min-h-[28rem] items-center justify-center p-8",
+};
+
+/** One demo: its title and description, then Preview and Code tabs. The section's id is the slugified title. */
+export function Demo({demo, code}: {demo: DemoDef; code: string}) {
+    const Component = demo.component;
+    return (
+        <section className="flex scroll-mt-24 flex-col gap-3" id={slugify(demo.title)}>
+            <div className="flex flex-col gap-1">
+                <h3 className="font-mono text-sm font-medium">{demo.title}</h3>
+                {demo.description ? <p className="text-sm text-muted-foreground">{demo.description}</p> : null}
+            </div>
+            <Tabs defaultValue="preview">
+                <TabsList>
+                    <TabsTrigger value="preview">Preview</TabsTrigger>
+                    <TabsTrigger value="code">Code</TabsTrigger>
+                </TabsList>
+                <TabsContent value="preview">
+                    <div
+                        data-slot="demo-frame"
+                        className={cn("rounded-xl border bg-card", layoutClass[demo.layout ?? "center"])}
+                    >
+                        <Component />
+                    </div>
+                </TabsContent>
+                <TabsContent value="code">
+                    <Code code={code} />
+                </TabsContent>
+            </Tabs>
+        </section>
+    );
+}
+
+/** A component's props: name, type, default and description. */
+export function PropsTable({component, rows}: {component: string; rows: PropRow[]}) {
+    return (
+        <section className="flex flex-col gap-3">
+            <h3 className="font-mono text-sm font-medium">{component}</h3>
+            <div className="overflow-hidden rounded-xl border bg-card">
+                <Table>
+                    <TableHeader>
+                        <TableRow>
+                            <TableHead>Prop</TableHead>
+                            <TableHead>Type</TableHead>
+                            <TableHead>Default</TableHead>
+                            <TableHead>Description</TableHead>
+                        </TableRow>
+                    </TableHeader>
+                    <TableBody>
+                        {rows.map((row) => (
+                            <TableRow key={row.name}>
+                                <TableCell className="font-mono text-xs text-primary-text">{row.name}</TableCell>
+                                <TableCell className="font-mono text-xs whitespace-normal">{row.type}</TableCell>
+                                <TableCell className="font-mono text-xs text-muted-foreground">
+                                    {row.default ?? "-"}
+                                </TableCell>
+                                <TableCell className="text-sm whitespace-normal text-muted-foreground">
+                                    {row.description}
+                                </TableCell>
+                            </TableRow>
+                        ))}
+                    </TableBody>
+                </Table>
+            </div>
+        </section>
+    );
+}

package/src/docs/doc-page.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import {Badge} from "@repraze/kernelkit/components/badge";
+import {
+    PageHeader,
+    PageHeaderDescription,
+    PageHeaderEyebrow,
+    PageHeaderTitle,
+} from "@repraze/kernelkit/components/page-header";
+import {Pager, PagerLink} from "@repraze/kernelkit/components/pager";
+import {SiteAside, SiteLayout, SiteMain, SiteSidebar} from "@repraze/kernelkit/components/site-layout";
+import {Toc, TocItem, TocList, TocTitle, useTocActive} from "@repraze/kernelkit/components/toc";
+import {ExternalLinkIcon} from "lucide-react";
+import type * as React from "react";
+
+import {Demo, type DocEntry, PropsTable, slugify} from "./doc-kit";
+import type {DocsIndex} from "./docs-index";
+
+/** A router link to a docs page, used as a `render` element: `(slug) => <Link to="/docs/$slug" params={{slug}} />`. */
+export type DocLinkFor = (slug: string) => React.ReactElement;
+
+/** The table of contents of a page: its demos, the notes' sections, then the API. */
+export function docToc(doc: DocEntry): {id: string; title: string}[] {
+    return [
+        ...doc.demos.map((demo) => ({id: slugify(demo.title), title: demo.title})),
+        ...(doc.sections ?? []),
+        ...(doc.props?.length ? [{id: "api", title: "API"}] : []),
+    ];
+}
+
+export interface DocPageProps<Category extends string = string> {
+    /** The loaded page (`index.loadDoc(slug)`, usually from the route's loader). */
+    doc: DocEntry<Category>;
+    index: DocsIndex<Category>;
+    linkFor: DocLinkFor;
+}
+
+/**
+ * A docs page in the suite's layout (GUIDELINES §7b): PageHeader (category, source badge, title,
+ * description), the demos, the notes, the API tables and the Pager in SiteMain; the Toc in SiteAside.
+ */
+export function DocPage<Category extends string>({doc, index, linkFor}: DocPageProps<Category>) {
+    const {prev, next} = index.neighbours(doc.slug);
+    const Notes = doc.notes;
+    const sections = docToc(doc);
+    const active = useTocActive(sections.map((s) => s.id));
+
+    return (
+        <>
+            <SiteMain>
+                <PageHeader>
+                    <PageHeaderEyebrow>
+                        <Badge variant="outline">{doc.category}</Badge>
+                        {doc.source ? (
+                            <Badge
+                                variant="secondary"
+                                className="font-mono"
+                                render={<a href={doc.source.href} target="_blank" rel="noreferrer" />}
+                            >
+                                {doc.source.label} <ExternalLinkIcon />
+                            </Badge>
+                        ) : null}
+                    </PageHeaderEyebrow>
+                    <PageHeaderTitle>{doc.title}</PageHeaderTitle>
+                    <PageHeaderDescription>{doc.description}</PageHeaderDescription>
+                </PageHeader>
+
+                {doc.demos.map((demo, i) => (
+                    <Demo key={demo.title} demo={demo} code={doc.demoSources[i] ?? ""} />
+                ))}
+
+                {Notes ? (
+                    <div className="flex flex-col gap-4">
+                        <Notes />
+                    </div>
+                ) : null}
+
+                {doc.props?.length ? (
+                    <section id="api" className="flex scroll-mt-24 flex-col gap-6">
+                        <h2 className="font-heading text-xl font-semibold">API</h2>
+                        {doc.props.map((p) => (
+                            <PropsTable key={p.component} {...p} />
+                        ))}
+                    </section>
+                ) : null}
+
+                <Pager>
+                    {prev ? (
+                        <PagerLink direction="previous" render={linkFor(prev.slug)}>
+                            {prev.title}
+                        </PagerLink>
+                    ) : null}
+                    {next ? (
+                        <PagerLink direction="next" render={linkFor(next.slug)}>
+                            {next.title}
+                        </PagerLink>
+                    ) : null}
+                </Pager>
+            </SiteMain>
+            {sections.length > 1 ? (
+                <SiteAside>
+                    <Toc>
+                        <TocTitle>On this page</TocTitle>
+                        <TocList>
+                            {sections.map((s) => (
+                                <TocItem key={s.id} href={`#${s.id}`} active={s.id === active}>
+                                    {s.title}
+                                </TocItem>
+                            ))}
+                        </TocList>
+                    </Toc>
+                </SiteAside>
+            ) : null}
+        </>
+    );
+}
+
+/** The suite's docs layout: SiteLayout with the docs nav in a sticky SiteSidebar, then the page (which adds its Toc). */
+export function DocsLayout({nav, children}: {nav: React.ReactNode; children: React.ReactNode}) {
+    return (
+        <SiteLayout>
+            <SiteSidebar>{nav}</SiteSidebar>
+            {children}
+        </SiteLayout>
+    );
+}