@jarenjs/md 0.56.0 → 0.67.0

package/README.md

@@ -139,7 +139,9 @@ mdToVnode(doc, { headingIds: true, slugPrefix: 'user-content-' });
 
 Repeated headings are numbered the way GitHub numbers them (`setup`,
 `setup-1`, `setup-2`), and a heading with no slug-worthy text (`## ***`)
-lands on `section`. Ids are **off by default on purpose**: CommonMark
+lands on `section`. Numbered ids are reserved too: headings `Foo`, `Foo`,
+`Foo-1` receive `foo`, `foo-1`, `foo-1-1`, so every permalink remains unique.
+Ids are **off by default on purpose**: CommonMark
 renders a heading as `<h1>Foo</h1>`, so emitting one by default would put
 the conformance score below at odds with what the package produces. The
 rules are normative in [MD-FORMAT.md](docs/MD-FORMAT.md) §4.5; the slug
@@ -315,7 +317,9 @@ createApp(appDoc, {
 - A document whose frontmatter declares a schema (`form:` or `$schema`)
   feeds [`@jarenjs/forms`](../../packages/forms) through `mdToForm(doc, forms)` —
   `{ schema, fields, data }`, with the forms module injected so this
-  package stays dependency-free.
+  package stays dependency-free. When frontmatter omits `data`, the built
+  form model supplies schema defaults and `const` values; explicit data,
+  including `null`, is preserved.
 - In an [`@jarenjs/app`](../../packages/app) document, a view can be a JSLT
   stylesheet over a loaded MdDocument: register `loadMarkdown` as an
   async effect that dispatches the plain `MdDocument` into the state,
@@ -537,6 +541,25 @@ Measured, not claimed — `npm run benchmark:markdown`, <!--fact:md.measured-->2
   tag's attributes — is normalized away on every engine's output, not
   just this one's.
 
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.md-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/md` | JavaScript | declared |
+| `@jarenjs/md/plugins` | JavaScript | declared |
+| `@jarenjs/md/html` | JavaScript | declared |
+| `@jarenjs/md/mdx` | JavaScript | declared |
+| `@jarenjs/md/directives` | JavaScript | declared |
+| `@jarenjs/md/component` | JavaScript | declared |
+| `@jarenjs/md/styles/md.css` | asset | — |
+| `@jarenjs/md/schemas/jaren-md-ast.schema.json` | schema | — |
+| `@jarenjs/md/package.json` | metadata | — |
+<!--/fact-->
+
 ## Development
 
 Tests live in the repository root: [`test/md/`](../../test/md)

package/dist/types/compiler.d.ts

@@ -128,12 +128,12 @@ export declare function frontmatterExternals(frontmatter: any): Record<string, a
  *
  * @param {MdDocument} doc
  * @param {{ buildFormModel: (schema: any) => any,
- *           createInitialData: (schema: any) => any }} forms
+ *           createInitialData: (fields: any) => any }} forms
  * @returns {{ schema: any, fields: any, data: any } | null}
  */
 export declare function mdToForm(doc: MdDocument, forms: {
     buildFormModel: (schema: any) => any;
-    createInitialData: (schema: any) => any;
+    createInitialData: (fields: any) => any;
 }): {
     schema: any;
     fields: any;

package/dist/types/loader.d.ts

@@ -3,7 +3,7 @@
  *
  * `loadMarkdown` resolves any URL the platform `fetch` accepts into a
  * compiled document. The shared LRU cache keys on normalized URL +
- * plugin set, remembers `ETag`/`Last-Modified` validators, shares
+ * compile options, remembers `ETag`/`Last-Modified` validators, shares
  * in-flight fetches, and revalidates stale entries in the background.
  * When the response body is a `ReadableStream` the parser runs
  * block-by-block as chunks arrive — `streamMarkdown` exposes that as

package/dist/types/utils.d.ts

@@ -20,8 +20,10 @@ export { hashContent, fnv1a, FNV1A_OFFSET_BASIS, slugify } from '@jarenjs/core/s
  *
  * Both emitters mint ids, so the rule lives here once: slug the text,
  * substitute `section` when nothing slug-worthy survives, number
- * repeats the way GitHub numbers them (`setup`, `setup-1`, `setup-2`)
- * and prefix the result. The COUNTER belongs to the caller — one map per
+ * repeats the way GitHub numbers them (`setup`, `setup-1`, `setup-2`),
+ * reserving every emitted slug so a literal `setup-1` cannot collide
+ * with a numbered `setup`, and prefix the result. The COUNTER belongs
+ * to the caller — one map per
  * emission, never shared with another numbering (a block key's hash and
  * a slug share a namespace only by accident, and a collision there would
  * shift an unrelated heading's number).

package/docs/LOADER.md

@@ -32,14 +32,23 @@ remembers the response's `ETag` and `Last-Modified`; a cache hit
 resolves immediately with the cached compiled document, and a
 revalidating fetch (`If-None-Match`/`If-Modified-Since`) only replaces
 the entry when the origin answers with new content (`200` with a
-different validator). Entries also key on the compile-relevant options
-(plugin names), so the same URL compiled with different plugin sets
-does not alias.
+different validator). Entries also key on every compile-relevant option:
+GFM and frontmatter parsing, source retention, HTML handling, heading and
+footnote policies, and vnode keys. Plugins and the injected TOML/URL
+callbacks key by identity, so equally named plugins with different
+implementations never alias. Treat plugin objects and callbacks as
+immutable for the lifetime of a compiled document.
 
 - `createMdCache(limit = 64)` — an LRU cache instance; the default
   shared instance is exported as `defaultMdCache`.
 - `cache: false` — bypass entirely.
-- `cache.delete(url)` / `cache.clear()` — manual invalidation.
+- `cache.delete(url)` — invalidate the normalized URL's default-options
+  entry; `cache.clear()` invalidates every entry, including option variants.
+
+Invalidation also revokes a pending load or background revalidation's
+right to update that entry. Its original caller still receives its
+response, but an older completion cannot restore a cleared entry,
+overwrite a newer document, or evict a newer load on failure.
 
 Concurrent `loadMarkdown` calls for the same key share one in-flight
 fetch (the promise itself is cached), so a burst of loads costs one

package/docs/MD-FORMAT.md

@@ -101,11 +101,15 @@ The built-in parser handles, from scratch and dependency-free:
   `yes`/`no`, sexagesimals, hex ints and timestamps — is a **string**.
 - **Quoted strings** — double quotes with JSON-style escapes
   (`\n \t \r \b \f \0 \\ \" \uXXXX`), single quotes with `''` → `'`.
+  An opening quote requires a closing quote; an unterminated string is
+  a located frontmatter error.
 - **Block maps and sequences** by indentation (spaces only). A sequence
   MAY sit at the same indent as its parent key. `- key: value` opens an
   inline map item.
 - **Flow collections** — `[a, b]` and `{a: 1}`, nesting freely, spanning
-  multiple lines while brackets remain open.
+  multiple lines while brackets remain open. Plain values retain internal
+  colons (`[a:b]`, `{url: http://host}`); shorthand map entries inside
+  sequences (`[a: b]`) are outside the subset and are rejected.
 - **Block scalars** — literal `|` and folded `>`, each with the `-`
   chomp (drop the final newline). The `+` chomp and explicit indent
   indicators are not supported.
@@ -133,7 +137,10 @@ with dotted paths, bare/quoted/dotted keys, basic and literal strings,
 integers (decimal/hex/octal/binary with `_`), floats, booleans, flow
 arrays (multi-line), inline tables and comments. Datetimes and any other
 unrecognized value are kept as verbatim **strings**; multi-line strings
-are not supported.
+are not supported. Comments end at each physical line, including within
+multi-line arrays. Dotted keys in an inline table preserve sibling
+members, and table names such as `__proto__` are ordinary own properties.
+An unterminated quoted string is a located frontmatter error.
 
 ### 3.4 Frontmatter as ambient variables
 
@@ -288,8 +295,9 @@ GitHub, in an editor preview and in this renderer:
 The result MAY be empty (`## ***`); an emitter MUST then substitute
 `section`, because a heading with no landing place cannot be linked.
 Within one document, the **second** heading yielding a given identifier
-MUST get `-1` appended, the third `-2`, and so on, counted over the
-substituted value so `***` twice yields `section` and `section-1`. The
+MUST get `-1` appended, the third `-2`, and so on, skipping any identifier
+already emitted (including numbered identifiers from another heading).
+Count over the substituted value so `***` twice yields `section` and `section-1`. The
 counter is per emission and MUST NOT be shared with any other numbering
 in the emitter.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/md",
   "private": false,
-  "version": "0.56.0",
+  "version": "0.67.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -73,8 +73,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.56.0",
-    "@jarenjs/mermaid": "^0.56.0",
-    "@jarenjs/view": "^0.56.0"
+    "@jarenjs/core": "^0.67.0",
+    "@jarenjs/mermaid": "^0.67.0",
+    "@jarenjs/view": "^0.67.0"
   }
 }

package/src/compiler.js

@@ -152,7 +152,7 @@ export function frontmatterExternals(frontmatter) {
  *
  * @param {MdDocument} doc
  * @param {{ buildFormModel: (schema: any) => any,
- *           createInitialData: (schema: any) => any }} forms
+ *           createInitialData: (fields: any) => any }} forms
  * @returns {{ schema: any, fields: any, data: any } | null}
  */
 export function mdToForm(doc, forms) {
@@ -162,6 +162,7 @@ export function mdToForm(doc, forms) {
     ? fm.form
     : typeof fm.$schema === 'object' && fm.$schema !== null ? fm.$schema : null;
   if (schema === null) return null;
-  const data = fm.data !== undefined ? fm.data : forms.createInitialData(schema);
-  return { schema, fields: forms.buildFormModel(schema), data };
+  const fields = forms.buildFormModel(schema);
+  const data = fm.data !== undefined ? fm.data : forms.createInitialData(fields);
+  return { schema, fields, data };
 }

package/src/frontmatter.js

@@ -403,7 +403,7 @@ function splitYamlKey(line, indent, lineNo) {
   if (key.length > 1) {
     const q = key.charCodeAt(0);
     if ((q === 0x22 || q === 0x27) && key.charCodeAt(key.length - 1) === q) {
-      key = String(parseQuoted(key, 0, /** @type {'"'|"'"} */ (key[0])).value);
+      key = String(parseQuoted(key, 0, /** @type {'"'|"'"} */ (key[0]), lineNo).value);
     }
   }
   let restColumn = indent + colon + 1;
@@ -462,7 +462,7 @@ function parseYamlFlowOrScalar(state, rest, lineNo) {
     const flow = parseFlowValue(text, 0, lineNo);
     return flow.value;
   }
-  return parseYamlScalar(stripComment(rest));
+  return parseYamlScalar(stripComment(rest), lineNo);
 }
 
 /**
@@ -509,13 +509,14 @@ function stripComment(text) {
 /**
  * Parse a scalar: quoted string, null, boolean, number, or plain string.
  * @param {string} text trimmed scalar text
+ * @param {number} lineNo
  * @returns {any}
  */
-function parseYamlScalar(text) {
+function parseYamlScalar(text, lineNo) {
   if (text === '') return null;
   const c0 = text.charCodeAt(0);
   if (c0 === 0x22 || c0 === 0x27) {
-    return parseQuoted(text, 0, /** @type {'"'|"'"} */ (text[0])).value;
+    return parseQuoted(text, 0, /** @type {'"'|"'"} */ (text[0]), lineNo).value;
   }
   switch (text) {
     case 'null': case 'Null': case 'NULL': case '~': return null;
@@ -533,9 +534,10 @@ function parseYamlScalar(text) {
  * @param {string} text
  * @param {number} pos
  * @param {'"'|"'"} quote
+ * @param {number} lineNo
  * @returns {{ value: string, end: number }}
  */
-function parseQuoted(text, pos, quote) {
+function parseQuoted(text, pos, quote, lineNo) {
   let out = '';
   let i = pos + 1;
   while (i < text.length) {
@@ -569,7 +571,7 @@ function parseQuoted(text, pos, quote) {
     out += ch;
     i++;
   }
-  return { value: out, end: i };
+  throw new MdFrontmatterError('unterminated quoted string', lineNo);
 }
 
 /**
@@ -578,26 +580,29 @@ function parseQuoted(text, pos, quote) {
  * @param {string} text
  * @param {number} pos
  * @param {number} lineNo
+ * @param {boolean} [key=false] whether a colon ends a map key
  * @returns {{ value: any, end: number }}
  */
-function parseFlowValue(text, pos, lineNo) {
+function parseFlowValue(text, pos, lineNo, key = false) {
   while (pos < text.length && text.charCodeAt(pos) === 0x20) pos++;
   const c = text.charCodeAt(pos);
   if (c === 0x5B /* [ */) return parseFlowSeq(text, pos, lineNo);
   if (c === 0x7B /* { */) return parseFlowMap(text, pos, lineNo);
   if (c === 0x22 || c === 0x27) {
-    return parseQuoted(text, pos, /** @type {'"'|"'"} */ (text[pos]));
+    return parseQuoted(text, pos, /** @type {'"'|"'"} */ (text[pos]), lineNo);
   }
   let end = pos;
   let depth = 0;
   while (end < text.length) {
     const cc = text.charCodeAt(end);
-    if (depth === 0 && (cc === 0x2C || cc === 0x5D || cc === 0x7D || cc === 0x3A)) break;
+    if (depth === 0 && (cc === 0x2C || cc === 0x5D || cc === 0x7D)) break;
+    if (depth === 0 && cc === 0x3A
+      && (key || end + 1 === text.length || /[\s,[\]{}]/.test(text[end + 1]))) break;
     if (cc === 0x5B || cc === 0x7B) depth++;
     else if (cc === 0x5D || cc === 0x7D) depth--;
     end++;
   }
-  return { value: parseYamlScalar(text.slice(pos, end).trim()), end };
+  return { value: parseYamlScalar(text.slice(pos, end).trim(), lineNo), end };
 }
 
 /**
@@ -620,6 +625,7 @@ function parseFlowArray(text, pos, lineNo, parseItem, unterminated) {
     if (i >= text.length) throw new MdFrontmatterError(unterminated, lineNo);
     if (text.charCodeAt(i) === 0x5D /* ] */) return { value: out, end: i + 1 };
     const item = parseItem(text, i, lineNo);
+    if (item.end <= i) throw new MdFrontmatterError('expected a flow array item', lineNo);
     out.push(item.value);
     i = item.end;
   }
@@ -651,7 +657,7 @@ function parseFlowMap(text, pos, lineNo) {
     while (i < text.length && (text.charCodeAt(i) === 0x20 || text.charCodeAt(i) === 0x2C)) i++;
     if (i >= text.length) throw new MdFrontmatterError('unterminated flow map', lineNo);
     if (text.charCodeAt(i) === 0x7D /* } */) return { value: out, end: i + 1 };
-    const key = parseFlowValue(text, i, lineNo);
+    const key = parseFlowValue(text, i, lineNo, true);
     i = key.end;
     while (i < text.length && text.charCodeAt(i) === 0x20) i++;
     if (text.charCodeAt(i) !== 0x3A /* : */) {
@@ -699,16 +705,15 @@ export function parseTomlSubset(text) {
     const eq = findTomlEquals(line);
     if (eq === -1) throw new MdFrontmatterError(`expected 'key = value', got '${line}'`, no);
     const path = parseTomlKeyPath(line.slice(0, eq), no);
-    let valueText = line.slice(eq + 1).trim();
-    // Multi-line flow arrays / inline tables: join lines while open.
-    while (flowDepth(stripTomlComment(valueText)) > 0 && no + 1 < lines.length) {
-      valueText += ' ' + lines[++no].trim();
+    let valueText = stripTomlComment(line.slice(eq + 1)).trim();
+    // Comments end at each physical line, before continuation lines join.
+    while (flowDepth(valueText) > 0 && no + 1 < lines.length) {
+      valueText += ' ' + stripTomlComment(lines[++no]).trim();
     }
-    valueText = stripTomlComment(valueText).trim();
     let target = table;
     for (let i = 0; i < path.length - 1; i++) {
       const step = path[i];
-      if (!(step in target) || typeof target[step] !== 'object') {
+      if (!Object.hasOwn(target, step) || typeof target[step] !== 'object') {
         const next = {};
         setObjectMember(target, step, next);
         target = next;
@@ -772,7 +777,7 @@ function parseTomlKeyPath(text, no) {
     while (i < text.length && text.charCodeAt(i) === 0x20) i++;
     const c = text.charCodeAt(i);
     if (c === 0x22 || c === 0x27) {
-      const q = parseQuoted(text, i, /** @type {'"'|"'"} */ (text[i]));
+      const q = parseQuoted(text, i, /** @type {'"'|"'"} */ (text[i]), no);
       out.push(q.value);
       i = q.end;
     }
@@ -812,7 +817,7 @@ function descendTomlTable(root, path, isArray, no) {
   let target = root;
   for (let i = 0; i < path.length - 1; i++) {
     const step = path[i];
-    let next = target[step];
+    let next = Object.hasOwn(target, step) ? target[step] : undefined;
     if (next === undefined) {
       next = {};
       setObjectMember(target, step, next);
@@ -827,7 +832,7 @@ function descendTomlTable(root, path, isArray, no) {
   }
   const leaf = path[path.length - 1];
   if (isArray) {
-    let arr = target[leaf];
+    let arr = Object.hasOwn(target, leaf) ? target[leaf] : undefined;
     if (arr === undefined) {
       arr = [];
       setObjectMember(target, leaf, arr);
@@ -837,7 +842,7 @@ function descendTomlTable(root, path, isArray, no) {
     arr.push(fresh);
     return fresh;
   }
-  let next = target[leaf];
+  let next = Object.hasOwn(target, leaf) ? target[leaf] : undefined;
   if (next === undefined) {
     next = {};
     setObjectMember(target, leaf, next);
@@ -861,7 +866,7 @@ function parseTomlValue(text, no) {
   if (text === '') throw new MdFrontmatterError('missing value', no);
   const c0 = text.charCodeAt(0);
   if (c0 === 0x22 || c0 === 0x27) {
-    return parseQuoted(text, 0, /** @type {'"'|"'"} */ (text[0])).value;
+    return parseQuoted(text, 0, /** @type {'"'|"'"} */ (text[0]), no).value;
   }
   if (c0 === 0x5B /* [ */) return parseTomlArray(text, no).value;
   if (c0 === 0x7B /* { */) return parseTomlInline(text, no).value;
@@ -907,8 +912,14 @@ function parseTomlInline(text, no) {
     const item = parseTomlItem(text, end + 1, no);
     let target = out;
     for (let p = 0; p < path.length - 1; p++) {
-      const next = {};
-      setObjectMember(target, path[p], next);
+      const step = path[p];
+      let next = Object.hasOwn(target, step) ? target[step] : undefined;
+      if (next === undefined) {
+        next = {};
+        setObjectMember(target, step, next);
+      }
+      if (next === null || typeof next !== 'object' || Array.isArray(next))
+        throw new MdFrontmatterError(`'${step}' is not a table`, no);
       target = next;
     }
     setObjectMember(target, path[path.length - 1], item.value);
@@ -935,7 +946,7 @@ function parseTomlItem(text, pos, no) {
     return { value: inner.value, end: pos + inner.end };
   }
   if (c === 0x22 || c === 0x27) {
-    return parseQuoted(text, pos, /** @type {'"'|"'"} */ (text[pos]));
+    return parseQuoted(text, pos, /** @type {'"'|"'"} */ (text[pos]), no);
   }
   let end = pos;
   while (end < text.length) {

package/src/utils.js

@@ -25,8 +25,10 @@ export { hashContent, fnv1a, FNV1A_OFFSET_BASIS, slugify } from '@jarenjs/core/s
  *
  * Both emitters mint ids, so the rule lives here once: slug the text,
  * substitute `section` when nothing slug-worthy survives, number
- * repeats the way GitHub numbers them (`setup`, `setup-1`, `setup-2`)
- * and prefix the result. The COUNTER belongs to the caller — one map per
+ * repeats the way GitHub numbers them (`setup`, `setup-1`, `setup-2`),
+ * reserving every emitted slug so a literal `setup-1` cannot collide
+ * with a numbered `setup`, and prefix the result. The COUNTER belongs
+ * to the caller — one map per
  * emission, never shared with another numbering (a block key's hash and
  * a slug share a namespace only by accident, and a collision there would
  * shift an unrelated heading's number).
@@ -38,9 +40,12 @@ export { hashContent, fnv1a, FNV1A_OFFSET_BASIS, slugify } from '@jarenjs/core/s
  */
 export function headingId(text, seen, prefix) {
   const base = slugify(text) || 'section';
-  const count = seen.get(base) ?? 0;
+  let count = seen.get(base) ?? 0;
+  let slug = count === 0 ? base : base + '-' + count;
+  while (seen.has(slug)) slug = base + '-' + ++count;
   seen.set(base, count + 1);
-  return prefix + (count === 0 ? base : base + '-' + count);
+  if (slug !== base) seen.set(slug, 1);
+  return prefix + slug;
 }
 
 /**