@thespielplatz/tsp-tools-theme 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -8,6 +8,20 @@ Consumers pin a caret range and do not auto-update, so a release only reaches a
 that service's own spec says so. This package has no users of its own — every entry below is a
 change to eight apps at once, at the moment each of them chooses to take it.
 
+## v0.3.3
+
+[compare changes](https://github.com/inf0matics/tsp-tools-theme/compare/v0.3.2...v0.3.3)
+
+### 🚀 Enhancements
+
+- The account page and the MCP page are components (spec 07) ([ec38a8c](https://github.com/inf0matics/tsp-tools-theme/commit/ec38a8c))
+- TspAppShell — the frame every app was hand-copying (spec 08) ([6713d8e](https://github.com/inf0matics/tsp-tools-theme/commit/6713d8e))
+
+### 📖 Documentation
+
+- The typography scale, and the pages as pages ([68e54e9](https://github.com/inf0matics/tsp-tools-theme/commit/68e54e9))
+- Anything with one right answer is a component, not a recipe ([75b88c7](https://github.com/inf0matics/tsp-tools-theme/commit/75b88c7))
+
 ## v0.3.2
 
 [compare changes](https://github.com/inf0matics/tsp-tools-theme/compare/v0.3.1...v0.3.2)

package/README.md

@@ -89,39 +89,41 @@ shell components wherever you like:
 
 ```vue
 <template>
-  <div class="flex min-h-svh bg-default text-default">
-    <TspSidebar>
-      <template #brand>
-        <TspBrandTile><img src="/logo.svg" alt="trips"></TspBrandTile>
-        <TspWordmark name="trips" />
-      </template>
-      <template #nav>
-        <TspNavItem to="/" icon="i-tabler-car" badge="Owner" badge-tone="primary">Fahrten</TspNavItem>
-        <TspNavGroup to="/reports" icon="i-tabler-file-text" label="Berichte">
-          <TspNavSubItem to="/reports/tax" icon="i-tabler-receipt">Steuer</TspNavSubItem>
-        </TspNavGroup>
-        <TspNavSection label="Extern" />
-        <TspNavItem to="/handbook" icon="i-tabler-book">Handbuch</TspNavItem>
-      </template>
-      <template #footer>
-        <TspSidebarFooter
-          v-model="locale"
-          app-name="trips"
-          user="fil" user-to="/user"
-          settings-to="/settings" logout-href="/auth/logout"
-          :locales="['de', 'en']"
-          github-link="https://github.com/…" version="v1.2.0" version-link="https://github.com/…/releases/tag/v1.2.0"
-          tip-jar tool-of
-        />
-      </template>
-    </TspSidebar>
-    <main class="flex-1 min-w-0 bg-default">
-      <TspContainer><NuxtPage /></TspContainer>
-    </main>
-  </div>
+  <TspAppShell app-name="trips">
+    <template #brand>
+      <TspBrandTile><img src="/logo.svg" alt="trips"></TspBrandTile>
+      <TspWordmark name="trips" />
+    </template>
+    <template #nav>
+      <TspNavItem to="/" icon="i-tabler-car" badge="Owner" badge-tone="primary">Fahrten</TspNavItem>
+      <TspNavGroup to="/reports" icon="i-tabler-file-text" label="Berichte">
+        <TspNavSubItem to="/reports/tax" icon="i-tabler-receipt">Steuer</TspNavSubItem>
+      </TspNavGroup>
+      <TspNavSection label="Extern" />
+      <TspNavItem to="/handbook" icon="i-tabler-book">Handbuch</TspNavItem>
+    </template>
+    <template #footer>
+      <TspSidebarFooter
+        v-model="locale"
+        app-name="trips"
+        user="fil" user-to="/user"
+        settings-to="/settings" logout-href="/auth/logout"
+        :locales="['de', 'en']"
+        github-link="https://github.com/…" version="v1.2.0" version-link="https://github.com/…/releases/tag/v1.2.0"
+        tip-jar tool-of
+      />
+    </template>
+
+    <NuxtPage />
+  </TspAppShell>
 </template>
 ```
 
+**`TspAppShell` is the whole frame** — root element, sidebar, content column, the mobile top bar
+and the measure. It picks a plain `div` or `<TspThemeProvider>` as its root from your
+`apply` setting, so the same layout serves global and scoped consumption. Don't hand-roll it:
+that frame was written out by hand in all eight services and no two of them agreed (spec 08).
+
 ## Scoped usage (one sub-area themed)
 
 `nuxt.config.ts`:
@@ -197,7 +199,8 @@ mask }`, show/hide a secret with a fixed-length placeholder.
 | Component | Purpose |
 |---|---|
 | `TspThemeProvider` | Scoped wrapper — marks a sub-area as themed (`.tsp-theme`). |
-| `TspSidebar` | App-shell sidebar frame; slots `#brand` `#nav` `#footer`. |
+| `TspAppShell` | **The whole logged-in frame** — root, sidebar, content column, top bar, measure. Start here. |
+| `TspSidebar` | The sidebar alone; slots `#brand` `#nav` `#footer`. `TspAppShell` wraps it for you. |
 | `TspSidebarFooter` | User → Settings → Logout → divider → theme + language → meta icons + version → "A tool of tsp.tools". Rows are **props**, not slots. |
 | `TspSiteHeader` | Public/marketing header; slots `#brand` `#nav` `#actions`, prop `sticky`. |
 | `TspSiteFooter` | Public/marketing footer; slots `#brand` `#links` `#actions`. |
@@ -210,6 +213,9 @@ mask }`, show/hide a secret with a fixed-length placeholder.
 | `TspNavLabel` | Truncates a label and reveals it in full on hover. Used by the rows above. |
 | `TspBrandTile` | The frame around a service's mark — `sidebar` (24px) or `hero` (64/96px). |
 | `TspUserCard` | Account card for a service's user page; masked id + manage link. |
+| `TspPageHeader` | The page title and its lede. **The heading scale lives here** — don't hand-roll an `h1`. |
+| `TspAccountPage` | The standalone account page, whole: heading + `TspUserCard`. |
+| `TspMcpSettings` | The whole MCP connection page — server, AI-processing warning, Claude, generic. |
 | `TspFooterRow` | One sidebar-footer row — `to` / `href` / `button`. |
 | `TspLanguageToggle` | DE/EN segmented control; all strings are props. |
 | `TspVersionBadge` | Version pill with a tag icon; a link only when given `href`. |
@@ -235,6 +241,27 @@ version badge links to the release; leave it out and the badge is plain text —
 is then ignored**, because a closed-source project has no release page to point at. There is no
 `variant` prop; a second source of truth could disagree with the first.
 
+### Three of them are whole pages
+
+`TspPageHeader`, `TspAccountPage` and `TspMcpSettings` are not building blocks — they are the
+page. Reach for them before assembling one out of `TspSectionCard` and `TspCopyField`:
+
+```vue
+<TspMcpSettings
+  endpoint="https://todo.tsp.tools/mcp"
+  :api-key="key"
+  server-name="todo"
+  :labels="{ apiKey: t('mcp.key'), … }"
+  @regenerate="rotate"
+/>
+```
+
+That is the whole page — the server card, the third-party-processing warning, the Claude
+snippet (redacted on screen, complete on copy) and the generic client card, in that order. It
+exists because the order is what drifted: the page reached four copies in three shapes before
+it was a component. Every visible string is an optional key on `labels`; see
+[`docs/api.md`](docs/api.md) for the full interface.
+
 ### App shell vs site shell
 
 `TspSidebar` + `TspSidebarFooter` are the **logged-in** shell. For a public/marketing surface

package/components/TspAccountPage.vue

@@ -0,0 +1,81 @@
+<!--
+  A service's account page, whole.
+
+    <TspAccountPage
+      :name="user.name"
+      :account-id="user.id"
+      manage-link="https://logto.tsp.tools/account"
+    />
+
+  WHY A WRAPPER OVER ONE CARD IS WORTH IT. TspUserCard has existed since 0.3.0
+  and tsp-todo used it correctly — and its account page still came out wrong,
+  because the heading above the card was the app's to invent and it invented
+  `text-[28px]`. Two correct components a consumer must know to combine is
+  precisely the step that failed. This is one named thing that can be found in
+  `api.md` and dropped in whole (spec 07).
+
+  It is the STANDALONE page. Inside a tabbed settings area the heading belongs
+  to the parent route, so use <TspPageHeader> there and <TspUserCard> directly
+  — a second <h1> under the tabs is not what this is for.
+
+  The layer has no auth and no data: the name, the id and the manage URL are
+  the app's. Every string is a prop with an English default, and they are
+  forwarded rather than redeclared with defaults of their own — two sets of
+  defaults for one card is two places for them to disagree.
+-->
+<template>
+  <div data-testid="tsp-account-page">
+    <TspPageHeader
+      :title="title"
+      :description="description"
+    />
+    <TspUserCard
+      :name="name"
+      :account-label="accountLabel"
+      :account-id="accountId"
+      :id-label="idLabel"
+      :manage-link="manageLink"
+      :manage-label="manageLabel"
+      :reveal-label="revealLabel"
+      :hide-label="hideLabel"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+// Only `title` carries a default. The card's strings are passed through as
+// `undefined` when the caller omits them, which is the value Vue resolves
+// against TspUserCard's OWN defaults — so there is exactly one copy of them.
+withDefaults(defineProps<{
+  /** Display name. */
+  name: string
+  /** The page title. */
+  title?: string
+  /** One line under the title. Omit for none. */
+  description?: string
+  /** Which account this is — shown under the name. */
+  accountLabel?: string
+  /** The account id. Omit to hide the whole id block. */
+  accountId?: string
+  /** Label over the account id. */
+  idLabel?: string
+  /** Where “manage account” goes. Omit to hide the link. */
+  manageLink?: string
+  /** Text of the manage-account link. */
+  manageLabel?: string
+  /** Accessible name for the eye while the id is hidden. */
+  revealLabel?: string
+  /** Accessible name for it while the id is shown. */
+  hideLabel?: string
+}>(), {
+  title: 'Account',
+  description: undefined,
+  accountLabel: undefined,
+  accountId: undefined,
+  idLabel: undefined,
+  manageLink: undefined,
+  manageLabel: undefined,
+  revealLabel: undefined,
+  hideLabel: undefined,
+})
+</script>

package/components/TspAppShell.vue

@@ -0,0 +1,121 @@
+<!--
+  The logged-in frame: root, sidebar, content column, mobile top bar, measure.
+
+    <TspAppShell app-name="todo">
+      <template #brand>…</template>
+      <template #nav>…</template>
+      <template #footer><TspSidebarFooter … /></template>
+      <NuxtPage />
+    </TspAppShell>
+
+  WHY THIS EXISTS. The layer already owned every piece; it did not own how they
+  go together, so all eight consumers and both demos hand-wrote the same fifteen
+  lines — and they were not the same fifteen lines. The survey behind spec 08
+  found three disagreements nobody had chosen:
+
+    · two scroll models (trips/gage/pogo pin the frame and scroll <main>;
+      everything else scrolls the page),
+    · three viewport units for one intent — min-h-svh, h-svh, and tsp-todo's
+      min-h-screen, which is 100vh: the unit that breaks under a mobile
+      browser's collapsing toolbar, and the reason svh exists,
+    · `bg-default` on the content column, or not — present in both demos,
+      absent in four apps, and only visible when a page is shorter than the
+      viewport, which is why nobody had noticed.
+
+  Otherwise the classes were identical but REORDERED (`flex-1 min-w-0 flex
+  flex-col` against `flex min-w-0 flex-1 flex-col`). That is copy-paste, not
+  intent, and it is what a component is for.
+
+  THE ROOT ELEMENT IS DERIVED, NOT DECLARED. `useTspThemeOptions().apply`
+  already knows whether this app is themed globally or scoped, so the shell
+  picks a plain <div> or <TspThemeProvider> itself. There is no `mode` prop, for
+  the same reason TspSidebarFooter has no `variant` prop: a second source of
+  truth is one that can disagree with the first.
+
+  What stays the app's: its mark, its nav list, its footer values, its page.
+-->
+<template>
+  <component
+    :is="root"
+    data-testid="tsp-app-shell"
+    :class="rootClass"
+  >
+    <TspSidebar>
+      <template #brand><slot name="brand" /></template>
+      <template #nav><slot name="nav" /></template>
+      <template #footer><slot name="footer" /></template>
+    </TspSidebar>
+
+    <!-- bg-default here as well as on the root: the root's paint is behind the
+         SIDEBAR too, and the column is what shows beside it when a page is
+         short. This is the line four apps are missing. -->
+    <div
+      data-testid="tsp-app-shell-content"
+      class="flex min-w-0 flex-1 flex-col bg-default"
+    >
+      <!-- Below sm the sidebar is a drawer, so this bar is the only thing that
+           says where you are. It hides itself above sm. -->
+      <TspTopBar :menu-label="menuLabel">
+        <template #brand>
+          <slot name="top-brand">
+            <TspWordmark
+              v-if="appName"
+              :name="appName"
+            />
+          </slot>
+        </template>
+      </TspTopBar>
+
+      <main :class="mainClass">
+        <TspContainer :width="containerWidth">
+          <slot />
+        </TspContainer>
+      </main>
+    </div>
+  </component>
+</template>
+
+<script setup lang="ts">
+// Imported rather than auto-imported: `<component :is>` needs the component
+// itself, and the auto-import only resolves a tag in a template.
+import TspThemeProvider from './TspThemeProvider.vue'
+
+const props = withDefaults(defineProps<{
+  /** The service's name. Renders the top bar's wordmark — override with `#top-brand`. */
+  appName?: string
+  /** Forwarded to `TspContainer`: `app` (1152px) or `site` (1240px). */
+  containerWidth?: 'app' | 'site'
+  /**
+   * `page` scrolls the document and leaves the sidebar sticky — the model this
+   * layer documents and the one the mobile drawer was built against. `inner`
+   * pins the frame to the viewport and scrolls `<main>` instead, which is what
+   * trips, gage and pogo run today; it is a real choice for a dense table view,
+   * so adopting this shell is not forced to be a redesign as well.
+   */
+  scroll?: 'page' | 'inner'
+  /** Accessible name for the mobile burger. Forwarded to `TspTopBar`. */
+  menuLabel?: string
+}>(), {
+  appName: undefined,
+  containerWidth: 'app',
+  scroll: 'page',
+  menuLabel: undefined,
+})
+
+const { apply } = useTspThemeOptions()
+
+// TspThemeProvider paints bg-default and text-default on its own root, so the
+// scoped branch must not repeat them — two sources for one colour.
+const root = computed(() => (apply === 'scoped' ? TspThemeProvider : 'div'))
+
+const rootClass = computed(() => [
+  'flex',
+  props.scroll === 'inner' ? 'h-svh overflow-hidden' : 'min-h-svh',
+  apply === 'scoped' ? '' : 'bg-default text-default',
+])
+
+const mainClass = computed(() => [
+  'min-w-0 flex-1',
+  props.scroll === 'inner' ? 'overflow-y-auto' : '',
+])
+</script>

package/components/TspMcpSettings.vue

@@ -0,0 +1,278 @@
+<!--
+  The MCP connection page for a service that exposes one, whole.
+
+    <TspMcpSettings
+      endpoint="https://todo.tsp.tools/mcp"
+      :api-key="key"
+      server-name="todo"
+      @regenerate="rotate"
+    />
+
+  WHY THIS IS A COMPONENT AND NOT A RECIPE. The page started in trips, was
+  generalised into the playground, copied into `scoped/`, and reached tsp-todo
+  through an agent that had never seen any of them — because the playground is
+  not in the published package. Four copies, three shapes. The layer's own two
+  demos had already drifted from each other: `scoped/` put Generic before
+  Claude and dropped a paragraph. Two copies in one repo could not hold still;
+  eight services will not (spec 07, ADR 017).
+
+  THE ORDER IS THE DESIGN. A service that exposes MCP has to tell a user four
+  things, and this is the order they need them in:
+
+    1. where the endpoint is and what their key is
+    2. that they are about to hand their data to someone else's model
+    3. how to paste it into Claude
+    4. how to paste it into anything else
+
+  The warning is not decoration and not optional by accident: it renders unless
+  a service passes :show-warning="false", so leaving it out is a decision
+  somebody made rather than a card they forgot to copy.
+
+  THE REDACTION IS LOAD-BEARING. The Claude snippet is shown with the key
+  replaced and copied with it filled in. Printing the real key in the code
+  block would defeat the masking one card above, and a service assembling the
+  JSON by hand is a service that can get that wrong — so the component builds
+  it.
+
+  The layer has no auth and no data: the endpoint, the key and the rotation are
+  the service's.
+-->
+<template>
+  <div
+    data-testid="tsp-mcp-settings"
+    class="flex flex-col gap-4"
+  >
+    <!-- Each block is wrapped rather than labelled on the card itself: a
+         data-testid on <TspSectionCard> falls through and REPLACES the card's
+         own, which the card's tests read. -->
+    <div
+      data-testid="tsp-mcp-block"
+      data-block="server"
+    >
+      <TspSectionCard
+        icon="i-tabler-server-2"
+        :title="l.serverTitle"
+      >
+        <div class="flex flex-col gap-4">
+          <TspCopyField
+            :label="l.endpoint"
+            :value="endpoint"
+            :copy-label="l.copy"
+            :copied-label="l.copied"
+          />
+          <TspCopyField
+            :label="l.apiKey"
+            :value="apiKey"
+            secret
+            :help="l.apiKeyHelp"
+            :reveal-label="l.reveal"
+            :hide-label="l.hide"
+            :copy-label="l.copy"
+            :copied-label="l.copied"
+          >
+            <template
+              v-if="canRegenerate"
+              #help
+            >
+              <button
+                type="button"
+                data-testid="tsp-mcp-regenerate"
+                class="inline-flex items-center gap-1.5 text-xs text-muted hover:text-highlighted"
+                @click="emit('regenerate')"
+              >
+                <UIcon name="i-tabler-refresh" />
+                {{ l.regenerate }}
+              </button>
+            </template>
+          </TspCopyField>
+        </div>
+      </TspSectionCard>
+    </div>
+
+    <div
+      v-if="showWarning"
+      data-testid="tsp-mcp-block"
+      data-block="warning"
+    >
+      <UAlert
+        data-testid="tsp-mcp-warning"
+        color="warning"
+        variant="subtle"
+        icon="i-tabler-info-circle"
+        :description="l.warning"
+      />
+    </div>
+
+    <div
+      data-testid="tsp-mcp-block"
+      data-block="claude"
+    >
+      <TspSectionCard
+        icon="i-tabler-sparkles"
+        :title="l.claudeTitle"
+      >
+        <p class="mb-3 text-sm text-muted">
+          {{ l.claudeHelp }}
+        </p>
+        <TspCodeBlock
+          :code="config(l.keyPlaceholder)"
+          :copy-value="config(apiKey)"
+          :copy-label="l.copyWithKey"
+          :copied-label="l.copiedWithKey"
+          :help="l.codeHelp"
+        />
+      </TspSectionCard>
+    </div>
+
+    <div
+      data-testid="tsp-mcp-block"
+      data-block="generic"
+    >
+      <TspSectionCard
+        icon="i-tabler-plug-connected"
+        :title="l.genericTitle"
+      >
+        <p class="mb-4 text-sm text-muted">
+          {{ l.genericHelp }}
+        </p>
+        <div class="flex flex-col gap-4">
+          <TspCopyField
+            :label="l.serverUrl"
+            :value="endpoint"
+            :copy-label="l.copy"
+            :copied-label="l.copied"
+          />
+          <!-- A second secret, and a much longer one than the bare key. The
+               fixed-length mask can only be proven with two of different
+               lengths to compare. -->
+          <TspCopyField
+            :label="l.authHeader"
+            :value="`Authorization: Bearer ${apiKey}`"
+            secret
+            :reveal-label="l.reveal"
+            :hide-label="l.hide"
+            :copy-label="l.copy"
+            :copied-label="l.copied"
+          />
+        </div>
+      </TspSectionCard>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+/**
+ * Every user-visible string in the page. One object rather than fifteen flat
+ * props: the layer's rule is that nothing is hardcoded beyond a default, not
+ * that each string must be its own attribute, and fifteen attributes is where
+ * the flat style stops paying. Partial — anything omitted keeps the English
+ * default below.
+ */
+export interface TspMcpLabels {
+  /** Title of the first card. */
+  serverTitle?: string
+  /** Label on the endpoint field. */
+  endpoint?: string
+  /** Label on the key field. */
+  apiKey?: string
+  /** The line under the key — say it is a password. */
+  apiKeyHelp?: string
+  /** The rotate-my-key control. Only rendered when `@regenerate` is bound. */
+  regenerate?: string
+  /** The third-party-processing warning. */
+  warning?: string
+  /** Title of the Claude card. */
+  claudeTitle?: string
+  /** How to install the snippet in Claude. */
+  claudeHelp?: string
+  /** Stands in for the key in the SHOWN snippet. The copy has the real one. */
+  keyPlaceholder?: string
+  /** Snippet copy button at rest. */
+  copyWithKey?: string
+  /** Snippet copy button just after a copy. */
+  copiedWithKey?: string
+  /** The line under the snippet, explaining the placeholder. */
+  codeHelp?: string
+  /** Title of the any-other-client card. */
+  genericTitle?: string
+  /** What to do with the two values below it. */
+  genericHelp?: string
+  /** Label on the server-URL field. */
+  serverUrl?: string
+  /** Label on the Authorization-header field. */
+  authHeader?: string
+  /** Accessible name for the eye while a secret is hidden. */
+  reveal?: string
+  /** Accessible name for it while the secret is shown. */
+  hide?: string
+  /** Accessible name for every field's copy button at rest. */
+  copy?: string
+  /** And just after a successful copy. */
+  copied?: string
+}
+
+const props = withDefaults(defineProps<{
+  /** The MCP endpoint URL. Shown, copied, and written into the config snippet. */
+  endpoint: string
+  /** The user's key. Never rendered while masked — only the copy carries it. */
+  apiKey: string
+  /** Key under `mcpServers` in the snippet. Use the service's short name. */
+  serverName?: string
+  /** The third-party-processing warning. On unless a service decides otherwise. */
+  showWarning?: boolean
+  /** Overrides for any visible string. Partial; English defaults for the rest. */
+  labels?: TspMcpLabels
+}>(), {
+  serverName: 'tsp',
+  showWarning: true,
+  labels: () => ({}),
+})
+
+const emit = defineEmits<{
+  /** The user asked for a new key. Rotating it is the service's job. */
+  regenerate: []
+}>()
+
+const DEFAULTS: Required<TspMcpLabels> = {
+  serverTitle: 'MCP Server',
+  endpoint: 'Endpoint',
+  apiKey: 'API key',
+  apiKeyHelp: 'Treat this key like a password — anyone with it can access your data.',
+  regenerate: 'Regenerate',
+  warning: 'Anything you send to your connected AI assistant is processed by that assistant\'s AI provider (e.g. Anthropic), under your own agreement with them — not by this service.',
+  claudeTitle: 'Claude',
+  claudeHelp: 'Add this to your Claude MCP configuration (Settings → Connectors, or claude_desktop_config.json), then restart Claude.',
+  keyPlaceholder: '<your API key>',
+  copyWithKey: 'Copy with API key',
+  copiedWithKey: 'Copied with key',
+  codeHelp: 'The key above is hidden — “Copy with API key” copies the config with your real key filled in.',
+  genericTitle: 'Generic / OpenAI',
+  genericHelp: 'For any other MCP client, add a remote (streamable HTTP) server with these details:',
+  serverUrl: 'Server URL',
+  authHeader: 'Auth header',
+  reveal: 'Show',
+  hide: 'Hide',
+  copy: 'Copy',
+  copied: 'Copied',
+}
+
+const l = computed<Required<TspMcpLabels>>(() => ({ ...DEFAULTS, ...props.labels }))
+
+// Built here, not by the caller. It is the same JSON for every service bar the
+// name and the URL, and JSON.stringify escapes what hand-written template
+// literals do not.
+const config = (key: string) => JSON.stringify({
+  mcpServers: {
+    [props.serverName]: {
+      url: props.endpoint,
+      headers: { Authorization: `Bearer ${key}` },
+    },
+  },
+}, null, 2)
+
+// A regenerate control with nothing behind it is a dead link, so it appears
+// only when the service actually listens. `defineEmits` strips the handler out
+// of `useAttrs`, so the vnode is where it can still be seen.
+const instance = getCurrentInstance()
+const canRegenerate = computed(() => !!instance?.vnode.props?.onRegenerate)
+</script>

package/components/TspPageHeader.vue

@@ -0,0 +1,53 @@
+<!--
+  The page title, and optionally the line under it.
+
+    <TspPageHeader title="Settings" description="AI client (MCP) connection." />
+
+  The smallest component in the layer and the one that stops the most drift.
+  Every page in every service opens with this block, and until now it was
+  twelve hand-written copies across the two demo apps alone — with three
+  different bottom margins between them. Nothing in `design-system.md` ever
+  stated the scale, so a consuming service had nothing to copy and guessed:
+  tsp-todo shipped `text-[28px]` under a correctly-used TspUserCard (spec 07).
+
+  THE SCALE IS FIXED HERE. `text-2xl` (24px), bold, `text-highlighted`. A
+  service that wants a different size on one page is a service whose pages no
+  longer match the others', which is the entire thing the layer exists to stop.
+
+  Spacing belongs to the component, not the caller: the gap below a title with
+  a lede is not the gap below a bare title, and leaving that to each page is
+  how three margins happened.
+
+  No slots. A slot over the title invites exactly the restyling this prevents.
+-->
+<template>
+  <header
+    data-testid="tsp-page-header"
+    :class="description ? 'mb-8' : 'mb-6'"
+  >
+    <h1
+      data-testid="tsp-page-header-title"
+      class="text-2xl font-bold text-highlighted"
+    >
+      {{ title }}
+    </h1>
+    <!-- Gated, not just empty: an unconditional <p> keeps its margin and
+         pushes the page's first card down by a line that is not there. -->
+    <p
+      v-if="description"
+      data-testid="tsp-page-header-description"
+      class="mt-2 max-w-2xl text-muted"
+    >
+      {{ description }}
+    </p>
+  </header>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  /** The page title. Rendered as the page's one `<h1>`. */
+  title: string
+  /** One line under the title. Capped at `max-w-2xl` — it is prose, the page is not. */
+  description?: string
+}>()
+</script>

package/docs/api.md

@@ -5,13 +5,43 @@
 drift from the components. For what each component is *for*, and the rules that govern
 it, read [`design-system.md`](design-system.md) — this file is the signature only.
 
-28 components · 116 props · 4 composables.
+32 components · 137 props · 4 composables.
 
 Every component is auto-imported; nothing needs an explicit import in a consuming app.
 A prop marked required has no default and the component will not render correctly without it.
 
 ---
 
+## TspAccountPage
+
+A service's account page, whole.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `name` | `string` | **required** | Display name. |
+| `title` | `string` | `'Account'` | The page title. |
+| `description` | `string` | `undefined` | One line under the title. Omit for none. |
+| `accountLabel` | `string` | `undefined` | Which account this is — shown under the name. |
+| `accountId` | `string` | `undefined` | The account id. Omit to hide the whole id block. |
+| `idLabel` | `string` | `undefined` | Label over the account id. |
+| `manageLink` | `string` | `undefined` | Where “manage account” goes. Omit to hide the link. |
+| `manageLabel` | `string` | `undefined` | Text of the manage-account link. |
+| `revealLabel` | `string` | `undefined` | Accessible name for the eye while the id is hidden. |
+| `hideLabel` | `string` | `undefined` | Accessible name for it while the id is shown. |
+
+## TspAppShell
+
+The logged-in frame: root, sidebar, content column, mobile top bar, measure.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `appName` | `string` | `undefined` | The service's name. Renders the top bar's wordmark — override with `#top-brand`. |
+| `containerWidth` | `'app' \| 'site'` | `'app'` | Forwarded to `TspContainer`: `app` (1152px) or `site` (1240px). |
+| `scroll` | `'page' \| 'inner'` | `'page'` | `page` scrolls the document and leaves the sidebar sticky — the model this layer documents and the one the mobile drawer was built against. `inner` pins the frame to the viewport and scrolls `<main>` instead, which is what trips, gage and pogo run today; it is a real choice for a dense table view, so adopting this shell is not forced to be a redesign as well. |
+| `menuLabel` | `string` | `undefined` | Accessible name for the mobile burger. Forwarded to `TspTopBar`. |
+
+**Slots** — default · `#brand` · `#footer` · `#nav` · `#top-brand`
+
 ## TspBanner
 
 A dismissible strip across the top of the content area. Its first job is the release announcement the tsp-release skill's `showBanner` flag turns on, but nothing here is release-specific: it is a banner.
@@ -111,7 +141,46 @@ DE/EN segmented control — the component gage, trips, pogo and tsp-tools each b
 | `groupLabel` | `string` | `'Language'` | aria-label for the group. |
 | `labels` | `Record<string, string>` | `() => ({ de: 'German', en: 'English' })` | Accessible name per code (aria-label + title). Falls back to the code. |
 
-**Emits** — `'update:modelValue': [code: string]`
+**Emits** — `update:modelValue: [code: string]`
+
+## TspMcpSettings
+
+The MCP connection page for a service that exposes one, whole.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `endpoint` | `string` | **required** | The MCP endpoint URL. Shown, copied, and written into the config snippet. |
+| `apiKey` | `string` | **required** | The user's key. Never rendered while masked — only the copy carries it. |
+| `serverName` | `string` | `'tsp'` | Key under `mcpServers` in the snippet. Use the service's short name. |
+| `showWarning` | `boolean` | `true` | The third-party-processing warning. On unless a service decides otherwise. |
+| `labels` | `TspMcpLabels` | `() => ({})` | Overrides for any visible string. Partial; English defaults for the rest. |
+
+**Emits** — `regenerate: []` — The user asked for a new key. Rotating it is the service's job.
+
+**`TspMcpLabels`**
+
+| Field | Type | |
+|---|---|---|
+| `serverTitle?` | `string` | Title of the first card. |
+| `endpoint?` | `string` | Label on the endpoint field. |
+| `apiKey?` | `string` | Label on the key field. |
+| `apiKeyHelp?` | `string` | The line under the key — say it is a password. |
+| `regenerate?` | `string` | The rotate-my-key control. Only rendered when `@regenerate` is bound. |
+| `warning?` | `string` | The third-party-processing warning. |
+| `claudeTitle?` | `string` | Title of the Claude card. |
+| `claudeHelp?` | `string` | How to install the snippet in Claude. |
+| `keyPlaceholder?` | `string` | Stands in for the key in the SHOWN snippet. The copy has the real one. |
+| `copyWithKey?` | `string` | Snippet copy button at rest. |
+| `copiedWithKey?` | `string` | Snippet copy button just after a copy. |
+| `codeHelp?` | `string` | The line under the snippet, explaining the placeholder. |
+| `genericTitle?` | `string` | Title of the any-other-client card. |
+| `genericHelp?` | `string` | What to do with the two values below it. |
+| `serverUrl?` | `string` | Label on the server-URL field. |
+| `authHeader?` | `string` | Label on the Authorization-header field. |
+| `reveal?` | `string` | Accessible name for the eye while a secret is hidden. |
+| `hide?` | `string` | Accessible name for it while the secret is shown. |
+| `copy?` | `string` | Accessible name for every field's copy button at rest. |
+| `copied?` | `string` | And just after a successful copy. |
 
 ## TspNavBadge
 
@@ -179,6 +248,15 @@ A child row inside a TspNavGroup. Carries its own icon, in its own indented colu
 
 **Slots** — default
 
+## TspPageHeader
+
+The page title, and optionally the line under it.
+
+| Prop | Type | Default | |
+|---|---|---|---|
+| `title` | `string` | **required** | The page title. Rendered as the page's one `<h1>`. |
+| `description` | `string` | `undefined` | One line under the title. Capped at `max-w-2xl` — it is prose, the page is not. |
+
 ## TspPageTabs
 
 Tabs across the top of an area, above the page title — the shape trips uses for Settings / MCP Server.
@@ -199,6 +277,28 @@ Release notes for one or more versions — the overview the tsp-release skill wr
 | `beforeLabel` | `string` | `'Before'` | Caption on the left side of a before/after pair. |
 | `afterLabel` | `string` | `'After'` | Caption on its right side. |
 
+**`TspReleaseItemObject`**
+
+| Field | Type | |
+|---|---|---|
+| `text` | `string` |  |
+| `compare?` | `{ before: string, after: string }` |  |
+| `beforeImage?` | `string` |  |
+| `afterImage?` | `string` |  |
+
+**`TspRelease`**
+
+| Field | Type | |
+|---|---|---|
+| `version` | `string` |  |
+| `date?` | `string` |  |
+| `showBanner?` | `boolean` |  |
+| `showPopup?` | `boolean` |  |
+| `important?` | `TspReleaseItem[]` |  |
+| `other?` | `TspReleaseItem[]` |  |
+
+**`TspReleaseItem`** — `string \| TspReleaseItemObject`
+
 ## TspSectionCard
 
 A titled content card: icon + title in a header row, content below.
@@ -261,7 +361,7 @@ The sidebar bottom block, in the order spec 03 fixes:
 
 **Slots** — `#logout` · `#user`
 
-**Emits** — `'update:modelValue': [code: string]`
+**Emits** — `update:modelValue: [code: string]`
 
 ## TspSiteFooter
 

package/docs/design-system.md

@@ -118,6 +118,25 @@ global and would reach a scoped consumer's unthemed area. There is no `TspCard`.
 Nunito everywhere; Space Grotesk for the wordmark only (`.tsp-wordmark` / `<TspWordmark>`).
 Both from Google via `@nuxt/fonts`, which ships with Nuxt UI.
 
+### Typography
+
+The scale a page is built from. It went unwritten until 0.4.0 and a consuming service duly
+guessed `text-[28px]` for its page title — so it is stated here and, more usefully, **carried by
+`<TspPageHeader>`**, which is what a page should use rather than reproducing the classes.
+
+| Role | Classes |
+|---|---|
+| Page title (`h1`) | `text-2xl font-bold text-highlighted` |
+| Page lede | `text-muted max-w-2xl` |
+| Card title (`h2`, inside `TspSectionCard`) | `text-sm font-bold text-highlighted` |
+| Section label above a group | `text-xs font-bold uppercase tracking-wide text-muted` |
+| Field label | `text-xs font-bold text-toned` |
+| Body | inherited — `text-default`, or `text-muted` for supporting prose |
+
+**Cap prose on the paragraph, not the page** (`max-w-2xl`), for the reason under *Layout*.
+There is no `h1` larger than `text-2xl` in an app shell: the marketing surface has its own
+hero scale and is not this.
+
 ### Icons
 
 Tabler, `i-tabler-*`. Install `@iconify-json/tabler` for offline resolution. **One icon family
@@ -157,6 +176,15 @@ is centred, so without it the whole page slides sideways by half a scrollbar the
 is tall enough to scroll. Browsers with overlay scrollbars are unaffected, and a consumer's
 unthemed public pages are deliberately not touched.
 
+**The frame is `TspAppShell`, not fifteen lines in your layout.** It renders the root, the
+sidebar, the content column, the mobile top bar and the container, and it derives its root
+element — plain `div` globally, `TspThemeProvider` when scoped — from `apply` rather than from a
+prop. Before it existed, all eight services had written that frame out by hand and disagreed
+three ways nobody had chosen: two scroll models, three viewport units for one intent
+(`min-h-svh` vs `h-svh` vs `min-h-screen`, which is `100vh` and breaks under a mobile toolbar),
+and `bg-default` on the content column or not. `scroll="inner"` keeps the pinned-frame model for
+a dense table view; the default scrolls the page and leaves the sidebar sticky.
+
 **Responsive.** `sm` (640px) is the shell's breakpoint. At and above it the sidebar is a column,
 sticky at viewport height. Below it the sidebar becomes an off-canvas drawer and `<TspTopBar>`
 appears.
@@ -172,7 +200,8 @@ has — a slot invites each app to restyle its copy, which is the drift the laye
 
 | Component | Purpose |
 |---|---|
-| `TspSidebar` | The frame. Slots `#brand` `#nav` `#footer`. Sticky on desktop, drawer below `sm`. |
+| `TspAppShell` | **The frame, whole** — root, sidebar, content column, top bar, container. Start here. |
+| `TspSidebar` | The sidebar alone. Slots `#brand` `#nav` `#footer`. Sticky on desktop, drawer below `sm`. |
 | `TspTopBar` | Mobile only: burger (left) · brand · page title. |
 | `TspSidebarFooter` | User → Settings → Logout → divider → theme + language → meta icons + version → attribution. |
 | `TspFooterRow` | One footer row; `to` / `href` / neither (button). |
@@ -194,6 +223,35 @@ has — a slot invites each app to restyle its copy, which is the drift the laye
 | `TspSiteHeader` | Slots `#brand` `#nav` `#actions`; `sticky`, and `bare` for a landing page (no bar). |
 | `TspSiteFooter` | Compact centred link row; `tool-of` adds the attribution. |
 
+### Pages
+
+Three components are whole pages, or the top of one. They exist because the layer being the
+source of the *shell* was never enough: a service still had to assemble each page from parts,
+and the parts went together differently every time. The MCP page reached four copies in three
+shapes — including two inside this repo that had drifted apart from each other — before it
+became a component (spec 07).
+
+| Component | Purpose |
+|---|---|
+| `TspPageHeader` | The page title and its lede. Every page starts with it; the scale above is its. |
+| `TspAccountPage` | The standalone account page — heading + `TspUserCard`. |
+| `TspMcpSettings` | The whole MCP connection page: server, the AI-processing warning, Claude, generic. |
+
+**Use the page, not the recipe.** If you find yourself rebuilding one of these out of
+`TspSectionCard` and `TspCopyField`, that is the drift these exist to stop — and if the page
+genuinely cannot do what your service needs, the fix belongs here, not in your app (ADR 017).
+
+Two rules they encode, worth knowing before overriding either:
+
+- **`TspMcpSettings` renders the third-party-processing warning by default.** The user is about
+  to hand their data to someone else's model. `:show-warning="false"` exists, so leaving it out
+  is a decision somebody made rather than a card nobody copied.
+- **The Claude snippet is redacted on screen and complete on copy.** Printing the real key
+  there would defeat the masking one card above it.
+
+Inside a tabbed settings area the heading belongs to the parent route — use `TspPageHeader`
+there and `TspUserCard` directly, rather than `TspAccountPage` under the tabs.
+
 ### Content
 
 | Component | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thespielplatz/tsp-tools-theme",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "tsp.tools design-system theme as a Nuxt layer (Nuxt UI v4 + Tailwind v4): amber-on-anthracite tokens (light + dark), Nunito/Space Grotesk fonts, per-area colour mode, and the shared app shell. Use globally via `extends`, or scoped to a sub-area.",
   "author": "inf0matics",
   "license": "MIT",