@techninja/clearstack 0.3.3 → 0.3.6

package/docs/COMPONENT_PATTERNS.md

@@ -292,7 +292,7 @@ handler resolves `host` to the page component as expected.
 Because components use light DOM, styles flow naturally:
 
 ```
-public/index.html
+src/index.html
   ├── <link> src/styles/reset.css      ← base reset
   ├── <link> src/styles/tokens.css     ← :root custom properties
   ├── <link> src/styles/shared.css     ← error states, icons, utilities

package/docs/CONVENTIONS.md

@@ -269,6 +269,23 @@ multiple keys.
 
 ---
 
+## Spec vs Test: Two Different Questions
+
+`spec` and `test` answer different questions and run at different times.
+
+|            | `npm run spec`                             | `npm test`                       |
+| ---------- | ------------------------------------------ | -------------------------------- |
+| Asks       | Is my code clean?                          | Does my code work?               |
+| Checks     | Line counts, lint, format, types, markdown | Unit, integration, browser tests |
+| Speed      | Fast (~10s)                                | Slower (varies)                  |
+| When       | Every save, every change                   | Before commit, in CI             |
+| Auto-fixes | Yes (lint, format, markdown)               | No                               |
+
+Spec is the inner dev loop — run it constantly. Tests are the commit gate —
+run them before pushing. CI runs both, in parallel.
+
+---
+
 ## Session Retrospective
 
 At the end of each implementation session, ask:

package/docs/FRONTEND_IMPLEMENTATION_RULES.md

@@ -117,12 +117,12 @@ import {
 
 ```
 project-root/
-├── public/                          # Static assets served at /
+├── src/                             # The app — served directly, no build
 │   ├── index.html                   # App shell with import map
-│   └── vendor/                      # Vendored ES module deps (generated)
-│       └── hybrids/                 # Copied from node_modules at install
-│
-├── src/                             # Application source (served at /src/)
+│   ├── vendor/                      # Vendored ES modules (generated, gitignored)
+│   │   └── hybrids/                 # Copied from node_modules at install
+│   ├── icons.json                   # Icon sprite (generated, gitignored)
+│   │
 │   ├── components/                  # UI components (atomic design)
 │   │   ├── atoms/                   # Smallest UI primitives
 │   │   │   └── app-button/
@@ -130,39 +130,47 @@ project-root/
 │   │   │       ├── app-button.css   # Scoped styles
 │   │   │       └── index.js         # Re-export
 │   │   ├── molecules/               # Compositions of atoms
-│   │   │   └── search-bar/
 │   │   ├── organisms/               # Complex UI sections
-│   │   │   └── app-header/
 │   │   └── templates/               # Page-level layout shells
-│   │       └── page-layout/
 │   │
 │   ├── pages/                       # Route-bound view components
-│   │   ├── home/
-│   │   │   ├── home-view.js
-│   │   │   └── index.js
-│   │   └── about/
+│   │   └── home/
+│   │       └── home-view.js
 │   │
 │   ├── store/                       # Hybrids store model definitions
 │   │   ├── AppState.js              # Singleton: global app state
-│   │   └── UserModel.js             # Enumerable: user records
+│   │   └── UserPrefs.js             # Singleton: user preferences
 │   │
 │   ├── router/                      # Router shell component
 │   │   └── index.js
 │   │
 │   ├── styles/                      # Shared CSS
 │   │   ├── tokens.css               # Design tokens (colors, spacing)
-│   │   └── reset.css                # Minimal CSS reset
+│   │   ├── reset.css                # Minimal CSS reset
+│   │   └── components.css           # Aggregates component CSS imports
+│   │
+│   ├── utils/                       # Pure helper functions
+│   │   └── formatDate.js
 │   │
-│   └── utils/                       # Pure helper functions
-│       └── formatDate.js
+│   ├── api/                         # Server routes (fullstack only)
+│   │   ├── entities.js              # Generic CRUD router
+│   │   └── schemas.js               # JSON Schema registry
+│   │
+│   └── server.js                    # Express entry point
+│
+├── scripts/                         # Install/setup scripts
+│   ├── vendor-deps.js               # Copies deps to src/vendor/
+│   └── build-icons.js               # Extracts Lucide SVGs to src/icons.json
 │
-├── scripts/                         # Build/install scripts
-│   └── vendor-deps.js               # Copies deps to public/vendor/
+├── .configs/                        # Linter/formatter/type configs
+├── docs/
+│   ├── clearstack/                  # Spec docs (synced on update)
+│   └── app-spec/                    # Project-specific specs (yours)
 │
-├── src/server.js                    # Express entry point
-├── package.json                     # type: "module", postinstall hook
-├── README.md                        # Project overview
-└── FRONTEND_IMPLEMENTATION_RULES.md # This file
+├── data/                            # JSON DB seed (fullstack only)
+├── .env                             # Defaults (committed)
+├── .env.local                       # Overrides (gitignored)
+└── package.json
 ```
 
 ### Key Conventions
@@ -170,7 +178,7 @@ project-root/
 - **One component per directory.** Each gets its own folder with `.js`, `.css`,
   and `index.js` (re-export).
 - **`src/` is served as-is** — the browser loads these files directly.
-- **`public/vendor/`** is gitignored and regenerated on `npm install` via the
+- **`src/vendor/`** is gitignored and regenerated on `npm install` via the
   `postinstall` script.
 - **No barrel files** beyond the per-component `index.js`. Import from the
   component directory, not from a giant `components/index.js`.

package/docs/QUICKSTART.md

@@ -42,33 +42,30 @@ If a `package.json` already exists, Clearstack merges into it — your existing
 ```
 your-project/
 ├── .configs/              # ⟳ Managed — synced on update
-│   ├── eslint.config.js
-│   ├── .prettierrc
-│   ├── jsconfig.json
-│   └── web-test-runner.config.js
 ├── .github/               # CI workflow, PR + issue templates
 ├── docs/
 │   ├── clearstack/        # ⟳ Managed — spec docs, synced on update
 │   └── app-spec/          # ✏️ Yours — project-specific specs
-├── public/                # ✏️ Yours — static assets, index.html, import map
-├── scripts/               # ✏️ Yours — vendor-deps, build-icons
-├── src/
-│   ├── api/               # ✏️ Yours — server routes (fullstack only)
-│   ├── components/        # ✏️ Yours — atoms/, molecules/, organisms/
-│   ├── pages/             # ✏️ Yours — route-level views
-│   ├── store/             # ✏️ Yours — Hybrids store models
-│   ├── styles/            # ✏️ Yours — global CSS
-│   ├── router/            # ✏️ Yours — client-side routing
-│   ├── utils/             # ✏️ Yours — shared helpers
-│   └── server.js          # ✏️ Yours — Express entry (fullstack only)
-├── data/                  # ✏️ Yours — JSON DB seed (fullstack only)
-├── .env                   # ✏️ Yours — PORT, spec thresholds
-└── package.json           # ✏️ Yours (spec scripts merged in)
+├── scripts/               # ✏️ Yours — setup, test, vendor-deps, build-icons
+├── src/                   # ✏️ Yours — the app, served directly
+│   ├── index.html         # App shell with import map
+│   ├── vendor/            # Vendored ES modules (generated, gitignored)
+│   ├── icons.json         # Icon sprite (generated, gitignored)
+│   ├── components/        # atoms/, molecules/, organisms/
+│   ├── pages/             # Route-level views
+│   ├── store/             # Hybrids store models
+│   ├── styles/            # Global CSS
+│   ├── router/            # Client-side routing
+│   ├── utils/             # Shared helpers
+│   ├── api/               # Server routes (fullstack only)
+│   └── server.js          # Express entry point
+├── data/                  # JSON DB seed (fullstack only)
+├── .env                   # Defaults (committed)
+├── .env.local             # Overrides (gitignored)
+└── package.json
 ```
 
-**⟳ Managed** files are updated when you run `clearstack update`. Review changes via `git diff`.
-
-**✏️ Yours** files are scaffolded once and never touched by updates. They're your code.
+`src/` is the entire app. `node src/server.js` serves it. For static deploy, point your CDN at `src/`. No build step.
 
 ## 4. Install and Run
 
@@ -76,18 +73,12 @@ your-project/
 npm install
 ```
 
-`postinstall` runs `vendor-deps.js` (copies hybrids to `public/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `public/icons.json`).
+`postinstall` runs `vendor-deps.js` (copies hybrids to `src/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `src/icons.json`).
 
 ### Fullstack
 
 ```bash
-npm run dev            # node --watch --env-file=.env src/server.js
-```
-
-### Static
-
-```bash
-npx serve public       # or any static file server
+npm run dev
 ```
 
 ## 5. Development Rules
@@ -152,7 +143,7 @@ SPEC_CODE_MAX_LINES=150
 SPEC_DOCS_MAX_LINES=500
 SPEC_CODE_EXTENSIONS=.js,.css
 SPEC_DOCS_EXTENSIONS=.md
-SPEC_IGNORE_DIRS=node_modules,public/vendor,.git,.configs
+SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs
 ```
 
 ## 9. CI Pipeline
@@ -170,7 +161,7 @@ spec:code → spec:docs → lint → format → typecheck → test
 | Install Clearstack    | `npm install -D @techninja/clearstack` |
 | Scaffold a project    | `npx clearstack init`                  |
 | Install dependencies  | `npm install`                          |
-| Start dev server      | `npm run dev` / `npx serve public`     |
+| Start dev server      | `npm run dev`                          |
 | Lint + format         | `npm run lint:fix && npm run format`   |
 | Type check            | `npm run typecheck`                    |
 | Run tests             | `npm test`                             |

package/docs/SERVER_AND_DEPS.md

@@ -14,13 +14,13 @@
 
 ### Responsibilities
 
-| Route         | Serves                                 |
-| ------------- | -------------------------------------- |
-| `/`           | `public/index.html` (app shell)        |
-| `/vendor/*`   | `public/vendor/` (vendored ES modules) |
-| `/src/*`      | `src/` (application source, as-is)     |
-| `/api/*`      | REST endpoints (see BACKEND_API_SPEC)  |
-| `/api/events` | SSE stream for realtime sync           |
+| Route         | Serves                                |
+| ------------- | ------------------------------------- |
+| `/`           | `src/index.html` (app shell)          |
+| `/vendor/*`   | `src/vendor/` (vendored ES modules)   |
+| `/src/*`      | `src/` (application source, as-is)    |
+| `/api/*`      | REST endpoints (see BACKEND_API_SPEC) |
+| `/api/events` | SSE stream for realtime sync          |
 
 ### Key Rules
 
@@ -38,7 +38,7 @@ const app = express();
 const PORT = process.env.PORT || 3000;
 
 // Static: vendored deps and app shell
-app.use(express.static('public'));
+app.use(express.static('src'));
 
 // Static: application source (ES modules served directly)
 app.use('/src', express.static('src'));
@@ -57,7 +57,7 @@ app.listen(PORT, () => console.log(`http://localhost:${PORT}`));
 ## Vendor Dependency Loading
 
 Third-party ES module packages are copied from `node_modules/` into
-`public/vendor/` at install time. This makes them servable as static files.
+`src/vendor/` at install time. This makes them servable as static files.
 
 ### scripts/vendor-deps.js
 
@@ -65,7 +65,7 @@ Third-party ES module packages are copied from `node_modules/` into
 import { cpSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-const VENDOR_DIR = resolve('public/vendor');
+const VENDOR_DIR = resolve('src/vendor');
 const DEPS = [{ name: 'hybrids', src: 'node_modules/hybrids/src' }];
 
 mkdirSync(VENDOR_DIR, { recursive: true });
@@ -89,7 +89,7 @@ In `package.json`:
 }
 ```
 
-Running `npm install` automatically vendors dependencies. The `public/vendor/`
+Running `npm install` automatically vendors dependencies. The `src/vendor/`
 directory should be in `.gitignore`.
 
 ### Adding a New Dependency
@@ -104,9 +104,9 @@ directory should be in `.gitignore`.
 ## Import Map
 
 The browser resolves bare specifiers like `'hybrids'` via an import map
-declared in `public/index.html`.
+declared in `src/index.html`.
 
-### public/index.html
+### src/index.html
 
 ```html
 <!DOCTYPE html>
@@ -137,7 +137,7 @@ declared in `public/index.html`.
 
 1. Browser encounters `import { html } from 'hybrids'` in any ES module.
 2. Import map resolves `'hybrids'` → `/vendor/hybrids/index.js`.
-3. Server serves the file from `public/vendor/hybrids/index.js`.
+3. Server serves the file from `src/vendor/hybrids/index.js`.
 4. Hybrids' internal imports use relative paths — they resolve naturally.
 
 ### Rules

package/lib/check.js

@@ -32,7 +32,7 @@ export function loadConfig(projectDir) {
     docsMax: parseInt(env.SPEC_DOCS_MAX_LINES) || 500,
     codeExt: (env.SPEC_CODE_EXTENSIONS || '.js,.css').split(','),
     docsExt: (env.SPEC_DOCS_EXTENSIONS || '.md').split(','),
-    ignore: (env.SPEC_IGNORE_DIRS || 'node_modules,src/public/vendor,.git,.configs').split(','),
+    ignore: (env.SPEC_IGNORE_DIRS || 'node_modules,src/vendor,.git,.configs').split(','),
   };
 }
 
@@ -43,6 +43,7 @@ export const CMDS = {
   prettier: 'npx prettier --config .configs/.prettierrc --write src scripts',
   mdlint: 'npx markdownlint-cli2 --config .configs/.markdownlint.jsonc --fix "docs/**/*.md" "*.md"',
   types: 'npx tsc --project .configs/jsconfig.json',
+  audit: 'npm audit --omit=dev',
 };
 
 /**
@@ -77,6 +78,7 @@ export async function check(projectDir, scope) {
     runCmd('Prettier', CMDS.prettier, projectDir, `${jsFiles} files`),
     runCmd('Markdown', CMDS.mdlint, projectDir, `${mdFiles} files`),
     runCmd('JSDoc types', CMDS.types, projectDir, `${jsFiles} files`),
+    runCmd('Security audit', CMDS.audit, projectDir),
   ];
 
   const passed = results.filter(Boolean).length;

package/lib/package-gen.js

@@ -40,6 +40,7 @@ export async function writePackageJson(dest, vars, existing) {
     eslint: '^10.1.0',
     'eslint-config-prettier': '^10.1.8',
     'eslint-plugin-jsdoc': '^62.8.1',
+    'eslint-plugin-unused-imports': '^4.0.0',
     'markdownlint-cli2': '^0.22.0',
     playwright: '^1.50.0',
     prettier: '^3.8.1',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -20,7 +20,7 @@
     "start": "node src/server.js",
     "dev": "node --watch --env-file=.env --env-file=.env.local src/server.js",
     "setup": "node scripts/vendor-deps.js && node scripts/build-icons.js",
-    "test": "node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js",
+    "test": "node scripts/test.js",
     "spec": "node --env-file=.env scripts/spec.js",
     "lint": "eslint --config .configs/eslint.config.js . --fix",
     "format": "prettier --config .configs/.prettierrc --write src scripts tests templates/**/*.md templates/**/*.html templates/**/*.css templates/**/*.json",
@@ -51,6 +51,7 @@
     "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsdoc": "^62.8.1",
+    "eslint-plugin-unused-imports": "^4.4.1",
     "express": "^5.2.1",
     "hybrids": "^9.1.22",
     "lucide-static": "^1.7.0",

package/templates/fullstack/src/server.js

@@ -19,7 +19,7 @@ app.use(express.static('src'));
 // SPA fallback
 app.use((req, res, next) => {
   if (req.method === 'GET' && !req.path.includes('.') && !req.path.startsWith('/api')) {
-    return res.sendFile('index.html', { root: 'src/public' });
+    return res.sendFile('index.html', { root: 'src' });
   }
   next();
 });

package/templates/shared/.configs/eslint.config.js

@@ -1,10 +1,11 @@
 import prettier from 'eslint-config-prettier';
 import jsdoc from 'eslint-plugin-jsdoc';
+import unusedImports from 'eslint-plugin-unused-imports';
 
 export default [
   {
     files: ['**/*.js'],
-    plugins: { jsdoc },
+    plugins: { jsdoc, 'unused-imports': unusedImports },
     languageOptions: {
       ecmaVersion: 2024,
       sourceType: 'module',
@@ -34,7 +35,9 @@ export default [
       'no-var': 'error',
       'prefer-const': 'error',
       eqeqeq: ['error', 'always'],
-      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+      'no-unused-vars': 'off',
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
       'no-console': 'off',
 
       // JSDoc enforcement
@@ -55,10 +58,11 @@ export default [
     rules: {
       'jsdoc/require-jsdoc': 'off',
       'no-unused-vars': 'off',
+      'unused-imports/no-unused-vars': 'off',
     },
   },
   {
-    ignores: ['node_modules/', 'src/public/vendor/'],
+    ignores: ['node_modules/', 'src/vendor/'],
   },
   prettier,
 ];

package/templates/shared/.configs/jsconfig.json

@@ -14,5 +14,5 @@
     }
   },
   "include": ["../src/**/*.js", "../scripts/**/*.js"],
-  "exclude": ["../node_modules", "../src/public/vendor", "../**/*.test.js"]
+  "exclude": ["../node_modules", "../src/vendor", "../**/*.test.js"]
 }

package/templates/shared/.env

@@ -3,7 +3,7 @@ SPEC_CODE_MAX_LINES=150
 SPEC_DOCS_MAX_LINES=500
 SPEC_CODE_EXTENSIONS=.js,.css
 SPEC_DOCS_EXTENSIONS=.md
-SPEC_IGNORE_DIRS=node_modules,src/public/vendor,.git,.configs
+SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs
 
 # Server
 PORT={{port}}

package/templates/shared/docs/clearstack/COMPONENT_PATTERNS.md

@@ -292,7 +292,7 @@ handler resolves `host` to the page component as expected.
 Because components use light DOM, styles flow naturally:
 
 ```
-public/index.html
+src/index.html
   ├── <link> src/styles/reset.css      ← base reset
   ├── <link> src/styles/tokens.css     ← :root custom properties
   ├── <link> src/styles/shared.css     ← error states, icons, utilities

package/templates/shared/docs/clearstack/CONVENTIONS.md

@@ -269,6 +269,23 @@ multiple keys.
 
 ---
 
+## Spec vs Test: Two Different Questions
+
+`spec` and `test` answer different questions and run at different times.
+
+|            | `npm run spec`                             | `npm test`                       |
+| ---------- | ------------------------------------------ | -------------------------------- |
+| Asks       | Is my code clean?                          | Does my code work?               |
+| Checks     | Line counts, lint, format, types, markdown | Unit, integration, browser tests |
+| Speed      | Fast (~10s)                                | Slower (varies)                  |
+| When       | Every save, every change                   | Before commit, in CI             |
+| Auto-fixes | Yes (lint, format, markdown)               | No                               |
+
+Spec is the inner dev loop — run it constantly. Tests are the commit gate —
+run them before pushing. CI runs both, in parallel.
+
+---
+
 ## Session Retrospective
 
 At the end of each implementation session, ask:

package/templates/shared/docs/clearstack/FRONTEND_IMPLEMENTATION_RULES.md

@@ -117,12 +117,12 @@ import {
 
 ```
 project-root/
-├── public/                          # Static assets served at /
+├── src/                             # The app — served directly, no build
 │   ├── index.html                   # App shell with import map
-│   └── vendor/                      # Vendored ES module deps (generated)
-│       └── hybrids/                 # Copied from node_modules at install
-│
-├── src/                             # Application source (served at /src/)
+│   ├── vendor/                      # Vendored ES modules (generated, gitignored)
+│   │   └── hybrids/                 # Copied from node_modules at install
+│   ├── icons.json                   # Icon sprite (generated, gitignored)
+│   │
 │   ├── components/                  # UI components (atomic design)
 │   │   ├── atoms/                   # Smallest UI primitives
 │   │   │   └── app-button/
@@ -130,39 +130,47 @@ project-root/
 │   │   │       ├── app-button.css   # Scoped styles
 │   │   │       └── index.js         # Re-export
 │   │   ├── molecules/               # Compositions of atoms
-│   │   │   └── search-bar/
 │   │   ├── organisms/               # Complex UI sections
-│   │   │   └── app-header/
 │   │   └── templates/               # Page-level layout shells
-│   │       └── page-layout/
 │   │
 │   ├── pages/                       # Route-bound view components
-│   │   ├── home/
-│   │   │   ├── home-view.js
-│   │   │   └── index.js
-│   │   └── about/
+│   │   └── home/
+│   │       └── home-view.js
 │   │
 │   ├── store/                       # Hybrids store model definitions
 │   │   ├── AppState.js              # Singleton: global app state
-│   │   └── UserModel.js             # Enumerable: user records
+│   │   └── UserPrefs.js             # Singleton: user preferences
 │   │
 │   ├── router/                      # Router shell component
 │   │   └── index.js
 │   │
 │   ├── styles/                      # Shared CSS
 │   │   ├── tokens.css               # Design tokens (colors, spacing)
-│   │   └── reset.css                # Minimal CSS reset
+│   │   ├── reset.css                # Minimal CSS reset
+│   │   └── components.css           # Aggregates component CSS imports
+│   │
+│   ├── utils/                       # Pure helper functions
+│   │   └── formatDate.js
 │   │
-│   └── utils/                       # Pure helper functions
-│       └── formatDate.js
+│   ├── api/                         # Server routes (fullstack only)
+│   │   ├── entities.js              # Generic CRUD router
+│   │   └── schemas.js               # JSON Schema registry
+│   │
+│   └── server.js                    # Express entry point
+│
+├── scripts/                         # Install/setup scripts
+│   ├── vendor-deps.js               # Copies deps to src/vendor/
+│   └── build-icons.js               # Extracts Lucide SVGs to src/icons.json
 │
-├── scripts/                         # Build/install scripts
-│   └── vendor-deps.js               # Copies deps to public/vendor/
+├── .configs/                        # Linter/formatter/type configs
+├── docs/
+│   ├── clearstack/                  # Spec docs (synced on update)
+│   └── app-spec/                    # Project-specific specs (yours)
 │
-├── src/server.js                    # Express entry point
-├── package.json                     # type: "module", postinstall hook
-├── README.md                        # Project overview
-└── FRONTEND_IMPLEMENTATION_RULES.md # This file
+├── data/                            # JSON DB seed (fullstack only)
+├── .env                             # Defaults (committed)
+├── .env.local                       # Overrides (gitignored)
+└── package.json
 ```
 
 ### Key Conventions
@@ -170,7 +178,7 @@ project-root/
 - **One component per directory.** Each gets its own folder with `.js`, `.css`,
   and `index.js` (re-export).
 - **`src/` is served as-is** — the browser loads these files directly.
-- **`public/vendor/`** is gitignored and regenerated on `npm install` via the
+- **`src/vendor/`** is gitignored and regenerated on `npm install` via the
   `postinstall` script.
 - **No barrel files** beyond the per-component `index.js`. Import from the
   component directory, not from a giant `components/index.js`.

package/templates/shared/docs/clearstack/QUICKSTART.md

@@ -42,33 +42,30 @@ If a `package.json` already exists, Clearstack merges into it — your existing
 ```
 your-project/
 ├── .configs/              # ⟳ Managed — synced on update
-│   ├── eslint.config.js
-│   ├── .prettierrc
-│   ├── jsconfig.json
-│   └── web-test-runner.config.js
 ├── .github/               # CI workflow, PR + issue templates
 ├── docs/
 │   ├── clearstack/        # ⟳ Managed — spec docs, synced on update
 │   └── app-spec/          # ✏️ Yours — project-specific specs
-├── public/                # ✏️ Yours — static assets, index.html, import map
-├── scripts/               # ✏️ Yours — vendor-deps, build-icons
-├── src/
-│   ├── api/               # ✏️ Yours — server routes (fullstack only)
-│   ├── components/        # ✏️ Yours — atoms/, molecules/, organisms/
-│   ├── pages/             # ✏️ Yours — route-level views
-│   ├── store/             # ✏️ Yours — Hybrids store models
-│   ├── styles/            # ✏️ Yours — global CSS
-│   ├── router/            # ✏️ Yours — client-side routing
-│   ├── utils/             # ✏️ Yours — shared helpers
-│   └── server.js          # ✏️ Yours — Express entry (fullstack only)
-├── data/                  # ✏️ Yours — JSON DB seed (fullstack only)
-├── .env                   # ✏️ Yours — PORT, spec thresholds
-└── package.json           # ✏️ Yours (spec scripts merged in)
+├── scripts/               # ✏️ Yours — setup, test, vendor-deps, build-icons
+├── src/                   # ✏️ Yours — the app, served directly
+│   ├── index.html         # App shell with import map
+│   ├── vendor/            # Vendored ES modules (generated, gitignored)
+│   ├── icons.json         # Icon sprite (generated, gitignored)
+│   ├── components/        # atoms/, molecules/, organisms/
+│   ├── pages/             # Route-level views
+│   ├── store/             # Hybrids store models
+│   ├── styles/            # Global CSS
+│   ├── router/            # Client-side routing
+│   ├── utils/             # Shared helpers
+│   ├── api/               # Server routes (fullstack only)
+│   └── server.js          # Express entry point
+├── data/                  # JSON DB seed (fullstack only)
+├── .env                   # Defaults (committed)
+├── .env.local             # Overrides (gitignored)
+└── package.json
 ```
 
-**⟳ Managed** files are updated when you run `clearstack update`. Review changes via `git diff`.
-
-**✏️ Yours** files are scaffolded once and never touched by updates. They're your code.
+`src/` is the entire app. `node src/server.js` serves it. For static deploy, point your CDN at `src/`. No build step.
 
 ## 4. Install and Run
 
@@ -76,18 +73,12 @@ your-project/
 npm install
 ```
 
-`postinstall` runs `vendor-deps.js` (copies hybrids to `public/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `public/icons.json`).
+`postinstall` runs `vendor-deps.js` (copies hybrids to `src/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `src/icons.json`).
 
 ### Fullstack
 
 ```bash
-npm run dev            # node --watch --env-file=.env src/server.js
-```
-
-### Static
-
-```bash
-npx serve public       # or any static file server
+npm run dev
 ```
 
 ## 5. Development Rules
@@ -152,7 +143,7 @@ SPEC_CODE_MAX_LINES=150
 SPEC_DOCS_MAX_LINES=500
 SPEC_CODE_EXTENSIONS=.js,.css
 SPEC_DOCS_EXTENSIONS=.md
-SPEC_IGNORE_DIRS=node_modules,public/vendor,.git,.configs
+SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs
 ```
 
 ## 9. CI Pipeline
@@ -170,7 +161,7 @@ spec:code → spec:docs → lint → format → typecheck → test
 | Install Clearstack    | `npm install -D @techninja/clearstack` |
 | Scaffold a project    | `npx clearstack init`                  |
 | Install dependencies  | `npm install`                          |
-| Start dev server      | `npm run dev` / `npx serve public`     |
+| Start dev server      | `npm run dev`                          |
 | Lint + format         | `npm run lint:fix && npm run format`   |
 | Type check            | `npm run typecheck`                    |
 | Run tests             | `npm test`                             |

package/templates/shared/docs/clearstack/SERVER_AND_DEPS.md

@@ -14,13 +14,13 @@
 
 ### Responsibilities
 
-| Route         | Serves                                 |
-| ------------- | -------------------------------------- |
-| `/`           | `public/index.html` (app shell)        |
-| `/vendor/*`   | `public/vendor/` (vendored ES modules) |
-| `/src/*`      | `src/` (application source, as-is)     |
-| `/api/*`      | REST endpoints (see BACKEND_API_SPEC)  |
-| `/api/events` | SSE stream for realtime sync           |
+| Route         | Serves                                |
+| ------------- | ------------------------------------- |
+| `/`           | `src/index.html` (app shell)          |
+| `/vendor/*`   | `src/vendor/` (vendored ES modules)   |
+| `/src/*`      | `src/` (application source, as-is)    |
+| `/api/*`      | REST endpoints (see BACKEND_API_SPEC) |
+| `/api/events` | SSE stream for realtime sync          |
 
 ### Key Rules
 
@@ -38,7 +38,7 @@ const app = express();
 const PORT = process.env.PORT || 3000;
 
 // Static: vendored deps and app shell
-app.use(express.static('public'));
+app.use(express.static('src'));
 
 // Static: application source (ES modules served directly)
 app.use('/src', express.static('src'));
@@ -57,7 +57,7 @@ app.listen(PORT, () => console.log(`http://localhost:${PORT}`));
 ## Vendor Dependency Loading
 
 Third-party ES module packages are copied from `node_modules/` into
-`public/vendor/` at install time. This makes them servable as static files.
+`src/vendor/` at install time. This makes them servable as static files.
 
 ### scripts/vendor-deps.js
 
@@ -65,7 +65,7 @@ Third-party ES module packages are copied from `node_modules/` into
 import { cpSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-const VENDOR_DIR = resolve('public/vendor');
+const VENDOR_DIR = resolve('src/vendor');
 const DEPS = [{ name: 'hybrids', src: 'node_modules/hybrids/src' }];
 
 mkdirSync(VENDOR_DIR, { recursive: true });
@@ -89,7 +89,7 @@ In `package.json`:
 }
 ```
 
-Running `npm install` automatically vendors dependencies. The `public/vendor/`
+Running `npm install` automatically vendors dependencies. The `src/vendor/`
 directory should be in `.gitignore`.
 
 ### Adding a New Dependency
@@ -104,9 +104,9 @@ directory should be in `.gitignore`.
 ## Import Map
 
 The browser resolves bare specifiers like `'hybrids'` via an import map
-declared in `public/index.html`.
+declared in `src/index.html`.
 
-### public/index.html
+### src/index.html
 
 ```html
 <!DOCTYPE html>
@@ -137,7 +137,7 @@ declared in `public/index.html`.
 
 1. Browser encounters `import { html } from 'hybrids'` in any ES module.
 2. Import map resolves `'hybrids'` → `/vendor/hybrids/index.js`.
-3. Server serves the file from `public/vendor/hybrids/index.js`.
+3. Server serves the file from `src/vendor/hybrids/index.js`.
 4. Hybrids' internal imports use relative paths — they resolve naturally.
 
 ### Rules

package/templates/shared/gitignore

@@ -1,5 +1,5 @@
 node_modules/
-src/public/vendor/
-src/public/icons.json
+src/vendor/
+src/icons.json
 data/db.json
 .env.local

package/templates/shared/scripts/build-icons.js

@@ -2,7 +2,7 @@
 
 /**
  * Extracts SVG path data from lucide-static for icons used in the app.
- * Generates public/icons.json — loaded by app-icon at runtime.
+ * Generates src/icons.json — loaded by app-icon at runtime.
  * Runs on `npm postinstall`.
  */
 
@@ -12,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ICONS_DIR = resolve(ROOT, 'node_modules/lucide-static/icons');
-const OUT = resolve(ROOT, 'src/public/icons.json');
+const OUT = resolve(ROOT, 'src/icons.json');
 
 /** Icons used in the app — lucide name → app name */
 const ICON_MAP = {
@@ -83,4 +83,4 @@ for (const [lucideName, appName] of Object.entries(ICON_MAP)) {
 }
 
 writeFileSync(OUT, JSON.stringify(icons, null, 2));
-console.log(`✓ Built ${count} icons → src/public/icons.json`);
+console.log(`✓ Built ${count} icons → src/icons.json`);

package/templates/shared/scripts/test.js

@@ -1,37 +1,57 @@
 #!/usr/bin/env node
 
 /**
- * Test runner — finds and executes all .test.js files.
+ * Test runner — runs node tests directly, browser tests via web-test-runner.
+ * Browser tests live in src/components/. Everything else runs in Node.
  * @module scripts/test
  */
 
 import { execSync } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readdirSync, statSync } from 'node:fs';
+import { readdirSync, existsSync } from 'node:fs';
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 
 /** @param {string} dir @returns {string[]} */
 function findTests(dir) {
   const results = [];
+  if (!existsSync(dir)) return results;
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const full = resolve(dir, entry.name);
-    if (entry.name === 'node_modules' || entry.name === 'public') continue;
+    if (entry.name === 'node_modules' || entry.name === 'vendor') continue;
     if (entry.isDirectory()) results.push(...findTests(full));
     else if (entry.name.endsWith('.test.js')) results.push(full);
   }
   return results;
 }
 
-const files = findTests(ROOT);
-if (files.length === 0) {
-  console.log('No test files found.');
-  process.exit(0);
+const componentDir = resolve(ROOT, 'src/components');
+const allTests = findTests(ROOT);
+const nodeTests = allTests.filter((f) => !f.startsWith(componentDir));
+const browserTests = allTests.filter((f) => f.startsWith(componentDir));
+let failed = false;
+
+if (nodeTests.length > 0) {
+  console.log(`Running ${nodeTests.length} node test(s)...\n`);
+  try {
+    execSync(`node --test ${nodeTests.join(' ')}`, { cwd: ROOT, stdio: 'inherit' });
+  } catch {
+    failed = true;
+  }
 }
 
-try {
-  execSync(`node --test ${files.join(' ')}`, { cwd: ROOT, stdio: 'inherit' });
-} catch {
-  process.exit(1);
+if (browserTests.length > 0) {
+  console.log(`\nRunning ${browserTests.length} browser test(s)...\n`);
+  try {
+    execSync('npx web-test-runner --config .configs/web-test-runner.config.js', {
+      cwd: ROOT,
+      stdio: 'inherit',
+    });
+  } catch {
+    failed = true;
+  }
 }
+
+if (allTests.length === 0) console.log('No test files found.');
+if (failed) process.exit(1);

package/templates/shared/scripts/vendor-deps.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * Copies third-party ES module sources into public/vendor/ so the browser
+ * Copies third-party ES module sources into src/vendor/ so the browser
  * can load them directly via import map. Runs on `npm postinstall`.
  */
 
@@ -10,7 +10,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
-const VENDOR_DIR = resolve(ROOT, 'src/public/vendor');
+const VENDOR_DIR = resolve(ROOT, 'src/vendor');
 
 /** @type {{ name: string, src: string }[]} */
 const DEPS = [{ name: 'hybrids', src: 'node_modules/hybrids/src' }];
@@ -21,5 +21,5 @@ for (const dep of DEPS) {
   const src = resolve(ROOT, dep.src);
   const dest = resolve(VENDOR_DIR, dep.name);
   cpSync(src, dest, { recursive: true });
-  console.log(`✓ Vendored: ${dep.name} → src/public/vendor/${dep.name}/`);
+  console.log(`✓ Vendored: ${dep.name} → src/vendor/${dep.name}/`);
 }

package/templates/shared/src/components/atoms/app-icon/app-icon.js

@@ -11,7 +11,10 @@ let iconCache = null;
 
 /** @type {Promise<Record<string, string>>} */
 const loading = fetch('/icons.json')
-  .then((r) => (r.ok ? r : fetch('/public/icons.json')))
+  .then((r) => {
+    if (r.ok) return r;
+    throw new Error('icons.json not found');
+  })
   .then((r) => r.json())
   .then((data) => {
     iconCache = data;

package/templates/shared/src/{public/index.html → index.html}

@@ -14,7 +14,7 @@
     <script type="importmap">
       {
         "imports": {
-          "hybrids": "/public/vendor/hybrids/index.js"
+          "hybrids": "/vendor/hybrids/index.js"
         }
       }
     </script>

package/templates/static/src/server.js

@@ -12,7 +12,7 @@ app.use(express.static('src'));
 
 app.use((req, res, next) => {
   if (req.method === 'GET' && !req.path.includes('.')) {
-    return res.sendFile('index.html', { root: 'src/public' });
+    return res.sendFile('index.html', { root: 'src' });
   }
   next();
 });