♻️ split Storybook client wiring

Group the Storybook integration, shared plugin loading, and adjacent client package refs into one review slice.

Author: Robdel12

clients/ember/bin/vizzly-testem-launcher.js

@@ -103,7 +103,10 @@ async function main() {
 
     // 2. Determine failOnDiff: env var > server.json > default (false)
     let failOnDiff = false;
-    if (process.env.VIZZLY_FAIL_ON_DIFF === 'true' || process.env.VIZZLY_FAIL_ON_DIFF === '1') {
+    if (
+      process.env.VIZZLY_FAIL_ON_DIFF === 'true' ||
+      process.env.VIZZLY_FAIL_ON_DIFF === '1'
+    ) {
       failOnDiff = true;
     } else {
       let serverInfo = getServerInfo();

clients/ember/src/launcher/screenshot-server.js

@@ -181,7 +181,9 @@ function httpPost(url, data) {
 
         if (res.statusCode >= 400) {
           reject(
-            new Error(`Vizzly server error: ${res.statusCode} - ${responseBody}`)
+            new Error(
+              `Vizzly server error: ${res.statusCode} - ${responseBody}`
+            )
           );
           return;
         }

clients/ember/src/test-support/index.js

@@ -161,8 +161,10 @@ function prepareTestingContainer(width = 1280, height = 720, fullPage = false) {
  * @returns {boolean}
  */
 function shouldFailOnDiff() {
-  return window.__VIZZLY_FAIL_ON_DIFF__ === true ||
-         window.__VIZZLY_FAIL_ON_DIFF__ === 'true';
+  return (
+    window.__VIZZLY_FAIL_ON_DIFF__ === true ||
+    window.__VIZZLY_FAIL_ON_DIFF__ === 'true'
+  );
 }
 
 /**
@@ -285,7 +287,9 @@ export async function vizzlyScreenshot(name, options = {}) {
       // Check if this is a "no server" error - gracefully skip instead of failing
       // This allows tests to pass when Vizzly isn't running (like Percy behavior)
       if (errorText.includes('No Vizzly server found')) {
-        console.warn('[vizzly] Vizzly server not running. Skipping visual screenshot.');
+        console.warn(
+          '[vizzly] Vizzly server not running. Skipping visual screenshot.'
+        );
         return { status: 'skipped', reason: 'no-server' };
       }
 
@@ -302,12 +306,14 @@ export async function vizzlyScreenshot(name, options = {}) {
       if (shouldFail) {
         throw new VizzlyDiffError(
           `Visual difference detected for '${name}' (${result.diffPercentage?.toFixed(2)}% diff). ` +
-          `View diff in Vizzly dashboard.`
+            `View diff in Vizzly dashboard.`
         );
       }
 
       // Log warning but don't fail
-      console.warn(`[vizzly] Visual difference detected for '${name}'. View diff in Vizzly dashboard.`);
+      console.warn(
+        `[vizzly] Visual difference detected for '${name}'. View diff in Vizzly dashboard.`
+      );
     }
 
     return result;
@@ -320,7 +326,9 @@ export async function vizzlyScreenshot(name, options = {}) {
     // Log connection errors only once to avoid spam
     if (!hasLoggedConnectionError) {
       hasLoggedConnectionError = true;
-      console.warn(`[vizzly] Screenshots skipped - server not available. Run 'vizzly tdd start' to enable.`);
+      console.warn(
+        `[vizzly] Screenshots skipped - server not available. Run 'vizzly tdd start' to enable.`
+      );
     }
     return { status: 'skipped', reason: 'error', error: error.message };
   } finally {

clients/ember/tests/unit/screenshot-server.test.js

@@ -231,7 +231,10 @@ describe('screenshot-server', () => {
         // (unless there's a server.json in a parent directory)
         if (info !== null) {
           assert.ok(typeof info.url === 'string', 'should have url');
-          assert.ok(typeof info.failOnDiff === 'boolean', 'should have failOnDiff');
+          assert.ok(
+            typeof info.failOnDiff === 'boolean',
+            'should have failOnDiff'
+          );
         }
       } finally {
         process.chdir(originalCwd);
@@ -260,8 +263,16 @@ describe('screenshot-server', () => {
         let info = getServerInfo();
 
         assert.ok(info !== null, 'should find server.json');
-        assert.strictEqual(info.url, 'http://localhost:47392', 'should have correct url');
-        assert.strictEqual(info.failOnDiff, true, 'should read failOnDiff as true');
+        assert.strictEqual(
+          info.url,
+          'http://localhost:47392',
+          'should have correct url'
+        );
+        assert.strictEqual(
+          info.failOnDiff,
+          true,
+          'should read failOnDiff as true'
+        );
       } finally {
         process.chdir(originalCwd);
       }
@@ -287,8 +298,16 @@ describe('screenshot-server', () => {
         let info = getServerInfo();
 
         assert.ok(info !== null, 'should find server.json');
-        assert.strictEqual(info.url, 'http://localhost:47393', 'should have correct url');
-        assert.strictEqual(info.failOnDiff, false, 'should default failOnDiff to false');
+        assert.strictEqual(
+          info.url,
+          'http://localhost:47393',
+          'should have correct url'
+        );
+        assert.strictEqual(
+          info.failOnDiff,
+          false,
+          'should default failOnDiff to false'
+        );
       } finally {
         process.chdir(originalCwd);
       }

clients/ember/tests/unit/testem-config.test.js

@@ -155,7 +155,10 @@ describe('testem-config', () => {
 
       configure({}, {});
 
-      assert.ok(!existsSync(configPath), 'should not write empty playwright.json');
+      assert.ok(
+        !existsSync(configPath),
+        'should not write empty playwright.json'
+      );
     });
 
     it('handles lowercase browser names', () => {

clients/storybook/README.md

@@ -54,7 +54,7 @@ await run('./storybook-static', {
   viewports: 'mobile:375x667,desktop:1920x1080',
   concurrency: 3,
 }, {
-  logger: console,
+  output: console,
 });
 ```
 

clients/storybook/src/crawler.js

@@ -129,7 +129,9 @@ export function filterStories(stories, config) {
     let storyConfig = extractStoryConfig(story);
     if (storyConfig?.skip) {
       if (verbose) {
-        console.error(`  [filter] Skipping ${story.id} (parameters.vizzly.skip)`);
+        console.error(
+          `  [filter] Skipping ${story.id} (parameters.vizzly.skip)`
+        );
       }
       return false;
     }

clients/storybook/src/index.js

@@ -4,6 +4,8 @@
  * Uses a tab pool for efficient browser tab management
  */
 
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
 import { closeBrowser, launchBrowser } from './browser.js';
 import { loadConfig } from './config.js';
 import { discoverStories } from './crawler.js';
@@ -16,9 +18,6 @@ import { generateTasks, processAllTasks } from './tasks.js';
  * @returns {Promise<boolean>} True if TDD server is running
  */
 async function isTddModeAvailable() {
-  let { existsSync, readFileSync } = await import('node:fs');
-  let { join, parse, dirname } = await import('node:path');
-
   try {
     // Look for .vizzly/server.json
     let currentDir = process.cwd();
@@ -64,11 +63,17 @@ function hasApiToken(config) {
  * Uses a tab pool for efficient parallel screenshot capture
  * @param {string} storybookPath - Path to static Storybook build
  * @param {Object} options - CLI options
- * @param {Object} context - Plugin context (logger, config, services)
+ * @param {Object} context - Plugin context (output, config, services)
  * @returns {Promise<void>}
  */
 export async function run(storybookPath, options = {}, context = {}) {
-  let { logger, config: vizzlyConfig, services } = context;
+  let {
+    output: providedOutput,
+    logger: legacyOutput,
+    config: vizzlyConfig,
+    services,
+  } = context;
+  let output = providedOutput || legacyOutput;
   let browser = null;
   let pool = null;
   let serverInfo = null;
@@ -77,8 +82,10 @@ export async function run(storybookPath, options = {}, context = {}) {
   let buildId = null;
   let startTime = null;
 
-  if (!logger) {
-    throw new Error('Logger is required but was not provided in context');
+  if (!output) {
+    throw new Error(
+      'Output utilities are required but were not provided in context'
+    );
   }
 
   try {
@@ -90,9 +97,9 @@ export async function run(storybookPath, options = {}, context = {}) {
     let hasToken = hasApiToken(vizzlyConfig);
 
     if (isTdd) {
-      logger.info('📍 TDD mode: Using local server');
+      output.info('📍 TDD mode: Using local server');
     } else if (hasToken) {
-      logger.info('☁️  Run mode: Uploading to cloud');
+      output.info('☁️  Run mode: Uploading to cloud');
     }
 
     let buildUrl = null;
@@ -108,7 +115,7 @@ export async function run(storybookPath, options = {}, context = {}) {
         testRunner.once('build-created', buildInfo => {
           if (buildInfo.url) {
             buildUrl = buildInfo.url;
-            logger.info(`🔗 ${buildInfo.url}`);
+            output.info(`🔗 ${buildInfo.url}`);
           }
         });
 
@@ -125,7 +132,7 @@ export async function run(storybookPath, options = {}, context = {}) {
           pullRequestNumber = gitInfo.prNumber;
         } else {
           // Fallback for older CLI versions - use environment variables
-          logger.warn(
+          output.warn(
             '⚠️  Upgrade to @vizzly-testing/cli@>=0.25.0 for improved git detection'
           );
           branch = process.env.VIZZLY_BRANCH || 'main';
@@ -167,29 +174,29 @@ export async function run(storybookPath, options = {}, context = {}) {
         process.env.VIZZLY_ENABLED = 'true';
       } catch (error) {
         // Log the error and continue without cloud mode
-        logger.error(`Failed to initialize cloud mode: ${error.message}`);
-        logger.warn('⚠️  Falling back to local-only mode');
-        logger.info('   Screenshots will not be uploaded to cloud');
+        output.error(`Failed to initialize cloud mode: ${error.message}`);
+        output.warn('⚠️  Falling back to local-only mode');
+        output.info('   Screenshots will not be uploaded to cloud');
         testRunner = null;
       }
     }
 
     if (!isTdd && !hasToken) {
-      logger.warn('⚠️  No TDD server or API token found');
-      logger.info('   Run `vizzly tdd start` or set VIZZLY_TOKEN');
+      output.warn('⚠️  No TDD server or API token found');
+      output.info('   Run `vizzly tdd start` or set VIZZLY_TOKEN');
     }
 
     // Start HTTP server to serve Storybook static files
     serverInfo = await startStaticServer(config.storybookPath);
 
     // Discover stories
     let stories = await discoverStories(config.storybookPath, config);
-    logger.info(
+    output.info(
       `📚 Found ${stories.length} stories in ${config.storybookPath}`
     );
 
     if (stories.length === 0) {
-      logger.warn('⚠️  No stories found');
+      output.warn('⚠️  No stories found');
       return;
     }
 
@@ -199,18 +206,18 @@ export async function run(storybookPath, options = {}, context = {}) {
 
     // Generate all tasks upfront (stories × viewports)
     let tasks = generateTasks(stories, serverInfo.url, config);
-    logger.info(
+    output.info(
       `📸 Processing ${tasks.length} screenshots (${config.concurrency} concurrent tabs)`
     );
 
     // Process all tasks through the tab pool
-    let errors = await processAllTasks(tasks, pool, config, logger);
+    let errors = await processAllTasks(tasks, pool, config, output);
 
     // Report summary
     if (errors.length > 0) {
-      logger.warn(`\n⚠️  ${errors.length} screenshot(s) failed:`);
+      output.warn(`\n⚠️  ${errors.length} screenshot(s) failed:`);
       errors.forEach(({ story, viewport, error }) => {
-        logger.error(`   ${story}@${viewport}: ${error}`);
+        output.error(`   ${story}@${viewport}: ${error}`);
       });
     }
 
@@ -220,11 +227,11 @@ export async function run(storybookPath, options = {}, context = {}) {
       await testRunner.finalizeBuild(buildId, false, true, executionTime);
 
       if (buildUrl) {
-        logger.info(`🔗 View results: ${buildUrl}`);
+        output.info(`🔗 View results: ${buildUrl}`);
       }
     }
   } catch (error) {
-    logger.error('Failed to process stories:', error.message);
+    output.error('Failed to process stories:', error.message);
 
     // Mark build as failed if in run mode
     if (testRunner && buildId) {

clients/storybook/src/navigation.js

@@ -47,7 +47,9 @@ export async function navigateToStory(page, storyId, baseUrl, options = {}) {
     await fullPageNavigation(page, storyId, baseUrl, timeout);
 
     if (verbose) {
-      console.error(`  [nav] ${storyId}: full-page took ${Date.now() - start}ms`);
+      console.error(
+        `  [nav] ${storyId}: full-page took ${Date.now() - start}ms`
+      );
     }
 
     if (entry) {
@@ -71,7 +73,9 @@ export async function navigateToStory(page, storyId, baseUrl, options = {}) {
     await clientSideNavigation(page, storyId, timeout);
 
     if (verbose) {
-      console.error(`  [nav] ${storyId}: client-side took ${Date.now() - start}ms`);
+      console.error(
+        `  [nav] ${storyId}: client-side took ${Date.now() - start}ms`
+      );
     }
     entry.currentStoryId = storyId;
   } catch (error) {
@@ -83,7 +87,9 @@ export async function navigateToStory(page, storyId, baseUrl, options = {}) {
     await fullPageNavigation(page, storyId, baseUrl, timeout);
 
     if (verbose) {
-      console.error(`  [nav] ${storyId}: fallback full-page took ${Date.now() - start}ms`);
+      console.error(
+        `  [nav] ${storyId}: fallback full-page took ${Date.now() - start}ms`
+      );
     }
     entry.currentStoryId = storyId;
   }
@@ -152,10 +158,10 @@ async function clientSideNavigation(page, storyId, timeout) {
         // Navigate to the story
         preview.channel.emit('setCurrentStory', { storyId: id });
 
-        // Timeout fallback - use configured timeout
+        // Trigger the full-page fallback when Storybook does not emit a render.
         timeoutId = setTimeout(() => {
           preview.channel.off('storyRendered', handleRendered);
-          resolve(); // Resolve anyway - story might have rendered
+          reject(new Error(`Storybook did not render ${id} before timeout`));
         }, timeoutMs);
       });
     },

clients/storybook/src/plugin.js

@@ -38,10 +38,10 @@ export default {
    * @param {import('commander').Command} program - Commander program instance
    * @param {Object} context - Plugin context
    * @param {Object} context.config - Vizzly configuration
-   * @param {Object} context.logger - Logger instance
+   * @param {Object} context.output - Output utilities
    * @param {Object} context.services - Service container
    */
-  register(program, { config, logger, services }) {
+  register(program, { config, output, services }) {
     program
       .command('storybook <path>')
       .description('Capture screenshots from static Storybook build')
@@ -78,14 +78,14 @@ export default {
           let mergedOptions = { ...globalOptions, ...options };
 
           await run(path, mergedOptions, {
-            logger,
+            output,
             config,
             services,
           });
         } catch (error) {
           console.error('Failed to run Storybook plugin:', error);
-          if (logger?.error) {
-            logger.error('Failed to run Storybook plugin:', error.message);
+          if (output?.error) {
+            output.error('Failed to run Storybook plugin:', error);
           }
           process.exit(1);
         }