explico 0.11.1 → 0.13.0

package/src/rules/catalog.ts

@@ -168,6 +168,7 @@ const GATE_MATH: Emitter = { module: 'src/reference/gate-math.ts', fn: 'resolveI
 const GLYPHS: Emitter = { module: 'src/reference/math-glyphs.mjs', fn: 'resolveMathGlyphs' };
 const REGISTRY: Emitter = { module: 'src/reference/registry.ts', fn: 'buildNotationRegistry' };
 const KEYED_FLOATS: Emitter = { module: 'src/reference/keyed-float-validate.ts', fn: 'validateKeyedFloats' };
+const INDICES: Emitter = { module: 'src/reference/gate-indices.ts', fn: 'gateIndices' };
 
 function consistency(fn: string): Emitter {
   return { module: 'src/reference/consistency.ts', fn };
@@ -203,6 +204,15 @@ function keyedFloatChecks(): RuleCheck[] {
       check(`${prefix}-duplicate-key`, 'error', false, emitter),
       check(`${prefix}-ref-resolves`, 'error', false, emitter),
     );
+    // A display block is one numbered equation: a second `\label` in it
+    // would name nothing.
+    if (prefix === 'eq') {
+      out.push(
+        check('eq-label-repeated', 'error', false, emitter),
+        // LaTeX's `\eqref{eq:key}` in prose, which MDX cannot parse.
+        check('eq-latex-ref', 'error', false, emitter),
+      );
+    }
     if (prefix === 'tab' || prefix === 'fig' || prefix === 'dia' || prefix === 'ex') {
       out.push(check(`${prefix}-key-unused`, 'info', false, emitter));
       // A prop that is gone: a name prop the caption pair (`caption` +
@@ -212,6 +222,20 @@ function keyedFloatChecks(): RuleCheck[] {
       // JSX float; a table never had one to remove.
       out.push(check(`${prefix}-removed-prop`, 'error', false, emitter));
     }
+    // A `short={…}` / `caption={…}` the manifest cannot read: a reference's
+    // card, a copied link and the float index name the float without it.
+    if (prefix !== 'eq' && prefix !== 'check') {
+      out.push(check(`${prefix}-unread-prop`, 'warning', false, emitter));
+    }
+    // A `<Table>` holding a second table, which every export would drop.
+    if (prefix === 'tab') {
+      out.push(
+        check('tab-several-tables', 'error', false, {
+          module: 'src/reference/tables-validate.ts',
+          fn: 'validateTables',
+        }),
+      );
+    }
   }
   // A worked-example set cannot do without its `id` (its anchor and
   // `[[ex-…]]`) or its `short` title (its heading after the "Example" badge).
@@ -221,13 +245,18 @@ function keyedFloatChecks(): RuleCheck[] {
       fn: 'validateExamples',
     }),
   );
-  // A section's key is its heading's anchor, which the slugger makes unique,
-  // so only the reference can go wrong.
+  // A section's key is its heading's anchor, which the slugger makes unique
+  // among headings; the reference can go wrong, and so can an anchor the
+  // engine already gives a float, a memo or the References section.
   out.push(
     check('sec-ref-resolves', 'error', true, {
       module: 'src/reference/sections-validate.ts',
       fn: 'validateSectionRefs',
     }),
+    check('heading-anchor-collision', 'error', true, {
+      module: 'src/reference/sections-validate.ts',
+      fn: 'validateHeadingAnchors',
+    }),
   );
   // A `<Fold>` is named by its `label`, or by the numbered floats it holds;
   // one with neither has an empty bar.
@@ -356,7 +385,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['prose', 'assessment', 'table'],
     doc: 'notation.md#n9',
     summary:
-      'Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity\'s unit out: "4 seconds", "2 meters per second squared", "30 degrees", "$x = 3$ meters" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own ("measured in meters") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption="…"`) and assessment choice labels render no math, so N9 does not apply there.',
+      'Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity\'s unit out: "4 seconds", "2 meters per second squared", "30 degrees", "$x = 3$ meters" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own ("measured in meters") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption="…"`) render no math, so N9 does not apply there; nor does it apply to an assessment choice label, which may still hold math (`$30^{\\circ}$`).',
     checks: [
       check(
         'prose-notation',
@@ -530,7 +559,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['notation'],
     doc: 'notation.md#n19',
     summary:
-      'Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, …) or `dimensionless: true`. A token outside the vocabulary is a warning.',
+      'Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, …) or `dimensionless: true`, except an index entry (`latex: "{}_0"`, N23), which takes neither. A token outside the vocabulary is a warning.',
     checks: [
       check('notation-units', 'warning', false, consistency('checkNotationUnits')),
       check('units-vocab', 'warning', false, consistency('checkNotationUnits')),
@@ -557,7 +586,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['notation'],
     doc: 'notation.md#n21',
     summary:
-      'A gloss `label` names the symbol in a few words (“launch angle”); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.',
+      'A gloss `name` names the symbol in a few words (“launch angle”); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.',
     checks: [check('gloss-name-shape', 'warning', false, consistency('checkGlossNameShape'))],
   },
   {
@@ -572,6 +601,7 @@ const RULES: readonly RuleEntry[] = [
       'A decoration (`\\hat`, `\\bar`, `\\overline`, `\'`, `^*`, `^\\dagger`, …) is on the course’s `allow` list (shipped empty), explained by an operator entry (`latex: \\hat{}`), or the decorated form has its own entry (`latex: \\hat{\\beta}`), which wins for that form. A page may suspend a decoration in `notation.suspend`, with a `reason`; every decorated form of it there then needs its own entry.',
     checks: [
       check('accent-explained', 'warning', false, consistency('checkAccentExplained')),
+      check('accent-swallowed', 'warning', false, consistency('checkAccentExplained')),
       check('suspended-operator-unresolved', 'error', true, GATE_MATH),
       check('operator-suspension-reason', 'warning', false, consistency('checkOperatorSuspension')),
       check('operator-suspended', 'info', false, consistency('checkOperatorSuspension')),
@@ -579,6 +609,25 @@ const RULES: readonly RuleEntry[] = [
     ],
     settings: baselineEdits('Decorations'),
   },
+  {
+    kind: 'rule',
+    id: 'N23',
+    short: 'An index is part of the symbol: whole form, family or index entry',
+    title:
+      'An index is part of the symbol: a subscript is explained by the indexed symbol’s entry, a family entry, or an index entry.',
+    elements: ['math', 'notation'],
+    doc: 'notation.md#n23',
+    summary:
+      'A subscript on a symbol is explained by the indexed symbol’s own entry (`latex: v_0`), a family entry whose index runs (`latex: x_k` explains `x_1`), or an index entry for the subscript (`latex: "{}_0"`, which composes a derived card); a card on the base alone does not explain it, and arithmetic on an index letter with its own card does (`X_{t-1}`). A running index — a lowercase letter not marked `fixedIndex` — states its set, as `range` on its card or after a `\\quad` on the first display line that uses it. Never wrap an indexed symbol in `\\explain` with a key whose `latex` has no index.',
+    checks: [
+      check('index-explained', 'error', true, INDICES),
+      check('index-swallowed', 'error', true, INDICES),
+      check('index-range', 'error', true, INDICES),
+      check('derived-key-taken', 'error', true, INDICES),
+    ],
+    unchecked:
+      'whether a `\\quad` clause states the set correctly; whether a lowercase index is really running; lab math whose glyph table is a copy of the one `labMathScope` returned.',
+  },
 
   // ---- V — visualizations -----------------------------------------------------
   {
@@ -613,8 +662,19 @@ const RULES: readonly RuleEntry[] = [
     elements: ['plot'],
     doc: 'visualizations.md#v3',
     summary:
-      'An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath`, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own.',
-    checks: [],
+      'An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath` (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause) and never KaTeX directly, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own. Its default picture is drawn at build time too and handed to the island as children, so the built page has it.',
+    checks: [
+      check('lab-katex-direct', 'error', false, {
+        module: 'src/reference/lab-katex-validate.ts',
+        fn: 'validateLabKatexImports',
+      }),
+      check('lab-picture-undrawn', 'warning', false, {
+        module: 'src/reference/figure-pictures.ts',
+        fn: 'undrawnFigurePictures',
+      }),
+    ],
+    unchecked:
+      'that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` — the build’s rendered check (`figure-symbols.ts`) covers the page it renders.',
   },
   {
     kind: 'rule',
@@ -666,6 +726,57 @@ const RULES: readonly RuleEntry[] = [
       },
     ],
   },
+  {
+    kind: 'rule',
+    id: 'V7',
+    short: 'A figure’s picture fits on one screen',
+    title: 'A figure’s picture takes at most `maxPercent` of the screen height.',
+    elements: ['plot'],
+    doc: 'visualizations.md#v7',
+    summary:
+      'The default slot of a `<Figure>` — plot, key and tables — stays within `maxPercent` of the viewport height, so the reader sees the picture and its caption line together. A square or tall plot gets a fixed width instead of the full column.',
+    checks: [
+      check('figure-too-tall', 'warning', false, {
+        module: 'src/reference/figure-fit.ts',
+        fn: 'checkFigureFit',
+      }),
+    ],
+    unchecked:
+      'any page or viewport the course’s Playwright suite does not open — the check runs in the browser, not in the build.',
+    settings: [
+      {
+        key: 'maxPercent',
+        title: 'Largest picture height (% of screen)',
+        description: 'How much of the viewport height a figure’s picture may take.',
+        schema: { type: 'integer', minimum: 10, default: 80 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'V8',
+    short: 'A diagram fits the lesson column',
+    title: 'A diagram is no wider than the lesson column.',
+    elements: ['diagram'],
+    doc: 'visualizations.md#v8',
+    summary:
+      'A `<Diagram>` lays out no wider than `columnWidth`, the lesson column at a 1366px-wide window, so the reader sees the whole graph without scrolling it. Narrow it with `direction="TB"`, a shorter label or a node `width` (its label wraps inside it); `warnAboveWidth={false}` marks a diagram meant to scroll.',
+    checks: [
+      check('dia-too-wide', 'warning', false, {
+        module: 'src/reference/diagram-fit.ts',
+        fn: 'oversizedDiagrams',
+      }),
+    ],
+    settings: [
+      {
+        key: 'columnWidth',
+        title: 'Column width (px)',
+        description:
+          'The widest a diagram may lay out: the lesson column at the window width the course is read at most (707px at 1366px).',
+        schema: { type: 'integer', minimum: 200, default: 707 },
+      },
+    ],
+  },
 
   // ---- C — versioning ---------------------------------------------------------
   {
@@ -799,7 +910,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['table'],
     doc: 'structure-rules.md#s3',
     summary:
-      'Wrap every pipe table or `<table>` in `<Table id="…" caption="…">` so it gets a number and `[[tab-…]]` can reach it.',
+      'Wrap every pipe table or `<table>` in `<Table id="…" caption="…">` so it gets a number and `[[tab-…]]` can reach it; a table in a worked example stays plain.',
     checks: [
       check('raw-table-markdown', 'warning', false, {
         module: 'src/reference/raw-floats-validate.ts',
@@ -831,24 +942,6 @@ const RULES: readonly RuleEntry[] = [
       }),
     ],
   },
-  {
-    kind: 'rule',
-    id: 'S5',
-    short: 'A sign / perspective convention is declared once and cited elsewhere',
-    title: 'A sign or perspective convention is declared once and cited everywhere else.',
-    elements: ['prose'],
-    doc: 'structure-rules.md#s5',
-    summary:
-      'Prose that states a sign / cash-flow-perspective convention resolves it to the single declaration — the `conventions.signConventionKey` notation entry (`[[key]]`) or the `conventions.cashFlowPerspectiveCompetency` competency — rather than restating it.',
-    checks: [
-      check(
-        'convention-single-definition',
-        'warning',
-        false,
-        consistency('checkConventionSingleDefinition'),
-      ),
-    ],
-  },
   {
     kind: 'rule',
     id: 'S6',
@@ -864,6 +957,12 @@ const RULES: readonly RuleEntry[] = [
         module: 'src/reference/gate-heading-structure.ts',
         fn: 'gateHeadingStructure',
       }),
+      // A knowledge check or a worked-example set, which draws an `<h2>`,
+      // inside a memo or a short note.
+      check('heading-nested', 'error', true, {
+        module: 'src/reference/gate-heading-structure.ts',
+        fn: 'gateHeadingStructure',
+      }),
     ],
   },
   {
@@ -906,6 +1005,33 @@ const RULES: readonly RuleEntry[] = [
       'Give each figure, table and diagram a `short` caption that names it: it opens the caption line in bold, and names the float in "Hidden here", a copied link and the "Figures and tables" page. The long `caption` goes on from that name to say what the float shows — its subject, its marks and symbols, the case shown — and at most the one thing to notice. The argument drawn from a figure is lesson text after it, and a lab’s instructions are the first line of its `tools`.',
     checks: [],
   },
+  {
+    kind: 'rule',
+    id: 'S10',
+    short: 'A page that is not a chapter explains its symbols but numbers nothing: it links a chapter’s float instead',
+    title:
+      'A page that is not a chapter — the landing page, a part’s overview page — explains its symbols like a chapter, but carries no numbered float: it links the chapter’s float instead.',
+    elements: ['part-page', 'plot', 'table', 'diagram', 'equation', 'notation'],
+    doc: 'structure-rules.md#s10',
+    summary:
+      'On `content/docs/index.mdx`, a `content/docs/<part>/index.mdx`, or any page outside a part: `[[key]]`, `\\explain`, math, citations and `[[chapter#tab-key]]` links work and open cards, and the math and prose gates apply. No `<Table>`, `<Figure>`, `<Diagram>`, `<CompactExamples>`, `<AssessmentSet>`, lab, `\\label{eq:…}` or `notation.local`/`notation.suspend`; no `$…$` or `[[…]]` in `hero.title`, `hero.tagline` or a `<PartOverview chain>` step.',
+    checks: [
+      check('non-chapter-float', 'error', true, {
+        module: 'src/reference/gate-non-chapter-pages.ts',
+        fn: 'gateNonChapterPages',
+      }),
+      check('non-chapter-local-notation', 'error', false, {
+        module: 'src/reference/gate-non-chapter-pages.ts',
+        fn: 'gateNonChapterPages',
+      }),
+      check('non-chapter-plain-text', 'error', false, {
+        module: 'src/reference/gate-non-chapter-pages.ts',
+        fn: 'gateNonChapterPages',
+      }),
+    ],
+    locked:
+      'a float needs a chapter number, and such a page has none — turning the rule off would not render one.',
+  },
 
   // ---- P — prose --------------------------------------------------------------
   {
@@ -1077,6 +1203,13 @@ const RETIRED: readonly RetiredRule[] = [
     into: 'C3',
     why: 'The release procedure and the invariant it keeps are one rule, and `knowledge-changelog-missing` (owned by C3) was already the check that fired on a half-finished release.',
   },
+  {
+    id: 'S5',
+    title: 'A sign or perspective convention is declared once and cited everywhere else.',
+    date: '2026-10-07',
+    into: 'N4',
+    why: 'Its check knew one finance course’s phrasing and one key per course, and never fired in any course; the `conventions` setting it read is gone. A convention is a definition, so it is now N4’s: defined once on its notation entry, whose `meaning` names the other choice and whose body says how to convert.',
+  },
 ];
 
 const INVARIANTS: readonly InvariantEntry[] = [
@@ -1087,7 +1220,7 @@ const INVARIANTS: readonly InvariantEntry[] = [
     elements: ['notation', 'math'],
     doc: 'components.md#reference-systems',
     summary:
-      'A `[[key]]` or `\\explain{key}{…}` names an existing entry; a key is kebab-case; a shared entry is defined once; formula references never form a cycle.',
+      'A `[[key]]` or `\\explain{key}{…}` names an existing entry; a key is kebab-case; a shared entry is defined once; references in meanings and bodies never form a cycle (formulas may name each other).',
     checks: [
       check('undefined-reference', 'error', false, REGISTRY),
       check('invalid-key', 'error', false, REGISTRY, GLYPHS),
@@ -1103,6 +1236,10 @@ const INVARIANTS: readonly InvariantEntry[] = [
       }),
       check('malformed-explicit-binding', 'error', true, GLYPHS),
       check('unused-definition', 'info', false, REGISTRY),
+      // A page-local entry under a shared key: two meanings for one key.
+      check('local-shadows-shared', 'warning', false, REGISTRY),
+      // A `[[` that never closes, before the render fails on it.
+      check('malformed-reference', 'error', false, REGISTRY),
     ],
   },
   {
@@ -1123,6 +1260,11 @@ const INVARIANTS: readonly InvariantEntry[] = [
       check('ambiguous-base-fallback', 'error', true, GLYPHS),
       check('ambiguous-canonical-notation', 'error', false, GLYPHS),
       check('math-compile-error', 'error', true, GATE_MATH),
+      // `$5 to $6`: money remark-math reads as one math span.
+      check('currency-dollar', 'error', true, {
+        module: 'src/reference/gate-math.ts',
+        fn: 'gateContentMath',
+      }),
     ],
   },
   {
@@ -1142,7 +1284,7 @@ const INVARIANTS: readonly InvariantEntry[] = [
     elements: ['changelog'],
     doc: 'README.md#amending',
     summary:
-      'A `rules.<ID>` block names a live rule; a deprecated top-level key (`operators`, `romanLabels`, `abbreviations`) still works but warns until it is moved under `rules`.',
+      'A `rules.<ID>` block names a live rule; a deprecated top-level key (`operators`, `romanLabels`, `abbreviations`) still works but warns until it is moved under `rules`; `conventions` is ignored and warns until it is deleted.',
     checks: [
       check('config-deprecated-key', 'warning', false, {
         module: 'src/rules/settings.ts',
@@ -1189,8 +1331,10 @@ const INVARIANTS: readonly InvariantEntry[] = [
           'track-order',
           'assessment-coverage',
           'invalid-assessment',
-          'review-state',
+          'missing-assumptions',
           'teaches-support',
+          // `[text [@id]](url)`: a citation the page prints as typed.
+          'citation-in-link',
         ] as const
       ).map((code) =>
         check(code, 'error', false, {
@@ -1204,7 +1348,6 @@ const INVARIANTS: readonly InvariantEntry[] = [
           'alignment-unknown-lesson',
           'alignment-introduction',
           'alignment-unavailable',
-          'alignment-review-state',
         ] as const
       ).map((code) =>
         check(code, 'error', false, {
@@ -1212,7 +1355,74 @@ const INVARIANTS: readonly InvariantEntry[] = [
           fn: 'validateNotationAlignment',
         }),
       ),
-    ] as [RuleCheck, ...RuleCheck[]],
+      // A course's parts and the lessons in them (`compileManifest`): a
+      // lesson in a directory no part lists, and a part with nothing in it yet.
+      check('lesson-outside-parts', 'error', false, {
+        module: 'src/compiler/manifest.ts',
+        fn: 'compileManifest',
+      }),
+      check('part-empty', 'warning', false, {
+        module: 'src/compiler/manifest.ts',
+        fn: 'compileManifest',
+      }),
+    ] as unknown as [RuleCheck, ...RuleCheck[]],
+  },
+  {
+    kind: 'invariant',
+    id: 'content-schema',
+    title: 'Every content file satisfies its collection’s schema.',
+    elements: ['notation', 'assessment', 'source', 'changelog'],
+    doc: 'structure.md#content-schemas',
+    summary:
+      'A page’s explico fields, a notation entry, an abbreviation, a competency, an assessment, a source and a track match the schema `astro build` loads them with (`compiler/content-schemas.ts`); `validate:content` reports the field and its line.',
+    checks: [
+      check('content-schema', 'error', false, {
+        module: 'src/compiler/content-schema.ts',
+        fn: 'validateContentSchemas',
+      }),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'retired-keys',
+    title: 'No content file sets a key the engine has retired or cannot honour.',
+    elements: ['changelog'],
+    doc: 'structure.md#retired-keys',
+    summary:
+      'A frontmatter or JSON key explico no longer reads (`editorialStatus`) fails the build at every file that still sets it; delete the line. A lesson’s `draft: true` fails it too (the sidebar would name a page the build drops), and its `sidebar.order` warns (chapters follow the tracks).',
+    checks: [
+      check('retired-key', 'error', false, {
+        module: 'src/reference/gate-retired-keys.ts',
+        fn: 'findRetiredKeys',
+      }),
+      check('unsupported-key', 'error', false, {
+        module: 'src/reference/gate-retired-keys.ts',
+        fn: 'findUnsupportedKeys',
+      }),
+      check('ignored-key', 'warning', false, {
+        module: 'src/reference/gate-retired-keys.ts',
+        fn: 'findUnsupportedKeys',
+      }),
+    ],
+  },
+  {
+    kind: 'invariant',
+    id: 'prop-text',
+    title: 'A component’s quoted prop holds plain text, and prose holds no `{…}` expression.',
+    elements: ['math', 'plot', 'diagram', 'table'],
+    doc: 'components.md#props-are-plain-text',
+    summary:
+      'A quoted prop (`caption="…"`, `short="…"`, `title="…"`, `label="…"`) reaches the page as plain text: no KaTeX, reference or citation runs in it. `$…$`, `[[…]]` or `[@…]` in one fails the build, since it would print as typed; write the symbol in Unicode or words, and reference or cite from the prose next to the component. MDX reads `{…}` in prose as JavaScript (`{a}` fails the build, "a is not defined"): write `\\{a\\}`, or `$\\{a\\}$` for a set.',
+    checks: [
+      check('markup-in-prop', 'error', false, {
+        module: 'src/reference/gate-prop-text.ts',
+        fn: 'findMarkupInProps',
+      }),
+      check('mdx-expression', 'error', false, {
+        module: 'src/reference/gate-mdx-expression.ts',
+        fn: 'gateMdxExpressions',
+      }),
+    ],
   },
 ];
 

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>();