@dorsk/yubisashi 0.1.0

package/shell/app.js

@@ -0,0 +1,554 @@
+const $ = (id) => document.getElementById(id);
+const frame = $('app');
+const overlay = $('overlay');
+const input = $('input');
+
+const hash = new URLSearchParams(location.hash.slice(1));
+const token = hash.get('token') ?? '';
+
+const state = {
+	annotations: [],
+	transcript: [],
+	session: null,
+	picking: false,
+	hover: null,
+	hoverLabel: '',
+	/** @type {{ el: Element, info: any }[]} */
+	selection: [],
+	thread: null,
+	tab: 'chat',
+	/** annotation id → elements picked in this tab, so pins survive re-renders that change selectors */
+	refs: new Map(),
+};
+
+async function api(path, body) {
+	const res = await fetch(`api${path}`, {
+		method: body ? 'POST' : 'GET',
+		headers: { 'content-type': 'application/json', 'x-yubi-token': token },
+		body: body ? JSON.stringify(body) : undefined,
+	});
+	if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
+	return res.json();
+}
+
+const esc = (s) =>
+	String(s).replace(
+		/[&<>"']/g,
+		(c) => `&${{ '&': 'amp', '<': 'lt', '>': 'gt', '"': 'quot', "'": '#39' }[c]};`,
+	);
+
+function markdown(text) {
+	const blocks = text.split(/```[\w-]*\n?/);
+	return blocks
+		.map((block, i) => {
+			if (i % 2) return `<pre><code>${esc(block.replace(/\n$/, ''))}</code></pre>`;
+			return block
+				.trim()
+				.split(/\n{2,}/)
+				.filter(Boolean)
+				.map((p) => {
+					const html = esc(p)
+						.replace(/`([^`]+)`/g, '<code>$1</code>')
+						.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+						.replace(/^#{1,6} (.*)$/gm, '<strong>$1</strong>')
+						.replace(
+							/\[([^\]]+)\]\((https?:[^)\s]+)\)/g,
+							'<a href="$2" target="_blank" rel="noreferrer">$1</a>',
+						)
+						.replace(/\n/g, '<br>');
+					return `<p>${html}</p>`;
+				})
+				.join('');
+		})
+		.join('');
+}
+
+// ---------------------------------------------------------------- element capture
+
+const shortFile = (file) => (file ? file.split('/').at(-1) : '');
+const where = (loc) =>
+	loc?.file ? `${loc.file}:${loc.line}${loc.column ? `:${loc.column}` : ''}` : '';
+
+function svelteMeta(el) {
+	for (let node = el; node; node = node.parentElement) {
+		if (node.__svelte_meta) return node.__svelte_meta;
+	}
+	return null;
+}
+
+function stackOf(meta) {
+	const frames = [];
+	for (let p = meta?.parent; p && frames.length < 12; p = p.parent) {
+		if (p.type !== 'component' || p.file?.includes('.svelte-kit/generated')) continue;
+		frames.push({
+			type: p.type,
+			name: p.componentTag ? `<${p.componentTag}>` : undefined,
+			file: p.file,
+			line: p.line,
+			column: p.column,
+		});
+	}
+	return frames;
+}
+
+const SCOPED_CLASS = /^(svelte|s)-[\w-]{5,}$/;
+
+function selectorOf(el) {
+	const doc = el.ownerDocument;
+	const parts = [];
+	for (
+		let node = el;
+		node && node.nodeType === 1 && node !== doc.documentElement;
+		node = node.parentElement
+	) {
+		for (const attr of ['data-testid', 'data-verb', 'data-test']) {
+			const value = node.getAttribute(attr);
+			if (value) {
+				parts.unshift(`[${attr}="${CSS.escape(value)}"]`);
+				return parts.join(' > ');
+			}
+		}
+		if (node.id && !/\d{3,}/.test(node.id)) {
+			parts.unshift(`#${CSS.escape(node.id)}`);
+			return parts.join(' > ');
+		}
+		let part = node.localName;
+		const classes = [...node.classList].filter((c) => !SCOPED_CLASS.test(c)).slice(0, 2);
+		if (classes.length) part += classes.map((c) => `.${CSS.escape(c)}`).join('');
+		const siblings = node.parentElement
+			? [...node.parentElement.children].filter((s) => s.localName === node.localName)
+			: [];
+		if (siblings.length > 1) part += `:nth-of-type(${siblings.indexOf(node) + 1})`;
+		parts.unshift(part);
+		if (parts.length >= 6) break;
+	}
+	return parts.join(' > ');
+}
+
+function describe(el) {
+	const meta = svelteMeta(el);
+	const attrs = {};
+	for (const a of el.attributes) {
+		if (
+			a.name.startsWith('data-') ||
+			['role', 'aria-label', 'href', 'name', 'type', 'title', 'alt'].includes(a.name)
+		) {
+			attrs[a.name] = a.value.slice(0, 200);
+		}
+	}
+	const r = el.getBoundingClientRect();
+	const html = el.outerHTML.replace(/\s+/g, ' ');
+	return {
+		tag: el.localName,
+		selector: selectorOf(el),
+		text: (el.innerText ?? el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 100),
+		html: html.length > 500 ? `${html.slice(0, 500)}…` : html,
+		attrs,
+		rect: {
+			x: Math.round(r.x),
+			y: Math.round(r.y),
+			width: Math.round(r.width),
+			height: Math.round(r.height),
+		},
+		source: meta
+			? { file: meta.loc.file, line: meta.loc.line, column: meta.loc.column }
+			: undefined,
+		stack: stackOf(meta),
+	};
+}
+
+const label = (info) => {
+	const src = info.source ? `${shortFile(info.source.file)}:${info.source.line}` : info.selector;
+	return `<${info.tag}> ${src}`;
+};
+
+// ---------------------------------------------------------------- iframe wiring
+
+function currentRoute() {
+	try {
+		const l = frame.contentWindow.location;
+		return l.pathname + l.search + l.hash;
+	} catch {
+		return '/';
+	}
+}
+
+function setPicking(on) {
+	state.picking = on;
+	$('pick').classList.toggle('on', on);
+	glass.hidden = !on;
+	if (!on) state.hover = null;
+}
+
+function onKey(e) {
+	const typing = e.target.closest?.(
+		'input, textarea, [contenteditable=""], [contenteditable="true"]',
+	);
+	if (e.key === 'Escape') {
+		if (state.picking) setPicking(false);
+		else if (state.selection.length) setSelection([]);
+		else if (state.thread) setThread(null);
+		return;
+	}
+	if (!typing && (e.key === 'c' || e.key === 'C') && !e.metaKey && !e.ctrlKey && !e.altKey) {
+		e.preventDefault();
+		setPicking(!state.picking);
+	}
+}
+
+/** Pick mode covers the app with a glass pane: disabled controls never receive clicks, and the
+ * app must not react to the pointing either. */
+const glass = $('glass');
+
+function elementAt(e) {
+	const doc = frame.contentDocument;
+	const r = frame.getBoundingClientRect();
+	return doc?.elementFromPoint(e.clientX - r.left, e.clientY - r.top) ?? null;
+}
+
+glass.addEventListener('mousemove', (e) => {
+	const el = elementAt(e);
+	if (el === state.hover) return;
+	state.hover = el;
+	state.hoverLabel = el ? label(describe(el)) : '';
+});
+
+glass.addEventListener('click', (e) => {
+	const el = elementAt(e);
+	if (!el) return;
+	const entry = { el, info: describe(el) };
+	if (e.shiftKey || e.metaKey || e.ctrlKey) {
+		const i = state.selection.findIndex((s) => s.el === el);
+		setSelection(i >= 0 ? state.selection.filter((_, j) => j !== i) : [...state.selection, entry]);
+	} else {
+		setSelection([entry]);
+		setPicking(false);
+	}
+	setThread(null);
+	input.focus();
+});
+
+glass.addEventListener(
+	'wheel',
+	(e) => {
+		const win = frame.contentWindow;
+		for (let node = elementAt(e); node; node = node.parentElement) {
+			const style = win.getComputedStyle(node);
+			if (/(auto|scroll)/.test(style.overflowY + style.overflowX)) {
+				const before = node.scrollTop + node.scrollLeft;
+				node.scrollBy(e.deltaX, e.deltaY);
+				if (node.scrollTop + node.scrollLeft !== before) return;
+			}
+		}
+		win.scrollBy(e.deltaX, e.deltaY);
+	},
+	{ passive: true },
+);
+
+function hook() {
+	const win = frame.contentWindow;
+	if (!win || win.__yubi) return;
+	win.__yubi = true;
+	win.addEventListener('keydown', onKey, true);
+}
+
+frame.addEventListener('load', hook);
+setInterval(() => {
+	hook();
+	const route = currentRoute();
+	if ($('route').textContent !== route) {
+		$('route').textContent = route;
+		hash.set('route', route);
+		history.replaceState(null, '', `#${hash}`);
+	}
+	renderPins();
+}, 400);
+
+// ---------------------------------------------------------------- overlay
+
+function box(rect, cls, text) {
+	const el = document.createElement('div');
+	el.className = `box ${cls}`;
+	Object.assign(el.style, {
+		left: `${rect.x}px`,
+		top: `${rect.y}px`,
+		width: `${rect.width}px`,
+		height: `${rect.height}px`,
+	});
+	if (text) {
+		const tag = document.createElement('span');
+		tag.className = 'tag';
+		tag.textContent = text;
+		el.append(tag);
+	}
+	return el;
+}
+
+let pins = [];
+
+function renderPins() {
+	const route = currentRoute();
+	pins = [];
+	let doc;
+	try {
+		doc = frame.contentDocument;
+	} catch {
+		return;
+	}
+	for (const a of state.annotations) {
+		if (a.status !== 'open' || a.route !== route || !a.targets.length) continue;
+		let el = state.refs.get(a.id)?.find((e) => e.isConnected);
+		if (!el) {
+			try {
+				el = doc?.querySelector(a.targets[0].selector);
+			} catch {}
+		}
+		if (el) pins.push({ id: a.id, el });
+	}
+}
+
+function draw() {
+	const layers = [];
+	const hover = state.hover;
+	if (state.picking && hover?.isConnected && !state.selection.some((s) => s.el === hover)) {
+		layers.push(box(hover.getBoundingClientRect(), 'hover', state.hoverLabel));
+	}
+	for (const s of state.selection) {
+		if (s.el.isConnected) layers.push(box(s.el.getBoundingClientRect(), 'selected', label(s.info)));
+	}
+	for (const p of pins) {
+		if (!p.el.isConnected) continue;
+		const r = p.el.getBoundingClientRect();
+		const pin = document.createElement('div');
+		pin.className = 'pin';
+		pin.textContent = p.id;
+		pin.style.left = `${r.x + r.width}px`;
+		pin.style.top = `${r.y}px`;
+		pin.onclick = () => {
+			switchTab('comments');
+			setThread(p.id);
+		};
+		layers.push(pin);
+	}
+	overlay.replaceChildren(...layers);
+	requestAnimationFrame(draw);
+}
+requestAnimationFrame(draw);
+
+// ---------------------------------------------------------------- panel
+
+function switchTab(tab) {
+	state.tab = tab;
+	for (const b of document.querySelectorAll('.tabs button'))
+		b.classList.toggle('active', b.dataset.tab === tab);
+	$('chat').hidden = tab !== 'chat';
+	$('comments').hidden = tab !== 'comments';
+}
+for (const b of document.querySelectorAll('.tabs button'))
+	b.onclick = () => switchTab(b.dataset.tab);
+
+function setSelection(selection) {
+	state.selection = selection;
+	renderContext();
+}
+
+function setThread(id) {
+	state.thread = id;
+	renderContext();
+	renderComments();
+	if (id) input.focus();
+}
+
+function renderContext() {
+	const chips = state.selection.map((s, i) => {
+		const chip = document.createElement('span');
+		chip.className = 'chip';
+		chip.title = [where(s.info.source), ...s.info.stack.map((f) => `${f.name ?? ''} ${where(f)}`)]
+			.filter(Boolean)
+			.join('\n');
+		chip.textContent = label(s.info);
+		const x = document.createElement('button');
+		x.type = 'button';
+		x.textContent = '×';
+		x.onclick = () => setSelection(state.selection.filter((_, j) => j !== i));
+		chip.append(x);
+		return chip;
+	});
+	if (state.thread) {
+		const chip = document.createElement('span');
+		chip.className = 'chip';
+		chip.textContent = `replying to #${state.thread}`;
+		const x = document.createElement('button');
+		x.type = 'button';
+		x.textContent = '×';
+		x.onclick = () => setThread(null);
+		chip.append(x);
+		chips.unshift(chip);
+	}
+	$('context').replaceChildren(...chips);
+	input.placeholder = state.thread
+		? `Reply to #${state.thread}…`
+		: state.selection.length
+			? 'What should change here?'
+			: 'Message the agent…';
+}
+
+function nearBottom(el) {
+	return el.scrollHeight - el.scrollTop - el.clientHeight < 80;
+}
+
+function entryNode(e) {
+	const el = document.createElement('div');
+	el.className = `msg ${e.kind}`;
+	if (e.kind === 'assistant') el.innerHTML = markdown(e.text);
+	else el.textContent = e.kind === 'event' ? `· ${e.text} ·` : e.text;
+	return el;
+}
+
+function renderChat(fresh) {
+	const feed = $('chat');
+	const stick = nearBottom(feed);
+	if (!fresh) {
+		if (!state.session) {
+			feed.innerHTML =
+				'<p class="empty">No Claude session attached.<br>Start <code>yubi up</code> from inside the agent\'s session or pass <code>--session &lt;id&gt;</code>.</p>';
+			return;
+		}
+		feed.replaceChildren(...state.transcript.map(entryNode));
+	} else {
+		feed.append(...fresh.map(entryNode));
+	}
+	if (stick || !fresh) feed.scrollTop = feed.scrollHeight;
+}
+
+function renderComments() {
+	const feed = $('comments');
+	const open = state.annotations.filter((a) => a.status === 'open').length;
+	$('count').textContent = open ? `(${open})` : '';
+	if (!state.annotations.length) {
+		feed.innerHTML =
+			'<p class="empty">Press <code>C</code>, click an element, and say what should change.</p>';
+		return;
+	}
+	const cards = [...state.annotations].reverse().map((a) => {
+		const card = document.createElement('article');
+		card.className = `card${a.status === 'open' ? '' : ' closed'}${state.thread === a.id ? ' focus' : ''}`;
+		const targets = a.targets
+			.map(
+				(t) =>
+					`<div class="where" title="${esc(t.stack.map((f) => `${f.name ?? ''} ${where(f)}`).join('\n'))}">${esc(label(t))}</div>`,
+			)
+			.join('');
+		const thread = a.thread
+			.map(
+				(m) =>
+					`<div class="${m.from}">${m.from === 'agent' ? markdown(m.text) : esc(m.text)}</div>`,
+			)
+			.join('');
+		card.innerHTML = `
+			<header><span class="id">#${a.id}</span><span class="badge ${a.status}">${a.status}</span>
+			<span class="where">${esc(a.route)}</span></header>
+			${targets}<div class="thread">${thread}</div>
+			<div class="actions"></div>`;
+		const actions = card.querySelector('.actions');
+		const action = (text, fn) => {
+			const b = document.createElement('button');
+			b.type = 'button';
+			b.textContent = text;
+			b.onclick = fn;
+			actions.append(b);
+		};
+		action('Reply', () => setThread(a.id));
+		if (a.status === 'open')
+			action('Resolve', () => api(`/annotations/${a.id}/messages`, { status: 'resolved' }));
+		else action('Reopen', () => api(`/annotations/${a.id}/messages`, { status: 'open' }));
+		return card;
+	});
+	feed.replaceChildren(...cards);
+}
+
+function setListening(on) {
+	const el = $('status');
+	el.classList.toggle('on', on);
+	el.textContent = on ? 'agent listening' : 'agent busy';
+	el.title = on
+		? 'The agent is waiting for your messages.'
+		: 'Messages queue until the agent runs `yubi wait` again.';
+}
+
+$('composer').addEventListener('submit', async (e) => {
+	e.preventDefault();
+	const text = input.value.trim();
+	if (!text) return;
+	input.disabled = true;
+	try {
+		if (state.thread) {
+			await api(`/annotations/${state.thread}/messages`, { text });
+		} else {
+			const picked = state.selection;
+			const created = await api('/annotations', {
+				comment: text,
+				route: currentRoute(),
+				viewport: { width: frame.clientWidth, height: frame.clientHeight },
+				targets: picked.map((s) => s.info),
+			});
+			if (picked.length)
+				state.refs.set(
+					created.id,
+					picked.map((s) => s.el),
+				);
+			setSelection([]);
+		}
+		input.value = '';
+	} catch (err) {
+		alert(`yubisashi: ${err.message}`);
+	} finally {
+		input.disabled = false;
+		input.focus();
+	}
+});
+
+input.addEventListener('keydown', (e) => {
+	if (e.key === 'Enter' && !e.shiftKey && !e.isComposing) {
+		e.preventDefault();
+		$('composer').requestSubmit();
+	}
+});
+document.addEventListener('keydown', onKey, true);
+$('pick').onclick = () => setPicking(!state.picking);
+$('reload').onclick = () => frame.contentWindow.location.reload();
+
+// ---------------------------------------------------------------- boot
+
+async function boot() {
+	if (!token) {
+		document.body.innerHTML =
+			'<p class="empty" style="margin:auto">Missing token. Open the URL printed by <code>yubi up</code> (or run <code>yubi url</code>).</p>';
+		return;
+	}
+	const initial = await api('/state');
+	state.annotations = initial.annotations;
+	state.transcript = initial.transcript;
+	state.session = initial.session;
+	$('open').href = initial.target;
+	frame.src = hash.get('route') || '/';
+	setListening(initial.listening);
+	renderChat();
+	renderComments();
+	renderContext();
+
+	const events = new EventSource(`api/events?token=${encodeURIComponent(token)}`);
+	events.addEventListener('listening', (e) => setListening(JSON.parse(e.data)));
+	events.addEventListener('annotations', (e) => {
+		state.annotations = JSON.parse(e.data);
+		renderComments();
+		renderPins();
+	});
+	events.addEventListener('transcript', (e) => {
+		const fresh = JSON.parse(e.data);
+		state.transcript.push(...fresh);
+		renderChat(fresh);
+	});
+}
+
+boot();

package/shell/index.html

@@ -0,0 +1,46 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>yubisashi</title>
+		<link rel="stylesheet" href="app.css" />
+	</head>
+	<body>
+		<main id="stage">
+			<header id="bar">
+				<button id="pick" type="button" title="Comment on elements (C)">
+					<span class="glyph">⌖</span> Comment
+				</button>
+				<span id="route"></span>
+				<button id="reload" type="button" title="Reload the app">↻</button>
+				<a id="open" href="/" target="_blank" rel="noreferrer" title="Open the app on its own">↗</a>
+			</header>
+			<div id="viewport">
+				<iframe id="app" title="app under review"></iframe>
+				<div id="overlay"></div>
+				<div id="glass" hidden></div>
+			</div>
+		</main>
+		<aside id="panel">
+			<header>
+				<nav class="tabs">
+					<button type="button" data-tab="chat" class="active">Conversation</button>
+					<button type="button" data-tab="comments">Comments <span id="count"></span></button>
+				</nav>
+				<span id="status" title=""></span>
+			</header>
+			<section id="chat" class="feed"></section>
+			<section id="comments" class="feed" hidden></section>
+			<form id="composer">
+				<div id="context"></div>
+				<textarea id="input" rows="3" placeholder="Message the agent…"></textarea>
+				<div class="row">
+					<span id="hint">C to point at elements · Shift+click to add · Enter to send</span>
+					<button type="submit">Send</button>
+				</div>
+			</form>
+		</aside>
+		<script type="module" src="app.js"></script>
+	</body>
+</html>

package/skill/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: yubisashi
+description: Use when the user wants to review a running web app visually and send you feedback by pointing at elements — "let me comment on the UI", "start a review session", "I'll show you what I don't like". Starts the dev server behind the yubisashi shell (app + conversation panel side by side) and wires the user's comments into this session.
+---
+
+# yubisashi: UI review loop
+
+The user points at elements in their running app, writes a comment, and it arrives here with
+the element's source `file:line`, the component chain that rendered it, a selector and an HTML
+snippet. Their view also streams this conversation next to the app.
+
+## Start
+
+1. Start the dev server behind yubisashi as a **background** command, from the app's directory:
+
+   ```sh
+   yubi up --target http://localhost:5173 -- npm run dev
+   ```
+
+   `--target` is the dev server's URL. Leave out `-- <cmd>` if the server is already running.
+   It listens on 127.0.0.1:4780 by default (`--port`, `--host`).
+
+2. Run `yubi url` and give the user the URL it prints (it carries the access token).
+
+3. Start listening as a **background** command:
+
+   ```sh
+   yubi wait
+   ```
+
+   It exits when the user sends something, and its output is their messages. The harness
+   wakes you up when it exits, so you don't need to poll.
+
+## Each time `yubi wait` returns
+
+1. Read every message. `source:` is where the element is written; `rendered by:` lists the
+   components that rendered it, innermost first. These are the files to look at.
+2. Do the work. The dev server hot-reloads, so the user sees the change in the shell.
+3. Answer each thread by id:
+   - `yubi resolve <id> "what changed"` when it's done
+   - `yubi reply <id> "question or progress"` to keep the thread open
+   - `yubi dismiss <id> "why"` to decline
+4. Start `yubi wait` in the background again. Until you do, the panel shows "agent busy" and
+   messages queue up.
+
+Messages without a target are general chat from the panel. Answer them in your normal
+response, since the user reads this conversation in the panel.
+
+`yubi list` shows open comments. Stop the loop only when the user says they're done, then stop
+the `yubi up` background task.