janela 0.2.1 → 0.3.0

data/docs/decisions/014-corrections-before-frames-are-built.md

@@ -0,0 +1,222 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 005, ADR 008, ADR 009, ADR 010, ADR 011, ADR 012, ADR 013
+Supersedes: part of ADR 012, part of ADR 013
+Triggers:
+  - building frames or panes as records
+  - naming anything in the gem's public vocabulary
+  - adding a route, a layout or an index to the engine
+  - scoping or authorising a frame
+  - rendering a pane from a row rather than from URL parameters
+Topics: frames, panes, naming, routes, layouts, authorisation, tenancy, sequencing
+---
+
+# ADR 014: Corrections Before Frames Are Built
+
+## Context
+
+ADR 012 made frames and panes data and ADR 013 decided how a frame is
+named and addressed. Both were accepted within an hour of each other
+at the end of a long session. An independent review before any code
+was written found three decisions that are wrong rather than
+incomplete, and several claims that are overstated. This ADR corrects
+them, records the naming rule that was implicit, and sequences the
+build. It is the document to read before writing any of it.
+
+## Decision
+
+### A frame page renders its panes, not empty frames
+
+ADR 013 has the engine serve an index and a show page for frames. ADR
+011 has anything the engine serves render in Janela's own minimal
+layout, which deliberately loads no assets. A frame page is a grid of
+lazily loaded `turbo-frame` elements, so with no Turbo on the page
+they never fetch and **the page renders blank**. The two ADRs conflict
+and neither noticed.
+
+A frame page therefore renders each pane's content inline, inside its
+`turbo-frame`, on the first response. Cross-filtering still replaces
+frames afterwards when Turbo is present, and without Turbo the page is
+a correct static dashboard.
+
+This is better than either ADR intended, for reasons beyond the
+conflict: it removes a fan out of one request per pane on every load,
+and it is what ADR 008 already required of a dashboard, that a shared
+link be correct before any JavaScript runs. The host composed
+dashboard should do the same, which makes `loading: :lazy` on a pane an
+option rather than the default.
+
+### A frame carries an opaque owner, and is always read through a scope
+
+ADR 012 said authorisation is the host's Pundit policy on
+`Janela::Frame`. A frame has no ownership column, so a multi tenant
+host cannot write a `Scope` over it at all, and the shipped index
+would list every tenant's frames with enumerable integer ids. One of
+the two real hosts is multi tenant.
+
+`Janela::Frame belongs_to :owner, polymorphic: true, optional: true`.
+Janela never interprets the owner: it sets nothing, reads nothing from
+it, and offers no roles. It exists so a host's policy `Scope` has
+something to filter on. A single user host leaves it null.
+
+Every controller lookup goes through the host's scope rather than
+`find` on the class, so a frame belonging to another tenant is a 404
+and ids stay unguessable in effect if not in form. The same correction
+applies to the existing snapshot pane controller, which looks a
+snapshot up unscoped today.
+
+### A pane row is addressed as a row
+
+ADR 012 assumed a persisted pane could be rendered through the
+existing pane URL. It cannot, for two reasons found in the code. The
+`turbo-frame` id is derived from the query, so two rows in one frame
+with the same measure, dimension and renderer produce duplicate DOM
+ids and Turbo replaces the wrong one. And a row's own title cannot
+reach the response, because the controller builds everything from URL
+parameters.
+
+A pane row gets its own nested route, `frames/:frame_id/panes/:id`,
+identified in the DOM as `janela_pane_<id>`, built from the row. The
+ADR 005 pane grammar stays exactly as published and keeps its purpose:
+an ad hoc pane, addressable and shareable without a row existing.
+
+This also resolves a collision ADR 012 missed. The controller that
+renders a query is already `PanesController`, and the forms surface
+needs that name for CRUD. The query renderer keeps the ADR 005 URL and
+is renamed with it.
+
+### Frames sit at the mount root, and the path configuration is dropped
+
+ADR 013 gave frames their own path segment, configurable, defaulting
+to `dashboards`, and claimed this removed the collision with the pane
+grammar entirely. That claim is false. `/dashboards/3` matches the
+pane route as model `dashboards` and measure `3`, and worse, a host
+model whose route key equals the chosen segment, `Report`, `Dashboard`
+or `Insight`, has its panes shadowed by it. Those are precisely the
+words the option exists to allow.
+
+Frames live at the mount root with a numeric id constraint:
+
+```
+/insights                  every frame
+/insights/3                one frame
+/insights/orders/revenue   an ad hoc pane, grammar unchanged
+```
+
+No model route key is all digits, so nothing collides, and the mount
+path is already the host's noun by ADR 005. The configuration value
+ADR 013 added is deleted before it ships. ADR 001 prefers this.
+
+### The security claim, stated accurately
+
+ADR 012 claimed a persisted pane adds no query surface because
+dimensions are the Ransack allowlist. The registry and the fetch or
+raise lookups do hold, and a row genuinely cannot invent a query,
+reach an unexposed model or widen what is filterable. Two corrections
+to how it was stated:
+
+- Dimensions are the allowlist **only when the model has not already
+  declared its own**. Janela skips generating the allowlist if the
+  host defined `ransackable_attributes`, so in that case the surface
+  is the host's list, not Janela's. Both real hosts define their own.
+- Filter parameters are still permitted wholesale, so any Ransack
+  predicate on an allowed attribute is reachable. That is issue #8 and
+  is unchanged by frames.
+
+Rows are validated against the registry on save, not only at render:
+model, measure, dimension, renderer, granularity and limit. Otherwise
+deleting a dimension from a `janela` block silently breaks every row
+naming it, and the failure appears to a reader as a missing pane. A
+pane's title is the first analyst authored text the gem renders, and
+is escaped like any other string, never marked safe.
+
+### A pane whose model has no policy fails as one pane
+
+A frame spanning several models may include one the viewer's host has
+no policy for, which raises inside a single pane request. That pane
+renders a refusal in its own frame with a 403 rather than taking out
+the response.
+
+### Naming: uncommon but conceivable, so a host is not pigeonholed
+
+The words in the gem's vocabulary, Janela, Frame, Pane, are chosen to
+be uncommon and still conceivable. A class called `Dashboard` would
+push every host into calling the thing a dashboard; `Frame` leaves
+them free to say insight, report or scorecard through i18n while the
+gem keeps one internal vocabulary. This is the same principle as the
+mount path belonging to the host (ADR 005) and the noun coming from a
+locale file (ADR 013), and it is a rule rather than a preference: **the
+gem's own words should not become a host's product language.**
+
+The review's argument for `Dashboard`, that it removes glue, is
+therefore declined, and the glue is realigned to `Frame` instead:
+
+- `janela_dashboard do ... end` becomes `janela_frame do ... end`, and
+  gains a record form, `janela_frame @frame`. One helper, two ways to
+  supply the panes.
+- The Stimulus controller `janela--dashboard` becomes `janela--frame`,
+  and its file follows. Hosts register it by name, so this is a
+  breaking change for the two installations and belongs in the
+  changelog.
+- The helper module becomes `Janela::FramesHelper`.
+- Today's runtime `Janela::Pane` becomes `Janela::Query`, freeing
+  `Pane` for the record, as ADR 012 decided.
+
+### Sequence: four builds, not one
+
+1. **Rename only.** `Pane` to `Query`, `janela_dashboard` to
+   `janela_frame`, the Stimulus controller, the helper module. No new
+   behaviour, no records, both hosts updated for the controller name.
+2. **Records and rendering.** Migrations, `Frame` and `Pane`, the
+   opaque owner, row validations, the nested pane route, inline first
+   render, the grid and the stylesheet. A host renders a frame in its
+   own page and owns the authorisation.
+3. **The engine's own pages.** Index and show at the mount root, only
+   once 1 and 2 are settled and scoping is proven in a real host.
+4. **Forms.** The analyst's editing surface, as conventional Rails
+   CRUD on the nested resources.
+
+The visual editor keeps its own future ADR, and ADR 012's commitment
+to it is softened here to undecided: the ownership argument justifies
+records and forms, and does not by itself justify a canvas.
+
+### Documentation that is now wrong
+
+The README still lists a report designer as out of scope and says
+there is no drag and drop designer. ADR 009 states there is no
+Dashboard model. ADR 010's skill instructs agents not to build a
+report designer, and requires the skill to describe only the README's
+API. All three must be corrected as part of build 2, not after it.
+
+## Consequences
+
+- Nothing in ADR 012's core is reversed: frames and panes are still
+  data, created at runtime, and the HTML still derives from the rows.
+  What changes is how they are addressed, scoped and first rendered.
+- One configuration value is removed before shipping and none is
+  added, so the gem still has exactly one, `parent_controller`.
+- Inline first render means a frame page does one query per pane on
+  the server. At the scale a dashboard renders that is cheaper than
+  the request per pane it replaces, but it makes the ordering and
+  limit decision of ADR 007 load bearing for page speed rather than
+  only for legibility.
+- The polymorphic owner is the first column Janela adds that it does
+  not itself use. It is a hook and is documented as one.
+- Build 1 is a breaking change for two known installations with no
+  user visible benefit, which is the right moment to take it: the only
+  installations are the author's.
+- Uncommon words are collision free by construction, which is the
+  point of the rule: no host names a model `Frame` or `Pane`, so the
+  class, the CSS hook, the DOM id and the sentence "the pane is not
+  loading" are unambiguous in any application with no coordination.
+  The application this gem was extracted from already has a
+  `Dashboard` model, a `DashboardPolicy` and a `dashboards` table, so
+  the declined name would have collided in conversation there
+  permanently. Active Storage's `Blob` and Action Text's `RichText`
+  are the same choice; Blazer's `Dashboard` is the counter example.
+- The cost is a permanent translation tax on documentation. Every
+  README example, error message and line of ADR 010's skill has to
+  decide whether to speak the gem's word or the reader's, and a gloss
+  like "a frame is a dashboard" never stops being necessary. That is
+  accepted as much smaller than a name that collides in every host.

data/docs/decisions/015-how-breaking-change-is-communicated.md

@@ -0,0 +1,114 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 001, ADR 010, ADR 014
+Triggers:
+  - making any change a host must act on
+  - cutting a release whose version's middle number changes
+  - adding a deprecation, an alias or a compatibility shim
+  - adding or changing what janela:doctor checks
+  - writing anything an agent is expected to follow
+Topics: releases, upgrades, documentation, ai, dx, deprecation
+---
+
+# ADR 015: How Breaking Change Is Communicated
+
+## Context
+
+Build 1 of ADR 014 renamed a helper, a Stimulus controller, a helper
+module, two controllers and a class. Every host has to act on it, and
+the only record is `CHANGELOG.md`, which a reader has to know to look
+for. The failures a host meets first are uninformative:
+`undefined method 'janela_dashboard'` and `uninitialized constant
+Janela::Pane` say nothing about what replaced them.
+
+The people and agents upgrading this gem are the same ones ADR 010 was
+written for. That ADR decided guidance ships inside the gem so nobody
+has to rediscover what the gem already knows. An upgrade path is
+guidance, and none has shipped. This is the first case where the
+principle has something concrete to do.
+
+A changelog is also the wrong document for the job. It records what
+changed, for a reader deciding whether to upgrade. It does not tell
+someone mid-upgrade what to do, in order, with exact before and after.
+Those are different readers and mixing them serves neither.
+
+## Decision
+
+**`UPGRADING.md` ships inside the gem.** One section per version that
+requires action, newest first, written as imperative steps with the
+exact old and new text. Not prose: something a person or an agent can
+work through and tick off. It is listed in the gemspec's files, so it
+travels with an installed gem and is readable without network access.
+
+The division of labour: `CHANGELOG.md` says what changed and why,
+`UPGRADING.md` says what to do about it, `docs/decisions/` says why
+the change was decided at all.
+
+**A breaking release sets `post_install_message`.** One or two lines
+naming the version and pointing at `UPGRADING.md`. Bundler prints it
+when the gem is updated, which makes it the only mechanism that
+reaches whoever, or whatever, ran the command at the moment they
+needed it.
+
+Used only for releases that require host action, and removed in the
+release after. A post install message on every version is noise that
+teaches people to skip it.
+
+**`rails janela:doctor` reports what a host needs to fix.** One
+command, a list of findings, exit status zero when clean. It checks
+what experience says actually breaks a host:
+
+- Stale identifiers from any previous version, for example
+  `janela--dashboard` or `janela_dashboard` in the host's markup and
+  JavaScript, or `Janela::Pane` in its Ruby.
+- Whether Janela's Stimulus controllers are registered at all, which
+  is the failure that looks like nothing happening.
+- A `through:` dimension whose associated model does not allowlist the
+  attribute, which Ransack refuses per class.
+- Whether Janela's endpoints are reachable without authentication,
+  which depends entirely on what the host's `ApplicationController`
+  does.
+- Whether the engine is mounted, and where.
+
+This is the most agent shaped surface the gem can offer: one command
+whose output is a list of actions rather than a paragraph to
+interpret. It covers install as well as upgrade, so the traps ADR 010
+listed become something a machine finds rather than something a person
+remembers.
+
+**No deprecation aliases and no compatibility shims.** A renamed
+helper is not kept alive with a warning. The codebase's posture is
+that a thing has one name, and a shim is a second name that lives
+forever because nobody dares delete it. A loud failure plus a
+findable, executable guide is better than a quiet alias, particularly
+before 1.0 where the version number already says what to expect.
+
+The exception, if one is ever wanted, is a constant that raises with a
+message naming its replacement, because that is an error rather than a
+second way to write working code. Not adopted now.
+
+**ADR 010's skill will point at all three.** When the skill ships it
+tells an agent to read `UPGRADING.md` before changing a version
+constraint and to run `janela:doctor` after, which is the loop this
+ADR exists to make possible.
+
+## Consequences
+
+- Three documents now have to stay in step on a breaking release:
+  changelog entry, upgrade section, and the doctor check that catches
+  the thing being renamed. The doctor is what keeps the other two
+  honest, because a check either finds the stale identifier or it does
+  not.
+- `janela:doctor` reads the host's source, which is the first time the
+  gem inspects an application rather than serving it. It only reads,
+  reports, and changes nothing.
+- A doctor check for authentication has to guess, since whether an
+  endpoint is public depends on the host's controller. It reports what
+  it observes and says plainly that it cannot be certain, rather than
+  asserting a system is safe.
+- Refusing aliases means an upgrade cannot be gradual within one
+  version. That is the intended cost: the guide is short because there
+  is exactly one way the code can be.
+- This ADR is itself the thing that makes 0.3.0 shippable to anyone
+  other than the author.

data/docs/decisions/016-the-styling-vocabulary.md

@@ -0,0 +1,100 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 001, ADR 012, ADR 014
+Triggers:
+  - adding or renaming a CSS class the engine renders
+  - adding a layout value a person can edit
+  - changing the spacing scale or the grid
+  - a host asking how to restyle Janela
+Topics: css, layout, styling, public-api, security
+---
+
+# ADR 016: The Styling Vocabulary
+
+## Context
+
+ADR 012 made a frame's layout data: how many columns, what gap, how
+many columns a pane spans. ADR 014 confirmed the vocabulary is CSS
+Grid's rather than a new glossary. Two things still had to be decided
+before any of it is rendered.
+
+The first is safety. These values are edited by an analyst, and a
+length like `1rem` interpolated into a style attribute is injectable:
+`1rem; position: fixed; top: 0` is valid CSS and escaping does not
+help inside an attribute. The field is harmless today only because
+nobody can type into it yet, which changes in build 4.
+
+The second is that Janela ships no CSS at all, so a table pane renders
+with no padding and a label runs into its number, reading as `false55`
+(issue #15). A grid means nothing without CSS, so the stylesheet stops
+being optional the moment frames exist.
+
+Tailwind is the obvious model, and the part worth taking is not
+utility classes but the reason they work: the scale is **finite and
+indexed rather than measured**, so an inconsistent design is not
+expressible.
+
+## Decision
+
+**Layout values are small integers, and the gem supplies the units.**
+`columns` 1 to 12, `gap` 0 to 8, `span` 1 to 12. An integer cannot
+inject anything, so the field is safe by construction rather than by a
+regular expression somebody has to keep trusting.
+
+**An integer selects a class; it is never interpolated into a style
+attribute.** The engine renders class names and the shipped stylesheet
+defines them:
+
+```css
+.janela-frame     { display: grid; }
+.janela-cols-3    { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.janela-gap-4     { gap: calc(var(--janela-space) * 4); }
+.janela-span-2    { grid-column: span 2; }
+```
+
+Around thirty rules, enumerated for every value the validations
+permit. Nothing an analyst supplies reaches CSS: the integer only
+chooses a rule that was already written.
+
+**One naming rule: `janela-{property}-{scale}`.** `janela-cols-3`,
+`janela-gap-4`, `janela-span-2`. Learn it once and the rest is
+predictable, which is doing more work in Tailwind's success than any
+individual class.
+
+**One base unit is the whole spacing theme.** `--janela-space`,
+defaulting to `0.25rem`. A host sets it once and the entire scale
+moves, without touching data or overriding rules.
+
+**Responsive behaviour is in the stylesheet, not in the data.** The
+grid collapses to a single column below a narrow breakpoint. An
+analyst chooses a column count, not a set of breakpoints, and a
+dashboard that is unreadable on a phone is not a choice worth
+offering. Per breakpoint control, if ever needed, is a separate
+decision.
+
+**No arbitrary value escape hatch.** Tailwind offers `gap-[17px]`
+because a developer occasionally has to defy the design system. Here
+the editor is an analyst, the constraint is the point, and an escape
+hatch reintroduces exactly the injection surface these integers close.
+
+**The class names are public API.** A host restyles Janela by
+overriding `.janela-pane`, `.janela-gap-4` and the rest, or by setting
+`--janela-space`, so renaming one is a breaking change and belongs in
+`UPGRADING.md` like any other (ADR 015). The stylesheet ships as
+`app/assets/stylesheets/janela.css` and a host includes it, rather
+than the engine injecting it into a layout it does not own.
+
+## Consequences
+
+- Issue #15 is answered: the gem ships CSS, so a pane is legible on
+  install, and a host overrides rather than writes from scratch.
+- An analyst cannot express `1.375rem` of gap. Intended: the realistic
+  choices are none, small, medium and large, and a finite scale is why
+  a dashboard built by several people still looks like one thing.
+- The enumerated rules must stay in step with the validation ranges.
+  A value that validates but has no class renders unstyled and
+  silently, so the test suite asserts the two agree.
+- Janela now owns a stylesheet, which is a surface it has to maintain
+  and a thing hosts will want to argue with. Custom properties are
+  the pressure valve: retheme without forking.

data/docs/decisions/017-janela-owns-no-data-store.md

@@ -0,0 +1,113 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 004, ADR 007, ADR 009
+Triggers:
+  - proposing a data store, warehouse, cache or copy of a host's data
+  - a pane or a frame being measurably slow on a real host
+  - adding a database adapter or a second connection
+  - anything that would query outside ActiveRecord and therefore outside the host's scope
+Topics: performance, columnar, storage, authorisation, scope, dependencies
+---
+
+# ADR 017: Janela Owns No Data Store
+
+## Context
+
+Commercial BI tools mostly answer performance by taking a copy: extract
+the host's data into a columnar store the vendor owns, and query that.
+Columnar storage is genuinely the right shape for what Janela does, a
+`SUM` or a `COUNT` grouped by one dimension over many rows, and the
+motivation for keeping that store local rather than in someone else's
+cloud is the same instinct that made this project worth starting.
+
+The Postgres ecosystem has caught up in a way that matters here.
+[`pg_duckdb` reached 1.0](https://motherduck.com/blog/pg-duckdb-release/)
+with over a million downloads by its own account,
+[`pg_ducklake` became production ready in January 2026](https://github.com/duckdb/pg_duckdb),
+and Citus has had a columnar access method for years. Each of these
+puts a vectorised columnar engine **inside** Postgres rather than
+beside it, which is the distinction this ADR turns on. Read those
+before reopening the question: they are the reason it is worth
+reopening at all, and they are also the reason it does not need to be
+reopened yet.
+
+ADR 001 already declined a separate data warehouse and ETL. This ADR
+records why that holds even now that a local columnar store is
+practical, and what Janela does instead.
+
+## Decision
+
+**Janela never holds a copy of a host's data.** No warehouse, no
+extract, no second connection, no adapter of its own.
+
+The reason is not performance, it is authorisation. Everything safe
+about this gem rests on `on: policy_scope(Order)`, an ActiveRecord
+relation carrying the host's Pundit scope and whatever tenancy it
+uses (ADR 002, ADR 004). A copy has no relation, no policy and no
+tenant filter, so a copy means reimplementing row level security
+against it. That is the subsystem ADR 001 refused, and getting it
+subtly wrong shows one tenant's numbers to another, which is a far
+worse failure than a slow pane.
+
+**Janela stays fast by generating SQL a columnar engine can
+accelerate, and by getting out of the way.** A host that needs
+analytical speed converts the table it reports on, with
+[`pg_duckdb`](https://github.com/duckdb/pg_duckdb), `pg_ducklake`,
+Citus columnar or whatever its own database offers. The
+table stays addressable by ActiveRecord, so Pundit, tenancy and every
+part of Janela's query path keep working, and **Janela gets faster
+with no change to the gem at all**. That is a page of documentation
+rather than an architecture, and it is the right division: the host
+owns its storage, the gem owns the question.
+
+It follows that the gem's obligation is to emit plain, grouped,
+aggregate SQL and not to outsmart the planner. ADR 007's ordering and
+limit are the whole of the performance surface Janela owns.
+
+**Snapshots are already the useful part of a warehouse.** ADR 009
+persists frozen results with no extract, no staleness question and no
+authorisation problem, because a snapshot was taken *under* a scope
+and stores only what that scope returned. Anything that wants
+precomputed aggregates should reach for a snapshot before it reaches
+for a store.
+
+**No measured problem exists.** The demo runs on 600 rows, the
+commercial host's largest reported table on about 1,100, the personal
+host's on four. Nothing is slow, and ADR 001 is explicit about not
+building for hypothetical futures.
+
+**What would change this.** A pane, measured on a real host, that is
+too slow to use after its table has been made columnar and after
+ADR 007's limit has been applied. At that point the question is
+whether Janela should read a host-owned materialised view or
+continuous aggregate, which is still the host's data under the host's
+scope, and not whether Janela should own a store. That distinction is
+the thing this ADR is really protecting.
+
+## Consequences
+
+- A host with genuinely large tables must do something about its own
+  storage, and the gem can only document the options rather than solve
+  it. That is a real limitation and it is the correct one: the
+  alternative is a copy whose access control Janela cannot honestly
+  guarantee.
+- The README gains a short performance section naming the columnar
+  extensions and pointing at snapshots. It must be honest that the
+  gem has not been tested against a large columnar table, because it
+  has not.
+- Refusing a second connection also refuses a whole category of
+  feature: querying anything that is not an ActiveRecord model in the
+  host. Reporting across two applications, or over a CSV, or over a
+  warehouse the business already has, is out of scope for the same
+  reason.
+- [`activerecord-duckdb`](https://rubygems.org/gems/activerecord-duckdb)
+  is at 0.1.0 and describes itself as incomplete, so even the tempting
+  version of this would be built on something immature today. That is
+  a timing observation rather than a reason, and it will stop being
+  true, which is why it is recorded as an observation.
+- This is the third time a scope question has been settled by asking
+  where authorisation lives (ADR 002's `on:`, ADR 012's persisted
+  panes, now this). It is worth naming as the project's actual test:
+  **if a feature cannot be expressed as a scoped ActiveRecord
+  relation, it is probably not Janela's to build.**

data/docs/decisions/018-a-table-is-the-universal-renderer.md

@@ -0,0 +1,75 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 009, ADR 011, ADR 013, ADR 016
+Triggers:
+  - rendering a pane where the chart runtime may be absent
+  - adding a renderer, or changing what a renderer means
+  - a pane rendering as something other than its row says
+  - the engine serving a page of its own
+Topics: rendering, renderers, charts, progressive-enhancement, engines
+---
+
+# ADR 018: A Table Is the Universal Renderer
+
+## Context
+
+ADR 013 promised a host could install the gem and navigate its own
+dashboards the same day, which is why the engine serves an index and a
+frame page of its own. ADR 011 established that those pages render in
+the engine's minimal layout, which loads none of the host's assets
+because the engine cannot know their names or bundler. ADR 014 then
+had a frame render its panes inline so that the page is correct before
+any JavaScript.
+
+Correct, but not complete. A chart pane is a `canvas` the Stimulus
+chart controller fills in, and the engine's own pages deliberately
+load no Stimulus and no Chart.js. So a frame with two chart panes
+served by the engine shows two empty holes the height of a chart. The
+claim that those pages are a correct static dashboard was not true.
+
+The engine could not fix this by loading a chart runtime: emitting a
+working module graph needs the host's importmap or bundle, which is
+exactly what ADR 011 said the engine cannot assume.
+
+## Decision
+
+**Where no chart runtime exists, a chart pane renders as a table.**
+
+The engine's own frame page passes `charts: false` to `janela_frame`,
+and a pane whose renderer is `bar` or `line` renders its table instead.
+A host's own page renders charts normally, because a host that
+registered the Stimulus controllers has the runtime.
+
+This is not JavaScript detection and it is not a fallback that guesses.
+The engine's pages deterministically have no chart renderer, so they
+deterministically use the one that needs nothing.
+
+**A renderer is a viewing choice, not part of the pane.** ADR 009
+already decided this when it made a snapshot store results rather than
+markup, and this follows from it: the row records that a pane is best
+seen as a bar chart, and a surface that cannot draw one shows the same
+numbers another way. Nothing about the data changes.
+
+**A table is the renderer that always works**, needing no JavaScript,
+no canvas and no measurement, which is why it is the one to fall back
+to rather than an error or an empty space.
+
+## Consequences
+
+- The engine's own pages are now what ADR 013 promised: a host mounts
+  the engine and reads a real dashboard the same day, with no
+  JavaScript wiring at all.
+- The same frame can look different in two places: a bar chart on a
+  host's page and a table on the engine's. That is the cost, it will
+  surprise someone, and the README says so plainly rather than leaving
+  them to discover it.
+- Cross-filtering is still absent from the engine's pages, because
+  that genuinely needs Stimulus. They are for reading, and a host that
+  wants interaction renders the frame in its own page, which is one
+  helper call.
+- `charts:` is a rendering option rather than a stored column, so no
+  migration and nothing for an analyst to get wrong.
+- If the engine ever gains a way to know a host's asset setup, this
+  decision is worth revisiting, because the better answer is a chart
+  that draws everywhere.