README.md

@@ -1,113 +1,168 @@
-# Lit-Only Architecture (No Build)
+# Lit + Zustand Architecture
 
-A minimal, no-build web application using only Lit web components with local state management.
+A modern, no-build web application architecture using Lit web components with Zustand state management and IndexedDB persistence.
-
-> **Note:** This is the `lit-only` branch. For the full-featured version with Zustand state management and IndexedDB persistence, see the `main` branch.
 
 ## For TSX/React Developers
 
-If you're coming from React/TSX, here's how this minimal architecture maps to familiar concepts:
+If you're coming from React/TSX, here's how this architecture maps to familiar concepts:
 
 | React/TSX Pattern | This Architecture |
 |-------------------|-------------------|
-| `useState` | Lit's `static properties` with `state: true` |
+| `useState` / `useReducer` | Zustand vanilla store |
-| Props drilling | Property passing via `.prop=${value}` |
+| `useEffect` + state subscription | `StoreController` (ReactiveController) |
-| Custom events | `CustomEvent` with `bubbles: true` |
+| Context API | Global Zustand store |
+| `localStorage` / `sessionStorage` | IndexedDB via persist middleware |
 | JSX | Lit's `html` tagged template literals |
 | CSS-in-JS / CSS Modules | Lit's `css` tagged template literals |
-| React Router | Simple route state in root component |
+| React Router | Simple route state in store |
 | Build step (Vite/Webpack) | Import maps (no build!) |
 
 ### Key Differences
 
 1. **No Virtual DOM**: Lit uses native Web Components with efficient DOM updates
 2. **No Build Step**: Import maps let you use npm packages directly from CDN
-3. **Local State Only**: Each component manages its own state, parent manages shared state
+3. **Reactive Controllers**: Replace hooks - attach to component lifecycle
-4. **Event-Based Communication**: Child components emit events, parent handles them
+4. **Tagged Templates**: Instead of JSX, use `html\`<div>...</div>\``
-5. **Tagged Templates**: Instead of JSX, use `html\`<div>...</div>\``
 
 ## Architecture Overview
 
 * **Lit-based web components** - Standards-based, framework-agnostic UI
 * **No-build tooling** - Import maps only, no bundler required
-* **Local state management** - Component properties and state
+* **Zustand state management** - Lightweight, vanilla JS store
-* **Event-driven** - CustomEvents for child-to-parent communication
+* **IndexedDB persistence** - Automatic state persistence with idb-keyval
 
-## Project Structure
+
+## Layout
 
 ```
-components/
+src/
-  app-root.js       ← Root component with shared state
+  store/
-  nav-bar.js        ← Navigation component
+    index.js          ← zustand store definition
-  page-home.js      ← Home page component
+    middleware/
-  page-items.js     ← Items page component
+      persistence.js  ← idb-keyval persist adapter
-index.html          ← Entry point with inline importmap
+      sync.js         ← optional cross-tab broadcast
-README.md
+  components/
-tasks.md
+    app-root.js
+    feature-a/
+      feature-a.js    ← Lit component
+      feature-a.css   ← adopted stylesheet or constructable
+  controllers/
+    fetch.js          ← ReactiveController for API calls
+    3d.js             ← optional Three/WebGPU controller
+  lib/
+    idb.js            ← thin idb-keyval wrapper/schema
+index.html
+importmap.json        ← extracted importmap (referenced via <script src>)
 ```
 
-## Data Flow Pattern
+## Data Flow Diagrams
 
-### Parent-to-Child (Props)
+### Component-to-Store Pattern
 
-```javascript
+```mermaid
-// Parent passes data down
+sequenceDiagram
-html`<child-component .items=${this.items}></child-component>`
+    participant User
+    participant LitComponent
+    participant StoreController
+    participant ZustandStore
+    participant IndexedDB
 
-// Child receives via properties
+    User->>LitComponent: Click button
-static properties = {
+    LitComponent->>ZustandStore: Call action (e.g., addItem)
-  items: { type: Array }
+    ZustandStore->>ZustandStore: Update state
-}
+    ZustandStore->>IndexedDB: Persist (via middleware)
+    ZustandStore->>StoreController: Notify subscribers
+    StoreController->>LitComponent: requestUpdate()
+    LitComponent->>LitComponent: Re-render
+    LitComponent->>User: Show updated UI
 ```
 
-### Child-to-Parent (Events)
+### Store Subscription Pattern
-
-```javascript
-// Child emits event
-this.dispatchEvent(new CustomEvent('add-item', {
-  detail: { item: newItem },
-  bubbles: true,
-  composed: true
-}))
-
-// Parent listens
-html`<child-component @add-item=${(e) => this.handleAdd(e.detail.item)}></child-component>`
-```
-
-## State Management Pattern
 
 ```mermaid
 graph TD
-    A[app-root] -->|.user, .items, .route| B[nav-bar]
+    A[Zustand Store] -->|subscribe| B[StoreController]
-    A -->|.user, .items| C[page-home]
+    B -->|selector function| C[Extract specific state]
-    A -->|.items| D[page-items]
+    C -->|value changed?| D{Compare}
-    B -->|@navigate event| A
+    D -->|Yes| E[host.requestUpdate]
-    D -->|@add-item event| A
+    D -->|No| F[Skip update]
-    D -->|@remove-item event| A
+    E --> G[Lit re-renders component]
     
     style A fill:#f9f,stroke:#333,stroke-width:2px
     style B fill:#bbf,stroke:#333,stroke-width:2px
-    style C fill:#bfb,stroke:#333,stroke-width:2px
+    style G fill:#bfb,stroke:#333,stroke-width:2px
-    style D fill:#bfb,stroke:#333,stroke-width:2px
+```
+
+### Complete Mental Model
+
+```
+┌─────────────────────────────────────────┐
+│           User Interaction              │
+└──────────────┬──────────────────────────┘
+               │ (events)
+               ▼
+┌─────────────────────────────────────────┐
+│        Lit Web Components               │
+│  - html`` templates (like JSX)          │
+│  - css`` styles (scoped)                │
+│  - Event handlers                       │
+└──────────────┬──────────────────────────┘
+               │ (actions)
+               ▼
+┌─────────────────────────────────────────┐
+│      StoreController (glue layer)       │
+│  - ReactiveController interface         │
+│  - Subscribes to store                  │
+│  - Triggers requestUpdate()             │
+└──────────────┬──────────────────────────┘
+               │ (selector)
+               ▼
+┌─────────────────────────────────────────┐
+│       Zustand Vanilla Store             │
+│  - Global state (like Context)          │
+│  - Actions (like reducers)              │
+│  - Subscriptions                        │
+└──────────────┬──────────────────────────┘
+               │ (persist middleware)
+               ▼
+┌─────────────────────────────────────────┐
+│  IndexedDB (via idb-keyval)             │
+│  - Automatic persistence                │
+│  - Async storage                        │
+└─────────────────────────────────────────┘
 ```
 
 ## Quick Start Example
 
-### 1. Define a Component
+### 1. Define Store (like Redux/Zustand)
+
+```javascript
+// store/index.js
+import { createStore } from 'zustand/vanilla'
+import { persist } from 'zustand/middleware'
+
+export const store = createStore(
+  persist(
+    (set) => ({
+      count: 0,
+      increment: () => set(s => ({ count: s.count + 1 })),
+    }),
+    { name: 'my-store' }
+  )
+)
+```
+
+### 2. Create Component (like React component)
 
 ```javascript
 // components/counter.js
 import { LitElement, html, css } from 'lit'
+import { StoreController } from '../controllers/store.js'
+import { store } from '../store/index.js'
 
 class Counter extends LitElement {
-  static properties = {
+  // Subscribe to store (like useSelector)
-    count: { type: Number, state: true }
+  #count = new StoreController(this, store, s => s.count)
-  }
-
-  constructor() {
-    super()
-    this.count = 0
-  }
 
   static styles = css`
     button { padding: 1rem; font-size: 1.2rem; }
@@ -116,8 +171,8 @@ class Counter extends LitElement {
   render() {
     return html`
       <div>
-        <p>Count: ${this.count}</p>
+        <p>Count: ${this.#count.value}</p>
-        <button @click=${() => this.count++}>
+        <button @click=${() => store.getState().increment()}>
           Increment
         </button>
       </div>
@@ -128,7 +183,7 @@ class Counter extends LitElement {
 customElements.define('my-counter', Counter)
 ```
 
-### 2. Use in HTML (no build step!)
+### 3. Use in HTML (no build step!)
 
 ```html
 <!DOCTYPE html>
@@ -137,7 +192,9 @@ customElements.define('my-counter', Counter)
   <script type="importmap">
   {
     "imports": {
-      "lit": "https://esm.sh/lit@3"
+      "lit": "https://esm.sh/lit@3",
+      "zustand/vanilla": "https://esm.sh/zustand@5/vanilla",
+      "zustand/middleware": "https://esm.sh/zustand@5/middleware"
     }
   }
   </script>
@@ -149,88 +206,17 @@ customElements.define('my-counter', Counter)
 </html>
 ```
 
-## Component Communication Patterns
-
-### Pattern 1: Shared State in Root
-
-```javascript
-class AppRoot extends LitElement {
-  static properties = {
-    items: { type: Array, state: true }
-  }
-
-  constructor() {
-    super()
-    this.items = []
-  }
-
-  addItem(item) {
-    this.items = [...this.items, item]
-  }
-
-  render() {
-    return html`
-      <child-component 
-        .items=${this.items}
-        @add=${(e) => this.addItem(e.detail.item)}
-      ></child-component>
-    `
-  }
-}
-```
-
-### Pattern 2: Local State in Component
-
-```javascript
-class MyComponent extends LitElement {
-  static properties = {
-    _draft: { type: String, state: true }
-  }
-
-  constructor() {
-    super()
-    this._draft = ''
-  }
-
-  render() {
-    return html`
-      <input 
-        .value=${this._draft}
-        @input=${e => this._draft = e.target.value}
-      />
-    `
-  }
-}
-```
-
 ## Benefits Over React/TSX
 
 ✅ **No build step** - Edit and refresh, instant feedback  
-✅ **Minimal dependencies** - Just Lit, nothing else  
 ✅ **Smaller bundle** - No framework runtime, just standards  
 ✅ **Better encapsulation** - Shadow DOM, scoped styles  
 ✅ **Framework agnostic** - Works anywhere, even in React apps  
 ✅ **Future-proof** - Built on web standards  
-✅ **Easy to learn** - Simple mental model, no complex state management
-
-## When to Use This vs. Full Stack
-
-### Use Lit-Only When:
-- Building small to medium apps
-- Don't need persistence
-- State is simple and hierarchical
-- Want maximum simplicity
-
-### Use Full Stack (main branch) When:
-- Need IndexedDB persistence
-- Complex state shared across many components
-- Need cross-tab synchronization
-- Want time-travel debugging
-- Building larger applications
 
 ## See Also
 
 - [tasks.md](./tasks.md) - Current issues and improvements
 - [Lit Documentation](https://lit.dev)
+- [Zustand Documentation](https://zustand.docs.pmnd.rs)
 - [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
-- [Import Maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)

components/app-root.js

@@ -1,64 +1,44 @@
 import { LitElement, html, css } from "lit";
+import { store} from "../store/index.js";
+import { StoreController } from "../controllers/store.js";
 import "./nav-bar.js";
 import "./page-home.js";
 import "./page-items.js";
 
 class AppRoot extends LitElement {
-    static properties = {
+    #hydrated = new StoreController(this, store, s => s._hydrated);
-        user: { type: Object, state: true },
+    #user = new StoreController(this, store, s => s.user);
-        route: { type: String, state: true },
+    #route = new StoreController(this, store, s => s.route);
-        items: { type: Array, state: true }
-    };
-
-    constructor() {
-        super();
-        this.user = null;
-        this.route = 'home';
-        this.items = [];
-    }
 
     static styles = css`
         :host {
             display: block;
             min-height: 100vh;
         }
+        
+        .loading {
+            display: grid;
+            place-items: center;
+            height: 100vh;
+            opacity: 0.4;
+        }
     `;
 
-    #navigate(route) {
-        this.route = route;
-    }
-
-    #addItem(item) {
-        this.items = [...this.items, item];
-    }
-
-    #removeItem(id) {
-        this.items = this.items.filter(i => i.id !== id);
-    }
-
     render() {
+        if (!this.#hydrated.value) {
+            return html`<div class="loading">loading...</div>`;
+        }
         return html`
-            <nav-bar 
+            <nav-bar .user=${this.#user.value}></nav-bar>
-                .user=${this.user}
-                .route=${this.route}
-                @navigate=${(e) => this.#navigate(e.detail.route)}
-            ></nav-bar>
             <main>${this.#renderRoute()}</main>
         `;
     }
 
     #renderRoute() {
-        switch (this.route) {
+        switch (this.#route.value) {
-            case "home": 
+            case "home": return html`<page-home></page-home>`;
-                return html`<page-home .user=${this.user} .items=${this.items}></page-home>`;
+            case "items": return html`<page-items></page-items>`;
-            case "items": 
+            default: return html`<page-home></page-home>`;
-                return html`<page-items 
-                    .items=${this.items}
-                    @add-item=${(e) => this.#addItem(e.detail.item)}
-                    @remove-item=${(e) => this.#removeItem(e.detail.id)}
-                ></page-items>`;
-            default: 
-                return html`<page-home .user=${this.user} .items=${this.items}></page-home>`;
         }
     }
 }

components/nav-bar.js

@@ -1,10 +1,13 @@
 // components/nav-bar.js
 import { LitElement, html, css } from 'lit'
+import { store } from '../store/index.js'
+import { StoreController } from '../controllers/store.js'
 
 class NavBar extends LitElement {
+  #route = new StoreController(this, store, s => s.route)
+
   static properties = {
-    user: { type: Object },
+    user: { type: Object }
-    route: { type: String }
   }
 
   static styles = css`
@@ -32,18 +35,14 @@ class NavBar extends LitElement {
 
   #navigate(route, e) {
     e.preventDefault()
-    this.dispatchEvent(new CustomEvent('navigate', { 
+    store.getState().navigate(route)
-      detail: { route },
-      bubbles: true,
-      composed: true
-    }))
   }
 
   #link(route, label) {
     return html`
       <a
         href="/${route}"
-        ?active=${this.route === route}
+        ?active=${this.#route.value === route}
         @click=${(e) => this.#navigate(route, e)}
       >${label}</a>
     `
@@ -62,4 +61,4 @@ class NavBar extends LitElement {
   }
 }
 
-customElements.define('nav-bar', NavBar)
+customElements.define('nav-bar', NavBar)

components/page-home.js

@@ -1,11 +1,11 @@
 // components/page-home.js
 import { LitElement, html, css } from 'lit'
+import { store } from '../store/index.js'
+import { StoreController } from '../controllers/store.js'
 
 class PageHome extends LitElement {
-  static properties = {
+  #user  = new StoreController(this, store, s => s.user)
-    user: { type: Object },
+  #items = new StoreController(this, store, s => s.items)
-    items: { type: Array }
-  }
 
   static styles = css`
     :host { display: block; padding: 2rem 1.5rem; }
@@ -25,8 +25,8 @@ class PageHome extends LitElement {
   `
 
   render() {
-    const name = this.user?.name ?? 'there'
+    const name = this.#user.value?.name ?? 'there'
-    const count = this.items?.length ?? 0
+    const count = this.#items.value.length
 
     return html`
       <h1>Hey, ${name}</h1>
@@ -41,4 +41,4 @@ class PageHome extends LitElement {
   }
 }
 
-customElements.define('page-home', PageHome)
+customElements.define('page-home', PageHome)

components/page-items.js

@@ -1,17 +1,16 @@
 // components/page-items.js
 import { LitElement, html, css } from 'lit'
+import { store } from '../store/index.js'
+import { StoreController } from '../controllers/store.js'
 
 class PageItems extends LitElement {
+  #items = new StoreController(this, store, s => s.items)
+
   static properties = {
-    items: { type: Array },
     _draft: { type: String, state: true }
   }
 
-  constructor() {
+  _draft = ''
-    super();
-    this.items = [];
-    this._draft = '';
-  }
 
   static styles = css`
     :host { display: block; padding: 2rem 1.5rem; }
@@ -64,22 +63,12 @@ class PageItems extends LitElement {
   #add() {
     const name = this._draft.trim()
     if (!name) return
-    
+    store.getState().addItem({ id: crypto.randomUUID(), name })
-    this.dispatchEvent(new CustomEvent('add-item', {
-      detail: { item: { id: crypto.randomUUID(), name } },
-      bubbles: true,
-      composed: true
-    }))
-    
     this._draft = ''
   }
 
   #remove(id) {
-    this.dispatchEvent(new CustomEvent('remove-item', {
+    store.getState().removeItem(id)
-      detail: { id },
-      bubbles: true,
-      composed: true
-    }))
   }
 
   #onKeydown(e) {
@@ -87,7 +76,7 @@ class PageItems extends LitElement {
   }
 
   render() {
-    const items = this.items ?? []
+    const items = this.#items.value
 
     return html`
       <h1>Items</h1>
@@ -119,4 +108,4 @@ class PageItems extends LitElement {
   }
 }
 
-customElements.define('page-items', PageItems)
+customElements.define('page-items', PageItems)

controllers/store.js

@@ -0,0 +1,23 @@
+export class StoreController {
+    constructor(host, store, selector) {
+      this.host = host
+      this.store = store
+      this.selector = selector
+      host.addController(this)
+    }
+  
+    hostConnected() {
+      this._unsub = this.store.subscribe(
+        (state) => {
+          const next = this.selector(state)
+          if (next !== this.value) {
+            this.value = next
+            this.host.requestUpdate()
+          }
+        }
+      )
+      this.value = this.selector(this.store.getState())
+    }
+  
+    hostDisconnected() { this._unsub?.() }
+  }

index.html

@@ -8,7 +8,10 @@
     {
         "imports": {
             "lit": "https://esm.sh/lit@3",
-            "lit/decorators.js": "https://esm.sh/lit@3/decorators.js"
+            "lit/decorators.js": "https://esm.sh/lit@3/decorators.js",
+            "zustand/vanilla": "https://esm.sh/zustand@5/vanilla",
+            "zustand/middleware": "https://esm.sh/zustand@5/middleware",
+            "idb-keyval": "https://esm.sh/idb-keyval@6"
         }
     }
     </script>

store/idb.js

@@ -0,0 +1,33 @@
+// lib/idb.js
+import { createStore, get, set, del, entries, clear } from 'idb-keyval'
+
+// Named stores — each maps to a distinct IDBObjectStore
+export const itemsStore = createStore('app-db', 'items')
+export const userStore  = createStore('app-db', 'user')
+export const cacheStore = createStore('app-db', 'cache')
+
+// Typed wrappers — keeps raw idb-keyval calls out of the rest of the app
+// and gives you one place to add validation, logging, or migration logic
+
+export const db = {
+  items: {
+    getAll:  ()          => entries(itemsStore),
+    get:     (id)        => get(id, itemsStore),
+    set:     (id, value) => set(id, value, itemsStore),
+    remove:  (id)        => del(id, itemsStore),
+    clear:   ()          => clear(itemsStore),
+  },
+
+  user: {
+    get:   ()      => get('user', userStore),
+    set:   (value) => set('user', value, userStore),
+    clear: ()      => del('user', userStore),
+  },
+
+  cache: {
+    get:   (key)         => get(key, cacheStore),
+    set:   (key, value)  => set(key, value, cacheStore),
+    remove: (key)        => del(key, cacheStore),
+    clear: ()            => clear(cacheStore),
+  }
+}

store/index.js

@@ -0,0 +1,42 @@
+import { createStore } from 'zustand/vanilla'
+import { persist, createJSONStorage } from 'zustand/middleware'
+import { get, set } from 'idb-keyval'
+
+const storage = createJSONStorage(() => ({
+  getItem: async (name) => {
+    const value = await get(name)
+    return value ?? null
+  },
+  setItem: async (name, value) => {
+    await set(name, value)
+  },
+  removeItem: async (name) => {
+    await del(name)
+  },
+}))
+
+export const store = createStore(
+  persist(
+    (set, get) => ({
+      _hydrated: false,
+      user: null,
+      items: [],
+      route: 'home',
+      setUser: (user) => set({ user }),
+      addItem: (item) => set(s => ({ items: [...s.items, item] })),
+      removeItem: (id) => set(s => ({ items: s.items.filter(i => i.id !== id) })),
+      navigate: (route) => set({ route }),
+    }),
+    {
+      name: 'app-store',
+      storage,
+      onRehydrateStorage: () => {
+        return (state, error) => {
+          if (!error) {
+            store.setState({ _hydrated: true })
+          }
+        }
+      },
+    }
+  )
+)

store/middleware/persistence.js

@@ -0,0 +1,9 @@
+// store/middleware/persistence.js
+import { db } from '../idb.js'
+
+export const makeIdbStorage = (storeName) =>
+  createJSONStorage(() => ({
+    getItem:    (name)        => db[storeName].get(name),
+    setItem:    (name, value) => db[storeName].set(name, value),
+    removeItem: (name)        => db[storeName].remove(name),
+  }))