janela 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91a8da061f836f0c93ed3c6005f704fc8c5830ea2fb8e73f2f77c96f2107c467
-  data.tar.gz: ace46d3c7c08ea5423de350f14dcd17e6a303528f62f2a3c60b66b9bf2cc88bf
+  metadata.gz: a28af383164e7bc1176c8b41bcff4d4ee384bbdaac7313b66a781c5c047a4fb8
+  data.tar.gz: 7611b5e28e04d9dc3cf45a940eba1aae33e2b80beb708f3a24b7ecc12a650819
 SHA512:
-  metadata.gz: ce044bb0f401c9541a69952212b22492c94d3d68a7a7ce05af8e568b0a77c16adf41b8153291cbc981c80ad2343a16122989890c00ce6feeb5ee3200605ebc82
-  data.tar.gz: 1244329924141334f04b3d4f4ac0f15834862d110d0577f5a3739ff2085549a790d76691941df362080a1b470de6927773a3a4cd0cda963f62cb3ca31e0640a4
+  metadata.gz: 8b32263ebc50a9d33ca95a9629bde4a58937370ea70df0fe17c58d651a0f87953aeb668dc363933c0aaa5e36a2b4bd663ffbdf4ea670cf5eec3dd5e3f7ee380d
+  data.tar.gz: 7651430b673d289b5bfa1a650c66351d580714c542cba06ec046cac4236dde21079c5debeddc9d27439442596b8a317aa60adccda1d1c3c9f1216b60a0d73f54

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-09-23
+
+### Added
+
+- `docs/theming.md`, "Theming Janela": the contract a theme may target. Every class the engine renders in your own pages, the three custom properties that carry `janela.css`, what a theme is expected to leave alone, and how to write one of your own. A theme is any stylesheet you name, `Janela.theme = "midnight"` resolving from your own asset paths, and vitral is one of them rather than the one. Ships in the gem; `test/dummy` has a live page at `/vitral` showing all of it against real panes (ADR 036).
+- `janela-own-headings`, a class you put on any ancestor when your own markup already says what a pane is. A table pane's `<caption>` and a single value's label stop being drawn and stay in the accessibility tree. Hidden rather than removed on purpose: a caption is the table's accessible name, so `display: none` lands a screen reader on a grid of numbers with nothing to say what they measure, which is the easy wrong answer this saves you writing. A chart pane needs nothing, since its title was only ever an `aria-label` (ADR 036, #26).
+- `docs/roadmap.md`, "Where Janela Is Going": what 1.0 means, which open issues are in it, and what is deliberately not coming. Three claims that can be checked rather than a feature count, since ADR 001 rules out a 1.0 measured against what a commercial BI tool ships: the public surface stops moving, a pane can be read, and the doctor can be trusted. It ships in the gem and renders on the demo at `/docs/roadmap`, because a reader who has to open an issue tracker to find out where a library is going has been told to do the maintainer's filing. It carries no dates on purpose, so that it can only ever be wrong about substance (ADR 037).
+
+### Changed
+
+- **Breaking.** `Janela.parent_controller=` raises when the assignment cannot take effect. The superclass of `Janela::ApplicationController` is resolved once, the first time the class loads, so naming a different controller after that did nothing at all: dashboards kept inheriting whatever was named first, and the host's authentication and `policy_scope` were not the ones it had written. Nothing said so. Set it in `config/initializers/janela.rb`, which runs before anything can load a Janela controller; `config.to_prepare` and `config.after_initialize` are both too late, and the README's own layout recipe is a `to_prepare` block that loads the controller. Naming the controller Janela already inherits is still allowed, since nothing is being asked for (ADR 035, #38).
+- **The class names only Janela's own pages use are no longer public API.** ADR 016 said "the class names are public API", which read literally promised that `janela-card`, `janela-crumb`, `janela-flash`, `janela-button`, `janela-form` and the rest of the engine's own chrome would never be renamed without an upgrade note. That was a promise made to nobody about markup only the engine renders, and it made Janela's own pages harder to change than the library they serve. They are scoped under `janela-page`, which only the engine's layout sets, so they cannot reach your pages, and they may now change in any release. Everything a host's own markup contains, the grid scale and the pane primitives, is the contract and is unchanged: `docs/theming.md` lists it (ADR 036).
+
+### Fixed
+
+- Janela believes only the definitions Janela built. `Janela::Model` is extended onto every ActiveRecord model, so `janela` is a question any of them can answer, and an application whose own model defines a class method by that name wins the collision, as Ruby says it should. Janela treated anything truthy that came back as a definition: `rails janela:doctor` raised `NoMethodError: undefined method 'dimensions' for an instance of String`, a named subclass of that model was registered so `/dashboards/<its route key>/...` resolved, and `Janela.definitions` handed out a value that was not a definition to anything iterating it, such as a form offering a choice of model. Nothing about your own method changes; Janela ignores it now instead of choking on it. A *column* named `janela` was never affected either way, because an attribute is an instance method and this is a class method (#54, found while investigating #12).
+
+- `rails janela:doctor`'s `through-dimensions-without-an-allowlist` reported once per dimension and once per class inheriting a declaration, where there is only ever one allowlist to write. Two dimensions reading through the same association produced two findings whose suggested lines contradicted each other, `%w[region]` and `%w[name]`, so pasting both kept the second and silently lost the first; an STI family produced a copy of each per subclass, since a subclass shares its parent's associations. It is now one finding per associated class, naming every column that class needs and every dimension that wants one, with a line that allows all of them. A subclass that reflects an association its parent does not still gets a finding of its own, because that is a different fix (#44).
+- `rails janela:doctor` checked whether your controller *defines* `policy_scope` rather than whether calling it works, so a Pundit host with no policy for Janela's own models got a clean report and a `Pundit::NotDefinedError` on every dashboard request. Pundit defines `policy_scope` the moment it is included, whether or not the model has a policy, so for the commonest authorisation library those are different questions. `unscoped-reads` now makes the call Janela makes, against `Janela::Frame` and `Janela::Snapshot`, and reports a raise as an error quoting your own exception, which names the policy to write. ADR 032 called this check "exact: the method is defined or it is not"; ADR 035 supersedes that. Its other claim stands: Pundit raises rather than leaking, so nothing was ever exposed (ADR 035, #51).
+- `frames-nobody-will-own` and `snapshots-nobody-will-see` never fired for any application whose `policy_scope` reaches for the signed in user, which is most of them. Both asked your policy on a controller with no request, where `session`, `params` and `current_user` are unreachable, and a blanket rescue read the resulting exception as "does not filter by owner". The checks now ask the way a request does, so those are empty rather than missing, which is an unauthenticated visitor and the right thing for a check to ask about. Expect findings that were always true and never printed (ADR 035).
+- Every check about your controller read `Janela.parent_controller`, the setting, rather than `Janela::ApplicationController.superclass`, what Janela actually inherits. When a host named a parent controller too late the two differed, and the doctor reported on a class that was not in the chain, including the sentence "Janela's controllers inherit X" about a class it does not (ADR 035, #38).
+- `hardcoded-disallowed-predicates` reported an error saying a file filters a model, having only found the dimension's name followed by a predicate somewhere under `app`, `config` or `lib`. An unrelated model's Ransack call, a comment warning against the predicate, and a key in a locale file all read the same to it, and a host was told an error about code that had nothing to do with Janela. It is now a warning, says the file *mentions* the key, and admits that it cannot tell which model a match belongs to. It also reports once per `janela` declaration rather than once per class inheriting it, so an STI family no longer multiplies the same finding (ADR 021, ADR 035, #51, part of #44).
+
 ## [0.7.0] - 2026-09-22
 
 ### Added
@@ -169,6 +192,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.8.0]: https://github.com/retail-tasker/janela/releases/tag/v0.8.0
 [0.7.0]: https://github.com/retail-tasker/janela/releases/tag/v0.7.0
 [0.6.0]: https://github.com/retail-tasker/janela/releases/tag/v0.6.0
 [0.5.0]: https://github.com/retail-tasker/janela/releases/tag/v0.5.0

data/README.md

@@ -27,7 +27,7 @@ Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has t
 
 ```ruby
 # Gemfile
-gem "janela", "~> 0.7"
+gem "janela", "~> 0.8"
 ```
 
 ```ruby
@@ -428,9 +428,9 @@ It is *prepended* so it runs before any filter on your `ApplicationController` t
 
 Your own route helpers work in there. Janela is an isolated engine, so a bare `new_session_path` would normally resolve against Janela's routes and raise, and this bites any host code that generates a URL while inside the engine: an authentication concern, a `rescue_from` that redirects, an `after_action`. Janela forwards the route helpers it does not define itself to your application, so they behave as they do everywhere else (ADR 022). Two things to know. A name Janela also uses means Janela's in here, and `main_app.frames_path` says yours. And `url_for(@record)` resolves polymorphically with no name to forward, so that one still needs `main_app.`.
 
-Scoping is automatic when you use Pundit: `Janela::ApplicationController` calls `policy_scope(model)` if your `ApplicationController` defines it, and raises `Janela::Unscoped` if it does not, rather than reading everything on the strength of an omission (ADR 032). An application with nothing to hide answers `def policy_scope(model) = model.all` once and is done; `bin/rails janela:doctor` reports the absence as `unscoped-reads` before a visitor finds it. 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.
+Scoping is automatic when you use Pundit: `Janela::ApplicationController` calls `policy_scope(model)` if your `ApplicationController` defines it, and raises `Janela::Unscoped` if it does not, rather than reading everything on the strength of an omission (ADR 032). An application with nothing to hide answers `def policy_scope(model) = model.all` once and is done; `bin/rails janela:doctor` reports the absence as `unscoped-reads` before a visitor finds it. 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. The doctor checks that by making the call rather than by looking for the method, because Pundit defines `policy_scope` the moment it is included and raises only when the model has no policy, so the two are different questions (ADR 035). `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.
+**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 what rows a scheduled snapshot freezes.
 
 ### The pages Janela serves
 
@@ -497,13 +497,13 @@ Janela ships the load-bearing core of a BI tool and nothing else. The reasoning
 - **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.
+- **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. The job will not freeze a scope you have not named (ADR 034).
 
 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.7.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, STI subclasses, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.8.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, STI subclasses, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests, with the classes a theme may target documented in [Theming Janela](docs/theming.md). Not yet built: a visual editor, drill-down on time panes, other chart types. [Where Janela Is Going](docs/roadmap.md) says what 1.0 means and which of these are in it; open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,69 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.7.0 to 0.8.0
+
+Two steps, each only if it applies to you: one if you name a parent
+controller, one if you wrote CSS against Janela's own pages. The doctor
+also starts reporting things it always should have; that needs nothing
+from you but a read.
+
+**1. Set `Janela.parent_controller` in an initializer, if you set it.**
+
+`Janela::ApplicationController` resolves its superclass once, the first
+time the class loads. Naming a different one after that did nothing at
+all, in silence, so your dashboards kept inheriting whatever was named
+first and your authentication and `policy_scope` were not the ones you
+wrote. It raises now rather than being ignored.
+
+```ruby
+# config/initializers/janela.rb   <- runs before anything can load it
+Janela.parent_controller = "Admin::BaseController"
+```
+
+Too late, all of them: `config.to_prepare`, `config.after_initialize`,
+an `initializer` block ordered after `load_config_initializers`, and
+anything that runs once the application is serving. The README's own
+recipe for giving Janela a layout is a `to_prepare` block that loads the
+controller, so if you use that, the initializer has to come first, and
+it does.
+
+Naming the controller Janela already inherits is still allowed, because
+nothing is being asked for.
+
+**2. Check any CSS you wrote against Janela's own pages.**
+
+ADR 016 said "the class names are public API", which read literally
+promised that `janela-card`, `janela-crumb`, `janela-flash`,
+`janela-button`, `janela-form` and the rest of the chrome the engine
+renders on *its own* pages would never be renamed without an entry here.
+That was a promise made to nobody about markup only the engine draws,
+and it made Janela's own pages harder to change than the library they
+serve.
+
+They are now scoped under `janela-page`, which only the engine's own
+layout sets, so they cannot reach your pages, and they may change in any
+release. Nothing is renamed in this release, so nothing breaks today. If
+you styled Janela's own pages by targeting those class names, that
+stylesheet is no longer standing on a contract.
+
+What *is* the contract is unchanged: everything your own markup
+contains, the grid scale and the pane primitives.
+[docs/theming.md](docs/theming.md) lists all of it, the three custom
+properties that carry `janela.css`, and what a theme is expected to
+leave alone.
+
+**What to expect from the doctor.** Two checks that could not fire for
+an application whose `policy_scope` reaches for the signed in user now
+do, so `bin/rails janela:doctor` may report findings that were always
+true and never printed. `unscoped-reads` calls your `policy_scope`
+rather than looking for the method, which catches a Pundit application
+with no policy for `Janela::Frame` or `Janela::Snapshot`: that used to
+pass the doctor and raise on every request.
+`hardcoded-disallowed-predicates` drops to a warning and says a file
+*mentions* a key rather than claiming it filters a model, because it
+only ever grepped for the name.
+
 ## 0.6.0 to 0.7.0
 
 Janela has stopped guessing what may be read, in the two places it used

data/app/assets/stylesheets/janela.css

@@ -87,6 +87,27 @@ table.janela-pane button[aria-pressed="true"] { background: var(--janela-accent)
 
 canvas.janela-chart { width: 100% !important; max-height: 20rem; }
 
+/* A host whose own markup already says what a pane is puts this on any
+   ancestor, and the caption and the single value's label stop being drawn
+   without leaving the accessibility tree. Hidden rather than removed on
+   purpose: a caption is the table's accessible name, so display: none would
+   land a screen reader on a grid of numbers with nothing to say what they
+   measure. The rule ships here because that is easy to get wrong and every
+   host would otherwise write it (ADR 036, #26). A chart pane needs nothing:
+   its title was only ever an aria-label. */
+.janela-own-headings table.janela-pane caption,
+.janela-own-headings .janela-value-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
 /* Janela's own pages (ADR 013). Scoped to a class the engine's layout sets,
    so including this stylesheet changes nothing about a host's own pages. */
 .janela-page {

data/docs/decisions/032-janela-will-not-read-a-model-it-cannot-scope.md

@@ -2,6 +2,7 @@
 Date: 2026-09-20
 Status: Accepted
 Related: ADR 002, ADR 004, ADR 015, ADR 019, ADR 021, ADR 025
+Superseded in part by: ADR 035
 Triggers:
   - deciding what Janela should do when a host has configured nothing
   - adding a hook a host answers by defining a method

data/docs/decisions/035-a-check-does-what-janela-does-or-says-what-it-saw.md

@@ -0,0 +1,262 @@
+---
+Date: 2026-09-22
+Status: Accepted
+Related: ADR 002, ADR 019, ADR 021, ADR 025, ADR 031, ADR 032, ADR 033
+Triggers:
+  - adding a check to janela:doctor, or changing what one reads
+  - a check that reports nothing for a host that has a real problem
+  - a check that reports something about code a host did not write
+  - rescuing an exception raised by a host's own code
+  - reading Janela.parent_controller anywhere
+  - assigning Janela.parent_controller outside an initializer
+Topics: tooling, configuration, authorisation, host-integration, security, releases
+---
+
+# ADR 035: A Check Does What Janela Does, or It Says What It Saw
+
+## Context
+
+Three reports arrived within a day of 0.7.0, two of them from a real host
+integration rather than from this repository (#51, #38). They read as
+three unrelated bugs in `janela:doctor` and they are one.
+
+Every failing check reads a **proxy** for the thing it reports on, and
+then words the finding as though it had checked the thing.
+
+| Check | Reads | Asserts |
+| --- | --- | --- |
+| every controller check | `Janela.parent_controller`, the setting | "Janela's controllers inherit X" |
+| `unscoped_reads` | whether a method is defined | "defines no policy_scope, so every pane will raise" |
+| `disallowed_uses` | a string anywhere under `app`, `config`, `lib` | "this file filters this model on this key" |
+| `scope_filters_by_owner?` | an exception, swallowed | "does not filter by owner" |
+
+### Measured
+
+All against the demo, plus Pundit 2.5.2 installed outside the bundle so
+it could be run rather than read. ADR 032 verified Pundit by reading, and
+that is the half of it that turned out wrong.
+
+**A Pundit host with no policy for Janela's own models.** This is the
+configuration the README treats as the common case, minus one file.
+
+```
+policy_scope defined on the host?  true
+a request (Janela.scope, the real path):
+  Pundit::NotDefinedError: unable to find scope `Janela::FramePolicy::Scope`
+the doctor's entire output:
+  WARNING (unauthenticated-endpoints): no authentication filter found
+```
+
+Every dashboard raises. The doctor says nothing about it.
+
+**A host that names its parent controller too late.** Measured at
+development boot, `config/initializers/*.rb` is safe because `to_prepare`
+runs after all of them, `config.after_initialize` is already too late,
+and within `to_prepare` it depends on registration order against anything
+else that touches the controller. The README's own layout recipe is such
+a block.
+
+```
+host named:            SecureHost (authenticated, policy_scope -> none)
+Janela actually uses:  ApplicationController
+doctor says:           WARNING ... no authentication filter found on SecureHost
+                       "Janela's controllers inherit SecureHost, so they are as public as it is"
+a pane served:         $375.00 (200)
+```
+
+That quoted sentence is false at the moment it is printed.
+
+**A predicate the host never wrote.** One planted file that does not
+mention `Order`:
+
+```
+ERROR (hardcoded-disallowed-predicates): Order does not allow status_cont
+  app/models/shipment.rb filters Order on status_cont
+ERROR (hardcoded-disallowed-predicates): WholesaleOrder does not allow status_cont
+```
+
+Twice, because #44 repeats a finding per STI class. What trips it, one
+case at a time:
+
+| Planted | Result |
+| --- | --- |
+| a ransack call on an unrelated model | 2 errors |
+| `def status_changed? = true` | nothing |
+| `def status_count = 0` | nothing |
+| `# never filter on status_cont, it is not allowed` | 2 errors |
+| `status_matches:` as a key in `config/locales/en.yml` | 2 errors |
+
+Ordinary identifiers are safe, so the predicate detection is doing real
+work and this is not a bare grep. A comment warning against the predicate
+still reports that you use it, at `error`, the loudest thing the doctor
+can say.
+
+**The worst of it, which nobody had reported.** The two owner checks call
+a host's `policy_scope` on `parent.allocate`, an instance with no
+request, and rescue everything:
+
+```
+RealisticOwnerHost     scope_filters_by_owner? -> false   raised: NameError
+SessionlessOwnerHost   scope_filters_by_owner? -> true    raised: no
+
+does frames-nobody-will-own fire?
+RealisticOwnerHost     no finding
+SessionlessOwnerHost   ... scopes frames by owner but defines no janela_frame_owner
+```
+
+`RealisticOwnerHost` differs from the other by one line: its
+`policy_scope` reaches for the signed in user through the session, which
+is what every authentication library does. On an allocated controller
+`session` is nil, the call raises `NameError`, the blanket rescue turns
+that into "does not filter by owner", and the check goes quiet.
+
+So `frames-nobody-will-own` and `snapshots-nobody-will-see` do not fire
+for any host with real authentication. The second of those shipped in
+0.7.0 yesterday, written because the case bit five times in one
+afternoon. It cannot fire for the hosts that need it.
+
+**Why this repository did not catch it.** The demo's `policy_scope` reads
+`Current.tenant`, a thread local, where a host reads the session. It is
+the #46 lesson a third time: a stand in wired differently to the
+documentation cannot catch a bug in the documentation's wiring. That is
+already a hard constraint in `/jan-orient`, and it did not extend to
+"wired differently to how hosts actually work".
+
+### The thing that makes this fixable
+
+An allocated controller can be given a request:
+
+```
+allocate, no request:                  NameError: undefined method 'session' for nil
+allocate + ActionDispatch::TestRequest, policy present:  ok, SELECT "janela_frames".*
+allocate + ActionDispatch::TestRequest, policy absent:   Pundit::NotDefinedError
+```
+
+A correctly wired host succeeds. A host missing a policy raises the same
+error its visitors get. The check can tell them apart without knowing
+that Pundit exists, which ADR 002 requires.
+
+### Options considered
+
+**Keep reading, and hedge in the prose.** Cheap, and leaves both owner
+checks dead and the Pundit gap unreported. A check that cannot fire is
+not improved by better wording.
+
+**Depend on Pundit so a check can name `Pundit::NotDefinedError`.**
+Rejected on ADR 002: authorisation here is a hook, not a dependency, and
+a doctor that knows one library's exception classes is a doctor that is
+wrong about every other library.
+
+**Build a real request through the integration stack.** Heavier than
+`ActionDispatch::TestRequest` and no more faithful. The controller never
+processes an action here; it is asked one question.
+
+**Statically resolve the receiver of a `ransack` call** so
+`disallowed_uses` can attribute a match honestly. That is a parser, for
+one advisory check, and it would still miss a call through a variable.
+
+**Remove `disallowed_uses`.** Seriously considered. It was written for
+the 0.5.0 upgrade (ADR 025) to help hosts find filters the predicate
+narrowing broke, two releases ago, and its noise is now measured. Kept,
+because a host upgrading from 0.4.x still exists and the check is
+salvageable as an observation.
+
+**Make `Janela.parent_controller=` raise when the assignment cannot take
+effect.** Chosen, below, after being weighed against a doctor check that
+names the disagreement instead.
+
+## Decision
+
+**A check does what Janela does, or it says what it saw.** Where Janela
+calls a method, the check calls the same method. Where Janela resolves a
+constant, the check resolves the same constant. Where a check cannot do
+what Janela does, it reports its observation and not a conclusion it did
+not earn.
+
+That is the rule the rest of this follows from.
+
+**A check that calls host code calls it the way a request does.** The
+controller is given an `ActionDispatch::TestRequest`, so a host's
+`policy_scope` can reach `session`, `params` and `current_user` and find
+them empty rather than absent. Empty is the honest condition: it is an
+unauthenticated visitor, which is exactly who a doctor should be asking
+about. Measured above to separate a wired host from an unwired one with
+no knowledge of the host's library.
+
+**An exception from host code is reported, never swallowed.**
+`scope_filters_by_owner?` collapses "raised" and "returned something
+unfiltered" into `false`, and both owner checks are silent as a result.
+The question becomes three-valued: filtered, not filtered, or raised. A
+raise is a finding in its own right, quoting the exception class and
+message, because Janela is about to do the same call on every request.
+
+**`unscoped_reads` calls `policy_scope` against `Janela::Frame` and
+`Janela::Snapshot`.** Those two are always present and are what the
+engine's own pages read first, so a host that cannot be asked about them
+has a broken dashboard whatever else is true. It stops testing for the
+method. **ADR 032's claim that this check is "exact: the method is
+defined or it is not, and that is the whole contract" is wrong and this
+supersedes it.** The contract is that calling it returns a relation.
+ADR 032's other claim, that a Pundit host missing a policy is not
+exposed, stands: Pundit raises rather than leaking, so no data is at
+risk and this is a diagnosis failure rather than a safety one.
+
+**Every check reads `Janela::ApplicationController.superclass`, not
+`Janela.parent_controller`.** The superclass is what Janela uses; the
+setting is what a host asked for, and the two can differ (#38). One line,
+four checks, and it removes the possibility of printing "Janela's
+controllers inherit X" about a class that is not in the chain.
+
+**`Janela.parent_controller=` raises when the assignment cannot take
+effect and names a different class.** Assigning before the controller
+loads is fine, and reassigning the value already resolved is fine, so the
+raise fires only for the case that is silently broken today. `Janela` can
+tell without forcing the autoload it is asking about, through
+`autoload?` and `const_defined?`. This is ADR 032's trade again, loud once
+at the exact wrong line rather than quiet forever, and it is why no new
+doctor check is added for #38: preventing the state is better than
+reporting it, and two mechanisms for one problem is what ADR 001 declines.
+It does not contradict ADR 032's refusal to raise at boot, which was
+about raising for a host that had done nothing wrong.
+
+**`disallowed_uses` says what it saw.** Janela never reads a host's
+source, so this check cannot do what Janela does and falls to the other
+half of the rule. It reports that a file *mentions* a key the model does
+not allow, rather than that the file *filters* that model, drops from
+error to warning, and reports once per declaration rather than once per
+inheriting class. It stays a hint to grep rather than a claim about the
+host's code.
+
+## Consequences
+
+- Two checks that could not fire for a host with real authentication
+  begin firing. Expect the first hosts to run this to see findings that
+  were always true and never printed.
+- A check now runs a host's own `policy_scope` during `janela:doctor`.
+  That is host code executing in a rake task, which it was already, but
+  deliberately rather than by accident. The contract for `policy_scope`
+  is that it returns a relation, so it reads; a host whose implementation
+  writes something has a larger problem than this check.
+- **A host assigning `Janela.parent_controller` too late goes from
+  silently ignored to an exception at boot.** Breaking, so it goes in
+  `UPGRADING.md` with the three places that are too late and the one that
+  is not (ADR 015). Most hosts assign in an initializer and see nothing.
+- `with_parent_controller` in this repository's own doctor tests works by
+  assigning after load, which is the very thing the setter now refuses.
+  Those tests have to set up their scenarios by another route, and they
+  were relying on the bug: they only worked because the checks read the
+  setting rather than the chain.
+- `disallowed_uses` dropping to warning means a host who genuinely broke
+  a filter is told less loudly. Accepted: it was error severity on
+  evidence it did not have, and a warning that is usually right beats an
+  error that is sometimes about a comment.
+- #44 is narrowed rather than closed. Reporting once per declaration
+  fixes the duplication in this one check; the rest of the model checks
+  still repeat per STI subclass.
+- The demo has to gain a host whose `policy_scope` reaches through the
+  session, because nothing else in this repository would have caught the
+  dead owner checks. That is the #46 lesson applied rather than restated.
+- What would change this decision: a host reporting that
+  `ActionDispatch::TestRequest` is not enough for their authorisation to
+  run, at which point the question is whether a check should be asking at
+  all rather than how hard it should try.

data/docs/decisions/036-janela-publishes-what-a-theme-may-target.md

@@ -0,0 +1,171 @@
+---
+Date: 2026-09-22
+Status: Accepted
+Related: ADR 011, ADR 015, ADR 016, ADR 021, ADR 023
+Triggers:
+  - adding a class, a custom property or a rule to either stylesheet
+  - deciding whether a piece of look belongs to the gem or to a theme
+  - writing a theme, or reading one somebody else wrote
+  - renaming anything a stylesheet targets
+  - adding a helper that renders markup a host will style
+Topics: styling, theming, host-integration, naming, public-api, releases
+---
+
+# ADR 036: Janela Publishes What a Theme May Target, and Vitral Is Only One
+
+## Context
+
+ADR 023 split the styling in two: `janela.css` is structure, frozen and
+boring, and `vitral.css` is taste, free to move. That was the right cut
+and it has held for the theme. It no longer describes the other file.
+
+### What `janela.css` actually contains
+
+Counted by where each name is used, in the engine's own views and in the
+demo standing in for a host:
+
+| Group | Names | Where they appear |
+| --- | --- | --- |
+| The grid scale | `janela-cols-1..12`, `janela-gap-0..8`, `janela-span-1..12` | chosen by a frame's own integers (ADR 016) |
+| Pane primitives | `janela-frame`, `janela-pane`, `janela-value`, `janela-value-label`, `janela-value-number`, `janela-chart`, `janela-empty`, `janela-error` | in a host's own pages, wherever a pane is rendered |
+| The engine's own chrome | `janela-card`, `janela-button`, `janela-crumb`, `janela-flash`, `janela-page`, `janela-form`, `janela-field`, `janela-heading`, `janela-subheading`, `janela-list`, `janela-list-row`, `janela-list-name`, `janela-actions`, `janela-exit`, `janela-hint`, `janela-muted`, `janela-danger`, `janela-errors` | only Janela's own pages: 2 to 6 engine views each, and none in the demo but `janela-form`, twice |
+
+The third group is a small UI kit for pages a host may never visit. ADR
+016 said "the class names are public API", meaning renaming one is
+breaking and belongs in `UPGRADING.md`. Applied to the third group that
+is a promise made to nobody, about markup only the engine renders, which
+makes the engine's own pages harder to change than the thing the gem is
+for.
+
+### A theme other than vitral already works
+
+`Janela.theme` is one line in the engine's layout,
+`stylesheet_link_tag Janela.theme if Janela.theme.present?`, so it
+resolves any stylesheet name against the host's own asset paths. Measured
+against Janela's own layout:
+
+```
+"vitral"         -> janela.css + vitral.css
+"application"    -> janela.css + the host's own application.css
+"no_such_theme"  -> raises, "The asset 'no_such_theme.css' was not found in the load path"
+nil              -> janela.css alone
+```
+
+So somebody else's skin needs nothing built. What it needs is to know
+what it may target, and today nothing says. A theme author reads
+`vitral.css` to find out, which makes every name vitral happens to use
+into an accidental interface, and makes the three groups above
+indistinguishable.
+
+### Four open issues are the same question
+
+`#26` a caption that cannot be hidden without losing it for screen
+readers, `#29` inter-pane layout being entirely the host's problem, `#30`
+a categorical palette, `#31` a single value pane with no typography and
+no way to say how prominent it is. Each one asks where a piece of look
+belongs, and each has been answered one at a time so far, which is how a
+split stops meaning anything: `janela.css` grew a UI kit that way,
+without anyone deciding it should.
+
+### Options considered
+
+**Leave it, and decide each issue as it comes.** What has been happening.
+It produced the drift above and gives a theme author nothing to read.
+
+**A third stylesheet**, splitting the engine's own chrome out of
+`janela.css`. Tempting and rejected on ADR 023's own consequence: a third
+file is a third thing every Sprockets host has to declare for
+precompilation, and #14 says the second one is already a rough edge. The
+problem is a missing promise, not a missing file.
+
+**Rename the chrome to mark it private**, `janela-internal-card` or
+similar. Rejected: the rename is itself the breaking change it is trying
+to make unnecessary, paid now for a benefit that is only cosmetic. Saying
+which names are the contract costs nothing and is just as clear.
+
+**Move the pane primitives into the theme**, so a host with no theme gets
+unstyled panes. Rejected: a pane has to be legible on install, which is
+ADR 016's founding reason, and #26 is the sharp case, since hiding a
+caption accessibly is correctness rather than taste and a host that never
+opts into a theme still needs it.
+
+## Decision
+
+**Janela publishes the hooks; a theme supplies the taste. What a theme
+may target is written down, and what is not written down is Janela's own
+chrome.**
+
+**Three layers, named, in two files.** No new stylesheet.
+
+- **The grid scale and the pane primitives are the contract.** These are
+  what a host's own pages contain and what a theme targets. Renaming one
+  is breaking and goes in `UPGRADING.md` with the doctor taught to find
+  the old name (ADR 015).
+- **The engine's own chrome is not the contract.** The classes only
+  Janela's own views render may change in any release. A host restyling
+  Janela's own pages is welcome to target them and should expect to
+  revisit it, which is the honest version of what was already true.
+- ADR 016's "the class names are public API" is **narrowed, not
+  superseded**: it is true of everything a host's markup contains, and
+  was never meant as a promise about the engine's breadcrumbs.
+
+**`docs/theming.md` carries the contract**, because a theme author is not
+going to read an ADR to find a class list. It names the two layers, every
+class in them, every custom property, and what a theme is expected to
+leave alone. Shipped in the gem beside the other docs.
+
+**A theme is any stylesheet the host names, and vitral is one of them.**
+Nothing more is built for this: `Janela.theme = "midnight"` already
+resolves against the host's asset paths, and a name that does not resolve
+already raises rather than failing quietly. What changes is that this is
+documented and supported rather than merely true, so a third party can
+publish a theme against a contract instead of against whatever vitral
+happens to do this month.
+
+**Where a new piece of look goes.** The rule that answers the four open
+issues without arguing each one separately:
+
+- Something a pane needs in order to be correct or legible on install is
+  a **hook**, and belongs in `janela.css` on the contract. A caption that
+  is announced but not seen is this (#26).
+- Something that is a choice about appearance is **taste**, and belongs
+  in a theme. A categorical palette is this (#30).
+- Something a host arranges is **layout**, and belongs in the grid scale
+  as an integer that selects a rule, never as a value interpolated into a
+  style attribute (ADR 016). Prominence for a single value pane is this
+  (#31), and so is inter-pane layout (#29).
+
+Where a feature has both halves, the hook ships in `janela.css` and the
+taste in the theme. A palette is the clean example: the class that marks
+which series a mark belongs to is a hook, and the colours it resolves to
+are a theme's.
+
+**Vitral stays in this repository**, and stays one theme among any
+others. It is the reference implementation of the contract, which is a
+reason to keep it here rather than to privilege it: if a rule cannot be
+written against the published names, the contract is wrong.
+
+## Consequences
+
+- A theme author has something to read, and a theme written against
+  `docs/theming.md` keeps working across releases in a way one written
+  against `vitral.css` never could.
+- The engine's own pages get easier to change, because their markup stops
+  being an interface. That is a real loosening: a host that today targets
+  `janela-card` will find it moves one day, and the doc says so rather
+  than leaving them to discover it.
+- Writing the contract down means reading every class in both files once
+  and deciding which side it is on. That is the work, and it is the point.
+- **Not decided here: whether Vitral grows to answer #29, #30 and #31.**
+  This says where each half of each of those belongs; it does not commit
+  to building them, and a component library large enough to lay out a
+  host's page is its own decision against ADR 001's preference for
+  staying small enough to fork.
+- A theme is still linked only into Janela's own layout. A host wanting
+  the look on its own pages links the stylesheet itself and uses the
+  theme's public classes, exactly as ADR 023 decided. The contract does
+  not change that asymmetry, it explains it.
+- What would change this decision: the engine's own chrome turning out to
+  be something hosts genuinely restyle, in reports rather than in
+  anticipation, at which point it has earned the promise this declines to
+  make and should be moved onto the contract deliberately.