rshow 0.0.3 → 0.0.5

package/dist/main.js

@@ -13,7 +13,7 @@ import process from "node:process";
 // src/version.ts
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-var VERSION = true ? "0.0.3" : versionFromPackage();
+var VERSION = true ? "0.0.5" : versionFromPackage();
 
 // src/binary.ts
 var ASSET_MANIFEST = "assets.json";
@@ -754,6 +754,9 @@ async function choose(env = process8.env, platform = process8.platform) {
   if (canUse(env, platform) && await usable(env)) return storeOf("keyring", env);
   return storeOf("file", env);
 }
+function fileStore(env = process8.env) {
+  return storeOf("file", env);
+}
 async function every(env = process8.env, platform = process8.platform) {
   const stores = [];
   if (canSave(platform, env.RSHOW_SECURITY_BIN)) stores.push(storeOf("keychain", env));
@@ -761,6 +764,23 @@ async function every(env = process8.env, platform = process8.platform) {
   stores.push(storeOf("file", env));
   return stores;
 }
+async function find(env, url, platform = process8.platform) {
+  const forcedBackend = forced(env);
+  const stores = forcedBackend === void 0 ? await every(env, platform) : [storeOf(forcedBackend, env)];
+  let failed = false;
+  let firstError;
+  for (const store2 of stores) {
+    try {
+      const token = await store2.read(url);
+      if (token !== void 0) return { store: store2, token };
+    } catch (err) {
+      if (!failed) firstError = err;
+      failed = true;
+    }
+  }
+  if (failed) throw firstError;
+  return void 0;
+}
 
 // src/config.ts
 var DEFAULT_OUT = "dist";
@@ -894,9 +914,8 @@ function requireArt(config) {
 async function readToken(env, url) {
   const token = (env.RSHOW_TOKEN ?? "").trim();
   if (token !== "") return token;
-  const store2 = await choose(env);
-  const saved = await store2.read(url);
-  if (saved !== void 0) return saved;
+  const found = await find(env, url);
+  if (found !== void 0) return found.token;
   throw new UsageError("no token: run rshow login, or set RSHOW_TOKEN");
 }
 
@@ -4531,9 +4550,8 @@ async function tokenOf(url) {
   if (env !== "") return { token: env, source: "env" };
   if (url === void 0) return {};
   try {
-    const store2 = await choose(process13.env);
-    const saved = await store2.read(url);
-    if (saved !== void 0) return { token: saved, source: store2.detail };
+    const found = await find(process13.env, url);
+    if (found !== void 0) return { token: found.token, source: found.store.detail };
     return {};
   } catch (err) {
     return { error: messageOf10(err) };
@@ -8744,6 +8762,17 @@ async function tokenFromStdin() {
   if (!token.startsWith(TOKEN_PREFIX)) throw new UsageError(`that is not an rshow token: it must start with ${TOKEN_PREFIX}`);
   return token;
 }
+async function saveIn(store2, url, token) {
+  await store2.save(url, token);
+  if (await store2.read(url) !== token) {
+    throw new ApiError(`cannot save the token in ${store2.description}`);
+  }
+}
+function reasonOf(err) {
+  const text = (err instanceof Error ? err.message : String(err)).replace(/^cannot save the token in the keyring: /, "");
+  const lines = text.split("\n").map((part) => part.trim()).filter((part) => part !== "");
+  return lines.at(-1) ?? "";
+}
 async function run19(argv, ctx, platform = process21.platform) {
   const args = parseCommandArgs(argv, { url: { type: "string" } }, 0, 0, LOGIN_USAGE);
   const settings = await ctx.config();
@@ -8753,10 +8782,19 @@ async function run19(argv, ctx, platform = process21.platform) {
   const me = (await new Client(url, token).send("GET", "/api/me")).body;
   const email = typeof me?.email === "string" ? me.email : "";
   const scope = typeof me?.scope === "string" ? me.scope : "";
-  const store2 = await choose(process21.env, platform);
-  await store2.save(url, token);
-  if (await store2.read(url) !== token) {
-    throw new ApiError(`cannot save the token in ${store2.description}`);
+  let store2 = await choose(process21.env, platform);
+  if (store2.backend === "keyring" && forced(process21.env) === void 0) {
+    try {
+      await saveIn(store2, url, token);
+    } catch (err) {
+      warn(`the Linux keyring cannot save the token (${reasonOf(err)}); saving it in a file`);
+      await store2.remove(url).catch(() => {
+      });
+      store2 = fileStore(process21.env);
+      await saveIn(store2, url, token);
+    }
+  } else {
+    await saveIn(store2, url, token);
   }
   ctx.out.data({ email, scope, url });
   ctx.out.line(`logged in as ${email} (scope ${scope}) for ${url}, saved in ${store2.description}`);

package/package.json

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

package/skills/rshow/SKILL.md

@@ -47,8 +47,13 @@ Copy this checklist into the reply and tick it as you go.
   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`.
+- 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.
+  A hard-coded colour sits inside a figure only.
+- Own CSS adds a class and never restyles a theme class globally.
+  Scope a new deck layout as `.slide.<name>` and scope a page part under its own class name, and use no `!important`.
+- A token override still goes in one `:root` block, with no limit on the declarations.
 - Keep the script and the styles inline.
   Add a framework only when the page needs one.
 - `connect-src` is `'self'`.
@@ -64,9 +69,10 @@ Copy this checklist into the reply and tick it as you go.
   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.
+- Documented templates carry decks, reports, posters, project pages and dashboards, so the markup is documented and the content is the work.
+  The markup is the starting point, and a page adds its own parts with its own classes when it needs them.
 - 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.
+  Starting a kit at its highest fidelity is the same mistake as decorating a documented template.
 
 ## Audience
 

package/skills/rshow/reference/dashboard.md

@@ -11,7 +11,7 @@
 - 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.
+It is a documented template, so the four blocks are the starting point and the data is the work, and a page may add its own parts with its own classes.
 `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

package/skills/rshow/reference/mockups.md

@@ -13,15 +13,17 @@
 - Look at it
 
 A mockup is a drawing of a product that does not exist yet, so it follows that product and not rshow.
-Decks, reports, posters, project pages and dashboards are fixed templates, while a mockup is a guided kit: the kit gives you a frame, a floor and a checklist, and the drawing is the work.
+Decks, reports, posters, project pages and dashboards are documented templates, while a mockup is a guided kit: the kit gives you a frame, a floor and a checklist, and the drawing is the work.
 `themes/MOCKUPS.md` in the rshow repo holds the kit itself, and this file is what to do with it.
 
 ## A guided kit
 
-- Start in `wire` every time, because a tidy drawing invites a room to argue about the colour of a button instead of the order of the steps.
-- Move to `sketch` when the room is too polite about a finished looking picture.
-- Move to a platform skin only when the look of the product is the decision.
+- Pick the skin from the question.
+- Use `wire` when the flow or the order of the layout is the question, because a tidy drawing invites a room to argue about the colour of a button instead of the order of the steps.
+- Use `sketch` for an early rough idea, or when the room is too polite about a finished looking picture.
+- Use a platform skin, or `tui` and `terminal` for a terminal, when the look is the decision or the person asks for the look.
 - Keep the inventing to layout, spacing, hierarchy and the order of steps.
+  Own CSS inside a screen is allowed for the part the kit lacks, and it takes colour from the `--mk-*` and theme tokens so a skin swap and dark mode still read.
   Data, copy, names and prices are placeholders and say so.
 
 ## Markup

package/skills/rshow/reference/pages.md

@@ -71,9 +71,11 @@ Every link carries the same version on purpose, because a mixed version renders
 ```
 
 `page.css` gives you `lede`, `table`, `num-cell`, `muted`, `small` and `mono`, plus the heading, list, figure, table and code rules.
-Use them and keep your own CSS to the one `:root` block.
+The theme is the base, not a cage.
+Use these classes first, and add a class of your own in one inline `<style>` block when the page needs a part the theme does not carry.
+Own CSS takes colour, type and space from the tokens with `var(--...)`, and it never restyles a theme class globally.
 There is no card class, no label class and no number tile.
-A page that needs one is usually a page with a table it has not written yet.
+A page that needs one writes it, and a page that needs only a table writes the table.
 
 The theme carries both modes, so the same page reads on white and on g100 with nothing in the page itself.
 
@@ -96,8 +98,8 @@ Print is always light, whatever the screen was.
 
 ## Token overrides
 
-Override a token instead of writing rules.
-Five declarations cover most restyling.
+Override a token instead of restyling a theme class.
+A few declarations cover most restyling, and there is no limit on how many.
 
 ```html
 <style>:root{

package/skills/rshow/reference/poster.md

@@ -11,7 +11,7 @@
 - Checks
 
 A poster is one sheet that prints from the browser, in the same theme as a page, a report and a project page.
-It is a fixed template, so the sheet, the columns and the print are set and the blocks are the work.
+It is a documented template, so the sheet, the columns and the print are set and the blocks are the starting point, and a page may add its own parts with its own classes.
 `poster.css` sets the look and `poster.js` sets the scale, the QR code and the one page print.
 
 ## The sheet

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

@@ -11,7 +11,7 @@
 - Checks
 
 A project page is the landing page of a paper, and it uses the same theme as a page, a report and a poster.
-It is a fixed template, so the sections are set and the content is the work.
+It is a documented template, so the sections are the starting point and the content is the work, and a page may add its own parts with its own classes.
 `project.css` sets the look and `project.js` does one thing, the copy button on the BibTeX entry.
 
 A project page is not a project.

package/skills/rshow/reference/sketch.md

@@ -11,7 +11,7 @@
 - Checks
 
 A sketch is a hand drawn figure from Excalidraw, read in the page and edited in place.
-It is a guided kit rather than a fixed template: `sketch.css` is the bar around the canvas and `sketch.js` is the canvas.
+It is a guided kit rather than a documented template: `sketch.css` is the bar around the canvas and `sketch.js` is the canvas.
 Use it for an architecture drawing, a flow of systems or an idea that should look unfinished.
 
 ## When a sketch

package/skills/rshow-slides/SKILL.md

@@ -6,8 +6,8 @@ description: Load before you build or revise a talk, deck or presentation. Load
 # rshow slides
 
 A deck is a folder with one `index.html` in it, published to `https://art.example.com/<slug>/`.
-It links the deck half of a published theme, so the folder holds no CSS, no font and no script of its own.
-The theme does the layout, and the deck only picks a layout per slide.
+It links the deck half of a published theme, so the folder holds no copy of the theme, no font and no script of its own.
+The theme does the layout, and the deck picks a layout per slide or adds one of its own in an inline `<style>` block.
 The look is IBM Carbon on IBM Plex, and `themes/DESIGN.md` in the rshow repo holds the whole system.
 
 ## 1. Outline first
@@ -23,6 +23,7 @@ A topic on its own is not a slide.
 - Open with a `title` slide and close with a `title` slide or a `big-number` that says what to do next.
 - Put one `section` slide before each move in the argument.
 - Give the evidence slides the layout that carries the claim: `figure`, `chart`, `table` or `figure-two` for a research or systems talk.
+- Name the layout of each line in the outline, including any layout the deck adds for itself.
 - In a research talk the figure, the plot and the table are the hero.
   The title says what the evidence shows and the type stays out of the way.
 - Say which slide carries the headline number, and put the number in it once.
@@ -71,11 +72,12 @@ Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, wh
 
 The three stylesheet links and the script carry the same `<n>` on purpose, because a mixed version renders somewhere between two designs.
 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, and keep it to a few declarations.
+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.
 
 ## 3. Layouts
 
-Every slide is a `<section class="slide ...">`, and the second class is one of twelve.
+Every slide is a `<section class="slide ...">`, and the second class is one of twelve or one the deck adds.
 
 - `title` for the opener, `section` for a divider and `statement` for one claim set large.
 - `bullets` for a takeaway title and at most five short points.
@@ -89,8 +91,11 @@ A bullets slide puts its points under the title at 28px with a 1.4 line, five at
 A figure slide starts at the top and lets the figure take the rest.
 A figure is `<figure>` with a `figcaption`, and two figures are `<div class="pair">` with two `<figure>` inside.
 A big number is `<p class="value">` plus `<p class="caption">`, and the value is a short statement with the figure inside it, never a bare digit.
-Do not invent a thirteenth layout and do not write the layout CSS yourself, because the theme owns it and a copy drifts.
-[layouts](reference/layouts.md) holds one markup example per layout. Read it before you write a slide that is not `title`, `bullets` or `section`.
+The twelve layouts are a starting set and not a ceiling.
+Invent a layout when none of them carries the claim, such as an annotated figure, a figure with a callout, a diagram built in HTML or SVG, a timeline, a before and after or a comparison grid.
+Give it a short class name and put its CSS in the deck's own `<style>` block, scoped to `.slide.<name>` and taken from the tokens.
+Vary the rhythm: do not run more than three text slides (`two-col` or `bullets`) in a row, and turn a text slide that explains a figure into an annotated figure.
+[layouts](reference/layouts.md) holds one markup example per layout and one worked example of your own layout. Read it before you write a slide that is not `title`, `bullets` or `section`.
 
 ## 4. Notes and steps
 
@@ -99,7 +104,8 @@ Do not invent a thirteenth layout and do not write the layout CSS yourself, beca
   It is what you say, not what the room reads.
 - Press `n` for the notes window, which also names the next slide.
 - Press `p` for the presenter view: the current slide, the next slide, the notes and an elapsed timer, kept in step with the deck.
-- Put `class="step"` on an `<li>` to reveal it one press later.
+- Put `class="step"` on any element inside a slide to reveal it one press later, because `deck.js` selects every `.step` in the slide.
+  That is how a diagram builds up in steps.
 - Every step is a reveal, so a slide with four steps needs four presses.
   Five is the ceiling before the slide drags.
 - Press `f` for fullscreen and arrows or space to advance.
@@ -132,5 +138,6 @@ Publish again after a fix instead of making a second slug, because the link in t
 - 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 animate a slide in, because a reveal is the only motion a deck needs.
+- Never animate a slide in for decoration.
+  Motion is allowed when it explains something, such as a step that builds a diagram or a short transition that shows a change.
 - Never invent a number and never present example data without saying so in the caption.

package/skills/rshow-slides/reference/layouts.md

@@ -14,9 +14,11 @@
 - two-col
 - quote
 - big-number
+- your own layout
 
 One markup example per layout, all inside `<main class="deck">`.
 Every slide carries `slide` plus one layout class, and the layout class goes second.
+The twelve are a starting set: a deck may add a layout of its own when none of them carries the claim.
 Nothing sits above a title: no kicker, no label, no number.
 
 A sparse slide (`title`, `section`, `statement`, `quote`, `big-number`, `bullets`) is centred a little above the middle of the 1280x720 canvas, so the air sits under the block instead of closing it in.
@@ -249,3 +251,51 @@ The unit belongs in the statement and the source goes under it.
 ```
 
 A number you cannot measure is `[PLACEHOLDER]` until it is real, and a number that stands for an example says so in the source line.
+
+## your own layout
+
+A layout of your own takes a short class name and sits second on the slide, in the same slot as the twelve.
+Pick the shape the claim needs, such as an annotated figure, a figure with a callout, a diagram built in HTML or SVG, a timeline, a before and after or a comparison grid.
+Its CSS goes in one inline `<style>` block after the theme links, scoped to `.slide.<name>`, with colour, type and space from the tokens.
+Here one figure carries three callouts, and they stack under it below 640px.
+
+```html
+<style>
+.slide.annotated .annotated-fig { position: relative; margin: 0; }
+.slide.annotated .annotated-fig img { display: block; width: 100%; }
+.slide.annotated .callout {
+  position: absolute;
+  max-width: 30%;
+  padding: var(--space-03) var(--space-04);
+  background: var(--layer-01);
+  border: 1px solid var(--border-strong);
+  color: var(--fg);
+  font-size: 18px;
+  line-height: 1.4;
+}
+.slide.annotated .callout.one { top: 6%; left: 3%; }
+.slide.annotated .callout.two { top: 40%; right: 3%; }
+.slide.annotated .callout.three { bottom: 6%; left: 30%; }
+@media (max-width: 640px) {
+  .slide.annotated .callout {
+    position: static;
+    max-width: none;
+    margin: var(--space-03) 0 0;
+    padding: 0;
+    border: 0;
+  }
+}
+</style>
+
+<section class="slide annotated">
+  <h2>The tail of the log is what a restart replays</h2>
+  <figure class="annotated-fig">
+    <img src="write-path.svg" alt="A log appended before the map is updated, with three stages marked.">
+    <p class="callout one">The append lands first.</p>
+    <p class="callout two">The map follows it.</p>
+    <p class="callout three">A crash replays the tail.</p>
+    <figcaption>A restart loses nothing after step 2.</figcaption>
+  </figure>
+  <aside class="notes"><p>Trace the three callouts in order.</p></aside>
+</section>
+```

package/themes/default/index.html

@@ -409,9 +409,11 @@
   <p>Every layout the theme ships, one frame each. A frame is lazy loaded, so
   the page stays light on a phone, and the link under it opens the same example
   full size. The deck, the page, the report, the project page, the poster and
-  the dashboard are fixed templates with a documented markup. The mockups, the
-  sketches, the terminals and the tuis are guided kits: they give an agent a
-  frame, a floor and a set of rules, and the drawing is the work.</p>
+  the dashboard are documented templates: the markup is the starting point, and
+  a page may add its own layouts and classes on top, with colours from the
+  tokens. The mockups, the sketches, the terminals and the tuis are guided kits:
+  they give an agent a frame, a floor and a set of rules, and the drawing is the
+  work.</p>
 
   <div class="layouts">
     <article class="layout">