@kamod-ch/preactpress 2.1.0 → 2.2.0

package/src/shared/pageReady.ts

@@ -0,0 +1,255 @@
+import { escapeHtml } from "./escapeHtml.js";
+import type { PageReadyConfig, ResolvedPageReadyConfig } from "../node/siteConfig.js";
+
+const DEFAULT_PRELOADER = `<div id="pp-preloader" role="status" aria-live="polite" aria-label="Loading">
+  <div class="pp-preloader-spinner" aria-hidden="true"></div>
+</div>`;
+
+const PAGE_READY_HEAD = `<style id="pp-page-ready">
+  html:not(.pp-ready) #app {
+    visibility: hidden;
+  }
+  html.pp-ready #pp-preloader {
+    display: none !important;
+  }
+  :root,
+  :root[data-theme="light"] {
+    --pp-preloader-bg: #ffffff;
+    --pp-preloader-track: #e5e7eb;
+    --pp-preloader-accent: #171717;
+  }
+  :root[data-theme="dark"],
+  html.dark {
+    --pp-preloader-bg: #1b1b1f;
+    --pp-preloader-track: #2f2f32;
+    --pp-preloader-accent: rgba(255, 255, 245, 0.86);
+  }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme]) {
+      --pp-preloader-bg: #1b1b1f;
+      --pp-preloader-track: #2f2f32;
+      --pp-preloader-accent: rgba(255, 255, 245, 0.86);
+    }
+  }
+  #pp-preloader {
+    position: fixed;
+    inset: 0;
+    z-index: 2147483647;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--pp-preloader-bg);
+    color-scheme: light dark;
+  }
+  .pp-preloader-spinner {
+    width: 2rem;
+    height: 2rem;
+    border: 3px solid var(--pp-preloader-track);
+    border-top-color: var(--pp-preloader-accent);
+    border-radius: 50%;
+    animation: pp-preloader-spin 0.7s linear infinite;
+    box-sizing: border-box;
+  }
+  @keyframes pp-preloader-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+</style>
+<script>
+  document.documentElement.setAttribute("aria-busy", "true");
+</script>
+<noscript>
+  <style>
+    #pp-preloader {
+      display: none !important;
+    }
+    #app {
+      visibility: visible !important;
+    }
+  </style>
+</noscript>`;
+
+function escapeJsString(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function normalizePreloaderHtml(html: string): string {
+  if (/id=["']pp-preloader["']/.test(html)) return html;
+  return `<div id="pp-preloader" role="status" aria-live="polite" aria-label="Loading">${html}</div>`;
+}
+
+function buildThemeCssProbe(probe: string | false): string {
+  if (probe === false) return "";
+  const safeProbe = escapeJsString(probe);
+  return `var probe = getComputedStyle(document.documentElement).getPropertyValue("${safeProbe}");
+      if (probe && probe.trim() !== "") return true;
+
+      `;
+}
+
+function buildPageReadyBootScript(config: ResolvedPageReadyConfig): string {
+  const themeProbe = buildThemeCssProbe(config.probe);
+  return `<script>
+  (function () {
+    var READY_CLASS = "pp-ready";
+    var FALLBACK_MS = ${config.fallbackMs};
+    var MAX_FRAMES = ${config.maxFrames};
+    var STABLE_FRAMES = ${config.stableFrames};
+
+    function markReady() {
+      if (document.documentElement.classList.contains(READY_CLASS)) return;
+      document.documentElement.classList.add(READY_CLASS);
+      document.documentElement.removeAttribute("aria-busy");
+    }
+
+    function themeCssApplied() {
+      ${themeProbe}var links = document.querySelectorAll('link[rel="stylesheet"][href]');
+      if (!links.length) return true;
+
+      for (var i = 0; i < links.length; i++) {
+        var link = links[i];
+        if (link.media === "print") return false;
+        try {
+          if (!link.sheet) return false;
+        } catch (e) {
+          return false;
+        }
+      }
+      return true;
+    }
+
+    function whenStylesReady() {
+      return new Promise(function (resolve) {
+        var settled = false;
+        var lastResourceCount = -1;
+        var stableFrames = 0;
+
+        function resourceCount() {
+          return (
+            document.querySelectorAll('link[rel="stylesheet"][href]').length +
+            document.querySelectorAll("style:not(#pp-page-ready)").length
+          );
+        }
+
+        function settle() {
+          if (settled) return;
+          if (!themeCssApplied()) return;
+          var count = resourceCount();
+          if (count !== lastResourceCount) {
+            lastResourceCount = count;
+            stableFrames = 0;
+            return;
+          }
+          stableFrames += 1;
+          if (stableFrames < STABLE_FRAMES) return;
+          settled = true;
+          observer.disconnect();
+          var app = document.getElementById("app");
+          if (app) void app.offsetHeight;
+          requestAnimationFrame(function () {
+            requestAnimationFrame(function () {
+              requestAnimationFrame(resolve);
+            });
+          });
+        }
+
+        var observer = new MutationObserver(settle);
+        observer.observe(document.head, { childList: true, subtree: true });
+
+        var links = document.querySelectorAll('link[rel="stylesheet"][href]');
+        for (var i = 0; i < links.length; i++) {
+          links[i].addEventListener("load", settle);
+          links[i].addEventListener("error", settle);
+        }
+
+        var frames = 0;
+        function poll() {
+          settle();
+          if (settled) return;
+          frames += 1;
+          if (frames >= MAX_FRAMES) {
+            settled = true;
+            observer.disconnect();
+            resolve();
+            return;
+          }
+          requestAnimationFrame(poll);
+        }
+        poll();
+      });
+    }
+
+    function start() {
+      whenStylesReady().then(markReady);
+      setTimeout(markReady, FALLBACK_MS);
+    }
+
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", start);
+    } else {
+      start();
+    }
+  })();
+</script>`;
+}
+
+export function resolvePageReadyConfig(
+  input: false | PageReadyConfig | undefined,
+): ResolvedPageReadyConfig | false {
+  if (input === false) return false;
+  const opts = input ?? {};
+  return {
+    preloader: normalizePreloaderHtml(opts.preloader ?? DEFAULT_PRELOADER),
+    fallbackMs: opts.fallbackMs ?? 5000,
+    probe: opts.probe === false ? false : (opts.probe ?? "--pp-bg"),
+    stableFrames: opts.stableFrames ?? 4,
+    maxFrames: opts.maxFrames ?? 300,
+  };
+}
+
+/** Render-blocking stylesheet link (ensures CSS applies before #app is revealed). */
+export function renderStylesheetLink(href: string, opts: { crossorigin?: boolean } = {}): string {
+  const safeHref = escapeHtml(href);
+  const cross = opts.crossorigin ? ' crossorigin="anonymous"' : "";
+  return `<link rel="stylesheet" href="${safeHref}"${cross}>`;
+}
+
+export function renderStylesheetLinks(
+  hrefs: string[],
+  opts: { crossorigin?: boolean } = {},
+): string {
+  return hrefs.map((href) => renderStylesheetLink(href, opts)).join("\n    ");
+}
+
+/** @deprecated Use renderStylesheetLink — async CSS caused FOUC when revealing #app. */
+export function renderNonBlockingStylesheetLink(
+  href: string,
+  opts: { crossorigin?: boolean } = {},
+): string {
+  return renderStylesheetLink(href, opts);
+}
+
+export function renderNonBlockingStylesheetLinks(
+  hrefs: string[],
+  opts: { crossorigin?: boolean } = {},
+): string {
+  return renderStylesheetLinks(hrefs, opts);
+}
+
+/** Inject inline preloader shell so first paint shows a spinner until stylesheets are ready. */
+export function injectPageReadyShell(
+  html: string,
+  pageReady: ResolvedPageReadyConfig | false = resolvePageReadyConfig(undefined),
+): string {
+  if (pageReady === false) return html;
+  if (html.includes('id="pp-page-ready"')) return html;
+
+  const bootScript = buildPageReadyBootScript(pageReady);
+
+  let out = html.replace(/<head>/i, `<head>\n    ${PAGE_READY_HEAD}\n`);
+
+  out = out.replace(/<body([^>]*)>/i, `<body$1>\n    ${pageReady.preloader}\n`);
+
+  return out.replace(/<\/body>/i, `    ${bootScript}\n  </body>`);
+}

package/templates/docs/.preactpress/config.ts

@@ -50,6 +50,7 @@ export default defineConfig({
               { text: "Overview", link: "/" },
               { text: "What is PreactPress?", link: "/guide/what-is-preactpress" },
               { text: "Getting started", link: "/guide/getting-started" },
+              { text: "Starter templates", link: "/guide/templates" },
               { text: "First five minutes", link: "/guide/first-five-minutes" },
             ],
           },

package/templates/docs/components/MarketingHero.tsx

@@ -12,6 +12,12 @@ const actions = [
   },
 ];
 
+const workflowLabels = [
+  { text: "Markdown", href: "https://www.markdownguide.org/tools/github-pages/" },
+  { text: "MDX", href: "https://mdxjs.com/" },
+  { text: "Preact", href: "https://preactjs.com/" },
+];
+
 export default function MarketingHero() {
   return (
     <section class="pp-mkt-hero" aria-labelledby="preactpress-hero-title">
@@ -36,9 +42,17 @@ export default function MarketingHero() {
         </div>
       </div>
       <div class="pp-mkt-hero-panel" aria-label="PreactPress workflow">
-        <span class="pp-mkt-panel-label">Markdown</span>
-        <span class="pp-mkt-panel-label">MDX</span>
-        <span class="pp-mkt-panel-label">Preact</span>
+        {workflowLabels.map((label) => (
+          <a
+            class="pp-mkt-panel-label"
+            href={label.href}
+            key={label.text}
+            rel="noopener noreferrer"
+            target="_blank"
+          >
+            {label.text}
+          </a>
+        ))}
         <span class="pp-mkt-panel-arrow" aria-hidden="true">
           <svg
             class="pp-mkt-panel-arrow-icon"

package/templates/docs/components/References.tsx

@@ -12,15 +12,20 @@ const references = [
     description: "Preact + Tailwind components that can be documented and demonstrated with MDX.",
     href: "https://ui.kamod.ch/",
   },
+  {
+    name: "Kamod Icons",
+    description: "A lightweight, tree-shakeable SVG icon library for Preact apps.",
+    href: "https://github.com/kamod-ch/kamod-icons",
+  },
   {
     name: "Kamod Hooks",
     description: "A Preact hooks library with documentation built around the same tooling stack.",
     href: "https://github.com/kamod-ch/kamod-hooks",
   },
   {
-    name: "Hono starter template",
-    description: "A product-and-docs starter shipped with PreactPress.",
-    href: "https://github.com/kamod-ch/preactpress/tree/main/templates/hono",
+    name: "Syncding",
+    description: "Secure file sync and snapshot recovery between your devices and servers.",
+    href: "https://www.syncding.com/",
   },
   {
     name: "More Kamod projects",

package/templates/docs/components/TemplateGallery.tsx

@@ -2,41 +2,98 @@
 import { h } from "preact";
 import CopyableCommand from "./CopyableCommand.tsx";
 
-const templates = [
+type TemplateCard = {
+  id: "docs" | "hono" | "magazine" | "default";
+  name: string;
+  useCase: string;
+  description: string;
+  highlights: string[];
+  command: string;
+  previewSrc: string;
+};
+
+const templates: TemplateCard[] = [
   {
+    id: "docs",
     name: "Documentation",
-    description: "The full reference starter used for this public demo.",
+    useCase: "Reference site",
+    description:
+      "The full reference starter used for this public demo — guides, examples, search, and i18n.",
+    highlights: ["Default docs theme", "Full guide + examples", "English / German locales"],
     command: "pnpm dlx @kamod-ch/preactpress init my-docs --template docs",
+    previewSrc: "/templates/docs.webp",
   },
   {
+    id: "hono",
     name: "Product + Docs",
-    description: "A polished product landing page with a complete documentation area.",
+    useCase: "Product + docs",
+    description:
+      "A polished marketing landing page paired with a focused documentation area and custom theme.",
+    highlights: ["Custom Preact theme", "Product landing + docs", "Built-in i18n demo"],
     command: "pnpm dlx @kamod-ch/preactpress init my-site --template hono",
+    previewSrc: "/templates/hono.webp",
   },
   {
+    id: "magazine",
     name: "Magazine",
-    description: "A custom editorial theme for articles, tags and content-heavy sites.",
+    useCase: "Editorial",
+    description:
+      "A custom editorial theme for articles, tags, and content-heavy sites with teaser grids.",
+    highlights: ["Custom magazine theme", "Article teasers + tags", "Content loader home"],
     command: "pnpm dlx @kamod-ch/preactpress init my-mag --template magazine",
+    previewSrc: "/templates/magazine.webp",
   },
   {
+    id: "default",
     name: "Minimal",
-    description: "A small starter with a home page, an about page and one guide.",
-    command: "pnpm dlx @kamod-ch/preactpress init my-docs",
+    useCase: "Quick start",
+    description:
+      "The smallest starter: a home page, an about page, and one guide — no custom theme.",
+    highlights: ["Default docs theme", "Tiny file tree", "Fastest way to try PreactPress"],
+    command: "pnpm dlx @kamod-ch/preactpress init my-site",
+    previewSrc: "/templates/default.webp",
   },
 ];
 
+function assetUrl(path: string): string {
+  const base = (import.meta.env.BASE_URL || "/").replace(/\/$/, "");
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${normalized}`;
+}
+
 export default function TemplateGallery() {
   return (
     <section class="pp-mkt-section" aria-labelledby="templates-title">
       <div class="pp-mkt-section-heading">
         <p class="pp-mkt-eyebrow">Template gallery</p>
         <h2 id="templates-title">Start with the shape of site you need</h2>
+        <p>
+          <a class="pp-mkt-section-link" href="/guide/templates">
+            Compare all templates →
+          </a>
+        </p>
       </div>
       <div class="pp-mkt-card-grid pp-mkt-card-grid-four">
         {templates.map((template) => (
-          <article class="pp-mkt-card pp-mkt-template" key={template.name}>
-            <h3>{template.name}</h3>
-            <p>{template.description}</p>
+          <article class="pp-mkt-card pp-mkt-template" key={template.id}>
+            <img
+              class="pp-mkt-template-preview"
+              src={assetUrl(template.previewSrc)}
+              alt={`${template.name} starter preview`}
+              loading="lazy"
+              width={640}
+              height={400}
+            />
+            <div class="pp-mkt-template-body">
+              <p class="pp-mkt-template-tag">{template.useCase}</p>
+              <h3>{template.name}</h3>
+              <p>{template.description}</p>
+              <ul class="pp-mkt-template-highlights">
+                {template.highlights.map((item) => (
+                  <li key={item}>{item}</li>
+                ))}
+              </ul>
+            </div>
             <CopyableCommand command={template.command} />
           </article>
         ))}

package/templates/docs/components/marketing.css

@@ -162,6 +162,26 @@
   font-weight: 800;
 }
 
+a.pp-mkt-panel-label {
+  color: inherit;
+  text-decoration: none;
+  transition:
+    border-color 160ms ease,
+    color 160ms ease,
+    transform 160ms ease;
+}
+
+a.pp-mkt-panel-label:hover {
+  border-color: var(--pp-accent);
+  color: var(--pp-accent);
+  transform: translateY(-1px);
+}
+
+a.pp-mkt-panel-label:focus-visible {
+  outline: 3px solid var(--pp-focus);
+  outline-offset: 3px;
+}
+
 .pp-mkt-panel-plus,
 .pp-mkt-panel-arrow {
   color: var(--pp-accent);
@@ -658,6 +678,11 @@
   font-size: 1.04rem;
 }
 
+.pp-mkt-section-link {
+  color: var(--pp-accent);
+  font-weight: 650;
+}
+
 .pp-mkt-demo-grid {
   display: grid;
   grid-template-columns: minmax(0, 1fr) minmax(260px, 0.8fr);
@@ -778,10 +803,75 @@ a.pp-mkt-card:focus-visible {
   letter-spacing: 0.08em;
 }
 
+.pp-mkt-section-link {
+  color: var(--pp-accent);
+  font-weight: 650;
+}
+
 .pp-mkt-template {
   display: grid;
-  align-content: space-between;
-  min-height: 250px;
+  grid-template-rows: auto 1fr auto;
+  align-content: stretch;
+  gap: 0;
+  min-height: 0;
+  padding: 0;
+  overflow: hidden;
+}
+
+.pp-mkt-template-preview {
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 10;
+  object-fit: cover;
+  object-position: top center;
+  background: color-mix(in srgb, var(--pp-code-bg) 70%, var(--pp-bg));
+  border-bottom: 1px solid var(--pp-border);
+}
+
+.pp-mkt-template-body {
+  padding: 18px 22px 0;
+}
+
+.pp-mkt-template-tag {
+  margin: 0 0 8px;
+  color: var(--pp-accent);
+  font-size: 0.78rem;
+  font-weight: 800;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+.pp-mkt-template-highlights {
+  margin: 14px 0 0;
+  padding: 0;
+  list-style: none;
+  color: var(--pp-muted);
+  font-size: 0.9rem;
+  line-height: 1.45;
+}
+
+.pp-mkt-template-highlights li {
+  position: relative;
+  padding-left: 1rem;
+}
+
+.pp-mkt-template-highlights li + li {
+  margin-top: 6px;
+}
+
+.pp-mkt-template-highlights li::before {
+  content: "";
+  position: absolute;
+  top: 0.55em;
+  left: 0;
+  width: 0.35rem;
+  height: 0.35rem;
+  border-radius: 999px;
+  background: var(--pp-accent);
+}
+
+.pp-mkt-template .pp-mkt-copyable {
+  margin: 16px 22px 22px;
 }
 
 .pp-mkt-copyable {

package/templates/docs/guide/advanced.md

@@ -21,6 +21,7 @@ export default defineConfig(async () => ({
 - `transformHead(ctx)` returns additional head tags.
 - `transformPageData(page, ctx)` changes page data before rendering.
 - `transformHtml(html, ctx)` changes the final HTML document.
+- `pageReady` customizes or disables the built-in loading overlay (see [Configuration](/guide/configuration#page-ready-preloader)).
 - `buildEnd(ctx)` runs after production output is complete.
 
 Hooks may be asynchronous. Keep output deterministic so incremental builds and CI remain reproducible.

package/templates/docs/guide/commands.md

@@ -16,6 +16,8 @@ Run commands from the site root or pass a root path as the final argument.
 | `preactpress build [root]`                   | Emit static production files                        |
 | `preactpress preview [root]`                 | Serve `outDir` locally                              |
 
+See [Starter templates](/guide/templates) for a comparison of the four official init starters.
+
 ## Recommended workflow
 
 ```bash

package/templates/docs/guide/configuration.md

@@ -34,6 +34,29 @@ export default defineConfig({
 | `head`            | Global meta, link, and script tuples                               |
 | `vite`            | User Vite configuration merged into the internal config            |
 | `build`           | Sitemap, robots, and feed output                                   |
+| `pageReady`       | Built-in loading overlay while CSS becomes ready; `false` disables |
+
+## Page-ready preloader
+
+PreactPress injects a small inline preloader into every HTML document so the first paint does not flash unstyled content. Customize or disable it in config instead of editing HTML with `transformHtml`.
+
+```ts
+export default defineConfig({
+  // Disable the built-in preloader entirely
+  pageReady: false,
+
+  // Or customize the overlay
+  pageReady: {
+    preloader: '<img src="/brand-mark.svg" alt="" width="48" height="48" />',
+    fallbackMs: 3000,
+    probe: "--pp-bg", // CSS variable that must be set before reveal
+  },
+});
+```
+
+`preloader` accepts either a full element with `id="pp-preloader"` or inner HTML only (wrapped automatically). The built-in spinner follows the default theme: it reacts to `data-theme`, the `dark` class, and `prefers-color-scheme`. Custom markup needs its own light/dark styles unless you reuse the `pp-preloader-spinner` class.
+
+`probe: false` skips the CSS-variable check and waits for stylesheet links only.
 
 ## Site metadata
 

package/templates/docs/guide/getting-started.md

@@ -44,6 +44,8 @@ Open **http://localhost:5173** to see the starter site.
 > **Note**
 > `preactpress init` copies the built-in starter template and writes `@kamod-ch/preactpress` to `devDependencies`. You do not need to install PreactPress separately before running the initializer.
 
+Not sure which starter to use? Compare the four official options on [Starter templates](/guide/templates).
+
 ## File structure
 
 After initialization, the project looks like this:

package/templates/docs/guide/templates.md

@@ -0,0 +1,57 @@
+---
+title: Starter templates
+description: Compare the built-in PreactPress init templates and choose the right starting shape.
+---
+
+# Starter templates
+
+PreactPress ships four official starters. Use `preactpress init` (or `pnpm dlx @kamod-ch/preactpress init`) and optionally `--template <name>` to scaffold one.
+
+See the [template gallery on the home page](/#templates-title) for screenshots and copyable commands.
+
+## Which template should I use?
+
+| Template       | CLI name                      | Theme                  | Best for                                 | Notable extras                                  |
+| -------------- | ----------------------------- | ---------------------- | ---------------------------------------- | ----------------------------------------------- |
+| Documentation  | `docs`                        | Default docs theme     | Full product or library docs (this site) | Guides, examples, search, EN/DE locales         |
+| Product + Docs | `hono`                        | Custom Preact theme    | Product marketing page plus a docs area  | Landing layout, focused guide subset, i18n demo |
+| Magazine       | `magazine`                    | Custom editorial theme | Articles, tags, content-heavy sites      | Teaser grid, tag pages, content loader          |
+| Minimal        | `default` (omit `--template`) | Default docs theme     | Trying PreactPress quickly               | Smallest file tree                              |
+
+## Scaffold commands
+
+```bash
+# Documentation (canonical reference starter)
+pnpm dlx @kamod-ch/preactpress init my-docs --template docs
+
+# Product landing + docs
+pnpm dlx @kamod-ch/preactpress init my-site --template hono
+
+# Editorial / magazine
+pnpm dlx @kamod-ch/preactpress init my-mag --template magazine
+
+# Minimal (default)
+pnpm dlx @kamod-ch/preactpress init my-site
+```
+
+After scaffolding:
+
+```bash
+cd my-site
+pnpm install
+pnpm run dev
+```
+
+## How they differ
+
+- **Documentation** is the largest starter and the public demo. Prefer it when you want the full guide surface, examples, and default theme features out of the box.
+- **Product + Docs** shows how far a custom theme can go for a marketing site while keeping a documentation section. Use it as a theme reference more than as the canonical API docs source.
+- **Magazine** focuses on editorial patterns: article teasers, tags, and a content-loader driven home page.
+- **Minimal** is the default `init` target. Start here if you want the fewest files and will grow the site yourself.
+
+## Related
+
+- [Getting started](/guide/getting-started)
+- [CLI and validation](/guide/commands)
+- [Custom themes](/guide/custom-themes)
+- [Custom theme example](/examples/custom-theme)

package/templates/docs/public/templates/.gitkeep

@@ -0,0 +1 @@
+# Generated by scripts/capture-template-previews.mjs