@nbtca/prompt 1.3.2 → 1.4.1

package/dist/features/docs.js

@@ -2,13 +2,15 @@ import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import chalk from 'chalk';
 import open from 'open';
-import { select, isCancel, confirm, text } from '@clack/prompts';
-import { error, warning, createSpinner } from '../core/ui.js';
+import { runMenu, menuFooter } from '../core/components/menu.js';
+import { runTextInput } from '../core/components/text-input.js';
+import { runConfirm } from '../core/components/confirm.js';
+import { warning, createSpinner } from '../core/ui.js';
 import { pickIcon } from '../core/icons.js';
 import { spawn, execFileSync } from 'child_process';
 import { URLS } from '../config/data.js';
 import { t, fmt } from '../i18n/index.js';
-import { setVimKeysActive } from '../core/vim-keys.js';
+import { enterScreen, breadcrumb } from '../core/transitions.js';
 import { createDocsClient } from '@nbtca/docs';
 function detectTerminalType() {
     const term = (process.env['TERM'] || '').toLowerCase();
@@ -48,16 +50,56 @@ function hasGlow() {
         _hasGlow = commandExists('glow');
     return _hasGlow;
 }
+// nbtca/documents links internally with relative/root-relative paths
+// (`./what-is-nbtca`, `/concepts/school`) that only resolve in a browser --
+// a terminal pager can neither follow nor hover-preview them, so showing
+// the path is dead weight. Matches './x', '../x', and '/x' but not a bare
+// '/' (an internal href is never *just* a slash in this content).
+function isInternalHref(href) {
+    return /^\.{0,2}\/./.test(href);
+}
 let _markedConfigured = false;
-function ensureMarkedConfigured() {
+export function ensureMarkedConfigured() {
     if (_markedConfigured)
         return;
     _markedConfigured = true;
-    marked.use(markedTerminal(getRendererOptions(getTerminalType())));
+    const extension = markedTerminal(getRendererOptions(getTerminalType()));
+    const renderer = extension.renderer ?? (extension.renderer = {});
+    const renderExternalLink = renderer.link;
+    if (renderExternalLink) {
+        renderer.link = function (token) {
+            if (isInternalHref(token.href))
+                return chalk.cyan.underline(token.text);
+            return renderExternalLink.call(this, token);
+        };
+    }
+    // marked-terminal's own `text` renderer always uses the token's raw
+    // `.text` string, never `.tokens` -- fine for a plain text run, but a
+    // *tight* list item (nbtca/documents' convention throughout: no blank
+    // line between "- " entries) tokenizes its content as a `text` token
+    // with markdown links inside still sitting unparsed in `.tokens`, not
+    // resolved into `.text`. Result: every link inside every bullet list
+    // rendered as completely raw, un-clickable-looking `[text](url)` syntax
+    // (only paragraph-level links, which *do* go through inline-parsing,
+    // picked up the `link` override above at all). Recursing into
+    // `parser.parseInline` here when `.tokens` exists routes list-item links
+    // through the same override, matching how paragraph/heading already do.
+    const renderPlainText = renderer.text;
+    if (renderPlainText) {
+        renderer.text = function (token) {
+            const withTokens = token;
+            if (Array.isArray(withTokens.tokens) && withTokens.tokens.length > 0) {
+                return this
+                    .parser.parseInline(withTokens.tokens);
+            }
+            return renderPlainText.call(this, token);
+        };
+    }
+    marked.use(extension);
 }
 // ─── marked-terminal renderer ─────────────────────────────────────────────────
 function getRendererOptions(type) {
-    const width = Math.min(process.stdout.columns || 80, 80);
+    const width = 80;
     const unicodeTableChars = {
         top: '─', 'top-mid': '┬', 'top-left': '┌', 'top-right': '┐',
         bottom: '─', 'bottom-mid': '┴', 'bottom-left': '└', 'bottom-right': '┘',
@@ -74,6 +116,14 @@ function getRendererOptions(type) {
         width,
         emoji: true,
         unescape: true,
+        // marked-terminal defaults this to true, prefixing every heading with
+        // its literal '#'/'##'/etc. markdown syntax. displayWithLess() already
+        // prints its own clean title line above the content, and most docs'
+        // first line is an H1 matching that same title -- so the raw '#
+        // Title' immediately below just repeated it a second time, syntax
+        // marks and all. firstHeading/heading's bold+color already
+        // distinguishes heading levels without the extra prefix.
+        showSectionPrefix: false,
         firstHeading: chalk.bold.cyan,
         heading: chalk.bold.white,
         codespan: chalk.yellowBright,
@@ -186,7 +236,7 @@ const CONTAINER_ICONS_ASCII = {
 const CONTAINER_ICONS_UNICODE = {
     info: 'ℹ️', tip: '💡', warning: '⚠️', danger: '🚨', details: '▶️'
 };
-function cleanMarkdownContent(content, type = getTerminalType()) {
+export function cleanMarkdownContent(content, type = getTerminalType()) {
     let c = content;
     // 1. YAML frontmatter
     c = c.replace(/^---\n[\s\S]*?\n---\n?/m, '');
@@ -203,6 +253,14 @@ function cleanMarkdownContent(content, type = getTerminalType()) {
         return `> ${icon} **${label}**\n>\n${quoted}\n`;
     });
     c = c.replace(/^:::\s*\w*.*$/gm, '');
+    // Internal wiki links (./foo, /concepts/foo) are handled at the renderer
+    // level (ensureMarkedConfigured's link override below), not here -- an
+    // earlier version of this rewrote link syntax into pre-colored raw ANSI
+    // text before marked() ever saw it, which broke when marked-terminal's
+    // own text reflow/wrapping ran on top of already-escaped text, corrupting
+    // the escape sequences into literal visible "[36m...[24m" garbage.
+    // Overriding the renderer instead lets marked-terminal own all ANSI
+    // output, so nothing downstream can mangle it.
     // 4. GitHub / GitLab callout alerts  (> [!NOTE])
     c = c.replace(/^>\s*\[!(NOTE|TIP|WARNING|CAUTION|IMPORTANT)\]\s*$/gim, (_, type) => `> **${type.charAt(0) + type.slice(1).toLowerCase()}:**`);
     // 5. [[toc]] — no value in terminal
@@ -272,14 +330,108 @@ function hasMarkdownTable(content) {
 function hasMermaidBlock(content) {
     return /^```mermaid\b/m.test(content);
 }
+/** Every internal ([text](href) where isInternalHref(href)) link in a
+ * document, in reading order, raw href not yet resolved to a real path. */
+function extractInternalLinks(markdown) {
+    const links = [];
+    const re = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(markdown))) {
+        const href = m[2] ?? '';
+        if (isInternalHref(href))
+            links.push({ text: m[1] ?? '', href });
+    }
+    return links;
+}
+/** Resolves a wiki-style href (relative to the *linking* document, VitePress
+ * conventions: no .md extension, trailing '/' means that dir's index) into
+ * a real repo-relative path matching DocItem.path -- e.g. './what-is-nbtca'
+ * from within 'about/index.md' -> 'about/what-is-nbtca.md'; '/concepts/'
+ * (root-relative, works from anywhere) -> 'concepts/index.md'. */
+function resolveInternalHref(href, fromPath) {
+    const fromDir = fromPath.includes('/') ? fromPath.slice(0, fromPath.lastIndexOf('/')) : '';
+    const combined = href.startsWith('/') ? href.slice(1) : (fromDir ? `${fromDir}/${href}` : href);
+    const stack = [];
+    for (const part of combined.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            stack.pop();
+            continue;
+        }
+        stack.push(part);
+    }
+    let target = stack.join('/');
+    if (target === '' || href.endsWith('/'))
+        target += (target ? '/' : '') + 'index';
+    if (!target.endsWith('.md'))
+        target += '.md';
+    return target;
+}
+/** Loads and renders a doc for the native in-app reader -- the same
+ * fetch/clean/render/cache pipeline viewMarkdownFile uses, minus the
+ * spinner/pager/post-read menu, which belong to the classic-pager
+ * presentation layer, not this one. */
+export async function loadDocForReader(filePath) {
+    ensureMarkedConfigured();
+    const rawContent = await fetchFileContent(filePath);
+    const fingerprint = contentFingerprint(rawContent);
+    const cached = getFreshRender(filePath);
+    let renderedDoc;
+    if (cached && cached.fingerprint === fingerprint) {
+        renderedDoc = cached;
+    }
+    else {
+        const cleaned = cleanMarkdownContent(rawContent, getTerminalType());
+        const title = extractDocTitle(rawContent, cleaned) || cleanFileName(filePath.split('/').pop() ?? filePath);
+        const readTime = estimateReadTime(cleaned);
+        const rendered = await marked(cleaned);
+        renderedDoc = { fingerprint, cleaned, rendered, title, readTime };
+        setRender(filePath, renderedDoc);
+    }
+    const seen = new Set();
+    const links = [];
+    for (const raw of extractInternalLinks(renderedDoc.cleaned)) {
+        const resolved = resolveInternalHref(raw.href, filePath);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        links.push({ text: raw.text, href: resolved });
+    }
+    return { path: filePath, title: renderedDoc.title, lines: renderedDoc.rendered.split('\n'), links };
+}
 // ─── Document tree ────────────────────────────────────────────────────────────
-const TOP_SECTION_ORDER = ['tutorial', 'process', 'repair', 'archived'];
+// Sourced from a live audit of nbtca/documents (2026-07-18): `about` and
+// `concepts` are two whole new top-level sections added in the repo's wiki
+// reconstruction (5abcc4d, 5beee27) -- omitted here, buildSections() below
+// silently drops every file under them, which is exactly what happened
+// before this fix caught up to the upstream restructuring. `about` leads
+// (org intro for newcomers) and `concepts` sits after the practical guide
+// as reference material.
+const TOP_SECTION_ORDER = ['about', 'guide', 'repair', 'concepts', 'archived'];
 const TOP_SECTION_SKIP = new Set(['docs', 'index.md', 'README.md']);
+// tutorial/ and process/ are two folders on disk but one section everywhere
+// a reader actually sees them: nbtca/documents' own site nav collapses both
+// under a single "指南/Guide" entry, and tutorial/sidebar.ts spells out why
+// ("「指南」= 教程（学技术）+流程（办社务）高内聚合并为一栏") -- presenting
+// them as two separate top-level categories in the terminal was true to the
+// folder layout but false to how the content is actually meant to be read.
+const SECTION_ALIAS = { tutorial: 'guide', process: 'guide' };
+export function localizeDocSections(sections, trans = t()) {
+    const labels = {
+        about: trans.docs.categoryAbout,
+        guide: trans.docs.categoryGuide,
+        repair: trans.docs.categoryRepair,
+        concepts: trans.docs.categoryConcepts,
+        archived: trans.docs.categoryArchived,
+    };
+    return sections.map((section) => ({ ...section, label: labels[section.key] ?? section.label }));
+}
 /**
  * Convert a kebab-case filename to a display-friendly title.
  * Preserves Chinese characters and date prefixes.
  */
-function cleanFileName(name) {
+export function cleanFileName(name) {
     const base = name.replace(/\.md$/, '');
     if (/^[\d.]/.test(base))
         return base;
@@ -287,40 +439,81 @@ function cleanFileName(name) {
         .replace(/[-_]/g, ' ')
         .replace(/\b([a-z])/g, (_, c) => c.toUpperCase());
 }
+/**
+ * Real titles (each document's own top-level `# heading`) for the
+ * curated tutorial/process/repair sections, keyed by repo-relative path.
+ * These are hand-authored English-filename docs with Chinese content —
+ * mechanically title-casing the filename ("Clean Drive C") reads as a
+ * different, lower-quality product than the document's own title ("C盘
+ * 清理标准化流程"). Deliberately scoped to these three sections only:
+ * `archived/`'s meeting notes are informal and often share the same
+ * generic real heading across many different dates (e.g. five different
+ * files all titled just "维修日") — there, the current filename-derived,
+ * date-prefixed label is more useful for telling entries apart than the
+ * real heading would be, so it is intentionally left as-is.
+ *
+ * Pulled from a live audit of the actual nbtca/documents content
+ * (2026-07-16). A doc added later without an entry here simply falls
+ * back to `cleanFileName` — never an error, never a blank label.
+ */
+const KNOWN_DOC_TITLES = {
+    'tutorial/2025/clean-drive-c.md': 'C盘清理标准化流程',
+    'tutorial/2025/edu-email.md': '教育邮箱用途',
+    'tutorial/2025/github-education-verification.md': 'Github Education 认证指南',
+    'tutorial/2025/github-workflow.md': '快速上手社团目前的Github工作流',
+    'tutorial/2025/google-calendar.md': '谷歌日历使用指南',
+    'tutorial/2025/nginx-usage.md': '快速上手你的nginx',
+    'tutorial/2025/tailscale-usage.md': '社团自建 Tailscale 使用指南',
+    'tutorial/manual/hardware-establish.md': '计算机硬件系统的搭建与维护',
+    'tutorial/manual/net-usage.md': '国际互联网的使用',
+    'tutorial/manual/os-skills.md': '基础操作系统的使用技术',
+    'tutorial/manual/windows-from-scratch.md': '从零开始安装 Windows',
+    'process/2025/apply-for-credits.md': '申请第二课堂学分',
+    'process/2025/borrow-classroom.md': '借教室',
+    'process/2025/event-organization.md': '活动举办文档(待完善)',
+    'process/2025/nbtca-post.md': '撰写并发布你的第一篇NBTCA博客',
+    'process/2025/reimbursement-process.md': '报销流程',
+    'repair/checklist.md': '维修日检查单',
+    'repair/guide.md': '维修操作指南',
+    'repair/repair-day.md': '维修日',
+    'repair/tools.md': '软件仓库（校内镜像站）',
+    'repair/weekend.md': '维修工单系统 (weekend)',
+};
+/** Display title for a tutorial/process/repair doc: the real, known title
+ * when we have one, otherwise the same filename-derived fallback used
+ * everywhere else (including for every archived/ doc, which never has a
+ * known-title entry by design). */
+export function displayDocTitle(path, name) {
+    return KNOWN_DOC_TITLES[path] ?? cleanFileName(name);
+}
 /** Group flat DocItem list into top-level sections. */
-function buildSections(all) {
-    const trans = t();
-    const labelMap = {
-        tutorial: trans.docs.categoryTutorial,
-        process: trans.docs.categoryProcess,
-        repair: trans.docs.categoryRepair,
-        archived: trans.docs.categoryArchived,
-    };
+export function buildSections(all) {
     const groups = new Map();
     for (const item of all) {
         const parts = item.path.split('/');
         if (parts.length < 2)
             continue;
-        const top = parts[0];
-        if (TOP_SECTION_SKIP.has(top))
+        const rawTop = parts[0];
+        if (TOP_SECTION_SKIP.has(rawTop))
             continue;
+        const top = SECTION_ALIAS[rawTop] ?? rawTop;
         if (!TOP_SECTION_ORDER.includes(top))
             continue;
         if (!groups.has(top))
             groups.set(top, []);
         groups.get(top).push(item);
     }
-    return TOP_SECTION_ORDER
+    return localizeDocSections(TOP_SECTION_ORDER
         .filter(k => groups.has(k))
         .map(k => ({
         key: k,
-        label: labelMap[k] ?? k,
+        label: k,
         count: groups.get(k).length,
         files: groups.get(k),
-    }));
+    })));
 }
 /** Group archived files by their second path component (year / manual / etc.). */
-function getArchivedGroups(files) {
+export function getArchivedGroups(files) {
     const groups = new Map();
     for (const item of files) {
         const group = item.path.split('/')[1] ?? 'other';
@@ -330,12 +523,19 @@ function getArchivedGroups(files) {
     }
     return groups;
 }
+/** Raw fetch, no spinner/UI — throws on failure. Shared by the classic and
+ * native-view loaders. */
+export async function fetchAllDocs() {
+    return docsClient.listAll();
+}
+export async function fetchSections() {
+    return buildSections(await fetchAllDocs());
+}
 async function loadSections() {
     const trans = t();
     const s = createSpinner(trans.docs.loading);
     try {
-        const all = await docsClient.listAll();
-        const sections = buildSections(all);
+        const sections = await fetchSections();
         s.stop();
         return sections;
     }
@@ -417,14 +617,15 @@ async function showDocSection(section) {
     const files = section.files.filter(f => f.name !== 'index.md' && !f.name.startsWith('index.'));
     if (files.length === 0)
         return;
-    const selected = await select({
-        message: section.label,
+    const selected = await runMenu({
+        title: section.label,
         options: [
             ...files.map(f => ({ value: f.path, label: cleanFileName(f.name) })),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
+        footer: menuFooter(),
     });
-    if (isCancel(selected) || selected === '__back__')
+    if (selected === null || selected === '__back__')
         return;
     await viewMarkdownFile(selected);
 }
@@ -443,8 +644,8 @@ async function showArchivedSection(files) {
             return 1;
         return a.localeCompare(b);
     });
-    const groupKey = await select({
-        message: trans.docs.categoryArchived,
+    const groupKey = await runMenu({
+        title: trans.docs.categoryArchived,
         options: [
             ...sortedKeys.map(k => ({
                 value: k,
@@ -453,13 +654,14 @@ async function showArchivedSection(files) {
             })),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
+        footer: menuFooter(),
     });
-    if (isCancel(groupKey) || groupKey === '__back__')
+    if (groupKey === null || groupKey === '__back__')
         return;
     const groupFiles = groups.get(groupKey) ?? [];
     const subDirs = new Set(groupFiles.map(f => f.path.split('/')[2]).filter(Boolean));
-    const fileSelected = await select({
-        message: `${trans.docs.categoryArchived} · ${groupKey}`,
+    const fileSelected = await runMenu({
+        title: `${trans.docs.categoryArchived} · ${groupKey}`,
         options: [
             ...groupFiles.map(f => {
                 const sub = f.path.split('/').slice(2, -1).join('/');
@@ -471,17 +673,18 @@ async function showArchivedSection(files) {
             }),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
+        footer: menuFooter(),
     });
-    if (isCancel(fileSelected) || fileSelected === '__back__')
+    if (fileSelected === null || fileSelected === '__back__')
         return;
     await viewMarkdownFile(fileSelected);
 }
 // ─── Document viewer ──────────────────────────────────────────────────────────
-async function viewMarkdownFile(filePath) {
+export async function viewMarkdownFile(filePath) {
     const trans = t();
+    ensureMarkedConfigured();
+    const s = createSpinner(`${trans.docs.loadingFile}: ${filePath}`);
     try {
-        ensureMarkedConfigured();
-        const s = createSpinner(`${trans.docs.loadingFile}: ${filePath}`);
         const rawContent = await fetchFileContent(filePath);
         const fingerprint = contentFingerprint(rawContent);
         const cachedRendered = getFreshRender(filePath);
@@ -506,26 +709,25 @@ async function viewMarkdownFile(filePath) {
             await displayWithLess(renderedDoc.rendered, renderedDoc.title, filePath, renderedDoc.readTime, toc);
         }
         const needsBrowser = hasMarkdownTable(rawContent) || hasMermaidBlock(rawContent);
-        const action = await select({
-            message: trans.docs.chooseAction,
+        const action = await runMenu({
+            title: trans.docs.chooseAction,
             options: [
                 { value: 'back', label: trans.docs.backToList },
                 { value: 'browser', label: trans.docs.openBrowser,
                     hint: needsBrowser ? trans.docs.tableHint : undefined },
             ],
+            footer: menuFooter(),
         });
-        if (!isCancel(action) && action === 'browser') {
+        if (action === 'browser') {
             await openDocsInBrowser(filePath);
         }
     }
     catch (err) {
-        error(trans.docs.loadError);
+        s.error(trans.docs.loadError);
         const errMsg = err instanceof Error ? err.message : String(err);
         console.log(chalk.gray(`  ${trans.docs.errorHint}: ${errMsg}`));
-        setVimKeysActive(false);
-        const openBrowser = await confirm({ message: trans.docs.openBrowserPrompt });
-        setVimKeysActive(true);
-        if (!isCancel(openBrowser) && openBrowser) {
+        const openBrowser = await runConfirm({ message: trans.docs.openBrowserPrompt });
+        if (openBrowser === true) {
             await openDocsInBrowser(filePath);
         }
     }
@@ -550,13 +752,11 @@ export async function openDocsInBrowser(path) {
 // ─── Search ────────────────────────────────────────────────────────────────────
 async function searchDocs() {
     const trans = t();
-    setVimKeysActive(false);
-    const query = await text({
+    const query = await runTextInput({
         message: trans.docs.searchPrompt,
         placeholder: trans.docs.searchPlaceholder,
     });
-    setVimKeysActive(true);
-    if (isCancel(query) || !query.trim())
+    if (query === null || !query.trim())
         return;
     const keyword = query.trim().toLowerCase();
     const s = createSpinner(trans.docs.searching);
@@ -568,8 +768,8 @@ async function searchDocs() {
             warning(trans.docs.searchNoResults);
             return;
         }
-        const selected = await select({
-            message: trans.docs.chooseDoc,
+        const selected = await runMenu({
+            title: trans.docs.chooseDoc,
             options: [
                 ...results.map(r => ({
                     value: r.path,
@@ -578,8 +778,9 @@ async function searchDocs() {
                 })),
                 { value: '__back__', label: chalk.dim(trans.docs.returnToMenu) },
             ],
+            footer: menuFooter(),
         });
-        if (isCancel(selected) || selected === '__back__')
+        if (selected === null || selected === '__back__')
             return;
         await viewMarkdownFile(selected);
     }
@@ -589,20 +790,22 @@ async function searchDocs() {
 }
 // ─── Menu ─────────────────────────────────────────────────────────────────────
 export async function showDocsMenu() {
+    await enterScreen(breadcrumb(t().menu.docs));
     let sections = await loadSections();
     if (!sections)
         return;
     while (true) {
         const trans = t();
-        const action = await select({
-            message: trans.docs.chooseCategory,
+        const action = await runMenu({
+            title: trans.docs.chooseCategory,
             options: [
                 ...sections.map(sec => ({ value: sec.key, label: sec.label })),
                 { value: 'search', label: chalk.dim(trans.docs.searchPrompt.replace(':', '')) },
                 { value: 'browser', label: chalk.dim(trans.docs.openBrowser) },
             ],
+            footer: menuFooter(),
         });
-        if (isCancel(action))
+        if (action === null)
             return;
         if (action === 'search') {
             await searchDocs();

package/dist/features/links.js

@@ -3,10 +3,11 @@
  */
 import open from 'open';
 import chalk from 'chalk';
-import { select, isCancel } from '@clack/prompts';
+import { runMenu, menuFooter } from '../core/components/menu.js';
 import { createSpinner } from '../core/ui.js';
 import { URLS } from '../config/data.js';
 import { t } from '../i18n/index.js';
+import { enterScreen, breadcrumb } from '../core/transitions.js';
 async function openUrl(url) {
     const trans = t();
     const s = createSpinner(trans.links.opening);
@@ -21,16 +22,18 @@ async function openUrl(url) {
 }
 export async function showLinksMenu() {
     const trans = t();
-    const selected = await select({
-        message: trans.links.choose,
+    await enterScreen(breadcrumb(trans.menu.links));
+    const selected = await runMenu({
+        title: trans.links.choose,
         options: [
             { value: URLS.homepage, label: trans.links.website },
             { value: URLS.github, label: trans.links.github },
             { value: URLS.roadmap, label: trans.links.roadmap },
             { value: URLS.repair, label: trans.links.repair },
         ],
+        footer: menuFooter(),
     });
-    if (isCancel(selected))
+    if (selected === null)
         return;
     await openUrl(selected);
 }

package/dist/features/schedule-query.js

@@ -0,0 +1,47 @@
+const DAY_MS = 86400000;
+export function currentWeekNumber(weekOneMonday, now) {
+    const base = new Date(`${weekOneMonday}T00:00:00`);
+    const days = Math.floor((now.getTime() - base.getTime()) / DAY_MS);
+    return Math.floor(days / 7) + 1;
+}
+export function campusWeekday(now) {
+    return ((now.getDay() + 6) % 7) + 1;
+}
+export function meetingsInWeek(meetings, week) {
+    return meetings.filter((mtg) => mtg.weeks.includes(week));
+}
+export function meetingsOnDay(meetings, weekday, week) {
+    return meetings
+        .filter((mtg) => mtg.weekday === weekday && mtg.weeks.includes(week))
+        .sort((a, b) => a.startPeriod - b.startPeriod);
+}
+export function periodStartDate(weekOneMonday, week, weekday, period, periods) {
+    const p = periods.find((x) => x.period === period);
+    if (!p)
+        return null;
+    const base = new Date(`${weekOneMonday}T00:00:00`);
+    const date = new Date(base.getTime() + ((week - 1) * 7 + (weekday - 1)) * DAY_MS);
+    const parts = p.start.split(':');
+    date.setHours(Number.parseInt(parts[0] ?? '0', 10), Number.parseInt(parts[1] ?? '0', 10), 0, 0);
+    return date;
+}
+export function nextMeeting(meetings, periods, weekOneMonday, now) {
+    let best = null;
+    for (const meeting of meetings) {
+        for (const week of meeting.weeks) {
+            const start = periodStartDate(weekOneMonday, week, meeting.weekday, meeting.startPeriod, periods);
+            if (start && start.getTime() > now.getTime() && (!best || start.getTime() < best.start.getTime())) {
+                best = { meeting, start };
+            }
+        }
+    }
+    return best;
+}
+/** The meeting occupying a grid cell, whether it starts there or is a later
+ * period of a meeting that started earlier the same day -- one condition
+ * (`startPeriod <= period <= endPeriod`) covers both cases, matching
+ * renderWeekGrid's own starting/continuing lookup so "does this cell have a
+ * meeting" and "what does the grid actually draw there" never disagree. */
+export function meetingAtCursor(meetings, week, cursor) {
+    return meetingsInWeek(meetings, week).find((m) => m.weekday === cursor.weekday && m.startPeriod <= cursor.period && cursor.period <= m.endPeriod) ?? null;
+}