@brett_lamy/docstream 1.8.0 → 1.9.0

package/src/docs/DocumentProperties.tsx

@@ -0,0 +1,84 @@
+import { useEffect, useState } from "react"
+import { ChevronRight, Plus, X } from "lucide-react"
+import { parseDocument, stringify } from "yaml"
+import type { DocumentPropertiesNode } from "../gitbook/ast"
+import { readDocumentProperties, removeDocumentProperty, setDocumentProperty, type DocumentPropertyValue } from "../gitbook/properties"
+
+export interface DocumentPropertiesProps {
+  properties: DocumentPropertiesNode
+  /** Omit for read-only properties. Edits retain the YAML document's comments and formatting. */
+  onChange?: (properties: DocumentPropertiesNode) => void
+  defaultOpen?: boolean
+  className?: string
+}
+
+function textValue(value: DocumentPropertyValue): string {
+  return value === null ? "" : typeof value === "object" ? stringify(value).trimEnd() : String(value)
+}
+
+function PropertyField({ name, value, onChange }: { name: string; value: DocumentPropertyValue; onChange: (value: DocumentPropertyValue) => void }) {
+  const rendered = textValue(value)
+  const [draft, setDraft] = useState(rendered)
+  const [error, setError] = useState<string>()
+  useEffect(() => { setDraft(rendered); setError(undefined) }, [rendered])
+  if (typeof value === "boolean") return <input type="checkbox" aria-label={name} checked={value} onChange={(event) => onChange(event.currentTarget.checked)} />
+  const complex = value !== null && typeof value === "object"
+  const multiline = complex || (typeof value === "string" && value.includes("\n"))
+  const change = (text: string) => {
+    setDraft(text)
+    if (!complex && typeof value !== "number") onChange(text)
+    else if (typeof value === "number" && text !== "" && Number.isFinite(Number(text))) onChange(Number(text))
+  }
+  const commit = () => {
+    if (!complex) return
+    try {
+      const yaml = parseDocument(draft)
+      if (yaml.errors.length) throw yaml.errors[0]
+      const next = yaml.toJS({ maxAliasCount: 100 }) as DocumentPropertyValue
+      JSON.stringify(next)
+      setError(undefined)
+      onChange(next)
+    } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+  }
+  return <div className="docs-property-field">
+    {multiline ? <textarea aria-label={name} value={draft} rows={Math.min(6, draft.split("\n").length)} aria-invalid={!!error || undefined}
+      onChange={(event) => change(event.currentTarget.value)} onBlur={commit} />
+      : <input type={typeof value === "number" ? "number" : "text"} aria-label={name} value={draft} placeholder="Empty"
+        onChange={(event) => change(event.currentTarget.value)} />}
+    {error ? <span role="alert" className="docs-properties-error">{error}</span> : null}
+  </div>
+}
+
+/** The shared, accessible property sheet used by the renderer and the editor. */
+export function DocumentProperties({ properties, onChange, defaultOpen = false, className }: DocumentPropertiesProps) {
+  const { values, error } = readDocumentProperties(properties)
+  const [adding, setAdding] = useState(false)
+  const [name, setName] = useState("")
+  const keys = Object.keys(values)
+  return <details className={["docs-document-properties", className].filter(Boolean).join(" ")} data-document-properties="" open={defaultOpen || undefined}>
+    <summary><ChevronRight size={13} aria-hidden="true" /><span>Properties</span><span className="docs-properties-count">{keys.length}</span></summary>
+    {error ? <div className="docs-properties-error" role="alert">
+      <p>{error}</p>
+      {onChange ? <textarea aria-label="Document properties YAML" value={properties.yaml} onChange={(event) => onChange({ ...properties, yaml: event.currentTarget.value })} />
+        : <pre>{properties.yaml}</pre>}
+    </div> : <>
+      <dl className="docs-properties-list">
+        {keys.map((key) => <div key={key} className="docs-property-row">
+          <dt>{key}</dt>
+          <dd>{onChange ? <PropertyField name={key} value={values[key]} onChange={(value) => onChange(setDocumentProperty(properties, key, value))} />
+            : <span className="docs-property-value">{values[key] === null ? "Empty" : typeof values[key] === "boolean" ? String(values[key]) : textValue(values[key])}</span>}</dd>
+          {onChange ? <button type="button" className="docs-property-remove" aria-label={`Remove ${key} property`} onClick={() => onChange(removeDocumentProperty(properties, key))}><X size={13} /></button> : null}
+        </div>)}
+      </dl>
+      {onChange ? adding ? <form className="docs-property-add" onSubmit={(event) => {
+        event.preventDefault()
+        const key = name.trim()
+        if (!key || Object.hasOwn(values, key)) return
+        onChange(setDocumentProperty(properties, key, "")); setName(""); setAdding(false)
+      }}><input aria-label="Property name" placeholder="Property name" autoFocus value={name} onChange={(event) => setName(event.currentTarget.value)} />
+        <button type="submit" disabled={!name.trim() || Object.hasOwn(values, name.trim())}>Add</button>
+        <button type="button" onClick={() => { setAdding(false); setName("") }}>Cancel</button></form>
+        : <button type="button" className="docs-property-add" onClick={() => setAdding(true)}><Plus size={13} />Add property</button> : null}
+    </>}
+  </details>
+}

package/src/docs/TaskCheckbox.tsx

@@ -0,0 +1,111 @@
+import { createContext, useEffect, useId, useRef, useState, type CSSProperties } from "react"
+import { createPortal } from "react-dom"
+import { Ban, Check, Circle, CircleCheck, CircleHelp, CircleMinus, CirclePause, CircleX, Clock3 } from "lucide-react"
+import type { ListItemNode, TaskState } from "../gitbook/ast"
+import { TASK_STATES } from "../gitbook/tasks"
+
+/** The icons used by the checkbox, tooltip and state picker. */
+export const TASK_STATE_ICONS = {
+  pending: Circle,
+  "in-progress": Clock3,
+  implemented: CircleHelp,
+  blocked: Ban,
+  parked: CirclePause,
+  refuted: CircleX,
+  verified: CircleCheck,
+  cancelled: CircleMinus,
+} as const
+
+export type TaskStateChangeHandler = (item: ListItemNode, state: TaskState) => void
+export const TaskStateChangeContext = createContext<TaskStateChangeHandler | undefined>(undefined)
+
+export interface TaskCheckboxProps {
+  state: TaskState
+  /** A normal click clears any marked state; clicking pending sets verified. */
+  onChange?: (state: TaskState) => void
+  label?: string
+  className?: string
+}
+
+const TOKENS = ["--foreground", "--muted-foreground", "--popover", "--popover-foreground", "--border", "--primary", "--accent", "--accent-foreground"]
+
+/** An accessible multi-state task checkbox. Right-click or Shift+F10 opens its keyboard-navigable state menu. */
+export function TaskCheckbox({ state, onChange, label = "Task", className }: TaskCheckboxProps) {
+  const input = useRef<HTMLInputElement>(null)
+  const menu = useRef<HTMLDivElement>(null)
+  const tipId = useId()
+  const [popup, setPopup] = useState<{ x: number; y: number; style: CSSProperties }>()
+  const [tip, setTip] = useState<{ x: number; y: number }>()
+  const hoverTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const meta = TASK_STATES.find((item) => item.id === state) ?? TASK_STATES[0]
+  const StateIcon = TASK_STATE_ICONS[meta.id]
+  const mixed = state !== "pending" && state !== "verified"
+  useEffect(() => { if (input.current) input.current.indeterminate = mixed }, [mixed, state])
+  useEffect(() => () => clearTimeout(hoverTimer.current), [])
+  const hideTip = () => { clearTimeout(hoverTimer.current); setTip(undefined) }
+  const showTip = () => {
+    clearTimeout(hoverTimer.current)
+    hoverTimer.current = setTimeout(() => {
+      const box = input.current?.getBoundingClientRect()
+      if (box) setTip({ x: Math.max(80, Math.min(window.innerWidth - 80, box.x + box.width / 2)), y: box.top > 36 ? box.top - 6 : box.bottom + 30 })
+    }, 400)
+  }
+  const open = (x?: number, y?: number) => {
+    if (!onChange || !input.current) return
+    hideTip()
+    const box = input.current.getBoundingClientRect()
+    const computed = getComputedStyle(input.current)
+    const style = Object.fromEntries(TOKENS.map((token) => [token, computed.getPropertyValue(token)])) as CSSProperties
+    style.fontFamily = computed.fontFamily
+    style.colorScheme = computed.colorScheme
+    setPopup({ x: Math.max(8, Math.min(window.innerWidth - 292, x ?? box.left)), y: Math.max(8, Math.min(window.innerHeight - 330, y ?? box.bottom + 4)), style })
+  }
+  const close = (restoreFocus = false) => { setPopup(undefined); if (restoreFocus) input.current?.focus({ preventScroll: true }) }
+  useEffect(() => {
+    if (!popup) return
+    menu.current?.querySelector<HTMLButtonElement>(`[data-state="${state}"]`)?.focus()
+    const outside = (event: PointerEvent) => { if (event.target instanceof Node && !menu.current?.contains(event.target)) close() }
+    const scroll = (event: Event) => { if (!(event.target instanceof Node && menu.current?.contains(event.target))) close() }
+    document.addEventListener("pointerdown", outside, true)
+    window.addEventListener("resize", scroll)
+    window.addEventListener("scroll", scroll, true)
+    return () => { document.removeEventListener("pointerdown", outside, true); window.removeEventListener("resize", scroll); window.removeEventListener("scroll", scroll, true) }
+  }, [popup])
+  return <span className={["docs-task-control", className].filter(Boolean).join(" ")} data-task-state={state}>
+    <input ref={input} type="checkbox" className="docs-task-checkbox" aria-label={`${label}: ${meta.label}`} aria-describedby={tip ? tipId : undefined}
+      aria-checked={mixed ? "mixed" : state === "verified"} aria-readonly={!onChange || undefined} aria-haspopup={onChange ? "menu" : undefined}
+      aria-expanded={onChange ? !!popup : undefined} checked={state === "verified"} readOnly={!onChange}
+      onClick={(event) => { if (!onChange) event.preventDefault() }}
+      onChange={() => { hideTip(); onChange?.(state === "pending" ? "verified" : "pending") }}
+      onMouseDown={(event) => { if (event.button === 0) event.preventDefault() }}
+      onMouseEnter={showTip} onMouseLeave={hideTip} onFocus={showTip} onBlur={hideTip}
+      onContextMenu={(event) => { if (onChange) { event.preventDefault(); open(event.clientX, event.clientY) } }}
+      onKeyDown={(event) => {
+        if (event.key === "ContextMenu" || (event.shiftKey && event.key === "F10")) { event.preventDefault(); open() }
+      }} />
+    <StateIcon className="docs-task-state-icon" size={20} strokeWidth={1.7} aria-hidden="true" data-state-icon={state} />
+    {tip && !popup ? createPortal(<div role="tooltip" id={tipId} className="docs-task-tooltip" style={{ left: tip.x, top: tip.y }}>{meta.label}</div>, document.body) : null}
+    {popup ? createPortal(<div ref={menu} role="menu" aria-label="Task state" className="docs-task-state-menu" style={{ ...popup.style, left: popup.x, top: popup.y }}
+      onContextMenu={(event) => event.preventDefault()}
+      onKeyDown={(event) => {
+        const items = [...(menu.current?.querySelectorAll<HTMLButtonElement>('[role="menuitemradio"]') ?? [])]
+        const current = items.indexOf(document.activeElement as HTMLButtonElement)
+        let next: number | undefined
+        if (event.key === "ArrowDown") next = (current + 1) % items.length
+        if (event.key === "ArrowUp") next = (current - 1 + items.length) % items.length
+        if (event.key === "Home") next = 0
+        if (event.key === "End") next = items.length - 1
+        if (event.key === "Escape" || event.key === "Tab") { event.preventDefault(); close(true) }
+        if (next !== undefined) { event.preventDefault(); items[next]?.focus() }
+      }}>
+      {TASK_STATES.map((item) => {
+        const Icon = TASK_STATE_ICONS[item.id]
+        return <button type="button" role="menuitemradio" key={item.id} data-state={item.id} aria-checked={item.id === state}
+          onClick={() => { onChange?.(item.id); close(true) }}>
+          <Icon size={19} strokeWidth={1.7} aria-hidden="true" data-state-icon={item.id} />
+          <span>{item.label}</span>{item.id === state ? <Check size={14} aria-hidden="true" /> : <span />}
+        </button>
+      })}
+    </div>, document.body) : null}
+  </span>
+}

package/src/docs/properties.css

@@ -0,0 +1,28 @@
+.docs-document-properties {
+  color: var(--muted-foreground, #787878);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  margin-block: 0 20px;
+}
+.docs-document-properties > summary { display: flex; align-items: center; gap: 6px; width: fit-content; padding-block: 5px; cursor: pointer; list-style: none; user-select: none; }
+.docs-document-properties > summary::-webkit-details-marker { display: none; }
+.docs-document-properties[open] > summary > svg { transform: rotate(90deg); }
+.docs-properties-count { font-variant-numeric: tabular-nums; opacity: .65; margin-left: 2px; }
+.docs-properties-list { margin: 6px 0; }
+.docs-property-row { display: grid; grid-template-columns: minmax(80px, 130px) minmax(0, 1fr) 22px; align-items: start; gap: 10px; padding-block: 6px; border-bottom: 1px solid var(--border, #e8e8e8); }
+.docs-property-row dt { padding-block: 3px; overflow-wrap: anywhere; }
+.docs-property-row dd { margin: 0; min-width: 0; color: var(--foreground, #242424); }
+.docs-property-value { display: block; white-space: pre-wrap; overflow-wrap: anywhere; padding-block: 3px; }
+.docs-document-properties :is(input:not([type="checkbox"]), textarea) { box-sizing: border-box; width: 100%; min-width: 0; padding: 3px 5px; color: var(--foreground, #242424); font: inherit; line-height: inherit; background: transparent; border: 0; border-radius: 4px; }
+.docs-document-properties textarea { resize: vertical; }
+.docs-document-properties input[type="checkbox"] { accent-color: var(--primary, #a87900); margin: 6px 0; }
+.docs-document-properties :is(input, textarea, button, summary):focus-visible { outline: 2px solid var(--primary, #a87900); outline-offset: 2px; }
+.docs-document-properties button { display: inline-flex; align-items: center; justify-content: center; gap: 5px; color: inherit; background: transparent; border: 0; border-radius: 4px; font: inherit; cursor: pointer; }
+.docs-property-remove { padding: 6px 3px; opacity: 0; }
+.docs-property-row:hover .docs-property-remove, .docs-property-remove:focus-visible { opacity: 1; }
+.docs-property-add { display: flex; align-items: center; gap: 8px; margin-block: 8px 0; padding: 3px 0; }
+.docs-property-add input { max-width: 240px; }
+.docs-property-add button { padding: 3px 6px; }
+.docs-properties-error { color: var(--destructive, #bc3030); font-size: 12px; overflow-wrap: anywhere; }
+.docs-properties-error pre { white-space: pre-wrap; }

package/src/docs/tasks.css

@@ -0,0 +1,13 @@
+.docs-task-control { position: relative; display: inline-flex; width: 21px; height: 21px; flex: 0 0 21px; vertical-align: text-bottom; color: var(--muted-foreground, #7a7a7a); }
+.docs-task-control .docs-task-checkbox { position: absolute; inset: 0; box-sizing: border-box; appearance: none; margin: 0; width: 100%; height: 100%; padding: 0; border: 0; border-radius: 50%; background: transparent; cursor: pointer; box-shadow: none; }
+.docs-task-checkbox:focus-visible { outline: 2px solid var(--primary, #a87900); outline-offset: 3px; }
+.docs-task-state-icon { position: absolute; inset: 0; width: 100%; height: 100%; pointer-events: none; }
+.docs-task-control[data-task-state="verified"], .docs-task-control[data-task-state="in-progress"], .docs-task-control[data-task-state="implemented"] { color: var(--primary, #a87900); }
+.docs-task-control[data-task-state="blocked"], .docs-task-control[data-task-state="refuted"] { color: var(--destructive, #bd3d36); }
+.docs-task-state-menu { position: fixed; z-index: 10000; box-sizing: border-box; width: 284px; max-height: calc(100vh - 16px); overflow: auto; padding: 5px; border: 1px solid var(--border, #dedede); border-radius: 10px; background: var(--popover, #fff); color: var(--popover-foreground, #222); box-shadow: 0 8px 32px #0003, 0 1px 3px #0001; font-size: 13px; line-height: 1.4; }
+.docs-task-state-menu > button { display: grid; grid-template-columns: 20px minmax(0, 1fr) 14px; align-items: center; gap: 9px; width: 100%; min-height: 35px; padding: 7px 8px; border: 0; border-radius: 5px; color: inherit; background: transparent; font: inherit; text-align: left; cursor: pointer; outline: none; }
+.docs-task-state-menu > button:hover, .docs-task-state-menu > button:focus { color: var(--accent-foreground, #222); background: var(--accent, #eee); }
+.docs-task-state-menu > button > svg:first-child { color: var(--muted-foreground, #777); }
+.docs-task-state-menu > button[aria-checked="true"] > svg { color: var(--primary, #a87900); }
+.docs-task-tooltip { position: fixed; z-index: 10001; transform: translate(-50%, -100%); border-radius: 5px; padding: 4px 8px; color: #fff; background: #303030; box-shadow: 0 2px 8px #0002; font: 12px/1.4 system-ui, sans-serif; white-space: nowrap; pointer-events: none; }
+.docs-tasklist li > .docs-task-control { margin-top: 2px; }

package/src/gitbook/ast.ts

@@ -433,6 +433,8 @@ export interface ListItemNode extends ContainerSpacing {
   type: "listItem"
   children: Block[]
   checked?: boolean // present only in task lists
+  /** Extended task state. Omitted for ordinary `[ ]` / `[x]` items for backwards compatibility. */
+  state?: TaskState
   /** The item's marker as written (`*`, `3.`), when it isn't the one its list's pattern gives it. */
   marker?: string
   /** Spaces between the marker and the content (default 1). */
@@ -443,6 +445,8 @@ export interface ListItemNode extends ContainerSpacing {
   checkMark?: "X"
 }
 
+export type TaskState = "pending" | "in-progress" | "implemented" | "blocked" | "parked" | "refuted" | "verified" | "cancelled"
+
 export interface ListNode extends BlockSpacing {
   type: "list"
   ordered: boolean
@@ -563,9 +567,21 @@ export type Block =
   | DefinitionNode
   | RawNode
 
+/** YAML frontmatter, kept separately from the document body. Comments, key order and quoting survive edits. */
+export interface DocumentPropertiesNode {
+  /** YAML between the delimiters, using the document's normalized line endings. */
+  yaml: string
+  /** Opening delimiter as written (including an optional BOM). Defaults to `---`. */
+  opening?: string
+  /** Closing delimiter as written (`---` or `...`). Defaults to `---`. */
+  closing?: string
+}
+
 export interface DocumentNode {
   type: "doc"
   children: Block[]
+  /** First-party document properties from YAML frontmatter. */
+  properties?: DocumentPropertiesNode
   /** Footnote citation definitions, in definition order. */
   citations?: CitationDef[]
   /** Blank lines before the trailing footnote definitions (default 1). */

package/src/gitbook/index.ts

@@ -1,6 +1,9 @@
 // Pure GitBook markdown engine (no React, no mermaid/streamdown). Safe to import
 // in non-DOM environments such as a server-side AI agent or a Cloudflare Worker.
 export type * from "./ast"
+export { TASK_STATES, getTaskState, taskMarker, taskStateFromMarker } from "./tasks"
+export { readDocumentProperties, removeDocumentProperty, setDocumentProperty } from "./properties"
+export type { DocumentPropertyValue, ParsedDocumentProperties } from "./properties"
 export { escapeAttr, unescapeAttr } from "./attrs"
 export { closesFence, demoBody, fenceOpener, fenceTracker, parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./parse"
 export { fenceFor, serializeBlocks, serializeDemoFile, serializeMarkdown } from "./serialize"

package/src/gitbook/parse.ts

@@ -36,6 +36,7 @@ import type {
 import { TAG_ATTRS, parseAttrs } from "./attrs"
 import { containerTags, defaultDelimiterRow, definitionLine, delimiterAlign, fenceInfo, figureMarkdown, serializeBlocks, type TaggedNode } from "./serialize"
 import { footnoteDefinitions, normalizeLabel, parseInline, plainText, refDefinitions } from "./inline"
+import { taskStateFromMarker } from "./tasks"
 
 // Minimal HTML-inline → markdown-inline bridge for HTML table cells.
 function htmlToInlineMd(html: string): string {
@@ -256,7 +257,15 @@ export function footnoteLine(id: string, url: string, label?: string): string {
 export function parseMarkdown(src: string): DocumentNode {
   // Windows line endings throughout come back as such; mixed ones stay in the lines as written.
   const crlf = src.includes("\r\n") && !/(^|[^\r])\n/.test(src)
-  const lines = src.split(crlf || !src.includes("\r\n") ? /\r?\n/ : "\n")
+  let lines = src.split(crlf || !src.includes("\r\n") ? /\r?\n/ : "\n")
+  let properties: DocumentNode["properties"]
+  if (/^\uFEFF?---[ \t]*$/.test(lines[0])) {
+    const closing = lines.findIndex((line, index) => index > 0 && /^(?:---|\.\.\.)[ \t]*$/.test(line))
+    if (closing > 0) {
+      properties = { yaml: lines.slice(1, closing).join("\n"), opening: lines[0], closing: lines[closing] }
+      lines = lines.slice(closing + 1)
+    }
+  }
   refDefinitions.clear()
   footnoteDefinitions.clear()
   const fences = fenceTracker()
@@ -289,6 +298,7 @@ export function parseMarkdown(src: string): DocumentNode {
   const trailing = group <= last
   const { blocks, end } = parseBody(trailing ? lines.slice(0, group) : lines)
   const doc: DocumentNode = { type: "doc", children: blocks }
+  if (properties) doc.properties = properties
   if (footnoteDefinitions.size) {
     doc.citations = [...footnoteDefinitions.entries()].map(([id, d]) => ({ id, ...d }))
   }
@@ -1117,10 +1127,10 @@ function parseList(lines: string[], start: number): ParsedList {
     let content = m[4]
     let checked: boolean | undefined
     let checkMark: string | undefined
-    const taskMatch = content.match(/^\[([ xX])\]\s+(.*)$/)
+    const taskMatch = content.match(/^\[([ xX~?bd!\-])\]\s+(.*)$/)
     if (taskMatch) {
       list.task = true
-      checked = taskMatch[1] !== " "
+      checked = /[xX]/.test(taskMatch[1])
       checkMark = taskMatch[1]
       content = taskMatch[2]
     }
@@ -1158,6 +1168,8 @@ function parseList(lines: string[], start: number): ParsedList {
     const para: Block = { type: "paragraph", children: parseInline(content) }
     const children: Block[] = body.length ? [para, ...parseBlocks(body)] : [para]
     const item: ListItemNode = checked === undefined ? { type: "listItem", children } : { type: "listItem", children, checked }
+    const state = checkMark === undefined ? undefined : taskStateFromMarker(checkMark)
+    if (state && state !== "pending" && state !== "verified") item.state = state
     const expected = ordered ? `${(list.start ?? 1) + items.length}${list.delimiter ?? "."}` : (list.bullet ?? "-")
     if (m[2] !== expected) item.marker = m[2]
     if (m[3].length !== 1) item.pad = m[3].length

package/src/gitbook/properties.ts

@@ -0,0 +1,49 @@
+import { isMap, isScalar, parseDocument } from "yaml"
+import type { DocumentPropertiesNode } from "./ast"
+
+export type DocumentPropertyValue = string | number | boolean | null | DocumentPropertyValue[] | { [key: string]: DocumentPropertyValue }
+export interface ParsedDocumentProperties {
+  values: Record<string, DocumentPropertyValue>
+  error?: string
+}
+
+/** Read properties without throwing on an incomplete or invalid document. YAML is never executed. */
+export function readDocumentProperties(properties: DocumentPropertiesNode): ParsedDocumentProperties {
+  try {
+    const doc = parseDocument(properties.yaml)
+    if (doc.errors.length) return { values: {}, error: doc.errors[0].message }
+    if (doc.contents && !isMap(doc.contents)) return { values: {}, error: "Document properties must be a YAML mapping." }
+    const values = (doc.toJS({ maxAliasCount: 100 }) ?? {}) as Record<string, DocumentPropertyValue>
+    // Cyclic aliases can be preserved as YAML, but cannot be represented by editable JSON-like values.
+    JSON.stringify(values)
+    return { values }
+  } catch (error) {
+    return { values: {}, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/** Change one property while retaining the other keys, comments, scalar styles and frontmatter delimiters. */
+export function setDocumentProperty(properties: DocumentPropertiesNode, key: string, value: DocumentPropertyValue): DocumentPropertiesNode {
+  const doc = parseDocument(properties.yaml)
+  const parsed = readDocumentProperties(properties)
+  if (parsed.error) throw new Error(parsed.error)
+  const previous = doc.get(key, true)
+  const range = isScalar(previous) ? previous.range : undefined
+  doc.set(key, value)
+  const yaml = doc.toString().replace(/\n$/, "")
+  const next = parseDocument(yaml).get(key, true)
+  // A scalar edit is a source-range patch, leaving every other byte (including flow-list spacing) alone.
+  if (range && isScalar(next) && next.range) {
+    return { ...properties, yaml: properties.yaml.slice(0, range[0]) + yaml.slice(next.range[0], next.range[1]) + properties.yaml.slice(range[1]) }
+  }
+  return { ...properties, yaml }
+}
+
+/** Remove one property; the frontmatter remains available for adding more. */
+export function removeDocumentProperty(properties: DocumentPropertiesNode, key: string): DocumentPropertiesNode {
+  const doc = parseDocument(properties.yaml)
+  const parsed = readDocumentProperties(properties)
+  if (parsed.error) throw new Error(parsed.error)
+  doc.delete(key)
+  return { ...properties, yaml: doc.toString().replace(/\n$/, "") }
+}

package/src/gitbook/serialize.ts

@@ -27,6 +27,7 @@ import { attr } from "./attrs"
 import { normalizeLabel, serializeInline, serializeReference, withDocumentDefinitions } from "./inline"
 import { plainText } from "./inline"
 import { parseBlocks } from "./parse"
+import { taskMarker } from "./tasks"
 
 /** A `{% tag %}…{% endtag %}` container, block or item. */
 export type TaggedNode = HintNode | TabsNode | TabNode | StepperNode | StepNode | ColumnsNode | ColumnNode | UpdatesNode | UpdateNode
@@ -114,7 +115,9 @@ export function serializeMarkdown(doc: DocumentNode): string {
   documentCitations = citations
   try {
     return withDocumentDefinitions(defs, () => {
-      let out = doc.children.map((b, k) => `${blankLines(b, k ? 1 : 0)}${serializeBlock(b)}\n`).join("")
+      const properties = doc.properties
+      let out = properties ? `${properties.opening ?? "---"}\n${properties.yaml}${properties.yaml ? "\n" : ""}${properties.closing ?? "---"}\n` : ""
+      out += doc.children.map((b, k) => `${blankLines(b, k ? 1 : 0)}${serializeBlock(b)}\n`).join("")
       // Footnote definitions not placed in the document end it, as a group.
       const trailing = (doc.citations ?? []).filter((c) => !placed.has(c.id))
       if (trailing.length) {
@@ -537,7 +540,7 @@ function inlineToHtml(nodes: Inline[]): string {
 
 function serializeListItem(item: ListItemNode, list: ListNode, idx: number): string {
   const marker = item.marker ?? (list.ordered ? `${(list.start ?? 1) + idx}${list.delimiter ?? "."}` : (list.bullet ?? "-"))
-  const check = list.task ? `[${item.checked ? (item.checkMark ?? "x") : " "}] ` : ""
+  const check = list.task ? `[${taskMarker(item)}] ` : ""
   const [first, ...rest] = item.children
   const firstText = first?.type === "paragraph" ? serializeInline(first.children) : first ? serializeBlock(first) : ""
   const restText = rest.length ? "\n" + indent(serializeBlocks(rest), " ".repeat(item.indent ?? 2)) : ""

package/src/gitbook/tasks.ts

@@ -0,0 +1,25 @@
+import type { ListItemNode, TaskState } from "./ast"
+
+export const TASK_STATES: ReadonlyArray<{ id: TaskState; marker: string; label: string }> = [
+  { id: "pending", marker: " ", label: "Pending" },
+  { id: "in-progress", marker: "~", label: "In progress" },
+  { id: "implemented", marker: "?", label: "Implemented · evidence needed" },
+  { id: "blocked", marker: "b", label: "Blocked" },
+  { id: "parked", marker: "d", label: "Parked · verification debt" },
+  { id: "refuted", marker: "!", label: "Refuted" },
+  { id: "verified", marker: "x", label: "Verified" },
+  { id: "cancelled", marker: "-", label: "Cancelled" },
+]
+
+export function taskStateFromMarker(marker: string): TaskState | undefined {
+  return TASK_STATES.find((state) => state.marker === (marker === "X" ? "x" : marker))?.id
+}
+
+export function getTaskState(item: Pick<ListItemNode, "state" | "checked">): TaskState {
+  return item.state ?? (item.checked ? "verified" : "pending")
+}
+
+/** Explicit state wins; untouched uppercase `[X]` tasks retain their spelling. */
+export function taskMarker(item: Pick<ListItemNode, "state" | "checked" | "checkMark">): string {
+  return item.state ? TASK_STATES.find((state) => state.id === item.state)?.marker ?? " " : item.checked ? item.checkMark ?? "x" : " "
+}

package/src/index.ts

@@ -3,6 +3,13 @@
 export { GitbookStreamdown } from "./streamdown"
 export type { GitbookStreamdownProps } from "./streamdown"
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
+export { TaskCheckbox, TASK_STATE_ICONS } from "./docs/TaskCheckbox"
+export type { TaskCheckboxProps, TaskStateChangeHandler } from "./docs/TaskCheckbox"
+export { TASK_STATES, getTaskState, taskMarker, taskStateFromMarker } from "./gitbook/tasks"
+export { DocumentProperties } from "./docs/DocumentProperties"
+export type { DocumentPropertiesProps } from "./docs/DocumentProperties"
+export { readDocumentProperties, removeDocumentProperty, setDocumentProperty } from "./gitbook/properties"
+export type { DocumentPropertyValue, ParsedDocumentProperties } from "./gitbook/properties"
 export type { DocRenderOptions, LivePreviewProps, LivePreviewRenderer, SourceReferenceRenderer } from "./docs/DocsRenderer"
 export { DocPageActions } from "./docs/PageActions"
 export type { DocPageAction, DocPageActionsOptions, DocPageActionsProps } from "./docs/PageActions"

package/src/streamdown.tsx

@@ -35,6 +35,8 @@ export function GitbookStreamdown({
   demoDependencies,
   demoVFS,
   pageActions,
+  documentProperties,
+  onTaskStateChange,
 }: GitbookStreamdownProps) {
   const content = markdown ?? children ?? ""
   const gitbookDoc = useMemo(
@@ -59,6 +61,8 @@ export function GitbookStreamdown({
         demoDependencies={demoDependencies}
         demoVFS={demoVFS}
         pageActions={isStreaming ? false : pageActions}
+        documentProperties={documentProperties}
+        onTaskStateChange={onTaskStateChange}
       />
     </div>
   )

package/src/styles.css

@@ -1,3 +1,5 @@
+@import "./docs/properties.css";
+@import "./docs/tasks.css";
 
 [data-docstream],
 .docs-article {