@seamapp/core 0.1.0 → 0.2.0

package/migrations/001_seam_init.sql

@@ -29,3 +29,36 @@ create table if not exists seam_changes (
 );
 
 create index if not exists seam_changes_project_idx on seam_changes (project_id, created_at desc);
+
+-- Row-level security. The local engine reads/writes these tables with the anon
+-- (publishable) key. If RLS is enabled with no policy, every snapshot insert
+-- fails with 42501. Enable RLS and grant the anon role the access the engine
+-- needs: INSERT + SELECT + UPDATE on snapshots, INSERT + SELECT + UPDATE on changes.
+alter table seam_snapshots enable row level security;
+
+drop policy if exists "anon insert snapshots" on seam_snapshots;
+create policy "anon insert snapshots"
+  on seam_snapshots for insert to anon with check (true);
+
+drop policy if exists "anon select snapshots" on seam_snapshots;
+create policy "anon select snapshots"
+  on seam_snapshots for select to anon using (true);
+
+drop policy if exists "anon update snapshots" on seam_snapshots;
+create policy "anon update snapshots"
+  on seam_snapshots for update to anon using (true) with check (true);
+
+alter table seam_changes enable row level security;
+
+drop policy if exists "anon insert changes" on seam_changes;
+create policy "anon insert changes"
+  on seam_changes for insert to anon with check (true);
+
+drop policy if exists "anon select changes" on seam_changes;
+create policy "anon select changes"
+  on seam_changes for select to anon using (true);
+
+-- The reverse/restore toggle flips a change's status (completed <-> rolled_back).
+drop policy if exists "anon update changes" on seam_changes;
+create policy "anon update changes"
+  on seam_changes for update to anon using (true) with check (true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapp/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./src/server.js",
   "files": [
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
-    "@seamapp/graphify-bridge": "*",
+    "@seamapp/graphify-bridge": "^0.2.0",
     "@supabase/supabase-js": "^2.43.0",
     "cors": "^2.8.5",
     "diff": "^5.2.0",

package/src/deployer.js

@@ -0,0 +1,51 @@
+import { execa } from 'execa';
+import path from 'path';
+
+/**
+ * Publish the working tree to the live site after a successful apply or rollback.
+ *
+ * This is the missing half of the loop: Seam edits local files, but the whole
+ * point is for the change to GO LIVE, not sit on disk. Configure in
+ * seam.config.json:
+ *
+ *   "deploy": { "enabled": true, "command": "vercel", "args": ["--prod","--yes"], "liveUrl": "https://bidwithsmith.com" }
+ *
+ * Fire-and-forget: never throws into the apply path. Broadcasts its own
+ * lifecycle events so the widget can show "Publishing… / Live ✓".
+ *   DEPLOYING       — started
+ *   DEPLOYED        — { url }   success
+ *   DEPLOY_FAILED   — { message }
+ *   DEPLOY_SKIPPED  — deploy not configured (silent, informational)
+ */
+export async function runDeploy(config, broadcast, { reason } = {}) {
+  const d = config.deploy;
+  if (!d || d.enabled === false || !d.command) {
+    broadcast?.({ type: 'DEPLOY_SKIPPED', message: 'Auto-deploy is not configured for this project.' });
+    return { skipped: true };
+  }
+
+  const cwd = path.resolve(process.cwd(), config.projectRoot || '.');
+  broadcast?.({ type: 'DEPLOYING', message: 'Publishing to your live site…', reason });
+
+  try {
+    const res = await execa(d.command, d.args || [], {
+      cwd,
+      timeout: d.timeoutMs || 180_000,
+      all: true
+    });
+    // Pull the production URL out of the CLI output (Vercel prints it).
+    const text = res.all || res.stdout || '';
+    const urls = text.match(/https?:\/\/[^\s"']+/g) || [];
+    const deployUrl = urls[urls.length - 1] || null;
+    const url = d.liveUrl || deployUrl;
+    broadcast?.({ type: 'DEPLOYED', url, deployUrl, message: url ? `Live at ${url}` : 'Published to your live site.' });
+    return { ok: true, url, deployUrl };
+  } catch (err) {
+    const msg = (err.shortMessage || err.message || 'deploy failed').split('\n')[0];
+    broadcast?.({
+      type: 'DEPLOY_FAILED',
+      message: `Saved locally, but publishing to the live site failed: ${msg}. Your change is on disk and reversible — you can retry the publish.`
+    });
+    return { ok: false, error: msg };
+  }
+}

package/src/fileResolver.js

@@ -0,0 +1,102 @@
+import Anthropic from '@anthropic-ai/sdk';
+import fs from 'fs-extra';
+import path from 'path';
+import { queryGraph } from '../../graphify-bridge/src/index.js';
+
+// Lazy client: the Anthropic key is loaded by dotenv in server.js's body, which
+// runs AFTER this module is imported. Instantiating at module-load time would
+// capture an undefined key. Build it on first use instead, when env is populated.
+let _client;
+function client() {
+  if (!_client) _client = new Anthropic({ apiKey: process.env.SEAM_ANTHROPIC_KEY });
+  return _client;
+}
+
+// Files Seam can actually edit. Images/video/binaries are excluded.
+const EDITABLE = /\.(html?|jsx?|tsx?|mjs|cjs|css|scss|sass|less|json|jsonc|md|mdx|sql|vue|svelte|astro|py|rb|go|rs|java|php|txt|ya?ml|toml|xml|svg)$/i;
+const SKIP = /(^|[\\/])(node_modules|\.git|graphify-out|dist|build|\.next|\.tmp|coverage)[\\/]/;
+
+function readManifest(graphifyOut) {
+  const p = path.join(process.cwd(), graphifyOut, 'manifest.json');
+  let m;
+  try { m = fs.readJsonSync(p); } catch { return []; }
+  const files = Array.isArray(m) ? m : Object.keys(m);
+  return files.filter(f => EDITABLE.test(f) && !SKIP.test(f));
+}
+
+/**
+ * Natural-language file resolver. Replaces brittle keyword gating: an LLM reads
+ * the user's plain-English request plus the project's file list and decides
+ * which files to edit — or asks for clarification, or says it can't tell.
+ *
+ * Graphify is used only as a *ranking hint*, never as a gate. Returns one of:
+ *   { status: 'resolved', files: [...], reason }
+ *   { status: 'clarify',  question, options: [...] }   // options are full, ready-to-send requests
+ *   { status: 'unclear',  message }
+ * plus { usage } for token logging.
+ */
+export async function resolveFiles({ request, config }) {
+  const allFiles = readManifest(config.graphifyOut);
+  if (!allFiles.length) {
+    return { status: 'unclear', message: "I can't see any editable files in this project yet. Try rebuilding the graph, then ask again.", usage: null };
+  }
+
+  // Best-effort graph hint — never throws, never gates.
+  let hints = [];
+  try {
+    const nodes = await queryGraph(request, config.graphifyOut);
+    hints = [...new Set(nodes.map(n => n.source_file || n.file).filter(Boolean))];
+  } catch { /* graph optional */ }
+
+  const system = `You map a user's plain-English website change request to the file(s) that must be edited.
+
+You will get the request and the full list of editable files in the project. A "graph hint" may list files that keyword-matched the request — treat it as a weak suggestion that is often wrong or noisy; trust your own reasoning about what the request means.
+
+Reply with ONLY a JSON object, no markdown, exactly one of these shapes:
+{ "status": "resolved", "files": ["relative/path", ...], "reason": "one short sentence" }
+{ "status": "clarify", "question": "a short, friendly question", "options": ["a full restated request", "another full restated request"] }
+{ "status": "unclear", "message": "a friendly sentence telling the user what you'd need to proceed" }
+
+Rules:
+- Choose the FEWEST files that satisfy the request. A typical small site change is ONE file.
+- Use ONLY paths that appear verbatim in the file list. Never invent or guess a path.
+- For a static site, visible content (buttons, text, hero, sections, forms, colors) almost always lives in the .html files — prefer those over docs/specs/markdown unless the request is clearly about docs.
+- If the request is ambiguous (could mean two different places/things), return "clarify". Each option MUST be a complete, self-contained request the user could send as-is (e.g. "Change the Book Smith button on the homepage to green").
+- If nothing in the project plausibly matches, or the request is too vague to act on, return "unclear" and suggest how to phrase it (name the page or the visible element).
+- Be forgiving of typos and loose wording — infer intent the way a helpful teammate would.`;
+
+  const user = [
+    `Request: ${request}`,
+    hints.length ? `\nGraph hint (may be wrong/noisy): ${hints.join(', ')}` : '',
+    `\nEditable files in this project:\n${allFiles.join('\n')}`
+  ].filter(Boolean).join('\n');
+
+  let resp;
+  try {
+    resp = await client().messages.create({
+      model: 'claude-haiku-4-5-20251001',
+      max_tokens: 1024,
+      system,
+      messages: [{ role: 'user', content: user }]
+    });
+  } catch (err) {
+    return { status: 'unclear', message: "I couldn't reach the model to interpret your request. Check the Anthropic key and try again.", usage: null };
+  }
+
+  const raw = (resp.content[0]?.text || '').replace(/```json|```/g, '').trim();
+  let out;
+  try { out = JSON.parse(raw); }
+  catch { return { status: 'unclear', message: "I had trouble understanding that — can you rephrase, naming the page or element you mean?", usage: resp.usage }; }
+
+  if (out.status === 'resolved') {
+    const valid = (out.files || []).filter(f => allFiles.includes(f));
+    if (!valid.length) {
+      return { status: 'unclear', message: "I couldn't pinpoint which file to change — can you name the page or the visible element (e.g. 'the Book Smith button on the homepage')?", usage: resp.usage };
+    }
+    return { status: 'resolved', files: valid, reason: out.reason || '', usage: resp.usage };
+  }
+  if (out.status === 'clarify' && out.question) {
+    return { status: 'clarify', question: out.question, options: Array.isArray(out.options) ? out.options.slice(0, 4) : [], usage: resp.usage };
+  }
+  return { status: 'unclear', message: out.message || "I couldn't tell what you want to change — try naming the page or element.", usage: resp.usage };
+}

package/src/fileWriter.js

@@ -105,16 +105,17 @@ export async function buildDryRunPreview(changePlan, config) {
 }
 
 /**
- * Read only the files referenced by graph nodes — returns { filepath: content }.
+ * Read the given files (array of relative path strings) — returns { filepath: content }.
  * Hard-capped at 10 files per COST_AND_SAFETY.md rules.
  */
-export async function readRelevantFiles(graphNodes, projectRoot) {
+export async function readRelevantFiles(filePaths, projectRoot) {
   const files = {};
-  const nodes = graphNodes.slice(0, 10);
-  for (const node of nodes) {
-    const absPath = path.resolve(projectRoot || process.cwd(), node.file);
+  const paths = (filePaths || []).slice(0, 10);
+  for (const rel of paths) {
+    if (!rel) continue;
+    const absPath = path.resolve(projectRoot || process.cwd(), rel);
     if (await fs.pathExists(absPath)) {
-      files[node.file] = await fs.readFile(absPath, 'utf8');
+      files[rel] = await fs.readFile(absPath, 'utf8');
     }
   }
   return files;

package/src/requestHandler.js

@@ -1,12 +1,20 @@
 import Anthropic from '@anthropic-ai/sdk';
-import { queryGraph, getBlastRadius } from '../../graphify-bridge/src/index.js';
+import { getNodesForFiles, getBlastRadius } from '../../graphify-bridge/src/index.js';
+import { resolveFiles } from './fileResolver.js';
 import { classifyRisk } from './riskClassifier.js';
 import { createSnapshot, logChange, rollbackToToken } from './snapshotManager.js';
 import { applyChangePlan, buildDryRunPreview, readRelevantFiles } from './fileWriter.js';
 import { processAttachments } from './attachmentProcessor.js';
 import { logTokenUsage } from './tokenLogger.js';
-
-const client = new Anthropic({ apiKey: process.env.SEAM_ANTHROPIC_KEY });
+import { runDeploy } from './deployer.js';
+
+// Lazy client: dotenv loads the key in server.js's body, which runs AFTER this
+// module is imported. Build the client on first use so it captures the real key.
+let _client;
+function client() {
+  if (!_client) _client = new Anthropic({ apiKey: process.env.SEAM_ANTHROPIC_KEY });
+  return _client;
+}
 
 const pendingPlans = new Map();
 
@@ -38,43 +46,68 @@ async function _handleChangeRequest({ requestId, request, attachments, config, b
     return;
   }
 
-  broadcast({ type: 'STATUS', status: 'analyzing', requestId, message: 'Reading the graph...' });
+  broadcast({ type: 'STATUS', status: 'analyzing', requestId, message: 'Understanding your request...' });
 
   const processedAttachments = await processAttachments(attachments, config);
 
-  // Graph query — 5s timeout per COST_AND_SAFETY.md
-  const graphNodes = await Promise.race([
-    queryGraph(request, config.graphifyOut),
-    timeout(5_000, 'Graph query')
+  // Natural-language file resolution (LLM). Graphify is a hint, not a gate.
+  // 15s timeout — a single cheap Haiku call.
+  const resolution = await Promise.race([
+    resolveFiles({ request, config }),
+    timeout(15_000, 'File resolution')
   ]);
 
-  if (!graphNodes.length) {
+  if (resolution.usage) {
+    await logTokenUsage({
+      requestId, request, tier: 'resolve',
+      inputTokens: resolution.usage.input_tokens,
+      outputTokens: resolution.usage.output_tokens,
+      status: 'resolved'
+    }).catch(() => {});
+  }
+
+  // Ambiguous request → ask the user instead of guessing or failing.
+  if (resolution.status === 'clarify') {
+    broadcast({
+      type: 'CLARIFY', requestId,
+      question: resolution.question,
+      options: resolution.options || []
+    });
+    return;
+  }
+
+  // Couldn't tell what to change → guide the user, don't dead-end.
+  if (resolution.status !== 'resolved' || !resolution.files?.length) {
     broadcast({
       type: 'FAILED', requestId,
-      message: "Seam couldn't find the relevant files in your codebase graph. Try rebuilding the graph (Settings → Rebuild Graph) or be more specific about what you want to change."
+      message: resolution.message || "I couldn't tell which file to change — try naming the page or the visible element (e.g. 'the Book Smith button on the homepage')."
     });
     return;
   }
 
+  const filePaths = resolution.files;
+
+  // Pull graph nodes for the resolved files so risk/blast-radius still work.
+  const graphNodes = await getNodesForFiles(filePaths, config.graphifyOut).catch(() => []);
   const blastRadius = getBlastRadius(graphNodes);
   const tier = classifyRisk(request, graphNodes, blastRadius);
 
   broadcast({
     type: 'RISK_ASSESSMENT', requestId, tier, blastRadius,
-    affectedFiles: graphNodes.map(n => n.file),
+    affectedFiles: filePaths,
     message: getRiskMessage(tier, blastRadius)
   });
 
   if (tier === 'B' || tier === 'C') {
     pendingPlans.set(requestId, {
-      request, graphNodes, blastRadius, tier,
+      request, filePaths, blastRadius, tier,
       processedAttachments, config,
       state: 'awaiting_confirmation'
     });
     return;
   }
 
-  await executePlan({ requestId, request, graphNodes, processedAttachments, tier, config, broadcast });
+  await executePlan({ requestId, request, filePaths, processedAttachments, tier, config, broadcast });
 }
 
 export async function executeConfirmedPlan(planId, broadcast) {
@@ -97,7 +130,7 @@ async function _executeConfirmedPlan(planId, broadcast) {
   await executePlan({
     requestId: planId,
     request: pending.request,
-    graphNodes: pending.graphNodes,
+    filePaths: pending.filePaths,
     processedAttachments: pending.processedAttachments,
     tier: pending.tier,
     config: pending.config,
@@ -105,10 +138,10 @@ async function _executeConfirmedPlan(planId, broadcast) {
   });
 }
 
-async function executePlan({ requestId, request, graphNodes, processedAttachments, tier, config, broadcast }) {
+async function executePlan({ requestId, request, filePaths, processedAttachments, tier, config, broadcast }) {
   broadcast({ type: 'STATUS', status: 'planning', requestId, message: 'Planning changes...' });
 
-  const fileContents = await readRelevantFiles(graphNodes, config.projectRoot);
+  const fileContents = await readRelevantFiles(filePaths, config.projectRoot);
 
   // One Claude call — 30s timeout per COST_AND_SAFETY.md
   let claudeResponse;
@@ -196,9 +229,18 @@ async function _applyApprovedPlan({ requestId, changePlan, fileContents, tier, r
     return;
   }
 
+  // Capture the POST-change contents so the change has a redo target. Without
+  // this the after-snapshot is empty and Reverse can't be un-reversed. Reading
+  // the just-written files is best-effort — a failure here must not undo a
+  // successful change, so we fall back to an empty snapshot (undo still works).
+  let afterContents = {};
+  try {
+    afterContents = await readRelevantFiles(writtenFiles, config.projectRoot);
+  } catch { /* redo target unavailable; undo via before-snapshot still works */ }
+
   const afterToken = await createSnapshot({
     changePlan, status: 'after', projectId: config.projectId,
-    request, tier, fileContents: {}, parentToken: beforeToken
+    request, tier, fileContents: afterContents, parentToken: beforeToken
   });
 
   await logChange({
@@ -207,6 +249,11 @@ async function _applyApprovedPlan({ requestId, changePlan, fileContents, tier, r
   });
 
   broadcast({ type: 'COMPLETE', requestId, beforeToken, afterToken, filesChanged: writtenFiles, message: 'Done' });
+
+  // The whole point of the loop: the change must GO LIVE, not sit on disk.
+  // Fire-and-forget so a slow publish never blocks/fails the apply — the deployer
+  // broadcasts its own DEPLOYING/DEPLOYED/DEPLOY_FAILED events to the widget.
+  runDeploy(config, broadcast, { reason: 'apply' }).catch(() => {});
 }
 
 async function callClaude({ request, fileContents, processedAttachments }) {
@@ -221,7 +268,7 @@ Your job is to return a JSON change plan ONLY — no explanation, no markdown, n
 The JSON must be this exact shape:
 {
   "originalRequest": "the user's request verbatim",
-  "summary": "one sentence: what this change does",
+  "summary": "a plain-English confirmation written for a non-technical site owner. Restate what they asked for in their own terms, name the visible on-page element by what it LOOKS LIKE and WHERE it sits (e.g. 'the As Seen On Shark Tank badge in the top-right of the hero photo'), and state its current value vs the new value in plain words (e.g. 'it's green right now — changing it to brown'). NO file names, CSS classes, variable names, hex codes, or code.",
   "changes": [
     {
       "filepath": "relative/path/to/file.tsx",
@@ -237,7 +284,8 @@ Rules:
 - Make the MINIMUM change that satisfies the request
 - Do not refactor unrelated code
 - Do not add features not asked for
-- originalSnippet must be unique enough to find exactly once in the file`;
+- originalSnippet must be unique enough to find exactly once in the file
+- The "summary" is shown to the user as a comprehension check BEFORE they approve — it must prove you understood them. Describe the element the way they SEE it on the page, not the way it appears in code.`;
 
   const messageContent = [];
 
@@ -258,7 +306,7 @@ Rules:
 
   messageContent.push({ type: 'text', text: userMessage });
 
-  const response = await client.messages.create({
+  const response = await client().messages.create({
     model: 'claude-sonnet-4-20250514',
     max_tokens: 4096,
     system: systemPrompt,
@@ -286,7 +334,7 @@ Rules:
 }
 
 function getRiskMessage(tier, blastRadius) {
-  if (tier === 'A') return 'Safe change — ready to apply.';
-  if (tier === 'B') return `Logic change — affects ${blastRadius.affectedNodes} file(s) across ${blastRadius.communities} section(s). Review before applying.`;
-  return `High risk — touches ${blastRadius.godNodes.length || 'core'} critical module(s) across ${blastRadius.communities} section(s). Read carefully.`;
+  if (tier === 'A') return 'Small, self-contained edit — safe to apply.';
+  if (tier === 'B') return 'This touches a few connected parts of your site, so it could affect more than what you asked. Worth a quick review before applying.';
+  return 'This edits a central part of your site, so a small change here can ripple further than expected. Read the preview, then apply — your current version is saved, so you can reverse it in one click.';
 }

package/src/server.js

@@ -10,7 +10,7 @@ import fs from 'fs-extra';
 import { fileURLToPath } from 'url';
 
 import { handleChangeRequest, executeConfirmedPlan, applyApprovedPlan } from './requestHandler.js';
-import { rollbackToToken, getChangeHistory } from './snapshotManager.js';
+import { rollbackToToken, getChangeHistory, toggleChange } from './snapshotManager.js';
 import { rebuildGraph } from '../../graphify-bridge/src/index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -129,6 +129,23 @@ app.post('/api/rollback', async (req, res) => {
   }
 });
 
+// Toggle a change on/off. direction 'undo' restores the before-state,
+// 'redo' restores the after-state — both re-publish and flip the change status.
+app.post('/api/toggle', async (req, res) => {
+  const { beforeToken, afterToken, direction } = req.body;
+  if (!beforeToken || !afterToken) return res.status(400).json({ error: 'beforeToken and afterToken required' });
+  if (activeRequest) return res.status(409).json({ error: 'A change is already in progress.' });
+  activeRequest = true;
+  res.json({ status: 'toggling' });
+  try {
+    await toggleChange({ beforeToken, afterToken, direction: direction === 'redo' ? 'redo' : 'undo', config, broadcast });
+  } catch (err) {
+    broadcast({ type: 'FAILED', message: err.message });
+  } finally {
+    activeRequest = false;
+  }
+});
+
 app.get('/api/history', async (req, res) => {
   const history = await getChangeHistory(config.projectId);
   res.json({ history });

package/src/snapshotManager.js

@@ -91,17 +91,18 @@ export async function logChange({ projectId, request, tier, filesChanged, before
 }
 
 /**
- * Full rollback: restore files from a before_token snapshot.
- * Returns the list of restored file paths.
+ * Write the files captured in a snapshot back to disk. Pure file restore —
+ * no status bookkeeping, no deploy. Returns the restored file paths.
+ * Shared by the write-failure rollback and the user-facing toggle.
  */
-export async function rollbackToToken(beforeToken, config, broadcast) {
-  const snapshot = await loadSnapshot(beforeToken);
+async function restoreFilesFromSnapshot(token, config) {
+  const snapshot = await loadSnapshot(token);
 
   const { applyChangePlan } = await import('./fileWriter.js');
-  const restoredFiles = Object.keys(snapshot.files);
+  const restoredFiles = Object.keys(snapshot.files || {});
 
-  const rollbackPlan = {
-    originalRequest: `Rollback to ${beforeToken}`,
+  const restorePlan = {
+    originalRequest: `Restore ${token}`,
     tier: snapshot.risk_tier,
     changes: restoredFiles.map(filepath => ({
       filepath,
@@ -110,9 +111,71 @@ export async function rollbackToToken(beforeToken, config, broadcast) {
     }))
   };
 
-  await applyChangePlan(rollbackPlan, config);
+  await applyChangePlan(restorePlan, config);
+  return restoredFiles;
+}
+
+/**
+ * Flip a logged change's status (completed <-> rolled_back) so the History
+ * toggle survives reloads. Matched on the change's before/after token pair.
+ */
+async function setChangeStatus({ beforeToken, afterToken, status }) {
+  const supabase = getClient();
+  const { error } = await supabase
+    .from('seam_changes')
+    .update({ status })
+    .eq('before_token', beforeToken)
+    .eq('after_token', afterToken);
+  if (error) throw new Error(`setChangeStatus failed: ${error.message}`);
+}
+
+/**
+ * Full rollback: restore files from a before_token snapshot.
+ * Used on a failed write to undo partial changes. Returns restored paths.
+ */
+export async function rollbackToToken(beforeToken, config, broadcast) {
+  const restoredFiles = await restoreFilesFromSnapshot(beforeToken, config);
   await markRolledBack(beforeToken);
 
   if (broadcast) broadcast({ type: 'STATUS', status: 'rolled_back', message: `Rolled back to ${beforeToken.slice(0, 8)}...` });
+
+  // A rescind only matters if the live site reverts too. Publish the restored
+  // files (fire-and-forget — the deployer broadcasts its own publish events).
+  const { runDeploy } = await import('./deployer.js');
+  runDeploy(config, broadcast, { reason: 'rollback' }).catch(() => {});
+
   return { restoredFiles, beforeToken };
 }
+
+/**
+ * Toggle a single change on or off — the reversible on/off switch.
+ *   direction 'undo' → restore the BEFORE snapshot (the change's pre-state)
+ *   direction 'redo' → restore the AFTER  snapshot (the change's post-state)
+ * Both directions re-publish the restored files to the live site and flip the
+ * logged change's status so the widget knows which way the toggle points. This
+ * is what makes Reverse reversible: every change stores both old and new file
+ * state, so flipping it off and back on are symmetric operations.
+ */
+export async function toggleChange({ beforeToken, afterToken, direction, config, broadcast }) {
+  const undo = direction !== 'redo';
+  const token = undo ? beforeToken : afterToken;
+  if (!token) throw new Error(`Cannot ${undo ? 'reverse' : 'restore'} — this change has no ${undo ? 'before' : 'after'} snapshot.`);
+
+  const restoredFiles = await restoreFilesFromSnapshot(token, config);
+
+  // Best-effort: flip the logged status so the History button toggles. The
+  // files are already restored, so a status-write failure (e.g. a missing
+  // "anon update changes" RLS policy) must not fail the whole reverse.
+  await setChangeStatus({ beforeToken, afterToken, status: undo ? 'rolled_back' : 'completed' }).catch(() => {});
+
+  if (broadcast) broadcast({
+    type: 'STATUS',
+    status: undo ? 'rolled_back' : 'restored',
+    message: undo ? `Reversed ${beforeToken.slice(0, 8)}…` : `Restored ${afterToken.slice(0, 8)}…`
+  });
+
+  const { runDeploy } = await import('./deployer.js');
+  runDeploy(config, broadcast, { reason: direction }).catch(() => {});
+
+  return { restoredFiles, direction };
+}