reladraw 0.0.1 → 0.2.0

package/dist/grammar.js

@@ -0,0 +1,215 @@
+/**
+ * The language's *lexical* vocabulary, and a scanner that classifies one line of
+ * source into colored spans.
+ *
+ * This is deliberately separate from `parser.ts`, and it is not a second parser.
+ * The parser answers "what does this file mean" and refuses anything it cannot
+ * answer for; a highlighter has to color a half-typed line without complaint,
+ * so it answers only "what kind of word is this" and never fails. Every rule
+ * below is a regex applied to a single line, in priority order, with one bit of
+ * carried state (whether anything has been seen on the line yet, and whether the
+ * previous token was an attribute key).
+ *
+ * **That restriction is the point, and it is what makes this reusable.** An
+ * Emacs `font-lock-keywords` list, a Vim `syntax match` file and a TextMate
+ * grammar are all exactly this: an ordered list of single-line regexes with a
+ * face attached. So the vocabulary here — which is the half that goes stale, and
+ * which is imported from `ast.ts`, `constants.ts` and `icons.ts` rather than
+ * retyped — can be emitted into any of those without this file being ported.
+ * The scanner is the JavaScript consumer of the same spec, and the playground is
+ * its only caller.
+ *
+ * Nothing in the language spans lines: `//` runs to the end of one, a string
+ * closes on one, and there are no blocks. That is the property those editor
+ * formats need and the reason a `.reladraw` grammar is small in all of them.
+ */
+import { DIRECTIONS, EDGES, PASSAGE_AXES } from './ast.js';
+/**
+ * The words a statement may open with. `parseStatement` in `parser.ts` is the
+ * authority — its switch is what actually accepts them — and this list mirrors
+ * it. A word missing here is a word that draws in the plain color, which is a
+ * dull page rather than a wrong one.
+ */
+export const STATEMENT_KEYWORDS = ['box', 'note', 'link', 'deck', 'style', 'diagram'];
+/** Statements whose second word declares a name. `diagram` has none. */
+const DECLARES_NAME = ['box', 'note', 'deck', 'style'];
+/**
+ * Every word that says something about where a thing goes. Assembled from the
+ * lists the parser itself reads, so a direction or a passage axis added there
+ * colors here without anybody remembering to come back.
+ */
+export const RELATION_WORDS = [
+    ...DIRECTIONS,
+    ...EDGES,
+    ...Object.keys(PASSAGE_AXES),
+    // The connecting words. `of` is optional after a direction, `and` joins
+    // targets, `between` opens a passage, `level with` is the alignment.
+    'of',
+    'and',
+    'level',
+    'with',
+    'between',
+];
+/** Longest first, so `above-left` is not read as `above` followed by `-left`. */
+function alternation(words) {
+    return [...new Set(words)].sort((a, b) => b.length - a.length).join('|');
+}
+/**
+ * The patterns, as source strings, so a generator can emit them into another
+ * editor's grammar without reaching into a compiled RegExp. Each is written to
+ * match at the point the scanner has reached; the scanner adds the sticky flag.
+ *
+ * A name may contain dots (containment) and hyphens, which is why the word
+ * pattern is what it is rather than `\w+`.
+ */
+export const PATTERNS = {
+    comment: '\\/\\/.*',
+    // The closing quote is optional: every string is unterminated for as long as
+    // it is being typed, and a highlighter that waits for the quote repaints the
+    // rest of the file on every keystroke.
+    string: '"(?:\\\\.|[^"\\\\])*"?',
+    keyword: `(?:${alternation(STATEMENT_KEYWORDS)})\\b`,
+    // `<->` first, or `<-` would match its opening half and leave a stray `>`.
+    arrow: '<->|->|<-',
+    attribute: '[A-Za-z][A-Za-z0-9_-]*:',
+    color: '#[0-9A-Fa-f]{3,8}\\b',
+    relation: `(?:${alternation(RELATION_WORDS)})\\b`,
+    bracket: '[()]',
+    // Matches what `tokenizeLine` treats as one bare token, and the awkwardness is
+    // load-bearing rather than accidental. A `(` counts as punctuation only where
+    // a token starts, so `rgb(20,20,20)` is one word — hence the first character
+    // being spelled differently from the rest. A lone `/` is ordinary and only a
+    // doubled one opens a comment, which is what the lookahead is for.
+    word: '(?:[^\\s()"\\/]|\\/(?!\\/))(?:[^\\s"\\/]|\\/(?!\\/))*',
+    /**
+     * The same, inside an open bracket, where `)` closes the group instead of
+     * being an ordinary character. An editor grammar that cannot count brackets
+     * should use this one throughout: mistaking `rgb(20,20,20)` for three tokens
+     * is a smaller wrong than swallowing the `)` that ends `(gap: tight)`.
+     */
+    wordInGroup: '(?:[^\\s()"\\/]|\\/(?!\\/))(?:[^\\s)"\\/]|\\/(?!\\/))*',
+};
+/**
+ * The rules that are pure regex, in priority order. Three things are missing and
+ * each for a reason: a comment wins over all of them and is tried first, a
+ * bracket is punctuation only at certain depths so the scanner counts them
+ * itself, and the catch-all word rule varies with that same depth and is
+ * appended per call.
+ */
+const RULES = [
+    { kind: 'string', re: sticky(PATTERNS.string) },
+    { kind: 'arrow', re: sticky(PATTERNS.arrow) },
+    // Before `relation`, because the trailing colon is what tells `left: …` from
+    // the `left` of a placement, and after `arrow` so `->` is never a word.
+    { kind: 'attribute', re: sticky(PATTERNS.attribute) },
+    { kind: 'color', re: sticky(PATTERNS.color) },
+    { kind: 'relation', re: sticky(PATTERNS.relation) },
+];
+const SPACE = sticky('[ \\t]+');
+const COMMENT = sticky(PATTERNS.comment);
+const KEYWORD = sticky(PATTERNS.keyword);
+const WORD = sticky(PATTERNS.word);
+const WORD_IN_GROUP = sticky(PATTERNS.wordInGroup);
+function sticky(source) {
+    return new RegExp(source, 'y');
+}
+function match(re, line, at) {
+    re.lastIndex = at;
+    const found = re.exec(line);
+    return found ? found[0] : null;
+}
+/**
+ * Classify one line. Always returns spans covering it end to end, in order, so a
+ * caller can rebuild the text by concatenation and can trust that nothing was
+ * dropped — which is what a highlighter drawn *behind* a textarea needs, since
+ * a lost character would slide every following one out of register.
+ */
+export function highlightLine(line) {
+    const spans = [];
+    let at = 0;
+    /** Nothing but whitespace seen yet, so the next word is the statement keyword. */
+    let opening = true;
+    /** The last thing emitted was a `key:`, so the next word is its value. */
+    let expectingValue = false;
+    /** How many brackets are open, which is what makes a `)` punctuation. */
+    let depth = 0;
+    const push = (kind, end) => {
+        spans.push({ kind, start: at, end });
+        at = end;
+    };
+    while (at < line.length) {
+        const gap = match(SPACE, line, at);
+        if (gap !== null) {
+            push('plain', at + gap.length);
+            continue;
+        }
+        // A comment wins everywhere, including in the middle of a statement.
+        const comment = match(COMMENT, line, at);
+        if (comment !== null) {
+            push('comment', at + comment.length);
+            continue;
+        }
+        if (opening) {
+            opening = false;
+            const keyword = match(KEYWORD, line, at);
+            if (keyword !== null) {
+                push('keyword', at + keyword.length);
+                if (DECLARES_NAME.includes(keyword)) {
+                    const space = match(SPACE, line, at);
+                    if (space !== null) {
+                        push('plain', at + space.length);
+                        const name = match(WORD, line, at);
+                        // `style backup  border: …` declares a name; `box  fill: red` is a
+                        // half-typed line whose second word is already an attribute, and
+                        // coloring that as a name would be a lie about what it is.
+                        if (name !== null && !name.endsWith(':'))
+                            push('name', at + name.length);
+                    }
+                }
+                continue;
+            }
+        }
+        // Brackets before the rest, and only where they are really punctuation: an
+        // opening one wherever a token starts, a closing one only while a group is
+        // open. That is `tokenizeLine`'s rule, and it is what keeps an unquoted
+        // `rgb(20,20,20)` a single word rather than three.
+        const ch = line[at];
+        if (ch === '(') {
+            depth += 1;
+            expectingValue = false;
+            push('bracket', at + 1);
+            continue;
+        }
+        if (ch === ')' && depth > 0) {
+            depth -= 1;
+            expectingValue = false;
+            push('bracket', at + 1);
+            continue;
+        }
+        let matched = false;
+        for (const rule of [...RULES, { kind: 'plain', re: depth > 0 ? WORD_IN_GROUP : WORD }]) {
+            const text = match(rule.re, line, at);
+            if (text === null)
+                continue;
+            // An attribute's value is whatever single token follows it, whatever it
+            // would otherwise have been called: `to: right` is a value, not a
+            // direction, and `style: wide` is a style name, not a gap.
+            const kind = expectingValue && rule.kind !== 'string' && rule.kind !== 'color' && rule.kind !== 'bracket'
+                ? 'value'
+                : rule.kind;
+            expectingValue = rule.kind === 'attribute';
+            push(kind, at + text.length);
+            matched = true;
+            break;
+        }
+        // Nothing in `RULES` can fail on a non-space character, but a scanner that
+        // could loop forever is not worth the saved line.
+        if (!matched)
+            push('plain', at + 1);
+    }
+    return spans;
+}
+/** Every line of a source file, classified. Line endings are not included. */
+export function highlight(source) {
+    return source.split(/\r?\n/).map(highlightLine);
+}

package/dist/icons.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The built-in icon set.
+ *
+ * Every glyph is path data written into the SVG, and that is the whole reason
+ * this file exists rather than a dependency. The output contract is a standalone
+ * document: an icon font would render as blank boxes on any machine that does
+ * not have the font, and an `<image href>` would need the file to travel beside
+ * the SVG. Inline paths cost a few hundred bytes each and always arrive.
+ *
+ * A name here says what the thing *is*, never what the picture looks like. The
+ * same discipline as `gap: wide` over `gap: 110` and `muted` over a hex value:
+ * the word is the whole interface, so it has to carry meaning rather than
+ * geometry, and naming the meaning is what lets the drawing be improved later
+ * without every diagram that uses it changing sense.
+ *
+ * The set is deliberately small. In a drawing tool you pick a shape out of a
+ * visual palette and hundreds are browsable; here you type the word from memory,
+ * which caps the useful vocabulary at something that fits in a head. Add a name
+ * when a diagram asks for a distinction it cannot otherwise make.
+ */
+/**
+ * Icons carry three tones rather than colors. `ink` is the drawn line, `shade`
+ * the body it encloses, and `void` is the page showing through — the same
+ * knockout a link label already uses. Naming tones instead of colors is what
+ * lets one glyph sit correctly on a dark theme and a light one.
+ */
+export type IconTone = 'ink' | 'shade' | 'void';
+export interface IconPath {
+    d: string;
+    fill?: IconTone;
+    stroke?: IconTone;
+}
+export interface Icon {
+    /** Side of the square the paths are drawn on. Scaled to the drawn size. */
+    readonly grid: number;
+    readonly paths: readonly IconPath[];
+}
+/** Line width on the 24-unit grid, scaled with everything else. */
+export declare const ICON_STROKE = 1.1;
+export declare const ICONS: Record<string, Icon>;
+export declare const ICON_NAMES: string[];
+/**
+ * The icon a node asks for, or nothing. Called by the resolver, which reserves
+ * the room, and by the renderer, which fills it, so the two cannot disagree
+ * about whether there is an icon at all.
+ *
+ * An unknown name is refused rather than dropped. That is the same rule
+ * `DIAGRAM_KEYS` follows and it is here for the same reason: a misspelt
+ * `icon: laptp` that quietly draws nothing is indistinguishable from the tool
+ * being broken, and an author will stare at the file looking for the mistake in
+ * the wrong place. Since the vocabulary is closed and short, the error can list
+ * the whole of it.
+ */
+/**
+ * The outlines a box can take. `box` is the plain rectangle and needs no word.
+ *
+ * Named for what a node *is*, never for the geometry, which is the same rule the
+ * icon names follow: `document` and not `folded-corner`. A shape carrying a
+ * conventional meaning is a second channel alongside color, and a stronger one
+ * — a fill is whatever the author assigned and has to be learnt from the
+ * diagram, while a folded corner has meant "an artifact, not a process" in
+ * flowcharts for decades and reads with no legend at all.
+ */
+export declare const BOX_SHAPES: readonly ["document"];
+export type BoxShape = 'box' | (typeof BOX_SHAPES)[number];
+export interface NodeShape {
+    outline: BoxShape;
+    /**
+     * Set when the node is drawn as a glyph rather than as a box. There is then
+     * no outline, no fill and no padding: the node *is* the picture, and its size
+     * is the picture's. `icon:` decorates a box, this replaces it.
+     */
+    body?: Icon;
+}
+/**
+ * What a node is drawn as. Shared by the resolver, which sizes it, and the
+ * renderer, which draws it.
+ *
+ * The value is either a box outline or the name of a glyph. Those are the two
+ * things "what is this drawn as" can answer, and the author has no reason to
+ * care which category their answer fell into. The test that separates them is
+ * whether the node still sizes itself from its label: a `document` does, a
+ * glyph does not.
+ */
+export declare function shapeFor(appearance: Record<string, string>, line: number): NodeShape;
+export declare function iconFor(appearance: Record<string, string>, line: number): Icon | undefined;

package/dist/icons.js

@@ -0,0 +1,166 @@
+/**
+ * The built-in icon set.
+ *
+ * Every glyph is path data written into the SVG, and that is the whole reason
+ * this file exists rather than a dependency. The output contract is a standalone
+ * document: an icon font would render as blank boxes on any machine that does
+ * not have the font, and an `<image href>` would need the file to travel beside
+ * the SVG. Inline paths cost a few hundred bytes each and always arrive.
+ *
+ * A name here says what the thing *is*, never what the picture looks like. The
+ * same discipline as `gap: wide` over `gap: 110` and `muted` over a hex value:
+ * the word is the whole interface, so it has to carry meaning rather than
+ * geometry, and naming the meaning is what lets the drawing be improved later
+ * without every diagram that uses it changing sense.
+ *
+ * The set is deliberately small. In a drawing tool you pick a shape out of a
+ * visual palette and hundreds are browsable; here you type the word from memory,
+ * which caps the useful vocabulary at something that fits in a head. Add a name
+ * when a diagram asks for a distinction it cannot otherwise make.
+ */
+import { SourceError } from './errors.js';
+const GRID = 24;
+/** Line width on the 24-unit grid, scaled with everything else. */
+export const ICON_STROKE = 1.1;
+/** A full circle as one path, so the data below can stay declarative. */
+function circle(cx, cy, r) {
+    return `M${cx - r} ${cy} a${r} ${r} 0 1 0 ${r * 2} 0 a${r} ${r} 0 1 0 ${-r * 2} 0 Z`;
+}
+/** The three visible faces of an isometric cube, top face centered on `cx, cy`. */
+function cube(cx, cy, s) {
+    const half = s / 2;
+    return [
+        { d: `M${cx} ${cy} L${cx + s} ${cy + half} L${cx} ${cy + s} L${cx - s} ${cy + half} Z`, fill: 'shade', stroke: 'ink' },
+        { d: `M${cx - s} ${cy + half} L${cx} ${cy + s} L${cx} ${cy + s * 2} L${cx - s} ${cy + s * 1.5} Z`, fill: 'shade', stroke: 'ink' },
+        { d: `M${cx + s} ${cy + half} L${cx} ${cy + s} L${cx} ${cy + s * 2} L${cx + s} ${cy + s * 1.5} Z`, fill: 'shade', stroke: 'ink' },
+    ];
+}
+export const ICONS = {
+    /** A spinning disk: the physical drive, not the filesystem on it. */
+    disk: {
+        grid: GRID,
+        paths: [
+            { d: 'M4 2 h16 a1.6 1.6 0 0 1 1.6 1.6 v16.8 a1.6 1.6 0 0 1 -1.6 1.6 h-16 a1.6 1.6 0 0 1 -1.6 -1.6 v-16.8 a1.6 1.6 0 0 1 1.6 -1.6 Z', fill: 'shade', stroke: 'ink' },
+            { d: circle(12, 10.6, 6.2), fill: 'void', stroke: 'ink' },
+            { d: circle(12, 10.6, 1.9), fill: 'ink' },
+            { d: 'M11.5 12.6 L12.9 13.4 L8.8 19.6 a1.25 1.25 0 0 1 -2.1 -1.35 Z', fill: 'ink' },
+        ],
+    },
+    /** A workstation: monitor, keyboard and tower. */
+    desktop: {
+        grid: GRID,
+        paths: [
+            { d: 'M1.2 2.6 h12.4 v9.2 h-12.4 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M6.3 11.8 h2.2 v1.7 h-2.2 Z', fill: 'ink' },
+            { d: 'M4.2 13.5 h6.4 v1.1 h-6.4 Z', fill: 'ink' },
+            { d: 'M1.2 16.4 h12.4 v3.2 h-12.4 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M2.6 17.6 h7.8 v0.9 h-7.8 Z', fill: 'ink' },
+            { d: 'M16.2 2.6 h6.6 v17 h-6.6 Z', fill: 'shade', stroke: 'ink' },
+            { d: circle(19.5, 5.2, 0.9), fill: 'ink' },
+            { d: 'M17.4 9.4 h4.2 v0.7 h-4.2 Z M17.4 11.4 h4.2 v0.7 h-4.2 Z M17.4 13.4 h4.2 v0.7 h-4.2 Z', fill: 'ink' },
+        ],
+    },
+    /** A portable machine. Open lid, so the screen is the page showing through. */
+    laptop: {
+        grid: GRID,
+        paths: [
+            { d: 'M4 3.6 h16 v11.4 h-16 Z', fill: 'void', stroke: 'ink' },
+            { d: 'M2.2 16 h19.6 l1.6 2.6 a0.7 0.7 0 0 1 -0.6 1.1 h-21.6 a0.7 0.7 0 0 1 -0.6 -1.1 Z', fill: 'ink' },
+            { d: 'M9.6 17.2 h4.8 v1 h-4.8 Z', fill: 'shade' },
+        ],
+    },
+    /** Something stored as a whole rather than run: an archive, a bucket, a sync root. */
+    package: {
+        grid: GRID,
+        paths: [
+            { d: 'M12 2.6 L22 7.4 L12 12.2 L2 7.4 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M2 7.4 L12 12.2 L12 21 L2 16.2 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M22 7.4 L12 12.2 L12 21 L22 16.2 Z', fill: 'shade', stroke: 'ink' },
+        ],
+    },
+    /**
+     * Several interchangeable units of the same kind, as a group. Three rather
+     * than any particular number: this is the symbol for "several", and at two
+     * line-heights square a literal count turns to mush. Where the count carries
+     * meaning — where one of them is the end of an arrow — they are nodes, and
+     * `shape: instance` is how you draw them.
+     */
+    cubes: {
+        grid: GRID,
+        paths: [...cube(6.6, 2.6, 4.4), ...cube(17.4, 2.6, 4.4), ...cube(12, 11.6, 4.4)],
+    },
+    /** One unit of the kind `cubes` shows several of. */
+    instance: {
+        grid: GRID,
+        paths: cube(12, 2.6, 8.4),
+    },
+    /** A store queried rather than read as files. */
+    database: {
+        grid: GRID,
+        paths: [
+            { d: 'M3 6.4 v11.2 a9 3.4 0 0 0 18 0 v-11.2 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M3 6.4 a9 3.4 0 0 1 18 0 a9 3.4 0 0 1 -18 0 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M3 11 a9 3.4 0 0 0 18 0', stroke: 'ink' },
+            { d: 'M3 15.6 a9 3.4 0 0 0 18 0', stroke: 'ink' },
+        ],
+    },
+};
+export const ICON_NAMES = Object.keys(ICONS);
+/**
+ * The icon a node asks for, or nothing. Called by the resolver, which reserves
+ * the room, and by the renderer, which fills it, so the two cannot disagree
+ * about whether there is an icon at all.
+ *
+ * An unknown name is refused rather than dropped. That is the same rule
+ * `DIAGRAM_KEYS` follows and it is here for the same reason: a misspelt
+ * `icon: laptp` that quietly draws nothing is indistinguishable from the tool
+ * being broken, and an author will stare at the file looking for the mistake in
+ * the wrong place. Since the vocabulary is closed and short, the error can list
+ * the whole of it.
+ */
+/**
+ * The outlines a box can take. `box` is the plain rectangle and needs no word.
+ *
+ * Named for what a node *is*, never for the geometry, which is the same rule the
+ * icon names follow: `document` and not `folded-corner`. A shape carrying a
+ * conventional meaning is a second channel alongside color, and a stronger one
+ * — a fill is whatever the author assigned and has to be learnt from the
+ * diagram, while a folded corner has meant "an artifact, not a process" in
+ * flowcharts for decades and reads with no legend at all.
+ */
+export const BOX_SHAPES = ['document'];
+const PLAIN = { outline: 'box' };
+/**
+ * What a node is drawn as. Shared by the resolver, which sizes it, and the
+ * renderer, which draws it.
+ *
+ * The value is either a box outline or the name of a glyph. Those are the two
+ * things "what is this drawn as" can answer, and the author has no reason to
+ * care which category their answer fell into. The test that separates them is
+ * whether the node still sizes itself from its label: a `document` does, a
+ * glyph does not.
+ */
+export function shapeFor(appearance, line) {
+    const named = appearance['shape'];
+    if (named === undefined)
+        return PLAIN;
+    if (named === 'box')
+        return PLAIN;
+    if (BOX_SHAPES.includes(named))
+        return { outline: named };
+    const glyph = ICONS[named];
+    if (glyph !== undefined)
+        return { outline: 'box', body: glyph };
+    throw new SourceError(`there is no shape called "${named}". The shapes are box, ${BOX_SHAPES.join(', ')}, ` +
+        `and any icon drawn as the node itself: ${ICON_NAMES.join(', ')}`, line);
+}
+export function iconFor(appearance, line) {
+    const named = appearance['icon'];
+    if (named === undefined)
+        return undefined;
+    const icon = ICONS[named];
+    if (icon === undefined) {
+        throw new SourceError(`there is no icon called "${named}". The icons are ${ICON_NAMES.join(', ')}`, line);
+    }
+    return icon;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './ast.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './grammar.js';
+export * from './measure.js';
+export * from './model.js';
+export { parse } from './parser.js';
+export { resolve, type ResolveOptions } from './resolve.js';
+export { render, DARK_THEME, type RenderOptions, type Theme } from './render.js';
+import { type RenderOptions } from './render.js';
+import { type ResolveOptions } from './resolve.js';
+/** Source text in, SVG out. The whole pipeline in one call. */
+export declare function compile(source: string, options?: ResolveOptions & RenderOptions): string;

package/dist/index.js

@@ -0,0 +1,16 @@
+export * from './ast.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './grammar.js';
+export * from './measure.js';
+export * from './model.js';
+export { parse } from './parser.js';
+export { resolve } from './resolve.js';
+export { render, DARK_THEME } from './render.js';
+import { parse } from './parser.js';
+import { render } from './render.js';
+import { resolve } from './resolve.js';
+/** Source text in, SVG out. The whole pipeline in one call. */
+export function compile(source, options = {}) {
+    return render(resolve(parse(source), options), options);
+}

package/dist/lexer.d.ts

@@ -0,0 +1,25 @@
+export interface Token {
+    text: string;
+    /** True when the token came from a quoted string, so `foo:` inside it is literal. */
+    quoted: boolean;
+}
+/**
+ * Split one line into tokens. Whitespace separates; double quotes group, with
+ * `\"` and `\\` as the only escapes. A `//` outside quotes starts a comment and
+ * runs to the end of the line, so a comment may trail a statement.
+ *
+ * A lone `/` is an ordinary character, which keeps a path or a ratio writable
+ * unquoted. `#` is ordinary too: it opens a hex color, which is why comments
+ * are spelled `//` rather than the `#` an earlier version used.
+ *
+ * Parentheses group the modifiers on a placement — `left of hub (gap: wide)` —
+ * and are tokens in their own right so that `(gap:` does not read as one word
+ * ending in a colon. They are deliberately *not* punctuation everywhere: an
+ * opening bracket counts only where a token starts, and a closing one only
+ * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
+ *
+ * Returns an empty array for a blank or comment-only line.
+ */
+export declare function tokenizeLine(line: string, lineNumber: number): Token[];
+/** A bare token ending in `:` opens the attribute section of a statement. */
+export declare function isAttrKey(token: Token): boolean;

package/dist/lexer.js

@@ -0,0 +1,91 @@
+import { SourceError } from './errors.js';
+/**
+ * Split one line into tokens. Whitespace separates; double quotes group, with
+ * `\"` and `\\` as the only escapes. A `//` outside quotes starts a comment and
+ * runs to the end of the line, so a comment may trail a statement.
+ *
+ * A lone `/` is an ordinary character, which keeps a path or a ratio writable
+ * unquoted. `#` is ordinary too: it opens a hex color, which is why comments
+ * are spelled `//` rather than the `#` an earlier version used.
+ *
+ * Parentheses group the modifiers on a placement — `left of hub (gap: wide)` —
+ * and are tokens in their own right so that `(gap:` does not read as one word
+ * ending in a colon. They are deliberately *not* punctuation everywhere: an
+ * opening bracket counts only where a token starts, and a closing one only
+ * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
+ *
+ * Returns an empty array for a blank or comment-only line.
+ */
+export function tokenizeLine(line, lineNumber) {
+    const tokens = [];
+    let i = 0;
+    let depth = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === ' ' || ch === '\t') {
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && line[i + 1] === '/')
+            break;
+        if (ch === '(') {
+            depth += 1;
+            tokens.push({ text: '(', quoted: false });
+            i += 1;
+            continue;
+        }
+        if (ch === ')' && depth > 0) {
+            depth -= 1;
+            tokens.push({ text: ')', quoted: false });
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            let text = '';
+            i += 1;
+            let closed = false;
+            while (i < line.length) {
+                const c = line[i];
+                if (c === '\\' && i + 1 < line.length) {
+                    const next = line[i + 1];
+                    // `\/` is the one escape that must survive tokenizing. The line break
+                    // it escapes is not resolved until `splitLines`, long after this, so
+                    // collapsing it to a bare `/` here would lose the fact that the
+                    // author asked for a literal. Every other escape resolves now.
+                    text += next === '/' ? '\\/' : next;
+                    i += 2;
+                    continue;
+                }
+                if (c === '"') {
+                    closed = true;
+                    i += 1;
+                    break;
+                }
+                text += c;
+                i += 1;
+            }
+            if (!closed)
+                throw new SourceError('unterminated string', lineNumber);
+            tokens.push({ text, quoted: true });
+            continue;
+        }
+        let text = '';
+        while (i < line.length) {
+            const c = line[i];
+            if (c === ' ' || c === '\t' || c === '"')
+                break;
+            if (c === '/' && line[i + 1] === '/')
+                break;
+            if (c === ')' && depth > 0)
+                break;
+            text += c;
+            i += 1;
+        }
+        tokens.push({ text, quoted: false });
+    }
+    return tokens;
+}
+/** A bare token ending in `:` opens the attribute section of a statement. */
+export function isAttrKey(token) {
+    return !token.quoted && token.text.length > 1 && token.text.endsWith(':');
+}

package/dist/measure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Text measurement, kept behind one interface on purpose.
+ *
+ * The parser and resolver are pure — text in, geometry out — and the only part
+ * of the system that needs to know about fonts is this. In Node there is no
+ * rendering engine to ask, so the default implementation assumes a monospace
+ * face, where every glyph has the same advance width and the answer is
+ * arithmetic. In a browser the same interface can be backed by the DOM, which
+ * measures exactly.
+ */
+export interface TextBox {
+    width: number;
+    height: number;
+    lines: string[];
+}
+export interface Measurer {
+    /** Font family written into the SVG. Must match what was measured. */
+    readonly fontFamily: string;
+    measure(text: string, fontSize: number): TextBox;
+    lineHeight(fontSize: number): number;
+}
+/**
+ * A slash with whitespace on both sides marks a line break, so a label is
+ * really a short stack of lines. Each line is trimmed; empty ones are dropped.
+ *
+ * The whitespace is what makes the marker safe. Splitting on a bare `/` meant
+ * no label could contain one, so `TCP/IP` came out as two lines, and so did
+ * `16/9`, `I/O` and every path or URL. Requiring the spaces keeps the marker
+ * legible where it is meant — `"Computer 1 / Ubuntu"` — while a
+ * slash inside a word stays an ordinary character.
+ *
+ * That leaves the label that wants a spaced slash and no break — `Before / After`
+ * — which writes it `\/`. The lexer preserves that escape rather than resolving
+ * it, so the backslash is still here to suppress the split, and is dropped once
+ * the splitting is done.
+ */
+export declare function splitLines(text: string): string[];
+export declare function monospaceMeasurer(fontFamily?: string, advanceRatio?: number): Measurer;