@diagrammo/dgmo 0.8.23 → 0.8.26

package/docs/language-reference.md

@@ -768,6 +768,8 @@ kanban [Title]
 
 ### 10.2 Columns
 
+Columns represent workflow stages and must flow left-to-right from least-done to most-done (e.g., Backlog → In Progress → Done). Every column should be a stage that cards pass through. Don't create columns for non-workflow concepts like gates, criteria, or definitions of done — use a tag instead (e.g., `type: Gate`).
+
 ```
 [Column Name]
 [Column Name](color) | wip: 3
@@ -1134,29 +1136,51 @@ marker
 
 ## 15. Data Charts
 
+### Conventions shared across all data charts
+
+Every section under §15 follows the same two rules.
+
+**Rule A — data rows are space-separated.** Commas between values are tolerated for back-compat but not idiomatic. Thousands-separator commas *inside a single number* (`3,984,078.65`) are always supported.
+
+```
+Q1 400 700 300 500     ✅  preferred
+Q1 400, 700, 300, 500  ⚠  tolerated; use spaces
+```
+
+**Rule B — list-of-labelled-items directives (e.g. `series`, `columns`) prefer the indented one-per-line form.** Short one-line forms are tolerated for ≤3 items with no colour annotations or spaces.
+
+```
+series                            ✅  preferred
+  Cloud Platform (blue)
+  Legacy Suite (red)
+  Mobile App (green)
+
+series Cloud (blue), Legacy (red) ⚠  tolerated; prefer the block
+```
+
+Parsers accept either form. The rules above are authoring guidance.
+
 ### 15.1 Simple Charts (bar, line, pie, doughnut, area, polar-area, radar, bar-stacked)
 
 **Declaration:** `bar [Title]`, `line [Title]`, etc.
 
-**Series:**
+**Series** — follows Rule B (prefer the indented block):
 ```
-series Name1 Name2
 series
-  Name1
-  Name2(color)
+  Cloud Platform (blue)
+  Legacy Suite (red)
 ```
 
-Commas between series names are optional.
+Short one-line form is tolerated: `series Revenue` or `series A B`.
 
-**Data rows (space-separated, NO colon):**
+**Data rows** — follows Rule A:
 ```
 Label 100
 Label 100 200 300
 Label(color) 100
+Q1 400 700 300 500
 ```
 
-Commas between values are optional. Thousands commas are supported (`3,984,078.65` is a valid number).
-
 **Options (space-separated, NO colon):**
 ```
 title My Chart
@@ -1182,14 +1206,12 @@ era Day 1 -> Day 3 Rough Seas (red)
 
 ### 15.2 Scatter / Bubble Charts
 
-**Data rows (space-separated, NO colon):**
+**Data rows** — follows §15 Rule A (space-separated):
 ```
 Name x y
 Name x y size
 ```
 
-Commas between values are optional. Thousands commas supported.
-
 **Categories:**
 ```
 [Caribbean](red)
@@ -1208,20 +1230,21 @@ Labels are on by default. Use `no-labels` to hide point names.
 
 ### 15.3 Heatmap
 
-**Columns:**
+**Columns** — follows §15 Rule B (prefer the indented block for multiple columns):
 ```
-columns Jan Feb Mar
+columns
+  Jan
+  Feb
+  Mar
 ```
 
-Commas between column names are optional.
+Short one-line form is tolerated: `columns Jan Feb Mar`.
 
-**Data rows (space-separated, NO colon):**
+**Data rows** — follows §15 Rule A:
 ```
 RowLabel 5 4 3
 ```
 
-Commas between values are optional. Thousands commas supported.
-
 ### 15.4 Function Charts (Colon REQUIRED)
 
 ```
@@ -1254,7 +1277,7 @@ Source -> Target 3500
 Source -- Target 2000
 ```
 
-`->` = directed, `--` = undirected. Thousands commas supported in values.
+`->` = directed, `--` = undirected. Values follow §15 Rule A.
 
 ### 15.6 Chord Charts
 
@@ -1263,19 +1286,17 @@ Blackbeard -- Bonnet 150        // undirected
 Roberts -> Rackham 20           // directed
 ```
 
-Thousands commas supported in values.
+Values follow §15 Rule A.
 
 ### 15.7 Funnel Charts
 
-**Data rows (space-separated, NO colon):**
+**Data rows** — follows §15 Rule A (space-separated):
 ```
 Visits 1200
 Signups 800
 Purchases 200
 ```
 
-Thousands commas supported.
-
 ---
 
 ## 16. Visualizations
@@ -1297,7 +1318,7 @@ Roberts 12 52
     Before COVID
     After COVID
   ```
-- Data rows: `Label value1 value2` — space-separated, no colons, no commas between values
+- Data rows: `Label value1 value2` — follows §15 Rule A (space-separated; commas between values tolerated for back-compat but not idiomatic)
 - Thousands commas within values supported (e.g., `1,000`)
 - Color annotations: `Label (color) value1 value2`
 - Minimum 2 periods required
@@ -1364,9 +1385,9 @@ Quartermaster 0.9 0.95
 Navigator 0.85 0.8
 ```
 
-- Axis labels: `x-label Low, High` — comma-separated
+- Axis labels: `x-label Low, High` — comma-separated (low/high pair, not a data row; comma is the delimiter here by design)
 - Position labels: `top-right Label` — space-separated
-- Data points: `Label x y` or `Label x, y` — comma or space between coordinates
+- Data points: `Label x y` — follows §15 Rule A (space-separated; `Label x, y` tolerated for back-compat)
 
 ---
 

package/fonts/LICENSE-Inter.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/gallery/fixtures/bar-stacked.dgmo

@@ -2,9 +2,15 @@ bar-stacked Support Tickets by Priority
 x-label Month
 y-label Tickets
 
-series Critical (red), High (orange), Medium (yellow), Low (green), Info (blue)
-January 8, 24, 45, 62, 31
-February 12, 19, 51, 58, 28
-March 6, 22, 38, 71, 35
-April 10, 28, 42, 65, 40
-May 5, 15, 48, 70, 33
+series
+  Critical (red)
+  High (orange)
+  Medium (yellow)
+  Low (green)
+  Info (blue)
+
+January 8 24 45 62 31
+February 12 19 51 58 28
+March 6 22 38 71 35
+April 10 28 42 65 40
+May 5 15 48 70 33

package/gallery/fixtures/heatmap.dgmo

@@ -1,8 +1,14 @@
 heatmap Deploy Frequency by Day and Hour
 
-columns Mon, Tue, Wed, Thu, Fri
-6 AM 1, 2, 0, 1, 0
-9 AM 5, 8, 6, 7, 4
-12 PM 3, 4, 5, 3, 2
-3 PM 8, 12, 9, 10, 6
-6 PM 2, 3, 1, 2, 1
+columns
+  Mon
+  Tue
+  Wed
+  Thu
+  Fri
+
+6 AM 1 2 0 1 0
+9 AM 5 8 6 7 4
+12 PM 3 4 5 3 2
+3 PM 8 12 9 10 6
+6 PM 2 3 1 2 1

package/gallery/fixtures/multi-line.dgmo

@@ -2,10 +2,14 @@ multi-line Quarterly Revenue vs Operating Cost
 x-label Quarter
 y-label Amount ($M)
 
-series Revenue (blue), Operating Cost (red), Net Profit (green)
-Q1 2023 4.2, 3.1, 1.1
-Q2 2023 4.8, 3.3, 1.5
-Q3 2023 5.1, 3.5, 1.6
-Q4 2023 5.9, 3.7, 2.2
-Q1 2024 6.3, 3.9, 2.4
-Q2 2024 7.1, 4.2, 2.9
+series
+  Revenue (blue)
+  Operating Cost (red)
+  Net Profit (green)
+
+Q1 2023 4.2 3.1 1.1
+Q2 2023 4.8 3.3 1.5
+Q3 2023 5.1 3.5 1.6
+Q4 2023 5.9 3.7 2.2
+Q1 2024 6.3 3.9 2.4
+Q2 2024 7.1 4.2 2.9

package/gallery/fixtures/quadrant.dgmo

@@ -8,11 +8,11 @@ top-right Major Projects
 bottom-left Fill-ins
 bottom-right Avoid
 
-Dark Mode (blue) 0.25, 0.85
-API v2 (red) 0.8, 0.9
-Fix Typos 0.1, 0.15
-SSO Integration 0.75, 0.7
-Export CSV 0.3, 0.6
-Refactor Auth 0.85, 0.3
-Add Tooltips 0.15, 0.45
-Mobile App 0.9, 0.95
+Dark Mode (blue) 0.25 0.85
+API v2 (red) 0.8 0.9
+Fix Typos 0.1 0.15
+SSO Integration 0.75 0.7
+Export CSV 0.3 0.6
+Refactor Auth 0.85 0.3
+Add Tooltips 0.15 0.45
+Mobile App 0.9 0.95

package/gallery/fixtures/scatter.dgmo

@@ -3,19 +3,19 @@ x-label Funding ($M)
 y-label Annual Revenue ($M)
 
 [SaaS](blue)
-  Acme Cloud 12, 8.5
-  DataSync 5.2, 3.1
-  CloudOps 25, 18.4
-  PlatformX 8, 5.7
-  NexGen 3.5, 1.2
+  Acme Cloud 12 8.5
+  DataSync 5.2 3.1
+  CloudOps 25 18.4
+  PlatformX 8 5.7
+  NexGen 3.5 1.2
 
 [Fintech](green)
-  PayFlow 45, 32
-  LendTech 18, 12.5
-  CoinBase+ 60, 41
-  QuickPay 9, 6.8
+  PayFlow 45 32
+  LendTech 18 12.5
+  CoinBase+ 60 41
+  QuickPay 9 6.8
 
 [HealthTech](red)
-  MediScan 15, 7.2
-  HealthAI 22, 14.1
-  CareLink 7, 3.8
+  MediScan 15 7.2
+  HealthAI 22 14.1
+  CareLink 7 3.8

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.8.23",
+  "version": "0.8.26",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/diagrammo/dgmo.git"
+  },
+  "homepage": "https://github.com/diagrammo/dgmo#readme",
   "type": "module",
   "bin": {
     "dgmo": "dist/cli.cjs"
@@ -50,10 +55,12 @@
         "types": "./dist/internal.d.cts",
         "default": "./dist/internal.cjs"
       }
-    }
+    },
+    "./fonts/*": "./fonts/*"
   },
   "files": [
     "dist",
+    "fonts",
     "src",
     "docs",
     "gallery/fixtures",
@@ -82,7 +89,7 @@
     "check:deadcode": "knip",
     "check:spelling": "cspell \"src/**/*.ts\" \"tests/**/*.ts\"",
     "check:all": "pnpm check:deadcode && pnpm check:spelling && pnpm check:duplication && pnpm check:circular && pnpm check:deps && pnpm check:security && pnpm build && pnpm check:publish && pnpm check:types",
-    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>7){console.error('New circular deps found ('+n+' > 7 known type-only cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
+    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>10){console.error('New circular deps found ('+n+' > 10 known type-only cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
     "check:deps": "depcheck --ignores='@codemirror/language,@lezer/*,husky,lint-staged,tsup'",
     "check:security": "pnpm audit --prod",
     "check:publish": "publint",

package/src/boxes-and-lines/parser.ts

@@ -97,6 +97,7 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
   const groupLabels = new Set<string>();
   let lastNodeLabel: string | null = null;
   let lastSourceIsGroup = false;
+  let lastNodeIndent = 0;
 
   // Description collection state
   let descState: {
@@ -481,9 +482,14 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
       // Indented shorthand: `-> Target` or `-label-> Target`
       if (trimmed.startsWith('->') || /^-[^>].*->/.test(trimmed)) {
         // If the edge is at group-child indent level, use the containing group
+        // UNLESS lastNodeLabel is a plain node (not a group) — then the edge
+        // is indented under that node and should source from it.
         const gs = currentGroupState();
         const inGroup = gs && indent > gs.indent;
-        if (inGroup) {
+        // Edge is deeper than the last node → indented under that node, use it
+        const indentedUnderNode =
+          lastNodeLabel && !lastSourceIsGroup && indent > lastNodeIndent;
+        if (inGroup && !indentedUnderNode) {
           const sourcePrefix = `[${gs.group.label}]`;
           edgeText = `${sourcePrefix} ${trimmed}`;
         } else if (lastNodeLabel) {
@@ -530,6 +536,7 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
     }
     lastNodeLabel = node.label;
     lastSourceIsGroup = false;
+    lastNodeIndent = indent;
 
     const gs = currentGroupState();
     const isGroupChild = gs && indent > gs.indent;
@@ -616,7 +623,11 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
   if (result.tagGroups.length > 0) {
     injectDefaultTagMetadata(result.nodes, result.tagGroups);
     validateTagValues(result.nodes, result.tagGroups, pushWarning, suggest);
-    validateTagGroupNames(result.tagGroups, pushWarning);
+    validateTagGroupNames(result.tagGroups, pushWarning, (line, msg) => {
+      const diag = makeDgmoError(line, msg);
+      result.diagnostics.push(diag);
+      if (!result.error) result.error = diag.message;
+    });
   }
 
   return result;

package/src/boxes-and-lines/renderer.ts

@@ -488,19 +488,28 @@ export function renderBoxesAndLines(
         .attr('clip-path', `url(#${clipId})`)
         .attr('class', 'bl-collapse-bar');
 
-      // Label centered vertically
-      groupG
-        .append('text')
-        .attr('class', 'bl-group-label')
-        .attr('x', group.x)
-        .attr('y', group.y)
-        .attr('text-anchor', 'middle')
-        .attr('dominant-baseline', 'central')
-        .attr('font-family', FONT_FAMILY)
-        .attr('font-size', GROUP_LABEL_FONT_SIZE)
-        .attr('font-weight', '600')
-        .attr('fill', palette.text)
-        .text(group.label);
+      // Label centered vertically — wrap like regular nodes
+      const maxLabelLines = Math.max(
+        2,
+        Math.floor((group.height - 16) / (MIN_NODE_FONT_SIZE * 1.3))
+      );
+      const fitted = fitLabelToHeader(group.label, group.width, maxLabelLines);
+      const lineH = fitted.fontSize * 1.3;
+      const totalH = fitted.lines.length * lineH;
+      for (let li = 0; li < fitted.lines.length; li++) {
+        groupG
+          .append('text')
+          .attr('class', 'bl-group-label')
+          .attr('x', group.x)
+          .attr('y', group.y - totalH / 2 + lineH / 2 + li * lineH)
+          .attr('text-anchor', 'middle')
+          .attr('dominant-baseline', 'central')
+          .attr('font-family', FONT_FAMILY)
+          .attr('font-size', fitted.fontSize)
+          .attr('font-weight', '600')
+          .attr('fill', palette.text)
+          .text(fitted.lines[li]);
+      }
     } else {
       // Expanded: background container with label
       groupG

package/src/chart-type-scoring.ts

@@ -0,0 +1,162 @@
+// ============================================================
+// Chart-type scoring (pluggability seam)
+// ============================================================
+//
+// This module is the designated pluggability point for chart-type selection.
+// The input/output shape (prompt string → ranked candidates + confidence) is
+// stable; the internals can later swap to embedding-based similarity, a local
+// tiny LM, or any other approach without changing the MCP tool surface or
+// the `chartTypes` data model.
+
+import { chartTypes, type ChartTypeMeta } from './chart-types';
+
+const TYPOGRAPHIC_REPLACEMENTS: [RegExp, string][] = [
+  [/[‘’]/g, "'"], // curly single quotes
+  [/[“”]/g, '"'], // curly double quotes
+  [/[–—]/g, '-'], // en/em dash
+  [/×/g, 'x'], // unicode multiplication → ASCII (for "2×2" vs "2x2")
+];
+
+/** Normalize a string to lowercase ASCII-ish tokens for matching. */
+export function normalize(s: string): string[] {
+  let out = s.normalize('NFKD').toLowerCase();
+  for (const [re, repl] of TYPOGRAPHIC_REPLACEMENTS)
+    out = out.replace(re, repl);
+  return out.split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+/**
+ * True if `triggerTokens` appears as a contiguous slice of `promptTokens`.
+ * Token-based (not substring) — prevents "scatter plot" matching "scattered
+ * the plot", "ER diagram" matching "water diagram", and similar traps.
+ */
+export function matchesContiguously(
+  promptTokens: readonly string[],
+  triggerTokens: readonly string[]
+): boolean {
+  if (triggerTokens.length === 0 || triggerTokens.length > promptTokens.length)
+    return false;
+  outer: for (let i = 0; i <= promptTokens.length - triggerTokens.length; i++) {
+    for (let j = 0; j < triggerTokens.length; j++) {
+      if (promptTokens[i + j] !== triggerTokens[j]) continue outer;
+    }
+    return true;
+  }
+  return false;
+}
+
+export interface ChartTypeScore {
+  readonly type: ChartTypeMeta;
+  readonly score: number;
+  readonly matched: string[];
+}
+
+/**
+ * Score a single chart type against a prompt.
+ *
+ * Primary signal: contiguous trigger-phrase matches weighted by token count
+ * (longer phrases beat shorter ones). Secondary signal: description-word
+ * overlap at 0.25× weight — a tiebreak-only hint that rescues prompts which
+ * miss every trigger but touch description vocabulary. Triggers always win
+ * over descriptions because any trigger match is ≥1.0 and descriptions
+ * contribute ≤0.25 per token.
+ */
+export function scoreChartType(
+  prompt: string,
+  type: ChartTypeMeta
+): { score: number; matched: string[] } {
+  const promptTokens = normalize(prompt);
+  const matched: string[] = [];
+  let score = 0;
+
+  for (const trigger of type.triggers) {
+    const triggerTokens = normalize(trigger);
+    if (matchesContiguously(promptTokens, triggerTokens)) {
+      matched.push(trigger);
+      score += triggerTokens.length;
+    }
+  }
+
+  const descTokens = new Set(normalize(type.description));
+  let descHits = 0;
+  for (const t of promptTokens) if (descTokens.has(t)) descHits++;
+  score += descHits * 0.25;
+
+  return { score, matched };
+}
+
+/**
+ * Minimum trigger-based score for a confident match. A result below this
+ * floor means no actual trigger fired — only description-rescue tokens
+ * contributed — so the caller should drop to the fallback list instead of
+ * returning a confident-looking wrong answer.
+ *
+ * 1.0 is the weight of a single-token trigger. Anything less came entirely
+ * from 0.25× description hits.
+ */
+export const MIN_PRIMARY_SCORE = 1.0;
+
+/**
+ * Minimum absolute score gap required before calling a match
+ * non-ambiguous. 0.5 ≈ two description-rescue tokens' worth, or half a
+ * trigger-token difference. Below this, the cliff between "medium" and
+ * "ambiguous" is effectively noise.
+ */
+export const AMBIGUITY_THRESHOLD = 0.5;
+
+export type Confidence = 'high' | 'medium' | 'ambiguous';
+
+/**
+ * Confidence from the top two scores. Rules:
+ *   1. top < MIN_PRIMARY_SCORE → ambiguous (no real trigger matched)
+ *   2. second === 0            → high      (nothing competes)
+ *   3. top ≥ 2 × second        → high      (top dominates)
+ *   4. top − second < AMBIGUITY_THRESHOLD → ambiguous (gap is noise)
+ *   5. otherwise               → medium
+ */
+export function confidence(top: number, second: number): Confidence {
+  if (top < MIN_PRIMARY_SCORE) return 'ambiguous';
+  if (second === 0) return 'high';
+  if (top >= second * 2) return 'high';
+  if (top - second < AMBIGUITY_THRESHOLD) return 'ambiguous';
+  return 'medium';
+}
+
+export interface SuggestionResult {
+  readonly ranked: readonly ChartTypeScore[];
+  readonly fallback: readonly ChartTypeMeta[];
+  readonly confidence: Confidence;
+  readonly fellBack: boolean;
+}
+
+/**
+ * Score every chart type against `prompt` and return a ranked suggestion
+ * bundle. Types with score 0 are filtered out. When the top score is below
+ * `MIN_PRIMARY_SCORE` (no real trigger fired), the caller should present
+ * the fallback list — `fellBack` is set to true in that case.
+ *
+ * Array order is preserved: scoring iterates `chartTypes` in source order
+ * and `.sort` is stable in V8, so ties go to the earlier entry — specialized
+ * types beat generic catch-alls by construction.
+ */
+export function suggestChartTypes(prompt: string): SuggestionResult {
+  const scored: ChartTypeScore[] = [];
+  for (const type of chartTypes) {
+    const { score, matched } = scoreChartType(prompt, type);
+    if (score > 0) scored.push({ type, score, matched });
+  }
+  scored.sort((a, b) => b.score - a.score);
+
+  const fallback = chartTypes.filter((c) => c.fallback);
+
+  const topScore = scored[0]?.score ?? 0;
+  const secondScore = scored[1]?.score ?? 0;
+  const fellBack = topScore < MIN_PRIMARY_SCORE;
+
+  return {
+    ranked: scored,
+    fallback,
+    confidence: confidence(topScore, secondScore),
+    fellBack,
+  };
+}