@gmb/bitmark-parser 7.7.0 → 7.9.0

package/README.md

@@ -71,7 +71,7 @@ runtime — the API surface never changes:
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
 | `full` (Node default)            | everything: rich `info` metadata + built-in translations + the semantic `diff`                                                                                                                         | ~1044 KB (~410 KB gzip) |
 | `browser-full` (browser default) | the same conversions and `diff`, without either                                                                                                                                                        | ~855 KB (~353 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, `info` (JSON only), breakscape, text fragments — no `diff` | ~629 KB (~256 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` | ~629 KB (~256 KB gzip) |
 
 **The rule.** _Every build includes every feature, except the two
 browser-targeted variants, which each carry an explicit exclusion list._ That
@@ -294,8 +294,8 @@ with each extra asked for by a flag in the options. `output` is exactly what
 one more flag and one more field each.
 
 - `bitSpans` — `true` adds `result.bitSpans`, where each top-level bit's text
-  landed in the output, for linking a source pane to an output pane bit by
-  bit:
+  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:
 
 ```ts
 const { output, bitSpans } = convertWithDetails(source, {
@@ -303,24 +303,32 @@ const { output, bitSpans } = convertWithDetails(source, {
   outputFormat: "html",
   bitSpans: true,
 });
-// bitSpans = { positionEncoding: "utf-16", spans: [{ index, start, end }, …] }
-for (const { index, start, end } of bitSpans!.spans) {
-  console.log(index, output.slice(start, end));
+// 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. An
-  entry that is not a bit gets no span, so the indexes can have gaps.
-- `start` / `end` are **the bit's text**, tight: never the separators
-  between bits (`\n`, blank lines, `,`) nor the JSON array's `[` / `]`. They
-  are counted in `positionEncoding` — `"utf-16"` by default, so
-  `output.slice(start, end)` is the bit — or `"utf-8"` bytes.
-- 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`.
+  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 span where its text would start.
+  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.
@@ -744,6 +752,56 @@ Unbreakscape text (unescape bitmark special characters).
 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`, `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
+
+```ts
+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
@@ -919,7 +977,9 @@ The normative definition of the JSON is
 
 #### version(): string
 
-Return the library version string.
+Return the library version string: the version the loaded wasm reports, so
+it is the parser actually running. Before a wasm is loaded (in the browser,
+before `init()`), the package's own version. Never throws.
 
 ### Typed API (generated types)
 
@@ -1081,7 +1141,8 @@ Differences (all loud, never silent):
   at the boundary). The markup produced _inside_ `<table>` follows this
   parser's html mapping and may differ from bpg's in detail.
   `keepUnknownTags` / `noBreakscaping` throw.
-- `version()` reports this package's version (6.x), not a bpg version.
+- `version()` reports this package's version (the loaded wasm's), not a bpg
+  version.
 
 ## CLI
 
@@ -1135,8 +1196,9 @@ bitmark convert input.bitmark --output-format semantic-tokens --tokens-layout ab
 # Dump the lexer token stream as JSON (debug tooling; bitmark input only)
 bitmark convert input.bitmark --input-format bitmark --output-format lex --pretty
 
-# Also write where each bit landed in the output, {positionEncoding, spans},
-# to its own file (offsets into this run's output; --position-encoding applies)
+# Also write where each bit is in the input and in the output,
+# {positionEncoding, spans}, to its own file (output offsets into this run's
+# output; --position-encoding applies)
 bitmark convert input.bitmark --output-format html -o out.html --bit-spans spans.json
 
 # Breakscape / unbreakscape text
@@ -1154,8 +1216,16 @@ bitmark info all -f json --pretty
 bitmark info --bit article          # compact: one line per tag (format, count, default)
 bitmark info --bit article --full   # full detail: defaults, provenance, keys, card set
 bitmark info deprecated             # deprecated bits + migration targets
-bitmark info list --all             # include deprecated bits in the listing
+bitmark info list --include-deprecated  # include deprecated bits in the listing
 bitmark info list --deprecated      # only deprecated bits
+
+# A bit's template: the tags an author usually writes, the body and the card
+# structure (PLAN-225) — plain bitmark, an LSP snippet, or JSON
+bitmark template --bit multiple-choice
+bitmark template --bit flashcard -f snippet
+bitmark template --bit article --full       # every tag + every attachable resource chain
+bitmark template --all --pretty             # every bit, both modes, keyed by name (JSON)
+bitmark editor complete input.bitmark --line 0 --character 2 --bit-template   # bit items insert their template
 ```
 
 All commands support `-o, --output <file>` and `-a, --append` flags. Commands that accept input support file paths, literal strings, or stdin (when no arguments are given).
@@ -1187,6 +1257,14 @@ selected variant's `.wasm` (from `dist/browser/wasm/`). A bare `init()` loads
 build, and a later `init({ feature: "full" })` upgrades in place (see _WASM
 variants_).
 
+The script and the `.wasm` are one release. Loaded through a version alias
+such as `@latest`, the script fetches the `.wasm` from the path pinned to its
+own version (`…/@gmb/bitmark-parser@<version>/…`), so a script served from a
+CDN cache after a release never drives the new release's wasm. `init()`
+rejects a `.wasm` of another version (`version-mismatch: …`) rather than
+running it; the glue can be instantiated once per page, so a reload is the
+remedy.
+
 ### Bundler (webpack / vite)
 
 ```js