@diagrammo/dgmo 0.14.1 → 0.15.1

package/src/index.ts

@@ -1,692 +1,215 @@
 // ============================================================
-// Diagnostics
-// ============================================================
-
-export { makeDgmoError, formatDgmoError } from './diagnostics';
-export type { DgmoError, DgmoSeverity } from './diagnostics';
-
-// ============================================================
-// Arrow helpers (in-arrow label validation)
-// ============================================================
-
-export {
-  parseInArrowLabel,
-  validateLabelCharacters,
-  matchColorParens,
-  ARROW_DIAGNOSTIC_CODES,
-} from './utils/arrows';
-export type { ParseInArrowLabelResult } from './utils/arrows';
-
-// ============================================================
-// Unified API
-// ============================================================
-
-export { render } from './render';
-
-// ============================================================
-// Chart-type registry (single source of truth)
-// ============================================================
-
-export { chartTypes, BETA_CHART_IDS } from './chart-types';
-export type { ChartTypeMeta } from './chart-types';
-
-export {
-  normalize as normalizeChartTypePrompt,
-  matchesContiguously,
-  scoreChartType,
-  confidence as chartTypeConfidence,
-  suggestChartTypes,
-  MIN_PRIMARY_SCORE,
-  AMBIGUITY_THRESHOLD,
-} from './chart-type-scoring';
-export type {
-  ChartTypeScore,
-  Confidence as ChartTypeConfidence,
-  SuggestionResult as ChartTypeSuggestionResult,
-} from './chart-type-scoring';
-
-// ============================================================
-// Router
-// ============================================================
-
-export {
-  parseDgmoChartType,
-  parseDgmo,
-  getRenderCategory,
-  isExtendedChartType,
-  getAllChartTypes,
-  CHART_TYPE_DESCRIPTIONS,
-  chartTypeParsers,
-  knownChartTypeIds,
-} from './dgmo-router';
-export type { RenderCategory } from './dgmo-router';
-
-// ============================================================
-// Parsers
-// ============================================================
-
-export { parseChart, parseDataRowValues } from './chart';
-export type { ParsedChart, ChartType, ChartDataPoint, ChartEra } from './chart';
-
-export { parseExtendedChart } from './echarts';
-export type { ParsedExtendedChart, ExtendedChartType } from './echarts';
-
-export {
-  parseVisualization,
-  orderArcNodes,
-  parseTimelineDate,
-  addDurationToDate,
-  formatDateLabel,
-} from './d3';
-export { computeTimeTicks } from './utils/time-ticks';
-export type {
-  ParsedVisualization,
-  VisualizationType,
-  D3ExportDimensions,
-  ArcLink,
-  ArcNodeGroup,
-} from './d3';
-
-export {
-  parseSequenceDgmo,
-  parseSequenceDgmo as parseSequenceDiagram,
-  looksLikeSequence,
-  isSequenceBlock,
-  isSequenceNote,
-} from './sequence/parser';
-export type {
-  ParsedSequenceDgmo,
-  SequenceParticipant,
-  SequenceMessage,
-  SequenceBlock,
-  ElseIfBranch,
-  SequenceSection,
-  SequenceNote,
-  SequenceElement,
-  SequenceGroup,
-  ParticipantType,
-} from './sequence/parser';
-
-export {
-  inferParticipantType,
-  RULE_COUNT,
-} from './sequence/participant-inference';
-
-export { parseFlowchart, looksLikeFlowchart } from './graph/flowchart-parser';
-
-export { parseState, looksLikeState } from './graph/state-parser';
-export { renderState, renderStateForExport } from './graph/state-renderer';
-export { collapseStateGroups } from './graph/state-collapse';
-export type { StateCollapseResult } from './graph/state-collapse';
-
-export { parseClassDiagram, looksLikeClassDiagram } from './class/parser';
-
-export type {
-  ParsedClassDiagram,
-  ClassNode,
-  ClassMember,
-  ClassRelationship,
-  ClassModifier,
-  MemberVisibility,
-  RelationshipType,
-} from './class/types';
-
-export { layoutClassDiagram } from './class/layout';
-export type {
-  ClassLayoutResult,
-  ClassLayoutNode,
-  ClassLayoutEdge,
-} from './class/layout';
-
-export {
-  renderClassDiagram,
-  renderClassDiagramForExport,
-} from './class/renderer';
-
-export { parseERDiagram, looksLikeERDiagram } from './er/parser';
-
-export type {
-  ParsedERDiagram,
-  ERTable,
-  ERColumn,
-  ERRelationship,
-  ERConstraint,
-  ERCardinality,
-} from './er/types';
-
-export { layoutERDiagram } from './er/layout';
-export type { ERLayoutResult, ERLayoutNode, ERLayoutEdge } from './er/layout';
-
-export { renderERDiagram, renderERDiagramForExport } from './er/renderer';
-
-export type {
-  ParsedGraph,
-  GraphNode,
-  GraphEdge,
-  GraphGroup,
-  GraphShape,
-  GraphDirection,
-} from './graph/types';
-
-export type { TagGroup, TagEntry } from './utils/tag-groups';
-
-export { parseInlineMarkdown, truncateBareUrl } from './utils/inline-markdown';
-export type { InlineSpan } from './utils/inline-markdown';
-
-export {
-  normalizeName,
-  displayName,
-  getOrCreateName,
-} from './utils/name-normalize';
-export type { NameEntry, GetOrCreateNameResult } from './utils/name-normalize';
-
-export { parseOrg } from './org/parser';
-export type { ParsedOrg, OrgNode } from './org/parser';
-
-export { layoutOrg } from './org/layout';
-export type {
-  OrgLayoutResult,
-  OrgLayoutNode,
-  OrgLayoutEdge,
-  OrgContainerBounds,
-} from './org/layout';
-
-export { renderOrg, renderOrgForExport } from './org/renderer';
-
-export { parseKanban } from './kanban/parser';
-export type {
-  ParsedKanban,
-  KanbanColumn,
-  KanbanCard,
-  KanbanTagGroup,
-  KanbanTagEntry,
-} from './kanban/types';
-export {
-  computeCardMove,
-  computeCardArchive,
-  isArchiveColumn,
-} from './kanban/mutations';
-export { renderKanban, renderKanbanForExport } from './kanban/renderer';
-
-export { parseC4 } from './c4/parser';
-export type {
-  ParsedC4,
-  C4Element,
-  C4ElementType,
-  C4Shape,
-  C4ArrowType,
-  C4Relationship,
-  C4Group,
-  C4DeploymentNode,
-  C4TagGroup,
-  C4TagEntry,
-} from './c4/types';
-
-export {
-  layoutC4Context,
-  layoutC4Containers,
-  layoutC4Components,
-  layoutC4Deployment,
-  rollUpContextRelationships,
-} from './c4/layout';
-export type {
-  C4LayoutResult,
-  C4LayoutNode,
-  C4LayoutEdge,
-  C4LayoutBoundary,
-  C4LegendGroup,
-  C4LegendEntry,
-  ContextRelationship,
-} from './c4/layout';
-
-export {
-  renderC4Context,
-  renderC4ContextForExport,
-  renderC4Containers,
-  renderC4ContainersForExport,
-  renderC4ComponentsForExport,
-  renderC4Deployment,
-  renderC4DeploymentForExport,
-} from './c4/renderer';
-
-export { parseBoxesAndLines } from './boxes-and-lines/parser';
-export type {
-  ParsedBoxesAndLines,
-  BLNode,
-  BLEdge,
-  BLGroup,
-} from './boxes-and-lines/types';
-export { layoutBoxesAndLines } from './boxes-and-lines/layout';
-export type {
-  BLLayoutResult,
-  BLLayoutNode,
-  BLLayoutEdge,
-  BLLayoutGroup,
-} from './boxes-and-lines/layout';
-export {
-  renderBoxesAndLines,
-  renderBoxesAndLinesForExport,
-} from './boxes-and-lines/renderer';
-
-export { collapseBoxesAndLines } from './boxes-and-lines/collapse';
-export type { BLCollapseResult } from './boxes-and-lines/collapse';
-
-export { parseSitemap, looksLikeSitemap } from './sitemap/parser';
-
-export type {
-  ParsedSitemap,
-  SitemapNode,
-  SitemapEdge,
-  SitemapDirection,
-} from './sitemap/types';
-
-export { layoutSitemap } from './sitemap/layout';
-export type {
-  SitemapLayoutResult,
-  SitemapLayoutNode,
-  SitemapLayoutEdge,
-  SitemapContainerBounds,
-  SitemapLegendGroup,
-  SitemapLegendEntry,
-} from './sitemap/layout';
-
-export { renderSitemap, renderSitemapForExport } from './sitemap/renderer';
-
-export { collapseSitemapTree } from './sitemap/collapse';
-
-// ── Infra Chart ────────────────────────────────────────────
-export { parseInfra } from './infra/parser';
-export type {
-  ParsedInfra,
-  InfraNode,
-  InfraEdge,
-  InfraGroup,
-  InfraTagGroup,
-  InfraProperty,
-  InfraDiagnostic,
-  InfraComputeParams,
-  InfraBehaviorKey,
-} from './infra/types';
-export { INFRA_BEHAVIOR_KEYS } from './infra/types';
-export { computeInfra } from './infra/compute';
-export type {
-  ComputedInfraModel,
-  ComputedInfraNode,
-  ComputedInfraEdge,
-  InfraLatencyPercentiles,
-  InfraAvailabilityPercentiles,
-  InfraCbState,
-} from './infra/types';
-export { validateInfra, validateComputed } from './infra/validation';
-export { inferRoles, collectDiagramRoles } from './infra/roles';
-export type { InfraRole } from './infra/roles';
-export { layoutInfra } from './infra/layout';
-export type {
-  InfraLayoutResult,
-  InfraLayoutNode,
-  InfraLayoutEdge,
-  InfraLayoutGroup,
-} from './infra/layout';
-export {
-  renderInfra,
-  parseAndLayoutInfra,
-  computeInfraLegendGroups,
-} from './infra/renderer';
-export type { InfraLegendGroup, InfraPlaybackState } from './infra/renderer';
-export type { CollapsedSitemapResult } from './sitemap/collapse';
-
-// ── Gantt Chart ───────────────────────────────────────────
-export { parseGantt } from './gantt/parser';
-export { calculateSchedule } from './gantt/calculator';
-export { renderGantt, buildTagLaneRowList } from './gantt/renderer';
-export type {
-  GanttInteractiveOptions,
-  GanttRow,
-  GanttGroupRow,
-  GanttTaskRow,
-  GanttLaneHeaderRow,
-} from './gantt/renderer';
-export { resolveTaskName, collectTasks } from './gantt/resolver';
-export type {
-  ParsedGantt,
-  GanttTask,
-  GanttGroup,
-  GanttParallelBlock,
-  GanttNode,
-  GanttDependency,
-  GanttHolidays,
-  GanttEra,
-  GanttMarker,
-  GanttOptions,
-  Duration,
-  DurationUnit,
-  ResolvedSchedule,
-  ResolvedTask,
-  ResolvedGroup,
-} from './gantt/types';
-
-// ── PERT Diagram ──────────────────────────────────────────
-export { parsePert, looksLikePert, extractPertSymbols } from './pert/parser';
-export { analyzePert } from './pert/analyzer';
-export { layoutPert, relayoutPert } from './pert/layout';
-export type { LayoutOverrides as PertLayoutOverrides } from './pert/internal';
-export { normalizePertSourceForShare } from './pert/share-normalize';
-export {
-  renderPert,
-  renderPertForExport,
-  renderPertAnalysisBlock,
-  measurePertAnalysisBlock,
-  highlightPertCriticalPath,
-  highlightPertSet,
-  pertLegendEntries,
-  pertLegendBlockWidth,
-  PERT_LEGEND_PILL_HEIGHT,
-  renderLegendBlock as renderPertLegendBlock,
-  resetPertCriticalPath,
-  resetPertHighlight,
-} from './pert/renderer';
-export type { PertRenderOptions } from './pert/renderer';
-export type {
-  Anchor as PertAnchor,
-  ParsedPert,
-  PertActivity,
-  PertEdge,
-  PertGroup,
-  PertMilestone,
-  PertOptions,
-  PertDirection,
-  NodeDetail,
-  ResolvedActivity,
-  ResolvedGroup as ResolvedPertGroup,
-  ResolvedPert,
-  MonteCarloResult,
-  PertLayoutNode,
-  PertLayoutEdge,
-  PertLayoutGroup,
-  LayoutResult as PertLayoutResult,
-} from './pert/types';
-
-export { collapseOrgTree, focusOrgTree } from './org/collapse';
-export type {
-  CollapsedOrgResult,
-  FocusOrgResult,
-  AncestorInfo,
-} from './org/collapse';
-
-export { parseMindmap } from './mindmap/parser';
-export type {
-  MindmapNode,
-  ParsedMindmap,
-  MindmapLayoutNode,
-  MindmapLayoutEdge,
-  MindmapLayoutResult,
-} from './mindmap/types';
-export { layoutMindmap } from './mindmap/layout';
-export { renderMindmap, renderMindmapForExport } from './mindmap/renderer';
-export { collapseMindmapTree } from './mindmap/collapse';
-export type { CollapsedMindmapResult } from './mindmap/collapse';
-
-export { parseWireframe } from './wireframe/parser';
-export type {
-  ParsedWireframe,
-  WireframeElement,
-  WireframeElementType,
-  WireframeFormFactor,
-} from './wireframe/types';
-export { layoutWireframe } from './wireframe/layout';
-export type { WireframeLayout, WireframeLayoutNode } from './wireframe/layout';
-export { renderWireframe } from './wireframe/renderer';
-
-export { parseTechRadar } from './tech-radar/parser';
-export { computeRadarLayout, getRadarGeometry } from './tech-radar/layout';
-export {
-  renderTechRadar,
-  renderTechRadarForExport,
-} from './tech-radar/renderer';
-export {
-  renderQuadrantFocus,
-  renderQuadrantFocusForExport,
-} from './tech-radar/interactive';
-export type {
-  ParsedTechRadar,
-  TechRadarRing,
-  TechRadarQuadrant,
-  TechRadarBlip,
-  TechRadarLayoutPoint,
-  QuadrantPosition,
-  BlipTrend,
-} from './tech-radar/types';
-
-export { parseCycle } from './cycle/parser';
-export { computeCycleLayout } from './cycle/layout';
-export { renderCycle, renderCycleForExport } from './cycle/renderer';
-export type { CycleRenderOptions } from './cycle/renderer';
-export type {
-  ParsedCycle,
-  CycleNode,
-  CycleEdge,
-  CycleLayoutNode,
-  CycleLayoutEdge,
-  CycleLayoutResult,
-} from './cycle/types';
-
-export { parseJourneyMap } from './journey-map/parser';
-export { layoutJourneyMap } from './journey-map/layout';
-export type { JourneyMapLayout } from './journey-map/layout';
-export {
-  renderJourneyMap,
-  renderJourneyMapForExport,
-} from './journey-map/renderer';
-export type {
-  ParsedJourneyMap,
-  JourneyMapPhase,
-  JourneyMapStep,
-  JourneyMapPersona,
-  JourneyMapAnnotation,
-} from './journey-map/types';
-export type { JourneyMapInteractiveOptions } from './journey-map/renderer';
-
-export { parsePyramid } from './pyramid/parser';
-export { renderPyramid, renderPyramidForExport } from './pyramid/renderer';
-export type { ParsedPyramid, PyramidLayer } from './pyramid/types';
-
-export { parseRing } from './ring/parser';
-export { renderRing, renderRingForExport } from './ring/renderer';
-export type { ParsedRing, RingLayer } from './ring/types';
-
-export type { RaciDragSource, RaciInteractionHandlers } from './raci';
-export {
-  parseRaci,
-  renderRaci,
-  renderRaciForExport,
-  VARIANTS as RACI_VARIANTS,
-  RACI_ERROR_CODES,
-  RACI_WARNING_CODES,
-  cellReplace as raciCellReplace,
-  cellAppendMarker as raciCellAppendMarker,
-  cellRemove as raciCellRemove,
-  cellCycle as raciCellCycle,
-} from './raci';
-export type {
-  ParsedRaci,
-  RaciVariant,
-  RaciMarker,
-  RaciTask,
-  RaciPhase,
-  RaciRoleAssignment,
-} from './raci';
-
-export { resolveOrgImports } from './org/resolver';
-export type {
-  ReadFileFn,
-  ResolveImportsResult,
-  ImportSource,
-} from './org/resolver';
-
-export { layoutGraph } from './graph/layout';
-export type {
-  LayoutResult,
-  LayoutNode,
-  LayoutEdge,
-  LayoutGroup,
-  LayoutOptions,
-} from './graph/layout';
-
-export {
-  renderFlowchart,
-  renderFlowchartForExport,
-} from './graph/flowchart-renderer';
-
-// ============================================================
-// Config Builders (produce framework-specific config objects)
-// ============================================================
-
-export {
-  buildExtendedChartOption,
-  buildSimpleChartOption,
-  renderExtendedChartForExport,
-  getExtendedChartLegendGroups,
-  getSimpleChartLegendGroups,
-  computeScatterLabelGraphics,
-} from './echarts';
-export type { ScatterLabelPoint } from './echarts';
-export {
-  renderLegendSvg,
-  renderLegendSvgFromConfig,
-  type LegendGroupData,
-} from './utils/legend-svg';
-export { LEGEND_HEIGHT, LEGEND_GEAR_PILL_W } from './utils/legend-constants';
-export { renderLegendD3 } from './utils/legend-d3';
-export {
-  computeLegendLayout,
-  controlsGroupCapsuleWidth,
-  getLegendReservedHeight,
-} from './utils/legend-layout';
-export type {
-  LegendConfig,
-  LegendState,
-  LegendCallbacks,
-  LegendPosition,
-  LegendMode,
-  LegendControl,
-  LegendLayout,
-  LegendHandle,
-  LegendPalette,
-} from './utils/legend-types';
-// ============================================================
-// Renderers (produce SVG output)
-// ============================================================
-
-export {
-  renderSlopeChart,
-  renderArcDiagram,
-  renderTimeline,
-  renderWordCloud,
-  renderVenn,
-  renderQuadrant,
-  renderForExport,
-} from './d3';
-
-export {
-  renderSequenceDiagram,
-  buildRenderSequence,
-  computeActivations,
-  applyPositionOverrides,
-  applyGroupOrdering,
-  groupMessagesBySection,
-  buildNoteMessageMap,
-} from './sequence/renderer';
-export type {
-  RenderStep,
-  Activation,
-  SectionMessageGroup,
-  SequenceRenderOptions,
-} from './sequence/renderer';
-
-export { applyCollapseProjection } from './sequence/collapse';
-export type { CollapsedView } from './sequence/collapse';
-
-// ============================================================
-// Colors & Palettes
-// ============================================================
-
-export {
-  resolveColor,
-  resolveColorWithDiagnostic,
-  colorNames,
-  nord,
-  seriesColors,
-  RECOGNIZED_COLOR_NAMES,
-  isRecognizedColorName,
-} from './colors';
-
-export {
-  // Registry
-  getPalette,
-  getAvailablePalettes,
-  registerPalette,
-  isValidHex,
-  // Utilities
-  hexToHSL,
-  hslToHex,
-  hexToHSLString,
-  tint,
-  shade,
-  getSeriesColors,
-  contrastText,
-  // Palette definitions
-  nordPalette,
-  solarizedPalette,
-  catppuccinPalette,
-  rosePinePalette,
-  gruvboxPalette,
-  tokyoNightPalette,
-  oneDarkPalette,
-  boldPalette,
-  draculaPalette,
-  monokaiPalette,
-} from './palettes';
-
-export type { PaletteConfig, PaletteColors } from './palettes';
-export { mix, shapeFill } from './palettes/color-utils';
-
-// ============================================================
-// Sharing (URL encoding/decoding)
-// ============================================================
-
-export {
-  encodeDiagramUrl,
-  decodeDiagramUrl,
-  encodeViewState,
-  decodeViewState,
-} from './sharing';
-export type {
-  EncodeDiagramUrlOptions,
-  EncodeDiagramUrlResult,
-  CompactViewState,
-  DecodedDiagramUrl,
+// @diagrammo/dgmo — Public API
+// ============================================================
+//
+// This is the frozen public surface. ~12 exports. Everything else lives in
+// `@diagrammo/dgmo/internal` (unstable, no semver), `@diagrammo/dgmo/editor`,
+// `@diagrammo/dgmo/highlight`, or `@diagrammo/dgmo/auto`.
+//
+// If you need something not exported here, import from `/internal` and
+// accept the no-semver contract.
+
+import { render as renderInternal } from './render';
+import {
+  encodeDiagramUrl as encodeDiagramUrlInternal,
+  decodeDiagramUrl as decodeDiagramUrlInternal,
+  type CompactViewState,
 } from './sharing';
-
-// ============================================================
-// Completion (symbol extraction API)
-// ============================================================
-
-export {
-  registerExtractor,
-  extractDiagramSymbols,
-  COMPLETION_REGISTRY,
-  CHART_TYPES,
-  METADATA_KEY_SET,
-  ENTITY_TYPES,
-  PIPE_METADATA,
-  extractTagDeclarations,
-} from './completion';
-export type {
-  DiagramSymbols,
-  ExtractFn,
-  DirectiveSpec,
-  DirectiveValueSpec,
-  PipeKeySpec,
-} from './completion';
-
-export { parseFirstLine, ALL_CHART_TYPES } from './utils/parsing';
+import { parseDgmo as validate } from './dgmo-router';
+import { palettes, getPalette } from './palettes';
+import type { PaletteConfig } from './palettes/types';
+import type { Theme } from './themes';
+import { formatDgmoError, type DgmoError } from './diagnostics';
+
+export type { CompactViewState } from './sharing';
+
+// ============================================================
+// render(text, options?)
+// ============================================================
+
+export interface RenderOptions {
+  theme?: Theme;
+  palette?: PaletteConfig;
+  /**
+   * How to handle parse errors:
+   *   'svg'    — render an inline error SVG (default)
+   *   'silent' — return empty svg + diagnostics; caller handles UI
+   *   'throw'  — throw an Error with the diagnostics
+   */
+  onError?: 'svg' | 'silent' | 'throw';
+  /**
+   * Pre-applied interactive view state — collapsed sections/columns,
+   * active swimlane tag-group, etc. Used to render a specific view
+   * non-interactively (server-side render, share-link decode).
+   */
+  viewState?: CompactViewState;
+}
+
+export interface RenderResult {
+  svg: string;
+  diagnostics: DgmoError[];
+}
+
+/**
+ * Render DGMO source to an SVG string.
+ *
+ * @example
+ * ```ts
+ * import { render, palettes, themes } from '@diagrammo/dgmo';
+ *
+ * const { svg } = await render(text, {
+ *   palette: palettes.catppuccin,
+ *   theme: themes.dark,
+ * });
+ * document.getElementById('chart').innerHTML = svg;
+ * ```
+ */
+export async function render(
+  text: string,
+  options?: RenderOptions
+): Promise<RenderResult> {
+  const palette = options?.palette ?? palettes.nord;
+  const onError = options?.onError ?? 'svg';
+
+  const result = await renderInternal(text, {
+    theme: options?.theme,
+    palette: palette.id,
+    viewState: options?.viewState,
+  });
+
+  const errors = result.diagnostics.filter((d) => d.severity === 'error');
+
+  if (errors.length === 0) {
+    return result;
+  }
+
+  if (onError === 'throw') {
+    throw new Error(
+      `DGMO parse error: ${errors.map(formatDgmoError).join('; ')}`
+    );
+  }
+
+  if (onError === 'silent') {
+    return result;
+  }
+
+  // 'svg' (default): render an inline error SVG so the user sees the problem
+  return {
+    svg: result.svg || renderErrorSvg(errors, palette, options?.theme),
+    diagnostics: result.diagnostics,
+  };
+}
+
+function renderErrorSvg(
+  errors: DgmoError[],
+  palette: PaletteConfig,
+  theme?: Theme
+): string {
+  const colors = palette[theme === 'dark' ? 'dark' : 'light'];
+  const bg = theme === 'transparent' ? 'transparent' : colors.bg;
+  const fg = colors.destructive ?? colors.text;
+  const muted = colors.textMuted ?? colors.text;
+  const lines = errors.slice(0, 5).map((e) => formatDgmoError(e));
+  const height = 60 + lines.length * 20;
+  const body = lines
+    .map(
+      (line, i) =>
+        `<text x="20" y="${60 + i * 20}" fill="${fg}" font-family="ui-monospace, monospace" font-size="12">${escapeXml(line)}</text>`
+    )
+    .join('');
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="${height}" viewBox="0 0 640 ${height}"><rect width="100%" height="100%" fill="${bg}"/><text x="20" y="34" fill="${muted}" font-family="system-ui, sans-serif" font-size="13" font-weight="600">DGMO parse error</text>${body}</svg>`;
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// ============================================================
+// validate(text)
+// ============================================================
+
+export { validate };
+
+// ============================================================
+// formatDgmoError(err)
+// ============================================================
+
+export { formatDgmoError };
+
+// ============================================================
+// Sharing — encodeDiagramUrl / decodeDiagramUrl
+// ============================================================
+
+export interface EncodeDiagramUrlOptions {
+  baseUrl?: string;
+  palette?: PaletteConfig;
+  theme?: Theme;
+  filename?: string;
+  /**
+   * Initial view state to embed in the URL — re-applied when the link is
+   * decoded so recipients open the diagram in the same configuration.
+   */
+  viewState?: CompactViewState;
+}
+
+/**
+ * Encode DGMO text into a shareable URL. Returns null if the compressed
+ * payload exceeds the 8 KB URL limit.
+ */
+export function encodeDiagramUrl(
+  text: string,
+  options?: EncodeDiagramUrlOptions
+): string | null {
+  const internalTheme =
+    options?.theme === 'light' || options?.theme === 'dark'
+      ? options.theme
+      : undefined;
+  const result = encodeDiagramUrlInternal(text, {
+    baseUrl: options?.baseUrl,
+    palette: options?.palette?.id,
+    theme: internalTheme,
+    filename: options?.filename,
+    viewState: options?.viewState,
+  });
+  return 'error' in result && result.error ? null : (result.url ?? null);
+}
+
+export interface DecodedDiagramUrl {
+  text: string;
+  palette?: PaletteConfig;
+  theme?: Theme;
+  filename?: string;
+}
+
+/**
+ * Decode a share URL back into DGMO text plus optional palette/theme/filename.
+ * Returns null if the URL contains no valid DGMO payload.
+ */
+export function decodeDiagramUrl(url: string): DecodedDiagramUrl | null {
+  const decoded = decodeDiagramUrlInternal(url);
+  if (!decoded.dsl) return null;
+  const palette = decoded.palette ? getPalette(decoded.palette) : undefined;
+  const out: DecodedDiagramUrl = { text: decoded.dsl };
+  if (palette) out.palette = palette;
+  if (decoded.theme) out.theme = decoded.theme;
+  if (decoded.filename) out.filename = decoded.filename;
+  return out;
+}
+
+// ============================================================
+// Palettes + themes (namespaces)
+// ============================================================
+
+export { palettes, getPalette } from './palettes';
+export { themes, type Theme } from './themes';
+
+// ============================================================
+// Public types
+// ============================================================
+
+export type { PaletteConfig, PaletteColors } from './palettes/types';
+export type { DgmoError, DgmoSeverity } from './diagnostics';