janela 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7fbc539879d1f11c15536c9305299ab9a754add8e26bb443cb582ea236823be
-  data.tar.gz: 150f1292e5c2789cb378e6438c91fd94b766e10088f4daa4aea445ba63341a1b
+  metadata.gz: e79c9733a355bce01c020c4dd98b34599167b88aa86ecbd20ffe8fdd2ea8842b
+  data.tar.gz: da0d442d1607b6347e5851ba136984da8009eac44ac8e453e2f8024a927016e0
 SHA512:
-  metadata.gz: a6d3e5390adf6ac5882d621abc014986f0da17cadad2bca3ba3404d9d2f0d4c744130d7163be7271ddfc70c1404250d1a9a3aa09f274d88a44be57c93c1ac8d4
-  data.tar.gz: 3d7d77e7022225e40c4c13f150818cfd646b0383400bbc59590014caa877b61894f6a1d0b4f056b4d438a1738b6c1489ead2d4ca60bb58caa9fa7554a15b8637
+  metadata.gz: 5ac5148b2676651bfdf2fabc046b960c475c3abd93ee4797b80cb869c733575933ce863360c455511cd12fb4b64c0a524ac5c21578ef271a34b4070e1df6ce21
+  data.tar.gz: 4898a621a1ed7312b8a13f5d42908bfd0e8ec10360984318f090b0b7c12258a390bd9025c2112f7a16d9dfe033d0c403225c4e6659cdf18548a413a03663328d

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-18
+
+### Added
+
+- `Janela.renderers`, `Janela.granularities` and `Janela.offered_limits`, alongside the existing `Janela.definitions`, so a gallery of what Janela can draw asks the gem rather than reading `Janela::Query::RENDERERS`, `Janela::Dimension::GRANULARITIES` or `Janela::Pane::OFFERED_LIMITS` directly. `test/dummy`'s `/gallery` is the reference page ADR 027 describes, built from exactly that surface plus `janela_pane`: a live pane per renderer per model, with the declaration that produced it beside it. A renderer a model cannot demonstrate, for want of a suitable dimension, is shown as unavailable rather than hidden, and a host with no `janela` models yet gets an explanation rather than a blank page (ADR 026, ADR 027, #39).
+
+### Changed
+
+- **Breaking.** A filter is bound to what kind of dimension it names rather than to every predicate Ransack knows. Every one of Ransack's 62 predicates worked on any allowed attribute, `_matches` sharpest among them: an arbitrary `LIKE` pattern, a leading wildcard scan away, on a page a host had already authorised someone to read. A categorical dimension now takes `eq`, `in`, `null` and `not_null`; a time dimension additionally takes `gteq`, `gt`, `lteq` and `lt`, which is exactly what a click produces (ADR 024) plus the range narrowing ADR 006 already documented. Anything else raises `Janela::BadRequest` naming the filter and what the dimension allows, rather than Ransack silently dropping it and a pane showing a number nobody asked for. A grouped query with no `limit` now gets one anyway, at the existing ceiling of 1000 (ADR 007); a single filter may carry at most 1000 values. `rails janela:doctor` finds a hardcoded filter that used a predicate no longer allowed, when it is written in the host's own source rather than read from a URL (ADR 025, #8).
+
+## [0.4.1] - 2026-09-17
+
+### Fixed
+
+- `Janela::HostRoutes.forwarded` could return an empty set. Route loading is lazy, so calling it before anything had drawn the host's routes, such as from a host's own initializer, silently forwarded nothing rather than raising. It now draws the routes first if they are not already loaded (#37).
+
 ## [0.4.0] - 2026-09-17
 
 ### Added
@@ -122,6 +138,8 @@ First alpha, installed from GitHub for testing in a single host application.
 - Only models that declare a `janela` block are addressable over HTTP.
 - ADRs 001 to 004 in `docs/decisions/`, shipped inside the gem.
 
+[0.5.0]: https://github.com/retail-tasker/janela/releases/tag/v0.5.0
+[0.4.1]: https://github.com/retail-tasker/janela/releases/tag/v0.4.1
 [0.4.0]: https://github.com/retail-tasker/janela/releases/tag/v0.4.0
 [0.3.0]: https://github.com/retail-tasker/janela/releases/tag/v0.3.0
 [0.2.1]: https://github.com/retail-tasker/janela/releases/tag/v0.2.1

data/README.md

@@ -27,7 +27,7 @@ Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has t
 
 ```ruby
 # Gemfile
-gem "janela", "~> 0.4"
+gem "janela", "~> 0.5"
 ```
 
 ```ruby
@@ -166,6 +166,8 @@ Scope a query to whatever the current user is allowed to see with `on:`:
 Order.janela.query(:revenue, by: :status, on: policy_scope(Order))
 ```
 
+A filter is bound to what kind of dimension it names, not to every predicate Ransack knows (ADR 025). A categorical dimension takes `eq`, `in`, `null` and `not_null`; a time dimension additionally takes `gteq`, `gt`, `lteq` and `lt`, so a range still narrows it. Anything else, such as `_cont` or `_matches`, raises `Janela::BadRequest` naming what is allowed. A grouped query with no `limit` gets one anyway, capped at 1000, and a single filter may carry at most 1000 values.
+
 Declaring a dimension makes that attribute filterable, so Janela defines the model's Ransack allowlist for you. A model that already defines its own keeps it. A `through:` dimension also needs the **associated** model to allow the attribute, because Ransack's allowlist is per-class:
 
 ```ruby
@@ -294,6 +296,19 @@ Every pane has its own URL under the mount, and a Turbo Frame in a dashboard loa
 
 The model is its route key (`orders`, `sales_orders`), then the measure, then optionally the dimension. Where an analyst would say *by*, the URL has a `/`; *where* is a `q` filter; *as a bar chart* is `?as=bar`; *top ten* is `?limit=10`; *as of* a snapshot is `/snapshots/:id/` in front. Category panes are always ordered by the measure, largest first; time panes are chronological. A pane opened on its own renders with its filters applied, so a filtered pane is a link you can send someone. ADR 005 has the grammar, ADR 011 the layout it renders in.
 
+### What Janela can draw
+
+`Janela.renderers`, `Janela.granularities` and `Janela.offered_limits` answer what a pane can be drawn as, without reaching into `Janela::Query::RENDERERS`, `Janela::Dimension::GRANULARITIES` or `Janela::Pane::OFFERED_LIMITS`. `Janela.definitions` answers the other half: every model that declares a `janela` block, with its own measures and dimensions. A gallery of every renderer, live against your own data, is a page you build from those four calls and `janela_pane`, not one the engine serves (ADR 026, ADR 027):
+
+```erb
+<% Janela.definitions.each do |definition| %>
+  <h2><%= definition.model.model_name.human %></h2>
+  <%= janela_pane definition.model, definition.measures.keys.first %>
+<% end %>
+```
+
+`test/dummy`'s `/gallery` is the reference: every renderer, per model, with the declaration that produced it beside it. A renderer a model cannot demonstrate, for want of a suitable dimension, shows as unavailable rather than disappearing, and a model with no `janela` block anywhere yet gets told so rather than an empty page.
+
 ### Snapshots
 
 A snapshot freezes the results of several panes at one instant, under one set of filters, so an audience sees exactly what was signed off while the live dashboard stays editable. Results are stored, not HTML; a stored pane can still be drawn as a table or a chart. It needs the same migrations frames do.
@@ -435,7 +450,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## Status
 
-**v0.4.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.5.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,59 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.4.1 to 0.5.0
+
+A filter is now bound to what kind of dimension it names (ADR 025). Most
+hosts do nothing: a click already writes `_eq` or `_in`, both still
+allowed. Three things need you only if you have gone further than that.
+
+**1. A predicate outside a dimension's allowlist now raises.**
+
+A categorical dimension (`dimension :status`) allows `eq`, `in`, `null`
+and `not_null`. A time dimension (`dimension :placed_on, granularity:
+:day`) additionally allows `gteq`, `gt`, `lteq` and `lt`. Anything else,
+most often `_cont`, `_matches`, `_start` or `_end`, now raises
+`Janela::BadRequest` instead of quietly filtering:
+
+```ruby
+- Order.janela.query(:revenue, where: { status_cont: params[:q] })
++ Order.janela.query(:revenue, where: { status_eq: params[:q] })
+```
+
+If you need a real pattern search, pass a relation you have already
+filtered through `on:`, where you write the condition yourself, under
+your own authorisation, rather than accepting one from a URL:
+
+```ruby
+Order.janela.query(:revenue, on: Order.where("status LIKE ?", "%#{params[:q]}%"))
+```
+
+Run `bin/rails janela:doctor` after upgrading: it finds a disallowed
+predicate hardcoded in your own source, the same way it finds a stale
+identifier. It cannot find one built from a URL param at request time;
+there is nothing in your source to read.
+
+**2. A grouped query with no `limit` now gets one anyway.**
+
+A breakdown over more than 1000 values used to return all of them and
+now returns the top 1000, ordered by the measure (ADR 007). Pass
+`limit:` yourself if you want a different cut:
+
+```ruby
+- Order.janela.query(:revenue, by: :customer)
++ Order.janela.query(:revenue, by: :customer, limit: 1000)  # unchanged
+```
+
+Nothing to do if your dashboard already has fewer than 1000 groups, or
+already passes `limit:`.
+
+**3. A single filter may not carry more than 1000 values.**
+
+`status_in` (or any other array predicate) with more than 1000 values
+now raises `Janela::BadRequest` instead of being answered. Nothing to
+do unless you build a filter with more values than that yourself; a
+click never does.
+
 ## 0.3.0 to 0.4.0
 
 Selecting more than one value in a dimension (ADR 024). Most hosts do

data/docs/decisions/010-agent-guidance-ships-the-agent-waits.md

@@ -3,6 +3,7 @@ Date: 2026-09-15
 Status: Accepted
 Related: ADR 001, ADR 005, ADR 009, ADR 012, ADR 014
 Superseded in part by: ADR 012
+Not implemented: the host skill, the install task and the agent definition
 Triggers:
   - writing or changing guidance for AI agents about using Janela
   - proposing that Janela ship an agent, a skill or an MCP surface to hosts

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/026-a-renderer-is-the-seam-and-html-comes-first.md

@@ -0,0 +1,93 @@
+---
+Date: 2026-09-18
+Status: Accepted
+Related: ADR 016, ADR 023, ADR 001, ADR 012
+Triggers:
+  - adding a visualisation or a renderer
+  - reaching for a charting library
+  - anything that would make how a pane is drawn configurable
+  - building the gallery
+Topics: rendering, styling, configuration, host-integration
+---
+
+# ADR 026: A Renderer Is the Seam, and HTML Comes First
+
+## Context
+
+Janela draws bar and line panes with Chart.js today, tables with plain
+HTML, and a value pane with a number in a div. That mix happened rather
+than being decided, and the next visualisation makes the question
+unavoidable: is Janela a wrapper around a charting library, or something
+that draws with whatever suits and reaches for a library only when it
+has to?
+
+Three things are being asked at once, and they have one answer between
+them.
+
+**Where a charting library sits.** A pane already names its renderer, so
+`renderer: "bar"` is a name on a record and the code behind it is ours.
+Nothing about Chart.js is in that name. Treating the renderer as the
+seam means a visualisation can change how it is drawn without any host
+noticing, and a host that wants a different bar chart replaces one small
+piece rather than the library.
+
+**Whether a visualisation needs JavaScript at all.** Most do not. A bar
+chart is a div with a percentage width. A ranked list is a table with a
+bar behind each row. A sparkline is inline SVG the server can render
+whole. Drawn that way the pane is in the HTML: it is there before any
+JavaScript loads, it prints, a screen reader can read it, and a click to
+cross-filter is a real button, which is already how the table renderer
+behaves and already how ADR 024's keyboard support works. A canvas can
+do none of that without being taught each one.
+
+The engine's own frame page already proves the point from the other
+side: it loads no chart runtime, so it renders a chart pane as a table,
+and the pane is still useful.
+
+**Whether a host should choose the charting library.** A setting for
+this is the obvious idea and the wrong one. It would mean every renderer
+written against an interface wide enough for any library, an adapter per
+library, and a test matrix multiplied by the number of libraries anyone
+has configured. ADR 001 kept Janela to a load bearing 5%, and the
+project's stance is that forking a small piece is a normal way to use
+this library, not a fallback. A renderer small enough to read in one
+sitting is worth more than a plugin system.
+
+## Decision
+
+**A renderer is the seam. Server rendered HTML and CSS are the default,
+a JavaScript library is an implementation detail of the renderers that
+need one, and there is no setting for choosing it.**
+
+1. A pane's `renderer` names a way of drawing, not a technology. What is
+   behind that name can change without a host changing anything.
+2. A new visualisation is built in HTML and CSS unless it cannot be. A
+   library earns its place by doing something the document cannot:
+   dense data, animation, interaction a button cannot express.
+3. Every renderer degrades to something readable with no JavaScript,
+   because a pane is rendered on the server before anything runs.
+4. No `Janela.chart_library` or equivalent. A host that wants a
+   different chart replaces a renderer, and the renderers stay small
+   enough that this is reasonable.
+5. Vitral reaches into the visualisation, not only the page around it.
+   The palette a bar takes, how a pane is framed and how a selection is
+   shown are part of the theme (ADR 023), which is what makes a
+   visualisation gallery a property of the gem rather than of the demo.
+
+## Consequences
+
+The gallery becomes gem work: a mountable page listing every renderer as
+a live pane against whatever data the host has, with the declaration
+that produced it beside it, and the theme applied. It is documentation
+that cannot go stale, because it is the real thing rendering. It is also
+the roadmap, since a renderer that does not exist yet is a visible gap
+rather than a line in a backlog.
+
+Chart.js stays for bar and line until a renderer that does not need it
+is written and measured against it. Nothing here asks a host to change
+anything today.
+
+The cost is that some visualisations are more work in HTML and CSS than
+in a library, and we accept that where the result stays readable without
+JavaScript. Where it does not, the library is the right answer and the
+renderer says so.

data/docs/decisions/027-the-gallery-is-a-host-page.md

@@ -0,0 +1,87 @@
+---
+Date: 2026-09-18
+Status: Accepted
+Related: ADR 011, ADR 016, ADR 018, ADR 023, ADR 026
+Triggers:
+  - building or changing the gallery
+  - adding a renderer
+  - exposing what Janela can draw to a host
+  - anything that would put JavaScript on the engine's own pages
+Topics: rendering, host-integration, layouts, styling
+---
+
+# ADR 027: The Gallery Is a Host Page, Built from the Gem's Helpers
+
+## Context
+
+ADR 026 decided that a gallery of renderers belongs in the gem rather
+than in the demo, because vitral reaches into the visualisation and a
+host should see its own data drawn its own way. It did not say what "in
+the gem" means, and investigating #39 showed that the obvious reading is
+the one that cannot work.
+
+The obvious reading is a page the engine serves, at the mount path,
+alongside the frames index. ADR 018 rules it out in its own words: "the
+engine's own pages deliberately load no Stimulus and no Chart.js." That
+is why a chart pane renders as a table there, and `frames_test.rb`
+asserts exactly that. A gallery of every renderer served by the engine
+would render table as a table, bar as a table and line as a table. It
+could not demonstrate the thing it exists to demonstrate.
+
+The same constraint takes the live configuration panel with it. The
+two-step form for adding a pane exists because, as the comment on
+`panes/new.html.erb` puts it, "the engine's pages run no JavaScript, so
+one select cannot refill another". A panel where changing a select
+re-renders the pane beside it is that, exactly.
+
+The way out is already built. `janela_pane(model, measure, by:, as:,
+granularity:, limit:)` renders any pane into a host's own page, where
+that host's JavaScript, layout and theme already are. ADR 011 sent panes
+there deliberately. A gallery is a page of panes.
+
+## Decision
+
+**The gallery is a page the host owns, built from helpers and
+enumerations the gem provides. The engine serves no gallery, and no
+JavaScript is added to the engine's own pages.**
+
+1. The gem's job is to make the page trivial to build: rendering a pane
+   into a host page already works, and what can be drawn becomes a
+   public enumeration rather than something a host reads out of a
+   constant. A gallery has to ask what renderers exist, what
+   granularities and limits are offered, and what a host's models
+   declare, and each of those is a supported question.
+2. The page itself is the host's: its route, its layout, its words. That
+   is the same trade ADR 011 made and the reason a host's theme and
+   assets are present at all.
+3. The demo carries the reference implementation, and it is the one we
+   look at. It is a host page like any other, so what works there works
+   for a host that copies it.
+4. Anything interactive in it is the host's JavaScript, which means the
+   gem's own Stimulus controllers are available there as they already
+   are for frames and charts. Nothing changes on the engine's pages,
+   and ADR 011 and ADR 018 stand untouched.
+
+## Consequences
+
+A host gets a gallery by mounting a page rather than by installing the
+gem, which is a real cost: it is not there on day one the way the frames
+index is (ADR 013). We accept it, because a gallery that cannot draw a
+chart would be worse than no gallery, and because the page is small when
+the helpers and enumerations are right.
+
+What the gem owes the page is now the work: an enumeration of renderers
+and their options that does not require reaching into
+`Janela::Query::RENDERERS`, and an answer for a host whose models
+declare nothing yet, since a gallery with no data to draw still has to
+say something useful.
+
+There are three renderers today, table, bar and line, one of which is
+the fallback the others degrade to. The gallery is therefore mostly a
+frame for what comes next rather than a showcase of what exists, which
+is the point of ADR 026 and worth saying plainly so nobody builds it
+expecting a wall of charts.
+
+If a gallery a host gets for free ever matters more than the engine's
+pages staying JavaScript free, this is the decision to supersede, and
+ADR 018 goes with it.

data/docs/decisions/028-the-predicate-list-adr-025-named.md

@@ -0,0 +1,75 @@
+---
+Date: 2026-09-18
+Status: Accepted
+Related: ADR 006, ADR 007, ADR 009, ADR 024, ADR 025
+Supersedes: ADR 025, in the predicate list and in what it says about snapshots
+Triggers:
+  - changing which predicates a dimension allows
+  - adding a predicate a click can produce
+  - reasoning about what a stored snapshot validates when it is read
+Topics: security, scope, urls, snapshots
+---
+
+# ADR 028: The Predicate List ADR 025 Named Was Not Quite Right
+
+## Context
+
+ADR 025 decided that Janela bounds what a filter can ask for, and it was
+right about the problem: every one of Ransack's 62 predicates was
+reachable on any attribute a dimension declared, a grouped query carried
+no `LIMIT`, and one filter accepted 5001 values. Building it (#8) proved
+all three still true and closed them.
+
+Two things the ADR said turned out not to survive contact with the code.
+An accepted ADR is not rewritten, so this records what is true instead.
+
+**The list it named would have broken behaviour the project already
+documents.** ADR 025 gave a categorical dimension `eq`, `in` and `null`,
+on the grounds that those are what a click produces (ADR 024). But
+`not_null` is already used, already tested in `definition_query_test.rb`,
+and has nothing to do with the hole being closed. Shipping the list as
+written would have refused a filter a host is entitled to use, loudly, in
+the name of security it does not buy.
+
+**The snapshot risk it described does not exist.** ADR 025 warned that a
+stored snapshot taken under a predicate later disallowed "would raise
+when read". It cannot. `Snapshot#stored_result` looks a pane up by key
+and returns the stored JSON; it never re-runs the query and never touches
+Ransack again. A snapshot's `filters` are metadata `Snapshot.take` built
+with, not something a read validates against. The fear was reasonable and
+the code does not have it.
+
+## Decision
+
+**A categorical dimension allows `eq`, `in`, `null` and `not_null`. A
+time dimension allows those plus `gteq`, `gt`, `lteq` and `lt`. Reading a
+stored snapshot validates no predicates, because it runs no query.**
+
+Everything else ADR 025 decided stands: predicates are allowed by the
+kind of dimension rather than globally, anything outside the list raises
+`Janela::BadRequest` naming the attribute and what is allowed, and one
+ceiling of 1000 bounds both an unlimited grouped query and the number of
+values a single filter may carry (ADR 007).
+
+The rule for adding to the list, so this does not become a place things
+accumulate: a predicate belongs there if a dashboard produces it, or if
+it is a boolean test of presence rather than a way to phrase a match.
+`not_null` qualifies on the second. `cont`, `matches` and `start` do not
+qualify on either, which is the whole point of the bound.
+
+## Consequences
+
+The built list is one predicate wider than the decided one, and a host
+using `not_null` keeps working rather than being broken by a security
+fix. That is the right trade, and it is worth naming why it was close: a
+list written from first principles in an ADR, without running it against
+the tests, refused something real.
+
+A regression test in `snapshot_test.rb` now pins the snapshot behaviour,
+so the failure mode ADR 025 imagined cannot appear later without a test
+noticing.
+
+The general lesson, which is why this is an ADR rather than a commit
+message: an ADR that names a specific list is making a claim about the
+code, not only about the design, and that claim needs checking against
+the code before the ADR is accepted rather than while it is built.

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, 027 |
+| **CSS & styling** | 016, 018, 023, 026, 027 |
 | **Frames, panes & persistence** | 012, 013, 014, 019 |
-| **Naming rule** | 014 |
-| **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 |
+| **Naming rule** | 014, 023 |
+| **JavaScript delivery & charts** | 004, 006, 026 |
+| **Time dimensions** | 006, 025 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025 |
+| **Snapshots & publishing** | 009, 020, 028 |
+| **AI agents & guidance** | 010, 015, 021 |
+| **Releases & upgrades** | 015, 021 |
+| **Accessibility & keyboard** | 024 |
+| **Security** | 003, 025, 028 |
 | **Testing** | 003 |
 
 ## Chronological
@@ -68,7 +69,11 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 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 |
+| 026 | A Renderer Is the Seam, and HTML Comes First | 2026-09-18 | Accepted |
+| 027 | The Gallery Is a Host Page, Built from the Gem's Helpers | 2026-09-18 | Accepted |
+| 028 | The Predicate List ADR 025 Named Was Not Quite Right | 2026-09-18 | Accepted |
 
 ## Next number
 
-Next ADR: 025
+Next ADR: 029

data/lib/janela/definition.rb

@@ -1,5 +1,9 @@
 module Janela
   class Definition
+    # ADR 007's existing ceiling on a limit, reused by ADR 025 as the default
+    # applied when a host asks for none, and as the bound on one filter's values.
+    MAXIMUM = 1000
+
     attr_reader :model, :measures, :dimensions
 
     def initialize(model)
@@ -35,7 +39,7 @@ module Janela
         measure.apply(buckets).transform_keys { |bucket| dimension.label(bucket, granularity) }
       else
         grouped = relation.group(dimension.attribute).order(Arel.sql("#{measure.sql_alias} DESC"))
-        grouped = grouped.limit(limit!(limit)) if limit
+        grouped = grouped.limit(limit ? limit!(limit) : MAXIMUM)
         measure.apply(grouped).transform_keys { |value| value.nil? ? Dimension::NONE : value }
       end
     end
@@ -64,7 +68,7 @@ module Janela
 
     def limit!(value)
       limit = Integer(value, exception: false)
-      raise BadRequest, "limit must be a whole number from 1 to 1000, got #{value.inspect}" unless limit&.between?(1, 1000)
+      raise BadRequest, "limit must be a whole number from 1 to #{MAXIMUM}, got #{value.inspect}" unless limit&.between?(1, MAXIMUM)
       limit
     end
 
@@ -82,6 +86,8 @@ module Janela
 
         search = relation.ransack(params)
         reject_dropped_filters!(search, params)
+        reject_disallowed_predicates!(search)
+        reject_oversized_filters!(search)
         search.result
       end
 
@@ -95,5 +101,35 @@ module Janela
         raise BadRequest, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
                      "Declare a janela dimension, or add it to ransackable_attributes."
       end
+
+      # An allowed attribute still reaches every predicate Ransack knows,
+      # including _matches, an arbitrary LIKE pattern (ADR 025). A dashboard
+      # asks in only the predicates its kind of dimension needs.
+      def reject_disallowed_predicates!(search)
+        by_ransack_name = dimensions.values.index_by(&:ransack_name)
+
+        search.conditions.each do |condition|
+          condition.attributes.each do |attribute|
+            dimension = by_ransack_name.fetch(attribute.name)
+            next if dimension.allowed_predicates.include?(condition.predicate_name)
+
+            allowed = dimension.allowed_predicates.map { |predicate| "#{attribute.name}_#{predicate}" }
+            raise BadRequest, "#{model} does not allow #{attribute.name}_#{condition.predicate_name}. " \
+                         "This dimension allows #{allowed.join(', ')}."
+          end
+        end
+      end
+
+      # A click writes _in (ADR 024), which takes an array Ransack does not
+      # otherwise bound. 5001 values answered rather than being refused.
+      def reject_oversized_filters!(search)
+        search.conditions.each do |condition|
+          next unless condition.predicate.wants_array
+          next if condition.values.size <= MAXIMUM
+
+          raise BadRequest, "#{model} does not allow a filter to carry more than #{MAXIMUM} values, " \
+                       "got #{condition.values.size} for #{condition.attributes.map(&:name).join(', ')}."
+        end
+      end
   end
 end

data/lib/janela/dimension.rb

@@ -2,6 +2,14 @@ module Janela
   class Dimension
     GRANULARITIES = %w[hour day week month quarter year].freeze
 
+    # What a click produces (ADR 024), plus not_null: excluding the null
+    # group is documented, tested behaviour ADR 025 did not measure and would
+    # otherwise silently break.
+    CATEGORICAL_PREDICATES = %w[eq in null not_null].freeze
+
+    # A time dimension additionally narrows a range (ADR 006).
+    TIME_PREDICATES = (CATEGORICAL_PREDICATES + %w[gteq gt lteq lt]).freeze
+
     # A group of rows whose dimension is null. Labelled rather than blank, and
     # filtered with Ransack's null predicate rather than an empty string.
     NONE = "(none)".freeze
@@ -41,6 +49,11 @@ module Janela
       !granularity.nil?
     end
 
+    # Which Ransack predicates a filter on this dimension may use (ADR 025).
+    def allowed_predicates
+      time? ? TIME_PREDICATES : CATEGORICAL_PREDICATES
+    end
+
     def attribute
       klass.arel_table[column]
     end

data/lib/janela/doctor.rb

@@ -11,7 +11,7 @@ module Janela
     # silences a check by that name (ADR 021).
     CHECKS = %i[stale_identifiers unmounted_engine unmigrated_tables unregistered_controllers
                 through_dimensions_without_an_allowlist frames_nobody_will_own
-                unauthenticated_endpoints].freeze
+                unauthenticated_endpoints hardcoded_disallowed_predicates].freeze
 
     # Identifiers a previous version of Janela used, and what replaced them.
     RENAMED = {
@@ -153,6 +153,34 @@ module Janela
         end
       end
 
+      # A filter read from a URL param is runtime state the doctor cannot see,
+      # but one written into the host's own Ruby is source like any other
+      # identifier this doctor already greps for (ADR 015, ADR 021, ADR 025).
+      def hardcoded_disallowed_predicates
+        janela_models.flat_map do |model|
+          model.janela.dimensions.values.flat_map { |dimension| disallowed_uses(model, dimension) }
+        end
+      end
+
+      def disallowed_uses(model, dimension)
+        pattern = /\b#{Regexp.escape(dimension.ransack_name)}(_\w+)/
+        source_files.flat_map do |file|
+          content = file.read
+          content.scan(pattern).flatten.uniq.filter_map do |candidate|
+            predicate = Ransack::Predicate.detect_from_string(candidate.dup)
+            next unless predicate
+            next if dimension.allowed_predicates.include?(predicate)
+
+            key = "#{dimension.ransack_name}_#{predicate}"
+            allowed = dimension.allowed_predicates.map { |p| "#{dimension.ransack_name}_#{p}" }
+            Finding.new(severity: :error,
+              summary: "#{model} does not allow #{key}",
+              detail: "  #{file.relative_path_from(@root)} filters #{model} on #{key}, which Janela now " \
+                      "refuses (ADR 025). Allowed here: #{allowed.join(', ')}.")
+          end
+        end
+      end
+
       # A host whose policy filters frames by owner, but which never tells
       # Janela what owns a new one, creates frames its own scope then hides.
       # The failure is silent, and a typo in the method name looks the same as

data/lib/janela/host_routes.rb

@@ -25,6 +25,12 @@ module Janela
     end
 
     def self.forwarded(host: Rails.application.routes, engine: Janela::Engine.routes)
+      # Route loading is lazy, so a call before anything else has drawn the
+      # host's routes would otherwise see an empty set rather than an error
+      # (issue #37). This does not recurse: define! runs from
+      # after_routes_loaded, by which point the reloader has already marked
+      # itself loaded.
+      Rails.application.reload_routes_unless_loaded
       host.named_routes.helper_names - engine.named_routes.helper_names
     end
   end

data/lib/janela/version.rb

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

data/lib/janela.rb

@@ -66,4 +66,19 @@ module Janela
 
     class_name.constantize.janela
   end
+
+  # What Janela can draw, so a gallery asks rather than reaching into
+  # Janela::Query::RENDERERS, Janela::Dimension::GRANULARITIES or
+  # Janela::Pane::OFFERED_LIMITS itself (ADR 027, #39).
+  def self.renderers
+    Query::RENDERERS
+  end
+
+  def self.granularities
+    Dimension::GRANULARITIES
+  end
+
+  def self.offered_limits
+    Pane::OFFERED_LIMITS
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -160,6 +160,10 @@ files:
 - 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/025-janela-bounds-what-a-filter-can-ask-for.md
+- docs/decisions/026-a-renderer-is-the-seam-and-html-comes-first.md
+- docs/decisions/027-the-gallery-is-a-host-page.md
+- docs/decisions/028-the-predicate-list-adr-025-named.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
@@ -183,14 +187,17 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  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.
+  Janela 0.5.0 bounds what a filter predicate can ask for (ADR 025). Most
+  applications need do nothing: a click already writes eq or in, both still
+  allowed. You need to act only if you pass a filter yourself using _cont,
+  _matches, _start, _end or another predicate outside a dimension's
+  allowlist, which now raises Janela::BadRequest instead of being quietly
+  answered.
 
   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