@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/inline-sources.d.ts

@@ -0,0 +1,49 @@
+import { Ref } from "./utils/refs.js";
+//#region src/framework/inline-sources.d.ts
+/**
+ * One value, with every ref through `slug` — or through any source when `slug` is omitted — replaced by
+ * what it resolves to.
+ *
+ * **Resolution hops configs.** A source's own value may be a ref into a third system, under a slug only
+ * that source declares, so the recursion continues in the config that answered rather than in ours, and
+ * `configFor` is what knows which one that is. Recursing against our own config would leave a ref naming
+ * a slug we never declared — the chained-link case in `inline-sources.test.ts`.
+ *
+ * The recursion takes all sources even when the top-level call is scoped to one, because a value about
+ * to become ours must not keep pointing anywhere.
+ */
+/**
+ * What to do with a sourced ref that names something with no value — a component, a `file`, a style
+ * property. There is nothing to substitute for one, so it needs its own answer, and which answer
+ * depends on whether the pin survives the edit.
+ *
+ * **It survives** for publishing and for reading a repo-local chain. The seam stays, so the ref stays:
+ * `keepIdentityRefs`. A borrowed component's `file` has to keep naming the system that owns the
+ * implementation or nothing can find it.
+ *
+ * **It is dropped** when a whole source is being taken in. Keeping the ref would dangle it the moment
+ * the declaration goes, and `delete` would refuse while the ref is still a referrer. It mustn't be
+ * refused either, because what it names is usually about to become this config's own — the same walk
+ * materializes it. So the ref is adopted, requalified at the local entity, and only a target that lands
+ * nowhere local is refused. See {@link adoptedRefs}.
+ */
+interface InlineOptions {
+  readonly keepIdentityRefs?: boolean;
+  /**
+   * Called for a ref that can be neither inlined nor requalified, in place of the refusal. The ref is
+   * left as it is so the walk reaches every other ref. A plan sets this to name every such ref rather
+   * than the first.
+   */
+  readonly onUnadoptable?: (ref: Ref) => void;
+  /**
+   * Where each thing borrowed through the slug will live once the pin is gone, as
+   * `style-property:bg@ds` → `style-property:bg`.
+   *
+   * Derived, not a caller's choice: whoever is dropping the pin builds it ({@link adoptedRefs}) and
+   * the walk threads it. It is in the options bag rather than a parameter because the walk is
+   * recursive and every hop needs it; its presence is what says "the seam is going".
+   */
+  readonly adopted?: ReadonlyMap<string, string>;
+}
+//#endregion
+export { InlineOptions };

package/dist/framework/inline-sources.js

@@ -0,0 +1,388 @@
+import { rejectData } from "./rejection.js";
+import { MINTED, collectRefs, entityRefOf, isRef, kindOf, pathOf, ref, rewriteRefs, sourceOf } from "./utils/refs.js";
+import { kindBorrowable } from "./registry.js";
+//#region src/framework/inline-sources.ts
+/**
+* Why a sourced ref with no value could not be carried across a dropped pin.
+*
+* Two different dead ends, and telling them apart is the whole point: the advice for one is a real
+* Next step and the advice for the other is impossible, so a single sentence covering both sends half
+* its readers somewhere `link` refuses to go.
+*
+* **A borrowable kind** — a `style-property`, a component. The ref can become ours, but only by being
+* copied first, so `linked-system/copy` is the fix. What this must not say is that we have no entity
+* at the path: we may well have one, and it is simply not the entity this ref names. A local `bg`
+* that happens to share a name with theirs is a different declaration, and quietly repointing at it
+* would change what every callsite means.
+*
+* **A kind that is not borrowable** — a `file`, which is how a borrowed component's implementation
+* travels. `link` refuses these by design (they belong to the system that holds them), so "link it
+* too" is advice with nowhere to go. The honest next step is the other end: the borrow that pulled the
+* file in is what has to be detached or dropped.
+*/
+function unadoptableMessage({ value, config, slug }) {
+	const kind = kindOf(value);
+	const path = pathOf(value);
+	const source = config.sourceFor(slug);
+	if (!kindBorrowable(config.entityOf(kind), {
+		config,
+		source
+	})) return `Cannot inline "${value.__ref}": ${kind} entries are not borrowable — they belong to "${slug}", and dropping the pin would leave this one unreachable. Detach what borrows it first (a borrowed component's implementation travels as its ${kind}), or drop what references it.`;
+	return `Cannot inline "${value.__ref}": nothing there has a value to keep, and this config has not taken over "${slug}"'s ${kind} "${path}" — a local ${kind} at the same path is a different declaration, so pointing at it would change what every callsite means. Link that ${kind} too, then break the link — or drop what references it.`;
+}
+function inlineSourcedRefs(value, config, slug, options) {
+	if (isRef(value)) {
+		const source = sourceOf(value);
+		if (source === void 0) return value;
+		if (slug !== void 0 && source !== slug) return value;
+		const owner = config.configFor(value);
+		if (!owner) rejectData(`Cannot inline "${value.__ref}": link "${source}" has no source attached and the artifact recorded nothing for it. Rebuild with the link installed before breaking it.`);
+		const target = config.resolveRef(value);
+		const body = target?.toJSON();
+		if (!target && !declaresGroup(owner, value)) rejectData(`Cannot inline "${value.__ref}": "${source}" has no ${kindOf(value)} at "${pathOf(value)}". A pin is exact, so this is a ref into a version that does not declare it.`);
+		if (body?.value === void 0) {
+			if (options?.keepIdentityRefs) return value;
+			const adopted = options?.adopted?.get(entityRefOf(value.__ref));
+			if (adopted !== void 0) return rewriteRefs(value, entityRefOf(value.__ref), adopted);
+			if (config.entityOf(kindOf(value))?.authoredRefs === false) return;
+			if (options?.onUnadoptable) {
+				options.onUnadoptable(value);
+				return value;
+			}
+			rejectData(unadoptableMessage({
+				value,
+				config,
+				slug: source
+			}));
+		}
+		return inlineSourcedRefs(body.value, owner, void 0, options);
+	}
+	if (Array.isArray(value)) return value.map((item) => inlineSourcedRefs(item, config, slug, options));
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [key, nested] of Object.entries(value)) out[key] = inlineSourcedRefs(nested, config, slug, options);
+		return out;
+	}
+	return value;
+}
+/**
+* One entity's body, with a borrowed entity taken whole rather than field by field.
+*
+* A ref names an entity, so borrowing one takes everything it declares: a token's conditional values come
+* with its default, the way they came together in the source. Inlining only `value` is a silent partial
+* copy — a colour that flips in dark mode arrives flat, and nothing says so.
+*
+* The merge is the borrower's fields over the target's, the same `{ ...base, ...override }` rule
+* `resolveDerived` uses for a derived member, so a reader learns it once. Declaring your own `overrides`
+* therefore replaces theirs rather than layering on them, which is the plain reading of a field you did
+* state.
+*
+* Only the primary field position is treated this way. A ref elsewhere in a body — a modifier's
+* `selector`, a canvas role's `component` — is a pointer to a thing rather than a borrowing of it, so it
+* keeps the plain value substitution.
+*
+* The kind says which field that is (`entry.primaryField`), the same field `link` writes a bare ref into.
+* Reading `body.value` instead would name the primary field of `token` and of nothing else, so a borrowed
+* `style-property`, whose primary is `properties`, would miss this path, fall through to the plain
+* substitution and throw "nothing there has a value to keep" — making any system that borrows a
+* non-token entity impossible to publish or take in. See
+* `.claude/rules/config-framework-kind-agnostic.md`.
+*/
+function inlineWholeEntity({ body, kind, config, slug, options }) {
+	const primary = config.entityOf(kind)?.primaryField;
+	const pointer = primary === void 0 ? void 0 : body[primary];
+	if (primary !== void 0 && isRef(pointer) && wants(pointer, slug)) {
+		const target = config.resolveRef(pointer);
+		const owner = config.configFor(pointer);
+		if (target && owner) {
+			const { [primary]: theirValue, ...theirFields } = borrowWhole({
+				fields: target.toJSON(),
+				kind,
+				source: owner
+			});
+			const { [primary]: _ourRef, ...ourFields } = body;
+			const merged = {
+				...inlineSourcedRefs(theirFields, owner, void 0, options),
+				...inlineSourcedRefs(ourFields, config, slug, options),
+				[primary]: inlineSourcedRefs(theirValue, owner, void 0, options)
+			};
+			assertCarriedRefsResolve(merged, config, pointer.__ref);
+			return merged;
+		}
+	}
+	return inlineSourcedRefs(body, config, slug, options);
+}
+/**
+* A borrowed entity's fields, following the source's own aliases to the bottom.
+*
+* Their `color/primary` may alias their `spectrum/gray/0`, and the alias target is often where the
+* interesting fields live: a semantic token points at a palette token, and the palette token carries the
+* light and dark values. Stopping at the first hop leaves a ref to one of their entities sitting in our
+* body, pointing at nothing of ours, and drops the conditional values with it.
+*
+* Each hop merges the way the borrow itself does — the outer entity's fields over the inner's — so a
+* semantic token stating its own `overrides` keeps them, and one stating none inherits the palette
+* Token's. The primary field always comes from the bottom, which is what an alias chain is for.
+*
+* Each hop asks the kind it is in for that field rather than assuming the chain stays one kind: an alias
+*/
+function borrowWhole({ fields, kind, source, seen = [] }) {
+	const primary = source.entityOf(kind)?.primaryField;
+	if (primary === void 0) return fields;
+	const alias = fields[primary];
+	if (!isRef(alias) || sourceOf(alias) !== void 0) return fields;
+	const innerKind = kindOf(alias);
+	const inner = source.resolve(innerKind, pathOf(alias));
+	if (!inner) return fields;
+	if (seen.includes(alias.__ref)) rejectData(`Cannot inline through "${alias.__ref}": the source aliases in a cycle (${[...seen, alias.__ref].join(" → ")}).`);
+	const resolved = borrowWhole({
+		fields: inner.toJSON(),
+		kind: innerKind,
+		source,
+		seen: [...seen, alias.__ref]
+	});
+	const innerPrimary = source.entityOf(innerKind)?.primaryField ?? primary;
+	return {
+		...resolved,
+		...fields,
+		[primary]: resolved[innerPrimary]
+	};
+}
+/**
+* Every local ref in a carried body has to resolve here, or the borrowed entity depends on something this
+* Config doesn't have.
+*
+* A borrowed entity arrives whole, and what it brought may point at things: a token's conditional value
+* names the modifier it varies under, and other kinds name other kinds. Those refs were written in the
+* source's vocabulary and now live in ours, so they resolve against us. That is the answer a consumer
+* wants — a token you pulled in flips under your dark mode — and an obligation at the same time.
+*
+* The failure is loud and names the fix. A dangling `on` would emit a conditional value under no
+* condition, reading as "this colour is always that" rather than "this colour changes in dark mode", and
+* nothing downstream could tell the difference. That is the class this refuses: a borrowed entity that
+* silently behaves like a lesser version of itself.
+*
+* A sourced ref is skipped. It still names the source's world, and it either inlined already or belongs
+* to a link we aren't resolving.
+*/
+function assertCarriedRefsResolve(fields, config, borrowed) {
+	for (const target of collectRefs(fields)) {
+		if (sourceOf(target) !== void 0) continue;
+		const kind = kindOf(target);
+		const name = pathOf(target);
+		if (config.resolve(kind, name)) continue;
+		rejectData(`Cannot inline "${borrowed}": it depends on ${kind} "${name}", which this config does not declare. A borrowed entity comes whole, and what it brought resolves against YOUR entities of the same name — so declare "${name}", or state your own value for this one to replace what it carried.`);
+	}
+}
+/** Whether `owner` declares a group at the path this ref names — the half of "does the target exist"
+*  that `resolveRef` cannot answer, because it narrows to an item. */
+function declaresGroup(owner, value) {
+	return owner.groups(kindOf(value)).some((group) => group.path === pathOf(value));
+}
+/** Whether this ref is one the caller asked to inline — any source, or the one named. Takes the ref
+*  either way it is spelled, because `collectRefs` hands back the string form. */
+function wants(value, slug) {
+	const source = sourceOf(value);
+	return source !== void 0 && (slug === void 0 || source === slug);
+}
+/**
+* Whether a body holds a ref this walk is asked to take — the cheap prefilter on the way to
+* {@link rewrittenBody}, and the reason a detach doesn't walk entities it has no business touching.
+*
+* It answers "is there anything here for this walk", not "will this walk change anything". The second
+* question is the one a write depends on, and only running the walk answers it — a ref can be present
+* and deliberately kept. So this is the skip, not the decision.
+*
+* Deep, because the walk is: a conditional value that varies under a borrowed modifier holds its ref a
+* level down, and a shallow test would call that item local and leave it pointing at a dropped pin.
+*/
+function holdsWantedRef(body, slug) {
+	return collectRefs(body).some((target) => wants(target, slug));
+}
+/**
+* Whether two bodies say the same thing — the test that decides whether a walk wrote anything.
+*
+* Structural, because an identity check cannot be: `inlineSourcedRefs` allocates a fresh object for
+* every object it visits, so `!==` reports "changed" for every body it touched. What it does not
+* reallocate is a leaf it decided to leave alone, which is why `Object.is` still short-circuits most
+* of the walk.
+*/
+function sameBody(left, right) {
+	if (Object.is(left, right)) return true;
+	if (Array.isArray(left) || Array.isArray(right)) return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((item, index) => sameBody(item, right[index]));
+	if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+	const theirs = right;
+	const ours = Object.entries(left);
+	return ours.length === Object.keys(theirs).length && ours.every(([key, value]) => key in theirs && sameBody(value, theirs[key]));
+}
+/**
+* One body walked, or `undefined` when the walk gave back what it was handed — the whole of "does this
+* Entity need an `update`?", and the guard every write site here goes through.
+*
+* {@link holdsWantedRef} is a prefilter and cannot be the whole answer, because holding a sourced ref
+* and being rewritten are not the same question. `keepIdentityRefs` is on for publishing and for every
+* scoped detach — the pin survives both — so a row whose only tie to the link is a ref at something
+* with no value (a component's `file`, a `style-property` a prop names) passes the prefilter, keeps its
+* ref exactly as it was by design, and is left byte-identical.
+*
+* Writing the `update` anyway is not harmless in the snapshot's sense of harmless: the row lands in the
+* branch's draft and in the changes panel claiming an edit nobody made, and reports a detach that
+* detached nothing as a success. It is the same thing the prefilter exists to prevent, one step later.
+*/
+function rewrittenBody({ body, kind, config, slug, options }) {
+	if (!holdsWantedRef(body, slug)) return void 0;
+	const inlined = inlineWholeEntity({
+		body,
+		kind,
+		config,
+		slug,
+		options
+	});
+	return sameBody(body, inlined) ? void 0 : inlined;
+}
+/**
+* Every item and group body of `config`, rewritten by {@link inlineSourcedRefs}.
+*
+* `linked-system` is skipped: the pins are not values that inline, and they stay — provenance is
+* information a consumer's tooling still wants for attribution and upgrade detection. Deleting one is
+* the pin's own `delete`, once nothing refers through it.
+*
+* Groups are walked as well as items. A group body carries fields like any entity, so a ref hiding in
+* one would otherwise survive a walk that only visited items — and "nothing sourced survives" is the
+* guarantee, not "nothing sourced survives in the places we remembered to look".
+*/
+/**
+* Where each thing borrowed through `slug` will live once the pin is gone — `style-property:bg@ds` →
+* `style-property:bg`.
+*
+* The third answer for a ref that names an identity rather than a value, and the one that makes "link
+* everything, then break the link" work. A borrowed component declares a `styleProperty` prop pointing
+* at `style-property:bg@ds`, and taking the source in materializes their style-property locally. So the
+* pointer is neither a seam to keep, since there will be no pin, nor a value to inline, since a
+* style-property has none. It is a pointer at something that is now ours.
+*
+* Read before anything moves, because a borrowed item is a stored pointer and materializing it is what
+* erases the pointer this map is built from.
+*
+* Two ways a borrow lands somewhere, and the map needs both:
+*
+*  - an item, whose local path is whatever this config filed it under. `link` takes a `to`, so their
+*    `bg` may be our `theirBg`, and path equality would point at an unrelated entity of ours.
+*  - a folder, which may have a group node pointing through the pin, or may be emergent from members
+*    that each do. The second has nothing stored to read, so the local group's own path answers, and a
+*    ref at `token:color@ds` becomes our `token:color`.
+*
+* A target in neither is left out deliberately: the refusal downstream names it, which is the right
+* outcome for borrowing a component without the style-property it uses.
+*/
+function adoptedRefs(config, slug) {
+	const moved = /* @__PURE__ */ new Map();
+	for (const kind of config.ownedKinds()) {
+		for (const item of config.list(kind)) {
+			const body = config.storedBody(kind, item.path);
+			if (!isRef(body) || sourceOf(body) !== slug) continue;
+			moved.set(entityRefOf(body.__ref), ref(kind, item.path).__ref);
+		}
+		for (const group of config.groups(kind)) {
+			const local = ref(kind, group.path).__ref;
+			moved.set(ref(kind, group.path, slug).__ref, local);
+			const pointer = group.meta.ref;
+			if (isRef(pointer) && sourceOf(pointer) === slug) moved.set(entityRefOf(pointer.__ref), local);
+		}
+	}
+	return moved;
+}
+function inlineAllSources(config, slug, options) {
+	const walk = slug === void 0 ? options : {
+		...options,
+		adopted: adoptedRefs(config, slug)
+	};
+	const materialized = config.withMaterializedExtensions({ slug });
+	let next = materialized;
+	for (const kind of materialized.ownedKinds()) {
+		if (materialized.entityOf(kind)?.sourceIdentity) continue;
+		for (const item of materialized.list(kind)) {
+			const data = rewrittenBody({
+				body: item.toJSON(),
+				kind,
+				config: materialized,
+				slug,
+				options: walk
+			});
+			if (data === void 0) continue;
+			next = next.apply({
+				kind,
+				operation: "update",
+				path: item.path,
+				data
+			});
+		}
+		for (const group of materialized.groups(kind)) {
+			const inlined = detachedGroupMeta({
+				config: materialized,
+				kind,
+				groupPath: group.path,
+				slug,
+				options: walk
+			});
+			if (!inlined) continue;
+			next = next.apply({
+				kind,
+				operation: "group-update",
+				path: group.path,
+				data: inlined
+			});
+		}
+	}
+	return next;
+}
+/**
+* A group's body with its borrow through `slug` dissolved — the pointer dropped, and what it was
+* inheriting kept as its own.
+*
+* A group's `ref` is the one sourced ref that must not be inlined, and the difference is what it names.
+* A ref in a value position stands in for a value; this names a folder, and a folder has no value to
+* collapse to. Handed to {@link inlineSourcedRefs} it takes the "nothing there has a value to keep"
+* throw, so a config holding a linked group can't be unlinked or published at all.
+*
+* Dropping it is also right rather than a way around the throw. Being borrowed is derived for a folder,
+* from every member agreeing on one slug, so once the members are local the pointer is a claim that has
+* stopped being true, and leaving it would report the folder as linked to a system nothing else draws
+* through.
+*
+* `ref: null` rather than an omission, because a `group-update` merges over the stored body and a key
+* left out is a key left alone. The label comes from `Config.groups`, which has already merged the
+* source's in, and reading the inherited meta is what keeps "Palette" on the folder after the link that
+* supplied it is gone.
+*
+* `undefined` when the folder draws through nothing this walk takes, including the ordinary case of an
+* emergent folder with no stored node, which a `group-update` would otherwise mint out of nothing for
+* every prefix of every kind.
+*/
+/**
+* A folder's meta with its borrow dropped — the pointer, and the mark that was only true while it
+* pointed.
+*
+* A folder the build minted is minted because it points through a link, so once the pointer is gone
+* the mark is a claim that has stopped being true. It also has to go for a mechanical reason: no kind
+* declares `__minted` as a group field, so a `group-update` carrying it is refused outright.
+*/
+function withoutPointer(meta) {
+	const { ref: _dropped, [MINTED]: _wasMinted, ...kept } = meta;
+	return kept;
+}
+function detachedGroupMeta({ config, kind, groupPath, slug, options }) {
+	const meta = config.groups(kind).find((group) => group.path === groupPath)?.meta ?? {};
+	const pointer = meta.ref;
+	if (!isRef(pointer) || !wants(pointer, slug)) {
+		if (!holdsWantedRef(meta, slug)) return void 0;
+		const inlined = inlineSourcedRefs(meta, config, slug, options);
+		return sameBody(meta, inlined) ? void 0 : inlined;
+	}
+	return {
+		...inlineSourcedRefs(withoutPointer(meta), config, slug, options),
+		ref: null
+	};
+}
+//#endregion
+export { inlineAllSources };

package/dist/framework/layer-styles.d.ts

@@ -0,0 +1,25 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/layer-styles.d.ts
+/** Whether every prop a rule names holds the value it asks for. Compared as strings, because a
+ *  condition is canonicalized into the rule's key and a variant value is a string there. */
+declare function ruleApplies(when: Record<string, unknown> | null | undefined, state: Record<string, unknown>): boolean;
+interface LayerStyleOptions {
+  /**
+   * Modifiers to treat as active — `['hover']` for a matrix column showing the hover state.
+   *
+   * A modifier's styles live in a `_<modifier>` block inside a layer's bag, which is where the
+   * stylesheet reads them from too. Forcing one flattens that block up into the bag, so a surface sees
+   * the values that state actually paints rather than the block itself.
+   */
+  readonly forced?: readonly string[];
+}
+/**
+ * The resolved style bag per layer, for the props an instance was given.
+ *
+ * Layers with nothing to say are absent rather than empty, so a caller can tell "no styling" from
+ * "styled with nothing".
+ */
+declare function layerStyles(config: Config, path: string, props?: Record<string, unknown>, options?: LayerStyleOptions): Record<string, Record<string, unknown>>;
+//#endregion
+export { LayerStyleOptions, layerStyles, ruleApplies };

package/dist/framework/layer-styles.js

@@ -0,0 +1,49 @@
+import { isRef, refLeaf } from "./utils/refs.js";
+import { authoredBag } from "./projections.js";
+//#region src/framework/layer-styles.ts
+/** Whether every prop a rule names holds the value it asks for. Compared as strings, because a
+*  condition is canonicalized into the rule's key and a variant value is a string there. */
+function ruleApplies(when, state) {
+	return Object.entries(when ?? {}).every(([prop, value]) => String(state[prop]) === String(refLeaf(value)));
+}
+/**
+* Merge a bag over another, flattening any forced modifier block as it goes.
+*
+* The bag arrives already read back through {@link authoredBag}, so what's merged is the leaf an
+* author wrote rather than the ref the bag stores — this projection answers "what is this layer styled
+* with" for a panel and a matrix cell, and a picker's options are leaves.
+*/
+function mergeBag(into, bag, forced) {
+	for (const [key, value] of Object.entries(bag)) {
+		const modifier = key.startsWith("_") ? key.slice(1) : void 0;
+		if (modifier && value && typeof value === "object" && !isRef(value)) {
+			if (forced.includes(modifier)) mergeBag(into, value, forced);
+			else into[key] = value;
+			continue;
+		}
+		into[key] = value;
+	}
+}
+/**
+* The resolved style bag per layer, for the props an instance was given.
+*
+* Layers with nothing to say are absent rather than empty, so a caller can tell "no styling" from
+* "styled with nothing".
+*/
+function layerStyles(config, path, props = {}, options = {}) {
+	const { styles = {}, defaultProps = {} } = config.resolve("component", path)?.toJSON() ?? {};
+	const state = {
+		...defaultProps,
+		...props
+	};
+	const forced = options.forced ?? [];
+	const applicable = Object.values(styles).filter((rule) => ruleApplies(rule.when, state)).sort((left, right) => Object.keys(left.when ?? {}).length - Object.keys(right.when ?? {}).length);
+	const out = {};
+	for (const rule of applicable) for (const [layer, bag] of Object.entries(rule.layers ?? {})) {
+		out[layer] ??= {};
+		mergeBag(out[layer], authoredBag(config, bag ?? {}), forced);
+	}
+	return out;
+}
+//#endregion
+export { layerStyles, ruleApplies };

package/dist/framework/memo.d.ts

@@ -0,0 +1,48 @@
+import { Snapshot } from "./snapshot.js";
+
+//#region src/framework/memo.d.ts
+/** The structural shape a memo needs — any config-like that can produce its snapshot. Structural
+ *  rather than an import of `Config`, which would be a cycle (Config memoizes through this). */
+interface HasSnapshot {
+  readonly snapshot: Snapshot;
+  /**
+   * The live source a LINKED kind reads through, when there is one.
+   *
+   * Optional, so a bare `{ snapshot }` is still a valid config-like — but a real `Config` must
+   * implement it, because a linked kind's data isn't in the consumer's snapshot at all.
+   */
+  linkedSource?(kind: string): {
+    readonly config: HasSnapshot;
+  } | undefined;
+  /**
+   * The linked SOURCES attached to this config, in a stable order.
+   *
+   * Part of every key, and not optional to correctness: a source's entities live in the source's
+   * snapshot, so a config that swapped one — hydrating with `{ sources }`, re-attaching after a
+   * republish — has the same slices and different data. Keyed on the source configs themselves, a
+   * derivation that reads a borrowed value recomputes when the source it read from changes.
+   */
+  attachedSources?(): readonly object[];
+}
+/**
+ * Wrap `compute` in a cache keyed on the identity of the `kinds` slices it reads.
+ *
+ * Entries are held in a chain of `WeakMap`s — one level per kind — so a cached result dies with the
+ * snapshot slices that produced it. Nothing to invalidate, and no version arithmetic.
+ *
+ * ```ts
+ * const tokenViews = createSliceMemo({
+ *   kinds: ['token', 'modifier'],
+ *   compute: (config: Config) => …,
+ * });
+ * ```
+ */
+declare function createSliceMemo<C extends HasSnapshot, T>({
+  kinds,
+  compute
+}: {
+  readonly kinds: readonly string[];
+  readonly compute: (config: C) => T;
+}): (config: C) => T;
+//#endregion
+export { HasSnapshot, createSliceMemo };

package/dist/framework/memo.js

@@ -0,0 +1,84 @@
+//#region src/framework/memo.ts
+/** Distinguishes "cached `undefined`" from "not cached" without an extra `has` lookup per level. */
+const MISS = Symbol("miss");
+/**
+* The level a cached value hangs off, so every slice is an interior key.
+*
+* Chains vary in length — one config links a kind and another doesn't — and without a terminator a
+* short chain would read its value where a long one expects another level.
+*/
+const RESULT = Object.freeze({});
+/**
+* Every slice a computation reads for one kind: this config's, then its source's, and so on down
+* the link chain.
+*
+* A linked kind reads THROUGH — `Config.list(kind)` returns the source's items — so the consumer's
+* own slice is the wrong thing to key on by itself. It never changes (the consumer owns nothing of
+* that kind), so a memo keyed on it alone caches the source's first answer forever.
+*/
+function sliceChain(config, kind, acc, seen) {
+	if (seen.has(config)) return;
+	seen.add(config);
+	acc.push(config.snapshot.slice(kind));
+	const source = config.linkedSource?.(kind)?.config;
+	if (source) sliceChain(source, kind, acc, seen);
+}
+/**
+* The identity of the data a computation over `kinds` reads: every attached source, then each kind's
+* slice chain.
+*
+* Exported because two things need it and they must agree. A memo hangs its cache off these objects;
+* a change hook compares this run's against the last one's to decide whether the derivation can be
+* skipped (`runChangeHooks`). Two statements of "what this computation reads" would drift, and the
+* failure is silent both ways — a stale cache hit, or a paint that never happens.
+*
+* Sources come first: they qualify every slice below them, and a config with none contributes nothing.
+*/
+function sliceKeys({ config, kinds }) {
+	const keys = [...config.attachedSources?.() ?? []];
+	for (const kind of kinds) sliceChain(config, kind, keys, /* @__PURE__ */ new Set());
+	return keys;
+}
+/** Whether two key lists name the same data — the skip test for a change hook. */
+function sameSliceKeys({ before, after }) {
+	return before.length === after.length && before.every((key, index) => key === after[index]);
+}
+/**
+* Wrap `compute` in a cache keyed on the identity of the `kinds` slices it reads.
+*
+* Entries are held in a chain of `WeakMap`s — one level per kind — so a cached result dies with the
+* snapshot slices that produced it. Nothing to invalidate, and no version arithmetic.
+*
+* ```ts
+* const tokenViews = createSliceMemo({
+*   kinds: ['token', 'modifier'],
+*   compute: (config: Config) => …,
+* });
+* ```
+*/
+function createSliceMemo({ kinds, compute }) {
+	if (kinds.length === 0) throw new Error("createSliceMemo needs at least one kind — a computation that reads nothing has nothing to key on");
+	const root = /* @__PURE__ */ new WeakMap();
+	return (config) => {
+		const keys = sliceKeys({
+			config,
+			kinds
+		});
+		let level = root;
+		for (const key of keys) {
+			let next = level.get(key);
+			if (!next) {
+				next = /* @__PURE__ */ new WeakMap();
+				level.set(key, next);
+			}
+			level = next;
+		}
+		const cached = level.has(RESULT) ? level.get(RESULT) : MISS;
+		if (cached !== MISS) return cached;
+		const value = compute(config);
+		level.set(RESULT, value);
+		return value;
+	};
+}
+//#endregion
+export { createSliceMemo, sameSliceKeys, sliceKeys };