@ytspar/sweetlink 1.19.0 → 1.21.0

package/dist/cli/sweetlink.js

@@ -9,13 +9,13 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { WebSocket } from 'ws';
 import { detectCDP, getNetworkRequestsViaCDP } from '../cdp.js';
+import { DaemonRequestError, daemonRequest, ensureDaemon, getDaemonStatus, stopDaemon, } from '../daemon/client.js';
+import { uploadEvidence } from '../daemon/evidence.js';
+import { extractPort } from '../daemon/stateFile.js';
 import { screenshotViaPlaywright } from '../playwright.js';
 import { getCardHeaderPreset, getNavigationPreset, measureViaPlaywright } from '../ruler.js';
 import { DEFAULT_WS_PORT, MAX_PORT_RETRIES, WS_PORT_OFFSET } from '../types.js';
 import { SCREENSHOT_DIR } from '../urlUtils.js';
-import { daemonRequest, ensureDaemon, getDaemonStatus, stopDaemon } from '../daemon/client.js';
-import { extractPort } from '../daemon/stateFile.js';
-import { uploadEvidence } from '../daemon/evidence.js';
 import { emitJson, printOutputSchema } from './outputSchemas.js';
 const COMMON_APP_PORTS = [3000, 3001, 4000, 5173, 5174, 8000, 8080];
 /**
@@ -118,7 +118,9 @@ function reportScreenshotSuccess(outputPath, width, height, method, selector) {
     try {
         sizeKb = ` · ${Math.round(fs.statSync(outputPath).size / 1024)}KB`;
     }
-    catch { /* file may have been moved or removed */ }
+    catch {
+        /* file may have been moved or removed */
+    }
     const selPart = selector ? ` · ${selector}` : '';
     if (process.env.SWEETLINK_VERBOSE === '1') {
         console.log(`[Sweetlink] ✓ Screenshot saved to: ${getRelativePath(outputPath)}`);
@@ -188,8 +190,7 @@ async function discoverServer(target) {
     }
     const lowerTarget = target.toLowerCase();
     // Exact match on branch or app name
-    const exact = results.find((r) => r.gitBranch?.toLowerCase() === lowerTarget ||
-        r.appName?.toLowerCase() === lowerTarget);
+    const exact = results.find((r) => r.gitBranch?.toLowerCase() === lowerTarget || r.appName?.toLowerCase() === lowerTarget);
     if (exact)
         return `ws://localhost:${exact.port}`;
     // Partial match (branch contains target)
@@ -485,8 +486,11 @@ async function screenshot(options) {
                 `Use --index N (with click) or a more specific selector to pick another.`);
         }
         // UX: hint at --full-page when content extends below the viewport.
-        if (!options.selector && !options.fullPage &&
-            data.pageHeight && data.viewportHeight && data.pageHeight > data.viewportHeight + 4) {
+        if (!options.selector &&
+            !options.fullPage &&
+            data.pageHeight &&
+            data.viewportHeight &&
+            data.pageHeight > data.viewportHeight + 4) {
             const overflow = data.pageHeight - data.viewportHeight;
             console.log(`[Sweetlink] ℹ Page extends ${overflow}px below the viewport. ` +
                 `Use --full-page to capture all of it.`);
@@ -1547,6 +1551,27 @@ async function getVitals(options) {
         process.exit(1);
     }
 }
+function printInspectSummary(data) {
+    console.log('\n[Sweetlink] Agent Inspect');
+    console.log(`  URL: ${data.url}`);
+    console.log(`  Title: ${data.title || '(untitled)'}`);
+    console.log(`  Viewport: ${data.viewport.width}x${data.viewport.height}` +
+        (data.viewport.deviceScaleFactor ? ` @${data.viewport.deviceScaleFactor}x` : ''));
+    console.log(`  Artifacts: ${getRelativePath(data.artifacts.dir)}`);
+    console.log(`  Refs: ${data.counts.refs} | Console: ${data.counts.consoleErrors} errors, ${data.counts.consoleWarnings} warnings | Network: ${data.counts.networkFailures} failures`);
+    if (data.counts.a11yViolations !== undefined) {
+        console.log(`  A11y: ${data.counts.a11yViolations} violations, ${data.counts.a11yIncomplete ?? 0} incomplete`);
+    }
+    if (data.nextActions.length > 0) {
+        console.log('\n  Suggested next actions:');
+        for (const action of data.nextActions) {
+            console.log(`    - ${action}`);
+        }
+    }
+    console.log(`\n  Summary: ${getRelativePath(data.artifacts.summaryMarkdown)}`);
+    console.log(`  JSON:    ${getRelativePath(data.artifacts.contextJson)}`);
+    console.log(`  PNG:     ${getRelativePath(data.artifacts.screenshotPng)}`);
+}
 // Per-command help text, keyed by canonical command name
 const COMMAND_HELP = {
     screenshot: `  screenshot [options]
@@ -1595,6 +1620,30 @@ const COMMAND_HELP = {
       pnpm sweetlink screenshot --force-cdp --width 375 --height 667       # Playwright at iPhone SE
       pnpm sweetlink screenshot --hifi                                     # Pixel-perfect via daemon
       pnpm sweetlink screenshot --responsive                               # 3 breakpoints via daemon`,
+    inspect: `  inspect [options] (alias: context)
+    Capture one LLM-ready frontend context bundle from the daemon.
+
+    Includes:
+      - Full-page screenshot artifact
+      - Interactive @e refs and accessibility snapshot
+      - Console and network deltas from daemon buffers
+      - Axe accessibility summary when axe-core is available
+      - Page timing/viewport metadata and suggested next actions
+
+    Options:
+      --url <url>                 Target URL (default: http://localhost:3000)
+      --last <number>             Console/network entries to include (default: 50)
+      --label <text>              Scenario label for artifact directory
+      --expected <text>           Expected outcome to embed in the bundle
+      --action <text>             Action transcript item (repeatable)
+      --no-a11y                   Skip axe accessibility audit
+      --format <type>             Output format: text (default), json
+      --output <path>             Also write the context JSON to this path
+
+    Examples:
+      pnpm sweetlink inspect --url http://localhost:5173
+      pnpm sweetlink context --label "checkout empty state" --expected "CTA is visible"
+      pnpm sweetlink inspect --format json --output .tmp/inspect.json`,
     query: `  query --selector <css-selector> [options]
     Query DOM elements and return data
 
@@ -1886,15 +1935,21 @@ const COMMAND_HELP = {
       --label <text>              Embedded in filename
       --device <name|udid>        Pick a specific simulator/emulator (default: first booted)
       --time-limit <sec>          Android only — caps screen recording (max 180)
+      --app <name>                Group artifacts under .sweetlink/<app>/<YYYYMMDD>/<run>/sim/
+      --run <id>                  Override the auto-generated run id
+      --no-overlays               Android only — skip tap-event capture and ffmpeg overlay
       --ignore-exit               Don't propagate the recorded command's exit code
 
     Requirements:
       iOS:     Xcode + a booted Simulator (Simulator.app)
       Android: Android Platform Tools (\`adb\`) + a running emulator
+               Tap-indicator overlays additionally need \`ffmpeg\` on PATH;
+               without it, taps are still captured to a sidecar .taps.json.
 
     Examples:
       pnpm sweetlink sim ios "fastlane scan" --device "iPhone 15"
-      pnpm sweetlink sim android "./gradlew connectedAndroidTest"`,
+      pnpm sweetlink sim android "./gradlew connectedAndroidTest"
+      pnpm sweetlink sim android "appium run" --no-overlays`,
     term: `  term <command...>
     Record a shell command's stdout/stderr into asciicast v2 + a self-contained
     HTML player. Captures real timing; the player has play/pause, 0.1×–4×
@@ -1903,6 +1958,8 @@ const COMMAND_HELP = {
     Options:
       --output <path>             .cast file path (default: .sweetlink/term/<label>-<stamp>.cast)
       --label <text>              Label embedded in the .cast title + filename
+      --app <name>                Group artifacts under .sweetlink/<app>/<YYYYMMDD>/<run>/term/
+      --run <id>                  Override the auto-generated run id (HHMM-SS or $SWEETLINK_RUN)
       --shell <path>              Shell to invoke the command in (default: /bin/sh)
       --cols <n>                  Reported terminal width (default: 120)
       --rows <n>                  Reported terminal height (default: 30)
@@ -1910,7 +1967,7 @@ const COMMAND_HELP = {
 
     Examples:
       pnpm sweetlink term "pytest -v" --label api-tests
-      pnpm sweetlink term "go test ./..." --label go-tests
+      pnpm sweetlink term "go test ./..." --app my-app --label go-tests
       pnpm sweetlink term "make build" --output .sweetlink/term/build.cast`,
     sessions: `  sessions [list|open]
     List or open all recorded sessions in this project.
@@ -1970,6 +2027,7 @@ const COMMAND_HELP = {
 const COMMAND_ALIASES = {
     measure: 'ruler',
     accessibility: 'a11y',
+    context: 'inspect',
 };
 const GLOBAL_HELP = `
 Global Flags:
@@ -2010,9 +2068,12 @@ Commands:`);
         // Each block looks like:
         //   "  command [args]\n    First-line description.\n..."
         // We pick the first non-empty line after the signature.
-        const lines = help.split('\n').map((l) => l.trim()).filter(Boolean);
+        const lines = help
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean);
         const desc = lines[1] ?? '';
-        const summary = desc.length > 70 ? desc.slice(0, 67) + '…' : desc;
+        const summary = desc.length > 70 ? `${desc.slice(0, 67)}…` : desc;
         console.log(`  ${name.padEnd(14)} ${summary}`);
     }
     if (process.argv.includes('--all')) {
@@ -2039,12 +2100,161 @@ function showCommandHelp(command) {
 }
 // CLI argument parsing
 const args = process.argv.slice(2);
-// Skip global flags to find the actual command
-const commandType = args.find((a) => !a.startsWith('--')) || args[0];
+// Skip global flags to find the actual command. Falling back to args[0]
+// would surface flags like `--json` as the command — we want undefined
+// in that case so the no-command paths (help / batch mode) can fire.
+const commandType = args.find((a) => !a.startsWith('--'));
 if (!commandType || commandType === '--help' || commandType === '-h') {
+    // `sweetlink --json` with stdin → multi-capture batch mode.
+    // Reads { action: "capture", captures: [...] } from stdin and runs
+    // each entry, aggregating results into a single JSON envelope on stdout.
+    if (args.includes('--json') && !process.stdin.isTTY) {
+        // Top-level await keeps the rest of the dispatch from running while
+        // the batch is in flight; we exit before fallthrough either way.
+        try {
+            await runBatchFromStdin();
+            process.exit(0);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stdout.write(`${JSON.stringify({ ok: false, error: msg })}\n`);
+            process.exit(1);
+        }
+    }
     showHelp();
     process.exit(0);
 }
+async function runBatchFromStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf-8').trim();
+    if (!raw) {
+        throw new Error('No input on stdin. Pipe a JSON document with {"action":"capture","captures":[...]}.');
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Could not parse stdin as JSON: ${e instanceof Error ? e.message : e}`);
+    }
+    if (body.action !== 'capture' || !Array.isArray(body.captures)) {
+        throw new Error('Expected { "action": "capture", "captures": [...] }.');
+    }
+    const startTime = Date.now();
+    const results = [];
+    for (const cap of body.captures) {
+        const t0 = Date.now();
+        const mode = cap.mode;
+        const label = cap.label;
+        try {
+            const data = await runOneBatchCapture(cap);
+            results.push({ ok: true, mode, label, data, duration: Date.now() - t0 });
+        }
+        catch (err) {
+            results.push({
+                ok: false,
+                mode,
+                label,
+                error: err instanceof Error ? err.message : String(err),
+                duration: Date.now() - t0,
+            });
+        }
+    }
+    const allOk = results.every((r) => r.ok);
+    process.stdout.write(`${JSON.stringify({
+        ok: allOk,
+        duration: Date.now() - startTime,
+        captures: results,
+    })}\n`);
+    if (!allOk)
+        process.exit(1);
+}
+async function runOneBatchCapture(cap) {
+    const mode = cap.mode;
+    if (!mode)
+        throw new Error('Capture entry missing required "mode" field.');
+    if (mode === 'term') {
+        const command = cap.command;
+        if (!command)
+            throw new Error('term capture missing "command".');
+        const label = cap.label ?? 'batch';
+        const labelSlug = label
+            .replace(/[^a-z0-9]/gi, '-')
+            .toLowerCase()
+            .slice(0, 40);
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+        const output = cap.output ??
+            path.join(findProjectRoot(), '.sweetlink', 'term', `${labelSlug}-${stamp}.cast`);
+        ensureDir(output);
+        const { captureTerminal } = await import('../term/recorder.js');
+        const { generatePlayer } = await import('../term/player.js');
+        const result = await captureTerminal({
+            command,
+            output,
+            label,
+            shell: cap.shell,
+            cols: typeof cap.cols === 'number' ? cap.cols : undefined,
+            rows: typeof cap.rows === 'number' ? cap.rows : undefined,
+        });
+        const playerPath = await generatePlayer({ castPath: output });
+        return {
+            castPath: output,
+            playerPath,
+            durationSec: result.durationSec,
+            exitCode: result.exitCode,
+            events: result.events,
+        };
+    }
+    if (mode === 'sim-ios' || mode === 'sim-android') {
+        const command = cap.command;
+        if (!command)
+            throw new Error(`${mode} capture missing "command".`);
+        const label = cap.label ?? 'batch';
+        const labelSlug = label
+            .replace(/[^a-z0-9]/gi, '-')
+            .toLowerCase()
+            .slice(0, 40);
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+        const output = cap.output ??
+            path.join(findProjectRoot(), '.sweetlink', 'sim', `${labelSlug}-${stamp}.mp4`);
+        ensureDir(output);
+        const device = cap.device;
+        if (mode === 'sim-ios') {
+            const { recordIosSimulator } = await import('../simulator/ios.js');
+            return recordIosSimulator({ command, output, device });
+        }
+        const { recordAndroidEmulator } = await import('../simulator/android.js');
+        return recordAndroidEmulator({
+            command,
+            output,
+            device,
+            timeLimit: typeof cap.timeLimit === 'number' ? cap.timeLimit : undefined,
+        });
+    }
+    if (mode === 'screenshot') {
+        const targetUrl = cap.url ?? 'http://localhost:3000';
+        const projRoot = findProjectRoot();
+        const state = await ensureDaemon(projRoot, targetUrl);
+        const resp = await daemonRequest(state, 'screenshot', {
+            selector: cap.selector,
+            fullPage: cap.fullPage,
+            viewport: cap.viewport,
+            padding: cap.padding,
+            theme: cap.theme,
+        });
+        const data = resp.data;
+        if (cap.output) {
+            const outputPath = cap.output;
+            ensureDir(outputPath);
+            fs.writeFileSync(outputPath, Buffer.from(data.screenshot, 'base64'));
+            return { path: outputPath, width: data.width, height: data.height };
+        }
+        return { width: data.width, height: data.height, base64Length: data.screenshot.length };
+    }
+    throw new Error(`Unknown capture mode: ${mode}. Allowed: term, sim-ios, sim-android, screenshot.`);
+}
 // Helper function to get argument value
 function getArg(flag) {
     const index = args.indexOf(flag);
@@ -2054,6 +2264,7 @@ function hasFlag(flag) {
     return args.includes(flag);
 }
 // Per-command --help: `pnpm sweetlink screenshot --help`
+// Past the early-exit at the top of dispatch, commandType is non-null.
 if (hasFlag('--help') || hasFlag('-h')) {
     showCommandHelp(commandType);
     process.exit(0);
@@ -2063,6 +2274,8 @@ if (hasFlag('--output-schema')) {
     // If commandType is a known command, print just that schema; otherwise print all
     const knownCommands = [
         'screenshot',
+        'inspect',
+        'context',
         'query',
         'logs',
         'exec',
@@ -2096,7 +2309,9 @@ if (hasFlag('--output-schema')) {
             ? 'ruler'
             : commandType === 'accessibility'
                 ? 'a11y'
-                : commandType
+                : commandType === 'context'
+                    ? 'inspect'
+                    : commandType
         : undefined;
     printOutputSchema(schemaCommand);
     process.exit(0);
@@ -2130,6 +2345,24 @@ function setupJsonMode(command, startTime) {
     });
     return { origExit, getLastError: () => lastErrorMsg };
 }
+function getErrorData(error) {
+    if (error instanceof DaemonRequestError) {
+        return {
+            action: error.action,
+            status: error.status,
+            ...(error.data ? error.data : {}),
+        };
+    }
+    return null;
+}
+function printErrorContext(error) {
+    if (!(error instanceof DaemonRequestError) || !error.data)
+        return;
+    const failureScreenshot = error.data.failureScreenshot;
+    if (typeof failureScreenshot === 'string') {
+        console.error(`[Sweetlink] Failure screenshot: ${failureScreenshot}`);
+    }
+}
 /**
  * Handle the `wait` command: wait for a server to be ready.
  */
@@ -2180,9 +2413,14 @@ async function handleStatusCommand() {
 }
 (async () => {
     const startTime = Date.now();
-    // Resolve --app flag: discover the matching Sweetlink server by branch/app name
+    // Resolve --app flag: for WS-bridge commands, this discovers the matching
+    // Sweetlink server by branch/app name. For commands that produce artifacts
+    // (term/sim), --app is a *namespace* used in the artifact directory layout
+    // (.sweetlink/<app>/<YYYYMMDD>/<run>/...) — those handlers read --app
+    // themselves, so we skip discovery here.
     const appTarget = getArg('--app');
-    if (appTarget) {
+    const isArtifactCommand = commandType === 'term' || commandType === 'sim';
+    if (appTarget && !isArtifactCommand) {
         try {
             resolvedWsUrl = await discoverServer(appTarget);
             console.log(`[Sweetlink] Targeting server: ${resolvedWsUrl}`);
@@ -2223,6 +2461,42 @@ async function handleStatusCommand() {
                         : undefined,
                 });
                 break;
+            case 'inspect':
+            case 'context': {
+                const projRoot = findProjectRoot();
+                const targetUrl = getArg('--url') ?? 'http://localhost:3000';
+                const state = await ensureDaemon(projRoot, targetUrl);
+                const actionTranscript = [];
+                args.forEach((arg, index) => {
+                    if (arg !== '--action')
+                        return;
+                    const value = args[index + 1];
+                    if (!value)
+                        return;
+                    actionTranscript.push({ action: value });
+                });
+                const resp = await daemonRequest(state, 'inspect', {
+                    last: getArg('--last') ? parseInt(getArg('--last'), 10) : undefined,
+                    label: getArg('--label'),
+                    expectedOutcome: getArg('--expected'),
+                    actionTranscript,
+                    includeA11y: !hasFlag('--no-a11y'),
+                });
+                const data = resp.data;
+                const output = getArg('--output');
+                if (output) {
+                    ensureDir(output);
+                    fs.writeFileSync(output, JSON.stringify(data, null, 2), 'utf-8');
+                }
+                if (getArg('--format') === 'json') {
+                    console.log(JSON.stringify(data, null, 2));
+                }
+                else {
+                    printInspectSummary(data);
+                }
+                result = data;
+                break;
+            }
             case 'query': {
                 const selector = getArg('--selector');
                 if (!selector) {
@@ -2318,7 +2592,9 @@ async function handleStatusCommand() {
                         }
                     }
                 }
-                catch { /* fall through to WS path */ }
+                catch {
+                    /* fall through to WS path */
+                }
                 result = await click({
                     selector: clickTarget,
                     text: clickText,
@@ -2446,7 +2722,8 @@ async function handleStatusCommand() {
                 }
                 const sessionDirArg = getArg('--session') ?? '.sweetlink';
                 // Find latest session manifest
-                const sessionFiles = fs.readdirSync(sessionDirArg)
+                const sessionFiles = fs
+                    .readdirSync(sessionDirArg)
                     .filter((f) => f.startsWith('session-'))
                     .sort()
                     .reverse();
@@ -2501,16 +2778,19 @@ async function handleStatusCommand() {
                     const data = resp.data;
                     const m = data.manifest;
                     console.log(`[Sweetlink] Recording stopped: ${m.sessionId}`);
-                    console.log(`  Duration: ${m.duration.toFixed(1)}s | Actions: ${m.commands.length}${m.video ? ' | Video: ' + m.video : ''}`);
+                    console.log(`  Duration: ${m.duration.toFixed(1)}s | Actions: ${m.commands.length}${m.video ? ` | Video: ${m.video}` : ''}`);
                     // Auto-open the viewer (cross-platform; --no-open to suppress)
                     if (data.viewerPath && !hasFlag('--no-open')) {
                         console.log(`  Viewer: ${data.viewerPath}`);
                         const { execFile } = await import('child_process');
                         // `start` on Windows is a cmd builtin, not an exe — must invoke via cmd.
-                        const cmd = process.platform === 'darwin' ? 'open'
-                            : process.platform === 'win32' ? 'cmd'
+                        const cmd = process.platform === 'darwin'
+                            ? 'open'
+                            : process.platform === 'win32'
+                                ? 'cmd'
                                 : 'xdg-open';
-                        const args = process.platform === 'win32' ? ['/c', 'start', '', data.viewerPath]
+                        const args = process.platform === 'win32'
+                            ? ['/c', 'start', '', data.viewerPath]
                             : [data.viewerPath];
                         execFile(cmd, args, (err) => {
                             if (err)
@@ -2553,7 +2833,10 @@ async function handleStatusCommand() {
                     const startResp = await daemonRequest(state, 'record-start', label ? { label } : {});
                     const startData = startResp.data;
                     console.log(`[Sweetlink] Recording: ${startData.sessionId}${label ? ` (${label})` : ''}`);
-                    const steps = script.split(';').map((s) => s.trim()).filter(Boolean);
+                    const steps = script
+                        .split(';')
+                        .map((s) => s.trim())
+                        .filter(Boolean);
                     // Snapshot once up-front so refs resolve.
                     await daemonRequest(state, 'snapshot', { interactive: true });
                     for (const step of steps) {
@@ -2637,7 +2920,8 @@ async function handleStatusCommand() {
                     console.error(`[Sweetlink] Session directory not found: ${sessionDirArg}`);
                     process.exit(1);
                 }
-                const reportSessions = fs.readdirSync(sessionDirArg)
+                const reportSessions = fs
+                    .readdirSync(sessionDirArg)
                     .filter((f) => f.startsWith('session-'))
                     .sort()
                     .reverse();
@@ -2714,7 +2998,10 @@ async function handleStatusCommand() {
                     }
                     const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
                     const summary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf-8') : '';
-                    const payload = { summary, manifest };
+                    const payload = {
+                        summary,
+                        manifest,
+                    };
                     // Include viewer HTML for Slack/Discord webhooks
                     if (/slack|discord/i.test(webhookUrl)) {
                         const viewerPath = path.join(reportSessionDir, 'viewer.html');
@@ -2758,7 +3045,14 @@ async function handleStatusCommand() {
                     console.error('[Sweetlink] Usage: sweetlink sim <ios|android> "<command>" [--output path] [--device <name>]');
                     process.exit(1);
                 }
-                const flagsWithValues = new Set(['--output', '--label', '--device', '--time-limit']);
+                const flagsWithValues = new Set([
+                    '--output',
+                    '--label',
+                    '--device',
+                    '--time-limit',
+                    '--app',
+                    '--run',
+                ]);
                 const positional = [];
                 for (let i = 2; i < args.length; i++) {
                     const a = args[i];
@@ -2776,10 +3070,19 @@ async function handleStatusCommand() {
                 }
                 const label = getArg('--label');
                 const labelSlug = label
-                    ? label.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40)
+                    ? label
+                        .replace(/[^a-z0-9]/gi, '-')
+                        .toLowerCase()
+                        .slice(0, 40)
                     : `sim-${platform}`;
                 const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-                const defaultDir = path.join(findProjectRoot(), '.sweetlink', 'sim');
+                const { runSlot: simRunSlot } = await import('../runs.js');
+                const defaultDir = simRunSlot({
+                    baseDir: findProjectRoot(),
+                    app: getArg('--app'),
+                    run: getArg('--run'),
+                    kind: 'sim',
+                });
                 const output = getArg('--output') ?? path.join(defaultDir, `${labelSlug}-${stamp}.mp4`);
                 ensureDir(output);
                 const device = getArg('--device');
@@ -2793,24 +3096,38 @@ async function handleStatusCommand() {
                     const { recordAndroidEmulator } = await import('../simulator/android.js');
                     const tl = getArg('--time-limit');
                     recResult = await recordAndroidEmulator({
-                        command, output, device,
+                        command,
+                        output,
+                        device,
                         timeLimit: tl ? parseInt(tl, 10) : undefined,
+                        overlays: !hasFlag('--no-overlays'),
                     });
                 }
                 let sizeKb = '?';
                 try {
                     sizeKb = String(Math.round(fs.statSync(output).size / 1024));
                 }
-                catch { /* file may not exist if recordingClosed is false */ }
+                catch {
+                    /* file may not exist if recordingClosed is false */
+                }
+                const tapSuffix = (recResult.tapCount ?? 0) > 0
+                    ? ` · ${recResult.tapCount} taps${recResult.overlaysApplied ? ' (overlaid)' : ' (sidecar only — install ffmpeg for overlays)'}`
+                    : '';
                 console.log(`[Sweetlink] ${recResult.recordingClosed ? '✓' : '⚠'} ${getRelativePath(output)} · ` +
                     `${recResult.durationSec.toFixed(1)}s · ${sizeKb}KB · ${recResult.device} · exit=${recResult.exitCode}` +
-                    (recResult.recordingClosed ? '' : ' (recording was force-killed; mp4 may be incomplete)'));
+                    tapSuffix +
+                    (recResult.recordingClosed
+                        ? ''
+                        : ' (recording was force-killed; mp4 may be incomplete)'));
                 result = {
                     path: output,
                     device: recResult.device,
                     durationSec: recResult.durationSec,
                     exitCode: recResult.exitCode,
                     recordingClosed: recResult.recordingClosed,
+                    tapCount: recResult.tapCount,
+                    tapsJsonPath: recResult.tapsJsonPath,
+                    overlaysApplied: recResult.overlaysApplied,
                 };
                 if (recResult.exitCode !== 0 && !hasFlag('--ignore-exit')) {
                     process.exit(recResult.exitCode);
@@ -2819,8 +3136,16 @@ async function handleStatusCommand() {
             }
             case 'term': {
                 // Record a shell command's stdout/stderr into asciicast v2 + HTML player.
-                // Example: sweetlink term "pytest -v" --label api-tests
-                const flagsWithValues = new Set(['--output', '--label', '--shell', '--cols', '--rows']);
+                // Example: sweetlink term "pytest -v" --label api-tests --app my-app
+                const flagsWithValues = new Set([
+                    '--output',
+                    '--label',
+                    '--shell',
+                    '--cols',
+                    '--rows',
+                    '--app',
+                    '--run',
+                ]);
                 const positional = [];
                 for (let i = 1; i < args.length; i++) {
                     const a = args[i];
@@ -2838,10 +3163,19 @@ async function handleStatusCommand() {
                 }
                 const label = getArg('--label');
                 const labelSlug = label
-                    ? label.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40)
+                    ? label
+                        .replace(/[^a-z0-9]/gi, '-')
+                        .toLowerCase()
+                        .slice(0, 40)
                     : 'term';
                 const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-                const defaultDir = path.join(findProjectRoot(), '.sweetlink', 'term');
+                const { runSlot } = await import('../runs.js');
+                const defaultDir = runSlot({
+                    baseDir: findProjectRoot(),
+                    app: getArg('--app'),
+                    run: getArg('--run'),
+                    kind: 'term',
+                });
                 const output = getArg('--output') ?? path.join(defaultDir, `${labelSlug}-${stamp}.cast`);
                 ensureDir(output);
                 console.log(`[Sweetlink] Recording terminal: ${command}`);
@@ -2940,8 +3274,20 @@ async function handleStatusCommand() {
                         console.log('\nAction sequences are identical.');
                     }
                     result = {
-                        a: { id: a.sessionId, label: a.label, duration: a.duration, actions: a.actionCount, errors: aErr },
-                        b: { id: b.sessionId, label: b.label, duration: b.duration, actions: b.actionCount, errors: bErr },
+                        a: {
+                            id: a.sessionId,
+                            label: a.label,
+                            duration: a.duration,
+                            actions: a.actionCount,
+                            errors: aErr,
+                        },
+                        b: {
+                            id: b.sessionId,
+                            label: b.label,
+                            duration: b.duration,
+                            actions: b.actionCount,
+                            errors: bErr,
+                        },
                         added,
                         removed,
                     };
@@ -2950,12 +3296,12 @@ async function handleStatusCommand() {
                     // Open the index.html in the browser
                     if (data.indexPath) {
                         const { execFile } = await import('child_process');
-                        const cmd = process.platform === 'darwin' ? 'open'
-                            : process.platform === 'win32' ? 'cmd'
+                        const cmd = process.platform === 'darwin'
+                            ? 'open'
+                            : process.platform === 'win32'
+                                ? 'cmd'
                                 : 'xdg-open';
-                        const cmdArgs = process.platform === 'win32'
-                            ? ['/c', 'start', '', data.indexPath]
-                            : [data.indexPath];
+                        const cmdArgs = process.platform === 'win32' ? ['/c', 'start', '', data.indexPath] : [data.indexPath];
                         execFile(cmd, cmdArgs, () => { });
                         console.log(`[Sweetlink] Opened ${data.indexPath}`);
                     }
@@ -3063,10 +3409,13 @@ async function handleStatusCommand() {
                         console.log(`[Sweetlink] Demo: "${state.title}" (${state.sections.length} sections)`);
                         console.log(`  File: ${state.filePath}`);
                         for (const s of state.sections) {
-                            const preview = s.type === 'note' ? s.content.substring(0, 60) :
-                                s.type === 'exec' ? `$ ${s.command}` :
-                                    s.type === 'screenshot' ? `[image] ${s.screenshotFile}` :
-                                        '[snapshot]';
+                            const preview = s.type === 'note'
+                                ? s.content.substring(0, 60)
+                                : s.type === 'exec'
+                                    ? `$ ${s.command}`
+                                    : s.type === 'screenshot'
+                                        ? `[image] ${s.screenshotFile}`
+                                        : '[snapshot]';
                             console.log(`  ${s.type.padEnd(12)} ${preview}`);
                         }
                         result = state;
@@ -3187,8 +3536,10 @@ async function handleStatusCommand() {
             const msg = error instanceof Error ? error.message : String(error);
             emitJson({
                 ok: false,
+                // commandType is non-undefined here: the early-exit at the top of
+                // CLI dispatch handles the bare `--json` (batch mode) case.
                 command: commandType,
-                data: null,
+                data: getErrorData(error),
                 error: msg,
                 duration: Date.now() - startTime,
             });
@@ -3198,6 +3549,7 @@ async function handleStatusCommand() {
         // to end users and clutters the output. Set SWEETLINK_DEBUG=1 to see it.
         if (error instanceof Error) {
             console.error(`[Sweetlink] ${error.message}`);
+            printErrorContext(error);
             if (process.env.SWEETLINK_DEBUG === '1' && error.stack) {
                 console.error(error.stack);
             }