@khorsheed/dsh-library 0.0.0-stage → 0.1.1

package/lib/types/cards.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Knowledge-card identity: when two inputs are the SAME card, and when they
+ * only look alike. The write path decides here, so the coach never has to read
+ * every card before writing one:
+ *
+ * - an exact match on the normalized key (case, width, whitespace, surrounding
+ *   punctuation, a light English plural fold) — against the term AND every
+ *   alias — merges automatically;
+ * - a near match (one key contains the other, or the two share most of their
+ *   words / characters) is held back with up to three candidates, and the
+ *   coach resends with `mergeInto` or `asNew`;
+ * - anything else is a new card.
+ *
+ * Pure functions only — the service owns the lock and the ledger.
+ *
+ * @module @khorsheed/dsh-library/cards
+ */
+import type { LibraryCard } from './types.ts';
+/**
+ * A term's comparison key: NFKC (full-width → half-width), lower case, inner
+ * whitespace collapsed, surrounding punctuation and brackets dropped, each
+ * English word's plural folded.
+ */
+export declare function cardKey(term: string): string;
+/** Every key a card answers to: its term and its aliases. */
+export declare function cardKeys(card: Pick<LibraryCard, 'term' | 'aliases'>): string[];
+/** How alike two keys look, 0..1 (1 = one contains the other). */
+export declare function keySimilarity(a: string, b: string): number;
+/** The threshold above which two keys are a near-duplicate worth asking about. */
+export declare const NEAR_DUPLICATE = 0.6;
+/** The live card an input key matches exactly, when one does. */
+export declare function exactMatch(cards: readonly LibraryCard[], keys: readonly string[]): LibraryCard | undefined;
+/** Up to `limit` live cards that look like the input, most alike first. */
+export declare function nearMatches(cards: readonly LibraryCard[], keys: readonly string[], limit?: number): LibraryCard[];
+/**
+ * Whether a card answers a free-text query: any key or the gloss / user gloss
+ * / a context sentence contains the query's key (the sidebar's ⌕ and the
+ * coach's `library_read · cards` share this).
+ */
+export declare function cardMatchesQuery(card: LibraryCard, query: string): boolean;
+//# sourceMappingURL=cards.d.ts.map

package/lib/types/cards.js

@@ -0,0 +1,111 @@
+/** Fold one English word's regular plural (instalments → instalment, theories → theory). */
+function foldPlural(word) {
+    if (!/^[a-z]+$/.test(word) || word.length <= 3)
+        return word;
+    if (word.endsWith('ies') && word.length > 4)
+        return `${word.slice(0, -3)}y`;
+    if (/(?:s|x|z|ch|sh)es$/.test(word))
+        return word.slice(0, -2);
+    if (word.endsWith('s') && !word.endsWith('ss') && !word.endsWith('us') && !word.endsWith('is'))
+        return word.slice(0, -1);
+    return word;
+}
+/**
+ * A term's comparison key: NFKC (full-width → half-width), lower case, inner
+ * whitespace collapsed, surrounding punctuation and brackets dropped, each
+ * English word's plural folded.
+ */
+export function cardKey(term) {
+    const base = term
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^[\p{P}\p{S}\s]+|[\p{P}\p{S}\s]+$/gu, '');
+    return base.split(' ').map(foldPlural).join(' ');
+}
+/** Every key a card answers to: its term and its aliases. */
+export function cardKeys(card) {
+    return [...new Set([card.term, ...card.aliases].map(cardKey).filter(key => key !== ''))];
+}
+/** The comparison units of a key: English words, or single CJK characters. */
+function units(key) {
+    const out = new Set();
+    for (const token of key.split(/[\s/／、,，·・-]+/)) {
+        if (token === '')
+            continue;
+        if (/[\p{Script=Han}]/u.test(token)) {
+            for (const char of token)
+                if (/[\p{Script=Han}\p{L}\p{N}]/u.test(char))
+                    out.add(char);
+        }
+        else {
+            out.add(token);
+        }
+    }
+    return out;
+}
+/** How alike two keys look, 0..1 (1 = one contains the other). */
+export function keySimilarity(a, b) {
+    if (a === '' || b === '')
+        return 0;
+    if (a === b)
+        return 1;
+    const shorter = a.length <= b.length ? a : b;
+    const longer = shorter === a ? b : a;
+    // Containment only counts when the shorter key is substantial: 「期」 inside
+    // 「不应期」 is noise, 「不应期」 inside 「绝对/相对不应期」 is the same idea.
+    const minimum = /[\p{Script=Han}]/u.test(shorter) ? 2 : 4;
+    if (shorter.length >= minimum && longer.includes(shorter))
+        return 1;
+    const left = units(a);
+    const right = units(b);
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let shared = 0;
+    for (const unit of left)
+        if (right.has(unit))
+            shared += 1;
+    return shared / Math.max(left.size, right.size);
+}
+/** The threshold above which two keys are a near-duplicate worth asking about. */
+export const NEAR_DUPLICATE = 0.6;
+/** The live card an input key matches exactly, when one does. */
+export function exactMatch(cards, keys) {
+    const wanted = new Set(keys);
+    return cards.find(card => card.status !== 'deleted' && cardKeys(card).some(key => wanted.has(key)));
+}
+/** Up to `limit` live cards that look like the input, most alike first. */
+export function nearMatches(cards, keys, limit = 3) {
+    const scored = [];
+    for (const card of cards) {
+        if (card.status === 'deleted')
+            continue;
+        let best = 0;
+        for (const own of cardKeys(card)) {
+            for (const key of keys)
+                best = Math.max(best, keySimilarity(own, key));
+        }
+        if (best >= NEAR_DUPLICATE)
+            scored.push({ card, score: best });
+    }
+    scored.sort((x, y) => y.score - x.score);
+    return scored.slice(0, limit).map(entry => entry.card);
+}
+/**
+ * Whether a card answers a free-text query: any key or the gloss / user gloss
+ * / a context sentence contains the query's key (the sidebar's ⌕ and the
+ * coach's `library_read · cards` share this).
+ */
+export function cardMatchesQuery(card, query) {
+    const needle = cardKey(query);
+    if (needle === '')
+        return true;
+    if (cardKeys(card).some(key => key.includes(needle)))
+        return true;
+    const haystack = [card.gloss, card.userGloss ?? '', ...card.contexts.map(context => context.sentence)]
+        .join('\n')
+        .normalize('NFKC')
+        .toLowerCase();
+    return haystack.includes(query.normalize('NFKC').toLowerCase().trim());
+}

package/lib/types/client/LibraryPane.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The library tab body: the right-Sidebar page, one route stack (see
+ * `client/store.ts`) over the v2 screens —
+ *
+ * - **今日** — reviews due, where each book stands, what the coach just noted,
+ *   the projects;
+ * - **项目** — its textbooks in study order (each with its own path — the
+ *   project carries none), drafts waiting, its cards, its reviews;
+ * - **书** — the roadmap draft waiting for 采用, or the adopted S-shaped path;
+ * - **这一节** — guide / the pages photographed for it / its chapter quizzes;
+ * - **知识卡片** — the learner's own cards, filtered by where they came from;
+ * - **章节考 → 结算** — answered here, choice and fill judged on the spot;
+ * - **复习** — flashcards over the due cards.
+ *
+ * The conversation does what needs the model (adding a book, drafting a path,
+ * composing a quiz, judging open answers): the pane binds the session and
+ * drafts the ask. One layout serves every width (docs/panel-design.md):
+ * `PanelRoot` declares the container, compact rules live in the stylesheet.
+ *
+ * @module @khorsheed/dsh-library/client/LibraryPane
+ */
+import { type ReactNode } from 'react';
+import type { LibraryPaneProps } from './contract.ts';
+/** The tab body. */
+export declare function LibraryPane(props: LibraryPaneProps): ReactNode;
+//# sourceMappingURL=LibraryPane.d.ts.map

package/lib/types/client/LibraryPane.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The library tab body: the right-Sidebar page, one route stack (see
+ * `client/store.ts`) over the v2 screens —
+ *
+ * - **今日** — reviews due, where each book stands, what the coach just noted,
+ *   the projects;
+ * - **项目** — its textbooks in study order (each with its own path — the
+ *   project carries none), drafts waiting, its cards, its reviews;
+ * - **书** — the roadmap draft waiting for 采用, or the adopted S-shaped path;
+ * - **这一节** — guide / the pages photographed for it / its chapter quizzes;
+ * - **知识卡片** — the learner's own cards, filtered by where they came from;
+ * - **章节考 → 结算** — answered here, choice and fill judged on the spot;
+ * - **复习** — flashcards over the due cards.
+ *
+ * The conversation does what needs the model (adding a book, drafting a path,
+ * composing a quiz, judging open answers): the pane binds the session and
+ * drafts the ask. One layout serves every width (docs/panel-design.md):
+ * `PanelRoot` declares the container, compact rules live in the stylesheet.
+ *
+ * @module @khorsheed/dsh-library/client/LibraryPane
+ */
+import { useEffect, useRef, useState } from 'react';
+import { PanelRoot } from '@khorsheed/dsh-client-ui-panel-kit/src/client/index.ts';
+import { BookView } from "./views/book.js";
+import { NodeView } from "./views/station.js";
+import { CardsView } from "./views/cards.js";
+import { NewProjectView, ProjectView, TodayView } from "./views/home.js";
+import { QuizView, ResultView, ReviewView } from "./views/quiz.js";
+import { LessonView } from "./views/lesson.js";
+import css from './LibraryPane.module.css';
+/** The tab body. */
+export function LibraryPane(props) {
+    const route = props.useStore(s => s.stack[s.stack.length - 1]);
+    const { revealed, actions } = props;
+    // A reveal (the session's first library write) lands on its project: taken on
+    // mount when the reveal opened this tab, at once when the tab was already open.
+    useEffect(() => {
+        const land = () => {
+            const projectId = revealed.take();
+            if (projectId !== undefined)
+                actions.openProject(projectId);
+        };
+        land();
+        return revealed.subscribe(land);
+    }, [revealed, actions]);
+    return (_jsxs(PanelRoot, { className: css.root, children: [(() => {
+                switch (route.view) {
+                    case 'today': return _jsx(TodayView, { p: props });
+                    case 'newProject': return _jsx(NewProjectView, { p: props });
+                    case 'project': return _jsx(ProjectView, { p: props, projectId: route.projectId });
+                    case 'resource': return _jsx(BookView, { p: props, projectId: route.projectId, resourceId: route.resourceId });
+                    case 'node': return _jsx(NodeView, { p: props, projectId: route.projectId, resourceId: route.resourceId, nodeId: route.nodeId, tab: route.tab });
+                    case 'lesson': return _jsx(LessonView, { p: props, projectId: route.projectId, resourceId: route.resourceId, nodeId: route.nodeId });
+                    case 'cards': return _jsx(CardsView, { p: props, projectId: route.projectId, filter: route.filter });
+                    case 'quiz': return _jsx(QuizView, { p: props, projectId: route.projectId, resourceId: route.resourceId, quizId: route.quizId });
+                    case 'result': return _jsx(ResultView, { p: props, projectId: route.projectId, resourceId: route.resourceId, result: route.result });
+                    case 'review': return _jsx(ReviewView, { p: props, ...(route.projectId === undefined ? {} : { projectId: route.projectId }) });
+                }
+            })(), _jsx(RecordToast, { p: props })] }));
+}
+/** How often the toast looks for new notes from this session. */
+const TOAST_POLL_MS = 5000;
+/** How long a toast stays up. */
+const TOAST_MS = 10_000;
+/**
+ * 「已记下」: when the coach notes a weak point from THIS session, say so in
+ * the sidebar with an undo — the chat line says it too, this is where the
+ * undo lives. Only notes made after the pane opened are toasted.
+ *
+ * The same timer is the pane's change poll: the host's writes (a landed quiz,
+ * a recorded page) move `latestActivity`, and a move refreshes the open view —
+ * the per-tab watch windows alone lapsed after two minutes and left the tab
+ * stale until a remount.
+ */
+function RecordToast({ p }) {
+    const { t, actions } = p;
+    const since = useRef(new Date().toISOString());
+    const seen = useRef(new Set());
+    const activityAt = useRef();
+    const [record, setRecord] = useState();
+    const [undone, setUndone] = useState(false);
+    useEffect(() => {
+        const poll = () => {
+            if (document.visibilityState !== 'visible')
+                return;
+            void p.latestActivity().then(result => {
+                if (!result.ok)
+                    return;
+                const at = result.value.at;
+                if (at === undefined)
+                    return;
+                // The first read only sets the baseline — the views just loaded fresh.
+                if (activityAt.current !== undefined && at > activityAt.current)
+                    actions.refresh();
+                activityAt.current = at;
+            }, () => { });
+            void p.recentRecords().then(result => {
+                if (!result.ok)
+                    return;
+                const fresh = result.value.records.find(entry => entry.session === String(p.sessionId) && entry.at > since.current && !seen.current.has(entry.at));
+                if (fresh === undefined)
+                    return;
+                seen.current.add(fresh.at);
+                setUndone(false);
+                setRecord(fresh);
+                actions.refresh();
+            }, () => { });
+        };
+        const timer = setInterval(poll, TOAST_POLL_MS);
+        return () => { clearInterval(timer); };
+    }, [p.sessionId]);
+    useEffect(() => {
+        if (record === undefined)
+            return;
+        const timer = setTimeout(() => { setRecord(undefined); }, undone ? 2000 : TOAST_MS);
+        return () => { clearTimeout(timer); };
+    }, [record, undone]);
+    if (record === undefined)
+        return null;
+    return (_jsxs("div", { className: css.toast, role: "status", children: [_jsx("span", { className: css.toastText, children: undone ? t('toast.undone') : t('toast.recorded', { terms: record.title ?? '' }) }), !undone && (_jsx("button", { type: "button", className: css.toastAction, onClick: () => {
+                    void p.undoCards(record.projectId, record.ids ?? [], record.at).then(result => {
+                        if (result.ok && result.value.ok) {
+                            setUndone(true);
+                            actions.refresh();
+                        }
+                    });
+                }, children: t('toast.undo') }))] }));
+}

package/lib/types/client/bind/BindChip.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The session header's library chip: which project — or which of its books —
+ * this learning session works on. The tools default `project` / `book` to it,
+ * the per-turn context names it, and the sidebar's gestures bind it too, so
+ * the chip mostly SHOWS the binding; its menu changes it.
+ *
+ * Shown only in sessions that hold the library tools (the strict half of the
+ * visibility criterion), and it re-reads the binding while visible: the coach
+ * binds through `library_binding` and nothing announces that here.
+ *
+ * @module @khorsheed/dsh-library/client/bind
+ */
+import { type ReactNode } from 'react';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { LibraryBinding, LibraryOutcome, LibraryProjectSummary } from '../../types.ts';
+/** One session's chip face (the header slot injects it per session). */
+export interface LibraryBindInjected {
+    offered: () => boolean;
+    subscribe: (listener: () => void) => () => void;
+    boundTarget: () => Promise<RemoteResult<LibraryBinding | null>>;
+    bindTarget: (binding: LibraryBinding | null) => Promise<RemoteResult<LibraryOutcome<{
+        binding: LibraryBinding | null;
+    }>>>;
+    listProjects: () => Promise<RemoteResult<{
+        projects: LibraryProjectSummary[];
+    }>>;
+}
+export interface LibraryBindChipProps extends LibraryBindInjected {
+    readonly t: TranslateNS<'library'>;
+}
+export declare function LibraryBindChip(props: LibraryBindChipProps): ReactNode;
+//# sourceMappingURL=BindChip.d.ts.map

package/lib/types/client/bind/BindChip.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The session header's library chip: which project — or which of its books —
+ * this learning session works on. The tools default `project` / `book` to it,
+ * the per-turn context names it, and the sidebar's gestures bind it too, so
+ * the chip mostly SHOWS the binding; its menu changes it.
+ *
+ * Shown only in sessions that hold the library tools (the strict half of the
+ * visibility criterion), and it re-reads the binding while visible: the coach
+ * binds through `library_binding` and nothing announces that here.
+ *
+ * @module @khorsheed/dsh-library/client/bind
+ */
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { Menu } from '@deepseek-ai/dsh-client-ui-primitives';
+import { IconChevronDownOutlineMedium } from "../icons.js";
+import css from './BindChip.module.css';
+/** How often the chip re-reads a binding the coach may have moved. */
+const BIND_POLL_MS = 4000;
+/** A binding's menu id. */
+function idOf(binding) {
+    return binding.resourceId === undefined ? `project:${binding.projectId}` : `resource:${binding.projectId}:${binding.resourceId}`;
+}
+export function LibraryBindChip(props) {
+    const shown = useSyncExternalStore(props.subscribe, props.offered);
+    return shown ? _jsx(BindMenu, { ...props }) : null;
+}
+function BindMenu({ t, boundTarget, bindTarget, listProjects }) {
+    const [open, setOpen] = useState(false);
+    const [bound, setBound] = useState(null);
+    const [projects, setProjects] = useState([]);
+    const [failed, setFailed] = useState(false);
+    const reload = useCallback(async () => {
+        const [current, list] = await Promise.all([boundTarget(), listProjects()]);
+        if (current.ok)
+            setBound(current.value);
+        if (list.ok)
+            setProjects(list.value.projects);
+    }, [boundTarget, listProjects]);
+    useEffect(() => { void reload().catch(() => { }); }, [reload]);
+    useEffect(() => {
+        const timer = setInterval(() => {
+            if (document.visibilityState !== 'visible')
+                return;
+            void boundTarget().then(current => { if (current.ok)
+                setBound(current.value); }).catch(() => { });
+        }, BIND_POLL_MS);
+        return () => { clearInterval(timer); };
+    }, [boundTarget]);
+    // A binding to something the chip has not listed yet (the coach just made it): list again.
+    const unseen = bound !== null && !projects.some(project => project.id === bound.projectId
+        && (bound.resourceId === undefined || project.resources.some(resource => resource.id === bound.resourceId)));
+    useEffect(() => {
+        if (!unseen)
+            return;
+        void listProjects().then(list => { if (list.ok)
+            setProjects(list.value.projects); }).catch(() => { });
+    }, [unseen, listProjects]);
+    const pick = async (binding) => {
+        const result = await bindTarget(binding);
+        if (result.ok && result.value.ok) {
+            setBound(result.value.binding);
+            setFailed(false);
+        }
+        else {
+            setFailed(true);
+        }
+    };
+    const project = bound === null ? undefined : projects.find(candidate => candidate.id === bound.projectId);
+    const resource = bound?.resourceId === undefined ? undefined : project?.resources.find(candidate => candidate.id === bound.resourceId);
+    const title = resource?.title ?? project?.name;
+    const items = [
+        { type: 'label', id: 'heading', text: t('bind.heading') },
+        ...projects.length === 0
+            ? [{ id: 'empty', label: t('bind.empty'), disabled: true }]
+            : projects.flatMap((entry) => [
+                { id: `project:${entry.id}`, label: t('bind.wholeProject', { project: entry.name }) },
+                // Only a thick entry (a book, a course) is bindable — a thin link carries no path.
+                ...entry.resources.filter(entryResource => entryResource.kind === 'book' || entryResource.kind === 'course').map(entryResource => ({ id: `resource:${entry.id}:${entryResource.id}`, label: `　${entryResource.title}` })),
+            ]),
+        ...bound === null ? [] : [
+            { type: 'separator', id: 'sep' },
+            { id: 'unbind', label: t('bind.unbind') },
+        ],
+    ];
+    return (_jsx(Menu, { open: open, portal: true, dense: true, items: items, ...bound === null ? {} : { selectedId: idOf(bound) }, onSelect: id => {
+            setOpen(false);
+            if (id === 'unbind')
+                void pick(null);
+            else if (id.startsWith('project:'))
+                void pick({ projectId: id.slice('project:'.length) });
+            else if (id.startsWith('resource:')) {
+                const [, projectId, resourceId] = id.split(':');
+                if (projectId !== undefined && resourceId !== undefined)
+                    void pick({ projectId, resourceId });
+            }
+        }, onClose: () => { setOpen(false); }, anchor: (_jsxs("button", { type: "button", className: css.trigger, "data-bound": bound !== null, "aria-label": t('bind.aria'), "aria-haspopup": "menu", "aria-expanded": open, title: failed ? t('bind.failed') : undefined, onClick: () => {
+                if (!open)
+                    void reload().catch(() => { });
+                setOpen(value => !value);
+            }, children: [_jsx("span", { className: css.label, children: failed ? t('bind.failed') : title === undefined ? t('bind.unbound') : t('bind.bound', { title }) }), _jsx(IconChevronDownOutlineMedium, { size: 12 })] })) }));
+}

package/lib/types/client/contract.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Compile-time contract between the library's browser half and its host half.
+ *
+ * Nothing here executes: this module holds the shapes only, so a change in the
+ * Remote surface or in the injected business face breaks compilation at the
+ * components that consume them instead of at runtime.
+ *
+ * @module @khorsheed/dsh-library/client/contract
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { GlobalStandardProps, InjectFace, PropsLocale, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { LibraryAssessResult, LibraryAssessment, LibraryAttempt, LibraryBinding, LibraryCard, LibraryCardQuery, LibraryProjectPatch, LibraryEvent, LibraryOutcome, LibraryPage, LibraryProject, LibraryProjectSummary, LibraryResource, LibraryReviewRating, LibraryRoadmap, LibraryTemplate, LibraryVerdict } from '../types.ts';
+import type { createLibraryStore } from './store.ts';
+import type { RevealedProject } from './reveal.ts';
+export type { RemoteResult };
+/** A Remote call's answer: the protocol envelope around a domain outcome. */
+type Answer<T> = Promise<RemoteResult<LibraryOutcome<T>>>;
+/**
+ * The business face every library surface receives from its registration:
+ * the wire verbs straight off the Remote, plus the two session gestures the
+ * pane cannot perform itself (priming the conversation, binding the session).
+ */
+export interface LibraryPaneInjected {
+    listProjects: () => Promise<RemoteResult<{
+        projects: LibraryProjectSummary[];
+    }>>;
+    getProject: (id: string) => Answer<{
+        project: LibraryProjectSummary;
+        resources: LibraryResource[];
+    }>;
+    createProject: (request: {
+        name: string;
+        template: LibraryTemplate;
+        goal?: string;
+    }) => Answer<{
+        project: LibraryProject;
+    }>;
+    updateProject: (projectId: string, patch: LibraryProjectPatch) => Answer<{
+        project: LibraryProject;
+    }>;
+    /** Delete a project and everything it holds (shelf, paths, pages, cards) — irreversible. */
+    deleteProject: (projectId: string) => Answer<{
+        id: string;
+    }>;
+    /** Remove a shelf entry: its registration, roadmaps and pages go; its cards stay, unhung. */
+    removeResource: (projectId: string, resourceId: string) => Answer<{
+        id: string;
+    }>;
+    /** Switch a textbook between 知识型 and 材料型. */
+    setBookKind: (projectId: string, resourceId: string, bookKind: 'knowledge' | 'material') => Answer<{
+        resource: LibraryResource;
+    }>;
+    /** Move a textbook to another place in the study order (the rest shift). */
+    moveResource: (projectId: string, resourceId: string, seq: number) => Answer<{
+        resources: LibraryResource[];
+    }>;
+    getRoadmap: (projectId: string, resourceId: string) => Promise<RemoteResult<{
+        roadmap?: LibraryRoadmap;
+        draft?: LibraryRoadmap;
+    }>>;
+    adoptRoadmap: (projectId: string, resourceId: string) => Answer<{
+        roadmap: LibraryRoadmap;
+    }>;
+    discardDraft: (projectId: string, resourceId: string) => Answer<{
+        resourceId: string;
+    }>;
+    markNodeRead: (projectId: string, resourceId: string | undefined, nodeId: string) => Answer<{
+        roadmap: LibraryRoadmap;
+        unlocked: string[];
+    }>;
+    listPages: (projectId: string, resourceId: string, nodeId?: string) => Promise<RemoteResult<{
+        pages: LibraryPage[];
+    }>>;
+    readPagePhoto: (projectId: string, pageId: string) => Answer<{
+        data: string;
+        mediaType: string;
+    }>;
+    /** A project's shelf, thick and thin. */
+    listResources: (projectId: string) => Promise<RemoteResult<{
+        resources: LibraryResource[];
+    }>>;
+    /** A station's acceptance history, newest first. */
+    listAttempts: (projectId: string, nodeId?: string, assessmentId?: string) => Promise<RemoteResult<{
+        attempts: LibraryAttempt[];
+    }>>;
+    listCards: (query: LibraryCardQuery) => Promise<RemoteResult<{
+        cards: LibraryCard[];
+        total: number;
+    }>>;
+    dueCards: (projectId?: string) => Promise<RemoteResult<{
+        cards: (LibraryCard & {
+            projectId: string;
+        })[];
+    }>>;
+    editCard: (projectId: string, cardId: string, patch: {
+        status?: LibraryCard['status'];
+        gloss?: string;
+    }) => Answer<{
+        card: LibraryCard;
+    }>;
+    undoCards: (projectId: string, ids: readonly string[], at: string) => Answer<{
+        removed: number;
+        reverted: number;
+    }>;
+    reviewCard: (projectId: string, cardId: string, rating: LibraryReviewRating) => Answer<{
+        card: LibraryCard;
+    }>;
+    listAssessments: (projectId: string, resourceId?: string, nodeId?: string, type?: 'quiz' | 'practice') => Promise<RemoteResult<{
+        assessments: LibraryAssessment[];
+    }>>;
+    getAssessment: (projectId: string, assessmentId: string) => Answer<{
+        assessment: LibraryAssessment;
+    }>;
+    putAttempt: (projectId: string, assessmentId: string, verdicts: readonly LibraryVerdict[]) => Answer<LibraryAssessResult>;
+    /** The newest knowledge-point state changes (今日 「最近的变化」). */
+    recentChanges: () => Promise<RemoteResult<{
+        changes: (LibraryEvent & {
+            projectId: string;
+            projectName: string;
+        })[];
+    }>>;
+    /** 订正: a retake paper over a station's open misses (all, or the keys named). */
+    /** No station: the whole project's open misses (今日复习). */
+    createRetake: (projectId: string, resourceId?: string, nodeId?: string, keys?: readonly string[]) => Answer<{
+        assessment: LibraryAssessment;
+    }>;
+    recentRecords: () => Promise<RemoteResult<{
+        records: (LibraryEvent & {
+            projectId: string;
+            projectName: string;
+        })[];
+    }>>;
+    /** The newest event's timestamp anywhere — the pane's change poll (host-side writes otherwise surface only on remount). */
+    latestActivity: () => Promise<RemoteResult<{
+        at?: string;
+        session?: {
+            id: string;
+            at: string;
+        };
+    }>>;
+    /** The session's binding, when it has one. */
+    boundTarget: () => Promise<RemoteResult<LibraryBinding | null>>;
+    /** The project a reveal asks the pane to land on, taken once (see reveal.ts). */
+    revealed: Pick<RevealedProject, 'take' | 'subscribe'>;
+    /** Bind the session (null unbinds). */
+    bindTarget: (binding: LibraryBinding | null) => Answer<{
+        binding: LibraryBinding | null;
+    }>;
+    /**
+     * Prime the session's conversation with a request (the coach does the
+     * work; the pane drafts the ask). False when the session has no input.
+     */
+    primeConversation: (text: string) => boolean;
+    /**
+     * Send a message in the session for the learner (it shows in the chat as
+     * theirs). False when the session has no input or is busy admitting.
+     */
+    sendMessage: (text: string) => boolean;
+    /** Send a photo with a message in the session for the learner (the 拍照 gesture). */
+    sendPhoto: (file: File, text: string) => boolean;
+}
+/** Full props of the library pane: the seat's session + store + locale + face. */
+export type LibraryPaneProps = {
+    sessionId: SessionId;
+} & GlobalStandardProps & PropsStore<ReturnType<typeof createLibraryStore>> & InjectFace<LibraryPaneInjected> & PropsLocale<'library'>;
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/contract.js

@@ -0,0 +1 @@
+export {};

package/lib/types/client/covers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Covers — what a station draws on — as chips with their provenance badges,
+ * plus the client-side mirror of the host's evidence gate (display only; the
+ * host enforces, `service.ts`'s coversVerbatimBlocker).
+ *
+ * v5: a cover is one shape — `{ ref, locator? }` — and the ref describes
+ * itself: a shelf resource's id, a bare url, or `topic:…` for coached
+ * teaching.
+ *
+ * @module @khorsheed/dsh-library/client/covers
+ */
+import type { ReactNode } from 'react';
+import { type LibraryNodeCover, type LibraryResource } from '../types.ts';
+import type { LibraryPaneProps } from './contract.ts';
+/** What labeling a cover needs: the project's shelf (books included). */
+export interface CoverContext {
+    readonly resources: readonly LibraryResource[];
+}
+type T = LibraryPaneProps['t'];
+/** A cover's one-line label. */
+export declare function coverLabel(cover: LibraryNodeCover, context: CoverContext, t: T): string;
+/** A cover's provenance badge (absent on a shelf resource — its tocSource already records it). */
+export declare function ProvenanceBadge({ cover, t }: {
+    cover: LibraryNodeCover;
+    t: T;
+}): ReactNode;
+/** One station's covers as a chip row: label + provenance badge each. */
+export declare function CoverChips({ covers, context, t }: {
+    covers: readonly LibraryNodeCover[];
+    context: CoverContext;
+    t: T;
+}): ReactNode;
+/** One line for a path row: 「《书》 第 3-5 章 · 链接 ×2 · 讲授 ×1」. */
+export declare function summarizeCovers(covers: readonly LibraryNodeCover[], context: CoverContext, t: T): string;
+export {};
+//# sourceMappingURL=covers.d.ts.map