@classytic/labs 0.4.0 → 0.5.0

package/dist/diagrams/magnetism/schema.mjs

@@ -0,0 +1,236 @@
+import { z } from "zod";
+
+//#region src/diagrams/magnetism/schema.ts
+/**
+* The authoring contract for a magnetism diagram (zod), kept apart from `spec.ts` so the learner
+* render path never loads zod. `check:props` validates every lesson's diagram against this.
+*/
+const coord = z.number().finite().min(-100).max(1200);
+const len = z.number().finite().positive().max(1200);
+const plane = z.enum([
+	"left",
+	"right",
+	"up",
+	"down"
+]);
+const space = z.enum([
+	"left",
+	"right",
+	"up",
+	"down",
+	"in",
+	"out"
+]);
+const label = z.string().trim().min(1).max(40);
+const item = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("field"),
+		dir: space,
+		x: coord,
+		y: coord,
+		w: len,
+		h: len,
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("wire"),
+		x: coord,
+		y: coord,
+		current: z.enum(["in", "out"]),
+		label: label.optional(),
+		rings: z.number().int().min(0).max(3).optional()
+	}),
+	z.object({
+		type: z.literal("conductor"),
+		x1: coord,
+		y1: coord,
+		x2: coord,
+		y2: coord,
+		label: label.optional(),
+		currentArrow: z.boolean().optional(),
+		force: z.boolean().optional()
+	}),
+	z.object({
+		type: z.literal("magnet"),
+		x: coord,
+		y: coord,
+		north: plane,
+		length: len.optional()
+	}),
+	z.object({
+		type: z.literal("coil"),
+		x: coord,
+		y: coord,
+		r: len,
+		view: z.enum(["face", "edge"]),
+		current: z.enum(["cw", "ccw"]).optional(),
+		normalDeg: z.number().min(-180).max(180).optional(),
+		normal: z.boolean().optional(),
+		theta: z.boolean().optional(),
+		label: label.optional(),
+		centreField: z.boolean().optional()
+	}),
+	z.object({
+		type: z.literal("solenoid"),
+		x: coord,
+		y: coord,
+		length: len,
+		radius: len.optional(),
+		turns: z.number().int().min(3).max(12).optional(),
+		current: z.enum(["up", "down"]),
+		poles: z.boolean().optional(),
+		core: z.enum([
+			"none",
+			"iron",
+			"steel"
+		]).optional(),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("bar"),
+		x: coord,
+		y: coord,
+		length: len.optional(),
+		axis: z.enum(["horizontal", "vertical"]).optional(),
+		material: z.enum([
+			"iron",
+			"steel",
+			"copper",
+			"aluminium",
+			"plastic",
+			"wood"
+		]),
+		poles: z.boolean().optional(),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("transformer"),
+		x: coord,
+		y: coord,
+		primaryTurns: z.number().int().positive().max(1e5),
+		secondaryTurns: z.number().int().positive().max(1e5),
+		primaryLabel: label.optional(),
+		secondaryLabel: label.optional(),
+		ac: z.boolean().optional()
+	}),
+	z.object({
+		type: z.literal("relay"),
+		x: coord,
+		y: coord,
+		energised: z.boolean(),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("charge"),
+		x: coord,
+		y: coord,
+		sign: z.enum(["+", "-"]),
+		v: z.union([plane, z.number().min(-360).max(360)]),
+		label: label.optional(),
+		force: z.boolean().optional(),
+		path: z.enum([
+			"none",
+			"arc",
+			"circle"
+		]).optional(),
+		radius: len.optional()
+	}),
+	z.object({
+		type: z.literal("slab"),
+		x: coord,
+		y: coord,
+		w: len,
+		h: len,
+		carriers: z.enum(["electrons", "holes"]),
+		current: z.enum(["left", "right"]),
+		show: z.enum(["setup", "charged"]).optional(),
+		voltage: z.boolean().optional(),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("rails"),
+		x: coord,
+		y: coord,
+		length: len,
+		gap: len,
+		rodAt: z.number().min(.1).max(.95).optional(),
+		v: plane,
+		induced: z.boolean().optional(),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("vector"),
+		x: coord,
+		y: coord,
+		dir: z.union([space, z.number().min(-360).max(360)]),
+		length: len.optional(),
+		kind: z.enum([
+			"force",
+			"field",
+			"current",
+			"velocity",
+			"plain"
+		]),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("compass"),
+		x: coord,
+		y: coord
+	}),
+	z.object({
+		type: z.literal("dim"),
+		x1: coord,
+		y1: coord,
+		x2: coord,
+		y2: coord,
+		label
+	}),
+	z.object({
+		type: z.literal("angle"),
+		x: coord,
+		y: coord,
+		from: z.number().min(-360).max(360),
+		to: z.number().min(-360).max(360),
+		r: len.optional(),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("line"),
+		x1: coord,
+		y1: coord,
+		x2: coord,
+		y2: coord,
+		dashed: z.boolean().optional(),
+		label: label.optional()
+	}),
+	z.object({
+		type: z.literal("point"),
+		x: coord,
+		y: coord,
+		label
+	}),
+	z.object({
+		type: z.literal("text"),
+		x: coord,
+		y: coord,
+		text: z.string().trim().min(1).max(80),
+		anchor: z.enum([
+			"start",
+			"middle",
+			"end"
+		]).optional(),
+		tone: z.enum(["ink", "soft"]).optional()
+	})
+]);
+const magnetismSceneSchema = z.object({
+	kind: z.literal("magnetism"),
+	size: z.tuple([z.number().min(120).max(440), z.number().min(80).max(600)]).optional(),
+	items: z.array(item).min(1).max(40),
+	fieldLines: z.boolean().optional(),
+	alt: z.string().trim().max(300).optional(),
+	caption: z.string().trim().max(200).optional()
+});
+
+//#endregion
+export { magnetismSceneSchema };

package/dist/diagrams/magnetism/spec.d.mts

@@ -0,0 +1,295 @@
+//#region src/diagrams/magnetism/spec.d.ts
+/**
+ * A magnetism diagram, as an author writes it.
+ *
+ * This is the drawing an exam paper puts beside a question: a wire seen end-on, a field region of
+ * crosses, a coil tilted at θ to the field, a particle bending round a circle, a Hall slab. Lessons
+ * had no way to show one. Every worked example and exam question in the magnetism chapters was
+ * text only, while a student's own hand notes put a sketch beside every idea.
+ *
+ * ## Authors place things; the physics decides directions
+ *
+ * An author says WHERE a wire is and which way its current runs. They never say which way its
+ * field circles go, which side a particle curves towards, which face of a Hall slab charges up, or
+ * which way the force on a conductor points. Those are computed (see `core.ts`), from the same
+ * `@classytic/stage` magnetism engine the labs use. A generated or hand-drawn diagram can be
+ * beautifully wrong about a direction and nobody notices; this one cannot be, because the arrow is
+ * the cross product, not a drawing of it.
+ *
+ * ## Coordinates
+ *
+ * Figure units, origin top left, y DOWN, like the SVG. The default canvas is 360 × 220, kept under
+ * the ~440-unit ceiling so labels stay legible on a phone (see `kit/figure/figure.tsx`). "in" is into
+ * the page and "out" is towards the reader.
+ *
+ * This file is types only. The zod schema that validates authored props lives in `schema.ts`, so
+ * the learner render path never loads zod.
+ */
+/** A direction in the plane of the page. */
+type PlaneDir = 'left' | 'right' | 'up' | 'down';
+/** A direction that may also point into or out of the page. */
+type SpaceDir = PlaneDir | 'in' | 'out';
+/** A uniform field over a rectangle. `in`/`out` draw as crosses/dots, in-plane as arrows. */
+interface FieldItem {
+  type: 'field';
+  dir: SpaceDir;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** Text beside the region, e.g. "B = 0.24 T". */
+  label?: string;
+}
+/** A long straight wire seen end-on: ⊙ for current out of the page, ⊗ for into it. */
+interface WireItem {
+  type: 'wire';
+  x: number;
+  y: number;
+  current: 'in' | 'out';
+  label?: string;
+  /**
+   * Draw this wire's own field circles with their sense marked (0 to 3 rings). The sense comes
+   * from the right-hand grip rule, computed, so reversing `current` reverses the arrows.
+   */
+  rings?: number;
+}
+/** A straight conductor lying IN the page, carrying current from (x1, y1) to (x2, y2). */
+interface ConductorItem {
+  type: 'conductor';
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  label?: string;
+  /** Mark the current direction along the conductor. Default true. */
+  currentArrow?: boolean;
+  /**
+   * Draw the force F = I L × B from the field region the conductor's midpoint sits in.
+   * Zero force (conductor parallel to B) draws a small "F = 0" note instead of an arrow.
+   */
+  force?: boolean;
+}
+/** A bar magnet. */
+interface MagnetItem {
+  type: 'magnet';
+  x: number;
+  y: number;
+  /** Which end is north. The magnet lies along that axis. */
+  north: PlaneDir;
+  length?: number;
+}
+/** A flat coil. `face` looks along its axis; `edge` sees it side-on as a line at an angle. */
+interface CoilItem {
+  type: 'coil';
+  x: number;
+  y: number;
+  /** Radius (face view) or half-length of the edge-on line (edge view). */
+  r: number;
+  view: 'face' | 'edge';
+  /** Face view: conventional current sense as seen by the reader. Omit for a coil with no current. */
+  current?: 'cw' | 'ccw';
+  /**
+   * Edge view: the angle between the coil's NORMAL and the field, in degrees. The coil's plane is
+   * drawn perpendicular to that normal, so 0° is face-on to the field (maximum flux).
+   */
+  normalDeg?: number;
+  /** Edge view: draw the normal as a dashed arrow. Default true. */
+  normal?: boolean;
+  /** Edge view: mark the angle θ between the normal and the field. Default true. */
+  theta?: boolean;
+  label?: string;
+  /** Face view: draw the field at the centre as ⊙/⊗ (computed from the current sense). */
+  centreField?: boolean;
+}
+/** A solenoid lying along the page. */
+interface SolenoidItem {
+  type: 'solenoid';
+  x: number;
+  y: number;
+  length: number;
+  /** Half-height of the windings. */
+  radius?: number;
+  turns?: number;
+  /** Conventional current in the FRONT of each turn: up or down the page. */
+  current: 'up' | 'down';
+  /** Label the ends N and S (computed from the current sense). Default true. */
+  poles?: boolean;
+  /** A core inside the winding. Iron and steel both strengthen the field; the drawing shows which. */
+  core?: 'none' | 'iron' | 'steel';
+  label?: string;
+}
+/**
+ * A plain bar of some material: an iron nail, a steel rod, a copper strip, a plastic ruler.
+ *
+ * When `poles` is on and the bar is iron or steel, the poles INDUCED in it are computed from the
+ * field of the magnets and solenoids around it: the end the field runs out of becomes north. A
+ * non-magnetic material never shows poles, which is the whole point of drawing one.
+ */
+interface BarItem {
+  type: 'bar';
+  x: number;
+  y: number;
+  length?: number;
+  axis?: 'horizontal' | 'vertical';
+  material: 'iron' | 'steel' | 'copper' | 'aluminium' | 'plastic' | 'wood';
+  poles?: boolean;
+  label?: string;
+}
+/**
+ * A transformer: two windings on one iron core. More turns are drawn as more loops, in proportion,
+ * so a step-up transformer LOOKS like one before a learner reads a number.
+ */
+interface TransformerItem {
+  type: 'transformer';
+  x: number;
+  y: number;
+  primaryTurns: number;
+  secondaryTurns: number;
+  /** Text at the primary leads, e.g. "220 V a.c." or "N_p = 1100". */
+  primaryLabel?: string;
+  secondaryLabel?: string;
+  /** Draw a.c. symbols on the primary leads. Default true. */
+  ac?: boolean;
+}
+/**
+ * A relay: a coil on an iron core, an iron armature on a pivot, and a pair of switch contacts.
+ * `energised` decides everything else: the armature is pulled to the core and the contacts close.
+ */
+interface RelayItem {
+  type: 'relay';
+  x: number;
+  y: number;
+  energised: boolean;
+  label?: string;
+}
+/** A charged particle with a velocity. */
+interface ChargeItem {
+  type: 'charge';
+  x: number;
+  y: number;
+  sign: '+' | '-';
+  /** Velocity direction, a plane direction or an angle in degrees (0 = right, 90 = up). */
+  v: PlaneDir | number;
+  label?: string;
+  /** Draw the force q v × B from the field region the particle sits in. Default true. */
+  force?: boolean;
+  /**
+   * Draw the path. `circle` closes it; `arc` draws the part that stays inside the field region.
+   * The side it curves to is computed, never authored.
+   */
+  path?: 'none' | 'arc' | 'circle';
+  /** Radius of the drawn path, in figure units. */
+  radius?: number;
+}
+/** A Hall slab carrying a current across a field. */
+interface SlabItem {
+  type: 'slab';
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  carriers: 'electrons' | 'holes';
+  /** Conventional current direction. */
+  current: 'left' | 'right';
+  /** `setup` draws the slab and current only; `charged` also piles charge on the faces (computed). */
+  show?: 'setup' | 'charged';
+  /** Mark the Hall voltage V_H across the faces. */
+  voltage?: boolean;
+  label?: string;
+}
+/** A rod sliding on two parallel rails (motional e.m.f.). */
+interface RailsItem {
+  type: 'rails';
+  x: number;
+  y: number;
+  length: number;
+  gap: number;
+  /** Where the rod sits, as a fraction of the rail length. */
+  rodAt?: number;
+  v: PlaneDir;
+  /** Draw the induced current in the rod (computed from v × B). */
+  induced?: boolean;
+  label?: string;
+}
+/** A free vector with a meaning, for anything the other items do not cover. */
+interface VectorItem {
+  type: 'vector';
+  x: number;
+  y: number;
+  dir: SpaceDir | number;
+  length?: number;
+  kind: 'force' | 'field' | 'current' | 'velocity' | 'plain';
+  label?: string;
+}
+/** A plotting compass whose needle lies along the computed field at its position. */
+interface CompassItem {
+  type: 'compass';
+  x: number;
+  y: number;
+}
+/** A dimension line, e.g. the separation between two wires. */
+interface DimItem {
+  type: 'dim';
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  label: string;
+}
+/**
+ * An angle mark: an arc from one direction to another, with a label such as "30°" or "θ".
+ * Directions in degrees, 0 = right, anticlockwise positive (the maths convention, not the SVG's).
+ */
+interface AngleItem {
+  type: 'angle';
+  x: number;
+  y: number;
+  from: number;
+  to: number;
+  r?: number;
+  label?: string;
+}
+/** A plain line, e.g. a dashed reference direction or a normal drawn by hand. */
+interface LineItem {
+  type: 'line';
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  dashed?: boolean;
+  label?: string;
+}
+/** A labelled point, e.g. "P". */
+interface PointItem {
+  type: 'point';
+  x: number;
+  y: number;
+  label: string;
+}
+/** A free label. */
+interface TextItem {
+  type: 'text';
+  x: number;
+  y: number;
+  text: string;
+  anchor?: 'start' | 'middle' | 'end';
+  tone?: 'ink' | 'soft';
+}
+type MagnetismItem = FieldItem | WireItem | ConductorItem | MagnetItem | CoilItem | SolenoidItem | BarItem | TransformerItem | RelayItem | ChargeItem | SlabItem | RailsItem | VectorItem | CompassItem | DimItem | AngleItem | LineItem | PointItem | TextItem;
+interface MagnetismScene {
+  kind: 'magnetism';
+  /** Canvas size in figure units, default [360, 220]. */
+  size?: [number, number];
+  items: MagnetismItem[];
+  /**
+   * Trace field lines through the whole scene, from every wire, magnet and solenoid together, so
+   * two wires show their neutral point and two magnets show attraction or repulsion. Default false.
+   */
+  fieldLines?: boolean;
+  /** A short description for screen readers. Generated from the items when omitted. */
+  alt?: string;
+  /** Caption under the figure. */
+  caption?: string;
+}
+//#endregion
+export { AngleItem, BarItem, ChargeItem, CoilItem, CompassItem, ConductorItem, DimItem, FieldItem, LineItem, MagnetItem, MagnetismItem, MagnetismScene, PlaneDir, PointItem, RailsItem, RelayItem, SlabItem, SolenoidItem, SpaceDir, TextItem, TransformerItem, VectorItem, WireItem };

package/dist/diagrams/rich.mjs

@@ -0,0 +1,27 @@
+'use client';
+
+import { jsx } from "react/jsx-runtime";
+
+//#region src/diagrams/rich.tsx
+/**
+* A label with subscripts: `V_H`, `I_1`, `B_{res}`. Authors type the underscore form everywhere
+* (it is how the syllabus writes them in plain text) and it used to print literally.
+*/
+function rich(text) {
+	const parts = text.split(/(_\{[^}]*\}|_[A-Za-z0-9])/g).filter(Boolean);
+	if (parts.length === 1) return text;
+	return parts.map((part, i) => part.startsWith("_") ? /* @__PURE__ */ jsx("tspan", {
+		baselineShift: "sub",
+		fontSize: "0.72em",
+		children: part.replace(/^_\{?|\}$/g, "")
+	}, i) : /* @__PURE__ */ jsx("tspan", { children: part }, i));
+}
+/** The same, for HTML text (captions). */
+function richHtml(text) {
+	const parts = text.split(/(_\{[^}]*\}|_[A-Za-z0-9])/g).filter(Boolean);
+	if (parts.length === 1) return text;
+	return parts.map((part, i) => part.startsWith("_") ? /* @__PURE__ */ jsx("sub", { children: part.replace(/^_\{?|\}$/g, "") }, i) : /* @__PURE__ */ jsx("span", { children: part }, i));
+}
+
+//#endregion
+export { rich, richHtml };

package/dist/diagrams/schema.mjs

@@ -0,0 +1,11 @@
+import { graphSceneSchema } from "./graph/schema.mjs";
+import { magnetismSceneSchema } from "./magnetism/schema.mjs";
+import { z } from "zod";
+
+//#region src/diagrams/schema.ts
+/** Zod contract for every diagram kind. Manifests import this; renderers never do. */
+/** Every diagram kind a lesson block can carry, keyed by `kind`. */
+const diagramSchema = z.discriminatedUnion("kind", [magnetismSceneSchema, graphSceneSchema]);
+
+//#endregion
+export { diagramSchema, graphSceneSchema, magnetismSceneSchema };

package/dist/discrete/arrangements/preset.mjs

@@ -4,13 +4,13 @@ import { Tex as Tex$1 } from "../../core/tex.mjs";
 import { IconButton, Stepper } from "../../kit/controls.mjs";
 import { Activity } from "../../kit/activity.mjs";
 import { Field, Readout } from "../../kit/frame.mjs";
-import { ChallengeCard, HintLadder, RevealSolution, useChallenge, useCheckpoint, useHints } from "../../kit/pedagogy.mjs";
 import { AuthoredResponse } from "../../kit/authored-response.mjs";
-import { factorial, multinomial } from "../core/combinatorics.mjs";
+import { ChallengeCard, HintLadder, RevealSolution, useChallenge, useCheckpoint, useHints } from "../../kit/pedagogy.mjs";
 import { CATEGORICAL } from "../../kit/palette.mjs";
+import { factorial, multinomial } from "../core/combinatorics.mjs";
 import { useMemo, useState } from "react";
-import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { useControlSurface } from "@classytic/stage";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { RotateCcw } from "lucide-react";
 
 //#region src/discrete/arrangements/preset.tsx

package/dist/discrete/bayes/preset.d.mts

@@ -1,5 +1,17 @@
+import { LabAskSpec } from "../../kit/ask.mjs";
 import { ReactNode } from "react";
 //#region src/discrete/bayes/preset.d.ts
+/**
+ * The learner TYPES the posterior P(condition | positive) before it is shown. Graded against the
+ * current slider values (so moving a slider moves the target with what is on screen), within
+ * `tol` absolute (default 0.02, two percentage points). `0.75`, `3/4` and `75%` all count.
+ */
+interface BayesGoal {
+  kind: 'posterior';
+  tol?: number;
+  /** Override the question text. */
+  prompt?: string;
+}
 interface BayesProps {
   prior?: number;
   sensitivity?: number;
@@ -13,7 +25,11 @@ interface BayesProps {
   objectives?: string[];
   hints?: string[];
   controlId?: string;
+  /** An authored question. Replaces the built-in "what fraction truly have it" MCQ when given. */
+  ask?: LabAskSpec;
+  /** A typed posterior. Hides the posterior readouts until it is answered (or revealed). */
+  goal?: BayesGoal;
 }
-declare function BayesLab({ prior, sensitivity, falsePositive, population, conditionLabels, testLabels, predict, title, prompt, objectives, hints: hintList, controlId }: BayesProps): ReactNode;
+declare function BayesLab({ prior, sensitivity, falsePositive, population, conditionLabels, testLabels, predict, title, prompt, objectives, hints: hintList, controlId, ask: askIn, goal }: BayesProps): ReactNode;
 //#endregion
-export { BayesLab, BayesProps };
+export { BayesGoal, BayesLab, BayesProps };