npm - @ai-matrx/print - Versions diffs - 0.3.2 → 0.5.0 - Mend

@ai-matrx/print 0.3.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/dist/exam.cjs.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"sources":["../src/exam.ts","../src/core.ts"],"sourcesContent":["/**\n * @ai-matrx/print/exam — the practice-test lane (question booklet, bubble\n * answer form, answer key, explanations).\n *\n * ── THE ANSWER-SEPARATION LAW ───────────────────────────────────────────────\n * The education research (PRINT-EDUCATION-RESEARCH.md, P0 row \"Practice test\n * booklets + bubble answer sheets\", modeled on Barron's / Princeton Review AP\n * and Kaplan) is explicit: the question booklet, the scannable bubble form and\n * the answer key are SEPARATE printable units. That is not a styling\n * preference — it is what makes a practice test re-usable: a student prints\n * ONE booklet and a fresh blank bubble form per attempt, and the key never\n * travels with the questions. So `question-booklet` emits no answers and no\n * explanations at all (there is a test asserting their ABSENCE), and every\n * variant here is an independently printable document.\n *\n * ── WHY THERE IS NO \"SHUFFLE\" SETTING ───────────────────────────────────────\n * Question order and choice order are DATA, not presentation. A printer that\n * shuffled would desynchronize the three units above — a bubble form or key\n * printed in a different session would no longer match the booklet, silently.\n * Shuffling belongs to whatever generates the PracticeTestData (where the\n * shuffled order can be persisted once and reused by all three units).\n *\n * Zero dependencies; `window` is touched only inside `print`, at call time, so\n * the module stays import-inert and RSC-safe.\n */\n\nimport {\n buildPrintDocument,\n openPrintWindow,\n type BlockPrinter,\n type PrintOutcome,\n type PrintSettings,\n} from \"./core\";\nimport { escapeHtml } from \"@ai-matrx/kit/html-escape\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\nexport interface ExamChoice {\n /** Optional explicit label. Omitted = auto-lettered A, B, C, … by position. */\n label?: string;\n text: string;\n}\n\nexport interface ExamQuestion {\n prompt: string;\n /** Omitted or empty = free-response (ruled work space instead of bubbles). */\n choices?: ExamChoice[];\n /** The correct choice label (or, for free response, the model answer text). */\n answer?: string;\n explanation?: string;\n points?: number;\n /** Ruled lines to print under a free-response question in the booklet. */\n workSpaceLines?: number;\n}\n\nexport interface PracticeTestData {\n title: string;\n instructions?: string;\n questions: ExamQuestion[];\n}\n\nexport type PracticeTestVariant =\n | \"question-booklet\"\n | \"bubble-sheet\"\n | \"answer-key\"\n | \"explanations\";\n\n// ─── Geometry constants (bubble sheet) ───────────────────────────────────────\n//\n// Letter portrait, 0.5in page margin. 25 rows per column is the scanner-form\n// convention (Scantron 882-E and the AP answer sheets both group in 25s) and\n// it also keeps a 5-choice row inside a 1.75in column at a 0.28in pitch.\n// Everything below is INCH-exact so a physical ruler laid on the print\n// matches: circles are 0.16in across, drawn as CSS borders (never images, and\n// never a background fill that a \"save ink\" print mode could drop).\n\n/** Rows per bubble column — the scanner-form convention. */\nconst BUBBLE_ROWS_PER_COLUMN = 25;\n/** Columns printed side by side before a page break. */\nconst BUBBLE_COLUMNS_PER_PAGE = 4;\n/** Max bubbles a row can carry (A–J) before we stop lettering. */\nconst CHOICE_LETTERS = \"ABCDEFGHIJ\";\n\n/** Auto-letter for choice index i; falls back to the number past the alphabet. */\nfunction letterFor(index: number): string {\n return CHOICE_LETTERS[index] ?? String(index + 1);\n}\n\n/** The label a choice prints under (explicit label wins over the auto letter). */\nfunction choiceLabel(choice: ExamChoice, index: number): string {\n const explicit = choice.label?.trim();\n return explicit && explicit.length > 0 ? explicit : letterFor(index);\n}\n\nfunction isFreeResponse(question: ExamQuestion): boolean {\n return !question.choices || question.choices.length === 0;\n}\n\n// ─── Data extraction ─────────────────────────────────────────────────────────\n\nfunction asString(value: unknown): string | undefined {\n return typeof value === \"string\" && value.trim().length > 0\n ? value.trim()\n : undefined;\n}\n\nfunction asNumber(value: unknown): number | undefined {\n return typeof value === \"number\" && Number.isFinite(value) ? value : undefined;\n}\n\nfunction parseChoice(raw: unknown): ExamChoice | null {\n if (typeof raw === \"string\") {\n return raw.trim().length > 0 ? { text: raw } : null;\n }\n if (!raw || typeof raw !== \"object\") return null;\n const obj = raw as Record<string, unknown>;\n const text = asString(obj[\"text\"]);\n if (text === undefined) return null;\n const label = asString(obj[\"label\"]);\n // exactOptionalPropertyTypes: only spread the key when it actually has a value.\n return label === undefined ? { text } : { label, text };\n}\n\nfunction parseQuestion(raw: unknown): ExamQuestion | null {\n if (!raw || typeof raw !== \"object\") return null;\n const obj = raw as Record<string, unknown>;\n const prompt = asString(obj[\"prompt\"]) ?? asString(obj[\"question\"]);\n if (prompt === undefined) return null;\n\n const question: ExamQuestion = { prompt };\n\n const rawChoices = obj[\"choices\"] ?? obj[\"options\"];\n if (Array.isArray(rawChoices)) {\n const choices = rawChoices\n .map((c) => parseChoice(c))\n .filter((c): c is ExamChoice => c !== null);\n if (choices.length > 0) question.choices = choices;\n }\n const answer = asString(obj[\"answer\"]);\n if (answer !== undefined) question.answer = answer;\n const explanation = asString(obj[\"explanation\"]);\n if (explanation !== undefined) question.explanation = explanation;\n const points = asNumber(obj[\"points\"]);\n if (points !== undefined) question.points = points;\n const workSpaceLines = asNumber(obj[\"workSpaceLines\"]);\n if (workSpaceLines !== undefined) {\n question.workSpaceLines = Math.max(0, Math.floor(workSpaceLines));\n }\n return question;\n}\n\n/**\n * Accept the canonical shape, a bare questions array, or a wrapper object that\n * carries one — the same tolerance the flashcards lane offers its hosts.\n */\nexport function extractPracticeTest(data: unknown): PracticeTestData {\n const empty: PracticeTestData = { title: \"Practice Test\", questions: [] };\n if (!data) return empty;\n\n if (Array.isArray(data)) {\n return {\n title: \"Practice Test\",\n questions: data\n .map(parseQuestion)\n .filter((q): q is ExamQuestion => q !== null),\n };\n }\n if (typeof data !== \"object\") return empty;\n\n const obj = data as Record<string, unknown>;\n const rawQuestions = obj[\"questions\"] ?? obj[\"items\"];\n const questions = Array.isArray(rawQuestions)\n ? rawQuestions.map(parseQuestion).filter((q): q is ExamQuestion => q !== null)\n : [];\n\n const test: PracticeTestData = {\n title: asString(obj[\"title\"]) ?? \"Practice Test\",\n questions,\n };\n const instructions = asString(obj[\"instructions\"]);\n if (instructions !== undefined) test.instructions = instructions;\n return test;\n}\n\n// ─── Settings ────────────────────────────────────────────────────────────────\n\ninterface ResolvedExamSettings {\n /** 1-based inclusive question range; both 0 = whole test. */\n from: number;\n to: number;\n /** 0 = derive the bubble count from each question's own choices. */\n bubbleLetters: number;\n showPointsColumn: boolean;\n}\n\nfunction resolveSettings(raw?: PrintSettings): ResolvedExamSettings {\n const num = (key: string): number => {\n const v = raw?.[key];\n return typeof v === \"number\" && Number.isFinite(v) && v > 0\n ? Math.floor(v)\n : 0;\n };\n return {\n from: num(\"fromQuestion\"),\n to: num(\"toQuestion\"),\n bubbleLetters: Math.min(num(\"bubbleLetters\"), CHOICE_LETTERS.length),\n showPointsColumn: raw?.[\"showPointsColumn\"] === true,\n };\n}\n\n/**\n * Slice by the range setting. Returns the questions AND the 0-based offset of\n * the first one, so every variant keeps the ORIGINAL question numbers (a key\n * for questions 26–50 must say \"26.\", never \"1.\").\n */\nfunction applyRange(\n questions: readonly ExamQuestion[],\n s: ResolvedExamSettings,\n): { questions: ExamQuestion[]; startIndex: number } {\n if (questions.length === 0) return { questions: [], startIndex: 0 };\n const start = s.from > 0 ? Math.min(s.from, questions.length) : 1;\n const end = s.to > 0 ? Math.min(s.to, questions.length) : questions.length;\n const [lo, hi] = start <= end ? [start, end] : [end, start];\n return { questions: questions.slice(lo - 1, hi), startIndex: lo - 1 };\n}\n\n// ─── Shared styles ───────────────────────────────────────────────────────────\n\nconst EXAM_BASE_STYLES = `\n .ex-title { font-size: 18pt; font-weight: 700; margin-bottom: 2px; }\n .ex-subtitle { font-size: 10pt; color: #475569; margin-bottom: 14px; }\n .ex-instructions {\n border: 2px solid #1e293b;\n border-radius: 6px;\n padding: 10px 14px;\n margin: 0 0 18px;\n font-size: 10.5pt;\n line-height: 1.5;\n background: #f8fafc;\n -webkit-print-color-adjust: exact;\n print-color-adjust: exact;\n }\n .ex-instructions-heading {\n font-size: 9pt;\n font-weight: 700;\n letter-spacing: 0.08em;\n text-transform: uppercase;\n color: #1e293b;\n margin-bottom: 4px;\n }\n`;\n\n// ─── Variant: question booklet ───────────────────────────────────────────────\n\nconst BOOKLET_VARIANT_STYLES = `\n ${EXAM_BASE_STYLES}\n .ex-q {\n /* A question never splits across a page mid-choice-list — a student\n reading choice (C) at the top of the next page misreads the item. */\n break-inside: avoid;\n page-break-inside: avoid;\n margin: 0 0 16px;\n }\n .ex-q-head { display: flex; gap: 8px; align-items: baseline; }\n .ex-q-num { font-weight: 700; min-width: 1.9em; }\n .ex-q-prompt { flex: 1; font-size: 11pt; line-height: 1.5; }\n .ex-q-points {\n font-size: 8.5pt;\n color: #475569;\n white-space: nowrap;\n font-weight: 600;\n }\n .ex-choices { list-style: none; margin: 6px 0 0 1.9em; padding: 0; }\n .ex-choice { display: flex; gap: 7px; font-size: 10.5pt; line-height: 1.45; margin-bottom: 3px; }\n .ex-choice-label { font-weight: 600; min-width: 1.3em; }\n .ex-work { margin: 8px 0 0 1.9em; }\n .ex-work-line {\n border-bottom: 1px solid #94a3b8;\n height: 0.32in;\n -webkit-print-color-adjust: exact;\n print-color-adjust: exact;\n }\n`;\n\nfunction renderPoints(question: ExamQuestion): string {\n if (question.points === undefined) return \"\";\n const unit = question.points === 1 ? \"pt\" : \"pts\";\n return `<span class=\"ex-q-points\">(${escapeHtml(String(question.points))} ${unit})</span>`;\n}\n\nfunction renderQuestionBooklet(\n test: PracticeTestData,\n questions: readonly ExamQuestion[],\n startIndex: number,\n): string {\n const instructions = test.instructions\n ? `<div class=\"ex-instructions\">\n <div class=\"ex-instructions-heading\">Instructions</div>\n ${escapeHtml(test.instructions)}\n </div>`\n : \"\";\n\n const items = questions\n .map((q, i) => {\n const number = startIndex + i + 1;\n const choices = (q.choices ?? [])\n .map(\n (c, ci) =>\n `<li class=\"ex-choice\"><span class=\"ex-choice-label\">${escapeHtml(\n choiceLabel(c, ci),\n )}.</span><span>${escapeHtml(c.text)}</span></li>`,\n )\n .join(\"\");\n const choiceList =\n choices.length > 0 ? `<ul class=\"ex-choices\">${choices}</ul>` : \"\";\n const lineCount = isFreeResponse(q) ? (q.workSpaceLines ?? 0) : 0;\n const work =\n lineCount > 0\n ? `<div class=\"ex-work\">${'<div class=\"ex-work-line\"></div>'.repeat(lineCount)}</div>`\n : \"\";\n return `<div class=\"ex-q\" data-question=\"${number}\">\n <div class=\"ex-q-head\">\n <span class=\"ex-q-num\">${number}.</span>\n <span class=\"ex-q-prompt\">${escapeHtml(q.prompt)}</span>\n ${renderPoints(q)}\n </div>\n ${choiceList}\n ${work}\n</div>`;\n })\n .join(\"\\n\");\n\n // NO answers, NO explanations here — the answer-separation law.\n return `<div class=\"ex-title\">${escapeHtml(test.title)}</div>\n<div class=\"ex-subtitle\">Question booklet — mark your answers on the separate answer sheet</div>\n${instructions}\n${items}`;\n}\n\n// ─── Variant: bubble sheet ───────────────────────────────────────────────────\n\nconst BUBBLE_STYLES = `\n @page { size: 8.5in 11in; margin: 0.5in; }\n\n .bs-header {\n border: 2px solid #111;\n padding: 0.12in 0.16in;\n margin-bottom: 0.22in;\n break-inside: avoid;\n page-break-inside: avoid;\n }\n .bs-header-title { font-size: 13pt; font-weight: 700; margin-bottom: 0.06in; }\n .bs-header-note { font-size: 8pt; color: #334155; margin-bottom: 0.1in; }\n .bs-fields { display: flex; gap: 0.2in; }\n .bs-field { flex: 1; font-size: 8.5pt; }\n .bs-field-score { flex: 0 0 1.2in; }\n .bs-field-rule {\n border-bottom: 1px solid #111;\n height: 0.26in;\n -webkit-print-color-adjust: exact;\n print-color-adjust: exact;\n }\n .bs-field-label {\n font-size: 7.5pt;\n letter-spacing: 0.06em;\n text-transform: uppercase;\n color: #334155;\n }\n\n .bs-columns {\n display: flex;\n gap: 0.3in;\n break-after: page;\n page-break-after: always;\n }\n .bs-columns:last-of-type { break-after: auto; page-break-after: auto; }\n\n .bs-column { flex: 1; }\n\n .bs-row {\n display: flex;\n align-items: center;\n height: 0.28in; /* the pitch — every row identical */\n break-inside: avoid;\n page-break-inside: avoid;\n }\n .bs-row-num {\n width: 0.3in;\n font-size: 8.5pt;\n text-align: right;\n padding-right: 0.06in;\n font-variant-numeric: tabular-nums;\n }\n .bs-bubble {\n width: 0.16in;\n height: 0.16in;\n border: 1.25px solid #111;\n border-radius: 50%;\n margin-right: 0.055in;\n font-size: 5.5pt;\n line-height: 0.16in;\n text-align: center;\n color: #111;\n -webkit-print-color-adjust: exact;\n print-color-adjust: exact;\n }\n .bs-blank-line {\n flex: 1;\n border-bottom: 1px solid #111;\n height: 0.16in;\n margin-right: 0.06in;\n -webkit-print-color-adjust: exact;\n print-color-adjust: exact;\n }\n .bs-points {\n width: 0.34in;\n font-size: 7.5pt;\n color: #334155;\n text-align: right;\n }\n`;\n\n/** How many bubbles row `q` prints: the override, else the question's choices. */\nfunction bubbleCountFor(\n question: ExamQuestion,\n s: ResolvedExamSettings,\n): number {\n if (isFreeResponse(question)) return s.bubbleLetters > 0 ? s.bubbleLetters : 0;\n const own = question.choices?.length ?? 0;\n const n = s.bubbleLetters > 0 ? s.bubbleLetters : own;\n return Math.min(n, CHOICE_LETTERS.length);\n}\n\nfunction renderBubbleRow(\n question: ExamQuestion,\n number: number,\n s: ResolvedExamSettings,\n): string {\n const count = bubbleCountFor(question, s);\n const cells =\n count > 0\n ? Array.from(\n { length: count },\n (_, i) =>\n `<span class=\"bs-bubble\" data-letter=\"${escapeHtml(letterFor(i))}\">${escapeHtml(\n letterFor(i),\n )}</span>`,\n ).join(\"\")\n : // Free response: a short rule to write the answer on, never bubbles.\n `<span class=\"bs-blank-line\"></span>`;\n const points =\n s.showPointsColumn && question.points !== undefined\n ? `<span class=\"bs-points\">${escapeHtml(String(question.points))}</span>`\n : \"\";\n return `<div class=\"bs-row\" data-question=\"${number}\" data-bubbles=\"${count}\">\n <span class=\"bs-row-num\">${number}.</span>${cells}${points}\n </div>`;\n}\n\nfunction renderBubbleSheet(\n test: PracticeTestData,\n questions: readonly ExamQuestion[],\n startIndex: number,\n s: ResolvedExamSettings,\n): string {\n const rows = questions.map((q, i) =>\n renderBubbleRow(q, startIndex + i + 1, s),\n );\n\n // Chunk into fixed 25-row columns, then group columns into page-sized sets.\n const columns: string[] = [];\n for (let i = 0; i < rows.length; i += BUBBLE_ROWS_PER_COLUMN) {\n columns.push(\n `<div class=\"bs-column\">${rows\n .slice(i, i + BUBBLE_ROWS_PER_COLUMN)\n .join(\"\")}</div>`,\n );\n }\n const sets: string[] = [];\n for (let i = 0; i < columns.length; i += BUBBLE_COLUMNS_PER_PAGE) {\n // Pad the last set with empty columns so the surviving columns keep their\n // width — a 1-column final page must not stretch to the full 7.5in.\n const group = columns.slice(i, i + BUBBLE_COLUMNS_PER_PAGE);\n while (group.length < BUBBLE_COLUMNS_PER_PAGE) {\n group.push(`<div class=\"bs-column\"></div>`);\n }\n sets.push(`<div class=\"bs-columns\">${group.join(\"\")}</div>`);\n }\n\n const header = `<div class=\"bs-header\">\n <div class=\"bs-header-title\">${escapeHtml(test.title)} — Answer Sheet</div>\n <div class=\"bs-header-note\">Fill the bubble completely with a No. 2 pencil. Erase changes fully. Do not write outside the boxes.</div>\n <div class=\"bs-fields\">\n <div class=\"bs-field\"><div class=\"bs-field-rule\"></div><div class=\"bs-field-label\">Name</div></div>\n <div class=\"bs-field\"><div class=\"bs-field-rule\"></div><div class=\"bs-field-label\">Date</div></div>\n <div class=\"bs-field bs-field-score\"><div class=\"bs-field-rule\"></div><div class=\"bs-field-label\">Score</div></div>\n </div>\n</div>`;\n\n return `${header}\n${sets.join(\"\\n\")}`;\n}\n\n// ─── Variant: answer key ─────────────────────────────────────────────────────\n\nconst KEY_STYLES = `\n ${EXAM_BASE_STYLES}\n .ak-grid { column-count: 4; column-gap: 0.3in; }\n .ak-row {\n break-inside: avoid;\n page-break-inside: avoid;\n font-size: 10pt;\n line-height: 1.5;\n display: flex;\n gap: 6px;\n }\n .ak-num { font-weight: 600; min-width: 2em; text-align: right; }\n .ak-answer { font-weight: 700; }\n .ak-points { color: #475569; font-size: 8.5pt; margin-left: auto; }\n .ak-free { column-count: 1; }\n .ak-free .ak-answer { font-weight: 500; }\n`;\n\n/** The printed answer for a question — \"—\" when the data carries none. */\nfunction answerText(question: ExamQuestion): string {\n return question.answer ?? \"—\";\n}\n\nfunction renderAnswerKey(\n test: PracticeTestData,\n questions: readonly ExamQuestion[],\n startIndex: number,\n): string {\n const anyPoints = questions.some((q) => q.points !== undefined);\n // Free-response answers are model-answer PROSE — they can't ride a 4-column\n // grid without becoming unreadable, so they get their own single-column list.\n const compact: string[] = [];\n const prose: string[] = [];\n questions.forEach((q, i) => {\n const number = startIndex + i + 1;\n const points =\n anyPoints && q.points !== undefined\n ? `<span class=\"ak-points\">${escapeHtml(String(q.points))}</span>`\n : \"\";\n const row = `<div class=\"ak-row\" data-question=\"${number}\"><span class=\"ak-num\">${number}.</span><span class=\"ak-answer\">${escapeHtml(\n answerText(q),\n )}</span>${points}</div>`;\n (isFreeResponse(q) ? prose : compact).push(row);\n });\n\n const compactHtml =\n compact.length > 0 ? `<div class=\"ak-grid\">${compact.join(\"\")}</div>` : \"\";\n const proseHtml =\n prose.length > 0\n ? `<h3>Free-response model answers</h3><div class=\"ak-grid ak-free\">${prose.join(\n \"\",\n )}</div>`\n : \"\";\n\n return `<div class=\"ex-title\">${escapeHtml(test.title)}</div>\n<div class=\"ex-subtitle\">Answer key — keep separate from the question booklet</div>\n${compactHtml}\n${proseHtml}`;\n}\n\n// ─── Variant: explanations ───────────────────────────────────────────────────\n\nconst EXPLANATIONS_STYLES = `\n ${EXAM_BASE_STYLES}\n .exp-row {\n break-inside: avoid;\n page-break-inside: avoid;\n border-bottom: 1px solid #e2e8f0;\n padding: 6px 0;\n }\n .exp-head { display: flex; gap: 6px; font-size: 10pt; }\n .exp-num { font-weight: 700; min-width: 2em; }\n .exp-answer { font-weight: 700; }\n .exp-prompt { color: #334155; }\n .exp-body { font-size: 9.5pt; line-height: 1.45; margin: 3px 0 0 2em; color: #1f2937; }\n`;\n\nfunction renderExplanations(\n test: PracticeTestData,\n questions: readonly ExamQuestion[],\n startIndex: number,\n): string {\n const rows = questions\n .map((q, i) => {\n const number = startIndex + i + 1;\n const explanation = q.explanation\n ? `<div class=\"exp-body\">${escapeHtml(q.explanation)}</div>`\n : \"\";\n return `<div class=\"exp-row\" data-question=\"${number}\">\n <div class=\"exp-head\">\n <span class=\"exp-num\">${number}.</span>\n <span class=\"exp-prompt\">${escapeHtml(q.prompt)}</span>\n </div>\n <div class=\"exp-body\"><span class=\"exp-answer\">Answer: ${escapeHtml(\n answerText(q),\n )}</span></div>\n ${explanation}\n</div>`;\n })\n .join(\"\\n\");\n\n return `<div class=\"ex-title\">${escapeHtml(test.title)}</div>\n<div class=\"ex-subtitle\">Answers & explanations — study sheet</div>\n${rows}`;\n}\n\n// ─── The printer ─────────────────────────────────────────────────────────────\n\nconst EMPTY_MESSAGE = \"No practice-test data available to print.\";\n\n/**\n * The practice-test printer. Four variants, each an INDEPENDENT printable unit\n * (see the answer-separation law at the top of this file).\n */\nexport const practiceTestPrinter: BlockPrinter = {\n label: \"Print practice test\",\n variants: [\n {\n id: \"question-booklet\",\n label: \"Question booklet (recommended)\",\n description:\n \"Numbered questions with lettered choices and ruled work space. Contains no answers — print it once and re-use it with a fresh answer sheet each attempt\",\n },\n {\n id: \"bubble-sheet\",\n label: \"Bubble answer sheet\",\n description:\n \"The scannable answer form: name/date/score header and a fixed grid of bubble rows, 25 per column. Free-response items get a write-in line\",\n },\n {\n id: \"answer-key\",\n label: \"Answer key\",\n description:\n \"Compact multi-column key for grading. Keep it away from the booklet\",\n },\n {\n id: \"explanations\",\n label: \"Answers & explanations\",\n description:\n \"Every question with its answer and explanation, at study-sheet density\",\n },\n ],\n settings: [\n {\n type: \"range\" as const,\n id: \"questionRange\",\n label: \"Questions to print\",\n description:\n \"Leave blank to print the whole test. Question numbers stay the original ones\",\n fromId: \"fromQuestion\",\n toId: \"toQuestion\",\n defaultFrom: 0,\n defaultTo: 0,\n min: 1,\n fromPlaceholder: \"1\",\n toPlaceholder: \"end\",\n },\n {\n type: \"number\" as const,\n id: \"bubbleLetters\",\n label: \"Bubbles per row (override)\",\n description:\n \"0 = derive from each question's own choices (recommended). Set 4 or 5 to force a uniform grid\",\n defaultValue: 0,\n min: 0,\n max: CHOICE_LETTERS.length,\n appliesTo: [\"bubble-sheet\"],\n },\n {\n type: \"boolean\" as const,\n id: \"showPointsColumn\",\n label: \"Show points column\",\n description: \"Prints each question's point value beside its bubble row\",\n defaultValue: false,\n appliesTo: [\"bubble-sheet\"],\n },\n ],\n\n print(\n data: unknown,\n variantId: string = \"question-booklet\",\n rawSettings?: PrintSettings,\n ): PrintOutcome {\n const test = extractPracticeTest(data);\n const s = resolveSettings(rawSettings);\n\n if (test.questions.length === 0) {\n return openPrintWindow(\n buildPrintDocument(`<p>${EMPTY_MESSAGE}</p>`, test.title, EXAM_BASE_STYLES),\n \"practice-test\",\n );\n }\n\n const { questions, startIndex } = applyRange(test.questions, s);\n\n switch (variantId as PracticeTestVariant) {\n case \"bubble-sheet\":\n return openPrintWindow(\n buildPrintDocument(\n renderBubbleSheet(test, questions, startIndex, s),\n `${test.title} — Answer Sheet`,\n BUBBLE_STYLES,\n ),\n `${test.title}-answer-sheet`,\n );\n case \"answer-key\":\n return openPrintWindow(\n buildPrintDocument(\n renderAnswerKey(test, questions, startIndex),\n `${test.title} — Answer Key`,\n KEY_STYLES,\n ),\n `${test.title}-answer-key`,\n );\n case \"explanations\":\n return openPrintWindow(\n buildPrintDocument(\n renderExplanations(test, questions, startIndex),\n `${test.title} — Explanations`,\n EXPLANATIONS_STYLES,\n ),\n `${test.title}-explanations`,\n );\n case \"question-booklet\":\n default:\n return openPrintWindow(\n buildPrintDocument(\n renderQuestionBooklet(test, questions, startIndex),\n test.title,\n BOOKLET_VARIANT_STYLES,\n ),\n `${test.title}-questions`,\n );\n }\n },\n};\n\n/** Geometry the bubble form is built on — exported so hosts/tests can assert it. */\nexport const BUBBLE_SHEET_GEOMETRY = {\n rowsPerColumn: BUBBLE_ROWS_PER_COLUMN,\n columnsPerPage: BUBBLE_COLUMNS_PER_PAGE,\n bubbleDiameterInches: 0.16,\n rowPitchInches: 0.28,\n} as const;\n","/**\n * @ai-matrx/print/core — the Block Print contract & print-window composition.\n *\n * Ported VERBATIM from matrx-frontend `lib/block-print/block-print-utils.ts`\n * (2026-08-29 state, including the `number` and `select` PrintSetting types the\n * commerce label lane added). Zero dependencies; touches `window` only at call\n * time, so the module stays import-inert and RSC-safe.\n *\n * BlockPrinter is the only interface a host system needs to know about.\n * Each printable unit exports its own BlockPrinter alongside its render\n * component; host code only ever calls print(data, variantId, settings).\n *\n * `buildFitTextScript` is the ONE auto-shrink script (the flashcards\n * FIT_TEXT pattern, parameterized by selector so the label lane shares it).\n */\n\n// THE ONE HTML escaper (duplication census row 14). Nine copies of\n// `escapeHtml` were live across the fleet and THEY DID NOT ESCAPE THE SAME\n// CHARACTERS — a string safe through one was an attribute break-out through\n// another. It moved to `@ai-matrx/kit/html-escape` with a decided character\n// set: an HTML escaper must not require this package's jspdf + html2canvas\n// graph. Not re-exported from here; import `@ai-matrx/kit/html-escape`.\nimport { escapeHtml } from \"@ai-matrx/kit/html-escape\";\n\n// ─── Contract ────────────────────────────────────────────────────────────────\n\nexport interface PrintVariant {\n id: string;\n label: string;\n description?: string;\n}\n\n/**\n * A single user-configurable setting shown in the print dialog.\n * Extend the discriminated union for new control types\n * without breaking existing printers.\n */\nexport type PrintSetting =\n | {\n type: \"boolean\";\n id: string;\n label: string;\n description?: string;\n /** Default value shown when the dialog first opens */\n defaultValue: boolean;\n /** Which variant IDs this setting applies to. Omit = applies to all. */\n appliesTo?: string[];\n }\n | {\n /**\n * A numeric \"from → to\" range control, rendered as two small number inputs.\n * Writes two entries into the resolved PrintSettings map — one under fromId,\n * one under toId. Printers interpret 0 (or missing) as \"no bound\" by convention.\n */\n type: \"range\";\n /** Stable id used as React key — not written to the settings map */\n id: string;\n label: string;\n description?: string;\n /** Settings map key for the lower bound value */\n fromId: string;\n /** Settings map key for the upper bound value */\n toId: string;\n defaultFrom: number;\n defaultTo: number;\n /** Minimum accepted value for each input (inclusive). Default 0. */\n min?: number;\n /** Placeholder shown when the input is empty (0). Default \"start\" / \"end\". */\n fromPlaceholder?: string;\n toPlaceholder?: string;\n /** Which variant IDs this setting applies to. Omit = applies to all. */\n appliesTo?: string[];\n }\n | {\n /** A single numeric input (e.g. \"start at label #\", \"copies\"). */\n type: \"number\";\n id: string;\n label: string;\n description?: string;\n defaultValue: number;\n /** Minimum accepted value (inclusive). Default 0. */\n min?: number;\n /** Maximum accepted value (inclusive). Omit = unbounded. */\n max?: number;\n /** Which variant IDs this setting applies to. Omit = applies to all. */\n appliesTo?: string[];\n }\n | {\n /** A one-of-N choice rendered as a compact segmented row. */\n type: \"select\";\n id: string;\n label: string;\n description?: string;\n options: { value: string; label: string }[];\n defaultValue: string;\n /** Which variant IDs this setting applies to. Omit = applies to all. */\n appliesTo?: string[];\n };\n\n/** A resolved map of setting id → current value, passed to print(). */\nexport type PrintSettings = Record<string, boolean | string | number>;\n\n/**\n * The self-contained print capability that each block can export.\n * Host code only ever calls print(data, variantId, settings) — it never inspects internals.\n */\nexport interface BlockPrinter {\n /** Tooltip / aria-label for the print button in the block header */\n label: string;\n\n /**\n * Variants offered to the user before printing.\n * Empty array = no options dialog shown; prints immediately with defaults.\n */\n variants: PrintVariant[];\n\n /**\n * Optional user-configurable settings shown below the variant picker.\n * Omit entirely if the block has no configurable settings.\n */\n settings?: PrintSetting[];\n\n /**\n * Execute the print.\n * data — the block's structured data (serverData or parsed content)\n * variantId — which variant was chosen (undefined = default / no variants)\n * settings — resolved setting values chosen by the user\n *\n * MAY resolve to a PrintOutcome (\"opened\" | \"downloaded\") so the host can\n * tell the user when the popup-blocked download fallback fired; `void`\n * stays legal for printers that don't go through a print window.\n */\n print: (\n data: unknown,\n variantId?: string,\n settings?: PrintSettings,\n ) => void | PrintOutcome | Promise<void | PrintOutcome>;\n}\n\n// ─── Shared Utilities ─────────────────────────────────────────────────────────\n\nconst PRINT_STYLES = `\n *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }\n\n body {\n font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Helvetica Neue', Arial, sans-serif;\n font-size: 11pt;\n line-height: 1.6;\n color: #1a1a1a;\n background: #fff;\n max-width: 860px;\n margin: 0 auto;\n padding: 28px 36px;\n }\n\n .print-actions {\n display: flex;\n gap: 10px;\n margin-bottom: 24px;\n padding-bottom: 18px;\n border-bottom: 2px solid #e5e7eb;\n }\n\n .print-btn {\n display: inline-flex;\n align-items: center;\n gap: 6px;\n padding: 8px 20px;\n border-radius: 8px;\n font-size: 13px;\n font-family: inherit;\n cursor: pointer;\n border: none;\n font-weight: 600;\n }\n\n .print-btn-primary { background: #2563eb; color: #fff; }\n .print-btn-secondary { background: #f3f4f6; color: #374151; border: 1px solid #d1d5db; }\n\n h1 { font-size: 22pt; font-weight: 700; margin-bottom: 0.5em; }\n h2 { font-size: 16pt; font-weight: 700; margin: 1.2em 0 0.4em; border-bottom: 1px solid #e5e7eb; padding-bottom: 0.2em; }\n h3 { font-size: 13pt; font-weight: 600; margin: 1em 0 0.3em; }\n p { margin-bottom: 0.7em; }\n\n table {\n width: 100%;\n border-collapse: collapse;\n margin: 1em 0;\n font-size: 10pt;\n }\n th {\n background: #1e293b;\n color: #f8fafc;\n font-weight: 600;\n text-align: left;\n padding: 7px 12px;\n border: 1px solid #334155;\n }\n td {\n padding: 6px 12px;\n border: 1px solid #e2e8f0;\n vertical-align: top;\n }\n tr:nth-child(even) td { background: #f8fafc; }\n\n @media print {\n body { max-width: 100%; padding: 0; }\n .print-actions { display: none !important; }\n th { -webkit-print-color-adjust: exact; print-color-adjust: exact; }\n }\n`;\n\n/**\n * Wrap body HTML in a complete, styled print document.\n */\nexport function buildPrintDocument(\n bodyHtml: string,\n title = \"AI Response\",\n extraStyles = \"\",\n): string {\n return `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"UTF-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n <title>${escapeHtml(title)}</title>\n <style>\n${PRINT_STYLES}\n${extraStyles}\n </style>\n</head>\n<body>\n <div class=\"print-actions\">\n <button class=\"print-btn print-btn-primary\" onclick=\"window.print()\">Print / Save as PDF</button>\n <button class=\"print-btn print-btn-secondary\" onclick=\"window.close()\">Close</button>\n </div>\n <div class=\"content\">\n${bodyHtml}\n </div>\n</body>\n</html>`;\n}\n\n/**\n * How a print request actually reached the user.\n *\n * \"opened\" — a print window/tab was opened and the document written into it.\n * \"downloaded\" — the popup was blocked, so the document was downloaded as an\n * .html file instead (the contract's fallback). Hosts SHOULD\n * surface this to the user (e.g. a toast saying the print file\n * was downloaded) — a blocked popup plus a silent download is\n * indistinguishable from \"nothing happened\", which is exactly\n * how QA filed it (2026-08-30, F5/F6/F8).\n */\nexport type PrintOutcome = \"opened\" | \"downloaded\";\n\n/**\n * Open a new browser window and write a complete HTML document into it.\n * Falls back to downloading an .html file if the popup is blocked.\n *\n * Returns which path was taken so callers can tell the user when the\n * fallback fired. `windowFeatures` customizes the popup geometry (the\n * flashcards fixed-geometry variants pass a wider window).\n */\nexport function openPrintWindow(\n htmlDocument: string,\n filename = \"print\",\n windowFeatures = \"width=920,height=720,scrollbars=yes\",\n): PrintOutcome {\n const win = window.open(\"\", \"_blank\", windowFeatures);\n if (!win) {\n // Popup blocked — fall back to file download\n const blob = new Blob([htmlDocument], { type: \"text/html;charset=utf-8\" });\n const url = URL.createObjectURL(blob);\n const a = document.createElement(\"a\");\n a.href = url;\n a.download = `${filename.replace(/\\s+/g, \"-\").toLowerCase()}.html`;\n document.body.appendChild(a);\n a.click();\n document.body.removeChild(a);\n // Revoke on a macrotask so the browser has started the blob fetch —\n // a synchronous revoke races the download in some engines.\n setTimeout(() => URL.revokeObjectURL(url), 0);\n return \"downloaded\";\n }\n win.document.open();\n win.document.write(htmlDocument);\n win.document.close();\n return \"opened\";\n}\n\n/**\n * Shorthand: build the document and open it in one call.\n * Returns the same PrintOutcome as openPrintWindow.\n */\nexport function printHtmlContent(\n bodyHtml: string,\n title = \"AI Response\",\n extraStyles = \"\",\n): PrintOutcome {\n const doc = buildPrintDocument(bodyHtml, title, extraStyles);\n return openPrintWindow(doc, title);\n}\n\n/**\n * Build the auto-shrink script that runs INSIDE a printed window: for every\n * element matching each selector, its font-size is reduced (0.5pt steps, 6pt\n * floor) until it fits its parent element's box. This is the flashcards\n * FIT_TEXT behavior verbatim, parameterized by selector so every lane\n * (flashcards card text, Avery text, label captions) shares the ONE loop.\n *\n * Pass the same selectors the original used to get byte-identical behavior:\n * flashcards passes `[\".card-text .card-text-inner\", \".avery-text-wrap .avery-text\"]`.\n */\nexport function buildFitTextScript(selectors: readonly string[]): string {\n const selectorsJson = JSON.stringify([...selectors]);\n return `\n<script>\n(function() {\n function fitText(el, container) {\n // container is the bounding box we must fit inside\n var maxW = container.clientWidth;\n var maxH = container.clientHeight;\n var size = parseFloat(window.getComputedStyle(el).fontSize);\n var minSize = 6;\n // Give the element a chance to reflow at current size before measuring\n el.style.fontSize = size + \"pt\";\n while (size > minSize && (el.scrollWidth > maxW + 1 || el.scrollHeight > maxH + 1)) {\n size -= 0.5;\n el.style.fontSize = size + \"pt\";\n }\n }\n function runAll() {\n var selectors = ${selectorsJson};\n for (var s = 0; s < selectors.length; s++) {\n var els = document.querySelectorAll(selectors[s]);\n for (var i = 0; i < els.length; i++) {\n fitText(els[i], els[i].parentElement);\n }\n }\n }\n if (document.readyState === \"loading\") {\n document.addEventListener(\"DOMContentLoaded\", runAll);\n } else {\n // document.write pages may already be loaded\n setTimeout(runAll, 0);\n }\n})();\n</script>`;\n}\n\n"],"mappings":"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","names":["import_html_escape"]}

package/dist/exam.d.cts ADDED Viewed

@@ -0,0 +1,69 @@
+import { BlockPrinter } from './core.cjs';
+/**
+ * @ai-matrx/print/exam — the practice-test lane (question booklet, bubble
+ * answer form, answer key, explanations).
+ *
+ * ── THE ANSWER-SEPARATION LAW ───────────────────────────────────────────────
+ * The education research (PRINT-EDUCATION-RESEARCH.md, P0 row "Practice test
+ * booklets + bubble answer sheets", modeled on Barron's / Princeton Review AP
+ * and Kaplan) is explicit: the question booklet, the scannable bubble form and
+ * the answer key are SEPARATE printable units. That is not a styling
+ * preference — it is what makes a practice test re-usable: a student prints
+ * ONE booklet and a fresh blank bubble form per attempt, and the key never
+ * travels with the questions. So `question-booklet` emits no answers and no
+ * explanations at all (there is a test asserting their ABSENCE), and every
+ * variant here is an independently printable document.
+ *
+ * ── WHY THERE IS NO "SHUFFLE" SETTING ───────────────────────────────────────
+ * Question order and choice order are DATA, not presentation. A printer that
+ * shuffled would desynchronize the three units above — a bubble form or key
+ * printed in a different session would no longer match the booklet, silently.
+ * Shuffling belongs to whatever generates the PracticeTestData (where the
+ * shuffled order can be persisted once and reused by all three units).
+ *
+ * Zero dependencies; `window` is touched only inside `print`, at call time, so
+ * the module stays import-inert and RSC-safe.
+ */
+interface ExamChoice {
+    /** Optional explicit label. Omitted = auto-lettered A, B, C, … by position. */
+    label?: string;
+    text: string;
+}
+interface ExamQuestion {
+    prompt: string;
+    /** Omitted or empty = free-response (ruled work space instead of bubbles). */
+    choices?: ExamChoice[];
+    /** The correct choice label (or, for free response, the model answer text). */
+    answer?: string;
+    explanation?: string;
+    points?: number;
+    /** Ruled lines to print under a free-response question in the booklet. */
+    workSpaceLines?: number;
+}
+interface PracticeTestData {
+    title: string;
+    instructions?: string;
+    questions: ExamQuestion[];
+}
+type PracticeTestVariant = "question-booklet" | "bubble-sheet" | "answer-key" | "explanations";
+/**
+ * Accept the canonical shape, a bare questions array, or a wrapper object that
+ * carries one — the same tolerance the flashcards lane offers its hosts.
+ */
+declare function extractPracticeTest(data: unknown): PracticeTestData;
+/**
+ * The practice-test printer. Four variants, each an INDEPENDENT printable unit
+ * (see the answer-separation law at the top of this file).
+ */
+declare const practiceTestPrinter: BlockPrinter;
+/** Geometry the bubble form is built on — exported so hosts/tests can assert it. */
+declare const BUBBLE_SHEET_GEOMETRY: {
+    readonly rowsPerColumn: 25;
+    readonly columnsPerPage: 4;
+    readonly bubbleDiameterInches: 0.16;
+    readonly rowPitchInches: 0.28;
+};
+export { BUBBLE_SHEET_GEOMETRY, type ExamChoice, type ExamQuestion, type PracticeTestData, type PracticeTestVariant, extractPracticeTest, practiceTestPrinter };

package/dist/exam.d.ts ADDED Viewed

@@ -0,0 +1,69 @@
+import { BlockPrinter } from './core.js';
+/**
+ * @ai-matrx/print/exam — the practice-test lane (question booklet, bubble
+ * answer form, answer key, explanations).
+ *
+ * ── THE ANSWER-SEPARATION LAW ───────────────────────────────────────────────
+ * The education research (PRINT-EDUCATION-RESEARCH.md, P0 row "Practice test
+ * booklets + bubble answer sheets", modeled on Barron's / Princeton Review AP
+ * and Kaplan) is explicit: the question booklet, the scannable bubble form and
+ * the answer key are SEPARATE printable units. That is not a styling
+ * preference — it is what makes a practice test re-usable: a student prints
+ * ONE booklet and a fresh blank bubble form per attempt, and the key never
+ * travels with the questions. So `question-booklet` emits no answers and no
+ * explanations at all (there is a test asserting their ABSENCE), and every
+ * variant here is an independently printable document.
+ *
+ * ── WHY THERE IS NO "SHUFFLE" SETTING ───────────────────────────────────────
+ * Question order and choice order are DATA, not presentation. A printer that
+ * shuffled would desynchronize the three units above — a bubble form or key
+ * printed in a different session would no longer match the booklet, silently.
+ * Shuffling belongs to whatever generates the PracticeTestData (where the
+ * shuffled order can be persisted once and reused by all three units).
+ *
+ * Zero dependencies; `window` is touched only inside `print`, at call time, so
+ * the module stays import-inert and RSC-safe.
+ */
+interface ExamChoice {
+    /** Optional explicit label. Omitted = auto-lettered A, B, C, … by position. */
+    label?: string;
+    text: string;
+}
+interface ExamQuestion {
+    prompt: string;
+    /** Omitted or empty = free-response (ruled work space instead of bubbles). */
+    choices?: ExamChoice[];
+    /** The correct choice label (or, for free response, the model answer text). */
+    answer?: string;
+    explanation?: string;
+    points?: number;
+    /** Ruled lines to print under a free-response question in the booklet. */
+    workSpaceLines?: number;
+}
+interface PracticeTestData {
+    title: string;
+    instructions?: string;
+    questions: ExamQuestion[];
+}
+type PracticeTestVariant = "question-booklet" | "bubble-sheet" | "answer-key" | "explanations";
+/**
+ * Accept the canonical shape, a bare questions array, or a wrapper object that
+ * carries one — the same tolerance the flashcards lane offers its hosts.
+ */
+declare function extractPracticeTest(data: unknown): PracticeTestData;
+/**
+ * The practice-test printer. Four variants, each an INDEPENDENT printable unit
+ * (see the answer-separation law at the top of this file).
+ */
+declare const practiceTestPrinter: BlockPrinter;
+/** Geometry the bubble form is built on — exported so hosts/tests can assert it. */
+declare const BUBBLE_SHEET_GEOMETRY: {
+    readonly rowsPerColumn: 25;
+    readonly columnsPerPage: 4;
+    readonly bubbleDiameterInches: 0.16;
+    readonly rowPitchInches: 0.28;
+};
+export { BUBBLE_SHEET_GEOMETRY, type ExamChoice, type ExamQuestion, type PracticeTestData, type PracticeTestVariant, extractPracticeTest, practiceTestPrinter };