clickroom 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "clickroom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Share prototype builds for review: pins, region comments, threads, versions, and agent hand-off (MCP). Teammates push builds to their team’s clickroom with `clickroom login`.",
+  "type": "module",
+  "bin": {
+    "clickroom": "bin/clickroom.js"
+  },
+  "scripts": {
+    "dev": "node bin/clickroom.js dev",
+    "share": "node bin/clickroom.js dev --tunnel",
+    "demo": "node bin/clickroom.js add demo ./examples/demo && node bin/clickroom.js dev --tunnel",
+    "test": "node --test test/*.test.js",
+    "screens": "node examples/screens/build.js",
+    "demo:seed": "node examples/demo/seed.js",
+    "prepublishOnly": "node --test test/detect.test.js test/changes.test.js test/webpush.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://clickroom.dev",
+  "keywords": [
+    "prototype",
+    "review",
+    "feedback",
+    "comments",
+    "mcp",
+    "claude"
+  ],
+  "files": [
+    "bin/",
+    "cli/",
+    "worker/handoff.js",
+    "README.md"
+  ],
+  "devDependencies": {
+    "wrangler": "^4.148.0"
+  }
+}

package/worker/handoff.js

@@ -0,0 +1,351 @@
+// Turns review threads into a digest a coding agent can act on.
+
+export const isQuestion = (t) => t.kind === 'question';
+export const isTask = (t) => t.kind === 'task';
+
+// Where a question stands: waiting for the client until a client has the last word. An assumption
+// the client confirmed with one click is "confirmed"; one they replied to (corrected) is "answered".
+// Once an agent worked the answer into the prototype it's "processed" (status review), and the next
+// push stamps the version it landed in (fixedIn), as for fixes.
+// A draft waits for the team to send it; one the team answered itself counts the team's answer.
+// An answer is final once the team sends it to an agent ("queued"); until then there may be follow-ups.
+export function questionState(t) {
+  if (t.status === 'resolved') return 'closed';
+  if (t.status === 'review') return 'processed';
+  if (t.status === 'queued') return 'queued';
+  if (t.status === 'draft') return 'draft';
+  const last = [...t.comments].reverse().find((c) => c.kind === 'comment' || c.kind === 'confirm');
+  const answerer = t.anchor?.teamOnly ? ['client', 'team'] : ['client'];
+  if (!answerer.includes(last?.author?.role) || last === t.comments[0]) return 'waiting';
+  return last.kind === 'confirm' ? 'confirmed' : 'answered';
+}
+
+export const QUESTION_STATES = {
+  question: { draft: 'draft', waiting: 'waiting for client', answered: 'answered', queued: 'sent to agent', processed: 'processed', closed: 'resolved' },
+  assumption: { draft: 'draft', waiting: 'to check', answered: 'answered', confirmed: 'confirmed', queued: 'sent to agent', processed: 'processed', closed: 'resolved' },
+};
+
+const typeOf = (t) => (t.anchor?.type === 'assumption' ? 'assumption' : 'question');
+const stateLabel = (t) => QUESTION_STATES[typeOf(t)][questionState(t)];
+const processedIn = (t) => (t.fixedIn ? `in ${t.fixedIn === 'live' ? 'the live dev server' : 'v' + t.fixedIn}` : 'not pushed yet');
+
+// kind: "feedback" (comments on the prototype), "question" (questions for the client) or "all".
+// "actionable": what the team queued for agents (and nothing else: the team decides what goes into
+// the next version).
+// "answered" (questions): answers the team sent to an agent (queued), not worked in yet. An answer
+// the team hasn't sent may still get follow-ups, so agents leave it alone.
+export function filterThreads(threads, status = 'actionable', kind = 'feedback') {
+  if (kind !== 'all') threads = threads.filter((t) => isQuestion(t) === (kind === 'question'));
+  if (status === 'all') return threads;
+  if (status === 'answered') return threads.filter((t) => isQuestion(t) && t.status === 'queued');
+  if (status === 'actionable') return threads.filter((t) => t.status === 'queued');
+  if (status === 'active') return threads.filter((t) => t.status !== 'resolved');
+  return threads.filter((t) => t.status === status);
+}
+
+export function toJson(project, threads, { status = 'actionable', kind = 'feedback', baseUrl } = {}) {
+  const items = filterThreads(threads, status, kind);
+  return {
+    project: project.name,
+    source: project.source || project.target || null,
+    filter: status,
+    kind,
+    generatedAt: new Date().toISOString(),
+    total: threads.length,
+    count: items.length,
+    threads: items.map((t) => (isQuestion(t) ? questionJson(t, project, baseUrl) : {
+      seq: t.seq,
+      status: t.status,
+      page: t.page,
+      version: t.version ?? null,
+      kind: t.kind,
+      title: titleOf(t),
+      reviewUrl: baseUrl ? reviewUrl(baseUrl, project.name, t) : undefined,
+      element: {
+        selector: t.anchor.selector || null,
+        tag: t.anchor.tag || null,
+        text: t.anchor.text || null,
+        html: t.anchor.html || null,
+        detachedFallback: { x: t.anchor.docX, y: t.anchor.docY },
+      },
+      where: whereOf(t.anchor),
+      screenshotUrl: t.shot && baseUrl ? shotUrl(baseUrl, project.name, t) : undefined,
+      fixedIn: t.fixedIn ?? undefined,
+      versions: versionsOf(t),
+      region: t.kind === 'region' ? { width: Math.round(t.anchor.w || 0), height: Math.round(t.anchor.h || 0) } : undefined,
+      viewport: t.anchor.viewport || null,
+      conversation: conversationJson(t),
+    })),
+  };
+}
+
+function questionJson(t, project, baseUrl) {
+  return {
+    seq: t.seq,
+    kind: t.kind,
+    type: typeOf(t),
+    key: t.anchor?.key,
+    now: t.anchor?.now,
+    element: t.anchor?.el ? { selector: t.anchor.el.selector || null, text: t.anchor.el.text || null } : undefined,
+    screenshotUrl: t.shot && baseUrl ? shotUrl(baseUrl, project.name, t) : undefined,
+    status: t.status,
+    state: questionState(t),
+    fixedIn: t.fixedIn ?? undefined,
+    page: t.page || null,
+    title: titleOf(t),
+    reviewUrl: baseUrl ? reviewUrl(baseUrl, project.name, t) : undefined,
+    conversation: conversationJson(t),
+  };
+}
+
+function conversationJson(t) {
+  return t.comments.map((c) => ({ kind: c.kind, author: c.author?.name, role: c.author?.role, at: c.createdAt, body: c.body }));
+}
+
+export function toMarkdown(project, threads, { status = 'actionable', kind = 'feedback', baseUrl } = {}) {
+  if (kind === 'question') return questionsMarkdown(project, threads, { status, baseUrl });
+  const items = filterThreads(threads, status, kind);
+  const src = project.source || project.target;
+  const out = [];
+  out.push(`# Prototype feedback: ${project.name}`);
+  out.push('');
+  out.push(
+    `_${src ? `Source: \`${src}\` · ` : ''}${items.length} item${items.length === 1 ? '' : 's'} (filter: ${status}) of ${threads.length} total · generated ${new Date().toISOString()}_`,
+  );
+  out.push('');
+  out.push('> **For agents:** each item is client/team feedback anchored to an element of the running prototype.');
+  out.push('> Selector, text and HTML come from the *built* page, so use them to locate the matching source component.');
+  out.push(`> When done, mark it fixed with MCP \`clickroom_mark_fixed {"project":"${project.name}","seq":N,"note":"what changed"}\``);
+  out.push(`> or CLI \`clickroom resolve ${project.name} N --note "what changed"\`: the reviewer checks it in the next pushed version.`);
+  out.push('> Ask the client with `clickroom_reply` if something is unclear. Screenshot links need the team token.');
+  out.push('');
+  if (!items.length) {
+    out.push('_No feedback matches this filter._');
+    return out.join('\n') + '\n';
+  }
+
+  // Tasks: free text the team added for the agent, not tied to a page or element.
+  const tasks = items.filter(isTask);
+  if (tasks.length) {
+    out.push('## Tasks');
+    out.push('');
+    for (const t of tasks) {
+      out.push(`### #${t.seq} · Task: ${titleOf(t)}  \`${t.status}\``);
+      out.push('');
+      if (t.status === 'review') out.push(`- **Done:** ${t.fixedIn ? `in ${t.fixedIn === 'live' ? 'the live dev server' : 'v' + t.fixedIn}` : 'not pushed yet'}, waiting for the reviewer`);
+      conversationMd(out, t);
+      out.push('');
+    }
+  }
+  const byPage = new Map();
+  for (const t of items) {
+    if (isTask(t)) continue;
+    if (!byPage.has(t.page)) byPage.set(t.page, []);
+    byPage.get(t.page).push(t);
+  }
+  for (const [page, list] of byPage) {
+    out.push(`## Page \`${page}\``);
+    out.push('');
+    for (const t of list) {
+      const a = t.anchor || {};
+      out.push(`### #${t.seq} · ${titleOf(t)}  \`${t.status}\``);
+      out.push('');
+      if (baseUrl) out.push(`- **Review link:** ${reviewUrl(baseUrl, project.name, t)}`);
+      out.push(
+        `- **Annotation:** ${
+          t.kind === 'region'
+            ? `region ${Math.round(a.w || 0)}×${Math.round(a.h || 0)}px over the element`
+            : `pin at ${pct(a.xPct)} × ${pct(a.yPct)} of the element`
+        }`,
+      );
+      const where = whereText(a);
+      if (where) out.push(`- **Where:** ${where}`);
+      if (t.shot && baseUrl) out.push(`- **Screenshot:** ${shotUrl(baseUrl, project.name, t)}`);
+      const seen = versionsText(t);
+      if (seen) out.push(`- **Versions:** ${seen}`);
+      if (t.status === 'review') out.push(`- **Fixed:** ${t.fixedIn ? `in ${t.fixedIn === 'live' ? 'the live dev server' : 'v' + t.fixedIn}` : 'not pushed yet'}, waiting for the reviewer`);
+      if (a.selector) out.push(`- **Element:** \`${a.selector}\``);
+      if (a.text) out.push(`- **Text:** "${oneLine(a.text, 160)}"`);
+      if (a.viewport) out.push(`- **Viewport:** ${a.viewport.w}×${a.viewport.h}`);
+      if (t.version) out.push(`- **Version:** ${t.version === 'live' ? 'live dev server' : 'v' + t.version}`);
+      if (a.html) {
+        out.push('');
+        out.push('```html');
+        out.push(a.html.replace(/```/g, '``​`'));
+        out.push('```');
+      }
+      out.push('');
+      out.push('**Conversation**');
+      out.push('');
+      conversationMd(out, t);
+      out.push('');
+    }
+  }
+  return out.join('\n') + '\n';
+}
+
+// Questions the team or an agent asked the client; the replies are the answer.
+function questionsMarkdown(project, threads, { status, baseUrl }) {
+  const all = threads.filter(isQuestion);
+  const items = filterThreads(threads, status, 'question');
+  const n = (type) => items.filter((t) => typeOf(t) === type).length;
+  const out = [`# Questions for the client: ${project.name}`, ''];
+  out.push(`_${n('question')} questions · ${n('assumption')} assumptions (filter: ${status}) of ${all.length} total · generated ${new Date().toISOString()}_`);
+  out.push('');
+  out.push('> **For agents:** the client\'s replies are the answer. Follow up with `clickroom_reply`, ask something new with');
+  out.push(`> \`clickroom_ask {"project":"${project.name}","question":"..."}\`. Once an answer is worked into the prototype, mark it with`);
+  out.push('> `clickroom_mark_fixed` and a note on what changed: the next push records the version it landed in.');
+  out.push('');
+  if (!items.length) {
+    out.push('_No questions match this filter._');
+    return out.join('\n') + '\n';
+  }
+  for (const t of items) {
+    out.push(`## #${t.seq} · ${typeOf(t) === 'assumption' ? 'Assumption' : 'Question'}: ${titleOf(t)}  \`${stateLabel(t)}\``);
+    out.push('');
+    if (t.anchor?.now) out.push(`- **Now:** ${indent(t.anchor.now)}`);
+    if (t.page) out.push(`- **About page:** \`${t.page}\``);
+    const el = t.anchor?.el;
+    if (el?.selector) out.push(`- **Element:** \`${el.selector}\`${el.text ? ` "${oneLine(el.text, 120)}"` : ''}`);
+    if (t.shot && baseUrl) out.push(`- **Screenshot:** ${shotUrl(baseUrl, project.name, t)}`);
+    if (t.anchor?.key) out.push(`- **Key:** \`${t.anchor.key}\``);
+    if (t.status === 'review') out.push(`- **Processed:** ${processedIn(t)}`);
+    if (t.anchor?.teamOnly) out.push('- **Answered by the team** (the client was not asked)');
+    if (baseUrl) out.push(`- **Review link:** ${reviewUrl(baseUrl, project.name, t)}`);
+    out.push('');
+    conversationMd(out, t);
+    out.push('');
+  }
+  return out.join('\n') + '\n';
+}
+
+function conversationMd(out, t) {
+  for (const c of t.comments) {
+    const who = `${c.author?.name || 'Someone'} (${c.author?.role || 'client'})`;
+    if (c.kind === 'confirm') {
+      out.push(`- **${who}** · ${c.createdAt.slice(0, 16).replace('T', ' ')}: ✓ confirmed`);
+      continue;
+    }
+    if (c.kind === 'event') out.push(`- _${who} · ${c.createdAt.slice(0, 16).replace('T', ' ')}: ${c.body}_`);
+    else out.push(`- **${who}** · ${c.createdAt.slice(0, 16).replace('T', ' ')}: ${indent(c.body)}`);
+  }
+}
+
+// Where in the app a comment was made when the URL doesn't say: the selected tab(s), and the
+// dialog, menu… it's in with the clicks that open it.
+function whereOf(a = {}) {
+  const view = (a.view || []).map((v) => v.text);
+  if (!view.length && !a.layer) return undefined;
+  return {
+    view: view.length ? view : undefined,
+    layer: a.layer ? { kind: a.layer.kind, label: a.layer.label, openedBy: (a.steps || []).map((s) => s.text || s.selector) } : undefined,
+  };
+}
+
+function whereText(a = {}) {
+  const parts = [];
+  for (const v of a.view || []) parts.push(`tab "${v.text}"`);
+  if (a.layer) {
+    const steps = (a.steps || []).map((s) => `"${s.text || s.selector}"`);
+    parts.push(`${a.layer.kind || 'overlay'}${a.layer.label ? ` "${a.layer.label}"` : ''}${steps.length ? ` (opened by clicking ${steps.join(' → ')})` : ''}`);
+  }
+  return parts.join(' → ');
+}
+
+export function titleOf(t) {
+  const first = t.comments.find((c) => c.kind === 'comment');
+  return oneLine(first?.body || '(no text)', 80);
+}
+
+function shotUrl(baseUrl, name, t) {
+  return `${baseUrl.replace(/\/$/, '')}/__ps/api/projects/${encodeURIComponent(name)}/threads/${t.seq}/shot`;
+}
+
+// Per version whether the comment's element was there: { lastSeen: '5', lost: ['6'] }.
+function versionsOf(t) {
+  const entries = Object.entries(t.checks || {});
+  if (!entries.length) return undefined;
+  const num = (v) => (v === 'live' ? Infinity : Number(v));
+  const seen = entries.filter(([, r]) => r !== 'missing').map(([v]) => v).sort((a, b) => num(a) - num(b));
+  const lost = entries.filter(([, r]) => r === 'missing').map(([v]) => v).sort((a, b) => num(a) - num(b));
+  return { lastSeen: seen[seen.length - 1] || null, lost };
+}
+
+function versionsText(t) {
+  const v = versionsOf(t);
+  if (!v) return '';
+  const name = (x) => (x === 'live' ? 'live' : 'v' + x);
+  const parts = [];
+  if (v.lastSeen) parts.push(`last seen in ${name(v.lastSeen)}`);
+  if (v.lost.length) parts.push(`not found in ${v.lost.map(name).join(', ')} (may already be handled, or the element changed)`);
+  return parts.join(' · ');
+}
+
+export function reviewUrl(baseUrl, name, t) {
+  return `${baseUrl.replace(/\/$/, '')}/s/${encodeURIComponent(name)}#${t.page || '/'}?thread=${t.seq}`;
+}
+
+function pct(v) {
+  return Number.isFinite(v) ? `${Math.round(v * 100)}%` : '?';
+}
+
+function oneLine(s, max) {
+  const flat = String(s).replace(/\s+/g, ' ').trim();
+  return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
+}
+
+function indent(s) {
+  return String(s).replace(/\n/g, '\n  ');
+}
+
+// The brief an agent works from: what to do, then the queued comments and answers. Built by the
+// review's Copy to Agent (brief.md) and by `clickroom process`. `comments` and `answers` are
+// { count, md } digests (toMarkdown with status actionable / answered).
+export function buildBrief(name, { comments, answers, tasks = 0 }, { root, reviewUrl } = {}) {
+  const out = [
+    `# Process clickroom feedback: ${name}`,
+    '',
+    ...(root || reviewUrl ? [...(root ? [`- **Project folder:** \`${root}\``] : []), ...(reviewUrl ? [`- **Review:** ${reviewUrl}`] : []), ''] : []),
+    `The team queued ${[tasks && plural(tasks, 'task'), plural(comments.count - tasks, 'comment')].filter(Boolean).join(', ')} and ${plural(answers.count, 'answer')} for this version.`,
+    'Work each one into the code, then mark it so the review shows where it landed:',
+    '',
+    `1. **${tasks ? 'Tasks and comments' : 'Comments'}:** change the code, then \`clickroom_mark_fixed\` with a short note on what changed.`,
+    '2. **Answers:** change the prototype to follow the answer (a confirmed assumption may need no change), then',
+    '   `clickroom_mark_fixed` on the question with a note on what changed, or "no change needed".',
+    '3. Anything unclear: ask with `clickroom_reply` (one item) or `clickroom_ask` (new question) instead of guessing.',
+    `4. When you're done, push a version: \`clickroom push "<one-line summary>"\`. It records the version on every item you marked.`,
+    '',
+    `No clickroom MCP tools? Use the CLI: \`clickroom resolve ${name} <n> --note "what changed"\` marks an item.`,
+    '',
+    '**Only these items:** leave everything else in the prototype as it is.',
+    '',
+  ];
+  if (comments.count) out.push('---', '', demote(comments.md));
+  if (answers.count) out.push('---', '', demote(answers.md));
+  return out.join('\n').trimEnd() + '\n';
+}
+
+// The digests start at "# …"; nest them under the brief's title.
+const demote = (md) => md.replace(/^(#+) /gm, '#$1 ').trimEnd() + '\n';
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// "Find gaps with Claude": what an agent reads in the prototype to draft questions and assumptions
+// for the client. Run in the background by the project's clickroom terminal (read-only, see
+// cli/gaps.js), or copied from the empty Clarify tab into Claude Code.
+export function gapsPrompt(project) {
+  return [
+    `Look for gaps in the clickroom prototype "${project}": what an agent can't know and would otherwise guess.`,
+    '',
+    `1. Read the prototype's source in this folder (pages, copy, flows), and the questions already asked: clickroom_get_questions {"project":"${project}","status":"all"}. Don't ask anything twice.`,
+    '2. Find what only the client can answer: content that is missing or placeholder, business rules (prices, limits, who can do what), the why and for whom behind a screen, and decisions the prototype makes on their behalf.',
+    `3. For each one, call clickroom_ask {"project":"${project}", ...} once:`,
+    '   - type "question" for something open, "assumption" for a choice the prototype already made that the client should confirm',
+    '   - start the text with a short topic and a colon ("Pricing: Do prices include VAT?"), and keep it to one sentence a client can answer quickly',
+    '   - "now": what the prototype does until it is answered',
+    '   - "page" (and "selector" when it is about one element) so the team sees where it is',
+    '   - a stable "key" (e.g. "pricing-vat") so running this again rewords instead of adding twice',
+    '4. Ask 8 to 12 of the most important ones, most important first. They start as drafts that only the team sees.',
+    '',
+    'Only read and ask: do not change any files.',
+  ].join('\n');
+}