@gmb/bitmark-parser 7.8.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
@@ -752,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
@@ -927,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)
 
@@ -1089,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
 
@@ -1163,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).
@@ -1196,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