@litfamily/lithermes 1.0.29 → 1.0.30

package/assets/lithermes-plugin/skills/lit-schematic/scripts/lib/geom.mjs

@@ -0,0 +1,113 @@
+// Plane geometry shared by the router, the label placer and the QA gate.
+// Boxes are [x0, y0, x1, y1] with x0 <= x1 and y0 <= y1; points are [x, y].
+
+export const EPS = 1e-6;
+
+export const boxOf = (points) => {
+  const xs = points.map((p) => p[0]);
+  const ys = points.map((p) => p[1]);
+  return [Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys)];
+};
+export const grow = ([x0, y0, x1, y1], by) => [x0 - by, y0 - by, x1 + by, y1 + by];
+export const union = (a, b) => [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.max(a[2], b[2]), Math.max(a[3], b[3])];
+export const area = ([x0, y0, x1, y1]) => Math.max(0, x1 - x0) * Math.max(0, y1 - y0);
+export const boxesOverlap = (a, b, by = 0) => a[0] < b[2] - by && a[2] > b[0] + by && a[1] < b[3] - by && a[3] > b[1] + by;
+export const overlapArea = (a, b) => area([Math.max(a[0], b[0]), Math.max(a[1], b[1]), Math.min(a[2], b[2]), Math.min(a[3], b[3])]);
+export const contains = (outer, inner, by = 0) =>
+  inner[0] >= outer[0] - by && inner[1] >= outer[1] - by && inner[2] <= outer[2] + by && inner[3] <= outer[3] + by;
+export const pointIn = ([x, y], [x0, y0, x1, y1], by = 0) => x > x0 + by && x < x1 - by && y > y0 + by && y < y1 - by;
+export const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+
+export function pointSegmentDistance(p, a, b) {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const span = dx * dx + dy * dy;
+  const t = span > 0 ? Math.max(0, Math.min(1, ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / span)) : 0;
+  return Math.hypot(p[0] - a[0] - t * dx, p[1] - a[1] - t * dy);
+}
+
+// Proper intersection point of two segments, or null. Touching at endpoints counts only when
+// `touch` is true; collinear overlaps are reported separately by `collinearOverlap`.
+export function segmentIntersection(a, b, c, d, touch = false) {
+  const r = [b[0] - a[0], b[1] - a[1]];
+  const s = [d[0] - c[0], d[1] - c[1]];
+  const denom = r[0] * s[1] - r[1] * s[0];
+  if (Math.abs(denom) < EPS) return null;
+  const t = ((c[0] - a[0]) * s[1] - (c[1] - a[1]) * s[0]) / denom;
+  const u = ((c[0] - a[0]) * r[1] - (c[1] - a[1]) * r[0]) / denom;
+  const lo = touch ? -EPS : 1e-4;
+  const hi = touch ? 1 + EPS : 1 - 1e-4;
+  if (t < lo || t > hi || u < lo || u > hi) return null;
+  return { point: [a[0] + t * r[0], a[1] + t * r[1]], t, u };
+}
+
+export function collinearOverlap(a, b, c, d, tolerance = 0.05) {
+  const r = [b[0] - a[0], b[1] - a[1]];
+  const length = Math.hypot(r[0], r[1]);
+  if (length < EPS) return 0;
+  const cross = (p) => Math.abs((p[0] - a[0]) * r[1] - (p[1] - a[1]) * r[0]) / length;
+  if (cross(c) > tolerance || cross(d) > tolerance) return 0;
+  const along = (p) => ((p[0] - a[0]) * r[0] + (p[1] - a[1]) * r[1]) / length;
+  const lo = Math.max(0, Math.min(along(c), along(d)));
+  const hi = Math.min(length, Math.max(along(c), along(d)));
+  return Math.max(0, hi - lo);
+}
+
+// Length of a segment that lies strictly inside a box (Liang–Barsky clip).
+export function insideLength(a, b, [x0, y0, x1, y1]) {
+  let t0 = 0;
+  let t1 = 1;
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  for (const [p, q] of [[-dx, a[0] - x0], [dx, x1 - a[0]], [-dy, a[1] - y0], [dy, y1 - a[1]]]) {
+    if (Math.abs(p) < EPS) {
+      if (q <= 0) return 0;
+    } else {
+      const t = q / p;
+      if (p < 0) t0 = Math.max(t0, t);
+      else t1 = Math.min(t1, t);
+    }
+  }
+  return t1 > t0 ? (t1 - t0) * Math.hypot(dx, dy) : 0;
+}
+
+export const segmentsOf = (points) => points.slice(1).map((point, index) => [points[index], point]);
+
+export function pathLength(points) {
+  return segmentsOf(points).reduce((sum, [a, b]) => sum + dist(a, b), 0);
+}
+
+export function pointAlong(points, at) {
+  let left = at;
+  for (const [a, b] of segmentsOf(points)) {
+    const length = dist(a, b);
+    if (left <= length) {
+      const t = length ? left / length : 0;
+      return { point: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t], direction: length ? [(b[0] - a[0]) / length, (b[1] - a[1]) / length] : [1, 0] };
+    }
+    left -= length;
+  }
+  const [a, b] = segmentsOf(points).at(-1);
+  const length = dist(a, b) || 1;
+  return { point: b, direction: [(b[0] - a[0]) / length, (b[1] - a[1]) / length] };
+}
+
+// Removes repeated points and merges collinear runs, keeping the polyline's corners only.
+export function simplify(points) {
+  const out = [];
+  for (const point of points) {
+    const last = out.at(-1);
+    if (last && dist(last, point) < EPS) continue;
+    if (out.length >= 2) {
+      const prev = out.at(-2);
+      const cross = (last[0] - prev[0]) * (point[1] - last[1]) - (last[1] - prev[1]) * (point[0] - last[0]);
+      const dot = (last[0] - prev[0]) * (point[0] - last[0]) + (last[1] - prev[1]) * (point[1] - last[1]);
+      if (Math.abs(cross) < EPS && dot > 0) {
+        out[out.length - 1] = point;
+        continue;
+      }
+    }
+    out.push(point);
+  }
+  return out;
+}

package/assets/lithermes-plugin/skills/lit-schematic/scripts/lib/interactive.mjs

@@ -0,0 +1,292 @@
+// One self-contained HTML page for an isometric cutaway: preset views, an exploded view, layer
+// toggles and callouts that light their part on hover or keyboard focus. Nothing is fetched:
+// the drawings, styles and script are inline, so the file works offline and from email.
+//
+// Input is the static art the kit already drew, one SVG per preset view, each carrying the
+// markers the kit writes: data-group on assemblies, data-part/data-hull on parts, data-leader,
+// data-leader-dot, data-for-leader and data-target on callouts. Explode vectors are screen
+// offsets per view (view.screenVector of the world move), so the page needs no geometry.
+//
+// State can be set from the URL hash for checks and screenshots:
+//   #view=<id>&explode=1&hide=<group>,<group>&select=<callout id>
+
+import { esc } from "./svg.mjs";
+
+const CSS = `
+:root{--paper:#ffffff;--ink:#1d1d20;--muted:#5d5d64;--line:#d9d9de;--accent:#0072b2;--accent-soft:rgba(0,114,178,.14);--focus:#0072b2;color-scheme:light}
+*{box-sizing:border-box}
+body{margin:0;background:var(--paper);color:var(--ink);font:15px/1.45 Arial,Helvetica,"Apple SD Gothic Neo","Noto Sans KR",Pretendard,sans-serif}
+main{max-width:1180px;margin:0 auto;padding:20px 16px 28px}
+h1{font-size:22px;margin:0 0 4px}
+.lede{margin:0 0 14px;color:var(--muted);max-width:72ch}
+.bar{display:flex;flex-wrap:wrap;gap:10px 18px;align-items:center;margin:0 0 10px;padding:10px 0;border-top:1px solid var(--line);border-bottom:1px solid var(--line)}
+.group{display:flex;flex-wrap:wrap;gap:6px;align-items:center;border:0;margin:0;padding:0}
+.group>span,.group legend{font-size:12px;letter-spacing:.04em;text-transform:uppercase;color:var(--muted);margin-right:4px;padding:0;float:left}
+button{font:inherit;font-size:14px;padding:6px 12px;border:1px solid var(--line);border-radius:6px;background:#fff;color:var(--ink);cursor:pointer}
+button[aria-pressed="true"]{background:var(--ink);border-color:var(--ink);color:#fff}
+label.toggle{display:inline-flex;gap:6px;align-items:center;font-size:14px;padding:4px 8px;border:1px solid var(--line);border-radius:6px;cursor:pointer}
+button:focus-visible,label.toggle:focus-within,[data-for-leader]:focus-visible{outline:2px solid var(--focus);outline-offset:3px}
+.stage{position:relative}
+.stage svg{display:block;width:100%;height:auto;max-height:max(360px, calc(100vh - 200px))}
+.stage .view[hidden]{display:none}
+[data-for-leader]{cursor:pointer}
+[data-for-leader].on{font-weight:bold;fill:var(--accent)}
+path[data-leader].on{stroke:var(--accent);stroke-width:.32}
+circle[data-leader-dot].on{fill:var(--accent)}
+.hl{fill:var(--accent-soft);stroke:var(--accent);stroke-width:.45;pointer-events:none}
+.stage.exploded [data-leader],.stage.exploded [data-leader-dot]{opacity:.55}
+.hint{margin:10px 0 0;font-size:13px;color:var(--muted)}
+.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
+@media (max-width:640px){h1{font-size:19px}button{padding:6px 9px}}
+`;
+
+// The page script: plain DOM, one animation loop that stops when nothing moves.
+const SCRIPT = `
+(() => {
+  const data = JSON.parse(document.getElementById("lit-data").textContent);
+  const stage = document.querySelector(".stage");
+  const live = document.getElementById("live");
+  const still = matchMedia("(prefers-reduced-motion: reduce)");
+  const state = { view: data.views[0].id, explode: 0, hidden: new Set(), select: null };
+  const progress = Object.fromEntries(data.order.map((g) => [g, 0]));
+  const target = Object.fromEntries(data.order.map((g) => [g, 0]));
+  const starts = {};
+  let frame = 0;
+
+  const svgOf = (id) => stage.querySelector('.view[data-view="' + id + '"] svg');
+  const active = () => svgOf(state.view);
+  const viewData = (id) => data.views.find((v) => v.id === id);
+  const say = (text) => { live.textContent = text; };
+
+  // Original leader ends, so an exploded part keeps its dot.
+  for (const view of data.views) {
+    const svg = svgOf(view.id);
+    for (const path of svg.querySelectorAll("path[data-leader]")) path.dataset.d0 = path.getAttribute("d");
+    for (const dot of svg.querySelectorAll("circle[data-leader-dot]")) { dot.dataset.cx0 = dot.getAttribute("cx"); dot.dataset.cy0 = dot.getAttribute("cy"); }
+    for (const label of svg.querySelectorAll("[data-for-leader]")) {
+      label.setAttribute("tabindex", "0");
+      label.setAttribute("role", "button");
+      label.setAttribute("aria-pressed", "false");
+    }
+  }
+
+  const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+  const offsetOf = (node, view) => {
+    let dx = 0, dy = 0;
+    for (let n = node; n && n.tagName !== "svg"; n = n.parentNode) {
+      const g = n.getAttribute && n.getAttribute("data-group");
+      const v = g && viewData(view).explode[g];
+      if (v) { dx += v[0] * progress[g]; dy += v[1] * progress[g]; }
+    }
+    return [dx, dy];
+  };
+
+  function place(view) {
+    const svg = svgOf(view);
+    const vd = viewData(view);
+    for (const node of svg.querySelectorAll("[data-group]")) {
+      const g = node.getAttribute("data-group");
+      const v = vd.explode[g];
+      const p = progress[g] || 0;
+      if (v && p > 0) node.setAttribute("transform", "translate(" + (v[0] * p).toFixed(3) + " " + (v[1] * p).toFixed(3) + ")");
+      else node.removeAttribute("transform");
+      // visibility, not display: an assembly nested in a hidden one (a bundle inside its shell) stays.
+      node.style.visibility = state.hidden.has(g) ? "hidden" : "visible";
+    }
+    for (const path of svg.querySelectorAll("path[data-leader]")) {
+      const id = path.getAttribute("data-leader");
+      const part = svg.querySelector('[data-part="' + CSS.escape(path.getAttribute("data-target") || "") + '"]');
+      const [dx, dy] = part ? offsetOf(part, view) : [0, 0];
+      const pts = path.dataset.d0.match(/-?[\\d.]+/g).map(Number);
+      pts[pts.length - 2] += dx; pts[pts.length - 1] += dy;
+      path.setAttribute("d", "M" + pts[0] + " " + pts[1] + pts.slice(2).reduce((s, v, i) => s + (i % 2 ? " " + v : "L" + v), ""));
+      const dot = svg.querySelector('circle[data-leader-dot="' + id + '"]');
+      dot.setAttribute("cx", (Number(dot.dataset.cx0) + dx).toFixed(3));
+      dot.setAttribute("cy", (Number(dot.dataset.cy0) + dy).toFixed(3));
+      const hiddenPart = part && part.closest("[data-group]") && [...state.hidden].some((g) => part.closest('[data-group="' + g + '"]'));
+      for (const el of [path, dot, svg.querySelector('[data-for-leader="' + id + '"]')]) el.style.display = hiddenPart ? "none" : "";
+    }
+    highlight(view);
+  }
+
+  function highlight(view) {
+    const svg = svgOf(view);
+    svg.querySelectorAll(".hl").forEach((n) => n.remove());
+    svg.querySelectorAll(".on").forEach((n) => n.classList.remove("on"));
+    svg.querySelectorAll("[data-for-leader]").forEach((n) => n.setAttribute("aria-pressed", "false"));
+    if (!state.select) return;
+    const label = svg.querySelector('[data-for-leader="' + state.select + '"]');
+    if (!label) return;
+    const path = svg.querySelector('path[data-leader="' + state.select + '"]');
+    const part = svg.querySelector('[data-part="' + CSS.escape(path.getAttribute("data-target") || "") + '"]');
+    [label, path, svg.querySelector('circle[data-leader-dot="' + state.select + '"]')].forEach((n) => n.classList.add("on"));
+    label.setAttribute("aria-pressed", "true");
+    if (part && part.dataset.hull) {
+      const [dx, dy] = offsetOf(part, view);
+      const poly = document.createElementNS("http://www.w3.org/2000/svg", "polygon");
+      poly.setAttribute("class", "hl");
+      poly.setAttribute("points", part.dataset.hull.split(" ").map((p) => p.split(",").map(Number)).map(([x, y]) => (x + dx).toFixed(2) + "," + (y + dy).toFixed(2)).join(" "));
+      svg.querySelector("[data-callouts]").before(poly);
+    }
+  }
+
+  function tick(now) {
+    let moving = false;
+    for (const g of data.order) {
+      const s = starts[g];
+      if (!s) continue;
+      const t = Math.min(1, Math.max(0, (now - s.at) / data.duration));
+      progress[g] = s.from + (target[g] - s.from) * ease(t);
+      if (t < 1) moving = true; else delete starts[g];
+    }
+    place(state.view);
+    frame = moving ? requestAnimationFrame(tick) : 0;
+  }
+
+  function setExplode(on, announce = true) {
+    state.explode = on ? 1 : 0;
+    stage.classList.toggle("exploded", !!on);
+    document.getElementById("explode").setAttribute("aria-pressed", String(!!on));
+    // Outside parts leave first and come home last.
+    const order = on ? data.order : [...data.order].reverse();
+    const now = performance.now();
+    order.forEach((g, i) => {
+      target[g] = on ? 1 : 0;
+      if (still.matches) { progress[g] = target[g]; delete starts[g]; }
+      else starts[g] = { from: progress[g], at: now + i * data.stagger };
+    });
+    if (still.matches) place(state.view);
+    else if (!frame) frame = requestAnimationFrame(tick);
+    if (announce) say(on ? data.text.exploded : data.text.assembled);
+  }
+
+  function setView(id, announce = true) {
+    state.view = id;
+    for (const node of stage.querySelectorAll(".view")) node.hidden = node.dataset.view !== id;
+    for (const b of document.querySelectorAll("[data-view-button]")) b.setAttribute("aria-pressed", String(b.dataset.viewButton === id));
+    place(id);
+    if (announce) say(viewData(id).label);
+  }
+
+  function select(id, announce = true) {
+    state.select = state.select === id ? null : id;
+    highlight(state.view);
+    if (announce && state.select) say(active().querySelector('[data-for-leader="' + state.select + '"]').textContent);
+  }
+
+  document.querySelectorAll("[data-view-button]").forEach((b) => b.addEventListener("click", () => setView(b.dataset.viewButton)));
+  document.getElementById("explode").addEventListener("click", () => setExplode(!state.explode));
+  document.querySelectorAll("[data-layer]").forEach((box) => box.addEventListener("change", () => {
+    if (box.checked) state.hidden.delete(box.dataset.layer); else state.hidden.add(box.dataset.layer);
+    place(state.view);
+    say((box.checked ? data.text.shown : data.text.hidden) + " " + box.dataset.label);
+  }));
+  stage.addEventListener("click", (e) => {
+    const label = e.target.closest("[data-for-leader]");
+    if (label) { select(label.getAttribute("data-for-leader")); return; }
+    const part = e.target.closest("[data-part]");
+    const id = part && partCallout(part);
+    if (id) select(id);
+  });
+  stage.addEventListener("keydown", (e) => {
+    const label = e.target.closest && e.target.closest("[data-for-leader]");
+    if (label && (e.key === "Enter" || e.key === " ")) { e.preventDefault(); select(label.getAttribute("data-for-leader")); }
+  });
+  stage.addEventListener("focusin", (e) => {
+    const label = e.target.closest && e.target.closest("[data-for-leader]");
+    if (label && state.select !== label.getAttribute("data-for-leader")) select(label.getAttribute("data-for-leader"));
+  });
+  // Hover previews a part's callout without changing the selection the keyboard made.
+  let hoverFrom = null;
+  stage.addEventListener("pointermove", (e) => {
+    const label = e.target.closest("[data-for-leader]");
+    const part = !label && e.target.closest("[data-part]");
+    const id = label ? label.getAttribute("data-for-leader") : part ? partCallout(part) : null;
+    if (id && id !== state.select) { if (hoverFrom === null) hoverFrom = state.select; state.select = id; highlight(state.view); }
+    if (!id && hoverFrom !== null) { state.select = hoverFrom; hoverFrom = null; highlight(state.view); }
+  });
+  stage.addEventListener("pointerleave", () => { if (hoverFrom !== null) { state.select = hoverFrom; hoverFrom = null; highlight(state.view); } });
+  document.addEventListener("keydown", (e) => {
+    // A held key repeats; a toggle should flip once per press.
+    if (e.repeat || e.altKey || e.ctrlKey || e.metaKey) return;
+    if (e.target.closest && e.target.closest("input,button")) { if (e.key !== "Escape") return; }
+    if (e.key === "Escape") { state.select = null; highlight(state.view); }
+    if (e.key === "e" || e.key === "E") setExplode(!state.explode);
+    const n = Number(e.key);
+    if (n >= 1 && n <= data.views.length) setView(data.views[n - 1].id);
+  });
+  function partCallout(part) {
+    for (let n = part; n && n.tagName !== "svg"; n = n.parentNode) {
+      const name = n.getAttribute && n.getAttribute("data-part");
+      if (!name) continue;
+      const path = active().querySelector('path[data-leader][data-target="' + CSS.escape(name) + '"]');
+      if (path) return path.getAttribute("data-leader");
+    }
+    return null;
+  }
+
+  // Initial state, optionally from the hash.
+  const hash = new URLSearchParams(location.hash.slice(1));
+  for (const g of (hash.get("hide") || "").split(",").filter(Boolean)) {
+    state.hidden.add(g);
+    const box = document.querySelector('[data-layer="' + g + '"]');
+    if (box) box.checked = false;
+  }
+  setView(viewData(hash.get("view")) ? hash.get("view") : state.view, false);
+  if (hash.get("explode") === "1") { for (const g of data.order) { progress[g] = 1; target[g] = 1; } state.explode = 1; stage.classList.add("exploded"); document.getElementById("explode").setAttribute("aria-pressed", "true"); }
+  if (hash.get("select")) state.select = hash.get("select");
+  place(state.view);
+  document.documentElement.dataset.ready = "1";
+})();
+`;
+
+export function renderInteractive({
+  title, description = "", lang = "en", views, layers = [], order = null,
+  duration = 700, stagger = 90, hint = null,
+  text = {},
+} = {}) {
+  if (!title) throw new Error("renderInteractive: title is required");
+  if (!views?.length) throw new Error("renderInteractive: give at least one view { id, label, svg, explode }");
+  const groups = order ?? [...new Set(views.flatMap((v) => Object.keys(v.explode ?? {})))];
+  const words = {
+    views: "View", layers: "Layers", explode: "Exploded view", exploded: "Exploded view", assembled: "Assembled",
+    shown: "Showing", hidden: "Hiding",
+    hint: "Hover or Tab to a label to light its part. E explodes, 1 to " + views.length + " switch views, Esc clears.",
+    ...text,
+  };
+  const data = {
+    views: views.map((v) => ({ id: v.id, label: v.label, explode: v.explode ?? {} })),
+    order: groups, duration, stagger,
+    text: { exploded: words.exploded, assembled: words.assembled, shown: words.shown, hidden: words.hidden },
+  };
+  const stripProlog = (svg) => svg.replace(/^\s*<\?xml[^>]*>\s*/u, "");
+  const viewButtons = views.map((v, i) => `<button type="button" data-view-button="${esc(v.id)}" aria-pressed="${i === 0}" aria-keyshortcuts="${i + 1}">${esc(v.label)}</button>`).join("");
+  const layerBoxes = layers.map((l) => `<label class="toggle"><input type="checkbox" checked data-layer="${esc(l.group)}" data-label="${esc(l.label)}">${esc(l.label)}</label>`).join("");
+  const stages = views.map((v, i) => `<div class="view" data-view="${esc(v.id)}"${i ? " hidden" : ""}>${stripProlog(v.svg)}</div>`).join("");
+  return `<!doctype html>
+<html lang="${esc(lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+<h1>${esc(title)}</h1>
+${description ? `<p class="lede">${esc(description)}</p>` : ""}
+<div class="bar">
+<div class="group" role="group" aria-label="${esc(words.views)}"><span aria-hidden="true">${esc(words.views)}</span>${viewButtons}</div>
+<button type="button" id="explode" aria-pressed="false" aria-keyshortcuts="E">${esc(words.explode)}</button>
+${layers.length ? `<fieldset class="group"><legend>${esc(words.layers)}</legend>${layerBoxes}</fieldset>` : ""}
+</div>
+<div class="stage">${stages}</div>
+<p class="hint">${esc(hint ?? words.hint)}</p>
+<p id="live" class="sr" aria-live="polite"></p>
+</main>
+<script type="application/json" id="lit-data">${JSON.stringify(data).replace(/</gu, "\\u003c")}</script>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+}

package/assets/lithermes-plugin/skills/lit-schematic/scripts/lib/isa.mjs

@@ -0,0 +1,115 @@
+// Instrument and equipment tag grammar after ANSI/ISA-5.1 identification letters.
+// The parser is deliberately strict about letter positions and lenient about loop numbers,
+// because projects number loops in many ways (101, 1-101, 101A) but letters carry meaning.
+
+export const MEASURED = Object.freeze({
+  A: "analysis", B: "burner, combustion", C: "conductivity", D: "density", E: "voltage",
+  F: "flow", G: "gauging", H: "hand", I: "current", J: "power", K: "time", L: "level",
+  M: "moisture", N: "user's choice", O: "user's choice", P: "pressure", Q: "quantity",
+  R: "radiation", S: "speed, frequency", T: "temperature", U: "multivariable", V: "vibration",
+  W: "weight, force", X: "unclassified", Y: "event, state", Z: "position",
+});
+
+export const VARIABLE_MODIFIER = Object.freeze({
+  D: "differential", F: "ratio", J: "scan", K: "time rate of change", M: "momentary",
+  Q: "integrate, totalize", S: "safety", X: "x-axis", Y: "y-axis", Z: "z-axis",
+});
+
+export const READOUT = Object.freeze({
+  A: "alarm", B: "user's choice", E: "primary element", G: "glass, gauge", I: "indicating",
+  L: "light", N: "user's choice", O: "orifice, restriction", P: "test point", R: "recording",
+  W: "well, probe", X: "unclassified",
+});
+
+export const OUTPUT = Object.freeze({
+  C: "controlling", K: "control station", S: "switch", T: "transmitting", U: "multifunction",
+  V: "valve, damper", Y: "compute, convert, relay", Z: "actuator, final element",
+});
+
+export const FUNCTION_MODIFIER = Object.freeze({ H: "high", L: "low", M: "middle" });
+
+// Pairs whose meaning is the readable name, not the letter-by-letter reading.
+const NAMED = Object.freeze({
+  PSV: "pressure safety valve", PSE: "rupture disk", TW: "thermowell", PG: "pressure gauge",
+  TG: "thermometer", LG: "level gauge", FG: "sight flow glass", PCV: "self-actuated pressure regulator",
+  FO: "restriction orifice", HV: "hand valve", HS: "hand switch", XV: "on-off valve",
+});
+
+const TAG = /^([A-Z]{1,6})[-\s]?([0-9]{1,5}(?:[-.][0-9]{1,5})?[A-Z]?)$/u;
+
+export function parseInstrumentTag(tag) {
+  const match = TAG.exec(String(tag ?? "").trim());
+  if (!match) return { ok: false, tag, error: "a tag is identification letters followed by a loop number, for example PIC-101" };
+  const [, letters, loop] = match;
+  const [first, ...rest] = letters;
+  if (!MEASURED[first]) return { ok: false, tag, error: `${first} is not a measured-variable letter` };
+  let index = 0;
+  let modifier = null;
+  // A second letter that is a variable modifier only counts as one when a function follows it.
+  if (rest.length > 1 && VARIABLE_MODIFIER[rest[0]]) {
+    const candidate = rest[0];
+    const followers = rest.slice(1);
+    const followersValid = followers.every((letter) => READOUT[letter] || OUTPUT[letter] || FUNCTION_MODIFIER[letter]);
+    if (followersValid && !(candidate === "S" && followers.every((letter) => FUNCTION_MODIFIER[letter]))) {
+      modifier = candidate;
+      index = 1;
+    }
+  }
+  const functions = rest.slice(index);
+  if (functions.length === 0) return { ok: false, tag, error: "a tag needs at least one function letter after the measured variable" };
+  const words = [];
+  let seenOutput = false;
+  for (let i = 0; i < functions.length; i++) {
+    const letter = functions[i];
+    if (FUNCTION_MODIFIER[letter]) {
+      const previous = functions[i - 1];
+      if (!previous || !(previous === "A" || previous === "S" || FUNCTION_MODIFIER[previous])) {
+        return { ok: false, tag, error: `${letter} (high/low) may only follow an alarm or switch letter` };
+      }
+      words.push(FUNCTION_MODIFIER[letter]);
+      continue;
+    }
+    if (READOUT[letter]) {
+      if (seenOutput && (letter === "I" || letter === "R")) return { ok: false, tag, error: `readout letter ${letter} must come before output letters` };
+      words.push(READOUT[letter]);
+      continue;
+    }
+    if (OUTPUT[letter]) {
+      seenOutput = true;
+      words.push(OUTPUT[letter]);
+      continue;
+    }
+    return { ok: false, tag, error: `${letter} is not a function letter` };
+  }
+  const repeated = functions.filter((letter, i) => !FUNCTION_MODIFIER[letter] && functions.indexOf(letter) !== i);
+  if (repeated.length) return { ok: false, tag, error: `function letter ${repeated[0]} repeats` };
+  const meaning = NAMED[letters] ?? [MEASURED[first], modifier ? VARIABLE_MODIFIER[modifier] : null, ...words].filter(Boolean).join(" ");
+  return { ok: true, tag, letters, loop, first, modifier, functions, meaning };
+}
+
+// Equipment tags: a class prefix of one to three letters, a number, an optional train suffix.
+const EQUIPMENT = /^([A-Z]{1,3})-?([0-9]{2,5})([A-Z]?)$/u;
+export const EQUIPMENT_CLASS = Object.freeze({
+  B: "blower", C: "column", CV: "conveyor", D: "drum", E: "heat exchanger", F: "filter",
+  H: "heater", K: "compressor", M: "mixer, agitator", P: "pump", PK: "package unit",
+  R: "reactor", S: "separator", T: "tower", TK: "tank", V: "vessel", X: "miscellaneous",
+  GC: "gas cylinder", CH: "chiller", BR: "booster", MFC: "mass flow controller", A: "analyzer",
+});
+
+export function parseEquipmentTag(tag) {
+  const match = EQUIPMENT.exec(String(tag ?? "").trim());
+  if (!match) return { ok: false, tag, error: "an equipment tag is a class prefix and a number, for example R-101 or P-101A" };
+  return { ok: true, tag, prefix: match[1], number: match[2], train: match[3] || null, meaning: EQUIPMENT_CLASS[match[1]] ?? null };
+}
+
+// Line numbers: nominal size, fluid code, sequence number, piping class, and an optional
+// insulation or tracing code, joined by hyphens: 2"-P-1001-A1A, 1/4"-CH4-101-HP1, DN50-CW-205-B1-IH.
+// Projects order the parts differently; this is the common size-first form most P&IDs use.
+const LINE_NUMBER = /^((?:\d+(?:\s\d+\/\d+)?|\d+\/\d+)"|DN\d{1,4}|\d{1,4}mm)-([A-Z][A-Z0-9]{0,5})-(\d{2,6}[A-Z]?)-([A-Z0-9]{1,8})(?:-([A-Z]{1,4}))?$/u;
+
+export function parseLineNumber(text) {
+  const match = LINE_NUMBER.exec(String(text ?? "").trim());
+  if (!match) return { ok: false, text, error: "a line number is size-fluid-sequence-class[-insulation], for example 2\"-P-1001-A1A" };
+  const [, size, fluid, sequence, spec, insulation = null] = match;
+  return { ok: true, text, size, fluid, sequence, spec, insulation };
+}