@graview/core 0.1.0

package/dist/schema/define-node.js

@@ -0,0 +1,254 @@
+/**
+ * The single declaration everything else derives from. Views, agent tool
+ * schemas, drag legality, aggregate contents and accessibility labels all
+ * read this — nothing is sealed, every derived value stays inspectable.
+ */
+export function defineNode(kind, spec) {
+    return {
+        ...spec,
+        kind,
+        edges: (spec.edges ?? {}),
+    };
+}
+/**
+ * Whether a node is CURRENT under its kind's declared lifecycle.
+ *
+ * True when the kind declares no lifecycle — currency is opt-in, and a kind
+ * that never retires anything should not pay for the concept. `today` is
+ * injectable so a test (or a view pinned to a survey date) can ask about a
+ * different day; it defaults to the real one.
+ */
+export function isCurrent(definition, node, today = new Date().toISOString().slice(0, 10)) {
+    const lifecycle = definition?.lifecycle;
+    if (!lifecycle)
+        return true;
+    const value = node[lifecycle.field];
+    if (lifecycle.retired === "date") {
+        // No date means no expiry: an open-ended node is current for ever.
+        if (typeof value !== "string" || value.length === 0)
+            return true;
+        return value >= today;
+    }
+    return !lifecycle.retired.includes(value);
+}
+/**
+ * WHAT TELLS TWO SAME-NAMED THINGS APART, among the nodes a person is
+ * choosing from. A single and its album are both "Blue Hour", and every
+ * picker, every ask and the Find strip listed "Blue Hour, Blue Hour": a
+ * choice nobody could make. For each node whose name another in the list
+ * shares, the first fact that differs between them — "single" and "album",
+ * or the dates — else its kind, else its id. Nodes with a name of their
+ * own get nothing.
+ */
+export function tellApart(nodes, definitionOf) {
+    const apart = new Map();
+    const byName = new Map();
+    for (const node of nodes) {
+        const name = labelOf(definitionOf(node.kind), node).trim().toLowerCase();
+        byName.set(name, [...(byName.get(name) ?? []), node]);
+    }
+    for (const same of byName.values()) {
+        if (same.length < 2)
+            continue;
+        const byKind = new Map();
+        for (const node of same)
+            byKind.set(node.kind, [...(byKind.get(node.kind) ?? []), node]);
+        for (const [kind, alike] of byKind) {
+            // One of its kind among namesakes of other kinds: the kind is what differs.
+            if (alike.length === 1) {
+                apart.set(alike[0].id, nounOf(definitionOf(kind), kind));
+                continue;
+            }
+            const facts = alike.map((node) => new Map(readableFields(node, definitionOf(node.kind)).map((field) => [field.key, field.alone])));
+            const keys = [...new Set(facts.flatMap((fact) => [...fact.keys()]))];
+            // A word before a number: "single" and "album" say more than two dates.
+            const wordy = (key) => facts.every((fact) => !/\d/.test(fact.get(key) ?? ""));
+            const ordered = [...keys.filter(wordy), ...keys.filter((key) => !wordy(key))];
+            const telling = ordered.find((key) => new Set(facts.map((fact) => fact.get(key) ?? "")).size === alike.length);
+            alike.forEach((node, at) => {
+                const fact = telling ? facts[at].get(telling) : undefined;
+                apart.set(node.id, fact ?? node.id);
+            });
+        }
+    }
+    return apart;
+}
+/** Resolves a node's display label, honouring the declaration's override. */
+export function labelOf(definition, node) {
+    if (definition?.label) {
+        return definition.label(node);
+    }
+    const own = node["label"];
+    return typeof own === "string" && own.length > 0 ? own : node.id;
+}
+/**
+ * Prose, shortened to a length, at a WORD BOUNDARY.
+ *
+ * Every app here had `text.slice(0, 60)` in its label function, and every one
+ * of them produced headings like "Hold the banked hour for a night s" — cut
+ * mid-word, with no ellipsis, in the largest type on the page. It is the
+ * obvious thing to write and it is wrong every time, so the framework should
+ * own it rather than leaving each app to discover it.
+ *
+ * A single word longer than the limit is still cut, because the alternative
+ * is a heading that ignores the limit it was given.
+ */
+export function summarise(text, max = 60) {
+    const clean = text.trim().replace(/\s+/g, " ");
+    if (clean.length <= max)
+        return clean;
+    const cut = clean.slice(0, max);
+    const boundary = cut.lastIndexOf(" ");
+    // A trailing comma or full stop before the ellipsis reads as a typo.
+    return `${(boundary > max * 0.5 ? cut.slice(0, boundary) : cut).replace(/[\s,.;:]+$/, "")}…`;
+}
+/** Resolves a node's prose description, used for a11y and tool text. */
+export function describeNode(definition, node) {
+    if (definition?.describe) {
+        return definition.describe(node);
+    }
+    return `${node.kind} ${labelOf(definition, node)}`;
+}
+/** Never shown: identity and the name, which the heading already is. */
+const NOT_A_FIELD = new Set(["id", "kind", "label"]);
+/** `effectiveFrom` shown to a person is a schema leaking through a surface. */
+export function humaniseField(field) {
+    const spaced = field
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim()
+        .toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * A field in words, as the declaration says it: its `display.labels` entry,
+ * else the key spoken. Every sentence that names a field — "Nothing
+ * declared writes the planned time", a tooltip, a refusal — reads it here,
+ * so `plannedAt` never reaches a person from one surface while another says
+ * "Planned at".
+ */
+export function fieldWords(definition, key) {
+    return definition?.display?.labels?.[key] ?? humaniseField(key);
+}
+/*
+ * "a item" is the sound of generated prose.
+ *
+ * Every surface here writes sentences about a kind the author named —
+ * "Add a item", "Nothing you may do with a item", "from a item it is
+ * captioned" — and a kind is as likely to begin with a vowel as not. The
+ * article is therefore never a literal: it is derived from the word, in one
+ * place, so that the scaffolder, the checker and the strip cannot disagree.
+ *
+ * Sound, not spelling, decides it, and the two disagree in exactly two small
+ * families that domain vocabulary is full of: "a user", "a unit" (the "yoo"
+ * sound), and "an hour", "an heir" (the silent h). Both are listed rather
+ * than guessed at.
+ */
+const SOUNDS_LIKE_YOU = /^(u[nt]i|use|usu|uti|ubiq|eu|ewe|one|once)/;
+const SILENT_H = /^(hour|honest|hono[ur]r?|heir)/;
+/** "a" or "an", by how the word SOUNDS. */
+export function article(word) {
+    const first = humaniseField(word).toLowerCase();
+    if (SILENT_H.test(first))
+        return "an";
+    if (SOUNDS_LIKE_YOU.test(first))
+        return "a";
+    return /^[aeiou]/.test(first) ? "an" : "a";
+}
+/**
+ * A kind in words, with its article: "an item", "a work order".
+ *
+ * Takes the declared id and speaks it — the hyphen in `work-order` is a
+ * identifier's punctuation, not a word's.
+ */
+export function withArticle(word) {
+    return `${article(word)} ${humaniseField(word).toLowerCase()}`;
+}
+/**
+ * What one of a kind is called: its declared `noun`, else its id spoken.
+ * Every sentence about ONE of them — "Change the staff member", "a staff
+ * member called …", "Remove the staff member" — reads this, never the id.
+ */
+export function nounOf(definition, kind) {
+    return definition?.noun ?? humaniseField(kind).toLowerCase();
+}
+/** Whether `line` carries `value` as whole words: "2027 Subaru Forester" says "Subaru" and "2027", not "Sub". */
+function saysAsWords(line, value) {
+    if (value.length === 0)
+        return false;
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[\\s·,(/])${escaped}($|[\\s·,)/])`).test(line);
+}
+/**
+ * WHICH of a node's fields a person sees, and HOW each one reads.
+ *
+ * One implementation, because there were two: the record on a page and the
+ * summary on a card each decided this for themselves, and every rule — hide an
+ * ordering key, format minutes as a time, render a boolean as a word, drop a
+ * value the heading already said — had to be written into both and kept in
+ * step by hand. They diverged the day the second one was written, which is how
+ * a summary card ended up showing a list's ordering key as a chip reading "0"
+ * while the page beside it did not.
+ *
+ * `said` is what the surrounding view has already put on screen. A value the
+ * heading already carries is not information twice, it is the same sentence
+ * twice — and where the heading is a SHORTENED form of a field, an exact
+ * comparison never catches it, so the summary's stem is compared too.
+ */
+export function readableFields(node, definition, options = {}) {
+    const display = definition?.display;
+    const skip = new Set([...NOT_A_FIELD, ...(display?.hide ?? [])]);
+    const said = (options.said ?? []).filter((text) => Boolean(text));
+    const stems = said
+        .filter((text) => text.endsWith("…"))
+        .map((text) => text.replace(/…$/, "").trim())
+        .filter((stem) => stem.length > 12);
+    const fields = [];
+    for (const [key, value] of Object.entries(node)) {
+        if (skip.has(key) || value === undefined || value === null)
+            continue;
+        const format = display?.format?.[key];
+        /*
+         * A NESTED OBJECT HAS NO ONE-LINE RENDERING, and inventing one is worse
+         * than leaving it to a view that knows what it is.
+         *
+         * That was true of an object and was not checked of an ARRAY of them,
+         * which fell through to `join(", ")` — so a piece of ground with a
+         * five-corner outline had a field on its record reading "[object
+         * Object], [object Object], [object Object], [object Object]". Nobody
+         * wrote that; nobody could have read it. The shape is drawn on the map
+         * and belongs there, not in a list of words.
+         *
+         * A declaration that HAS a one-line rendering says so with `format`,
+         * and then it is the declaration's sentence rather than this one's
+         * guess — "5 corners" is a useful thing to say and only the app knows
+         * that the numbers are corners.
+         */
+        const nested = typeof value === "object" &&
+            (!Array.isArray(value) || value.some((one) => typeof one === "object" && one !== null));
+        if (nested && format === undefined)
+            continue;
+        const text = format
+            ? format(value)
+            : Array.isArray(value)
+                ? value.join(", ")
+                : typeof value === "boolean"
+                    ? // Nobody says "false". A boolean is a state, and the words for a
+                        // state are words.
+                        value
+                            ? "Yes"
+                            : "No"
+                    : String(value);
+        if (said.includes(text) || stems.some((stem) => text.startsWith(stem)))
+            continue;
+        if (options.glance && (typeof value === "string" || typeof value === "number") && said.some((line) => saysAsWords(line, text)))
+            continue;
+        const label = fieldWords(definition, key);
+        const alone = typeof value === "number" ? `${label} ${text}` : typeof value === "boolean" ? `${label}: ${text.toLowerCase()}` : text;
+        fields.push({ key, label, value: text, alone });
+        if (fields.length >= (options.limit ?? 10))
+            break;
+    }
+    return fields;
+}
+//# sourceMappingURL=define-node.js.map

package/dist/schema/define-node.js.map

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

package/dist/schema/figures.d.ts

@@ -0,0 +1,42 @@
+/** A kind's figure: inline SVG, or the name of one from the shipped set. */
+export type Figure = string;
+/**
+ * THE SHIPPED SET — a small vocabulary, so a first app has something true
+ * to point at before anybody draws anything.
+ *
+ * Deliberately few and deliberately generic: the things almost every domain
+ * turns out to have. A kind that is none of these declares its own, and the
+ * agent draws it (see `graview figure`).
+ *
+ * Each is drawn on a 24-unit box at the same three-quarter angle, in a
+ * single stroke weight, with no fill: the isometric city's own language,
+ * so twelve of them on one screen read as one drawing rather than as
+ * twelve clip-art imports.
+ */
+export declare const FIGURES: Readonly<Record<string, string>>;
+export declare const FIGURE_NAMES: string[];
+/** The SVG a figure names, or the figure itself when it is already one. */
+export declare function figureSvg(figure: Figure | undefined): string | undefined;
+/**
+ * What is wrong with a figure, in the words of somebody about to fix it.
+ *
+ * Art with no `viewBox` cannot be sized by anything that draws it, a
+ * literal colour ignores the scheme and the kind's hue, a `fill` that is
+ * not `none` turns a line drawing into a blob at chip size, a name that is
+ * not in the shipped set is a silent blank — and anything in the markup
+ * that is not a drawing is not a figure at all.
+ */
+/**
+ * THE BRIEF A FIGURE IS DRAWN FROM — the rules, in the words somebody draws
+ * to, with a shipped figure beside them as the style.
+ *
+ * The shipped set is nine, deliberately generic, and any domain that is not
+ * an abstract tracker runs out of it immediately: an outdoors product needed
+ * eleven figures and had to draw ten. Growing the set would move the wall
+ * rather than remove it, so the authoring loop is the answer — and it works
+ * through the door every app has, which is a prompt to copy and an answer to
+ * paste. No key, no vendor, no seam the CLI has no business holding.
+ */
+export declare function figureBrief(kind: string, from: string): string;
+export declare function figureFaults(figure: Figure): readonly string[];
+//# sourceMappingURL=figures.d.ts.map

package/dist/schema/figures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figures.d.ts","sourceRoot":"","sources":["../../src/schema/figures.ts"],"names":[],"mappings":"AAuBA,4EAA4E;AAC5E,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyEpD,CAAC;AAEF,eAAO,MAAM,YAAY,UAAuB,CAAC;AAEjD,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxE;AA4BD;;;;;;;;GAQG;AACH;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAuB9D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAuC9D"}

package/dist/schema/figures.js

@@ -0,0 +1,220 @@
+/*
+ * A KIND HAS A FIGURE: a drawing of the THING, not an emblem for it.
+ *
+ * Every kind is drawn the same way today — a coloured dot on its chips, a
+ * plural on its district, an isometric block at altitude, a heading on its
+ * page. The picture would say far more if a kind carried a drawing of what
+ * it represents: a person's silhouette, a plot of ground, a vehicle, a
+ * cleat. The scene, the Graview and, where it fits, the pages then draw it
+ * wherever the kind is drawn, from one declaration.
+ *
+ * HONEST GEOMETRY, and it is the whole rule here. A figure is line art of
+ * the thing — single weight, drawn from the isometric city's own three-
+ * quarter angle, no fill but the ground's. It is never a decorative badge, a
+ * rounded-square app icon, or a shape chosen because it filled the space.
+ * A kind whose figure is a circle with a smaller circle in it has learnt
+ * nothing about itself and taught the reader nothing.
+ *
+ * Everything is `currentColor`, so a figure takes the scheme, the kind's own
+ * hue and the brand's ink without being redrawn; one `viewBox`, so every
+ * surface can size it; and it must read at twenty pixels, because that is
+ * the size a chip gives it.
+ */
+/**
+ * THE SHIPPED SET — a small vocabulary, so a first app has something true
+ * to point at before anybody draws anything.
+ *
+ * Deliberately few and deliberately generic: the things almost every domain
+ * turns out to have. A kind that is none of these declares its own, and the
+ * agent draws it (see `graview figure`).
+ *
+ * Each is drawn on a 24-unit box at the same three-quarter angle, in a
+ * single stroke weight, with no fill: the isometric city's own language,
+ * so twelve of them on one screen read as one drawing rather than as
+ * twelve clip-art imports.
+ */
+export const FIGURES = {
+    /**
+     * Somebody, STANDING. Head, torso, arms, legs — a figure on the ground.
+     *
+     * It was a head and shoulders, and at chip size that read as a person the
+     * way any shape does when it is four pixels tall. Standing a district on
+     * it showed what it actually was: two crescents, one over an open arc,
+     * because a head drawn as two arcs is a circle only while it is too small
+     * to see. A figure has to be the thing at every size it is drawn.
+     */
+    person: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<circle cx="11.6" cy="5.4" r="2.5"/>' +
+        '<path d="M7.9 12.4c0-2.1 1.7-3.8 3.7-3.8s3.7 1.7 3.7 3.8v3.2H7.9z"/>' +
+        '<path d="M8 12.6 6.4 17.2"/><path d="M15.2 12.6 16.8 17.2"/>' +
+        '<path d="M9.8 15.6v5"/><path d="M13.4 15.6v5"/></svg>',
+    /** A piece of ground, seen from above and to the side. */
+    plot: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M2.6 9.4 12 4.6l9.4 4.8-9.4 4.8z"/><path d="M2.6 9.4v4.4l9.4 4.8 9.4-4.8V9.4"/>' +
+        '<path d="M12 14.2v4.4"/><path d="M7 11.9v3"/><path d="M17 11.9v3"/></svg>',
+    /** A thing with a lid, standing on the ground: a box, a crate, a case. */
+    box: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M3.4 7.9 12 3.6l8.6 4.3-8.6 4.3z"/><path d="M3.4 7.9v8.2L12 20.4l8.6-4.3V7.9"/>' +
+        '<path d="M12 12.2v8.2"/></svg>',
+    /** Something to be done: a card with a line struck across its corner. */
+    task: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M4.4 6.6 12 2.9l7.6 3.7v9.5L12 19.8 4.4 16.1z"/><path d="M12 12.4v7.4"/>' +
+        '<path d="M4.4 6.6 12 10.3l7.6-3.7"/><path d="M8 9.6l2.4 2.4L16 8.4"/></svg>',
+    /** A stretch of time: a block with its hours ruled across it. */
+    shift: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M3.2 8.2 12 4l8.8 4.2-8.8 4.2z"/><path d="M3.2 8.2v7.2L12 19.6l8.8-4.2V8.2"/>' +
+        '<path d="M12 12.4v7.2"/><path d="M6.6 10.8v3.4"/><path d="M9.3 12v3.4"/></svg>',
+    /** A place things live: a tray, open at the front. */
+    list: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M2.8 10.4 12 6l9.2 4.4-9.2 4.4z"/><path d="M2.8 10.4v3.2L12 18l9.2-4.4v-3.2"/>' +
+        '<path d="M6.6 8.6 15.8 13"/><path d="M9.4 7.2 18.6 11.6"/></svg>',
+    /** Something to drive: a body on wheels, seen from three-quarters. */
+    vehicle: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M2.8 14.2 5 9.4l8.6-1.6 5.4 3-1 3.6z"/><path d="M2.8 14.2v2.2h2.4"/>' +
+        '<path d="M18 16.4h1.9l.1-2.2"/><circle cx="7.6" cy="16.6" r="1.9"/><circle cx="16.1" cy="16.6" r="1.9"/>' +
+        '<path d="M8.6 8.2 9.8 12l7.2-1"/></svg>',
+    /**
+     * A rule: a set square STANDING on the ground, graduated up its upright.
+     *
+     * It was a ruler lying across the box on the diagonal, which is a flat
+     * thing floating at an angle — fine as a glyph, nothing at all as a
+     * building. A standard is an object you stand a thing against.
+     */
+    rule: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M5.4 19.4V6.6l12 12.8z"/>' +
+        '<path d="M5.4 6.6 7.6 5.5l12 12.8-2.2 1.1"/>' +
+        '<path d="M5.4 19.4 7.6 18.3h12"/>' +
+        '<path d="M5.4 10.1h1.7"/><path d="M5.4 13.3h1.7"/><path d="M5.4 16.5h1.7"/></svg>',
+    /**
+     * A note somebody left: a leaf of paper standing up, seen from three
+     * quarters, its corner turned and two lines written on it.
+     *
+     * It was a flat document icon — the one figure in the set drawn square to
+     * the page while everything around it stood in the city's own projection,
+     * which is exactly the clip-art import the house style forbids.
+     */
+    note: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">' +
+        '<path d="M6.2 6.2 14.8 10.5v9L6.2 15.2z"/>' +
+        '<path d="M12.4 9.3 14.8 10.5l-.6 2.3"/>' +
+        '<path d="M8.2 10.6 12.8 12.9"/><path d="M8.2 13.2 11.4 14.8"/></svg>',
+};
+export const FIGURE_NAMES = Object.keys(FIGURES);
+/** The SVG a figure names, or the figure itself when it is already one. */
+export function figureSvg(figure) {
+    if (!figure)
+        return undefined;
+    return FIGURES[figure] ?? (figure.trimStart().startsWith("<svg") ? figure : undefined);
+}
+/**
+ * A FIGURE IS LINE ART, and these are the only things line art is made of.
+ *
+ * Everything drawn here is declared in code the bundle already runs — until
+ * a figure arrives from somewhere else. A model asked to draw a kind can
+ * answer with an `<svg>` carrying a `<script>`, an `onload`, or a remote
+ * `href`, and a drawing is inserted as markup wherever it is shown; a check
+ * of the house style alone would have passed all three, because none of
+ * them is a colour or a viewBox. So the vocabulary is closed: these
+ * elements, these attributes, and anything else is a fault with a name.
+ *
+ * It is one judgement rather than a second sanitiser beside the first,
+ * because the surfaces that draw a figure already ask this function's
+ * caller — `graview check`, `graview figure`, the agent that draws one —
+ * whether the drawing is any good.
+ */
+const DRAWING_ELEMENTS = new Set([
+    "svg", "g", "title", "desc", "path", "circle", "ellipse", "rect", "line", "polyline", "polygon",
+]);
+const DRAWING_ATTRIBUTES = new Set([
+    "viewbox", "xmlns", "width", "height", "fill", "fill-rule", "clip-rule", "stroke", "stroke-width",
+    "stroke-linecap", "stroke-linejoin", "stroke-dasharray", "stroke-dashoffset", "stroke-miterlimit",
+    "opacity", "fill-opacity", "stroke-opacity", "vector-effect", "transform", "d", "cx", "cy", "r",
+    "rx", "ry", "x", "y", "x1", "y1", "x2", "y2", "points", "role", "aria-hidden", "focusable",
+]);
+/**
+ * What is wrong with a figure, in the words of somebody about to fix it.
+ *
+ * Art with no `viewBox` cannot be sized by anything that draws it, a
+ * literal colour ignores the scheme and the kind's hue, a `fill` that is
+ * not `none` turns a line drawing into a blob at chip size, a name that is
+ * not in the shipped set is a silent blank — and anything in the markup
+ * that is not a drawing is not a figure at all.
+ */
+/**
+ * THE BRIEF A FIGURE IS DRAWN FROM — the rules, in the words somebody draws
+ * to, with a shipped figure beside them as the style.
+ *
+ * The shipped set is nine, deliberately generic, and any domain that is not
+ * an abstract tracker runs out of it immediately: an outdoors product needed
+ * eleven figures and had to draw ten. Growing the set would move the wall
+ * rather than remove it, so the authoring loop is the answer — and it works
+ * through the door every app has, which is a prompt to copy and an answer to
+ * paste. No key, no vendor, no seam the CLI has no business holding.
+ */
+export function figureBrief(kind, from) {
+    return [
+        `Draw a figure for a node kind called "${kind}": ${from}.`,
+        "",
+        "It is line art of the THING, not an emblem for it — never a badge, never a",
+        "rounded-square app icon, never a shape chosen because it filled the space.",
+        "Draw it from a three-quarter isometric angle, the same angle as a city seen",
+        "from above and to the side, so a dozen of them on one screen read as one",
+        "drawing rather than as twelve clip-art imports.",
+        "",
+        "Answer with the SVG and nothing else. It must:",
+        '  - be one <svg> with viewBox="0 0 24 24" and no width or height;',
+        '  - stroke with currentColor, fill="none", stroke-width 1.4,',
+        "    stroke-linecap and stroke-linejoin round;",
+        "  - use only path, circle, ellipse, rect, line, polyline, polygon and g;",
+        "  - carry no literal colour anywhere, no class, no style, no id;",
+        "  - READ AT TWENTY PIXELS, because that is the size a chip gives it.",
+        "",
+        "This is the shipped figure for a person, as the style to match:",
+        FIGURES["person"] ?? "",
+        "",
+        `Then: graview figure <entry> --kind ${kind} --judge <the file you saved it in>`,
+    ].join("\n");
+}
+export function figureFaults(figure) {
+    if (!figure.trimStart().startsWith("<svg")) {
+        return FIGURE_NAMES.includes(figure)
+            ? []
+            : [`"${figure}" is not one of the shipped figures (${FIGURE_NAMES.join(", ")}).`];
+    }
+    const faults = [];
+    const box = /viewBox\s*=\s*"([^"]+)"/.exec(figure);
+    if (!box)
+        faults.push("it has no viewBox, so nothing that draws it can size it.");
+    else if (box[1].trim().split(/\s+/).length !== 4) {
+        faults.push(`its viewBox "${box[1]}" is not four numbers.`);
+    }
+    /*
+     * A literal colour anywhere. `currentColor` is what lets one drawing take
+     * the scheme, the kind's hue and the brand's ink without being redrawn —
+     * and a figure that hard-codes #333 is invisible in one of the two
+     * schemes, which nobody notices until somebody switches.
+     */
+    const literal = /(?:stroke|fill)\s*=\s*"(?!none|currentColor)([^"]+)"/.exec(figure);
+    if (literal) {
+        faults.push(`it paints with "${literal[1]}" — use currentColor so it takes the scheme and the kind's hue.`);
+    }
+    if (!/stroke\s*=\s*"currentColor"/.test(figure)) {
+        faults.push('nothing in it is stroked with currentColor, so it will not be drawn in the kind\'s ink.');
+    }
+    /*
+     * THE VOCABULARY IS CLOSED. Named rather than stripped: a drawing with a
+     * script in it is not a drawing with a fixable blemish, and whoever is
+     * about to keep it should be told what was in it.
+     */
+    for (const [, element] of figure.matchAll(/<\s*\/?\s*([a-zA-Z][\w:-]*)/g)) {
+        const name = (element ?? "").toLowerCase();
+        if (!DRAWING_ELEMENTS.has(name))
+            faults.push(`it contains <${element}>, which is not something a line drawing is made of.`);
+    }
+    for (const [, attribute] of figure.matchAll(/[\s"']([a-zA-Z][\w:-]*)\s*=/g)) {
+        const name = (attribute ?? "").toLowerCase();
+        if (!DRAWING_ATTRIBUTES.has(name))
+            faults.push(`it carries ${attribute}, which is not a drawing attribute.`);
+    }
+    return [...new Set(faults)];
+}
+//# sourceMappingURL=figures.js.map

package/dist/schema/figures.js.map

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

package/dist/schema/json-schema.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { AnySchema } from "./schema.js";
+import type { AnyNodeDefinition } from "./types.js";
+export type JsonSchema = Record<string, unknown>;
+/**
+ * One source, three outputs: the same Zod declaration produces runtime
+ * validation, TypeScript inference, and the JSON Schema an agent tool
+ * definition needs. Nothing is written twice, so nothing drifts.
+ */
+export declare function toJsonSchema(schema: z.ZodType): JsonSchema;
+/** JSON Schema for one node kind, including its id and kind discriminator. */
+export declare function nodeJsonSchema(definition: AnyNodeDefinition): JsonSchema;
+export interface MutationToolSchema {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    /** Arguments that name graph nodes, and the kinds each accepts. */
+    readonly nodeRefs: readonly {
+        name: string;
+        kinds: readonly string[];
+        optional: boolean;
+    }[];
+}
+/**
+ * Derives an agent-facing tool schema from a mutation declaration. The
+ * `nodeRefs` metadata travels alongside so a caller can resolve "a person"
+ * to real ids without the agent guessing.
+ */
+export declare function mutationToolSchema(mutation: {
+    name: string;
+    title?: string;
+    description?: string;
+    input: z.ZodType;
+    creates?: readonly string[];
+}): MutationToolSchema;
+/** Every node kind's JSON Schema, keyed by kind. */
+export declare function schemaJson(schema: AnySchema): Record<string, JsonSchema>;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/schema/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/schema/json-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,UAAU,CAU1D;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,UAAU,EAAE,iBAAiB,GAAG,UAAU,CAOxE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC7F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,GAAG,kBAAkB,CAkCrB;AAED,oDAAoD;AACpD,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAMxE"}