janela 0.7.0 → 0.9.0

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

@@ -20,26 +20,29 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 
 | Topic | ADRs |
 |-------|------|
-| **Vision, scope, forkability** | 001, 010, 012 |
-| **Open-source & host-decoupling** | 001, 022 |
-| **DSL & query layer** | 002, 006, 007, 020, 025 |
+| **Vision, scope, forkability** | 001, 010, 012, 037 |
+| **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 |
+| **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 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033 |
-| **Naming rule** | 014, 023 |
-| **JavaScript delivery & charts** | 004, 006, 026 |
+| **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, 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 |
-| **Releases & upgrades** | 015, 021, 032, 034 |
-| **Accessibility & keyboard** | 024 |
-| **Security** | 003, 025, 028, 031, 032, 034 |
+| **The doctor & checks** | 021, 025, 032, 033, 035 |
+| **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 |
 
 ## Chronological
 
@@ -79,7 +82,15 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 032 | Janela Will Not Read a Model It Cannot Scope | 2026-09-20 | Accepted |
 | 033 | A Snapshot Is Told Who Owns It | 2026-09-21 | Accepted |
 | 034 | Janela Will Not Freeze a Scope the Host Has Not Named | 2026-09-21 | Accepted |
+| 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: 035
+Next ADR: 043

data/docs/multi-tenancy.md

@@ -149,6 +149,28 @@ save failed silently. `bin/rails janela:doctor` reports this for you:
 it asks your policy for a scope over frames and looks for an owner in
 what comes back.
 
+### A frame of your own for a page
+
+Your code finds a frame it keeps for one of its pages by owner and key
+(ADR 041):
+
+```ruby
+Janela::Frame.for(Current.account, :overview)
+Janela::Frame.for(queue, :analytics) { |frame| frame.name = "#{queue.name} analytics" }
+```
+
+When the owner is the tenant, nothing changes in your policy. When it is
+one of your own records, such as the queue above, the frame belongs to
+the tenant through that record, and your scope has to say so or the
+frame is hidden from the people it was made for:
+
+```ruby
+def resolve
+  scope.where(owner: Current.account)
+       .or(scope.where(owner_type: "Queue", owner_id: Current.account.queues.select(:id)))
+end
+```
+
 ## Snapshots
 
 A snapshot carries the same polymorphic owner a frame does, so your

data/docs/naming.md

@@ -44,6 +44,13 @@ from the thing itself rather than from a list of synonyms for "chart".
 | **Query** | The runtime object that calculates one pane | Not a window word, on purpose. It is an implementation detail rather than something a person arranges, so it gets the plain name for what it does. |
 | **Grid** | How a frame is divided: `columns`, `gap`, and each pane's `span` | A window is divided into panes, and the grid is the division. Small integers that choose a class the stylesheet already defines, so nothing an analyst types reaches CSS (ADR 016). |
 | **Vitral** | The optional stained glass theme | A stained glass window, in the same language. See ADR 023. |
+| **Vista** | The roadmap | The view through the window. What you can see from here is also what is ahead: *outlook* and *prospect* carry the same double meaning in English, and this one carries it in Portuguese. |
+| **Horizonte** | The roadmap's far half: wanted, not blocking a release | The horizon is the edge of what you can see. Work still in sight, as against work that is not in the picture at all. |
+
+The last two are a step away from anatomy. A window's parts name the
+things a host arranges; what you see through it names the things the
+project has not built yet. Both halves come from the same object, which
+is the point of picking an object rather than a list of synonyms.
 
 The anatomy was argued over before it was settled. *Sash* was
 considered for the dashboard and rejected: a sash is one layer inside a

data/docs/roadmap.md

@@ -0,0 +1,218 @@
+---
+Topics: roadmap, releases, scope, planning
+---
+
+# Vista
+
+<p style="text-align: center;">Vista shows where Janela is heading.</p>
+
+<svg viewBox="0 0 680 360" width="100%" role="img" aria-labelledby="vista-title vista-desc" class="vista-art" style="display: block; margin: 1.75rem 0; border-radius: 10px;">
+  <title id="vista-title">Vista</title>
+  <desc id="vista-desc">Sea and sky with a horizon across them. Eight lights burn on the near water, one for each issue in 1.0, and three sit far off at the horizon for the work still in sight past it. A low sun rises and sets on the horizon as the pointer moves up and down, and never climbs higher: the sky above is empty, because what is not coming is not in view.</desc>
+
+  <style>
+    .vista-art .v-far { transform: translate3d(calc(var(--vitral-shift-x, 0) * 13px), calc(var(--vitral-shift-y, 0) * 7px), 0); transition: transform .45s cubic-bezier(.2,.7,.3,1); }
+    .vista-art .v-mid { transform: translate3d(calc(var(--vitral-shift-x, 0) * 6px), calc(var(--vitral-shift-y, 0) * 3px), 0); transition: transform .45s cubic-bezier(.2,.7,.3,1); }
+    .vista-art .v-near { transform: translate3d(calc(var(--vitral-shift-x, 0) * -8px), calc(var(--vitral-shift-y, 0) * -4px), 0); transition: transform .45s cubic-bezier(.2,.7,.3,1); }
+    .vista-art .v-glow-a { opacity: calc(.6 - var(--vitral-shift-x, 0) * 1.2); transform: translate3d(calc(var(--vitral-shift-x, 0) * -40px), calc(var(--vitral-shift-y, 0) * 16px), 0); transition: transform .9s cubic-bezier(.2,.7,.3,1), opacity .9s ease; }
+    .vista-art .v-glow-b { opacity: calc(.6 + var(--vitral-shift-x, 0) * 1.2); transform: translate3d(calc(var(--vitral-shift-x, 0) * 44px), calc(var(--vitral-shift-y, 0) * -14px), 0); transition: transform .9s cubic-bezier(.2,.7,.3,1), opacity .9s ease; }
+    .vista-art .v-sun { transform: translate3d(calc(var(--vitral-shift-x, 0) * 10px), calc(var(--vitral-shift-y, 0) * 84px), 0); transition: transform 1.1s cubic-bezier(.2,.7,.3,1); }
+    .vista-art .v-glint { opacity: calc(.45 - var(--vitral-shift-y, 0) * .9); transform: translate3d(calc(var(--vitral-shift-x, 0) * 10px), 0, 0); transition: opacity 1.1s ease, transform 1.1s cubic-bezier(.2,.7,.3,1); }
+    @media (prefers-reduced-motion: reduce) {
+      .vista-art .v-sun, .vista-art .v-glint { transform: none; opacity: .45; }
+      .vista-art .v-far, .vista-art .v-mid, .vista-art .v-near, .vista-art .v-glow-a, .vista-art .v-glow-b { transform: none; opacity: .6; }
+    }
+  </style>
+
+  <defs>
+    <clipPath id="vFrame"><rect x="0" y="0" width="680" height="360" rx="10"/></clipPath>
+    <clipPath id="vAbove"><rect x="0" y="0" width="680" height="196"/></clipPath>
+    <radialGradient id="vSun">
+      <stop offset="0" stop-color="#FFF4D6" stop-opacity="0.95"/>
+      <stop offset="0.7" stop-color="#FFD58A" stop-opacity="0.9"/>
+      <stop offset="1" stop-color="#F7A96B" stop-opacity="0.75"/>
+    </radialGradient>
+    <radialGradient id="vSunHalo">
+      <stop offset="0" stop-color="#FFD98F" stop-opacity="0.5"/>
+      <stop offset="1" stop-color="#F7A96B" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="vSky" x1="0" y1="0" x2="0.22" y2="1">
+      <stop offset="0" stop-color="#5B49C9" stop-opacity="0.54"/>
+      <stop offset="0.38" stop-color="#8A6EE4" stop-opacity="0.34"/>
+      <stop offset="0.7" stop-color="#E06082" stop-opacity="0.29"/>
+      <stop offset="1" stop-color="#F0B046" stop-opacity="0.46"/>
+    </linearGradient>
+    <linearGradient id="vSea" x1="0" y1="0" x2="0.08" y2="1">
+      <stop offset="0" stop-color="#F0B046" stop-opacity="0.34"/>
+      <stop offset="0.22" stop-color="#1CA89E" stop-opacity="0.38"/>
+      <stop offset="1" stop-color="#132F5C" stop-opacity="0.78"/>
+    </linearGradient>
+    <radialGradient id="vLamp">
+      <stop offset="0" stop-color="#FFE9B8" stop-opacity="0.78"/>
+      <stop offset="1" stop-color="#FFD98F" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="vP1"><stop offset="0" stop-color="#367AEB" stop-opacity="0.6"/><stop offset="1" stop-color="#367AEB" stop-opacity="0"/></radialGradient>
+    <radialGradient id="vP2"><stop offset="0" stop-color="#1CA89E" stop-opacity="0.30"/><stop offset="1" stop-color="#1CA89E" stop-opacity="0"/></radialGradient>
+    <radialGradient id="vP3"><stop offset="0" stop-color="#E06082" stop-opacity="0.5"/><stop offset="1" stop-color="#E06082" stop-opacity="0"/></radialGradient>
+  </defs>
+
+  <g clip-path="url(#vFrame)">
+    <g class="v-far">
+      <rect x="-30" y="-30" width="740" height="256" fill="url(#vSky)"/>
+      <ellipse class="v-glow-a" cx="150" cy="104" rx="230" ry="132" fill="url(#vP1)"/>
+      <ellipse class="v-glow-b" cx="520" cy="140" rx="250" ry="100" fill="url(#vP3)"/>
+    </g>
+
+    <g clip-path="url(#vAbove)">
+      <g class="v-sun">
+        <circle cx="432" cy="192" r="96" fill="url(#vSunHalo)"/>
+        <circle cx="432" cy="192" r="24" fill="url(#vSun)"/>
+      </g>
+    </g>
+    <g class="v-mid">
+      <rect x="-30" y="196" width="740" height="204" fill="url(#vSea)"/>
+      <ellipse cx="580" cy="288" rx="220" ry="124" fill="url(#vP2)"/>
+      <path d="M6 200.0 h18 M46 200.0 h18 M80 200.0 h11 M145 200.0 h9 M173 200.0 h8 M204 200.0 h22 M235 200.0 h7 M266 200.0 h18 M305 200.0 h19 M339 200.0 h23 M372 200.0 h30 M424 200.0 h24 M490 200.0 h16 M519 200.0 h30 M555 200.0 h12 M581 200.0 h30 M618 200.0 h22 M650 200.0 h9" stroke="#FFF3DA" stroke-opacity="0.28" stroke-width="1" stroke-linecap="round"/>
+      <path d="M74 204.2 h12 M100 204.2 h12 M195 204.2 h28 M245 204.2 h13 M384 204.2 h10 M404 204.2 h23 M441 204.2 h31 M527 204.2 h30 M568 204.2 h12 M604 204.2 h12 M639 204.2 h23 M669 204.2 h8" stroke="#FFF3DA" stroke-opacity="0.28" stroke-width="1" stroke-linecap="round"/>
+      <path d="M127 209.4 h23 M169 209.4 h16 M278 209.4 h32 M329 209.4 h27 M398 209.4 h27 M431 209.4 h25 M477 209.4 h17 M501 209.4 h23 M548 209.4 h28 M598 209.4 h33 M650 209.4 h32" stroke="#FFF3DA" stroke-opacity="0.27" stroke-width="1" stroke-linecap="round"/>
+      <path d="M6 215.8 h32 M56 215.8 h27 M148 215.8 h38 M208 215.8 h20 M247 215.8 h22 M370 215.8 h23 M487 215.8 h35 M538 215.8 h35 M593 215.8 h15 M631 215.8 h36" stroke="#FFF3DA" stroke-opacity="0.26" stroke-width="1" stroke-linecap="round"/>
+      <path d="M6 223.7 h28 M44 223.7 h26 M96 223.7 h32 M141 223.7 h15 M169 223.7 h17 M207 223.7 h26 M258 223.7 h41 M308 223.7 h11 M326 223.7 h32 M492 223.7 h30 M543 223.7 h31" stroke="#FFF3DA" stroke-opacity="0.25" stroke-width="1" stroke-linecap="round"/>
+      <path d="M56 233.5 h23 M99 233.5 h33 M149 233.5 h39 M197 233.5 h44 M252 233.5 h27 M308 233.5 h24 M361 233.5 h39 M477 233.5 h40 M542 233.5 h18 M591 233.5 h46 M664 233.5 h22" stroke="#FFF3DA" stroke-opacity="0.24" stroke-width="1" stroke-linecap="round"/>
+      <path d="M52 245.5 h34 M107 245.5 h13 M246 245.5 h33 M309 245.5 h40 M494 245.5 h38 M562 245.5 h35 M615 245.5 h46" stroke="#FFF3DA" stroke-opacity="0.22" stroke-width="1" stroke-linecap="round"/>
+      <path d="M6 260.4 h52 M147 260.4 h37 M193 260.4 h58 M271 260.4 h50 M414 260.4 h33 M482 260.4 h26 M521 260.4 h33 M589 260.4 h35 M639 260.4 h42" stroke="#FFF3DA" stroke-opacity="0.20" stroke-width="1" stroke-linecap="round"/>
+      <path d="M79 278.8 h28 M126 278.8 h34 M310 278.8 h39 M432 278.8 h49 M507 278.8 h60 M605 278.8 h28 M669 278.8 h63" stroke="#FFF3DA" stroke-opacity="0.17" stroke-width="1" stroke-linecap="round"/>
+      <path d="M296 301.6 h69 M404 301.6 h26 M521 301.6 h73 M610 301.6 h49" stroke="#FFF3DA" stroke-opacity="0.14" stroke-width="1" stroke-linecap="round"/>
+      <path d="M156 329.6 h58 M314 329.6 h91 M422 329.6 h26 M479 329.6 h75 M587 329.6 h58" stroke="#FFF3DA" stroke-opacity="0.09" stroke-width="1" stroke-linecap="round"/>
+      <circle cx="186" cy="202" r="8" fill="url(#vLamp)" opacity="0.2"/>
+      <circle cx="186" cy="202" r="1.7" fill="#FFF3DC" opacity="0.55"/>
+      <circle cx="322" cy="201" r="8" fill="url(#vLamp)" opacity="0.2"/>
+      <circle cx="322" cy="201" r="1.5" fill="#FFF3DC" opacity="0.55"/>
+      <circle cx="540" cy="202.5" r="8" fill="url(#vLamp)" opacity="0.2"/>
+      <circle cx="540" cy="202.5" r="1.6" fill="#FFF3DC" opacity="0.55"/>
+    </g>
+
+    <g class="v-glint" stroke="#FFE2A6" stroke-linecap="round">
+      <path d="M404 201 h56" stroke-width="2" stroke-opacity="0.7"/>
+      <path d="M412 207 h40" stroke-width="1.6" stroke-opacity="0.55"/>
+      <path d="M418 214 h28" stroke-width="1.4" stroke-opacity="0.42"/>
+      <path d="M423 223 h18" stroke-width="1.2" stroke-opacity="0.3"/>
+      <path d="M427 234 h10" stroke-width="1" stroke-opacity="0.2"/>
+    </g>
+    <g class="v-near">
+      <circle cx="74" cy="330" r="22" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="74" cy="330" r="4.3" fill="#FFF6E2" opacity="0.88"/>
+      <circle cx="154" cy="302" r="20" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="154" cy="302" r="4.0" fill="#FFF6E2" opacity="0.88"/>
+      <circle cx="238" cy="340" r="21" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="238" cy="340" r="4.2" fill="#FFF6E2" opacity="0.88"/>
+      <circle cx="312" cy="283" r="18" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="312" cy="283" r="3.6" fill="#FFF6E2" opacity="0.88"/>
+      <circle cx="392" cy="314" r="19" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="392" cy="314" r="3.8" fill="#FFF6E2" opacity="0.88"/>
+      <circle cx="470" cy="268" r="16" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="470" cy="268" r="3.3" fill="#FFF6E2" opacity="0.88"/>
+      <circle cx="552" cy="294" r="18" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="552" cy="294" r="3.5" fill="#FFF6E2" opacity="0.88"/>
+      <circle cx="630" cy="256" r="16" fill="url(#vLamp)" opacity="0.4"/>
+      <circle cx="630" cy="256" r="3.1" fill="#FFF6E2" opacity="0.88"/>
+    </g>
+
+    <path d="M0 196 H680" stroke="#FFF1D2" stroke-opacity="0.72" stroke-width="1.5" fill="none"/>
+    <text x="664" y="218" text-anchor="end" font-size="10" letter-spacing="0.13em" fill="#FFF4DE" opacity="0.6">HORIZONTE</text>
+  </g>
+</svg>
+
+Janela is alpha. It works, it is tested against a real Rails application
+in a real browser, and its public surface has changed in three of the
+last four releases. This page says what has to be true before that stops,
+what is in the next release, and what is deliberately not coming. The
+reasoning behind it is ADR 037.
+
+## What 1.0 means
+
+Not that Janela is finished. ADR 001 commits the project to the
+load-bearing 5% of a BI tool and to staying small enough to fork, so a
+1.0 measured against what a commercial tool ships would never arrive.
+
+1.0 is three claims you can check.
+
+**The public surface stops moving.** Everything listed as the contract in
+[Theming Janela](theming), the measures and dimensions DSL, `janela_pane`
+and `janela_frame`, the pane URL shape and the dashboard filter
+parameters change only on a major version after 1.0. Until then they can
+change in any release, and every change of that kind carries an entry in
+`UPGRADING.md`.
+
+**A pane can be read.** Janela draws tables, bars and lines. A
+part-to-whole split currently has to be drawn as bars, a table row cannot
+carry context beside its label, and a chart takes Chart.js's default
+proportions whether or not they suit the page. Those are not extra
+features. They are the 5% not finished, and most of them were found by
+people installing the gem rather than reading it.
+
+**The doctor can be trusted.** `rails janela:doctor` checks an
+installation for the mistakes that produce a dashboard showing numbers
+nobody should see. Two of its checks have no test that makes them fire.
+A check nobody can prove is working is a check nobody should rely on.
+
+## In 1.0
+
+The eight lights burning in the near ground.
+
+| Issue | What |
+| --- | --- |
+| [#24](https://github.com/retail-tasker/janela/issues/24) | A chart's height and aspect ratio are the host's to set |
+| [#27](https://github.com/retail-tasker/janela/issues/27) | A ratio measure, so refusing `average:` over a boolean offers somewhere to go |
+| [#30](https://github.com/retail-tasker/janela/issues/30) | Doughnut and pie, and a categorical palette that makes them readable |
+| [#31](https://github.com/retail-tasker/janela/issues/31) | A pane says how prominent it is |
+| [#34](https://github.com/retail-tasker/janela/issues/34) | A table pane carries an attribute column beside its label |
+| [#53](https://github.com/retail-tasker/janela/issues/53) | The last two doctor checks get tests |
+| [#14](https://github.com/retail-tasker/janela/issues/14) | A Sprockets host serves the engine's JavaScript, or is told it cannot |
+| [#6](https://github.com/retail-tasker/janela/issues/6) | How contributions are accepted, who cuts a release, where to report a vulnerability |
+
+Progress is tracked on the
+[1.0 milestone](https://github.com/retail-tasker/janela/milestone/2).
+
+## Horizonte
+
+The three lights far off at the horizon. Wanted, not blocking a stable
+release, and being on this list is not a refusal.
+
+- **Drill-down on time panes** ([#18](https://github.com/retail-tasker/janela/issues/18)).
+  Clicking a month could filter every other pane to it, or narrow that
+  pane to weeks within it. Both are reasonable, they need different
+  things from the URL, and ADR 006 left the question open on purpose. It
+  needs a decision record before any code.
+- **A command palette for the demo** ([#41](https://github.com/retail-tasker/janela/issues/41)).
+  The demo site, not the gem.
+- **A scroll drift on the gallery page** ([#45](https://github.com/retail-tasker/janela/issues/45)).
+  Cosmetic, demo only, and possibly not worth fixing.
+
+## Not coming
+
+The sky above the horizon is empty, and that is the honest part of the
+picture. Janela is meant to be small enough that forking it and adding
+your own piece is a normal way to use it. These are the things you would
+be adding yourself, and each is left out because something you already
+run does it better.
+
+Natural-language query. A separate data warehouse. A row-level-security
+subsystem, because your application already has Pundit or CanCanCan and
+Janela reads through it. A refresh-scheduling interface, because you
+already have a scheduler and snapshots are an ActiveJob. An embedding
+SDK. A mobile application. Print and paginated reports. A drag-and-drop
+visual dashboard designer, though frames and panes are database records,
+so an application can build its own editor on top of them.
+
+Whether Janela should help arrange panes on a page is genuinely open
+([#29](https://github.com/retail-tasker/janela/issues/29)). The default
+answer is that layout belongs to your application, and changing it would
+need a decision record first.
+
+## How this page stays honest
+
+It is updated when a release lands, not on a schedule, and it carries no
+dates. A roadmap with dates on a project this size would be wrong within
+a fortnight and would train you to ignore it. If something here has been
+true for a long time and nothing has moved, that is worth reading as the
+signal it is.