@classytic/stage 0.1.0

package/dist/builder/Palette.mjs

@@ -0,0 +1,100 @@
+'use client';
+
+import { ToolIcon } from "./icons.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/builder/Palette.tsx
+const btn = (active) => ({
+	display: "inline-flex",
+	alignItems: "center",
+	gap: 6,
+	padding: "6px 10px",
+	borderRadius: 8,
+	fontSize: 13,
+	fontWeight: 600,
+	cursor: "pointer",
+	color: active ? "var(--stage-bg)" : "var(--stage-fg)",
+	background: active ? "var(--stage-accent)" : "transparent",
+	border: `1px solid ${active ? "var(--stage-accent)" : "var(--stage-muted)"}`
+});
+const iconBtn = (disabled) => ({
+	display: "inline-flex",
+	alignItems: "center",
+	gap: 6,
+	padding: "6px 10px",
+	borderRadius: 8,
+	fontSize: 13,
+	fontWeight: 600,
+	cursor: disabled ? "not-allowed" : "pointer",
+	opacity: disabled ? .4 : 1,
+	color: "var(--stage-fg)",
+	background: "transparent",
+	border: "1px solid var(--stage-muted)"
+});
+function Palette({ tools, activeTool, onSelect, onUndo, onRedo, canUndo, canRedo, onClear, onSave, hint }) {
+	return /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsxs("div", {
+		role: "toolbar",
+		"aria-label": "construction tools",
+		style: {
+			display: "flex",
+			flexWrap: "wrap",
+			gap: 6,
+			alignItems: "center"
+		},
+		children: [
+			tools.map((t) => /* @__PURE__ */ jsxs("button", {
+				type: "button",
+				"aria-pressed": activeTool === t.id,
+				onClick: () => onSelect(t.id),
+				style: btn(activeTool === t.id),
+				children: [/* @__PURE__ */ jsx(ToolIcon, { name: t.icon }), t.label]
+			}, t.id)),
+			/* @__PURE__ */ jsx("span", { style: {
+				width: 1,
+				alignSelf: "stretch",
+				background: "var(--stage-muted)",
+				margin: "0 4px"
+			} }),
+			/* @__PURE__ */ jsxs("button", {
+				type: "button",
+				onClick: onUndo,
+				disabled: !canUndo,
+				style: iconBtn(!canUndo),
+				children: [/* @__PURE__ */ jsx(ToolIcon, { name: "undo" }), "Undo"]
+			}),
+			/* @__PURE__ */ jsxs("button", {
+				type: "button",
+				onClick: onRedo,
+				disabled: !canRedo,
+				style: iconBtn(!canRedo),
+				children: [/* @__PURE__ */ jsx(ToolIcon, { name: "redo" }), "Redo"]
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				onClick: onClear,
+				style: iconBtn(false),
+				children: "Clear"
+			}),
+			onSave && /* @__PURE__ */ jsx("button", {
+				type: "button",
+				onClick: onSave,
+				style: {
+					...iconBtn(false),
+					color: "var(--stage-good)",
+					borderColor: "var(--stage-good)"
+				},
+				children: "Save"
+			})
+		]
+	}), /* @__PURE__ */ jsx("p", {
+		style: {
+			fontSize: 12,
+			opacity: .7,
+			margin: "6px 2px 0"
+		},
+		children: hint
+	})] });
+}
+
+//#endregion
+export { Palette };

package/dist/builder/SceneBuilder.d.mts

@@ -0,0 +1,26 @@
+import { ViewBox } from "../core/coords.mjs";
+import { SceneDoc } from "../scene/types.mjs";
+import { Tool } from "./tools.mjs";
+import { ReactNode } from "react";
+
+//#region src/builder/SceneBuilder.d.ts
+interface SceneBuilderProps {
+  initial?: SceneDoc;
+  onSave?: (doc: SceneDoc) => void;
+  view?: ViewBox;
+  height?: number;
+  tools?: Tool[];
+  /** Authoring mode: adds slider/label tools, a live scalar strip, and the
+   *  pedagogy (LabMeta) editor; onSave emits meta.pedagogy. */
+  authoring?: boolean;
+}
+declare function SceneBuilder({
+  initial,
+  onSave,
+  view,
+  height,
+  tools,
+  authoring
+}: SceneBuilderProps): ReactNode;
+//#endregion
+export { SceneBuilder, SceneBuilderProps };

package/dist/builder/SceneBuilder.mjs

@@ -0,0 +1,340 @@
+'use client';
+
+import { Stage } from "../view/Stage.mjs";
+import { Point } from "../primitives/Dot.mjs";
+import { Axes, Grid } from "../primitives/Grid.mjs";
+import { isCircleVal, isFree, isLineVal, isVec2 } from "../scene/types.mjs";
+import { emptyDoc } from "../scene/migrate.mjs";
+import { renderElements } from "../scene/render.mjs";
+import { useEditor } from "./editor.mjs";
+import { Palette } from "./Palette.mjs";
+import { AUTHORING_TOOLS, GEOMETRY_TOOLS } from "./tools.mjs";
+import { useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/builder/SceneBuilder.tsx
+/**
+* <SceneBuilder> — the click-to-construct authoring surface. Pick a tool, click
+* the canvas: every action funnels through the Editor command stack (undo/redo +
+* the agent API). Output is a SceneDoc (onSave) — the same JSON the player
+* renders and the DB stores. Free points drag only in Select mode, so clicks in
+* other tools go to the tool, not a drag.
+*/
+const DEFAULT_VIEW = {
+	xMin: -8,
+	xMax: 8,
+	yMin: -5,
+	yMax: 5
+};
+const MATH_TOL = .45;
+const snap = (m) => ({
+	x: Math.round(m.x * 2) / 2,
+	y: Math.round(m.y * 2) / 2
+});
+function SceneBuilder({ initial, onSave, view, height = 440, tools, authoring = false }) {
+	const toolSet = tools ?? (authoring ? AUTHORING_TOOLS : GEOMETRY_TOOLS);
+	const { editor, doc, resolved } = useEditor(initial ?? emptyDoc());
+	const [activeTool, setActiveTool] = useState("point");
+	const [pending, setPending] = useState([]);
+	const [pedagogy, setPedagogy] = useState(() => initial?.meta?.pedagogy ?? {});
+	const v = view ?? doc.view ?? DEFAULT_VIEW;
+	const tool = toolSet.find((t) => t.id === activeTool) ?? toolSet[0];
+	const hasPedagogy = Object.values(pedagogy).some((x) => Array.isArray(x) ? x.length : x != null && x !== "");
+	const sceneWithMeta = () => {
+		const s = editor.getScene();
+		return hasPedagogy ? {
+			...s,
+			meta: {
+				...s.meta,
+				pedagogy
+			}
+		} : s;
+	};
+	const scalars = doc.elements.filter((e) => e.kind === "scalar" && isFree(e));
+	const hitPoint = (m) => {
+		let best = null;
+		let bestD = MATH_TOL;
+		for (const el of doc.elements) {
+			if (el.kind !== "point") continue;
+			const val = resolved.values.get(el.id);
+			if (!isVec2(val)) continue;
+			const d = Math.hypot(val.x - m.x, val.y - m.y);
+			if (d < bestD) {
+				bestD = d;
+				best = el.id;
+			}
+		}
+		return best;
+	};
+	const hitElement = (m) => {
+		let best = null;
+		let bestD = MATH_TOL;
+		for (const el of doc.elements) {
+			const val = resolved.values.get(el.id);
+			if (isCircleVal(val)) {
+				const d = Math.abs(Math.hypot(val.center.x - m.x, val.center.y - m.y) - val.r);
+				if (d < bestD) {
+					bestD = d;
+					best = el.id;
+				}
+			} else if (isLineVal(val)) {
+				const ab = {
+					x: val.b.x - val.a.x,
+					y: val.b.y - val.a.y
+				};
+				const len2 = ab.x * ab.x + ab.y * ab.y || 1;
+				let t = ((m.x - val.a.x) * ab.x + (m.y - val.a.y) * ab.y) / len2;
+				if (el.kind === "segment") t = Math.max(0, Math.min(1, t));
+				const cp = {
+					x: val.a.x + t * ab.x,
+					y: val.a.y + t * ab.y
+				};
+				const d = Math.hypot(cp.x - m.x, cp.y - m.y);
+				if (d < bestD) {
+					bestD = d;
+					best = el.id;
+				}
+			}
+		}
+		return best;
+	};
+	const nextId = (prefix) => {
+		const used = new Set(editor.getScene().elements.map((e) => e.id));
+		if (prefix === "P") {
+			for (const ch of "ABCDEFGHJKLMNOPQRSTUVWXYZ") if (!used.has(ch)) return ch;
+		}
+		let i = 1;
+		while (used.has(`${prefix}${i}`)) i += 1;
+		return `${prefix}${i}`;
+	};
+	const handlePoint = (mArr) => {
+		const m = {
+			x: mArr[0],
+			y: mArr[1]
+		};
+		const ctx = {
+			editor,
+			hitPoint,
+			hitElement,
+			pending,
+			setPending,
+			snap,
+			nextId
+		};
+		tool.onPoint(ctx, m);
+	};
+	const selectTool = (id) => {
+		setActiveTool(id);
+		setPending([]);
+	};
+	const clear = () => {
+		const cmds = editor.getScene().elements.map((e) => ({
+			op: "remove",
+			id: e.id
+		}));
+		if (cmds.length) editor.dispatch({
+			op: "batch",
+			label: "clear",
+			commands: cmds
+		});
+		setPending([]);
+	};
+	const pendingDots = useMemo(() => pending.map((id) => {
+		const val = resolved.values.get(id);
+		return isVec2(val) ? /* @__PURE__ */ jsx(Point, {
+			x: val.x,
+			y: val.y,
+			r: 9,
+			color: "var(--stage-warn)"
+		}, `pend-${id}`) : null;
+	}), [pending, resolved]);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "not-prose",
+		style: {
+			display: "flex",
+			flexDirection: "column",
+			gap: 10
+		},
+		children: [
+			/* @__PURE__ */ jsx(Palette, {
+				tools: toolSet,
+				activeTool,
+				onSelect: selectTool,
+				onUndo: () => editor.undo(),
+				onRedo: () => editor.redo(),
+				canUndo: editor.canUndo(),
+				canRedo: editor.canRedo(),
+				onClear: clear,
+				onSave: onSave ? () => onSave(sceneWithMeta()) : void 0,
+				hint: tool.hint
+			}),
+			/* @__PURE__ */ jsxs(Stage, {
+				view: v,
+				height,
+				ariaLabel: "Construction builder",
+				onPointerMath: handlePoint,
+				children: [
+					/* @__PURE__ */ jsx(Grid, {}),
+					/* @__PURE__ */ jsx(Axes, { ticks: false }),
+					renderElements(doc, resolved, {
+						draggablePoints: activeTool === "select",
+						onPointMove: (id, p, phase) => phase === "move" ? editor.updateDrag(id, snap(p)) : editor.endDrag(id, snap(p))
+					}),
+					pendingDots
+				]
+			}),
+			authoring && scalars.length > 0 && /* @__PURE__ */ jsx("div", {
+				style: {
+					display: "flex",
+					flexWrap: "wrap",
+					gap: 14,
+					padding: "2px",
+					fontSize: 13
+				},
+				children: scalars.map((el) => {
+					const f = el.free;
+					return /* @__PURE__ */ jsxs("label", {
+						style: {
+							display: "inline-flex",
+							alignItems: "center",
+							gap: 6
+						},
+						children: [
+							/* @__PURE__ */ jsx("strong", { children: el.label ?? el.id }),
+							/* @__PURE__ */ jsx("input", {
+								type: "range",
+								min: f.min ?? 0,
+								max: f.max ?? 10,
+								step: f.step ?? 1,
+								value: f.value,
+								onChange: (e) => editor.dispatch({
+									op: "mutate",
+									id: el.id,
+									patch: { free: { value: Number(e.currentTarget.value) } }
+								})
+							}),
+							/* @__PURE__ */ jsx("span", {
+								style: {
+									fontVariantNumeric: "tabular-nums",
+									minWidth: 24
+								},
+								children: f.value
+							})
+						]
+					}, el.id);
+				})
+			}),
+			authoring && /* @__PURE__ */ jsxs("details", {
+				style: {
+					fontSize: 13,
+					border: "1px solid var(--stage-muted)",
+					borderRadius: 8,
+					padding: "6px 10px"
+				},
+				children: [/* @__PURE__ */ jsx("summary", {
+					style: {
+						cursor: "pointer",
+						fontWeight: 600
+					},
+					children: "Pedagogy — objectives · hints · difficulty"
+				}), /* @__PURE__ */ jsxs("div", {
+					style: {
+						display: "grid",
+						gap: 8,
+						marginTop: 8
+					},
+					children: [
+						/* @__PURE__ */ jsxs("label", {
+							style: {
+								display: "grid",
+								gap: 3
+							},
+							children: ["Objectives (one per line)", /* @__PURE__ */ jsx("textarea", {
+								rows: 2,
+								value: (pedagogy.objectives ?? []).join("\n"),
+								onChange: (e) => setPedagogy((p) => ({
+									...p,
+									objectives: splitLines(e.currentTarget.value)
+								})),
+								style: FIELD
+							})]
+						}),
+						/* @__PURE__ */ jsxs("label", {
+							style: {
+								display: "grid",
+								gap: 3
+							},
+							children: ["Hints (one per line)", /* @__PURE__ */ jsx("textarea", {
+								rows: 2,
+								value: (pedagogy.hints ?? []).join("\n"),
+								onChange: (e) => setPedagogy((p) => ({
+									...p,
+									hints: splitLines(e.currentTarget.value)
+								})),
+								style: FIELD
+							})]
+						}),
+						/* @__PURE__ */ jsxs("label", {
+							style: {
+								display: "grid",
+								gap: 3
+							},
+							children: ["Success criteria", /* @__PURE__ */ jsx("input", {
+								value: pedagogy.successCriteria ?? "",
+								onChange: (e) => setPedagogy((p) => ({
+									...p,
+									successCriteria: e.currentTarget.value || void 0
+								})),
+								style: FIELD
+							})]
+						}),
+						/* @__PURE__ */ jsxs("label", {
+							style: {
+								display: "inline-flex",
+								alignItems: "center",
+								gap: 8
+							},
+							children: ["Difficulty", /* @__PURE__ */ jsxs("select", {
+								value: pedagogy.difficulty ?? "",
+								onChange: (e) => setPedagogy((p) => ({
+									...p,
+									difficulty: e.currentTarget.value ? Number(e.currentTarget.value) : void 0
+								})),
+								style: {
+									...FIELD,
+									width: "auto"
+								},
+								children: [/* @__PURE__ */ jsx("option", {
+									value: "",
+									children: "—"
+								}), [
+									1,
+									2,
+									3,
+									4,
+									5
+								].map((d) => /* @__PURE__ */ jsx("option", {
+									value: d,
+									children: d
+								}, d))]
+							})]
+						})
+					]
+				})]
+			})
+		]
+	});
+}
+const FIELD = {
+	width: "100%",
+	border: "1px solid var(--stage-muted)",
+	borderRadius: 6,
+	padding: "4px 8px",
+	background: "transparent",
+	color: "inherit",
+	font: "inherit"
+};
+const splitLines = (s) => s.split("\n").map((x) => x.trim()).filter(Boolean);
+
+//#endregion
+export { SceneBuilder };

package/dist/builder/controls.d.mts

@@ -0,0 +1,18 @@
+import { Id } from "../scene/types.mjs";
+import { Editor } from "./editor.mjs";
+import { ControlMap } from "../core/control.mjs";
+
+//#region src/builder/controls.d.ts
+interface ControlPick {
+  /** Element id of a free scalar (slider / unknown). */
+  id: Id;
+  /** Public control name (what an agent addresses). */
+  name: string;
+  label?: string;
+  min?: number;
+  max?: number;
+  step?: number;
+}
+declare function controlsFromScene(editor: Editor, picks: ControlPick[]): ControlMap;
+//#endregion
+export { ControlPick, controlsFromScene };

package/dist/builder/controls.mjs

@@ -0,0 +1,29 @@
+'use client';
+
+//#region src/builder/controls.ts
+function controlsFromScene(editor, picks) {
+	const map = {};
+	for (const p of picks) map[p.name] = {
+		type: "number",
+		label: p.label,
+		min: p.min,
+		max: p.max,
+		step: p.step,
+		get: () => {
+			const v = editor.getResolved().values.get(p.id);
+			return typeof v === "number" ? v : 0;
+		},
+		set: (v) => {
+			editor.dispatch({
+				op: "mutate",
+				id: p.id,
+				patch: { free: { value: v } }
+			});
+			editor.mark(`set ${p.name}`);
+		}
+	};
+	return map;
+}
+
+//#endregion
+export { controlsFromScene };

package/dist/builder/editor.d.mts

@@ -0,0 +1,46 @@
+import { Vec2 } from "../core/vec.mjs";
+import { Id, SceneDoc } from "../scene/types.mjs";
+import { Command, CommandResult } from "../scene/commands.mjs";
+import { Resolved } from "../scene/resolve.mjs";
+
+//#region src/builder/editor.d.ts
+interface DispatchOpts {
+  history?: 'record' | 'ignore';
+}
+declare class Editor {
+  private doc;
+  private undoStack;
+  private redoStack;
+  private overlay;
+  private listeners;
+  private prev?;
+  constructor(doc: SceneDoc);
+  getScene(): SceneDoc;
+  /** Replace the whole scene (e.g. the authored config changed in the editor). */
+  reset(doc: SceneDoc): void;
+  getResolved(): Resolved;
+  subscribe(fn: () => void): () => void;
+  private emit;
+  /** Apply a command. The ONLY mutation entry point. */
+  dispatch(cmd: Command, opts?: DispatchOpts): CommandResult;
+  /** Group boundary marker (label-only in this impl; batch commands group atomically). */
+  mark(_label?: string): void;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  undo(): void;
+  redo(): void;
+  /** Discard the live drag overlay without committing (drag cancel). */
+  bail(): void;
+  beginDrag(_id: Id): void;
+  updateDrag(id: Id, p: Vec2): void;
+  endDrag(id: Id, p: Vec2): void;
+  getOverlay(): ReadonlyMap<Id, Vec2>;
+}
+/** React binding: holds one Editor and re-renders on its changes. */
+declare function useEditor(initial: SceneDoc): {
+  editor: Editor;
+  doc: SceneDoc;
+  resolved: Resolved;
+};
+//#endregion
+export { DispatchOpts, Editor, useEditor };

package/dist/builder/editor.mjs

@@ -0,0 +1,130 @@
+'use client';
+
+import { resolve } from "../scene/resolve.mjs";
+import { applyCommand, inverse } from "../scene/commands.mjs";
+import { useEffect, useReducer, useRef, useState } from "react";
+
+//#region src/builder/editor.ts
+/**
+* Editor — the single funnel for ALL scene mutations (builder tools, agents,
+* undo/redo, the control-surface bridge). Commands ARE the agent action API:
+* dispatch(cmd) is exactly what a human tool, a voice agent, and an undo all call.
+* Drag is an ephemeral overlay layer; updateDrag writes no command (no undo, no
+* persist), endDrag commits ONE mutate.
+*/
+var Editor = class {
+	doc;
+	undoStack = [];
+	redoStack = [];
+	overlay = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	prev;
+	constructor(doc) {
+		this.doc = doc;
+	}
+	getScene() {
+		return this.doc;
+	}
+	/** Replace the whole scene (e.g. the authored config changed in the editor). */
+	reset(doc) {
+		this.doc = doc;
+		this.undoStack = [];
+		this.redoStack = [];
+		this.overlay.clear();
+		this.prev = void 0;
+		this.emit();
+	}
+	getResolved() {
+		const r = resolve(this.doc, this.overlay.size ? this.overlay : void 0, this.prev);
+		this.prev = r;
+		return r;
+	}
+	subscribe(fn) {
+		this.listeners.add(fn);
+		return () => {
+			this.listeners.delete(fn);
+		};
+	}
+	emit() {
+		this.listeners.forEach((l) => l());
+	}
+	/** Apply a command. The ONLY mutation entry point. */
+	dispatch(cmd, opts = {}) {
+		const inv = inverse(cmd, this.doc);
+		this.doc = applyCommand(this.doc, cmd);
+		if (opts.history !== "ignore") {
+			this.undoStack.push({
+				cmd,
+				inv
+			});
+			this.redoStack = [];
+		}
+		this.emit();
+		return { ok: true };
+	}
+	/** Group boundary marker (label-only in this impl; batch commands group atomically). */
+	mark(_label) {}
+	canUndo() {
+		return this.undoStack.length > 0;
+	}
+	canRedo() {
+		return this.redoStack.length > 0;
+	}
+	undo() {
+		const entry = this.undoStack.pop();
+		if (!entry) return;
+		this.doc = applyCommand(this.doc, entry.inv);
+		this.redoStack.push(entry);
+		this.emit();
+	}
+	redo() {
+		const entry = this.redoStack.pop();
+		if (!entry) return;
+		this.doc = applyCommand(this.doc, entry.cmd);
+		this.undoStack.push(entry);
+		this.emit();
+	}
+	/** Discard the live drag overlay without committing (drag cancel). */
+	bail() {
+		this.overlay.clear();
+		this.emit();
+	}
+	beginDrag(_id) {}
+	updateDrag(id, p) {
+		this.overlay.set(id, p);
+		this.emit();
+	}
+	endDrag(id, p) {
+		this.overlay.delete(id);
+		this.dispatch({
+			op: "mutate",
+			id,
+			patch: { free: { at: p } }
+		});
+	}
+	getOverlay() {
+		return this.overlay;
+	}
+};
+/** React binding: holds one Editor and re-renders on its changes. */
+function useEditor(initial) {
+	const [editor] = useState(() => new Editor(initial));
+	const [, force] = useReducer((x) => x + 1, 0);
+	useEffect(() => editor.subscribe(() => force()), [editor]);
+	const firstRun = useRef(true);
+	useEffect(() => {
+		if (firstRun.current) {
+			firstRun.current = false;
+			return;
+		}
+		editor.reset(initial);
+	}, [editor, initial]);
+	return {
+		editor,
+		doc: editor.getScene(),
+		resolved: editor.getResolved()
+	};
+}
+
+//#endregion
+export { Editor, useEditor };

package/dist/builder/icons.d.mts

@@ -0,0 +1,14 @@
+import { ReactNode } from "react";
+
+//#region src/builder/icons.d.ts
+type IconName = 'select' | 'point' | 'segment' | 'line' | 'circle' | 'midpoint' | 'intersect' | 'measure' | 'scalar' | 'note' | 'delete' | 'undo' | 'redo';
+/** A single builder icon. `size` in px; inherits `currentColor`. Decorative. */
+declare function ToolIcon({
+  name,
+  size
+}: {
+  name: IconName;
+  size?: number;
+}): ReactNode;
+//#endregion
+export { IconName, ToolIcon };