@xenterprises/nuxt-x-marketing 1.1.2 → 1.2.2

package/README.md

@@ -5,6 +5,7 @@ A comprehensive Nuxt layer for building marketing websites with 38+ pre-built co
 ## Features
 
 - **38+ Marketing Components** - Hero, Features, Pricing, Testimonials, Blog, Affiliate/Review, and more
+- **Consent-aware tracking** - Drop GTM/GA4/Clarity IDs in `app.config`, the cookie banner auto-fires them on accept
 - **Zero Required Props** - Every component works out of the box with sensible defaults
 - **Dark Mode Support** - All components support light and dark themes
 - **Responsive Design** - Mobile-first approach with tablet and desktop breakpoints
@@ -714,6 +715,81 @@ Cookie toast notification.
 />
 ```
 
+#### XMarkPrivacyCookieConsent
+
+**Consent-aware cookie banner + preferences modal that auto-fires tracking scripts.** Drop your GTM/GA4/Clarity IDs into `app.config.ts`, drop `<XMarkPrivacyCookieConsent />` into your layout, and the component handles banner display, consent storage, and dynamic script injection.
+
+```vue
+<!-- app.vue -->
+<template>
+  <div>
+    <NuxtPage />
+    <XMarkPrivacyCookieConsent
+      policy-url="/cookies"
+      privacy-url="/privacy"
+    />
+  </div>
+</template>
+```
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  xMarketing: {
+    tracking: {
+      gtmId: 'GTM-XXXXXXX',
+      ga4Id: 'G-XXXXXXXX',
+      clarityId: 'abc123def4',
+      // Optional escape hatch for anything else (Meta Pixel, Hotjar, etc.)
+      scripts: [
+        {
+          id: 'meta-pixel',
+          src: 'https://connect.facebook.net/en_US/fbevents.js',
+          category: 'marketing',
+          attrs: { async: '' },
+        },
+      ],
+      autoInject: true, // default
+    },
+  },
+})
+```
+
+Scripts only fire after the visitor grants consent for the matching category (analytics or marketing). On revisit, the client plugin auto-loads stored scripts immediately — no flash of banner.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `String` | `'We use cookies'` | Banner heading |
+| `message` | `String` | (see source) | Banner body text |
+| `acceptLabel` | `String` | `'Accept all'` | Accept button text |
+| `rejectLabel` | `String` | `'Reject all'` | Reject button text |
+| `saveLabel` | `String` | `'Save preferences'` | Save button text (modal) |
+| `policyLabel` | `String` | `'Read our policy'` | Policy link text |
+| `policyUrl` | `String` | — | Cookie policy URL |
+| `privacyUrl` | `String` | — | Privacy policy URL |
+| `prefsTitle` | `String` | `'Cookie preferences'` | Modal title |
+| `prefsDescription` | `String` | (see source) | Modal description |
+| `showCustomize` | `Boolean` | `true` | Show the Customize button |
+| `categories` | `Category[]` | (4 standard) | Categories shown in the modal |
+| `storageKey` | `String` | `'xMarketing.consent'` | localStorage key |
+| `forceShow` | `Boolean` | `false` | Force the banner open (e.g. from a "Manage cookies" link) |
+
+| Emit | Payload | When |
+|------|---------|------|
+| `@accept` | `Record<CategoryId, boolean>` | Visitor accepted all |
+| `@reject` | `Record<CategoryId, boolean>` | Visitor rejected all |
+| `@save` | `Record<CategoryId, boolean>` | Visitor saved preferences |
+
+**Underlying composable** — `useConsentTracking()` is auto-imported. Use it directly if you need to programmatically grant consent or read state:
+
+```ts
+const consent = useConsentTracking()
+consent.acceptAll()       // grant every category
+consent.rejectAll()       // grant only necessary
+consent.hasConsent('analytics')
+consent.state.value       // reactive { necessary, analytics, marketing, preferences }
+```
+
 #### XMarkGDPR
 
 GDPR cookie preference modal.

package/app/app.config.ts

@@ -71,6 +71,31 @@ export default defineAppConfig({
           "Welcome to our blog. Here you can find the latest news, updates, and articles.",
       },
     },
+    /**
+     * Tracking + analytics configuration consumed by
+     * `<XMarkPrivacyCookieConsent>` and `useConsentTracking()`.
+     *
+     * Convenience IDs (gtmId / ga4Id / clarityId) auto-generate the
+     * standard snippet for that tool. Use `scripts[]` for everything
+     * else (Meta Pixel, Hotjar, Segment, LinkedIn Insight, etc.).
+     *
+     * Scripts only fire after the visitor grants consent for the
+     * matching category (analytics or marketing).
+     */
+    tracking: {
+      // ---- Convenience IDs (string-only, zero-config) ----
+      /** Google Tag Manager container ID, e.g. "GTM-XXXXXXX". */
+      gtmId: undefined,
+      /** Google Analytics 4 measurement ID, e.g. "G-XXXXXXXX". */
+      ga4Id: undefined,
+      /** Microsoft Clarity project ID, e.g. "abc123def4". */
+      clarityId: undefined,
+      // ---- Escape hatch: arbitrary scripts ----
+      scripts: [],
+      // ---- Behavior ----
+      /** Auto-inject configured scripts on consent. Default: true. */
+      autoInject: true,
+    },
   },
 });
 
@@ -119,24 +144,67 @@ declare module "@nuxt/schema" {
           src?: string;
           alt?: string;
         };
-        socials?: {
-          name: string;
-          url: string;
-          icon: string;
-        }[];
-        columns?: {
-          headerLabel: string;
-          links: {
-            label: string;
-            to: string;
-            target?: string;
-          }[];
+socials?: {
+        name: string;
+        url: string;
+        icon: string;
+      }[];
+      columns?: {
+        headerLabel: string;
+        links: {
+          label: string;
+          to: string;
+          target?: string;
         }[];
-      };
+      }[];
+      /**
+       * Tracking + analytics config. Read by
+       * `<XMarkPrivacyCookieConsent>` and `useConsentTracking()`.
+       * Only fires after the matching consent category is granted.
+       */
+      tracking?: XMarketingTracking;
     };
   }
 }
 
+/**
+ * Tracking entry — use the convenience IDs for the common tools
+ * (GTM, GA4, Clarity) or `scripts[]` for everything else. Scripts
+ * are injected only after the visitor grants consent for the
+ * matching `category` (default: "analytics").
+ */
+interface XMarketingTracking {
+  /** Google Tag Manager container ID, e.g. "GTM-XXXXXXX". */
+  gtmId?: string;
+  /** Google Analytics 4 measurement ID, e.g. "G-XXXXXXXX". */
+  ga4Id?: string;
+  /** Microsoft Clarity project ID, e.g. "abc123def4". */
+  clarityId?: string;
+  /**
+   * Arbitrary scripts (Meta Pixel, Hotjar, Segment, LinkedIn Insight,
+   * Pinterest, TikTok, etc.). Each fires once the matching consent
+   * category is granted. Use `inline` for hand-written snippets like
+   * `gtag('js', new Date())`.
+   */
+  scripts?: XMarketingTrackingScript[];
+  /** Auto-inject configured scripts on consent. Default: true. */
+  autoInject?: boolean;
+}
+
+interface XMarketingTrackingScript {
+  /** Stable ID — used to dedupe re-injection. */
+  id: string;
+  /** External script URL (e.g. "https://www.googletagmanager.com/gtag/js?id=G-XXX"). */
+  src?: string;
+  /** Inline script body (no `src` required). */
+  inline?: string;
+  /** Consent category gate. "necessary" fires immediately; "analytics" / "marketing" gated. */
+  category?: "necessary" | "analytics" | "marketing";
+  /** Extra attributes applied to the injected <script>. */
+  attrs?: Record<string, string>;
+}
+}
+
 interface NavLink {
   label: string;
   to?: string;

package/app/app.vue

@@ -42,6 +42,11 @@
       :columns="footerColumns"
       :legal-links="legalLinks"
     />
+
+    <!-- Cookie consent banner — auto-shows on first visit and fires
+         any tracking scripts configured in app.config.xMarketing.tracking
+         once the visitor accepts. -->
+    <XMarkPrivacyCookieConsent policy-url="/cookies" privacy-url="/privacy" />
   </div>
 </template>
 <script setup>

package/app/components/X/Footer/index.vue

@@ -12,8 +12,14 @@
 			class="relative pt-24 overflow-hidden"
 			:class="footer?.bg?.color ? footer?.bg?.color : 'bg-gray-900'"
 		>
+			<!-- Dark overlay to guarantee readable white text regardless of bg image -->
+			<div
+				class="absolute inset-0 bg-gray-900/80"
+				aria-hidden="true"
+				v-if="footer?.bg?.img?.src"
+			></div>
 			<img
-				class="absolute left-1/2 bottom-0 h-full transform -translate-x-1/2"
+				class="absolute left-1/2 bottom-0 h-full transform -translate-x-1/2 opacity-30"
 				:src="footer?.bg?.img?.src"
 				:alt="footer?.bg?.img?.alt"
 				v-if="footer?.bg?.img?.src"
@@ -34,7 +40,7 @@
 								/>
 							</a>
 							<p
-								class="mb-8 text-gray-400 font-medium leading-relaxed max-w-lg mx-auto lg:mx-0"
+								class="mb-8 text-white font-medium leading-relaxed max-w-lg mx-auto lg:mx-0"
 							>
 								{{ footer?.body }}
 							</p>
@@ -66,7 +72,7 @@
 								:key="index"
 							>
 								<h3
-									class="mb-6 text-sm text-gray-500 uppercase font-semibold leading-normal tracking-wide"
+									class="mb-6 text-sm text-white uppercase font-semibold leading-normal tracking-wide"
 								>
 									{{ column?.headerLabel }}
 								</h3>
@@ -75,7 +81,7 @@
 										<nuxt-link
 											:to="link?.to"
 											:target="link?.target ? link?.target : '_self'"
-											class="text-white hover:text-gray-300 font-medium leading-relaxed transition-colors"
+											class="text-white hover:text-primary-300 font-medium leading-relaxed transition-colors"
 											>{{ link?.label }}</nuxt-link
 										>
 									</li>

package/app/components/X/Mark/Blog/Card.vue

@@ -1,47 +1,82 @@
 <template>
-	<article class="group">
-		<NuxtLink :to="`/blog/${post.slug}`" class="block">
+	<article
+		class="group flex flex-col h-full"
+		:class="featured && 'p-0'"
+	>
+		<!-- Clickable card surface (image, meta, title, excerpt, author) -->
+		<NuxtLink :to="postHref" class="block flex-1">
+			<!-- Featured ribbon -->
+			<div v-if="featured" class="mb-3">
+				<UBadge
+					label="Featured"
+					color="primary"
+					variant="solid"
+					size="md"
+				/>
+			</div>
+
 			<!-- Image -->
 			<figure
-				v-if="post.img?.src"
-				class="aspect-[16/9] rounded-xl overflow-hidden mb-4 xHover-zoom shadow-md transition-shadow duration-300 group-hover:shadow-xl"
+				v-if="imageSrc"
+				:class="[
+					'rounded-xl overflow-hidden xHover-zoom shadow-md transition-shadow duration-300 group-hover:shadow-xl',
+					featured
+						? 'aspect-[21/9] mb-6'
+						: 'aspect-[16/9] mb-4',
+				]"
 			>
 				<img
-					:src="post.img.src"
-					:alt="post.img.alt || post.title"
+					:src="imageSrc"
+					:alt="imageAlt"
 					class="w-full h-full object-cover"
 				/>
 			</figure>
 
 			<!-- Meta -->
-			<div class="flex items-center gap-3 mb-3">
+			<div class="flex items-center gap-3 mb-3 flex-wrap">
 				<UBadge
 					v-if="hasCategory && post.category"
 					:label="post.category"
 					variant="subtle"
 				/>
-				<time :datetime="post.date" class="text-sm text-neutral-500">
+				<time
+					v-if="post.date || post.publishedAt"
+					:datetime="post.date || post.publishedAt"
+					:class="featured ? 'text-base text-neutral-500' : 'text-sm text-neutral-500'"
+				>
 					{{ formattedDate }}
 				</time>
-				<span class="text-sm text-neutral-400">·</span>
-				<span class="text-sm text-neutral-500"
+				<span v-if="post.readingTime" class="text-sm text-neutral-400">·</span>
+				<span
+					v-if="post.readingTime"
+					:class="featured ? 'text-base text-neutral-500' : 'text-sm text-neutral-500'"
 					>{{ post.readingTime }} min read</span
 				>
 			</div>
 
 			<!-- Title -->
 			<h3
-				class="xText-title text-neutral-900 dark:text-white group-hover:text-primary-500 transition-colors"
+				:class="[
+					'text-neutral-900 dark:text-white group-hover:text-primary-500 transition-colors',
+					featured
+						? 'text-2xl sm:text-3xl lg:text-4xl font-bold leading-tight'
+						: 'xText-title',
+				]"
 			>
 				{{ post.title }}
 			</h3>
 
-			<!-- Excerpt -->
+			<!-- Excerpt / Description -->
 			<p
-				v-if="hasExcerpt && post.description"
-				class="mt-2 text-neutral-600 dark:text-neutral-400 line-clamp-2"
+				v-if="hasExcerpt && excerpt"
+				:class="[
+					'text-neutral-600 dark:text-neutral-400',
+					featured
+						? 'mt-4 text-base sm:text-lg leading-relaxed'
+						: 'mt-2 text-sm line-clamp-2',
+				]"
 			>
-				{{ post.description }}
+				{{ excerpt }}
 			</p>
 
 			<!-- Author -->
@@ -50,77 +85,149 @@
 					v-if="post.author.avatar"
 					:src="post.author.avatar"
 					:alt="post.author.name"
-					class="w-8 h-8 rounded-full object-cover"
+					:class="featured ? 'w-10 h-10 rounded-full object-cover' : 'w-8 h-8 rounded-full object-cover'"
 				/>
 				<div
 					v-else
-					class="w-8 h-8 rounded-full bg-primary-100 dark:bg-primary-900 flex items-center justify-center"
+					:class="featured
+						? 'w-10 h-10 rounded-full bg-primary-100 dark:bg-primary-900 flex items-center justify-center'
+						: 'w-8 h-8 rounded-full bg-primary-100 dark:bg-primary-900 flex items-center justify-center'"
 				>
 					<span
 						class="text-primary-600 dark:text-primary-400 font-medium text-sm"
 					>
-						{{ post.author.name.charAt(0) }}
+						{{ post.author.name?.charAt(0) }}
 					</span>
 				</div>
-				<span class="text-sm font-medium text-neutral-900 dark:text-white">
+				<span
+					:class="featured
+						? 'text-base font-medium text-neutral-900 dark:text-white'
+						: 'text-sm font-medium text-neutral-900 dark:text-white'"
+				>
 					{{ post.author.name }}
 				</span>
 			</div>
 		</NuxtLink>
 
-		<!-- Full Width Button -->
+		<!-- Full Width Button (always visible when `button` prop is passed) -->
 		<UButton
 			v-if="button?.label"
-			:to="`/blog/${post.slug}`"
+			:to="postHref"
 			:label="button.label"
-			:color="button.color || 'neutral'"
-			:variant="button.variant || 'outline'"
+			:color="button.color || 'primary'"
+			:variant="button.variant || 'solid'"
 			:icon="button.icon"
 			block
-			class="mt-4 justify-center"
+			:size="featured ? 'xl' : 'md'"
+			class="mt-4 w-full justify-center"
 		/>
 	</article>
 </template>
 
 <script setup>
 const props = defineProps({
-	/** Blog post object { title, slug, img?, excerpt?, date?, category?, author?, tags? } */
+	/**
+	 * Blog post object.
+	 * Accepted shapes (auto-detected):
+	 *   - { title, slug, img: { src, alt }?, excerpt?, date?, category?, author?, tags? }
+	 *   - Nuxt Content: { title, _path, path, image?, description?, publishedAt?, category?, author? }
+	 */
 	post: {
 		type: Object,
 		default: () => ({
 			title: "Blog Post Title",
 			slug: "#",
-			excerpt:
-				"A short description of this blog post that gives readers a preview of the content.",
-			date: new Date().toISOString(),
-			category: "General",
 		}),
 	},
-	/** Has category badge */
+	/** Show category badge */
 	hasCategory: {
 		type: Boolean,
 		default: true,
 	},
-	/** Has author info */
+	/** Show author info */
 	hasAuthor: {
 		type: Boolean,
 		default: true,
 	},
-	/** Has description */
+	/** Show excerpt / description */
 	hasExcerpt: {
 		type: Boolean,
 		default: true,
 	},
-	/** Optional full-width button { label, color?, variant?, icon? } */
+	/**
+	 * Optional full-width read-more button.
+	 * Shape: { label: string, color?: string, variant?: string, icon?: string }
+	 * Default theme uses `primary`/`solid`.
+	 */
 	button: {
 		type: Object,
 		default: null,
 	},
+	/**
+	 * Optional path prefix. Defaults to "/blog".
+	 * Posts with a full `_path` / `path` (e.g. "/blog/my-post") are used as-is.
+	 */
+	pathPrefix: {
+		type: String,
+		default: "/blog",
+	},
+	/**
+	 * Featured variant: wider image (21:9), larger title (up to 4xl),
+	 * un-clamped excerpt, larger author, "Featured" ribbon, xl button.
+	 */
+	featured: {
+		type: Boolean,
+		default: false,
+	},
+});
+
+// --- Resolved post fields (handle Nuxt Content + custom shapes) ------------
+
+const slug = computed(() => {
+	const p = props.post;
+	if (p.slug) return p.slug;
+	// Derive slug from Nuxt Content _path / path
+	const raw = p._path || p.path || "";
+	const stripped = raw.replace(/^\/+/, "");
+	if (!stripped) return "";
+	// _path might already be "/blog/foo" — return tail
+	return stripped.includes("/") ? stripped.split("/").pop() : stripped;
+});
+
+const postHref = computed(() => {
+	const p = props.post;
+	if (p._path) return p._path;
+	if (p.path) return p.path;
+	const s = slug.value;
+	if (!s || s === "#") return props.pathPrefix;
+	return `${props.pathPrefix}/${s}`;
+});
+
+const imageSrc = computed(() => {
+	const p = props.post;
+	if (p.img?.src) return p.img.src;
+	if (typeof p.img === "string" && p.img) return p.img;
+	if (typeof p.image === "string" && p.image) return p.image;
+	if (p.cover?.src) return p.cover.src;
+	return "";
+});
+
+const imageAlt = computed(() => {
+	const p = props.post;
+	if (p.img?.alt) return p.img.alt;
+	return p.title || "";
+});
+
+const excerpt = computed(() => {
+	const p = props.post;
+	return p.excerpt || p.description || "";
 });
 
 const formattedDate = computed(() => {
-	if (!props.post.date) return "";
-	const date = new Date(props.post.date);
+	const raw = props.post.date || props.post.publishedAt || "";
+	if (!raw) return "";
+	const date = new Date(raw);
+	if (Number.isNaN(date.getTime())) return "";
 	return date.toLocaleDateString("en-US", {
 		year: "numeric",
 		month: "short",

package/app/components/X/Mark/Privacy/CookieConsent.vue

@@ -0,0 +1,377 @@
+<template>
+  <Teleport to="body">
+    <!-- Bottom banner — shown until visitor makes a decision. -->
+    <Transition
+      enter-active-class="transition duration-200 ease-out"
+      enter-from-class="translate-y-full opacity-0"
+      enter-to-class="translate-y-0 opacity-100"
+      leave-active-class="transition duration-150 ease-in"
+      leave-from-class="translate-y-0 opacity-100"
+      leave-to-class="translate-y-full opacity-0"
+    >
+      <div
+        v-if="bannerVisible"
+        class="x-cookie-consent fixed inset-x-0 bottom-0 z-50 border-t border-neutral-200 bg-white shadow-2xl dark:border-neutral-800 dark:bg-neutral-950"
+        role="dialog"
+        aria-label="Cookie consent"
+      >
+        <div class="mx-auto flex max-w-6xl flex-col gap-3 p-4 sm:flex-row sm:items-center sm:p-6">
+          <div class="flex-1 text-sm text-neutral-700 dark:text-neutral-300">
+            <p class="font-semibold text-neutral-900 dark:text-white">
+              {{ title }}
+            </p>
+            <p class="mt-1">
+              {{ message }}
+              <NuxtLink
+                v-if="policyUrl"
+                :to="policyUrl"
+                class="text-primary hover:underline"
+              >
+                {{ policyLabel }}
+              </NuxtLink>
+            </p>
+          </div>
+          <div class="flex flex-wrap gap-2">
+            <UButton
+              v-if="showCustomize"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              @click="prefsOpen = true"
+            >
+              Customize
+            </UButton>
+            <UButton
+              color="neutral"
+              variant="outline"
+              size="sm"
+              @click="onRejectAll"
+            >
+              {{ rejectLabel }}
+            </UButton>
+            <UButton color="primary" size="sm" @click="onAcceptAll">
+              {{ acceptLabel }}
+            </UButton>
+          </div>
+        </div>
+      </div>
+    </Transition>
+
+    <!-- Preferences modal — shown when visitor clicks "Customize". -->
+    <UModal v-model:open="prefsOpen">
+      <template #content>
+        <div class="p-6">
+          <header class="mb-6">
+            <h3 class="text-xl font-semibold text-neutral-900 dark:text-white">
+              {{ prefsTitle }}
+            </h3>
+            <p class="mt-2 text-sm text-neutral-600 dark:text-neutral-400">
+              {{ prefsDescription }}
+            </p>
+          </header>
+
+          <div class="space-y-4">
+            <div
+              v-for="category in effectiveCategories"
+              :key="category.id"
+              class="rounded-xl border border-neutral-200 p-4 dark:border-neutral-700"
+            >
+              <div class="flex items-start justify-between gap-4">
+                <div class="flex-1">
+                  <div class="flex items-center gap-2">
+                    <h4 class="font-medium text-neutral-900 dark:text-white">
+                      {{ category.label }}
+                    </h4>
+                    <UBadge
+                      v-if="category.required"
+                      label="Required"
+                      size="xs"
+                      variant="subtle"
+                    />
+                  </div>
+                  <p class="mt-1 text-sm text-neutral-600 dark:text-neutral-400">
+                    {{ category.description }}
+                  </p>
+                </div>
+                <UToggle
+                  :model-value="selections[category.id]"
+                  :disabled="category.required"
+                  @update:model-value="(val) => (selections[category.id] = val)"
+                />
+              </div>
+            </div>
+          </div>
+
+          <footer class="mt-6 flex flex-col gap-3 sm:flex-row">
+            <UButton
+              :label="rejectLabel"
+              variant="ghost"
+              color="neutral"
+              class="flex-1"
+              @click="onRejectAll"
+            />
+            <UButton
+              :label="saveLabel"
+              variant="outline"
+              class="flex-1"
+              @click="onSaveSelected"
+            />
+            <UButton :label="acceptLabel" class="flex-1" @click="onAcceptAll" />
+          </footer>
+
+          <div
+            v-if="policyUrl || privacyUrl"
+            class="mt-4 border-t border-neutral-200 pt-4 text-center dark:border-neutral-700"
+          >
+            <div class="flex justify-center gap-4 text-sm">
+              <NuxtLink
+                v-if="privacyUrl"
+                :to="privacyUrl"
+                class="text-primary hover:underline"
+              >
+                Privacy Policy
+              </NuxtLink>
+              <NuxtLink
+                v-if="policyUrl"
+                :to="policyUrl"
+                class="text-primary hover:underline"
+              >
+                Cookie Policy
+              </NuxtLink>
+            </div>
+          </div>
+        </div>
+      </template>
+    </UModal>
+  </Teleport>
+</template>
+
+<script setup lang="ts">
+type CategoryId = "necessary" | "analytics" | "marketing" | "preferences";
+
+interface Category {
+  id: CategoryId;
+  label: string;
+  description: string;
+  required?: boolean;
+  /** Default toggle state on first show. Ignored when `required: true`. */
+  enabledByDefault?: boolean;
+}
+
+const props = withDefaults(
+  defineProps<{
+    /** Banner heading. */
+    title?: string;
+    /** Banner body text. */
+    message?: string;
+    /** Label on the Accept button. */
+    acceptLabel?: string;
+    /** Label on the Reject button. */
+    rejectLabel?: string;
+    /** Label on the Save Preferences button (in modal). */
+    saveLabel?: string;
+    /** Label of the policy link. */
+    policyLabel?: string;
+    /** URL of the cookie policy page. */
+    policyUrl?: string;
+    /** URL of the privacy policy page. */
+    privacyUrl?: string;
+    /** Modal title. */
+    prefsTitle?: string;
+    /** Modal description. */
+    prefsDescription?: string;
+    /** Show the Customize button in the banner. */
+    showCustomize?: boolean;
+    /** Categories shown in the preferences modal. */
+    categories?: Category[];
+    /** Cookie storage key. Override if you ship multiple consent UIs. */
+    storageKey?: string;
+    /** Force show the banner (e.g. via a "Manage cookies" link). */
+    forceShow?: boolean;
+  }>(),
+  {
+    title: "We use cookies",
+    message:
+      "We use cookies to enhance your browsing experience, analyze traffic, and improve our service. You can choose which categories to allow.",
+    acceptLabel: "Accept all",
+    rejectLabel: "Reject all",
+    saveLabel: "Save preferences",
+    policyLabel: "Read our policy",
+    prefsTitle: "Cookie preferences",
+    prefsDescription:
+      "Choose which categories of cookies you allow. You can change this anytime.",
+    showCustomize: true,
+    storageKey: "xMarketing.consent",
+    categories: () => [
+      {
+        id: "necessary",
+        label: "Strictly necessary",
+        description:
+          "Required for the site to function (auth, security, basic page state). Cannot be disabled.",
+        required: true,
+        enabledByDefault: true,
+      },
+      {
+        id: "analytics",
+        label: "Analytics",
+        description:
+          "Helps us understand how visitors interact with the site so we can improve it.",
+        enabledByDefault: false,
+      },
+      {
+        id: "marketing",
+        label: "Marketing",
+        description:
+          "Used to deliver personalized ads and measure campaign effectiveness.",
+        enabledByDefault: false,
+      },
+      {
+        id: "preferences",
+        label: "Preferences",
+        description: "Remembers your settings such as dark mode and locale.",
+        enabledByDefault: false,
+      },
+    ],
+  },
+);
+
+const emit = defineEmits<{
+  /** Emitted with the granted categories when the visitor accepts all. */
+  (e: "accept", state: Record<CategoryId, boolean>): void;
+  /** Emitted with the granted categories when the visitor rejects all. */
+  (e: "reject", state: Record<CategoryId, boolean>): void;
+  /** Emitted with the granted categories on Save Preferences. */
+  (e: "save", state: Record<CategoryId, boolean>): void;
+}>();
+
+const tracking = useConsentTracking();
+
+// The banner is visible if:
+//  - The parent forces it (forceShow), OR
+//  - The visitor hasn't made a decision yet (no localStorage key).
+const bannerVisible = ref(false);
+const prefsOpen = ref(false);
+const selections = ref<Record<CategoryId, boolean>>({});
+
+const effectiveCategories = computed(() => props.categories);
+
+function buildStateFromSelections(): Record<CategoryId, boolean> {
+  const out: Record<CategoryId, boolean> = {
+    necessary: true,
+    analytics: false,
+    marketing: false,
+    preferences: false,
+  };
+  for (const c of props.categories) {
+    out[c.id] = c.required ? true : Boolean(selections.value[c.id]);
+  }
+  return out;
+}
+
+function buildStateAll(value: boolean): Record<CategoryId, boolean> {
+  const out: Record<CategoryId, boolean> = {
+    necessary: true,
+    analytics: false,
+    marketing: false,
+    preferences: false,
+  };
+  for (const c of props.categories) {
+    out[c.id] = c.required ? true : value;
+  }
+  return out;
+}
+
+function initSelections() {
+  for (const c of props.categories) {
+    selections.value[c.id] = c.required
+      ? true
+      : Boolean(c.enabledByDefault ?? false);
+  }
+}
+
+function syncFromStored() {
+  if (typeof window === "undefined") return false;
+  const raw = window.localStorage.getItem(props.storageKey);
+  if (!raw) return false;
+  try {
+    const parsed = JSON.parse(raw);
+    for (const c of props.categories) {
+      selections.value[c.id] = c.required
+        ? true
+        : Boolean(parsed[c.id] ?? c.enabledByDefault ?? false);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+onMounted(() => {
+  if (typeof window === "undefined") return;
+  // Defer so we don't fight hydration.
+  queueMicrotask(() => {
+    const hadDecision = syncFromStored();
+    if (!hadDecision || props.forceShow) {
+      initSelections();
+      bannerVisible.value = true;
+    }
+  });
+});
+
+// If `forceShow` flips to true at runtime, show the banner.
+watch(
+  () => props.forceShow,
+  (v) => {
+    if (v) bannerVisible.value = true;
+  },
+);
+
+function persistAndBroadcast(state: Record<CategoryId, boolean>) {
+  if (typeof window === "undefined") return;
+  // Use the composable to handle storage + event dispatch + injection.
+  // We pass a shallow copy that matches ConsentState shape.
+  tracking.setConsent({
+    necessary: true,
+    analytics: Boolean(state.analytics),
+    marketing: Boolean(state.marketing),
+    preferences: Boolean(state.preferences),
+  });
+}
+
+function onAcceptAll() {
+  const state = buildStateAll(true);
+  for (const k of Object.keys(state)) {
+    selections.value[k as CategoryId] = state[k as CategoryId];
+  }
+  persistAndBroadcast(state);
+  bannerVisible.value = false;
+  prefsOpen.value = false;
+  emit("accept", state);
+}
+
+function onRejectAll() {
+  const state = buildStateAll(false);
+  for (const k of Object.keys(state)) {
+    selections.value[k as CategoryId] = state[k as CategoryId];
+  }
+  persistAndBroadcast(state);
+  bannerVisible.value = false;
+  prefsOpen.value = false;
+  emit("reject", state);
+}
+
+function onSaveSelected() {
+  const state = buildStateFromSelections();
+  persistAndBroadcast(state);
+  bannerVisible.value = false;
+  prefsOpen.value = false;
+  emit("save", state);
+}
+</script>
+
+<style scoped>
+.x-cookie-consent {
+  /* Sit above any sticky footer/CTA; matches the affiliate layer's banner. */
+  z-index: 50;
+}
+</style>

package/app/composables/useConsentTracking.ts

@@ -0,0 +1,297 @@
+/**
+ * useConsentTracking
+ *
+ * Reads `app.config.xMarketing.tracking` and dynamically injects
+ * scripts (GTM, GA4, Clarity, Meta Pixel, etc.) only after the
+ * matching consent category is granted.
+ *
+ * Decoupled from any specific UI — the cookie consent component
+ * fires a `consent:updated` window event with the granted category
+ * map, and this composable listens + reacts. Auto-runs on plugin
+ * load so re-visitors get scripts immediately (no flash of banner).
+ *
+ * Consent storage is shared with `<XMarkPrivacyCookieConsent>` via
+ * the `xMarketing.consent` localStorage key (JSON shape:
+ * `{ necessary: true, analytics: bool, marketing: bool, preferences: bool }`).
+ */
+
+import { computed, ref, watch } from "vue";
+
+export type ConsentCategory = "necessary" | "analytics" | "marketing" | "preferences";
+export type ConsentState = Record<ConsentCategory, boolean>;
+
+const STORAGE_KEY = "xMarketing.consent";
+const EVENT_NAME = "consent:updated";
+
+/** Default state — visitor hasn't decided yet. */
+const DEFAULT_STATE: ConsentState = {
+  necessary: true, // always true; required for the site to function
+  analytics: false,
+  marketing: false,
+  preferences: false,
+};
+
+/** SSR-safe no-op shared ref so server + client first-render agree. */
+const consentState = ref<ConsentState>(DEFAULT_STATE);
+let initialized = false;
+
+/**
+ * Read consent from localStorage and re-fire any tracking scripts the
+ * granted categories unlock. Called by the plugin on client mount.
+ */
+export function useConsentTracking() {
+  const appConfig = useAppConfig();
+  const tracking = computed(() => appConfig.xMarketing?.tracking ?? null);
+
+  const hasDecision = computed(() =>
+    typeof window !== "undefined" && window.localStorage.getItem(STORAGE_KEY) !== null,
+  );
+
+  function readStored(): ConsentState | null {
+    if (typeof window === "undefined") return null;
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      return { ...DEFAULT_STATE, ...parsed };
+    } catch {
+      return null;
+    }
+  }
+
+  function writeStored(state: ConsentState) {
+    if (typeof window === "undefined") return;
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  }
+
+  /**
+   * Apply a new consent decision — writes to storage, updates the
+   * shared ref, fires scripts, and notifies listeners via window event.
+   */
+  function setConsent(next: ConsentState) {
+    const merged = { ...DEFAULT_STATE, ...next, necessary: true };
+    consentState.value = merged;
+    writeStored(merged);
+    injectForState(merged);
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent(EVENT_NAME, { detail: merged }));
+    }
+  }
+
+  function acceptAll(): ConsentState {
+    const next: ConsentState = {
+      necessary: true,
+      analytics: true,
+      marketing: true,
+      preferences: true,
+    };
+    setConsent(next);
+    return next;
+  }
+
+  function rejectAll(): ConsentState {
+    const next: ConsentState = {
+      necessary: true,
+      analytics: false,
+      marketing: false,
+      preferences: false,
+    };
+    setConsent(next);
+    return next;
+  }
+
+  /** Re-apply stored consent — used on revisit to fire scripts immediately. */
+  function rehydrate() {
+    if (typeof window === "undefined") return;
+    const stored = readStored();
+    if (!stored) return;
+    consentState.value = stored;
+    injectForState(stored);
+  }
+
+  /** True when the visitor has granted consent for the given category. */
+  function hasConsent(category: ConsentCategory): boolean {
+    return Boolean(consentState.value[category]);
+  }
+
+  // ----------------------------------------------------------------
+  // Script injection
+  // ----------------------------------------------------------------
+
+  const injectedIds = new Set<string>();
+
+  function isInjected(id: string): boolean {
+    return injectedIds.has(id);
+  }
+
+  function markInjected(id: string) {
+    injectedIds.add(id);
+  }
+
+  function buildScriptList(): Array<{
+    id: string;
+    src?: string;
+    inline?: string;
+    category: ConsentCategory;
+    attrs?: Record<string, string>;
+  }> {
+    const cfg = tracking.value;
+    if (!cfg) return [];
+    const list: Array<{
+      id: string;
+      src?: string;
+      inline?: string;
+      category: ConsentCategory;
+      attrs?: Record<string, string>;
+    }> = [];
+
+    // GTM (loaded head + body noscript; GA4 / Clarity ride inside GTM
+    // when both are set, so we skip the standalone snippet to avoid
+    // double counting).
+    if (cfg.gtmId) {
+      const hasGtmHostsOthers = Boolean(cfg.ga4Id || cfg.clarityId);
+      if (!hasGtmHostsOthers) {
+        // No other IDs — still load GTM itself, but skip standalone GA4/Clarity below.
+      }
+      list.push({
+        id: `gtm-${cfg.gtmId}`,
+        src: `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(cfg.gtmId)}`,
+        category: "analytics",
+        attrs: { async: "", id: "gtm-script" },
+      });
+    }
+
+    // GA4 — only emit the standalone snippet if GTM isn't already
+    // managing it (avoids double page-view).
+    if (cfg.ga4Id && !cfg.gtmId) {
+      list.push({
+        id: `ga4-${cfg.ga4Id}`,
+        src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(cfg.ga4Id)}`,
+        category: "analytics",
+        attrs: { async: "" },
+      });
+      list.push({
+        id: `ga4-init-${cfg.ga4Id}`,
+        inline: `window.dataLayer = window.dataLayer || [];function gtag(){dataLayer.push(arguments);}gtag('js', new Date());gtag('config', '${cfg.ga4Id}', { anonymize_ip: true });`,
+        category: "analytics",
+      });
+    }
+
+    // Microsoft Clarity — only if GTM isn't managing it.
+    if (cfg.clarityId && !cfg.gtmId) {
+      list.push({
+        id: `clarity-${cfg.clarityId}`,
+        inline: `(function(c,l,a,r,i,t,y){c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);})(window, document, "clarity", "script", "${cfg.clarityId}");`,
+        category: "analytics",
+      });
+    }
+
+    // User-defined scripts. `Array.isArray` + iteration narrows the
+    // element type to `never` when the layer default is `[]`, so cast
+    // to the augmented type explicitly.
+    const customScripts = (cfg.scripts ?? []) as Array<{
+      id: string;
+      src?: string;
+      inline?: string;
+      category?: "necessary" | "analytics" | "marketing";
+      attrs?: Record<string, string>;
+    }>;
+    for (const s of customScripts) {
+      if (!s || !s.id) continue;
+      list.push({
+        id: s.id,
+        src: s.src,
+        inline: s.inline,
+        category: s.category ?? "analytics",
+        attrs: s.attrs,
+      });
+    }
+
+    return list;
+  }
+
+  function injectScript(entry: ReturnType<typeof buildScriptList>[number]) {
+    if (typeof document === "undefined") return;
+    if (isInjected(entry.id)) return;
+
+    const el = document.createElement("script");
+    if (entry.attrs) {
+      for (const [k, v] of Object.entries(entry.attrs)) {
+        if (v === "") {
+          // boolean attribute (e.g. `async`)
+          (el as unknown as Record<string, unknown>)[k] = true;
+          el.setAttribute(k, "");
+        } else {
+          el.setAttribute(k, v);
+        }
+      }
+    }
+    if (entry.src) {
+      el.src = entry.src;
+    } else if (entry.inline) {
+      el.textContent = entry.inline;
+    }
+    document.head.appendChild(el);
+    markInjected(entry.id);
+  }
+
+  function injectForState(state: ConsentState) {
+    if (typeof window === "undefined") return;
+    if (tracking.value?.autoInject === false) return;
+    for (const entry of buildScriptList()) {
+      if (state[entry.category]) injectScript(entry);
+    }
+  }
+
+  // ----------------------------------------------------------------
+  // Plugin init — listen for events from the banner + auto-load on revisit
+  // ----------------------------------------------------------------
+
+  function init() {
+    if (typeof window === "undefined" || initialized) return;
+    initialized = true;
+    rehydrate();
+    window.addEventListener(EVENT_NAME, ((ev: CustomEvent<ConsentState>) => {
+      consentState.value = ev.detail;
+      injectForState(ev.detail);
+    }) as EventListener);
+  }
+
+  // React to app.config changes — if the site adds a tracking ID at
+  // runtime (e.g. via HMR), honor it without requiring a full reload.
+  if (typeof window !== "undefined") {
+    watch(
+      () => [
+        tracking.value?.gtmId,
+        tracking.value?.ga4Id,
+        tracking.value?.clarityId,
+        tracking.value?.scripts,
+      ],
+      () => {
+        if (hasDecision.value) {
+          injectForState(consentState.value);
+        }
+      },
+      { deep: true },
+    );
+  }
+
+  return {
+    /** Reactive consent state — necessary/analytics/marketing/preferences. */
+    state: consentState,
+    /** Has the visitor made any decision yet? */
+    hasDecision,
+    /** Apply a full consent map. */
+    setConsent,
+    /** Accept all categories. */
+    acceptAll,
+    /** Reject non-essential categories. */
+    rejectAll,
+    /** Re-read storage and fire scripts (no event broadcast). */
+    rehydrate,
+    /** Has consent been granted for a single category? */
+    hasConsent,
+    /** Initialize listeners + rehydrate. Called by the client plugin. */
+    init,
+  };
+}

package/app/plugins/consent-tracking.client.ts

@@ -0,0 +1,16 @@
+/**
+ * Consent Tracking — Client Plugin
+ *
+ * Bootstraps the `useConsentTracking` composable on client mount so:
+ *   1. Returning visitors (already consented) get tracking scripts
+ *      loaded immediately, without waiting for any banner interaction.
+ *   2. First-time visitors see the banner; their accept/reject fires
+ *      the scripts via the `consent:updated` window event.
+ *
+ * Pair with `<XMarkPrivacyCookieConsent>` in your layout — the banner
+ * component itself uses the same composable and storage key.
+ */
+export default defineNuxtPlugin(() => {
+  const consent = useConsentTracking();
+  consent.init();
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@xenterprises/nuxt-x-marketing",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "1.1.2",
+  "version": "1.2.2",
   "main": "./nuxt.config.ts",
   "scripts": {
     "dev": "nuxi dev .playground",