@deadair/plugin-sdk 0.2.0

package/dist/plugin.api.version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.api.version.d.ts","sourceRoot":"","sources":["../src/plugin.api.version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC"}

package/dist/plugin.base.d.ts

@@ -0,0 +1,80 @@
+import type { PluginHost } from './plugin.host.js';
+import type { PluginLifecycle } from './plugin.lifecycle.js';
+/** Undoes one thing a plugin set up. Run in reverse order of registration when the plugin unloads. */
+export type PluginDisposer = () => void | Promise<void>;
+/**
+ * The base a plugin extends, so unloading is correct by construction.
+ *
+ * Two jobs, both of them chores every plugin was otherwise doing by hand:
+ *
+ * 1. **`this.host` is there or it throws with a sentence.** Each plugin used to
+ *    hold `host?: PluginHost` and write its own `hostOrThrow()`, or forget to
+ *    and get a `TypeError` about reading a property of undefined instead.
+ * 2. **Teardown is registered next to setup.** {@link Plugin.register} takes an
+ *    undo, and the base runs every one on unload, last registered first,
+ *    whether or not {@link Plugin.onUnload} throws.
+ *
+ * The second matters MORE in this host, not less. Plugins run inside the API process
+ * (`packages/plugin-sdk/CLAUDE.md` § "Trust and egress"), so a timer or a socket a plugin forgets
+ * is not confined to a sandbox that gets torn down: it lives in the server until somebody restarts
+ * it. Reloading a plugin on every config change is a normal thing an operator does, so "forgets on
+ * unload" compounds.
+ *
+ * ```ts
+ * class MyPlugin extends Plugin implements EnrichmentPluginInstance {
+ *     protected async onLoad(): Promise<void> {
+ *         const timer = setInterval(() => void this.refresh(), 60_000);
+ *         this.register(() => clearInterval(timer));
+ *     }
+ * }
+ * ```
+ *
+ * Extending this is optional: the host only ever asks for `PluginLifecycle`, so
+ * a plugin that implements `init` and `dispose` itself is as valid as it was.
+ */
+export declare abstract class Plugin implements PluginLifecycle {
+    private currentHost?;
+    private readonly disposers;
+    /**
+     * The host, once `init` has run.
+     *
+     * A getter rather than a field so the failure is a sentence naming the
+     * plugin instead of a `TypeError` from somewhere three calls deeper.
+     *
+     * @throws {PluginError} `internal` when read before `init` or after
+     *   `dispose`. Both are host bugs rather than operator ones, which is what
+     *   that code means.
+     */
+    protected get host(): PluginHost;
+    /**
+     * Registers something to undo when this plugin unloads.
+     *
+     * Call it next to the setup it undoes, which is the whole point: a
+     * `clearInterval` written beside its `setInterval` is one that cannot drift
+     * away from it as the file grows.
+     */
+    protected register(disposer: PluginDisposer): void;
+    /** {@link Plugin.register} for the common case. Works for `setTimeout` and `setInterval` alike. */
+    protected registerTimer(timer: ReturnType<typeof setTimeout>): void;
+    /** Your setup. Called once, after `this.host` is available and before any capability method. */
+    protected onLoad(): Promise<void>;
+    /**
+     * Anything left to undo that `register` could not express, such as dropping
+     * a cache. Runs after every registered disposer.
+     */
+    protected onUnload(): Promise<void>;
+    init(host: PluginHost): Promise<void>;
+    /**
+     * Undoes everything, in reverse.
+     *
+     * Every disposer runs even if an earlier one throws, because one broken
+     * undo must not strand the rest: the failure is logged and the walk
+     * continues. `onUnload` runs afterwards for the same reason it exists, and
+     * `this.host` is released last so both still have it.
+     *
+     * Idempotent. The host calls it on unload, on a config change and at
+     * shutdown, and those can overlap.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=plugin.base.d.ts.map

package/dist/plugin.base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.base.d.ts","sourceRoot":"","sources":["../src/plugin.base.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,sGAAsG;AACtG,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,MAAO,YAAW,eAAe;IACnD,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD;;;;;;;;;OASG;IACH,SAAS,KAAK,IAAI,IAAI,UAAU,CAK/B;IAED;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAIlD,mGAAmG;IACnG,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI;IAInE,gGAAgG;IAChG,SAAS,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;OAGG;IACH,SAAS,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C;;;;;;;;;;OAUG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBjC"}

package/dist/plugin.config.fields.d.ts

@@ -0,0 +1,524 @@
+import { z } from 'zod';
+/**
+ * The kinds of input a plugin can ask the operator for.
+ *
+ * - `string`      free text, one line
+ * - `text`        free text over several lines, for anything a person writes
+ *                 rather than pastes: a prompt, a persona, a list of phrasings.
+ *                 Stored exactly like a `string`, so nothing downstream has to
+ *                 know it exists; the difference is the box the operator types
+ *                 into, and a one-line box for a paragraph is the reason a
+ *                 setting like that ends up being edited by hand in psql
+ * - `url`         free text validated/normalised as a URL
+ * - `secret`      write-only: the host encrypts it, the settings UI never reads
+ *                 it back, and only `host.secrets.get()` sees the plaintext
+ * - `number`      numeric input
+ * - `boolean`     toggle
+ * - `select`      one of `options`
+ * - `multiselect` any number of `options`, stored as a JSON array of the chosen
+ *                 values. Read it back with {@link parseMultiSelect}
+ * - `list`        any number of ROWS with the same `columns`, stored as a JSON
+ *                 array of objects. Read it back with {@link parseRows}. For a
+ *                 list whose entries have parts — a feed with a name and a
+ *                 category — where the alternative is a `text` field with a
+ *                 separator in it and a line an operator can mistype into
+ *                 silence
+ * - `note`        not an input at all: static help text rendered in the form
+ */
+export type ConfigFieldType = 'string' | 'text' | 'url' | 'secret' | 'number' | 'boolean' | 'select' | 'multiselect' | 'list' | 'note';
+/**
+ * What a `number` field's value is measured in, so the form can offer a control a person can use.
+ *
+ * The VALUE is always stored in the unit named here — `bytes` means the row holds bytes — and the
+ * console converts on the way in and out. That is the whole point: a byte count is the right thing
+ * for code to compare against and a terrible thing to type, and the alternative to declaring it is
+ * either storing a friendlier unit (and doing the multiplication at every reader) or special-casing
+ * a particular setting key inside the form, which is the kind of thing nobody finds later.
+ *
+ * `fraction` is the second member and the one the first paragraph predicted: the row holds a share
+ * between 0 and 1, because that is what the code multiplying by it wants, and the console says
+ * `40%`, because that is what a person means. Honoured by a `slider`, which is the control every
+ * share in this station asks for; a fraction drawn as an ordinary spinner is still shown as the
+ * fraction it stores, since a number typed exactly is unambiguous either way.
+ *
+ * An enum rather than a boolean because the third member is obvious (a duration in milliseconds has
+ * exactly the same problem) and because a closed set is what the contract mirroring this can
+ * express.
+ */
+export type ConfigFieldUnit = 'bytes' | 'fraction';
+/**
+ * The control a field asks for, where the default one for its type is not the readable one.
+ *
+ * {@link ConfigFieldUnit}'s sibling, and the same bargain: what is STORED does not change, only the
+ * thing the operator touches. A `slider` over a share between 0 and 1 stores a fraction, and every
+ * reader still reads a fraction.
+ *
+ * Opt-in per field rather than inferred from `min` and `max` being present, which is the whole
+ * point. A slider is right for a value somebody feels for (a percentage, a trim in decibels, one
+ * pad every N breaks) and wrong for one they have to hit exactly: 3500 out of 0 to 600000 is a
+ * pixel, and a pause in milliseconds is a number an operator types rather than aims at. Declaring
+ * it makes that a judgement per setting instead of a rule that is right eight times and wrong six.
+ *
+ * A `slider` must declare both `min` and `max`, since a range with no ends is not one a track can
+ * be drawn for. A field asking for one without them falls back to the ordinary input rather than
+ * failing: this is a hint about drawing, and a form that renders nothing is worse than a form that
+ * renders a spinner.
+ *
+ * `tags` is for a `string` that is really a SET, stored as one comma-separated line because that is
+ * what the reader behind it splits. It changes nothing about the value: the form splits on the way
+ * in and joins on the way out, so `dialogueKinds()` keeps parsing exactly the string it always did.
+ * What it buys is that a set of names is added to and removed from one at a time, rather than by
+ * editing punctuation in a sentence — a stray comma in a one-line box is a kind the station simply
+ * does not have, and nothing says so. The cost is that a value CONTAINING a comma cannot be one
+ * tag, which is why this is asked for per field rather than being what a `string` does.
+ */
+export type ConfigFieldControl = 'slider' | 'tags';
+/** One choice in a `select`, a `multiselect`, or a suggestion list. */
+export interface ConfigFieldOption {
+    value: string;
+    label: string;
+}
+/**
+ * Where a field's or a column's choices come from when neither the plugin nor the operator's own
+ * server is the one that knows them.
+ *
+ * A closed HOST vocabulary, and the third of three ways a choice can be offered: `options` is what
+ * the PLUGIN decided when its manifest was written, `suggestConfigOptions()` is what the operator's
+ * own server currently says, and this is what the STATION says. It exists because a plugin cannot
+ * ask — a news plugin has no way to learn which categories this station holds, and the alternative
+ * is a free-text cell where `sports` and `sport` are a silent miss nobody sees until bulletins start
+ * declining.
+ *
+ * `intl.timeZones` is the second member and stretches the name slightly: it is the PLATFORM's list
+ * rather than the station's, out of `Intl.supportedValuesOf('timeZone')`. It belongs here anyway,
+ * because the property is about who can answer rather than about where the answer is kept, and the
+ * console is again the only side that can — a zone name has to be one the browser and the server
+ * both know, and a server that enumerated its own would be answering for a different machine.
+ *
+ * `station.newsFeeds` answers the feeds the installed plugins currently offer, by their qualified id
+ * and the operator's own name for each. It is the one source whose value is minted by a PLUGIN and
+ * whose list only the station can assemble, which is why it is here rather than being something a
+ * plugin could answer: the ids are qualified with the plugin that offered them, and no plugin knows
+ * what the others are called.
+ *
+ * The four `plugins.*` members answer the enabled plugins that declare a given capability — speech,
+ * llm, mixer, analysis — by id and name, for the settings that pick which plugin a capability with
+ * several installed candidates uses. Those settings stay free text (`selectPlugin` in
+ * `plugin.selection.ts` accepts an id that is not currently a candidate without falling back), so
+ * this is a suggestion list rather than a closed `select` — the console resolves it the same way as
+ * the other sources here, against the plugin list rather than a static enum.
+ *
+ * `llm.models` is the odd one and the only member whose answer comes from a PLUGIN rather than from
+ * a station table: the models the selected model plugin currently offers, for the settings that say
+ * which model a particular writer should use. It resolves through the suggestions route every plugin
+ * settings form already uses, against whichever plugin `llm.pluginId` names, so the six writer
+ * settings offer the same list the plugin's own form does — including which provider each model
+ * lives on, since a model name carries that.
+ *
+ * An enum rather than a boolean for {@link ConfigFieldUnit}'s reason: the next one (voices,
+ * personas) is obvious, and a closed set is what the contract mirroring this can express. Whatever
+ * it names is resolved by the CONSOLE; nothing here reaches a plugin.
+ */
+export type ConfigFieldOptionSource = 'station.newsCategories' | 'station.newsFeeds' | 'intl.timeZones' | 'plugins.speech' | 'plugins.llm' | 'plugins.mixer' | 'plugins.analysis' | 'llm.models';
+/**
+ * One column of a `list` field.
+ *
+ * Still a smaller vocabulary than {@link ConfigFieldType} — no nested `list`, because a table inside
+ * a table is a form nobody can fill in — but `secret` is now in it, and the reason it was not is
+ * worth keeping because it is what had to be built to allow it. A row was stored as plain JSON with
+ * nothing to encrypt one cell against: a ciphertext has to belong to a ROW, and a row had no
+ * identity beyond its position in an array the console rewrites whole on every save. {@link ROW_ID_KEY}
+ * is that identity, and {@link rowSecretKey} is where the cell's ciphertext lives.
+ *
+ * Every ordinary cell is stored as a STRING in the row, so a column is about the control the
+ * operator gets rather than about the shape of what is kept. A `secret` cell is the exception and
+ * the exception is the point: it is never in the row at all, and the row an author reads back has
+ * no trace of it. See {@link readRowSecret}.
+ */
+export interface ConfigFieldColumn {
+    /**
+     * Key this cell is stored under inside the row object.
+     *
+     * Whatever suits the plugin, dots included, exactly like {@link ConfigField.key}. A row editor
+     * addresses a cell by a path and a dot in a path means a step into a nested object, but that is
+     * the FORM's problem and it solves it the way it already solves the same problem for a
+     * dot-keyed station setting: it names its inputs positionally and puts the real keys back on
+     * the way out. Nothing a plugin author has to know about.
+     *
+     * One character is refused, and only because {@link rowSecretKey} joins on it: a `/`. That
+     * separator has to be unambiguous or a cell's ciphertext could be addressed by two different
+     * keys, so it is refused at the schema rather than escaped.
+     */
+    key: string;
+    /** Column heading. */
+    label: string;
+    /**
+     * `string` free text, `url` free text meant to be an address, `select` one of `options`, and
+     * `secret` a credential this row holds — write-only, encrypted per cell, and never in the row.
+     */
+    type: 'string' | 'url' | 'select' | 'secret';
+    /** Whether a row is only counted once this cell is filled in. */
+    required?: boolean;
+    /** Ghost text inside the cell. */
+    placeholder?: string;
+    /** Choices, fixed when the manifest is written. See {@link ConfigField.options}. */
+    options?: ConfigFieldOption[];
+    /** Choices only the station can enumerate. See {@link ConfigFieldOptionSource}. */
+    optionsFrom?: ConfigFieldOptionSource;
+    /**
+     * Key of another column in the same list. This cell only applies to a row whose cell there
+     * holds one of {@link dependsOnValues}.
+     *
+     * For the table whose columns are not all about the same row: a provider list where the
+     * address belongs to a self-hosted server and the API key to a vendor, a supplier list where
+     * one kind is reached by URL and another by account id. Without it every column is drawn on
+     * every row, so an operator meets a cell their row has no use for, with no way to tell it from
+     * one they have not filled in yet.
+     *
+     * **This is not the rendering hint {@link ConfigField.dependsOn} is**, and the difference is
+     * the whole reason it is here. A field-level `dependsOn` hides a control and the server never
+     * reads it. This says the cell DOES NOT APPLY, so the console declines to send it and the host
+     * declines to derive anything from it — which for a `url` column means the row contributes no
+     * hostname to the plugin's allowlist (`addressCells` in `plugin.host.factory.ts`). An address
+     * typed on a row before its kind was changed would otherwise widen the allowlist by a host the
+     * plugin can never call, which is exactly the quiet widening that path exists to refuse.
+     *
+     * Forgiving in three places, all of them the same instinct as `isVisible` in the console's
+     * form: a target this list does not declare shows the cell, a target cell that is EMPTY shows
+     * the cell, and values without a target are ignored. The empty case is the load-bearing one. A
+     * column has no `default`, so a row somebody has just added holds `''` in every cell, and a
+     * rule that hid a cell there would hide it on the one row that most needs filling in.
+     *
+     * A `secret` cell that does not apply keeps whatever is stored rather than being cleared.
+     * Absent already means "keep it" in `plugin.config.rows.ts`, and reading a visibility rule as
+     * an instruction to destroy a credential would be a surprise nobody asked for.
+     */
+    dependsOn?: string;
+    /**
+     * The values of the {@link dependsOn} cell that this one applies to. Ignored without a target.
+     *
+     * Omitted means "any value at all", which is what a field-level `dependsOn` already means, so
+     * an author who knows that one knows this.
+     */
+    dependsOnValues?: string[];
+}
+/**
+ * The chosen values of a `multiselect`, out of the string it is stored as.
+ *
+ * Stored as a JSON array because plugin config is a string map, and read back
+ * through here so every plugin agrees on the encoding. Tolerant on purpose: a
+ * value hand-edited into something unreadable answers empty rather than failing
+ * a load, which for a field like "which models can use tools" is the difference
+ * between a degraded station and one that will not start.
+ */
+export declare function parseMultiSelect(raw: unknown): string[];
+/**
+ * The cell key a row's own identity is stored under.
+ *
+ * A reserved name rather than a column an author declares, because it is not data: nobody types it,
+ * nothing renders it, and a plugin that ignores it entirely is a plugin that behaves exactly as it
+ * did before this existed. The host mints one when a row is first saved and preserves it forever
+ * after.
+ *
+ * ## Why a row needs a name at all
+ *
+ * Only so a {@link ConfigFieldColumn} may be a `secret`. A secret is encrypted and kept out of the
+ * row, which means something has to say which row a given ciphertext belongs to — and until this
+ * existed the only answer was "the third one", from a console that rewrites the whole array on
+ * every save and lets the operator reorder it. Position is not identity. A `$` leads it because no
+ * sensible column key does, and because a row whose keys are printed somewhere reads as obviously
+ * not-a-column.
+ */
+export declare const ROW_ID_KEY = "$id";
+/**
+ * Where a `secret` cell's ciphertext lives, in the same flat map a `secret` FIELD's does.
+ *
+ * `field/row/column`, joined on the one character a field key and a column key may not contain
+ * (both schemas refuse it below). That is what keeps this unambiguous against a plain secret
+ * field's key, which is a bare field key and can therefore never collide with a three-part one.
+ *
+ * One map rather than a nested shape because everything already built for secrets — encrypting per
+ * entry, reporting configured-ness as a boolean, the rule that no value ever leaves the server —
+ * works on a flat `Record<string, string>` and needed no changes to carry these.
+ */
+export declare function rowSecretKey(fieldKey: string, rowId: string, columnKey: string): string;
+/**
+ * Whether a stored secret key belongs to a row rather than to a field.
+ *
+ * For the host, which merges stored secrets back into the form to validate it: a row's cells belong
+ * inside their row and putting them at the top level would show a plugin's schema three keys it has
+ * never declared.
+ */
+export declare function isRowSecretKey(key: string): boolean;
+/**
+ * The rows of a `list` field, out of the string it is stored as.
+ *
+ * A JSON array of objects in a string, for {@link parseMultiSelect}'s reason and encoded the same
+ * way, so a `list` needs nothing of the storage path that a `string` did not already have. Tolerant
+ * in the same way and for the same stakes: anything unreadable is no rows rather than a plugin that
+ * will not load, and a cell that is not a string is dropped rather than stringified, since a number
+ * where a URL was expected is a mistake worth seeing as an empty cell.
+ *
+ * A row with nothing in it is dropped, because the form leaves one behind whenever an operator adds
+ * a row and thinks better of it.
+ */
+export declare function parseRows(raw: unknown): Record<string, string>[];
+/**
+ * A declarative description of one row in a plugin's settings form. The host
+ * renders these; plugins never ship UI.
+ */
+export interface ConfigField {
+    /** Key this value is stored under, and the key `host.config`/`host.secrets` reads it back by. */
+    key: string;
+    /** Human label shown next to the input. */
+    label: string;
+    type: ConfigFieldType;
+    /** Whether the form refuses to save without a value. Defaults to false. */
+    required?: boolean;
+    /** Prefilled value. Never provide a default for a `secret`. */
+    default?: string | number | boolean;
+    /**
+     * What a `number`'s value is measured in. Ignored on every other type.
+     *
+     * See {@link ConfigFieldUnit}: the stored value stays in this unit and only the control the
+     * operator touches changes.
+     */
+    unit?: ConfigFieldUnit;
+    /**
+     * The control to draw this field with, where the ordinary one for its type reads badly.
+     *
+     * `slider` is for a `number` and is ignored without both `min` and `max`; `tags` is for a
+     * `string`. See {@link ConfigFieldControl}. Nothing about the stored value changes either way.
+     */
+    control?: ConfigFieldControl;
+    /**
+     * How coarsely a `control` moves. Ignored without one, and defaults to 1.
+     *
+     * The unit is the field's own, so a share between 0 and 1 wants `0.05` and a word count wants
+     * `10`. Worth setting on anything whose range is wider than the pixels it is drawn in, since
+     * the alternative is a control that can express values nobody wants and cannot be stopped on
+     * the ones they do.
+     */
+    step?: number;
+    /**
+     * The smallest and largest a `number` may be, inclusive. Ignored on every other type.
+     *
+     * A range the field is DECLARED with rather than one the reader clamps to, which is the whole
+     * point: a resolver that clamps answers a legal number for an illegal one, so the station runs
+     * on something the console never showed and the operator never chose. Declared here, the console
+     * refuses it in front of them and the station's own settings route refuses it again for anything
+     * that did not come through a console.
+     *
+     * A plugin's config is NOT validated against these — the host stores what it is handed and a
+     * plugin's own schema is what judges it — so for a plugin these are a hint to the form. For a
+     * station setting they are enforced, in `serializeSetting`.
+     */
+    min?: number;
+    max?: number;
+    /** Ghost text inside the input. */
+    placeholder?: string;
+    /** Longer explanation rendered under the input. */
+    help?: string;
+    /**
+     * Choices, for a `select` or a `multiselect`.
+     *
+     * Fixed when the manifest is written, so this is for a closed set the plugin
+     * decides. For anything the operator's own server decides, implement
+     * `suggestConfigOptions()` instead: what it returns for this key replaces
+     * these, and it can also turn a `string` into free text with suggestions.
+     */
+    options?: ConfigFieldOption[];
+    /**
+     * Choices only the console can enumerate. See {@link ConfigFieldOptionSource}.
+     *
+     * The field-level twin of {@link ConfigFieldColumn.optionsFrom}, and it resolves the same way
+     * and merges at the same point: whatever `suggestConfigOptions()` says for this key wins, and
+     * this is what is offered when it says nothing.
+     */
+    optionsFrom?: ConfigFieldOptionSource;
+    /**
+     * The columns of a `list`, in the order they are drawn. Ignored on every other type.
+     *
+     * A `list` with none is a field with nothing to fill in, so declare at least one.
+     */
+    columns?: ConfigFieldColumn[];
+    /**
+     * Key of another field in the same form. This field is only shown when
+     * that field has a truthy value.
+     */
+    dependsOn?: string;
+    /**
+     * Key of the `number` field that is the UPPER end of the range this one opens. Declared on the
+     * lower end only, and ignored on every other type.
+     *
+     * Two settings, still: each keeps its own key, its own row and its own validation, and
+     * `serializeSetting` refuses each one by name exactly as it did before. What this changes is
+     * that the console draws them as one control with two handles instead of two boxes that happen
+     * to sit next to each other.
+     *
+     * The reason is legibility. Two boxes cannot say that one is the far end of the other, so a
+     * range arrives as two settings whose labels have to carry the relationship ("fewest", "most",
+     * "the other end") and an operator reads the pair rather than seeing it. One track with two
+     * handles says it in the shape of the control.
+     *
+     * NOT correctness, which is worth stating because it is the plausible reason and it is wrong
+     * here: every reader of a paired setting in this station takes the two ends as an UNORDERED
+     * pair and sorts them, so a range stored the wrong way round has always been tolerated rather
+     * than obeyed. The handles not crossing is a nicety on top, not the point.
+     *
+     * Worth declaring only where the declared range is narrow enough that the whole track is
+     * usable. A pair bounded by a typo guard rather than by intent — one to a hundred and twenty
+     * minutes, for a station that runs eight to twelve — puts both handles in the first tenth and
+     * makes the exact figure somebody has in mind a pixel. Those stay two boxes.
+     *
+     * A rendering hint like {@link ConfigField.dependsOn}, and forgiving in the same way: if the
+     * named key is not in this form, both ends fall back to their own controls rather than one of
+     * them disappearing. A settings page that draws one group of a larger set is the ordinary case
+     * for that.
+     */
+    rangeWith?: string;
+}
+export declare const configFieldOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export declare const configFieldTypeSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    text: "text";
+    url: "url";
+    secret: "secret";
+    select: "select";
+    multiselect: "multiselect";
+    list: "list";
+    note: "note";
+}>;
+export declare const configFieldUnitSchema: z.ZodEnum<{
+    bytes: "bytes";
+    fraction: "fraction";
+}>;
+export declare const configFieldControlSchema: z.ZodEnum<{
+    slider: "slider";
+    tags: "tags";
+}>;
+/**
+ * Every member of {@link ConfigFieldOptionSource}, and it has to stay every member: this validates
+ * real manifests at load, so a source missing here is a plugin the host refuses to start. Two were
+ * missing for exactly that reason and nothing caught it, because no bundled plugin had asked for
+ * one yet.
+ */
+export declare const configFieldOptionSourceSchema: z.ZodEnum<{
+    "station.newsCategories": "station.newsCategories";
+    "station.newsFeeds": "station.newsFeeds";
+    "intl.timeZones": "intl.timeZones";
+    "plugins.speech": "plugins.speech";
+    "plugins.llm": "plugins.llm";
+    "plugins.mixer": "plugins.mixer";
+    "plugins.analysis": "plugins.analysis";
+    "llm.models": "llm.models";
+}>;
+export declare const configFieldColumnSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        url: "url";
+        secret: "secret";
+        select: "select";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+    optionsFrom: z.ZodOptional<z.ZodEnum<{
+        "station.newsCategories": "station.newsCategories";
+        "station.newsFeeds": "station.newsFeeds";
+        "intl.timeZones": "intl.timeZones";
+        "plugins.speech": "plugins.speech";
+        "plugins.llm": "plugins.llm";
+        "plugins.mixer": "plugins.mixer";
+        "plugins.analysis": "plugins.analysis";
+        "llm.models": "llm.models";
+    }>>;
+    dependsOn: z.ZodOptional<z.ZodString>;
+    dependsOnValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const configFieldSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        text: "text";
+        url: "url";
+        secret: "secret";
+        select: "select";
+        multiselect: "multiselect";
+        list: "list";
+        note: "note";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    unit: z.ZodOptional<z.ZodEnum<{
+        bytes: "bytes";
+        fraction: "fraction";
+    }>>;
+    control: z.ZodOptional<z.ZodEnum<{
+        slider: "slider";
+        tags: "tags";
+    }>>;
+    step: z.ZodOptional<z.ZodNumber>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    help: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+    optionsFrom: z.ZodOptional<z.ZodEnum<{
+        "station.newsCategories": "station.newsCategories";
+        "station.newsFeeds": "station.newsFeeds";
+        "intl.timeZones": "intl.timeZones";
+        "plugins.speech": "plugins.speech";
+        "plugins.llm": "plugins.llm";
+        "plugins.mixer": "plugins.mixer";
+        "plugins.analysis": "plugins.analysis";
+        "llm.models": "llm.models";
+    }>>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            url: "url";
+            secret: "secret";
+            select: "select";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>>;
+        optionsFrom: z.ZodOptional<z.ZodEnum<{
+            "station.newsCategories": "station.newsCategories";
+            "station.newsFeeds": "station.newsFeeds";
+            "intl.timeZones": "intl.timeZones";
+            "plugins.speech": "plugins.speech";
+            "plugins.llm": "plugins.llm";
+            "plugins.mixer": "plugins.mixer";
+            "plugins.analysis": "plugins.analysis";
+            "llm.models": "llm.models";
+        }>>;
+        dependsOn: z.ZodOptional<z.ZodString>;
+        dependsOnValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    dependsOn: z.ZodOptional<z.ZodString>;
+    rangeWith: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=plugin.config.fields.d.ts.map

package/dist/plugin.config.fields.d.ts.map

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