forgebook 0.3.3 → 0.4.1

package/dist/src/searchTypos.d.ts

@@ -0,0 +1,88 @@
+/**
+ * How the catalogue's searches read a word nothing holds as typed: as the nearest word of the catalogue's names, a
+ * letter or two away.
+ *
+ * @remarks
+ * `forgebook find`, `forgebook search`, the dev server's API and MCP read typos alike from here. The shell's search
+ * reads words as typed: what reading typos costs is more than its first search's budget leaves. Pure.
+ *
+ * @module
+ */
+import { type SearchAnswer, type Searchable, type SearchLimits } from "./search.ts";
+import { type SearchPlace } from "./searchMatch.ts";
+/** A word of a query read as another, because nothing holds it as typed and the other is a letter or two away. */
+export type SearchCorrection = {
+    /** The word as typed, lower case and without accents. */
+    readonly typed: string;
+    /** The word of the catalogue it was read as. */
+    readonly read: string;
+};
+/**
+ * How many letters a typed word may be away from the word meant: none under four letters, one up to seven, two from
+ * eight.
+ *
+ * @param word - a word, as `wordsOf` gives it.
+ */
+export declare const typosAllowed: (word: string) => number;
+/**
+ * How many letters two words are apart, a letter added, removed, changed, or two side by side swapped counting one
+ * each (the restricted Damerau-Levenshtein distance); none past a limit.
+ *
+ * @remarks
+ * Stops at the first row past the limit, so a word far from the one asked costs a few steps, not its whole table.
+ *
+ * @param first - a word.
+ * @param second - another.
+ * @param limit - the most that counts.
+ * @returns the distance, or `undefined` past the limit.
+ */
+export declare const distanceWithin: (first: string, second: string, limit: number) => number | undefined;
+/**
+ * The words of a query that nothing holds, each read as the nearest word of the catalogue's names, when one is near
+ * enough (`typosAllowed`).
+ *
+ * @remarks
+ * Only a word that matches nothing anywhere is read as another, so a typo never changes what a word found already
+ * finds, and every result of an exact query stays. The nearest wins; between words as near, the one the catalogue
+ * uses most, then the first in alphabetical order, so the same query reads the same way twice. The synonyms' words
+ * count as the catalogue's where it holds a word of their group: `dialgo` reads `dialog`, which then finds a `Modal`.
+ *
+ * @param missing - the query's words that nothing holds.
+ * @param everything - the words of each thing that can be found, by where they are.
+ */
+export declare const correctionsOf: (missing: readonly string[], everything: readonly Partial<Record<SearchPlace, readonly string[]>>[]) => readonly SearchCorrection[];
+/**
+ * A query's words with its corrections applied, each word once.
+ *
+ * @param words - the query's words.
+ * @param corrections - what some of them are read as (`correctionsOf`).
+ */
+export declare const correctedWords: (words: readonly string[], corrections: readonly SearchCorrection[]) => string[];
+/** A query's words as a search reads them. */
+export type CorrectedQuery = {
+    /** The words nothing held as typed, and what each was read as; empty when the query is read as typed. */
+    readonly corrections: readonly SearchCorrection[];
+    /** The query's words, the corrections applied, each word once. */
+    readonly words: readonly string[];
+};
+/**
+ * A query's words with those nothing holds read as near names (`correctionsOf`).
+ *
+ * @param words - the query's words.
+ * @param held - those something holds as typed.
+ * @param everything - the words of each thing that can be found, by where they are.
+ */
+export declare const correctedQuery: (words: readonly string[], held: ReadonlySet<string>, everything: readonly Partial<Record<SearchPlace, readonly string[]>>[]) => CorrectedQuery;
+/** What a query finds, with the words read as others. */
+export type CorrectedAnswer = SearchAnswer & {
+    /** The words nothing held as typed, and what each was read as; empty when the query was read as typed. */
+    readonly corrections: readonly SearchCorrection[];
+};
+/**
+ * What a query finds (`searchCatalogue`), a word nothing holds as typed read as the nearest name (`correctedQuery`).
+ *
+ * @param all - everything that can be found (`searchables`).
+ * @param query - what was typed.
+ * @param limits - how much of the answer to give.
+ */
+export declare const correctedSearch: (all: readonly Searchable[], query: string, limits: SearchLimits) => CorrectedAnswer;

package/dist/src/searchTypos.js

@@ -0,0 +1,178 @@
+/**
+ * How the catalogue's searches read a word nothing holds as typed: as the nearest word of the catalogue's names, a
+ * letter or two away.
+ *
+ * @remarks
+ * `forgebook find`, `forgebook search`, the dev server's API and MCP read typos alike from here. The shell's search
+ * reads words as typed: what reading typos costs is more than its first search's budget leaves. Pure.
+ *
+ * @module
+ */
+import { answerOf, queryOf, scoredAll } from "./search.js";
+import { SYNONYMS } from "./searchMatch.js";
+/** The places whose words a typo is read against: names, not prose, where a near word is seldom the one meant. */
+const CORRECTION_PLACES = ["name", "keyword", "prop", "heading", "title", "story"];
+/** The shortest word read as another: in a shorter one, a letter changed makes most often a different word. */
+const MIN_CORRECTED = 4;
+/** From this length a word may be two letters away from the one meant. */
+const TWO_TYPOS_FROM = 8;
+/**
+ * How many letters a typed word may be away from the word meant: none under four letters, one up to seven, two from
+ * eight.
+ *
+ * @param word - a word, as `wordsOf` gives it.
+ */
+export const typosAllowed = (word) => {
+    if (word.length < MIN_CORRECTED)
+        return 0;
+    return word.length < TWO_TYPOS_FROM ? 1 : 2;
+};
+/**
+ * How many letters two words are apart, a letter added, removed, changed, or two side by side swapped counting one
+ * each (the restricted Damerau-Levenshtein distance); none past a limit.
+ *
+ * @remarks
+ * Stops at the first row past the limit, so a word far from the one asked costs a few steps, not its whole table.
+ *
+ * @param first - a word.
+ * @param second - another.
+ * @param limit - the most that counts.
+ * @returns the distance, or `undefined` past the limit.
+ */
+export const distanceWithin = (first, second, limit) => {
+    if (Math.abs(first.length - second.length) > limit)
+        return undefined;
+    let before = [];
+    let previous = Array.from({ length: second.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= first.length; row += 1) {
+        const current = distanceRow(first, second, row, { previous, before });
+        if (Math.min(...current) > limit)
+            return undefined;
+        before = previous;
+        previous = current;
+    }
+    const distance = previous[second.length] ?? 0;
+    return distance <= limit ? distance : undefined;
+};
+/**
+ * One row of the distance's table: how far the first `row` letters of a word are from each start of another.
+ *
+ * @param first - the word the rows follow.
+ * @param second - the word the columns follow.
+ * @param row - how many letters of the first word.
+ * @param rows - the row before and the one before it, for a swap.
+ */
+const distanceRow = (first, second, row, rows) => {
+    const { previous, before } = rows;
+    const current = [row];
+    for (let column = 1; column <= second.length; column += 1) {
+        const cost = first[row - 1] === second[column - 1] ? 0 : 1;
+        const steps = [
+            (previous[column] ?? 0) + 1,
+            (current[column - 1] ?? 0) + 1,
+            (previous[column - 1] ?? 0) + cost
+        ];
+        const isSwap = row > 1 && column > 1 && first[row - 1] === second[column - 2] && first[row - 2] === second[column - 1];
+        if (isSwap)
+            steps.push((before[column - 2] ?? 0) + 1);
+        current.push(Math.min(...steps));
+    }
+    return current;
+};
+/**
+ * The words a typo can be read as, each with how often the catalogue's names use it.
+ *
+ * @param everything - the words of each thing that can be found, by where they are.
+ */
+const candidateWords = (everything) => {
+    const counts = new Map();
+    for (const parts of everything) {
+        for (const word of CORRECTION_PLACES.flatMap((place) => parts[place] ?? [])) {
+            counts.set(word, (counts.get(word) ?? 0) + 1);
+        }
+    }
+    // a synonym is a candidate only when the catalogue holds a word of its group: read otherwise, it would find nothing
+    for (const group of SYNONYMS.filter((each) => each.some((word) => counts.has(word)))) {
+        for (const word of group)
+            if (!counts.has(word))
+                counts.set(word, 0);
+    }
+    return counts;
+};
+/** Whether a candidate is a better reading than the best so far: nearer, then used more, then first in order. */
+const isBetter = (candidate, best) => best === undefined ||
+    candidate.distance < best.distance ||
+    (candidate.distance === best.distance &&
+        (candidate.count > best.count || (candidate.count === best.count && candidate.word < best.word)));
+/** The candidate a typed word is read as; none when none is near enough. */
+const nearestWord = (typed, counts) => {
+    let best;
+    for (const [word, count] of counts) {
+        const distance = distanceWithin(typed, word, typosAllowed(typed));
+        if (distance === undefined || distance === 0)
+            continue;
+        const candidate = { word, distance, count };
+        if (isBetter(candidate, best))
+            best = candidate;
+    }
+    return best?.word;
+};
+/**
+ * The words of a query that nothing holds, each read as the nearest word of the catalogue's names, when one is near
+ * enough (`typosAllowed`).
+ *
+ * @remarks
+ * Only a word that matches nothing anywhere is read as another, so a typo never changes what a word found already
+ * finds, and every result of an exact query stays. The nearest wins; between words as near, the one the catalogue
+ * uses most, then the first in alphabetical order, so the same query reads the same way twice. The synonyms' words
+ * count as the catalogue's where it holds a word of their group: `dialgo` reads `dialog`, which then finds a `Modal`.
+ *
+ * @param missing - the query's words that nothing holds.
+ * @param everything - the words of each thing that can be found, by where they are.
+ */
+export const correctionsOf = (missing, everything) => {
+    const asked = missing.filter((word) => typosAllowed(word) > 0);
+    if (asked.length === 0)
+        return [];
+    const counts = candidateWords(everything);
+    return asked.flatMap((typed) => {
+        const read = nearestWord(typed, counts);
+        return read === undefined ? [] : [{ typed, read }];
+    });
+};
+/**
+ * A query's words with its corrections applied, each word once.
+ *
+ * @param words - the query's words.
+ * @param corrections - what some of them are read as (`correctionsOf`).
+ */
+export const correctedWords = (words, corrections) => [
+    ...new Set(words.map((word) => corrections.find((each) => each.typed === word)?.read ?? word))
+];
+/**
+ * A query's words with those nothing holds read as near names (`correctionsOf`).
+ *
+ * @param words - the query's words.
+ * @param held - those something holds as typed.
+ * @param everything - the words of each thing that can be found, by where they are.
+ */
+export const correctedQuery = (words, held, everything) => {
+    const corrections = correctionsOf(words.filter((word) => !held.has(word)), everything);
+    return { corrections, words: correctedWords(words, corrections) };
+};
+/**
+ * What a query finds (`searchCatalogue`), a word nothing holds as typed read as the nearest name (`correctedQuery`).
+ *
+ * @param all - everything that can be found (`searchables`).
+ * @param query - what was typed.
+ * @param limits - how much of the answer to give.
+ */
+export const correctedSearch = (all, query, limits) => {
+    const typed = queryOf(query);
+    const strict = scoredAll(all, typed);
+    const { corrections, words } = correctedQuery(typed.words, new Set(strict.flatMap((each) => each.matched)), all.map((each) => each.parts));
+    if (corrections.length === 0)
+        return { ...answerOf(strict, typed, limits), corrections };
+    const read = { ...typed, words };
+    return { ...answerOf(scoredAll(all, read), read, limits), corrections };
+};

package/dist/src/shapeValues.d.ts

@@ -0,0 +1,86 @@
+/**
+ * What reads a value against its shape (`valueShape.ts`): whether it fits, what the panel starts from, what a story's own
+ * arg looks like, and the worst case of each kind. Loaded with the first prop that has a shape, so a catalogue of plain
+ * props never pays for it; the commands import it directly.
+ *
+ * @remarks
+ * A link's author chooses the values, and a component may spread an object onto an element. What a type declares is
+ * checked by name; what no type describes (`json`, `record`) is checked for what an element would run: an attribute that
+ * runs a script or writes markup, Vue's marks for a property or a modifier (`.innerHTML`, `^onclick`), an address that
+ * runs when opened, and a named value, which only a type offers. Pure.
+ *
+ * @module
+ */
+import { type ArgValue } from "./messages.ts";
+import { type NamedValues } from "./namedValues.ts";
+import type { ValueShape } from "./valueShape.ts";
+/**
+ * The names a free-form part of a value may not hold (`json`, `record`): an attribute that runs a script or writes
+ * markup when a component spreads the object onto an element. A link's author chooses these names, and no type says
+ * which are meant; an `on` word that is no event stays allowed.
+ *
+ * @param name - the name.
+ */
+export declare const isUnsafeFreeName: (name: string) => boolean;
+/**
+ * Whether a free-form value holds anything it may not hold, at any depth.
+ *
+ * @param value - the value.
+ * @param allowsNamed - whether a named value may be in it: a schema's author has said what it takes, and the name is looked
+ *   up among the source's own values; `false` by default, where nothing has said.
+ */
+export declare const holdsUnsafePart: (value: ArgValue, allowsNamed?: boolean) => boolean;
+/**
+ * Whether a value fits a shape: what the panel could have set. Names an object's type does not declare are refused, as
+ * a prop the story does not declare is: a link must not reach an element's attributes through them.
+ *
+ * @param shape - the shape.
+ * @param value - the value.
+ * @param namedValues - the source's named values.
+ */
+export declare const isValueOfShape: (shape: ValueShape, value: ArgValue, namedValues: NamedValues) => boolean;
+/**
+ * The value a shape starts from when the panel first gives it one: what a required part must hold, so a value the
+ * panel sends always fits its type.
+ *
+ * @param shape - the shape.
+ * @param namedValues - the source's named values.
+ * @returns the value; none when the source names none for a part that needs one.
+ */
+export declare const startValueOf: (shape: ValueShape, namedValues: NamedValues) => ArgValue | undefined;
+/**
+ * The shape a story's own arg shows, for an arg no type describes: fields from its names, a list's items from its
+ * items when they all look alike, JSON for the rest.
+ *
+ * @param value - the arg's value.
+ */
+export declare const shapeOfValue: (value: ArgValue) => ValueShape;
+/**
+ * A shape with what a story's own arg looks like read from it.
+ *
+ * @param shape - the shape.
+ */
+export declare const resolvedShape: (shape: ValueShape) => ValueShape;
+/** The longest text a `file` control keeps: a link holds the file, and a server refuses a longer address. */
+export declare const MOST_FILE_TEXT = 8000;
+/**
+ * Whether a text is what a `file` control sets: a small file as a `data:` address, of a type it keeps.
+ *
+ * @param value - the text.
+ */
+export declare const isFileText: (value: ArgValue) => boolean;
+/**
+ * Whether a value is what a `file` control sets.
+ *
+ * @param value - the value.
+ */
+export declare const isFileList: (value: ArgValue) => boolean;
+/**
+ * A shape's worst value: an object's fields at their worst, a list of many items, a mixed union's first member that has a
+ * worst case.
+ *
+ * @param shape - the shape.
+ * @param namedValues - the source's named values, for a required part only they can fill.
+ * @returns the value; none when a long text or a huge number has no place in it, or when the address could not hold it.
+ */
+export declare const worstOfShape: (shape: ValueShape, namedValues: NamedValues) => ArgValue | undefined;

package/dist/src/shapeValues.js

@@ -0,0 +1,295 @@
+/**
+ * What reads a value against its shape (`valueShape.ts`): whether it fits, what the panel starts from, what a story's own
+ * arg looks like, and the worst case of each kind. Loaded with the first prop that has a shape, so a catalogue of plain
+ * props never pays for it; the commands import it directly.
+ *
+ * @remarks
+ * A link's author chooses the values, and a component may spread an object onto an element. What a type declares is
+ * checked by name; what no type describes (`json`, `record`) is checked for what an element would run: an attribute that
+ * runs a script or writes markup, Vue's marks for a property or a modifier (`.innerHTML`, `^onclick`), an address that
+ * runs when opened, and a named value, which only a type offers. Pure.
+ *
+ * @module
+ */
+import { isArgList, isArgObject, isArgValue, isDateArg, isNamedArg } from "./messages.js";
+import { namedValueOf } from "./namedValues.js";
+import { WORST_ARG_TEXT, WORST_NUMBER } from "./worstCase.js";
+/**
+ * The names a free-form part of a value may not hold (`json`, `record`): an attribute that runs a script or writes
+ * markup when a component spreads the object onto an element. A link's author chooses these names, and no type says
+ * which are meant; an `on` word that is no event stays allowed.
+ *
+ * @param name - the name.
+ */
+export const isUnsafeFreeName = (name) => /^(dangerouslySetInnerHTML|innerHTML|outerHTML|srcdoc)$/i.test(name) ||
+    /^[.^:@#]/.test(name) ||
+    name.includes(":") ||
+    (/^on/i.test(name) && !/^(once|one|only|online|onboarding|ongoing|onward)$/.test(name));
+/** Whether a text in a free-form value is an address a browser would run. */
+const isRunnableText = (text) => 
+// browsers skip control characters and white space inside a scheme, so a link's `java\tscript:` is the same address
+/^(javascript|vbscript|data:text\/html)/i.test([...text].filter((each) => each > " ").join(""));
+/**
+ * Whether a free-form value holds anything it may not hold, at any depth.
+ *
+ * @param value - the value.
+ * @param allowsNamed - whether a named value may be in it: a schema's author has said what it takes, and the name is looked
+ *   up among the source's own values; `false` by default, where nothing has said.
+ */
+export const holdsUnsafePart = (value, allowsNamed = false) => {
+    if (typeof value === "string")
+        return isRunnableText(value);
+    if (isNamedArg(value))
+        return !allowsNamed;
+    if (isArgList(value))
+        return value.some((each) => holdsUnsafePart(each, allowsNamed));
+    if (!isArgObject(value))
+        return false;
+    return Object.entries(value).some(([name, each]) => isUnsafeFreeName(name) || holdsUnsafePart(each, allowsNamed));
+};
+/** Whether a value fits a tuple's items. */
+const fitsTuple = (items, value, namedValues) => isArgList(value) &&
+    value.length === items.length &&
+    items.every((item, index) => {
+        const each = value[index];
+        return each !== undefined && isValueOfShape(item, each, namedValues);
+    });
+/** Whether a value fits an object's fields, and names no other. */
+const fitsObject = (fields, value, namedValues) => {
+    if (!isArgObject(value) || isNamedArg(value))
+        return false;
+    const isKnown = Object.keys(value).every((name) => fields.some((field) => field.name === name));
+    return (isKnown &&
+        fields.every((field) => {
+            const each = Object.hasOwn(value, field.name) ? value[field.name] : undefined;
+            if (each === undefined)
+                return !field.isRequired;
+            return (each === null && field.isNullable === true) || isValueOfShape(field.shape, each, namedValues);
+        }));
+};
+/** Whether a value fits a part only the source's named values fill, or a text where it takes one. */
+const fitsNamed = (shape, value, namedValues) => {
+    if (typeof value === "string")
+        return shape.canTakeText === true;
+    return (isNamedArg(value) &&
+        value.of === shape.type &&
+        namedValueOf(namedValues, value.of, value.named) !== undefined);
+};
+/**
+ * Whether a value fits a shape: what the panel could have set. Names an object's type does not declare are refused, as
+ * a prop the story does not declare is: a link must not reach an element's attributes through them.
+ *
+ * @param shape - the shape.
+ * @param value - the value.
+ * @param namedValues - the source's named values.
+ */
+export const isValueOfShape = (shape, value, namedValues) => {
+    switch (shape.kind) {
+        case "text":
+            return typeof value === "string";
+        case "date":
+            return isDateArg(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean" && (shape.only === undefined || shape.only === value);
+        case "choice":
+            return (typeof value === "string" || typeof value === "number") && shape.values.includes(value);
+        case "list":
+            return isArgList(value) && value.every((item) => isValueOfShape(shape.of, item, namedValues));
+        case "tuple":
+            return fitsTuple(shape.items, value, namedValues);
+        case "object":
+            return fitsObject(shape.fields, value, namedValues);
+        case "record":
+            return (isArgObject(value) &&
+                !isNamedArg(value) &&
+                Object.entries(value).every(([name, each]) => !isUnsafeFreeName(name) && isValueOfShape(shape.of, each, namedValues)));
+        case "union":
+            return shape.of.some((member) => isValueOfShape(member, value, namedValues));
+        case "named":
+            return fitsNamed(shape, value, namedValues);
+        case "json":
+            return isArgValue(value) && !holdsUnsafePart(value);
+        case "like":
+            return isValueOfShape(shapeOfValue(shape.value), value, namedValues);
+    }
+};
+/**
+ * The value a shape starts from when the panel first gives it one: what a required part must hold, so a value the
+ * panel sends always fits its type.
+ *
+ * @param shape - the shape.
+ * @param namedValues - the source's named values.
+ * @returns the value; none when the source names none for a part that needs one.
+ */
+export const startValueOf = (shape, namedValues) => {
+    switch (shape.kind) {
+        case "text":
+            return "";
+        case "date":
+            return { forgebookDate: new Date().toISOString() };
+        case "number":
+            return 0;
+        case "boolean":
+            return shape.only ?? false;
+        case "choice":
+            return shape.values[0];
+        case "list":
+            return [];
+        case "record":
+            return {};
+        case "json":
+            return null;
+        case "like":
+            return startValueOf(shapeOfValue(shape.value), namedValues);
+        case "tuple": {
+            const items = shape.items.map((item) => startValueOf(item, namedValues));
+            return items.every((item) => item !== undefined)
+                ? items.filter((item) => item !== undefined)
+                : undefined;
+        }
+        case "object": {
+            const fields = shape.fields
+                .filter((field) => field.isRequired)
+                .map((field) => [field.name, startValueOf(field.shape, namedValues)]);
+            return fields.every(([, each]) => each !== undefined)
+                ? Object.fromEntries(fields.flatMap(([name, each]) => (each === undefined ? [] : [[name, each]])))
+                : undefined;
+        }
+        case "union":
+            return shape.of.map((member) => startValueOf(member, namedValues)).find((start) => start !== undefined);
+        case "named": {
+            if (Object.hasOwn(namedValues, shape.type)) {
+                const [first] = Object.keys(namedValues[shape.type] ?? {});
+                if (first !== undefined)
+                    return { of: shape.type, named: first };
+            }
+            return shape.canTakeText === true ? "" : undefined;
+        }
+    }
+};
+/**
+ * The shape a story's own arg shows, for an arg no type describes: fields from its names, a list's items from its
+ * items when they all look alike, JSON for the rest.
+ *
+ * @param value - the arg's value.
+ */
+export const shapeOfValue = (value) => {
+    if (typeof value === "string")
+        return { kind: "text" };
+    if (typeof value === "number")
+        return { kind: "number" };
+    if (typeof value === "boolean")
+        return { kind: "boolean" };
+    if (isNamedArg(value))
+        return { kind: "named", type: value.of };
+    if (isDateArg(value))
+        return { kind: "date" };
+    if (isArgList(value)) {
+        const shapes = [...new Set(value.map((item) => JSON.stringify(shapeOfValue(item))))];
+        const [first] = value;
+        return {
+            kind: "list",
+            of: shapes.length === 1 && first !== undefined ? shapeOfValue(first) : { kind: "json" }
+        };
+    }
+    if (isArgObject(value)) {
+        return {
+            kind: "object",
+            fields: Object.entries(value).map(([name, each]) => ({
+                name,
+                shape: shapeOfValue(each),
+                isRequired: false
+            }))
+        };
+    }
+    return { kind: "json" };
+};
+/**
+ * A shape with what a story's own arg looks like read from it.
+ *
+ * @param shape - the shape.
+ */
+export const resolvedShape = (shape) => shape.kind === "like" ? shapeOfValue(shape.value) : shape;
+/** The longest text a `file` control keeps: a link holds the file, and a server refuses a longer address. */
+export const MOST_FILE_TEXT = 8000;
+/** What a `file` control keeps: pictures, sound and film, a plain text and a PDF, none of which a browser runs as a page. */
+const FILE_TYPES = /^data:((image\/(png|jpeg|gif|webp|avif|bmp|x-icon))|(audio\/[\w.+-]+)|(video\/[\w.+-]+)|text\/plain|application\/pdf)(;[\w=.+-]+)*,/i;
+/**
+ * Whether a text is what a `file` control sets: a small file as a `data:` address, of a type it keeps.
+ *
+ * @param value - the text.
+ */
+export const isFileText = (value) => typeof value === "string" && value.length <= MOST_FILE_TEXT && FILE_TYPES.test(value);
+/**
+ * Whether a value is what a `file` control sets.
+ *
+ * @param value - the value.
+ */
+export const isFileList = (value) => isArgList(value) && value.every(isFileText);
+/** How many items a list at the top takes in the worst case: more than a row or a page of a list lays out comfortably. */
+const WORST_ITEMS = 12;
+/** How many items a list inside another part takes: several levels of many would write an address no server takes. */
+const WORST_NESTED_ITEMS = 2;
+/** The longest worst value kept, as JSON: an address holds it, and a server refuses a longer one. */
+const MOST_WORST_TEXT = 3000;
+/** A tuple's worst value: each item's, or what it must hold; none when no item has a worst case. */
+const worstTuple = (shapes, namedValues, depth) => {
+    const items = shapes.map((item) => worstAt(item, namedValues, depth + 1) ?? startValueOf(item, namedValues));
+    const fitted = items.filter((item) => item !== undefined);
+    const hasWorst = shapes.some((item) => worstAt(item, namedValues, depth + 1) !== undefined);
+    return hasWorst && fitted.length === items.length ? fitted : undefined;
+};
+/** An object's worst value: each field's, or what a required one must hold; none when no field has a worst case. */
+const worstObject = (shapes, namedValues, depth) => {
+    const fields = shapes.flatMap((field) => {
+        const worst = worstAt(field.shape, namedValues, depth + 1);
+        if (worst !== undefined)
+            return [[field.name, worst, true]];
+        const start = field.isRequired ? startValueOf(field.shape, namedValues) : undefined;
+        return start === undefined ? [] : [[field.name, start, false]];
+    });
+    const isWhole = shapes.every((field) => !field.isRequired || fields.some(([name]) => name === field.name));
+    return isWhole && fields.some(([, , isWorst]) => isWorst)
+        ? Object.fromEntries(fields.map(([name, value]) => [name, value]))
+        : undefined;
+};
+/** A shape's worst value, however long. */
+const worstAt = (shape, namedValues, depth) => {
+    switch (shape.kind) {
+        case "text":
+            return WORST_ARG_TEXT;
+        case "number":
+            return WORST_NUMBER;
+        case "like":
+            return worstAt(shapeOfValue(shape.value), namedValues, depth);
+        case "list": {
+            const item = worstAt(shape.of, namedValues, depth + 1);
+            const length = depth === 0 ? WORST_ITEMS : WORST_NESTED_ITEMS;
+            return item === undefined ? undefined : Array.from({ length }, () => item);
+        }
+        case "tuple":
+            return worstTuple(shape.items, namedValues, depth);
+        case "object":
+            return worstObject(shape.fields, namedValues, depth);
+        case "union":
+            return shape.of
+                .map((member) => worstAt(member, namedValues, depth + 1))
+                .find((each) => each !== undefined);
+        default:
+            return undefined;
+    }
+};
+/**
+ * A shape's worst value: an object's fields at their worst, a list of many items, a mixed union's first member that has a
+ * worst case.
+ *
+ * @param shape - the shape.
+ * @param namedValues - the source's named values, for a required part only they can fill.
+ * @returns the value; none when a long text or a huge number has no place in it, or when the address could not hold it.
+ */
+export const worstOfShape = (shape, namedValues) => {
+    const worst = worstAt(shape, namedValues, 0);
+    return worst !== undefined && JSON.stringify(worst).length <= MOST_WORST_TEXT ? worst : undefined;
+};