@classytic/stage 0.1.0

package/dist/view/useElementSize.mjs

@@ -0,0 +1,40 @@
+'use client';
+
+import { useEffect, useRef, useState } from "react";
+
+//#region src/view/useElementSize.ts
+/**
+* SSR-safe size observer. Returns `null` before mount so callers fall back to
+* explicit/default dimensions and render REAL content on first paint (no
+* blank-until-JS). After mount, a ResizeObserver reports the measured box.
+*/
+function useElementSize() {
+	const ref = useRef(null);
+	const [size, setSize] = useState(null);
+	useEffect(() => {
+		const el = ref.current;
+		if (!el || typeof ResizeObserver === "undefined") return;
+		const ro = new ResizeObserver((entries) => {
+			const e = entries[0];
+			if (!e) return;
+			setSize({
+				width: e.contentRect.width,
+				height: e.contentRect.height
+			});
+		});
+		ro.observe(el);
+		const r = el.getBoundingClientRect();
+		if (r.width > 0) setSize({
+			width: r.width,
+			height: r.height
+		});
+		return () => ro.disconnect();
+	}, []);
+	return {
+		ref,
+		size
+	};
+}
+
+//#endregion
+export { useElementSize };

package/dist/view/useInView.d.mts

@@ -0,0 +1,9 @@
+import { RefObject } from "react";
+
+//#region src/view/useInView.d.ts
+declare function useInView<T extends Element = HTMLDivElement>(rootMargin?: string): {
+  ref: RefObject<T | null>;
+  inView: boolean;
+};
+//#endregion
+export { useInView };

package/dist/view/useInView.mjs

@@ -0,0 +1,33 @@
+'use client';
+
+import { useEffect, useRef, useState } from "react";
+
+//#region src/view/useInView.ts
+/**
+* useInView — pause work when a lab scrolls off-screen. Sim labs drive an
+* unbounded requestAnimationFrame loop; without this, every sim on a page runs
+* forever even when nobody can see it (and a gallery of labs pins the CPU). Gate
+* `useFrameLoop({ running: inView })` on this. SSR-safe; if IntersectionObserver
+* is unavailable it assumes visible (never silently freezes a lab).
+*/
+function useInView(rootMargin = "160px") {
+	const ref = useRef(null);
+	const [inView, setInView] = useState(false);
+	useEffect(() => {
+		const el = ref.current;
+		if (!el || typeof IntersectionObserver === "undefined") {
+			setInView(true);
+			return;
+		}
+		const io = new IntersectionObserver((entries) => setInView(entries.some((e) => e.isIntersecting)), { rootMargin });
+		io.observe(el);
+		return () => io.disconnect();
+	}, [rootMargin]);
+	return {
+		ref,
+		inView
+	};
+}
+
+//#endregion
+export { useInView };

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "@classytic/stage",
+  "version": "0.1.0",
+  "description": "Domain-neutral visual primitive engine for the web. Declarative SVG diagram/math primitives, draggable handles, a math↔pixel coordinate system, a motion core + energy effect defs, theming, pure sim cores, and a small kit of neutral glyph primitives. Reactive, web-native, agent-drivable. The render foundation under @classytic/labs (subject-matter glyphs live there); canvas + 3D subpaths later.",
+  "author": "Classytic",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css",
+    "**/assets/**"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.mts",
+      "default": "./dist/core/index.mjs"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.mts",
+      "default": "./dist/primitives/index.mjs"
+    },
+    "./interaction": {
+      "types": "./dist/interaction/index.d.mts",
+      "default": "./dist/interaction/index.mjs"
+    },
+    "./view": {
+      "types": "./dist/view/index.d.mts",
+      "default": "./dist/view/index.mjs"
+    },
+    "./scene": {
+      "types": "./dist/scene/index.d.mts",
+      "default": "./dist/scene/index.mjs"
+    },
+    "./builder": {
+      "types": "./dist/builder/index.d.mts",
+      "default": "./dist/builder/index.mjs"
+    },
+    "./assets": {
+      "types": "./dist/assets/index.d.mts",
+      "default": "./dist/assets/index.mjs"
+    },
+    "./math": {
+      "types": "./dist/math/index.d.mts",
+      "default": "./dist/math/index.mjs"
+    },
+    "./sim": {
+      "types": "./dist/sim/index.d.mts",
+      "default": "./dist/sim/index.mjs"
+    },
+    "./field": {
+      "types": "./dist/field/index.d.mts",
+      "default": "./dist/field/index.mjs"
+    },
+    "./thermo": {
+      "types": "./dist/thermo/index.d.mts",
+      "default": "./dist/thermo/index.mjs"
+    },
+    "./chem": {
+      "types": "./dist/chem/index.d.mts",
+      "default": "./dist/chem/index.mjs"
+    },
+    "./lesson": {
+      "types": "./dist/lesson/index.d.mts",
+      "default": "./dist/lesson/index.mjs"
+    },
+    "./styles.css": "./styles.css",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "styles.css",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "sync": "node scripts/sync-stage.mjs",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "verify": "npm run typecheck && npm test",
+    "push": "classytic-push",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm run build && changeset publish",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "peerDependencies": {
+    "katex": ">=0.16",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "katex": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.9",
+    "@classytic/dev-tools": "^0.2.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/katex": "^0.16.7",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "happy-dom": "^20.0.0",
+    "katex": "^0.16.11",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "keywords": [
+    "react",
+    "svg",
+    "visualization",
+    "interactive",
+    "geometry",
+    "diagram",
+    "coordinate-system",
+    "draggable",
+    "math",
+    "engine",
+    "primitives"
+  ]
+}

package/styles.css

@@ -0,0 +1,70 @@
+/**
+ * @classytic/stage — theme tokens.
+ *
+ * Import once in your app's global CSS:
+ *   @import "@classytic/stage/styles.css";
+ *
+ * THEME-AWARE: the drawing surface + neutrals bind to the host's shadcn tokens
+ * (`--card`, `--card-foreground`, `--foreground`, `--muted-foreground`), so a
+ * stage adopts the app's LIGHT or DARK theme automatically — no fixed dark
+ * canvas. Domain colours (metal/pan/sheen/grid) have no shadcn equivalent, so
+ * they carry tuned light values in `:root` and brighter dark values in `.dark`
+ * (same split globals.css uses). Override any token in your own `:root`/`.dark`
+ * to retheme every stage at once. (Each value keeps a literal fallback so a
+ * non-shadcn host still renders.)
+ */
+
+@source "./dist/**/*.mjs";
+
+:root {
+  /* Surface + neutrals follow the host theme (light here). */
+  --stage-bg: var(--card, oklch(1 0 0));
+  --stage-fg: var(--card-foreground, oklch(0.20 0.02 260));
+  --stage-muted: var(--muted-foreground, oklch(0.55 0.02 260));
+  --stage-grid: color-mix(in oklab, var(--foreground, oklch(0.2 0.02 260)) 14%, transparent);
+  --stage-axis: color-mix(in oklab, var(--foreground, oklch(0.2 0.02 260)) 42%, transparent);
+
+  /* Accents — host brand where one exists; the rest tuned to read on a LIGHT
+     surface (lower lightness / more chroma than the dark-mode values below). */
+  --stage-accent: var(--primary, oklch(0.59 0.22 261));
+  --stage-accent-2: var(--brand-2, oklch(0.62 0.18 48));
+  --stage-good: var(--success, oklch(0.58 0.16 150));
+  --stage-warn: var(--warning, oklch(0.68 0.15 72));
+  --stage-danger: var(--destructive, oklch(0.62 0.24 25));
+
+  /* Asset kit. metal/pan are domain greys → a mid grey that reads on white.
+     The unknown (weight) tracks the brand. --stage-sheen is the top-edge
+     highlight so components never hardcode #fff. */
+  --stage-metal: oklch(0.62 0.02 255);
+  --stage-pan: oklch(0.66 0.02 255);
+  --stage-weight: var(--primary, oklch(0.59 0.22 261));
+  --stage-weight-2: var(--brand-2, oklch(0.62 0.18 48));
+  --stage-sheen: oklch(1 0 0);
+  --stage-liquid: oklch(0.6 0.13 220 / 0.55);
+  --stage-handle-ring: color-mix(in oklab, var(--primary, oklch(0.59 0.22 261)) 40%, transparent);
+
+  /* Electronics — semantic aliases so circuit symbols never hardcode a colour.
+     Override these alone to retheme every circuit lab. wire = leads/conductors,
+     live = energised current path, charge = capacitor field / stored charge. */
+  --stage-wire: var(--stage-metal);
+  --stage-live: var(--stage-good);
+  --stage-charge: var(--stage-accent);
+}
+
+.dark {
+  /* Brighter neutrals + accents so glyphs pop on the dark card surface. */
+  --stage-bg: var(--card, oklch(0.20 0.02 260));
+  --stage-fg: var(--card-foreground, oklch(0.92 0.01 255));
+  --stage-muted: var(--muted-foreground, oklch(0.70 0.02 260));
+  --stage-grid: color-mix(in oklab, var(--foreground, oklch(0.95 0.01 255)) 18%, transparent);
+  --stage-axis: color-mix(in oklab, var(--foreground, oklch(0.95 0.01 255)) 45%, transparent);
+
+  --stage-accent-2: var(--brand-2, oklch(0.78 0.16 50));
+  --stage-good: var(--success, oklch(0.72 0.17 150));
+  --stage-warn: var(--warning, oklch(0.82 0.16 85));
+
+  --stage-metal: oklch(0.85 0.018 255);
+  --stage-pan: oklch(0.83 0.02 255);
+  --stage-weight-2: var(--brand-2, oklch(0.74 0.15 50));
+  --stage-liquid: oklch(0.7 0.13 220 / 0.6);
+}