jmd-format 0.0.1 → 0.1.1

package/README.md

@@ -2,9 +2,9 @@
 
 **JMD (JSON Markdown) — JavaScript reference implementation.**
 
-JMD is a structured data format for LLM-driven infrastructure, designed to work
-*with* the natural generation behavior of large language models rather than
-against it. See the [JMD specification](https://github.com/ostermeyer/jmd-spec)
+JMD is a structured data format for LLM-driven infrastructure, designed to
+work *with* the natural generation behavior of large language models rather
+than against it. See the [JMD specification](https://github.com/ostermeyer/jmd-spec)
 for the format itself.
 
 This package is the JavaScript reference implementation. A Python reference
@@ -12,11 +12,118 @@ implementation exists as the `jmd-format` package on PyPI.
 
 ## Status
 
-**Work in progress — 0.0.x placeholder.** The package name is reserved; the
-implementation is under active design. Expect no functional code before 0.1.0.
+**Byte-compatible with the Python reference.** The core syntax (all four
+document modes, nested objects, arrays of scalars / objects /
+sub-arrays, multiline blockquotes, frontmatter, thematic breaks)
+produces output identical to `jmd-format` on PyPI for the same input
+value and label — verified by a 10 000-case randomized
+cross-implementation stress test.
 
-Follow [github.com/ostermeyer/jmd-js](https://github.com/ostermeyer/jmd-js) for
-updates.
+Schema-specific type expressions (§14) and QBE filter conditions (§13)
+are still parsed as raw strings on both sides; structured interpretation
+will follow.
+
+## Install
+
+```
+npm install jmd-format
+```
+
+Node 20+ required. Pure ESM, no transpilation, no dependencies.
+
+## Usage
+
+### Batch
+
+```js
+import { parse, serialize } from 'jmd-format'
+
+const { mode, label, frontmatter, value } = parse(text)
+const out = serialize({ id: 42, status: 'pending' }, 'Order')
+```
+
+Frontmatter and alternate root modes are expressed at the call site:
+
+```js
+serialize(value, '? Order', { page: 1, 'page-size': 50 })  // query mode
+serialize(value, '! Order')                                 // schema mode
+serialize(value, '- Order')                                 // delete mode
+```
+
+### Streaming
+
+The parser and serializer both have streaming surfaces — async generator
+for input, sync generator for output. Events follow the sequence from
+spec §18.2.
+
+```js
+import { createParser, toLines, serializeLines } from 'jmd-format'
+
+// Parse a stream of arbitrary text chunks (e.g. an HTTP response body).
+const parser = createParser()
+for await (const event of parser.events(toLines(response.body))) {
+  // event: { type: 'field', key: 'id', value: 42 }
+  // event: { type: 'object_start', key: 'address' }
+  // event: { type: 'document_end' }
+}
+
+// Serialize line by line.
+for (const line of serializeLines(value, 'Orders')) {
+  res.write(line)  // each line includes its trailing newline
+}
+```
+
+`toLines(source)` is the adapter that turns an async iterable of arbitrary
+string chunks into an async iterable of complete lines.
+
+## Currently supported
+
+- All four document modes (`#`, `#!`, `#?`, `#-`): parsing recognizes the
+  mode and extracts the label; the body parses as standard JMD.
+- Scalars: `null`, `true`, `false`, numbers, bare and quoted strings.
+- Nested objects via heading depth.
+- Arrays of scalars and of objects (with indented continuation fields).
+- Sub-arrays and arrays of arrays (`### []`, §8.4).
+- Blockquote multiline strings (§9.1).
+- Frontmatter (§3.5): both `key: value` and bare-key forms.
+- Deferred blank-line scope reset (§7.2a) — a blank followed by a
+  deeper heading re-enters the nested scope; a blank followed by a bare
+  field triggers the reset. Matches the Python reference behavior.
+- Scalar headings for scope return (`## total: 84.99`, §7.2).
+- Anonymous headings (§3.2a).
+- Thematic breaks (`---`) as array-item separators (§8.6). Consumed by
+  the innermost enclosing array whose most-recent item is a dict with
+  nested structures.
+- Depth-qualified array items (`##N -`, §8.6a) and depth+1 items
+  (`##N - key: val`, §8.6b). Parser-tolerance forms: the canonical
+  serializer emits bare `- ` items with thematic-break separators, but
+  the parser accepts the depth-annotated forms that LLMs tend to
+  produce when items sit one heading level below the array heading.
+- **Streaming parser** via async generator: events match the sequence
+  defined in §18.2 (document_start, field, field_start, field_content,
+  object_start/end, array_start/end, item_start/value/end, scope_reset,
+  document_end, frontmatter).
+- **Streaming serializer** via sync generator (`serializeLines`).
+- Line adapter (`toLines`) to convert chunked input to lines.
+
+## Not yet structured
+
+Schema-specific type expressions (§14) and QBE filter conditions (§13)
+are parsed as raw strings on both this implementation and the Python
+reference. Structured interpretation will follow in a later release.
+
+## Design
+
+JavaScript-native throughout:
+
+- Functions and closures, not classes. No `new`, no `this`.
+- Plain objects as data carriers.
+- ESM only; no build step.
+- No external dependencies.
+- Zero Node-specific APIs in the core — runs in the browser unchanged.
+
+The implementation is strict on the generator side and tolerant on the
+parser side, following §22.1 of the specification.
 
 ## License
 

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "jmd-format",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "JMD (JSON Markdown) — structured data format for LLM-driven infrastructure. JavaScript reference implementation.",
   "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
   "author": {
     "name": "Andreas Ostermeyer",
     "email": "andreas@ostermeyer.de"
@@ -28,7 +32,11 @@
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "files": [
+    "src/",
     "README.md",
     "LICENSE"
   ]

package/src/index.js

@@ -0,0 +1,7 @@
+// jmd-format — JavaScript reference implementation.
+//
+// Public surface: minimal on purpose. Batch API for the common case,
+// streaming API for large or incremental workloads.
+
+export { parse, createParser, toLines } from './parser.js'
+export { serialize, serializeLines } from './serializer.js'

package/src/parser.js

@@ -0,0 +1,501 @@
+// JMD parser.
+//
+// The parser processes a JMD document line by line, maintaining a scope
+// stack driven by heading depth. It has two surfaces:
+//
+//   - parse(text)          — batch. Returns { mode, label, frontmatter, value }.
+//   - events(lineSource)   — streaming. Async generator of parse events.
+//
+// Both share the same line-processing core. Events follow the sequence
+// defined in JMD spec §18.2. Parser-tolerant per §22.1.
+
+import { parseScalar, parseKey, parseField } from './value.js'
+
+const HEADING = /^(#+)([!?-])?(?:\s+(.*))?$/
+
+export function createParser() {
+  let lineNo = 0
+
+  // Document-level state.
+  let mode = null
+  let label = null
+  const frontmatter = {}
+  let inFrontmatter = true
+  let seenRoot = false
+  let root = null
+
+  // Scope stack. Each entry:
+  //   { kind: 'object' | 'array', container, depth, currentItem? }
+  // currentItem lives on array scopes only and holds the object built by
+  // the most recent `- ` line so indented continuations attach to it.
+  let stack = []
+
+  // Pending blockquote state.
+  //   { container, key, lines }
+  let bq = null
+
+  // A blank line may or may not terminate the current scope — it depends on
+  // what comes after. We defer the decision: flag the blank, then let the
+  // next real line resolve it. A deeper heading re-enters (no reset); a bare
+  // field at the root indicates a scope return (full reset); a `---` inside
+  // an array is a thematic break (item separator, §8.6).
+  let blankPending = false
+
+  // Events emitted by the current line — drained on each processLine call.
+  let pending = []
+  function emit(type, data) {
+    pending.push(data ? { type, ...data } : { type })
+  }
+  function drain() {
+    const out = pending
+    pending = []
+    return out
+  }
+
+  // --- Line processing -----------------------------------------------------
+
+  function processLine(rawLine) {
+    lineNo++
+    const line = rawLine.replace(/\r$/, '')
+
+    if (bq !== null) {
+      if (line === '>' || line.startsWith('> ')) {
+        const content = line === '>' ? '' : line.slice(2)
+        bq.lines.push(content)
+        emit('field_content', { text: content })
+        return drain()
+      }
+      commitBlockquote()
+    }
+
+    if (/^\s*$/.test(line)) { blankPending = true; return drain() }
+
+    const h = HEADING.exec(line)
+    if (h) {
+      // A heading stands on its own authority — its depth drives scope.
+      blankPending = false
+      onHeading(h[1].length, h[2] || '', h[3] || '')
+      return drain()
+    }
+
+    if (inFrontmatter) { onFrontmatter(line); return drain() }
+
+    if (/^\s{2,}/.test(line)) {
+      blankPending = false
+      onIndented(line)
+      return drain()
+    }
+
+    // Thematic break: `---` (or more) at column 0, only meaningful inside
+    // an array scope, where it terminates the current item.
+    if (/^-{3,}$/.test(line)) {
+      onThematicBreak()
+      return drain()
+    }
+
+    if (line === '-' || line.startsWith('- ')) {
+      if (blankPending) applyBlankReset()
+      onItem(line)
+      return drain()
+    }
+
+    if (blankPending) applyBlankReset()
+    onField(line)
+    return drain()
+  }
+
+  function applyBlankReset() {
+    blankPending = false
+    if (stack.length <= 1) return
+    emit('scope_reset')
+    while (stack.length > 1) popScope()
+    if (stack[0] && stack[0].kind === 'array') closeItem(stack[0])
+  }
+
+  function onThematicBreak() {
+    blankPending = false
+    // A thematic break is consumed by the innermost enclosing array whose
+    // most-recent item is a dict containing nested structures — this is
+    // the only context where jmd-format emits the break, and the parser
+    // mirrors that rule (spec §8.6). Inner scopes are closed; if no array
+    // on the stack qualifies, the line is tolerated as decoration.
+    let targetIdx = -1
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const s = stack[i]
+      if (s.kind !== 'array') continue
+      const last = s.container[s.container.length - 1]
+      if (last && typeof last === 'object' && !Array.isArray(last)
+          && Object.values(last).some(
+            v => v !== null && typeof v === 'object')) {
+        targetIdx = i
+        break
+      }
+    }
+    if (targetIdx === -1) return
+    while (stack.length - 1 > targetIdx) popScope()
+    closeItem(stack[targetIdx])
+  }
+
+  // --- Blockquote ----------------------------------------------------------
+
+  function startBlockquote(container, key) {
+    bq = { container, key, lines: [] }
+    emit('field_start', { key })
+  }
+
+  function commitBlockquote() {
+    bq.container[bq.key] = bq.lines.join('\n')
+    bq = null
+  }
+
+  // --- Root / frontmatter --------------------------------------------------
+
+  function onFrontmatter(line) {
+    const f = parseField(line)
+    if (f) {
+      const v = f.empty ? true : f.value
+      frontmatter[f.key] = v
+      emit('frontmatter', { key: f.key, value: v })
+      return
+    }
+    const pk = parseKey(line)
+    if (pk && pk.rest === '') {
+      frontmatter[pk.key] = true
+      emit('frontmatter', { key: pk.key, value: true })
+      return
+    }
+    throw parseError('Unexpected line before root heading')
+  }
+
+  function openRoot(modeMark, text) {
+    inFrontmatter = false
+    seenRoot = true
+
+    if (modeMark === '!') mode = 'schema'
+    else if (modeMark === '?') mode = 'query'
+    else if (modeMark === '-') mode = 'delete'
+    else mode = 'data'
+
+    if (text === '[]') {
+      label = '[]'
+      root = []
+      stack = [{ kind: 'array', container: root, depth: 1, currentItem: null }]
+    } else if (text.endsWith('[]')) {
+      label = text.slice(0, -2)
+      root = []
+      stack = [{ kind: 'array', container: root, depth: 1, currentItem: null }]
+    } else {
+      label = text
+      root = {}
+      stack = [{ kind: 'object', container: root, depth: 1 }]
+    }
+    emit('document_start', { mode, label })
+  }
+
+  // --- Headings ------------------------------------------------------------
+
+  function onHeading(depth, modeMark, text) {
+    if (!seenRoot) {
+      if (depth !== 1) {
+        throw parseError('Document must begin with a depth-1 heading')
+      }
+      openRoot(modeMark, text)
+      return
+    }
+    if (modeMark) {
+      throw parseError('Mode markers (!, ?, -) are only valid on the root heading')
+    }
+
+    // Depth-qualified array item (§8.6a) or depth+1 item (§8.6b):
+    // `##N -` or `##N - key: val` starts a new item in an enclosing array.
+    // Resolution prefers the innermost array at depth N; failing that, an
+    // array at depth N-1 (the LLM-natural "items under the heading" form).
+    if (text === '-' || text.startsWith('- ')) {
+      onDepthQualifiedItem(depth, text)
+      return
+    }
+
+    popToDepth(depth)
+
+    if (text === '' || text === undefined) {
+      openObjectScope(depth, '')
+      return
+    }
+
+    // Anonymous sub-array: `### []` — handled below with the other array forms.
+    if (text === '[]') {
+      openSubArray(depth)
+      return
+    }
+
+    if (text.endsWith('[]')) {
+      const keyText = text.slice(0, -2)
+      const pk = parseKey(keyText)
+      if (!pk || pk.rest !== '') throw parseError('Malformed array heading key')
+      openArrayScope(depth, pk.key)
+      return
+    }
+
+    const field = parseField(text)
+    if (field && !field.empty) {
+      const parent = parentObjectAt(depth)
+      parent[field.key] = field.value
+      emit('field', { key: field.key, value: field.value })
+      return
+    }
+
+    if (field && field.empty) {
+      const parent = parentObjectAt(depth)
+      startBlockquote(parent, field.key)
+      return
+    }
+
+    const pk = parseKey(text)
+    if (pk && pk.rest === '') {
+      openObjectScope(depth, pk.key)
+      return
+    }
+
+    throw parseError('Malformed heading')
+  }
+
+  function openObjectScope(depth, key) {
+    const parent = parentObjectAt(depth)
+    const obj = {}
+    parent[key] = obj
+    stack.push({ kind: 'object', container: obj, depth })
+    emit('object_start', { key })
+  }
+
+  function openArrayScope(depth, key) {
+    const parent = parentObjectAt(depth)
+    const arr = []
+    parent[key] = arr
+    stack.push({ kind: 'array', container: arr, depth, currentItem: null })
+    emit('array_start', { key })
+  }
+
+  function openSubArray(depth) {
+    // `### []`: start a new anonymous array as the next item of the
+    // enclosing array scope.
+    const top = stack[stack.length - 1]
+    if (!top || top.kind !== 'array') {
+      throw parseError('Anonymous sub-array outside array scope')
+    }
+    closeItem(top)
+    const inner = []
+    top.container.push(inner)
+    stack.push({ kind: 'array', container: inner, depth, currentItem: null })
+    emit('array_start', {})
+  }
+
+  function parentObjectAt(depth) {
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const s = stack[i]
+      if (s.depth < depth) {
+        if (s.kind === 'object') return s.container
+        if (s.kind === 'array' && s.currentItem) return s.currentItem
+        throw parseError('Field has no enclosing object scope')
+      }
+    }
+    throw parseError('No enclosing scope for depth ' + depth)
+  }
+
+  function popToDepth(targetDepth) {
+    while (stack.length > 1 && stack[stack.length - 1].depth >= targetDepth) {
+      popScope()
+    }
+  }
+
+  function popScope() {
+    const s = stack.pop()
+    if (s.kind === 'array') {
+      closeItem(s)
+      emit('array_end', s.depth === 1 ? {} : { key: keyOfScope(s) })
+    } else {
+      emit('object_end', { key: keyOfScope(s) })
+    }
+  }
+
+  function closeItem(arrayScope) {
+    if (arrayScope.currentItem !== null) {
+      emit('item_end')
+      arrayScope.currentItem = null
+    }
+  }
+
+  // The parent container holds the scope's container under a known key;
+  // look it up once so end events can name what closed.
+  function keyOfScope(scope) {
+    // Walk the stack below; find the container that holds scope.container.
+    // Micro-inefficient but runs once per pop — fine for now.
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const parent = stack[i]
+      const bag = parent.kind === 'array' && parent.currentItem
+        ? parent.currentItem
+        : parent.container
+      for (const k of Object.keys(bag)) {
+        if (bag[k] === scope.container) return k
+      }
+    }
+    return undefined
+  }
+
+  // --- Bare fields ---------------------------------------------------------
+
+  function onField(line) {
+    const f = parseField(line)
+    if (!f) throw parseError('Malformed field line')
+    const top = stack[stack.length - 1]
+    const target = top.kind === 'object'
+      ? top.container
+      : (top.currentItem || throwHere('Bare field inside array scope without an item'))
+    if (f.empty) {
+      startBlockquote(target, f.key)
+      return
+    }
+    target[f.key] = f.value
+    emit('field', { key: f.key, value: f.value })
+  }
+
+  // --- Array items ---------------------------------------------------------
+
+  function onDepthQualifiedItem(headingDepth, text) {
+    // Find target: innermost array at depth == headingDepth wins (§8.6a).
+    // Else fall back to array at depth == headingDepth - 1 (§8.6b — the
+    // LLM-natural pattern of writing items one heading-level under the
+    // array heading).
+    let sameDepthIdx = -1
+    let parentDepthIdx = -1
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const s = stack[i]
+      if (s.kind !== 'array') continue
+      if (sameDepthIdx === -1 && s.depth === headingDepth) sameDepthIdx = i
+      if (parentDepthIdx === -1 && s.depth === headingDepth - 1) {
+        parentDepthIdx = i
+      }
+    }
+    const targetIdx = sameDepthIdx !== -1 ? sameDepthIdx : parentDepthIdx
+    if (targetIdx === -1) {
+      throw parseError('Depth-qualified item has no matching array scope')
+    }
+    // Close any scopes nested inside the target array.
+    while (stack.length - 1 > targetIdx) popScope()
+    // Reuse the regular item handler with the target array on top.
+    onItem(text)
+  }
+
+  function onItem(line) {
+    const top = stack[stack.length - 1]
+    if (top.kind !== 'array') throw parseError('Array item outside array scope')
+
+    closeItem(top)
+    const rest = line === '-' ? '' : line.slice(2)
+
+    if (rest === '') {
+      const item = {}
+      top.container.push(item)
+      top.currentItem = item
+      emit('item_start')
+      return
+    }
+
+    const f = parseField(rest)
+    if (f) {
+      const item = {}
+      top.container.push(item)
+      top.currentItem = item
+      emit('item_start')
+      if (f.empty) {
+        startBlockquote(item, f.key)
+      } else {
+        item[f.key] = f.value
+        emit('field', { key: f.key, value: f.value })
+      }
+      return
+    }
+
+    const value = parseScalar(rest)
+    top.container.push(value)
+    top.currentItem = null
+    emit('item_value', { value })
+  }
+
+  function onIndented(line) {
+    const content = line.replace(/^\s+/, '')
+    const top = stack[stack.length - 1]
+    if (top.kind !== 'array' || !top.currentItem) {
+      throw parseError('Indented continuation without an active array item')
+    }
+    const f = parseField(content)
+    if (!f) throw parseError('Malformed indented continuation')
+    if (f.empty) {
+      startBlockquote(top.currentItem, f.key)
+      return
+    }
+    top.currentItem[f.key] = f.value
+    emit('field', { key: f.key, value: f.value })
+  }
+
+  // --- Finalization --------------------------------------------------------
+
+  function finish() {
+    if (bq !== null) commitBlockquote()
+    if (!seenRoot) {
+      throw parseError('Document contained no root heading')
+    }
+    while (stack.length > 0) popScope()
+    emit('document_end')
+    return drain()
+  }
+
+  // --- Errors --------------------------------------------------------------
+
+  function parseError(msg) {
+    const err = new Error(msg + ' (line ' + lineNo + ')')
+    err.line = lineNo
+    return err
+  }
+  function throwHere(msg) { throw parseError(msg) }
+
+  // --- Public surface ------------------------------------------------------
+
+  function parse(text) {
+    // A trailing newline is a line terminator, not a blank line — drop
+    // any empty final element from the split.
+    const lines = text.split('\n')
+    if (lines.length && lines[lines.length - 1] === '') lines.pop()
+    for (const line of lines) processLine(line)
+    finish()
+    return { mode, label, frontmatter, value: root }
+  }
+
+  async function* events(source) {
+    for await (const line of source) {
+      for (const ev of processLine(line)) yield ev
+    }
+    for (const ev of finish()) yield ev
+  }
+
+  return { processLine, finish, parse, events }
+}
+
+export function parse(text) {
+  return createParser().parse(text)
+}
+
+// Line adapter: turn an async iterable of arbitrary string chunks (e.g. a
+// fetch response body stream) into an async iterable of lines. Trailing
+// `\r` is stripped; the final line is emitted even if unterminated.
+export async function* toLines(source) {
+  let buffer = ''
+  for await (const chunk of source) {
+    buffer += typeof chunk === 'string' ? chunk : String(chunk)
+    let idx
+    while ((idx = buffer.indexOf('\n')) !== -1) {
+      yield buffer.slice(0, idx).replace(/\r$/, '')
+      buffer = buffer.slice(idx + 1)
+    }
+  }
+  if (buffer !== '') yield buffer.replace(/\r$/, '')
+}

package/src/serializer.js

@@ -0,0 +1,180 @@
+// JMD serializer.
+//
+// Two surfaces over one implementation:
+//
+//   - serializeLines(value, label, frontmatter)  — generator of lines with
+//                                                  trailing newlines. Suitable
+//                                                  for streaming to a transport.
+//   - serialize(value, label, frontmatter)       — returns the full document
+//                                                  as a single string (no
+//                                                  trailing newline), matching
+//                                                  the byte form emitted by
+//                                                  the jmd-format Python
+//                                                  reference implementation.
+//
+// Generator-strict per §22.1: output matches the canonical form that a
+// conforming parser accepts without tolerance.
+
+import { serializeScalar, serializeKey } from './value.js'
+
+export function serialize(value, label = 'Document', frontmatter = null) {
+  const lines = []
+  emitDocument(value, label, frontmatter, lines)
+  return lines.join('\n')
+}
+
+export function* serializeLines(value, label = 'Document', frontmatter = null) {
+  const lines = []
+  emitDocument(value, label, frontmatter, lines)
+  for (const ln of lines) yield ln + '\n'
+}
+
+function emitDocument(value, label, frontmatter, lines) {
+  if (frontmatter && Object.keys(frontmatter).length > 0) {
+    for (const [k, v] of Object.entries(frontmatter)) {
+      if (v === true) lines.push(serializeKey(k))
+      else lines.push(serializeKey(k) + ': ' + serializeScalar(v))
+    }
+    lines.push('')
+  }
+
+  if (Array.isArray(value)) {
+    const head = label === '[]' ? '# []' : '# ' + label + '[]'
+    lines.push(head)
+    writeArrayItems(value, lines, 1)
+  } else if (value !== null && typeof value === 'object') {
+    lines.push('# ' + label)
+    writeObjectFields(value, lines, 1)
+  } else {
+    throw new TypeError('Root value must be an object or array')
+  }
+}
+
+function heading(depth) {
+  return '#'.repeat(depth) + ' '
+}
+
+function writeMultiline(value, lines) {
+  for (const part of value.split('\n')) {
+    lines.push(part === '' ? '>' : '> ' + part)
+  }
+}
+
+function writeObjectFields(obj, lines, depth) {
+  let needsHeading = false
+  for (const [key, value] of Object.entries(obj)) {
+    const k = serializeKey(key)
+    if (isPlainObject(value)) {
+      lines.push('')
+      lines.push(heading(depth + 1) + k)
+      writeObjectFields(value, lines, depth + 1)
+      needsHeading = true
+    } else if (Array.isArray(value)) {
+      lines.push('')
+      lines.push(heading(depth + 1) + k + '[]')
+      writeArrayItems(value, lines, depth + 1)
+      needsHeading = true
+    } else if (typeof value === 'string' && value.includes('\n')) {
+      lines.push((needsHeading ? heading(depth + 1) : '') + k + ':')
+      writeMultiline(value, lines)
+      needsHeading = true
+    } else if (needsHeading) {
+      lines.push(heading(depth + 1) + k + ': ' + serializeScalar(value))
+    } else {
+      lines.push(k + ': ' + serializeScalar(value))
+    }
+  }
+}
+
+function writeArrayItems(lst, lines, depth) {
+  if (lst.length === 0) return
+
+  const allLists = lst.every(i => Array.isArray(i))
+  const allDicts = lst.every(isPlainObject)
+  const allScalars = lst.every(i => !isNested(i))
+
+  if (allLists) {
+    for (const item of lst) {
+      lines.push(heading(depth + 1) + '[]')
+      writeArrayItems(item, lines, depth + 1)
+    }
+    return
+  }
+
+  if (allDicts) {
+    const hasNested = lst.some(item =>
+      Object.values(item).some(isNested))
+    for (let i = 0; i < lst.length; i++) {
+      writeDictItem(lst[i], lines, depth, i > 0 && hasNested)
+    }
+    return
+  }
+
+  if (allScalars) {
+    for (const item of lst) {
+      lines.push('- ' + serializeScalar(item))
+    }
+    return
+  }
+
+  // Heterogeneous array.
+  //
+  // The C-accelerated Python reference does not insert thematic breaks
+  // inside a heterogeneous array — items simply follow one another. We
+  // match that form byte-for-byte.
+  for (const item of lst) {
+    if (isPlainObject(item)) {
+      writeDictItem(item, lines, depth, false)
+    } else if (Array.isArray(item)) {
+      lines.push(heading(depth + 1) + '[]')
+      writeArrayItems(item, lines, depth + 1)
+    } else {
+      lines.push('- ' + serializeScalar(item))
+    }
+  }
+}
+
+function writeDictItem(item, lines, depth, separatorNeeded) {
+  const scalarFields = []
+  const nestedFields = []
+  for (const [k, v] of Object.entries(item)) {
+    if (isNested(v)) nestedFields.push([k, v])
+    else scalarFields.push([k, v])
+  }
+
+  if (separatorNeeded) {
+    // Match the C-accelerated Python serializer (the default in jmd-format):
+    // blank line before the `---`, but the next `- ` follows immediately on
+    // the next line — no blank after the thematic break.
+    lines.push('')
+    lines.push('---')
+  }
+
+  if (scalarFields.length === 0) {
+    lines.push('-')
+  } else {
+    let first = true
+    for (const [k, v] of scalarFields) {
+      const sv = serializeScalar(v)
+      const qk = serializeKey(k)
+      if (first) {
+        lines.push('- ' + qk + ': ' + sv)
+        first = false
+      } else {
+        lines.push('  ' + qk + ': ' + sv)
+      }
+    }
+  }
+
+  if (nestedFields.length > 0) {
+    writeObjectFields(Object.fromEntries(nestedFields), lines, depth)
+  }
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}
+
+function isNested(v) {
+  return v !== null && typeof v === 'object'
+}

package/src/value.js

@@ -0,0 +1,106 @@
+// Scalar values and keys.
+//
+// Parsing and serialization of the smallest JMD units: scalar values
+// (null, booleans, numbers, strings) and field keys. These helpers are
+// used by both parser and serializer, and stay at the character level —
+// line structure and scope are handled one layer up.
+
+const NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/
+const BARE_KEY = /^[A-Za-z0-9_-]+/
+
+// Parse the text that appears after `key: ` into a JS value.
+// §2.1: bare values are tried as null, true, false, number; otherwise string.
+export function parseScalar(raw) {
+  if (raw === '') return ''
+  if (raw === 'null') return null
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  if (NUMBER.test(raw)) return Number(raw)
+  if (raw.charCodeAt(0) === 34 /* " */) {
+    // Quoted string — JSON semantics for escapes (§5, RFC 8259).
+    return JSON.parse(raw)
+  }
+  return raw
+}
+
+// Serialize a scalar for use as a field value.
+// §6.1: quote strings that would otherwise be misread (as type or structure).
+export function serializeScalar(value) {
+  if (value === null) return 'null'
+  if (value === true) return 'true'
+  if (value === false) return 'false'
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError('Cannot serialize non-finite number: ' + value)
+    }
+    return String(value)
+  }
+  if (typeof value === 'string') {
+    return needsQuoting(value) ? JSON.stringify(value) : value
+  }
+  throw new TypeError('Cannot serialize scalar of type ' + typeof value)
+}
+
+function needsQuoting(s) {
+  // Quoting rules matching the jmd-format Python reference:
+  //   - empty string, ambiguous scalars, and numbers ⇒ always quote
+  //   - structural prefixes (`# `, `- `) ⇒ quote
+  //   - strings starting with `"` ⇒ quote (otherwise ambiguous with quoted form)
+  //   - strings containing newline or tab ⇒ quote (JSON-escape line structure)
+  //   - internal quotes and backslashes are left bare — the parser is
+  //     tolerant enough to accept them, and Python's serializer does the same.
+  if (s === '') return true
+  if (s === 'null' || s === 'true' || s === 'false') return true
+  if (NUMBER.test(s)) return true
+  if (s === '-') return true
+  if (s.startsWith('# ') || s.startsWith('- ')) return true
+  if (s.charCodeAt(0) === 34 /* " */) return true
+  if (/[\n\t]/.test(s)) return true
+  return false
+}
+
+// Parse a bare or quoted key from the start of a string.
+// Returns { key, rest } or null if no key is present.
+export function parseKey(str) {
+  if (str.charCodeAt(0) === 34 /* " */) {
+    let i = 1
+    while (i < str.length) {
+      const c = str.charCodeAt(i)
+      if (c === 92 /* \ */) { i += 2; continue }
+      if (c === 34 /* " */) {
+        const key = JSON.parse(str.slice(0, i + 1))
+        return { key, rest: str.slice(i + 1) }
+      }
+      i++
+    }
+    return null
+  }
+  const m = BARE_KEY.exec(str)
+  if (!m) return null
+  return { key: m[0], rest: str.slice(m[0].length) }
+}
+
+// Serialize a key — bare if the character class permits, quoted otherwise.
+export function serializeKey(key) {
+  if (typeof key !== 'string') {
+    throw new TypeError('Key must be a string, got ' + typeof key)
+  }
+  if (key.length > 0 && /^[A-Za-z0-9_-]+$/.test(key)) return key
+  return JSON.stringify(key)
+}
+
+// Parse `key: value` or `key:` (empty value).
+// Returns { key, value } or { key, empty: true } or null.
+export function parseField(line) {
+  const pk = parseKey(line)
+  if (!pk) return null
+  const rest = pk.rest
+  if (rest.length === 0) return null
+  if (rest.charCodeAt(0) !== 58 /* : */) return null
+  const after = rest.slice(1)
+  if (after === '' || /^\s*$/.test(after)) {
+    return { key: pk.key, empty: true }
+  }
+  if (after.charCodeAt(0) !== 32 /* space */) return null
+  return { key: pk.key, value: parseScalar(after.slice(1)) }
+}