@master/internal-site 0.2.2 → 0.2.4

package/dist/astro.mjs

@@ -250,7 +250,7 @@ async function inlineGeneratedStyles(file, ancestors = []) {
 }
 /** Preserve HTML link order and each reusable entry's cache identity. Originals
 * remain available to any JS/CSS references; no client loading logic is added. */
-async function compactStyleAssets(output) {
+async function compactStyleAssets(output, transformPage = (html) => html) {
 	const root = resolve(output), replacements = /* @__PURE__ */ new Map();
 	const documents = /* @__PURE__ */ new Map(), users = /* @__PURE__ */ new Map();
 	const boundaries = /* @__PURE__ */ new Set();
@@ -322,9 +322,32 @@ async function compactStyleAssets(output) {
 			await flush();
 			html = html.replace(run[0], replacement);
 		}
-		await writeFile(file, html);
+		await writeFile(file, transformPage(html));
 	}
 }
+// src/astro/island-scripts.ts
+const islandScriptSlot = "<!--master-site:island-scripts-->";
+const islandStyles = "<style>astro-island,astro-slot,astro-static-slot{display:contents}</style>";
+/** Move Astro's first client:load preamble ahead of the stylesheets. A classic
+* script after a stylesheet pauses HTML parsing until that stylesheet arrives. */
+function hoistIslandScripts(html) {
+	const slot = html.indexOf(islandScriptSlot);
+	if (slot < 0) return html;
+	const unchanged = () => html.replace(islandScriptSlot, "");
+	const headEnd = html.indexOf("</head>", slot);
+	const body = html.indexOf("<body", headEnd);
+	if (headEnd < 0 || body < 0) return unchanged();
+	const island = html.indexOf("<astro-island ", body);
+	const styles = html.indexOf(islandStyles, body);
+	if (island < 0 || styles < 0 || styles > island) return unchanged();
+	const start = styles + 74;
+	const preamble = html.slice(start, island);
+	const scripts = preamble.match(/<script>[\s\S]*?<\/script>/g);
+	if (!scripts || scripts.length !== 2 || preamble.trim() !== scripts.join("")) return unchanged();
+	const [directive, runtime] = scripts;
+	if (!directive.includes("astro:load") || !directive.includes("self.Astro") || !runtime.includes("customElements.define(") || !runtime.includes("astro-island")) return unchanged();
+	return (html.slice(0, start) + html.slice(island)).replace(islandScriptSlot, directive + runtime);
+}
 // src/docs-shell/remark/slug-and-toc.js
 function remarkSlugAndTOC() {
 	return (tree) => {
@@ -688,7 +711,7 @@ function masterSite(site) {
 					recursive: true,
 					force: false
 				});
-				await compactStyleAssets(fileURLToPath(destination));
+				await compactStyleAssets(fileURLToPath(destination), hoistIslandScripts);
 			}
 		}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@master/internal-site",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "First-party Astro and Svelte website framework for Master sites.",
   "engines": {

package/src/astro/index.ts

@@ -17,6 +17,7 @@ import serverStyles from './server-styles'
 import svgMarkup from './svg-markup'
 import localizedMdx from './localized-mdx'
 import { compactStyleAssets } from './style-assets'
+import { hoistIslandScripts } from './island-scripts'
 import remarkSlugAndTOC from '../docs-shell/remark/slug-and-toc.js'
 import remarkMarkdownComponents from '../docs-shell/remark/markdown-components.js'
 import svgoConfig from '../docs-shell/common/svgo.config.js'
@@ -123,7 +124,7 @@ export default function masterSite(site: SiteConfig): AstroIntegration {
         const destination = output
         await mkdir(destination, { recursive: true })
         await cp(new URL('../public/', import.meta.url), destination, { recursive: true, force: false })
-        await compactStyleAssets(fileURLToPath(destination))
+        await compactStyleAssets(fileURLToPath(destination), hoistIslandScripts)
       }
     }
   }

package/src/astro/island-scripts.ts

@@ -0,0 +1,31 @@
+export const islandScriptSlot = '<!--master-site:island-scripts-->'
+
+const islandStyles = '<style>astro-island,astro-slot,astro-static-slot{display:contents}</style>'
+
+/** Move Astro's first client:load preamble ahead of the stylesheets. A classic
+ * script after a stylesheet pauses HTML parsing until that stylesheet arrives. */
+export function hoistIslandScripts(html: string) {
+  const slot = html.indexOf(islandScriptSlot)
+  if (slot < 0) return html
+  const unchanged = () => html.replace(islandScriptSlot, '')
+
+  const headEnd = html.indexOf('</head>', slot)
+  const body = html.indexOf('<body', headEnd)
+  if (headEnd < 0 || body < 0) return unchanged()
+
+  const island = html.indexOf('<astro-island ', body)
+  const styles = html.indexOf(islandStyles, body)
+  if (island < 0 || styles < 0 || styles > island) return unchanged()
+
+  const start = styles + islandStyles.length
+  const preamble = html.slice(start, island)
+  const scripts = preamble.match(/<script>[\s\S]*?<\/script>/g)
+  if (!scripts || scripts.length !== 2 || preamble.trim() !== scripts.join('')) return unchanged()
+  const [directive, runtime] = scripts
+  // Leave unfamiliar Astro output alone. Only the shell's known first island
+  // can supply this preamble. Author scripts and later directives stay put.
+  if (!directive.includes('astro:load') || !directive.includes('self.Astro')
+    || !runtime.includes('customElements.define(') || !runtime.includes('astro-island')) return unchanged()
+
+  return (html.slice(0, start) + html.slice(island)).replace(islandScriptSlot, directive + runtime)
+}

package/src/astro/style-assets.ts

@@ -30,7 +30,7 @@ export async function inlineGeneratedStyles(file: string, ancestors: string[] =
 
 /** Preserve HTML link order and each reusable entry's cache identity. Originals
  * remain available to any JS/CSS references; no client loading logic is added. */
-export async function compactStyleAssets(output: string) {
+export async function compactStyleAssets(output: string, transformPage = (html: string) => html) {
   const root = resolve(output), replacements = new Map<string, string>()
   const documents = new Map<string, string>(), users = new Map<string, string[]>()
   const boundaries = new Set<string>()
@@ -102,6 +102,6 @@ export async function compactStyleAssets(output: string) {
       await flush()
       html = html.replace(run[0], replacement)
     }
-    await writeFile(file, html)
+    await writeFile(file, transformPage(html))
   }
 }

package/src/docs-shell/components/PageContentList.svelte

@@ -8,7 +8,6 @@
 <script lang="ts">
   import '@master/internal-site/styles/system/toc.css'
 
-  import Link from './Link.svelte'
   import PageContentTitle from './PageContentTitle.svelte'
   import { usePageContent, type PageContentItem } from './page-content.svelte'
   import groupPageContent from '../utils/group-page-content'
@@ -57,9 +56,9 @@
 
 <!-- The bootstrap script marks the live entry before hydration, so its attribute may differ from the first render. -->
 {#snippet nav({ id, title, level }: PageContentItem)}
-  <Link href={'#' + id} aria-current={pageContent.currentId === id ? 'location' : undefined} data-page-content-nav-id={id} data-level={level} lang={langOf(title)}>
+  <a href={'#' + id} aria-current={pageContent.currentId === id ? 'location' : undefined} data-page-content-nav-id={id} data-level={level} lang={langOf(title)}>
     <PageContentTitle {title} translate={translate ? t : undefined} />
-  </Link>
+  </a>
 {/snippet}
 
 <ol bind:this={element} {lang} data-fold={fold ? '' : undefined}>

package/src/docs-shell/components/page-content.svelte.ts

@@ -96,6 +96,10 @@ export function providePageContent(getItems: () => PageContentItem[]): PageConte
 
     updateCurrentId()
     initialUpdateTimeout = window.setTimeout(requestUpdate, 100)
+    // The rail can hydrate before a streamed article has delivered its headings.
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', requestUpdate, { once: true })
+    }
     document.addEventListener('scroll', requestUpdate, {
       capture: true,
       passive: true
@@ -103,6 +107,7 @@ export function providePageContent(getItems: () => PageContentItem[]): PageConte
     window.addEventListener('resize', requestUpdate, { passive: true })
 
     return () => {
+      document.removeEventListener('DOMContentLoaded', requestUpdate)
       document.removeEventListener('scroll', requestUpdate, true)
       window.removeEventListener('resize', requestUpdate)
       window.clearTimeout(initialUpdateTimeout)

package/src/docs-shell/layouts/Doc.astro

@@ -26,16 +26,12 @@ const pageContent = Array.isArray(toc) && toc.length > 0 ? toc : null
 ---
 
 <DocMain class={props.class} footerProps={footerProps}>
+  {/* Stream the rail before the article so both columns are present when its title first paints. */}
+  {pageContent && <PageContent client:load items={pageContent.map(({ id, title, level }) => ({ id, title, level }))} metadata={{ sourcePath: metadata.sourcePath, title: metadata.title }} />}
   <DocArticle aside={Boolean(pageContent)}>
     <ArticleHeader {...props} locale={locale} metadata={metadata} dictionaries={dictionaries} toc={pageContent} />
     <slot />
     <PageNavs locale={locale} metadata={metadata} pageCategories={pageCategories} dictionaries={dictionaries} />
   </DocArticle>
-  {pageContent && (
-    <Fragment>
-      {/* The rail's island serializes only the fields it renders. */}
-      <PageContent client:load items={pageContent.map(({ id, title, level }) => ({ id, title, level }))} metadata={{ sourcePath: metadata.sourcePath, title: metadata.title }} />
-      <PageContentBootstrap items={pageContent} />
-    </Fragment>
-  )}
+  {pageContent && <PageContentBootstrap items={pageContent} />}
 </DocMain>

package/src/layouts/Document.astro

@@ -9,6 +9,8 @@ import { localizePathname } from '../astro/route-paths'
 import { siteContextElementId } from '../docs-shell/site'
 import type { Metadata } from '../docs-shell/types/Metadata'
 import type { PageAssets } from '../astro/propagated-assets'
+import { islandScriptSlot } from '../astro/island-scripts'
+import NavigationTransition from './NavigationTransition.astro'
 
 interface Props {
   metadata: Partial<Metadata>
@@ -45,17 +47,19 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    {!bare && <NavigationTransition />}
     <link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="any" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <script is:inline blocking="render" set:html={themeScript}></script>
+    {!bare && import.meta.env.PROD && <Fragment set:html={islandScriptSlot} />}
     <link blocking="render" rel="preload" as="font" href="/fonts/GeistVariable.woff2" crossorigin="anonymous" />
     <link blocking="render" rel="preload" as="font" href="/fonts/IBMPlexMono-Regular.woff2" crossorigin="anonymous" />
     {(site.locale !== 'en' || basePathname === '/brand') && <link href={`https://fonts.googleapis.com/css2?family=Noto+Sans+${({ ja: 'JP', ko: 'KR', cn: 'SC' } as Record<string, string>)[site.locale] ?? 'TC'}:wght@100..900&display=swap`} rel="stylesheet" />}
     <style is:inline blocking="render" set:html={fontCSS}></style>
+    {assets.links.map((href) => <link rel="stylesheet" href={href} />)}
     {/* client:load islands can hydrate while a streamed body is still parsing.
-        Their request-local context must already exist, even with cached CSS/JS. */}
+        Keep their context in the head, after stylesheet discovery. */}
     <script is:inline type="application/json" id={siteContextElementId} set:html={siteContextJSON}></script>
-    {assets.links.map((href) => <link rel="stylesheet" href={href} />)}
     {/* Without the dev id, Vite appends a second copy when an island imports the same CSS, reordering the cascade. */}
     {assets.styles.map(({ id, content }) => <style is:inline data-vite-dev-id={id} set:html={content}></style>)}
     <title>{head.title}</title>

package/src/layouts/NavigationTransition.astro

@@ -0,0 +1,58 @@
+<style is:inline>
+  @media (prefers-reduced-motion: no-preference) and (scripting: enabled) {
+    @view-transition { navigation: auto; types: master-navigation; }
+  }
+</style>
+<script is:inline>
+  (() => {
+    if (!('onpagereveal' in window)) return
+
+    const hasTitle = () => Boolean(document.querySelector('main h1')?.textContent?.trim())
+    const hasFragmentTarget = () => {
+      if (!location.hash) return true
+      try {
+        return Boolean(document.getElementById(decodeURIComponent(location.hash.slice(1))))
+      } catch {
+        return false
+      }
+    }
+
+    addEventListener('pageswap', ({ viewTransition, activation }) => {
+      if (!viewTransition) return
+      void viewTransition.ready.catch(() => {})
+      // The standalone examples own their transitions and do not opt in to the site capture.
+      const destination = activation?.entry?.url
+      if (destination && new URL(destination).pathname.startsWith('/examples/')) viewTransition.skipTransition()
+    })
+    addEventListener('pagereveal', ({ viewTransition }) => {
+      if (!viewTransition) return
+      void viewTransition.ready.catch(() => {})
+      if (!hasTitle() || !hasFragmentTarget()) viewTransition.skipTransition()
+    })
+
+    const activation = window.navigation?.activation
+    const source = activation ? activation.from?.url : document.referrer
+    const navigation = performance.getEntriesByType('navigation')[0]
+    if (!source || new URL(source).origin !== location.origin || navigation?.type === 'reload'
+      || document.visibilityState !== 'visible' || !matchMedia('(prefers-reduced-motion: no-preference)').matches) return
+
+    // The browser may reveal a buffered response before parsing its title. Release this short
+    // wait as soon as the title arrives. If the stream is slower, pagereveal skips the capture.
+    const blocker = document.createElement('link')
+    if (!('blocking' in blocker)) return
+    blocker.rel = 'expect'
+    blocker.href = '#master-navigation-ready'
+    blocker.setAttribute('blocking', 'render')
+    const release = () => {
+      observer.disconnect()
+      clearTimeout(timeout)
+      blocker.remove()
+    }
+    const observer = new MutationObserver(() => {
+      if (hasTitle()) release()
+    })
+    const timeout = setTimeout(release, 120)
+    observer.observe(document.documentElement, { childList: true, subtree: true, characterData: true })
+    document.head.append(blocker)
+  })()
+</script>

package/src/styles/docs-shell/docs.css

@@ -63,6 +63,7 @@
 
   /* The contents rail stands still beside the article; a long list scrolls inside it. */
   :is(.ui-docs-body > .ui-toc, .ui-docs-body > astro-island > .ui-toc) {
+    order: 1;
     position: sticky; top: var(--docs-header); display: flex; flex: none; flex-direction: column; align-self: start; width: var(--docs-rail); max-height: calc(100dvh - var(--docs-header));
     padding: 3.5rem var(--ui-space-lg) var(--ui-space-xl) 0;
   }

package/src/styles/system/header-core.css

@@ -1,4 +1,6 @@
 /* header-core: owned component styles; shared definitions come from the foundation. */
+@import './navigation-transitions.css';
+
 @layer components {
   .ui-app { min-height: 100dvh; background: var(--ui-surface-canvas); color: var(--ui-text-body); }
 

package/src/styles/system/navigation-transitions.css

@@ -0,0 +1,61 @@
+/* Cross-document captures only. The homepage and blog overlay headers travel with their page. */
+:root:active-view-transition-type(master-navigation) .ui-header:not([data-variant="stickable"]) {
+  view-transition-name: master-header;
+  view-transition-class: master-navigation-chrome;
+}
+
+:root:active-view-transition-type(master-navigation) #sidebar.ui-sidebar {
+  view-transition-name: master-sidebar;
+  view-transition-class: master-navigation-chrome;
+}
+
+:root:active-view-transition-type(master-navigation) .ui-docs-body .ui-toc[data-rail] {
+  view-transition-name: master-contents;
+  view-transition-class: master-navigation-chrome;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition {
+  pointer-events: none;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-group(root) {
+  animation-duration: var(--ui-duration-quick);
+}
+
+/* Replace matching navigation in place while the page underneath crossfades. */
+:root:active-view-transition-type(master-navigation)::view-transition-group(.master-navigation-chrome) {
+  animation: none;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-old(.master-navigation-chrome) {
+  animation: none;
+  opacity: 0;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-new(.master-navigation-chrome) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
+/* If a layout gains or loses navigation, fade that capture with the page. */
+:root:active-view-transition-type(master-navigation)::view-transition-old(.master-navigation-chrome):only-child {
+  animation-name: master-navigation-chrome-out;
+  animation-duration: var(--ui-duration-quick);
+  animation-fill-mode: both;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-new(.master-navigation-chrome):only-child {
+  animation-name: master-navigation-chrome-in;
+  animation-duration: var(--ui-duration-quick);
+  animation-fill-mode: both;
+}
+
+@keyframes master-navigation-chrome-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes master-navigation-chrome-out {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}