explico 0.1.0 → 0.2.0

package/dist/reference/rehype-heading-anchors.mjs

@@ -0,0 +1,144 @@
+/**
+ * Deep-linkable content headings (Step F3).
+ *
+ * The lesson pipeline uses a custom Markdown `processor` (see `astro.config.mjs`),
+ * which bypasses Starlight's own heading-link rehype pass. This plugin restores
+ * it with the *same* markup Starlight emits, so its bundled `anchor-links.css`
+ * (shipped globally because `markdown.headingLinks` defaults on) styles it for
+ * free — including the hover/focus reveal of an otherwise invisible anchor:
+ *
+ *   <div class="sl-heading-wrapper level-h2">
+ *     <h2 id="slug">Heading</h2>
+ *     <a class="sl-anchor-link" href="#slug"> <icon> <sr-only label> </a>
+ *   </div>
+ *
+ * The `:target` flash, sticky-header scroll offset, and the JS niceties
+ * (re-trigger on repeat activation, smooth scroll, `history.pushState`, brief
+ * section highlight) live in `global.css` + `HeadingAnchorEnhancer.astro`, the
+ * same split the keyed-equation feature uses.
+ *
+ * `rehypeHeadingIds` from `@astrojs/markdown-remark` normally runs *after* the
+ * user rehype plugins, so heading `id`s do not exist yet when this runs. It is
+ * idempotent (only assigns a missing `id`, and rebuilds `file.data.astro.headings`
+ * from an unchanged document order), so this plugin runs it first and Astro's
+ * later pass becomes a no-op for these headings.
+ */
+
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+
+const HEADING_TAG = /^h([1-6])$/;
+
+// Starlight's `link-alt` icon (`components-internals/Icons.ts`), the same glyph
+// its own `rehypeAutolinkHeadings` uses.
+const LINK_ICON_PATH =
+  'm12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42';
+
+function headingText(node) {
+  let text = '';
+  const walk = (current) => {
+    if (!current || typeof current !== 'object') return;
+    if (current.type === 'text' || current.type === 'raw') {
+      text += String(current.value ?? '');
+      return;
+    }
+    if (Array.isArray(current.children)) current.children.forEach(walk);
+  };
+  walk(node);
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function isHeadingWrapper(node) {
+  const className = node?.properties?.className;
+  return (
+    node?.type === 'element' &&
+    Array.isArray(className) &&
+    className.includes('sl-heading-wrapper')
+  );
+}
+
+function anchorLink(id, label) {
+  return {
+    type: 'element',
+    tagName: 'a',
+    properties: { className: ['sl-anchor-link'], href: `#${id}` },
+    children: [
+      {
+        type: 'element',
+        tagName: 'span',
+        properties: { ariaHidden: 'true', className: ['sl-anchor-icon'] },
+        children: [
+          {
+            type: 'element',
+            tagName: 'svg',
+            properties: {
+              width: 16,
+              height: 16,
+              viewBox: '0 0 24 24',
+              fill: 'currentColor',
+            },
+            children: [
+              {
+                type: 'element',
+                tagName: 'path',
+                properties: { d: LINK_ICON_PATH },
+                children: [],
+              },
+            ],
+          },
+        ],
+      },
+      {
+        type: 'element',
+        tagName: 'span',
+        properties: { className: ['sr-only'], 'data-pagefind-ignore': 'true' },
+        children: [{ type: 'text', value: label }],
+      },
+    ],
+  };
+}
+
+export default function rehypeHeadingAnchors() {
+  const assignHeadingIds = rehypeHeadingIds();
+
+  return function transform(tree, file) {
+    assignHeadingIds(tree, file);
+
+    const walk = (node) => {
+      if (!node || typeof node !== 'object' || !Array.isArray(node.children)) {
+        return;
+      }
+      if (isHeadingWrapper(node)) return; // already processed
+
+      for (let index = 0; index < node.children.length; index++) {
+        const child = node.children[index];
+        const tag =
+          child?.type === 'element' && typeof child.tagName === 'string'
+            ? HEADING_TAG.exec(child.tagName)
+            : null;
+
+        if (
+          tag &&
+          tag[1] !== '1' &&
+          typeof child.properties?.id === 'string' &&
+          child.properties.id.length > 0
+        ) {
+          const id = child.properties.id;
+          const label = `Section titled “${headingText(child)}”`;
+          node.children[index] = {
+            type: 'element',
+            tagName: 'div',
+            properties: {
+              className: ['sl-heading-wrapper', `level-${child.tagName}`],
+            },
+            children: [child, anchorLink(id, label)],
+          };
+          continue; // the heading is a leaf for our purposes
+        }
+
+        walk(child);
+      }
+    };
+
+    walk(tree);
+  };
+}

package/dist/reference/remark-citation.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @param {{ sources?: Map<string, object> | readonly object[] | (() => Map<string, object> | readonly object[]) }} [options]
+ */
+export default function remarkCitation(options?: {
+    sources?: Map<string, object> | readonly object[] | (() => Map<string, object> | readonly object[]);
+}): (tree: any, file: any) => void;

package/dist/reference/remark-notation.d.mts

@@ -0,0 +1,49 @@
+/**
+ * @param {{
+ *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
+ *   resolve?: (key: string, context: object) => object | undefined,
+ *   unknown?: 'error' | 'warn' | 'ignore',
+ *   base?: string,
+ *   equations?: Record<string, Record<string, string>>,
+ * }} [options]
+ */
+export default function remarkNotation(options?: {
+    definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>);
+    resolve?: (key: string, context: object) => object | undefined;
+    unknown?: "error" | "warn" | "ignore";
+    base?: string;
+    equations?: Record<string, Record<string, string>>;
+}): (tree: any, file: any) => void;
+/**
+ * Remark adapter for semantic notation references.
+ *
+ * Author syntax:
+ *   - Prose introduces a meaning: `[[rates.discount-factor]]`
+ *   - Later math uses ordinary LaTeX: `D(0,t)`
+ *   - `\\explain{rates.discount-factor}{D(0,t)}` remains available inside math
+ *     when lexical scope cannot select one meaning unambiguously.
+ *
+ * Prose references become ordinary links. Lesson math is resolved against the
+ * page glyph table — `notation.local` plus the shared entries the page names
+ * with `[[key]]` (or `\\explain{key}{…}`) — and the base library; the
+ * adapter then injects the narrowly trusted `\\explain` marker before
+ * build-time KaTeX rendering. `notation.uses` is retired: the use is the
+ * declaration (D1 decision, 2026-09-02).
+ *
+ * Definitions can be supplied as a Map, an array, an object keyed by the
+ * semantic key, or a loader returning one of those forms. Loaders are
+ * evaluated for every document transform so a long-running development
+ * server can discover definitions created after startup. A resolver can
+ * provide page-local lexical scoping:
+ *
+ *   remarkNotation({
+ *     definitions: sharedDefinitions,
+ *     resolve(key, { file, kind, localDefinitions, sharedDefinitions }) {
+ *       return localDefinitions.get(key) ?? sharedDefinitions.get(key);
+ *     },
+ *   })
+ *
+ * A definition may be either its data object or an Astro collection entry
+ * with the data object under `.data`.
+ */
+export const NOTATION_KEY_PATTERN: RegExp;

package/dist/reference/remark-notation.mjs

@@ -36,7 +36,9 @@ export const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 import { GlyphResolutionError, resolveMathGlyphs } from './math-glyphs.mjs';
 import {
   EQ_LABEL_PATTERN,
+  collectDisplayEquations,
   collectEquationLabels,
+  equationAnchorId,
   parseEquationRef,
   stripEquationLabels,
 } from './equations.mjs';
@@ -307,28 +309,31 @@ function defaultHref(definition, key, base = '') {
 }
 
 /**
- * Wrap a keyed `$$…$$` `math` node so the container survives `rehype-katex`
- * (which splices the inner `math-display` element out). The visible number is
- * a focusable `<a>` sibling — never authored, never inside KaTeX — so it
- * survives print and screen readers name it "Equation 2.4".
+ * Wrap a display `$$…$$` `math` node so the container survives `rehype-katex`
+ * (which splices the inner `math-display` element out). Every display equation
+ * in a lesson is numbered; a keyed one anchors at `#eq-<key>`, an unkeyed one
+ * at its positional `#eq-<section>-<index>`. The visible number is a focusable
+ * `<a>` sibling — never authored, never inside KaTeX — so it survives print and
+ * screen readers name it "Equation 2.4".
  */
-function keyedEquationNode(mathNode, key, number) {
+function equationNode(mathNode, { key, number }) {
+  const id = equationAnchorId({ key, number });
+  const hProperties = {
+    id,
+    className: ['keyed-equation'],
+    'data-eq-number': number,
+  };
+  if (key) hProperties['data-eq-key'] = key;
+  else hProperties['data-eq-auto'] = '';
+
   return {
     type: 'paragraph',
-    data: {
-      hName: 'div',
-      hProperties: {
-        id: `eq-${key}`,
-        className: ['keyed-equation'],
-        'data-eq-key': key,
-        'data-eq-number': number,
-      },
-    },
+    data: { hName: 'div', hProperties },
     children: [
       mathNode,
       {
         type: 'link',
-        url: `#eq-${key}`,
+        url: `#${id}`,
         children: [{ type: 'text', value: `(${number})` }],
         data: {
           hProperties: {
@@ -598,6 +603,14 @@ export default function remarkNotation(options = {}) {
       crossPage: options.equations ?? {},
     };
 
+    // Number and anchor every display equation on a lesson page, keyed or
+    // not (F3). Non-lesson pages (notation registry, stray docs) keep the
+    // keyed-only behaviour so their body math is left untouched.
+    const displayEquations = lessonId ? collectDisplayEquations(tree) : [];
+    const equationByNode = new Map(
+      displayEquations.map((equation) => [equation.node, equation]),
+    );
+
     const resolve = (key, kind, node) => {
       const context = {
         file,
@@ -647,7 +660,6 @@ export default function remarkNotation(options = {}) {
               node,
             );
           }
-          node.__eqKey = labelMatch[1];
           value = stripEquationLabels(value);
           replaceMathSource(node, value);
         }
@@ -725,14 +737,8 @@ export default function remarkNotation(options = {}) {
           continue;
         }
         visit(child, false);
-        if (child && child.__eqKey) {
-          const key = child.__eqKey;
-          delete child.__eqKey;
-          node.children[index] = keyedEquationNode(
-            child,
-            key,
-            pageLabels.get(key),
-          );
+        if (child && child.type === 'math' && equationByNode.has(child)) {
+          node.children[index] = equationNode(child, equationByNode.get(child));
         }
       }
     };

package/dist/reference/types.d.ts

@@ -15,6 +15,19 @@ type NotationAlignment = {
     readonly rationale: string;
 };
 type NotationReferenceKind = 'prose' | 'math' | 'definition';
+/**
+ * A gloss resolved by the loader (D15). Declared on a card, keyed
+ * `<card key>.<slug(name)>`, and deliberately absent from the registry: a
+ * gloss is never a definition record, never a reference target, and never a
+ * curriculum node. See `reference/gloss.ts`.
+ */
+interface NotationGlossEntry {
+    readonly key: string;
+    readonly notation: string;
+    readonly label: string;
+    readonly units?: string;
+    readonly ownerKey: string;
+}
 interface NotationReferenceInput {
     readonly key: string;
     readonly kind: NotationReferenceKind;
@@ -37,6 +50,8 @@ interface SharedNotationDefinitionInput {
     readonly body: string;
     /** References harvested from the Markdown body. */
     readonly references: readonly NotationReferenceInput[];
+    /** Symbols this entry's `formula` names but does not make cards of. */
+    readonly glosses: readonly NotationGlossEntry[];
     readonly source: SourceSpan;
 }
 interface LocalNotationDefinitionInput {
@@ -51,6 +66,8 @@ interface LocalNotationDefinitionInput {
     readonly alignment: NotationAlignment;
     /** References harvested from summary content. */
     readonly references: readonly NotationReferenceInput[];
+    /** Symbols this entry's `formula` names but does not make cards of. */
+    readonly glosses: readonly NotationGlossEntry[];
     readonly source: SourceSpan;
 }
 interface NotationLessonInput {
@@ -67,7 +84,7 @@ interface NotationRegistryInput {
     readonly sharedDefinitions: readonly SharedNotationDefinitionInput[];
     readonly lessons: readonly NotationLessonInput[];
 }
-type NotationDiagnosticCode = 'invalid-key' | 'duplicate-page' | 'duplicate-definition' | 'conflicting-definition' | 'undefined-reference' | 'reference-cycle' | 'unused-definition' | 'alignment-unknown-competency' | 'alignment-unknown-lesson' | 'alignment-introduction' | 'alignment-unavailable' | 'alignment-review-state';
+type NotationDiagnosticCode = 'invalid-key' | 'duplicate-page' | 'duplicate-definition' | 'conflicting-definition' | 'undefined-reference' | 'reference-cycle' | 'unused-definition' | 'alignment-unknown-competency' | 'alignment-unknown-lesson' | 'alignment-introduction' | 'alignment-unavailable' | 'alignment-review-state' | 'gloss-collides-with-card';
 type DiagnosticSeverity = 'error' | 'warning';
 interface NotationDiagnostic {
     readonly code: NotationDiagnosticCode;
@@ -95,6 +112,12 @@ interface ResolvedNotationReference {
 interface NotationDefinitionRecordBase {
     readonly id: string;
     readonly key: string;
+    /**
+     * Symbols this entry's `formula` names but does not make cards of (D15).
+     * Carried on the record so the manifest can build the entry-scoped formula
+     * table; deliberately **not** a definition, a reference target, or an edge.
+     */
+    readonly glosses: readonly NotationGlossEntry[];
     readonly scope: NotationDefinitionScope;
     readonly notation: string;
     readonly label: string;
@@ -148,4 +171,4 @@ interface NotationRegistry {
     readonly diagnostics: readonly NotationDiagnostic[];
 }
 
-export type { DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };
+export type { DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationGlossEntry, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };

package/dist/session/user-context.js

@@ -1,5 +1,5 @@
 import { createContext, useContext } from "react";
-import { anonymousUser } from "./user";
+import { anonymousUser } from "./user.js";
 const SessionUserContext = createContext(anonymousUser);
 function useSessionUser() {
   return useContext(SessionUserContext);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",
@@ -48,6 +48,6 @@
     "typescript": "6.0.2"
   },
   "scripts": {
-    "build": "tsup && node scripts/copy-assets.mjs"
+    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json"
   }
 }

package/src/compiler/collections.ts

@@ -32,10 +32,12 @@ import type {
   NotationRegistryInput,
   SharedNotationDefinitionInput,
   SourceSpan,
+  NotationGlossEntry,
 } from '../reference/types';
 import { isSubstantiveMeaning } from '../reference/prose';
 import { parseEquationRef } from '../reference/equations.mjs';
 import { resolveLabel } from '../reference/label';
+import { resolveGlosses } from '../reference/gloss';
 import {
   deriveRequires,
   deriveSources,
@@ -322,6 +324,42 @@ export async function loadCurriculumCatalog(): Promise<CurriculumCatalog> {
 
 // --- notation registry input -------------------------------------------
 
+/**
+ * A card's authored `glosses:` list (D15). Keys are derived from the names, so
+ * a gloss is entry-scoped and promoting one to a card needs no reference
+ * rewrite anywhere in the corpus — see `reference/gloss.ts`.
+ */
+function glossEntries(
+  raw: unknown,
+  ownerKey: string,
+  at: string,
+): NotationGlossEntry[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) throw new Error(`${at} must be an array`);
+
+  const authored = raw.map((value, index) => {
+    const data = record(value, `${at}[${index}]`);
+    const units = optionalString(data.units, `${at}[${index}].units`);
+    return {
+      latex: string(data.latex, `${at}[${index}].latex`),
+      name: string(data.name, `${at}[${index}].name`),
+      ...(units === undefined ? {} : { units }),
+    };
+  });
+
+  const glosses = resolveGlosses(ownerKey, authored);
+  const seen = new Set<string>();
+  for (const gloss of glosses) {
+    if (seen.has(gloss.key)) {
+      throw new Error(
+        `${at} declares two glosses named ${JSON.stringify(gloss.label)}`,
+      );
+    }
+    seen.add(gloss.key);
+  }
+  return glosses;
+}
+
 function localDefinition(
   raw: unknown,
   file: string,
@@ -350,6 +388,7 @@ function localDefinition(
         ? { kind: 'general', rationale: 'Lesson-local symbol.' }
         : alignment(data.alignment, `${at}.alignment`),
     references: extractNotationReferences(definitionText, file, 'definition'),
+    glosses: glossEntries(data.glosses, key, `${at}.glosses`),
     source: { file },
     ...(formula === undefined ? {} : { formula }),
     ...(units === undefined ? {} : { units }),
@@ -382,6 +421,7 @@ function sharedNotationEntries(): SharedNotationDefinitionInput[] {
       aiAssisted: boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
       references: extractNotationReferences(body, file, undefined),
+      glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
       ...(formula === undefined ? {} : { formula }),
       ...(units === undefined ? {} : { units }),

package/src/compiler/manifest.ts

@@ -57,7 +57,10 @@ import {
 } from '../reference/gate-math';
 import { loadLintIgnore } from '../reference/lint-ignore';
 import { buildNotationRegistry } from '../reference/registry';
+import { formulaGlyphScope } from '../reference/gloss';
+import type { GlyphScopeEntry } from '../reference/gloss';
 import { resolveReferenceId } from '../reference/references';
+import type { NotationGlossEntry } from '../reference/types';
 import type {
   EditorialStatus,
   NotationBacklink,
@@ -137,6 +140,14 @@ export interface ManifestLessonNotation {
   readonly seeAlso: readonly string[];
   readonly units?: string;
   readonly formula?: string;
+  /** Symbols the formula names that have no card of their own (D15). */
+  readonly glosses: readonly NotationGlossEntry[];
+  /**
+   * Entry-scoped glyph table for `formula` — the entry, its glosses, and any
+   * card the formula names. Precomputed here because the whole card set lives
+   * in the compiler, not in the page component.
+   */
+  readonly formulaScope: readonly GlyphScopeEntry[];
 }
 
 export interface ManifestLesson {
@@ -306,6 +317,7 @@ function lessonNotationBundle(
   bundle: NotationPageBundle | undefined,
   definitionsById: ReadonlyMap<string, NotationDefinitionRecord>,
   resolution: readonly ManifestNotationResolution[],
+  cardsByKey: ReadonlyMap<string, GlyphScopeEntry>,
 ): ManifestLesson['notation'] {
   const definitions: ManifestLessonNotation[] = [];
   for (const definitionId of bundle?.definitionIds ?? []) {
@@ -320,6 +332,16 @@ function lessonNotationBundle(
       summary: definition.summary,
       editorialStatus: definition.status,
       seeAlso: [...definition.seeAlso],
+      glosses: [...definition.glosses],
+      formulaScope: formulaGlyphScope({
+        key: definition.key,
+        notation: definition.notation,
+        glosses: definition.glosses,
+        cardsByKey,
+        ...(definition.formula === undefined
+          ? {}
+          : { formula: definition.formula }),
+      }),
       ...(definition.units === undefined ? {} : { units: definition.units }),
       ...(definition.formula === undefined
         ? {}
@@ -379,6 +401,14 @@ export async function compileManifest(
   ]);
 
   const registry = buildNotationRegistry(notationInput);
+  // Cards a `formula` may name with `\explain{key}` (D15). Shared entries
+  // only: a page-local symbol is not addressable from another entry.
+  const cardsByKey = new Map<string, GlyphScopeEntry>(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation },
+    ]),
+  );
   const definitionsById = new Map(
     registry.definitions.map((definition) => [definition.id, definition]),
   );
@@ -476,6 +506,7 @@ export async function compileManifest(
           definitionsById,
           availableDefinitionIds,
         ),
+        cardsByKey,
       ),
     });
   }

package/src/components/HoverPanel.astro

@@ -11,6 +11,14 @@
  * Extra attributes (e.g. `data-notation-panel`, `data-citation-panel`) are
  * forwarded to the `<aside>` so each layer keeps the hook its tests and pin
  * controls already reference.
+ *
+ * `tabindex="-1"`: never in the tab order, but a valid target for
+ * `panel.focus()`. A layer that lets the reader click deeper into the panel's
+ * own content (D15's in-panel navigation) needs somewhere stable to move
+ * focus to before it replaces whatever the reader just clicked — otherwise
+ * removing the focused node drops focus to nothing, and the shared
+ * `focusout` handler in `./hover-panel.ts` reads that as "the reader left"
+ * and closes the panel it was just asked to update.
  */
 export interface Props {
   /** Element id — pin controls point `aria-controls` at it. */
@@ -31,8 +39,17 @@ const { id, label, class: className, ...rest } = Astro.props;
   aria-live="polite"
   aria-atomic="true"
   hidden
+  tabindex="-1"
   {...rest}
 >
+  <button
+    class="hover-panel-close"
+    type="button"
+    data-hover-panel-close
+    aria-label="Close"
+  >
+    <span aria-hidden="true">&times;</span>
+  </button>
   <slot />
 </aside>
 
@@ -48,6 +65,7 @@ const { id, label, class: className, ...rest } = Astro.props;
       width: min(23rem, calc(100vw - 1.5rem));
       overflow: auto;
       padding: 1rem;
+      padding-inline-end: 2.4rem;
       border: 1px solid var(--sl-color-gray-5);
       border-top: 0.25rem solid var(--sl-color-accent);
       border-radius: 0.65rem;
@@ -57,6 +75,30 @@ const { id, label, class: className, ...rest } = Astro.props;
       font-size: var(--sl-text-sm);
     }
 
+    .hover-panel-close {
+      position: absolute;
+      top: 0.5rem;
+      right: 0.5rem;
+      width: 1.6rem;
+      height: 1.6rem;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 0;
+      border: 0;
+      border-radius: 0.35rem;
+      color: var(--sl-color-gray-3);
+      background: transparent;
+      font-size: 1.15rem;
+      line-height: 1;
+      cursor: pointer;
+    }
+
+    .hover-panel-close:hover {
+      color: var(--sl-color-text);
+      background: var(--sl-color-gray-6);
+    }
+
     /* Slotted fields carry the owning layer's scope, not this component's, so
        the descendant match must be global. */
     .hover-panel :global(:focus-visible) {

package/src/components/citation/CitationLayer.astro

@@ -108,6 +108,7 @@ import HoverPanel from '../HoverPanel.astro';
 
     createHoverPanel({
       panel,
+      groupId: 'citation',
       triggerFrom: markerFrom,
       keyFor: (element) => element.dataset.citationNumber ?? null,
       render,