@odla-ai/blog 0.0.4 → 0.0.6

package/README.md

@@ -1,13 +1,13 @@
 # @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.**
+> ⚠️ **Early access — pre-1.0.** Agents work from bounded runbooks; humans
+> approve credentials, production changes, releases, and merges. APIs and exact
+> package availability can change. Review the documented guarantees and
+> limitations; this software is MIT-licensed and provided without warranty.
 
 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
+GitHub Pages or Cloudflare. When [odla-db](https://www.npmjs.com/package/@odla-ai/db) is
 configured, interactive features (sign-in, comments, likes) light up as a
 progressive layer — the static site never depends on it.
 
@@ -43,19 +43,30 @@ Pick one with `"theme": "salt"` in `blog.config.json`. Themes ship in the
 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).
+same-named file in your site's `theme/` directory. Build your site with the
+package API and preview the emitted static directory with your usual local
+static server.
+
+## Input boundaries
+
+Footnote identifiers are capped at 256 characters, and malformed `[^`
+introducers are handled by a monotonic scanner so adversarial Markdown cannot
+force repeated whole-suffix regex scans. Markdown still permits authored raw
+HTML by design; it is not a sanitizer. JS pages and collection templates must
+use `escapeHtml(String(value))` for every schema-free frontmatter value or
+filename-derived slug placed into HTML.
 
 ## Deploy (Cloudflare)
 
 `build()` emits a plain static directory; serve it from a Worker assets
 binding — `{ "assets": { "directory": "./dist-site" } }` in `wrangler.jsonc`,
 build before every deploy. Add a `main` worker script only when you want
-`/api/*` routes next to the static site (see `examples/demo-app` in the
-odla-ai monorepo for the full pattern, including odla-db + o11y wiring).
+`/api/*` routes next to the static site; the public platform manual describes
+how to combine the assets binding with odla-db and o11y.
 
 ## Status
 
-Early. The build pipeline, themes, and example site work; CLI (`init`/`new`/`dev`/
-`check`), feeds, search, deploy scaffolding, and the odla-db islands are in
-progress — see `PLAN.md` at the repo root.
+Early. The build pipeline and themes work; CLI (`init`/`new`/`dev`/`check`),
+feeds, search, deploy scaffolding, and the odla-db islands are in progress.
+Track supported behavior in the public docs and the package's shipped
+`llms.txt` rather than relying on internal planning files.

package/llms.txt

@@ -1,8 +1,11 @@
-# @odla-ai/blog — agent reference (llms.txt)
+# @odla-ai/blog — LLM context
 
-> 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. Files in, site out; odla-db lights up interactivity when configured.
+
+> EARLY ACCESS — pre-1.0. Agents work from bounded runbooks; humans approve
+> credentials, production changes, releases, and merges. APIs and exact package
+> availability can change. Review the documented guarantees and limitations;
+> this software is MIT-licensed and provided without warranty.
 
 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
@@ -84,7 +87,9 @@ package (`import { escapeHtml, renderMarkdown, postList } from "@odla-ai/blog"`)
 ## Markdown extras
 
 - **Footnotes** (GFM `[^1]` / `[^1]: text`) render as numbered superscript
-  links plus a `<section class="footnotes">` appended to the content.
+  links plus a `<section class="footnotes">` appended to the content. IDs are
+  limited to 256 characters, and malformed introducers are handled by a
+  monotonic scanner rather than repeated whole-suffix regex matching.
 - **Smart typography**: `--`/`---` become em dashes and straight quotes curl,
   in prose text only — code spans and blocks are never touched.
 - **Excerpts**: the home page (`indexLimit` most recent, default 20) and
@@ -127,6 +132,11 @@ GitHub-flavored, rendered by `marked`. Fenced code blocks are highlighted at
 build time by highlight.js (`lib/common` language set) into `hljs-*` classes —
 no client-side JS. Headings get slugified `id` anchors.
 
+Authored raw HTML remains enabled; this renderer is not a sanitizer. Treat
+schema-free collection/frontmatter fields and filename-derived slugs as
+untrusted when writing a JS page, and apply `escapeHtml(String(value))` in the
+correct HTML context.
+
 ## Theming
 
 Bundled themes: `juniper` (default), `salt`, `chalk`, `clay` — pick with
@@ -176,7 +186,7 @@ to the theme's CSS (after the `ui.css` aliases). Post URLs live under
 
 The output is a plain static directory — serve it from a Worker's assets
 binding (this is what `blog init --deploy cloudflare` will generate; a
-working example lives at `examples/demo-app` in the odla-ai monorepo):
+the public machine-readable platform runbook documents the same Worker + assets composition):
 
 ```js
 // build-site.mjs — run before every deploy

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@odla-ai/blog",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Minimal-dependency, static-first blogging platform. Files in, site out; odla-db lights up interactivity when configured.",
   "type": "module",
   "license": "MIT",
+  "homepage": "https://odla.ai/docs/packages/blog",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cory/odla-ai.git",
+    "directory": "packages/blog"
+  },
   "exports": {
     ".": "./src/index.js"
   },
@@ -14,7 +20,8 @@
     "config.schema.json"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": false
   },
   "engines": {
     "node": ">=20"
@@ -22,10 +29,12 @@
   "scripts": {
     "preview": "node scripts/preview.mjs",
     "test": "node --test --test-reporter=spec",
-    "coverage": "c8 --src=src --reporter=text --reporter=html node --test"
+    "coverage": "c8 --src=src --reporter=text --reporter=html node --test",
+    "gen:llms": "node ../../scripts/gen-llms.mjs",
+    "prepublishOnly": "npm run gen:llms && npm test"
   },
   "dependencies": {
-    "@odla-ai/ui": "^0.1.0",
+    "@odla-ai/ui": "^0.3.0",
     "highlight.js": "^11.11.0",
     "marked": "^16.0.0",
     "yaml": "^2.8.0"

package/src/markdown.js

@@ -31,17 +31,84 @@ export function slugify(text) {
 // is synchronous, so module-level state is safe.
 let footnoteNumbers = new Map(); // id → number, in first-reference order
 let footnoteBodies = new Map(); // id → rendered inline HTML
+let headingIds = new Map(); // base slug → occurrences in this document
+const MAX_FOOTNOTE_ID_LENGTH = 256;
+const footnoteWhitespace = /\s/u;
+
+// Return one syntactically valid reference at or after `from`. Both the search
+// cursor and every candidate cursor move only forward, while malformed IDs are
+// capped, so adversarial runs of "[^" remain linear in the input size.
+function findFootnoteReference(source, from = 0) {
+  let cursor = from;
+  while (cursor < source.length) {
+    const start = source.indexOf("[^", cursor);
+    if (start < 0) return;
+    const reference = parseFootnoteReference(source, start);
+    if (reference) return reference;
+    cursor = start + 2;
+  }
+}
+
+function parseFootnoteReference(source, start = 0) {
+  if (source[start] !== "[" || source[start + 1] !== "^") return;
+  const idEnd = footnoteIdEnd(source, start + 2);
+  if (idEnd === undefined || source[idEnd + 1] === ":") return;
+  return { index: start, id: source.slice(start + 2, idEnd), raw: source.slice(start, idEnd + 1) };
+}
+
+function footnoteIdEnd(source, start) {
+  for (let length = 0; start + length < source.length && length <= MAX_FOOTNOTE_ID_LENGTH; length++) {
+    const char = source[start + length];
+    if (char === "]") return length ? start + length : undefined;
+    if (footnoteWhitespace.test(char) || length === MAX_FOOTNOTE_ID_LENGTH) return;
+  }
+}
+
+// Parse a definition's first line and its ≥2-character horizontal-indent
+// continuation lines without a nested, backtracking regular expression.
+function parseFootnoteDefinition(source) {
+  if (!source.startsWith("[^")) return;
+  const idEnd = footnoteIdEnd(source, 2);
+  if (idEnd === undefined || source[idEnd + 1] !== ":") return;
+  let cursor = idEnd + 2;
+  while (source[cursor] === " " || source[cursor] === "\t") cursor++;
+  let lineEnd = source.indexOf("\n", cursor);
+  if (lineEnd < 0) lineEnd = source.length;
+  const body = [source.slice(cursor, lineEnd)];
+  let rawEnd = lineEnd;
+  while (lineEnd < source.length) {
+    const indentStart = lineEnd + 1;
+    let contentStart = indentStart;
+    while (source[contentStart] === " " || source[contentStart] === "\t") contentStart++;
+    if (contentStart - indentStart < 2) break;
+    lineEnd = source.indexOf("\n", contentStart);
+    if (lineEnd < 0) lineEnd = source.length;
+    body.push(source.slice(contentStart, lineEnd));
+    rawEnd = lineEnd;
+  }
+  return { id: source.slice(2, idEnd), raw: source.slice(0, rawEnd), text: body.join(" ").trim() };
+}
+
+function uniqueHeadingId(text) {
+  const base = slugify(text);
+  const count = (headingIds.get(base) ?? 0) + 1;
+  headingIds.set(base, count);
+  return count === 1 ? base : `${base}-${count}`;
+}
 
 const footnotes = {
   hooks: {
     preprocess(markdown) {
       footnoteNumbers = new Map();
       footnoteBodies = new Map();
+      headingIds = new Map();
       // Number by first reference (definitions like "[^id]:" excluded).
-      for (const match of markdown.matchAll(/\[\^([^\]\s]+)\](?!:)/g)) {
-        if (!footnoteNumbers.has(match[1])) {
-          footnoteNumbers.set(match[1], footnoteNumbers.size + 1);
+      let reference = findFootnoteReference(markdown);
+      while (reference) {
+        if (!footnoteNumbers.has(reference.id)) {
+          footnoteNumbers.set(reference.id, footnoteNumbers.size + 1);
         }
+        reference = findFootnoteReference(markdown, reference.index + reference.raw.length);
       }
       return markdown;
     },
@@ -62,14 +129,13 @@ const footnotes = {
       level: "block",
       tokenizer(src) {
         // "[^id]: text" plus continuation lines indented ≥2 spaces.
-        const match = /^\[\^([^\]\s]+)\]:[ \t]*([^\n]*(?:\n[ \t]{2,}[^\n]*)*)/.exec(src);
-        if (!match) return;
-        const text = match[2].replace(/\n[ \t]+/g, " ").trim();
+        const definition = parseFootnoteDefinition(src);
+        if (!definition) return;
         return {
           type: "footnoteDef",
-          raw: match[0],
-          id: match[1],
-          tokens: this.lexer.inlineTokens(text),
+          raw: definition.raw,
+          id: definition.id,
+          tokens: this.lexer.inlineTokens(definition.text),
         };
       },
       renderer(token) {
@@ -86,10 +152,14 @@ const footnotes = {
         return src.indexOf("[^");
       },
       tokenizer(src) {
-        const match = /^\[\^([^\]\s]+)\](?!:)/.exec(src);
-        if (match && footnoteNumbers.has(match[1])) {
-          return { type: "footnoteRef", raw: match[0], id: match[1] };
+        if (!src.startsWith("[^")) return;
+        const reference = parseFootnoteReference(src);
+        if (reference && footnoteNumbers.has(reference.id)) {
+          return { type: "footnoteRef", raw: reference.raw, id: reference.id };
         }
+        // Consume the introducer as ordinary text. Returning here prevents
+        // Marked from retrying every malformed prefix against the whole suffix.
+        return { type: "text", raw: "[^", text: "[^" };
       },
       renderer(token) {
         const n = footnoteNumbers.get(token.id);
@@ -135,7 +205,7 @@ const marked = new Marked(
       },
       heading({ tokens, depth }) {
         const text = this.parser.parseInline(tokens);
-        const id = slugify(text);
+        const id = uniqueHeadingId(text);
         return `<h${depth} id="${id}">${text}</h${depth}>\n`;
       },
     },