@orbytes/astrolab 0.3.0

package/src/pin/toolbar.js

@@ -0,0 +1,3181 @@
+/**
+ * orbytes-pin — the dev toolbar app.
+ *
+ * Click a rendered element on `astro dev`, type or dictate a comment, and the dev server writes a
+ * markdown ticket plus a screenshot to local disk. This file is the browser half only; the
+ * integration (index.mjs) owns the server half and registers this file as the app entrypoint.
+ *
+ * Two surfaces live here, and they are allowed to be open at once:
+ *
+ *   · THE PICKER — the crosshair, the climb, the comment box. Everything below `the app`.
+ *   · THE TICKET PANEL and its PAGE MARKERS — a right-hand rail with an Open and a Resolved
+ *     tab, and a map pin on every ticket's element on this page: blue for open, grey for
+ *     resolved, none at all for one that cannot be placed honestly. Everything under
+ *     `the ticket panel`, whose own contract notes say why each part is shaped as it is.
+ *
+ * The panel reads tickets from the board's own per-card JSON payload (`renderBoard`,
+ * src/board.mjs) and writes through the package's one endpoint, whose address it takes from
+ * the board's `data-api` — it never parses a ticket file and never assembles a URL.
+ *
+ * Self-contained on purpose: it imports no FILE from its own package — only `astro/toolbar`
+ * (the public app helper), two of Astro's own dev-toolbar helpers, and one virtual module the
+ * integration generates (`virtual:orbytes-pin/config.mjs`, the resolved options — a toolbar app
+ * entrypoint is handed none, so this is the only way in). The helpers are both reachable through
+ * astro's declared `./client/*` export map:
+ *
+ *   node_modules/astro/package.json  "./toolbar"  -> dist/toolbar/index.js
+ *   node_modules/astro/package.json  "./client/*" -> dist/runtime/client/*
+ *
+ * Astro 7.3.1 APIs used, with the file each was read from:
+ *   dist/types/public/toolbar.d.ts:30      init(canvas: ShadowRoot, app, server)
+ *   dist/types/public/toolbar.d.ts:31      beforeTogglingOff(canvas): boolean
+ *   dist/toolbar/index.js:1                defineToolbarApp(app)
+ *   dist/runtime/client/dev-toolbar/helpers.js:65/79   server.send / server.on
+ *   dist/runtime/client/dev-toolbar/helpers.js:36      app.onToggled({ state })
+ *   dist/runtime/client/dev-toolbar/apps/utils/highlight.js   createHighlight/positionHighlight
+ *   dist/runtime/client/dev-toolbar/apps/utils/window.js      createWindowElement/synchronizePlacementOnUpdate
+ */
+
+import { defineToolbarApp } from 'astro/toolbar';
+import {
+	createHighlight,
+	getElementsPositionInDocument,
+	positionHighlight,
+} from 'astro/client/dev-toolbar/apps/utils/highlight.js';
+import {
+	createWindowElement,
+	synchronizePlacementOnUpdate,
+} from 'astro/client/dev-toolbar/apps/utils/window.js';
+import pinConfig from 'virtual:orbytes-pin/config.mjs';
+
+const SRC_ATTR = 'data-orbytes-src';
+const RESTORE_KEY = 'orbytes-pin:last';
+const RESTORE_TTL_MS = 30 * 60 * 1000;
+const FLASH_MS = 1200;
+const OUTER_HTML_LIMIT = 400;
+const REPLY_TIMEOUT_MS = 8000;
+/**
+ * How long a transient acknowledgement stays on screen. Long enough to read the ticket id after
+ * looking away to the page; short enough that the panel is not carrying yesterday's news. A
+ * FAILURE never uses this — it has no timer at all (› `say`).
+ */
+const ACK_MS = 6000;
+/** How far the hit test will follow nested frames before it stops and says so. */
+const MAX_FRAME_DEPTH = 8;
+
+/**
+ * Layering. The built-in window is `position: fixed; z-index: 999999999`
+ * (ui-library/window.js) and the toolbar bar is `z-index: 2000000010` (toolbar.js:47).
+ * Everything this app paints has to sit ABOVE the page and BELOW the window, or the pick
+ * surface swallows clicks meant for the comment box.
+ */
+const Z = {
+	surface: 999_998_000,
+	hover: 999_998_500,
+	selected: 999_998_600,
+	chip: 999_998_700,
+	flash: 999_998_800,
+	/** A pin marker: over the pick surface so it is clickable, under the pick highlight so the
+	 *  crosshair's own chrome always reads on top of it. */
+	marker: 999_998_400,
+	/** The ticket panel: over everything this app paints on the page, under the comment window,
+	 *  which must never be covered by anything. */
+	panel: 999_998_900,
+};
+
+/* ------------------------------------------------------------------ pure helpers */
+
+/**
+ * Words that name a RUNTIME CONDITION rather than a variant. A class ending in one of these
+ * moves between elements while the page is alive — `swiper-slide-active` is on slide 1 now and
+ * slide 2 once the carousel scrolls — so a selector built on one is dead the moment the
+ * component moves, exactly like an id minted at init.
+ *
+ * This is English state vocabulary, not one library's namespace, and that is the point: the
+ * same list retires `swiper-slide-active`, `slick-active`, `glide__slide--active`,
+ * `owl-item-active`, `tns-slide-active` and a hand-written `is-open` without naming any of them.
+ * Variant words — `solid`, `small`, `medium`, `wide`, `outline`, `tan` — are deliberately absent,
+ * because a variant is authored and permanent.
+ *
+ * Measured on this site 2026-09-21 (311 distinct classes across four pages): this list retires
+ * nine of them. Six are genuinely runtime (`swiper-slide-active/-visible/-fully-visible/-next`,
+ * `swiper-backface-hidden`, `is-unbuilt`); three are authored and stable but state-named
+ * (`founder__arrow-icon--next/--prev`, `navbar__toggle-icon--open`). Losing those three costs a
+ * slightly longer selector and nothing else, because cssPathOf verifies whatever it builds and
+ * falls through to tag + :nth-of-type. That asymmetry is the whole argument for erring wide: a
+ * false positive costs readability, a false negative costs the ticket.
+ */
+const STATE_WORDS = new Set([
+	'active', 'inactive', 'animate', 'animated', 'animating', 'busy', 'checked', 'closed',
+	'closing', 'collapsed', 'current', 'dimmed', 'dirty', 'disabled', 'dragged', 'dragging',
+	'duplicate', 'empty', 'enabled', 'entered', 'entering', 'error', 'exiting', 'filled',
+	'first', 'focus', 'focused', 'hidden', 'highlighted', 'hover', 'hovered', 'init',
+	'initialized', 'invalid', 'inview', 'invisible', 'last', 'leaving', 'loaded', 'loading',
+	'mounted', 'next', 'offscreen', 'onscreen', 'open', 'opened', 'opening', 'paused',
+	'pinned', 'playing', 'pressed', 'prev', 'previous', 'pristine', 'ready', 'revealed',
+	'revealing', 'scrolled', 'scrolling', 'selected', 'showing', 'shown', 'stuck', 'sticky',
+	'touched', 'transitioning', 'unchecked', 'valid', 'visible',
+]);
+
+/**
+ * True for a class that describes what the element is DOING rather than what it IS.
+ * Two shapes, both library-agnostic:
+ *   · the universal state prefixes — `is-open`, `has-error`, `js-active`;
+ *   · a trailing state word — `swiper-slide-active`, `foo--visible`, `active`.
+ */
+function isTransientClass(name) {
+	const words = String(name ?? '').toLowerCase().split(/[-_]+/).filter(Boolean);
+	if (!words.length) return false;
+	if (words.length > 1 && (words[0] === 'is' || words[0] === 'has' || words[0] === 'js')) return true;
+	return STATE_WORDS.has(words[words.length - 1]);
+}
+
+/**
+ * Classes that are machine output, not authored intent — never put them in a selector, because
+ * the value changes and the selector stops resolving. Two families:
+ *   · build hashes, which change when the file is next touched;
+ *   · runtime state (› isTransientClass), which changes while the page is open.
+ *
+ * Still deliberately narrow about authored names: BEM blocks, elements and modifiers
+ * (`hero__title`, `button--solid`, `section--medium`) are authored and must survive, and
+ * anything this misses is still caught by the selector verification in cssPathOf().
+ */
+function isNoiseClass(name) {
+	if (!name) return true;
+	if (/^astro-[a-z0-9]{6,}$/i.test(name)) return true; // Astro scoped style class
+	if (/^svelte-[a-z0-9]{5,}$/i.test(name)) return true;
+	if (/^_[A-Za-z0-9-]+_[a-z0-9]{4,}$/i.test(name)) return true; // Vite CSS-module hash
+	if (isTransientClass(name)) return true;
+	return false;
+}
+
+/**
+ * The base class this one decorates with a SINGLE dash, when that base is also on the element —
+ * `swiper-slide` under `swiper-slide-active`, `swiper` under `swiper-initialized`. Returns null
+ * otherwise.
+ *
+ * The separator is the discriminator, and it is a convention rather than a law, which is why the
+ * state lexicon above is the primary rule and this is the backstop. A library that mints state
+ * onto its own block class almost always does it with one dash (`slick-initialized`,
+ * `owl-loaded`, `tns-horizontal`, `swiper-watch-progress`); a human writing BEM reaches for `--`
+ * or `__`. Measured here: of 48 same-element extensions on this site, every single-dash one is
+ * Swiper's and every `--` one is authored (`button--solid`, `footer__band--cta`,
+ * `approach__step-slot--1`). Cost of a wrong call is again readability only.
+ */
+function extendsSiblingClass(name, all) {
+	for (const base of all) {
+		if (base === name || !base) continue;
+		if (
+			name.length > base.length + 1 &&
+			name.startsWith(base) &&
+			name[base.length] === '-' &&
+			name[base.length + 1] !== '-'
+		) {
+			return base;
+		}
+	}
+	return null;
+}
+
+function stableClasses(el) {
+	const all = Array.prototype.slice.call(el.classList);
+	const out = [];
+	for (const name of all) {
+		if (isNoiseClass(name)) continue;
+		if (extendsSiblingClass(name, all)) continue;
+		out.push(name);
+		if (out.length === 3) break;
+	}
+	return out;
+}
+
+function escapeIdent(value) {
+	if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(value);
+	return String(value).replace(/([^\w-])/g, '\\$1');
+}
+
+/** 1-based index among same-tag siblings, or null when the tag is unique in its parent. */
+function nthOfType(el) {
+	const parent = el.parentElement;
+	if (!parent) return null;
+	let index = 0;
+	let seen = 0;
+	for (const sibling of parent.children) {
+		if (sibling.tagName !== el.tagName) continue;
+		seen += 1;
+		if (sibling === el) index = seen;
+	}
+	return seen > 1 ? index : null;
+}
+
+/** Full positional path — the fallback that always describes exactly one node. */
+function nthChildPath(el) {
+	const parts = [];
+	const root = el.ownerDocument.documentElement;
+	let node = el;
+	while (node && node.nodeType === 1 && node !== root) {
+		const parent = node.parentElement;
+		if (!parent) break;
+		const index = Array.prototype.indexOf.call(parent.children, node) + 1;
+		parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
+		node = parent;
+	}
+	return parts.length ? `html > ${parts.join(' > ')}` : '';
+}
+
+function matchesExactly(selector, el) {
+	if (!selector) return false;
+	try {
+		// The element's OWN document, not this one. Inside the component lab the element being
+		// described lives in a story iframe, and a selector verified against the shell around it
+		// would be verified against a document it will never be run in.
+		const found = el.ownerDocument.querySelectorAll(selector);
+		return found.length === 1 && found[0] === el;
+	} catch {
+		return false;
+	}
+}
+
+/** How many nodes a selector finds in `doc`, or -1 when it does not parse. */
+function countMatches(selector, doc) {
+	if (!selector) return -1;
+	try {
+		return doc.querySelectorAll(selector).length;
+	} catch {
+		return -1;
+	}
+}
+
+/**
+ * One `-`/`_`/`.`/`:`-separated piece of an id that a human plausibly typed: a word, a small
+ * counter, or a word with a small counter welded on (`h1`, `col2`, `step3`).
+ */
+const HUMAN_ID_SEGMENT = /^(?:[A-Za-z]{1,20}|\d{1,3}|[A-Za-z]{1,5}\d{1,3})$/;
+
+/**
+ * Whether an id is safe to anchor a selector on — which is NOT the same question as whether it
+ * is unique right now. Swiper mints `id="swiper-wrapper-<random hex>"` when it initialises and
+ * mints a DIFFERENT one on every page load, so an id can be perfectly unique at pick time and
+ * name nothing at all ten seconds later. Measured on this site 2026-09-21: the same wrapper came
+ * back as `…2a2469caeb1c8a14`, then `…54d9ec0d44549cd5`, then `…78419b56f1752d81` on three
+ * consecutive loads of `/`.
+ *
+ * The test is an ALLOWLIST of authored shapes rather than a blocklist of generated ones, and
+ * that direction is the whole design:
+ *   · a blocklist has to predict the next library's garbage — ban "swiper" and React's `:r0:`,
+ *     Radix's `radix-:r3:`, Emotion's `css-1q2w3e` and MUI's hashes all still walk through, and
+ *     each one emits a confident dead selector, which is the defect this exists to stop;
+ *   · an allowlist only has to describe what a person types — words, separators, small counters
+ *     — and everything else falls through to the structural path, which cssPathOf verifies
+ *     against the live document anyway.
+ *   · The two error costs are not symmetric. Refusing a real id costs a longer selector.
+ *     Trusting a generated one costs the ticket: PIN-005 carried
+ *     `#swiper-wrapper-884c31f1c76fd5de > … > blockquote`, resolved to one node when written and
+ *     zero on every load after, and nothing on the ticket said so.
+ *
+ * Measured against every id this site actually emits (7 routes, two loads each): `navbar-mega`,
+ * `main` and `services` pass; `swiper-wrapper-<16 hex>` is the only id that fails, and it is the
+ * only one that changed between loads. No false positives, no false negatives, on real data.
+ *
+ * What it does NOT catch, stated plainly rather than papered over: framework COUNTER ids —
+ * `mui-1`, `cdk-overlay-0`, `ember42` — are word-plus-small-number, which is exactly what a
+ * person types, so no shape test can separate them from `faq-item-3`. They are unstable all the
+ * same. That residue is why shot.mjs re-counts every selector on a genuinely fresh load and
+ * writes the answer into the ticket: this function lowers the failure rate, the fresh-load count
+ * makes whatever is left visible instead of silent.
+ */
+function isTrustworthyId(id) {
+	const raw = String(id ?? '');
+	if (!raw || raw.length > 60) return false;
+	// Split without `+` so a leading, trailing or doubled separator leaves an empty segment and
+	// is rejected — `:r0:` and `__nuxt` are framework markers, not names anyone chose.
+	for (const segment of raw.split(/[-_.:]/)) {
+		if (!HUMAN_ID_SEGMENT.test(segment)) return false;
+		// A pure-letter segment drawn only from the hex alphabet is a hash that got lucky
+		// (`deadbeefcafe`). Real words this long inside a-f do not occur; `facade` is six.
+		if (segment.length >= 8 && /^[a-f]+$/i.test(segment)) return false;
+	}
+	return true;
+}
+
+/**
+ * Every way ONE node can name itself, shortest first: `tag.class.class`, then the same with
+ * `:nth-of-type(n)` welded on. A unique, trustworthy id replaces both and ends the walk, because
+ * nothing above a document-unique id can narrow anything below it.
+ *
+ * `anchored` is that fact, returned rather than re-derived: the search reads it to know it has
+ * hit the ceiling.
+ */
+function partCandidates(node) {
+	const id = node.getAttribute && node.getAttribute('id');
+	if (id && isTrustworthyId(id) && matchesExactly(`#${escapeIdent(id)}`, node)) {
+		return { parts: [`#${escapeIdent(id)}`], anchored: true };
+	}
+	let base = node.tagName.toLowerCase();
+	for (const cls of stableClasses(node)) base += `.${escapeIdent(cls)}`;
+	const parts = [base];
+	const nth = nthOfType(node);
+	if (nth !== null) parts.push(`${base}:nth-of-type(${nth})`);
+	return { parts, anchored: false };
+}
+
+/** How far up the search will look for a narrowing ancestor before it gives up and falls back. */
+const MAX_SELECTOR_HOPS = 12;
+
+/** How many levels the selector may name at once. Each one doubles the combinations tried. */
+const MAX_SELECTOR_LEVELS = 4;
+
+/**
+ * Every selector a chain of levels (outermost first) can spell, FEWEST QUALIFIERS FIRST.
+ *
+ * The ordering is the point, and it is what makes an ancestor pay for itself twice. Retaining
+ * `a.navbar__card:nth-of-type(3)` also settles which `span.navbar__card-arrow` is meant, so the
+ * span no longer needs its own `:nth-of-type(1)` — but only a search that re-tries the span's
+ * plain form AFTER the ancestor is in hand will ever find that out. Cost is the number of levels
+ * spelled with a positional qualifier; ties break on the shorter string.
+ */
+function selectorCombos(levels) {
+	let out = [{ text: '', cost: 0 }];
+	for (const level of levels) {
+		const next = [];
+		for (const acc of out) {
+			for (let index = 0; index < level.parts.length; index++) {
+				next.push({
+					text: acc.text ? `${acc.text} ${level.parts[index]}` : level.parts[index],
+					cost: acc.cost + index,
+				});
+			}
+		}
+		out = next;
+	}
+	out.sort((a, b) => a.cost - b.cost || a.text.length - b.text.length);
+	return out.map((combo) => combo.text);
+}
+
+/** The most specific spelling of a level chain — the one with the fewest possible matches. */
+function mostSpecific(levels) {
+	return levels.map((level) => level.parts[level.parts.length - 1]).join(' ');
+}
+
+/**
+ * The SHORTEST readable CSS selector that resolves to exactly this element — nothing more.
+ *
+ * Until 2026-09-22 this built the full ancestor chain down from the nearest trustworthy id and
+ * welded `:nth-of-type(n)` onto every step that had same-tag siblings, whether or not either was
+ * needed. The pseudo-classes turned out not to be necessary at all: of the 1,809 elements
+ * sampled across six routes, 96.6% carried an `:nth-of-type` and the average selector ran 175
+ * characters.
+ *
+ * Length was the visible half. The invisible half is that **both additions make the selector
+ * more fragile, not less**. `section.statement:nth-of-type(2)` stops resolving the moment a
+ * sibling section is added above it; `.statement__story`, which names the same node, does not
+ * care. Every ancestor in the chain is one more node whose class or position can move. A
+ * qualifier is worth its fragility only when it is doing work.
+ *
+ * So the search builds up instead of stripping down, and each step is verified before it is
+ * accepted:
+ *
+ *   1. **The element alone** — `div.statement__story`, then `…:nth-of-type(n)` if that was
+ *      ambiguous. One of these ends it for most elements on a component-built site, because a
+ *      BEM class is already unique.
+ *   2. **Climb for a NARROWING ancestor**, nearest first. An ancestor is prepended (as a
+ *      descendant, ` `, not a child, `>`, so the intermediate nodes can be skipped entirely)
+ *      only when it actually cuts the number of matches. A wrapper div that narrows nothing is
+ *      exactly the noise this exists to drop, and it is dropped.
+ *   3. **Stop at a unique id**, for the reason in partCandidates.
+ *   4. **Fall back to the positional path** when even that is ambiguous — unchanged, and still
+ *      the thing that always describes one node.
+ *
+ * Shortening is only safe because the verification it inherits is real: every candidate is run
+ * against the live document with `matchesExactly` — one node, and that node is this one — before
+ * it is returned. It is a search over verified candidates, not a guess at a prettier string.
+ *
+ * The element that prompted the question is the worked example — 118 characters to 21, naming
+ * the same node:
+ *
+ *   before  #main > section.section.statement:nth-of-type(2) >
+ *             div.container.statement__inner > div.statement__story:nth-of-type(1)
+ *   after   div.statement__story
+ *
+ * Measured 2026-09-22 against the old builder over 1,809 elements sampled from six routes (`/`,
+ * `/about-us`, `/faqs`, `/payment-and-insurance`, `/individual-services/individual-therapy`,
+ * `/evaluative-services/forensic-evaluations`). The method, because a number is worth only the
+ * run behind it: build a selector for every sampled element on one load, then count each one
+ * with `querySelectorAll` on a GENUINELY fresh load in a new browser context — never on the DOM
+ * it was built against, which always flatters it.
+ *
+ *   dead (0 matches on reload)   0 → 0        no selector got worse
+ *   ambiguous (>1 on reload)     0 → 0
+ *   average length               175 → 57 characters
+ *   average parts                5.9 → 2.2
+ *   carrying an :nth-of-type     96.6% → 63.5%
+ *
+ * That last figure is the honest one: two thirds of elements still take a positional qualifier,
+ * and on inspection they have earned it — `a.navbar__card:nth-of-type(3)` is the third of four
+ * identical cards, and no class tells them apart. What has gone is the *redundant* qualifier:
+ * `span.navbar__card-arrow` inside that card no longer repeats the index its ancestor already
+ * settled, which is why the combination search tries the plain form again after an ancestor is
+ * retained rather than only before.
+ *
+ * The carousel case separately, since a Swiper selector is the one that historically died: 80
+ * elements inside `.swiper` on `/`, selectors built with the carousel ADVANCED two slides, then
+ * counted on a fresh un-advanced load — 0 dead and 0 ambiguous, before and after.
+ */
+function cssPathOf(el) {
+	if (!el || el.nodeType !== 1) return '';
+	const doc = el.ownerDocument;
+	const root = doc.documentElement;
+
+	let levels = [partCandidates(el)];
+	for (const candidate of selectorCombos(levels)) if (matchesExactly(candidate, el)) return candidate;
+
+	let matches = countMatches(mostSpecific(levels), doc);
+	let hops = 0;
+	for (
+		let node = el.parentElement;
+		node && node !== root && hops < MAX_SELECTOR_HOPS;
+		node = node.parentElement, hops++
+	) {
+		const ancestor = partCandidates(node);
+		const trial = [ancestor].concat(levels);
+		for (const candidate of selectorCombos(trial)) if (matchesExactly(candidate, el)) return candidate;
+
+		// Keep the ancestor only when it actually cut the field. A wrapper div that narrows
+		// nothing is exactly the noise this search exists to drop, so it is dropped and the
+		// walk carries on past it.
+		const count = countMatches(mostSpecific(trial), doc);
+		if (count > 0 && count < matches) {
+			levels = trial;
+			matches = count;
+		}
+		if (ancestor.anchored) break;
+		if (levels.length >= MAX_SELECTOR_LEVELS) break;
+	}
+
+	const best = mostSpecific(levels);
+	if (matchesExactly(best, el)) return best;
+	const positional = nthChildPath(el);
+	if (matchesExactly(positional, el)) return positional;
+	return best || positional;
+}
+
+/**
+ * The element's box in DOCUMENT coordinates — getBoundingClientRect() is viewport-relative,
+ * so the page's scroll offset has to be added back. The contract's `rect` and Playwright's
+ * screenshot `clip` are both document-relative, which is why this must not be skipped and
+ * why the server must not add `scroll` to it a second time.
+ */
+function docRect(el, scrollX, scrollY) {
+	const r = el.getBoundingClientRect();
+	return {
+		x: Math.round(r.left + scrollX),
+		y: Math.round(r.top + scrollY),
+		width: Math.round(r.width),
+		height: Math.round(r.height),
+	};
+}
+
+/** True for a path that would leak a machine-local location into a ticket. */
+function looksAbsolute(value) {
+	return /^\//.test(value) || /^[A-Za-z]:[\\/]/.test(value) || /^file:/i.test(value);
+}
+
+/* ------------------------------------------------------------------ frames */
+
+/**
+ * The component lab renders every story inside an <iframe> of `/lab/stories/<id>` — one in the
+ * viewport configurator (`#vp-frame`, astro-lab/src/shell/Viewport.astro) and one per card in the
+ * grid (CardGrid.astro). This toolbar lives in the PARENT document, so until 2026-09-21 a click
+ * on a story landed on the iframe ELEMENT and the ticket described the shell instead of the
+ * thing that was pointed at. Reproduced that day as PIN-005: `selector: '#vp-frame'`,
+ * `source: unresolved`, `url: /lab/viewport/…`, a 1440x900 rect and the iframe's own tag as
+ * `outer_html`. Nothing in it names an element.
+ *
+ * Every lab frame is same-origin — same dev server, same port — so `contentDocument` is readable
+ * and the hit test simply keeps going. Three things travel with it, and the third is the one that
+ * fails silently if it is got wrong:
+ *
+ *   · the POINT goes IN, through whatever scale the parent applied. The configurator scales a
+ *     wrapper DIV around the frame; the card grid scales the frame itself. Neither is special-cased.
+ *   · the GEOMETRY comes back OUT, because the highlight and the chip are painted in the TOP
+ *     document and have to land over the right pixels there.
+ *   · the TICKET describes the INNER document and nothing else — its url, its viewport, its
+ *     scroll, its document-coordinate rect. `shot.mjs` re-loads `url` and clips `rect` against
+ *     THAT page, so a ticket carrying the shell's url and the story's rect photographs the wrong
+ *     document and leaves a clean trail behind it. Taking all four from `el.ownerDocument`'s own
+ *     window is what makes the parent's transform structurally irrelevant: a scaled iframe does
+ *     not change its content window's `innerWidth`, and a rect measured inside the frame never
+ *     saw the transform at all.
+ *
+ * A frame this cannot see into is not an error. It is picked as an element in its own right and
+ * the reason is said out loud in the panel.
+ */
+
+/** The frame's document, or null when it is cross-origin, empty, or not loaded yet. */
+function frameDocument(frame) {
+	try {
+		const doc = frame.contentDocument;
+		return doc && doc.documentElement ? doc : null;
+	} catch {
+		return null; // cross-origin: touching contentDocument throws
+	}
+}
+
+/**
+ * Whether every transform between `el` and its document root is a plain scale and/or translate.
+ * A rotation, skew, mirror, or 3D transform cannot be undone by dividing by a ratio of widths, so
+ * a frame under one is picked as an element rather than entered with geometry that would be
+ * quietly wrong.
+ */
+function isAxisAligned(el) {
+	const win = el.ownerDocument && el.ownerDocument.defaultView;
+	if (!win) return false;
+	for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
+		const value = win.getComputedStyle(node).transform;
+		if (!value || value === 'none') continue;
+		let m;
+		try {
+			m = new win.DOMMatrixReadOnly(value);
+		} catch {
+			return false;
+		}
+		if (!m.is2D) return false;
+		if (Math.abs(m.b) > 1e-6 || Math.abs(m.c) > 1e-6) return false;
+		if (m.a <= 0 || m.d <= 0) return false;
+	}
+	return true;
+}
+
+/**
+ * How a point in the PARENT's viewport maps into this frame's own viewport.
+ *
+ * `getBoundingClientRect()` is the VISUAL box — every transform between the frame and the root
+ * has already been applied to it — while `offsetWidth`/`offsetHeight` is the LAYOUT box, which a
+ * transform never touches. Their ratio is therefore the total accumulated scale, wherever in the
+ * ancestor chain it was applied: the configurator scales `.vp__wrapper` around the frame and the
+ * card grid scales the frame itself, and this reads both without knowing which.
+ *
+ * Border and padding are removed in VISUAL px (they are layout px, so they scale too), because
+ * the frame's content box — not its border box — is what its viewport coordinates start from.
+ */
+function frameGeometry(frame) {
+	const rect = frame.getBoundingClientRect();
+	const ow = frame.offsetWidth;
+	const oh = frame.offsetHeight;
+	if (!ow || !oh || !rect.width || !rect.height) return null;
+	if (!isAxisAligned(frame)) return null;
+	const win = frame.ownerDocument.defaultView;
+	const style = win.getComputedStyle(frame);
+	const scaleX = rect.width / ow;
+	const scaleY = rect.height / oh;
+	const px = (name) => parseFloat(style[name]) || 0;
+	return {
+		scaleX,
+		scaleY,
+		left: rect.left + (px('borderLeftWidth') + px('paddingLeft')) * scaleX,
+		top: rect.top + (px('borderTopWidth') + px('paddingTop')) * scaleY,
+	};
+}
+
+/**
+ * Live geometry for a whole chain of frames, outermost first. Recomputed on every use rather
+ * than cached, because a scroll or a resize anywhere in the chain moves all of it.
+ * @returns {Array|null} null when any hop has gone away or stopped being translatable.
+ */
+function chainGeometry(frames) {
+	const geos = [];
+	for (const frame of frames) {
+		if (!frame || !frame.isConnected) return null;
+		const geo = frameGeometry(frame);
+		if (!geo) return null;
+		geos.push(geo);
+	}
+	return geos;
+}
+
+/** A rect in the innermost frame's viewport coordinates, expressed in the TOP document's. */
+function outward(geos, rect) {
+	let left = rect.left;
+	let top = rect.top;
+	let width = rect.width;
+	let height = rect.height;
+	for (let i = geos.length - 1; i >= 0; i--) {
+		const g = geos[i];
+		left = g.left + left * g.scaleX;
+		top = g.top + top * g.scaleY;
+		width *= g.scaleX;
+		height *= g.scaleY;
+	}
+	return { left, top, width, height, right: left + width, bottom: top + height };
+}
+
+/** `el`'s box in the TOP document's viewport coordinates, or null when the chain has broken. */
+function viewportRect(el, frames) {
+	const geos = chainGeometry(frames || []);
+	if (!geos) return null;
+	return outward(geos, el.getBoundingClientRect());
+}
+
+/**
+ * The iframe to descend into for a point that hit `el`, or null.
+ *
+ * Two shapes, because the lab has both. The configurator's `#vp-frame` takes pointer events, so
+ * it arrives as `el` itself. The grid's thumbnails carry `pointer-events: none` (CardGrid.astro,
+ * so the card stays one link), which means `elementsFromPoint` never returns them at all and the
+ * hit is the `.lab-card__thumb` wrapper — the frame has to be found INSIDE what was hit. Only a
+ * descendant counts: a pill drawn over a thumbnail is a pill, not the story underneath it.
+ */
+function frameUnder(el, x, y) {
+	if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') return el;
+	if (!el.getElementsByTagName) return null;
+	for (const frame of el.getElementsByTagName('iframe')) {
+		const r = frame.getBoundingClientRect();
+		if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return frame;
+	}
+	return null;
+}
+
+/** The path of the document `el` actually lives in — the story's, not the shell's. */
+function documentPath(el) {
+	const win = el.ownerDocument && el.ownerDocument.defaultView;
+	if (!win) return '';
+	return win.location.pathname + win.location.search;
+}
+
+/**
+ * Walk up to the nearest ancestor stamped by the source-stamp Vite plugin.
+ * Re-read from the live DOM on every pick: another toolbar app may have mutated the tree
+ * since the last look (the built-in audit app strips `data-astro-source-file` and
+ * `data-astro-source-loc` in apps/audit/annotations.js:12-16 — it does not touch this
+ * attribute, but nothing guarantees the next app is as polite).
+ */
+function resolveSource(el) {
+	if (!el || typeof el.closest !== 'function') return { source: null, error: null };
+	const holder = el.closest(`[${SRC_ATTR}]`);
+	if (!holder) return { source: null, error: null };
+	const raw = (holder.getAttribute(SRC_ATTR) || '').trim();
+	if (!raw) return { source: null, error: null };
+	if (looksAbsolute(raw)) {
+		return {
+			source: null,
+			error: `The source attribute on <${holder.tagName.toLowerCase()}> is an absolute path. Refusing to put it in a ticket.`,
+		};
+	}
+	return { source: raw, error: null };
+}
+
+function truncate(value, limit) {
+	const text = String(value ?? '');
+	return text.length > limit ? text.slice(0, limit) : text;
+}
+
+
+/* ------------------------------------------------------------ the ticket panel: the contract */
+
+/**
+ * Where the board is served — the panel fetches it for the ticket list, and the head's "Board ↗"
+ * button opens it.
+ *
+ * It is the RESOLVED `route` option, delivered by `virtual:orbytes-pin/config.mjs` (› index.mjs,
+ * `pinConfigPlugin`). It was the literal `'/pin'` until 2026-09-22, which was wrong for any site
+ * that set `pin: { route: "/__pin" }` — the panel fetched a path the middleware does not serve and
+ * showed an empty list, and the new button would have opened the same empty tab. The fallback
+ * is the documented default, for the one case the virtual module cannot
+ * cover: this file imported directly, outside the integration that generates it.
+ */
+const BOARD_ROUTE = (pinConfig && pinConfig.route) || '/pin';
+
+/**
+ * The status vocabulary, ruled 2026-09-22. Six values, in this order:
+ *
+ *   Backlog           an agent should NOT pick this up yet
+ *   Ready for agent   replaces `To Do` — an agent may start
+ *   In Progress
+ *   Ready for review  an agent has finished; this is THE HUMAN REVIEW QUEUE
+ *   Resolved          a human has accepted it. Only a human ever sets it — no agent, ever.
+ *   Cancelled         an archive. It must not take up space or override anything.
+ *
+ * The panel has exactly TWO tabs, which is fixed and not a preference, so the six map onto them:
+ * **Open is everything that is not `Resolved` and not `Cancelled`**, `Resolved` is its own tab, and
+ * `Cancelled` appears in neither and draws no marker — drawing an archived ticket on the page is
+ * precisely the "taking up space" the status exists to stop. It stays reachable on `/pin`.
+ *
+ * These names are for CLASSIFYING and LABELLING only. Every write sends the status string the
+ * board itself reported (› `setStatus`), never a string from this list, because `expect` is
+ * compared against what is on disk and the two vocabularies are mid-migration: `tickets.mjs` is
+ * the owner of `STATUSES` and this panel must not race it.
+ */
+const STATUS_RESOLVED = 'Resolved';
+
+/** Statuses written before 2026-09-22, and what they read as today. Never emitted. */
+const LEGACY_STATUS = Object.freeze({ 'to do': 'Ready for agent', done: STATUS_RESOLVED });
+
+/**
+ * Where "Reopen" sends a ticket, most-wanted first. Reopening means "this needs more work", so it
+ * lands back in the agent's lane rather than in the human review queue.
+ *
+ * It is a PREFERENCE LIST rather than one value because the target is chosen against the statuses
+ * the board actually reports (› `ticketsFromBoardHtml`), not against this file's idea of them. The
+ * write endpoint refuses any status outside `STATUSES`, and `STATUSES` lives in a file this panel
+ * does not own and is being changed in parallel — so picking from what the board renders is the
+ * only way this control cannot break the moment the vocabulary moves under it.
+ */
+const REOPEN_PREFERENCE = ['Ready for agent', 'To Do', 'Backlog', 'In Progress'];
+
+/** Per-viewer, survives a reload, degrades silently. Not shared, not in a ticket. */
+const SHOW_RESOLVED_KEY = 'orbytes-pin:show-resolved-markers';
+
+/** The marker glyph's box, in CSS px. The tip is the bottom centre of the viewBox. */
+const MARKER_W = 26;
+const MARKER_H = 34;
+
+/** A status as this panel classifies it — one word, from any of the vocabularies in play. */
+function statusKind(raw) {
+	const s = String(raw ?? '').trim().toLowerCase();
+	if (s === 'resolved' || s === 'done') return 'resolved';
+	if (s === 'cancelled' || s === 'canceled') return 'cancelled';
+	if (s === 'ready for review') return 'review';
+	if (s === 'ready for agent' || s === 'to do' || s === 'todo') return 'agent';
+	if (s === 'backlog') return 'backlog';
+	if (s === 'in progress') return 'progress';
+	return 'other';
+}
+
+/** The status in today's words. A legacy value is SHOWN as what it reads as, never rewritten. */
+function statusLabel(raw) {
+	const s = String(raw ?? '').trim();
+	return LEGACY_STATUS[s.toLowerCase()] ?? (s || 'No status');
+}
+
+const isResolvedStatus = (raw) => statusKind(raw) === 'resolved';
+const isCancelledStatus = (raw) => statusKind(raw) === 'cancelled';
+
+/**
+ * Open is a NEGATIVE test on purpose — not `Resolved`, not `Cancelled` — so a status nobody here
+ * has heard of still appears somewhere rather than vanishing. The one failure this panel must not
+ * have is a ticket that exists on disk and is on no tab.
+ */
+const isOpenStatus = (raw) => !isResolvedStatus(raw) && !isCancelledStatus(raw);
+
+/** Where a status sorts inside the Open tab: the review queue first, then work not yet begun. */
+const OPEN_ORDER = { review: 0, progress: 1, agent: 2, backlog: 3, other: 4 };
+
+/**
+ * The tickets, read from the board's own machine-readable payload.
+ *
+ * This panel does NOT parse a ticket file. `collectTickets`/`parseTicket` (board.mjs, tickets.mjs)
+ * are the reader, they run on the server, and `renderBoard` already serialises each ticket it read
+ * into a `<script type="application/json" class="card-data">` block beside its card — that block is
+ * what this reads. A second markdown parser in the browser is how three earlier bugs in this system
+ * happened; there is no read endpoint to use instead, so the board's own emission is the nearest
+ * thing to one, and it is generated from the same call the board draws itself from.
+ *
+ * Two other things come out of the same document rather than being hardcoded here:
+ *   · `apiPath` — the write endpoint, from `[data-board] data-api`. The board only carries it when
+ *     it is writable, so its absence is the honest answer to "can this surface write?".
+ *   · `statuses` — every status the board renders a column for, which is the live vocabulary from
+ *     `STATUSES` including anything a ticket carries that is not in it.
+ *
+ * Refuses rather than warns: cards present with no payload means the board changed shape, and a
+ * silently short list would be worse than a sentence saying so.
+ */
+function ticketsFromBoardHtml(html, route = BOARD_ROUTE) {
+	const doc = new DOMParser().parseFromString(String(html ?? ''), 'text/html');
+	const board = doc.querySelector('[data-board]');
+	const cards = doc.querySelectorAll('[data-card]');
+	const blocks = doc.querySelectorAll('script.card-data');
+	if (!board && !cards.length && !doc.querySelector('.none, .broken')) {
+		throw new Error(`${route} did not answer with the pin board — is the orbytes-pin integration loaded?`);
+	}
+	if (cards.length && !blocks.length) {
+		throw new Error(
+			`the board no longer puts a card-data payload beside each card, which is where this panel reads tickets from — the panel needs updating alongside ${route}.`,
+		);
+	}
+	const tickets = [];
+	for (const block of blocks) {
+		try {
+			tickets.push(JSON.parse(block.textContent || ''));
+		} catch (error) {
+			throw new Error(`a card on ${route} carried a payload this panel could not read: ${error && error.message}`);
+		}
+	}
+	const statuses = Array.prototype.map
+		.call(doc.querySelectorAll('[data-col][data-status]'), (col) => col.getAttribute('data-status'))
+		.filter(Boolean);
+	const broken = Array.prototype.map.call(doc.querySelectorAll('.broken li code'), (el) => el.textContent);
+	return { tickets, apiPath: board ? board.getAttribute('data-api') : null, statuses, broken };
+}
+
+/** `/a/` and `/a` are the same page; a query string is part of the address and is not dropped. */
+function normalisePath(value) {
+	const raw = String(value ?? '');
+	if (!raw) return '';
+	const cut = raw.indexOf('?');
+	const path = cut === -1 ? raw : raw.slice(0, cut);
+	const query = cut === -1 ? '' : raw.slice(cut);
+	return (path.length > 1 ? path.replace(/\/+$/, '') : path) + query;
+}
+
+const samePath = (a, b) => normalisePath(a) === normalisePath(b);
+
+/** `3d`, `4h`, `now` — short enough for a row, from a `YYYY-MM-DD` or any parseable date. */
+function ageLabel(value, now = Date.now()) {
+	const at = Date.parse(String(value ?? ''));
+	if (!Number.isFinite(at)) return '';
+	const seconds = Math.max(0, (now - at) / 1000);
+	if (seconds < 90) return 'now';
+	const minutes = seconds / 60;
+	if (minutes < 60) return `${Math.round(minutes)}m`;
+	const hours = minutes / 60;
+	if (hours < 24) return `${Math.round(hours)}h`;
+	const days = hours / 24;
+	if (days < 7) return `${Math.round(days)}d`;
+	const weeks = days / 7;
+	if (weeks < 6) return `${Math.round(weeks)}w`;
+	return `${Math.round(days / 30)}mo`;
+}
+
+/** `PIN-007` → `7`, for the number drawn inside a marker. */
+function ticketNumber(id) {
+	const m = /(\d+)/.exec(String(id ?? ''));
+	return m ? String(Number(m[1])) : '';
+}
+
+/* ------------------------------------------------------------------ the app */
+
+export default defineToolbarApp({
+	init(canvas, app, server) {
+		/** Every shadow host between the pick surface and the document, so the hit test can
+		 * ignore this app's own chrome. `document.elementsFromPoint` retargets shadow content
+		 * to its host, so skipping the hosts skips the surface, the window, the highlights,
+		 * the chip and the toolbar bar in one test. */
+		const ownHosts = [];
+		{
+			let root = canvas;
+			while (root && root.host) {
+				ownHosts.push(root.host);
+				root = root.host.getRootNode ? root.host.getRootNode() : null;
+			}
+		}
+
+		let mode = 'idle'; // idle | picking | selected
+		let hoverEl = null;
+		let selectedEl = null;
+		/**
+		 * The climb. `chain` is what was clicked at index 0 and each ancestor above it after
+		 * that, stopping short of <body>; `climbIndex` says which one the pin currently
+		 * describes, and `selectedEl` is always `chain[climbIndex]`.
+		 *
+		 * Index 0 is kept as an ELEMENT, not as a selector or a remembered index, because
+		 * climbing back down has to land on the thing actually pointed at — a button among
+		 * four identical ones is not recoverable from a description of where it was.
+		 */
+		let chain = [];
+		let climbIndex = 0;
+		// The chain of same-origin iframes each of those lives inside, outermost first. Empty on
+		// an ordinary page; one deep in the lab's viewport configurator and card grid.
+		let hoverFrames = [];
+		let selectedFrames = [];
+		let busy = false;
+		let replyTimer = null;
+		let swallowEscapeKeyup = false;
+		let rafPending = false;
+		let lastPointer = { x: 0, y: 0 };
+		/** The timer that clears a transient acknowledgement. Null while a failure is on screen. */
+		let ackTimer = null;
+
+		/* ---------- chrome ---------- */
+
+		const surface = document.createElement('div');
+		surface.setAttribute('data-orbytes-pin-ui', 'surface');
+		Object.assign(surface.style, {
+			position: 'fixed',
+			inset: '0',
+			zIndex: String(Z.surface),
+			cursor: 'crosshair',
+			background: 'transparent',
+		});
+
+		const hoverHighlight = makeHighlight(Z.hover, 'blue');
+		const selectedHighlight = makeHighlight(Z.selected, 'purple');
+		const chip = makeChip();
+
+		function makeHighlight(zIndex, style) {
+			const el = createHighlight({ top: 0, left: 0, width: 0, height: 0 });
+			el.highlightStyle = style;
+			el.tabIndex = -1;
+			el.style.display = 'none';
+			el.style.zIndex = String(zIndex);
+			// createHighlight() sets tabIndex 0 and leaves pointer events on, which would let
+			// the highlight sit between the cursor and the pick surface and freeze hovering.
+			el.style.pointerEvents = 'none';
+			return el;
+		}
+
+		function makeChip() {
+			const el = document.createElement('div');
+			el.setAttribute('data-orbytes-pin-ui', 'chip');
+			Object.assign(el.style, {
+				position: 'absolute',
+				display: 'none',
+				zIndex: String(Z.chip),
+				pointerEvents: 'none',
+				maxWidth: '60vw',
+				overflow: 'hidden',
+				textOverflow: 'ellipsis',
+				whiteSpace: 'nowrap',
+				padding: '3px 8px',
+				borderRadius: '9999px',
+				border: '1px solid rgba(113, 24, 226, 1)',
+				background: '#13151A',
+				color: '#fff',
+				font: '500 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace',
+				boxShadow: '0 2px 6px rgba(19, 21, 26, 0.5)',
+			});
+			return el;
+		}
+
+		const win = createWindowElement(`
+			<style>
+				[hidden] { display: none !important; }
+				.pin { display: flex; flex-direction: column; gap: 12px; overflow: auto; }
+				.pin-head { display: flex; align-items: center; gap: 8px; }
+				.pin-head h1 {
+					margin: 0; font-size: 16px; font-weight: 600; color: #fff;
+					display: flex; align-items: center; gap: 8px;
+				}
+				.pin-head astro-dev-toolbar-icon { width: 1em; height: 1em; display: block; }
+				.pin-spacer { flex: 1; }
+				.pin-hint { margin: 0; font-size: 13px; line-height: 1.5; }
+				.pin-kbd {
+					font: 600 11px ui-monospace, SFMono-Regular, Menlo, monospace;
+					border: 1px solid rgba(145, 152, 173, 0.6); border-radius: 4px;
+					padding: 1px 5px; color: #fff;
+				}
+				/* One line, always. It scrolls sideways rather than wrapping, because a chain
+				   that grows a second row pushes the comment box down the panel — and the box
+				   is the thing being typed or dictated into. */
+				.pin-crumbs {
+					display: flex; align-items: center; gap: 2px;
+					overflow-x: auto; overflow-y: hidden; white-space: nowrap;
+					scrollbar-width: thin; padding-bottom: 2px;
+				}
+				.pin-crumbs[hidden] { display: none; }
+				.pin-crumbs button {
+					flex: none; cursor: pointer; border-radius: 6px;
+					padding: 2px 7px; border: 1px solid transparent; background: transparent;
+					color: rgba(145, 152, 173, 1);
+					font: 500 11px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
+				}
+				.pin-crumbs button:hover { color: #fff; background: rgba(52, 56, 65, 1); }
+				.pin-crumbs button[data-current] {
+					color: #fff; background: rgba(113, 24, 226, 0.35);
+					border-color: rgba(113, 24, 226, 1);
+				}
+				.pin-crumbs .sep { flex: none; color: rgba(145, 152, 173, 0.5); font-size: 10px; }
+				.pin-target {
+					display: flex; flex-direction: column; gap: 4px;
+					padding: 8px 10px; border-radius: 8px;
+					background: rgba(27, 30, 36, 1); border: 1px solid rgba(52, 56, 65, 1);
+					font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+					word-break: break-all;
+				}
+				.pin-target .src { color: #fff; }
+				.pin-target .src[data-unresolved] { color: rgba(255, 236, 179, 1); }
+				.pin-target .sel { color: rgba(145, 152, 173, 1); }
+				.pin-target .url { color: rgba(145, 152, 173, 1); }
+				.pin-target .url::before { content: '@ '; }
+				#pin-comment {
+					width: 100%; box-sizing: border-box; min-height: 92px; resize: vertical;
+					padding: 10px; border-radius: 8px;
+					border: 1px solid rgba(52, 56, 65, 1); background: rgba(19, 21, 26, 1);
+					color: #fff; font: 14px/1.5 ui-sans-serif, system-ui, sans-serif;
+				}
+				#pin-comment:focus { outline: 2px solid rgba(113, 24, 226, 1); outline-offset: 1px; }
+				.pin-row { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+				.pin-dispatch {
+					display: flex; align-items: center; gap: 8px; font-size: 13px;
+					padding: 4px 10px 4px 4px; border-radius: 9999px;
+					border: 1px solid rgba(52, 56, 65, 1);
+				}
+				.pin-dispatch .on { color: #fff; font-weight: 600; }
+				/* ONE line, never a list. The four colours are the ones the running log used, to
+				   the value — this replaced the log's behaviour, not its look. */
+				.pin-status {
+					margin: 0; font-size: 12px; line-height: 1.5; cursor: pointer;
+					display: flex; gap: 6px; align-items: baseline;
+				}
+				.pin-status[hidden] { display: none; }
+				.pin-status[data-level="error"] { color: rgba(249, 196, 215, 1); }
+				.pin-status[data-level="warn"] { color: rgba(255, 236, 179, 1); }
+				.pin-status[data-level="ok"] { color: rgba(213, 249, 196, 1); }
+				.pin-status[data-level="info"] { color: rgba(191, 193, 201, 1); }
+				/* A failure stays until it is dismissed or replaced, so it says so. */
+				.pin-status::after {
+					content: '✕'; margin-left: auto; opacity: 0.45; font-size: 11px;
+				}
+				.pin-status:hover::after { opacity: 1; }
+				[data-busy] { opacity: 0.5; pointer-events: none; }
+			</style>
+			<div class="pin">
+				<div class="pin-head">
+					<h1><astro-dev-toolbar-icon icon="file-search"></astro-dev-toolbar-icon>orbytes pin</h1>
+					<span class="pin-spacer"></span>
+					<!-- Two different things, deliberately: "Tickets" toggles the in-page rail
+					     over this page, "Board" opens the full kanban at BOARD_ROUTE in its own
+					     tab. The tab is where a ticket is dragged between statuses and where a
+					     screenshot is looked at full size — which is why there is a way to
+					     reach it from here (added 2026-09-22). -->
+					<astro-dev-toolbar-button id="pin-tickets" size="small" button-style="ghost">Tickets</astro-dev-toolbar-button>
+					<astro-dev-toolbar-button id="pin-open-board" size="small" button-style="ghost">Board ↗</astro-dev-toolbar-button>
+					<astro-dev-toolbar-badge id="pin-mode" size="small" badge-style="gray">idle</astro-dev-toolbar-badge>
+				</div>
+
+				<p class="pin-hint" id="pin-hint"></p>
+
+				<section id="pin-form" hidden>
+					<!-- The ancestor chain of what was clicked, outermost first, so it reads in
+					     the same direction as the selector underneath it. Clicking one moves the
+					     pin to that element; ⌥↑ / ⌥↓ do the same without leaving the keyboard. -->
+					<nav class="pin-crumbs" id="pin-crumbs" aria-label="Ancestors of the picked element" hidden></nav>
+					<div class="pin-target">
+						<span class="src" id="pin-src"></span>
+						<span class="sel" id="pin-sel"></span>
+						<!-- The page the ticket will name, which is the page the screenshot will be
+						     taken of. On the lab that is the STORY route inside the frame, not the
+						     shell around it, and seeing it is the only way to catch it being wrong
+						     before a ticket is written. -->
+						<span class="url" id="pin-url"></span>
+					</div>
+					<textarea id="pin-comment" autocomplete="off" autocapitalize="sentences"
+						placeholder="What is wrong with it? Talk or type — this goes into the ticket verbatim."></textarea>
+					<div class="pin-row">
+						<span class="pin-dispatch">
+							<astro-dev-toolbar-toggle id="pin-dispatch" toggle-style="purple"></astro-dev-toolbar-toggle>
+							<span id="pin-dispatch-label">queue</span>
+						</span>
+						<astro-dev-toolbar-button id="pin-submit" size="small" button-style="purple">Create ticket</astro-dev-toolbar-button>
+						<astro-dev-toolbar-button id="pin-again" size="small" button-style="ghost">Pick another</astro-dev-toolbar-button>
+						<astro-dev-toolbar-button id="pin-cancel" size="small" button-style="ghost">Cancel</astro-dev-toolbar-button>
+					</div>
+				</section>
+
+				<section id="pin-idle" hidden>
+					<astro-dev-toolbar-button id="pin-start" size="small" button-style="purple">Pick an element</astro-dev-toolbar-button>
+				</section>
+
+				<p class="pin-status" id="pin-status" title="Dismiss" hidden></p>
+			</div>
+		`);
+
+		canvas.append(win, hoverHighlight, selectedHighlight, chip);
+		synchronizePlacementOnUpdate(app, canvas);
+
+		const ui = {
+			badge: win.querySelector('#pin-mode'),
+			hint: win.querySelector('#pin-hint'),
+			form: win.querySelector('#pin-form'),
+			idle: win.querySelector('#pin-idle'),
+			crumbs: win.querySelector('#pin-crumbs'),
+			src: win.querySelector('#pin-src'),
+			sel: win.querySelector('#pin-sel'),
+			url: win.querySelector('#pin-url'),
+			comment: win.querySelector('#pin-comment'),
+			dispatch: win.querySelector('#pin-dispatch'),
+			dispatchLabel: win.querySelector('#pin-dispatch-label'),
+			submit: win.querySelector('#pin-submit'),
+			again: win.querySelector('#pin-again'),
+			cancel: win.querySelector('#pin-cancel'),
+			start: win.querySelector('#pin-start'),
+			tickets: win.querySelector('#pin-tickets'),
+			openBoard: win.querySelector('#pin-open-board'),
+			status: win.querySelector('#pin-status'),
+		};
+
+		/* ---------- status ---------- */
+
+		/**
+		 * ONE line, not a log — ruled 2026-09-22, when the running log was found redundant and the
+		 * one thing worth keeping from it became a button that opens the pin tab. Until then this
+		 * was a running four-entry list
+		 * that narrated every step — *"Sending to the dev server…"*, *"Selection dropped."*,
+		 * *"PIN-002 written to backlog/tasks/…"* — most of it about things that had plainly
+		 * worked, and most of it repeating what the badge, the hint line and the target box
+		 * already said. Those calls are gone from their call sites, not merely hidden here.
+		 *
+		 * What survives, and why each is not commentary:
+		 *
+		 *   · A FAILURE — a refused ticket, a screenshot that did not happen, a selector that dies
+		 *     on reload — is the one thing nothing else on screen can say. It shows and it STAYS:
+		 *     no timer, so it cannot scroll away unread. Click it, or trigger the next message,
+		 *     to clear it.
+		 *   · The TICKET-WRITTEN ACK stays too, transiently. The contract makes a point of the
+		 *     panel confirming on the same synchronous tick as the write, in under 30ms
+		 *     (../../docs/PIN-CONTRACT.md › Screenshots), and a confirmation nobody can see is not
+		 *     a confirmation. It clears itself after ACK_MS.
+		 *   · A CAVEAT nothing else on screen reveals — pinning inside a frame, a climb that has
+		 *     run out of ancestors — is transient too.
+		 *
+		 * A new message always replaces the one before it. That is what makes this a status line
+		 * and not a shorter log.
+		 */
+		function say(level, message) {
+			const persistent = level === 'error' || level === 'warn';
+			clearTimeout(ackTimer);
+			ui.status.textContent = message;
+			ui.status.dataset.level = level;
+			ui.status.hidden = false;
+			if (!persistent) ackTimer = setTimeout(clearStatus, ACK_MS);
+		}
+
+		function clearStatus() {
+			clearTimeout(ackTimer);
+			ui.status.hidden = true;
+			ui.status.textContent = '';
+			ui.status.removeAttribute('data-level');
+		}
+
+		/** say(), minus the repeat — Escape and ⌥↑ both get pressed more than once. */
+		function sayOnce(level, message) {
+			if (!ui.status.hidden && ui.status.dataset.level === level && ui.status.textContent === message) {
+				return;
+			}
+			say(level, message);
+		}
+
+		ui.status.addEventListener('click', clearStatus);
+
+		/* ---------- the ticket panel ---------- */
+
+		/**
+		 * ONE token block for every colour, length and typeface the panel and the markers use.
+		 *
+		 * This package is being merged into the component lab and shipped as one app, and it is ruled
+		 * twice over — once for the lab, once for this board — that the chrome is standard across
+		 * every site and never takes the host site's styling. The lab does that with a namespaced
+		 * token set and one stylesheet. So everything below is declared once, here, under a `--pin-`
+		 * prefix: the merge repoints this block at the lab's tokens in a single edit instead of
+		 * someone hunting for literals through two thousand lines. Do not write a hex value, a px
+		 * value or a font stack anywhere else in the panel, the markers or their handlers.
+		 *
+		 * Not `--lab-*`: that stylesheet lives in another repo and is not present here, so naming it
+		 * would only break. The namespace is also what stops a consumer's own `--color-background`
+		 * reaching this chrome if the two ever share a document.
+		 *
+		 * **No bare element selectors.** Every rule is reached by class or by a scoped root — a bare
+		 * `div {}` or `button {}` in a shared stylesheet inherits down into the page being previewed,
+		 * which the lab learned the hard way.
+		 */
+		const panelStyle = document.createElement('style');
+		panelStyle.textContent = `
+			.pin-chrome {
+				/* colour — surfaces */
+				--pin-bg: rgba(19, 21, 26, 0.98);
+				--pin-bg-raised: rgba(27, 30, 36, 1);
+				--pin-bg-sunken: rgba(15, 17, 21, 1);
+				--pin-bg-hover: rgba(52, 56, 65, 1);
+				--pin-border: rgba(52, 56, 65, 1);
+				--pin-border-strong: rgba(71, 78, 94, 1);
+				/* colour — ink */
+				--pin-ink: #fff;
+				--pin-ink-dim: rgba(145, 152, 173, 1);
+				--pin-ink-faint: rgba(145, 152, 173, 0.62);
+				--pin-ink-bad: rgba(249, 196, 215, 1);
+				--pin-ink-warn: rgba(255, 236, 179, 1);
+				/* colour — this app's own accent, shared with the picker's highlights */
+				--pin-accent: rgba(113, 24, 226, 1);
+				--pin-accent-soft: rgba(113, 24, 226, 0.35);
+				/* colour — the two marker states. Ruled 2026-09-22: open pins blue, resolved grey. */
+				--pin-open: rgb(47, 123, 255);
+				--pin-open-ink: #fff;
+				--pin-resolved: rgb(139, 145, 158);
+				--pin-resolved-ink: #fff;
+				/* colour — Ready for review is the human review queue, and the thing the eye finds first */
+				--pin-review: rgb(255, 191, 0);
+				--pin-review-ink: rgb(26, 20, 0);
+				/* colour — Backlog means an agent must NOT start; it sits next to Ready for agent
+				   and means the opposite, so it is drawn as held back rather than as ready */
+				--pin-hold: rgba(145, 152, 173, 0.55);
+				--pin-hold-ink: rgba(19, 21, 26, 1);
+				/* a marker has to read on a white hero and on this site's near-black sections alike,
+				   so it carries its own light ring and its own dark shadow and depends on neither */
+				--pin-halo: rgba(255, 255, 255, 0.95);
+				--pin-marker-shadow: 0 2px 7px rgba(0, 0, 0, 0.55);
+				--pin-shadow: 0 10px 34px rgba(0, 0, 0, 0.5);
+				/* space */
+				--pin-space-1: 4px;
+				--pin-space-2: 8px;
+				--pin-space-3: 12px;
+				--pin-space-4: 16px;
+				--pin-radius: 8px;
+				--pin-radius-sm: 6px;
+				--pin-radius-pill: 9999px;
+				/* type */
+				--pin-font: ui-sans-serif, system-ui, -apple-system, sans-serif;
+				--pin-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+				--pin-fs-body: 13px;
+				--pin-fs-small: 11.5px;
+				--pin-fs-tiny: 10px;
+				--pin-fs-title: 14px;
+				--pin-lh: 1.45;
+				/* geometry */
+				--pin-panel-w: 384px;
+				--pin-panel-bottom: 76px;
+				--pin-thumb-w: 64px;
+				--pin-marker-w: ${MARKER_W}px;
+				--pin-marker-h: ${MARKER_H}px;
+				/* layering — above the page, below the comment window, which always wins */
+				--pin-z-marker: ${Z.marker};
+				--pin-z-panel: ${Z.panel};
+			}
+
+			.pin-panel {
+				position: fixed;
+				top: var(--pin-space-3);
+				right: var(--pin-space-3);
+				bottom: var(--pin-panel-bottom);
+				z-index: var(--pin-z-panel);
+				width: var(--pin-panel-w);
+				max-width: calc(100vw - var(--pin-space-3) * 2);
+				display: flex;
+				flex-direction: column;
+				box-sizing: border-box;
+				border: 1px solid var(--pin-border-strong);
+				border-radius: var(--pin-radius);
+				background: var(--pin-bg);
+				box-shadow: var(--pin-shadow);
+				color: var(--pin-ink);
+				font-family: var(--pin-font);
+				font-size: var(--pin-fs-body);
+				line-height: var(--pin-lh);
+				backdrop-filter: blur(6px);
+				overflow: hidden;
+			}
+			.pin-panel[hidden] { display: none; }
+
+			.pin-panel__head {
+				display: flex; align-items: center; gap: var(--pin-space-2);
+				padding: var(--pin-space-2) var(--pin-space-2) var(--pin-space-2) var(--pin-space-3);
+				border-bottom: 1px solid var(--pin-border);
+				flex: none;
+			}
+			.pin-panel__title { font-size: var(--pin-fs-title); font-weight: 600; }
+			.pin-panel__spacer { flex: 1; }
+			.pin-panel__icon {
+				flex: none; cursor: pointer; width: 26px; height: 26px; padding: 0;
+				display: flex; align-items: center; justify-content: center;
+				border: 1px solid transparent; border-radius: var(--pin-radius-sm);
+				background: transparent; color: var(--pin-ink-dim);
+				font-family: var(--pin-font); font-size: var(--pin-fs-title); line-height: 1;
+			}
+			.pin-panel__icon:hover { background: var(--pin-bg-hover); color: var(--pin-ink); }
+			.pin-panel__icon:focus-visible { outline: 2px solid var(--pin-accent); outline-offset: 1px; }
+
+			.pin-panel__tabs {
+				display: flex; gap: var(--pin-space-1); flex: none;
+				padding: var(--pin-space-2) var(--pin-space-2) 0;
+			}
+			.pin-panel__tab {
+				flex: 1; cursor: pointer; padding: var(--pin-space-2); border-radius: var(--pin-radius-sm);
+				border: 1px solid transparent; background: transparent; color: var(--pin-ink-dim);
+				font-family: var(--pin-font); font-size: var(--pin-fs-body); font-weight: 600;
+				display: flex; align-items: center; justify-content: center; gap: var(--pin-space-2);
+			}
+			.pin-panel__tab:hover { color: var(--pin-ink); background: var(--pin-bg-hover); }
+			.pin-panel__tab[aria-selected="true"] {
+				color: var(--pin-ink); background: var(--pin-accent-soft); border-color: var(--pin-accent);
+			}
+			.pin-panel__tab-count {
+				font-family: var(--pin-font-mono); font-size: var(--pin-fs-small); font-weight: 700;
+				padding: 1px 6px; border-radius: var(--pin-radius-pill);
+				background: var(--pin-bg-sunken); color: var(--pin-ink);
+			}
+
+			.pin-panel__switch {
+				display: flex; align-items: center; gap: var(--pin-space-2); flex: none;
+				padding: var(--pin-space-2) var(--pin-space-3);
+				color: var(--pin-ink-dim); font-size: var(--pin-fs-small);
+			}
+			.pin-panel__switch-text { cursor: pointer; }
+
+			.pin-panel__list {
+				/* min-height: 0 is load-bearing, not tidying. A flex item defaults to
+				   min-height: auto, so without it this column refuses to shrink below its
+				   content, grows past the panel's own bottom edge and is then clipped by the
+				   panel's overflow: hidden — measured here 2026-09-22 with an expanded ticket,
+				   whose Resolve button sat 369px below the panel, invisible and unclickable,
+				   while scrollTop stayed 0 because nothing was scrollable. */
+				flex: 1; min-height: 0; overflow-y: auto; overflow-x: hidden;
+				padding: 0 var(--pin-space-2) var(--pin-space-2);
+				scrollbar-width: thin;
+			}
+			.pin-panel__group {
+				margin: var(--pin-space-3) 0 var(--pin-space-1);
+				padding: 0 var(--pin-space-1);
+				color: var(--pin-ink-faint);
+				font-size: var(--pin-fs-tiny); font-weight: 700;
+				text-transform: uppercase; letter-spacing: 0.09em;
+			}
+			.pin-panel__empty {
+				margin: var(--pin-space-4) var(--pin-space-2);
+				color: var(--pin-ink-dim); font-size: var(--pin-fs-body);
+			}
+			.pin-panel__note {
+				flex: none; margin: 0; padding: var(--pin-space-2) var(--pin-space-3);
+				border-top: 1px solid var(--pin-border);
+				color: var(--pin-ink-dim); font-size: var(--pin-fs-small);
+			}
+			.pin-panel__note[data-level="error"] { color: var(--pin-ink-bad); }
+			.pin-panel__note[data-level="warn"] { color: var(--pin-ink-warn); }
+			.pin-panel__note[hidden] { display: none; }
+
+			.pin-row {
+				border: 1px solid var(--pin-border); border-radius: var(--pin-radius);
+				background: var(--pin-bg-raised); margin-top: var(--pin-space-2);
+				overflow: hidden;
+			}
+			.pin-row[data-kind="review"] { border-left: 3px solid var(--pin-review); }
+			.pin-row[data-current] { border-color: var(--pin-accent); }
+			.pin-row__summary {
+				width: 100%; box-sizing: border-box; cursor: pointer; text-align: left;
+				display: flex; gap: var(--pin-space-2); align-items: flex-start;
+				padding: var(--pin-space-2); border: 0; background: transparent;
+				color: var(--pin-ink); font-family: var(--pin-font); font-size: var(--pin-fs-body);
+			}
+			.pin-row__summary:hover { background: var(--pin-bg-hover); }
+			.pin-row__summary:focus-visible { outline: 2px solid var(--pin-accent); outline-offset: -2px; }
+			.pin-row__thumb {
+				flex: none; width: var(--pin-thumb-w); aspect-ratio: 4 / 3; overflow: hidden;
+				border-radius: var(--pin-radius-sm); background: var(--pin-bg-sunken);
+				border: 1px solid var(--pin-border);
+				display: flex; align-items: center; justify-content: center;
+				color: var(--pin-ink-faint); font-size: var(--pin-fs-tiny); text-align: center;
+			}
+			.pin-row__shot { width: 100%; height: 100%; object-fit: cover; display: block; }
+			.pin-row__main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: var(--pin-space-1); }
+			.pin-row__title {
+				font-weight: 600; line-height: 1.35;
+				display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden;
+			}
+			.pin-row__meta { display: flex; align-items: center; gap: var(--pin-space-1); flex-wrap: wrap; }
+			.pin-row__id {
+				font-family: var(--pin-font-mono); font-size: var(--pin-fs-small); color: var(--pin-ink-dim);
+			}
+			.pin-row__age { font-size: var(--pin-fs-small); color: var(--pin-ink-faint); }
+			.pin-row__src {
+				font-family: var(--pin-font-mono); font-size: var(--pin-fs-tiny); color: var(--pin-ink-faint);
+				overflow: hidden; text-overflow: ellipsis; white-space: nowrap; direction: rtl; text-align: left;
+			}
+
+			.pin-chip {
+				font-size: var(--pin-fs-tiny); font-weight: 700; line-height: 1.6;
+				padding: 0 var(--pin-space-2); border-radius: var(--pin-radius-pill);
+				background: var(--pin-bg-sunken); color: var(--pin-ink-dim);
+				border: 1px solid var(--pin-border-strong); white-space: nowrap;
+			}
+			.pin-chip[data-kind="review"] {
+				background: var(--pin-review); color: var(--pin-review-ink); border-color: var(--pin-review);
+			}
+			.pin-chip[data-kind="progress"] {
+				background: var(--pin-open); color: var(--pin-open-ink); border-color: var(--pin-open);
+			}
+			.pin-chip[data-kind="resolved"] {
+				background: var(--pin-resolved); color: var(--pin-resolved-ink); border-color: var(--pin-resolved);
+			}
+			.pin-chip[data-kind="backlog"] {
+				background: transparent; color: var(--pin-ink-faint); border-style: dashed;
+			}
+			.pin-chip[data-kind="here"] {
+				background: transparent; color: var(--pin-open); border-color: var(--pin-open);
+			}
+			.pin-chip[data-kind="nomarker"] {
+				background: transparent; color: var(--pin-ink-warn); border-color: var(--pin-ink-warn);
+			}
+
+			.pin-row__detail {
+				padding: 0 var(--pin-space-2) var(--pin-space-2);
+				display: flex; flex-direction: column; gap: var(--pin-space-2);
+			}
+			.pin-row__detail[hidden] { display: none; }
+			.pin-row__full { width: 100%; display: block; border-radius: var(--pin-radius-sm); border: 1px solid var(--pin-border); }
+			.pin-row__comment { margin: 0; white-space: pre-wrap; word-break: break-word; }
+			.pin-row__warn {
+				margin: 0; padding: var(--pin-space-2); border-radius: var(--pin-radius-sm);
+				background: var(--pin-bg-sunken); border: 1px solid var(--pin-border-strong);
+				color: var(--pin-ink-warn); font-size: var(--pin-fs-small);
+			}
+			.pin-row__meta-list {
+				margin: 0; display: grid; grid-template-columns: auto 1fr;
+				gap: var(--pin-space-1) var(--pin-space-2); font-size: var(--pin-fs-small);
+			}
+			.pin-row__key { color: var(--pin-ink-faint); }
+			.pin-row__val {
+				margin: 0; color: var(--pin-ink-dim); font-family: var(--pin-font-mono);
+				font-size: var(--pin-fs-tiny); word-break: break-all;
+			}
+			.pin-row__actions { display: flex; gap: var(--pin-space-2); flex-wrap: wrap; align-items: center; }
+
+			/* ---- the markers ---- */
+
+			.pin-markers { position: absolute; top: 0; left: 0; width: 0; height: 0; }
+			.pin-marker {
+				position: absolute; padding: 0; margin: 0; border: 0; background: transparent;
+				width: var(--pin-marker-w); height: var(--pin-marker-h);
+				z-index: var(--pin-z-marker);
+				transform: translate(-50%, -100%);
+				cursor: pointer; line-height: 0;
+				filter: drop-shadow(var(--pin-marker-shadow));
+				transition: transform 120ms ease-out;
+			}
+			.pin-marker:hover { transform: translate(-50%, -100%) scale(1.12); }
+			.pin-marker:focus-visible { outline: 2px solid var(--pin-accent); outline-offset: 2px; }
+			.pin-marker[data-state="resolved"] { opacity: 0.85; }
+			.pin-marker__glyph { width: 100%; height: 100%; display: block; overflow: visible; }
+			.pin-marker__body { fill: var(--pin-open); stroke: var(--pin-halo); stroke-width: 1.8; }
+			.pin-marker[data-state="resolved"] .pin-marker__body { fill: var(--pin-resolved); }
+			.pin-marker__disc { fill: var(--pin-halo); }
+			.pin-marker__num {
+				fill: var(--pin-open); font-family: var(--pin-font); font-size: 11px; font-weight: 700;
+			}
+			.pin-marker[data-state="resolved"] .pin-marker__num { fill: var(--pin-resolved); }
+			.pin-marker[data-current] .pin-marker__body { stroke: var(--pin-accent); stroke-width: 2.6; }
+			.pin-marker[data-current] { transform: translate(-50%, -100%) scale(1.15); }
+
+			/* While the picker is armed the page belongs to it: a click anywhere must pin the
+			   element underneath, never open a ticket. The markers stay visible — seeing where the
+			   existing comments are is useful while leaving a new one — they just stop taking clicks. */
+			.pin-markers[data-picking] .pin-marker { pointer-events: none; opacity: 0.55; }
+
+			@media (max-width: 480px) {
+				.pin-chrome {
+					--pin-panel-w: 100vw;
+					--pin-thumb-w: 52px;
+				}
+				.pin-panel { top: var(--pin-space-2); right: var(--pin-space-2); left: var(--pin-space-2); }
+			}
+			@media (prefers-reduced-motion: reduce) {
+				.pin-marker { transition: none; }
+			}
+		`;
+
+		/* ---------- the ticket panel ---------- */
+
+		/**
+		 * Panel state. `tickets` is whatever the last read of the board said; nothing here is a
+		 * cache of the files, and every write is followed by a re-read rather than an optimistic
+		 * edit of this array — the status on screen after a resolve is the status the file now has.
+		 */
+		let panelOpen = false;
+		let panelTab = 'open'; // open | resolved
+		let panelTickets = [];
+		let panelApi = null;
+		let panelStatuses = [];
+		let panelBroken = [];
+		let expandedId = null;
+		let panelLoading = false;
+		let panelLoadedOnce = false;
+		/** The last read's failure, or null. A failed read must never read as an empty board. */
+		let panelLoadError = null;
+		/** id → { el, target, isFixed } for every marker currently on the page. */
+		const markers = new Map();
+		let markerFrame = false;
+
+		const panel = document.createElement('aside');
+		panel.className = 'pin-chrome pin-panel';
+		panel.setAttribute('data-orbytes-pin-ui', 'panel');
+		panel.setAttribute('aria-label', 'Pin tickets');
+		panel.hidden = true;
+		panel.innerHTML = `
+			<div class="pin-panel__head">
+				<span class="pin-panel__title">Tickets</span>
+				<span class="pin-panel__spacer"></span>
+				<button type="button" class="pin-panel__icon" data-p-refresh title="Re-read the board" aria-label="Re-read the board">&#8635;</button>
+				<button type="button" class="pin-panel__icon" data-p-close title="Close the panel" aria-label="Close the panel">&times;</button>
+			</div>
+			<div class="pin-panel__tabs" role="tablist">
+				<button type="button" class="pin-panel__tab" role="tab" data-p-tab="open" aria-selected="true">
+					Open <span class="pin-panel__tab-count" data-p-count="open">0</span>
+				</button>
+				<button type="button" class="pin-panel__tab" role="tab" data-p-tab="resolved" aria-selected="false">
+					Resolved <span class="pin-panel__tab-count" data-p-count="resolved">0</span>
+				</button>
+			</div>
+			<div class="pin-panel__switch">
+				<astro-dev-toolbar-toggle data-p-show-resolved toggle-style="gray"></astro-dev-toolbar-toggle>
+				<span class="pin-panel__switch-text" data-p-show-resolved-label>Show resolved pins on the page</span>
+			</div>
+			<div class="pin-panel__list" data-p-list></div>
+			<p class="pin-panel__note" data-p-note hidden></p>
+		`;
+
+		/**
+		 * The markers live in the toolbar's own canvas, never in `document.body`, and that is not a
+		 * matter of tidiness. `shot.mjs` hides exactly one thing before it takes a screenshot —
+		 * `astro-dev-toolbar{display:none!important}` — so a marker parented to the page would be
+		 * photographed into every ticket from then on, and every screenshot would carry the pins of
+		 * the tickets before it. Inside the canvas it is hidden with the toolbar, it cannot be
+		 * reached by the site's CSS, and the hit test already skips it.
+		 *
+		 * The consequence, stated plainly: markers are visible while the Pin app is open, because
+		 * Astro sets `display: none` on an app's canvas when its app is toggled off.
+		 */
+		const markerLayer = document.createElement('div');
+		markerLayer.className = 'pin-chrome pin-markers';
+		markerLayer.setAttribute('data-orbytes-pin-ui', 'markers');
+
+		canvas.append(panelStyle, markerLayer, panel);
+
+		const pui = {
+			list: panel.querySelector('[data-p-list]'),
+			note: panel.querySelector('[data-p-note]'),
+			counts: {
+				open: panel.querySelector('[data-p-count="open"]'),
+				resolved: panel.querySelector('[data-p-count="resolved"]'),
+			},
+			tabs: Array.prototype.slice.call(panel.querySelectorAll('[data-p-tab]')),
+			showResolved: panel.querySelector('[data-p-show-resolved]'),
+			showResolvedLabel: panel.querySelector('[data-p-show-resolved-label]'),
+		};
+
+		/** The toggle's choice, per viewer. Storage can be off; the panel then just forgets it. */
+		function readShowResolved() {
+			try {
+				const raw = localStorage.getItem(SHOW_RESOLVED_KEY);
+				return raw === null ? true : raw === '1';
+			} catch {
+				return true;
+			}
+		}
+		function writeShowResolved(value) {
+			try {
+				localStorage.setItem(SHOW_RESOLVED_KEY, value ? '1' : '0');
+			} catch {
+				/* private mode, storage disabled — the choice is a convenience, not a contract */
+			}
+		}
+		let showResolvedMarkers = readShowResolved();
+
+		/**
+		 * Keep the panel clear of the comment window.
+		 *
+		 * The window is centred and this rail is right-aligned, so on a narrow-enough viewport the
+		 * two overlap — and the window is painted above (z-index 999999999, ui-library/window.js)
+		 * because the comment box must never be covered by anything. Measured here 2026-09-22 at
+		 * 800x620: the window occupied x 80-720, y 377-549 and swallowed the bottom half of the
+		 * panel, including the Resolve button, which took the click and did nothing visible.
+		 *
+		 * So the PANEL yields, not the window: when the two would share a column, the panel's bottom
+		 * edge is lifted to sit above the window. Nothing is covered, nothing is layered over the
+		 * comment box, and on a wide screen — where they never meet — the panel keeps its full height.
+		 */
+		function fitPanelAroundWindow() {
+			if (!panelOpen) return;
+			const floor = 76; // the toolbar bar's own strip along the bottom
+			let bottom = floor;
+			const wr = win.getBoundingClientRect();
+			const pr = panel.getBoundingClientRect();
+			const overlapsColumn = wr.width > 0 && wr.right > pr.left && wr.left < pr.right;
+			if (overlapsColumn) bottom = Math.max(floor, Math.round(window.innerHeight - wr.top + 12));
+			panel.style.bottom = `${bottom}px`;
+		}
+
+		function panelNote(level, message) {
+			if (!message) {
+				pui.note.hidden = true;
+				pui.note.textContent = '';
+				return;
+			}
+			pui.note.hidden = false;
+			pui.note.dataset.level = level;
+			pui.note.textContent = message;
+		}
+
+		/* ---------- reading the board ---------- */
+
+		/**
+		 * Re-read every ticket from the board. One fetch, no polling: this is a dev tool on the
+		 * page being built, and a timer hitting the dev server every few seconds would be noise
+		 * for a file set that only changes when a person or an agent changes it. It refreshes when the
+		 * panel opens, when a ticket is written, when a screenshot lands, after a write, and on
+		 * the refresh button.
+		 */
+		async function loadBoard({ quiet = false } = {}) {
+			if (panelLoading) return;
+			panelLoading = true;
+			if (!quiet) panelNote('info', 'Reading the board…');
+			try {
+				const response = await fetch(BOARD_ROUTE, { cache: 'no-store', credentials: 'same-origin' });
+				if (!response.ok) {
+					throw new Error(`${BOARD_ROUTE} answered ${response.status} ${response.statusText}`);
+				}
+				const parsed = ticketsFromBoardHtml(await response.text(), BOARD_ROUTE);
+				panelTickets = parsed.tickets;
+				panelApi = parsed.apiPath;
+				panelStatuses = parsed.statuses;
+				panelBroken = parsed.broken;
+				panelLoadedOnce = true;
+				panelLoadError = null;
+				panelNote(
+					panelBroken.length ? 'warn' : 'info',
+					panelBroken.length
+						? `${panelBroken.length} ticket${panelBroken.length === 1 ? '' : 's'} on disk could not be read — ${BOARD_ROUTE} names them.`
+						: '',
+				);
+			} catch (error) {
+				panelTickets = [];
+				panelApi = null;
+				panelLoadError = (error && error.message) || String(error);
+				panelNote('error', `Could not read the tickets: ${panelLoadError}`);
+			} finally {
+				panelLoading = false;
+				renderPanel();
+				syncMarkers();
+				// The count on the toolbar button is read from the same list, so it moves with it.
+				updateTicketsButton();
+			}
+		}
+
+		/* ---------- placement ---------- */
+
+		/**
+		 * Where this ticket's marker goes on THIS page, decided against the live DOM.
+		 *
+		 * A ticket carries a `selector`, a document-coordinate `rect` taken when it was written,
+		 * and `selector_matches` — how many nodes the selector found on a genuinely fresh load,
+		 * counted by shot.mjs before the shutter. The rect is the tempting fallback and it is the
+		 * one thing this must not do: the page has been edited since, which is the whole point of
+		 * the ticket, so a marker drawn at a stale rect points confidently at the wrong element.
+		 * That is worse than no marker, because nothing on screen says it is wrong.
+		 *
+		 * So placement is decided by running the selector here, now, which is also the most honest
+		 * test available — more current than the recorded count, which was taken at capture time.
+		 * Exactly one match is placed. Nothing, several, or no selector at all is UNPLACEABLE, and
+		 * an unplaceable ticket is shown in the panel with the reason in plain words and no marker
+		 * on the page.
+		 */
+		function placementFor(ticket) {
+			if (isCancelledStatus(ticket.status)) {
+				return { kind: 'archived', why: 'Cancelled, so it is archived and draws nothing.' };
+			}
+			if (!samePath(ticket.url, currentPath())) {
+				return { kind: 'elsewhere', why: `It was left on ${ticket.url || 'an unrecorded page'}.` };
+			}
+			if (!ticket.selector) {
+				return { kind: 'none', why: 'This ticket records no selector, so there is nothing to find.' };
+			}
+			let found;
+			try {
+				found = document.querySelectorAll(ticket.selector);
+			} catch {
+				return { kind: 'bad', why: 'Its selector is not valid CSS any more, so it cannot be looked up.' };
+			}
+			if (found.length === 1) return { kind: 'placed', el: found[0] };
+			if (found.length === 0) {
+				return {
+					kind: 'dead',
+					why: 'Its selector finds nothing on this page now, so a marker would have to be guessed from where the element used to be — which would point at the wrong thing. Work it from the screenshot, the source file and the HTML snippet.',
+				};
+			}
+			return {
+				kind: 'ambiguous',
+				why: `Its selector finds ${found.length} elements here, so which one was meant is not recorded. No marker is drawn rather than one on the wrong element.`,
+			};
+		}
+
+		/** What the ticket itself recorded about its selector, for the detail panel. */
+		function recordedSelectorNote(ticket) {
+			if (ticket.flag && ticket.flag.label) return `${ticket.flag.label} when it was captured`;
+			if (ticket.selectorNote) return `${ticket.selectorNote} when it was captured`;
+			return 'found exactly one element when it was captured';
+		}
+
+		/* ---------- markers ---------- */
+
+		function markerVisible(ticket) {
+			if (isCancelledStatus(ticket.status)) return false;
+			if (isResolvedStatus(ticket.status)) return showResolvedMarkers;
+			return true;
+		}
+
+		function makeMarker(ticket) {
+			const button = document.createElement('button');
+			button.type = 'button';
+			button.className = 'pin-marker';
+			button.setAttribute('data-orbytes-pin-ui', 'marker');
+			button.dataset.id = ticket.id;
+			const ns = 'http://www.w3.org/2000/svg';
+			const svg = document.createElementNS(ns, 'svg');
+			svg.setAttribute('class', 'pin-marker__glyph');
+			svg.setAttribute('viewBox', `0 0 ${MARKER_W} ${MARKER_H}`);
+			svg.setAttribute('aria-hidden', 'true');
+			const body = document.createElementNS(ns, 'path');
+			body.setAttribute('class', 'pin-marker__body');
+			// A map pin: a circle of radius 11.6 centred at (13, 13) drawn down to a tip at
+			// (13, 33.2), which is the bottom centre of the box — so `translate(-50%, -100%)`
+			// puts that tip exactly on the anchor point.
+			body.setAttribute(
+				'd',
+				'M13 33.2C13 33.2 24.6 21.4 24.6 13A11.6 11.6 0 1 0 1.4 13C1.4 21.4 13 33.2 13 33.2Z',
+			);
+			const disc = document.createElementNS(ns, 'circle');
+			disc.setAttribute('class', 'pin-marker__disc');
+			disc.setAttribute('cx', '13');
+			disc.setAttribute('cy', '13');
+			disc.setAttribute('r', '7.4');
+			const num = document.createElementNS(ns, 'text');
+			num.setAttribute('class', 'pin-marker__num');
+			num.setAttribute('x', '13');
+			num.setAttribute('y', '13');
+			num.setAttribute('text-anchor', 'middle');
+			num.setAttribute('dominant-baseline', 'central');
+			num.textContent = ticketNumber(ticket.id);
+			svg.append(body, disc, num);
+			button.append(svg);
+			button.addEventListener('click', (event) => {
+				event.preventDefault();
+				event.stopPropagation();
+				openPanel({ focus: false });
+				expandedId = ticket.id;
+				panelTab = isResolvedStatus(ticket.status) ? 'resolved' : 'open';
+				renderPanel();
+				const row = pui.list.querySelector(`[data-p-row="${CSS.escape(ticket.id)}"]`);
+				if (row && row.scrollIntoView) row.scrollIntoView({ block: 'nearest' });
+				syncMarkers();
+				handFocusBack();
+			});
+			return button;
+		}
+
+		function decorateMarker(button, ticket) {
+			button.dataset.state = isResolvedStatus(ticket.status) ? 'resolved' : 'open';
+			if (ticket.id === expandedId) button.setAttribute('data-current', '');
+			else button.removeAttribute('data-current');
+			const label = `${ticket.id} — ${ticket.title} (${statusLabel(ticket.status)})`;
+			button.title = label;
+			button.setAttribute('aria-label', label);
+		}
+
+		/**
+		 * Reconcile the marker layer with the tickets. Called after every read, every write, every
+		 * tab change and every toggle — it adds, updates and removes rather than rebuilding, so a
+		 * marker keeps its place across a refresh and nothing flickers under the cursor.
+		 */
+		function syncMarkers() {
+			const wanted = new Map();
+			for (const ticket of panelTickets) {
+				if (!markerVisible(ticket)) continue;
+				const placement = placementFor(ticket);
+				if (placement.kind !== 'placed') continue;
+				wanted.set(ticket.id, { ticket, el: placement.el });
+			}
+			for (const [id, record] of markers) {
+				if (!wanted.has(id)) {
+					record.el.remove();
+					markers.delete(id);
+				}
+			}
+			for (const [id, { ticket, el }] of wanted) {
+				let record = markers.get(id);
+				if (!record) {
+					record = { el: makeMarker(ticket), target: el };
+					markers.set(id, record);
+					markerLayer.append(record.el);
+				}
+				record.target = el;
+				decorateMarker(record.el, ticket);
+			}
+			watchTargets();
+			placeMarkers();
+		}
+
+		/**
+		 * Layout moves under a marker for reasons no scroll or resize event reports — an image
+		 * settling, a font swapping, a section being edited two screens up. The highlight code
+		 * this app already runs answers scroll and resize; a ResizeObserver on the page root and
+		 * on each marked element answers the rest, all of it funnelled through one rAF so a
+		 * cascade of observations costs one layout read.
+		 */
+		const targetObserver =
+			typeof ResizeObserver === 'function' ? new ResizeObserver(() => schedulePlaceMarkers()) : null;
+		function watchTargets() {
+			if (!targetObserver) return;
+			targetObserver.disconnect();
+			try {
+				targetObserver.observe(document.documentElement);
+				if (document.body) targetObserver.observe(document.body);
+				targetObserver.observe(win);
+			} catch {
+				/* nothing to do — placement still runs on scroll and resize */
+			}
+			for (const record of markers.values()) {
+				try {
+					targetObserver.observe(record.target);
+				} catch {
+					/* the element went away between the sync and here; placeMarkers drops it */
+				}
+			}
+		}
+
+		function schedulePlaceMarkers() {
+			if (markerFrame) return;
+			markerFrame = true;
+			requestAnimationFrame(() => {
+				markerFrame = false;
+				placeMarkers();
+				fitPanelAroundWindow();
+			});
+		}
+
+		/**
+		 * Put every marker on its element, the same way the picker's highlights are placed:
+		 * document coordinates for an element in normal flow (so ordinary scrolling needs no work
+		 * at all), viewport coordinates when anything in its ancestry is `position: fixed`.
+		 *
+		 * The tip lands inside the element's top-left corner, which is where a pin belongs on a
+		 * section as much as on a button, and is clamped so it can never be drawn off the top or
+		 * the left of the page.
+		 */
+		function placeMarkers() {
+			for (const [id, record] of markers) {
+				const el = record.target;
+				if (!el || !el.isConnected) {
+					record.el.style.display = 'none';
+					continue;
+				}
+				const r = el.getBoundingClientRect();
+				if (!r.width && !r.height) {
+					record.el.style.display = 'none';
+					continue;
+				}
+				const { isFixed } = getElementsPositionInDocument(el);
+				const scrollX = isFixed ? 0 : window.scrollX;
+				const scrollY = isFixed ? 0 : window.scrollY;
+				const tipX = r.left + Math.min(MARKER_W * 0.62, Math.max(2, r.width / 2));
+				const tipY = r.top + Math.min(MARKER_H, Math.max(MARKER_H * 0.6, r.height));
+				record.el.style.display = 'block';
+				record.el.style.position = isFixed ? 'fixed' : 'absolute';
+				record.el.style.left = `${Math.max(tipX + scrollX, MARKER_W / 2)}px`;
+				record.el.style.top = `${Math.max(tipY + scrollY, MARKER_H)}px`;
+			}
+		}
+
+		/* ---------- the list ---------- */
+
+		function mkEl(tag, className, text) {
+			const node = document.createElement(tag);
+			if (className) node.className = className;
+			if (text !== undefined && text !== null) node.textContent = String(text);
+			return node;
+		}
+
+		function statusChip(kind, text) {
+			const node = mkEl('span', 'pin-chip', text);
+			node.dataset.kind = kind;
+			return node;
+		}
+
+		function metaRow(list, key, value) {
+			if (value === undefined || value === null || value === '') return;
+			list.append(mkEl('dt', 'pin-row__key', key), mkEl('dd', 'pin-row__val', value));
+		}
+
+		/** The two tabs, and the review queue first inside Open. `Cancelled` is on neither, by rule. */
+		function ticketsForTab(tab) {
+			const rows = panelTickets.filter((t) =>
+				tab === 'resolved' ? isResolvedStatus(t.status) : isOpenStatus(t.status),
+			);
+			const here = currentPath();
+			rows.sort((a, b) => {
+				const aHere = samePath(a.url, here) ? 0 : 1;
+				const bHere = samePath(b.url, here) ? 0 : 1;
+				if (aHere !== bHere) return aHere - bHere;
+				if (tab === 'open') {
+					const ao = OPEN_ORDER[statusKind(a.status)] ?? 9;
+					const bo = OPEN_ORDER[statusKind(b.status)] ?? 9;
+					if (ao !== bo) return ao - bo;
+				}
+				return Number(ticketNumber(b.id) || 0) - Number(ticketNumber(a.id) || 0);
+			});
+			return rows;
+		}
+
+		function buildDetail(ticket, placement) {
+			const detail = mkEl('div', 'pin-row__detail');
+			detail.hidden = ticket.id !== expandedId;
+			if (detail.hidden) return detail;
+
+			if (ticket.shot) {
+				const img = mkEl('img', 'pin-row__full');
+				img.src = ticket.shot;
+				img.alt = `Screenshot taken with ${ticket.id}`;
+				img.loading = 'lazy';
+				img.decoding = 'async';
+				detail.append(img);
+			}
+
+			const comment = mkEl('div', 'pin-row__comment');
+			// Already escaped by the board (board.mjs `esc`), which is the same HTML its own detail
+			// dialog shows. Paragraphs and code blocks, never one folded string.
+			comment.innerHTML = ticket.commentHtml || '';
+			detail.append(comment);
+
+			if (placement.kind !== 'placed' && placement.kind !== 'elsewhere' && placement.kind !== 'archived') {
+				detail.append(mkEl('p', 'pin-row__warn', `No marker on this page. ${placement.why}`));
+			}
+
+			const list = mkEl('dl', 'pin-row__meta-list');
+			metaRow(list, 'Status', statusLabel(ticket.status) + (statusLabel(ticket.status) !== String(ticket.status ?? '') ? ` (on disk: ${ticket.status})` : ''));
+			metaRow(list, 'Page', ticket.url);
+			metaRow(list, 'Source', ticket.source || 'unresolved');
+			metaRow(list, 'Selector', ticket.selector);
+			metaRow(list, 'At capture', recordedSelectorNote(ticket));
+			metaRow(
+				list,
+				'On this page',
+				placement.kind === 'placed'
+					? 'found — the marker is on it'
+					: placement.kind === 'elsewhere'
+						? 'not this page'
+						: placement.why,
+			);
+			metaRow(list, 'Viewport', ticket.viewport ? `${ticket.viewport.width}x${ticket.viewport.height}` : '');
+			metaRow(list, 'Dispatch', ticket.dispatch);
+			metaRow(list, 'Priority', ticket.priority);
+			metaRow(list, 'Created', ticket.created);
+			metaRow(list, 'Updated', ticket.updated);
+			metaRow(list, 'File', ticket.file);
+			if ((ticket.labels || []).length) metaRow(list, 'Labels', ticket.labels.join(', '));
+			detail.append(list);
+
+			const actions = mkEl('div', 'pin-row__actions');
+			const resolved = isResolvedStatus(ticket.status);
+			const action = document.createElement('astro-dev-toolbar-button');
+			action.setAttribute('size', 'small');
+			action.setAttribute('button-style', resolved ? 'gray' : 'green');
+			action.textContent = resolved ? 'Reopen' : 'Resolve';
+			action.addEventListener('click', () => {
+				setStatus(ticket, resolved ? reopenTarget() : STATUS_RESOLVED);
+			});
+			actions.append(action);
+
+			if (placement.kind === 'placed') {
+				const show = document.createElement('astro-dev-toolbar-button');
+				show.setAttribute('size', 'small');
+				show.setAttribute('button-style', 'ghost');
+				show.textContent = 'Show on page';
+				show.addEventListener('click', () => {
+					try {
+						placement.el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'auto' });
+					} catch {
+						/* an element that refuses to scroll is not worth an error */
+					}
+					schedulePlaceMarkers();
+				});
+				actions.append(show);
+			}
+			detail.append(actions);
+			return detail;
+		}
+
+		function buildRow(ticket) {
+			const placement = placementFor(ticket);
+			const row = mkEl('article', 'pin-row');
+			row.dataset.pRow = ticket.id;
+			row.dataset.kind = statusKind(ticket.status);
+			if (ticket.id === expandedId) row.setAttribute('data-current', '');
+
+			const summary = mkEl('button', 'pin-row__summary');
+			summary.type = 'button';
+			summary.setAttribute('aria-expanded', ticket.id === expandedId ? 'true' : 'false');
+
+			const thumb = mkEl('span', 'pin-row__thumb');
+			if (ticket.shot) {
+				const img = mkEl('img', 'pin-row__shot');
+				img.src = ticket.shot;
+				img.alt = '';
+				img.loading = 'lazy';
+				img.decoding = 'async';
+				thumb.append(img);
+			} else {
+				thumb.append(mkEl('span', null, 'no shot'));
+			}
+
+			const main = mkEl('span', 'pin-row__main');
+			main.append(mkEl('span', 'pin-row__title', ticket.title));
+			const meta = mkEl('span', 'pin-row__meta');
+			meta.append(mkEl('span', 'pin-row__id', ticket.id));
+			meta.append(statusChip(statusKind(ticket.status), statusLabel(ticket.status)));
+			if (placement.kind === 'placed') meta.append(statusChip('here', 'pinned'));
+			// The failure is said on the ROW, not only inside the detail: a ticket that belongs to
+			// this page and has no marker on it is exactly the case a reader would otherwise read
+			// as "there is no pin here", and go looking for the element by hand.
+			else if (placement.kind !== 'elsewhere' && placement.kind !== 'archived') {
+				meta.append(statusChip('nomarker', 'no marker'));
+			}
+			const age = ageLabel(ticket.updated || ticket.created);
+			if (age) meta.append(mkEl('span', 'pin-row__age', age));
+			main.append(meta);
+			const where =
+				ticket.source && ticket.source !== 'unresolved' ? ticket.source : ticket.url || '';
+			main.append(mkEl('span', 'pin-row__src', where));
+			summary.append(thumb, main);
+			summary.addEventListener('click', () => {
+				expandedId = expandedId === ticket.id ? null : ticket.id;
+				renderPanel();
+				syncMarkers();
+				handFocusBack();
+			});
+			row.append(summary, buildDetail(ticket, placement));
+			return row;
+		}
+
+		function renderPanel() {
+			const open = panelTickets.filter((t) => isOpenStatus(t.status)).length;
+			const resolved = panelTickets.filter((t) => isResolvedStatus(t.status)).length;
+			pui.counts.open.textContent = String(open);
+			pui.counts.resolved.textContent = String(resolved);
+			for (const tab of pui.tabs) {
+				tab.setAttribute('aria-selected', tab.dataset.pTab === panelTab ? 'true' : 'false');
+			}
+			if (pui.showResolved.input) pui.showResolved.input.checked = showResolvedMarkers;
+
+			pui.list.innerHTML = '';
+			const rows = ticketsForTab(panelTab);
+			if (!rows.length) {
+				// A read that FAILED is not an empty board, and must never be drawn as one — the
+				// whole list going quiet is exactly the shape a missing ticket would take.
+				const empty = panelLoadError
+					? `No tickets could be read. ${panelLoadError}`
+					: !panelLoadedOnce
+						? 'Reading the board…'
+						: panelTab === 'open'
+							? 'Nothing open. Pick an element to leave one.'
+							: 'Nothing resolved yet.';
+				pui.list.append(mkEl('p', 'pin-panel__empty', empty));
+				return;
+			}
+			const here = currentPath();
+			let group = null;
+			for (const ticket of rows) {
+				const onThisPage = samePath(ticket.url, here);
+				const name = onThisPage ? 'This page' : 'Other pages';
+				if (name !== group) {
+					group = name;
+					pui.list.append(mkEl('p', 'pin-panel__group', name));
+				}
+				pui.list.append(buildRow(ticket));
+			}
+		}
+
+		/* ---------- the one write ---------- */
+
+		/**
+		 * Where Reopen sends a ticket: the first status in the preference list the BOARD says it
+		 * knows. The write endpoint refuses anything outside `STATUSES` (tickets.mjs, a file this
+		 * panel does not own and which is being changed in parallel), so asking the board what it
+		 * renders is the only way this control cannot break under a vocabulary change.
+		 */
+		function reopenTarget() {
+			for (const wanted of REOPEN_PREFERENCE) {
+				if (panelStatuses.includes(wanted)) return wanted;
+			}
+			return REOPEN_PREFERENCE[0];
+		}
+
+		/**
+		 * The status change — `POST <board>/api/ticket`, the package's one write path, whose address
+		 * is read from the board's own `data-api` rather than assembled here.
+		 *
+		 * Two things are deliberate. `expect` carries the status EXACTLY as the board reported it,
+		 * never this panel's relabelled version, because the endpoint compares it against the file
+		 * and a legacy value on disk must compare as itself. And every refusal is shown verbatim
+		 * and changes nothing on screen: the endpoint refuses a stale `expect`, an unknown status
+		 * and a file that moved under the read, and each of those is a real answer about the disk.
+		 */
+		async function setStatus(ticket, next) {
+			if (!panelApi) {
+				panelNote('error', `There is no write endpoint on ${BOARD_ROUTE}, so this panel cannot change a status.`);
+				return;
+			}
+			panelNote('info', `${ticket.id} → ${next}…`);
+			let response;
+			let body;
+			try {
+				response = await fetch(panelApi, {
+					method: 'POST',
+					headers: { 'Content-Type': 'application/json' },
+					credentials: 'same-origin',
+					body: JSON.stringify({ id: ticket.id, status: next, expect: { status: ticket.status } }),
+				});
+				body = await response.json();
+			} catch (error) {
+				panelNote('error', `${ticket.id} was not changed: ${(error && error.message) || error}`);
+				return;
+			}
+			if (!response.ok || !body || body.ok !== true) {
+				panelNote('error', `${ticket.id} was not changed — ${(body && body.error) || `the server answered ${response.status}`}`);
+				return;
+			}
+			panelNote('info', `${ticket.id} is now ${statusLabel(body.status)}.`);
+			say('ok', `${ticket.id} → ${body.status}`);
+			// Re-read rather than patch the array: the panel then shows what the file says, which
+			// is the same discipline the endpoint itself uses before it answers.
+			await loadBoard({ quiet: true });
+		}
+
+		/* ---------- opening and closing ---------- */
+
+		/**
+		 * The panel and the picker are both allowed to be open, and that is a decision rather than
+		 * an oversight: the flow this is built for is read a ticket, look at the element, leave the
+		 * next comment, and a panel that closed the picker would throw away a held selection and
+		 * the words already typed into the comment box.
+		 *
+		 * What they do NOT share is clicks. The pick surface covers the viewport while picking, the
+		 * panel sits above it so its own controls stay usable, and the markers stop taking clicks
+		 * for as long as the picker is armed (`.pin-markers[data-picking]`) — so a click on the page
+		 * during a pick always pins the element underneath and never opens a ticket.
+		 *
+		 * And the panel never takes focus while a comment is being written. A voice dictation tool types
+		 * into whatever is focused, so stealing focus mid-sentence would put the next words somewhere
+		 * they cannot be seen.
+		 */
+		function openPanel({ focus = true } = {}) {
+			const first = !panelOpen;
+			panelOpen = true;
+			panel.hidden = false;
+			updateTicketsButton();
+			fitPanelAroundWindow();
+			if (first || !panelLoadedOnce) loadBoard({ quiet: panelLoadedOnce });
+			handFocusBack(() => {
+				if (!focus) return;
+				const tab = pui.tabs.find((t) => t.dataset.pTab === panelTab);
+				if (tab) tab.focus();
+			});
+		}
+
+		/**
+		 * Where focus goes after a panel control is used.
+		 *
+		 * While a selection is held the comment box owns focus and gets it straight back, caret and
+		 * all — refocusing a textarea restores its own selection range, so a dictated sentence
+		 * carries on where it stopped. A voice dictation tool types into whatever is focused, so a panel
+		 * that kept focus after a click would put the next words into a button. This is the same move
+		 * `climbTo` already makes for the same reason, and the cost is deliberate: while a comment is
+		 * being written the tabs cannot be walked with the keyboard. The box wins.
+		 */
+		function handFocusBack(otherwise) {
+			if (mode === 'selected') {
+				// Next frame, not this one. A real mouse click assigns focus to the control that was
+				// clicked AFTER the click handler has run, so focusing here is undone a moment later
+				// and the caret lands on nothing — measured 2026-09-22: a tab switch driven by a real
+				// click left document.activeElement on <body> while the same switch driven by
+				// .click() left it on the comment box. select() already defers for this reason.
+				requestAnimationFrame(focusComment);
+				return;
+			}
+			if (typeof otherwise === 'function') otherwise();
+		}
+
+		function closePanel() {
+			panelOpen = false;
+			panel.hidden = true;
+			updateTicketsButton();
+		}
+
+		function togglePanel() {
+			if (panelOpen) closePanel();
+			else openPanel();
+		}
+
+		function updateTicketsButton() {
+			const open = panelTickets.filter((t) => isOpenStatus(t.status)).length;
+			ui.tickets.textContent = panelLoadedOnce ? `Tickets · ${open}` : 'Tickets';
+			ui.tickets.setAttribute('button-style', panelOpen ? 'purple' : 'ghost');
+		}
+
+		/* ---------- wiring ---------- */
+
+		ui.tickets.addEventListener('click', togglePanel);
+
+		/**
+		 * Open the board in its own tab — a button in the Astro widget that opens the pin tab,
+		 * added 2026-09-22.
+		 *
+		 * The window is NAMED, so a second click focuses the tab that is already open instead of
+		 * stacking another copy of the board — "the pin tab", singular, which is the whole point
+		 * of it. The route is the resolved one (› BOARD_ROUTE), so this cannot open the wrong path on
+		 * a site that moved the board.
+		 *
+		 * Focus goes back to the comment box when one is being written: `window.open` takes focus
+		 * to the new tab, and returning to this one would otherwise leave the caret nowhere and
+		 * dictation typing into a button — the same reason `handFocusBack` exists for the panel.
+		 */
+		ui.openBoard.title = `Open ${BOARD_ROUTE} in its own tab`;
+		ui.openBoard.addEventListener('click', () => {
+			window.open(BOARD_ROUTE, 'orbytes-pin-board');
+			handFocusBack();
+		});
+		panel.querySelector('[data-p-close]').addEventListener('click', () => {
+			closePanel();
+			handFocusBack();
+		});
+		panel.querySelector('[data-p-refresh]').addEventListener('click', () => {
+			loadBoard();
+			handFocusBack();
+		});
+		for (const tab of pui.tabs) {
+			tab.addEventListener('click', () => {
+				panelTab = tab.dataset.pTab;
+				// Not `expandedId = null`: an entry stays open across a tab switch, and nothing here
+				// touches the comment box either. Switching tabs is a view change, not a reset.
+				renderPanel();
+				syncMarkers();
+				handFocusBack();
+			});
+		}
+		if (pui.showResolved.input) {
+			pui.showResolved.input.checked = showResolvedMarkers;
+			pui.showResolved.input.addEventListener('change', () => {
+				showResolvedMarkers = Boolean(pui.showResolved.input.checked);
+				writeShowResolved(showResolvedMarkers);
+				syncMarkers();
+			});
+		}
+		pui.showResolvedLabel.addEventListener('click', () => {
+			if (!pui.showResolved.input) return;
+			pui.showResolved.input.checked = !pui.showResolved.input.checked;
+			pui.showResolved.input.dispatchEvent(new Event('change'));
+		});
+		// Hovering the panel is not hovering the page — drop the pick highlight so the crosshair
+		// chrome is not left painted over whatever the cursor last crossed.
+		panel.addEventListener('mouseenter', () => {
+			if (mode !== 'picking') return;
+			hoverEl = null;
+			hoverFrames = [];
+			hideChrome(hoverHighlight);
+			hideChip();
+		});
+
+		/* ---------- mode ---------- */
+
+		function setMode(next) {
+			mode = next;
+			ui.badge.textContent = next;
+			ui.badge.setAttribute(
+				'badge-style',
+				next === 'picking' ? 'blue' : next === 'selected' ? 'purple' : 'gray',
+			);
+			ui.form.hidden = next !== 'selected';
+			ui.idle.hidden = next !== 'idle';
+			// The window changes height between modes, so the panel re-measures against it.
+			requestAnimationFrame(fitPanelAroundWindow);
+			ui.hint.innerHTML =
+				next === 'picking'
+					? 'Move the cursor over the page — click to pin that element. <span class="pin-kbd">Esc</span> cancels.'
+					: next === 'selected'
+						? 'Comment goes in verbatim. <span class="pin-kbd">⌥ ↑</span> pins the parent instead, <span class="pin-kbd">⌥ ↓</span> comes back — or click the trail above. <span class="pin-kbd">⌘ Enter</span> creates the ticket, <span class="pin-kbd">Esc</span> keeps what you have written — Cancel discards it.'
+						: 'Nothing selected.';
+
+			if (next === 'picking') {
+				if (!surface.isConnected) canvas.append(surface);
+				hideChrome(hoverHighlight);
+				// The picker owns clicks while it is armed — a marker must not swallow one that
+				// was meant to pin the element underneath it.
+				markerLayer.setAttribute('data-picking', '');
+			} else {
+				markerLayer.removeAttribute('data-picking');
+				surface.remove();
+				hoverEl = null;
+				hoverFrames = [];
+				hideChrome(hoverHighlight);
+				hideChip();
+			}
+			if (next !== 'selected') {
+				selectedEl = null;
+				selectedFrames = [];
+				chain = [];
+				climbIndex = 0;
+				clearCrumbs();
+				hideChrome(selectedHighlight);
+			}
+		}
+
+		function hideChrome(el) {
+			el.style.display = 'none';
+		}
+
+		function hideChip() {
+			chip.style.display = 'none';
+		}
+
+		/* ---------- highlight placement ---------- */
+
+		/**
+		 * Both highlights are painted in the TOP document, so an element inside a frame has its
+		 * box mapped back out through every scale in the chain before it is positioned.
+		 * Fixed-ness is judged on the OUTERMOST frame, not the element: `position: fixed` inside
+		 * a frame is fixed to that frame, and the frame scrolls with the page like anything else.
+		 */
+		function place(highlight, el, frames) {
+			if (!el || !el.isConnected) {
+				hideChrome(highlight);
+				return null;
+			}
+			const rect = viewportRect(el, frames);
+			if (!rect || (rect.width === 0 && rect.height === 0)) {
+				hideChrome(highlight);
+				return null;
+			}
+			const { isFixed } = getElementsPositionInDocument(frames && frames.length ? frames[0] : el);
+			highlight.style.position = isFixed ? 'fixed' : 'absolute';
+			positionHighlight(highlight, rect);
+			return { rect, isFixed };
+		}
+
+		function placeChip(el, frames, text, unresolved) {
+			const rect = viewportRect(el, frames);
+			if (!rect) {
+				hideChip();
+				return;
+			}
+			const { isFixed } = getElementsPositionInDocument(frames && frames.length ? frames[0] : el);
+			const scrollX = isFixed ? 0 : window.scrollX;
+			const scrollY = isFixed ? 0 : window.scrollY;
+			chip.style.position = isFixed ? 'fixed' : 'absolute';
+			chip.style.display = 'block';
+			chip.style.left = `${Math.max(rect.left + scrollX - 10, 0)}px`;
+			// Sit above the box when there is room, otherwise tuck inside its top edge.
+			const room = rect.top > 32;
+			chip.style.top = `${Math.max(rect.top + scrollY - (room ? 14 : -14), 0)}px`;
+			chip.style.transform = room ? 'translateY(-100%)' : 'none';
+			chip.textContent = text;
+			chip.style.borderColor = unresolved ? 'rgba(181, 138, 45, 1)' : 'rgba(113, 24, 226, 1)';
+			chip.style.color = unresolved ? 'rgba(255, 236, 179, 1)' : '#fff';
+		}
+
+		/** The chip's label: the source file, marked when the element is inside a story frame. */
+		function chipText(source, frames) {
+			const label = source || 'unresolved';
+			return frames && frames.length ? `\u21b3 ${label}` : label;
+		}
+
+		function reposition() {
+			if (mode === 'picking' && hoverEl) {
+				place(hoverHighlight, hoverEl, hoverFrames);
+				const { source } = resolveSource(hoverEl);
+				placeChip(hoverEl, hoverFrames, chipText(source, hoverFrames), !source);
+			}
+			if (selectedEl) place(selectedHighlight, selectedEl, selectedFrames);
+			placeMarkers();
+			fitPanelAroundWindow();
+		}
+
+		/**
+		 * A frame scrolls and resizes independently of the page and neither event reaches the top
+		 * window, so without this the highlight would sit where the element used to be. Added the
+		 * first time the hit test enters a given frame window; the WeakSet keeps it to once.
+		 */
+		const watchedWindows = new WeakSet();
+		function watchFrameWindow(win) {
+			if (!win || watchedWindows.has(win)) return;
+			watchedWindows.add(win);
+			for (const event of ['scroll', 'resize']) {
+				try {
+					win.addEventListener(event, reposition, { passive: true });
+				} catch {
+					/* the frame went away between the hit test and here */
+				}
+			}
+		}
+
+		/* ---------- hit testing ---------- */
+
+		/** Chrome this app must never pick, in whichever document it turns up. */
+		function isChrome(el) {
+			if (ownHosts.includes(el)) return true;
+			if (el.hasAttribute && el.hasAttribute('data-orbytes-pin-ui')) return true;
+			// Every story frame is served by this same dev server, so each one carries its OWN
+			// dev toolbar at the bottom of its viewport. Picking it would pin Astro's chrome.
+			if (el.tagName === 'ASTRO-DEV-TOOLBAR') return true;
+			return false;
+		}
+
+		function pickIn(doc, x, y) {
+			for (const el of doc.elementsFromPoint(x, y)) {
+				if (!el || el.nodeType !== 1) continue;
+				if (isChrome(el)) continue;
+				if (el.tagName === 'HTML') continue;
+				return el;
+			}
+			return null;
+		}
+
+		/**
+		 * The deepest REAL element under a point, plus the chain of same-origin iframes it lives
+		 * inside (outermost first) and a plain sentence when a frame could not be entered.
+		 *
+		 * `x`/`y` arrive in the top document's viewport coordinates and are re-expressed at every
+		 * hop. A frame that cannot be entered — cross-origin, rotated, or zero-sized — is
+		 * returned as the pick itself with the reason attached, so the ticket still describes
+		 * something real and the panel says why it is not the thing underneath.
+		 *
+		 * @returns {{ el: Element|null, frames: Element[], note: string|null }}
+		 */
+		function hitTest(x, y) {
+			let doc = document;
+			let px = x;
+			let py = y;
+			const frames = [];
+			const upOne = (note) => ({ el: frames[frames.length - 1], frames: frames.slice(0, -1), note });
+
+			for (let depth = 0; depth <= MAX_FRAME_DEPTH; depth++) {
+				const el = pickIn(doc, px, py);
+				if (!el) {
+					// Nothing in this document answers to the point. Inside a frame that means
+					// the frame's own padding or scrollbar, so the frame is the honest pick.
+					return frames.length ? upOne(null) : { el: null, frames: [], note: null };
+				}
+
+				const frame = frameUnder(el, px, py);
+				if (!frame) return { el, frames: frames.slice(), note: null };
+
+				const inner = frameDocument(frame);
+				if (!inner) {
+					return {
+						el: frame,
+						frames: frames.slice(),
+						note: 'That frame is cross-origin, so nothing inside it can be read — the ticket will describe the frame itself.',
+					};
+				}
+				const geo = frameGeometry(frame);
+				if (!geo) {
+					return {
+						el: frame,
+						frames: frames.slice(),
+						note: 'That frame is rotated, mirrored or has no size, so a point cannot be translated into it — the ticket will describe the frame itself.',
+					};
+				}
+				const win = inner.defaultView;
+				const cx = (px - geo.left) / geo.scaleX;
+				const cy = (py - geo.top) / geo.scaleY;
+				if (!win || cx < 0 || cy < 0 || cx > win.innerWidth || cy > win.innerHeight) {
+					return { el: frame, frames: frames.slice(), note: null };
+				}
+
+				watchFrameWindow(win);
+				frames.push(frame);
+				doc = inner;
+				px = cx;
+				py = cy;
+			}
+			return upOne(`Frames are nested more than ${MAX_FRAME_DEPTH} deep here, so the hit test stopped climbing in.`);
+		}
+
+		function onPointerMove(event) {
+			lastPointer = { x: event.clientX, y: event.clientY };
+			if (rafPending) return;
+			rafPending = true;
+			requestAnimationFrame(() => {
+				rafPending = false;
+				if (mode !== 'picking') return;
+				const hit = hitTest(lastPointer.x, lastPointer.y);
+				if (!hit.el) {
+					hoverEl = null;
+					hoverFrames = [];
+					hideChrome(hoverHighlight);
+					hideChip();
+					return;
+				}
+				hoverEl = hit.el;
+				hoverFrames = hit.frames;
+				// sayOnce, not say: a hover over an unreadable frame fires every frame otherwise.
+				if (hit.note) sayOnce('warn', hit.note);
+				place(hoverHighlight, hoverEl, hoverFrames);
+				const { source, error } = resolveSource(hoverEl);
+				if (error) say('error', error);
+				placeChip(hoverEl, hoverFrames, chipText(source, hoverFrames), !source);
+			});
+		}
+
+		function onSurfaceClick(event) {
+			// The surface exists so a click never reaches the page underneath — a pin on a
+			// link must not navigate away from the thing being pinned.
+			event.preventDefault();
+			event.stopPropagation();
+			if (mode !== 'picking') return;
+			const hit = hitTest(event.clientX, event.clientY);
+			if (!hit.el) {
+				// info, not warn: nothing failed, so this must not be one of the lines that stays
+				// on screen until it is dismissed.
+				say('info', 'Nothing under the cursor there.');
+				return;
+			}
+			if (hit.note) say('warn', hit.note);
+			select(hit.el, hit.frames);
+		}
+
+		surface.addEventListener('mousemove', onPointerMove, { passive: true });
+		surface.addEventListener('click', onSurfaceClick, true);
+		surface.addEventListener('contextmenu', (event) => event.preventDefault());
+
+		/* ---------- selection ---------- */
+
+		/**
+		 * Where the climb stops: an element that IS the page rather than something on it.
+		 *
+		 * Two tests, because a page has two ways of being its own wrapper.
+		 *   · **By tag** — `<body>`, `<html>`, and `<main>`, which is the content region by
+		 *     definition. A ticket against one of them names no component and says nothing a
+		 *     screenshot of the page would not.
+		 *   · **By size** — a `div` that happens to wrap everything is the page in a different
+		 *     costume, so anything covering essentially the whole scroll height is out too.
+		 *     Measured on `/` before this test existed: climbing three levels off a text block
+		 *     reached `#main` and produced a real ticket whose rect was 1440 × 7477 and whose
+		 *     screenshot was a 2.2 MB photograph of the entire home page.
+		 *
+		 * The size test only applies on a page meaningfully taller than the viewport. On a short
+		 * page — a lab story, which is one section and nothing else — the outermost section IS
+		 * most of the document, and climbing to it is exactly what the story's owner wants; there
+		 * the whole-page rect it would produce is a viewport-sized picture and costs nothing.
+		 */
+		function isThePageItself(node) {
+			const tag = node.tagName;
+			if (tag === 'BODY' || tag === 'HTML' || tag === 'MAIN') return true;
+			const doc = node.ownerDocument;
+			const view = doc.defaultView;
+			const pageHeight = doc.documentElement ? doc.documentElement.scrollHeight : 0;
+			if (!view || !pageHeight || pageHeight < view.innerHeight * 1.5) return false;
+			return node.getBoundingClientRect().height >= pageHeight * 0.95;
+		}
+
+		/**
+		 * What was clicked, then every ancestor worth pinning, innermost first.
+		 *
+		 * The walk stays inside the element's OWN document, so a pick inside a lab story climbs
+		 * to that story's outermost section and no further — never out through the iframe into
+		 * the shell around it, which is a different page with a different url and rect.
+		 */
+		function ancestorChain(el) {
+			const out = [el];
+			for (let node = el.parentElement; node; node = node.parentElement) {
+				if (isThePageItself(node)) break;
+				out.push(node);
+			}
+			return out;
+		}
+
+		/** A crumb's label: enough to recognise the element, short enough to keep one row. */
+		function crumbLabel(node) {
+			let label = node.tagName.toLowerCase();
+			const [first] = stableClasses(node);
+			if (first) label += `.${first}`;
+			return label;
+		}
+
+		function clearCrumbs() {
+			if (!ui.crumbs) return;
+			ui.crumbs.innerHTML = '';
+			ui.crumbs.hidden = true;
+		}
+
+		/** The trail, outermost first so it reads in the same direction as the selector. */
+		function renderCrumbs() {
+			ui.crumbs.innerHTML = '';
+			if (chain.length < 2) {
+				ui.crumbs.hidden = true;
+				return;
+			}
+			ui.crumbs.hidden = false;
+			for (let index = chain.length - 1; index >= 0; index--) {
+				const node = chain[index];
+				const button = document.createElement('button');
+				button.type = 'button';
+				button.textContent = crumbLabel(node);
+				button.title = `${cssPathOf(node)}\n${resolveSource(node).source || 'unresolved'}`;
+				if (index === climbIndex) button.setAttribute('data-current', '');
+				button.addEventListener('click', () => climbTo(index));
+				// Hovering a crumb paints the blue hover box over that element, so the parent can
+				// be SEEN before it is committed to. Nothing else uses that highlight while a
+				// selection is held, so it is free.
+				button.addEventListener('mouseenter', () => {
+					if (mode === 'selected') place(hoverHighlight, node, selectedFrames);
+				});
+				button.addEventListener('mouseleave', () => hideChrome(hoverHighlight));
+				ui.crumbs.append(button);
+				if (index > 0) {
+					const sep = document.createElement('span');
+					sep.className = 'sep';
+					sep.textContent = '›';
+					ui.crumbs.append(sep);
+				}
+			}
+			const current = ui.crumbs.querySelector('[data-current]');
+			if (current && current.scrollIntoView) {
+				current.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+			}
+		}
+
+		/**
+		 * Paint whatever level the climb is on. Everything visible about the target moves
+		 * together — the purple box, the source file, the selector, the url and the trail — and
+		 * the comment box is deliberately not among them: the words in it are yours, they survive
+		 * every climb, and the only control that throws them away is still Cancel.
+		 */
+		function applySelection() {
+			const el = chain[climbIndex];
+			if (!el) return;
+			selectedEl = el;
+			hideChrome(hoverHighlight);
+			place(selectedHighlight, el, selectedFrames);
+
+			const { source, error } = resolveSource(el);
+			if (error) say('error', error);
+			ui.src.textContent = source || 'unresolved';
+			if (source) ui.src.removeAttribute('data-unresolved');
+			else ui.src.setAttribute('data-unresolved', '');
+			ui.sel.textContent = cssPathOf(el);
+			ui.url.textContent = documentPath(el);
+			renderCrumbs();
+		}
+
+		/**
+		 * Move the pin up or down the chain.
+		 *
+		 * The keys are ⌥↑ / ⌥↓ rather than the bare arrows devtools uses, for one reason: the
+		 * comment box is focused the whole time and the bare arrows belong to it — taking them
+		 * would break moving the caret through dictated text, which is the flow this panel is
+		 * built around. Focus is handed straight back to the box afterwards, so a climb never
+		 * interrupts dictation.
+		 */
+		function climbTo(index) {
+			if (mode !== 'selected' || !chain.length) return;
+			const next = Math.max(0, Math.min(chain.length - 1, index));
+			if (next === climbIndex) {
+				if (index > climbIndex) {
+					sayOnce('info', 'That is as far out as this goes — the page itself is not a pin target.');
+				} else if (index < climbIndex) {
+					sayOnce('info', 'Already on the element you clicked.');
+				}
+				focusComment();
+				return;
+			}
+			climbIndex = next;
+			// A parent often lives in a DIFFERENT component — this is how a pin on a button
+			// becomes a pin on the section that owns it. applySelection() rewrites #pin-src with
+			// the new file, so the change is already on screen; the line that used to narrate it
+			// here was the log repeating the target box.
+			applySelection();
+			focusComment();
+		}
+
+		function select(el, frames) {
+			selectedFrames = frames || [];
+			chain = ancestorChain(el);
+			climbIndex = 0;
+			setMode('selected');
+			applySelection();
+			if (selectedFrames.length) {
+				say('info', `Inside a frame — this ticket describes ${documentPath(el)}, not the page around it.`);
+			}
+
+			// A voice dictation tool types into whatever is focused — the box has to be live
+			// the instant the panel opens, with no extra click.
+			requestAnimationFrame(focusComment);
+		}
+
+		/** preventScroll is not universal; losing the box is worse than a jump, so fall back. */
+		function focusComment() {
+			try {
+				ui.comment.focus({ preventScroll: true });
+			} catch {
+				ui.comment.focus();
+			}
+		}
+
+		function clearSelection() {
+			selectedEl = null;
+			selectedFrames = [];
+			chain = [];
+			climbIndex = 0;
+			clearCrumbs();
+			hideChrome(selectedHighlight);
+			hideChrome(hoverHighlight);
+			ui.comment.value = '';
+		}
+
+		/* ---------- payload + send ---------- */
+
+		/**
+		 * Every field below is read from the document the element ACTUALLY lives in — its own
+		 * window — never from the page this toolbar is running in. On the lab that is the story
+		 * route inside the frame, and the four that travel together have to agree or the ticket
+		 * is worse than useless:
+		 *
+		 *   url      the page shot.mjs re-loads to take the picture;
+		 *   rect     document coordinates OF THAT PAGE, which the screenshot clips against;
+		 *   viewport the width the page is re-loaded at, so it lays out as it was seen;
+		 *   scroll   where that page was scrolled to, so scroll-reveals have fired.
+		 *
+		 * This is also why the parent's scale needs no correction here. A CSS transform on a
+		 * frame scales what is drawn, not what is laid out: the content window's `innerWidth`
+		 * and a rect measured inside it are in unscaled CSS px whatever the parent did to them.
+		 */
+		function buildPayload(el, comment) {
+			const { source } = resolveSource(el);
+			const win = el.ownerDocument.defaultView;
+			return {
+				comment,
+				dispatch: ui.dispatch.input && ui.dispatch.input.checked ? 'now' : 'queue',
+				source,
+				selector: cssPathOf(el),
+				url: win.location.pathname + win.location.search,
+				viewport: {
+					width: win.innerWidth,
+					height: win.innerHeight,
+					dpr: win.devicePixelRatio,
+				},
+				scroll: { x: Math.round(win.scrollX), y: Math.round(win.scrollY) },
+				rect: docRect(el, win.scrollX, win.scrollY),
+				outerHTML: truncate(el.outerHTML, OUTER_HTML_LIMIT),
+			};
+		}
+
+		function setBusy(next) {
+			busy = next;
+			if (next) ui.form.setAttribute('data-busy', '');
+			else ui.form.removeAttribute('data-busy');
+		}
+
+		function submit() {
+			if (busy) return;
+			const comment = ui.comment.value;
+			if (!comment.trim()) {
+				say('error', 'Nothing to send — the comment is empty.');
+				ui.comment.focus();
+				return;
+			}
+			if (!selectedEl || !selectedEl.isConnected) {
+				say('error', 'That element has left the page. Pick it again.');
+				setMode('picking');
+				return;
+			}
+			if (selectedFrames.length && !chainGeometry(selectedFrames)) {
+				say('error', 'The frame that element was in has reloaded or moved. Pick it again.');
+				setMode('picking');
+				return;
+			}
+
+			let payload;
+			try {
+				payload = buildPayload(selectedEl, comment);
+			} catch (error) {
+				say('error', `Could not describe that element: ${error && error.message}`);
+				return;
+			}
+
+			// No "Sending to the dev server…" here. The form goes [data-busy] on the same tick and
+			// the reply lands in under 30ms — a line saying a thing is happening would be replaced
+			// by the line saying it happened before it could be read.
+			setBusy(true);
+			rememberPin(payload.selector, selectedFrames);
+			server.send('orbytes-pin:create', payload);
+
+			clearTimeout(replyTimer);
+			replyTimer = setTimeout(() => {
+				if (!busy) return;
+				setBusy(false);
+				say(
+					'error',
+					'No reply from the dev server after 8 seconds. Is the orbytes-pin integration loaded?',
+				);
+			}, REPLY_TIMEOUT_MS);
+		}
+
+		server.on('orbytes-pin:created', (data) => {
+			clearTimeout(replyTimer);
+			setBusy(false);
+			if (!data) {
+				say('error', 'The dev server replied with nothing at all.');
+				return;
+			}
+			if (data.error) {
+				say('error', `Ticket refused: ${data.error}`);
+				return;
+			}
+			say('ok', `${data.id} written to ${data.file} — screenshot pending.`);
+			clearSelection();
+			setMode('picking');
+			loadBoard({ quiet: true });
+		});
+
+		/**
+		 * The screenshot reply, which also carries the one thing this page cannot work out for
+		 * itself: how many elements the selector finds on a GENUINELY fresh load. Here, the
+		 * selector was just built against this very DOM and was verified unique before it was
+		 * sent, so it always looks healthy — that is exactly how a carousel pin used to ship a
+		 * selector that resolved to one node when written and none ever again, with the source
+		 * file, the screenshot and the outerHTML all perfectly correct and nothing saying so.
+		 *
+		 * `selectorMatches` is `1` when healthy, `0` when the selector died on reload, more than
+		 * one when it names several elements, and `null` when the question could not be asked
+		 * (no screenshot, or shots turned off). Anything but `1` is said out loud, because the
+		 * ticket is still workable by hand and you should know which kind you have.
+		 */
+		server.on('orbytes-pin:shot', (data) => {
+			if (!data) return;
+			if (data.error) say('warn', `${data.id || 'Screenshot'} has no image yet: ${data.error}`);
+			else say('ok', `${data.id} screenshot landed at ${data.shot}`);
+			loadBoard({ quiet: true });
+
+			const matches = data.selectorMatches;
+			if (matches === 0) {
+				say(
+					'warn',
+					`${data.id || 'That pin'}: the selector finds nothing when the page is reloaded — this element is generated, so the ticket has to be worked from its source file, screenshot and HTML snippet instead.`,
+				);
+			} else if (typeof matches === 'number' && matches > 1) {
+				say(
+					'warn',
+					`${data.id || 'That pin'}: the selector finds ${matches} elements on a reload, not one — the ticket says which, but it does not point at a single element.`,
+				);
+			}
+		});
+
+		/* ---------- controls ---------- */
+
+		ui.submit.addEventListener('click', submit);
+		ui.start.addEventListener('click', () => setMode('picking'));
+		ui.again.addEventListener('click', () => {
+			clearSelection();
+			setMode('picking');
+		});
+		ui.cancel.addEventListener('click', () => {
+			clearSelection();
+			setMode('idle');
+		});
+		ui.comment.addEventListener('keydown', (event) => {
+			if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+				event.preventDefault();
+				submit();
+			}
+		});
+		// `change` does not cross a shadow boundary, so listen on the toggle's own input
+		// (ui-library/toggle.js creates it in the constructor and appends it on connect).
+		if (ui.dispatch.input) {
+			ui.dispatch.input.addEventListener('change', () => {
+				ui.dispatchLabel.textContent = ui.dispatch.input.checked ? 'now' : 'queue';
+			});
+		}
+
+		/* ---------- escape ---------- */
+
+		// The toolbar itself closes the active app on a document `keyup` for Escape
+		// (toolbar.js:326-335). While picking or holding a selection that would throw away
+		// dictated text, so consume the key here in the capture phase and swallow the
+		// matching keyup. When neither applies, Escape still closes the app as usual.
+		//
+		// Stopping the close was only half of it. Escape is the key a person reaches for to
+		// dismiss a dictation overlay or a stray autocomplete, so it lands on a FULL comment
+		// box constantly — and a dictated paragraph cannot be retyped from memory. So Escape
+		// never discards text: with anything in the box it holds the selection, the words and
+		// the caret, and points at Cancel, which is the one control that discards on purpose.
+		function onKeydown(event) {
+			// The climb. Capture phase and preventDefault, because ⌥↑ in a textarea is
+			// "move the caret to the start of the paragraph" on macOS and would otherwise
+			// scramble the dictated comment while the selection moved.
+			if (
+				mode === 'selected' &&
+				event.altKey &&
+				!event.metaKey &&
+				!event.ctrlKey &&
+				(event.key === 'ArrowUp' || event.key === 'ArrowDown')
+			) {
+				event.preventDefault();
+				event.stopPropagation();
+				climbTo(climbIndex + (event.key === 'ArrowUp' ? 1 : -1));
+				return;
+			}
+			if (event.key !== 'Escape') return;
+			if (mode === 'picking') {
+				event.preventDefault();
+				event.stopPropagation();
+				swallowEscapeKeyup = true;
+				// The badge and the hint line both change on setMode — saying it again in words
+				// was the log talking to itself.
+				setMode(selectedEl ? 'selected' : 'idle');
+			} else if (mode === 'selected') {
+				event.preventDefault();
+				event.stopPropagation();
+				swallowEscapeKeyup = true;
+				if (ui.comment.value.trim()) {
+					focusComment();
+					sayOnce('info', 'Your comment is still here — click Cancel to discard it.');
+					return;
+				}
+				clearSelection();
+				setMode('idle');
+			} else if (panelOpen) {
+				// Idle, with the panel open. Escape peels one layer at a time — the expanded entry,
+				// then the panel — and only once both are shut does it reach Astro's own
+				// close-the-app handler, which is the behaviour from before the panel existed.
+				//
+				// This branch is deliberately LAST. While something is being picked or written the
+				// two branches above own the key, because the comment box is the thing a stray
+				// Escape must never cost: a dictated paragraph cannot be retyped from memory.
+				event.preventDefault();
+				event.stopPropagation();
+				swallowEscapeKeyup = true;
+				// Each branch is visible the instant it runs — the entry folds, or the rail goes.
+				// Narrating it was the log describing the screen to the person looking at it.
+				if (expandedId) {
+					expandedId = null;
+					renderPanel();
+					syncMarkers();
+				} else {
+					closePanel();
+				}
+			}
+		}
+
+		function onKeyup(event) {
+			if (event.key !== 'Escape' || !swallowEscapeKeyup) return;
+			swallowEscapeKeyup = false;
+			event.stopImmediatePropagation();
+		}
+
+		document.addEventListener('keydown', onKeydown, true);
+		document.addEventListener('keyup', onKeyup, true);
+
+		/* ---------- lifecycle ---------- */
+
+		app.onToggled(({ state }) => {
+			if (state) {
+				setMode(selectedEl ? 'selected' : 'picking');
+				// Astro hides an app's whole canvas when the app is toggled off, so the markers go
+				// with it. Coming back is therefore the moment to re-read: tickets may have been
+				// resolved on the board, and the page may have been edited underneath them.
+				loadBoard({ quiet: true });
+			} else {
+				setMode('idle');
+			}
+		});
+
+		for (const event of ['scroll', 'resize']) {
+			window.addEventListener(event, reposition, { passive: true });
+		}
+		document.addEventListener('astro:after-swap', () => {
+			clearSelection();
+			setMode(mode === 'picking' ? 'picking' : 'idle');
+			// Every marker was pointing into the document that has just been replaced.
+			for (const record of markers.values()) record.el.remove();
+			markers.clear();
+			loadBoard({ quiet: true });
+		});
+
+		/* ---------- scroll restore + flash ---------- */
+
+		function currentPath() {
+			return location.pathname + location.search;
+		}
+
+		/**
+		 * `frames` is the chain of iframes the element lives inside, stored as one selector per
+		 * hop so the restore can walk back in after a reload. A pin taken inside a lab story
+		 * would otherwise be looked for in the shell document, where it has never existed.
+		 */
+		function rememberPin(selector, frames) {
+			if (!selector) return;
+			try {
+				sessionStorage.setItem(
+					RESTORE_KEY,
+					JSON.stringify({
+						selector,
+						frames: (frames || []).map((frame) => cssPathOf(frame)),
+						path: currentPath(),
+						ts: Date.now(),
+					}),
+				);
+			} catch {
+				/* private mode, storage disabled — the restore is a convenience, not a contract */
+			}
+		}
+
+		/** Walk the stored frame chain back in and find the element. null if any hop is gone. */
+		function resolveRestore(entry) {
+			let doc = document;
+			const frames = [];
+			for (const selector of entry.frames || []) {
+				let frame = null;
+				try {
+					frame = doc.querySelector(selector);
+				} catch {
+					return null; // no longer parses — nothing to say, nothing to do
+				}
+				if (!frame) return null;
+				const inner = frameDocument(frame);
+				if (!inner) return null;
+				frames.push(frame);
+				doc = inner;
+			}
+			let el = null;
+			try {
+				el = doc.querySelector(entry.selector);
+			} catch {
+				return null;
+			}
+			return el ? { el, frames } : null;
+		}
+
+		function readRestore() {
+			try {
+				const raw = sessionStorage.getItem(RESTORE_KEY);
+				if (!raw) return null;
+				const entry = JSON.parse(raw);
+				if (!entry || typeof entry.selector !== 'string') return null;
+				if (entry.frames && !Array.isArray(entry.frames)) return null;
+				if (entry.path !== currentPath()) return null;
+				if (!(Date.now() - Number(entry.ts) < RESTORE_TTL_MS)) return null;
+				return entry;
+			} catch {
+				return null;
+			}
+		}
+
+		function flash(el, frames) {
+			const box = document.createElement('div');
+			box.setAttribute('data-orbytes-pin-ui', 'flash');
+			Object.assign(box.style, {
+				position: 'fixed',
+				pointerEvents: 'none',
+				zIndex: String(Z.flash),
+				borderRadius: '6px',
+				border: '2px solid rgba(113, 24, 226, 1)',
+				background:
+					'linear-gradient(180deg, rgba(224, 204, 250, 0.33) 0%, rgba(224, 204, 250, 0.08) 100%)',
+			});
+			const put = () => {
+				const r = viewportRect(el, frames);
+				if (!r) return;
+				box.style.left = `${r.left - 4}px`;
+				box.style.top = `${r.top - 4}px`;
+				box.style.width = `${r.width + 8}px`;
+				box.style.height = `${r.height + 8}px`;
+			};
+			put();
+			document.body.append(box);
+			window.addEventListener('scroll', put, { passive: true });
+			const done = () => {
+				window.removeEventListener('scroll', put);
+				box.remove();
+			};
+			if (typeof box.animate === 'function') {
+				const animation = box.animate(
+					[{ opacity: 0 }, { opacity: 1 }, { opacity: 1 }, { opacity: 0 }],
+					{ duration: FLASH_MS, easing: 'ease-out' },
+				);
+				animation.addEventListener('finish', done);
+				animation.addEventListener('cancel', done);
+			} else {
+				setTimeout(done, FLASH_MS);
+			}
+		}
+
+		/**
+		 * Any `.astro` edit is a full page reload in Astro 7 with no scroll restoration, so a
+		 * fix pass would throw you back to the top of the page on every ticket. Scroll to the
+		 * ELEMENT, not to a saved pixel offset — the edit just moved the layout.
+		 */
+		function restoreAfterReload() {
+			const entry = readRestore();
+			if (!entry) return;
+			const run = () => {
+				// Resolves through the stored frame chain, so a pin taken inside a lab story is
+				// found inside that story and not looked for in the shell.
+				const found = resolveRestore(entry);
+				if (!found) return; // element edited away, or its frame is gone — degrade silently
+				try {
+					// The frame first, so the element's own scroll has somewhere visible to land.
+					if (found.frames.length) {
+						found.frames[0].scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'auto' });
+					}
+					found.el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'auto' });
+					flash(found.el, found.frames);
+					rememberPin(entry.selector, found.frames); // keep the anchor alive across the pass
+					// The page scrolls and the element flashes. Saying so in words said nothing.
+				} catch {
+					/* nothing here is worth breaking the page for */
+				}
+			};
+			if (document.readyState === 'complete') requestAnimationFrame(run);
+			else window.addEventListener('load', () => requestAnimationFrame(run), { once: true });
+		}
+
+		window.addEventListener('pagehide', () => {
+			// A selection made but not sent yet is still the thing being looked at.
+			if (selectedEl && selectedEl.isConnected) rememberPin(cssPathOf(selectedEl), selectedFrames);
+			else {
+				// Re-store the existing entry verbatim to refresh its timestamp. Rebuilding it
+				// would drop the frame chain, which is stored as selectors, not elements.
+				const entry = readRestore();
+				if (entry) {
+					try {
+						sessionStorage.setItem(RESTORE_KEY, JSON.stringify({ ...entry, ts: Date.now() }));
+					} catch {
+						/* storage disabled — the restore is a convenience, not a contract */
+					}
+				}
+			}
+		});
+
+		setMode('idle');
+		restoreAfterReload();
+		// Read the board once at start-up so the markers are on the page the moment the app is
+		// opened, without having to open the panel first.
+		loadBoard({ quiet: true });
+	},
+
+	beforeTogglingOff(canvas) {
+		// Nothing this app owns should outlive the canvas being hidden.
+		for (const el of canvas.querySelectorAll('[data-orbytes-pin-ui="surface"]')) el.remove();
+		return true;
+	},
+});
+
+/** Exported for headless verification only — not part of the app's runtime surface. */
+export const __test = {
+	ageLabel,
+	isCancelledStatus,
+	isOpenStatus,
+	isResolvedStatus,
+	normalisePath,
+	samePath,
+	statusKind,
+	statusLabel,
+	ticketNumber,
+	ticketsFromBoardHtml,
+	chainGeometry,
+	countMatches,
+	cssPathOf,
+	docRect,
+	documentPath,
+	frameDocument,
+	frameGeometry,
+	frameUnder,
+	isAxisAligned,
+	outward,
+	extendsSiblingClass,
+	mostSpecific,
+	nthChildPath,
+	nthOfType,
+	partCandidates,
+	selectorCombos,
+	stableClasses,
+	isNoiseClass,
+	isTransientClass,
+	isTrustworthyId,
+	resolveSource,
+	truncate,
+	looksAbsolute,
+};