janela 0.7.0 → 0.9.0

data/docs/theming.md

@@ -0,0 +1,179 @@
+---
+Topics: styling, theming, css, host-integration
+---
+
+# Theming Janela
+
+Janela publishes the hooks; a theme supplies the taste. This page is the
+contract: the class names and custom properties the engine renders, which
+your own stylesheet or somebody else's theme may target, and which will
+not change without an entry in `UPGRADING.md` (ADR 036).
+
+Two stylesheets ship in the gem.
+
+```erb
+<%= stylesheet_link_tag "janela" %>   <%# the hooks, and enough style to be legible %>
+<%= stylesheet_link_tag "vitral" %>   <%# optional: one theme, stained glass %>
+```
+
+`janela.css` is not a look. It is the grid, the pane's own markup and
+enough base styling that a table does not run its label into its number.
+Everything decorative is a theme's, and vitral is one theme rather than
+the theme.
+
+## The contract
+
+### Custom properties
+
+Three, and setting them moves everything that depends on them.
+
+| Property | Default | What it does |
+| --- | --- | --- |
+| `--janela-space` | `0.25rem` | The base unit of the whole spacing scale. Every gap and padding is a multiple of it. |
+| `--janela-line` | `rgba(128, 128, 128, 0.3)` | Rules between rows, borders on cards and fields. |
+| `--janela-accent` | `rgb(54, 162, 235)` | A selected value, a hovered card. |
+
+```css
+:root {
+  --janela-space: 0.3rem;
+  --janela-accent: #7c3aed;
+}
+```
+
+### The grid
+
+A frame's stored integers choose these. Nothing an analyst types reaches
+CSS as a length: the number selects a rule that is already written
+(ADR 016).
+
+| Class | Range |
+| --- | --- |
+| `janela-frame` | the grid container itself |
+| `janela-cols-N` | 1 to 12 |
+| `janela-gap-N` | 0 to 8, multiplied by `--janela-space` |
+| `janela-span-N` | 1 to 12, on a pane |
+
+Below `40rem` the grid collapses to one column. That is in the
+stylesheet rather than in the data, because a dashboard nobody can read
+on a phone is not a choice worth offering.
+
+### The pane
+
+What `janela_pane` and `janela_frame` put in your own pages. These are
+the names a theme spends most of its time on.
+
+| Class | On | Rendered when |
+| --- | --- | --- |
+| `janela-pane` | `<table>`, `<p>`, `<figure>` or `<div>` | every pane, whatever the renderer |
+| `janela-value` | `<p>` | a single value pane |
+| `janela-value-label` | `<span>` | its caption |
+| `janela-value-number` | `<strong>` | the number itself |
+| `janela-chart` | `<canvas>` | a bar or line pane, inside its `<figure>` |
+| `janela-chart-title` | `<figcaption>` | its caption (ADR 042) |
+| `janela-empty` | `<p>` | a pane whose query returned nothing |
+| `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 |
+
+A table pane renders a `<caption>` and a chart pane a `<figcaption>`,
+each its own accessible name; the chart's canvas points to its
+figcaption with `aria-labelledby` rather than repeating the string in
+`aria-label`, so the two cannot drift apart (ADR 042).
+
+### Hiding a heading you already wrote
+
+Put `janela-own-headings` on any ancestor and a table's caption, a
+single value's label and a chart's title are hidden from sight while
+staying in the accessibility tree.
+
+```erb
+<div class="janela-own-headings">
+  <h3>Revenue by status</h3>
+  <%= janela_pane Order, :revenue, by: :status %>
+</div>
+```
+
+Use it when your own markup already says what the pane is, so the text
+is not on screen twice. It hides rather than removes on purpose: a pane
+with no visible caption still needs its accessible name, so a screen
+reader lands on a grid of numbers with nothing to say what they
+measure. `display: none` would do that, which is why this rule ships
+here rather than being left for each host to write.
+
+## What is not the contract
+
+`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.
+
+**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
+pages to match your application, and expect to revisit it after an
+upgrade; or point `Janela.theme` at a stylesheet of your own, below.
+
+## Writing a theme
+
+A theme is any stylesheet, named once:
+
+```ruby
+# config/initializers/janela.rb
+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 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
+have embedded yourself, link the stylesheet there too. The asymmetry is
+deliberate: Janela is an isolated engine and does not write your layout
+(ADR 011).
+
+A theme targets the contract above and nothing else. If it cannot be
+written that way, the contract is missing something, which is worth an
+issue rather than a workaround.
+
+## Vitral
+
+The theme the gem ships. A *vitral* is a stained glass window: each pane
+holds one of five colours, dark leading runs between them, and the light
+comes from behind.
+
+```erb
+<%= stylesheet_link_tag "vitral" %>
+<body class="vitral">
+```
+
+Nothing is repainted until that class is present, so linking the
+stylesheet can never be the thing that broke a page.
+
+**Its own public classes**, so the page around a dashboard can be made of
+the same window: `vitral-pane`, `vitral-panes`, `vitral-button`,
+`vitral-button-primary`, `vitral-lattice`.
+
+**Retheme it from its custom properties** rather than by forking it. The
+light is `--vitral-light-cobalt`, `-teal`, `-amber`, `-rose`, `-violet`;
+the glass is `--vitral-pane-1` through `-5`; the leading is
+`--vitral-came`; and `--vitral-ink`, `--vitral-muted`, `--vitral-ground`,
+`--vitral-radius`, `--vitral-shadow` and `--vitral-blur` do what they
+say.
+
+```css
+:root {
+  --vitral-pane-1: rgba(120, 60, 200, 0.3);
+  --vitral-came: #1b1b1b;
+}
+```
+
+**It works without JavaScript.** Janela's own pages load none (ADR 011),
+so the stained glass is CSS and the lattice that leans toward the pointer
+is a separate optional controller. Reduced motion, reduced transparency
+and increased contrast each fall back to a still, solid window, and so
+does a browser without `backdrop-filter`.
+
+`test/dummy` has a live page at `/vitral` showing all of it against real
+panes.

data/lib/janela/definition.rb

@@ -6,8 +6,15 @@ module Janela
 
     attr_reader :model, :measures, :dimensions
 
+    # The class whose janela block this is, which a subclass shares with the
+    # parent it inherited from. A subclass gets a definition of its own, so
+    # anything reporting on a declaration rather than on a model groups by
+    # this or says the same thing once per class in an STI family (ADR 035).
+    attr_accessor :declared_by
+
     def initialize(model, &block)
       @model = model
+      @declared_by = model
       @measures = {}
       @dimensions = {}
       @block = block
@@ -19,7 +26,7 @@ module Janela
     # the queries they run are its own, because ActiveRecord adds the type
     # condition to a relation on the subclass (ADR 031).
     def for(model)
-      self.class.new(model, &@block)
+      self.class.new(model, &@block).tap { |inherited| inherited.declared_by = declared_by }
     end
 
     def measure(name, **aggregate)
@@ -90,6 +97,14 @@ module Janela
       dimensions.values.filter_map(&:through).map(&:to_s).uniq
     end
 
+    # A filter the host fixed for a render (ADR 040), applied as its own
+    # condition before the reader's, so the reader's can only narrow inside
+    # it. The same bounds as any filter: declared dimensions, ADR 025's
+    # predicates and value limit.
+    def narrow(relation, conditions)
+      filter(relation, conditions.to_h)
+    end
+
     private
       def filter(relation, params)
         return relation if params.empty?

data/lib/janela/doctor.rb

@@ -134,22 +134,43 @@ module Janela
 
       # Ransack's allowlist is per class, so a dimension read through an
       # association needs the associated model to allow the attribute too.
+      #
+      # Grouped by the allowlist that has to be written rather than by the
+      # dimension that led here, because that is what the finding is about and
+      # there is one of it. Two dimensions reading through the same
+      # association used to produce two findings whose suggested lines
+      # contradicted each other, so a host pasting both kept the second and
+      # silently lost the first; an STI family produced a copy of each per
+      # class, since a subclass shares its parent's associations (#44).
       def through_dimensions_without_an_allowlist
-        janela_models.flat_map do |model|
-          model.janela.dimensions.values.select(&:through).filter_map do |dimension|
+        missing_allowlist_entries.map do |klass, entry|
+          allowed = klass.ransackable_attributes.map(&:to_s)
+          Finding.new(severity: :error,
+            summary: "#{klass} does not allow filtering on #{entry[:columns].sort.to_sentence}",
+            detail: "  Ransack's allowlist is per class, and these read through an association:\n" \
+                    "#{entry[:sources].sort.map { |source| "    #{source}" }.join("\n")}\n" \
+                    "  Add to #{klass}:\n" \
+                    "    def self.ransackable_attributes(_auth_object = nil) = " \
+                    "%w[#{(allowed + entry[:columns].sort).uniq.join(' ')}]")
+        end
+      end
+
+      # Keyed on the associated class rather than on the declaration, because a
+      # subclass may reflect an association its parent does not: two classes
+      # sharing a declaration and an association share a fix, and two that do
+      # not have a fix each. The source list names declaring classes, so an STI
+      # family is one line rather than one per subclass.
+      def missing_allowlist_entries
+        janela_models.each_with_object({}) do |model, missing|
+          model.janela.dimensions.values.select(&:through).each do |dimension|
             association = model.reflect_on_association(dimension.through)
             next unless association
+            next if association.klass.ransackable_attributes.map(&:to_s).include?(dimension.column.to_s)
 
-            allowed = association.klass.ransackable_attributes.map(&:to_s)
-            next if allowed.include?(dimension.column.to_s)
-
-            Finding.new(severity: :error,
-              summary: "#{association.klass} does not allow filtering on #{dimension.column}",
-              detail: "  #{model}'s #{dimension.name.inspect} dimension reads it through " \
-                      "#{dimension.through.inspect}, and Ransack's allowlist is per class. Add to " \
-                      "#{association.klass}:\n" \
-                      "    def self.ransackable_attributes(_auth_object = nil) = " \
-                      "%w[#{(allowed + [ dimension.column.to_s ]).uniq.join(' ')}]")
+            entry = missing[association.klass] ||= { columns: [], sources: [] }
+            entry[:columns] |= [ dimension.column.to_s ]
+            entry[:sources] |= [ "#{model.janela.declared_by}'s #{dimension.name.inspect} dimension, " \
+                                 "through #{dimension.through.inspect}" ]
           end
         end
       end
@@ -158,11 +179,23 @@ module Janela
       # but one written into the host's own Ruby is source like any other
       # identifier this doctor already greps for (ADR 015, ADR 021, ADR 025).
       def hardcoded_disallowed_predicates
-        janela_models.flat_map do |model|
-          model.janela.dimensions.values.flat_map { |dimension| disallowed_uses(model, dimension) }
+        janela_definitions.flat_map do |definition|
+          definition.dimensions.values.flat_map { |dimension| disallowed_uses(definition.declared_by, dimension) }
         end
       end
 
+      # One finding per declaration rather than one per class that inherits it.
+      # An STI family shares its parent's dimensions (ADR 031), so iterating
+      # models multiplied the same finding by the size of the family (#44).
+      def janela_definitions
+        janela_models.filter_map(&:janela).uniq(&:declared_by)
+      end
+
+      # The match is a string in a file, and nothing here establishes that the
+      # file filters this model, or filters anything: a comment warning against
+      # the predicate reads the same as a call. So the finding says what was
+      # seen and admits the limit, and is a warning rather than an error
+      # (ADR 021, ADR 035, #51).
       def disallowed_uses(model, dimension)
         pattern = /\b#{Regexp.escape(dimension.ransack_name)}(_\w+)/
         source_files.flat_map do |file|
@@ -174,10 +207,12 @@ module Janela
 
             key = "#{dimension.ransack_name}_#{predicate}"
             allowed = dimension.allowed_predicates.map { |p| "#{dimension.ransack_name}_#{p}" }
-            Finding.new(severity: :error,
+            Finding.new(severity: :warning,
               summary: "#{model} does not allow #{key}",
-              detail: "  #{file.relative_path_from(@root)} filters #{model} on #{key}, which Janela now " \
-                      "refuses (ADR 025). Allowed here: #{allowed.join(', ')}.")
+              detail: "  #{file.relative_path_from(@root)} mentions #{key}, which Janela refuses on " \
+                      "#{model} (ADR 025). Allowed here: #{allowed.join(', ')}.\n" \
+                      "  This reads your source for the name and cannot tell which model a match\n" \
+                      "  belongs to, so it may be another model's filter, or prose about one.")
           end
         end
       end
@@ -186,14 +221,35 @@ module Janela
       # and since ADR 032 every dashboard raises rather than answering with
       # every row. Reported so it is found here rather than by a visitor.
       #
-      # Where unauthenticated_endpoints has to hedge, because what counts as
-      # authentication cannot be determined by reading, this one is exact: the
-      # method is defined or it is not, and that is the whole contract.
+      # ADR 032 called this check exact, on the reasoning that the method is
+      # defined or it is not. That was wrong, and ADR 035 supersedes it: Pundit
+      # defines policy_scope the moment it is included, whether or not the
+      # model has a policy, so for the commonest authorisation library defined
+      # and works are different questions. The check makes the call Janela
+      # makes rather than reading the method table (#51).
       def unscoped_reads
-        parent = Janela.parent_controller.safe_constantize
+        parent = parent_controller
         return unless parent
-        return if parent.private_method_defined?(:policy_scope) || parent.method_defined?(:policy_scope)
+        return undefined_policy_scope(parent) unless answers_policy_scope?(parent)
+        return unless Janela::Frame.table_exists? && Janela::Snapshot.table_exists?
+
+        [ Janela::Frame, Janela::Snapshot ].filter_map do |model|
+          outcome, answer = ask_for_scope(model)
+          next unless outcome == :raised
+
+          Finding.new(severity: :error,
+            summary: "#{parent}'s policy_scope raises for #{model}, so every pane will too",
+            detail: "  Janela makes this exact call on every dashboard request, and got:\n" \
+                    "    #{answer.class}: #{answer.message.to_s.lines.first.to_s.strip.truncate(140)}\n" \
+                    "  Janela's own records go through your policy like any other model's, so\n" \
+                    "  they need whatever yours need: with Pundit that is a policy class for\n" \
+                    "  #{model}. docs/multi-tenancy.md has the wiring.")
+        end
+      rescue StandardError
+        nil # no database to ask yet
+      end
 
+      def undefined_policy_scope(parent)
         Finding.new(severity: :error,
           summary: "#{parent} defines no policy_scope, so every pane will raise",
           detail: "  Janela asks your controller what may be read and refuses to guess.\n" \
@@ -204,15 +260,19 @@ module Janela
                   "  narrower; docs/multi-tenancy.md has the wiring for the usual libraries.")
       end
 
+      def answers_policy_scope?(parent)
+        parent.private_method_defined?(:policy_scope) || parent.method_defined?(:policy_scope)
+      end
+
       # A host whose policy filters frames by owner, but which never tells
       # Janela what owns a new one, creates frames its own scope then hides.
       # The failure is silent, and a typo in the method name looks the same as
       # not defining it, which is the cost of asking by duck typing (ADR 019).
       def frames_nobody_will_own
-        parent = Janela.parent_controller.safe_constantize
-        return unless parent&.private_method_defined?(:policy_scope) || parent&.method_defined?(:policy_scope)
+        parent = parent_controller
+        return unless parent && answers_policy_scope?(parent)
         return if parent.private_method_defined?(:janela_frame_owner) || parent.method_defined?(:janela_frame_owner)
-        return unless Janela::Frame.table_exists? && scope_filters_by_owner?(parent, Janela::Frame)
+        return unless Janela::Frame.table_exists? && owner_filtering(Janela::Frame) == :filtered
 
         Finding.new(severity: :error,
           summary: "#{parent} scopes frames by owner but defines no janela_frame_owner",
@@ -236,9 +296,9 @@ module Janela
       # times in this repository's tests and once on the live demo within an
       # afternoon of the column landing (#49).
       def snapshots_nobody_will_see
-        parent = Janela.parent_controller.safe_constantize
+        parent = parent_controller
         return unless parent && Janela::Snapshot.table_exists?
-        return unless scope_filters_by_owner?(parent, Janela::Snapshot)
+        return unless owner_filtering(Janela::Snapshot) == :filtered
 
         unowned = Janela::Snapshot.where(owner_id: nil).count
         return if unowned.zero?
@@ -256,17 +316,46 @@ module Janela
       # Asking the policy rather than reading its source: a scope that narrows
       # an owned record is one that will hide an unowned one. Shared, because
       # a frame and a snapshot are the same question asked of two tables.
-      def scope_filters_by_owner?(parent, model)
-        parent.allocate.send(:policy_scope, model).to_sql.include?("owner")
+      #
+      # Three-valued on purpose. Collapsing a raise into false is how both
+      # owner checks came to be silent for every host whose policy reaches for
+      # the signed in user: a raise is a different fact from a scope that does
+      # not filter, and unscoped_reads is the check that reports it (ADR 035).
+      def owner_filtering(model)
+        outcome, answer = ask_for_scope(model)
+        return :raised if outcome == :raised
+
+        answer.to_sql.include?("owner") ? :filtered : :unfiltered
       rescue StandardError
-        false
+        :raised
+      end
+
+      # What Janela's controllers actually inherit. Janela.parent_controller is
+      # what a host asked for, and the two differ when it was named too late,
+      # which is how a check came to print "Janela's controllers inherit X"
+      # about a class that was not in the chain (ADR 035, #38).
+      def parent_controller
+        Janela::ApplicationController.superclass
+      end
+
+      # Asks the host's policy the way a request does. On a controller with no
+      # request, session, params and current_user are all unreachable, so a
+      # policy that touches any of them raises for a reason that is not the
+      # host's fault. Given a request they are empty instead, which is an
+      # unauthenticated visitor: the right thing for a check to ask about.
+      def ask_for_scope(model)
+        controller = parent_controller.allocate
+        controller.set_request!(ActionDispatch::TestRequest.create) if controller.respond_to?(:set_request!)
+        [ :ok, controller.send(:policy_scope, model) ]
+      rescue StandardError => e
+        [ :raised, e ]
       end
 
       # Whether an endpoint is public depends on what the host's controller
       # does, which cannot be determined by reading, so this observes and says
       # so rather than declaring anything safe.
       def unauthenticated_endpoints
-        parent = Janela.parent_controller.safe_constantize
+        parent = parent_controller
         return unless parent
 
         filters = parent._process_action_callbacks.map(&:filter).map(&:to_s)
@@ -281,7 +370,7 @@ module Janela
 
       def janela_models
         Rails.application.eager_load!
-        ActiveRecord::Base.descendants.select { |model| model.respond_to?(:janela) && model.janela }
+        ActiveRecord::Base.descendants.select { |model| Janela.our_definition(model) }
       rescue StandardError
         []
       end

data/lib/janela/model.rb

@@ -29,9 +29,14 @@ module Janela
     # does not exist yet, so it registers as it is created (ADR 031). An
     # anonymous class has no route key to be addressed by; naming it is the
     # host's move and declaring on it is the host's other one.
+    #
+    # A Definition rather than anything truthy: this is extended onto every
+    # model in the application, so `janela` may be a method the host wrote for
+    # its own reasons, and the host's own wins. Janela believes only what
+    # Janela built (#54).
     def inherited(subclass)
       super
-      Janela.register_subclass(subclass) if subclass.name && janela
+      Janela.register_subclass(subclass) if subclass.name && janela.is_a?(Definition)
     end
 
     private

data/lib/janela/version.rb

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

data/lib/janela.rb

@@ -27,7 +27,41 @@ module Janela
 
   # Janela's controllers inherit from the host's, so the host's authentication
   # and authorisation apply to dashboards with no configuration.
-  mattr_accessor :parent_controller, default: "ApplicationController"
+  #
+  # Resolved once, when Janela::ApplicationController is first loaded. A host
+  # naming one after that point used to be ignored in silence: dashboards kept
+  # inheriting whatever was named first, so the host's authentication and its
+  # policy_scope were not the ones it had written, and nothing said so. Naming
+  # a different one too late raises instead (ADR 035, #38).
+  @parent_controller = "ApplicationController"
+
+  class << self
+    attr_reader :parent_controller
+
+    def parent_controller=(name)
+      inherited = inherited_controller
+      if inherited && inherited != name.to_s
+        raise Error, "Janela::ApplicationController already inherits #{inherited}, so naming " \
+                     "#{name} now would do nothing: the superclass is resolved once, the first " \
+                     "time the class is loaded. Set it earlier, 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 so is anything that runs " \
+                     "once the application is serving."
+      end
+
+      @parent_controller = name
+    end
+
+    # What Janela::ApplicationController resolved to, or nil if it has not been
+    # loaded yet. Asked without forcing the autoload the question is about:
+    # const_defined? is true for a registered autoload, and autoload? stops
+    # being truthy only once the file has actually been loaded.
+    def inherited_controller
+      return nil if autoload?(:ApplicationController) || !const_defined?(:ApplicationController, false)
+
+      const_get(:ApplicationController, false).superclass.name
+    end
+  end
 
   # The stylesheet Janela's own pages load on top of janela.css. Nil means the
   # structural one only, which is what a host that has its own look wants. The
@@ -95,7 +129,7 @@ module Janela
   # here until a restart, and a form offering it would fail to draw at all.
   def self.definitions
     Rails.application.eager_load!
-    registry.sort.filter_map { |_route_key, class_name| class_name.safe_constantize&.janela }
+    registry.sort.filter_map { |_route_key, class_name| our_definition(class_name.safe_constantize) }
   end
 
   def self.definition!(route_key)
@@ -104,7 +138,17 @@ module Janela
     Rails.application.eager_load! unless registry.key?(route_key)
     class_name = registry.fetch(route_key) { raise NotFound, "#{route_key.inspect} is not a janela model" }
 
-    class_name.constantize.janela
+    our_definition(class_name.constantize) ||
+      raise(NotFound, "#{route_key.inspect} is not a janela model")
+  end
+
+  # Janela::Model is extended onto every model in the application, so `janela`
+  # is a question any of them can answer, and a host that answers it for its
+  # own reasons wins: its method is on its own singleton. Janela believes only
+  # what Janela built, rather than anything truthy that comes back (#54).
+  def self.our_definition(model)
+    definition = model.janela if model.respond_to?(:janela)
+    definition if definition.is_a?(Definition)
   end
 
   # What Janela can draw, so a gallery asks rather than reaching into

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Jay Killeen
@@ -114,6 +114,7 @@ files:
 - app/models/janela/query.rb
 - app/models/janela/snapshot.rb
 - app/views/janela/frames/_card.html.erb
+- app/views/janela/frames/_content.html.erb
 - app/views/janela/frames/_form.html.erb
 - app/views/janela/frames/_frame.html.erb
 - app/views/janela/frames/_pane.html.erb
@@ -121,6 +122,7 @@ files:
 - app/views/janela/frames/index.html.erb
 - app/views/janela/frames/new.html.erb
 - app/views/janela/frames/show.html.erb
+- app/views/janela/panes/_content_form.html.erb
 - app/views/janela/panes/_form.html.erb
 - app/views/janela/panes/_row.html.erb
 - app/views/janela/panes/edit.html.erb
@@ -137,6 +139,9 @@ files:
 - db/migrate/20260916000001_create_janela_frames.rb
 - db/migrate/20260916000002_create_janela_panes.rb
 - db/migrate/20260921000001_add_owner_to_janela_snapshots.rb
+- db/migrate/20260924000001_add_content_to_janela_panes.rb
+- db/migrate/20260924000002_add_key_to_janela_frames.rb
+- docs/composing.md
 - docs/decisions/001-built-to-be-forked.md
 - docs/decisions/002-measures-and-dimensions-over-ransack.md
 - docs/decisions/003-cross-filtering-with-turbo-frames.md
@@ -171,9 +176,19 @@ files:
 - docs/decisions/032-janela-will-not-read-a-model-it-cannot-scope.md
 - docs/decisions/033-a-snapshot-is-told-who-owns-it.md
 - docs/decisions/034-janela-will-not-freeze-a-scope-the-host-has-not-named.md
+- docs/decisions/035-a-check-does-what-janela-does-or-says-what-it-saw.md
+- docs/decisions/036-janela-publishes-what-a-theme-may-target.md
+- docs/decisions/037-what-1-0-means.md
+- docs/decisions/038-a-ratio-is-a-measure-of-its-own.md
+- docs/decisions/039-a-pane-can-hold-words-and-only-code-writes-markup.md
+- docs/decisions/040-a-host-can-fix-a-frames-filter.md
+- docs/decisions/041-a-host-finds-its-frame-by-owner-and-key.md
+- docs/decisions/042-a-charts-title-is-a-figcaption.md
 - docs/decisions/INDEX.md
 - docs/multi-tenancy.md
 - docs/naming.md
+- docs/roadmap.md
+- docs/theming.md
 - lib/janela.rb
 - lib/janela/definition.rb
 - lib/janela/dimension.rb
@@ -194,22 +209,22 @@ metadata:
   bug_tracker_uri: https://github.com/retail-tasker/janela/issues
   rubygems_mfa_required: 'true'
 post_install_message: |
-  Janela 0.7.0 stops guessing what may be read. Two things now refuse
-  rather than defaulting to every row, and both are quick to answer.
+  Janela 0.9.0: a migration if you use stored frames, and a markup
+  check if you wrote CSS or JavaScript against a chart pane.
 
-  1. If your ApplicationController defines no policy_scope, every pane
-     raises Janela::Unscoped instead of totalling every row. Pundit
-     hosts and anyone following docs/multi-tenancy.md: nothing to do.
-     Everyone else writes one line (ADR 032).
+  1. If you use stored frames, take two migrations together:
+     bin/rails janela:install:migrations && bin/rails db:migrate
+     A pane can now hold words or a host partial instead of a query
+     (ADR 039), and Janela::Frame.for(owner, key) finds a frame kept
+     for one of your pages without a column of your own (ADR 041).
+     Existing frames and panes are unaffected either way.
 
-  2. If you schedule Janela::SnapshotJob, it now needs to be told what
-     rows to freeze: pass scope: :model_default, or subclass it and
-     override scope_for. A job already on your queue was serialised
-     without that argument and will raise when it performs, so drain it
-     or re-enqueue (ADR 034).
-
-  If you use snapshots, there is also a migration: janela_snapshots
-  gains a nullable owner (ADR 033).
+  2. A chart pane's title is now a visible <figcaption> inside a
+     <figure> wrapping the canvas, not only the canvas's aria-label
+     (ADR 042). janela-pane moved from the <canvas> to the <figure>;
+     janela-chart stayed on the canvas. If you selected
+     .janela-pane.janela-chart as one element, or read a chart's
+     title from aria-label, both need updating.
 
   Steps: UPGRADING.md in this gem, or
   https://github.com/retail-tasker/janela/blob/main/UPGRADING.md