[codex] Add surface gallery example

.github/workflows/ci.yml

@@ -43,6 +43,7 @@ jobs:
       - run: pnpm test
       - run: pnpm build
       - run: pnpm check:public-packages
+      - run: pnpm check:public-api
       - run: pnpm pack:dry-run
 
   safety:
@@ -74,4 +75,5 @@ jobs:
             exit "$status"
           fi
       - run: pnpm exec playwright install --with-deps chromium webkit
+      - run: pnpm test:gallery
       - run: pnpm test:safety

README.md

@@ -29,6 +29,18 @@ The public package boundary is:
 pnpm install
 cp apps/server/.env.example apps/server/.env
 # edit apps/server/.env and set ANTHROPIC_API_KEY
+pnpm dev:gallery
+```
+
+Open `http://localhost:5174`.
+
+The Surface Gallery is the first OSS demo: curated live presets that show
+static, host-resource, host-action, approval-gated, component-island, and
+worker-backed Summon surfaces without exposing workbench controls.
+
+For the maintainer workbench:
+
+```sh
 pnpm dev:all
 ```
 
@@ -71,6 +83,8 @@ explicit accepted `SurfacePlan`.
 
 ## Demo Map
 
+- `examples/surface-gallery` - first-run OSS gallery with curated live presets,
+  compact host contracts, a sandboxed surface, and a small event strip.
 - `/generate.html` - contract cockpit with scenario grants, surface plans,
   static/declarative/scripted/worker tiers, component islands, host resources,
   token overrides, repair diagnostics, edit/replay, Ghost steering, Devtools,
@@ -99,10 +113,11 @@ explicit accepted `SurfacePlan`.
 - `packages/engine`, `packages/host`, `packages/devtools`,
   `packages/sandbox-runtime`, `packages/server`, `packages/react` - private
   implementation workspaces published only through the public facades.
+- `examples/surface-gallery` - first-run live example app for OSS adopters.
 - `apps/server` - Anthropic-backed demo server, direction loading, repair
   feedback, and demo backing routes.
-- `apps/demo` - Vite host app for generation, batch runs, adversarial checks,
-  strict input, and fatal sandbox testing.
+- `apps/demo` - Vite workbench for generation, batch runs, adversarial checks,
+  strict input, Ghost steering, repair diagnostics, and fatal sandbox testing.
 
 ## Adoption Docs
 
@@ -139,10 +154,12 @@ pnpm test:safety
 pnpm typecheck
 pnpm test
 pnpm test:safety
+pnpm test:gallery
 pnpm build
 pnpm check:public-api
 pnpm smoke:public-packages
 pnpm pack:dry-run
+pnpm dev:gallery
 pnpm dev:all
 pnpm port-direction <path-to-expression.md> [id]
 pnpm eval-directions [--prompts N] [--directions id,id] [--seed N] [--dry]

docs/adoption/quickstart.md

@@ -1,30 +1,47 @@
 # Summon Adoption Quickstart
 
-This is the golden path for proving Summon works locally: generation, interactive
-data resources, host state pushback, Devtools events, stream health, and sandbox
-boundaries.
+This is the golden path for proving Summon works locally. Start with the Surface
+Gallery to see rich host-owned surfaces without workbench controls, then use the
+Workbench to inspect generation, interactive data resources, host state
+pushback, Devtools events, stream health, and sandbox boundaries.
 
 ## Prerequisites
 
 - Node 18 or newer.
 - pnpm 10 or newer.
 - An Anthropic API key for `apps/server`.
 
-## Run The Demo
+## Run The Gallery
 
 ```sh
 pnpm install
 cp apps/server/.env.example apps/server/.env
 # edit apps/server/.env and set ANTHROPIC_API_KEY
+pnpm dev:gallery
+```
+
+Open `http://localhost:5174`.
+
+The gallery is live-first. It requires `apps/server` and `ANTHROPIC_API_KEY`;
+it does not silently fall back to replay. Use the preset cards to generate
+static, host-resource, host-action, approval-gated, component-island, and
+worker-backed surfaces.
+
+Each preset sends an explicit `SurfacePlan`, narrowed capability/component
+contracts, and matching script policy to `/api/generate`.
+
+## Run The Workbench
+
+```sh
 pnpm dev:all
 ```
 
 Open `http://localhost:5173/generate.html`.
 
 ## Golden Scenario
 
-Use the **Host-resource search** scenario. The scenario is intentionally shaped
-to exercise the adoption path:
+In the workbench, use the **Host-resource search** scenario. The scenario is
+intentionally shaped to exercise the adoption path:
 
 - `defineDataResource` via the demo `search` resource.
 - Loading, error, and data states through resource bindings.

examples/surface-gallery/index.html

@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Summon Surface Gallery</title>
+</head>
+<body>
+  <main id="app" class="gallery-shell">
+    <aside class="preset-rail" aria-label="Surface presets">
+      <a class="wordmark" href="/">summon</a>
+      <div class="rail-intro">
+        <p class="eyebrow">Surface Gallery</p>
+        <h1>Sandboxed mini-apps with host-owned authority.</h1>
+      </div>
+      <div id="preset-list" class="preset-list"></div>
+    </aside>
+
+    <section class="surface-stage" aria-label="Generated surface">
+      <header class="stage-header">
+        <div>
+          <p class="eyebrow" id="preset-category">Gallery</p>
+          <h2 id="preset-title">Static Brief</h2>
+          <p id="preset-description">Choose a preset to see a focused Summon surface.</p>
+        </div>
+        <button id="run" type="button">Generate</button>
+      </header>
+
+      <label class="prompt-label" for="prompt">Prompt</label>
+      <textarea id="prompt" class="prompt-box" spellcheck="false"></textarea>
+
+      <div class="sandbox-frame">
+        <iframe id="sandbox" title="Summon surface gallery sandbox"></iframe>
+        <div id="welcome" class="welcome">
+          <strong>Choose a preset, then generate.</strong>
+          <span>Live generation streams into a null-origin iframe.</span>
+        </div>
+      </div>
+
+      <details id="event-strip" class="event-strip">
+        <summary>Events <span id="event-count">0</span></summary>
+        <div id="event-log" class="event-log"></div>
+      </details>
+    </section>
+
+    <aside class="contract-panel" aria-label="Host contract">
+      <div class="panel-block">
+        <p class="eyebrow">Host contract</p>
+        <div id="contract-summary" class="contract-summary"></div>
+      </div>
+      <div class="panel-block">
+        <p class="eyebrow">Stream health</p>
+        <div class="health-grid">
+          <div><span>Status</span><strong id="status">idle</strong></div>
+          <div><span>Accepted</span><strong id="accepted-count">0</strong></div>
+          <div><span>Skipped</span><strong id="skipped-count">0</strong></div>
+          <div><span>Blocked</span><strong id="blocked-count">0</strong></div>
+        </div>
+      </div>
+      <div class="panel-block">
+        <p class="eyebrow">Host state</p>
+        <pre id="state-preview">{}</pre>
+      </div>
+      <div id="setup-note" class="setup-note" hidden></div>
+    </aside>
+  </main>
+
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>

examples/surface-gallery/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@summon-example/surface-gallery",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pnpm --filter @summon-internal/devtools --filter @summon-internal/engine --filter @summon-internal/host --filter @summon-internal/sandbox-runtime build && pnpm --filter @anarchitecture/summon build && vite --host 127.0.0.1 --port 5174",
+    "build": "pnpm --filter @summon-internal/devtools --filter @summon-internal/engine --filter @summon-internal/host --filter @summon-internal/sandbox-runtime build && pnpm --filter @anarchitecture/summon build && vite build",
+    "test": "tsx --test src/*.test.ts",
+    "test:e2e": "playwright test -c playwright.config.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anarchitecture/summon": "workspace:*",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.4.0"
+  }
+}

examples/surface-gallery/playwright.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 30_000,
+  expect: {
+    timeout: 10_000,
+  },
+  reporter: process.env.CI ? [['list'], ['html', { open: 'never' }]] : 'list',
+  use: {
+    baseURL: 'http://127.0.0.1:5174',
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'pnpm --filter @summon-example/surface-gallery dev',
+    url: 'http://127.0.0.1:5174',
+    reuseExistingServer: false,
+    timeout: 120_000,
+  },
+});