feat(sideshow-term): add clear command (#31)

Author: benvinegar

CHANGELOG.md

@@ -22,6 +22,8 @@ All notable user-visible changes to this project are documented in this file.
   and bare `sideshow-term` opens the watcher. Terminal servers default to port
   4243, with `--port` for choosing another local port. The watcher supports
   mouse input for clicking sidebar snippets and wheel-scrolling content.
+  Agents can run `sideshow-term clear` to remove stale visualizations from the
+  current session, or `sideshow-term clear --all` to clear the whole surface.
   `sideshow-term serve` remains for explicit server-only use.
 - Snippets are now "surfaces" throughout the API: `/api/surfaces`, `surface-*`
   SSE events, and comments keyed by `surfaceId`. The old snippet endpoints and

sideshow-term/README.md

@@ -67,6 +67,7 @@ sideshow-term render <file|-> [--width N]   preview STML to plain text (Bun)
 sideshow-term publish <file|-> [--title …]  publish an STML snippet
 sideshow-term update <id> <file|->          revise a snippet (new version)
 sideshow-term list / sessions               inspect what's published
+sideshow-term clear [--session id|--all]    clear existing visualizations
 sideshow-term demo                          seed an example session
 sideshow-term guide / setup                 print the agent contract
 ```

sideshow-term/bin/sideshow-term.js

@@ -43,6 +43,8 @@ usage:
   sideshow-term update <id> <file|->      revise a snippet (new version)
       --title <t>            replace title
   sideshow-term list [--session <id>|--all]   list snippets
+  sideshow-term clear [--session <id>|--all] [--sessions]
+                                      clear existing visualizations
   sideshow-term sessions                  list sessions
   sideshow-term comment <text> [opts]     post a comment
       --snippet <id> | --session <id>
@@ -375,6 +377,37 @@ const commands = {
     out(await api(`/api/sessions/${session}/snippets`));
   },
 
+  async clear() {
+    const { values: flags } = parse({
+      options: {
+        session: { type: "string" },
+        all: { type: "boolean" },
+        sessions: { type: "boolean" },
+      },
+    });
+    if (flags.all && flags.session) fail("pass either --session or --all, not both");
+    const sessionIds = flags.all
+      ? (await api("/api/sessions")).map((session) => session.id)
+      : [flags.session ?? (await resolveSession(flags))].filter(Boolean);
+    if (sessionIds.length === 0) fail("no active session — pass --session or --all");
+
+    let visualizations = 0;
+    let deletedSessions = 0;
+    for (const session of sessionIds) {
+      const snippets = await api(`/api/sessions/${session}/snippets`);
+      for (const snippet of snippets) {
+        await api(`/api/snippets/${snippet.id}`, { method: "DELETE" });
+        visualizations += 1;
+      }
+      if (flags.sessions) {
+        await api(`/api/sessions/${session}`, { method: "DELETE" });
+        deletedSessions += 1;
+      }
+    }
+
+    out({ ok: true, sessions: sessionIds.length, visualizations, deletedSessions });
+  },
+
   async sessions() {
     parse();
     out(await api("/api/sessions"));

sideshow-term/guide/AGENT_SETUP.md

@@ -17,6 +17,10 @@ sideshow-term update <id> revised.stml
 
 # Preview in your own shell, no viewer needed:
 sideshow-term render sketch.stml
+
+# Clear stale visuals before replacing a board:
+sideshow-term clear           # current session
+sideshow-term clear --all     # every session on this surface
 ```
 
 If `sideshow-term` is not on PATH but you are in this repo, use

sideshow-term/skills/sideshow-term/SKILL.md

@@ -38,6 +38,10 @@ Save the returned `sessionId` and snippet `id`. Iterate with
 publishing near-duplicates — versions are kept. Preview without the viewer:
 `sideshow-term render sketch.stml`.
 
+To remove stale visuals before replacing a board, run `sideshow-term clear` for
+the current session or `sideshow-term clear --all` for every session on the
+surface.
+
 Rules of thumb:
 
 - On your first publish, set a session title that names the task ("Auth