fix(stage): the ready handshake survives an empty referrer, and the CI harness step builds once

Ready handshake: with a strict Referrer-Policy the frame had nowhere to
post `ready` and the publisher posted nothing before `ready`, so neither
side ever spoke. The bridge now remembers the last `ready` and re-posts
it the moment an allowlisted message teaches it the parent origin; the
stage component subscribes to seeks before posting `ready` so that
listener exists. The publisher says hello (`{ type, t: 0 }`) at most
once per 500 ms until `ready` arrives. Specs cover both sides.

CI harness step: the stage scroll verification built the website twice
(a standalone build, then the serve's own build dependency) and the
second run dropped the content symlink. The standalone build is gone;
the symlink is added after the readiness curl succeeds. The scroll-craft
README's local commands mirror the same ordering.

Minor: StageAct drops the unused `stage-frame-chrome` and
`stage-rail-heading` class names and gains `stage-rail-beat` /
`stage-rail-hold` test ids, which home-stage.spec.ts now locates by.
`StageMilestone` lives in stage-beats.ts (re-exported from the
publisher) and analytics/events.ts types `stage_event` and `beat` from
it instead of duplicating the unions.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: blove

.github/workflows/ci.yml

@@ -676,22 +676,22 @@ jobs:
       # act and fails on dead scroll outside the declared hold and on cues that
       # never peak. The Nx build lands in dist/apps/website with a rewritten
       # next.config, which only `nx serve --configuration=production` can
-      # start; the content symlink mirrors playwright.config.ts's production
-      # mode. The earlier e2e builds run with --skip-nx-cache and write no
-      # cache entry, so this build is a full one; the serve skips the cache
-      # too, otherwise its own build target restores dist/apps/website from
-      # the entry this step just wrote and drops the symlink.
+      # start, and the serve's own build dependency is the one build here:
+      # it runs with --skip-nx-cache (the earlier e2e builds wrote no cache
+      # entry either) so it emits dist rather than restoring it. The content
+      # symlink, which mirrors playwright.config.ts's production mode, is
+      # added only after the server answers, so it lands on the dist the
+      # build has finished writing rather than on one it is about to replace.
       - name: Stage scroll verification (scroll-craft harness)
         env:
           GROWTH_FORM_POLICY: growth_v1
           SCROLLCRAFT_CHROME: /usr/bin/google-chrome
         run: |
           command -v ffmpeg > /dev/null || (sudo apt-get update && sudo apt-get install -y ffmpeg)
-          npx nx build website
-          ln -sfn ../../../apps/website/content dist/apps/website/content
           (npx nx serve website --configuration=production --port=4308 --skip-nx-cache > /tmp/next-start.log 2>&1 &)
           for i in $(seq 1 60); do curl -sf http://127.0.0.1:4308/ > /dev/null && break; sleep 2; done
           curl -sf http://127.0.0.1:4308/ > /dev/null || { cat /tmp/next-start.log; exit 1; }
+          ln -sfn ../../../apps/website/content dist/apps/website/content
           node apps/website/e2e/scroll-craft/verify-home.mjs --url http://127.0.0.1:4308 --out dist/stage-shots
       - name: Upload stage contact sheets
         if: always()

apps/website/e2e/home-stage.spec.ts

@@ -66,7 +66,9 @@ test.describe('homepage stage', () => {
     await expect(page.locator('html')).toHaveClass(/sc-ready/);
     await scrollAct(page, 0.05);
     expect(await progress(page)).toBeGreaterThan(0);
-    const stream = page.locator('.stage-rail-beat[data-beat="stream"]');
+    const stream = page
+      .getByTestId('stage-rail-beat')
+      .and(page.locator('[data-beat="stream"]'));
     await expect(stream).toHaveCSS('opacity', '1');
     // Inside the approve hold: approve spans 0.4167..0.8167 of the act and the
     // hold is 35–70% of it (0.5567..0.6967). 0.68 also sits on the last hold
@@ -76,7 +78,7 @@ test.describe('homepage stage', () => {
       'data-sc-verify-hold',
       'true'
     );
-    await expect(page.locator('.stage-rail-hold').last()).toHaveCSS(
+    await expect(page.getByTestId('stage-rail-hold').last()).toHaveCSS(
       'opacity',
       /^(0\.[5-9]\d*|1)$/
     );
@@ -87,7 +89,9 @@ test.describe('homepage stage', () => {
     );
     await scrollAct(page, 1);
     await expect(
-      page.locator('.stage-rail-beat[data-beat="render"]')
+      page
+        .getByTestId('stage-rail-beat')
+        .and(page.locator('[data-beat="render"]'))
     ).toHaveCSS('opacity', '1');
   });
 

apps/website/e2e/scroll-craft/README.md

@@ -47,17 +47,19 @@ those facts; run them with `--modes desktop,phone,reduced`.
 Build and serve the production site on a free port, then verify:
 
 ```bash
-npx nx build website
-ln -sfn ../../../apps/website/content dist/apps/website/content
 (npx nx serve website --configuration=production --port=4308 --skip-nx-cache &)
 until curl -sf http://127.0.0.1:4308/ > /dev/null; do sleep 2; done
+ln -sfn ../../../apps/website/content dist/apps/website/content
 node apps/website/e2e/scroll-craft/verify-home.mjs --url http://127.0.0.1:4308 --out dist/stage-shots
 ```
 
-The serve skips the Nx cache on purpose: its own build target would otherwise
-restore `dist/apps/website` from the entry the build just wrote and drop the
-`content` symlink. Kill the backgrounded serve when you are done (`lsof
--iTCP:4308 -sTCP:LISTEN -n` names the process).
+The serve's own build dependency emits `dist/apps/website`; there is no
+separate build step. It skips the Nx cache on purpose so that build is a real
+one rather than a cache restore, and the `content` symlink is added only once
+the server answers, so it lands on the directory the build has finished
+writing rather than on one the build is still about to replace. Kill the
+backgrounded serve when you are done (`lsof -iTCP:4308 -sTCP:LISTEN -n` names
+the process).
 
 The Nx build lands in `dist/apps/website` with a rewritten `next.config`, so a
 bare `next start` cannot serve it; `nx serve --configuration=production` can.

apps/website/src/components/landing/StageAct.tsx

@@ -127,11 +127,7 @@ export function StageAct({ onFallback }: Props) {
       <div className="stage-pin" data-sc-stage>
         <Container className="stage-pin-inner">
           <div className="stage-frame">
-            <BrowserFrame
-              url="demo.threadplane.ai/stage"
-              elevation="lg"
-              className="stage-frame-chrome"
-            >
+            <BrowserFrame url="demo.threadplane.ai/stage" elevation="lg">
               <div className="stage-frame-stage">
                 <img
                   src={POSTER}
@@ -170,6 +166,7 @@ export function StageAct({ onFallback }: Props) {
             {STAGE_RAIL.map((b) => (
               <div
                 className="stage-rail-beat"
+                data-testid="stage-rail-beat"
                 data-beat={b.beat}
                 data-sc-cue={cueFor(b.beat)}
                 key={b.beat}
@@ -183,9 +180,7 @@ export function StageAct({ onFallback }: Props) {
                     aria-hidden="true"
                   />
                 </div>
-                <h3 className="feature-block-heading stage-rail-heading">
-                  {b.headline}
-                </h3>
+                <h3 className="feature-block-heading">{b.headline}</h3>
                 <p className="feature-block-body">{b.body}</p>
                 <div className="feature-block-rows">
                   {b.rows.map((row) => (
@@ -209,6 +204,7 @@ export function StageAct({ onFallback }: Props) {
             {STAGE_HOLD_LINES.map((line, i) => (
               <p
                 className="stage-rail-hold"
+                data-testid="stage-rail-hold"
                 data-sc-cue={holdCues[i]}
                 key={line}
               >

apps/website/src/components/landing/use-stage-publisher.spec.ts

@@ -5,6 +5,7 @@ import { useRef } from 'react';
 import {
   createStagePublisher,
   STAGE_DEMO_ORIGIN,
+  STAGE_HELLO_INTERVAL_MS,
   STAGE_MESSAGE_TYPE,
   useStagePublisher,
   type StagePublisher,
@@ -85,10 +86,44 @@ describe('stage publisher', () => {
     });
   });
 
-  it('posts nothing before ready', () => {
+  it('posts no seek before ready, only a throttled hello so the frame learns the origin', () => {
+    let now = 1000;
+    vi.spyOn(performance, 'now').mockImplementation(() => now);
     const { section, posted, pub } = setup({ ready: false });
     section.style.setProperty('--sc-p', '0.3');
     pub.tick();
+    now += 100;
+    pub.tick();
+    // Two ticks inside the interval: exactly one hello.
+    expect(posted).toEqual([
+      { origin: STAGE_DEMO_ORIGIN, m: { type: STAGE_MESSAGE_TYPE, t: 0 } },
+    ]);
+    now += STAGE_HELLO_INTERVAL_MS;
+    pub.tick();
+    expect(posted).toHaveLength(2);
+    expect(posted[1]).toEqual({
+      origin: STAGE_DEMO_ORIGIN,
+      m: { type: STAGE_MESSAGE_TYPE, t: 0 },
+    });
+    // Once ready arrives the hello stops and the real seek is posted.
+    fromDemo(READY);
+    now += STAGE_HELLO_INTERVAL_MS * 4;
+    pub.tick();
+    pub.tick();
+    expect(posted).toHaveLength(3);
+    expect(posted[2]).toEqual({
+      origin: STAGE_DEMO_ORIGIN,
+      m: { type: STAGE_MESSAGE_TYPE, t: timeAt(0.3, READY) },
+    });
+  });
+
+  it('says no hello while the frame window is not there yet', () => {
+    const { section, posted, pub } = setup({
+      ready: false,
+      frameWindow: () => null,
+    });
+    section.style.setProperty('--sc-p', '0.3');
+    pub.tick();
     expect(posted).toHaveLength(0);
   });
 
@@ -200,12 +235,15 @@ describe('stage publisher', () => {
 
   it('ignores a malformed ready: no hold, or a beat with a non-numeric time', () => {
     const { section, posted, onReady, pub } = setup({ ready: false });
+    // A malformed ready leaves the publisher un-ready, so the only thing it
+    // may post is the hello (t: 0), never a seek.
+    const seeks = () => posted.filter((p) => (p.m as { t: number }).t !== 0);
     const { hold: _hold, ...noHold } = READY;
     void _hold;
     fromDemo(noHold);
     section.style.setProperty('--sc-p', '0.1');
     expect(() => pub.tick()).not.toThrow();
-    expect(posted).toHaveLength(0);
+    expect(seeks()).toHaveLength(0);
     expect(onReady).not.toHaveBeenCalled();
 
     fromDemo({
@@ -218,13 +256,18 @@ describe('stage publisher', () => {
     section.style.setProperty('--sc-p', '0.11');
     expect(() => pub.tick()).not.toThrow();
     pub.tick();
-    expect(posted).toHaveLength(0);
+    expect(seeks()).toHaveLength(0);
     expect(onReady).not.toHaveBeenCalled();
 
     // A well-formed ready afterwards still works.
     fromDemo(READY);
     pub.tick();
-    expect(posted).toHaveLength(1);
+    expect(seeks()).toEqual([
+      {
+        origin: STAGE_DEMO_ORIGIN,
+        m: { type: STAGE_MESSAGE_TYPE, t: timeAt(0.11, READY) },
+      },
+    ]);
     expect(onReady).toHaveBeenCalledTimes(1);
   });
 

apps/website/src/components/landing/use-stage-publisher.ts

@@ -5,14 +5,18 @@ import {
   inHold,
   timeAt,
   type StageBeat,
+  type StageMilestone,
   type StageReadyMessage,
 } from '../../lib/stage-beats';
 
+export type { StageMilestone } from '../../lib/stage-beats';
+
 export const STAGE_DEMO_ORIGIN = 'https://demo.threadplane.ai';
 export const STAGE_DEMO_URL = `${STAGE_DEMO_ORIGIN}/stage?t=0`;
 export const STAGE_MESSAGE_TYPE = 'tplane-stage';
 
-export type StageMilestone = 'enter' | 'beat' | 'threshold' | 'complete';
+/** How often the publisher says hello to a frame that has not answered yet. */
+export const STAGE_HELLO_INTERVAL_MS = 500;
 
 export interface StagePublisherDeps {
   section: HTMLElement;
@@ -78,6 +82,7 @@ export function createStagePublisher(deps: StagePublisherDeps): StagePublisher {
   let thresholdSeen = false;
   const beatsSeen = new Set<StageBeat>();
   let disposed = false;
+  let lastHello = -Infinity;
 
   const onMessage = (e: MessageEvent) => {
     if (e.origin !== STAGE_DEMO_ORIGIN) return;
@@ -130,8 +135,21 @@ export function createStagePublisher(deps: StagePublisherDeps): StagePublisher {
         deps.track('complete');
       }
       lastP = p;
+      // Hello. Under a strict Referrer-Policy the frame arrives with no
+      // referrer and posts nothing (it has nowhere to answer) until it hears
+      // from an allowlisted parent; the frame learns the origin from this
+      // message and answers with `ready`. Throttled so a scroll that idles
+      // before the frame boots does not flood it.
+      if (!ready) {
+        const now = performance.now();
+        if (now - lastHello < STAGE_HELLO_INTERVAL_MS) return;
+        const w = deps.frameWindow();
+        if (!w) return;
+        w.postMessage({ type: STAGE_MESSAGE_TYPE, t: 0 }, STAGE_DEMO_ORIGIN);
+        lastHello = now;
+        return;
+      }
       // Seek.
-      if (!ready) return;
       const t = timeAt(p, ready);
       if (t === lastT) return;
       const w = deps.frameWindow();

apps/website/src/lib/analytics/events.ts

@@ -1,3 +1,5 @@
+import type { StageBeat, StageMilestone } from '../stage-beats';
+
 export const analyticsEvents = {
   marketingCtaClick: 'marketing:cta_click',
   marketingExternalLinkClick: 'marketing:external_link_click',
@@ -142,7 +144,7 @@ export type AnalyticsProperties = {
   ai_source?: string;
   user_agent?: string;
   /** Homepage stage milestones (`marketing:stage_progress`). */
-  stage_event?: 'enter' | 'beat' | 'threshold' | 'complete';
-  beat?: 'stream' | 'persist' | 'approve' | 'render';
+  stage_event?: StageMilestone;
+  beat?: StageBeat;
   [key: string]: string | number | boolean | undefined;
 };

apps/website/src/lib/stage-beats.ts

@@ -8,6 +8,9 @@
 export const STAGE_BEATS = ['stream', 'persist', 'approve', 'render'] as const;
 export type StageBeat = (typeof STAGE_BEATS)[number];
 
+/** The scroll milestones the publisher reports (`marketing:stage_progress`). */
+export type StageMilestone = 'enter' | 'beat' | 'threshold' | 'complete';
+
 /** Viewport-heights of scroll each beat owns. Approve is the peak by a visible margin. */
 export const STAGE_SHARES: Readonly<Record<StageBeat, number>> = {
   stream: 1.3,

examples/chat/angular/src/app/stage/stage-bridge.spec.ts

@@ -72,6 +72,33 @@ describe('createStageBridge', () => {
     });
   });
 
+  it('re-posts ready once an empty-referrer frame learns the parent origin from a seek', () => {
+    const e = env('');
+    const bridge = createStageBridge({ referrer: e.referrer, parent: e.parent, self: e.self });
+    const seen: number[] = [];
+    bridge.onSeek((t) => seen.push(t));
+    const ready = {
+      totalMs: 9000,
+      beats: [{ beat: 'stream' as const, startMs: 0, endMs: 1000 }],
+      hold: { startMs: 5000, endMs: 8000 },
+      reloadEndMs: 1600,
+    };
+    bridge.postReady(ready);
+    // Nothing yet: the frame has nowhere to answer.
+    expect(e.parent.postMessage).not.toHaveBeenCalled();
+    e.fire({ type: STAGE_MESSAGE_TYPE, t: 5 }, 'https://evil.example');
+    expect(e.parent.postMessage).not.toHaveBeenCalled();
+    e.fire({ type: STAGE_MESSAGE_TYPE, t: 0 });
+    expect(seen).toEqual([0]);
+    const calls = (e.parent.postMessage as ReturnType<typeof vi.fn>).mock.calls;
+    expect(calls).toHaveLength(1);
+    expect(calls[0][0]).toEqual({ type: STAGE_MESSAGE_TYPE, ready: true, ...ready });
+    expect(calls[0][1]).toBe('https://threadplane.ai');
+    // A second seek does not repeat the handshake.
+    e.fire({ type: STAGE_MESSAGE_TYPE, t: 100 });
+    expect(calls).toHaveLength(1);
+  });
+
   it('posts nothing when not embedded', () => {
     const e = env();
     const bridge = createStageBridge({ referrer: '', parent: e.self, self: e.self });

examples/chat/angular/src/app/stage/stage-bridge.ts

@@ -48,6 +48,10 @@ export function createStageBridge(env: BridgeEnv): StageBridge {
   let parentOrigin: string | null =
     fromReferrer !== null && isAllowedParentOrigin(fromReferrer) ? fromReferrer : null;
   const embedded = env.parent !== env.self;
+  // The last `ready` posted (or held back while the parent origin was still
+  // unknown): re-posted the moment the origin is learned, so a parent that
+  // arrived with an empty referrer still receives the handshake.
+  let lastReady: Record<string, unknown> | null = null;
   const post = (msg: Record<string, unknown>) => {
     if (!embedded || parentOrigin === null) return;
     env.parent.postMessage({ type: STAGE_MESSAGE_TYPE, ...msg }, parentOrigin);
@@ -61,20 +65,24 @@ export function createStageBridge(env: BridgeEnv): StageBridge {
         if (!d || d.type !== STAGE_MESSAGE_TYPE || typeof d.t !== 'number' || !Number.isFinite(d.t)) return;
         // Under a strict Referrer-Policy the referrer is empty, so the first
         // allowlisted message is how the frame learns where to answer.
-        if (parentOrigin === null) parentOrigin = e.origin;
+        if (parentOrigin === null) {
+          parentOrigin = e.origin;
+          if (lastReady !== null) post(lastReady);
+        }
         cb(d.t);
       };
       env.self.addEventListener('message', handler);
       return () => env.self.removeEventListener('message', handler);
     },
     postReady(ready) {
-      post({
+      lastReady = {
         ready: true,
         totalMs: ready.totalMs,
         beats: ready.beats,
         hold: ready.hold,
         reloadEndMs: ready.reloadEndMs,
-      });
+      };
+      post(lastReady);
     },
     postState(state) {
       post({ applied: state.applied, phase: state.phase, t: state.t });