windcraft-editor 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @windcraft/editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Windcraft visual editor (HTML + Tailwind): canvas, layers, Properties panel, code panel and pages. It has no backend of its own: the page that mounts it gives it a **host** that loads and saves.
+
+```js
+import { mountEditor } from "@windcraft/editor";
+
+await mountEditor(document.getElementById("root"), {
+    host,   // saving, projects, AI and the address: see design/host.js
+    data,   // the design to open: { id, title, htmlCode, ... }
+});
+```
+
+| Piece | Where |
+|---|---|
+| What the app must provide | `design/host.js` (the `Host` type) |
+| A host with no backend (localStorage) | `demo/demo.js` |
+| Run the demo | `npm run demo`, then open http://localhost:4000/editor/demo/ |
+| Windcraft's own host | `src/public/js/app-host.js` |
+
+The page must map `@windcraft/core/` and `@windcraft/editor/` to where they are served (an import map, as in `demo/index.html`, or a bundler). `mountEditor` loads Tailwind's play CDN (v3) unless you pass `tailwind: false`. One editor per page; it takes over the page's size, keys and zoom.
+
+The AI panel and "Generate" need `host.generate`; without a working one they show its error.
+
+## Embedding in a container
+
+`embedEditor` puts the editor in an element of your page, isolated in an iframe (its own keys, zoom and styles), so several can share a page and it fills whatever size you give it. Leave out the parts you don't need with `ui`; keep the code box and the details form in your own page.
+
+```js
+import { embedEditor } from "@windcraft/editor";
+
+const ed = embedEditor(el, {
+    host,                                    // saving, as above
+    data: { htmlCode },                      // what to open
+    ui: { panels: false, nav: false, tools: ["move", "hand", "interact", "frame", "shape", "text", "add"] },
+    onDetails: (fields) => showMyForm(fields), // the first save of a new design needs a name: you ask, then call saveDetails
+});
+ed.onChange(({ html, dirty, status, source }) => {});  // source: "host" (your setHtml), "editor" (a change there), "status" (save state only)
+ed.setHtml(html);  ed.getHtml();  ed.isDirty();  ed.save();
+await ed.saveDetails({ title, category, description, tags, isPublished, useAsReference, project });
+ed.destroy();
+```
+
+| `ui` | Effect |
+|---|---|
+| `panels: false` | no Layers, Properties or Code panels |
+| `nav: false` | no Back, page list or project |
+| `tools: [...]` | only these tools (`move hand interact frame shape text add`); `null` keeps all |
+
+The iframe loads `embed.html` (next to `embed.js`; pass `src` if you serve it elsewhere). It needs the same import map as any editor page. Run `npm run demo` and open `/editor/demo/embed.html` for a working example: a code box and the editor following each other.

package/core/board-layout.js

@@ -0,0 +1,71 @@
+// Where each design sits on a project's infinite plane. Shared by the project board and the editor.
+// Saved positions win. Everything else is laid out automatically: pages in a row, each page's sections stacked beneath it.
+// Pages that have a group ("Public site", "Customer area") get a row of their own per group, the rows one under the other in
+// the order the groups first appear; without groups there is one row, as there always was.
+export const GAP_X = 320;
+export const SECTION_GAP = 200;
+export const ROW_GAP = 360; // between the bottom of one group's row and the labels of the next
+export const PAGE_H = 900;
+export const SEC_H = 480;
+
+const LABEL_H = 40; // the name above each frame belongs to it
+const CLEAR = 60; // the least air between two frames
+
+/**
+ * items: [{ id, kind, parent, group, board }]. Returns { [id]: { x, y } }. A frame may be wider than frameW (widthOf).
+ * Nothing placed automatically lands on another frame: a spot that is taken (by a frame with a saved position, or one placed before)
+ * is moved past it, a page to the right and a section below. Saved positions are never moved.
+ */
+export function computeLayout(items, { frameW, heightOf, widthOf = () => frameW }) {
+    const pos = {};
+    const box = (it, p) => ({ x: p.x, y: p.y - LABEL_H, r: p.x + widthOf(it), b: p.y + heightOf(it) });
+    const taken = []; // the boxes of what has a place: the saved ones first, then each one placed
+    items.forEach((i) => { if (i.board) taken.push(box(i, i.board)); });
+    const hit = (a, b) => a.x < b.r + CLEAR && a.r + CLEAR > b.x && a.y < b.b + CLEAR && a.b + CLEAR > b.y;
+    /** The first spot from `p` that touches nothing, moving right (down: false) or down. */
+    const clear = (it, p, down) => {
+        let q = { ...p };
+        for (let n = 0; n < 400; n++) {
+            const me = box(it, q), other = taken.find((t) => hit(me, t));
+            if (!other) return q;
+            q = down ? { x: q.x, y: other.b + CLEAR + LABEL_H } : { x: other.r + CLEAR, y: q.y };
+        }
+        return q;
+    };
+    const place = (it, want, down) => {
+        const p = it.board ? { x: it.board.x, y: it.board.y } : clear(it, want, down);
+        if (!it.board) taken.push(box(it, p));
+        return p;
+    };
+    const pages = items.filter((i) => i.kind !== "section" || !items.some((p) => p.id === i.parent));
+    /** @type {{ group: string, pages: typeof pages }[]} */
+    const rows = [];
+    pages.forEach((p) => {
+        const group = p.group || "";
+        let row = rows.find((r) => r.group === group);
+        if (!row) rows.push((row = { group, pages: [] }));
+        row.pages.push(p);
+    });
+    let rowY = 0;
+    rows.forEach((row) => {
+        let nextX = 0;
+        // the lowest edge of this row, so the next row starts below it. A page moved by hand keeps its slot, its height included:
+        // dragging a page never moves another one (a row below doesn't move up when a tall page is picked up)
+        let bottom = rowY;
+        row.pages.forEach((p) => {
+            pos[p.id] = place(p, { x: nextX, y: rowY }, false);
+            nextX = (p.board ? nextX : pos[p.id].x) + widthOf(p) + GAP_X;
+            let y = pos[p.id].y + heightOf(p) + 260;
+            let slot = rowY + heightOf(p) + 260; // the same stack, as it stands in the slot
+            bottom = Math.max(bottom, rowY + heightOf(p));
+            items.filter((i) => i.kind === "section" && i.parent === p.id).forEach((s) => {
+                pos[s.id] = place(s, { x: pos[p.id].x, y }, true);
+                bottom = Math.max(bottom, slot + heightOf(s));
+                y = pos[s.id].y + heightOf(s) + SECTION_GAP;
+                slot += heightOf(s) + SECTION_GAP;
+            });
+        });
+        rowY = bottom + ROW_GAP;
+    });
+    return pos;
+}

package/core/class-groups.js

@@ -0,0 +1,210 @@
+// @ts-check
+// A registry of Tailwind utility groups. Each group is a set of mutually exclusive classes
+// (for example every font size). Controls read and write a group for a chosen variant
+// (breakpoint and state), e.g. "md:hover:".
+export const HUES = ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose", "brand"]; // brand: every project has its own scale (brand-50 to brand-950, see theme.js)
+export const SHADES = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+export const SPECIAL_COLORS = ["black", "white", "transparent", "current"];
+
+export const STEPS = ["0", "px", "0.5", "1", "1.5", "2", "2.5", "3", "3.5", "4", "5", "6", "7", "8", "9", "10", "11", "12", "14", "16", "20", "24", "28", "32", "36", "40", "44", "48", "52", "56", "60", "64", "72", "80", "96"];
+export const SIZES = [...STEPS, "auto", "full", "screen", "min", "max", "fit", "1/2", "1/3", "2/3", "1/4", "3/4", "1/5", "2/5", "3/5", "4/5"];
+export const MAX_W = ["none", "xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl", "7xl", "full", "prose", "screen-sm", "screen-md", "screen-lg", "screen-xl"];
+
+const STEP = "\\d+(?:\\.5)?|px";
+const SIZE = `${STEP}|auto|full|screen|min|max|fit|\\d+/\\d+`;
+const ARB = "\\[[^\\]]+\\]";
+const HUE_RE = HUES.join("|");
+const COLOR = `(?:(?:${HUE_RE})-\\d{2,3}|black|white|transparent|current|inherit|\\[(?:#|rgb|hsl|var)[^\\]]*\\])(?:/\\d+|/\\[[^\\]]+\\])?`;
+
+const normArb = (v) => {
+    v = String(v).trim();
+    if (/^\[.*\]$/.test(v)) return v;
+    if (/^-?\d*\.?\d+(px|rem|em|%|vh|vw|vmin|vmax|ch|deg|ms|s|fr)$/.test(v) || /^(calc|var|min|max|clamp)\(/.test(v)) return `[${v}]`;
+    return v;
+};
+const normColor = (v) => {
+    v = String(v).trim();
+    if (/^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\()/.test(v)) return `[${v.replace(/\s+/g, "_")}]`;
+    return v;
+};
+
+// prefix-value utility (w-4, -mt-2, gap-x-[10px])
+const P = (prefix, vals, { neg = false, arb = true } = {}) => ({
+    re: new RegExp(`^(${neg ? "-?" : ""})${prefix}-(${vals}${arb ? `|${ARB}` : ""})$`),
+    read: (m) => (m[1] || "") + m[2],
+    build: (v) => {
+        let sign = "";
+        v = String(v).trim();
+        if (neg && v.startsWith("-")) { sign = "-"; v = v.slice(1); }
+        return `${sign}${prefix}-${normArb(v)}`;
+    },
+});
+// exact words (display: flex)
+const E = (alts) => ({ re: new RegExp(`^(${alts})$`), read: (m) => m[1], build: (v) => v });
+// color utility with optional /opacity
+const C = (prefix) => ({
+    re: new RegExp(`^${prefix}-(${COLOR})$`),
+    read: (m) => m[1],
+    build: (v) => `${prefix}-${normColor(v)}`,
+});
+
+export const GROUPS = {
+    // layout
+    display: E("block|inline-block|inline|flex|inline-flex|grid|inline-grid|hidden|contents|table|flow-root"),
+    position: E("static|fixed|absolute|relative|sticky"),
+    overflow: E("overflow-(?:auto|hidden|visible|scroll|clip)"),
+    overflowX: E("overflow-x-(?:auto|hidden|visible|scroll|clip)"),
+    overflowY: E("overflow-y-(?:auto|hidden|visible|scroll|clip)"),
+    z: P("z", "\\d+|auto", { neg: true }),
+    visibility: E("visible|invisible"),
+    // flex and grid
+    flexDir: E("flex-(?:row|col|row-reverse|col-reverse)"),
+    flexWrap: E("flex-(?:wrap|nowrap|wrap-reverse)"),
+    justify: E("justify-(?:start|center|end|between|around|evenly|stretch|normal)"),
+    items: E("items-(?:start|center|end|stretch|baseline)"),
+    content: E("content-(?:start|center|end|between|around|evenly|stretch)"),
+    self: E("self-(?:auto|start|center|end|stretch|baseline)"),
+    grow: E("grow|grow-0"),
+    shrink: E("shrink|shrink-0"),
+    flexNum: E("flex-(?:1|auto|initial|none)"),
+    gap: P("gap", STEP),
+    gapX: P("gap-x", STEP),
+    gapY: P("gap-y", STEP),
+    gridCols: P("grid-cols", "\\d+|none|subgrid"),
+    gridRows: P("grid-rows", "\\d+|none|subgrid"),
+    colSpan: P("col-span", "\\d+|full"),
+    rowSpan: P("row-span", "\\d+|full"),
+    order: P("order", "\\d+|first|last|none", { neg: true }),
+    // size
+    w: P("w", SIZE),
+    h: P("h", SIZE),
+    minW: P("min-w", `${STEP}|full|min|max|fit`),
+    maxW: P("max-w", `${STEP}|${MAX_W.join("|")}|fit|min|max`),
+    minH: P("min-h", `${STEP}|full|screen|min|max|fit`),
+    maxH: P("max-h", `${STEP}|full|screen|min|max|fit|none`),
+    aspect: P("aspect", "auto|square|video"),
+    objectFit: E("object-(?:contain|cover|fill|none|scale-down)"),
+    // spacing
+    p: P("p", STEP), px: P("px", STEP), py: P("py", STEP), pt: P("pt", STEP), pr: P("pr", STEP), pb: P("pb", STEP), pl: P("pl", STEP),
+    m: P("m", `${STEP}|auto`, { neg: true }), mx: P("mx", `${STEP}|auto`, { neg: true }), my: P("my", `${STEP}|auto`, { neg: true }),
+    mt: P("mt", `${STEP}|auto`, { neg: true }), mr: P("mr", `${STEP}|auto`, { neg: true }), mb: P("mb", `${STEP}|auto`, { neg: true }), ml: P("ml", `${STEP}|auto`, { neg: true }),
+    spaceX: P("space-x", STEP, { neg: true }),
+    spaceY: P("space-y", STEP, { neg: true }),
+    // position offsets
+    inset: P("inset", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    top: P("top", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    right: P("right", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    bottom: P("bottom", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    left: P("left", `${STEP}|auto|full|\\d+/\\d+`, { neg: true }),
+    // typography
+    fontFamily: E("font-(?:sans|serif|mono)"),
+    fontSize: { re: /^text-(xs|sm|base|lg|xl|[2-9]xl|\[\d[^\]]*\])$/, read: (m) => m[1], build: (v) => `text-${normArb(v)}` },
+    fontWeight: E("font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)"),
+    fontStyle: E("italic|not-italic"),
+    leading: P("leading", "none|tight|snug|normal|relaxed|loose|\\d+"),
+    tracking: P("tracking", "tighter|tight|normal|wide|wider|widest"),
+    textAlign: E("text-(?:left|center|right|justify|start|end)"),
+    textColor: C("text"),
+    textDecoration: E("underline|overline|line-through|no-underline"),
+    textTransform: E("uppercase|lowercase|capitalize|normal-case"),
+    textOverflow: E("truncate|text-ellipsis|text-clip"),
+    whitespace: E("whitespace-(?:normal|nowrap|pre|pre-line|pre-wrap|break-spaces)"),
+    lineClamp: P("line-clamp", "\\d+|none"),
+    // background
+    bgColor: C("bg"),
+    bgImage: E("bg-gradient-to-(?:t|tr|r|br|b|bl|l|tl)|bg-none"),
+    gradFrom: C("from"), gradVia: C("via"), gradTo: C("to"),
+    bgSize: E("bg-(?:auto|cover|contain)"),
+    bgPosition: E("bg-(?:center|top|right|bottom|left|left-top|left-bottom|right-top|right-bottom)"),
+    bgRepeat: E("bg-(?:repeat|no-repeat|repeat-x|repeat-y)"),
+    fill: C("fill"), stroke: C("stroke"),
+    // border
+    borderWidth: { re: /^border(?:-([0248]|\[\d[^\]]*\]))?$/, read: (m) => m[1] || "1", build: (v) => (v === "1" || v === "" ? "border" : `border-${normArb(v)}`) },
+    borderT: P("border-t", "[0248]"), borderR: P("border-r", "[0248]"), borderB: P("border-b", "[0248]"), borderL: P("border-l", "[0248]"),
+    borderStyle: E("border-(?:solid|dashed|dotted|double|none)"),
+    borderColor: C("border"),
+    radius: { re: /^rounded(?:-(none|sm|md|lg|xl|2xl|3xl|full|\[[^\]]+\]))?$/, read: (m) => m[1] || "", build: (v) => (v === "" || v === "default" ? "rounded" : `rounded-${normArb(v)}`) },
+    radiusTL: P("rounded-tl", "none|sm|md|lg|xl|2xl|3xl|full"), radiusTR: P("rounded-tr", "none|sm|md|lg|xl|2xl|3xl|full"),
+    radiusBR: P("rounded-br", "none|sm|md|lg|xl|2xl|3xl|full"), radiusBL: P("rounded-bl", "none|sm|md|lg|xl|2xl|3xl|full"),
+    ring: { re: /^ring(?:-([0124-8]))?$/, read: (m) => m[1] || "3", build: (v) => (v === "3" ? "ring" : `ring-${v}`) },
+    ringColor: C("ring"),
+    // effects
+    shadow: { re: /^shadow(?:-(sm|md|lg|xl|2xl|inner|none))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" || v === "" ? "shadow" : `shadow-${v}`) },
+    shadowColor: C("shadow"),
+    opacity: P("opacity", "\\d+"),
+    blur: { re: /^blur(?:-(none|sm|md|lg|xl|2xl|3xl))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" ? "blur" : `blur-${v}`) },
+    backdropBlur: { re: /^backdrop-blur(?:-(none|sm|md|lg|xl|2xl|3xl))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" ? "backdrop-blur" : `backdrop-blur-${v}`) },
+    brightness: P("brightness", "\\d+"),
+    grayscale: { re: /^grayscale(?:-(0))?$/, read: (m) => m[1] || "100", build: (v) => (v === "0" ? "grayscale-0" : "grayscale") },
+    mixBlend: E("mix-blend-(?:normal|multiply|screen|overlay|darken|lighten|difference)"),
+    rotate: P("rotate", "\\d+", { neg: true }),
+    scale: P("scale", "\\d+"),
+    // an outline: its style (outline = solid), width, colour and offset are four classes
+    outlineStyle: E("outline|outline-none|outline-dashed|outline-dotted|outline-double"),
+    outlineW: P("outline", "\\d+|\\[\\d+(?:\\.\\d+)?px\\]", { arb: false }),
+    outlineColor: C("outline"),
+    outlineOffset: P("outline-offset", "\\d+|\\[\\d+(?:\\.\\d+)?px\\]", { arb: false }),
+    flipX: E("-scale-x-100"), // a mirror image: the one scale class that works in Tailwind 3 and 4 alike
+    flipY: E("-scale-y-100"),
+    translateX: P("translate-x", `${STEP}|full|\\d+/\\d+`, { neg: true }),
+    translateY: P("translate-y", `${STEP}|full|\\d+/\\d+`, { neg: true }),
+    // motion and interaction
+    transition: { re: /^transition(?:-(none|all|colors|opacity|shadow|transform))?$/, read: (m) => m[1] || "default", build: (v) => (v === "default" ? "transition" : `transition-${v}`) },
+    duration: P("duration", "\\d+"),
+    ease: E("ease-(?:linear|in|out|in-out)"),
+    delay: P("delay", "\\d+"),
+    cursor: E("cursor-(?:pointer|default|text|move|not-allowed|wait|grab|grabbing|crosshair|help|auto)"),
+    pointerEvents: E("pointer-events-(?:none|auto)"),
+    userSelect: E("select-(?:none|text|all|auto)"),
+};
+
+export const BREAKPOINTS = ["", "sm", "md", "lg", "xl", "2xl"];
+export const STATES = ["", "hover", "focus", "active", "disabled", "dark", "group-hover", "focus-within", "first", "last", "odd", "even"];
+export const BREAKPOINT_WIDTH = { "": 390, sm: 640, md: 768, lg: 1024, xl: 1280, "2xl": 1536 };
+
+const split = (str) => String(str || "").split(/\s+/).filter(Boolean);
+
+/** "md:hover:bg-red-500" -> { variant: "md:hover:", base: "bg-red-500" } (ignores colons inside [...]) */
+export function parseToken(tok) {
+    let depth = 0, cut = -1;
+    for (let i = 0; i < tok.length; i++) {
+        if (tok[i] === "[") depth++;
+        else if (tok[i] === "]") depth--;
+        else if (tok[i] === ":" && depth === 0) cut = i;
+    }
+    return cut === -1 ? { variant: "", base: tok } : { variant: tok.slice(0, cut + 1), base: tok.slice(cut + 1) };
+}
+
+/** Current value of a group for one variant, or null. */
+export function getGroup(classes, key, variant = "") {
+    const g = GROUPS[key];
+    for (const tok of split(classes)) {
+        const { variant: v, base } = parseToken(tok);
+        if (v !== variant) continue;
+        const m = base.match(g.re);
+        if (m) return { token: tok, value: g.read(m) };
+    }
+    return null;
+}
+
+/** Sets (or, with an empty value, clears) a group for one variant. Returns the new class string, or null if the value is invalid. */
+export function setGroup(classes, key, value, variant = "") {
+    const g = GROUPS[key];
+    let built = "";
+    if (value !== "" && value !== null && value !== undefined) {
+        built = g.build(value);
+        if (!g.re.test(built)) return null;
+    }
+    // the new class takes the old one's place (or goes at the end), so the rest of the list keeps its order
+    const out = [];
+    let at = -1;
+    for (const tok of split(classes)) {
+        const { variant: v, base } = parseToken(tok);
+        if (v === variant && g.re.test(base)) { if (at === -1) at = out.length; continue; }
+        out.push(tok);
+    }
+    if (built) out.splice(at === -1 ? out.length : at, 0, variant + built);
+    return out.join(" ");
+}
+
+export const ALL_GROUP_KEYS = Object.keys(GROUPS);

package/core/design-spec.js

@@ -0,0 +1,303 @@
+// @ts-check
+// The design spec: a design as JSON an AI can read and target reliably, and back to HTML. It replaces the old element
+// description (element-description/index.js), which only ran in the browser and lost spaces, comments and most SVG.
+//
+// It works on a tree the HTML was already read into: the browser's own (DOMParser) or the server's (node-html-parser).
+// Both are read through the few helpers below, so the browser and the server number elements the same way.
+//
+// Elements are numbered in document order (n1, n2...) every time a spec is made. The ids belong to that version of the
+// design: a patch says which version it was read from (design-spec.service.js), so an id never lands on the wrong element.
+import { GROUPS, parseToken } from "./class-groups.js";
+
+/**
+ * Class properties by variant: { base: { p: "6" }, md: { p: "8" }, "md:hover": { bgColor: "blue-600" } }.
+ * The keys inside are class groups (class-groups.js), the values what the group reads and builds.
+ * @typedef {Record<string, Record<string, string>>} Props
+ */
+/**
+ * One element of a spec, or a run of text between elements ({ text } alone).
+ * @typedef {object} SpecNode
+ * @property {string} [id] n1, n2... in document order; only for elements
+ * @property {string} [tag]
+ * @property {string} [role] title, button, card... (simple rules)
+ * @property {Props} [props] classes read as properties
+ * @property {string[]} [raw] classes no group reads back exactly
+ * @property {string} [css] the style attribute
+ * @property {Record<string, string>} [attrs]
+ * @property {string} [text]
+ * @property {SpecNode[]} [children]
+ * @property {string} [svg] an <svg>'s inner markup
+ * @property {number} [svgChars] its length, when the drawing is left out
+ */
+/**
+ * @typedef {object} Assets
+ * @property {string} [css]
+ * @property {string} [js]
+ * @property {string[]} [stylesheets]
+ * @property {string[]} [scripts]
+ */
+/**
+ * @typedef {object} Spec
+ * @property {Record<string, string[]>} tokens
+ * @property {Assets} assets
+ * @property {SpecNode[]} tree
+ * @property {string} [id]
+ * @property {string} [title]
+ * @property {number} [version]
+ * @property {string} [kind]
+ * @property {string} [warning]
+ */
+
+// ── Reading either tree ──────────────────────────────────────────────────────
+const tagOf = (n) => String(n.localName || n.rawTagName || "").toLowerCase();
+const attrsOf = (n) => {
+    const a = n.attributes;
+    if (!a) return {};
+    if (typeof a.length === "number") return Object.fromEntries(Array.from(a, (x) => [x.name, x.value])); // the browser's NamedNodeMap
+    return { ...a }; // node-html-parser: already { name: value }
+};
+const textOf = (n) => (n.data !== undefined ? n.data : n.text); // a text node's decoded text
+const rawOf = (n) => (n.rawText !== undefined ? n.rawText : n.textContent); // <style>/<script> content, as written
+const innerOf = (n) => n.innerHTML;
+const kidsOf = (n) => Array.from(n.childNodes || []);
+const ELEMENT = 1, TEXT = 3;
+
+/** Head-only and asset elements: never part of the tree (their content goes to `assets`). */
+const SKIP = new Set(["head", "style", "script", "link", "meta", "title", "base", "noscript", "template"]);
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"]);
+/** Elements whose text is kept exactly as written (spaces and line breaks matter). */
+const EXACT = new Set(["pre", "textarea", "code"]);
+const INLINE = new Set(["a", "abbr", "b", "br", "button", "code", "em", "i", "img", "input", "kbd", "label", "mark", "q", "s", "select", "small", "span", "strong", "sub", "sup", "svg", "time", "u", "textarea"]);
+
+/** The nodes a design's content starts at: the <body>'s children, or the top level for a fragment. */
+export function contentRoots(root) {
+    const body = root.body || (root.querySelector && root.querySelector("body"));
+    return kidsOf(body || root);
+}
+
+/**
+ * Visits every element of the tree in document order with its id (n1, n2...). An <svg> is one element: what's inside it
+ * has no ids. The spec builder and the patch engine both number elements with this, so their ids always agree.
+ */
+export function walkElements(roots, visit) {
+    let count = 0;
+    const go = (n, parentId) => {
+        if (n.nodeType !== ELEMENT || SKIP.has(tagOf(n))) return;
+        const id = `n${++count}`;
+        const into = visit(n, id, parentId) !== false;
+        if (into && tagOf(n) !== "svg") kidsOf(n).forEach((k) => go(k, id));
+    };
+    roots.forEach((r) => go(r, null));
+}
+
+// ── Classes as properties ────────────────────────────────────────────────────
+const GROUP_KEYS = Object.keys(GROUPS);
+/** "md:hover:" -> "md:hover", "" -> "base" */
+const atOf = (variant) => (variant ? variant.slice(0, -1) : "base");
+
+/**
+ * Splits a class list into properties by class group and variant ({ base: { p: "6" }, md: { p: "8" } }) and the classes
+ * no group reads back exactly (`raw`). Nothing is lost: every class is in one or the other.
+ */
+/** @param {string | null | undefined} classes @returns {{ props: Props, raw: string[] }} */
+export function readClasses(classes) {
+    /** @type {Props} */
+    const props = {};
+    /** @type {string[]} */
+    const raw = [];
+    for (const tok of String(classes || "").split(/\s+/).filter(Boolean)) {
+        const { variant, base } = parseToken(tok);
+        let placed = false;
+        for (const key of GROUP_KEYS) {
+            const m = base.match(GROUPS[key].re);
+            if (!m) continue;
+            const value = GROUPS[key].read(m);
+            const at = atOf(variant);
+            // only when writing it back gives the same class, and the variant doesn't already have one from this group
+            if (GROUPS[key].build(value) === base && !(props[at] && key in props[at])) {
+                (props[at] = props[at] || {})[key] = value;
+                placed = true;
+            }
+            break;
+        }
+        if (!placed) raw.push(tok);
+    }
+    return { props, raw };
+}
+
+/** The class list for properties and raw classes: the reverse of readClasses. */
+/** @param {Props} [props] @param {string[]} [raw] @returns {string} */
+export function writeClasses(props = {}, raw = []) {
+    const out = [];
+    const ats = Object.keys(props).sort((a, b) => (a === "base" ? -1 : b === "base" ? 1 : 0));
+    for (const at of ats) {
+        const variant = at === "base" ? "" : `${at}:`;
+        for (const [key, value] of Object.entries(props[at] || {})) {
+            if (!GROUPS[key]) throw new Error(`Unknown property "${key}"`);
+            const built = GROUPS[key].build(value);
+            if (!GROUPS[key].re.test(built)) throw new Error(`"${value}" is not a valid ${key}`);
+            out.push(variant + built);
+        }
+    }
+    return [...out, ...raw].join(" ");
+}
+
+// ── Roles: what an element is for, by simple rules ───────────────────────────
+const hasAny = (props, keys) => Object.values(props).some((p) => keys.some((k) => k in p));
+function roleOf(tag, attrs, props) {
+    if (/^h[1-6]$/.test(tag)) return "title";
+    if (tag === "svg") return "icon";
+    if (tag === "img" || tag === "picture" || tag === "video") return "media";
+    if (tag === "button" || (tag === "input" && /^(submit|button|reset)$/i.test(attrs.type || ""))) return "button";
+    if (tag === "a") return hasAny(props, ["bgColor", "borderWidth"]) && hasAny(props, ["px", "py", "p"]) ? "button" : "link";
+    if (tag === "input" || tag === "select" || tag === "textarea") return "field";
+    if (tag === "p" || tag === "blockquote") return "text";
+    if (tag === "ul" || tag === "ol") return "list";
+    if (tag === "li") return "item";
+    if (["nav", "header", "footer", "main", "form", "section", "article", "aside", "label", "table"].includes(tag)) return tag;
+    if (tag === "div") {
+        if (hasAny(props, ["radius", "borderWidth", "shadow"]) && hasAny(props, ["p", "px", "py"])) return "card";
+        if (props.base && props.base.mx === "auto" && "maxW" in props.base) return "container";
+        if (hasAny(props, ["display"]) && Object.values(props).some((p) => /flex|grid/.test(p.display || ""))) return "layout";
+    }
+    return undefined;
+}
+
+// ── HTML -> spec ─────────────────────────────────────────────────────────────
+const squash = (s) => s.replace(/\s+/g, " ");
+
+function describe(el, id, nextId, opts) {
+    const tag = tagOf(el);
+    const attrs = attrsOf(el);
+    const { props, raw } = readClasses(attrs.class);
+    const node = { id, tag };
+    const role = roleOf(tag, attrs, props);
+    if (role) node.role = role;
+    delete attrs.class;
+    if (attrs.style !== undefined) { node.css = attrs.style; delete attrs.style; }
+    if (Object.keys(attrs).length) node.attrs = attrs;
+    if (Object.keys(props).length) node.props = props;
+    if (raw.length) node.raw = raw;
+    if (tag === "svg") {
+        // an icon's drawing: in full, or (for reading only) just its size, since nothing targets what's inside it
+        if (opts.svg === false) node.svgChars = innerOf(el).length;
+        else node.svg = innerOf(el);
+        return node;
+    }
+    if (VOID.has(tag)) return node;
+
+    const kids = kidsOf(el).filter((k) => k.nodeType === ELEMENT || k.nodeType === TEXT);
+    const exact = EXACT.has(tag);
+    if (kids.every((k) => k.nodeType === TEXT)) {
+        const t = kids.map(textOf).join("");
+        const shown = exact ? t : squash(t).trim();
+        if (shown) node.text = shown;
+        return node;
+    }
+    const children = [];
+    kids.forEach((k, i) => {
+        if (k.nodeType === ELEMENT) {
+            if (!SKIP.has(tagOf(k))) children.push(describe(k, nextId(), nextId, opts));
+            return;
+        }
+        const t = exact ? textOf(k) : squash(textOf(k));
+        if (t.trim()) children.push({ text: t }); // its edge spaces stay: "Hello <b>you</b>" needs the one before <b>
+        else {
+            // a space between two inline elements shows on the page ("<b>Hello</b> <i>world</i>"): keep it
+            const prev = kids[i - 1], next = kids[i + 1];
+            if (prev && next && prev.nodeType === ELEMENT && next.nodeType === ELEMENT && INLINE.has(tagOf(prev)) && INLINE.has(tagOf(next))) children.push({ text: " " });
+        }
+    });
+    if (children.length) node.children = children;
+    return node;
+}
+
+/** The design tokens it uses: the values that recur, most used first. */
+function tokensOf(tree) {
+    const buckets = { colors: new Map(), fontSizes: new Map(), radius: new Map(), spacing: new Map(), shadows: new Map() };
+    const add = (b, v) => buckets[b].set(v, (buckets[b].get(v) || 0) + 1);
+    const visit = (n) => {
+        for (const p of Object.values(n.props || {})) {
+            for (const [k, v] of Object.entries(p)) {
+                if (/Color$|^grad(From|Via|To)$|^fill$|^stroke$/.test(k)) add("colors", v);
+                else if (k === "fontSize") add("fontSizes", v);
+                else if (/^radius/.test(k)) add("radius", v);
+                else if (/^(p|px|py|pt|pr|pb|pl|m|mx|my|mt|mr|mb|ml|gap|gapX|gapY|spaceX|spaceY)$/.test(k)) add("spacing", v);
+                else if (k === "shadow") add("shadows", v);
+            }
+        }
+        (n.children || []).forEach(visit);
+    };
+    tree.forEach(visit);
+    /** @type {Record<string, string[]>} */
+    const out = {};
+    for (const [k, m] of Object.entries(buckets)) {
+        const top = [...m.entries()].sort((a, b) => b[1] - a[1]).slice(0, 12).map(([v]) => v);
+        if (top.length) out[k] = top;
+    }
+    return out;
+}
+
+/** <style>, inline <script>, and the stylesheets and scripts it loads, as written. */
+function assetsOf(root) {
+    const all = (sel) => Array.from(root.querySelectorAll(sel));
+    const css = all("style").map(rawOf).map((s) => s.trim()).filter(Boolean).join("\n\n");
+    const js = all("script").filter((s) => !attrsOf(s).src).map(rawOf).map((s) => s.trim()).filter(Boolean).join("\n\n");
+    const stylesheets = all("link[href]").filter((l) => /stylesheet/i.test(attrsOf(l).rel || "")).map((l) => attrsOf(l).href);
+    const scripts = all("script[src]").map((s) => attrsOf(s).src);
+    /** @type {Assets} */
+    const out = {};
+    if (css) out.css = css;
+    if (js) out.js = js;
+    if (stylesheets.length) out.stylesheets = stylesheets;
+    if (scripts.length) out.scripts = scripts;
+    return out;
+}
+
+/** In the browser: HTML text read by the browser's own parser, ready for toSpec. (The server uses node-html-parser.) */
+export const readHtmlInBrowser = (html) => new DOMParser().parseFromString(String(html || ""), "text/html");
+
+/**
+ * A design (already read into a tree) as a spec: { tokens, assets, tree }. With { svg: false }, icons carry only their
+ * size (svgChars) instead of their drawing: smaller to read, but toHtml can't rebuild the icons from it.
+ */
+/** @param {any} root a read tree @param {{ svg?: boolean }} [opts] @returns {Spec} */
+export function toSpec(root, opts = {}) {
+    let count = 0;
+    const nextId = () => `n${++count}`;
+    const tree = contentRoots(root).filter((n) => n.nodeType === ELEMENT && !SKIP.has(tagOf(n))).map((n) => describe(n, nextId(), nextId, opts));
+    return { tokens: tokensOf(tree), assets: assetsOf(root), tree };
+}
+
+// ── spec -> HTML ─────────────────────────────────────────────────────────────
+const escText = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const escAttr = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+const TAG_RE = /^[a-z][a-z0-9-]*$/;
+
+function nodeHtml(n) {
+    if (n.text !== undefined && !n.tag) return escText(n.text);
+    if (!TAG_RE.test(n.tag || "")) throw new Error(`Invalid tag "${n.tag}"`);
+    const cls = writeClasses(n.props, n.raw);
+    const attrs = { ...(n.attrs || {}) };
+    if (cls) attrs.class = cls;
+    if (n.css) attrs.style = n.css;
+    const open = `<${n.tag}${Object.entries(attrs).map(([k, v]) => (v === "" ? ` ${k}` : ` ${k}="${escAttr(v)}"`)).join("")}>`;
+    if (VOID.has(n.tag)) return open;
+    const inner = n.tag === "svg" ? n.svg || "" : n.text !== undefined ? escText(n.text) : (n.children || []).map(nodeHtml).join("");
+    return `${open}${inner}</${n.tag}>`;
+}
+
+/** A spec (or a list of spec nodes) as HTML, with its <style> and <script> when it has them. */
+/** @param {Spec | SpecNode[]} spec @returns {string} */
+export function toHtml(spec) {
+    const tree = Array.isArray(spec) ? spec : spec.tree || [];
+    const body = tree.map(nodeHtml).join("\n");
+    const a = Array.isArray(spec) ? {} : spec.assets || {};
+    return [
+        ...(a.stylesheets || []).map((h) => `<link rel="stylesheet" href="${escAttr(h)}">`),
+        a.css ? `<style>\n${a.css}\n</style>` : "",
+        body,
+        ...(a.scripts || []).map((s) => `<script src="${escAttr(s)}"></script>`),
+        a.js ? `<script>\n${a.js}\n</script>` : "",
+    ].filter(Boolean).join("\n");
+}