From 254cda9f85694c1d4a4324df0d219d6c5d265259 Mon Sep 17 00:00:00 2001
From: Adnaan <badr.adnaan@gmail.com>
Date: Tue, 31 Mar 2026 22:18:00 +0530
Subject: [PATCH 1/2] fix: todos example crashes on startup due to stale DB
 schema

The todos example failed to start with "no such column: user_id" when
an old todos.db existed. The migration used CREATE TABLE IF NOT EXISTS
which doesn't modify existing tables.

Fixes:
- Add hasOutdatedSchema() migration that detects old schema via
  PRAGMA table_info and recreates the table
- Replace custom JS search clear button with native input[type=search]
  (framework handles the search event natively)
- Replace inline styles with Pico CSS semantic elements: <s> for
  strikethrough, <nav> for flex layout, hidden attr for visibility,
  <del> for error messages
- Wrap pagination/clearCompleted buttons in forms for reliable action
  routing
- Rewrite README to document actual controller-based API
- Add framework documentation section to CLAUDE.md
- Strengthen CSS rules in CLAUDE.md to prefer semantic HTML over
  inline styles

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md           |  14 ++
 todos/README.md     | 275 +++++++++-----------------------------
 todos/db_manager.go |  45 ++++++-
 todos/todos.tmpl    | 315 ++++++++++++++++++++++++--------------------
 todos/todos_test.go |  44 ++-----
 5 files changed, 299 insertions(+), 394 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index b86bde7..cad7946 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -68,6 +68,18 @@ When a form is submitted, the framework resolves the action in this order:
 - `live-preview/` — Tier 1 with `Change()` method for live updates
 - `chat/` — Tier 1+2 (uses `lvt-scroll` for auto-scroll)
 
+## Framework Documentation
+
+Before writing code, always consult the LiveTemplate reference docs and guides:
+
+- **References:** `https://github.com/livetemplate/livetemplate/docs/references/` — client attributes, server API, action routing
+- **Guides:** `https://github.com/livetemplate/livetemplate/docs/guides/` — progressive complexity, patterns, best practices
+
+Use framework-native solutions instead of custom JavaScript. Common patterns:
+- `input type="search"` has a browser-native clear button; the framework handles the `search` event automatically (no custom JS needed)
+- The `Change()` method auto-wires input/change/search events on named form fields with 300ms debounce
+- Use `hidden` HTML attribute for visibility toggling (not `style="display:none"`)
+
 ## CSS
 
 All examples use [Pico CSS](https://picocss.com/docs) exclusively:
@@ -77,10 +89,12 @@ All examples use [Pico CSS](https://picocss.com/docs) exclusively:
 - Use Pico classes sparingly: `.container`, `.grid`, `.secondary`, `.contrast`, `.outline`
 - Use `aria-invalid="true"` for form validation errors, `<small>` for helper/error text
 - Use `<ins>` for success messages, `<del>` for error messages (with `style="display:block;text-decoration:none"`)
+- Use `<s>` for strikethrough text (e.g., completed todos), `<del>` for removed/error content
 - Use `<mark>` for highlighted/badge text
 - Use `<progress>` for progress bars
 - Use `<hgroup>` for title + subtitle groupings
 - Use `<fieldset role="group">` for inline input+button groups
 - Use `<blockquote>` for callout/info boxes
+- Do NOT write inline `style` attributes. Use Pico semantic elements instead (e.g., `<s>` not `style="text-decoration:line-through"`, `<nav>` not `style="display:flex"`, `hidden` not `style="display:none"`)
 - Do NOT write custom CSS. If Pico cannot express a style, ask before adding custom CSS.
 - Pico CSS variables (`--pico-*`) may be used for theming when semantic markup is insufficient
diff --git a/todos/README.md b/todos/README.md
index 6cbb9d7..acb0786 100644
--- a/todos/README.md
+++ b/todos/README.md
@@ -1,261 +1,112 @@
-# LiveTemplate Todo App Example
+# LiveTemplate Todo App
 
-A real-time todo application demonstrating LiveTemplate's reactive state management with [Pico CSS](https://picocss.com/) for semantic, class-less styling.
+A real-time todo application demonstrating LiveTemplate's controller pattern with SQLite persistence, basic authentication, search, sorting, and pagination. Styled with [Pico CSS](https://picocss.com/).
 
 ## Features
 
-- **Add todos** - Create new tasks via form submission
+- **Basic authentication** - Per-user todo lists (alice/password, bob/password)
+- **Add todos** - Create new tasks via form submission with validation
 - **Toggle completion** - Mark tasks as done/undone with checkboxes
 - **Delete todos** - Remove individual tasks
 - **Clear completed** - Bulk remove all completed tasks
+- **Search** - Filter todos by text
+- **Sort** - Newest first, oldest first, alphabetical (A-Z / Z-A)
+- **Pagination** - 3 items per page with navigation controls
 - **Live statistics** - Real-time total, completed, and remaining counts
-- **Reactive updates** - Changes automatically broadcast to all connected clients
-- **Semantic CSS** - Beautiful UI using Pico CSS without custom classes
-- **Transport-agnostic** - Works over WebSocket or plain HTTP/AJAX
+- **Reactive updates** - Changes broadcast to all connected clients
+- **SQLite persistence** - Todos survive server restarts
 
-## Running the Example
+## Quick Start
 
-1. **Start the server:**
-
-   From project root:
-   ```bash
-   go run examples/todos/main.go
-   ```
-
-   Or from the todos directory:
-   ```bash
-   cd examples/todos
-   go run main.go
-   ```
+```bash
+cd examples/todos
+go run .
+```
 
-   With custom port:
-   ```bash
-   PORT=8081 go run main.go
-   ```
+Open <http://localhost:8080> and log in with `alice` / `password`.
 
-2. **Open your browser:**
-   Navigate to `http://localhost:8080`
+With a custom port:
 
-3. **Interact with todos:**
-   - Type a task in the input field and click "Add"
-   - Check/uncheck boxes to toggle completion
-   - Click "Delete" to remove a task
-   - Click "Clear Completed" to remove all done tasks
-   - Watch statistics update in real-time
+```bash
+PORT=8081 go run .
+```
 
 ## How It Works
 
-### Server Side (Go)
+### Controller Pattern
 
-Simple reactive API with array state management:
+The app uses LiveTemplate's controller pattern where each action maps to a typed method:
 
 ```go
-type TodoItem struct {
-    ID        string
-    Text      string
-    Completed bool
-}
-
-type TodoState struct {
-    Title          string
-    Todos          []TodoItem
-    TotalCount     int
-    CompletedCount int
-    RemainingCount int
+type TodoController struct {
+    Queries *db.Queries
 }
 
-// Implement the Store interface
-func (s *TodoState) Change(action string, data map[string]interface{}) {
-    switch action {
-    case "add":
-        text := livetemplate.GetString(data, "text")
-        s.Todos = append(s.Todos, TodoItem{
-            ID:   fmt.Sprintf("todo-%d", time.Now().UnixNano()),
-            Text: text,
-        })
-    case "toggle":
-        id := livetemplate.GetString(data, "id")
-        // Find and toggle todo
-    case "delete":
-        id := livetemplate.GetString(data, "id")
-        // Remove todo from slice
-    case "clear_completed":
-        // Filter out completed todos
+func (c *TodoController) Add(state TodoState, ctx *livetemplate.Context) (TodoState, error) {
+    var input AddInput
+    if err := ctx.BindAndValidate(&input, validate); err != nil {
+        return state, err
     }
-
-    s.updateStats()
+    // Create todo in database, reload list
+    return c.loadTodos(dbCtx, state, ctx.UserID())
 }
 
-func main() {
-    state := &TodoState{Title: "Todo App", Todos: []TodoItem{}}
-
-    // Auto-discovers todos.tmpl in current directory
-    tmpl := livetemplate.New("todos")
-
-    // Handle() auto-configures: WebSocket, HTTP, state cloning, updates
-    http.Handle("/", tmpl.Handle(state))
-    http.ListenAndServe(":8080", nil)
-}
+func (c *TodoController) Toggle(state TodoState, ctx *livetemplate.Context) (TodoState, error) { ... }
+func (c *TodoController) Delete(state TodoState, ctx *livetemplate.Context) (TodoState, error) { ... }
+func (c *TodoController) ClearCompleted(state TodoState, ctx *livetemplate.Context) (TodoState, error) { ... }
+func (c *TodoController) Search(state TodoState, ctx *livetemplate.Context) (TodoState, error) { ... }
+func (c *TodoController) Sort(state TodoState, ctx *livetemplate.Context) (TodoState, error) { ... }
+func (c *TodoController) NextPage(state TodoState, ctx *livetemplate.Context) (TodoState, error) { ... }
+func (c *TodoController) PrevPage(state TodoState, ctx *livetemplate.Context) (TodoState, error) { ... }
 ```
 
-**Key concepts:**
-- **Array State Management**: Todos stored as slice, automatically tracked
-- **Auto-discovery**: Automatically finds and parses `todos.tmpl`
-- **Auto Updates**: Handle() automatically generates and sends updates after Change()
-- **Auto Cloning**: Each WebSocket connection gets its own state copy
-- **Session Management**: HTTP connections get session-based persistence
-
-### Client Side (Pico CSS + LiveTemplate)
-
-**Zero JavaScript needed** - Pico CSS + LiveTemplate handles everything:
+Actions are routed from HTML via form `name` and button `name` attributes (Tier 1 pattern):
 
 ```html
-<!-- Pico CSS via CDN - no custom classes needed! -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
-
-<main class="container">
-    <article>
-        <!-- Add Todo Form -->
-        <form lvt-submit="add">
-            <fieldset role="group">
-                <input type="text" name="text" placeholder="What needs to be done?" required>
-                <button type="submit">Add</button>
-            </fieldset>
-        </form>
-
-        <!-- Statistics Table -->
-        <table>
-            <tbody>
-                <tr><td>Total</td><td><strong>{{.TotalCount}}</strong></td></tr>
-                <tr><td>Completed</td><td><strong>{{.CompletedCount}}</strong></td></tr>
-                <tr><td>Remaining</td><td><strong>{{.RemainingCount}}</strong></td></tr>
-            </tbody>
-        </table>
-
-        <!-- Todo List -->
-        {{range .Todos}}
-        <tr data-key="{{.ID}}">
-            <td>
-                <input type="checkbox" {{if .Completed}}checked{{end}}
-                       lvt-change="toggle" lvt-data-id="{{.ID}}">
-            </td>
-            <td>{{.Text}}</td>
-            <td>
-                <button lvt-click="delete" lvt-data-id="{{.ID}}">Delete</button>
-            </td>
-        </tr>
-        {{end}}
-    </article>
-</main>
-
-<!-- Auto-initializing client library -->
-<script src="livetemplate-client.js"></script>
+<!-- Form name="add" routes to Add() method -->
+<form method="POST" name="add">
+    <input type="text" name="text" placeholder="What needs to be done?" required />
+    <button type="submit" name="add">Add</button>
+</form>
+
+<!-- Hidden input passes data; form name routes to Toggle() -->
+<form method="POST" name="toggle">
+    <input type="hidden" name="id" value="{{ .ID }}" />
+    <input type="checkbox" onchange="this.form.requestSubmit()" />
+</form>
+
+<!-- Button name routes to ClearCompleted() -->
+<button name="clearCompleted">Clear Completed</button>
 ```
 
-**Pico CSS features used:**
-- `<main class="container">` - Responsive centered layout
-- `<article>` - Card-style sections with automatic spacing
-- `<form>` with `<fieldset role="group">` - Inline form controls
-- `<table>` - Clean, styled tables
-- `<button>` - Semantic button styling (primary, secondary variants)
-- Semantic HTML elements automatically styled
+### Authentication
 
-**LiveTemplate features:**
-- `lvt-submit` - Form submission with all field values
-- `lvt-change` - Checkbox change events
-- `lvt-click` - Button click events
-- `lvt-data-*` - Custom data passed to actions
-- `data-key` - Item tracking for range updates
+Basic auth with hardcoded demo users. `ctx.UserID()` returns the authenticated username, used to isolate each user's todos in SQLite:
 
-## Architecture
-
-```
-Browser                    WebSocket/HTTP              Go Server
-┌─────────────────┐        ┌──────────┐               ┌──────────────────┐
-│ todos.tmpl      │        │          │               │ TodoState        │
-│ (Pico CSS)      │        │          │               │   Todos []Item   │
-│                 │        │          │               │   Stats          │
-│ [Add] [Delete]  │◄──────►│  /       │◄─────────────►│                  │
-│ [✓] Checkboxes  │        │          │               │ Change(action,   │
-│                 │        │          │               │   data)          │
-│ LiveTemplate    │        │          │               │                  │
-│ Client JS       │        │ Auto-    │               │ Handle()         │
-│                 │        │ detects  │               │ - Clones state   │
-│ lvt-* attrs     │        │ transport│               │ - Generates      │
-│ - submit        │        │          │               │   updates        │
-│ - click         │        │          │               │ - Broadcasts     │
-│ - change        │        │          │               │                  │
-└─────────────────┘        └──────────┘               └──────────────────┘
-```
-
-## Example Update Payloads
-
-**Initial State (no todos):**
-```json
-{
-  "s": ["<main class=\"container\">...", "...</main>"],
-  "0": "Todo App",
-  "1": "No tasks yet. Add one above!"
-}
+```go
+auth := livetemplate.NewBasicAuthenticator(func(username, password string) (bool, error) {
+    users := map[string]string{"alice": "password", "bob": "password"}
+    pass, ok := users[username]
+    return ok && pass == password, nil
+})
 ```
 
-**After Adding Todo (only changed values):**
-```json
-{
-  "1": "<table><tbody><tr data-key=\"todo-1234\">...",
-  "2": "1",
-  "3": "0",
-  "4": "1"
-}
-```
+### Database
 
-This demonstrates LiveTemplate's bandwidth efficiency - subsequent updates contain only changed dynamic values, not the full HTML.
+SQLite via [sqlc](https://sqlc.dev/)-generated queries. The `db/` directory contains generated code from `queries.sql`. Schema migrations run automatically on startup, including detection and recreation of outdated schemas.
 
 ## Testing
 
-### WebSocket Integration Test
-
-```bash
-go test -v -run TestWebSocketBasic
-```
-
-Tests:
-- WebSocket connection establishment
-- Add todo action
-- Toggle completion action
-- Response validation
-
 ### Browser E2E Test
 
 ```bash
 go test -v -run TestTodosE2E
 ```
 
-Tests:
-- Initial page load with Pico CSS
-- WebSocket connectivity
-- LiveTemplate wrapper preservation
-- Semantic HTML structure
-
 Requires Docker for Chrome headless testing.
 
 ## Development Notes
 
 - **Port**: Defaults to `:8080`, override with `PORT` environment variable
-- **Endpoint**: `/` handles both WebSocket upgrades and HTTP POST requests
-- **Template Path**: Reads from `examples/todos/todos.tmpl`
-- **Client Library**: Serves via `internal/testing.ServeClientLibrary()` (dev only)
-- **State Isolation**: Each WebSocket connection gets its own todo list
-- **Session Management**: HTTP connections persist state via cookies
-- **Pico CSS**: Loaded from CDN, no build step required
-
-## Why Pico CSS?
-
-- **Zero configuration** - Works with semantic HTML
-- **No custom classes** - `<article>`, `<table>`, `<form>` are pre-styled
-- **Responsive** - Mobile-friendly by default
-- **Dark mode** - Automatic theme switching
-- **Accessible** - Proper ARIA roles and keyboard navigation
-- **Minimal** - ~10KB gzipped
-
-Perfect for LiveTemplate demos where you want beautiful UIs without CSS complexity!
+- **Database**: `todos.db` in the current directory (`:memory:` when `TEST_MODE=1`)
+- **Client Library**: Served via `e2etest.ServeClientLibrary` in dev mode, CDN in production
diff --git a/todos/db_manager.go b/todos/db_manager.go
index 322ee83..c51aff9 100644
--- a/todos/db_manager.go
+++ b/todos/db_manager.go
@@ -42,8 +42,20 @@ func InitDB(dbPath string) (*db.Queries, error) {
 	return queries, nil
 }
 
-// runMigrations creates the database schema
-func runMigrations(db *sql.DB) error {
+// runMigrations creates the database schema, handling upgrades from older versions.
+func runMigrations(database *sql.DB) error {
+	// Check if the todos table exists with an outdated schema (missing user_id column).
+	// CREATE TABLE IF NOT EXISTS won't modify an existing table, so we must detect
+	// and drop the old schema before recreating.
+	if needsRecreate, err := hasOutdatedSchema(database); err != nil {
+		return fmt.Errorf("checking schema: %w", err)
+	} else if needsRecreate {
+		log.Println("Detected outdated todos table (missing user_id column), recreating...")
+		if _, err := database.Exec("DROP TABLE IF EXISTS todos"); err != nil {
+			return fmt.Errorf("dropping outdated table: %w", err)
+		}
+	}
+
 	schema := `
 CREATE TABLE IF NOT EXISTS todos (
   id TEXT PRIMARY KEY,
@@ -57,10 +69,37 @@ CREATE INDEX IF NOT EXISTS idx_todos_created_at ON todos(created_at);
 CREATE INDEX IF NOT EXISTS idx_todos_completed ON todos(completed);
 CREATE INDEX IF NOT EXISTS idx_todos_user_id ON todos(user_id);
 `
-	_, err := db.Exec(schema)
+	_, err := database.Exec(schema)
 	return err
 }
 
+// hasOutdatedSchema returns true if the todos table exists but lacks the user_id column.
+func hasOutdatedSchema(database *sql.DB) (bool, error) {
+	rows, err := database.Query("PRAGMA table_info(todos)")
+	if err != nil {
+		return false, err
+	}
+	defer rows.Close()
+
+	var hasTable, hasUserID bool
+	for rows.Next() {
+		hasTable = true
+		var cid int
+		var name, ctype string
+		var notnull int
+		var dfltValue sql.NullString
+		var pk int
+		if err := rows.Scan(&cid, &name, &ctype, &notnull, &dfltValue, &pk); err != nil {
+			return false, err
+		}
+		if name == "user_id" {
+			hasUserID = true
+		}
+	}
+
+	return hasTable && !hasUserID, rows.Err()
+}
+
 // CloseDB closes the database connection
 func CloseDB() {
 	if database != nil {
diff --git a/todos/todos.tmpl b/todos/todos.tmpl
index 9d6ca39..55a9f11 100644
--- a/todos/todos.tmpl
+++ b/todos/todos.tmpl
@@ -1,141 +1,157 @@
 {{/* Template Partials */}}
 
-{{define "add-form"}}
-<form method="POST" name="add">
-  <fieldset role="group">
-    <label for="new-todo-text" class="visually-hidden">New todo text</label>
-    <input
-      type="text"
-      id="new-todo-text"
-      name="text"
-      placeholder="What needs to be done?"
-      required
-      aria-required="true"
-      {{ if .lvt.HasError "text" }}aria-invalid="true"{{ end }}
-    />
-    <button type="submit" name="add">Add</button>
-  </fieldset>
-  {{ if .lvt.HasError "text" }}
-    <small style="color: var(--pico-del-color);">{{ .lvt.Error "text" }}</small>
-  {{ end }}
-</form>
-{{end}}
-
-{{define "stats"}}
-<!-- Statistics -->
-<p>
-  <small>
-    Total: <strong>{{ .TotalCount }}</strong> •
-    Completed: <strong>{{ .CompletedCount }}</strong> •
-    Remaining: <strong>{{ .RemainingCount }}</strong>
-  </small>
-</p>
-{{end}}
-
-{{define "search-form"}}
-<div style="position: relative;">
-  <style>input[type="search"]::-webkit-search-cancel-button { -webkit-appearance: none; display: none; }</style>
-  <label for="search-todos" class="visually-hidden">Search todos</label>
-  <input
-    type="search"
-    id="search-todos"
-    name="query"
-    placeholder="Search todos..."
-    value="{{ .SearchQuery }}"
-    style="padding-right: 2rem;"
-  />
-  <button type="button" name="search" onclick="var input=this.previousElementSibling; input.value=''; input.dispatchEvent(new Event('input', { bubbles: true })); this.style.display='none';" style="position: absolute; right: 0.5rem; top: 50%; transform: translateY(-50%); background: none; border: none; cursor: pointer; padding: 0.25rem; color: #9ca3af; font-size: 1.25rem; line-height: 1;{{if not .SearchQuery}} display: none;{{end}}" title="Clear search">&times;</button>
-</div>
-{{end}}
-
-{{define "sort-select"}}
-<div>
-  <label for="sort_by">Sort by:</label>
-  <select name="sort_by" id="sort_by">
-    <option value="" {{ if eq .SortBy "" }}selected{{ end }}>
-      Newest First
-    </option>
-    <option value="alphabetical" {{ if eq .SortBy "alphabetical" }}selected{{ end }}>
-      Alphabetical (A-Z)
-    </option>
-    <option value="reverse_alphabetical" {{ if eq .SortBy "reverse_alphabetical" }}selected{{ end }}>
-      Alphabetical (Z-A)
-    </option>
-    <option value="oldest_first" {{ if eq .SortBy "oldest_first" }}selected{{ end }}>
-      Oldest First
-    </option>
-  </select>
-</div>
-{{end}}
-
-{{define "todo-item"}}
-<tr data-key="{{ .ID }}">
-  <td>
-    <form method="POST" name="toggle" style="margin:0;">
-      <input type="hidden" name="id" value="{{ .ID }}">
+{{ define "add-form" }}
+  <form method="POST" name="add">
+    <fieldset role="group">
+      <label for="new-todo-text" class="visually-hidden">New todo text</label>
       <input
-        type="checkbox"
-        {{ if .Completed }}checked{{ end }}
-        onchange="this.form.requestSubmit()"
-        aria-label="Toggle completion"
+        type="text"
+        id="new-todo-text"
+        name="text"
+        placeholder="What needs to be done?"
+        required
+        aria-required="true"
+        {{ if .lvt.HasError "text" }}aria-invalid="true"{{ end }}
       />
-      <button type="submit" name="toggle" hidden>Toggle</button>
-    </form>
-  </td>
-  <td style="{{ if .Completed }}text-decoration: line-through; opacity: 0.6;{{ end }}">
-    {{ .Text }}
-  </td>
-  <td>
-    <form method="POST" name="delete" style="margin:0;">
-      <input type="hidden" name="id" value="{{ .ID }}">
-      <button type="submit" name="delete" class="secondary" aria-label="Delete this todo">
-        Delete
-      </button>
-    </form>
-  </td>
-</tr>
-{{end}}
-
-{{define "pagination"}}
-<nav
-  data-pagination
-  aria-label="Page navigation"
-  data-visible="{{ if .ShowPagination }}true{{ else }}false{{ end }}"
-  style="display: {{ if .ShowPagination }}block{{ else }}none{{ end }};"
-  {{ if not .ShowPagination }}hidden{{ end }}
->
-  <ul style="display: flex; justify-content: center; align-items: center; gap: 1rem; list-style: none; padding: 0;">
-    <li>
-      <button
-        name="prevPage"
-        data-disabled="{{ if .PrevDisabled }}true{{ else }}false{{ end }}"
-        {{ if .PrevDisabled }}disabled aria-disabled="true"{{ end }}
-        class="secondary"
-        aria-label="Go to previous page"
+      <button type="submit" name="add">Add</button>
+    </fieldset>
+    {{ if .lvt.HasError "text" }}
+      <del style="display:block;text-decoration:none">{{ .lvt.Error "text" }}</del>
+    {{ end }}
+  </form>
+{{ end }}
+
+{{ define "stats" }}
+  <!-- Statistics -->
+  <p>
+    <small>
+      Total: <strong>{{ .TotalCount }}</strong> • Completed:
+      <strong>{{ .CompletedCount }}</strong> • Remaining:
+      <strong>{{ .RemainingCount }}</strong>
+    </small>
+  </p>
+{{ end }}
+
+{{ define "search-form" }}
+  <div>
+    <label for="search-todos" class="visually-hidden">Search todos</label>
+    <input
+      type="search"
+      id="search-todos"
+      name="query"
+      placeholder="Search todos..."
+      value="{{ .SearchQuery }}"
+    />
+  </div>
+{{ end }}
+
+{{ define "sort-select" }}
+  <div>
+    <label for="sort_by">Sort by:</label>
+    <select name="sort_by" id="sort_by">
+      <option value="" {{ if eq .SortBy "" }}selected{{ end }}>
+        Newest First
+      </option>
+      <option
+        value="alphabetical"
+        {{ if eq .SortBy "alphabetical" }}selected{{ end }}
       >
-        Previous
-      </button>
-    </li>
-    <li>
-      <small>Page {{ .CurrentPage }} of {{ .TotalPages }}</small>
-    </li>
-    <li>
-      <button
-        name="nextPage"
-        data-disabled="{{ if .NextDisabled }}true{{ else }}false{{ end }}"
-        {{ if .NextDisabled }}disabled aria-disabled="true"{{ end }}
-        class="secondary"
-        aria-label="Go to next page"
+        Alphabetical (A-Z)
+      </option>
+      <option
+        value="reverse_alphabetical"
+        {{ if eq .SortBy "reverse_alphabetical" }}selected{{ end }}
       >
-        Next
-      </button>
-    </li>
-  </ul>
-</nav>
-{{end}}
+        Alphabetical (Z-A)
+      </option>
+      <option
+        value="oldest_first"
+        {{ if eq .SortBy "oldest_first" }}selected{{ end }}
+      >
+        Oldest First
+      </option>
+    </select>
+  </div>
+{{ end }}
+
+{{ define "todo-item" }}
+  <tr data-key="{{ .ID }}">
+    <td>
+      <form method="POST" name="toggle">
+        <input type="hidden" name="id" value="{{ .ID }}" />
+        <input
+          type="checkbox"
+          {{ if .Completed }}checked{{ end }}
+          onchange="this.form.requestSubmit()"
+          aria-label="Toggle completion"
+        />
+        <button type="submit" name="toggle" hidden>Toggle</button>
+      </form>
+    </td>
+    <td>
+      {{ if .Completed }}<s>{{ .Text }}</s>{{ else }}{{ .Text }}{{ end }}
+    </td>
+    <td>
+      <form method="POST" name="delete">
+        <input type="hidden" name="id" value="{{ .ID }}" />
+        <button
+          type="submit"
+          name="delete"
+          class="secondary"
+          aria-label="Delete this todo"
+        >
+          Delete
+        </button>
+      </form>
+    </td>
+  </tr>
+{{ end }}
+
+{{ define "pagination" }}
+  <nav
+    data-pagination
+    aria-label="Page navigation"
+    {{ if not .ShowPagination }}hidden{{ end }}
+  >
+    <ul>
+      <li>
+        <form method="POST">
+          <button
+            type="submit"
+            name="prevPage"
+            data-disabled="{{- if .PrevDisabled -}}true{{- else -}}false{{- end -}}"
+            {{ if .PrevDisabled }}disabled aria-disabled="true"{{ end }}
+            class="secondary"
+            aria-label="Go to previous page"
+          >
+            Previous
+          </button>
+        </form>
+      </li>
+      <li>
+        <small>Page {{ .CurrentPage }} of {{ .TotalPages }}</small>
+      </li>
+      <li>
+        <form method="POST">
+          <button
+            type="submit"
+            name="nextPage"
+            data-disabled="{{- if .NextDisabled -}}true{{- else -}}false{{- end -}}"
+            {{ if .NextDisabled }}disabled aria-disabled="true"{{ end }}
+            class="secondary"
+            aria-label="Go to next page"
+          >
+            Next
+          </button>
+        </form>
+      </li>
+    </ul>
+  </nav>
+{{ end }}
 
 {{/* Main Template */}}
 
+
 <!DOCTYPE html>
 <html lang="en" data-theme="light">
   <head>
@@ -167,20 +183,24 @@
         <header>
           <h1>{{ .Title }}</h1>
           <p>A simple todo app with real-time updates</p>
-          {{ if .Username }}<p><small>Logged in as: <strong>{{ .Username }}</strong></small></p>{{ end }}
+          {{ if .Username }}
+            <p>
+              <small>Logged in as: <strong>{{ .Username }}</strong></small>
+            </p>
+          {{ end }}
         </header>
 
         {{/* Add Todo Form */}}
-        {{template "add-form" .}}
+        {{ template "add-form" . }}
 
         {{/* Statistics */}}
-        {{template "stats" .}}
+        {{ template "stats" . }}
 
         {{/* Search */}}
-        {{template "search-form" .}}
+        {{ template "search-form" . }}
 
         {{/* Sort */}}
-        {{template "sort-select" .}}
+        {{ template "sort-select" . }}
 
         {{/* Todo List */}}
         <section>
@@ -188,11 +208,14 @@
           <table>
             <tbody>
               {{ range .PaginatedTodos }}
-                {{template "todo-item" .}}
+                {{ template "todo-item" . }}
               {{ end }}
             </tbody>
           </table>
-          <p data-empty-state {{ if gt (len .PaginatedTodos) 0 }}hidden{{ end }}>
+          <p
+            data-empty-state
+            {{ if gt (len .PaginatedTodos) 0 }}hidden{{ end }}
+          >
             {{ if ne .SearchQuery "" }}
               <small>No todos found matching "{{ .SearchQuery }}"</small>
             {{ else }}
@@ -201,12 +224,14 @@
           </p>
 
           {{/* Pagination Controls */}}
-          {{template "pagination" .}}
+          {{ template "pagination" . }}
 
           {{ if gt .CompletedCount 0 }}
-            <button name="clearCompleted" class="secondary">
-              Clear Completed ({{ .CompletedCount }})
-            </button>
+            <form method="POST">
+              <button type="submit" name="clearCompleted" class="secondary">
+                Clear Completed ({{ .CompletedCount }})
+              </button>
+            </form>
           {{ end }}
         </section>
 
@@ -216,10 +241,10 @@
       </article>
     </main>
 
-    {{if .lvt.DevMode}}
-    <script src="/livetemplate-client.js"></script>
-    {{else}}
-    <script src="https://cdn.jsdelivr.net/npm/@livetemplate/client@latest/dist/livetemplate-client.browser.js"></script>
-    {{end}}
+    {{ if .lvt.DevMode }}
+      <script src="/livetemplate-client.js"></script>
+    {{ else }}
+      <script src="https://cdn.jsdelivr.net/npm/@livetemplate/client@latest/dist/livetemplate-client.browser.js"></script>
+    {{ end }}
   </body>
 </html>
diff --git a/todos/todos_test.go b/todos/todos_test.go
index 049ea7d..f42afc5 100644
--- a/todos/todos_test.go
+++ b/todos/todos_test.go
@@ -436,14 +436,10 @@ func TestTodosE2E(t *testing.T) {
 				Text    string `json:"text"`
 			}
 			paginationState struct {
-				HiddenAttr  bool   `json:"hiddenAttr"`
-				Display     string `json:"display"`
-				DataVisible string `json:"dataVisible"`
+				HiddenAttr bool `json:"hiddenAttr"`
 			}
 			paginationVisibleState struct {
-				HiddenAttr  bool   `json:"hiddenAttr"`
-				Display     string `json:"display"`
-				DataVisible string `json:"dataVisible"`
+				HiddenAttr bool `json:"hiddenAttr"`
 			}
 			debugInfo   string
 			consoleLogs string
@@ -536,15 +532,8 @@ func TestTodosE2E(t *testing.T) {
 			chromedp.Evaluate(`
 				(() => {
 					const nav = document.querySelector('[data-pagination]');
-					if (!nav) {
-						return { hiddenAttr: true, display: 'none', dataVisible: 'false' };
-					}
-					const style = window.getComputedStyle(nav);
-					return {
-						hiddenAttr: nav.hasAttribute('hidden'),
-						display: style.display,
-						dataVisible: nav.dataset.visible || ''
-					};
+					if (!nav) return { hiddenAttr: true };
+					return { hiddenAttr: nav.hasAttribute('hidden') };
 				})();
 			`, &paginationState),
 			chromedp.OuterHTML(`section`, &html, chromedp.ByQuery),
@@ -594,11 +583,8 @@ func TestTodosE2E(t *testing.T) {
 		if !strings.Contains(emptyState.Text, "No todos found matching \"NonExistent\"") {
 			t.Errorf("Empty state text unexpected: %q", emptyState.Text)
 		}
-		if paginationState.Display != "none" {
-			t.Errorf("Pagination controls should be hidden (display none) when no todos match search. State: %+v", paginationState)
-		}
-		if paginationState.DataVisible != "false" {
-			t.Errorf("Pagination data-visible should be 'false' when hidden. State: %+v", paginationState)
+		if !paginationState.HiddenAttr {
+			t.Errorf("Pagination should have hidden attribute when no todos match search. State: %+v", paginationState)
 		}
 
 		t.Log("✅ Empty search results handled correctly")
@@ -619,26 +605,16 @@ func TestTodosE2E(t *testing.T) {
 			chromedp.Evaluate(`
 				(() => {
 					const nav = document.querySelector('[data-pagination]');
-					if (!nav) {
-						return { hiddenAttr: true, display: 'none', dataVisible: 'false' };
-					}
-					const style = window.getComputedStyle(nav);
-					return {
-						hiddenAttr: nav.hasAttribute('hidden'),
-						display: style.display,
-						dataVisible: nav.dataset.visible || ''
-					};
+					if (!nav) return { hiddenAttr: true };
+					return { hiddenAttr: nav.hasAttribute('hidden') };
 				})();
 			`, &paginationVisibleState),
 		)
 		if err != nil {
 			t.Fatalf("Failed to verify pagination visibility after clearing search: %v", err)
 		}
-		if paginationVisibleState.Display != "block" {
-			t.Errorf("Pagination controls should be visible (display block) after clearing search. State: %+v", paginationVisibleState)
-		}
-		if paginationVisibleState.DataVisible != "true" {
-			t.Errorf("Pagination data-visible should be 'true' after clearing search. State: %+v", paginationVisibleState)
+		if paginationVisibleState.HiddenAttr {
+			t.Errorf("Pagination should NOT have hidden attribute after clearing search. State: %+v", paginationVisibleState)
 		}
 
 		t.Log("✅ Search cleared successfully")

From 98dbca48e3f4a37ebd46dd21b886b618dd5c9063 Mon Sep 17 00:00:00 2001
From: Adnaan <badr.adnaan@gmail.com>
Date: Wed, 1 Apr 2026 00:23:17 +0530
Subject: [PATCH 2/2] fix: address Copilot review comments

- Fix README Quick Start path (cd todos, not cd examples/todos)
- Use non-destructive ALTER TABLE migration instead of DROP/recreate
- Rename shadowed database parameter back to db
- Fix GitHub doc URLs to use /tree/main/ for navigable links
- Resolve inline style inconsistency: carve out explicit exception
  for the standardized <ins>/<del> block-level pattern in CLAUDE.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md           |  8 ++++----
 todos/README.md     |  2 +-
 todos/db_manager.go | 20 ++++++++++----------
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index cad7946..ef9c994 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -72,8 +72,8 @@ When a form is submitted, the framework resolves the action in this order:
 
 Before writing code, always consult the LiveTemplate reference docs and guides:
 
-- **References:** `https://github.com/livetemplate/livetemplate/docs/references/` — client attributes, server API, action routing
-- **Guides:** `https://github.com/livetemplate/livetemplate/docs/guides/` — progressive complexity, patterns, best practices
+- **References:** `https://github.com/livetemplate/livetemplate/tree/main/docs/references/` — client attributes, server API, action routing
+- **Guides:** `https://github.com/livetemplate/livetemplate/tree/main/docs/guides/` — progressive complexity, patterns, best practices
 
 Use framework-native solutions instead of custom JavaScript. Common patterns:
 - `input type="search"` has a browser-native clear button; the framework handles the `search` event automatically (no custom JS needed)
@@ -88,13 +88,13 @@ All examples use [Pico CSS](https://picocss.com/docs) exclusively:
 - Use semantic HTML — Pico auto-styles: `<article>` (cards), `<dialog>` (modals), `<details>` (accordions), `<table>`, `<nav>`, `<progress>`
 - Use Pico classes sparingly: `.container`, `.grid`, `.secondary`, `.contrast`, `.outline`
 - Use `aria-invalid="true"` for form validation errors, `<small>` for helper/error text
-- Use `<ins>` for success messages, `<del>` for error messages (with `style="display:block;text-decoration:none"`)
+- Use `<ins>` for success messages, `<del>` for error messages, using the standardized inline style `style="display:block;text-decoration:none"` when rendering them as block-level alerts
 - Use `<s>` for strikethrough text (e.g., completed todos), `<del>` for removed/error content
 - Use `<mark>` for highlighted/badge text
 - Use `<progress>` for progress bars
 - Use `<hgroup>` for title + subtitle groupings
 - Use `<fieldset role="group">` for inline input+button groups
 - Use `<blockquote>` for callout/info boxes
-- Do NOT write inline `style` attributes. Use Pico semantic elements instead (e.g., `<s>` not `style="text-decoration:line-through"`, `<nav>` not `style="display:flex"`, `hidden` not `style="display:none"`)
+- Do NOT write inline `style` attributes, except for the standardized `<ins>`/`<del>` block-level pattern above. Use Pico semantic elements instead (e.g., `<s>` not `style="text-decoration:line-through"`, `<nav>` not `style="display:flex"`, `hidden` not `style="display:none"`)
 - Do NOT write custom CSS. If Pico cannot express a style, ask before adding custom CSS.
 - Pico CSS variables (`--pico-*`) may be used for theming when semantic markup is insufficient
diff --git a/todos/README.md b/todos/README.md
index acb0786..a8e84c4 100644
--- a/todos/README.md
+++ b/todos/README.md
@@ -19,7 +19,7 @@ A real-time todo application demonstrating LiveTemplate's controller pattern wit
 ## Quick Start
 
 ```bash
-cd examples/todos
+cd todos
 go run .
 ```
 
diff --git a/todos/db_manager.go b/todos/db_manager.go
index c51aff9..8820904 100644
--- a/todos/db_manager.go
+++ b/todos/db_manager.go
@@ -43,16 +43,16 @@ func InitDB(dbPath string) (*db.Queries, error) {
 }
 
 // runMigrations creates the database schema, handling upgrades from older versions.
-func runMigrations(database *sql.DB) error {
+func runMigrations(db *sql.DB) error {
 	// Check if the todos table exists with an outdated schema (missing user_id column).
 	// CREATE TABLE IF NOT EXISTS won't modify an existing table, so we must detect
-	// and drop the old schema before recreating.
-	if needsRecreate, err := hasOutdatedSchema(database); err != nil {
+	// and migrate the old schema before ensuring the current one.
+	if needsMigration, err := hasOutdatedSchema(db); err != nil {
 		return fmt.Errorf("checking schema: %w", err)
-	} else if needsRecreate {
-		log.Println("Detected outdated todos table (missing user_id column), recreating...")
-		if _, err := database.Exec("DROP TABLE IF EXISTS todos"); err != nil {
-			return fmt.Errorf("dropping outdated table: %w", err)
+	} else if needsMigration {
+		log.Println("Detected outdated todos table (missing user_id column), adding column...")
+		if _, err := db.Exec(`ALTER TABLE todos ADD COLUMN user_id TEXT NOT NULL DEFAULT ''`); err != nil {
+			return fmt.Errorf("adding user_id column: %w", err)
 		}
 	}
 
@@ -69,13 +69,13 @@ CREATE INDEX IF NOT EXISTS idx_todos_created_at ON todos(created_at);
 CREATE INDEX IF NOT EXISTS idx_todos_completed ON todos(completed);
 CREATE INDEX IF NOT EXISTS idx_todos_user_id ON todos(user_id);
 `
-	_, err := database.Exec(schema)
+	_, err := db.Exec(schema)
 	return err
 }
 
 // hasOutdatedSchema returns true if the todos table exists but lacks the user_id column.
-func hasOutdatedSchema(database *sql.DB) (bool, error) {
-	rows, err := database.Query("PRAGMA table_info(todos)")
+func hasOutdatedSchema(db *sql.DB) (bool, error) {
+	rows, err := db.Query("PRAGMA table_info(todos)")
 	if err != nil {
 		return false, err
 	}