@knowvah/dot-engine 1.1.1 → 1.2.0

package/README.md

@@ -21,10 +21,18 @@ literal byte-for-byte SVG output — see [Conformance](./docs/conformance.md) fo
 the exact definition and the comparison code, and
 [known divergences](./docs/known-divergences.md) for the documented exceptions.
 
-> **Status: `0.1.x` — in active development, published to npm.** The port is
-> mature enough to lay out and render real graphs across all engines; the C
-> feature surface is not 100% covered. The `dot` engine is the primary
-> fidelity target. See [Status & coverage](#status--coverage) below.
+> **Status: published and semver-stable from 1.0.0.** The public API —
+> `renderSvg`, `/api`, `/render` — follows semver: a breaking change gets a
+> major bump. The version line does **not** track C feature coverage, and the
+> two are independent signals.
+>
+> The rendering surface is settled: parsing, all eight layout engines, SVG,
+> and the `json` / `xdot` / `dot` / `plain` / imagemap text formats. It does
+> not cover the whole C feature surface, and the remainder is **out of scope
+> rather than pending** — the unported C areas stay inventoried in the
+> [port catalog](./plans/port-catalog/README.md) so you can check a specific
+> feature before depending on it. The `dot` engine is the primary fidelity
+> target. See [Status & coverage](#status--coverage) below.
 
 ## Why this exists
 
@@ -261,32 +269,39 @@ from the canonical C Graphviz. New behavior is pinned to the C source — see
 ## Status & coverage
 
 - **What works:** parsing, all eight layout engines, SVG output, and the
-  intermediate `json` / `xdot` / `dot` / imagemap text formats.
+  intermediate `json` / `xdot` / `dot` / `plain` / imagemap text formats.
 - **Conformance bar:** a render is **conformant** when it matches the C oracle
   within a ±0.01 deterministic tolerance (`dot`, `circo`, `twopi`, `osage`,
   `patchwork`) or is characterized at a looser ±0.5 tolerance for the
   iterative force-directed engines (`neato`, `fdp`, `sfdp`) — never literal
   byte equality. Full definition: [Conformance](./docs/conformance.md).
-- **Current parity** (fresh corpus sweeps, dated 2026-07-11 — see
-  [`test/corpus/PARITY.md`](./test/corpus/PARITY.md) and the
-  [docs-site parity pages](https://knowvah.github.io/dot-engine/engines) for
-  live counts): `dot` SVG 762/788 conformant (+14 structural-match, 0
-  unaccepted tracked gaps — every remaining non-conformant graph is a
-  documented, accepted divergence); `dot` xdot 754/759; `circo` xdot 745/762;
-  `twopi` xdot 740/762; `osage` xdot 744/759; `patchwork` xdot 757/762
-  (all deterministic, ±0.01). `neato`/`fdp`/`sfdp` are characterized at ±0.5
-  rather than gated at the deterministic bar, per the tolerance split above.
+- **Current parity:** `dot` SVG 762/788 conformant (0 unaccepted tracked gaps —
+  every remaining non-conformant graph is a documented, accepted divergence);
+  `dot` xdot 761/761; `patchwork` xdot 762/762; `osage` xdot 755/762; `circo`
+  xdot 752/762; `twopi` xdot 746/762 (all deterministic, ±0.01).
+  `neato`/`fdp`/`sfdp` are characterized at ±0.5 rather than gated at the
+  deterministic bar, per the tolerance split above. These figures are a
+  snapshot of one row each from [`test/corpus/PARITY.md`](./test/corpus/PARITY.md),
+  which is generated by `test/corpus/parity-report.ts` and covers every
+  engine × surface track (SVG, xdot, json, plain, imagemap); read it, or the
+  [docs-site parity pages](https://knowvah.github.io/dot-engine/engines),
+  rather than this bullet for current counts.
 - **What's tracked:** every C algorithm and its port status is inventoried in
   the [port catalog](./plans/port-catalog/README.md). Items marked `[ ]` there
-  are real gaps, not footnotes.
+  are genuinely unported — not footnotes, and not a roadmap either. Treat the
+  catalog as the authoritative answer to "is feature X in?".
 - **Known behavioral divergences from C** (differences investigated,
   root-caused, and deliberately not chased) are listed in
   [`docs/known-divergences.md`](./docs/known-divergences.md).
 
 ## Known limitations
 
-- **Feature coverage is incomplete.** The C source defines completeness; gaps
-  are tracked in the port catalog rather than hidden.
+- **The feature surface is narrower than C's, by design.** The C source
+  defines completeness, and this port does not reach it. The uncovered areas
+  are listed in the [port catalog](./plans/port-catalog/README.md) rather than
+  hidden — check it before depending on a specific C feature. They are not a
+  backlog; absence from the shipped surface is a scope decision, not a
+  pending item.
 - **Very large graphs are impractical to lay out at runtime.** Graphs beyond
   roughly 10k nodes or a few MB of DOT source hit a scale ceiling — layout
   (mincross, ranking, spline routing) is superlinear. This is **shared with

package/dist/api.js

@@ -67,6 +67,30 @@ var Graph = class {
    * @see lib/cgraph/graph.c:agsubg (attr defval copy)
    */
   graphDefaultsSnapshot;
+  /**
+   * Keys in `attrs` the BUILDER seeded from `graphDefaultsSnapshot` rather than
+   * the input declaring them in this scope (see builder.ts GRAPH_LABEL_INHERIT_
+   * KEYS). cgraph distinguishes these structurally — a seeded value is inherited
+   * through the dict view and has no local symbol, while a local declaration
+   * creates one even when its value equals the inherited value — so the
+   * serializer needs the provenance to decide what write_dict would print.
+   * Undefined on the root graph and on any scope that seeded nothing.
+   * @see lib/cgraph/write.c:262 write_dict
+   */
+  seededAttrs;
+  /**
+   * Graph-attribute keys whose declaration in THIS scope was the first anywhere
+   * in the graph. cgraph's `setattr` splits on exactly this: a key with no
+   * existing symbol takes the global-declaration branch, which ends up seeding
+   * every direct subgraph that already exists with a local empty value (see
+   * `eagerEmptyParts`); a key some earlier scope already declared takes the
+   * "new local definition" branch and touches no subgraph at all. So an
+   * identical `graph [fill=x]` statement makes a child print `fill=""` or print
+   * nothing purely according to whether a SIBLING declared `fill` first.
+   * Undefined on any scope that declared nothing new.
+   * @see lib/cgraph/attr.c:257 setattr (lsym / psym / global branches)
+   */
+  firstGraphDecl;
   /**
    * Layout-engine info; replaces GD_* macros via agbindrec (AD-1).
    * @see lib/cgraph/cgraph.h:agbindrec