janela 0.3.0 → 0.4.1

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/025-janela-bounds-what-a-filter-can-ask-for.md

@@ -0,0 +1,131 @@
+---
+Date: 2026-09-17
+Status: Accepted
+Related: ADR 002, ADR 005, ADR 006, ADR 007, ADR 008, ADR 015, ADR 024
+Triggers:
+  - a filter reaching Ransack from a URL
+  - adding a predicate, or widening what a filter may contain
+  - a query with no LIMIT, or a grouped query over a high cardinality dimension
+  - deciding whether a bound belongs to Janela or to the host
+Topics: security, ransack, urls, performance, cross-filtering
+---
+
+# ADR 025: Janela Bounds What a Filter Can Ask For
+
+## Context
+
+ADR 002 chose Ransack so that a host's filters are the Ransack params a
+Rails developer already reads, and made a dimension declaration the
+allowlist of attributes. That part holds. What it left open is which
+*predicates* may be used on an allowed attribute, and issue #8 asked the
+question.
+
+Measured against the demo before writing this:
+
+| Filter passed | Result today |
+| --- | --- |
+| `status_eq: "paid"` | 300.0 |
+| `status_cont: "pai"` | 300.0 |
+| `status_start: "p"` | 325.0 |
+| `status_matches: "%aid"` | 300.0 |
+| `customer_name_cont: "cm"` | 150.0 |
+| `amount_gt: 60` | `BadRequest`, `amount` is not a dimension |
+| `status_frobnicate: "x"` | `BadRequest`, no such predicate |
+
+So the attribute allowlist works, and every predicate Ransack knows is
+reachable on an allowed attribute, including through an association.
+`Ransack::Predicate.names` has 62 entries. The sharpest is `_matches`,
+which takes an arbitrary `LIKE` pattern, so a leading wildcard scan of an
+indexed column is one URL edit away, in a page a host has already
+authorised someone to read.
+
+Two other bounds are missing. A grouped query with no `limit` carries no
+`LIMIT` in SQL at all, so a breakdown by a high cardinality dimension
+returns a row per value. And a single filter can carry any number of
+values: `status_in` with 5001 of them was answered rather than refused,
+which matters more since ADR 024 made `_in` the shape a click writes.
+
+**The question worth deciding is whose job this is.** ADR 002
+deliberately spent Ransack's familiarity on the host, and the obvious
+objection to bounding anything here is that a host can restrict filtering
+itself by defining `ransackable_attributes`. That objection is false, and
+the measurement above is why: `ransackable_attributes` allows *columns*,
+and Ransack has no per-attribute predicate allowlist. Once a host allows
+a column for equality, it has allowed `_matches` on that column too.
+There is nowhere else for this bound to live.
+
+Options considered and rejected:
+
+- **Leave it, and document it.** A dashboard is often the first page a
+  company exposes to people it would not give SQL to, and the library
+  hands them a pattern scan. Documenting a sharp edge is not the same as
+  not having one.
+- **Restrict to `_eq` and `_in`,** as issue #8 proposed. It would delete
+  documented behaviour: ADR 006 allows `placed_on_gteq` and
+  `placed_on_lt` so a host can narrow a time range, and the README says
+  so. A range filter on a time dimension is a dashboard's ordinary
+  question, not an escape hatch.
+- **A setting listing the allowed predicates.** Rejected on the test
+  ADR 021 and ADR 023 set: a setting earns itself when the judgement is
+  made once about the whole application and cannot be inferred. This one
+  can be inferred, from what kind of dimension is being filtered.
+
+## Decision
+
+**Janela allows only the predicates a dashboard asks in, bounds what a
+grouped query returns, and bounds how many values one filter may carry.**
+
+**Predicates are allowed by the kind of dimension.** A categorical
+dimension takes `eq`, `in` and `null`, which is exactly what a click
+produces (ADR 024). A time dimension additionally takes `gteq`, `gt`,
+`lteq` and `lt`, because narrowing a range is how a time dimension is
+filtered (ADR 006). Anything else raises `Janela::BadRequest` naming the
+attribute and the predicates that are allowed, the way a disallowed
+attribute already does.
+
+The check belongs beside the existing one in `Definition#filter`, which
+already raises for a filter Ransack silently dropped. `Ransack::Predicate
+.detect_from_string` splits a key into attribute and predicate, so this
+is a comparison, not a parser.
+
+**One ceiling, 1000, in both places.** A grouped query with no `limit`
+gets `LIMIT 1000`, and a single filter may carry at most 1000 values.
+1000 is not a new number: ADR 007 already fixed it as the maximum a host
+may ask for, so the ceiling is the existing maximum applied by default
+rather than a second constant to reason about. A pane that hits the
+ceiling is unreadable long before it is reached, so this is a bound on
+harm, not on usefulness.
+
+**Time panes keep their exemption.** ADR 007 exempted them from `limit`
+because a time series shows its whole range, and gap filled buckets are
+generated rather than returned by the database. The ceiling does not
+apply to them. A host that wants fewer buckets narrows the range or
+coarsens the granularity, which ADR 006 already allows.
+
+**No setting is added.** A host that genuinely needs a pattern search
+already has the documented way in: pass a pre-filtered relation through
+`on:`, where it writes the condition itself in its own code, under its
+own authorisation, rather than accepting one from a URL.
+
+## Consequences
+
+- The reachable filter surface goes from 62 predicates to three on a
+  categorical dimension and seven on a time dimension. That is the point.
+- **Breaking for a host that passes anything else.** A `_cont` or
+  `_matches` filter that works today raises `BadRequest` after this. It
+  needs an `UPGRADING.md` entry naming the allowed predicates and the
+  `on:` alternative, and the release carrying it is minor (ADR 015).
+  The doctor cannot find this one by reading source, because the filter
+  is usually built at runtime; the upgrade note is the whole mitigation.
+- A stored snapshot holds the filters it was taken under (ADR 009). One
+  taken with a now disallowed predicate would raise when read. Whether to
+  refuse those at read time or leave stored results alone is not decided
+  here and should be settled while building this.
+- The default ceiling changes a number a host can see: a breakdown over
+  more than 1000 values silently showed all of them and will now show
+  1000. It is ordered by the measure, so what is cut is the smallest, and
+  a host that wants a different cut passes `limit`.
+- What would change this: a host with a real need for a predicate not on
+  the list. The answer is to add that predicate to the list for that kind
+  of dimension, in an ADR that says which dashboard question needed it,
+  not to make the list configurable.

data/docs/decisions/INDEX.md

@@ -21,23 +21,24 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | Topic | ADRs |
 |-------|------|
 | **Vision, scope, forkability** | 001, 010, 012 |
-| **Open-source & host-decoupling** | 001 |
-| **DSL & query layer** | 002, 006, 007 |
-| **Dependencies** | 002, 003, 004, 006, 017 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019 |
-| **Performance & storage** | 007, 017 |
-| **Cross-filtering & Hotwire** | 003, 004, 005, 008 |
-| **Layouts & views** | 011, 012, 016, 018 |
-| **CSS & styling** | 016, 018 |
+| **Open-source & host-decoupling** | 001, 022 |
+| **DSL & query layer** | 002, 006, 007, 020, 025 |
+| **Dependencies** | 002, 003, 004, 006, 017, 025 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022 |
+| **Performance & storage** | 007, 017, 025 |
+| **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025 |
+| **Layouts & views** | 011, 012, 016, 018, 020 |
+| **CSS & styling** | 016, 018, 023 |
 | **Frames, panes & persistence** | 012, 013, 014, 019 |
-| **Naming rule** | 014 |
+| **Naming rule** | 014, 023 |
 | **JavaScript delivery & charts** | 004, 006 |
-| **Time dimensions** | 006 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013 |
-| **Snapshots & publishing** | 009 |
-| **AI agents & guidance** | 010, 015 |
-| **Releases & upgrades** | 015 |
-| **Security** | 003 |
+| **Time dimensions** | 006, 025 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025 |
+| **Snapshots & publishing** | 009, 020 |
+| **AI agents & guidance** | 010, 015, 021 |
+| **Releases & upgrades** | 015, 021 |
+| **Accessibility & keyboard** | 024 |
+| **Security** | 003, 025 |
 | **Testing** | 003 |
 
 ## Chronological
@@ -65,7 +66,11 @@ 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 |
+| 025 | Janela Bounds What a Filter Can Ask For | 2026-09-17 | Accepted |
 
 ## Next number
 
-Next ADR: 022
+Next ADR: 026

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?