@vc-shell/vc-app-skill 2.0.0-alpha.23 → 2.0.0-alpha.24

package/runtime/knowledge/patterns/details-blade-pattern.md

@@ -115,7 +115,7 @@ A details blade is a form-based panel opened from a list blade (or navigation) t
               :label="$t('MODULE.FIELDS.IS_ACTIVE.LABEL')"
             />
 
-            <!-- Date/DateTime field: VcInput type="datetime-local" -->
+            <!-- Date/DateTime field: VcDatePicker (preferred over VcInput type="datetime-local") -->
             <Field
               v-slot="{ errorMessage, handleChange, errors }"
               :label="$t('MODULE.FIELDS.CREATED_DATE.LABEL')"
@@ -123,10 +123,9 @@ A details blade is a form-based panel opened from a list blade (or navigation) t
               name="createdDate"
               rules="required"
             >
-              <VcInput
+              <VcDatePicker
                 v-model="entity.createdDate"
                 class="tw-p-3"
-                type="datetime-local"
                 :label="$t('MODULE.FIELDS.CREATED_DATE.LABEL')"
                 required
                 :error="!!errors.length"
@@ -134,6 +133,143 @@ A details blade is a form-based panel opened from a list blade (or navigation) t
                 @update:model-value="handleChange"
               />
             </Field>
+
+            <!-- Textarea field: for long text (description, notes, comments) -->
+            <Field
+              v-slot="{ errorMessage, handleChange, errors }"
+              :label="$t('MODULE.FIELDS.DESCRIPTION.LABEL')"
+              :model-value="entity.description"
+              name="description"
+            >
+              <VcTextarea
+                v-model="entity.description"
+                class="tw-p-3"
+                :label="$t('MODULE.FIELDS.DESCRIPTION.LABEL')"
+                :placeholder="$t('MODULE.FIELDS.DESCRIPTION.PLACEHOLDER')"
+                :error="!!errors.length"
+                :error-message="errorMessage"
+                @update:model-value="handleChange"
+              />
+            </Field>
+
+            <!-- Rich text / HTML field: VcEditor (WYSIWYG) -->
+            <Field
+              v-slot="{ errorMessage, handleChange, errors }"
+              :label="$t('MODULE.FIELDS.BODY.LABEL')"
+              :model-value="entity.body"
+              name="body"
+            >
+              <VcEditor
+                v-model="entity.body"
+                class="tw-p-3"
+                :label="$t('MODULE.FIELDS.BODY.LABEL')"
+                :error="!!errors.length"
+                :error-message="errorMessage"
+                @update:model-value="handleChange"
+              />
+            </Field>
+
+            <!-- Currency field: VcInputCurrency (formatted monetary input) -->
+            <Field
+              v-slot="{ errorMessage, handleChange, errors }"
+              :label="$t('MODULE.FIELDS.PRICE.LABEL')"
+              :model-value="entity.price"
+              name="price"
+              rules="required|min_value:0"
+            >
+              <VcInputCurrency
+                v-model="entity.price"
+                class="tw-p-3"
+                :label="$t('MODULE.FIELDS.PRICE.LABEL')"
+                currency="USD"
+                required
+                :error="!!errors.length"
+                :error-message="errorMessage"
+                @update:model-value="handleChange"
+              />
+            </Field>
+
+            <!-- Multi-select / Tags field: VcMultivalue -->
+            <VcMultivalue
+              v-model="entity.tags"
+              class="tw-p-3"
+              :label="$t('MODULE.FIELDS.TAGS.LABEL')"
+              :placeholder="$t('MODULE.FIELDS.TAGS.PLACEHOLDER')"
+            />
+
+            <!-- Checkbox field: alternative to VcSwitch for accept/agree semantics -->
+            <VcCheckbox
+              v-model="entity.agreeTerms"
+              class="tw-p-3"
+            >
+              {{ $t('MODULE.FIELDS.AGREE_TERMS.LABEL') }}
+            </VcCheckbox>
+
+            <!-- Radio group: for enum fields with 2-5 options -->
+            <VcRadioGroup
+              v-model="entity.priority"
+              class="tw-p-3"
+              :label="$t('MODULE.FIELDS.PRIORITY.LABEL')"
+              :options="priorityOptions"
+              option-value="id"
+              option-label="name"
+            />
+
+            <!-- Rating field: VcRating -->
+            <VcRating
+              v-model="entity.rating"
+              class="tw-p-3"
+              :label="$t('MODULE.FIELDS.RATING.LABEL')"
+            />
+
+            <!-- Slider field: VcSlider (numeric range) -->
+            <VcSlider
+              v-model="entity.discount"
+              class="tw-p-3"
+              :label="$t('MODULE.FIELDS.DISCOUNT.LABEL')"
+              :min="0"
+              :max="100"
+            />
+
+            <!-- Color field: VcColorInput -->
+            <VcColorInput
+              v-model="entity.brandColor"
+              class="tw-p-3"
+              :label="$t('MODULE.FIELDS.BRAND_COLOR.LABEL')"
+            />
+
+            <!-- Image upload field: VcImageUpload -->
+            <VcImageUpload
+              v-model="entity.avatar"
+              class="tw-p-3"
+              :label="$t('MODULE.FIELDS.AVATAR.LABEL')"
+            />
+
+            <!-- File upload field: VcFileUpload -->
+            <VcFileUpload
+              v-model="entity.attachment"
+              class="tw-p-3"
+              :label="$t('MODULE.FIELDS.ATTACHMENT.LABEL')"
+              :accept="'.pdf,.doc,.docx'"
+            />
+          </VcCol>
+        </VcRow>
+
+        <!-- Form sections with VcCard for visual grouping -->
+        <VcRow>
+          <VcCol>
+            <VcCard :header="$t('MODULE.SECTIONS.ADVANCED.TITLE')">
+              <!-- Group related fields inside a card -->
+            </VcCard>
+          </VcCol>
+        </VcRow>
+
+        <!-- Collapsible sections with VcAccordion -->
+        <VcRow>
+          <VcCol>
+            <VcAccordion :header="$t('MODULE.SECTIONS.SETTINGS.TITLE')">
+              <!-- Fields that are less frequently edited -->
+            </VcAccordion>
           </VcCol>
         </VcRow>
 
@@ -367,6 +503,163 @@ The `VcDataTable` here is read-only — no toolbar, no selection, no pagination
 
 ---
 
+## Read-Only Details Pattern (VcField)
+
+For details blades that display data without editing (e.g., order details, transaction history), use `VcField` instead of `VcInput`. This is a common pattern for view-only pages.
+
+Source: `apps/vendor-portal/src/modules/orders/pages/order-details.vue`
+
+```vue
+<VcCard :header="$t('MODULE.SECTIONS.INFO.TITLE')">
+  <div class="tw-p-4 tw-space-y-4">
+    <VcField
+      :label="$t('MODULE.FIELDS.ORDER_REF.LABEL')"
+      :model-value="entity.number || entity.id"
+      orientation="horizontal"
+      :aspect-ratio="[1, 2]"
+      copyable
+      type="text"
+    />
+    <VcField
+      :label="$t('MODULE.FIELDS.STATUS.LABEL')"
+      :model-value="entity.status"
+      orientation="horizontal"
+      :aspect-ratio="[1, 2]"
+      type="text"
+      :tooltip="$t('MODULE.FIELDS.STATUS.TOOLTIP')"
+    />
+    <VcField
+      :label="$t('MODULE.FIELDS.TOTAL.LABEL')"
+      :model-value="withCurrency(entity.total)"
+      orientation="horizontal"
+      :aspect-ratio="[1, 2]"
+      type="text"
+      class="tw-font-semibold"
+    />
+  </div>
+</VcCard>
+```
+
+Key `VcField` props:
+- `orientation="horizontal"` — label left, value right (default is vertical)
+- `:aspect-ratio="[1, 2]"` — label takes 1/3, value takes 2/3
+- `copyable` — adds a copy-to-clipboard button
+- `:tooltip` — adds an info icon with hover text
+
+Use `VcField` when:
+- The blade is read-only (order details, audit log, transaction view)
+- Showing summary/computed data that users don't edit
+- Displaying key-value pairs in a structured layout
+
+---
+
+## Contextual Banners Pattern (VcBanner)
+
+Use `VcBanner` at the top of a form to show contextual alerts, warnings, or informational messages based on entity state.
+
+Source: `apps/vendor-portal/src/modules/offers/pages/offers-details.vue`, `seller-details-edit.vue`
+
+```vue
+<!-- Error banner (shown conditionally) -->
+<VcBanner
+  v-if="errorMessage"
+  variant="danger"
+  icon="lucide-alert-circle"
+  icon-size="l"
+  icon-variant="danger"
+>
+  <template #title>
+    {{ $t("MODULE.ALERTS.ERROR") }}
+  </template>
+  <template #default>
+    {{ errorMessage }}
+  </template>
+</VcBanner>
+
+<!-- Info banner with action button -->
+<VcBanner
+  v-if="!entity.id"
+  variant="info"
+  icon="lucide-lightbulb"
+  icon-size="l"
+>
+  {{ $t("MODULE.ALERTS.CREATE_NEW_HINT") }}
+</VcBanner>
+
+<!-- Warning banner with inline action -->
+<VcBanner
+  v-if="entity.id && !entity.priceLists?.length"
+  variant="info"
+  icon="lucide-lightbulb"
+  icon-size="l"
+>
+  <div class="tw-flex tw-flex-row tw-justify-between tw-items-center">
+    <span>{{ $t("MODULE.ALERTS.MISSING_PRICES") }}</span>
+    <VcButton
+      icon="lucide-plus"
+      variant="link"
+      size="sm"
+      class="tw-shrink-0"
+      @click="openBlade({ name: 'PricesList' })"
+    >{{ $t("MODULE.ACTIONS.ADD_PRICE") }}</VcButton>
+  </div>
+</VcBanner>
+```
+
+Banner variants: `"info"`, `"warning"`, `"danger"`, `"success"`.
+
+Use banners when:
+- Entity is in a special state (new, error, incomplete)
+- User needs to take action (missing required data)
+- Showing validation errors at form level
+
+---
+
+## Blade Widgets Pattern (useBladeWidgets)
+
+Blade widgets appear as icon buttons in the blade sidebar, showing related entities with badge counts. Clicking a widget opens a child blade.
+
+Source: `apps/vendor-portal/src/modules/products/widgets/useProductWidgets.ts`
+
+```ts
+import { useBladeWidgets, type UseBladeWidgetsReturn } from "@vc-shell/framework";
+
+export function useProductWidgets(options: { item: Ref<Product | undefined> }): UseBladeWidgetsReturn {
+  const { item } = options;
+  const { openBlade } = useBlade();
+
+  const { count: offersCount, loading: offersLoading, refresh: refreshOffers } = useOfferCount(item);
+
+  const widgets = useBladeWidgets([
+    {
+      id: "OffersWidget",
+      icon: "lucide-tag",
+      title: "PRODUCTS.PAGES.DETAILS.WIDGETS.OFFERS",
+      badge: offersCount,
+      loading: offersLoading,
+      isVisible: computed(() => !!item.value?.id),
+      onClick: () => openBlade({ name: "Offers", options: { product: item.value } }),
+      onRefresh: refreshOffers,
+    },
+    // ... more widgets
+  ]);
+
+  return widgets;
+}
+```
+
+Use in the blade:
+```ts
+const { widgets } = useProductWidgets({ item: entity });
+```
+
+Use widgets when:
+- Entity has related sub-entities (product → offers, videos, assets)
+- You want sidebar navigation with counts
+- Each widget opens a different child blade
+
+---
+
 ## Key Rules
 
 1. **`defineBlade({ name: "XxxDetails" })`** — no `url`, no `isWorkspace` for blades opened from list. Add `url` + `isWorkspace: true` only for standalone workspace blades (settings pages, profile pages).
@@ -376,3 +669,57 @@ The `VcDataTable` here is read-only — no toolbar, no selection, no pagination
 5. **After save/delete**: always `callParent("reload")` first, then `closeSelf()`.
 6. **`isVisible`** on toolbar items: use `!!param.value` for edit-only actions (save, reset, delete), `!param.value` for create-only actions.
 7. **`disabled: computed(...)`** on toolbar items must be a computed, not a plain boolean, for reactivity.
+
+---
+
+## Field Type → Component Mapping
+
+Use this table to choose the correct component for each field type during generation. The `formField.type` value comes from the design prompt analysis (Phase 2 of `/vc-app design`) or from API type inference.
+
+| Field Type | Component | When to Use | Notes |
+|---|---|---|---|
+| `string` | `VcInput` | Default for short text (name, title, email, phone, URL) | Use `type="number"` for numeric strings, `rules="email"` for emails |
+| `text` | `VcTextarea` | Long text: description, notes, comments, bio | Multi-line input, no formatting |
+| `rich-text` | `VcEditor` | HTML content: article body, email template, product description | WYSIWYG HTML editor |
+| `number` | `VcInput` | Plain numbers: quantity, count, age, priority | Set `type="number"`, use `rules="bigint\|min_value:0"` |
+| `currency` | `VcInputCurrency` | Money: price, cost, amount, salary, budget | Formatted with currency symbol and decimals |
+| `boolean` | `VcSwitch` | Toggle: isActive, isEnabled, isPublished | No `Field` wrapper needed |
+| `boolean` | `VcCheckbox` | Consent/agree: agreeTerms, acceptPolicy | Use when "agree/accept" semantics, not toggle |
+| `date-time` | `VcDatePicker` | Date/datetime: createdDate, deadline, startDate, birthday | Calendar picker, preferred over `VcInput type="datetime-local"` |
+| `enum` | `VcSelect` | Dropdown: status, type, category (6+ options or dynamic) | Use `option-value` + `option-label` |
+| `enum` | `VcRadioGroup` | Radio: priority, type (2-5 static options) | More visual for small option sets |
+| `multi-select` | `VcMultivalue` | Tags/multi-pick: tags, categories, permissions, roles | Tag-style chips with add/remove |
+| `multi-select` | `VcCheckboxGroup` | Multi-check: features, capabilities (few static options) | Vertical checkbox list |
+| `rating` | `VcRating` | Star rating: rating, score, quality | 1-5 star picker |
+| `range` | `VcSlider` | Range: discount, opacity, volume, percentage | Numeric slider with min/max |
+| `color` | `VcColorInput` | Color: brandColor, backgroundColor, themeColor | Color picker with hex input |
+| `image` | `VcImageUpload` | Single image: avatar, logo, thumbnail, banner | Upload with preview |
+| `gallery` | `VcGallery` | Multiple images: productPhotos, screenshots | Multi-image management grid |
+| `file` | `VcFileUpload` | Attachment: document, contract, certificate | File upload with accept filter |
+
+### Selection heuristics (when type is ambiguous)
+
+When the field type from prompt analysis is plain `"string"`, use field name patterns to upgrade:
+
+| Field name pattern | Upgrade to |
+|---|---|
+| `description`, `notes`, `comment`, `bio`, `summary`, `about` | `text` → `VcTextarea` |
+| `body`, `content`, `html`, `template`, `article` | `rich-text` → `VcEditor` |
+| `price`, `cost`, `amount`, `total`, `salary`, `budget`, `fee` | `currency` → `VcInputCurrency` |
+| `avatar`, `logo`, `photo`, `thumbnail`, `banner`, `icon` | `image` → `VcImageUpload` |
+| `photos`, `images`, `screenshots`, `gallery` | `gallery` → `VcGallery` |
+| `file`, `attachment`, `document`, `contract`, `certificate` | `file` → `VcFileUpload` |
+| `tags`, `labels`, `categories`, `roles`, `permissions` | `multi-select` → `VcMultivalue` |
+| `rating`, `score`, `stars` | `rating` → `VcRating` |
+| `color`, `colour`, `brandColor`, `backgroundColor` | `color` → `VcColorInput` |
+| `discount`, `opacity`, `volume`, `percentage`, `progress` | `range` → `VcSlider` |
+| `email` | `string` → `VcInput` with `rules="required\|email"` |
+| `phone`, `tel` | `string` → `VcInput` with `type="tel"` |
+| `url`, `website`, `link` | `string` → `VcInput` with `type="url"` |
+
+### Layout heuristics
+
+- **3+ fields in a form** → use `VcRow` / `VcCol` grid to arrange fields in 2 columns
+- **5+ fields with logical groups** → wrap groups in `VcCard` with a section header
+- **8+ fields** → consider `VcAccordion` for secondary/advanced fields
+- **Mixed required + optional fields** → put required fields at the top, optional in a collapsible section

package/runtime/knowledge/patterns/extension-points-usage.md

@@ -0,0 +1,308 @@
+# Extension Points Usage Pattern
+
+Cross-module UI composition without compile-time dependencies. One module declares a named slot (host), other modules inject components into it (plugin). Fully reactive and order-independent.
+
+---
+
+## When to Use
+
+- Module A needs to inject UI into Module B without importing it (e.g., a "Commissions" section inside a "Seller Details" blade owned by another module).
+- Modules load in any order (including remote Module Federation modules).
+
+**Do not use** for simple parent-child communication within one module -- use props/slots/provide-inject instead.
+
+---
+
+## Core Concepts
+
+### Two Roles
+
+| Role | API | Purpose |
+|------|-----|---------|
+| **Host** | `<ExtensionPoint>` or `defineExtensionPoint()` | Declares a named region that accepts plugins |
+| **Plugin** | `useExtensionPoint()` | Registers components into a named region |
+
+Neither side imports the other. They communicate through a shared **name string**.
+
+### Order Independence
+
+Plugins can register components **before** the host declares the point. The reactive store preserves pre-registered components and upgrades the entry when the host declares.
+
+### Priority Sorting
+
+Components are sorted by `priority` (ascending, default `0`). Same priority = registration order.
+
+---
+
+## Inbound Extensions (Host Accepts Plugins)
+
+A module declares a named extension point in its blade template. Other modules inject components into it.
+
+### Declarative: `<ExtensionPoint>` Component
+
+The simplest approach -- declares the point and renders registered components in one step:
+
+```vue
+<!-- seller-details/pages/seller-details-edit.vue -->
+<template>
+  <VcBlade title="Seller Details">
+    <form><!-- main form fields --></form>
+
+    <ExtensionPoint
+      v-if="sellerDetails?.id"
+      name="seller:commissions"
+      wrapper-class="tw-p-2"
+    />
+  </VcBlade>
+</template>
+
+<script setup lang="ts">
+import { ExtensionPoint } from "@vc-shell/framework";
+</script>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | required | Extension point name |
+| `separator` | `boolean` | `false` | Adds `<hr>` before components |
+| `separatorClass` | `string` | built-in | Custom CSS class for `<hr>` |
+| `wrapperClass` | `string` | none | CSS class for wrapper div |
+| `gap` | `string` | none | CSS gap (e.g. `"1rem"`) |
+| `filter` | `Record<string, unknown>` | none | Filter by meta field equality |
+
+### Composable: `defineExtensionPoint()`
+
+For programmatic access to registered components (e.g., building tabs dynamically):
+
+```typescript
+import { defineExtensionPoint } from "@vc-shell/framework";
+
+interface TabMeta {
+  zone: "tabs" | "toolbar";
+  label: string;
+}
+
+const { components, hasComponents } = defineExtensionPoint<TabMeta>("product:details");
+
+// components.value is ComputedRef<ExtensionComponent[]>, sorted by priority
+// hasComponents.value is ComputedRef<boolean>
+```
+
+### Scoped Slot for Custom Rendering
+
+When the host needs full control over layout:
+
+```vue
+<ExtensionPoint name="order:actions" v-slot="{ components, hasComponents }">
+  <div v-if="hasComponents" class="tw-flex tw-gap-2">
+    <component
+      v-for="ext in components"
+      :key="ext.id"
+      :is="ext.component"
+      v-bind="ext.props || {}"
+    />
+  </div>
+</ExtensionPoint>
+```
+
+---
+
+## Outbound Extensions (Plugin Provides Components)
+
+A module registers components into an extension point declared by another module (or the framework itself).
+
+### Basic Registration
+
+```typescript
+// commissions-module/index.ts
+import { defineAppModule, useExtensionPoint } from "@vc-shell/framework";
+import CommissionFields from "./components/CommissionFields.vue";
+
+const { add } = useExtensionPoint("seller:commissions");
+add({
+  id: "marketplace:commission-fields",
+  component: CommissionFields,
+  props: { editable: true },
+  priority: 10,
+});
+
+export default defineAppModule({ /* locales, blades, etc. */ });
+```
+
+### Using Framework Constants
+
+The framework exposes typed constants for its own extension points:
+
+```typescript
+import { useExtensionPoint, ExtensionPoints } from "@vc-shell/framework";
+import RegistrationButton from "./components/RegistrationButton.vue";
+
+const { add } = useExtensionPoint(ExtensionPoints.AUTH_AFTER_FORM);
+add({
+  id: "registration:signup-button",
+  component: RegistrationButton,
+  meta: { type: "action" },
+});
+```
+
+Currently defined framework constants:
+
+| Constant | Value | Location |
+|----------|-------|----------|
+| `ExtensionPoints.AUTH_AFTER_FORM` | `"auth:after-form"` | Login page, below sign-in form |
+
+### Removing a Registration
+
+```typescript
+const { add, remove } = useExtensionPoint("seller:commissions");
+add({ id: "my-fields", component: MyFields });
+
+// Later (e.g., during cleanup):
+remove("my-fields");
+```
+
+---
+
+## Passing Props and Context to Injected Components
+
+Props are passed via the `props` field in `add()` and bound with `v-bind`:
+
+```typescript
+add({
+  id: "commission-fields",
+  component: CommissionFields,
+  props: { editable: true, sellerId: "abc-123" },
+  priority: 10,
+});
+```
+
+The injected component receives them as standard Vue props:
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{
+  editable?: boolean;
+  sellerId?: string;
+}>();
+</script>
+```
+
+For dynamic context that changes after registration, use reactive values or provide/inject within the host blade.
+
+---
+
+## Metadata Filtering
+
+Categorize extensions with `meta` and render different subsets in different locations:
+
+```typescript
+const { add } = useExtensionPoint("product:details");
+add({ id: "specs-tab",    component: SpecsTab,    meta: { zone: "tabs" },    priority: 10 });
+add({ id: "review-tab",   component: ReviewTab,   meta: { zone: "tabs" },    priority: 20 });
+add({ id: "quick-action", component: QuickAction,  meta: { zone: "toolbar" } });
+```
+
+```vue
+<template>
+  <VcBlade title="Product Details">
+    <div class="toolbar">
+      <ExtensionPoint name="product:details" :filter="{ zone: 'toolbar' }" />
+    </div>
+    <div class="tabs">
+      <ExtensionPoint name="product:details" :filter="{ zone: 'tabs' }" />
+    </div>
+  </VcBlade>
+</template>
+```
+
+Filtering uses strict equality (`===`) on every key-value pair; all pairs must match.
+
+---
+
+## Recipe: Adding a Custom Tab to Another Module's Blade
+
+**Step 1 -- Host module declares the point:**
+
+```vue
+<!-- orders/pages/order-details.vue -->
+<template>
+  <VcBlade title="Order Details">
+    <VcForm><!-- core order fields --></VcForm>
+
+    <ExtensionPoint
+      name="order:details-tabs"
+      gap="1rem"
+      wrapper-class="tw-mt-4"
+    />
+  </VcBlade>
+</template>
+
+<script setup lang="ts">
+import { ExtensionPoint } from "@vc-shell/framework";
+</script>
+```
+
+**Step 2 -- Plugin module registers a tab component:**
+
+```typescript
+// shipping-module/index.ts
+import { defineAppModule, useExtensionPoint } from "@vc-shell/framework";
+import ShippingTab from "./components/ShippingTab.vue";
+
+const { add } = useExtensionPoint("order:details-tabs");
+add({
+  id: "shipping:tracking-tab",
+  component: ShippingTab,
+  props: { showMap: true },
+  priority: 20,
+});
+
+export default defineAppModule({ /* ... */ });
+```
+
+**Step 3 -- The injected component:**
+
+```vue
+<!-- shipping-module/components/ShippingTab.vue -->
+<template>
+  <VcCard header="Shipping & Tracking">
+    <div class="tw-p-4">
+      <p>Carrier: {{ carrier }}</p>
+      <div v-if="showMap"><!-- map widget --></div>
+    </div>
+  </VcCard>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+defineProps<{ showMap?: boolean }>();
+const carrier = ref("FedEx");
+</script>
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Typo in extension point name | Component registered but never rendered | Check dev console for `"Extension point X is not declared"` warning. Use shared constants. |
+| Duplicate `id` across modules | Later registration silently replaces the earlier one | Prefix IDs with module name: `"shipping:tracking-tab"` |
+| Forgetting `import { ExtensionPoint }` in host template | Vue renders nothing (unknown component) | Add the import in `<script setup>` |
+| Calling `defineExtensionPoint` outside setup context | Computed refs not reactive | Call inside `<script setup>` or a composable used during setup |
+
+---
+
+## Related
+
+| Resource | Path |
+|----------|------|
+| Extension Points Plugin (full docs) | `framework/core/plugins/extension-points/extension-points.docs.md` |
+| Store implementation | `framework/core/plugins/extension-points/store.ts` |
+| ExtensionPoint component | `framework/core/plugins/extension-points/ExtensionPoint.vue` |
+| Types | `framework/core/plugins/extension-points/types.ts` |
+| Public API exports | `framework/core/plugins/extension-points/public.ts` |
+| Real-world host usage | `apps/vendor-portal/src/modules/seller-details/pages/seller-details-edit.vue` |
+| Framework host usage | `framework/shell/auth/LoginPage/components/login/Login.vue` |