@pagenary/publisher 2026.6.14 → 2026.6.16

package/examples/page-effects/config.json

@@ -7,5 +7,6 @@
   "accentColor": "#e11d48",
   "surfaceColor": "#ffffff",
   "inkColor": "#0b1220",
-  "bottomNav": "always"
+  "bottomNav": "always",
+  "livingScroll": true
 }

package/examples/page-effects/content/disclosure.md

@@ -0,0 +1,40 @@
+---
+title: Disclosure (accordion)
+summary: Production accordion built on native <details> — works with zero JS, keyboard-operable, single-open optional.
+hero:
+  eyebrow: Primitive
+  title: Disclosure
+  subtitle: An accordion that's just native <details> — accessible and complete with JavaScript off.
+  align: start
+---
+
+# Disclosure (accordion)
+
+`.pe-accordion` styles native `<details>/<summary>`, so each panel opens, closes,
+and takes keyboard focus with **zero JavaScript**. Add `data-pe-single` to make it
+single-open — opening one panel closes its siblings — which is a pure enhancement:
+with JS off, every panel still works independently and no content is ever hidden
+behind the script.
+
+```html
+<div class="pe-accordion" data-pe-single>
+  <details open>
+    <summary>What is a page effect?</summary>
+    <p>An opt-in, accessible enhancement — heroes, reveal-on-scroll, living scroll,
+       disclosure — that degrades to plain content when JavaScript or motion is off.</p>
+  </details>
+  <details>
+    <summary>Does it work without JavaScript?</summary>
+    <p>Yes. The accordion is native <code>&lt;details&gt;</code>. The only thing JS
+       adds is the single-open grouping, and that's optional.</p>
+  </details>
+  <details>
+    <summary>Is it keyboard accessible?</summary>
+    <p>Native disclosure is operable with Enter/Space and shows a visible focus
+       ring. The open/closed state uses a +/− marker, not color alone.</p>
+  </details>
+</div>
+```
+
+Drop `data-pe-single` to let multiple panels stay open at once. Style is theme-token
+aware, so it inherits each tenant's palette automatically.

package/examples/page-effects/content/index.md

@@ -81,6 +81,34 @@ the viewport, and appear instantly under reduced-motion.
 </div>
 ```
 
+## Staggered reveal
+
+The cards below arrive in a wave — `data-reveal-stagger` on the grid sequences
+each child's entrance as it scrolls into view (JS-off and reduced-motion show all
+at once).
+
+```html
+<div class="pe-card-grid" data-reveal-stagger="90">
+  <section class="pe-demo-card"><h3>One</h3><p>Arrives first.</p></section>
+  <section class="pe-demo-card"><h3>Two</h3><p>A beat later.</p></section>
+  <section class="pe-demo-card"><h3>Three</h3><p>Then this one.</p></section>
+  <section class="pe-demo-card"><h3>Four</h3><p>And finally this.</p></section>
+</div>
+```
+
+## Figure zoom
+
+The figure below shows its image normally; click it (or press Enter when focused)
+to enlarge it in a modal. With JavaScript off, the image is just visible at its
+normal size.
+
+```html
+<figure class="pe-figure" data-pe-zoom>
+  <img src="images/ridge.svg" alt="Layered ridge illustration" />
+  <figcaption>Click to enlarge — opens a native dialog with focus trap and Esc-to-close.</figcaption>
+</figure>
+```
+
 ## Authoring paths
 
 You have four ways to add a hero, from least to most control:

package/examples/page-effects/content/parallax-and-sticky.md

@@ -61,3 +61,16 @@ The CTA band primitive is just as portable:
 ```
 
 Keep scrolling to confirm the sticky hero releases at the end of the page.
+
+## Parallax on any element
+
+The card below isn't a hero — it drifts on its own with `data-pe-parallax="0.35"`.
+Any element can; the speed is clamped so it never wanders far, and it's skipped
+entirely under reduced motion.
+
+```html
+<div class="pe-demo-card" data-pe-parallax="0.35" style="max-width: 20rem;">
+  <h3>Parallax aside</h3>
+  <p>Drifts gently against the scroll — a non-hero element with its own speed.</p>
+</div>
+```

package/examples/page-effects/content/scroll-snap.md

@@ -0,0 +1,29 @@
+---
+title: Scroll-snap sections
+summary: A CSS-only .pe-snap region whose panels snap as you scroll — opt-in, no runtime, never traps the keyboard.
+hero:
+  eyebrow: Primitive
+  title: Scroll-snap sections
+  subtitle: Bounded snap panels for landing pages — pure CSS, and the keyboard is never trapped.
+  align: start
+---
+
+# Scroll-snap sections
+
+`.pe-snap` is a **self-contained, opt-in** scroll region whose `.pe-snap__panel`
+children snap into place as you scroll it. It's pure CSS — no runtime — and uses
+`scroll-snap-type: y proximity` (not `mandatory`) inside a bounded height, so it
+never takes over the page scroll and never traps keyboard users.
+
+```html
+<div class="pe-snap">
+  <section class="pe-snap__panel"><h2>Capture</h2><p>Scroll inside this region — each panel snaps to the top.</p></section>
+  <section class="pe-snap__panel"><h2>Compose</h2><p>Proximity snapping, so you can still stop between panels.</p></section>
+  <section class="pe-snap__panel"><h2>Publish</h2><p>Tab through; the keyboard is never trapped.</p></section>
+</div>
+```
+
+Smooth glide to the snap points is gated under `prefers-reduced-motion:
+no-preference`; reduced-motion readers get instant positioning. The panels are
+ordinary sections, so the content is complete and reachable with or without
+snapping.

package/examples/page-effects/content/scrollytelling.md

@@ -0,0 +1,35 @@
+---
+title: Scrollytelling
+summary: A sticky stage beside content steps — the stage updates as each step scrolls into view. JS-off shows the steps as plain content.
+hero:
+  eyebrow: Primitive
+  title: Scrollytelling
+  subtitle: A sticky stage that reacts as you read past each step — built from sticky layout + scroll position, no animation engine.
+  align: start
+---
+
+# Scrollytelling
+
+A `.pe-scrolly` block pairs a **sticky stage** with a column of `[data-pe-step]`
+content steps. As each step scrolls into view, the stage's matching layer
+crossfades in. With JavaScript off, the steps are ordinary readable content and
+the stage shows its layers statically — the swap is a pure enhancement.
+
+```html
+<div class="pe-scrolly">
+  <div class="pe-scrolly__stage">
+    <div data-pe-step="capture"><h2>Capture</h2></div>
+    <div data-pe-step="compose"><h2>Compose</h2></div>
+    <div data-pe-step="publish"><h2>Publish</h2></div>
+  </div>
+  <div class="pe-scrolly__steps">
+    <section data-pe-step="capture"><p>Write your content as Markdown, HTML, or a JS module.</p></section>
+    <section data-pe-step="compose"><p>Shared templates turn it into a branded, tenant-specific site.</p></section>
+    <section data-pe-step="publish"><p>Build emits static files — host them anywhere.</p></section>
+  </div>
+</div>
+```
+
+The active step is the last one to scroll past the upper-middle of the viewport —
+the same rect-based detection scroll-spy uses, so no bespoke animation engine is
+needed. The crossfade is gated under `prefers-reduced-motion: no-preference`.

package/examples/page-effects/manifest.json

@@ -14,10 +14,22 @@
       "file": "parallax-and-sticky.md"
     },
     {
-      "id": "effects-spike",
-      "title": "Effect Spike",
-      "summary": "Throwaway prototypes for disclosure, scroll-snap panels, and figure zoom candidates.",
-      "file": "effects-spike.md"
+      "id": "disclosure",
+      "title": "Disclosure",
+      "summary": "Production accordion on native <details> — zero-JS, keyboard-operable, single-open optional.",
+      "file": "disclosure.md"
+    },
+    {
+      "id": "scroll-snap",
+      "title": "Scroll-snap",
+      "summary": "CSS-only .pe-snap region — bounded, opt-in snap panels that never trap the keyboard.",
+      "file": "scroll-snap.md"
+    },
+    {
+      "id": "scrollytelling",
+      "title": "Scrollytelling",
+      "summary": "A sticky stage that reacts as you read past each step — sticky layout + scroll position, no animation engine.",
+      "file": "scrollytelling.md"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagenary/publisher",
-  "version": "2026.6.14",
+  "version": "2026.6.16",
   "type": "module",
   "description": "Multi-tenant static publishing component for Pagenary platform.",
   "license": "AGPL-3.0-or-later",

package/scripts/build-tenants.js

@@ -277,6 +277,11 @@ function isGitAvailable() {
  * Execute a command with timeout and retry
  */
 async function execWithRetry(command, options = {}) {
+  const commandSegments = Array.isArray(command) ? command : [];
+  if (commandSegments.length === 0) {
+    throw new Error('execWithRetry expected an argument array');
+  }
+
   const {
     cwd = root,
     timeout = DEFAULT_GIT_TIMEOUT,
@@ -288,10 +293,13 @@ async function execWithRetry(command, options = {}) {
   for (let attempt = 1; attempt <= retries; attempt++) {
     try {
       return await new Promise((resolve, reject) => {
-        const proc = spawn('sh', ['-c', command], {
+        const proc = spawn(commandSegments[0], commandSegments.slice(1), {
           cwd,
           stdio: ['pipe', 'pipe', 'pipe'],
-          env: { ...env, GIT_TERMINAL_PROMPT: '0' },
+          env: {
+            ...env,
+            GIT_TERMINAL_PROMPT: '0'
+          },
           timeout
         });
 
@@ -305,7 +313,10 @@ async function execWithRetry(command, options = {}) {
           if (code === 0) {
             resolve({ stdout, stderr });
           } else {
-            reject(new Error(`Command failed (exit ${code}): ${stderr || stdout}`));
+            const prettyCommand = commandSegments
+              .map((segment) => maskAuthSegment(String(segment)))
+              .join(' ');
+            reject(new Error(`Command failed (exit ${code}): ${stderr || stdout} (command: ${prettyCommand})`));
           }
         });
 
@@ -334,6 +345,34 @@ async function execWithRetry(command, options = {}) {
   throw lastError;
 }
 
+function maskAuthSegment(value) {
+  return value.replace(/\/\/[^@]+@/, '//***@');
+}
+
+/**
+ * Build an authenticated git URL when GIT_CREDENTIALS is available.
+ */
+function withGitCredentials(rawUrl) {
+  const credentials = process.env.GIT_CREDENTIALS || '';
+  const [username, password] = credentials.split(':', 2);
+  if (!credentials || !username || password === undefined || !rawUrl) return rawUrl;
+
+  try {
+    const source = new URL(rawUrl);
+    if (!['https:', 'http:'].includes(source.protocol)) {
+      return rawUrl;
+    }
+
+    if (source.username) {
+      return rawUrl;
+    }
+
+    return `${source.protocol}//${encodeURIComponent(username)}:${encodeURIComponent(password)}@${source.host}${source.pathname}${source.search}${source.hash}`;
+  } catch {
+    return rawUrl;
+  }
+}
+
 /**
  * Generate cache key for git source
  */
@@ -364,7 +403,10 @@ function isImmutableRef(ref) {
  */
 async function getHeadCommit(repoDir) {
   try {
-    const { stdout } = await execWithRetry(`git -C "${repoDir}" rev-parse HEAD`, { cwd: root, retries: 1 });
+    const { stdout } = await execWithRetry(['git', '-C', repoDir, 'rev-parse', 'HEAD'], {
+      cwd: root,
+      retries: 1
+    });
     return stdout.trim();
   } catch {
     return null;
@@ -385,7 +427,7 @@ async function getChangedFiles(repoDir, oldCommit, newCommit, subPath = '.') {
   try {
     // Use --name-status to get file status (A=added, M=modified, D=deleted)
     const { stdout } = await execWithRetry(
-      `git -C "${repoDir}" diff --name-status ${oldCommit} ${newCommit}`,
+      ['git', '-C', repoDir, 'diff', '--name-status', oldCommit, newCommit],
       { cwd: root, retries: 1 }
     );
 
@@ -461,6 +503,7 @@ async function cloneGitSource(source, cacheDir, options = {}) {
 
   // Sanitize URL for logging (hide credentials)
   const safeUrl = url.replace(/\/\/[^@]+@/, '//***@');
+  const authUrl = withGitCredentials(url);
 
   console.log(`  ↳ git source: ${safeUrl}`);
   console.log(`  ↳ ref: ${ref}, path: ${subPath || '(root)'}`);
@@ -494,8 +537,8 @@ async function cloneGitSource(source, cacheDir, options = {}) {
       console.log(`  ↳ current HEAD: ${oldCommit ? oldCommit.slice(0, 7) : 'unknown'}`);
 
       try {
-        await execWithRetry(`git -C "${cloneDir}" fetch origin ${ref} --depth ${effectiveDepth}`, { cwd: root });
-        await execWithRetry(`git -C "${cloneDir}" checkout FETCH_HEAD`, { cwd: root });
+        await execWithRetry(['git', '-C', cloneDir, 'fetch', 'origin', ref, '--depth', String(effectiveDepth)], { cwd: root });
+        await execWithRetry(['git', '-C', cloneDir, 'checkout', 'FETCH_HEAD'], { cwd: root });
         newCommit = await getHeadCommit(cloneDir);
         console.log(`  ↳ updated HEAD: ${newCommit ? newCommit.slice(0, 7) : 'unknown'}`);
       } catch (err) {
@@ -513,33 +556,33 @@ async function cloneGitSource(source, cacheDir, options = {}) {
     wasCloned = true;
 
     // Build clone command
-    let cloneCmd = `git clone --depth ${effectiveDepth}`;
+    const cloneArgs = ['git', 'clone', '--depth', String(effectiveDepth)];
 
     // Add branch/ref
     // For commits, we can't use --branch, need to fetch after
     if (!isImmutableRef(ref) || /^v?\d+\.\d+/.test(ref)) {
-      cloneCmd += ` --branch ${ref}`;
+      cloneArgs.push('--branch', ref);
     }
 
     // Sparse checkout preparation
     if (effectiveSparse) {
-      cloneCmd += ' --filter=blob:none --sparse';
+      cloneArgs.push('--filter=blob:none', '--sparse');
     }
 
-    cloneCmd += ` "${url}" "${cloneDir}"`;
+    cloneArgs.push(authUrl, cloneDir);
 
     try {
-      await execWithRetry(cloneCmd, { cwd: root });
+      await execWithRetry(cloneArgs, { cwd: root });
 
       // If ref is a commit SHA, checkout after clone
       if (/^[0-9a-f]{7,40}$/i.test(ref) && !/^v?\d+\.\d+/.test(ref)) {
-        await execWithRetry(`git -C "${cloneDir}" fetch --depth ${effectiveDepth} origin ${ref}`, { cwd: root });
-        await execWithRetry(`git -C "${cloneDir}" checkout ${ref}`, { cwd: root });
+        await execWithRetry(['git', '-C', cloneDir, 'fetch', '--depth', String(effectiveDepth), 'origin', ref], { cwd: root });
+        await execWithRetry(['git', '-C', cloneDir, 'checkout', ref], { cwd: root });
       }
 
       // Set up sparse checkout if needed
       if (effectiveSparse) {
-        await execWithRetry(`git -C "${cloneDir}" sparse-checkout set "${subPath}"`, { cwd: root });
+        await execWithRetry(['git', '-C', cloneDir, 'sparse-checkout', 'set', subPath], { cwd: root });
       }
 
       newCommit = await getHeadCommit(cloneDir);
@@ -1670,6 +1713,83 @@ async function applyReadingProgressConfig(distDir, config, tenantId) {
   console.log(`  ↳ enabled reading progress for ${tenantId}`);
 }
 
+/**
+ * Living scroll on any layout (docs included). Blog tenants opt in via
+ * `blog.livingScroll` (handled in applyBlogLayout); this is the general path,
+ * driven by a top-level `livingScroll: true` (or `reader.livingScroll`). It sets
+ * the layout-agnostic body flag plus a reading-progress bar. The hidden base
+ * state, reduced-motion fallback, and JS-off completeness all live in
+ * page-effects.js + styles.css — the build only sets the hooks.
+ */
+async function applyLivingScrollConfig(distDir, config, tenantId) {
+  const reader = (config.reader && typeof config.reader === 'object') ? config.reader : {};
+  if (config.livingScroll !== true && reader.livingScroll !== true) return;
+
+  const indexPath = path.join(distDir, 'index.html');
+  if (!(await pathExists(indexPath))) return;
+
+  let html = await fsp.readFile(indexPath, 'utf8');
+  // Idempotent, and don't fight applyBlogLayout if it already set the blog alias.
+  if (/<body[^>]*data-(?:blog-)?living-scroll(?:[\s=>])/.test(html)) return;
+  const attrs = ['data-living-scroll'];
+  // Living scroll pairs with a progress bar; only add it if not already set
+  // (applyReadingProgressConfig runs first and may have added it).
+  if (!/<body[^>]*data-reading-progress(?:[\s=>])/.test(html)) {
+    attrs.push('data-reading-progress');
+  }
+  html = html.replace(/<body(?=[\s>])/, `<body ${attrs.join(' ')}`);
+  await fsp.writeFile(indexPath, html, 'utf8');
+  console.log(`  ↳ enabled living scroll for ${tenantId}`);
+}
+
+/**
+ * On-this-page TOC + scroll-spy (#73). Opt-in via a top-level `pageToc`:
+ *   pageToc: true                              → rail placement, default min
+ *   pageToc: { placement: "rail"|"top"|"off", minHeadings: N }
+ * Sets the body hooks the pageToc page-effect reads; the effect generates the nav
+ * client-side from the page's headings.
+ */
+async function applyPageTocConfig(distDir, config, tenantId) {
+  const toc = config.pageToc;
+  if (toc !== true && (!toc || typeof toc !== 'object')) return;
+  const placementRaw = toc && typeof toc === 'object' ? toc.placement : undefined;
+  if (placementRaw === 'off' || (toc && typeof toc === 'object' && toc.enabled === false)) return;
+  const placement = placementRaw === 'top' ? 'top' : 'rail';
+  const min = toc && typeof toc === 'object' && Number.isInteger(toc.minHeadings) && toc.minHeadings > 0
+    ? toc.minHeadings : null;
+
+  const indexPath = path.join(distDir, 'index.html');
+  if (!(await pathExists(indexPath))) return;
+
+  let html = await fsp.readFile(indexPath, 'utf8');
+  if (/<body[^>]*data-page-toc(?:[\s=>])/.test(html)) return;
+  const attrs = [`data-page-toc="${placement}"`];
+  if (min) attrs.push(`data-page-toc-min="${min}"`);
+  html = html.replace(/<body(?=[\s>])/, `<body ${attrs.join(' ')}`);
+  await fsp.writeFile(indexPath, html, 'utf8');
+  console.log(`  ↳ enabled on-this-page TOC (${placement}) for ${tenantId}`);
+}
+
+/**
+ * Sidebar nav collapse behavior. Configurable via `navCollapse`:
+ *   "overlay" (default) — drawer hidden by default; hamburger slides it over the content
+ *   "push"             — nav visible; collapse slides it out and reflows the content
+ *   "instant"          — nav visible; collapse instantly hides the column
+ * Writes data-nav-collapse so styles.css can switch modes (drawer modes apply only
+ * to the default left-sidebar layout; positioned-nav demos are unaffected).
+ */
+async function applyNavCollapseConfig(distDir, config, tenantId) {
+  const raw = typeof config.navCollapse === 'string' ? config.navCollapse.toLowerCase() : '';
+  const mode = raw === 'push' || raw === 'instant' ? raw : 'overlay';
+  const indexPath = path.join(distDir, 'index.html');
+  if (!(await pathExists(indexPath))) return;
+  let html = await fsp.readFile(indexPath, 'utf8');
+  if (/<body[^>]*data-nav-collapse(?:[\s=>])/.test(html)) return;
+  html = html.replace(/<body(?=[\s>])/, `<body data-nav-collapse="${mode}"`);
+  await fsp.writeFile(indexPath, html, 'utf8');
+  console.log(`  ↳ nav collapse mode: ${mode} for ${tenantId}`);
+}
+
 /**
  * Write the synthetic blog-index section module and register it in manifest.js.
  * Mirrors applyDocsMap's injection (append + idempotent).
@@ -3822,8 +3942,11 @@ async function processNestedContent(sourceDir, distDir, tenantId, contentRoot, o
   const layout = typeof config.layout === 'string' ? config.layout.toLowerCase() : 'docs';
   const blogCfg = (config.blog && typeof config.blog === 'object') ? config.blog : {};
   const siteConfig = {
-    bottomNav: rootManifest?.bottomNav || 'mobile',
-    bottomNavSections: rootManifest?.bottomNavSections || [],
+    // Prev/next article nav at the bottom of each page is a generic docs feature,
+    // visible on all screens by default. Honor config.json or the root manifest;
+    // a tenant can scope it down with "mobile" or turn it off with "never".
+    bottomNav: config.bottomNav || rootManifest?.bottomNav || 'always',
+    bottomNavSections: config.bottomNavSections || rootManifest?.bottomNavSections || [],
     // Pass SEO-relevant config to SPA for dynamic meta tag updates.
     // siteUrl falls back to `domain` (#15); ogImage drives social cards (#16).
     siteTitle: config.title || '',
@@ -4022,7 +4145,7 @@ function buildManifestModuleSource(manifestEntries, defaultSection, siteConfig =
   const manifestJson = JSON.stringify(manifestEntries, null, 2);
   const defaultJson = JSON.stringify(defaultSection || null);
   const configJson = JSON.stringify({
-    bottomNav: siteConfig.bottomNav || 'mobile', // 'always' | 'mobile' | 'never'
+    bottomNav: siteConfig.bottomNav || 'always', // 'always' | 'mobile' | 'never'
     bottomNavSections: siteConfig.bottomNavSections || [], // Section prefixes to always show nav
     ...siteConfig
   }, null, 2);
@@ -4215,8 +4338,10 @@ async function processTenantManifestLegacy(sourceDir, distDir, tenantId, options
 
   // Extract site configuration from manifest
   const siteConfig = {
-    bottomNav: manifestData.bottomNav || 'mobile',
-    bottomNavSections: manifestData.bottomNavSections || [],
+    // Prev/next article nav is a generic docs feature, visible on all screens by
+    // default; honor config.json or the manifest, scope down with "mobile"/"never".
+    bottomNav: config.bottomNav || manifestData.bottomNav || 'always',
+    bottomNavSections: config.bottomNavSections || manifestData.bottomNavSections || [],
     // SEO-relevant config for runtime meta updates — parity with the nested path
     // so the runtime <title> brand matches config.title, not a generic fallback (#29).
     siteTitle: config.title || manifestData.title || '',
@@ -4776,6 +4901,9 @@ async function buildTenant(tenant, targetOverride, cacheDir, buildOptions) {
     await applyNavAlignment(distDir, config, tenantId);
     await applyBlogLayout(distDir, config, tenantId);
     await applyReadingProgressConfig(distDir, config, tenantId);
+    await applyLivingScrollConfig(distDir, config, tenantId);
+    await applyPageTocConfig(distDir, config, tenantId);
+    await applyNavCollapseConfig(distDir, config, tenantId);
     await applyDocsMap(distDir, config, tenantId);
     await applyWelcome(distDir, config, tenantId);
   }