feat(io): model the editor's host protocol and run the Gherkin scenarios against it

apps/io-playground/README.md

@@ -0,0 +1,11 @@
+# I/O protocol playground
+
+An interactive view of `@portabletext/io`: Editor A, the link to the server, the server, the link to Editor B, and Editor B, side by side. Save requests, rejections and feed transactions sit as cards in the links until you deliver them, so a race is played by choosing the order.
+
+Each editor shows its message path: every `mutation`, `mutation sent`, `transaction`, `feed lost`, `load` and `resync` between its host and io, every `apply` io sends the editor, and the host's re-submits. Every value opens to its Portable Text blocks, every mutation, transaction and message to its patches. Each label has a one-sentence explanation behind its "i", and the Concepts button lists them all. After every step a narration says what happened in plain words.
+
+The Scenarios tab runs the Gherkin scenarios one step at a time. The Free play tab drives the same world by hand and writes down the steps as Gherkin, ready to copy out as a new scenario. It starts the editors in their first commit, and offers a plain, a Studio-shaped and a Horizon-shaped host, a feed that dies without telling anyone, a stored copy below the floor reached by a resync or by a transaction, and a listener that sends the document with each transaction. A `work dropped` shows as a notice with the dropped text.
+
+```sh
+pnpm --filter io-playground dev
+```

apps/io-playground/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>I/O protocol playground</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/io-playground/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "io-playground",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b && vite build",
+    "check:types": "tsc --noEmit --pretty --project tsconfig.app.json",
+    "check:types:watch": "tsc --watch --project tsconfig.app.json",
+    "clean": "del .turbo && del dist && del node_modules",
+    "dev": "vite",
+    "preview": "vite preview",
+    "test:unit": "vitest --run"
+  },
+  "dependencies": {
+    "@portabletext/io": "workspace:^",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "catalog:tooling",
+    "@types/react": "catalog:tooling",
+    "@types/react-dom": "catalog:tooling",
+    "@vitejs/plugin-react": "catalog:tooling",
+    "tailwindcss": "catalog:tooling",
+    "typescript": "catalog:tooling",
+    "vite": "catalog:tooling",
+    "vitest": "catalog:tooling"
+  }
+}

apps/io-playground/src/App.tsx

@@ -0,0 +1,234 @@
+import type {EditorName, World} from '@portabletext/io/testing'
+import {useState} from 'react'
+import {
+  applicableActions,
+  applicableNetworkActions,
+  editorPrompts,
+} from './applicable'
+import {DrawerView, OpenDetailsProvider, type Drawer} from './drawers'
+import {EditorPanel} from './editor-panel'
+import {FreePlayTab, useFreePlay} from './free-play-tab'
+import {LinkPanel} from './link-panel'
+import {ScenariosTab, useScenarioRunner} from './scenarios-tab'
+import {ServerPanel} from './server-panel'
+import {Button} from './ui'
+
+type Tab = 'scenarios' | 'free play'
+
+export function App() {
+  const [tab, setTab] = useState<Tab>('scenarios')
+  const [drawerState, setDrawerState] = useState<{
+    world: World
+    drawer: Drawer
+  } | null>(null)
+  const scenarioRunner = useScenarioRunner()
+  const freePlay = useFreePlay()
+  const world = tab === 'scenarios' ? scenarioRunner.world : freePlay.world
+  const snapshot = world.snapshot()
+  const drawer = drawerState?.world === world ? drawerState.drawer : null
+  const setDrawer = (
+    next: Drawer | null | ((current: Drawer | null) => Drawer | null),
+  ) => {
+    const resolved = typeof next === 'function' ? next(drawer) : next
+    setDrawerState(resolved === null ? null : {world, drawer: resolved})
+  }
+  const deadFeeds = tab === 'free play' ? freePlay.deadFeeds : []
+  const network = applicableNetworkActions(snapshot, deadFeeds)
+  const promptsFor = (name: EditorName) => {
+    const held = network.links[name].held
+
+    return [
+      ...editorPrompts(applicableActions(snapshot, name)),
+      ...(held === undefined ? [] : [held]),
+    ]
+  }
+  const [selection, setSelection] = useState<{
+    world: World
+    mutationIds: Array<string>
+  } | null>(null)
+  const selectedMutationIds =
+    selection?.world === world ? selection.mutationIds : []
+  const [dismissedWork, setDismissedWork] = useState<{
+    world: World
+    byEditor: Record<EditorName, Array<number>>
+  } | null>(null)
+  const dismissedFor = (name: EditorName) =>
+    dismissedWork?.world === world ? dismissedWork.byEditor[name] : []
+  const dismissWork = (name: EditorName, index: number) =>
+    setDismissedWork({
+      world,
+      byEditor: {
+        'Editor A': dismissedFor('Editor A'),
+        'Editor B': dismissedFor('Editor B'),
+        [name]: [...dismissedFor(name), index],
+      },
+    })
+  const onStep =
+    tab === 'free play'
+      ? (text: string) => freePlay.perform('When', text)
+      : undefined
+  const onDeliver =
+    tab === 'free play'
+      ? (text: string) => freePlay.perform('When', text)
+      : scenarioRunner.finished && !scenarioRunner.running
+        ? scenarioRunner.deliver
+        : undefined
+  const saveRequests = snapshot.network?.saveRequests ?? []
+  const selectedRequests = saveRequests.filter((request) =>
+    selectedMutationIds.includes(request.mutationId),
+  )
+
+  function toggleSelected(mutationId: string) {
+    setSelection({
+      world,
+      mutationIds: selectedMutationIds.includes(mutationId)
+        ? selectedMutationIds.filter((candidate) => candidate !== mutationId)
+        : [
+            ...selectedMutationIds.filter((candidate) =>
+              saveRequests.some((request) => request.mutationId === candidate),
+            ),
+            mutationId,
+          ],
+    })
+  }
+
+  function receiveSelected() {
+    const [first, second] = selectedRequests
+
+    if (!first || !second || !onStep) {
+      return
+    }
+
+    setSelection(null)
+    onStep(
+      `the server receives ${first.editor}'s mutation ${first.mutationNumber} and ${second.editor}'s mutation ${second.mutationNumber} as one transaction`,
+    )
+  }
+
+  return (
+    <OpenDetailsProvider
+      value={(selection) => setDrawer({type: 'details', selection})}
+    >
+      <div className="flex h-screen flex-col">
+        <header className="flex items-center gap-3 border-b border-gray-200 bg-white px-4 py-1.5">
+          <h1 className="text-sm font-semibold">I/O protocol playground</h1>
+          <p className="flex-1 text-xs text-gray-500">
+            Two editors save to one server through a link each. Click any value,
+            mutation or transaction to look inside it.
+          </p>
+          <Button
+            onClick={() =>
+              setDrawer((current) =>
+                current?.type === 'concepts' ? null : {type: 'concepts'},
+              )
+            }
+          >
+            Concepts
+          </Button>
+        </header>
+
+        <main className="grid min-h-0 flex-1 grid-cols-[minmax(0,1.25fr)_minmax(0,1fr)_minmax(0,1.1fr)_minmax(0,1fr)_minmax(0,1.25fr)] gap-2 p-2">
+          <EditorPanel
+            name="Editor A"
+            editor={snapshot.editors?.['Editor A']}
+            savingFor={
+              tab === 'free play' ? freePlay.savingFor('Editor A') : undefined
+            }
+            dismissedWork={dismissedFor('Editor A')}
+            onDismissWork={(index) => dismissWork('Editor A', index)}
+            waitingCount={snapshot.network?.feeds['Editor A'].length ?? 0}
+            prompts={promptsFor('Editor A')}
+          />
+          <LinkPanel
+            name="Editor A"
+            editorSide="left"
+            editor={snapshot.editors?.['Editor A']}
+            network={snapshot.network}
+            applicability={network.links['Editor A']}
+            onStep={onStep}
+            onDeliver={onDeliver}
+            selectedMutationIds={selectedMutationIds}
+            onToggleSelected={toggleSelected}
+            deadFeed={deadFeeds.includes('Editor A')}
+          />
+          <ServerPanel
+            server={snapshot.server}
+            now={snapshot.network?.now}
+            advanceClock={network.advanceClock}
+            onStep={onStep}
+            selectedRequests={selectedRequests}
+            onReceiveSelected={receiveSelected}
+            editorA={snapshot.editors?.['Editor A']}
+            editorADeadFeed={deadFeeds.includes('Editor A')}
+            carriesServerCopy={
+              snapshot.network?.carriesServerCopy ??
+              (tab === 'free play' && freePlay.setup.transactionsCarryCopy)
+            }
+            onToggleServerCopy={
+              tab === 'free play'
+                ? freePlay.setTransactionsCarryCopy
+                : undefined
+            }
+          />
+          <LinkPanel
+            name="Editor B"
+            editorSide="right"
+            editor={snapshot.editors?.['Editor B']}
+            network={snapshot.network}
+            applicability={network.links['Editor B']}
+            onStep={onStep}
+            onDeliver={onDeliver}
+            selectedMutationIds={selectedMutationIds}
+            onToggleSelected={toggleSelected}
+            deadFeed={deadFeeds.includes('Editor B')}
+          />
+          <EditorPanel
+            name="Editor B"
+            editor={snapshot.editors?.['Editor B']}
+            savingFor={
+              tab === 'free play' ? freePlay.savingFor('Editor B') : undefined
+            }
+            dismissedWork={dismissedFor('Editor B')}
+            onDismissWork={(index) => dismissWork('Editor B', index)}
+            waitingCount={snapshot.network?.feeds['Editor B'].length ?? 0}
+            prompts={promptsFor('Editor B')}
+          />
+        </main>
+
+        <footer className="flex h-[40vh] flex-col border-t border-gray-300 bg-white">
+          <nav className="flex gap-1 border-b border-gray-200 px-4 pt-2">
+            {(['scenarios', 'free play'] as const).map((candidate) => (
+              <button
+                key={candidate}
+                type="button"
+                onClick={() => setTab(candidate)}
+                className={`rounded-t px-3 py-1 text-sm capitalize ${
+                  candidate === tab
+                    ? 'border border-b-0 border-gray-300 bg-gray-50 font-semibold'
+                    : 'text-gray-500 hover:text-gray-800'
+                }`}
+              >
+                {candidate}
+              </button>
+            ))}
+          </nav>
+          <div className="min-h-0 flex-1 overflow-hidden p-4">
+            {tab === 'scenarios' ? (
+              <ScenariosTab runner={scenarioRunner} />
+            ) : (
+              <FreePlayTab freePlay={freePlay} />
+            )}
+          </div>
+        </footer>
+      </div>
+
+      {drawer ? (
+        <DrawerView
+          drawer={drawer}
+          snapshot={snapshot}
+          onClose={() => setDrawer(null)}
+        />
+      ) : null}
+    </OpenDetailsProvider>
+  )
+}