BranchesTags

Repository files navigation

Clearstack

A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.

Why This Exists

Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?

The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.

This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.

Quick Start

npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard

npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.

What's In The Box

A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.

Specification

DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance

Using Clearstack

Install as a dev dependency, scaffold, and keep in sync:

npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance

Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).

See QUICKSTART.md for the full walkthrough.

Rules That Matter

  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.

Scripts

npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream

Watch dashboard keys

q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License

MIT

About

A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.

Topics

stackstatic

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
BranchesTags
Repository files navigation
Clearstack
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Why This Exists
Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?
The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.
Quick Start
npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard
npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
What's In The Box
A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
Specification
DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance
Using Clearstack
Install as a dev dependency, scaffold, and keep in sync:
npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance
Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).
See QUICKSTART.md for the full walkthrough.
Rules That Matter
  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.
Scripts
npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream
Watch dashboard keys
q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License
MIT
About
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Topics
stackstatic
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Clearstack
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Why This Exists
Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?
The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.
Quick Start
npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard
npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
What's In The Box
A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
Specification
DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance
Using Clearstack
Install as a dev dependency, scaffold, and keep in sync:
npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance
Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).
See QUICKSTART.md for the full walkthrough.
Rules That Matter
  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.
Scripts
npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream
Watch dashboard keys
q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License
MIT
About
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Topics
stackstatic
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Clearstack
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Why This Exists
Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?
The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.
Quick Start
npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard
npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
What's In The Box
A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
Specification
DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance
Using Clearstack
Install as a dev dependency, scaffold, and keep in sync:
npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance
Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).
See QUICKSTART.md for the full walkthrough.
Rules That Matter
  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.
Scripts
npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream
Watch dashboard keys
q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License
MIT
About
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Topics
stackstatic
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
BranchesTags
Repository files navigation
Clearstack
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Why This Exists
Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?
The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.
Quick Start
npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard
npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
What's In The Box
A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
Specification
DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance
Using Clearstack
Install as a dev dependency, scaffold, and keep in sync:
npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance
Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).
See QUICKSTART.md for the full walkthrough.
Rules That Matter
  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.
Scripts
npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream
Watch dashboard keys
q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License
MIT
About
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Topics
stackstatic
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Clearstack
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Why This Exists
Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?
The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.
Quick Start
npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard
npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
What's In The Box
A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
Specification
DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance
Using Clearstack
Install as a dev dependency, scaffold, and keep in sync:
npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance
Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).
See QUICKSTART.md for the full walkthrough.
Rules That Matter
  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.
Scripts
npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream
Watch dashboard keys
q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License
MIT
About
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Topics
stackstatic
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
BranchesTags
Repository files navigation
Clearstack
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Why This Exists
Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?
The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.
Quick Start
npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard
npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
What's In The Box
A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
Specification
DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance
Using Clearstack
Install as a dev dependency, scaffold, and keep in sync:
npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance
Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).
See QUICKSTART.md for the full walkthrough.
Rules That Matter
  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.
Scripts
npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream
Watch dashboard keys
q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License
MIT
About
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Topics
stackstatic
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
BranchesTags
Repository files navigation
Clearstack
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Why This Exists
Modern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: what if we optimized for comprehension instead?
The core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.
This entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: npm run spec checks every file against its own rules.
Quick Start
npm install -D @techninja/clearstack
npx clearstack init # scaffold a spec-compliant project
npm install
npm run spec watch # start dev server + spec dashboard
npm run spec watch is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
What's In The Box
A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
Specification
DocumentWhat It Covers
FRONTEND_IMPLEMENTATION_RULES.mdPhilosophy, framework choice, project structure, atomic design
COMPONENT_PATTERNS.mdAuthoring, light DOM, styling, layout engine, JSDoc typing
STATE_AND_ROUTING.mdStore, routing, unified app state, realtime SSE sync
CONVENTIONS.mdNaming rules, anti-patterns
SERVER_AND_DEPS.mdExpress server, import maps, vendor dependency loading
BACKEND_API_SPEC.mdREST CRUD, JSON Schema via HEAD, entity management
TESTING.mdTesting philosophy, tools, patterns, phase checkpoints
I18N.mdInternationalization — 4-layer cascade, t() usage, conventions
BUILD_LOG.mdHow this project was built — LLM-human collaboration proof
QUICKSTART.mdScaffolder setup, development workflow, updating, compliance
Using Clearstack
Install as a dev dependency, scaffold, and keep in sync:
npm install -D @techninja/clearstack # add to your project
npx clearstack init # scaffold (interactive)
npx clearstack init -y # scaffold (fullstack defaults)
npx clearstack init --static # scaffold (static, no server)
npx clearstack update # sync docs (skip existing configs)
npx clearstack update --force # sync docs + overwrite configs
npm run spec # check compliance
Two modes: fullstack (Express + WebSocket + JSON DB + SSE) or static (localStorage, no server).
See QUICKSTART.md for the full walkthrough.
Rules That Matter
  • No build tools. ES modules served directly to the browser.
  • ≤150 lines per code file. When it grows, it splits.
  • Light DOM by default. Shared styles just work.
  • JSDoc over TypeScript. Types without a compile step — validated by tsc --checkJs.
  • Test at the boundary. Each phase passes before the next begins.
  • The spec checks itself.npm run spec code and npm run spec docs.
  • Lint and format. ESLint + Prettier, semicolons, 2-space indent.
Scripts
npm run spec watch # Dev server + continuous spec dashboard (recommended)
npm start # Start server only
npm run dev # Start server with --watch
npm test# Node + browser tests
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier auto-format
npm run typecheck # JSDoc type validation via tsc
npm run spec # Spec compliance (interactive)
npm run spec all # Full spec check
npm run spec code # Check code files ≤150 lines
npm run spec docs # Check doc files ≤500 lines
npm run spec update # Sync docs from upstream
Watch dashboard keys
q / Ctrl-C quit
↑ ↓ scroll violations
c copy violations to clipboard (paste into LLM)

License
MIT
About
A no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.
Topics
stackstatic
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
4 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases
Packages
Contributors
Languages