@hagicode/hagilight 0.18.0 → 0.19.1-dev.184.1.830a4c6

package/README.md

@@ -112,7 +112,8 @@ The build warning reads `Hagilight SEO image <address> was kept as declared: its
 `hagilight()` writes `/llms.txt` after the build, following the [llms.txt](https://llmstxt.org/) layout: the site name as the H1, the home page description as a blockquote summary, and one H2 section of links per top-level path segment. It is generated from the built HTML, so it works for plain Astro and Starlight sites alike and needs no content collection.
 
 - Only one language is listed: the Astro `i18n.defaultLocale`, then the home page language. The home pages of the other languages go under `## Optional`.
-- Pages are left out when they are `noindex`, instant redirects, 404 pages, or declare a canonical URL for another page.
+- Pages are left out when they are `noindex`, meta-refresh redirects, 404 pages, or declare a canonical URL for another page.
+- A page that redirects as soon as it loads with a script can opt out with `<meta name="hagilight:llms" content="exclude">` in its `<head>`. Only the redirect page should carry it; a normal page keeps its entry.
 - Each link carries the page's meta description. A description repeated on three or more pages is treated as a site-wide default and left out of the links.
 - Section order is Overview first, then by page count. A section lists 12 links (Overview 36) and the file lists at most 120.
 - An `llms.txt` that the site already provides, as a public file or a page, is never overwritten. `hagilight({ enabled: false })` skips generation too.
@@ -120,8 +121,8 @@ The build warning reads `Hagilight SEO image <address> was kept as declared: its
 ```js
 hagilight({
   llms: {
-    title: 'Example Docs',        // default: the home page og:site_name
-    summary: 'What this site is.', // default: the home page description
+    title: 'Example Docs',        // default: the home page og:site_name; a configured value always wins
+    summary: 'What this site is.', // default: the home page description; a configured value always wins
     lang: 'en-US',                // default: i18n.defaultLocale
     maxLinksPerSection: 60,       // default: 12
     maxLinks: 200,                // default: 120
@@ -164,7 +165,7 @@ Pass `llms: false` (or `{ enabled: false }`) to opt out. The file is only as goo
     "llms": "/llms.txt"
   },
   "analytics": { "googleAnalytics": true, "fiftyOneLa": false, "posthog": true },
-  "features": { "seo": true, "promoto": true }
+  "features": { "seo": true, "promoto": true, "consent": true }
 }
 ```
 
@@ -178,7 +179,7 @@ Pass `llms: false` (or `{ enabled: false }`) to opt out. The file is only as goo
 
 ## PostHog
 
-`hagilight()` injects PostHog into the head of every page of a production build, with no analytics option, enabled flag, or project key. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://us.i.posthog.com`, and SDK defaults `2026-05-30`, the same as the Starlight and Docusaurus plugins. `astro dev` pages emit no loader. Injection does not depend on the `enabled` option, which controls only the sitemap and `robots.txt`.
+`hagilight()` injects PostHog into the head of every page of a production build, with no analytics option, enabled flag, or project key. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://t.hagicode.com` (managed proxy), UI host `https://us.posthog.com`, person profiles `identified_only`, and SDK defaults `2026-05-30`, the same as the Starlight and Docusaurus plugins. Sites with a strict script or connect policy must allow `t.hagicode.com`. `astro dev` pages emit no loader. Injection does not depend on the `enabled` option, which controls only the sitemap and `robots.txt`.
 
 | PostHog input | Behavior |
 | --- | --- |
@@ -194,7 +195,7 @@ hagilight({ analytics: { posthog: { apiKey: 'phc_Custom123' } } });
 hagilight({ analytics: { posthog: { enabled: false } } });
 ```
 
-The built-in key belongs to HagiCode, so a site that omits `analytics` sends its traffic to HagiCode's project. The loader initializes once per document. SDK defaults own navigation tracking; Hagilight adds no capture calls. Choose one initialization owner: a site that already renders `@hagicode/hagilight-core/PostHog` or another PostHog snippet should remove it or set `enabled: false`. When `@astrojs/starlight` is registered, this integration injects nothing and the Starlight plugin owns PostHog. The `analytics.posthog` flag in `hagilight.metadata.json` is `true` when the built pages contain the loader.
+The built-in key belongs to HagiCode, so a site that omits `analytics` sends its traffic to HagiCode's project. The loader initializes once per document. SDK defaults own navigation tracking. Hagilight also registers the site context once after initialization (`site_id` from `links.siteId` or the site URL's hostname, `site_framework` `astro`, `hagilight_version`, `locale` from `<html lang>`, and `page_type`), sets `capture_exceptions`, and sends `cta_click` for marked links through a click listener that works without Google Analytics; it adds no other capture calls. `page_type` is `other` unless a page sets it: pass the `pageType` prop to `SEOHead`, which emits `<meta name="hagilight:page-type">`, or render that meta element yourself. Choose one initialization owner: a site that already renders `@hagicode/hagilight-core/PostHog` or another PostHog snippet should remove it or set `enabled: false`. When `@astrojs/starlight` is registered, this integration injects nothing and the Starlight plugin owns PostHog. The `analytics.posthog` flag in `hagilight.metadata.json` is `true` when the built pages contain the loader.
 
 ## Body images
 
@@ -211,4 +212,8 @@ hagilight({ contentImages: { enabled: false } });
 
 Sites that do not use this integration can import the plugin from `@hagicode/hagilight-core` directly; its README describes the options and processor setup.
 
-See the [repository documentation](https://github.com/HagiCode-org/hagilight#readme) for RSS configuration, feed callback types, and integration behavior.
+See the [repository documentation](https://github.com/HagiCode-org/hagilight#readme) for RSS configuration, feed callback types, and integration behavior.
+
+### Consent
+
+`analytics.consent` (`enabled`, `privacyUrl`, `policyVersion`) applies to the PostHog this integration injects. With consent on (the default) the head carries an inert descriptor, the page mounts the popup and gate, and PostHog starts only after a grant. `enabled: false` injects PostHog immediately as before. Layouts that compose `<PostHog />`, `<GoogleAnalytics />` or `<Analytics51LA />` by hand pass `consent` to each component and render `<CookieConsent providers={...} />`.

package/SEOHead.astro

@@ -16,6 +16,7 @@ import {
   OG_IMAGE_WIDTH,
   classifyOgImage,
 } from '@hagicode/hagilight-core/og-image';
+import { POSTHOG_PAGE_TYPES, type PostHogPageType } from '@hagicode/hagilight-core/posthog-events';
 
 interface Props {
   page?: {
@@ -37,6 +38,8 @@ interface Props {
   ogType?: string;
   organization?: DefaultOrganizationOptions;
   defaultStructuredData?: boolean;
+  /** The PostHog page type for this page. Emitted as `<meta name="hagilight:page-type">` when in the vocabulary. */
+  pageType?: PostHogPageType;
 }
 
 const {
@@ -50,6 +53,7 @@ const {
   ogType,
   organization,
   defaultStructuredData = true,
+  pageType,
 } = Astro.props;
 const site = configuredSite?.toString();
 const currentPageUrl = site
@@ -131,6 +135,7 @@ const defaultValues = buildDefaultStructuredData({
 ---
 
 {composedHead.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}
+{(POSTHOG_PAGE_TYPES as readonly string[]).includes(pageType ?? '') && <meta name="hagilight:page-type" content={pageType} />}
 {[...defaultValues, ...dataValues].map((value) => (
   <script type="application/ld+json" set:html={serializeJsonLd(value)} />
 ))}

package/dist/integration.d.ts

@@ -43,6 +43,18 @@ export interface HagilightOptions {
 }
 export interface HagilightAnalyticsOptions {
     posthog?: HagilightPostHogOptions;
+    /**
+     * Strict prior consent for the PostHog this integration injects. On by default; `enabled: false` injects PostHog
+     * immediately as before. Components composed by hand take their own `consent` prop.
+     */
+    consent?: HagilightConsentOptions;
+}
+export interface HagilightConsentOptions {
+    enabled?: boolean;
+    /** An absolute HTTP(S) URL or a site-relative path for the privacy link. */
+    privacyUrl?: string;
+    /** Defaults to `1`. 1 to 32 letters, digits, dots, underscores or hyphens. */
+    policyVersion?: string;
 }
 export interface HagilightPostHogOptions {
     /** Defaults to true when the provider options are omitted, otherwise to whether `apiKey` is set. */

package/dist/integration.js

@@ -6,6 +6,8 @@ import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
 import { checkContentImageRegistration, registerContentImages } from '@hagicode/hagilight-core/content-images';
 import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
 import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN, posthogInitScript } from '@hagicode/hagilight-core/posthog';
+import { consentHeadScript } from '@hagicode/hagilight-core/consent-mount';
+import { validatePolicyVersion, validatePrivacyUrl } from '@hagicode/hagilight-core/consent-markup';
 import { resolveRssLocales } from '@hagicode/hagilight-core/rss';
 import { resolvePlainAstroRssOwner } from '@hagicode/hagilight-core/rss-ownership';
 import { resolveSiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
@@ -49,6 +51,33 @@ function resolvePostHogApiKey(analytics) {
 function integrationName(integration) {
     return isRecord(integration) ? integration.name : undefined;
 }
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+/** The plain-Astro site context: `site_id` is the configured site's hostname, when there is one. */
+/** Consent for the injected PostHog: on by default, and the core validators name any invalid option. */
+function resolveConsentOptions(analytics, posthogEnabled) {
+    const consent = isRecord(analytics) ? analytics.consent : undefined;
+    if (consent !== undefined && !isRecord(consent)) {
+        throw new TypeError('Hagilight analytics consent option must be an object.');
+    }
+    if (consent?.enabled !== undefined && typeof consent.enabled !== 'boolean') {
+        throw new TypeError('Hagilight analytics consent enabled option must be a boolean.');
+    }
+    return {
+        enabled: posthogEnabled && (consent?.enabled ?? true),
+        privacyUrl: validatePrivacyUrl(consent?.privacyUrl),
+        policyVersion: validatePolicyVersion(consent?.policyVersion),
+    };
+}
+function postHogSiteContext(site) {
+    let siteId;
+    try {
+        siteId = new URL(site).hostname || undefined;
+    }
+    catch {
+        siteId = undefined;
+    }
+    return { siteId, framework: 'astro', version: PACKAGE_VERSION };
+}
 function resolveDiscoverySite(site) {
     const message = 'Hagilight sitemap and robots require an absolute HTTP(S) Astro site URL. Set `site` in astro.config.mjs.';
     let parsed;
@@ -91,6 +120,7 @@ export function hagilight({ enabled = true, rss, contentImages, llms, metadata,
         throw new TypeError('Hagilight content images enabled option must be a boolean.');
     }
     const posthogApiKey = resolvePostHogApiKey(analytics);
+    const consent = resolveConsentOptions(analytics, posthogApiKey !== undefined);
     const llmsOptions = resolveLlmsOptions(llms);
     const metadataOptions = resolveSiteMetadataOption(metadata);
     const contentImagesEnabled = typeof contentImages === 'boolean' ? contentImages : contentImages?.enabled !== false;
@@ -128,7 +158,23 @@ export function hagilight({ enabled = true, rss, contentImages, llms, metadata,
                     // site gets PostHog from the Starlight plugin's generated Head instead.
                     const hasStarlight = (config.integrations ?? []).some((integration) => integrationName(integration) === '@astrojs/starlight');
                     if (posthogApiKey && command === 'build' && !hasStarlight) {
-                        injectScript('head-inline', posthogInitScript(posthogApiKey));
+                        if (consent.enabled) {
+                            // The loader travels inside an inert descriptor; the shared mount places the popup and starts PostHog
+                            // and its click sink only after a grant.
+                            const loader = posthogInitScript(posthogApiKey, postHogSiteContext(config.site));
+                            injectScript('head-inline', consentHeadScript({
+                                posthog: { apiKey: posthogApiKey, loader },
+                                config: { providers: ['posthog'], privacyUrl: consent.privacyUrl, policyVersion: consent.policyVersion },
+                            }));
+                            const mountModule = fileURLToPath(import.meta.resolve('@hagicode/hagilight-core/consent-mount'));
+                            injectScript('page', `import { mountConsent } from ${JSON.stringify(mountModule)};\nmountConsent();`);
+                        }
+                        else {
+                            injectScript('head-inline', posthogInitScript(posthogApiKey, postHogSiteContext(config.site)));
+                            // The click sink is independent of Google Analytics; it stays silent until window.posthog exists.
+                            const clickSink = fileURLToPath(import.meta.resolve('@hagicode/hagilight-core/posthog-events'));
+                            injectScript('page', `import { installPostHogClickTracking } from ${JSON.stringify(clickSink)};\ninstallPostHogClickTracking();`);
+                        }
                     }
                     if (!enabled)
                         return;

package/dist/llms.d.ts

@@ -33,6 +33,9 @@ export interface BuildLlmsTxtOptions {
 }
 export declare const DEFAULT_MAX_LINKS_PER_SECTION = 12;
 export declare const DEFAULT_MAX_LINKS = 120;
+/** `<meta name="hagilight:llms" content="exclude">` keeps an immediate-redirect page out of llms.txt. */
+export declare const LLMS_EXCLUDE_META_NAME = "hagilight:llms";
+export declare const LLMS_EXCLUDE_META_VALUE = "exclude";
 /**
  * Read the facts `llms.txt` needs from one built page. Returns `undefined` for pages that should
  * not be listed: `noindex`, instant redirects, 404 pages, and pages whose canonical URL points

package/dist/llms.js

@@ -8,6 +8,9 @@ export const DEFAULT_MAX_LINKS_PER_SECTION = 12;
 export const DEFAULT_MAX_LINKS = 120;
 const OVERVIEW_LIMIT_FACTOR = 3;
 const GENERIC_DESCRIPTION_MIN_PAGES = 3;
+/** `<meta name="hagilight:llms" content="exclude">` keeps an immediate-redirect page out of llms.txt. */
+export const LLMS_EXCLUDE_META_NAME = 'hagilight:llms';
+export const LLMS_EXCLUDE_META_VALUE = 'exclude';
 const LOCALE_SEGMENT = /^[a-z]{2,3}(?:-[a-z0-9]{2,8})?$/iu;
 const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
 function decodeEntities(value) {
@@ -74,6 +77,10 @@ export function parsePageMeta(html, pageUrl) {
         return undefined;
     if (metas.some((meta) => meta['http-equiv']?.toLowerCase() === 'refresh'))
         return undefined;
+    // A page that redirects as soon as it loads (for example an inline script) opts out explicitly.
+    if (metas.some((meta) => meta.name?.toLowerCase() === LLMS_EXCLUDE_META_NAME
+        && meta.content?.trim().toLowerCase() === LLMS_EXCLUDE_META_VALUE))
+        return undefined;
     const canonicalTag = [...head.matchAll(/<link\b[^>]*>/giu)]
         .map(([tag]) => attributes(tag))
         .find((link) => link.rel?.toLowerCase().split(/\s+/u).includes('canonical'));

package/dist/site-metadata.js

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CONSENT_DESCRIPTOR_ID } from '@hagicode/hagilight-core/consent-markup';
 import { buildSiteMetadata, detectAnalyticsLoaders, SITE_METADATA_PATH, } from '@hagicode/hagilight-core/site-metadata';
 import { findDiscoveryOutputs, writeSiteMetadata } from '@hagicode/hagilight-core/site-metadata-writer';
 import { parseHeadMeta } from './llms.js';
@@ -97,6 +98,8 @@ export function writeAstroSiteMetadata({ config, outDir, pages, build, options,
         build,
         discovery: findDiscoveryOutputs(outDir),
         analytics: detectAnalyticsLoaders(pageHtml),
+        // The popup is mounted exactly when a built page carries its config descriptor.
+        features: { consent: pageHtml.some((html) => html.includes(CONSENT_DESCRIPTOR_ID)) },
     });
     writeSiteMetadata({
         outDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight",
-  "version": "0.18.0",
+  "version": "0.19.1-dev.184.1.830a4c6",
   "type": "module",
   "description": "Astro integrations and components for HagiCode sites",
   "repository": {
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.7.4",
-    "@hagicode/hagilight-core": "0.18.0"
+    "@hagicode/hagilight-core": "0.19.1-dev.184.1.830a4c6"
   },
   "keywords": [
     "hagicode",