janela 0.1.0

data/app/models/janela/visual.rb

@@ -0,0 +1,65 @@
+module Janela
+  # One measure grouped by one dimension, rendered as a table or a chart. A
+  # visual ignores filters on its own dimension: clicking a value in a visual
+  # should re-scope the others, not collapse itself to the value clicked.
+  class Visual
+    RENDERERS = %w[table bar].freeze
+
+    attr_reader :definition, :measure, :dimension, :renderer, :filters
+
+    # The helper renders the frame and the controller renders its replacement,
+    # so both derive the id the same way from the same parameters.
+    def self.frame_id(model:, measure:, by:, as: :table)
+      "janela_#{model.to_s.underscore}_#{measure}_by_#{by}_#{as}"
+    end
+
+    def initialize(definition:, measure:, dimension:, renderer: "table", filters: {})
+      @definition = definition
+      @measure = measure
+      @dimension = dimension
+      @renderer = renderer.to_s
+      @filters = filters
+
+      raise Error, "unknown visual renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
+    end
+
+    def model
+      definition.model
+    end
+
+    def chart?
+      renderer != "table"
+    end
+
+    def frame_id
+      self.class.frame_id(model: model.name, measure: measure, by: dimension, as: renderer)
+    end
+
+    def title
+      "#{measure.to_s.humanize} by #{dimension.to_s.humanize}"
+    end
+
+    def result(on: nil)
+      definition.query(measure, by: dimension, where: applicable_filters, on: on)
+    end
+
+    def filter_key
+      "#{ransack_name}_eq"
+    end
+
+    # The filter on this visual's own dimension is not applied to its query,
+    # but it is what the user clicked here, so the view highlights it.
+    def selected_value
+      filters[filter_key] || filters[filter_key.to_sym]
+    end
+
+    private
+      def ransack_name
+        definition.dimension!(dimension).ransack_name
+      end
+
+      def applicable_filters
+        filters.reject { |key, _| key.to_s.start_with?(ransack_name) }
+      end
+  end
+end

data/app/views/janela/visuals/show.html.erb

@@ -0,0 +1,36 @@
+<%= turbo_frame_tag @visual.frame_id do %>
+  <% if @result.empty? %>
+    <p class="janela-visual janela-empty"><%= @visual.title %>: no data</p>
+  <% elsif @visual.chart? %>
+    <canvas class="janela-visual janela-chart"
+            data-controller="janela--chart"
+            data-action="janela--chart:toggle->janela--dashboard#toggle"
+            data-janela--chart-type-value="<%= @visual.renderer %>"
+            data-janela--chart-title-value="<%= @visual.title %>"
+            data-janela--chart-key-value="<%= @visual.filter_key %>"
+            data-janela--chart-selected-value="<%= @visual.selected_value %>"
+            data-janela--chart-labels-value="<%= @result.keys.to_json %>"
+            data-janela--chart-values-value="<%= @result.values.map(&:to_f).to_json %>"
+            role="img" aria-label="<%= @visual.title %>"></canvas>
+  <% else %>
+    <table class="janela-visual">
+      <caption><%= @visual.title %></caption>
+      <tbody>
+        <% @result.each do |value, measured| %>
+          <tr>
+            <td>
+              <button type="button"
+                      aria-pressed="<%= value.to_s == @visual.selected_value.to_s && @visual.selected_value.present? %>"
+                      data-action="janela--dashboard#toggle"
+                      data-janela--dashboard-key-param="<%= @visual.filter_key %>"
+                      data-janela--dashboard-value-param="<%= value %>">
+                <%= value %>
+              </button>
+            </td>
+            <td><%= number_with_delimiter(measured) %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+<% end %>

data/config/importmap.rb

@@ -0,0 +1,5 @@
+pin "janela/dashboard_controller", to: "janela/dashboard_controller.js"
+pin "janela/chart_controller", to: "janela/chart_controller.js"
+
+# Hosts that already pin their own Chart.js keep it.
+pin "chart.js", to: "janela/vendor/chart.js" unless packages.key?("chart.js")

data/config/routes.rb

@@ -0,0 +1,3 @@
+Janela::Engine.routes.draw do
+  resource :visual, only: :show
+end

data/docs/decisions/001-built-to-be-forked.md

@@ -0,0 +1,73 @@
+---
+Date: 2026-09-11
+Status: Accepted
+Triggers:
+  - adding a feature or configuration option to Janela
+  - a design decision that touches a specific host application's domain or business logic
+  - reviewing a contribution (human or agent-authored)
+  - deciding how much flexibility/configurability a new API surface should expose
+Topics: vision, scope, forkability, open-source, host-decoupling
+---
+
+# ADR 001: Built to Be Forked
+
+## Context
+
+Janela is a standalone open-source Rails gem: business-intelligence-
+style dashboards and cross-filtering on ActiveRecord models. It is
+being built and open-sourced deliberately, with the aspiration of
+presenting it to the wider Rails community.
+
+Commercial BI dashboard tools' actual surface area is mostly enterprise
+packaging. The load-bearing 5%, declarative measures and dimensions
+over a data model plus cross-filtering, is the real gap in the Rails BI
+ecosystem. Every other feature a BI tool "should" have (drag-drop
+designer, NL query, RLS subsystem, embedding SDK, etc.) is either
+bloat or something Rails/Pundit/ActiveJob already own better.
+
+Separately, DHH's framing in his September 2026 Lex Fridman interview
+(#501, "Future of Programming, AI, Agentic Engineering, Vibe Coding &
+Linux", https://lexfridman.com/dhh-2-transcript/) gave language to an
+approach already implicit in the scope decision: agents make it
+economically viable for a consumer to fork a small tool and keep only
+the 5% they need, rather than adopt a large configurable one wholesale.
+He also argued that overly prescriptive project instructions actively
+damage agent output. Describe the problem, not the solution.
+
+## Decision
+
+Janela is designed to be forked, not just configured.
+
+1. **Ship only the load-bearing 5%.** Measures/dimensions as a thin
+   Ruby DSL over Ransack (not a new query language), cross-filtering
+   via a Stimulus controller + Turbo Frames (not a JS framework).
+   Everything else stays out of scope.
+2. **Prefer one obvious way to do a thing over configurable
+   flexibility.** Every added config flag is a fork someone didn't
+   need to make. Default to fewer knobs, not more.
+3. **Stay fully decoupled from any host application.** No
+   application-specific code, model names, table shapes, or business
+   logic in this repo, ever. Host applications depend on Janela;
+   Janela never depends on a host application.
+4. **Document decisions as ADRs in this repo**, so a forker
+   understands *why* a piece exists before they rip it out or
+   replace it, not just what it does.
+5. **Treat agent-authored contributions the same as human ones.**
+   Reviewed on the merits of the diff, not the source.
+6. **Keep project instructions (CLAUDE.md) minimal and intent-focused**
+   rather than prescriptive, consistent with the reasoning above.
+
+## Consequences
+
+- Feature requests that only make sense as a config flag for one
+  user's edge case should default to "fork it" rather than "add a
+  flag." This will read as less accommodating than a typical OSS
+  project and is intentional.
+- The codebase must stay small and legible enough that forking a
+  chunk is realistic. This is a constant pressure against adding
+  abstractions, even useful-seeming ones.
+- Any specific host application's needs get solved in that
+  application's own codebase against Janela's public API, never by
+  special-casing Janela itself.
+- Future scope decisions (what's in the 5%, what isn't) should cite
+  this ADR rather than re-litigate the philosophy each time.

data/docs/decisions/002-measures-and-dimensions-over-ransack.md

@@ -0,0 +1,125 @@
+---
+Date: 2026-09-13
+Status: Accepted
+Related: ADR 001
+Triggers:
+  - adding or changing the measures/dimensions DSL
+  - deciding how a dashboard filter reaches the query layer
+  - adding a dependency to the query path
+  - wiring authorisation around a dashboard query
+  - adding time-granularity or drill-down dimensions
+Topics: dsl, query-layer, ransack, dependencies, authorisation
+---
+
+# ADR 002: Measures and Dimensions over Ransack
+
+## Context
+
+ADR 001 committed to shipping the load-bearing core: declarative
+measures/dimensions, and cross-filtering. This ADR covers the first
+half, spiked against real ActiveRecord models in `test/dummy`.
+
+Two questions had to be answered by building rather than arguing.
+
+**What sits under the DSL?** The spike first hid Ransack behind
+Janela's own filter vocabulary (`where: { region: "EU" }`), translating
+dimension names into Ransack predicates. That worked, but the
+familiarity a Rails developer gets from Ransack was spent entirely
+inside Janela. The host still inherited Ransack's constraints while
+touching none of its API. Plain ActiveRecord was the obvious
+alternative, since every Janela filter is only ever "dimension in
+values".
+
+**How does authorisation get in?** ADR 001 already put a
+row-level-security subsystem out of scope. The open question was
+whether to depend on Pundit directly.
+
+A survey of the filtering ecosystem informed the first question.
+Ransack has roughly 115M downloads against 1.9M for the next
+most-used option, so it is the only filter gem that a Rails developer
+can be assumed to already know. Notably, none of the filter gems do
+aggregation. The `GROUP BY` half of Janela is Janela's own code
+regardless of what sits underneath the filter half.
+
+## Decision
+
+**The DSL is a `janela` block on the model.**
+
+```ruby
+class Order < ApplicationRecord
+  belongs_to :customer
+
+  janela do
+    measure :revenue, sum: :amount
+    measure :orders, count: true
+    dimension :status
+    dimension :region, through: :customer
+  end
+end
+```
+
+A measure takes exactly one aggregate of `sum`, `count`, `average`,
+`minimum`, `maximum`. A dimension is a column on the model, or a
+column on an association via `through:`.
+
+**Filters are Ransack params, passed through rather than translated.**
+
+```ruby
+Order.janela.query(:revenue, by: :status, where: { customer_region_in: %w[APAC EU] })
+```
+
+The host can hand `params[:q]` from a standard `search_form_for`
+slicer straight to Janela with no translation layer, and the
+cross-filter controller emits predicate names every Rails developer
+already reads fluently. Ransack is a runtime dependency.
+
+**Dimensions define the Ransack allowlist.** Declaring a dimension is
+declaring that the attribute is filterable, so Janela generates
+`ransackable_attributes` and `ransackable_associations` on the model.
+A model that already declares its own keeps it.
+
+**A dropped filter raises.** Ransack silently discards conditions its
+allowlist does not permit. For a BI tool that means quietly returning
+unfiltered numbers that look filtered, so Janela verifies every
+supplied filter was applied and raises `Janela::Error` otherwise.
+
+**Authorisation is a hook, not a dependency.** `query` accepts `on:`,
+any relation, defaulting to `model.all`:
+
+```ruby
+Order.janela.query(:revenue, on: policy_scope(Order))
+```
+
+Pundit users recognise that line; CanCanCan users pass
+`Order.accessible_by(current_ability)`. Janela does not depend on
+either.
+
+## Consequences
+
+- Janela's public filter API is coupled to Ransack's predicate naming.
+  Replacing the filter engine later is a breaking change. Accepted
+  deliberately: ADR 001 prefers one obvious way, and Ransack is the
+  obvious Rails way to filter.
+- **A `through:` dimension requires the associated model to allowlist
+  the attribute itself.** Ransack's allowlist is per-class, so Janela
+  can only own the allowlist of the model the dimensions are declared
+  on. Associated models need both `ransackable_attributes` and
+  `ransackable_associations` defined or Ransack raises. This must be
+  documented prominently; it is the most likely source of confusion
+  for a first-time user.
+- Filtering and grouping on the same association produces a redundant
+  aliased join, because Ransack builds its own join regardless of one
+  already being present. Results are correct; the cost will compound
+  as dashboards add through-dimensions. Revisit if it shows up in real
+  query plans, not before.
+- Aggregation stays Janela's own code. No filter gem offers it, so
+  nothing in this decision reduces the surface area Janela maintains
+  for measures.
+- Time-granularity dimensions (`granularity: :day`) are not built.
+  When they are, Groupdate is the conventional answer and should be
+  evaluated then. Time-zone-correct bucketing is genuinely fiddly,
+  and worth a dependency in a way filtering was not.
+- Active Search, the search framework 37signals is introducing at
+  Rails World 2026, is text search across swappable engines and does
+  not overlap this decision. Worth revisiting only if it ships facet
+  counts, which are adjacent to slicer counts.

data/docs/decisions/003-cross-filtering-with-turbo-frames.md

@@ -0,0 +1,104 @@
+---
+Date: 2026-09-13
+Status: Accepted
+Related: ADR 001, ADR 002
+Triggers:
+  - changing how filter state is shared between visuals
+  - adding a visual type, or changing what a visual renders
+  - exposing a model or query over HTTP
+  - adding authentication or authorisation to dashboards
+  - deciding whether a behaviour needs a browser test
+Topics: cross-filtering, stimulus, turbo, security, authorisation, testing
+---
+
+# ADR 003: Cross-filtering with Turbo Frames
+
+## Context
+
+Cross-filtering is the reason Janela exists. No gem in the Rails
+ecosystem lets clicking a value in one visual re-scope every other
+visual on the page, and ADR 001 named it one of the two things worth
+building.
+
+The obvious implementations all pull in machinery Janela does not
+want: a JS framework holding client state, Turbo Streams broadcasting
+updates, or a WebSocket. Each would contradict the first principle of
+no JS framework and no build step.
+
+Exposing visuals over HTTP also raises a question the DSL did not.
+A visual is identified by a model, a measure and a dimension, and
+those arrive as request parameters, so something has to stop a
+parameter naming an arbitrary class.
+
+## Decision
+
+**A visual is a Turbo Frame whose `src` carries the filters.** Turbo
+reloads a frame whenever its `src` attribute changes, so a Stimulus
+controller holding shared filter state only has to rewrite each
+frame's `src`:
+
+```js
+filtersValueChanged() {
+  this.visualTargets.forEach((visual) => {
+    const url = new URL(visual.dataset.janelaSrc, window.location.origin)
+    for (const [key, value] of Object.entries(this.filtersValue)) {
+      url.searchParams.set(`q[${key}]`, value)
+    }
+    if (visual.src !== url.href) visual.src = url.href
+  })
+}
+```
+
+No streams, no sockets, no state library. Filters are Ransack params
+per ADR 002, so they stay readable and shareable in the URL. Clicking
+a value already applied removes it.
+
+**A visual ignores filters on its own dimension.** Otherwise clicking
+"paid" in a revenue-by-status visual collapses that visual to the
+single bar that was clicked. The rule is per-dimension rather than
+per-visual: a visual grouped by region ignores region filters even
+when a different visual originated them, so region totals stay
+comparable. This is one line in `Janela::Visual` and needs no
+tracking of which visual a filter came from.
+
+**Only models that declare a `janela` block are addressable.**
+Declaring the block registers the model's name, and the registry is
+a strict allowlist, so a request parameter can never constantize an
+arbitrary class. Names are stored rather than class objects so a
+reloaded model leaves nothing stale behind. A lookup that misses in
+development calls `eager_load!` rather than constantizing the
+parameter to find out whether it is valid.
+
+**Authorisation needs no configuration.** `Janela::ApplicationController`
+inherits from `Janela.parent_controller` (the host's
+`ApplicationController` by default), so the host's authentication
+filters already apply. Scoping calls `policy_scope` when the host
+defined it and falls back to `model.all`, which means Pundit users
+get authorisation automatically without Janela depending on Pundit.
+
+**Cross-filtering gets a browser test.** Request tests cannot prove
+that clicking re-renders other frames, and that behaviour is the
+product. `test/system/cross_filtering_test.rb` drives real Chrome;
+CI runs it as a separate job so the unit matrix stays fast.
+
+## Consequences
+
+- Each filter change refetches every visual, one request per frame.
+  Fine at the scale a dashboard page renders; a page with many
+  visuals will want debouncing or a combined endpoint later. Do not
+  optimise before a real dashboard shows the problem.
+- Filter state lives in frame `src` attributes, not in the page URL,
+  so the browser back button does not step through filter changes and
+  a filtered dashboard cannot yet be shared as a link. Promoting
+  filter state to the page URL is the obvious next step and was left
+  out deliberately.
+- The host registers the Stimulus controller explicitly
+  (`application.register("janela--dashboard", JanelaDashboardController)`).
+  One documented line, rather than Janela reaching into the host's
+  Stimulus instance.
+- Visuals render as tables. Charts wrap an existing library off the
+  same server-supplied values and change nothing about the mechanism.
+- `turbo-rails` and `stimulus-rails` become runtime dependencies,
+  which is what "built on Ruby and Stimulus" already implied.
+- CI now needs Chrome for one job. Accepted because the alternative
+  is that the product's central claim is only ever verified by hand.

data/docs/decisions/004-charts-and-javascript-delivery.md

@@ -0,0 +1,135 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 003
+Triggers:
+  - changing how Janela's JavaScript reaches a host application
+  - adding or changing a chart type or the chart controller
+  - adding a JavaScript dependency
+  - a host reporting that no Janela controller connects
+  - securing or authenticating dashboard endpoints
+Topics: javascript, npm, importmap, jsbundling, charts, chart.js, authorisation, packaging
+---
+
+# ADR 004: Charts and JavaScript Delivery
+
+## Context
+
+ADR 003 delivered Janela's Stimulus controller through the engine's
+`config/importmap.rb`. Installing the gem into a real host application
+for the v0.1.0 alpha showed that this reaches only importmap hosts. A
+host that bundles JavaScript with esbuild, bun or webpack (jsbundling)
+has no importmap, so the engine's pin is silently skipped and none of
+Janela's JavaScript loads. The Turbo Frames still render, so the
+failure is quiet: everything looks right and nothing cross-filters.
+
+The alpha also required charts. Two questions had to be settled at
+once: how a chart library reaches both kinds of host, and how a click
+on a chart element becomes the same filter toggle a table button
+already emits.
+
+A third finding came from the same install. `Janela::ApplicationController`
+inherits from the host's `ApplicationController`, which is only as
+authenticated as the host makes it. In a host that authenticates per
+controller, Janela's endpoints were public, and a host filter that
+redirected to the sign-in page resolved its route against the engine's
+route set rather than the host's.
+
+## Decision
+
+**Janela ships as a gem and an npm package, from the same repository.**
+The gem carries the engine; a root `package.json` exposes the same
+Stimulus controllers as `@retail-tasker/janela` with `exports` for
+`./dashboard_controller` and `./chart_controller`. Both halves install
+from GitHub with no registry publish:
+
+```ruby
+gem "janela", github: "retail-tasker/janela"
+```
+
+```bash
+yarn add github:retail-tasker/janela
+```
+
+The package name is scoped because `janela` is already taken on npm,
+and because that is the convention Rails-adjacent packages follow
+(`@hotwired/turbo-rails`, `@rails/actiontext`). The engine's importmap
+pins stay for importmap hosts and for `test/dummy`.
+
+**Charts are Chart.js, driven by one Stimulus controller.** The
+`janela--chart` controller builds a chart on `connect` from data
+attributes the view already renders (`labels`, `values`, the filter
+key, the selected value) and destroys it on `disconnect`, which is
+what makes a chart survive Turbo replacing its frame on every
+cross-filter. `Chart.register(...registerables)` is called explicitly:
+importing `{ Chart }` alone yields a Chart with no controllers and
+`"bar" is not a registered controller` at runtime.
+
+Chart.js reaches each host the way its other JavaScript does. Bundler
+hosts declare it as a peer dependency and resolve it from their own
+`node_modules`. Importmap hosts get a vendored, self-contained ESM
+bundle at `app/assets/javascripts/janela/vendor/chart.js`, pinned as
+`chart.js` unless the host already pins its own. The vendored file is
+self-contained on purpose: Chart.js's own `dist/chart.js` imports a
+`./chunks/` sibling that Propshaft digesting breaks, and the UMD
+build sets a global instead of exporting.
+
+**A chart click is a table click.** The chart controller's `onClick`
+maps the hit element's index to its label and dispatches
+`janela--chart:toggle` with `{ key, value }` in `detail`. The dashboard
+controller's `toggle` reads `{ ...event.detail, ...event.params }`, so
+a table button (params) and a chart (detail) arrive identically and the
+dashboard cannot tell them apart.
+
+**Renderer is a helper option and part of the frame identity.**
+`janela_visual Order, :revenue, by: :status, as: :bar`. The renderer is
+whitelisted (`table`, `bar`) and included in the frame id, so a table
+and a chart of the same measure can share a page.
+
+**Selection state is rendered by the server.** The filter on a
+visual's own dimension is not applied to its query, but it is what the
+user clicked, so the view marks it: `aria-pressed` on the table button,
+a solid bar against faded siblings on the chart. Because the frame
+reloads on every filter change, server-rendered state needs no
+re-application in JavaScript.
+
+**Securing endpoints is a documented host pattern, not a knob.**
+
+```ruby
+Rails.application.config.to_prepare do
+  Janela::ApplicationController.prepend_before_action do
+    redirect_to main_app.new_session_path unless user_signed_in?
+  end
+end
+```
+
+Prepended, so it runs before filters on the host's `ApplicationController`
+that assume a user (tenant lookup was the one that raised). Through
+`main_app`, because inside an isolated engine a bare host route helper
+resolves against the engine's routes. Blazer documents the same
+`main_app` requirement.
+
+## Consequences
+
+- The npm package's `files` glob excludes `vendor/`, so registry or
+  `github:` installs do not ship the vendored Chart.js. yarn 1's
+  `file:` protocol copies the whole directory regardless; harmless,
+  only relevant during local development against a sibling checkout.
+- An importmap host with its own `chart.js` pin keeps it. The check is
+  `packages.key?("chart.js")` in the engine's `config/importmap.rb` and
+  depends on the host's importmap being evaluated first, which is the
+  order importmap-rails uses.
+- Bar is the only chart type. Adding another is a new value in
+  `Visual::RENDERERS` and a `type` the controller passes through;
+  nothing about delivery or the click contract changes.
+- Propshaft in development rescans assets only when the Rails
+  reloader fires, so a JavaScript-only change in an engine can appear
+  stale until a Ruby or view file changes or the server restarts.
+  Stale `public/assets` from an earlier `assets:precompile` shadows
+  `app/assets/builds` entirely. Both are host development gotchas
+  worth knowing when a controller "does not connect".
+- A host whose sign-in route is not `new_session_path` adapts the one
+  line. If the pattern proves awkward across hosts, the Blazer-style
+  `Janela.before_action = :method_name` configuration is the fallback.
+- CanCanCan hosts still get `model.all` silently (ADR 002). Unchanged
+  here and tracked as a pre-public issue.

data/docs/decisions/INDEX.md

@@ -0,0 +1,44 @@
+# ADR Index
+
+Topic-tagged map of all ADRs. Read this **before any non-trivial task**
+to find which decisions are already made.
+
+Every ADR carries `Triggers:` and `Topics:` near the top. Grep for
+them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
+
+## How to use
+
+1. Identify the area of the task (scope, DSL, cross-filtering, etc).
+2. Look up the topic below to see which ADRs are relevant.
+3. Read the relevant ADRs **before** writing code, advising, or making
+   a decision in that area.
+4. If the task spans topics, read all relevant ADRs.
+5. If no ADR covers the area but the decision is significant, draft a
+   new one.
+
+## Topics
+
+| Topic | ADRs |
+|-------|------|
+| **Vision, scope, forkability** | 001 |
+| **Open-source & host-decoupling** | 001 |
+| **DSL & query layer** | 002 |
+| **Dependencies** | 002, 003, 004 |
+| **Authorisation** | 002, 003, 004 |
+| **Cross-filtering & Hotwire** | 003, 004 |
+| **JavaScript delivery & charts** | 004 |
+| **Security** | 003 |
+| **Testing** | 003 |
+
+## Chronological
+
+| ADR | Title | Date | Status |
+|-----|-------|------|--------|
+| 001 | Built to Be Forked | 2026-09-11 | Accepted |
+| 002 | Measures and Dimensions over Ransack | 2026-09-13 | Accepted |
+| 003 | Cross-filtering with Turbo Frames | 2026-09-13 | Accepted |
+| 004 | Charts and JavaScript Delivery | 2026-09-15 | Accepted |
+
+## Next number
+
+Next ADR: 005

data/lib/janela/definition.rb

@@ -0,0 +1,70 @@
+module Janela
+  class Definition
+    attr_reader :model, :measures, :dimensions
+
+    def initialize(model)
+      @model = model
+      @measures = {}
+      @dimensions = {}
+    end
+
+    def measure(name, **aggregate)
+      measures[name] = Measure.build(name, **aggregate)
+    end
+
+    def dimension(name, through: nil)
+      dimensions[name] = Dimension.new(name, model: model, through: through)
+    end
+
+    # Filters are Ransack params, so a host can pass params[:q] straight
+    # through from a search_form_for slicer. Scope with on: to respect the
+    # host's authorisation, e.g. on: policy_scope(Order).
+    def query(measure_name, by: nil, where: {}, on: nil)
+      relation = filter(on || model.all, where)
+
+      if by
+        dimension = dimension!(by)
+        relation = relation.left_joins(dimension.through) if dimension.through
+        relation = relation.group(dimension.attribute)
+      end
+
+      measure!(measure_name).apply(relation)
+    end
+
+    def dimension!(name)
+      dimensions.fetch(name) { raise Error, "#{model} has no janela dimension #{name.inspect}" }
+    end
+
+    def ransackable_attributes
+      dimensions.values.reject(&:through).map { |dimension| dimension.name.to_s }
+    end
+
+    def ransackable_associations
+      dimensions.values.filter_map(&:through).map(&:to_s).uniq
+    end
+
+    private
+      def filter(relation, params)
+        return relation if params.empty?
+
+        search = relation.ransack(params)
+        reject_dropped_filters!(search, params)
+        search.result
+      end
+
+      # Ransack silently discards conditions an allowlist does not permit,
+      # which would quietly return unfiltered numbers.
+      def reject_dropped_filters!(search, params)
+        applied = search.conditions.flat_map { |condition| condition.attributes.map(&:name) }
+        dropped = params.keys.reject { |key| applied.any? { |name| key.to_s.start_with?(name) } }
+        return if dropped.empty?
+
+        raise Error, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
+                     "Declare a janela dimension, or add it to ransackable_attributes."
+      end
+
+      def measure!(name)
+        measures.fetch(name) { raise Error, "#{model} has no janela measure #{name.inspect}" }
+      end
+  end
+end