Skip to content

A frameless page for a site's own page, and the matrix of every item - #20

Merged
mklarmann merged 15 commits into
first-versionfrom
dashboard-page
Nov 17, 2026
Merged

mklarmann merged 15 commits into
first-versionfrom
dashboard-page

Conversation

@mklarmann

@mklarmann mklarmann commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Follow-up to #2, on top of first-version. It builds what sentier-bafu asked for (a page without a frame, every item on a local page) in the look of sentier-bafu-agribalyse's trial dashboard, the basis Manuel chose. It takes the dashboard's look and structure only: none of its values, and none of its defects (listed under Evidence).

Summary

One body serves a site's page and a page of its own:

page.body(data)                          a site's page
  <div class="sentier-diagnostics" data-sentier-diagnostics>   one root, no id, no html/head/body
    header, comparison chips, one control row, matrix grid, item drawer
    below, closed: steps and the whole way, distributions, worst, explanations, rule
    <script type="application/json" data-sd="data">…</script>  the checked file, every "<" escaped
  + page.assets(): diagnostics.js, diagnostics.css               the site copies these

page.write(data, folder, breakdowns, matrix)                    a page of its own
  index.html  = shell + <h1> + the same body (data-sd-standalone)
  standalone.css (the :root tokens and font a site would set)
  matrix.js   (when the file names a matrix)
 src/sentier_diagnostics/
+├── matrix.py            # sentier-diagnostics-matrix/1: make, dumps, write, read, errors, against
 ├── chain.py             # + build_with_matrix (a local file of items only)
 ├── fileformat.py        # + optional "matrix": {file, items} (local, items tier) and "indicator": {one, many}
 ├── page.py              # body(), assets(standalone=False), write(..., matrix), named_matrix()
 ├── cli.py               # check / page / example know the matrix
 └── page/
+    ├── body.html        # the frameless body, data-sd="…" in place of ids
+    ├── standalone.css   # :root and body, for a page of its own only
     ├── index.html       # now only a shell around the body
     ├── diagnostics.css  # every rule under .sentier-diagnostics; --sd-* take the host's tokens
     └── diagnostics.js   # mount(root, {data}); auto-mounts every [data-sentier-diagnostics]
+examples/local/          # the local example and its matrix (6 listed of 10)

The matrix of every item is loaded after the page is drawn:

show(data)                          draws the listed items at once
  loadMatrix()
    window.SENTIER_DIAGNOSTICS_MATRIX         set by the site, or
    data-sd-matrix / data.matrix.file
      *.js   → <script src>   (works from disk: page.write writes matrix.js)
      *.json → fetch over http(s) only, capped at 64 MB
    checkMatrix(m, data)                      of this file? one row per item, rows the right length?
      yes → the grid and worst list hold every item, a dot marks the listed ones
      no  → "The matrix was not loaded: <reason>. The grid shows the N items listed in this file."

Every grid cell with a ratio shows after ÷ before in three significant digits (1.00, 0.984, 2.27), agreeing pairs included; the class is the tint (amber up, teal down, by band) and a mark, never in place of the number. A matrix row holds no band, so the page names it from the results the way rule.band does, and a test holds the two equal. The grid opens with the items furthest apart; a heading sorts by severityKey (furthest first) with aria-sort; filters cover name, group, class and verdict; 300 rows are drawn at a time. An item opens in a drawer (full width on a phone; Close or Escape closes it). "Why it differs" comes first: the item's own explanations, then those about a step or indicator it moved in (marked as such), or "none given".

Evidence

  • Before: node --test tests/js/page.test.js: 26 pass. Python: 145 tests. No matrix, no frameless body. Every rule of diagnostics.css was global (:root, body, ids).
    After: node: 50 pass. Python: 182 pass, doctests of matrix included. CI runs the same commands.
  • The mutation probe of First version: format, counting rule, chain, page, SPEC and migration plan #2 (55 hand-made mutations, run on a copy): 54 caught. One no longer matched the rewritten script: a breakdown of another item is drawn. Applied by hand, it went unseen, because the old test was refused by its step alone. A new node test (right step, another item) now catches it.
  • New tests that would fail without the change:
    • ScopedStyle: parses diagnostics.css and asserts every selector starts with .sentier-diagnostics, with no font-family, no :root, no html/body selector, and --sd-ink → var(--ink, …).
    • Body: one root, no html/head/body/h1/link, no id. A title of </script><!-- <script> cannot end the data element and reads back equal.
    • Matrix: against catches a changed class code, direction, result, verdict, listed name, one item fewer, title, count, attribution, qualifying and matrix.items.
    • node: the band named for a matrix row equals the Python rule's on every acceptance case. It also covers the matrix by global, by <script> with data-sd-base, and by fetch over https, plus the refusal of another file's matrix, 650 rows in 300-row pages, the heading sort order, the drawer on an unlisted item (focus, Escape), and the title set only on a page of its own.
  • In a browser (preview at 1024 px, 375 px and dark):
    • The local page loads matrix.js and shows 10 of 10 with 6 dots.
    • A host page with its own :root, body { font-family: Georgia }, h2 and table { border: 4px solid red } keeps its title, font, background, h2 and table border. Our tables have 0 px border. Our colours take the host's tokens.
    • At 375 px the page does not scroll sideways (scrollWidth 375), and the drawer is 375 wide.
    • No console errors.
  • Not carried over from the trial dashboard:
    • two definitions of agreement: the class stays the file's;
    • a "none" over a top-8 list: every count says "of how many, among which";
    • breakdowns not tied to a run: unchanged from First version: format, counting rule, chain, page, SPEC and migration plan #2, tied by states;
    • hand-written agreement labels;
    • placeholder amounts summed across units;
    • JS inside Python strings with fixed column positions: the JS is a file, and lookups go by data-sd name;
    • closeness to ADEME shown as agreement.
  • Not checked:
    • Opening index.html from disk with the matrix. The preview pane renders file:// without scripts, and the same <script src> path is checked over http.
    • Firefox and Safari.
    • A real site (sentier-bafu, sentier-bafu-agribalyse) holding the body.

Later commits

  • b8e5a55: chain.state(identity=) leaves out entries whose value is None (asked for by sentier-bafu, whose writer is draft The comparison as a chain in sentier-diagnostics' format; the countries' factors as a step (fork's work, 4) sentier-bafu#52).
  • 3c0a953: from sentier-agribalyse's trial on its own local data (2,451 products × 19 indicators; the matrix is 4.98 MB and loads with no console error):
    • a tables description may name the matrix ("matrix": "matrix.json", local files of items only), and sentier-diagnostics build writes it beside the file;
    • once the matrix is loaded, the line under the title says all items are loaded.
  • d90f76e: the page's own sentences say the file's word for an item.
  • 163d6b1: asked for by sentier-bafu:
    • an optional indicator: {one, many} in the format (and in a tables description), which the page and the summary say in place of "indicator" ("4 impact categories", a column "Impact category");
    • steps are numbered from 0 only where the first state is published, since step 0 is then the reproduction. A chain that starts from a build of its own counts from 1, in the page, the drawer and the summary.
    • Tests: Python 182, node 45. Nine reverts of the change, applied on a copy, each make a test fail. In the browser, a page built from the located-factors fixture shows "Step 1" and "impact categories", and the published example still shows "Step 0" and its note.
  • 20e7d1e: the grid reads like the trial dashboard, from Manuel's look at it in sentier-bafu's frame (11,947 × 25):
    • a ratio in every cell, three significant digits, agreeing pairs included ("1.00"); the class is the tint and a mark (~, »);
    • amber up, teal down, a stronger tint by band;
    • the grid opens with the items furthest apart (largest factor over every indicator), not with the listed ones;
    • compact columns: no Unit column, hyphenated headers. 25 indicators still scroll sideways at 976 px (1,949 px wide, was 2,733);
    • SPEC says how a host lets the body be wide when its article caps children at a reading measure.
    • Checked on sentier-bafu's real page with these assets (not committed, nothing copied), at 375 px and in dark mode on the example. Node 48; seven reverts each fail a test.
  • 7274efd: a matrix page, from Manuel's second look beside the trial dashboard at 1600 px:
    • header: title, about, one quiet line; a local file is part of that line, not a red box;
    • chips choose the comparison (the whole way, then each step with its number, what moved, ! where nothing explains it, a mark per verdict worth a look), in place of the select;
    • one control row (name, group, class, verdict, size) with the count and a compact legend on its right, then the grid;
    • steps and the whole way, distributions, worst, explanations and rule below the grid, closed until opened; the steps table gives label and claim room;
    • a host's page never offers to open a file.
    • Checked at 1600 px on sentier-bafu's real page with this body and these assets (in the browser only, nothing saved), drawer included, and at 375 px on the example. Node 50; six reverts each fail a test.

Merge Danger

Door: two-way

Nothing is published or tagged. The format sentier-diagnostics/1 gains two optional keys (matrix, indicator), which an older reader of this branch would refuse as unknown. No file outside this repository uses it yet.

Blast Radius: page

  • page.write no longer writes data.js / breakdowns.js: the data is inside index.html. A site that loads data.js itself still works through window.SENTIER_DIAGNOSTICS.
  • page.assets() now returns the script and the style only. Pass standalone=True for the shell, standalone.css and body.html.
  • The page's element lookups moved from ids to data-sd names, so a site that copied the old index.html frame must take the body instead.

🤖 Generated with Claude Code

mklarmann and others added 9 commits November 16, 2026 18:05
The page is now one body for both uses. `page.body(data)` is a single
`<div class="sentier-diagnostics">` with the file inside it as JSON: no
html, head or body, and no id. A site holds it and loads diagnostics.js
and diagnostics.css from `page.assets()`. `page.write` wraps the same body
in a page of its own with `standalone.css`.

- The style is scoped: every rule is under `.sentier-diagnostics`. It sets
  no font and nothing on `:root` or `body`, and resets what a site does to
  bare tables. Colours are `--sd-*` that take the site's tokens
  (`--sd-ink: var(--ink, ...)`). Up, down and noise keep their own colours.
- The script mounts into every `[data-sentier-diagnostics]`. It reads the
  data from the body, a global or `?file=`, and sets the document title
  only on a page of its own.
- The matrix of every item (`sentier-diagnostics-matrix/1`, new module
  `matrix`): a local file of items may name one, and
  `chain.build_with_matrix` writes it. `matrix.against` works every code
  out again and holds the file's counts, attribution and `items_count` to
  it exactly. The page loads it after drawing, as `matrix.js` beside the
  page or as JSON over http, and refuses one of another file.
- The grid shows after ÷ before, coloured by direction and shaded by band.
  It sorts by a heading (furthest first), filters by name, group, class
  and verdict, and draws 300 rows at a time.
- The item opens in a drawer. "Why it differs" comes first: the item's own
  explanations, then those of a step or indicator it moved in.
- CLI: `check` holds a matrix beside its file to it; `page` writes it;
  `example` also writes the local example. The local example is committed
  in examples/local/.

Taken from the trial dashboard of sentier-bafu-agribalyse: its look and
structure only. None of its values, and not its two definitions of
agreement, hand-written labels or a "none" over a top-N list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Asked for by sentier-bafu: every writer otherwise drops absent values itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both from sentier-agribalyse's trial on its own data (2,451 products x 19
indicators):

- A description may name the matrix (`"matrix": "matrix.json"`, local
  files of items only). `from_tables.build_with_matrix` returns it, and
  `sentier-diagnostics build` writes it beside the file.
- Once the matrix is loaded, the line under the title says all items are
  loaded instead of "N are not in this file".

Also a node test where a breakdown names the right step and another item.
The mutation probe found that removing the page's item check went unseen:
the old test was refused by its step alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Asked for by sentier-bafu, whose items are datasets: the matrix's lead, the
whole-way note and two aria labels said "item".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sults

Asked for by sentier-bafu, which calls its indicators impact categories and
whose chain starts from a build of its own.

- The format takes an optional `indicator: {one, many}`, checked like `item`.
  chain.build takes `indicator_word`, a tables description takes `indicator`.
  The page and the summary use the word wherever they said "indicator"; a
  file without it reads as before.
- Steps are numbered from 0 only where the first state is `published` (step 0
  is then the reproduction); otherwise from 1. Page and summary agree
  (`fileformat.first_step`, `stepNo` in the script).
- The page refuses an indicator word that is not {one, many}.
- The near-zero class text no longer names the indicator: "both results are
  within their floor".

Tests: Python 182 (from 176), node 45 (from 42). Each of nine reverts of
the change, applied on a copy, makes a test fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…est first

From Manuel's look at the page in sentier-bafu's frame (11,947 datasets x 25
impact categories), side by side with sentier-bafu-agribalyse's trial
dashboard. Most cells showed "=" or "1 - 3.037e-5", the tint was faint, and
the grid opened with the listed items, whose moves were in columns off-screen.

- Every cell with a ratio shows it in three significant digits (1.00, 0.984,
  2.27, 1.01e-3), agreeing pairs included. The class is the tint and a mark
  (~ within noise, >> beyond 10x), never in place of the number. Cells
  without a ratio keep what the class says (from 0, - -> +, ~0, missing).
- Up is amber and down teal, as in the dashboard; the tint is stronger
  (up to 55 %, by band).
- The grid opens with the items furthest apart: the largest factor over every
  indicator among the values that moved with a ratio, then moves without a
  ratio by severity, then the rest. A second click on a heading goes back.
- Compact columns: no Unit column (it is in the name's title and the drawer),
  hyphenated headers, the group cut to 8rem.
- SPEC: section 10.5 says all of this, and section 10 says how a host lets
  the body be wide when its article caps children at a reading measure.

Tests: node 48 (from 45). Seven reverts of the change, applied on a copy,
each make a test fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…below

From Manuel's second look in sentier-bafu's frame, side by side with the
trial dashboard at 1600 px: ours was a report page with a matrix in the
middle. A 17-column steps table opened it, its label and claim broke after
every word, and the header ran to six blocks with a red box.

- Header: title, the file's about, one quiet line of counts; a local file
  is a quiet part of that line, not a box. No eyebrow. The states move to
  the steps section.
- A row of chips chooses the comparison in place of the select: the whole
  way, then each step with its number, the values that moved, "!" where
  nothing explains it and a mark per verdict worth a look.
- One control row: name, group, class, verdict and the size filter, with
  the count, the matrix line and a compact legend on its right. The count
  says "Showing 300 of 11 947 datasets"; the comparison and the order go
  to the grid's aria-label.
- Then the grid and the drawer. Below them, closed until opened (details):
  steps and the whole way, distributions, worst, explanations, rule. The
  steps table gives its label and claim room; numbers stay narrow.
- A host's page never offers to open a file, only says why nothing is
  drawn.

Tests: node 50 (from 48). Six reverts, applied on a copy, each fail a test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t moved first

Built on 7274efd (the chips, the grid first, the rest below), after Manuel's
third look in sentier-bafu's frame. What a reviewer still had to hunt for:

- What a step claimed. The claim sat in the folded steps table. Under the chips
  is now one line for the chosen step: the states it goes between, what it is,
  its claim with who made it, what the claim found ("All 11 124 moves as
  claimed", or "691 not claimed" in the signal colour), its tolerance and noise.
- What a step moved. The columns came in the file's order, so the countries'
  factors (water use and land use) sat off-screen at the far right. The matrix
  now puts first the indicators in which the chosen comparison moved most; one
  in which nothing moved comes last, quietened, and keeps its column.
- Where a reviewer is. The address keeps the chosen step with the open item
  (`#step=<id>&item=<id>`), so a link opens exactly that view; closing an item
  keeps the step, and an unknown step falls back to the whole way.
- The arrow keys move between the chips.
- The filters keep one line; the count, the matrix line and the legend take the
  row under them.

Tests: node 54 (from 50). Seven reverts, applied on a copy, each fail a test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ress

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mklarmann and others added 6 commits November 17, 2026 02:43
…ial dashboard has them

The distributions were a table of small bars, folded away at the foot of the page. They
are now always in view under the matrix, one card per indicator, in the order of the
matrix's columns (what the chosen comparison moved most first, the unmoved ones quiet).
Each card is a histogram of the file's own counts: across zero, down from far to near,
the band around 1, up from near to far, then the values with no ratio; on the scale of
its own tallest bar, every count in a bar's title.

Under it, how many moved, and the median, 10th and 90th percentile of after ÷ before,
in as many digits as keep apart the ones that differ. Those come only from every item
(the matrix, or a file that lists all): the listed ones are the furthest apart, and a
median of them would say more than the whole holds, so the card gives none and the
section says why.

A card's title sorts the matrix by its indicator; a heading of the matrix marks its card.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each card on its own tallest bar is the default, as the trial dashboard draws them, so a
few values that moved are seen beside many that agree; one scale (the share of all values)
is a choice beside the legend, so that a bar of one height means as many in each card.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…honest percentiles

From the review of 752043b and 38d6767:

- The line of a step names every verdict on a move with its count, "as claimed" first
  ("11 124 values moved as claimed"); "Nothing moved, as claimed" only where all are zero.
  Weight, not green or red: a verdict is not an approval (ADR 0010, A20).
- A column or card whose only change is a missing value is not quietened as if nothing
  moved: missing counts with what moved, and its title says so.
- The percentiles say over how many ratios they are taken and how many values have none;
  each is widened only as far as its neighbour needs, and two that six digits cannot part
  read "just under the median" / "just over the median".
- Each card says what its full height is ("tallest bar: 7", or on one scale the share).
- The axis words fit at 375 px (↓ ÷10, ×10 ↑).
- SPEC: the distributions are open under the matrix; 10.3 says per card is the default and
  why, one scale a switch, and that the percentiles are the one number the page works out,
  from every item only; 10.5 says choosing a comparison sorts furthest-first again; A21.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ring pair apart

Each percentile was widened on its own, so one line could mix precisions:
1.00004, 1.00005, 1.00006 read "1.0000, 1.00005, 1.00006", a rounded 10th
percentile standing as exactly 1 beside a six-digit median. Now the three
share one precision, the smallest (3 to 6) at which every two that differ
read differently. Where six digits cannot part a percentile from the
median, it is said in words and the numbers left take the digits they need
("just under the median, 1.00, 5.95"). Found in review by the
sentier-diagnostics session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review a step where it is chosen: its claim beside its effect, what it moved first
…an its file

checkMatrix compared the title, the ids and the count only, and matrixRows then drew the
matrix's values and classes even for the items the file lists. A matrix left over from
another run of the same chain passed and replaced the file's numbers (found in the review
of PR 20: p08's values tripled and every class changed, and the grid showed them).

Every listed item's row must now say what the file says of it: name, place, group, unit,
results, classes, directions and verdicts. It compares through matrixRows, so it holds for
any shorthand the decoder reads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mklarmann

Copy link
Copy Markdown
Collaborator Author

Reviewed by the sentier-bafu-agribalyse session (in-house review, 17 Nov 2026), on #20's own commits (first-version...7274efd).

Merged at Manuel's request ("merge #20 once its review is in").

@mklarmann
mklarmann marked this pull request as ready for review November 17, 2026 05:36
@mklarmann
mklarmann merged commit b04137e into first-version Nov 17, 2026
7 checks passed
mklarmann added a commit that referenced this pull request Nov 17, 2026
…ts that tell

- The summary counted the ends over the indicators measured, so an end built twice with no
  result beyond the floor (by: {}) lost "measured at 1 of 2 ends" and read "in both builds"
  for a state never built twice. It now counts the ends that measured at all, and says "where
  it was measured" for a noise taken from two states.
- Python now tells an end that measured one indicator from one that measured another
  (`ends_known`), and reads "measured at 1 of 2 ends" from a built file; dropping either
  fails one test each (node already caught both).
- The run guard's node test rewrites an item the file does not list: since #20 a listed
  item that is not the file's refuses the matrix before a run is judged.
- SPEC 4: a step's noise reads measured whether one end or both measured; A30 after A29.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant