@phtngyn/cms 0.2.0-beta.3 → 0.2.0-beta.5

package/src/{DocumentEngine-ClhFXW9M.js → DocumentEngine-j6Vi7nQo.js}

@@ -1,7 +1,8 @@
-import { d as SourcePath, o as PublicPath } from "./scalars-B2lgGUnj.js";
-import { M as DocumentSeo, c as DocumentIssue, h as DocumentSourceMapping, n as CmsMarkdownDocument, r as CompiledDocument, t as CmsDocumentAnalysis, v as DocumentValidationResult } from "./models-ChRxBChy.js";
-import { c as resolveCmsComarkAttributes, d as createCmsComarkRenderData, l as withCmsComarkProps, o as normalizeCmsComponentBindings, u as cmsComarkTextContent } from "./Forms-DoB56hfe.js";
-import { f as DOCUMENT_ENGINE_FINGERPRINT, l as validateCollectionBody, m as SOURCE_MAPPINGS_META_KEY, o as createAuthoringDocumentValidator, p as createDocumentParser } from "./Configuration-BU-UyGoH.js";
+import { o as PublicPath, r as DocumentId } from "./scalars-CVZqT3L0.js";
+import { P as DocumentSeo, _ as DocumentSourceMapping, b as DocumentValidationResult, l as DocumentIssue, n as CmsMarkdownDocument, r as CompiledDocument, t as CmsDocumentAnalysis } from "./models-VmGmG19-.js";
+import { i as decodeManagedMediaReference, r as decodeAuthoredDocumentReference } from "./References-CCPDAPve.js";
+import { c as resolveCmsComarkAttributes, d as createCmsComarkRenderData, l as withCmsComarkProps, o as normalizeCmsComponentBindings, u as cmsComarkTextContent } from "./Forms-CX-hwmJF.js";
+import { h as SOURCE_MAPPINGS_META_KEY, l as validateCollectionBody, m as createDocumentParser, o as createAuthoringDocumentValidator, p as DOCUMENT_ENGINE_FINGERPRINT } from "./Configuration-JQ1qyaU0.js";
 import { DateTime, Effect, Option, Predicate, Result, Schema } from "effect";
 
 //#region ../document/src/internal/document-address.ts
@@ -12,15 +13,15 @@ function parseDocumentAddress(pattern) {
 		name: match[1] ?? ""
 	}));
 	if (pattern.replace(addressTokenPattern, "").includes(":") || tokens.some((token) => !token.name)) return Result.fail({
-		field: "addressPattern",
+		field: "routes.entry",
 		message: `Document address pattern "${pattern}" contains an invalid token.`
 	});
 	if (tokens.filter((token) => token.catchAll).length > 1) return Result.fail({
-		field: "addressPattern",
+		field: "routes.entry",
 		message: `Document address pattern "${pattern}" contains more than one catch-all token.`
 	});
 	if (new Set(tokens.map((token) => token.name)).size !== tokens.length) return Result.fail({
-		field: "addressPattern",
+		field: "routes.entry",
 		message: `Document address pattern "${pattern}" contains duplicate tokens.`
 	});
 	return Result.succeed({
@@ -45,16 +46,6 @@ function resolveDocumentAddress(address, relativeKey, data) {
 	}
 	return normalizePublicPath(resolved);
 }
-function documentKeyFromSourcePath(relativeSourcePath) {
-	const extension = relativeSourcePath.match(/\.(?:md|mdc)$/iu)?.[0];
-	if (!extension) return Result.fail({
-		field: "sourcePath",
-		message: `Document source must be a Markdown file: "${relativeSourcePath}".`
-	});
-	const segments = relativeSourcePath.slice(0, -extension.length).split("/");
-	if (segments.at(-1)?.toLocaleLowerCase() === "index") segments.pop();
-	return normalizeDocumentRelativePath(segments.join("/")).pipe(Result.flatMap(normalizePublicPath));
-}
 function localizeDocumentPath(key, locale, configuration) {
 	if (!configuration || !locale || locale === configuration.defaultLocale && !configuration.prefixDefaultLocale) return key;
 	return PublicPath.make(`/${locale}${key === "/" ? "" : key}`);
@@ -95,7 +86,7 @@ var DocumentEngineConfigurationInvalid = class extends Schema.TaggedError()("Doc
 	field: Schema.optionalKey(Schema.NonEmptyString)
 }) {};
 var DocumentParseFailed = class extends Schema.TaggedError()("DocumentEngine.DocumentParseFailed", {
-	sourcePath: SourcePath,
+	documentId: DocumentId,
 	cause: Schema.Defect()
 }) {};
 var DocumentCompilationFailed = class extends Schema.TaggedError()("DocumentEngine.DocumentCompilationFailed", { issues: Schema.Array(DocumentIssue) }) {};
@@ -209,12 +200,12 @@ function normalizeText(value) {
 
 //#endregion
 //#region ../document/src/internal/document-engine/frontmatter-validation.ts
-const validateFrontmatter = Effect.fn("DocumentEngine.validateFrontmatter")(function* (raw, schema, type, sourcePath) {
+const validateFrontmatter = Effect.fn("DocumentEngine.validateFrontmatter")(function* (raw, schema, type, documentId) {
 	const projection = schema.project(raw);
-	const issues = projection.unknownPaths.toSorted().map((path) => unknownFieldIssue(path, type, sourcePath));
+	const issues = projection.unknownPaths.toSorted().map((path) => unknownFieldIssue(path, type, documentId));
 	const result = yield* schema.validate(projection.value);
 	if ("issues" in result) {
-		issues.push(...result.issues.map((issue) => schemaIssue(issue, projection.value, type, sourcePath)));
+		issues.push(...result.issues.map((issue) => schemaIssue(issue, projection.value, type, documentId)));
 		return {
 			data: projection.value,
 			issues
@@ -222,7 +213,7 @@ const validateFrontmatter = Effect.fn("DocumentEngine.validateFrontmatter")(func
 	}
 	const parsed = Schema.decodeUnknownOption(Schema.JsonObject)(result.value);
 	if (Option.isNone(parsed)) {
-		issues.push(issue("schema.constraint", "The collection schema output must be a JSON-compatible object.", type, sourcePath, "frontmatter"));
+		issues.push(issue("schema.constraint", "The collection schema output must be a JSON-compatible object.", type, documentId, "frontmatter"));
 		return {
 			data: projection.value,
 			issues
@@ -236,13 +227,13 @@ const validateFrontmatter = Effect.fn("DocumentEngine.validateFrontmatter")(func
 		issues
 	};
 });
-function unknownFieldIssue(path, type, sourcePath) {
-	if (path === "id") return issue("document.id", "Document identity is managed by the CMS and cannot be authored in frontmatter.", type, sourcePath, path);
-	return issue("schema.unknown", `Frontmatter field "${path}" is not declared by collection "${type.collection}".`, type, sourcePath, path);
+function unknownFieldIssue(path, type, documentId) {
+	if (path === "id") return issue("document.id", "Document identity is managed by the CMS and cannot be authored in frontmatter.", type, documentId, path);
+	return issue("schema.unknown", `Frontmatter field "${path}" is not declared by collection "${type.collection}".`, type, documentId, path);
 }
-function schemaIssue(error, input, type, sourcePath) {
+function schemaIssue(error, input, type, documentId) {
 	const field = issuePath(error.path);
-	return issue(issueCode(error, input, field), error.message, type, sourcePath, field || void 0);
+	return issue(issueCode(error, input, field), error.message, type, documentId, field || void 0);
 }
 function issueCode(error, input, field) {
 	if (error.code === "invalid_type") return nestedValue(input, field) === void 0 ? "schema.required" : "schema.type";
@@ -262,14 +253,14 @@ function nestedValue(value, path) {
 		return Schema.is(Schema.JsonObject)(current) ? current[segment] : void 0;
 	}, value);
 }
-function issue(code, message, type, sourcePath, field) {
+function issue(code, message, type, documentId, field) {
 	return {
 		code,
 		collection: type.collection,
 		...field === void 0 ? void 0 : { field },
 		message,
 		severity: "error",
-		sourcePath
+		documentId
 	};
 }
 
@@ -277,26 +268,27 @@ function issue(code, message, type, sourcePath, field) {
 //#region ../document/src/internal/document-engine/compilation.ts
 const isDocumentParseFailed$1 = Schema.is(DocumentParseFailed);
 const compileCompiledDocument = Effect.fn("DocumentEngine.compileDocument")(function* (configuration, parseMarkdown, source) {
-	const location = yield* resolveSourceLocation(configuration, source);
+	const collection = yield* resolveCollection(configuration, source);
 	const parsedBody = yield* parseBody(parseMarkdown, source);
 	const mappings = yield* sourceMappings(parsedBody, source);
 	const body = normalizeCmsComponentBindings(withoutSourceMappings(parsedBody), configuration.components);
 	const { collectionFrontmatter, rawSeo } = splitFrontmatter(body.frontmatter);
-	const seoProjection = projectSeo(rawSeo, source.sourcePath);
-	const relativeKey = yield* fromAddressResult(documentKeyFromSourcePath(location.relativeSourcePath), source.sourcePath);
-	const validation = yield* validateFrontmatter(collectionFrontmatter, location.type.schema, location.type.definition, source.sourcePath).pipe(Effect.mapError((cause) => new DocumentCompilationFailed({ issues: [{
+	const seoProjection = projectSeo(rawSeo, source.identity.documentId);
+	const validation = yield* validateFrontmatter(collectionFrontmatter, collection.schema, collection.definition, source.identity.documentId).pipe(Effect.mapError((cause) => new DocumentCompilationFailed({ issues: [{
 		code: "schema.constraint",
-		collection: location.type.definition.collection,
+		collection: collection.definition.collection,
+		documentId: source.identity.documentId,
 		message: cause.message,
-		severity: "error",
-		sourcePath: source.sourcePath
+		severity: "error"
 	}] })));
-	const address = resolveDocumentAddress(location.type.address, relativeKey, validation.data);
-	const key = Result.isSuccess(address) ? address.success : provisionalKey(source.documentId);
-	const path = localizeDocumentPath(key, location.locale, configuration.documents.locales);
-	const title = stringValue(validation.data.title) ?? stringValue(body.meta.title) ?? titleFromSource(location.relativeSourcePath);
+	const relativeKey = PublicPath.make(source.placement.kind === "home" ? "/" : `/${source.placement.slug}`);
+	const route = source.placement.kind === "home" ? collection.homeRoute : collection.entryRoute;
+	const address = resolveDocumentAddress(route, relativeKey, validation.data);
+	const key = Result.isSuccess(address) ? address.success : provisionalKey(source.identity.documentId);
+	const path = localizeDocumentPath(key, source.identity.locale, configuration.documents.locales);
+	const title = stringValue(validation.data.title) ?? stringValue(body.meta.title) ?? (source.placement.kind === "home" ? collection.definition.label : humanize(source.placement.slug));
 	const description = stringValue(validation.data.description) ?? stringValue(body.meta.description);
-	const issues = Result.isSuccess(address) ? validation.issues : [...validation.issues, addressIssue(address.failure, source.sourcePath)];
+	const issues = Result.isSuccess(address) ? validation.issues : [...validation.issues, addressIssue(address.failure, source.identity.documentId)];
 	const canonicalFrontmatter = rawSeo === void 0 ? validation.data : Object.assign({ _seo: rawSeo }, validation.data);
 	const canonicalBody = CmsMarkdownDocument.make({
 		frontmatter: canonicalFrontmatter,
@@ -308,32 +300,35 @@ const compileCompiledDocument = Effect.fn("DocumentEngine.compileDocument")(func
 		title
 	});
 	return CompiledDocument.make(Object.assign({
-		id: source.documentId,
+		id: source.identity.documentId,
+		identity: source.identity,
+		placement: source.placement,
 		key,
 		path,
-		collection: location.type.definition.collection,
+		collection: source.identity.collection,
 		draft: source.draft,
 		title,
 		data: validation.data,
 		issues: [
 			...issues,
 			...seoProjection.issues,
-			...(configuration.validateAuthoringDocument?.(canonicalBody, location.type.definition.body) ?? []).map((message) => ({
+			...(configuration.validateAuthoringDocument?.(canonicalBody, collection.definition.body) ?? []).map((issue) => ({
 				code: "reference.component",
-				message,
-				severity: "error",
-				sourcePath: source.sourcePath
+				component: issue.component,
+				documentId: source.identity.documentId,
+				...issue.field ? { field: issue.field.join(".") } : void 0,
+				message: issue.message,
+				severity: "error"
 			}))
 		],
 		analysis,
 		body: canonicalBody,
 		engineFingerprint: DOCUMENT_ENGINE_FINGERPRINT,
 		source: {
-			path: source.sourcePath,
 			mappings,
 			...source.publishedAt === void 0 ? void 0 : { publishedAt: source.publishedAt }
 		}
-	}, location.locale === void 0 ? void 0 : { locale: location.locale }, description === void 0 ? void 0 : { description }, seoProjection.seo === void 0 ? void 0 : { seo: seoProjection.seo }));
+	}, source.identity.locale === void 0 ? void 0 : { locale: source.identity.locale }, description === void 0 ? void 0 : { description }, seoProjection.seo === void 0 ? void 0 : { seo: seoProjection.seo }));
 });
 function splitFrontmatter(frontmatter) {
 	const { _seo: rawSeo, ...collectionFrontmatter } = frontmatter;
@@ -342,7 +337,7 @@ function splitFrontmatter(frontmatter) {
 		rawSeo
 	};
 }
-function projectSeo(rawSeo, sourcePath) {
+function projectSeo(rawSeo, documentId) {
 	if (rawSeo === void 0) return { issues: [] };
 	const decoded = Schema.decodeUnknownResult(DocumentSeo)(rawSeo, { onExcessProperty: "error" });
 	if (Result.isSuccess(decoded)) return {
@@ -351,83 +346,60 @@ function projectSeo(rawSeo, sourcePath) {
 	};
 	return { issues: [{
 		code: "seo.invalid",
+		documentId,
 		field: "_seo",
 		message: `Document SEO is invalid: ${String(decoded.failure)}`,
-		severity: "error",
-		sourcePath
+		severity: "error"
 	}] };
 }
 function provisionalKey(documentId) {
 	return PublicPath.make(`/_cms-invalid/${documentId}`);
 }
-function addressIssue(error, sourcePath) {
-	const issue = {
+function addressIssue(error, documentId) {
+	return {
 		code: "document.invalid",
+		documentId,
+		...error.field === void 0 ? void 0 : { field: error.field },
 		message: error.message,
-		severity: "error",
-		sourcePath
-	};
-	return error.field === void 0 ? issue : {
-		...issue,
-		field: error.field
+		severity: "error"
 	};
 }
-function resolveSourceLocation(configuration, source) {
-	const segments = source.sourcePath.split("/");
-	let locale;
-	if (configuration.documents.locales) {
-		const candidate = segments.shift();
-		locale = configuration.documents.locales.locales.find((value) => value === candidate);
-		if (!locale) return compilationFailure({
-			code: "document.invalid",
-			field: "locale",
-			message: `Localized document "${source.sourcePath}" must begin with a configured locale.`,
-			severity: "error",
-			sourcePath: source.sourcePath
-		});
-	}
-	const localizedSourcePath = segments.join("/");
-	const type = configuration.types.find(({ definition }) => definition.directory === "." || localizedSourcePath.startsWith(`${definition.directory}/`));
-	if (!type) return compilationFailure({
+function resolveCollection(configuration, source) {
+	const collection = configuration.types.find(({ definition }) => definition.collection === source.identity.collection);
+	if (!collection) return compilationFailure({
 		code: "document.invalid",
-		field: "sourcePath",
-		message: `No document collection contains "${source.sourcePath}".`,
-		severity: "error",
-		sourcePath: source.sourcePath
+		documentId: source.identity.documentId,
+		field: "identity.collection",
+		message: `Document collection "${source.identity.collection}" does not exist.`,
+		severity: "error"
 	});
-	const relativeSourcePath = type.definition.directory === "." ? localizedSourcePath : localizedSourcePath.slice(type.definition.directory.length + 1);
-	if (!relativeSourcePath) return compilationFailure({
+	const locales = configuration.documents.locales;
+	const locale = source.identity.locale;
+	if (!locales && locale !== void 0 || locales && (locale === void 0 || !locales.locales.includes(locale))) return compilationFailure({
 		code: "document.invalid",
-		field: "sourcePath",
-		message: `Document source "${source.sourcePath}" has no collection-relative path.`,
-		severity: "error",
-		sourcePath: source.sourcePath
-	});
-	return Effect.succeed(locale === void 0 ? {
-		relativeSourcePath,
-		type
-	} : {
-		locale,
-		relativeSourcePath,
-		type
+		documentId: source.identity.documentId,
+		field: "identity.locale",
+		message: locale ? `Document locale "${locale}" is not configured.` : "A locale is required for this document.",
+		severity: "error"
 	});
+	return Effect.succeed(collection);
 }
 function parseBody(parseMarkdown, source) {
 	return Effect.tryPromise({
 		try: () => parseMarkdown(source.markdown),
 		catch: (cause) => new DocumentParseFailed({
 			cause,
-			sourcePath: source.sourcePath
+			documentId: source.identity.documentId
 		})
 	}).pipe(Effect.flatMap(Schema.decodeUnknownEffect(CmsMarkdownDocument)), Effect.mapError((cause) => isDocumentParseFailed$1(cause) ? cause : new DocumentParseFailed({
 		cause,
-		sourcePath: source.sourcePath
+		documentId: source.identity.documentId
 	})));
 }
 function sourceMappings(body, source) {
 	return Schema.decodeUnknownEffect(Schema.Array(DocumentSourceMapping))(body.meta["__cmsSourceMappings"] ?? []).pipe(Effect.mapError((cause) => new DocumentParseFailed({
 		cause,
-		sourcePath: source.sourcePath
+		documentId: source.identity.documentId
 	})));
 }
 function withoutSourceMappings(body) {
@@ -438,25 +410,21 @@ function withoutSourceMappings(body) {
 		nodes: body.nodes
 	});
 }
-function fromAddressResult(result, sourcePath) {
-	if (Result.isSuccess(result)) return Effect.succeed(result.success);
-	return compilationFailure(addressIssue(result.failure, sourcePath));
-}
 function compilationFailure(issue) {
 	return Effect.fail(new DocumentCompilationFailed({ issues: [issue] }));
 }
 function stringValue(value) {
 	return Predicate.isString(value) && value.trim() ? value.trim() : void 0;
 }
-function titleFromSource(sourcePath) {
-	const stem = (sourcePath.split("/").at(-1) ?? "content").replace(/\.(?:md|mdc)$/iu, "");
-	return (stem.toLocaleLowerCase() === "index" ? sourcePath.split("/").at(-2) ?? "home" : stem).replace(/[-_]+/gu, " ").replace(/^./u, (character) => character.toLocaleUpperCase());
+function humanize(value) {
+	return value.replace(/[-_]+/gu, " ").replace(/^./u, (character) => character.toLocaleUpperCase());
 }
 
 //#endregion
 //#region ../document/src/internal/document-engine/catalog-lookup.ts
 function createCatalogLookup(documents, configuration) {
 	const byPath = new Map(documents.map((document) => [document.path, document]));
+	const byId = new Map(documents.map((document) => [document.id, document]));
 	const byVariant = new Map(documents.map((document) => [localeAndKey(document.locale, document.key), document]));
 	const findByKey = (input, locale) => {
 		const keyResult = normalizePublicPath(input);
@@ -486,6 +454,7 @@ function createCatalogLookup(documents, configuration) {
 		return Option.fromNullishOr(byVariant.get(localeAndKey(locales.fallbackLocale, request.key)));
 	};
 	return {
+		findById: (documentId) => Option.fromNullishOr(byId.get(documentId)),
 		findByKey,
 		findByPath
 	};
@@ -519,15 +488,14 @@ function collisionIssues(documents) {
 	const byPath = /* @__PURE__ */ new Map();
 	const byVariant = /* @__PURE__ */ new Map();
 	for (const document of documents) {
-		const identityCollision = byId.get(document.id);
-		if (identityCollision) issues.push(collisionIssue(`Document identity collision for "${document.id}" between "${identityCollision.source.path}" and "${document.source.path}".`, document));
+		if (byId.get(document.id)) issues.push(collisionIssue(`Document identity collision for "${document.id}".`, document));
 		else byId.set(document.id, document);
 		const pathCollision = byPath.get(document.path);
-		if (pathCollision) issues.push(collisionIssue(`Document route collision at "${document.path}" between "${pathCollision.source.path}" and "${document.source.path}".`, document, document.path));
+		if (pathCollision) issues.push(collisionIssue(`Document route collision at "${document.path}" between documents "${pathCollision.id}" and "${document.id}".`, document, document.path));
 		else byPath.set(document.path, document);
 		const variant = localeAndKey(document.locale, document.key);
 		const variantCollision = byVariant.get(variant);
-		if (variantCollision && variantCollision.path !== pathCollision?.path) issues.push(collisionIssue(`Document locale collision at "${document.key}" between "${variantCollision.source.path}" and "${document.source.path}".`, document, document.key));
+		if (variantCollision && variantCollision.path !== pathCollision?.path) issues.push(collisionIssue(`Document locale collision at "${document.key}" between documents "${variantCollision.id}" and "${document.id}".`, document, document.key));
 		else byVariant.set(variant, document);
 	}
 	return issues;
@@ -549,21 +517,15 @@ function collisionIssue(message, document, key) {
 		code: "document.collision",
 		message,
 		severity: "error",
-		sourcePath: document.source.path
+		documentId: document.id
 	};
 	return key === void 0 ? issue : Object.assign(issue, { key });
 }
 
 //#endregion
 //#region ../document/src/internal/document-engine/reference-target.ts
-function referenceTarget(tag, attributes, documentPath, mediaBaseUrl) {
-	if (tag === "a") {
-		const path = documentTarget(attributes.get("href"), documentPath);
-		return path ? {
-			kind: "document",
-			path
-		} : void 0;
-	}
+function referenceTarget(tag, attributes, mediaBaseUrl) {
+	if (tag === "a") return decodeDocumentReference(attributes.get("href"));
 	if (tag === "img") {
 		const key = mediaKey(attributes.get("src"), mediaBaseUrl);
 		return key ? {
@@ -580,10 +542,29 @@ function referenceTarget(tag, attributes, documentPath, mediaBaseUrl) {
 function targetKey(target) {
 	switch (target.kind) {
 		case "component": return `component:${target.name.toLocaleLowerCase()}`;
-		case "document": return `document:${target.path}`;
+		case "document": return `document:${target.documentId}`;
 		case "media": return `media:${target.key}`;
 	}
 }
+function decodeDocumentReference(value) {
+	if (!Predicate.isString(value)) return void 0;
+	const reference = decodeAuthoredDocumentReference(value);
+	return reference ? {
+		kind: "document",
+		...reference
+	} : void 0;
+}
+function decodeMediaReference(value, mediaBaseUrl) {
+	if (!Predicate.isString(value)) return void 0;
+	const reference = decodeManagedMediaReference(value);
+	if (!reference) return void 0;
+	const key = mediaKey(reference.lastKnownUrl, mediaBaseUrl);
+	return key ? {
+		kind: "media",
+		key,
+		mediaId: reference.mediaId
+	} : void 0;
+}
 function mediaKey(value, mediaBaseUrl) {
 	if (!Predicate.isString(value) || mediaBaseUrl === void 0) return void 0;
 	const prefix = `${mediaBaseUrl}/`;
@@ -599,25 +580,6 @@ function mediaKey(value, mediaBaseUrl) {
 		return;
 	}
 }
-function documentTarget(value, documentPath) {
-	if (!Predicate.isString(value)) return void 0;
-	const href = value.trim();
-	if (!href || href.startsWith("#") || href.startsWith("?") || href.startsWith("//") || /^[a-z][a-z\d+.-]*:/iu.test(href)) return;
-	const resolvedPath = resolveRelativePath(href.split(/[?#]/u)[0] ?? "", documentPath);
-	if ((resolvedPath.split("/").at(-1) ?? "").includes(".")) return void 0;
-	const normalized = normalizePublicPath(resolvedPath);
-	return Result.isSuccess(normalized) ? normalized.success : void 0;
-}
-function resolveRelativePath(href, documentPath) {
-	const normalizedHref = href.replace(/\\/gu, "/");
-	const segments = normalizedHref.startsWith("/") ? [] : documentPath.split("/").filter(Boolean).slice(0, -1);
-	for (const segment of normalizedHref.split("/")) {
-		if (!segment || segment === ".") continue;
-		if (segment === "..") segments.pop();
-		else segments.push(segment);
-	}
-	return `/${segments.join("/")}`;
-}
 function hasControlCharacter(value) {
 	for (const character of value) {
 		const codePoint = character.codePointAt(0);
@@ -629,19 +591,24 @@ function hasControlCharacter(value) {
 //#endregion
 //#region ../document/src/internal/document-engine/references.ts
 const noReferences = Object.freeze([]);
-function createDocumentReferenceIndex(documents, configuration, findByPath) {
+function createDocumentReferenceIndex(documents, configuration, findById) {
 	const all = [];
 	const byTarget = /* @__PURE__ */ new Map();
 	const issues = /* @__PURE__ */ new Map();
 	for (const document of documents) {
+		const invalidManagedMedia = (lastKnownUrl) => addIssue(issues, document.id, {
+			code: "reference.media",
+			documentId: document.id,
+			message: `Managed-media reference "${lastKnownUrl}" is outside the configured media library.`,
+			severity: "error"
+		});
 		const indexTarget = (target, nodePath) => {
 			if (!target) return;
 			const reference = freezeReference({
 				nodePath,
 				source: {
 					documentId: document.id,
-					path: document.path,
-					sourcePath: document.source.path
+					route: document.path
 				},
 				target
 			});
@@ -650,18 +617,20 @@ function createDocumentReferenceIndex(documents, configuration, findByPath) {
 			const matching = byTarget.get(key) ?? [];
 			matching.push(reference);
 			byTarget.set(key, matching);
-			if (target.kind === "document" && Option.isNone(findByPath(target.path))) addIssue(issues, document.source.path, {
+			if (target.kind === "document" && Option.isNone(findById(target.documentId))) addIssue(issues, document.id, {
 				code: "reference.document",
-				key: target.path,
-				message: `Document link "${target.path}" does not resolve.`,
-				severity: "error",
-				sourcePath: document.source.path
+				documentId: document.id,
+				key: target.lastKnownRoute,
+				message: `Document link target "${target.documentId}" does not resolve.`,
+				severity: "error"
 			});
 		};
-		const seoImageTarget = document.seo?.socialImage ? referenceTarget("img", /* @__PURE__ */ new Map([["src", document.seo.socialImage.url]]), document.path, configuration.mediaBaseUrl) : void 0;
+		const seoImageTarget = document.seo?.socialImage ? referenceTarget("img", /* @__PURE__ */ new Map([["src", document.seo.socialImage.url]]), configuration.mediaBaseUrl) : void 0;
 		indexTarget(seoImageTarget?.kind === "media" ? Object.assign({}, seoImageTarget, { mediaId: document.seo?.socialImage?.mediaId }) : seoImageTarget, []);
+		const collection = configuration.types.find(({ definition }) => definition.collection === document.collection);
+		for (const target of propertyTargets(collection?.definition.authoringFields ?? [], document.data, configuration.mediaBaseUrl, invalidManagedMedia)) indexTarget(target, []);
 		visit(document.body.nodes, createCmsComarkRenderData(document.body), (tag, attributes, children, nodePath) => {
-			const targets = [referenceTarget(tag, attributes, document.path, configuration.mediaBaseUrl), ...propertyTargets(configuration.components?.get(tag.toLowerCase())?.authoring.props ?? [], Object.fromEntries([...attributes].flatMap(([key, value]) => value === void 0 ? [] : [[key, value]])), document.path, configuration.mediaBaseUrl)];
+			const targets = [referenceTarget(tag, attributes, configuration.mediaBaseUrl), ...propertyTargets(configuration.components?.get(tag.toLowerCase())?.authoring.props ?? [], Object.fromEntries([...attributes].flatMap(([key, value]) => value === void 0 ? [] : [[key, value]])), configuration.mediaBaseUrl, invalidManagedMedia)];
 			for (const target of targets) indexTarget(target, nodePath);
 		});
 	}
@@ -692,19 +661,31 @@ function freezeReference(reference) {
 		target: Object.freeze({ ...reference.target })
 	});
 }
-function addIssue(issues, sourcePath, issue) {
-	const sourceIssues = issues.get(sourcePath) ?? [];
+function addIssue(issues, documentId, issue) {
+	const sourceIssues = issues.get(documentId) ?? [];
 	sourceIssues.push(issue);
-	issues.set(sourcePath, sourceIssues);
+	issues.set(documentId, sourceIssues);
 }
-function propertyTargets(fields, values, path, mediaBaseUrl) {
+function propertyTargets(fields, values, mediaBaseUrl, onInvalidManagedMedia) {
 	return fields.flatMap((field) => {
 		const value = values[field.name] === void 0 ? field.defaultValue : values[field.name];
+		if (field.input === "document") {
+			const target = decodeDocumentReference(value);
+			return target ? [target] : [];
+		}
+		if (field.input === "media") {
+			const target = decodeMediaReference(value, mediaBaseUrl);
+			if (!target && Predicate.isString(value)) {
+				const reference = decodeManagedMediaReference(value);
+				if (reference) onInvalidManagedMedia(reference.lastKnownUrl);
+			}
+			return target ? [target] : [];
+		}
 		if (field.input === "link" || field.input === "image") {
-			const target = referenceTarget(field.input === "link" ? "a" : "img", /* @__PURE__ */ new Map([[field.input === "link" ? "href" : "src", value]]), path, mediaBaseUrl);
+			const target = referenceTarget(field.input === "link" ? "a" : "img", /* @__PURE__ */ new Map([[field.input === "link" ? "href" : "src", value]]), mediaBaseUrl);
 			return target ? [target] : [];
 		}
-		if (field.fields) return (Array.isArray(value) ? value : [value]).flatMap((entry) => Schema.is(Schema.JsonObject)(entry) ? propertyTargets(field.fields ?? [], entry, path, mediaBaseUrl) : []);
+		if (field.fields) return (Array.isArray(value) ? value : [value]).flatMap((entry) => Schema.is(Schema.JsonObject)(entry) ? propertyTargets(field.fields ?? [], entry, mediaBaseUrl, onInvalidManagedMedia) : []);
 		return [];
 	});
 }
@@ -712,44 +693,168 @@ function propertyTargets(fields, values, path, mediaBaseUrl) {
 //#endregion
 //#region ../document/src/internal/document-engine/catalog.ts
 function createDocumentCatalog(configuration, input) {
-	const documents = [...input].sort((left, right) => left.source.path.localeCompare(right.source.path));
+	const resolved = resolvePlacementGraph(configuration, input);
+	if (Result.isFailure(resolved)) return Result.fail(resolved.failure);
+	const documents = resolved.success.toSorted((left, right) => left.path.localeCompare(right.path));
 	const collisions = collisionIssues(documents);
 	if (collisions.length > 0) return Result.fail(new DocumentCompilationFailed({ issues: collisions }));
 	const lookup = createCatalogLookup(documents, configuration);
-	const references = createDocumentReferenceIndex(documents, configuration, lookup.findByPath);
+	const references = createDocumentReferenceIndex(documents, configuration, lookup.findById);
 	const withReferenceIssues = documents.map((document) => {
-		const additional = references.issues.get(document.source.path) ?? [];
-		return additional.length === 0 ? document : CompiledDocument.make(Object.assign({}, document, { issues: [...document.issues, ...additional] }));
+		const additional = references.issues.get(document.id) ?? [];
+		const projected = resolveSemanticRoutes(document, lookup.findById);
+		return additional.length === 0 ? projected : CompiledDocument.make(Object.assign({}, projected, { issues: [...document.issues, ...additional] }));
 	});
+	const finalLookup = createCatalogLookup(withReferenceIssues, configuration);
 	return Result.succeed({
 		documents: withReferenceIssues,
 		issues: [...withReferenceIssues.flatMap((document) => document.issues), ...translationIssues(withReferenceIssues, configuration)],
-		...createCatalogLookup(withReferenceIssues, configuration),
+		...finalLookup,
 		references: references.index
 	});
 }
+function resolveSemanticRoutes(document, findById) {
+	const nodes = document.body.nodes.map((node) => resolveNodeReferences(node, findById));
+	const data = resolveJsonObjectReferences(document.data, findById);
+	const frontmatter = resolveJsonObjectReferences(document.body.frontmatter, findById);
+	return CompiledDocument.make(Object.assign({}, document, {
+		data,
+		body: Object.assign({}, document.body, {
+			frontmatter,
+			nodes
+		})
+	}));
+}
+function resolveNodeReferences(node, findById) {
+	if (Schema.is(Schema.String)(node)) return node;
+	const [tag, attributes, ...children] = node;
+	if (tag === null) return node;
+	return [
+		tag,
+		resolveJsonObjectReferences(attributes, findById),
+		...children.map((child) => resolveNodeReferences(child, findById))
+	];
+}
+function resolveJsonObjectReferences(value, findById) {
+	return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolveJsonReferences(entry, findById)]));
+}
+function resolveJsonReferences(value, findById) {
+	if (Schema.is(Schema.String)(value)) {
+		const reference = decodeDocumentReference(value);
+		if (reference?.kind === "document") {
+			const target = findById(reference.documentId);
+			return Option.isSome(target) ? target.value.path : reference.lastKnownRoute;
+		}
+		return decodeManagedMediaReference(value)?.lastKnownUrl ?? value;
+	}
+	if (Array.isArray(value)) return value.map((entry) => resolveJsonReferences(entry, findById));
+	if (Schema.is(Schema.JsonObject)(value)) return resolveJsonObjectReferences(value, findById);
+	return value;
+}
+function resolvePlacementGraph(configuration, documents) {
+	const byId = /* @__PURE__ */ new Map();
+	const homes = /* @__PURE__ */ new Map();
+	const issues = [];
+	for (const document of documents) {
+		if (byId.get(document.id)) {
+			issues.push(invalid$1(document, `Document identity "${document.id}" appears more than once.`));
+			continue;
+		}
+		byId.set(document.id, document);
+		if (document.placement.kind === "home") {
+			const key = identityScope(document);
+			const existing = homes.get(key);
+			if (existing) issues.push(invalid$1(document, `Documents "${existing.id}" and "${document.id}" are both home documents for collection "${document.collection}"${document.locale ? ` in locale "${document.locale}"` : ""}.`));
+			else homes.set(key, document);
+		}
+	}
+	const segments = /* @__PURE__ */ new Map();
+	const visiting = /* @__PURE__ */ new Set();
+	const resolveSegments = (document) => {
+		const cached = segments.get(document.id);
+		if (cached) return cached;
+		if (visiting.has(document.id)) {
+			issues.push(invalid$1(document, `Document placement cycle includes "${document.id}".`, "placement"));
+			return;
+		}
+		visiting.add(document.id);
+		let result;
+		if (document.placement.kind === "home") result = [];
+		else {
+			const parent = byId.get(document.placement.parentDocumentId);
+			if (!parent) issues.push(invalid$1(document, `Parent document "${document.placement.parentDocumentId}" does not exist in this catalog.`, "placement.parentDocumentId"));
+			else if (parent.collection !== document.collection) issues.push(invalid$1(document, "A parent document must belong to the same collection.", "placement.parentDocumentId"));
+			else if (parent.locale !== document.locale) issues.push(invalid$1(document, "A parent document must use the same locale.", "placement.parentDocumentId"));
+			else {
+				const collection = configuration.types.find(({ definition }) => definition.collection === document.collection);
+				if (!collection) issues.push(invalid$1(document, `Collection "${document.collection}" is not configured.`));
+				else if (!collection.definition.hierarchy && parent.placement.kind !== "home") issues.push(invalid$1(document, "This collection allows entries only directly below its home document.", "placement"));
+				else {
+					const parentSegments = resolveSegments(parent);
+					if (parentSegments) result = [...parentSegments, document.placement.slug];
+				}
+			}
+		}
+		visiting.delete(document.id);
+		if (result) segments.set(document.id, result);
+		return result;
+	};
+	for (const document of documents) resolveSegments(document);
+	if (issues.length > 0) return Result.fail(new DocumentCompilationFailed({ issues }));
+	const projected = documents.map((document) => {
+		const collection = configuration.types.find(({ definition }) => definition.collection === document.collection);
+		const placementSegments = segments.get(document.id);
+		if (!collection || !placementSegments) return document;
+		const relativeKey = PublicPath.make(`/${placementSegments.join("/")}`);
+		const configuredRoute = document.placement.kind === "home" ? collection.homeRoute : collection.entryRoute;
+		const route = resolveDocumentAddress(configuredRoute, relativeKey, document.data);
+		if (Result.isFailure(route)) {
+			issues.push(invalid$1(document, route.failure.message, route.failure.field));
+			return document;
+		}
+		return CompiledDocument.make(Object.assign({}, document, {
+			key: route.success,
+			path: localizeDocumentPath(route.success, document.locale, configuration.documents.locales)
+		}));
+	});
+	return issues.length > 0 ? Result.fail(new DocumentCompilationFailed({ issues })) : Result.succeed(projected);
+}
+function identityScope(document) {
+	return `${document.collection}:${document.locale ?? ""}`;
+}
+function invalid$1(document, message, field) {
+	return {
+		code: "document.invalid",
+		collection: document.collection,
+		documentId: document.id,
+		...field === void 0 ? void 0 : { field },
+		...document.locale === void 0 ? void 0 : { locale: document.locale },
+		message,
+		severity: "error"
+	};
+}
 
 //#endregion
 //#region ../document/src/internal/document-engine/configuration.ts
 function resolveDocumentEngineConfiguration(documents, options) {
 	if (documents.types.length === 0) return invalid("Documents must define at least one collection.", "types");
 	const collections = /* @__PURE__ */ new Set();
-	const directories = /* @__PURE__ */ new Map();
 	const resolved = [];
 	for (const definition of documents.types) {
 		if (collections.has(definition.collection)) return invalid(`Document collection "${definition.collection}" is defined more than once.`, "types");
 		collections.add(definition.collection);
-		const existing = directories.get(definition.directory);
-		if (existing) return invalid(`Document collections "${existing}" and "${definition.collection}" use the same directory "${definition.directory}".`, "types");
-		directories.set(definition.directory, definition.collection);
-		const addressResult = parseDocumentAddress(definition.addressPattern);
-		if (Result.isFailure(addressResult)) return invalid(addressResult.failure.message, addressResult.failure.field);
-		if (definition.hierarchy && !addressResult.success.tokens.some((token) => token.catchAll)) return invalid(`Document collection "${definition.collection}" can only enable hierarchy with a catch-all address.`, "types");
+		const homeRoute = parseDocumentAddress(definition.routes.home);
+		const entryRoute = parseDocumentAddress(definition.routes.entry);
+		if (Result.isFailure(homeRoute)) return invalid(homeRoute.failure.message, homeRoute.failure.field);
+		if (Result.isFailure(entryRoute)) return invalid(entryRoute.failure.message, entryRoute.failure.field);
+		if (homeRoute.success.tokens.length > 0) return invalid(`Document collection "${definition.collection}" home route cannot contain tokens.`, "types");
+		if (definition.hierarchy && !entryRoute.success.tokens.some((token) => token.catchAll)) return invalid(`Document collection "${definition.collection}" can only enable hierarchy with a catch-all entry route.`, "types");
 		const schema = options.documentModel.types[definition.collection];
 		if (!schema) return invalid(`Document collection "${definition.collection}" has no executable schema.`, "documentModel");
 		resolved.push({
-			address: addressResult.success,
 			definition,
+			entryRoute: entryRoute.success,
+			homeRoute: homeRoute.success,
 			schema
 		});
 	}
@@ -772,7 +877,6 @@ function resolveDocumentEngineConfiguration(documents, options) {
 		}
 	}
 	const mediaBaseUrl = options.mediaBaseUrl?.replace(/\/+$/u, "");
-	resolved.sort((left, right) => directoryDepth(right.definition.directory) - directoryDepth(left.definition.directory));
 	const configuration = {
 		documents,
 		types: resolved
@@ -798,9 +902,6 @@ function resolveComponents(definitions) {
 		return invalid(cause instanceof Error ? cause.message : "The component authoring catalog is invalid.", "components");
 	}
 }
-function directoryDepth(directory) {
-	return directory === "." ? 0 : directory.split("/").length;
-}
 function invalid(message, field) {
 	return Result.fail(new DocumentEngineConfigurationInvalid(field === void 0 ? { message } : {
 		field,
@@ -819,14 +920,14 @@ const createDocumentEngine = Effect.fn("DocumentEngine.make")(function* (documen
 	const compileAll = Effect.fn("DocumentEngine.compileAll")(function* (input) {
 		const previous = input.previous ? compilations.get(input.previous) : void 0;
 		const compiled = yield* Effect.forEach(input.sources, (source) => {
-			const cached = previous?.get(source.documentId);
+			const cached = previous?.get(source.identity.documentId);
 			return cached && sameCompilationSource(cached.source, source) ? Effect.succeed(cached.document) : compile(source);
 		});
 		const catalog = yield* Effect.fromResult(createDocumentCatalog(configuration, compiled));
 		compilations.set(catalog, new Map(input.sources.map((source, index) => {
 			const document = compiled[index];
-			if (!document) throw new Error(`Compiled document "${source.documentId}" is missing.`);
-			return [source.documentId, {
+			if (!document) throw new Error(`Compiled document "${source.identity.documentId}" is missing.`);
+			return [source.identity.documentId, {
 				document,
 				source
 			}];
@@ -848,7 +949,7 @@ const createDocumentEngine = Effect.fn("DocumentEngine.make")(function* (documen
 			code: "markdown.parse",
 			message: errorMessage(error.cause),
 			severity: "error",
-			sourcePath: error.sourcePath
+			documentId: error.documentId
 		}] : error.issues;
 		return DocumentValidationResult.make({
 			valid: false,
@@ -863,7 +964,7 @@ const createDocumentEngine = Effect.fn("DocumentEngine.make")(function* (documen
 	};
 });
 function sameCompilationSource(left, right) {
-	return left.documentId === right.documentId && left.draft === right.draft && left.markdown === right.markdown && left.sourcePath === right.sourcePath && samePublishedAt(left.publishedAt, right.publishedAt);
+	return left.identity.documentId === right.identity.documentId && left.identity.collection === right.identity.collection && left.identity.locale === right.identity.locale && left.placement.kind === right.placement.kind && (left.placement.kind === "home" || right.placement.kind === "entry" && left.placement.parentDocumentId === right.placement.parentDocumentId && left.placement.slug === right.placement.slug) && left.draft === right.draft && left.markdown === right.markdown && samePublishedAt(left.publishedAt, right.publishedAt);
 }
 function samePublishedAt(left, right) {
 	return left === void 0 || right === void 0 ? left === right : DateTime.Equivalence(left, right);
@@ -873,5 +974,5 @@ function errorMessage(cause) {
 }
 
 //#endregion
-export { normalizeDocumentRelativePath as a, resolveDocumentAddress as c, localizeDocumentPath as i, referenceTarget as n, normalizePublicPath as o, DocumentCompilationFailed as r, parseDocumentAddress as s, createDocumentEngine as t };
-//# sourceMappingURL=DocumentEngine-ClhFXW9M.js.map
+export { DocumentCompilationFailed as n, createDocumentEngine as t };
+//# sourceMappingURL=DocumentEngine-j6Vi7nQo.js.map