@classytic/labs 0.2.0 → 0.3.0

package/dist/algorithms/tree-contract.d.mts

@@ -0,0 +1,95 @@
+//#region src/algorithms/tree-contract.d.ts
+interface BinaryTreeNode {
+  id: string;
+  value: number;
+  left?: string;
+  right?: string;
+}
+interface BinaryTree {
+  rootId?: string;
+  nodes: BinaryTreeNode[];
+}
+interface TreePosition {
+  id: string;
+  x: number;
+  y: number;
+  depth: number;
+}
+type TraversalOrder = 'preorder' | 'inorder' | 'postorder';
+type TreeEvent = {
+  type: 'start';
+  nodeId?: string;
+  message: string;
+} | {
+  type: 'enter-call';
+  nodeId: string;
+  stack: string[];
+  message: string;
+} | {
+  type: 'compare';
+  nodeId: string;
+  target: number;
+  relation: 'less' | 'equal' | 'greater';
+  stack: string[];
+  message: string;
+} | {
+  type: 'descend';
+  from: string;
+  to?: string;
+  side: 'left' | 'right';
+  stack: string[];
+  message: string;
+} | {
+  type: 'base-case';
+  parentId?: string;
+  side?: 'left' | 'right';
+  stack: string[];
+  message: string;
+} | {
+  type: 'visit';
+  nodeId: string;
+  output: string[];
+  stack: string[];
+  message: string;
+} | {
+  type: 'return';
+  nodeId: string;
+  stack: string[];
+  message: string;
+} | {
+  type: 'insert';
+  nodeId: string;
+  parentId?: string;
+  side?: 'left' | 'right';
+  tree?: BinaryTree;
+  message: string;
+} | {
+  type: 'balance';
+  nodeId: string;
+  factor: number;
+  leftHeight: number;
+  rightHeight: number;
+  rotation?: 'LL' | 'RR' | 'LR' | 'RL';
+  stack: string[];
+  message: string;
+} | {
+  type: 'rotate';
+  nodeId: string;
+  pivotId: string;
+  direction: 'left' | 'right';
+  tree: BinaryTree;
+  message: string;
+} | {
+  type: 'complete';
+  found?: boolean;
+  output: string[];
+  message: string;
+};
+interface TreeTrace {
+  operation: 'traversal' | 'search' | 'insert' | 'avl-insert';
+  events: TreeEvent[];
+  output: string[];
+  tree: BinaryTree;
+}
+//#endregion
+export { BinaryTree, BinaryTreeNode, TraversalOrder, TreeEvent, TreePosition, TreeTrace };

package/dist/algorithms/tree-layout.d.mts

@@ -0,0 +1,9 @@
+import { BinaryTree, TreePosition } from "./tree-contract.mjs";
+
+//#region src/algorithms/tree-layout.d.ts
+declare const TREE_GAP_X = 56;
+declare const TREE_GAP_Y = 74;
+/** Compact layered binary-tree layout with stable ordering and centered parents. */
+declare function layoutBinaryTree(tree: BinaryTree): TreePosition[];
+//#endregion
+export { TREE_GAP_X, TREE_GAP_Y, layoutBinaryTree };

package/dist/algorithms/tree-layout.mjs

@@ -0,0 +1,47 @@
+//#region src/algorithms/tree-layout.ts
+const TREE_GAP_X = 56;
+const TREE_GAP_Y = 74;
+/** Compact layered binary-tree layout with stable ordering and centered parents. */
+function layoutBinaryTree(tree) {
+	if (!tree.rootId) return [];
+	const nodes = new Map(tree.nodes.map((node) => [node.id, node]));
+	const placed = [];
+	const seen = /* @__PURE__ */ new Set();
+	const place = (id, depth, origin) => {
+		if (!id || seen.has(id)) return void 0;
+		const node = nodes.get(id);
+		if (!node) return void 0;
+		seen.add(id);
+		const left = place(node.left, depth + 1, origin);
+		const rightOrigin = origin + (left?.width ?? 0) + (left && node.right ? 1 : 0);
+		const right = place(node.right, depth + 1, rightOrigin);
+		let rootX;
+		if (left && right) rootX = (left.rootX + right.rootX) / 2;
+		else if (left) rootX = left.rootX + .5;
+		else if (right) rootX = right.rootX - .5;
+		else rootX = origin;
+		const minX = Math.min(origin, rootX);
+		const maxX = Math.max(rootX, right ? rightOrigin + right.width - 1 : left ? origin + left.width - 1 : origin);
+		placed.push({
+			id,
+			rawX: rootX,
+			x: 0,
+			y: 0,
+			depth
+		});
+		return {
+			rootX,
+			width: Math.max(1, maxX - minX + 1)
+		};
+	};
+	place(tree.rootId, 0, 0);
+	const min = Math.min(...placed.map((item) => item.rawX));
+	return placed.map(({ rawX, ...item }) => ({
+		...item,
+		x: (rawX - min) * 56,
+		y: item.depth * 74
+	}));
+}
+
+//#endregion
+export { TREE_GAP_X, TREE_GAP_Y, layoutBinaryTree };

package/dist/algorithms/tree-presets.d.mts

@@ -0,0 +1,7 @@
+import { BinaryTree } from "./tree-contract.mjs";
+
+//#region src/algorithms/tree-presets.d.ts
+declare const CLASSIC_BST: BinaryTree;
+declare const BALANCED_BST: BinaryTree;
+//#endregion
+export { BALANCED_BST, CLASSIC_BST };

package/dist/algorithms/tree-presets.mjs

@@ -0,0 +1,92 @@
+//#region src/algorithms/tree-presets.ts
+const CLASSIC_BST = {
+	rootId: "8",
+	nodes: [
+		{
+			id: "8",
+			value: 8,
+			left: "3",
+			right: "10"
+		},
+		{
+			id: "3",
+			value: 3,
+			left: "1",
+			right: "6"
+		},
+		{
+			id: "10",
+			value: 10,
+			right: "14"
+		},
+		{
+			id: "1",
+			value: 1
+		},
+		{
+			id: "6",
+			value: 6,
+			left: "4",
+			right: "7"
+		},
+		{
+			id: "14",
+			value: 14,
+			left: "13"
+		},
+		{
+			id: "4",
+			value: 4
+		},
+		{
+			id: "7",
+			value: 7
+		},
+		{
+			id: "13",
+			value: 13
+		}
+	]
+};
+const BALANCED_BST = {
+	rootId: "20",
+	nodes: [
+		{
+			id: "20",
+			value: 20,
+			left: "10",
+			right: "30"
+		},
+		{
+			id: "10",
+			value: 10,
+			left: "5",
+			right: "15"
+		},
+		{
+			id: "30",
+			value: 30,
+			left: "25",
+			right: "35"
+		},
+		{
+			id: "5",
+			value: 5
+		},
+		{
+			id: "15",
+			value: 15
+		},
+		{
+			id: "25",
+			value: 25
+		},
+		{
+			id: "35",
+			value: 35
+		}
+	]
+};
+
+//#endregion
+export { BALANCED_BST, CLASSIC_BST };

package/dist/algorithms/tree.d.mts

@@ -0,0 +1,10 @@
+import { BinaryTree, TraversalOrder, TreeTrace } from "./tree-contract.mjs";
+
+//#region src/algorithms/tree.d.ts
+declare function traverseTree(tree: BinaryTree, order?: TraversalOrder): TreeTrace;
+declare function searchBST(tree: BinaryTree, target: number): TreeTrace;
+declare function insertBST(tree: BinaryTree, value: number): TreeTrace;
+/** Insert into an AVL tree and expose every balance check and structural rotation. */
+declare function insertAVL(tree: BinaryTree, value: number): TreeTrace;
+//#endregion
+export { insertAVL, insertBST, searchBST, traverseTree };

package/dist/algorithms/tree.mjs

@@ -0,0 +1,375 @@
+//#region src/algorithms/tree.ts
+const indexTree = (tree) => new Map(tree.nodes.map((node) => [node.id, node]));
+function traverseTree(tree, order = "inorder") {
+	const nodes = indexTree(tree);
+	const events = [{
+		type: "start",
+		nodeId: tree.rootId,
+		message: `Start ${order} traversal at the root.`
+	}];
+	const output = [];
+	const walk = (id, stack, parentId, side) => {
+		if (!id || !nodes.has(id)) {
+			events.push({
+				type: "base-case",
+				parentId,
+				side,
+				stack,
+				message: `No ${side ?? ""} child—this recursive call returns.`
+			});
+			return;
+		}
+		const node = nodes.get(id);
+		const nextStack = [...stack, id];
+		events.push({
+			type: "enter-call",
+			nodeId: id,
+			stack: nextStack,
+			message: `Enter traverse(${node.value}); push it onto the call stack.`
+		});
+		const visit = () => {
+			output.push(id);
+			events.push({
+				type: "visit",
+				nodeId: id,
+				output: [...output],
+				stack: nextStack,
+				message: `Visit ${node.value}; append it to the traversal output.`
+			});
+		};
+		if (order === "preorder") visit();
+		events.push({
+			type: "descend",
+			from: id,
+			to: node.left,
+			side: "left",
+			stack: nextStack,
+			message: `Explore ${node.value}'s left subtree.`
+		});
+		walk(node.left, nextStack, id, "left");
+		if (order === "inorder") visit();
+		events.push({
+			type: "descend",
+			from: id,
+			to: node.right,
+			side: "right",
+			stack: nextStack,
+			message: `Explore ${node.value}'s right subtree.`
+		});
+		walk(node.right, nextStack, id, "right");
+		if (order === "postorder") visit();
+		events.push({
+			type: "return",
+			nodeId: id,
+			stack,
+			message: `Return from traverse(${node.value}); pop it from the call stack.`
+		});
+	};
+	walk(tree.rootId, []);
+	events.push({
+		type: "complete",
+		output: [...output],
+		message: `${order} complete: ${output.map((id) => nodes.get(id)?.value).join(" → ")}.`
+	});
+	return {
+		operation: "traversal",
+		events,
+		output,
+		tree
+	};
+}
+function searchBST(tree, target) {
+	const nodes = indexTree(tree);
+	const events = [{
+		type: "start",
+		nodeId: tree.rootId,
+		message: `Search for ${target}, beginning at the root.`
+	}];
+	const stack = [];
+	let id = tree.rootId;
+	while (id && nodes.has(id)) {
+		const node = nodes.get(id);
+		stack.push(id);
+		const relation = target === node.value ? "equal" : target < node.value ? "less" : "greater";
+		events.push({
+			type: "compare",
+			nodeId: id,
+			target,
+			relation,
+			stack: [...stack],
+			message: `${target} is ${relation === "equal" ? "equal to" : relation === "less" ? "less than" : "greater than"} ${node.value}.`
+		});
+		if (relation === "equal") {
+			events.push({
+				type: "complete",
+				found: true,
+				output: [id],
+				message: `Found ${target} after ${stack.length} comparison${stack.length === 1 ? "" : "s"}.`
+			});
+			return {
+				operation: "search",
+				events,
+				output: [id],
+				tree
+			};
+		}
+		const side = relation === "less" ? "left" : "right";
+		const next = node[side];
+		events.push({
+			type: "descend",
+			from: id,
+			to: next,
+			side,
+			stack: [...stack],
+			message: `Follow the ${side} branch from ${node.value}.`
+		});
+		id = next;
+	}
+	events.push({
+		type: "base-case",
+		stack: [...stack],
+		message: `Reached an empty child; ${target} is not in this tree.`
+	});
+	events.push({
+		type: "complete",
+		found: false,
+		output: [],
+		message: `${target} was not found.`
+	});
+	return {
+		operation: "search",
+		events,
+		output: [],
+		tree
+	};
+}
+function insertBST(tree, value) {
+	if (!tree.rootId) {
+		const node = {
+			id: `n-${value}`,
+			value
+		};
+		const next = {
+			rootId: node.id,
+			nodes: [node]
+		};
+		return {
+			operation: "insert",
+			output: [node.id],
+			tree: next,
+			events: [
+				{
+					type: "start",
+					message: `Insert ${value} into the empty tree.`
+				},
+				{
+					type: "insert",
+					nodeId: node.id,
+					message: `${value} becomes the root.`
+				},
+				{
+					type: "complete",
+					output: [node.id],
+					message: "Insertion complete."
+				}
+			]
+		};
+	}
+	const search = searchBST(tree, value);
+	const lastDescend = [...search.events].reverse().find((event) => event.type === "descend");
+	if (!lastDescend || search.events.some((event) => event.type === "complete" && event.found)) return {
+		...search,
+		operation: "insert",
+		events: [...search.events.slice(0, -1), {
+			type: "complete",
+			output: search.output,
+			message: `${value} already exists; the tree is unchanged.`
+		}]
+	};
+	const baseId = `n-${value}`;
+	let id = baseId;
+	let suffix = 2;
+	while (tree.nodes.some((node) => node.id === id)) id = `${baseId}-${suffix++}`;
+	const newNode = {
+		id,
+		value
+	};
+	const nodes = tree.nodes.map((node) => node.id === lastDescend.from ? {
+		...node,
+		[lastDescend.side]: id
+	} : node);
+	const next = {
+		...tree,
+		nodes: [...nodes, newNode]
+	};
+	return {
+		operation: "insert",
+		events: search.events.slice(0, -2).concat({
+			type: "insert",
+			nodeId: id,
+			parentId: lastDescend.from,
+			side: lastDescend.side,
+			tree: next,
+			message: `The ${lastDescend.side} child is empty; insert ${value} here.`
+		}, {
+			type: "complete",
+			output: [id],
+			message: `Inserted ${value}. The BST invariant is preserved.`
+		}),
+		output: [id],
+		tree: next
+	};
+}
+const cloneTree = (rootId, nodes) => ({
+	rootId,
+	nodes: [...nodes.values()].map((node) => ({ ...node }))
+});
+const nodeHeight = (id, nodes) => id && nodes.has(id) ? 1 + Math.max(nodeHeight(nodes.get(id).left, nodes), nodeHeight(nodes.get(id).right, nodes)) : 0;
+/** Insert into an AVL tree and expose every balance check and structural rotation. */
+function insertAVL(tree, value) {
+	if (!tree.rootId) return {
+		...insertBST(tree, value),
+		operation: "avl-insert"
+	};
+	if (tree.nodes.some((node) => node.value === value)) return {
+		...insertBST(tree, value),
+		operation: "avl-insert"
+	};
+	const nodes = new Map(tree.nodes.map((node) => [node.id, { ...node }]));
+	const events = [{
+		type: "start",
+		nodeId: tree.rootId,
+		message: `Insert ${value}, then restore the AVL balance invariant.`
+	}];
+	let rootId = tree.rootId;
+	let newId = `n-${value}`;
+	let suffix = 2;
+	while (nodes.has(newId)) newId = `n-${value}-${suffix++}`;
+	const replaceParentLink = (oldId, nextId) => {
+		if (rootId === oldId) rootId = nextId;
+		else for (const candidate of nodes.values()) {
+			if (candidate.left === oldId) {
+				candidate.left = nextId;
+				break;
+			}
+			if (candidate.right === oldId) {
+				candidate.right = nextId;
+				break;
+			}
+		}
+	};
+	const rotateLeft = (root) => {
+		const x = nodes.get(root);
+		const pivot = nodes.get(x.right);
+		replaceParentLink(root, pivot.id);
+		x.right = pivot.left;
+		pivot.left = root;
+		events.push({
+			type: "rotate",
+			nodeId: root,
+			pivotId: pivot.id,
+			direction: "left",
+			tree: cloneTree(rootId, nodes),
+			message: `Rotate left at ${x.value}; ${pivot.value} rises and ${x.value} moves left.`
+		});
+		return pivot.id;
+	};
+	const rotateRight = (root) => {
+		const y = nodes.get(root);
+		const pivot = nodes.get(y.left);
+		replaceParentLink(root, pivot.id);
+		y.left = pivot.right;
+		pivot.right = root;
+		events.push({
+			type: "rotate",
+			nodeId: root,
+			pivotId: pivot.id,
+			direction: "right",
+			tree: cloneTree(rootId, nodes),
+			message: `Rotate right at ${y.value}; ${pivot.value} rises and ${y.value} moves right.`
+		});
+		return pivot.id;
+	};
+	const insert = (id, stack, parentId, side) => {
+		if (!id) {
+			nodes.set(newId, {
+				id: newId,
+				value
+			});
+			events.push({
+				type: "insert",
+				nodeId: newId,
+				parentId,
+				side,
+				message: `The ${side ?? "root"} position is empty; place ${value} here.`
+			});
+			return newId;
+		}
+		const node = nodes.get(id);
+		const nextStack = [...stack, id];
+		const relation = value < node.value ? "less" : "greater";
+		events.push({
+			type: "compare",
+			nodeId: id,
+			target: value,
+			relation,
+			stack: nextStack,
+			message: `${value} is ${relation} than ${node.value}.`
+		});
+		const branch = relation === "less" ? "left" : "right";
+		events.push({
+			type: "descend",
+			from: id,
+			to: node[branch],
+			side: branch,
+			stack: nextStack,
+			message: `Follow the ${branch} branch.`
+		});
+		node[branch] = insert(node[branch], nextStack, id, branch);
+		const inserted = [...events].reverse().find((event) => event.type === "insert" && event.nodeId === newId);
+		if (inserted && !inserted.tree) inserted.tree = cloneTree(rootId, nodes);
+		const leftHeight = nodeHeight(node.left, nodes);
+		const rightHeight = nodeHeight(node.right, nodes);
+		const factor = leftHeight - rightHeight;
+		let rotation;
+		if (factor > 1) rotation = value < nodes.get(node.left).value ? "LL" : "LR";
+		if (factor < -1) rotation = value > nodes.get(node.right).value ? "RR" : "RL";
+		events.push({
+			type: "balance",
+			nodeId: id,
+			factor,
+			leftHeight,
+			rightHeight,
+			rotation,
+			stack: nextStack,
+			message: rotation ? `${node.value} has balance factor ${factor}; this is an ${rotation} imbalance.` : `${node.value} has balance factor ${factor}, so it remains balanced.`
+		});
+		if (rotation === "LL") return rotateRight(id);
+		if (rotation === "RR") return rotateLeft(id);
+		if (rotation === "LR") {
+			node.left = rotateLeft(node.left);
+			return rotateRight(id);
+		}
+		if (rotation === "RL") {
+			node.right = rotateRight(node.right);
+			return rotateLeft(id);
+		}
+		return id;
+	};
+	rootId = insert(rootId, []);
+	const result = cloneTree(rootId, nodes);
+	events.push({
+		type: "complete",
+		output: [newId],
+		message: `Inserted ${value}; every node now has balance factor −1, 0, or 1.`
+	});
+	return {
+		operation: "avl-insert",
+		events,
+		output: [newId],
+		tree: result
+	};
+}
+
+//#endregion
+export { insertAVL, insertBST, searchBST, traverseTree };

package/dist/authoring/index.d.mts

@@ -0,0 +1,11 @@
+import { ActivityPattern, AuthoredActivity, AuthoredActivityStep, AuthoredChoice, AuthoredChoiceQuestion, AuthoredDataset, AuthoredNumericQuestion, AuthoredOrderingQuestion, AuthoredQuestion, AuthoredReflectionQuestion, AuthoredSuccessCondition, AuthoredTextQuestion, AuthoredTransferCase, CompiledAuthoredActivity, SuccessOperator, compileAuthoredActivity, defineAuthoredActivity, isCompiledAuthoredActivity, withAuthoredObjectives } from "../kit/activity-authoring.mjs";
+import { LabAuthoringComponent, LabLearningExperience, LabManifest, LabRepresentation, LabRuntimeComponent, LabTaxonomy, defineLab, labTag } from "../lab-def/define-lab.mjs";
+import { activityPatternSchema, authoredActivitySchema, authoredActivityStepSchema, authoredChoiceSchema, authoredDatasetSchema, authoredQuestionSchema, authoredSuccessSchema, authoredTransferCaseSchema } from "../schemas/activity-authoring.mjs";
+import { LabAccessibilityEvidence, LabExperienceAssessment, assessLabExperience, deriveActivityExperience } from "./quality.mjs";
+import { LabQualityEntry, LabQualityReport, LabQualityStatus, createLabQualityReport } from "./report.mjs";
+
+//#region src/authoring/index.d.ts
+/** Validate unknown CMS data and compile it into the learner runtime plan. */
+declare function parseAuthoredActivity(input: unknown): CompiledAuthoredActivity;
+//#endregion
+export { type ActivityPattern, type AuthoredActivity, type AuthoredActivityStep, type AuthoredChoice, type AuthoredChoiceQuestion, type AuthoredDataset, type AuthoredNumericQuestion, type AuthoredOrderingQuestion, type AuthoredQuestion, type AuthoredReflectionQuestion, type AuthoredSuccessCondition, type AuthoredTextQuestion, type AuthoredTransferCase, type CompiledAuthoredActivity, type LabAccessibilityEvidence, type LabAuthoringComponent, type LabExperienceAssessment, type LabLearningExperience, type LabManifest, type LabQualityEntry, type LabQualityReport, type LabQualityStatus, type LabRepresentation, type LabRuntimeComponent, type LabTaxonomy, type SuccessOperator, activityPatternSchema, assessLabExperience, authoredActivitySchema, authoredActivityStepSchema, authoredChoiceSchema, authoredDatasetSchema, authoredQuestionSchema, authoredSuccessSchema, authoredTransferCaseSchema, compileAuthoredActivity, createLabQualityReport, defineAuthoredActivity, defineLab, deriveActivityExperience, isCompiledAuthoredActivity, labTag, parseAuthoredActivity, withAuthoredObjectives };

package/dist/authoring/index.mjs

@@ -0,0 +1,20 @@
+import { compileAuthoredActivity, defineAuthoredActivity, isCompiledAuthoredActivity, withAuthoredObjectives } from "../kit/activity-authoring.mjs";
+import { defineLab, labTag } from "../lab-def/define-lab.mjs";
+import { activityPatternSchema, authoredActivitySchema, authoredActivityStepSchema, authoredChoiceSchema, authoredDatasetSchema, authoredQuestionSchema, authoredSuccessSchema, authoredTransferCaseSchema } from "../schemas/activity-authoring.mjs";
+import { assessLabExperience, deriveActivityExperience } from "./quality.mjs";
+import { createLabQualityReport } from "./report.mjs";
+
+//#region src/authoring/index.ts
+/**
+* Public, host-neutral authoring contract.
+*
+* This subpath contains no lab runtime, renderer, editor, or domain barrel. Community
+* tools can define and validate labs without downloading the learner experience.
+*/
+/** Validate unknown CMS data and compile it into the learner runtime plan. */
+function parseAuthoredActivity(input) {
+	return compileAuthoredActivity(authoredActivitySchema.parse(input));
+}
+
+//#endregion
+export { activityPatternSchema, assessLabExperience, authoredActivitySchema, authoredActivityStepSchema, authoredChoiceSchema, authoredDatasetSchema, authoredQuestionSchema, authoredSuccessSchema, authoredTransferCaseSchema, compileAuthoredActivity, createLabQualityReport, defineAuthoredActivity, defineLab, deriveActivityExperience, isCompiledAuthoredActivity, labTag, parseAuthoredActivity, withAuthoredObjectives };

package/dist/authoring/quality.d.mts

@@ -0,0 +1,18 @@
+import { AuthoredActivity, CompiledAuthoredActivity } from "../kit/activity-authoring.mjs";
+import { LabLearningExperience, LabManifest } from "../lab-def/define-lab.mjs";
+
+//#region src/authoring/quality.d.ts
+interface LabExperienceAssessment {
+  ready: boolean;
+  issues: string[];
+}
+type LabAccessibilityEvidence = LabLearningExperience['accessibility'];
+/** Derive only what activity data proves; access capabilities require explicit evidence. */
+declare function deriveActivityExperience(activity: AuthoredActivity | CompiledAuthoredActivity, accessibility: LabAccessibilityEvidence): LabLearningExperience;
+/**
+ * Host-neutral quality gate for a showcase learning experience. It checks declared
+ * teaching and access capabilities without importing or rendering the runtime.
+ */
+declare function assessLabExperience(manifest: Pick<LabManifest, 'experience'>, activity?: AuthoredActivity | CompiledAuthoredActivity): LabExperienceAssessment;
+//#endregion
+export { LabAccessibilityEvidence, LabExperienceAssessment, assessLabExperience, deriveActivityExperience };