@panaversity/ksor 0.0.26 → 0.0.28

package/templates/scaffold/system/site/components/ui/progress.tsx

@@ -0,0 +1,29 @@
+// Generated by `pnpm dlx shadcn@latest add progress`. Yours to edit.
+"use client";
+
+import * as React from "react";
+import { Progress as ProgressPrimitive } from "radix-ui";
+
+import { cn } from "@/lib/utils";
+
+function Progress({
+  className,
+  value,
+  ...props
+}: React.ComponentProps<typeof ProgressPrimitive.Root>) {
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      className={cn("relative h-2 w-full overflow-hidden rounded-full bg-primary/20", className)}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className="h-full w-full flex-1 bg-primary transition-all"
+        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+      />
+    </ProgressPrimitive.Root>
+  );
+}
+
+export { Progress };

package/templates/scaffold/system/site/lib/attachment-rule.ts

@@ -0,0 +1,124 @@
+/**
+ * What makes a file in the record an ATTACHMENT rather than a document.
+ *
+ * A document may carry study attachments named after it — `x.summary.md` and
+ * `x.flashcards.yaml` belong to `x.md` in the same directory. An attachment is
+ * PART OF its parent: no route, no sidebar entry, no llms.txt line, no stable
+ * id, no MCP node, and its parent's governance rather than its own.
+ *
+ * This rule is duplicated by construction — the kernel's ingest decides what
+ * becomes a node, the site's staging decides what is copied, the site's build
+ * decides what is a page, and the record's checker decides what is well-formed.
+ * Four readers of one rule is exactly the shape decision 18 names, so this file
+ * is canonical and every other copy is asserted against it rather than trusted.
+ *
+ * A LEAF: no imports, so any of those four can take it without taking anything
+ * else with it.
+ */
+
+/** The suffix that marks each kind, longest-match first. */
+export const ATTACHMENT_SUFFIXES = [
+  { suffix: ".summary.md", kind: "summary" },
+  { suffix: ".summary.mdx", kind: "summary" },
+  { suffix: ".flashcards.yaml", kind: "deck" },
+] as const;
+
+export type AttachmentKind = (typeof ATTACHMENT_SUFFIXES)[number]["kind"];
+
+/**
+ * The near-miss extensions, refused BY NAME rather than left to fail later.
+ *
+ * `.yml` is the one an author reaches for by habit, and fumadocs' meta loader
+ * accepts `.yaml`/`.json` only — anything else throws `Unknown file type`,
+ * naming the path and nothing about the rule (verified in fumadocs-mdx@15.3.0,
+ * dist/meta-BR_rkCyY.js). A refusal here costs one line and replaces that.
+ */
+export const ATTACHMENT_NEAR_MISSES = [
+  { suffix: ".flashcards.yml", want: ".flashcards.yaml" },
+  { suffix: ".flashcards.json", want: ".flashcards.yaml" },
+  { suffix: ".summary.markdown", want: ".summary.md" },
+] as const;
+
+/**
+ * The attachment kind this file name carries, or null when it is not one.
+ *
+ * Matched on the whole base name, never on a path: `.summary.md` in a directory
+ * called `summary` is not an attachment, and a file called exactly
+ * `.summary.md` (a dotfile with no stem) has no parent to attach to and is not
+ * one either — the same "a dotfile has no suffix" boundary ingest's isDoc uses.
+ */
+export function attachmentKindOf(baseName: string): AttachmentKind | null {
+  for (const entry of ATTACHMENT_SUFFIXES) {
+    if (baseName.length > entry.suffix.length && baseName.endsWith(entry.suffix)) {
+      return entry.kind;
+    }
+  }
+  return null;
+}
+
+/** True when this file name is an attachment of some document. */
+export function isAttachment(baseName: string): boolean {
+  return attachmentKindOf(baseName) !== null;
+}
+
+/**
+ * The base name of the document this attachment belongs to, or null when the
+ * name is not an attachment. Always `<stem>.md`: the record is CommonMark, so
+ * a parent is a `.md` file even where the attachment itself is `.mdx`.
+ */
+export function parentDocumentOf(baseName: string): string | null {
+  for (const entry of ATTACHMENT_SUFFIXES) {
+    if (baseName.length > entry.suffix.length && baseName.endsWith(entry.suffix)) {
+      return `${baseName.slice(0, -entry.suffix.length)}.md`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The extension an author probably meant, when a name is one character off a
+ * real attachment. Null when the name is not a near miss.
+ */
+export function nearMissOf(
+  baseName: string,
+): { readonly is: string; readonly want: string } | null {
+  for (const entry of ATTACHMENT_NEAR_MISSES) {
+    if (baseName.length > entry.suffix.length && baseName.endsWith(entry.suffix)) {
+      return { is: entry.suffix, want: entry.want };
+    }
+  }
+  return null;
+}
+
+/**
+ * The cases every implementation of this rule must agree on.
+ *
+ * The rule lives in four languages — TypeScript here, TypeScript again in the
+ * site's staging, a glob in source.config.ts, and plain JS in the record's
+ * checker — and the three copies cannot import this file. So the TABLE is the
+ * rule, asserted against each implementation, the way AUDIENCE_CASES is
+ * (decision 18). A copy that drifts fails on the ROW it broke.
+ */
+export const ATTACHMENT_CASES = [
+  { name: "returns.summary.md", kind: "summary", parent: "returns.md" },
+  { name: "returns.flashcards.yaml", kind: "deck", parent: "returns.md" },
+  { name: "index.summary.md", kind: "summary", parent: "index.md" },
+  // A stem containing dots keeps every one of them: the parent is the same
+  // name with the attachment suffix removed, never "up to the first dot".
+  { name: "v1.2.policy.summary.md", kind: "summary", parent: "v1.2.policy.md" },
+  // Ordinary documents, including ones whose names merely CONTAIN the words.
+  { name: "returns.md", kind: null, parent: null },
+  { name: "summary.md", kind: null, parent: null },
+  { name: "flashcards.yaml", kind: null, parent: null },
+  { name: "my-summary.md", kind: null, parent: null },
+  // A dotfile with no stem attaches to nothing — refused as an attachment so
+  // it is refused as an unexpected file instead, which is the honest error.
+  { name: ".summary.md", kind: null, parent: null },
+  { name: ".flashcards.yaml", kind: null, parent: null },
+  // Case matters: the record already refuses two names differing only in case,
+  // so an uppercase suffix is a different file, not the same rule.
+  { name: "returns.SUMMARY.md", kind: null, parent: null },
+  // Not attachments — near misses, which get their own refusal.
+  { name: "returns.flashcards.yml", kind: null, parent: null },
+  { name: "returns.flashcards.json", kind: null, parent: null },
+] as const;

package/templates/scaffold/system/site/lib/attachments.ts

@@ -0,0 +1,105 @@
+import { decks, summaries } from "collections/server";
+
+import { ATTACHMENT_SUFFIXES } from "./attachment-rule";
+import { cardHash, type Card, type Deck } from "./deck";
+import { newCard, type CardSchedule } from "./srs";
+
+/**
+ * Finding a document's study attachments.
+ *
+ * Both collections are keyed by their record-relative path (fumadocs'
+ * `info.path`), which is the same shape as a page's own `page.path` — so the
+ * lookup is a suffix swap, not a second index to keep in step. `x.md` finds
+ * `x.summary.md` and `x.flashcards.yaml`, and nothing else can be reached.
+ *
+ * Neither collection is ever handed to `loader()`, which is what keeps an
+ * attachment off the route table, the sidebar, llms.txt, llms-full.txt, the
+ * markdown twin and the search index — see source.config.ts.
+ */
+
+const DOC_SUFFIX = /\.mdx?$/;
+
+/** `policies/returns.md` + `.summary.md` → `policies/returns.summary.md`. */
+function attachmentPath(documentPath: string, suffix: string): string {
+  return documentPath.replace(DOC_SUFFIX, "") + suffix;
+}
+
+export interface SummaryEntry {
+  readonly body: (props: { components?: Record<string, unknown> }) => React.ReactElement;
+  readonly toc: unknown;
+  /**
+   * The summary's processed markdown, for counting its reading time. The
+   * collection enables `includeProcessedMarkdown` so this is in memory —
+   * `"raw"` would go back to disk and resolve against the wrong base.
+   */
+  readonly getText: (type: "raw" | "processed") => Promise<string>;
+}
+
+/**
+ * The summary for a document, or null when it has none.
+ *
+ * Null is the ordinary case and never an error: the feature is presence-driven,
+ * so a document with no summary renders no tab strip at all rather than an
+ * empty one.
+ */
+export function summaryFor(documentPath: string): SummaryEntry | null {
+  const wanted = attachmentPath(documentPath, ".summary.md");
+  const wantedMdx = attachmentPath(documentPath, ".summary.mdx");
+  const hit = summaries.find(
+    (entry) => entry.info.path === wanted || entry.info.path === wantedMdx,
+  );
+  return hit === undefined ? null : (hit as unknown as SummaryEntry);
+}
+
+/** One card as the deck UI consumes it: authored text plus its identity. */
+export interface DeckCard extends Card {
+  /** Identity: a hash of the card's own text, so an edit resets only this card. */
+  readonly hash: string;
+}
+
+export interface DeckEntry {
+  readonly title: string;
+  readonly description?: string;
+  readonly cards: readonly DeckCard[];
+  /**
+   * The deck's identity, used to key persisted review state. The record-relative
+   * path — never an authored id, because the path IS the identity here.
+   */
+  readonly path: string;
+}
+
+/** The deck for a document, or null when it has none. */
+export function deckFor(documentPath: string): DeckEntry | null {
+  const wanted = attachmentPath(documentPath, ".flashcards.yaml");
+  const hit = decks.find((entry) => entry.info.path === wanted);
+  if (hit === undefined) return null;
+
+  const parsed = hit as unknown as Deck & { readonly info: { readonly path: string } };
+  return {
+    title: parsed.deck.title,
+    description: parsed.deck.description,
+    path: parsed.info.path,
+    cards: parsed.cards.map((card) => ({ ...card, hash: cardHash(card) })),
+  };
+}
+
+/** True when a document has either attachment — the presence gate for the UI. */
+export function hasAttachments(documentPath: string): boolean {
+  return summaryFor(documentPath) !== null || deckFor(documentPath) !== null;
+}
+
+/**
+ * A fresh schedule for every card in a deck, all due now.
+ *
+ * Exported so the deck's first render and its reset path agree by construction
+ * rather than by two similar-looking object literals.
+ */
+export function freshSchedules(
+  cards: readonly DeckCard[],
+  now: number,
+): Record<string, CardSchedule> {
+  return Object.fromEntries(cards.map((card) => [card.hash, newCard(card.hash, now)]));
+}
+
+/** Every attachment suffix, for the surfaces that need the list rather than the rule. */
+export const ATTACHMENT_SUFFIX_LIST: readonly string[] = ATTACHMENT_SUFFIXES.map((e) => e.suffix);

package/templates/scaffold/system/site/lib/deck.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+/**
+ * The shape of a `<doc>.flashcards.yaml` deck.
+ *
+ * NO AUTHORED IDS, anywhere — not on the deck, not on a card. The record's
+ * third principle is that identity derives from the file path, and the checker
+ * refuses `id:`/`name:` on a document for exactly this reason. A deck's
+ * identity is its path; a CARD's identity is its own text, hashed
+ * (`cardHash`), which is also what makes a per-card reset possible: an edited
+ * card is a different card, and every card the author did not touch keeps its
+ * review history.
+ *
+ * The predecessor authored `deck.id`, `card.id` AND `deck.version` by hand. The
+ * version decided nothing (it was logged, never acted on) and the ids were a
+ * second identity to keep in step with the filename.
+ */
+export const CardSchema = z.object({
+  front: z.string().min(1).max(300),
+  back: z.string().min(1).max(600),
+  /** An optional prompt that turns a recall check into a thinking one. */
+  why: z.string().max(240).optional(),
+});
+
+export const DeckSchema = z.object({
+  deck: z.object({
+    title: z.string().min(1).max(120),
+    description: z.string().max(300).optional(),
+  }),
+  cards: z.array(CardSchema).min(1).max(60),
+});
+
+export type Deck = z.infer<typeof DeckSchema>;
+export type Card = z.infer<typeof CardSchema>;
+
+/**
+ * A card's identity: a stable hash of the text a learner actually sees.
+ *
+ * FNV-1a, 32-bit, hand-rolled — the site has no crypto import at build time and
+ * this needs to run identically in the browser. Collisions cost a single card's
+ * review history, never correctness, so 32 bits is the right size of hammer.
+ *
+ * `why` is deliberately NOT hashed: it is a hint about the card, not the card,
+ * and rewording it should not throw away a learner's history with the card.
+ */
+export function cardHash(card: Card): string {
+  // NUL as the separator, written as an escape rather than embedded: a raw
+  // NUL in the source makes git treat this file as binary. It has to be a
+  // separator of some kind — without one, front "ab"/back "c" hashes the same
+  // as front "a"/back "bc" — and NUL is the one character authored card text
+  // cannot contain.
+  const text = `${card.front}\u0000${card.back}`;
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}

package/templates/scaffold/system/site/lib/reading-time.ts

@@ -0,0 +1,45 @@
+/**
+ * How long a document takes to read.
+ *
+ * Computed at BUILD time from the document's own markdown, so the figure is in
+ * the server-rendered HTML — a reader with a failed bundle, a crawler and an
+ * agent parsing the page all get it. The predecessor measured `article.
+ * textContent` in the browser after paint, which put the number out of reach of
+ * every one of them.
+ *
+ * A LEAF: no imports, so it can be tested in isolation.
+ */
+
+/**
+ * Words per minute for prose.
+ *
+ * 200 is the conventional figure for adult silent reading of ordinary text and
+ * is what the predecessor used. It is a rough number, and the clock beside it
+ * is what says so — nobody reads a time next to a clock icon as a promise. A
+ * governed record's prose is denser than a novel's, so if anything this reads
+ * slightly fast.
+ */
+export const WORDS_PER_MINUTE = 200;
+
+/**
+ * Fenced code is not read at prose speed — it is scanned, or studied, but
+ * either way counting its tokens as words inflates the estimate badly on a
+ * technical document. It is removed before counting rather than weighted:
+ * a weight would be a second invented number on top of the first.
+ */
+const FENCED_CODE = /^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[ \t]*$/gm;
+
+/** Frontmatter is metadata, not prose, and is never shown to the reader. */
+const FRONTMATTER = /^?---\n[\s\S]*?\n---[ \t]*\n/;
+
+/**
+ * Minutes to read this markdown, rounded to the nearest minute and never zero:
+ * a document that exists takes some time to read, and "0 min read" is a
+ * sentence no reader has use for.
+ */
+export function readingMinutes(markdown: string): number {
+  const prose = markdown.replace(/\r\n/g, "\n").replace(FRONTMATTER, "").replace(FENCED_CODE, " ");
+  const words = prose.split(/\s+/).filter((word) => /[\p{L}\p{N}]/u.test(word)).length;
+  if (words === 0) return 1;
+  return Math.max(1, Math.round(words / WORDS_PER_MINUTE));
+}

package/templates/scaffold/system/site/lib/srs.ts

@@ -0,0 +1,219 @@
+/**
+ * Review scheduling for flashcard decks.
+ *
+ * A two-grade SM-2 variant. It is NOT FSRS, it models no memory, and it makes
+ * no retention guarantee — see `SCHEDULER_POLICY` and the note at the foot of
+ * this file. Naming it for what it is costs nothing and stops a future reader
+ * assuming a probabilistic guarantee that was never here.
+ *
+ * A LEAF and a pure function: `(schedule, rating, now) -> schedule`. No React,
+ * no storage, no ambient clock — `now` is always passed in, which is what makes
+ * the whole transition table assertable against a frozen clock.
+ */
+
+/** Persisted beside the state, so a stored record always says what wrote it. */
+export const SCHEDULER_POLICY = "ksor-sm2-v1";
+
+/** New | Learning | Review | Relearning. */
+export type CardState = 0 | 1 | 2 | 3;
+
+export type Rating = "again" | "good";
+
+export interface CardSchedule {
+  readonly state: CardState;
+  /** Index into the active step ladder while sub-day; 0 in Review. */
+  readonly step: number;
+  /** The last scheduled interval in days; 0 while sub-day. */
+  readonly intervalDays: number;
+  /** The interval a lapse interrupted, remembered so re-graduation can halve it. */
+  readonly lapsedIntervalDays: number;
+  /** Growth multiplier, clamped to [EASE_MIN, EASE_START]. */
+  readonly ease: number;
+  readonly reps: number;
+  readonly lapses: number;
+  readonly dueMs: number;
+  readonly lastReviewMs?: number;
+  /** Hash of the card's authored text — a change resets THIS card only. */
+  readonly hash: string;
+}
+
+const MINUTE_MS = 60_000;
+const DAY_MS = 86_400_000;
+
+// Every constant below is a choice. FSRS's own defaults are named where ours
+// match them, so a future reader can see which numbers are inherited and which
+// are ours.
+/** Matches FSRS's default learning steps. */
+export const LEARNING_STEPS_MIN: readonly number[] = [1, 10];
+/** Matches FSRS's default relearning steps. */
+export const RELEARNING_STEPS_MIN: readonly number[] = [10];
+/** Matches FSRS's observed New → Good → Good interval. */
+export const GRADUATING_INTERVAL_DAYS = 2;
+export const EASE_START = 2.5;
+export const EASE_MIN = 1.3;
+export const EASE_LAPSE_PENALTY = 0.2;
+/** A re-graduated card returns at half the interval its lapse interrupted. */
+export const LAPSE_INTERVAL_FACTOR = 0.5;
+/** Ten years. FSRS ships a hundred; a century is not a claim this can make. */
+export const MAX_INTERVAL_DAYS = 3650;
+export const MIN_REVIEW_INTERVAL_DAYS = 1;
+
+export function newCard(hash: string, now: number): CardSchedule {
+  return {
+    state: 0,
+    step: 0,
+    intervalDays: 0,
+    lapsedIntervalDays: 0,
+    ease: EASE_START,
+    reps: 0,
+    lapses: 0,
+    dueMs: now,
+    hash,
+  };
+}
+
+function clamp(value: number, low: number, high: number): number {
+  return Math.min(high, Math.max(low, value));
+}
+
+/** Advance along a sub-day ladder, or null when the ladder is finished. */
+function nextRung(steps: readonly number[], step: number): number | null {
+  return step + 1 < steps.length ? step + 1 : null;
+}
+
+/**
+ * The next schedule for a card, given how the learner graded it and when.
+ *
+ * Never mutates its input: review state is persisted, and an in-place update
+ * that a failed write leaves half-applied is a corrupt record.
+ */
+export function schedule(card: CardSchedule, rating: Rating, now: number): CardSchedule {
+  const base = { ...card, reps: card.reps + 1, lastReviewMs: now };
+
+  if (card.state === 0) {
+    // New. Again starts the ladder; Good skips its first rung — a card the
+    // learner already knows should not be asked again in sixty seconds.
+    const step = rating === "again" ? 0 : Math.min(1, LEARNING_STEPS_MIN.length - 1);
+    return {
+      ...base,
+      state: 1,
+      step,
+      dueMs: now + (LEARNING_STEPS_MIN[step] ?? 1) * MINUTE_MS,
+    };
+  }
+
+  if (card.state === 1 || card.state === 3) {
+    const relearning = card.state === 3;
+    const steps = relearning ? RELEARNING_STEPS_MIN : LEARNING_STEPS_MIN;
+
+    if (rating === "again") {
+      return { ...base, step: 0, dueMs: now + (steps[0] ?? 1) * MINUTE_MS };
+    }
+
+    const advanced = nextRung(steps, card.step);
+    if (advanced !== null) {
+      return { ...base, step: advanced, dueMs: now + (steps[advanced] ?? 1) * MINUTE_MS };
+    }
+
+    // Graduating. A first graduation takes the fixed interval; a RE-graduation
+    // takes half the interval its lapse interrupted, so a card that was on a
+    // 40-day interval does not restart from two days.
+    const intervalDays = relearning
+      ? clamp(
+          Math.round(card.lapsedIntervalDays * LAPSE_INTERVAL_FACTOR),
+          MIN_REVIEW_INTERVAL_DAYS,
+          MAX_INTERVAL_DAYS,
+        )
+      : GRADUATING_INTERVAL_DAYS;
+
+    return { ...base, state: 2, step: 0, intervalDays, dueMs: now + intervalDays * DAY_MS };
+  }
+
+  // Review.
+  if (rating === "again") {
+    return {
+      ...base,
+      state: 3,
+      step: 0,
+      lapses: card.lapses + 1,
+      ease: Math.max(EASE_MIN, card.ease - EASE_LAPSE_PENALTY),
+      lapsedIntervalDays: card.intervalDays,
+      dueMs: now + (RELEARNING_STEPS_MIN[0] ?? 10) * MINUTE_MS,
+    };
+  }
+
+  // The `intervalDays + 1` floor is load-bearing: at the minimum ease,
+  // round(1 * 1.3) is 1, and the card would be scheduled at the same interval
+  // forever. One clamp prevents a stall that takes months of use to notice.
+  const grown = clamp(
+    Math.round(card.intervalDays * card.ease),
+    card.intervalDays + 1,
+    MAX_INTERVAL_DAYS,
+  );
+  return { ...base, state: 2, step: 0, intervalDays: grown, dueMs: now + grown * DAY_MS };
+}
+
+/**
+ * The cards due at `now`, soonest first, with never-seen cards ahead of
+ * overdue ones so a first session walks the deck in its authored order.
+ *
+ * This is the function the predecessor computed and then never called — its
+ * deck rendered `deck.cards` directly, so its spaced repetition influenced
+ * nothing a learner ever saw (`useFSRS.ts:253-256` against `Flashcards.tsx:176`).
+ * Here it is what the session reads.
+ */
+export function dueOrder<T>(
+  cards: readonly T[],
+  scheduleOf: (card: T) => CardSchedule,
+  now: number,
+): readonly T[] {
+  return cards
+    .map((card, index) => ({ card, index, state: scheduleOf(card) }))
+    .filter((entry) => entry.state.dueMs <= now)
+    .sort((a, b) =>
+      a.state.state === 0 && b.state.state !== 0
+        ? -1
+        : b.state.state === 0 && a.state.state !== 0
+          ? 1
+          : a.state.dueMs !== b.state.dueMs
+            ? a.state.dueMs - b.state.dueMs
+            : a.index - b.index,
+    )
+    .map((entry) => entry.card);
+}
+
+/**
+ * What this gives up against FSRS, recorded beside the code rather than in a
+ * document that can drift from it:
+ *
+ *  1. No memory model. `ease` is a heuristic multiplier with no probabilistic
+ *     meaning; it cannot answer "how likely is recall today".
+ *  2. Elapsed time is ignored — the largest single loss. FSRS feeds
+ *     retrievability into every update, so a card recalled sixty days late
+ *     earns a much larger interval. Here the interval grows the same whether
+ *     the review was on time or a year late.
+ *  3. No retention target. FSRS derives intervals to hit a requested
+ *     retention; "roughly 90%" is a sentence this is not entitled to.
+ *  4. No optimisation. FSRS re-fits parameters per learner; these are
+ *     constants, identical for everyone.
+ *  5. No graded lapse recovery — a flat half-interval and a flat ease penalty,
+ *     whatever the card.
+ *  6. Four grades reduced to two, which costs nothing: the UI never exposed
+ *     Hard or Easy, so no information that was ever collected was discarded.
+ */
+
+/**
+ * How far through the deck the reader is, as a percentage, counting the card
+ * they are ON rather than the ones behind it.
+ *
+ * Extracted because it was wrong and silently so: the bar read `position` while
+ * its caption read `position + 1`, so the two disagreed by one card the whole
+ * way — "1 / 5" over an empty bar, "5 / 5" over a bar at 80%, and a full bar
+ * never once on screen, because reaching the end swaps the bar for the
+ * completion panel. One number, one place, one test.
+ */
+export function progressPercent(position: number, total: number): number {
+  if (total <= 0) return 0;
+  const shown = Math.min(Math.max(position, 0) + 1, total);
+  return (shown / total) * 100;
+}