@markmo/europacore-session-ui 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @markmo/europacore-session-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+europacore's session UI for any React 18 or 19 app that reaches a europacore server (`europacore/docs/server-api.md`):
+
+- sessions, with the live transcript, tool calls, approvals, steering and Stop;
+- workspaces (git, diffs, accept and discard, snapshots, pull requests) and fleets;
+- the overview, the live board and the decision register.
+
+It is europacoreui's own frontend, kept in that repository as an npm workspace. devassistant (Codaflow) installs it.
+
+## Use it
+
+```ts
+import { configureSessionUi, ThemeProvider, ToastProvider, SessionPage, OverviewPage, DialogHost } from '@markmo/europacore-session-ui';
+
+configureSessionUi({
+  // where the server's /v1 is, and how calls to it are signed
+  transport: {
+    baseUrl: '/europacore/v1',
+    headers: async () => ({ Authorization: `Bearer ${await idToken()}`, 'X-Devassistant-Workspace': workspaceId() }),
+    onUnauthorized: () => signIn(),
+  },
+  basePath: '/coding',            // pages at /coding/sessions/:id, /coding/board, ...
+  userName: () => currentUser()?.name ?? null,
+  // features: what the app allows (the coder, fleets, credentials); all off by default
+  // workspaces: the app's directories a coder can work in, when it has them
+  // disabledPermissionModes: modes users may not switch to here, e.g. ['bypassPermissions']
+  // approvalArmMs: how long an approval card ignores clicks after it appears (300 by default)
+});
+```
+
+Call it once before the first render, then:
+
+- **Routes.** Mount the pages at the paths `lib/paths.ts` names, under `basePath`:
+  - `SessionPage` at `sessions/:sessionId` (`new` starts one);
+  - `OverviewPage` at `sessions`;
+  - `ComparePage` at `sessions/:sessionId/compare/:group`;
+  - `BoardPage` at `board`;
+  - `DecisionsPage` at `decisions`.
+- **Shell.** Render `DialogHost` once, inside the router. Call `bootstrapFeatures()` once, and `loadAgents()` once signed in. `SessionsPanel`, `CommandPalette` and the hooks (`useAttention`, `useMemoryCapture`, `useSessionPageHooks`, `useHotkeys`) are optional.
+- **Router.** The package uses React Router 7 (`react-router`), a peer dependency.
+- **Theme.** `ThemeProvider` owns light and dark. Without it, the package follows the document's `dark` class.
+
+### Styles
+
+The components use Tailwind utilities named after semantic tokens:
+
+- `bg-surface`, `bg-surface-alt`, `bg-surface-sunken`, `bg-surface-hover`, `bg-bg`;
+- `text-ink`, `text-muted`, `text-faint`;
+- `border-line`, `border-line-soft`;
+- `accent`, `accent-hover`, `accent-soft` and `on-accent`;
+- the families `danger`, `warn` and `ok` (each with `-soft` and `-line`; `danger` also has `-ink`);
+- `disabled`.
+
+The app's Tailwind (v4) generates the utilities. Point it at the package, and give it the tokens:
+
+```css
+@import 'tailwindcss';
+@source '../node_modules/@markmo/europacore-session-ui/dist';
+@import '@markmo/europacore-session-ui/tokens.css';   /* europacoreui's palette; or define the names yourself */
+@import '@markmo/europacore-session-ui/styles.css';   /* markdown and the streaming caret */
+```
+
+## Develop
+
+From `frontend/`:
+
+- `npm test` runs the app's tests, then the package's.
+- `npm run typecheck` checks both.
+- `npm run build -w @markmo/europacore-session-ui` builds `dist/`: ES modules, one chunk per page, and `.d.ts` files.
+- `npm pack -w @markmo/europacore-session-ui` makes a tarball, for trying a change in an app before it is published.
+
+## Publish
+
+It is published to public npm, so an app installs it with no token: `npm install @markmo/europacore-session-ui`.
+
+1. Bump `version` and add to `CHANGELOG.md`.
+2. Once that is on `main`, push the tag `session-ui-v<version>`.
+3. `.github/workflows/publish-session-ui.yml` then checks, tests and publishes the package through npm trusted publishing: the workflow signs in as itself (OIDC), with no token. npmjs.com's package settings name this repository and workflow as its trusted publisher.