@webstir-io/webstir 0.1.0

package/assets/templates/ssg/src/frontend/content/content-pipeline.md

@@ -0,0 +1,82 @@
+# Content pipeline
+
+This starter supports Markdown docs out of the box.
+
+If you add files under `src/frontend/content/**/*.md`, Webstir will:
+
+- Convert Markdown to HTML at build time
+- Wrap it in your shared layout (`src/frontend/app/app.html`)
+- Write real pages under `/docs/.../`
+
+The starter includes a docs hub at `/docs/` with basic navigation.
+
+## Add a doc
+
+Create a file like:
+
+- `src/frontend/content/my-doc.md`
+
+It becomes:
+
+- `/docs/my-doc/`
+
+## Where the output goes
+
+For example, this file:
+
+- `src/frontend/content/content-pipeline.md`
+
+builds to:
+
+- `/docs/content-pipeline/`
+
+## Routing rules (simple)
+
+- In a folder, `index.md` becomes the folder root (e.g. `src/frontend/content/guides/index.md` → `/docs/guides/`)
+- In a folder, `readme.md` also becomes the folder root (e.g. `src/frontend/content/guides/readme.md` → `/docs/guides/`)
+- Otherwise, the file name becomes a segment (e.g. `content-pipeline.md` → `/docs/content-pipeline/`)
+
+## Frontmatter (optional)
+
+You can set a title/description at the top of a Markdown file:
+
+```md
+---
+title: My doc
+description: A short summary for the docs index.
+order: 10
+---
+```
+
+## Manifests
+
+Webstir also emits helper manifests for docs navigation:
+
+- `/docs-nav.json`
+ 
+It’s written alongside your built frontend output:
+
+- `build/frontend/docs-nav.json` while watching
+- `dist/frontend/docs-nav.json` for publish output
+
+## Search (optional)
+
+Enable site-wide search:
+
+- `webstir enable search`
+
+When enabled, Webstir generates search data and adds the search UI assets to your app:
+
+- `/search.json` (used by the search feature module)
+- `src/frontend/app/scripts/features/search.ts` (search behavior, added to your source tree and imported by `src/frontend/app/app.ts`)
+- `src/frontend/app/styles/features/search.css` (search UI styling, added to your source tree)
+
+## Development vs publish
+
+- `webstir watch` builds to `build/frontend/` for a fast dev loop.
+- `webstir publish` writes `dist/frontend/` for static hosting.
+
+## Clean URLs on static hosts
+
+If you deploy `dist/frontend/` with folder-style URLs (like `/docs/content-pipeline/`), configure your host to serve
+`index.html` for directory paths.

package/assets/templates/ssg/src/frontend/content/css-playbook.md

@@ -0,0 +1,68 @@
+# CSS Playbook
+
+This starter uses a small, convention-first CSS system. The goal is to keep styling predictable and reduce "naming entropy" (lots of one-off classes and tokens).
+
+## Principles
+
+- Tokens-first: use CSS custom properties instead of ad-hoc `#hex`/`px` values.
+- Tiny surface area: prefer a few layout building blocks + a few components over "utility everything".
+- Deterministic cascade: use cascade layers so "where do I put this?" is obvious.
+- Accessible defaults: focus rings, readable type, and sensible spacing are part of the system.
+
+## The Contract (v0)
+
+### Layout (classes)
+
+Use a small fixed set of layout building blocks:
+
+- `.ws-container` - centered max-width container
+- `.ws-stack` - vertical layout with gap
+- `.ws-cluster` - inline row with wrap + gap
+- `.ws-grid` - responsive grid
+- `.ws-sidebar` - content + sidebar layout
+
+Tune layout building blocks with CSS variables instead of creating more classes:
+
+```html
+<div class="ws-stack" style="--ws-gap: var(--ws-space-4)">
+  ...
+</div>
+```
+
+### Components (`data-ui`)
+
+Target components by `data-ui` and use a small set of variant attributes:
+
+- `data-ui="btn"` (and other component ids)
+- `data-variant="solid|ghost|outline|soft"`
+- `data-size="sm|md|lg"`
+- `data-tone="neutral|accent|danger|success|warning"`
+
+Example:
+
+```html
+<a data-ui="btn" data-variant="solid" data-tone="accent" href="/about">About</a>
+```
+
+Prefer `aria-*` and native attributes for state:
+
+- `aria-current="page"`, `aria-expanded="true|false"`, `disabled`, etc.
+
+### Tokens
+
+Define and customize design values via CSS variables (custom properties).
+
+Common token categories:
+
+- Color: `--ws-bg`, `--ws-fg`, `--ws-muted`, `--ws-border`, `--ws-accent`
+- Space: `--ws-space-1..8`
+- Radius: `--ws-radius-1..3`
+- Type: `--ws-font-sans`, `--ws-font-mono`
+
+### Scoping
+
+Docs-only rules should be scoped under a stable attribute:
+
+- `[data-scope="docs"] { ... }`
+
+This keeps "docs chrome" styles from leaking into app pages.

package/assets/templates/ssg/src/frontend/content/hosting.md

@@ -0,0 +1,48 @@
+---
+title: Deploying your site
+description: Clean URLs, sitemap, and static hosting notes for Webstir SSG.
+order: 2
+---
+
+# Deploying your site
+
+Webstir SSG outputs plain HTML files that can be hosted on any static host (S3, Netlify, Cloudflare Pages, etc.).
+
+## Clean URLs (recommended)
+
+The publish output is directory-based:
+
+- `/about/` → `about/index.html`
+- `/docs/content-pipeline/` → `docs/content-pipeline/index.html`
+
+Your host should serve `index.html` automatically when a URL points at a directory.
+
+If you want `/about` (no trailing slash) to work too, configure your host to treat it like a directory request.
+
+Example (nginx):
+
+```nginx
+location / {
+  try_files $uri $uri/ $uri/index.html =404;
+}
+```
+
+## Sitemap
+
+Webstir writes `sitemap.xml` during SSG publish. For absolute `<loc>` entries, set:
+
+- `WEBSTIR_SITE_URL=https://your-domain.com`
+
+Or add to `package.json`:
+
+```json
+{
+  "webstir": {
+    "siteUrl": "https://your-domain.com"
+  }
+}
+```
+
+## Broken link checks
+
+During SSG publish, Webstir validates internal links and `#hash` anchors across the generated HTML pages and fails with actionable errors if anything is broken.

package/assets/templates/ssg/src/frontend/pages/about/index.css

@@ -0,0 +1,33 @@
+@layer overrides {
+.page {
+  padding: 48px 0 96px;
+  --ws-container: 100%;
+}
+
+.page .ws-stack {
+  --ws-gap: 32px;
+}
+
+.page-header {
+  max-width: none;
+}
+
+.lead {
+  color: var(--ws-muted);
+  font-size: 1.1rem;
+  margin: 0;
+}
+
+ul {
+  margin: 0;
+  padding-left: 20px;
+}
+
+li {
+  margin: 10px 0;
+}
+
+.bullets {
+  max-width: none;
+}
+}

package/assets/templates/ssg/src/frontend/pages/about/index.html

@@ -0,0 +1,60 @@
+<head>
+  <title>About</title>
+  <link rel="stylesheet" href="index.css" />
+</head>
+<body>
+  <main>
+    <section class="page">
+      <div class="ws-container">
+        <div class="ws-stack">
+          <header class="page-header">
+            <h1>About</h1>
+            <p class="lead">
+              This starter uses static site generation (SSG): your pages become fast, standalone HTML you can deploy anywhere.
+            </p>
+          </header>
+
+          <section>
+            <h2>What is SSG?</h2>
+            <p>
+              With SSG, your site is rendered at build time. Visitors get a real HTML page (great for performance and SEO),
+              and you can still add JavaScript later when you need interactivity.
+            </p>
+          </section>
+
+          <section>
+            <h2>How Webstir helps</h2>
+            <ul class="bullets">
+              <li>Keep pages simple: plain HTML and CSS per page.</li>
+              <li>Share a layout: common markup lives in <code>src/frontend/app/app.html</code>.</li>
+              <li>Ship production output with <code>webstir publish</code>.</li>
+            </ul>
+          </section>
+
+          <section>
+            <h2>Dev experience</h2>
+            <p>
+              Run <code>webstir watch</code> while you edit for fast refresh and hot reload, so you can iterate without a full rebuild.
+            </p>
+          </section>
+
+          <section>
+            <h2>Build output</h2>
+            <ul class="bullets">
+              <li>Dev builds go to <code>build/frontend/</code> (used by <code>webstir watch</code>).</li>
+              <li>Publish output goes to <code>dist/frontend/</code> (used by <code>webstir publish</code>).</li>
+            </ul>
+          </section>
+
+          <section>
+            <h2>Deploying</h2>
+            <p>
+              <code>dist/frontend/</code> is a plain static site. If you want clean URLs (like <code>/docs/content-pipeline/</code>),
+              configure your host to serve <code>index.html</code> for directory paths.
+            </p>
+          </section>
+        </div>
+      </div>
+    </section>
+  </main>
+</body>