@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/framework/Entity.d.ts

@@ -0,0 +1,127 @@
+//#region src/framework/Entity.d.ts
+/**
+ * One flat, path-keyed entity — an item or a group node. The base owns hydration and
+ * serialization from the kind's declared field names, so a kind adds no per-entity ctor
+ * or `toJSON`. Identity IS the qualified path; the group is simply its prefix.
+ */
+declare class Entity {
+  #private;
+  readonly path: string;
+  private readonly fieldKeys;
+  /**
+   * VIRTUAL fields — read like any other, and deliberately absent from {@link toJSON}.
+   *
+   * The split is the whole point of having them separately. A computed field is a function of the
+   * entity and its config, so persisting one writes a derivation into the artifact: it goes stale the
+   * moment either input changes, and the stale copy wins on the next hydrate. Provenance is the
+   * clearest case — whether an item borrows is read off the source qualifier in its own fields, so a
+   * stored answer could contradict the value sitting next to it.
+   */
+  private readonly computedKeys;
+  readonly label?: string;
+  readonly description?: string;
+  /** Where a copied entity was taken from, as `<path>@<slug>`; `undefined` for one authored here. */
+  readonly copiedFrom?: string;
+  /** Kept and resolving, but not offered by authoring surfaces. This entity's own flag only; the
+   *  answer that also reads its folders and its pin is `Config.hidden`. */
+  readonly hidden?: boolean;
+  /** Withdrawn from new work: hidden, and every existing use flagged. This entity's own flag only;
+   *  the answer that also reads its folders is `Config.deprecated`. */
+  readonly deprecated?: boolean;
+  /** How to use this entity, as prose for a model. Collected into the guidance document per kind. */
+  readonly guidance?: string;
+  /**
+   * The DEPENDENCIES this item's own fields point through, deduped and sorted — the framework installs
+   * this computed on every kind, so it is declared here rather than per kind.
+   *
+   * `declare` because the value arrives through the computed pass like any other field; this only says
+   * that every entity has it, which is what lets a kind-agnostic reader (`config.resolve(kind, path)`)
+   * ask without a cast.
+   *
+   * Empty for an item the config owns. Reads never need it — `resolveFieldValue` chases a local and a
+   * sourced ref identically — so a caller asking whether this is non-empty is a WRITER, gating an edit
+   * that would turn someone else's value into a copy of itself. A caller wanting to NAME where it comes
+   * from asks {@link source}.
+   */
+  readonly sources: readonly string[];
+  /**
+   * The dependency this item is borrowed FROM — `undefined` for one this config authored, and that
+   * includes one whose own fields point through a link. The framework installs this computed on every
+   * kind too, so it is declared here beside {@link sources}.
+   *
+   * The pair is easy to conflate and gates opposite things. `sources` is about the VALUE: it says a
+   * badge should name another system, and it is set for `{ value: token:accent@ds }` — a pointer this
+   * config wrote, into someone else's token. This is about the ENTITY: it is set only when the item is
+   * stored AS a pointer (`Token.ref('accent@ds').extend({ … })`), which makes the item the source's
+   * with our fields laid over it.
+   *
+   * So a WRITER asks this one. Gating on `sources` locks the first case, where nothing but our own
+   * artifact changes when the ref is retargeted — which is how repointing a local alias came to be
+   * impossible in the token rail. See `borrowedSlug`.
+   */
+  readonly borrowedFrom: string | undefined;
+  constructor(path: string, raw: Record<string, unknown>, fieldKeys: readonly string[],
+  /**
+   * VIRTUAL fields — read like any other, and deliberately absent from {@link toJSON}.
+   *
+   * The split is the whole point of having them separately. A computed field is a function of the
+   * entity and its config, so persisting one writes a derivation into the artifact: it goes stale the
+   * moment either input changes, and the stale copy wins on the next hydrate. Provenance is the
+   * clearest case — whether an item borrows is read off the source qualifier in its own fields, so a
+   * stored answer could contradict the value sitting next to it.
+   */
+  computedKeys?: readonly string[]);
+  /**
+   * The ONE source this item comes from, or `undefined` when it comes from none — what a surface names
+   * when it says where something came from.
+   *
+   * Folds BOTH ways an item can involve another system, because a provenance surface does not care
+   * which: an item borrowed and locally extended came from its source, and an item we authored whose
+   * value points into a source draws from it. Reading only {@link sources} left a borrowed COMPONENT
+   * unbadged, because resolving an extension merges the source's own literal fields in and there is no
+   * qualified ref left to find.
+   *
+   * `undefined` when the answer is not unanimous, which is the case worth stating: an item involving two
+   * systems has no single answer, and naming either would label the other wrongly. That is the same rule
+   * a group follows — see `Config.groupSource`.
+   *
+   * NOT the write gate. Whose the item is has one answer and it is {@link borrowedFrom}.
+   *
+   * A getter rather than a computed field so there is one walk and one stored answer; this is a read of
+   * it.
+   */
+  get source(): string | undefined;
+  /** The pin a copied entity came through — the `@<slug>` half of {@link copiedFrom}. */
+  get copiedThrough(): string | undefined;
+  /** The path a copied entity was taken from, as the source spells it — the half of {@link copiedFrom}
+   *  before the `@`. */
+  get copiedPath(): string | undefined;
+  /** Identity is the whole qualified path (`color/brand`). */
+  get identity(): string;
+  /** The emergent group — everything before the last segment (`color/brand` → `color`);
+   *  `undefined` for a top-level item. Membership is never stored, only derived. */
+  get group(): string | undefined;
+  /** The bare last segment (`color/brand` → `brand`) — what a UI renders. */
+  get leaf(): string;
+  /**
+   * What a UI calls this item: its authored `label` field, else the bare
+   * {@link leaf}. Never identity — a label is metadata and two items may share
+   * one — and never a `kind:` marker, which no person should read.
+   */
+  get displayLabel(): string;
+  /**
+   * This item's declared fields as a plain bag.
+   *
+   * For a reader whose KIND is only known at runtime — a prompt catalogue walking every kind, an op
+   * form rendering whatever collection its tool names. A reader that knows the kind asks the entity
+   * class instead (`Component.get(config, path).styles`), which answers typed.
+   *
+   * Deliberately not `toJSON`: serialization is for storage and the wire, and a display surface
+   * reaching for it is how a raw-shape cast gets in. (No kind declares a field called `body`; one
+   * that did would shadow this, since fields are assigned as own properties.)
+   */
+  get body(): Record<string, unknown>;
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+export { Entity };

package/dist/framework/Entity.js

@@ -0,0 +1,125 @@
+//#region src/framework/Entity.ts
+/**
+* One flat, path-keyed entity — an item or a group node. The base owns hydration and
+* serialization from the kind's declared field names, so a kind adds no per-entity ctor
+* or `toJSON`. Identity IS the qualified path; the group is simply its prefix.
+*/
+var Entity = class {
+	label;
+	description;
+	/** Where a copied entity was taken from, as `<path>@<slug>`; `undefined` for one authored here. */
+	copiedFrom;
+	/** Kept and resolving, but not offered by authoring surfaces. This entity's own flag only; the
+	*  answer that also reads its folders and its pin is `Config.hidden`. */
+	hidden;
+	/** Withdrawn from new work: hidden, and every existing use flagged. This entity's own flag only;
+	*  the answer that also reads its folders is `Config.deprecated`. */
+	deprecated;
+	/** How to use this entity, as prose for a model. Collected into the guidance document per kind. */
+	guidance;
+	constructor(path, raw, fieldKeys, computedKeys = []) {
+		this.path = path;
+		this.fieldKeys = fieldKeys;
+		this.computedKeys = computedKeys;
+		const hydrated = {};
+		for (const key of [...fieldKeys, ...computedKeys]) if (raw[key] !== void 0) hydrated[key] = raw[key];
+		Object.assign(this, hydrated);
+		this.label = raw.label;
+		this.description = raw.description;
+		this.copiedFrom = raw.copiedFrom;
+		this.hidden = raw.hidden;
+		this.deprecated = raw.deprecated;
+		this.guidance = raw.guidance;
+	}
+	/**
+	* The ONE source this item comes from, or `undefined` when it comes from none — what a surface names
+	* when it says where something came from.
+	*
+	* Folds BOTH ways an item can involve another system, because a provenance surface does not care
+	* which: an item borrowed and locally extended came from its source, and an item we authored whose
+	* value points into a source draws from it. Reading only {@link sources} left a borrowed COMPONENT
+	* unbadged, because resolving an extension merges the source's own literal fields in and there is no
+	* qualified ref left to find.
+	*
+	* `undefined` when the answer is not unanimous, which is the case worth stating: an item involving two
+	* systems has no single answer, and naming either would label the other wrongly. That is the same rule
+	* a group follows — see `Config.groupSource`.
+	*
+	* NOT the write gate. Whose the item is has one answer and it is {@link borrowedFrom}.
+	*
+	* A getter rather than a computed field so there is one walk and one stored answer; this is a read of
+	* it.
+	*/
+	get source() {
+		if (this.borrowedFrom !== void 0) return this.borrowedFrom;
+		return this.sources.length === 1 ? this.sources[0] : void 0;
+	}
+	/** The pin a copied entity came through — the `@<slug>` half of {@link copiedFrom}. */
+	get copiedThrough() {
+		const at = this.copiedFrom?.lastIndexOf("@") ?? -1;
+		return at === -1 ? void 0 : this.copiedFrom?.slice(at + 1);
+	}
+	/** The path a copied entity was taken from, as the source spells it — the half of {@link copiedFrom}
+	*  before the `@`. */
+	get copiedPath() {
+		const at = this.copiedFrom?.lastIndexOf("@") ?? -1;
+		return at === -1 ? void 0 : this.copiedFrom?.slice(0, at);
+	}
+	/** Identity is the whole qualified path (`color/brand`). */
+	get identity() {
+		return this.path;
+	}
+	/** The emergent group — everything before the last segment (`color/brand` → `color`);
+	*  `undefined` for a top-level item. Membership is never stored, only derived. */
+	get group() {
+		const slash = this.path.lastIndexOf("/");
+		return slash === -1 ? void 0 : this.path.slice(0, slash);
+	}
+	/** The bare last segment (`color/brand` → `brand`) — what a UI renders. */
+	get leaf() {
+		const slash = this.path.lastIndexOf("/");
+		return slash === -1 ? this.path : this.path.slice(slash + 1);
+	}
+	/**
+	* What a UI calls this item: its authored `label` field, else the bare
+	* {@link leaf}. Never identity — a label is metadata and two items may share
+	* one — and never a `kind:` marker, which no person should read.
+	*/
+	get displayLabel() {
+		const label = this.label?.trim();
+		return label ? label : this.leaf;
+	}
+	/**
+	* This item's declared fields as a plain bag.
+	*
+	* For a reader whose KIND is only known at runtime — a prompt catalogue walking every kind, an op
+	* form rendering whatever collection its tool names. A reader that knows the kind asks the entity
+	* class instead (`Component.get(config, path).styles`), which answers typed.
+	*
+	* Deliberately not `toJSON`: serialization is for storage and the wire, and a display surface
+	* reaching for it is how a raw-shape cast gets in. (No kind declares a field called `body`; one
+	* that did would shadow this, since fields are assigned as own properties.)
+	*/
+	get body() {
+		return this.#bag([...this.fieldKeys, ...this.computedKeys]);
+	}
+	toJSON() {
+		return this.#bag(this.fieldKeys);
+	}
+	/** The fields named by `keys`, as a plain bag. `body` and `toJSON` differ only in which keys they
+	*  ask for — the READ shape includes computeds, the WIRE shape cannot. */
+	#bag(keys) {
+		const self = this;
+		const out = {};
+		for (const key of keys) if (self[key] !== void 0) out[key] = self[key];
+		if (this.label !== void 0) out.label = this.label;
+		if (this.description !== void 0) out.description = this.description;
+		if (this.copiedFrom !== void 0) out.copiedFrom = this.copiedFrom;
+		if (this.hidden !== void 0) out.hidden = this.hidden;
+		if (this.deprecated !== void 0) out.deprecated = this.deprecated;
+		if (this.guidance !== void 0) out.guidance = this.guidance;
+		return out;
+	}
+};
+//#endregion
+export { Entity };

package/dist/framework/authoring.d.ts

@@ -0,0 +1,24 @@
+//#region src/framework/authoring.d.ts
+/**
+ * The bridge between any typed authoring surface and the live `Config`.
+ *
+ * An authoring API (like `defineComponent`) produces sugar — markers, builders, handles —
+ * that isn't the entity's stored shape. `Authored` is the one contract that lets `Config`
+ * ingest ANY such output without knowing its specifics: it exposes the target `kind`, a
+ * `toStored()` that normalizes the sugar into the entity's wire def (validated on the way
+ * in like any create), and an optional `assignPath` so a ref-handle can adopt its
+ * qualified identity at registration (enabling cross-references).
+ *
+ * New authoring APIs need only return an `Authored`; `Config.author` (see Config.ts) and
+ * the rest of the system stay unchanged.
+ */
+interface Authored {
+  readonly kind: string;
+  /** Normalize the authoring sugar into the entity's stored/wire def. */
+  toStored(): Record<string, unknown>;
+  /** Adopt the qualified path assigned at registration (so refs to this resolve). */
+  assignPath?(path: string): void;
+}
+declare function isAuthored(value: unknown): value is Authored;
+//#endregion
+export { Authored, isAuthored };

package/dist/framework/authoring.js

@@ -0,0 +1,7 @@
+//#region src/framework/authoring.ts
+function isAuthored(value) {
+	if (typeof value !== "object" && typeof value !== "function") return false;
+	return value !== null && "kind" in value && typeof value.toStored === "function";
+}
+//#endregion
+export { isAuthored };

package/dist/framework/change-hooks.d.ts

@@ -0,0 +1,119 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/change-hooks.d.ts
+/**
+ * The previous result, and the config it came from.
+ *
+ * `from` is what makes a cheap path expressible at all — a delta needs the state it is a delta from.
+ * A hook that keeps a partial result must keep the config that part came from with it, not accept
+ * `from` as the base: after one cheap run, `from` is the config the cheap run answered, which is no
+ * longer the state the kept part describes. (`stylesOnChange` carries a `base` in its value for
+ * exactly this reason — the overlay is always a delta from the sheet's own config, never from the
+ * previous edit.)
+ */
+interface LastDerived<T> {
+  readonly from: Config;
+  readonly value: T;
+}
+/**
+ * When a scheduled derivation actually runs.
+ *
+ * `'idle'` is the editor answer: after the frame the edit landed on, so the click paints first.
+ * `'sync'` runs it immediately, which is what a test and a server want. A function is anything else.
+ */
+type ChangeSchedule = 'sync' | 'idle' | ((fire: () => void) => void);
+/** One derived value that follows the config. */
+interface ChangeHook<C extends Config = Config, T = unknown> {
+  /**
+   * Every kind the derivation can reach, including ones it only touches by chasing refs. A change
+   * that moves none of them is skipped, so under-declaring means a paint that never happens —
+   * declare the same list the memo inside `run` declares.
+   */
+  readonly kinds: readonly string[];
+  /**
+   * Declared as a method rather than as a function property on purpose: method parameters are checked
+   * bivariantly, which is what lets a `ChangeHook<C, LiveStyles>` sit in a map of
+   * `ChangeHook<C, unknown>` without an `any` to paper over the variance.
+   */
+  run(config: C, last: LastDerived<T> | undefined): T | Promise<T>;
+  /** Default `'sync'`: a caller that wants the derivation off the interaction path asks for it. */
+  readonly schedule?: ChangeSchedule;
+}
+/** Where the live config comes from — a session, a store, anything that can be read and watched. */
+interface ConfigFeed<C extends Config = Config> {
+  current(): C | null;
+  subscribe(listener: () => void): () => void;
+}
+/**
+ * A set of hooks, keyed by the name their result is read under.
+ *
+ * The entries are heterogeneous — each produces its own type — so the map is stated at `unknown` and
+ * the real type is recovered at the read by {@link DerivedOf}, off the literal type of what the caller
+ * passed. That is why `run` is a method: it makes this widening legal without an `any`.
+ */
+type ChangeHookMap<C extends Config> = Record<string, ChangeHook<C, unknown>>;
+/** The result type an entry of the map produces, so `derived('styles')` is typed without a cast. */
+type DerivedOf<H> = H extends ChangeHook<Config, infer T> ? T : never;
+/** What registering a hook set hands back: the values, a way to watch them, and the teardown. */
+interface ChangeHookRun<H> {
+  /** The current value, or `undefined` before the first run has published one. */
+  derived<K extends keyof H>(name: K): DerivedOf<H[K]> | undefined;
+  /**
+   * Called on every publish, and immediately with the current value if there already is one.
+   *
+   * The replay is what makes this safe to use from an effect: a sink that only heard about future
+   * publishes would miss the derivation that ran before it mounted, and the miss looks exactly like
+   * a value that never derived. Returns the disposer.
+   */
+  onDerived<K extends keyof H>(name: K, listener: (value: DerivedOf<H[K]>) => void): () => void;
+  /** Stop watching and drop anything scheduled. Safe to call twice. */
+  dispose(): void;
+}
+interface ChangeHookOptions {
+  /**
+   * A derivation that threw. Never swallowed silently: the surface waiting on the value is showing
+   * something stale, and only the caller knows how to say so.
+   */
+  readonly onError?: (name: string, error: unknown) => void;
+}
+/**
+ * A hook must not move what it reads — the one way to use this that does not terminate.
+ *
+ * The skip test below keys on {@link sliceKeys}, which includes every attached source by identity —
+ * load-bearing, since a config that swapped a source has the same slices and different data. A hook
+ * whose published value is applied back onto the feed, and that changes one of those keys, re-triggers
+ * itself: the driver cannot tell that cycle from ordinary progress, since each run sees genuinely
+ * different keys and is genuinely not skippable. A hook that fetches sources and attaches them, for
+ * instance, mints a fresh `Config` per answer — an unbounded loop of requests, paced only by network
+ * latency.
+ *
+ * So a hook that derives a value something else writes back into the same feed owns the fixed point:
+ * it must compare against what is already there and write nothing when the answer hasn't moved.
+ * There's no guard here, because "the value changed" and "the value changed because I changed it" are
+ * the same event from this side.
+ */
+/**
+ * Run `hooks` against `feed` until disposed.
+ *
+ * Each entry gets its own coalescer, so a slow derivation cannot hold up a fast one, and each is
+ * driven by the key of what it declares it reads rather than by config identity. That distinction is
+ * the whole correctness argument:
+ *
+ *  - **Skipping.** A config change that moves none of a hook's kinds cannot change its result, so
+ *    there is nothing to run.
+ *  - **Discarding.** A result computed for a config the feed has moved past is only stale if the
+ *    newer config reads differently — and if it does, the change that superseded it will run. Keyed
+ *    on config identity instead, a result would be discarded by an edit its own kinds never saw
+ *    (a label, a description) and then never recomputed, because the follow-up run would be skipped
+ *    by the rule above. That combination is a canvas that silently stops repainting.
+ */
+declare function runChangeHooks<C extends Config, H extends ChangeHookMap<C>>({
+  feed,
+  hooks,
+  onError
+}: {
+  readonly feed: ConfigFeed<C>;
+  readonly hooks: H;
+} & ChangeHookOptions): ChangeHookRun<H>;
+//#endregion
+export { ChangeHook, ChangeHookMap, ChangeHookRun, runChangeHooks };

package/dist/framework/change-hooks.js

@@ -0,0 +1,131 @@
+import { sameSliceKeys, sliceKeys } from "./memo.js";
+import { coalesceLatest } from "./coalesce.js";
+//#region src/framework/change-hooks.ts
+/** How long an idle derivation can be held back — one frame's worth, so the canvas repaints in the
+*  same beat as the panel rather than whenever the tab next goes quiet. */
+const IDLE_TIMEOUT_MS = 48;
+function scheduler(schedule) {
+	if (typeof schedule === "function") return schedule;
+	if (schedule === "sync") return (fire) => fire();
+	return (fire) => {
+		if (typeof requestIdleCallback === "function") {
+			requestIdleCallback(fire, { timeout: IDLE_TIMEOUT_MS });
+			return;
+		}
+		setTimeout(fire, 0);
+	};
+}
+/**
+* A hook must not move what it reads — the one way to use this that does not terminate.
+*
+* The skip test below keys on {@link sliceKeys}, which includes every attached source by identity —
+* load-bearing, since a config that swapped a source has the same slices and different data. A hook
+* whose published value is applied back onto the feed, and that changes one of those keys, re-triggers
+* itself: the driver cannot tell that cycle from ordinary progress, since each run sees genuinely
+* different keys and is genuinely not skippable. A hook that fetches sources and attaches them, for
+* instance, mints a fresh `Config` per answer — an unbounded loop of requests, paced only by network
+* latency.
+*
+* So a hook that derives a value something else writes back into the same feed owns the fixed point:
+* it must compare against what is already there and write nothing when the answer hasn't moved.
+* There's no guard here, because "the value changed" and "the value changed because I changed it" are
+* the same event from this side.
+*/
+/**
+* Run `hooks` against `feed` until disposed.
+*
+* Each entry gets its own coalescer, so a slow derivation cannot hold up a fast one, and each is
+* driven by the key of what it declares it reads rather than by config identity. That distinction is
+* the whole correctness argument:
+*
+*  - **Skipping.** A config change that moves none of a hook's kinds cannot change its result, so
+*    there is nothing to run.
+*  - **Discarding.** A result computed for a config the feed has moved past is only stale if the
+*    newer config reads differently — and if it does, the change that superseded it will run. Keyed
+*    on config identity instead, a result would be discarded by an edit its own kinds never saw
+*    (a label, a description) and then never recomputed, because the follow-up run would be skipped
+*    by the rule above. That combination is a canvas that silently stops repainting.
+*/
+function runChangeHooks({ feed, hooks, onError }) {
+	const values = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Map();
+	const requests = [];
+	const cancels = [];
+	let disposed = false;
+	for (const [name, hook] of Object.entries(hooks)) {
+		let last;
+		let lastKeys;
+		const publish = (value, from) => {
+			last = {
+				from,
+				value
+			};
+			values.set(name, value);
+			for (const listener of listeners.get(name) ?? []) listener(value);
+		};
+		const derive = coalesceLatest({
+			schedule: scheduler(hook.schedule ?? "sync"),
+			run: async (config) => {
+				const keys = sliceKeys({
+					config,
+					kinds: hook.kinds
+				});
+				if (lastKeys && sameSliceKeys({
+					before: lastKeys,
+					after: keys
+				})) return;
+				let value;
+				try {
+					value = await hook.run(config, last);
+				} catch (error) {
+					onError?.(name, error);
+					return;
+				}
+				const live = feed.current();
+				if (disposed || !live || !sameSliceKeys({
+					before: keys,
+					after: sliceKeys({
+						config: live,
+						kinds: hook.kinds
+					})
+				})) return;
+				lastKeys = keys;
+				publish(value, config);
+			}
+		});
+		requests.push(derive);
+		cancels.push(derive.cancel);
+	}
+	const request = () => {
+		const config = feed.current();
+		if (!config || disposed) return;
+		for (const derive of requests) derive(config);
+	};
+	request();
+	const unsubscribe = feed.subscribe(request);
+	return {
+		derived: (name) => values.get(String(name)),
+		onDerived: (name, listener) => {
+			const key = String(name);
+			let set = listeners.get(key);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				listeners.set(key, set);
+			}
+			set.add(listener);
+			if (values.has(key)) listener(values.get(key));
+			return () => {
+				set?.delete(listener);
+			};
+		},
+		dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			unsubscribe();
+			for (const cancel of cancels) cancel();
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+export { runChangeHooks };

package/dist/framework/changes.d.ts

@@ -0,0 +1,88 @@
+import { StampedPatch } from "./overlay.js";
+import { Config } from "./Config.js";
+
+//#region src/framework/changes.d.ts
+/** What a patch addresses: one item, one group node, or a kind's order. */
+type ChangeTarget = 'item' | 'group' | 'order';
+interface Change {
+  /** The pending patch's id — what `ConfigSession.drop` takes. */
+  readonly id: string;
+  /** The gesture that wrote this patch alongside others, when it was one of several. */
+  readonly changeset?: string;
+  readonly kind: string;
+  readonly operation: string;
+  readonly target: ChangeTarget;
+  /** The item or group path the patch addresses. Absent for a reorder, which names no one path. */
+  readonly path?: string;
+  /** Where a rename moved the path. */
+  readonly to?: string;
+  /**
+   * The dotted path within the body the patch wrote, when it wrote one place: a partial write's
+   * single key (`modifiers.dark`), or a sub-op's member (`layers.root`). Absent when the patch wrote
+   * the whole body or several fields, in which case `before` and `after` are bodies.
+   */
+  readonly field?: string;
+  /** The value on the base. `undefined` when the path did not exist there. */
+  readonly before: unknown;
+  /** The value on the draft. `undefined` when the path no longer exists. */
+  readonly after: unknown;
+}
+/** The base as a config of its own — the branch with no draft applied. */
+declare function baseOf(config: Config): Config;
+/** The value a change addresses in one config — the body, or the field within it. */
+declare function changeValueAt({
+  config,
+  change,
+  side
+}: {
+  config: Config;
+  change: Pick<Change, 'kind' | 'path' | 'field' | 'target'>;
+  side: 'before' | 'after';
+}): unknown;
+/** One pending patch as a change, with its values read off `base` and `draft`. */
+declare function changeOf(entry: StampedPatch, {
+  base,
+  draft
+}: {
+  base: Config;
+  draft: Config;
+}): Change;
+/** Every pending patch of `config` as a change, in draft order. */
+declare function changesOf(config: Config, base?: Config): Change[];
+/**
+ * What a set of changes on one entity did, in words — the line a card carries under the entity's
+ * name. `entity` is the path the changes are grouped under, which may be a prefix of what each
+ * change addresses (a token group over its tokens) or the item itself (a component).
+ */
+declare function summarizeChanges({
+  config,
+  kind,
+  entity,
+  changes
+}: {
+  config: Config;
+  kind: string; /** The grouping path; absent when the changes are a kind's order. */
+  entity: string | undefined;
+  changes: readonly Change[];
+}): string;
+/**
+ * A body summarized as what it contains — the cell for a created or deleted container, where the
+ * body itself is too much to show. `undefined` for a value that is not a body.
+ *
+ * `config` is the one the body was read from, since a group's members are counted there.
+ */
+declare function describeBody({
+  config,
+  kind,
+  path,
+  target,
+  value
+}: {
+  config: Config;
+  kind: string;
+  path: string;
+  target: ChangeTarget;
+  value: unknown;
+}): string | undefined;
+//#endregion
+export { Change, ChangeTarget, baseOf, changeOf, changeValueAt, changesOf, describeBody, summarizeChanges };