@litfamily/litopencode 1.0.31 → 1.0.33

package/skills/lit-schematic/examples/iso-heat-exchanger/scene.mjs

@@ -0,0 +1,133 @@
+// The heat exchanger as a scene: one function of the camera, the explode amount and the flow
+// phase, so the static figure, the interactive page and the motion loop share one geometry.
+//
+// Parts list (written before any geometry): base pad, two saddles with base plates; front
+// channel with ellipsoidal bonnet, channel and shell flanges with bolt circles, shell with a
+// window cutaway, rear bonnet and flange; inside: twelve tubes split at every baffle, four
+// baffles, two tubesheets; nozzles: shell-side and tube-side inlets with flanges and bolts.
+//
+// Assemblies (groups) and how they come apart for maintenance: the front head (channel, its
+// flange and the tube-side nozzle) comes off first, then the tube bundle is pulled out of the
+// front, the rear head comes off the back; shell and supports stay.
+
+import { createFigure } from "../../scripts/lib/figure.mjs";
+import { createIsoView, ellipsoidalHead, frameAlong } from "../../scripts/lib/iso.mjs";
+
+export const MOVES = Object.freeze({ front: [-230, 0, 0], bundle: [-150, 0, 0], rear: [110, 0, 0] });
+export const ORDER = Object.freeze(["front", "bundle", "rear"]);
+export const LAYERS = Object.freeze([
+  { group: "shell", label: "Shell" },
+  { group: "bundle", label: "Tube bundle" },
+  { group: "front", label: "Front head" },
+  { group: "rear", label: "Rear head" },
+]);
+export const VIEWS = Object.freeze([
+  { id: "front-left", label: "Front left", azimuth: 62, elevation: 28 },
+  { id: "front-high", label: "From above", azimuth: 50, elevation: 48 },
+  { id: "rear-right", label: "Rear right", azimuth: 118, elevation: 26 },
+]);
+
+const Z = 120;
+const R = 60;
+const SHELL = [8, 330];
+const BAFFLES = [80, 140, 200, 260];
+const TUBE_ROWS = [[-30, 18], [-10, 18], [10, 18], [30, 18], [-20, 0], [0, 0], [20, 0], [-30, -18], [-10, -18], [10, -18], [30, -18], [0, 36]];
+
+// explode: 0 assembled .. 1 apart, per group or one number for all. flow: dash phase in mm
+// along the tubes, or null for no flow. reach: keep the exploded positions in frame.
+export function scene({ azimuth = 62, elevation = 28, explode = 0, flow = null, callouts = true, reach = false, width = 160, height = 92 } = {}) {
+  const share = (g) => (typeof explode === "number" ? explode : explode[g] ?? 0);
+  const shift = (g, p) => { const m = MOVES[g] ?? [0, 0, 0]; return [p[0] + m[0] * share(g), p[1] + m[1] * share(g), p[2] + m[2] * share(g)]; };
+  const v = createIsoView({ azimuth, elevation });
+
+  v.halo({ plan: { x: -130, y: -95, w: 520, d: 190, r: 6 }, z: -12 });
+  v.box({ name: "base pad", plan: { x: -130, y: -95, w: 520, d: 190, r: 6 }, z: -12, h: 12, tone: "lo", layer: -1, group: "support" });
+  const saddles = [70, 270].map((sx) => {
+    v.box({ name: `saddle base ${sx}`, plan: { x: sx - 12, y: -52, w: 24, d: 104, r: 2 }, z: 0, h: 5, tone: "frame", group: "support" });
+    return v.box({ name: `saddle ${sx}`, plan: { x: sx - 4, y: -46, w: 8, d: 92 }, z: 5, h: Z - R - 2, tone: "frame", group: "support" });
+  });
+  if (reach) {
+    const far = (g, x) => [[x + MOVES[g][0], -R - 12, Z - R - 12], [x + MOVES[g][0], R + 12, Z + R + 40]];
+    v.extent([...far("front", -110), ...far("rear", 390)]);
+  }
+
+  const axis = "x";
+  const disc = (name, s0, s1, r, { tone = "mid", into = null, group }) =>
+    v.lathe({ name, origin: shift(group, [0, 0, Z]), axis, profile: [[s0, 0], [s0, r], [s1, r], [s1, 0]], tone, into, group });
+
+  // Front head: channel with bonnet, channel flange and bolts, tube-side nozzle.
+  const bonnet = ellipsoidalHead(62).map(([s, r, sm]) => [-70 - s, r, sm]).reverse();
+  v.lathe({ name: "channel", origin: shift("front", [0, 0, Z]), axis, profile: [...bonnet, [-70, 62], [-8, 62], [-8, 0]], tone: "mid", seams: [-70], group: "front" });
+  const channelFlange = disc("channel flange", -8, 0, 72, { group: "front" });
+  v.boltCircle({ name: "channel flange bolts", frame: frameAlong(shift("front", [0, 0, Z]), axis), s: -4, radius: 67, count: 16, group: "front" });
+
+  // Shell with its flanges; the cutaway window shows the bundle inside.
+  disc("shell flange", 0, 8, 72, { group: "shell" });
+  v.boltCircle({ name: "shell flange bolts", frame: frameAlong([0, 0, Z], axis), s: 4, radius: 67, count: 16, group: "shell" });
+  const shell = v.lathe({
+    name: "shell", origin: [0, 0, Z], axis, profile: [[SHELL[0], 0], [SHELL[0], R], [SHELL[1], R], [SHELL[1], 0]],
+    tone: "hi", cut: { from: 40, to: 290, span: 96 }, wall: 4, seams: [120, 220], group: "shell",
+  });
+
+  // Rear head.
+  disc("rear flange", 330, 338, 72, { group: "rear" });
+  v.lathe({ name: "rear bonnet", origin: shift("rear", [0, 0, Z]), axis, profile: [[338, 0], [338, 62], ...ellipsoidalHead(62).map(([s, r, sm]) => [338 + s, r, sm]).slice(1)], tone: "mid", group: "rear" });
+  v.boltCircle({ name: "rear flange bolts", frame: frameAlong(shift("rear", [0, 0, Z]), axis), s: 334, radius: 67, count: 16, group: "rear" });
+
+  // Tube bundle, drawn inside the shell's cutaway: tubesheets, baffles, tubes split at each baffle.
+  disc("front tubesheet", 8, 16, R - 4, { tone: "brass", into: shell, group: "bundle" });
+  disc("rear tubesheet", 322, 330, R - 4, { tone: "brass", into: shell, group: "bundle" });
+  const baffles = BAFFLES.map((s, i) => v.lathe({
+    name: `baffle ${i + 1}`, origin: shift("bundle", [0, 0, Z]), axis,
+    profile: [[s, 0], [s, R - 5], [s + 3, R - 5], [s + 3, 0]], tone: "stainless", into: shell, group: "bundle",
+  }));
+  const stops = [16, ...BAFFLES.flatMap((s) => [s, s + 3]), 322];
+  const tubes = [];
+  TUBE_ROWS.forEach(([y, z], t) => {
+    for (let k = 0; k < stops.length; k += 2) {
+      const origin = shift("bundle", [0, y, Z + z]);
+      tubes.push(v.lathe({ name: `tube ${t + 1}.${k / 2 + 1}`, origin, axis, profile: [[stops[k], 0], [stops[k], 3.5], [stops[k + 1], 3.5], [stops[k + 1], 0]], tone: "copper", steps: 32, into: shell, group: "bundle" }));
+      if (flow !== null) {
+        // Tube-side fluid: dashes on the tube's crown line, marching from the channel end.
+        const a = [origin[0] + stops[k], origin[1], origin[2] + 3.6];
+        const b = [origin[0] + stops[k + 1], origin[1], origin[2] + 3.6];
+        v.polyline({ name: `tube flow ${t + 1}.${k / 2 + 1}`, points: [a, b], color: "#0b5e8e", width: 0.5, bias: 1.2, into: shell, group: "bundle", flow: { dash: [9, 9], start: stops[k], offset: flow } });
+      }
+    }
+  });
+
+  // Nozzles with flanges: shell side on the shell, tube side on the channel.
+  const nozzle = (name, s, group) => {
+    const at = shift(group, [s, 0, Z]);
+    const body = v.lathe({ name, origin: at, axis: "z", profile: [[R - 6, 0], [R - 6, 13], [R + 26, 13], [R + 26, 0]], tone: "mid", group });
+    v.lathe({ name: `${name} flange`, origin: at, axis: "z", profile: [[R + 26, 0], [R + 26, 21], [R + 32, 21], [R + 32, 0]], tone: "mid", group });
+    v.boltCircle({ name: `${name} bolts`, frame: frameAlong([at[0], at[1], at[2] + R + 32], "z"), s: 0, radius: 17, count: 8, group });
+    return body;
+  };
+  const shellInlet = nozzle("shell inlet", 312, "shell");
+  const tubeInlet = nozzle("tube inlet", -40, "front");
+
+  if (callouts) {
+    v.callout({ part: shell, at: shell.anchor(0.93, -25), text: "Shell" });
+    v.callout({ part: baffles[2], at: baffles[2].anchor(0.5, -72), text: "Segmental baffle" });
+    v.callout({ part: tubeInlet, text: "Tube-side inlet" });
+    v.callout({ part: shellInlet, text: "Shell-side inlet" });
+    v.callout({ part: channelFlange, at: channelFlange.anchor(0.5, -40), text: "Channel flange" });
+    v.callout({ part: saddles[1], at: saddles[1].anchor(), text: "Saddle support" });
+    v.callout({ part: tubes[stops.length / 2 * 1 + 2], text: "Tube bundle" });
+  }
+
+  const fig = createFigure({ width, height, mode: "iso", title: "Shell-and-tube heat exchanger, window cutaway", desc: "Isometric cutaway of a shell-and-tube heat exchanger showing tubes, baffles, tubesheets, nozzles and saddles." });
+  fig.panel(null, [0, 0, width, height]).iso(v, { labelColumn: callouts ? 26 : null });
+  const svg = fig.render();
+  return { svg, view: v, warnings: fig.warnings() };
+}
+
+// One loop for the motion export: the bundle and heads come together, tube-side fluid runs,
+// then they come apart again, so the last frame leads straight back into the first.
+const smooth = (t) => t * t * (3 - 2 * t);
+export function frame(t) {
+  const together = t < 0.3 ? 1 - smooth(t / 0.3) : t < 0.7 ? 0 : smooth((t - 0.7) / 0.3);
+  const explode = Object.fromEntries(ORDER.map((g, i) => [g, Math.min(1, Math.max(0, together * 1.25 - i * 0.12))]));
+  return scene({ explode, flow: t * 4 * 18, callouts: false, reach: true }).svg;
+}

package/skills/lit-schematic/examples/journal-adsorption-rig/build.mjs

@@ -0,0 +1,87 @@
+// Worked example: a two-panel journal figure (double column, 178 mm) of a breakthrough
+// adsorption apparatus. (a) the flow schematic with stream colours and a key; (b) an
+// isometric window cutaway of the packed column.
+// node build.mjs [out-dir]  ->  journal-adsorption-rig.svg
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createFigure } from "../../scripts/lib/figure.mjs";
+import { createIsoView } from "../../scripts/lib/iso.mjs";
+import * as S from "../../scripts/lib/pid.mjs";
+
+const out = resolve(process.argv[2] ?? ".");
+const fig = createFigure({
+  width: "double",
+  height: 84,
+  title: "Breakthrough adsorption apparatus",
+  desc: "(a) Flow schematic: feed gases through mass flow controllers to a packed column in an oven, back-pressure regulator and mass spectrometer. (b) Cutaway of the packed column.",
+});
+
+// ---------------------------------------------------------------- (a) flow schematic
+const a = fig.panel("a", [0, 0, 106, 84]);
+const c = a.canvas({ box: [0, 7, 106, 74] });
+const co2 = c.add(S.gasCylinder({ x: 7, y: 50, w: 7, h: 22, name: "CO2/N2" }));
+const he = c.add(S.gasCylinder({ x: 18, y: 50, w: 7, h: 22, name: "He" }));
+const mfc1 = c.add(S.mfc({ x: 33, y: 15 }));
+const mfc2 = c.add(S.mfc({ x: 33, y: 29 }));
+const column = c.add(S.vessel({ x: 60, y: 40, w: 9, h: 34, packing: true, name: "Column" }));
+const ms = c.add(S.unit({ x: 96, y: 30, w: 14, h: 10, caption: "MS", ports: { in: ["left", 0.5], vent: ["top", 0.65] } }));
+const vent = c.add(S.vent({ x: 98.1, y: 17, text: "Vent" }));
+c.zone([43, 17, 76, 64], "Oven");
+
+c.stream({ from: co2.port("outlet"), to: mfc1.port("a"), role: "gas" });
+c.stream({ from: he.port("outlet"), to: mfc2.port("a"), role: "gas" });
+const feed = c.stream({ from: mfc1.port("b"), to: column.port("top"), role: "gas" });
+c.stream({ from: mfc2.port("b"), to: feed.tap([40, 15]), role: "gas" });
+const effluent = c.stream({ from: column.port("bottom"), to: ms.port("in"), role: "sample", via: [[60, 68], [80, 68], [80, 30]] });
+c.inline(effluent, (o) => S.regulator({ ...o, backPressure: true }), { at: [80, 42] });
+c.stream({ from: ms.port("vent"), to: vent.port("in"), role: "vent" });
+const pressureTap = effluent.tap([80, 54]);
+const pt = c.add(S.instrument({ x: 90, y: 54, tag: "PT-1" }));
+c.connect({ from: pressureTap.dir[0] < 0 ? pressureTap.flip() : pressureTap, to: pt.port("left") });
+
+fig.key(["gas", "sample", "vent"], [4, 81], { columns: 3, colWidth: 30 });
+
+// ---------------------------------------------------------------- (b) column cutaway
+const b = fig.panel("b", [110, 0, 68, 84]);
+const v = createIsoView({ azimuth: 40, elevation: 24 });
+const L = 160;
+const R = 14;
+v.halo({ plan: { x: -36, y: -36, w: 72, d: 72, r: 6 }, z: -30 });
+v.box({ name: "stand base", plan: { x: -36, y: -36, w: 72, d: 72, r: 4 }, z: -30, h: 6, tone: "cast", layer: -1 });
+v.lathe({ name: "stand post", origin: [-26, -26, -24], axis: "z", profile: [[0, 0], [0, 3], [L + 26, 3], [L + 26, 0]], tone: "stainless" });
+v.box({ name: "clamp", plan: { x: -28, y: -14, w: 8, d: 6, r: 1 }, z: L * 0.55, h: 10, tone: "cast" });
+const tube = v.lathe({ name: "column", origin: [0, 0, 0], axis: "z", profile: [[0, 0], [0, R], [L, R], [L, 0]], tone: "glass", cut: { from: 22, to: L - 22, span: 84 }, wall: 2.2 });
+const bed = v.lathe({ name: "adsorbent bed", origin: [0, 0, 0], axis: "z", profile: [[36, 0], [36, R - 2.4], [L - 36, R - 2.4], [L - 36, 0]], tone: "warm", into: tube });
+const woolLow = v.lathe({ name: "glass wool plug", origin: [0, 0, 0], axis: "z", profile: [[24, 0], [24, R - 2.4], [36, R - 2.4], [36, 0]], tone: "cool", into: tube });
+v.lathe({ name: "glass wool plug top", origin: [0, 0, 0], axis: "z", profile: [[L - 36, 0], [L - 36, R - 2.4], [L - 24, R - 2.4], [L - 24, 0]], tone: "cool", into: tube });
+// Pellet texture on the bed's lit face: rows that stop short of the limbs and the plugs.
+const pellets = [];
+for (let i = 0; i < 260; i++) {
+  const h = Math.sin(i * 12.9898) * 43758.5453;
+  const g = Math.sin(i * 78.233) * 12345.6789;
+  const s = 40 + (h - Math.floor(h)) * (L - 80);
+  const t = tube.facingAngle + ((g - Math.floor(g)) - 0.5) * 1.5;
+  pellets.push(bed.point(s, R - 2.4, t));
+}
+v.dots({ name: "pellets", points: pellets, r: 0.26, color: "#b08a6a", into: tube });
+for (const [z, name] of [[0, "bottom fitting"], [L, "top fitting"]]) {
+  v.lathe({ name, origin: [0, 0, z], axis: z ? "z" : "-z", profile: [[0, 0], [0, R + 3], [8, R + 3], [8, 0]], tone: "brass" });
+}
+const inlet = v.pipe({ name: "gas inlet", points: [[0, 0, -8], [0, 0, -18], [34, 0, -18]], r: 2.2, tone: "stainless" });
+const outlet = v.pipe({ name: "effluent line", points: [[0, 0, L + 8], [0, 0, L + 18], [34, 0, L + 18]], r: 2.2, tone: "stainless" });
+const wells = [0.3, 0.5, 0.7].map((f, i) => v.pipe({ name: `thermocouple ${i + 1}`, points: [[R + 0.2, 0, L * f], [R + 24, 0, L * f]], r: 1, tone: "stainless", caps: [false, true] }));
+
+v.callout({ part: tube, at: tube.anchor(0.92, -35), text: "Column, 26 mm ID" });
+v.callout({ part: bed, text: "Adsorbent bed" });
+v.callout({ part: woolLow, text: "Glass wool" });
+v.callout({ part: wells[1], at: wells[1].anchor(0.8), text: "Thermocouples" });
+v.callout({ part: inlet, at: inlet.anchor(0.85), text: "Feed in" });
+v.callout({ part: outlet, at: outlet.anchor(0.85), text: "To MS" });
+b.iso(v);
+
+mkdirSync(out, { recursive: true });
+const file = join(out, "journal-adsorption-rig.svg");
+writeFileSync(file, fig.render());
+for (const warning of fig.warnings()) console.warn(`WARN ${warning}`);
+console.log(file);

package/skills/lit-schematic/examples/pid-dosing-skid/build.mjs

@@ -0,0 +1,85 @@
+// Worked example: P&ID of a chemical dosing skid on an A3 sheet.
+// node build.mjs [out-dir]  ->  pid-dosing-skid.svg (then run scripts/qa.mjs and scripts/render.mjs)
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import * as S from "../../scripts/lib/pid.mjs";
+import { createSheet } from "../../scripts/lib/sheet.mjs";
+
+const out = resolve(process.argv[2] ?? ".");
+
+const sheet = createSheet({
+  size: "A3",
+  title: "Sodium hypochlorite dosing skid",
+  subtitle: "Piping and instrumentation diagram",
+  number: "EX-PID-001",
+  rev: "A",
+  date: "2026-10-25",
+  project: "Worked example",
+  owner: "lit-schematic",
+  drawn: "LS",
+  notes: [
+    "Line numbers read size - fluid code - sequence - piping class.",
+    "Pumps P-101A/B are duty and standby; one runs at a time.",
+    "PSV-101 relieves pump discharge back to TK-101 above the liquid level.",
+  ],
+});
+
+// Equipment: storage tank on the left, duty/standby metering pumps stacked to its right.
+const tank = sheet.add(S.tank({ x: 92, y: 150, w: 40, h: 50, tag: "TK-101", name: "Hypochlorite tank" }));
+const pumpA = sheet.add(S.pump({ x: 190, y: 125, type: "metering", tag: "P-101A", name: "Dosing pump" }));
+const pumpB = sheet.add(S.pump({ x: 190, y: 185, type: "metering", tag: "P-101B", name: "Dosing pump" }));
+sheet.equipmentInfo(tank, ["2.5 m3, HDPE", "Atmospheric"]);
+sheet.equipmentInfo(pumpA, ["0-40 L/h at 6 barg", "Duty"]);
+sheet.equipmentInfo(pumpB, ["0-40 L/h at 6 barg", "Standby"]);
+
+// Fill, vent and drain on the tank.
+const fill = sheet.add(S.offPage({ x: 30, y: 72, text: "FROM UNLOADING" }));
+const fillLine = sheet.pipe({ from: fill.port("out"), to: tank.port("top-left"), kind: "process-minor", number: '1"-NAOCL-101-P1' });
+sheet.inline(fillLine, S.valve, { type: "ball", at: 0.6 });
+const vent = sheet.add(S.vent({ x: 92, y: 100 }));
+sheet.pipe({ from: tank.port("top"), to: vent.port("in"), kind: "process-minor", arrows: false });
+const drain = sheet.add(S.drain({ x: 82, y: 222 }));
+const drainLine = sheet.pipe({ from: tank.port("bottom", 0.3), to: drain.port("in"), kind: "process-minor", arrows: false });
+sheet.inline(drainLine, S.valve, { type: "gate" });
+
+// Suction: one main from the tank up a vertical manifold to P-101A, a branch down to P-101B.
+const suction = sheet.pipe({ from: tank.port("right", 0.9), to: pumpA.port("suction"), via: [[150, 171], [150, 125]], number: '1"-NAOCL-102-P1' });
+sheet.inline(suction, S.valve, { type: "ball", at: 0.12 });
+sheet.inline(suction, S.filter, { at: 0.9 });
+const branchB = sheet.pipe({ from: suction.tap([138, 171]), to: pumpB.port("suction"), kind: "process-minor" });
+sheet.inline(branchB, S.filter, { at: 0.7 });
+
+// Discharge: check valve on each pump into a common header that rises to the injection point.
+const injection = sheet.add(S.offPage({ x: 300, y: 95, text: "TO INJECTION POINT" }));
+const header = sheet.pipe({ from: pumpB.port("discharge"), to: injection.port("in"), via: [[226, 180], [226, 95]], number: '1/2"-NAOCL-103-P2' });
+sheet.inline(header, S.valve, { type: "check", at: 0.06 });
+const flowEl = sheet.inline(header, S.orifice, { at: [286, 95], tag: "FE-101" });
+const dischargeA = sheet.pipe({ from: pumpA.port("discharge"), to: header.tap([226, 120]).flip(), kind: "process-minor" });
+sheet.inline(dischargeA, S.valve, { type: "check" });
+
+// Relief: PSV above the header, discharge back into the tank side above the liquid.
+const psv = sheet.add(S.safetyValve({ x: 246, y: 76, outlet: "left", tag: "PSV-101", setPressure: "SET 8 barg" }));
+sheet.pipe({ from: header.tap([246, 95]).flip(), to: psv.port("inlet"), kind: "process-minor", arrows: false });
+sheet.pipe({ from: psv.port("outlet"), to: tank.port("right", 0.1), kind: "process-minor" });
+
+// Instruments: tank level to the DCS, local discharge pressure, flow loop on the pump stroke.
+const levelNozzle = tank.port("left", 0.8);
+const lt = sheet.add(S.instrument({ x: 44, y: levelNozzle.y, tag: "LT-101" }));
+sheet.connect({ from: levelNozzle, to: lt.port("right") });
+const lia = sheet.add(S.instrument({ x: 44, y: 140, tag: "LIA-101", location: "dcs" }));
+sheet.signal({ from: lt.port("top"), to: lia.port("bottom") });
+const pi = sheet.add(S.instrument({ x: 266, y: 116, tag: "PI-102" }));
+sheet.connect({ from: header.tap([266, 95]), to: pi.port("top") });
+const ftX = flowEl.port("b").x + 4;
+const ft = sheet.add(S.instrument({ x: ftX, y: 116, tag: "FT-101" }));
+sheet.connect({ from: header.tap([ftX, 95]), to: ft.port("top") });
+const fic = sheet.add(S.instrument({ x: ftX, y: 150, tag: "FIC-101", location: "dcs" }));
+sheet.signal({ from: ft.port("bottom"), to: fic.port("top") });
+sheet.signal({ from: fic.port("bottom"), to: pumpB.port("signal") });
+
+mkdirSync(out, { recursive: true });
+const file = join(out, "pid-dosing-skid.svg");
+writeFileSync(file, sheet.render({ desc: "A3 P&ID of a hypochlorite dosing skid: tank, duty and standby metering pumps, relief and flow control." }));
+for (const warning of sheet.warnings) console.warn(`WARN ${warning}`);
+console.log(file);

package/skills/lit-schematic/references/cutaway-outputs.md

@@ -0,0 +1,70 @@
+# Cutaway outputs: static, interactive page, motion loop
+
+An isometric cutaway can leave the skill in three forms. The **static** figure (SVG with PDF and 600 dpi PNG) is the default and the only form a paper, a report or a P&ID set takes. An **interactive page** (one HTML file) lets a reader take the machine apart, switch views and find a part by its name. A **motion loop** (MP4 with an animated WebP and GIF) shows something happening: an assembly coming together, coolant running through a coil, an impeller turning. All three come from one scene function, so they always show the same machine.
+
+## Contents
+1. Choosing the output
+2. One scene, three outputs
+3. The interactive page
+4. Designing the explode
+5. The motion loop
+6. Checking each output
+7. When a film needs more than a loop
+
+## 1. Choosing the output
+
+| The request says | Output |
+| --- | --- |
+| nothing about the medium, or "figure", "그림", "논문", "보고서", "slide", "PNG", "PDF" | static (default) |
+| "HTML", "interactive", "web page", "웹", "인터랙티브", "explorable", "hover", "분해해서 볼 수 있게" | interactive page, plus the static figure |
+| "animation", "motion", "video", "MP4", "GIF", "loop", "애니메이션", "모션", "영상", "동영상", "움직이는" | motion loop, plus the static figure |
+| both kinds of words | both, plus the static figure |
+
+A bare request keeps the static default and asks nothing. Ask **one short question** only when the user is present (an interactive session, not a headless run) and the request names a use that a moving or explorable output would serve without naming the form, for example "for our lab website" or "for the open-day screen": "A static figure, an interactive web page, or a short looping video?" Take the answer and do not ask again. In a headless run, choose from the words alone and say in the reply which form you made and that the others are available.
+
+The static figure is always delivered with the others: it is the reference the page and the loop are checked against, and the form a journal or a print can use.
+
+## 2. One scene, three outputs
+
+Write the cutaway as `scene({ azimuth, elevation, explode, flow, callouts, reach })` returning `{ svg, view, warnings }`, following `examples/iso-heat-exchanger/scene.mjs`:
+
+- **Groups.** Give every part the assembly it belongs to with `group`: the shell and its flanges, the internals, the drive, the front and rear heads, the supports. A group is what a reader can hide or pull out; parts that bolt together and move together share one.
+- **Moves.** Keep the world move of each group that comes apart in one table (`MOVES`), the order they leave in (`ORDER`, outside parts first), and the layers a reader can hide (`LAYERS`). The scene shifts each group's origins by `MOVES[g] × explode[g]`, so a film frame is real geometry with a correct painter's order.
+- **Extents.** With `reach: true` the scene calls `view.extent(points)` with where the moved groups end up, so every frame of a film and every state of a page share one scale and nothing leaves the frame.
+- **Flow.** A `flow` phase in mm drives dashed stripes along pipes (`pipe({ flow })`) or along tube crowns (`polyline({ flow })`); give collinear pieces of one run the same offset and their own start.
+- **Callouts** stay on for the figure and the page and go off for the film, where moving leaders would distract.
+
+`build.mjs` writes the static figure from `scene()` and, with `--html`, the page from one `scene({ reach: true })` per preset view.
+
+## 3. The interactive page
+
+`renderInteractive` turns those views into one HTML file with no external file, font or script, so it opens offline, from a USB stick or from an email. It gives the reader:
+
+- **Preset views** as buttons (keys `1` to `n`): two or three useful camera positions, such as the default front-left, a higher view into the cut, and the opposite side. Draw each with its own callouts; anchors that use `side` offsets relative to the facing angle stay on visible faces when the camera turns.
+- **Exploded view** (button or `E`): each group slides by its screen vector, one after another in `ORDER`, and comes home in reverse; the leader dots ride with their parts. At zero the transform is removed, so the assembled page is exactly the static art.
+- **Layers** as checkboxes: hiding the shell leaves the internals drawn inside it.
+- **Callouts as controls**: each label is a focusable button; hover or focus lights its part's outline and its leader, `Enter` or `Space` toggles the selection, `Esc` clears it. Hovering a part lights its callout.
+- **Access**: visible focus rings, `aria-pressed` on toggles, an `aria-live` line that says what changed ("Exploded view", "Hiding Shell"), and `prefers-reduced-motion` honoured by moving parts straight to their end positions.
+- **State in the URL**: `#view=front-high&explode=1&hide=shell&select=C3` opens the page in that state, which is how screenshots for a report or a check are taken.
+
+## 4. Designing the explode
+
+Take the machine apart the way a fitter would. Outside parts leave first and come back last: a head comes off before the bundle slides out; a drive comes off before the cover lifts; a cover lifts before the internals rise. Move each group along a real path: along the axis it is bolted on, straight up for a lid, outward along a radius for side parts. Keep the moves short enough that the exploded machine still fits the page at a readable scale, usually less than the part's own length. Parts that join two assemblies belong to the one they stay with. A part nested inside another (a bundle inside its shell) can move on its own; the page and the film both treat it as its own group.
+
+On the page the explode is a 2D slide of the static art, so painter's order is that of the assembled view: check the exploded state for a part that should now be in front and is drawn behind. The film rebuilds every frame from the scene, so its order is always right.
+
+## 5. The motion loop
+
+`node "$SKILL_ROOT"/scripts/motion.mjs scene.mjs --out <dir> --name <name>` draws `frame(t)` for 4 s at 24 fps by default (`--seconds`, `--fps`, `--width 1280`, `--small 720`) and writes `name.mp4` (H.264, yuv420p, faststart, plays in slides and browsers), `name.webp` and `name.gif` (720 px wide, for a README or a chat). Design the loop so its last frame leads into its first: start in the state you end in (both exploded, or both assembled), ease every move (smoothstep), and make a flow phase advance a whole number of dash periods over the loop. Keep it calm: one thing happening at a time, nothing faster than a reader can follow, no flashes. A 4–8 s loop of about 100–200 frames renders in one to three minutes; run it under `nice`.
+
+The encoder needs ffmpeg (and img2webp for WebP). Nothing is installed: a missing tool stops the run with `ENCODER_REQUIRED` and the install line for the user; report the loop as `BLOCKED` for that format and deliver the others.
+
+## 6. Checking each output
+
+- **Static**: as for every drawing: `qa.mjs`, render, look (`references/verification.md`).
+- **Page**: open it in a real browser (headless Chrome with the mock keychain flags, or a browser-automation session) and exercise it: focus the first callout and Tab to the next (the part outline lights), toggle the explode (groups move, then return to exactly the static art), hide a layer (nested groups stay), switch each view, and open it once with reduced motion forced (moves are immediate). Screenshot the states through the URL hash and read them. Confirm the page has no `http` reference other than the SVG namespace and no console errors.
+- **Loop**: tile a dozen frames from the MP4 (`ffmpeg … -vf "select='not(mod(n\,12))',scale=640:-1,tile=4x3"`) and read the sheet: the start and end states match, parts move along their paths without passing through each other, nothing leaves the frame, flow stripes stay on their pipes. Check the MP4 stream is H.264 yuv420p at the frame count you asked for.
+
+## 7. When a film needs more than a loop
+
+A silent loop of the machine is this skill's job. A film with a treatment, titles, narration beats or a sound bed (an explainer for a launch, a conference opener) belongs to `lit-typographic-motion`: hand it the interactive page or the scene as the stage it captures, and let it own the treatment, timing, sound and its own QA. Keep the machine's geometry here; never redraw the equipment in the film skill.

package/skills/lit-schematic/references/isometric-craft.md

@@ -0,0 +1,101 @@
+# Isometric and cutaway craft
+
+An isometric illustration explains equipment by showing it as the real, well-made object: a reader recognises a shell-and-tube exchanger, a stirred autoclave or a packed column at a glance and then finds the part the text is about. The rules below are what separates such a figure from a 3D-looking diagram; each one comes from a fault that makes a figure read as fake.
+
+## Contents
+1. What a good figure has
+2. Size it, then write the parts list
+3. Camera and composition
+4. Solids, tones and light
+5. Painter's order
+6. Window cutaways
+7. Turned parts, flanges, nozzles and pipes
+8. Detail that belongs to parts
+9. Callouts
+10. Groups for pages and films
+11. Anti-patterns
+
+## 1. What a good figure has
+
+1. **A real object.** Model the actual equipment from its real proportions (shell diameter to length, nozzle sizes, flange thickness). Take mood and finish from references; never trace one.
+2. **Many small, precise parts.** A single-machine figure has 40–80 parts; a dense one 80–150. Density comes from structure (saddles, flanges, bolts, nozzles, brackets, baffles), never from texture.
+3. **Volume.** Every part has thickness, shaded faces and a lighter top; a soft halo sits under the base.
+4. **Material colour.** Thin outlines (0.2 mm) over the full-colour material palette, the default of `createIsoView`: every part wears the finish it really has (painted steel, stainless, copper tubes, brass fittings, cast iron, concrete, glass, insulation cladding), so the reader tells parts apart by what they are made of. Signal red (`tone: "accent"`) marks the one part the text is about when its own material would not stand out. The grey palette (`createIsoView({ palette: "grey" })`) is opt-in, for a request that asks for a quiet, monochrome or print-grey figure.
+5. **Truth.** Dimensions and counts that the caption states are the ones drawn (12 tubes, 4 baffles, 26 mm ID).
+
+## 2. Size it, then write the parts list
+
+Name the size before drawing: **Figure** (one machine, 40–80 parts) or **Hero** (a machine with its piping and skid, 80–150). A whole plant in 3D is a package: propose one unit.
+
+Write the parts list in the build script header before any geometry, grouped:
+
+- **Ground**: pad or skid (`box`, `layer: -1`), halo, feet.
+- **Structure**: saddles, legs, skirt, frame, brackets, stand and clamp.
+- **Body**: shell, heads, channel, bonnet, flanges.
+- **Internals** (inside a cutaway): tubes, baffles, tubesheets, impeller and shaft, coil, packing, liquid, frits, wool plugs.
+- **Connections**: nozzles with flanges and bolt circles, pipes with bends, valves, fittings.
+- **Instruments**: gauges, thermowells, transmitters, cable glands.
+
+Every part sits on another part: a nozzle on the shell, a flange on the nozzle, bolts on the flange, the shell on saddles, saddles on the pad.
+
+## 3. Camera and composition
+
+- `createIsoView({ azimuth, elevation })`: azimuth 45° shows two faces equally; turn it (30–65°) so the face that carries the mechanism, or the long side of a horizontal vessel, faces the viewer (the exchanger example uses 62°). Elevation 25–30° for most equipment; 35–45° to look into an open vessel or down onto a skid.
+- World units are the object's millimetres: x and y on the floor, z up. Build everything at its real position and let `fit` scale it into the panel.
+- The art fills most of its panel; callouts take side columns only as wide as their longest label, and `fit` chooses the sides that leave the art largest.
+- A set of figures keeps one azimuth, elevation and scale so parts compare.
+
+## 4. Solids, tones and light
+
+- **Solids, never wireframes.** Every part is filled, so what is in front hides what is behind. No dashed hidden edges, no see-through boxes.
+- **One fixed light** from the upper left in front; faces turned toward it are lighter. Flat parts (`box`, `prism`) shade each side face by its facing and lighten the top; turned parts (`lathe`) shade continuously around their axis, so a cylinder or head never steps in tone.
+- **Tones are materials.** Name each part's finish: `steel` (painted carbon steel), `stainless`, `frame` (painted structural steel), `copper`, `brass`, `cast` (cast iron, motors, dark machinery), `concrete`, `insulation` (aluminium cladding), `rubber` (gaskets, hoses), `glass`. The generic roles still work and follow the palette: ground `lo` (concrete), structure and heads `mid` (painted steel), the body `hi` (stainless), the subject `accent`, the inside of a cut vessel `cavity`, cut wall faces `section`, a liquid `liquid`, a granular solid `warm`, a soft plug `cool`. A figure usually shows four to six materials; a single grey body with one accent is the opt-in quiet look, not the default.
+- **Halo.** `halo({ plan, z })` under the base grounds the object.
+
+## 5. Painter's order
+
+Items are painted far to near by the depth of their centre, after their layer: halo (−2), ground (−1), everything else (0). Two rules fix almost every ordering fault:
+
+1. **Ground first.** A large pad has its centre far behind the parts that stand on its front; give it `layer: -1`.
+2. **Split anything that wraps or interleaves.** Tubes that pass through baffles are split at every baffle into segments, each its own item; a pipe is drawn as chunks that sort separately; a long body cut by a ring is two bodies and the ring. An item that is both in front of and behind another cannot be ordered by any key.
+
+When something behind shows through something in front, the item in front is painted too early: lower the far item's `bias`, raise the near one's, or split one of them.
+
+## 6. Window cutaways
+
+`lathe({ cut: { from, to, span }, wall })` removes a window from the side facing the viewer between `s = from` and `s = to`, `span` degrees wide. Through it the reader sees the inner wall (`cavity` tones), the internals passed with `into: shell`, and the cut wall faces (`section` tone) along both edges and on the window sill. Everything outside the window stays closed and hides what is behind it.
+
+- Keep the rims closed: start the window a little after a flange or head and end it before the next.
+- **Never put a nozzle, bracket or gauge on shell the window removes.** With a wide span the window reaches the top and bottom of the shell; move the nozzle along the axis past the window, or narrow the span (80–100°).
+- Internals sit fully inside the inner radius (`R - wall`), so nothing pokes through the wall.
+- A liquid is a lathe of `liquid` tone up to its level, inside the vessel; an interface is a seam ring.
+
+## 7. Turned parts, flanges, nozzles and pipes
+
+- **Think in half-sections.** A turned part is its profile `[[s, r], …]` along an axis: a flat cap is a jump in `r` at one `s`; a head is `ellipsoidalHead(R)` with smooth knots. One lathe is one convex body; a flange is its own lathe (a disc), a nozzle its own lathe, so each sorts by its own depth.
+- **Flanges sit flush.** A flange's back face lands on the end of its nozzle or pipe; two flanges meet face to face at a joint; add a `boltCircle` on the face that points at the viewer.
+- **Nozzles leave along the surface normal**: radially from a shell (`axis: "z"` for a top nozzle), axially from a head.
+- **Pipes bend; they do not kink.** `pipe({ points, r })` fillets every corner with a bend of about 2.6 r. Start on the port's normal, follow the structure (parallel to the body, along racks), cross other pipes only on straights and clearly apart in depth, and end on a flange or fitting.
+- **Few pipe sizes**, all distinguishable: main lines, feed lines, tubing for instruments.
+
+## 8. Detail that belongs to parts
+
+At 1× the figure reads as one machine; at 4× every region still has something true on it. Before finishing, render the close-up sweep (`render.mjs --sheet`) and look for bare faces, then add the real part that belongs there: bolts on every flange, a nameplate with rule lines, seams where a head meets the shell (`seams`), a drain plug, earthing lug, feet under a skid, a thermowell with its head. Never add decoration that belongs to no part. A texture (pellets, a weave) stops at a real edge or thins toward a limb; it never stops on a straight cut in mid-face.
+
+## 9. Callouts
+
+Words stay out of the art. `callout({ part, text })` puts each label in a column beside the art with a hairline leader that ends on a dot on the named part; labels are ordered so no two leaders cross or run within 1.4 mm of each other, and QA fails a leader whose dot is off its named part (`LEADER.LOOSE`), that crosses another (`LEADER.CROSSING`) or that crowds another or its dot (`LEADER.SPACING`). Two dots a few millimetres apart on the page (a baffle and the tube in front of it) crowd whatever the order: spread them before you build, on faces far enough apart. Choose the anchor on a face the viewer can see (`handle.anchor(f, sideDegrees)`): QA reads outlines, not visibility, so a dot on a hidden face passes the gate and fails the eye. One label per part, a noun phrase, sentence case, no full stop; numbers with units (`Column, 26 mm ID`). For a journal figure the caption names the parts in the same words.
+
+## 10. Groups for pages and films
+
+Give every part its assembly with `group` (shell, internals, drive, heads, supports) even for a static figure: it costs nothing, it is written as `data-group`, and it is what an interactive page hides and explodes and a motion loop moves. Write the cutaway as a scene function of the camera, the explode amount and a flow phase when the user may want a page or a film; `references/cutaway-outputs.md` has the pattern.
+
+## 11. Anti-patterns
+
+- Abstract stacks: floating slabs or boxes standing for units read as nothing; draw the real equipment.
+- One big plain body: a shell with nothing on it is unfinished; add flanges, nozzles, supports, seams.
+- Labels or leader balloons over the object.
+- Colour that names no material: a hue on a part must be its real finish, a fluid, or the one accent; never paint parts in rainbow categories.
+- A part sunk into another, or floating off it: every contact is flush or seated.
+- A curved surface in visible tone steps: use `lathe`, never stacked boxes.
+- A cutaway that shows internals the real equipment does not have, or hides the one the text is about.

package/skills/lit-schematic/references/journal-figures.md

@@ -0,0 +1,72 @@
+# Journal figures of apparatus and equipment
+
+An apparatus figure in a paper answers one question: what did the experiment use, and how was it connected? A reviewer reads it beside the methods section, often printed in grey, sometimes reduced. Everything here is about surviving that reading.
+
+## Contents
+1. Size
+2. Type
+3. Lines and colour
+4. Panels
+5. What goes in the art and what goes in the caption
+6. Korean labels
+7. Export
+8. Publisher notes
+
+## 1. Size
+
+Draw at final size; never scale a figure afterwards, because type and lines scale with it.
+
+| Width | mm | Kit |
+| --- | --- | --- |
+| Single column | 85 (Elsevier 90, ACS 82.5, Nature 89) | `createFigure({ width: "single" })` |
+| One and a half | 120–140 | `"onehalf"` |
+| Double column | 178 (Elsevier 190, ACS 178, Nature 183) | `"double"` |
+
+Use the target journal's own numbers when the user names it (`createFigure({ width: 183 })`). Height is what the content needs, at most 230 mm; an apparatus figure is usually 60–100 mm tall. Check the current author guidelines when submission accuracy matters; numbers here can go stale.
+
+## 2. Type
+
+- **7 pt** for labels (`JOURNAL.textPt`), **8 pt bold** for panel labels, never under **6 pt** at print size; the QA gate fails anything smaller (`TEXT.MIN_SIZE`).
+- One sans family: **Arial** (Helvetica-compatible) for Latin text; it is what most publishers ask for and Chrome embeds it in a PDF as real TrueType text.
+- Sentence case, no full stops on labels; units with a space (`5 MPa`, `2 °C`); chemical formulas with true subscripts when the font allows, otherwise plain (`CO2`) consistently.
+- No title inside the art: the caption is the title.
+
+## 3. Lines and colour
+
+- Lines 0.5–1 pt (0.18–0.35 mm); nothing under 0.25 pt (`STROKE.MIN`). Stream lines 1 pt, symbol outlines 1–1.4 pt.
+- **Colour-vision-safe stream roles** (Okabe–Ito): gas blue `#0072B2`, liquid sky `#56B4E9`, coolant green `#009E73`, heating vermillion `#D55E00`, sample purple `#CC79A7`, vacuum orange `#E69F00` dashed, vent grey dashed, signal grey dashed. `PALETTE.CVD` fails two role colours that become hard to tell apart under normal, deuteranopic, protanopic or tritanopic vision.
+- **Colour is never the only carrier.** Vent, vacuum and signal lines also differ by dash; every role used is in the key (`fig.key`), and the caption can name the streams.
+- Figures print in grey: check the PNG in greyscale when streams differ only by hue.
+
+## 4. Panels
+
+- Label panels **(a), (b), …** at their top left, bold 8 pt, in reading order left to right, top to bottom (`PANEL.LABELS` checks order, size and position).
+- Each panel makes one point: (a) the flow scheme, (b) the cell or column in detail, (c) a photograph or a measured result (that panel belongs to `lit-scientific-visualization`; leave it a box and say so).
+- Align panel edges; give the 3D panel enough width for its callouts, or put its callouts on one side.
+- A shared key goes once, under the panels.
+
+## 5. What goes in the art and what goes in the caption
+
+| In the art | In the caption |
+| --- | --- |
+| Equipment names (`Column`, `MS`, `MFC`), short and consistent with the methods | What the apparatus does and the experimental sequence |
+| Stream key | Model numbers, suppliers, dimensions not visible in the art |
+| Panel labels | The meaning of each panel |
+| One number when it is the point (`26 mm ID`) | Operating ranges, uncertainties |
+
+Tags such as `PT-1` belong in a methods-style figure only when the text refers to them; otherwise use names (`Pressure transducer`). Journal canvases label equipment with `name` and fall back to the tag.
+
+## 6. Korean labels
+
+Hangul labels use **Pretendard** for the whole label (`fontFor` switches automatically when a label contains Hangul). Keep units and formulas in Latin (`압력 5 MPa`, `CO2 공급`). Korean labels run wider: allow about 1 em per syllable. The renderer loads Pretendard from the sibling `lit-diagram-drawer` skill; in the SVG the family name stays `Pretendard` with system fallbacks. For an English paper with Korean annotations remove the Korean before submission.
+
+## 7. Export
+
+- **SVG**: the editable master, vector, millimetre-sized.
+- **PDF**: `render.mjs --pdf`; vector, page size equals the figure size (`PDF.SIZE`). Latin text in Arial is embedded as TrueType text. Chrome embeds Pretendard (a CFF variable font) as **Type 3** glyphs; some checkers (for example IEEE PDF eXpress) reject Type 3, so for those journals keep labels in Latin or submit the PNG/TIFF.
+- **PNG**: `render.mjs --png --dpi 600` (line art: 600–1200 dpi; 1000+ when the journal asks for line-art TIFF). The file records its resolution in a pHYs chunk; `qa.mjs --png` checks the resolution and that the pixel width matches the drawing width.
+- Name files by figure number (`fig2-apparatus.pdf`).
+
+## 8. Publisher notes
+
+Commonly published values, to confirm against the current guide: Elsevier lists Arial, Courier, Times and Symbol, column widths of 90/140/190 mm and 1000 dpi for line-art TIFF; ACS uses 3.25 in and 7 in columns, Helvetica or Arial, and 1200 dpi line art; Nature uses 89/183 mm and Helvetica or Arial at 5–7 pt; RSC uses 8.3/17.1 cm columns. Korean journals (대한화학회, 한국화학공학회): follow the template; Hangul in a sans such as Pretendard or 맑은 고딕. Always confirm the current guide for the target journal.