mosaic-headless 1.2.0

package/tools/sweep_properties.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Set every declared node property to a probe value on a live site and assert the effect.
+
+    python sweep_properties.py --config sweep.json [--carriers text,button,div,...]
+
+Writes ../data/property-verification.csv.
+
+## What a "pass" means here
+
+Each property is set, alone, on a node that is known to render, and the delivered page
+is then compared against an unprobed baseline of the same page. The probe is unique per
+(type, property) pair, so a hit means *that* property produced *that* output and
+nothing else could have.
+
+Enum properties (`accepted_values` in node-properties.csv) must be probed with a real
+member of their enum - a marker string would simply be rejected - and enum members like
+"0", "none" or "left" already appear all over a normal page. So the test is not "does
+the value appear" but "does it appear MORE OFTEN than without the probe". An enum value
+whose count does not grow is reported INCONCLUSIVE rather than being scored as a pass.
+
+## Outcomes
+
+    HTML       the probe value reached the delivered markup
+    CSS        the probe value reached Mosaic's compiled inline CSS
+    ENUM_APPLIED   an enum value was accepted and shows up in the output
+    INCONCLUSIVE an enum value that appears no more often than on an unprobed page,
+               so the probe proves nothing either way
+    NO_EFFECT  accepted and stored, but nothing observable changed on a bare page
+               (normal for properties that need context: conditions, interactions,
+               loop bindings)
+    REJECTED   validator said no - HTTP 200 with an `exceptions` body
+    COMMIT_5xx PHP fatal during commit
+    BROKE_PAGE the page stopped rendering
+
+NO_EFFECT is not a failure. It is the honest answer for a property whose effect a bare
+probe page cannot show, and it is reported as itself instead of being quietly counted
+as a pass.
+"""
+import argparse
+import csv
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from sweep_node_types import (  # noqa: E402
+    MIN_HEALTHY_BYTES,
+    Client,
+    delete_subtree,
+    envelopes,
+    exceptions_of,
+    unwrap,
+)
+
+# properties that are structural rather than presentational - setting them blind either
+# does nothing observable or removes the node, so they are probed but never expected to
+# show up in markup
+STRUCTURAL = {"currentStatus", "locked", "hidden", "override", "conditions", "interactions", "style"}
+
+
+def probe_value(prop, validators, accepted, marker):
+    """Pick a value the validator chain will accept, as distinctive as it allows."""
+    if accepted:
+        return accepted[0], True
+    if "ValidatorURL" in validators or "ValidatorURLObject" in validators:
+        return "https://example.com/%s" % marker, False
+    if "ValidatorArray" in validators:
+        return [marker], False
+    if "ValidatorInt" in validators or "ValidatorNumber" in validators:
+        return 7, False
+    return marker, False
+
+
+RE_MOSAIC_STYLE = re.compile(
+    r'<style id="mosaic-[^"]*-inline-css">(.*?)</style>', re.S
+)
+
+
+def split_markup_and_css(html):
+    """Separate Mosaic's compiled CSS from the markup it sits inside.
+
+    Mosaic ships NO stylesheet file. Every compiled rule is emitted as an inline
+    <style id="mosaic-theme-block-editor-styles_<breakpointID>-inline-css"> block in
+    the document head - one block per breakpoint, the base breakpoint being `_`.
+
+    This matters for the sweep: searching linked stylesheets finds nothing at all, so
+    a probe whose only effect is a CSS rule would be scored NO_EFFECT. Pull the blocks
+    out of the HTML, and search what is left as markup, so the two can be told apart.
+    """
+    css = "\n".join(RE_MOSAIC_STYLE.findall(html))
+    markup = RE_MOSAIC_STYLE.sub("", html)
+    return markup, css
+
+
+def load_surface(carriers):
+    here = os.path.dirname(os.path.abspath(__file__))
+    data = os.path.join(here, "..", "data")
+    types = {r["type"]: r for r in csv.DictReader(open(os.path.join(data, "node-types.csv"), encoding="utf-8"))}
+    props = list(csv.DictReader(open(os.path.join(data, "node-properties.csv"), encoding="utf-8")))
+    by_class = {}
+    for p in props:
+        by_class.setdefault(p["owner_class"], []).append(p)
+
+    verified = os.path.join(data, "node-verification.csv")
+    renders = set()
+    if os.path.exists(verified):
+        renders = {r["type"] for r in csv.DictReader(open(verified, encoding="utf-8"))
+                   if r["outcome"] == "RENDERED"}
+
+    jobs = []
+    # every element inherits these; probing them on one carrier per shape is enough,
+    # they are the same code path regardless of the node they sit on
+    inherited = by_class.get("ElementMResourceDataAbstract", []) + by_class.get("NodeMResourceDataAbstract", [])
+    for t in carriers:
+        for p in inherited:
+            jobs.append((t, p))
+    # a type's own properties are only meaningful on that type
+    for slug, row in sorted(types.items()):
+        if renders and slug not in renders:
+            continue
+        for p in by_class.get(row["data_class"], []):
+            jobs.append((slug, p))
+    return jobs
+
+
+def run(client, cfg, jobs, out_path):
+    master = cfg["masterID"]
+    key = "node/master/%s" % master
+    doc = unwrap(client.get("masterDocumentInstance/%s" % master), "masterDocumentInstance")
+    baseline_ids = {n["ID"] for n in doc[key]}
+    base_html = client.page(cfg.get("path", ""))
+    if len(base_html) < MIN_HEALTHY_BYTES:
+        sys.exit("baseline page already broken (%d bytes)" % len(base_html))
+    base_markup, base_css = split_markup_and_css(base_html)
+    print("baseline %d bytes, %d nodes, %d probes\n" % (len(base_html), len(baseline_ids), len(jobs)))
+
+    rows = []
+    for n, (node_type, prop) in enumerate(jobs):
+        marker = "MPROP%04dX" % n
+        accepted = [v for v in prop["accepted_values"].split("|") if v]
+        value, is_enum = probe_value(prop["property"], prop["validators"], accepted, marker)
+        needle = str(value[0] if isinstance(value, list) else value)
+
+        doc = unwrap(client.get("masterDocumentInstance/%s" % master), "masterDocumentInstance")
+        nid = str(uuid.uuid4())
+        rec = {
+            "ID": nid, "parentType": "node", "parentID": cfg["parentNodeID"], "ordering": "a0",
+            "status": "publish", "revision": "", "version": "", "type": node_type,
+            "data": {"attrID": "prop-%d" % n, prop["property"]: value},
+            "documentType": "master", "documentID": master,
+        }
+        resp = client.commit("masterDocumentInstance/%s" % master, envelopes(doc),
+                             {key: [{"newRevisionRecord": rec, "originalRevisionRecord": None}]})
+        err = exceptions_of(resp)
+
+        if err:
+            code = resp.get("_httperror")
+            outcome = "COMMIT_%d" % code if code and code >= 500 else "REJECTED"
+            detail = "PHP fatal during commit" if code else err
+        else:
+            html = client.page(cfg.get("path", ""))
+            if len(html) < MIN_HEALTHY_BYTES:
+                outcome, detail = "BROKE_PAGE", html.strip()[:160]
+            else:
+                markup, css = split_markup_and_css(html)
+                # Counting occurrences against the unprobed baseline, rather than just
+                # testing for presence, is what makes an enum probe meaningful: values
+                # like "0", "none" or "left" already appear all over a normal page, and
+                # a presence test scores them as a hit no matter what the property did.
+                grew_css = css.count(needle) > base_css.count(needle)
+                grew_markup = markup.count(needle) > base_markup.count(needle)
+                if grew_css:
+                    outcome = "CSS"
+                elif grew_markup:
+                    outcome = "ENUM_APPLIED" if is_enum else "HTML"
+                elif is_enum and (needle in css or needle in markup):
+                    # present, but no more often than on a page without the probe -
+                    # nothing can be concluded from this value
+                    outcome = "INCONCLUSIVE"
+                else:
+                    outcome = "NO_EFFECT"
+                detail = ""
+
+        rows.append({
+            "type": node_type, "property": prop["property"], "owner_class": prop["owner_class"],
+            "creator": prop["creator"], "probe_value": needle, "is_enum": "yes" if is_enum else "",
+            "outcome": outcome, "detail": detail,
+        })
+        print("%-28s %-18s %-13s %s" % (node_type, prop["property"], outcome, detail[:50]), flush=True)
+        delete_subtree(client, master, baseline_ids, cfg["parentNodeID"])
+
+    with open(out_path, "w", newline="", encoding="utf-8") as fh:
+        w = csv.DictWriter(fh, fieldnames=list(rows[0].keys()))
+        w.writeheader()
+        w.writerows(rows)
+    tally = {}
+    for r in rows:
+        tally[r["outcome"]] = tally.get(r["outcome"], 0) + 1
+    print("\n" + "  ".join("%s=%d" % kv for kv in sorted(tally.items())) + "  -> %s" % out_path)
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--config", required=True)
+    ap.add_argument("--carriers", default="text,button,div,section,image,icon",
+                    help="types used to probe the inherited property set")
+    ap.add_argument("--out", default="../data/property-verification.csv")
+    a = ap.parse_args()
+    cfg = json.load(open(a.config, encoding="utf-8"))
+    run(Client(cfg), cfg, load_surface(a.carriers.split(",")), a.out)

package/tools/sweep_style_properties.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Write every style property to a live page and check what came out.
+
+    python sweep_style_properties.py --config sweep.json --page moksa --csv out.csv
+
+Why this exists
+---------------
+`data/style-properties.csv` lists 98 settable style properties, read out of the
+plugin's source. Before this sweep, 18 of them had ever been written to a real page:
+`data/style-value-shapes.csv` covers the structured ones because their SHAPE had to
+be reverse-engineered, and the scalar majority was assumed to work because the shape
+was obvious. Assumed is not measured. `gridColumnStart` is declared, has its own
+factory group, and compiles to nothing - so "declared" does not imply "works", and
+until this ran, eighty properties were resting on that implication.
+
+Method
+------
+One `div` per property, all committed into one document, then the page is fetched
+once and each element's own rule is read out of the compiled base stylesheet. Every
+probe carries a value chosen to be unmistakable (`37px`, `rgb(9, 99, 199)`), so a
+match means *that* declaration produced *that* value rather than colliding with a
+default.
+
+The node sweep runs one type per document because a bad node can kill the whole
+page; a style property cannot - the worst it does is compile to nothing, which is
+exactly what is being measured. So this one batches, and stays per-property
+attributable because each div has its own attrID and therefore its own class.
+
+Two things that will silently ruin this sweep, both learned the hard way
+-----------------------------------------------------------------------
+**`ordering` must be a valid fractional index.** Pass anything else - `z000` seemed
+harmless - and the commit returns no exception, but the row is stored with BOTH
+`ordering` and `parentID` blanked. The node is orphaned, never renders, and every
+property reads as a false ABSENT. Use `ordering_for()`; never format your own.
+
+**Do not parent probes to `body`.** heal() owns the body's own children and rebuilds
+that skeleton whenever it thinks one is missing. Hang them off a div inside it.
+
+Statuses
+--------
+    COMPILED    the property is in the element's rule with the value we sent
+    DIFFERENT   in the rule, different value - recorded so it can be read
+    ABSENT      declared, committed without error, nothing in the stylesheet
+    SKIPPED     no test value could be synthesised; NOT counted as a pass
+
+`SKIPPED` and `DIFFERENT` are never folded into a pass rate. A sweep that scores its
+own blind spots as successes is the thing this skill exists to argue against.
+"""
+import argparse
+import csv
+import json
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from build_page import Surface, flatten, ordering_for  # noqa: E402
+from sweep_node_types import Client, envelopes, exceptions_of, unwrap  # noqa: E402
+
+MARK_LEN = "37px"
+MARK_COLOR = "rgb(9, 99, 199)"
+MARK_NUM = "7"
+
+# Style keys whose CSS name is not the kebab-case of the key.
+ALIASES = {
+    "gridCols": "grid-template-columns",
+    "radius": "border-radius",
+    "move": "transform",
+    "shadow": "box-shadow",
+    "transitionAll": "transition",
+    "objectFitStyle": "object-fit",
+    "backgroundStyle": "background-image",
+    "customStyles": None,          # raw CSS, not a single declaration
+}
+
+# Structured values whose shape was pinned down by data/style-value-shapes.csv.
+SHAPES = {
+    "borderRadius": {"type": "all", "allOptions": {"borderRadiusValue": MARK_LEN}},
+    "move": {"translateY": MARK_LEN},
+    "shadow": {"x": "0px", "y": MARK_LEN, "blur": "9px", "spread": "0px",
+               "color": MARK_COLOR},
+    "border": {"width": "3px", "style": "dashed", "color": MARK_COLOR},
+    "gridCols": [{"type": "default", "defaultOptions": {"size": MARK_LEN}}],
+    "gridTemplateColumns": [{"type": "default", "defaultOptions": {"size": MARK_LEN}}],
+    "gridTemplateRows": [{"type": "default", "defaultOptions": {"size": MARK_LEN}}],
+    "objectFitStyle": {"objectFit": "cover", "objectPositionX": "37%",
+                       "objectPositionY": "37%"},
+}
+
+LENGTHY = re.compile(
+    r"(width|height|size|top|right|bottom|left|gap|padding|margin|indent|spacing|"
+    r"offset|radius|thickness|basis|inset)", re.I)
+COLORY = re.compile(r"color$", re.I)
+NUMERIC = {"zIndex", "order", "flexGrow", "flexShrink", "lineHeight",
+           "fontWeight", "gridColumnStart", "gridColumnEnd", "gridRowStart",
+           "gridRowEnd"}
+# properties whose valid range excludes the generic marker. `opacity: 7` compiles to
+# `1` because the browser clamps it - which reads as DIFFERENT and is my test value's
+# fault, not the property's.
+RANGED = {"opacity": "0.37"}
+
+
+def kebab(name):
+    return re.sub(r"(?<!^)(?=[A-Z])", "-", name).lower()
+
+
+def css_name(key):
+    return ALIASES[key] if key in ALIASES else kebab(key)
+
+
+def test_value(row):
+    """Pick an unmistakable value for one property, or None if we cannot."""
+    key = row["property"]
+    if key in SHAPES:
+        return SHAPES[key]
+    if key == "customStyles":
+        return None
+    enum = (row.get("accepted_values") or "").strip()
+    if enum:
+        options = [o for o in enum.split("|") if o and " " not in o]
+        return options[-1] if options else None      # least likely to be the default
+    if key in RANGED:
+        return RANGED[key]
+    if key in NUMERIC:
+        return MARK_NUM
+    if COLORY.search(key):
+        return MARK_COLOR
+    if LENGTHY.search(key):
+        return MARK_LEN
+    return None
+
+
+def parse_rules(html, suffix=""):
+    """{M_EL class: {css property: value}} for one compiled stylesheet."""
+    m = re.search(
+        r'<style id="mosaic-theme-block-editor-styles_%s-inline-css">(.*?)</style>'
+        % suffix, html, re.S)
+    rules = {}
+    if not m:
+        return rules
+    for sel, decls in re.findall(r"([^{}]+)\{([^{}]*)\}", m.group(1)):
+        cls = re.match(r"^\.(M_EL\d+)$", sel.strip())
+        if not cls:
+            continue
+        props = {}
+        for d in decls.split(";"):
+            if ":" in d:
+                k, v = d.split(":", 1)
+                props[k.strip()] = v.strip()
+        rules.setdefault(cls.group(1), {}).update(props)
+    return rules
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--config", required=True)
+    ap.add_argument("--page", required=True, help="slug of a page that renders")
+    ap.add_argument("--csv")
+    a = ap.parse_args()
+
+    cfg = json.load(open(a.config, encoding="utf-8"))
+    here = os.path.dirname(os.path.abspath(__file__))
+    props = list(csv.DictReader(
+        open(os.path.join(here, "..", "data", "style-properties.csv"),
+             encoding="utf-8")))
+
+    client = Client(cfg)
+    tei = unwrap(client.get("adminTemplateEditorInstance"), "adminTemplateEditorInstance")
+    master = tei["template"][-1]["masterID"]
+    instance = "masterDocumentInstance/%s" % master
+    doc = unwrap(client.get(instance), "masterDocumentInstance")
+    key = "node/master/%s" % master
+    body = next(n for n in doc[key] if n["type"] == "body")
+    # a div INSIDE the body - heal() owns the body's own children
+    host = next(n for n in doc[key]
+                if n["parentID"] == body["ID"] and n["type"] == "div")
+    surface = Surface()
+
+    planned, skipped, records = [], [], []
+    for i, row in enumerate(props):
+        value = test_value(row)
+        if value is None:
+            skipped.append(row["property"])
+            continue
+        attr = "sp-%03d" % i
+        planned.append((attr, row["property"], value))
+        for rec in flatten({"type": "div", "data": {"attrID": attr},
+                            "style": {"&": {"_": {row["property"]: value}}}},
+                           host["ID"], master, surface, True,
+                           # a valid fractional index, never a formatted number
+                           ordering=ordering_for(i), parent_type="div"):
+            records.append({"newRevisionRecord": rec, "originalRevisionRecord": None})
+
+    print("%d properties, %d probes, %d skipped" % (len(props), len(planned), len(skipped)))
+    resp = client.commit(instance, envelopes(doc), {key: records})
+    err = exceptions_of(resp)
+    if err:
+        sys.exit("commit rejected: %s" % err[:400])
+
+    html = client.page(a.page)
+    classes = {}
+    for m in re.finditer(r'id="(sp-\d+)"[^>]*class="(M_EL\d+)', html):
+        classes[m.group(1)] = m.group(2)
+    print("probes rendered: %d of %d" % (len(classes), len(planned)))
+    if not classes:
+        sys.exit("no probe rendered - check ordering and parent before trusting a run")
+
+    rules = parse_rules(html)
+
+    rows = []
+    for attr, key_name, value in planned:
+        cls = classes.get(attr)
+        name = css_name(key_name)
+        got = rules.get(cls, {}) if cls else {}
+        hit = None
+        if name:
+            hit = got.get(name) or next(
+                (v for k, v in got.items() if k.startswith(name)), None)
+        want = value if isinstance(value, str) else None
+        if cls is None:
+            status = "NO_ELEMENT"
+        elif hit is None:
+            status = "ABSENT"
+        elif want is None or want.replace(" ", "") in hit.replace(" ", ""):
+            status = "COMPILED"
+        else:
+            status = "DIFFERENT"
+        rows.append([key_name, name or "", json.dumps(value, ensure_ascii=False),
+                     hit or "", status])
+    for p in skipped:
+        rows.append([p, css_name(p) or "", "", "", "SKIPPED"])
+
+    counts = {}
+    for r in rows:
+        counts[r[4]] = counts.get(r[4], 0) + 1
+    print()
+    for k in ("COMPILED", "DIFFERENT", "ABSENT", "NO_ELEMENT", "SKIPPED"):
+        if counts.get(k):
+            print("  %-11s %d" % (k, counts[k]))
+    for k in ("ABSENT", "DIFFERENT"):
+        names = [r[0] for r in rows if r[4] == k]
+        if names:
+            print("\n  %s: %s" % (k, ", ".join(names)))
+
+    if a.csv:
+        with open(a.csv, "w", newline="", encoding="utf-8") as fh:
+            w = csv.writer(fh)
+            w.writerow(["property", "css_property", "sent", "compiled", "status"])
+            w.writerows(sorted(rows))
+        print("\nwrote", a.csv)
+
+
+if __name__ == "__main__":
+    main()

package/tools/theme_export.php

@@ -0,0 +1,91 @@
+<?php
+/**
+ * Export a complete Mosaic theme to portable JSON.
+ *
+ *   wp eval-file theme_export.php <themeID> > mytheme.json
+ *   wp eval-file theme_export.php active    > mytheme.json
+ *
+ * A Mosaic theme is not a file and not an option row - it is a themeID scattered
+ * across nineteen tables. Nothing in the plugin exports one without a licence, and
+ * "copy the site" is not a migration path when you want one theme out of fifty.
+ *
+ * What makes this safe to re-import is the schema: every theme-scoped table has a
+ * COMPOSITE primary key of (themeID, ID). Internal ids - masters, templates, nodes,
+ * breakpoints, collection variables - only have to be unique WITHIN a theme. So an
+ * import can keep every internal id exactly as it was and rewrite nothing but the
+ * themeID, which means no id remapping, no dangling parentID, and no rewriting of
+ * the ids embedded inside node `data` blobs.
+ *
+ * Node `data` is emitted verbatim as a string. It contains style objects, dynamic
+ * expressions and raw CSS; decoding and re-encoding it would risk changing it.
+ */
+
+global $wpdb;
+
+$args = isset($args) ? $args : [];
+$want = isset($args[0]) ? $args[0] : '';
+
+// bare keywords, not --flags: wp-cli claims anything --prefixed first
+if ($want === 'active' || $want === '') {
+    $stylesheet = get_option('stylesheet');
+    if (!preg_match('/^mosaic-\d+-\d+-([0-9a-f\-]{36})$/i', $stylesheet, $m)) {
+        fwrite(STDERR, "active theme is not a Mosaic theme: {$stylesheet}\n");
+        return;
+    }
+    $want = $m[1];
+}
+
+$p = $wpdb->prefix . 'mosaic_';
+
+$theme = $wpdb->get_row($wpdb->prepare("SELECT * FROM {$p}themes WHERE ID=%s", $want), ARRAY_A);
+if (!$theme) {
+    fwrite(STDERR, "no such theme: {$want}\n");
+    return;
+}
+
+// Every table that carries a themeID. locks, settings and submission_actions are
+// deliberately absent: they are site state, not part of a theme.
+$tables = [
+    'breakpoints', 'collections', 'collection_modes', 'collection_skins',
+    'collection_groups', 'collection_variables', 'element_classes', 'sub_classes',
+    'utility_classes', 'utility_sub_classes', 'styleguides', 'masters', 'templates',
+    'template_assigns', 'nodes', 'components', 'component_documents',
+    'component_categories', 'submissions',
+];
+
+$out = [
+    'format'     => 'mosaic-theme-export/1',
+    'exported'   => gmdate('c'),
+    'source'     => home_url(),
+    'mosaic'     => defined('MOSAIC_VERSION') ? MOSAIC_VERSION : null,
+    'theme'      => $theme,
+    'tables'     => [],
+    'rowCounts'  => [],
+];
+
+foreach ($tables as $t) {
+    $rows = $wpdb->get_results(
+        $wpdb->prepare("SELECT * FROM {$p}{$t} WHERE themeID=%s", $want), ARRAY_A);
+    $out['tables'][$t] = $rows ? $rows : [];
+    $out['rowCounts'][$t] = count($out['tables'][$t]);
+}
+
+// template_assigns points at posts by id. Carry the slug too, so an import onto a
+// different site can rebind by slug instead of silently pointing at whatever post
+// happens to hold that id there.
+foreach ($out['tables']['template_assigns'] as &$a) {
+    if (($a['type'] ?? '') === 'post') {
+        $post = get_post((int)$a['typeIdentifier']);
+        $a['_postSlug'] = $post ? $post->post_name : null;
+        $a['_postType'] = $post ? $post->post_type : null;
+    }
+}
+unset($a);
+
+echo json_encode($out, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT);
+echo "\n";
+fwrite(STDERR, sprintf("exported theme %s (%s): %s\n", $theme['ID'], $theme['name'],
+    implode(', ', array_map(
+        function ($k, $v) { return "$k=$v"; },
+        array_keys(array_filter($out['rowCounts'])),
+        array_values(array_filter($out['rowCounts']))))));

package/tools/theme_import.php

@@ -0,0 +1,113 @@
+<?php
+/**
+ * Import a theme exported by theme_export.php, under a fresh themeID.
+ *
+ *   wp eval-file theme_import.php mytheme.json "Imported name"
+ *   wp eval-file theme_import.php mytheme.json "Imported name" activate
+ *   wp eval-file theme_import.php mytheme.json "Imported name" rebind
+ *
+ * Only the themeID changes. Every internal id - masters, templates, nodes,
+ * breakpoints, collection variables - is carried across unchanged, which is legal
+ * because each theme-scoped table has a COMPOSITE primary key of (themeID, ID).
+ * That is what makes this a copy rather than a rewrite: no id remapping, so nothing
+ * can dangle, and the ids embedded inside node `data` blobs stay correct without the
+ * blob ever being decoded.
+ *
+ * Every insert passes an explicit all-%s format array. Without one,
+ * $wpdb->insert() consults $wpdb->field_types, which hardcodes 'ID' => '%d' for
+ * WordPress core tables - so a Mosaic varchar ID is cast to an integer and the
+ * breakpoint '_t' is stored as 0. It fails loudly on the second breakpoint, because
+ * '_m' also becomes 0 and collides on the primary key; on a table where only one row
+ * happened to be affected it would have failed silently.
+ *
+ * `rebind` re-points template assignments at the post with the same slug
+ * on THIS site rather than the same numeric id, which is what you want when moving a
+ * theme between installs. Without it the ids are copied verbatim and an assignment
+ * may silently land on an unrelated post.
+ */
+
+use Mosaic\WPTheme\WPThemeManager;
+
+global $wpdb;
+
+$args = isset($args) ? $args : [];
+$path = isset($args[0]) ? $args[0] : '';
+$name = isset($args[1]) ? $args[1] : '';
+$flags = array_slice($args, 2);
+// bare keywords, not --flags: wp-cli claims anything --prefixed first
+$activate = in_array('activate', $flags, true);
+$rebind = in_array('rebind', $flags, true);
+
+if (!$path || !file_exists($path)) {
+    fwrite(STDERR, "usage: wp eval-file theme_import.php <export.json> [name] [--activate] [--rebind-by-slug]\n");
+    return;
+}
+
+$data = json_decode(file_get_contents($path), true);
+if (!$data || ($data['format'] ?? '') !== 'mosaic-theme-export/1') {
+    fwrite(STDERR, "not a mosaic-theme-export/1 file\n");
+    return;
+}
+
+$newID = wp_generate_uuid4();
+$p = $wpdb->prefix . 'mosaic_';
+
+$theme = $data['theme'];
+$theme['ID'] = $newID;
+if ($name !== '') {
+    $theme['name'] = $name;
+}
+$wpdb->insert($p . 'themes', $theme, array_fill(0, count($theme), '%s'));
+if ($wpdb->last_error) {
+    fwrite(STDERR, "theme row failed: {$wpdb->last_error}\n");
+    return;
+}
+
+$counts = [];
+foreach ($data['tables'] as $table => $rows) {
+    $n = 0;
+    foreach ($rows as $row) {
+        // strip the export-only hints before they reach a column that does not exist
+        $slug = $row['_postSlug'] ?? null;
+        $ptype = $row['_postType'] ?? null;
+        unset($row['_postSlug'], $row['_postType']);
+
+        $row['themeID'] = $newID;
+
+        if ($rebind && $table === 'template_assigns'
+            && ($row['type'] ?? '') === 'post' && $slug) {
+            $found = get_page_by_path($slug, OBJECT, $ptype ? $ptype : 'page');
+            if ($found) {
+                $row['typeIdentifier'] = (string)$found->ID;
+            } else {
+                fwrite(STDERR, "  no post with slug '{$slug}' here; assignment left pointing at id {$row['typeIdentifier']}\n");
+            }
+        }
+
+        $wpdb->insert($p . $table, $row, array_fill(0, count($row), '%s'));
+        if ($wpdb->last_error) {
+            fwrite(STDERR, "  {$table} row failed: {$wpdb->last_error}\n");
+            $wpdb->last_error = '';
+            continue;
+        }
+        $n++;
+    }
+    if ($n) {
+        $counts[$table] = $n;
+    }
+}
+
+WPThemeManager::createThemeOnCurrentSite($newID, $theme['name'], $theme['revision']);
+
+$parts = [];
+foreach ($counts as $k => $v) {
+    $parts[] = "$k=$v";
+}
+fwrite(STDERR, sprintf("imported as %s (%s): %s\n", $newID, $theme['name'], implode(', ', $parts)));
+
+if ($activate) {
+    switch_theme('mosaic-1-1-' . $newID);
+    fwrite(STDERR, "activated mosaic-1-1-{$newID}\n");
+}
+
+echo "THEME_ID={$newID}\n";