@jarenjs/mermaid 0.46.5 → 0.49.2

package/README.md

@@ -158,13 +158,73 @@ flowchart LR
 Fully laid out: **flowchart**, **sequence**, **state** (through the
 flowchart engine via an adapter — states as rounded nodes, `[*]` as a
 filled start dot and an end ring, verbatim transition labels on the
-edges; composite states stay flattened in v1). Structured panels /
-chart: **class**, **ER**, **gantt**, **pie**. Parse-accepted with an
+edges; composite states stay flattened in v1) and **gantt** (a real time
+axis — see below). Structured panels / chart: **class**, **ER**,
+**pie**. Parse-accepted with an
 honest "not yet laid out" placeholder: mindmap, gitGraph, journey,
 timeline, quadrantChart, requirement. The benchmark's coverage scorecard reports this
 without hiding gaps.
 
 
+## Gantt: the date directives are interpreted
+
+A Gantt diagram is parsed into a **resolved schedule** and rendered as a
+timeline — an aligned time axis, section bands, bars, milestone
+diamonds, dependency connectors and shaded excluded days:
+
+```mermaid
+gantt
+title Release plan
+dateFormat YYYY-MM-DD
+excludes weekends
+tickInterval 1week
+section Build
+Design : done, a1, 2024-01-04, 3d
+Implement : active, a2, after a1, 5d
+section Ship
+Review : crit, a3, after a2, 2d
+Launch : milestone, m1, after a3, 0d
+```
+
+Every directive means something. `dateFormat` compiles to a strict date
+parser, `axisFormat` to the axis labels, `tickInterval` and `weekday` to
+the tick boundaries, and `excludes`/`weekend` to a working calendar that
+moves a duration-derived end past the days it skips. Tick positions come
+from `@jarenjs/core/dates` — the same ladder the chart component's time
+axis reads — so a timeline and a chart cannot disagree about where a
+week begins.
+
+Each task carries `{ id, flags, start, end, duration, after, line }`
+beside its raw `info`, with `start`/`end` as epoch milliseconds and the
+interval half-open. The grammar, the vendored conformance table and the
+three deliberate divergences from Mermaid are in
+[docs/MERMAID-FORMAT.md §4.4](./docs/MERMAID-FORMAT.md). The load-bearing
+one: **there is no clock here**, so a schedule with no dated anchor is a
+line-aware error rather than a diagram whose meaning changes daily.
+
+Mermaid's `dateFormat` is moment's grammar and its `axisFormat` is
+strftime; neither is LDML, so each has its own tokenizer and each token
+is mapped individually onto the core date kernel. An unsupported token
+is refused by name rather than passed through as text.
+
+**Localized labels take an injected provider.** This engine ships no
+month or weekday names, so `axisFormat %b %Y` (or a `dateFormat` with
+`MMMM`) needs one — the same `DateNames` record
+`@jarenjs/locales`' `compileDateLocale(pack).names` produces:
+
+```js
+import { compileDateLocale, nl } from '@jarenjs/locales';
+renderMermaid(source, { dateNames: compileDateLocale(nl).names });
+```
+
+Without a provider a name token is a compile error, not a silent English
+fallback. Task ids and dates stay ASCII data either way — an RTL name is
+text, not syntax.
+
+At scale, parse (which is also schedule resolution), layout and render
+are reported separately in the benchmark: <!--bm:mermaid.ganttScale-->at 10,000 tasks, ~34 ms to parse and resolve, ~3.8 ms to lay out and ~7.7 ms to render<!--/bm-->.
+
+
 ## Styling, notes and interaction
 
 **`classDef` / `class` / `style` now paint.** The parser always recorded them;
@@ -261,7 +321,7 @@ detection + Jison + validation — so it is heavy and noisy; these are
 representative, not a bare-grammar microbenchmark.)
 
 The headless **parse → layout → SVG string** rows are jaren-only
-(<!--bm:mermaid.svgMs-->~0.46 ms for a 25-node flowchart, ~1.4 ms at 100 nodes<!--/bm-->): mermaid.js
+(<!--bm:mermaid.svgMs-->~0.68 ms for a 25-node flowchart, ~1 ms at 100 nodes<!--/bm-->): mermaid.js
 needs a browser DOM (`getBBox`) to render, so there is no fair
 full-render head-to-head — producing a complete standalone SVG in pure
 Node is a capability it lacks.

package/dist/types/gantt-calendar.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @file The working calendar behind `excludes`: which whole days a
+ * schedule skips, and what a duration therefore means.
+ *
+ * Two implementations of one answer live here on purpose. The exported
+ * one expresses an excluded stretch as half-open day intervals and
+ * measures it with `@jarenjs/core/series` (`mergeIntervals`,
+ * `coverageOf`) — the suite's one interval algebra, so a weekend here
+ * and an unavailability there are the same kind of thing. The other,
+ * {@link pushEndDayByDay}, is the naive day-stepping loop the shipped
+ * Mermaid renderer runs; it exists so the fast answer has an
+ * independent oracle to be differential-tested against, and it is the
+ * definition when the two disagree.
+ *
+ * The rule is Mermaid's, not an invention: an excluded day pushes a
+ * task's END out by a whole day, the task's own START is left where the
+ * document put it, and an end that was written as an explicit DATE is
+ * never pushed at all — only one derived from a duration is. Days are
+ * UTC days, because this engine has no local zone and no clock.
+ *
+ * This is not a holiday service. A schedule skips exactly the weekends,
+ * weekday names and dates its own `excludes` line lists.
+ */
+/** Milliseconds in a UTC day. */
+export declare const DAY_MS = 86400000;
+/**
+ * Mermaid's own guard: a schedule whose exclusions swallow every day
+ * would push an end forever, so the walk stops and the caller reports a
+ * `JM` error instead of hanging.
+ */
+export declare const MAX_PUSH_DAYS = 10000;
+/**
+ * The index of the UTC day holding `ms`, counting from 1970-01-01.
+ * @param {number} ms
+ * @returns {number}
+ */
+export declare function dayIndexOf(ms: number): number;
+export type Excluder = {
+    /**
+     * whether the document excludes anything at all
+     */
+    any: boolean;
+    isExcludedDay: (dayIndex: number) => boolean;
+    /**
+     * merged half-open day spans over `[fromDay, toDay)`
+     */
+    intervalsIn: (fromDay: number, toDay: number) => {
+        start: number;
+        end: number;
+    }[];
+};
+/**
+ * @typedef {object} Excluder
+ * @property {boolean} any whether the document excludes anything at all
+ * @property {(dayIndex: number) => boolean} isExcludedDay
+ * @property {(fromDay: number, toDay: number) => { start: number, end: number }[]}
+ *   intervalsIn merged half-open day spans over `[fromDay, toDay)`
+ */
+/**
+ * Build the working calendar a document's `excludes`, `weekend` and
+ * `dateFormat` describe.
+ *
+ * @param {{ weekends: boolean, weekdays: number[], days: number[] }} rules -
+ *   `weekdays` are ISO weekday numbers, `days` are day indexes
+ * @param {number} weekendStart - ISO weekday the weekend starts on
+ * @returns {Excluder}
+ */
+export declare function createExcluder(rules: {
+    weekends: boolean;
+    weekdays: number[];
+    days: number[];
+}, weekendStart: number): Excluder;
+/**
+ * Push a task's end past the excluded days its span crosses.
+ *
+ * The probes are the instants `start + k days` for `k` from 1, which is
+ * what makes this a *day* rule rather than a millisecond one: a task
+ * that starts at noon on Friday and lasts a day ends at noon on Monday
+ * when the weekend is excluded, not at midnight.
+ *
+ * @param {number} start - epoch milliseconds
+ * @param {number} end - epoch milliseconds, at or after `start`
+ * @param {Excluder} excluder
+ * @returns {number} the pushed end, or `NaN` when the exclusions never
+ *   let the task finish
+ */
+export declare function pushEndPastExclusions(start: number, end: number, excluder: Excluder): number;
+/**
+ * The oracle: Mermaid's own day-stepping loop, written plainly. Kept as
+ * a test double rather than as the implementation because it walks
+ * every day of a span one at a time, but it is the definition of the
+ * answer {@link pushEndPastExclusions} computes.
+ *
+ * @param {number} start - epoch milliseconds
+ * @param {number} end - epoch milliseconds
+ * @param {Excluder} excluder
+ * @returns {number} the pushed end, or `NaN` when it never finishes
+ */
+export declare function pushEndDayByDay(start: number, end: number, excluder: Excluder): number;

package/dist/types/index.d.ts

@@ -28,11 +28,17 @@ export { MERMAID_VERSION, diagramDocument, walkSequence, flowNode, flowEdge, seq
 /**
  * Convenience: parse → layout → render, error-safe, in one call.
  * @param {string} source
- * @param {{ theme?: any }} [options]
+ * @param {{ theme?: any, dateNames?: import('@jarenjs/core/dates').DateNames,
+ *   parseFrontmatter?: (text: string) => any }} [options] - `dateNames`
+ *   is the locale-name record a Gantt's `dateFormat`/`axisFormat` needs
+ *   for a month or weekday token (`compileDateLocale(pack).names`);
+ *   this engine ships none of its own
  * @returns {any} an SVG vnode
  */
 export declare function renderMermaid(source: string, options?: {
     theme?: any;
+    dateNames?: import('@jarenjs/core/dates').DateNames;
+    parseFrontmatter?: (text: string) => any;
 }): any;
 export type CompiledMermaid = {
     /**

package/dist/types/layout/gantt.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file Gantt layout: a resolved schedule → a deterministic
+ * `PositionedDiagram` scene. Pure, host-free and vnode-free, so the
+ * geometry can be asserted without rendering anything.
+ *
+ * The time axis is not this file's invention: the domain comes from the
+ * AST, the tick positions come from `@jarenjs/core/dates` — either the
+ * document's own `tickInterval` through `timeTicksEvery`, or the shared
+ * step ladder through `axisTicksTime`, the same one the chart component
+ * draws its time axis with — and the tick labels come from the
+ * document's `axisFormat` compiled once here. A second tick ladder in a
+ * renderer would be a second set of positions.
+ *
+ * Two decisions are made here rather than in the renderer, because both
+ * are geometry:
+ *
+ * - **Tick labels thin out.** `tickInterval 1day` over two years is 730
+ *   ticks; the marks all stay, and labels are kept at the largest
+ *   stride that leaves them from overlapping. The scene says which.
+ * - **Row names elide.** A name wider than the label column is cut with
+ *   an ellipsis at layout time, so the measured width and the drawn text
+ *   are the same string.
+ */
+/**
+ * @param {any} ast gantt AST (`parser/gantt.js`)
+ * @param {{ dateNames?: import('@jarenjs/core/dates').DateNames }} [options]
+ * @returns {any} PositionedDiagram
+ */
+export declare function layoutGantt(ast: any, options?: {
+    dateNames?: import('@jarenjs/core/dates').DateNames;
+}): any;

package/dist/types/parser/gantt-grammar.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @file The three Gantt token grammars, adapted to the core date
+ * kernel. Mermaid's Gantt header speaks **three different pattern
+ * languages** and none of them is Unicode LDML:
+ *
+ * - `dateFormat` is dayjs' `customParseFormat` vocabulary (moment's
+ *   spelling): `YYYY-MM-DD`, where `YYYY` is the calendar year;
+ * - `axisFormat` is d3-time-format's strftime vocabulary: `%Y-%m-%d`;
+ * - `tickInterval` and a task's duration are two small regular
+ *   grammars of their own (`1week`, `3d`).
+ *
+ * Each gets its own tokenizer here, and each token is mapped
+ * individually onto the LDML token `compileDateFormat`/`compileDateParser`
+ * understand. Handing `YYYY` straight to the core compiler would be a
+ * silent lie — LDML's `YYYY` is the *week-numbering* year, which is
+ * moment's most reported footgun and the reason `@jarenjs/core/dates`
+ * refuses that spelling in the first place.
+ *
+ * Every function here returns `{ value, error }` rather than throwing:
+ * the caller owns the source line, and a `JM` error without one is not
+ * worth much.
+ *
+ * The vendored conformance table for all of this — which tokens the
+ * shipped Mermaid version documents, which of them this engine
+ * implements and why the rest are refused — is
+ * `test/mermaid/fixtures/gantt-grammar.json`, pinned against this file
+ * by `test/mermaid/gantt.test.js`.
+ */
+/** Mermaid's own default when a diagram declares no `dateFormat`. */
+export declare const DEFAULT_DATE_FORMAT = "YYYY-MM-DD";
+/** Mermaid's own default when a diagram declares no `axisFormat`. */
+export declare const DEFAULT_AXIS_FORMAT = "%Y-%m-%d";
+/** dayjs token → the LDML token that reads and writes the same field. */
+declare const MOMENT_TO_LDML: Readonly<{
+    YYYY: "yyyy";
+    YY: "yy";
+    Y: "y";
+    MMMM: "MMMM";
+    MMM: "MMM";
+    MM: "MM";
+    M: "M";
+    DD: "dd";
+    D: "d";
+    HH: "HH";
+    H: "H";
+    hh: "hh";
+    h: "h";
+    mm: "mm";
+    m: "m";
+    ss: "ss";
+    s: "s";
+    SSS: "SSS";
+    S: "S";
+    A: "a";
+    a: "a";
+    ZZ: "XX";
+    Z: "XXX";
+}>;
+/** Documented dayjs tokens this engine will not read, and why. */
+declare const MOMENT_REFUSED: Readonly<{
+    SS: "the fraction tokens are tenths (S) and milliseconds (SSS); there is no hundredths field";
+    Q: "a quarter is derived from a month, not a field of a date";
+    Do: "the ordinal suffix is locale text and this engine ships no ordinal data";
+    DDDD: "the day of the year is derived from a date, not a field of one";
+    DDD: "the day of the year is derived from a date, not a field of one";
+    X: "an epoch second is a whole value, not a calendar field";
+    x: "an epoch millisecond is a whole value, not a calendar field";
+    ww: "the ISO week number is derived from a date, not a field of one";
+    w: "the ISO week number is derived from a date, not a field of one";
+}>;
+/** strftime specifier → the LDML fragment that writes the same field. */
+declare const STRFTIME_TO_LDML: Readonly<{
+    Y: "yyyy";
+    y: "yy";
+    m: "MM";
+    d: "dd";
+    H: "HH";
+    I: "hh";
+    M: "mm";
+    S: "ss";
+    L: "SSS";
+    j: "DDD";
+    a: "EEE";
+    A: "EEEE";
+    b: "MMM";
+    B: "MMMM";
+    p: "a";
+    Z: "XX";
+    x: "MM'/'dd'/'yyyy";
+    X: "HH':'mm':'ss";
+    '%': "'%'";
+}>;
+/** Documented strftime specifiers this engine will not write, and why. */
+declare const STRFTIME_REFUSED: Readonly<{
+    e: "a space-padded day is a token the formatter does not have";
+    c: "it expands to %e, which is unsupported";
+    U: "d3 counts weeks from the first Sunday; the core week number is ISO, so the two disagree";
+    W: "d3 counts weeks from the first Monday; the core week number is ISO, so the two disagree";
+    w: "d3 numbers Sunday 0; the core weekday number is ISO, where 1 is Monday";
+    f: "microseconds are below the millisecond this suite measures time in";
+    g: "the week-based year is a second year field, and the core parts record has one";
+    G: "the week-based year is a second year field, and the core parts record has one";
+    q: "a quarter on a time axis is a label, not a tick this engine plans";
+    Q: "an epoch is a whole value, not a calendar field";
+    s: "an epoch is a whole value, not a calendar field";
+    u: "the ISO weekday number is a tick label this engine does not plan";
+    V: "the ISO week number is a tick label this engine does not plan";
+}>;
+export type Adapted = {
+    value: any;
+    error: string | null;
+};
+/**
+ * Adapt a Mermaid `dateFormat` to an LDML pattern.
+ * @param {string} pattern - a dayjs `customParseFormat` pattern
+ * @returns {Adapted} `value` is the LDML pattern
+ */
+export declare function momentToLdml(pattern: string): Adapted;
+/**
+ * Adapt a Mermaid `axisFormat` to an LDML pattern. This is a separate
+ * grammar from `dateFormat` on purpose: `%m` is a month and `m` is a
+ * minute, so one table serving both would silently mis-read half of
+ * every axis.
+ * @param {string} pattern - a d3-time-format (strftime) pattern
+ * @returns {Adapted} `value` is the LDML pattern
+ */
+export declare function strftimeToLdml(pattern: string): Adapted;
+/**
+ * Whether an LDML pattern uses a token that needs locale names, and
+ * which token that is. Used to turn `compileDateFormat`'s TypeError into
+ * a `JM` error that names the Mermaid spelling and the way out.
+ * @param {string} ldml
+ * @returns {string | null}
+ */
+export declare function ldmlNeedsNames(ldml: string): string | null;
+/**
+ * Parse a `tickInterval` directive.
+ * @param {string} text
+ * @returns {Adapted} `value` is `{ amount, unit }`, the unit a core
+ *   `DATE_UNITS` member
+ */
+export declare function parseTickInterval(text: string): Adapted;
+/**
+ * Parse a task duration (`3d`, `1.5w`, `2M`).
+ * @param {string} text
+ * @returns {Adapted} `value` is `{ amount, unit }`, or `null` with no
+ *   error when the text is simply not a duration (the caller then tries
+ *   to read it as a date)
+ */
+export declare function parseTaskDuration(text: string): Adapted;
+/** ISO weekday numbers, 1 is Monday — the numbering `isoWeekdayFromDays` uses. */
+export declare const ISO_WEEKDAYS: Readonly<{
+    monday: 1;
+    tuesday: 2;
+    wednesday: 3;
+    thursday: 4;
+    friday: 5;
+    saturday: 6;
+    sunday: 7;
+}>;
+/**
+ * Parse a `weekday` directive: which day a whole-week tick starts on.
+ * @param {string} text
+ * @returns {Adapted} `value` is an ISO weekday, 1 to 7
+ */
+export declare function parseWeekday(text: string): Adapted;
+/**
+ * Parse a `weekend` directive: the first of the two days
+ * `excludes weekends` removes.
+ * @param {string} text
+ * @returns {Adapted} `value` is an ISO weekday, 5 (friday) or 6 (saturday)
+ */
+export declare function parseWeekend(text: string): Adapted;
+export { MOMENT_TO_LDML, MOMENT_REFUSED, STRFTIME_TO_LDML, STRFTIME_REFUSED };

package/dist/types/parser/gantt.d.ts

@@ -1,11 +1,41 @@
 /**
- * @file Gantt grammar → gantt AST: a schedule DAG. Header
- * directives (`title`, `dateFormat`, `axisFormat`, `excludes`) go to
- * `meta`; `section` groups tasks; task rows keep their raw metadata
- * string (`:done, id, 2014-01-06, 3d`) verbatim, geometry-free.
+ * @file Gantt grammar → gantt AST: a schedule, resolved.
+ *
+ * Header directives (`title`, `dateFormat`, `axisFormat`, `excludes`,
+ * `tickInterval`, `weekday`, `weekend`, `todayMarker`) are kept verbatim
+ * in `meta` so the printer stays a fixed point, and are *also*
+ * interpreted into `rules` — a compiled date parser, an axis pattern, a
+ * tick step, a working calendar. `section` groups tasks; a task row
+ * keeps its raw metadata string (`:done, id, 2014-01-06, 3d`) in `info`
+ * for the same printing reason and gains the semantic members a
+ * timeline needs: `{ id, flags, start, end, duration, after, line }`,
+ * with `start`/`end` epoch milliseconds and the interval half-open.
+ *
+ * The AST stays geometry-free and plain JSON: no compiled closure and
+ * no coordinate crosses this boundary. Layout re-compiles the axis
+ * pattern from `rules`, once per diagram.
+ *
+ * Three refusals are the whole difference from a permissive reader, and
+ * each one is a `JM` error carrying its source line:
+ *
+ * 1. **No clock.** Mermaid starts an undated first task *today*. This
+ *    engine has no clock (`docs/ROADMAP.md`, "there is no now"), so a
+ *    schedule with no dated anchor is an error rather than a diagram
+ *    that means something different tomorrow.
+ * 2. **No silent literals.** An unsupported `dateFormat` or
+ *    `axisFormat` token is refused by name; Mermaid passes it through as
+ *    literal text, which turns a typo into a date that reads as
+ *    something else.
+ * 3. **No guessed dependencies.** A missing id, a duplicate id, a cycle
+ *    and a reversed or empty span are all errors.
  */
 /**
  * @param {string[]} lines
+ * @param {number} [offset] - 0-based index of `lines[0]` in the source
+ * @param {string} [_header]
+ * @param {{ dateNames?: import('@jarenjs/core/dates').DateNames }} [options]
  * @returns {object}
  */
-export declare function parseGantt(lines: string[]): object;
+export declare function parseGantt(lines: string[], offset?: number, _header?: string, options?: {
+    dateNames?: import('@jarenjs/core/dates').DateNames;
+}): object;

package/dist/types/parser/index.d.ts

@@ -14,9 +14,13 @@ export declare const SECONDARY_TYPES: Set<string>;
 /**
  * Parse Mermaid source into a `DiagramDocument`.
  * @param {string} source
- * @param {{ parseFrontmatter?: (text: string) => any }} [options]
+ * @param {{ parseFrontmatter?: (text: string) => any,
+ *   dateNames?: import('@jarenjs/core/dates').DateNames }} [options] -
+ *   `dateNames` is the locale-name record a Gantt's `dateFormat` needs
+ *   for a month name token; this engine ships none of its own
  * @returns {import('../ast.js').DiagramDocument}
  */
 export declare function parseMermaid(source: string, options?: {
     parseFrontmatter?: (text: string) => any;
+    dateNames?: import('@jarenjs/core/dates').DateNames;
 }): import('../ast.js').DiagramDocument;

package/dist/types/render/gantt.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file Gantt renderer: a positioned schedule → pure-vnode SVG. A real
+ * timeline — an aligned time axis, section bands, task bars, milestone
+ * diamonds, dependency connectors and shaded excluded days — where the
+ * engine used to draw a list of strings in a box.
+ *
+ * It imports `@jarenjs/core` and `@jarenjs/view` and nothing else: the
+ * tick ladder is core's, so this file acquires no dependency on the
+ * chart component to draw a time axis.
+ *
+ * Accessibility: the root carries a `<title>` (the diagram's own title,
+ * or a generic one) and a `<desc>` naming the span and the task count,
+ * so a screen reader gets the shape of the schedule rather than a
+ * hundred unlabelled rectangles. Bars carry `data-id` and a status
+ * class, which is also what an interactive host hit-tests on.
+ */
+/**
+ * @param {any} scene PositionedDiagram (gantt)
+ * @param {{ tokens: Record<string,string>, cssVars: Record<string,string> }} theme
+ * @param {string} hash
+ * @returns {any}
+ */
+export declare function renderGantt(scene: any, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string): any;

package/dist/types/render/misc.d.ts

@@ -2,7 +2,7 @@
  * @file Renderers for the first-class types beyond flowchart and
  * sequence, and an honest placeholder for the deferred secondary
  * types. Pie is
- * a real chart; class/ER/state/gantt render as structured panels — a
+ * a real chart; class and ER render as structured panels — a
  * readable, geometry-light view that renders without error and so counts
  * honestly in the coverage scorecard. Secondary types (mindmap,
  * gitGraph, journey, timeline) render a labeled "not yet laid out"

package/docs/MERMAID-FORMAT.md

@@ -105,7 +105,7 @@ whose grammar permits those characters in ids.
 (`{ kind:'block', blockType, branches:[{ label, statements[] }] }`) for
 loop/opt/alt/par/critical/break.
 
-### 4.3 class / er / state / gantt / pie
+### 4.3 class / er / state / pie
 
 Class: `{ classes:[{ name, label, members[] }], relations[] }`. ER:
 `{ entities:[{ name, attributes[] }], relationships[] }`. State:
@@ -118,10 +118,112 @@ the guard (nesting counted), the effect starts at the first `/` after
 it (or the first `/` at all when there is no guard), and a label that
 fits no pattern — an unmatched `[`, or text between `]` and `/` — reads
 whole as the event, which keeps plain labels meaning what they always
-meant. Gantt: `{ meta, sections:[{ name, tasks[] }] }`. Pie:
-`{ title, showData, slices:[{ label, value }] }`.
+meant. Pie: `{ title, showData, slices:[{ label, value }] }`.
 
-### 4.4 Secondary types
+Gantt is `{ meta, rules, sections:[{ name, tasks[] }], domain }` and is
+described in §4.4, because it is the one AST that carries a *resolved*
+answer rather than only what the source said.
+
+### 4.4 gantt — a resolved schedule
+
+```
+{ meta, rules, sections:[{ name, tasks[] }], domain:{ start, end } }
+```
+
+`meta` holds the header lines **verbatim** (`title`, `dateFormat`,
+`axisFormat`, `excludes`, `tickInterval`, `weekday`, `weekend`,
+`todayMarker`), which is what keeps `printGantt` a fixed point. `rules`
+holds the same directives *interpreted*:
+`{ dateFormat, axisFormat, tick, weekStart, weekendStart, excludes,
+todayMarker }`, where `tick` is `{ amount, unit }` or `null`,
+`weekStart`/`weekendStart` are ISO weekdays (1 is Monday), and
+`excludes` is `{ weekends, weekdays[], days[] }` with `days` as day
+indexes from 1970-01-01.
+
+A task is
+`{ name, info, id, flags, start, end, duration, after, line }`. `info`
+is the raw metadata string the printer emits; the rest is the schedule.
+`start`/`end` are epoch milliseconds and the interval is **half-open**,
+so `end` is the first instant the task no longer occupies — except a
+milestone, which is the instant `start === end`. `flags` is the subset
+of `done`, `active`, `crit`, `milestone` in that order. `domain` is the
+half-open span every task falls inside, and it is what layout scales
+against.
+
+The AST stays geometry-free and plain JSON: no compiled closure and no
+coordinate crosses this boundary. `layout/gantt.js` re-compiles the axis
+pattern from `rules`, once per diagram.
+
+#### The three grammars
+
+A Gantt header speaks three pattern languages and **none of them is
+Unicode LDML**, so each gets its own tokenizer and each token is mapped
+individually onto the core vocabulary (`src/parser/gantt-grammar.js`):
+
+| Directive | Grammar | Example |
+|---|---|---|
+| `dateFormat` | dayjs `customParseFormat` (moment's spelling) | `DD-MM-YYYY` |
+| `axisFormat` | d3-time-format (strftime) | `%Y-%m-%d` |
+| `tickInterval` | `^([1-9]\d*)(millisecond\|second\|minute\|hour\|day\|week\|month)$` | `1week` |
+| a task duration | `^(\d+(?:\.\d+)?)([Mdhmswy]\|ms)$` | `3d`, `1.5w`, `2M` |
+
+Handing `YYYY` straight to the core compiler would be a silent lie —
+LDML's `YYYY` is the *week-numbering* year, so `YYYY-MM-DD` read as LDML
+answers 2019 for `2018-12-31`. Note also that moment's `m` is a minute
+while strftime's `%m` is a month: one shared table would mis-read half
+of every diagram.
+
+An **unsupported** token is a `JM` error naming the token and the
+reason, not a literal passed through. The vendored conformance table —
+every documented token of the Mermaid version this engine tracks, marked
+supported or refused with its reason, plus the provenance of where it
+was read — is `test/mermaid/fixtures/gantt-grammar.json`, and
+`test/mermaid/gantt.test.js` pins the code against it in both
+directions.
+
+Both directions is a closed loop, so the table is also checked against
+the shipped chunk it was read from: dayjs' parse table is inlined there,
+and every token Mermaid really accepts must appear. A token in neither
+list is not refused — it becomes literal text, and then the diagram's
+own dates are what look wrong. `w`, `ww` and `Y` reached the tree that
+way; the week numbers are now refused by name (a week number is derived
+from a date rather than a field of one, which is why `compileDateParser`
+will not read one either) and `Y` is the signed variable-width year
+core's `y` already spells.
+
+#### Task forms and working days
+
+The field-count rule is Mermaid's own: one field is an end, two are a
+start and an end, three add an explicit id in front, and the four flags
+lead. `after <id …>` starts a task at the latest end of those ids;
+`until <id …>` ends it at the earliest start of those. Ids may be
+forward references — resolution is a topological pass — and a cycle, a
+missing id, a duplicate id, a reversed span and an empty non-milestone
+span are all refused with the offending line.
+
+`excludes` removes whole days: `weekends` (the `weekend` day and the one
+after it, saturday by default), weekday names, and dates written in the
+document's own `dateFormat`. An end derived from a *duration* is pushed
+out one day per excluded day it crosses; an end written as an explicit
+*date* is the author's answer and is never pushed. The probes are the
+instants `start + k days`, so a task starting Friday noon and lasting a
+day ends Monday noon. Days are UTC days. This is not a holiday service:
+a schedule skips exactly what its own `excludes` line lists.
+
+#### Three deliberate divergences from Mermaid
+
+1. **No clock.** Mermaid starts an undated first task *today*. This
+   engine has no clock anywhere (`docs/ROADMAP.md`, "there is no now"),
+   so a schedule with no dated anchor is a `JM` error rather than a
+   diagram that means something different tomorrow. In practice only the
+   first task needs a date. For the same reason `todayMarker` is kept
+   in `meta` and never drawn.
+2. **No silent literals** — an unsupported pattern token is refused by
+   name, where Mermaid passes it through as text.
+3. **No guessed dependencies** — Mermaid falls back to today for an
+   `after` naming an unknown id; this engine refuses.
+
+### 4.5 Secondary types
 
 mindmap, gitGraph, journey, timeline, quadrantChart, requirement
 parse-accept into `{ diagram, lines[] }` and render an honest "not yet

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/mermaid",
   "private": false,
-  "version": "0.46.5",
+  "version": "0.49.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -77,8 +77,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/charts": "^0.46.5",
-    "@jarenjs/core": "^0.46.5",
-    "@jarenjs/view": "^0.46.5"
+    "@jarenjs/charts": "^0.49.2",
+    "@jarenjs/core": "^0.49.2",
+    "@jarenjs/view": "^0.49.2"
   }
 }