@loomcli/core 0.6.0 → 0.8.0

package/dist/plain.js

@@ -1,12 +1,238 @@
+/**
+ * The verdict the declaring call under way reached on each part of a declaration it captured, so
+ * every later rule of that call reads that one verdict and never asks the part's prototype again.
+ * No call is under way outside `declaring`, so a run and every later call judge afresh.
+ */
+let verdicts = undefined;
+/**
+ * Runs one declaring call with verdicts of its own, dropped when it returns or throws. A call made
+ * inside another, such as a `plugin()` a getter makes, is part of the outer read and shares them.
+ */
+function declaring(call) {
+    if (verdicts !== undefined) {
+        return call();
+    }
+    verdicts = new WeakMap();
+    try {
+        return call();
+    }
+    finally {
+        verdicts = undefined;
+    }
+}
 /**
  * A structural value core reads as plain data: an object literal, and never a declaration that
  * carries state of its own. The options slots read it to reject a value that is not an options
- * object, and inspection reads it to copy a declared value faithfully.
+ * object, and `snapshot` reads it to copy a declared value faithfully. A value a declaring call
+ * already judged answers with that verdict.
  */
-export function isPlainObject(value) {
+function isPlainObject(value) {
     if (value === null || typeof value !== 'object') {
         return false;
     }
+    return verdicts?.get(value) ?? hasPlainPrototype(value);
+}
+/** Whether one object's prototype, read once, is `Object.prototype` or `null`. */
+function hasPlainPrototype(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
+/**
+ * Whether a declaring call reads one part of a declaration as plain data, decided once: the first
+ * verdict is recorded, and `isPlainObject` answers with it for the same value from then on.
+ */
+function decidePlain(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const known = verdicts?.get(value);
+    if (known !== undefined) {
+        return known;
+    }
+    const verdict = hasPlainPrototype(value);
+    verdicts?.set(value, verdict);
+    return verdict;
+}
+/**
+ * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
+ * consumer cannot reach the source through the copy. A value that holds itself is copied with the
+ * same cycle, because each source object is judged and copied once and every path to it reaches
+ * that copy. Primitives and library objects, such as a class instance or a `Date` a schema
+ * produced, are reported as they are, because core cannot copy them meaningfully. Build reads it
+ * for a converter's schema, and the chain for the request one middleware holds.
+ */
+function snapshot(value) {
+    return copied(value, copying(Number.POSITIVE_INFINITY), 1);
+}
+/** The snapshot of one plain object, under the record type the caller already established. */
+function snapshotRecord(value) {
+    return copiedRecord(value, copying(Number.POSITIVE_INFINITY), 1);
+}
+/**
+ * The snapshot `snapshot` takes, of a value whose paths may hold at most `levels` arrays and plain
+ * objects, the value itself included. Every path through a container the value holds twice counts
+ * it, and a value that holds itself has a path without end. Either kind of path past `levels`
+ * throws `NestedTooDeepError` before the walk goes deeper than `levels`, so neither the walk nor
+ * any later reader of the copy goes deeper either. A declaring call reads it for a declared default.
+ */
+function boundedSnapshot(value, levels) {
+    return copied(value, copying(levels), 1);
+}
+/** What `boundedSnapshot` throws for a value with a path longer than its limit. */
+class NestedTooDeepError extends Error {
+    name = 'NestedTooDeepError';
+}
+/** A snapshot about to start, whose paths may hold at most `levels` containers. */
+function copying(levels) {
+    return { copies: new Map(), heights: new Map(), levels };
+}
+/**
+ * One value of a snapshot in progress, reached at `level`, where the value itself is level 1. An
+ * object the walk reached already answers as it did then, so its prototype is read once.
+ */
+function copied(value, walk, level) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    if (walk.copies.has(value)) {
+        return walk.copies.get(value);
+    }
+    if (Array.isArray(value)) {
+        return copiedList(value, walk, level);
+    }
+    if (isPlainObject(value)) {
+        return copiedRecord(value, walk, level);
+    }
+    return kept(value, walk);
+}
+/** An object core cannot copy, kept as it is, which every later reach answers with unread. */
+function kept(value, walk) {
+    walk.copies.set(value, value);
+    walk.heights.set(value, 0);
+    return value;
+}
+/**
+ * How many containers the longest path from one entry holds, once the walk has copied the entry of
+ * a container reached at `level`. A container the walk filled counts every container below it,
+ * even one it reached first by a shorter path. A container still being filled is one this entry
+ * leads back into, so the path through it has no end, and any other value holds none.
+ */
+function checkedHeight(entry, walk, level) {
+    const height = typeof entry === 'object' && entry !== null
+        ? (walk.heights.get(entry) ?? Number.POSITIVE_INFINITY)
+        : 0;
+    if (level + height > walk.levels) {
+        throw new NestedTooDeepError();
+    }
+    return height;
+}
+/**
+ * The copier of each entry of one container reached at `level`, which counts how many containers
+ * the longest path from that container holds, itself included.
+ */
+function entryCopier(walk, level) {
+    let height = 1;
+    return {
+        copy: (entry) => {
+            const copy = copied(entry, walk, level + 1);
+            height = Math.max(height, checkedHeight(entry, walk, level) + 1);
+            return copy;
+        },
+        height: () => height,
+    };
+}
+/** Throws `NestedTooDeepError` for a container the walk first reaches past its limit. */
+function checkLevel(walk, level) {
+    if (level > walk.levels) {
+        throw new NestedTooDeepError();
+    }
+}
+/**
+ * One array's copy. It joins `copies` before its entries are read, so an entry that leads back to
+ * it reaches the copy, and it is frozen once it is filled. A hole stays a hole.
+ */
+function copiedList(list, walk, level) {
+    checkLevel(walk, level);
+    const copy = [];
+    walk.copies.set(list, copy);
+    const entries = entryCopier(walk, level);
+    fillList(copy, list, entries.copy);
+    walk.heights.set(list, entries.height());
+    return Object.freeze(copy);
+}
+/**
+ * One plain object's copy on `Object.prototype`, filled and frozen as an array's copy is. Each key
+ * is defined as an own data property, so a key of `__proto__` is stored under that name.
+ */
+function copiedRecord(record, walk, level) {
+    checkLevel(walk, level);
+    const copy = {};
+    walk.copies.set(record, copy);
+    const entries = entryCopier(walk, level);
+    for (const [key, entry] of Object.entries(record)) {
+        defineEntry(copy, key, entries.copy(entry));
+    }
+    walk.heights.set(record, entries.height());
+    return Object.freeze(copy);
+}
+/** Defines one key as an own data property, so a key of `__proto__` is stored under that name. */
+function defineEntry(target, key, value) {
+    Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true,
+    });
+}
+/**
+ * A copy of every own string key of one object, enumerable or not, each described once and read
+ * once, in the order the object lists its keys. `entering` hears each key before it is read, so a
+ * read that throws can name it. A symbol key is not copied, because no declaration declares one.
+ */
+function copyOwnKeys(declared, entering = () => undefined) {
+    const copy = {};
+    for (const key of Reflect.ownKeys(declared)) {
+        if (typeof key === 'string') {
+            entering(key);
+            if (Reflect.getOwnPropertyDescriptor(declared, key) !== undefined) {
+                defineEntry(copy, key, Reflect.get(declared, key));
+            }
+        }
+    }
+    return copy;
+}
+/**
+ * The copy of one part of a declaration that `decidePlain` judges plain, by `copyOwnKeys`. Any other
+ * value is answered as it is, so the rule for its slot reports it.
+ */
+function shallowRecord(value) {
+    return decidePlain(value) ? copyOwnKeys(value) : value;
+}
+/**
+ * Fills `copy` with what `convert` makes of each entry of `list`, read by its length once and then
+ * index by index, so none of the list's own methods runs. A hole stays a hole.
+ */
+function fillList(copy, list, convert) {
+    const { length } = list;
+    for (let index = 0; index < length; index += 1) {
+        if (Object.hasOwn(list, index)) {
+            defineEntry(copy, index, convert(list[index]));
+        }
+    }
+    copy.length = length;
+}
+/** A copy of one list's entries by `fillList`. Each entry is what its factory built, so it is kept. */
+function copyList(list) {
+    const copy = [];
+    fillList(copy, list, (entry) => entry);
+    return copy;
+}
+/** The copy of a value that is a list, by `copyList`. Any other value is answered as it is. */
+function shallowList(value) {
+    if (!Array.isArray(value)) {
+        return value;
+    }
+    const list = value;
+    return copyList(list);
+}
+export { boundedSnapshot, copyList, copyOwnKeys, decidePlain, declaring, isPlainObject, NestedTooDeepError, shallowList, shallowRecord, snapshot, snapshotRecord, };

package/dist/plugin-rules.d.ts

@@ -5,6 +5,12 @@ declare const notAList: import("./diagnostic-text.js").DiagnosticRule;
  * that is not an object.
  */
 declare const notAnObject: import("./diagnostic-text.js").DiagnosticRule;
+/**
+ * A declaration whose read throws while core takes its one copy, such as a getter that throws or a
+ * proxy whose trap throws: the config of an argument or option, a plugin's definition and each of
+ * its option declarations, and the options of a Command or of the Application.
+ */
+declare const unreadableDeclaration: import("./diagnostic-text.js").DiagnosticRule;
 /** A list entry that its factory did not build, such as a hand-made plugin or translation. */
 declare const foreignValue: import("./diagnostic-text.js").DiagnosticRule;
 /** One plugin identity installed twice. */
@@ -13,8 +19,6 @@ declare const pluginInstalledTwice: import("./diagnostic-text.js").DiagnosticRul
 declare const slotTaken: import("./diagnostic-text.js").DiagnosticRule;
 /** A plugin, extension, or view identity outside the identity grammar. */
 declare const invalidIdentity: import("./diagnostic-text.js").DiagnosticRule;
-/** A validator or a presence rule on a plugin option. */
-declare const pluginOptionRule: import("./diagnostic-text.js").DiagnosticRule;
 /** A middleware activation that is missing, empty, or names an option the plugin lacks. */
 declare const middlewareActivation: import("./diagnostic-text.js").DiagnosticRule;
 /** A loader, a hook, or a translator that core cannot call. */
@@ -25,7 +29,7 @@ declare const unknownSignal: import("./diagnostic-text.js").DiagnosticRule;
 declare const signalClaimedTwice: import("./diagnostic-text.js").DiagnosticRule;
 /** A configuration source binding that is not one of the plugin's option extensions. */
 declare const sourceBinding: import("./diagnostic-text.js").DiagnosticRule;
-/** A plugin option that carries its own plugin's source binding. */
+/** A plugin's option that carries its own plugin's source binding. */
 declare const sourceBoundOwnOption: import("./diagnostic-text.js").DiagnosticRule;
 /** Two distinct objects under one extension or declared-view identity. */
 declare const twoPackageCopies: import("./diagnostic-text.js").DiagnosticRule;
@@ -59,4 +63,4 @@ declare const renderingPolicyRule: import("./diagnostic-text.js").DiagnosticRule
 declare const themeMapping: import("./diagnostic-text.js").DiagnosticRule;
 /** A theme name that a built-in style member already holds. */
 declare const themeNameTaken: import("./diagnostic-text.js").DiagnosticRule;
-export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, };
+export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, unreadableDeclaration, };

package/dist/plugin-rules.js

@@ -6,7 +6,7 @@ import { registerRule } from './diagnostic-text.js';
  */
 /** A slot that holds a list, such as `plugins` or `commands`, holding a value of another kind. */
 const notAList = registerRule('@loomcli/core/not-a-list', {
-    explanation: 'Core reads plugins, commands, extensions, views, translators, and signals each as a list, in order. A value of any other kind has no entries to read.',
+    explanation: 'Core reads plugins, commands, extensions, views, translators, signals, and aliases each as a list, in order. A value of any other kind has no entries to read.',
     headline: 'Not a list',
 });
 /**
@@ -14,9 +14,18 @@ const notAList = registerRule('@loomcli/core/not-a-list', {
  * that is not an object.
  */
 const notAnObject = registerRule('@loomcli/core/not-an-object', {
-    explanation: "Core reads the options of a Command and of the Application, a plugin's definition, its options record, each of its option declarations, its middleware, its source, and the config of an argument or option by their keys. A value of any other kind has no keys to read.",
+    explanation: "Core reads the options of a Command and of the Application, a plugin's definition, its options record, each of its option declarations, its middleware, its source, the config of an argument or option, and the settings a plugin factory takes by their keys. A value of any other kind has no keys to read.",
     headline: 'Not an object',
 });
+/**
+ * A declaration whose read throws while core takes its one copy, such as a getter that throws or a
+ * proxy whose trap throws: the config of an argument or option, a plugin's definition and each of
+ * its option declarations, and the options of a Command or of the Application.
+ */
+const unreadableDeclaration = registerRule('@loomcli/core/unreadable-declaration', {
+    explanation: 'Core reads a declaration by its keys, and each list in it by index, once, at the call that declares it, and checks and records the copy it takes. A read that throws, such as a throwing getter or proxy trap, leaves core nothing to check or record.',
+    headline: 'Declaration could not be read',
+});
 /** A list entry that its factory did not build, such as a hand-made plugin or translation. */
 const foreignValue = registerRule('@loomcli/core/foreign-value', {
     explanation: 'Core reads a plugin, an extension, an extension value, a declared view, a view override, and a translation through facts its factory recorded when it built the value. Any other value carries none, even one of the same shape.',
@@ -37,11 +46,6 @@ const invalidIdentity = registerRule('@loomcli/core/invalid-identity', {
     explanation: 'An identity keys what a plugin, an extension, or a view contributes, names it in every diagnostic, and prefixes the identities of the rules its package declares, so it is a package name as npm spells one, scoped or not, then any subpath segments, each after a / and each of lowercase letters and digits in words joined by single hyphens.',
     headline: 'Invalid identity',
 });
-/** A validator or a presence rule on a plugin option. */
-const pluginOptionRule = registerRule('@loomcli/core/plugin-option-rule', {
-    explanation: "A plugin's middleware interprets its own options' values, so a plugin option declares how it parses and nothing more: no validator and no presence rule.",
-    headline: 'Rule on a plugin option',
-});
 /** A middleware activation that is missing, empty, or names an option the plugin lacks. */
 const middlewareActivation = registerRule('@loomcli/core/middleware-activation', {
     explanation: "Activation decides when core loads a plugin's middleware: on every run with 'always', or only when an invocation supplies one of the plugin's own options the list names, so a middleware no invocation needs costs it nothing.",
@@ -67,7 +71,7 @@ const sourceBinding = registerRule('@loomcli/core/source-binding', {
     explanation: 'A configuration source answers the options that carry its binding, an extension the plugin lists under extensions that applies to options. Core asks the source about those options without knowing what the binding means.',
     headline: 'Invalid source binding',
 });
-/** A plugin option that carries its own plugin's source binding. */
+/** A plugin's option that carries its own plugin's source binding. */
 const sourceBoundOwnOption = registerRule('@loomcli/core/source-bound-own-option', {
     explanation: "A plugin's own options resolve before its configuration source loads, because the source reads them, so none of them can take a value from that source.",
     headline: 'Source bound to its own option',
@@ -152,4 +156,4 @@ const themeNameTaken = registerRule('@loomcli/core/theme-name-taken', {
     explanation: 'Each theme name becomes a member of the style object beside the built-in members, so a name a built-in already holds would hide it.',
     headline: 'Theme name taken',
 });
-export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, };
+export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, unreadableDeclaration, };

package/dist/plugin-settings.d.ts

@@ -0,0 +1,18 @@
+/** The plugin factory whose settings `checkShortSetting` judges, and the option `short` spells. */
+interface ShortSettingDeclarer {
+    /** The plugin's identity, which the sentence and each finding's note name. */
+    readonly plugin: string;
+    /** The factory's name, the call each finding quotes, such as `'format'`. */
+    readonly call: string;
+    /** The name of the option the setting gives a short spelling, such as `'format'`. */
+    readonly option: string;
+}
+/**
+ * Judges a plugin factory's settings at its call, under core's own rules: settings that are neither
+ * undefined nor a plain object are the not-an-object fault, and a `short` that is not one ASCII
+ * letter is the short-alias fault every option's short spelling answers, in the same sentence. Each
+ * finding quotes the factory's call and names the plugin, so a first-party plugin that takes a short
+ * spelling as `{ short }` reports it where the author wrote it.
+ */
+export declare function checkShortSetting(settings: unknown, declarer: ShortSettingDeclarer): void;
+export {};

package/dist/plugin-settings.js

@@ -0,0 +1,38 @@
+import { DeclarationError, quoted } from './errors.js';
+import { declarerNote } from './facts.js';
+import { shortAlias } from './input-rules.js';
+import { shortAliasText, isShortAlias } from './options.js';
+import { isPlainObject } from './plain.js';
+import { notAnObject } from './plugin-rules.js';
+/**
+ * Judges a plugin factory's settings at its call, under core's own rules: settings that are neither
+ * undefined nor a plain object are the not-an-object fault, and a `short` that is not one ASCII
+ * letter is the short-alias fault every option's short spelling answers, in the same sentence. Each
+ * finding quotes the factory's call and names the plugin, so a first-party plugin that takes a short
+ * spelling as `{ short }` reports it where the author wrote it.
+ */
+export function checkShortSetting(settings, declarer) {
+    if (settings === undefined) {
+        return;
+    }
+    const { call, option, plugin } = declarer;
+    const finding = (mark) => ({
+        arguments: [settings],
+        call,
+        mark,
+        note: declarerNote(plugin),
+    });
+    if (!isPlainObject(settings)) {
+        throw new DeclarationError(notAnObject, {
+            correction: 'Supply a settings object, or omit the settings.',
+            findings: [finding('0')],
+            sentence: `Plugin ${quoted(plugin)} declares settings that are not an object.`,
+        });
+    }
+    if (settings.short !== undefined && !isShortAlias(settings.short)) {
+        throw new DeclarationError(shortAlias, {
+            ...shortAliasText(`Option ${quoted(option)}`),
+            findings: [finding('0.short')],
+        });
+    }
+}

package/dist/plugin.d.ts

@@ -9,18 +9,21 @@ import type { ProcessSignal } from './signals.js';
 import type { Palette } from './style-state.js';
 import type { ContextualStyle, ThemeConstraint, ThemeMapping } from './style.js';
 import type { Translation, TranslationContributor } from './translators.js';
-import type { CommandAttachHook, Host, OptionValue, Out, PluginOptionConfig } from './types.js';
+import type { CommandAttachHook, GlobalOptionConfig, Host, OptionValue, Out } from './types.js';
 import type { OptionInput } from './validation.js';
 import type { ViewContribution, ViewSubject } from './view.js';
 /**
- * The declaration record a plugin contributes its options under: the parsing part of an option
- * config, keyed by option name. A plugin option carries no schema and no presence rule, so the
- * config type publishes neither, and `plugin()` repeats the rule for a JavaScript author.
+ * The declaration record a plugin contributes its global options under, keyed by option name. Each
+ * entry takes the configuration `globalOption()` takes, so the config type publishes no presence
+ * rule, and `plugin()` repeats the rule for a JavaScript author.
+ */
+type PluginOptions = Readonly<Record<string, GlobalOptionConfig>>;
+/**
+ * The values one plugin's options take, read through the same `OptionValue` an action's options
+ * are, so a validated option reads as its validator's output.
  */
-type PluginOptions = Readonly<Record<string, PluginOptionConfig>>;
-/** The values one plugin's own options take, read through the same rules an action's options are. */
 type PluginOptionValues<Options extends PluginOptions> = {
-    readonly [Name in keyof Options]: OptionValue<Options[Name]>;
+    readonly [Name in keyof Options & string]: OptionValue<Options[Name]>;
 };
 /**
  * The spelling that supplied each of one plugin's own options given as a token, such as `-h`,
@@ -48,6 +51,16 @@ declare class PluginDeclaration<Options extends PluginOptions, Theme extends The
 type Plugin<Options extends PluginOptions = PluginOptions, Theme extends ThemeMapping = {}> = Pick<PluginDeclaration<Options, Theme>, typeof pluginOptions | typeof pluginTheme>;
 /** The declared options of a plugin, or of the factory that returns one. */
 type OptionsOf<Contributor> = Contributor extends Plugin<infer Options> ? Options : Contributor extends (...args: never[]) => Plugin<infer Options> ? Options : PluginOptions;
+/**
+ * The option values an installed plugin tuple contributes to every action's options, each plugin's
+ * read through `PluginOptionValues`. The Application computes it once from the constructor's
+ * `plugins`. A plugin typed as the wide `Plugin` states no option names, and a list widened to
+ * `Plugin[]` states no plugins, so neither names an option.
+ */
+type InstalledOptionValues<Plugins extends readonly Plugin[]> = Plugins extends readonly [
+    infer First extends Plugin,
+    ...infer Rest extends readonly Plugin[]
+] ? (string extends keyof OptionsOf<First> ? {} : PluginOptionValues<OptionsOf<First>>) & InstalledOptionValues<Rest> : {};
 /** A middleware reads its own plugin's options and either takes over or continues the chain. */
 type Middleware<Contributor extends Plugin | ((...args: never[]) => Plugin)> = (context: MiddlewareContext<OptionsOf<Contributor>>) => Promise<void> | void;
 /**
@@ -66,11 +79,12 @@ interface SourceContext<Options extends PluginOptions = PluginOptions> {
     readonly style: ContextualStyle;
 }
 /**
- * One answer: a value of the option's raw type, a string, a Boolean, or a list of strings for a
- * multiple option, and the one-line label core prints in a diagnostic about the value.
+ * One answer: a value of the option's raw type, a string, a Boolean, a whole number of 0 or more
+ * for a counted option, or a list of strings for a multiple option, and the one-line label core
+ * prints in a diagnostic about the value.
  */
 interface SourceAnswer {
-    readonly value: string | boolean | readonly string[];
+    readonly value: string | boolean | number | readonly string[];
     readonly label: string;
 }
 /**
@@ -114,8 +128,8 @@ interface PluginDefinition<Options extends PluginOptions = PluginOptions, Theme
  * One plugin: an identity and the contributions it carries. Creating and installing the value runs
  * none of its code: `onCommandAttach` runs at graph build, `onFailure` runs when `run()` renders a
  * failure, and the middleware runs inside an invocation, so an installed plugin an invocation never
- * reaches costs that invocation its hooks alone. Every rule
- * that one definition carries on its own throws here, before the value exists.
+ * reaches costs that invocation its hooks alone. The definition is read once, after the identity,
+ * and every rule that one definition carries on its own throws here, before the value exists.
  */
 declare function plugin<Options extends PluginOptions = {}, const Theme extends ThemeMapping = {}>(identity: string, definition: PluginDefinition<Options, Theme>): Plugin<NoInfer<Options>, NoInfer<Theme>>;
 /** How every plugin diagnostic names one plugin at the start of a sentence. */
@@ -130,9 +144,9 @@ interface InstalledPlugins {
 /**
  * The installed list in composition order, with every rule that reads two plugins together: an
  * identity installed twice, a second claim on the theme slot, the signals slot, or the
- * configuration source, and two distinct descriptors under one identity. The slot is read
- * defensively, because a JavaScript author reaches it with any value. Each plugin's own rules
- * already ran at its `plugin()` call.
+ * configuration source, and two distinct descriptors under one identity. The slot is the copy the
+ * Application's constructor took, which a JavaScript author fills with any value. Each plugin's own
+ * rules already ran at its `plugin()` call.
  */
 declare function installPlugins(application: string, plugins: unknown): InstalledPlugins;
 /**
@@ -164,7 +178,7 @@ interface BuiltPlugin {
     onCommandAttach: CommandAttachHook | undefined;
     /** The hook core calls for each failure `run()` renders after graph build, or nothing. */
     onFailure: FailureHook | undefined;
-    /** The plugin's own `views` slot, read once the validated theme is in place. */
+    /** The copy of the plugin's own `views` list, which the Application reads again. */
     views: unknown;
     /** The translations the plugin registers, which resolve after the application's. */
     translators: TranslationContributor;
@@ -182,17 +196,8 @@ interface BuiltPlugin {
 }
 /** The signals the one slot owner claimed, or none when no installed plugin claims the slot. */
 declare function ownedSignals(plugins: readonly BuiltPlugin[]): readonly ProcessSignal[];
-/** The value shape a plugin option takes, which is what `OptionValue` gives its declaration. */
-type PluginValues = Record<string, string | string[] | boolean | undefined>;
-/**
- * One plugin's own option values for one run: what argv or an input source supplied, or the
- * declared default, filled without validation. A collected value and an array default are copied,
- * so a plugin that writes to what it received changes neither the declaration nor the next run.
- * Entries become own keys even for a name such as `__proto__`, which assignment would not.
- */
-declare function pluginValues(inputs: readonly OptionInput[], values: OptionValues): PluginValues;
 /** One plugin's own spellings for one run, frozen, so no plugin writes what another reads. */
 declare function pluginSpellings(inputs: readonly OptionInput[], values: OptionValues): Readonly<Record<string, string>>;
 type ThemeOf<Contributor> = [Contributor] extends [never] ? {} : Contributor extends Plugin<PluginOptions, infer Theme> ? Theme : {};
-export type { ThemeOf, BuiltPlugin, BuiltSource, PluginValues, SourceAnswer, SourceContext, SourceResolver, Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, };
-export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, pluginValues, };
+export type { ThemeOf, BuiltPlugin, BuiltSource, InstalledOptionValues, SourceAnswer, SourceContext, SourceResolver, Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, };
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, };