axstack 0.36.1 → 0.38.0

package/skills/axstack-anatomy/scripts/react-dots-opacity.test.mjs

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import test from "node:test";
+import * as G from "../kit/lathe.mjs";
+const require = createRequire(import.meta.url);
+const ts = require("typescript");
+const React = require("react");
+const { renderToStaticMarkup } = require("react-dom/server");
+const directory = mkdtempSync(join(tmpdir(), "anatomy-react-solid-"));
+try {
+  for (const file of ["kit/iso-kit.ts", "kit/react/live.tsx", "kit/react/draw.tsx"]) {
+    const output = join(directory, file.replace(/\.tsx?$/, ".js"));
+    mkdirSync(dirname(output), { recursive: true });
+    const result = ts.transpileModule(readFileSync(resolve(file), "utf8"), { fileName: file, compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022, jsx: ts.JsxEmit.React } });
+    writeFileSync(output, result.outputText);
+  }
+  const { Dots } = require(join(directory, "kit/react/draw.js"));
+  const P = { origin: [0, 0], scale: 1, azimuth: 45, elevation: 30 };
+  test("actual React renderer preserves the kit's faded bolt circle", () => {
+    const points = G.dotsOf(G.frameAlong([0, 0, 0], [0, 0, 1]), 2, 4, 32, P, { fade: [0.04, 0.42] });
+    assert.ok(points.some((point) => point.length === 3));
+    const html = renderToStaticMarkup(React.createElement(Dots, { points }));
+    const circles = [...html.matchAll(/<circle[^>]*>/g)].map(([circle]) => circle);
+    assert.equal(circles.length, points.length);
+    points.forEach((point, index) => {
+      if (point[2] === undefined) assert.doesNotMatch(circles[index], /fill-opacity/);
+      else assert.equal(Number(circles[index].match(/fill-opacity="([^"]+)"/)[1]), point[2]);
+    });
+  });
+  test("actual React renderer preserves opacity while dots pulse", () => {
+    const html = renderToStaticMarkup(React.createElement(Dots, { points: [[2, 3, 0.25]], pulse: true }));
+    assert.match(html, /fill-opacity="0.25"/);
+    assert.match(html, /data-pulse=""/);
+    assert.match(html, /--pulse-at:0ms/);
+  });
+  test("actual React renderer clamps negative opacity to zero", () => {
+    const html = renderToStaticMarkup(React.createElement(Dots, { points: [[0, 0, -0.5]] }));
+    assert.match(html, /fill-opacity="0"/);
+  });
+  test("actual React renderer preserves ordinary opaque points", () => {
+    const html = renderToStaticMarkup(React.createElement(Dots, { points: [[2.22, 3.33], [4, 5, 1]], size: 0.75, tone: "lo" }));
+    assert.doesNotMatch(html, /fill-opacity/);
+    assert.match(html, /cx="2.2" cy="3.3" r="0.75"/);
+    assert.match(html, /data-tone="lo"/);
+  });
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}

package/skills/axstack-anatomy/scripts/react-readout-first-write.test.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import test from "node:test";
+const require = createRequire(import.meta.url);
+const { build } = require("esbuild");
+const nodePaths = (process.env.NODE_PATH ?? "").split(":").filter(Boolean);
+const alias = Object.fromEntries(["react", "react-dom"].map(name => [name, dirname(require.resolve(name+"/package.json", { paths: nodePaths }))]));
+const directory = mkdtempSync(join(tmpdir(), "anatomy-react-readout-"));
+let observed;
+try {
+  const entry = `import React,{useEffect,useLayoutEffect} from 'react';import {createRoot} from 'react-dom/client';import {flushSync} from 'react-dom';import {useReadout} from ${JSON.stringify(resolve("kit/react/live.tsx"))};
+const changes={};function Probe({mode}){const{anchor,say}=useReadout();useLayoutEffect(()=>{const node=anchor.current.closest('.iso-plate').querySelector('[data-readout]');const observer=new MutationObserver(records=>changes[mode]=(changes[mode]??0)+records.length);observer.observe(node,{childList:true});if(mode==='layout')say('layout');return()=>observer.disconnect();},[]);useEffect(()=>{if(mode==='empty')say('');if(mode==='healthy'||mode==='repeat')say(mode);setTimeout(()=>{if(mode==='layout')say('layout');if(mode==='repeat')say('repeat');},20);},[]);return React.createElement('div',{className:'iso-plate',id:mode},React.createElement('span',{'data-readout':true},'rest'),React.createElement('div',{ref:anchor}));}
+flushSync(()=>createRoot(document.getElementById('root')).render(React.createElement(React.Fragment,null,...['layout','empty','healthy','repeat'].map(mode=>React.createElement(Probe,{key:mode,mode})))));setTimeout(()=>{const values=Object.fromEntries(['layout','empty','healthy','repeat'].map(mode=>[mode,document.querySelector('#'+mode+' [data-readout]').textContent]));window.readoutObserved={values,changes};document.getElementById('results').textContent=JSON.stringify(window.readoutObserved);},100);`;
+  await build({ stdin: { contents: entry, resolveDir: process.cwd(), loader: "jsx" }, bundle: true, outfile: join(directory, "fixture.js"), platform: "browser", nodePaths, alias });
+  writeFileSync(join(directory, "fixture.html"), '<!doctype html><html><body><div id="root"></div><pre id="results"></pre><script src="fixture.js"></script></body></html>');
+  const result = await promisify(execFile)(process.execPath, ["scripts/drive.mjs", join(directory, "fixture.html"), JSON.stringify([["eval", "({observed:window.readoutObserved,html:document.body.innerHTML})"]])], { timeout: 30000, maxBuffer: 16 * 1024 * 1024 });
+  const payload = result.stdout.match(/eval: (.*)/);
+  assert.ok(payload, "actual ReactDOM client must complete and publish its native DOM observations");
+  const inspection = JSON.parse(payload[1]);
+  observed = inspection.observed;
+  console.log("actual client inspection:", JSON.stringify(inspection));
+  assert.ok(observed?.values, `actual native observations are required: ${result.stdout}`);
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}
+test("native ReactDOM readout accepts its first empty text", () => assert.equal(observed.values.empty, ""));
+test("native ReactDOM readout accepts layout-effect text before passive binding", () => assert.equal(observed.values.layout, "layout"));
+test("native ReactDOM readout preserves ordinary passive-effect text", () => assert.equal(observed.values.healthy, "healthy"));
+test("native ReactDOM readout preserves duplicate-write suppression", () => {
+  assert.equal(observed.values.repeat, "repeat");
+  assert.equal(observed.changes.repeat, 1);
+});

package/skills/axstack-anatomy/scripts/react-solid-seamless.test.mjs

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import test from "node:test";
+import * as G from "../kit/lathe.mjs";
+const require = createRequire(import.meta.url);
+const ts = require("typescript");
+const React = require("react");
+const { renderToStaticMarkup } = require("react-dom/server");
+const directory = mkdtempSync(join(tmpdir(), "anatomy-react-solid-"));
+try {
+  for (const file of ["kit/iso-kit.ts", "kit/react/live.tsx", "kit/react/draw.tsx"]) {
+    const output = join(directory, file.replace(/\.tsx?$/, ".js"));
+    mkdirSync(dirname(output), { recursive: true });
+    const result = ts.transpileModule(readFileSync(resolve(file), "utf8"), { fileName: file, compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022, jsx: ts.JsxEmit.React } });
+    writeFileSync(output, result.outputText);
+  }
+  const { Solid } = require(join(directory, "kit/react/draw.js"));
+  const P = { origin: [0, 0], scale: 1, azimuth: 45, elevation: 30 };
+  for (const lit of [false, true]) test(`actual React renderer preserves seamless sphere tone regions with lit=${lit}`, () => {
+    const paths = G.sphereOf([0, 0, 0], 4, P);
+    assert.equal(paths.seamless, true);
+    assert.ok(paths.shades.some(Boolean));
+    const html = renderToStaticMarkup(React.createElement("svg", null, React.createElement(Solid, { paths, lit })));
+    assert.match(html, /data-seamless=""/);
+    assert.equal(/data-lit=""/.test(html), lit);
+    assert.match(html, /class="iso-shade"/);
+  });
+  test("actual React renderer preserves ordinary hard solids", () => {
+    const paths = G.prismOf(G.frameAlong([0, 0, 0], [0, 0, 1]), [[-1, -1], [1, -1], [1, 1], [-1, 1]], 0, 2, P);
+    assert.equal(Boolean(paths.seamless), false);
+    const html = renderToStaticMarkup(React.createElement(Solid, { paths }));
+    assert.doesNotMatch(html, /data-seamless/);
+    assert.match(html, /class="iso-line iso-edge"/);
+  });
+  test("actual React renderer preserves seamless opt-out and child ordering", () => {
+    const paths = { ...G.sphereOf([0, 0, 0], 4, P), seamless: false };
+    const html = renderToStaticMarkup(React.createElement(Solid, { paths, inner: React.createElement("circle", { id: "inner" }) }, React.createElement("circle", { id: "child" })));
+    assert.doesNotMatch(html, /data-seamless/);
+    assert.ok(html.indexOf('id="inner"') < html.indexOf('class="iso-line iso-edge"'));
+    assert.ok(html.indexOf('id="child"') > html.indexOf('class="iso-line iso-edge"'));
+  });
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}

package/skills/axstack-anatomy/scripts/react-visibility-target.test.mjs

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import test from "node:test";
+import { promisify } from "node:util";
+const require = createRequire(import.meta.url);
+const { build } = require("esbuild");
+const nodePaths = (process.env.NODE_PATH ?? "").split(":").filter(Boolean);
+const alias = Object.fromEntries(["react", "react-dom"].map(name => [name, dirname(require.resolve(name+"/package.json", { paths: nodePaths }))]));
+const directory = await mkdtemp(join(tmpdir(), "anatomy-visibility-target-"));
+let observed;
+try {
+  const entry = `import React,{StrictMode,useRef,useState,useEffect} from 'react';import {createRoot} from 'react-dom/client';import {flushSync} from 'react-dom';import {useInView} from ${JSON.stringify(resolve("kit/react/live.tsx"))};
+function Probe({mode}){const ref=useRef(null);const [phase,setPhase]=useState(false);const visible=useInView(ref);useEffect(()=>{const timer=setTimeout(()=>setPhase(true),150);return()=>clearTimeout(timer)},[]);const absent=mode==='late'&&!phase;const distant=(mode==='swap'&&!phase)||(mode==='moved'&&phase);return React.createElement('section',{id:'probe-'+mode,'data-visible':String(visible),'data-phase':String(phase)},absent?null:React.createElement('div',{ref,key:mode==='swap'?String(phase):'stable','data-target':mode,style:{position:'absolute',top:distant?'5000px':'20px',left:'20px',width:'20px',height:'20px'}},mode));}
+for(const mode of ['swap','late','healthy','moved','strict'])flushSync(()=>createRoot(document.getElementById(mode)).render(mode==='strict'?React.createElement(StrictMode,null,React.createElement(Probe,{mode})):React.createElement(Probe,{mode})));setTimeout(()=>{window.visibilityObserved=Object.fromEntries(['swap','late','healthy','moved','strict'].map(mode=>[mode,{visible:document.querySelector('#probe-'+mode).dataset.visible,phase:document.querySelector('#probe-'+mode).dataset.phase,top:document.querySelector('[data-target="'+mode+'"]').getBoundingClientRect().top}]))},700);`;
+  await build({ stdin: { contents: entry, resolveDir: process.cwd(), loader: "jsx" }, bundle: true, outfile: join(directory,"fixture.js"), platform: "browser", nodePaths, alias });
+  const page = join(directory,"figure.html");
+  await writeFile(page,'<!doctype html><div class="iso-plate"><div id="swap"></div><div id="late"></div><div id="healthy"></div><div id="moved"></div><div id="strict"></div></div><script src="fixture.js"></script>');
+  const result = await promisify(execFile)(process.execPath,["scripts/drive.mjs",page,JSON.stringify([["eval","window.visibilityObserved"]])],{timeout:30000});
+  const payload = result.stdout.match(/eval: (.*)/);
+  assert.ok(payload, result.stdout);
+  observed = JSON.parse(payload[1]);
+  assert.ok(observed, result.stdout);
+} finally { await rm(directory,{recursive:true,force:true}); }
+test("native visibility observes a replacement node on the same ref",()=>{
+  assert.equal(observed.swap.phase,"true");assert.equal(observed.swap.top,20);assert.equal(observed.swap.visible,"true");
+});
+test("native visibility observes a target mounted after the initial empty ref",()=>{
+  assert.equal(observed.late.phase,"true");assert.equal(observed.late.top,20);assert.equal(observed.late.visible,"true");
+});
+test("an unchanged visible target stays observed",()=>assert.equal(observed.healthy.visible,"true"));
+test("the same target becoming distant retains real visibility updates",()=>{
+  assert.equal(observed.moved.top,5000);assert.equal(observed.moved.visible,"false");
+});
+test("native StrictMode effect replay preserves ordinary observation",()=>assert.equal(observed.strict.visible,"true"));

package/skills/axstack-anatomy/scripts/turn-bench.mjs

@@ -0,0 +1,74 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { TURN } from "../kit/turn.mjs";
+
+const argv = process.argv.slice(2);
+if (!argv.length || argv.includes("--help")) {
+  console.log(`Time a 3D figure's runtime in Node: emit and order over 360 angles, CPU time, median of 7 rounds.
+
+  node scripts/turn-bench.mjs examples/turning-dial/build.mjs [--rounds 7] [--unit 1]
+
+The build module must export T (from turning()); if it also exports follow(values), every angle is mapped through it.`);
+  process.exit(argv.length ? 0 : 1);
+}
+const take = (flag, fallback) => {
+  const at = argv.indexOf(flag);
+  return at < 0 ? fallback : Number(argv[at + 1]);
+};
+const rounds = take("--rounds", 7);
+const unit = take("--unit", 1);
+const mod = await import(pathToFileURL(resolve(argv[0])).href);
+const T = mod.T;
+const follow = mod.follow ?? ((values) => values);
+const scene = TURN.prepare(T.data, { unit });
+const runs = scene.runs;
+const frames = runs.map((run) => TURN.frame(run));
+const turn = T.groups.find((g) => g.kind === "turn");
+const angles = Array.from({ length: 360 }, (_, i) => i + 0.37);
+const cams = angles.map((angle) => TURN.cams(scene, follow({ [turn.name]: angle })));
+for (let i = 0; i < 20; i++) for (const run of runs) TURN.emit(run, run.group >= 0 ? cams[i][run.group] : cams[i].world, frames[run.index]);
+const perPart = runs.map(() => []);
+const orderTimes = [];
+const frameTimes = [];
+const cpuFrames = [];
+for (let round = 0; round < rounds; round++) {
+  const sums = new Float64Array(runs.length);
+  let orderSum = 0;
+  const cpu0 = process.cpuUsage();
+  const wall0 = performance.now();
+  const previous = scene.layers.map((layer) => layer.rest);
+  for (let a = 0; a < angles.length; a++) {
+    const c = cams[a];
+    for (const run of runs) {
+      const t0 = performance.now();
+      TURN.emit(run, run.group >= 0 ? c[run.group] : c.world, frames[run.index]);
+      sums[run.index] += performance.now() - t0;
+    }
+    const t1 = performance.now();
+    scene.layers.forEach((layer, index) => {
+      previous[index] = TURN.order(layer, frames, c, previous[index], {}, scene);
+    });
+    orderSum += performance.now() - t1;
+  }
+  const cpu = process.cpuUsage(cpu0);
+  cpuFrames.push((cpu.user + cpu.system) / 1000 / angles.length);
+  frameTimes.push((performance.now() - wall0) / angles.length);
+  orderTimes.push(orderSum / angles.length);
+  runs.forEach((run, index) => perPart[index].push(sums[index] / angles.length));
+}
+const median = (list) => list.slice().sort((x, y) => x - y)[Math.floor(list.length / 2)];
+const kinds = new Map();
+runs.forEach((run, index) => {
+  const kind = run.kind === "tube" ? "tube chunk" : run.kind;
+  if (!kinds.has(kind)) kinds.set(kind, []);
+  kinds.get(kind).push(median(perPart[index]));
+});
+console.log(`turn-bench ${argv[0]} · ${runs.length} parts · ${angles.length} angles · median of ${rounds} rounds · unit ${unit}`);
+for (const [kind, list] of [...kinds].sort((a, b) => b[1].reduce((s, v) => s + v, 0) - a[1].reduce((s, v) => s + v, 0))) {
+  const total = list.reduce((s, v) => s + v, 0);
+  console.log(`  ${kind.padEnd(11)} ${String(list.length).padStart(4)} parts · ${(total / list.length).toFixed(4)} ms per part · ${total.toFixed(3)} ms per frame · slowest ${Math.max(...list).toFixed(4)} ms`);
+}
+const slow = runs.map((run, index) => [run.name, median(perPart[index])]).sort((a, b) => b[1] - a[1]).slice(0, 6);
+console.log(`  slowest parts: ${slow.map(([name, ms]) => `${name} ${ms.toFixed(3)}`).join(" · ")}`);
+console.log(`  order ${median(orderTimes).toFixed(3)} ms per frame (${scene.layers.map((layer) => `${layer.name}: ${layer.parts.length} parts, ${layer.planar.length / 5} planes, ${layer.dynamic.length / 2} dynamic`).join("; ")})`);
+console.log(`  frame ${median(frameTimes).toFixed(3)} ms wall · ${median(cpuFrames).toFixed(3)} ms CPU`);