janela 0.12.0 → 0.14.0

data/docs/decisions/054-a-chart-reads-numbers-the-way-its-measure-formats-them.md

@@ -0,0 +1,221 @@
+---
+Date: 2026-10-06
+Status: Accepted
+Related: ADR 004, ADR 020, ADR 029, ADR 037, ADR 038, ADR 046, ADR 047, ADR 050, ADR 053
+Triggers:
+  - a chart's axis showing a number the tooltip shows differently
+  - drawing text on a chart canvas, or adding a Chart.js plugin
+  - adding a boolean to a pane, a column to janela_panes, or a parameter to the pane URL
+  - a ratio, a currency or a percentage on a chart
+  - a chart too dense to label every bar
+Topics: charts, formatting, measures, public-api, panes, urls
+---
+
+# ADR 054: A Chart Reads Numbers the Way Its Measure Formats Them
+
+## Context
+
+#72 and #76, raised from a real install building a client report: a share
+of rows by category, drawn as bars, with the percentage on each bar. Two
+things stood in the way, and both are the same gap. A chart is the one
+place a number reaches a reader without the measure's format applied
+(ADR 020), except the tooltip, which a reader has to hover to see.
+
+Both were reproduced against the demo on `main` (Chart.js 4.5.1), with the
+chart built live and the drawn scale read from it.
+
+**The axis is raw.** A bar chart of a ratio drew ticks `0, 0.1 ... 1.0`
+beside tooltips reading `0.0%`. Revenue drew `0, 50,000 ... 500,000` beside
+tooltips reading `$469,097.85`. `chart_controller.js` sets
+`scales: { y: { beginAtZero: true } }` and formats only the tooltip.
+
+**#72 said this was never decided. It was.** ADR 020 closes its Decision
+with "The chart still plots raw numbers, because an axis is a scale and not
+a label." That sentence is wrong for a reader, who reads the axis as labels
+whatever it is to Chart.js. A ratio's axis at 0.5 against a tooltip at 50.0%
+reads as two different numbers (ADR 038 keeps the stored value a fraction
+for the data's sake, which is not a reason for the axis to show one). The
+rest of ADR 020 stands: the number is never rounded or transformed, and the
+measure is the layer that owns its format.
+
+**Tick precision does not need a rule of Janela's own.** The worry in #72
+was that ticks fall between data points, so the precision that suits a
+value (`25.0%`) is wrong for a tick (`25%`). Chart.js's own numeric tick
+formatter already derives its decimals from the spacing between ticks.
+Calling it with a ratio's ticks scaled by 100 and appending `%` gave, on the
+live chart:
+
+| ratio data up to | ticks |
+| --- | --- |
+| 0.53 | `0%, 10% ... 60%` |
+| 0.03 | `0%, 0.5%, 1% ... 3%` |
+| 1 | `0% ... 100%` |
+
+Whole percentages where the spacing is whole, half percentages only where
+the ticks really are half a percent apart. One catch: scaling by 100 leaves
+float noise (`3.5000000000000004%`), so the scaled value has to be rounded
+before it is formatted.
+
+**A bar label has to fit, and nothing guarantees it does.** Measured with a
+label drawn at each bar's end:
+
+- The tallest bar of a default chart touches the top of the plot area, so a
+  label above it is clipped. `scales.y.grace = "10%"` left 30px of
+  headroom in a 300px chart, and Chart.js 4.5.1 supports it.
+- A label inside the bar was never an option: the shortest bars are about
+  2px tall.
+- With 30 bars in a 600px chart a bar was 13px wide and a label such as
+  `$88,000.00` was 60px, so neighbouring labels overlap several deep.
+  Hiding only the ones that collide would label some bars and not others
+  for a reason a reader cannot see.
+- A negative bar ends below its base, so a label placed above the end would
+  sit on the bar.
+- A plugin cannot be added to a chart after it is built, so the drawing has
+  to be handed over when the controller constructs the chart, as
+  `maintainAspectRatio` is for a height (ADR 047).
+
+### What was considered
+
+**Formatted tick strings from the server.** The server formats a value
+(ADR 020), but the client chooses the ticks, where they fall depends on the
+chart's size and data, and the server cannot know them. It would have to
+format values it is never asked about.
+
+**A `precision` of the measure's own for ticks.** A measure's precision is
+what one value means. A scale spanning `$0` to `$500,000` in steps of
+50,000 does not want cents, and a ratio at one decimal place would print
+`20.0%` at every tick. It is the answer to a different question.
+
+**A host-supplied tick callback.** A setting, to do what one formatter
+already does for every measure. ADR 001 prefers one obvious way, and ADR 021
+and ADR 023 only allow a setting where a judgement is made once at boot.
+
+**`chartjs-plugin-datalabels` for the bar labels.** A dependency, and a
+second way to format a number on a chart. ADR 004 keeps Chart.js the one
+thing the engine ships, and an inline plugin that draws a string the server
+already produced is about twenty lines.
+
+**Labels on by default.** Changes every bar chart that exists, and a chart
+of thirty bars gains nothing from it. Unset must change nothing, as it does
+for height and prominence.
+
+**A setting for where the label sits, or whether it fits.** Outside the end
+is the only place that works for every bar, including the shortest and the
+negative, and a fit that is a judgement per chart is a decision a reader of
+the dashboard cannot see made.
+
+**Labels on a line, or on a ring.** A line has a point per bucket, often
+sixty or more, and a ring already prints every value beside it (ADR 046).
+Neither gains from it.
+
+## Decision
+
+**A chart's axis is formatted by the measure, always, and a bar chart can
+be asked to draw each bar's value as a label.** The first supersedes the one
+sentence in ADR 020 above and nothing else in it. The second is opt in.
+
+### The axis
+
+The server sends what a tick needs as one more data attribute on the canvas:
+the measure's `prefix`, its `suffix`, and whether it is a ratio.
+
+```erb
+data-janela--chart-tick-format-value='{"prefix":"$","suffix":"","ratio":false}'
+```
+
+The controller formats each tick with Chart.js's own numeric formatter and
+adds those. A ratio's ticks are scaled by 100, rounded to remove float
+noise, and given a `%`. The measure's `precision` is not used: the tick's
+decimals come from the spacing between ticks, which is what answers "25%,
+not 25.0%". It applies to a bar and a line, both of which have a value axis,
+and it is not a setting: it is what the axis always was, now correct.
+
+A measure with no prefix, suffix or ratio draws what it draws today.
+
+### The labels
+
+**A pane may carry `value_labels`, a boolean. Unset is exactly what it is
+today.** When set on a bar chart, each bar's formatted string, the same one
+the tooltip shows, is drawn beyond the end of the bar, above for a positive
+value and below for a negative one. The value axis is given 10% of grace so
+the tallest bar keeps its label in the plot.
+
+**All or none.** The labels are drawn only if every one of them fits within
+its category's slot, the chart area's width divided by the number of bars.
+If any does not, none is drawn and the chart is what it was without the flag.
+A chart never labels some bars and not others, and a host that wants the
+labels on a dense chart makes the chart wider or the pane a bar chart of
+fewer categories (`limit:`, ADR 007).
+
+**One vocabulary in three places,** as height and prominence do:
+
+```erb
+<%= janela_pane Order, :expedited_rate, by: :status, as: :bar, value_labels: true %>
+```
+
+- `Janela::Pane#value_labels`, a nullable boolean, offered on the pane form
+  as a checkbox.
+- `janela_pane` and `janela_snapshot_pane` take `value_labels:`.
+- The pane URL carries it as `?value_labels=1`, because the server draws the
+  pane again from that URL on every cross-filter.
+
+**The name avoids `labels`.** In this codebase a chart's labels are its
+categories: the controller's `labels` value is the x axis. `value_labels`
+says which labels, and `values` would collide the same way with the
+controller's `values`. It is the one name that reads the same at the helper,
+the column, the URL and the controller (ADR 037).
+
+**It is not part of the pane's identity.** ADR 029 identifies a frame by who
+it is, and whether its bars carry numbers does not say which query it is. It
+stays out of `Query.turbo_frame_id`.
+
+**On anything that is not a bar chart it is ignored, not an error.** A
+table, a single value, a line and a ring keep what they have, and a pane
+switched between renderers keeps the flag, as height does on a ring
+(ADR 047).
+
+## Consequences
+
+- **Every existing chart's axis can change.** A revenue chart gains a `$`
+  on its ticks and a ratio chart reads in percentages. Nothing else about it
+  moves, and a measure with no prefix, suffix or ratio is untouched. It is
+  in `CHANGELOG.md` under Changed as a visible correction, with no action for
+  a host; it is not an `UPGRADING.md` step (ADR 015), because nothing a host
+  wrote has to change. A host that overrode the tick callback on its own
+  chart is unaffected, since Janela does not set one for it.
+- A ratio chart is readable end to end: a percentage on the axis, in the
+  tooltip, and on the bars if asked.
+- **A migration for stored frames.** `janela_panes` gains a nullable
+  boolean `value_labels`, additive, so every existing pane is unset and
+  unchanged. A host using stored frames runs `bin/rails
+  janela:install:migrations` and `db:migrate`, as it did for `height`,
+  `prominence` and `companions`. The doctor's `unmigrated-columns` check
+  (ADR 035) is taught the new column, so a host that upgrades and skips the
+  migration is told rather than meeting an error on the pane form. A host that
+  does not use stored frames has nothing to do.
+- **`Janela::Tools` has to learn the attribute.** Its `PANE_ATTRIBUTES` is the
+  list of a pane's own attributes an agent may set (ADR 053), and an
+  attribute not on it is refused. `value_labels` joins it in the same change as
+  the column, or an agent could arrange every other part of a pane and not
+  this one.
+- **The pane URL grammar grows by one optional parameter.** ADR 037 counts
+  that as public surface, which is why this belongs before 1.0.
+- **Ticks use the browser's number locale, and the tooltip uses the host's
+  delimiter** (ADR 020). A host whose `number.format.delimiter` differs from
+  its readers' browsers would see two styles on one chart. This is from how
+  Chart.js formats and is not something measured here; if it turns up in
+  practice the answer is to pass the delimiter in the same attribute, not to
+  stop using Chart.js's formatter.
+- The all or none rule means the flag can do nothing on a dense chart, and
+  the pane form cannot say so. That is a real cost, accepted because the
+  alternative is a chart that labels bars selectively.
+- Drawn pixels are not available to a screen reader. That is as true of the
+  bars themselves, which ADR 042 answers with the figure's caption and the
+  table beside it, and this decision does not change it.
+- Tests read what the code produced: the drawn tick labels, and the position
+  and text of each drawn bar label, not the attribute that asked for them
+  (ADR 035).
+- What would change this decision: a need for a label on a line or a ring,
+  which is an argument about those renderers and not about this one; or a
+  host that needs the labels to survive on a dense chart, which would be a
+  case for a step in how they are thinned and not for a placement setting.

data/docs/decisions/INDEX.md

@@ -23,26 +23,26 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | **Vision, scope, forkability** | 001, 010, 012, 037, 052 |
 | **Open-source & host-decoupling** | 001, 022, 036, 041, 052 |
 | **DSL & query layer** | 002, 006, 007, 020, 025, 038, 044, 049, 051 |
-| **Dependencies** | 002, 003, 004, 006, 017, 025 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040, 048 |
+| **Dependencies** | 002, 003, 004, 006, 017, 025, 053 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040, 048, 053 |
 | **Performance & storage** | 007, 017, 025, 048, 051 |
-| **Ordering & formatting** | 007, 020, 038 |
+| **Ordering & formatting** | 007, 020, 038, 054 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025, 040, 043, 044, 045, 048, 049 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027, 039, 047, 050 |
 | **CSS & styling** | 016, 018, 023, 026, 027, 036, 042, 046, 047, 050 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044, 047, 048, 050, 051 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044, 047, 048, 050, 051, 053, 054 |
 | **Naming rule** | 014, 023, 036 |
-| **JavaScript delivery & charts** | 004, 006, 026, 042, 046, 047 |
+| **JavaScript delivery & charts** | 004, 006, 026, 042, 046, 047, 054 |
 | **Time dimensions** | 006, 025, 045 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051, 054 |
 | **Snapshots & publishing** | 009, 020, 028, 033, 034, 051 |
-| **AI agents & guidance** | 010, 015, 021 |
+| **AI agents & guidance** | 010, 015, 021, 053 |
 | **The doctor & checks** | 021, 025, 032, 033, 035 |
 | **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037, 042, 052 |
 | **Accessibility & keyboard** | 024, 042, 045, 046, 049 |
 | **Security** | 003, 025, 028, 031, 032, 034, 035, 044, 052 |
 | **Testing** | 003 |
-| **Roadmap & planning** | 001, 037, 045, 046, 052 |
+| **Roadmap & planning** | 001, 037, 045, 046, 052, 053 |
 
 ## Chronological
 
@@ -100,7 +100,9 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 050 | A Single Value's Prominence Is One of Three Steps, and Unset Changes Nothing | 2026-09-30 | Accepted |
 | 051 | A Table Can Carry Companion Columns, and a Fact Is Shown Only When It Is Shared | 2026-09-30 | Accepted |
 | 052 | Two People Cut Releases, Reports Go Private, and Support Is Best Effort | 2026-09-30 | Accepted |
+| 053 | An Agent Reaches Janela Through Tools the Host Scopes, and Janela Registers None | 2026-10-02 | Accepted |
+| 054 | A Chart Reads Numbers the Way Its Measure Formats Them | 2026-10-06 | Accepted |
 
 ## Next number
 
-Next ADR: 053
+Next ADR: 055

data/docs/multi-tenancy.md

@@ -36,9 +36,10 @@ without asking first:
 - A snapshot, read through `policy_scope(Janela::Snapshot)`.
 
 A pane rendered inline in your own page runs in your request, so the
-same scope applies there as in the engine's controllers. Nothing is
-calculated in a background context where the current tenant would have
-gone missing.
+same scope applies there as in the engine's controllers, so a live pane
+is never calculated where the current tenant would have gone missing. A
+scheduled snapshot is the one thing that runs in the background, and it
+is told whose it is (see Snapshots below).
 
 ## With Pundit
 
@@ -69,6 +70,23 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+A snapshot is read through its own scope as well. Without a policy for it
+Pundit raises, and a hand rolled `policy_scope` that does not name it
+would hand every tenant every snapshot, so write the second one too:
+
+```ruby
+# app/policies/janela/snapshot_policy.rb
+module Janela
+  class SnapshotPolicy < ApplicationPolicy
+    class Scope < ApplicationPolicy::Scope
+      def resolve
+        scope.where(owner: Current.account)
+      end
+    end
+  end
+end
+```
+
 Your own models keep the policies they already have. Janela calls
 `policy_scope(Order)` and gets whatever `OrderPolicy::Scope` returns.
 
@@ -85,7 +103,7 @@ class ApplicationController < ActionController::Base
   private
     def policy_scope(model)
       case model.name
-      when "Janela::Frame" then model.where(owner: ActsAsTenant.current_tenant)
+      when "Janela::Frame", "Janela::Snapshot" then model.where(owner: ActsAsTenant.current_tenant)
       else model.all # acts_as_tenant has already scoped your own models
       end
     end

data/docs/roadmap.md

@@ -8,7 +8,7 @@ Topics: roadmap, releases, scope, planning
 
 <svg viewBox="0 0 680 360" width="100%" role="img" aria-labelledby="vista-title vista-desc" class="vista-art" style="display: block; margin: 1.75rem 0; border-radius: 10px;">
   <title id="vista-title">Vista</title>
-  <desc id="vista-desc">Sea and sky with a horizon across them. The near water is dark, because every issue in 1.0 has shipped, and three lights sit far off at the horizon for the work still in sight past it. A low sun rises and sets on the horizon as the pointer moves up and down, and never climbs higher: the sky above is empty, because what is not coming is not in view.</desc>
+  <desc id="vista-desc">Sea and sky with a horizon across them. The near water is dark, because every issue in 1.0 has shipped, and five lights sit far off at the horizon for the work still in sight past it. A low sun rises and sets on the horizon as the pointer moves up and down, and never climbs higher: the sky above is empty, because what is not coming is not in view.</desc>
 
   <style>
     .vista-art .v-far { transform: translate3d(calc(var(--vitral-shift-x, 0) * 13px), calc(var(--vitral-shift-y, 0) * 7px), 0); transition: transform .45s cubic-bezier(.2,.7,.3,1); }
@@ -89,6 +89,10 @@ Topics: roadmap, releases, scope, planning
       <circle cx="322" cy="201" r="1.5" fill="#FFF3DC" opacity="0.55"/>
       <circle cx="540" cy="202.5" r="8" fill="url(#vLamp)" opacity="0.2"/>
       <circle cx="540" cy="202.5" r="1.6" fill="#FFF3DC" opacity="0.55"/>
+      <circle cx="112" cy="201.5" r="8" fill="url(#vLamp)" opacity="0.2"/>
+      <circle cx="112" cy="201.5" r="1.5" fill="#FFF3DC" opacity="0.55"/>
+      <circle cx="430" cy="202" r="8" fill="url(#vLamp)" opacity="0.2"/>
+      <circle cx="430" cy="202" r="1.6" fill="#FFF3DC" opacity="0.55"/>
     </g>
 
     <g class="v-glint" stroke="#FFE2A6" stroke-linecap="round">
@@ -109,7 +113,7 @@ Topics: roadmap, releases, scope, planning
 Janela is alpha. It works, it is tested against a real Rails application
 in a real browser, and its public surface has changed in three of the
 last four releases. This page says what has to be true before that stops,
-what is in the next release, and what is deliberately not coming. The
+what is left before 1.0, and what is deliberately not coming. The
 reasoning behind it is ADR 037.
 
 ## What 1.0 means
@@ -128,11 +132,11 @@ change in any release, and every change of that kind carries an entry in
 `UPGRADING.md`.
 
 **A pane can be read.** Janela draws tables, bars, lines, doughnuts and
-pies. A table row still cannot carry context beside its label, a single
-number has no way to say how prominent it is, and a chart takes whatever
-height its width gives it whether or not that suits the page. Those are
-not extra features. They are the 5% not finished, and most of them were
-found by people installing the gem rather than reading it.
+pies. A table row can carry context beside its label, a single number says
+how prominent it is, a chart has a height that suits the page, its axis reads
+in the measure's own format, and a bar can show its value. Those
+were not extra features. They were the 5% not finished, and most of them
+were found by people installing the gem rather than reading it.
 
 **The doctor can be trusted.** `rails janela:doctor` checks an
 installation for the mistakes that produce a dashboard showing numbers
@@ -144,17 +148,24 @@ working is a check nobody should rely on.
 
 The near ground is clear. Every issue that was in 1.0 has shipped: chart
 height, a ratio measure, single value prominence, companion columns, Sprockets
-hosts, and how the project is run. What 1.0 waits on now is time with real
-installs, since much of that surface was added in the last days and has only
-met this repository. When nothing surprising comes back, the surface is
-frozen and 1.0 is tagged.
+hosts, and how the project is run. 0.13.0 added tools an agent can use
+(ADR 053). 0.14.0 followed: a chart's axis reads in the measure's own format,
+so a ratio is a percentage down the side as well as in the tooltip, and a bar
+chart can show each bar's value (ADR 054). Both came from a real install, and
+the second adds a pane option, so it starts its own short soak. What 1.0 waits
+on now is a week of real installs of 0.14.0 ([#71](https://github.com/retail-tasker/janela/issues/71)),
+since much of that surface was added in the last days and has only met this
+repository. When nothing surprising comes back, the surface is frozen and 1.0
+is tagged. The agent tools are the one new piece of surface: the read tools are
+frozen at 1.0, and the write tools are frozen with them only if a real host has
+used them by the end of that week. Otherwise they wait for 1.1.
 
 Progress is tracked on the
 [1.0 milestone](https://github.com/retail-tasker/janela/milestone/2).
 
 ## Horizonte
 
-The three lights far off at the horizon. Wanted, not blocking a stable
+The lights far off at the horizon. Wanted, not blocking a stable
 release, and being on this list is not a refusal.
 
 - **Drilling down on time panes** ([#65](https://github.com/retail-tasker/janela/issues/65)).
@@ -162,6 +173,17 @@ release, and being on this list is not a refusal.
   that pane itself to the weeks within it is a different gesture, with
   its own questions about getting back out and about the URL, and it
   needs a decision record before any code.
+- **Telling a frame to refresh** ([#68](https://github.com/retail-tasker/janela/issues/68)).
+  One action a host's own timer or push can call, and no timer or stream of
+  Janela's own (ADR 048). Additive, so it can land after 1.0.
+- **A frame toolbar** ([#77](https://github.com/retail-tasker/janela/issues/77)).
+  A small strip of standard controls a host does not have to build, starting
+  with full screen. Additive, so it can land after 1.0, and it needs a decision
+  record first.
+- **A theme panel in the demo** ([#84](https://github.com/retail-tasker/janela/issues/84)).
+  Setting how every pane is presented, starting with colours, as a page of
+  controls over the properties a theme already publishes. The demo, not the
+  gem, and any property beyond colour needs a decision record first.
 - **A command palette for the demo** ([#41](https://github.com/retail-tasker/janela/issues/41)).
   The demo site, not the gem.
 - **A scroll drift on the gallery page** ([#45](https://github.com/retail-tasker/janela/issues/45)).
@@ -178,7 +200,9 @@ run does it better.
 Natural-language query. A separate data warehouse. A row-level-security
 subsystem, because your application already has Pundit or CanCanCan and
 Janela reads through it. A refresh-scheduling interface, because you
-already have a scheduler and snapshots are an ActiveJob. An embedding
+already have a scheduler and snapshots are an ActiveJob (a way to tell a
+frame to refresh, which your scheduler can call, is
+[#68](https://github.com/retail-tasker/janela/issues/68)). An embedding
 SDK. A mobile application. Print and paginated reports. A drag-and-drop
 visual dashboard designer, though frames and panes are database records,
 so an application can build its own editor on top of them.

data/docs/theming.md

@@ -82,6 +82,7 @@ the names a theme spends most of its time on.
 | `janela-legend` | `<table>` | its legend, one row of swatch, button and value per slice |
 | `janela-swatch` | `<span>` | the colour beside a legend label |
 | `janela-empty` | `<p>` | a pane whose query returned nothing |
+| `janela-muted` | `<p>` | the note under a ring that could not be drawn and became a table (ADR 046) |
 | `janela-error` | `<p>` | a pane that could not be read |
 | `janela-content` | `<div>` | a stored pane holding words or a host partial rather than a query (ADR 039) |
 | `janela-content-heading` | `<h2>` | a text pane's heading |
@@ -121,8 +122,9 @@ here rather than being left for each host to write.
 `janela.css` also styles Janela's own pages, the frame index and the
 editing forms: `janela-page`, `janela-card`, `janela-button`,
 `janela-form`, `janela-field`, `janela-list`, `janela-crumb`,
-`janela-flash` and the rest. They are scoped under `janela-page`, which
-only the engine's own layout sets, so they cannot touch your pages.
+`janela-flash` and the rest. They are plain class names that the engine's
+own pages use, not scoped to `janela-page`, so they affect your pages
+only if your own markup uses the same names. Avoid them.
 
 **Those names may change in any release.** They are the engine's own
 chrome rather than an interface. Restyle them if you want Janela's
@@ -140,8 +142,8 @@ Janela.theme = "midnight"
 
 The name is resolved against your own asset paths, so `midnight.css` in
 your application works exactly as the gem's own `vitral` does. A name
-that resolves to nothing raises rather than quietly rendering an
-unthemed page.
+that your asset pipeline cannot find raises when the page renders,
+rather than quietly rendering an unthemed one.
 
 That setting links the theme into **Janela's own pages**. Your pages load
 whatever your layout says, so if you want the same look around a pane you

data/lib/janela/doctor.rb

@@ -9,7 +9,7 @@ module Janela
 
     # Run in this order, and each one names the finding it produces: a host
     # silences a check by that name (ADR 021).
-    CHECKS = %i[stale_identifiers unmounted_engine unmigrated_tables unregistered_controllers
+    CHECKS = %i[stale_identifiers unmounted_engine unmigrated_tables unmigrated_columns unregistered_controllers
                 through_dimensions_without_an_allowlist unscoped_reads frames_nobody_will_own
                 snapshots_nobody_will_see unauthenticated_endpoints
                 hardcoded_disallowed_predicates].freeze
@@ -21,10 +21,22 @@ module Janela
       "janela/dashboard_controller" => "janela/frame_controller",
       "janela/dashboard_controller.js" => "janela/frame_controller.js",
       "Janela::DashboardHelper" => "Janela::FramesHelper",
-      "Janela::PanesController" => "Janela::QueriesController",
       "Janela::SnapshotPanesController" => "Janela::SnapshotQueriesController"
     }.freeze
 
+    # A name that was renamed away and later given back to something else, so
+    # finding it cannot say which one the host means. An error would send a
+    # host patching the stored-pane form to a controller without pane_params,
+    # and the extra param would silently stop saving (#74). A warning says what
+    # the name means now and leaves the judgement to the host.
+    REUSED = {
+      "Janela::PanesController" =>
+        "This name was the controller that renders a pane's query until 0.7, when it became " \
+        "Janela::QueriesController. Since 0.12 it is the stored-pane form's controller again, " \
+        "and it owns pane_params. A patch to the form belongs here; a patch to how a query " \
+        "renders belongs on Janela::QueriesController."
+    }.freeze
+
     SEARCHED = %w[app config lib].freeze
     READABLE = %w[.rb .erb .js .erb.html .html.erb .haml .slim .yml].freeze
 
@@ -79,14 +91,26 @@ module Janela
       end
 
       def stale_identifiers
-        RENAMED.filter_map do |old, new|
-          files = source_files.select { |file| file.read.include?(old) }
-          next if files.empty?
+        renamed = RENAMED.filter_map do |old, new|
+          next unless (files = files_naming(old)).any?
 
-          Finding.new(severity: :error,
-            summary: "#{old} is now #{new}",
-            detail: files.map { |file| "  #{file.relative_path_from(@root)}" }.join("\n"))
+          Finding.new(severity: :error, summary: "#{old} is now #{new}", detail: listed(files))
         end
+        reused = REUSED.filter_map do |name, meaning|
+          next unless (files = files_naming(name)).any?
+
+          Finding.new(severity: :warning, summary: "#{name} has meant two things",
+            detail: "  #{meaning}\n#{listed(files)}")
+        end
+        renamed + reused
+      end
+
+      def files_naming(identifier)
+        source_files.select { |file| file.read.include?(identifier) }
+      end
+
+      def listed(files)
+        files.map { |file| "  #{file.relative_path_from(@root)}" }.join("\n")
       end
 
       def unmounted_engine
@@ -116,6 +140,40 @@ module Janela
         nil # no database to ask yet
       end
 
+      # The columns a release added to a table that already existed. A host that
+      # upgraded and did not run the migration has the table, so the check above
+      # passes, and meets an error the first time a pane form or a stored pane
+      # reads the column. Only the tables that exist are asked: a missing table
+      # is that check's finding, and listing every column of it here would say
+      # the same thing twice.
+      ADDED_COLUMNS = {
+        "Janela::Frame" => %w[key default_model default_where],
+        "Janela::Pane" => %w[kind heading body link partial height prominence companions value_labels],
+        "Janela::Snapshot" => %w[owner_type owner_id]
+      }.freeze
+
+      def unmigrated_columns
+        return unless engine_mounted?
+
+        absent = ADDED_COLUMNS.filter_map do |model_name, columns|
+          model = model_name.constantize
+          next unless model.table_exists?
+
+          missing = columns - model.column_names
+          "#{model.table_name} (#{missing.join(', ')})" if missing.any?
+        end
+        return if absent.empty?
+
+        Finding.new(severity: :error,
+          summary: "#{absent.to_sentence} #{absent.one? ? 'is' : 'are'} missing columns a release added",
+          detail: "  The tables exist, so the migrations from an earlier release ran, but a later one has not.\n" \
+                  "  Run:\n" \
+                  "    bin/rails janela:install:migrations\n" \
+                  "    bin/rails db:migrate")
+      rescue StandardError
+        nil # no database to ask yet
+      end
+
       def engine_mounted?
         Rails.application.routes.routes.any? { |route| route.app.respond_to?(:app) && route.app.app == Janela::Engine }
       end