@classytic/stage 0.1.0

package/dist/math/tokenize.mjs

@@ -0,0 +1,112 @@
+import { isFunction } from "./defs.mjs";
+
+//#region src/math/tokenize.ts
+/**
+* expr/tokenize — source string → token stream.
+*
+* Handles numbers (incl. `1.5e3`, rejecting malformed `2..3`), identifiers
+* (classified as function vs variable), operators, parens, and commas. Inserts
+* implicit-multiplication operators where two value-producing tokens abut
+* (`2x`, `3sin(x)`, `(x+1)(x-1)`), so the parser stays simple.
+*/
+const isDigit = (c) => c >= "0" && c <= "9";
+const isAlpha = (c) => c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c === "_";
+function tokenize(src) {
+	const raw = [];
+	let i = 0;
+	const s = src.trim();
+	while (i < s.length) {
+		const c = s[i];
+		if (c === " " || c === "	") {
+			i++;
+			continue;
+		}
+		if (isDigit(c) || c === "." && isDigit(s[i + 1] ?? "")) {
+			let j = i;
+			let seenDot = false;
+			while (j < s.length) {
+				const ch = s[j] ?? "";
+				if (isDigit(ch)) {
+					j++;
+					continue;
+				}
+				if (ch === ".") {
+					if (seenDot) throw new Error(`Malformed number near '${s.slice(i, j + 1)}'`);
+					seenDot = true;
+					j++;
+					continue;
+				}
+				break;
+			}
+			if (s[j] === "e" || s[j] === "E") {
+				let k = j + 1;
+				if (s[k] === "+" || s[k] === "-") k++;
+				if (!isDigit(s[k] ?? "")) throw new Error(`Incomplete exponent in number '${s.slice(i, k + 1)}'`);
+				k++;
+				while (isDigit(s[k] ?? "")) k++;
+				j = k;
+			}
+			raw.push({
+				t: "num",
+				v: Number.parseFloat(s.slice(i, j))
+			});
+			i = j;
+			continue;
+		}
+		if (isAlpha(c)) {
+			let j = i + 1;
+			while (j < s.length && (isAlpha(s[j] ?? "") || isDigit(s[j] ?? ""))) j++;
+			const orig = s.slice(i, j);
+			const lower = orig.toLowerCase();
+			raw.push(isFunction(lower) ? {
+				t: "fn",
+				v: lower
+			} : {
+				t: "var",
+				v: orig
+			});
+			i = j;
+			continue;
+		}
+		if (c === "(") {
+			raw.push({ t: "lp" });
+			i++;
+			continue;
+		}
+		if (c === ")") {
+			raw.push({ t: "rp" });
+			i++;
+			continue;
+		}
+		if (c === ",") {
+			raw.push({ t: "comma" });
+			i++;
+			continue;
+		}
+		if ("+-*/%^".includes(c)) {
+			raw.push({
+				t: "op",
+				v: c
+			});
+			i++;
+			continue;
+		}
+		throw new Error(`Unexpected character '${c}'`);
+	}
+	const out = [];
+	for (let k = 0; k < raw.length; k++) {
+		const prev = out[out.length - 1];
+		const cur = raw[k];
+		const prevIsValue = !!prev && (prev.t === "num" || prev.t === "var" || prev.t === "rp");
+		const curStartsValue = cur.t === "num" || cur.t === "var" || cur.t === "fn" || cur.t === "lp";
+		if (prevIsValue && curStartsValue) out.push({
+			t: "op",
+			v: "*"
+		});
+		out.push(cur);
+	}
+	return out;
+}
+
+//#endregion
+export { tokenize };

package/dist/primitives/CanvasLayer.d.mts

@@ -0,0 +1,26 @@
+import { CoordinateSystem, CoordsOptions, ViewBox } from "../core/coords.mjs";
+import { ReactNode } from "react";
+
+//#region src/primitives/CanvasLayer.d.ts
+interface CanvasLayerProps {
+  view: ViewBox;
+  height?: number;
+  /** Draw into the HiDPI 2D context using the coordinate system (math↔px). */
+  draw: (ctx: CanvasRenderingContext2D, coords: CoordinateSystem) => void;
+  /** Pointer in MATH coords on press + drag (e.g. to set a start point). */
+  onPointerMath?: (m: [number, number]) => void;
+  coordsOptions?: CoordsOptions;
+  ariaLabel?: string;
+  className?: string;
+}
+declare function CanvasLayer({
+  view,
+  height,
+  draw,
+  onPointerMath,
+  coordsOptions,
+  ariaLabel,
+  className
+}: CanvasLayerProps): ReactNode;
+//#endregion
+export { CanvasLayer, CanvasLayerProps };

package/dist/primitives/CanvasLayer.mjs

@@ -0,0 +1,87 @@
+'use client';
+
+import { createCoords } from "../core/coords.mjs";
+import { useElementSize } from "../view/useElementSize.mjs";
+import { useEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/CanvasLayer.tsx
+/**
+* <CanvasLayer> — the engine's HIGH-ELEMENT-COUNT escape hatch: a zero-dependency
+* HiDPI <canvas> that shares the engine's coordinate system + clock. Use it when
+* a lab needs a heatmap, a particle/gas sim, or thousands of moving dots at 60fps
+* — cases where one retained SVG node per element would drop frames. Declarative,
+* low-count, accessible figures should stay on <Stage> (SVG); this is the
+* deliberate, bundle-free alternative to a WebGL engine (no Pixi/three dependency)
+* until a lab MEASURABLY needs shaders/tens-of-thousands of textured sprites.
+*
+* `draw(ctx, coords)` runs in CSS-pixel space (the context is pre-scaled for dpr)
+* on mount, on resize, and whenever `draw`'s identity changes — so memoize it on
+* your state (or bump it from a useFrameLoop tick) to drive animation. Overlay a
+* sibling <Stage> with the SAME view for accessible SVG handles/labels on top.
+*/
+function CanvasLayer({ view, height = 320, draw, onPointerMath, coordsOptions, ariaLabel = "interactive canvas", className }) {
+	const { ref: wrapRef, size } = useElementSize();
+	const canvasRef = useRef(null);
+	const dragging = useRef(false);
+	const w = Math.max(1, Math.round(size?.width ?? 640));
+	useEffect(() => {
+		const cv = canvasRef.current;
+		if (!cv) return;
+		const dpr = Math.min(typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1, 2);
+		cv.width = Math.round(w * dpr);
+		cv.height = Math.round(height * dpr);
+		const ctx = cv.getContext("2d");
+		if (!ctx) return;
+		ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+		ctx.clearRect(0, 0, w, height);
+		draw(ctx, createCoords(w, height, view, coordsOptions));
+	}, [
+		w,
+		height,
+		view,
+		draw,
+		coordsOptions
+	]);
+	const toMath = (e) => {
+		const cv = canvasRef.current;
+		if (!cv || !onPointerMath) return null;
+		const rect = cv.getBoundingClientRect();
+		return createCoords(w, height, view, coordsOptions).toMath(e.clientX - rect.left, e.clientY - rect.top);
+	};
+	const fire = (e) => {
+		const m = toMath(e);
+		if (m) onPointerMath(m);
+	};
+	return /* @__PURE__ */ jsx("div", {
+		ref: wrapRef,
+		className,
+		style: { width: "100%" },
+		children: /* @__PURE__ */ jsx("canvas", {
+			ref: canvasRef,
+			role: "img",
+			"aria-label": ariaLabel,
+			style: {
+				display: "block",
+				width: "100%",
+				height,
+				touchAction: "none",
+				cursor: onPointerMath ? "crosshair" : "default"
+			},
+			onPointerDown: onPointerMath ? (e) => {
+				dragging.current = true;
+				e.currentTarget.setPointerCapture(e.pointerId);
+				fire(e);
+			} : void 0,
+			onPointerMove: onPointerMath ? (e) => {
+				if (dragging.current) fire(e);
+			} : void 0,
+			onPointerUp: onPointerMath ? () => {
+				dragging.current = false;
+			} : void 0
+		})
+	});
+}
+
+//#endregion
+export { CanvasLayer };

package/dist/primitives/Dot.d.mts

@@ -0,0 +1,27 @@
+import { StyleProps } from "./props.mjs";
+import { ReactNode } from "react";
+
+//#region src/primitives/Dot.d.ts
+interface DotProps extends StyleProps {
+  x: number;
+  y: number;
+  /** Pixel radius (never scaled). */
+  r?: number;
+}
+declare function Dot({
+  x,
+  y,
+  r,
+  color,
+  opacity
+}: DotProps): ReactNode;
+/** A point with a contrast ring (reads clearly over any background). */
+declare function Point({
+  x,
+  y,
+  r,
+  color,
+  opacity
+}: DotProps): ReactNode;
+//#endregion
+export { Dot, DotProps, Point };

package/dist/primitives/Dot.mjs

@@ -0,0 +1,40 @@
+'use client';
+
+import { fmt } from "../core/coords.mjs";
+import { useCoords } from "../core/context.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/primitives/Dot.tsx
+function Dot({ x, y, r = 5, color = "var(--stage-accent)", opacity = 1 }) {
+	const [px, py] = useCoords().toPx(x, y);
+	return /* @__PURE__ */ jsx("circle", {
+		cx: fmt(px),
+		cy: fmt(py),
+		r,
+		fill: color,
+		opacity
+	});
+}
+/** A point with a contrast ring (reads clearly over any background). */
+function Point({ x, y, r = 6, color = "var(--stage-accent)", opacity = 1 }) {
+	const [px, py] = useCoords().toPx(x, y);
+	return /* @__PURE__ */ jsxs("g", {
+		opacity,
+		children: [/* @__PURE__ */ jsx("circle", {
+			cx: fmt(px),
+			cy: fmt(py),
+			r,
+			fill: color
+		}), /* @__PURE__ */ jsx("circle", {
+			cx: fmt(px),
+			cy: fmt(py),
+			r,
+			fill: "none",
+			stroke: "var(--stage-bg)",
+			strokeWidth: 1.5
+		})]
+	});
+}
+
+//#endregion
+export { Dot, Point };

package/dist/primitives/Grid.d.mts

@@ -0,0 +1,30 @@
+import { ReactNode } from "react";
+
+//#region src/primitives/Grid.d.ts
+/** A "nice" step (1,2,5 × 10ⁿ) so ~`target` gridlines span the range. */
+declare function niceStep(span: number, target?: number): number;
+interface GridProps {
+  step?: number;
+  color?: string;
+}
+declare function Grid({
+  step,
+  color
+}: GridProps): ReactNode;
+interface AxesProps {
+  color?: string;
+  ticks?: boolean;
+  step?: number;
+  /** Show the numeric value at each tick (and a "0" at the origin) so learners
+   *  can READ coordinates off the grid — needed for graphs where the answer is a
+   *  point (systems, plotting). Default off (most figures want a clean axis). */
+  labels?: boolean;
+}
+declare function Axes({
+  color,
+  ticks,
+  step,
+  labels
+}: AxesProps): ReactNode;
+//#endregion
+export { Axes, AxesProps, Grid, GridProps, niceStep };

package/dist/primitives/Grid.mjs

@@ -0,0 +1,122 @@
+'use client';
+
+import { useCoords } from "../core/context.mjs";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/Grid.tsx
+/** A "nice" step (1,2,5 × 10ⁿ) so ~`target` gridlines span the range. */
+function niceStep(span, target = 8) {
+	const raw = Math.abs(span) / target || 1;
+	const magnitude = Math.pow(10, Math.floor(Math.log10(raw)));
+	const n = raw / magnitude;
+	return (n < 1.5 ? 1 : n < 3 ? 2 : n < 7 ? 5 : 10) * magnitude;
+}
+function tickValues(min, max, step) {
+	const out = [];
+	const start = Math.ceil(min / step) * step;
+	for (let v = start; v <= max + step * 1e-6; v += step) out.push(Math.round(v / step) * step);
+	return out;
+}
+function Grid({ step, color = "var(--stage-grid)" }) {
+	const c = useCoords();
+	const s = step ?? niceStep(c.view.xMax - c.view.xMin);
+	const lines = [];
+	for (const x of tickValues(c.view.xMin, c.view.xMax, s)) {
+		const a = c.toPx(x, c.view.yMin);
+		const b = c.toPx(x, c.view.yMax);
+		lines.push(/* @__PURE__ */ jsx("line", {
+			x1: a[0],
+			y1: a[1],
+			x2: b[0],
+			y2: b[1],
+			stroke: color,
+			strokeWidth: 1
+		}, `gx${x}`));
+	}
+	for (const y of tickValues(c.view.yMin, c.view.yMax, s)) {
+		const a = c.toPx(c.view.xMin, y);
+		const b = c.toPx(c.view.xMax, y);
+		lines.push(/* @__PURE__ */ jsx("line", {
+			x1: a[0],
+			y1: a[1],
+			x2: b[0],
+			y2: b[1],
+			stroke: color,
+			strokeWidth: 1
+		}, `gy${y}`));
+	}
+	return /* @__PURE__ */ jsx("g", { children: lines });
+}
+const fmtTick = (v) => Number.isInteger(v) ? String(v) : v.toFixed(1);
+function Axes({ color = "var(--stage-axis)", ticks = true, step, labels = false }) {
+	const c = useCoords();
+	const s = step ?? niceStep(c.view.xMax - c.view.xMin);
+	const xAxisA = c.toPx(c.view.xMin, 0);
+	const xAxisB = c.toPx(c.view.xMax, 0);
+	const yAxisA = c.toPx(0, c.view.yMin);
+	const yAxisB = c.toPx(0, c.view.yMax);
+	const labelStyle = {
+		paintOrder: "stroke",
+		stroke: "var(--stage-bg)",
+		strokeWidth: 3,
+		strokeLinejoin: "round"
+	};
+	const num = (key, px, py, text, anchor) => /* @__PURE__ */ jsx("text", {
+		x: px,
+		y: py,
+		fill: "var(--stage-muted)",
+		fontSize: 11,
+		textAnchor: anchor,
+		dominantBaseline: "middle",
+		style: labelStyle,
+		children: text
+	}, key);
+	const nodes = [/* @__PURE__ */ jsx("line", {
+		x1: xAxisA[0],
+		y1: xAxisA[1],
+		x2: xAxisB[0],
+		y2: xAxisB[1],
+		stroke: color,
+		strokeWidth: 1.5
+	}, "ax"), /* @__PURE__ */ jsx("line", {
+		x1: yAxisA[0],
+		y1: yAxisA[1],
+		x2: yAxisB[0],
+		y2: yAxisB[1],
+		stroke: color,
+		strokeWidth: 1.5
+	}, "ay")];
+	if (ticks) {
+		for (const x of tickValues(c.view.xMin, c.view.xMax, s)) {
+			if (Math.abs(x) < 1e-9) continue;
+			const p = c.toPx(x, 0);
+			nodes.push(/* @__PURE__ */ jsx("line", {
+				x1: p[0],
+				y1: p[1] - 4,
+				x2: p[0],
+				y2: p[1] + 4,
+				stroke: color,
+				strokeWidth: 1.5
+			}, `tx${x}`));
+			if (labels) nodes.push(num(`lx${x}`, p[0], p[1] + 14, fmtTick(x), "middle"));
+		}
+		for (const y of tickValues(c.view.yMin, c.view.yMax, s)) {
+			if (Math.abs(y) < 1e-9) continue;
+			const p = c.toPx(0, y);
+			nodes.push(/* @__PURE__ */ jsx("line", {
+				x1: p[0] - 4,
+				y1: p[1],
+				x2: p[0] + 4,
+				y2: p[1],
+				stroke: color,
+				strokeWidth: 1.5
+			}, `ty${y}`));
+			if (labels) nodes.push(num(`ly${y}`, p[0] - 8, p[1], fmtTick(y), "end"));
+		}
+		if (labels) nodes.push(num("l0", c.toPx(0, 0)[0] - 8, c.toPx(0, 0)[1] + 12, "0", "end"));
+	}
+	return /* @__PURE__ */ jsx("g", { children: nodes });
+}
+
+//#endregion
+export { Axes, Grid, niceStep };

package/dist/primitives/Label.d.mts

@@ -0,0 +1,33 @@
+import { ReactNode } from "react";
+
+//#region src/primitives/Label.d.ts
+interface LabelProps {
+  x: number;
+  y: number;
+  text: string;
+  color?: string;
+  size?: number;
+  /** Pixel offset from the anchor. */
+  dx?: number;
+  dy?: number;
+  anchor?: 'start' | 'middle' | 'end';
+  baseline?: 'auto' | 'middle' | 'hanging';
+  weight?: number;
+}
+/** Upright pixel-space text with a background-colored outline for legibility.
+ *  Renders `_`/`^` as real SVG sub/superscripts via the shared `parseRichText`
+ *  grammar (the same one labs' HTML `<RichText>` uses — one source of truth). */
+declare function Label({
+  x,
+  y,
+  text,
+  color,
+  size,
+  dx,
+  dy,
+  anchor,
+  baseline,
+  weight
+}: LabelProps): ReactNode;
+//#endregion
+export { Label, LabelProps };

package/dist/primitives/Label.mjs

@@ -0,0 +1,45 @@
+'use client';
+
+import { fmt } from "../core/coords.mjs";
+import { parseRichText } from "../core/richText.mjs";
+import { useCoords } from "../core/context.mjs";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/Label.tsx
+/** Upright pixel-space text with a background-colored outline for legibility.
+*  Renders `_`/`^` as real SVG sub/superscripts via the shared `parseRichText`
+*  grammar (the same one labs' HTML `<RichText>` uses — one source of truth). */
+function Label({ x, y, text, color = "var(--stage-fg)", size = 14, dx = 0, dy = 0, anchor = "middle", baseline = "middle", weight = 600 }) {
+	const [px, py] = useCoords().toPx(x, y);
+	const spans = parseRichText(text);
+	const shift = size * .32;
+	let prevLevel = 0;
+	return /* @__PURE__ */ jsx("text", {
+		x: fmt(px + dx),
+		y: fmt(py + dy),
+		fill: color,
+		fontSize: size,
+		fontWeight: weight,
+		textAnchor: anchor,
+		dominantBaseline: baseline,
+		style: {
+			paintOrder: "stroke",
+			stroke: "var(--stage-bg)",
+			strokeWidth: 3,
+			strokeLinejoin: "round"
+		},
+		children: spans.length === 1 && spans[0].script === "base" ? text : spans.map((sp, i) => {
+			const level = sp.script === "sub" ? 1 : sp.script === "sup" ? -1 : 0;
+			const dyPx = (level - prevLevel) * shift;
+			prevLevel = level;
+			return /* @__PURE__ */ jsx("tspan", {
+				dy: fmt(dyPx),
+				fontSize: sp.script === "base" ? void 0 : fmt(size * .72),
+				children: sp.text
+			}, i);
+		})
+	});
+}
+
+//#endregion
+export { Label };

package/dist/primitives/Lines.d.mts

@@ -0,0 +1,50 @@
+import { Vec2 } from "../core/vec.mjs";
+import { StyleProps } from "./props.mjs";
+import { ReactNode } from "react";
+
+//#region src/primitives/Lines.d.ts
+interface SegmentProps extends StyleProps {
+  from: Vec2;
+  to: Vec2;
+}
+declare function Segment({
+  from,
+  to,
+  color,
+  weight,
+  opacity,
+  dashed
+}: SegmentProps): ReactNode;
+interface LineProps extends StyleProps {
+  from: Vec2;
+  to: Vec2;
+}
+declare function Line({
+  from,
+  to,
+  color,
+  weight,
+  opacity,
+  dashed
+}: LineProps): ReactNode;
+declare function Ray({
+  from,
+  to,
+  color,
+  weight,
+  opacity,
+  dashed
+}: LineProps): ReactNode;
+interface VectorProps extends StyleProps {
+  tail?: Vec2;
+  tip: Vec2;
+}
+declare function Vector({
+  tail,
+  tip,
+  color,
+  weight,
+  opacity
+}: VectorProps): ReactNode;
+//#endregion
+export { Line, LineProps, Ray, Segment, SegmentProps, Vector, VectorProps };

package/dist/primitives/Lines.mjs

@@ -0,0 +1,82 @@
+'use client';
+
+import { fmt } from "../core/coords.mjs";
+import { useCoords } from "../core/context.mjs";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/Lines.tsx
+const extend = (c, a, b, back) => {
+	const dx = b[0] - a[0];
+	const dy = b[1] - a[1];
+	const len = Math.hypot(dx, dy) || 1;
+	const ux = dx / len;
+	const uy = dy / len;
+	const big = Math.hypot(c.width, c.height) * 2;
+	return [back ? [a[0] - ux * big, a[1] - uy * big] : a, [a[0] + ux * big, a[1] + uy * big]];
+};
+function Segment({ from, to, color = "var(--stage-fg)", weight = 2, opacity = 1, dashed }) {
+	const c = useCoords();
+	const a = c.toPx(from.x, from.y);
+	const b = c.toPx(to.x, to.y);
+	return /* @__PURE__ */ jsx("line", {
+		x1: fmt(a[0]),
+		y1: fmt(a[1]),
+		x2: fmt(b[0]),
+		y2: fmt(b[1]),
+		stroke: color,
+		strokeWidth: weight,
+		opacity,
+		strokeLinecap: "round",
+		strokeDasharray: dashed ? "6 6" : void 0
+	});
+}
+function Line({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1, dashed }) {
+	const c = useCoords();
+	const [p1, p2] = extend(c, c.toPx(from.x, from.y), c.toPx(to.x, to.y), true);
+	return /* @__PURE__ */ jsx("line", {
+		x1: fmt(p1[0]),
+		y1: fmt(p1[1]),
+		x2: fmt(p2[0]),
+		y2: fmt(p2[1]),
+		stroke: color,
+		strokeWidth: weight,
+		opacity,
+		strokeDasharray: dashed ? "6 6" : void 0
+	});
+}
+function Ray({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1, dashed }) {
+	const c = useCoords();
+	const [p1, p2] = extend(c, c.toPx(from.x, from.y), c.toPx(to.x, to.y), false);
+	return /* @__PURE__ */ jsx("line", {
+		x1: fmt(p1[0]),
+		y1: fmt(p1[1]),
+		x2: fmt(p2[0]),
+		y2: fmt(p2[1]),
+		stroke: color,
+		strokeWidth: weight,
+		opacity,
+		strokeDasharray: dashed ? "6 6" : void 0
+	});
+}
+function Vector({ tail = {
+	x: 0,
+	y: 0
+}, tip, color = "var(--stage-accent-2)", weight = 2.5, opacity = 1 }) {
+	const c = useCoords();
+	const a = c.toPx(tail.x, tail.y);
+	const b = c.toPx(tip.x, tip.y);
+	return /* @__PURE__ */ jsx("line", {
+		x1: fmt(a[0]),
+		y1: fmt(a[1]),
+		x2: fmt(b[0]),
+		y2: fmt(b[1]),
+		stroke: color,
+		strokeWidth: weight,
+		opacity,
+		strokeLinecap: "round",
+		markerEnd: "url(#stage-arrow)"
+	});
+}
+
+//#endregion
+export { Line, Ray, Segment, Vector };