create-bascik 1.0.0-rc.1

package/assets/SKILL.md

@@ -0,0 +1,2025 @@
+---
+name: bascik
+description: Comprehensive guide for building with Bascik, a file-based web component framework. Use when creating components, writing scoped CSS or JavaScript, configuring props or slots, using the CLI, setting up the build, or debugging Bascik-specific behavior.
+---
+
+# Bascik Developer & Usage Copilot Skill (`SKILL.md`)
+
+This file contains the **complete, centralized documentation and development skill guide** for Bascik. It is designed to provide Copilot and external developers with everything needed to build, compile, maintain, and write components for the Bascik project.
+
+**Note on Code & Script Examples:** Code examples throughout this skill guide demonstrate patterns, capabilities, and API structures. Adapt file paths, script names, tag names, and configuration values to match the specific project requirements rather than copying illustrative names literally.
+
+---
+
+## 1. What Bascik Is & Does
+
+> Bascik is a build tool for HTML components. It scopes and assembles reusable HTML component files into vanilla HTML pages at build time. It adds zero JavaScript to the output. You write HTML, CSS, and JavaScript; Bascik scopes and assembles them.
+
+* **Resolves custom HTML tags** (e.g. `<my-nav></my-nav>`) to their component source HTML at build time.
+* **Scopes CSS class names, element selectors, `@keyframes`, and CSS custom properties** per component so they never collide.
+* **Rewrites DOM selector calls** (`getElementById`, `querySelector`, etc.) in component scripts to match scoped attribute names.
+* **Wraps component scripts in IIFEs** so variables do not leak between components.
+* **Derives instance IDs deterministically** from page path, component name, and ordinal index, ensuring byte-identical builds across repeated runs.
+* **Internal build metadata in `dist/.bascik/`:** Build-internal artifacts (such as `dist/.bascik/manifest.json` when `generate.manifest` is enabled) are stored in dot-prefixed paths within `dist/`. These are never served over HTTP because requests containing dot-segments always return 404.
+* **Outputs a `dist/` directory of plain `.html` files** with zero runtime dependencies and no client-side JS added by Bascik itself.
+
+### What Bascik Does NOT Do
+* It is not a JavaScript framework. There is no virtual DOM, no reactive state, no client-side routing.
+* It does not add any JavaScript to pages. Every script in the output was written by you.
+* It does not require Web Components, Shadow DOM, or any browser-specific API.
+
+### End-to-End Example: Input → Output
+
+One component file, its usage, and the scoped build output:
+
+```html
+<!-- src/components/my-card.html -->
+<style>
+  .card {
+    padding: 26px 28px;
+    border: 1px solid #3a3d40;
+    border-radius: 10px;
+    &.active { border-color: #d3ff8d; }
+  }
+</style>
+<div class="card" id="card">
+  <div data-bascik-slot></div>
+</div>
+<script>
+  const card = document.getElementById('card');
+  card.addEventListener('click', () => {
+    card.classList.toggle('active');
+  });
+</script>
+```
+
+```html
+<!-- src/pages/index.html -->
+<my-card>
+  <h3>My Card</h3>
+  <p>Any HTML goes inside as slot content.</p>
+</my-card>
+```
+
+```html
+<!-- dist/index.html - classes and selectors scoped, script wrapped in IIFE -->
+<style>
+  .bascik__my-card__card {
+    padding: 26px 28px;
+    border: 1px solid #3a3d40;
+    border-radius: 10px;
+    &.bascik__my-card__active { border-color: #d3ff8d; }
+  }
+</style>
+<div class="bascik__my-card__card" id="bascik__my-card__a1b__card">
+  <h3>My Card</h3>
+  <p>Any HTML goes inside as slot content.</p>
+</div>
+<script>
+  (function () {
+    const card = document.getElementById('bascik__my-card__a1b__card');
+    card.addEventListener('click', () => {
+      card.classList.toggle('bascik__my-card__active');
+    });
+  })();
+</script>
+```
+
+Because IDs are scoped per instance, the same component can appear multiple times on one page and each instance's JS stays fully isolated. Plain `getElementById` / `querySelector` calls just work.
+
+
+### How Bascik Compares to Other Tools
+* **Vanilla HTML with Build-Time Components:** Bascik is built for content sites, landing pages, and documentation portals where shipping 80+ KB of React or framework runtime is unnecessary.
+* **Contrast with Svelte:** Svelte compiles to a JavaScript runtime for reactive DOM management. Bascik compiles to plain HTML with zero runtime added.
+* **Complements HTMX and Alpine.js:** Bascik resolves components at build time, while HTMX and Alpine add behavior at runtime. They compose cleanly together.
+* **Contrast with Eleventy / Hugo / Jekyll:** Those tools focus on content pipelines (Markdown collections and template engines). Bascik focuses on HTML page composition and component reuse without a template language.
+
+### Source Vocabulary and Browser Compatibility
+* The custom component tags in a Bascik project are the components the developer creates; Bascik does not provide a framework-owned component catalog.
+* Build instructions such as `data-bascik-slot`, `data-bascik-prop-*`, and `data-bascik-build` use HTML's standards-valid `data-*` extension mechanism.
+* Bascik consumes those instructions at build time. They are not runtime directives that require a client library to interpret them.
+* **Tag structure ordering rule:** When writing component files containing both styles and scripts alongside HTML, always place `<style>` tags above the HTML markup as a style guide, and always place `<script>` tags below the HTML markup.
+
+### Repository Layout and the Create App
+
+The repo is split into four top-level folders:
+
+```text
+bascik/
+  pkg/          ← the @bascik/bascik npm package
+  create/       ← the standalone generator used by `npm create bascik@latest`
+  docs/         ← the docs site and internal developer guide
+  extensions/   ← editor tooling, including the VS Code extension for component navigation and scoping checks
+```
+
+The `create/` folder is intentionally separate from `pkg/`. Contributor work in this monorepo uses Yarn 4 with `yarn.lock`, while generated projects intentionally use npm and receive their own `package-lock.json`. That split keeps contributor workflows Yarn-based while preserving the standard npm onboarding flow for generated apps.
+
+The editor package in `extensions/vscode-bascik/` is intentionally separate from `pkg/`. It provides context-aware IntelliSense (component, prop, and slot completions), command-click component navigation, rich hover details, syntax highlighting, and real-time scoping warnings. Linting and language server capabilities are powered by `@bascik/language-server`, which also runs standalone via CLI (`npm run lint` or `npx @bascik/language-server --check`) and implements LSP so it works in Neovim, Helix, Zed, and other editors. The compatibility rules are generated from `docs/content/compatibility.md` via `docs/scripts/generate-compatibility-rules.ts`, so the editor and the published capability table stay in sync automatically instead of drifting apart.
+
+The generator in `create/src/index.ts` validates input, then calls `create/src/scaffold.ts` to write the project files. The generated app is not coupled to the monorepo layout. It just uses the published `@bascik/bascik` package and then runs as a normal Bascik site.
+
+For local contributor testing of the generator itself, rebuild from `create/`, link it with `npm link`, and invoke it via `npx create-bascik ...`; that remains the working flow for exercising the local scaffold end-to-end. `npm link` runs the `prepare` script, which copies the latest SKILL.md from `docs/` and rebuilds `dist/` automatically, so no separate build step is needed after a fresh checkout.
+
+---
+
+## 2. Component Format
+
+A component is one `.html` file inside `src/components/`. Its tag name is derived from the file name.
+
+### Component Naming Conventions
+Under the **WHATWG HTML standard (§4.13.1.2)**, custom elements should contain at least one hyphen (such as `<site-nav>`, `<hello-card>`, or `<my-button>`).
+* Single-word component filenames (e.g., `card.html`) compile for backward compatibility, but Bascik's CLI compiler and VS Code extension issue warnings encouraging a hyphenated name (`my-card.html`).
+* Filenames matching native HTML elements (e.g., `header.html` or `dialog.html`) issue a shadowing warning.
+* Always use lowercase hyphenated filenames in `src/components/` (e.g., `src/components/feature-card.html` for `<feature-card>`).
+
+**HTML-only component:**
+```html
+<!-- src/components/page-footer.html -->
+<footer>
+  <p>© 2025 My Site. All rights reserved.</p>
+</footer>
+```
+
+**HTML with inline CSS:**
+```html
+<!-- src/components/promo-banner.html -->
+<style>
+  .banner { padding: 1rem 1.5rem; background: #e8f4fd; border-left: 4px solid #3b82f6; }
+</style>
+<aside class="banner">…</aside>
+```
+
+**HTML with inline JavaScript** (use `id` + `getElementById` for per-instance targeting):
+```html
+<!-- src/components/scroll-top.html -->
+<button id="btn" type="button">Back to top</button>
+<script>
+  document.getElementById('btn').addEventListener('click', () => {
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+  });
+</script>
+```
+
+**All three in one file** (HTML + `<style>` + `<script>`):
+```html
+<!-- src/components/alert-box.html -->
+<style>
+  .alert { display: flex; align-items: center; gap: 0.75rem; padding: 1rem; border: 1px solid #f59e0b; border-radius: 6px; background: #fffbeb; }
+  .alert-close { margin-left: auto; background: none; border: none; cursor: pointer; }
+</style>
+<div class="alert" id="alert">
+  <span>Maintenance on Sunday, 2am–4am UTC.</span>
+  <button id="close" class="alert-close" aria-label="Dismiss">×</button>
+</div>
+<script>
+  document.getElementById('close').addEventListener('click', () => {
+    document.getElementById('alert').hidden = true;
+  });
+</script>
+```
+
+Use it in any page or other component:
+```html
+<alert-box></alert-box>
+```
+*Self-closing tags are also supported:* `<site-nav />` or `<site-nav class="top" />`
+
+**Separate CSS file:** pair a `.css` file with the same base name:
+```
+src/components/
+  alert-box.html
+  alert-box.css   ← scoped to alert-box
+```
+
+**Subfolder layout** (subfolders are allowed for organization, but the filename determines the tag name; duplicate names anywhere in components error):
+```
+src/components/
+  alert-box/
+    alert-box.html
+    alert-box.css
+    alert-box.ts    ← inlined and scoped via <script src="alert-box.ts"></script>
+```
+
+### Companion CSS and Script Files
+Companion `.css` files in the component directory are merged automatically. Companion script files (`.ts`, `.js`, `.mjs`) explicitly referenced via `<script src="counter.ts"></script>` inside component HTML are resolved, inlined, and scoped at build time. Path resolution is strictly scoped to the component directory or base filename.
+
+### Component Metadata Comments (`<!-- @bascik ... -->`)
+To document a component's public contract and provide rich hover and autocomplete information in editor tooling (such as the Bascik VS Code extension), add an optional leading `@bascik` metadata comment block at the very top of the component file:
+
+```html
+<!-- @bascik
+Interactive demo box with Preview, Source, and Output panes.
+@prop no-preview - Hides the Preview tab and collapses margins.
+@prop file - Monospace file path displayed in the demo meta bar.
+@slot example - Content rendered in the live preview pane.
+@slot source-usage - Usage code snippet shown in the source tab.
+@slot default - Default slot content if an un-named slot is exposed.
+-->
+<div class="demo-box">
+  <span data-bascik-prop-no-preview hidden></span>
+  <div class="demo-meta" data-bascik-prop-file></div>
+  <div data-bascik-slot="example"></div>
+  <div data-bascik-slot="source-usage"></div>
+  <div data-bascik-slot></div>
+</div>
+```
+
+**Metadata rules:**
+- **Placement:** Must be placed before any markup, `<style>`, or `<script>` tags. Whitespace and standard HTML comments may precede it.
+- **Markup is authoritative:** `@prop` and `@slot` annotations enrich inferred members with descriptions; they cannot declare members that do not exist in the markup.
+- **Syntax:** `@prop <name> - <description>` and `@slot <name> - <description>`. Use `@slot default - <description>` for the default slot. Text is rendered literally.
+
+### Component Decomposition & Shared Head Tags
+When structuring or migrating a site with Bascik, identify repeating HTML structures (especially shared `<head>` markup such as meta charset, viewport, favicons, fonts, Open Graph tags, and global CSS links, as well as site headers/footers) and extract them into reusable components.
+
+Component tags can be placed inside `<head>` element blocks in your page shells:
+
+```html
+<!-- src/components/site-head.html -->
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+<link rel="stylesheet" href="/styles.css" />
+```
+
+Page shells can then include `<site-head />` inside their `<head>`:
+
+```html
+<!-- src/pages/index.html -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <site-head />
+  <title>Home - My Site</title>
+</head>
+<body>
+  <site-nav />
+  <main>
+    <h1>Welcome</h1>
+  </main>
+  <site-footer />
+</body>
+</html>
+```
+
+At build time, Bascik expands `<site-head>` inside `<head>` and merges any component styles into the document `<head>` naturally. Proactively extract shared head elements, site headers, and site footers whenever initializing or refactoring a site into Bascik.
+
+### Multiple Root Elements
+Unlike other frameworks that require a single wrapper element or fragment, Bascik component templates support multiple top-level HTML elements in a single `.html` file. All root elements are inserted in order. If non-`data-bascik-*` attributes are passed on a usage tag, Bascik merges them onto the first root HTML element.
+
+**No restart needed.** The dev server watches the components directory. Drop a new `.html` (or paired `.css`) file in and all pages that use that tag are automatically re-transpiled and reloaded with no server restart required.
+
+---
+
+## 3. Scoped CSS
+
+Scoped CSS can live in a paired `.css` file or one or more inline `<style>` tags inside component HTML. Both go through the same scoping pipeline.
+
+At build time, Bascik extracts all inline `<style>` blocks, combines them with any companion `.css` file, scopes them, and injects them into the document `<head>`. Using multiple `<style>` tags (or mixing them with a companion `.css` file) is supported but not recommended for readability and maintainability. Choose a single stylesheet pattern per component.
+
+### Global Class Passthrough
+Bascik checks whether a class name in a component template is defined in the component's CSS (paired `.css` or inline `<style>`). Only class names defined in the component's stylesheet are scoped (prefixed/hashed). Classes in component HTML that are NOT defined in the component's stylesheet (such as global utility classes like `skip-link`, `flex`, `hidden`, or design system classes) pass through as unscoped global classes so global stylesheets continue to match them.
+
+Pair a `.css` file alongside the HTML in a same-named directory:
+
+```
+src/components/
+  site-nav/
+    site-nav.html
+    site-nav.css
+```
+
+All class names, element selectors, `#id` selectors, `@keyframes`, `@layer`, `@container`, `:is()/.class`, `:where()/.class`, `:has()/.class`, child/sibling combinator selectors, and CSS custom properties in component CSS are automatically scoped to that component. SVG elements with `class` attributes inside component HTML are also scoped. CSS `#id` selectors are converted to generated class selectors and the class is injected on the matching HTML element.
+
+`html`, `body`, and `head` are **never** converted to scoped classes. Cross-boundary selectors like `html[data-theme="light"] .foo {}` compile correctly: the root element name is preserved verbatim and only `.foo` is scoped, producing `html[data-theme="light"] .bascik__comp__foo {}`. This means theme-switching, dark/light mode, and other document-root state selectors in component CSS work as expected.
+
+These rewrites compose normally in one component: bare element selectors receive generated classes, locally declared custom properties and their `var()` references are renamed together, and keyframe declarations stay synchronized with `animation` references.
+
+Fragment-only CSS references such as `fill: url(#gradient)` are rewritten when the ID is declared in the same component. Quoted fragment forms are supported. Real URLs, data URLs, remote URLs, and cross-document fragments such as `url(sprite.svg#icon)` remain unchanged. Because IDs are per instance, a component with a resolvable CSS fragment automatically emits per-instance CSS even when `deduplicateCss: true`; components without fragments still deduplicate normally. Fragment rewriting runs before base-path URL processing.
+
+```css
+/* site-nav.css: source */
+.nav a {
+  color: white;
+}
+p {
+  margin: 0;
+}
+@keyframes fade {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+```
+
+```css
+/* compiled output */
+.bascik__site-nav__nav a { color: white; }
+.bascik__site-nav__el__p { margin: 0; }
+@keyframes bascik__site-nav__keyframe__fade { ... }
+```
+
+### Scoped CSS Custom Properties
+CSS custom properties declared in the file are also scoped. `var(--prop, fallback)` with fallback values is fully supported, the property name is scoped and the fallback preserved:
+
+```css
+/* source */
+:root {
+  --brand: #d3ff8d;
+}
+.title {
+  color: var(--brand);
+  border-color: var(--brand, rgb(150, 150, 150)); /* fallback preserved */
+}
+
+/* compiled */
+:root {
+  --bascik__site-nav__brand: #d3ff8d;
+}
+.bascik__site-nav__title {
+  color: var(--bascik__site-nav__brand);
+  border-color: var(--bascik__site-nav__brand, rgb(150, 150, 150));
+}
+```
+
+#### Using global design tokens in a component
+Define your design tokens once in a global stylesheet, then consume them inside any component. Because the component never declares those properties locally, Bascik leaves the `var()` references as-is and they resolve from the global stylesheet at render time.
+
+```css
+/* src/styles.css: design tokens, linked in every page <head> */
+:root {
+  --brand: #d3ff8d;
+  --card-bg: #1e2022;
+  --text-muted: #8d929e;
+}
+```
+
+```html
+<!-- src/components/brand-card.html -->
+<style>
+  .card {
+    padding: 24px 28px;
+    background: var(--card-bg); /* global: Bascik leaves untouched */
+    border-top: 3px solid var(--brand);
+    border-radius: 10px;
+  }
+  .card-label {
+    color: var(--text-muted);
+  }
+</style>
+<div class="card">
+  <p class="card-label" data-bascik-prop-label></p>
+  <div data-bascik-slot></div>
+</div>
+```
+
+```css
+/* dist/ output: class names scoped, var() refs preserved */
+.bascik__brand-card__card {
+  padding: 24px 28px;
+  background: var(--card-bg);
+  border-top: 3px solid var(--brand);
+  border-radius: 10px;
+}
+.bascik__brand-card__card-label {
+  color: var(--text-muted);
+}
+```
+
+### CSS Scoping Compatibility Notes
+* CSS nesting: fully supports explicit `&` nesting (`& p`, `& > h2`, `&>h2`) and 2023 W3C relaxed direct nesting without `&` (`> h2`, `+ li`, `~ span`, direct nested element selectors)
+* `@property`: `@property --name { }` declaration names are scoped along with any matching `--name:` declarations and `var(--name)` references in the same component
+* `@starting-style`: class names and element selectors inside `@starting-style` blocks are scoped by the same passes that handle other at-rules; both standalone `@starting-style { .foo { } }` and nested `.foo { @starting-style { } }` forms work
+* `@counter-style`: `@counter-style name { }` declaration names are scoped; references in `list-style`, `list-style-type`, `counter(counter, name)`, and `counters(counter, sep, name)` in the same CSS file are updated to match
+* `view-transition-name`: ✓ values are scoped per component (`bascik__<comp>__vtn__<name>`); matching `::view-transition-old/new/group/image-pair()` pseudo-element references in the same file are updated; `none` and `auto` are not scoped
+* `anchor-name` / `@position-try`: `anchor-name: --name` declarations are scoped per component; matching `position-anchor: --name` references and `@position-try --name { }` at-rules in the same CSS file are updated to match; only anchors declared in the component's own CSS are scoped
+* `@scope` (native): class names in `@scope (.foo)` argument and optional `to (.clause)` are scoped normally, and class names inside the `@scope` block are scoped
+* `:nth-child(An+B of .selector)`: class names in the `of <selector>` argument are scoped (same global `(?<=\.)` pass as `:is()`, `:where()`, `:has()`); works for `:nth-child` and `:nth-last-child`
+* `@font-face`: passed through untouched; declare in a shared stylesheet to avoid duplicate injections
+* `@import`: local file imports (`@import "./file.css"`) are inlined recursively and scoped to the component; remote URLs (`@import "https://..."`) are preserved and hoisted to the top of the compiled stylesheet
+* Standalone attribute selectors (e.g. `[data-state]`): not scoped and can leak globally; anchor with a scoped class: `.card[data-state]`
+* `[id]` selectors: `[id]` and `[id="..."]` attribute selectors in CSS are stripped at compile time because they cannot be scoped without DOM wrapping
+* Compound element selectors: `.class element {}` and `.class > element {}` are scoped (element converted to class and injected on matching HTML elements); patterns with two bare elements (`div p {}`) still require a class anchor on the left
+* Element names inside `:is()`, `:where()`, and `:has()` are not converted; use class selectors inside those pseudo-classes instead
+
+---
+
+## 4. Scoped JavaScript
+
+**Key rule:** Use `id` attributes to identify elements you need to control per-instance, and `getElementById` to find them. Bascik rewrites selector strings at build time, you write your component as if it's the only one on the page.
+
+DOM selectors in component scripts are rewritten to match scoped names:
+
+```html
+<!-- source -->
+<button id="my-btn">Click</button>
+<script>
+  document
+    .getElementById("my-btn")
+    .addEventListener("click", () => alert("hi"));
+</script>
+```
+
+```html
+<!-- compiled -->
+<button id="bascik__my-btn__a1b2__my-btn">Click</button>
+<script>
+  (function () {
+    document
+      .getElementById("bascik__my-btn__a1b2__my-btn")
+      .addEventListener("click", () => alert("hi"));
+  })();
+</script>
+```
+
+### Supported DOM Methods (auto-rewritten)
+* `document.getElementById("id")`
+* `document.querySelector("#id")` / `document.querySelectorAll("#id")`
+* `document.querySelector(".cls")` / `document.querySelectorAll(".cls")`: single OR compound selectors
+* `document.querySelector(".foo .bar")` / `querySelector("#id .child")`: compound selectors supported
+* `document.getElementsByClassName("cls")`
+* `document.getElementsByName("name")`
+* `element.closest("#id")` / `element.closest(".cls")`: compound-aware
+* `element.matches("#id")` / `element.matches(".cls")`: works for event delegation too
+* `element.classList.add/remove/toggle/contains("cls")`: all single and multi-argument forms
+* `element.classList.replace("old", "new")`: both arguments rewritten
+* `element.setAttribute("class", "cls")` / `setAttribute("id", "id-value")` / `setAttribute("name", "value")`: string literal values
+* `element.className = "cls"` or `"cls1 cls2"` or `+= " cls"`: setter forms; space-separated multi-class strings fully rewritten
+* `innerHTML` / `insertAdjacentHTML` string literals, known class names inside the HTML string are rewritten
+* `removeAttribute`, `hasAttribute`, `toggleAttribute`: take attribute names (not values), no rewriting needed
+* **JS-only class discovery:** class names referenced in `classList.*`, `.className` in selector strings, `el.className = "..."`, and `setAttribute("class", "...")` are automatically discovered and added to the class scope map before JS rewriting.
+
+### Not Rewritten (known limitations)
+* `el.id = "value"`: property setter not rewritten; use `getElementById` then work from the reference
+* `el.style.setProperty("--my-var", value)`: runtime CSS custom property names are not rewritten; the scoped var name (e.g. `--bascik__comp__my-var`) is different from the source name
+* Template literals: `` el.className = `box ${state}` ``, not rewritten; use `classList.add/remove` instead
+* Template-literal replacement arguments in `classList.replace(oldName, \`${dynamic}\`)` are not rewritten safely; prefer `classList.add/remove/toggle` with static class names
+* `querySelector("[name='username']")`: attribute-selector form for `name`; use `getElementsByName` instead
+* `innerHTML` / `insertAdjacentHTML` string literals: scanning only recognizes class names that appear in the HTML template.
+
+### Scoping Model
+`id` and `name` attributes are scoped **per-instance:** each use of a component generates a different `instanceId`, guaranteeing unique DOM IDs even when the same component appears multiple times on a page. `class` attributes are scoped to the component name only (no instanceId), so all instances share the same class names and CSS deduplication emits a single `<style>` block.
+
+HTML references to locally declared IDs are rewritten automatically in the same component. This includes `<label for>`, form, ARIA, and microdata `itemref` ID attributes, fragment-only `href` values, SVG fragment attributes, and inline `style` `url(#id)` values. Space-separated lists resolve one token at a time. `usemap` resolves against `<map name>` and follows name scoping. References that target page-shell IDs or IDs in another component remain unchanged because cross-component instance resolution is not possible at build time. Use `data-bascik-preserve` when an external system requires a literal ID graph.
+
+Form inputs using `<input name="username">` receive per-instance scoped names (e.g. `bascik__comp__a1b2c3__username`), so `new FormData(form)` keys reflect the scoped name.
+
+Literal component tags inside `<script>`, `<style>`, `<textarea>`, or HTML comments (`<!-- <my-card> -->`) are treated as text and never resolved into components.
+
+```
+class  →  bascik__<componentName>__<originalName>
+id     →  bascik__<componentName>__<instanceId>__<originalName>
+name   →  bascik__<componentName>__<instanceId>__<originalName>
+```
+
+### Multiple Script Blocks
+Component templates can contain multiple `<script>` tags. Bascik processes each script tag according to its attributes:
+* **Client scripts:** Standard JavaScript blocks are each wrapped in an isolated IIFE `(function() { ... })();` when `scoping.scriptBlocks` is enabled. If you include multiple client `<script>` tags in a single component, each runs in its own IIFE so local variables do not collide.
+* **Build scripts (`<script data-bascik-build>`):** Executed during build or dev time in Node.js to generate dynamic markup.
+* **Server scripts (`<script data-bascik-server>`):** Executed on the server at request time in Node.js.
+* **Data scripts (e.g. `type="application/ld+json"`):** Left untouched without IIFE wrapping or JavaScript minification.
+
+Recommended Pattern: Keeping separate, unrelated concerns in dedicated client `<script>` tags (like form validation and UI animation) is recommended for code readability and maintainability.
+
+### Multiple Instances
+Using a component more than once works automatically, each use gets a different `instanceId`, so IDs never collide and each instance's scripts reference only its own elements.
+
+### Class Selectors and Multiple Instances (PITFALL)
+Because class names are scoped to the component **name** (not per-instance), `querySelector('.my-class')` and `querySelectorAll('.my-class')` **always return the first matching element in the document**, even after Bascik rewrites the class name. When the same component is used more than once on a page, every instance's script will target the first instance's elements, the other instances' buttons/inputs/etc. will appear non-functional.
+
+**Rule:** In component scripts, always use `getElementById` (or `getElementsByName`) to locate specific elements, both are per-instance scoped and always resolve to the correct element. Never use `querySelector`/`querySelectorAll` with a class selector to find an element you need to control per-instance.
+
+```html
+<!-- ❌ Broken for multiple instances -->
+<button class="my-btn">Click</button>
+<script>
+  document.querySelector('.my-btn').addEventListener('click', () => { … });
+</script>
+
+<!-- ✅ Correct: id is per-instance -->
+<button id="my-btn" class="my-btn">Click</button>
+<script>
+  document.getElementById('my-btn').addEventListener('click', () => { … });
+</script>
+```
+
+**Escape hatch:** Set `scoping.deduplicateCss` to `false` in `bascik.config.ts` to switch to per-instance class scoping. By default, all instances of the same component share identical scoped class names so Bascik emits one shared `<style>` block per component. With `scoping.deduplicateCss: false`, class selectors become unique per instance (like IDs), but Bascik emits a separate `<style>` block for each component instance.
+
+### `deduplicateCss` Trade-Off Comparison
+
+Setting `scoping.deduplicateCss` in `bascik.config.ts` controls whether class names are scoped per component type or per component instance.
+
+| Feature or Aspect | `deduplicateCss: true` (Default) | `deduplicateCss: false` |
+|---|---|---|
+| **Class Scoping Scheme** | `bascik__card__wrapper` (shared per component) | `bascik__card__a1b2c3d4__wrapper` (unique per instance) |
+| **CSS Payload** | Single `<style>` block per component type, zero CSS duplication | Multiplied `<style>` blocks (one block per component instance) |
+| **`querySelector('.cls')` Behavior** | Targets the first instance on the page | Targets the matching element inside that specific instance |
+| **Instance Isolation Model** | Use `id` and `getElementById()` for per-instance script isolation | Class selectors inherently isolate per instance |
+| **Best For** | Virtually all production sites and design systems | Migrating legacy or third-party code that relies on class queries |
+
+#### Side-by-Side Code Example
+
+Given two instances of `<my-card>` on the same page:
+
+```html
+<!-- Input Page HTML -->
+<my-card></my-card>
+<my-card></my-card>
+```
+
+**Output with `deduplicateCss: true` (Default, Shared Class Scope):**
+
+```html
+<!-- HTML Output: Shared classes, unique IDs -->
+<div class="bascik__my-card__wrapper" id="bascik__my-card__a1b2c3d4__root">...</div>
+<div class="bascik__my-card__wrapper" id="bascik__my-card__e5f6g7h8__root">...</div>
+
+<!-- CSS Output: Emitted once in <head> -->
+<style>
+  .bascik__my-card__wrapper { padding: 1rem; }
+</style>
+```
+
+**Output with `deduplicateCss: false` (Per-Instance Class Scope):**
+
+```html
+<!-- HTML Output: Unique classes per instance -->
+<div class="bascik__my-card__a1b2c3d4__wrapper" id="bascik__my-card__a1b2c3d4__root">...</div>
+<div class="bascik__my-card__e5f6g7h8__wrapper" id="bascik__my-card__e5f6g7h8__root">...</div>
+
+<!-- CSS Output: Emitted for every instance -->
+<style>
+  .bascik__my-card__a1b2c3d4__wrapper { padding: 1rem; }
+  .bascik__my-card__e5f6g7h8__wrapper { padding: 1rem; }
+</style>
+```
+
+Using the `id`-based pattern with `getElementById()` is recommended because it gives you per-instance JS isolation while keeping `deduplicateCss: true` for minimal CSS payload.
+
+### TypeScript in Component Scripts
+
+Bascik ships vanilla JavaScript to the browser and strips browser TypeScript automatically on two supported paths. No configuration is required and `minify.js` is not involved.
+
+* **Default: companion `.ts` file.** `<script src="counter.ts"></script>` inside a component inlines `counter.ts` with its erasable types stripped. Line structure is preserved so `//# sourceURL` line numbers match the `.ts` source.
+* **Inline opt-in:** `<script type="text/typescript">...</script>` in a page or component is stripped and emitted as an ordinary `<script>` (the `type` attribute is removed).
+* **Ordinary `<script>` is JavaScript.** Browsers do not run TypeScript in an unmarked block, so Bascik never rewrites it. If it can positively identify erasable TypeScript there, the build logs a warning naming the file and the two fixes above. Do not put TypeScript annotations in an unmarked `<script>`.
+
+Pipeline order is fixed: TypeScript strip, then scoping (IIFE, selector rewriting, `//# sourceURL`), then optional `minify.js`. A `minify.js` function (built-in or custom such as esbuild with `loader: 'js'`) therefore always receives valid JavaScript.
+
+**Default compiler is erasable syntax only** (Node 22.18+ strip-only mode): annotations, interfaces, type aliases, `as` casts, `!` assertions, `import type`. Non-erasable syntax (`enum`, parameter properties, namespaces with runtime code) fails the build with the file path. Prefer `as const` objects over `enum`.
+
+**Compiler selection: `scripts.typescript`** (`true` default | `false` | function). Set a function to bring your own compiler when a project needs `enum`, decorators, an older browser `target`, or the same toolchain it uses elsewhere. It receives `(code, { sourcePath, kind })` where `kind` is `'companion'` or `'inline'`, must return plain JavaScript, and runs at the same pipeline point (before scoping and `minify.js`), including inside worker threads. Set `false` only when another tool has already compiled the files Bascik reads; marked blocks then pass through untouched, `type` attribute included.
+
+```ts
+// bascik.config.ts (illustrative: esbuild as the browser TypeScript compiler)
+import { transform } from 'esbuild';
+import { defineConfig } from '@bascik/bascik/config';
+
+export default defineConfig({
+  scripts: {
+    typescript: async (code, { sourcePath }) =>
+      (await transform(code, { loader: 'ts', target: 'es2020', sourcefile: sourcePath })).code,
+  },
+});
+```
+
+This option is browser-only. Build, routes, server, and API route `.ts` files are executed by Node directly; Node handles their TypeScript (pass `--experimental-transform-types` via `NODE_OPTIONS` for non-erasable syntax there).
+
+Never configure `minify.js` merely to strip TypeScript. Bascik performs supported browser TypeScript stripping automatically before the minifier hook. Add a custom `minify.js` function only when the project requires non-default JavaScript minification.
+
+### Debugging Component Scripts & Virtual Source Files
+
+When debugging component scripts in browser DevTools (Cmd+Option+I or F12), Bascik provides virtual source files and accurate stack traces:
+
+* **Virtual Source Files:** Bascik appends a `//# sourceURL=src/components/name.html` directive and preserves line-offset padding in every component client `<script>` block. In browser DevTools under the **Sources** (or Debugger) panel, your component scripts appear as virtual files matching your project folder structure (e.g., `src/components/card.html`).
+* **Console Logs & Breakpoints:** Because component scripts are listed as virtual files, you can search for them directly using `Cmd + P` or `Ctrl + P` in DevTools, set breakpoints, and step-debug. Runtime console logs and uncaught exceptions map directly to the original component file and line offset rather than the generated HTML page.
+
+---
+
+## 5. Dynamic Runtime Class Scoping & JS-Only Class Discovery
+
+Class names referenced in JavaScript (`classList.add/remove/toggle/replace`, `.className` in selector strings, `el.className = "..."`, and `setAttribute("class", "...")`) are automatically discovered by Bascik's JS scanner and added to the component's class scope map before the JS rewrite runs.
+
+This means dynamic modifier classes (such as `is-open` or `btn--active`) that only appear inside a `<script>` block and never in a `class="..."` HTML attribute are scoped automatically in both CSS and JS without needing any template annotations.
+
+```html
+<section class="card" id="card">
+  <p id="status">Panel closed</p>
+  <button id="toggle" type="button">Toggle</button>
+</section>
+<script>
+  const toggle = document.getElementById('toggle');
+  const status = document.getElementById('status');
+  const card = document.getElementById('card');
+
+  toggle.addEventListener('click', () => {
+    const isOpen = card.classList.toggle('is-open'); // is-open is automatically discovered and scoped in CSS and JS
+    status.textContent = isOpen ? 'Panel open' : 'Panel closed';
+  });
+</script>
+```
+
+The only exception is `innerHTML` / `insertAdjacentHTML` HTML string scanning, which only recognizes class names that appear as static `class="..."` attributes in the component HTML template.
+
+---
+
+## 6. Slots & Props
+
+### Slots (Default & Named)
+
+#### Default Slot
+
+Add `data-bascik-slot` (no value) to any element in the component template. The element is replaced by the slot content at the usage site. Use the element's inner content as fallback when no slot content is provided.
+
+Slot content remains raw HTML, participates in scoping, and may contain nested Bascik components. Use slots, not props, for rich markup.
+
+```html
+<!-- my-card.html -->
+<div class="card">
+  <div data-bascik-slot><p>No content provided.</p></div>
+</div>
+
+<!-- usage -->
+<my-card>
+  <h2>Card Title</h2>
+  <p>Card body text.</p>
+</my-card>
+
+<!-- output -->
+<div class="card">
+  <h2>Card Title</h2>
+  <p>Card body text.</p>
+</div>
+```
+
+#### Named Slots
+
+Use `data-bascik-slot="name"` in the template to define named zones. At the usage site, wrap content with the same attribute.
+
+```html
+<!-- page-layout.html -->
+<div class="layout">
+  <header><div data-bascik-slot="header"></div></header>
+  <main><div data-bascik-slot></div></main>
+  <aside><div data-bascik-slot="sidebar"></div></aside>
+</div>
+
+<!-- usage -->
+<page-layout>
+  <p>Main body content.</p>
+  <div data-bascik-slot="header"><h1>Page Title</h1></div>
+  <div data-bascik-slot="sidebar"><nav>Sidebar nav</nav></div>
+</page-layout>
+```
+
+### Slot Whitespace
+Leading and trailing whitespace is trimmed from all slot content at build time. Whitespace *within* slot content is preserved exactly as written.
+By default Bascik skips transpilation inside `<code>` elements, so raw code examples stay literal.
+
+### Props
+Inject text values into a component at usage time.
+
+```html
+<!-- alert-box.html -->
+<div class="alert">
+  <strong data-bascik-prop-title></strong>
+  <p data-bascik-prop-message></p>
+</div>
+
+<!-- usage -->
+<alert-box
+  data-bascik-prop-title="Success"
+  data-bascik-prop-message="Your changes were saved."
+></alert-box>
+```
+Props in Bascik follow the same basic idea as React props, but the mechanism is vanilla HTML through `data-bascik-prop-*` attributes.
+The `data-bascik-prop-*` marker is removed from compiled output, while the target element's other attributes are preserved.
+Prop values are HTML-escaped on injection. Entity-encode delimiting quotes in usage attributes. Props are read only from the component's opening tag, so nested component props do not leak upward.
+*Props accept text values only. For rich HTML content or nested components, use slots.*
+
+To send a prop value to an element attribute, use `data-bascik-attr-{attribute}="{propName}"` in the component template:
+
+```html
+<img data-bascik-attr-src="image" data-bascik-attr-alt="alt">
+<a data-bascik-attr-href="link">Read more</a>
+```
+
+This is the same prop value with a different destination, not templating or variables. The directive is removed from output. A missing prop adds no attribute. If the target already exists, the prop wins and Bascik warns. Bound `id`, `name`, and `class` values are scoped normally.
+
+---
+
+## 7. Attribute Inheritance & Tags
+
+### Attribute Inheritance
+Non-`data-bascik-*` attributes on a usage tag are merged onto the component's root element when `scoping.inheritAttributes` is `true` (the default). `id` is forwarded too unless the template root already defines its own `id`. Class names are appended, not replaced.
+
+If a component template contains multiple root elements, inherited attributes are merged onto the first root HTML element in the component template.
+
+```html
+<!-- usage: attributes here are forwarded onto the component root -->
+<site-nav class="sticky" aria-label="main navigation"></site-nav>
+
+<!-- site-nav.html: component template -->
+<nav class="nav"><a href="/">Home</a></nav>
+
+<!-- compiled output: class appended, aria-label forwarded -->
+<nav class="bascik__site-nav__nav sticky" aria-label="main navigation">
+  <a href="/">Home</a>
+</nav>
+```
+
+Inherited class names are not scoped, they are treated as global page-level classes. To disable inheritance, set `scoping.inheritAttributes` to `false` in `bascik.config.ts`.
+
+### Internal Masking vs. Preserving Element Contents
+
+These two mechanisms serve distinct purposes:
+
+* **Internal scanning mask (internal, hardcoded, not configurable):** Bascik temporarily blanks the contents of `<script>`, `<style>`, `<textarea>`, and HTML comments while scanning with regular expressions, so a component tag inside a JavaScript string, style block, or comment is not mistaken for real markup. The mask is discarded immediately after scanning. Authors never interact with or configure this behavior.
+* **Preserve scoping (authoring choice):** Keep scoping enabled by default. Use `scoping.preserve` (default `['code']`) when every matching tag and subtree must keep literal `id`, `name`, and `class` values. Entries are exact tag names or `*` wildcard patterns (for example `vendor-*` preserves every tag whose name starts with `vendor-`); both use the same semantics. Use bare `data-bascik-preserve` for one element and subtree, or list selected attributes such as `data-bascik-preserve="name"`. Nesting only widens. Preserving `name` gives up per-instance radio-group isolation, so reserve it for external form endpoints that require literal field names.
+
+### Self-Closing Tags
+Components that do not contain inner slot content should always use self-closing void syntax:
+```html
+<site-nav />
+<site-head />
+<site-footer />
+<site-nav class="top" />
+```
+
+### Head Components
+Components work inside `<head>` to organize metadata and shared links:
+```html
+<!-- src/components/site-meta.html -->
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<meta name="description" content="My site" />
+
+<!-- usage in page shell -->
+<head>
+  <site-meta />
+  <title>Home</title>
+</head>
+```
+
+---
+
+## 8. Build-time Scripts
+
+`<script data-bascik-build>` blocks are executed at transpile time as Node.js ESM modules. The script's stdout is injected in place of the tag. Runs in both dev and build modes.
+
+```html
+<script data-bascik-build>
+  import { readFile } from 'node:fs/promises';
+  import { marked } from 'marked';
+  const md = await readFile('./content/intro.md', 'utf8');
+  console.log(marked(md));
+</script>
+```
+
+* Top-level `import` and top-level `await` are supported.
+* CWD is the project root. Quoted data paths (`readFile('./content/x.md')`) resolve from there.
+* **Importing shared helpers: use `@/` by default.** `import { renderMd } from '@/lib/md-renderer.ts'` resolves against `scripts.importRoot` (default `src`), so the identical import line works from any page or component at any nesting depth. Relative `./` and `../` specifiers still work and resolve against the file that contains the script; use them for helpers that live next to the page or component. Both forms also apply to `data-bascik-server`, `data-bascik-routes`, and the `src="…"` attribute on those tags.
+* **Never use a bare leading `/`.** `import x from '/lib/x.ts'` or `src="/lib/x.ts"` inside a Bascik script is a hard compile error (and a red diagnostic in the VS Code extension), regardless of `onBuildScriptError`. A bare slash is ambiguous between filesystem root and site root. The error names the two valid rewrites: `@/lib/x.ts` (import root) or `./lib/x.ts` (relative). Plain client `<script>` tags are unaffected.
+* **Alias gotchas:** only the exact `@/` prefix is an alias (`@scope/pkg` is a normal package). Aliases are rewritten only inside script blocks; a helper file importing another helper must use `./` or `../`. Add shared build helpers to `pipeline.watchPaths` when outside the pages/components directories. The import-root watcher only invalidates request-time modules, not page compilation caches.
+* Use `console.log()` or `process.stdout.write()` to output HTML. Build scripts execute as top-level Node.js ESM modules rather than wrapped functions, so top-level `return` is a JavaScript syntax error; output is sent to stdout instead.
+* Build scripts run before component resolution, so their output can contain component tags.
+* Each uncached build script executes in its own fresh child process, isolated from every other script, regardless of how many siblings are cache misses. Output is assembled in document order once all scripts complete. Bounded concurrency is enforced by a memory-aware semaphore, but scripts never share a process or global ESM registry, so detached async output from one script can never bleed into a neighbor.
+* On error, behavior is controlled by three script-specific options in `bascik.config.ts`: `scripts.onBuildScriptError`, `scripts.onRoutesScriptError`, and `scripts.onServerScriptError` (each supports `'warn'`, `'error'`, or `'ignore'`). Defaults are mode-aware: `'warn'` in dev, `'error'` during `--build` and `--server`. For `data-bascik-stream` scripts, an error cannot produce an HTTP 500 because headers are already committed; the slot is emitted empty, the failure is logged at the configured severity, and the document completes.
+* **Stack Trace Remapping:** For `<script data-bascik-build>`, `<script data-bascik-server>`, and `<script data-bascik-stream>` blocks, Bascik automatically intercepts child-process stack traces, filters out noisy Node.js internal files, stack frames, and `Command failed:` headers, and remaps temporary execution files back to your source HTML file and line offset (e.g., `src/pages/dashboard.html:25`). This filters out the noise of internal V8 loader frames and child process execution headers, leaving only the clean, actionable stack trace of your template and helper scripts. In VS Code or terminal emulators, you can Cmd+Click (or Ctrl+Click) the file reference in the error log to jump directly to the failing script's exact line.
+* **Hard error:** combining any of `data-bascik-build`, `data-bascik-routes`, `data-bascik-server`, or `data-bascik-stream` on the same tag throws and aborts the build. Directives are mutually exclusive.
+
+### Build Script Environment Variables
+
+Build scripts receive these `process.env` variables:
+
+| Variable | Description |
+|---|---|
+| `BASCIK_PAGE_PATH` | Normalized root-relative route path of the current page shell (e.g. `/getting-started`, `/switch/from-vue`, `/`). |
+| `BASCIK_SOURCE_FILE` | Absolute path to the file currently being transpiled (page or component template). |
+| `BASCIK_PAGE_FILE` | Absolute path of the current page file (e.g. `/project/src/pages/about.html`). Use this to generate page-specific output like canonical URLs. |
+| `BASCIK_PAGES_DIR` | Absolute path to the configured pages directory. |
+| `BASCIK_OUT_DIR` | Absolute path to the configured output directory (exec scripts). |
+| `BASCIK_BUILD` | `"1"` during `bascik --build`, `"0"` during dev. Use to produce different output per mode. |
+| `BASCIK_SITE_URL` | The site URL resolved from `--site-url`, the `BASCIK_SITE_URL` env var, or `.env`. Absent when unset, never an empty string. |
+| `BASCIK_BASE` | Normalized deployment base from config. Always present and defaults to `/`. Use it when a build script must expose the prefix for JavaScript-built URLs. |
+| `BASCIK_ROUTE` | JSON string `{ params, data }` passed to build scripts inside dynamic route templates. |
+
+These are critical for scripts that generate per-page output. A script using `BASCIK_SOURCE_FILE`, `BASCIK_PAGE_FILE`, or `BASCIK_PAGE_PATH` gets a separate cache entry per page automatically.
+
+### The Fetch-Once Pattern
+
+When a data-driven page needs the same data in several places, read or fetch it **once at page level** in a single `data-bascik-build` script, then apply it everywhere on the page. Not once per component instance. The same data object can feed a second script, a JSON payload for client JavaScript, or a component prop, without a second network round trip or file read.
+
+**Cache exclusion gotcha:** the build script cache keys on script content, statically scanned local dependencies, and resolved installed-package identity. It **cannot see network fetches**, `readdir` directory reads, computed file paths, or dynamic computed imports. A script whose output depends on a remote API will be served from cache with stale data across builds, and nothing will tell you. A script containing a dynamic non-literal import (`import(someName)` or `` import(`../${x}`) ``) is treated as non-cacheable and re-runs every build. Exclude scripts that read external data via `scripts.cache.exclude` (see below), or disable the cache for them.
+
+### Build Script Output Cache
+
+Each `<script data-bascik-build>` spawns a Node.js child process (~50–150 ms startup each). Bascik caches script output on disk so unchanged scripts skip the spawn on subsequent builds or server restarts.
+
+**Cache location:** `node_modules/.cache/bascik/script-cache/<sha256>.json`
+
+**Cache key:** SHA-256 of the script content + dev/build mode + the source file path (`BASCIK_SOURCE_FILE`) + the site URL + the deployment base + dynamic route parameters + the full content of any local dependency files referenced as quoted path literals in the script + the resolved identity of every installed package the script (or its local dependencies) imports. Package identity covers the package manifest and the resolved entry, plus a bounded transitive hash of the packages those imports themselves pull in, so upgrading a build-time npm dependency invalidates affected entries automatically regardless of cache temperature.
+
+**Excluding scripts from cache:** Statically scanned cache keys cannot detect runtime network calls, `readdir` directory reads, or dynamic computed file paths. For scripts reading from external APIs or computed paths, exclude them via `scripts.cache.exclude`:
+
+```ts
+// bascik.config.ts
+import { defineConfig } from '@bascik/bascik/config';
+
+export default defineConfig({
+  scripts: {
+    cache: {
+      enabled: true,
+      exclude: ['src/pages/live-feed/**', 'src/components/api-cards/**'],
+    },
+  },
+});
+```
+
+**Environment variable cache keys (`scripts.cache.environment`):** By default, `process.env` reads are invisible to the cache key. Declare the exact variable names a script reads in `scripts.cache.environment` so their resolved values become part of the key:
+
+```ts
+export default defineConfig({
+  scripts: {
+    cache: {
+      enabled: true,
+      environment: ['MY_FEATURE_FLAG', 'API_BASE_URL'],
+    },
+  },
+});
+```
+
+When a declared variable's value changes, the cache key changes and the script re-runs. Values are hashed into the key and never persisted. Missing vs. empty string produce different keys. Only exact names are supported (no globs). Bascik warns about statically visible `process.env.NAME` reads that are not declared; the warning is advisory and never fails the build.
+
+**To bust the entire cache** (waive cache correctness, e.g. after an unusual external change the identity walk cannot see):
+
+```sh
+rm -rf node_modules/.cache/bascik/script-cache
+```
+
+With `pipeline.workers: true`, multiple workers share the same cache directory. Workers that independently miss the same key both spawn a child process; last write wins with identical content. This is a minor inefficiency on a cold first build only.
+
+### Rendering and Styling Markdown
+
+Install a Markdown parser such as `marked`, read the source in a build script, and write the resulting HTML to stdout:
+
+```html
+<script data-bascik-build>
+  import { readFile } from 'node:fs/promises';
+  import { marked } from 'marked';
+
+  const md = await readFile('./content/article.md', 'utf8');
+  console.log(marked(md));
+</script>
+```
+
+Given this Markdown source:
+
+```md
+## A practical heading
+
+Markdown stays comfortable for authors, while the published page stays **vanilla HTML**.
+
+> Add an editorial treatment with ordinary CSS.
+```
+
+`marked()` emits:
+
+```html
+<h2>A practical heading</h2>
+<p>Markdown stays comfortable for authors, while the published page stays <strong>vanilla HTML</strong>.</p>
+<blockquote>
+<p>Add an editorial treatment with ordinary CSS.</p>
+</blockquote>
+```
+
+The parser emits ordinary HTML, so it can be styled by a global stylesheet or wrapped in a Bascik component. For reusable scoped styles, have the script emit `<markdown-content>${marked(md)}</markdown-content>` and give that component a default slot.
+
+Use wrapper descendant selectors for generated slot content:
+
+```css
+.markdown-content h2 { margin-block: 2.5rem 0.75rem; }
+.markdown-content blockquote { border-left: 4px solid currentColor; }
+```
+
+Do not rely on a bare `h2 {}` component rule for Markdown passed through a slot. Bare element rules are transformed before slot content is inserted; a scoped wrapper selector continues to match the generated descendants.
+
+### Page-Aware Scripts
+
+Some pages need content that is specific to the current page, such as a canonical URL in the head, an Open Graph image, a structured-data block, or even a page-specific sidebar. Hardcoding those values in every page file works. However, a shared script is easier to maintain. You can change the logic once and every page picks it up automatically.
+
+Bascik makes this possible by injecting environment variables into every `data-bascik-build` subprocess: `BASCIK_SOURCE_FILE`, `BASCIK_PAGE_FILE`, `BASCIK_PAGES_DIR`, and `BASCIK_SITE_URL` (described in the Environment Variables table above).
+
+#### Canonical URL Example
+
+A canonical URL tag tells search engines which URL is the authoritative version of a page. Every docs page on this site uses a shared `scripts/canonical.ts` that derives the URL from `BASCIK_SOURCE_FILE`:
+
+```ts
+// scripts/canonical.ts
+export async function canonical(): Promise<string> {
+  const siteUrl = (process.env.BASCIK_SITE_URL ?? '').replace(/\/$/, '');
+  const pageFile = process.env.BASCIK_SOURCE_FILE ?? process.env.BASCIK_PAGE_FILE ?? '';
+  const pagesDir = process.env.BASCIK_PAGES_DIR ?? '';
+
+  if (!siteUrl || !pageFile || !pagesDir) return '';
+
+  const relPath = pageFile.slice(pagesDir.length).replace(/^[\\/]/, '').replace(/\\/g, '/');
+  const withoutExt = relPath.replace(/\.html$/, '');
+  const route = withoutExt === 'index' ? '' : withoutExt.replace(/\/index$/, '/');
+  const urlPath = route ? `/${route}` : '/';
+
+  return `<link rel="canonical" href="${siteUrl}${urlPath}" />`;
+}
+```
+
+Use it from any page's `<head>`:
+
+```html
+<head>
+  <script data-bascik-build>
+    import { canonical } from '../../scripts/canonical.ts';
+    console.log(await canonical());
+  </script>
+</head>
+```
+
+#### Reading the Page's Own HTML
+
+For richer outputs, including Open Graph tags or JSON-LD structured data, a script can also read the page file itself to extract metadata. `BASCIK_SOURCE_FILE` is an absolute path, so `readFile` works directly:
+
+```ts
+// scripts/article-schema.ts (simplified)
+import { readFile } from 'node:fs/promises';
+
+export async function articleSchema(): Promise<string> {
+  const pageFile = process.env.BASCIK_SOURCE_FILE ?? process.env.BASCIK_PAGE_FILE ?? '';
+  const siteUrl = (process.env.BASCIK_SITE_URL ?? '').replace(/\/$/, '');
+  if (!pageFile || !siteUrl) return '';
+
+  const html = await readFile(pageFile, 'utf8');
+  const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/);
+  const descMatch = html.match(/<meta\s+name="description"\s+content="([^"]+)"/);
+  if (!titleMatch || !descMatch) return '';
+
+  const headline = titleMatch[1].trim();
+  const description = descMatch[1].trim();
+  // ... compute url, build schema object, return JSON-LD script tag
+}
+```
+
+The script runs on the source HTML before any other build scripts have fired, so `<title>` and `<meta name="description">` are always present as written.
+
+### data-bascik-dev
+
+Tag a browser script with `data-bascik-dev` to mark it as dev-only. In development the attribute is stripped and the script runs normally in the browser. In production builds (`bascik --build`) the entire script tag is removed.
+
+```html
+<script data-bascik-dev>
+  console.log('dev only: stripped from production build');
+</script>
+```
+
+Useful for debug logging, development overlays, or any browser script that should never ship to production.
+
+> **dev vs. build:** `data-bascik-build` executes at transpile time and injects HTML into the page. `data-bascik-dev` runs in the browser, but only in dev mode.
+
+### Dynamic Routes (data-bascik-routes)
+
+Dynamic routes allow you to generate multiple static HTML files from a single template at build time. Use square brackets in the template filename (such as `src/pages/blog/[slug].html` or `src/pages/[category]/[id].html`) and include a `<script data-bascik-routes>` block:
+
+```html
+<!-- src/pages/blog/[slug].html -->
+<script data-bascik-routes>
+  const posts = [
+    { slug: 'hello-world', title: 'Hello World' },
+    { slug: 'second-post', title: 'Second Post' }
+  ];
+  const routes = posts.map(p => ({
+    params: { slug: p.slug },
+    data: p
+  }));
+  console.log(JSON.stringify(routes));
+</script>
+
+<script data-bascik-build>
+  const { params, data } = JSON.parse(process.env.BASCIK_ROUTE || '{}');
+  console.log(`<h1>${data.title}</h1>`);
+</script>
+```
+
+Rules:
+* Script must output a valid JSON array of route objects with required `params` (matching all bracket names in the template path) and optional `data`.
+* Route parameters must be URL-safe tokens; characters like `#`, `%`, `&`, `'`, `+`, spaces, leading dots, and Windows device names are disallowed.
+* In build scripts, `process.env.BASCIK_ROUTE` provides the current `{ params, data }` payload.
+* Dynamic route templates are expanded into concrete static HTML files during `bascik --build` and dev server startup. Route collisions with static pages or other templates cause build errors.
+* Concrete route URLs are automatically added to `sitemap.xml` with percent-encoding.
+* `data-bascik-routes`, `data-bascik-build`, `data-bascik-server`, and `data-bascik-stream` are mutually exclusive and cannot be combined on the same tag.
+
+### data-bascik-server
+
+Tag a `<script>` block with `data-bascik-server` to run it **at request time** on the server. Server scripts execute in-process via `ScriptRegistry` on every request; handler results are not cached, but loaded modules are reused. Use them to personalize pages per visitor, reading cookies, querying a database, rendering content based on query parameters. All `data-bascik-server` scripts on a page resolve before the response is sent, returning a complete buffered response with `Content-Length`.
+
+```html
+<script data-bascik-server>
+  import { escape } from '@/lib/server.ts';
+
+  export default function (request) {
+    const name = escape(request.headers.get('x-display-name') ?? 'Guest');
+    return `<p>Welcome, ${name}!</p>`;
+  }
+</script>
+```
+
+Handlers receive `(request, context, { signal })`:
+
+* `request`: standard WHATWG `Request`, identical to API routes (`request.method`, `new URL(request.url).searchParams`, `request.headers.get(...)`)
+* `context`: `{ remoteIp }`
+* `{ signal }`: standard `AbortSignal` for timeouts and client disconnects
+
+> **Escaping gotcha:** Bascik does not escape output and ships no escaper. Output is raw HTML by contract. Write a five-line escaper in `src/lib/server.ts` or install `escape-html`. Untrusted data includes anything from `request`, database rows containing user input, and third-party APIs.
+
+| Sink | Correct treatment |
+| :--- | :--- |
+| Text between tags / Quoted attribute | HTML entity escape (`& < > " '`) |
+| Unquoted attribute | Never do this; quote the attribute |
+| `href`, `src`, `action` | Validate URL (`new URL(v, base)`), allow-list `http:`/`https:` (entity escaping does not stop `javascript:`) |
+| Inline `<script>` / `on*` attributes / `<style>` | Never interpolate untrusted data (use `data-*` attributes for static client scripts) |
+| Already-rendered HTML | HTML sanitizer at data layer |
+
+Rules:
+* Top-level `import` and `await` are supported.
+* `data-bascik-server` blocks are stripped from emitted HTML into a sidecar file (`dist/.bascik/server-scripts.json`) leaving an inert placeholder (`<script type="text/bascik-server">`), so Node server source is never shipped to browsers in static builds.
+* When served with `bascik --server` or the dev server, the sidecar is loaded and scripts execute in-process on each request.
+* They are NOT executed during `bascik --build` itself.
+* Execution is bounded by `scripts.timeout` in `bascik.config.ts`.
+* On error, behavior is governed by `scripts.onServerScriptError` (`'error'`, `'warn'`, or `'ignore'`). Under `'error'`, the request halts and returns an HTTP 500. Under `'warn'`, the error is logged and the tag is replaced with an empty string without failing other scripts or the page.
+* In-process caveat: synchronous blocking code blocks Node's single-threaded event loop and cannot be interrupted by timeouts; always use async APIs.
+
+#### Request Module Lifetime
+
+* Node retains evaluated ESM identities, including old development generations, until process exit. Clearing framework caches does not reclaim them; release authored timers and resources explicitly and keep request-specific data in handler arguments.
+* Inline `server` and `stream` loads use weak script-job owners. Replacing a page does not retain its inline source history globally; accepted requests can finish using their old jobs without publishing loads into the replacement page.
+* In development, generations of literal file imports contribute to inline module identity. Tracked helper edits reload affected inline modules, while unrelated edits preserve singleton state. Computed imports do not gain this guarantee; watcher and tracked-root limits still apply. Production uses stable identities and immutable releases.
+
+### data-bascik-stream
+
+Tag a `<script>` block with `data-bascik-stream` to run it at request time with chunked HTTP streaming. It uses the exact same authoring model as `data-bascik-server` (`export default async function (request, context, { signal })`, in-process execution, sidecar registry, and stack remapping). The only difference: the server does not wait for it. Response headers and all static HTML bytes preceding the tag are sent immediately. When the script resolves, its returned markup is written in document order via chunked transfer.
+
+```html
+<script data-bascik-stream>
+  import { escape } from '@/lib/server.ts';
+
+  export default async function (request, context, { signal }) {
+    const data = await loadData(request, signal);
+    return `<article>${escape(data.title)}</article>`;
+  }
+</script>
+```
+
+Decision rule:
+* Use `data-bascik-server` when the output must be present before anything is sent, or when a failure must be an HTTP 500.
+* Use `data-bascik-stream` when the page shell and static layout should paint while this slow block loads.
+
+Rules & Gotchas:
+* **Mixed-page ordering:** All `data-bascik-server` scripts on the page resolve first. If any `server` script fails under `onServerScriptError: 'error'`, the response aborts with an HTTP 500 before any bytes are sent. Once all `server` scripts resolve, headers commit and `stream` chunks flow in document order. A slow `data-bascik-server` script on a page that also streams delays the first byte for the whole page.
+* **Error handling:** A `stream` script failure can never produce an HTTP 500 because headers are already committed. The slot emits an empty string, the error is logged at the configured `scripts.onServerScriptError` severity (with the dev overlay under `'error'`), and the document streams to completion.
+* **Header consequences:** Stream pages use `transfer-encoding: chunked` on HTTP/1.1 (DATA frames on HTTP/2) with `cache-control: private, no-store`. They omit `content-length`, `etag`, and Brotli `content-encoding`. `HEAD` requests always take the buffered execution path and execute the scripts.
+* **No config key:** There is no configuration key for streaming. Opt in per script with `data-bascik-stream`; opt out by using `data-bascik-server`.
+* **Zero-CLS Placeholders:** Everything the author writes before a `stream` tag is delivered and painted before the script runs. Use a component with a reserved-size container (`min-block-size` or `aspect-ratio`), `aria-busy`/`role="status"`, and either a one-cell grid stack (`grid-area: 1 / 1`) or a `:has(> .result)` rule to swap the placeholder visually. Bascik adds no CSS or JS for this. Put slow `stream` blocks last in source and place them with `grid-template-areas` or `order` so the rest of the layout paints first.
+* Note that code examples are illustrative; adjust module paths and database queries to your project.
+
+---
+
+## 9. Configuration (`bascik.config.ts`)
+
+Bascik is **zero-config by default**. Start without `bascik.config.ts`. Create one only after identifying a concrete requirement that differs from built-in behavior, such as `generate.sitemapLastmod`, an existing custom `exec` build script, or a non-default production minification override. `bascik --build` and `bascik --server` already enable HTML, CSS, JavaScript, and identifier minification.
+
+Use `bascik.config.ts` (preferred) or `bascik.config.js` (takes precedence if both exist). Import `defineConfig` for full editor autocomplete and inline docs.
+
+### Configuration is validated at startup
+
+Bascik validates the config before anything reads it and reports every problem together: each error names the key, the received value, and the expectation. Unknown keys are rejected with a "did you mean" suggestion, so a typo like `minfy:` or `directroy:` fails loudly instead of being silently ignored. Referenced paths (`directory.pages`, `pipeline.exec[].script`, `pipeline.watchPaths`, `assets.inlineStyles`, TLS key/cert files) are checked for existence. `base` is normalized to a leading and trailing slash (`docs` becomes `/docs/`); only a full URL is rejected.
+
+`base` defaults to `/`, which is a complete output and routing no-op. A non-root value such as `/docs/` rewrites root-relative HTML, CSS, and web app manifest URLs, serves dev and production-server requests below that prefix, and is included in sitemap, robots, and canonical URLs. Requests outside the prefix return `404`. Bascik does not rewrite URLs constructed in JavaScript; emit `BASCIK_BASE` from a build script when client code needs the prefix.
+
+### The site URL is not a config key
+
+`siteUrl` is a per-deployment value, so it never goes in `bascik.config.ts` (setting it there is an error). Three sources, in precedence order:
+
+```text
+--site-url flag  >  BASCIK_SITE_URL env var  >  .env file
+```
+
+The value must be an absolute `http` or `https` URL. Bascik loads `./.env` automatically (silently skipped when absent); `--env-file <path>` is repeatable with later files winning, and a missing explicit file is an error. A real environment variable always beats a file value. When `generate.sitemap` or `generate.robots` is enabled (both default to `true`) and no source provides the URL, the build fails with a message showing all three ways to set it.
+
+### Create a Config Only for a Non-Default Requirement
+
+Do not create `bascik.config.ts` preemptively. When a verified non-default requirement makes one necessary, include only that setting:
+
+```ts
+// bascik.config.ts (minimal example)
+import { defineConfig } from '@bascik/bascik/config';
+
+export default defineConfig({
+  generate: { sitemapLastmod: true },
+});
+```
+
+### Anti-Pattern: Defaults-Only Configuration
+
+Create `bascik.config.ts` only when a value differs from the default. If the configuration file would contain only defaults, **do not create the file**.
+
+```ts
+// DO NOT write this. Every value here is already the default for `bascik --build`.
+export const build = {
+  minify: true,
+};
+```
+
+### Full Configuration Reference (Built-In Defaults)
+
+You do not need to populate default options in `bascik.config.ts`. The reference below displays all available configuration options populated with their built-in default values for illustrative purposes only:
+
+```ts
+// bascik.config.ts (reference showing all default values)
+import { defineConfig } from '@bascik/bascik/config';
+
+export default defineConfig({
+  directory: {
+    pages: 'src/pages',
+    components: 'src/components',
+    out: 'dist',
+    api: 'src/api',
+  },
+  scoping: {
+    scriptBlocks: true,
+    inheritAttributes: true,
+    attributes: {
+      class: true,
+      id: true,
+      name: true,
+    },
+    preserve: ['code'],
+    deduplicateCss: true,
+  },
+  minify: {
+    html: false,
+    css: false,
+    js: false,
+    identifiers: false,
+  },
+  assets: {
+    inlineStyles: false,
+    exclude: [],
+  },
+  generate: {
+    sitemap: true,
+    robots: true,
+    sitemapLastmod: false,
+    cspHashes: false,       // writes dist/.bascik/csp-hashes.json with exact sha256 hashes for inline blocks
+    manifest: false,
+  },
+  pipeline: {
+    watchPaths: [],
+    exec: [],
+    workers: false,
+  },
+  scripts: {
+    cache: { enabled: true },
+    typescript: true,
+    onBuildScriptError: 'error',
+    onRoutesScriptError: 'error',
+    onServerScriptError: 'error',
+    timeout: 30000,
+    importRoot: 'src',      // directory that @/ and / script imports resolve against
+  },
+  onMinifyError: 'warn',
+  http: {
+    port: undefined,
+    hostname: 'localhost',
+    tls: {
+      enabled: false,
+    },
+    rateLimit: true,
+    trustProxy: false,
+    cacheControl: 'public, max-age=3600',
+    compression: true,
+    maxBodySize: 1048576,
+    apiTimeout: 10000,
+  },
+  logging: {
+    level: 'info',
+    requests: true,
+    copies: true,
+    deletes: true,
+    transpiles: true,
+  },
+  base: '/',
+});
+```
+
+> **Reverse Proxy & CDN Note (`trustProxy`):** When deploying `bascik --server` behind a CDN or load balancer, set `http.trustProxy: true` in `bascik.config.ts`. This ensures per-IP rate limiting and HSTS headers accurately resolve the client from `X-Forwarded-For` and `X-Forwarded-Proto`. Do not enable `trustProxy` if the server is exposed directly to the Internet without a reverse proxy.
+
+> **Health Endpoints & Port Conflicts:** `bascik --server` provides `GET /_health` (returns 200 when ready, 503 during boot or drain). Under `--server`, port conflicts (`EADDRINUSE`) fail fast rather than binding an unexpected port.
+
+> **Live Reload & Error Overlay:** In dev mode, live reload uses SSE with periodic comment heartbeats to survive proxies. Build errors surface directly in an in-browser overlay (`data-testid="bascik-build-error-overlay"`) and clear on the next successful build. Live reload scripts never ship to production.
+
+> **Watch Mode & Config Changes:** Changes to `bascik.config.ts` require a server restart because configuration is deep-frozen at boot time. Bascik prints a restart hint when config files change.
+
+> **Content Security Policy (CSP):** Bascik does not set a `Content-Security-Policy` header. Enable `generate.cspHashes: true` to generate SHA-256 hashes of all inline styles and scripts, and apply the CSP header at your host or reverse proxy.
+
+### Agent Guidelines for Configuration
+
+When creating or modifying `bascik.config.ts`:
+* **Do not create a config without a verified need:** Bascik is zero-config by default. Before creating `bascik.config.ts`, identify the exact requested behavior and verify that it differs from a built-in default. If no such requirement exists, omit the file entirely.
+* **Keep `bascik.config.ts` minimal:** Do NOT add redundant default options like `directory: { pages: 'src/pages', components: 'src/components' }`, `scoping.scriptBlocks: true`, `scoping.inheritAttributes: true`, `scoping.deduplicateCss: true`, `pipeline.watchPaths: []`, or empty `pipeline.exec` arrays. Never add an all-`true` production minification block because `bascik --build` and `bascik --server` already apply those values. Include only options that differ from defaults.
+* **Monorepo layout:** `directory.pages`, `directory.components`, and `scripts.importRoot` are three independent directories that never need a common parent. `directory.components` accepts `string | string[]`; every listed root is scanned, watched, and known to `--check`, and roots may point outside the project (for example `components: ['../../shared/components', 'src/components']` with `scripts: { importRoot: '../../shared/scripts' }`) so several Bascik sites in one repository share components and script helpers with no copying while each keeps private components. Component names must be unique across ALL roots (filename-derived tags; duplicates are a build error, never shadowed), roots may not be nested inside one another, and duplicate roots (including via symlink) are rejected. `bascik add` copies into the first listed root. See `/how-to/monorepos`.
+* **Package.json `"type": "module"` and NPM scripts:** When initializing or configuring a Bascik project, ensure `package.json` specifies `"type": "module"` (since `bascik.config.ts` uses ES module imports) and includes standard npm scripts (`"dev": "bascik"`, `"build": "bascik --build"`, `"check": "bascik --check"`).
+* **Proactively decompose shared layout components:** When creating or migrating a site, identify repeating layout sections (especially shared `<head>` tags such as `<site-head>`, site headers, and footers) and extract them into reusable components.
+* **Prefer self-closing void syntax for components without slots:** Use self-closing void syntax (`<site-head />`, `<site-nav />`, `<site-footer />`) for any component tag that does not enclose inner slot content.
+* **Do NOT invent non-existent `pipeline.exec` scripts:** `pipeline.exec` is only for executing existing custom lifecycle script files. If no custom script file exists in the workspace, omit it.
+* **Array Replacement in `build`:** Array properties like `pipeline.exec`, `pipeline.watchPaths`, and `assets.inlineStyles` are replaced as atomic values (not concatenated) when specified in `export const build`. When defining `build.pipeline.exec`, include all scripts that should run in production builds.
+* **Write artifacts to `dist/`:** Lifecycle scripts must write generated artifacts only to the output directory, never source files or watched paths. Never configure `pipeline.watchPaths` or `pipeline.exec[].watch` for generated outputs. There is no `outputs` option. Exec receives `BASCIK_BUILD`, `BASCIK_PAGES_DIR`, `BASCIK_OUT_DIR`, `BASCIK_BASE`, and `BASCIK_SITE_URL`. Use `pre` for required generated dependencies, not `parallel`.
+* **Source-owned exec phases:** `pipeline.exec[].watch` selects matching scripts after a source edit. One cycle coalesces overlap with pages, components, and `pipeline.watchPaths`: pre finishes before compilation, parallel starts alongside it, post starts after compilation and disk writes. Known source dependents rebuild once; unknown external dependencies conservatively rebuild all pages without rerunning unmatched scripts. Exec-only inputs need no duplicate `pipeline.watchPaths`. Completion never queues another compile or reload. Edits during work are retained; failed paths retry on the next source edit. Pre/compile/post failures discard success reloads. Dev parallel stays nonblocking and reports every failure; build joins parallel and compilation/post before success. Never suppress watched script edits as presumed self-writes. Bascik cannot safely identify source-writing loops. `scripts.importRoot` and `assets.inlineStyles` do not add compilation watches.
+* **Stick to recommended defaults without restating them:** Preserve `scoping.deduplicateCss: true`, `scoping.scriptBlocks: true`, and `scoping.inheritAttributes: true` unless specifically instructed otherwise or integrating global utility frameworks like Tailwind CSS. Do not write these values into a config just to preserve them.
+* **Set `BASCIK_SITE_URL` for production features:** Provide the site URL via the environment (e.g. `BASCIK_SITE_URL=https://example.com bascik --build`) when page-aware canonical scripts, sitemaps, or `robots.txt` generation are enabled. Never put `siteUrl` in `bascik.config.ts`.
+* **Use `base` for subdirectory deployments:** Set a literal path prefix such as `base: '/docs/'`. Do not include a query, fragment, percent escape, backslash, or dot segment, and do not use a full URL. Bascik does not rewrite paths assembled inside JavaScript; use the build-time `BASCIK_BASE` value for those paths.
+
+**`minify.js`:** `true` (default) strips comments and collapses whitespace; it does not mangle identifiers. Pass a custom async function to plug in esbuild or terser. The function always receives valid JavaScript (browser TypeScript on supported paths is stripped first) and Bascik re-attaches its own `//# sourceURL` directive on a fresh line after the function returns, so minifiers that drop comments are safe:
+
+```ts
+import { transform } from 'esbuild';
+import { defineConfig } from '@bascik/bascik/config';
+
+export const build = defineConfig({
+  minify: {
+    js: async (js) => (await transform(js, { minify: true, loader: 'js' })).code,
+  },
+});
+```
+
+---
+
+## 10. Folder Structure, Static Assets, 404, and 500 pages
+
+```
+src/
+  components/           ← component .html (+ optional .css) templates
+  pages/                ← HTML routes and publishable assets
+    index.html          → dist/index.html
+    css/styles.css      → dist/css/styles.css (auto-minified)
+    js/main.js          → dist/js/main.js (auto-minified)
+    images/logo.svg     → dist/images/logo.svg
+    404.html            → dist/404.html
+```
+
+### Static Assets and Subdirectories
+* **One Publish Tree:** Put images, fonts, downloads, standalone browser JavaScript, CSS, and other public assets under `directory.pages`. Colocate them with a route or use shared subdirectories such as `src/pages/assets/`. Eligible files copy to `directory.out` with relative structure preserved.
+* **Project-Specific Exclusions:** `assets.exclude` adds glob exclusions matched relative to `directory.pages`. Keep tests and source-only helpers outside the publish tree.
+* **Auto-Minification:** CSS and JS files placed in `src/pages/` are automatically minified by `bascik --build` and `bascik --server`; no config is required. Custom BYOMinifier minifier/transformer functions (e.g. PostCSS/Autoprefixer, LightningCSS, esbuild, terser) can be assigned to `minify.css` and `minify.js` only when a project needs non-default processing.
+* **Built-In Deny-List:** Dotfiles, dot-directories, `node_modules`, `.html`, `.ts`, `.mjs`, `.cjs`, `.mts`, `.cts`, `.map`, `.md`, test/spec files, and inlined stylesheets never copy. This deny-list always applies, including when `assets.exclude` is configured.
+* **External Copying:** When assets must come from a separate source tree, use a `pipeline.exec` script that writes intentionally selected files to `directory.out`.
+
+### Custom 404 & 500 Error Pages
+* **404 Page (`src/pages/404.html`):** Picked up automatically by path convention in the dev server and under `bascik --server` as a fallback for any non-existent routes (with a 404 status code). When built with `bascik --build`, it compiles to `dist/404.html`, which static hosting platforms (GitHub Pages, Cloudflare Pages, Netlify, Vercel) recognize and serve automatically.
+* **500 Error Pages in Static vs. Server Contexts:**
+  * **Static builds (`bascik --build`):** A 500 error page is meaningless in a fully static build, because static web hosts serve their own error pages if an infrastructure or server issue occurs. Do not port a 500 error page from Next.js, Remix, or any server-rendered framework into a static Bascik site.
+  * **Production server (`bascik --server`):** Custom `src/pages/500.html` support under `bascik --server` is convention-based with no config key. When an unhandled error occurs, `src/pages/500.html` is served with status 500 and security headers, falling back to a built-in minimal document when absent. Static hosts serve their own error pages.
+
+---
+
+## 11. CLI & Development Workflow
+
+### Scaffold a New Project
+
+The zero-friction way to start a new Bascik project:
+
+```sh
+npm create bascik@latest my-site -y
+```
+
+This scaffolds the project, installs dependencies, and starts the dev server in one shot. You're live at **http://localhost:8080**. Pass a different name to use it as both the directory name and the site title. Omit the name to be prompted for one (defaulting to `bascik-app`). Drop `-y` to step through the install and dev server prompts manually.
+
+The scaffold creates a complete starter site: pages, components with unit tests, Playwright E2E browser tests, global CSS, `.vscode/extensions.json` (recommends the official Bascik extension), and AI assistant skills at `.github/skills/bascik/SKILL.md` and `.claude/skills/bascik/SKILL.md`. It includes a `lint` script in `package.json` powered by `@bascik/language-server` (`npm run lint`), and omits `bascik.config.ts` because the starter uses Bascik's built-in defaults. When the dev server stops, the CLI prints a reminder:
+
+```
+To start again:  cd my-site && npm run dev
+```
+
+### Adding to an Existing Project
+
+```sh
+npm install @bascik/bascik
+```
+
+Then run `bascik init` to scaffold starter files (`src/pages/index.html`, `src/components/`), append `.gitignore` entries (`dist/`, `node_modules/.cache/bascik/`), and patch `package.json` (`"type": "module"` when absent plus standard scripts and dependency), or add the scripts manually to `package.json`:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "bascik",
+    "build": "bascik --build"
+  }
+}
+```
+
+### CLI Commands
+
+```sh
+bascik                        # dev: transpile, start plaintext HTTP server at http://localhost:8080, watch
+bascik --build                # production: transpile to dist/ only
+bascik --build --log [path]   # write build output to a log file (default: .bascik/build.log; only valid with --build)
+bascik --build --only <glob>  # targeted build: rebuild matching pages only without cleaning dist/ (repeatable)
+bascik --server               # production server: serve a pre-built dist/ folder
+bascik --check                # static analysis: validate pages, components, and config without building
+bascik add <package>          # copy-in components from an installed npm package into src/components/
+```
+
+More flags: `--config <path>` (load a specific config file), `--port <n>`, `--host <name>`, `--log-level <silent|error|warn|info|debug>`, `--site-url <url>`, `--only <glob>` (repeatable, only with `--build`), `--force` (overwrite locally modified components during `add`), `--dry-run` (preview what `add` would copy), `--yes`/`-y` (skip interactive prompts during `add`), and `--env-file <path>` (repeatable). Every value flag accepts both `--flag value` and `--flag=value`. Precedence: a flag beats the environment variable (`BASCIK_SERVER_PORT`, `BASCIK_SERVER_HOST`, `BASCIK_LOG_LEVEL`), which beats the config file. The parser rejects `--build` combined with `--server`, `--only` without `--build`, unknown flags, and stray positionals: `bascik build` (no dashes) errors with a `Did you mean "--build"?` suggestion instead of silently starting the dev server.
+
+**`bascik add`:** copies components from an installed npm package into `src/components/`. Files are **project files** committed to version control, not resolved runtime dependencies. Component tag names derive from filenames; if a package component collides with an existing project component, `bascik add` refuses to write anything and reports both paths. `bascik add` maintains a `bascik-lock.json` file in the project root with file hashes. Unmodified files update cleanly on re-add; locally modified files are never overwritten without `--force`.
+
+**Gotchas with `--only`:** Targeted builds skip cleaning `directory.out` so existing compiled pages survive. Sitemap and robots generation is skipped with a warning to avoid delisting unbuilt pages. Artifacts (`dist/.bascik/manifest.json`, `dist/.bascik/csp-hashes.json`) merge updated entries into existing files.
+
+**`bascik --build --target <name>`:** also emits a serverless deployment bundle under `dist/.bascik/<name>/` (`cloudflare`, `cloudflare-workers`, or `cloudflare-pages`). The normal `dist/` is unchanged. The bundle has a `public/` upload tree (static files plus the generated Worker and routing) and compiles every server script, stream script, API route, and dynamic page template into the Worker; dynamic templates are never in `public/`, so a routing miss is a 404, not inert placeholders. Official targets resolve to `@bascik/adapter-cloudflare` (`npm install --save-dev @bascik/adapter-cloudflare`). Rejected with `--only`. Unsupported `node:*` imports (for example `node:child_process`) fail the build with the import chain. Streamed pages are sent with `Content-Encoding: identity` so the edge does not buffer them. See the Cloudflare deployment guide.
+
+**`bascik --server`:** starts the production server against a pre-built `dist/` directory (HTTP/1.1 by default; HTTP/2 when TLS is enabled). **Needed when the site uses `data-bascik-server` or `data-bascik-stream` scripts or API routes (`src/api/`)** for per-request dynamic content, unless you deploy a serverless bundle instead. Sites with only static pages and none of those can be deployed to any static host. Run `bascik --build` first, then `bascik --server`. Unlike the dev server, `--server` does not watch files or inject live-reload. `data-bascik-server` scripts and API routes execute per-request in both modes.
+
+### API Routes (`src/api/`)
+
+Define HTTP endpoints in TypeScript/JavaScript files under `src/api/` (`directory.api`). Handlers take a standard WHATWG `Request` and return a standard `Response`:
+
+```ts
+// src/api/contact.ts
+export const POST = async (request: Request): Promise<Response> => {
+  const data = await request.json();
+  if (!data.name) return Response.json({ error: "name is required" }, { status: 400 });
+  return Response.json({ ok: true }, { status: 201 });
+};
+```
+
+* **Method exports:** `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD`. Unexported methods return `405 Method Not Allowed` with an accurate `Allow` header.
+* **Derived HEAD & Auto OPTIONS:** `HEAD` auto-derives from `GET` (headers only, body stripped); `OPTIONS` auto-responds 204 with `Allow`.
+* **Context argument:** `(request, { params, remoteIp }, { signal })`. Route params are parsed from `[param]` segments. `remoteIp` is proxy-aware when `http.trustProxy` is true. `signal` provides cooperative abort on `http.apiTimeout`.
+* **Streaming request body:** `request.body` is a WHATWG stream with `duplex: 'half'`. Handlers call `.json()`, `.text()`, etc. `http.maxBodySize` (default 1 MB) counts streamed bytes and aborts with 413 without memory buffering.
+* **Security & secrets:** Handlers run in-process with access to `process.env`. Handler source files in `src/api/` are never served or copied to static builds. Thrown errors return 500 with zero stack/path info leaked to clients. No CORS headers are added by default.
+* **Portability:** The handler function is reusable because it takes a standard `Request`, but routing, method dispatch, and imports still need a host. Bascik supplies all three on `bascik --server` and on the Cloudflare target (`bascik --build --target cloudflare|cloudflare-workers|cloudflare-pages`, see below). Other hosts are manual porting: write the platform wrapper yourself.
+* **`context.platform`:** optional host capabilities. `{ name: "node" }` on the built-in server; `{ name: "cloudflare", env, waitUntil }` in a generated Worker, where `env` carries KV/D1/secrets bindings. Never copied to globals; a handler that ignores it runs unchanged everywhere.
+* **Gotchas:** Plain static builds (`bascik --build`) cannot serve API routes and warn at build time; add `--target <name>` to package them into a serverless bundle. Handlers run in-process on the server; synchronous infinite loops cannot be interrupted by timers. No automatic compression or CORS headers are added by default.
+
+**`http` config block:** configure the server in `bascik.config.ts`:
+```ts
+export default {
+  http: {
+    port: 8080,            // default (8080 HTTP, 8443 HTTPS)
+    hostname: 'localhost', // set '0.0.0.0' to bind all interfaces
+    httpCache: true,       // default in --server; false in dev
+    tls: {
+      enabled: false,      // default; set true for HTTP/2 HTTPS
+      keyFile: 'bascik-privkey.pem',
+      certFile: 'bascik-cert.pem',
+    },
+  },
+};
+```
+When `tls.enabled: true` is set, TLS certs are generated automatically (mkcert if available, openssl fallback) when `keyFile`/`certFile` are absent. Provide your own certs from a public CA for production.
+
+**`http.httpCache`:** defaults to `true` in `--server` and `false` in the dev server. When `true`: pages and static assets receive strong SHA-256 content-hash `ETag` headers (not mtime-derived, so identical bytes produce identical ETags across separate server instances/replicas) and the server returns `304 Not Modified` for unchanged content, carrying `vary` and `cache-control`. Set `false` if a CDN manages caching externally.
+
+**`http.cacheControl`:** a string (applied to every static asset) or a per-extension map, e.g. `{ '.woff2': 'public, max-age=31536000, immutable', '.png': 'public, max-age=86400' }`. Unmapped extensions fall back to the default `public, max-age=3600`. Only pair `immutable` with a URL whose content cannot change (in practice, a fingerprinted filename).
+
+**`http.compression`:** negotiates Brotli or Gzip based on `Accept-Encoding`. Static HTML pages are pre-compressed with both Brotli and Gzip in the background at startup; static assets negotiate Brotli or Gzip with sidecar support (`.br`/`.gz`). Compression is skipped below a size threshold and for already-compressed formats (images, video, audio, archives, `woff2`). Each encoded representation gets a distinct ETag from the identity representation (e.g. `"hash-br"`, `"hash-gz"`).
+
+**Production hardening (automatic in `--server`):**
+* **Security headers:** every response includes `x-content-type-options: nosniff`, `x-frame-options: SAMEORIGIN`, `referrer-policy: strict-origin-when-cross-origin`, `permissions-policy: interest-cohort=()`. When serving over HTTPS/TLS (`enableTls: true` or `x-forwarded-proto: https`), `strict-transport-security: max-age=31536000; includeSubDomains` (HSTS) is automatically included per RFC 6797.
+* **URL routing (dev and production):** pages are served at their filename without the `.html` extension. `dist/about.html` is at `/about`, `dist/blog/post.html` is at `/blog/post`, `dist/index.html` is at `/`. Unmatched paths fall through to `/404` if a `dist/404.html` exists.
+* **Rate limiting:** 500 requests per 10 seconds per IP. Clients over the limit get `429 Too Many Requests` with `Retry-After`. Not active in the dev server. When behind a reverse proxy the limit applies to the proxy's IP; use the proxy's own rate limiting for per-client control.
+* **Graceful shutdown:** SIGTERM and SIGINT mark readiness as draining, stop accepting connections, start registered cleanup handlers, and close protocol resources. If the server has not closed within `http.timeouts.drain` (default 5000 ms), Bascik force-exits with a nonzero status.
+* **Path traversal protection:** static asset URLs are validated against `dist/`; requests that escape with `/../` sequences get `400 Bad Request`.
+* **Hidden-path protection:** after URL decoding, any request path containing a segment that starts with `.` gets `404 Not Found` before static file lookup.
+
+**Deployment:** Bascik's server runs over unencrypted HTTP/1.1 by default. Edge platforms (Heroku, Fly.io, AWS ECS, Render) that terminate TLS at the load balancer can forward cleartext HTTP directly to the container. Always run production servers under a process supervisor (systemd, Docker restart policy, or Kubernetes supervisor) as Bascik's process-level crash net terminates with a non-zero exit code on unhandled errors to avoid undefined state. Key patterns:
+
+* **VPS / dedicated**: bind `hostname: '0.0.0.0'`, supply Let's Encrypt certs via `keyFile`/`certFile` with `enableTls: true`, run as a `systemd` service with `Restart=on-failure`.
+* **Docker**: multi-stage build (build stage: `npx bascik --build`; serve stage: `npx bascik --server`) with `--restart=unless-stopped`.
+* **PaaS (Railway, Render, Fly.io)**: set start command to `bascik --build && bascik --server` and bind port `8080`.
+
+When using a reverse proxy, forward `X-Real-IP` and any auth headers so `data-bascik-server` scripts receive them via `request.headers` or `context.remoteIp`.
+
+### Development Workflow & Server Output
+Bascik's CLI is designed to provide clean, minimal, and informative terminal output.
+
+#### 1. Starting the Dev Server
+When you start the dev server, Bascik starts the HTTP server concurrently with page transpilation so the server is already bound to its port by the time the last page finishes. The `Server running at` line prints immediately after the transpilation summary with no gap between them. Pages are served from memory with no disk I/O at request time in dev mode. If port 8080 is in use, Bascik automatically tries the next available port (8081, 8082, etc.).
+
+```terminal
+Starting transpiling...
+transpiled: pages/getting-started.html in 0.4ms
+transpiled: pages/index.html in 0.6ms
+transpiled: pages/about.html in 0.3ms
+
+✓ 3 pages transpiled in 45ms
+Server running at http://localhost:8080
+```
+
+On startup, Bascik cleans `directory.out` before pre-phase lifecycle scripts run, then computes the full component list and global styles **once** and transpiles all pages. By default pages transpile sequentially on the main thread; setting `pipeline.workers: true` in `bascik.config.ts` distributes them across a pool of CPU-core worker threads instead. Worker startup has a fixed cost (each worker loads the transpiler's module graph independently), so `pipeline.workers` is opt-in and best suited to larger sites or CPU-heavy per-page work, small sites are usually faster with the sequential default. Brotli and Gzip compression for each page runs in the background after storage and does not block the page from being marked ready or served; the server falls back to serving uncompressed content for any request that arrives before compression finishes. The server becomes ready as soon as memory is populated. In dev mode, Bascik stores each page in memory first, then writes its compiled HTML to `dist/` asynchronously. Serving never waits for that disk write.
+
+#### 2. Watching for File Changes (Watch Mode)
+While the dev server is active, Bascik watches your file system and incrementally updates your build as files are added, updated, or removed:
+
+* **Modifying/Adding Pages:** Editing or adding an HTML page in your pages directory (e.g., `src/pages/about.html`) triggers incremental transpilation of just that page:
+  ```terminal
+  transpiled: pages/about.html in 0.3ms
+  ```
+* **Modifying Components:** Editing a component (e.g., `src/components/site-nav/site-nav.html`) triggers selective transpilation. Bascik tracks dependency mappings and only rebuilds pages that actually reference that component:
+  ```terminal
+  transpiled: pages/index.html in 0.5ms
+  transpiled: pages/about.html in 0.3ms
+  ```
+* **Open-Page Prioritization:** When a batch rebuild is triggered (such as an inlined stylesheet or shared component), Bascik checks active live-reload browser connections and prioritizes compiling currently open pages first, emitting reload signals immediately before compiling background pages.
+* **Static Assets:** Replicating any non-HTML static assets (like custom CSS, JS files, or images) from pages directly into the output directory:
+  ```terminal
+  copied: pages/css/custom.css
+  ```
+* **Deleting Pages:** Removing a page from your pages directory automatically cleans up its compiled output counterpart to prevent dead files:
+  ```terminal
+  deleted file: pages/old-page.html
+  ```
+
+#### 3. Transpilation & Build Errors
+Development and production builds handle page failures differently. The dev server logs a failed page, completes boot, continues serving healthy pages, and retries the failed page on the next save. A production `bascik --build` waits for every page job, reports all failures together, and exits nonzero rather than reporting success with missing output.
+
+Hard build failures include a missing or unreadable configured pages directory, a page without a non-empty `<body>`, runaway component expansion, output directory creation failure, and page write failure. `ENOENT` write errors are not ignored.
+
+```terminal
+Build failed with 2 page errors:
+  src/pages/about.html
+    validate markup: Page does not contain a non-empty <body> element
+  src/pages/blog/post.html
+    write output: EACCES: permission denied
+```
+
+* **Component Transpilation Failure:** If a component markup or CSS scoping parser fails during transpilation:
+  ```terminal
+  [bascik] Transpilation failed for component <site-nav> during css-scoping in "pages/about.html" at (line 22, column 8)
+    Defined in component template: "components/site-nav/site-nav.html"
+    Error: ParseError: CSS Selector is invalid or could not be parsed.
+  ```
+* **Build Script Failure:** If a build-time JavaScript execution block (using `<script data-bascik-build>`) encounters an error:
+  ```terminal
+  [bascik] build script error in "pages/index.html" at (line 12, column 5):
+  ReferenceError: marked is not defined
+  ```
+* **Unknown Component Tags:** If a page references a hyphenated tag with no matching component file, Bascik warns during transpilation:
+  ```terminal
+  [bascik] Unresolved component tag in "pages/about.html": <my-mistyped> - no matching component file found. Run `bascik --check` for a full report.
+  ```
+  Use `bascik --check` (or `bascik --check --strict`) as the CI gate for project references and diagnostics.
+
+#### 4. Static Analysis (`bascik --check`)
+Run `bascik --check` from your project root to validate pages, component files, config, and API route files without starting the dev server or writing any output:
+
+```sh
+bascik --check
+```
+
+Bascik scans project sources and reports:
+* **Warnings (exit code 0):** Unmatched hyphenated tags (including third-party web components), unused component files, unknown `data-bascik-*` attributes, and component ordering conventions (`<style>` above markup, `<script>` below).
+  ```terminal
+  Components with no matching file (1)
+    These are either typos, or third-party web components. Bascik does not
+    transpile them; they are passed through to the browser unchanged.
+
+    <model-viewer>     src/pages/gallery.html:42
+  ```
+* **Errors (exit code 1):** Config validation failures, missing site URL for sitemap/robots generation, duplicate component names, circular component references, script mode conflicts (`data-bascik-build` + `data-bascik-server` on one tag), duplicate route resolution, API route files missing method handlers, API route collisions, and WHATWG HTML5 parse errors in compiled `dist/` HTML files (requires [parse5](https://parse5.js.org/) as a dev dependency; when parse5 is absent, `--check` prints a one-line install hint and does not fail).
+* **Strict mode:** Pass `--strict` to treat warnings as errors and exit with code `1`.
+* **JSON output:** Pass `--json` to output structured findings for CI integration. The JSON schema includes `distHtmlChecked` (number of `dist/` files parse5 validated, or `null`) and `distHtmlSpecHintNeeded` (`true` when parse5 is absent but `dist/` HTML exists).
+* **Success**: Exits with code `0` when no errors are found (or under `--strict` when no errors or warnings).
+
+`missing-required-prop` is intentionally not emitted. The cheap whole-project heuristic is noisy for real projects and creates speculative warnings.
+
+Run in CI:
+```sh
+bascik --check && bascik --build
+```
+
+**What `bascik --check` does not cover:** it does not replace CSS/JS syntax linting. Use external tools alongside `--check`:
+
+| Tool | What it catches |
+|---|---|
+| VS Code built-in CSS | CSS syntax errors (squiggly lines, no install needed) |
+| [Stylelint](https://stylelint.io) | CSS syntax, invalid properties, conventions |
+| [parse5](https://parse5.js.org/) | WHATWG HTML5 parse errors in compiled `dist/` output (`npm install -D parse5` then `bascik --check`) |
+| [HTMLHint](https://htmlhint.com) | HTML structure errors in `.html` files |
+| [ESLint](https://eslint.org) | JS syntax and logic errors in `<script>` blocks |
+
+Recommended CI pipeline with CSS validation:
+```sh
+npx stylelint "src/**/*.css" && bascik --check && bascik --build
+```
+
+#### Editor Configuration
+
+Editors validate all `<script>` blocks in an HTML file as sharing one scope, causing false "variable already declared" errors. Bascik wraps each block in an IIFE at build time, so the errors are false positives.
+
+**VS Code fix:** add `.vscode/settings.json`:
+```json
+{ "html.validate.scripts": false }
+```
+
+Commit this file so all contributors get the correct behavior automatically. Alternatively, add `// @ts-nocheck` as the first line inside any individual script block that triggers the warning.
+
+#### 5. Inspecting `dist/` Output
+
+Both `bascik --build` and dev mode (`bascik`) write compiled HTML and static assets to `dist/` on disk. Dev stores pages in memory before issuing asynchronous disk writes, so the server can return updated pages immediately while `dist/` remains available for inspection. The `dist/` structure mirrors `src/pages/` with the leading directory stripped:
+
+```
+src/pages/about.html       →  dist/about.html
+src/pages/blog/post.html   →  dist/blog/post.html
+```
+
+What to check in compiled output:
+* **Component resolution:** every custom tag (e.g. `<site-nav>`) should be replaced with expanded HTML. A hyphenated tag still present in `dist/` means no component file matched.
+* **Scoped class names:** attributes like `class="bascik__site-nav__nav"` (or a short hash with `minify.identifiers`) confirm CSS scoping ran correctly.
+* **Injected `<style>` block:** the `<head>` should contain one combined `<style>` with CSS from all components used on that page.
+* **Build script output:** `<script data-bascik-build>` is replaced with stdout; if missing, check the terminal for a `[bascik] build script error` line.
+* **Server script output:** `<script data-bascik-server>` is replaced at request time; if output is missing on a live request, check the terminal for a `[bascik] server script error` line. Remember these scripts run in Node.js, not the browser, they require `bascik --server` or the dev server to execute.
+* **Slot and prop values:** verify fallback and injected text appear in the right place.
+
+The browser's **View Source** (or DevTools **Sources** panel) is equivalent to reading `dist/` and is often faster during development.
+
+---
+
+## 12. JavaScript Libraries & Progressive Enhancement
+
+Bascik adds zero JavaScript to output pages by default, but places no restrictions on including external libraries.
+
+**Note for AI Assistants:** The integration patterns below (petite-vue, Alpine.js, Tailwind CSS) demonstrate how to combine Bascik with external runtime libraries. Do not add or configure these libraries unless the project explicitly uses them or the user requests them.
+
+### How to Include
+Add a CDN `<script src>` tag to the page `<head>` or a shared head component. Bascik passes external script tags through completely unchanged.
+
+**Bare specifiers do not work in client scripts.** Bascik does not rewrite `import x from 'some-package'` in a `<script type="module">`; the browser receives it verbatim and fails with `Failed to resolve module specifier`. Bare specifiers work only in `data-bascik-build` and `data-bascik-server` scripts, which run in Node.js. For an npm package with no CDN build, bundle it with esbuild as a `pipeline.exec` step (`phase: 'pre'`), write the bundle into `dist/assets/js/`, and import it from the page with a root-relative URL.
+
+```html
+<head>
+  <script src="https://unpkg.com/petite-vue" defer init></script>
+</head>
+```
+
+### petite-vue
+petite-vue (~5 KB) is a Vue-compatible progressive enhancement library. Declare `v-scope` on any element to give it isolated reactive state:
+
+```html
+<!-- src/components/my-counter.html -->
+<div v-cloak v-scope="{ count: 0 }">
+  {{ count }}
+  <button @click="count++">+</button>
+</div>
+```
+
+Load it once in the page `<head>` with `defer init` to auto-mount all `v-scope` elements:
+```html
+<script src="https://unpkg.com/petite-vue" defer init></script>
+```
+
+### Alpine.js
+Alpine.js uses `x-data` for state and `@click` / `x-show` for events and visibility:
+
+```html
+<div x-data="{ open: false }">
+  <button @click="open = !open">Toggle</button>
+  <p x-show="open">Hidden content.</p>
+</div>
+<script src="https://unpkg.com/alpinejs" defer></script>
+```
+
+### Tailwind CSS
+Tailwind utility classes are global by design. Bascik's class scoping would rename `class="flex gap-4"` to `class="bascik__comp__flex bascik__comp__gap-4"`, breaking Tailwind's CSS.
+
+**Required config:** disable class scoping in `bascik.config.ts`:
+```ts
+import { defineConfig } from '@bascik/bascik/config';
+
+export default defineConfig({
+  scoping: {
+    attributes: {
+      class: false, // let Tailwind utility classes pass through unchanged
+    },
+  },
+});
+```
+
+Include Tailwind via CDN (development) or Tailwind CLI (production):
+```html
+<script src="https://cdn.tailwindcss.com"></script>
+```
+
+With `class: false`, utility classes work normally inside any component:
+```html
+<!-- src/components/feature-card.html -->
+<div class="rounded-xl border border-gray-200 p-6 shadow-sm">
+  <h3 class="mb-2 text-lg font-semibold" data-bascik-prop-title></h3>
+  <p class="text-sm text-gray-600" data-bascik-prop-body></p>
+</div>
+```
+
+Trade-off: with `class: false`, Bascik no longer isolates component class names. IDs and names remain scoped independently.
+
+### HTMX, Stimulus, and Others
+* **HTMX:** Uses `hx-get`, `hx-post` attributes for server-driven partial updates.
+* **Stimulus:** Uses `data-controller` for attaching behavior to DOM structures.
+* **Chart.js, D3, Leaflet:** Mounts to elements via `getElementById`; Bascik rewrites the ID and matching selectors at build-time so they stay in sync.
+
+---
+
+## 13. Testing
+
+Bascik provides per-package commands and workspace-wide aggregators run from the root.
+
+### Monorepo Aggregators
+
+```sh
+yarn typecheck:all     # typecheck pkg, create, docs, ext
+yarn check:all         # spelling and web standards
+yarn unit:all          # unit tests across all packages
+yarn e2e:all           # Playwright E2E suites across all packages
+yarn coverage:all      # update coverage across all packages
+yarn test:all          # typecheck:all + check:all + unit:all + e2e:all + docs:lighthouse
+```
+
+### Unit Tests (Vitest)
+
+```sh
+yarn pkg:unit          # single run (@bascik/bascik)
+yarn pkg:test          # watch mode
+yarn create:unit       # create-bascik unit tests
+yarn docs:unit         # bascik-docs unit tests
+yarn ext:unit          # bascik-vscode unit tests
+yarn pkg:bench         # benchmarks
+```
+
+Each `pkg/src/lib/*.ts` module has a paired `*.test.ts`. Because modules depend on `BascikConfig` (a singleton), unit tests use `vi.mock('../config.ts', ...)` to stub configuration, then import the module under test **after** the mock call.
+
+### Runtime Profiling and Retention
+
+Use `yarn workspace @bascik/bascik profile:workload --report-dir <private-directory>` for bounded runtime captures, separate from throughput benchmarks. Replace the illustrative placeholder with a new, empty, absolute directory outside the repository and all served or watched trees; existing roots must be user-owned and mode `0700`. Run tools sequentially and keep manifests, profiles, and snapshots private.
+
+Captures require complete byte-checked work and valid artifacts, not merely exit code zero. Main-isolate CPU profiles do not establish worker or child-process coverage. Worker CPU recording is unsupported on Node v24.17.0/macOS; unprofiled workers remain available. Allocation samples do not prove reclamation: use the separate module-retention experiments and heap retainer paths described in the testing docs. Failed profiling tests retain private diagnostic paths; do not retry failures into success or infer Node ESM eviction from framework cache cleanup.
+
+### End-to-End Tests (Playwright)
+
+```sh
+yarn pkg:build                  # build package first
+yarn pkg:e2e                    # run static production suite
+yarn pkg:e2e:dev                # run dev server live-reload and watch suite
+yarn pkg:e2e:prod               # run both HTTP/1.1 and HTTP/2 production server suites
+yarn pkg:e2e:prod:http1         # run cleartext HTTP/1.1 prod server suite
+yarn pkg:e2e:prod:http2         # run TLS HTTP/2 prod server suite
+```
+
+The E2E suite lives in `pkg/e2e/` and supports four execution modes:
+1. **Static production suite (`playwright.config.ts`)**: builds the fixture site with `bascik --build` and serves static files via `server.ts` on port 4200.
+2. **HTTP/1.1 production server suite (`playwright.server.config.ts`)**: boots cleartext `bascik --server` over HTTP/1.1 on port 9443 to test `data-bascik-server` request-time script execution and cleartext server behavior.
+3. **HTTP/2 production server suite (`playwright.server-http2.config.ts`)**: boots TLS-enabled `bascik --server` over HTTP/2 on port 9444 to test `data-bascik-server` request-time script execution and encrypted server behavior.
+4. **Dev server watch suite (`playwright.dev.config.ts`)**: boots `bascik --dev` on port 8080 to run the full test suite and live-reload watcher tests directly against the live dev server with SSE tracking and open-page priority re-transpilation.
+
+Keep each mode's `testIgnore` list on its `default` project. Playwright project arrays replace matching top-level arrays instead of extending them, which can silently select server-only tests in the wrong mode. The config-selection unit test must cover all four project exclusion lists.
+
+The fixture config sets `minify.identifiers: false` so Playwright selectors can use readable scoped names like `bascik__my-comp__btn` instead of opaque hashes. However, in production builds (where `minify.identifiers: true` is enabled), Bascik compiles and minifies element IDs and class names. Consequently, relying on raw CSS selectors like `page.locator('.my-class')` or `page.locator('#my-id')` will fail because those identifiers are hashed and compressed.
+
+Choose locators by test intent:
+* **Behavior-oriented E2E tests:** Prefer accessibility-based locators such as `page.getByRole(...)`, `page.getByLabel(...)`, and `page.getByPlaceholder(...)`, or explicit `data-testid` attributes with `page.getByTestId(...)`. These locators remain stable when identifier minification changes classes and IDs.
+* **Compiler-output verification tests:** When the transformed selector or identifier is itself under test, deliberately assert generated scoped class names or rewritten IDs. Do not use a behavior-only locator as a substitute for asserting the compiler output that the test is meant to verify.
+
+**Adding a new e2e test:**
+1. Add a component in `pkg/e2e/src/components/my-feature/`
+2. Add a page in `pkg/e2e/src/pages/my-feature-test.html` with two or more instances (to verify isolation)
+3. Add `pkg/e2e/tests/my-feature.test.ts` using the standard pattern:
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test.describe('my-feature-test page', () => {
+  test.beforeEach(async ({ page }) => { await page.goto('/my-feature-test'); });
+
+  test('instances are isolated', async ({ page }) => {
+    const a = page.locator('.bascik__my-feature__wrapper').nth(0);
+    const b = page.locator('.bascik__my-feature__wrapper').nth(1);
+    // assert A and B are independent
+  });
+});
+```
+
+There are 44 e2e test files covering CSS scoping, JS scoping, slots, props, attribute inheritance, animations, observers, SVG, and head components.
+
+### Debugging with VS Code and Node.js
+
+Bascik works smoothly with debuggers because it operates directly on vanilla HTML, CSS, and JavaScript without complex runtime abstractions or heavy bundle transformations.
+
+#### Source Location Preservation
+
+Debugging server-side scripts, build-time scripts, and browser component code in Bascik requires no special source map plugins or transpilation step:
+
+* **Server and Build Scripts:** Bascik automatically appends `//# sourceURL=${relPath}` comments to temporary script modules created during compilation (`<script data-bascik-build>` and `<script data-bascik-server>`). Stack traces and debugger breakpoints point directly back to your original source file paths.
+* **Client Component Scripts:** Bascik preserves newline padding when scoping component `<script>` tags. Line numbers reported in console errors or hit during step-debugging match the exact line numbers in your component `.html` source files.
+* **Native TypeScript Debugging:** Because Node 22.18.0+ natively executes TypeScript files by stripping type annotations, setting breakpoints in `.ts` modules pauses execution immediately with full access to local scope variables and call stacks.
+
+#### Pre-Configured VS Code Launch Configurations
+
+Projects created using `npm create bascik@latest` include a pre-configured `.vscode/launch.json` file focused on testing and debugging your application. You can start debugging immediately by pressing `F5` or selecting a profile from VS Code's **Run and Debug** panel:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Dev Server",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["bascik"],
+      "console": "integratedTerminal",
+      "restart": true,
+      "skipFiles": ["<node_internals>/**"]
+    },
+    {
+      "name": "Debug Unit Tests",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["vitest", "run"],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"]
+    },
+    {
+      "name": "Launch Chrome",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:8080",
+      "webRoot": "${workspaceFolder}"
+    }
+  ]
+}
+```
+
+#### Debugging Server Scripts and Build Steps
+
+To debug server scripts (`<script data-bascik-server>`), build-time scripts (`<script data-bascik-build>`), or custom server logic modules:
+
+1. Open your component `.html` file or imported `.ts` logic file in VS Code.
+2. Click to the left of any line number inside your script block or function to set a breakpoint.
+3. Select **Debug Dev Server** in the Run and Debug panel and press `F5`.
+4. Open your browser and navigate to the page triggering the request.
+5. Node.js pauses execution on your breakpoint inside VS Code. You can inspect variables, evaluate expressions in the Debug Console, step through functions, and view call stacks.
+
+#### Debugging Unit Tests in VS Code
+
+To step through unit test logic or component contract assertions in VS Code:
+
+1. Open your test file (such as `my-counter.test.ts`) and set a breakpoint inside an `it()` or `describe()` block.
+2. Select **Debug Unit Tests** from the Run and Debug panel and press `F5`.
+3. Vitest runs the test suite under the Node.js debugger and pauses at your breakpoint before assertions complete.
+
+#### Debugging Client Component Scripts in the Browser
+
+To debug interactive client component scripts in Google Chrome or Microsoft Edge directly from VS Code:
+
+1. Start the dev server using **Debug Dev Server** or `npm run dev`.
+2. Select **Launch Chrome** from the Run and Debug panel and press `F5`.
+3. VS Code launches a new Chrome window attached to the debugger.
+4. Set breakpoints directly in your component `.html` files in VS Code, or open Chrome DevTools (`F12`), press `Cmd + P` (or `Ctrl + P`), and open virtual source files like `src/components/my-counter.html`.
+
+### Validating Compiled Output Against the HTML Spec
+
+Install `parse5` (the reference WHATWG HTML5 parser used by jsdom and Playwright) as a dev dependency and add a Vitest test that walks every `dist/**/*.html` file. Use `onParseError` with `sourceCodeLocationInfo: true` to fail on any spec violation with an actionable `file:line:col [error-code]` message:
+
+```ts
+// src/lib/dist-sanity.test.ts
+import { describe, it, expect } from 'vitest';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse, type ParserError } from 'parse5';
+
+const DIST_DIR = path.resolve(process.cwd(), 'dist');
+
+async function walk(dir: string, ext: string): Promise<string[]> {
+  const out: string[] = [];
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); }
+  catch { return out; }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await walk(full, ext)));
+    else if (entry.isFile() && entry.name.endsWith(ext)) out.push(full);
+  }
+  return out;
+}
+
+describe('dist HTML — WHATWG spec compliance', () => {
+  it('every page is free of parse errors', async () => {
+    const files = await walk(DIST_DIR, '.html');
+    const failures: string[] = [];
+    for (const file of files) {
+      const html = await readFile(file, 'utf-8');
+      const errors: ParserError[] = [];
+      parse(html, { sourceCodeLocationInfo: true, onParseError: (e) => errors.push(e) });
+      for (const err of errors) {
+        failures.push(`${path.relative(DIST_DIR, file)}:${err.startLine}:${err.startCol}  [${err.code}]`);
+      }
+    }
+    expect(failures, failures.join('\n')).toHaveLength(0);
+  });
+});
+```
+
+Run after `bascik --build`. Catches corrupted script bodies, mismatched tags, and unreplaced internal tokens that string-based assertions miss. Bascik is a build tool — hold output to the full spec, not browser recovery behavior.
+
+### Testing Site Logic in a Bascik Project
+
+Browser component scripts are IIFE-based and not directly importable. The recommended pattern for testing complex client-side logic:
+
+1. **Extract pure functions** (no DOM, no `fetch`) into a sibling TypeScript `.ts` file, such as `search-logic.ts` alongside `docs-search.html`.
+2. **Reference the companion directly** with `<script src="search-logic.ts"></script>`. Bascik strips erasable TypeScript before scoping and JavaScript minification, so do not add a build script or `minify.js` hook for type stripping.
+3. **Test the module with Vitest**: import the `.ts` file directly in a `*.test.ts` file. No browser or DOM is required for pure function tests.
+
+**What to test vs. skip:** DOM wiring (adding event listeners, toggling visibility) is low value to test because it depends on the compiled output. Pure data functions (parsing, scoring, formatting) are high value. Extract those into a `.ts` module and test them with Vitest. Configure Vitest in `vite.config.ts`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+  },
+});
+```
+
+**Server scripts** (`data-bascik-server`): test the business logic as pure functions in a `.ts` module. Node 24 runs `.ts` files natively with no separate build or compilation step required. Test the HTTP layer with integration tests that POST to the dev server, not by importing the script.
+
+---
+
+## 14. CI / CD
+
+Two GitHub Actions workflows handle all automation.
+
+**CI** (`.github/workflows/ci.yml`): runs on every push to `main` and every PR, two parallel jobs on Node 24:
+- `test`: runs `yarn pkg:test:ci` (unit tests with coverage)
+- `e2e`: builds the package (`yarn pkg:build`), installs Chromium via `playwright install chromium`, then runs `yarn pkg:e2e` (Playwright tests)
+- Both jobs have `permissions: contents: read`
+
+**Release** (`.github/workflows/release.yml`): triggers on version tags:
+
+| Package | Tag | Job guard |
+|---|---|---|
+| `@bascik/bascik` | `v*.*.*` | `if: startsWith(github.ref_name, 'v')` |
+| `create-bascik` | `create-v*.*.*` | `if: startsWith(github.ref_name, 'create-v')` |
+| `@bascik/adapter-cloudflare` | `adapter-cloudflare-v*.*.*` | `if: startsWith(github.ref_name, 'adapter-cloudflare-v')` |
+| `@bascik/language-server` | `lsp-v*.*.*` | `if: startsWith(github.ref_name, 'lsp-v')` |
+
+Each release job: install → test → build → `npm publish --provenance --access public --tag <dist-tag>`. The tag must equal the prefix plus the package version; prereleases such as `1.0.0-rc.1` publish under the `rc` dist-tag instead of `latest`.
+
+- `--provenance` requires `id-token: write` permission; generates a signed attestation on npmjs.com linking the package to the Actions run.
+- Both `package.json` files also declare `"publishConfig": { "access": "public" }`.
+- Requires the `NPM_TOKEN` repository secret (Settings → Secrets and variables → Actions).
+
+**Tagging a release:**
+```sh
+# @bascik/bascik
+git tag v1.2.0 && git push origin main --tags
+
+# create-bascik
+git tag create-v1.0.3 && git push origin main --tags
+```
+
+`dist/` is never committed to git; the workflow always builds it fresh.
+
+---
+
+## 15. VS Code Extension
+
+The `extensions/vscode-bascik/` package provides editor tooling:
+
+* **Command-click navigation:** click a component tag like `<site-nav>` to jump to `src/components/site-nav/site-nav.html`.
+* **Inline warnings:** flags CSS patterns Bascik cannot safely scope (standalone attribute selectors, element names inside `:is()`/`:where()`/`:has()`) and JS patterns that won't be rewritten (`.id =` setter, template-literal class names, `style.setProperty('--var', …)`).
+* **Rules generated from the compatibility matrix:** `docs/scripts/generate-compatibility-rules.ts` reads `docs/content/compatibility.md` and writes the warning rules, so editor diagnostics stay in sync with the documented capability table automatically.
+
+To install locally: open `extensions/vscode-bascik/` in VS Code and press F5.
+
+---
+
+## 16. Lighthouse 100s & Performance
+
+Bascik gives you an enormous head start on Lighthouse scores. Because it outputs vanilla HTML with zero framework runtime, you begin every page with near-perfect scores. Reaching 100 across all four Lighthouse categories is a matter of applying a small, well-known set of HTML patterns.
+
+### What Bascik Does
+* **Zero runtime:** The most impactful thing Bascik does is what it does not add: no framework bundle, no hydration script, and no client-side router. The only JavaScript on any page is what you wrote.
+* **CSS deduplication:** When a component appears multiple times on a page, Bascik emits a single `<style>` block regardless of instance count.
+* **HTML minification:** HTML comments are stripped and excess whitespace is collapsed in every built page. Content inside `<pre>` blocks is left intact.
+* **Script minification:** `minify.js` is `true` by default, stripping comments and whitespace.
+* **Inline styles:** Set `assets.inlineStyles` in `bascik.config.ts` to inject a stylesheet directly into `<head>`, eliminating the render-blocking HTTP request.
+
+### Performance Patterns for Developers
+* **Responsive Images (`srcset`):** Avoid sending oversized images. Use `srcset` density or width descriptors, and always include explicit `width` and `height` attributes to prevent Cumulative Layout Shift (CLS).
+* **Lazy Loading (`loading="lazy"`):** Add `loading="lazy"` to below-the-fold images and iframes. Do not lazy-load above-the-fold hero images.
+* **Preloading (`<link rel="preload">`):** Preload critical first-render assets, such as your hero image, critical web fonts, or early stylesheets.
+* **Prefetching (`<link rel="prefetch">`):** Fetch resources or future pages during idle time if a navigation is highly likely.
+* **Preconnect / DNS Prefetch:** For critical third-party domains, resolve DNS and negotiate connections early using `dns-prefetch` and `preconnect`.
+* **Async and Deferred Scripts:** Use `defer` for scripts that need the DOM ready, and `async` for fully independent scripts like analytics.
+
+---
+
+## 17. Switch to Bascik
+
+Detailed per-framework migration guides live at `/switch/*`. Key patterns that apply across all migrations:
+
+- **Component files:** Rename to hyphenated `.html` files in `src/components/<name>/`. Remove framework-specific syntax (`<template>`, JSX, `.astro` frontmatter fences). The HTML file is just the component markup.
+- **Scoped styles:** Delete framework scoped-style blocks (`<style scoped>`, `.module.css`). Create a paired `.css` file alongside the component HTML. Class names stay the same; Bascik scopes them at build time.
+- **Slots:** `<slot />` / `children` → `data-bascik-slot` (no value) for default, `data-bascik-slot="name"` for named slots.
+- **Props:** `defineProps` / component props → `data-bascik-prop-*` attributes (text only).
+- **Reactive state:** `ref`, `useState`, etc. → plain `<script>` with vanilla JS. Bascik scopes `id` values so multiple instances stay independent.
+- **Routing:** Client-side router → one `.html` file per URL in `src/pages/`. No dynamic segments; generate static files for parameterized routes.
+- **Build-time data:** `onMounted` / `getStaticProps` / frontmatter → `<script data-bascik-build>` (Node.js ESM, stdout injected).
+
+### From Svelte
+
+Full guide: `/switch/from-svelte`. Key Svelte-specific mappings:
+
+| Svelte | Bascik |
+|--------|--------|
+| `.svelte` file (`<script>` + markup + `<style>`) | `.html` + `.css` paired files |
+| `children` snippet / `{@render children()}` (Svelte 5) | `data-bascik-slot` (no value) |
+| `<slot />` (Svelte 4, deprecated) | `data-bascik-slot` (no value) |
+| Named snippet prop / `{#snippet header()}` (Svelte 5) | `data-bascik-slot="x"` |
+| `<slot name="x" />` (Svelte 4, deprecated) | `data-bascik-slot="x"` |
+| `$props()` / `export let` | `data-bascik-prop-*` attributes |
+| `$state()` / reactive variables | Vanilla JS `<script>` |
+| `{#if}` / `{#each}` | Static HTML or `<script data-bascik-build>` |
+| SvelteKit file routing (`+page.svelte`) | One `.html` per route in `src/pages/` |
+| `onMount` data fetch | `<script data-bascik-build>` (build time) or `<script>` (runtime) |
+
+### From Vue
+
+Full guide: `/switch/from-vue`. Key Vue-specific mappings:
+
+| Vue | Bascik |
+|-----|--------|
+| `<template>` + `<style scoped>` | `.html` + `.css` paired files |
+| `<slot />` | `data-bascik-slot` (no value) |
+| `<slot name="x" />` | `data-bascik-slot="x"` |
+| `defineProps` | `data-bascik-prop-*` attributes |
+| `ref` / `reactive` | Vanilla JS `<script>` |
+| `v-if` / `v-show` | CSS `display:none` or JS toggle |
+| `vue-router` | One `.html` per route in `src/pages/` |
+| `onMounted` data fetch | `<script data-bascik-build>` |
+
+### Migrating Existing Sitemap & Robots Files
+
+When migrating an existing website to Bascik, follow this procedure for existing `sitemap.xml` and `robots.txt` files:
+
+1. **Open and inspect the existing files:** Read the existing `sitemap.xml` and `robots.txt`.
+2. **Determine if custom directives exist:** Decide whether they contain anything Bascik would not generate automatically: hand-curated URLs, `Disallow` rules for paths that still exist, a `Sitemap:` pointer to an external index, or crawl directives specific to a single bot.
+3. **If they contain nothing special, delete them:** Delete the old files and let Bascik generate fresh ones automatically at build time. Do not copy them into `src/pages/`, and do not set `generate.sitemap: false` or `generate.robots: false` in `bascik.config.ts`.
+4. **If they contain custom directives, keep the authored file:** Keep the authored file in `src/pages/`, turn off the matching generator in `bascik.config.ts` (`generate: { sitemap: false }` or `generate: { robots: false }`), and add a comment in the config explaining why. Authored files in `src/pages/` take precedence over generated ones; if generation remains enabled, Bascik preserves the authored file and emits a warning. To exclude individual redirect-only pages from `sitemap.xml`, use `<meta name="bascik-sitemap" content="exclude">` in the page template.
+
+**Failure Mode Warning:** Copying old sitemap and robots files into `src/pages/` while disabling Bascik's built-in generation looks superficially correct, but silently freezes the sitemap at the old site's URL list forever as new pages are created or routes change.
+
+---
+
+## 18. Key Constraints & Rules for AI Code Generation (MUST FOLLOW)
+
+When generating code, pages, or components for a Bascik project, the following conventions are strictly enforced:
+
+1. **Hyphenated Custom Tags:** Component tag names must be hyphenated (e.g. `my-nav`, `site-header`). Single-word tags are not valid custom element names.
+2. **Scoping Rules:** CSS scoping only applies to paired `.css` files and inline `<style>` tags inside component HTML.
+3. **Selector Rewrites:** CSS `#id {}` hash selectors are converted to component-scoped class selectors; the class is automatically injected onto the matching element. The `[id]` attribute-selector form is stripped.
+4. **Script Selectors:** Use `id` and `class` selectors in JS that exactly match the attributes in the component HTML, Bascik rewrites them at build time.
+5. **DOM Traversal:** For compound DOM queries, query by a single scoped `id` first, then traverse from the returned element.
+6. **Dynamic Toggles:** Use `data-` attributes for runtime state that changes via JavaScript (e.g. `data-state="open"`). Scoped class names are assigned at build time and cannot be reliably looked up by JS string manipulation *unless* you utilize a scoping helper (Section 5).
+7. **Text Props:** Props accept text only. For rich HTML content, use slots.
+8. **Script Modules:** `<script type="module">` scripts are not wrapped in an IIFE, but their selectors are still rewritten.
+9. **Non-JS Script Types:** Script tags with any `type` other than `text/javascript` (e.g. `type="application/json"`) are left completely untouched: no IIFE wrapping, no selector rewriting.
+10. **Literal Tag Text Is Safe:** Component tag text inside `<script>`, `<style>`, or `<textarea>` content (e.g. `<my-card>` in a JSON-LD string or code example) is treated as text and never resolved into a component.
+11. **HTML and CSS First:** Always try to use HTML and CSS before resorting to JavaScript. If a feature or layout can be implemented cleanly and without causing issues using only HTML and CSS, do it in HTML and CSS.
+
+---
+
+## 19. FAQ
+
+**How do you pronounce Bascik? Where does the name come from?** Just like "basic." The idea is basic, the implementation is basic in theory, and the usage is basic. The spelling comes from the author's maternal grandmother's maiden name, so it's unique and means something personal.
+
+**Isn't BASIC already a programming language?** Yes, the classic one from the 1960s. Used it on an old Texas Instruments calculator. Enough time has passed; it can take on new meaning.
+
+**Who made Bascik?** Collin Thomas.
+
+**Why was Bascik created?** To build the fastest possible websites and dashboards with components. It uses only foundational languages (HTML, CSS, and JavaScript) to let you leverage what you already know, without abstraction layers or runtime JavaScript bottlenecks.
+
+**What happens if a component file is named after a native HTML element (e.g. `nav.html`)?**
+Bascik logs a warning and still loads the component, but it will replace every occurrence of that element in pages with the component content, almost certainly breaking the site. Always use a hyphenated component name (e.g. `site-nav.html`).
+
+**What happens with uppercase letters in a component filename (e.g. `My-Card.html`)?**
+Component names are normalized to lowercase at load time. `My-Card.html` registers as `my-card` and is referenced as `<my-card>`. If two files differ only in case, the last one loaded wins. Convention: always use lowercase, hyphenated filenames.
+
+**What happens if I reference a component that doesn't exist?**
+During a build (`bascik --build`), Bascik emits a warning naming the unresolved tag, and the tag ships to the HTML output unchanged without failing the build. Similarly, `bascik --check` treats an unknown hyphenated tag as a warning (exit code 0), allowing third-party custom elements (such as `<model-viewer>` or `<ion-icon>`) to pass without failing the check. Pass `--strict` if you want warnings to fail the check.
+