@odla-ai/blog 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cory Ondrejka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,10 @@
 # @odla-ai/blog
 
+> ⚠️ **Experimental — an agentic-coding experiment.** This package is built and
+> operated by autonomous coding agents as an experiment in agentic loops. APIs
+> change without notice and nothing here is production-hardened. **Use at your
+> own risk.**
+
 Minimal-dependency, static-first blogging platform. A site is a directory of
 markdown plus one JSON config; `build()` emits a fully static site that works on
 GitHub Pages or Cloudflare. When [odla-db](https://github.com/odla-ai/odla-db) is
@@ -33,9 +38,13 @@ Four bundled themes, all with light + dark modes (system preference + ☾/☀ to
 - **chalk** — chalkboard on graph paper; copper/cerulean, mono chrome
 - **clay** — sand paper and terracotta; system fonts only, zero external requests
 
-Pick one with `"theme": "salt"` in `blog.config.json`. Override any theme file by
-placing a same-named file in your site's `theme/` directory. Preview all four
-against the example site with `npm run preview` (from the monorepo root).
+Pick one with `"theme": "salt"` in `blog.config.json`. Themes ship in the
+[`@odla-ai/ui`](https://www.npmjs.com/package/@odla-ai/ui) dependency (the odla
+design system); every built site also gets ui's class-scoped component layer
+(`assets/odla-ui.css` — buttons, form fields, cards, …) theme-matched via the
+theme's `ui.css` token aliases. Override any theme file by placing a
+same-named file in your site's `theme/` directory. Preview all four against
+the example site with `npm run preview` (from the monorepo root).
 
 ## Deploy (Cloudflare)
 

package/llms.txt

@@ -1,5 +1,9 @@
 # @odla-ai/blog — agent reference (llms.txt)
 
+> EXPERIMENTAL — an agentic-coding experiment. This package is built and operated
+> by autonomous coding agents as an experiment in agentic loops. APIs change
+> without notice and nothing here is production-hardened. Use at your own risk.
+
 This file ships in the npm package so an agent working in a *site* repo can
 operate the platform from `node_modules/@odla-ai/blog/llms.txt` alone. The
 source in `src/` is small and dependency-light — read it when in doubt; it is
@@ -109,12 +113,13 @@ const result = await build({
 
 Output: `index.html`, `posts/<slug>/index.html`, `<page>/index.html`,
 `archive/`, `tags/`, `tags/<tag>/`, `rss.xml`, `sitemap.xml`,
-`assets/styles.css`, plus everything from `public/`. All URLs are prefixed
-with `config.basePath` (default `/`) — set it when deploying under a subpath
-(e.g. GitHub project pages).
+`assets/styles.css`, `assets/odla-ui.css`, plus everything from `public/`.
+All URLs are prefixed with `config.basePath` (default `/`) — set it when
+deploying under a subpath (e.g. GitHub project pages).
 
 Also exported: `loadPosts`, `loadPages`, `parseFrontmatter`, `slugFromFilename`,
-`renderMarkdown`, `slugify`, `escapeHtml`, `resolveThemeFile`.
+`renderMarkdown`, `slugify`, `escapeHtml`, `resolveThemeFile`, `listThemes`,
+`THEME_NAMES`.
 
 ## Markdown
 
@@ -125,13 +130,19 @@ no client-side JS. Headings get slugified `id` anchors.
 ## Theming
 
 Bundled themes: `juniper` (default), `salt`, `chalk`, `clay` — pick with
-`"theme": "<name>"` in config. Each theme is a single self-contained
-`src/themes/<name>/styles.css` plus `theme.json` metadata.
-
-Invariants every theme upholds (keep them when editing or adding one):
+`"theme": "<name>"` in config. **Themes live in the `@odla-ai/ui`
+dependency** (`node_modules/@odla-ai/ui/themes/<name>/`): `styles.css` (the
+full theme), `ui.css` (maps the theme's palette onto the `--ui-*` design
+tokens), `theme.json` (metadata). Resolution order for any theme file:
+`<site>/theme/<file>` → `@odla-ai/ui/themes/<name>/<file>` →
+`src/templates/<file>`. (`@odla-ai/ui` also ships a `paper` theme — it is a
+dashboard theme, NOT a blog theme; it doesn't style the selector contract.)
+
+Invariants every theme upholds (keep them when editing or adding one;
+tested in @odla-ai/ui's `test/themes.test.js`):
 - Light tokens on `:root`; dark tokens duplicated on BOTH `[data-theme="dark"]`
   and `@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) }`.
-  The two dark blocks must stay identical (tested in `test/themes.test.js`).
+  The two dark blocks must stay identical.
 - Common token names: `--bg`, `--text`, `--accent`, `--border`, `--code-bg`,
   and the highlight set `--hl-keyword`, `--hl-string`, `--hl-comment`,
   `--hl-number`, `--hl-title`, `--hl-attr`, `--hl-type`, `--hl-meta`,
@@ -141,15 +152,25 @@ Invariants every theme upholds (keep them when editing or adding one):
   `.post-title`, `.post-meta`, `.post-tag`, `.prose`, `.page-title`,
   `.archive-year`, `.archive-list`, `.archive-item`, `.tag-cloud`, `.hljs-*`.
 
+**Component classes on any page:** every built site also ships
+`assets/odla-ui.css` (linked before the theme stylesheet) — the class-scoped
+@odla-ai/ui component layer (`.btn`, `.field`/`.input`/`.textarea`, `.card`,
+`.table`, `.banner`, chat classes, …), theme-correct because the build
+appends the theme's `ui.css` token aliases into `assets/styles.css`. Use
+these classes in pages/templates instead of inventing inline styles; the
+full inventory is in `node_modules/@odla-ai/ui/llms.txt`. A site
+`public/assets/odla-ui.css` overrides the shipped copy (public/ copies
+last), same valve as styles.css.
+
 **Site-local overrides:** any file placed in the site's `theme/` directory
-shadows the packaged theme file of the same name (`styles.css`, or any
-template like `post.js` or `index.js`). Copy the packaged file out, edit,
+shadows the packaged theme file of the same name (`styles.css`, `ui.css`, or
+any template like `post.js` or `index.js`). Copy the packaged file out, edit,
 done. Templates are plain JS functions returning template-literal HTML
 strings; they may import shared helpers from the package
 (`import { postList } from "@odla-ai/blog"`). To ADD styles without forking
 the whole stylesheet, put them in `theme/custom.css` — the build appends it
-to the theme's CSS. Post URLs live under `config.postsPath` (default
-"posts").
+to the theme's CSS (after the `ui.css` aliases). Post URLs live under
+`config.postsPath` (default "posts").
 
 ## Deploy (Cloudflare)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/blog",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Minimal-dependency, static-first blogging platform. Files in, site out; odla-db lights up interactivity when configured.",
   "type": "module",
   "license": "MIT",
@@ -21,9 +21,11 @@
   },
   "scripts": {
     "preview": "node scripts/preview.mjs",
-    "test": "node --test --test-reporter=spec"
+    "test": "node --test --test-reporter=spec",
+    "coverage": "c8 --src=src --reporter=text --reporter=html node --test"
   },
   "dependencies": {
+    "@odla-ai/ui": "^0.1.0",
     "highlight.js": "^11.11.0",
     "marked": "^16.0.0",
     "yaml": "^2.8.0"

package/src/build.js

@@ -1,10 +1,11 @@
 // Static build: content + theme → dist/. Pure pipeline, top to bottom.
 //
 // Theme resolution (file-by-file shadowing):
-//   1. <site>/theme/<file>          — site-local override
-//   2. src/themes/<name>/<file>     — the chosen packaged theme
-//   3. src/templates/<file>         — shared default templates
-// Themes usually only provide styles.css; templates come from the shared set.
+//   1. <site>/theme/<file>                    — site-local override
+//   2. @odla-ai/ui/themes/<name>/<file>       — the chosen packaged theme
+//   3. src/templates/<file>                   — shared default templates
+// Themes usually only provide styles.css (+ ui.css); templates come from
+// the shared set. Themes live in the @odla-ai/ui dependency.
 import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -13,15 +14,16 @@ import { loadPosts, loadPages, loadJsPages, loadCollections } from "./content.js
 import { renderMarkdown, slugify } from "./markdown.js";
 import { excerpt } from "./excerpt.js";
 import { atom, rss, sitemap } from "./feeds.js";
+import { THEME_NAMES, uiFile, uiThemeFile } from "./themes.js";
 
 const SRC = dirname(fileURLToPath(import.meta.url));
 
 export function resolveThemeFile(siteDir, themeName, file) {
   const candidates = [
     join(siteDir, "theme", file),
-    join(SRC, "themes", themeName, file),
+    uiThemeFile(themeName, file),
     join(SRC, "templates", file),
-  ];
+  ].filter(Boolean);
   return candidates.find((c) => existsSync(c)) ?? null;
 }
 
@@ -188,17 +190,37 @@ export async function build({
   await write("atom.xml", atom({ config, posts }));
   await write("sitemap.xml", sitemap({ config, posts, pages }));
 
-  // theme/custom.css is appended to the theme stylesheet — additions without
+  // Theme stylesheet assembly: styles.css, then the theme's ui.css (maps its
+  // palette onto the @odla-ai/ui --ui-* token contract so component classes
+  // render theme-correct), then site theme/custom.css — additions without
   // forking the whole file (full replacement: shadow styles.css itself).
   const styles = resolveThemeFile(siteDir, themeName, "styles.css");
-  if (!styles) throw new Error(`Theme "${themeName}" has no styles.css`);
+  if (!styles) {
+    throw new Error(
+      `Theme "${themeName}" has no styles.css — bundled themes: ${THEME_NAMES.join(", ")} (or add <site>/theme/styles.css)`
+    );
+  }
   let css = await readFile(styles, "utf8");
+  const uiAlias = resolveThemeFile(siteDir, themeName, "ui.css");
+  if (uiAlias) {
+    css += `\n/* ─── ${themeName}/ui.css (odla-ui token aliases) ─── */\n${await readFile(uiAlias, "utf8")}`;
+  }
   const customCss = join(siteDir, "theme", "custom.css");
   if (existsSync(customCss)) {
     css += `\n/* ─── site custom.css ─── */\n${await readFile(customCss, "utf8")}`;
   }
   await write(join("assets", "styles.css"), css);
 
+  // Every site ships the ui component layer (class-scoped, inert until a
+  // page uses the classes). base.js links it BEFORE styles.css so the theme
+  // and site css win ties. A site public/assets/odla-ui.css overrides it
+  // (public/ copies last), same valve as styles.css.
+  const uiCss = uiFile("odla-ui.css");
+  if (!uiCss) {
+    throw new Error("@odla-ai/ui not found — run npm install (blog themes and component CSS ship there)");
+  }
+  await write(join("assets", "odla-ui.css"), await readFile(uiCss, "utf8"));
+
   const publicDir = join(siteDir, "public");
   if (existsSync(publicDir)) await cp(publicDir, outDir, { recursive: true });
 

package/src/index.js

@@ -1,4 +1,5 @@
 export { build, resolveThemeFile } from "./build.js";
+export { listThemes, THEME_NAMES } from "./themes.js";
 export { loadPosts, loadPages, parseFrontmatter, slugFromFilename } from "./content.js";
 export { renderMarkdown, slugify, escapeHtml } from "./markdown.js";
 export { postList, tagList, tagUrl, formatDate, isoDate } from "./templates/helpers.js";

package/src/templates/base.js

@@ -125,6 +125,7 @@ export function base({ config, title, description, path, image, content }) {
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 ${headMeta(config, { fullTitle, description, path, image })}
+<link rel="stylesheet" href="${base}assets/odla-ui.css">
 <link rel="stylesheet" href="${base}assets/styles.css">
 <script>${NO_FLASH}</script>
 </head>

package/src/themes.js

@@ -0,0 +1,32 @@
+// Themes ship in @odla-ai/ui (themes/<name>/{styles.css,ui.css,theme.json});
+// this module is the blog's bridge to them. createRequire (not
+// import.meta.resolve) because it works on every Node 20.x, returns plain
+// filesystem paths, and verifies existence with a catchable error.
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+
+const require = createRequire(import.meta.url);
+
+// The bundled themes that uphold the blog selector contract. @odla-ai/ui
+// also ships "paper", which does not — keep it out of this list.
+export const THEME_NAMES = ["chalk", "clay", "juniper", "salt"];
+
+// Absolute path of a file shipped by @odla-ai/ui, or null if absent.
+export function uiFile(subpath) {
+  try {
+    return require.resolve(`@odla-ai/ui/${subpath}`);
+  } catch {
+    return null;
+  }
+}
+
+export function uiThemeFile(themeName, file) {
+  return uiFile(`themes/${themeName}/${file}`);
+}
+
+// Metadata for every bundled blog theme (for pickers/galleries).
+export function listThemes() {
+  return THEME_NAMES.map((name) =>
+    JSON.parse(readFileSync(uiThemeFile(name, "theme.json"), "utf8"))
+  );
+}