rshow 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rshow",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Publish static artifacts to rshow",
   "license": "MIT",
   "homepage": "https://rslib.github.io/rshow",

package/skills/rshow/SKILL.md

@@ -20,7 +20,7 @@ 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
+- [ ] page written, theme linked at `@latest`
 - [ ] rshow check <dir> exits 0
 - [ ] rshow preview <dir> looked at 360px wide and at desktop width
 - [ ] audience confirmed with the person
@@ -30,7 +30,7 @@ Copy this checklist into the reply and tick it as you go.
 ```
 
 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.
+2. Write `index.html` in its own folder, link the theme at `@latest` 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.
@@ -46,7 +46,10 @@ Copy this checklist into the reply and tick it as you go.
 - 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.
+  The stylesheet links and `mode.js` in the head all carry the same `<name>@latest`.
+- Link `@latest`, so a theme fix reaches the page with no republish.
+  Write a number only when the person asks to freeze a page, such as a talk on the day it is given.
+  A page frozen on a number needs 8 or newer for math.
 - The theme is the base, not a cage.
   A page may carry one inline `<style>` block with its own classes and its own layouts when the content needs them.
   Own CSS takes colour, type and space from the theme tokens with `var(--...)`, so light, dark, print and a theme swap keep working.
@@ -63,7 +66,6 @@ Copy this checklist into the reply and tick it as you go.
 - 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.
 - Math is LaTeX in the text of an element with the class `math`, and the page links `math.css` and `math.js` for it.
-  Math needs theme version 8 or newer, so a page on an older version moves up with `rshow config <dir>`.
   A `div.math` is display math and any other element is inline.
   A `$` in the prose is a price and is never read as math, so `$5` stays text.
   Read [reports](reference/reports.md) for the markup an equation takes.
@@ -154,4 +156,4 @@ The short list above is a hard rule.
   Write the LaTeX in an element with the class `math` and link `math.css` and `math.js`.
 - 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.
+- Never delete a version, a theme or an artifact, and never drop a share, unless the person asks for it.

package/skills/rshow/reference/cli.md

@@ -25,9 +25,10 @@ This file is the whole surface, both config files and the exit codes.
 | `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 config [dir] [--offline]` | print the merged config as JSON, with `theme` as `<name>@latest` and, with the network, `theme_resolved` as the version it resolves to |
 | `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 upgrade [--check] [--version x.y.z] [--force]` | replace the single executable, or run `npm install -g` on an npm install, with another release |
 | `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 |
@@ -36,7 +37,7 @@ This file is the whole surface, both config files and the exit codes.
 | `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 delete <slug> [--version n] [--force] --yes` | delete an artifact, or one version of it |
 | `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` |
@@ -51,6 +52,10 @@ This file is the whole surface, both config files and the exit codes.
 `--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.
 
+`rshow upgrade` moves an installed rshow to the newest release, or to the one `--version` names, and `--check` prints both versions and changes nothing.
+It needs no config and no token, and a source checkout or an npx cache is named with the tool that owns it instead of being touched.
+Run `rshow upgrade` only when the person asks for it.
+
 Every flag takes `--flag value` or `--flag=value`.
 `--add`, `--editor`, `--remove` and `--tag` accept several values in a row after one flag.
 
@@ -77,7 +82,7 @@ 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.
+A published page that links `/_themes/<name>@<n>/` or `/_themes/<name>@latest/` needs the network to confirm the theme 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.
@@ -90,7 +95,7 @@ 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.
+It works offline: `/_themes/<name>@<n>/` and `/_themes/<name>@latest/` come 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
@@ -174,8 +179,10 @@ Set the tags and the project in `rshow.json` when they are a fact about the fold
 `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.
+`rshow delete <slug> --yes` deletes the artifact and every version, and `--version <n>` deletes only that version.
 It needs `--yes`, and it needs a yes from the person.
+A theme or a theme version also needs `--force`, because pages link to it.
+A public version can stay visible for up to 5 minutes after the delete, and a theme file for longer, so tell the person this when they delete to take something down.
 
 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>`.
@@ -238,7 +245,7 @@ Later files win, and the environment beats both.
 | `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 |
+| `theme` | the theme a page should link: `<name>`, `<name>@latest` or a fixed `<name>@<n>`. Agents link `<name>@latest` and `rshow config` keeps it that way, with `theme_resolved` beside it when the lookup works |
 | `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` |

package/skills/rshow/reference/dashboard.md

@@ -30,11 +30,11 @@ A dashboard that nobody filters is a report with extra steps.
 <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>
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/dashboard.css">
+<script src="/_themes/default@latest/mode.js"></script>
+<script defer src="/_themes/default@latest/dashboard.js"></script>
 </head>
 <body>
 <div class="dashboard" data-src="results.csv" data-facet="workload"

package/skills/rshow/reference/page-contract.md

@@ -8,7 +8,7 @@ It reads the files a publish would upload, so for a prerendered site it reads th
 
 - One `index.html` at the root of the folder you publish.
 - Every other path inside the artifact is relative and has no leading slash, such as `chart.svg`.
-- The two root-relative prefixes are `/_themes/<name>@<n>/` and `/_data/`, and both point at the host on purpose.
+- The root-relative prefixes are `/_themes/<name>@latest/`, `/_themes/<name>@<n>/` and `/_data/`, and all point at the host on purpose.
 - At most 2000 files and 100 MiB per version, and at most 25 MiB per file.
 - No theme file in the artifact.
   No `deck.css`, no `page.css`, no font file, no `assets/` copy of a theme.
@@ -34,6 +34,7 @@ The theme files under `/_themes/` count as `'self'`, so a linked theme needs no
 ## CDN builds, pinned
 
 Pin the exact version in the URL and never write `@latest` or a moving tag, which `rshow check` counts as an error.
+A theme link is the one moving link that is allowed, so `/_themes/<name>@latest/` is right and a number is for a frozen page.
 
 | Library | Pinned URL |
 |---|---|

package/skills/rshow/reference/pages.md

@@ -27,8 +27,8 @@ A single file published on its own becomes `index.html` and nothing else is uplo
 
 ## The skeleton
 
-Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, which the server resolves to the current version. Use `default@3` only when `rshow config` warns that it cannot resolve the theme.
-Every link carries the same version on purpose, because a mixed version renders somewhere between two designs.
+Link the theme at `@latest`, so a theme fix reaches the page with no republish. Write a number only when the person asks to freeze a page, such as a talk on the day it is given. A page frozen on a number needs 8 or newer for math.
+Every link names the same theme on purpose, and all of them use `@latest` or all use the same number, because a mix of two versions renders somewhere between two designs.
 
 ```html
 <!doctype html>
@@ -37,10 +37,10 @@ Every link carries the same version on purpose, because a mixed version renders
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Q3 latency report</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/page.css">
-<script src="/_themes/default@3/mode.js"></script>
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/page.css">
+<script src="/_themes/default@latest/mode.js"></script>
 <style>:root{--accent: #0f62fe;}</style>
 </head>
 <body>
@@ -164,7 +164,7 @@ Put the same thing in `rshow.json` when it should not be retyped:
 {
   "slug": "status",
   "title": "Cluster status",
-  "theme": "default@3",
+  "theme": "default@latest",
   "build": "npm run build",
   "out": "dist"
 }

package/skills/rshow/reference/poster.md

@@ -37,12 +37,12 @@ The status line beside the buttons always names the width and the height, so the
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Immutable artifacts for reproducible figures</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/poster.css">
-<script src="/_themes/default@3/mode.js"></script>
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/poster.css">
+<script src="/_themes/default@latest/mode.js"></script>
 <script defer src="https://cdn.jsdelivr.net/npm/qrcode-generator@1.4.4/qrcode.js"></script>
-<script defer src="/_themes/default@3/poster.js"></script>
+<script defer src="/_themes/default@latest/poster.js"></script>
 </head>
 <body>
 

package/skills/rshow/reference/project-page.md

@@ -38,11 +38,11 @@ Link `fonts.css`, `tokens.css` and `project.css`, then `mode.js` in the head and
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Immutable artifacts for reproducible figures</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/project.css">
-<script src="/_themes/default@3/mode.js"></script>
-<script defer src="/_themes/default@3/project.js"></script>
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/project.css">
+<script src="/_themes/default@latest/mode.js"></script>
+<script defer src="/_themes/default@latest/project.js"></script>
 </head>
 <body>
 <div class="project">

package/skills/rshow/reference/reports.md

@@ -35,11 +35,11 @@ Link `fonts.css`, `tokens.css` and `report.css`, then `mode.js` in the head and
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Publishing a folder as an immutable artifact</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/report.css">
-<script src="/_themes/default@3/mode.js"></script>
-<script defer src="/_themes/default@3/report.js"></script>
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/report.css">
+<script src="/_themes/default@latest/mode.js"></script>
+<script defer src="/_themes/default@latest/report.js"></script>
 </head>
 <body>
 <div class="report">

package/skills/rshow/reference/sketch.md

@@ -23,11 +23,11 @@ A sketch is also the honest shape for a workshop, where a tidy drawing would end
 ## Markup
 
 ```html
-<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/sketch.css">
-<script src="/_themes/default@3/mode.js"></script>
-<script defer src="/_themes/default@3/sketch.js"></script>
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/sketch.css">
+<script src="/_themes/default@latest/mode.js"></script>
+<script defer src="/_themes/default@latest/sketch.js"></script>
 ...
 <div class="sketch" data-src="drawing.excalidraw" data-store="sketch-main"></div>
 ```

package/skills/rshow/reference/terminal.md

@@ -26,11 +26,11 @@ The viewer and the TUI kit are the theme's, and both are guided kits: the frame
 ## The viewer
 
 ```html
-<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/terminal.css">
-<script src="/_themes/default@3/mode.js"></script>
-<script defer src="/_themes/default@3/terminal.js"></script>
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/terminal.css">
+<script src="/_themes/default@latest/mode.js"></script>
+<script defer src="/_themes/default@latest/terminal.js"></script>
 ...
 <figure class="terminal" data-mode="ansi" data-src="capture.ans"
         data-cols="100" data-rows="30" data-title="procview" data-palette="default"></figure>

package/skills/rshow-slides/SKILL.md

@@ -32,8 +32,7 @@ A topic on its own is not a slide.
 
 ## 2. Skeleton
 
-Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, which the server resolves to the current version. Use `default@3` only when `rshow config` warns that it cannot resolve the theme.
-Math needs theme version 8 or newer, so a page on an older version moves up with `rshow config <dir>`.
+Link the theme at `@latest`, so a theme fix reaches the deck with no republish. Write a number only when the person asks to freeze a deck, such as a talk on the day it is given. A deck frozen on a number needs 8 or newer for math.
 
 ```html
 <!doctype html>
@@ -42,12 +41,12 @@ Math needs theme version 8 or newer, so a page on an older version moves up with
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Talk title</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/deck.css">
+<link rel="stylesheet" href="/_themes/default@latest/fonts.css">
+<link rel="stylesheet" href="/_themes/default@latest/tokens.css">
+<link rel="stylesheet" href="/_themes/default@latest/deck.css">
 <!-- a deck that writes math links these two, and math.js goes before deck.js -->
-<link rel="stylesheet" href="/_themes/default@3/math.css">
-<script defer src="/_themes/default@3/math.js"></script>
+<link rel="stylesheet" href="/_themes/default@latest/math.css">
+<script defer src="/_themes/default@latest/math.js"></script>
 </head>
 <body>
 <main class="deck">
@@ -69,13 +68,12 @@ Math needs theme version 8 or newer, so a page on an older version moves up with
   </section>
 
 </main>
-<script src="/_themes/default@3/deck.js"></script>
+<script src="/_themes/default@latest/deck.js"></script>
 </body>
 </html>
 ```
 
-The three stylesheet links and the script carry the same `<n>` on purpose, because a mixed version renders somewhere between two designs.
-A fallback to `default@3` keeps the page readable but has no math, so a deck on that version links neither `math.css` nor `math.js`, and the `math.js` warning of `rshow check` is the sign to move up.
+The three stylesheet links and the script carry `@latest` on purpose, so a theme fix reaches every deck on the next open.
 The deck needs no `mode.js`, because `deck.js` reads the same key and `t` does the same work.
 Override a token in one `:root` block after the theme links when the deck needs its own accent, with no limit on the declarations.
 An inline `<style>` block after the theme links may also carry a layout of the deck's own, as section 3 says.