@mailwoman/core 3.0.0 → 4.0.0

package/out/pipeline/span-logit-aggregation.js

@@ -32,8 +32,9 @@
  * @param logits Per-token logits from ONNX inference, shape `[seqLen][numLabels]`.
  * @param pieces Token pieces with character-level offsets (from the tokenizer's `encode`).
  * @param spans Phrase-grouper span proposals in character offsets.
- * @param opts Options — `topK` (default 3), `labels` (required — the BIO label vocabulary the model
- *   emits, e.g. `["O", "B-locality", "I-locality", ...]`).
+ * @param opts Options bag.
+ * @param opts.topK Number of top-scoring tags to return per span (default 3).
+ * @param opts.labels The BIO label vocabulary the model emits, e.g. `["O", "B-locality", ...]`.
  */
 export function aggregateSpanLogits(logits, pieces, spans, opts) {
     const topK = opts.topK ?? 3;

package/out/pipeline/span-logit-aggregation.js.map

@@ -1 +1 @@
-{"version":3,"file":"span-logit-aggregation.js","sourceRoot":"","sources":["../../pipeline/span-logit-aggregation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"span-logit-aggregation.js","sourceRoot":"","sources":["../../pipeline/span-logit-aggregation.ts"],"names":[],"mappings":"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"}

package/out/pipeline/types.d.ts

@@ -156,6 +156,8 @@ export interface ClassifierOpts {
     queryShape?: QueryShapeLite;
     fst?: FstMatcherLike;
     fstBiasScale?: number;
+    /** Run the deterministic postcode regex repair pass (v0.7 #35) on the decoded labels. */
+    postcodeRepair?: boolean;
 }
 export interface AddressClassifier {
     parse(text: string, opts?: ClassifierOpts): Promise<AddressTree>;

package/out/pipeline/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../pipeline/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../pipeline/types.ts"],"names":[],"mappings":"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"}

package/out/resolver/resolve.js

@@ -20,6 +20,18 @@ import { DEFAULT_PLACETYPE_MAP, } from "./types.js";
 export function createWofResolver(backend) {
     return new WofResolver(backend);
 }
+/** Find the first postcode value anywhere in the tree (a one-shot pre-scan; postcode and locality are
+ * siblings, so the top-down walk wouldn't otherwise let the locality lookup see it). */
+function firstPostcodeValue(roots) {
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (n.tag === "postcode" && n.value.trim().length > 0)
+            return n.value.trim();
+        stack.push(...n.children);
+    }
+    return undefined;
+}
 class WofResolver {
     #backend;
     constructor(backend) {
@@ -33,6 +45,9 @@ class WofResolver {
             placetypeMap: opts.placetypeMap ?? DEFAULT_PLACETYPE_MAP,
             minWinningScore: opts.minWinningScore ?? 0,
             candidatesPerLookup: opts.candidatesPerLookup ?? 5,
+            defaultCountry: opts.defaultCountry,
+            parentFallback: opts.parentFallback ?? true,
+            postcode: firstPostcodeValue(tree.roots),
         };
         const newRoots = [];
         for (const root of tree.roots) {
@@ -65,17 +80,34 @@ class WofResolver {
             placetype,
             limit: state.candidatesPerLookup,
         };
-        // Pass the inherited parent constraint to the backend when available — both `parentId` and
-        // `country` are valid narrowing hints depending on what the parent resolved to.
-        if (parentResolved) {
-            if (typeof parentResolved.id === "number")
-                query.parentId = parentResolved.id;
-            if (parentResolved.country)
-                query.country = parentResolved.country;
-        }
+        // Pass the inherited parent constraint to the backend when available — `parentId` scopes to
+        // the resolved parent's descendants. For `country`: a resolved parent's country wins, else
+        // fall back to the caller's `defaultCountry`. Without this top-level hint a bare "IL" over a
+        // multi-country gazetteer fuzzy-matches a foreign place (e.g. a French region) — see the
+        // Direction-C resolver eval.
+        if (parentResolved && typeof parentResolved.id === "number")
+            query.parentId = parentResolved.id;
+        const country = parentResolved?.country ?? state.defaultCountry;
+        if (country)
+            query.country = country;
+        // Coordinate-first: hand the sibling postcode to locality lookups so the backend can inject
+        // postcode-proximal candidates the name-match would miss. Only for locality (the placetype both
+        // `locality` and `dependent_locality` map to); other placetypes ignore it.
+        if (placetype === "locality" && state.postcode)
+            query.postcode = state.postcode;
         let candidates;
         try {
             candidates = await this.#backend.findPlace(query);
+            // Parent soft-gating: `parentId` is a HARD descendant filter in the backend, which wrongly
+            // zeroes the result when the parent resolved wrong OR the gazetteer hierarchy is incomplete
+            // (a real locality whose `ancestors` chain is missing its region). Rather than turn a
+            // resolvable node into an unresolved one, retry once WITHOUT the parent constraint — we
+            // prefer a parent-scoped hit but never sacrifice recall. The country constraint is kept, so
+            // this still can't wander to a foreign place. Same logical resolution → no extra budget.
+            if (candidates.length === 0 && state.parentFallback && query.parentId !== undefined) {
+                delete query.parentId;
+                candidates = await this.#backend.findPlace(query);
+            }
         }
         catch {
             // Defensive: a backend failure should not abort the whole tree walk. Leave the node with
@@ -111,6 +143,16 @@ function decorateNode(node, resolved, alternatives) {
     node.lat = resolved.lat;
     node.lon = resolved.lon;
     node.placeId = `wof:${resolved.id}`; // v1: only WOF resolvers; the URI scheme stays this simple
+    // Record the resolver's ranking score AND the resolved place's CANONICAL name. The name is the
+    // gazetteer's truth for the place we picked — distinct from `node.value` (the raw input span). It
+    // lets consumers display the canonical name and lets the end-to-end eval check the resolver chose
+    // the right PLACE (gazetteer-name vs ground-truth) rather than merely echoing the parser's text.
+    node.metadata = { ...(node.metadata ?? {}), resolver_score: resolved.score, resolver_name: resolved.name };
+    // The postcode/locality conflict flag (the falsehood differentiator): the postcode pointed to a
+    // geographically different place than the parsed city name. Surface it so callers can warn rather
+    // than silently trust the resolved point.
+    if (resolved.mismatch)
+        node.metadata["postcode_city_mismatch"] = true;
     if (alternatives.length > 0) {
         node.alternatives = alternatives;
     }

package/out/resolver/resolve.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../resolver/resolve.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../resolver/resolve.ts"],"names":[],"mappings":"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"}

package/out/resolver/types.d.ts

@@ -38,6 +38,13 @@ export interface ResolvedPlace {
      * defined; callers should treat as ordinal.
      */
     score: number;
+    /**
+     * Set when the resolver detected that the address's postcode and its parsed locality name point to
+     * geographically different places (a transposed / wrong-for-the-city postcode). Surfaced onto the
+     * resolved node's metadata as `postcode_city_mismatch` so callers can lower confidence or flag the
+     * conflict instead of silently mislocating.
+     */
+    mismatch?: boolean;
 }
 /**
  * Pull-based contract for a single resolver query. The resolver knows nothing about `AddressTree` —
@@ -52,6 +59,13 @@ export interface ResolverBackend {
         placetype?: string | string[];
         country?: string;
         parentId?: number | string;
+        /**
+         * Sibling postcode string, when the address carries one. A coordinate-first backend uses it to
+         * inject postcode-proximal locality candidates (the postcode→locality table) and soft-score
+         * them against the parsed name — recovering localities the name-match alone misses. Backends
+         * without postcode support ignore it.
+         */
+        postcode?: string;
         limit?: number;
     }): Promise<ResolvedPlace[]>;
 }
@@ -75,6 +89,22 @@ export interface ResolveOpts {
      * candidate after post-scoring, but the backend may benefit from over-fetching for ranking.
      */
     candidatesPerLookup?: number;
+    /**
+     * Default ISO-3166 alpha-2 country to constrain top-level lookups to, when no resolved parent has
+     * supplied a country yet. Without it, a bare component over a multi-country gazetteer (e.g. "IL")
+     * can fuzzy-match a foreign place. Callers should set this from the detected locale (the
+     * pipeline's locale-gate). A resolved parent's country still overrides it deeper in the tree.
+     */
+    defaultCountry?: string;
+    /**
+     * When a resolved parent constrains a child lookup (`parentId` is passed to the backend as a hard
+     * descendant filter) and that filtered lookup returns NOTHING, retry the lookup once without the
+     * parent constraint. Guards against an incomplete gazetteer hierarchy (a real locality whose
+     * ancestor chain is missing its region) or a mis-resolved parent silently turning a resolvable
+     * node unresolved. The country constraint is retained on the retry, so resolution still can't
+     * wander cross-border. Default true. Set false to measure the strict-parent baseline.
+     */
+    parentFallback?: boolean;
     /**
      * Override the default ComponentTag → resolver-placetype mapping. When set, this map FULLY
      * REPLACES `DEFAULT_PLACETYPE_MAP` — start from the default by spreading it (`{

package/out/resolver/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEpE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,wDAAwD;IACxD,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;IACX,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC3B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,CAAC,KAAK,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;AAEhE,eAAO,MAAM,qBAAqB,EAAE,YAUnC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACxB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACxE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEpE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,wDAAwD;IACxD,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;IACX,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC3B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,CAAC,KAAK,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;QAC1B;;;;;WAKG;QACH,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,KAAK,CAAC,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;AAEhE,eAAO,MAAM,qBAAqB,EAAE,YAUnC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACxB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACxE"}

package/out/resolver/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmGH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IAClD,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,kBAAkB,EAAE,UAAU;IAC9B,SAAS,EAAE,QAAQ;IACnB,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,QAAQ,EAAE,YAAY;CACtB,CAAA"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../resolver/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiIH,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IAClD,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,kBAAkB,EAAE,UAAU;IAC9B,SAAS,EAAE,QAAQ;IACnB,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,QAAQ,EAAE,YAAY;CACtB,CAAA"}

package/out/resources/whosonfirst/PlacetypeDataSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlacetypeDataSource.d.ts","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAClB,KAAK,mBAAmB,EAGxB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAgB,KAAK,mBAAmB,EAAsB,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAEtE,MAAM,WAAW,0BAA0B,CAC1C,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,EACrD,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,GAAG,mBAAmB;IAExE,SAAS,EAAE,CAAC,CAAA;IACZ,YAAY,EAAE,CAAC,CAAA;IACf,aAAa,EAAE,eAAe,CAAA;CAC9B;AAED,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;OAEG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,UAAU;;WAGvC,UAAU,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,EAAE,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GACb,EAAE,IAAI,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,cAAc,GAAG,eAAe,CAAC,GASxE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IAGtC,aAAa,IAAI,IAAI;IAkBrB,cAAc,IAAI,IAAI;gBAejB,YAAY,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,mBAAmB;IAYnE,CAAC,MAAM,CAAC,OAAO,CAAC;IAIvB;;OAEG;IAEI,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC;IAgBhF;;;;OAIG;IACU,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B3D"}
+{"version":3,"file":"PlacetypeDataSource.d.ts","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAClB,KAAK,mBAAmB,EAGxB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAgB,KAAK,mBAAmB,EAAsB,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAEtE,MAAM,WAAW,0BAA0B,CAC1C,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,EACrD,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,GAAG,mBAAmB;IAExE,SAAS,EAAE,CAAC,CAAA;IACZ,YAAY,EAAE,CAAC,CAAA;IACf,aAAa,EAAE,eAAe,CAAA;CAC9B;AAED,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;OAEG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,UAAU;;WAGvC,UAAU,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,SAAS,mBAAmB,GAAG,kBAAkB,EAAE,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GACb,EAAE,IAAI,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,GAAG,cAAc,GAAG,eAAe,CAAC,GASxE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IAGtC,aAAa,IAAI,IAAI;IAkBrB,cAAc,IAAI,IAAI;gBAejB,YAAY,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,mBAAmB;IAcnE,CAAC,MAAM,CAAC,OAAO,CAAC;IAIvB;;OAEG;IAEI,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,cAAc,CAAC,eAAe,CAAC;IAgBhF;;;;OAIG;IACU,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B3D"}

package/out/resources/whosonfirst/PlacetypeDataSource.js

@@ -50,7 +50,9 @@ export class PlacetypeDataSource {
 		`);
     }
     constructor(databasePath, dbOptions) {
-        this.#db = new DatabaseSync(databasePath.toString(), dbOptions);
+        this.#db = dbOptions
+            ? new DatabaseSync(databasePath.toString(), dbOptions)
+            : new DatabaseSync(databasePath.toString());
         // node:sqlite has no .pragma() helper; pragmas are executed as plain SQL.
         this.#db.exec("PRAGMA busy_timeout = 10000");
         this.#db.exec("PRAGMA journal_mode = WAL");

package/out/resources/whosonfirst/PlacetypeDataSource.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlacetypeDataSource.js","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAElB,eAAe,EACf,qBAAqB,GACrB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAgD,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmDrD;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC/B,GAAG,CAAc;IAEV,MAAM,CAAC,UAAU,CAAqF,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GAC2E;QACxF,MAAM,sBAAsB,GAAG,qBAAqB,CAAC,YAAY,CAAC;YACjE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC;YACnC,CAAC,CAAC,YAAY,CAAA;QAEf,OAAO,WAAW,CAAC,IAAI,CACtB,aAAa,EACb,SAAS,EACT,GAAG,sBAAsB,KAAK,CACa,CAAA;IAC7C,CAAC;IAEM,aAAa;QACnB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;;;;GAcvB,CAAC,CAAA;IACH,CAAC;IAEM,cAAc;QACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;GAWvB,CAAC,CAAA;IACH,CAAC;IAED,YAAY,YAA6B,EAAE,SAA+B;QACzE,IAAI,CAAC,GAAG,GAAG,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAA;QAE/D,0EAA0E;QAC1E,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAEzC,IAAI,CAAC,aAAa,EAAE,CAAA;QACpB,uBAAuB;IACxB,CAAC;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;IAED;;OAEG;IAEI,IAAI,CAAC,QAAkC;QAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;WAGpC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;aAC3B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,OAAO,GAAG,EAAE,CAAC;aAChC,IAAI,CAAC,MAAM,CAAC;GACd,CAAC,CAAA;QAEF,4FAA4F;QAC5F,2DAA2D;QAC3D,OAAO,QAAQ,CAAC,IAAI,CACnB,SAAS,CAAC,OAAO,CAAC,QAAoD,CAAC,CACzB,CAAA;IAChD,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,MAAM,CAAC,MAAuB;QAC1C,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;IAsB5C,CAAC,CAAA;YAEF,SAAS,CAAC,GAAG,CAAC,MAAkD,CAAC,CAAA;QAClE,CAAC,CAAA;QAED,MAAM,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;IACjC,CAAC;CACD"}
+{"version":3,"file":"PlacetypeDataSource.js","sourceRoot":"","sources":["../../../resources/whosonfirst/PlacetypeDataSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,kBAAkB,EAElB,eAAe,EACf,qBAAqB,GACrB,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAgD,MAAM,aAAa,CAAA;AACxF,OAAO,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmDrD;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC/B,GAAG,CAAc;IAEV,MAAM,CAAC,UAAU,CAAqF,EAC5G,SAAS,EACT,YAAY,EACZ,aAAa,GAC2E;QACxF,MAAM,sBAAsB,GAAG,qBAAqB,CAAC,YAAY,CAAC;YACjE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC;YACnC,CAAC,CAAC,YAAY,CAAA;QAEf,OAAO,WAAW,CAAC,IAAI,CACtB,aAAa,EACb,SAAS,EACT,GAAG,sBAAsB,KAAK,CACa,CAAA;IAC7C,CAAC;IAEM,aAAa;QACnB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;;;;GAcvB,CAAC,CAAA;IACH,CAAC;IAEM,cAAc;QACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;GAWvB,CAAC,CAAA;IACH,CAAC;IAED,YAAY,YAA6B,EAAE,SAA+B;QACzE,IAAI,CAAC,GAAG,GAAG,SAAS;YACnB,CAAC,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC;YACtD,CAAC,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAA;QAE5C,0EAA0E;QAC1E,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAA;QAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAEzC,IAAI,CAAC,aAAa,EAAE,CAAA;QACpB,uBAAuB;IACxB,CAAC;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IACjB,CAAC;IAED;;OAEG;IAEI,IAAI,CAAC,QAAkC;QAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;WAGpC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;aAC3B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,OAAO,GAAG,EAAE,CAAC;aAChC,IAAI,CAAC,MAAM,CAAC;GACd,CAAC,CAAA;QAEF,4FAA4F;QAC5F,2DAA2D;QAC3D,OAAO,QAAQ,CAAC,IAAI,CACnB,SAAS,CAAC,OAAO,CAAC,QAAoD,CAAC,CACzB,CAAA;IAChD,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,MAAM,CAAC,MAAuB;QAC1C,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;IAsB5C,CAAC,CAAA;YAEF,SAAS,CAAC,GAAG,CAAC,MAAkD,CAAC,CAAA;QAClE,CAAC,CAAA;QAED,MAAM,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;IACjC,CAAC;CACD"}

package/out/resources/whosonfirst/placetypes/graph.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { PlacetypeRole } from "./definition.js";
+import { Placetype } from "./Placetype.js";
+/**
+ * A single node in a placetype graph. One entry per unique placetype name.
+ */
+export interface PlacetypeGraphNode {
+    name: string;
+    /** Brooklyn Integers ID. */
+    id: number;
+    role: PlacetypeRole;
+}
+/**
+ * A directed parent → child edge. Field names match d3-force / react-flow / cytoscape conventions
+ * so the graph drops straight into common viewers.
+ */
+export interface PlacetypeGraphLink {
+    source: string;
+    target: string;
+}
+/**
+ * Node-link projection of the placetype DAG rooted at a given placetype. Each node and each
+ * (parent, child) edge appears exactly once — see {@linkcode generatePlacetypeGraph} for why this is
+ * the preferred shape when the root has many shared descendants (e.g. `planet`).
+ */
+export interface PlacetypeGraph {
+    root: string;
+    nodes: PlacetypeGraphNode[];
+    links: PlacetypeGraphLink[];
+}
+/**
+ * Build a node-link graph of a placetype and its descendants, optionally filtered by role.
+ *
+ * Unlike {@linkcode generatePlacetypeTree}, this emits each node and each (parent, child) edge
+ * exactly once. WOF placetypes form a DAG with heavy descendant sharing (e.g. `installation` is a
+ * leaf reachable from many parents); projecting that DAG to a nested tree duplicates every shared
+ * subtree under every parent path and blows up exponentially for roots like `planet` (~165 MB for
+ * the full hierarchy). The graph shape stays O(nodes + edges) regardless.
+ *
+ * Output is well-suited for d3-force, react-flow, cytoscape, and any other HTML graph viewer.
+ */
+export declare function generatePlacetypeGraph(placetype: Placetype, roles?: Iterable<PlacetypeRole> | null): PlacetypeGraph;
+//# sourceMappingURL=graph.d.ts.map

package/out/resources/whosonfirst/placetypes/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,aAAa,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,kBAAkB,EAAE,CAAA;IAC3B,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,cAAc,CAsCnH"}

package/out/resources/whosonfirst/placetypes/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAgC1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB,EAAE,KAAsC;IAClG,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAE7C,MAAM,KAAK,GAAG,IAAI,GAAG,EAA8B,CAAA;IACnD,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAEhC,MAAM,OAAO,GAAG,CAAC,CAAY,EAAQ,EAAE;QACtC,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,OAAM;QAC7B,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IAC5D,CAAC,CAAA;IAED,MAAM,IAAI,GAAG,CAAC,IAAe,EAAQ,EAAE;QACtC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAErB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;YAChD,OAAO,CAAC,KAAK,CAAC,CAAA;YAEd,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAA;YAC5C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;gBACtB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YACtD,CAAC;YAED,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAQ;YACpC,IAAI,CAAC,KAAK,CAAC,CAAA;QACZ,CAAC;IACF,CAAC,CAAA;IAED,OAAO,CAAC,SAAS,CAAC,CAAA;IAClB,IAAI,CAAC,SAAS,CAAC,CAAA;IAEf,OAAO;QACN,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,KAAK;KACL,CAAA;AACF,CAAC"}

package/out/resources/whosonfirst/placetypes/index.d.ts

@@ -5,6 +5,8 @@
  */
 export * from "./admin.js";
 export * from "./definition.js";
+export * from "./graph.js";
 export * from "./mermaid.js";
 export * from "./Placetype.js";
+export * from "./tree.js";
 //# sourceMappingURL=index.d.ts.map

package/out/resources/whosonfirst/placetypes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,WAAW,CAAA"}

package/out/resources/whosonfirst/placetypes/index.js

@@ -5,6 +5,8 @@
  */
 export * from "./admin.js";
 export * from "./definition.js";
+export * from "./graph.js";
 export * from "./mermaid.js";
 export * from "./Placetype.js";
+export * from "./tree.js";
 //# sourceMappingURL=index.js.map

package/out/resources/whosonfirst/placetypes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,WAAW,CAAA"}

package/out/resources/whosonfirst/placetypes/mermaid.d.ts

@@ -3,18 +3,50 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  */
-import type { PlacetypeRole } from "./definition.js";
+import { type PlacetypeRole } from "./definition.js";
 import { Placetype } from "./Placetype.js";
 /**
- * Colors for placetype roles.
+ * Hand-tuned default colors for placetype roles. Used when no `interpolator` is passed to
+ * {@linkcode generateMermaidMarkup}. Each entry pairs a fill with a darker stroke and a text color
+ * chosen for contrast against the fill.
  */
 export declare const PlacetypeRoleColor: {
     readonly common: "#0066cc";
     readonly common_optional: "#00cc66";
     readonly optional: "#ffcc00";
 };
+/**
+ * A color interpolator — compatible with d3-scale-chromatic's `interpolate*` functions (e.g.
+ * `interpolateViridis`, `interpolateTurbo`). Receives `t ∈ [0, 1]` and returns a CSS color string.
+ */
+export type InterpolateColorCallback = (t: number) => string;
+export interface GenerateMermaidMarkupOptions {
+    /** Restrict descendants to the given roles. Default: all roles. */
+    roles?: Iterable<PlacetypeRole>;
+    /**
+     * Edge color interpolator. Each edge is colored by its child node's depth from the root: `t =
+     * (childDepth - 1) / (maxDepth - 1)`. This traces a smooth gradient along any lineage path (e.g.
+     * `planet → continent → country → …`) and gives a visual cue for how deep an edge sits in the
+     * tree.
+     *
+     * Defaults to d3-scale-chromatic's `interpolateViridis` — perceptually uniform and
+     * colorblind-friendly. Node fills/strokes are _not_ affected; they always use the hand-tuned
+     * {@linkcode PlacetypeRoleColor} palette, which carries more semantic weight than a sampled
+     * gradient for only three categorical role values.
+     */
+    edgeInterpolator?: InterpolateColorCallback;
+}
 /**
  * Generate a Mermaid flowchart markup for a placetype and its descendants.
+ *
+ * The walk is a recursive `findChildren` traversal — every emitted edge is a real direct-parent →
+ * direct-child relationship. WOF placetypes form a DAG (e.g. `borough` has both `country` and
+ * `macroregion` as parents), so a child can legitimately appear on multiple edges; the `visited`
+ * set prevents the subtree below it from being re-emitted.
+ *
+ * Edges are colored by depth from the root via
+ * {@linkcode GenerateMermaidMarkupOptions.edgeInterpolator} (default: viridis), so any lineage path
+ * traces a smooth gradient down the chart. Node fills always use the hand-tuned role palette.
  */
-export declare function generateMermaidMarkup(placetype: Placetype, roles?: Iterable<PlacetypeRole>): string;
+export declare function generateMermaidMarkup(placetype: Placetype, options?: GenerateMermaidMarkupOptions): string;
 //# sourceMappingURL=mermaid.d.ts.map

package/out/resources/whosonfirst/placetypes/mermaid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/mermaid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;CAImB,CAAA;AAElD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CA8BnG"}
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/mermaid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAa1C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;CAImB,CAAA;AAclD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AAE5D,MAAM,WAAW,4BAA4B;IAC5C,mEAAmE;IACnE,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAA;IAC/B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,wBAAwB,CAAA;CAC3C;AAuCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,4BAAiC,GAAG,MAAM,CA+C9G"}

package/out/resources/whosonfirst/placetypes/mermaid.js

@@ -3,19 +3,81 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  */
+import { rgb } from "d3-color";
+import { interpolateViridis } from "d3-scale-chromatic";
+import { PlacetypeRoles } from "./definition.js";
 import { Placetype } from "./Placetype.js";
 /**
- * Colors for placetype roles.
+ * Mermaid's `classDef` parser uses commas to separate style properties, so an `rgb(r, g, b)` value
+ * (which d3-scale-chromatic emits for several interpolators, e.g. `interpolateRainbow`,
+ * `interpolateTurbo`, `interpolateSinebow`) breaks the parse. Convert any d3-color-recognised input
+ * to hex before embedding. `d3-color` already handles hex/rgb/rgba/hsl/named inputs.
+ */
+function toMermaidColor(input) {
+    const parsed = rgb(input);
+    return Number.isNaN(parsed.r) ? input : parsed.formatHex();
+}
+/**
+ * Hand-tuned default colors for placetype roles. Used when no `interpolator` is passed to
+ * {@linkcode generateMermaidMarkup}. Each entry pairs a fill with a darker stroke and a text color
+ * chosen for contrast against the fill.
  */
 export const PlacetypeRoleColor = {
     common: "#0066cc",
     common_optional: "#00cc66",
     optional: "#ffcc00",
 };
+const PlacetypeRoleStroke = {
+    common: "#004d99",
+    common_optional: "#009933",
+    optional: "#cca300",
+};
+const PlacetypeRoleText = {
+    common: "white",
+    common_optional: "white",
+    optional: "black",
+};
+const HAND_TUNED_PALETTE = Object.fromEntries(PlacetypeRoles.map((role) => [
+    role,
+    { fill: PlacetypeRoleColor[role], stroke: PlacetypeRoleStroke[role], text: PlacetypeRoleText[role] },
+]));
+/**
+ * Walk the (filtered) subtree once to determine the deepest reachable descendant. Mirrors the
+ * structure of the emit-walk in {@linkcode generateMermaidMarkup} so the depths it computes line up
+ * with the edges that will be emitted. Cycles in the DAG are guarded by the `visited` set.
+ */
+function measureMaxDepth(root, roles) {
+    let maxDepth = 0;
+    const visited = new Set();
+    const walk = (node, depth) => {
+        for (const child of node.findChildren(roles)) {
+            const childDepth = depth + 1;
+            if (childDepth > maxDepth)
+                maxDepth = childDepth;
+            if (visited.has(child.name))
+                continue;
+            visited.add(child.name);
+            walk(child, childDepth);
+        }
+    };
+    walk(root, 0);
+    return maxDepth;
+}
 /**
  * Generate a Mermaid flowchart markup for a placetype and its descendants.
+ *
+ * The walk is a recursive `findChildren` traversal — every emitted edge is a real direct-parent →
+ * direct-child relationship. WOF placetypes form a DAG (e.g. `borough` has both `country` and
+ * `macroregion` as parents), so a child can legitimately appear on multiple edges; the `visited`
+ * set prevents the subtree below it from being re-emitted.
+ *
+ * Edges are colored by depth from the root via
+ * {@linkcode GenerateMermaidMarkupOptions.edgeInterpolator} (default: viridis), so any lineage path
+ * traces a smooth gradient down the chart. Node fills always use the hand-tuned role palette.
  */
-export function generateMermaidMarkup(placetype, roles) {
+export function generateMermaidMarkup(placetype, options = {}) {
+    const { roles, edgeInterpolator = interpolateViridis } = options;
+    const palette = HAND_TUNED_PALETTE;
     const lines = [
         "---",
         "config:",
@@ -24,21 +86,31 @@ export function generateMermaidMarkup(placetype, roles) {
         "---",
         "graph TD",
         "  linkStyle default stroke-width: 5",
-        `  classDef common fill:${PlacetypeRoleColor.common},stroke:#004d99,color:white,font-weight:bold`,
-        `  classDef common_optional fill:${PlacetypeRoleColor.common_optional},stroke:#009933,color:white,font-weight:bold`,
-        `  classDef optional fill:${PlacetypeRoleColor.optional},stroke:#cca300,color:black,font-weight:bold`,
+        ...PlacetypeRoles.map((role) => `  classDef ${role} fill:${palette[role].fill},stroke:${palette[role].stroke},color:${palette[role].text},font-weight:bold`),
+        // The root is never the target of an emitted edge, so declare it standalone so it picks
+        // up the role classDef and renders alongside the others.
+        `  ${placetype.name}:::${placetype.role}`,
     ];
-    const descendants = placetype.findDescendants(roles);
-    for (const [idx, descendant] of descendants.entries()) {
-        lines.push(`  ${placetype.name} --> ${descendant.name}:::${descendant.role}`);
-        lines.push(`  linkStyle ${idx} stroke:${PlacetypeRoleColor[descendant.role]}`);
-    }
-    for (const descendant of descendants) {
-        const children = descendant.findChildren(roles);
-        for (const child of children) {
-            lines.push(`  ${descendant.name} --> ${child.name}:::${child.role}`);
+    // Pre-compute max depth once so every edge's `t` is consistent across the second pass.
+    const maxDepth = measureMaxDepth(placetype, roles);
+    const visited = new Set();
+    let edgeIdx = 0;
+    const walk = (node, depth) => {
+        for (const child of node.findChildren(roles)) {
+            const childDepth = depth + 1;
+            // Single-level case: nothing to interpolate across, sample mid-gradient.
+            const t = maxDepth > 1 ? (childDepth - 1) / (maxDepth - 1) : 0.5;
+            const edgeColor = toMermaidColor(edgeInterpolator(t));
+            lines.push(`  ${node.name} --> ${child.name}:::${child.role}`);
+            lines.push(`  linkStyle ${edgeIdx} stroke:${edgeColor}`);
+            edgeIdx++;
+            if (visited.has(child.name))
+                continue;
+            visited.add(child.name);
+            walk(child, childDepth);
         }
-    }
+    };
+    walk(placetype, 0);
     return lines.join("\n");
 }
 //# sourceMappingURL=mermaid.js.map

package/out/resources/whosonfirst/placetypes/mermaid.js.map

@@ -1 +1 @@
-{"version":3,"file":"mermaid.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/mermaid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC,MAAM,EAAE,SAAS;IACjB,eAAe,EAAE,SAAS;IAC1B,QAAQ,EAAE,SAAS;CAC8B,CAAA;AAElD;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAoB,EAAE,KAA+B;IAC1F,MAAM,KAAK,GAAa;QACvB,KAAK;QACL,SAAS;QACT,cAAc;QACd,0BAA0B;QAC1B,KAAK;QACL,UAAU;QACV,qCAAqC;QACrC,0BAA0B,kBAAkB,CAAC,MAAM,8CAA8C;QACjG,mCAAmC,kBAAkB,CAAC,eAAe,8CAA8C;QACnH,4BAA4B,kBAAkB,CAAC,QAAQ,8CAA8C;KACrG,CAAA;IAED,MAAM,WAAW,GAAG,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;IAEpD,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,IAAI,QAAQ,UAAU,CAAC,IAAI,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7E,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,WAAW,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC/E,CAAC;IAED,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;QAE/C,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC,IAAI,QAAQ,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;QACrE,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACxB,CAAC"}
+{"version":3,"file":"mermaid.js","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/mermaid.ts"],"names":[],"mappings":"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"}

package/out/resources/whosonfirst/placetypes/tree.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { PlacetypeRole } from "./definition.js";
+import { Placetype } from "./Placetype.js";
+/**
+ * A node in the nested placetype tree produced by {@linkcode generatePlacetypeTree}.
+ *
+ * WOF placetypes form a DAG (a placetype can have multiple parents — `borough`, for example, is a
+ * direct child of both `country` and `macroregion`), so a tree projection rooted at a single
+ * placetype can list the same descendant under multiple branches. That repetition is expected.
+ */
+export interface PlacetypeTreeNode {
+    name: string;
+    id: number;
+    role: PlacetypeRole;
+    children: PlacetypeTreeNode[];
+}
+/**
+ * Build a nested tree of a placetype and its descendants, optionally filtered by role.
+ *
+ * The traversal mirrors {@linkcode Placetype.findChildren} — direct children only at each level,
+ * recursively. The DAG-to-tree projection may repeat descendants under multiple parents; if you
+ * need each placetype to appear exactly once, use {@linkcode Placetype.findDescendants} for a flat
+ * de-duplicated set instead.
+ */
+export declare function generatePlacetypeTree(placetype: Placetype, roles?: Iterable<PlacetypeRole> | null): PlacetypeTreeNode;
+//# sourceMappingURL=tree.d.ts.map

package/out/resources/whosonfirst/placetypes/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../../resources/whosonfirst/placetypes/tree.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,aAAa,CAAA;IACnB,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,iBAAiB,CAIrH"}