create-spark-html-app 0.11.1 → 0.13.0

package/template-prerender/README.md

@@ -1,13 +1,76 @@
-# ⚡ Spark Static App
+# ⚡ Spark App
 
-A prerendered static site built with
-[spark-html](https://github.com/wilkinnovo/spark-html) + `spark-prerender`.
-Components stay single-file HTML; the build writes fully-rendered pages into
-`dist/` (plus sitemap/robots hooks) and the browser hydrates over them.
+A starter built with [spark-html](https://github.com/wilkinnovo/spark-html) — single-file
+HTML components with built-in reactivity. No compiler, no virtual DOM, no build step.
+
+The scaffold is a **multi-page SPA** with client-side routing, live demos, and a
+shared design system — edit any component and save to see it update instantly.
+Depending on the options you picked at scaffold time it also wires up
+`spark-html-theme` (dark/light), `spark-html-image` (build-time webp/avif),
+`spark-html-sri` (integrity checks), and `spark-html-manifest` (PWA manifest +
+icons + offline app shell). `spark-html-head`, `spark-html-persist`,
+`spark-prerender`, and `spark-html-devtools` are always included.
+
+## Develop
 
 ```bash
 bun install
-bun run dev       # dev server with HMR
-bun run build     # prerendered static output → dist/, deploy anywhere
-bun run preview   # preview the production build
+bun run dev          # dev server with HMR
 ```
+
+In dev mode, `spark-html-devtools` adds a debugging overlay — inspect
+component state, stores, and the mounted tree live.
+
+## Build (SEO-ready)
+
+```bash
+bun run build     # static output → dist/, serve anywhere
+bun run preview   # preview the production build locally
+```
+
+`bun run build` is **SEO-friendly out of the box**: the `spark-prerender`
+pipeline step runs your app at build time and writes fully-rendered HTML into
+`dist/` — so crawlers and AI tools read real content (headings, text, links),
+not empty placeholders. The browser still hydrates over it for full
+interactivity.
+
+Per-route `<title>` and `<meta>` tags are set reactively via
+`spark-html-head` in `src/main.js` — no per-component boilerplate.
+
+Don't need SEO? Remove the `prerender(...)` step from `spark.config.js`.
+
+## Architecture
+
+Client routing is set up in `src/main.js` — `router()` (from
+`spark-html-router`) replaces `mount()` and discovers your routes from
+`<template route>` blocks in `index.html`. Per-route `<title>` and `<meta>`
+are handled by `head()` (from `spark-html-head`), and `spark-html-devtools`
+provides a live debugging overlay in dev mode.
+
+Each route is just an HTML file in `public/components/`.
+
+## What's inside
+
+The scaffold's components in `public/components/` each demonstrate a Spark feature
+(all using only the published runtime — no experimental APIs):
+
+| Component | Features shown |
+|---|---|
+| `nav.html` | Client routing (active link highlight via `aria-current="page"`), theme toggle via `useStore('theme')` |
+| `hero.html` | Local state, `$:` reactive declarations, shared store (`useStore('app')`) |
+| `home.html` | Page composition — imports `hero` + demo components for the `/` route |
+| `about.html` | Page composition — uses `feature-card` with props and slots for the `/about` route |
+| `demo-todo.html` | `bind:value`/`bind:checked`, `<template each>` with `key`, `$:` derived counts |
+| `demo-props.html` | `export let` props, named `<slot>`, component composition |
+| `demo-await.html` | `<template await>` with `once()`, `onMount`, loading/then/catch states |
+| `feature-card.html` | Reusable card via `export let` + `<slot>`, used by `about` and `demo-props` |
+| `footer.html` | Static content component, imported by the shell |
+
+A component is a `.html` file with optional `<script>` and `<style>`. Top-level
+variables are reactive state — assigning to one re-patches that component's DOM.
+Derive values with `$:`, share state across components with `useStore(name)`, use
+`bind:value` for two-way binds, and pass props as attributes on the `import`
+placeholder.
+
+See the [full docs](https://wilkinnovo.github.io/spark-html/docs) for the complete
+template syntax reference.

package/template-prerender/_gitignore

@@ -1,2 +1,4 @@
 node_modules
 dist
+*.local
+.DS_Store

package/template-prerender/index.html

@@ -1,13 +1,214 @@
 <!doctype html>
 <html lang="en">
   <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Spark Static App</title>
-    <link rel="stylesheet" href="/src/style.css" />
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Spark App</title>
+    <meta name="description" content="A reactive app built with Spark — single-file HTML components, no compiler, no virtual DOM." />
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⚡</text></svg>" />
+    <!-- Fonts are injected by spark-html-font/bun (see spark.config.js):
+         preconnects, the stylesheet, and a size-adjusted fallback face so the
+         swap never moves the page. -->
+    <style>
+      /* Design system — the same palette and monospace type as the Spark
+               website. Tokens + base + a shared card/button/input system live here in
+               <head> so they apply globally before any component boots. Light & dark
+               are driven by [data-theme] (spark-html-theme writes it). */
+      *,
+      *::before,
+      *::after {
+        box-sizing: border-box;
+        margin: 0;
+        padding: 0;
+      }
+      :root {
+        --bg: #000;
+        --surface: #0a0a0a;
+        --surface-2: #101014;
+        --border: #1a1a1a;
+        --border-strong: #333;
+        --text: #fff;
+        --muted: #888;
+        --muted-dim: #555;
+        --spark: #ffd24a;
+        --spark-ink: #ffd24a;
+        --danger: #ff6b6b;
+        --radius: 12px;
+        /* the injected --font-jetbrains-mono stack includes the fallback face;
+           the var() fallback list covers a config without the font step */
+        --font: var(--font-jetbrains-mono, "JetBrains Mono", ui-monospace, monospace);
+      }
+      [data-theme="light"] {
+        --bg: #fff;
+        --surface: #fafafa;
+        --surface-2: #f4f4f5;
+        --border: #ededed;
+        --border-strong: #d4d4d4;
+        --text: #1a1a1a;
+        --muted: #666;
+        --muted-dim: #999;
+        --spark: #ffd24a;
+        --spark-ink: #9a6a00;
+        --danger: #d63b3b;
+      }
+      html {
+        scroll-behavior: smooth;
+      }
+      body {
+        font-family: var(--font);
+        background: var(--bg);
+        color: var(--text);
+        line-height: 1.6;
+        -webkit-font-smoothing: antialiased;
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+      }
+      ::selection {
+        background: var(--spark);
+        color: #000;
+      }
+      [data-theme="light"] ::selection {
+        background: #ffe9a8;
+        color: #111;
+      }
+      a {
+        color: var(--spark-ink);
+        text-decoration: none;
+      }
+      [hidden] {
+        display: none !important;
+      }
+      .routes {
+        flex: 1;
+        width: 100%;
+        max-width: 960px;
+        margin: 0 auto;
+        padding: 0 24px;
+      }
+
+      /* Shared component system — components lean on these instead of each
+               redefining a card/button/input. */
+      .card {
+        background: var(--surface);
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        padding: 22px;
+      }
+      .card h2 {
+        font-size: 16px;
+        font-weight: 700;
+        margin-bottom: 4px;
+        letter-spacing: -0.01em;
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        flex-wrap: wrap;
+      }
+      .tag {
+        font-size: 10px;
+        font-weight: 500;
+        color: var(--spark-ink);
+        border: 1px solid var(--border-strong);
+        padding: 1px 7px;
+        border-radius: 999px;
+      }
+      .hint {
+        font-size: 12.5px;
+        color: var(--muted);
+        margin-bottom: 16px;
+        line-height: 1.5;
+      }
+      code {
+        background: var(--surface-2);
+        color: var(--spark-ink);
+        padding: 1px 6px;
+        border-radius: 4px;
+        font-size: 12px;
+      }
+      .row {
+        display: flex;
+        gap: 8px;
+        align-items: center;
+        flex-wrap: wrap;
+      }
+
+      button,
+      .btn {
+        font-family: inherit;
+        font-size: 13px;
+        cursor: pointer;
+        padding: 8px 15px;
+        border-radius: 8px;
+        border: 1px solid var(--border-strong);
+        background: var(--surface-2);
+        color: var(--text);
+        transition:
+          border-color 0.12s,
+          background 0.12s,
+          color 0.12s,
+          transform 0.08s;
+      }
+      button:hover:not(:disabled) {
+        border-color: var(--spark);
+        color: var(--spark-ink);
+      }
+      button:active:not(:disabled) {
+        transform: scale(0.97);
+      }
+      button:disabled {
+        opacity: 0.4;
+        cursor: not-allowed;
+      }
+      button.primary {
+        background: var(--spark);
+        color: #000;
+        border-color: var(--spark);
+        font-weight: 700;
+      }
+      button.primary:hover:not(:disabled) {
+        color: #000;
+        filter: brightness(1.06);
+      }
+
+      label {
+        display: flex;
+        flex-direction: column;
+        gap: 4px;
+        font-size: 12px;
+        color: var(--muted);
+      }
+      input,
+      textarea {
+        font-family: inherit;
+        font-size: 14px;
+        width: 100%;
+        background: var(--bg);
+        color: var(--text);
+        border: 1px solid var(--border-strong);
+        border-radius: 8px;
+        padding: 9px 12px;
+      }
+      input:focus,
+      textarea:focus {
+        outline: none;
+        border-color: var(--spark);
+      }
+    </style>
   </head>
   <body>
-    <div import="components/hero"></div>
+    <div import="components/nav"></div>
+    <main class="routes">
+      <!-- @spark:router -->
+      <template route="/"><div import="components/home"></div></template>
+      <template route="/about"><div import="components/about"></div></template>
+      <!-- @spark:end -->
+      <!-- @spark:!router -->
+      <div import="components/home"></div>
+      <!-- @spark:end -->
+    </main>
+    <div import="components/footer"></div>
+
     <script type="module" src="/src/main.js"></script>
   </body>
 </html>

package/template-prerender/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "spark-static-app",
+  "name": "spark-app",
   "private": true,
   "version": "0.0.0",
   "type": "module",
@@ -9,10 +9,19 @@
     "preview": "spark preview"
   },
   "dependencies": {
-    "spark-html": "latest"
+    "spark-html": "latest",
+    "spark-html-router": "latest",
+    "spark-html-theme": "latest",
+    "spark-html-head": "latest",
+    "spark-html-persist": "latest",
+    "spark-html-sri": "latest",
+    "spark-html-manifest": "latest"
   },
   "devDependencies": {
     "spark-html-bun": "latest",
-    "spark-prerender": "latest"
+    "spark-prerender": "latest",
+    "spark-html-devtools": "latest",
+    "spark-html-image": "latest",
+    "spark-html-font": "latest"
   }
 }

package/template-prerender/public/components/hero.html

@@ -1,14 +1,75 @@
-<main>
-  <h1>⚡ {greeting}</h1>
-  <p>This page is prerendered at build time — view-source on the deployed
-  site and the content is right there. Edit this component and save.</p>
-  <button onclick={cheer}>Clicked {count} times</button>
-</main>
+<header class="hero">
+  <span class="bolt" :class="igniting ? 'bolt lit' : 'bolt'" onclick="{ignite}" title="Strike the bolt">⚡</span>
+
+  <h1>HTML that <span class="grad">reacts</span>.</h1>
+  <p class="tagline">
+    Single-file reactive components — no compiler, no virtual DOM, no build step.
+    Everything below is live the moment the page loads.
+  </p>
+
+  <div class="counter">
+    <button class="round" onclick="{count = Math.max(0, count - 1)}" :disabled="count <= 0" aria-label="decrement">–</button>
+    <div class="readout">
+      <span class="num">{count}</span>
+      <span class="sub">doubled is {doubled} · {capitalize(mood)}</span>
+    </div>
+    <button class="round plus" onclick="{count++}" aria-label="increment">+</button>
+  </div>
+
+  <p class="store-line">
+    You've struck the bolt <strong>{app.sparks}</strong>
+    {pluralize(app.sparks, 'time')} — that lives in a shared store.
+  </p>
+</header>
 
 <script>
-  let greeting = 'HTML that reacts';
+  import { capitalize, pluralize } from '../lib/format.js';
+
   let count = 0;
-  let pageTitle = 'Spark Static App';
-  let pageDescription = 'A prerendered spark-html starter — SEO-ready static HTML that hydrates into a reactive app.';
-  function cheer() { count++; }
+  let igniting = false;
+
+  $: doubled = count * 2;
+  $: mood = count === 0 ? 'a calm start' : count < 5 ? 'warming up' : 'on fire';
+
+  const app = useStore('app');
+
+  function ignite() {
+    app.sparks++;
+    igniting = true;
+    setTimeout(() => { igniting = false; }, 450);
+  }
 </script>
+
+<style>
+  .hero { display: flex; flex-direction: column; align-items: center; text-align: center; gap: 16px; padding-top: 32px; }
+  .bolt {
+    font-size: 32px; line-height: 1; cursor: pointer; user-select: none;
+    filter: drop-shadow(0 0 14px rgba(255, 210, 74, .45));
+    transition: transform .2s ease, filter .2s ease;
+  }
+  .bolt:hover { transform: translateY(-1px) scale(1.06); }
+  .bolt.lit { animation: zap .45s ease; }
+  @keyframes zap {
+    0%   { transform: scale(1); filter: drop-shadow(0 0 14px rgba(255, 210, 74, .45)); }
+    40%  { transform: scale(1.35) rotate(-8deg); filter: drop-shadow(0 0 34px rgba(255, 210, 74, .95)); }
+    100% { transform: scale(1); filter: drop-shadow(0 0 14px rgba(255, 210, 74, .45)); }
+  }
+
+  h1 { font-size: clamp(32px, 6vw, 48px); font-weight: 800; letter-spacing: -.03em; }
+  .grad {
+    background: linear-gradient(110deg, var(--text), var(--spark));
+    -webkit-background-clip: text; background-clip: text; color: transparent;
+  }
+  .tagline { max-width: 480px; color: var(--muted); font-size: 14px; }
+
+  .counter { display: flex; align-items: center; justify-content: center; gap: 22px; margin-top: 8px; }
+  .round {
+    width: 44px; height: 44px; border-radius: 50%; font-size: 22px; padding: 0;
+  }
+  .round.plus { background: var(--surface-2); }
+  .readout { min-width: 130px; }
+  .num { display: block; font-size: 42px; font-weight: 800; font-variant-numeric: tabular-nums; line-height: 1.1; }
+  .sub { font-size: 11px; color: var(--muted); }
+  .store-line { font-size: 13px; color: var(--muted); margin-top: 4px; }
+  .store-line strong { color: var(--spark-ink); }
+</style>

package/template-prerender/spark.config.js

@@ -1,9 +1,72 @@
 import prerender from 'spark-prerender/bun';
+// @spark:theme
+import theme from 'spark-html-theme/bun';
+// @spark:end
+// @spark:font
+import font from 'spark-html-font/bun';
+// @spark:end
+// @spark:image
+import image from 'spark-html-image/bun';
+// @spark:end
+// @spark:pwa
+import manifest from 'spark-html-manifest/bun';
+// @spark:end
+// @spark:sri
+import sri from 'spark-html-sri/bun';
+// @spark:end
 
-// Static site, the Spark way: `spark dev` serves components raw with HMR;
-// `spark build` copies public/, bundles the entry, then prerender() runs the
-// REAL app at build time and writes fully-rendered HTML into dist/ — crawlers
-// and AI tools read real content, the browser hydrates over it.
+// Spark needs no build step — spark-html-bun is just a fast dev server and a
+// bundler for your app shell. `spark dev` serves component fragments raw and
+// hot-reloads only the edited component; components live in public/ so they
+// ship verbatim to the production build too.
+//
+// The `pipeline` runs in order after `spark build` copies public/ and bundles
+// the entry. Order matters: prerender() first (it writes one HTML file per
+// route), then the steps that rewrite those pages — sri() must be last so it
+// hashes the final bytes.
+//
+// `prerender()` makes `bun run build` SEO-friendly: it runs your app at build
+// time and writes fully-rendered HTML into dist/ (crawlers and AI tools read
+// real content; the browser still hydrates over it), plus sitemap.xml +
+// robots.txt. Remove it if you don't need SEO.
 export default {
-  pipeline: [prerender({ pages: ['index.html'] })],
+  pipeline: [
+    prerender({ pages: ['index.html'] }),
+    // @spark:theme
+    // Bakes the tiny no-flash script into each page (dev too) so the saved /
+    // OS theme is on <html> before first paint — no wrong-theme flash on load.
+    theme(),
+    // @spark:end
+    // @spark:font
+    // Preconnect + the Google stylesheet + a size-adjusted local fallback
+    // face, baked into each page (dev too) — the font swap never moves or
+    // visibly reflows the page.
+    font({
+      fallback: ['ui-monospace', 'monospace'],
+      fonts: [{ family: 'JetBrains Mono', google: true, weights: [300, 400, 500, 600, 700, 800] }],
+    }),
+    // @spark:end
+    // @spark:image
+    // Every <img> in pages and components: converted to webp/avif at multiple
+    // widths, srcset + width/height added (no layout shift), loading="lazy".
+    // Zero config.
+    image(),
+    // @spark:end
+    // @spark:pwa
+    // One config → manifest.webmanifest + resized icons + <head> tags + an
+    // offline app-shell service worker (registered automatically).
+    manifest({
+      name: 'Spark App',
+      themeColor: '#ffd24a',
+      icon: 'public/icon.png',
+      offline: true,
+    }),
+    // @spark:end
+    // @spark:sri
+    // Hashes every built asset + component, stamps integrity/crossorigin onto
+    // script/link tags, and bakes the verify manifest into each page. Keep it
+    // LAST so it sees the final pages.
+    sri(),
+    // @spark:end
+  ],
 };

package/template-prerender/src/main.js

@@ -1,2 +1,61 @@
-import { mount } from 'spark-html';
-mount();
+import { store } from "spark-html";
+// @spark:!router
+import { mount } from "spark-html";
+// @spark:end
+// @spark:router
+import { router } from "spark-html-router";
+// @spark:end
+// @spark:theme
+import { theme } from "spark-html-theme";
+// @spark:end
+import { head } from "spark-html-head";
+import { persist } from "spark-html-persist";
+// @spark:sri
+import { sri } from "spark-html-sri";
+// @spark:end
+import { devtools } from "spark-html-devtools";
+
+const dev = import.meta.env?.DEV;
+if (dev) devtools(); // dev only
+
+// @spark:sri
+// Subresource Integrity: verifies every component fetch against the
+// manifest the build baked into the page, and allow-lists remote URL
+// imports (TOFU). Fails open on localhost, enforces in production.
+sri();
+// @spark:end
+
+head({
+  title: { "/": "Home", "/about": "About", "*": "Not found" },
+  titleTemplate: (t) => `${t} · My Site`,
+  meta: { description: (path) => `The ${path} page` },
+});
+
+// Shared stores connect components without providers or prop drilling.
+store("app", { sparks: 0 });
+
+// A store that survives reloads — hydrates from localStorage on boot,
+// saves on every change (see components/demo-persist.html).
+persist("prefs", { name: "", visits: 0 });
+
+// @spark:theme
+// One-line dark/light/system theming (the ⚡ logo toggles it).
+theme();
+// @spark:end
+
+// @spark:pwa
+// PWA: manifest.webmanifest, icons, and the offline app-shell worker are
+// generated by spark-html-manifest/bun (see spark.config.js) — the worker
+// registration is injected into every built page automatically.
+// Want offline-capable CDN component imports too? See spark-html-offline
+// (a page registers one worker per scope, so pick the one you need).
+// @spark:end
+
+// @spark:router
+// Client-side router: reads <template route> blocks, intercepts <a> clicks,
+// and manages SPA navigation. Call it once — replaces mount().
+router({ devOverlay: dev, quiet: !dev });
+// @spark:end
+// @spark:!router
+mount(document.body);
+// @spark:end