npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@gmb/bitmark-parser

v8.0.0

Published

A parser for bitmark text, powered by WebAssembly.

Readme

A high-performance parser and generator for bitmark. Provides a programmatic API (powered by WebAssembly) and a CLI (prebuilt native binary per platform) for converting between bitmark markup and JSON.

Installation

npm install @gmb/bitmark-parser

Programmatic API (JS / TS)

import {
  convert,
  semanticTokens,
  breakscapeText,
  unbreakscapeText,
  info,
  version,
} from "@gmb/bitmark-parser";

// Convert bitmark to JSON — set inputFormat explicitly when known (skips
// auto-detection); "auto" also works but costs an extra scan
const json = convert("[.article]\nHello **bold**", {
  inputFormat: "bitmark",
  warnings: true,
});
const parsedJson = JSON.parse(json);
console.log(parsedJson[0].bit.type);
console.log(parsedJson[0].parser.warnings);
console.log(parsedJson[0].bitmark);

// Generate bitmark from JSON
const bitmark = convert(json, { inputFormat: "json", outputFormat: "bitmark" });

// Parser-derived highlighting in the LSP semantic-tokens shape
const highlights = semanticTokens("[.article]\nHello **bold**", {
  tokensLayout: "absolute",
});

// Dump the lexer's token stream (debug tooling; bitmark input only)
const tokens = JSON.parse(
  convert("[.article]\nHello **bold**", {
    inputFormat: "bitmark",
    outputFormat: "lex",
  }),
);

// Breakscape / unbreakscape text
const escaped = breakscapeText("[!example]", {
  format: "bitmark++",
  location: "body",
});
const unescaped = unbreakscapeText(escaped, {
  format: "bitmark++",
  location: "body",
});

// Query supported bit types
const bitInfo = info({ infoType: "list", format: "text" });

// Get library version
console.log(version());

WASM variants (full / browser-full / bitmark-json)

The package ships three wasm builds of the same engine and selects one at runtime — the API surface never changes:

| Feature | Contents | Size (approx.) | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | | full (Node default) | everything: rich info metadata + built-in translations + the semantic diff + the incremental document (createDocument) | ~1314 KB (~531 KB gzip) | | browser-full (browser default) | the same conversions, diff and createDocument, without the metadata and translations | ~1109 KB (~469 KB gzip) | | bitmark-json | bitmark ↔ JSON only: convert/canonicalize/transform (formats auto/bitmark/json, plus the text, semantic-tokens and diagnostics outputs), the editor services, bit templates, info (JSON only), breakscape, text fragments — no diff, no createDocument | ~761 KB (~318 KB gzip) |

The rule. Every build includes every feature, except the two browser-targeted variants, which each carry an explicit exclusion list. That is the whole story — a new capability is in every build unless it is named below:

| build | features | | -------------------------------------------------- | ----------------------------------------------------------------------------------- | | native CLI, daemon, docgen, schemagen, wasm full | all | | wasm browser-full | all except info-meta (bit + tag prose) and translations (the baked table) | | wasm bitmark-json | all except the above and markup, mapping-report, diff, lex (with ast), info-text, document (the incremental document, ~25 KB gzip) |

So, not in bitmark-json: the markup formats (html, xml, xml-niso-iec, …) as input or output (they throw an unsupported error), the lex output format and the mappingReport option (same error), diff and createDocument (throw UnsupportedFeatureError), and the human-readable rendering of info — info({ format: "text" }) throws UnsupportedFeatureError there, so pass format: "json" (the JSON views are the contractual ones and are in every variant).

full and browser-full convert identically — they differ only in what info can report: the META fields (bit and tag descriptions, group provenance and raw mapping patterns) and the built-in translations table. Bit titles and the bit-group / resource-group catalogs are in every variant, in English; register supplies the texts — descriptions and translations — to the lean ones (see Display names, descriptions and languages).

Why the defaults differ: only the browser pays a download-latency cost for those strings, and a Node backend loading wasm from disk has the same requirements as the native CLI. But which channel an artifact ends up in is not knowable from the artifact — browser code is routinely package-managed and webpack-built — so both variants are available on both platforms and the defaults are conveniences only. If you bundle the Node entry for the browser, select browser-full explicitly.

Migrating from ≤ 6.10: full used to mean what browser-full means now. Browser code that explicitly selected "full" should move to "browser-full" to keep its download size close to what it was; leave it on "full" to gain the metadata and built-in translations for ~62 KB gzip. Nothing else changes — the capabilities that were in full are in both.

import { init, convert, variant } from "@gmb/bitmark-parser";

await init({ feature: "bitmark-json" }); // load the minimal wasm
convert("[.article]\nHello"); // works
variant(); // "bitmark-json"

// Upgrade in place: the interface stays valid while the full wasm loads —
// calls keep being served by the active module, then swap atomically.
await init({ feature: "full" });
convert("[.article]\nHi", { outputFormat: "html" }); // now works

Notes:

  • Node: with no explicit init, the first call lazily loads full synchronously — existing zero-init usage is unchanged. initSync({ feature }) selects a variant synchronously.
  • Browser: init() is required as before, and loads browser-full; only the selected variant's .wasm is fetched (all three small JS glue modules are in the bundle). Overlapping init calls: same-feature calls coalesce; a different-feature call supersedes an unfinished one (last call wins); every promise resolves once the finally-active module is live. init({}) is the same request as init(). In the browser, initSync(bytes, { feature }) instantiates from bytes you supply, and takes part in the same last-call-wins order: an init still loading when initSync runs never swaps in afterwards.
  • Supplying your own .wasm: glue and module are a pair, so name the feature the bytes belong to — init({ feature, module_or_path }). The back-compat positional form init(module_or_path) stays on full, since those bytes are bitmark_wasm_bg.wasm.
  • Workers: transformParallel workers load the active variant.
  • Legacy API: works on bitmark-json (it follows the active module) except its HTML-dependent members (e.g. convertHtmlTable), which throw.
  • A previously active module's reference is dropped on swap; wasm-bindgen's glue retains the instance until that variant is re-initialised, so switching back is cheap but the memory of an abandoned variant is only reclaimed on page/process end or its re-init.

API

Errors

Errors are thrown, never returned. Every fallible WASM export raises a JavaScript Error whose message has one shape:

<kind> at <path>: <message>

A returned string is therefore always a result — there is no prefix or sentinel to test for, and every call site is a try/catch.

<kind> is a stable kebab-case identifier — the part to match on. <path> locates the failure (a JSON pointer-ish path, offset N for a JSON syntax error, or empty) and <message> is human-readable prose that may change in any release. The kinds:

| kind | meaning | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | invalid-json | the input string is not well-formed JSON | | compose | the reverse composer rejected the JSON (shape / field / type) | | unsupported | the requested conversion is not available (an output-only format used as input, or a format compiled out of this variant) | | patch-parse-error | a patch or patch document is malformed | | patch-index-out-of-range | a patch path addressed an array element that does not exist | | patch-type-mismatch | a patch value's JSON type is incompatible with its target | | patch-conflict | a patch document's entries contradict each other (a bit removed or moved twice, or an anchor that is itself removed or moved) | | document-version | createDocument: a change's version is not newer than the document's (thrown as DocumentVersionError) | | document-range | createDocument: a change's range is not in the text | | document-view | createDocument: no open view has that id |

Every TypeScript wrapper propagates that Error unchanged — convert, transform, canonicalize, bitmarkToObjects, countBits, diff, … — as does the parallel worker pool, which rejects with the first failing bit's error. register re-wraps it as a RegisterError; a capability the loaded variant compiled out raises UnsupportedFeatureError before any wasm call.

convert(input: string, options?: ConvertOptions): string

Convert between bitmark, JSON, and the mapped markup formats (html/xml/…).

A JSON input may be an array or a single value, each entry a { bit: {…} } envelope (the forward output) or a bare bit object. An entry that is not a bit produces no bitmark: it is skipped and reported as a bit-invalid issue (or bit-type-invalid when it has a type the registry does not know) naming its JSON path ($[2] is not a bit: expected a bit object with "type" — ignored) on the warnings channel of the CLI (--warnings) and the daemon; the bits beside it still convert, and a document in which nothing is a bit converts to empty output. This convert returns a bare string and so cannot show the skip. Only malformed JSON text throws (invalid-json).

Options:

  • inputFormat — "auto" (default), "bitmark", "json", "jsonl", or a mapping id ("html", "xml", …)
  • outputFormat — "auto" (default: the opposite direction), "jsonl" (the JSON entries one per line: compact, each line ending in \n, pretty does not apply; reads back like JSON, a bad line throws naming it, and "auto" detects it), "text" (lossy plain-text extraction; output-only), "semantic-tokens" / "diagnostics" / "lex" / "ast" (output-only, bitmark input only — see their sections), or as above
  • mode — "optimized" (default) or "full"
  • warnings — include validation warnings (default: false)
  • plainText — output text as plain text (default: false)
  • pretty — prettify the emitted JSON (default: false). For JSON output this is the whole document; for bitmark output it pretty-prints the embedded JSON bodies of json-format bits (cosmetic — they re-parse to the same value)
  • indent — indent size for pretty JSON (default: 2)
  • inlineStyle — bitmark output only: how inline marks are written — "toggle" (default: toggle tags, (+bold)x(-bold), which may overlap) or "legacy" (the deprecated **bold**, ==x==|bold|). Any other value throws (unknown inline style): it is never read as the default. A mark with only one spelling keeps it: semantic and highlight search are toggles in either style. In toggle style every mark is a toggle: no legacy form is written, and a mark the toggle spelling cannot hold is dropped and reported (mark-dropped). Also on canonicalize, transform, objectsToBitmark, diff and the CLI's --inline-style. Reading bitmark, each legacy span raises the warning formatting-deprecated, showing the toggle tags to write instead (write it as (+link:https://a.com)…(-link)) — the tags this writer writes for it. Every legacy span warns, except where the text is just text
  • includeUnknownProperties — bitmark → JSON only (default: false): include unknown properties in the bit JSON. An unknown property ([@key:value] the bit's config cannot resolve, at the bit body/footer — never inside cards or consumed by a chain) is appended after all real keys as an array of strings (a valueless [@key] → true); a key colliding with a configured key of the bit is _-prefixed. A bare tag the bit does not declare ([!…], [?…], [#…], … on a bit whose config has no such tag) is an unknown too, under the key a declaring bit would use ([!x] → "instruction": ["x"]); a rejected resource attachment is not — it is still emitted, with a warning. Unknown properties are never converted back to bitmark, and each occurrence warns whether or not it is included. Also available on bitmarkToObjects and as the CLI's --include-unknown-properties
  • mappingReport — replace the converted output with a human-readable MAPPING REPORT of what each input construct mapped to, including the inputs that are NOT mapped (default: false). The report lists every input occurrence, grouped by bit (mapped → its output construct, carried → what consumed it, or NOT MAPPED), a per-name summary table, and a NOT-MAPPED inventory. Composite conversions (e.g. xml → json) report every leg, one section after the other. Most useful on foreign document import (inputFormat: "xml-niso-iec"), where NOT MAPPED means recorded loss. Also the CLI's --mapping-report

Performance: inputFormat: "auto" detects the format by scanning the input for a bitmark bit header — for non-bitmark input that is a full pass over the whole input before parsing starts, and the detection is a heuristic (markup formats are never auto-detected). If you know the input format, set inputFormat explicitly. The same applies to canonicalize and transform, whose inputFormat also defaults to "auto".

Input limits: JSON objects/arrays and markup elements may nest at most 256 levels deep. Deeper JSON is rejected like any other malformed JSON ("error: … nesting depth exceeds 256"); a deeper markup open tag is kept as literal text. The bound keeps a crafted document from exhausting the WASM stack — an instance that rejects a too-deep input stays usable for the next call.

convert is the single string-based conversion surface — parsing is { inputFormat: "bitmark", outputFormat: "json" }, generating is { inputFormat: "json", outputFormat: "bitmark" }. For typed objects use bitmarkToObjects / objectsToBitmark (below), which pin their formats.

For bitmark input, output is a JSON array of entries with:

  • bit — serialized bit payload
  • parser — parser metadata, errors / warnings, and infos (informational notices for recoveries that are not necessarily wrong: text kept as text because it only looks like an unclosed tag, tag-unclosed, or a formatting mark with no partner, formatting-unclosed — in bitmark malformed markup is text, not an error). A reference whose target is not in this document, text-tag-target-missing, is reported by diagnostics() only, never here. Each issue carries a stable machine-readable code ("tag-invalid", "tag-missing", …) and a scope ("bit", "card", "bit-chain" or "card-chain" — where the issue sits) beside its human-readable message, plus text and location. Branch on code and scope — a shipped code never changes meaning, whereas the message text is not contractual and may be reworded in any release. bitmark info error-codes lists every code with its severity and message template (see info below)
  • bitmark — source bitmark text (a convenience echo; every bit is fully described by bit alone)

A region the parser could not read — an unknown bit type, or non-blank text that never opened a bit — comes back as a bit of type _error beside its parser.errors entry. It carries originalType (the header exactly as written between the level dots and the ], including a leading | for a commented-out bit and any :format / &resource suffix; absent when there was no header) and body (the raw text after it, as a plain string), so generating bitmark from it reproduces the original region.

The other direction reports too. Going to bitmark (from JSON or from markup), an inline mark that has no bitmark form is dropped — the forward parser would not read it back as that mark, so writing it would corrupt the surrounding text. The text it decorated is always kept, and the loss is reported: mark-dropped when the whole mark goes, mark-reduced when it survives in a lesser form (its value cleared, or one of its segments dropped). Both arrive on the conversion's warnings, like every other issue. In practice they are rare — a href holding a line terminator, a mark kind the grammar has no tag for — so treat either as a signal that the JSON holds something bitmark cannot express, not as routine noise. Likewise list-number-invalid: a list start or item value that is not a valid number for its list (4000 on a Roman list), or a value on a bullet or task item, is ignored and reported.

Reading bitmark, an inline property list (==text==|link:…|?hint|) reports two things (PLAN-217): text-tag-cardinality-exceeded when a child is given more often than it may be (|?a|?b| — the later value wins), and text-tag-value-invalid when a value does not fit its format but is kept (|symbol:…|width:wide|).

A reference (==see==|►sec-1|) must find an anchor with its value ([▼sec-1], or an inline image's |▼sec-1|) in the same document — one input is one document. A customer reference (|customer►sec-1|) must likewise find a customer anchor ([customer▼sec-1], |customer▼sec-1|); these carry a source format's own ids, while ▼ / ► stay the platform's. An unmatched value is noted once, as the info text-tag-target-missing, by diagnostics() on bitmark source (PLAN-229, PLAN-271): a diagnostic only, never in a conversion's output. An empty reference names nothing and is not noted. A reference into another document is not wrong, only unverifiable, so it is a notice, not a warning.

convertWithDetails(input: string, options?: ConvertWithDetailsOptions): ConvertResult

convert, returning { output, …extras } — the same conversion, run once, with each extra asked for by a flag in the options. output is exactly what convert returns, and it throws exactly as convert does. Future extras are one more flag and one more field each.

  • bitSpans — true adds result.bitSpans, where each top-level bit's text is in the input and in the output, for linking the panes that show them bit by bit — whichever side of the conversion a pane is on:
const { output, bitSpans } = convertWithDetails(source, {
  inputFormat: "bitmark",
  outputFormat: "html",
  bitSpans: true,
});
// bitSpans = { positionEncoding: "utf-16",
//   spans: [{ index, inputStart, inputEnd, outputStart, outputEnd }, …] }
for (const { index, inputStart, inputEnd, outputStart, outputEnd } of bitSpans!.spans) {
  console.log(index, source.slice(inputStart, inputEnd), output.slice(outputStart, outputEnd));
}
  • index is the bit's position in the input: its splitBits index for bitmark input, its entry index in the top-level array for JSON input, its position among the bits the import finds for markup input. An entry that is not a bit gets no span, so the indexes can have gaps.
  • Each side is the bit's text, tight: never the separators between bits (\n, blank lines, ,) nor the JSON array's [ / ]. Both are counted in positionEncoding — "utf-16" by default, so output.slice(outputStart, outputEnd) is the bit — or "utf-8" bytes.
  • inputStart / inputEnd: for bitmark input, the bit's splitBits start / end; for JSON, its top-level entry; for markup, the element it was read from — one that holds the next bit's element (a NISO section around its paragraphs) ends where that element starts. Converting an output back gives input spans equal to the output spans it was written with.
  • Output spans are reported for the document outputs: bitmark, json (compact or pretty), text, and the markup formats (html, xml, …). In bitmark output they equal splitBits(output)'s start / end.
  • A bit that writes nothing (an empty or _error bit in text) gets a zero-width output span where its text would start.
  • Only top-level bits get spans. For any other output (lex, ast, semantic-tokens, diagnostics, a mapping report) bitSpans is present with spans: []; without the flag it is absent.

The CLI's --bit-spans FILE and the daemon's convert option bitSpans: true (reply field bitSpans) return the same object.

  • bitAnchors — true adds result.bitAnchors: fixed points inside each bit, for keeping linked panes aligned inside a long bit, where the bit spans alone are only its two ends:
const { output, bitAnchors } = convertWithDetails(source, {
  inputFormat: "bitmark",
  outputFormat: "json",
  pretty: true,
  bitAnchors: true,
});
// bitAnchors = { positionEncoding: "utf-16",
//   anchors: [{ index, inputOffset, outputOffset }, …] }
for (const { index, inputOffset, outputOffset } of bitAnchors!.anchors) {
  console.log(index, source.slice(inputOffset).split("\n")[0], output.slice(outputOffset, outputOffset + 40));
}
  • An anchor pairs a source node's first character (inputOffset) with the first character of the value it produced (outputOffset): each body, footer and card block (paragraph, heading, list, image…), each list item, each card / side / variant / footer divider (====, --, ++, ==== footer ====) and each bit- or card-level tag (its [, to the value it wrote — for a repeatable tag, the element). Inline nodes have none.
  • Each bit also ends with an anchor: its last visible character, paired with the closing } of its bit value, so the parser / bitmark fields written after it fall between bits. It is always the bit's last anchor, so a consumer can tell it from the starts.
  • index is the bit, as in bitSpans. Anchors are ordered by index, then inputOffset; output offsets need not be in order — the configuration can write a tag's value before the body — so a consumer pairing panes keeps an in-order subset.
  • Reported for bitmark input to json (compact or pretty) or jsonl, and to HTML or XML (every markup output, compact or pretty), where an anchor's output offset is the < of the element the node produced and a bit's end is the < of its element's closing tag. A literal-format body is text, not an element, so it has none. For any other conversion bitAnchors is present with anchors: [], and without the flag it is absent. Offsets are counted in positionEncoding.

The CLI's --bit-anchors FILE and the daemon's convert option bitAnchors: true (reply field bitAnchors) return the same object.

createDocument(text: string, options?: DocumentOptions): BitmarkDocument

A handle on one text for an editor (PLAN-271): send it the editor's changes and each open view — one output of the text — answers with the edits that turn its previous output into the new one. Only the bits a change touched are converted again, so a keystroke in a large document costs milliseconds where re-converting it costs hundreds; the views' outputs are still exactly what convert writes. The contract is .zen/specs/API-IDC-incremental-document.tsp.

import { createDocument } from "@gmb/bitmark-parser";

const doc = createDocument(model.getValue(), { version: model.getVersionId() });
const json = doc.openView({ outputFormat: "json", pretty: true, bitSpans: true });
jsonModel.setValue(json.output!);

model.onDidChangeContent((e) => {
  // Monaco's ranges are 1-based; LSP's (and the handle's) are 0-based.
  const changes = e.changes.map((c) => ({
    range: {
      start: { line: c.range.startLineNumber - 1, character: c.range.startColumn - 1 },
      end: { line: c.range.endLineNumber - 1, character: c.range.endColumn - 1 },
    },
    text: c.text,
  }));
  const update = doc.applyChanges(model.getVersionId(), changes);
  for (const view of update.views) {
    // Every range is in the view's previous output: apply them together.
    jsonModel.applyEdits(view.edits.map(toMonacoEdit));
  }
  monaco.editor.setModelMarkers(model, "bitmark", doc.diagnostics().diagnostics.map(toMarker));
});
// … later
doc.free();
  • options: inputFormat ("bitmark" by default; "json", "jsonl" and the markup formats too), version (the editor's document version, default 0) and positionEncoding ("utf-16" by default) — every position in and out is counted in it.
  • openView(options) — options are convertWithDetails' (outputFormat: json, jsonl, text, bitmark or a markup format, plus mode, pretty, indent, spacesAroundValues, inlineStyle, includeUnknownProperties, bitSpans, bitAnchors). Returns a ViewUpdate with the whole output. closeView(view) closes it.
  • applyChanges(version, changes) — LSP content changes ({ range, text }, or { text } for the whole text), applied in order. Returns { views, inputError? }: one ViewUpdate per open view, with its edits (LSP TextEdits, ranges in its previous output) and, when asked for, its whole bitSpans / bitAnchors. A version not newer than the document's throws DocumentVersionError and changes nothing: re-send the text with setText(version, text), whose updates hold whole outputs.
  • JSON or markup input that does not parse (or parses but does not convert) changes no view: views is empty and inputError ({ message, range }) says where the text fails; every view keeps its last good output. When the text converts again, the edits lead from those last good outputs.
  • semanticTokens(range?, { tokensLayout }) — the tokens on range's lines (or of the whole text), and diagnostics() — the whole document's, the link check included. Bitmark input only.
  • JSON input is read in its entries and jsonl in its lines, so a change inside one entry converts only it; a markup export read back (each bit an element of its own) likewise. Other markup — a NISO document, whose bits come from nested elements — converts whole on every change, with the same answers.
  • The handle lives in wasm memory: call free() when done (a FinalizationRegistry frees a forgotten one when it is collected). It stays bound to the wasm variant that was active when it was created. Not in the bitmark-json variant (UnsupportedFeatureError).

canonicalize(input: string, options?: CanonicalizeOptions): string

Re-emit input in its own format in canonical form — the single same-format surface. mode: "optimized" (default, omit natural defaults) or "full" (all keys).

transform(input: string, options?: TransformOptions): string

Apply a patch document to a document, bit by bit, and re-emit it. transformParallel is the worker-thread variant returning a Promise<string>. Each bit is converted on its own and the parts are joined as convert joins them: with no patch and no hook, transform writes exactly what convert writes (PLAN-271), hooks or not.

  • patch — a PatchDocument, or the shorthand: a bare array of entries applied to every bit (build entries with patchEntry). Either form may be a JSON string. An entry's path is in one of two languages, told apart by its first character (one language per call; a mixed call is refused):
    • a JSON path addresses the bit JSON (title, quizzes[0].choices[1].choice, table.data[1][1], id[-1]) and the value is a JSON value;
    • a bitmark path addresses the bit as an author writes it and the value is bitmark source (see Bitmark paths below). Bitmark paths need bitmark input
  • a skipped entry — a bad path, an index out of range, a value the engine refuses, a precondition the target no longer meets — throws PatchError (diagnostics: { path, kind, severity, message }[]) rather than returning a document with the edit silently missing. Warnings (severity: "warning": patch-base-changed, patch-already-resolved) report changes that were applied and never throw
  • patch may also be a string of bitmark change proposals — see Change proposals below — applied to the input
  • applyProposals — apply the change proposals the input itself carries and mark each applied one resolved, recording date (default: today, UTC) and by
  • preHook / postHook — per-bit hooks; the pre-hook may return patches, an output-format override or drop. Hooks see the original bits, in order, before the document reshapes anything; a hook's patches apply after the document's
  • inputFormat, outputFormat, mode, pretty, indent, spacesAroundValues — as for convert. outputFormat (default "json") takes every per-bit format: "json", "jsonl", "bitmark", "text" or a mapping id such as "html" (per-bit text outputs are joined with newlines). The whole-document outputs "lex", "ast", "semantic-tokens" and "diagnostics" are refused with an unsupported error in every driver — use convert. An explicit inputFormat is honoured as given, patch or hooks or not; it is never re-detected from the content

A patch document addresses bits by their position (or id) in the input before any entry is applied, so it reads like a diff. An inserted or replacing bit is a JSON bit, or a string holding one bit of bitmark source:

{
  "version": 1,
  "entries": [
    {
      "select": { "index": 3, "id": "mc-014" },
      "patch": [{ "path": "title", "op": "set", "value": "New" }]
    },
    { "select": { "index": 9 }, "remove": true },
    { "select": { "index": 5 }, "bit": "[.note]\nIn its place" },
    {
      "insert": { "before": 4 },
      "bit": { "type": "article", "body": "Inserted" }
    },
    { "insert": { "before": 12 }, "bit": "[.article]\nAt the end of 12 bits" },
    { "select": { "index": 7 }, "move": { "before": 2 } },
    { "select": "all", "patch": [{ "lang": "de" }] }
  ]
}

A position (before: n) is "before input bit n", n from 0 to the bit count — the count is the end. It is a slot of the input, so it stays valid when bit n is itself removed or moved: it is where that bit was. A select with a bit and no insert replaces the bit in place; the slot keeps its patches. A bit may be the target of at most one remove, move or replacement entry: a second claim of any kind is rejected, naming the second of the conflicting entries. diff produces such a document from two versions of a file (below).

Bitmark paths

A bitmark path spells the thing it names the way an author writes it, so the same path works for every bit type and no JSON key name is needed:

| Path | Addresses | | --- | --- | | [@id], [!], [#], [&image] | the bit's first such tag; [@id][-1] the last, [-][1] the second [-…] | | [&image][@width] | [@width] in the run after [&image] — a chain is spelled like the chain | | $body | the bit's own text (tags, cards and footer untouched) | | $raw | everything after the bit header | | $card[1] | the whole second card; $card[1][0] its first side, $card[1][0][1] a variant | | $card[1][!], $card[1][-][1] | tags inside a card, by occurrence | | $card[1]$body, $card[1]$raw | a card's own text / whole content | | $footer | the ==== footer ==== section |

Values are bitmark source, breakscaped as an author would write it (a bare ] or a trailing ^ in a tag value is refused — use breakscapeText with location: "tag" for user data, and add subLocation: "attrValue" when the value is an inline-attr chain value such as a link: href); null is a valueless tag ([@x]). The ops are JSON Patch's (RFC 6902), with one addition. add puts the value where the path points: a member — $body, $raw, $footer, a section's content — is created or replaced; an indexed path ($card[1][-][1], $card[2]) gets the value INSERTED before the element there, an index equal to the count being the end ($card[2] on a two-card bit is a new last card, as is a bare $card); an unindexed tag path adds another occurrence after the last one on its own line ($card[1][-] twice gives white, green, blue, red). With add every slot is reachable, so a reorder is remove + add. remove removes a tag (a run head takes its whole run — [&image:u][@width:1] minus [&image] leaves nothing behind), a section, a body. replace replaces a tag's value, a section's content or a scope's text, and needs an existing target; on a tag, a value that is one whole tag ("[## Heading]" at [#]) replaces the tag as written, marker included. test changes nothing: the value at the path must still read as the value (whitespace runs aside), else the entry is refused as patch-conflict — the target changed since the entry was written. substitute, the one op outside the RFC, swaps the entry's find fragment, found exactly once in the addressed text, for the value. For add on a tag, a value that is one whole tag ("[+ orange]") goes in as written — any sigil in any slot; other text is the value of a tag of the path's own kind.

On JSON paths the same four RFC ops apply: add creates or replaces a key, or inserts before an array index (id[-], the RFC's -, is the end); test compares a JSON value by equality (a string with whitespace runs aside; absent reads as empty); substitute is bitmark-only.

Every edit is a splice of the bit's own source: the parser's tree is the address map, the rest of the bit keeps its formatting, and an edit that would change the structure outside the addressed scope — a ==== text ==== or ==== footer ==== that would swallow the cards after it, a bit header in a value — is refused with the bit untouched. convert(…, { outputFormat: "ast" }) shows the tree a path resolves against.

transform(doc, {
  outputFormat: "bitmark",
  patch: [
    { path: "$card[1][-]", op: "append", value: "green" },
    { path: "$card[0][!]", op: "set", value: "Milk (cold)" },
    { path: "$body", op: "set", value: "Think **twice**." },
  ],
});

diff(a: string, b: string, options?: DiffOptions): string

Semantic diff of two documents. Both sides are re-canonicalized and compared as bit JSON, so tag order, spacing, breakscaping and omitted defaults are not differences; every real change is rendered as the canonical bitmark an author would type. The inputs may be bitmark or JSON, and need not share a format.

@@ bit 1 -> 2 (id mc-014) [.multiple-choice] changed
 instruction[0]
-[!Pick one]
+[!Pick exactly one]
 quizzes[0]
 ====
 [-Bonn]
-[-Berlin]
+[+Berlin]
@@ bit 4 (id hero) [.image] removed
-[.image]
-[@id:hero]
-[&image:https://example.com/hero.png]

Bits are paired by id, then by sourceBB on the same sourceRL, then by exact content, then by text similarity; a bit whose position changed among the kept ones is reported moved. Empty output means the documents are semantically equal.

  • outputFormat — "bitmark" (default; the text above), "json" (one object per aligned bit, see diffBits), "patch" (a patch document that turns a into b — feed it to transform), or "bitmark-patch" (the same patch as change-proposal bits, one per change — see Change proposals)
  • paths — the path language of a "patch" output: "json" (default) or "bitmark" (bitmark inputs). A bitmark-path patch is derived from A's source and verified: each bit's entries are applied to A and kept only when the result means B — fine tag and text edits first, whole cards next, the bit's whole content last
  • pairLeftovers — after every other stage, pair the bits still unpaired by type, in order, when both sides have as many of that type; a bit with an id takes no part (default: true)
  • inputFormat — applies to both sides (default: "auto", sniffed per side)
  • context — unchanged lines kept around each change (default: 3)
  • locate — add source line numbers to bit positions (bitmark inputs; default: false)
  • similarity — pairing threshold for bits with no id, box or exact match, 0..1 (default: 0.6; 1 disables)
  • bboxTolerance — pixels per coordinate for the sourceBB stage (default: 8)
  • spacesAroundValues — in the rendered bitmark lines (default: 0)
  • inlineStyle — the rendered bitmark's inline marks: "toggle" (default) or "legacy", as for convert, in every output — the hunks and both patch forms

The text layout and the JSON shape are stable contracts. A key the generator writes only together with others (a heading's level, inside its title tag) is shown in place, as the line reads (-[#Heading] / +[##Heading]). An unknown property is shown as a JSON line, since the generator cannot render it, and cannot be re-applied. In the JSON ops / revert, a value present on both sides is a replace and a new key an add; an array of objects (cards, choices, body nodes) is edited by element — remove at an index, add at an index (it inserts), a changed element in place — and replaced whole only when one side has none.

The bitmark-patch output (and patch with paths: "bitmark") describes each part of a bit — its own text, each card, side and variant — as tag and text edits wherever a path can say it: a test of the old value then a replace or remove, an add, a substitute of the changed fragment. A card that came, went, changed places or changed its sides is a whole card; what no path can say (a tag line added between two lines of text, for one) comes as the whole content. Not available on the bitmark-json variant (UnsupportedFeatureError).

Change proposals

A change proposal is a bit that carries an edit to another bit — written by a validator, a reviewer or diff(…, { outputFormat: "bitmark-patch" }), applied by transform. The bit types are config: [.bit-diff], and [.review-request-for-review-note] (a review note with a proposal). Each ==== patch ==== card (or plain ====) is one edit, applied in card order:

[.review-request-for-review-note]
[@diffRef:mc1]
[!Fix the choices and the hint]
==== patch ====
[@diffOp:substitute][@diffAt:body][@diffFind:think twice.]
--
think three times.
==== patch ====
[@diffOp:add][@diffAt:card/1/-/1]
--
[+ orange]
==== patch ====
[@diffOp:replace][@diffAt:raw]
--
[% item ][% lead ]
Anything goes here: [tags], **marks**, -- and ++ lines.
^====
[! A card ]
  • @diffRef — the target: an id, or #n for the n-th bit of the document (counting from 0; n equal to the bit count is the position after the last bit, for an add at bit only)
  • @diffBase — the target's fingerprint when the proposal was written; a mismatch on apply is a patch-base-changed warning (the test cards decide; a replace or remove of a tag without one is applied as it is, so test what a card replaces or removes) — unless the proposal overwrites what no test can check: a replace or remove of a whole card, side or variant, of raw or of the footer, or an add at raw or footer (which sets it) — or removes or replaces the whole bit (remove / replace at bit). It is then refused, nothing applied (patch-conflict): on a target that changed, such an edit would overwrite what it was not written against, and a target named by its place (#n) may be another bit by now. An add (which sets that text), a replace or a remove at body with no test of the same text before it is refused likewise when a text is there, and applied when the text is empty: test the text first, or use substitute. Leave @diffBase out to apply whatever the target now holds
  • @diffOp — add, remove, replace, test or substitute; at the path bit also move
  • @diffAt — a bitmark path, bracket-free so it fits in a tag: card/1/-/1 is $card[1][-][1], %/1 is [%][1], &image/@alt is [&image][@alt], body is $body, raw is $raw; bit is the whole target bit (bit/after: the slot after it, for add and move)
  • @diffFind — for substitute: the text to find and replace
  • the value — after --, written exactly as it appears in the target (for test: the value expected there): the side is read verbatim, so tags, marks, -- and ++ need no escaping. Two escapes, for what would otherwise end the card: a line starting with ==== (a value holding cards) is written ^====, and a line starting with [. (a value holding a whole bit) is written [^. — one ^ more per level, the same rule as plain-text bodies. Two things a card does not keep: space and blank lines at the start and end of the value, and — at the very end of the proposal's last card — the attributes of a mark the value cuts in half (figure==|link:x| reads figure==: name the whole mark instead). The proposals diff writes lose nothing this way

A whole-bit card (@diffAt:bit, the last card of its proposal) is the proposal's document-level op, with the same powers as a patch document: remove removes the target; replace replaces it, header included (a type change); add puts the value — a whole bit — before it; move puts the target before the bit the value names (#0: first; #n with n the bit count: last). Positions (#n) always mean the input's, whatever earlier proposals did.

To put a new or moved bit AFTER a bit instead, write the path bit/after (bit/before is accepted as the same as bit): an add lands after the target, a move after the bit its value names. @diffRef still names the bit the proposal is about — a transcript added after its audio bit:

[.bit-diff]
[@diffRef:audio-1]
==== patch ====
[@diffOp:add][@diffAt:bit/after]
--
[^.audio-transcript]
The words of the interview.

A proposal applies as a whole or not at all: a failed card, a precondition the target no longer meets, an edit that would leave the target with a new error or warning (a tag its bit does not allow), or a whole-bit card the document engine refuses (a bit removed or replaced by an earlier proposal, a bit moved twice) leaves the target untouched and throws PatchError naming the card. With applyProposals, each applied proposal is marked resolved (@resolved, @resolvedDate, @resolvedBy); a resolved one is not applied again.

const fixes = diff(oldDoc, newDoc, { outputFormat: "bitmark-patch" });
transform(oldDoc, { patch: fixes, outputFormat: "bitmark" }); // means newDoc
transform(book, { applyProposals: true, by: "validator", outputFormat: "bitmark" });

diffBits(a: string, b: string, options?: DiffOptions): BitDiff[]

The typed form of diff: one BitDiff per aligned bit, unchanged ones included so the alignment is complete — status (unchanged | changed | moved | removed | added), the a/b positions, ops (a patch turning the A bit into the B bit) and revert, the parser issue codes gained or lost, and the rendered hunks.

countBits(input: string): number / splitBits(input: string, options?: SplitBitsOptions): BitSlice[]

splitBits returns one { index, start, end, byteStart, byteEnd, source } per bit. start / end locate the bit's text, source, counted in options.positionEncoding — "utf-16" by default, so input.slice(start, end) === source — or "utf-8" bytes. byteStart / byteEnd are UTF-8 byte offsets that tile the document (each bit runs to the next bit's start), for chunking.

splitBits splits bitmark source into its bits without full parsing; countBits counts the bits of a bitmark, JSON or JSONL input. A JSON input may be an array or a single value, each entry a { bit: {…} } envelope or a bare bit object (the four shapes convert accepts). An entry that is not a bit is not counted — countBits, transform and diff work on the recognised bits and have no warnings channel; convert reports the skip.

semanticTokens(input: string, options?: SemanticTokensOptions): SemanticTokens

Parser-derived highlighting of bitmark source in the LSP semantic-tokens shape — the typed form of convert(input, { inputFormat: "bitmark", outputFormat: "semantic-tokens" }). The parser runs (never the validator; diagnostics stay on their own channel) and the AST is walked loss-lessly, so every character of the source is covered exactly once and the highlighting agrees with the JSON the same input produces: an unpaired ** is text, an unclosed [!tag is a tag flagged unclosed that ends at the ==== / -- after it, the body of a bit whose body format is not bitmark ([.code], ==== text ====) is plain text. Bitmark input only.

Options (SemanticTokensOptions, also ConvertOptions keys):

  • positionEncoding — "utf-16" (default; the LSP default, what browser editors index by) or "utf-8" (bytes). Echoed in the response.
  • tokensLayout — "lsp" (default): data, the LSP relative encoding, five integers per token (deltaLine, deltaStart, length, tokenType, tokenModifiers; the type is a legend index, the modifiers a bitset); or "absolute": tokens, one { line, start, length, type, modifiers } per token, 0-based, by name. Both carry legend and positionEncoding.

Lines break at \n, \r\n and \r; no token contains a line terminator. The legend orders are stable (a change is semver-major; new entries may be appended). Token types name sigil classes and syntax positions, never a bit or tag name; each has a recommended standard super type so an editor's default theme colours it — paste the table into a VS Code extension's semanticTokenTypes:

| type | covers | super type | | ---------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------- | | frontmatter | the region before the first bit | comment | | bitSigil | [., level dots, \|, :, &, ] of a bit header | keyword | | bitType / bitFormat / bitResourceType | the header's three fields | type / modifier / type | | tagSigil | every tag's own syntax ([@, [!, [##, :, ], …) | keyword | | propertyKey / resourceType | a property tag's key / a resource tag's type | property / type | | tagText | plain text inside any tag value | string | | cardDivider / sideDivider / variantDivider / footerDivider / textDivider | ====, --, ++, ==== footer ====, ==== text ==== | operator | | paragraphBreak | a \| paragraph break | operator | | headingSigil / heading | # / the heading's plain text | keyword / string | | listMarker | • , •1 , •+ , the indent | keyword | | imageSigil / imageSrc | \|image: / the source | keyword / string | | markSigil | a mark's open and close markers | operator | | bold / italic / highlight / light / inline | the marked text (in body text and bitmark++ values; a string value is one literal tagText) | string | | attrSigil / attrKey / attrValue | an attr chain's \| and : / key / value | operator / property / string | | url | a bare URL the parser auto-linked | string | | text | plain body / card / footer text, and every top-level gap | (none) | | plainText | a plain region (after ==== text ====, or a raw body) | string |

Modifiers, in bit order: the tag classes property, resource, title, reference, anchor, item, instruction, hint, true, false, gap, mark, solution (every token of a tag of that class, sigils included — exactly one per tag); comment (every token of a commented-out bit); unclosed (tokens inside a parser unclosed-mark / unclosed-tag notice); bold, italic, highlight, light (the text of an inline mark ==…==\|…\| whose chain carries that bare key — style it as you style the bold / italic / highlight / light token types). The full contract is .zen/specs/API-SEM-semantic-tokens.tsp.

diagnostics(input: string, options?: DiagnosticsOptions): Diagnostics

Every issue the JSON parser envelope would carry for bitmark source, as LSP 3.17 Diagnostics with editor positions — the typed form of convert(input, { inputFormat: "bitmark", outputFormat: "diagnostics" }). Parse and validate, no serialization: cheap enough for every keystroke. The validator owns every issue, so this is exactly the envelope's set — the same codes, the same spans, the same order (bit by bit) — with the envelope's buckets as LSP severities: errors → 1 (DiagnosticSeverity.Error), warnings → 2, infos → 3. Bitmark input only.

import { diagnostics, DiagnosticSeverity } from "@gmb/bitmark-parser";

const { positionEncoding, diagnostics: list } = diagnostics(source);
// list[i] = {
//   range: { start: { line, character }, end: { line, character } },  // 0-based, UTF-16 units
//   severity: 2,                        // DiagnosticSeverity.Warning
//   code: "tag-invalid",                // the contract — branch on this
//   source: "bitmark",
//   message: "[@nope] is not valid for [.article]",   // prose, may change
//   data: { bit: 0, scope: "bit" },     // the bit's index in the JSON array; the issue's scope
// }

Option: positionEncoding — "utf-16" (default) or "utf-8", as for semanticTokens; echoed in the response. The types (Diagnostic, Range, Position, DiagnosticSeverity) are written field for field as the protocol defines them, so a Diagnostic assigns to Monaco's marker input and to vscode-languageserver-types without a cast, and the package keeps its zero runtime dependencies. In every wasm variant. The contract is .zen/specs/API-EDT-editor-services.tsp.

complete(input, position, options?) / resolve(input, position, item, options?) / hover(input, position, options?)

The editor position queries, in LSP 3.17 shapes (PLAN-196, PLAN-202). Positions are 0-based { line, character } in positionEncoding units — "utf-16" by default, as for semanticTokens.

complete returns an LSP CompletionList of everything valid at the cursor:

| where the cursor is | what you get | | --- | --- | | a bit header's type ([.art) | every bit type (kind: Class), with its title | | a header's :format / &resource | the body formats / the resource types this bit allows | | a tag, or body / card / footer text | the tags valid in THAT scope — the bit body, a card variant, a chain — minus those already at their maximum, the ones the scope still requires sorted first (the first preselected) | | a tag's value | an enum tag's vocabulary, a boolean tag's true / false | | after a tag's ] | that tag's chain children | | an inline attribute chain (==x==\|bo) | the attribute keys, and the closed value set of one that has it | | a line holding a prefix of one (empty, =, ==== f) | the structural lines the bit's card set allows there (====, --, ++), ==== footer ====, ==== text ==== — each documented | | bitmark text (body text, a bitmark++ tag's value), after none, = or == | the inline mark ==…==\|…\| as a snippet (insertTextFormat: 2); never in a string value or a plain region |

Items carry kind, detail, tags: [1] when deprecated, sortText, insertText, and — in LSP's own data slot — the info record behind them, so you can build UI from fields rather than prose. isIncomplete is always false: every candidate for the context comes back and filtering by the typed prefix is the editor's job. A half-typed [@wi, [.art or ==x==\|bo resolves as if it were closed. A header resource attachment ([.flashcard&image]) is offered at the bit's level until it is there; a tag whose label is only its sigil (%, !) leads its detail with its name (item, instruction). The result adds one field beyond LSP, context, saying where the query resolved.

Pass triggerCharacter in the options when a character opened the query (LSP CompletionContext.triggerCharacter; Monaco and VS Code hand it to the provider). A trigger that opens nothing where the cursor is — a . or a - typed in prose — answers an empty list; [ opens a tag anywhere, and = / - / + narrow the list to the structural lines they begin. An explicit invocation (Ctrl+Space) is never narrowed. Editors that open the list on every letter (Monaco's quickSuggestions) should turn that off for bitmark: it is prose with markup in it.

Items carry NO documentation (PLAN-202): a header's list is every bit type, and its prose would be most of the bytes of every list. resolve is LSP's completionItem/resolve — pass the same input and position you gave complete plus one item as it was listed, and get that item back with its Markdown documentation (a bit's title and description; a tag's format, count, default, JSON key, chain and description in this scope; an inline attribute's shape). Wire it to Monaco's resolveCompletionItem or an LSP server's resolve handler, so only the item about to be shown is rendered. When the list at that position no longer holds the item, the item comes back as given.

hover returns an LSP Hover — Markdown contents plus the record in data — for the bit type, a tag AS RESOLVED IN ITS SCOPE (the same record info({ infoType: "bit", full: true }) shows for it there), a tag value, a header resource type, or an inline attribute key or value. It is null on body text, dividers and whitespace.

import { complete, resolve, hover, CompletionItemKind } from "@gmb/bitmark-parser";

const list = complete("[.article]\n[@", { line: 1, character: 2 });
list.context; // { bit: "article", scope: "bit" }
list.items.filter((i) => i.kind === CompletionItemKind.Property).map((i) => i.label);

const id = list.items.find((i) => i.label === "@id");
resolve("[.article]\n[@", { line: 1, character: 2 }, id).documentation.value; // Markdown for @id here

const h = hover("[.article]\n[@id:1]", { line: 1, character: 2 });
h.contents.value; // Markdown: format, count, default, JSON key, description
h.data.tag; // the info record for @id in this bit

Both need a variant built with editor (all three are) — otherwise they throw UnsupportedFeatureError. All three read bitmark SOURCE, so a JSON document is refused; an empty buffer, or one that is still only frontmatter, is source being typed and is answered normally (an empty one's complete offers the bit types). The CLI has the same three services under one command: bitmark editor diagnostics|complete|resolve|hover. The contract is .zen/specs/API-EDT-editor-services.tsp.

The lex and ast output formats

convert(input, { inputFormat: "bitmark", outputFormat: "lex" }) returns the lexer's token stream as a JSON array: one { kind, span, text } per token (the LexToken type), span in bytes. Debug tooling — the token kinds are the engine's own names, not a stable vocabulary, and the parser is never run (pairing, the card-set divider rule and raw-body handling all happen after lexing), so a highlighter should use semantic-tokens instead. Bitmark input only; a JSON or markup document has no source text to lex. The former lex() export and bitmark lex command were removed in 7.0 (see the migration guide).

convert(input, { inputFormat: "bitmark", outputFormat: "ast" }) returns the parser's tree as JSON — bits, their blocks (tag runs, body text, dividers) and inlines, every node with its byte span. Debug tooling like lex: the shape follows the parser and is not a contract. It shows what a bitmark patch path addresses (a run is one TagChain; a card is what sits between divider blocks). Not to be confused with the legacy entry point's "ast", which is bit JSON. Bitmark input only; in the same builds as lex.

breakscapeText(input: string, options?: BreakscapeOptions): string

Breakscape text (escape bitmark special characters).

  • format — "bitmark++" (default) or "plainText"
  • location — "body" (default), "cardBody", "tag" or "cardTag"
  • subLocation — "text" (default) or "attrValue"

subLocation REFINES location, it does not replace it. "attrValue" means the string is the value half of an inline-attr chain segment (==t==|link:VALUE|): it adds the chain delimiter | to the escaped set and drops the running-text rules (inline doubles, block markers), while location keeps deciding the tag rules — a [+trigger is escaped in body and inert in tag, a ] is inert in body and escaped in tag.

"cardBody" is a card side or variant body. It has the body rules plus the card dividers -- and ++, which are markup only inside a card set and only at the start of a line, where they break to -^- and +^+. "cardTag" is a tag's value inside a card set: the tag rules plus the same dividers, because a divider ends an open tag.

Reach for subLocation: "attrValue" when building a chain value for the patch API by hand; without it, an href containing [@ cannot be written correctly.

breakscapeText("http://x/a[@b]", { location: "body", subLocation: "attrValue" });
// → "http://x/a[^@b]"

Carets themselves follow one rule: a literal ^ is written ^^ except with format: "plainText" and location: "body", where it is written ^. Three cases land on the ^^ side although they read as though they would not — a tag value in a plain-format bit (the :text suffix switches the body only), an inline code mark (ordinary bitmark text carrying a mark), and an attr value or bare URL. A |code block body is raw, but it has no public format: the parser and generator apply that rule themselves at the block boundary.

unbreakscapeText(input: string, options?: BreakscapeOptions): string

Unbreakscape text (unescape bitmark special characters).

  • format — "bitmark++" (default) or "plainText"
  • location — "body" (default), "cardBody", "tag" or "cardTag"
  • subLocation — accepted and ignored

For bitmark++ the rule is "remove one caret from each run" whatever the context, so a single inverse undoes every breakscape mode.

template(options: TemplateOptions): string

The template of a bit (PLAN-225): an empty, config-filtered skeleton — the header, the tags an author usually writes (required ones, and those the config flags template) with their chains, the body, and the card structure (one card, every side, the first variant). Every value is the tag's default, so the plain rendering parses and canonicalizes cleanly.

  • bit — the bit name; required unless all is set
  • format — "text" (default; plain bitmark), "snippet" (an LSP snippet, insertTextFormat: 2: ${n:default} per value, a choice for enums and booleans with the default first, labelled body placeholders, $0 last), or "json" (the slot model — bit, attachment, tags[] with name, format, default, values, required, noValue (a tag that takes no value, written bare: a [%] chain lead), chain; body; card with its sides — plus the text and snippet renderings)
  • full — every tag in the bit's set plus the head chain of every resource type the bit may attach: a diagnostic dump, expected to validate with warnings (default false)
  • includeDeprecated — keep deprecated tags (and, with all, deprecated bits)
  • all — every bit as one JSON object { [bit]: { normal, full } }, whatever format says ("snippet" throws)
  • pretty / indent — JSON formatting
template({ bit: "multiple-choice" });
// [.multiple-choice]
// [@revealSolutions:false]
// [@additionalSolutions:]
//
// ====
// [+]
// [-]
// ====
template({ bit: "quote", format: "snippet" });
// [.quote]\n[@quotedPerson:${1}]\n${2:body}\n$0
JSON.parse(template({ bit: "image", format: "json" })).tags[0].name; // "&image"

Which tags are "usual" is configuration: a template member on a tag entry (true, false, or { "only": { "bits": [...], "bitGroups": [...] } } / { "except": … }), resolved by bitmark-confgen into a per-bit flag the info views show as template: true. Required tags are always in the template. A resource head flagged for a bit that can only reach it through a header attachment puts the attachment in the header ([.article&image]).

complete(input, position, { bitTemplate: true }) makes a bit-type item insert the bit's normal snippet from the name onward (article]⏎…) — the editor must then replace a ] it auto-closed after the cursor. Available in every wasm variant.

info(options?: InfoOptions): string

Query information about supported bit types. "bit"/"all" default to a compact view — one line per tag with its format, effective count and default, chains and card-set tags nested. With full: true they report the complete detail: body/footer/resource rules, default provenance (configured vs format-natural), nullability (absence as a distinct state — orthogonal to defaults), JSON keys, per-context overrides, and the card set structure. "deprecated" lists deprecated bits with their deprecation version and (separately) any migration target.

Some bits carry flags (provisional: new, not released to authors yet; private: internal). A flagged bit parses and converts like any other, but it is left out of "list", "all", "deprecated", the "bit-groups" members (a group whose bits are all flagged is left out too), editor completion and template({ all: true }). Looked up by name ("bit", hover) it is found, with its flags. bitmark.json lists the flag names (bitFlags) and each bit's flags.

  • infoType — "list" (default), "bit", "all", "deprecated", "bit-groups", "resource-groups", "languages", or "error-codes" (every issue code the