@zvndev/darkmown 0.7.0 → 0.8.0

package/AGENTS.md

@@ -27,6 +27,8 @@ Commands: `darkmown dev`, `darkmown build`, `darkmown serve`.
 
 `{ name }` or `{ name.path }`. Resolves in order: loop item → in-scope value → declared `:state` → otherwise literal text. **Declare state before you bind it** — compilation is line-based, top to bottom, so a `{ x }` or `:if x` must come *after* the `:state x` (or the `:form into x`) that creates it.
 
+The page's frontmatter is in scope as `meta`: `{ meta.title }` prints a field, `{ meta.tags }` joins an array with `, `, and `@loop meta.tags into tag` iterates a frontmatter array (build-time, stays static). Frontmatter arrays are inline only — `tags: [a, b, "x, y"]`; a value without a leading `[` is a plain string.
+
 ## Directives — the complete set (nothing else exists)
 
 ### State and buttons

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.8.0 — 2026-06-14
+
+- **Array frontmatter + readable `meta`.** Frontmatter now parses inline flow arrays — `tags: [sales, revenue, "q1, q2"]` becomes a real array (previously the literal string `"[sales, revenue]"`), with quoted items keeping their internal commas and bracket-free values staying plain scalars. Block sequences (`- item` lines) remain out of scope to keep the parser single-pass.
+- A page's frontmatter is now in scope in its body as `meta`: `{ meta.title }` prints a field, `{ meta.tags }` renders an array joined with `, `, and `@loop meta.tags into tag` iterates a frontmatter array at build time (stays `runtime: false`, zero-JS).
+- A correctness fix in its own right, and the groundwork for reading/emitting bundles in Google Cloud's Open Knowledge Format (markdown + `type`-bearing frontmatter + cross-links). OKF support, if pursued, will be a thin additive export — deliberately not coupled to its v0.1 Draft.
+
 ## 0.7.0 — 2026-06-13
 
 - **Per-row actions in reactive loops.** A `:button` inside `@loop … into item` can now act on its own row — the canonical add-to-cart / remove-line / delete-todo pattern, with no hand-written JavaScript:

package/README.md

@@ -54,8 +54,24 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 
 - In-scope static values (include arguments, loop values) resolve at build time.
 - Declared `:state` becomes a live binding.
+- The page's own frontmatter is in scope as `meta` — `{ meta.title }` prints a field.
 - Anything else stays literal text — braces in prose never break a page or pull in the runtime.
 
+## Frontmatter
+
+YAML-style `key: value` frontmatter between `---` fences. Values are strings, plus inline arrays:
+
+```wd
+---
+title: Customers
+tags: [sales, revenue, "q1, q2"]
+---
+```
+
+- `{ meta.title }` prints a scalar; `{ meta.tags }` prints an array joined with `, `.
+- `@loop meta.tags into tag` iterates an array field at build time (stays static, zero-JS).
+- Arrays are inline flow only (`[a, b]`); quoted items keep internal commas (`"q1, q2"`). A value without a leading `[` stays a plain string.
+
 ## Loops
 
 `@loop <things> into <thing>` is the only loop. The source decides the behavior:

package/docs/okf-integration.md

@@ -0,0 +1,120 @@
+# OKF integration — plan & options
+
+Status: **parked / decision pending** (2026-06-14). Research-verified; revisit when
+we decide how far to take it. v0.8.0 (array frontmatter + readable `meta`) already
+shipped the enabling groundwork.
+
+## What OKF is (verified)
+
+**Open Knowledge Format (OKF)** is real. Published **2026-06-12** by the Google Cloud
+Data Analytics team (Sam McVeety, Amir Hormati).
+
+- Announcement: <https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/>
+- Spec: <https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>
+- Repo (Apache-2.0, `okf/` subdir): <https://github.com/GoogleCloudPlatform/knowledge-catalog>
+- **Not** the Open Knowledge Foundation (unrelated nonprofit — do not conflate).
+
+It is a **file format**, not a service: a directory of markdown "concept" files for
+feeding organizational knowledge to AI agents. Each concept file has YAML frontmatter
+where **`type` is the only required field**; `title`, `description`, `resource` (a URI
+for the underlying asset), `tags` (a YAML list), and `timestamp` (ISO 8601) are
+optional. Producers may add arbitrary keys; consumers must preserve unknown keys.
+
+- **Cross-links** are ordinary markdown links between concept files (bundle-relative
+  absolute like `/tables/customers.md` recommended). They are treated as **directed,
+  untyped graph edges** — the relationship's meaning lives in surrounding prose.
+- **Reserved files:** `index.md` (a directory listing for *progressive disclosure* — an
+  agent navigates one level at a time) and `log.md` (chronological history). The root
+  `index.md` frontmatter may declare `okf_version: "0.1"`.
+- **Conformance is permissive:** consumers MUST tolerate broken links, unknown `type`
+  values, unknown keys, and missing optional fields (so agent-generated, partial bundles
+  still work).
+- **Reference tooling (both labeled proof-of-concept):** a BigQuery *enrichment agent*
+  that drafts OKF docs per table, and a *visualizer* — a `visualize` command that emits a
+  single self-contained interactive HTML file (Cytoscape.js force-graph + marked.js body,
+  no backend).
+- **Sample bundles:** GA4 e-commerce, Stack Overflow, Bitcoin. ("BigQuery Table /
+  Dataset / Metric" are concept *types inside* bundles, not separate samples.)
+
+## Why it's interesting for Darkmown
+
+OKF's entire surface — YAML frontmatter + a folder tree + relative markdown links →
+static HTML — **is what Darkmown already does**. A `.md` tree with a `type:` field and
+cross-links is *nearly an OKF bundle by accident*. Two directions:
+
+1. **Darkmown as an OKF renderer.** Darkmown renders markdown bundles to static, zero-JS
+   HTML — directly competitive with OKF's reference visualizer, which is OKF's weakest
+   surface (a single JS-heavy HTML file).
+2. **Every Darkmown site emits an OKF bundle.** Any docs/content site also becomes
+   machine-readable agent context. No other markdown framework offers this.
+
+## Why to be cautious
+
+- **v0.1 "Draft," explicitly evolving.** Google's own blog: "a starting point, not a
+  finished standard." Field names and required fields may change (minor versions promise
+  backward-compatible additions only; breaking changes need a major bump).
+- **Thin traction.** ~1.2k GitHub stars but ~8 issues, ~13 PRs, ~27 commits at launch.
+  **No third-party adopters** — only Google's own Cloud Knowledge Catalog consumes it.
+- **Governance unclear.** Lives under Google's repo with no foundation/working group.
+- **Thin convention.** Net-new over "a markdown vault + Obsidian/Dataview" is small: one
+  required field, two reserved filenames, link-as-edge semantics. Easy for others to
+  ignore or fork.
+
+## Decision (Kirby, 2026-06-14)
+
+**Support OKF naturally; do not tie ourselves to it.** Treat it as a cheap, additive
+interop convention, not a strategic bet or a core-model change.
+
+## Options (revisit later)
+
+### Option A — Do nothing more (status quo)
+v0.8.0 array frontmatter already makes Darkmown frontmatter able to carry `tags` lists
+and a `type` field. A Darkmown content tree with `type:` in frontmatter is already
+~conformant. Cost: zero. Keep tracking adoption.
+
+### Option B — Thin OKF emit (recommended first step if we act) — increment #3
+A flag-gated export from a built site: `okf: true` in config or `--emit-okf`.
+- During `buildSite` (`src/builder.js`), alongside `routes.json`, write `dist/okf/`.
+- For each page, emit an OKF doc: frontmatter (`type` defaulting to `page`, `title` from
+  meta, `tags` from meta, `timestamp` from file mtime/git) + the page's markdown body.
+- Derive edges from internal links + `@include` edges (`resolveInclude`/`compileFile`
+  already know these). Emit per-directory `index.md` for progressive disclosure.
+- **Map at emit time** — do not restructure Darkmown's internal model around OKF.
+- Effort: low; it hooks the existing route loop. Largely free.
+
+### Option C — OKF render mode ("best OKF renderer") — increment #2
+`darkmown build --okf ./bundle [--out dist-okf]`: walk an arbitrary bundle root, render
+each doc (type-aware templates, generic fallback), rewrite `.md` cross-links to routes,
+emit a static index/graph view. Reuse `parseFrontmatter`, markdown-it, `compileFile` —
+do not fork the pipeline. Must stay `runtime: false`.
+- **Gate this on OKF showing real external adoption.** Today you'd build a renderer for a
+  format only Google uses. Higher effort, higher coupling risk.
+
+### Sequencing if we proceed
+1. (done) Array frontmatter + readable `meta` — v0.8.0.
+2. Option B (emit) — additive, low-regret.
+3. Option C (render) — only if the format gets stickier.
+
+## Hard "avoid" list
+
+- Don't hardcode Google/BigQuery `type` vocabularies (`BigQuery Table`, etc.) — `type` is
+  uncentralized and producer-defined.
+- Don't bet on v0.1 field names / required-field stability — map our frontmatter → OKF at
+  emit time.
+- Don't depend on OKF's reference enrichment agent or visualizer — both are proofs of
+  concept. If we want a graph view, build our own; the format is trivial.
+- Don't market "OKF-native" as a moat — it's a thin convention with thin adoption. A
+  cheap interoperability checkbox, not a strategic bet.
+
+## Invariants to respect (if/when we build)
+
+- `.md` never gains directive behavior; OKF docs are content, rendered as content.
+- No eval of bundle content; the `constructor`/`prototype`/`__proto__` rejection in
+  `getPath` still applies.
+- OKF render/emit are pure content transforms — `runtime: false` always.
+- Compile/render errors include the offending file path and a corrective suggestion.
+
+## Source
+
+Full research briefing (cited): the research-investigator memory
+`reference_okf_open_knowledge_format.md`, and `docs/spec-alignment.md` Stage 7.

package/docs/spec-alignment.md

@@ -56,6 +56,10 @@ This audit compares the current Darkmown implementation with the original MARROW
 - **Editor tooling:** VS Code extension (`editors/vscode`) ships `.wd` + `.skin` TextMate grammars, snippets, and folding, grammar-tested in CI.
 - **`AGENTS.md`:** a model-facing build guide (shipped in the npm files array), tuned over a 5-round agent-eval benchmark that lifted build quality from 2.78→4.51/5.
 
+## Stage 7 additions (2026-06-14)
+
+- **Array frontmatter + readable `meta`:** `parseFrontmatter` now parses inline flow arrays (`tags: [a, b, "x, y"]` → real array; quoted items keep internal commas; a value without a leading `[` stays a scalar — block sequences are intentionally out of scope to keep the parser single-pass). A page's frontmatter is exposed to its body under `meta`, so `{ meta.title }` prints a field, `{ meta.tags }` renders an array joined with `, `, and `@loop meta.tags into tag` iterates a frontmatter array at build time (stays `runtime: false`). Genuine correctness fix on its own, and the groundwork for reading/emitting OKF-style bundles (Google Cloud's Open Knowledge Format — markdown + `type`-bearing frontmatter + cross-links; tracked but deliberately not coupled to its v0.1 Draft).
+
 ## Still missing from the full vision
 
 - First-party server runtime (`site/api/`), HTML-fragment `swap` semantics, and cart server sync — parked behind the adapter decision until a real project needs them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/site/pages/docs/index.wd

@@ -109,8 +109,22 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 
 - If the name is a static value in scope (include argument, loop value), it is resolved at build time.
 - If the name is declared `:state`, it becomes a live binding.
+- The page's frontmatter is in scope as `meta` — `{ meta.title }` prints a field.
 - Otherwise the text is left exactly as written — braces in prose never break a page or pull in the runtime.
 
+## Frontmatter
+
+Frontmatter sits between `---` fences. Values are strings, plus inline arrays:
+
+```wd
+---
+title: Customers
+tags: [sales, revenue, "q1, q2"]
+---
+```
+
+`{ meta.title }` prints a scalar and `{ meta.tags }` joins an array with `, `. You can loop a frontmatter array at build time — `@loop meta.tags into tag` — and the page stays static. Arrays are inline flow only (`[a, b]`); quoted items keep their commas.
+
 ## Sections
 
 `::: section #id .class` opens a container and `:::` closes it. Sections scope state: a `:state` declared inside a section belongs to that section, so two sections can both declare `count` without colliding. Bindings and buttons resolve to the nearest scope.

package/src/compiler.js

@@ -82,7 +82,9 @@ function compileFile(file, context, stack, scope, comp, sections, loopItem) {
     return { meta, html: md.render(body, {}) };
   }
 
-  const ctx = { file, context, stack: [...stack, real], scope, comp, sections, loopItem };
+  // Expose this file's frontmatter to the body under `meta` so `{ meta.title }`,
+  // `{ meta.tags }`, and `@loop meta.tags into tag` resolve as static values.
+  const ctx = { file, context, stack: [...stack, real], scope: createScope(scope, { meta }), comp, sections, loopItem };
   return { meta, html: compileBody(body.replace(/\r\n?/g, "\n").split("\n"), ctx) };
 }
 
@@ -95,11 +97,49 @@ export function parseFrontmatter(raw) {
   const meta = {};
   for (const line of front.split("\n")) {
     const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (match) meta[match[1]] = stripQuotes(match[2]);
+    if (match) meta[match[1]] = parseFrontmatterValue(match[2]);
   }
   return { meta, body };
 }
 
+// Frontmatter values are scalars, except an inline flow array `[a, b, c]`.
+// Block sequences (`- item` on following lines) are intentionally out of scope —
+// the parser stays single-pass and line-based.
+function parseFrontmatterValue(raw) {
+  const value = raw.trim();
+  if (value.startsWith("[") && value.endsWith("]")) return parseInlineArray(value);
+  return stripQuotes(value);
+}
+
+function parseInlineArray(raw) {
+  const inner = raw.slice(1, -1);
+  if (inner.trim() === "") return [];
+  const items = [];
+  let buf = "";
+  let quote = null;
+  let quoted = false;
+  const push = () => {
+    items.push(quoted ? buf : buf.trim());
+    buf = "";
+    quoted = false;
+  };
+  for (const char of inner) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else buf += char;
+    } else if ((char === '"' || char === "'") && buf.trim() === "") {
+      quote = char;
+      quoted = true;
+    } else if (char === ",") {
+      push();
+    } else {
+      buf += char;
+    }
+  }
+  push();
+  return items;
+}
+
 // ---------------------------------------------------------------------------
 // Block parser: directives + prose segments
 // ---------------------------------------------------------------------------
@@ -868,7 +908,9 @@ function resolveBindingHtml(expr, ctx) {
 
   const staticValue = lookupVar(ctx.scope, head);
   if (staticValue.found) {
-    return escapeHtml(getPath(staticValue.value, segs.slice(1)) ?? "");
+    const resolved = getPath(staticValue.value, segs.slice(1));
+    if (Array.isArray(resolved)) return escapeHtml(resolved.join(", "));
+    return escapeHtml(resolved ?? "");
   }
 
   const key = resolveStateKey(head, ctx);