feat(cli): loading workflow (TTFB, FCP, render-blocking, scripts, fonts)

Add --workflow loading for timing-sensitive loading metrics that require
a real page load, complementing the deterministic audit workflow.

- New cli/src/workflows/loading.js with 6 steps: TTFB, FCP, render-blocking,
  resource-hints, scripts, fonts
- Two new decision-tree rules: TTFB > 600ms → TTFB-Sub-Parts, FCP > 1.8s →
  render-blocking (both run in the shared page session from #76)
- Register loading workflow in bin.js and update help text
- E2E tests in cli/tests/e2e/loading.test.js

Closes #77

Author: nucliweb

cli/src/bin.js

@@ -4,13 +4,15 @@ import { loadSnippet } from "./load-snippet.js";
 import { runSnippets, runMeasurement, VIEWPORT_PRESETS } from "./runner.js";
 import { cwvWorkflow } from "./workflows/cwv.js";
 import { auditWorkflow } from "./workflows/audit.js";
+import { loadingWorkflow } from "./workflows/loading.js";
 import { RULES } from "./decision-tree.js";
 import { reportHuman } from "./reporters/human.js";
 import { reportJson } from "./reporters/json.js";
 
 const WORKFLOWS = {
   "core-web-vitals": cwvWorkflow,
   audit: auditWorkflow,
+  loading: loadingWorkflow,
 };
 
 const SNIPPET_ALIASES = {
@@ -53,7 +55,7 @@ Run curated WebPerf Snippets headlessly via Playwright.
 
 Options:
   --workflow <name>     Workflow to run (default: core-web-vitals)
-                        Workflows: core-web-vitals, audit
+                        Workflows: core-web-vitals, audit, loading
   --snippet <name>      Run a single snippet by alias or Category/Name path
                         Aliases: LCP, CLS, LCP-Subparts, fonts,
                                  render-blocking, resource-hints, preload-scripts,

cli/src/decision-tree.js

@@ -6,6 +6,16 @@ export const RULES = [
     append: { id: "LCP-Subparts", path: "CoreWebVitals/LCP-Subparts" },
     reason: "LCP > 2.5s — drilling into sub-parts",
   },
+  {
+    when: (r) => r.id === "TTFB" && r.status === "ok" && r.value > 600,
+    append: { id: "ttfb-subparts", path: "Loading/TTFB-Sub-Parts" },
+    reason: "TTFB > 600ms — drilling into sub-parts",
+  },
+  {
+    when: (r) => r.id === "FCP" && r.status === "ok" && r.value > 1800,
+    append: { id: "render-blocking", path: "Loading/Find-render-blocking-resources" },
+    reason: "FCP > 1.8s — checking render-blocking resources",
+  },
 ];
 
 export function nextSteps(results) {

cli/src/workflows/loading.js

@@ -0,0 +1,14 @@
+// Loading performance workflow — timing-sensitive measurements requiring a real page load.
+// Complements the audit workflow (deterministic structural checks) with live metrics.
+export const loadingWorkflow = {
+  id: "loading",
+  title: "Loading Performance",
+  steps: [
+    { id: "TTFB", path: "Loading/TTFB" },
+    { id: "FCP", path: "Loading/FCP" },
+    { id: "render-blocking", path: "Loading/Find-render-blocking-resources" },
+    { id: "resource-hints", path: "Loading/Resource-Hints-Validation" },
+    { id: "scripts", path: "Loading/Script-Loading" },
+    { id: "fonts", path: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold" },
+  ],
+};

cli/tests/e2e/loading.test.js

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { runMeasurement, VIEWPORT_PRESETS } from "../../src/runner.js";
+import { loadingWorkflow } from "../../src/workflows/loading.js";
+import { RULES } from "../../src/decision-tree.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_HTML = readFileSync(join(HERE, "../fixtures/index.html"), "utf8");
+
+let server;
+let baseUrl;
+
+beforeAll(
+  () =>
+    new Promise((resolve) => {
+      server = createServer((_req, res) => {
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(FIXTURE_HTML);
+      });
+      server.listen(0, "127.0.0.1", () => {
+        const { port } = server.address();
+        baseUrl = `http://127.0.0.1:${port}`;
+        resolve();
+      });
+    }),
+  10000
+);
+
+afterAll(
+  () =>
+    new Promise((resolve) => {
+      server.close(resolve);
+    })
+);
+
+describe("loading workflow", () => {
+  it(
+    "runs all steps without errors",
+    async () => {
+      const { results } = await runMeasurement({
+        url: baseUrl,
+        workflow: loadingWorkflow,
+        rules: RULES,
+        waitMs: 500,
+        viewport: VIEWPORT_PRESETS.mobile,
+      });
+
+      const stepIds = loadingWorkflow.steps.map((s) => s.id);
+      for (const id of stepIds) {
+        const r = results.find((r) => r.id === id);
+        expect(r, `step "${id}" missing from results`).toBeDefined();
+        expect(r.status, `${id} threw: ${r?.error}`).not.toBe("error");
+      }
+    },
+    30000
+  );
+
+  it(
+    "TTFB returns a numeric value with a rating",
+    async () => {
+      const { results } = await runMeasurement({
+        url: baseUrl,
+        workflow: loadingWorkflow,
+        rules: RULES,
+        waitMs: 500,
+        viewport: VIEWPORT_PRESETS.mobile,
+      });
+
+      const ttfb = results.find((r) => r.id === "TTFB");
+      expect(ttfb.status).toBe("ok");
+      expect(typeof ttfb.value).toBe("number");
+      expect(ttfb.value).toBeGreaterThanOrEqual(0);
+      expect(["good", "needs-improvement", "poor"]).toContain(ttfb.rating);
+      expect(ttfb.unit).toBe("ms");
+    },
+    30000
+  );
+
+  it(
+    "FCP returns a numeric value with a rating",
+    async () => {
+      const { results } = await runMeasurement({
+        url: baseUrl,
+        workflow: loadingWorkflow,
+        rules: RULES,
+        waitMs: 500,
+        viewport: VIEWPORT_PRESETS.mobile,
+      });
+
+      const fcp = results.find((r) => r.id === "FCP");
+      expect(fcp.status).toBe("ok");
+      expect(typeof fcp.value).toBe("number");
+      expect(fcp.value).toBeGreaterThanOrEqual(0);
+      expect(["good", "needs-improvement", "poor"]).toContain(fcp.rating);
+      expect(fcp.unit).toBe("ms");
+    },
+    30000
+  );
+
+  it(
+    "returns a single navMs — only one navigation",
+    async () => {
+      const { navMs } = await runMeasurement({
+        url: baseUrl,
+        workflow: loadingWorkflow,
+        rules: RULES,
+        waitMs: 500,
+        viewport: VIEWPORT_PRESETS.mobile,
+      });
+
+      expect(typeof navMs).toBe("number");
+      expect(navMs).toBeGreaterThan(0);
+    },
+    30000
+  );
+});