@markup-carve/carve-wasm 0.1.5 → 0.1.6

package/examples/carve-worker.mjs

@@ -0,0 +1,35 @@
+import init, { ParserSession, toHtmlWithOptions } from '@markup-carve/carve-wasm/web'
+
+const ready = init()
+let session
+self.onmessage = async ({ data: { id, action, source, changes } }) => {
+  try {
+    await ready
+    let value
+    switch (action) {
+      case 'open': {
+        const next = new ParserSession(source)
+        session?.free()
+        session = next
+        value = JSON.parse(session.snapshot())
+        break
+      }
+      case 'edit':
+        if (!session) throw new Error('Open a document before editing')
+        value = JSON.parse(session.edit(JSON.stringify(changes)))
+        break
+      case 'render':
+        value = toHtmlWithOptions(source, { rawHtml: false, profile: 'comment' })
+        break
+      case 'close':
+        session?.free()
+        session = undefined
+        value = null
+        break
+      default: throw new Error('Unknown worker action')
+    }
+    self.postMessage({ id, value })
+  } catch (error) {
+    self.postMessage({ id, error: { name: error.name, message: error.message } })
+  }
+}

package/examples/offsets.d.ts

@@ -0,0 +1,3 @@
+export function utf16ToUtf8(source: string, offset: number): number;
+export function codepointToUtf8(source: string, offset: number): number;
+export function utf8ToUtf16(source: string, offset: number): number;

package/examples/offsets.mjs

@@ -0,0 +1,18 @@
+const encoder = new TextEncoder()
+
+function convert(source, offset, from, to) {
+  if (!Number.isSafeInteger(offset) || offset < 0) throw new RangeError('offset must be a non-negative safe integer')
+  const position = { utf16: 0, utf8: 0, codepoint: 0 }
+  for (const character of source) {
+    if (position[from] === offset) return position[to]
+    position.utf16 += character.length
+    position.utf8 += encoder.encode(character).length
+    position.codepoint++
+    if (position[from] > offset) throw new RangeError('offset splits a Unicode character')
+  }
+  if (position[from] !== offset) throw new RangeError('offset exceeds the source length')
+  return position[to]
+}
+export const utf16ToUtf8 = (source, offset) => convert(source, offset, 'utf16', 'utf8')
+export const codepointToUtf8 = (source, offset) => convert(source, offset, 'codepoint', 'utf8')
+export const utf8ToUtf16 = (source, offset) => convert(source, offset, 'utf8', 'utf16')

package/node/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Scherer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node/README.md

@@ -0,0 +1,105 @@
+# carve-wasm
+
+WebAssembly build of the [Carve](https://markup-carve.github.io/carve/) markup
+renderer, compiled from
+[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
+
+```bash
+npm install @markup-carve/carve-wasm
+```
+
+## Render Carve
+
+The package root selects synchronous Node bindings in Node and the bundler
+build in browser bundles. The browser bundler must support native WASM imports
+and top-level await. Vite 8.3.2 is tested. See the
+[compatibility guide](docs/compatibility.md) for explicit browser, Node and
+rendering-only imports.
+
+```js
+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,
+})
+```
+
+`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.
+
+Other core targets include `toMarkdown`, `toPlainText`, `toAnsi`, and
+`toCarve`. Each has a `*WithOptions` form.
+
+## Convert existing content
+
+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.
+
+Markdown, Djot, and BBCode reports currently mark fidelity as unverified. An
+empty diagnostic list does not claim that every construct was preserved.
+
+```js
+import { fromHtml, fromMarkdown, htmlToAst, htmlToCarve } 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')
+
+fromHtml(html, 'semantic')
+fromMarkdown(markdown)
+```
+
+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.
+- `ParserSession` retains a document between edits and can reuse unchanged
+  plain paragraphs. Call `free()` when the editor closes. Tree patches,
+  three-way merge and ProseMirror helpers also 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
+
+Contributor documentation lives under `docs/`:
+
+- [Building and testing](https://github.com/markup-carve/carve-wasm/blob/main/docs/building.md)
+- [The carve-rs engine pin](https://github.com/markup-carve/carve-wasm/blob/main/docs/engine-pin.md)
+- [Release process](https://github.com/markup-carve/carve-wasm/blob/main/docs/releasing.md)