@khorsheed/dsh-library 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,63 @@
+/**
+ * The library's visual identity pieces (M4): a project's color and glyph,
+ * and a book's generated cover. A project's color rides the `--pc` custom
+ * property (set by `data-color` in the stylesheet), so every surface under it
+ * — its card, its header band, its books' covers and its path — inherits one
+ * hue without passing it around.
+ *
+ * @module @khorsheed/dsh-library/client/look
+ */
+import type { ReactNode } from 'react';
+import type { LibraryColor, LibraryIcon, LibraryProject } from '../types.ts';
+/** A project's color, with the template default for projects made before M4. */
+export declare function colorOf(project: Pick<LibraryProject, 'color' | 'template'>): LibraryColor;
+/** A project's icon, with the template default. */
+export declare function iconOf(project: Pick<LibraryProject, 'icon' | 'template'>): LibraryIcon;
+/** A project's glyph tile (white strokes on its color). */
+export declare function ProjectGlyph({ icon, size }: {
+    icon: LibraryIcon;
+    size?: number;
+}): ReactNode;
+/** Just the glyph's strokes, for pickers. */
+export declare function GlyphStrokes({ icon }: {
+    icon: LibraryIcon;
+}): ReactNode;
+/**
+ * A cover's abbreviation: the coach's, else derived — CJK titles keep their
+ * first two characters plus any number (剑桥雅思 5 → 剑5), Latin titles their
+ * capitalized initials plus any number (Principles of Neural Science → PNS).
+ */
+export declare function shortOf(book: {
+    readonly title: string;
+    readonly short?: string | undefined;
+}): string;
+/** A generated cover: the project's hue (shaded per shelf position), the abbreviation, the kind. */
+export declare function Cover({ book, shade, size, kindLabel }: {
+    book: {
+        readonly title: string;
+        readonly short?: string | undefined;
+        readonly edition?: string | undefined;
+    };
+    shade?: number;
+    size?: 'shelf' | 'mini' | 'badge' | 'card' | 'hero';
+    kindLabel?: string | undefined;
+}): ReactNode;
+/** The display shape a cover tile needs, lifted off a shelf resource's meta. */
+export declare function coverOf(resource: {
+    readonly title: string;
+    readonly meta?: {
+        readonly short?: string;
+        readonly edition?: string;
+    } | undefined;
+}): {
+    title: string;
+    short?: string;
+    edition?: string;
+};
+/** A circular progress ring in the project's color. */
+export declare function Ring({ percent, label, title }: {
+    percent: number;
+    label?: string | undefined;
+    title?: string | undefined;
+}): ReactNode;
+//# sourceMappingURL=look.d.ts.map

package/lib/types/client/look.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { TEMPLATE_LOOK } from "../types.js";
+import css from './LibraryPane.module.css';
+/** A project's color, with the template default for projects made before M4. */
+export function colorOf(project) {
+    return project.color ?? TEMPLATE_LOOK[project.template].color;
+}
+/** A project's icon, with the template default. */
+export function iconOf(project) {
+    return project.icon ?? TEMPLATE_LOOK[project.template].icon;
+}
+/** The 24×24 strokes of each preset icon. */
+const GLYPHS = {
+    globe: _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "M3 12h18M12 3a14 14 0 0 1 0 18M12 3a14 14 0 0 0 0 18" })] }),
+    brain: _jsxs(_Fragment, { children: [_jsx("path", { d: "M9 4a3 3 0 0 0-3 3v1a3 3 0 0 0-2 5 3 3 0 0 0 2 5v1a3 3 0 0 0 6 0V5a3 3 0 0 0-3-1z" }), _jsx("path", { d: "M15 4a3 3 0 0 1 3 3v1a3 3 0 0 1 2 5 3 3 0 0 1-2 5v1a3 3 0 0 1-6 0" })] }),
+    book: _jsxs(_Fragment, { children: [_jsx("path", { d: "M4 5a2 2 0 0 1 2-2h13v16H6a2 2 0 0 0-2 2z" }), _jsx("path", { d: "M4 19V5" })] }),
+    flask: _jsx(_Fragment, { children: _jsx("path", { d: "M9 3h6M10 3v6l-5 9a2 2 0 0 0 2 3h10a2 2 0 0 0 2-3l-5-9V3" }) }),
+    atom: _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "1.5" }), _jsx("ellipse", { cx: "12", cy: "12", rx: "9", ry: "4" }), _jsx("ellipse", { cx: "12", cy: "12", rx: "9", ry: "4", transform: "rotate(60 12 12)" }), _jsx("ellipse", { cx: "12", cy: "12", rx: "9", ry: "4", transform: "rotate(120 12 12)" })] }),
+    leaf: _jsxs(_Fragment, { children: [_jsx("path", { d: "M5 19c0-8 6-14 15-14 0 9-6 15-14 15" }), _jsx("path", { d: "M5 19 13 11" })] }),
+    pen: _jsxs(_Fragment, { children: [_jsx("path", { d: "M4 20l4-1 11-11-3-3L5 16z" }), _jsx("path", { d: "M14 6l3 3" })] }),
+    music: _jsxs(_Fragment, { children: [_jsx("path", { d: "M9 18V5l11-2v13" }), _jsx("circle", { cx: "6", cy: "18", r: "3" }), _jsx("circle", { cx: "17", cy: "16", r: "3" })] }),
+    scale: _jsx(_Fragment, { children: _jsx("path", { d: "M12 3v18M5 7h14M7 7l-3 7a3 3 0 0 0 6 0zM17 7l-3 7a3 3 0 0 0 6 0z" }) }),
+    chart: _jsxs(_Fragment, { children: [_jsx("path", { d: "M4 20V4M4 20h16" }), _jsx("path", { d: "M8 16v-4M12 16V8M16 16v-6" })] }),
+    code: _jsx(_Fragment, { children: _jsx("path", { d: "M8 7l-5 5 5 5M16 7l5 5-5 5" }) }),
+    compass: _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "M15.5 8.5l-2 5-5 2 2-5z" })] }),
+};
+/** A project's glyph tile (white strokes on its color). */
+export function ProjectGlyph({ icon, size = 34 }) {
+    return (_jsx("span", { className: css.glyph, style: { width: size, height: size }, "aria-hidden": "true", children: _jsx("svg", { viewBox: "0 0 24 24", children: GLYPHS[icon] }) }));
+}
+/** Just the glyph's strokes, for pickers. */
+export function GlyphStrokes({ icon }) {
+    return _jsx("svg", { viewBox: "0 0 24 24", className: css.glyphStrokes, "aria-hidden": "true", children: GLYPHS[icon] });
+}
+/**
+ * A cover's abbreviation: the coach's, else derived — CJK titles keep their
+ * first two characters plus any number (剑桥雅思 5 → 剑5), Latin titles their
+ * capitalized initials plus any number (Principles of Neural Science → PNS).
+ */
+export function shortOf(book) {
+    if (book.short !== undefined && book.short !== '')
+        return book.short;
+    const number = /\d+/.exec(book.title)?.[0] ?? '';
+    if (/[\p{Script=Han}]/u.test(book.title))
+        return `${book.title.replace(/[\s\d（(].*$/, '').slice(0, 1)}${number || book.title.slice(1, 2)}`;
+    const initials = book.title.split(/\s+/).filter(word => /^[A-Z]/.test(word)).map(word => word[0]).join('');
+    return `${initials.slice(0, 4)}${number}`.slice(0, 5) || book.title.slice(0, 3);
+}
+/** A generated cover: the project's hue (shaded per shelf position), the abbreviation, the kind. */
+export function Cover({ book, shade = 0, size = 'shelf', kindLabel }) {
+    return (_jsxs("span", { className: css.cover, "data-size": size, "data-shade": String(shade % 3), "aria-hidden": size !== 'shelf', children: [size !== 'mini' && (_jsxs("span", { className: css.coverHead, children: [_jsx("span", { className: css.coverShort, children: shortOf(book) }), size === 'shelf' && kindLabel !== undefined && _jsx("span", { className: css.coverKind, children: kindLabel })] })), size === 'shelf' && _jsx("span", { className: css.coverTitle, children: book.edition === undefined ? book.title : `${book.title} · ${book.edition}` })] }));
+}
+/** The display shape a cover tile needs, lifted off a shelf resource's meta. */
+export function coverOf(resource) {
+    return {
+        title: resource.title,
+        ...(resource.meta?.short === undefined ? {} : { short: resource.meta.short }),
+        ...(resource.meta?.edition === undefined ? {} : { edition: resource.meta.edition }),
+    };
+}
+/** A circular progress ring in the project's color. */
+export function Ring({ percent, label, title }) {
+    return (_jsx("span", { className: css.ring, "data-labelled": label === undefined ? undefined : 'true', style: { ['--pct']: `${Math.max(0, Math.min(100, percent))}%` }, role: "img", "aria-label": title ?? `${percent}%`, title: title, children: _jsxs("span", { children: [percent, "%", label !== undefined && _jsx("small", { children: label })] }) }));
+}

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

@@ -0,0 +1,24 @@
+/**
+ * TeX rendering for the pane: $…$ / $$…$$ segments in coach-authored text
+ * (quiz prompts, options, explanations, station notes) render as MathML —
+ * browser-native, so no KaTeX fonts or CSS need bundling.
+ *
+ * @module @khorsheed/dsh-library/client/math
+ */
+import { type ReactNode } from 'react';
+/** One TeX segment, rendered to MathML; falls back to the source text. */
+export declare function Tex({ tex, block }: {
+    tex: string;
+    block?: boolean;
+}): ReactNode;
+/** Text with its $…$ / $$…$$ segments rendered; everything else plain. */
+export declare function MathText({ text }: {
+    text: string;
+}): ReactNode;
+/** Split text into plain runs and $…$ (inline) / $$…$$ (block) TeX segments. */
+export declare function splitMath(text: string): readonly {
+    text?: string;
+    tex?: string;
+    block?: boolean;
+}[];
+//# sourceMappingURL=math.d.ts.map

package/lib/types/client/math.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * TeX rendering for the pane: $…$ / $$…$$ segments in coach-authored text
+ * (quiz prompts, options, explanations, station notes) render as MathML —
+ * browser-native, so no KaTeX fonts or CSS need bundling.
+ *
+ * @module @khorsheed/dsh-library/client/math
+ */
+import { Fragment, useMemo } from 'react';
+import katex from 'katex';
+import css from './LibraryPane.module.css';
+/** One TeX segment, rendered to MathML; falls back to the source text. */
+export function Tex({ tex, block }) {
+    const html = useMemo(() => {
+        try {
+            return katex.renderToString(tex, { output: 'mathml', throwOnError: false, displayMode: block === true });
+        }
+        catch {
+            return undefined;
+        }
+    }, [tex, block]);
+    if (html === undefined)
+        return _jsx("code", { children: tex });
+    return _jsx("span", { className: block === true ? css.mathBlock : undefined, dangerouslySetInnerHTML: { __html: html } });
+}
+/** Text with its $…$ / $$…$$ segments rendered; everything else plain. */
+export function MathText({ text }) {
+    const parts = useMemo(() => splitMath(text), [text]);
+    return (_jsx(_Fragment, { children: parts.map((part, at) => part.tex === undefined
+            ? _jsx(Fragment, { children: part.text }, at)
+            : _jsx(Tex, { tex: part.tex, ...(part.block === undefined ? {} : { block: part.block }) }, at)) }));
+}
+/** Split text into plain runs and $…$ (inline) / $$…$$ (block) TeX segments. */
+export function splitMath(text) {
+    const parts = [];
+    const pattern = /\$\$([\s\S]+?)\$\$|\$([^$\n]+)\$/g;
+    let at = 0;
+    for (const match of text.matchAll(pattern)) {
+        if (match.index > at)
+            parts.push({ text: text.slice(at, match.index) });
+        parts.push({ tex: match[1] ?? match[2] ?? '', block: match[1] !== undefined });
+        at = match.index + match[0].length;
+    }
+    if (at < text.length)
+        parts.push({ text: text.slice(at) });
+    return parts;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The mistake ledger's shared read: every quiz's latest sitting (attempts
+ * arrive newest first), and the failed or flagged questions off it. One
+ * collection, three filters — the station's 错题 list, its 其他站 shelf and
+ * the project page's entry count are the same rows scoped differently, so
+ * the two views can never disagree about what counts as missed.
+ *
+ * @module @khorsheed/dsh-library/client/mistakes
+ */
+import type { LibraryAssessment, LibraryAttempt, LibraryQuizQuestion } from '../types.ts';
+/** One failed (or flagged) question off a paper's latest sitting. */
+export interface MissedRow {
+    readonly quiz: LibraryAssessment;
+    readonly question: LibraryQuizQuestion;
+    readonly at: string;
+}
+/** Every failed, non-voided question — pass the project's quizzes for the cross-station shelf, one station's for its own list. */
+export declare function collectMissed(attempts: readonly LibraryAttempt[], quizzes: readonly LibraryAssessment[]): MissedRow[];
+/** Every question the learner flagged 「这题有问题」 (void — counted for nothing). */
+export declare function collectVoided(attempts: readonly LibraryAttempt[], quizzes: readonly LibraryAssessment[]): MissedRow[];
+//# sourceMappingURL=mistakes.d.ts.map

package/lib/types/client/mistakes.js

@@ -0,0 +1,28 @@
+/** The rows one predicate collects: each quiz contributes its newest sitting only. */
+function latestSittingRows(attempts, quizzes, keep) {
+    const byId = new Map(quizzes.map(quiz => [quiz.id, quiz]));
+    const seen = new Set();
+    const rows = [];
+    for (const attempt of attempts) {
+        const quiz = byId.get(attempt.assessmentId ?? '');
+        if (quiz === undefined || seen.has(quiz.id))
+            continue;
+        seen.add(quiz.id);
+        for (const verdict of attempt.verdicts) {
+            if (!keep(verdict))
+                continue;
+            const question = quiz.questions?.find(candidate => candidate.id === verdict.task);
+            if (question !== undefined)
+                rows.push({ quiz, question, at: attempt.at });
+        }
+    }
+    return rows;
+}
+/** Every failed, non-voided question — pass the project's quizzes for the cross-station shelf, one station's for its own list. */
+export function collectMissed(attempts, quizzes) {
+    return latestSittingRows(attempts, quizzes, verdict => !verdict.pass && verdict.void !== true);
+}
+/** Every question the learner flagged 「这题有问题」 (void — counted for nothing). */
+export function collectVoided(attempts, quizzes) {
+    return latestSittingRows(attempts, quizzes, verdict => verdict.void === true);
+}

package/lib/types/client/preset-visibility.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The preset-composition visibility of the library right-Sidebar tab type
+ * (proposal 2026-10-06-library-learning-mode; the canvas double check,
+ * `packages/canvas/src/client/preset-visibility.ts`, inlined per the
+ * visibility doc's keep-copies-inline rule). The tab is the entry to a
+ * cross-session workspace, so the criterion is NOT "did this session's preset
+ * grant the row" alone — it answers "can THIS session reach the library
+ * tools", which has two grant paths because the `./tool` entry mounts in two
+ * legal shapes:
+ *
+ * 1. **Profile-root mount** (a deployment that grants every session the
+ *   library tools): the inventory's `entries` carry an ENABLED
+ *   `@khorsheed/dsh-library/tool` row → visible for every session.
+ * 2. **Preset mount** (the learning-mode recipe: the row named in the target
+ *   preset's plugins): visible exactly when the CURRENT session's preset
+ *   composition names that row.
+ *
+ * Checking only path 2 re-runs the 2026-09-16 canvas incident: the
+ * composition data is perfectly readable, the row simply is not IN any
+ * preset, so the verdict would be a permanent hide. Every unreadable path
+ * therefore fails OPEN (visible): no pluginInventory namespace, a
+ * pending/failed RPC, a missing or `broken` preset group, a session with no
+ * preset, and the no-session home state (a frame-level surface has no preset
+ * input until a session exists — showing there is the neutral state, not a
+ * leak).
+ *
+ * Hidden means NOT registered: the guide enumerates the tab-type registry,
+ * opened tabs are stored per session (an ungranted session's layout never
+ * held one), and a kind with no registrant renders the host's designed
+ * `tab.unavailable` fallback ("a real state, not a defect").
+ * @module @khorsheed/dsh-library/client/preset-visibility
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+/** The criterion's row: the library tools/prompt/skill composition entry. */
+export declare const LIBRARY_TOOL_ROW_MODULE = "@khorsheed/dsh-library/tool";
+/**
+ * Minimal structural mirror of the official pluginInventory snapshot — the
+ * entries slice (root grants) plus the agentPresets slice (preset grants),
+ * duck-typed and host-version tolerant.
+ */
+export interface LibraryPluginInventorySnapshot {
+    readonly entries?: readonly {
+        readonly moduleName: string;
+        readonly enabled?: boolean;
+    }[];
+    readonly agentPresets?: readonly {
+        readonly id: string;
+        readonly broken?: string;
+        readonly rows: readonly {
+            readonly moduleName: string;
+            readonly enabled?: boolean;
+        }[];
+    }[];
+}
+/**
+ * The tab's visibility controller: one inventory fetch per page (composition
+ * data changes only with preset files, which a reload re-reads anyway),
+ * re-evaluated by the toggle on every session switch.
+ */
+export declare class LibraryTabVisibility {
+    private readonly ctx;
+    /** The inventory answer; null while pending/failed and on namespace-less hosts. */
+    private composition;
+    private readonly listeners;
+    /**
+     * @param ctx - client root context.
+     * @param pluginInventory - the OFFICIAL namespace, probed through ctx.get
+     *   (never injected — declaring it would pend the whole client on a host
+     *   without it, and the criterion must fail open there).
+     */
+    constructor(ctx: Context, pluginInventory: {
+        list: () => Promise<RemoteResult<LibraryPluginInventorySnapshot>>;
+    } | undefined);
+    show(sessionId: SessionId | undefined): boolean;
+    /**
+     * The binding chip's stricter question: does THIS session hold the library
+     * tools? Unlike the tab (fail-open), an unanswered inventory or an unknown
+     * preset answers no — a chip in every session's header is noise, and the
+     * tab stays reachable either way.
+     */
+    grants(sessionId: SessionId | undefined): boolean;
+    /** Subscribe to criterion-input changes (session switches, the inventory answer). */
+    subscribe(listener: () => void): () => void;
+    private notify;
+}
+/**
+ * The tab type's registration toggle (the room template): registers exactly
+ * while the criterion passes for the current session and disposes otherwise.
+ * Unlike the keyed-slot consumers, the sidebarRightTabs registry is a direct
+ * inject — no slot-declaration wait, so the toggle is ready immediately.
+ */
+export declare class RegistrationToggle {
+    private readonly register;
+    private readonly show;
+    private dispose;
+    private ready;
+    /**
+     * @param register - mounts the entry and returns its disposer.
+     * @param show - the current decision (re-read on every sync).
+     */
+    constructor(register: () => () => void, show: () => boolean);
+    /** The registry is reachable — decisions may register now. */
+    setReady(ready: boolean): void;
+    /** Re-evaluate: register while shown and ready, dispose otherwise. */
+    sync(): void;
+}
+//# sourceMappingURL=preset-visibility.d.ts.map

package/lib/types/client/preset-visibility.js

@@ -0,0 +1,123 @@
+/** The criterion's row: the library tools/prompt/skill composition entry. */
+export const LIBRARY_TOOL_ROW_MODULE = '@khorsheed/dsh-library/tool';
+/** The current session's agent preset, the dual read per host line. */
+function presetOf(row) {
+    const value = row
+        ?.projectionValues?.agentPreset
+        ?? row?.agentPreset;
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * The tab's visibility controller: one inventory fetch per page (composition
+ * data changes only with preset files, which a reload re-reads anyway),
+ * re-evaluated by the toggle on every session switch.
+ */
+export class LibraryTabVisibility {
+    ctx;
+    /** The inventory answer; null while pending/failed and on namespace-less hosts. */
+    composition = null;
+    listeners = new Set();
+    /**
+     * @param ctx - client root context.
+     * @param pluginInventory - the OFFICIAL namespace, probed through ctx.get
+     *   (never injected — declaring it would pend the whole client on a host
+     *   without it, and the criterion must fail open there).
+     */
+    constructor(ctx, pluginInventory) {
+        this.ctx = ctx;
+        if (pluginInventory !== undefined) {
+            void pluginInventory.list().then(result => {
+                if (!result.ok)
+                    return;
+                this.composition = result.value ?? null;
+                this.notify();
+            }).catch(() => { });
+        }
+        // Session switches re-decide the tab type's registration (the guide
+        // enumerates registrations, not components).
+        ctx.effect(() => ctx.sessions.list.subscribe(() => { this.notify(); }), 'library: tab visibility session follower');
+    }
+    show(sessionId) {
+        if (this.composition === null)
+            return true;
+        // Path 1: a root-mounted tool row grants the tools to every session —
+        // a deployment-level constant, checked before any per-session question.
+        if (this.composition.entries?.some(row => row.moduleName === LIBRARY_TOOL_ROW_MODULE && row.enabled === true) === true)
+            return true;
+        if (sessionId === undefined)
+            return true;
+        const preset = presetOf(this.ctx.sessions.list.getSnapshot().byId[sessionId]);
+        if (preset === undefined)
+            return true;
+        const group = this.composition.agentPresets?.find(candidate => candidate.id === preset);
+        if (group === undefined || group.broken !== undefined)
+            return true;
+        // Path 2: the preset-mounted row grants this session.
+        return group.rows.some(row => row.moduleName === LIBRARY_TOOL_ROW_MODULE && row.enabled !== false);
+    }
+    /**
+     * The binding chip's stricter question: does THIS session hold the library
+     * tools? Unlike the tab (fail-open), an unanswered inventory or an unknown
+     * preset answers no — a chip in every session's header is noise, and the
+     * tab stays reachable either way.
+     */
+    grants(sessionId) {
+        if (this.composition === null || sessionId === undefined)
+            return false;
+        if (this.composition.entries?.some(row => row.moduleName === LIBRARY_TOOL_ROW_MODULE && row.enabled === true) === true)
+            return true;
+        const preset = presetOf(this.ctx.sessions.list.getSnapshot().byId[sessionId]);
+        const group = preset === undefined ? undefined : this.composition.agentPresets?.find(candidate => candidate.id === preset);
+        return group?.rows.some(row => row.moduleName === LIBRARY_TOOL_ROW_MODULE && row.enabled !== false) === true;
+    }
+    /** Subscribe to criterion-input changes (session switches, the inventory answer). */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * The tab type's registration toggle (the room template): registers exactly
+ * while the criterion passes for the current session and disposes otherwise.
+ * Unlike the keyed-slot consumers, the sidebarRightTabs registry is a direct
+ * inject — no slot-declaration wait, so the toggle is ready immediately.
+ */
+export class RegistrationToggle {
+    register;
+    show;
+    dispose;
+    ready = false;
+    /**
+     * @param register - mounts the entry and returns its disposer.
+     * @param show - the current decision (re-read on every sync).
+     */
+    constructor(register, show) {
+        this.register = register;
+        this.show = show;
+    }
+    /** The registry is reachable — decisions may register now. */
+    setReady(ready) {
+        this.ready = ready;
+        if (!ready && this.dispose !== undefined) {
+            this.dispose();
+            this.dispose = undefined;
+        }
+        this.sync();
+    }
+    /** Re-evaluate: register while shown and ready, dispose otherwise. */
+    sync() {
+        if (!this.ready)
+            return;
+        if (this.show()) {
+            this.dispose ??= this.register();
+        }
+        else if (this.dispose !== undefined) {
+            this.dispose();
+            this.dispose = undefined;
+        }
+    }
+}

package/lib/types/client/quiz-drafts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Quiz drafts: the learner's in-progress answers survive leaving the paper
+ * (back to the station, a closed sidebar, a reload). Stored in localStorage
+ * per quiz id — a draft is local by definition (never ledgered until 交卷),
+ * so no host write is involved; the entry clears when the sitting lands.
+ *
+ * @module @khorsheed/dsh-library/client/quiz-drafts
+ */
+/** One question's saved state in the draft. */
+export interface QuizDraftAnswer {
+    readonly given: string;
+    /** Judged on the spot (choice / fill); open questions stay undefined. */
+    readonly pass?: boolean;
+    readonly void?: boolean;
+}
+/** One paper's in-progress sitting. */
+export interface QuizDraft {
+    readonly answers: Readonly<Record<string, QuizDraftAnswer>>;
+    /** Open-answer text not yet submitted. */
+    readonly drafts: Readonly<Record<string, string>>;
+    readonly at: string;
+}
+/** The saved sitting of one paper, when one parses. */
+export declare function loadQuizDraft(quizId: string): QuizDraft | undefined;
+/** Save the sitting (every answer / keystroke; the write is a full replace). */
+export declare function saveQuizDraft(quizId: string, draft: QuizDraft): void;
+/** Drop the draft (the sitting landed, or the paper was superseded under it). */
+export declare function clearQuizDraft(quizId: string): void;
+//# sourceMappingURL=quiz-drafts.d.ts.map

package/lib/types/client/quiz-drafts.js

@@ -0,0 +1,50 @@
+/**
+ * Quiz drafts: the learner's in-progress answers survive leaving the paper
+ * (back to the station, a closed sidebar, a reload). Stored in localStorage
+ * per quiz id — a draft is local by definition (never ledgered until 交卷),
+ * so no host write is involved; the entry clears when the sitting lands.
+ *
+ * @module @khorsheed/dsh-library/client/quiz-drafts
+ */
+function keyOf(quizId) {
+    return `dsh-library:quiz-draft:${quizId}`;
+}
+/** The saved sitting of one paper, when one parses. */
+export function loadQuizDraft(quizId) {
+    let raw;
+    try {
+        raw = localStorage.getItem(keyOf(quizId));
+    }
+    catch {
+        return undefined; // storage blocked (private mode) — a draft is a nicety, never a failure
+    }
+    if (raw === null)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || typeof parsed.answers !== 'object' || parsed.answers === null)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Save the sitting (every answer / keystroke; the write is a full replace). */
+export function saveQuizDraft(quizId, draft) {
+    try {
+        localStorage.setItem(keyOf(quizId), JSON.stringify(draft));
+    }
+    catch {
+        // Quota or privacy mode — the sitting stays in memory for this mount.
+    }
+}
+/** Drop the draft (the sitting landed, or the paper was superseded under it). */
+export function clearQuizDraft(quizId) {
+    try {
+        localStorage.removeItem(keyOf(quizId));
+    }
+    catch {
+        // As above.
+    }
+}