janela 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86e2bcbf47fdcf475b8e34b2b1897d308a6c9f478e7b3f0903979cd3fa6bb8e2
-  data.tar.gz: 9116c50f2f6e92a69489827acf9e9d580954c21bbe068887c3605b96d0531019
+  metadata.gz: 507d6baa4984a11605225ee2f97d8795f606e1d1b4739bb7d63567702d6a76c5
+  data.tar.gz: b12856e553a97feed8c12c56f78774addd360a603b8fc56cb81b01ee6167fe34
 SHA512:
-  metadata.gz: a132498d5553317cd888139ba00559b5c7844c3878bdfe4c0c595783e14e3e4a082ec6fbe0a844d9f07a985a586daf4a4104164ff9dd452ed8ddf4390bdfe630
-  data.tar.gz: 5f35f6d28fe84c469e3502f97f8c0ec13b7e1c703f04c5aa21360ef7ad6e14b4cc9c8e8d174e5ac1af9207adcc221d3ed430e2851059ef41f08eb5833637712b
+  metadata.gz: 65c9dd8f4ea0efc927fe648e52bd519ef7485d9cfda48bc200f4371cc33d8c844d5a496b9de9af7396b256306b5549614fe3235a1742774c118fc26b3b3e6eac
+  data.tar.gz: 70cac5044f03d17ebf4bd56f5407005815c5945f0979b869d93116d26b4c97d636dd53b18f973d1917efe54ce040d66014bd6e717d9135d66caea1d0a094389c

data/CHANGELOG.md

@@ -5,7 +5,43 @@ 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).
 
-## [Unreleased]
+## [0.3.0] - 2026-09-16
+
+### Added
+
+- `docs/multi-tenancy.md`, shipped in the gem: what goes through the host's scope and what does not, worked wiring for Pundit, acts_as_tenant and CanCanCan, what owns a frame an analyst creates, how to prove it with a test, and the honest note that a snapshot has no owner column yet (#32).
+- A measure declares how its number reads: `precision:`, `prefix:` and `suffix:`, applied the same way to a table cell, a single value and a chart tooltip. Precision defaults to what the schema already says, so counting rows is whole, a `decimal(10, 2)` column reads to the cent and only an average of an integer falls back to two places. Formatting is rendering, never rounding: a snapshot stores the number and reads back under whatever format is declared later (ADR 020, #25).
+- A pane whose row asks for a chart renders as its table where no chart runtime exists, which is the engine's own pages; a host's page still draws the chart. `janela_frame(@frame, charts: false)` asks for it explicitly (ADR 018).
+- The engine's layout loads Janela's own stylesheet, so its pages are styled on install. It still loads none of the host's assets.
+- The analyst's editing surface: conventional Rails CRUD on frames and on panes nested under a frame, on Janela's own pages, working with nothing but HTML. Adding a pane is two steps, the first picking a model and the second offering only the measures and dimensions that model declares, because those pages run no JavaScript to refill one select from another. A pane moves with Up and Down buttons rather than a position field, and positions stay contiguous. Every action reads through the host's scope, so another tenant's frame is a 404 to change as well as to read (ADR 012, ADR 014).
+- `janela_frame_owner`, a hook a host defines on its own `ApplicationController`. Janela assigns its return value as the owner of a frame it creates, so a host whose `policy_scope` filters frames by owner does not have the analyst's new dashboard hidden the instant it is saved. A host with no tenancy defines nothing and gets a nil owner. Duck typed, like `policy_scope` itself.
+- Janela serves its own pages: an index of frames and a page per frame, at the mount root (`/dashboards`, `/dashboards/3`). Both read through the host's `policy_scope`, the noun in every heading comes from `Janela::Frame.model_name.human` so a host renames it in its own locale file, and the gem ships `config/locales/en.yml` with the English defaults. A host that wants a different index writes its own page over `Janela::Frame` and never routes to ours (ADR 013).
+- A dashboard can be data. `Janela::Frame` holds a name and a grid (`columns` 1 to 12, `gap` 0 to 8), `Janela::Pane` holds one visual (`position`, `span` 1 to 12, model, measure, dimension, renderer, granularity, limit and an optional title of its own), and `janela_frame @frame` renders one. The block form is unchanged, so nothing already built has to move (ADR 012, ADR 014). Run `bin/rails janela:install:migrations && bin/rails db:migrate` for the two new tables.
+- A pane row is rendered by its own nested route, `<mount>/:frame_id/panes/:id`, and identified in the DOM as `janela_pane_<id>`, so two rows showing the same measure by the same dimension do not share a turbo frame. The ad hoc pane grammar from ADR 005 is unchanged.
+- A frame renders every pane inline on the first response, so a shared link is a correct dashboard before any JavaScript runs and a page load makes no request per pane. Filters in the page URL apply to every pane either way.
+- A pane row is validated against the registry on save: the model must have a `janela` block, the measure, dimension, renderer and granularity must be declared or supported, a granularity only applies to a time dimension, and a limit is 1 to 1000. A bad row is rejected with a readable message rather than rendering as a missing pane later.
+- `Janela::Frame belongs_to :owner, polymorphic: true, optional: true`. Janela sets nothing there and reads nothing from it; it exists so a multi tenant host's Pundit `Scope` has a column to filter on. Every lookup of a frame or a pane row goes through that scope, so another tenant's frame is a 404 (ADR 014).
+- A stylesheet, `app/assets/stylesheets/janela.css`, which a host includes with `stylesheet_link_tag "janela"`. It defines the grid classes for every value the records allow, styles the existing `janela-pane`, `janela-chart`, `janela-value` and `janela-empty` hooks so a pane is legible on install (#15), and collapses to one column on a narrow screen. Set `--janela-space` to move the whole spacing scale. The engine never injects it into a layout it does not own (ADR 016).
+- `bin/rails janela:doctor` reads a host application and lists what it still needs to do: identifiers from an earlier version, unregistered Stimulus controllers, a `through:` dimension whose associated model has no allowlist, an unmounted engine, a mounted engine whose tables were never migrated, a `policy_scope` that filters frames by owner where the host defines no `janela_frame_owner`, and whether anything authenticates the endpoints. Exits non-zero on an error so it can run in CI (ADR 015). Every finding names the check that produced it, such as `unauthenticated-endpoints`, and a host silences one it has judged a false alarm with `Janela.silenced_checks`. A silenced check is still named in the output every run (ADR 021).
+- `UPGRADING.md`, shipped inside the gem, with the steps for each release that needs a host to act. The changelog says what changed; the upgrade guide says what to do.
+
+### Changed
+
+- Numbers render to the precision the measure means rather than to whatever the database returned. A sum of a `decimal(10, 2)` column that read as `375.0` now reads as `375.00`, and an average that read as `928.8767833333333` now reads as `928.88`. Nothing is rounded before it is stored or compared (ADR 020).
+- Janela's own minimal layout now links the gem's own stylesheet, refining ADR 011. It still loads nothing of the host's, and still no JavaScript, because Turbo and Stimulus come from the host's bundler: Janela's own pages are therefore correct, styled, static dashboards. Panes render inline and filters in the URL apply; nothing cross-filters, and a chart pane draws nothing there. The engine also declares `janela.css` for precompilation, so a host on Sprockets serves it in production.
+- A snapshot is read through the host's scope rather than `Snapshot.find`, so a stored pane a host's policy hides is a 404 rather than a result anyone who guesses an id can read (ADR 014).
+- The frame controller no longer rewrites pane `src` attributes when it connects, only when the filters actually change. A pane rendered inline would otherwise be fetched again immediately and its first render thrown away.
+- A frame or a pane a host's scope cannot see now answers with Janela's own sentence inside the requesting turbo frame, rather than the host's error page. Still a 404.
+- Breaking rename, no behaviour change (ADR 014). A host must act on all of these:
+  - The Stimulus controller `janela--dashboard` is now `janela--frame`, and its file is `frame_controller.js`. Change `application.register("janela--dashboard", ...)` to `application.register("janela--frame", ...)`, and the import path from `@retail-tasker/janela/dashboard_controller` to `@retail-tasker/janela/frame_controller` on npm, or `janela/dashboard_controller` to `janela/frame_controller` on importmap.
+  - Any `data-action="janela--dashboard#clear"` (or `#toggle`), `data-janela--dashboard-*-param` and `data-janela--dashboard-target` in the host's own markup becomes `janela--frame`.
+  - The helper `janela_dashboard do ... end` is now `janela_frame do ... end`. `janela_pane` and `janela_snapshot_pane` are unchanged.
+  - The helper module `Janela::DashboardHelper` is now `Janela::FramesHelper`, which only matters to a host that includes or overrides it.
+  - `Janela::Pane` is now `Janela::Query`, and its `frame_id` is `turbo_frame_id`. `Pane` is reserved for a future record. Frame unqualified now means the dashboard; the DOM element is always spelled turbo frame.
+  - `Janela::PanesController` is now `Janela::QueriesController` and `Janela::SnapshotPanesController` is now `Janela::SnapshotQueriesController`, with their views at `app/views/janela/queries/`. A host that overrides the view moves its copy.
+  - `test/query_test.rb` is now `definition_query_test.rb`, since `query_test` read as a test of `Janela::Query` rather than of `Definition#query`.
+  - Unchanged on purpose: the pane URLs, the route helpers `pane_path` and `snapshot_pane_path`, the turbo frame ids, and the CSS hooks `janela-pane`, `janela-chart`, `janela-value` and `janela-empty`.
+- The README's advice on styling a directly opened pane was wrong: it suggested pointing Janela at the host's application layout, which is the thing that raises `NameError` inside an isolated engine. It now shows a small asset-only layout instead, the pattern a real host arrived at.
 
 ## [0.2.1] - 2026-09-15
 
@@ -62,6 +98,7 @@ 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.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
 [0.2.0]: https://github.com/retail-tasker/janela/releases/tag/v0.2.0
 [0.1.0]: https://github.com/retail-tasker/janela/releases/tag/v0.1.0

data/README.md

@@ -25,7 +25,7 @@ Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has t
 
 ```ruby
 # Gemfile
-gem "janela", "~> 0.2"
+gem "janela", "~> 0.3"
 ```
 
 ```ruby
@@ -43,9 +43,9 @@ yarn add github:retail-tasker/janela   # or: npm install github:retail-tasker/ja
 
 ```js
 // app/javascript/controllers/index.js
-import JanelaDashboardController from "@retail-tasker/janela/dashboard_controller"
+import JanelaFrameController from "@retail-tasker/janela/frame_controller"
 import JanelaChartController from "@retail-tasker/janela/chart_controller"
-application.register("janela--dashboard", JanelaDashboardController)
+application.register("janela--frame", JanelaFrameController)
 application.register("janela--chart", JanelaChartController)
 ```
 
@@ -53,16 +53,22 @@ The chart controller imports `chart.js`, which is a peer dependency: add `chart.
 
 **With importmap-rails:**
 
-Nothing to install. The engine pins `janela/dashboard_controller`, `janela/chart_controller` and a vendored `chart.js` for you (your own `chart.js` pin wins if you have one). Register the controllers:
+Nothing to install. The engine pins `janela/frame_controller`, `janela/chart_controller` and a vendored `chart.js` for you (your own `chart.js` pin wins if you have one). Register the controllers:
 
 ```js
 // app/javascript/application.js
-import JanelaDashboardController from "janela/dashboard_controller"
+import JanelaFrameController from "janela/frame_controller"
 import JanelaChartController from "janela/chart_controller"
-application.register("janela--dashboard", JanelaDashboardController)
+application.register("janela--frame", JanelaFrameController)
 application.register("janela--chart", JanelaChartController)
 ```
 
+Include the stylesheet in whichever layout renders dashboards. It is small, it is the grid, and it is meant to be overridden:
+
+```erb
+<%= stylesheet_link_tag "janela" %>
+```
+
 Requires Rails 8.0+ and Ruby 3.3+. If your app is on Rails 8.1.x with the `json` gem at 3.x, encrypted cookie reads raise inside ActiveSupport and every Turbo Frame request will 500 in the browser; pin `gem "json", "< 3"` until Rails ships the fix.
 
 ## Usage
@@ -86,6 +92,20 @@ end
 
 A dimension with a `granularity` is a time dimension. Groupdate buckets it (`hour`, `day`, `week`, `month`, `quarter`, `year`), fills empty buckets with zero, and uses your app's `Time.zone` and week start. **On SQLite, buckets are UTC**, because SQLite cannot convert time zones: with a non-UTC `Time.zone` a daily bucket is shifted by your offset, and an early-morning row lands in the previous day. Coarser granularities blunt the shift without removing it. If you need local-day buckets on SQLite, store a local date column and use it as a plain dimension.
 
+### How numbers read
+
+A measure says what its own number means, and every renderer asks it, so a table cell, a single value and a chart tooltip cannot disagree (ADR 020):
+
+```ruby
+measure :revenue, sum: :amount, prefix: "$"                      # $1,234.50
+measure :pass_rate, average: :score, precision: 1, suffix: "%"   # 66.7%
+measure :orders, count: true                                     # 1,234
+```
+
+Precision defaults to what the schema already says. Counting rows has no decimal places, a `decimal(10, 2)` column reads to the cent, and summing an integer column stays whole. Declare `precision:` where the schema has nothing to say, such as averaging an integer, or where you want something else. Thousands are delimited with your app's locale.
+
+Formatting is rendering, never rounding. The number itself reaches a snapshot and an order clause at full precision, so a snapshot taken last month reads back under a format you declare today.
+
 Then query them:
 
 ```ruby
@@ -120,11 +140,11 @@ end
 
 ### Dashboards
 
-Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one re-scopes the others:
+Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one re-scopes the others. `janela_frame` wraps them: a frame is Janela's own word for the dashboard, so the gem's vocabulary never dictates what you call one (ADR 014).
 
 ```erb
-<%= janela_dashboard do %>
-  <button type="button" data-action="janela--dashboard#clear">Clear filters</button>
+<%= janela_frame do %>
+  <button type="button" data-action="janela--frame#clear">Clear filters</button>
 
   <%= janela_pane Order, :revenue %>
   <%= janela_pane Order, :revenue, by: :status, as: :bar %>
@@ -135,6 +155,88 @@ Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one r
 
 A pane with no `by:` is the measure's single total, the KPI tile. `limit: 10` keeps the top ten rows or bars. `as:` is `:table` by default, `:bar` for a Chart.js bar chart, or `:line`, which suits a time dimension: `janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week`. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
 
+### Frames
+
+A dashboard does not have to be written in ERB. A frame is a record, so the person who decides which panes a dashboard has and how wide each one is does not need a deploy to change it (ADR 012):
+
+```bash
+bin/rails janela:install:migrations && bin/rails db:migrate
+```
+
+```ruby
+frame = Janela::Frame.create!(name: "Orders", columns: 3, gap: 4)
+frame.panes.create!(model: "orders", measure: "revenue")
+frame.panes.create!(model: "orders", measure: "revenue", dimension: "placed_on",
+                    renderer: "line", granularity: "month", span: 3)
+frame.panes.create!(model: "orders", measure: "revenue", dimension: "status",
+                    renderer: "bar", span: 2, title: "Money by status")
+```
+
+```erb
+<%= janela_frame @frame %>
+```
+
+Same helper, two ways to supply the panes. A row names a model by its route key, and only a measure, dimension, renderer and granularity the model's `janela` block declares: a row that names anything else is rejected on save, so an analyst arranges what is shown and cannot invent a query or reach a model nobody exposed. `position` orders the panes and is set for you when you leave it out. `title` is optional and replaces the title Janela would write itself.
+
+The layout is CSS Grid's own vocabulary as small integers: `columns` 1 to 12 and `gap` 0 to 8 on the frame, `span` 1 to 12 on a pane. Each one picks a class the shipped stylesheet already defines, `janela-cols-3`, `janela-gap-4`, `janela-span-2`, so nothing an analyst types reaches CSS. Set `--janela-space` once, anywhere, to move the whole spacing scale; the grid collapses to a single column on a narrow screen. ADR 016 has the reasoning.
+
+A frame renders each pane inline on the first response, so the page is a correct dashboard before any JavaScript runs and there is no request per pane on load. Cross-filtering then works exactly as it does for hand written panes. Every pane of a frame goes through your Pundit scope if you have one, the same as every other Janela query.
+
+A frame may belong to an owner, `belongs_to :owner, polymorphic: true, optional: true`. Janela sets nothing there and reads nothing from it: it exists so a multi tenant host's Pundit `Scope` has a column to filter on. Set it to whatever your tenant is, and leave it null if you have one tenant.
+
+### Janela's own pages
+
+The engine serves an index and a page per frame at the mount root, so you can install the gem and navigate the same day:
+
+```
+/dashboards                       every frame your scope returns
+/dashboards/3                     one frame
+/dashboards/orders/revenue/status an ad hoc pane, grammar unchanged
+```
+
+No model's route key is all digits, so a frame id and a pane URL cannot be confused. Both pages read through `policy_scope(Janela::Frame)`, so a frame your scope does not return is a 404 rather than a page, and so is a pane row under it.
+
+These pages render in Janela's own minimal layout, which loads the gem's stylesheet and nothing else. It does not load Turbo or Stimulus, because those come from your bundler and the engine cannot name them. So Janela's own pages are correct, styled, **static** dashboards: every pane is rendered inline and the numbers are right, filters in the URL apply, and nothing cross-filters when you click. A chart pane needs Chart.js, so on these pages it draws nothing; put a frame on your own page, where your JavaScript is, for the interactive version.
+
+The noun in the headings is `Janela::Frame.model_name.human`, so rename it in your own locale file rather than in a setting:
+
+```yaml
+en:
+  activerecord:
+    models:
+      janela/frame:
+        one: "Dashboard"
+        other: "Dashboards"
+```
+
+A host that wants a different index writes its own page over `Janela::Frame` and never routes to ours.
+
+### Editing a dashboard
+
+The same pages are the analyst's editing surface, as conventional Rails CRUD:
+
+```
+/dashboards/new        name it and choose its grid
+/dashboards/3/edit     rename it, rearrange it, add and remove panes
+/dashboards/3/panes/new
+```
+
+Everything there works with nothing but HTML, because those pages load no JavaScript. Adding a pane is therefore two steps: the first picks a model, the second offers exactly the measures and dimensions that model's `janela` block declares, so a choice that would be rejected is never offered. Granularity appears when the dimension can take one. A pane moves with Up and Down buttons rather than a position field, because arranging the window is the point, and positions stay contiguous. There is no drag and drop and no canvas; a visual editor is its own decision, not built.
+
+**Tell Janela what a new frame belongs to.** If your `ApplicationController` defines `janela_frame_owner`, the engine assigns its return value as the owner of a frame it creates. Without it, a host whose `policy_scope` filters frames by owner would hide the analyst's new dashboard the instant it was saved:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def janela_frame_owner
+    Current.account
+  end
+end
+```
+
+A host with no tenancy defines nothing, gets a nil owner, and is correct: nothing is filtering on it. Every editing action reads through `policy_scope(Janela::Frame)` as well, so another tenant's frame is a 404 to change as much as to read. The [multi tenancy guide](docs/multi-tenancy.md) has the wiring for each of the common setups.
+
+### Filters and clicks
+
 The dashboard's filters live in the page URL as the same `q[...]` parameters, so a reload keeps them and a filtered dashboard is a link you can send: `/reports/orders?q[status_eq]=paid` renders filtered before any JavaScript runs. A pane ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the pane you clicked. Time panes re-scope with the others but are not click sources yet; drill-down is the next decision. The selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read. A pane with no matching rows renders a `.janela-empty` paragraph. A group whose dimension is null is labelled `(none)` and filters with Ransack's null predicate rather than an empty string. Only models that declare a `janela` block can be requested over HTTP.
 
 ### Pane URLs
@@ -151,15 +253,11 @@ Every pane has its own URL under the mount, and a Turbo Frame in a dashboard loa
                                                 orders revenue by placed_on, per week, as a line
 ```
 
-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 inside your application layout with its filters applied, so a filtered pane is a link you can send someone. ADR 005 has the reasoning.
+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.
 
 ### 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.
-
-```bash
-bin/rails janela:install:migrations && bin/rails db:migrate
-```
+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.
 
 ```ruby
 Janela::Snapshot.take(name: "September 2026", filters: { status_eq: "paid" }) do |take|
@@ -175,7 +273,32 @@ Render a stored pane the same way you render a live one:
 <%= janela_snapshot_pane @snapshot, Order, :revenue, by: :status, as: :bar %>
 ```
 
-Panes render in Janela's own minimal layout when opened directly, so a shared pane link shows its numbers but no host styling and no charts; set `Janela::ApplicationController.layout "application"` in an initializer to use your own layout, which must not call a bare host route helper (inside an engine those need a `main_app.` prefix). Inside a dashboard, panes are Turbo Frames and carry no layout at all.
+Inside a dashboard a pane is a Turbo Frame and carries no layout at all. Opened directly it renders in Janela's own minimal layout, which deliberately loads no assets, because the gem cannot know your asset names or whether you bundle. A direct pane link therefore shows its numbers unstyled, and a chart pane shows nothing, since the chart needs Stimulus.
+
+To make direct pane links styled and chart-capable, give Janela a small layout of your own that loads your assets and nothing else:
+
+```erb
+<%# app/views/layouts/janela.html.erb %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= content_for(:title) || "Insights" %></title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= stylesheet_link_tag :app %>
+    <%= javascript_importmap_tags %>
+  </head>
+  <body><%= yield %></body>
+</html>
+```
+
+```ruby
+# config/initializers/janela.rb
+Rails.application.config.to_prepare { Janela::ApplicationController.layout "janela" }
+```
+
+Do not point Janela at your **application** layout. Janela is an isolated engine, so a bare route helper anywhere in that layout, a nav link for instance, resolves against Janela's routes and raises `NameError`. Keep the layout above small and asset-only.
 
 Stored panes are static by nature: no filter buttons, charts ignore clicks, and the URL says *as of*: `/dashboards/snapshots/42/orders/revenue/status`. Request filters are ignored because the snapshot's were fixed when it was taken.
 
@@ -198,23 +321,80 @@ end
 
 Two details matter. It is *prepended* so it runs before any filter on your `ApplicationController` that assumes a signed-in user (tenant lookups, audit logging). It redirects through `main_app` because Janela is an isolated engine, so a bare `new_session_path` inside it resolves against Janela's own routes and fails.
 
-Scoping is automatic when you use Pundit: `Janela::ApplicationController` calls `policy_scope(model)` if your `ApplicationController` defines it, and falls back to `model.all` otherwise. Every model you put on a dashboard needs a policy with a `Scope`.
+Scoping is automatic when you use Pundit: `Janela::ApplicationController` calls `policy_scope(model)` if your `ApplicationController` defines it, and falls back to `model.all` otherwise. Every model you put on a dashboard needs a policy with a `Scope`, and so do `Janela::Frame` and `Janela::Snapshot`: frames, pane rows and stored panes are all read through the scope, never around it. `test/dummy/app/controllers/application_controller.rb` is the smallest honest example of the wiring.
+
+**Multi tenancy** has its own guide: [docs/multi-tenancy.md](docs/multi-tenancy.md). It covers what goes through your scope, worked wiring for Pundit, acts_as_tenant and CanCanCan, what owns a frame the analyst creates, and the one rough edge, which is that a snapshot has no owner column yet.
+
+### The pages Janela serves
+
+Mounting the engine gives you an index of frames and a page per frame with no
+work at all, which is enough to navigate on the day you install it:
+
+```
+/insights      every frame your policy scope returns
+/insights/3    one frame
+```
+
+Both go through your `policy_scope`, so a frame another tenant owns is a 404.
+
+These pages load Janela's own stylesheet and nothing of yours, because the gem
+cannot know your asset names or bundler. Two consequences worth knowing. They
+do not cross-filter, since that needs Stimulus. And a pane whose row asks for a
+chart renders as its **table** here, because there is no chart runtime on the
+page and a table needs nothing: the same frame rendered in your own page with
+`janela_frame(@frame)` draws the chart. A renderer is a viewing choice, not part
+of the pane (ADR 018).
+
+### Checking an installation
+
+```bash
+bin/rails janela:doctor
+```
+
+Reads your application and lists what still needs doing: identifiers left over
+from an earlier version, Stimulus controllers you have not registered, tables
+you have not migrated, a `through:` dimension whose associated model does not
+allowlist the attribute, a policy that scopes frames by an owner you never
+supply, and whether the engine is mounted and authenticated. It exits non-zero
+when it finds an error, so it works in CI. It only reads and reports.
+
+Every finding names the check that produced it:
+
+```
+WARNING (unauthenticated-endpoints): no authentication filter found on ApplicationController
+```
+
+One check cannot be certain: Janela reads your controller's filters to guess
+whether the endpoints are authenticated, so if you authenticate another way it
+is a false alarm every run. Silence one you have judged, by name:
+
+```ruby
+# config/initializers/janela.rb
+Janela.silenced_checks = %w[unauthenticated-endpoints]
+```
+
+Silenced checks are named in the output every run, because a silence nobody
+remembers is how a real finding goes unread (ADR 021).
+
+Run it after installing and after any upgrade. Steps for a specific version
+upgrade are in [UPGRADING.md](UPGRADING.md).
 
 ## Design
 
 Janela ships the load-bearing core of a BI tool and nothing else. The reasoning is recorded in [`docs/decisions/`](docs/decisions/INDEX.md), starting with ADR 001.
 
-- **Measures and dimensions are a Ruby DSL on the model**, config-as-code like `routes.rb`. No drag-and-drop designer.
+- **Measures and dimensions are a Ruby DSL on the model**, config-as-code like `routes.rb`. Developers define what can be asked.
+- **Composition is data.** A frame and its panes are records, so analysts arrange what is shown without a deploy (ADR 012). A visual, drag-and-drop editor is not built and is a decision of its own.
 - **Querying rides on [Ransack](https://github.com/activerecord-hackery/ransack)'s association-path traversal.** Janela does not invent a query language.
 - **Cross-filtering is a Stimulus controller plus Turbo Frames.** Click a value in one pane, shared filter state updates, every other frame on the page re-renders.
 - **Charts are [Chart.js](https://www.chartjs.org)**, driven by one small Stimulus controller from the same values the tables show. Not a charting engine.
 - **Publishing creates a Snapshot.** An ActiveJob freezes the result set into a new record; the live dashboard stays editable and the published view is a point-in-time fork, not a toggle on the same record. Not built yet.
 
-Deliberately out of scope: report designer UI, natural-language query, a separate data warehouse, a row-level-security subsystem (use your app's Pundit/CanCanCan), refresh-scheduling UI (schedule the Snapshot job with whatever you already use), embedding SDK, mobile app, print/paginated reports. If you need one of those, the codebase is meant to be small enough to fork and add your own.
+Deliberately out of scope: natural-language query, a separate data warehouse, a row-level-security subsystem (use your app's Pundit/CanCanCan), refresh-scheduling UI (schedule the Snapshot job with whatever you already use), embedding SDK, mobile app, print/paginated reports. If you need one of those, the codebase is meant to be small enough to fork and add your own.
 
 ## Status
 
-**v0.2.1 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering, bar and line charts, pane URLs, shareable dashboard URLs and snapshots work and are covered by unit and real-browser tests. Not yet built: drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.3.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames and the engine's own pages for reading and editing them 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

@@ -0,0 +1,136 @@
+# Upgrading Janela
+
+What to do, in order, when a release needs you to act. For what
+changed and why, see [CHANGELOG.md](CHANGELOG.md); for why it was
+decided, see [docs/decisions](docs/decisions/INDEX.md).
+
+After any upgrade, run:
+
+```bash
+bin/rails janela:doctor
+```
+
+It reads your application and lists what still needs changing.
+
+## 0.2.1 to 0.3.0
+
+Two things arrive together. Janela's own words settle on frames and
+panes, which is a rename across your application: a frame is the
+dashboard, a pane is one visual in it. And a dashboard can now be a
+database record rather than only ERB, which is what the new tables and
+the engine's own pages are for.
+
+Step 1 is the one that breaks a page if you skip it. The renames after
+it can be done in any order, and `janela:doctor` will tell you what you
+have missed.
+
+**1. Run the migrations.**
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Required if you mount the engine, even if you never intend to store a
+dashboard. From this release the mount root serves an index of frames,
+so without the tables `/dashboards` raises where it used to work.
+
+**2. Rename the Stimulus controller you register.**
+
+```js
+// app/javascript/controllers/index.js, or wherever you register it
+- import JanelaDashboardController from "@retail-tasker/janela/dashboard_controller"
+- application.register("janela--dashboard", JanelaDashboardController)
++ import JanelaFrameController from "@retail-tasker/janela/frame_controller"
++ application.register("janela--frame", JanelaFrameController)
+```
+
+On importmap the path is `janela/frame_controller` rather than
+`janela/dashboard_controller`. On npm, reinstall so the new export
+path resolves:
+
+```bash
+yarn add github:retail-tasker/janela#v0.3.0   # or bump your version range
+```
+
+**3. Rename the helper that wraps your panes.**
+
+```erb
+- <%= janela_dashboard do %>
++ <%= janela_frame do %>
+    <%= janela_pane Order, :revenue %>
+  <% end %>
+```
+
+`janela_pane` and `janela_snapshot_pane` are unchanged.
+
+**4. Rename any Janela data attributes in your own markup.**
+
+Anything you wrote by hand, most likely a clear button:
+
+```erb
+- <button data-action="janela--dashboard#clear">Clear filters</button>
++ <button data-action="janela--frame#clear">Clear filters</button>
+```
+
+The same applies to `data-janela--dashboard-target` and
+`data-janela--dashboard-*-param` if you built your own controls.
+
+**5. Rename the constants, if you reference them.**
+
+Most applications do not.
+
+| Was | Now |
+| --- | --- |
+| `Janela::Pane` | `Janela::Query` |
+| `Janela::Pane#frame_id` | `Janela::Query#turbo_frame_id` |
+| `Janela::DashboardHelper` | `Janela::FramesHelper` |
+| `Janela::PanesController` | `Janela::QueriesController` |
+| `Janela::SnapshotPanesController` | `Janela::SnapshotQueriesController` |
+
+`Janela::Pane` is reserved for a database record in a later release,
+which is why the runtime object had to give the name up.
+
+If you override Janela's view, move your copy from
+`app/views/janela/panes/` to `app/views/janela/queries/`.
+
+**6. Tell Janela what a new frame belongs to, if your policy asks.**
+
+Only for a multi tenant host. If your Pundit scope filters
+`Janela::Frame` by an owner, a frame created through Janela's own form
+would be saved with no owner and hidden by that scope the instant it
+was saved. Define the hook on the controller Janela inherits from:
+
+```ruby
+class ApplicationController < ActionController::Base
+  def janela_frame_owner
+    Current.account # whatever your scope filters frames by
+  end
+end
+```
+
+`janela:doctor` reports this one for you: it asks your policy for a
+scope and looks for an owner in it. `docs/multi-tenancy.md`, shipped
+in the gem, has the wiring for Pundit, acts_as_tenant and CanCanCan.
+
+**7. Link the stylesheet, if you have not.**
+
+```erb
+<%= stylesheet_link_tag "janela" %>
+```
+
+Optional. It is the grid and enough style to read a pane, and Janela's
+own pages load it themselves either way.
+
+**Numbers read differently, and you need do nothing.** A measure now
+renders to the precision it means rather than to whatever the database
+returned, so a sum of a `decimal(10, 2)` column that read as `375.0`
+reads as `375.00`. Declare `precision:`, `prefix:` or `suffix:` on the
+measure to say otherwise. Nothing is rounded before it is stored or
+compared.
+
+**Nothing else changed.** Pane URLs, the route helpers `pane_path` and
+`snapshot_pane_path`, turbo frame ids, and the CSS hooks
+`janela-pane`, `janela-chart`, `janela-value` and `janela-empty` are
+all as they were. Your measures, dimensions and snapshots are
+untouched.

data/app/assets/javascripts/janela/chart_controller.js

@@ -4,11 +4,12 @@ import { Chart, registerables } from "chart.js"
 Chart.register(...registerables)
 
 // Renders one pane as a chart and turns a click on a bar into the same
-// toggle event a table button emits, so the dashboard controller cannot tell
-// the difference. Turbo replaces the frame on every cross-filter, so the chart
-// is destroyed on disconnect and rebuilt on connect.
+// toggle event a table button emits, so the frame controller cannot tell the
+// difference. Turbo replaces the turbo frame on every cross-filter, so the
+// chart is destroyed on disconnect and rebuilt on connect.
 export default class extends Controller {
-  static values = { type: String, labels: Array, values: Array, filters: Object, title: String, selected: String }
+  static values = { type: String, labels: Array, values: Array, filters: Object, title: String,
+                    selected: String, formatted: Array }
 
   connect() {
     this.chart = new Chart(this.element, {
@@ -25,7 +26,13 @@ export default class extends Controller {
       options: {
         animation: false,
         scales: { y: { beginAtZero: true } },
-        plugins: { legend: { display: false } },
+        plugins: {
+          legend: { display: false },
+          // The server formatted every number for the table, so the tooltip
+          // reads the same string rather than formatting a second time here
+          // and disagreeing with the cell beside it.
+          tooltip: { callbacks: { label: (item) => this.formattedValue[item.dataIndex] ?? item.formattedValue } }
+        },
         onClick: (_event, elements) => {
           if (elements.length === 0) return
           const label = this.labelsValue[elements[0].index]

data/app/assets/javascripts/janela/{dashboard_controller.js → frame_controller.js}

@@ -1,7 +1,7 @@
 import { Controller } from "@hotwired/stimulus"
 
-// Shared filter state for every pane on the page. Clicking a value rewrites
-// each frame's src, and Turbo reloads a frame whenever its src changes, so
+// Shared filter state for every pane in the frame. Clicking a value rewrites
+// each turbo frame's src, and Turbo reloads one whenever its src changes, so
 // cross-filtering needs no streams, no sockets and no state library.
 export default class extends Controller {
   static targets = ["pane"]
@@ -26,7 +26,14 @@ export default class extends Controller {
     this.filtersValue = {}
   }
 
-  filtersValueChanged() {
+  // Stimulus calls this as the controller connects, handing back the value it
+  // just read from the attribute the server rendered, so nothing has changed
+  // yet. A frame rendered from rows is already showing the right numbers
+  // inline, and a src assigned here would make Turbo fetch every pane and
+  // throw that first render away (ADR 014).
+  filtersValueChanged(filters, previous) {
+    if (previous === undefined || JSON.stringify(filters) === JSON.stringify(previous)) return
+
     this.paneTargets.forEach((pane) => {
       const url = new URL(pane.dataset.janelaSrc, window.location.origin)
       this.writeFilters(url)
@@ -37,7 +44,7 @@ export default class extends Controller {
   }
 
   // The page URL carries the same q[...] the panes do, so a reload or a
-  // pasted link opens the dashboard filtered (ADR 008). Replaced rather than
+  // pasted link opens the frame filtered (ADR 008). Replaced rather than
   // pushed: a click is not a place the back button should return to.
   syncPageUrl() {
     const url = new URL(window.location.href)