@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/utils/field-path.js

@@ -0,0 +1,136 @@
+//#region src/framework/utils/field-path.ts
+/**
+* A write's ADDRESS, carried in the delta's KEY.
+*
+* `update` / `sub-update` take a partial whose keys are FIELD PATHS. One rule covers every depth:
+* **the value replaces whatever the key addresses**, and `null` removes it.
+*
+*   { layers: {…} }                 →  replaces the whole `layers` field
+*   { 'layers.root.bg': 'hover' }   →  replaces one leaf, touching nothing else
+*   { 'layers.root.bg': null }      →  removes that leaf
+*   { 'layers.root': null }         →  removes the whole bag
+*
+* So depth is something the CALLER states rather than something the verb implies — Firestore's
+* `update()` rule, and the reason there is no second "deep" verb. A deep write and a whole-field
+* write differ only in how many segments the key has.
+*
+* The nested-object delta this replaces could not tell those two apart. Merged recursively,
+* `{ value: { warning: {} } }` is both "add a value called `warning`" and "empty the one that is
+* already there", and the merge had to GUESS — it pruned, so adding a variant value applied cleanly
+* and stored nothing: a silent no-op with no rejection to explain it. Under an address there is
+* nothing to guess, because setting and removing are different calls rather than different-looking
+* data.
+*
+* The one thing an address cannot spell is a member key that itself contains a dot (`spacing.2`,
+* which nothing names today — paths separate with `/`). Such a key is reachable by `sub-upsert`,
+* which addresses it whole.
+*/
+/** A JSON object — not an array, not a class instance. */
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* The segments a delta key addresses.
+*
+* A key is a PATH when it contains a `.` AND its first segment names a field of the thing being
+* written — decidable off the target's own schema, so it is a rule rather than a guess. A key that
+* fails either test addresses one field, dot and all, which is what keeps a literal dotted key
+* writable at the depth it lives at.
+*/
+function pathSegments(key, isField) {
+	const dot = key.indexOf(".");
+	if (dot === -1) return [key];
+	return isField(key.slice(0, dot)) ? key.split(".") : [key];
+}
+/**
+* A partial over one section of an item, as the item-level delta that writes it: every key prefixed by
+* the section's field, so `{ prefix: 'acme' }` on `css` becomes `{ 'css.prefix': 'acme' }`. A value that
+* is not a record writes the section whole.
+*/
+function sectionDelta(field, data) {
+	if (!isPlainObject(data)) return { [field]: data };
+	return Object.fromEntries(Object.entries(data).map(([key, value]) => [`${field}.${key}`, value]));
+}
+/**
+* `body` with `value` at `segments` — assigned, or REMOVED when `value` is `null`. Neither input is
+* mutated.
+*
+* Two rules about containers along the way, and both follow from "the value replaces what the key
+* addresses":
+*
+*  - An intermediate that is missing, or is a scalar, becomes a container. The caller addressed
+*    something inside it, which is a caller saying one belongs there.
+*  - A removal that EMPTIES a container takes the container with it, except at the first segment —
+*    those are the target's own declared fields, and a rule whose `layers` bag has been cleared is
+*    still a rule with an empty bag, not a rule missing a required field. Removing the field itself
+*    is what `null` AT that segment says. A SET never prunes: an empty object a caller wrote is a
+*    value.
+*/
+function setAtPath(body, segments, value, depth = 0) {
+	const [head, ...rest] = segments;
+	if (head === void 0) return body;
+	const next = { ...body };
+	if (rest.length === 0) {
+		if (value === null) delete next[head];
+		else next[head] = value;
+		return next;
+	}
+	const written = setAtPath(isPlainObject(next[head]) ? next[head] : {}, rest, value, depth + 1);
+	if (depth > 0 && value === null && Object.keys(written).length === 0) delete next[head];
+	else next[head] = written;
+	return next;
+}
+/**
+* A path-keyed delta applied to a body, entry by entry in the order the caller wrote them.
+*
+* Order matters and is the caller's: two entries may address the same subtree, and the second is
+* meant to win. That is also what makes one batch safe where a read-merge-write pair was not.
+*/
+function applyPathDelta(current, delta, isField) {
+	let out = current;
+	for (const [key, value] of Object.entries(delta)) out = setAtPath(out, pathSegments(key, isField), value);
+	return out;
+}
+/**
+* The inverse of {@link applyPathDelta}: the path-keyed delta that turns `existing` into `desired`,
+* over `fields` — one entry per changed member (`null` removes), nothing restated. This is what
+* makes a reconciling writer produce patches that SAY what the gesture did: a prop edit reads back
+* as `props.bg`, not as a whole-body replace.
+*
+* Descent stops exactly where addressing stops, so applying the delta always reproduces `desired`:
+* both sides must be plain records (an array, a ref, a scalar replaces at its own address), every
+* member key must be dot-free (a dotted key can't be addressed — the record writes whole), and a
+* NESTED record emptied of members writes whole, since {@link setAtPath} prunes a container a
+* removal empties. A declared field is never pruned there, so at the field level the same
+* emptying stays addressed.
+*
+* `same` is the caller's structural equality — bodies hold refs, and whether two spellings of one
+* are equal is the caller's to say.
+*/
+function pathDelta({ existing, desired, fields, same }) {
+	const delta = {};
+	const isRef = (value) => typeof value?.__ref === "string";
+	const walk = (address, before, after, depth) => {
+		if (same(before, after)) return;
+		const keys = isPlainObject(before) && isPlainObject(after) ? [...new Set([...Object.keys(before), ...Object.keys(after)])] : void 0;
+		if (!(keys !== void 0 && keys.length > 0 && (depth === 0 || Object.keys(after).length > 0) && !isRef(before) && !isRef(after) && keys.every((key) => !key.includes(".")))) {
+			delta[address] = after === void 0 ? null : after;
+			return;
+		}
+		for (const key of keys) walk(`${address}.${key}`, before[key], after[key], depth + 1);
+	};
+	for (const field of fields) walk(field, existing[field], desired[field], 0);
+	return delta;
+}
+/** A field predicate over a known list of names — an entity's `fieldKeys`, straight off the kind. */
+function namedFields(names) {
+	const declared = new Set(names);
+	return (name) => declared.has(name);
+}
+/** The FIELDS a delta touched — every key's first segment. What a write reports as changed, so work
+*  scoped to written fields (member coercion) covers the same set the delta reached. */
+function touchedFields(delta, isField) {
+	return new Set(Object.keys(delta).map((key) => pathSegments(key, isField)[0]));
+}
+//#endregion
+export { applyPathDelta, isPlainObject, namedFields, pathDelta, pathSegments, sectionDelta, setAtPath, touchedFields };

package/dist/framework/utils/field-schema.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+
+//#region src/framework/utils/field-schema.d.ts
+/** A kind's fields: a flat object, or a union discriminated on one field for kinds whose
+ *  shape varies (each member a `z.object`). */
+type FieldsSchema = z.ZodObject<z.ZodRawShape> | z.ZodDiscriminatedUnion<readonly z.ZodObject<z.ZodRawShape>[]>;
+/** Distribute over a union first, then drop each member's index signature so an empty
+ *  `z.object({})` (which infers to `Record<string, never>`) intersects cleanly with the
+ *  metadata below. Real declared keys are kept; only the catch-all index is removed. */
+type RemoveIndex<T> = T extends unknown ? { [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: T[K] } : never;
+/** The typed author/create body for a schema — the schema's input shape (so a field with
+ *  a zod `.default()` is optional to author; it's coerced in) plus the universal metadata
+ *  every entity may carry. Over a discriminated union this stays a union, so authoring one
+ *  member's fields never bleeds into another's. */
+type CreateInput<S extends FieldsSchema> = RemoveIndex<z.input<S>> & {
+  label?: string;
+  description?: string;
+  copiedFrom?: string;
+  hidden?: boolean;
+  deprecated?: boolean;
+  guidance?: string;
+};
+/** The create validator — the field schema plus metadata (the storage shape; a value
+ *  storage accepts is creatable — no artificial narrowing at the entity layer). A union
+ *  extends each member so the discriminant still selects one strict shape. `safeExtend`, so a
+ *  check a kind declares across its fields (a preview prop naming a prop the body doesn't
+ *  declare) survives: `extend` drops an object's checks. */
+declare function deriveCreateSchema(schema: FieldsSchema): z.ZodTypeAny;
+/**
+ * The update validator — a partial whose keys are field paths ({@link applyPathDelta}).
+ *
+ * Loose, and that is load-bearing rather than lax: `layers.root.bg` is not a declared field, so a
+ * schema that stripped unknown keys (zod's default) would drop every deep write on the floor and
+ * report success. What the key names is checked when the delta is applied — the path's head must be a
+ * field — and the result of applying it is then validated against the create schema, which is where
+ * value types, cross-field checks and coercions all live. So this schema's job is to describe the
+ * fields a caller may name and to type the whole-field case; it is deliberately not the gate.
+ */
+declare function deriveUpdateSchema(schema: FieldsSchema): z.ZodTypeAny;
+/**
+ * Whether a name is a field of the thing being written — what {@link pathSegments} asks to decide
+ * whether a dotted delta key is an address or one literal key.
+ *
+ * Liberal by construction: a union contributes every member's keys, and a record contributes all
+ * names, because a record's keys are its fields (a component's `layers` bag is addressed by layer
+ * name). Metadata counts too, so `label` is namable wherever it is storable. A name this says no to
+ * is written as one key, dot and all, which is the safe answer — the create schema then judges it.
+ */
+declare function declaredField(schema: z.ZodTypeAny | undefined): (name: string) => boolean;
+/** The declared field names, in order — hydration and `toJSON` walk these. A union yields
+ *  the union of every member's keys (discriminant first), so hydration copies whichever
+ *  fields the stored member actually carries. */
+declare function fieldKeys(schema: FieldsSchema): string[];
+//#endregion
+export { CreateInput, FieldsSchema, declaredField, deriveCreateSchema, deriveUpdateSchema, fieldKeys };

package/dist/framework/utils/field-schema.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+//#region src/framework/utils/field-schema.ts
+/**
+* An entity declares its fields as a plain `z.object({ ... })` — optionality, value types,
+* and validation come straight from zod (`z.string().optional()`), no custom dsl. Everything
+* downstream (typed bodies, create/update validators, hydration) derives from that one
+* schema.
+*
+* A kind whose shape genuinely varies by a discriminant (Motion: `runtime: 'css'` needs
+* `keyframes`, `runtime: 'js'` carries interaction state instead) may instead declare a
+* `z.discriminatedUnion` — so the coupling is a type, not a runtime hope. The three
+* derivations below handle both: an object extends/partials its shape directly; a union
+* extends/partials each member and re-composes, keeping the discriminant intact.
+*/
+/**
+* Universal editable metadata — every entity's create body may carry it, on an item and on a group
+* node alike.
+*
+* `copiedFrom` is where a copied entity was taken from, as `<path>@<slug>`: the source's spelling of
+* the path and the pin it came through. A plain string rather than a ref, because a copy stands on its
+* own — it must not become a dependency on the pin, and dropping the pin must not delete it. Written by
+* `linked-system/copy`; absent on an entity authored here.
+*
+* `hidden` and `deprecated` are the two ways to retire an entity short of deleting it. Both keep it
+* registered, resolving and emitting, and take it out of every surface that offers values to pick
+* from. `deprecated` additionally flags every existing use, so it can be worked through. Set on a
+* group node, either applies to every member; `Config.hidden` and `Config.deprecated` read both.
+*
+* `guidance` is how to use the entity, as prose for a model composing with the system, in the
+* imperative voice of a guidance rule. `description` says what the thing is for a surface that lists
+* it. The guidance document collects these per kind and the prompt prints them there.
+*/
+const METADATA = {
+	label: z.string().optional(),
+	description: z.string().optional(),
+	copiedFrom: z.string().optional(),
+	hidden: z.boolean().optional(),
+	deprecated: z.boolean().optional(),
+	guidance: z.string().optional()
+};
+/**
+* The metadata names a body may carry on top of its kind's own fields — read off {@link metadata}
+* rather than re-listed, so the two cannot disagree.
+*
+* What a caller wants it for is deciding whether a delta key names something: `fieldKeys` covers the
+* declared fields and stops, so a gate built on that alone refuses `label` on every kind. `Entity`
+* hydrates these two separately for the same reason.
+*/
+const METADATA_KEYS = Object.keys(METADATA);
+/** Re-compose a discriminated union from transformed members. Each member keeps its literal
+*  discriminant at runtime, but mapping over the erased `ZodObject<ZodRawShape>` members
+*  hides that literal from `discriminatedUnion`'s tuple constraint — so the one bridging cast
+*  lives here rather than at every call site. */
+function composeDiscriminated(discriminator, members) {
+	return z.discriminatedUnion(discriminator, members);
+}
+/** Make every field of a shape a partial-patch field: an optional field also accepts
+*  `null` (the universal "clear this field" affordance — `apply` drops null keys), a
+*  required field just becomes optional. Keys in `keep` pass through untouched — used to
+*  hold a union's discriminant literal required so the patch still identifies its member. */
+function partializeShape(shape, keep) {
+	const out = {};
+	for (const [key, field] of Object.entries(shape)) {
+		if (keep.has(key)) {
+			out[key] = field;
+			continue;
+		}
+		const f = field;
+		out[key] = (f instanceof z.ZodOptional ? f.unwrap() : f).nullable().optional();
+	}
+	return out;
+}
+/** The create validator — the field schema plus metadata (the storage shape; a value
+*  storage accepts is creatable — no artificial narrowing at the entity layer). A union
+*  extends each member so the discriminant still selects one strict shape. `safeExtend`, so a
+*  check a kind declares across its fields (a preview prop naming a prop the body doesn't
+*  declare) survives: `extend` drops an object's checks. */
+function deriveCreateSchema(schema) {
+	if (schema instanceof z.ZodDiscriminatedUnion) return composeDiscriminated(schema.def.discriminator, schema.def.options.map((member) => member.safeExtend(METADATA)));
+	return schema.safeExtend(METADATA);
+}
+/**
+* The delta shape — one entry per field a partial may name, each optional and `null`-accepting.
+*
+* A union flattens into one shape rather than staying discriminated, and that is the point: a delta
+* addresses a field, not a member, so requiring the discriminant would mean restating `type` to
+* change a Motion's duration. A key two members declare differently widens to `unknown` — the delta
+* doesn't say which member it is aimed at, and the narrower of two types would refuse a legitimate
+* write. What the delta is actually checked against is the create schema, applied to the result.
+*
+* `undefined` when there is no shape to partial: a member may be a scalar (a component layer is its
+* element), and there is nothing to name inside it.
+*/
+function deltaShape(schema) {
+	if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable || schema instanceof z.ZodDefault) return deltaShape(unwrapOnce(schema));
+	if (schema instanceof z.ZodPipe) return deltaShape(schema.def.in);
+	if (schema instanceof z.ZodObject) return partializeShape(schema.shape, /* @__PURE__ */ new Set());
+	if (schema instanceof z.ZodUnion || schema instanceof z.ZodDiscriminatedUnion) {
+		const out = {};
+		const shared = z.unknown().nullable().optional();
+		for (const member of schema.options) {
+			const fields = deltaShape(member);
+			if (!fields) return void 0;
+			for (const [key, field] of Object.entries(fields)) out[key] = key in out ? shared : field;
+		}
+		return out;
+	}
+}
+/** One layer of optional/nullable/default off a schema. */
+function unwrapOnce(schema) {
+	if (schema instanceof z.ZodDefault) return schema.def.innerType;
+	return schema.unwrap();
+}
+/**
+* The update validator — a partial whose keys are field paths ({@link applyPathDelta}).
+*
+* Loose, and that is load-bearing rather than lax: `layers.root.bg` is not a declared field, so a
+* schema that stripped unknown keys (zod's default) would drop every deep write on the floor and
+* report success. What the key names is checked when the delta is applied — the path's head must be a
+* field — and the result of applying it is then validated against the create schema, which is where
+* value types, cross-field checks and coercions all live. So this schema's job is to describe the
+* fields a caller may name and to type the whole-field case; it is deliberately not the gate.
+*/
+function deriveUpdateSchema(schema) {
+	const metadata = partializeShape(METADATA, /* @__PURE__ */ new Set());
+	return z.looseObject({
+		...deltaShape(schema),
+		...metadata
+	});
+}
+/** The update (partial) validator for a sub-entity member — {@link deriveUpdateSchema} without the
+*  Entity metadata (a layer/prop member isn't an entity, carries no label/description). A member with
+*  no shape to name into — a component layer is its element — keeps its own schema: there is no path
+*  to write, so an update replaces it. */
+function deriveMemberUpdateSchema(schema) {
+	if (schema instanceof z.ZodNullable) return deriveMemberUpdateSchema(schema.unwrap()).nullable();
+	const shape = deltaShape(schema);
+	return shape ? z.looseObject(shape) : schema;
+}
+/**
+* Whether a name is a field of the thing being written — what {@link pathSegments} asks to decide
+* whether a dotted delta key is an address or one literal key.
+*
+* Liberal by construction: a union contributes every member's keys, and a record contributes all
+* names, because a record's keys are its fields (a component's `layers` bag is addressed by layer
+* name). Metadata counts too, so `label` is namable wherever it is storable. A name this says no to
+* is written as one key, dot and all, which is the safe answer — the create schema then judges it.
+*/
+function declaredField(schema) {
+	const names = new Set(Object.keys(METADATA));
+	let anyName = false;
+	const collect = (from) => {
+		if (!from) return;
+		if (from instanceof z.ZodOptional || from instanceof z.ZodNullable || from instanceof z.ZodDefault) {
+			collect(unwrapOnce(from));
+			return;
+		}
+		if (from instanceof z.ZodRecord) {
+			anyName = true;
+			return;
+		}
+		if (from instanceof z.ZodObject) {
+			for (const key of Object.keys(from.shape)) names.add(key);
+			return;
+		}
+		if (from instanceof z.ZodUnion || from instanceof z.ZodDiscriminatedUnion) for (const member of from.options) collect(member);
+	};
+	collect(schema);
+	return (name) => anyName || names.has(name);
+}
+/** The declared field names, in order — hydration and `toJSON` walk these. A union yields
+*  the union of every member's keys (discriminant first), so hydration copies whichever
+*  fields the stored member actually carries. */
+function fieldKeys(schema) {
+	if (schema instanceof z.ZodDiscriminatedUnion) {
+		const keys = [];
+		for (const member of schema.def.options) for (const key of Object.keys(member.shape)) if (!keys.includes(key)) keys.push(key);
+		return keys;
+	}
+	return Object.keys(schema.shape);
+}
+//#endregion
+export { METADATA_KEYS, declaredField, deriveCreateSchema, deriveMemberUpdateSchema, deriveUpdateSchema, fieldKeys };

package/dist/framework/utils/group.d.ts

@@ -0,0 +1,37 @@
+import { Ref } from "./refs.js";
+import { CreateInput, FieldsSchema } from "./field-schema.js";
+import { Authored } from "../authoring.js";
+
+//#region src/framework/utils/group.d.ts
+declare const GROUP: unique symbol;
+/**
+ * One authored entry for a kind: an item body, a group node, a bare shorthand for the primary field,
+ * or a NESTED record whose keys extend the path.
+ *
+ * Recursive because nesting is. A path is a slash-joined name and a config may spell it either way —
+ * `'color/text/primary'` or `color: { text: { primary } }` — so a record of these is admissible at
+ * every level, exactly as `register` flattens them.
+ */
+type AuthoredEntry<F extends FieldsSchema, G extends FieldsSchema> = CreateInput<F> | GroupBody<F, G> | Authored | string | number | Ref | NestedEntries<F, G>;
+/**
+ * A record of entries under a shared prefix.
+ *
+ * Its values are entries in their own right, but never a BARE SHORTHAND. That mirrors the flattener,
+ * which treats a record as a prefix only when every value is an object — so a string sitting in one
+ * is a malformed item either way, and this is what makes the type say so rather than silently
+ * reading `{ valuee: '#fff' }` as a nested token named `valuee`.
+ */
+type NestedEntries<F extends FieldsSchema, G extends FieldsSchema> = {
+  readonly [key: string]: CreateInput<F> | GroupBody<F, G> | Authored | Ref | NestedEntries<F, G>;
+};
+/** A group node — its own fields, plus the members that live under its path. */
+type GroupBody<F extends FieldsSchema, G extends FieldsSchema> = CreateInput<G> & {
+  /** The group's members, keyed by the segment that extends its path. Stating the prefix once is
+   *  the point: `color: Token.group({ items: { brand } })` rather than `'color/brand'` per entry. */
+  readonly items?: Readonly<Record<string, AuthoredEntry<F, G>>>;
+  readonly [GROUP]?: true;
+};
+declare function brandGroup<F extends FieldsSchema, G extends FieldsSchema>(meta: GroupBody<F, G>): GroupBody<F, G>;
+declare function isGroupBody(value: unknown): boolean;
+//#endregion
+export { AuthoredEntry, GROUP, GroupBody, brandGroup, isGroupBody };

package/dist/framework/utils/group.js

@@ -0,0 +1,13 @@
+//#region src/framework/utils/group.ts
+const GROUP = Symbol("entity-kit/group");
+function brandGroup(meta) {
+	return {
+		...meta,
+		[GROUP]: true
+	};
+}
+function isGroupBody(value) {
+	return typeof value === "object" && value !== null && value[GROUP] === true;
+}
+//#endregion
+export { GROUP, brandGroup, isGroupBody };

package/dist/framework/utils/package-path.d.ts

@@ -0,0 +1,37 @@
+//#region src/framework/utils/package-path.d.ts
+/**
+ * A package specifier → the path its `Package` entities live at.
+ *
+ * **There is no slug. The path IS the module** — `package:@ariakit/react#TooltipAnchor` — the same
+ * choice `File` makes for its src, and for the same reason: a name derived from another name is a
+ * second copy that can drift, and a derived name has to stay stable against a set that grows.
+ *
+ * It used to be a slug (`package:ariakit/TooltipAnchor`), computed over the whole import SET so that
+ * two specifiers sharing a scope could both qualify away from it. That made a key depend on what else
+ * happened to be imported: `@phosphor-icons/core` arriving beside `@phosphor-icons/react` renamed the
+ * latter's group and stranded every stored ref that named it. Declaring the groups froze the answer,
+ * at the cost of making every consumer restate imports it had already written. A module is a name npm
+ * has already made unique, so using it needs neither a set nor a declaration.
+ *
+ * Lives in the config package because BOTH sides derive from it: the layers schema serializes a
+ * native marker to `package:<module>/<name>` at parse, and codegen's collectors key registry entries
+ * and `Package` groups the same way at build. One rule — and now one that cannot be computed two
+ * ways, because it consults nothing but the specifier in hand.
+ */
+declare const EXPORT_MEMBER = "exports";
+declare function packageName(specifier: string): string;
+/**
+ * The stored ref for one export — `package:react-native#Pressable`.
+ *
+ * The MODULE is the entity and the export is a MEMBER of it, separated by the grammar's own member
+ * marker rather than by a `/` and a convention about which segment is which. A `/` cannot do it: an
+ * npm specifier contains them (`@ariakit/react`, `motion/react`), so "the last segment is the export"
+ * is a guess that `motion/react` and `@phosphor-icons/core` both break — the first is a module that
+ * parses as an export called `react`, the second a module that parsed as an export called `core`.
+ *
+ * The module goes in VERBATIM. `motion/react` and `motion` are different modules even though they are
+ * one npm package, and only the exact one regenerates the import the author wrote.
+ */
+declare function packageKey(specifier: string, name: string): string;
+//#endregion
+export { EXPORT_MEMBER, packageKey, packageName };

package/dist/framework/utils/package-path.js

@@ -0,0 +1,61 @@
+//#region src/framework/utils/package-path.ts
+/**
+* A package specifier → the path its `Package` entities live at.
+*
+* **There is no slug. The path IS the module** — `package:@ariakit/react#TooltipAnchor` — the same
+* choice `File` makes for its src, and for the same reason: a name derived from another name is a
+* second copy that can drift, and a derived name has to stay stable against a set that grows.
+*
+* It used to be a slug (`package:ariakit/TooltipAnchor`), computed over the whole import SET so that
+* two specifiers sharing a scope could both qualify away from it. That made a key depend on what else
+* happened to be imported: `@phosphor-icons/core` arriving beside `@phosphor-icons/react` renamed the
+* latter's group and stranded every stored ref that named it. Declaring the groups froze the answer,
+* at the cost of making every consumer restate imports it had already written. A module is a name npm
+* has already made unique, so using it needs neither a set nor a declaration.
+*
+* Lives in the config package because BOTH sides derive from it: the layers schema serializes a
+* native marker to `package:<module>/<name>` at parse, and codegen's collectors key registry entries
+* and `Package` groups the same way at build. One rule — and now one that cannot be computed two
+* ways, because it consults nothing but the specifier in hand.
+*/
+/**
+* A specifier stripped to the npm package it installs — `@scope/pkg/sub` → `@scope/pkg`.
+*
+* The unit a GROUP is keyed by, because it is the unit a consumer installs: two specifiers reaching
+* into one package are one dependency. The SUBPATH is not lost — it is the key of the `File.imports`
+* entry that reached it. So the two kinds divide the fact: `File` records what the source WROTE,
+* `Package` records what a consumer INSTALLS.
+*
+* This is also what answers "where does the module end and the export begin" in a stored path — a
+* leading `@` means the first two segments, otherwise the first one, which is npm's own rule. An
+* export name cannot contain a `/`, so there is nothing left ambiguous.
+*/
+/** The grammar's member marker, and the FIELD `Package` stores its exports in. Both spelled here so a
+*  key and a `memberRef` cannot disagree about the one string that separates a ref's two halves.
+*
+*  It is the field name rather than the sub-entity's own name because that is what resolution reads:
+*  `ref-integrity`'s `resolves` looks the collection up as `owner[member.slice(0, slash)]`, the same
+*  way `component:Input#props/disabled` names the `props` field. */
+const MEMBER = "#";
+const EXPORT_MEMBER = "exports";
+function packageName(specifier) {
+	const segments = specifier.split("/");
+	return specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0] ?? specifier;
+}
+/**
+* The stored ref for one export — `package:react-native#Pressable`.
+*
+* The MODULE is the entity and the export is a MEMBER of it, separated by the grammar's own member
+* marker rather than by a `/` and a convention about which segment is which. A `/` cannot do it: an
+* npm specifier contains them (`@ariakit/react`, `motion/react`), so "the last segment is the export"
+* is a guess that `motion/react` and `@phosphor-icons/core` both break — the first is a module that
+* parses as an export called `react`, the second a module that parsed as an export called `core`.
+*
+* The module goes in VERBATIM. `motion/react` and `motion` are different modules even though they are
+* one npm package, and only the exact one regenerates the import the author wrote.
+*/
+function packageKey(specifier, name) {
+	return `package:${specifier}${MEMBER}${name}`;
+}
+//#endregion
+export { EXPORT_MEMBER, packageKey, packageName };