v0.2.4: --headed flag actually works on browser-driving subcommands; dismiss new "Skip intro" overlay

Two bug reports from a first-time user, both confirmed and fixed:

#1 (Commander option resolution)
   `--headed` had no effect on `submit`, `resume`, `fetch`, `loop`. The
   flag was defined on each subcommand without a default, so
   `opts.headed` resolved to `undefined` (falsy) and the browser
   always launched headless regardless of CLI intent. The wizard
   itself was unaffected because the program-level `--headed` had a
   `true` default. Fixed by giving each browser-driving subcommand
   the same `--headed (default: true)` + `--no-headed` pattern as the
   program level. So `pnpm design submit <id>` now launches headed
   by default; `--no-headed` flips for CI / smoke tests. Verified
   via a Commander parser smoke test before shipping.

#2 (Live UI regression)
   `fillNewProject` timed out clicking the Create button on first
   project creation per session. claude.ai/design started shipping a
   "Skip intro" onboarding overlay that intercepts pointer events on
   the form behind it. Added `dismissOnboardingOverlay()` at the
   start of `fillNewProject` — best-effort 1.5s wait, click if
   visible, silently fall through if not. Tries multiple locators
   ("Skip intro", "Skip", text fallback) so a future copy rotation
   doesn't silently regress us. Once dismissed, the persistent
   profile never sees it again; on subsequent runs the dismissal is
   a silent no-op.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: talzu

CHANGELOG.md

@@ -6,6 +6,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-05-15
+
+### Fixed
+- **`--headed` had no effect on `submit`, `resume`, `fetch`, and `loop`
+  subcommands** — the flag was defined on each subcommand without a
+  default value, so `opts.headed` resolved to `undefined` (falsy) and
+  the browser always launched headless, ignoring the user's `--headed`
+  intent. The program-level `--headed` flag (used by the wizard) was
+  unaffected. Each browser-driving subcommand now defines `--headed`
+  with `default: true` and a companion `--no-headed` to flip it,
+  matching the program-level pattern. So `pnpm design submit <id>`
+  now launches headed by default; pass `--no-headed` for CI / quick
+  smoke tests.
+- **`fillNewProject` timed out clicking the Create button on first
+  project creation per session** — claude.ai/design started shipping a
+  "Skip intro" onboarding overlay that intercepts pointer events on
+  the form behind it. We now best-effort dismiss the overlay
+  (1.5s wait + click) at the start of `fillNewProject`. Once
+  dismissed, the persistent Chromium profile never sees it again,
+  so the dismissal is a silent no-op on subsequent runs.
+
 ## [0.2.3] - 2026-05-15
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekolabs/claude-design-loop",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Round-trip design loop between your IDE and claude.ai/design. Capture a route, send a brief, iterate visually with Claude, fetch the handoff bundle, translate it into framework-native scaffolds, and verify the result.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,

src/cli.ts

@@ -67,7 +67,7 @@ const program = new Command();
 program
   .name('design-loop')
   .description('Round-trip design loop between your IDE and claude.ai/design')
-  .version('0.2.3');
+  .version('0.2.4');
 
 // Default action: when no subcommand is supplied, drop into the wizard.
 program
@@ -106,7 +106,8 @@ program
     'Drive claude.ai/design end-to-end for an existing loop: open project, attach screenshots, send brief, wait for the first design pass, then hand control to an interactive terminal prompt for review/iterate/fetch.',
   )
   .argument('<loopId>', 'loop id (the directory name under design-loops/)')
-  .option('--headed', 'show the browser window (recommended for review)')
+  .option('--headed', 'show the browser window (recommended for review)', true)
+  .option('--no-headed', 'run the browser headless (CI / quick smoke tests)')
   .option(
     '--fidelity <fidelity>',
     'wireframe | high-fidelity (default: high-fidelity)',
@@ -159,7 +160,8 @@ program
     '--project-url <url>',
     'override the manifest-saved project URL (claude.ai/design/p/...)',
   )
-  .option('--headed', 'show the browser window (recommended)')
+  .option('--headed', 'show the browser window (recommended)', true)
+  .option('--no-headed', 'run the browser headless (CI / quick smoke tests)')
   .option(
     '--no-interactive',
     'skip the terminal review prompt \u2014 exit after the first settle',
@@ -201,7 +203,8 @@ program
     '--project-url <url>',
     'override the manifest-saved project URL (claude.ai/design/p/...)',
   )
-  .option('--headed', 'show the browser window')
+  .option('--headed', 'show the browser window', true)
+  .option('--no-headed', 'run the browser headless (CI / quick smoke tests)')
   .option(
     '--no-pull',
     'just capture the bundle URL, don\'t auto-pull (you\'ll need to run pull yourself)',
@@ -365,7 +368,8 @@ program
   .argument('<route>', 'route path, e.g. / or /canonical')
   .option('--breakpoints <list>', 'comma-separated viewport widths in px')
   .option('--intent <text>', 'optional one-line intent for this round')
-  .option('--headed', 'show the browser window')
+  .option('--headed', 'show the browser window', true)
+  .option('--no-headed', 'run the browser headless (CI / quick smoke tests)')
   .option('--fidelity <fidelity>', 'wireframe | high-fidelity (default: high-fidelity)')
   .option(
     '--no-interactive',

src/lib/claude-design.ts

@@ -617,6 +617,16 @@ async function assertLoggedIn(page: Page, headed: boolean): Promise<void> {
 
 async function fillNewProject(page: Page, opts: SubmitOptions): Promise<void> {
   console.log(`[submit] creating project "${opts.projectName}" ...`);
+
+  // claude.ai/design ships a "Skip intro" onboarding overlay on first
+  // project creation per session. It intercepts pointer events on the
+  // form below it (most visibly: the Create button click times out).
+  // Dismiss it eagerly so every later interaction in this function
+  // works against the real form. Once dismissed it stays dismissed for
+  // the persistent profile, so on subsequent runs the locator never
+  // resolves and we fall through silently.
+  await dismissOnboardingOverlay(page);
+
   const nameBox = page.getByRole('textbox', { name: 'Project name' });
   await nameBox.fill(opts.projectName);
 
@@ -662,6 +672,37 @@ function createButtonLocator(page: Page): import('playwright').Locator {
   return page.locator('[data-testid="create-project-button"]');
 }
 
+/**
+ * Best-effort dismissal of the "Skip intro" onboarding overlay that
+ * claude.ai/design started shipping in mid-2026. It pops up on first
+ * project creation per session and intercepts pointer events on the
+ * form behind it — most visibly causing the Create button click to
+ * time out. We try a 1.5s wait and silently fall through if it never
+ * appears (subsequent runs in the persistent profile never see it).
+ *
+ * Multiple selectors because Anthropic has rotated the button copy in
+ * past UI revisions and a single role-name match is brittle.
+ */
+async function dismissOnboardingOverlay(page: Page): Promise<void> {
+  const candidates = [
+    page.getByRole('button', { name: /^Skip intro$/i }),
+    page.getByRole('button', { name: /^Skip$/i }),
+    page.locator('button:has-text("Skip intro")'),
+  ];
+  for (const locator of candidates) {
+    try {
+      await locator.first().waitFor({ state: 'visible', timeout: 1500 });
+      console.log('[submit] dismissing onboarding overlay');
+      await locator.first().click({ timeout: 2000 });
+      // Let the overlay animate out before any subsequent interaction.
+      await page.waitForTimeout(400);
+      return;
+    } catch {
+      /* not present on this run — try the next candidate */
+    }
+  }
+}
+
 /**
  * Locator for a fidelity card button. String matching is critical here —
  * the buttons render with an icon prefix that shows up as a leading space