@markup-carve/carve-wasm 0.1.3 → 0.1.5

package/README.md

@@ -2,9 +2,9 @@
 
 WebAssembly build of the [Carve](https://markup-carve.github.io/carve/) markup
 renderer, compiled from
-[carve-rs](https://github.com/markup-carve/carve-rs). Lets the Rust
-implementation run client-side in the browser and backs the **Rust (WASM)**
-engine in the [Carve playground](https://markup-carve.github.io/carve/playground).
+[carve-rs](https://github.com/markup-carve/carve-rs). It runs the Rust
+implementation in browsers and powers the **Rust (WASM)** engine in the
+[Carve playground](https://markup-carve.github.io/carve/playground).
 
 ## Install
 
@@ -12,316 +12,95 @@ engine in the [Carve playground](https://markup-carve.github.io/carve/playground
 npm install @markup-carve/carve-wasm
 ```
 
-> Publishing to npm is pending. Until the package is live you can build locally
-> (see [Build](#build) below) or consume the `pkg/` output directly.
+> Publishing to npm is pending. Until the package is live, build it locally
+> using the [build guide](docs/building.md) or consume the generated `pkg/`
+> directory directly.
 
-## Usage
+## Render Carve
 
-### HTML migration
-
-`htmlToCarve(html, mode)` returns `{ value, report }`, using the same HTML5
-import policy and canonical writer as carve-rs. Modes are `safe` (default),
-`semantic`, and trusted-only `roundtrip`.
-
-```js
-const { value, report } = htmlToCarve('<p>Hello <strong>world</strong></p>', 'safe')
-```
-
-Portable migration code can use `fromHtml(html, mode)` and
-`fromMarkdown(markdown)`. Both return `{ value, report }`; Markdown carries an
-empty diagnostics list because the engine migrates the document whole.
-
-### Core renderer
-
-Renders Carve markup to HTML with no extensions enabled.
-
-The published package is the **bundler** target (webpack, Vite, Rollup, ...):
-the wasm initializes automatically, so the exports are synchronous - no `init()`
-call.
-
-```js
-import { toHtml } from '@markup-carve/carve-wasm'
-
-// The other core targets are toMarkdown, toPlainText, toAnsi, and toCarve.
-
-const html = toHtml('# Hello, Carve!')
-document.body.innerHTML = html
-```
-
-### Source-preserving patches
-
-Tools can prepare canonical formatting as stale-safe UTF-8 byte edits:
-
-```js
-const patch = toCarvePatch(source)
-const formatted = applySourcePatch(source, patch)
-```
-
-`createSourcePatch(source, replacement, kind, code)` prepares the same wire
-shape for another complete replacement. Its ranges are UTF-8 byte offsets. The
-fingerprint and byte length catch accidental staleness; they are not a
-cryptographic signature. Treat a patch as trusted edit instructions.
-
-### Extensions
-
-`extensions()` reports every extension this build accepts. The list comes from
-the engine, so it cannot fall behind what the engine has:
-
-```js
-import { extensions, toHtmlWithOptions } from '@markup-carve/carve-wasm'
-
-extensions()
-// ['autolink', 'citations', 'code-callouts', 'code-group', ...]
-
-toHtmlWithOptions(src, { extensions: ['glossary', 'table-of-contents'] })
-```
-
-Names are kebab-case; snake_case (`math_block`) is accepted too. An unknown name
-throws, because an ignored extension renders as missing behavior that looks
-like a Carve bug.
-
-### Full renderer (preview set)
-
-`toHtmlFull` enables the preview set the playground uses: tab normalisation,
-`<details>` fences, Mermaid diagrams, wikilinks, autolink, list-table, math
-blocks, heading permalinks, citations, code callouts, external-link decoration,
-code groups, and tabs.
-
-It is a curated subset rather than everything registered. Extensions that
-rewrite a document that never asked - `heading-numbers` numbers every heading,
-`table-of-contents` injects a TOC - are wrong for a preview. Name them
-explicitly through `toHtmlWithOptions` when you want them.
-
-```js
-import { toHtmlFull } from '@markup-carve/carve-wasm'
-
-const html = toHtmlFull('# Hello\n\n``` mermaid\ngraph TD; A-->B\n```\n')
-document.body.innerHTML = html
-```
-
-### Symbols
-
-A `:name:` symbol renders its literal `:name:` source unless the name is in the
-**symbols map**. Pass one as a plain object (or a `Map`) to `toHtmlWithSymbols`,
-or as the optional second argument of `toHtmlFull`:
-
-```js
-import { toHtmlWithSymbols } from '@markup-carve/carve-wasm'
-
-toHtmlWithSymbols('Ship it :rocket:', { rocket: '🚀' })
-// => '<p>Ship it 🚀</p>'
-
-toHtmlWithSymbols('Ship it :rocket: :shrug:', { rocket: '🚀' })
-// => '<p>Ship it 🚀 :shrug:</p>'   (an unmapped name stays literal)
-```
-
-The word-boundary guard is unaffected by an active map: `a:b:c`, `10:30:` and
-`me@example.com` never become symbols. Names and values must both be strings; a
-non-string value throws a `TypeError`.
-
-> **Security: symbol values are TRUSTED RAW output.**
-> A mapped value is inserted into the output **unescaped** - the same trust
-> class as a static `renderers` callback. `{ b: '<b>x</b>' }` emits a real
-> `<b>` element, not escaped text. This is deliberate (processor configuration
-> is trusted). **Never build a symbols map out of untrusted / user-supplied
-> input.**
-
-### Section wrappers
-
-A top-level heading is wrapped, along with the content following it up to the
-next same-or-shallower heading, in a `<section>` carrying the heading's id (spec
-PART 9 §13). Only the id moves - `{#install .featured}` gives
-`<section id="install"><h2 class="featured">` - and a heading inside a
-blockquote, div or list item is not wrapped at all.
-
-`toHtmlWithOptions` is the general entry point, and `sections: false` renders
-headings flat with the id back on the `<h*>`:
+The published package uses the bundler target for webpack, Vite, Rollup, and
+similar tools. WASM initialization is automatic, so its exports are
+synchronous.
 
 ```js
-import { toHtmlWithOptions } from '@markup-carve/carve-wasm'
-
-toHtmlWithOptions('# A\n\np\n', { sections: false })
-// '<h1 id="A">A</h1>\n<p>p</p>'
-
-toHtmlWithOptions(src, { sections: false, symbols: { rocket: '🚀' }, full: true })
+import { toHtml, toHtmlFull, toHtmlWithOptions } from '@markup-carve/carve-wasm'
+
+toHtml('# Hello, Carve!')
+toHtmlFull('# Hello\n\n``` mermaid\ngraph TD; A-->B\n```\n')
+toHtmlWithOptions(source, {
+  extensions: ['glossary', 'table-of-contents'],
+  rawHtml: false,
+  sections: true,
+})
 ```
 
-Every field is optional. Omitting the object, or passing `null`, renders with
-defaults, so the three shorthands above remain the zero-config forms.
-
-| Field | Default | What it does |
-|---|---|---|
-| `sections` | `true` | Wrap each top-level heading and its content in a `<section>` |
-| `symbols` | none | `:name:` to value, TRUSTED-RAW (see above) |
-| `extensions` | none | Array of registry names; takes precedence over `full` |
-| `full` | `false` | Enable the preview extension set |
-| `rawHtml` | `true` | Emit an explicit passthrough as markup; `false` escapes it |
-| `profile` | none | `full` / `article` / `comment` / `minimal`; rejection throws |
-| `profileBaseHost` | none | The host the profile's link policy counts as internal |
-| `mode` | `interactive` | `static` renders the self-contained form: no client scripts |
-| `sourceLine` | `false` | Stamp top-level blocks with `data-source-line` |
-| `positions` | `false` | Keep source offsets on the nodes |
-| `labels` | none | Override engine-written strings, for a page not in English |
-| `smartTypography` | `glyph` | `source` keeps the author's run instead of the glyph |
-| `lowercaseHeadingIds` | `false` | Lowercase the generated heading ids |
-| `asciiHeadingIds` | `off` | `fold` transliterates, `strict` guarantees ASCII |
+`toHtml` uses the core renderer. `toHtmlFull` enables the extension set used
+by the playground preview. `toHtmlWithOptions` lets the caller choose
+extensions and rendering policy. Unknown extension names throw instead of
+silently producing incomplete output.
 
-An unrecognized key is ignored, because the object is configuration and a typo
-should not break a render. A recognized key with the wrong type throws a
-`TypeError` instead of being coerced: JS truthiness would read
-`{ sections: 'false' }` as `true`, the opposite of what was written.
+Other core targets include `toMarkdown`, `toPlainText`, `toAnsi`, and
+`toCarve`. Each has a `*WithOptions` form.
 
-This exists for a host whose CSS or JS assumes rendered blocks are direct
-children of the content container - the `.stack > * + *` spacing idiom,
-`:first-child`, `nth-child()` counting, `element.children` walks - all of which
-stop matching once a wrapper sits in between. It is the one output change that
-breaks a document whose *source* migrated cleanly.
+## Convert existing content
 
-Nothing else changes: ids, collision dedup, `</#id>` cross-references, implicit
-`[Heading][]` references and heading numbering all resolve against the slug
-rather than the element carrying it. The endnotes
-`<section role="doc-endnotes">` is a separate construct and is still emitted.
+The package imports HTML, Markdown, Djot, and BBCode. `fromHtml`,
+`fromMarkdown`, `migrateDjot`, and `migrateBbcode` return the converted value
+with a fidelity report. The simpler `fromDjot` and `fromBbcode` helpers return
+only the converted string.
 
-### Rendering a document you did not write
-
-`rawHtml: false` renders an explicit passthrough - the `=html` raw block and the
-`` `…`{=html} `` inline raw span - as escaped text instead of markup. It is the
-switch carve-js spells `allowRawHtml`.
+Markdown, Djot, and BBCode reports currently mark fidelity as unverified. An
+empty diagnostic list does not claim that every construct was preserved.
 
 ```js
-toHtmlWithOptions(fromTheReader, { rawHtml: false })
-```
+import { fromHtml, fromMarkdown, htmlToAst, htmlToCarve } from '@markup-carve/carve-wasm'
 
-Reach for it whenever the document comes from somewhere other than the person
-running the page: a shared link, a comment field, a pasted file. A passthrough is
-the one construct that puts author-controlled markup on your origin, so leaving
-it on for a document a reader supplied is a way to run their script.
-
-The symbols map is unaffected and stays TRUSTED-RAW either way - it is
-configuration the host wrote, not content the document carries.
-
-### Rendering with a profile
-
-`rawHtml: false` closes the passthrough vector. It does not cap input length,
-deny a construct, or constrain link schemes - that is what a profile is for, and
-the four presets match the ones the spec and the sibling bindings describe.
-
-```js
-toHtmlWithOptions(fromTheReader, { profile: 'comment', rawHtml: false })
-```
-
-**A rejected document throws.** The engine's infallible entry point turns a
-profile rejection - input past `max_length`, or a denied construct when the
-action is Error - into an EMPTY STRING, and a caller cannot tell that from a
-document that legitimately rendered to nothing. This binding renders through the
-fallible one, so a rejection arrives as an `Error` whose `name` is
-`ProfileViolationError` and whose `violations` array carries one message per
-refused construct.
-
-```js
-try {
-  html = toHtmlWithOptions(fromTheReader, { profile: 'comment' })
-} catch (error) {
-  if (error.name === 'ProfileViolationError') report(error.violations)
-}
-```
-
-### Editing a tree, and reading one back
-
-`parseJson` serializes a document out. `astJsonToHtml` renders one back, and
-`astJsonToCarve` writes one back as source, so a host that reads the tree in
-order to change something can display and save the result without a server.
-
-```js
-const tree = JSON.parse(parseJson(source))
-tree.children.unshift({ type: 'heading', level: 1, children: [{ type: 'text', value: 'Added' }] })
-const html = astJsonToHtml(JSON.stringify(tree), { full: true })
-const carve = astJsonToCarve(JSON.stringify(tree))
-```
-
-A tree carrying something no Carve source can spell is refused by
-`astJsonToCarve` rather than written approximately, and an invalid tree throws
-from either.
-
-`lintCarve` returns the degradation diagnostics as
-`{ line, column, rule, message, start, end }`, with the rule ids carve-js and
-carve-php use for the same triggers. Offsets are BYTE offsets into the source,
-matching the engine.
-
-### TypeScript
-
-The package ships `.d.ts` declarations. Types are inferred automatically when
-imported from `@markup-carve/carve-wasm`.
-
-```ts
-import { toHtml, toHtmlFull, version } from '@markup-carve/carve-wasm'
-
-console.log(`carve-wasm v${version()}`)
-const html: string = toHtml('_Hello_')
-```
-
-## API
-
-| Export | Signature | Description |
-|--------|-----------|-------------|
-| `toHtml` | `(source: string) => string` | Core renderer, no extensions |
-| `toHtmlWithSymbols` | `(source: string, symbols?: object \| null) => string` | Core renderer + a `:name:` -> value symbols map (values are raw, see above) |
-| `toHtmlFull` | `(source: string, symbols?: object \| null) => string` | Core + common extensions (matches playground), optional symbols map |
-| `toHtmlWithOptions` | `(source: string, options?: object \| null) => string` | General form; see the options table above. Throws `ProfileViolationError` when a profile rejects the document |
-| `toHtmlWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | HTML plus bounded `raw-format-dropped` losses; strict mode throws `RenderLossError` |
-| `toMarkdownWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked Markdown render |
-| `toPlainTextWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked plain-text render |
-| `toAnsiWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked ANSI render |
-| `toCarveWithReport` | `(source: string, strict?: boolean, maximum?: number) => RenderResult` | Checked canonical Carve render (lossless) |
-| `parseJson` | `(source: string) => string` | The parsed AST as JSON (PART 12 exchange shape) |
-| `astJsonToHtml` | `(json: string, options?: object \| null) => string` | Render an AST-JSON document; takes the same options object |
-| `astJsonToCarve` | `(json: string) => string` | Write an AST-JSON document back as canonical Carve source |
-| `lintCarve` | `(source: string) => LintWarning[]` | Degradation diagnostics, with the rule ids carve-js and carve-php share |
-| `readStamp` | `(source: string) => { version, generatedBy } \| null` | The document's provenance marker, if it carries one |
-| `needsReview` | `(source: string, currentVersion: string) => boolean` | Whether the stamp predates `currentVersion`; unstamped counts as yes |
-| `fromDjot` | `(source: string) => string` | Convert Djot source to Carve |
-| `fromBbcode` | `(source: string) => string` | Convert BBCode source to Carve; throws past the engine's size cap |
-| `createSourcePatch` | `(source, replacement, kind, code) => SourcePatch` | Build a minimal UTF-8 byte-range patch |
-| `toCarvePatch` | `(source: string) => SourcePatch` | Preview canonical formatting as a patch |
-| `applySourcePatch` | `(source: string, patch: SourcePatch) => string` | Validate and apply trusted patch instructions |
-| `version` | `() => string` | Returns the carve-wasm package version |
-
-### The parsed AST
-
-`parseJson` returns the document as a JSON string - the [PART 12 exchange
-shape](https://markup-carve.github.io/carve/ast-json), the same tree every Carve
-engine publishes, so a consumer written against one implementation reads
-another's output.
-
-```js
-import { parseJson } from '@markup-carve/carve-wasm'
+const { value, report } = htmlToCarve('<p>Hello <strong>world</strong></p>', 'safe')
+const { value: ast } = htmlToAst('<p>Hello <b>world</b></p>', 'safe')
 
-const ast = JSON.parse(parseJson('# Title\n\nBody[^a].\n\n[^a]: note\n'))
-ast.children.map((n) => n.type) // ['heading', 'paragraph', 'footnote']
-ast.children[0].pos             // { startLine: 1, startColumn: 1, ... }
+fromHtml(html, 'semantic')
+fromMarkdown(markdown)
 ```
 
-The root carries exactly `type`, `children` and `srcByteLength`; frontmatter and
-footnote definitions are block nodes inside `children`, not root fields. Every
-node except the root carries `pos` when the engine could place it - 1-based
-lines and columns, 0-based offsets, ends exclusive, counted in Unicode
-**codepoints**, not bytes or UTF-16 units. A node the engine could not place,
-such as reassembled table-cell text, carries no `pos` at all rather than an
-invented one.
-
-A string rather than a JS object: the caller runs `JSON.parse`, which the
-browser does natively and faster than building the object graph across the wasm
-boundary one property at a time - and it keeps the bytes available for a caller
-that stores or forwards them.
+HTML modes are `safe` (the default), `semantic`, and trusted-only
+`roundtrip`. `htmlToAst` returns the serialized Carve AST without passing it
+through the source writer, so its report can differ from `htmlToCarve` when a
+construct is representable in the tree but not in Carve source.
+
+## Common host APIs
+
+- `extensions()` returns the extension names supported by the bundled engine.
+- `toCarvePatch()` and `applySourcePatch()` create and apply stale-safe UTF-8
+  byte edits.
+- `toHtmlWithSymbols()` resolves configured `:name:` symbols. Symbol values
+  are trusted raw output and must not come from user input.
+- `parseJson()`, `astJsonToHtml()`, and the other AST functions use the PART 12
+  AST JSON shared by Carve implementations.
+- Include expansion calls a synchronous host resolver, records dependencies,
+  and enforces depth, byte, and call budgets. The resolver decides which paths
+  to refuse.
+- Incremental parsing, tree patches, three-way merge, and ProseMirror helpers
+  support browser editors.
+
+The [complete API and usage reference](docs/reference.md) documents these
+APIs, renderer profiles, resource limits, includes, AST fields, and the
+TypeScript declarations.
+
+## Security
+
+Use `rawHtml: false` with a restrictive profile such as `comment` for
+untrusted documents. Symbols and static renderer callbacks are trusted
+configuration and may emit unescaped HTML. Treat source patches as trusted
+edit instructions, not as signed data. A profile rejection throws.
+
+Carve also enforces URL-scheme and attribute hardening in the renderer. See
+the language [security documentation](https://markup-carve.github.io/carve/security)
+for the complete model.
 
 ## Development
 
-The reference material a contributor needs lives in `docs/`, so this page can
-stay about USING the package:
+Contributor documentation lives under `docs/`:
 
-- [Building](docs/building.md) - the wasm-pack targets, pointing the tests at a
-  built package, and the rendering-only browser profile.
-- [The carve-rs pin](docs/engine-pin.md) - why the engine is pinned to an exact
-  commit, and how to move it.
-- [Releasing](docs/releasing.md) - the gate, what it refuses, and the runbook
-  for cutting a version.
+- [Building and testing](docs/building.md)
+- [The carve-rs engine pin](docs/engine-pin.md)
+- [Release process](docs/releasing.md)