janela 0.2.1 → 0.3.0

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

@@ -1,47 +1,4 @@
-<% content_for :title, @pane.title %>
-<%= 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-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 %>"
-            data-janela--chart-filters-value="<%= @pane.filters_for(@result.keys).to_json %>"
-            role="img" aria-label="<%= @pane.title %>"></canvas>
-  <% else %>
-    <table class="janela-pane">
-      <caption><%= @pane.title %></caption>
-      <tbody>
-        <% @result.each do |label, measured| %>
-          <% key, value = @pane.filter_params(label) %>
-          <tr>
-            <td>
-              <% if key %>
-                <button type="button"
-                        aria-pressed="<%= label.to_s == @pane.selected_value.to_s && @pane.selected_value.present? %>"
-                        data-action="janela--dashboard#toggle"
-                        data-janela--dashboard-key-param="<%= key %>"
-                        data-janela--dashboard-value-param="<%= value %>">
-                  <%= label %>
-                </button>
-              <% else %>
-                <span><%= label %></span>
-              <% end %>
-            </td>
-            <td><%= number_with_delimiter(measured) %></td>
-          </tr>
-        <% end %>
-      </tbody>
-    </table>
-  <% end %>
+<% content_for :title, @query.title %>
+<%= turbo_frame_tag @pane.turbo_frame_id do %>
+  <%= render "janela/queries/query", query: @query, result: @result %>
 <% end %>

data/app/views/janela/queries/_query.html.erb

@@ -0,0 +1,47 @@
+<%# One pane's content, without its turbo frame: the same markup whether the
+    pane came from a URL, a row, or a frame rendered inline. %>
+<% if query.single_value? %>
+  <p class="janela-pane janela-value">
+    <span class="janela-value-label"><%= query.title %></span>
+    <strong class="janela-value-number"><%= query.format(result || 0) %></strong>
+  </p>
+<% elsif result.empty? %>
+  <p class="janela-pane janela-empty"><%= query.title %>: no data</p>
+<% elsif query.chart? %>
+  <canvas class="janela-pane janela-chart"
+          data-controller="janela--chart"
+          data-action="janela--chart:toggle->janela--frame#toggle"
+          data-janela--chart-type-value="<%= query.renderer %>"
+          data-janela--chart-title-value="<%= query.title %>"
+          data-janela--chart-selected-value="<%= query.selected_value %>"
+          data-janela--chart-labels-value="<%= result.keys.to_json %>"
+          data-janela--chart-values-value="<%= result.values.map(&:to_f).to_json %>"
+          data-janela--chart-formatted-value="<%= result.values.map { |measured| query.format(measured) }.to_json %>"
+          data-janela--chart-filters-value="<%= query.filters_for(result.keys).to_json %>"
+          role="img" aria-label="<%= query.title %>"></canvas>
+<% else %>
+  <table class="janela-pane">
+    <caption><%= query.title %></caption>
+    <tbody>
+      <% result.each do |label, measured| %>
+        <% key, value = query.filter_params(label) %>
+        <tr>
+          <td>
+            <% if key %>
+              <button type="button"
+                      aria-pressed="<%= label.to_s == query.selected_value.to_s && query.selected_value.present? %>"
+                      data-action="janela--frame#toggle"
+                      data-janela--frame-key-param="<%= key %>"
+                      data-janela--frame-value-param="<%= value %>">
+                <%= label %>
+              </button>
+            <% else %>
+              <span><%= label %></span>
+            <% end %>
+          </td>
+          <td><%= query.format(measured) %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

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

@@ -0,0 +1,4 @@
+<% content_for :title, @query.title %>
+<%= turbo_frame_tag @query.turbo_frame_id do %>
+  <%= render "janela/queries/query", query: @query, result: @result %>
+<% end %>

data/app/views/janela/shared/_errors.html.erb

@@ -0,0 +1,7 @@
+<% if record.errors.any? %>
+  <ul class="janela-errors">
+    <% record.errors.full_messages.each do |message| %>
+      <li><%= message %></li>
+    <% end %>
+  </ul>
+<% end %>

data/app/views/layouts/janela/application.html.erb

@@ -1,7 +1,11 @@
-<%# A pane opened directly, outside a Turbo Frame. Deliberately minimal: the
-    engine cannot know the host's asset names or bundler, and a host layout's
-    route helpers do not resolve inside an isolated engine (ADR 011). A host
-    can override this file, or point the controller at its own layout. %>
+<%# Janela's own pages and a pane opened directly, outside a Turbo Frame.
+    Deliberately minimal: the engine cannot know the host's asset names or
+    bundler, and a host layout's route helpers do not resolve inside an
+    isolated engine (ADR 011). It loads Janela's own stylesheet, which the gem
+    ships and can therefore name, and no JavaScript: Turbo and Stimulus come
+    from the host, so these pages are static dashboards rather than broken
+    ones. A host can override this file, or point the controller at its own
+    layout. %>
 <!DOCTYPE html>
 <html>
   <head>
@@ -10,9 +14,13 @@
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
+    <%= stylesheet_link_tag "janela" %>
     <%= yield :head %>
   </head>
-  <body>
+  <body class="janela-page">
+    <% flash.each do |_kind, message| %>
+      <p class="janela-flash"><%= message %></p>
+    <% end %>
     <%= yield %>
   </body>
 </html>

data/config/importmap.rb

@@ -1,4 +1,4 @@
-pin "janela/dashboard_controller", to: "janela/dashboard_controller.js"
+pin "janela/frame_controller", to: "janela/frame_controller.js"
 pin "janela/chart_controller", to: "janela/chart_controller.js"
 
 # Hosts that already pin their own Chart.js keep it.

data/config/locales/en.yml

@@ -0,0 +1,64 @@
+en:
+  activerecord:
+    models:
+      janela/frame:
+        one: Frame
+        other: Frames
+      janela/pane:
+        one: Pane
+        other: Panes
+    attributes:
+      janela/frame:
+        name: Name
+        columns: Columns
+        gap: Gap
+      janela/pane:
+        model: Model
+        measure: Measure
+        dimension: Dimension
+        renderer: Renderer
+        granularity: Granularity
+        limit: Rows
+        span: Width
+        title: Title
+  janela:
+    actions:
+      add_pane: "Add a %{name}"
+      cancel: Cancel
+      continue: Continue
+      delete: Remove
+      delete_frame: "Delete this %{name}"
+      edit: Edit
+      move_down: Down
+      move_up: Up
+      new_frame: "New %{name}"
+      save: Save
+      view: View
+    frames:
+      created: Created.
+      destroyed: Deleted.
+      updated: Saved.
+      index:
+        blank: "No %{name} yet."
+      edit:
+        blank: "No %{name} yet."
+      frame:
+        panes:
+          zero: no panes
+          one: 1 pane
+          other: "%{count} panes"
+        changed: "changed %{time} ago"
+    panes:
+      created: Added.
+      destroyed: Removed.
+      updated: Saved.
+      declared_granularity: As the model declares it
+      granularity_hint: "Applies to %{dimensions} only."
+      no_dimension: "No breakdown, one number"
+      no_limit: Every row
+      summary: "%{renderer}, %{span} wide"
+      title_placeholder: Janela writes one if you leave this blank
+    renderers:
+      bar: Bar chart
+      line: Line chart
+      table: Table

data/config/routes.rb

@@ -1,9 +1,22 @@
 Janela::Engine.routes.draw do
   segment = /[a-z0-9_]+/
 
-  get "snapshots/:snapshot_id/:model/:measure(/:dimension)", to: "snapshot_panes#show", as: :snapshot_pane,
+  # Frames sit at the mount root and are drawn before the pane grammar, with a
+  # numeric constraint: no model's route key is all digits, so /3 is a frame
+  # and /orders/revenue is a pane, with nothing to disambiguate (ADR 014).
+  resources :frames, path: "", constraints: { id: /\d+/ } do
+    # No index: a frame's own edit page is the list of its panes.
+    resources :panes, except: :index, constraints: { id: /\d+/, frame_id: /\d+/ } do
+      member do
+        patch :move_up
+        patch :move_down
+      end
+    end
+  end
+
+  get "snapshots/:snapshot_id/:model/:measure(/:dimension)", to: "snapshot_queries#show", as: :snapshot_pane,
     constraints: { snapshot_id: /\d+/, model: segment, measure: segment, dimension: segment }
 
-  get ":model/:measure(/:dimension)", to: "panes#show", as: :pane,
+  get ":model/:measure(/:dimension)", to: "queries#show", as: :pane,
     constraints: { model: segment, measure: segment, dimension: segment }
 end

data/db/migrate/20260916000001_create_janela_frames.rb

@@ -0,0 +1,13 @@
+class CreateJanelaFrames < ActiveRecord::Migration[8.0]
+  def change
+    create_table :janela_frames do |t|
+      t.string :name, null: false
+      t.integer :columns, null: false, default: 3
+      t.integer :gap, null: false, default: 4
+      # Janela never reads the owner. It is here so a host's Pundit Scope has
+      # something to filter a frame on (ADR 014).
+      t.references :owner, polymorphic: true, null: true
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260916000002_create_janela_panes.rb

@@ -0,0 +1,22 @@
+class CreateJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    create_table :janela_panes do |t|
+      # The composite index below is the one a frame's panes are read by, so
+      # references adds none of its own.
+      t.references :frame, null: false, index: false, foreign_key: { to_table: :janela_frames }
+      t.integer :position, null: false
+      t.integer :span, null: false, default: 1
+      # A model's route key, the same identifier a pane URL carries (ADR 005).
+      t.string :model, null: false
+      t.string :measure, null: false
+      t.string :dimension
+      t.string :renderer, null: false, default: "table"
+      t.string :granularity
+      t.integer :limit
+      t.string :title
+      t.timestamps
+    end
+
+    add_index :janela_panes, [ :frame_id, :position ]
+  end
+end

data/docs/decisions/001-built-to-be-forked.md

@@ -71,3 +71,7 @@ Janela is designed to be forked, not just configured.
   special-casing Janela itself.
 - Future scope decisions (what's in the 5%, what isn't) should cite
   this ADR rather than re-litigate the philosophy each time.
+- The exclusion of a report designer was partly superseded by ADR 012:
+  composition became data, because this ADR assumed the developer
+  authored dashboards and the author is the analyst. The reasoning
+  still holds for the query vocabulary, which stays in code.

data/docs/decisions/009-snapshots.md

@@ -1,7 +1,8 @@
 ---
 Date: 2026-09-15
 Status: Accepted
-Related: ADR 001, ADR 002, ADR 005, ADR 008
+Related: ADR 001, ADR 002, ADR 005, ADR 008, ADR 012
+Superseded in part by: ADR 012
 Triggers:
   - publishing a dashboard or pane for an audience that must not see live data or slicers
   - adding a database table, migration or model to the engine
@@ -53,7 +54,9 @@ several panes frozen at the same instant under the same filters, so a
 `Janela::Snapshot` row holds a name, `taken_at`, the filters, and an
 array of pane results. There is no Dashboard model and no dashboard
 DSL: the host's page is the dashboard, and the host names the panes to
-freeze. If the host renders its live page from the same list it passes
+freeze. (Superseded in part by ADR 012: a dashboard is now a record,
+`Janela::Frame`, and a snapshot of a frame rather than of a list is
+the obvious next shape. Nothing about what a snapshot stores changes.) If the host renders its live page from the same list it passes
 here, nothing is declared twice.
 
 ```ruby

data/docs/decisions/010-agent-guidance-ships-the-agent-waits.md

@@ -1,7 +1,8 @@
 ---
 Date: 2026-09-15
 Status: Accepted
-Related: ADR 001, ADR 005, ADR 009
+Related: ADR 001, ADR 005, ADR 009, ADR 012, ADR 014
+Superseded in part by: ADR 012
 Triggers:
   - writing or changing guidance for AI agents about using Janela
   - proposing that Janela ship an agent, a skill or an MCP surface to hosts
@@ -65,9 +66,12 @@ is why it survives whatever agent formats come and go.
 4. When to take a snapshot, and that a snapshot holds results, not
    HTML.
 5. The three traps above, each with its one line fix.
-6. What Janela deliberately does not do, so an agent does not build a
-   report designer, natural language query, row level security or a
-   scheduler into the host by accident.
+6. What Janela deliberately does not do, so an agent does not build
+   natural language query, row level security or a scheduler into the
+   host by accident. Composition is no longer on that list: ADR 012
+   made frames and panes records and ADR 014 sequenced the editing
+   surfaces, so the skill points an agent at those rather than telling
+   it to compose dashboards in ERB.
 
 **The skill describes the README's API and nothing else.** One API,
 one set of names. If the skill needs to say something the README does

data/docs/decisions/012-frames-and-panes-are-data.md

@@ -0,0 +1,166 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 005, ADR 009
+Supersedes: part of ADR 001
+Triggers:
+  - changing what a frame or a pane stores, or how either is rendered
+  - adding an editing surface for dashboards
+  - anything that would let a persisted row widen what can be queried
+  - deciding whether a dashboard belongs in git
+  - adding layout vocabulary, or a layer between a frame and its panes
+  - naming anything "frame"
+Topics: frames, panes, persistence, layout, css-grid, naming, authorisation, scope
+---
+
+# ADR 012: Frames and Panes Are Data
+
+## Context
+
+ADR 001 put a drag and drop report designer out of scope and made
+dashboards code. A dashboard was an ERB page in the host application
+calling `janela_pane` helpers, which kept it in git, reviewable and
+identical across environments. Everything since has been built on that
+assumption.
+
+Dogfooding found the assumption wrong, and the reason is ownership
+rather than convenience. **The author of a dashboard is the analyst.**
+In the commercial application this gem was extracted from, the people
+who decide which panes a dashboard has, in what order and at what
+size, are the people reading it, and they cannot deploy. A composition
+that lives in ERB is a file held by the wrong owner. One install
+measured a fourteen minute round trip, edit, test, lint, CI, deploy,
+poll, to add a single pane; the cost is real, but the ownership is the
+argument.
+
+The gem was already half of the way there, and the asymmetry was
+visible once pointed at. A pane is a real URL accepting `as`,
+`granularity`, `limit` and Ransack `q[...]`, so what a pane *shows*
+changes live for anyone with the link (ADR 005, ADR 007, ADR 008).
+Only *composition* was frozen in code.
+
+## Decision
+
+**A frame is a dashboard, and it is data.** Two records, created at
+runtime, with no requirement to be declared or seeded in code first:
+
+- `Janela::Frame`, one dashboard. A name, a slug, and its grid: how
+  many columns and what gap.
+- `Janela::Pane`, one visual in one frame. Its position, how many
+  columns it spans, and what it shows: model, measure, dimension,
+  renderer, granularity, limit, and an optional title of its own.
+
+**The data definition drives the HTML.** Janela renders a frame from
+its rows and the host composes nothing:
+
+```erb
+<%= janela_frame @frame %>
+```
+
+Grid, order, spans and each pane's Turbo Frame all derive from the
+data. This is the point of the change: the library is data driven and
+the markup fits the definition, rather than the definition being
+markup.
+
+**Layout uses CSS Grid's vocabulary, not a new one.** `columns` and
+`gap` on the frame, `span` on a pane. Every Rails developer knows
+these words, they map directly onto what renders with no translation
+layer, and ADR 001 argues against inventing a glossary when a shared
+one exists.
+
+**The names come from window anatomy, one level each.** Janela is
+Portuguese for window, so the gem name already carries the metaphor
+and a class called `Window` would stutter. In a window the frame is
+the fixed outer structure, the sash is the movable assembly inside it,
+and the panes are the glass. The frame holds the panes, so `Frame` is
+the container and `Pane` is the visual. `Sash`, a band of panes within
+a frame, is deliberately **not** built: `columns` on the frame plus
+`span` on a pane already express a row of single values, a full width
+time series and a row of breakdowns, which is the dashboard shape this
+project recommends. A sash would be a layer the layout does not need,
+and it stays available if nested bands ever earn one.
+
+**"Frame" now means two things, and the rule is written down rather
+than discovered.** `Janela::Frame` is a dashboard. A `<turbo-frame>`
+is the mechanism each pane is rendered inside. They sit one level
+apart, so the frame holds frames, and the ambiguity is real: a
+`Pane belongs_to :frame` gives `pane.frame_id` as a foreign key, which
+collided with the existing `frame_id` meaning the DOM id of a pane's
+turbo frame. That method is renamed `turbo_frame_id`, which is clearer
+regardless. The rule: **frame unqualified means the dashboard; the DOM
+element is always spelled turbo frame.**
+
+**The code keeps the vocabulary; the data arranges it.** Measures and
+dimensions stay declared in the `janela` block on the model, in git. A
+`Pane` row may only name a measure and a dimension that block
+declares, because `Janela.definition!` validates against the registry
+and dimensions are themselves the Ransack allowlist (ADR 002, ADR
+003). A row therefore cannot invent a query, reach a model nobody
+exposed, or widen what is filterable. This property is worth stating
+plainly, because it is precisely what is usually wrong with database
+backed dashboards, and here it falls out of what is already built.
+
+The division of labour is then: **developers define what can be asked;
+analysts arrange what is shown.**
+
+**The runtime object is `Janela::Query`.** Today's `Janela::Pane`
+conflates the thing displayed with the query it runs. With `Pane`
+taken by the persisted record, the runtime object, a definition plus a
+measure, a dimension, filters and a renderer that resolves to a
+result, becomes `Janela::Query`. A `Pane` row builds one to do its
+work.
+
+**Three editing surfaces, in this order.** All three are wanted; they
+are not alternatives.
+
+1. **Rows.** The models are the foundation, so a host, a script or an
+   agent composes a frame with ordinary ActiveRecord. This is the
+   whole of the first increment.
+2. **Forms in the engine.** Plain Rails CRUD, no canvas: add a pane by
+   choosing from the declared vocabulary, reorder, set a span, set a
+   granularity. This is the analyst's minimum and the point at which
+   the change delivers what it is for.
+3. **A visual editor.** Accepted as the direction and deferred to its
+   own ADR, because it is mostly a JavaScript design problem and
+   should not be settled in the same breath as a schema.
+
+**Authorisation is the host's, as always.** Reading and editing go
+through Pundit policies on `Janela::Frame` and `Janela::Pane` in the
+host application, the same hook every other part of the gem uses.
+Janela ships no roles.
+
+## What this supersedes in ADR 001
+
+ADR 001 listed a drag and drop report designer under what Janela would
+deliberately not build, reasoning that dashboards defined in code stay
+small, reviewable and forkable. That reasoning holds for the
+*vocabulary*, which is why measures and dimensions stay in code. It
+does not hold for *composition*, because it assumed the developer was
+the author. Everything else in ADR 001 stands: ship the load bearing
+core, prefer one obvious way, stay decoupled from any host, keep the
+codebase small enough to fork.
+
+## Consequences
+
+- A dashboard is no longer in git. It cannot be code reviewed,
+  diffed, or guaranteed identical between environments, and a
+  production frame will drift from anything staging has. This is the
+  price of the decision and it is paid knowingly: the owner of a
+  dashboard is not a person who works in git.
+- Export and import of a frame will be wanted, to move one between
+  environments and to put one under review when it matters. Not built
+  now; noted so it is not a surprise.
+- Rendering a frame is a new surface: a helper, a grid, and a
+  stylesheet, because a grid with no CSS means nothing. The missing
+  default stylesheet (#15) and inter pane layout (#29) become part of
+  this work rather than neighbours to it.
+- Snapshots (ADR 009) name their panes explicitly today. A frame gives
+  a snapshot an obvious subject: freeze a frame, not a list. A later
+  ADR, but the shape is now clear.
+- Renaming the runtime object touches the helper, both controllers,
+  the snapshot model, a view and the tests. Mechanical, pre 1.0, and
+  invisible to hosts: `janela_pane` keeps its name, so neither
+  existing installation changes.
+- Every dashboard built so far, including the demo and both hosts, is
+  ERB calling `janela_pane`. That helper keeps working. A frame is an
+  addition, not a replacement, and nothing has to move.

data/docs/decisions/013-naming-and-addressing-frames.md

@@ -0,0 +1,119 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 005, ADR 011, ADR 012
+Triggers:
+  - changing how a frame is addressed, or what a frame is called in a host's interface
+  - adding a slug, a friendly URL or a lookup other than the primary key
+  - adding or replacing the index of frames
+  - a frame slug or path segment colliding with the pane grammar
+Topics: routes, urls, naming, i18n, frames, defaults
+---
+
+# ADR 013: Naming and Addressing Frames
+
+## Context
+
+ADR 012 made a frame a database record. Three questions follow from
+that and none were settled there: what a host calls a frame in its own
+interface, how a frame is addressed, and how a person finds one.
+
+The first is the same question ADR 005 answered for the mount path.
+"Frame" is the code's word, taken from window anatomy; it is not a
+word an analyst would use. One host calls these insights, another
+reports, another dashboards, and the difference is business language
+rather than preference.
+
+The second has a trap. ADR 005 published the pane grammar as
+`/<mount>/:model/:measure(/:dimension)`. A frame addressed directly
+under the mount, `/insights/vamos-review`, cannot be distinguished
+from the start of a pane URL: Rails cannot tell a frame slug from a
+model route key, and the frame route would shadow every pane.
+
+## Decision
+
+**What a frame is called comes from i18n, not from configuration.**
+The class stays `Janela::Frame`, and every label the engine renders
+uses `Frame.model_name.human`, so a host renames it in its own locale
+file:
+
+```yaml
+en:
+  activerecord:
+    models:
+      janela/frame:
+        one: "Dashboard"
+        other: "Dashboards"
+```
+
+This adds no setting, uses the mechanism Rails already has, and
+composes with real translation rather than only relabelling. Janela
+ships English defaults.
+
+**Frames live under their own path segment, and that segment is the
+host's.** A single configurable value, defaulting to `dashboards`
+because that is the word most hosts want and no one should have to
+read the gem to like the default:
+
+```
+/insights/dashboards            every frame
+/insights/dashboards/3          one frame
+/insights/orders/revenue/status a pane, grammar unchanged
+```
+
+The segment removes the collision entirely, so the pane grammar from
+ADR 005 needs no constraints or disambiguation and stays exactly as
+published.
+
+**A frame is addressed by its primary key, the Rails way.**
+`resources :frames` inside the engine, looked up with
+`find(params[:id])`. No slug column, therefore no uniqueness rules, no
+reserved word list, no regeneration on rename, and no second lookup
+path to keep working.
+
+If readable URLs are wanted later, the Rails answer is to override
+`to_param` to return `"3-quarterly-review"`. Rails resolves that back
+through `to_i`, so lookups do not change and nothing has to be
+unique. That is an option for a host or a later decision here, not a
+schema.
+
+**Using `resources` is also the editing surface.** ADR 012's second
+editing surface, plain forms in the engine, is `index`, `new`, `edit`,
+`update` and `destroy` on that resource. Choosing the conventional
+route shape means the forms are the framework's defaults rather than
+something invented.
+
+**Janela ships an index, and a host may ignore it.** The mount's frame
+segment renders a grid of cards, one per frame, with its name, how
+many panes it has and when it changed. That is enough for a host to
+install the gem and navigate on the same day, which is the point.
+
+A host that wants something else writes its own page over
+`Janela::Frame.all` and never routes to ours. This is the pattern from
+ADR 011: ship a default that works, let the host replace it, add no
+configuration for the choice.
+
+**A richer browse is not this decision.** Rows grouped by category,
+horizontal scrolling and hover previews are a different size of
+feature, and a preview in particular is expensive because a thumbnail
+means rendering panes. The card grid is the default; anything more
+earns its own ADR once a host has enough frames to justify browsing
+rather than listing.
+
+## Consequences
+
+- Nothing in a host's interface says "frame" unless the host wants it
+  to, and the word in the URL is the host's too. The code keeps one
+  vocabulary and the reader keeps theirs.
+- One configuration value is added, for the path segment. It is
+  justified on the same grounds as ADR 005's mount path: it appears in
+  a URL a person reads. The noun in labels deliberately is not
+  configuration, because i18n already does it.
+- Integer ids mean a frame URL is not self describing. `to_param` is
+  the escape hatch and costs nothing to adopt later.
+- The index is a new view in the engine, so it is more surface to
+  style, which reinforces that the default stylesheet (#15) is part of
+  this body of work and not adjacent to it.
+- Frames being a conventional Rails resource means the forms surface
+  arrives largely for free, which moves ADR 012's second editing stage
+  closer than it looked.