@glw907/cairn-cms 0.60.0 → 0.62.1

package/src/lib/components/MarkdownHelpDialog.svelte

@@ -7,6 +7,7 @@ open(), so the component renders no trigger of its own.
 -->
 <script lang="ts">
   import ShortcutsGrid from './ShortcutsGrid.svelte';
+  import { markdownReference } from './markdown-reference.js';
 
   let dialog = $state<HTMLDialogElement | null>(null);
 
@@ -33,21 +34,9 @@ open(), so the component renders no trigger of its own.
         </tr>
       </thead>
       <tbody>
-        <tr><td><code>## Heading</code></td><td>A heading</td></tr>
-        <tr><td><code>### Heading</code></td><td>A smaller heading</td></tr>
-        <tr><td><code>#### Heading</code></td><td>A fourth-level heading</td></tr>
-        <tr><td><code>**bold**</code></td><td>Bold text</td></tr>
-        <tr><td><code>*italic*</code></td><td>Italic text</td></tr>
-        <tr><td><code>~~text~~</code></td><td>Crossed-out text</td></tr>
-        <tr><td><code>[text](url)</code></td><td>A link</td></tr>
-        <tr><td><code>[[page-name]]</code></td><td>A link to one of your pages</td></tr>
-        <tr><td><code>- item</code></td><td>A bulleted list</td></tr>
-        <tr><td><code>1. item</code></td><td>A numbered list</td></tr>
-        <tr><td><code>- [ ] item</code></td><td>A checklist</td></tr>
-        <tr><td><code>&gt; quote</code></td><td>A quote</td></tr>
-        <tr><td><code>`code`</code></td><td>Code</td></tr>
-        <tr><td>Table</td><td>The Table button in the toolbar inserts one</td></tr>
-        <tr><td><code>---</code></td><td>A horizontal rule</td></tr>
+        {#each markdownReference as row (row.syntax)}
+          <tr><td><code>{row.syntax}</code></td><td>{row.makes}</td></tr>
+        {/each}
       </tbody>
     </table>
     <h3 class="mt-4 mb-2 text-sm font-semibold">Keyboard shortcuts</h3>

package/src/lib/components/client-ingest.ts

@@ -118,12 +118,16 @@ export function firstImageFile(dt: {
   return normalizeDataTransfer(dt)[0] ?? null;
 }
 
-/** The conservative canvas area budget, about 16.7M px (4096 x 4096). A source over this is scaled
- *  down before any `drawImage`, never clipped. */
+/**
+ * The conservative canvas area budget, about 16.7M px (4096 x 4096). A source over this is scaled
+ *  down before any `drawImage`, never clipped.
+ */
 export const MAX_AREA = 16_777_216;
 
-/** The conservative short-side budget. A source whose smaller dimension exceeds this is scaled down so
- *  the short side lands at the cap, even when its area is within MAX_AREA. */
+/**
+ * The conservative short-side budget. A source whose smaller dimension exceeds this is scaled down so
+ *  the short side lands at the cap, even when its area is within MAX_AREA.
+ */
 export const MAX_SHORT_SIDE = 4096;
 
 /**
@@ -151,9 +155,11 @@ export function budgetForDimensions(
   };
 }
 
-/** The ingest failure taxonomy. `decode-unsupported` is a format the browser and the HEIC decoder both
+/**
+ * The ingest failure taxonomy. `decode-unsupported` is a format the browser and the HEIC decoder both
  *  refuse; `transcode-failed` is a HEIC decode or a canvas re-encode that threw; `too-large` is a
- *  source still over budget after a transcode; `network` is the upload fetch rejecting. */
+ *  source still over budget after a transcode; `network` is the upload fetch rejecting.
+ */
 export type IngestFailureKind =
   | 'decode-unsupported'
   | 'transcode-failed'
@@ -254,8 +260,10 @@ export function buildUploadRequest(opts: UploadRequestOpts): { url: string; init
 // Browser-coupled glue (wired, proven live at 2b/site, not unit-tested here)
 // ---------------------------------------------------------------------------
 
-/** The structural shape of the heic-to module's `heicTo`, typed here so the dynamic import stays
- *  lazy. A HEIC blob in, a decoded image blob out (PNG, with the HEIF orientation already applied). */
+/**
+ * The structural shape of the heic-to module's `heicTo`, typed here so the dynamic import stays
+ *  lazy. A HEIC blob in, a decoded image blob out (PNG, with the HEIF orientation already applied).
+ */
 type HeicTo = (args: { blob: Blob; type: 'image/png' }) => Promise<Blob>;
 
 /** A decoded source plus its dimensions, the input to the upload step. */
@@ -373,8 +381,10 @@ export async function sendUpload(url: string, init: RequestInit): Promise<Respon
   }
 }
 
-/** Guard a drop target: cancel the browser's default open-the-file behavior on `dragover` and `drop`
- *  so a dropped image stays inside the editor rather than navigating the page to the file. */
+/**
+ * Guard a drop target: cancel the browser's default open-the-file behavior on `dragover` and `drop`
+ *  so a dropped image stays inside the editor rather than navigating the page to the file.
+ */
 export function guardDropTarget(event: DragEvent): void {
   event.preventDefault();
 }

package/src/lib/components/editor-media.ts

@@ -35,10 +35,12 @@ import type { MediaLibrary, MediaLibraryEntry } from '../media/library-entry.js'
 // validation, so a non-media or malformed URL is dropped after the match.
 const MEDIA_IMAGE = /!\[([^\]]*)\]\((media:[^\s)]+)\)/g;
 
-/** A matched media image in a line: the alt text and the URL token's character offsets within the
+/**
+ * A matched media image in a line: the alt text and the URL token's character offsets within the
  *  whole document, plus the parsed reference and the library entry (null when the hash is unknown).
  *  figureRole carries the enclosing `:::figure` placement (the closed-set role, or `'figure'` for
- *  the measure default), or null when the token is not in a figure: a bare token shows no role pill. */
+ *  the measure default), or null when the token is not in a figure: a bare token shows no role pill.
+ */
 interface MediaImageMatch {
   alt: string;
   from: number;
@@ -138,8 +140,10 @@ class MediaChipWidget extends WidgetType {
   }
 }
 
-/** Scan one line's text for media image tokens, mapping each to its document offsets and resolving its
- *  library entry. lineFrom is the line's document start, so the match offsets become absolute. */
+/**
+ * Scan one line's text for media image tokens, mapping each to its document offsets and resolving its
+ *  library entry. lineFrom is the line's document start, so the match offsets become absolute.
+ */
 function matchesInLine(text: string, lineFrom: number, library: MediaLibrary): MediaImageMatch[] {
   const out: MediaImageMatch[] = [];
   MEDIA_IMAGE.lastIndex = 0;
@@ -168,10 +172,12 @@ function matchesInLine(text: string, lineFrom: number, library: MediaLibrary): M
   return out;
 }
 
-/** Every media image match across the editor's visible ranges, in document order, each carrying its
+/**
+ * Every media image match across the editor's visible ranges, in document order, each carrying its
  *  enclosing figure role. One {@link fenceScan} over the whole document feeds the cheap per-token
  *  figure detection (no remark parse on the per-rebuild chip path); the visible lines are scanned
- *  for tokens, then each token's line index drives {@link figureRoleAtLine}. */
+ *  for tokens, then each token's line index drives {@link figureRoleAtLine}.
+ */
 function visibleMatches(view: EditorView, library: MediaLibrary): MediaImageMatch[] {
   const lines = view.state.doc.toString().split('\n');
   const scan = fenceScan(lines);
@@ -189,8 +195,10 @@ function visibleMatches(view: EditorView, library: MediaLibrary): MediaImageMatc
   return out;
 }
 
-/** Replace decorations for each visible media image's reference token: the chip widget over the URL
- *  token, the alt left untouched. The same spans seed the atomic-range set. */
+/**
+ * Replace decorations for each visible media image's reference token: the chip widget over the URL
+ *  token, the alt left untouched. The same spans seed the atomic-range set.
+ */
 function buildMediaDecorations(view: EditorView, library: MediaLibrary): DecorationSet {
   const builder = new RangeSetBuilder<Decoration>();
   for (const match of visibleMatches(view, library)) {
@@ -199,9 +207,11 @@ function buildMediaDecorations(view: EditorView, library: MediaLibrary): Decorat
   return builder.finish();
 }
 
-/** The atomic ranges for the visible media reference tokens: a caret or selection edit treats each
+/**
+ * The atomic ranges for the visible media reference tokens: a caret or selection edit treats each
  *  token as one unit, so a stray keystroke replaces the whole reference rather than corrupting a hex
- *  digit. Built from the same matches the decorations use, so the two never disagree. */
+ *  digit. Built from the same matches the decorations use, so the two never disagree.
+ */
 function buildAtomicRanges(view: EditorView, library: MediaLibrary): DecorationSet {
   const ranges: Range<Decoration>[] = [];
   for (const match of visibleMatches(view, library)) {

package/src/lib/components/editor-placeholder.ts

@@ -24,8 +24,10 @@ import {
 import { StateEffect, StateField, type Extension } from '@codemirror/state';
 import { insertImage as insertImageFormat } from './markdown-format.js';
 
-/** One active placeholder's data: its stable id, the object URL for the thumbnail, and the upload
- *  progress as a 0..1 fraction. The widget reads this to render the thumbnail and the bar. */
+/**
+ * One active placeholder's data: its stable id, the object URL for the thumbnail, and the upload
+ *  progress as a 0..1 fraction. The widget reads this to render the thumbnail and the bar.
+ */
 interface PlaceholderData {
   id: number;
   url: string;
@@ -87,8 +89,10 @@ class PlaceholderWidget extends WidgetType {
   }
 }
 
-/** The active placeholders as a decoration set plus the per-id position map, so a resolve can find
- *  the mapped position to insert at and the field can rebuild after a position shift. */
+/**
+ * The active placeholders as a decoration set plus the per-id position map, so a resolve can find
+ *  the mapped position to insert at and the field can rebuild after a position shift.
+ */
 interface PlaceholderState {
   set: DecorationSet;
   // Each active placeholder's current data and its mapped document position.
@@ -149,9 +153,11 @@ const placeholderField = StateField.define<PlaceholderState>({
   provide: (f) => EditorView.decorations.from(f, (v) => v.set),
 });
 
-/** The seam the host drives: begin lands a placeholder and returns its id; progress moves its bar;
+/**
+ * The seam the host drives: begin lands a placeholder and returns its id; progress moves its bar;
  *  resolveTo swaps it for the committed image text; cancel removes it leaving the source untouched.
- *  Mirrors the register-callback idiom MarkdownEditor uses for its other editor ops. */
+ *  Mirrors the register-callback idiom MarkdownEditor uses for its other editor ops.
+ */
 export interface ImagePlaceholderApi {
   /** Land an optimistic placeholder at the current caret from a local object URL; returns its id. */
   begin(objectUrl: string): number;

package/src/lib/components/editor-tidy.ts

@@ -20,10 +20,12 @@ import { Decoration, EditorView, WidgetType, type DecorationSet } from '@codemir
 import { StateEffect, StateField, RangeSet, type Extension, type Range } from '@codemirror/state';
 import type { Change } from './tidy-diff.js';
 
-/** A change plus its live disposition and current mapped span. `pending` is undecided-in-the-buffer:
+/**
+ * A change plus its live disposition and current mapped span. `pending` is undecided-in-the-buffer:
  *  it still carries decorations. `accepted` has been written (its edit dispatched), so it carries no
  *  decoration. `rejected` was dropped, so it also carries no decoration and never writes. The `from`
- *  and `to` are the change's current offsets, mapped across every accepted edit since tidy opened. */
+ *  and `to` are the change's current offsets, mapped across every accepted edit since tidy opened.
+ */
 interface TidyEntry {
 	index: number;
 	from: number;
@@ -171,21 +173,29 @@ const tidyField = StateField.define<TidyState>({
 	provide: (f) => EditorView.decorations.from(f, (v) => buildDecorations(v)),
 });
 
-/** The api the host drives over one editor view (spec 2.5). Mirrors imagePlaceholderApi: the host
+/**
+ * The api the host drives over one editor view (spec 2.5). Mirrors imagePlaceholderApi: the host
  *  registers it through registerTidy, and the review surface calls it as the author works the list.
- *  Every accept lands as a CodeMirror transaction; reject and reject-all write no text. */
+ *  Every accept lands as a CodeMirror transaction; reject and reject-all write no text.
+ */
 export interface TidyApi {
-	/** Open tidy with the validated change set: seed the field, show the decorations. The buffer is
-	 *  untouched; the originals stay until an accept writes. */
+	/**
+	 * Open tidy with the validated change set: seed the field, show the decorations. The buffer is
+	 *  untouched; the originals stay until an accept writes.
+	 */
 	enter(changes: Change[]): void;
-	/** Accept one change: dispatch its replacement over its current span in one transaction and mark it
-	 *  accepted. The other pending changes map across the edit. */
+	/**
+	 * Accept one change: dispatch its replacement over its current span in one transaction and mark it
+	 *  accepted. The other pending changes map across the edit.
+	 */
 	acceptOne(index: number): void;
 	/** Reject one change: mark it rejected so its decorations clear, leaving the original untouched. */
 	rejectOne(index: number): void;
-	/** Accept many changes (the bulk action) in ONE transaction: the whole edit is one undoable step.
+	/**
+	 * Accept many changes (the bulk action) in ONE transaction: the whole edit is one undoable step.
 	 *  The caller passes ONLY the indexes it has decided to keep; this never sweeps an index the caller
-	 *  did not name, which is how Accept-fixes confines itself to objective hunks. */
+	 *  did not name, which is how Accept-fixes confines itself to objective hunks.
+	 */
 	acceptMany(indexes: number[]): void;
 	/** Reject every remaining pending change, leaving the document byte-identical. */
 	rejectAll(): void;
@@ -193,15 +203,19 @@ export interface TidyApi {
 	exit(): void;
 }
 
-/** The tidy extension: the StateField holding the change set and its decorations. The host adds it to
+/**
+ * The tidy extension: the StateField holding the change set and its decorations. The host adds it to
  *  the initial editor state (in its own compartment beside media and folding), then builds the driving
- *  api with tidyApi once the view exists. */
+ *  api with tidyApi once the view exists.
+ */
 export function cairnTidy(): Extension {
 	return tidyField;
 }
 
-/** Build the api that drives tidy against one editor view. The host registers it through registerTidy;
- *  the review surface calls enter, the per-hunk and bulk accept/reject, and exit. */
+/**
+ * Build the api that drives tidy against one editor view. The host registers it through registerTidy;
+ *  the review surface calls enter, the per-hunk and bulk accept/reject, and exit.
+ */
 export function tidyApi(view: EditorView): TidyApi {
 	// Dispatch the named changes' replacements over their CURRENT mapped spans in one transaction, mark
 	// them accepted, and let the field map any remaining pending entries. The changes are read from the

package/src/lib/components/index.ts

@@ -8,6 +8,7 @@ export { default as CsrfField } from './CsrfField.svelte';
 export { default as ConceptList } from './ConceptList.svelte';
 export { default as CairnMediaLibrary } from './CairnMediaLibrary.svelte';
 export { default as CairnTidySettings } from './CairnTidySettings.svelte';
+export { default as HelpHome } from './HelpHome.svelte';
 export { default as EditPage } from './EditPage.svelte';
 export { default as ManageEditors } from './ManageEditors.svelte';
 export { default as MarkdownEditor } from './MarkdownEditor.svelte';

package/src/lib/components/link-completion.ts

@@ -21,15 +21,19 @@ function sectionFor(concept: string): { name: string; rank: number } {
   return CONCEPT_SECTIONS[concept] ?? { name: concept.charAt(0).toUpperCase() + concept.slice(1), rank: 2 };
 }
 
-/** The open `[[query` before the cursor, or null. The query stops at a closing bracket or a newline,
- *  so a finished `[[x]]` link and ordinary prose never trigger. `from` is the index of the `[[`. */
+/**
+ * The open `[[query` before the cursor, or null. The query stops at a closing bracket or a newline,
+ *  so a finished `[[x]]` link and ordinary prose never trigger. `from` is the index of the `[[`.
+ */
 export function matchCairnTrigger(before: string): { query: string; from: number } | null {
   const match = /\[\[([^[\]\n]*)$/.exec(before);
   return match ? { query: match[1], from: match.index } : null;
 }
 
-/** The completion options for a query: a case-insensitive title substring match, each option grouped
- *  by concept, a draft marked and a post date shown in the detail, and the apply text the full link. */
+/**
+ * The completion options for a query: a case-insensitive title substring match, each option grouped
+ *  by concept, a draft marked and a post date shown in the detail, and the apply text the full link.
+ */
 export function linkCompletions(targets: LinkTarget[], query: string): Completion[] {
   const q = query.trim().toLowerCase();
   const matched = q ? targets.filter((t) => t.title.toLowerCase().includes(q)) : targets;
@@ -41,9 +45,11 @@ export function linkCompletions(targets: LinkTarget[], query: string): Completio
   }));
 }
 
-/** A CodeMirror CompletionSource over the site's link targets, triggered by `[[`. It replaces the
+/**
+ * A CodeMirror CompletionSource over the site's link targets, triggered by `[[`. It replaces the
  *  whole `[[query` with the chosen link, and sets filter:false because linkCompletions already
- *  filtered by the query (CodeMirror would otherwise re-filter against the literal `[[query`). */
+ *  filtered by the query (CodeMirror would otherwise re-filter against the literal `[[query`).
+ */
 export function cairnLinkCompletionSource(targets: LinkTarget[]): CompletionSource {
   return async (context: CompletionContext): Promise<CompletionResult | null> => {
     const line = context.state.doc.lineAt(context.pos);

package/src/lib/components/markdown-directives.ts

@@ -18,8 +18,8 @@ const INLINE = /(?<![:\w]):[\w-]+\[[^\]]*\](\{[^}]*\})?/g;
 const CODE_FENCE = /^\s{0,3}(`{3,}|~{3,})/;
 
 /**
- * The directive name from a container opener line (`:::callout{...}` -> `callout`,
- * `::::cta[Book]` -> `cta`), or null when the line is not a named container opener. Reads the
+ * The directive name from a container opener line (`:::callout{...}` gives `callout`,
+ * `::::cta[Book]` gives `cta`), or null when the line is not a named container opener. Reads the
  * same FENCE match the scan uses: group 2 is the name, empty on a bare closer, so a closer or a
  * non-fence line returns null.
  */
@@ -39,9 +39,11 @@ export function directiveLineKind(line: string): 'fence' | 'leaf' | null {
 export interface FenceScan {
   /** The 1-based container depth per line, or null outside any container. */
   depths: (number | null)[];
-  /** Whether a line opened or closed a container, or null for everything else. A fence-shaped
+  /**
+   * Whether a line opened or closed a container, or null for everything else. A fence-shaped
    *  line the code-block tracking disowned is null too, so the role array is the one source of
-   *  truth for pairing and no caller re-parses a line the scan already judged. */
+   *  truth for pairing and no caller re-parses a line the scan already judged.
+   */
   roles: ('opener' | 'closer' | null)[];
 }
 
@@ -161,8 +163,10 @@ export function containerRanges(scan: FenceScan): ContainerRange[] {
   return out;
 }
 
-/** The closed placement-role set for the reserved `figure` directive, mirroring remark-figure.ts.
- *  A class outside this set is the measure default, never passed through as a role. */
+/**
+ * The closed placement-role set for the reserved `figure` directive, mirroring remark-figure.ts.
+ *  A class outside this set is the measure default, never passed through as a role.
+ */
 const FIGURE_ROLES = new Set(['center', 'wide', 'full']);
 
 // The directive `{attrs}` brace, and the `.class` shorthands inside it. mdast-util-directive folds
@@ -174,7 +178,8 @@ const ATTR_BRACE = /\{([^}]*)\}/;
 const CLASS_SHORTHAND = /\.([\w-]+)/g;
 const CLASS_ATTR = /class\s*=\s*"([^"]*)"/;
 
-/** The figure placement role for a media token sitting on `lineIndex`, derived from the editor's
+/**
+ * The figure placement role for a media token sitting on `lineIndex`, derived from the editor's
  *  line scan without a remark parse (the chip rebuild runs on every doc and viewport change).
  *
  *  Returns the closed-set role (`center`/`wide`/`full`) when the innermost container holding the
@@ -216,7 +221,7 @@ export interface FenceToken {
 
 /**
  * Split a fence line into machinery and meaning. The colon run, the label's brackets, and the
- * whole {attrs} group are machinery; the directive name and the label text are meaning, the
+ * whole `{attrs}` group are machinery; the directive name and the label text are meaning, the
  * parts an editor reads. A bare closer is a single machinery span, and a non-fence line yields
  * no spans at all.
  */

package/src/lib/components/markdown-format.ts

@@ -59,8 +59,10 @@ const LINE: Record<LineKind, { prefix: (i: number) => string; exact?: RegExp; st
 const TABLE_GRID =
   '| Column 1 | Column 2 |\n| -------- | -------- |\n|          |          |\n|          |          |';
 
-/** Wrap the selection in `marker`, or unwrap when the markers are already there (inside or just
- *  outside the selection). The returned range covers the text without its markers either way. */
+/**
+ * Wrap the selection in `marker`, or unwrap when the markers are already there (inside or just
+ *  outside the selection). The returned range covers the text without its markers either way.
+ */
 function toggleWrap(doc: string, from: number, to: number, marker: string): FormatResult {
   const m = marker.length;
   const sel = doc.slice(from, to);
@@ -75,10 +77,12 @@ function toggleWrap(doc: string, from: number, to: number, marker: string): Form
   return { doc: next, from: from + m, to: to + m };
 }
 
-/** Apply a line-prefix kind to every selected line. When the kind toggles and every line already
+/**
+ * Apply a line-prefix kind to every selected line. When the kind toggles and every line already
  *  carries its marker, the markers come off; otherwise competing markers are replaced and each
  *  line gains the kind's prefix. The selection shifts with the first line's edit and stretches
- *  by the total length change, the same mechanics the original single-prefix version had. */
+ *  by the total length change, the same mechanics the original single-prefix version had.
+ */
 function applyLinePrefix(doc: string, from: number, to: number, kind: LineKind): FormatResult {
   const { prefix, exact, strip } = LINE[kind];
   const lineStart = doc.lastIndexOf('\n', from - 1) + 1; // 0 when the selection is on the first line
@@ -97,8 +101,10 @@ function applyLinePrefix(doc: string, from: number, to: number, kind: LineKind):
   };
 }
 
-/** Fence the selected lines in triple backticks on their own lines, or remove the fences when the
- *  lines just above and below the selection already are fences. */
+/**
+ * Fence the selected lines in triple backticks on their own lines, or remove the fences when the
+ *  lines just above and below the selection already are fences.
+ */
 function toggleCodeFence(doc: string, from: number, to: number): FormatResult {
   const lineStart = doc.lastIndexOf('\n', from - 1) + 1;
   const lineEndRaw = doc.indexOf('\n', to);
@@ -118,6 +124,9 @@ function toggleCodeFence(doc: string, from: number, to: number): FormatResult {
   return { doc: next, from: from + open.length, to: to + open.length };
 }
 
+/**
+ *
+ */
 export function applyMarkdownFormat(doc: string, from: number, to: number, kind: FormatKind): FormatResult {
   if (kind === 'bold' || kind === 'italic' || kind === 'code' || kind === 'strike') {
     return toggleWrap(doc, from, to, WRAP[kind]);
@@ -215,10 +224,12 @@ export function findMediaImagesNeedingAlt(doc: string): MediaImageNeedingAlt[] {
   return hits;
 }
 
-/** Concatenate a link node's text-child values. The parser has already unescaped them, so a source
+/**
+ * Concatenate a link node's text-child values. The parser has already unescaped them, so a source
  *  `Notes \[draft\]` yields `Notes [draft]`. Used instead of mdast-util-to-string, which is not a
  *  direct dependency. Non-text children (a nested emphasis, say) contribute no value, which is fine
- *  for the picker-produced links this fix targets. */
+ *  for the picker-produced links this fix targets.
+ */
 function linkText(node: Link): string {
   return node.children.map((c) => ('value' in c ? c.value : '')).join('');
 }
@@ -250,8 +261,10 @@ export function unwrapCairnLink(doc: string, href: string): string {
   return out;
 }
 
-/** The closed placement role set the figure render step honors. A role outside it is the measure
- *  default (null), so the control never writes one. Mirrors the set in render/remark-figure.ts. */
+/**
+ * The closed placement role set the figure render step honors. A role outside it is the measure
+ *  default (null), so the control never writes one. Mirrors the set in render/remark-figure.ts.
+ */
 export type FigureRole = 'center' | 'wide' | 'full';
 const FIGURE_ROLES = new Set<string>(['center', 'wide', 'full']);
 
@@ -281,15 +294,19 @@ export interface FigureAtImage {
   } | null;
 }
 
-/** Parse a doc with the figure-aware pipeline (the render step's grammar), so the editor transforms
- *  agree with what renders. Container directives need remark-directive on top of the markdown base. */
+/**
+ * Parse a doc with the figure-aware pipeline (the render step's grammar), so the editor transforms
+ *  agree with what renders. Container directives need remark-directive on top of the markdown base.
+ */
 function parseFigureDoc(doc: string): Root {
   return unified().use(remarkParse).use(remarkGfm).use(remarkDirective).parse(doc) as Root;
 }
 
-/** Find the media `image` node whose source range contains `pos`, or whose enclosing figure contains
+/**
+ * Find the media `image` node whose source range contains `pos`, or whose enclosing figure contains
  *  `pos`, along with its enclosing `figure` directive when there is one. Returns null when `pos` is
- *  not on a media image nor inside a figure that wraps one. */
+ *  not on a media image nor inside a figure that wraps one.
+ */
 function locateMediaImage(
   tree: Root,
   pos: number,
@@ -322,8 +339,10 @@ function locateMediaImage(
   return figureHit ?? bareHit;
 }
 
-/** The `figure`-named container directive that encloses `node`, or null. Walks the tree to find the
- *  ancestor, since unist-util-visit's per-call ancestors are not retained across the traversal. */
+/**
+ * The `figure`-named container directive that encloses `node`, or null. Walks the tree to find the
+ *  ancestor, since unist-util-visit's per-call ancestors are not retained across the traversal.
+ */
 function enclosingFigure(tree: Root, target: Image): ContainerDirective | null {
   let found: ContainerDirective | null = null;
   visit(tree, 'containerDirective', (dir: ContainerDirective) => {
@@ -337,26 +356,32 @@ function enclosingFigure(tree: Root, target: Image): ContainerDirective | null {
   return found;
 }
 
-/** Strip one leading backslash sitting immediately before a colon, the inverse of the fence-escape
+/**
+ * Strip one leading backslash sitting immediately before a colon, the inverse of the fence-escape
  *  wrapImageInFigure/updateFigure apply, so a caption that began with a directive-opening colon run
- *  round-trips to the author's original text. */
+ *  round-trips to the author's original text.
+ */
 function unescapeCaption(raw: string): string {
   return raw.replace(/^\\(?=:)/, '');
 }
 
-/** Collapse a raw caption source span to the single-line value the control edits: internal newlines
- *  to single spaces, trimmed, with the leading-colon fence escape stripped. */
+/**
+ * Collapse a raw caption source span to the single-line value the control edits: internal newlines
+ *  to single spaces, trimmed, with the leading-colon fence escape stripped.
+ */
 function finishCaption(raw: string): string {
   return unescapeCaption(raw.replace(/\s*\n\s*/g, ' ').trim());
 }
 
-/** Read the raw caption source from a figure directive, mirroring the render step's caption: the first
+/**
+ * Read the raw caption source from a figure directive, mirroring the render step's caption: the first
  *  text-bearing content after the image. The render step (remark-figure.ts) handles both caption
  *  forms, so the read must too. In the no-blank-line form the caption shares the image's paragraph,
  *  trailing the token, so it is read from the token end to that block's end; in the blank-line form it
  *  is the first text-bearing block after the image's paragraph. Only the first such content is the
  *  caption (a later block is a stray paragraph the render leaves outside the figcaption). Empty when
- *  the figure has no caption. */
+ *  the figure has no caption.
+ */
 function readCaption(doc: string, figure: ContainerDirective, image: Image): string {
   const imageStart = image.position?.start?.offset;
   const imageEnd = image.position?.end?.offset;
@@ -385,8 +410,10 @@ function readCaption(doc: string, figure: ContainerDirective, image: Image): str
   return '';
 }
 
-/** Whether a block's subtree carries any non-whitespace text, the caption-candidate test the render
- *  step uses (a bare image paragraph has no text node, so it is never read as a caption). */
+/**
+ * Whether a block's subtree carries any non-whitespace text, the caption-candidate test the render
+ *  step uses (a bare image paragraph has no text node, so it is never read as a caption).
+ */
 function blockHasText(node: RootContent): boolean {
   let found = false;
   visit(node, 'text', (text) => {
@@ -418,19 +445,23 @@ export function figureAtImage(doc: string, pos: number): FigureAtImage | null {
   return { imageFrom, imageTo, figure: { from, to, caption: readCaption(doc, dir, hit.image), role } };
 }
 
-/** Sanitize a caption into a single safe body line: collapse internal newlines to single spaces,
+/**
+ * Sanitize a caption into a single safe body line: collapse internal newlines to single spaces,
  *  trim, and neutralize ONLY the directive-fence hazard (a leading colon would open a directive at
  *  line start) by prefixing one backslash. The author's inline markdown is preserved otherwise, so
- *  emphasis and links survive. figureAtImage strips the backslash on read for a clean round-trip. */
+ *  emphasis and links survive. figureAtImage strips the backslash on read for a clean round-trip.
+ */
 function sanitizeCaption(caption: string): string {
   const line = caption.replace(/\s*\n\s*/g, ' ').trim();
   return line.startsWith(':') ? '\\' + line : line;
 }
 
-/** Build the canonical figure block source: the opener (with the role brace only for a non-null
+/**
+ * Build the canonical figure block source: the opener (with the role brace only for a non-null
  *  role), the image token verbatim on its own line, then a blank line and the sanitized caption when
  *  the caption is non-empty, and the closing fence. This is the blank-line form remarkFigure reads as
- *  its primary path, and it reads cleanly when hand-edited. */
+ *  its primary path, and it reads cleanly when hand-edited.
+ */
 function buildFigureBlock(imageSrc: string, caption: string, role: FigureRole | null): string {
   const opener = role ? `:::figure{.${role}}` : ':::figure';
   const cap = sanitizeCaption(caption);
@@ -466,9 +497,11 @@ export function wrapImageInFigure(
   return { doc: before + inserted + after, from: end, to: end };
 }
 
-/** The inner image token of the figure at `figureRange.from`, sliced verbatim from the source so it
+/**
+ * The inner image token of the figure at `figureRange.from`, sliced verbatim from the source so it
  *  is reused byte-for-byte (open risk 3). Empty when no media image is found there, which leaves the
- *  rebuild image-less rather than throwing. Shared by updateFigure and unwrapFigure. */
+ *  rebuild image-less rather than throwing. Shared by updateFigure and unwrapFigure.
+ */
 function figureImageSrc(doc: string, figureRange: { from: number; to: number }): string {
   const info = figureAtImage(doc, figureRange.from);
   return info ? doc.slice(info.imageFrom, info.imageTo) : '';

package/src/lib/components/markdown-reference.ts

@@ -0,0 +1,30 @@
+// The one Markdown cheat-sheet table, the single source the editor's Markdown help dialog and the
+// Help home both render, so the two surfaces cannot drift. Each row pairs the literal syntax an
+// author types with a plain gloss of what it makes, grouped so the Help home can show the everyday
+// rows (text and links) and the dialog can show every group. Mirrors editor-shortcuts.ts.
+
+/** One cheat-sheet row: the literal syntax, a plain gloss, and the group it belongs to. */
+export interface MarkdownReferenceRow {
+  syntax: string;
+  makes: string;
+  group: 'text' | 'links' | 'blocks';
+}
+
+/** The cheat-sheet vocabulary, everyday rows first: the five text, the four links, then the blocks. */
+export const markdownReference: MarkdownReferenceRow[] = [
+  { syntax: '## Heading', makes: 'A heading', group: 'text' },
+  { syntax: '**bold**', makes: 'Bold text', group: 'text' },
+  { syntax: '*italic*', makes: 'Italic text', group: 'text' },
+  { syntax: '> quote', makes: 'A quote', group: 'text' },
+  { syntax: '`code`', makes: 'Inline code', group: 'text' },
+  { syntax: '[text](url)', makes: 'A link', group: 'links' },
+  { syntax: '[[page-name]]', makes: 'A link to one of your pages', group: 'links' },
+  { syntax: '- item', makes: 'A bulleted list', group: 'links' },
+  { syntax: '1. item', makes: 'A numbered list', group: 'links' },
+  { syntax: '### Heading', makes: 'A smaller heading', group: 'blocks' },
+  { syntax: '#### Heading', makes: 'A fourth-level heading', group: 'blocks' },
+  { syntax: '~~text~~', makes: 'Crossed-out text', group: 'blocks' },
+  { syntax: '- [ ] item', makes: 'A checklist', group: 'blocks' },
+  { syntax: 'Table', makes: 'The Table button in the toolbar inserts one', group: 'blocks' },
+  { syntax: '---', makes: 'A horizontal rule', group: 'blocks' },
+];