funicular 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5816e8e43d54e6bec4b6bb8a06da6165ab138e549cdbad649d2acba002a5fec4
-  data.tar.gz: 51ed5ca984f12669bfd1587bf384ea685c54e2d03dff9552d3cc49485d29081f
+  metadata.gz: 3daa358d6b29db11190349ae990006246a9c4b1d04e2e363235428dd3e53fd2a
+  data.tar.gz: 4ef7607d5e6d33385b776c6f01ba763c555bdc453109adb7d3473089889827cc
 SHA512:
-  metadata.gz: 360c39bdc7375ae5967c37f0b24437fa6d254f8814520ae984cc455195ac957b1279988a430f752e731eb40eab62cbeba178bc1ad08dc8836c7ce64c0d0810d5
-  data.tar.gz: 31bb97a1b6fbedbf3d1b1539c3e8ea5a8169c91095733c09d38f465c463a56071ecb766524945e307b66998708e09fff0ce0f6388e009f54b9d9945169922259
+  metadata.gz: 547f30c0948941c1b40c2506c129e7aaa1d364b5db0073a2fe7f404d34149e2ba6d9400067748b6512beb7ffa34ba9dd318a9d6b6b9d78caf2baeeffc45f0442
+  data.tar.gz: b2c64be4ae511ead4abc54df652e391aafeea9e6ef1be3373e5dc686bac00d7de0885ffca2d4ad392dbb76c0f9fc7443ebfc367b35d22e8470766010669c5493

data/CHANGELOG.md

@@ -1,4 +1,432 @@
-## [Unreleased]
+## [0.5.0] - 2026-08-13
+
+The local database release: an ActiveRecord-like, reactive local store on
+in-browser SQLite (picoruby-sqlite3), with the Rails server as the source
+of truth. Plus the first round of fixes and API gaps surfaced by building
+a real shop on the framework.
+
+### Added
+
+- `Funicular::StyleValue#+`: styles now support one-off class
+  additions (`styles.field + " col-span-2"`) instead of raising
+  NoMethodError. `+` concatenates verbatim like String#+, accepts
+  String or StyleValue, and raises TypeError for anything else
+  (matching String#+ instead of silently to_s-ing mistakes); `|`
+  remains the space-joining combinator. `to_str` is deliberately not
+  defined: the mruby client's String#+ never coerces implicitly, so
+  defining it on CRuby would let SSR accept `"base " + styles.field`
+  while the browser raises; both VMs reject that form identically
+  instead.
+
+- Navigation guard: a component can veto leaving by overriding
+  `navigation_guard` to return a confirmation message (nil allows).
+  The router consults it before `navigate` (including `link_to
+  navigate: true`), on browser back/forward (restoring the history
+  entry when the user stays), and through a synchronous `beforeunload`
+  listener for reload / tab close via the browser's native dialog.
+  `Funicular.confirm_handler=` injects the dialog for tests or custom
+  UIs; SSR never blocks. The guard must not suspend.
+
+- `Funicular::SSR.render_component(component_name, props:, state:)`:
+  render one component to static HTML with no route lookup, so a
+  server-rendered (ERB) page can embed a Funicular component -- a shared
+  site header, say -- instead of duplicating its markup. The component
+  is named by string and resolved after `boot!` (host apps keep
+  app/funicular out of Rails autoloading); a constant that is not a
+  `Funicular::Component` subclass is rejected with ArgumentError. No
+  hydration and no handler binding: links work, onclick does not.
+
+- `Funicular::Testing::DOMTest` gains the negative assertions
+  `assert_no_selector` / `assert_no_text` and a `selector_count` helper;
+  "this must NOT render" was previously untestable without hand-rolled
+  JS.eval node counting.
+
+- `Funicular::Testing.ensure_compiled!`: one call in a test helper that
+  syncs plugin assets and recompiles app.mrb when sources are newer,
+  replacing the boilerplate every host app grew by hand. Plain
+  controller tests that render `funicular_plugin_include_tags` no
+  longer fail order-dependently on unsynced plugin CSS.
+
+- `Funicular::HTTP::Response#body` as an alias of `#data`: components
+  reach for the universal name first, and the resulting NoMethodError
+  used to vanish inside the JS bridge as a silently frozen page.
+
+- The SQLite local-database subsystem is now globally opt-in through
+  `config.local_database = true` and defaults off. REST-only applications do
+  not start SQLite, IndexedDB, Web Locks, replica write-through, or session
+  epochs. Opted-in applications must also declare `config.user_key` or
+  `config.anonymous_only = true`; existing snapshots are retained while the
+  feature is disabled.
+
+- Design documentation for the local database layer:
+  `docs/local_database.md` is the user-facing API contract (source-of-truth
+  contract, `storage`/`refresh` declarations, `migrate` blocks, `.local`
+  Relations, `watch`, persistence/durability, namespaces and tabs, session
+  epoch, SSR constraints); `docs/architecture.md` gains the
+  contributor-facing invariants.
+- `Model.all(params)` now forwards `params` as a percent-encoded query
+  string (`Post.all(page: 2)` -> `GET /posts?page=2`) via the new
+  picoruby-uri gem's CRuby-compatible `URI.encode_www_form`. The argument
+  existed before but was silently ignored.
+- The local-query foundation (`mrblib/db.rb`, `mrblib/relation.rb`):
+  `Funicular::Relation`, the lazy chainable query builder behind `.local`
+  (where/order/limit/offset; hash, IN, BETWEEN, IS NULL, and raw-fragment
+  conditions; each/to_a/first/count/exists?/find/find_by/delete_all), the
+  `Funicular::DB` error vocabulary, and the shared boolean/datetime codec
+  (`true`/`false` <-> 1/0, `Time` <-> UTC ISO 8601 TEXT) used on both the
+  SQLite and REST boundaries. The model-layer wiring (`storage`, `.local`)
+  arrives in a following change; the gem now depends on picoruby-sqlite3.
+- The model declaration DSL: `storage :replica (default) | :ephemeral |
+  :local do ... end` (with `migrate N [, reset: true] do |t| ... end`
+  blocks recorded at class eval and version rules -- baseline and
+  contiguity -- validated there), `refresh :manual` (`:auto`/`:live`
+  raise "not yet supported"), `table_name` (naive pluralization +
+  override), and the `.local` entry point returning a whole-table
+  `Funicular::Relation` (NoTableError on ephemeral models). Replica
+  column metadata derives from the server schema (binary attributes
+  excluded); materializing a query before `Funicular::DB.boot` (a later
+  change) raises `Funicular::DB::UnavailableError`.
+- Associations: `belongs_to :user` and `has_many :comments` as local-query
+  sugar over the `<name>_id` convention -- `post.user` reads
+  `User.local.find_by(id: post.user_id)`, `post.comments` returns the
+  chainable `Comment.local.where(post_id: post.id)` Relation (usable in
+  `watch`). `class_name:` and `foreign_key:` override the conventions;
+  `through:`, eager loading, and polymorphic associations raise as
+  unsupported in v1. Targets resolve lazily at first read, so model files
+  may load in any order, and a declaration whose name collides with a
+  column, a REST attribute, another declaration, or a `Funicular::Model`
+  instance method is refused instead of silently shadowing it.
+- The client-only-table migration machinery: `Funicular::DB::TableBuilder`
+  (the `t` in migrate blocks -- string/text/integer/float/boolean/datetime
+  columns with `default:`/`null:`, `timestamps`, `index`/`remove_index`,
+  `rename`, `remove`, raw `execute`) and the per-table runner
+  (`Funicular::DB.apply_local_migrations`): fresh and below-baseline
+  tables rebuild from the baseline -- the newest `reset: true` block, or
+  the first block; superseded pre-reset history may stay in the code and
+  is never folded or applied -- upgrades apply exactly
+  the missing blocks in one transaction (rolled back on failure; in
+  development a failed upgrade auto-resets the table instead), applied
+  versions live in the `funicular_meta` table, and a table newer than
+  the declarations raises `Funicular::DB::SchemaTooNewError`. The column
+  fold is validated before any DDL runs, so declarations SQLite would
+  accept as plain DDL (renaming or removing the implicit `id`) are
+  rejected while the database is still intact. Local
+  models' `local_columns` now fold their migrate blocks (implicit
+  `id INTEGER PRIMARY KEY` included), replacing the interim
+  UnavailableError.
+- The change-event bus (`mrblib/db.rb`): `Funicular::DB.subscribe`/
+  `unsubscribe` per [database role, table], and the raw-SQL protocol
+  `Funicular::DB.notify_changed(Model)` (or `(:local | :replica,
+  table)`; ephemeral models raise NoTableError). Events fire
+  post-commit only: inside a guarded transaction block they coalesce to
+  one event per [role, table] and flush after COMMIT, or vanish with
+  the rollback. Delivery is deferred to the NEXT tick (JS
+  `setTimeout(0)` by default; the scheduler is pluggable and CRuby
+  drains immediately, where no component can be mid-update), coalescing
+  per [role, table] within the tick; an event raised by a subscriber
+  belongs to the following tick -- never nested, never dropped -- and a
+  raising subscriber is isolated. `Model.local_table_changed` now feeds
+  this bus, so every framework write (local CRUD, delete_all, replica
+  write-through) announces itself.
+- The writer election (`mrblib/db.rb`, docs decision 14): one tab per
+  namespace persists. `Funicular::DB.elect_writer` runs once at boot
+  with Web Locks' `ifAvailable` -- granted makes the tab the
+  `persistent_writer` (the lock is held by a promise resolved only at
+  `release_writer_lock`, the terminal step-down seam), not granted
+  makes it a `persistent_reader` for the life of the page (no
+  promotion in v1; reload to write), and a missing or failing Web
+  Locks API drops the page to `volatile` (everything works, nothing
+  persists). `Funicular::DB.durability` reports the state; the JS shim
+  accepts an injectable Locks API for tests.
+- The persistence core (`mrblib/db.rb`, docs decisions 11/16):
+  whole-database snapshots (serialize -> Base64) in Funicular's OWN
+  IndexedDB store, opened with the in-memory fallback disabled --
+  availability errors (private mode) classify as the `volatile` state,
+  every other storage error stays loud for the boot to fail on.
+  Auto-persist rides the post-commit change-event funnel with a
+  per-role debounce (replica ~5 s, local ~500 ms; a rollback schedules
+  nothing), `Funicular::DB.flush` snapshots immediately (writer only;
+  `ReadOnlyTabError` on a reader, honest no-op on volatile), and a
+  `visibilitychange` backstop persists when the tab hides. A persist
+  landing while that database has an open transaction (a stale timer,
+  the backstop, an in-block flush) refuses to serialize uncommitted
+  pages and defers itself to the commit/rollback settle. Failures are
+  never silent: always logged, plus `config.on_persist_error`.
+  `Funicular::DB.configure` arrives with the persistence knobs
+  (`replica_debounce_ms`/`local_debounce_ms`/
+  `request_persistent_storage` -- `navigator.storage.persist()` is
+  asked only when local data exists -- and the
+  `on_persist_error`/`on_boot_error`/`on_session_change` hooks).
+- `Funicular::DB.boot` (docs decision 19), the client-side boot that
+  wires everything in order: page metadata -> namespace resolution
+  (+ session epoch held for the HTTP layer) -> writer election ->
+  snapshot store (availability errors -> volatile) -> the two
+  `:memory:` connections -> local snapshot restore + migrations ->
+  replica restore + schema-derived DDL -> guarded handles installed
+  (`Funicular::DB.local`/`.replica`, and `Model.local_db`/`replica_db`
+  now consult the boot; reader tabs get `PRAGMA query_only=ON` plus a
+  read-only local proxy) -> `navigator.storage.persist()` when a
+  local model exists -> the visibilitychange backstop. One-shot;
+  raises `UnavailableError` under SSR. The handles gate on
+  `boot_state == :ready`, not on their existence: mid-boot (another
+  Task running during a boot await) and after a failed boot the
+  database is equally unreachable -- and the raw-database paths that
+  bypass the handles carry the gate too: `Model.reset_local` requires
+  `:ready`, `wipe` allows `:ready` or `:failed` (wiping from
+  `on_boot_error` is the official corrupt-snapshot recovery), and
+  `persist_snapshot` -- the final persistence entry that flush and
+  the debounce funnel through -- refuses during `:booting`, so a
+  mid-boot flush cannot overwrite stored snapshots with unrestored
+  databases. Any failure is decision 16's
+  fail loud: `boot_state` becomes `:failed`, the handles are torn
+  back out, the errors hit the console and `config.on_boot_error`,
+  nothing mounts (wired with `Funicular.start` in a following
+  change), and once the hook has had its recovery chance the writer
+  lock is released -- a failed page must not deny the writer slot to
+  every other tab. SchemaTooNew instead
+  completes the boot LOCKED DOWN (docs decision 7): every model-level
+  local operation raises `SchemaTooNewError`, raw SELECT export
+  through `DB.local` survives, writes are refused by SQLite itself.
+  `Model.reset_local` arrives with it: writer-only baseline rebuild of
+  one client-only table that lifts the lockdown once the whole
+  declared set passes again -- and the lift is provisional: a reset
+  that fails mid-rebuild puts SQLite's own write refusal
+  (`query_only`) back up before re-raising.
+- The schema boot barrier and the start gate (docs decision 19,
+  wiring half). `Funicular.load_schemas` is now a real barrier: every
+  request settles its slot exactly once -- success, HTTP error, or a
+  schema that arrived but cannot be applied -- so it always
+  completes. All green boots the local database (declared models come
+  from a new Model registry filled at subclass definition; namespace,
+  epoch, and user-key metadata come from the include tag's
+  HTML-escaped `data-funicular-*` attributes) and only then runs the
+  completion block; any failure never invokes the block, reports
+  through the console and `config.on_boot_error`, and marks the boot
+  failed. `Funicular.start` gates on the boot before touching the
+  DOM: replica apps boot inside the barrier, local-only apps boot
+  right in start, and nothing mounts on top of a failed boot. An
+  empty schema set with a schema-less replica model declared fails
+  the boot loud instead of running on missing tables.
+- The session-epoch terminal latch (docs decision 13, client half)
+  and HTTP's exactly-once settle. Every `Funicular::HTTP` request now
+  settles its callback exactly once: a rejected fetch (network
+  failure, invalid URL) delivers a status-0 error response instead of
+  hanging the schema barrier and every REST caller, and an exception
+  out of the caller's own block never settles twice. When the page
+  carried a session epoch, every response's `X-Funicular-Epoch` is
+  checked -- a rotated value OR a missing header means this page
+  belongs to a session that no longer exists: the response is
+  discarded (the caller settles with an error, nothing is applied)
+  and the page goes TERMINAL, irreversibly. From then on the page
+  refuses to ISSUE requests as well -- every verb settles immediately
+  with the same session-changed error before any fetch, since a
+  request executed under the new session's cookies could mutate
+  another user's data. A terminal writer steps
+  down completely: pending persist timers are cancelled, the final
+  persistence entry refuses forever, the writer lock frees the slot
+  for a fresh tab -- but only after an in-flight snapshot write has
+  landed, so a new writer can never race the old session's image --
+  and both database handles become a non-persistent read view. The
+  latch is independent of durability: `wipe` and `Model.reset_local`
+  -- the raw paths that bypass the read-only proxies -- refuse on ANY
+  terminated page, including a volatile one, which never steps down
+  to reader. A mismatch landing MID-BOOT (the boot suspends at the
+  writer election and at every storage read, with nothing to tear
+  down yet) aborts the boot through the ordinary failure funnel,
+  releasing a writer lock the election acquired after the
+  termination; as defense in depth, handles installed on a terminal
+  page come up read-only. `config.on_session_change` runs
+  once (default: `location.reload()`). The schema barrier arms the
+  page's epoch BEFORE its first request leaves, and the check itself
+  latches lazily off the page otherwise -- pre-boot HTTP (an
+  ephemeral model's REST call, a direct `HTTP.get` at app init) is
+  covered too, not only traffic after `DB.boot`, which alone would
+  latch too late. Pages without an epoch (no Rails integration yet)
+  are unaffected.
+- The Rails half of data isolation and the session epoch (docs
+  decisions 12/13). `Funicular.configure` gains `application_id`
+  (default `"funicular"`; give each app sharing an origin its own),
+  `user_key` (a lambda receiving the controller and returning a
+  stable identifier, nil when signed out), and `anonymous_only` (the
+  explicit opt-out for apps without users) -- setting both is a
+  configuration error raised straight from the initializer. The
+  Railtie now stamps `X-Funicular-Epoch` on every response (emitted
+  lowercase, as the Rack 3 spec requires; HTTP header names are
+  case-insensitive on the wire): the epoch
+  lives in the Rails session PER application_id
+  (`session["funicular_epochs"]`) and rotates whenever the computed
+  user key changes, so login, logout, and direct user switches all
+  rotate it with no application code. Rotation runs in a controller
+  around_action (the user_key lambda needs its controller) that
+  stamps BEFORE the action and re-stamps in its ensure with the
+  post-action identity -- the login/logout actions flip the identity
+  mid-request, and their own response must already carry the rotated
+  epoch. The header itself is written by a Rack middleware sitting
+  ABOVE ActionDispatch's exception renderer: a controller-set header
+  dies with the controller's response when the action raises, and a
+  header-less 500 would read as an epoch mismatch client-side,
+  terminating a healthy page over a mere server error. Both the
+  concern and the include-tag helper read the session through
+  `request.session`, never the controller/view `session` accessor: an
+  application action named "session" shadows that accessor, and
+  calling it would invoke the action itself. Session-less
+  Rails API apps stay unbroken: a disabled session leaves the epoch
+  feature off (no cookie identity exists to protect) instead of
+  raising on every action. `picoruby_include_tag` embeds
+  the namespace + epoch metadata as HTML-escaped `data-funicular-*`
+  attributes on the bootstrap script tag -- exactly the contract
+  `DB.read_page_metadata` reads client-side -- with the user-key
+  attribute omitted for signed-out visitors and the epoch drawn from
+  the same session entry the response header uses; the user-key
+  attribute and the epoch identity come from ONE resolver evaluation,
+  so a racy `current_user` cannot embed one user's namespace with
+  another user's epoch. A `user_key` that resolves to an empty string
+  fails loud server-side.
+- `Funicular::DB.wipe` and the mutation generation (docs decision 17):
+  one call drops every table in both databases of the current
+  namespace, deletes its two snapshot keys, rebuilds the replica DDL +
+  fingerprint and the local migration state from scratch, and notifies
+  watchers only once the tables are queryable again AND the stale
+  snapshots are really gone (components re-render onto empty tables,
+  never onto missing ones; a failing snapshot delete raises out of
+  wipe before any watcher is told). Writer-only
+  (`ReadOnlyTabError` on a reader; fine on volatile, where there are
+  no snapshots to delete). The wipe is safe mid-flight: it advances
+  the mutation generation FIRST, so REST responses issued before it
+  are discarded -- the callback gets `(nil, Funicular::DB::Error)`
+  instead of resurrecting the previous session's rows -- pending
+  persistence timers are cancelled, and an in-progress snapshot
+  cannot overwrite the cleared state. While either database has an
+  open transaction, wipe refuses loudly BEFORE any side effect: the
+  rebuild would otherwise nest into (or be rolled back with) that
+  transaction. The check cannot be raced, either: wipe never suspends
+  its Task between the check and the end of the rebuild -- the
+  snapshot deletes, the only awaiting operations, come last.
+- The reactivity layer on top of the bus: `Component#watch(:key)` binds
+  a state key to a `storage :local`/`.local` Relation -- the block runs
+  once, materializes into `state[:key]`, and re-runs (re-subscribing,
+  so branchy blocks may switch relations) after every change event on
+  the relation's table; anything that is not a Relation raises, pointing
+  at `Model.on_change`/`off_change`, the public primitive for hashes,
+  counts, and raw-SQL-derived state. Watch subscriptions die with the
+  component even when a lifecycle hook raises.
+- The guarded database handles (`mrblib/db.rb`,
+  `Funicular::DB::GuardedDatabase`/`GuardedStatement`/
+  `GuardedResultSet`): the proxies `Funicular::DB.local`/`.replica`
+  will hand out instead of raw connections. The allowlist is closed --
+  persist/close/serialize/deserialize/backup do not exist in any state,
+  `transaction` yields the proxy itself, and `query` returns a wrapped
+  result set. Read-only handles enforce at EVERY execution entry
+  (execute, step, ResultSet next/reset) via `Statement#readonly?` (a
+  write prepared while writable is still refused after the handle went
+  read-only, one-way), raising
+  `Funicular::DB::ReadOnlyTabError`; ATTACH/DETACH and
+  `PRAGMA query_only` are rejected in every state, comment prefixes
+  included, while read pragmas stay available.
+- The namespace identity (`mrblib/db.rb`): a typed, versioned tuple
+  (`["v1", app, "anonymous"]` / `["v1", app, "user", key]`) encoded as
+  canonical JSON, which every durable name -- the two snapshot keys and
+  the Web Lock name -- derives from. Structure, not delimiters,
+  separates the fields, so a user_key of "anonymous" or one containing
+  separators cannot collide. `resolve_namespace` enforces the
+  declaration rules client-side (`Funicular::DB::ConfigError`):
+  user_key and anonymous_only are mutually exclusive, and every opted-in
+  application requires a user_key unless anonymous_only explicitly accepts
+  one shared anonymous namespace.
+- REST is wired to the local database layer: response values decode
+  through the shared codec when instances initialize and when `update`
+  applies the server row (ISO 8601 strings become `Time`, 1/0 become
+  booleans -- `Post.all` and `Post.local.find` now return the same Ruby
+  types), and every successful REST call mirrors its result into the
+  replica through the single apply entry point BEFORE user callbacks
+  run (`all`/`find`/`create` upsert, `update` upserts the applied
+  server row, `destroy` deletes). Write-through stays inert until
+  `Funicular::DB.boot` installs the replica handle, so REST keeps
+  working standalone.
+- The replica-table plumbing (`mrblib/db.rb`): CREATE TABLE derived from
+  the server schema (id type follows the server -- INTEGER or TEXT; a
+  schema without id raises pointing at `storage :ephemeral`; binary
+  attributes never reach the replica), the canonical-JSON schema
+  fingerprint stored in `funicular_meta` (string equality; a mismatch
+  drops and recreates ALL replica tables empty, refilled by the app's
+  next explicit fetch), and the single write-through entry points
+  `replica_upsert` (whole-row INSERT OR REPLACE through the codec) and
+  `replica_delete` (RETURNING-based), both firing the model's change
+  hook. Boot wiring and the REST call sites arrive next.
+- Local CRUD and the bare-class alias on `storage :local` models:
+  synchronous, validated `create` (id from the inserted row; omitted
+  attributes take the SQL DEFAULT while an explicit nil binds NULL; the
+  row is read back, so defaults and codec normalization land in the
+  instance; auto `created_at`/`updated_at`), `#update`
+  (true/false; an update with no actual changes is a no-op that does
+  not touch `updated_at`), `#destroy`, `#reload`, `#new_record?`;
+  `Draft.all` is the whole-table Relation (blocks and params raise --
+  there is no REST side), and `where`/`order`/`limit`/`offset`/`count`/
+  `first`/`exists?`/`find_by`/`delete_all` hang off the bare class,
+  which on other storage kinds points you at `.local`. All local writes
+  fire the `local_table_changed` hook and let SQLite constraint
+  violations escape as `SQLite3::Exception`. `Model.create` now also
+  accepts bare keywords (`Draft.create(title: "x")`) on every storage
+  kind.
+
+### Changed (BREAKING)
+
+- Every `Funicular::Model` REST callback is now uniformly
+  `(result, error)`: on success `result` is the payload (`all` -> array,
+  `find`/`create` -> instance, `update` -> the applied instance, `destroy`
+  -> `true`) and `error` is nil; on failure `result` is nil. `update` and
+  `destroy` used to yield boolean-first `(true/false, data_or_error)`;
+  callsites reading the first argument as a boolean must be updated.
+  `update` with nothing to send (no changes, or binary-only changes) now
+  reports a successful no-op instead of silently not calling the block.
+
+### Fixed
+
+- `Model#initialize` uses key-presence lookups instead of `||`, so a
+  string-keyed `false` (boolean columns) no longer collapses to nil.
+
+- Dev-mode SSR reloads edited component sources instead of caching them
+  per process (the railtie enables it in development): SSR markup no
+  longer goes stale behind the middleware's recompiled app.mrb until a
+  server restart. Concurrent renders serialize the reload, and a file
+  vanishing mid-edit does not break the mtime check.
+
+- Event-handler and HTTP-callback exceptions name the component and
+  handler on the console before re-raising, instead of an anonymous
+  "Callback <id>" line -- or, for HTTP callbacks, nothing at all.
+
+- `Schema.build` skips validator introspection for `readonly: true`
+  attributes: server-managed columns no longer fail client-side
+  validation against values the client never edits.
+
+- `Schema::RegexpTranslator` unescapes Ruby's `\#` identity escape, which
+  survives in `Regexp#source` but is rejected by the JS RegExp engine under
+  the `u` flag (`URI::MailTo::EMAIL_REGEXP` is the common casualty: one such
+  validator used to fail the whole client boot).
+
+- `Schema.serialize` now carries `allow_nil` / `allow_blank` through to the
+  client -- including kinds that serialize to a bare `true`, such as
+  `presence` and unconstrained `numericality`, which upgrade to a Hash --
+  so a validator on an optional attribute no longer rejects the nil or
+  blank value the server accepts.
+
+- A schema `format` regex the client runtime cannot compile downgrades to a
+  console warning and drops that one validator instead of failing the whole
+  schema load.
+
+- `FileUpload.upload_with_formdata` attaches the CSRF token from the
+  page's meta tag (Rails forgery protection rejected every upload) and
+  accepts a `method:` keyword instead of hard-coding PATCH.
+
+### Removed
+
+- The IndexedDB-backed HTTP response cache (`Funicular::HTTP` `cache:`
+  option, `cache_purge`, `cache_clear`). It was dead code -- no caller
+  anywhere passed `cache:` -- and the local database layer is this
+  release's answer to caching. Structured data belongs in replica tables,
+  not keyed response bodies.
+
+## [0.4.0] - 2026-07-23
 
 ### Added
 

data/demo/local_notes.html

@@ -0,0 +1,207 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Local Notes - Funicular</title>
+</head>
+<body>
+  <div><a href="../index.html">Back</a></div>
+  <h1>Local Notes (Funicular local database)</h1>
+  <!-- A page declaring storage :local models must choose its
+       namespace explicitly (docs decision 12) or the boot fails
+       loud. A Rails app gets these attributes from
+       picoruby_include_tag; this static page carries them by hand. -->
+  <div id="app"
+       data-funicular-local-database="true"
+       data-funicular-application-id="local_notes_demo"
+       data-funicular-anonymous-only="true"></div>
+
+  <div class="explain">
+    <p>A server-less demo of the local database layer:
+      <code>storage :local</code>, <code>.local</code> queries,
+      <code>watch</code>, snapshot persistence, the single-writer
+      election, and <code>Funicular::DB.wipe</code>.</p>
+    <ul>
+      <li><b>Add some notes, then reload the page.</b> The writer tab
+        snapshots the database into IndexedDB about half a second
+        after the last write, and the next visit restores it.</li>
+      <li><b>Open this page in a second tab.</b> Only one tab per
+        browser profile wins the writer election; the other becomes a
+        persistent reader whose writes raise. Close the writer tab
+        and reload the reader to take over.</li>
+      <li><b>Press "Wipe everything".</b> Both databases of this
+        namespace are dropped and rebuilt empty, the stored snapshots
+        are deleted, and the watcher re-renders onto empty tables.</li>
+      <li>The list re-renders through
+        <code>watch(:notes) { Note.local.order(created_at: :desc) }</code>
+        after every change event; no manual state bookkeeping.</li>
+    </ul>
+  </div>
+
+  <script type="text/ruby">
+    class Note < Funicular::Model
+      table_name "local_notes"
+      storage :local do
+        migrate 1 do |t|
+          t.string :title
+          t.timestamps
+        end
+      end
+    end
+
+    class NotesApp < Funicular::Component
+      READER_MESSAGE =
+        "This tab is a persistent reader: another tab holds the " \
+        "writer lock. Close the writer tab and reload to write here."
+
+      def initialize_state
+        # start boots the database before anything mounts, so the
+        # durability verdict is already final here.
+        {
+          notes: [],
+          message: "",
+          durability: Funicular::DB.durability,
+        }
+      end
+
+      def component_mounted
+        watch(:notes) { Note.local.order(created_at: :desc) }
+      end
+
+      def handle_add(event)
+        event.preventDefault
+        field = JS.document.getElementById("note-title")
+        title = field[:value].to_s
+        return if title.empty?
+        begin
+          Note.create(title: title)
+          field[:value] = ""
+          patch(message: "")
+        rescue Funicular::DB::ReadOnlyTabError
+          patch(message: READER_MESSAGE)
+        end
+      end
+
+      def handle_delete(note)
+        -> {
+          begin
+            note.destroy
+            patch(message: "")
+          rescue Funicular::DB::ReadOnlyTabError
+            patch(message: READER_MESSAGE)
+          end
+        }
+      end
+
+      def handle_wipe(event)
+        event.preventDefault
+        begin
+          Funicular::DB.wipe
+          patch(message: "Wiped: tables rebuilt empty, snapshots deleted.")
+        rescue Funicular::DB::ReadOnlyTabError
+          patch(message: READER_MESSAGE)
+        end
+      end
+
+      def render
+        notes = state[:notes]
+        div(class: "notes-app") do
+          p(class: "status") do
+            "durability: #{state[:durability]} | notes: #{notes.size}"
+          end
+          div(class: "composer") do
+            # A placeholder disappears as soon as text is typed, so it
+            # cannot be the field's accessible name.
+            label(for: "note-title") { "Note title" }
+            input(type: "text", id: "note-title",
+                  placeholder: "What to remember?")
+            button(onclick: :handle_add) { "Add" }
+            button(onclick: :handle_wipe, class: "danger") do
+              "Wipe everything"
+            end
+          end
+          p(class: "message") { state[:message] }
+          ul(class: "notes") do
+            notes.each do |note|
+              li(key: note.id) do
+                span(class: "title") { note.title }
+                span(class: "stamp") { note.created_at.to_s }
+                button(onclick: handle_delete(note), class: "delete") do
+                  "delete"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # No load_schemas round: a local-only app boots right inside
+    # start's gate. The namespace comes from the hand-written
+    # data-funicular-* attributes on the #app container above: pages
+    # with storage :local models must declare anonymous_only (or a
+    # user key) explicitly -- a silent shared default would merge
+    # every user's data, so the boot fails loud without it.
+    Funicular.start(NotesApp, container: 'app')
+  </script>
+  <script src="../init.iife.js"></script>
+</body>
+<style>
+.notes-app {
+  max-width: 560px;
+}
+
+.status {
+  color: #555;
+  font-family: monospace;
+}
+
+.composer input {
+  margin-right: 6px;
+  padding: 4px 6px;
+  width: 260px;
+}
+
+.composer button {
+  margin-right: 6px;
+}
+
+.composer .danger {
+  color: #a00;
+}
+
+.message {
+  color: #a00;
+  min-height: 1.2em;
+}
+
+ul.notes {
+  list-style: none;
+  padding: 0;
+}
+
+ul.notes li {
+  border-bottom: 1px solid #ddd;
+  display: flex;
+  gap: 10px;
+  padding: 6px 2px;
+}
+
+ul.notes .title {
+  flex: 1;
+}
+
+ul.notes .stamp {
+  color: #888;
+  font-size: 0.85em;
+}
+
+.explain {
+  border-top: 1px solid #ccc;
+  color: #333;
+  margin-top: 24px;
+  max-width: 640px;
+  padding-top: 12px;
+}
+</style>
+</html>