feat(viewer): post/surface vocabulary — engine UI, host contract, helper rename

Adopt the canonical workspace ▸ session ▸ post ▸ surface model in the viewer
engine. A post is the published artifact (an ordered list of surfaces); a
surface is one block inside a post.

Internal rename only — behavior is unchanged and every wire-bound string is
kept byte-identical: /api/* paths, /s/ nav URLs, the ?part= query key, SSE
event types (surface-created/-updated/-deleted), the comment body { surface }
key and author:"surface" value, and the server-provided surfaceCount field.
The Route type's surfaceId field is also left intact.

- viewer local identifiers/props/signals/functions: artifact surface→post,
  block part→surface (focusPost, standalonePost, posts, postLink, postImageLink,
  Card/StandaloneView prop post, surfaceFrames).
- component files renamed: ImagePart→ImageSurface, JsonPart→JsonSurface,
  TracePart→TraceSurface (prop part→surface).
- CSS classes: .part-unsupported→.surface-unsupported, .imagepart→.image-surface,
  .tracepart→.trace-surface, .jsonpart→.json-surface, .tl-surface→.tl-post.
- user-visible strings: "surface"→"post"; onboarding copy reworded off the
  retired board/snippet terms.
- host contract: identity.accountSlug→identity.workspaceSlug (embedders must
  update) in viewer/src/host.ts and viewer/embed.d.ts.
- server helper: surfaceParts.ts→postSurfaces.ts, coerceSurfaceParts→coerceSurfaces,
  validateSurfaceParts→validateSurfaces; importers + mcpHttp coerceParts alias updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: benvinegar

.changeset/viewer-post-surface-vocab.md

@@ -0,0 +1,22 @@
+---
+"sideshow": minor
+---
+
+Adopt the **post / surface** vocabulary throughout the viewer engine and the
+host contract. The canonical hierarchy is **workspace ▸ session ▸ post ▸
+surface**: a **post** is the published artifact (an ordered list of surfaces),
+and a **surface** is one block inside a post.
+
+This is an internal rename of the viewer's local identifiers, component names,
+props, CSS classes, and user-visible strings — behavior is unchanged and all
+wire paths, query keys (`?part=`), SSE event types, and server-provided JSON
+field names are kept byte-identical for compatibility. The block component
+files were renamed (`ImagePart`→`ImageSurface`, `JsonPart`→`JsonSurface`,
+`TracePart`→`TraceSurface`), and the server helper `surfaceParts.ts` is now
+`postSurfaces.ts` (`coerceSurfaceParts`→`coerceSurfaces`,
+`validateSurfaceParts`→`validateSurfaces`).
+
+**Host-contract change (embedders must update):** the host identity key
+`identity.accountSlug` is renamed to `identity.workspaceSlug`. Any embedder
+passing `accountSlug` on the injected host's `identity` must rename it to
+`workspaceSlug`.

server/app.ts

@@ -30,7 +30,7 @@ import {
   type TerminalSurface,
   type TraceStep,
 } from "./types.ts";
-import { validateSurfaceParts } from "./surfaceParts.ts";
+import { validateSurfaces } from "./postSurfaces.ts";
 
 const MAX_SURFACE_BYTES = 2 * 1024 * 1024;
 const MAX_WAIT_SECONDS = 300;
@@ -808,7 +808,7 @@ export function createApp({
     if (!body || !Array.isArray(blocks)) {
       return c.json({ error: 'body must include a "surfaces" (or legacy "parts") array' }, 400);
     }
-    const parsed = await validateSurfaceParts(blocks);
+    const parsed = await validateSurfaces(blocks);
     if (!parsed.ok) return c.json({ error: parsed.error }, 400);
     return publish(c, body, parsed.parts);
   };
@@ -823,7 +823,7 @@ export function createApp({
     if (!body || typeof body.html !== "string" || !body.html.trim()) {
       return c.json({ error: 'body must include non-empty "html" string' }, 400);
     }
-    const parsed = await validateSurfaceParts([htmlSurface(body.html, body.kits)]);
+    const parsed = await validateSurfaces([htmlSurface(body.html, body.kits)]);
     if (!parsed.ok) return c.json({ error: parsed.error }, 400);
     return publish(c, body, parsed.parts);
   });
@@ -860,11 +860,11 @@ export function createApp({
       if (!Array.isArray(blocks)) {
         return c.json({ error: '"surfaces" (or legacy "parts") must be an array' }, 400);
       }
-      const parsed = await validateSurfaceParts(blocks);
+      const parsed = await validateSurfaces(blocks);
       if (!parsed.ok) return c.json({ error: parsed.error }, 400);
       parts = parsed.parts;
     } else if (typeof body.html === "string") {
-      const parsed = await validateSurfaceParts([htmlSurface(body.html, body.kits)]);
+      const parsed = await validateSurfaces([htmlSurface(body.html, body.kits)]);
       if (!parsed.ok) return c.json({ error: parsed.error }, 400);
       parts = parsed.parts;
     }

server/kits.ts

@@ -6,7 +6,7 @@
 // per part, not a frame every surface is locked into.
 //
 // Runtime-agnostic (no node imports): imported by surfacePage (server render),
-// surfaceParts (id allowlist), and surfaced over HTTP/MCP for discovery. Every
+// postSurfaces (id allowlist), and surfaced over HTTP/MCP for discovery. Every
 // class resolves against the theme `--color-*` / `--font-*` / radius tokens, so
 // kit output re-themes with the board like any other html part.
 

server/mcpHttp.ts

@@ -11,7 +11,7 @@ import {
   type Surface,
 } from "./types.ts";
 import { HTTP_MCP_TOOLS, MCP_INSTRUCTIONS, MCP_SERVER_INFO } from "./mcpSpec.ts";
-import { coerceSurfaceParts } from "./surfaceParts.ts";
+import { coerceSurfaces } from "./postSurfaces.ts";
 
 // Stateless MCP over streamable HTTP: every request is self-contained, which
 // is what a serverless deployment needs. Session continuity is explicit —
@@ -51,7 +51,7 @@ export interface McpDeps {
 // Coerce loosely-typed tool args into validated SurfacePart[]. Unknown kinds
 // and empty parts are dropped rather than rejected, so a slightly-off call
 // still publishes what it can.
-export const coerceParts = coerceSurfaceParts;
+export const coerceParts = coerceSurfaces;
 
 export function registerMcp(app: Hono, deps: McpDeps) {
   // The view URL's path segment: legacy tools emit /s/<id>; the new post tools

server/surfaceParts.ts server/postSurfaces.tsserver/surfaceParts.ts renamed to server/postSurfaces.ts

@@ -269,10 +269,10 @@ async function parseSurfaceParts(
   return { parts, errors: [] };
 }
 
-export const coerceSurfaceParts = (raw: unknown): Promise<Surface[]> =>
+export const coerceSurfaces = (raw: unknown): Promise<Surface[]> =>
   parseSurfaceParts(raw).then((r) => r.parts);
 
-export async function validateSurfaceParts(
+export async function validateSurfaces(
   raw: unknown,
 ): Promise<{ ok: true; parts: Surface[] } | { ok: false; error: string }> {
   const result = await parseSurfaceParts(raw, { strict: true });

test/assets.test.ts

@@ -8,7 +8,7 @@ import {
   selectEvictions,
   type Surface,
 } from "../server/types.ts";
-import { validateSurfaceParts } from "../server/surfaceParts.ts";
+import { validateSurfaces } from "../server/postSurfaces.ts";
 
 // --- selectEvictions ---
 
@@ -78,8 +78,8 @@ test("surfacesByteLength counts image/trace surfaces without throwing", () => {
 
 // --- SurfacePart validation/coercion ---
 
-test("validateSurfaceParts accepts all supported part kinds", async () => {
-  const result = await validateSurfaceParts([
+test("validateSurfaces accepts all supported part kinds", async () => {
+  const result = await validateSurfaces([
     { kind: "html", html: "<p>x</p>" },
     { kind: "html", html: "<div class=tree></div>", kits: ["issues"] },
     { kind: "diff", patch: "--- a/x\n+++ b/x\n@@ -1 +1 @@\n-a\n+b", layout: "unified" },
@@ -118,7 +118,7 @@ test("validateSurfaceParts accepts all supported part kinds", async () => {
     );
 });
 
-test("validateSurfaceParts rejects malformed parts", async () => {
+test("validateSurfaces rejects malformed parts", async () => {
   for (const parts of [
     [{ kind: "html", html: 1 }],
     [{ kind: "html", html: "<p>x</p>", kits: ["nope"] }], // unknown kit id (strict)
@@ -131,41 +131,41 @@ test("validateSurfaceParts rejects malformed parts", async () => {
     [{ kind: "code" }], // missing code
     [{ kind: "unknown" }],
   ]) {
-    const result = await validateSurfaceParts(parts);
+    const result = await validateSurfaces(parts);
     assert.equal(result.ok, false, JSON.stringify(parts));
   }
 });
 
-test("validateSurfaceParts rejects a diff patch with no parseable file content", async () => {
+test("validateSurfaces rejects a diff patch with no parseable file content", async () => {
   for (const patch of [
     "not a patch at all",
     "hello world\nfoo bar",
     "@@ -1 +1 @@\n-a\n+b", // hunk with no --- /+++ file headers
   ]) {
-    const result = await validateSurfaceParts([{ kind: "diff", patch }]);
+    const result = await validateSurfaces([{ kind: "diff", patch }]);
     assert.equal(result.ok, false, `patch ${JSON.stringify(patch)} should be rejected`);
     if (!result.ok) assert.match(result.error, /did not parse to any file/);
   }
 });
 
-test("validateSurfaceParts accepts real unified and git-style diff patches", async () => {
+test("validateSurfaces accepts real unified and git-style diff patches", async () => {
   for (const patch of [
     "--- a/x.ts\n+++ b/x.ts\n@@ -1 +1 @@\n-a\n+b",
     "diff --git a/x b/x\nindex 0..1 100644\n--- a/x\n+++ b/x\n@@ -1 +1 @@\n-a\n+b",
     "--- a/x\n+++ b/x\n@@ -1,2 +1,2 @@\n a\n-b\n+c\n d\n--- a/y\n+++ b/y\n@@ -1 +1 @@\n-e\n+f", // multi-file
   ]) {
-    const result = await validateSurfaceParts([{ kind: "diff", patch }]);
+    const result = await validateSurfaces([{ kind: "diff", patch }]);
     assert.equal(result.ok, true, `patch ${JSON.stringify(patch)} should be accepted`);
   }
 });
 
-test("validateSurfaceParts accepts valid mermaid diagrams (supported types)", async () => {
+test("validateSurfaces accepts valid mermaid diagrams (supported types)", async () => {
   for (const mermaid of [
     'pie title Pets\n  "Dogs" : 386\n  "Cats" : 85',
     "gitGraph\n  commit\n  commit\n  branch develop",
     "architecture-beta\n  group api(cloud)[API]",
   ]) {
-    const result = await validateSurfaceParts([{ kind: "mermaid", mermaid }]);
+    const result = await validateSurfaces([{ kind: "mermaid", mermaid }]);
     assert.equal(
       result.ok,
       true,
@@ -174,7 +174,7 @@ test("validateSurfaceParts accepts valid mermaid diagrams (supported types)", as
   }
 });
 
-test("validateSurfaceParts lets unsupported mermaid types through (Jison types)", async () => {
+test("validateSurfaces lets unsupported mermaid types through (Jison types)", async () => {
   // flowchart, sequence, class, state, er, gantt are still on Jison — the
   // official parser doesn't cover them, so validation is skipped and the
   // viewer's graceful fallback handles any render failure.
@@ -186,7 +186,7 @@ test("validateSurfaceParts lets unsupported mermaid types through (Jison types)"
     "gantt\n  title Project\n  section Phase 1\n  Task 1 :a1, 2024-01-01, 30d",
     "classDiagram\n  Animal <|-- Dog",
   ]) {
-    const result = await validateSurfaceParts([{ kind: "mermaid", mermaid }]);
+    const result = await validateSurfaces([{ kind: "mermaid", mermaid }]);
     assert.equal(
       result.ok,
       true,
@@ -195,12 +195,12 @@ test("validateSurfaceParts lets unsupported mermaid types through (Jison types)"
   }
 });
 
-test("validateSurfaceParts rejects invalid mermaid with a parse error (supported types)", async () => {
+test("validateSurfaces rejects invalid mermaid with a parse error (supported types)", async () => {
   for (const mermaid of [
     'pie title Pets\n  "Dogs" : broken !!@@',
     "gitGraph\n  commit\n  !!bad syntax!!",
   ]) {
-    const result = await validateSurfaceParts([{ kind: "mermaid", mermaid }]);
+    const result = await validateSurfaces([{ kind: "mermaid", mermaid }]);
     assert.equal(
       result.ok,
       false,

test/kits.test.ts

@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 import { isKnownKit, KIT_IDS, kitAssets, kitSummaries } from "../server/kits.ts";
 import { renderHtmlPage } from "../server/surfacePage.ts";
-import { coerceSurfaceParts, validateSurfaceParts } from "../server/surfaceParts.ts";
+import { coerceSurfaces, validateSurfaces } from "../server/postSurfaces.ts";
 
 // --- kitAssets ---
 
@@ -75,29 +75,29 @@ test("kitSummaries advertises each kit without leaking the css/js payload", () =
 
 // --- validation: strict (REST) rejects, loose (MCP) filters ---
 
-test("validateSurfaceParts accepts an html part with known kits", async () => {
-  const r = await validateSurfaceParts([
+test("validateSurfaces accepts an html part with known kits", async () => {
+  const r = await validateSurfaces([
     { kind: "html", html: "<p>x</p>", kits: ["issues", "slides"] },
   ]);
   assert.equal(r.ok, true);
   if (r.ok)
     assert.deepEqual(r.parts[0], { kind: "html", html: "<p>x</p>", kits: ["issues", "slides"] });
 });
 
-test("validateSurfaceParts rejects an unknown kit id with the valid set", async () => {
-  const r = await validateSurfaceParts([{ kind: "html", html: "<p>x</p>", kits: ["bogus"] }]);
+test("validateSurfaces rejects an unknown kit id with the valid set", async () => {
+  const r = await validateSurfaces([{ kind: "html", html: "<p>x</p>", kits: ["bogus"] }]);
   assert.equal(r.ok, false);
   if (!r.ok) assert.match(r.error, /unknown kit "bogus".*issues/);
 });
 
-test("coerceSurfaceParts filters unknown kits rather than dropping the part", async () => {
-  const parts = await coerceSurfaceParts([
+test("coerceSurfaces filters unknown kits rather than dropping the part", async () => {
+  const parts = await coerceSurfaces([
     { kind: "html", html: "<p>x</p>", kits: ["issues", "bogus"] },
   ]);
   assert.deepEqual(parts, [{ kind: "html", html: "<p>x</p>", kits: ["issues"] }]);
 });
 
-test("coerceSurfaceParts drops an all-unknown kits field entirely", async () => {
-  const parts = await coerceSurfaceParts([{ kind: "html", html: "<p>x</p>", kits: ["nope"] }]);
+test("coerceSurfaces drops an all-unknown kits field entirely", async () => {
+  const parts = await coerceSurfaces([{ kind: "html", html: "<p>x</p>", kits: ["nope"] }]);
   assert.deepEqual(parts, [{ kind: "html", html: "<p>x</p>" }]);
 });

viewer/embed.d.ts

@@ -18,7 +18,7 @@ export interface SideshowHost {
   basePath: string;
   router: HostRouter;
   /** The caller's own identity, when the host knows it. */
-  identity?: { login: string; accountSlug?: string; role?: string };
+  identity?: { login: string; workspaceSlug?: string; role?: string };
   /**
    * Layout the engine renders. "full" (default) shows the sidebar + stream;
    * "stream" shows only the current session's stream — no sidebar, session list,