react-cheminfo 0.2.0 → 0.4.0

package/lib/pedagogy/core/glossary.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The `[[term]]` marker language, parsed without a DOM.
+ *
+ * Authored prose — tutorial steps, exercise descriptions, hints — links its
+ * jargon by wrapping it in `[[double brackets]]`. A marker may be written
+ * `[[term|displayed text]]` when the sentence needs a different wording than
+ * the glossary key. Parsing and resolution live here, in plain TypeScript, so
+ * both are unit-tested without rendering anything.
+ */
+/** One worked example inside a glossary entry. */
+export interface GlossaryExample {
+    /** The construct itself: a pattern, a SMILES, a LaTeX fragment, a layer. */
+    code: string;
+    /**
+     * What the construct is shown working on, for a term whose examples take an
+     * input. Left out when the example is about notation only.
+     * @default undefined
+     */
+    input?: string;
+    /**
+     * What this example demonstrates, in one line.
+     * @default undefined
+     */
+    note?: string;
+}
+/** One glossary term, shown wherever a `[[marker]]` names it. */
+export interface GlossaryEntry {
+    /** The term, spelled out as the heading of the tooltip. */
+    title: string;
+    /** One short paragraph — the whole definition. */
+    summary: string;
+    /** Worked examples, shown under the summary. */
+    examples: GlossaryExample[];
+}
+/**
+ * Every term a site defines, keyed by the lowercased text inside a `[[...]]`.
+ *
+ * A key that no marker names is simply never shown, and a marker naming no key
+ * renders as plain prose — so the two sides may be written in either order.
+ */
+export type Glossary = Record<string, GlossaryEntry>;
+/**
+ * One piece of parsed prose: either a run of text, or one marker.
+ *
+ * `start` is the offset of the piece in the source string, which makes it a
+ * stable and unique React key — an array index is neither.
+ */
+export type GlossarySegment = {
+    kind: 'text';
+    start: number;
+    text: string;
+} | {
+    kind: 'term';
+    start: number;
+    term: string;
+    text: string;
+};
+/**
+ * Split authored prose into prose runs and markers.
+ *
+ * A marker yields the lowercased lookup `term` and the `text` to display, which
+ * are the same thing unless the marker used the `term|text` form. The term is
+ * never checked against any glossary here: an unknown term still produces a
+ * `term` segment, and the renderer falls back to showing its text as plain
+ * prose — an author may link a term months before it is written, and the page
+ * must never show the brackets. Text that never closes its brackets (`[[foo`)
+ * is not a marker at all and comes back verbatim inside a `text` segment.
+ * @param text - Authored prose, with or without markers.
+ * @returns The segments, in order, with no empty run between adjacent markers.
+ */
+export declare function parseGlossaryMarkers(text: string): GlossarySegment[];
+/**
+ * Resolve a marker term against a glossary, case-insensitively.
+ * @param glossary - The terms the site defines.
+ * @param term - The text before the pipe of a `[[marker]]`, in any case.
+ * @returns The entry, or `undefined` when no such term has been written yet.
+ */
+export declare function lookupGlossaryTerm(glossary: Glossary, term: string): GlossaryEntry | undefined;
+//# sourceMappingURL=glossary.d.ts.map

package/lib/pedagogy/core/glossary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/glossary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAsBpE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,GACX,aAAa,GAAG,SAAS,CAI3B"}

package/lib/pedagogy/core/glossary.js

@@ -0,0 +1,71 @@
+/**
+ * The `[[term]]` marker language, parsed without a DOM.
+ *
+ * Authored prose — tutorial steps, exercise descriptions, hints — links its
+ * jargon by wrapping it in `[[double brackets]]`. A marker may be written
+ * `[[term|displayed text]]` when the sentence needs a different wording than
+ * the glossary key. Parsing and resolution live here, in plain TypeScript, so
+ * both are unit-tested without rendering anything.
+ */
+/**
+ * Split authored prose into prose runs and markers.
+ *
+ * A marker yields the lowercased lookup `term` and the `text` to display, which
+ * are the same thing unless the marker used the `term|text` form. The term is
+ * never checked against any glossary here: an unknown term still produces a
+ * `term` segment, and the renderer falls back to showing its text as plain
+ * prose — an author may link a term months before it is written, and the page
+ * must never show the brackets. Text that never closes its brackets (`[[foo`)
+ * is not a marker at all and comes back verbatim inside a `text` segment.
+ * @param text - Authored prose, with or without markers.
+ * @returns The segments, in order, with no empty run between adjacent markers.
+ */
+export function parseGlossaryMarkers(text) {
+    const segments = [];
+    // A fresh regexp per call: a /g/ literal carries `lastIndex` between calls.
+    const marker = new RegExp(MARKER_SOURCE, 'g');
+    let cursor = 0;
+    let match = marker.exec(text);
+    while (match !== null) {
+        if (match.index > cursor) {
+            segments.push({
+                kind: 'text',
+                start: cursor,
+                text: text.slice(cursor, match.index),
+            });
+        }
+        segments.push(toTermSegment(match.groups?.term ?? '', match.index));
+        cursor = match.index + match[0].length;
+        match = marker.exec(text);
+    }
+    if (cursor < text.length) {
+        segments.push({ kind: 'text', start: cursor, text: text.slice(cursor) });
+    }
+    return segments;
+}
+/**
+ * Resolve a marker term against a glossary, case-insensitively.
+ * @param glossary - The terms the site defines.
+ * @param term - The text before the pipe of a `[[marker]]`, in any case.
+ * @returns The entry, or `undefined` when no such term has been written yet.
+ */
+export function lookupGlossaryTerm(glossary, term) {
+    const key = term.trim().toLowerCase();
+    // `[[constructor]]` and `[[tostring]]` are prose, not inherited members.
+    return Object.hasOwn(glossary, key) ? glossary[key] : undefined;
+}
+const MARKER_SOURCE = String.raw `\[\[(?<term>[^\]]+)\]\]`;
+function toTermSegment(inner, start) {
+    const pipe = inner.indexOf('|');
+    const rawTerm = pipe === -1 ? inner : inner.slice(0, pipe);
+    const rawText = pipe === -1 ? inner : inner.slice(pipe + 1);
+    const term = rawTerm.trim().toLowerCase();
+    const text = rawText.trim();
+    return {
+        kind: 'term',
+        start,
+        term,
+        text: text === '' ? rawTerm.trim() : text,
+    };
+}
+//# sourceMappingURL=glossary.js.map

package/lib/pedagogy/core/glossary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glossary.js","sourceRoot":"","sources":["../../../src/pedagogy/core/glossary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+CH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,4EAA4E;IAC5E,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IAC9C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,KAAK,KAAK,IAAI,EAAE,CAAC;QACtB,IAAI,KAAK,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC;YACzB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,MAAM;gBACb,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC;aACtC,CAAC,CAAC;QACL,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,IAAI,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACvC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAkB,EAClB,IAAY;IAEZ,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACtC,yEAAyE;IACzE,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAA,yBAAyB,CAAC;AAE1D,SAAS,aAAa,CAAC,KAAa,EAAE,KAAa;IACjD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,KAAK;QACL,IAAI;QACJ,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;KAC1C,CAAC;AACJ,CAAC"}

package/lib/pedagogy/core/index.d.ts

@@ -0,0 +1,8 @@
+export type { Glossary, GlossaryEntry, GlossaryExample, GlossarySegment, } from './glossary.ts';
+export { parseGlossaryMarkers } from './glossary.ts';
+export type { ExerciseProgress, LocalStorageProgressStoreOptions, ProgressRecords, ProgressStore, ProgressSummary, } from './progress.ts';
+export { localStorageProgressStore, progressSummary } from './progress.ts';
+export type { BaseExercise, ExerciseLevel, ExerciseSet, ExerciseStatus, TutorialStep, } from './types.ts';
+export type { FinishValidationOptions, TestCaseResult, ValidationResult, } from './validation.ts';
+export { failedValidation, finishValidation } from './validation.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/pedagogy/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,QAAQ,EACR,aAAa,EACb,eAAe,EACf,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EACV,gBAAgB,EAChB,gCAAgC,EAChC,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3E,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,cAAc,EACd,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,uBAAuB,EACvB,cAAc,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/lib/pedagogy/core/index.js

@@ -0,0 +1,4 @@
+export { parseGlossaryMarkers } from "./glossary.js";
+export { localStorageProgressStore, progressSummary } from "./progress.js";
+export { failedValidation, finishValidation } from "./validation.js";
+//# sourceMappingURL=index.js.map

package/lib/pedagogy/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/pedagogy/core/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAQrD,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAa3E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/lib/pedagogy/core/jsonStorage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Best-effort JSON access to `localStorage`.
+ *
+ * A page framed in a course may have no storage at all — third-party storage is
+ * partitioned in Chrome and blocked in Safari — and a full quota must never
+ * take the page down with it. So both calls swallow everything: an unreadable
+ * entry reads as nothing stored, and a refused write is simply lost.
+ */
+/**
+ * Read one entry back as JSON.
+ * @param key - The storage key.
+ * @returns What was parsed, or `undefined` when there is nothing readable.
+ */
+export declare function readJsonEntry(key: string): unknown;
+/**
+ * Write one entry as JSON.
+ * @param key - The storage key.
+ * @param value - What to store.
+ */
+export declare function writeJsonEntry(key: string, value: unknown): void;
+//# sourceMappingURL=jsonStorage.d.ts.map

package/lib/pedagogy/core/jsonStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStorage.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/jsonStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAWlD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAQhE"}

package/lib/pedagogy/core/jsonStorage.js

@@ -0,0 +1,55 @@
+/**
+ * Best-effort JSON access to `localStorage`.
+ *
+ * A page framed in a course may have no storage at all — third-party storage is
+ * partitioned in Chrome and blocked in Safari — and a full quota must never
+ * take the page down with it. So both calls swallow everything: an unreadable
+ * entry reads as nothing stored, and a refused write is simply lost.
+ */
+/**
+ * Read one entry back as JSON.
+ * @param key - The storage key.
+ * @returns What was parsed, or `undefined` when there is nothing readable.
+ */
+export function readJsonEntry(key) {
+    const storage = getStorage();
+    if (storage === null)
+        return undefined;
+    try {
+        const raw = storage.getItem(key);
+        if (raw === null)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    catch {
+        // Corrupt JSON, or a store that refuses to be read.
+        return undefined;
+    }
+}
+/**
+ * Write one entry as JSON.
+ * @param key - The storage key.
+ * @param value - What to store.
+ */
+export function writeJsonEntry(key, value) {
+    const storage = getStorage();
+    if (storage === null)
+        return;
+    try {
+        storage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // Quota exceeded, or a store that refuses to be written.
+    }
+}
+function getStorage() {
+    try {
+        const candidate = globalThis.localStorage;
+        return candidate ?? null;
+    }
+    catch {
+        // Reading localStorage throws outright when storage is blocked.
+        return null;
+    }
+}
+//# sourceMappingURL=jsonStorage.js.map

package/lib/pedagogy/core/jsonStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStorage.js","sourceRoot":"","sources":["../../../src/pedagogy/core/jsonStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACnC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAAc;IACxD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO;IAC7B,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC;AAED,SAAS,UAAU;IACjB,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,UAAU,CAAC,YAAmC,CAAC;QACjE,OAAO,SAAS,IAAI,IAAI,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/pedagogy/core/progress.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Where the work a student did is kept, and how it is read back.
+ *
+ * The browser is the only binding there is by default; a course hosting its own
+ * service implements the same two calls and is plugged in instead, without
+ * anything else in the page knowing where the work went.
+ */
+import type { ExerciseStatus } from './types.ts';
+/** What is remembered about one exercise. */
+export interface ExerciseProgress {
+    status: ExerciseStatus;
+    /** What the student last wrote or drew, exactly as they left it. */
+    answer: string;
+    /**
+     * How many hints of the ladder were opened. A count, not a flag per hint:
+     * the ladder grows, and "solved with two hints" is what a student reads.
+     */
+    hintsRevealed: number;
+    /** Whether the sample answer is on screen. */
+    showSolution: boolean;
+}
+/** Everything a student has done, keyed by exercise id. */
+export type ProgressRecords<TProgress = ExerciseProgress> = Record<string, TProgress>;
+/**
+ * Where the results of the exercises are kept.
+ *
+ * A binding that answers over the network returns a promise from either call;
+ * what {@link ProgressStore.load} resolves to replaces whatever the page
+ * started from.
+ */
+export interface ProgressStore<TProgress = ExerciseProgress> {
+    /** How the binding names itself, for a sentence about it on the page. */
+    readonly name: string;
+    /** Give back everything that was stored. */
+    load: () => ProgressRecords<TProgress> | Promise<ProgressRecords<TProgress>>;
+    /** Keep everything, as it stands after a change. */
+    save: (records: ProgressRecords<TProgress>) => void | Promise<void>;
+}
+/**
+ * The record an exercise nobody has touched starts from.
+ * @returns A blank record.
+ */
+export declare function emptyProgress(): ExerciseProgress;
+/**
+ * Read one stored record over its defaults, field by field.
+ *
+ * A stored field is taken only when it has the same shape as its default, so a
+ * payload written by an older version of the page, or a corrupted one, falls
+ * back field by field rather than wholesale — and a field added after the last
+ * save simply keeps its default. A `null` default accepts anything.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @param defaults - The record a fresh exercise starts from.
+ * @returns A complete record, with nothing unreadable carried over.
+ */
+export declare function mergeProgressRecord<TProgress extends object>(stored: unknown, defaults: TProgress): TProgress;
+/**
+ * Read one stored {@link ExerciseProgress}, with its two constrained fields
+ * checked rather than merely shape-matched: a status outside the three the
+ * page knows reads as `idle`, and a hint count that is negative or fractional
+ * reads as none revealed.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @returns A record the page can trust.
+ */
+export declare function mergeExerciseProgress(stored: unknown): ExerciseProgress;
+/** What {@link localStorageProgressStore} is built from. */
+export interface LocalStorageProgressStoreOptions<TProgress> {
+    /** Namespace of the entry, without the version: `smiles:exercises`. */
+    key: string;
+    /**
+     * Bumped when the shape of a record changes, so a future shape can ignore
+     * today's entries instead of misreading them.
+     * @default 1
+     */
+    version?: number;
+    /**
+     * The record a fresh exercise starts from. When given, every stored record is
+     * read over it with {@link mergeProgressRecord}; when left out, a stored
+     * record is handed back as it was written.
+     * @default undefined
+     */
+    defaults?: TProgress;
+    /**
+     * How the binding names itself on the page.
+     * @default 'this browser'
+     */
+    name?: string;
+}
+/**
+ * Keep the work in `localStorage`, under one namespaced and versioned entry.
+ * @param options - Which entry to use, and what a fresh record looks like.
+ * @returns The binding, ready to be handed to the page.
+ */
+export declare function localStorageProgressStore<TProgress extends object>(options: LocalStorageProgressStoreOptions<TProgress>): ProgressStore<TProgress>;
+/** How far through a set of exercises a student is. */
+export interface ProgressSummary {
+    /** How many are right. */
+    solved: number;
+    /** How many were handed in and are not right yet. */
+    attempted: number;
+    /** How many there are to do. */
+    total: number;
+    /** `solved / total`, and 0 when there is nothing to do. */
+    ratio: number;
+}
+/**
+ * Count where a student stands, for the progress bar over a set.
+ * @param records - What the store gave back.
+ * @param ids - The exercises of the set being counted. Pass them whenever the
+ * bar must read against the whole set: without them only the exercises that
+ * were touched are counted, and the bar would sit at 100% on the first answer.
+ * @returns The counts and the ratio the bar is drawn from.
+ */
+export declare function progressSummary<TProgress extends {
+    status: ExerciseStatus;
+}>(records: ProgressRecords<TProgress>, ids?: readonly string[]): ProgressSummary;
+//# sourceMappingURL=progress.d.ts.map

package/lib/pedagogy/core/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/progress.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,2DAA2D;AAC3D,MAAM,MAAM,eAAe,CAAC,SAAS,GAAG,gBAAgB,IAAI,MAAM,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,SAAS,GAAG,gBAAgB;IACzD,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,eAAe,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7E,oDAAoD;IACpD,IAAI,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,CAEhD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,SAAS,MAAM,EAC1D,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,GAClB,SAAS,CAUX;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAQvE;AAED,4DAA4D;AAC5D,MAAM,WAAW,gCAAgC,CAAC,SAAS;IACzD,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,SAAS,MAAM,EAChE,OAAO,EAAE,gCAAgC,CAAC,SAAS,CAAC,GACnD,aAAa,CAAC,SAAS,CAAC,CAsB1B;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,SAAS;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,EAC1E,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,EACnC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,GACtB,eAAe,CAWjB"}

package/lib/pedagogy/core/progress.js

@@ -0,0 +1,122 @@
+/**
+ * Where the work a student did is kept, and how it is read back.
+ *
+ * The browser is the only binding there is by default; a course hosting its own
+ * service implements the same two calls and is plugged in instead, without
+ * anything else in the page knowing where the work went.
+ */
+import { readJsonEntry, writeJsonEntry } from "./jsonStorage.js";
+/**
+ * The record an exercise nobody has touched starts from.
+ * @returns A blank record.
+ */
+export function emptyProgress() {
+    return { status: 'idle', answer: '', hintsRevealed: 0, showSolution: false };
+}
+/**
+ * Read one stored record over its defaults, field by field.
+ *
+ * A stored field is taken only when it has the same shape as its default, so a
+ * payload written by an older version of the page, or a corrupted one, falls
+ * back field by field rather than wholesale — and a field added after the last
+ * save simply keeps its default. A `null` default accepts anything.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @param defaults - The record a fresh exercise starts from.
+ * @returns A complete record, with nothing unreadable carried over.
+ */
+export function mergeProgressRecord(stored, defaults) {
+    const merged = { ...defaults };
+    if (!isPlainRecord(stored))
+        return merged;
+    for (const [field, fallback] of Object.entries(defaults)) {
+        const value = stored[field];
+        if (value !== undefined && isSameShape(fallback, value)) {
+            merged[field] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * Read one stored {@link ExerciseProgress}, with its two constrained fields
+ * checked rather than merely shape-matched: a status outside the three the
+ * page knows reads as `idle`, and a hint count that is negative or fractional
+ * reads as none revealed.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @returns A record the page can trust.
+ */
+export function mergeExerciseProgress(stored) {
+    const merged = mergeProgressRecord(stored, emptyProgress());
+    return {
+        ...merged,
+        status: STATUSES.has(merged.status) ? merged.status : 'idle',
+        hintsRevealed: merged.hintsRevealed > 0 ? Math.floor(merged.hintsRevealed) : 0,
+    };
+}
+/**
+ * Keep the work in `localStorage`, under one namespaced and versioned entry.
+ * @param options - Which entry to use, and what a fresh record looks like.
+ * @returns The binding, ready to be handed to the page.
+ */
+export function localStorageProgressStore(options) {
+    const { key, version = 1, defaults, name = 'this browser' } = options;
+    const storageKey = `${key}:v${version}`;
+    return {
+        name,
+        load() {
+            const records = {};
+            const stored = readJsonEntry(storageKey);
+            if (!isPlainRecord(stored))
+                return records;
+            for (const [id, value] of Object.entries(stored)) {
+                if (!isPlainRecord(value))
+                    continue;
+                records[id] =
+                    defaults === undefined
+                        ? value
+                        : mergeProgressRecord(value, defaults);
+            }
+            return records;
+        },
+        save(records) {
+            writeJsonEntry(storageKey, records);
+        },
+    };
+}
+/**
+ * Count where a student stands, for the progress bar over a set.
+ * @param records - What the store gave back.
+ * @param ids - The exercises of the set being counted. Pass them whenever the
+ * bar must read against the whole set: without them only the exercises that
+ * were touched are counted, and the bar would sit at 100% on the first answer.
+ * @returns The counts and the ratio the bar is drawn from.
+ */
+export function progressSummary(records, ids) {
+    const keys = ids ?? Object.keys(records);
+    let solved = 0;
+    let attempted = 0;
+    for (const id of keys) {
+        const status = records[id]?.status;
+        if (status === 'solved')
+            solved++;
+        else if (status === 'attempted')
+            attempted++;
+    }
+    const total = keys.length;
+    return { solved, attempted, total, ratio: total === 0 ? 0 : solved / total };
+}
+const STATUSES = new Set([
+    'idle',
+    'attempted',
+    'solved',
+]);
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSameShape(fallback, stored) {
+    if (fallback === null)
+        return true;
+    if (Array.isArray(fallback) !== Array.isArray(stored))
+        return false;
+    return typeof fallback === typeof stored && stored !== null;
+}
+//# sourceMappingURL=progress.js.map

package/lib/pedagogy/core/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../../src/pedagogy/core/progress.ts"],"names":[],"mappings":"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"}

package/lib/pedagogy/core/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The spine every pedagogic tool shares: a level, a status, an exercise, a set
+ * of them, and one stop of a guided tour. What a given tool asks of a student
+ * differs — a regex, a SMILES, a formula — so those parts stay generic and the
+ * site adds them.
+ */
+/**
+ * How hard a step or an exercise is, which is also how it is coloured: green
+ * for a beginner, yellow for an intermediate, pink for an advanced one.
+ */
+export type ExerciseLevel = 'beginner' | 'intermediate' | 'advanced';
+/**
+ * Where a student stands on one exercise: never handed in, handed in and not
+ * right yet, or right. The three are exclusive — a solved exercise is no longer
+ * an attempted one.
+ */
+export type ExerciseStatus = 'idle' | 'attempted' | 'solved';
+/**
+ * What every exercise carries, whatever it asks for.
+ *
+ * A tool extends it with the shape of its own question and its own test cases.
+ */
+export interface BaseExercise {
+    /** Stable and URL-safe: it is what `/exercises/<id>` carries. */
+    id: string;
+    /** How the exercise is listed. */
+    title: string;
+    level: ExerciseLevel;
+    /** What to do, in a few sentences; may carry `[[term]]` markers. */
+    description: string;
+    /**
+     * Ordered from a nudge to almost the answer, revealed one at a time. Two to
+     * four is the useful range: never one, never six.
+     */
+    hints: string[];
+    /** A sample answer, shown only when the student asks to see it. */
+    solution: string;
+}
+/**
+ * A named list of exercises, which is what a link hands out.
+ *
+ * The exercise type is the tool's own, so a set of SMARTS questions and a set
+ * of LaTeX formulas are the same structure holding different questions.
+ */
+export interface ExerciseSet<TExercise = BaseExercise> {
+    /** Stable and URL-safe. */
+    id: string;
+    title: string;
+    /** One line on what the set drills. */
+    description: string;
+    /**
+     * The level of the set as a whole, when it has one. A set whose level is read
+     * off its questions rather than written down leaves it out.
+     * @default undefined
+     */
+    level?: ExerciseLevel;
+    exercises: TExercise[];
+}
+/**
+ * One stop in the guided tour, plus whatever the tool preloads into its live
+ * playground — a pattern and its flags, a SMILES, a structure and a layer.
+ *
+ * A step is a working configuration the student is free to edit, never a slide.
+ */
+export type TutorialStep<TPayload = unknown> = {
+    /** Stable and URL-safe: it is what a link to the step carries. */
+    id: string;
+    title: string;
+    /** One short paragraph; may carry `[[term]]` markers. */
+    description: string;
+    /** Which coloured group the step is listed under. */
+    level: ExerciseLevel;
+} & TPayload;
+//# sourceMappingURL=types.d.ts.map

package/lib/pedagogy/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,CAAC;IACrB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,SAAS,GAAG,YAAY;IACnD,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,SAAS,EAAE,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,QAAQ,GAAG,OAAO,IAAI;IAC7C,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,KAAK,EAAE,aAAa,CAAC;CACtB,GAAG,QAAQ,CAAC"}

package/lib/pedagogy/core/types.js

@@ -0,0 +1,8 @@
+/**
+ * The spine every pedagogic tool shares: a level, a status, an exercise, a set
+ * of them, and one stop of a guided tour. What a given tool asks of a student
+ * differs — a regex, a SMILES, a formula — so those parts stay generic and the
+ * site adds them.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/pedagogy/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/pedagogy/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}