janela 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b37ede25ec758841e03748b59d6ebce1044ffeacc50fa38eea78a95a57f731be
-  data.tar.gz: beae0fa4879019dfd161a5196bff0420b2053bccd6d7243a272bd3b173b77ce7
+  metadata.gz: 8f1be37d3c8dc019195214b51f66d263d13032c3f12e44861620fd2d4f1cbe88
+  data.tar.gz: be62c3edcf0f95b897c22a7b348b76168398ee6f3c801230236a3195bda9aae6
 SHA512:
-  metadata.gz: fb70200d571c6ba005f868336d05e4fbe40d7acc720ecd73895c328b92429b2606fd806b9e8a42fe68ca8fb6f47423f57cb1af9fba3424d5c2d1561a299a56d6
-  data.tar.gz: 0d78429d0dfdde06f0b77bdec85704d1f7d1a13e29046926937d9fb99346097d86f4420c74cea5035b48e22950813b11a53d8b4e5064e122eb7b128788803844
+  metadata.gz: 63ef09cab8969ea61002ac8273304222ef40d3d11cc5d5470eecab7a26ef57d84186afb44b58b6bcbeb25a336ae16e91fbc45289199a2163ed3a203bef739ff8
+  data.tar.gz: 05462c455475cadb4dc633e76ea3181eeba0d169c9f82090a715a39afb375b92adebba3ca4de4db9e41c03d6a3dd53a641017ee5605e3c90280c18ab3c5dba1a

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-15
+
+Breaking. Renames and a new URL scheme while the only installation is the author's own (ADR 005).
+
+### Changed
+
+- `janela_visual` is now `janela_pane`; `Janela::Visual` is `Janela::Pane`; CSS hooks are `janela-pane`, `janela-chart`, `janela-value`, `janela-empty`.
+- A pane's URL is `/<mount>/<model route key>/<measure>[/<dimension>]?as=bar&q[...]` instead of `/<mount>/visual?model=...`. Frame ids follow the same shape.
+- The gem no longer ships its Rakefile, which referenced the unshipped dummy application.
+- The helper finds the engine's mount in the host's routes, so `mount Janela::Engine => "/reports", as: :reports` works. Documentation and the dummy application mount at `/dashboards`.
+
+### Added
+
+- A pane with no dimension renders the measure's single total.
+- Time dimensions: `dimension :placed_on, granularity: :month` buckets with Groupdate (`hour` to `year`), gap-filled, labelled in Ruby. Override per pane with `?granularity=week` or `janela_pane ..., granularity: :week`. Time panes re-scope with the dashboard but are not yet click sources (ADR 006).
+- `as: :line` renderer for time series.
+- Groupdate is a runtime dependency.
+- Published to rubygems.org through trusted publishing; a public demo of `test/dummy` deploys from `main`.
+- Snapshots: `Janela::Snapshot.take` freezes several panes' results at one instant under one set of filters; `janela_snapshot_pane` renders a stored pane, static by nature, at `/snapshots/:id/<model>/<measure>[/<dimension>]`. `Janela::SnapshotJob` for scheduling. First migration: `rails janela:install:migrations` (ADR 009).
+- Dashboard filters live in the page URL as `q[...]`; a reload keeps them and a filtered dashboard is shareable. The server renders the initial state from `params[:q]` (ADR 008).
+- Category panes are ordered by their measure, largest first, in SQL. `?limit=N` / `janela_pane ..., limit: N` keeps the top N (ADR 007).
+- `dimension :customer, through: :customer, column: :name` names a dimension for its meaning while reading another column.
+
+
 ## [0.1.0] - 2026-09-15
 
 First alpha, installed from GitHub for testing in a single host application.
@@ -23,4 +47,5 @@ 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.2.0]: https://github.com/retail-tasker/janela/releases/tag/v0.2.0
 [0.1.0]: https://github.com/retail-tasker/janela/releases/tag/v0.1.0

data/README.md

@@ -21,16 +21,16 @@ Janela's bet: the same dashboard definition should serve two audiences without b
 
 ## Installation
 
-Janela is pre-release and installed from GitHub. It has two halves, a gem and an npm package, installed the same way:
+Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has two halves, a gem and an npm package:
 
 ```ruby
 # Gemfile
-gem "janela", github: "retail-tasker/janela"
+gem "janela", "~> 0.2"
 ```
 
 ```ruby
 # config/routes.rb
-mount Janela::Engine => "/janela"
+mount Janela::Engine => "/dashboards"   # or /reports, or wherever you like
 ```
 
 Then register the two Stimulus controllers. How depends on how your app ships JavaScript.
@@ -79,16 +79,22 @@ class Order < ApplicationRecord
 
     dimension :status
     dimension :region, through: :customer
+    dimension :placed_on, granularity: :month
   end
 end
 ```
 
+A dimension with a `granularity` is a time dimension. Groupdate buckets it (`hour`, `day`, `week`, `month`, `quarter`, `year`), fills empty buckets with zero, and uses your app's `Time.zone` and week start.
+
 Then query them:
 
 ```ruby
 Order.janela.query(:revenue)                  # => 375
 Order.janela.query(:revenue, by: :status)     # => { "paid" => 300, "refunded" => 50, "pending" => 25 }
 Order.janela.query(:revenue, by: :region)     # => { "APAC" => 150, "EU" => 225 }
+Order.janela.query(:revenue, by: :placed_on)  # => { "Sep 2026" => 375 }
+Order.janela.query(:revenue, by: :placed_on, granularity: :day)
+                                              # => { "2026-09-01" => 100, "2026-09-02" => 50, ... }
 ```
 
 Filters are [Ransack](https://github.com/activerecord-hackery/ransack) params, so a slicer built with `search_form_for` can pass `params[:q]` straight through:
@@ -114,21 +120,66 @@ end
 
 ### Dashboards
 
-Compose visuals on any page. Each visual is a Turbo Frame; clicking a value in one re-scopes the others:
+Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one re-scopes the others:
 
 ```erb
 <%= janela_dashboard do %>
   <button type="button" data-action="janela--dashboard#clear">Clear filters</button>
 
-  <%= janela_visual Order, :revenue, by: :status, as: :bar %>
-  <%= janela_visual Order, :revenue, by: :region %>
-  <%= janela_visual Order, :orders,  by: :region %>
+  <%= janela_pane Order, :revenue %>
+  <%= janela_pane Order, :revenue, by: :status, as: :bar %>
+  <%= janela_pane Order, :revenue, by: :region %>
+  <%= janela_pane Order, :orders,  by: :region %>
 <% end %>
 ```
 
-`as:` is `:table` by default or `:bar` for a Chart.js bar chart. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
+A pane with no `by:` is the measure's single total, the KPI tile. `limit: 10` keeps the top ten rows or bars. `as:` is `:table` by default, `:bar` for a Chart.js bar chart, or `:line`, which suits a time dimension: `janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week`. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
+
+The dashboard's filters live in the page URL as the same `q[...]` parameters, so a reload keeps them and a filtered dashboard is a link you can send: `/reports/orders?q[status_eq]=paid` renders filtered before any JavaScript runs. A pane ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the pane you clicked. Time panes re-scope with the others but are not click sources yet; drill-down is the next decision. The selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read. A pane with no matching rows renders a `.janela-empty` paragraph. Only models that declare a `janela` block can be requested over HTTP.
+
+### Pane URLs
+
+Every pane has its own URL under the mount, and a Turbo Frame in a dashboard loads exactly the same URL a person can open directly:
+
+```
+/dashboards/orders/revenue                      orders revenue
+/dashboards/orders/revenue/status               orders revenue by status
+/dashboards/orders/revenue/status?as=bar        ... as a bar chart
+/dashboards/orders/revenue/region?q[status_eq]=paid
+                                                orders revenue by region where status is paid
+/dashboards/orders/revenue/placed_on?granularity=week&as=line
+                                                orders revenue by placed_on, per week, as a line
+```
+
+The model is its route key (`orders`, `sales_orders`), then the measure, then optionally the dimension. Where an analyst would say *by*, the URL has a `/`; *where* is a `q` filter; *as a bar chart* is `?as=bar`; *top ten* is `?limit=10`; *as of* a snapshot is `/snapshots/:id/` in front. Category panes are always ordered by the measure, largest first; time panes are chronological. A pane opened on its own renders inside your application layout with its filters applied, so a filtered pane is a link you can send someone. ADR 005 has the reasoning.
+
+### Snapshots
+
+A snapshot freezes the results of several panes at one instant, under one set of filters, so an audience sees exactly what was signed off while the live dashboard stays editable. Results are stored, not HTML; a stored pane can still be drawn as a table or a chart.
+
+```bash
+bin/rails janela:install:migrations && bin/rails db:migrate
+```
+
+```ruby
+Janela::Snapshot.take(name: "September 2026", filters: { status_eq: "paid" }) do |take|
+  take.pane Order, :revenue,                                on: policy_scope(Order)
+  take.pane Order, :revenue, by: :status,                   on: policy_scope(Order)
+  take.pane Order, :revenue, by: :placed_on, granularity: :week
+end
+```
+
+Render a stored pane the same way you render a live one:
+
+```erb
+<%= janela_snapshot_pane @snapshot, Order, :revenue, by: :status, as: :bar %>
+```
+
+Stored panes are static by nature: no filter buttons, charts ignore clicks, and the URL says *as of*: `/dashboards/snapshots/42/orders/revenue/status`. Request filters are ignored because the snapshot's were fixed when it was taken.
+
+`Janela::SnapshotJob.perform_later(name:, panes: [{ "model" => "orders", "measure" => "revenue", "by" => "status" }])` takes one from serialisable arguments so you can schedule it with whatever runs your jobs. The job uses each model's default scope; if you scope by tenant, write your own job around `Snapshot.take` and pass `on:`.
 
-A visual ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the visual you clicked. The selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read. A visual with no matching rows renders a `.janela-empty` paragraph. Only models that declare a `janela` block can be requested over HTTP.
+Who may see a snapshot is your decision. Stored panes go through the same controllers as live ones, so your authentication applies; an external audience gets a page you build over `janela_snapshot_pane` behind whatever share tokens you already trust. ADR 009 has the reasoning.
 
 ### Securing dashboards
 
@@ -153,7 +204,7 @@ Janela ships the load-bearing core of a BI tool and nothing else. The reasoning
 
 - **Measures and dimensions are a Ruby DSL on the model**, config-as-code like `routes.rb`. No drag-and-drop designer.
 - **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 visual, shared filter state updates, every other frame on the page re-renders.
+- **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.
 
@@ -161,7 +212,7 @@ Deliberately out of scope: report designer UI, natural-language query, a separat
 
 ## Status
 
-**v0.1.0 alpha.** The measures/dimensions DSL, cross-filtering, and bar charts work and are covered by unit and real-browser tests. Not yet built: time-granularity dimensions, other chart types, filter state in the page URL, published snapshots. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.2.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering, bar and line charts, pane URLs, shareable dashboard URLs and snapshots work and are covered by unit and real-browser tests. Not yet built: drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

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

@@ -3,7 +3,7 @@ import { Chart, registerables } from "chart.js"
 
 Chart.register(...registerables)
 
-// Renders one visual as a chart and turns a click on a bar into the same
+// Renders one pane as a chart and turns a click on a bar into the same
 // toggle event a table button emits, so the dashboard controller cannot tell
 // the difference. Turbo replaces the frame on every cross-filter, so the chart
 // is destroyed on disconnect and rebuilt on connect.
@@ -15,13 +15,19 @@ export default class extends Controller {
       type: this.typeValue,
       data: {
         labels: this.labelsValue,
-        datasets: [{ label: this.titleValue, data: this.valuesValue, backgroundColor: this.colours() }]
+        datasets: [{
+          label: this.titleValue,
+          data: this.valuesValue,
+          backgroundColor: this.colours(),
+          borderColor: "rgba(54, 162, 235, 0.9)"
+        }]
       },
       options: {
         animation: false,
+        scales: { y: { beginAtZero: true } },
         plugins: { legend: { display: false } },
         onClick: (_event, elements) => {
-          if (elements.length === 0) return
+          if (!this.keyValue || elements.length === 0) return
           const value = this.labelsValue[elements[0].index]
           this.dispatch("toggle", { detail: { key: this.keyValue, value } })
         }

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

@@ -1,10 +1,10 @@
 import { Controller } from "@hotwired/stimulus"
 
-// Shared filter state for every visual on the page. Clicking a value rewrites
+// Shared filter state for every pane on the page. Clicking a value rewrites
 // each frame's src, and Turbo reloads a frame whenever its src changes, so
 // cross-filtering needs no streams, no sockets and no state library.
 export default class extends Controller {
-  static targets = ["visual"]
+  static targets = ["pane"]
   static values = { filters: Object }
 
   // Table buttons send key/value as Stimulus action params; charts dispatch a
@@ -27,14 +27,32 @@ export default class extends Controller {
   }
 
   filtersValueChanged() {
-    this.visualTargets.forEach((visual) => {
-      const url = new URL(visual.dataset.janelaSrc, window.location.origin)
+    this.paneTargets.forEach((pane) => {
+      const url = new URL(pane.dataset.janelaSrc, window.location.origin)
+      this.writeFilters(url)
+      if (pane.src !== url.href) pane.src = url.href
+    })
 
-      for (const [key, value] of Object.entries(this.filtersValue)) {
-        url.searchParams.set(`q[${key}]`, value)
-      }
+    this.syncPageUrl()
+  }
 
-      if (visual.src !== url.href) visual.src = url.href
-    })
+  // The page URL carries the same q[...] the panes do, so a reload or a
+  // pasted link opens the dashboard filtered (ADR 008). Replaced rather than
+  // pushed: a click is not a place the back button should return to.
+  syncPageUrl() {
+    const url = new URL(window.location.href)
+    for (const key of [...url.searchParams.keys()]) {
+      if (key.startsWith("q[")) url.searchParams.delete(key)
+    }
+    this.writeFilters(url)
+    if (url.href !== window.location.href) history.replaceState(history.state, "", url)
+  }
+
+  // Sorted so the browser serialises filters the same way the server does and
+  // an unchanged src is never reloaded.
+  writeFilters(url) {
+    for (const key of Object.keys(this.filtersValue).sort()) {
+      url.searchParams.set(`q[${key}]`, this.filtersValue[key])
+    }
   }
 }

data/app/controllers/janela/{visuals_controller.rb → panes_controller.rb}

@@ -1,15 +1,17 @@
 module Janela
-  class VisualsController < ApplicationController
+  class PanesController < ApplicationController
     def show
-      @visual = Visual.new(
+      @pane = Pane.new(
         definition: Janela.definition!(params.require(:model)),
         measure: params.require(:measure).to_sym,
-        dimension: params.require(:by).to_sym,
+        dimension: params[:dimension]&.to_sym,
         renderer: params.fetch(:as, "table"),
+        granularity: params[:granularity],
+        limit: params[:limit],
         filters: filters
       )
 
-      @result = @visual.result(on: janela_scope(@visual.model))
+      @result = @pane.result(on: janela_scope(@pane.model))
     end
 
     private

data/app/controllers/janela/snapshot_panes_controller.rb

@@ -0,0 +1,21 @@
+module Janela
+  # A pane as it was when a snapshot was taken. Filters in the request are
+  # ignored: they were fixed at taking (ADR 009).
+  class SnapshotPanesController < ApplicationController
+    def show
+      snapshot = Snapshot.find(params.require(:snapshot_id))
+      @pane = Pane.new(
+        definition: Janela.definition!(params.require(:model)),
+        measure: params.require(:measure).to_sym,
+        dimension: params[:dimension]&.to_sym,
+        renderer: params.fetch(:as, "table"),
+        granularity: params[:granularity],
+        limit: params[:limit],
+        snapshot: snapshot
+      )
+
+      @result = @pane.result
+      render "janela/panes/show"
+    end
+  end
+end

data/app/helpers/janela/dashboard_helper.rb

@@ -1,16 +1,49 @@
 module Janela
   module DashboardHelper
+    # The page URL carries the dashboard's filters as q[...] (ADR 008), so a
+    # shared link renders filtered before any JavaScript runs.
     def janela_dashboard(&block)
-      tag.div(data: { controller: "janela--dashboard" }, &block)
+      tag.div(data: { controller: "janela--dashboard", janela__dashboard_filters_value: janela_page_filters.to_json }, &block)
     end
 
-    def janela_visual(model, measure, by:, as: :table)
-      src = janela.visual_path(model: model.name, measure: measure, by: by, as: as)
+    def janela_pane(model, measure, by: nil, as: :table, granularity: nil, limit: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit }.compact
+      base = janela_routes.pane_path(model.model_name.route_key, measure, by, **query)
+      src = janela_page_filters.empty? ? base : janela_routes.pane_path(model.model_name.route_key, measure, by, **query, q: janela_page_filters)
 
-      turbo_frame_tag Visual.frame_id(model: model.name, measure: measure, by: by, as: as),
+      turbo_frame_tag Pane.frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit),
         src: src,
         loading: :lazy,
-        data: { janela__dashboard_target: "visual", janela_src: src }
+        data: { janela__dashboard_target: "pane", janela_src: base }
     end
+
+    # A pane as it was when the snapshot was taken: same shape as janela_pane,
+    # not part of the live dashboard's filter state (ADR 009).
+    def janela_snapshot_pane(snapshot, model, measure, by: nil, as: :table, granularity: nil, limit: nil)
+      query = { as: (as unless as.to_s == "table"), granularity: granularity, limit: limit }.compact
+      src = janela_routes.snapshot_pane_path(snapshot, model.model_name.route_key, measure, by, **query)
+
+      turbo_frame_tag Pane.frame_id(model: model, measure: measure, by: by, as: as, granularity: granularity, limit: limit, snapshot: snapshot),
+        src: src, loading: :lazy
+    end
+
+    private
+      def janela_page_filters
+        @janela_page_filters ||= begin
+          q = request.query_parameters["q"]
+          q.is_a?(Hash) ? q.sort.to_h : {}
+        end
+      end
+
+      # The host chooses where and under what name the engine is mounted, so
+      # the route proxy is looked up rather than assumed to be `janela`.
+      def janela_routes
+        @janela_routes ||= begin
+          mount = Rails.application.routes.routes.find { |route| route.app.respond_to?(:app) && route.app.app == Janela::Engine }
+          raise Error, "Janela::Engine is not mounted in the host application's routes" unless mount
+
+          public_send(mount.name)
+        end
+      end
   end
 end

data/app/jobs/janela/snapshot_job.rb

@@ -0,0 +1,18 @@
+module Janela
+  # Takes a snapshot from serialisable arguments so a host can schedule it
+  # with whatever runs its jobs. Each pane uses its model's default scope; a
+  # host that scopes by tenant writes its own job around Snapshot.take and
+  # passes on: (ADR 009).
+  class SnapshotJob < ActiveJob::Base
+    def perform(name:, panes:, filters: {})
+      Snapshot.take(name: name, filters: filters) do |take|
+        panes.each do |pane|
+          pane = pane.to_h.stringify_keys
+          model = Janela.definition!(pane.fetch("model")).model
+          take.pane(model, pane.fetch("measure").to_sym,
+                    by: pane["by"]&.to_sym, granularity: pane["granularity"], limit: pane["limit"])
+        end
+      end
+    end
+  end
+end

data/app/models/janela/pane.rb

@@ -0,0 +1,118 @@
+module Janela
+  # One pane of a dashboard: a measure, optionally grouped by a dimension,
+  # rendered as a single value, a table or a chart. A pane ignores filters on
+  # its own dimension so that clicking a value re-scopes the other panes
+  # rather than collapsing this one to the value clicked. A pane read from a
+  # snapshot shows stored results and cannot be clicked at all.
+  class Pane
+    RENDERERS = %w[table bar line].freeze
+
+    attr_reader :definition, :measure, :dimension, :renderer, :limit, :filters, :snapshot
+
+    # The helper renders the frame and the controller renders its replacement,
+    # so both derive the id the same way from the same parameters.
+    def self.frame_id(model:, measure:, by: nil, as: :table, granularity: nil, limit: nil, snapshot: nil)
+      parts = [ "janela", ("snapshot_#{snapshot.id}" if snapshot), model.model_name.route_key, measure, by,
+                (granularity if by), (as unless by.nil?), ("top#{limit}" if by && limit) ]
+      parts.compact.join("_")
+    end
+
+    def initialize(definition:, measure:, dimension: nil, renderer: "table", granularity: nil, limit: nil, filters: {}, snapshot: nil)
+      @definition = definition
+      @measure = measure
+      @dimension = dimension
+      @renderer = renderer.to_s
+      @filters = filters
+      @snapshot = snapshot
+
+      raise Error, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
+      @granularity = Dimension.granularity!(granularity) if granularity.present?
+      @limit = definition.limit!(limit) if limit.present?
+    end
+
+    def model
+      definition.model
+    end
+
+    def single_value?
+      dimension.nil?
+    end
+
+    def time?
+      !single_value? && dimension_definition.time?
+    end
+
+    def frozen?
+      !snapshot.nil?
+    end
+
+    def granularity
+      @granularity || (dimension_definition.granularity if time?)
+    end
+
+    # Clicking a category adds one Ransack condition; clicking a time bucket
+    # would need two, and the dashboard toggles one key at a time (ADR 006).
+    # A stored pane is the record of a moment and is not clickable (ADR 009).
+    def clickable?
+      !single_value? && !time? && !frozen?
+    end
+
+    def chart?
+      !single_value? && renderer != "table"
+    end
+
+    def frame_id
+      self.class.frame_id(model: model, measure: measure, by: dimension, as: renderer,
+                          granularity: @granularity, limit: limit, snapshot: snapshot)
+    end
+
+    def title
+      base = if single_value?
+        measure.to_s.humanize
+      else
+        by = "#{measure.to_s.humanize} by #{dimension.to_s.humanize}"
+        time? ? "#{by} per #{granularity}" : by
+      end
+      frozen? ? "#{base} as of #{snapshot.taken_at.strftime('%-d %b %Y')}" : base
+    end
+
+    # What identifies this pane's data inside a snapshot.
+    def lookup_key
+      { "model" => model.model_name.route_key, "measure" => measure.to_s, "dimension" => dimension&.to_s,
+        "granularity" => granularity&.to_s, "limit" => limit }
+    end
+
+    def result(on: nil)
+      return snapshot.stored_result(self) if frozen?
+
+      definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
+    end
+
+    def filter_key
+      "#{ransack_name}_eq" if clickable?
+    end
+
+    # The filter on this pane's own dimension is not applied to its query, but
+    # it is what the user clicked here, so the view highlights it.
+    def selected_value
+      return unless clickable?
+
+      filters[filter_key] || filters[filter_key.to_sym]
+    end
+
+    private
+      def dimension_definition
+        definition.dimension!(dimension)
+      end
+
+      def ransack_name
+        dimension_definition.ransack_name
+      end
+
+      def applicable_filters
+        return filters if single_value? || time?
+
+        filters.reject { |key, _| key.to_s.start_with?(ransack_name) }
+      end
+  end
+end

data/app/models/janela/snapshot.rb

@@ -0,0 +1,51 @@
+module Janela
+  # A snapshot freezes the results of several panes at one instant under one
+  # set of filters, so an audience sees exactly what was signed off while the
+  # live dashboard stays editable (ADR 009). Results are stored, not HTML; the
+  # renderer is chosen by whoever shows a stored pane.
+  class Snapshot < ActiveRecord::Base
+    attribute :filters, default: -> { {} }
+    attribute :panes, default: -> { [] }
+
+    validates :name, :taken_at, presence: true
+
+    def self.take(name:, filters: {}, taken_at: Time.current)
+      taking = Taking.new(filters.to_h.stringify_keys)
+      yield taking
+      create!(name: name, taken_at: taken_at, filters: taking.filters, panes: taking.panes)
+    end
+
+    def stored_result(pane)
+      key = pane.lookup_key
+      entry = panes.find { |stored| stored.slice(*key.keys) == key }
+      raise Error, "snapshot #{id} has no pane #{key.compact.values.join(' ')}" unless entry
+
+      entry["result"]
+    end
+
+    class Taking
+      attr_reader :filters, :panes
+
+      def initialize(filters)
+        @filters = filters
+        @panes = []
+      end
+
+      def pane(model, measure, by: nil, granularity: nil, limit: nil, on: nil)
+        pane = Pane.new(definition: model.janela, measure: measure, dimension: by,
+                        granularity: granularity, limit: limit, filters: filters)
+        panes << pane.lookup_key.merge("result" => plain(pane.result(on: on)))
+      end
+
+      private
+        # BigDecimal would otherwise be encoded as a JSON string.
+        def plain(result)
+          case result
+          when Hash then result.transform_values { |v| plain(v) }
+          when BigDecimal then result.to_f
+          else result
+          end
+        end
+    end
+  end
+end

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

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

data/config/routes.rb

@@ -1,3 +1,9 @@
 Janela::Engine.routes.draw do
-  resource :visual, only: :show
+  segment = /[a-z0-9_]+/
+
+  get "snapshots/:snapshot_id/:model/:measure(/:dimension)", to: "snapshot_panes#show", as: :snapshot_pane,
+    constraints: { snapshot_id: /\d+/, model: segment, measure: segment, dimension: segment }
+
+  get ":model/:measure(/:dimension)", to: "panes#show", as: :pane,
+    constraints: { model: segment, measure: segment, dimension: segment }
 end

data/db/migrate/20260915000001_create_janela_snapshots.rb

@@ -0,0 +1,13 @@
+class CreateJanelaSnapshots < ActiveRecord::Migration[8.0]
+  def change
+    create_table :janela_snapshots do |t|
+      t.string :name, null: false
+      t.datetime :taken_at, null: false
+      t.json :filters, null: false
+      t.json :panes, null: false
+      t.timestamps
+    end
+
+    add_index :janela_snapshots, :taken_at
+  end
+end

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

@@ -111,10 +111,11 @@ resolves against the engine's routes. Blazer documents the same
 
 ## Consequences
 
-- The npm package's `files` glob excludes `vendor/`, so registry or
-  `github:` installs do not ship the vendored Chart.js. yarn 1's
-  `file:` protocol copies the whole directory regardless; harmless,
-  only relevant during local development against a sibling checkout.
+- The npm package's `files` glob excludes `vendor/`, which a registry
+  install honours. Git-based installs (`github:`, `file:`) copy the
+  repository tree as is, so they carry the 200 KB vendored Chart.js
+  that a bundler host never imports. Harmless, and gone the day the
+  package is published to npm.
 - An importmap host with its own `chart.js` pin keeps it. The check is
   `packages.key?("chart.js")` in the engine's `config/importmap.rb` and
   depends on the host's importmap being evaluated first, which is the