figdown 0.4.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "figdown",
   "displayName": "FigDown",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A missing edge still looks fine. Text doesn't. FigDown keeps figures as text whose source states the meaning: participants, containment, field widths, table structure. The next reader can check it, not just look at it. Deterministic SVG, embedded in your Markdown — block diagrams, topologies, flowcharts, bit-level layouts, tables, timing waveforms.",
   "author": {
     "name": "FigDown",

package/dist/README.md

@@ -0,0 +1,85 @@
+# FigDown embeddable library
+
+Generated builds — do not edit; regenerate with `node tools/make-lib.js`
+(single engine source: `editor/figdown.html`).
+
+- `figdown.mjs` — ESM
+- `figdown.js` — UMD (CommonJS `require` or script tag → `globalThis.figdown`)
+
+No dependencies, no DOM needed; works in Node and browsers.
+
+## API
+
+- `parse(text)` → `{ doc, errors }` — `errors` is an array of
+  `"Line N: message"` strings (empty on success).
+- `render(text)` → `{ svg, errors }` — `svg` is `null` whenever there are
+  errors (determinism over convenience: no partial renders).
+- `renderDoc(doc)` → SVG string, for an already-validated `doc` from `parse`.
+- `artifact(text)` → `{ svg, errors }` — the self-carrying artifact: the
+  rendered SVG plus a
+  `<metadata id="figdown-source" data-sha256="…" data-engine-version="…">`
+  block embedding the source text, the SHA-256 **of that source**, and the
+  version string of the engine that rendered it — the same convention as
+  `tools/build-svg.js` (spec core §7). Synchronous and dependency-free
+  (bundled minimal SHA-256). `svg` is `null` on errors.
+- `version` — the **release version** of the engine in this build, the string
+  the artifact records in `data-engine-version` (spec core §13.0); reproducing
+  an artifact needs both it and the source (`RENDERING-DETERMINISM`).
+
+## The version numbers, and which is which
+
+Spec core §13.0 defines **two** version numbers, and neither of them is a
+property of this directory:
+
+- **`figdown X.Y`** versions the **language**. It is written in the `figdown`
+  header line of a `.fd` document and nowhere else. No API here returns it.
+- **`vX.Y.Z`** versions the **release** — this repository and its engine. It
+  is written in the git tag, in `package.json`, and in the
+  `data-engine-version` attribute of every artifact. `require('figdown').version`
+  returns that string.
+
+So the two strings a consumer can see — `require('figdown').version` and
+`package.json`'s `"version"` — are **the same number**, and until `v0.1.0` is
+tagged they are two different *pre-release spellings* of it: the engine
+carries the dated pre-release increment it was built from, and `package.json`
+carries the **npm pin** that names one published tarball, spelled
+`X.Y.Z-rc.N` while the release is a candidate. They converge at `v0.1.0`. The
+pin itself is **not restated here** — read it from `package.json`, which is
+its one home: a version burned on npm can never be republished, so the pin
+advances on every publish whether or not the engine moved, and a copy of it in
+prose is stale by the next one.
+`make-lib.js` reads the engine version out of the engine region, so there is
+no second copy of it to keep in step; the npm pin is edited by hand, and only
+when a release is published.
+
+## This directory is GATED
+
+`node tools/dist-check.js --strict` (`npm run gate:dist`) requires that
+regenerating these files is a byte-level no-op, that both builds report the
+engine's own version, that both load and produce identical SVG, and that every
+published `.fd` parses through `dist/figdown.js` with the same error set as the
+reference engine. Until 0.1 nothing in the repository read `dist/` at
+all, and a published tarball shipped a build of an older engine that rejected
+`index=` — a frozen key — and refused `examples/srh.fd`. Run the gate before
+publishing.
+
+## Integration example
+
+```js
+// ESM
+import { render, artifact } from './figdown.mjs';
+const { svg, errors } = render(source);
+if (errors.length) console.error(errors.join('\n'));
+else element.innerHTML = svg;
+
+// To save a file that carries its own source (round-trippable):
+const art = artifact(source).svg;
+```
+
+```html
+<!-- UMD script tag / CDN -->
+<script src="figdown.js"></script>
+<script>
+  const { svg, errors } = figdown.render(source);
+</script>
+```