@asd20/ui-next 2.31.4 → 2.31.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.31.6](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.31.5...ui-next-v2.31.6) (2026-10-12)
+
+
+### Bug Fixes
+
+* revise PDF handbook footers; rewrite links on the handbook template to link to route to handbook content ([365a527](https://github.com/academydistrict20/asd20-ui-next/commit/365a527082a05a5746fd75b3ebf458a5e4f11d46))
+
+## [2.31.5](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.31.4...ui-next-v2.31.5) (2026-10-09)
+
+
+### Bug Fixes
+
+* add specific cover sheet for each handbook ([6c1f423](https://github.com/academydistrict20/asd20-ui-next/commit/6c1f423c06be9caa2443eee0c6d74d975416cc5a))
+
 ## [2.31.4](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.31.3...ui-next-v2.31.4) (2026-10-09)
 
 

package/helpers.js

@@ -60,3 +60,4 @@ export { default as queryPeople } from './src/helpers/queryPeople.js'
 export { default as sendEmail } from './src/helpers/sendEmail.js'
 export { default as sortOrgsByLevel } from './src/helpers/sortOrgsByLevel.js'
 export { buildHandbookDocument, documentImageUrls } from './src/helpers/handbookDocument.js'
+export { handbookSchoolYear, isDistrictHandbook, handbookCoverTitle, handbookFooterTitle, handbookDownloadFilename } from './src/helpers/handbookPresentation.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asd20/ui-next",
-  "version": "2.31.4",
+  "version": "2.31.6",
   "private": false,
   "description": "ASD20 UI component library for Vue 3.",
   "license": "MIT",

package/src/components/atoms/Asd20Messaging/index.vue

@@ -89,6 +89,7 @@
           :key="cta.label"
           :label="cta.label"
           :link="cta.url"
+          :data-asd20-handbook-link="cta.handbookTargetId || undefined"
           bordered
           transparent
         />

package/src/components/atoms/Asd20RichBodyContent/headingContext.js

@@ -124,12 +124,19 @@ export function createHeadingSession(inputContext = {}) {
   }
 
   function href(value, sourcePath) {
+    return link(value, sourcePath).href
+  }
+
+  function link(value, sourcePath, { download = false } = {}) {
+    if (download) return { href: value }
+    const handbook = !download && context.idPlan?.linkResolver?.resolve(value)
+    if (handbook) return { href: handbook.href, handbookTargetId: handbook.targetId }
     const target = fragmentTarget(value, context.documentUrl || context.idPlan?.documentUrl)
-    if (target === null) return value
+    if (target === null) return { href: value }
     const sourceKey = `${prefix}:${sourcePath}`
     references.push({ target, prefix, sourceKey })
     const mapped = context.idPlan?.fragmentsByTopic[prefix]?.[target]
-    return mapped ? `#${encodeURIComponent(mapped)}` : value
+    return { href: mapped ? `#${encodeURIComponent(mapped)}` : value }
   }
 
   function html(value, fieldPath, renderPlaceholder = null, accordionItemId = null) {
@@ -166,8 +173,15 @@ export function createHeadingSession(inputContext = {}) {
             `${prefix}-html-${fieldPath}-element-${path}-name`)
         setAttribute(node, 'name', allocated.id)
       }
-      const link = node.tagName === 'a' ? getAttribute(node, 'href') : ''
-      if (link) setAttribute(node, 'href', href(link, `html-${fieldPath}-element-${path}-href`))
+      const hrefValue = node.tagName === 'a' ? getAttribute(node, 'href') : ''
+      if (hrefValue) {
+        const resolved = link(hrefValue, `html-${fieldPath}-element-${path}-href`, { download: node.attrs.some(attr => attr.name === 'download') })
+        setAttribute(node, 'href', resolved.href)
+        if (resolved.handbookTargetId) {
+          node.attrs = node.attrs.filter(attr => attr.name !== 'target')
+          setAttribute(node, 'data-asd20-handbook-link', resolved.handbookTargetId)
+        }
+      }
       const blockType = getAttribute(node, 'data-cc-block')
       if (blockType) {
         const nonempty = (node.childNodes || []).some(child =>
@@ -196,7 +210,7 @@ export function createHeadingSession(inputContext = {}) {
     return { html: serialize(fragment), nodes }
   }
 
-  return { context, entries, headings, diagnostics, references, report, anchor, heading, href, html, scope }
+  return { context, entries, headings, diagnostics, references, report, anchor, heading, href, link, html, scope }
 }
 
 export function buildHeadingIdPlan(sessions, reservedIds = []) {

package/src/components/atoms/Asd20RichBodyContent/messageDocumentRenderer.js

@@ -712,9 +712,10 @@ function renderMarkedText(node, context, path) {
     else if (mark.type === 'subscript') html = `<sub>${html}</sub>`
     else if (mark.type === 'superscript') html = `<sup>${html}</sup>`
     else if (mark.type === 'link') {
-      html = `<a${attribute('href', context ? context.href(mark.attrs.href, `${path}-link`) : mark.attrs.href)}${attribute(
+      const link = context ? context.link(mark.attrs.href, `${path}-link`) : { href: mark.attrs.href }
+      html = `<a${attribute('href', link.href)}${attribute('data-asd20-handbook-link', link.handbookTargetId)}${attribute(
         'target',
-        mark.attrs.target
+        link.handbookTargetId ? null : mark.attrs.target
       )}${attribute('rel', mark.attrs.rel)}${attribute(
         'class',
         mark.attrs.class
@@ -1115,7 +1116,7 @@ export function buildRichBodyRenderModel(input = {}) {
 }
 
 // This prepass is deliberately independent of Vue instances and mounted topics.
-export function buildPublicationHeadingModels({ bodies = [], reservedIds = [], documentUrl } = {}) {
+export function buildPublicationHeadingModels({ bodies = [], reservedIds = [], documentUrl, linkResolverFactory } = {}) {
   const prefixes = new Set()
   const prepared = bodies.map(body => {
     const prefix = body.headingIdPrefix
@@ -1133,7 +1134,10 @@ export function buildPublicationHeadingModels({ bodies = [], reservedIds = [], d
     render(session)
     return { context, render, session }
   })
-  const idPlan = buildHeadingIdPlan(prepared.map(row => row.session), reservedIds)
+  const headingPlan = buildHeadingIdPlan(prepared.map(row => row.session), reservedIds)
+  const idPlan = linkResolverFactory
+    ? Object.freeze({ ...headingPlan, linkResolver: linkResolverFactory(headingPlan) })
+    : headingPlan
   const models = prepared.map(row => finalizeContextualModel(row.render, row.context, idPlan))
   return {
     idPlan, models,

package/src/components/templates/Asd20HandbookDocument/index.vue

@@ -3,19 +3,27 @@
     class="asd20-handbook-document"
     :data-asd20-document-root="documentId"
   >
-    <header>
-      <h1>{{ title }}</h1>
-      <div
-        v-if="document.introduction.lead"
-        class="asd20-page-header__lead"
-        v-html="document.introduction.lead"
-      />
+    <header class="asd20-handbook-document__cover">
+      <div class="asd20-handbook-document__cover-heading">
+        <h1>
+          <span class="asd20-handbook-document__organization">{{ coverTitle.organizationTitle }}</span>{{ ' ' }}
+          <span class="asd20-handbook-document__title">{{ coverTitle.handbookTitle }}</span>
+        </h1>
+        <img
+          v-if="organization.logoImageUrl"
+          class="asd20-handbook-document__logo"
+          :src="organization.logoImageUrl"
+          :alt="`${coverTitle.organizationTitle} logo`"
+        />
+      </div>
+      <div class="asd20-handbook-document__cover-body">
+        <asd20-messaging
+          :body-content="messages[0]?.bodyContent || ''"
+          :body-json="messages[0]?.bodyJson || ''"
+          :heading-id-prefix="document.coverKey"
+        />
+      </div>
     </header>
-    <asd20-print-header
-      :organization-title="organization.title || ''"
-      :canonical-url="documentUrl"
-      v-bind="printMetadata"
-    />
     <asd20-print-contents :headings="document.headings" />
     <main>
       <article
@@ -31,10 +39,10 @@
         <div
           v-if="entry.message.shortDescription || entry.message.summary"
           class="asd20-template-handbook__summary"
-          v-html="entry.message.shortDescription || entry.message.summary"
+          v-html="document.linkResolver.html(entry.message.shortDescription || entry.message.summary)"
         />
         <asd20-messaging
-          v-bind="entry.message"
+          v-bind="{ ...entry.message, callsToAction: document.linkResolver.callsToAction(entry.message.callsToAction) }"
           heading=""
           short-description=""
           detail-link=""
@@ -48,14 +56,14 @@
 
 <script>
 import Asd20Messaging from '../../atoms/Asd20Messaging'
-import Asd20PrintHeader from '../../molecules/Asd20PrintHeader'
 import Asd20PrintContents from '../../molecules/Asd20PrintContents'
 import { buildHandbookDocument } from '../../../helpers/handbookDocument'
+import { handbookCoverTitle } from '../../../helpers/handbookPresentation'
 import { publicationHeadingPlanKey } from '../../atoms/Asd20RichBodyContent/headingContext'
 
 export default {
   name: 'Asd20HandbookDocument',
-  components: { Asd20Messaging, Asd20PrintHeader, Asd20PrintContents },
+  components: { Asd20Messaging, Asd20PrintContents },
   provide() { return { [publicationHeadingPlanKey]: () => this.document.headingModels.idPlan } },
   props: {
     title: { type: String, required: true },
@@ -65,9 +73,14 @@ export default {
     documentId: { type: String, required: true },
     documentUrl: { type: String, required: true },
     printMetadata: { type: Object, default: () => ({}) },
+    includeIntroductionBody: { type: Boolean, default: true },
+    schoolYear: { type: String, default: '' },
   },
   computed: {
     document() { return buildHandbookDocument(this.$props) },
+    coverTitle() {
+      return handbookCoverTitle(this.organization, this.document.introduction.heading || this.title, this.printMetadata.generatedAt || new Date().toISOString())
+    },
   },
 }
 </script>
@@ -81,5 +94,16 @@ export default {
   h3 { font-size: 13pt; }
   h4, h5, h6 { font-size: 11pt; }
   a { color: #111; }
+  &__cover { break-after: page; padding-top: 0.35in; }
+  &__cover-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 0.3in; }
+  &__cover h1 { flex: 1; font-size: 24pt; line-height: 1.3; margin: 0; color: #1e477d; }
+  &__organization, &__title { display: block; }
+  &__title { margin-top: 0.15in; font-size: 19pt; }
+  &__cover &__logo { width: 1.45in; max-width: 1.45in; max-height: 1.65in; object-fit: contain; }
+  &__cover-body { margin-top: 0.75in; }
+  &__cover-body .asd20-messaging { padding: 0; margin: 0; }
+  &__cover-body .asd20-messaging__body-content { font-size: 10pt; line-height: 1.5; }
+  &__cover-body p { margin: 0 0 0.18in; }
+  &__cover-body img { margin-top: 0.2in; }
 }
 </style>

package/src/components/templates/Asd20HandbookTemplate/index.vue

@@ -2,6 +2,7 @@
   <div
     class="asd20-template-handbook"
     :data-asd20-document-root="documentPrint ? publicationDocumentId : undefined"
+    @click.capture="onHandbookLinkClick"
   >
     <asd20-skip-to to="#handbook-content" />
 
@@ -27,7 +28,7 @@
     />
 
     <asd20-page-header
-      :heading="title"
+      :heading="introduction.heading || title"
       :lead="handbookLead"
       :organization="organization"
       :organization-options="organizationOptions"
@@ -231,7 +232,7 @@
           class="asd20-template-handbook__summary-divider"
         />
         <asd20-messaging
-          v-bind="entry.message"
+          v-bind="topicMessage(entry.message)"
           heading=""
           short-description=""
           detail-link=""
@@ -271,6 +272,7 @@ import Asd20PrintHeader from '../../molecules/Asd20PrintHeader'
 import Asd20PrintContents from '../../molecules/Asd20PrintContents'
 import { buildHandbookDocument } from '../../../helpers/handbookDocument'
 import { installDocumentPrintLifecycle } from '../../../helpers/documentPrint'
+import { shouldHandleClientRoutingEvent } from '../../../helpers/linkPolicy'
 import pageTemplateMixin from '../../../mixins/pageTemplateMixin'
 import { publicationHeadingPlanKey } from '../../atoms/Asd20RichBodyContent/headingContext'
 
@@ -307,19 +309,24 @@ export default {
     expandedTopicId: null,
     topicsOpen: false,
     handbookHelpOpen: false,
+    fragmentEpoch: 0,
   }),
   computed: {
     handbookDocument() {
       return buildHandbookDocument({
         messages: this.messages, metaDescription: this.metaDescription,
-        documentId: this.publicationDocumentId, documentUrl: this.publicationDocumentUrl,
+        documentId: this.publicationDocumentId, documentUrl: this.handbookDocumentUrl,
         reservedIds: this.publicationReservedIds,
       })
     },
     introduction() { return this.handbookDocument.introduction },
     publicationDiagnostics() { return this.handbookDocument.diagnostics },
     printHeadings() { return this.handbookDocument.headings },
-    handbookLead() { return this.introduction.lead },
+    handbookDocumentUrl() {
+      if (this.publicationDocumentUrl) return this.publicationDocumentUrl
+      try { return new URL(this.path || '/', this.organization?.canonicalWebsite || this.organization?.website).href } catch { return '' }
+    },
+    handbookLead() { return this.handbookDocument.linkResolver.html(this.introduction.lead) },
     topicMessages() { return this.messages.slice(1) },
     topicEntries() { return this.handbookDocument.entries },
     publicationHeadings() { return this.handbookDocument.headingModels },
@@ -333,18 +340,93 @@ export default {
   },
   watch: {
     documentPrint() { this.updatePrintLifecycle() },
-    messages: { deep: true, handler() { this.updatePrintLifecycle() } },
+    messages: { deep: true, handler() { this.updatePrintLifecycle(); this.onFragmentChange() } },
     publicationDocumentId() { this.updatePrintLifecycle() },
   },
-  mounted() { this.updatePrintLifecycle() },
-  beforeUnmount() { this.stopPrintLifecycle?.() },
+  mounted() {
+    this.updatePrintLifecycle()
+    window.addEventListener('hashchange', this.onFragmentChange)
+    window.addEventListener('popstate', this.onFragmentChange)
+    this.onFragmentChange()
+  },
+  beforeUnmount() {
+    this.fragmentEpoch++
+    window.removeEventListener('hashchange', this.onFragmentChange)
+    window.removeEventListener('popstate', this.onFragmentChange)
+    this.stopPrintLifecycle?.()
+  },
   methods: {
     updatePrintLifecycle() {
       this.stopPrintLifecycle?.()
       this.stopPrintLifecycle = this.documentPrint ? installDocumentPrintLifecycle(this.$el) : null
     },
     topicSummary(message) {
-      return message.shortDescription || message.summary || ''
+      return this.handbookDocument.linkResolver.html(message.shortDescription || message.summary || '')
+    },
+    topicMessage(message) {
+      return { ...message, callsToAction: this.handbookDocument.linkResolver.callsToAction(message.callsToAction) }
+    },
+    entryForFragment(id) {
+      return this.topicEntries.find(entry => entry.titleId === id ||
+        Object.entries(this.publicationHeadings.idPlan.idsBySourceKey).some(([key, target]) => key.startsWith(entry.key + ':') && target === id))
+    },
+    onFragmentChange() {
+      if (typeof window !== 'undefined') this.activateHandbookFragment(window.location.hash)
+    },
+    async activateHandbookFragment(fragment) {
+      let id
+      try { id = decodeURIComponent(String(fragment || '').replace(/^#/, '')) } catch { return false }
+      const entry = this.entryForFragment(id)
+      if (!entry) return false
+      const epoch = ++this.fragmentEpoch
+      this.selectedMessageId = entry.key
+      this.expandedTopicId = entry.key
+      this.topicsOpen = false
+      await this.$nextTick()
+      await this.$nextTick()
+      if (epoch !== this.fragmentEpoch) return false
+      const article = this.topicArticle(entry.key)
+      const target = Array.from(article?.querySelectorAll('[id]') || []).find(element => element.id === id)
+      if (!target) return false
+      const accordions = []
+      for (let element = target; element && element !== article; element = element.parentElement) {
+        if (element.classList.contains('asd20-accordion')) accordions.unshift(element)
+      }
+      for (const accordion of accordions) {
+        const toggle = Array.from(accordion.querySelectorAll('[aria-expanded="false"][aria-controls]'))
+          .find(button => button.closest('.asd20-accordion') === accordion)
+        toggle?.click()
+        await this.$nextTick()
+        if (epoch !== this.fragmentEpoch) return false
+      }
+      target.scrollIntoView({ block: 'start' })
+      // A followed content link moves keyboard focus to its destination.
+      if (!target.hasAttribute('tabindex')) target.setAttribute('tabindex', '-1')
+      target.focus({ preventScroll: true })
+      return true
+    },
+    onHandbookLinkClick(event) {
+      const link = event.target?.closest?.('a[href]')
+      if (!link || !this.$el.contains(link) || link.hasAttribute('download') ||
+        (link.getAttribute('target') && link.getAttribute('target').toLowerCase() !== '_self') ||
+        !shouldHandleClientRoutingEvent(event)) return
+      const href = link.getAttribute('href')
+      if (!href?.startsWith('#')) return
+      let id
+      try { id = decodeURIComponent(href.slice(1)) } catch { return }
+      const entry = this.entryForFragment(id)
+      if (!entry) return
+      event.preventDefault()
+      if (window.location.hash !== href || this.activeEntry?.key !== entry.key) {
+        let currentId
+        try { currentId = decodeURIComponent(window.location.hash.slice(1)) } catch { currentId = '' }
+        // Preserve the currently visible topic as the Back destination, even
+        // when it was selected from the index before the first content link.
+        if (this.activeEntry && this.entryForFragment(currentId)?.key !== this.activeEntry.key)
+          window.history.replaceState(window.history.state, '', `#${encodeURIComponent(this.activeEntry.titleId)}`)
+        window.history.pushState(window.history.state, '', href)
+      }
+      this.activateHandbookFragment(href)
     },
     topicArticle(topicKey) {
       return Array.from(this.$el.querySelectorAll('.asd20-template-handbook__topic'))
@@ -359,6 +441,7 @@ export default {
       this.expandedTopicId = this.expandedTopicId === messageId ? null : messageId
     },
     async selectTopic(messageId) {
+      this.fragmentEpoch++
       this.selectedMessageId = messageId
       this.expandedTopicId = this.subtopicsFor(messageId).length ? messageId : null
       this.topicsOpen = false
@@ -366,6 +449,7 @@ export default {
       this.topicArticle(messageId)?.scrollIntoView({ block: 'start' })
     },
     async selectSubtopic(messageId, headingId) {
+      this.fragmentEpoch++
       this.selectedMessageId = messageId
       this.expandedTopicId = messageId
       this.topicsOpen = false

package/src/helpers/handbookDocument.js

@@ -2,6 +2,7 @@ import { buildPublicationIntroduction } from './publicationIntroduction'
 import { buildPublicationHeadingModels } from '../components/atoms/Asd20RichBodyContent/messageDocumentRenderer'
 import { createPublicationHeadingPrefix } from '../components/atoms/Asd20RichBodyContent/headingContext'
 import { parseFragment } from 'parse5'
+import { createHandbookLinkResolver } from './handbookLinks'
 
 export function documentImageUrls(html, baseUrl) {
   const urls = new Set()
@@ -18,7 +19,7 @@ export function documentImageUrls(html, baseUrl) {
 
 // The online handbook and the isolated PDF view share ordering, exclusions and
 // heading planning. Rendering a document never changes the authored messages.
-export function buildHandbookDocument({ messages = [], metaDescription = '', documentId = 'handbook', documentUrl = '', reservedIds = [] } = {}) {
+export function buildHandbookDocument({ messages = [], metaDescription = '', documentId = 'handbook', documentUrl = '', reservedIds = [], includeIntroductionBody = false } = {}) {
   const counts = new Map()
   const entries = messages.slice(1).map((message, index) => {
     const identity = String(message.id ?? `position-${index}`)
@@ -27,18 +28,27 @@ export function buildHandbookDocument({ messages = [], metaDescription = '', doc
     const key = createPublicationHeadingPrefix(documentId, JSON.stringify([identity, ordinal]))
     return { message, key, titleId: `${key}-title`, subtopicsId: `${key}-subtopics` }
   })
+  const coverKey = createPublicationHeadingPrefix(documentId, 'cover')
+  const bodies = entries.map(entry => ({ bodyContent: entry.message.bodyContent, bodyJson: entry.message.bodyJson, headingLevelOffset: 1, headingIdPrefix: entry.key }))
+  if (includeIntroductionBody) bodies.push({ bodyContent: messages[0]?.bodyContent, bodyJson: messages[0]?.bodyJson, headingIdPrefix: coverKey })
   const headingModels = buildPublicationHeadingModels({
     documentUrl,
-    bodies: entries.map(entry => ({ bodyContent: entry.message.bodyContent, bodyJson: entry.message.bodyJson, headingLevelOffset: 1, headingIdPrefix: entry.key })),
+    bodies,
     reservedIds: ['main', 'handbook-content', 'handbook-topics', ...reservedIds, ...entries.flatMap(entry => [entry.titleId, entry.subtopicsId])],
+    linkResolverFactory: idPlan => createHandbookLinkResolver(entries, documentUrl, idPlan),
   })
   const introduction = buildPublicationIntroduction(messages[0], metaDescription)
+  const coverBody = includeIntroductionBody ? headingModels.models[entries.length] : null
   return {
-    entries, introduction, headingModels,
+    entries, introduction, headingModels, linkResolver: headingModels.idPlan.linkResolver,
+    coverKey, coverBody,
     headings: entries.flatMap((entry, index) => [
       { id: entry.titleId, label: entry.message.heading || entry.message.title, authoredLevel: 2, renderedLevel: 2 },
       ...(headingModels.models[index]?.headings || []),
     ]),
-    diagnostics: [...introduction.diagnostics, ...headingModels.headingDiagnostics],
+    diagnostics: [...introduction.diagnostics, ...headingModels.headingDiagnostics,
+      ...(coverBody?.status === 'unsupported' ? [{ code: 'introduction-body-unsupported' }] : []),
+      ...(coverBody?.headings.some(heading => heading.renderedLevel === 1) ? [{ code: 'introduction-body-h1' }] : []),
+    ],
   }
 }

package/src/helpers/handbookLinks.js

@@ -0,0 +1,82 @@
+import { parseFragment, serialize } from 'parse5'
+
+const fallbackBase = 'https://handbook.invalid/'
+const filePath = /\/[^/]+\.[a-z0-9]{1,8}$/i
+
+function destination(value, documentUrl) {
+  if (typeof value !== 'string' || !value.trim() || value.trim().startsWith('#')) return null
+  try {
+    const url = new URL(value, documentUrl || fallbackBase)
+    const path = url.pathname.replace(/\/+$/, '') || '/'
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || filePath.test(path)) return null
+    // The two district root hostnames are the same published website.
+    if (url.hostname === 'asd20.org') url.hostname = 'www.asd20.org'
+    return { key: `${url.origin}${path}${url.search}`, hash: url.hash }
+  } catch { return null }
+}
+
+function canonicalLinks(message) {
+  const links = (Array.isArray(message.links) ? message.links : []).map(row => row?.link || row)
+  const detail = links.find(link => link?.type === 'Detail Link')
+  // Match the website mapper's single selected Detail Link. The same field is
+  // retained in the PDF source, keeping online/PDF behavior identical.
+  return [message.detailLink || detail?.url].filter(Boolean)
+}
+
+// Only an included topic's declared detail-page URL identifies its canonical
+// destination. Duplicate/unknown destinations remain ordinary links.
+export function createHandbookLinkResolver(entries, documentUrl, idPlan) {
+  const destinations = new Map()
+  const handbookPage = destination(documentUrl, documentUrl)?.key
+  const ownedIds = new Map(entries.map(entry => [entry.key, new Set(
+    Object.entries(idPlan.idsBySourceKey).filter(([key]) => key.startsWith(entry.key + ':')).map(([, id]) => id)
+  )]))
+  for (const entry of entries) {
+    for (const value of canonicalLinks(entry.message)) {
+      const url = destination(value, documentUrl)
+      if (!url || url.key === handbookPage) continue
+      const topics = destinations.get(url.key) || new Set()
+      topics.add(entry); destinations.set(url.key, topics)
+    }
+  }
+  function resolve(value) {
+    const url = destination(value, documentUrl)
+    const topics = url && destinations.get(url.key)
+    if (topics?.size !== 1) return null
+    const entry = [...topics][0]
+    let id = entry.titleId
+    if (url.hash && url.hash !== '#') {
+      let fragment
+      try { fragment = decodeURIComponent(url.hash.slice(1)) } catch { return null }
+      if (idPlan.diagnostics.some(row => row.code === 'ambiguous-anchor' && row.sourceKey.startsWith(entry.key + ':') && row.detail === fragment)) return null
+      id = idPlan.fragmentsByTopic[entry.key]?.[fragment] || fragment
+      if (!ownedIds.get(entry.key).has(id)) return null
+    }
+    return { href: `#${encodeURIComponent(id)}`, targetId: id }
+  }
+  function html(value) {
+    if (!value || !/<a[\s>]/i.test(value)) return value || ''
+    const fragment = parseFragment(value)
+    const walk = node => {
+      if (node.tagName === 'a' && !node.attrs.some(attr => attr.name === 'download')) {
+        const href = node.attrs.find(attr => attr.name === 'href')
+        const link = href && resolve(href.value)
+        if (link) {
+          href.value = link.href
+          node.attrs = node.attrs.filter(attr => !['target', 'data-asd20-handbook-link'].includes(attr.name))
+          node.attrs.push({ name: 'data-asd20-handbook-link', value: link.targetId })
+        }
+      }
+      for (const child of node.childNodes || []) walk(child)
+    }
+    walk(fragment)
+    return serialize(fragment)
+  }
+  function callsToAction(items = []) {
+    return (Array.isArray(items) ? items : []).map(item => {
+      const link = item && resolve(item.url)
+      return link ? { ...item, url: link.href, handbookTargetId: link.targetId } : item
+    })
+  }
+  return Object.freeze({ resolve, html, callsToAction })
+}

package/src/helpers/handbookPresentation.js

@@ -0,0 +1,73 @@
+// Shared website/PDF presentation rules. The renderer copy is generated by
+// scripts/sync-handbook-presentation.mjs.
+const districtId = '26eaf390-d8ab-11e9-a3a8-5de5bba4f125'
+
+function generationDateParts(generatedAt) {
+  if (!Number.isFinite(Date.parse(generatedAt)))
+    throw new Error('Invalid PDF generation date.')
+  return Object.fromEntries(
+    new Intl.DateTimeFormat('en-US', {
+      timeZone: 'America/Denver',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit'
+    })
+      .formatToParts(new Date(generatedAt))
+      .map((part) => [part.type, part.value])
+  )
+}
+
+export function handbookSchoolYear(generatedAt) {
+  const { year, month } = generationDateParts(generatedAt)
+  const start = Number(year) - (Number(month) < 7 ? 1 : 0)
+  return `${start}-${String(start + 1).slice(-2)}`
+}
+
+export function isDistrictHandbook(organization = {}) {
+  return (
+    organization.id === districtId ||
+    (!organization.id && organization.abbreviation === 'ASD20')
+  )
+}
+
+function handbookTitles(organization, firstMessageTitle) {
+  const organizationTitle = isDistrictHandbook(organization)
+    ? 'Academy District 20'
+    : organization.title || organization.name || 'School'
+  const handbookTitle = isDistrictHandbook(organization)
+    ? firstMessageTitle || 'School Handbook'
+    : 'School Handbook'
+  return { organizationTitle, handbookTitle }
+}
+
+export function handbookCoverTitle(
+  organization = {},
+  firstMessageTitle = '',
+  generatedAt
+) {
+  const { organizationTitle, handbookTitle } = handbookTitles(organization, firstMessageTitle)
+  return { organizationTitle, handbookTitle: `${handbookSchoolYear(generatedAt)} ${handbookTitle}` }
+}
+
+export function handbookFooterTitle(organization = {}, firstMessageTitle = '') {
+  const { organizationTitle, handbookTitle } = handbookTitles(organization, firstMessageTitle)
+  return `${organizationTitle} ${handbookTitle}`
+}
+
+export function handbookDownloadFilename(
+  organization = {},
+  generatedAt,
+  firstMessageTitle = ''
+) {
+  const safe = (value) =>
+    String(value || '')
+      .replace(/[^a-zA-Z0-9_. ()-]/g, '')
+      .trim()
+      .slice(0, 160)
+  const abbreviation = safe(organization.abbreviation).slice(0, 80)
+  const { year, month, day } = generationDateParts(generatedAt)
+  const title = isDistrictHandbook(organization)
+    ? `ASD20 ${safe(firstMessageTitle) || 'School Handbook'}`
+    : `${abbreviation ? abbreviation + ' ' : ''}School Handbook`
+  return `${title} - ${year}-${month}-${day}.pdf`
+}

package/src/helpers/publicationIntroduction.js

@@ -11,31 +11,16 @@ function nonemptyHtml(html) {
   return (parseFragment(String(html || '')).childNodes || []).some(visit)
 }
 
-function nonemptyJson(value) {
-  if (!value) return false
-  let doc = value
-  if (typeof value === 'string') {
-    try { doc = JSON.parse(value) } catch { return true }
-  }
-  if (doc?.version === 1 && Array.isArray(doc.blocks)) return doc.blocks.length > 0
-  const visit = node => {
-    if (node?.type === 'text') return Boolean(node.text?.trim())
-    if (!['doc', 'paragraph'].includes(node?.type)) return true
-    return (node.content || []).some(visit)
-  }
-  return visit(doc)
-}
-
 export function buildPublicationIntroduction(firstMessage, metaDescription = '') {
   const message = firstMessage || {}
   const lead = message.shortDescription || message.summary || metaDescription || ''
-  const excludedFields = ['heading', 'title', 'bodyContent', 'bodyJson', 'longDescription', 'images', 'callsToAction', 'detailLink', 'detailLinkLabel']
+  // First-message body/media belong to the PDF cover, never the online header.
+  const excludedFields = ['bodyContent', 'bodyJson', 'longDescription', 'images', 'callsToAction', 'detailLink', 'detailLinkLabel']
   const unmappedFields = []
-  for (const field of ['bodyContent', 'longDescription']) {
+  for (const field of ['longDescription']) {
     if (nonemptyHtml(message[field])) unmappedFields.push(field)
   }
-  if (nonemptyJson(message.bodyJson)) unmappedFields.push('bodyJson')
-  for (const field of ['images', 'callsToAction']) {
+  for (const field of ['callsToAction']) {
     if (message[field]?.length) unmappedFields.push(field)
   }
   // Detail links direct readers from wayfinding messages to detailed pages.
@@ -44,7 +29,7 @@ export function buildPublicationIntroduction(firstMessage, metaDescription = '')
   if (message.links?.some(item => (item?.link ?? item)?.type !== 'Detail Link')) unmappedFields.push('links')
   if (message.shortDescription && nonemptyHtml(message.summary) && message.summary !== lead) unmappedFields.push('summary')
   return {
-    messageId: message.id ?? null, mode: 'first-summary-lead', lead,
+    messageId: message.id ?? null, mode: 'first-message-header', heading: message.heading || message.title || '', lead,
     detailLinkPolicy: 'omit-wayfinding',
     leadSource: message.shortDescription || message.summary ? 'summary' : metaDescription ? 'metaDescription' : 'none',
     excludedFields: [...excludedFields, 'links', ...(message.shortDescription ? ['summary'] : [])],