@xdelivered/emberflow 0.2.0 → 0.4.0

package/server/subflowRunner.ts

@@ -1,16 +1,57 @@
 import type {
+  FlowRun,
   LogLine,
   NodeRegistry,
+  NodeRunState,
   StartRunOptions,
   SubflowResult,
   TraceSink,
   WorkflowDefinition,
+  WorkflowRun,
 } from '../src/engine';
 import { runOutput, startRun } from '../src/engine';
 
 /** Max depth of nested Subflow calls (ancestry chain length) before a run fails. */
 export const SUBFLOW_DEPTH_CAP = 8;
 
+/**
+ * One live drilled-into child on a stepped run. Pushed by the subflow runner
+ * when a Subflow node starts its child; popped by the registry's composite
+ * step() when the child's own stepping completes. `resolve`/`reject` settle
+ * the promise the parent's Subflow node execution is blocked on.
+ */
+export interface DrillEntry {
+  handle: FlowRun;
+  /** The child flow's id (what the caller drilled into). */
+  workflowId: string;
+  /** The parent Subflow node that triggered the child. */
+  viaNodeId: string;
+  /** Hands the completed child run back to the blocked parent Subflow node. */
+  resolve: (run: WorkflowRun) => void;
+  reject: (err: unknown) => void;
+  /**
+   * This level's own executor.step() promise, left pending while a DEEPER
+   * child runs (a Subflow node's execution blocks on its child). Stashed by
+   * the registry when it observes `entered`; folded back in on exit.
+   */
+  pendingStep?: Promise<boolean>;
+}
+
+/**
+ * Per-root-run drill state for stepped runs. The root's subflow runner and
+ * every nested child's runner share the SAME instance, so grandchildren push
+ * onto the same stack and nesting Just Works.
+ */
+export interface DrillState {
+  stack: DrillEntry[];
+  /** Armed by the registry's step() while it awaits a level's step, so a
+   *  child starting can be raced against the (now blocked) step promise. */
+  onChildStarted?: (entry: DrillEntry) => void;
+  /** Set by RunRegistry.cancel(): unwinding parent executions must not start
+   *  (or block on) new children — runSubflow fails fast instead. */
+  cancelled?: boolean;
+}
+
 export interface SubflowRunnerOptions {
   /** Resolves a child workflow by id (server hosts this via apiStore.load). */
   loadFlow: (id: string) => WorkflowDefinition | undefined;
@@ -29,6 +70,17 @@ export interface SubflowRunnerOptions {
    *  prefixed with the child flow's name and the caller node's id, exactly as
    *  the live runner streams them over SSE. Absent for headless runs. */
   onLog?: (line: LogLine) => void;
+  /**
+   * Present only for stepped runs: children become step-drivable instead of
+   * running to completion. The runner pushes each started child onto
+   * `drill.stack` and blocks the Subflow node until the registry pops it.
+   */
+  drill?: DrillState;
+  /** Child nodeState forwarder for stepped runs — receives the CHILD flow's
+   *  id so the client can route states to the drilled-in view. Only wired
+   *  when `drill` is present (non-stepped children keep today's behavior:
+   *  their node states are discarded, only the output returns). */
+  onNodeState?: (workflowId: string, nodeId: string, state: NodeRunState) => void;
 }
 
 /**
@@ -45,6 +97,11 @@ export function makeSubflowRunner(
   ancestry: string[],
 ): NonNullable<StartRunOptions['subflowRunner']> {
   return async (workflowId, input, callerNodeId): Promise<SubflowResult> => {
+    // A cancelled stepped run's unwinding parents (their runSubflow was
+    // rejected) may retry: never push a new child that nothing will step.
+    if (opts.drill?.cancelled) {
+      return { status: 'failed', error: 'run cancelled' };
+    }
     if (ancestry.length >= SUBFLOW_DEPTH_CAP) {
       return { status: 'failed', error: `subflow depth cap (${SUBFLOW_DEPTH_CAP}) exceeded` };
     }
@@ -72,18 +129,42 @@ export function makeSubflowRunner(
         mocks: (childFlow as { mocks?: Record<string, unknown> }).mocks ?? {},
         trace: opts.trace,
         subflowRunner: makeSubflowRunner(opts, [...ancestry, workflowId]),
-        events: opts.onLog
-          ? {
-              onLog: (line) =>
-                opts.onLog!({
-                  ...line,
-                  nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
-                  nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
-                }),
-            }
-          : undefined,
+        events:
+          opts.onLog || (opts.drill && opts.onNodeState)
+            ? {
+                ...(opts.onLog
+                  ? {
+                      onLog: (line: LogLine) =>
+                        opts.onLog!({
+                          ...line,
+                          nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
+                          nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
+                        }),
+                    }
+                  : {}),
+                // Stepped children stream their node states into the ROOT
+                // run's SSE stream, tagged with the child flow's id.
+                ...(opts.drill && opts.onNodeState
+                  ? {
+                      onNodeStateChange: (nodeId: string, state: NodeRunState) =>
+                        opts.onNodeState!(childFlow.id, nodeId, state),
+                    }
+                  : {}),
+              }
+            : undefined,
       });
-      const childRun = await childHandle.runToEnd();
+      // Stepped run: don't run the child here. Push it onto the shared drill
+      // stack and block this Subflow node until the registry's composite
+      // step() drives the child to completion and pops the entry — resolving
+      // with the completed child run, which flows into the exact same
+      // output-extraction / failure-mapping path runToEnd feeds today.
+      const childRun = opts.drill
+        ? await new Promise<WorkflowRun>((resolve, reject) => {
+            const entry: DrillEntry = { handle: childHandle, workflowId, viaNodeId: callerNodeId, resolve, reject };
+            opts.drill!.stack.push(entry);
+            opts.drill!.onChildStarted?.(entry);
+          })
+        : await childHandle.runToEnd();
       if (childRun.status !== 'succeeded') {
         // Surface the child's actual failure (e.g. the Mock-mode "would touch
         // real infrastructure" boundary message) through the Subflow node's

package/server/updateCheck.test.ts

@@ -0,0 +1,209 @@
+import { EventEmitter } from 'node:events';
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  checkForUpdate,
+  isLinkedInstall,
+  ownVersion,
+  resetUpdateCheckCache,
+  runNpmInstall,
+  type InstallResult,
+} from './updateCheck';
+
+/** A fetch stub returning a registry-shaped `{ version }` body. */
+function fetchReturning(version: string, ok = true): typeof fetch {
+  return vi.fn(async () => ({ ok, json: async () => ({ version }) })) as unknown as typeof fetch;
+}
+
+describe('checkForUpdate', () => {
+  beforeEach(() => resetUpdateCheckCache());
+  afterEach(() => {
+    delete process.env.EMBERFLOW_UPDATE_CHECK;
+    delete process.env.EMBERFLOW_REGISTRY;
+  });
+
+  it('reports updateAvailable when the registry version is newer', async () => {
+    const result = await checkForUpdate('0.3.0', { fetchFn: fetchReturning('0.4.0') });
+    expect(result).toEqual({ current: '0.3.0', latest: '0.4.0', updateAvailable: true });
+  });
+
+  it('reports no update when versions are equal', async () => {
+    const result = await checkForUpdate('0.3.0', { fetchFn: fetchReturning('0.3.0') });
+    expect(result).toEqual({ current: '0.3.0', latest: '0.3.0', updateAvailable: false });
+  });
+
+  it('reports no update when the registry version is OLDER (local ahead of npm)', async () => {
+    const result = await checkForUpdate('0.10.0', { fetchFn: fetchReturning('0.9.9') });
+    expect(result?.updateAvailable).toBe(false);
+  });
+
+  it('compares numerically, not lexically (0.10.0 beats 0.9.0)', async () => {
+    const result = await checkForUpdate('0.9.0', { fetchFn: fetchReturning('0.10.0') });
+    expect(result?.updateAvailable).toBe(true);
+  });
+
+  it('returns null on fetch rejection (fail-silent)', async () => {
+    const fetchFn = vi.fn(async () => {
+      throw new Error('ENETDOWN');
+    }) as unknown as typeof fetch;
+    await expect(checkForUpdate('0.3.0', { fetchFn })).resolves.toBeNull();
+  });
+
+  it('returns null on a non-ok response (404 pre-publish)', async () => {
+    await expect(checkForUpdate('0.3.0', { fetchFn: fetchReturning('irrelevant', false) })).resolves.toBeNull();
+  });
+
+  it('returns null on malformed json / missing version', async () => {
+    const fetchFn = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({ nope: true }),
+    })) as unknown as typeof fetch;
+    await expect(checkForUpdate('0.3.0', { fetchFn })).resolves.toBeNull();
+    resetUpdateCheckCache();
+    const throwsOnJson = vi.fn(async () => ({
+      ok: true,
+      json: async () => {
+        throw new Error('bad json');
+      },
+    })) as unknown as typeof fetch;
+    await expect(checkForUpdate('0.3.0', { fetchFn: throwsOnJson })).resolves.toBeNull();
+  });
+
+  it('caches within the TTL and refetches after it expires', async () => {
+    let clock = 1_000;
+    const fetchFn = fetchReturning('0.4.0');
+    const opts = { fetchFn, ttlMs: 60_000, now: () => clock };
+
+    expect(await checkForUpdate('0.3.0', opts)).toMatchObject({ latest: '0.4.0' });
+    clock += 30_000; // inside TTL — served from cache
+    expect(await checkForUpdate('0.3.0', opts)).toMatchObject({ latest: '0.4.0' });
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+
+    clock += 60_001; // past TTL — hits the registry again
+    await checkForUpdate('0.3.0', opts);
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('caches failures too (no registry hammering while offline)', async () => {
+    const fetchFn = vi.fn(async () => {
+      throw new Error('offline');
+    }) as unknown as typeof fetch;
+    await checkForUpdate('0.3.0', { fetchFn });
+    await checkForUpdate('0.3.0', { fetchFn });
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('is disabled entirely by EMBERFLOW_UPDATE_CHECK=0', async () => {
+    process.env.EMBERFLOW_UPDATE_CHECK = '0';
+    const fetchFn = fetchReturning('9.9.9');
+    await expect(checkForUpdate('0.3.0', { fetchFn })).resolves.toBeNull();
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+
+  it('honors the EMBERFLOW_REGISTRY override', async () => {
+    process.env.EMBERFLOW_REGISTRY = 'http://127.0.0.1:9999';
+    const fetchFn = fetchReturning('0.4.0');
+    await checkForUpdate('0.3.0', { fetchFn });
+    expect(fetchFn).toHaveBeenCalledWith('http://127.0.0.1:9999/@xdelivered/emberflow/latest');
+  });
+});
+
+describe('ownVersion', () => {
+  it('resolves this package version from package.json (source layout)', () => {
+    // Running from the source repo: server/updateCheck.ts → root is one up.
+    expect(ownVersion()).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});
+
+/** Minimal spawn-shaped fake: emits like a ChildProcess, never runs npm. */
+function fakeChild() {
+  const child = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter;
+    stderr: EventEmitter;
+    kill: ReturnType<typeof vi.fn>;
+  };
+  child.stdout = new EventEmitter();
+  child.stderr = new EventEmitter();
+  child.kill = vi.fn();
+  return child;
+}
+
+describe('runNpmInstall', () => {
+  it('spawns npm install <pkg>@latest in the project root, no shell', async () => {
+    const child = fakeChild();
+    const spawnFn = vi.fn(() => child);
+    const done = runNpmInstall('/proj', { spawnFn: spawnFn as never });
+    expect(spawnFn).toHaveBeenCalledWith('npm', ['install', '@xdelivered/emberflow@latest'], {
+      cwd: '/proj',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    child.emit('close', 0);
+    await expect(done).resolves.toEqual({ ok: true });
+  });
+
+  it('fails with the output tail on a nonzero exit', async () => {
+    const child = fakeChild();
+    const done = runNpmInstall('/proj', { spawnFn: (() => child) as never });
+    child.stderr.emit('data', 'npm ERR! code E403\n');
+    child.stderr.emit('data', 'npm ERR! forbidden\n');
+    child.emit('close', 1);
+    const result = (await done) as InstallResult & { ok: false };
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('E403');
+    expect(result.error).toContain('forbidden');
+  });
+
+  it('keeps only the last ~4KB of output in the error tail', async () => {
+    const child = fakeChild();
+    const done = runNpmInstall('/proj', { spawnFn: (() => child) as never });
+    child.stdout.emit('data', 'EARLY-MARKER ' + 'x'.repeat(8000));
+    child.stderr.emit('data', ' LATE-MARKER');
+    child.emit('close', 1);
+    const result = (await done) as InstallResult & { ok: false };
+    expect(result.error).toContain('LATE-MARKER');
+    expect(result.error).not.toContain('EARLY-MARKER');
+    expect(result.error.length).toBeLessThanOrEqual(4096);
+  });
+
+  it('fails on a spawn error event (npm missing) without rejecting', async () => {
+    const child = fakeChild();
+    const done = runNpmInstall('/proj', { spawnFn: (() => child) as never });
+    child.emit('error', new Error('spawn npm ENOENT'));
+    await expect(done).resolves.toEqual({ ok: false, error: 'spawn npm ENOENT' });
+  });
+
+  it('kills and fails after the timeout', async () => {
+    const child = fakeChild();
+    const done = runNpmInstall('/proj', { spawnFn: (() => child) as never, timeoutMs: 10 });
+    const result = await done; // child never closes — the timer settles it
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain('timed out');
+    expect(child.kill).toHaveBeenCalledWith('SIGKILL');
+  });
+});
+
+describe('isLinkedInstall', () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'ef-update-'));
+  });
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  it('is false when the package is not installed at all', () => {
+    expect(isLinkedInstall(root)).toBe(false);
+  });
+
+  it('is false for a real directory install', () => {
+    mkdirSync(join(root, 'node_modules', '@xdelivered', 'emberflow'), { recursive: true });
+    expect(isLinkedInstall(root)).toBe(false);
+  });
+
+  it('is true for a symlinked (file:/npm link) install', () => {
+    mkdirSync(join(root, 'node_modules', '@xdelivered'), { recursive: true });
+    mkdirSync(join(root, 'real-checkout'));
+    symlinkSync(join(root, 'real-checkout'), join(root, 'node_modules', '@xdelivered', 'emberflow'));
+    expect(isLinkedInstall(root)).toBe(true);
+  });
+});

package/server/updateCheck.ts

@@ -0,0 +1,175 @@
+import { spawn } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { newer } from './agents/detect';
+
+/**
+ * Update notifier + installer plumbing for consumer projects (they install
+ * @xdelivered/emberflow from npm and run `npx emberflow dev`).
+ *
+ * - checkForUpdate: asks the npm registry for the latest published version and
+ *   compares it against the running one. Fail-SILENT by design: any network,
+ *   HTTP, or parse failure returns null — an update nudge must never break or
+ *   slow the studio. Results (including failures) are cached in-memory for an
+ *   hour so /update-status stays cheap and the registry isn't hammered.
+ * - runNpmInstall: the actual one-click updater — `npm install <pkg>@latest`
+ *   spawned (no shell) in the project root. Injectable spawn for tests.
+ */
+
+export const EMBERFLOW_PACKAGE = '@xdelivered/emberflow';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1h
+const INSTALL_TIMEOUT_MS = 5 * 60 * 1000; // 5min
+const OUTPUT_TAIL_BYTES = 4096;
+
+export interface UpdateCheckResult {
+  current: string;
+  latest: string;
+  updateAvailable: boolean;
+}
+
+export interface CheckForUpdateOpts {
+  /** Registry base URL. Defaults to EMBERFLOW_REGISTRY env, then npmjs. */
+  registry?: string;
+  /** Cache TTL in ms (default 1h). */
+  ttlMs?: number;
+  /** Injectable clock for TTL tests. */
+  now?: () => number;
+  /** Injectable fetch for tests. */
+  fetchFn?: typeof fetch;
+}
+
+// Single-entry cache: the runner only ever checks one package/version pair.
+// Failures are cached too — a flaky network shouldn't retrigger a fetch on
+// every /update-status poll.
+let cache: { at: number; result: UpdateCheckResult | null } | null = null;
+
+/** Test hook: clear the in-memory check cache. */
+export function resetUpdateCheckCache(): void {
+  cache = null;
+}
+
+/**
+ * Latest-version check against the npm registry. Returns null when the check
+ * is disabled (EMBERFLOW_UPDATE_CHECK=0) or unavailable for ANY reason —
+ * never throws.
+ */
+export async function checkForUpdate(
+  currentVersion: string,
+  opts: CheckForUpdateOpts = {},
+): Promise<UpdateCheckResult | null> {
+  if (process.env.EMBERFLOW_UPDATE_CHECK === '0') return null;
+  const now = opts.now ?? Date.now;
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  if (cache && now() - cache.at < ttlMs) return cache.result;
+
+  const registry = opts.registry ?? process.env.EMBERFLOW_REGISTRY ?? DEFAULT_REGISTRY;
+  const fetchFn = opts.fetchFn ?? fetch;
+  let result: UpdateCheckResult | null = null;
+  try {
+    const res = await fetchFn(`${registry}/${EMBERFLOW_PACKAGE}/latest`);
+    if (res.ok) {
+      const body = (await res.json()) as { version?: unknown };
+      if (typeof body.version === 'string' && body.version.length > 0) {
+        result = {
+          current: currentVersion,
+          latest: body.version,
+          updateAvailable: newer(body.version, currentVersion),
+        };
+      }
+    }
+  } catch {
+    result = null; // fail-silent: network error, bad JSON, anything
+  }
+  cache = { at: now(), result };
+  return result;
+}
+
+/**
+ * The running package's own version, read from its package.json. Two layouts,
+ * same probe as prompt.ts's EMBERFLOW_BIN: in the source repo this file is
+ * server/updateCheck.ts and the package root is one level up; in the shipped
+ * package it runs from dist/server/updateCheck.js and the root is two up.
+ */
+export function ownVersion(): string | null {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const root of [resolve(here, '..'), resolve(here, '../..')]) {
+    const file = join(root, 'package.json');
+    if (!existsSync(file)) continue;
+    try {
+      const pkg = JSON.parse(readFileSync(file, 'utf8')) as { version?: unknown };
+      if (typeof pkg.version === 'string') return pkg.version;
+    } catch {
+      // malformed — try the next candidate
+    }
+  }
+  return null;
+}
+
+/**
+ * True when the consumer's node_modules/@xdelivered/emberflow is a symlink —
+ * a `file:`/`npm link` dev setup that an npm install would clobber. POST
+ * /update refuses in that case.
+ */
+export function isLinkedInstall(projectRoot: string): boolean {
+  try {
+    return lstatSync(join(projectRoot, 'node_modules', '@xdelivered', 'emberflow')).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export type InstallResult = { ok: true } | { ok: false; error: string };
+
+export interface RunNpmInstallOpts {
+  /** Injectable spawner so tests never actually npm install. */
+  spawnFn?: typeof spawn;
+  /** Kill-and-fail deadline (default 5min). */
+  timeoutMs?: number;
+}
+
+/**
+ * Runs `npm install @xdelivered/emberflow@latest` in the project root via
+ * spawn (no shell). Captures the last ~4KB of combined output; on failure
+ * that tail is the error. Never rejects.
+ */
+export function runNpmInstall(projectRoot: string, opts: RunNpmInstallOpts = {}): Promise<InstallResult> {
+  const spawnFn = opts.spawnFn ?? spawn;
+  const timeoutMs = opts.timeoutMs ?? INSTALL_TIMEOUT_MS;
+  return new Promise((resolveInstall) => {
+    let tail = '';
+    const append = (chunk: unknown): void => {
+      tail = (tail + String(chunk)).slice(-OUTPUT_TAIL_BYTES);
+    };
+
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawnFn('npm', ['install', `${EMBERFLOW_PACKAGE}@latest`], {
+        cwd: projectRoot,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolveInstall({ ok: false, error: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+    child.stdout?.on('data', append);
+    child.stderr?.on('data', append);
+
+    let settled = false;
+    const settle = (result: InstallResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveInstall(result);
+    };
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      settle({ ok: false, error: `npm install timed out after ${Math.round(timeoutMs / 1000)}s\n${tail}`.trim() });
+    }, timeoutMs);
+    child.on('error', (err) => settle({ ok: false, error: err.message }));
+    child.on('close', (code) =>
+      settle(code === 0 ? { ok: true } : { ok: false, error: tail.trim() || `npm install exited with code ${code}` }),
+    );
+  });
+}

package/server/workflowTestRoute.test.ts

@@ -12,7 +12,7 @@ import { join } from 'node:path';
 // the harness in environmentsRoute.test.ts / runsAuth.test.ts.
 
 let proc: ChildProcess;
-const PORT = 8137;
+const PORT = 8156;
 const base = `http://127.0.0.1:${PORT}`;
 let projectDir: string;
 

package/src/App.tsx

@@ -1,9 +1,11 @@
-import { useEffect } from 'react';
-import { PanelBottomOpenIcon, PanelLeftOpenIcon, PanelRightOpenIcon, XIcon } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { FlameIcon, PanelBottomOpenIcon, PanelLeftOpenIcon, PanelRightOpenIcon, XIcon } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@/components/ui/resizable';
 import { AgentConsole } from './components/AgentConsole';
+import { CreateModalHost } from './components/CreateModal';
 import { Dock } from './components/Dock';
+import { EMPTY_STATE_DISMISSED_KEY, EmptyState } from './components/EmptyState';
 import { Inspector } from './components/Inspector';
 import { RunConsole, useRunConsole } from './components/RunLogPanel';
 import { RunbookView } from './components/RunbookView';
@@ -68,9 +70,84 @@ function EdgeReopen({
   );
 }
 
+/**
+ * Calm, honest offline state. The workspace (operations, environments, runs) all
+ * come from the runner — with it down and no workspace ever adopted, there is
+ * nothing to show and nothing to execute, so we say so plainly instead of
+ * pretending an empty canvas is a project.
+ */
+function RunnerOfflinePanel() {
+  const checkRunner = useBuilderStore((s) => s.checkRunner);
+  return (
+    <div className="flex h-full min-h-0 items-center justify-center p-8">
+      <div className="flex max-w-md flex-col items-center gap-3 text-center">
+        <FlameIcon className="size-8 text-muted-foreground/50" />
+        <h2 className="text-[15px] font-semibold tracking-tight">Runner offline</h2>
+        <p className="text-[13px] leading-relaxed text-muted-foreground">
+          The studio is a pure client — your operations, environments and runs all
+          live on the runner. Start it, then this workspace fills in.
+        </p>
+        <code className="rounded-md border border-border bg-tertiary px-2.5 py-1.5 font-mono text-[12.5px] text-foreground">
+          npx emberflow dev
+        </code>
+        <button
+          type="button"
+          onClick={() => void checkRunner()}
+          className="mt-1 rounded-md px-2.5 py-1 text-[12px] text-muted-foreground transition-colors hover:bg-secondary/60 hover:text-foreground"
+        >
+          Re-check
+        </button>
+      </div>
+    </div>
+  );
+}
+
 /** The center panel's content: the runbook document is the sole flow surface. */
 function CenterView() {
   const viewRegister = useBuilderStore((s) => s.viewRegister);
+  const runnerOnline = useBuilderStore((s) => s.runnerOnline);
+  const workspaceSource = useBuilderStore((s) => s.workspaceSource);
+  const setupStatus = useBuilderStore((s) => s.setupStatus);
+  const welcomeOpen = useBuilderStore((s) => s.welcomeOpen);
+  const setCreateModal = useBuilderStore((s) => s.setCreateModal);
+  const switchWorkflow = useBuilderStore((s) => s.switchWorkflow);
+  // Explicit dismissal of the post-onboarding empty state ("explore the
+  // example" path). Building a second op dismisses it implicitly — onlyHello
+  // stops matching once setupStatus refreshes (WelcomeDialog/StatusBar refetch
+  // it on agent-run finish), so no flag is written on that path.
+  const [emptyDismissed, setEmptyDismissed] = useState(
+    () => typeof localStorage !== 'undefined' && localStorage.getItem(EMPTY_STATE_DISMISSED_KEY) === '1',
+  );
+  // Offline AND no runner workspace ever adopted → the calm offline panel. Once
+  // a workspace has been adopted (workspaceSource === 'server'), a mid-session
+  // runner blip keeps showing the flow; the StatusBar carries the offline signal.
+  if (runnerOnline === false && workspaceSource !== 'server') {
+    return (
+      <div className="relative h-full min-h-0">
+        <RunnerOfflinePanel />
+      </div>
+    );
+  }
+  // Post-onboarding: the bare hello-example project gets a clear starting point
+  // instead of someone else's op — hidden while the Welcome dialog still runs.
+  if (!welcomeOpen && !emptyDismissed && setupStatus?.ops.onlyHello) {
+    return (
+      <div className="relative h-full min-h-0">
+        <EmptyState
+          status={setupStatus}
+          dismissed={emptyDismissed}
+          onCreate={() => setCreateModal({ mode: 'api' })}
+          onExplore={() => {
+            if (typeof localStorage !== 'undefined') {
+              localStorage.setItem(EMPTY_STATE_DISMISSED_KEY, '1');
+            }
+            setEmptyDismissed(true);
+            switchWorkflow('default/hello');
+          }}
+        />
+      </div>
+    );
+  }
   return (
     <div className="relative h-full min-h-0">
       <RunbookView register={viewRegister} />
@@ -228,6 +305,9 @@ export default function App() {
       )}
       </div>
       <StatusBar />
+      {/* The one New API / New operation modal — hosted here (not in the
+          Sidebar) so the canvas empty state can open it with the sidebar closed. */}
+      <CreateModalHost />
     </div>
   );
 }