@lettercamp/cli 0.1.11 → 0.1.12

package/dist/build.js

@@ -8,6 +8,7 @@ import mdx from '@astrojs/mdx';
 import { unified } from '@astrojs/markdown-remark';
 import { prepareWorkspace } from './workspace.js';
 import { readingTime } from './reading-time.js';
+import { searchContent } from './search-content.js';
 import { mediaDimensions } from './media-dimensions.js';
 import { reactViteConfig } from './react.js';
 export async function buildSite(directory, options) {
@@ -39,7 +40,7 @@ export async function buildSite(directory, options) {
             publicDir: path.join(workspace, '.lettercamp-no-public'), outDir, output: 'static',
             integrations: [mdx(), react()],
             vite: reactViteConfig,
-            markdown: { syntaxHighlight: false, processor: unified({ remarkPlugins: [contentComponents, readingTime, codeBlocks, componentBlocks, [mediaDimensions, { root }], [publicationLinks, { basePath: origin.pathname }]], rehypePlugins: [[mediaDimensions, { root }]] }) },
+            markdown: { syntaxHighlight: false, processor: unified({ remarkPlugins: [contentComponents, readingTime, searchContent, codeBlocks, componentBlocks, [mediaDimensions, { root }], [publicationLinks, { basePath: origin.pathname }]], rehypePlugins: [[mediaDimensions, { root }]] }) },
             build: { format: 'directory', ...(options.assetsPrefix ? { assetsPrefix: options.assetsPrefix } : {}) },
         });
         return outDir;

package/dist/content-components.js

@@ -1,6 +1,6 @@
 import { readCodeSettings, writeCodeSettings } from "./code-block.js";
 import { textStyleString } from "./text-styles.js";
-export const contentComponentNames = ["KeyTakeaways", "Image", "Video", "Audio", "CodeBlock", "Table", "TableRow", "TableCell"];
+export const contentComponentNames = ["KeyTakeaways", "FAQ", "FAQItem", "Image", "Video", "Audio", "CodeBlock", "Table", "TableRow", "TableCell"];
 export const isContentElement = (node) => node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement";
 export const isContentComponent = (node) => isContentElement(node) && contentComponentNames.includes(node.name);
 // Only literal values are interpreted. Expressions, spreads, and user code stay opaque.
@@ -66,6 +66,24 @@ export function expandContentComponent(node) {
         return null;
     const inline = node.type === "mdxJsxTextElement";
     switch (node.name) {
+        case "FAQ": {
+            if (inline || !allowed(props, ["width"]))
+                return null;
+            const items = meaningful(node.children.flatMap(child => child.type === "paragraph" ? child.children : [child]));
+            const details = [];
+            for (const item of items) {
+                if (!isContentElement(item) || item.name !== "FAQItem")
+                    return null;
+                const itemProps = componentProps(item);
+                if (!itemProps || !allowed(itemProps, ["question"]) || typeof itemProps.question !== "string")
+                    return null;
+                details.push(html("details", {}, [
+                    html("summary", {}, [{ type: "paragraph", children: [{ type: "text", value: itemProps.question }] }]),
+                    html("div", { "data-faq-answer": "true" }, item.children),
+                ]));
+            }
+            return html("div", { "data-lettercamp-faq": "true", "data-block-width": widthOf(props.width) }, details);
+        }
         case "KeyTakeaways":
             return allowed(props, ["width"]) && !inline ? html("div", { "data-lettercamp-key-takeaways": "true", "data-block-width": widthOf(props.width) }, node.children) : null;
         case "Image":
@@ -195,6 +213,10 @@ export function importedComponentNames(tree) {
 // Generic mdast nodes with hName work in both Markdown and Astro's MDX compiler.
 export function renderContentComponents(tree) {
     const imported = importedComponentNames(tree);
+    // Markdown needs a paragraph context to escape question text when exporting
+    // legacy HTML. A native summary only accepts phrasing content on the page.
+    const childrenOf = (node) => isContentElement(node) && node.name === "summary"
+        ? node.children.flatMap(child => child.type === "paragraph" ? child.children : [child]) : node.children;
     const visit = (node) => {
         if (isContentComponent(node) && !imported.has(node.name)) {
             const expanded = expandContentComponent(node);
@@ -203,7 +225,7 @@ export function renderContentComponents(tree) {
             return lower(expanded);
         }
         if ("children" in node)
-            node.children = node.children.map(visit);
+            node.children = childrenOf(node).map(visit);
         return node;
     };
     const lower = (node) => {
@@ -213,7 +235,7 @@ export function renderContentComponents(tree) {
             // would silently remove playback controls from published MDX pages.
             if (Object.hasOwn(properties, "controls"))
                 properties.controls = true;
-            const children = node.children.map(child => isContentElement(child) && child.name && /^[a-z]/.test(child.name) ? lower(child) : visit(child));
+            const children = childrenOf(node).map(child => isContentElement(child) && child.name && /^[a-z]/.test(child.name) ? lower(child) : visit(child));
             return { type: "lettercampElement", data: { hName: node.name, hProperties: properties }, children };
         }
         return visit(node);

package/dist/dev.js

@@ -10,6 +10,7 @@ import { unified } from '@astrojs/markdown-remark';
 import { prepareWorkspace } from './workspace.js';
 import { selectDefaultPort } from './ports.js';
 import { readingTime } from './reading-time.js';
+import { searchContent } from './search-content.js';
 import { mediaDimensions } from './media-dimensions.js';
 import { reactIntegrationDirectory, reactViteConfig } from './react.js';
 import { writeCustomLayout } from './custom-layout.js';
@@ -59,7 +60,7 @@ export async function startDev(directory, options) {
                                 addMiddleware({ entrypoint: options.middleware, order: 'post' });
                             } },
                     }] : [])],
-            markdown: { syntaxHighlight: false, processor: unified({ remarkPlugins: [contentComponents, readingTime, codeBlocks, componentBlocks, [mediaDimensions, { root: contentRoot }]], rehypePlugins: [[mediaDimensions, { root: contentRoot }]] }) },
+            markdown: { syntaxHighlight: false, processor: unified({ remarkPlugins: [contentComponents, readingTime, searchContent, codeBlocks, componentBlocks, [mediaDimensions, { root: contentRoot }]], rehypePlugins: [[mediaDimensions, { root: contentRoot }]] }) },
             devToolbar: { enabled: false },
             server: { port, host: options.host, open: options.open },
             vite: {

package/dist/search-content.js

@@ -0,0 +1,24 @@
+import { fromHtml } from 'hast-util-from-html';
+// Extract authored text during compilation, never imports, JSX props, or
+// expressions. Dynamic component output is not part of the static index.
+export function searchContent() {
+    return (tree, file) => {
+        const parts = [];
+        function visit(node) {
+            if (['script', 'style', 'template'].includes((node.tagName ?? node.name ?? '').toLowerCase()))
+                return;
+            if (['text', 'inlineCode', 'code'].includes(node.type))
+                parts.push(node.value ?? '');
+            if (node.type === 'image')
+                parts.push(node.alt ?? '');
+            if (node.type === 'html')
+                visit(fromHtml(node.value ?? '', { fragment: true }));
+            for (const child of node.children ?? [])
+                visit(child);
+        }
+        visit(tree);
+        const astro = file.data.astro;
+        if (astro?.frontmatter)
+            astro.frontmatter.searchText = parts.join(' ').replace(/\s+/g, ' ').trim();
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lettercamp/cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "The repository for the Lettercamp CLI",
   "keywords": [
     "lettercamp",

package/renderer/src/components/BlogHome.astro

@@ -1,6 +1,7 @@
 ---
 import { sitePath } from '../lib/urls.js';
 import PostCard from './PostCard.astro';
+import PostSearch from './PostSearch.astro';
 import { getPosts, getCategories } from '../lib/posts.js';
 import { readHomeWidthPx } from '../lib/home-layout';
 const { site, category = '' } = Astro.props;
@@ -16,10 +17,13 @@ const featuredLimit = 9;
     <h1>{category || (site.home.title ?? `${site.name} Blog`)}</h1>
     {site.description && <p class="description" style="margin-top: 12px">{site.description}</p>}
   </header>
-  {hasCategories && <nav class="category-selector" aria-label="Filter posts by category" hidden={site.home?.showCategories === false}>
-    <a href={sitePath("/")} data-category="" aria-current={!category ? "page" : undefined}>All</a>
-    {categories.map(item => <a href={item.href} data-category={item.name} aria-current={category === item.name ? "page" : undefined}>{item.name}</a>)}
-  </nav>}
+  <div class="blog-toolbar">
+    {hasCategories && <nav class="category-selector" aria-label="Filter posts by category" hidden={site.home?.showCategories === false}>
+      <a href={sitePath("/")} data-category="" aria-current={!category ? "page" : undefined}>All</a>
+      {categories.map(item => <a href={item.href} data-category={item.name} aria-current={category === item.name ? "page" : undefined}>{item.name}</a>)}
+    </nav>}
+    <PostSearch posts={allPosts} />
+  </div>
   <p class="sr-only" data-results-count role="status" aria-live="polite">{posts.length} articles</p>
   <section aria-label="Recent articles">
     <h2 class="sr-only">Recent articles</h2>

package/renderer/src/components/Footer.astro

@@ -15,7 +15,7 @@ const socials = (site.footer?.socials ?? []).filter(({ href }) => {
   <div class="footer-main">
     <div class="footer-brand">
       <a class="brand" href={sitePath("/")} aria-label={`${site.name} home`}>
-        <img src={logo} width="24" height="24" alt="" />
+        {logo ? <img src={logo} width="24" height="24" alt="" /> : <span>{site.name}</span>}
       </a>
     </div>
     {columns.length > 0 && <div class="footer-columns">

package/renderer/src/components/Header.astro

@@ -14,7 +14,7 @@ const logo = site.logo;
       <template data-mobile-menu-icons><MobileMenuIcons /></template>
       <div class="site-header-inner">
       <a class="brand" href={sitePath("/")}>
-        <img src={logo} width="30" height="30" alt="" />
+        {logo && <img src={logo} width="30" height="30" alt="" />}
         <span>{site.name}</span>
       </a>
       {(navLinks.length > 0 || primary) && <div class="header-actions">

package/renderer/src/components/PostSearch.astro

@@ -0,0 +1,30 @@
+---
+import '../styles/post-search.css';
+import { postSearchScript } from '../lib/post-search';
+const { posts } = Astro.props;
+// Only public post fields enter the browser. Escape HTML delimiters even in an
+// inert JSON script: article text may contain a literal closing script tag.
+const index = JSON.stringify(posts.map(post => ({
+  title: String(post.title), href: post.href,
+  summary: typeof post.description === 'string' ? post.description : '',
+  text: typeof post.searchText === 'string' ? post.searchText : '',
+  category: post.category, date: post.date.label,
+}))).replace(/</g, '\\u003c');
+---
+
+<div class="post-search-trigger" hidden>
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><circle cx="10.5" cy="10.5" r="6.5" /><path d="m16 16 4.5 4.5" /></svg>
+  <input type="search" readonly placeholder="Search articles…" aria-label="Search articles" aria-haspopup="dialog" aria-controls="post-search-dialog" />
+</div>
+<dialog id="post-search-dialog" class="post-search-dialog" aria-label="Search articles">
+  <div class="post-search-header">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><circle cx="10.5" cy="10.5" r="6.5" /><path d="m16 16 4.5 4.5" /></svg>
+    <input type="text" role="searchbox" enterkeyhint="search" placeholder="Search articles…" aria-label="Search article titles and content" aria-controls="post-search-results" autocomplete="off" spellcheck="false" autofocus />
+    <button type="button" class="post-search-close" aria-label="Close search"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="m6 6 12 12M18 6 6 18" /></svg></button>
+  </div>
+  <p class="post-search-status" role="status" aria-live="polite" aria-atomic="true"></p>
+  <ul id="post-search-results" class="post-search-results" aria-label="Matching articles"></ul>
+  <p class="post-search-empty" hidden>No articles found. Try a different word or title.</p>
+</dialog>
+<script is:inline type="application/json" data-post-search-index set:html={index} />
+<script is:inline set:html={postSearchScript} />

package/renderer/src/components/RelatedPosts.astro

@@ -0,0 +1,11 @@
+---
+import PostCard from './PostCard.astro';
+const { posts, site } = Astro.props;
+---
+
+{posts.length > 0 && <section class="related-posts" aria-labelledby="related-posts-heading" hidden={site.post?.showRelatedPosts === false}>
+  <h2 id="related-posts-heading">Related</h2>
+  <div class="post-list">
+    {posts.map(post => <PostCard post={post} site={site} />)}
+  </div>
+</section>}

package/renderer/src/layouts/SiteLayout.astro

@@ -14,6 +14,7 @@ import { mobileNavigationScript } from '../lib/mobile-navigation';
 import { blockWidthStyles } from '../lib/block-widths';
 import { tableStyles } from '../lib/table-styles';
 import { keyTakeawaysStyles } from '../lib/key-takeaways';
+import { faqStyles } from '../lib/faq';
 import { siteColors } from '../lib/site-colors';
 import { imageWidthStyles } from '../lib/image-widths';
 import { googleAnalyticsScript } from '../lib/analytics';
@@ -25,14 +26,15 @@ const meta = pageMetadata(site, page, Astro.url, article, basePath);
 const typography = site.design?.typography ?? {};
 const fonts = fontResources(typography, article ? 700 : 500);
 const fontSize = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
-const baseSize = fontSize(typography.baseSizePx, 16);
+const headingBaseSize = fontSize(typography.headingBaseSizePx, 18);
+const bodyBaseSize = fontSize(typography.bodyBaseSizePx, 16);
 const bodyLineHeight = fontSize(typography.bodyLineHeight, 1.8);
 const colors = siteColors(site.design);
 const analytics = googleAnalyticsScript(site.analytics?.googleAnalyticsId);
 ---
 
 <!doctype html>
-<html data-base-path={basePath} data-site-accent={colors['--site-accent'] !== 'inherit' ? '' : undefined} lang={meta.language} style={{ ...colors, '--image-radius': readImageRadius(site.design?.imageRadiusPercent) / 100, '--font-family': fonts.bodyFamily, '--heading-font': fonts.headingFamily, '--type-scale': baseSize / 16, '--body-line-height': bodyLineHeight }}>
+<html data-base-path={basePath} data-site-accent={colors['--site-accent'] !== 'inherit' ? '' : undefined} lang={meta.language} style={{ ...colors, '--image-radius': readImageRadius(site.design?.imageRadiusPercent) / 100, '--font-family': fonts.bodyFamily, '--heading-font': fonts.headingFamily, '--heading-type-scale': headingBaseSize / 18, '--body-type-scale': bodyBaseSize / 16, '--body-line-height': bodyLineHeight }}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -48,6 +50,7 @@ const analytics = googleAnalyticsScript(site.analytics?.googleAnalyticsId);
     <style is:inline set:html={codeBlockStyles} />
     <style is:inline set:html={tableStyles} />
     <style is:inline set:html={keyTakeawaysStyles} />
+    <style is:inline set:html={faqStyles} />
     <title>{meta.documentTitle}</title>
     <meta name="description" content={meta.description} />
     {meta.keywords && <meta name="keywords" content={meta.keywords} />}

package/renderer/src/lib/branding.js

@@ -7,6 +7,8 @@ export const defaultSiteBranding = {
 export function withDefaultBranding(source) {
   const branding = Object.fromEntries(Object.entries(defaultSiteBranding).map(([key, fallback]) =>
     [key, typeof source[key] === 'string' && source[key].trim() ? source[key] : fallback]));
+  // An explicit empty logo disables the image while omitted logos keep the default.
+  if (typeof source.logo === 'string') branding.logo = source.logo.trim();
   return {
     ...source,
     ...branding,

package/renderer/src/lib/faq.ts

@@ -0,0 +1,25 @@
+// Generated from lettercamp/lib/faq.ts.
+// Shared by the editor preview and published posts. Native disclosures work
+// without hydration and let readers keep several answers open at once.
+export const faqStyles = `
+[data-lettercamp-faq] { margin-block: 24px; color: inherit; overflow-wrap: anywhere; }
+[data-lettercamp-faq] > details { border-bottom: 1px solid var(--site-border, #e5e5e5); }
+[data-lettercamp-faq] > details:first-child { border-top: 1px solid var(--site-border, #e5e5e5); }
+[data-lettercamp-faq] > details > summary {
+  display: flex; align-items: center; justify-content: space-between; gap: 24px;
+  padding: 18px 0; cursor: pointer; list-style: none; font-weight: 600; line-height: 1.5;
+}
+[data-lettercamp-faq] > details > summary::-webkit-details-marker { display: none; }
+[data-lettercamp-faq] > details > summary::after {
+  content: ''; width: 7px; height: 7px; flex: 0 0 7px; margin: 0 4px 4px;
+  border-right: 1.5px solid currentColor; border-bottom: 1.5px solid currentColor;
+  transform: rotate(45deg); transition: transform 150ms;
+}
+[data-lettercamp-faq] > details[open] > summary::after { transform: translateY(4px) rotate(225deg); }
+[data-lettercamp-faq] > details > summary:focus-visible { outline: 2px solid currentColor; outline-offset: 4px; border-radius: 2px; }
+[data-lettercamp-faq] > details > [data-faq-answer] { padding: 0 28px 20px 0; }
+[data-lettercamp-faq] > details > [data-faq-answer] > :first-child { margin-top: 0; }
+[data-lettercamp-faq] > details > [data-faq-answer] > :last-child { margin-bottom: 0; }
+@media (prefers-reduced-motion: reduce) { [data-lettercamp-faq] > details > summary::after { transition: none; } }
+@media print { [data-lettercamp-faq] > details::details-content { content-visibility: visible; } }
+`;

package/renderer/src/lib/post-search.ts

@@ -0,0 +1,194 @@
+export const postSearchScript = String.raw`(() => {
+  const trigger = document.querySelector('.post-search-trigger');
+  const dialog = document.querySelector('#post-search-dialog');
+  const data = document.querySelector('[data-post-search-index]');
+  if (!trigger || !dialog || !data || typeof dialog.showModal !== 'function') return;
+  const opener = trigger.querySelector('input');
+  const input = dialog.querySelector('input');
+  const results = dialog.querySelector('.post-search-results');
+  const status = dialog.querySelector('.post-search-status');
+  const empty = dialog.querySelector('.post-search-empty');
+  const limit = 20;
+  let posts;
+  const normalized = [];
+  let generation = 0;
+  let timer;
+  let restoringFocus = false;
+  const normalize = text => text.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase().replace(/\s+/g, ' ').trim();
+  const element = (tag, className, text) => {
+    const node = document.createElement(tag);
+    node.className = className;
+    node.textContent = text;
+    return node;
+  };
+  function highlighted(className, text, terms) {
+    const node = element('span', className, '');
+    if (!terms.length) { node.textContent = text; return node; }
+    // Map folded characters back to authored text, including accents and
+    // ligatures. Only the displayed titles/excerpts need this small offset map.
+    let folded = '';
+    let offset = 0;
+    const starts = [], ends = [];
+    for (const character of text) {
+      const end = offset + character.length;
+      const value = character.normalize('NFKD').replace(/\p{M}/gu, '').replace(/\s/g, ' ');
+      if (!value && ends.length) ends[ends.length - 1] = end;
+      for (const unit of value) {
+        if (unit === ' ' && folded.endsWith(' ')) { ends[ends.length - 1] = end; continue; }
+        folded += unit;
+        for (let i = 0; i < unit.length; i++) { starts.push(offset); ends.push(end); }
+      }
+      offset = end;
+    }
+    folded = folded.toLowerCase();
+    const ranges = [];
+    for (const term of new Set([normalize(input.value), ...terms])) {
+      let start = folded.indexOf(term);
+      while (start >= 0) {
+        ranges.push([starts[start], ends[start + term.length - 1]]);
+        start = folded.indexOf(term, start + term.length);
+      }
+    }
+    ranges.sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+    const merged = [];
+    for (const range of ranges) {
+      const previous = merged.at(-1);
+      if (previous && range[0] <= previous[1]) previous[1] = Math.max(previous[1], range[1]);
+      else merged.push(range);
+    }
+    let cursor = 0;
+    for (const [start, end] of merged) {
+      node.append(document.createTextNode(text.slice(cursor, start)), element('mark', 'post-search-match', text.slice(start, end)));
+      cursor = end;
+    }
+    node.append(document.createTextNode(text.slice(cursor)));
+    return node;
+  }
+  const snippet = (post, terms, entry) => {
+    const text = post.text || post.summary;
+    const folded = post.text ? entry.text : entry.summary;
+    const match = terms.map(term => folded.indexOf(term)).filter(index => index >= 0);
+    const start = match.length ? Math.max(0, Math.min(...match) - 55) : 0;
+    // Normalization can change character offsets slightly; excerpts are just
+    // context, so keep the original authored text rather than folded text.
+    return (start ? '…' : '') + text.slice(start, start + 180) + (text.length > start + 180 ? '…' : '');
+  };
+  function render(matches, count, terms) {
+    const fragment = document.createDocumentFragment();
+    for (const { index } of matches) {
+      const post = posts[index];
+      const row = document.createElement('li');
+      const link = element('a', 'post-search-result', '');
+      link.href = post.href;
+      link.append(highlighted('post-search-title', post.title, terms));
+      const meta = [post.category, post.date].filter(Boolean).join(' · ');
+      if (meta) link.append(element('span', 'post-search-meta', meta));
+      const excerpt = terms.length ? snippet(post, terms, normalized[index]) : post.summary;
+      if (excerpt) link.append(highlighted('post-search-excerpt', excerpt, terms));
+      row.append(link);
+      fragment.append(row);
+    }
+    results.replaceChildren(fragment);
+    results.scrollTop = 0;
+    results.removeAttribute('aria-busy');
+    empty.hidden = count > 0;
+    empty.textContent = posts.length ? 'No articles found. Try a different word or title.' : 'No articles here yet.';
+    status.textContent = !terms.length ? 'Recent articles' : count > limit
+      ? 'Showing ' + limit + ' of ' + count + ' matching articles. Keep typing to narrow your search.'
+      : count + (count === 1 ? ' article found' : ' articles found');
+  }
+  function search() {
+    clearTimeout(timer);
+    const current = ++generation;
+    const query = normalize(input.value);
+    const terms = [...new Set(query.split(' ').filter(Boolean))];
+    if (!terms.length) {
+      render(posts.slice(0, 8).map((_, index) => ({ index })), posts.length, terms);
+      return;
+    }
+    // Clear stale links immediately so Enter never opens an old query's result.
+    results.replaceChildren();
+    results.setAttribute('aria-busy', 'true');
+    empty.hidden = true;
+    status.textContent = 'Searching…';
+    let cursor = 0;
+    let count = 0;
+    const best = [];
+    function step() {
+      if (current !== generation || !dialog.open) return;
+      const deadline = performance.now() + 6;
+      while (cursor < posts.length) {
+        const index = cursor++;
+        const post = posts[index];
+        const entry = normalized[index] ??= {
+          title: normalize(post.title),
+          summary: normalize(post.summary), text: normalize(post.text),
+        };
+        if (terms.every(term => entry.title.includes(term) || entry.summary.includes(term) || entry.text.includes(term))) {
+          count++;
+          const score = (entry.title === query ? 1000 : entry.title.startsWith(query) ? 500 : entry.title.includes(query) ? 250 : 0)
+            + terms.reduce((sum, term) => sum + (entry.title.includes(term) ? 10 : 0), 0);
+          const position = best.findIndex(item => score > item.score);
+          if (position >= 0) best.splice(position, 0, { index, score });
+          else if (best.length < limit) best.push({ index, score });
+          if (best.length > limit) best.pop();
+        }
+        // Yield between chunks for large publications. A newer query cancels
+        // this work; only the best 20 matches ever become DOM nodes.
+        if (performance.now() >= deadline) break;
+      }
+      if (cursor < posts.length) timer = setTimeout(step, 0);
+      else render(best, count, terms);
+    }
+    timer = setTimeout(step, 0);
+  }
+  function open() {
+    if (restoringFocus || dialog.open) return;
+    if (!posts) {
+      posts = JSON.parse(data.textContent);
+      data.textContent = '';
+    }
+    dialog.showModal();
+    input.focus({ preventScroll: true });
+    search();
+  }
+  function close() {
+    restoringFocus = true;
+    ++generation;
+    clearTimeout(timer);
+    dialog.close();
+    opener.focus({ preventScroll: true });
+    // Native dialog focus restoration must not immediately reopen the search.
+    queueMicrotask(() => { restoringFocus = false; });
+  }
+  opener.addEventListener('focus', open);
+  opener.addEventListener('click', open);
+  opener.addEventListener('keydown', event => {
+    if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); open(); }
+  });
+  input.addEventListener('input', event => { if (!event.isComposing) search(); });
+  input.addEventListener('compositionend', search);
+  dialog.querySelector('.post-search-close').addEventListener('click', close);
+  dialog.addEventListener('cancel', event => { event.preventDefault(); close(); });
+  let backdropDown = false;
+  dialog.addEventListener('pointerdown', event => { backdropDown = event.target === dialog; });
+  dialog.addEventListener('click', event => {
+    if (event.target === dialog && backdropDown) close();
+  });
+  dialog.addEventListener('keydown', event => {
+    if (event.isComposing) return;
+    const links = [...results.querySelectorAll('a')];
+    const index = links.indexOf(document.activeElement);
+    if (event.key === 'ArrowDown' && (event.target === input || index >= 0)) {
+      event.preventDefault();
+      (links[Math.min(index + 1, links.length - 1)] || input).focus();
+    } else if (event.key === 'ArrowUp' && (event.target === input || index >= 0)) {
+      event.preventDefault();
+      (index === -1 ? links.at(-1) || input : links[index - 1] || input).focus();
+    } else if (event.key === 'Enter' && event.target === input) {
+      event.preventDefault();
+      links[0]?.click();
+    }
+  });
+  trigger.hidden = false;
+})();`;

package/renderer/src/lib/related-posts.ts

@@ -0,0 +1,50 @@
+// Generated from lettercamp/lib/related-posts.ts.
+type RelatedPost = { href: string; title?: unknown; description?: unknown; category?: unknown; draft?: unknown };
+
+// Shared by the static renderer and editor preview. Keep this function self-contained
+// so the preview bridge can embed it without shipping a separate client bundle.
+export function createRelatedPostSelector<T extends RelatedPost>(posts: T[], language = "en") {
+  const stopWords: Record<string, string> = {
+    en: "a an and are as at be been but by for from has have how in is it its of on or our that the their this to was we were what when which who will with you your",
+    es: "a al con de del el en es esta este la las lo los o para por que se su sus un una y",
+    fr: "a au aux avec ce ces dans de des du elle en est et il la le les leur ou par pas pour que qui se son sur un une",
+    de: "am an auf aus bei das dem den der des die ein eine einer es für im in ist mit oder sich sind und von zu zum zur",
+    it: "a al alla che con da dal dei del della di e è gli i il in la le lo o per si su un una",
+    pt: "a ao as com da das de do dos e em é na nas no nos o os ou para por que se sua um uma",
+  };
+  const ignored = new Set((stopWords[language.toLowerCase().split("-")[0]] ?? "").split(" "));
+  const segmenter = new Intl.Segmenter(language, { granularity: "word" });
+  const text = {
+    normalize(value: unknown) {
+      return typeof value === "string" ? value.normalize("NFKC").toLocaleLowerCase(language).trim() : "";
+    },
+    prepare(post: T) {
+      const words = new Map<string, number>();
+      for (const [value, weight] of [[post.description, 1], [post.title, 3]] as const) {
+        for (const part of segmenter.segment(text.normalize(value))) {
+          if (part.isWordLike && !ignored.has(part.segment)) words.set(part.segment, weight);
+        }
+      }
+      return { post, words, weight: [...words.values()].reduce((sum, weight) => sum + weight, 0), category: text.normalize(post.category) };
+    },
+    hash(value: string) {
+      let result = 2166136261;
+      for (let index = 0; index < value.length; index++) result = Math.imul(result ^ value.charCodeAt(index), 16777619);
+      return result >>> 0;
+    },
+  };
+  const candidates = [...new Map(posts.filter(post => post.draft !== true).map(post => [post.href, post])).values()].map(text.prepare);
+  const byHref = new Map(candidates.map(candidate => [candidate.post.href, candidate]));
+  return (current: T): T[] => {
+    const existing = byHref.get(current.href);
+    const source = existing?.post === current ? existing : text.prepare(current);
+    return candidates.filter(candidate => candidate.post.href !== current.href).map(candidate => {
+      let overlap = 0;
+      for (const [word, weight] of source.words) overlap += Math.min(weight, candidate.words.get(word) ?? 0);
+      const union = source.weight + candidate.weight - overlap;
+      const score = (union ? 75 * overlap / union : 0) + (source.category && source.category === candidate.category ? 25 : 0);
+      return { post: candidate.post, score, tie: text.hash(current.href + "\n" + candidate.post.href) };
+    }).sort((a, b) => b.score - a.score || a.tie - b.tie || (a.post.href < b.post.href ? -1 : a.post.href > b.post.href ? 1 : 0))
+      .slice(0, 3).map(candidate => candidate.post);
+  };
+}

package/renderer/src/pages/[...slug].astro

@@ -1,20 +1,27 @@
 ---
 import SiteLayout from '../layouts/SiteLayout.astro';
 import AuthorByline from '../components/AuthorByline.astro';
-import { pageSlug, postDate, getCategories } from '../lib/posts.js';
+import RelatedPosts from '../components/RelatedPosts.astro';
+import { pageSlug, postDate, getCategories, getPosts } from '../lib/posts.js';
+import { createRelatedPostSelector } from '../lib/related-posts';
+import { sitePath } from '../lib/urls.js';
 import site from '../site.js';
 import { readContentWidthEm } from '../lib/post-layout';
 import { pages } from '../content.js';
 import { postShareButton } from '../lib/post-share';
 
 export function getStaticPaths() {
+  const posts = getPosts(site.language, site.timeZone);
+  const selectRelated = createRelatedPostSelector(posts, site.language);
+  const byHref = new Map(posts.map(post => [post.href, post]));
   return Object.entries(pages).map(([filename, page]) => {
     const slug = pageSlug(filename);
-    return { params: { slug }, props: { page } };
+    const href = sitePath(`/${slug.split('/').map(encodeURIComponent).join('/')}/`);
+    return { params: { slug }, props: { page, relatedPosts: selectRelated(byHref.get(href)) } };
   });
 }
 
-const { page } = Astro.props;
+const { page, relatedPosts } = Astro.props;
 const { Content, frontmatter = {} } = page;
 const coverImage = frontmatter.image ?? frontmatter.ogImage;
 const coverImageWidth = Number(frontmatter.coverImageWidth ?? (frontmatter.image ? frontmatter.imageWidth : undefined));
@@ -65,5 +72,6 @@ const coverWidth = /^[0-9]+$/.test(String(frontmatter.coverWidth)) && Number(fro
       </aside>}
       <div class="prose"><Content /></div>
     </div>
+    <RelatedPosts posts={relatedPosts} site={site} />
   </article>
 </SiteLayout>

package/renderer/src/styles/post-search.css

@@ -0,0 +1,37 @@
+.post-search-trigger { position: relative; flex: 0 1 240px; min-width: 180px; margin-left: auto; }
+.post-search-trigger svg { position: absolute; left: 13px; top: 50%; width: 16px; height: 16px; transform: translateY(-50%); color: var(--site-text-muted); pointer-events: none; }
+.post-search-trigger input { width: 100%; height: 36px; padding: 0 14px 0 38px; border: 1px solid var(--site-border-strong); border-radius: 999px; background: var(--site-background); color: var(--site-foreground); font: 400 var(--text-label)/1.5 var(--font-family); cursor: text; }
+.post-search-trigger input::placeholder, .post-search-header input::placeholder { color: var(--site-text-secondary); opacity: 1; }
+.post-search-trigger input:focus-visible { outline: 2px solid var(--site-foreground); outline-offset: 3px; }
+html:has(.post-search-dialog[open]) { overflow: hidden; }
+.post-search-dialog { position: fixed; inset: 0; width: min(620px, calc(100vw - 32px)); max-width: none; max-height: min(440px, calc(100dvh - 48px)); margin: auto; padding: 0; overflow: hidden; border: 1px solid var(--site-border); border-radius: 14px; background: var(--site-background); color: var(--site-foreground); box-shadow: 0 20px 80px #0003; font: 400 var(--text-label)/1.5 var(--font-family); }
+.post-search-dialog[open] { display: flex; flex-direction: column; }
+.post-search-dialog::backdrop { background: color-mix(in srgb, var(--site-background) 65%, transparent); backdrop-filter: blur(3px); }
+.post-search-header { display: flex; flex-shrink: 0; align-items: center; gap: 10px; padding: 10px 14px; border-bottom: 1px solid var(--site-border); }
+.post-search-header > svg { width: 20px; height: 20px; flex-shrink: 0; color: var(--site-text-secondary); }
+.post-search-header input { min-width: 0; width: 100%; padding: 2px 0; border: 0; outline: none; background: transparent; color: inherit; font: 400 max(16px, var(--text-small))/1.5 var(--font-family); }
+.post-search-header:focus-within { border-bottom-color: var(--site-border-strong); }
+.post-search-close { display: grid; flex-shrink: 0; place-items: center; width: 28px; height: 28px; padding: 4px; border: 0; background: transparent; color: var(--site-text-secondary); }
+.post-search-close:hover { color: var(--site-foreground); }
+.post-search-close svg { width: 20px; height: 20px; }
+.post-search-status { flex-shrink: 0; margin: 0; padding: 8px 16px 4px; color: var(--site-text-secondary); font-size: var(--text-meta); }
+.post-search-results { flex: 0 1 auto; min-height: 0; margin: 0; padding: 0 6px 6px; overflow: auto; overscroll-behavior: contain; list-style: none; }
+.post-search-result { display: flex; flex-direction: column; gap: 2px; padding: 8px 10px; border-radius: 8px; color: inherit; text-decoration: none; overflow-wrap: anywhere; }
+.post-search-result:is(:hover, :focus-visible) { outline: none; background: var(--site-surface-active); border-radius: 8px; }
+.post-search-title { font-size: var(--text-label); font-weight: 500; }
+.post-search-meta { color: var(--site-text-secondary); font-size: var(--text-meta); }
+.post-search-excerpt { font-size: var(--text-meta); display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; color: var(--site-text-secondary); }
+.post-search-empty { margin: 0; padding: 20px 16px; color: var(--site-text-secondary); text-align: center; }
+.post-search-results:empty { flex: 0; }
+@media (max-width: 640px) {
+  .post-search-trigger { flex-basis: 100%; min-width: 0; }
+  .post-search-dialog { width: calc(100vw - 24px); max-height: min(440px, calc(100dvh - 24px)); }
+  .post-search-header { padding: 10px 12px; }
+}
+@media (prefers-reduced-motion: no-preference) {
+  .post-search-dialog[open] { animation: post-search-enter 140ms ease-out; }
+  @keyframes post-search-enter { from { opacity: 0; transform: translateY(6px) scale(.98); } to { opacity: 1; transform: none; } }
+}
+
+.post-search-match { padding: 0 1px; border-radius: 3px; background: color-mix(in srgb, var(--site-foreground) 7%, transparent); color: var(--site-foreground); font-weight: 600; }
+html[data-site-accent] .post-search-match { background: color-mix(in srgb, var(--site-accent) 25%, transparent); }

package/renderer/src/styles/site.css

@@ -1,14 +1,16 @@
 :root {
   --font-family: 'Inter', Arial, Helvetica, sans-serif;
   font-size: 100%;
-  --type-scale: 1;
-  --text-base: calc(1rem * var(--type-scale));
-  --text-title: calc(clamp(2rem, 3.5vw, 2.625rem) * var(--type-scale));
-  --text-card-title: calc(clamp(1.125rem, 1.4vw, 1.25rem) * var(--type-scale));
-  --text-h2: calc(var(--text-base) * 1.875);
-  --text-h3: calc(var(--text-base) * 1.5);
-  --text-h4: calc(var(--text-base) * 1.25);
-  --text-h5: calc(var(--text-base) * 1.125);
+  --heading-type-scale: 1;
+  --body-type-scale: 1;
+  --heading-base: calc(1.125rem * var(--heading-type-scale));
+  --text-base: calc(1rem * var(--body-type-scale));
+  --text-title: calc(clamp(2rem, 3.5vw, 2.625rem) * var(--heading-type-scale));
+  --text-card-title: calc(clamp(1.125rem, 1.4vw, 1.25rem) * var(--heading-type-scale));
+  --text-h2: calc(var(--heading-base) * 30 / 18);
+  --text-h3: calc(var(--heading-base) * 24 / 18);
+  --text-h4: calc(var(--heading-base) * 20 / 18);
+  --text-h5: var(--heading-base);
   --text-summary: calc(var(--text-base) * .9375);
   --text-small: calc(var(--text-base) * .875);
   --text-label: calc(var(--text-base) * .8125);
@@ -72,17 +74,21 @@ html:has(.site-header[data-header-position='fixed']) { scroll-padding-top: 80px;
 }
 .blog-home { padding-block: 72px 100px; }
 .blog-heading { margin-bottom: 18px; }
-.blog-home:not(:has(> .category-selector:not([hidden]))) > .blog-heading { margin-bottom: 64px; }
+.blog-home:not(:has(.blog-toolbar > :not([hidden], script, dialog))) > .blog-heading { margin-bottom: 64px; }
 .blog-heading h1 { margin-bottom: 0; }
 .article-category { margin: 0 0 20px; }
 .article-category a, .post-card-category { display: inline-flex; align-items: center; justify-content: center; padding: 4px 15px; border: 0; border-radius: 10px; background: var(--site-surface); color: var(--muted); font-size: var(--text-meta); font-weight: 500; line-height: 1.333333; text-decoration: none; }
 h1 { font-size: var(--text-title); font-weight: 500; line-height: 1.15; letter-spacing: -.04em; margin: 0 0 22px; }
 .description { color: var(--text-secondary); font-size: var(--text-base); line-height: 1.65; max-width: 660px; margin: 0; }
-.category-selector { display: flex; flex-wrap: wrap; gap: 8px 24px; margin-block: 0 40px; }
+.blog-toolbar { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 16px 32px; margin-bottom: 40px; }
+.blog-toolbar:not(:has(> :not([hidden], script, dialog))) { display: none; }
+.category-selector { display: flex; flex-wrap: wrap; gap: 8px 24px; }
 .category-selector a { padding-block: 8px; color: var(--muted); font-size: var(--text-small); line-height: 1.5; text-decoration: none; transition: color .15s; }
 .category-selector a:hover { color: var(--site-foreground); }
 .category-selector a[aria-current='page'] { color: var(--site-foreground); font-weight: 500; }
 .post-list { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 64px 48px; }
+.related-posts { margin-top: 80px; padding-top: 40px; }
+.related-posts > h2 { margin: 0 0 32px; font-size: var(--text-h3); font-weight: 500; letter-spacing: -.025em; }
 .post-card { position: relative; isolation: isolate; min-width: 0; }
 .post-card-link { color: inherit; text-decoration: none; }
 .post-card-link::after { content: ''; position: absolute; inset: 0; z-index: 1; }
@@ -138,7 +144,7 @@ h1 { font-size: var(--text-title); font-weight: 500; line-height: 1.15; letter-s
 .archive-list .post-card-cover, .archive-list .post-card-description { display: none; }
 .archive-list .post-card-content { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, .85fr); align-items: center; gap: 16px 32px; }
 .archive-list .post-card-details { display: none; }
-.archive-list h3 { grid-area: 1 / 1; font-size: var(--text-base); margin: 0; }
+.archive-list h3 { grid-area: 1 / 1; font-size: calc(var(--heading-base) * 16 / 18); margin: 0; }
 .archive-list .post-card-meta { grid-area: 1 / 2; display: flex; align-items: center; justify-content: flex-end; flex-wrap: wrap; gap: 6px 16px; margin: 0; color: var(--site-text-muted); font-size: var(--text-label); line-height: 1.4; }
 .archive-list .archive-date { display: block; white-space: nowrap; }
 .archive-list .post-byline { align-items: flex-end; min-width: 0; margin: 0; padding: 0; text-align: right; }
@@ -195,7 +201,7 @@ h1 { font-size: var(--text-title); font-weight: 500; line-height: 1.15; letter-s
 .prose h3 { font-size: var(--text-h3); line-height: 1.4; font-weight: 600; letter-spacing: -.03em; margin: 1.7em 0 .6em; }
 .prose h4 { font-size: var(--text-h4); line-height: 1.5; font-weight: 600; margin: 1.6em 0 .5em; }
 .prose h5 { font-size: var(--text-h5); line-height: 1.5; }
-.prose h6 { font-size: var(--text-base); line-height: 1.5; }
+.prose h6 { font-size: calc(var(--heading-base) * 16 / 18); line-height: 1.5; }
 .prose h3 a { text-decoration: none; }
 .prose h3 a:hover { text-decoration: underline; }
 .prose ul, .prose ol { padding-left: 1.4em; }
@@ -212,7 +218,7 @@ h1 { font-size: var(--text-title); font-weight: 500; line-height: 1.15; letter-s
 .card { display: flex; flex-direction: column; align-items: start; padding: 26px; border-radius: 6px; background: var(--site-surface-hover); text-decoration: none; }
 .card:hover { background: var(--site-surface-active); }
 .card-eyebrow { font-size: calc(var(--text-base) * .6875); text-transform: uppercase; letter-spacing: .1em; color: var(--muted); }
-.prose .card h3 { font-size: calc(var(--text-base) * 1.375); margin: 12px 0 6px; }
+.prose .card h3 { font-size: calc(var(--heading-base) * 22 / 18); margin: 12px 0 6px; }
 .prose .card p { font-size: var(--text-summary); line-height: 1.7; color: var(--muted); margin: 0 0 20px; }
 .card-link { font-size: var(--text-label); font-weight: 600; margin-top: auto; }
 .site-footer { border-top: 1px solid var(--line); }
@@ -265,9 +271,11 @@ h1 { font-size: var(--text-title); font-weight: 500; line-height: 1.15; letter-s
   .mobile-menu-panel a { flex: none; padding: 12px 0; font-size: var(--text-base); line-height: 1.4; overflow-wrap: anywhere; }
   @media (prefers-reduced-motion: no-preference) { .mobile-navigation[open] .mobile-menu-panel { animation: mobile-menu-enter 180ms ease-out; } }
   .blog-home { padding-block: 46px 64px; }
-  .blog-home:not(:has(> .category-selector:not([hidden]))) > .blog-heading { margin-bottom: 40px; }
-  .category-selector { margin-bottom: 36px; gap: 4px 20px; }
+  .blog-home:not(:has(.blog-toolbar > :not([hidden], script, dialog))) > .blog-heading { margin-bottom: 40px; }
+  .blog-toolbar { margin-bottom: 36px; }
+  .category-selector { gap: 4px 20px; }
   .post-list { grid-template-columns: 1fr; gap: 48px; }
+  .related-posts { margin-top: 56px; padding-top: 32px; }
   [data-home-layout='rows'] .post-list .post-card-layout { display: flex; align-items: stretch; gap: 20px; }
   [data-home-layout='rows'] .post-list .post-card h3 { font-size: var(--text-h4); }
   .archive { margin-top: 72px; }