@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/configuration/formatDetailsConfigSchema.d.ts

@@ -1,7 +1,7 @@
 /**
  * Levels of subfeature the `subfeatures` callback runs on when no tier sets
- * `depth`. Lives here rather than as the slot's `defaultValue` because the slot
- * has to be able to say "unset": see the `depth` slot's own comment.
+ * `depth`. Applied by the reader rather than as the slot's `defaultValue`, so
+ * the slot can still read as unset and the session's value reach a track.
  */
 export declare const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
 /**
@@ -35,46 +35,20 @@ export declare const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
  * ```
  */
 export declare function FormatDetailsConfigSchemaFactory(): import("./configurationSchema.ts").ConfigurationSchemaType<{
-    /**
-     * #slot formatDetails.feature
-     * callback returning an object of fields to merge onto the clicked feature.
-     * A plain object works too, for fields that are the same on every feature
-     */
     readonly feature: {
-        readonly type: "frozen";
-        readonly description: "adds extra fields to the feature details";
-        readonly defaultValue: {};
-        readonly contextVariable: ["feature"];
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
     };
-    /**
-     * #slot formatDetails.subfeatures
-     * the same, applied to each subfeature down to `depth`
-     */
     readonly subfeatures: {
-        readonly type: "frozen";
-        readonly description: "adds extra fields to the subfeatures of a feature";
-        readonly defaultValue: {};
-        readonly contextVariable: ["feature"];
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
     };
-    /**
-     * #slot formatDetails.depth
-     * how many levels of subfeature the `subfeatures` callback runs on,
-     * defaulting to 2, which stops at a gene's transcripts rather than
-     * descending into their exons and CDSs. A track's value wins over the
-     * session's
-     */
     readonly depth: {
-        readonly type: "maybeNumber";
-        readonly description: "levels of subfeature the formatDetails.subfeatures callback runs on, default 2";
+        type: "maybeNumber";
     };
-    /**
-     * #slot formatDetails.maxDepth
-     * how many levels of subfeature card the panel renders at all, which is a
-     * separate question from how deep `subfeatures` formats. Unset means no
-     * limit. A track's value wins over the session's
-     */
     readonly maxDepth: {
-        readonly type: "maybeNumber";
-        readonly description: "hide subfeatures nested deeper than this, default no limit";
+        type: "maybeNumber";
     };
-}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
+}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("./requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;

package/esm/configuration/formatDetailsConfigSchema.js

@@ -1,8 +1,8 @@
 import { ConfigurationSchema } from './configurationSchema.js';
 /**
  * Levels of subfeature the `subfeatures` callback runs on when no tier sets
- * `depth`. Lives here rather than as the slot's `defaultValue` because the slot
- * has to be able to say "unset": see the `depth` slot's own comment.
+ * `depth`. Applied by the reader rather than as the slot's `defaultValue`, so
+ * the slot can still read as unset and the session's value reach a track.
  */
 export const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
 /**
@@ -40,23 +40,27 @@ export function FormatDetailsConfigSchemaFactory() {
         /**
          * #slot formatDetails.feature
          * callback returning an object of fields to merge onto the clicked feature.
-         * A plain object works too, for fields that are the same on every feature
+         * `track` is the track's config, so one session-wide callback can link out
+         * per assembly or name the track. A plain object works too, for fields
+         * that are the same on every feature
          */
         feature: {
             type: 'frozen',
             description: 'adds extra fields to the feature details',
             defaultValue: {},
-            contextVariable: ['feature'],
+            contextVariable: ['feature', 'track'],
         },
         /**
          * #slot formatDetails.subfeatures
-         * the same, applied to each subfeature down to `depth`
+         * the same, applied to each subfeature down to `depth`. `parent` is the
+         * feature it sits in and `depth` how far down, 1 for a gene's transcript
+         * and 2 for the transcript's exon
          */
         subfeatures: {
             type: 'frozen',
             description: 'adds extra fields to the subfeatures of a feature',
             defaultValue: {},
-            contextVariable: ['feature'],
+            contextVariable: ['feature', 'parent', 'depth', 'track'],
         },
         /**
          * #slot formatDetails.depth
@@ -66,11 +70,6 @@ export function FormatDetailsConfigSchemaFactory() {
          * session's
          */
         depth: {
-            // `maybeNumber`, so unset is expressible. With a `defaultValue` the two
-            // tiers cannot be told apart -- a plain number slot reads back its own
-            // default, so "the track set 2" and "the track set nothing" are the same
-            // read, and the session-wide value can never apply to a track. The
-            // resolved default is DEFAULT_FORMAT_DETAILS_DEPTH, applied by the reader
             type: 'maybeNumber',
             description: 'levels of subfeature the formatDetails.subfeatures callback runs on, default 2',
         },
@@ -81,8 +80,6 @@ export function FormatDetailsConfigSchemaFactory() {
          * limit. A track's value wins over the session's
          */
         maxDepth: {
-            // `maybeNumber` for the same reason as `depth`, and here unset is also
-            // the meaningful value: no limit at all
             type: 'maybeNumber',
             description: 'hide subfeatures nested deeper than this, default no limit',
         },

package/esm/configuration/fullConfSnapshot.d.ts

@@ -5,24 +5,9 @@ import type { AnyConfigurationModel } from './types.ts';
  * via `types.stripDefault`, this returns every slot's current value, so the
  * result is a self-contained config object an RPC worker can read with no
  * schema. JEXL callback slots keep their raw `"jexl:..."` string for the worker
- * to evaluate per-feature.
- *
- * **Why this isn't exported from `@jbrowse/core/configuration`.** It was
- * (as `getConfSnapshot`), and being reachable was the hazard. A promotable slot
- * resolves against the session at read time, so snapshotting one raw ships the
- * bare `undefined` inherit sentinel to a worker with no session to resolve it
- * against — and every display in the repo now has promotable slots. The public
- * form used to defend itself by *throwing* on such a config, which meant the
- * obvious spelling in a new `rpcProps()` failed at runtime, on the first fetch,
- * in whichever product exercised that display. Off the barrel, the same mistake
- * is an unresolved import: it can't be written at all, and
- * `getConfigSnapshotWithPromotables(display)` is the one way across the boundary.
- * So this is the shared walker those resolvers are built on, not an entry point.
- *
- * The nested-schema guard below is the part of that defense still worth
- * enforcing at runtime, since no import can express it.
- *
- * Note: only handles slots and direct sub-configuration models. Arrays or maps
- * of sub-schemas are silently dropped — nothing has needed them.
+ * to evaluate per-feature. A sub-schema recurses, and so does each entry of an
+ * array or map of them; an explicitly typed schema carries its `type`, which
+ * is what tells the entries of a union list apart. Constants are the editor's
+ * and are left out.
  */
 export declare function fullConfSnapshot(confObject: AnyConfigurationModel): Record<string, unknown>;

package/esm/configuration/fullConfSnapshot.js

@@ -1,66 +1,44 @@
-import { getSnapshot, isArrayType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
-import { promotableSlotNames } from './promotableSlots.js';
-import { getConfigurationSchemaDefinition } from './schemaRegistry.js';
-import { isConfigurationModel, isConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
+import { getSnapshot, getType, isArrayType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { isConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
+// a sub-schema member: one node, or an array or map of them, entry by entry
+function subConfSnapshot(member) {
+    if (!isStateTreeNode(member)) {
+        return member;
+    }
+    const type = getType(member);
+    if (isArrayType(type)) {
+        return member.map(fullConfSnapshot);
+    }
+    if (isMapType(type)) {
+        return Object.fromEntries([...member.entries()].map(([key, node]) => [key, fullConfSnapshot(node)]));
+    }
+    return fullConfSnapshot(member);
+}
 /**
  * Plain-object snapshot of a configuration model including ALL values, even
  * defaults. Unlike `getSnapshot()`, which strips a slot sitting at its default
  * via `types.stripDefault`, this returns every slot's current value, so the
  * result is a self-contained config object an RPC worker can read with no
  * schema. JEXL callback slots keep their raw `"jexl:..."` string for the worker
- * to evaluate per-feature.
- *
- * **Why this isn't exported from `@jbrowse/core/configuration`.** It was
- * (as `getConfSnapshot`), and being reachable was the hazard. A promotable slot
- * resolves against the session at read time, so snapshotting one raw ships the
- * bare `undefined` inherit sentinel to a worker with no session to resolve it
- * against — and every display in the repo now has promotable slots. The public
- * form used to defend itself by *throwing* on such a config, which meant the
- * obvious spelling in a new `rpcProps()` failed at runtime, on the first fetch,
- * in whichever product exercised that display. Off the barrel, the same mistake
- * is an unresolved import: it can't be written at all, and
- * `getConfigSnapshotWithPromotables(display)` is the one way across the boundary.
- * So this is the shared walker those resolvers are built on, not an entry point.
- *
- * The nested-schema guard below is the part of that defense still worth
- * enforcing at runtime, since no import can express it.
- *
- * Note: only handles slots and direct sub-configuration models. Arrays or maps
- * of sub-schemas are silently dropped — nothing has needed them.
+ * to evaluate per-feature. A sub-schema recurses, and so does each entry of an
+ * array or map of them; an explicitly typed schema carries its `type`, which
+ * is what tells the entries of a union list apart. Constants are the editor's
+ * and are left out.
  */
 export function fullConfSnapshot(confObject) {
-    const result = {};
-    const table = getConfigurationSchemaDefinition(confObject);
-    for (const [key, def] of Object.entries(table ?? {})) {
-        const v = confObject[key];
+    const meta = getConfigurationSchemaMetadata(getType(confObject));
+    const result = meta?.options.explicitlyTyped
+        ? { type: confObject.type }
+        : {};
+    for (const [key, def] of Object.entries(meta?.definition ?? {})) {
+        const member = confObject[key];
         if (isSlotDefinitionEntry(def)) {
-            // jexl callback strings pass through raw for per-feature evaluation in
-            // the worker.
-            result[key] = isStateTreeNode(v) ? getSnapshot(v) : v;
+            result[key] = isStateTreeNode(member) ? getSnapshot(member) : member;
         }
-        else if (isConfigurationSchemaType(def) &&
-            !isArrayType(def) &&
-            !isMapType(def) &&
-            isConfigurationModel(v)) {
-            // a direct sub-configuration recurses. Arrays/maps of sub-schemas are
-            // dropped: their MST node also reports as a config model, but the
-            // array/map type carries no registered slot table, so recursing would
-            // emit a meaningless `{}` (a type-confusion hazard for a consumer
-            // expecting the array). Constants are skipped entirely.
-            assertNoPromotableSlots(v);
-            result[key] = fullConfSnapshot(v);
+        else if (isConfigurationSchemaType(def) && member !== undefined) {
+            result[key] = subConfSnapshot(member);
         }
     }
     return result;
 }
-// A promotable slot is only ever resolvable at a config's own top level — the
-// resolver walks that one slot table (`promotableSlotNames` / `getSlotDefinition`)
-// and never descends. So one declared inside a *nested* schema would resolve
-// nowhere and serialize as its bare inherit sentinel, with no import to get wrong
-// and no symptom until a worker read the sentinel. Fail at the snapshot instead.
-function assertNoPromotableSlots(confObject) {
-    const promotable = promotableSlotNames(confObject);
-    if (promotable.size > 0) {
-        throw new Error(`nested config schema declares promotable slots (${[...promotable].join(', ')}): the cascade only resolves a display config's own top-level slots, so these would serialize as the bare inherit sentinel. Declare them on the display's own schema instead.`);
-    }
-}

package/esm/configuration/getConf.d.ts

@@ -1,5 +1,4 @@
-import type { ResolvableDisplay } from './promotableResolve.ts';
-import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue, ConfigurationSlotValueResolved } from './types.ts';
+import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 /**
  * #api core/configuration
  * Reads a configuration value from a state model that has a `.configuration`
@@ -12,12 +11,6 @@ import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSche
  * It does not consult the session and has no per-slot behavior; what you read is
  * what the track stores.
  *
- * A `promotable` slot read this way therefore yields the raw stored value,
- * `undefined` included — that `undefined` is the cascade's inherit sentinel, and
- * `resolveConf` is what turns it into a real value. The read type keeps the
- * `undefined` on purpose, so reaching for the wrong reader is a compile error
- * rather than a silent one.
- *
  * @param model - object containing a 'configuration' member
  * @param slotPaths - array of paths to read
  * @param args - extra arguments e.g. for a feature callback,
@@ -26,36 +19,21 @@ import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSche
 export declare function getConf(model: {
     configuration: AnyConfigurationModel;
 }): AnyConfigurationSnapshot;
-export declare function getConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | string[] = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
+export declare function getConf<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
     configuration: CONFMODEL;
-}, slotPath: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : any;
+}, slotPath: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
 /**
  * #api core/configuration
- * Reads a `promotable` slot through the display-type-default cascade — the
- * track's own value, else the session-wide promoted default for this display
- * type, else the slot's `promotedBase`. Always yields a real value, never the
- * `undefined` inherit sentinel, so a display's value getter is
- * `get displayMode(): DisplayMode { return resolveConf(self, 'displayMode') }`
- * with no post-guard and no cast.
- *
- * Separate from `getConf` rather than folded into it, deliberately: resolution
- * consults the session, so it is main-thread only and throws on a detached node.
- * Folding it in was built and reverted — ADR-046.
- *
- * Throws if `slot` isn't promotable — the cascade has nothing to say about a
- * plain slot, and `getConf` is what you want there.
+ * Write counterpart to `getConf`, and it takes the same path: a slot name, or
+ * an array naming a sub-schema's member at any depth —
+ * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
+ * model, or a config node directly.
  *
- * Takes no jexl `args`, unlike `getConf`: a promotable slot cannot hold a
- * callback (see `SlotResolution`), so there is no per-feature context to supply.
- *
- * @param model - the display state model (needs the session + display type)
- * @param slot - the promotable slot to resolve
- */
-export declare function resolveConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: ResolvableDisplay<CONFMODEL>, slot: SLOT): ConfigurationSlotValueResolved<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
-/**
- * #api core/configuration
- * Write counterpart to `getConf`: sets a slot on a state model that has a
- * `.configuration` member (a track or display state model).
+ * **The path length says what the write replaces.** A path ending on a slot
+ * writes that slot and leaves the object around it alone; a path ending on a
+ * sub-schema replaces the whole object, which is how a channel whose members
+ * move together — a facet's field and the domain that field's values order —
+ * gets written without a stale member surviving underneath.
  *
  * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
  * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
@@ -75,14 +53,40 @@ export declare function resolveConf<CONFMODEL extends AnyConfigurationModel, SLO
  * `HostChecksSlotNames` pins each one.
  *
  * A wrong *value* type still throws at runtime (MST type-checks the assignment)
- * rather than at compile time. `value` is deliberately `unknown` because the
- * inherit sentinel (`undefined`/`null`) is a legitimate write on every
- * promotable slot, which the declared slot value type doesn't include.
+ * rather than at compile time. `value` is deliberately `unknown` because
+ * `undefined` is a legitimate write — it resets a slot to its schema default —
+ * and the declared slot value type doesn't include it.
  *
- * @param model - object containing a 'configuration' member
- * @param slotName - the slot to write
+ * @param target - a model with a `configuration` member, or a config node
+ * @param slotPath - the slot to write, or the path to one
  * @param value - the new value
  */
-export declare function setConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
+export declare function setConf<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(target: CONFMODEL | {
     configuration: CONFMODEL;
-}, slotName: SLOT, value: unknown): void;
+}, slotPath: SLOT, value: unknown): void;
+export interface ConfSettingsReport {
+    /** the keys the config declares, written */
+    applied: string[];
+    /** the keys it does not, with the values the lift left them */
+    undeclared: Record<string, unknown>;
+    /** a declared key whose write threw, and why */
+    failed: {
+        key: string;
+        error: string;
+    }[];
+}
+/**
+ * #api core/configuration
+ * Write a settings bag — a session spec's track entry, a share link, an agent
+ * call — onto a config. Each key names a member: a slot or a channel is written
+ * whole, as `setConf` writes it, so `null` resets it (ADR-146); a namespace's
+ * object names members inside it, at any depth, and the ones it leaves out
+ * keep their values. The config's own lift and checks run over the bag first,
+ * and each namespace's over its part, so a shorthand or a legacy key reads the
+ * same here as in `config.json`. A key the config does not declare is reported
+ * for the caller to route or refuse, and a declared key whose write throws
+ * costs that key alone.
+ */
+export declare function applyConfSettings(target: AnyConfigurationModel | {
+    configuration: AnyConfigurationModel;
+}, settings: Record<string, unknown>): ConfSettingsReport;

package/esm/configuration/getConf.js

@@ -1,46 +1,24 @@
-import { resolveSlot } from './promotableResolve.js';
+import { getType, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { isPlainObject } from '../util/objectUtils.js';
 import { readConfObject } from './readConfObject.js';
+import { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.js';
+import { isConfigurationModel, isConfigurationSchemaType, isConstantEntry, } from './schemaTypes.js';
+import { preProcessSnapshotWith } from './snapshotPreprocess.js';
 export function getConf(model, slotPath, args = {}) {
     return readConfObject(model.configuration, slotPath, args);
 }
 /**
  * #api core/configuration
- * Reads a `promotable` slot through the display-type-default cascade — the
- * track's own value, else the session-wide promoted default for this display
- * type, else the slot's `promotedBase`. Always yields a real value, never the
- * `undefined` inherit sentinel, so a display's value getter is
- * `get displayMode(): DisplayMode { return resolveConf(self, 'displayMode') }`
- * with no post-guard and no cast.
+ * Write counterpart to `getConf`, and it takes the same path: a slot name, or
+ * an array naming a sub-schema's member at any depth —
+ * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
+ * model, or a config node directly.
  *
- * Separate from `getConf` rather than folded into it, deliberately: resolution
- * consults the session, so it is main-thread only and throws on a detached node.
- * Folding it in was built and reverted — ADR-046.
- *
- * Throws if `slot` isn't promotable — the cascade has nothing to say about a
- * plain slot, and `getConf` is what you want there.
- *
- * Takes no jexl `args`, unlike `getConf`: a promotable slot cannot hold a
- * callback (see `SlotResolution`), so there is no per-feature context to supply.
- *
- * @param model - the display state model (needs the session + display type)
- * @param slot - the promotable slot to resolve
- */
-export function resolveConf(
-// the display state node itself, not just its `.configuration`: the cascade
-// keys the session-wide tier on `type` and reaches the session through the
-// node. Asking for that shape is what keeps this cast-free — hand it a bare
-// config holder and tsc names the missing members instead of failing at the
-// first read. `ResolvableDisplay<CONFMODEL>`, never
-// `ResolvableDisplay & { configuration: CONFMODEL }`: the intersection
-// re-widens the slot names to `string` (see `ResolvableDisplay`)
-model, slot) {
-    // the resolution is `unknown`, which the declared return type can't infer
-    return resolveSlot(model, slot).value;
-}
-/**
- * #api core/configuration
- * Write counterpart to `getConf`: sets a slot on a state model that has a
- * `.configuration` member (a track or display state model).
+ * **The path length says what the write replaces.** A path ending on a slot
+ * writes that slot and leaves the object around it alone; a path ending on a
+ * sub-schema replaces the whole object, which is how a channel whose members
+ * move together — a facet's field and the domain that field's values order —
+ * gets written without a stale member surviving underneath.
  *
  * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
  * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
@@ -60,15 +38,104 @@ model, slot) {
  * `HostChecksSlotNames` pins each one.
  *
  * A wrong *value* type still throws at runtime (MST type-checks the assignment)
- * rather than at compile time. `value` is deliberately `unknown` because the
- * inherit sentinel (`undefined`/`null`) is a legitimate write on every
- * promotable slot, which the declared slot value type doesn't include.
+ * rather than at compile time. `value` is deliberately `unknown` because
+ * `undefined` is a legitimate write — it resets a slot to its schema default —
+ * and the declared slot value type doesn't include it.
  *
- * @param model - object containing a 'configuration' member
- * @param slotName - the slot to write
+ * @param target - a model with a `configuration` member, or a config node
+ * @param slotPath - the slot to write, or the path to one
  * @param value - the new value
  */
-export function setConf(model, slotName, value) {
-    // eslint-disable-next-line no-restricted-syntax -- this is setConf
-    model.configuration.setSlot(slotName, value);
+export function setConf(target, slotPath, value) {
+    writeConfPath(isConfigurationModel(target) ? target : target.configuration, typeof slotPath === 'string' ? [slotPath] : slotPath, value);
+}
+/**
+ * Walk to the node the last segment names a member of, then write that member
+ * through whichever of the node's two write actions the member is: a
+ * sub-schema, single or a collection, is replaced whole, and a slot goes
+ * through `setSlot` so ADR-052's name guard and the value-type guard both run.
+ * MST's `applyPatch` takes the same path and runs neither guard.
+ */
+function writeConfPath(conf, path, value) {
+    if (!path.length) {
+        throw new Error('setConf needs a slot name or a path to one');
+    }
+    let node = conf;
+    for (const segment of path.slice(0, -1)) {
+        const child = node[segment];
+        if (!isConfigurationModel(child)) {
+            throw new Error(`${getType(node).name} has no sub-schema "${segment}", so ${path.join('.')} names nothing to write`);
+        }
+        node = child;
+    }
+    const leaf = path.at(-1);
+    // Classify off the declaration, never off what the member holds: a
+    // `stringArray` slot holds an array node, and an optional sub-schema nobody
+    // has written yet holds nothing.
+    const declared = getConfigurationSchemaDefinition(node)?.[leaf];
+    if (isConfigurationSchemaType(declared)) {
+        // eslint-disable-next-line no-restricted-syntax -- this is setConf
+        node.setSubschema(leaf, value);
+    }
+    else {
+        // eslint-disable-next-line no-restricted-syntax -- this is setConf
+        node.setSlot(leaf, value);
+    }
+}
+// A sub-schema of independent settings, whose members a bag names one by one.
+// A channel — a sub-schema with a shorthand — takes one written value, so a
+// bag replaces it whole: `{ field }` after `{ field, domain }` is a facet with
+// no domain, and a merge would leave the old domain standing.
+function namespaceMetadata(member) {
+    const meta = isStateTreeNode(member)
+        ? getConfigurationSchemaMetadata(getType(member))
+        : undefined;
+    return meta?.options.shorthand === undefined ? meta : undefined;
+}
+function writeConfMember(conf, key, value) {
+    const member = conf[key];
+    const namespace = isPlainObject(value) ? namespaceMetadata(member) : undefined;
+    if (namespace) {
+        for (const [k, v] of Object.entries(preProcessSnapshotWith(namespace, value))) {
+            writeConfMember(member, k, v);
+        }
+    }
+    else {
+        writeConfPath(conf, [key], value);
+    }
+}
+/**
+ * #api core/configuration
+ * Write a settings bag — a session spec's track entry, a share link, an agent
+ * call — onto a config. Each key names a member: a slot or a channel is written
+ * whole, as `setConf` writes it, so `null` resets it (ADR-146); a namespace's
+ * object names members inside it, at any depth, and the ones it leaves out
+ * keep their values. The config's own lift and checks run over the bag first,
+ * and each namespace's over its part, so a shorthand or a legacy key reads the
+ * same here as in `config.json`. A key the config does not declare is reported
+ * for the caller to route or refuse, and a declared key whose write throws
+ * costs that key alone.
+ */
+export function applyConfSettings(target, settings) {
+    const conf = isConfigurationModel(target) ? target : target.configuration;
+    const meta = getConfigurationSchemaMetadata(conf);
+    const values = meta ? preProcessSnapshotWith(meta, settings) : settings;
+    const report = { applied: [], undeclared: {}, failed: [] };
+    for (const [key, value] of Object.entries(values)) {
+        const declared = Object.hasOwn(meta?.definition ?? {}, key)
+            ? meta.definition[key]
+            : undefined;
+        if (declared === undefined || isConstantEntry(declared)) {
+            report.undeclared[key] = value;
+            continue;
+        }
+        try {
+            writeConfMember(conf, key, value);
+            report.applied.push(key);
+        }
+        catch (e) {
+            report.failed.push({ key, error: `${e}` });
+        }
+    }
+    return report;
 }

package/esm/configuration/index.d.ts

@@ -1,19 +1,32 @@
 export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.ts';
-export type { ConfigurationSchemaDefinition } from './configurationSchema.ts';
-export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigModelForFields, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, } from './types.ts';
-export { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.ts';
+export type { ConfigurationSchemaDefinition, RetiredSpelling, } from './configurationSchema.ts';
+export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.ts';
+export type { ConfigurationSchemaUnionType } from './configurationSchemaUnion.ts';
+export type { ConfigSlotDefinition } from './configurationSlot.ts';
+export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigModelForFields, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, IdentifierSlotDef, PluggableConfigNode, TypeSlotDef, } from './types.ts';
+export { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.ts';
+export type { ConfigurationSchemaUnionMetadata } from './schemaRegistry.ts';
 export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.ts';
 export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.ts';
 export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.ts';
 export { mergeFormatCallbacks } from './mergeFormatCallbacks.ts';
-export { readConfObject, readConfSlot, readConfigValue, } from './readConfObject.ts';
-export { getConf, resolveConf, setConf } from './getConf.ts';
-export { expandTabixShorthand, tabixIndexSnapshot } from './tabixShorthand.ts';
-export { tabixIndexFields } from './tabixIndexFields.ts';
+export { readConfObject, readConfigValue } from './readConfObject.ts';
+export { applyConfSettings, getConf, setConf } from './getConf.ts';
+export type { ConfSettingsReport } from './getConf.ts';
+export { fillLocations } from './fillLocations.ts';
+export { applyRetiredSpellings, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, } from './snapshotPreprocess.ts';
+export { shorthandTargets, shorthandTargetsOf } from './schemaTypes.ts';
+export type { ShorthandForm } from './schemaTypes.ts';
+export { requirementProblems } from './requirements.ts';
+export type { ConfigurationSchemaRequirement, RequirementProblem, } from './requirements.ts';
+export { expandTabixShorthand, indexSnapshot, requestedIndexType, tabixIndexSnapshot, } from './tabixShorthand.ts';
+export { expandUriShorthand } from './uriShorthand.ts';
+export { bamIndexFields, bamIndexSchema } from './bamIndexFields.ts';
+export { tabixIndexFields, tabixIndexSchema } from './tabixIndexFields.ts';
+export { fillIndexType, indexSuffix, isCsiLocation } from './indexType.ts';
+export type { IndexType, SiblingIndexType } from './indexType.ts';
 export { evaluateJexl, isCallbackValue } from './slotValueUtils.ts';
 export { toCallbackValue, toFixedValue } from './configurationSlot.ts';
-export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.ts';
+export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, slotChoices, slotValueRefusal, } from './slotFacade.ts';
 export type { SlotFacade } from './slotFacade.ts';
-export type { ResolvableDisplay } from './promotableResolve.ts';
-export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.ts';
-export type { Pin, ResolvedConfigSnapshot, TrackConfigWithPromotables, } from './promotableDefaults.ts';
+export { fullConfSnapshot } from './fullConfSnapshot.ts';

package/esm/configuration/index.js

@@ -1,19 +1,27 @@
 export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.js';
+export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.js';
 export { getConfigurationSchemaDefinition, 
 // exported for scripts/generateConfigManifest.ts, which needs the
 // preProcessSnapshot off a schema whose pluggable type does not expose one —
 // TextSearchAdapterType, where the shorthand is nonetheless the documented
 // way to write the config
-getConfigurationSchemaMetadata, } from './schemaRegistry.js';
+getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.js';
 export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
 export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.js';
 export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.js';
 export { mergeFormatCallbacks } from './mergeFormatCallbacks.js';
-export { readConfObject, readConfSlot, readConfigValue, } from './readConfObject.js';
-export { getConf, resolveConf, setConf } from './getConf.js';
-export { expandTabixShorthand, tabixIndexSnapshot } from './tabixShorthand.js';
-export { tabixIndexFields } from './tabixIndexFields.js';
+export { readConfObject, readConfigValue } from './readConfObject.js';
+export { applyConfSettings, getConf, setConf } from './getConf.js';
+export { fillLocations } from './fillLocations.js';
+export { applyRetiredSpellings, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, } from './snapshotPreprocess.js';
+export { shorthandTargets, shorthandTargetsOf } from './schemaTypes.js';
+export { requirementProblems } from './requirements.js';
+export { expandTabixShorthand, indexSnapshot, requestedIndexType, tabixIndexSnapshot, } from './tabixShorthand.js';
+export { expandUriShorthand } from './uriShorthand.js';
+export { bamIndexFields, bamIndexSchema } from './bamIndexFields.js';
+export { tabixIndexFields, tabixIndexSchema } from './tabixIndexFields.js';
+export { fillIndexType, indexSuffix, isCsiLocation } from './indexType.js';
 export { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
 export { toCallbackValue, toFixedValue } from './configurationSlot.js';
-export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.js';
-export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.js';
+export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, slotChoices, slotValueRefusal, } from './slotFacade.js';
+export { fullConfSnapshot } from './fullConfSnapshot.js';