@ai-gui/plugin-flashcard 0.18.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# @ai-gui/plugin-flashcard
+
+## 0.18.0
+
+### Minor Changes
+
+- a22ba20: **New package: `@ai-gui/plugin-flashcard` — cards to revise from.**
+
+  The moment a vocabulary list stops being a list. A word shown beside its meaning is a word being
+  _read_, and reading a word you have already read teaches nothing — what moves it into memory is being
+  asked for it and finding out whether it came. So a card hides its back, and the person says how it went
+  before they are told.
+
+  ```flashcards
+  {"version":1,"id":"de-week-1","gradeAction":"revise.word","cards":[{"id":"word-1","front":"der Kühlschrank","back":"冰箱","hint":"der Kühl-schrank","example":"Der Kühlschrank ist leer."}]}
+  ```
+
+  It schedules nothing: which card comes back tomorrow and which in a month is the host's, because only
+  the host knows what else this person is learning and when they last saw it. What travels out is one
+  grade per card — `again` / `hard` / `good` — through the same action allowlist a form's submission uses.
+  Three grades because "I half knew it" is the commonest answer and a two-way split forces it into a lie
+  in either direction.
+
+  `reveal: "immediate"` shows both sides of every card and grades nothing, for the teaching moment: hiding
+  the meaning of a word nobody has been told is a quiz on a lesson that has not happened.
+
+  The answer is written into the DOM only when it is asked for, not merely hidden — `hidden` is a style,
+  and an answer sitting in the card's text is one select-all away from being read first. Each card
+  dispatches under its own `cardId`, so the runtime's dedupe means "this card graded twice in one breath"
+  rather than dropping the second card's grade while the first is still in flight. Space or Enter reveals,
+  `1` `2` `3` grade, and a number pressed before the answer is shown does nothing.
+
+### Patch Changes
+
+- Updated dependencies [a22ba20]
+  - @ai-gui/core@0.18.0
+
+## 0.18.0
+
+### Minor Changes
+
+- a22ba20: **New package: cards to revise from.**
+
+  The moment a vocabulary list stops being a list. A word shown beside its meaning is a word being
+  _read_, and reading a word you have already read teaches nothing — what moves it into memory is being
+  asked for it and finding out whether it came. So a card hides its back, and the person says how it went
+  before they are told.
+
+  ```flashcards
+  {"version":1,"id":"de-week-1","gradeAction":"revise.word","cards":[{"id":"word-1","front":"der Kühlschrank","back":"冰箱","hint":"der Kühl-schrank","example":"Der Kühlschrank ist leer."}]}
+  ```
+
+  It schedules nothing: which card comes back tomorrow and which in a month is the host's, because only
+  the host knows what else this person is learning and when they last saw it. What travels out is one
+  grade per card — `again` / `hard` / `good` — through the same action allowlist a form's submission uses.
+  Three grades because "I half knew it" is the commonest answer and a two-way split forces it into a lie
+  in either direction.
+
+  `reveal: "immediate"` shows both sides of every card and grades nothing, for the teaching moment: hiding
+  the meaning of a word nobody has been told is a quiz on a lesson that has not happened.
+
+  The answer is written into the DOM only when it is asked for, not merely hidden — `hidden` is a style,
+  and an answer sitting in the card's text is one select-all away from being read first. Each card
+  dispatches under its own `cardId`, so the runtime's dedupe means "this card graded twice in one breath"
+  rather than dropping the second card's grade while the first is still in flight. Space or Enter reveals,
+  `1` `2` `3` grade, and a number pressed before the answer is shown does nothing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @ai-gui/plugin-flashcard
+
+Cards to revise from: one at a time, answer hidden, self-graded.
+
+The moment a vocabulary list stops being a list. A word shown beside its meaning is a word being
+*read*, and reading a word you have already read teaches nothing — what moves it into memory is being
+asked for it and finding out whether it came. So a card hides its back, and the person says how it went
+before they are told.
+
+```md
+```flashcards
+{"version":1,"id":"de-week-1","title":"本周德语词","gradeAction":"revise.word","cards":[
+  {"id":"word-1","front":"der Kühlschrank","back":"冰箱","hint":"der Kühl-schrank","example":"Der Kühlschrank ist leer."},
+  {"id":"word-2","front":"möchten","back":"想要"}
+]}
+```
+```
+
+```ts
+import { flashcards } from "@ai-gui/plugin-flashcard"
+
+const plugin = flashcards({ actionRuntime })
+```
+
+## What it does not do
+
+**Scheduling.** Which card comes back tomorrow and which in a month is the host's: only the host knows
+what else this person is learning and when they last saw it. What travels out is one grade per card —
+`again` / `hard` / `good` — dispatched through the same action allowlist a form's submission uses:
+
+```ts
+registry.register({
+  type: "revise.word",
+  run: ({ cardId, grade }) => scheduleNextAppearance(cardId, grade),
+})
+```
+
+Three grades, not two: "I half knew it" is the commonest answer, and a two-way split forces it into a
+lie in either direction.
+
+## Two modes
+
+`reveal: "hidden"` (the default) is revision — one card, answer hidden, graded.
+
+`reveal: "immediate"` shows both sides of every card at once and grades nothing. That is the teaching
+moment: the person is meeting these for the first time, and hiding the meaning of a word nobody has
+been told is a quiz on a lesson that has not happened.
+
+## Keyboard
+
+Space or Enter reveals; `1` `2` `3` grade. A number pressed before the answer is shown does nothing —
+otherwise a stray keypress grades a card the person never saw, and the schedule believes it.

package/dist/index.cjs

@@ -0,0 +1,399 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __ai_gui_core = __toESM(require("@ai-gui/core"));
+
+//#region src/index.ts
+/**
+* Cards to test yourself against, one at a time.
+*
+* The moment a vocabulary list stops being a list: a word shown beside its meaning is a word being
+* read, and reading a word you have already read teaches nothing. What moves a word into memory is
+* being asked for it and finding out whether it came — so a card hides its back, and the person says
+* whether they knew it before they are told.
+*
+* That self-report is the whole output. This plugin does not schedule anything: which card comes back
+* in a day and which in a month is the host's, because only the host knows what else the person is
+* learning and when they last saw it. What travels out is one grade per card, through the same action
+* allowlist a form's submission uses.
+*/
+const DEFAULTS = {
+	maxSourceBytes: 16 * 1024,
+	maxCards: 60
+};
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const DECK_KEYS = new Set([
+	"id",
+	"version",
+	"reveal",
+	"gradeAction",
+	"title",
+	"cards"
+]);
+const CARD_KEYS = new Set([
+	"id",
+	"front",
+	"back",
+	"hint",
+	"example",
+	"note"
+]);
+const DEFAULT_LABELS = {
+	reveal: "看答案",
+	again: "不认识",
+	hard: "模糊",
+	good: "认识",
+	progress: (seen, total) => `${seen} / ${total}`,
+	done: (counts) => `这一轮：认识 ${counts.good}，模糊 ${counts.hard}，不认识 ${counts.again}`
+};
+/** Read a deck out of a block, strictly. */
+function parseFlashcards(source, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	if (new TextEncoder().encode(source).byteLength > limits.maxSourceBytes) return {
+		valid: false,
+		issues: ["Deck is too large."]
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return {
+			valid: false,
+			issues: ["Deck must be valid JSON."]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		valid: false,
+		issues: ["Deck must be a JSON object."]
+	};
+	const value = parsed;
+	const issues = [];
+	for (const key of Object.keys(value)) if (!DECK_KEYS.has(key)) issues.push(`$.${key} is not a deck property.`);
+	if (value.version !== 1) issues.push("$.version must be 1.");
+	const id = typeof value.id === "string" ? value.id.trim() : "";
+	if (!id || !SAFE_ID.test(id)) issues.push("$.id must be a safe identifier.");
+	const reveal = value.reveal === void 0 ? "hidden" : value.reveal;
+	if (reveal !== "hidden" && reveal !== "immediate") issues.push("$.reveal must be \"hidden\" or \"immediate\".");
+	let gradeAction;
+	if (value.gradeAction !== void 0) if (typeof value.gradeAction !== "string" || !SAFE_ID.test(value.gradeAction)) issues.push("$.gradeAction must name a registered action.");
+	else gradeAction = value.gradeAction;
+	const title = typeof value.title === "string" ? value.title.trim() : void 0;
+	if (!Array.isArray(value.cards)) issues.push("$.cards must be an array.");
+	const cards = [];
+	const seen = new Set();
+	for (const [index, entry] of (Array.isArray(value.cards) ? value.cards : []).entries()) {
+		const path = `$.cards[${index}]`;
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+			issues.push(`${path} must be an object.`);
+			continue;
+		}
+		const card = entry;
+		for (const key of Object.keys(card)) if (!CARD_KEYS.has(key)) issues.push(`${path}.${key} is not a card property.`);
+		const cardId = typeof card.id === "string" ? card.id.trim() : "";
+		const front = typeof card.front === "string" ? card.front.trim() : "";
+		const back = typeof card.back === "string" ? card.back.trim() : "";
+		if (!cardId || !SAFE_ID.test(cardId)) issues.push(`${path}.id must be a safe identifier.`);
+		if (!front) issues.push(`${path}.front is required.`);
+		if (!back) issues.push(`${path}.back is required.`);
+		if (cardId && seen.has(cardId)) issues.push(`${path}.id is already used in this deck.`);
+		seen.add(cardId);
+		if (!cardId || !front || !back) continue;
+		cards.push({
+			id: cardId,
+			front,
+			back,
+			...typeof card.hint === "string" && card.hint.trim() ? { hint: card.hint.trim() } : {},
+			...typeof card.example === "string" && card.example.trim() ? { example: card.example.trim() } : {},
+			...typeof card.note === "string" && card.note.trim() ? { note: card.note.trim() } : {}
+		});
+		if (cards.length > limits.maxCards) {
+			issues.push(`$.cards holds more than ${limits.maxCards} cards.`);
+			break;
+		}
+	}
+	if (cards.length === 0 && issues.length === 0) issues.push("$.cards is empty.");
+	if (issues.length > 0) return {
+		valid: false,
+		issues
+	};
+	return {
+		valid: true,
+		data: {
+			id,
+			version: 1,
+			reveal,
+			gradeAction,
+			title,
+			cards
+		}
+	};
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** Every card at once, with both sides shown — the teaching case, where nothing is being tested yet. */
+function renderOpenDeck(deck) {
+	const rows = deck.cards.map((card) => {
+		const hint = card.hint ? `<span data-aigui-card-hint>${escapeHtml(card.hint)}</span>` : "";
+		const example = card.example ? `<p data-aigui-card-example>${escapeHtml(card.example)}</p>` : "";
+		return `<li><div data-aigui-card-front><strong>${escapeHtml(card.front)}</strong>${hint}</div><div data-aigui-card-back>${escapeHtml(card.back)}</div>${example}</li>`;
+	}).join("");
+	const title = deck.title ? `<p data-aigui-deck-title>${escapeHtml(deck.title)}</p>` : "";
+	return `<div data-aigui-flashcards="${escapeHtml(deck.id)}" data-reveal="immediate">${title}<ul data-aigui-card-list>${rows}</ul></div>`;
+}
+/**
+* A deck that asks first.
+*
+* Mounted rather than rendered as HTML: the whole point is what happens between showing the front and
+* showing the back, and that is a sequence of events, not a string.
+*/
+function mountDeck(host, deck, options) {
+	const labels = {
+		...DEFAULT_LABELS,
+		...options.labels
+	};
+	const root = document.createElement("div");
+	root.setAttribute("data-aigui-flashcards", deck.id);
+	root.setAttribute("data-reveal", "hidden");
+	const header = document.createElement("div");
+	header.setAttribute("data-aigui-deck-header", "");
+	const title = document.createElement("span");
+	title.setAttribute("data-aigui-deck-title", "");
+	title.textContent = deck.title ?? "";
+	const progress = document.createElement("span");
+	progress.setAttribute("data-aigui-deck-progress", "");
+	progress.setAttribute("aria-live", "polite");
+	header.append(title, progress);
+	const card = document.createElement("div");
+	card.setAttribute("data-aigui-card", "");
+	card.tabIndex = 0;
+	card.setAttribute("role", "button");
+	const front = document.createElement("div");
+	front.setAttribute("data-aigui-card-front", "");
+	const hint = document.createElement("span");
+	hint.setAttribute("data-aigui-card-hint", "");
+	const back = document.createElement("div");
+	back.setAttribute("data-aigui-card-back", "");
+	back.hidden = true;
+	const example = document.createElement("p");
+	example.setAttribute("data-aigui-card-example", "");
+	example.hidden = true;
+	card.append(front, hint, back, example);
+	const reveal = document.createElement("button");
+	reveal.type = "button";
+	reveal.setAttribute("data-aigui-card-reveal", "");
+	reveal.textContent = labels.reveal;
+	const grades = document.createElement("div");
+	grades.setAttribute("data-aigui-card-grades", "");
+	grades.hidden = true;
+	for (const grade$1 of [
+		"again",
+		"hard",
+		"good"
+	]) {
+		const button = document.createElement("button");
+		button.type = "button";
+		button.dataset.aiguiCardGrade = grade$1;
+		button.textContent = labels[grade$1];
+		grades.appendChild(button);
+	}
+	const done = document.createElement("p");
+	done.setAttribute("data-aigui-deck-done", "");
+	done.hidden = true;
+	root.append(header, card, reveal, grades, done);
+	host.replaceChildren(root);
+	let index = 0;
+	let shown = false;
+	const counts = {
+		again: 0,
+		hard: 0,
+		good: 0
+	};
+	let disposed = false;
+	const draw = () => {
+		const current = deck.cards[index];
+		if (!current) {
+			card.hidden = true;
+			reveal.hidden = true;
+			grades.hidden = true;
+			done.hidden = false;
+			done.textContent = labels.done(counts);
+			root.setAttribute("data-finished", "true");
+			progress.textContent = labels.progress(deck.cards.length, deck.cards.length);
+			return;
+		}
+		front.textContent = current.front;
+		hint.textContent = current.hint ?? "";
+		hint.hidden = !current.hint;
+		back.textContent = shown ? current.back : "";
+		example.textContent = shown ? current.example ?? "" : "";
+		back.hidden = !shown;
+		example.hidden = !shown || !current.example;
+		reveal.hidden = shown;
+		grades.hidden = !shown;
+		card.setAttribute("data-shown", String(shown));
+		progress.textContent = labels.progress(index + (shown ? 1 : 0), deck.cards.length);
+	};
+	const show = () => {
+		if (shown) return;
+		shown = true;
+		draw();
+		grades.querySelector("button")?.focus();
+	};
+	const grade = (value) => {
+		const current = deck.cards[index];
+		if (!current || disposed) return;
+		counts[value] += 1;
+		if (deck.gradeAction) options.actionRuntime.dispatch({
+			type: deck.gradeAction,
+			cardType: deck.id,
+			cardId: current.id,
+			params: {
+				deckId: deck.id,
+				cardId: current.id,
+				grade: value
+			}
+		}, { owner: root }).catch((error) => {
+			if (error instanceof __ai_gui_core.ActionRuntimeError) return;
+			throw error;
+		});
+		index += 1;
+		shown = false;
+		draw();
+		if (index < deck.cards.length) card.focus();
+	};
+	const onCardActivate = (event) => {
+		if (event instanceof KeyboardEvent) {
+			if (event.key !== "Enter" && event.key !== " ") return;
+			event.preventDefault();
+		}
+		show();
+	};
+	card.addEventListener("click", onCardActivate);
+	card.addEventListener("keydown", onCardActivate);
+	reveal.addEventListener("click", show);
+	const onGrade = (event) => {
+		const button = event.target.closest("[data-aigui-card-grade]");
+		if (!button) return;
+		grade(button.dataset.aiguiCardGrade);
+	};
+	grades.addEventListener("click", onGrade);
+	const onKey = (event) => {
+		if (!shown) return;
+		const byNumber = {
+			"1": "again",
+			"2": "hard",
+			"3": "good"
+		};
+		const chosen = byNumber[event.key];
+		if (!chosen) return;
+		event.preventDefault();
+		grade(chosen);
+	};
+	root.addEventListener("keydown", onKey);
+	draw();
+	return () => {
+		disposed = true;
+		card.removeEventListener("click", onCardActivate);
+		card.removeEventListener("keydown", onCardActivate);
+		reveal.removeEventListener("click", show);
+		grades.removeEventListener("click", onGrade);
+		root.removeEventListener("keydown", onKey);
+	};
+}
+function flashcardPromptSpec() {
+	return [
+		"Flashcards (fenced): ```flashcards <safe deck JSON>```.",
+		"Deck: {\"version\":1,\"id\":\"...\",\"reveal\":\"hidden|immediate\"?,\"gradeAction\":\"...\"?,\"title\":\"...\"?,\"cards\":[{\"id\":\"...\",\"front\":\"...\",\"back\":\"...\",\"hint\":\"...\"?,\"example\":\"...\"?}]}.",
+		"`hidden` (the default) shows one card at a time and asks the person to say how it went before showing the answer — use it to revise. `immediate` shows both sides of every card at once and grades nothing — use it when they are meeting these for the first time.",
+		"`front` is what is being asked and `back` is what it is checked against; a `hint` is shown with the front and must never give the answer away. `id` on each card is what a grade is reported against, so use the host's own ids.",
+		"gradeAction must name an application-registered Action. Never emit URLs, scripts, HTML or handlers."
+	].join("\n");
+}
+const flashcardCss = `
+[data-aigui-flashcards] { margin: 14px 0; padding: 14px; border: 1px solid #c8d6ce; border-radius: 12px; background: #f7f9f6; }
+[data-aigui-deck-header] { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; margin-bottom: 10px; font-size: 12px; color: #5d6f65; }
+[data-aigui-card] { display: grid; gap: 6px; padding: 22px 16px; text-align: center; border: 1px solid #c4d1ca; border-radius: 10px; background: #fff; cursor: pointer; }
+[data-aigui-card]:focus-visible { outline: 2px solid #2f6b4f; outline-offset: 2px; }
+[data-aigui-card-front] { font-size: 20px; font-weight: 700; }
+[data-aigui-card-hint] { font-size: 12px; color: #7b8b81; }
+[data-aigui-card-back] { padding-top: 8px; border-top: 1px dashed #d3ded7; font-size: 16px; }
+[data-aigui-card-example] { margin: 0; font-size: 13px; color: #55655c; }
+[data-aigui-card-reveal] { width: 100%; margin-top: 10px; padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }
+[data-aigui-card-grades] { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; margin-top: 10px; }
+[data-aigui-card-grades] button { padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }
+[data-aigui-card-grades] button[data-aigui-card-grade="again"] { color: #8a2b20; border-color: #e3b4ad; }
+[data-aigui-card-grades] button[data-aigui-card-grade="good"] { color: #23543c; border-color: #a9c9b6; }
+[data-aigui-card-list] { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }
+[data-aigui-card-list] li { display: grid; gap: 2px; padding: 10px 12px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; }
+[data-aigui-deck-done] { margin: 10px 0 0; text-align: center; font-size: 13px; color: #23543c; }
+`;
+/**
+* Cards to revise from.
+*
+* @example
+* ```ts
+* const plugin = flashcards({ actionRuntime })
+* ```
+*/
+function flashcards(options) {
+	if (!options?.actionRuntime) throw new TypeError("flashcards() requires an actionRuntime");
+	return {
+		name: "flashcards",
+		nodeRenderers: { flashcards: (node) => {
+			const parsed = parseFlashcards(node.content ?? "", options);
+			if (!parsed.valid) return {
+				kind: "html",
+				html: `<div data-aigui-flashcards-error>${escapeHtml(parsed.issues[0] ?? "Invalid deck.")}</div>`,
+				trusted: true
+			};
+			const deck = parsed.data;
+			if (deck.gradeAction && !options.actionRuntime.hasAction(deck.gradeAction)) return {
+				kind: "html",
+				html: `<div data-aigui-flashcards-error>${escapeHtml(`Unknown action: ${deck.gradeAction}`)}</div>`,
+				trusted: true
+			};
+			if (deck.reveal === "immediate") return {
+				kind: "html",
+				html: renderOpenDeck(deck),
+				trusted: true
+			};
+			return {
+				kind: "mount",
+				mount: (host) => mountDeck(host, deck, options)
+			};
+		} },
+		promptSpec: flashcardPromptSpec(),
+		css: flashcardCss
+	};
+}
+
+//#endregion
+exports.flashcardCss = flashcardCss
+exports.flashcardPromptSpec = flashcardPromptSpec
+exports.flashcards = flashcards
+exports.parseFlashcards = parseFlashcards

package/dist/index.d.cts

@@ -0,0 +1,75 @@
+import { AIGuiPlugin, ActionRuntime } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/** How the person said it went. Three, because "I half knew it" is the commonest answer and a
+* two-way split forces it into a lie either way. */
+/** How the person said it went. Three, because "I half knew it" is the commonest answer and a
+ * two-way split forces it into a lie either way. */
+type CardGrade = "again" | "hard" | "good";
+interface FlashcardOptions {
+  maxSourceBytes?: number;
+  maxCards?: number;
+}
+interface FlashcardPluginOptions extends FlashcardOptions {
+  /** Shared runtime whose registry is the only allowlist for `gradeAction`. */
+  actionRuntime: ActionRuntime;
+  /** Labels, so a deck can speak the language the lesson is in. */
+  labels?: Partial<FlashcardLabels>;
+}
+interface FlashcardLabels {
+  reveal: string;
+  again: string;
+  hard: string;
+  good: string;
+  progress: (seen: number, total: number) => string;
+  done: (counts: Record<CardGrade, number>) => string;
+}
+interface Flashcard {
+  /** The host's own id for this card — what a grade is reported against. */
+  id: string;
+  /** What is asked. A word, a formula, a question.  */
+  front: string;
+  /** What is checked against. */
+  back: string;
+  /** Shown with the front: a reading, a first letter, a category. Never the answer itself. */
+  hint?: string;
+  /** Shown with the back: the sentence that makes the answer usable. */
+  example?: string;
+  note?: string;
+}
+interface FlashcardDeck {
+  id: string;
+  version: 1;
+  /**
+   * `hidden` asks before it tells — the revision case, and the default.
+   *
+   * `immediate` shows both sides at once and grades nothing: the teaching case, where the person is
+   * meeting these for the first time and there is nothing yet to test.
+   */
+  reveal: "hidden" | "immediate";
+  /** The registered action a grade is reported to. Absent means nothing is reported. */
+  gradeAction?: string;
+  title?: string;
+  cards: Flashcard[];
+}
+type FlashcardParseResult = {
+  valid: true;
+  data: FlashcardDeck;
+} | {
+  valid: false;
+  issues: string[];
+};
+/** Read a deck out of a block, strictly. */
+declare function parseFlashcards(source: string, options?: FlashcardOptions): FlashcardParseResult;
+declare function flashcardPromptSpec(): string;
+declare const flashcardCss = "\n[data-aigui-flashcards] { margin: 14px 0; padding: 14px; border: 1px solid #c8d6ce; border-radius: 12px; background: #f7f9f6; }\n[data-aigui-deck-header] { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; margin-bottom: 10px; font-size: 12px; color: #5d6f65; }\n[data-aigui-card] { display: grid; gap: 6px; padding: 22px 16px; text-align: center; border: 1px solid #c4d1ca; border-radius: 10px; background: #fff; cursor: pointer; }\n[data-aigui-card]:focus-visible { outline: 2px solid #2f6b4f; outline-offset: 2px; }\n[data-aigui-card-front] { font-size: 20px; font-weight: 700; }\n[data-aigui-card-hint] { font-size: 12px; color: #7b8b81; }\n[data-aigui-card-back] { padding-top: 8px; border-top: 1px dashed #d3ded7; font-size: 16px; }\n[data-aigui-card-example] { margin: 0; font-size: 13px; color: #55655c; }\n[data-aigui-card-reveal] { width: 100%; margin-top: 10px; padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }\n[data-aigui-card-grades] { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; margin-top: 10px; }\n[data-aigui-card-grades] button { padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }\n[data-aigui-card-grades] button[data-aigui-card-grade=\"again\"] { color: #8a2b20; border-color: #e3b4ad; }\n[data-aigui-card-grades] button[data-aigui-card-grade=\"good\"] { color: #23543c; border-color: #a9c9b6; }\n[data-aigui-card-list] { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }\n[data-aigui-card-list] li { display: grid; gap: 2px; padding: 10px 12px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; }\n[data-aigui-deck-done] { margin: 10px 0 0; text-align: center; font-size: 13px; color: #23543c; }\n";
+/**
+ * Cards to revise from.
+ *
+ * @example
+ * ```ts
+ * const plugin = flashcards({ actionRuntime })
+ * ```
+ */
+declare function flashcards(options: FlashcardPluginOptions): AIGuiPlugin; //#endregion
+export { CardGrade, Flashcard, FlashcardDeck, FlashcardLabels, FlashcardOptions, FlashcardParseResult, FlashcardPluginOptions, flashcardCss, flashcardPromptSpec, flashcards, parseFlashcards };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { AIGuiPlugin, ActionRuntime } from "@ai-gui/core";
+
+//#region src/index.d.ts
+/** How the person said it went. Three, because "I half knew it" is the commonest answer and a
+* two-way split forces it into a lie either way. */
+/** How the person said it went. Three, because "I half knew it" is the commonest answer and a
+ * two-way split forces it into a lie either way. */
+type CardGrade = "again" | "hard" | "good";
+interface FlashcardOptions {
+  maxSourceBytes?: number;
+  maxCards?: number;
+}
+interface FlashcardPluginOptions extends FlashcardOptions {
+  /** Shared runtime whose registry is the only allowlist for `gradeAction`. */
+  actionRuntime: ActionRuntime;
+  /** Labels, so a deck can speak the language the lesson is in. */
+  labels?: Partial<FlashcardLabels>;
+}
+interface FlashcardLabels {
+  reveal: string;
+  again: string;
+  hard: string;
+  good: string;
+  progress: (seen: number, total: number) => string;
+  done: (counts: Record<CardGrade, number>) => string;
+}
+interface Flashcard {
+  /** The host's own id for this card — what a grade is reported against. */
+  id: string;
+  /** What is asked. A word, a formula, a question.  */
+  front: string;
+  /** What is checked against. */
+  back: string;
+  /** Shown with the front: a reading, a first letter, a category. Never the answer itself. */
+  hint?: string;
+  /** Shown with the back: the sentence that makes the answer usable. */
+  example?: string;
+  note?: string;
+}
+interface FlashcardDeck {
+  id: string;
+  version: 1;
+  /**
+   * `hidden` asks before it tells — the revision case, and the default.
+   *
+   * `immediate` shows both sides at once and grades nothing: the teaching case, where the person is
+   * meeting these for the first time and there is nothing yet to test.
+   */
+  reveal: "hidden" | "immediate";
+  /** The registered action a grade is reported to. Absent means nothing is reported. */
+  gradeAction?: string;
+  title?: string;
+  cards: Flashcard[];
+}
+type FlashcardParseResult = {
+  valid: true;
+  data: FlashcardDeck;
+} | {
+  valid: false;
+  issues: string[];
+};
+/** Read a deck out of a block, strictly. */
+declare function parseFlashcards(source: string, options?: FlashcardOptions): FlashcardParseResult;
+declare function flashcardPromptSpec(): string;
+declare const flashcardCss = "\n[data-aigui-flashcards] { margin: 14px 0; padding: 14px; border: 1px solid #c8d6ce; border-radius: 12px; background: #f7f9f6; }\n[data-aigui-deck-header] { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; margin-bottom: 10px; font-size: 12px; color: #5d6f65; }\n[data-aigui-card] { display: grid; gap: 6px; padding: 22px 16px; text-align: center; border: 1px solid #c4d1ca; border-radius: 10px; background: #fff; cursor: pointer; }\n[data-aigui-card]:focus-visible { outline: 2px solid #2f6b4f; outline-offset: 2px; }\n[data-aigui-card-front] { font-size: 20px; font-weight: 700; }\n[data-aigui-card-hint] { font-size: 12px; color: #7b8b81; }\n[data-aigui-card-back] { padding-top: 8px; border-top: 1px dashed #d3ded7; font-size: 16px; }\n[data-aigui-card-example] { margin: 0; font-size: 13px; color: #55655c; }\n[data-aigui-card-reveal] { width: 100%; margin-top: 10px; padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }\n[data-aigui-card-grades] { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; margin-top: 10px; }\n[data-aigui-card-grades] button { padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }\n[data-aigui-card-grades] button[data-aigui-card-grade=\"again\"] { color: #8a2b20; border-color: #e3b4ad; }\n[data-aigui-card-grades] button[data-aigui-card-grade=\"good\"] { color: #23543c; border-color: #a9c9b6; }\n[data-aigui-card-list] { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }\n[data-aigui-card-list] li { display: grid; gap: 2px; padding: 10px 12px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; }\n[data-aigui-deck-done] { margin: 10px 0 0; text-align: center; font-size: 13px; color: #23543c; }\n";
+/**
+ * Cards to revise from.
+ *
+ * @example
+ * ```ts
+ * const plugin = flashcards({ actionRuntime })
+ * ```
+ */
+declare function flashcards(options: FlashcardPluginOptions): AIGuiPlugin; //#endregion
+export { CardGrade, Flashcard, FlashcardDeck, FlashcardLabels, FlashcardOptions, FlashcardParseResult, FlashcardPluginOptions, flashcardCss, flashcardPromptSpec, flashcards, parseFlashcards };

package/dist/index.js

@@ -0,0 +1,372 @@
+import { ActionRuntimeError } from "@ai-gui/core";
+
+//#region src/index.ts
+/**
+* Cards to test yourself against, one at a time.
+*
+* The moment a vocabulary list stops being a list: a word shown beside its meaning is a word being
+* read, and reading a word you have already read teaches nothing. What moves a word into memory is
+* being asked for it and finding out whether it came — so a card hides its back, and the person says
+* whether they knew it before they are told.
+*
+* That self-report is the whole output. This plugin does not schedule anything: which card comes back
+* in a day and which in a month is the host's, because only the host knows what else the person is
+* learning and when they last saw it. What travels out is one grade per card, through the same action
+* allowlist a form's submission uses.
+*/
+const DEFAULTS = {
+	maxSourceBytes: 16 * 1024,
+	maxCards: 60
+};
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const DECK_KEYS = new Set([
+	"id",
+	"version",
+	"reveal",
+	"gradeAction",
+	"title",
+	"cards"
+]);
+const CARD_KEYS = new Set([
+	"id",
+	"front",
+	"back",
+	"hint",
+	"example",
+	"note"
+]);
+const DEFAULT_LABELS = {
+	reveal: "看答案",
+	again: "不认识",
+	hard: "模糊",
+	good: "认识",
+	progress: (seen, total) => `${seen} / ${total}`,
+	done: (counts) => `这一轮：认识 ${counts.good}，模糊 ${counts.hard}，不认识 ${counts.again}`
+};
+/** Read a deck out of a block, strictly. */
+function parseFlashcards(source, options = {}) {
+	const limits = {
+		...DEFAULTS,
+		...options
+	};
+	if (new TextEncoder().encode(source).byteLength > limits.maxSourceBytes) return {
+		valid: false,
+		issues: ["Deck is too large."]
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return {
+			valid: false,
+			issues: ["Deck must be valid JSON."]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		valid: false,
+		issues: ["Deck must be a JSON object."]
+	};
+	const value = parsed;
+	const issues = [];
+	for (const key of Object.keys(value)) if (!DECK_KEYS.has(key)) issues.push(`$.${key} is not a deck property.`);
+	if (value.version !== 1) issues.push("$.version must be 1.");
+	const id = typeof value.id === "string" ? value.id.trim() : "";
+	if (!id || !SAFE_ID.test(id)) issues.push("$.id must be a safe identifier.");
+	const reveal = value.reveal === void 0 ? "hidden" : value.reveal;
+	if (reveal !== "hidden" && reveal !== "immediate") issues.push("$.reveal must be \"hidden\" or \"immediate\".");
+	let gradeAction;
+	if (value.gradeAction !== void 0) if (typeof value.gradeAction !== "string" || !SAFE_ID.test(value.gradeAction)) issues.push("$.gradeAction must name a registered action.");
+	else gradeAction = value.gradeAction;
+	const title = typeof value.title === "string" ? value.title.trim() : void 0;
+	if (!Array.isArray(value.cards)) issues.push("$.cards must be an array.");
+	const cards = [];
+	const seen = new Set();
+	for (const [index, entry] of (Array.isArray(value.cards) ? value.cards : []).entries()) {
+		const path = `$.cards[${index}]`;
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+			issues.push(`${path} must be an object.`);
+			continue;
+		}
+		const card = entry;
+		for (const key of Object.keys(card)) if (!CARD_KEYS.has(key)) issues.push(`${path}.${key} is not a card property.`);
+		const cardId = typeof card.id === "string" ? card.id.trim() : "";
+		const front = typeof card.front === "string" ? card.front.trim() : "";
+		const back = typeof card.back === "string" ? card.back.trim() : "";
+		if (!cardId || !SAFE_ID.test(cardId)) issues.push(`${path}.id must be a safe identifier.`);
+		if (!front) issues.push(`${path}.front is required.`);
+		if (!back) issues.push(`${path}.back is required.`);
+		if (cardId && seen.has(cardId)) issues.push(`${path}.id is already used in this deck.`);
+		seen.add(cardId);
+		if (!cardId || !front || !back) continue;
+		cards.push({
+			id: cardId,
+			front,
+			back,
+			...typeof card.hint === "string" && card.hint.trim() ? { hint: card.hint.trim() } : {},
+			...typeof card.example === "string" && card.example.trim() ? { example: card.example.trim() } : {},
+			...typeof card.note === "string" && card.note.trim() ? { note: card.note.trim() } : {}
+		});
+		if (cards.length > limits.maxCards) {
+			issues.push(`$.cards holds more than ${limits.maxCards} cards.`);
+			break;
+		}
+	}
+	if (cards.length === 0 && issues.length === 0) issues.push("$.cards is empty.");
+	if (issues.length > 0) return {
+		valid: false,
+		issues
+	};
+	return {
+		valid: true,
+		data: {
+			id,
+			version: 1,
+			reveal,
+			gradeAction,
+			title,
+			cards
+		}
+	};
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** Every card at once, with both sides shown — the teaching case, where nothing is being tested yet. */
+function renderOpenDeck(deck) {
+	const rows = deck.cards.map((card) => {
+		const hint = card.hint ? `<span data-aigui-card-hint>${escapeHtml(card.hint)}</span>` : "";
+		const example = card.example ? `<p data-aigui-card-example>${escapeHtml(card.example)}</p>` : "";
+		return `<li><div data-aigui-card-front><strong>${escapeHtml(card.front)}</strong>${hint}</div><div data-aigui-card-back>${escapeHtml(card.back)}</div>${example}</li>`;
+	}).join("");
+	const title = deck.title ? `<p data-aigui-deck-title>${escapeHtml(deck.title)}</p>` : "";
+	return `<div data-aigui-flashcards="${escapeHtml(deck.id)}" data-reveal="immediate">${title}<ul data-aigui-card-list>${rows}</ul></div>`;
+}
+/**
+* A deck that asks first.
+*
+* Mounted rather than rendered as HTML: the whole point is what happens between showing the front and
+* showing the back, and that is a sequence of events, not a string.
+*/
+function mountDeck(host, deck, options) {
+	const labels = {
+		...DEFAULT_LABELS,
+		...options.labels
+	};
+	const root = document.createElement("div");
+	root.setAttribute("data-aigui-flashcards", deck.id);
+	root.setAttribute("data-reveal", "hidden");
+	const header = document.createElement("div");
+	header.setAttribute("data-aigui-deck-header", "");
+	const title = document.createElement("span");
+	title.setAttribute("data-aigui-deck-title", "");
+	title.textContent = deck.title ?? "";
+	const progress = document.createElement("span");
+	progress.setAttribute("data-aigui-deck-progress", "");
+	progress.setAttribute("aria-live", "polite");
+	header.append(title, progress);
+	const card = document.createElement("div");
+	card.setAttribute("data-aigui-card", "");
+	card.tabIndex = 0;
+	card.setAttribute("role", "button");
+	const front = document.createElement("div");
+	front.setAttribute("data-aigui-card-front", "");
+	const hint = document.createElement("span");
+	hint.setAttribute("data-aigui-card-hint", "");
+	const back = document.createElement("div");
+	back.setAttribute("data-aigui-card-back", "");
+	back.hidden = true;
+	const example = document.createElement("p");
+	example.setAttribute("data-aigui-card-example", "");
+	example.hidden = true;
+	card.append(front, hint, back, example);
+	const reveal = document.createElement("button");
+	reveal.type = "button";
+	reveal.setAttribute("data-aigui-card-reveal", "");
+	reveal.textContent = labels.reveal;
+	const grades = document.createElement("div");
+	grades.setAttribute("data-aigui-card-grades", "");
+	grades.hidden = true;
+	for (const grade$1 of [
+		"again",
+		"hard",
+		"good"
+	]) {
+		const button = document.createElement("button");
+		button.type = "button";
+		button.dataset.aiguiCardGrade = grade$1;
+		button.textContent = labels[grade$1];
+		grades.appendChild(button);
+	}
+	const done = document.createElement("p");
+	done.setAttribute("data-aigui-deck-done", "");
+	done.hidden = true;
+	root.append(header, card, reveal, grades, done);
+	host.replaceChildren(root);
+	let index = 0;
+	let shown = false;
+	const counts = {
+		again: 0,
+		hard: 0,
+		good: 0
+	};
+	let disposed = false;
+	const draw = () => {
+		const current = deck.cards[index];
+		if (!current) {
+			card.hidden = true;
+			reveal.hidden = true;
+			grades.hidden = true;
+			done.hidden = false;
+			done.textContent = labels.done(counts);
+			root.setAttribute("data-finished", "true");
+			progress.textContent = labels.progress(deck.cards.length, deck.cards.length);
+			return;
+		}
+		front.textContent = current.front;
+		hint.textContent = current.hint ?? "";
+		hint.hidden = !current.hint;
+		back.textContent = shown ? current.back : "";
+		example.textContent = shown ? current.example ?? "" : "";
+		back.hidden = !shown;
+		example.hidden = !shown || !current.example;
+		reveal.hidden = shown;
+		grades.hidden = !shown;
+		card.setAttribute("data-shown", String(shown));
+		progress.textContent = labels.progress(index + (shown ? 1 : 0), deck.cards.length);
+	};
+	const show = () => {
+		if (shown) return;
+		shown = true;
+		draw();
+		grades.querySelector("button")?.focus();
+	};
+	const grade = (value) => {
+		const current = deck.cards[index];
+		if (!current || disposed) return;
+		counts[value] += 1;
+		if (deck.gradeAction) options.actionRuntime.dispatch({
+			type: deck.gradeAction,
+			cardType: deck.id,
+			cardId: current.id,
+			params: {
+				deckId: deck.id,
+				cardId: current.id,
+				grade: value
+			}
+		}, { owner: root }).catch((error) => {
+			if (error instanceof ActionRuntimeError) return;
+			throw error;
+		});
+		index += 1;
+		shown = false;
+		draw();
+		if (index < deck.cards.length) card.focus();
+	};
+	const onCardActivate = (event) => {
+		if (event instanceof KeyboardEvent) {
+			if (event.key !== "Enter" && event.key !== " ") return;
+			event.preventDefault();
+		}
+		show();
+	};
+	card.addEventListener("click", onCardActivate);
+	card.addEventListener("keydown", onCardActivate);
+	reveal.addEventListener("click", show);
+	const onGrade = (event) => {
+		const button = event.target.closest("[data-aigui-card-grade]");
+		if (!button) return;
+		grade(button.dataset.aiguiCardGrade);
+	};
+	grades.addEventListener("click", onGrade);
+	const onKey = (event) => {
+		if (!shown) return;
+		const byNumber = {
+			"1": "again",
+			"2": "hard",
+			"3": "good"
+		};
+		const chosen = byNumber[event.key];
+		if (!chosen) return;
+		event.preventDefault();
+		grade(chosen);
+	};
+	root.addEventListener("keydown", onKey);
+	draw();
+	return () => {
+		disposed = true;
+		card.removeEventListener("click", onCardActivate);
+		card.removeEventListener("keydown", onCardActivate);
+		reveal.removeEventListener("click", show);
+		grades.removeEventListener("click", onGrade);
+		root.removeEventListener("keydown", onKey);
+	};
+}
+function flashcardPromptSpec() {
+	return [
+		"Flashcards (fenced): ```flashcards <safe deck JSON>```.",
+		"Deck: {\"version\":1,\"id\":\"...\",\"reveal\":\"hidden|immediate\"?,\"gradeAction\":\"...\"?,\"title\":\"...\"?,\"cards\":[{\"id\":\"...\",\"front\":\"...\",\"back\":\"...\",\"hint\":\"...\"?,\"example\":\"...\"?}]}.",
+		"`hidden` (the default) shows one card at a time and asks the person to say how it went before showing the answer — use it to revise. `immediate` shows both sides of every card at once and grades nothing — use it when they are meeting these for the first time.",
+		"`front` is what is being asked and `back` is what it is checked against; a `hint` is shown with the front and must never give the answer away. `id` on each card is what a grade is reported against, so use the host's own ids.",
+		"gradeAction must name an application-registered Action. Never emit URLs, scripts, HTML or handlers."
+	].join("\n");
+}
+const flashcardCss = `
+[data-aigui-flashcards] { margin: 14px 0; padding: 14px; border: 1px solid #c8d6ce; border-radius: 12px; background: #f7f9f6; }
+[data-aigui-deck-header] { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; margin-bottom: 10px; font-size: 12px; color: #5d6f65; }
+[data-aigui-card] { display: grid; gap: 6px; padding: 22px 16px; text-align: center; border: 1px solid #c4d1ca; border-radius: 10px; background: #fff; cursor: pointer; }
+[data-aigui-card]:focus-visible { outline: 2px solid #2f6b4f; outline-offset: 2px; }
+[data-aigui-card-front] { font-size: 20px; font-weight: 700; }
+[data-aigui-card-hint] { font-size: 12px; color: #7b8b81; }
+[data-aigui-card-back] { padding-top: 8px; border-top: 1px dashed #d3ded7; font-size: 16px; }
+[data-aigui-card-example] { margin: 0; font-size: 13px; color: #55655c; }
+[data-aigui-card-reveal] { width: 100%; margin-top: 10px; padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }
+[data-aigui-card-grades] { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; margin-top: 10px; }
+[data-aigui-card-grades] button { padding: 9px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; cursor: pointer; }
+[data-aigui-card-grades] button[data-aigui-card-grade="again"] { color: #8a2b20; border-color: #e3b4ad; }
+[data-aigui-card-grades] button[data-aigui-card-grade="good"] { color: #23543c; border-color: #a9c9b6; }
+[data-aigui-card-list] { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }
+[data-aigui-card-list] li { display: grid; gap: 2px; padding: 10px 12px; border: 1px solid #c4d1ca; border-radius: 9px; background: #fff; }
+[data-aigui-deck-done] { margin: 10px 0 0; text-align: center; font-size: 13px; color: #23543c; }
+`;
+/**
+* Cards to revise from.
+*
+* @example
+* ```ts
+* const plugin = flashcards({ actionRuntime })
+* ```
+*/
+function flashcards(options) {
+	if (!options?.actionRuntime) throw new TypeError("flashcards() requires an actionRuntime");
+	return {
+		name: "flashcards",
+		nodeRenderers: { flashcards: (node) => {
+			const parsed = parseFlashcards(node.content ?? "", options);
+			if (!parsed.valid) return {
+				kind: "html",
+				html: `<div data-aigui-flashcards-error>${escapeHtml(parsed.issues[0] ?? "Invalid deck.")}</div>`,
+				trusted: true
+			};
+			const deck = parsed.data;
+			if (deck.gradeAction && !options.actionRuntime.hasAction(deck.gradeAction)) return {
+				kind: "html",
+				html: `<div data-aigui-flashcards-error>${escapeHtml(`Unknown action: ${deck.gradeAction}`)}</div>`,
+				trusted: true
+			};
+			if (deck.reveal === "immediate") return {
+				kind: "html",
+				html: renderOpenDeck(deck),
+				trusted: true
+			};
+			return {
+				kind: "mount",
+				mount: (host) => mountDeck(host, deck, options)
+			};
+		} },
+		promptSpec: flashcardPromptSpec(),
+		css: flashcardCss
+	};
+}
+
+//#endregion
+export { flashcardCss, flashcardPromptSpec, flashcards, parseFlashcards };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ai-gui/plugin-flashcard",
+  "version": "0.18.0",
+  "description": "Flashcards to revise from: one card at a time, hidden answer, self-graded.",
+  "keywords": [
+    "llm",
+    "ai",
+    "flashcard",
+    "srs",
+    "revision",
+    "vocabulary",
+    "learning",
+    "plugin",
+    "aigui"
+  ],
+  "license": "MIT",
+  "author": "Liang Li <ll_faw@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liliang-cn/aigui.git",
+    "directory": "packages/plugin-flashcard"
+  },
+  "homepage": "https://github.com/liliang-cn/aigui#readme",
+  "bugs": "https://github.com/liliang-cn/aigui/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-gui/core": "0.18.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project plugin-flashcard",
+    "typecheck": "tsc --noEmit"
+  }
+}