@litfamily/lithermes 1.0.28 → 1.0.30

package/assets/lithermes-plugin/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/assets/lithermes-plugin/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/assets/lithermes-plugin/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/assets/lithermes-plugin/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 this plugin; 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.

package/assets/lithermes-plugin/skills/lit-schematic/references/kit-api.md

@@ -0,0 +1,134 @@
+# Kit API
+
+Every kit drawing is authored in **millimetres at final print size**: the SVG root carries `width="…mm"`, `height="…mm"` and a viewBox in the same numbers, so a stroke of `0.35` is 0.35 mm on paper and a font size of `2.47` is 7 pt. Import modules from `$SKILL_ROOT/scripts/lib/` (the scaffold writes absolute `file://` imports for you).
+
+## Contents
+1. Sheets and canvases (`sheet.mjs`)
+2. Symbols (`pid.mjs`)
+3. Routing (`route.mjs`)
+4. Journal figures (`figure.mjs`)
+5. Isometric views (`iso.mjs`)
+6. Tags (`isa.mjs`), theme (`theme.mjs`), helpers
+7. QA and render from code
+8. Legend sheet (`legend-sheet.mjs`)
+9. Interactive page (`interactive.mjs`) and motion loop (`scripts/motion.mjs`)
+
+## 1. Sheets and canvases (`sheet.mjs`)
+
+### `createSheet(options)` → sheet
+An ISO sheet with a zone frame, an equipment header band, a legend column, a notes block and a title block. Options: `mode` (`"pid"` | `"pfd"`), `size` (`"A4"`, `"A3"` default, `"A2"`, `"A1"`, or `[w, h]` mm), `title` (required), `subtitle`, `number`, `rev`, `date`, `scale` (`"NTS"` default), `sheet` (`"1 OF 1"`), `project`, `owner`, `drawn`, `checked`, `approved`, `notes` (array of strings, numbered), `lang`, `legendTitle`, `legendColumn` (default `true`), `headerBand` (default `true`). When the legend column would overflow, the instrument identification letters move to the right half of the notes block; if it still overflows, `sheet.warnings` says so.
+
+The drawing area on A3 is about `[24, 39, 342, 246]`; read `sheet.drawing` for the exact box. Place every symbol inside it. A sheet has every canvas method below plus:
+
+| Method | Does |
+| --- | --- |
+| `sheet.equipmentInfo(sym, lines)` | Adds the symbol's tag, name and spec lines to the header band above it (columns de-overlap themselves). |
+| `sheet.render({ desc })` | The finished SVG string (`data-schematic-mode` is the sheet's mode). |
+| `sheet.warnings` | Placement problems the build could not solve (a label with no clear place, a symbol outside the canvas, a legend that overflows). Print them; QA will fail on the same defects. |
+
+### `createCanvas({ box, style, grid, clearance, stub, labelSize })` → canvas
+A routed drawing area in a sheet or a journal panel. `style` is `"pid"` (black ink, ISA line weights) or `"journal"` (stream colours, names instead of tags, 7 pt labels, a 1 mm routing grid).
+
+| Method | Does |
+| --- | --- |
+| `add(sym)` | Places a symbol; warns when it overlaps another or leaves the canvas. Returns the symbol. |
+| `pipe({ from, to, via, points, kind, number, arrows })` | A process line. `kind`: `process-major` (default, 0.7 mm), `process-minor` (0.5), `utility` (0.35); every class has its own weight. `from`/`to` are ports or taps. With no `points` it is routed; `via` adds waypoints; `points` gives every corner yourself (checked orthogonal, first and last legs on the port normals). `number` places the line number on the longest clear straight. `arrows`: `"auto"`, `false`, or fractions `[0.3, 0.8]`. |
+| `signal({ from, to, type })` | An instrument signal (ISA-5.1 Table 5.3.2): `type` `electric` (dashed, default), `pneumatic` (double slashes), `hydraulic` (L marks), `capillary` (crosses), `guided` (sine wave), `unguided` (broken sine wave), `data` (open circles; `software` is the same), `mechanical` (filled dots). Run a controller output to `valve.port("actuator")`. |
+| `connect({ from, to })` | Instrument supply or process connection (0.18 mm thin solid impulse line). |
+| `stream({ from, to, role, via })` | Journal stream line in the colour of `role` (`gas`, `liquid`, `coolant`, `heating`, `vent`, `signal`, `sample`, `vacuum`). |
+| `inline(line, factory, options)` | Puts a valve, element or filter on the line at `options.at` (fraction, or a point near the line) and gaps the line under it. It snaps to the nearest straight run long enough; it throws when none is. Returns the symbol. |
+| `line.tap(at)` | A branch point on a line (fraction, arc length, or a point within 1 mm of the line, and at least 3 mm from a bend). The port normal points to the line's left; `.flip()` gives the other side. A junction dot is drawn. |
+| `line.at(fraction)` | `{ point, direction }` along the routed line. |
+| `zone(box, name)` | A dashed enclosure (oven, cold box, skid boundary) with its name inside the top-left corner; lines may cross it, labels avoid it. |
+| `streamNumber(line, n, { at })` | PFD stream number diamond on a straight run. |
+| `streamTable({ box: [x0, y0, x1], streams, rows: [{ label, values }] })` | A stream table; returns its bottom y. |
+| `text(x, y, text, { size, anchor, bold, color, kind })` | A fixed label that routes and later labels avoid. |
+| `render()` | The canvas group. |
+
+## 2. Symbols (`pid.mjs`)
+
+Every factory takes `x, y` (the centre unless noted) in sheet mm and returns a symbol with `kind`, `tag`, `box`, `boxes`, `port(name[, t])`. Equipment tags must parse as `R-101`, `P-101A`, `TK-101`, …; instrument tags as ISA-5.1 (`PIC-101`). A bad tag throws.
+
+| Factory | Kind(s) | Ports |
+| --- | --- | --- |
+| `vessel({ w, h, top, bottom, jacket, agitator, coil, packing, trays, demister, supports, liquid, tag, name })` | `vessel.vertical`, `.reactor`, `.jacketed`, `.column` | `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `jacket-in`, `jacket-out`, and `port("left" \| "right", t)` along the straight shell (t 0 top tangent → 1 bottom tangent), `port("top" \| "bottom", t)` across a head |
+| `reactor(o)`, `column(o)`, `tank(o)` | jacketed stirred reactor; column with trays; cone-roof tank | as `vessel` |
+| `drum({ w, h, saddles })` | `vessel.horizontal` | `left`, `right`, `port("top" \| "bottom", t)` |
+| `gasCylinder({ w, h })` | `gas.cylinder` | `outlet` (up) |
+| `pump({ r, type, facing })` | `pump.centrifugal`, `.positive`, `.metering` | `suction`, `discharge`, `signal` (stroke or speed input, bottom) |
+| `compressor({ r, type, facing })` | `compressor.centrifugal`, `.reciprocating` (also a gas booster) | `inlet`, `outlet`, `drive` |
+| `motor({ r })` | `drive.motor` | `shaft`, `left`, `right`, `bottom` |
+| `exchanger({ r })` | `exchanger.general` | `tube-in`, `tube-out`, `shell-in`, `shell-out` |
+| `shellTube({ w, h, type })` | `exchanger.shelltube` (`type: "fixed"`, default), `exchanger.floating`, `exchanger.utube` | `tube-in`, `tube-out`, `shell-in`, `shell-out` |
+| `plateExchanger({ w, h })` | `exchanger.plate` (ISO 10628-2 item 3.6) | `hot-in`, `hot-out`, `cold-in`, `cold-out` |
+| `airCooler({ w, h })` | `exchanger.aircooler` | `in`, `out` |
+| `unit({ w, h, caption, glyph, ports })` | `package.unit` (chiller, circulator, analyser, DAQ, booster skid) | as declared: `ports: { supply: ["right", 0.3] }`; also `port(side, t)` |
+| `valve({ type, orient, actuator, fail, tag })` | `valve.gate`, `.globe`, `.ball`, `.butterfly`, `.check`, `.needle`, `.plug`, `.diaphragm`, `.threeway`; with `actuator` (`diaphragm`, `piston`, `motor`, `solenoid`, `hand`) the kind is `valve.<type>.<actuator>`; `fail` is `FO`, `FC`, `FL` or `FI` | `a`, `b` (and `c` on a three-way), `actuator` when actuated |
+| `angleValve({ inlet, outlet, actuator, fail, tag })` | `valve.angle`, `valve.angle.<actuator>` | `inlet`, `outlet` on two perpendicular sides, `actuator` |
+| `regulator({ backPressure })` | `valve.regulator`, `valve.backpressure` | `a`, `b` |
+| `safetyValve({ outlet, setPressure, tag })` | `valve.safety` | `inlet` (from below), `outlet` (side) |
+| `ruptureDisk`, `orifice`, `rotameter`, `mfc`, `filter`, `reducer({ eccentric, flat })`, `flange`, `sightGlass`, `blind({ state })` | `relief.rupture`, `flow.orifice`, `flow.rotameter`, `flow.mfc` (+ `signal`), `line.filter`, `line.reducer`, `line.reducer-eccentric`, `line.flange`, `line.sightglass`, `line.blind`, `line.blind-open` | `a`, `b` |
+| `flowElement({ type })` | `flow.orifice`, `flow.venturi`, `flow.magnetic`, `.coriolis`, `.vortex`, `.turbine`, `.ultrasonic`, `.thermal` | `a`, `b` |
+| `instrument({ tag, fn, location, r })` | `instrument.<fn>-<location>`: `fn` `discrete` (default), `shared`, `computer`, `plc`; `location` `field` (default), `main`, `main-rear`, `aux`, `aux-rear` (round-1 names `dcs`, `plc`, `panel`, `panel-rear`, `local-panel` still work) | `top`, `bottom`, `left`, `right` |
+| `interlock({ text })` | `logic.interlock` | `top`, `bottom`, `left`, `right` |
+| `vent({ text })`, `drain({ text })`, `samplePoint({ text, facing })` | `terminal.vent`, `terminal.drain`, `terminal.sample` | `in` |
+| `offPage({ text, pointing })`, `utility({ text, pointing })` | `terminal.offpage`, `terminal.utility` | `in`, `out` |
+
+Inline factories take `orient` (`right`, `left`, `up`, `down`); `sheet.inline` sets it from the line. A symbol on a line running left is mirrored, not turned over, so an actuator still stands above the line; letters on an inline symbol (fail positions) always read upright, and on a vertical line they sit beside the body opposite the actuator. A later process line that crosses an earlier one hops it; the gate accepts the hop. `describeKind(kind, { short })` gives the legend text for every kind, including composed ones; `KIND_DESCRIPTIONS`, `ACTUATORS`, `FUNCTIONS`, `LOCATIONS` and `FAIL_POSITIONS` hold the parts.
+
+## 3. Routing (`route.mjs`)
+
+`routeOrthogonal({ from, to, obstacles, lines, bounds, grid, clearance, stub, bendCost, crossCost, nearCost, exempt })` returns corner points. It leaves each port along its normal far enough to clear every symbol's clearance zone, never enters an inflated symbol box, never runs along or turns on an existing line, crosses existing lines only at right angles (with a cost), and minimises length plus bends. Two ports that face each other on one axis join straight. It throws when no route exists. `orthogonal(points, { from, to })` validates a hand-given polyline.
+
+## 4. Journal figures (`figure.mjs`)
+
+`createFigure({ width, height, title, desc, lang, mode, labelStyle, textPt })`: `width` is `"single"` (85 mm), `"onehalf"` (120), `"double"` (178) or a number; `height` ≤ 230 mm; `labelStyle` `"paren"` → (a), `"bold"` → a, `"upper"` → A.
+
+| Method | Does |
+| --- | --- |
+| `fig.panel(label, [x, y, w, h])` | A panel with its label at the top left (`label` `null` for a single-panel figure without a label). |
+| `panel.canvas({ box })` | A journal-style canvas inside the panel (default box: below the label). |
+| `panel.iso(view, { box, labelColumn, calloutSize })` | Fits an isometric view and its callouts into the panel. |
+| `panel.text(x, y, text, options)`, `panel.raw(svg)` | Extra content. |
+| `fig.key(roles, [x, y], { columns, colWidth })` | Stream-colour key; QA requires every role drawn to be in it. |
+| `fig.render()` | The SVG (`data-min-text-pt="6"`). |
+
+## 5. Isometric views (`iso.mjs`)
+
+`createIsoView({ azimuth = 45, elevation = 30, light })`. World units are the object's own millimetres, x and y on the floor, z up. Nothing is projected until `fit`.
+
+| Function | Does |
+| --- | --- |
+| `lathe({ name, origin, axis, profile, tone, steps, seams, cut, wall, layer, bias, into })` | A turned part: `profile` is `[[s, r], …]` along `axis` (`"x"`, `"y"`, `"z"`, `"-z"` or a vector) from `origin`; add a third element `1` to mark a smooth knot (no crease ring). One lathe is one convex body: build steps, flanges and nozzles as separate lathes. `seams: [s…]` draws weld rings. `cut: { from, to, span, turn }` opens a window from `s = from` to `to`, `span` degrees wide, centred on the side facing the viewer (`turn` rotates it); `wall` is the cut wall thickness. Returns a handle with `point(s, r, angle)`, `surface(s, sideDeg)`, `anchor(f, sideDeg)`, `facingAngle`, `frame`. |
+| `box({ name, plan: { x, y, w, d, r }, z, h, tone, layer })`, `prism({ ring, z, h, … })` | Flat parts: pads, skids, saddles, brackets, plates. `anchor()` is the top centre. |
+| `pipe({ name, points, r, tone, bend, caps, flow })` | A filleted route drawn as depth-sorted chunks with shine and shade bands; `anchor(f)` a point along it. `flow: { color, dash: [on, off], offset, width }` adds a dashed stripe whose dashes march with `offset` (screen mm), continuous across chunks. |
+| `sphere({ name, center, r })`, `dots({ points, r, color })`, `polyline({ points, color, width, dash, flow })`, `boltCircle({ frame, s, radius, count })` | Balls, textures, hairlines, bolt heads. `polyline` `flow: { dash, offset, start }` in world mm marches dashes along collinear pieces of one run. |
+| `extent(points)` | World points the fit keeps in frame although nothing is drawn there: where exploded or moving parts go, so every frame and every page state shares one scale. |
+| `halo({ plan, z })` | Soft ground shadow (layer −2). |
+| `callout({ part, at, text, side, number })` | A label in a column beside the art with a leader to a dot on `part` (its `anchor()`, or `at`). Sides are chosen to leave the art largest; leaders are reordered so none cross. |
+| `fit(box, { pad, labelColumn, size })`, `render()`, `renderCallouts({ box, size })` | Used by `panel.iso`. Callout leaders are ordered so none cross and none run within 1.4 mm of another; what cannot be cleared lands in `view.warnings` (and in `fig.warnings()`). |
+| `screenVector([dx, dy, dz])` | The screen offset in mm of a world move at the fitted scale: the explode vector an interactive page needs. |
+
+Every factory also takes `group`: the assembly the part belongs to (`"shell"`, `"internals"`, `"drive"`). It is written as `data-group` around the part; interactive pages toggle and explode by it.
+
+`createIsoView({ azimuth, elevation, light, palette })`: `palette` is `"material"` (default, full colour) or `"grey"` (opt-in quiet look); any other name throws. Material tones: `steel`, `stainless`, `frame`, `copper`, `brass`, `cast`, `concrete`, `insulation`, `rubber`, `glass` (the same in both palettes). Role tones, painted by the palette: `lo`, `mid`, `hi`, `accent` (the one part to watch), `cavity`, `section`, `liquid`, `warm`, `cool`. Layers: `-2` halo, `-1` ground, `0` everything else; `into: handle` draws a part inside a cut lathe, between its inner wall and its outer shell. Helpers: `ellipsoidalHead(R)`, `vesselProfile(R, straight, { top, bottom })`, `frameAlong(origin, axis)`, `fillet(points, radius)`.
+
+## 6. Tags, theme, helpers
+
+- `parseInstrumentTag(tag)` → `{ ok, letters, loop, first, modifier, functions, meaning }` or `{ ok: false, error }`; `parseEquipmentTag(tag)`; `parseLineNumber(text)` → `{ ok, size, fluid, sequence, spec, insulation }`.
+- `theme.mjs`: `PID` (weights and text sizes), `JOURNAL` (widths, 7 pt text, 6 pt floor, 0.75 pt lines), `OKABE_ITO`, `STREAM` roles, `ISO` tokens, `fontFor(text)` (Arial for Latin, Pretendard for Hangul).
+- `svg.mjs`: `svgDocument`, `el`, `pathOf`, `textBox`, `ptToMm`, `mmToPt`.
+
+## 7. QA and render from code
+
+`check(svgText, { mode, minTextPt, minStrokeMm })` from `qa-core.mjs` returns `{ verdict, fails, warnings, findings, stats }`. `renderPng`, `renderPdf`, `renderSheet`, `findChrome` from `scripts/render.mjs`; `checkExports` from `scripts/qa.mjs`.
+
+## 8. Legend sheet (`legend-sheet.mjs`)
+
+`createLegendSheet({ size = "A2", title, number, rev, date, scale, project, owner, drawn, checked, approved, sheet })` returns the SVG of the "P&ID symbols and abbreviations" sheet: every line class, the equipment, valves, actuators, self-acting and relief devices, piping items, flow elements, connections, the ISA-5.1 shape-and-location matrix, the identification letters by position, fail positions, the line-number form and the equipment prefixes, laid out in columns that never split a short section, with the usual frame, notes and title block. It is built from the library, so it lists exactly what the kit draws.
+
+## 9. Interactive page (`interactive.mjs`) and motion loop (`scripts/motion.mjs`)
+
+`renderInteractive({ title, description, lang, views: [{ id, label, svg, explode }], layers: [{ group, label }], order, duration, stagger, hint, text })` returns one self-contained HTML page: a button per preset view, an exploded-view toggle, a checkbox per layer group, callout labels that are focusable buttons, a part outline lit on hover or focus, keys `E` and `1`…`n`, `Esc` to clear, reduced motion honoured, an `aria-live` line for state changes, and `#view=…&explode=1&hide=a,b&select=C3` to open in a given state. `explode` maps each group to its screen vector in that view (`view.screenVector(worldMove)`); `order` is the order groups leave in (they come back in reverse). Build each view from the same scene function with `reach: true` style extents so the exploded parts stay on the page.
+
+`renderMotion({ frame, out, name, seconds, fps, width, small, formats })` (or `node scripts/motion.mjs scene.mjs --out <dir>`) draws `frame(t)` for t in [0, 1), rasterises each frame in headless Chrome and writes `name.mp4` (H.264, yuv420p, even size), `name.webp` and `name.gif` (`small` px wide). It needs ffmpeg (and img2webp for WebP) and stops with `ENCODER_REQUIRED` and the install line when one is missing; it never installs anything. `examples/iso-heat-exchanger/scene.mjs` shows the pattern: one `scene({ azimuth, elevation, explode, flow, callouts, reach })` for the figure, the page and the film.

package/assets/lithermes-plugin/skills/lit-schematic/references/pfd-and-layout.md

@@ -0,0 +1,53 @@
+# BFD, PFD and equipment layout
+
+ISO 10628-1 names three process diagrams that refine each other: the **block flow diagram** (units as boxes and the main streams), the **process flow diagram** (equipment, main streams with numbers, operating conditions, a stream table, the control loops that define the process), and the **P&ID** (every line, valve, instrument and safety device). Pick the lightest one that answers the reader's question.
+
+## Contents
+1. Which diagram
+2. Block flow diagram
+3. Process flow diagram
+4. Stream table
+5. Equipment layout and plot plan
+6. Faults
+
+## 1. Which diagram
+
+| Reader's question | Diagram | Mode |
+| --- | --- | --- |
+| What are the units and how does material move between them? | BFD | `pfd` with `unit()` boxes |
+| What equipment, at what conditions, with what mass balance? | PFD | `pfd` |
+| How is it built, controlled, isolated and protected? | P&ID | `pid` |
+| How is it arranged in space, and what does it look like? | Layout or isometric | `pfd` sheet in plan, or `iso` |
+| What did the experiment use? (paper) | Apparatus figure | `journal` |
+
+A BFD drawn with real equipment symbols, or a PFD drawn with every isolation valve, answers the wrong question and costs the reader time.
+
+## 2. Block flow diagram
+
+Units are labelled boxes (`unit({ caption: "Hydrate formation" })`) of one size per level of importance, arranged left to right in process order; streams are `pipe` lines with arrows and short names (`"Feed gas, 5 MPa"` as a line number); recycles return along the bottom lane; utilities stay off the diagram unless they are the point. Use `createSheet({ mode: "pfd" })` and `streamNumber(line, n)` when a mass balance accompanies it.
+
+## 3. Process flow diagram
+
+- **Equipment**: every major item with its tag and name in the header band, drawn with the same symbols as the P&ID; spares (`P-101B`) and minor items stay off.
+- **Streams**: main process lines, heavy; each carries a **stream number** in a diamond (`sheet.streamNumber(line, 3)`), numbered in flow order. The stream number is the key into the stream table.
+- **Conditions**: pressure and temperature flags at key points as short texts beside the line (`sheet.text(x, y, "5.0 MPa, 2 °C")`), or only in the table.
+- **Control**: the loops that define the process (reactor pressure, jacket temperature, level), with their controllers and final elements; no isolation valves, drains or vents.
+- **Utilities**: heating and cooling media as short utility lines into exchangers, labelled with the medium.
+
+## 4. Stream table
+
+`streamTable({ box: [x0, y0, x1], streams: [1, 2, 3], rows: [{ label: "Pressure (MPa)", values: [0.1, 5.0, 5.0] }, …] })` draws one column per stream and one row per property inside the box and returns its bottom. Usual rows: phase, temperature, pressure, total mass flow, molar flow, composition of the key components. Put it below the drawing or across the bottom of the sheet; values come from the user's balance or simulation (HYSYS, Aspen, a spreadsheet), never from estimation without saying so. Units go in the row label, never in the cells.
+
+## 5. Equipment layout and plot plan
+
+A plan view is a PFD-style canvas drawn to scale: `createSheet({ scale: "1:50" })` and coordinates in sheet millimetres = real millimetres ÷ 50. Equipment outlines are their real footprints (`unit` boxes for skids and packages, plain circles added with `canvas.raw()` for vessels seen from above), with aisles at least 1 m real, maintenance envelopes dashed (`zone`), and north arrow and grid lines when the site needs them. For a three-dimensional impression of the same arrangement use an isometric view (`references/isometric-craft.md`): boxes for skids, lathes for vessels, pipes along racks.
+
+## 6. Faults
+
+| You see | Fix |
+| --- | --- |
+| A PFD full of block valves and drains | Remove them; they belong to the P&ID. |
+| Stream numbers that skip or jump around | Number in flow order; recycles take the next free number. |
+| A stream table without units | Units in the row labels. |
+| Values that do not close the balance | Take them from the user's balance or say they are illustrative. |
+| A BFD with equipment symbols | Use labelled boxes; the BFD is about units, not hardware. |