@theoremjs/react 0.0.0-stage → 0.3.1

package/client/shaped-data.js

@@ -0,0 +1,343 @@
+/**
+ * The rules `ShapedData` draws a payload by, as plain decisions: which shape a
+ * value takes, what a row is called, what a field's label and unit are. The
+ * component only maps each decision to its Astryx part.
+ */
+/** Fields that name a row, in the order they're tried. */
+const TITLE_KEYS = ['name', 'title', 'label', 'headline', 'subject', 'id'];
+/** Fields that place or sort a row, shown as tokens beside its title. */
+const TAG_KEYS = [
+    'country',
+    'region',
+    'state',
+    'admin1',
+    'city',
+    'category',
+    'type',
+    'kind',
+    'status',
+];
+const MAX_TAGS = 2;
+const MAX_TAG_LENGTH = 24;
+/** Fields that say, in a line, what a row is. */
+const DESCRIPTION_KEYS = [
+    'description',
+    'summary',
+    'snippet',
+    'extract',
+    'subtitle',
+    'address',
+    'display_name',
+    'text',
+];
+/** Fields that link a row to its page. */
+const LINK_KEYS = ['url', 'link', 'href'];
+/** Fields a list row shows beyond its name, line, link, and tags, at its end. */
+const MAX_LIST_EXTRAS = 2;
+/** A list of flat objects with at most this many fields reads as a table. */
+const MAX_TABLE_COLUMNS = 6;
+/** Rows shown before the rest are left to the JSON view. */
+export const MAX_ROWS = 50;
+/** A list of plain values this short sits inline as tokens beside the other fields. */
+const MAX_INLINE_TOKENS = 8;
+/** Levels drawn before a subtree shows as JSON. */
+const MAX_DEPTH = 8;
+export const ISO_DATE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+export function isRow(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isPlain(value) {
+    return value === null || typeof value !== 'object';
+}
+const UNREADABLE = '[Unreadable]';
+const NO_TO_JSON = Symbol('no toJSON');
+/** A read that throws reads as a marker. */
+function readSafe(read) {
+    try {
+        return read();
+    }
+    catch {
+        return UNREADABLE;
+    }
+}
+/** What the value's own toJSON gives, made safe; NO_TO_JSON when it has none. */
+function viaToJSON(value, inside) {
+    const own = value.toJSON;
+    return typeof own === 'function' ? jsonSafe(own.call(value), inside) : NO_TO_JSON;
+}
+/**
+ * What JSON.stringify can't take, made plain: a cycle, a BigInt, a property
+ * that throws when read. Each becomes a marker in place, so the rest still shows.
+ */
+function jsonSafe(value, ancestors = []) {
+    if (typeof value === 'bigint')
+        return String(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (ancestors.includes(value))
+        return '[Circular]';
+    const inside = [...ancestors, value];
+    const converted = readSafe(() => viaToJSON(value, inside));
+    if (converted !== NO_TO_JSON)
+        return converted;
+    if (Array.isArray(value))
+        return value.map((item) => jsonSafe(item, inside));
+    return Object.fromEntries(Object.keys(value).map((key) => [key, readSafe(() => jsonSafe(value[key], inside))]));
+}
+/** The value as indented JSON, whatever it holds. */
+export function json(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? String(value);
+    }
+    catch {
+        return JSON.stringify(jsonSafe(value), null, 2) ?? String(value);
+    }
+}
+/** A string that holds a JSON object or list, parsed; anything else as it came. */
+export function unpacked(value) {
+    if (typeof value !== 'string')
+        return value;
+    const text = value.trim();
+    if (!/^[[{]/.test(text))
+        return value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return value;
+    }
+}
+/** `country_code`, `countryCode` → "Country code". */
+export function humanize(key) {
+    const words = key
+        .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+        .replace(/([a-zA-Z])(\d)/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** A unit worth printing: a symbol or abbreviation, not a format name like `iso8601` or `wmo code`. */
+export function printableUnit(unit) {
+    if (typeof unit !== 'string' || unit === '' || /\s/.test(unit) || unit === 'iso8601')
+        return undefined;
+    return unit;
+}
+/** Unit suffixes a key can end in (`distance_m`, `duration_ms`), and the unit each prints as. */
+const SUFFIX_UNITS = {
+    m: 'm',
+    km: 'km',
+    mi: 'mi',
+    ms: 'ms',
+    s: 's',
+    sec: 's',
+    min: 'min',
+    h: 'h',
+    kg: 'kg',
+    g: 'g',
+    pct: '%',
+    percent: '%',
+    c: '°C',
+    f: '°F',
+    usd: 'USD',
+    eur: 'EUR',
+    gbp: 'GBP',
+    jpy: 'JPY',
+};
+/** The unit a key's suffix names, and the key without it: `distance_m` → Distance, m. */
+function suffixUnit(key) {
+    const match = /^(.+?)[_-]([a-z]+)$/i.exec(key);
+    const unit = match ? SUFFIX_UNITS[(match[2] ?? '').toLowerCase()] : undefined;
+    return match?.[1] && unit ? { label: humanize(match[1]), unit } : undefined;
+}
+/** A column's label and unit: from its `<key>_units` entry, else its key's suffix. */
+export function fieldLabel(key, units) {
+    const listed = printableUnit(units?.[key]);
+    if (listed)
+        return { label: humanize(key), unit: listed };
+    return suffixUnit(key) ?? { label: humanize(key) };
+}
+/** A field's label and the unit its value reads with. A unit only reads onto a number: `country_code` stays "Country code". */
+export function fieldReading(key, value, units) {
+    if (typeof value !== 'number')
+        return { label: humanize(key) };
+    return fieldLabel(key, units);
+}
+/** The `<key>_units` object beside `key`, if there is one. */
+export function unitsOf(row, key) {
+    const units = row[`${key}_units`];
+    return isRow(units) ? units : undefined;
+}
+/** A row's fields, less the units objects its other fields read. */
+export function shownEntries(row) {
+    return Object.entries(row).filter(([key, value]) => !(key.endsWith('_units') && isRow(value) && key.slice(0, -'_units'.length) in row));
+}
+/** A string that's a date: a bare day or a moment. */
+function dateReading(text) {
+    if (!ISO_DATE.test(text))
+        return undefined;
+    const date = new Date(text);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return text.includes('T') ? { kind: 'date-time', date } : { kind: 'date', date };
+}
+export function plainReading(value, unit) {
+    if (value === null || value === undefined)
+        return { kind: 'none' };
+    if (typeof value === 'boolean')
+        return { kind: 'boolean', value };
+    if (typeof value === 'number')
+        return unit ? { kind: 'number', value, unit } : { kind: 'number', value };
+    const text = String(value);
+    if (/^https?:\/\/\S+$/.test(text))
+        return { kind: 'link', href: text };
+    return dateReading(text) ?? { kind: 'text', text };
+}
+/** A formatted number with its unit: symbols sit close (21°C, 35%), words stand apart (320 m). */
+export function withUnit(number, unit) {
+    if (!unit)
+        return number;
+    return /^[°%]/.test(unit) ? `${number}${unit}` : `${number} ${unit}`;
+}
+/** The field that names a row, if it has one. */
+export function titleKey(row) {
+    return TITLE_KEYS.find((key) => typeof row[key] === 'string' || typeof row[key] === 'number');
+}
+/** Up to two short strings that place or sort a row. */
+function tags(row, skip) {
+    return TAG_KEYS.filter((key) => {
+        const value = row[key];
+        return (key !== skip &&
+            typeof value === 'string' &&
+            value.length > 0 &&
+            value.length <= MAX_TAG_LENGTH);
+    })
+        .slice(0, MAX_TAGS)
+        .map((key) => row[key]);
+}
+/** A flat row's parts, if a name and a line say what it is. */
+function listRow(item) {
+    if (!isRow(item) || !Object.values(item).every(isPlain))
+        return undefined;
+    const title = titleKey(item);
+    const description = DESCRIPTION_KEYS.find((key) => typeof item[key] === 'string' && item[key] !== '');
+    if (!title || !description)
+        return undefined;
+    const link = LINK_KEYS.find((key) => typeof item[key] === 'string' && /^https?:\/\//.test(item[key]));
+    const rowTags = tags(item, title);
+    const shown = new Set([title, description, link]);
+    const extras = Object.entries(item).filter(([key, value]) => !shown.has(key) && !(TAG_KEYS.includes(key) && rowTags.includes(value)));
+    if (extras.length > MAX_LIST_EXTRAS)
+        return undefined;
+    return {
+        title: String(item[title]),
+        description: item[description],
+        href: link ? item[link] : undefined,
+        tags: rowTags,
+        extras,
+    };
+}
+/** A collapsible row's heading and what it opens to: a titled row loses its title field; else it's named by its place. */
+export function rowHeading(item) {
+    if (!isRow(item))
+        return { tags: [], rest: item };
+    const key = titleKey(item);
+    if (!key)
+        return { tags: tags(item, undefined), rest: item };
+    return {
+        title: String(item[key]),
+        tags: tags(item, key),
+        rest: Object.fromEntries(Object.entries(item).filter(([k]) => k !== key)),
+    };
+}
+/** Small flat objects sharing their fields: a table's rows. */
+function tableColumns(items) {
+    if (items.length < 2 || !items.every((item) => isRow(item) && Object.values(item).every(isPlain)))
+        return undefined;
+    const columns = [...new Set(items.flatMap((item) => Object.keys(item)))];
+    return columns.length <= MAX_TABLE_COLUMNS ? columns : undefined;
+}
+/** An object of equal-length lists of plain values (a column store): a table's columns. */
+export function columnStore(row) {
+    const entries = shownEntries(row);
+    if (entries.length < 2)
+        return undefined;
+    const lengths = new Set(entries.map(([, value]) => (Array.isArray(value) && value.every(isPlain) ? value.length : -1)));
+    const [length] = lengths;
+    return lengths.size === 1 && length !== undefined && length >= 2
+        ? entries.map(([key]) => key)
+        : undefined;
+}
+/** A column store's lists, turned into rows. */
+export function storeRows(row, columns) {
+    const lists = columns.map((key) => row[key]);
+    return (lists[0] ?? []).map((_, index) => Object.fromEntries(columns.map((key, k) => [key, lists[k]?.[index]])));
+}
+function listShape(items) {
+    if (items.length === 0)
+        return { kind: 'none' };
+    if (items.every(isPlain))
+        return { kind: 'tokens', items };
+    const listed = items.map(listRow);
+    if (listed.every((row) => row !== undefined))
+        return { kind: 'list', rows: listed };
+    const columns = tableColumns(items);
+    return columns ? { kind: 'table', columns, rows: items } : { kind: 'rows', items };
+}
+function rowShape(row) {
+    if (Object.keys(row).length === 0)
+        return { kind: 'none' };
+    const store = columnStore(row);
+    return store
+        ? { kind: 'table', columns: store, rows: storeRows(row, store) }
+        : { kind: 'fields', row };
+}
+/** How a value (already unpacked) at `depth` is drawn. */
+export function shapeOf(value, depth) {
+    if (depth > MAX_DEPTH)
+        return { kind: 'json' };
+    if (Array.isArray(value))
+        return listShape(value);
+    return isRow(value) ? rowShape(value) : { kind: 'plain' };
+}
+/** Text this long, or on several lines, reads as prose: full width, as Markdown. */
+const PROSE_CHARS = 160;
+export function isProse(value) {
+    return typeof value === 'string' && (value.length > PROSE_CHARS || value.includes('\n'));
+}
+/** A field that sits in the field list: a plain value (prose aside), or a short list of them. */
+function isInline(value) {
+    const inner = unpacked(value);
+    if (isProse(inner))
+        return false;
+    if (isPlain(inner))
+        return true;
+    return (Array.isArray(inner) &&
+        inner.length > 0 &&
+        inner.length <= MAX_INLINE_TOKENS &&
+        inner.every(isPlain));
+}
+function section(row, key) {
+    const path = [key];
+    let inner = unpacked(row[key]);
+    let units = unitsOf(row, key);
+    while (isRow(inner)) {
+        // why: A units object beside the one field doesn't count: `{ hourly, hourly_units }` is still a wrapper.
+        const entries = shownEntries(inner);
+        const only = entries.length === 1 ? entries[0] : undefined;
+        if (!only || isPlain(unpacked(only[1])))
+            break;
+        path.push(only[0]);
+        units = unitsOf(inner, only[0]);
+        inner = unpacked(only[1]);
+    }
+    return { key, title: path.map(humanize).join(' › '), value: inner, units };
+}
+/** An object's fields split: plain ones for the field list, nested ones as sections. */
+export function splitFields(row) {
+    const entries = shownEntries(row);
+    return {
+        plain: entries.filter(([, value]) => isInline(value)),
+        sections: entries.filter(([, value]) => !isInline(value)).map(([key]) => section(row, key)),
+    };
+}

package/client/source-citations.d.ts

@@ -0,0 +1,13 @@
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+/** One source as a citation: its title, and when it's on the web, its link and favicon. */
+export type SourceCitation = {
+    key: string;
+    title: string;
+    href?: string;
+    icon?: string;
+};
+export type SourceCitationBlock = Extract<TranscriptBlock, {
+    kind: 'citation';
+}>;
+/** A citation's sources, in the order they were cited. */
+export declare function citationsFromBlock(block: SourceCitationBlock): SourceCitation[];

package/client/source-citations.js

@@ -0,0 +1,56 @@
+/**
+ * Gemini grounding links through this host rather than to the page, and names
+ * the page's own site in the source title instead.
+ */
+const GROUNDING_REDIRECT_HOST = 'vertexaisearch.cloud.google.com';
+/** A citation's sources, in the order they were cited. */
+export function citationsFromBlock(block) {
+    return block.sources.map((source, i) => citationFromSource(source, `c-${String(i)}`));
+}
+function citationFromSource(source, key) {
+    const url = webUrl(source.uri);
+    const site = url && siteOf(url, source.title);
+    return {
+        key,
+        title: source.title.trim() || hostLabel(source.uri) || source.type,
+        ...(url ? { href: url.href } : {}),
+        ...(site ? { icon: faviconUrl(site) } : {}),
+    };
+}
+/**
+ * A source is linked only at an http(s) URL. Sources come from the model and
+ * from tool output, so a `javascript:`, `data:`, or other scheme never becomes
+ * a clickable link.
+ */
+function webUrl(uri) {
+    if (!URL.canParse(uri))
+        return undefined;
+    const url = new URL(uri);
+    return url.protocol === 'https:' || url.protocol === 'http:' ? url : undefined;
+}
+/** The site a source is on: the link's host, or for a grounding redirect, the site its title names. */
+function siteOf(url, title) {
+    if (url.hostname !== GROUNDING_REDIRECT_HOST)
+        return url.hostname;
+    const named = title.trim().toLowerCase();
+    if (!named.includes('.') || !URL.canParse(`https://${named}`))
+        return undefined;
+    return new URL(`https://${named}`).hostname === named ? named : undefined;
+}
+/** Google's favicon service; the visitor's browser sends it the site's host, never the page. */
+function faviconUrl(site) {
+    return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(site)}&sz=32`;
+}
+function hostLabel(uri) {
+    try {
+        return new URL(uri).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return truncate(uri, 40);
+    }
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}

package/client/space-geometry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What the embedding space draws, as flat arrays a GPU takes as they are:
+ * the axes' three circles, each document's dot, a line for each link, heavier
+ * the further its cosine similarity passes the threshold, and a query's white
+ * dot with a line to each match that passes its own.
+ * Every other line joins two real points and stands for their cosine
+ * similarity; nothing is drawn for show.
+ *
+ * @module
+ */
+import type { EmbeddingSpace, SpacePoint } from './embedding-space.ts';
+/**
+ * Floats per line segment: from (3), to (3), colour (3), alpha, width in CSS
+ * pixels, the two slots it reads its state from, where it sits along its line
+ * (0 at the start, 1 at the end), and the gap in CSS pixels it leaves before
+ * its start and after its end, where a dot sits.
+ */
+export declare const SEGMENT_FLOATS = 16;
+/** Floats per dot: position (3), colour (3), alpha, radius in CSS pixels, its slot, and where it sits along the line that reaches it. */
+export declare const DOT_FLOATS = 10;
+/** Stands for the query where a slot would go. */
+export declare const QUERY_SLOT = -1;
+/** Stands for the axes' circles, which no document's state reaches. */
+export declare const FRAME_SLOT = -2;
+/** Line segments and dots, packed as {@link SEGMENT_FLOATS} and {@link DOT_FLOATS} describe. */
+export type SpaceGeometry = {
+    segments: Float32Array;
+    dots: Float32Array;
+};
+/** Everything a space draws before any query: the axes' circles, a line for each link, then every document's dot. */
+export declare function spaceGeometry(space: EmbeddingSpace): SpaceGeometry;
+/** A match the query is joined to. */
+export type QueryMatch = {
+    index: number;
+    /** How far its similarity passes the threshold it stood out against, from 0 at it to 1 at identical. */
+    closeness: number;
+};
+/** A query's white dot where it landed, and a line from it to each match, weighted as a link is. */
+export declare function queryGeometry(space: EmbeddingSpace, at: SpacePoint, matches: readonly QueryMatch[]): SpaceGeometry;

package/client/space-geometry.js

@@ -0,0 +1,183 @@
+/**
+ * What the embedding space draws, as flat arrays a GPU takes as they are:
+ * the axes' three circles, each document's dot, a line for each link, heavier
+ * the further its cosine similarity passes the threshold, and a query's white
+ * dot with a line to each match that passes its own.
+ * Every other line joins two real points and stands for their cosine
+ * similarity; nothing is drawn for show.
+ *
+ * @module
+ */
+/**
+ * Floats per line segment: from (3), to (3), colour (3), alpha, width in CSS
+ * pixels, the two slots it reads its state from, where it sits along its line
+ * (0 at the start, 1 at the end), and the gap in CSS pixels it leaves before
+ * its start and after its end, where a dot sits.
+ */
+export const SEGMENT_FLOATS = 16;
+/** Floats per dot: position (3), colour (3), alpha, radius in CSS pixels, its slot, and where it sits along the line that reaches it. */
+export const DOT_FLOATS = 10;
+/** Stands for the query where a slot would go. */
+export const QUERY_SLOT = -1;
+/** Stands for the axes' circles, which no document's state reaches. */
+export const FRAME_SLOT = -2;
+/** Every cluster's colour has this lightness and chroma, so none reads dirtier or louder than another. */
+const LIGHTNESS = 0.72;
+const CHROMA = 0.085;
+const QUERY_COLOUR = [0.97, 0.98, 1.0];
+/**
+ * Every line is a faint hairline in its documents' colour: it hints at a
+ * connection, and the dots carry the picture. Its width in CSS pixels and its
+ * opacity, at the threshold and at identical.
+ */
+const LINE_WIDTH = [0.3, 0.5];
+const LINE_ALPHA = [0.18, 0.4];
+function weighted([at, to], strength) {
+    return at + (to - at) * strength;
+}
+function gamma(linear) {
+    return linear <= 0.0031308 ? 12.92 * linear : 1.055 * linear ** (1 / 2.4) - 0.055;
+}
+/** An OKLCH colour as sRGB from 0 to 1, or `null` when the screen cannot show it. */
+function oklch(l, c, hue) {
+    const a = c * Math.cos(hue);
+    const b = c * Math.sin(hue);
+    const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    const rgb = [
+        4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+        -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+        -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_,
+    ];
+    if (rgb.some((v) => v < -1e-4 || v > 1 + 1e-4))
+        return null;
+    return rgb.map((v) => gamma(Math.min(1, Math.max(0, v))));
+}
+/** A cluster's colour from its tone, a hue from 0 to 1, at the palette's one lightness; chroma gives way only where the screen runs out. */
+function colourOf(tone) {
+    const hue = tone * 2 * Math.PI;
+    for (let c = CHROMA; c > 0; c -= 0.005) {
+        const colour = oklch(LIGHTNESS, c, hue);
+        if (colour)
+            return colour;
+    }
+    return oklch(LIGHTNESS, 0, hue) ?? [0.8, 0.8, 0.8];
+}
+function mixed(a, b, u) {
+    return [a[0] + (b[0] - a[0]) * u, a[1] + (b[1] - a[1]) * u, a[2] + (b[2] - a[2]) * u];
+}
+/** The longest piece a line is cut into, so depth fades along it, not only at its ends. */
+const PIECE = 0.1;
+/** Points along the straight line from one point to another, through the ball. */
+function pieces(a, b) {
+    const steps = Math.max(1, Math.ceil(Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]) / PIECE));
+    return Array.from({ length: steps + 1 }, (_, s) => mixed(a, b, s / steps));
+}
+class Strokes {
+    segments = [];
+    dots = [];
+    line({ from, to, colour, alpha, width, slots, gaps }) {
+        const points = pieces(from, to);
+        const last = points.length - 1;
+        for (let i = 1; i <= last; i += 1) {
+            const u = i / last;
+            this.segments.push(...points[i - 1], ...points[i], ...colour((i - 0.5) / last), alpha, width, slots[0], slots[1], u, i === 1 ? gaps[0] : 0, i === last ? gaps[1] : 0);
+        }
+    }
+    /** One segment no document's state reaches, always shown, with no gaps. */
+    segment(from, to, colour, alpha, width) {
+        this.segments.push(...from, ...to, ...colour, alpha, width, FRAME_SLOT, FRAME_SLOT, 0, 0, 0);
+    }
+    dot({ at, colour, alpha, radius, slot, along }) {
+        this.dots.push(...at, ...colour, alpha, radius, slot, along);
+    }
+    done() {
+        return { segments: new Float32Array(this.segments), dots: new Float32Array(this.dots) };
+    }
+}
+/** A document's dot, and the query's, a little larger, in CSS pixels. */
+const DOCUMENT_RADIUS = 2.6;
+const QUERY_RADIUS = 3.6;
+/** The clear space between a line's end and the dot it reaches. */
+const GAP = 1.75;
+/** How far a link passes the threshold, from 0 at it to 1 at identical. */
+function strengthOf(space, similarity) {
+    if (space.threshold >= 1)
+        return 1;
+    return Math.min(Math.max((similarity - space.threshold) / (1 - space.threshold), 0), 1);
+}
+/** The axes' circles: a hairline round the rim in each plane two of the three axes span. */
+const FRAME_COLOUR = [0.88, 0.9, 0.94];
+/** At the ball's front; the renderer fades a circle with the square of its depth, toward a quarter of this at the back. */
+const FRAME_ALPHA = 0.29;
+const FRAME_WIDTH = 0.7;
+const FRAME_STEPS = 96;
+function frame(strokes) {
+    const planes = [
+        (a) => [Math.cos(a), Math.sin(a), 0],
+        (a) => [Math.cos(a), 0, Math.sin(a)],
+        (a) => [0, Math.cos(a), Math.sin(a)],
+    ];
+    for (const at of planes)
+        for (let i = 0; i < FRAME_STEPS; i += 1)
+            strokes.segment(at((i / FRAME_STEPS) * 2 * Math.PI), at(((i + 1) / FRAME_STEPS) * 2 * Math.PI), FRAME_COLOUR, FRAME_ALPHA, FRAME_WIDTH);
+}
+/** Everything a space draws before any query: the axes' circles, a line for each link, then every document's dot. */
+export function spaceGeometry(space) {
+    const strokes = new Strokes();
+    frame(strokes);
+    const colourOfDocument = (index) => colourOf(space.clusters[space.documents[index].cluster].tone);
+    for (const link of space.links) {
+        const strength = strengthOf(space, link.similarity);
+        // invariant: a link's two documents are in one cluster, so it takes their colour.
+        const colour = colourOfDocument(link.a);
+        strokes.line({
+            from: space.documents[link.a].position,
+            to: space.documents[link.b].position,
+            colour: () => colour,
+            alpha: weighted(LINE_ALPHA, strength),
+            width: weighted(LINE_WIDTH, strength),
+            slots: [link.a, link.b],
+            gaps: [DOCUMENT_RADIUS + GAP, DOCUMENT_RADIUS + GAP],
+        });
+    }
+    for (const document of space.documents)
+        strokes.dot({
+            at: document.position,
+            colour: colourOfDocument(document.index),
+            alpha: 1,
+            radius: DOCUMENT_RADIUS,
+            slot: document.index,
+            along: 0,
+        });
+    return strokes.done();
+}
+/** A query's white dot where it landed, and a line from it to each match, weighted as a link is. */
+export function queryGeometry(space, at, matches) {
+    const strokes = new Strokes();
+    for (const match of matches) {
+        const document = space.documents[match.index];
+        if (!document)
+            continue;
+        const colour = colourOf(space.clusters[document.cluster].tone);
+        strokes.line({
+            from: at,
+            to: document.position,
+            colour: (u) => mixed(QUERY_COLOUR, colour, u),
+            alpha: weighted(LINE_ALPHA, match.closeness),
+            width: weighted(LINE_WIDTH, match.closeness),
+            slots: [QUERY_SLOT, match.index],
+            gaps: [QUERY_RADIUS + GAP, DOCUMENT_RADIUS + GAP],
+        });
+    }
+    strokes.dot({
+        at,
+        colour: QUERY_COLOUR,
+        alpha: 1,
+        radius: QUERY_RADIUS,
+        slot: QUERY_SLOT,
+        along: 0,
+    });
+    return strokes.done();
+}

package/client/state-fields.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The rules behind editing a decision's state as fields: which lists read as
+ * words, and what a new row in a list starts as.
+ *
+ * @module
+ */
+import type { DecisionJson } from '@theoremjs/agents';
+/** A list edited as tokens: empty, or every entry a string. */
+export declare function isWordList(value: DecisionJson[]): value is string[];
+/** A new row shaped like `like`: its fields kept, its values emptied. */
+export declare function blankLike(like: DecisionJson | undefined): DecisionJson;
+/** Columns a list of rows edits as a table in, or `null` when its rows are not all small, flat, and alike. */
+export declare function tableColumns(value: DecisionJson[]): {
+    key: string;
+    weight: number;
+}[] | null;