Improve the developer experience when rendering links

[romain-pm]

A JavaScript module has no link concept, so every module writes <a href={buildNodeUrl(node)}> by hand — and buildNodeUrl throws on a falsy node (urlBuilder.ts:72).

An unresolvable reference is not an edge case. Publishing a page does not publish a jnt:page it links to (referencedNodeTypesToSkip defaults to jnt:page,jmix:autoPublish), so the normal outcome of shipping a link to an unpublished page is a live fragment replaced by <!-- Module error : Error: Expected a node in buildNodeUrl, received undefined--> — HTTP 200, section gone, per visitor. Measured end to end on 8.2.3. Unpublished, deleted and permission-denied all collapse to the same falsy value at the JCR boundary, so a component cannot tell them apart.

The rest is hand-written too: the none | internal | external switch appears in samples/hydrogen, Jahia/luxe-jahia-demo, Jahia/jahia.com and Jahia/se-utils under four incompatible property names, and nothing in the library reads j:target, emits rel on an author-supplied external URL, or checks that a target exists in the language being linked to.

Target: a junior renders a correct, cacheable, accessible link by naming the target.

<JLink node={props["j:linknode"]}>{title}</JLink>

That one line must produce an href built through buildNodeUrl, a cache dependency that still covers the target while it is unresolvable, aria-current="page" when the target is the current page, and — when the reference does not resolve — the children rendered without an anchor. Never a throw, never an <a> with no href.

Architecture (the URL tier already exists):

Tier	API	Owns
URL	buildNodeUrl(node, …) — unchanged	mode/workspace/language, context path, the nt:file split
Props	getLinkProps(target, …) · resolveContentLink(node)	resolution, fallback, cache dependency, target/rel, current-page state, scheme allow-list
Component	<JLink node | content | href …>	the <a>, children, unwrapping when not navigable

getLinkProps returns { anchor, state }. anchor is DOM-spreadable, every key a valid <a> attribute, exactly as ImageProps is; state (navigable, isCurrent, isAncestor, label) is not, and is never spread.

JLink is server-only. The vite plugin hard-fails any import of the library from a client bundle (vite-plugin/src/index.ts:214-221, :316-321), so an Island receives anchor and renders its own <a {...anchor}> — the shape the image guide already uses for <img {...imageProps} />. A client-rendered anchor loses what core adds after the render (vanity URL, ?jsite=).

Two things the spec deliberately does not own: vanity and SEO rewriting, which URLFilter does once after the render, and rich text, where the sink is dangerouslySetInnerHTML and out of a link component's reach.

API sketch, proposed breakdown and the use-case coverage table are in the comments. This answers the spike #80.

Sub-issues: #752 props tier · #753 component · #754 content-node vocabulary · #755 cache.mainResource · #756 buildNodeUrl gaps · #757 guide + sample fix · #758 tests. First implementation pass in #751.

Grounding: source analysis of the library, the engine and decompiled 8.2.3 core; live experiments on a local 8.2.3 EE (publication of an unpublished reference, dangling reference, permission-denied, vanity URLs, edit-mode anchors); and a link-use-case harvest of Jahia/jahia.com, Jahia/luxe-jahia-demo, samples/hydrogen, Jahia/default, Jahia/dx-base-demo-*, Jahia/industrial, Jahia/se-utils, Jahia/bootstrap3 and Jahia/legacy-default-components. Companion of the image epic #734.

[romain-pm]

API sketch. Server-only; buildNodeUrl is unchanged.

// ── Tier 1 — URL. Exists today; this issue does not change it.
//
//   buildNodeUrl(node, { parameters, language, mode, extension } | { parameters, args })
//
// Gaps tracked in the buildNodeUrl sub-issue, not solved here:
//   • no `absolute` option (og:url reaches for the Java getAbsoluteUrl escape hatch)
//   • no view/template segment (`<path>.<view>.html`)
//   • `mode: "edit"` emits /cms/edit/, while the page builder serves /cms/editframe/
//   • core discards `args` on a plain node: JCRNodeWrapperImpl.getUrl(List) returns getUrl()
//   • passing mode/language/extension takes the manual branch (urlBuilder.ts:80-104), which
//     hand-concatenates "/cms/render/<ws>/" + lang + path + ext and so LOSES the nt:file
//     /files/<workspace>/ split that getUrl() applies on the other branch (:106-112)

// ── Tier 2 — Props

/** A node, an already-built URL, or nothing. Both null and undefined occur:
 *  an unresolved reference yields the JCR null, an unset property yields undefined. */
export type LinkTarget = JCRNodeWrapper | string | null | undefined;

/** The four values jmix:link's j:target allows (02-jahia-nodetypes.cnd:693). */
export type LinkTargetAttribute = "_blank" | "_parent" | "_self" | "_top";

/**
 * DOM-spreadable: every key is a valid <a> attribute, by construction — the same contract
 * ImageProps has. This is the shape an Island receives and spreads: <a {...anchor}>.
 * `href` absent means "not navigable".
 */
export type AnchorProps = {
  /**
   * Server-side intermediate, NOT the delivered URL. Core completes it after the render, and
   * only when it is emitted as one of URLTraverser's tag/attribute pairs (a[href], img[src…],
   * form[action], link[href], embed[src], source[srcset], param[value]) in an html template
   * type inside the render chain. Never string-compare it. Copy it into a data-* attribute or
   * an Island payload and it stays un-rewritten: no vanity URL, no ?jsite= cross-site parameter.
   */
  href?: string;
  target?: LinkTargetAttribute;
  /** "noopener noreferrer" whenever target resolves to _blank. */
  rel?: string;
  title?: string;
};

/** NOT DOM-spreadable. Never spread onto an <a>; JLink consumes it. */
export type LinkState = {
  /** false when there is no href. */
  navigable: boolean;
  /** The target is the current main resource. JLink emits aria-current="page". */
  isCurrent: boolean;
  /** The current page is a descendant of the target. Never emitted; style with it. */
  isAncestor: boolean;
  /** Derived label, used when the caller renders no children. */
  label: string;
};

export type LinkProps = { anchor: AnchorProps; state: LinkState };

export type LinkOptions = {
  /** Query string. Inserted before any fragment, on node and string targets alike. */
  parameters?: Record<string, string>;
  /** Fragment, without the leading "#". Appended last. */
  hash?: string;
  language?: string;
  /** When `language` is set: require the target to have that translation. Default true. */
  requireTranslation?: boolean;
  target?: LinkTargetAttribute;
  /** Overrides the automatic "noopener noreferrer". */
  rel?: string;
  title?: string;
  /** Overrides the derived label. */
  label?: string;
  /** Overrides the computed value. A language switcher must set it — see the guide. */
  isCurrent?: boolean;
  /**
   * true (default) picks the form automatically: { node } when the target resolves,
   * { uuid } when a reference does not, nothing for a string target.
   * Pass an explicit key form to override — { path } is what a JCR-query result loop wants.
   */
  cacheDependency?: boolean | { node: JCRNodeWrapper } | { path: string } | { uuid: string };
};

export function getLinkProps(
  target: LinkTarget,
  options?: LinkOptions,
  context?: { renderContext?: RenderContext; mainNode?: JCRNodeWrapper },
): LinkProps;

/**
 * Reads a link off a content node. Handles core's own types — jnt:nodeLink (j:node),
 * jnt:externalLink (j:url) — plus jmix:link's j:target and mix:title's jcr:title.
 *
 * It ALSO handles the j:linkType convention, which is NOT core: it ships in the Jahia/default
 * MODULE (definitions.cnd:49-56, LinkTypeInitializer), with jmix:internalLink (j:linknode) and
 * jmix:externalLink (j:url, j:linkTitle). Because it is a module convention and three other
 * spellings exist in the wild, the property name is a parameter.
 *
 * Returns null when the discriminator is "none" or the node carries no link.
 */
export function resolveContentLink(
  node: JCRNodeWrapper,
  options?: LinkOptions & {
    /** Discriminator property. Default "j:linkType". luxe uses "ctaType", se-utils "seu:linkType". */
    typeProperty?: string;
    /** Value meaning "no link". Default "none". */
    noneValue?: string;
  },
  context?: Parameters<typeof getLinkProps>[2],
): LinkProps | null;

// ── Tier 3 — Component (server-only)

type JLinkCommon = {
  children?: ReactNode;
  /** Not navigable: render children unwrapped (default) or render nothing. */
  whenUnresolved?: "children" | "none";
} & Pick<
  LinkOptions,
  "parameters" | "hash" | "language" | "requireTranslation" | "target" | "rel" | "title" | "isCurrent" | "cacheDependency"
> &
  Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "target" | "rel" | "title">;

/**
 * A discriminated union, so "exactly one of node / href / content" is a type error rather than
 * prose — and so the href branch cannot ship an anchor with no accessible name (WCAG 2.4.4),
 * the way JImage's required `alt` cannot ship an image with none.
 */
export type JLinkProps =
  | ({ node: JCRNodeWrapper | null | undefined; href?: never; content?: never } & JLinkCommon)
  | ({ content: JCRNodeWrapper; node?: never; href?: never } & JLinkCommon)
  | ({ href: string; node?: never; content?: never } & JLinkCommon &
      ({ children: ReactNode } | { "aria-label": string }));

export function JLink(props: JLinkProps): JSX.Element | null;

// ── Pinned semantics
//
// Not navigable  — any falsy target; the empty string and a whitespace-only string (jahia.com
//                  NavBar.tsx:66 emits href: "" today, which survives `!target` and which React
//                  then drops, producing the hrefless <a> this API forbids); a string whose
//                  scheme is not allow-listed; a falsy return from buildNodeUrl (getUrl() returns
//                  null on a RepositoryException); resolveContentLink returning null; and, when
//                  `language` is set, a target that lacks that translation. Renders children
//                  unwrapped. Never throws. Never emits <a> without href. Never falls back to the
//                  raw reference UUID (getPropertyAsString still returns it for a node the
//                  visitor may not read).
// Falsiness      — test with `!target`, then trim strings; do not use default parameter values
//                  or default destructuring, they only fire on undefined.
// URL            — always through buildNodeUrl, never node.getUrl() alone: buildNodeUrl adds the
//                  context path and the servlet path, and getUrl() carries the nt:file
//                  /files/<workspace>/<canonicalPath> split. NOT for vanity resolution — that is
//                  URLFilter's job, once, after the render. Never emit a literal
//                  /cms/render/default/: the live outbound rules only match /cms/render/live/,
//                  so preview-workspace output leaks into a public page.
// Cache dep      — server.render.addCacheDependency, default on, skipped when there is no
//                  renderContext. { node } when the target resolves; { uuid } on the raw
//                  reference string when it does NOT, so publishing the target later flushes the
//                  fallback fragment. Core's nodeLink.jsp:10 registers on the uuid before and
//                  independently of resolution; { node } alone cannot.
// Main resource  — isCurrent / isAncestor / aria-current are functions of the main resource, and
//                  the fragment cache key does NOT include it unless the view opts in.
//                  PathCacheKeyPartGenerator adds the _mr_ part only when the resource declares
//                  cache.mainResource=true (verified in 8.2.3 bytecode; there is no
//                  MainResourceCacheKeyPartGenerator). A shared fragment — an AbsoluteArea nav —
//                  that emits aria-current without declaring it is cached once and replayed on
//                  every page. luxe declares it (NavMenu/default.server.tsx:23); the monorepo
//                  never mentions the property.
// Comparison     — isCurrent is identifier equality, isAncestor is a path-segment test
//                  (`mainPath === path || mainPath.startsWith(path + "/")`). Never a substring
//                  test, and never `===` on node proxies: two JCRNodeWrapper proxies for the same
//                  node are not guaranteed identical, and samples/hydrogen relies on that today.
// target / rel   — validated against the four jmix:link values; unknown or unset means the
//                  attribute is omitted, never target="". rel="noopener noreferrer" when target
//                  resolves to _blank. LIVE AND PREVIEW ONLY: in the page builder, core's
//                  EditModeFilter rewrites /edit/ to /editframe/ and either deletes `target` or
//                  staples target="_blank" on with no rel (verified in 8.2.3 bytecode).
// Label          — children win. With no children: the explicit label, then
//                  node.getDisplayableName(), which is what core and Jahia/jahia.com already use
//                  and which already encodes the jcr:title / node-name / nt:file rules.
// Scheme         — allow-list on every URL string JLink did not build itself, INCLUDING the j:url
//                  that resolveContentLink reads off content: http, https, mailto, tel, ftp, plus
//                  site-relative "/…" and fragment "#…". Anything else is not navigable. React
//                  only substitutes a throwing javascript: URL into the href (it does not remove
//                  the attribute) and matches javascript: alone — data:, blob: and vbscript: are
//                  covered by this allow-list and by nothing else.

[romain-pm]

Proposed breakdown. Not opened yet — one issue per bullet when this is agreed.

1. Library link primitive: getLinkProps + LinkProps

Part of the JLink epic, API sketch in its first comment. The props tier: everything mechanical about turning a target into anchor data.

• getLinkProps(target, options, context) → { anchor, state }. anchor is DOM-spreadable by construction (href, target, rel, title) — the same contract ImageProps has, so <a {...anchor}> is correct in an Island. state (navigable, isCurrent, isAncestor, label) is separate and is never spread.
• Not-navigable is a first-class result, not an error: falsy target, "" or whitespace-only string (Jahia/jahia.com NavBar.tsx:66 emits href: "" today), a string failing the scheme allow-list, a falsy return from buildNodeUrl, or a missing translation. Never throws — today buildNodeUrl does (urlBuilder.ts:72), and there is no error boundary in the engine or the library.
• Cache dependency, default on, skipped without a render context. { node } when the target resolves, { uuid } on the raw reference string when it does not — otherwise publishing the target never flushes the cached fallback. Core's nodeLink.jsp:10 registers on the uuid before checking resolution. cacheDependency also accepts an explicit { node } | { path } | { uuid }; { path } is what a JCR-query loop wants (Jahia/jahia.com NavBar.tsx:135).
• target validated against jmix:link's four values; unknown or unset omits the attribute, never target="". rel="noopener noreferrer" when target resolves to _blank. Both are live/preview guarantees only — EditModeFilter rewrites them in the page builder.
• isCurrent is identifier equality and is overridable via options; isAncestor is a path-segment test. Not a substring test (luxe NavigationToggler.tsx:32 and industrial both mark /home/news active on /home/newsletter) and not === on node proxies (samples/hydrogen/src/components/NavBar/default.server.tsx:20,27).
• Scheme allow-list on every string JLink did not build itself, j:url included: http https mailto tel ftp, plus /… and #…. React only substitutes a throwing javascript: URL and matches that scheme alone; data:, blob: and vbscript: are covered by nothing else.
• parameters and hash compose correctly: query before fragment. appendParameters (urlBuilder.ts:8-14) splits on ? today, so it would produce #main?a=b.
• label is node.getDisplayableName(), with an explicit override.
• When language is set, check hasI18N(locale) and the target's j:invalidLanguages (Jahia/jahia.com NavBar.tsx:106-120 does both); no translation means not navigable. Decide whether hasI18N also gets exposed to JS.

Component tier, vocabulary reader and cache-key ergonomics are separate issues. The library is engine-provided at runtime, so this ships with an engine release.

---

2. Library exports a server JLink component

Part of the JLink epic. The component over getLinkProps. Server-only.

<JLink node={props["j:linknode"]} className={classes.cta}>{label}</JLink>

• Renders a bare <a>: no class, no wrapper, no styling opinion — the same stance as <JImage>.
• JLinkProps is a discriminated union over node | content | href, so "exactly one of" is a type error rather than prose, and the href branch requires children or aria-label. An anchor with no accessible name is a WCAG 2.4.4 failure, and it is the real analogue of JImage's required alt.
• whenUnresolved: "children" (default) renders the children unwrapped, "none" renders nothing. Not named fallback — JImage's fallback is a static-asset URL, and the two components are presented as a matched pair.
• Never an <a> without href. That is what luxe's CTA produces today, and its test asserts the resulting <a>Broken</a>.
• Emits aria-current="page" from state.isCurrent. No LinkState key reaches the DOM — assert this in a unit test, so a field added later cannot leak.
• Arbitrary children, so <JLink node={target}><JImage node={cover} alt={alt} /></JLink> works — core's jnt:imageReferenceLink family, which Digitall ships instances of.
• All other anchor attributes pass through untouched (onClick, aria-label, hreflang, lang, download).
• Importing it from a client bundle already fails at build time (vite-plugin/src/index.ts:214-221, :316-321). Make sure the error names JLink's server-only status and points at getLinkProps + <a {...anchor}>.
• Naming: JLink, for the same reason <JImage> is not <Image>.

---

3. Read a link off a content node

Part of the JLink epic. Deletes the hand-written link switch.

The none | internal | external switch is written by hand four times, under four names: j:linkType in samples/hydrogen (Hero/CallToAction/default.server.tsx:20-37), ctaType in Jahia/luxe-jahia-demo (mixins/CTA/index.tsx:5-45) and again in Jahia/jahia.com (src/mixins/CTA/server.tsx), and seu:linkType in Jahia/se-utils, which adds a self value.

j:linkType is not core. Core's CND has only jmix:link (j:target), jnt:nodeLink (j:node) and jnt:externalLink (j:url) — verified in the running 8.2.3 at 02-jahia-nodetypes.cnd:693-711. The j:linkType / jmix:internalLink / jmix:externalLink vocabulary ships in the Jahia/default module (META-INF/definitions.cnd:49-56, LinkTypeInitializer).

• resolveContentLink(node, options) → LinkProps | null. Handles core's jnt:nodeLink and jnt:externalLink directly.
• The discriminator is a parameter (typeProperty, default "j:linkType"; noneValue, default "none"), not a hardcode — otherwise the engine-provided library bakes in a module convention, and still deletes no code in luxe or jahia.com.
• j:url goes through the scheme allow-list. It is editor input, and it is what spike Provide link component for js modules to improve usability and security #80 is about. Core already guards it at render time (jnt_externalLink/html/externalLink.jsp:17) but with a different remedy — it prefixes http:// rather than dropping the href. Pick one and say why (see the epic's open questions).
• Label: explicit label, then getDisplayableName() on the link node, then on the target. Jahia/jahia.com instead emits a literal "Internal link not defined" sentinel — decide whether an author-visible placeholder in edit mode is worth having.
• <JLink content={node}> as the component shortcut.
• Document what happens on a site that does not deploy Jahia/default.

---

4. cache.mainResource: make current-page state safe to cache

Part of the JLink epic. The epic's headline default is unsafe in a shared fragment, and nothing in the monorepo says so.

isCurrent / isAncestor / aria-current are functions of the main resource, but the fragment cache key does not include it unless the view opts in. PathCacheKeyPartGenerator adds its _mr_ part only when the resource declares cache.mainResource=true — verified in 8.2.3 bytecode; there is no MainResourceCacheKeyPartGenerator in the package. Core declares it on every main-resource-dependent view (jnt_navMenu, jnt_area, jnt_absoluteArea, jnt_mainResourceDisplay). Jahia/luxe-jahia-demo declares it on its site-level nav (NavMenu/default.server.tsx:23). grep -rn cache.mainResource across the whole javascript-modules monorepo returns zero hits.

So a nav rendered from an AbsoluteArea — one shared node, many pages — that emits aria-current is cached once and replayed everywhere. (samples/hydrogen's navbar escapes only because it is a per-page node.)

• Pin the rule: a view that lets JLink emit aria-current, or that reads isCurrent/isAncestor, must declare cache.mainResource=true.
• Document the properties: { "cache.mainResource": "true" } recipe on jahiaComponent, in the links guide and in the caching guide.
• Development-mode warning when isCurrent is computed in a view that has not declared it, in the style of the image API's ?w= warning.
• Cypress: render the same nav on two pages via an AbsoluteArea and assert aria-current follows the page.

---

5. buildNodeUrl gaps a link component cannot work around

Part of the JLink epic. Five holes in the URL tier, each found by a real call site.

• nt:file is lost on the manual branch. buildNodeUrl has two paths (urlBuilder.ts:80-104 vs :106-112). The /files/<workspace>/<canonicalPath> split lives in JCRNodeWrapperImpl.getUrl(), called only on the second. Pass any of mode, language or extension and the first path hand-concatenates a render URL for a binary: <JLink node={pdf} language="fr"> yields /cms/render/live/fr/sites/x/files/doc.pdf.html. Either reproduce the split on the manual branch or make file targets always take the getUrl() path.
• absolute option. Jahia/luxe-jahia-demo's og:url and og:image drop out of the JS API and call the Java JCRNodeWrapper.getAbsoluteUrl(request). Note a cross-site absolute URL needs the target site's server name, not the request's.
• View/template segment (<path>.<view>.html). Core's jnt:componentLink and jnt:siteLink both need it; today the only route is extension: ".myView.html" as a string hack.
• mode: "edit" emits /cms/edit/…. The page builder is served from /cms/editframe/…. Jahia/jahia.com already patches this by hand: buildNodeUrl(target).replace("/cms/edit/", "/cms/editframe/") (src/templates/NavBar.tsx:83), with a comment. /cms/edit/ works only because EditModeFilter rewrites it — and the same filter deletes or staples on target while it is there.
• args JSDoc. JCRNodeWrapperImpl.getUrl(List<String>) returns getUrl() — core discards the arguments on a plain node. The JSDoc documents a silent no-op as a feature. Same fix shape as Fix misleading args JSDoc; document getThumbnailUrl #736.

Also worth a line in the guide: an href built with a literal default workspace survives into a live page, because the live outbound rules only match /cms/render/live/….

---

6. Links guide + fix the tutorial and sample anti-pattern

Part of the JLink epic. The canonical sample teaches the pattern that breaks.

samples/hydrogen/src/components/Hero/CallToAction/default.server.tsx types j:linknode as a non-optional JCRNodeWrapper and calls buildNodeUrl on it unguarded, puts an author-supplied j:url straight into href, registers no cache dependency, reads no j:target and emits no rel. It is the exact component whose live failure was reproduced for this epic.

• docs/2-guides/<n>-links/README.md: the one-liner recipe; the not-navigable contract and why an unresolvable reference is the normal state; cache dependencies and the three key forms; cache.mainResource; target/rel and the page-builder carve-out; current-page state; what core already does for you and what it does not.
• Be explicit that anchor.href is a server-side intermediate. Core completes it after the render, and only for URLTraverser's tag/attribute pairs (a[href], img[src|srcset|data-src|data-srcset], form[action], link[href], embed[src], source[srcset], param[value]) in an html template type. A URL in an Island payload, a data-* attribute, or an action's JSON response gets neither vanity rewriting nor the ?jsite= cross-site parameter that SiteParameterAdder adds in live. Jahia/jahia.com ships two divergent URLs per link today for exactly this reason.
• Islands: the form is <a {...anchor}>, not <JLink {...}> — the library cannot be imported client-side. Mention action() as the way to fetch link data after hydration, and its URL caveat.
• Update samples/hydrogen's CallToAction and NavBar to <JLink>. Flag two behaviour changes rather than presenting them as a refactor: the CTA's none branch renders <s>{title}</s> today, which whenUnresolved="children" does not reproduce; and NavBar's current-page test is page === mainNode, reference equality on Graal proxies, which becomes identifier equality.
• Update the blog tutorial wherever it renders an anchor.
• A callout that dangerouslySetInnerHTML on rich text is outside JLink's reach: core resolves the internal links there, but nothing sanitises an author-pasted javascript: href — verified end to end on 8.2.3. Name registerRenderFilter above priority 21 as where such a policy would live.
• 3-reference is hand-written and Academy-published, so the guide carries the teaching.

---

7. Tests: unit coverage plus the unresolvable-reference e2e cases

Part of the JLink epic.

• Vitest over getLinkProps and resolveContentLink: falsy target, "" and whitespace-only string, string target, scheme allow-list — accept http https mailto tel ftp / #, reject javascript: data: blob: vbscript: — target validation and omission, rel on _blank, isCurrent vs isAncestor (including /home/news vs /home/newsletter, and two distinct proxies for the same node, which must compare equal), isCurrent override, label fallback, parameters + hash ordering on node and string targets, missing translation.
• Unit test asserting no LinkState key (navigable, isCurrent, isAncestor, label) reaches the DOM.
• Unit test asserting the label agrees with getDisplayableName() for jnt:page, nt:file and an untitled node.
• Cypress: publish a link whose target is not published, assert the page renders the fallback and no <!-- Module error appears. No test exercises an unresolvable reference today — getNodePropsTest.cy.ts:109-111 only asserts the happy path for a weakreference.
• Cypress: rename the target of a rendered link, assert the cached fragment is flushed.
• Cypress: publish a previously-dangling target and assert the fallback fragment is flushed — this is what the { uuid } dependency form buys, and { node } cannot.
• Cypress: render the same nav on two pages via an AbsoluteArea and assert aria-current follows the page (the cache.mainResource case).
• Page-builder case: a <JLink> in the builder must emit an /cms/editframe/… href, so a click navigates the builder instead of opening a new tab. Assert on the delivered DOM, not the component output — EditModeFilter rewrites both the href and target.

[romain-pm]

Harvested use case	Source	Spec coverage
Whole-card link around image + heading (5 copies)	luxe	Covered — <JLink node={currentNode} className>
Design-system card that takes data, not an element	luxe, jahia.com (CTA/index.tsx)	Covered — anchor is the boundary type; the card spreads it onto its own <a>
CTA mixin: none / internal / external switch	hydrogen, luxe, jahia.com, se-utils	Covered — resolveContentLink(node, { typeProperty }). Four different discriminators, so the property name is a parameter; a hardcoded j:linkType would delete code in hydrogen only
Dangling or absent link target	luxe, hydrogen	Covered — not-navigable contract, children unwrapped, { uuid } cache dependency
Empty-string href as a third broken shape	jahia.com NavBar.tsx:66	Covered — "" and whitespace-only are not navigable, named explicitly
Author-supplied external j:url in href	luxe, hydrogen, jahia.com, Digitall	Covered — allow-list applies to j:url, plus rel
Hard-coded target="_blank" footer links	luxe	Covered — target validated, rel automatic (live/preview only)
Nav menu current / in-path state	luxe, hydrogen, jahia.com, industrial, bootstrap3	Covered — isCurrent by identifier, isAncestor by path segment, aria-current="page". Five different tests in the wild, including reference equality on Graal proxies
Shared nav fragment reused across pages	luxe (declares it), core's four views	Covered — cache.mainResource=true pinned as a semantic, with a dev warning and a Cypress case
Language switcher	luxe, jahia.com	Covered — isCurrent override for locale-current, plus hasI18N / j:invalidLanguages for translation existence. Was uncoverable in the draft
Cross-language link to the same resource	luxe, dx-base-demo, jahia.com	Covered — language + requireTranslation
Brand link wrapping a logo image	luxe	Covered — arbitrary children + automatic cache dependency
mailto: / tel: from an author property	luxe	Covered — string target, allow-listed scheme. Number normalisation stays with the caller
Skip link #main	luxe	Covered — href="#main" accepted, not resolved as a node; hash composes before parameters
Login link that is also a dialog trigger	luxe	Covered — onClick and all anchor props pass through
URLs serialised into Islands	luxe (NavigationToggler.tsx:26-31)	Covered — <a {...anchor}> in the Island. One site, not four: the language switcher needs a flag anchor cannot carry, and the other two are a form action and a video URL
Pagination implemented as <button> + pushState	luxe	Covered — parameters makes the pages real links
Query-parameter / UTM decoration	luxe, se-utils, bootstrap3	Covered — parameters, fragment-aware. appendParameters splits on ? today and would emit #main?a=b
Request parameters propagated to the target	jahia.com Breadcrumb.tsx:52-60	Covered — parameters. Guide must note the fragment then varies by query string, so QueryStringCacheKeyPartGenerator must vary too
Search-hit URL from a JCR query, with a per-hit cache dependency	jahia.com NavBar.tsx:133-142	Covered — string/node target plus cacheDependency: { path }
Search-hit URL string from GraphQL or a Hit	luxe, dx-base-demo	Covered — string target gets the same target/rel/allow-list treatment
jnt:externalLink core view	Jahia/default	Covered — resolveContentLink + allow-list + label + j:target
jnt:nodeLink core view	Jahia/default	Covered — resolveContentLink + { uuid } cache dependency + not-navigable fallback
nt:base link fallback: any node is linkable	Jahia/default	Covered — <JLink node> with no other prop
Image wrapped in a link	Jahia/default, Digitall	Covered — <JLink><JImage/></JLink>
Read-more / card link with label fallback	dx-base-demo, jahia.com	Covered — getDisplayableName() + cache dependency
Conditional wrapper: <a> when linked, <div> when not	industrial	Covered — whenUnresolved
Permission-guarded link	dx-base-demo, legacy-default	Covered by contract — an unreadable target is falsy, so the link is not navigable
Cache dependency next to every link	Jahia/default, dx-base-demo (14 sites), luxe CTA, jahia.com	Covered — automatic, default on, three key forms. luxe's CTA already hand-writes the exact call this absorbs
Output escaping and URL-scheme safety	Jahia/default#146, #148	Covered — React escapes text; the allow-list covers data:/blob:/vbscript:, which React does not
Inert links (href="#", dropdown trigger, tab)	bootstrap3, industrial, Jahia/default	Covered — pass href directly; JLink does not invent a destination
SEO / vanity URL rewriting	core	No work — URLFilter (priority 21) does it once, after the render. Not encodeURL, which strips the jsessionid
File / download link (jnt:file)	Jahia/default, industrial	Partial — correct only on buildNodeUrl's getUrl() branch; mode/language/extension take the manual branch and lose the /files/<workspace> split. Tracked in the buildNodeUrl sub-issue. download and file-type icons stay with the caller
Analytics-instrumented link	jahia.com (every link)	Partial — the props tier returns the href and the label the caller needs; an asChild escape hatch on JLink is an open question. data-* is outside URLTraverser, so an instrumented URL is un-rewritten
Polymorphic jnt:linkList children	luxe, Jahia/default	Partial — JLink is the primitive. A JSM link view is an open question; jahia.com already ships one for its own type
Breadcrumb	bootstrap3, legacy-default, luxe, jahia.com	Partial — "the current item is not an anchor" is covered; the ancestor walk is not. Four repos hand-roll it; open question
Sibling / prev-next navigation	legacy-default	Partial — aria-label and title pass through; no helper
Absolute URL (og:url, newsletter)	luxe, dx-base-demo	Not covered — absolute is a buildNodeUrl gap. The RSS motivation is dropped: a JSM view cannot be a feed at all, because jahiaComponent hardcodes templateType: "html" (jahiaComponent.tsx:52)
hreflang / x-default alternates in <head>	jahia.com, Jahia/sitemap	Not covered — anchor-level hreflang passes through, the <link rel="alternate"> set does not. Open question
Link to a named template/view or an action	Jahia/default, legacy-default	Not covered — a buildNodeUrl gap
Link to a node with no page of its own (findDisplayableNode)	7 JSP sites	Not covered — no JS binding exists. Open question
Cross-site link	—	Not covered — SiteParameterAdder appends ?jsite= in live; isCurrent/isAncestor are meaningless across site roots. Open question
Anchor into an <Area> on another page	—	Not covered — hash composes correctly, but Area emits no id to land on
Link rendered client-side after hydration	luxe (4 Islands)	Out of scope — the library cannot be imported client-side, and a client-rendered anchor loses the vanity URL and ?jsite=. Use <a {...anchor}> server-rendered, or action()
Rich-text anchors via dangerouslySetInnerHTML	luxe (5 sites)	Out of scope — core resolves ##ref##. A rel/target/sanitising policy belongs in a registerRenderFilter above priority 21, not in a component
Mode / workspace switch links (buildEndpointUrl)	luxe	Out of scope — no node involved
Node URL used as <form action>	luxe	Out of scope — tier 1, unchanged
Link inside a third-party HTML config string	luxe (Leaflet)	Out of scope — a component cannot reach into an HTML string
Security: what JLink guarantees	—	Scheme allow-list on every string it did not build, j:url included, applied at render time so it also protects content stored before any validator existed; rel="noopener noreferrer" on _blank; target restricted to the four jmix:link values; never echoes a target's raw UUID
Security: what JLink does not do	—	React neutralises javascript: by substituting a throwing javascript: URL — it does not remove the attribute — and matches no other scheme, so the allow-list is the only cover for data:/blob:/vbscript:. In the page builder EditModeFilter can staple target="_blank" on with no rel, so those two are live/preview guarantees. JLink does not protect rich text. It does not distinguish unpublished / deleted / forbidden — one value at the JCR boundary, and telling them apart would be an existence oracle. Entry-time validation of j:url is a separate change on the definitions, or a content patch

[romain-pm]

Correction to the API sketch above. The pinned Cache dep semantic and breakdown item 1 both say { uuid } keeps a fallback fragment flushable while the reference is unresolved. It does not, today: RenderHelper.renderTag populates the tag before it sets the page context, so AddCacheDependencyTag.setUuid throws a NullPointerException that safePopulate swallows, and nothing is registered — #750. { node }, { path } and { flushOnPathMatchingRegexp } (a real fourth key form the sketch missed) all work. The API in #751 still picks { uuid } for the unresolved case, since it is the only key that case offers, and documents that the engine drops it.

First implementation pass is #751.