@getvitops/astro 0.9.0 → 2.0.0

package/dist/index.d.mts

@@ -1,7 +1,328 @@
-import { Format } from "@getvitops/generator";
+import { LegalOutput, SiteFont, StylesheetFormat } from "@getvitops/generator";
+import { generateIconInclude } from "@getvitops/utils";
 import { AstroIntegration } from "astro";
 export * from "@getvitops/utils";
 
+//#region src/analytics.d.ts
+/**
+ * The `<Analytics />` resolution layer — provider config in, the exact tags to
+ * emit out.
+ *
+ * Kept separate from `Analytics.astro` for the same reason `seo.ts` is separate
+ * from `Seo.astro`: everything decidable is a pure function and asserted in
+ * `analytics.test.ts`, and the component only renders what this returns.
+ *
+ * Two properties here are the point of the whole file:
+ *
+ *  - **Which consent category a provider needs is derived, never declared.** It
+ *    follows from whether that provider sets cookies, which follows from its own
+ *    configuration (Matomo with `disableCookies` is genuinely cookieless; Matomo
+ *    with `cookies: true` is not). A consumer cannot mark Google Analytics
+ *    `necessary` to skip a banner, because `setsCookies` isn't theirs to set.
+ *  - **The same fact drives the legal documents.** `@getvitops/generator`'s
+ *    `legal/providers.ts` maps the *site config's* `analytics` block onto named
+ *    processors with cookie lists. If a provider is configured here but not
+ *    there, the site runs a tag its own cookie notice doesn't disclose — so the
+ *    integration warns, and `warnings` is returned as data so that check is a
+ *    test rather than a log line someone might scroll past.
+ */
+/**
+ * When a tag is allowed to load. Third-party analytics is never worth a
+ * millisecond of the critical path, so the default puts every tag after `load`.
+ */
+type AnalyticsStrategy = 'idle' | 'async' | 'interaction';
+/**
+ * The consent vocabulary, mirroring `@getvitops/core`'s `consent/store.ts`.
+ * Mirrored rather than imported because this value is `JSON.stringify`d into the
+ * virtual module and the component reads it at build time, while core's copy is a
+ * browser runtime — `consent.test.ts` and `analytics.test.ts` pin both ends.
+ */
+type ConsentCategory = 'necessary' | 'analytics' | 'marketing' | 'preferences';
+type OptionalConsentCategory = Exclude<ConsentCategory, 'necessary'>;
+interface GoogleAnalyticsOptions {
+  /** Measurement ID, e.g. `G-XXXXXXXXXX`. */
+  id: string;
+  /**
+   * Which category gates it (default `analytics`). Set `marketing` when the
+   * property feeds Google Ads — the tag is the same, the permission isn't.
+   */
+  category?: OptionalConsentCategory;
+  /** Extra `gtag('config', id, …)` parameters, e.g. `{ send_page_view: false }`. */
+  config?: Record<string, string | number | boolean>;
+}
+interface ClarityOptions {
+  /** Clarity project ID. */
+  id: string;
+  category?: OptionalConsentCategory;
+}
+interface MatomoOptions {
+  /** Instance base URL — self-hosted, or `https://<you>.matomo.cloud`. */
+  url: string;
+  /** Site ID within that instance. */
+  siteId: string | number;
+  /**
+   * Let Matomo set its cookies (default **false**).
+   *
+   * The default is what makes Matomo the cookieless option: with
+   * `disableCookies` it stores no identifier on the device, needs no banner, and
+   * the generated cookie notice can state positively that it sets none. Turning
+   * this on gives you returning-visitor metrics and a consent obligation.
+   */
+  cookies?: boolean;
+}
+interface PlausibleOptions {
+  /** The domain as registered in Plausible, e.g. `example.com`. */
+  domain: string;
+  /** Script URL — override for a self-hosted instance or a custom-events build. */
+  src?: string;
+}
+interface GetvitopsAnalyticsOptions {
+  googleAnalytics?: string | GoogleAnalyticsOptions;
+  clarity?: string | ClarityOptions;
+  matomo?: MatomoOptions;
+  plausible?: string | PlausibleOptions;
+  /** When tags load (default `'idle'`). */
+  strategy?: AnalyticsStrategy;
+}
+/**
+ * The consent gate, configured on the integration rather than inside `analytics`.
+ *
+ * That placement is the design, not an accident: analytics is one consumer of
+ * consent, not its owner. A/B assignment, account personalisation and third-party
+ * embeds gate on the same choice via `data-consent`, and a site can enable the
+ * banner with no analytics configured at all.
+ */
+interface GetvitopsConsentOptions {
+  /**
+   * Categories the banner offers. Defaults to the ones the configured providers
+   * actually need — offering a choice nothing is waiting on is noise.
+   */
+  categories?: OptionalConsentCategory[];
+  /** Link the banner to the cookie notice (`vitops legal` renders one). */
+  policyUrl?: string;
+}
+/** One tag, fully resolved. */
+interface ResolvedTag {
+  key: 'googleAnalytics' | 'clarity' | 'matomo' | 'plausible';
+  /** The provider as a reader would recognise it — used in warnings. */
+  provider: string;
+  category: ConsentCategory;
+  setsCookies: boolean;
+  /** Names (or `prefix*` patterns) to clear when consent is withdrawn. */
+  cookies: string[];
+  strategy: AnalyticsStrategy;
+  /**
+   * Emitted inert (`type="text/plain"`) for the runtime to activate, rather than
+   * as a live `<script>`. False only for the one case that needs no runtime at
+   * all: a cookieless provider with `strategy: 'async'`.
+   */
+  gated: boolean;
+  /** Bootstrap JS. Runs before `src`, so a queue is populated before it drains. */
+  inline: string;
+  src: string | null;
+  attrs: Record<string, string>;
+}
+interface ResolvedAnalytics {
+  tags: ResolvedTag[];
+  /** Does anything here need `@getvitops/core/consent` loaded? */
+  needsRuntime: boolean;
+  /** Configuration problems, as prose. The integration logs these. */
+  warnings: string[];
+}
+interface ResolveAnalyticsContext {
+  /** Is the consent gate enabled on this site (`getvitops({ consent })`)? */
+  consent?: boolean;
+}
+/**
+ * Resolve the configured providers into the tags to emit.
+ *
+ * An invalid provider is dropped with a warning rather than throwing: one
+ * malformed ID should not take down a build, and a missing tag is visible in the
+ * output while a failed build is just a red wall.
+ */
+declare function resolveAnalytics(opts: GetvitopsAnalyticsOptions | undefined, ctx?: ResolveAnalyticsContext): ResolvedAnalytics;
+/** Which optional categories a set of tags actually needs a visitor to decide. */
+declare function consentCategories(tags: ResolvedTag[]): OptionalConsentCategory[];
+//#endregion
+//#region src/seo.d.ts
+/**
+ * The `<Seo />` resolution layer — site-level defaults merged with per-page props
+ * into the exact tags to emit.
+ *
+ * Kept separate from `Seo.astro` deliberately. The component this replaces
+ * (`SEO.astro`, deleted in c949cae) fused resolution with markup, which is why it
+ * was never unit-tested and why its title handling drifted: it computed a title
+ * for `og:title` but left `<title>` to the layout, so the two could disagree.
+ * Everything decidable lives here and is asserted in `seo.test.ts`; the component
+ * only renders what this returns.
+ */
+/** Twitter card types, per <https://developer.x.com/en/docs/twitter-for-websites/cards>. */
+type SeoTwitterCard = 'summary' | 'summary_large_image' | 'app' | 'player';
+/** Open Graph object types this component knows how to describe. */
+type SeoOgType = 'website' | 'article' | 'profile';
+/**
+ * Site-level SEO defaults, passed to `getvitops({ seo })` and baked into the
+ * `virtual:getvitops/head` module. Per-page `<Seo />` props override these.
+ *
+ * The vocabulary mirrors the site-config schema's `seo` block
+ * (`@getvitops/generator`, `src/site.ts`) so a `SiteConfig` → these adapter would
+ * be a flat field map — but it is not imported from there. This is the
+ * integration's own option surface, and it must stay JSON-serialisable: it is
+ * `JSON.stringify`d into the virtual module, so no functions, no `URL`s, no dates.
+ */
+interface GetvitopsSeoOptions {
+  /** `og:site_name`, and the `<title>` when a page passes none. */
+  siteName?: string;
+  /**
+   * Page-title pattern; `%s` is the page's own title. e.g. `'%s · Acme'`.
+   *
+   * Applies to `<title>` only. `og:title`/`twitter:title` get the untemplated
+   * title: a social card already shows `og:site_name` and the domain, so the
+   * suffix would sit directly above the brand it repeats. Override per page with
+   * `ogTitle`.
+   *
+   * Skipped when a page's title already equals `siteName` — a homepage titled
+   * "Acme" emits `Acme`, not `Acme · Acme` — and never applied to `defaultTitle`.
+   */
+  titleTemplate?: string;
+  /** `<title>` for pages that pass none. Used verbatim — the template is not applied. */
+  defaultTitle?: string;
+  /** `<meta name="description">` for pages that pass none. */
+  defaultDescription?: string;
+  /** Site-wide robots directive, e.g. `'index,follow,max-image-preview:large'`. */
+  robots?: string;
+  /** Google Search Console verification token. */
+  googleSiteVerification?: string;
+  /** Bing Webmaster Tools verification token. */
+  bingSiteVerification?: string;
+  openGraph?: {
+    /** Default `og:type` (default `'website'`). */type?: SeoOgType; /** `og:locale`. Written either way — `en-CA` and `en_CA` both emit `en_CA`. */
+    locale?: string; /** Additional locales the same content exists in → `og:locale:alternate`. */
+    localeAlternates?: string[]; /** Fallback share image. Relative URLs resolve against `site`. */
+    image?: {
+      url: string;
+      alt?: string;
+      width?: number;
+      height?: number;
+      type?: string;
+    };
+  };
+  twitter?: {
+    /** Card type when no image resolves (default `'summary'`). */card?: SeoTwitterCard; /** The site's own handle, `@acme`. */
+    site?: string; /** Default author handle, `@ada`. */
+    creator?: string;
+  };
+}
+/** Per-page `<Seo />` props. Everything is optional; defaults fill the gaps. */
+interface SeoProps {
+  /** Page title, before `titleTemplate` is applied. */
+  title?: string;
+  /**
+   * `og:title`/`twitter:title`, when the social headline should differ from
+   * `title`. Defaults to `title` **without** `titleTemplate` — see the note on
+   * `titleTemplate` for why the suffix is dropped there.
+   */
+  ogTitle?: string;
+  description?: string;
+  /** Overrides the computed canonical. Relative values resolve against `site`. */
+  canonical?: string;
+  /** Overrides `og:site_name` and the title fallback. */
+  siteName?: string;
+  /** Share image for this page. Relative URLs resolve against `site`. */
+  image?: string;
+  imageAlt?: string;
+  imageWidth?: number;
+  imageHeight?: number;
+  /** MIME type of the share image, e.g. `'image/png'`. */
+  imageType?: string;
+  noindex?: boolean;
+  nofollow?: boolean;
+  noarchive?: boolean;
+  nocache?: boolean;
+  /** Extra robots directives, e.g. `'max-snippet:-1'`. Appended to the composed value. */
+  robotsExtras?: string;
+  /** Full robots override. Wins over the flags above and the site default. */
+  robots?: string;
+  /** `og:type` for this page (default: the site default, else `'website'`). */
+  type?: SeoOgType;
+  /** Emitted only when `type` is `'article'`. */
+  article?: {
+    publishedTime?: string;
+    modifiedTime?: string;
+    expirationTime?: string;
+    authors?: string[];
+    section?: string;
+    tags?: string[];
+  };
+  /** `og:locale` for this page. */
+  locale?: string;
+  /** Twitter author handle for this page, `@ada`. */
+  twitterCreator?: string;
+  /**
+   * Translations of *this* page, as `<link rel="alternate" hreflang>`.
+   *
+   * Explicit only, and it must include the current page. Nothing is inferred:
+   * the deleted component derived alternates from the site's locale list and
+   * pointed every one of them at that locale's homepage, so every page on the
+   * site claimed the homepage as its translation. Only the page knows its own
+   * translated URLs. Pass `hreflang: 'x-default'` for the fallback entry.
+   */
+  alternates?: {
+    hreflang: string;
+    href: string;
+  }[];
+}
+/** A `<meta property>` tag (Open Graph uses `property`, not `name`). */
+interface SeoPropertyTag {
+  property: string;
+  content: string;
+}
+/** A `<meta name>` tag. */
+interface SeoNameTag {
+  name: string;
+  content: string;
+}
+/** Everything `<Seo />` renders, already decided. `null` means "emit nothing". */
+interface ResolvedSeo {
+  title: string | null;
+  /** `og:title`/`twitter:title` — the page title without `titleTemplate`. */
+  socialTitle: string | null;
+  description: string | null;
+  canonical: string | null;
+  robots: string | null;
+  openGraph: SeoPropertyTag[];
+  twitter: SeoNameTag[];
+  verification: SeoNameTag[];
+  alternates: {
+    hreflang: string;
+    href: string;
+  }[];
+}
+/** Render context supplied by the component from `Astro`. */
+interface SeoContext {
+  /**
+   * The deployed origin — `Astro.site`, or `config.site` via the virtual module.
+   *
+   * `undefined` when neither is set, and then every absolute-URL tag is dropped
+   * rather than being derived from the request. `astro-seo` falls back to
+   * `Astro.url` here; on a static build that is `http://localhost:4321`, which
+   * would bake a localhost canonical into production HTML.
+   */
+  site?: URL | undefined;
+  /** `Astro.url.pathname` — already includes `base`. */
+  pathname: string;
+  /** `Astro.url.search`, if the canonical should keep the query string. */
+  search?: string;
+}
+/**
+ * Merges site defaults with page props into the final tag set.
+ *
+ * Pure — no `Astro`, no filesystem, no config lookup. Everything it needs comes
+ * through its three arguments, which is what makes it testable and what keeps the
+ * package free of the consumer-global coupling that sank the previous site model.
+ */
+declare function resolveSeo(defaults: GetvitopsSeoOptions, props: SeoProps, ctx: SeoContext): ResolvedSeo;
+//#endregion
 //#region src/integration.d.ts
 interface GetvitopsFaviconOptions {
   /** Source SVG or PNG. */
@@ -14,10 +335,28 @@ interface GetvitopsFaviconOptions {
   backgroundColor?: string;
 }
 interface GetvitopsCssOptions {
-  /** Path to design-system.json (default 'design-system.json'). */
+  /**
+   * Path to the config (default `'design-system.json'`).
+   *
+   * May be a `design-system.json` **or** the larger site config that embeds one
+   * (`company.json` / `site.json`) — they are told apart by shape. Pointing this
+   * at a site config makes the top-level `site` option redundant and lets
+   * `legal` and `fonts` default their own `input` to it, so the path is declared
+   * once.
+   */
   input?: string;
-  /** Output format (default 'tailwind'). */
-  format?: Format;
+  /**
+   * Which `designSystem.themes` entry to build, when `input` is a site config.
+   * Default: the config's `defaultTheme`, else `default`.
+   */
+  theme?: string;
+  /**
+   * Output format (default 'tailwind'). Narrower than the generator's `Format`
+   * on purpose: this option exists to produce a stylesheet to inject, and the
+   * `design` format emits only `DESIGN.md`. Run that one via the CLI
+   * (`vitops generate --format design --out .`).
+   */
+  format?: StylesheetFormat;
   /** Directory the generated CSS is written to (default 'src/styles'). */
   out?: string;
   /**
@@ -28,8 +367,120 @@ interface GetvitopsCssOptions {
    * only your own pages (and previews rendered through them) are styled.
    */
   inject?: boolean;
+  /**
+   * Also flip to dark when the visitor's OS asks and they have made no explicit
+   * choice — `@media (prefers-color-scheme: dark)`.
+   *
+   * Off by default: turning it on flips the site dark for dark-OS visitors, which
+   * is a visible change to an existing site. Turning it **on** is what makes
+   * `<color-scheme-toggle>`'s "System" position do anything (System removes the
+   * theme attribute, so without this block it falls through to light), and it is
+   * the only way a no-JS page gets the OS appearance at all.
+   *
+   * The site config's `designSystem.defaultColorScheme: "system"` says the same thing and is the
+   * better home for it when you have one — this option wins if both are set, and
+   * exists because requiring a whole `SiteConfig` to set one boolean would be out
+   * of proportion.
+   */
+  systemColorScheme?: boolean;
+}
+interface GetvitopsSiteOptions {
+  /** Path to the site config (JSON). */
+  input: string;
+  /** Environment whose A/B variant applies (default 'production'). */
+  siteEnv?: string;
+}
+interface GetvitopsLegalOptions {
+  /**
+   * Path to the site config (JSON) the documents are rendered from. Optional
+   * when the top-level `site` option is set — it defaults to that file, since
+   * they are almost always the same one.
+   */
+  input?: string;
+  /**
+   * Where to write them (default 'src/content/legal'). The default is a content
+   * collection: the documents are markdown, and a collection is what lets a page
+   * render one through your own layout rather than the integration injecting a
+   * route (which nothing in this package does).
+   */
+  out?: string;
+  /** Output format (default 'md'). */
+  format?: LegalOutput;
+  /** Environment whose A/B variant applies (default 'production'). */
+  siteEnv?: string;
+}
+/** `changefreq`, mirroring @astrojs/sitemap's `ChangeFreq`. */
+type GetvitopsSitemapChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+/** One sitemap entry, mirroring @astrojs/sitemap's `SitemapItem`. */
+interface GetvitopsSitemapEntry {
+  url: string;
+  lastmod?: string;
+  changefreq?: GetvitopsSitemapChangeFreq;
+  priority?: number;
+  /** Alternate-language variants. `lang` is required, as upstream requires it. */
+  links?: {
+    lang: string;
+    hreflang?: string;
+    url: string;
+  }[];
+}
+/**
+ * Forwarded verbatim to `@astrojs/sitemap`. Deliberately a hand-written subset of
+ * its `SitemapOptions` rather than a re-export: aliasing would put an
+ * `import … from '@astrojs/sitemap'` — and, transitively via `SitemapItem`, from
+ * `sitemap` — into this package's published .d.mts, which cannot resolve for the
+ * consumers who don't install the optional peer. Worse, `skipLibCheck` (on by
+ * default via astro's base tsconfig) *suppresses* that error, silently degrading
+ * the option to `any` instead of failing loudly.
+ *
+ * Need something not listed here (e.g. `chunks`)? Add `sitemap()` to your own
+ * `integrations` array — getvitops detects it and leaves yours in charge.
+ */
+interface GetvitopsSitemapOptions {
+  /** Keep a page out of the sitemap. Receives the page's full absolute URL. */
+  filter?: (page: string) => boolean;
+  /** Absolute URLs of pages Astro doesn't build but the site serves. */
+  customPages?: string[];
+  /** Absolute URLs of externally-generated sitemaps to list in the index. */
+  customSitemaps?: string[];
+  /** Max entries per file before it splits (default 45000). */
+  entryLimit?: number;
+  /** Filename prefix (default 'sitemap' → `sitemap-index.xml`). */
+  filenameBase?: string;
+  changefreq?: GetvitopsSitemapChangeFreq;
+  lastmod?: Date;
+  priority?: number;
+  /** Per-entry rewrite; return `undefined` to drop the entry. */
+  serialize?: (item: GetvitopsSitemapEntry) => GetvitopsSitemapEntry | Promise<GetvitopsSitemapEntry | undefined> | undefined;
+  /** Emit `<xhtml:link rel="alternate">` for localised routes. */
+  i18n?: {
+    defaultLocale: string;
+    locales: Record<string, string>;
+  };
+  /** XSL stylesheet to prettify the XML (path relative to `site`, or absolute URL). */
+  xslURL?: string;
+  /** XML namespaces to exclude (all included by default). */
+  namespaces?: {
+    news?: boolean;
+    xhtml?: boolean;
+    image?: boolean;
+    video?: boolean;
+  };
 }
 interface GetvitopsOptions {
+  /**
+   * Your site config — the one place to name it.
+   *
+   * A `SiteConfig` records site-level facts, several of which other options here
+   * need: `designSystem.defaultColorScheme` decides whether the generated colour layer
+   * carries a `prefers-color-scheme` block, `fonts` can supply the webfont
+   * declarations, and `legal` renders from it. Set this and each of those reads
+   * it, rather than repeating the path per feature. Every one can still be given
+   * explicitly, which wins.
+   *
+   * Needs `css`, since the generation runs in the Vite plugin `css` registers.
+   */
+  site?: GetvitopsSiteOptions;
   favicon?: GetvitopsFaviconOptions;
   /** Copy + link the web-component bundles (default true). */
   webComponents?: boolean;
@@ -47,8 +498,174 @@ interface GetvitopsOptions {
    * dev server, so on a static build that button simply isn't rendered.
    */
   editor?: boolean;
+  /**
+   * Render the site's legal documents (privacy policy, terms, cookie notice)
+   * from a site config, and re-render when it changes. Off unless provided.
+   *
+   * Requires `css`, which is what registers the Vite plugin that runs the
+   * generation — without it the documents would be written once and never
+   * refresh. Not using `css`? Run `vitops legal` from the CLI instead; it is the
+   * same renderer and works in any stack.
+   */
+  legal?: GetvitopsLegalOptions;
+  /**
+   * Load webfonts through Astro's Fonts API and emit `<Font />` for each from
+   * `<Head />`. Off unless provided.
+   *
+   * This is the seam the design system deliberately lacks. `design-system.json`'s
+   * `fonts` block holds **stacks only** — `--font-<name>` tokens and nothing else: no
+   * `@font-face`, no preload, no metrics-matched fallback. Declaring the family here
+   * makes the token resolvable *and* loaded, so the token keeps pointing at a
+   * `cssVariable` rather than at a literal stack the browser has no file for:
+   *
+   * ```js
+   * getvitops({ fonts: [{ name: 'League Spartan', provider: 'fontsource',
+   *                       cssVariable: '--font-league-spartan',
+   *                       weights: ['100 900'], subsets: ['latin'], preload: true }] })
+   * ```
+   * ```jsonc
+   * // design-system.json
+   * "fonts": { "display": "var(--font-league-spartan), sans-serif" }
+   * ```
+   *
+   * Pass a **string** instead to read the array from a site config's `fonts` block —
+   * the same declarations, kept next to the rest of the site's facts. (`siteEnv`
+   * picks the A/B variant, as in `legal`.) With the top-level `site` option set,
+   * plain `true` does the same thing without repeating the path.
+   *
+   * Independent of `css`: the loading runs in `astro:config:setup`, not in the Vite
+   * plugin. Both `<Head />` and the config entry are required — Astro's `fonts:`
+   * config resolves the files, and `<Font />` is what puts the `@font-face` on the
+   * page — so a declaration without `<Head />` in your layout loads nothing.
+   */
+  fonts?: boolean | string | SiteFont[] | GetvitopsFontsOptions;
+  /**
+   * Emit `sitemap-index.xml` + `sitemap-0.xml` via `@astrojs/sitemap`, and link it
+   * from `<Head />`. Off unless provided; `true` uses its defaults.
+   *
+   * Needs `@astrojs/sitemap` (an optional peer — install it yourself) and the
+   * `site` astro.config option, since a sitemap lists absolute URLs.
+   *
+   * Skipped with a warning when `emdash()` is registered — EmDash serves its own
+   * database-driven `/sitemap.xml` — and deferred to when you already list
+   * `@astrojs/sitemap` yourself. Note it enumerates **prerendered** routes only,
+   * so on-demand pages of an `output: 'server'` site are not listed.
+   */
+  sitemap?: boolean | GetvitopsSitemapOptions;
+  /**
+   * Site-level defaults for `<Seo />` (`@getvitops/astro/Seo.astro`) — site name,
+   * title template, Open Graph + Twitter defaults, verification tokens. Off unless
+   * provided; per-page props override every field.
+   *
+   * Needs the `site` astro.config option for canonical and `og:url`; without it
+   * `<Seo />` omits every absolute-URL tag rather than deriving one from the
+   * request, and this warns at build time.
+   *
+   * On an EmDash site prefer `<EmDashHead>`, which covers the same tags from the
+   * CMS — using both double-emits them.
+   */
+  seo?: GetvitopsSeoOptions;
+  /**
+   * Resolve semantic icon names centrally and, on a server build, derive which
+   * icons to bundle by scanning your source. Off unless provided; `true` uses
+   * the defaults below.
+   *
+   * Two separate jobs, and it is worth knowing which one you are buying:
+   *
+   * 1. **Naming.** `<Icon name="menu" />` resolves through the semantic map, so
+   *    the icon set is a config value rather than something spelled out at every
+   *    call site. A name containing `:` passes through untouched — that is the
+   *    escape hatch for a set-specific glyph.
+   * 2. **Bundle size.** astro-icon is zero-config on a static build, but under
+   *    `output: 'server'` it bundles EVERY icon in a set unless given an
+   *    `include` map. That is the list consumers end up hand-maintaining. Here it
+   *    is derived by scanning `scan` for icon references, merged with anything
+   *    you declare. On a static build no `include` is passed at all, because
+   *    there is nothing to trim.
+   *
+   * Names the scanner cannot read statically (`<Icon name={expr} />`) are
+   * reported with file and line, not guessed at — declare them in `include`.
+   */
+  icons?: boolean | GetvitopsIconsOptions;
+  /**
+   * Analytics tags for `<Analytics />` — Google Analytics, Microsoft Clarity,
+   * Matomo, Plausible. Off unless provided.
+   *
+   * Every tag loads off the critical path (`strategy`, default `'idle'`: after
+   * `load`, on an idle callback) and, when it sets cookies, only after consent.
+   *
+   * Which consent category a provider needs is derived from whether it sets
+   * cookies, not declared — so configuring a cookie-setting provider without
+   * `consent` warns rather than silently tracking everyone.
+   */
+  analytics?: GetvitopsAnalyticsOptions;
+  /**
+   * The consent gate: `@getvitops/core/consent` + `<CookieConsent />`. Off unless
+   * provided; `true` uses its defaults.
+   *
+   * A sibling of `analytics`, not part of it. The gate is general — anything
+   * marked `data-consent="<category>"` waits on the same choice, so A/B
+   * assignment, personalisation and third-party embeds use it too, and a site can
+   * enable it with no analytics configured at all.
+   *
+   * Pair it with `legal` so the cookie notice describes the categories this
+   * actually offers.
+   */
+  consent?: boolean | GetvitopsConsentOptions;
+}
+interface GetvitopsFontsOptions {
+  /** Path to a site config (JSON) whose `fonts` array holds the declarations. */
+  input?: string;
+  /** Declarations written inline; merged after anything `input` supplies. */
+  families?: SiteFont[];
+  /** Environment whose A/B variant applies to `input` (default 'production'). */
+  siteEnv?: string;
+}
+interface GetvitopsIconsOptions {
+  /** Icon set for UI chrome. Default `'fa7-solid'`. */
+  ui?: string;
+  /** Icon set for brand marks. Default `'simple-icons'`. */
+  brand?: string;
+  /**
+   * Weight for suffix-weighted sets like Phosphor (`'bold'`, `'fill'`, …).
+   * Ignored by sets that split weights across collections, e.g. Font Awesome.
+   */
+  weight?: string;
+  /**
+   * Icons to bundle, in `generateIconInclude`'s shape:
+   * `{ semantic: ['menu'], 'simple-icons': ['zoho'] }`.
+   *
+   * Merged with what the scan finds. Declared names that don't resolve **throw**
+   * (a config error); scanned names that don't resolve only **warn** (a source
+   * typo shouldn't kill the dev server).
+   */
+  include?: Parameters<typeof generateIconInclude>[0];
+  /**
+   * How `<Icon />` draws the glyph.
+   *
+   * `'inline'` (default) reads it from the `@iconify-json/*` collection and
+   * inlines the `<svg>` — no runtime request, no icon-integration peer.
+   * `'sprite'` emits `<use href="…/icons.svg#id">` instead, for pages served
+   * where the sprite is already on the origin.
+   *
+   * Note this is separate from `register`: whether astro-icon is registered for
+   * YOUR OWN `<Icon>` usage is a different question from how ours renders.
+   */
+  engine?: 'inline' | 'sprite';
+  /**
+   * Register the icon integration for you (default true). Set false when you
+   * already list `icon()` in `integrations` yourself — the scan, the sprite and
+   * the resolver still run either way.
+   */
+  register?: boolean;
+  /** Directories to scan, relative to the project root. Default `['src']`; `false` disables. */
+  scan?: string[] | false;
+  /** Public href of the sprite, for the `'sprite'` engine. Default `'/vitops/icons.svg'`. */
+  sprite?: string;
+  /** Aliases applied before the semantic map — legacy names, or values stored in CMS content. */
+  overrides?: Record<string, string>;
 }
 declare function getvitops(opts?: GetvitopsOptions): AstroIntegration;
 //#endregion
-export { type GetvitopsCssOptions, type GetvitopsFaviconOptions, type GetvitopsOptions, getvitops as default };
+export { type AnalyticsStrategy, type ClarityOptions, type ConsentCategory, type GetvitopsAnalyticsOptions, type GetvitopsConsentOptions, type GetvitopsCssOptions, type GetvitopsFaviconOptions, type GetvitopsOptions, type GetvitopsSeoOptions, type GetvitopsSitemapChangeFreq, type GetvitopsSitemapEntry, type GetvitopsSitemapOptions, type GoogleAnalyticsOptions, type MatomoOptions, type OptionalConsentCategory, type PlausibleOptions, type ResolveAnalyticsContext, type ResolvedAnalytics, type ResolvedSeo, type ResolvedTag, type SeoContext, type SeoNameTag, type SeoOgType, type SeoPropertyTag, type SeoProps, type SeoTwitterCard, consentCategories, getvitops as default, resolveAnalytics, resolveSeo };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/integration.ts"],"mappings":";;;;;UAsBiB,uBAAA;;EAEf,MAAA;EACA,YAAA;EAHe;EAKf,IAAA;;EAEA,UAAA;EACA,eAAA;AAAA;AAAA,UAGe,mBAAA;EAJf;EAMA,KAAA;EALe;EAOf,MAAA,GAAS,MAAM;EAJA;EAMf,GAAA;;;;;;;;EAQA,MAAA;AAAA;AAAA,UAGe,gBAAA;EACf,OAAA,GAAU,uBAAA;;EAEV,aAAA;EAFA;EAIA,GAAA,GAAM,mBAAmB;EAFzB;;;;;AAcM;AACP;;;;;EADC,MAAA;AAAA;AAAA,iBA2BsB,SAAA,CAAU,IAAA,GAAM,gBAAA,GAAwB,gBAAgB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/analytics.ts","../src/seo.ts","../src/integration.ts"],"mappings":"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"}