From cf8f328e852449c5d94766a7e1d69d5bc8fe2ed0 Mon Sep 17 00:00:00 2001
From: Maciej <7597086+mdanilowicz@users.noreply.github.com>
Date: Mon, 1 Jun 2026 14:36:00 +0200
Subject: [PATCH 1/3] feat: init Frontends recipes

---
 apps/docs/.vitepress/sidebar.ts               |  17 ++
 apps/docs/src/components/LoginFlowDiagram.vue | 268 ++++++++++++++++++
 .../src/frontends-recipes/account/index.md    |  11 +
 .../src/frontends-recipes/account/login.md    | 175 ++++++++++++
 apps/docs/src/frontends-recipes/index.md      |  15 +
 5 files changed, 486 insertions(+)
 create mode 100644 apps/docs/src/components/LoginFlowDiagram.vue
 create mode 100644 apps/docs/src/frontends-recipes/account/index.md
 create mode 100644 apps/docs/src/frontends-recipes/account/login.md
 create mode 100644 apps/docs/src/frontends-recipes/index.md

diff --git a/apps/docs/.vitepress/sidebar.ts b/apps/docs/.vitepress/sidebar.ts
index c11bb148e..48d0b4798 100644
--- a/apps/docs/.vitepress/sidebar.ts
+++ b/apps/docs/.vitepress/sidebar.ts
@@ -240,6 +240,23 @@ export const sidebar = [
       },
     ],
   },
+  {
+    text: "FRONTENDS RECIPES",
+    link: "/frontends-recipes/",
+    items: [
+      {
+        text: "Account",
+        link: "/frontends-recipes/account/",
+        collapsed: true,
+        items: [
+          {
+            text: "Login",
+            link: "/frontends-recipes/account/login.html",
+          },
+        ],
+      },
+    ],
+  },
   {
     text: "BEST PRACTICES",
     link: "/best-practices/",
diff --git a/apps/docs/src/components/LoginFlowDiagram.vue b/apps/docs/src/components/LoginFlowDiagram.vue
new file mode 100644
index 000000000..9c3a2fa13
--- /dev/null
+++ b/apps/docs/src/components/LoginFlowDiagram.vue
@@ -0,0 +1,268 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+
+const steps = [
+  {
+    title: "UI",
+    action: "Submit credentials",
+    detail:
+      "The login form collects username and password, then calls the composable. The component owns loading and form error state only.",
+    code: "submit() -> login(credentials)",
+    state: "local form state",
+  },
+  {
+    title: "Composable",
+    action: "Run login workflow",
+    detail:
+      "useUser owns the Shopware-specific workflow. It sends credentials first, then refreshes context and cart data.",
+    code: "useUser().login(credentials)",
+    state: "customer workflow",
+  },
+  {
+    title: "Store API",
+    action: "Authenticate customer",
+    detail:
+      "The API client invokes the generated operation for POST /account/login. This step validates credentials.",
+    code: 'apiClient.invoke("loginCustomer post /account/login")',
+    state: "sw-context-token",
+  },
+  {
+    title: "Context",
+    action: "Refresh session",
+    detail:
+      "The session context is fetched again so customer, customer group, currency, rules, and other context-dependent values are current.",
+    code: 'apiClient.invoke("readContext get /context")',
+    state: "user, isLoggedIn, sales channel context",
+  },
+  {
+    title: "Cart",
+    action: "Reload cart",
+    detail:
+      "The cart is refreshed because prices, promotions, and line items can depend on the authenticated customer context.",
+    code: "refreshCart()",
+    state: "cart, prices, promotions",
+  },
+  {
+    title: "UI",
+    action: "Render new state",
+    detail:
+      "The UI reads user, isLoggedIn, and cart data from composables instead of keeping its own copy.",
+    code: "user + isLoggedIn + cart",
+    state: "reactive UI",
+  },
+];
+
+const activeStepIndex = ref(0);
+const activeStep = computed(() => steps[activeStepIndex.value]);
+</script>
+
+<template>
+  <section class="login-flow" aria-label="Login flow diagram">
+    <div class="login-flow__track">
+      <button
+        v-for="(step, index) in steps"
+        :key="`${step.title}-${index}`"
+        type="button"
+        class="login-flow__step"
+        :class="{ 'login-flow__step--active': activeStepIndex === index }"
+        :aria-pressed="activeStepIndex === index"
+        @click="activeStepIndex = index"
+      >
+        <span class="login-flow__number">{{ index + 1 }}</span>
+        <span class="login-flow__title">{{ step.title }}</span>
+        <span class="login-flow__action">{{ step.action }}</span>
+      </button>
+    </div>
+
+    <div class="login-flow__details">
+      <div>
+        <p class="login-flow__eyebrow">Step {{ activeStepIndex + 1 }}</p>
+        <h3>{{ activeStep.title }}: {{ activeStep.action }}</h3>
+        <p>{{ activeStep.detail }}</p>
+      </div>
+
+      <dl class="login-flow__facts">
+        <div>
+          <dt>Code</dt>
+          <dd>
+            <code>{{ activeStep.code }}</code>
+          </dd>
+        </div>
+        <div>
+          <dt>State</dt>
+          <dd>{{ activeStep.state }}</dd>
+        </div>
+      </dl>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.login-flow {
+  margin: 24px 0;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--vp-c-bg-soft);
+}
+
+.login-flow__track {
+  display: grid;
+  grid-template-columns: repeat(6, minmax(0, 1fr));
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.login-flow__step {
+  min-height: 128px;
+  display: grid;
+  grid-template-rows: auto auto 1fr;
+  gap: 8px;
+  align-content: start;
+  padding: 16px 12px;
+  border: 0;
+  border-right: 1px solid var(--vp-c-divider);
+  background: transparent;
+  color: var(--vp-c-text-2);
+  text-align: left;
+  cursor: pointer;
+}
+
+.login-flow__step:last-child {
+  border-right: 0;
+}
+
+.login-flow__step:hover,
+.login-flow__step:focus-visible {
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+}
+
+.login-flow__step:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: -2px;
+}
+
+.login-flow__step--active {
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  box-shadow: inset 0 -3px 0 var(--vp-c-brand-1);
+}
+
+.login-flow__number {
+  width: 28px;
+  height: 28px;
+  display: inline-grid;
+  place-items: center;
+  border-radius: 999px;
+  background: var(--vp-c-default-soft);
+  color: var(--vp-c-text-1);
+  font-weight: 700;
+  font-size: 13px;
+}
+
+.login-flow__step--active .login-flow__number {
+  background: var(--vp-c-brand-soft);
+  color: var(--vp-c-brand-1);
+}
+
+.login-flow__title {
+  font-weight: 700;
+  font-size: 14px;
+}
+
+.login-flow__action {
+  font-size: 13px;
+  line-height: 1.4;
+}
+
+.login-flow__details {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(260px, 0.6fr);
+  gap: 24px;
+  padding: 24px;
+  background: var(--vp-c-bg);
+}
+
+.login-flow__details h3 {
+  margin: 0 0 8px;
+  font-size: 20px;
+}
+
+.login-flow__details p {
+  margin: 0;
+}
+
+.login-flow__eyebrow {
+  margin-bottom: 8px;
+  color: var(--vp-c-brand-1);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.login-flow__facts {
+  display: grid;
+  gap: 12px;
+  margin: 0;
+}
+
+.login-flow__facts div {
+  padding: 12px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg-soft);
+}
+
+.login-flow__facts dt {
+  margin-bottom: 6px;
+  color: var(--vp-c-text-2);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.login-flow__facts dd {
+  margin: 0;
+  font-size: 13px;
+}
+
+.login-flow__facts code {
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
+@media (max-width: 960px) {
+  .login-flow__track {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+
+  .login-flow__step:nth-child(3) {
+    border-right: 0;
+  }
+
+  .login-flow__step:nth-child(n + 4) {
+    border-top: 1px solid var(--vp-c-divider);
+  }
+}
+
+@media (max-width: 640px) {
+  .login-flow__track,
+  .login-flow__details {
+    grid-template-columns: 1fr;
+  }
+
+  .login-flow__step {
+    min-height: auto;
+    border-right: 0;
+    border-bottom: 1px solid var(--vp-c-divider);
+  }
+
+  .login-flow__step:nth-child(n + 4) {
+    border-top: 0;
+  }
+
+  .login-flow__details {
+    padding: 18px;
+  }
+}
+</style>
diff --git a/apps/docs/src/frontends-recipes/account/index.md b/apps/docs/src/frontends-recipes/account/index.md
new file mode 100644
index 000000000..dfa745deb
--- /dev/null
+++ b/apps/docs/src/frontends-recipes/account/index.md
@@ -0,0 +1,11 @@
+---
+nav:
+  title: Account
+  position: 10
+---
+
+# Account
+
+Recipes for customer session and account flows.
+
+<PageRef page="login.html" title="Login" sub="Understand the customer login flow, Store API operations, generated types, context refresh, cart refresh, and error handling." />
diff --git a/apps/docs/src/frontends-recipes/account/login.md b/apps/docs/src/frontends-recipes/account/login.md
new file mode 100644
index 000000000..98bd8e0a8
--- /dev/null
+++ b/apps/docs/src/frontends-recipes/account/login.md
@@ -0,0 +1,175 @@
+---
+nav:
+  position: 10
+recipe:
+  area: account
+  status: stable
+  frameworks:
+    - vue
+  composables:
+    - useUser
+    - useSessionContext
+    - useCart
+  helpers: []
+  operations:
+    - loginCustomer post /account/login
+    - readContext get /context
+    - logoutCustomer post /account/logout
+  schemas:
+    - Customer
+    - SalesChannelContext
+---
+
+<script setup>
+import LoginFlowDiagram from "../../components/LoginFlowDiagram.vue";
+</script>
+
+# Login
+
+## Goal
+
+Build a customer login flow and understand what happens after credentials are submitted. The important part is not the form itself, but how Shopware Frontends updates the customer session, context, and cart after the Store API accepts the login.
+
+## Shopware Flow
+
+Login is a small form action, but it changes the whole sales channel session. The important part is that `POST /account/login` only authenticates the customer. The UI becomes reliable after the session context and cart are refreshed.
+
+<LoginFlowDiagram />
+
+Read the diagram from left to right:
+
+1. Customer submits the login form.
+2. `useUser().login()` sends credentials to `POST /account/login`.
+3. The API client keeps using the current `sw-context-token` and reacts to context-token changes from the API response.
+4. `useUser` refreshes the sales channel context with `GET /context`.
+5. `useUser` refreshes the cart so it matches the customer session.
+6. The UI reads `user`, `isLoggedIn`, and cart state from composables instead of keeping its own copy.
+
+You usually do not need to call `readContext get /context` manually after login, because `useUser` calls `refreshSessionContext()` internally.
+
+## Request Flow
+
+| Step | Code | Store API | Type |
+|---|---|---|---|
+| Submit credentials | `login(credentials)` | `POST /account/login` | `operations["loginCustomer post /account/login"]["body"]` |
+| Refresh session context | `refreshSessionContext()` | `GET /context` | `operations["readContext get /context"]["response"]` |
+| Logout customer | `logout()` | `POST /account/logout` | `operations["logoutCustomer post /account/logout"]["response"]` |
+
+## Composables
+
+- `useUser`: exposes `login`, `logout`, `user`, `isLoggedIn`, and related customer state.
+- `useSessionContext`: refreshes the sales channel context after the customer session changes.
+- `useCart`: refreshes the cart after login or logout so line items and prices match the current customer context.
+
+## Types
+
+Use generated Store API types when you need to type credentials, responses, or lower-level API client calls:
+
+```ts
+import type { Schemas, operations } from "#shopware";
+
+type LoginBody = operations["loginCustomer post /account/login"]["body"];
+type LoginResponse =
+  operations["loginCustomer post /account/login"]["response"];
+type SessionContext = operations["readContext get /context"]["response"];
+type Customer = Schemas["Customer"];
+```
+
+## Minimal Vue Example
+
+```vue
+<script setup lang="ts">
+import type { operations } from "#shopware";
+
+const { login, logout, isLoggedIn, user } = useUser();
+
+const credentials = reactive<
+  operations["loginCustomer post /account/login"]["body"]
+>({
+  username: "",
+  password: "",
+});
+
+const isSubmitting = ref(false);
+const loginError = ref("");
+
+const submit = async () => {
+  loginError.value = "";
+  isSubmitting.value = true;
+
+  try {
+    await login(credentials);
+  } catch {
+    loginError.value = "The email or password is invalid.";
+  } finally {
+    isSubmitting.value = false;
+  }
+};
+</script>
+
+<template>
+  <form v-if="!isLoggedIn" @submit.prevent="submit">
+    <label>
+      Email
+      <input v-model="credentials.username" type="email" autocomplete="email" />
+    </label>
+
+    <label>
+      Password
+      <input
+        v-model="credentials.password"
+        type="password"
+        autocomplete="current-password"
+      />
+    </label>
+
+    <p v-if="loginError">{{ loginError }}</p>
+
+    <button type="submit" :disabled="isSubmitting">
+      {{ isSubmitting ? "Signing in..." : "Sign in" }}
+    </button>
+  </form>
+
+  <div v-else>
+    <p>Signed in as {{ user?.firstName || user?.email }}</p>
+    <button type="button" @click="logout()">Sign out</button>
+  </div>
+</template>
+```
+
+## State And Session
+
+The Store API identifies the current sales channel session with the `sw-context-token` header. A successful login can affect the current customer context and the cart associated with that context.
+
+After `POST /account/login`, `useUser().login()` calls `refreshSessionContext()`. That request uses `GET /context` and updates the reactive session context. The `user` and `isLoggedIn` values then reflect the customer from the refreshed context.
+
+`useUser().login()` also calls `refreshCart()`. This matters because cart prices, promotions, customer-specific rules, and line items can depend on the logged-in customer context.
+
+## Edge Cases
+
+- Invalid credentials cause the API client call to throw. Map this error to the login form instead of assuming the composable stores form errors.
+- If the session context is missing or stale, login can fail before customer state is refreshed.
+- Customer-specific prices, promotions, or rules may change after login because the cart is refreshed in the new context.
+- A successful API response does not mean old local UI state is still valid. Read `user`, `isLoggedIn`, and cart data from the composables after the login promise resolves.
+
+## Common Mistakes
+
+- Do not keep a separate local `isLoggedIn` flag. Use `useUser().isLoggedIn`.
+- Do not skip the cart refresh after login when implementing a custom flow with `apiClient.invoke` directly.
+- Do not assume the old cart totals are still correct after the customer session changes.
+- Do not expose raw API error details directly in the UI.
+
+## Testing Checklist
+
+- Successful login calls `loginCustomer post /account/login`.
+- Successful login refreshes the session context and updates `isLoggedIn`.
+- Successful login refreshes the cart.
+- Invalid credentials show a form-level error and keep the user logged out.
+- Logout calls `logoutCustomer post /account/logout`, refreshes context, and refreshes cart.
+
+## Related Links
+
+- [Login form page element](../../getting-started/page-elements/login-form.html)
+- [Composables reference](../../packages/composables/)
+- [API client package](../../packages/api-client.html)
+- [Cart documentation](../../getting-started/e-commerce/cart.html)
diff --git a/apps/docs/src/frontends-recipes/index.md b/apps/docs/src/frontends-recipes/index.md
new file mode 100644
index 000000000..769f8ad3b
--- /dev/null
+++ b/apps/docs/src/frontends-recipes/index.md
@@ -0,0 +1,15 @@
+---
+nav:
+  title: Frontends Recipes
+  position: 115
+---
+
+# Frontends Recipes
+
+Frontends Recipes explain how common Shopware Frontends features work end-to-end. Each recipe connects a UI action with composables, API client calls, Store API endpoints, generated types, session state, and production concerns.
+
+These pages are written for frontend developers who want to understand the Shopware flow behind real Frontends features. They are not generic Vue tutorials.
+
+## Account
+
+<PageRef page="account/" title="Account" sub="Customer session flows such as login, logout, registration, and account state." />

From 2cd1672127beb6f85c5b19491648d18101aaf0b3 Mon Sep 17 00:00:00 2001
From: Maciej <7597086+mdanilowicz@users.noreply.github.com>
Date: Mon, 1 Jun 2026 14:51:04 +0200
Subject: [PATCH 2/3] feat: add vue flow

---
 apps/docs/package.json                        |   1 +
 .../src/components/LoginVueFlowDiagram.vue    | 313 ++++++++++++++++++
 .../src/frontends-recipes/account/login.md    |   5 +
 pnpm-lock.yaml                                |  93 ++++++
 4 files changed, 412 insertions(+)
 create mode 100644 apps/docs/src/components/LoginVueFlowDiagram.vue

diff --git a/apps/docs/package.json b/apps/docs/package.json
index 75b70394c..510daa101 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -14,6 +14,7 @@
     "@shopware/composables": "workspace:*",
     "@shopware/helpers": "workspace:*",
     "@shopware/api-client": "workspace:*",
+    "@vue-flow/core": "^1.48.2",
     "flexsearch": "0.8.212",
     "markdown-it": "14.1.1",
     "vitepress": "1.6.4",
diff --git a/apps/docs/src/components/LoginVueFlowDiagram.vue b/apps/docs/src/components/LoginVueFlowDiagram.vue
new file mode 100644
index 000000000..2c99ef591
--- /dev/null
+++ b/apps/docs/src/components/LoginVueFlowDiagram.vue
@@ -0,0 +1,313 @@
+<script setup lang="ts">
+import { VueFlow } from "@vue-flow/core";
+import "@vue-flow/core/dist/style.css";
+import "@vue-flow/core/dist/theme-default.css";
+import { computed, ref } from "vue";
+
+const nodes = ref([
+  {
+    id: "ui-submit",
+    label: "Login form",
+    position: { x: 0, y: 80 },
+    class: "login-vue-flow__node login-vue-flow__node--ui",
+    data: {
+      title: "UI: submit credentials",
+      description:
+        "The component collects username and password, then calls the composable. Loading and form errors stay local to the UI.",
+      code: "submit() -> login(credentials)",
+      state: "local form state",
+    },
+  },
+  {
+    id: "use-user",
+    label: "useUser().login()",
+    position: { x: 240, y: 80 },
+    class: "login-vue-flow__node login-vue-flow__node--composable",
+    data: {
+      title: "Composable: own the workflow",
+      description:
+        "useUser sends credentials to the Store API and then coordinates the context and cart refreshes.",
+      code: "useUser().login(credentials)",
+      state: "customer workflow",
+    },
+  },
+  {
+    id: "login-api",
+    label: "POST /account/login",
+    position: { x: 520, y: 0 },
+    class: "login-vue-flow__node login-vue-flow__node--api",
+    data: {
+      title: "Store API: authenticate",
+      description:
+        "The generated operation validates credentials and can affect the active sales channel session.",
+      code: "loginCustomer post /account/login",
+      state: "sw-context-token",
+    },
+  },
+  {
+    id: "context",
+    label: "GET /context",
+    position: { x: 520, y: 170 },
+    class: "login-vue-flow__node login-vue-flow__node--context",
+    data: {
+      title: "Context: refresh session",
+      description:
+        "The refreshed context provides the current customer, customer group, currency, rules, and other context-dependent values.",
+      code: "refreshSessionContext()",
+      state: "user, isLoggedIn, sales channel context",
+    },
+  },
+  {
+    id: "cart",
+    label: "refreshCart()",
+    position: { x: 800, y: 80 },
+    class: "login-vue-flow__node login-vue-flow__node--cart",
+    data: {
+      title: "Cart: reload customer-aware data",
+      description:
+        "Cart data is loaded again because prices, promotions, and line items can depend on the authenticated customer context.",
+      code: "refreshCart()",
+      state: "cart, prices, promotions",
+    },
+  },
+  {
+    id: "ui-reactive",
+    label: "Reactive UI",
+    position: { x: 1060, y: 80 },
+    class: "login-vue-flow__node login-vue-flow__node--ui",
+    data: {
+      title: "UI: render new state",
+      description:
+        "The page reads user, isLoggedIn, and cart data from composables instead of keeping a separate copy.",
+      code: "user + isLoggedIn + cart",
+      state: "reactive UI",
+    },
+  },
+]);
+
+const edges = ref([
+  {
+    id: "ui-to-composable",
+    source: "ui-submit",
+    target: "use-user",
+    animated: true,
+    label: "calls",
+  },
+  {
+    id: "composable-to-login",
+    source: "use-user",
+    target: "login-api",
+    animated: true,
+    label: "authenticates",
+  },
+  {
+    id: "login-to-context",
+    source: "login-api",
+    target: "context",
+    animated: true,
+    label: "then refreshes",
+  },
+  {
+    id: "context-to-cart",
+    source: "context",
+    target: "cart",
+    animated: true,
+    label: "then reloads",
+  },
+  {
+    id: "cart-to-ui",
+    source: "cart",
+    target: "ui-reactive",
+    animated: true,
+    label: "updates",
+  },
+]);
+
+const selectedNodeId = ref(nodes.value[0].id);
+const selectedNode = computed(
+  () =>
+    nodes.value.find((node) => node.id === selectedNodeId.value) ??
+    nodes.value[0],
+);
+
+function selectNode(event: { node: (typeof nodes.value)[number] }) {
+  selectedNodeId.value = event.node.id;
+}
+</script>
+
+<template>
+  <section class="login-vue-flow">
+    <div class="login-vue-flow__canvas" aria-label="Vue Flow login diagram">
+      <VueFlow
+        v-model:nodes="nodes"
+        v-model:edges="edges"
+        :fit-view-on-init="true"
+        :nodes-draggable="false"
+        :nodes-connectable="false"
+        :elements-selectable="true"
+        :pan-on-drag="true"
+        :zoom-on-scroll="false"
+        :zoom-on-double-click="false"
+        :min-zoom="0.55"
+        :max-zoom="1.2"
+        @node-click="selectNode"
+      />
+    </div>
+
+    <!-- <aside class="login-vue-flow__panel">
+      <p class="login-vue-flow__eyebrow">Vue Flow detail</p>
+      <h3>{{ selectedNode.data.title }}</h3>
+      <p>{{ selectedNode.data.description }}</p>
+      <dl>
+        <div>
+          <dt>Code</dt>
+          <dd>
+            <code>{{ selectedNode.data.code }}</code>
+          </dd>
+        </div>
+        <div>
+          <dt>State</dt>
+          <dd>{{ selectedNode.data.state }}</dd>
+        </div>
+      </dl>
+    </aside> -->
+  </section>
+</template>
+
+<style>
+.login-vue-flow .vue-flow__node.login-vue-flow__node {
+  width: 170px;
+  min-height: 72px;
+  display: grid;
+  place-items: center;
+  padding: 12px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  box-shadow: 0 10px 24px rgba(0, 0, 0, 0.08);
+  font-size: 13px;
+  font-weight: 700;
+  text-align: center;
+}
+
+.login-vue-flow .vue-flow__node.login-vue-flow__node.selected {
+  border-color: var(--vp-c-brand-1);
+  box-shadow:
+    0 0 0 3px var(--vp-c-brand-soft),
+    0 10px 24px rgba(0, 0, 0, 0.1);
+}
+
+.login-vue-flow .login-vue-flow__node--ui {
+  border-top: 4px solid #2563eb;
+}
+
+.login-vue-flow .login-vue-flow__node--composable {
+  border-top: 4px solid #7c3aed;
+}
+
+.login-vue-flow .login-vue-flow__node--api {
+  border-top: 4px solid #0891b2;
+}
+
+.login-vue-flow .login-vue-flow__node--context {
+  border-top: 4px solid #16a34a;
+}
+
+.login-vue-flow .login-vue-flow__node--cart {
+  border-top: 4px solid #ea580c;
+}
+
+.login-vue-flow .vue-flow__edge-path {
+  stroke: var(--vp-c-brand-1);
+  stroke-width: 2;
+}
+
+.login-vue-flow .vue-flow__edge-textbg {
+  fill: var(--vp-c-bg);
+}
+
+.login-vue-flow .vue-flow__edge-text {
+  fill: var(--vp-c-text-2);
+  font-size: 11px;
+  font-weight: 700;
+}
+</style>
+
+<style scoped>
+.login-vue-flow__canvas {
+  height: 360px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  overflow: hidden;
+  background:
+    linear-gradient(var(--vp-c-bg-soft), var(--vp-c-bg-soft)),
+    var(--vp-c-bg);
+}
+
+.login-vue-flow__panel {
+  min-height: 360px;
+  padding: 20px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg);
+}
+
+.login-vue-flow__panel h3 {
+  margin: 0 0 10px;
+  font-size: 20px;
+}
+
+.login-vue-flow__panel p {
+  margin: 0;
+}
+
+.login-vue-flow__eyebrow {
+  margin-bottom: 8px;
+  color: var(--vp-c-brand-1);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.login-vue-flow__panel dl {
+  display: grid;
+  gap: 12px;
+  margin: 18px 0 0;
+}
+
+.login-vue-flow__panel dl div {
+  padding: 12px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg-soft);
+}
+
+.login-vue-flow__panel dt {
+  margin-bottom: 6px;
+  color: var(--vp-c-text-2);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.login-vue-flow__panel dd {
+  margin: 0;
+  font-size: 13px;
+}
+
+.login-vue-flow__panel code {
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
+@media (max-width: 960px) {
+  .login-vue-flow {
+    grid-template-columns: 1fr;
+  }
+
+  .login-vue-flow__panel {
+    min-height: 0;
+  }
+}
+</style>
diff --git a/apps/docs/src/frontends-recipes/account/login.md b/apps/docs/src/frontends-recipes/account/login.md
index 98bd8e0a8..7b7f870ac 100644
--- a/apps/docs/src/frontends-recipes/account/login.md
+++ b/apps/docs/src/frontends-recipes/account/login.md
@@ -22,6 +22,7 @@ recipe:
 
 <script setup>
 import LoginFlowDiagram from "../../components/LoginFlowDiagram.vue";
+import LoginVueFlowDiagram from "../../components/LoginVueFlowDiagram.vue";
 </script>
 
 # Login
@@ -34,6 +35,10 @@ Build a customer login flow and understand what happens after credentials are su
 
 Login is a small form action, but it changes the whole sales channel session. The important part is that `POST /account/login` only authenticates the customer. The UI becomes reliable after the session context and cart are refreshed.
 
+<ClientOnly>
+  <LoginVueFlowDiagram />
+</ClientOnly>
+
 <LoginFlowDiagram />
 
 Read the diagram from left to right:
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b9375cee9..e12560cdb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -72,6 +72,9 @@ importers:
       '@shopware/helpers':
         specifier: workspace:*
         version: link:../../packages/helpers
+      '@vue-flow/core':
+        specifier: ^1.48.2
+        version: 1.48.2(vue@3.5.34(typescript@5.9.3))
       flexsearch:
         specifier: 0.8.212
         version: 0.8.212
@@ -6181,6 +6184,11 @@ packages:
   '@volar/typescript@2.4.28':
     resolution: {integrity: sha512-Ja6yvWrbis2QtN4ClAKreeUZPVYMARDYZl9LMEv1iQ1QdepB6wn0jTRxA9MftYmYa4DQ4k/DaSZpFPUfxl8giw==}
 
+  '@vue-flow/core@1.48.2':
+    resolution: {integrity: sha512-raxhgKWE+G/mcEvXJjGFUDYW9rAI3GOtiHR3ZkNpwBWuIaCC1EYiBmKGwJOoNzVFgwO7COgErnK7i08i287AFA==}
+    peerDependencies:
+      vue: ^3.3.0
+
   '@vue-macros/common@3.1.1':
     resolution: {integrity: sha512-afW2DMjgCBVs33mWRlz7YsGHzoEEupnl0DK5ZTKsgziAlLh5syc5m+GM7eqeYrgiQpwMaVxa1fk73caCvPxyAw==}
     engines: {node: '>=20.19.0'}
@@ -7284,6 +7292,44 @@ packages:
   csstype@3.2.3:
     resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
 
+  d3-color@3.1.0:
+    resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
+    engines: {node: '>=12'}
+
+  d3-dispatch@3.0.1:
+    resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
+    engines: {node: '>=12'}
+
+  d3-drag@3.0.0:
+    resolution: {integrity: sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==}
+    engines: {node: '>=12'}
+
+  d3-ease@3.0.1:
+    resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
+    engines: {node: '>=12'}
+
+  d3-interpolate@3.0.1:
+    resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
+    engines: {node: '>=12'}
+
+  d3-selection@3.0.0:
+    resolution: {integrity: sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==}
+    engines: {node: '>=12'}
+
+  d3-timer@3.0.1:
+    resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
+    engines: {node: '>=12'}
+
+  d3-transition@3.0.1:
+    resolution: {integrity: sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      d3-selection: 2 - 3
+
+  d3-zoom@3.0.0:
+    resolution: {integrity: sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==}
+    engines: {node: '>=12'}
+
   data-uri-to-buffer@4.0.1:
     resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}
     engines: {node: '>= 12'}
@@ -19839,6 +19885,17 @@ snapshots:
       path-browserify: 1.0.1
       vscode-uri: 3.1.0
 
+  '@vue-flow/core@1.48.2(vue@3.5.34(typescript@5.9.3))':
+    dependencies:
+      '@vueuse/core': 10.11.1(vue@3.5.34(typescript@5.9.3))
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-zoom: 3.0.0
+      vue: 3.5.34(typescript@5.9.3)
+    transitivePeerDependencies:
+      - '@vue/composition-api'
+
   '@vue-macros/common@3.1.1(vue@3.5.34(typescript@5.9.3))':
     dependencies:
       '@vue/compiler-sfc': 3.5.34
@@ -21219,6 +21276,42 @@ snapshots:
 
   csstype@3.2.3: {}
 
+  d3-color@3.1.0: {}
+
+  d3-dispatch@3.0.1: {}
+
+  d3-drag@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-selection: 3.0.0
+
+  d3-ease@3.0.1: {}
+
+  d3-interpolate@3.0.1:
+    dependencies:
+      d3-color: 3.1.0
+
+  d3-selection@3.0.0: {}
+
+  d3-timer@3.0.1: {}
+
+  d3-transition@3.0.1(d3-selection@3.0.0):
+    dependencies:
+      d3-color: 3.1.0
+      d3-dispatch: 3.0.1
+      d3-ease: 3.0.1
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-timer: 3.0.1
+
+  d3-zoom@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
   data-uri-to-buffer@4.0.1:
     optional: true
 

From e0aa12c83085ad824666476ff7c6134f5c28e7ed Mon Sep 17 00:00:00 2001
From: Maciej <7597086+mdanilowicz@users.noreply.github.com>
Date: Tue, 2 Jun 2026 09:59:16 +0200
Subject: [PATCH 3/3] feat: type tooltip

---
 .../.vitepress/data/login-flow-schema.data.ts | 296 ++++++++++++++++++
 apps/docs/src/components/LoginFlowDiagram.vue |  25 +-
 .../src/components/LoginVueFlowDiagram.vue    |  81 ++++-
 .../docs/src/components/SchemaTypeTooltip.vue | 173 ++++++++++
 .../src/frontends-recipes/account/login.md    |  17 +-
 5 files changed, 576 insertions(+), 16 deletions(-)
 create mode 100644 apps/docs/.vitepress/data/login-flow-schema.data.ts
 create mode 100644 apps/docs/src/components/SchemaTypeTooltip.vue

diff --git a/apps/docs/.vitepress/data/login-flow-schema.data.ts b/apps/docs/.vitepress/data/login-flow-schema.data.ts
new file mode 100644
index 000000000..da2b81b41
--- /dev/null
+++ b/apps/docs/.vitepress/data/login-flow-schema.data.ts
@@ -0,0 +1,296 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { defineLoader } from "vitepress";
+
+type OpenApiSchema = {
+  paths: Record<string, Record<string, Operation>>;
+  components: {
+    schemas: Record<string, SchemaNode>;
+    responses: Record<string, ResponseNode>;
+  };
+};
+
+type Operation = {
+  requestBody?: {
+    content?: Record<string, { schema?: SchemaNode }>;
+  };
+  responses?: Record<string, ResponseNode | { $ref: string }>;
+};
+
+type ResponseNode = {
+  description?: string;
+  headers?: Record<string, { description?: string; schema?: SchemaNode }>;
+  content?: Record<string, { schema?: SchemaNode }>;
+};
+
+type SchemaNode = {
+  $ref?: string;
+  type?: string;
+  format?: string;
+  description?: string;
+  enum?: string[];
+  required?: string[];
+  properties?: Record<string, SchemaNode>;
+  items?: SchemaNode;
+  oneOf?: SchemaNode[];
+  allOf?: SchemaNode[];
+  anyOf?: SchemaNode[];
+};
+
+export type SchemaFieldSummary = {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+};
+
+export type SchemaSummary = {
+  label: string;
+  source: string;
+  description?: string;
+  fields: SchemaFieldSummary[];
+  hiddenFields: number;
+};
+
+export interface Data {
+  summaries: Record<string, SchemaSummary>;
+}
+
+declare const data: Data;
+export { data };
+
+export default defineLoader({
+  load(): Data {
+    const projectRootDir = getProjectRootDir();
+    const schemaPath = join(
+      projectRootDir,
+      "packages/api-client/api-types/storeApiSchema.json",
+    );
+    const schema = JSON.parse(
+      readFileSync(schemaPath, "utf8"),
+    ) as OpenApiSchema;
+
+    const loginOperation = schema.paths["/account/login"].post;
+    const contextOperation = schema.paths["/context"].get;
+    const logoutOperation = schema.paths["/account/logout"].post;
+
+    return {
+      summaries: {
+        LoginBody: summarizeSchema({
+          label: "LoginBody",
+          source: 'operations["loginCustomer post /account/login"]["body"]',
+          schema,
+          node: getJsonSchema(schema, loginOperation.requestBody),
+        }),
+        ContextTokenResponse: summarizeResponse({
+          label: "ContextTokenResponse",
+          source: 'operations["loginCustomer post /account/login"]["response"]',
+          schema,
+          response: loginOperation.responses?.["200"],
+        }),
+        LogoutResponse: summarizeResponse({
+          label: "LogoutResponse",
+          source:
+            'operations["logoutCustomer post /account/logout"]["response"]',
+          schema,
+          response: logoutOperation.responses?.["200"],
+        }),
+        SalesChannelContext: summarizeSchema({
+          label: "SalesChannelContext",
+          source: 'operations["readContext get /context"]["response"]',
+          schema,
+          node: getJsonSchema(schema, contextOperation.responses?.["200"]),
+        }),
+        Customer: summarizeSchema({
+          label: "Customer",
+          source: 'Schemas["Customer"]',
+          schema,
+          node: schema.components.schemas.Customer,
+        }),
+        Cart: summarizeSchema({
+          label: "Cart",
+          source: 'Schemas["Cart"]',
+          schema,
+          node: schema.components.schemas.Cart,
+        }),
+        ApiError: summarizeSchema({
+          label: "ApiError",
+          source: 'components["schemas"]["failure"]',
+          schema,
+          node: schema.components.schemas.failure,
+        }),
+      },
+    };
+  },
+});
+
+function getProjectRootDir() {
+  const cwd = process.cwd();
+  if (cwd.endsWith("/apps/docs")) {
+    return join(cwd, "../..");
+  }
+
+  return join(cwd, "src/frontends/_source");
+}
+
+function summarizeResponse({
+  label,
+  source,
+  schema,
+  response,
+}: {
+  label: string;
+  source: string;
+  schema: OpenApiSchema;
+  response?: ResponseNode | { $ref: string };
+}): SchemaSummary {
+  const resolvedResponse = resolveResponse(schema, response);
+  const bodySummary = summarizeSchema({
+    label,
+    source,
+    schema,
+    node: getJsonSchema(schema, resolvedResponse),
+  });
+
+  const headerFields = Object.entries(resolvedResponse?.headers ?? {}).map(
+    ([name, header]) => ({
+      name,
+      type: formatType(schema, header.schema),
+      required: false,
+      description: header.description,
+    }),
+  );
+
+  return {
+    ...bodySummary,
+    description: resolvedResponse?.description || bodySummary.description,
+    fields: [...headerFields, ...bodySummary.fields],
+  };
+}
+
+function summarizeSchema({
+  label,
+  source,
+  schema,
+  node,
+}: {
+  label: string;
+  source: string;
+  schema: OpenApiSchema;
+  node?: SchemaNode;
+}): SchemaSummary {
+  const resolvedNode = resolveSchema(schema, node);
+  const properties = Object.entries(resolvedNode?.properties ?? {});
+  const maxFields = 8;
+  const required = new Set(resolvedNode?.required ?? []);
+
+  return {
+    label,
+    source,
+    description: resolvedNode?.description,
+    fields: properties.slice(0, maxFields).map(([name, property]) => ({
+      name,
+      type: formatType(schema, property),
+      required: required.has(name),
+      description: property.description,
+    })),
+    hiddenFields: Math.max(properties.length - maxFields, 0),
+  };
+}
+
+function getJsonSchema(
+  schema: OpenApiSchema,
+  node: ResponseNode | { $ref: string } | Operation["requestBody"] | undefined,
+) {
+  if (!node) {
+    return undefined;
+  }
+
+  if ("$ref" in node) {
+    return getJsonSchema(schema, resolveResponse(schema, node));
+  }
+
+  if ("content" in node) {
+    return node.content?.["application/json"]?.schema;
+  }
+
+  return undefined;
+}
+
+function resolveResponse(
+  schema: OpenApiSchema,
+  response: ResponseNode | { $ref: string } | undefined,
+): ResponseNode | undefined {
+  if (!response) {
+    return undefined;
+  }
+
+  if ("$ref" in response) {
+    return resolveRef(schema, response.$ref) as ResponseNode | undefined;
+  }
+
+  return response;
+}
+
+function resolveSchema(schema: OpenApiSchema, node?: SchemaNode): SchemaNode {
+  if (!node) {
+    return {};
+  }
+
+  if (node.$ref) {
+    return resolveSchema(schema, resolveRef(schema, node.$ref) as SchemaNode);
+  }
+
+  if (node.allOf?.length) {
+    return resolveSchema(schema, node.allOf[0]);
+  }
+
+  return node;
+}
+
+function resolveRef(schema: OpenApiSchema, ref: string) {
+  return ref
+    .replace("#/", "")
+    .split("/")
+    .reduce<unknown>((current, segment) => {
+      if (current && typeof current === "object" && segment in current) {
+        return (current as Record<string, unknown>)[segment];
+      }
+
+      return undefined;
+    }, schema);
+}
+
+function formatType(schema: OpenApiSchema, node?: SchemaNode): string {
+  const resolvedNode = resolveSchema(schema, node);
+
+  if (node?.$ref) {
+    return node.$ref.split("/").at(-1) ?? "object";
+  }
+
+  if (resolvedNode.oneOf?.length) {
+    return resolvedNode.oneOf
+      .map((item) => formatType(schema, item))
+      .join(" | ");
+  }
+
+  if (resolvedNode.anyOf?.length) {
+    return resolvedNode.anyOf
+      .map((item) => formatType(schema, item))
+      .join(" | ");
+  }
+
+  if (resolvedNode.type === "array") {
+    return `${formatType(schema, resolvedNode.items)}[]`;
+  }
+
+  if (resolvedNode.enum?.length) {
+    return resolvedNode.enum.map((value) => `"${value}"`).join(" | ");
+  }
+
+  if (resolvedNode.format) {
+    return `${resolvedNode.type ?? "unknown"}:${resolvedNode.format}`;
+  }
+
+  return resolvedNode.type ?? "object";
+}
diff --git a/apps/docs/src/components/LoginFlowDiagram.vue b/apps/docs/src/components/LoginFlowDiagram.vue
index 9c3a2fa13..5de4e1c6c 100644
--- a/apps/docs/src/components/LoginFlowDiagram.vue
+++ b/apps/docs/src/components/LoginFlowDiagram.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { computed, ref } from "vue";
+import SchemaTypeTooltip from "./SchemaTypeTooltip.vue";
 
 const steps = [
   {
@@ -9,6 +10,7 @@ const steps = [
       "The login form collects username and password, then calls the composable. The component owns loading and form error state only.",
     code: "submit() -> login(credentials)",
     state: "local form state",
+    typeKeys: ["LoginBody"],
   },
   {
     title: "Composable",
@@ -17,6 +19,7 @@ const steps = [
       "useUser owns the Shopware-specific workflow. It sends credentials first, then refreshes context and cart data.",
     code: "useUser().login(credentials)",
     state: "customer workflow",
+    typeKeys: ["LoginBody", "ContextTokenResponse"],
   },
   {
     title: "Store API",
@@ -25,6 +28,7 @@ const steps = [
       "The API client invokes the generated operation for POST /account/login. This step validates credentials.",
     code: 'apiClient.invoke("loginCustomer post /account/login")',
     state: "sw-context-token",
+    typeKeys: ["LoginBody", "ContextTokenResponse", "ApiError"],
   },
   {
     title: "Context",
@@ -33,6 +37,7 @@ const steps = [
       "The session context is fetched again so customer, customer group, currency, rules, and other context-dependent values are current.",
     code: 'apiClient.invoke("readContext get /context")',
     state: "user, isLoggedIn, sales channel context",
+    typeKeys: ["SalesChannelContext", "Customer"],
   },
   {
     title: "Cart",
@@ -41,6 +46,7 @@ const steps = [
       "The cart is refreshed because prices, promotions, and line items can depend on the authenticated customer context.",
     code: "refreshCart()",
     state: "cart, prices, promotions",
+    typeKeys: ["Cart"],
   },
   {
     title: "UI",
@@ -49,6 +55,7 @@ const steps = [
       "The UI reads user, isLoggedIn, and cart data from composables instead of keeping its own copy.",
     code: "user + isLoggedIn + cart",
     state: "reactive UI",
+    typeKeys: ["Customer", "Cart"],
   },
 ];
 
@@ -92,6 +99,16 @@ const activeStep = computed(() => steps[activeStepIndex.value]);
           <dt>State</dt>
           <dd>{{ activeStep.state }}</dd>
         </div>
+        <div>
+          <dt>Types</dt>
+          <dd class="login-flow__types">
+            <SchemaTypeTooltip
+              v-for="typeKey in activeStep.typeKeys"
+              :key="typeKey"
+              :type-key="typeKey"
+            />
+          </dd>
+        </div>
       </dl>
     </div>
   </section>
@@ -102,7 +119,7 @@ const activeStep = computed(() => steps[activeStepIndex.value]);
   margin: 24px 0;
   border: 1px solid var(--vp-c-divider);
   border-radius: 8px;
-  overflow: hidden;
+  overflow: visible;
   background: var(--vp-c-bg-soft);
 }
 
@@ -231,6 +248,12 @@ const activeStep = computed(() => steps[activeStepIndex.value]);
   overflow-wrap: anywhere;
 }
 
+.login-flow__types {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
 @media (max-width: 960px) {
   .login-flow__track {
     grid-template-columns: repeat(3, minmax(0, 1fr));
diff --git a/apps/docs/src/components/LoginVueFlowDiagram.vue b/apps/docs/src/components/LoginVueFlowDiagram.vue
index 2c99ef591..37d905fd0 100644
--- a/apps/docs/src/components/LoginVueFlowDiagram.vue
+++ b/apps/docs/src/components/LoginVueFlowDiagram.vue
@@ -3,84 +3,103 @@ import { VueFlow } from "@vue-flow/core";
 import "@vue-flow/core/dist/style.css";
 import "@vue-flow/core/dist/theme-default.css";
 import { computed, ref } from "vue";
+import SchemaTypeTooltip from "./SchemaTypeTooltip.vue";
 
 const nodes = ref([
   {
     id: "ui-submit",
-    label: "Login form",
+    type: "flowStep",
     position: { x: 0, y: 80 },
     class: "login-vue-flow__node login-vue-flow__node--ui",
     data: {
+      label: "Login form",
+      action: "Submit credentials",
       title: "UI: submit credentials",
       description:
         "The component collects username and password, then calls the composable. Loading and form errors stay local to the UI.",
       code: "submit() -> login(credentials)",
       state: "local form state",
+      typeKeys: ["LoginBody"],
     },
   },
   {
     id: "use-user",
-    label: "useUser().login()",
+    type: "flowStep",
     position: { x: 240, y: 80 },
     class: "login-vue-flow__node login-vue-flow__node--composable",
     data: {
+      label: "useUser().login()",
+      action: "Run login workflow",
       title: "Composable: own the workflow",
       description:
         "useUser sends credentials to the Store API and then coordinates the context and cart refreshes.",
       code: "useUser().login(credentials)",
       state: "customer workflow",
+      typeKeys: ["LoginBody", "ContextTokenResponse"],
     },
   },
   {
     id: "login-api",
-    label: "POST /account/login",
+    type: "flowStep",
     position: { x: 520, y: 0 },
     class: "login-vue-flow__node login-vue-flow__node--api",
     data: {
+      label: "POST /account/login",
+      action: "Authenticate customer",
       title: "Store API: authenticate",
       description:
         "The generated operation validates credentials and can affect the active sales channel session.",
       code: "loginCustomer post /account/login",
       state: "sw-context-token",
+      typeKeys: ["LoginBody", "ContextTokenResponse", "ApiError"],
     },
   },
   {
     id: "context",
-    label: "GET /context",
+    type: "flowStep",
     position: { x: 520, y: 170 },
     class: "login-vue-flow__node login-vue-flow__node--context",
     data: {
+      label: "GET /context",
+      action: "Refresh session",
       title: "Context: refresh session",
       description:
         "The refreshed context provides the current customer, customer group, currency, rules, and other context-dependent values.",
       code: "refreshSessionContext()",
       state: "user, isLoggedIn, sales channel context",
+      typeKeys: ["SalesChannelContext", "Customer"],
     },
   },
   {
     id: "cart",
-    label: "refreshCart()",
+    type: "flowStep",
     position: { x: 800, y: 80 },
     class: "login-vue-flow__node login-vue-flow__node--cart",
     data: {
+      label: "refreshCart()",
+      action: "Reload cart",
       title: "Cart: reload customer-aware data",
       description:
         "Cart data is loaded again because prices, promotions, and line items can depend on the authenticated customer context.",
       code: "refreshCart()",
       state: "cart, prices, promotions",
+      typeKeys: ["Cart"],
     },
   },
   {
     id: "ui-reactive",
-    label: "Reactive UI",
+    type: "flowStep",
     position: { x: 1060, y: 80 },
     class: "login-vue-flow__node login-vue-flow__node--ui",
     data: {
+      label: "Reactive UI",
+      action: "Render new state",
       title: "UI: render new state",
       description:
         "The page reads user, isLoggedIn, and cart data from composables instead of keeping a separate copy.",
       code: "user + isLoggedIn + cart",
       state: "reactive UI",
+      typeKeys: ["Customer", "Cart"],
     },
   },
 ]);
@@ -151,7 +170,23 @@ function selectNode(event: { node: (typeof nodes.value)[number] }) {
         :min-zoom="0.55"
         :max-zoom="1.2"
         @node-click="selectNode"
-      />
+      >
+        <template #node-flowStep="{ data }">
+          <div class="login-flow-node">
+            <strong>{{ data.label }}</strong>
+            <span>{{ data.action }}</span>
+            <div class="login-flow-node__types">
+              <span
+                v-for="typeKey in data.typeKeys"
+                :key="typeKey"
+                class="login-flow-node__type"
+              >
+                <SchemaTypeTooltip :type-key="typeKey" />
+              </span>
+            </div>
+          </div>
+        </template>
+      </VueFlow>
     </div>
 
     <!-- <aside class="login-vue-flow__panel">
@@ -176,10 +211,8 @@ function selectNode(event: { node: (typeof nodes.value)[number] }) {
 
 <style>
 .login-vue-flow .vue-flow__node.login-vue-flow__node {
-  width: 170px;
-  min-height: 72px;
-  display: grid;
-  place-items: center;
+  width: 190px;
+  min-height: 112px;
   padding: 12px;
   border: 1px solid var(--vp-c-divider);
   border-radius: 8px;
@@ -191,6 +224,30 @@ function selectNode(event: { node: (typeof nodes.value)[number] }) {
   text-align: center;
 }
 
+.login-vue-flow .vue-flow {
+  overflow: visible;
+}
+
+.login-vue-flow .login-flow-node {
+  display: grid;
+  gap: 8px;
+  justify-items: center;
+}
+
+.login-vue-flow .login-flow-node > span {
+  color: var(--vp-c-text-2);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.35;
+}
+
+.login-vue-flow .login-flow-node__types {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 6px;
+}
+
 .login-vue-flow .vue-flow__node.login-vue-flow__node.selected {
   border-color: var(--vp-c-brand-1);
   box-shadow:
@@ -239,7 +296,7 @@ function selectNode(event: { node: (typeof nodes.value)[number] }) {
   height: 360px;
   border: 1px solid var(--vp-c-divider);
   border-radius: 8px;
-  overflow: hidden;
+  overflow: visible;
   background:
     linear-gradient(var(--vp-c-bg-soft), var(--vp-c-bg-soft)),
     var(--vp-c-bg);
diff --git a/apps/docs/src/components/SchemaTypeTooltip.vue b/apps/docs/src/components/SchemaTypeTooltip.vue
new file mode 100644
index 000000000..31b5604cc
--- /dev/null
+++ b/apps/docs/src/components/SchemaTypeTooltip.vue
@@ -0,0 +1,173 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import { data as schemaData } from "../../.vitepress/data/login-flow-schema.data";
+
+const props = defineProps<{
+  typeKey: string;
+  label?: string;
+}>();
+
+const triggerElement = ref<HTMLElement>();
+const isVisible = ref(false);
+const tooltipStyle = ref<Record<string, string>>({});
+const summary = computed(() => schemaData.summaries[props.typeKey]);
+const displayLabel = computed(
+  () => props.label ?? summary.value?.label ?? props.typeKey,
+);
+
+function showTooltip() {
+  const trigger = triggerElement.value;
+  if (!trigger) {
+    return;
+  }
+
+  const rect = trigger.getBoundingClientRect();
+  const tooltipWidth = Math.min(340, window.innerWidth - 32);
+  const left = Math.min(
+    Math.max(rect.left + rect.width / 2, tooltipWidth / 2 + 16),
+    window.innerWidth - tooltipWidth / 2 - 16,
+  );
+  const shouldOpenAbove =
+    rect.bottom + 260 > window.innerHeight && rect.top > 260;
+
+  tooltipStyle.value = {
+    left: `${left}px`,
+    top: `${shouldOpenAbove ? rect.top - 10 : rect.bottom + 10}px`,
+    width: `${tooltipWidth}px`,
+    transform: shouldOpenAbove ? "translate(-50%, -100%)" : "translateX(-50%)",
+  };
+  isVisible.value = true;
+}
+
+function hideTooltip() {
+  isVisible.value = false;
+}
+</script>
+
+<template>
+  <span
+    ref="triggerElement"
+    class="schema-type"
+    tabindex="0"
+    @mouseenter="showTooltip"
+    @mouseleave="hideTooltip"
+    @focus="showTooltip"
+    @blur="hideTooltip"
+    @keydown.escape="hideTooltip"
+  >
+    {{ displayLabel }}
+    <Teleport to="body">
+      <span
+        v-if="isVisible"
+        class="schema-type__tooltip"
+        role="tooltip"
+        :style="tooltipStyle"
+      >
+      <strong>{{ summary?.label ?? typeKey }}</strong>
+      <small>{{ summary?.source }}</small>
+      <span v-if="summary?.description" class="schema-type__description">
+        {{ summary.description }}
+      </span>
+      <span class="schema-type__fields">
+        <span
+          v-for="field in summary?.fields ?? []"
+          :key="field.name"
+          class="schema-type__field"
+        >
+          <code>{{ field.name }}{{ field.required ? "" : "?" }}</code>
+          <span>{{ field.type }}</span>
+        </span>
+        <span v-if="summary?.hiddenFields" class="schema-type__more">
+          +{{ summary.hiddenFields }} more fields
+        </span>
+      </span>
+      </span>
+    </Teleport>
+  </span>
+</template>
+
+<style scoped>
+.schema-type {
+  position: relative;
+  display: inline-flex;
+  max-width: 100%;
+  padding: 3px 7px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 999px;
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-brand-1);
+  font-size: 11px;
+  font-weight: 700;
+  line-height: 1.2;
+  vertical-align: middle;
+  cursor: help;
+}
+
+.schema-type:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.schema-type__tooltip {
+  position: fixed;
+  z-index: 100;
+  display: grid;
+  gap: 8px;
+  padding: 12px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  box-shadow: 0 18px 42px rgba(0, 0, 0, 0.18);
+  pointer-events: none;
+  text-align: left;
+}
+
+.schema-type__tooltip strong {
+  color: var(--vp-c-text-1);
+  font-size: 13px;
+}
+
+.schema-type__tooltip small {
+  color: var(--vp-c-text-2);
+  font-family: var(--vp-font-family-mono);
+  font-size: 11px;
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+}
+
+.schema-type__description {
+  color: var(--vp-c-text-2);
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 1.4;
+}
+
+.schema-type__fields {
+  display: grid;
+  gap: 5px;
+}
+
+.schema-type__field {
+  display: grid;
+  grid-template-columns: minmax(90px, 0.8fr) minmax(0, 1fr);
+  gap: 8px;
+  align-items: baseline;
+  font-size: 12px;
+  font-weight: 400;
+}
+
+.schema-type__field code {
+  color: var(--vp-c-text-1);
+  font-size: 11px;
+  overflow-wrap: anywhere;
+}
+
+.schema-type__field span,
+.schema-type__more {
+  color: var(--vp-c-text-2);
+  font-size: 12px;
+  font-weight: 500;
+  overflow-wrap: anywhere;
+}
+</style>
diff --git a/apps/docs/src/frontends-recipes/account/login.md b/apps/docs/src/frontends-recipes/account/login.md
index 7b7f870ac..07b60271a 100644
--- a/apps/docs/src/frontends-recipes/account/login.md
+++ b/apps/docs/src/frontends-recipes/account/login.md
@@ -23,6 +23,7 @@ recipe:
 <script setup>
 import LoginFlowDiagram from "../../components/LoginFlowDiagram.vue";
 import LoginVueFlowDiagram from "../../components/LoginVueFlowDiagram.vue";
+import SchemaTypeTooltip from "../../components/SchemaTypeTooltip.vue";
 </script>
 
 # Login
@@ -39,6 +40,8 @@ Login is a small form action, but it changes the whole sales channel session. Th
   <LoginVueFlowDiagram />
 </ClientOnly>
 
+Hover a type chip to inspect fields generated from the current Store API schema.
+
 <LoginFlowDiagram />
 
 Read the diagram from left to right:
@@ -56,9 +59,9 @@ You usually do not need to call `readContext get /context` manually after login,
 
 | Step | Code | Store API | Type |
 |---|---|---|---|
-| Submit credentials | `login(credentials)` | `POST /account/login` | `operations["loginCustomer post /account/login"]["body"]` |
-| Refresh session context | `refreshSessionContext()` | `GET /context` | `operations["readContext get /context"]["response"]` |
-| Logout customer | `logout()` | `POST /account/logout` | `operations["logoutCustomer post /account/logout"]["response"]` |
+| Submit credentials | `login(credentials)` | `POST /account/login` | <SchemaTypeTooltip type-key="LoginBody" label='operations["loginCustomer post /account/login"]["body"]' /> |
+| Refresh session context | `refreshSessionContext()` | `GET /context` | <SchemaTypeTooltip type-key="SalesChannelContext" label='operations["readContext get /context"]["response"]' /> |
+| Logout customer | `logout()` | `POST /account/logout` | <SchemaTypeTooltip type-key="LogoutResponse" label='operations["logoutCustomer post /account/logout"]["response"]' /> |
 
 ## Composables
 
@@ -70,6 +73,14 @@ You usually do not need to call `readContext get /context` manually after login,
 
 Use generated Store API types when you need to type credentials, responses, or lower-level API client calls:
 
+<div style="display: flex; flex-wrap: wrap; gap: 6px; margin: 12px 0 18px;">
+  <SchemaTypeTooltip type-key="LoginBody" />
+  <SchemaTypeTooltip type-key="ContextTokenResponse" />
+  <SchemaTypeTooltip type-key="SalesChannelContext" />
+  <SchemaTypeTooltip type-key="Customer" />
+  <SchemaTypeTooltip type-key="Cart" />
+</div>
+
 ```ts
 import type { Schemas, operations } from "#shopware";