#papyr.mbt

#What lives here

• papyr.normalized-document.v0 and the decoder that accepts it.
• A MoonBit core PapyrDocument API and validation middleware for authoring payloads.
• MoonBit Markdown parse/serialize/format APIs for headings, paragraphs, inline marks, links, flat lists, and fenced code blocks.
• MoonBit adapter scaffolding, starting with an in-memory document adapter.
• Stable diagnostics JSON for decode and projection failures.
• A CLI with compatibility commands for docs builds and the migrated markdown/json conversion surface.
• Core document stack tool envelopes for validation, Markdown conversion, preview/search, and workspace/publication export over PapyrDocument.
• tmpx-backed HTML rendering for static pages and partial fragments.
• Optional mx-* helper emission for mhx-style progressive enhancement.
• Fixtures, golden-style tests, and the frozen compatibility snapshot copied from the current papyr docs corpus.
• The vendored docs workspace under apps/docs and packages/*.

#Acknowledgements

#Ownership boundary

• MoonBit owns document modeling, Markdown conversion, formatter behavior, adapters, normalized-document decoding, deterministic diagnostics, publication projection, artifact emission, and tmpx-backed HTML rendering.
• JS/TS owns npm compatibility entrypoints, the React UI, playground routes, the Worker runtime, and Cloudflare or R2 integration until each surface is migrated or intentionally kept as runtime glue.

#Read next

• docs/compatibility/README.md freezes the current docs-site compatibility contract.
• docs/build-content-bridge.md explains the JS parse -> MoonBit projection bridge used by apps/docs/scripts/build-content.ts.
• docs/vendored-workspace.md explains why the docs app is vendored here and how to keep that workspace reproducible.
• docs/post-parity-boundary.md records the next ownership step after the parity milestone.

#Vendored docs app

• apps/docs
• packages/*

#Workspace reproducibility

pnpm install --frozen-lockfile
pnpm run verify:vendored-workspace

#Release / npm publish

• Versions use CalVer YYYY.M.PATCH, for example 2026.4.0.
• All published packages move in lockstep to the same version.

#Bump package versions

pnpm bump 2026.M.X

#Manual publish (first release)

pnpm install --frozen-lockfile
pnpm -r build
pnpm publish:packages

#Trusted publishing (after npm setup)

git tag v2026.M.X
git push origin main --follow-tags

#Normalized document shape

{
  "schemaVersion": "papyr.normalized-document.v0",
  "id": "docs/intro",
  "path": "docs/intro.md",
  "frontmatter": {
    "title": "Intro",
    "tags": ["guide"]
  },
  "blocks": [
    {
      "type": "heading",
      "depth": 1,
      "text": "Intro"
    },
    {
      "type": "paragraph",
      "children": [
        { "type": "text", "value": "Hello" }
      ]
    }
  ]
}

#Core PapyrDocument contract

{
  "id": "intro",
  "title": "Intro",
  "blocks": [
    ["Heading", { "id": "b1", "level": 1, "content": [{ "text": "Intro", "marks": [] }] }]
  ],
  "meta": { "source": "markdown" }
}

#CLI

moon run src/cmd/main --target native -- markdown_to_document '# Intro' intro
moon run src/cmd/main --target native -- validate_document '{"id":"intro","blocks":[]}'

#decode

{"ok":true,"command":"decode","documents":[...]}

{"ok":false,"message":"...","diagnostics":[...]}

#build-docs

{"documents":[...]}

#markdown-to-json

moon run src/cmd/main -- markdown-to-json '# Intro' intro

#json-to-markdown

moon run src/cmd/main -- json-to-markdown '{"id":"intro","title":"Intro","blocks":[["Heading",{"id":"b1","level":1,"content":[{"text":"Intro","marks":[]}]}]]}'

#format-markdown

#Document stack tool commands

{"ok":true,"tool":"markdown_to_document","result":{},"diagnostics":[]}

{"tool":"preview_document","input":{"document":{"id":"intro","blocks":[]}}}

#Local issue workflow