explico 0.12.0 → 0.13.1

package/src/rules/settings.ts

@@ -174,6 +174,16 @@ export function resolveRules(config: CourseConfig): ResolvedRules {
     });
   }
 
+  if (config.conventions !== undefined) {
+    diagnostics.push({
+      code: 'config-deprecated-key',
+      severity: 'warning',
+      message:
+        'CourseConfig `conventions` is no longer read: rule S5, its only reader, was retired into rule N4. ' +
+        'Delete the block. See docs/authoring/retired.md.',
+    });
+  }
+
   const enabled = new Map<string, boolean>();
   const settings = new Map<string, Readonly<Record<string, unknown>>>();
 

package/src/session/PreferenceStore.ts

@@ -11,6 +11,8 @@
  * cookie-backed store) and nothing else changes. `createBrowserPreferenceStore`
  * is the "versioned local-storage adapter" the architecture doc anticipates —
  * kept deliberately tiny, and the only place `git grep localStorage` matches.
+ * `createSessionPreferenceStore` is its per-tab twin, for state one tab keeps
+ * of its own (the cards it carries, `card-carry.ts`).
  */
 
 export interface PreferenceStore {
@@ -54,6 +56,57 @@ export function createBrowserPreferenceStore(): PreferenceStore {
   };
 }
 
+/**
+ * A `sessionStorage`-backed store: one tab's own state, which a reload, Back
+ * and Forward keep and another tab never sees. Wrapped like the local one.
+ */
+export function createSessionPreferenceStore(): PreferenceStore {
+  return {
+    get(key) {
+      try {
+        return window.sessionStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        window.sessionStorage.setItem(key, value);
+      } catch {
+        // Storage unavailable or full — the tab still works, it just forgets.
+      }
+    },
+    remove(key) {
+      try {
+        window.sessionStorage.removeItem(key);
+      } catch {
+        // Storage unavailable — there is nothing stored to forget.
+      }
+    },
+  };
+}
+
+/**
+ * The store's one inline twin: the source of a script that copies a stored
+ * preference onto the root element as `attribute` before the page first
+ * paints. Every other reader of a preference is a module script, which runs
+ * after that paint: fine for a panel's state, but a page drawn at one text
+ * size and then redrawn at another visibly jumps. Only a value in `values`
+ * is copied; anything else stored is ignored. It is built here so that
+ * browser storage is still touched in this file alone.
+ */
+export function inlineRootAttributeScript(
+  key: string,
+  attribute: string,
+  values: readonly string[],
+): string {
+  return (
+    `try{var v=window.localStorage.getItem(${JSON.stringify(key)});` +
+    `if(${JSON.stringify(values)}.indexOf(v)>=0)` +
+    `document.documentElement.setAttribute(${JSON.stringify(attribute)},v)}catch(e){}`
+  );
+}
+
 /** An in-memory store — the no-op-equivalent seam for SSR or tests. */
 export function createMemoryPreferenceStore(): PreferenceStore {
   const map = new Map<string, string>();

package/src/styles/global.css

@@ -188,6 +188,28 @@ body {
   padding-inline: 2px;
 }
 
+/* An equation wider than the column scrolls inside it, with no scrollbar on
+   a phone: the edge it is cut at fades, so the reader sees the formula goes
+   on (`data-overflow`, set by `KeyedFloatEnhancer.astro`). The mask fades the
+   ink, whatever the background; focus and print show the equation whole. */
+.sl-markdown-content .katex-display[data-overflow='end'] {
+  mask-image: linear-gradient(to right, #000 calc(100% - 2.5rem), transparent);
+}
+.sl-markdown-content .katex-display[data-overflow='start'] {
+  mask-image: linear-gradient(to left, #000 calc(100% - 2.5rem), transparent);
+}
+.sl-markdown-content .katex-display[data-overflow='start end'] {
+  mask-image: linear-gradient(to right, transparent, #000 2.5rem, #000 calc(100% - 2.5rem), transparent);
+}
+.sl-markdown-content .katex-display[data-overflow]:focus-visible {
+  mask-image: none;
+}
+@media print {
+  .sl-markdown-content .katex-display[data-overflow] {
+    mask-image: none;
+  }
+}
+
 /* Focusable only while it overflows (`KeyedFloatEnhancer.astro`), so it can
    be scrolled from the keyboard. */
 .sl-markdown-content .katex-display:focus-visible {
@@ -264,6 +286,24 @@ body {
   margin-block-start: 0;
 }
 
+/* The reader's text size on a touch screen (`TextSizeControl.astro`): the
+   root font size, which every `rem` follows, so the text, the math, the
+   spacing and the cards scale together. Screen only: print keeps its own
+   sizes, and a screen with hover has the browser's zoom instead. */
+@media screen and (hover: none) {
+  :root[data-text-size='90'] {
+    font-size: 90%;
+  }
+
+  :root[data-text-size='80'] {
+    font-size: 80%;
+  }
+
+  :root[data-text-size='70'] {
+    font-size: 70%;
+  }
+}
+
 .lab-chart {
   overflow-x: auto;
   min-height: 18rem;
@@ -276,6 +316,14 @@ body {
   background: var(--sl-color-bg);
 }
 
+/* A lab shows the build's copy of its default plot (its children, in an
+   `<astro-slot>`) until it has drawn its own into `.lab-chart-live`. The
+   copy goes the moment the live plot exists, so the two never stack, not
+   even for the frame before the island drops it (rule V3). */
+.lab-chart:has(> .lab-chart-live > svg) > astro-slot {
+  display: none;
+}
+
 .cds-leg-chart:empty {
   display: none;
 }
@@ -1372,7 +1420,7 @@ details.layout-part-has-open > summary > .group-label {
    end. It rises above the raised header, or the header's box takes every
    tap and the navigation never opens on a phone. Starlight hides the
    button from 50rem up, so the rule needs no media query. */
-starlight-menu-button > button {
+.sl-menu-button {
   z-index: calc(var(--sl-z-index-navbar) + 2);
 }
 
@@ -1417,13 +1465,111 @@ starlight-menu-button > button {
   z-index: var(--sl-z-index-toc);
 }
 
-/* S9: "Keep the article left", fixed at the top of the side column just
-   under the header, over the cards scrolling past it. `card-side.ts` sets
-   its `left`. */
-.explico-keep-left {
+/* The row of card controls (`card-side.ts`, S9, S11, K1): at the top of the
+   side column, "Article left", "Carry cards" and, once a card has been
+   resized, the width menu; with no side column in use, "Carry cards" alone
+   at the article's top right while a card is kept (D7). Fixed just under
+   the site header, over the cards scrolling past; `card-side.ts` sets its
+   `left` or `right`. It wraps rather than reaching over the rail. */
+.explico-side-controls {
   position: fixed;
   z-index: var(--sl-z-index-navbar);
   top: calc(var(--sl-nav-height) + 0.5rem);
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+.explico-side-controls[data-at='article'] {
+  justify-content: flex-end;
+}
+
+.explico-side-controls[hidden] {
+  display: none;
+}
+
+/* S11: the width menu, a pill like the switch beside it. */
+.explico-side-width {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.2rem 0.35rem 0.2rem 0.65rem;
+  border: var(--ex-edge-border);
+  border-radius: 999px;
+  font-size: var(--sl-text-xs);
+  line-height: 1.4;
+  color: var(--sl-color-gray-2);
+  background: var(--sl-color-bg);
+  box-shadow: var(--sl-shadow-sm);
+}
+
+.explico-side-width[hidden] {
+  display: none;
+}
+
+.explico-side-width select {
+  border: 0;
+  padding: 0 0.2rem;
+  font: inherit;
+  color: var(--sl-color-text);
+  background: transparent;
+  cursor: pointer;
+}
+
+.explico-side-width:focus-within {
+  outline: 3px solid var(--sl-color-accent);
+  outline-offset: 2px;
+}
+
+/* K7: a card's "Opened at" link lands on the trigger the card was opened
+   at, and lights it a moment (`card-manager.ts`, `is-card-origin`). */
+.is-card-origin {
+  border-radius: 0.2em;
+  animation: explico-card-origin 1.2s ease-out;
+}
+
+@keyframes explico-card-origin {
+  from {
+    background-color: var(--sl-color-accent-low);
+    box-shadow: 0 0 0 0.2em var(--sl-color-accent-low);
+  }
+  to {
+    background-color: transparent;
+    box-shadow: 0 0 0 0.2em transparent;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .is-card-origin {
+    animation: none;
+    background-color: var(--sl-color-accent-low);
+  }
+}
+
+/* K5: cards carried in from another page and held at the window's bottom
+   edge never leave it, so they would cover the page's last stretch — its
+   Next and Previous links. The page grows by their stack, so its end
+   scrolls clear of them (`card-manager.ts` sets the room). */
+@media screen {
+  body {
+    padding-block-end: var(--explico-carried-room, 0px);
+  }
+}
+
+/* S11: while a docked card reaches over the rail, the rail goes under the
+   card layer, so the card and its edge stay whole; the header covers both. */
+:root[data-card-over-rail] .right-sidebar {
+  z-index: calc(var(--sl-z-index-navbar) - 1);
+}
+
+:root[data-card-resizing],
+:root[data-card-resizing] * {
+  cursor: col-resize !important;
+  user-select: none;
+}
+
+.explico-side-switch {
   display: inline-flex;
   align-items: center;
   gap: 0.45rem;
@@ -1440,20 +1586,20 @@ starlight-menu-button > button {
   cursor: pointer;
 }
 
-.explico-keep-left[hidden] {
+.explico-side-switch[hidden] {
   display: none;
 }
 
-.explico-keep-left:hover {
+.explico-side-switch:hover {
   color: var(--sl-color-text);
 }
 
-.explico-keep-left:focus-visible {
+.explico-side-switch:focus-visible {
   outline: 3px solid var(--sl-color-accent);
   outline-offset: 2px;
 }
 
-.explico-keep-left-switch {
+.explico-side-switch-knob {
   position: relative;
   flex: none;
   width: 1.75em;
@@ -1463,7 +1609,7 @@ starlight-menu-button > button {
   transition: background-color 100ms ease;
 }
 
-.explico-keep-left-switch::after {
+.explico-side-switch-knob::after {
   content: '';
   position: absolute;
   top: 0.125em;
@@ -1475,33 +1621,33 @@ starlight-menu-button > button {
   transition: transform 100ms ease;
 }
 
-.explico-keep-left[aria-pressed='true'] .explico-keep-left-switch {
+.explico-side-switch[aria-pressed='true'] .explico-side-switch-knob {
   background: var(--sl-color-accent);
 }
 
-.explico-keep-left[aria-pressed='true'] .explico-keep-left-switch::after {
+.explico-side-switch[aria-pressed='true'] .explico-side-switch-knob::after {
   transform: translateX(0.75em);
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .explico-keep-left-switch,
-  .explico-keep-left-switch::after {
+  .explico-side-switch-knob,
+  .explico-side-switch-knob::after {
     transition: none;
   }
 }
 
 @media (forced-colors: active) {
-  .explico-keep-left-switch {
+  .explico-side-switch-knob {
     border: 1px solid ButtonText;
   }
 
-  .explico-keep-left[aria-pressed='true'] .explico-keep-left-switch {
+  .explico-side-switch[aria-pressed='true'] .explico-side-switch-knob {
     background: Highlight;
   }
 }
 
 @media print {
-  .explico-keep-left {
+  .explico-side-controls {
     display: none !important;
   }
 }
@@ -1556,14 +1702,6 @@ starlight-menu-button > button {
   overflow-wrap: anywhere;
 }
 
-.sl-markdown-content .citation-status {
-  padding-inline: 0.4em;
-  border: 1px solid var(--sl-color-gray-5);
-  border-radius: 999px;
-  font-size: var(--sl-text-xs);
-  text-transform: lowercase;
-}
-
 .sl-markdown-content .citation-backref {
   margin-inline-start: 0.15rem;
 }
@@ -1606,12 +1744,12 @@ starlight-menu-button > button {
 }
 
 /* Equation identity (D7): a keyed `$$…$$` is wrapped by the remark adapter in
-   `.keyed-equation` with an `id="eq-<key>"`, a `data-eq-number`, and a
-   `.keyed-equation__controls` pair — a focusable number link, and a "Copy
-   LaTeX" button. Prose refers to it with `[[eq:key]]` → `a.equation-ref`. The
-   deep-link highlight is a pure-CSS `:target` animation with a
-   reduced-motion fallback; `KeyedFloatEnhancer.astro` only re-triggers it on
-   a repeated activation and moves focus. */
+   `.keyed-equation` with an `id="eq-<key>"`, a `data-eq-number`, its number
+   (`.keyed-equation__controls`, a focusable number link) and a "Copy LaTeX"
+   button on its bottom border. Prose refers to it with `[[eq:key]]` →
+   `a.equation-ref`. The deep-link highlight is a pure-CSS `:target`
+   animation with a reduced-motion fallback; `KeyedFloatEnhancer.astro` only
+   re-triggers it on a repeated activation and moves focus. */
 .sl-markdown-content .keyed-equation {
   position: relative;
   scroll-margin-block-start: 5rem;
@@ -1646,23 +1784,32 @@ starlight-menu-button > button {
   transition: opacity 120ms ease-out;
 }
 
+/* Copy LaTeX, centred on the block's bottom border: the edge of its hover
+   highlight. `float-toolbar.ts` measures each equation and sets
+   `--eq-copy-inline-end`: under the number, or, in an equation too short
+   for the number's copy-link button between the two, slid left along the
+   border, clear of the number. It shows while the equation is hovered or
+   focused, and always on a touch screen. */
 .sl-markdown-content .keyed-equation__copy {
+  --eq-copy-size: 1.375rem;
+  position: absolute;
+  inset-block-end: calc(var(--eq-copy-size) / -2);
+  inset-inline-end: var(--eq-copy-inline-end, 1rem);
+  z-index: 2;
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 1.5rem;
-  height: 1.5rem;
+  width: var(--eq-copy-size);
+  height: var(--eq-copy-size);
   padding: 0;
   border: 1px solid var(--sl-color-gray-5);
   border-radius: 999px;
-  color: var(--sl-color-gray-1);
-  background: transparent;
+  color: var(--sl-color-gray-2);
+  background: var(--sl-color-bg);
+  box-shadow: 0 1px 3px rgb(0 0 0 / 0.12);
   font: inherit;
   cursor: pointer;
-  /* Quiet by default for the same reason as the number above — it fades in
-     alongside it, not the equation, so print (which drops it entirely, see
-     below) never has to reconcile the two. */
-  opacity: 0.45;
+  opacity: 0;
   transition:
     opacity 120ms ease-out,
     border-color 120ms ease-out,
@@ -1670,8 +1817,8 @@ starlight-menu-button > button {
 }
 
 .sl-markdown-content .keyed-equation__copy svg {
-  width: 0.85rem;
-  height: 0.85rem;
+  width: 0.75rem;
+  height: 0.75rem;
   fill: none;
   stroke: currentColor;
   stroke-width: 1.75;
@@ -1713,6 +1860,78 @@ starlight-menu-button > button {
   outline-offset: 2px;
 }
 
+/* The toolbar on a float's number (`float-toolbar.ts`): Pin and Dock just
+   above the number, Copy link just below it, none of them over it. The
+   script places each part against the number, inside the number's own
+   box; it shows only with a mouse, and never prints. */
+.float-toolbar {
+  display: contents;
+}
+
+.float-toolbar[hidden] {
+  display: none;
+}
+
+.float-toolbar__above,
+.float-toolbar__link {
+  position: absolute;
+  z-index: 4;
+  display: inline-flex;
+  gap: 0.25rem;
+}
+
+.float-toolbar__button,
+.float-toolbar__link {
+  align-items: center;
+  justify-content: center;
+  width: 1.375rem;
+  height: 1.375rem;
+  padding: 0;
+  border: 1px solid var(--sl-color-gray-5);
+  border-radius: 999px;
+  color: var(--sl-color-gray-2);
+  background: var(--sl-color-bg);
+  box-shadow: 0 1px 3px rgb(0 0 0 / 0.12);
+  font: inherit;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.float-toolbar__button {
+  display: inline-flex;
+}
+
+.float-toolbar__button:hover,
+.float-toolbar__button:focus-visible,
+.float-toolbar__link:hover,
+.float-toolbar__link:focus-visible {
+  border-color: var(--sl-color-accent);
+  color: var(--sl-color-text-accent);
+}
+
+.float-toolbar svg {
+  width: 0.75rem;
+  height: 0.75rem;
+}
+
+.float-toolbar__button svg {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.5;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.float-toolbar__link svg {
+  fill: currentColor;
+}
+
+@media print {
+  .float-toolbar {
+    display: none !important;
+  }
+}
+
 /* The click-to-copy gesture (`KeyedFloatEnhancer.astro`) works on any part of
    the box — including the reserved gutter between the equation and its
    number/button, not just the rendered `.katex-html` — that isn't a symbol
@@ -2128,6 +2347,8 @@ starlight-menu-button > button {
 }
 
 .sl-markdown-content .float-caption__number {
+  /* The room the chain icon used to keep before the short caption. */
+  margin-inline-end: 0.45em;
   font-weight: 600;
   font-variant-numeric: tabular-nums;
   color: var(--sl-color-text-accent);
@@ -2139,31 +2360,7 @@ starlight-menu-button > button {
   text-decoration: underline;
 }
 
-.sl-markdown-content .float-caption__anchor {
-  display: inline-flex;
-  width: 1.15em;
-  height: 1.15em;
-  margin-inline: 0.15em 0.3em;
-  vertical-align: -0.2em;
-  align-items: center;
-  justify-content: center;
-  color: var(--sl-color-gray-4);
-  text-decoration: none;
-  -webkit-user-select: none;
-  user-select: none;
-}
-
-.sl-markdown-content .float-caption__anchor svg {
-  width: 0.85em;
-  height: 0.85em;
-}
-
-.sl-markdown-content .float-caption__anchor:hover,
-.sl-markdown-content .float-caption__anchor:focus-visible {
-  color: var(--sl-color-text-accent);
-}
-
-.sl-markdown-content :is(.float-caption__number, .float-caption__anchor):focus-visible {
+.sl-markdown-content .float-caption__number:focus-visible {
   outline: 2px solid var(--sl-color-accent);
   outline-offset: 0.15rem;
 }
@@ -2651,12 +2848,14 @@ starlight-menu-button > button {
   opacity: 1;
 }
 
-/* A narrow screen shows no section number and, often, has no hover to reveal
-   the chain icon — yet the icon is the way to the section's link and, in its
-   "Link copied · § 1.1.2", its number (docs/plans/titles-and-containers.md
-   Q3). So it is always shown there, smaller and in the muted text colour.
-   The size variable also sets the room `anchor-links.css` reserves for it at
-   the end of the title. After the hover rules above, which it overrides. */
+/* A narrow screen shows no section number, so the chain icon is the way to
+   the section's link and, in its "Link copied · § 1.1.2", its number
+   (docs/plans/titles-and-containers.md Q3). There it is smaller and in the
+   muted text colour. The size variable also sets the room `anchor-links.css`
+   reserves for it at the end of the title. A touch screen has no hover to
+   reveal it, so there it is always shown; a narrow window with a mouse
+   reveals it on hover, as a wide one does, instead of showing it on every
+   heading. After the hover rules above, which it overrides. */
 @media screen and (width < 50em) {
   .sl-markdown-content .sl-heading-wrapper {
     --sl-anchor-icon-size: 0.7em;
@@ -2664,11 +2863,17 @@ starlight-menu-button > button {
 
   .sl-markdown-content .sl-heading-wrapper > .sl-anchor-link,
   .sl-markdown-content .sl-heading-wrapper.sl-section-titlebar > .sl-anchor-link {
-    opacity: 1;
     color: var(--sl-color-gray-3);
   }
 }
 
+@media screen and (width < 50em) and (hover: none) {
+  .sl-markdown-content .sl-heading-wrapper > .sl-anchor-link,
+  .sl-markdown-content .sl-heading-wrapper.sl-section-titlebar > .sl-anchor-link {
+    opacity: 1;
+  }
+}
+
 /* The chevron sits to the *left* of the title without shifting the title's
    own position: `markdown.css`'s default marker is inline, right before the
    text, pushed left slightly by a negative margin — meaning the title
@@ -3125,7 +3330,7 @@ starlight-menu-button > button {
   }
 }
 
-/* Browser-native lesson printing. The print controller opens real native
+/* Browser-native page printing. The print controller opens real native
    disclosures before the browser lays out pages; these rules own only the
    paper presentation and therefore also remain a useful no-JS fallback. */
 @media print {
@@ -3175,7 +3380,6 @@ starlight-menu-button > button {
   .keyed-table__pagination-links,
   .keyed-table__more-row,
   .sl-anchor-link,
-  .float-caption__anchor,
   .short-note__collapse,
   .assessment-actions,
   .assessment-chevron,
@@ -3186,6 +3390,18 @@ starlight-menu-button > button {
     display: none !important;
   }
 
+  /* Print is always light (above), so the splash hero prints its light image
+     whatever theme the reader is in; the dark one's pale strokes would vanish
+     on white paper. Starlight's own site logo does this with `print:hidden`
+     and `print:block`, but its hero does not. */
+  .hero > img.light\:sl-hidden {
+    display: none;
+  }
+
+  .hero > img.dark\:sl-hidden {
+    display: block;
+  }
+
   .main-frame,
   .main-pane,
   .content-panel,