@abinnovision/payloadcms-wayfinder 1.0.0-beta.2 → 1.0.0-beta.3

package/README.md

@@ -6,10 +6,11 @@ Editor-authored URL routing for [Payload CMS](https://payloadcms.com/).
 
 Wayfinder owns one thing: the map from collections to the URL patterns their documents are served
 at. That map is authored in the CMS, so adding a page type is an editorial act rather than a code
-change. Everything else in the package falls out of it. `buildHref` turns a document into an href,
-`buildPath` builds a path from parameter values alone for sitemaps and feeds,
-`resolvePathToDocument` turns a request path back into a document for a catch-all route, and
-`resolveLink` plus `linkField` give editors a link that follows its target when that collection's
+change. Everything else in the package falls out of it. `createRouter` binds the mapping, the
+locale and the href formatter once per request and hands back a router: `router.href` turns a
+document into an href, `router.path` builds a path from parameter values alone for sitemaps and
+feeds, `router.resolve` turns a request path back into a document for a catch-all route, and
+`router.link` plus `linkField` give editors a link that follows its target when that collection's
 pattern changes. [`docs/concepts.md`](./docs/concepts.md) describes the model;
 [`docs/limitations.md`](./docs/limitations.md) states what is out of scope and why.
 
@@ -42,7 +43,7 @@ import { buildConfig } from "payload";
 
 export default buildConfig({
   // ...
-  plugins: [wayfinderPlugin({ linkableCollections: ["pages", "articles"] })],
+  plugins: [wayfinderPlugin({ checkDefaultPopulateOn: ["pages", "articles"] })],
 });
 ```
 
@@ -63,7 +64,7 @@ Read the mapping and hand it to a catch-all route:
 
 ```tsx
 // app/[[...path]]/page.tsx
-import { resolvePathToDocument } from "@abinnovision/payloadcms-wayfinder";
+import { createRouter } from "@abinnovision/payloadcms-wayfinder";
 import { loadMappings } from "@abinnovision/payloadcms-wayfinder/config";
 import { notFound } from "next/navigation";
 import { getPayload } from "payload";
@@ -75,11 +76,10 @@ const Page = async ({ params }: { params: Promise<{ path?: string[] }> }) => {
   const mappings = await loadMappings({ payload });
   const { path } = await params;
 
-  const resolved = await resolvePathToDocument({
+  const wayfinder = createRouter({ mappings, locale: "en" });
+
+  const resolved = await wayfinder.resolve(`/${(path ?? []).join("/")}`, {
     payload,
-    mappings,
-    path: `/${(path ?? []).join("/")}`,
-    locale: "en",
   });
 
   if (!resolved) {
@@ -98,17 +98,20 @@ export default Page;
 ## Entrypoints
 
 ```
-"."         buildHref, buildPath, resolvePathToDocument, resolveLink, defineMappings, defineLinks, types
-"./config"  wayfinderPlugin, createMappingGlobal, loadMappings, linkField
-"./lexical" wayfinderLinkFeature, linkLabelFeature, resolveLinkNode
-"./admin"   LinkLabelFeatureClient, mounted by linkLabelFeature through the import map
-"./montage" initWayfinder, getMappings, wayfinderExtension
+"."          createRouter, defineMappings, defineLinks, resolveRelationshipSlug, deriveLinkLabel, types
+"./internal" the unbound functions the router is built out of, plus the pattern internals
+"./config"   wayfinderPlugin, createMappingGlobal, loadMappings, linkField
+"./lexical"  wayfinderLinkFeature, linkLabelFeature, resolveLinkNode
+"./admin"    LinkLabelFeatureClient, mounted by linkLabelFeature through the import map
+"./montage"  initWayfinder, wayfinderFrom, wayfinderExtension
 ```
 
 `.` is the runtime half. It takes mappings as plain data and never reads the CMS, so it runs in a
-route handler, a sitemap, a script or a test alike. `./config` is loaded by the CLI, by migrations
-and by `payload generate:types`, so it must stay React-free. `./lexical`, `./admin` and
-`./montage` each pull in an optional peer and are separate for that reason.
+route handler, a sitemap, a script or a test alike. `./internal` is the escape hatch behind it,
+for a caller that holds no request or wants a different set of arguments per call; nothing there
+carries a compatibility guarantee. `./config` is loaded by the CLI, by migrations and by
+`payload generate:types`, so it must stay React-free. `./lexical`, `./admin` and `./montage` each
+pull in an optional peer and are separate for that reason.
 [`docs/layers.md`](./docs/layers.md) explains the split.
 
 ## Documentation
@@ -119,7 +122,7 @@ and by `payload generate:types`, so it must stay React-free. `./lexical`, `./adm
   works without.
 - [`docs/integration.md`](./docs/integration.md): plugin setup, caching, catch-all routes,
   sitemaps and `defaultPopulate`.
-- [`docs/linking.md`](./docs/linking.md): `linkField`, `defineLinks`, `resolveLink` and the Lexical
+- [`docs/linking.md`](./docs/linking.md): `linkField`, `defineLinks`, `router.link` and the Lexical
   feature.
 - [`docs/code-defined-mappings.md`](./docs/code-defined-mappings.md): `defineMappings`, with no CMS
   global at all.

package/dist/config/load-mappings.d.mts

@@ -17,8 +17,24 @@ interface MappingCache {
 interface LoadMappingsArgs {
   payload: Payload;
   globalSlug?: string;
-  /** Must match what {@link createMappingGlobal} was given. */
+  /**
+   * Whether patterns are per-locale.
+   *
+   * Derived from the instance's own `localization` config, which is the same
+   * authority `wayfinderPlugin` derives it from, so the two sides cannot
+   * disagree. Set it only to override that, and then on both sides.
+   */
   localized?: boolean;
+  /**
+   * The field a relationship parameter falls back to when the target
+   * collection's own pattern cannot name one.
+   *
+   * Read off the mapping global's own config when the plugin was given it,
+   * so a project states it once, where the global is declared, and both the
+   * save-time validation and the compiled mappings get the same answer. Set
+   * it here only to override that.
+   */
+  fallbackIdentifierField?: string;
   /** Reuses compiled patterns across reads. @see MappingCache */
   cache?: MappingCache;
 }

package/dist/config/load-mappings.mjs

@@ -10,6 +10,16 @@ import "./mapping-global.mjs";
 };
 const defaultCache = createMemoryCache();
 /**
+* Reads what {@link createMappingGlobal} was told, off the global's own config.
+*
+* The write side validates patterns against this and the read side compiles
+* mappings with it, so the two have to agree. Carrying it on the config means
+* a project states it where it declares the global and nowhere else.
+*/ const declaredIdentifierField = (payload, slug) => {
+	const declared = (payload.config.globals.find((it) => it.slug === slug)?.custom)?.wayfinder?.fallbackIdentifierField;
+	return typeof declared === "string" ? declared : void 0;
+};
+/**
 * Reads the mapping global and compiles it.
 *
 * Returns an empty list rather than throwing when the global has never been
@@ -20,10 +30,12 @@ const defaultCache = createMemoryCache();
 *
 * @param args The Payload instance and mapping-global settings.
 */ const loadMappings = async (args) => {
-	const localized = args.localized ?? true;
+	const slug = args.globalSlug ?? "collections-mapping";
+	const localized = args.localized ?? Boolean(args.payload.config.localization);
 	const cache = args.cache ?? defaultCache;
+	const fallbackIdentifierField = args.fallbackIdentifierField ?? declaredIdentifierField(args.payload, slug);
 	const global = await args.payload.findGlobal({
-		slug: args.globalSlug ?? "collections-mapping",
+		slug,
 		depth: 0,
 		overrideAccess: true,
 		...localized ? { locale: "all" } : {}
@@ -43,12 +55,12 @@ const defaultCache = createMemoryCache();
 			path: patterns
 		}] : [];
 	});
-	const key = JSON.stringify(usable);
+	const key = JSON.stringify([usable, fallbackIdentifierField]);
 	const cached = cache.get(key);
 	if (cached) return cached;
 	const compiled = usable.flatMap((mapping) => {
 		try {
-			return [resolveCollectionMapping(mapping)];
+			return [resolveCollectionMapping(mapping, fallbackIdentifierField)];
 		} catch {
 			return [];
 		}

package/dist/config/mapping-global.d.mts

@@ -6,13 +6,22 @@ interface CreateMappingGlobalArgs {
   /** Defaults to {@link DEFAULT_MAPPING_GLOBAL_SLUG}. */
   globalSlug?: string;
   /**
-   * Whether path patterns differ per locale. Turn it off for a project with
-   * no `localization` block — Payload would otherwise return a scalar where
-   * a per-locale record is expected.
+   * Whether path patterns differ per locale.
+   *
+   * Derived from the config's `localization` block by `wayfinderPlugin`, and
+   * from the running instance by `loadMappings`, so a project normally never
+   * sets it. Pass it only to override that — and then to both sides, because
+   * Payload returns a scalar for an unlocalized field and a per-locale record
+   * for a localized one, and the read has to expect the shape the write
+   * produced.
    */
   localized?: boolean;
-  /** Fallback identifier field for relationship parameters. */
-  identifierField?: string;
+  /**
+   * The field a relationship parameter falls back to when the target
+   * collection's pattern cannot name one. Used here to validate a pattern at
+   * save time, before any mapping has been compiled to carry it.
+   */
+  fallbackIdentifierField?: string;
   label?: GlobalConfig["label"];
   adminGroup?: string;
   access?: GlobalConfig["access"];

package/dist/config/mapping-global.mjs

@@ -41,7 +41,7 @@ import { text } from "payload/shared";
 					config: collection.config,
 					param: key.name,
 					collections: opts.req.payload.collections,
-					...args.identifierField ? { identifierField: args.identifierField } : {}
+					...args.fallbackIdentifierField ? { fallbackIdentifierField: args.fallbackIdentifierField } : {}
 				});
 				if ("error" in resolved) return resolved.error;
 			}
@@ -51,6 +51,7 @@ import { text } from "payload/shared";
 	return {
 		slug: args.globalSlug ?? "collections-mapping",
 		label: args.label ?? "Collections Mapping",
+		...args.fallbackIdentifierField ? { custom: { wayfinder: { fallbackIdentifierField: args.fallbackIdentifierField } } } : {},
 		...args.access ? { access: args.access } : {},
 		admin: {
 			group: args.adminGroup ?? "Settings",

package/dist/config/plugin.d.mts

@@ -3,10 +3,13 @@ import { Plugin } from "payload";
 //#region src/config/plugin.d.ts
 interface WayfinderPluginArgs extends CreateMappingGlobalArgs {
   /**
-   * Collections that can be linked to. Only used to warn about missing
-   * `defaultPopulate`; linking itself is governed by the link field.
+   * Collections to check for `defaultPopulate` at boot.
+   *
+   * Named for what it does. It grants nothing: which collections can be
+   * linked to is decided by the link field's own `relationTo`, and an
+   * earlier name implied this list governed that.
    */
-  linkableCollections?: string[];
+  checkDefaultPopulateOn?: string[];
   /**
    * Set when the project resolves references through its own index rather
    * than a populated document. Suppresses the `defaultPopulate` warning,

package/dist/config/plugin.mjs

@@ -13,7 +13,10 @@ import { createMappingGlobal } from "./mapping-global.mjs";
 */ const wayfinderPlugin = (args = {}) => (incoming) => {
 	const config = {
 		...incoming,
-		globals: [...incoming.globals ?? [], createMappingGlobal(args)],
+		globals: [...incoming.globals ?? [], createMappingGlobal({
+			localized: Boolean(incoming.localization),
+			...args
+		})],
 		i18n: {
 			...incoming.i18n,
 			translations: {
@@ -24,7 +27,7 @@ import { createMappingGlobal } from "./mapping-global.mjs";
 	};
 	if (args.quiet) return config;
 	if (!args.resolvesReferencesExternally) {
-		const missing = (args.linkableCollections ?? []).filter((slug) => {
+		const missing = (args.checkDefaultPopulateOn ?? []).filter((slug) => {
 			const collection = config.collections?.find((it) => it.slug === slug);
 			return collection && !collection.defaultPopulate;
 		});

package/dist/index.d.mts

@@ -1,16 +1,12 @@
-import { BaseResolvedLink, BuiltinLinkVariant, Contributed, DEFAULT_LOCALE_KEY, DeclaredLinkVariant, FormatHref, LabelLike, LinkFieldData, PayloadCollectionMapping, PayloadCollectionMappingMatch, PayloadCollectionMappingResolved, PayloadCollectionMappingResolvers, PayloadCollectionMappingSpecificity, ResolvedLink } from "./pattern/types.mjs";
-import { AnyLinkVariantDefinition, DataOfFields, LinkDataOf, LinkDeclaration, LinkVariantDefinition, LinkVariantSource, LinkVariantSpec, ResolvedLinkOf, VariantBuilder, defineLinks, variantsOf } from "./pattern/define-links.mjs";
-import { defineMappings } from "./pattern/define-mappings.mjs";
-import { deriveLinkLabel } from "./pattern/derive-link-label.mjs";
-import { PayloadCollectionMatch, matchCollectionMappings } from "./pattern/matcher.mjs";
-import { DEFAULT_IDENTIFIER_FIELD, RegisteredCollections, ResolveParamQueryPathArgs, resolveParamQueryPath } from "./pattern/param-query-path.mjs";
-import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
-import "./pattern/index.mjs";
+import { BaseResolvedLink, BuiltinLinkVariant, DocumentId, FormatHref, LabelLike, LinkFieldData, PayloadCollectionMapping, PayloadCollectionMappingResolved } from "./pattern/types.mjs";
+import { LinkContextOf, LinkDataOf, LinkDeclaration, ResolvedLinkOf, defineLinks } from "./pattern/define-links.mjs";
 import { BuildDiagnosticReason, Diagnostic, DiagnosticReason, OnDiagnostic, ResolveLinkDiagnosticReason, ResolvePathDiagnosticReason } from "./runtime/diagnostics.mjs";
-import { BuildHrefArgs, LinkableDocument, buildHref, identityFormatHref } from "./runtime/build-href.mjs";
-import { BuildPathArgs, buildPath } from "./runtime/build-path.mjs";
-import { ResolveLinkArgs, ResolveReference, isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
-import { PayloadDocument, ResolvePathToDocumentArgs, ResolvePathWhere, ResolvedPath, resolvePathToDocument } from "./runtime/resolve-path.mjs";
+import { LinkableDocument } from "./runtime/build-href.mjs";
+import { ResolveReference } from "./runtime/resolve-link.mjs";
+import { PayloadCollectionMatch } from "./pattern/matcher.mjs";
+import { PayloadDocument, ResolvePathWhere, ResolvedPath } from "./runtime/resolve-path.mjs";
+import { CreateRouterArgs, Router, createRouter } from "./runtime/create-router.mjs";
 import { ResolveRelationshipSlugArgs, resolveRelationshipSlug } from "./runtime/resolve-relationship-slug.mjs";
-import "./runtime/index.mjs";
-export { type AnyLinkVariantDefinition, type BaseResolvedLink, type BuildDiagnosticReason, type BuildHrefArgs, type BuildPathArgs, type BuiltinLinkVariant, type Contributed, DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, type DataOfFields, type DeclaredLinkVariant, type Diagnostic, type DiagnosticReason, type FormatHref, type LabelLike, type LinkDataOf, type LinkDeclaration, type LinkFieldData, type LinkVariantDefinition, type LinkVariantSource, type LinkVariantSpec, type LinkableDocument, type OnDiagnostic, type PayloadCollectionMapping, type PayloadCollectionMappingMatch, type PayloadCollectionMappingResolved, type PayloadCollectionMappingResolvers, type PayloadCollectionMappingSpecificity, type PayloadCollectionMatch, type PayloadDocument, type RegisteredCollections, type ResolveLinkArgs, type ResolveLinkDiagnosticReason, type ResolveParamQueryPathArgs, type ResolvePathDiagnosticReason, type ResolvePathToDocumentArgs, type ResolvePathWhere, type ResolveReference, type ResolveRelationshipSlugArgs, type ResolvedLink, type ResolvedLinkOf, type ResolvedPath, type VariantBuilder, buildHref, buildPath, defineLinks, defineMappings, deriveLinkLabel, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolveRelationshipSlug, resolversFor, variantsOf };
+import { defineMappings } from "./pattern/define-mappings.mjs";
+import { deriveLinkLabel } from "./pattern/derive-link-label.mjs";
+export { type BaseResolvedLink, type BuildDiagnosticReason, type BuiltinLinkVariant, type CreateRouterArgs, type Diagnostic, type DiagnosticReason, type DocumentId, type FormatHref, type LabelLike, type LinkContextOf, type LinkDataOf, type LinkDeclaration, type LinkFieldData, type LinkableDocument, type OnDiagnostic, type PayloadCollectionMapping, type PayloadCollectionMappingResolved, type PayloadCollectionMatch, type PayloadDocument, type ResolveLinkDiagnosticReason, type ResolvePathDiagnosticReason, type ResolvePathWhere, type ResolveReference, type ResolveRelationshipSlugArgs, type ResolvedLinkOf, type ResolvedPath, type Router, createRouter, defineLinks, defineMappings, deriveLinkLabel, resolveRelationshipSlug };

package/dist/index.mjs

@@ -1,15 +1,6 @@
-import { defineLinks, variantsOf } from "./pattern/define-links.mjs";
-import { DEFAULT_LOCALE_KEY } from "./pattern/types.mjs";
-import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
+import { defineLinks } from "./pattern/define-links.mjs";
+import { createRouter } from "./runtime/create-router.mjs";
+import { resolveRelationshipSlug } from "./runtime/resolve-relationship-slug.mjs";
 import { defineMappings } from "./pattern/define-mappings.mjs";
 import { deriveLinkLabel } from "./pattern/derive-link-label.mjs";
-import { matchCollectionMappings } from "./pattern/matcher.mjs";
-import { DEFAULT_IDENTIFIER_FIELD, resolveParamQueryPath } from "./pattern/param-query-path.mjs";
-import "./pattern/index.mjs";
-import { buildHref, identityFormatHref } from "./runtime/build-href.mjs";
-import { buildPath } from "./runtime/build-path.mjs";
-import { isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
-import { resolvePathToDocument } from "./runtime/resolve-path.mjs";
-import { resolveRelationshipSlug } from "./runtime/resolve-relationship-slug.mjs";
-import "./runtime/index.mjs";
-export { DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, buildHref, buildPath, defineLinks, defineMappings, deriveLinkLabel, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolveRelationshipSlug, resolversFor, variantsOf };
+export { createRouter, defineLinks, defineMappings, deriveLinkLabel, resolveRelationshipSlug };

package/dist/internal.d.mts

@@ -0,0 +1,11 @@
+import { Contributed, DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, DeclaredLinkVariant, PayloadCollectionMappingMatch, PayloadCollectionMappingResolvers, PayloadCollectionMappingSpecificity, ResolvedLink } from "./pattern/types.mjs";
+import { AnyLinkVariantDefinition, DataOfFields, LinkVariantDefinition, LinkVariantSource, LinkVariantSpec, VariantBuilder, variantsOf } from "./pattern/define-links.mjs";
+import { BuildHrefArgs, buildHref, identityFormatHref } from "./runtime/build-href.mjs";
+import { ResolveLinkArgs, isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
+import { matchCollectionMappings } from "./pattern/matcher.mjs";
+import { ResolvePathToDocumentArgs, resolvePathToDocument } from "./runtime/resolve-path.mjs";
+import { BuildPathArgs, buildPath } from "./runtime/build-path.mjs";
+import { normaliseLinkNodeFields } from "./pattern/link-node.mjs";
+import { RegisteredCollections, ResolveParamQueryPathArgs, resolveParamQueryPath } from "./pattern/param-query-path.mjs";
+import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
+export { type AnyLinkVariantDefinition, type BuildHrefArgs, type BuildPathArgs, type Contributed, DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, type DataOfFields, type DeclaredLinkVariant, type LinkVariantDefinition, type LinkVariantSource, type LinkVariantSpec, type PayloadCollectionMappingMatch, type PayloadCollectionMappingResolvers, type PayloadCollectionMappingSpecificity, type RegisteredCollections, type ResolveLinkArgs, type ResolveParamQueryPathArgs, type ResolvePathToDocumentArgs, type ResolvedLink, type VariantBuilder, buildHref, buildPath, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, normaliseLinkNodeFields, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolversFor, variantsOf };

package/dist/internal.mjs

@@ -0,0 +1,11 @@
+import { DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY } from "./pattern/types.mjs";
+import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
+import { buildHref, identityFormatHref } from "./runtime/build-href.mjs";
+import { buildPath } from "./runtime/build-path.mjs";
+import { variantsOf } from "./pattern/define-links.mjs";
+import { isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
+import { matchCollectionMappings } from "./pattern/matcher.mjs";
+import { resolveParamQueryPath } from "./pattern/param-query-path.mjs";
+import { resolvePathToDocument } from "./runtime/resolve-path.mjs";
+import { normaliseLinkNodeFields } from "./pattern/link-node.mjs";
+export { DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, buildHref, buildPath, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, normaliseLinkNodeFields, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolversFor, variantsOf };

package/dist/lexical/index.d.mts

@@ -1,4 +1,3 @@
-import { BaseResolvedLink, LinkFieldData, ResolvedLink } from "../pattern/types.mjs";
 import { LinkDeclaration, ResolvedLinkOf } from "../pattern/define-links.mjs";
 import { LinkFieldArgs } from "../config/link-field.mjs";
 import { ResolveLinkArgs } from "../runtime/resolve-link.mjs";
@@ -18,35 +17,22 @@ declare const linkLabelFeature: import("@payloadcms/richtext-lexical").FeaturePr
  * @param args The same arguments as the standalone link field.
  */
 declare const wayfinderLinkFeature: <TDeclaration extends LinkDeclaration = LinkDeclaration>(args: LinkFieldArgs<TDeclaration>) => ReturnType<typeof LinkFeature>;
-/**
- * The two shapes a link node's fields arrive in.
- *
- * A node written by {@link wayfinderLinkFeature} nests the group under `link`.
- * A node written by Lexical's stock link feature stores `linkType` and `doc`
- * at the top level, which existing content will still hold.
- */
-interface SerializedLinkFields {
-  link?: LinkFieldData;
-  linkType?: "custom" | "internal";
-  url?: string | null;
-  newTab?: boolean | null;
-  doc?: {
-    relationTo: string;
-    value: string | {
-      id: string;
-    };
-  } | null;
-}
 /**
  * Resolves a rich-text link node to an href.
  *
+ * Takes the node's `fields` as `unknown`, because Lexical types them as an
+ * open record and a narrower parameter would make every converter cast. The
+ * two shapes a node can hold are unwrapped by
+ * {@link normaliseLinkNodeFields}, so a link written in rich text and a link
+ * authored in a block resolve through exactly the same call.
+ *
  * Returns null when the node points nowhere resolvable, so a converter can
  * render the text without an anchor rather than emitting a dead one.
  *
  * @param args The node's fields plus the usual link-resolution arguments.
  */
-declare const resolveLinkNode: <TExtra = object, TDeclaration extends LinkDeclaration = LinkDeclaration>(args: Omit<ResolveLinkArgs<TExtra, TDeclaration>, "link"> & {
-  fields: SerializedLinkFields | undefined;
-}) => BaseResolvedLink | ResolvedLink<object> | ResolvedLinkOf<TDeclaration> | null;
+declare const resolveLinkNode: <TDeclaration extends LinkDeclaration = LinkDeclaration>(args: Omit<ResolveLinkArgs<TDeclaration>, "link"> & {
+  fields: unknown;
+}) => ResolvedLinkOf<TDeclaration> | null;
 //#endregion
 export { linkLabelFeature, resolveLinkNode, wayfinderLinkFeature };

package/dist/lexical/index.mjs

@@ -1,4 +1,5 @@
 import { resolveLink } from "../runtime/resolve-link.mjs";
+import { normaliseLinkNodeFields } from "../pattern/link-node.mjs";
 import { linkField } from "../config/link-field.mjs";
 import { LinkFeature, createServerFeature } from "@payloadcms/richtext-lexical";
 //#region src/lexical/index.ts
@@ -22,36 +23,21 @@ import { LinkFeature, createServerFeature } from "@payloadcms/richtext-lexical";
 * @param args The same arguments as the standalone link field.
 */ const wayfinderLinkFeature = (args) => LinkFeature({ fields: () => [linkField(args)] });
 /**
-* Normalises a link node's fields into the link field's own shape.
-*
-* @param fields The node's `fields` object.
-*/ const normaliseNodeFields = (fields) => {
-	if (!fields) return;
-	if (fields.link) return fields.link;
-	if (fields.linkType === "internal" && fields.doc) return {
-		type: "reference",
-		reference: fields.doc,
-		newTab: fields.newTab ?? null
-	};
-	if (fields.url) return {
-		type: "custom",
-		url: fields.url,
-		newTab: fields.newTab ?? null
-	};
-};
-/**
 * Resolves a rich-text link node to an href.
 *
+* Takes the node's `fields` as `unknown`, because Lexical types them as an
+* open record and a narrower parameter would make every converter cast. The
+* two shapes a node can hold are unwrapped by
+* {@link normaliseLinkNodeFields}, so a link written in rich text and a link
+* authored in a block resolve through exactly the same call.
+*
 * Returns null when the node points nowhere resolvable, so a converter can
 * render the text without an anchor rather than emitting a dead one.
 *
 * @param args The node's fields plus the usual link-resolution arguments.
-*/ const resolveLinkNode = (args) => {
-	const link = normaliseNodeFields(args.fields);
-	return resolveLink({
-		...args,
-		link
-	});
-};
+*/ const resolveLinkNode = (args) => resolveLink({
+	...args,
+	link: normaliseLinkNodeFields(args.fields)
+});
 //#endregion
 export { linkLabelFeature, resolveLinkNode, wayfinderLinkFeature };

package/dist/montage/index.d.mts

@@ -1,32 +1,54 @@
 import { PayloadCollectionMappingResolved } from "../pattern/types.mjs";
+import { AnyLinkVariantDefinition, LinkDeclaration } from "../pattern/define-links.mjs";
 import { LoadMappingsArgs } from "../config/load-mappings.mjs";
+import { CreateRouterArgs, Router } from "../runtime/create-router.mjs";
 import { MontageSlots } from "@abinnovision/payloadcms-montage";
 //#region src/montage/index.d.ts
 /**
- * The slot the compiled mappings ride in.
+ * The slot the bound router rides in.
  *
  * Prefixed with the package name because extension names share one namespace
  * across every library using montage.
  */
-declare const wayfinderExtension: import("@abinnovision/payloadcms-montage").ContextExtension<PayloadCollectionMappingResolved[]>;
+declare const wayfinderExtension: import("@abinnovision/payloadcms-montage").ContextExtension<Router<LinkDeclaration<Record<string, AnyLinkVariantDefinition>>>>;
 /**
- * Loads the mappings once and parks them on the render context.
+ * What `initWayfinder` needs: a router's settings, plus where the mappings
+ * come from.
+ *
+ * Either hand over mappings already in hand, or the instance to read them
+ * from. A route that resolved a path has them already, and reading the global
+ * a second time to render the same page is a query for nothing.
+ */
+type InitWayfinderArgs<TDeclaration extends LinkDeclaration = LinkDeclaration> = Omit<CreateRouterArgs<TDeclaration>, "mappings"> & ({
+  mappings: PayloadCollectionMappingResolved[];
+} | {
+  load: Omit<LoadMappingsArgs, "localized"> & {
+    localized?: boolean;
+  };
+});
+/**
+ * Builds the router once and parks it on the render context.
  *
  * Blocks resolve links individually and there may be dozens on a page, so the
- * read happens once per request rather than once per link.
+ * mappings are read once per request rather than once per link — and the
+ * locale and href formatter travel with them, which is what stops a block
+ * resolving a link into the wrong locale or out of preview.
  *
  * @param ctx The render context.
- * @param args The Payload instance and mapping-global settings.
+ * @param args The router's settings, and the mappings or where to read them.
  */
-declare const initWayfinder: (ctx: MontageSlots, args: LoadMappingsArgs) => Promise<void>;
+declare const initWayfinder: <TDeclaration extends LinkDeclaration = LinkDeclaration>(ctx: MontageSlots, args: InitWayfinderArgs<TDeclaration>) => Promise<void>;
 /**
- * Reads the mappings off the render context.
+ * Reads the router off the render context.
  *
- * Returns an empty list when {@link initWayfinder} has not run, so a block
- * rendered outside a request renders without links rather than throwing.
+ * Named for what it does — the router is already built, and this is a slot
+ * read rather than a load. Throws when {@link initWayfinder} has not run,
+ * because a block rendering links without a locale would silently produce the
+ * wrong ones, and a blank page is easier to explain than a page of quietly
+ * mislocalised links.
  *
  * @param ctx The render context.
  */
-declare const getMappings: (ctx: MontageSlots) => PayloadCollectionMappingResolved[];
+declare const wayfinderFrom: <TDeclaration extends LinkDeclaration = LinkDeclaration>(ctx: MontageSlots) => Router<TDeclaration>;
 //#endregion
-export { getMappings, initWayfinder, wayfinderExtension };
+export { InitWayfinderArgs, initWayfinder, wayfinderExtension, wayfinderFrom };

package/dist/montage/index.mjs

@@ -1,30 +1,44 @@
+import { createRouter } from "../runtime/create-router.mjs";
 import { loadMappings } from "../config/load-mappings.mjs";
 import { createContextExtension } from "@abinnovision/payloadcms-montage";
 //#region src/montage/index.ts
 /**
-* The slot the compiled mappings ride in.
+* The slot the bound router rides in.
 *
 * Prefixed with the package name because extension names share one namespace
 * across every library using montage.
-*/ const wayfinderExtension = createContextExtension("wayfinder:mappings");
+*/ const wayfinderExtension = createContextExtension("wayfinder:router");
 /**
-* Loads the mappings once and parks them on the render context.
+* Builds the router once and parks it on the render context.
 *
 * Blocks resolve links individually and there may be dozens on a page, so the
-* read happens once per request rather than once per link.
+* mappings are read once per request rather than once per link — and the
+* locale and href formatter travel with them, which is what stops a block
+* resolving a link into the wrong locale or out of preview.
 *
 * @param ctx The render context.
-* @param args The Payload instance and mapping-global settings.
+* @param args The router's settings, and the mappings or where to read them.
 */ const initWayfinder = async (ctx, args) => {
-	wayfinderExtension.set(ctx, await loadMappings(args));
+	const mappings = "mappings" in args ? args.mappings : await loadMappings(args.load);
+	wayfinderExtension.set(ctx, createRouter({
+		...args,
+		mappings
+	}));
 };
 /**
-* Reads the mappings off the render context.
+* Reads the router off the render context.
 *
-* Returns an empty list when {@link initWayfinder} has not run, so a block
-* rendered outside a request renders without links rather than throwing.
+* Named for what it does — the router is already built, and this is a slot
+* read rather than a load. Throws when {@link initWayfinder} has not run,
+* because a block rendering links without a locale would silently produce the
+* wrong ones, and a blank page is easier to explain than a page of quietly
+* mislocalised links.
 *
 * @param ctx The render context.
-*/ const getMappings = (ctx) => wayfinderExtension.get(ctx) ?? [];
+*/ const wayfinderFrom = (ctx) => {
+	const router = wayfinderExtension.get(ctx);
+	if (!router) throw new Error("[wayfinder] No router on the render context. Call `initWayfinder(ctx, ...)` in the route before rendering blocks.");
+	return router;
+};
 //#endregion
-export { getMappings, initWayfinder, wayfinderExtension };
+export { initWayfinder, wayfinderExtension, wayfinderFrom };

package/dist/pattern/define-links.d.mts

@@ -49,8 +49,16 @@ type FieldData<F1> = F1 extends {
 } ? { [K in N]?: number | null; } : F1 extends {
   type: "checkbox";
 } ? { [K in N]?: boolean | null; } : { [K in N]?: unknown; } : object;
-/** Everything a variant's own fields contribute, as one object type. */
-type DataOfFields<TFields extends readonly unknown[]> = UnionToIntersection<FieldData<TFields[number]>>;
+/**
+ * Everything a variant's own fields contribute, as one object type.
+ *
+ * A variant declared without `fields`, or one whose fields were not captured
+ * as a literal tuple, arrives here as the bare `readonly Field[]`. Deriving
+ * from the whole `Field` union would intersect every field type into index
+ * signatures that reject ordinary link data, so such a variant contributes
+ * nothing rather than something wrong.
+ */
+type DataOfFields<TFields extends readonly unknown[]> = number extends TFields["length"] ? object : UnionToIntersection<FieldData<TFields[number]>>;
 /** A variant that has had no resolver attached. */
 interface LinkVariantSpec<TFields extends readonly Field[]> {
   label: LabelLike;
@@ -93,17 +101,21 @@ interface LinkDeclaration<TVariants1 extends Record<string, AnyLinkVariantDefini
   variants: TVariants1;
 }
 /** The stored shape of a link field built from a declaration. */
+type FieldsData<V> = V extends {
+  fields?: infer F extends readonly unknown[];
+} ? DataOfFields<F> : object;
 /**
  * What one variant contributes.
  *
- * Read off `__data` rather than re-derived from `fields`, so a variant that
- * named its own shape with `.data<T>()` keeps it.
+ * `__data` is read first, so a variant that named its own shape with
+ * `.data<T>()` keeps it. Every object type structurally satisfies an optional
+ * property, so its absence shows up as `unknown` and falls through to the
+ * fields — which is what lets a variant with no resolver be written as a plain
+ * object literal and still be typed.
  */
 type DataOfVariant<V> = V extends {
   __data?: infer D;
-} ? unknown extends D ? object : D : V extends {
-  fields?: infer F extends readonly unknown[];
-} ? DataOfFields<F> : object;
+} ? unknown extends D ? FieldsData<V> : D : FieldsData<V>;
 type LinkDataOf<T> = T extends LinkDeclaration<infer TVariants> ? LinkFieldData<Extract<keyof TVariants, string>, UnionToIntersection<{ [K in keyof TVariants]: DataOfVariant<TVariants[K]>; }[keyof TVariants]>> : never;
 /** What resolving a link built from a declaration can produce. */
 type ResolvedLinkOf<T> = T extends LinkDeclaration<infer TVariants> ? BaseResolvedLink & Contributed<UnionToIntersection<{ [K in keyof TVariants]: TVariants[K] extends {

package/dist/pattern/define-mappings.d.mts

@@ -9,7 +9,11 @@ import { PayloadCollectionMapping, PayloadCollectionMappingResolved } from "./ty
  * tests — none of which should have to stand up a global first.
  *
  * @param mappings The collection-to-pattern map.
+ * @param options Where a relationship parameter falls back to when the target
+ *   collection's own pattern cannot name an identifier.
  */
-declare const defineMappings: (mappings: PayloadCollectionMapping[]) => PayloadCollectionMappingResolved[];
+declare const defineMappings: (mappings: PayloadCollectionMapping[], options?: {
+  fallbackIdentifierField?: string;
+}) => PayloadCollectionMappingResolved[];
 //#endregion
 export { defineMappings };

package/dist/pattern/define-mappings.mjs

@@ -9,6 +9,8 @@ import { resolveCollectionMapping } from "./resolver.mjs";
 * tests — none of which should have to stand up a global first.
 *
 * @param mappings The collection-to-pattern map.
-*/ const defineMappings = (mappings) => mappings.map((mapping) => resolveCollectionMapping(mapping));
+* @param options Where a relationship parameter falls back to when the target
+*   collection's own pattern cannot name an identifier.
+*/ const defineMappings = (mappings, options = {}) => mappings.map((mapping) => resolveCollectionMapping(mapping, options.fallbackIdentifierField));
 //#endregion
 export { defineMappings };