@notis_ai/cli 0.2.5 → 0.2.7

package/src/runtime/output.js

@@ -94,6 +94,14 @@ export class OutputManager {
     process.stderr.write(`${message}\n`);
   }
 
+  emitProgress({ phase, message, requestId = null }) {
+    if (this.runtime.quiet) {
+      return;
+    }
+    const suffix = requestId ? ` (${requestId})` : '';
+    process.stderr.write(`[${phase}] ${message}${suffix}\n`);
+  }
+
   emitSuccess({
     ok = true,
     command,
@@ -116,7 +124,10 @@ export class OutputManager {
       meta: {
         profile: this.runtime.profileName,
         api_base: this.runtime.apiBase,
-        mutating: Boolean(meta.mutating),
+        mutating:
+          meta.mutating === true
+            ? true
+            : (meta.mutating === false ? false : null),
         ...meta,
       },
     };

package/src/runtime/profiles.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { CliError, EXIT_CODES } from './errors.js';
+import { getDesktopAuthRecovery } from './desktop-auth.js';
 
 export const CONFIG_DIR = join(homedir(), '.notis');
 export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
@@ -37,6 +38,9 @@ export function normalizeConfig(rawConfig = {}) {
           typeof profile.access_expires_at === 'number' ? profile.access_expires_at : undefined,
         refresh_expires_at:
           typeof profile.refresh_expires_at === 'number' ? profile.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof profile.desktop_app_name === 'string' ? profile.desktop_app_name : undefined,
+        desktop_pid: typeof profile.desktop_pid === 'number' ? profile.desktop_pid : undefined,
       };
     }
 
@@ -65,6 +69,9 @@ export function normalizeConfig(rawConfig = {}) {
           typeof raw.access_expires_at === 'number' ? raw.access_expires_at : undefined,
         refresh_expires_at:
           typeof raw.refresh_expires_at === 'number' ? raw.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof raw.desktop_app_name === 'string' ? raw.desktop_app_name : undefined,
+        desktop_pid: typeof raw.desktop_pid === 'number' ? raw.desktop_pid : undefined,
       },
     },
   };
@@ -187,7 +194,37 @@ export function resolveTimeoutMs(globalOptions = {}) {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 30000;
 }
 
-export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true } = {}) {
+export function parseDebugEntitlementOverride(value = process.env.NOTIS_DEBUG_ENTITLEMENT_OVERRIDE) {
+  if (!value) {
+    return null;
+  }
+  const candidates = [value];
+  try {
+    candidates.push(Buffer.from(value, 'base64url').toString('utf-8'));
+  } catch {
+    // The plain JSON candidate below will provide the actionable error.
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+      // Try the next supported encoding.
+    }
+  }
+  throw new CliError({
+    code: 'debug_entitlement_override_invalid',
+    message: 'NOTIS_DEBUG_ENTITLEMENT_OVERRIDE must be a JSON object or base64url-encoded JSON object.',
+    exitCode: EXIT_CODES.usage,
+  });
+}
+
+export function resolveRuntimeProfile(
+  globalOptions = {},
+  { requireAuth = true, includeDebugEntitlementOverride = true } = {},
+) {
   const config = loadConfig();
   const profileName = getCurrentProfileName(config, globalOptions.profile);
   const apiBase = getApiBase(config, profileName, globalOptions.apiBase);
@@ -197,43 +234,62 @@ export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true }
   const nonInteractive = isNonInteractive(globalOptions);
   const outputMode = resolveOutputMode(globalOptions);
   const timeoutMs = resolveTimeoutMs(globalOptions);
+  const debugEntitlementOverride = includeDebugEntitlementOverride
+    ? parseDebugEntitlementOverride()
+    : null;
 
   if (requireAuth && !jwt) {
+    const recovery = getDesktopAuthRecovery({
+      apiBase,
+      desktopAppName: profile.desktop_app_name,
+      desktopPid: profile.desktop_pid,
+    });
     throw new CliError({
       code: 'auth_missing',
       message: `No JWT configured for profile ${profileName}`,
       exitCode: EXIT_CODES.auth,
-      hints: [
-        {
-          command: 'Open the Notis desktop app and sign in',
-          reason: 'Set NOTIS_JWT or sign in through the Notis desktop app',
-        },
-      ],
+      hints: recovery.hints,
     });
   }
 
-  // An explicit NOTIS_JWT is a complete credential override: use it verbatim and do
-  // NOT attempt a stored-profile dev_portal token refresh (whose refresh_token may be
-  // stale or belong to a different session). Without this, a long-lived shell with an
-  // expired profile refresh_token fails every command with invalid_grant even though
-  // the supplied NOTIS_JWT is valid.
+  // An explicit NOTIS_JWT is a complete credential override. Use it verbatim
+  // and never replace it with a token later synced by the desktop profile.
   const usingEnvJwt = Boolean(process.env.NOTIS_JWT);
   return {
     config,
     profileName,
     apiBase,
     jwt,
-    authMode: usingEnvJwt ? 'jwt' : profile.auth_mode,
-    refreshToken: usingEnvJwt ? undefined : profile.refresh_token,
-    accessExpiresAt: usingEnvJwt ? undefined : profile.access_expires_at,
-    refreshExpiresAt: usingEnvJwt ? undefined : profile.refresh_expires_at,
+    credentialSource: usingEnvJwt ? 'env' : 'profile',
+    desktopAppName: usingEnvJwt ? undefined : profile.desktop_app_name,
+    desktopPid: usingEnvJwt ? undefined : profile.desktop_pid,
     agentMode,
     nonInteractive,
     outputMode,
     timeoutMs,
+    debugEntitlementOverride,
   };
 }
 
+export function getJwtExpiration(jwt) {
+  if (typeof jwt !== 'string' || !jwt) {
+    return null;
+  }
+  try {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return typeof payload.exp === 'number' ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isJwtExpired(jwt, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const expiration = getJwtExpiration(jwt);
+  return expiration !== null && expiration <= nowSeconds;
+}
+
 export function workspacePath(appId) {
   return join(WORKSPACE_DIR, appId);
 }

package/src/runtime/store-screenshot.js

@@ -0,0 +1,138 @@
+import sharp from 'sharp';
+import { fileURLToPath } from 'node:url';
+
+const STORE_SCREENSHOT_ASPECT = 16 / 10;
+const SHARED_BACKDROP_PATH = fileURLToPath(
+  new URL('./assets/store-screenshot-dark.png', import.meta.url),
+);
+
+const ACCENT_PALETTES = {
+  blue: { glow: '#4f7cff', glow2: '#274690' },
+  violet: { glow: '#9b87f5', glow2: '#5038a1' },
+  emerald: { glow: '#34d399', glow2: '#176b55' },
+  amber: { glow: '#f2a94a', glow2: '#8b4f20' },
+  rose: { glow: '#fb7185', glow2: '#8f3048' },
+  sky: { glow: '#38bdf8', glow2: '#176887' },
+  fuchsia: { glow: '#d946ef', glow2: '#772786' },
+  teal: { glow: '#2dd4bf', glow2: '#176e68' },
+};
+
+const ACCENT_NAMES = Object.keys(ACCENT_PALETTES);
+
+function stableHash(value) {
+  let hash = 2166136261;
+  for (const character of String(value || 'notis-app')) {
+    hash ^= character.codePointAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+export function resolveStoreScreenshotAccent(accent, seed = 'notis-app') {
+  if (accent && ACCENT_PALETTES[accent]) {
+    return accent;
+  }
+  return ACCENT_NAMES[stableHash(seed) % ACCENT_NAMES.length];
+}
+
+export function storeScreenshotLayout(width = 2000, height = 1250) {
+  const horizontalInset = Math.max(48, Math.round(width * 0.06));
+  const verticalInset = Math.max(40, Math.round(height * 0.06));
+  let cardWidth = width - horizontalInset * 2;
+  let cardHeight = Math.round(cardWidth / STORE_SCREENSHOT_ASPECT);
+  const maximumCardHeight = height - verticalInset * 2;
+  if (cardHeight > maximumCardHeight) {
+    cardHeight = maximumCardHeight;
+    cardWidth = Math.round(cardHeight * STORE_SCREENSHOT_ASPECT);
+  }
+  const cardLeft = Math.round((width - cardWidth) / 2);
+  const cardTop = Math.round((height - cardHeight) / 2) - Math.round(height * 0.008);
+  return {
+    width,
+    height,
+    cardWidth,
+    cardHeight,
+    cardLeft,
+    cardTop,
+    radius: Math.max(18, Math.round(width * 0.016)),
+  };
+}
+
+async function backdropImage(layout) {
+  return sharp(SHARED_BACKDROP_PATH)
+    .resize(layout.width, layout.height, { fit: 'cover', position: 'centre' })
+    .png()
+    .toBuffer();
+}
+
+function roundedRectSvg(width, height, radius, { fill = '#ffffff', stroke = null } = {}) {
+  const strokeAttribute = stroke
+    ? ` fill="none" stroke="${stroke}" stroke-width="2"`
+    : ` fill="${fill}"`;
+  return Buffer.from(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect x="1" y="1" width="${width - 2}" height="${height - 2}" rx="${radius}" ry="${radius}"${strokeAttribute}/></svg>`,
+  );
+}
+
+/**
+ * Composite a truthful browser capture into the deterministic Store frame.
+ * The source pixels are only resized/cropped; the app UI is never redrawn.
+ */
+export async function composeStoreScreenshot({
+  inputPath,
+  outputPath,
+  width = 2000,
+  height = 1250,
+  accent = null,
+  seed = 'notis-app',
+  focused = false,
+  theme = 'light',
+}) {
+  const resolvedTheme = theme === 'dark' ? 'dark' : 'light';
+  const layout = storeScreenshotLayout(width, height);
+  const resolvedAccent = resolveStoreScreenshotAccent(accent, seed);
+
+  const roundedCapture = await sharp(inputPath)
+    .resize(layout.cardWidth, layout.cardHeight, {
+      fit: 'cover',
+      position: focused ? 'top' : 'centre',
+    })
+    .composite([{
+      input: roundedRectSvg(layout.cardWidth, layout.cardHeight, layout.radius),
+      blend: 'dest-in',
+    }])
+    .png()
+    .toBuffer();
+
+  const border = roundedRectSvg(
+    layout.cardWidth,
+    layout.cardHeight,
+    layout.radius,
+    { stroke: resolvedTheme === 'dark' ? '#FFFFFF2A' : '#0F172A22' },
+  );
+
+  await sharp(await backdropImage(layout))
+    .composite([
+      { input: roundedCapture, left: layout.cardLeft, top: layout.cardTop },
+      { input: border, left: layout.cardLeft, top: layout.cardTop },
+    ])
+    .png({
+      compressionLevel: 9,
+      adaptiveFiltering: true,
+    })
+    .toFile(outputPath);
+
+  return {
+    mode: 'framed',
+    accent: resolvedAccent,
+    focused: Boolean(focused),
+    theme: resolvedTheme,
+    card: {
+      left: layout.cardLeft,
+      top: layout.cardTop,
+      width: layout.cardWidth,
+      height: layout.cardHeight,
+      radius: layout.radius,
+    },
+  };
+}

package/src/runtime/transport.js

@@ -3,11 +3,11 @@ import { createReadStream } from 'node:fs';
 import { CliError, EXIT_CODES } from './errors.js';
 import {
   DEFAULT_PROFILE,
-  ensureProfile,
   getProfile,
+  isJwtExpired,
   loadConfig,
-  saveConfig,
 } from './profiles.js';
+import { createExpiredAuthError, createInvalidAuthHints } from './desktop-auth.js';
 
 function escapeMultipartHeaderValue(value) {
   return String(value ?? '')
@@ -76,7 +76,7 @@ function createMultipartFileUpload(payload, bindingMetadata, fileBindings) {
   };
 }
 
-function normalizeBackendError(status, payload) {
+function normalizeBackendError(status, payload, runtime) {
   const backendError = payload?.error;
   const message =
     backendError?.message ||
@@ -91,10 +91,7 @@ function normalizeBackendError(status, payload) {
       message,
       exitCode: EXIT_CODES.auth,
       hints: [
-        {
-          command: 'Open the Notis desktop app and sign in',
-          reason: 'Open the Notis desktop app to refresh CLI auth, or set NOTIS_JWT',
-        },
+        ...createInvalidAuthHints(runtime),
       ],
       details: payload || {},
     });
@@ -145,46 +142,10 @@ function normalizeBackendError(status, payload) {
   });
 }
 
-function shouldAttemptDevPortalRefresh(runtime, { force = false } = {}) {
-  if (runtime.authMode !== 'dev_portal' || !runtime.refreshToken || !runtime.apiBase) {
-    return false;
-  }
-
-  if (force) {
-    return true;
-  }
-
-  if (typeof runtime.accessExpiresAt !== 'number' || runtime.accessExpiresAt <= 0) {
+function reloadJwtFromConfig(runtime) {
+  if (runtime.credentialSource === 'env') {
     return false;
   }
-
-  const thresholdSeconds = 60;
-  return runtime.accessExpiresAt - Math.floor(Date.now() / 1000) <= thresholdSeconds;
-}
-
-function persistDevPortalRuntimeAuth(runtime, session) {
-  const config = ensureProfile(loadConfig(), runtime.profileName || DEFAULT_PROFILE);
-  const profileName = runtime.profileName || DEFAULT_PROFILE;
-  config.current_profile = profileName;
-  config.profiles[profileName] = {
-    ...config.profiles[profileName],
-    jwt: session.access_token,
-    api_base: runtime.apiBase,
-    auth_mode: 'dev_portal',
-    refresh_token: session.refresh_token,
-    access_expires_at: session.access_expires_at,
-    refresh_expires_at: session.refresh_expires_at,
-  };
-  saveConfig(config);
-
-  runtime.jwt = session.access_token;
-  runtime.authMode = 'dev_portal';
-  runtime.refreshToken = session.refresh_token;
-  runtime.accessExpiresAt = session.access_expires_at;
-  runtime.refreshExpiresAt = session.refresh_expires_at;
-}
-
-function reloadJwtFromConfig(runtime) {
   const profileName = runtime.profileName || DEFAULT_PROFILE;
   let profile;
   try {
@@ -197,39 +158,8 @@ function reloadJwtFromConfig(runtime) {
     return false;
   }
   runtime.jwt = nextJwt;
-  runtime.authMode = profile.auth_mode;
-  runtime.refreshToken = profile.refresh_token;
-  runtime.accessExpiresAt = profile.access_expires_at;
-  runtime.refreshExpiresAt = profile.refresh_expires_at;
-  return true;
-}
-
-async function maybeRefreshDevPortalAuth(runtime, { force = false } = {}) {
-  if (!shouldAttemptDevPortalRefresh(runtime, { force })) {
-    return false;
-  }
-
-  const response = await fetch(`${runtime.apiBase}/portal_auth/dev-refresh`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'X-Notis-CLI-Version': runtime.cliVersion,
-    },
-    body: JSON.stringify({ refresh_token: runtime.refreshToken }),
-  });
-
-  let payload = null;
-  try {
-    payload = await response.json();
-  } catch {
-    payload = null;
-  }
-
-  if (!response.ok || !payload?.session?.access_token || !payload?.session?.refresh_token) {
-    throw normalizeBackendError(response.status, payload);
-  }
-
-  persistDevPortalRuntimeAuth(runtime, payload.session);
+  runtime.desktopAppName = profile.desktop_app_name;
+  runtime.desktopPid = profile.desktop_pid;
   return true;
 }
 
@@ -241,7 +171,14 @@ export async function httpRequest({
   multipart = false,
   requireAuth = true,
 }) {
-  await maybeRefreshDevPortalAuth(runtime);
+  // The desktop renderer is the single owner of the rotating Supabase refresh
+  // token. Each CLI request only consumes the newest access token it synced to
+  // disk, avoiding refresh-token races between independent CLI processes and
+  // the running desktop session.
+  reloadJwtFromConfig(runtime);
+  if (requireAuth && isJwtExpired(runtime.jwt)) {
+    throw createExpiredAuthError(runtime);
+  }
 
   let controller = new AbortController();
   let timeout = setTimeout(() => controller.abort(), runtime.timeoutMs);
@@ -298,8 +235,7 @@ export async function httpRequest({
     }
 
     if (response.status === 401) {
-      const refreshed = (await maybeRefreshDevPortalAuth(runtime, { force: true }))
-        || reloadJwtFromConfig(runtime);
+      const refreshed = reloadJwtFromConfig(runtime) && !isJwtExpired(runtime.jwt);
       if (refreshed) {
         if (requireAuth && runtime.jwt) {
           headers.Authorization = `Bearer ${runtime.jwt}`;
@@ -324,7 +260,10 @@ export async function httpRequest({
     clearTimeout(timeout);
 
     if (!response.ok) {
-      throw normalizeBackendError(response.status, payload);
+      if (response.status === 401 && isJwtExpired(runtime.jwt)) {
+        throw createExpiredAuthError(runtime);
+      }
+      throw normalizeBackendError(response.status, payload, runtime);
     }
 
     return {
@@ -379,6 +318,9 @@ export async function callTool({
       cwd: process.cwd(),
       agent_mode: runtime.agentMode,
       cli_version: runtime.cliVersion,
+      ...(runtime.debugEntitlementOverride
+        ? { debug_entitlement_override: runtime.debugEntitlementOverride }
+        : {}),
     },
   };
 

package/template/.harness/index.html.tmpl

@@ -3,6 +3,11 @@
 <head>
   <meta charset="utf-8">
   <title>Notis App Harness</title>
+  <script>
+    const harnessTheme = new URLSearchParams(window.location.search).get('theme') === 'dark' ? 'dark' : 'light';
+    document.documentElement.classList.toggle('dark', harnessTheme === 'dark');
+    document.documentElement.dataset.theme = harnessTheme;
+  </script>
   <link rel="stylesheet" href="./bundle/app.css">
   <script type="importmap">
   {
@@ -14,8 +19,80 @@
     }
   }
   </script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap">
   <style>
-    body { margin: 0; font-family: system-ui, sans-serif; }
+    /*
+     * Portal-parity theme tokens. In production the portal copies its computed
+     * :root custom properties onto the app root, so app CSS written against
+     * hsl(var(--token)) resolves to the real portal palette. The harness mirrors
+     * the portal's light theme here so dev renders and listing screenshots look
+     * exactly like the app inside the portal. Keep in sync with
+     * portal/src/app/globals.css (:root).
+     */
+    :root {
+      color-scheme: light;
+      --background: 0 0% 100%;
+      --foreground: 222.2 84% 4.9%;
+      --card: 0 0% 100%;
+      --card-foreground: 222.2 84% 4.9%;
+      --popover: 0 0% 100%;
+      --popover-foreground: 222.2 84% 4.9%;
+      --primary: 222.2 47.4% 11.2%;
+      --primary-foreground: 210 40% 98%;
+      --secondary: 210 40% 96.1%;
+      --secondary-foreground: 222.2 47.4% 11.2%;
+      --muted: 210 40% 96.1%;
+      --muted-foreground: 0 0% 46.9%;
+      --accent: 210 40% 96.1%;
+      --accent-foreground: 222.2 47.4% 11.2%;
+      --destructive: 0 84.2% 60.2%;
+      --destructive-foreground: 210 40% 98%;
+      --border: 214.3 31.8% 91.4%;
+      --input: 214.3 31.8% 91.4%;
+      --ring: 222.2 84% 4.9%;
+      --radius: 0.5rem;
+      --chart-1: 210 100% 49%;
+      --chart-2: 173 58% 39%;
+      --chart-3: 197 37% 24%;
+      --chart-4: 43 74% 66%;
+      --chart-5: 27 87% 67%;
+    }
+    :root.dark {
+      color-scheme: dark;
+      --background: 0 0% 13%;
+      --foreground: 210 40% 98%;
+      --card: 0 0% 13%;
+      --card-foreground: 210 40% 98%;
+      --popover: 0 0% 13%;
+      --popover-foreground: 210 40% 98%;
+      --primary: 210 40% 98%;
+      --primary-foreground: 222.2 47.4% 11.2%;
+      --secondary: 0 0% 18%;
+      --secondary-foreground: 210 40% 98%;
+      --muted: 0 0% 18%;
+      --muted-foreground: 0 0% 65.1%;
+      --accent: 0 0% 18%;
+      --accent-foreground: 210 40% 98%;
+      --destructive: 0 84.2% 60.2%;
+      --destructive-foreground: 210 40% 98%;
+      --border: 0 0% 23.5%;
+      --input: 0 0% 23.5%;
+      --ring: 212.7 26.8% 83.9%;
+      --chart-1: 220 70% 50%;
+      --chart-2: 160 60% 45%;
+      --chart-3: 30 80% 55%;
+      --chart-4: 280 65% 60%;
+      --chart-5: 340 75% 55%;
+    }
+    body {
+      margin: 0;
+      font-family: 'Inter', system-ui, -apple-system, sans-serif;
+      background: hsl(var(--background));
+      color: hsl(var(--foreground));
+      -webkit-font-smoothing: antialiased;
+    }
     #harness-status { position: fixed; top: 0; left: 0; right: 0; padding: 4px 8px; font-size: 11px; background: #111; color: #0f0; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; z-index: 9999; }
     #root { padding-top: 24px; min-height: 100vh; }
   </style>
@@ -29,6 +106,7 @@
     const mode = {{MODE}};
     const apiBase = {{API_BASE}};
     const jwt = {{JWT}};
+    const fixtures = {{FIXTURES}};
     const status = document.getElementById('harness-status');
     const setStatus = (msg, color = '#0f0') => {
       status.textContent = `harness: ${msg}`;
@@ -42,6 +120,7 @@
       mounted: false,
       mode,
       route: descriptor.route && descriptor.route.slug,
+      scenario: descriptor.context && descriptor.context.screenshotScenario,
     };
 
     window.addEventListener('error', (event) => {
@@ -118,15 +197,48 @@
         },
         callTool: async (name, args) => {
           record('callTool', { name, arguments: args || {} });
+          if (fixtures && fixtures.tools && Object.prototype.hasOwnProperty.call(fixtures.tools, name)) {
+            return structuredClone(fixtures.tools[name]);
+          }
           return { ok: true, result: null };
         },
         request: async (path, options) => {
           record('request', { path, options });
+          if (fixtures && fixtures.requests && Object.prototype.hasOwnProperty.call(fixtures.requests, path)) {
+            return structuredClone(fixtures.requests[path]);
+          }
           return null;
         },
       };
     }
 
+    const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+    async function applyScenarioActions() {
+      const actions = fixtures && fixtures.scenario && Array.isArray(fixtures.scenario.actions)
+        ? fixtures.scenario.actions
+        : [];
+      for (const action of actions) {
+        if (action && action.type === 'wait') {
+          await delay(Math.max(0, Number(action.ms) || 0));
+          continue;
+        }
+        if (action && action.type === 'click' && typeof action.selector === 'string') {
+          const deadline = Date.now() + 5000;
+          let element = null;
+          while (!element && Date.now() < deadline) {
+            element = document.querySelector(action.selector);
+            if (!element) await delay(50);
+          }
+          if (!element || typeof element.click !== 'function') {
+            throw new Error(`Screenshot scenario could not click ${action.selector}`);
+          }
+          element.click();
+          await delay(Number(action.settle_ms) || 350);
+        }
+      }
+    }
+
     function liveRuntime() {
       return {
         ...stubRuntime(),
@@ -192,11 +304,21 @@
       window.__harness.renderStarted = true;
       createRoot(document.getElementById('root')).render(React.createElement(Root));
 
-      requestAnimationFrame(() => requestAnimationFrame(() => {
-        window.__harness.mounted = true;
-        const errors = window.__harness.errors.length;
-        const calls = window.__harness.runtimeCalls.length;
-        setStatus(`mounted (errors=${errors}, runtimeCalls=${calls})`, errors ? '#f55' : '#0f0');
+      requestAnimationFrame(() => requestAnimationFrame(async () => {
+        try {
+          await delay(500);
+          await applyScenarioActions();
+          window.__harness.mounted = true;
+          const errors = window.__harness.errors.length;
+          const calls = window.__harness.runtimeCalls.length;
+          setStatus(`mounted (errors=${errors}, runtimeCalls=${calls})`, errors ? '#f55' : '#0f0');
+        } catch (error) {
+          window.__harness.errors.push({
+            type: 'scenario',
+            message: error && error.message ? error.message : String(error),
+          });
+          setStatus(`scenario failed: ${error && error.message ? error.message : String(error)}`, '#f55');
+        }
       }));
     } catch (error) {
       window.__harness.errors.push({

package/template/CHANGELOG.md

@@ -0,0 +1,5 @@
+# App Changelog
+
+## [Initial Release] - {PR_MERGE_DATE}
+
+- First Store release.