janela 0.3.0 → 0.4.0

data/docs/decisions/022-host-route-helpers-work-inside-the-engine.md

@@ -0,0 +1,104 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 004, ADR 005, ADR 011, ADR 019
+Triggers:
+  - a route helper raising inside Janela's controllers
+  - host code inherited from ApplicationController running in the engine
+  - authentication redirects
+  - anything that would make the engine less isolated
+Topics: host-integration, routing, engine-isolation, authentication
+---
+
+# ADR 022: A Host's Route Helpers Work Inside the Engine
+
+## Context
+
+`isolate_namespace Janela` points every route helper evaluated inside
+Janela's controllers at the engine's own route set. That is the right
+default for the engine's own code. It is the wrong answer for the
+host's, and the host's runs there constantly, because
+`Janela::ApplicationController` inherits the host's
+`ApplicationController` on purpose (ADR 004).
+
+Three reports, one cause, and each host found it separately:
+
+1. A host's application layout calling `root_path` in its nav, which
+   made every pane 500. Solved another way in 0.2.1 by not rendering
+   panes in the host's layout (ADR 011).
+2. A host authenticating per controller, whose `before_action`
+   redirected to `new_session_path`.
+3. A host authenticating globally, whose `Authentication` concern
+   redirected to `new_session_path` from inside the engine and raised
+   `ActionController::UrlGenerationError`. An unauthenticated visitor
+   got a 500 instead of a sign-in page.
+
+Case 3 is the one that shows the shape of the problem. The README had
+framed the fix as something to do "if your app authenticates per
+controller", which is not the trigger at all. The trigger is that a
+URL is generated by host code while it is inside the engine. A
+`rescue_from` that redirects, an `after_action`, a flash partial and an
+audit callback all qualify. Each host discovers it on its own, in
+production, as a 500.
+
+`main_app.new_session_path` is the documented fix and it works. It
+also asks every host to know that Janela is an isolated engine, and to
+remember it in code that has nothing to do with Janela. That is the
+opposite of what installing this gem is supposed to feel like.
+
+The option of including the host's `url_helpers` wholesale was
+considered and rejected. Both sets of helpers would then be present,
+and a name in both would resolve by module order, so `frames_path`
+inside Janela's own view could silently become the host's `/frames`.
+Trading a loud `UrlGenerationError` for a quietly wrong link is a bad
+trade.
+
+## Decision
+
+**Janela forwards to the host exactly those route helpers the engine
+does not define, and no others.**
+
+The set is computed when routes are loaded, as the host's helper names
+minus the engine's, and each one is defined to call `main_app`. It is
+rebuilt whenever routes reload, so a name that goes away goes away
+here too.
+
+```ruby
+# In a host's ApplicationController, running inside Janela:
+redirect_to new_session_path   # works, forwarded to the host
+frames_path                    # Janela's, never the host's /frames
+main_app.frames_path           # the host's, said unambiguously
+```
+
+Two properties matter more than the convenience:
+
+**The engine's own routes can never be shadowed.** A name is forwarded
+only when Janela does not define it, so no host route can change what
+one of Janela's own views means. Precedence is decided by
+construction, not by the order modules happened to be included.
+
+**`main_app` still means what it means.** Nothing is taken away. A
+host that prefers to be explicit, or that needs a name Janela also
+uses, says `main_app.` and is unambiguous.
+
+**This covers named helpers only.** `url_for(record)` and
+`redirect_to @record` resolve polymorphically at call time, so there
+is no name to forward and they still need `main_app.`. That boundary
+is documented rather than papered over.
+
+## Consequences
+
+- A host's authentication redirect works inside Janela with no
+  configuration, no reopened class and no knowledge that an engine is
+  involved. That was the whole complaint in three reports.
+- Janela is slightly less isolated than a textbook engine, in one
+  direction only: host names in, never Janela names out. ADR 005's
+  mount independence is untouched, since the engine still generates
+  every one of its own URLs through its own routes.
+- A host route helper shares a name with one of Janela's and the host
+  loses the bare name inside the engine. Janela's route names are few
+  and dull, which makes this rare, and `main_app.` remains.
+- The README's explanation was wrong about the cause and is corrected
+  here and there.
+- Polymorphic routing is a known gap. If it bites someone the answer
+  is another ADR, not a quiet widening of this one.

data/docs/decisions/023-vitral-is-a-theme-not-the-stylesheet.md

@@ -0,0 +1,86 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 011, ADR 016, ADR 021
+Triggers:
+  - changing how Janela looks
+  - adding a stylesheet, a class or a custom property
+  - adding a Stimulus controller to the gem
+  - adding a setting
+Topics: styling, host-integration, configuration, naming
+---
+
+# ADR 023: Vitral Is a Theme, Not the Stylesheet
+
+## Context
+
+ADR 016 gave Janela one stylesheet, deliberately plain: the grid classes
+an analyst's numbers choose from, and just enough style that a pane is
+legible on install. That was right, and it left an obvious gap. A host
+that wants a dashboard to look like something has to write all of it,
+and the first thing anyone does with a new library is judge how it
+looks.
+
+The temptation is to make `janela.css` prettier. That would be a
+mistake. Structure and taste have different lifetimes: the grid classes
+are load bearing and must not change, while taste is the first thing a
+host will want to replace and the first thing we will want to revise.
+Putting both in one file means every visual revision risks the layout,
+and every host that dislikes the look has to fight rules it also needs.
+
+## Decision
+
+**A second stylesheet, `vitral.css`, optional and separate.**
+
+A *vitral* is a stained glass window. Janela is a window, its parts are
+frames and panes, and this is what the glass looks like. The name
+follows the same rule as the rest: an uncommon but conceivable word, so
+it never collides with the vocabulary a host already uses for its own
+things.
+
+```erb
+<%= stylesheet_link_tag "janela" %>
+<%= stylesheet_link_tag "vitral" %>
+```
+
+Four rules hold it in place.
+
+**Nothing is repainted until asked.** The light and the leading hang off
+a `vitral` class. A host that links the stylesheet and adds no class
+gets nothing, which means linking it can never be the thing that broke
+a page.
+
+**It is a small library, not a private skin.** `vitral-pane`,
+`vitral-panes` and `vitral-button` are public, so the page around a
+dashboard can be made of the same window. Everything else is a custom
+property, so a host rethemes from its own stylesheet rather than by
+forking this one.
+
+**The theme must be complete without JavaScript.** Janela's own pages
+load none at all (ADR 011), so the stained glass is CSS, and the part
+that answers the pointer is a separate optional controller. The
+stylesheet carries a static lattice for everyone who never loads it.
+
+**Janela's own pages wear it by name.** `Janela.theme = "vitral"` is the
+third setting this gem has, and it earns that the same way the second
+did: which theme, if any, is a judgement made once about the whole
+application, and that is what configuration is for (ADR 021). A host
+that leaves it unset gets the structural stylesheet, exactly as before.
+
+## Consequences
+
+- Janela looks like something out of the box, and a host that hates it
+  removes one line rather than overriding a hundred rules.
+- `janela.css` can stay frozen and boring while the theme moves. A
+  revision to the look is not a revision to the grid.
+- The lattice is an inline SVG data URI rather than an image, because a
+  stylesheet shipped in a gem cannot rely on a host's asset pipeline to
+  resolve a `url()`.
+- Accessibility is the theme's problem, not the host's: reduced motion,
+  reduced transparency and increased contrast each fall back to a
+  still, solid window, and so does a browser without `backdrop-filter`.
+- A visual change to vitral is visible to every host that opted in, so
+  it belongs in the changelog like any other change a host can see
+  (ADR 015). It is not a breaking change, because nothing depends on it.
+- A third stylesheet is a third thing for a Sprockets host to declare
+  for precompilation. The engine declares both itself.

data/docs/decisions/024-selecting-more-than-one-value.md

@@ -0,0 +1,127 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 003, ADR 005, ADR 008, ADR 009, ADR 018
+Triggers:
+  - changing what a click on a value does
+  - adding a filter predicate or changing the URL grammar
+  - adding a keyboard shortcut
+  - anything a mouse can do that a keyboard cannot
+Topics: cross-filtering, urls, accessibility, ransack
+---
+
+# ADR 024: Selecting More Than One Value
+
+## Context
+
+A click on a value writes one Ransack condition, `q[status_eq]=paid`,
+and clicking the same value again removes it. One value per dimension.
+Every real dashboard eventually needs two: paid and pending, APAC and
+EU. A commercial tool does this with a modifier click, and everyone
+already knows the gesture.
+
+The gesture is the easy part. `toggle(event)` already receives the
+event, so `ctrlKey || metaKey` is there for a table button, and
+Chart.js hands its own click handler the native event. What needs
+deciding is what the URL says, what happens to the null group, and
+what someone without a mouse does instead, because a modifier click is
+invisible, absent on touch and unreachable from a keyboard. Deciding
+the gesture without deciding that last part would build a feature only
+some people can use (#35, #36).
+
+Three things were measured against the dummy before writing this,
+rather than assumed:
+
+- `status_in: [paid, pending]` passes Janela's allowlist guard and
+  returns the sum of both. A dimension's allowlist is per attribute, so
+  the predicate needs nothing added.
+- `status_eq: paid` still works, so an existing link keeps working
+  whatever a new click writes.
+- `channel_null: 1` together with `channel_in: [web]` **returns zero**.
+  Ransack ANDs its conditions, so that combination asks for rows whose
+  channel is both null and web.
+
+That last one is the whole difficulty. It does not raise. It renders
+an empty dashboard, which reads as a bug in Janela rather than as an
+impossible question.
+
+## Decision
+
+**A click selects, a modifier click adds, and the selection is a set.**
+
+Following the convention every list in every operating system already
+uses, so that nothing has to be learned:
+
+| Gesture | Result |
+| --- | --- |
+| Click an unselected value | That value alone is selected |
+| Click the only selected value | The dimension is cleared |
+| Click a value while others are selected | That value replaces them |
+| Ctrl or Cmd click | That value is added or removed, the rest stay |
+
+**Janela writes `_in`, and keeps reading `_eq`.** A click always
+produces `q[status_in][]=paid`, one value or five, so there is one
+shape in the controller, one in the view and one in a stored snapshot.
+A hand written or previously shared `_eq` link keeps working, because
+Ransack accepts it and because a URL somebody already sent should not
+stop working to suit us (ADR 005).
+
+**The null group is exclusive within its dimension.** Selecting
+`(none)` clears the other values of that dimension, and selecting a
+value clears `(none)`. The combination is unanswerable, and the honest
+options are to refuse it or to render nothing and let it look broken.
+
+Ransack can express the OR through its `g[]` grouping, and that is
+rejected. It would make the URL unreadable, and ADR 005's grammar is
+built on a URL a person can read and edit. It would also have to be
+understood by every stored snapshot and every hand written link
+forever, to serve a question almost nobody asks.
+
+**The keyboard gets the same two gestures, not a different feature.**
+A value is already a real `<button>` (ADR 018), so Enter is a click
+and **Ctrl or Cmd with Enter is a modifier click**, using the same
+flags on the same event. Nothing new is invented, and nothing has to
+be learned twice.
+
+**Janela binds exactly two keys, and only inside the frame.**
+
+- `Escape` clears the frame's filters.
+- `Enter` and `Space` act on the focused value, as they already do.
+
+No single letter keys. A single letter belongs to the host
+application, to its own shortcuts, and to any text field on the page.
+Janela is a guest in someone else's application and will not take a
+key that could mean something there. A host that wants `c` for clear
+binds its own control to `janela--frame#clear`, which is how the clear
+button already works.
+
+**A chart stays a mouse surface, and the table is the accessible one.**
+A bar is painted pixels with nothing focusable behind it. Rather than
+build a parallel focus model inside a canvas, Janela says plainly that
+the table renders the same data and is operable by keyboard, which is
+what ADR 018 made a table the universal renderer for. A chart
+highlights every selected value rather than one.
+
+## Consequences
+
+- A dashboard can answer "paid and pending", which is the ordinary
+  question this could not previously express.
+- `Query#selected_value` becomes `selected_values` and returns an
+  array. A host that overrode a pane view touches it, so this is a
+  breaking change, and it goes in UPGRADING.md with the version that
+  carries it (ADR 015).
+- A shared link's shape changes from `q[status_eq]=paid` to
+  `q[status_in][]=paid`. Older links keep working, so nothing that was
+  sent stops working.
+- The page URL and every pane `src` now carry repeated parameters. The
+  controller sorts filters so an unchanged `src` is never reloaded, and
+  it must sort the values inside a dimension too or a set will
+  serialise two ways and refetch every pane for nothing.
+- Touch has no modifier key, so a touch user gets replace-only
+  selection. That is a real gap and this ADR does not close it. The
+  answer, when someone needs it, is a control the host can render that
+  makes the next clicks additive, with the modifier as its accelerator
+  rather than the only path. Not built, because the simple thing has
+  not yet failed.
+- Snapshots store filters as JSON, so an array needs nothing new, and
+  a snapshot taken under `_eq` still reads.

data/docs/decisions/INDEX.md

@@ -65,7 +65,10 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 019 | A Created Frame Asks the Host Who Owns It | 2026-09-16 | Accepted |
 | 020 | Formatting Belongs to the Measure | 2026-09-16 | Accepted |
 | 021 | A Check Has a Name, and a Host Can Silence It | 2026-09-16 | Accepted |
+| 022 | A Host's Route Helpers Work Inside the Engine | 2026-09-16 | Accepted |
+| 023 | Vitral Is a Theme, Not the Stylesheet | 2026-09-16 | Accepted |
+| 024 | Selecting More Than One Value | 2026-09-16 | Accepted |
 
 ## Next number
 
-Next ADR: 022
+Next ADR: 025

data/docs/naming.md

@@ -0,0 +1,172 @@
+---
+Topics: naming, vocabulary, design, renaming
+---
+
+# Naming Things Is Hard
+
+There are two hard problems in computer science, and this page is about
+the one that is not cache invalidation. Every name in Janela was chosen
+on purpose, several were changed after they shipped, and one rule sits
+under all of them.
+
+## The rule
+
+> With words like Janela, Frame and Pane I am purposefully selecting
+> uncommon but understandable, conceivable words so that people aren't
+> pigeonholed and can select their own nomenclature.
+
+A library that calls its main idea a Dashboard has taken that word from
+every application that installs it. Your app probably already has a
+`Dashboard`, or a `Report`, or an `Insight`, and whatever you call yours
+is the word your users know. So Janela's own vocabulary is deliberately
+a step to the side: close enough to understand on first read, unusual
+enough that it never collides with the words you already use, and never
+the word your users have to see.
+
+That gives two tests for any name in this codebase:
+
+- **Conceivable.** Someone reading it for the first time can guess what
+  it is without looking it up.
+- **Uncommon.** It is unlikely to already be a model, a table, a route
+  or a word on your screens.
+
+## The window
+
+*Janela* is Portuguese for window. The word is the same in Portugal and
+in Brazil. Once the library is a window, the rest of its anatomy follows
+from the thing itself rather than from a list of synonyms for "chart".
+
+| Name | What it is | Why this word |
+| --- | --- | --- |
+| **Janela** | The library | A window onto your data. Uncommon in English, obvious once explained. |
+| **Frame** | A dashboard: a name and a grid of panes | A window frame holds the panes. It is also what Turbo calls the element that makes cross-filtering work (ADR 003), which is a happy accident rather than the reason. |
+| **Pane** | One visual inside a frame, stored as a row | A pane of glass sits in a frame. You look through each one at part of the picture. |
+| **Query** | The runtime object that calculates one pane | Not a window word, on purpose. It is an implementation detail rather than something a person arranges, so it gets the plain name for what it does. |
+| **Grid** | How a frame is divided: `columns`, `gap`, and each pane's `span` | A window is divided into panes, and the grid is the division. Small integers that choose a class the stylesheet already defines, so nothing an analyst types reaches CSS (ADR 016). |
+| **Vitral** | The optional stained glass theme | A stained glass window, in the same language. See ADR 023. |
+
+The anatomy was argued over before it was settled. *Sash* was
+considered for the dashboard and rejected: a sash is one layer inside a
+window, the moving part that holds glass, and the thing that holds
+panes is the frame.
+
+## Words that stay ordinary
+
+Not everything gets an unusual name, and the exceptions follow the same
+reasoning.
+
+**Measure and dimension** are the words the business intelligence field
+already agreed on. An analyst who has used any tool of that kind knows
+exactly what `measure :revenue` and `dimension :region` mean. They are
+also method names inside a model's `janela` block rather than classes
+sitting in your namespace, so there is nothing for them to collide with.
+A domain language should speak its reader's language (ADR 002).
+
+**Snapshot** and **owner** are plain because what they describe is
+plain: the numbers frozen at an instant, and whatever a frame belongs
+to. Janela assigns an owner and never reads it, so it has no reason to
+give it a clever name (ADR 009, ADR 019).
+
+**The doctor** is the conventional name for a command that reads your
+setup and tells you what is wrong. Homebrew, Flutter, npm and Bundler
+all ship one, so the word already means the right thing (ADR 021).
+
+## Your words, not ours
+
+None of Janela's vocabulary has to reach your users. Two places decide
+what they see.
+
+**The noun comes from your locale file.** Every heading the engine
+renders uses `Janela::Frame.model_name.human`, so your users read
+whatever you call them:
+
+```yaml
+en:
+  activerecord:
+    models:
+      janela/frame:
+        one: "Report"
+        other: "Reports"
+```
+
+**The address is wherever you mount it.** Frames live at the mount root
+and a pane's URL sits beneath the same path, so the words in the address
+bar are yours too:
+
+```ruby
+mount Janela::Engine => "/insights"
+```
+
+```
+/insights                   every frame
+/insights/3                 one frame
+/insights/orders/revenue    a pane
+```
+
+ADR 013 first gave frames a configurable path segment of their own. ADR
+014 took it back out, because a segment named `dashboards` or `reports`
+is exactly the kind of word a host model already owns, and it shadowed
+that model's panes. Keeping Janela's own words out of your URLs turned
+out to be the fix as well as the principle.
+
+## One word, one meaning
+
+A single name used for two things is worse than an awkward name, so
+some sentences in this codebase are spelled more carefully than they
+would be in conversation.
+
+**Frame** on its own always means the dashboard. The HTML element is
+always written **turbo frame**, in prose, in comments and in commit
+messages, so the two can never be confused.
+
+**Grid** always means a frame's layout, its columns and gap. The lines
+drawn between panes by the theme are leading, never grid.
+
+**Pane** always means the stored row. That is why the runtime object
+had to give the name up: it was `Janela::Pane` until ADR 014 renamed it
+`Janela::Query` so the record could take the word it deserved.
+
+## When a name turns out wrong
+
+Names were changed after release, and each change was treated as
+breaking rather than tidied away:
+
+- `janela_dashboard` became `janela_frame`, and the Stimulus controller
+  `janela--dashboard` became `janela--frame`.
+- `Janela::Pane` became `Janela::Query`, freeing `Pane` for the record.
+- `Janela::DashboardHelper` became `Janela::FramesHelper`.
+
+Every one of those is listed in `UPGRADING.md` with the exact
+replacement, and `bin/rails janela:doctor` finds any old name left in
+your code and names what replaced it (ADR 015). Renaming is allowed. A
+rename a user has to discover for themselves is not.
+
+## The look follows the name
+
+The demo and the vitral theme are not decoration picked separately.
+Once the library is a window, the design had one obvious direction.
+
+- **The panes are glass.** Each one holds its own colour, and the colour
+  cycles by position so a row is never monochrome.
+- **The lines between them are leading,** dark and slightly uneven, the
+  way lead holds real stained glass. The theme calls its colour
+  `--vitral-came`, after the lead strip itself, but that is a styling
+  detail to override rather than a word you need to know.
+- **The light comes from behind.** Shafts fall from a sun at the top
+  right, and hovering the mark fans light through the window, splitting
+  into its colours as it comes out the front.
+- **The lattice leans toward you.** Its nodes reach for the cursor,
+  because a dashboard is meant to respond to the person looking at it.
+
+## Naming something new
+
+If you are adding to Janela or forking it, the same checks apply:
+
+1. Would a stranger guess what it is from the name alone?
+2. Is it a word a Rails application is likely to have already?
+3. Does it already mean something else in this codebase, or in Rails,
+   or in Turbo?
+4. Is it something a person arranges, which earns a window word, or an
+   implementation detail, which gets a plain one?
+5. If you are renaming, have you added it to `UPGRADING.md` and taught
+   the doctor to find the old name?

data/lib/janela/engine.rb

@@ -24,7 +24,16 @@ module Janela
     # Janela's own layout links janela.css, and a host on Sprockets serves it
     # in production only if something declared it.
     initializer "janela.assets" do |app|
-      app.config.assets.precompile << "janela.css" if app.config.respond_to?(:assets) && app.config.assets.respond_to?(:precompile)
+      if app.config.respond_to?(:assets) && app.config.assets.respond_to?(:precompile)
+        app.config.assets.precompile << "janela.css"
+        app.config.assets.precompile << "vitral.css"
+      end
+    end
+
+    # A host's route names are only known once its routes are drawn, which is
+    # lazy and happens again on every reload in development.
+    initializer "janela.host_routes" do |app|
+      app.config.after_routes_loaded { Janela::HostRoutes.define! }
     end
 
     initializer "janela.importmap", before: "importmap" do |app|

data/lib/janela/host_routes.rb

@@ -0,0 +1,31 @@
+module Janela
+  # Route helpers the host application has and the engine does not, forwarded
+  # to the host.
+  #
+  # isolate_namespace points every route helper inside Janela's controllers at
+  # the engine's own routes, and a host's ApplicationController runs there,
+  # because Janela's controllers inherit it. So an authentication redirect, a
+  # rescue_from or an after_action that names one of the host's own routes
+  # raises where it would work anywhere else in the application (ADR 022).
+  #
+  # Only names the engine does not define are forwarded, so the engine's own
+  # routes can never be shadowed by a host's. main_app stays the unambiguous
+  # way to say either.
+  module HostRoutes
+    def self.define!(host: Rails.application.routes, engine: Janela::Engine.routes)
+      # Routes reload in development, so a name that has gone is removed
+      # rather than left behind pointing at nothing.
+      instance_methods(false).each { |method| remove_method(method) }
+
+      forwarded(host: host, engine: engine).each do |name|
+        define_method(name) do |*args, **options, &block|
+          main_app.public_send(name, *args, **options, &block)
+        end
+      end
+    end
+
+    def self.forwarded(host: Rails.application.routes, engine: Janela::Engine.routes)
+      host.named_routes.helper_names - engine.named_routes.helper_names
+    end
+  end
+end

data/lib/janela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Janela
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/janela.rb

@@ -10,6 +10,7 @@ require "janela/definition"
 require "janela/measure"
 require "janela/dimension"
 require "janela/doctor"
+require "janela/host_routes"
 
 module Janela
   class Error < StandardError; end
@@ -24,6 +25,12 @@ module Janela
   # and authorisation apply to dashboards with no configuration.
   mattr_accessor :parent_controller, default: "ApplicationController"
 
+  # The stylesheet Janela's own pages load on top of janela.css. Nil means the
+  # structural one only, which is what a host that has its own look wants. The
+  # gem ships "vitral". A host's own pages are untouched either way: they load
+  # whatever that host's layout says (ADR 023).
+  mattr_accessor :theme, default: nil
+
   # Checks janela:doctor should not report, by the name it prints beside each
   # finding. A check that is a false alarm for one application stays a false
   # alarm, and that is a judgement made once at boot, which is what a setting

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -99,7 +99,9 @@ files:
 - app/assets/javascripts/janela/chart_controller.js
 - app/assets/javascripts/janela/frame_controller.js
 - app/assets/javascripts/janela/vendor/chart.js
+- app/assets/javascripts/janela/vitral_controller.js
 - app/assets/stylesheets/janela.css
+- app/assets/stylesheets/vitral.css
 - app/controllers/janela/application_controller.rb
 - app/controllers/janela/frames_controller.rb
 - app/controllers/janela/panes_controller.rb
@@ -155,13 +157,18 @@ files:
 - docs/decisions/019-a-created-frame-asks-the-host-who-owns-it.md
 - docs/decisions/020-formatting-belongs-to-the-measure.md
 - docs/decisions/021-a-check-has-a-name-a-host-can-silence.md
+- docs/decisions/022-host-route-helpers-work-inside-the-engine.md
+- docs/decisions/023-vitral-is-a-theme-not-the-stylesheet.md
+- docs/decisions/024-selecting-more-than-one-value.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
+- docs/naming.md
 - lib/janela.rb
 - lib/janela/definition.rb
 - lib/janela/dimension.rb
 - lib/janela/doctor.rb
 - lib/janela/engine.rb
+- lib/janela/host_routes.rb
 - lib/janela/measure.rb
 - lib/janela/model.rb
 - lib/janela/version.rb
@@ -176,18 +183,14 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.3.0 needs two things from you. Run the migrations, because the
-  mount root now serves an index of frames:
-
-    bin/rails janela:install:migrations && bin/rails db:migrate
-
-  Then rename the Stimulus controller you register, the helper that wraps
-  your panes, and a few constants.
+  Janela 0.4.0 selects more than one value in a dimension. Most applications
+  need do nothing. You need to act only if you override a pane view, where
+  selected_value is now selected_values, or if something of yours reads
+  Janela's URLs, where a click now writes q[field_in][] rather than
+  q[field_eq]. Links already shared keep working.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md
-
-  Then run: bin/rails janela:doctor
 rdoc_options: []
 require_paths:
 - lib