pac-vector 0.1.0__py3-none-any.whl

pac_vector/document.py

@@ -0,0 +1,1375 @@
+"""Virtual documents (one per "window") and every edit operation.
+
+Each mutating method is wrapped by @mutation: it snapshots the document first,
+rolls back if anything raises (so a failed call never leaves a half-edit), and
+on success pushes one undo step and notifies the preview. Mutating methods
+return (summary, touched_ids); the decorator returns just the summary.
+"""
+
+from __future__ import annotations
+
+import copy
+import difflib
+import functools
+import gzip
+import os
+import re
+import threading
+import uuid
+from pathlib import Path
+
+from lxml import etree
+
+from . import render as R
+from ._xml import (
+    ELIDED_MARK,
+    INK_GROUPMODE,
+    INK_LABEL,
+    INK_NS,
+    SODI_INSENSITIVE,
+    SODI_NS,
+    URL_REF,
+    EditError,
+    attr_name,
+    children,
+    el_ctm,
+    fmt,
+    from_bytes,
+    get_prop,
+    href,
+    inv,
+    is_el,
+    is_ident,
+    is_svg,
+    iter_els,
+    local,
+    mul,
+    new_root,
+    parent_ctm,
+    parse_document,
+    parse_fragment,
+    parse_length,
+    parse_style,
+    parse_transform,
+    prepend_transform,
+    q,
+    refs_of,
+    rewrite_refs,
+    same,
+    sanitize,
+    short_attr,
+    style_str,
+    apply,
+)
+
+DEFS_TAGS = {
+    "linearGradient", "radialGradient", "pattern", "filter", "marker",
+    "symbol", "clipPath", "mask", "style",
+}
+NON_DRAWABLE = {"defs", "namedview", "metadata", "title", "desc", "style", "script"}
+AUTO_ID_SKIP = {"stop", "tspan", "title", "desc", "metadata", "style", "defs"}
+CONTAINERS = {"svg", "g", "a", "switch", "symbol", "defs", "mask", "clipPath", "pattern", "marker"}
+CLIP_SHAPES = {"rect", "circle", "ellipse", "line", "polyline", "polygon", "path", "text", "use"}
+TEXTUAL = {"text", "tspan", "textPath", "title", "desc"}
+INHERITED = (
+    "fill", "fill-opacity", "fill-rule", "stroke", "stroke-width", "stroke-opacity",
+    "stroke-linecap", "stroke-linejoin", "stroke-dasharray", "stroke-dashoffset",
+    "stroke-miterlimit", "font-family", "font-size", "font-weight", "font-style",
+    "text-anchor", "color", "visibility", "paint-order", "clip-rule",
+)
+GEOM = {
+    "rect": ("x", "y", "width", "height", "rx"),
+    "circle": ("cx", "cy", "r"),
+    "ellipse": ("cx", "cy", "rx", "ry"),
+    "line": ("x1", "y1", "x2", "y2"),
+    "polyline": ("points",),
+    "polygon": ("points",),
+    "path": ("d",),
+    "text": ("x", "y"),
+    "image": ("x", "y", "width", "height", "href"),
+    "use": ("href", "x", "y", "width", "height"),
+    "linearGradient": ("x1", "y1", "x2", "y2", "gradientUnits", "href"),
+    "radialGradient": ("cx", "cy", "r", "fx", "fy", "gradientUnits", "href"),
+    "pattern": ("x", "y", "width", "height", "patternUnits"),
+    "stop": ("offset",),
+    "mask": ("mask-type",),
+}
+PAINT = (
+    "fill", "stroke", "stroke-width", "opacity", "fill-opacity", "stroke-opacity",
+    "font-size", "font-family", "stop-color", "stop-opacity", "mask", "clip-path", "filter",
+    "marker-start", "marker-end",
+)
+UNITS = ("px", "mm", "cm", "in", "pt", "pc")
+MAX_HISTORY = 100
+MAX_OUTLINE_LINES = 400
+MAX_XML_CHARS = 60_000
+_ID_OK = re.compile(r"^[A-Za-z_][\w.\-]*$")
+
+
+def is_layer(el) -> bool:
+    return is_el(el) and local(el) == "g" and el.get(INK_GROUPMODE) == "layer"
+
+
+def desc(el) -> str:
+    if el is None:
+        return "?"
+    if is_layer(el):
+        return f'layer "{el.get(INK_LABEL) or ""}" #{el.get("id")}'
+    eid = el.get("id")
+    return f"{local(el)}#{eid}" if eid else f"<{local(el)}>"
+
+
+def short_val(v: str, limit: int = 48) -> str:
+    if v.startswith("data:"):
+        head = v.split(",", 1)[0]
+        return f"{head}…({len(v) / 1024:.1f}kB)"
+    v = " ".join(v.split())
+    return v if len(v) <= limit else f"{v[: limit - 4]}…({len(v)})"
+
+
+def parse_pos(p: str | None) -> tuple[str | None, str | None]:
+    if p is None or not str(p).strip():
+        return None, None
+    p = str(p).strip()
+    if p in ("top", "bottom", "up", "down"):
+        return p, None
+    m = re.match(r"^(before|after)\s*[:=]\s*#?(.+)$", p)
+    if m:
+        return m.group(1), m.group(2).strip()
+    raise EditError("position must be top | bottom | up | down | before:<id> | after:<id>")
+
+
+def nice_matrix(m) -> str:
+    a, b, c, d, e, f = m
+    if abs(a - 1) < 1e-9 and abs(b) < 1e-9 and abs(c) < 1e-9 and abs(d - 1) < 1e-9:
+        return f"translate({fmt(e)},{fmt(f)})"
+    return "matrix(" + ",".join(fmt(x) for x in m) + ")"
+
+
+def pretty(el, level: int = 0) -> None:
+    """Indent containers only. Never touches text-bearing elements, where added
+    whitespace would change rendering."""
+    if local(el) in TEXTUAL or local(el) == "style":
+        return
+    kids = list(el)
+    if not kids or (el.text and el.text.strip()):
+        return
+    if any(k.tail and k.tail.strip() for k in kids):
+        return
+    pad = "\n" + "  " * (level + 1)
+    el.text = pad
+    for k in kids:
+        k.tail = pad
+        if is_el(k):
+            pretty(k, level + 1)
+    kids[-1].tail = "\n" + "  " * level
+
+
+def elide(root) -> None:
+    for e in iter_els(root):
+        for k, v in list(e.attrib.items()):
+            if v.startswith("data:") and len(v) > 300:
+                e.set(k, f"{v[:40]}{ELIDED_MARK} {len(v) - 40} chars⟫")
+
+
+def resolve_path(p: str) -> Path:
+    P = Path(os.path.expandvars(p)).expanduser()
+    if not P.is_absolute():
+        P = Path(os.environ.get("PAC_VECTOR_ROOT") or os.getcwd()) / P
+    return P.resolve()
+
+
+def mutation(fn):
+    @functools.wraps(fn)
+    def wrapper(self: "Document", *a, **kw):
+        with self.lock:
+            snap = self._snap()
+            try:
+                summary, touched = fn(self, *a, **kw)
+            except BaseException:
+                self._restore(snap)
+                raise
+            self.history.append(snap)
+            del self.history[:-MAX_HISTORY]
+            self.version += 1
+            self.dirty = True
+            self.touched = [t for t in touched if t]
+            if self.on_change:
+                self.on_change(self, summary)
+            return summary
+
+    return wrapper
+
+
+class Document:
+    def __init__(self, doc_id, name, root, lock, on_change=None, path=None):
+        self.id = doc_id
+        self.name = name
+        self.root = root
+        self.lock = lock
+        self.on_change = on_change
+        self.path = path
+        self.background: str | None = None
+        self.current_layer: str | None = None
+        self.history: list[tuple[bytes, dict]] = []
+        self.version = 0
+        self.dirty = False
+        self.touched: list[str] = []
+        self._counters: dict[str, int] = {}
+
+    # ── snapshots ───────────────────────────────────────────────────────────
+    def _snap(self):
+        props = {"name": self.name, "background": self.background, "current_layer": self.current_layer}
+        return etree.tostring(self.root), props
+
+    def _restore(self, snap):
+        data, props = snap
+        self.root = from_bytes(data)
+        self.name = props["name"]
+        self.background = props["background"]
+        self.current_layer = props["current_layer"]
+
+    # ── lookup ──────────────────────────────────────────────────────────────
+    def ids(self) -> set[str]:
+        return {e.get("id") for e in iter_els(self.root) if e.get("id")}
+
+    def find(self, eid: str):
+        r = self.root.xpath("//*[@id=$i]", i=eid)
+        return r[0] if r else None
+
+    def get(self, ref: str):
+        ref = str(ref).strip().lstrip("#")
+        if ref == "root":
+            return self.root
+        el = self.find(ref)
+        if el is not None:
+            return el
+        named = [l for l in self.layers() if l.get(INK_LABEL) == ref]
+        if len(named) == 1:
+            return named[0]
+        close = difflib.get_close_matches(ref, sorted(self.ids()), 5, 0.5)
+        hint = f"; did you mean {', '.join('#' + c for c in close)}?" if close else "; inspect lists the ids"
+        raise EditError(f"no element #{ref} in {self.id}{hint}")
+
+    def targets(self, ids) -> list:
+        if not ids:
+            raise EditError("ids is empty")
+        if isinstance(ids, str):
+            ids = [ids]
+        found = []
+        for i in ids:
+            el = self.get(i)
+            if el not in found:
+                found.append(el)
+        order = {e: n for n, e in enumerate(self.root.iter())}
+        return sorted(found, key=lambda e: order.get(e, 0))
+
+    def layers(self) -> list:
+        return [e for e in iter_els(self.root) if is_layer(e)]
+
+    def namedview(self):
+        for c in children(self.root):
+            if local(c) == "namedview":
+                return c
+        nv = etree.SubElement(self.root, f"{{{SODI_NS}}}namedview")
+        self.root.insert(0, nv)
+        nv.set("id", "namedview")
+        nv.set("pagecolor", "#ffffff")
+        nv.set(f"{{{INK_NS}}}pageopacity", "0")
+        return nv
+
+    def defs(self):
+        for c in children(self.root):
+            if local(c) == "defs":
+                return c
+        d = etree.SubElement(self.root, q("defs"))
+        self.root.insert(self._drawable_start(self.root), d)
+        d.set("id", self._auto("defs", self.ids()))
+        return d
+
+    def _drawable_start(self, parent) -> int:
+        i = 0
+        for c in parent:
+            if is_el(c) and is_svg(c) and local(c) not in NON_DRAWABLE:
+                break
+            i += 1
+        return i
+
+    def current(self):
+        if self.current_layer:
+            el = self.find(self.current_layer)
+            if el is not None and is_layer(el):
+                return el
+        lays = [c for c in children(self.root) if is_layer(c)]
+        if lays:
+            return lays[-1]
+        return self._new_layer("Layer 1", self.root)
+
+    def container(self, ref):
+        if ref is None:
+            return self.current()
+        el = self.get(ref)
+        if local(el) not in CONTAINERS:
+            raise EditError(
+                f"{desc(el)} is not a container; to place next to it use position='after:{el.get('id')}'"
+            )
+        return el
+
+    # ── ids ─────────────────────────────────────────────────────────────────
+    def _auto(self, base: str, taken: set[str]) -> str:
+        n = self._counters.get(base, 0) + 1
+        while f"{base}-{n}" in taken:
+            n += 1
+        self._counters[base] = n
+        return f"{base}-{n}"
+
+    def _unique(self, eid: str, taken: set[str]) -> str:
+        m = re.match(r"^(.*?)-(\d+)$", eid)
+        return self._auto(m.group(1) if m else eid, taken)
+
+    def _wants_id(self, e) -> bool:
+        ln = local(e)
+        return is_svg(e) and ln not in AUTO_ID_SKIP and not ln.startswith("fe")
+
+    def assign_ids(self, tops, taken: set[str] | None = None) -> dict[str, str]:
+        if taken is None:
+            # tops may already sit in this tree (import, a mask source being moved):
+            # their own ids must not count as taken, or they'd rename themselves.
+            inside = {e for t in tops for e in iter_els(t)}
+            taken = {e.get("id") for e in iter_els(self.root) if e.get("id") and e not in inside}
+        renames: dict[str, str] = {}
+        for top in tops:
+            for e in iter_els(top):
+                if not is_svg(e) or e is self.root:
+                    continue
+                eid = e.get("id")
+                if eid:
+                    if eid in taken:
+                        new = self._unique(eid, taken)
+                        renames[eid] = new
+                        e.set("id", new)
+                    taken.add(e.get("id"))
+                elif self._wants_id(e):
+                    new = self._auto("layer" if is_layer(e) else local(e), taken)
+                    e.set("id", new)
+                    taken.add(new)
+        rewrite_refs(tops, renames)
+        return renames
+
+    def _rename(self, e, new) -> None:
+        new = str(new).strip().lstrip("#")
+        if not _ID_OK.match(new):
+            raise EditError(f"invalid id '{new}' (letters, digits, _ . -; must not start with a digit)")
+        old = e.get("id")
+        if new == old:
+            return
+        if self.find(new) is not None:
+            raise EditError(f"id #{new} is already taken")
+        e.set("id", new)
+        if old:
+            rewrite_refs([self.root], {old: new})
+            if self.current_layer == old:
+                self.current_layer = new
+
+    # ── checks & notes ──────────────────────────────────────────────────────
+    def check_unlocked(self, el) -> None:
+        for a in [el, *el.iterancestors()]:
+            if a.get(SODI_INSENSITIVE) == "true":
+                inside = "" if a is el else f" (inside locked {desc(a)})"
+                raise EditError(
+                    f"{desc(el)} is locked{inside}; unlock with update(ids=['{a.get('id')}'], locked=false)"
+                )
+
+    def dangling(self, tops) -> list[str]:
+        ids = self.ids()
+        out = []
+        for top in tops:
+            for e in iter_els(top):
+                for r in sorted(refs_of(e) - ids):
+                    out.append(f"{desc(e)} references missing #{r}")
+        return out
+
+    def _place(self, parent, els, kind, ref) -> None:
+        if kind in (None, "top"):
+            for e in els:
+                parent.append(e)
+        elif kind == "bottom":
+            i = self._drawable_start(parent)
+            for n, e in enumerate(els):
+                parent.insert(i + n, e)
+        elif kind == "before":
+            r = self.get(ref)
+            for e in els:
+                r.addprevious(e)
+        elif kind == "after":
+            anchor = self.get(ref)
+            for e in els:
+                anchor.addnext(e)
+                anchor = e
+        else:
+            raise EditError(f"position '{kind}' is not valid here")
+
+    def _new_layer(self, label, parent, kind="top", ref=None):
+        g = etree.SubElement(parent, q("g"))
+        g.set(INK_GROUPMODE, "layer")
+        g.set(INK_LABEL, label)
+        g.set("id", self._auto("layer", self.ids()))
+        if kind not in (None, "top"):
+            self._place(parent, [g], kind, ref)
+        return g
+
+    def _route(self, els) -> tuple[list, list]:
+        """Split parsed elements into drawing elements and <defs> content."""
+        body, defs_added = [], []
+        for e in els:
+            if local(e) == "defs":
+                for c in children(e):
+                    self.defs().append(c)
+                    defs_added.append(c)
+            elif local(e) in DEFS_TAGS:
+                self.defs().append(e)
+                defs_added.append(e)
+            else:
+                body.append(e)
+        return body, defs_added
+
+    def normalise_layers(self) -> int:
+        """If the drawing has no layers, wrap its loose elements into 'Layer 1'."""
+        drawables = [c for c in children(self.root) if is_svg(c) and local(c) not in NON_DRAWABLE]
+        if any(is_layer(c) for c in drawables):
+            return 0
+        lay = self._new_layer("Layer 1", self.root)
+        for c in drawables:
+            lay.append(c)
+        return len(drawables)
+
+    def set_background(self, bg: str | None) -> None:
+        self.background = bg
+        nv = self.namedview()
+        if bg:
+            nv.set("pagecolor", bg)
+            nv.set(f"{{{INK_NS}}}pageopacity", "1")
+        else:
+            nv.set(f"{{{INK_NS}}}pageopacity", "0")
+
+    def _center(self, el) -> tuple[float, float]:
+        """Visual center of `el`, in its parent's coordinates."""
+        box = R.measure(R.isolate(self.root, {el.get("id")}))
+        if not box:
+            raise EditError(f"{desc(el)} has no visible pixels to find a center; pass origin=[x, y]")
+        cx, cy = box[0] + box[2] / 2, box[1] + box[3] / 2
+        return apply(inv(parent_ctm(el)), cx, cy)
+
+    def _move(self, el, parent, kind, ref) -> None:
+        """Move el keeping its on-canvas position (compensates parent transforms)."""
+        old = parent_ctm(el)
+        new = el_ctm(parent)
+        self._place(parent, [el], kind, ref)
+        if not same(old, new):
+            prepend_transform(el, nice_matrix(mul(inv(new), old)))
+
+    # ── info ────────────────────────────────────────────────────────────────
+    def element_count(self) -> int:
+        n = 0
+        for e in iter_els(self.root):
+            if e is self.root or not is_svg(e) or local(e) in NON_DRAWABLE:
+                continue
+            if any(local(a) == "defs" for a in e.iterancestors()):
+                continue
+            n += 1
+        return n
+
+    def info(self) -> str:
+        r = self.root
+        lays = ", ".join(f'"{l.get(INK_LABEL)}" #{l.get("id")}' for l in self.layers()) or "none"
+        cur = self.current_layer or "-"
+        parts = [
+            f'{self.id} "{self.name}"',
+            f'{r.get("width")}×{r.get("height")}',
+            f'viewBox {r.get("viewBox") or "-"}',
+            f"bg {self.background or 'none'}",
+            f"{self.element_count()} elements",
+            f"layers {lays} (current #{cur})",
+            f"v{self.version}" + (" unsaved" if self.dirty else ""),
+        ]
+        if self.path:
+            parts.append(self.path)
+        return " · ".join(parts)
+
+    def payload(self, summary: str = "") -> dict:
+        return {
+            "type": "doc",
+            "id": self.id,
+            "name": self.name,
+            "svg": etree.tostring(self.root, encoding="unicode"),
+            "background": self.background,
+            "version": self.version,
+            "touched": self.touched,
+            "summary": summary,
+            "info": self.info(),
+        }
+
+    # ── reading ─────────────────────────────────────────────────────────────
+    def _line(self, el) -> str:
+        if not is_svg(el):
+            return short_attr(el.tag)
+        ln = local(el)
+        parts = [desc(el)]
+        label = el.get(INK_LABEL)
+        if label and not is_layer(el):
+            parts.append(f'"{label}"')
+        for a in GEOM.get(ln, ()):
+            v = href(el) if a == "href" else el.get(a)
+            if v is not None:
+                parts.append(f"{a}={short_val(v)}")
+        for p in PAINT:
+            v = get_prop(el, p)
+            if v is not None:
+                parts.append(f"{p}={short_val(v)}")
+        if ln in ("text", "textPath"):
+            t = " ".join("".join(el.itertext()).split())
+            parts.append(repr(t if len(t) <= 40 else t[:37] + "…"))
+        if el.get("transform"):
+            parts.append(f"transform={short_val(el.get('transform'))}")
+        if get_prop(el, "display") == "none":
+            parts.append("HIDDEN")
+        if el.get(SODI_INSENSITIVE) == "true":
+            parts.append("LOCKED")
+        n = len(children(el))
+        if n and ln not in ("text",):
+            parts.append(f"[{n}]")
+        return " ".join(parts)
+
+    def inspect(self, root_ref=None, depth=3, fmt_="outline") -> str:
+        with self.lock:
+            top = self.root if root_ref is None else self.get(root_ref)
+            if fmt_ == "xml":
+                clone = copy.deepcopy(top)
+                elide(clone)
+                pretty(clone)
+                s = etree.tostring(clone, encoding="unicode")
+                if len(s) > MAX_XML_CHARS:
+                    s = s[:MAX_XML_CHARS] + f"\n… truncated ({len(s)} chars); inspect a smaller root"
+                return s
+            if fmt_ != "outline":
+                raise EditError("format must be 'outline' or 'xml'")
+            lines = [self.info()] if top is self.root else [self._line(top)]
+            base = 0 if top is self.root else 1
+
+            def walk(el, d):
+                for c in children(el):
+                    if local(c) == "namedview":
+                        continue
+                    lines.append("  " * (d + base) + self._line(c))
+                    if children(c) and local(c) not in ("text",) and d + 1 < depth:
+                        walk(c, d + 1)
+
+            walk(top, 0)
+            if len(lines) > MAX_OUTLINE_LINES:
+                extra = len(lines) - MAX_OUTLINE_LINES
+                lines = lines[:MAX_OUTLINE_LINES] + [f"… {extra} more lines; inspect(root=<id>) to drill in"]
+            return "\n".join(lines)
+
+    def render(self, ids=None, scale=1.0, padding=16, background=True, isolate=False):
+        with self.lock:
+            root = copy.deepcopy(self.root)
+            els = self.targets(ids) if ids else []
+        bg = self.background if background else None
+        resdir = str(Path(self.path).parent) if self.path else None
+        if not els:
+            png, w, h, s = R.render_page(root, scale, bg, resdir)
+            return f"page {w}×{h}px (scale {s:g})", png
+        idset = {e.get("id") for e in els}
+        iso = R.isolate(root, idset)
+        box = R.measure(iso)
+        if not box:
+            raise EditError(f"nothing visible for {', '.join('#' + i for i in idset)} (hidden or transparent?)")
+        W, _ = R.size_px(root)
+        vb = R.viewbox(root)
+        ppu = W / vb[2] * scale
+        pad = padding / ppu
+        region = (box[0] - pad, box[1] - pad, box[2] + 2 * pad, box[3] + 2 * pad)
+        pw, ph = region[2] * ppu, region[3] * ppu
+        if max(pw, ph) > R.MAX_SIDE:
+            k = R.MAX_SIDE / max(pw, ph)
+            pw, ph = pw * k, ph * k
+        pw, ph = max(1, round(pw)), max(1, round(ph))
+        png = R.render_region(iso if isolate else root, region, pw, ph, bg, resdir)
+        bb = " ".join(f"{k}={fmt(round(v, 1))}" for k, v in zip("xywh", box))  # 0.1: below AA noise
+        return f"{', '.join('#' + i for i in idset)} bbox {bb} (user units) · {pw}×{ph}px", png
+
+    # ── editing ─────────────────────────────────────────────────────────────
+    @mutation
+    def add(self, markup, parent=None, position=None):
+        els = parse_fragment(markup)
+        notes = sanitize(els)
+        kind, ref = parse_pos(position)
+        if kind in ("up", "down"):
+            raise EditError("position up/down is for arrange; add takes top | bottom | before:<id> | after:<id>")
+        if kind in ("before", "after"):
+            anchor = self.get(ref)
+            cont = anchor.getparent()
+            if parent is not None and cont is not self.container(parent):
+                raise EditError(f"#{ref} is not inside #{parent}")
+        else:
+            cont = self.container(parent)
+        if cont is not self.root:
+            self.check_unlocked(cont)
+        renames = self.assign_ids(els)
+        body, defs_added = self._route(els)
+        if body:
+            self._place(cont, body, kind, ref)
+        if is_layer(cont):
+            self.current_layer = cont.get("id")
+        out = []
+        if body:
+            out.append(f"added {len(body)} to {desc(cont)}: " + ", ".join(desc(e) for e in body))
+        if defs_added:
+            out.append("defs: " + ", ".join(desc(e) for e in defs_added))
+        if renames:
+            out.append("renamed (id taken): " + ", ".join(f"{a}→{b}" for a, b in renames.items()))
+        out += self.dangling(body + defs_added) + notes
+        return "\n".join(out), [e.get("id") for e in body + defs_added]
+
+    @mutation
+    def update(self, ids, attrs=None, style=None, text=None, transform=None, label=None, hidden=None, locked=None):
+        els = self.targets(ids)
+        attrs = dict(attrs or {})
+        if not (attrs or style or text is not None or transform is not None
+                or label is not None or hidden is not None or locked is not None):
+            raise EditError("nothing to update: pass attrs, style, text, transform, label, hidden or locked")
+        if "id" in attrs and len(els) != 1:
+            raise EditError("renaming (attrs.id) takes exactly one element")
+        changed: set[str] = set()
+        for e in els:
+            if locked is not False:
+                self.check_unlocked(e)
+            for k, v in attrs.items():
+                if k == "id":
+                    self._rename(e, v)
+                    changed.add("id")
+                    continue
+                key = attr_name(k)
+                if etree.QName(key).localname == "href":  # keep one href spelling
+                    for alt in ("href", attr_name("xlink:href")):
+                        if alt != key:
+                            e.attrib.pop(alt, None)
+                if v is None:
+                    e.attrib.pop(key, None)
+                else:
+                    e.set(key, fmt(v))
+                changed.add(k)
+            if style:
+                st = parse_style(e.get("style"))
+                for k, v in style.items():
+                    if v is None:
+                        st.pop(k, None)
+                        e.attrib.pop(k, None)
+                    else:
+                        st[k] = fmt(v)
+                    changed.add(k)
+                if st:
+                    e.set("style", style_str(st))
+                else:
+                    e.attrib.pop("style", None)
+            if text is not None:
+                if local(e) not in TEXTUAL:
+                    raise EditError(f"{desc(e)} holds no text (text works on text/tspan/textPath/title/desc)")
+                for c in list(e):
+                    e.remove(c)
+                e.text = text
+                changed.add("text")
+            if transform is not None:
+                self._apply_transform(e, transform)
+                changed.add("transform")
+            if label is not None:
+                if label:
+                    e.set(INK_LABEL, label)
+                else:
+                    e.attrib.pop(INK_LABEL, None)
+                changed.add("label")
+            if hidden is not None:
+                st = parse_style(e.get("style"))
+                st.pop("display", None)
+                e.attrib.pop("display", None)
+                if hidden:
+                    st["display"] = "none"
+                if st:
+                    e.set("style", style_str(st))
+                else:
+                    e.attrib.pop("style", None)
+                changed.add("hidden")
+            if locked is not None:
+                if locked:
+                    e.set(SODI_INSENSITIVE, "true")
+                else:
+                    e.attrib.pop(SODI_INSENSITIVE, None)
+                changed.add("locked")
+        out = [f"updated {len(els)}: {', '.join(desc(e) for e in els)} ({', '.join(sorted(changed))})"]
+        out += self.dangling(els)
+        return "\n".join(out), [e.get("id") for e in els]
+
+    def _apply_transform(self, e, spec) -> None:
+        if isinstance(spec, str):
+            s = spec.strip()
+            if s and re.sub(r"(matrix|translate|scale|rotate|skewX|skewY)\s*\([^)]*\)", "", s).strip(" ,"):
+                raise EditError(f"unrecognised transform '{spec}'")
+            if s:
+                e.set("transform", s)
+            else:
+                e.attrib.pop("transform", None)
+            return
+        spec = {k: v for k, v in dict(spec).items() if v is not None}
+        mode = spec.get("mode", "append")
+        if mode not in ("append", "set"):
+            raise EditError("transform.mode must be 'append' or 'set'")
+        tr, rot, sc = spec.get("translate"), spec.get("rotate"), spec.get("scale")
+        if tr is None and rot is None and sc is None:
+            raise EditError("transform needs translate, rotate and/or scale")
+        saved = e.get("transform")
+        if mode == "set":
+            e.attrib.pop("transform", None)
+        ox = oy = 0.0
+        if rot is not None or sc is not None:
+            origin = spec.get("origin", "center")
+            if origin == "center":
+                ox, oy = self._center(e)
+            elif isinstance(origin, (list, tuple)) and len(origin) == 2:
+                ox, oy = float(origin[0]), float(origin[1])
+            else:
+                raise EditError("transform.origin must be 'center' or [x, y]")
+        parts = []
+        if tr is not None:
+            if isinstance(tr, (int, float)) or len(tr) != 2:
+                raise EditError("transform.translate must be [dx, dy]")
+            parts.append(f"translate({fmt(tr[0])},{fmt(tr[1])})")
+        if rot is not None:
+            parts.append(f"rotate({fmt(rot)},{fmt(ox)},{fmt(oy)})")
+        if sc is not None:
+            sx, sy = (sc, sc) if isinstance(sc, (int, float)) else (sc[0], sc[1])
+            if ox or oy:
+                parts.append(f"translate({fmt(ox)},{fmt(oy)}) scale({fmt(sx)},{fmt(sy)}) translate({fmt(-ox)},{fmt(-oy)})")
+            else:
+                parts.append(f"scale({fmt(sx)},{fmt(sy)})")
+        try:
+            prepend_transform(e, " ".join(parts))
+        except EditError:
+            if saved is not None:
+                e.set("transform", saved)
+            raise
+
+    @mutation
+    def replace(self, markup, target=None):
+        els = parse_fragment(markup)
+        notes = sanitize(els)
+        t = None if target is None else self.get(target)
+        if t is None or t is self.root:
+            return self._replace_all(els, notes)
+        self.check_unlocked(t)
+        if t is self.namedview():
+            raise EditError("the namedview holds document settings; use doc_set")
+        if len(els) == 1 and not els[0].get("id"):
+            els[0].set("id", t.get("id"))
+        freed = {e.get("id") for e in iter_els(t) if e.get("id")}
+        renames = self.assign_ids(els, self.ids() - freed)
+        for e in els:
+            t.addprevious(e)
+        t.getparent().remove(t)
+        out = [f"replaced #{target} with " + ", ".join(desc(e) for e in els)]
+        if renames:
+            out.append("renamed (id taken): " + ", ".join(f"{a}→{b}" for a, b in renames.items()))
+        gone = freed - self.ids()
+        for e in iter_els(self.root):
+            for r in sorted(refs_of(e) & gone):
+                out.append(f"{desc(e)} still references removed #{r}")
+        out += self.dangling(els) + notes
+        return "\n".join(out), [e.get("id") for e in els]
+
+    def _replace_all(self, els, notes):
+        if len(els) == 1 and local(els[0]) == "svg":
+            src = els[0]
+            for a in ("width", "height", "viewBox"):
+                if src.get(a):
+                    self.root.set(a, src.get(a))
+            els = children(src)
+        nv = self.namedview()
+        for c in list(self.root):
+            if c is not nv:
+                self.root.remove(c)
+        for e in els:
+            e.tail = None
+        renames = self.assign_ids(els, self.ids())
+        body, defs_added = self._route(els)
+        for e in body:
+            self.root.append(e)
+        wrapped = self.normalise_layers()
+        self.current_layer = None
+        out = [f"replaced the whole drawing: {len(body)} elements, {len(defs_added)} defs"]
+        if wrapped:
+            out.append(f'wrapped {wrapped} loose elements into layer "Layer 1"')
+        if renames:
+            out.append("renamed duplicate ids: " + ", ".join(f"{a}→{b}" for a, b in renames.items()))
+        out += self.dangling([self.root]) + notes
+        return "\n".join(out), [e.get("id") for e in body]
+
+    @mutation
+    def remove(self, ids):
+        els = self.targets(ids)
+        for e in els:
+            if e is self.root or local(e) in ("namedview", "defs"):
+                raise EditError(f"{desc(e)} can't be removed")
+            self.check_unlocked(e)
+        removed = {x.get("id") for e in els for x in iter_els(e) if x.get("id")}
+        names = [desc(e) for e in els]
+        for e in els:
+            p = e.getparent()
+            if p is not None:
+                p.remove(e)
+        if self.current_layer in removed:
+            self.current_layer = None
+        out = [f"removed {len(els)}: {', '.join(names)}"]
+        for e in iter_els(self.root):
+            for r in sorted(refs_of(e) & removed):
+                out.append(f"{desc(e)} still references removed #{r}")
+        return "\n".join(out), []
+
+    @mutation
+    def arrange(self, ids, to=None, position=None, copy_=False, offset=None):
+        els = self.targets(ids)
+        for e in els:
+            if e is self.root or local(e) in ("namedview", "defs"):
+                raise EditError(f"{desc(e)} can't be arranged")
+            if not copy_:
+                self.check_unlocked(e)
+        kind, ref = parse_pos(position)
+        dest = self.container(to) if to is not None else None
+        if dest is not None:
+            if kind in ("up", "down"):
+                raise EditError("up/down steps within the current parent; drop `to`")
+            if dest is not self.root:
+                self.check_unlocked(dest)
+            for e in els:
+                if dest is e or e in dest.iterancestors():
+                    raise EditError(f"can't move {desc(e)} into itself")
+        if ref is not None:
+            r = self.get(ref)
+            if r in els:
+                raise EditError(f"#{ref} is one of the elements being arranged")
+            if dest is not None and r.getparent() is not dest:
+                raise EditError(f"#{ref} is not a child of #{to}")
+        if kind is None and dest is None and not copy_:
+            raise EditError("nothing to do: pass to=<container> and/or position=")
+        if kind in ("up", "down") and copy_:
+            raise EditError("up/down is for moves, not copies")
+
+        if kind in ("up", "down"):
+            sel = set(els)
+            seq = reversed(els) if kind == "up" else els
+            for e in seq:
+                n = e.getnext() if kind == "up" else e.getprevious()
+                while n is not None and not is_el(n):
+                    n = n.getnext() if kind == "up" else n.getprevious()
+                if n is None or n in sel or local(n) in NON_DRAWABLE:
+                    continue
+                (n.addnext if kind == "up" else n.addprevious)(e)
+            return f"moved {kind}: {', '.join(desc(e) for e in els)}", [e.get("id") for e in els]
+
+        nodes = els
+        if copy_:
+            nodes = []
+            for e in els:
+                c = copy.deepcopy(e)
+                c.tail = None
+                nodes.append(c)
+            self.assign_ids(nodes)
+        anchor_after = self.get(ref) if kind == "after" else None
+        bottom_count: dict = {}
+        for orig, node in zip(els, nodes):
+            old = parent_ctm(orig)
+            if kind is None and dest is None:  # copy beside its original
+                orig.addnext(node)
+                continue
+            parent = dest if dest is not None else (
+                self.get(ref).getparent() if kind in ("before", "after") else orig.getparent()
+            )
+            new = el_ctm(parent)
+            if kind == "after":
+                anchor_after.addnext(node)
+                anchor_after = node
+            elif kind == "bottom":
+                i = self._drawable_start(parent) + bottom_count.get(parent, 0)
+                bottom_count[parent] = bottom_count.get(parent, 0) + 1
+                parent.insert(i, node)
+            elif kind == "before":
+                self.get(ref).addprevious(node)
+            else:
+                parent.append(node)
+            if not same(old, new):
+                prepend_transform(node, nice_matrix(mul(inv(new), old)))
+        if offset:
+            if len(offset) != 2:
+                raise EditError("offset must be [dx, dy]")
+            for node in nodes:
+                prepend_transform(node, f"translate({fmt(offset[0])},{fmt(offset[1])})")
+        where = desc(dest) if dest is not None else (f"{kind}:{ref}" if ref else (kind or "beside originals"))
+        verb = "copied" if copy_ else "moved"
+        return f"{verb} {len(nodes)} → {where}: {', '.join(desc(n) for n in nodes)}", [n.get("id") for n in nodes]
+
+    @mutation
+    def group(self, ids=None, label=None, layer=False, parent=None, position=None):
+        kind, ref = parse_pos(position)
+        if kind in ("up", "down"):
+            raise EditError("group position takes top | bottom | before:<id> | after:<id>")
+        if not ids:
+            dest = self.container(parent) if parent is not None else (self.root if layer else self.current())
+            if dest is not self.root:
+                self.check_unlocked(dest)
+            if layer:
+                n = len(self.layers()) + 1
+                g = self._new_layer(label or f"Layer {n}", dest, kind, ref)
+                self.current_layer = g.get("id")
+            else:
+                g = etree.SubElement(dest, q("g"))
+                g.set("id", self._auto("g", self.ids()))
+                if label:
+                    g.set(INK_LABEL, label)
+                if kind not in (None, "top"):
+                    self._place(dest, [g], kind, ref)
+            return f"created empty {desc(g)} in {desc(dest)}", [g.get("id")]
+        els = self.targets(ids)
+        for e in els:
+            if e is self.root or local(e) in NON_DRAWABLE:
+                raise EditError(f"{desc(e)} can't be grouped")
+            self.check_unlocked(e)
+        anchor = els[-1]
+        dest = self.container(parent) if parent is not None else anchor.getparent()
+        if dest is not self.root:
+            self.check_unlocked(dest)
+        g = etree.SubElement(dest, q("g"))
+        if kind is not None:
+            self._place(dest, [g], kind, ref)
+        elif anchor.getparent() is dest:
+            anchor.addnext(g)
+        if layer:
+            g.set(INK_GROUPMODE, "layer")
+            g.set(INK_LABEL, label or f"Layer {len(self.layers())}")
+        elif label:
+            g.set(INK_LABEL, label)
+        g.set("id", self._auto("layer" if layer else "g", self.ids()))
+        for e in els:
+            self._move(e, g, "top", None)
+        if layer:
+            self.current_layer = g.get("id")
+        return f"grouped {len(els)} into {desc(g)} in {desc(dest)}: {', '.join(desc(e) for e in els)}", [g.get("id")]
+
+    @mutation
+    def ungroup(self, ids):
+        out_ids, names = [], []
+        for g in self.targets(ids):
+            if local(g) not in ("g", "a"):
+                raise EditError(f"{desc(g)} is not a group")
+            self.check_unlocked(g)
+            for p in ("mask", "clip-path", "filter"):
+                if get_prop(g, p) not in (None, "none"):
+                    raise EditError(f"{desc(g)} has a {p}; unmask/remove it before ungrouping")
+            gtf = g.get("transform") or ""
+            inherit = {p: get_prop(g, p) for p in INHERITED if get_prop(g, p) is not None}
+            if get_prop(g, "display") == "none":
+                inherit["display"] = "none"
+            try:
+                gop = float(get_prop(g, "opacity") or 1)
+            except ValueError:
+                gop = 1.0
+            for k in list(g):
+                g.addprevious(k)
+                if not (is_el(k) and is_svg(k)) or local(k) in NON_DRAWABLE:
+                    continue
+                if gtf:
+                    prepend_transform(k, gtf)
+                for p, v in inherit.items():
+                    if get_prop(k, p) is None:
+                        k.set(p, v)
+                if gop != 1:
+                    st = parse_style(k.get("style"))
+                    try:
+                        ko = float(get_prop(k, "opacity") or 1) * gop
+                    except ValueError:
+                        ko = gop
+                    if "opacity" in st:
+                        st["opacity"] = fmt(ko)
+                        k.set("style", style_str(st))
+                    else:
+                        k.set("opacity", fmt(ko))
+                out_ids.append(k.get("id"))
+            names.append(desc(g))
+            if self.current_layer == g.get("id"):
+                self.current_layer = None
+            g.getparent().remove(g)
+        return f"ungrouped {', '.join(names)} → {len(out_ids)} elements", out_ids
+
+    def _clip_flatten(self, els) -> list:
+        out = []
+        for e in els:
+            if local(e) in ("g", "a"):
+                tf = e.get("transform") or ""
+                for c in children(e):
+                    for f in self._clip_flatten([c]):
+                        if tf:
+                            prepend_transform(f, tf)
+                        out.append(f)
+            elif local(e) in CLIP_SHAPES:
+                out.append(e)
+            elif local(e) not in ("title", "desc"):
+                raise EditError(f"<{local(e)}> can't be part of a clip; use shapes, text or <use> (or kind='mask')")
+        return out
+
+    @mutation
+    def mask(self, targets, source, kind="mask", mode="luminance"):
+        if kind not in ("mask", "clip"):
+            raise EditError("kind must be 'mask' or 'clip'")
+        if mode not in ("luminance", "alpha"):
+            raise EditError("mode must be 'luminance' or 'alpha'")
+        attr = "mask" if kind == "mask" else "clip-path"
+        tg = self.targets(targets)
+        for t in tg:
+            self.check_unlocked(t)
+            if get_prop(t, attr) not in (None, "none"):
+                raise EditError(f"{desc(t)} already has a {attr}; unmask it first")
+        notes = []
+        src = source.strip()
+        if src.startswith("<"):
+            src_els = parse_fragment(src)
+            notes = sanitize(src_els)
+            space = {id(t): parent_ctm(t) for t in tg}  # markup is drawn in each target's parent space
+            src_name = ", ".join(f"<{local(e)}>" for e in src_els)
+        else:
+            s = self.get(src)
+            if s in tg or any(a in tg for a in s.iterancestors()) or any(t in tg for t in iter_els(s)):
+                raise EditError("the mask source must not be (inside) a target")
+            if s is self.root or local(s) in NON_DRAWABLE:
+                raise EditError(f"{desc(s)} can't be a mask source")
+            self.check_unlocked(s)
+            sp = parent_ctm(s)
+            space = {id(t): sp for t in tg}
+            src_name = desc(s)
+            s.getparent().remove(s)
+            s.tail = None
+            src_els = [s]
+        groups: list[tuple] = []
+        for t in tg:
+            m = mul(inv(el_ctm(t)), space[id(t)])
+            for g in groups:
+                if same(g[0], m):
+                    g[1].append(t)
+                    break
+            else:
+                groups.append((m, [t]))
+        made = []
+        defs = self.defs()
+        for i, (m, ts) in enumerate(groups):
+            content = src_els if i == 0 else [copy.deepcopy(e) for e in src_els]
+            if kind == "clip":
+                content = self._clip_flatten(content)
+            cont = etree.SubElement(defs, q("mask" if kind == "mask" else "clipPath"))
+            for c in content:
+                cont.append(c)
+                if not is_ident(m):
+                    prepend_transform(c, nice_matrix(m))
+            if kind == "mask" and mode == "alpha":
+                cont.set("mask-type", "alpha")
+                cont.set("style", "mask-type:alpha")
+            self.assign_ids([cont])
+            for t in ts:
+                t.set(attr, f"url(#{cont.get('id')})")
+            made.append(cont)
+        what = f"{kind}" + (f" ({mode})" if kind == "mask" else "")
+        out = [
+            f"{what} from {src_name} applied to {', '.join(desc(t) for t in tg)} via "
+            + ", ".join(desc(c) for c in made)
+        ] + notes
+        return "\n".join(out), [t.get("id") for t in tg]
+
+    @mutation
+    def unmask(self, targets):
+        out_ids, lines = [], []
+        for t in self.targets(targets):
+            self.check_unlocked(t)
+            found = False
+            for attr in ("mask", "clip-path"):
+                v = get_prop(t, attr)
+                if not v or v == "none":
+                    continue
+                found = True
+                t.attrib.pop(attr, None)
+                st = parse_style(t.get("style"))
+                if attr in st:
+                    st.pop(attr)
+                    if st:
+                        t.set("style", style_str(st))
+                    else:
+                        t.attrib.pop("style", None)
+                m = URL_REF.search(v)
+                cont = self.find(m.group(1)) if m else None
+                if cont is None:
+                    lines.append(f"{desc(t)}: {attr} pointed at a missing element; attribute removed")
+                    continue
+                cid = cont.get("id")
+                shared = any(e is not t and cid in refs_of(e) for e in iter_els(self.root))
+                content = [copy.deepcopy(c) for c in children(cont)] if shared else children(cont)
+                if not shared:
+                    cont.getparent().remove(cont)
+                for c in content:
+                    c.tail = None
+                if shared:
+                    self.assign_ids(content)
+                anchor, tf = t, t.get("transform") or ""
+                for c in content:
+                    if tf:
+                        prepend_transform(c, tf)
+                    anchor.addnext(c)
+                    anchor = c
+                    out_ids.append(c.get("id"))
+                lines.append(
+                    f"released {attr} of {desc(t)}: {', '.join(desc(c) for c in content)} placed above it"
+                    + (" (mask still used elsewhere, content copied)" if shared else "")
+                )
+            if not found:
+                raise EditError(f"{desc(t)} has no mask or clip-path")
+        return "\n".join(lines), out_ids + [i for i in (targets if isinstance(targets, list) else [targets])]
+
+    @mutation
+    def set_props(self, name=None, width=None, height=None, units=None, view_box=None, background=None, fit=None):
+        r = self.root
+        out = []
+        if name:
+            self.name = name
+            out.append(f'name "{name}"')
+        cw, ch = parse_length(r.get("width")) or (None, ""), parse_length(r.get("height")) or (None, "")
+        unit = units if units is not None else (cw[1] or "px")
+        if unit not in UNITS:
+            raise EditError(f"units must be one of {', '.join(UNITS)}")
+        suffix = "" if unit == "px" else unit
+        if width is not None or height is not None or units is not None:
+            vb = R.viewbox(r)
+            ow, oh = cw[0] or vb[2], ch[0] or vb[3]
+            nw = float(width) if width is not None else ow
+            nh = float(height) if height is not None else oh
+            if nw <= 0 or nh <= 0:
+                raise EditError("width/height must be > 0")
+            if view_box is None and r.get("viewBox") and (width is not None or height is not None):
+                r.set("viewBox", " ".join(fmt(v) for v in (vb[0], vb[1], vb[2] * nw / ow, vb[3] * nh / oh)))
+            r.set("width", fmt(nw) + suffix)
+            r.set("height", fmt(nh) + suffix)
+            self.namedview().set(f"{{{INK_NS}}}document-units", unit)
+            out.append(f"size {r.get('width')}×{r.get('height')}")
+        if view_box is not None:
+            nums = [float(x) for x in re.split(r"[\s,]+", str(view_box).strip()) if x]
+            if len(nums) != 4 or nums[2] <= 0 or nums[3] <= 0:
+                raise EditError("view_box must be 'minx miny width height' with width, height > 0")
+            r.set("viewBox", " ".join(fmt(v) for v in nums))
+            out.append(f"viewBox {r.get('viewBox')}")
+        if background is not None:
+            bg = background.strip()
+            self.set_background(None if bg.lower() in ("", "none", "transparent") else bg)
+            out.append(f"background {self.background or 'none'}")
+        if fit is not None:
+            if fit != "content":
+                raise EditError("fit must be 'content'")
+            box = R.measure(r)
+            if not box:
+                raise EditError("drawing is empty; nothing to fit")
+            vb = R.viewbox(r)
+            lw = parse_length(r.get("width")) or (vb[2], "")
+            lh = parse_length(r.get("height")) or (vb[3], "")
+            sx, sy = lw[0] / vb[2], lh[0] / vb[3]
+            r.set("viewBox", " ".join(fmt(v) for v in box))
+            r.set("width", fmt(box[2] * sx) + lw[1])
+            r.set("height", fmt(box[3] * sy) + lh[1])
+            out.append(f"fit to content: viewBox {r.get('viewBox')}, size {r.get('width')}×{r.get('height')}")
+        if not out:
+            raise EditError("nothing to set")
+        return "set " + "; ".join(out), []
+
+    def undo(self, steps=1) -> str:
+        with self.lock:
+            if not self.history:
+                raise EditError("nothing to undo")
+            n = max(1, min(int(steps), len(self.history)))
+            snap = None
+            for _ in range(n):
+                snap = self.history.pop()
+            self._restore(snap)
+            self.version += 1
+            self.dirty = True
+            self.touched = []
+            summary = f"undid {n} step(s); {len(self.history)} left"
+            if self.on_change:
+                self.on_change(self, summary)
+            return summary
+
+    # ── export ──────────────────────────────────────────────────────────────
+    def export(self, path=None, format=None, scale=1.0, area="page", plain=False, background=True) -> str:
+        with self.lock:
+            target = path or self.path
+            if not target:
+                raise EditError("no path: pass path= (this document was never saved)")
+            P = resolve_path(target)
+            kind = (format or P.suffix.lstrip(".")).lower()
+            if kind not in ("svg", "png"):
+                raise EditError("format must be 'svg' or 'png' (or use a .svg / .png path)")
+            root = copy.deepcopy(self.root)
+            bg = self.background if background else None
+            if area != "page":
+                ids = None if area == "drawing" else ([area] if isinstance(area, str) else list(area))
+                if ids:
+                    ids = {e.get("id") for e in self.targets(ids)}
+                src = R.isolate(root, ids) if ids else root
+                box = R.measure(src)
+                if not box:
+                    raise EditError("nothing visible to export in that area")
+                vb = R.viewbox(root)
+                lw = parse_length(root.get("width")) or (vb[2], "")
+                lh = parse_length(root.get("height")) or (vb[3], "")
+                root = src
+                root.set("viewBox", " ".join(fmt(v) for v in box))
+                root.set("width", fmt(box[2] * lw[0] / vb[2]) + lw[1])
+                root.set("height", fmt(box[3] * lh[0] / vb[3]) + lh[1])
+            P.parent.mkdir(parents=True, exist_ok=True)
+            existed = P.exists()
+            if kind == "png":
+                resdir = str(Path(self.path).parent) if self.path else None
+                png, w, h, s = R.render_page(root, scale, bg, resdir)
+                P.write_bytes(png)
+                dims = f"{w}×{h}px"
+            else:
+                if bg:
+                    vb = R.viewbox(root)
+                    rect = etree.Element(q("rect"))
+                    for k, v in zip(("x", "y", "width", "height"), vb):
+                        rect.set(k, fmt(v))
+                    rect.set("fill", bg)
+                    rect.set("id", "background")
+                    root.insert(self._drawable_start(root), rect)
+                if plain:
+                    for e in list(iter_els(root)):
+                        ns = etree.QName(e).namespace
+                        if ns in (INK_NS, SODI_NS) and e.getparent() is not None:
+                            e.getparent().remove(e)
+                            continue
+                        for k in list(e.attrib):
+                            if etree.QName(k).namespace in (INK_NS, SODI_NS):
+                                del e.attrib[k]
+                    etree.cleanup_namespaces(root)
+                pretty(root)
+                data = b'<?xml version="1.0" encoding="UTF-8"?>\n' + etree.tostring(root, encoding="utf-8")
+                P.write_bytes(data)
+                dims = f"{root.get('width')}×{root.get('height')}"
+                if area == "page" and not plain:
+                    self.path = str(P)
+                    self.dirty = False
+            return f"{'overwrote' if existed else 'wrote'} {P} ({kind}, {dims}, {P.stat().st_size / 1024:.1f}kB)"
+
+
+class Store:
+    """All open documents. One lock serialises edits against preview reads."""
+
+    def __init__(self):
+        self.docs: dict[str, Document] = {}
+        self.lock = threading.RLock()
+        self.on_change = None  # (doc, summary) -> None
+        self.on_close = None  # (doc_id) -> None
+
+    def get(self, doc_id: str) -> Document:
+        d = self.docs.get(str(doc_id).strip())
+        if d:
+            return d
+        if not self.docs:
+            raise EditError(f"no document '{doc_id}'; none are open (doc_create)")
+        raise EditError(f"no document '{doc_id}'; open: {', '.join(self.docs)}")
+
+    def create(self, name=None, width=None, height=None, units="px", view_box=None,
+               background=None, layers=None, source=None) -> tuple[Document, list[str]]:
+        notes: list[str] = []
+        path = None
+        if source and source.strip():
+            s = source.strip()
+            if s.startswith("<"):
+                root = parse_document(s)
+            else:
+                P = resolve_path(s)
+                if not P.exists():
+                    raise EditError(f"file not found: {P}")
+                raw = P.read_bytes()
+                if P.suffix.lower() == ".svgz" or raw[:2] == b"\x1f\x8b":
+                    raw = gzip.decompress(raw)
+                root = parse_document(raw.decode("utf-8-sig"))
+                path = str(P)
+                name = name or P.stem
+            notes += sanitize([root])
+        else:
+            root = new_root()
+        if units not in UNITS:
+            raise EditError(f"units must be one of {', '.join(UNITS)}")
+        name = (name or "untitled").strip()
+        slug = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")[:24] or "doc"
+        doc_id = f"{slug}__{uuid.uuid4().hex[:6]}"
+        doc = Document(doc_id, name, root, self.lock, self._changed, path)
+        suffix = "" if units == "px" else units
+        imported = source is not None and bool(source.strip())
+        if not imported or width is not None or height is not None:
+            w = float(width if width is not None else (800 if not imported else R.size_px(root)[0]))
+            h = float(height if height is not None else (600 if not imported else R.size_px(root)[1]))
+            if w <= 0 or h <= 0:
+                raise EditError("width/height must be > 0")
+            root.set("width", fmt(w) + suffix)
+            root.set("height", fmt(h) + suffix)
+            if not root.get("viewBox"):
+                root.set("viewBox", f"0 0 {fmt(w)} {fmt(h)}")
+        if view_box:
+            nums = [float(x) for x in re.split(r"[\s,]+", view_box.strip()) if x]
+            if len(nums) != 4 or nums[2] <= 0 or nums[3] <= 0:
+                raise EditError("view_box must be 'minx miny width height' with width, height > 0")
+            root.set("viewBox", " ".join(fmt(v) for v in nums))
+        nv = doc.namedview()
+        nv.set(f"{{{INK_NS}}}document-units", units if not imported else (nv.get(f"{{{INK_NS}}}document-units") or units))
+        if background is not None:
+            bg = background.strip()
+            doc.set_background(None if bg.lower() in ("", "none", "transparent") else bg)
+        elif imported:
+            try:
+                if float(nv.get(f"{{{INK_NS}}}pageopacity") or 0) > 0 and nv.get("pagecolor"):
+                    doc.background = nv.get("pagecolor")
+            except ValueError:
+                pass
+        doc.assign_ids([root])
+        if imported:
+            wrapped = doc.normalise_layers()
+            if wrapped:
+                notes.append(f'wrapped {wrapped} loose elements into layer "Layer 1"')
+        existing = {l.get(INK_LABEL) for l in doc.layers()}
+        wanted = list(layers) if layers else ([] if imported else ["Layer 1"])
+        for label in wanted:
+            if label not in existing:
+                doc._new_layer(label, root)
+        lays = [c for c in children(root) if is_layer(c)]
+        doc.current_layer = lays[-1].get("id") if lays else None
+        with self.lock:
+            self.docs[doc_id] = doc
+        self._changed(doc, f"opened {doc.name}")
+        return doc, notes
+
+    def close(self, doc_id: str, discard: bool = False) -> str:
+        with self.lock:
+            d = self.get(doc_id)
+            if d.dirty and not discard:
+                raise EditError(
+                    f"{d.id} has unsaved changes (v{d.version}); doc_export it first or pass discard=true"
+                )
+            del self.docs[d.id]
+        if self.on_close:
+            self.on_close(d.id)
+        return f"closed {d.id}" + (" (unsaved changes discarded)" if d.dirty else "")
+
+    def _changed(self, doc, summary):
+        if self.on_change:
+            self.on_change(doc, summary)