stream_weaver 0.3.0

data/docs/crud-patterns.md

@@ -0,0 +1,265 @@
+# StreamWeaver CRUD Patterns
+
+StreamWeaver handles CRUD differently from Rails. Because button callbacks are plain Ruby, data mutation happens directly — no controller layer, no POST-redirect-GET cycle. The URL routing layer handles deep-linking to edit views.
+
+## The Core Insight
+
+A StreamWeaver button callback IS a POST handler:
+
+```ruby
+button "Save" do |s|
+  initiative = load_initiative(s[:editing_id])
+  initiative[:title] = s[:edit_title]
+  initiative[:status] = s[:edit_status]
+  save_initiative(initiative)
+  s[:editing_initiative] = false   # exit edit mode
+  s[:flash] = "Saved!"
+end
+```
+
+No controller. No form action. No redirect. Just Ruby.
+
+---
+
+## Read (Index + Show)
+
+Standard StreamWeaver patterns — load from YAML/store, render in app block:
+
+```ruby
+# Index: list all initiatives
+initiatives = load_initiatives
+table initiatives do
+  column :title
+  column :status
+  column(:id) { |i| button("View") { |s| s[:initiative_id] = i[:id] } }
+end
+
+# Show: render detail when initiative_id is set
+if state[:initiative_id]
+  init = load_initiative(state[:initiative_id])
+  card do
+    header3 init[:title]
+    text "Status: #{init[:status]}"
+    button "Edit" do |s|
+      s[:editing_initiative] = true
+    end
+  end
+end
+```
+
+---
+
+## Create
+
+Use a modal or inline form. State holds the draft fields; the save button commits to the store.
+
+```ruby
+button "New Initiative", style: :primary do |s|
+  s[:creating_initiative] = true
+  s[:new_init_title] = ""
+  s[:new_init_status] = "active"
+end
+
+modal :new_initiative, title: "New Initiative" do
+  text_field :new_init_title, placeholder: "Title", submit: false
+  select :new_init_status, %w[active paused completed], submit: false
+
+  modal_footer do
+    button "Create", style: :primary do |s|
+      id = create_initiative(title: s[:new_init_title], status: s[:new_init_status])
+      s[:creating_initiative] = false
+      s[:initiative_id] = id   # navigate to new record
+      s[:flash] = "Initiative created"
+    end
+    button "Cancel" do |s|
+      s[:creating_initiative] = false
+    end
+  end
+end
+```
+
+The `modal :new_initiative` opens when `state[:new_initiative_open]` is true (StreamWeaver convention: `modal :key` → controlled by `state[:key_open]`).
+
+---
+
+## Update (Edit Form)
+
+### Option A: Modal Edit (no URL change)
+
+Good for quick edits on a list view. State holds the record being edited.
+
+```ruby
+initiatives.each do |init|
+  hstack do
+    text init[:title]
+    button "Edit" do |s|
+      s[:editing_id] = init[:id]
+      # load current values into edit fields
+      s[:edit_title]  = init[:title]
+      s[:edit_status] = init[:status]
+    end
+  end
+end
+
+if state[:editing_id]
+  modal :edit_initiative, title: "Edit Initiative" do
+    text_field :edit_title, placeholder: "Title", submit: false
+    select :edit_status, %w[active paused completed], submit: false
+
+    modal_footer do
+      button "Save", style: :primary do |s|
+        update_initiative(s[:editing_id], title: s[:edit_title], status: s[:edit_status])
+        s[:editing_id] = nil
+        s[:flash] = "Saved"
+      end
+      button "Cancel" do |s|
+        s[:editing_id] = nil
+      end
+    end
+  end
+end
+```
+
+### Option B: URL-Addressable Edit Page
+
+Pairs with `route_with` routing (see `routing.md`). Visiting `/initiative/init-001/edit` seeds `state[:editing_initiative] = true`.
+
+```ruby
+# route_with parser handles: /initiative/:id/edit → { initiative_id: id, editing_initiative: true }
+# route_with builder handles: editing_initiative? → /initiative/:id/edit
+
+if state[:editing_initiative] && state[:initiative_id]
+  init = load_initiative(state[:initiative_id])
+
+  # Seed edit fields on first load
+  if state[:edit_seeded_for] != state[:initiative_id]
+    state[:edit_title]     = init[:title]
+    state[:edit_status]    = init[:status]
+    state[:edit_seeded_for] = state[:initiative_id]
+  end
+
+  card do
+    header3 "Edit: #{init[:title]}"
+
+    text_field :edit_title, label: "Title", submit: false
+    select :edit_status, %w[active paused completed], submit: false
+
+    hstack do
+      button "Save", style: :primary do |s|
+        update_initiative(s[:initiative_id], title: s[:edit_title], status: s[:edit_status])
+        s[:editing_initiative] = false   # URL drops back to /initiative/:id
+        s[:flash] = "Saved"
+      end
+      button "Cancel", style: :secondary do |s|
+        s[:editing_initiative] = false
+      end
+    end
+  end
+end
+```
+
+**Field seeding pattern**: The `edit_seeded_for` guard ensures edit fields are seeded from the record once per initiative, not overwritten on every re-render. Without it, every button click would reset the form to the stored value.
+
+---
+
+## Delete
+
+```ruby
+button "Delete", style: :danger do |s|
+  s[:confirm_delete_id] = init[:id]
+end
+
+if state[:confirm_delete_id]
+  alert(variant: :warning) do
+    text "Delete this initiative? This cannot be undone."
+    hstack do
+      button "Confirm Delete", style: :danger do |s|
+        delete_initiative(s[:confirm_delete_id])
+        s[:confirm_delete_id] = nil
+        s[:initiative_id] = nil   # navigate away
+        s[:flash] = "Deleted"
+      end
+      button "Cancel" do |s|
+        s[:confirm_delete_id] = nil
+      end
+    end
+  end
+end
+```
+
+---
+
+## Flash Messages
+
+StreamWeaver has no built-in flash. Use `state[:flash]` with a conditional render:
+
+```ruby
+if state[:flash]
+  alert(variant: :success) { text state[:flash] }
+  # Auto-clear: set flash to nil after it's rendered once
+  # Use a counter trick or a dedicated clear button
+end
+```
+
+For auto-dismiss, use a toast:
+
+```ruby
+# In button callback:
+s[:toasts] ||= []
+s[:toasts] << { id: SecureRandom.hex(4), message: "Saved!", type: :success, duration: 3000 }
+
+# In render:
+toast_container  # renders toasts from state[:toasts]
+```
+
+---
+
+## Store Adapter Pattern
+
+Keep data access decoupled from the UI. Centralizing it makes the CRUD callbacks readable:
+
+```ruby
+module InitiativeStore
+  YAML_PATH = File.expand_path("~/cultiv-os/cabinet/initiatives/master-initiatives.yaml")
+
+  def self.all
+    YAML.safe_load_file(YAML_PATH, symbolize_names: true)[:initiatives] || []
+  end
+
+  def self.find(id)
+    all.find { |i| i[:id] == id }
+  end
+
+  def self.update(id, attrs)
+    data = YAML.safe_load_file(YAML_PATH)
+    idx  = data["initiatives"].index { |i| i["id"] == id }
+    return false unless idx
+    data["initiatives"][idx].merge!(attrs.transform_keys(&:to_s))
+    File.write(YAML_PATH, data.to_yaml)
+    true
+  end
+end
+
+# In app:
+button "Save" do |s|
+  InitiativeStore.update(s[:initiative_id], title: s[:edit_title], status: s[:edit_status])
+  s[:editing_initiative] = false
+end
+```
+
+---
+
+See [docs/resource-dsl.md](resource-dsl.md) for the implemented `resource` DSL.
+
+---
+
+## Decision Guide
+
+| Interaction | Pattern |
+|---|---|
+| Read-only list | `table` + state filter |
+| Quick edit (no URL change) | Modal edit + `state[:editing_id]` |
+| Deep-linkable edit form | `route_with` + URL-addressable edit page |
+| Inline edit (click cell) | Not yet supported — use modal |
+| Bulk update | `checkbox_group` + bulk action button |
+| Delete with confirmation | Confirm state flag + conditional alert |

data/docs/endpoints.md

@@ -0,0 +1,122 @@
+# Custom HTTP Endpoints — `endpoint`
+
+The "never rewrite in Sinatra" escape hatch: register a real HTTP route (webhook
+receiver, JSON API, file download, health check) directly from the app DSL,
+without leaving StreamWeaver or hand-rolling a separate Sinatra/Rails service.
+
+**This is not URL routing.** [`docs/routing.md`](routing.md) (`route_by` /
+`route_with` / `page`) maps URL paths to *state* so the same StreamWeaver view
+renders differently per path — it's still an HTML page render. `endpoint` is
+the opposite: a genuine Rack route that bypasses StreamWeaver's state
+machinery, component tree, and view rendering entirely. Use `route_by`/`page`
+for "different tab/view depending on the URL." Use `endpoint` for "something
+that isn't a StreamWeaver page at all" — a webhook, a JSON API, a file
+download.
+
+## Basic usage
+
+```ruby
+app "My App" do
+  endpoint :get, "/api/status" do |req|
+    { ok: true, uptime: 42 }          # Hash -> 200 application/json
+  end
+
+  endpoint :post, "/webhook/github" do |req|
+    payload = req.body.read           # req is a Rack::Request
+    handle_github_event(payload)
+    [202, {}, "queued"]                # Rack triplet passes through verbatim
+  end
+
+  # ... normal StreamWeaver UI DSL below, in the same app
+  header1 "My App"
+end.run!
+```
+
+Supported verbs: `:get`, `:post`, `:put`, `:patch`, `:delete`.
+
+## Return value conventions
+
+The block's return value is converted into the HTTP response:
+
+| Return type | Response |
+|---|---|
+| `Hash` | `200`, `Content-Type: application/json`, body is `JSON.generate`d |
+| `String` | `200`, `Content-Type: text/html`, body is the string as-is |
+| `[status, headers, body]` (Array) | Passed through to Rack verbatim — full control (custom status, headers, streaming, file downloads, etc.) |
+| anything else | `200`, `Content-Type: text/plain`, body is `#to_s` |
+
+Use the Rack-triplet form for anything that doesn't fit the Hash/String
+shortcuts — custom status codes, redirects, non-JSON/HTML content types, or
+file downloads:
+
+```ruby
+endpoint :get, "/export/report.csv" do |req|
+  csv = generate_report_csv
+  [200, { 'Content-Type' => 'text/csv', 'Content-Disposition' => 'attachment; filename="report.csv"' }, csv]
+end
+```
+
+## The block argument
+
+The block receives the raw [`Rack::Request`](https://www.rubydoc.info/gems/rack/Rack/Request)
+for the current request — not StreamWeaver state, not a component. Use it like
+you would in any Rack app:
+
+```ruby
+endpoint :get, "/api/echo" do |req|
+  { query: req.params }                     # query string / route params
+end
+
+endpoint :post, "/webhook/github" do |req|
+  req.body.read                             # raw request body
+end
+```
+
+**Gotcha:** if the incoming request's `Content-Type` is
+`application/x-www-form-urlencoded` or `multipart/form-data`, Sinatra will
+already have consumed the body to build `params` *before* your block runs —
+`req.body.read` comes back empty in that case. Use `req.params` for form
+submissions instead, or make sure the sender uses a different `Content-Type`
+(e.g. `application/json`, `text/plain`) for endpoints that need the raw body.
+
+## No CSRF, no session, no state
+
+`endpoint` is a raw Rack route. It does **not** go through StreamWeaver's
+session/state machinery, CSRF protection, or component rendering — the block
+you write is the entire request handler. If you need auth, verify a webhook
+signature, parse JSON, etc., do it yourself inside the block just as you would
+in a plain Sinatra route.
+
+## Precedence: internal routes always win
+
+StreamWeaver's own framework routes (`/update`, `/action/*`, `/submit`,
+`/event/*`, `/form/*`, `/theme/*`, `/sw/*`, plus a handful of others like `/`,
+`/stream`, `/deck/*`) are defined before any `endpoint` you register. Sinatra
+dispatches to the *first* route that matches a request, so if an `endpoint`
+path collides with one of these, the internal route always wins — your block
+is simply never reached.
+
+`endpoint` warns at registration time when it detects a collision with a
+known-reserved path/prefix, so the mistake is loud instead of silently eaten:
+
+```
+StreamWeaver: endpoint POST /update collides with a StreamWeaver-internal route
+and will never be reached — the internal route always wins.
+```
+
+Pick paths outside StreamWeaver's reserved prefixes (`/action/`, `/event/`,
+`/form/`, `/theme/`, `/sw/`) and outside `/update` and `/submit` to avoid this
+entirely.
+
+## Service mode (`streamweaver run`)
+
+In standalone mode (`App#run!`), endpoints are served at the path exactly as
+registered (e.g. `GET /api/status`).
+
+In multi-app service mode, each app is mounted under `/apps/:app_id`, so its
+endpoints are scoped under that prefix too: an app registered as `svc123`
+serves `endpoint :get, "/api/status"` at `GET /apps/svc123/api/status` — and
+equally via the app's human-readable slug, e.g. `GET /apps/my-dashboard/api/status`. The
+same precedence rule applies — StreamWeaver's fixed `/apps/:app_id/...` routes
+(update, action, event, form, theme) are defined first and always win on
+collision.

data/docs/for_llms.md

@@ -0,0 +1 @@
+../llms.txt

data/docs/form-patterns.md

@@ -0,0 +1,165 @@
+# StreamWeaver Form Patterns
+
+Canonical patterns for form/input/selection UIs. Use this to pick the right component for your use case.
+
+## Pattern Reference
+
+| Pattern | Use Case | Component | Example |
+|---|---|---|---|
+| Instant feedback | Filters, toggles | Default inputs (auto-submit) | `select :filter, options` |
+| Multi-select then act | Batch operations | `checkbox_group` or `submit: false` + button | Check items then "Delete Selected" |
+| Traditional form | Edit/create with Save/Cancel | `form` block | `form :edit_person do...end` |
+| Single selection for later action | Pick category then add item | `select` with `submit: false` | `select :cat, names, submit: false` |
+| Scrollable list | Long item lists | `scroll_box` | `scroll_box(max_height: "400px") do...end` |
+
+## Examples
+
+### Instant Feedback (default)
+```ruby
+# Every change triggers a server round-trip and re-render
+select :filter, ["All", "Active", "Done"]
+text_field :search, placeholder: "Search..."
+```
+
+### Single Selection for Later Action
+```ruby
+# User picks a category, then clicks Add — no round-trip on select change
+cat_names = categories.map { |c| c["name"] }
+select :category, cat_names, default: cat_names.first, submit: false
+
+button "Add Item", style: :primary do |s|
+  chosen = s[:category]  # string name, not an index
+  # ... use chosen
+end
+```
+
+### Multi-Select Then Act
+```ruby
+checkbox_group :selected_items do
+  items.each { |item| item item.id do text item.name end }
+end
+
+button "Delete Selected" do |s|
+  ids = s[:selected_items]  # array of checked values
+  # ... delete them
+end
+```
+
+### Traditional Form
+```ruby
+form :edit_person do
+  text_field :name, placeholder: "Name"
+  text_field :email, placeholder: "Email"
+  submit "Save" do |s|
+    data = s[:edit_person]  # { name: "...", email: "..." }
+    # ... save
+  end
+  cancel "Cancel"
+end
+```
+
+### Scrollable List
+```ruby
+scroll_box(max_height: "400px") do
+  items.each do |item|
+    hstack spacing: :xs, align: :center do
+      text item.name
+      button "Edit", id: "edit_#{item.id}" do |s|
+        # ...
+      end
+    end
+  end
+end
+```
+
+## Anti-Patterns
+
+### 1. Button-as-Radio
+**Wrong** — Using buttons + state to simulate selection:
+```ruby
+# DON'T DO THIS
+hstack do
+  categories.each_with_index do |cat, i|
+    button cat, style: state[:cat] == i ? :primary : :secondary do |s|
+      s[:cat] = i
+    end
+  end
+end
+```
+
+**Right** — Use `select` or `radio_group`:
+```ruby
+select :cat, category_names, submit: false
+```
+
+### 2. Integer State Keys
+**Wrong** — Storing array indices in session state:
+```ruby
+s[:cat] = i  # breaks if list order changes
+```
+
+**Right** — Store the string name, resolve to index at action time:
+```ruby
+s[:cat_name] = cat["name"]
+# later:
+idx = categories.index { |c| c["name"] == s[:cat_name] } || 0
+```
+
+### 3. Forgetting `submit: false`
+**Wrong** — Inputs inside button-action workflows auto-submit by default:
+```ruby
+text_field :label  # triggers round-trip on every keystroke!
+button "Add" do |s| ... end
+```
+
+**Right**:
+```ruby
+text_field :label, submit: false
+button "Add" do |s| ... end
+```
+
+### 4. Session Cookie Overflow
+Large text values in state overflow the 4KB cookie limit.
+**Fix**: Use `transient: true` to exclude from the session cookie:
+```ruby
+text_area :paste_area, transient: true
+```
+
+### 5. Stale Session After Restart
+Static dev secret preserves cookies across restarts. If your state schema changed, old cookies cause errors.
+**Fix**: Store state as recoverable strings (not fragile indices). Use `--reset` flag or clear cookies after schema changes.
+
+### 6. Transient Fields Never Resync From the Server
+`transient: true` is documented above (#4) as "exclude from the session cookie" — but the
+Alpine adapter's morph-merge goes further than that: it also skips writing the server's value
+back into the browser's reactive store on *every* subsequent update, not just full-cookie
+snapshots (`adapter/alpinejs.rb`, the `htmx:beforeSwap` handler — `if (transientKeys.has(k))
+return;`). In practice this means once a transient field's DOM node exists, only the user's own
+typing ever changes what it shows — a server-side `s[:x] = ""` after a button handler, or a
+fresh prefill for a *different* record reusing the same state key, is silently dropped.
+
+**Wrong** — clearing a transient field after its own submit handler:
+```ruby
+text_field :custom_item, submit: false, transient: true
+button "Add" do |s|
+  add_item(s[:custom_item])
+  s[:custom_item] = ""   # never reaches the browser — field still shows the old value
+end
+```
+
+**Wrong** — reusing one transient key across multiple records' edit forms (e.g. a schema-driven
+edit UI where every row's Time/Date field binds to the same `:edit_time`/`:edit_date` key
+instead of a per-row key): opening row B's edit form after row A's still shows row A's value,
+because the fresh prefill for row B never overwrites what's already sitting in the browser.
+
+**Fix**: if a field's value must ever be authoritatively reset by the server (a post-submit
+clear, a fresh prefill on reopen), don't mark it `transient: true` unless it's genuinely a
+one-shot, never-cleared, never-reused input (the large-paste-area case #4 was written for).
+Short single-value fields rarely have a real cookie-size reason to be transient — dropping the
+flag is usually simpler than working around the resync gap. If cookie size is the actual
+concern *and* the field needs server-driven resets, the two needs are currently in tension —
+there's no flag that gives "excluded from cookie" without also losing resync.
+
+Found via `~/work/cultiv-ai/apps/health_dashboard/app.rb`, 2026-08-20 — a custom-item field
+that never visually cleared after Add, and an entry-edit form's Time/Date fields that leaked
+one edit's value into the next.