rshow 0.0.0-stage → 0.0.2

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "rshow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Publish static artifacts to rshow",
+  "license": "MIT",
+  "homepage": "https://rslib.github.io/rshow",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rslib/rshow.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/rslib/rshow/issues"
+  },
+  "keywords": [
+    "rshow",
+    "cli",
+    "publish",
+    "static",
+    "artifacts"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "rshow": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "worker",
+    "skills",
+    "themes",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepack": "node scripts/assemble.mjs",
+    "sea": "node scripts/sea.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "esbuild": "0.28.2",
+    "rshow-shared": "*",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/rshow/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: rshow
+description: Load before you write, fix, share or publish a page, report, printed or web poster, paper landing page or status dashboard behind an rshow link, such as an art.<domain>/<name> URL. Load it even for a quick question about one or for one accent or theme shared by many pages, one link that gathers a paper's page, deck and figures for co-authors, a CSV you can filter and sort, wireframes or mockups of a web, desktop, mobile or terminal app, TUI layouts and ratatui panes, a rough hand sketch of boxes and arrows, an asciinema capture on a page, grouping artifacts into a project, sending a link not an attachment, a rollback or a publish error. Slide decks belong to rshow-slides, code from a design belongs to rshow-implement, an editable .pptx belongs to slides, a claude.ai Artifact belongs to the Artifact tool, visual design direction belongs to frontend-design.
+---
+
+# rshow
+
+rshow serves a folder of static files at a stable link on `https://art.example.com/<slug>/`.
+Every publish of the same slug adds an immutable version, and the link keeps working.
+A theme is a published artifact of its own, and a page links one at a version.
+One theme ships, `default`: IBM Carbon on IBM Plex, in two modes, white and g100, following the system by default.
+A report, a poster, a project page, a dashboard, a mockup, a sketch and a terminal page are the other shapes this skill writes.
+Every one of them uses the same theme.
+A talk deck is the one shape this skill hands off, and building the app is the other.
+Read `rshow-slides` and `rshow-implement` for those two and come back here to publish.
+
+## Workflow
+
+Copy this checklist into the reply and tick it as you go.
+
+```text
+- [ ] shape picked and outline or headings agreed
+- [ ] page written, theme linked at a pinned version
+- [ ] rshow check <dir> exits 0
+- [ ] rshow preview <dir> looked at 360px wide and at desktop width
+- [ ] audience confirmed with the person
+- [ ] project and tags passed as --project and --tag
+- [ ] rshow publish <dir> printed a live-url
+- [ ] live-url and audience reported
+```
+
+1. Pick the shape and say it back in one sentence, such as a page, a report, a poster, a project page, a dashboard, a mockup, a sketch, a terminal page or a prerendered Astro or Vite site.
+2. Write `index.html` in its own folder, link the theme at a pinned version and keep every other path relative.
+3. Run `rshow check <dir>`.
+4. Fix every error, then run `rshow check` again until it exits 0.
+5. Run `rshow preview <dir>` and open the printed `http://127.0.0.1:4321` link.
+   Look at it at 360px and at desktop width.
+6. Confirm the audience with the person before any `people` or `public` change.
+7. Run `rshow publish <dir> --slug <slug> --label "<what changed>"`.
+   Add `--project <slug> --tag <tag>` when the artifact belongs to a project or carries a tag.
+8. Report the printed `live-url` and say who can see it, and say which project holds it.
+
+## Page rules
+
+- One `index.html` at the root of what you publish.
+- Every path inside the artifact is relative, with no leading slash.
+  The only exceptions are `/_themes/...` and `/_data/...`.
+- Link the theme, never copy it.
+  The stylesheet links and `mode.js` in the head all carry the same `<name>@<n>` version.
+- Override tokens in one `:root` block, five declarations at most.
+  No selectors, no rules, no `!important`.
+- Keep the script and the styles inline.
+  Add a framework only when the page needs one.
+- `connect-src` is `'self'`.
+  Bake data in as a literal and fetch nothing from a third party.
+- Pin an exact version in every CDN URL, such as `chart.js@4.4.1`.
+  Never write `latest`.
+- A report links `report.css` and `report.js` in place of `page.css`, and `mode.js` still goes in the head.
+  Read [reports](reference/reports.md) before you write one.
+- The page reads at 360px wide.
+  Tables go inside `<div class="table">`.
+- Nothing secret in a page, because anyone who holds the link can read the HTML source.
+- Never invent a number.
+  Print `[PLACEHOLDER]` and say so in the footer.
+- The look is IBM Carbon on IBM Plex, and every colour has one job.
+  `themes/DESIGN.md` in the rshow repo holds the system, the type scale and the layout set.
+- Fixed templates carry decks, reports, posters, project pages and dashboards, so the sections are set and the content is the work.
+- Guided kits carry mockups, sketches and TUIs, so the kit gives you a frame, a floor and a checklist and the drawing is the work.
+  Starting a kit at its highest fidelity is the same mistake as decorating a fixed template.
+
+## Audience
+
+- `private` is the owner plus the editors.
+  Keep it while the page is still being built.
+- `people` is the owner plus every share, viewer or editor.
+- `public` is anyone who holds the link, with no sign in.
+
+Always confirm the audience with the person before you set `people` or `public`.
+Name the artifact and say who will be able to read it.
+Then say that a public link means anyone who receives it can read the page.
+Also confirm before `--remove` and before `delete`.
+Never widen access to make a demo easier.
+
+Editors can publish and pin.
+Only the owner can share, rename or delete.
+
+## Exit codes
+
+| code | meaning | what to do |
+|---|---|---|
+| 0 | success | read the printed lines and report the `live-url` |
+| 2 | usage | a flag, an argument, a slug or the token is wrong, or no token is set. Read `rshow --help` and fix the command |
+| 4 | auth | the token is expired, revoked or under-scoped. Ask the person to set a token that fits |
+| 5 | api | the host refused the request. Read the message, fix the input, retry once |
+| 6 | check | `rshow check` or `rshow doctor` found an error. Read each finding and fix the page or the config |
+
+On 2, fix the command and do not retry the same line.
+On a config error (`no server configured`, no token, or a config file that will not load), run `rshow doctor` and show its output to the person.
+On 4, or on exit 2 with `no token`, never ask for a token in chat. Tell the person to run `rshow login` in their own terminal, which saves the token in the Keychain.
+On 5, retry once and then report the message verbatim.
+On 6, fix the page, never `--no-check` past it.
+
+## Reference files
+
+- [page contract](reference/page-contract.md) holds the CSP, the allowed CDNs, the data store and the phone width rule.
+  Read it before you write or review any HTML that goes to the host.
+- [pages](reference/pages.md) holds the page skeleton, the token override block, diagrams and prerendered Astro or Vite sites.
+  Read it when the page is more than a few paragraphs.
+- [themes](reference/themes.md) holds the shipped theme, its two modes, token files, the preview page, contrast and version bumps.
+  Read it when a token override is not enough and the look has to change.
+- [reports](reference/reports.md) holds the report layout: sections, figures, tables, cross-references, notes, citations and print.
+  Read it when the artifact is a report or a paper rather than a page or a deck.
+- [project page](reference/project-page.md) is the landing page of a paper, with its title block, teaser, key results and BibTeX entry.
+- [poster](reference/poster.md) is the conference poster, with one sheet size, columns, a QR code and a print that is one page.
+- [dashboard](reference/dashboard.md) is the results explorer, with a CSV in the folder, a filter bar, a summary, small multiples and a table.
+- [mockups](reference/mockups.md) is the guided kit for UI drawings, with frames, skins, flows, states, annotations and comments.
+- [sketch](reference/sketch.md) is an Excalidraw drawing read in the page and edited in place, saved to the store or downloaded.
+- [terminal](reference/terminal.md) is the terminal viewer, the TUI kit and a real ratatui app built with Ratzilla.
+- [cli](reference/cli.md) holds every command, every flag, the projects and tags that group artifacts and both config files.
+  Read it when a flag is not obvious, a publish failed or an artifact has to join a project.
+
+## Never in the look
+
+- Never write an eyebrow, a kicker or a small caps label with wide tracking above a heading.
+- Never set a label in mono or in capitals and never write a meta string such as `A / B / C` above a title.
+- Never number a slide or a card 01, 02, 03 and never ship three equal cards with a coloured top rule.
+- Never build an identity from cream and terracotta, from beige and brass or from near black plus one bright accent.
+- Never put a coloured bar on an edge or a rule down the side of a quote, and never use a hairline rule as decoration.
+- Never use Inter, Space Grotesk, Geist, Fraunces or Instrument Serif as the gesture.
+- Never use gradient text, glass, a large shadow or an emoji.
+- Never decorate what carries no information.
+  A chart is labelled at the end of the line, a table keeps its rules and nothing else does.
+
+The short list above is a hard rule.
+`themes/DESIGN.md` holds the rest: the palette roles, the type scale and the twelve layouts.
+
+## Never
+
+- Never publish a folder that holds `.env`, a key, a credential or customer data.
+- Never publish a source tree, `node_modules` or a `dist` folder that still holds a draft.
+- Never write the token into a page, a script, a log line, a commit or a chat message.
+- Never create a second artifact with a `-v2` slug.
+  Publish the same slug again.
+- Never delete an artifact or drop a share without a yes from the person.

package/skills/rshow/reference/cli.md

@@ -0,0 +1,263 @@
+# CLI
+
+## Contents
+
+- Every command
+- check
+- preview
+- publish
+- share and pin
+- projects
+- tags and list
+- theme, show, delete
+- skills
+- handoff and compare
+- Config files
+- Exit codes
+
+`rshow` is one binary and one file of flags.
+This file is the whole surface, both config files and the exit codes.
+
+## Every command
+
+| Command | What it does |
+|---|---|
+| `rshow check <file-or-dir>` | apply the page contract to the files a publish would upload |
+| `rshow preview <dir>` | serve a folder on `127.0.0.1` for a look, offline |
+| `rshow publish <file-or-dir>` | upload a folder, or one file as `index.html`, as a new version |
+| `rshow config [dir] [--offline]` | print the merged config as JSON, with `theme` resolved to its current version, such as `default@3` |
+| `rshow init --url <admin-url> --art <viewer-url>` | write the global config file, with `--theme` and `--force` |
+| `rshow doctor [dir]` | check node, config, token, api, art, theme and skills, one `ok\|warn\|fail` line each |
+| `rshow list` | list artifacts you own or that are shared with you, with `--project`, `--tag` and `--q` filters |
+| `rshow show <slug>` | print the artifact, its versions, its shares, its project and its tags |
+| `rshow share <slug>` | set the mode, or add and remove shares |
+| `rshow pin <slug> <n\|live>` | serve version `n`, or `live` for the newest |
+| `rshow project <cmd>` | create, list, show, share or delete a project |
+| `rshow tag <slug>` | add or remove tags on an artifact |
+| `rshow handoff <slug>@v<n>` | write a design handoff folder from a published design |
+| `rshow compare --against <dir>` | compare an implementation with that handoff folder |
+| `rshow delete <slug> --yes` | delete an artifact |
+| `rshow theme new <name>` | write a preset folder that extends a built-in theme |
+| `rshow theme check <dir>` | check a theme or preset folder against the token contract |
+| `rshow theme preview <dir>` | build the theme, then serve its preview page on `127.0.0.1` |
+| `rshow theme publish <dir>` | publish a theme folder as `theme-<name>` and set it public |
+| `rshow theme list` | list theme artifacts and the version each one serves |
+| `rshow skills install [target ...]` | link or copy the three skills into `~/.claude/skills`, `~/.pi/agent/skills` or `~/.codex/skills` |
+| `rshow skills uninstall [target ...]` | remove the skill links and copies rshow made |
+| `rshow skills status [target ...]` | print `link`, `copy v<version>`, `missing` or `foreign` per target and skill |
+| `rshow login` | read a token from the terminal with no echo, check it and save it in the macOS Keychain. The person runs it, never the agent |
+| `rshow logout` | remove the saved token |
+
+`--help` on its own prints the general usage, and `--help` after a command prints that command.
+`--json` is global and makes stdout the API reply, which is how a script reads a version number.
+
+Every flag takes `--flag value` or `--flag=value`.
+`--add`, `--editor`, `--remove` and `--tag` accept several values in a row after one flag.
+
+## check
+
+```bash
+rshow check <file-or-dir> [--offline]
+```
+
+It reads the same files a publish would upload, including `<dir>/<out>` when `rshow.json` names a build or an out folder.
+Each finding is one line in the form `path:line: error|warning: msg`.
+The exit code is 6 when there is at least one error and 0 otherwise.
+Warnings do not fail the run, and they are still worth fixing when the fix is one line.
+
+A warning is one of these:
+
+- `index.html` with no viewport meta, or with no `title`.
+- An `img` with no `alt`.
+- A deck that links `deck.js` and holds no `<section class="slide">`.
+- A style warning, such as an eyebrow label, three elements numbered `01`, `02`, `03`, gradient text, one of the trend fonts, a font nothing loads, cream next to terracotta, an emoji in visible text, glass or a heavy shadow and a purple to blue gradient.
+
+The style warnings read every `.html` and `.css` file in the folder and skip anything under `fonts/` and any vendored `*.min.css` or `*.min.js`.
+They are never errors, because a person may have a reason.
+`--no-style` skips all of them, and `--json` prints the findings as data.
+
+`--offline` skips every request the check would make, so it works on a plane and it never waits on the host.
+A published page that links `/_themes/<name>@<n>/` needs the network to confirm that version exists, so a `--offline` run reports those links as unchecked rather than as a pass.
+
+`rshow publish` runs the check first and stops while there is an error, so a page that fails the contract does not go live.
+`--no-check` skips that step.
+Use it only when you just ran `rshow check` yourself and the tree has not moved since.
+
+## preview
+
+```bash
+rshow preview <dir> [--theme <dir>] [--offline] [--no-reload] [--port 4321]
+```
+
+It serves `<dir>` on `127.0.0.1`, prints `http://127.0.0.1:<port>` and keeps running until you stop it.
+It works offline: `/_themes/<name>@<n>/` comes from `--theme` when that folder is the theme, then from the built-in theme on disk, and only then from the art URL in the config, which `--offline` turns off.
+A page that uses `<artifact>/_data/<key>` gets a local store for the session, and the page reloads by itself when a file changes, which `--no-reload` turns off.
+
+## publish
+
+```bash
+rshow publish <file-or-dir> [--slug s] [--title t] [--label l] [--project p] [--tag t ...] [--build cmd] [--no-check] [--force]
+```
+
+| Flag | Effect |
+|---|---|
+| `--slug` | the artifact name, `[a-z0-9][a-z0-9-]{0,62}`, default is the folder name made lowercase |
+| `--title` | the human title, default keeps the current one |
+| `--label` | a note on this version, such as "first draft" |
+| `--build` | run this command in `<dir>` first, then publish `<dir>/<out>` |
+| `--project` | move the artifact into a project |
+| `--tag` | set its tags, and the flag repeats or takes several values |
+| `--no-check` | skip the check and upload whatever is in the folder |
+| `--force` | publish a new version even when the folder did not change |
+
+A folder needs an `index.html` at its root.
+A single file is published as `index.html`.
+Publishing the same slug again adds a version and changes the live page, so a fix is a second publish and never a new slug.
+A folder that did not change adds no version and prints `unchanged: <slug> is already v<n>`, and `theme publish` does the same for an unchanged theme.
+It prints `slug`, `version`, `files`, `uploaded`, `skipped`, `label`, `version-url` and `live-url`.
+Report `live-url` to the person, because that is the link that follows the newest version.
+
+## share and pin
+
+```bash
+rshow share <slug> [--mode private|people|public] [--add a@b] [--editor a@b] [--remove a@b]
+rshow pin <slug> <n|live>
+```
+
+`--add` shares as viewer and `--editor` shares as editor.
+`--remove` drops the share.
+`pin <slug> <n>` serves an old version at the live link while the newest one stays latest, and `pin <slug> live` follows the newest again.
+Pin before a talk, so a half finished publish cannot reach the room.
+
+## projects
+
+```bash
+rshow project create <slug> [--title t] [--description d]
+rshow project list
+rshow project show <slug>
+rshow project share <slug> [--add a@b] [--editor a@b] [--remove a@b]
+rshow project delete <slug> --yes
+```
+
+A project groups artifacts and shares them at once, and the URLs of the artifacts do not change.
+A project has a slug in its own namespace, a title and a description of at most 500 characters.
+`--add` adds a member as viewer and `--editor` adds one as editor, so a project share is the cheapest way to let a co-author see five artifacts.
+
+The group page is at `https://art.example.com/_p/<project>/`, and the host renders it in the theme's look.
+It lists the artifacts of the project that the viewer may see, with the title, the mode and the date.
+It 404s when the viewer may see none of them and is not a member.
+Copy that link from `rshow project show <slug>`, which prints it as `url`.
+Send it when the person asks for everything at once.
+
+An artifact belongs to at most one project, and moving one in needs its owner plus the owner or an editor of the project.
+The effective role on an artifact is the higher of its own share role and the project member role.
+The mode rules stay per artifact: `private` is the owner plus the editors, `people` adds every project member and `public` is everyone.
+Deleting a project keeps its artifacts and clears their project.
+
+## tags and list
+
+```bash
+rshow tag <slug> [--add t ...] [--remove t ...]
+rshow list [--project p] [--tag t] [--q text]
+```
+
+A tag is `[a-z0-9][a-z0-9-]{0,31}`, stored lowercase, at most ten per artifact.
+A tag is a filter and never an audience, so it grants nothing and it hides nothing.
+`rshow tag` prints the tags after the change, and an empty list prints `-`.
+`rshow list` prints `slug mode served title` per artifact.
+The three filters combine with AND.
+`--q` matches the slug and the title.
+Set the tags and the project in `rshow.json` when they are a fact about the folder rather than a one off, and the flag still wins.
+
+## theme, show, delete
+
+`rshow theme publish <dir> [--label l] [--build cmd]` needs a `theme.json` with a `name`, publishes the folder as `theme-<name>`, sets it public and prints `/_themes/<name>@<n>/`.
+`rshow theme list` prints the theme artifacts and the version each one serves.
+`rshow show <slug>` prints the artifact, its versions, its shares, its pin and its URLs.
+`rshow delete <slug> --yes` deletes the artifact and every version.
+It needs `--yes`, and it needs a yes from the person.
+
+A preset is a small folder whose `theme.json` carries `"extends": "default"` and only token and font overrides.
+`rshow theme new <name> [--dir <parent>] [--from default]` writes it with both modes pre-filled with the base values of `--bg`, `--fg`, `--muted`, `--accent` and `--layer-01`, and prints the path plus `next: rshow theme check <dir>`.
+
+```bash
+rshow theme new acme --dir ./themes
+rshow theme check ./themes/acme
+rshow theme preview ./themes/acme --port 4321
+rshow theme publish ./themes/acme
+```
+
+`theme check` prints `theme.json:<line>: error|warning: <message>` per finding and a summary line, and exits 6 on any error.
+It names an unknown token, a colour value that is not `#hex`, `rgb()` or `var(--known-token)`, text under 4.5:1 in light, in dark or in print, a missing font file and a name that breaks the theme rules.
+`theme preview` builds the preset on its base in a temporary folder and serves it on `127.0.0.1`, with the same offline theme lookup, local `_data` store and live reload as `rshow preview`, and prints the URL of `index.html`; the temporary folder goes when the server stops.
+`theme publish` runs the check first on a preset, then publishes the built folder, so `--no-check` skips both.
+
+## skills
+
+```bash
+rshow skills install [target ...] [--link|--copy] [--dry-run]
+rshow skills uninstall [target ...] [--dry-run]
+rshow skills status [target ...] [--json]
+```
+
+The three skills, `rshow`, `rshow-slides` and `rshow-implement`, teach an agent to publish; `rshow skills install` puts them where claude, pi and codex read them.
+A target is `claude` (`~/.claude/skills`), `pi` (`~/.pi/agent/skills`) or `codex` (`~/.codex/skills`), and with no target every one whose parent folder exists is used.
+The default is a symlink to the skills folder rshow reads from; `--copy` copies it and writes a `.rshow-skill` marker with the version, which a link does not need.
+The default copies in an npx cache, because npm may delete that folder under a live link.
+Each skill prints `ok`, `installed`, `updated` or `removed`, then a summary line.
+A folder, a file or a link that rshow did not make is left alone, with `skip <dst>: exists and is not from rshow` on stderr and exit 6 on the run.
+`rshow skills uninstall` removes only what rshow made: a link into a skills folder that holds rshow skills, or a copy with the marker.
+`rshow doctor` reports the skills on one `skills` line, which warns and never fails.
+
+## handoff and compare
+
+```bash
+rshow handoff <slug>@v<n> [--out dir] [--widths 1440,390] [--modes light,dark]
+rshow compare --against <handoff-dir> [--map rshow.map.json] [--threshold 0.1] [--max-diff-ratio 0.02] [--tui-colors] [--publish]
+```
+
+`handoff` freezes a published design into a folder of `tokens.json`, `spec.json`, `HANDOFF.md` and `baseline/`, so a builder works from a copy that cannot move.
+`compare` opens that folder's screens next to the app and fails with exit 7 when a screen drifts.
+Both belong to `rshow-implement`, which owns the map, the three checks and the whole loop, so read that skill before you run either one.
+This skill publishes the mockup and hands the link over, and it never builds the app.
+
+The one exception is a tmux target, such as `tmux:mysession:0.1`, which is how a terminal app is compared cell by cell.
+
+## Config files
+
+Later files win, and the environment beats both.
+
+| File | Fields |
+|---|---|
+| `~/.config/rshow/config.json` | `url`, `art`, `theme`, `tokens` |
+| `<dir>/rshow.json` | `slug`, `title`, `theme`, `tokens`, `project`, `tags`, `build`, `out` |
+
+| Field | Meaning |
+|---|---|
+| `url` | the API base, set by `rshow init` or `RSHOW_URL`; a command that needs the API fails without it |
+| `art` | the art base the preview proxies `/_themes/` to, set by `rshow init` or `RSHOW_ART`; without it a theme lookup is skipped with a warning |
+| `slug` | the artifact to publish to, overridden by `--slug` |
+| `title` | the human title, overridden by `--title` |
+| `theme` | the theme a page should link: `<name>`, `<name>@latest` or a fixed `<name>@<n>`. `rshow config` prints it as `<name>@<n>` and you apply it by hand |
+| `tokens` | token overrides recorded and printed by `rshow config`. No command writes them into a page, so apply them by hand |
+| `build` | the command `publish` runs in the folder first |
+| `out` | the folder under `<dir>` to publish, default `dist` |
+| `project` | the project slug the artifact belongs to, overridden by `--project` |
+| `tags` | the tags to set, overridden by `--tag` |
+
+`RSHOW_URL` overrides `url` and `RSHOW_ART` overrides `art`.
+`rshow init --url <admin-url> --art <viewer-url>` writes the global file with both, keeps its other fields, and prints the next step, `rshow login`.
+`rshow doctor [dir]` checks node, both config files, the token, the API, the art host, the theme and the skills, one line each, and exits 6 when a check failed. Run it on a config error and show its output to the person.
+The token comes from `RSHOW_TOKEN`, else from the macOS Keychain, where `rshow login` saves it. It is never read from a file or from a flag.
+`XDG_CONFIG_HOME` moves the global config file away from `~/.config`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | it worked |
+| 2 | usage, which covers a bad flag, a bad slug, a missing `index.html` and a missing token |
+| 4 | auth, which covers an expired token, a revoked token and a token without the scope the command needs |
+| 5 | api or a failed build, which covers a taken slug, a refused request and a build command that exited non-zero |
+| 6 | `rshow check` found an error in the page, or a skill folder in the way is not from rshow |
+| 7 | `rshow compare` found a screen that drifted from the handoff |

package/skills/rshow/reference/dashboard.md

@@ -0,0 +1,122 @@
+# Dashboard
+
+## Contents
+
+- What it is for
+- Skeleton
+- Where the data comes from
+- Which column does what
+- The four blocks
+- State in the link
+- Checks
+
+A results dashboard is the page a reader works in rather than reads: a filter bar, a summary, small multiples and the table of rows behind them.
+It is a fixed template, so the four blocks are set and the data is the work.
+`dashboard.css` sets the look and `dashboard.js` reads the data, draws the chart and keeps the view in the link.
+
+## What it is for
+
+Use it when somebody asks the same question of the same table every week, such as what the last run did or which configuration was slowest.
+Use a report when the answer is a sentence.
+Use a deck when the answer is a room.
+A dashboard that nobody filters is a report with extra steps.
+
+## Skeleton
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Write-ahead log, results per run</title>
+<link rel="stylesheet" href="/_themes/default@3/fonts.css">
+<link rel="stylesheet" href="/_themes/default@3/tokens.css">
+<link rel="stylesheet" href="/_themes/default@3/dashboard.css">
+<script src="/_themes/default@3/mode.js"></script>
+<script defer src="/_themes/default@3/dashboard.js"></script>
+</head>
+<body>
+<div class="dashboard" data-src="results.csv" data-facet="workload"
+     data-x="nodes" data-series="system" data-metric="throughput"
+     data-unit="publishes/s" data-filters="system,workload,nodes">
+
+  <header class="dash-head">
+    <h1>Write-ahead log, results per run</h1>
+    <p class="dash-lede">One line that says what this page answers.</p>
+    <p class="dash-meta" data-dashboard-source></p>
+  </header>
+
+  <form class="dash-filters" data-dashboard-filters></form>
+  <p class="dash-status" data-dashboard-status aria-live="polite"></p>
+
+  <section class="dash-section">
+    <h2>Summary</h2>
+    <div class="dash-box" data-dashboard-summary></div>
+  </section>
+
+  <section class="dash-section">
+    <h2>Throughput by node count</h2>
+    <figure class="dash-figure">
+      <div data-dashboard-facets></div>
+      <figcaption data-dashboard-caption></figcaption>
+    </figure>
+  </section>
+
+  <section class="dash-section">
+    <h2>Runs</h2>
+    <div class="dash-toolbar" data-dashboard-toolbar></div>
+    <div class="dash-box" data-dashboard-table></div>
+  </section>
+
+</div>
+</body>
+</html>
+```
+
+## Where the data comes from
+
+The data is a file in the folder, such as `results.csv`, named by `data-src`.
+A `.json` path reads as an array of rows or as `{"rows": [...]}`, and anything else reads as CSV with quoted fields.
+A `<script type="application/json" id="data">` block wins over `data-src`, which is how a small table travels inside the one file.
+
+The content policy allows `connect-src 'self'` and nothing else, so a page never fetches from a third party.
+Publish the CSV with the page and say in the footer where the rows came from, such as the commit and the date of the run.
+Keep the CSV plain, with a header row, one row per run and one column per fact.
+
+## Which column does what
+
+Which column does what is a page decision, so it is an attribute and never a guess.
+
+| Attribute | Meaning |
+|---|---|
+| `data-facet` | the column that groups the panels and the summary |
+| `data-x` | the column on the axis |
+| `data-series` | the column that splits a panel into lines, one to eight |
+| `data-metric` | the number the summary and the chart read |
+| `data-unit` | the unit printed after a value, such as `publishes/s` |
+| `data-filters` | the columns that get a control, one select per text column and a from and to pair per number column |
+
+## The four blocks
+
+- The summary is runs, median and p95 of the metric, and it names the filter it was computed under.
+- The small multiples are one panel per facet value, on a shared scale, so a reader compares shapes and not axes.
+- The table holds the rows behind the chart, sorted by a click on a header, with numbers right aligned in tabular figures.
+- The status line says how many rows of how many are showing, and it is the only place a count of hidden rows appears.
+
+A chart is labelled at the end of the line and the palette is `--chart-1` to `--chart-8`, so no legend box is needed.
+The script reads those tokens at draw time, which is why a mode change redraws the chart instead of restyling it.
+
+## State in the link
+
+The filters and the sort live in the URL hash, so a link reproduces the view.
+Send the person the link with the filters set, because a screenshot of a filtered view is a claim nobody can check.
+The reset control returns to the whole table, and the address without a hash is the whole table.
+
+## Checks
+
+- `rshow check <dir>` exits 0, and it holds no unpinned script and no absolute request.
+- `rshow preview <dir>`, then filter, sort and reload: the view comes back from the link.
+- Look at it at desktop width and at 360px, in both modes.
+  Check that the table scrolls inside its own box.
+- Every number on the page is in the CSV, and the footer says where the CSV came from.