janela 0.8.0 → 0.9.0

data/docs/decisions/039-a-pane-can-hold-words-and-only-code-writes-markup.md

@@ -0,0 +1,168 @@
+---
+Date: 2026-09-24
+Status: Accepted
+Related: ADR 001, ADR 009, ADR 012, ADR 016, ADR 036, ADR 037
+Triggers:
+  - putting a heading, a paragraph, a link, an icon or an image on a stored frame
+  - adding a kind of pane that is not a query
+  - letting an analyst's text reach a page
+  - storing HTML, Markdown or a template in a row
+  - deciding whether a frame draws its own name
+Topics: frames, panes, persistence, layout, authorisation, html
+---
+
+# ADR 039: A Pane Can Hold Words, and Only Code Writes Markup
+
+## Context
+
+ADR 012 made a dashboard data so that its author, the analyst, can
+change it without a deploy. It gave the analyst one thing to arrange:
+a pane that names a measure the model declared. That was the whole
+vocabulary, and it is why a stored frame is safe to hand over. A row
+cannot invent a query, reach a model nobody exposed, or put anything on
+the page that a developer did not write.
+
+A real dashboard is more than query results. The first one a host asked
+about had, above its numbers, a heading with an icon, a count of done
+out of total, a percentage, a "view all" link and a progress bar. A
+block form frame can have all of it, because the page around the panes
+is the host's own ERB (docs/composing.md). A stored frame can have none
+of it. `janela/frames/_frame` renders `frame.panes` and nothing else,
+and `Janela::Pane` requires a `measure` and validates it against a
+`janela` block, so there is no row a heading could be. The frame's
+`name` is never drawn either. The analyst who owns the dashboard can
+choose every number on it and cannot label them.
+
+So the question is not whether a stored frame should hold content. It
+has to, or the frame the analyst owns is always the unlabelled half of
+the page. The question is what an analyst may put in a row without
+breaking the property ADR 012 was built on.
+
+### What was considered
+
+**Stored HTML**, a column of markup rendered as it is, was rejected.
+It is the one thing ADR 012 exists to prevent: an analyst's row would
+put arbitrary markup on a page that every other reader of that frame
+loads, which is stored cross site scripting with a dashboard for a
+delivery mechanism. Running it through Rails' `sanitize` narrows the
+tags but not the problem. The allowlist becomes a security boundary
+Janela has to maintain, and what survives it, links anywhere and
+styling that imitates the host's own chrome, is still content a
+developer did not write appearing as if they had.
+
+**Markdown** was rejected for the same reason one step removed. It
+compiles to HTML, it needs a parser as a dependency (ADR 001 is spare
+with those), and a link in it can point anywhere. What an analyst
+actually needs from it, a heading and a paragraph, is two fields.
+
+**A sandboxed iframe**, `<iframe srcdoc sandbox="allow-scripts">`, was
+considered because an application built on this gem already renders
+agent-authored slides that way, and it works: the sandbox gives the
+content an opaque origin, so it cannot read the page or its cookies.
+It was rejected for a public gem. The surface is large, the
+guarantees depend on attributes a host can loosen, and an iframe does
+not size to its content, so it cannot sit in a CSS grid beside a pane
+without fixed heights, which is exactly what #24 is trying to remove
+for charts. It stays available to any host that wants it, in its own
+code, around a frame.
+
+**Drawing the frame's name as a heading** was rejected as the whole
+answer. It would change every existing frame's appearance on upgrade,
+it gives one heading per frame when a dashboard often wants one per
+row, and it still leaves no icon, no paragraph and no link.
+
+**A separate table of content rows** beside `janela_panes` was
+rejected because position is the frame's single ordering. Two tables
+would need a shared position sequence across them, and ADR 012 kept
+one level between a frame and what it shows on purpose.
+
+## Decision
+
+**A pane can hold words instead of a query. An analyst writes text
+into a row and Janela escapes it; anything that needs markup is a
+partial the host wrote in code, which the analyst places by name.**
+
+This is ADR 012's division of labour applied to content: developers
+define what can be shown, analysts arrange it and write the words.
+
+**A pane gains a `kind`.** `query` is today's pane and the default, so
+every existing row is unchanged. Two more kinds:
+
+- **`text`**: a `heading`, a `body` and an optional `link`, each a
+  plain string. Janela renders the heading as a heading, the body as
+  paragraphs split on blank lines, and the link as an anchor, and
+  escapes all three. No markup an analyst types reaches the page as
+  markup.
+- **`partial`**: a `partial` name, plus the same `heading`, `body` and
+  `link` passed to it as locals. The partial is the host's, under
+  `app/views/janela_content/`, so the host writes the icon, the image,
+  the layout and the look, and the analyst writes the words that go in
+  it. A name must match `/\A[a-z0-9_]+\z/` and a partial must exist in
+  that directory, so a row cannot reach any other template. There is
+  no registry and no setting: the directory is the allowlist, the way
+  a controller's views directory already is. It sits outside
+  `app/views/janela/` on purpose. A host view at an engine's path
+  replaces the engine's own, and `janela/panes/` already holds the
+  engine's `_form` and `_row`, so a content partial named `form` there
+  would silently replace the pane editing form.
+
+```ruby
+frame.panes.create!(kind: "text", heading: "Refunds are excluded",
+                    body: "Figures are in the store's own currency.")
+frame.panes.create!(kind: "partial", partial: "overview_heading",
+                    heading: "Project overview", link: "/cards", span: 3)
+```
+
+A `text` or `partial` pane has no `model` or `measure`. Those columns
+become nullable, and a validation requires them for `query` and
+refuses them for the other two, so the database cannot hold a
+half-query.
+
+**A link is a path, not a URL.** `link` must start with `/`, and not
+`//`, so an analyst can point readers at another page of the same
+application and cannot send them to another site. A host that wants an
+external link writes it in a partial.
+
+**Images and icons are the host's.** Janela stores no files and ships
+no icon set (ADR 036). A heading with an icon is a partial that draws
+the icon beside the heading it is given. An image is a partial that
+reads it from wherever the host already keeps images. Janela does not
+take a dependency on Active Storage to do something a host's own
+partial already can.
+
+**A content pane sits in the grid like any other.** It spans columns,
+it is ordered by `position`, it is drawn as a `janela-pane`, and under
+vitral it is a pane of glass. It does not take part in cross filtering:
+it has no query, so the frame controller has no `src` to rewrite, and a
+content pane renders inline rather than inside a turbo frame.
+
+## Consequences
+
+- An analyst can label a stored frame, explain it and link out of it
+  without a deploy, which is the half of ADR 012 that was missing.
+- The property ADR 012 stated plainly still holds, extended: a row can
+  name only a declared measure, an escaped string, a same-site path, or
+  a partial a developer wrote. Nothing an analyst types is markup.
+- `janela_panes` gains `kind`, `heading`, `body`, `link` and `partial`,
+  and `model` and `measure` become nullable. That is a migration a host
+  has to install, so it needs an `UPGRADING.md` entry (ADR 015). The
+  engine's own forms need a way to add each kind.
+- The pane partial becomes a branch on `kind`. `_pane.html.erb` is the
+  smallest file this touches and should stay that way: one partial per
+  kind under `janela/frames/`, chosen by name.
+- Snapshots store results, not HTML (ADR 009). A snapshot is a list of
+  pane results with no frame behind it, so a content pane has no result
+  to store and is not in one. Words that explain a signed off figure
+  have to live in whatever page shows the snapshot. If a snapshot ever
+  needs to carry the text that sat beside its numbers on the day, that
+  is a separate decision.
+- The pane class names a theme may target (ADR 036) gain one for the
+  content kinds, `janela-content`, and it goes into docs/theming.md in
+  the same change.
+- Not in 1.0 (ADR 037). It adds to the public surface rather than
+  changing it, so it does not block a stable release and can land
+  before or after one.
+- What would change this decision: a host that genuinely needs an
+  analyst to author markup, with a real reason a partial cannot serve.
+  The sandboxed iframe is the fallback that case would reopen, and this
+  record says why it was set aside.

data/docs/decisions/040-a-host-can-fix-a-frames-filter.md

@@ -0,0 +1,145 @@
+---
+Date: 2026-09-24
+Status: Accepted
+Related: ADR 003, ADR 008, ADR 012, ADR 024, ADR 025, ADR 030, ADR 032, ADR 034
+Triggers:
+  - showing a frame on a record's own page, filtered to that record
+  - reusing one frame across many records
+  - carrying a host's filter in q[...] and finding it cleared
+  - deciding whether a filter is a view choice or an authorisation boundary
+  - changing how a pane URL is built, or what clear() and toggle() touch
+Topics: frames, filters, cross-filtering, urls, authorisation
+---
+
+# ADR 040: A Host Can Fix a Frame's Filter, and No Click Removes It
+
+## Context
+
+A host wants the same dashboard on every record's page, narrowed to
+that record: a frame of the work in a queue, shown at the top of each
+queue's page. Since ADR 012 a frame is a row an analyst edits, so the
+panes are the same everywhere and only the record changes. Janela has
+no way to say "this frame, for this record" (#57).
+
+The only filter Janela knows is the one in the page URL, `q[...]`
+(ADR 008). So a host redirects the record's page to carry one,
+`/queues/42?q[queue_id_eq]=42`, and the panes read it. Measured on the
+demo with `q[status_eq]=paid` standing in for the host's filter, it
+does not hold:
+
+- Opened with the filter, the revenue pane read $469,097.85 and every
+  pane's `src` carried `q[status_eq]=paid`.
+- **Clear filters**, the button a dashboard shows, took it off. Revenue
+  read $664,639.01, the whole table, and the page URL lost the
+  parameter.
+- **Escape**, with focus inside the frame, did the same.
+- A click on a `status` value would replace it, because `toggle()`
+  clears every predicate on the dimension it is changing (ADR 024).
+
+None of this is a bug in the frame controller. `q[...]` is Janela's by
+design: `stripFilters` removes every `q[` key before writing the
+current selection, and `clear()` empties the frame's filters, because
+the selection is the reader's to change. A host's filter placed there
+becomes the reader's to change too. On a record's page the reader then
+sees every record their scope allows under that record's heading.
+Nothing leaks, since `policy_scope` still bounds every pane (ADR 032).
+The numbers are wrong, and they look right.
+
+### What was considered
+
+**Making `clear()` leave the host's keys alone** was rejected. The
+controller cannot tell a host's `q[queue_id_eq]` from a reader's link
+that carries the same key, and ADR 008 means a shared link carries
+exactly that. Any rule for telling them apart would be a second
+convention inside one parameter.
+
+**The host's `policy_scope`** was rejected. It answers who may see
+which rows, and it runs in the engine's pane requests, which know
+nothing about the page that holds the frame. Putting a page's record
+into it would make authorisation depend on which page a pane was
+loaded from, and ADR 032's checks would be reasoning about a scope that
+changes per page.
+
+**Storing the filter on the frame**, a `filters` column on
+`janela_frames`, was rejected as the answer to this case. The case is
+one frame reused across many records, so the filter belongs to the
+render, not to the row. A frame that should always be narrowed the
+same way is a smaller, different case, and it can be built on this
+later.
+
+**Signing the filter**, carrying it as a `MessageVerifier` token so a
+reader cannot edit it, was rejected. It would imply a security
+guarantee this is not. A reader who edits the fixed filter out of a
+pane URL sees rows `policy_scope` already lets them see, which they
+could see on any other dashboard. Signing adds a key to rotate and a
+failure mode to explain, to protect nothing that authorisation does
+not already protect.
+
+## Decision
+
+**A host passes a filter when it renders a frame, and Janela applies it
+to every pane beneath the reader's selection, where no click, clear or
+link can remove it.**
+
+```erb
+<%= janela_frame @frame, where: { queue_id_eq: @queue.id } %>
+
+<%= janela_frame where: { queue_id_eq: @queue.id } do %>
+  <%= janela_pane Card, :count, by: :status %>
+<% end %>
+```
+
+`where:` is the name `Definition#query` already uses for the same
+thing, Ransack conditions narrowing a relation, so a host learns one
+word for it.
+
+**It travels in the pane's base URL under its own key, `where[...]`.**
+The helper writes it into each pane's `data-janela-src`, the base the
+frame controller builds every request from, and into the first
+render's `src`. The controller never reads or writes `where[...]`:
+`stripFilters` removes only `q[` keys, `clear()` empties only the
+frame's filters, and `toggle()` changes only `q[`. So the fixed filter
+survives every click without the controller learning anything about
+it. It is not written into the page URL, which already says what the
+record is.
+
+**The server applies it first and separately.** The pane endpoints
+read `params[:where]` and `params[:q]` and narrow the relation twice,
+fixed filter first, so the reader's selection can only narrow further.
+The same key in both is two conditions ANDed, never one replacing the
+other. The fixed filter goes through `Definition#filter`, so it is
+bounded exactly as `q[...]` is: only declared dimensions, only the
+predicates ADR 025 allows for each kind, and no more than 1000 values.
+A host cannot fix a filter on a column it has not declared, which is
+the same rule a reader already meets.
+
+**It is a view filter, not an authorisation boundary, and the
+documentation says so in those words.** It is visible in every pane's
+URL, and a reader can remove it by editing one. What they reach by
+doing that is what `policy_scope` already allows. A host that needs a
+reader not to see other records writes that in its scope, where it
+applies to every pane on every page.
+
+## Consequences
+
+- One frame serves every record's page. An analyst edits it once, and
+  the host needs no column pointing at a frame per record.
+- A host that carries its filter in `q[...]` today, by redirect, moves
+  it to `where:` and drops the redirect. Nothing breaks if it does not
+  move; the old way keeps its old weakness. The guide for this goes in
+  docs/composing.md.
+- The pane URL shape gains `where[...]`. ADR 037 names the pane URL as
+  part of the surface that stops moving at 1.0, so this is better
+  decided before 1.0 than after, and it is additive: every existing URL
+  means what it meant.
+- A snapshot is taken with the filters its caller passes (ADR 009,
+  ADR 034), not from a rendered page. A host snapshotting a record's
+  frame passes the fixed filter in `filters:`, and nothing does that
+  for it. Worth a line in the snapshot documentation, not a mechanism.
+- The dimension the host fixes should not also be offered as a
+  clickable pane. Clicking it would AND a second condition on the same
+  column, and any value but the fixed one returns nothing. That is
+  correct and confusing, so the guide says not to.
+- What would change this decision: a host that needs the fixed filter
+  hidden from the reader for a reason `policy_scope` cannot express.
+  That would reopen signing, and this record says why it was left out.

data/docs/decisions/041-a-host-finds-its-frame-by-owner-and-key.md

@@ -0,0 +1,112 @@
+---
+Date: 2026-09-24
+Status: Accepted
+Related: ADR 012, ADR 013, ADR 014, ADR 019, ADR 040
+Triggers:
+  - giving a record of the host's its own frame
+  - finding a frame from code without storing its id
+  - an owner that has more than one frame
+  - adding a slug, a handle or any second identifier to a frame
+Topics: frames, persistence, naming, host-integration
+---
+
+# ADR 041: A Host Finds Its Frame by Owner and Key
+
+## Context
+
+A host that shows a frame on one of its own pages has to find that
+frame from code. ADR 012 made frames rows an analyst edits, and ADR 040
+made one frame usable across many records, so the host needs a way to
+say "the frame for this" without a deploy creating it and without
+remembering an id.
+
+The owner looked like the answer. It is a nullable polymorphic
+reference that Janela never reads (ADR 014, ADR 019), so a host can
+point it at the record the frame is for, and
+`Janela::Frame.find_or_create_by!(owner: queue)` is a frame's `dom_id`:
+two columns, nothing added to the host's schema.
+
+It holds for exactly one frame per owner, and owners rarely have one. A
+tenant owns every frame an analyst makes from the engine's New button,
+through `janela_frame_owner`, and a host wants frames of its own for
+particular pages on top of those. `find_by(owner: account)` then returns
+whichever row the database gives first. On a real installation it
+returned the wrong frame: the first the tenant had ever made, not the
+one the page was for (#59).
+
+### What was considered
+
+**`name` as the key** was rejected. It is the analyst's to rename, so a
+host looking a frame up by name loses it the day someone edits the
+title.
+
+**A column in the host's table** pointing at the frame was rejected as
+the answer the owner was meant to save a host from. It needs a
+migration on every table whose records want a frame, and a second one
+for each extra frame per record.
+
+**A slug**, which ADR 013 turned down, is not what is being asked for,
+and the difference is the reason this is allowed. ADR 013 rejected a
+slug as a way to *address* a frame: in a URL a person reads, derived
+from the name, needing uniqueness rules, reserved words and regeneration
+on rename, and a second lookup path to keep working. What a host needs
+is none of those. It is an identifier the host writes in its own code,
+never in a URL, never derived from the name, never shown to an analyst,
+and never changed once set.
+
+**Janela choosing the frame for a record**, a registry mapping host
+classes to frames, was rejected as configuration for something one line
+of the host's code already says.
+
+## Decision
+
+**A frame may carry a `key` the host sets. A frame is found by its
+owner and its key together, and each owner has at most one frame per
+key.**
+
+```ruby
+Janela::Frame.for(account, :overview)         # the tenant's overview
+Janela::Frame.for(queue, :analytics)          # this queue's frame
+Janela::Frame.for(queue, :analytics) { |frame| frame.name = "#{queue.name} analytics" }
+```
+
+`for` finds the frame with that owner and key, or creates it. The block
+runs only when it creates one, to set what the host wants a new frame to
+start as; a new frame is named after its key unless the block says
+otherwise. The owner may be `nil` for a host with one tenant.
+
+**The key is the host's and nobody else's.** Janela reads it only in
+`for`. It is not in any route and not in the engine's forms, so an
+analyst can rename, regrid and recompose a keyed frame without being
+able to detach it from the page that finds it. A frame without a key,
+which is every frame an analyst makes, is unchanged.
+
+**Uniqueness is per owner, in the database.** A unique index on owner
+and key, so two requests creating the same frame at once end with one
+row, and `for` retries the find when the insert loses that race. Frames
+with no key are not constrained by it.
+
+`key` is a short lowercase string matching `/\A[a-z0-9_]+\z/`, the
+shape of the symbols a host will pass, so `:analytics` and `"analytics"`
+are the same key and nothing that looks like a URL or a name gets in.
+
+## Consequences
+
+- A host gives any record any number of frames with no column of its
+  own: owner and key are the `dom_id`, and the key is the suffix
+  `dom_id(queue, :analytics)` would carry.
+- `janela_frames` gains `key` and a unique index, so a migration and an
+  `UPGRADING.md` entry (ADR 015). Existing frames keep a nil key.
+- The owner now does two jobs for a host that uses `for`: tenancy for
+  the policy scope, and which record a frame belongs to. ADR 019 said
+  Janela never reads the owner; `for` queries by it, and only there. A
+  host whose owner is a record rather than its tenant has to make its
+  policy scope see frames owned by its own records, which the
+  multi-tenancy guide shows.
+- A frame deleted from the engine's pages is created again, empty, the
+  next time its page is visited. That is the right answer for a frame a
+  page depends on, and it is worth a line in the README so it is not a
+  surprise.
+- What would change this decision: a host needing to find a frame by
+  something that is not stable in its own code. That is the addressing
+  problem ADR 013 decided, and it would be decided there again.

data/docs/decisions/042-a-charts-title-is-a-figcaption.md

@@ -0,0 +1,174 @@
+---
+Date: 2026-09-28
+Status: Accepted
+Related: ADR 016, ADR 018, ADR 024, ADR 026, ADR 036
+Triggers:
+  - adding a title, caption or visible label to any renderer
+  - changing what a chart pane's markup contains, or what carries its classes
+  - extending or reading `.janela-own-headings`
+  - deciding what a theme may target in `janela.css` (ADR 036)
+  - a chart type that cannot sit inside a figure the way bar and line do
+Topics: rendering, charts, accessibility, styling, public-api, theming
+---
+
+# ADR 042: A Chart's Title Is a Figcaption, and the Canvas Points to It
+
+## Context
+
+#61 found that a chart pane (`renderer: bar` or `renderer: line`) never
+shows its title to a sighted reader. `janela/queries/_query.html.erb`
+renders it as a bare `<canvas role="img" aria-label="<%= query.title
+%>">`, and `chart_controller.js` passes the same string only into the
+dataset's `label`, with the legend that would draw it turned off. A
+table pane's `<caption>` and a single value pane's `<span
+class="janela-value-label">` both render the same `query.title` as
+visible text. A chart pane is the one renderer that does not.
+
+This is not new. #26's own investigation, closed and shipped in 0.8.0,
+already found and recorded the same fact while building
+`.janela-own-headings`:
+
+> The table's and the single value's are visible ... The chart's is
+> not ... A chart pane is already announced without being seen.
+
+#26 used that as the *model* the other two renderers should be brought
+into line with for hiding purposes, not as a gap to close, and the
+comment above `.janela-own-headings` in `janela.css` still says so:
+"a chart pane needs nothing: its title was only ever an aria-label."
+That sentence is accurate about the code and wrong about the design.
+Nobody decided a chart should be the one renderer with no visible
+title; it fell out of `legend: { display: false }` turning off the
+only thing that would have drawn it.
+
+### Why the issue's own fix does not hold up
+
+#61 proposes `plugins.title: { display: true, text: this.titleValue }`,
+Chart.js's own title option. It works, and it was rejected, for three
+reasons that all come from the same place: the text would live inside
+the canvas bitmap rather than in the document.
+
+- **It cannot be hidden by `.janela-own-headings`.** That rule hides
+  the table's `<caption>` and the value's `<span>` visually while
+  leaving them in the accessibility tree, by targeting real elements
+  with CSS (#26). A host with its own heading above a chart pane would
+  have no way to suppress the canvas-drawn one short of reconfiguring
+  Chart.js, so the one mechanism #26 shipped for this exact problem
+  would not cover the one renderer it was modelled on.
+- **It contradicts ADR 026 directly**, not just in spirit. That
+  decision's third numbered point is "every renderer degrades to
+  something readable with no JavaScript, because a pane is rendered on
+  the server before anything runs." A title Chart.js paints is not
+  there until the chart runtime has loaded and `connect()` has run;
+  server-rendered text is there in the same response that draws the
+  rest of the pane.
+- **It is not text.** Not selectable, not found by the browser's find
+  bar, not sized by the vitral theme's typography, not read by a
+  screen reader that has switched off image descriptions but still
+  reads a page's headings.
+
+None of that is a knock on Chart.js. It is the same argument ADR 026
+already settled for the chart itself: a renderer draws in HTML unless
+it genuinely cannot, and a caption is not a case a canvas is needed for.
+
+### Where the title should live
+
+A table pane already pairs a `<table>` with a `<caption>`. HTML has the
+matching pair for an image with a caption: `<figure>` and
+`<figcaption>`. Wrapping the existing canvas in one costs nothing Chart.js
+cares about, since `new Chart(this.element, ...)` still receives the
+canvas itself, unchanged.
+
+One thing about that pairing had to be checked rather than assumed:
+`<figcaption>` gives its text to the `<figure>` as a description, not
+to an arbitrary element nested inside it. A screen reader is not
+guaranteed to treat the figcaption as the canvas's own accessible name
+just because it sits beside it. The canvas needs an explicit
+`aria-labelledby` pointing at the figcaption's id; the implicit
+figure/figcaption pairing is not enough on its own and this record
+does not lean on it.
+
+### What was considered
+
+**Chart.js's `plugins.title`**, #61's own suggestion. Rejected above.
+
+**A bare sibling, `<div class="janela-chart-title">` before an
+unwrapped canvas.** Considered and rejected only because HTML already
+has the element built for exactly this pairing, and using it costs
+nothing: a chart pane on its own page already reads as a captioned
+figure to a browser's own outline, not just to Janela's CSS.
+
+**Leaving `aria-label` on the canvas alongside the new visible text.**
+Rejected: two independent strings for the same title can drift, and
+`aria-labelledby` pointing at the one that is now visible cannot.
+
+## Decision
+
+**A chart pane's title is a `<figcaption>` inside a `<figure>` that
+wraps the canvas, and the canvas's accessible name is
+`aria-labelledby` pointing at it.**
+
+```erb
+<figure class="janela-pane">
+  <figcaption class="janela-chart-title" id="<%= title_id %>"><%= query.title %></figcaption>
+  <canvas class="janela-chart"
+          data-controller="janela--chart"
+          ...
+          role="img" aria-labelledby="<%= title_id %>"></canvas>
+</figure>
+```
+
+**`janela-pane` moves from the canvas to the figure; `janela-chart`
+stays on the canvas.** The figure is now the grid item and the thing a
+theme styles as a pane, the same job `<table class="janela-pane">` and
+`<p class="janela-pane janela-value">` already do for the other two
+renderers. The canvas keeps `janela-chart` because that is what
+`canvas.janela-chart { width: 100% !important; max-height: 20rem; }`
+and the Stimulus controller both already target, and because #61's own
+system test selects `canvas.janela-chart` directly; nothing that
+selects the canvas by that class alone stops matching. What stops
+matching is anything that selected `.janela-pane.janela-chart` as one
+element, which is the breaking part of this change.
+
+**`janela-chart-title` joins the pane primitives on the contract**
+(ADR 036), the same group `janela-value-label` and a table's `caption`
+selector are already in. Its base legibility rule (size, weight,
+spacing) goes in `janela.css` next to the other two, not in vitral,
+for the same reason theirs does: a pane has to be legible with no
+theme installed.
+
+**`.janela-own-headings` gets a third rule.** It already hides the
+table's caption and the value's label visually while keeping them in
+the accessibility tree; `figcaption.janela-chart-title` joins that
+selector, and the comment above it that says a chart pane needs
+nothing is corrected to say why it no longer does.
+
+**Chart.js's dataset `label` and the disabled legend are unchanged.**
+The visible title no longer depends on either, which is the point:
+it is there whether or not the chart runtime ever finishes loading.
+
+## Consequences
+
+- A chart pane finally shows its title the way the other two renderers
+  do, closing #61 and the half of #26 that was left standing on
+  purpose.
+- Breaking change: `janela-pane` is no longer on the `<canvas>`, and
+  `aria-label` is replaced by `aria-labelledby`. Anything a host wrote
+  against either goes in `UPGRADING.md` (ADR 015), and the doctor's
+  list of things to check for an old release is worth a line.
+- `docs/theming.md` gains `janela-chart-title` in the pane primitives
+  table (ADR 036), and `janela.css` gains its rule and its line in
+  `.janela-own-headings`.
+- The system test in `test/system/chart_test.rb` asserts
+  `canvas.janela-chart[aria-label='...']` today; it moves to asserting
+  the figcaption's text and the `aria-labelledby` wiring, which is
+  build work, not a decision.
+- Chart.js keeps drawing bar and line exactly as it does today; nothing
+  about `chart_controller.js`'s own options needs to change for this,
+  only the markup around it.
+- What would change this decision: a chart type that cannot sit inside
+  a figure the way bar and line do, or a case where wrapping the canvas
+  measurably breaks Chart.js's own sizing against its parent. Neither
+  is expected, since the canvas already sits one level inside a turbo
+  frame today and gains only one more ordinary block-level ancestor,
+  but it is exactly the kind of assumption to re-check against the demo
+  before the build lands rather than after.

data/docs/decisions/INDEX.md

@@ -21,24 +21,25 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | Topic | ADRs |
 |-------|------|
 | **Vision, scope, forkability** | 001, 010, 012, 037 |
-| **Open-source & host-decoupling** | 001, 022, 036 |
-| **DSL & query layer** | 002, 006, 007, 020, 025 |
+| **Open-source & host-decoupling** | 001, 022, 036, 041 |
+| **DSL & query layer** | 002, 006, 007, 020, 025, 038 |
 | **Dependencies** | 002, 003, 004, 006, 017, 025 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040 |
 | **Performance & storage** | 007, 017, 025 |
-| **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025 |
-| **Layouts & views** | 011, 012, 016, 018, 020, 027 |
-| **CSS & styling** | 016, 018, 023, 026, 027, 036 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033 |
+| **Ordering & formatting** | 007, 020, 038 |
+| **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025, 040 |
+| **Layouts & views** | 011, 012, 016, 018, 020, 027, 039 |
+| **CSS & styling** | 016, 018, 023, 026, 027, 036, 042 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041 |
 | **Naming rule** | 014, 023, 036 |
-| **JavaScript delivery & charts** | 004, 006, 026 |
+| **JavaScript delivery & charts** | 004, 006, 026, 042 |
 | **Time dimensions** | 006, 025 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041 |
 | **Snapshots & publishing** | 009, 020, 028, 033, 034 |
 | **AI agents & guidance** | 010, 015, 021 |
 | **The doctor & checks** | 021, 025, 032, 033, 035 |
-| **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037 |
-| **Accessibility & keyboard** | 024 |
+| **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037, 042 |
+| **Accessibility & keyboard** | 024, 042 |
 | **Security** | 003, 025, 028, 031, 032, 034, 035 |
 | **Testing** | 003 |
 | **Roadmap & planning** | 001, 037 |
@@ -84,7 +85,12 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 035 | A Check Does What Janela Does, or It Says What It Saw | 2026-09-22 | Accepted |
 | 036 | Janela Publishes What a Theme May Target, and Vitral Is Only One | 2026-09-22 | Accepted |
 | 037 | 1.0 Means the Surface Stops Moving, Not That Janela Is Finished | 2026-09-23 | Accepted |
+| 038 | A Ratio Is a Measure of Its Own, Stored as a Fraction and Read as a Percentage | 2026-09-24 | Proposed |
+| 039 | A Pane Can Hold Words, and Only Code Writes Markup | 2026-09-24 | Accepted |
+| 040 | A Host Can Fix a Frame's Filter, and No Click Removes It | 2026-09-24 | Accepted |
+| 041 | A Host Finds Its Frame by Owner and Key | 2026-09-24 | Accepted |
+| 042 | A Chart's Title Is a Figcaption, and the Canvas Points to It | 2026-09-28 | Accepted |
 
 ## Next number
 
-Next ADR: 038
+Next ADR: 043