fix(codegen-ts): layout-aware field links in template-source docs

Field hrefs now route through docPageHref(layout,...) like the Payload link, so they resolve under package layout (../<pkg>/Owner.md) instead of a bare ./Owner.md. Annotator keeps the flat ./ default when no resolver is injected, so flat output is byte-identical. Partial {{>ref}} hrefs route through the same docPageHref so they resolve under package layout too.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/codegen-ts/src/generators/template-doc-builder.ts

@@ -32,6 +32,7 @@ import type { Provider } from "@metaobjectsdev/render";
 import { GENERATED_HEADER } from "../constants.js";
 import type { OutputLayout } from "../import-path.js";
 import { docPageHref, docPageNode, type DocPageNode } from "../docs-paths.js";
+import { fieldAnchorSlug } from "./field-anchor.js";
 import type { TemplateDocData, TemplateOutputPart } from "./template-doc-data.js";
 import { buildEnrichedPayloadTree } from "./template-payload-tree.js";
 import { annotateTemplate, type AnnotatePayloadField } from "./template-source-annotate.js";
@@ -174,6 +175,8 @@ export function buildTemplateDocData(
     const section = buildTemplateSourceSection({
       provider: opts.provider,
       root,
+      layout,
+      template,
       payloadName,
       // Document: the single @textRef (unlabeled). Email: one labeled part each.
       refs:
@@ -202,6 +205,12 @@ interface SourceRefSpec {
 interface BuildSectionArgs {
   provider: Provider;
   root: MetaRoot;
+  /** Page-placement layout — threaded so field/partial hrefs route through the
+   *  SAME docPageHref the Payload cross-link uses (resolves under package layout). */
+  layout: OutputLayout;
+  /** The `template.output` node whose page is being built — the FROM page for
+   *  every relative href on this section. */
+  template: MetaData;
   payloadName: string;
   refs: SourceRefSpec[];
 }
@@ -217,9 +226,23 @@ interface BuildSectionArgs {
  * resolved, so the caller omits the section entirely.
  */
 function buildTemplateSourceSection(args: BuildSectionArgs): string | undefined {
-  const { provider, root, payloadName, refs } = args;
+  const { provider, root, layout, template, payloadName, refs } = args;
   const tree: AnnotatePayloadField[] = buildEnrichedPayloadTree(root, payloadName);
-  const resolvePartialHref = makePartialHrefResolver(root);
+  const fromNode = docPageNode(template);
+
+  // Layout-aware field href: route through the SAME docPageHref the Payload
+  // cross-link uses, so the link lands on the owner VO's REAL page in BOTH
+  // layouts (flat → `./Owner.md`, package → `../<pkg>/Owner.md`). Resolve the
+  // owner's package off the root (by short name); fall back to a package-less
+  // node when it can't be resolved — mirroring the Payload link's fallback.
+  const fieldHref = (owner: string, name: string): string => {
+    const ownerObj = root.findObject(owner);
+    const toNode: DocPageNode =
+      ownerObj !== undefined ? docPageNode(ownerObj) : { name: owner };
+    return `${docPageHref(layout, fromNode, toNode)}#${fieldAnchorSlug(name)}`;
+  };
+
+  const resolvePartialHref = makePartialHrefResolver(root, layout, fromNode);
   const isMultipart = refs.length > 1 || refs.some((r) => r.label !== undefined);
 
   const blocks: string[] = [];
@@ -229,6 +252,7 @@ function buildTemplateSourceSection(args: BuildSectionArgs): string | undefined
     const tokens = annotateTemplate(source, tree, {
       ownerVoName: payloadName,
       resolvePartialHref,
+      fieldHref,
     });
     const parts: string[] = [];
     if (isMultipart && spec.label !== undefined) parts.push(`### ${spec.label}`);
@@ -244,15 +268,20 @@ function buildTemplateSourceSection(args: BuildSectionArgs): string | undefined
 }
 
 /**
- * A `{{>ref}}` partial-href resolver: returns `./<TemplateName>.md` when `ref`
- * is a mustache source documented by SOME `template.output` node (it is one of
- * that template's source refs — @textRef or an email part ref), else undefined
- * (the partial is highlight-only). This makes a partial that inlines another
- * documented template link to that template's page.
+ * A `{{>ref}}` partial-href resolver: returns a relative href to the page of the
+ * `template.output` node that documents `ref` (it is one of that template's
+ * source refs — @textRef or an email part ref), else undefined (the partial is
+ * highlight-only). The href routes through the SAME `docPageHref(layout, …)` the
+ * field/Payload links use, so it resolves in BOTH layouts (flat → `./Name.md`,
+ * package → a correct relative path like `../comms/OrderEmail.md`).
  */
-function makePartialHrefResolver(root: MetaRoot): (ref: string) => string | undefined {
-  // Map each documented source ref → the template node's short name.
-  const refToTemplate = new Map<string, string>();
+function makePartialHrefResolver(
+  root: MetaRoot,
+  layout: OutputLayout,
+  fromNode: DocPageNode,
+): (ref: string) => string | undefined {
+  // Map each documented source ref → the template node that documents it.
+  const refToTemplate = new Map<string, MetaData>();
   for (const child of root.ownChildren()) {
     if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
     for (const attr of [
@@ -263,12 +292,12 @@ function makePartialHrefResolver(root: MetaRoot): (ref: string) => string | unde
     ]) {
       const v = child.ownAttr(attr);
       if (typeof v === "string" && v.length > 0 && !refToTemplate.has(v)) {
-        refToTemplate.set(v, child.name);
+        refToTemplate.set(v, child);
       }
     }
   }
   return (ref: string) => {
-    const name = refToTemplate.get(ref);
-    return name !== undefined ? `./${name}.md` : undefined;
+    const node = refToTemplate.get(ref);
+    return node !== undefined ? docPageHref(layout, fromNode, docPageNode(node)) : undefined;
   };
 }

server/typescript/packages/codegen-ts/src/generators/template-source-annotate.ts

@@ -80,6 +80,15 @@ export interface AnnotateOptions {
 	 * Optional — when absent, partials are captured ref-only (no href).
 	 */
 	resolvePartialHref?: (ref: string) => string | undefined;
+	/**
+	 * Override how a resolved field's doc-page href is built (owner page + the
+	 * shared `#field-<name>` fragment). Optional — when absent, the flat default
+	 * `./<owner>.md#field-<name>` is used (byte-identical to today). A caller with
+	 * the output layout + page placement in scope injects a layout-aware resolver
+	 * (the SAME `docPageHref(layout, …)` the Payload cross-link uses) so the link
+	 * resolves under package layout too.
+	 */
+	fieldHref?: (owner: string, name: string) => string;
 }
 
 // A Mustache parse token: [type, value, start, end, subTokens?, closeStart?, ...].
@@ -111,6 +120,10 @@ export function annotateTemplate(
 	const out: TplToken[] = [];
 	let cursor = 0;
 
+	// How a resolved field's href is built: the injected layout-aware resolver
+	// when provided, else the flat default (byte-identical to today's output).
+	const buildFieldHref = opts.fieldHref ?? fieldHref;
+
 	// Emit verbatim source between `cursor` and `to` as a text token, advancing
 	// the cursor. This recovers literal text AND any span Mustache trimmed as
 	// standalone (e.g. the newline after a standalone partial/section), so the
@@ -129,7 +142,7 @@ export function annotateTemplate(
 		const hit = resolveTemplateVariable(stack, path);
 		if (!hit) return undefined;
 		const field = toResolvedField(hit);
-		return { field, href: fieldHref(field.owner, field.name) };
+		return { field, href: buildFieldHref(field.owner, field.name) };
 	}
 
 	// Build a variable token ({{x}} or {{&x}}/{{{x}}}). The implicit iterator