From 35dbb5d5574e581c56beee806cbfb296c00b6d04 Mon Sep 17 00:00:00 2001
From: doxa-maps <discipletheory@proton.me>
Date: Tue, 22 Sep 2026 05:53:56 +0000
Subject: [PATCH] Run the share round-trip over every plugin that has one, and
 ship the recipe

The OPEN WORK line asks for Playwright coverage over every plugin AND ALL
SHARING. Sharing had never been exercised across the set this flight: the
gate needs a served tree, a token, per-plugin --url flags and (on this box)
--browser chromium, so a bare `bun run smoke:share` only prints usage.

Derived the real coverage set -- grep -rln ShareButton plugin-designs/*/*.vue
gives 8 built leaves -- and ran it: 8/8 pass. Every Share button emits a URL
that resolves 200 text/html and reopens the correct element with a live
canvas.

The pass count alone would have proved nothing. The failure this gate exists
to catch, an SPA fallback or a host stripping the hash deep-link, renders A
map for every share URL, so all 8 pass while all 8 links are wrong. The
discriminating evidence is six DISTINCT reopened tags, each matching its own
plugin, canvas:y on all eight.

reference.md now carries the copy-paste invocation, verified by running it
verbatim from a clean shell (8/8, same six tags). It also corrects a detail:
the doc said Firefox, which is the default but stops on this box -- the tool
detects its own WebGL limitation and names the chromium flag in its output.
---
 documentation/reference.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/documentation/reference.md b/documentation/reference.md
index eef59aa8f..25d47489c 100644
--- a/documentation/reference.md
+++ b/documentation/reference.md
@@ -244,7 +244,36 @@ Measured 2026-09-22, by running each one:
 | Gate | Needs | What a bare run does |
 |---|---|---|
 | `smoke:gallery` (and `smoke:playground`, its alias) | a dev server: `bun x vite` on **:5174** | exits non-zero with *"cannot read http://localhost:5174/__plugin-gallery/registry.json — is `bun x vite` running?"* — a **precondition**, not a defect |
-| `smoke:share` | `--url <page>` arguments **and** the dev server | prints `usage:` and exits non-zero |
+| `smoke:share` | `--url <page>` arguments, a served tree, a token, and **`--browser chromium` on this box** | prints `usage:` and exits non-zero; with default Firefox it stops with "Verified on a BLANK page, so it is the engine/box, not the product" and names the chromium flag itself |
+
+**Copy-paste: the full share round-trip over every plugin that has a Share button.** Assembled and run
+2026-09-22 — **8/8 pass**. Without this recipe an inheritor has to work out the server, the token and the
+eight `--url` flags from scratch, which is why the gate had never been run across all of them.
+
+```sh
+cd doxa-maps-plugin-studio
+( cd public && python3 -m http.server 4950 & )            # serve the built tree
+export MAPBOX_TOKEN=$(curl -s https://doxa.life/api/maps/token \
+  | python3 -c 'import json,sys;print(json.load(sys.stdin)["token"])')
+
+B=http://127.0.0.1:4950/doxa-maps
+ARGS=""
+for p in demo-map/demo-map cities-internet/connectivity-map doxa-research-map/research-map \
+         country-posters/countries-map doxa-simple-map/doxa-simple-map \
+         gospel-resources/resources-map my-upg-100-list/upg-100-list my-upg-100-list/upg-100-mfe; do
+  ARGS="$ARGS --url $B/$p/index.html?tk=$MAPBOX_TOKEN"
+done
+node internal/share-roundtrip-smoke.mjs $ARGS --browser chromium
+```
+
+> **The pass count alone proves nothing — check the reopened TAGS.** The failure this gate exists to catch
+> (an SPA fallback, or a host that strips the `#` deep-link) renders *a* map for every share URL, so every
+> target passes while every link is wrong. The discriminating evidence is that the run returned **six
+> distinct custom-element tags** — `demo-map`, `cities-internet-map`, `doxa-research-map`,
+> `country-posters-map`, `doxa-map`, `gospel-resources-map` — each matching its own plugin, with
+> `canvas:y` on all eight. (The two `my-upg-100-list` profiles legitimately share one tag.) Derive the
+> plugin list the same way it was derived here rather than pasting it stale:
+> `grep -rln ShareButton plugin-designs/*/*.vue`.
 | `smoke:embeds` · `verify:map-paint` · `verify:5-caps` | `MAPBOX_TOKEN` in the environment | **does not fail — it DEGRADES.** Without a token map profiles cannot mount, and `smoke:embeds` reports them as TIMEOUTS. It once read 27/40 for this reason and 40/40 with a token. A timeout here means "no token" far more often than "broken plugin" |
 
 ```sh