wtt-connect 0.2.49 → 0.2.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtt-connect",
-  "version": "0.2.49",
+  "version": "0.2.51",
   "private": false,
   "description": "WTT-native connector daemon for Codex, Claude Code, Cursor, Gemini, ACP, and other coding agent surfaces.",
   "type": "module",

package/src/main.js

@@ -138,7 +138,7 @@ Commands:
   opendesign-upload --dir <path>
                                   Alias for upload-artifact
   preview-port --port <port> [--topic-id <id>] [--snapshot-dir <dir>]
-                                  Create a Cloud Sandbox preview URL and optional persistent snapshot
+                                  Create a Cloud Sandbox live preview URL; snapshots are opt-in
   cleanup-previews                Stop preview servers previously registered by this agent
   help                           Show this help
 `);
@@ -149,6 +149,7 @@ async function previewPort(config, argv) {
   if (!Number.isInteger(port) || port < 1024 || port > 65535 || port === 3000) {
     throw new Error('preview-port requires --port <1024-65535>, excluding 3000');
   }
+  await assertLocalPreviewPort(port, Number(argv.portCheckTimeout || argv.timeout || 5000));
   const keepLast = previewKeepLast(config, argv);
   const cleanup = cleanupOldPreviews(config, {
     currentPort: port,
@@ -162,7 +163,8 @@ async function previewPort(config, argv) {
   const url = preview.preview_url || preview.url;
   if (!url) throw new Error('Cloud Sandbox preview API returned no URL');
   const title = String(argv.title || argv.previewName || preview.name || 'Cloud Sandbox Preview').trim();
-  const snapshot = argv.noSnapshot ? null : await createPreviewSnapshot(config, argv, { title });
+  const wantsSnapshot = Boolean(String(argv.snapshotDir || '').trim()) && !argv.noSnapshot;
+  const snapshot = wantsSnapshot ? await createPreviewSnapshot(config, argv, { title }) : null;
   const snapshotUrl = snapshot?.snapshot_url || '';
   const markdown = JSON.stringify({
     type: 'cloud_sandbox_preview',
@@ -195,6 +197,19 @@ async function previewPort(config, argv) {
   console.log(JSON.stringify({ ok: true, port, url, preview_url: url, snapshot, markdown, cleanup, published }, null, 2));
 }
 
+async function assertLocalPreviewPort(port, timeoutMs = 5000) {
+  const url = `http://127.0.0.1:${port}/`;
+  try {
+    await fetch(url, {
+      method: 'GET',
+      signal: AbortSignal.timeout(Math.max(1000, Math.min(Number(timeoutMs || 5000), 15000))),
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`preview-port local server is not reachable at ${url}: ${message}`);
+  }
+}
+
 async function createPreviewSnapshot(config, argv, { title = 'Cloud Sandbox Preview' } = {}) {
   const dir = String(argv.snapshotDir || '').trim();
   if (!dir) return null;

package/src/runner.js

@@ -943,11 +943,12 @@ function renderCloudSandboxStorageInstruction(config, topicId = '') {
     '- Before publishing a preview URL, verify the server is actually listening and serving content with `curl -fsS http://127.0.0.1:<port>/ >/dev/null`.',
     '- If local curl fails, fix or restart the web server first. Never publish a preview URL for a dead port.',
     '- `wtt-connect preview-port` automatically keeps the most recent preview servers for this agent and stops older registered previews beyond the retention limit. Default retention is 3 live previews; use `--keep-last <n>` only when the user asks.',
-    '- For static pages, animations, charts, dashboards, and HTML demos, pass the generated static directory to `wtt-connect preview-port --snapshot-dir <dir> --snapshot-entry index.html` so WTT stores a persistent snapshot fallback. Live preview URLs are for recent interactive previews; snapshots/artifacts preserve history after cleanup.',
+    '- Do not pass `--snapshot-dir` for normal live previews. Live Cloud Sandbox previews should render as inline WTT preview cards, not as ordinary index.html/document artifacts.',
+    '- If the user explicitly asks for a persistent static artifact or downloadable HTML, publish that separately with `wtt-connect upload-artifact --dir <dir> --title "Short Title"` instead of mixing it with the live preview URL.',
     '- If you start a web server in the sandbox and the user should preview it, call the Cloudflare Sandbox outbound Worker directly with curl and include the returned `preview_url` in your reply as `[preview_url:Short Title](<preview_url>)`.',
     '- Preview ports must be 1024-65535 and cannot be 3000. For Vite/Next-style dev servers prefer 5173, 4173, or 8080.',
     `- Preview curl rule: curl -sS -X POST "\${WTT_SANDBOX_OUTBOX_URL:-http://wtt.preview}/preview-port" -H 'content-type: application/json' -d '{"agent_id":"'\${WTT_AGENT_ID:-cloud-agent}'","port":<port>}'`,
-    `- Prefer automatic WTT publishing when topic id is available: wtt-connect preview-port --port <port>${topicId ? ` --topic-id ${topicId}` : ' --topic-id <topic_id>'} --title "Short Title" --snapshot-dir <static_dir> --snapshot-entry index.html. This publishes a cloud_sandbox_preview card with live and snapshot URLs.`,
+    `- Prefer automatic WTT publishing when topic id is available: wtt-connect preview-port --port <port>${topicId ? ` --topic-id ${topicId}` : ' --topic-id <topic_id>'} --title "Short Title". This publishes one cloud_sandbox_preview live card.`,
   );
   return lines.join('\n');
 }