@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/nuxt/.claude/docs/stack.md

@@ -0,0 +1,666 @@
+# Nuxt Application Coding Standard
+
+> **Stack**: Nuxt 4.4, Vue 3.5, TypeScript 5.9, Nuxt UI 4, Tailwind CSS 4, Pinia 3, Pinia Colada, VueUse, Nuxt Image, i18n, SEO and Scripts modules.
+> **Composition**: `@stackonward/nuxt-site-shell` extends reusable layers; routes, app configuration and registry-installed source belong to the generated application.
+> Exact versions and executable scripts are controlled by `package.json` and the lockfile.
+
+## I. Commands and Environment
+
+### Commands
+
+| Command                | Behavior                                                         |
+| ---------------------- | ---------------------------------------------------------------- |
+| `pnpm install`         | Resolve dependencies, prepare Nuxt and register repository hooks |
+| `pnpm dev`             | Start the Nuxt development server                                |
+| `pnpm prepare:nuxt`    | Regenerate Nuxt framework/types preparation                      |
+| `pnpm lint`            | Run Nuxt-aware code lint and CSS/Vue style lint                  |
+| `pnpm lint:code:fix`   | Fix supported JavaScript, TypeScript and Vue lint findings       |
+| `pnpm lint:styles:fix` | Fix supported CSS and Vue-style findings                         |
+| `pnpm format`          | Format application source, tests and root configuration          |
+| `pnpm format:check`    | Check formatting without writes                                  |
+| `pnpm typecheck`       | Run `nuxt typecheck`                                             |
+| `pnpm test`            | Run the Nuxt application test suite                              |
+| `pnpm build`           | Build the application and Nitro output                           |
+| `pnpm check`           | Run format, lint, typecheck, test and build gates                |
+| `pnpm preview`         | Preview the built application                                    |
+
+ESLint composes the Nuxt-generated flat configuration with `@stackonward/eslint-config/nuxt`. Stylelint, Prettier and Commitlint load their versioned StackOnward policies through application-owned root configuration. Husky owns clone-local hook registration; lint-staged owns staged-file selection. The full `pnpm check` result is the application gate.
+
+### Environment Variables
+
+`nuxt.config.ts` owns public runtime mapping; `.env.example` documents available values. Public means readable by browser users.
+
+| Variable family                                                                  | Consumer and meaning                                                           |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `NUXT_PUBLIC_API_BASE_URL`, `NUXT_PUBLIC_API_TIMEOUT`                            | Public API URL and timeout configuration                                       |
+| `NUXT_PUBLIC_SITE_URL`, `SITE_ENV`, `SITE_NAME`, `SITE_DESCRIPTION`              | Canonical site identity and environment under the same prefix                  |
+| `NUXT_PUBLIC_ANALYTICS_ENABLED`, `ANALYTICS_DEBUG`                               | Analytics enable/debug configuration                                           |
+| `NUXT_PUBLIC_ANALYTICS_REQUIRE_CONSENT`, `ANALYTICS_PAGE_TRACKING`               | Consent requirement and route tracking                                         |
+| `NUXT_PUBLIC_ANALYTICS_DATA_LAYER`, `GA_ID`, `GTM_ID`                            | Public analytics integration IDs under the same prefix                         |
+| `NUXT_PUBLIC_GOOGLE_IDENTITY_ENABLED`, `GOOGLE_CLIENT_ID`                        | Google client-side identity configuration                                      |
+| `NUXT_PUBLIC_GOOGLE_CREDENTIAL_ENDPOINT`, `GOOGLE_ONE_TAP`, `GOOGLE_AUTO_PROMPT` | Configured credential exchange endpoint and prompting options                  |
+| `NUXT_PUBLIC_CHECKOUT_URL`, `CHECKOUT_RESULT_PARAM`                              | Checkout destination and return parameter                                      |
+| `NUXT_PUBLIC_YOUTUBE_PRIVACY_ENHANCED`                                           | Video privacy configuration                                                    |
+| `NUXT_PUBLIC_OG_IMAGE_ENABLED`                                                   | SEO layer option; verify the installed layer consumer before changing behavior |
+
+Never place OAuth secrets, service credentials or provider API keys here. An enabled client feature does not prove backend credentials or permission are configured. Validate numeric input at its actual consumer rather than relying on `Number.parseInt` alone.
+
+## II. Project Structure and Imports
+
+| Owner                                                                 | Responsibility                                                       |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `nuxt.config.ts`                                                      | Layer/module composition, public runtime config, imports and icons   |
+| `app/app.config.ts`                                                   | Brand, theme composition, site navigation and consent copy           |
+| `app/pages/`                                                          | File-based routes: home, app shell, UI, blog, author and legal views |
+| `app/i18n/locales/en.json`                                            | Application locale content                                           |
+| `server/api/preview.get.ts`                                           | Current preview capability response                                  |
+| `server/api/content/sitemap-urls.get.ts`                              | Current sitemap URL list                                             |
+| `public/`                                                             | Static app-owned icons and media                                     |
+| Registry-installed `app/components`, `app/composables`, theme and CSS | Editable application source delivered by the CLI                     |
+
+The template's preview endpoint currently returns `preview: false` and an inspected path. It is not an authenticated CMS preview session. Sitemap URLs are the current source list, not proof that a content backend exists.
+
+### Import Order
+
+1. Explicit type imports.
+2. Vue/framework imports where auto-import is not provided.
+3. Public StackOnward package exports.
+4. Installed third-party exports.
+5. Application owners through Nuxt aliases or relative paths.
+
+Use `~/` for Nuxt app source and `~~/` for the project root where Nuxt's context requires it. Do not copy OneX Admin `#/` aliases, Vben imports or TanStack Query calls into this Pinia Colada application. Verify auto-import declarations before adding redundant imports or assuming a package symbol is globally available.
+
+## III. Pre-edit and Ownership Gate (CRITICAL)
+
+Read root rules, this document, the actual page, child/shared components, installed layers, API owner and nearest equivalent page before editing. Inventory visible regions, overlays, slots, form controls, data states and route/context ownership.
+
+```text
+PRE_PATCH_EVIDENCE:
+- target: route, source design, viewport, identity and selected object
+- source_inventory: page, children, layer, API/configuration and nearest equivalents
+- runtime_inventory: regions, menus, overlays, controls and async states
+- reuse: installed primitive/composable and actual public import
+- verification: typecheck/build scope plus browser and network evidence
+```
+
+Every new file must have a precise owner. Business fields and protocol types do not belong inline in page templates. Component props/emits stay with the component; API types stay with the API owner; shared types require genuine consumers.
+
+### Placement Decision Tree
+
+```text
+Request/response type? → API/service owner
+Component props/emits? → component
+Pure function without Vue? → feature-local utility, share after reuse is proven
+Reactive reusable state? → composable
+Global client state? → Pinia owner
+Server query cache? → existing Pinia Colada/query owner
+Single page presentation? → page-private component
+Used by multiple pages? → existing shared app component or package
+```
+
+File names follow installed conventions: Vue components use descriptive PascalCase, composables `useFeature.ts`, Nuxt pages/routes use filesystem route syntax, and server endpoints include method suffixes such as `.get.ts`. Avoid generic `helper`, `manager`, `new` or caller-branded names.
+
+## IV. Forbidden Patterns
+
+| ID     | Forbidden                                                 | Required behavior                                       |
+| ------ | --------------------------------------------------------- | ------------------------------------------------------- |
+| NX-S1  | Hardcoded deployment API origins                          | Public runtime configuration                            |
+| NX-S2  | Ad-hoc token storage and credential forwarding            | Actual identity adapter/session contract                |
+| NX-S3  | Untrusted `v-html`                                        | Escaped text or the declared sanitized-content boundary |
+| NX-S4  | Private secrets in public config or committed env         | Private server/process configuration                    |
+| NX-A1  | Business workflow in page markup                          | Service/composable owner                                |
+| NX-A2  | HTTP calls in template event expressions                  | Typed API action through state coordination             |
+| NX-A3  | Module-global mutable SSR state                           | Request/application-scoped state                        |
+| NX-A4  | Duplicated API types in views and stores                  | Canonical API types                                     |
+| NX-A5  | Navigation bypassing configured locale/base-path behavior | Framework navigation and existing route composition     |
+| NX-A6  | Undeclared imports or missing public exports              | Manifest and export agreement                           |
+| NX-A7  | Copying Vben table/form/modal adapters                    | Installed Nuxt UI and app primitives                    |
+| NX-A8  | Duplicate loading/cache owners for one query              | Existing query lifecycle                                |
+| NX-A9  | Watch/refetch loops for reactive query identity           | Declarative reactive key/parameters                     |
+| NX-A10 | Duplicated pagination shapes across APIs                  | Shared contract at the actual API boundary              |
+| NX-T1  | `any` or unsafe casts used as validation                  | Concrete types and unknown parsing                      |
+| NX-T2  | Untyped service results                                   | Typed request/result/error contracts                    |
+| NX-C1  | Hidden controls treated as authorization                  | Server-enforced resource policy                         |
+| NX-C2  | Swallowing remote error into empty success                | Preserve safe semantic failure                          |
+| NX-C3  | Display labels used as machine identifiers                | Stable contract codes and localized labels              |
+| NX-H1  | Credential/user payload debug logs                        | Safe diagnostics only                                   |
+| NX-H2  | Dead code, unused imports, deferred handlers              | Delete or implement complete behavior                   |
+| NX-H3  | Per-page hardcoded theme overrides                        | Existing token/theme owner                              |
+| NX-H4  | Direct DOM mutation for reactive UI                       | Vue refs and state                                      |
+| NX-H5  | Global component CSS leaking across routes                | Utility classes or scoped owner styles                  |
+| NX-E1  | Business enum metadata copied into pages                  | Actual backend metadata/generated contract              |
+| NX-E2  | Invented `useEnum` endpoint                               | Use installed owner and declared contract               |
+| NX-M1  | Mixed locale persistence formats                          | Explicit locale boundary mapping                        |
+| NX-M2  | Page-local locale lists/fallback policy                   | Existing i18n owner                                     |
+| NX-P1  | Generic layer branches on a customer/product              | Application composition or named adapter                |
+| NX-P2  | Registry metadata reconstructed in frontend               | Authoritative service contract                          |
+| NX-P3  | Caller-supplied scope treated as permission               | Validate and authorize at backend                       |
+
+## V. API and Result Contracts
+
+API adapters own transport formats and safe failures. Components consume typed state and actions. Do not add a parallel fetch client with different token, timeout or error behavior to make one page work.
+
+For HTTP services following the shared platform contract:
+
+| Operation       | Status | Body                                    |
+| --------------- | ------ | --------------------------------------- |
+| Read resource   | 200    | Direct resource object                  |
+| Read collection | 200    | Agreed collection and pagination object |
+| Create          | 201    | Created resource                        |
+| Update          | 200    | Updated resource                        |
+| Delete          | 204    | No body                                 |
+
+```json
+{
+  "error": {
+    "type": "validation_error",
+    "code": "invalid_parameters",
+    "message": "Request validation failed"
+  }
+}
+```
+
+The producer contract remains authoritative. Do not invent `{ code: 200, data: ... }` wrapping or strip collection metadata in a generic interceptor. API request/response types are co-located and exported through existing public entrypoints. A transport generic is not a response validator.
+
+✅ Correct: a mutation completes through the API owner, then invalidates affected queries and reports success.
+
+❌ Wrong: display success and clear the draft before awaiting the write; catch failures by returning `[]`.
+
+## VI. State Management and SSR
+
+```text
+API/service adapter → typed transport results
+Query composable   → server cache, request identity and invalidation
+Pinia store        → client preferences/session projection/UI state
+Page/component     → local draft and presentation
+```
+
+Read the installed Pinia Colada integration before selecting query calls. Do not copy TanStack-specific `queryClient` APIs or invent a cache TTL. Keys include all identity, scope and filter values that change the response. Reactive values must remain reactive across composable boundaries.
+
+Pinia stores use Composition API style and stable IDs. Identity-owned stores expose meaningful reset behavior; logout clears private state and invalidates in-flight results. Do not put request-specific mutable state at module scope.
+
+Browser APIs run only within a client lifecycle. Initial server/client rendering must agree; use deterministic placeholders for browser-only data and hydrate through its owner. Register cleanup for subscriptions, observers, timers and requests.
+
+### Complete Scoped Query and Mutation Example
+
+The following files form one complete framework example. `ItemService` is an injected, typed application boundary; the caller supplies its real validated API adapter. These examples do not install an `/items` endpoint or pretend a backend exists. A scope key isolates cached identity/resource context; authorization still belongs to the service. The installed `@pinia/colada-nuxt` module exports query composables through Nuxt `#imports`, so consumers do not need an undeclared direct package import.
+
+**Contract and key owner — `app/api/items.ts`:**
+
+```typescript
+export interface Item {
+  id: string;
+  name: string;
+}
+export interface ItemFilters {
+  keyword: string;
+}
+export interface ItemDraft {
+  name: string;
+}
+export interface ItemService {
+  list(scope: string, filters: ItemFilters, signal: AbortSignal): Promise<Item[]>;
+  detail(scope: string, id: string, signal: AbortSignal): Promise<Item>;
+  save(scope: string, id: string | null, draft: ItemDraft, signal: AbortSignal): Promise<Item>;
+}
+export const itemKeys = {
+  scope: (scope: string) => ["items", scope] as const,
+  lists: (scope: string) => [...itemKeys.scope(scope), "list"] as const,
+  list: (scope: string, filters: ItemFilters) =>
+    [...itemKeys.lists(scope), filters.keyword] as const,
+  detail: (scope: string, id: string) => [...itemKeys.scope(scope), "detail", id] as const,
+};
+```
+
+**Query/mutation owner — `app/composables/useItems.ts`:**
+
+```typescript
+import type { MaybeRefOrGetter } from "vue";
+import type { ItemDraft, ItemFilters, ItemService } from "~/api/items";
+import { toValue } from "vue";
+import { useMutation, useQuery, useQueryCache } from "#imports";
+import { itemKeys } from "~/api/items";
+
+export function useItemList(
+  api: ItemService,
+  scope: MaybeRefOrGetter<string>,
+  filters: MaybeRefOrGetter<ItemFilters>,
+) {
+  return useQuery({
+    key: () => itemKeys.list(toValue(scope), toValue(filters)),
+    query: ({ signal }) => api.list(toValue(scope), { ...toValue(filters) }, signal),
+  });
+}
+
+export function useItemDetail(
+  api: ItemService,
+  scope: MaybeRefOrGetter<string>,
+  id: MaybeRefOrGetter<string>,
+) {
+  return useQuery({
+    key: () => itemKeys.detail(toValue(scope), toValue(id)),
+    query: ({ signal }) => api.detail(toValue(scope), toValue(id), signal),
+    enabled: () => toValue(id).length > 0,
+  });
+}
+
+interface SaveItemVariables {
+  scope: string;
+  id: string | null;
+  draft: ItemDraft;
+  signal: AbortSignal;
+}
+
+export function useSaveItem(api: ItemService) {
+  const cache = useQueryCache();
+  const mutation = useMutation({
+    mutation: (variables: SaveItemVariables) =>
+      api.save(variables.scope, variables.id, variables.draft, variables.signal),
+    onSuccess: async (saved, variables) => {
+      // 失效作用域的完成结果不能重新写回私有缓存。
+      if (variables.signal.aborted) return;
+      const detailKey = itemKeys.detail(variables.scope, saved.id);
+      // 取消旧详情读取，避免晚到响应覆盖服务端已确认的保存结果。
+      cache.cancelQueries({ key: detailKey, exact: true });
+      cache.setQueryData(detailKey, saved);
+      // 写入已成功；把网络刷新作为独立结果处理，避免误导用户重复提交。
+      await cache.invalidateQueries({ key: itemKeys.lists(variables.scope) }, false);
+    },
+  });
+
+  function refreshSavedScope(scope: string) {
+    return cache.invalidateQueries({ key: itemKeys.lists(scope) });
+  }
+
+  return { ...mutation, refreshSavedScope };
+}
+```
+
+The function form of `key` retains reactive scope/filter dependencies. `query` captures current values before the asynchronous boundary and forwards the library's abort signal. A detail query is disabled when its required identifier is absent. The save variables retain the submitting scope; a later account change must never invalidate the new account's cache.
+
+Before writing the confirmed detail result, cancel the exact detail key in that same submitted scope. Colada `setQueryData` does not clear an older pending read; cancellation clears its pending identity so even a service that ignores abort cannot overwrite the saved value when that read resolves. Do not cancel another scope or unrelated detail queries.
+
+✅ Use `useItemList(api, () => props.scope, () => ({ keyword: filters.keyword }))`. A filter or scope change chooses a different key and the query owner handles loading, cache and cancellation.
+
+❌ Do not use `useItemList(api, props.scope, { keyword: filters.keyword })` when those values must remain reactive. Do not add a second `watch(..., refetch)` loop or copy the query result into another store.
+
+### Complete Composition Store and Scope Reset
+
+**Client-state owner — `app/stores/item-filters.ts`:**
+
+```typescript
+import { defineStore } from "pinia";
+import { ref } from "vue";
+
+export const useItemFiltersStore = defineStore("item-filters", () => {
+  const keyword = ref("");
+  const selectedId = ref<string | null>(null);
+
+  function $reset() {
+    keyword.value = "";
+    selectedId.value = null;
+  }
+
+  return { keyword, selectedId, $reset };
+});
+```
+
+The store owns only shared client preferences/selection. It does not hold a duplicate `items` list or create an immortal query. Its complete reset assigns every state field; `Object.assign(filters, {})` does not remove old properties and is not a reset.
+
+For a full identity-scope transition, cancel and remove private cache entries **after switching the active identity/scope**. The following helper runs inside a Nuxt setup/plugin context; its `previousScope` is the authenticated scope being retired, not caller input used for authorization:
+
+**Scope lifecycle owner — `app/composables/useItemScopeReset.ts`:**
+
+```typescript
+import { useQueryCache } from "#imports";
+import { itemKeys } from "~/api/items";
+import { useItemFiltersStore } from "~/stores/item-filters";
+
+export function useItemScopeReset() {
+  const cache = useQueryCache();
+  const filters = useItemFiltersStore();
+
+  return (previousScope: string) => {
+    cache.cancelQueries({ key: itemKeys.scope(previousScope) });
+    for (const entry of cache.getEntries({ key: itemKeys.scope(previousScope) })) {
+      cache.remove(entry);
+    }
+    filters.$reset();
+  };
+}
+```
+
+An ordinary component unmount must not remove a cache entry shared by other active consumers. Query observer cleanup belongs to Pinia Colada; identity retirement owns private-cache removal. Mutation cancellation remains the submitting component/service owner's responsibility. The examples use the installed Colada `key`, `query`, `mutation`, `useQueryCache` and filter APIs, not TanStack `queryKey`, `queryFn` or `useQueryClient` APIs.
+
+## VII. Component and Theme Standards (CRITICAL)
+
+Read the installed layer, app theme and existing component before introducing another implementation. Nuxt UI primitives and registry-owned components are the component system; Ant Design/Vben rules are not installed APIs here.
+
+| Need               | Component responsibility                                   |
+| ------------------ | ---------------------------------------------------------- |
+| Form               | Typed validation, labels, field errors and submit state    |
+| Table/list         | Dataset identity, pagination, stable keys and row actions  |
+| Modal/action sheet | Bounded choice or confirmation, focus trapping and restore |
+| Drawer/detail      | Owned object context, navigation and editing lifecycle     |
+| Tooltip/copy       | Accessible description and actual copyable value           |
+| Toast/status       | Confirmed operation result, not primary error recovery     |
+| History            | Real ordered events with source metadata                   |
+| Theme              | Central tokens and app configuration                       |
+
+```vue
+<script setup lang="ts">
+interface Props {
+  pending: boolean;
+}
+defineProps<Props>();
+const emit = defineEmits<{ submit: [] }>();
+</script>
+
+<template>
+  <UButton :loading="pending" :disabled="pending" @click="emit('submit')"> Save </UButton>
+</template>
+```
+
+✅ The component exposes a typed action and pending state; the caller owns the write.
+
+❌ A presentational button creates an HTTP client, chooses credentials and reports success without a server result.
+
+Use Tailwind utilities and theme tokens. Scoped CSS is for behavior that utilities cannot express cleanly. Dark/light modes must use the same semantic tokens; never fix one page with a hardcoded light background that breaks dark mode.
+
+### Complete Create/Edit Form, Recovery and Close Lifecycle
+
+The component below consumes the three owners defined in section VI. It includes a real query-driven list, create/edit entry, typed validation, mutation submission, post-save refresh and failure recovery. All types/functions it imports are defined above or exported by the installed framework. Nuxt UI's `validate` callback avoids adding an uninstalled schema library to this template.
+
+**Consumer — `app/components/ItemEditor.vue`:**
+
+```vue
+<script setup lang="ts">
+import type { FormError, FormSubmitEvent } from "@nuxt/ui";
+import type { Item, ItemDraft, ItemService } from "~/api/items";
+import { onScopeDispose, reactive, ref, watch } from "vue";
+import { useItemList, useSaveItem } from "~/composables/useItems";
+import { useItemScopeReset } from "~/composables/useItemScopeReset";
+import { useItemFiltersStore } from "~/stores/item-filters";
+
+const props = defineProps<{ scope: string; service: ItemService }>();
+const filters = useItemFiltersStore();
+const retireScope = useItemScopeReset();
+const {
+  data: items,
+  error: listError,
+  isLoading: listLoading,
+  refetch,
+} = useItemList(
+  props.service,
+  () => props.scope,
+  () => ({ keyword: filters.keyword }),
+);
+const {
+  mutateAsync,
+  isLoading: saving,
+  reset: resetMutation,
+  refreshSavedScope,
+} = useSaveItem(props.service);
+const open = ref(false);
+const editingId = ref<string | null>(null);
+const draft = reactive<ItemDraft>({ name: "" });
+const saveError = ref("");
+const resultMessage = ref("");
+let revision = 0;
+let saveController: AbortController | undefined;
+
+function validate(values: ItemDraft): FormError[] {
+  const name = values.name.trim();
+  if (name.length === 0) return [{ name: "name", message: "Enter a name." }];
+  if (name.length > 120) return [{ name: "name", message: "Use at most 120 characters." }];
+  return [];
+}
+
+function resetDraft() {
+  editingId.value = null;
+  draft.name = "";
+  saveError.value = "";
+}
+
+function beginEdit(item?: Item) {
+  revision += 1;
+  resetDraft();
+  resetMutation();
+  editingId.value = item?.id ?? null;
+  draft.name = item?.name ?? "";
+  resultMessage.value = "";
+  open.value = true;
+}
+
+function afterClose() {
+  // 离场后清理，避免关闭动画中闪现空表单。
+  if (!open.value) resetDraft();
+}
+
+async function submit(event: FormSubmitEvent<ItemDraft>) {
+  const submittedRevision = revision;
+  const submittedScope = props.scope;
+  const controller = new AbortController();
+  saveController = controller;
+  saveError.value = "";
+  try {
+    await mutateAsync({
+      scope: submittedScope,
+      id: editingId.value,
+      draft: { name: event.data.name.trim() },
+      signal: controller.signal,
+    });
+  } catch {
+    if (revision === submittedRevision && !controller.signal.aborted) {
+      saveError.value = "Unable to save. Your input is preserved; try again.";
+    }
+    return;
+  } finally {
+    if (saveController === controller) saveController = undefined;
+  }
+  if (revision !== submittedRevision || controller.signal.aborted) return;
+  open.value = false;
+  resultMessage.value = "Saved.";
+  try {
+    await refreshSavedScope(submittedScope);
+  } catch {
+    if (revision === submittedRevision) {
+      resultMessage.value =
+        "Saved, but the list could not refresh. Refresh the list; do not submit again.";
+    }
+  }
+}
+
+watch(
+  () => props.scope,
+  (_current, previous) => {
+    revision += 1;
+    saveController?.abort();
+    open.value = false;
+    resetDraft();
+    resultMessage.value = "";
+    retireScope(previous);
+  },
+  { flush: "sync" },
+);
+
+onScopeDispose(() => {
+  revision += 1;
+  saveController?.abort();
+});
+</script>
+
+<template>
+  <section class="space-y-4">
+    <UFormField label="Search" name="keyword">
+      <UInput v-model="filters.keyword" class="w-full" />
+    </UFormField>
+    <UButton :disabled="saving" @click="beginEdit()">Create</UButton>
+    <p v-if="resultMessage" role="status" v-text="resultMessage" />
+    <p v-if="listLoading" role="status">Loading…</p>
+    <div v-if="listError" role="alert">
+      <p>Unable to refresh the list. Previously loaded items remain available.</p>
+      <UButton :loading="listLoading" @click="refetch()">Refresh list</UButton>
+    </div>
+    <p v-if="items && items.length === 0 && !listError">No matching items.</p>
+    <ul v-if="items" class="space-y-2">
+      <li v-for="item in items" :key="item.id" class="flex items-center gap-3">
+        <span class="min-w-0 break-words" v-text="item.name" />
+        <UButton :disabled="saving" @click="beginEdit(item)">Edit</UButton>
+      </li>
+    </ul>
+    <UModal
+      v-model:open="open"
+      :title="editingId ? 'Edit item' : 'Create item'"
+      :dismissible="!saving"
+      :close="!saving"
+      @after:leave="afterClose"
+    >
+      <template #body>
+        <UForm
+          :state="draft"
+          :validate="validate"
+          :disabled="saving"
+          class="space-y-4"
+          @submit="submit"
+        >
+          <UFormField label="Name" name="name" required>
+            <UInput v-model="draft.name" class="w-full" />
+          </UFormField>
+          <p v-if="saveError" role="alert" v-text="saveError" />
+          <div class="flex justify-end gap-2">
+            <UButton color="neutral" variant="outline" :disabled="saving" @click="open = false"
+              >Cancel</UButton
+            >
+            <UButton type="submit" :loading="saving" :disabled="saving">Save</UButton>
+          </div>
+        </UForm>
+      </template>
+    </UModal>
+  </section>
+</template>
+```
+
+The component's `scope` is a validated identity/resource-context key supplied by its parent. The service instance must be request/application-scoped and perform actual authorization. In an application with a global identity coordinator, move `retireScope(previous)` to that single owner rather than repeating account-retirement effects in every editor.
+
+The submitting editor blocks normal close/duplicate submit while the write is pending. Account changes and disposal abort local waiting and invalidate the revision, so old errors/results cannot update the new scope. This does not claim that an accepted remote write was rolled back. The API adapter must expose ambiguous acceptance safely instead of automatically replaying a mutation.
+
+✅ A failed save leaves the modal open and the draft intact. A successful save closes it, resets draft after the leave transition and refreshes the submitted scope. A refresh failure is reported as **saved but not refreshed**, with a read-only retry; it never invites another create.
+
+❌ Do not place write and refresh in one catch that reports both as “save failed”. Do not call `resetDraft()` in a write `finally`, close before awaiting `mutateAsync`, destroy old data on a refresh error, or use `Object.assign(state, {})` as reset.
+
+**Acceptance cases for these examples**: change filter while the first query is pending; switch identity while saving; fail validation without invoking the service; fail save and retain typed input; succeed save but fail list refresh; close/reopen and verify cleared errors; dispose while pending; verify another active consumer keeps its shared query cache. Query loading and stale-data states come from Colada, not a second ad-hoc fetch lifecycle.
+
+For the late-detail-read case, hold a detail read pending, complete a save, then resolve the older read with stale data even though its signal was aborted. Assert that `cache.getQueryData(itemKeys.detail(submittedScope, saved.id))` still equals `saved`; also assert that a different scope's detail request was not aborted. This proves that saved data survives out-of-order completion without cancelling unrelated consumers.
+
+## VIII. Layout and Interaction Rules
+
+Each rule applies to the matching UI surface; administrative density and Vben-specific APIs are not imposed on consumer/marketing routes.
+
+| ID     | Required behavior                                                                                     |
+| ------ | ----------------------------------------------------------------------------------------------------- |
+| NX-U1  | Variable-length columns share width; deterministic values retain appropriate bounds.                  |
+| NX-U2  | Read component defaults before alignment or sizing overrides.                                         |
+| NX-U3  | Keep alignment coherent with content; numeric and prose semantics differ.                             |
+| NX-U4  | Preserve required information when fixing width; use responsive layout or scroll.                     |
+| NX-U5  | Long names, URLs and descriptions must wrap/truncate with usable detail access.                       |
+| NX-U6  | Fixed-size controls and dates must not consume arbitrary flex space.                                  |
+| NX-U7  | Row actions must not accidentally trigger parent selection/navigation.                                |
+| NX-U8  | Details use real layout regions, not overlapping absolute panels.                                     |
+| NX-U9  | Equivalent pages reuse the established layout and interaction shape.                                  |
+| NX-U10 | Theme adjustments belong to the token/component owner.                                                |
+| NX-U11 | Primary, secondary and tertiary actions have clear visual hierarchy.                                  |
+| NX-U12 | Labels remain visually closer to their own control than adjacent fields.                              |
+| NX-U13 | Density follows the user task; consumer pages do not inherit admin compactness blindly.               |
+| NX-U14 | Date ranges and multi-field controls keep usable width on narrow screens.                             |
+| NX-U15 | Choose sheet/modal/drawer by interaction semantics and the accepted design.                           |
+| NX-U16 | Form controls fill the usable field width and preserve validation space.                              |
+| NX-U17 | Entity references use searchable real options instead of raw foreign-key entry.                       |
+| NX-U18 | Ordinary lists load their valid default state before optional refinement.                             |
+| NX-U19 | Media selection/upload uses the existing unified asset control when available.                        |
+| NX-U20 | List row density and secondary text follow the accepted consumer design.                              |
+| NX-U21 | Workbench pane width follows information density, not equal thirds.                                   |
+| NX-U22 | Parent context survives related steps; do not split one workflow into disconnected pages.             |
+| NX-U23 | Page chrome communicates actual object/context, not implementation instructions.                      |
+| NX-U24 | Field help and actionable error states replace decorative warning banners.                            |
+| NX-U25 | Metrics and badges must inform a real user decision.                                                  |
+| NX-U26 | Structured business values use typed controls, not raw JSON as the primary editor.                    |
+| NX-U27 | Loading states are component state, not fake selectable values.                                       |
+| NX-U28 | References display meaningful identity and real navigation/copy affordances.                          |
+| NX-U29 | Server-generated identifiers are not mandatory manual form fields.                                    |
+| NX-U30 | Frequent simple edits use the accepted inline interaction; full edits retain their form.              |
+| NX-U31 | Table alignment belongs to the actual Nuxt component/theme; no copied Vben center mandate.            |
+| NX-U32 | Real identifiers/long values have reusable copy behavior where useful.                                |
+| NX-U33 | User-facing names use human labels; machine codes remain available for diagnostics.                   |
+| NX-U34 | Bounded details, history and steps use semantic components rather than forced tables.                 |
+| NX-U35 | Detail navigation and child section chrome match the accepted design.                                 |
+| NX-U36 | Design verification accounts for every visible region and resolves in-scope gaps.                     |
+| NX-U37 | Empty values explain the field's absence; absent values are not copyable controls.                    |
+| NX-U38 | Navigation follows related analytical layers versus heterogeneous sections.                           |
+| NX-U39 | Prose and long detail values retain natural readable alignment.                                       |
+| NX-U40 | Long pickers/history support their actual paginated or infinite-loading contract.                     |
+| NX-U41 | Large machine collections offer bounded previews and search, not default tag walls.                   |
+| NX-U42 | Custom icon/tag content aligns through component layout, not arbitrary offsets.                       |
+| NX-U43 | Denied writes do not blank readable evidence or unrelated detail sections.                            |
+| NX-U44 | Parent sections own outer spacing; children own internal gaps.                                        |
+| NX-U45 | Read-only rows retain safe navigation and omit meaningless destructive controls.                      |
+| NX-U46 | Embedded lists adapt to content/viewport without blank action columns or magic heights.               |
+| NX-U47 | Repeated title/action rows use the shared component owner.                                            |
+| NX-U48 | Wide lists keep important actions reachable without deleting data to fit.                             |
+| NX-U49 | Runtime inventory includes children, slots, teleports and overlays.                                   |
+| NX-U50 | Repeated row actions use one reusable action owner and actual permission state.                       |
+| NX-U51 | Preserve meaningful accepted steps; do not collapse security/review/relationship decisions.           |
+| NX-U52 | Every step owns real state, validation, payload, failure and refresh behavior.                        |
+| NX-U53 | Remote relationship selection preserves selected summary, unavailable rows and explicit confirmation. |
+| NX-U54 | Equivalent details reuse navigation, field, reference, picker and history primitives.                 |
+| NX-U55 | History comes from a real event source and updates after relevant mutations.                          |
+| NX-U56 | Scope/permission explanation uses semantic labels and real references.                                |
+| NX-U57 | Credential operations need actual backend APIs and one-time-secret handling; no fake buttons.         |
+| NX-U58 | Browser evidence covers changed and adjacent states, console and network results.                     |
+| NX-U59 | Each filter dimension has one primary control owner, not duplicate chips and form inputs.             |
+
+## IX. Filters, Pagination and Complex Flows
+
+A search control must map to a supported API field. Use one keyword control when the producer supports combined search; do not invent server search semantics. Date ranges declare inclusive/exclusive boundaries and timezone. Pagination must use the producer's actual cursor/page contract and preserve total/next information.
+
+Remote selection debounces where appropriate, cancels stale work and preserves labels for selected IDs. “Select loaded” means loaded selectable rows; never claim all matching records unless the backend provides that contract.
+
+For complex pages, complete these steps before coding:
+
+1. State the user's real decision in one sentence.
+2. Draw the resource/dependency chain.
+3. Select list, scoped child, orchestration or layered-detail shape.
+4. Identify parent/child context and propagation.
+5. Allocate width by density and responsive behavior.
+6. Define each region's data contract, permissions and errors.
+7. For computed results such as prices, identify base inputs, overrides and authoritative result.
+8. Verify that every action has a real source, payload, result and refresh target.
+
+Draw the layout as boxes before styling; compare it to the accepted design. Do not replace meaningful user steps with an implementation shortcut.
+
+## X. Internationalization, Accessibility and Content
+
+Use the installed i18n owner for locale lists, fallback and route generation. API locale keys and browser language tags may differ; normalize at the boundary without rewriting backend identifiers. Do not duplicate locale option arrays in pages.
+
+Every interactive control needs an accessible name, keyboard operation and visible focus. Dialog close restores focus; error text links to its field. Test both themes and narrow/long-text states.
+
+SEO metadata uses the real canonical URL and actual content. Sitemap configuration cannot prove indexability; preview configuration cannot prove authenticated CMS integration. Assets need correct dimensions, alt semantics and legal ownership.
+
+## XI. Delivery and References
+
+Code comments explain why in Chinese. Exported APIs/composables document non-obvious contracts, lifetime and errors. Delete dead imports and commented code; do not introduce deferred production actions.
+
+Read [Architecture](architecture.md), [Security and Lifecycle](security-lifecycle.md), [Verification](verification.md) and the complete [Design Template](architecture-template.md).
+
+### Pre-commit Checklist
+
+- [ ] Real package versions, aliases and layer exports are used.
+- [ ] API and server-state owners remain separate from presentation.
+- [ ] SSR identity, hydration and disposal behavior are verified.
+- [ ] Private configuration never enters public payloads.
+- [ ] Every visible action maps to a real implementation and error path.
+- [ ] All applicable NX-S/A/T/C/H/E/M/P/U rules are checked.
+- [ ] Design coverage includes children, overlays and loading/empty/error/forbidden states.
+- [ ] `pnpm typecheck` and `pnpm build` pass for code/contract changes.
+- [ ] Browser and network evidence proves the touched interactions.
+- [ ] No uninstalled lint/test/authorization capability is claimed.