@getvitops/astro 0.9.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,223 @@
 # @getvitops/astro
 
+## 1.0.0
+
+### Minor Changes
+
+- fd1a35b: Add `<Seo />` — page metadata for non-EmDash sites: `<title>`, description, canonical, Open Graph,
+  Twitter cards, robots, `article:*`, `hreflang` and verification tokens.
+
+  Site-level defaults go in the integration; pages pass only what differs.
+
+  ```js
+  // astro.config.mjs
+  vitops({
+    seo: {
+      siteName: 'Acme',
+      titleTemplate: '%s · Acme',
+      defaultDescription: 'We make the thing.',
+      openGraph: {
+        locale: 'en_CA',
+        image: { url: '/og.png', alt: 'Acme', width: 1200, height: 630 },
+      },
+      twitter: { site: '@acme' },
+    },
+  });
+  ```
+
+  ```astro
+  ---
+  import Seo from '@getvitops/astro/Seo.astro';
+  ---
+  <Seo title={title} description={description} image={cover} />
+  ```
+
+  **`<Seo />` owns `<title>` and `<meta name="description">` — remove them from your layout when you
+  adopt it.** It already computes the resolved title for `og:title`/`twitter:title`, and emitting those
+  in one place while the layout emits `<title>` in another is how the two drift apart. `<Head />` is
+  unaffected and still handles favicons, theme-color and the web-component runtime; use both.
+
+  Notable behaviour:
+  - `titleTemplate` is skipped when a page's title already equals `siteName`, so a homepage titled
+    "Acme" emits `Acme` rather than `Acme · Acme`. It never applies to `defaultTitle`.
+  - Canonical, `og:url` and relative `og:image` values need the `site` astro.config option. Without it
+    they're omitted rather than derived from the request URL — a canonical built from a dev or preview
+    origin can de-index you — and the integration warns at build time. Absolute image URLs still work.
+  - `robots` is omitted unless it says something; `index, follow` is what crawlers already assume. Use
+    `noindex`/`nofollow`/`noarchive`/`nocache`/`robotsExtras` per page, `robots` for a full override, or
+    `seo.robots` site-wide.
+  - `twitter:card` upgrades to `summary_large_image` whenever an image resolves.
+  - `hreflang` alternates are explicit only — pass `alternates`, including the current page. Nothing is
+    inferred from a locale list.
+  - No JSON-LD. The `./schemas/*` components take entity data and compose alongside it.
+
+  **On an EmDash site use `<EmDashHead>` instead** — it emits the same tags from the CMS, and rendering
+  both duplicates every one of them. The integration warns if `seo` is configured alongside `emdash()`.
+
+  The merge logic ships as the pure `resolveSeo(defaults, props, ctx)` if you need to drive it yourself.
+
+- 20252c2: Add an opt-in `sitemap` option to `getvitops()`, and link the result from `<Head />`.
+
+  `sitemap: true` registers the official `@astrojs/sitemap` for you; pass an object to configure it
+  (`filter`, `customPages`, `changefreq`, `priority`, `i18n`, `entryLimit`, `filenameBase`,
+  `serialize`, …). `<Head />` gains a matching `<link rel="sitemap">`.
+
+  ```js
+  getvitops({ sitemap: true });
+  getvitops({ sitemap: { filter: (page) => !page.includes('/draft/') } });
+  ```
+
+  `@astrojs/sitemap` is an **optional peer** — install it yourself (`pnpm add -D @astrojs/sitemap`) and
+  the build fails with a message saying so if you don't, rather than silently emitting nothing. The
+  option also needs the `site` astro.config option, since a sitemap lists absolute URLs; without it the
+  option warns and skips. Note `@astrojs/sitemap` enumerates **prerendered** routes only, so on an
+  `output: 'server'` site you'll want `export const prerender = true` on the pages you want indexed, or
+  `sitemap.customPages`.
+
+  **On an EmDash site, leave it off** — EmDash serves its own database-driven `/sitemap.xml`, which also
+  covers on-demand pages a static sitemap can't. The option detects `emdash()` and skips with a warning.
+  If you want both, add `sitemap()` to your own `integrations` array; getvitops detects that too and
+  leaves yours in charge, which is also how you reach the few `@astrojs/sitemap` options this
+  integration doesn't mirror.
+
+  Also fixes the `virtual:getvitops/head` type declaration, which was missing the `editor` field that
+  `<Head />` already reads — a type error in consumer projects that don't set `skipLibCheck`.
+
+- bb92a14: Add a fourth output format, `design`, that emits `DESIGN.md` — the agent-facing brief in
+  [google-labs-code/design.md](https://github.com/google-labs-code/design.md) format.
+
+  ```sh
+  vitops generate --format design --out .     # DESIGN.md, and nothing else
+  vitops generate --format css,design         # compose it with a stylesheet
+  ```
+
+  The file is YAML front matter carrying the tokens (`colors`, `typography`, `rounded`,
+  `spacing`, `components`, cross-referenced with `{group.token}`) followed by a prose body
+  carrying the rationale — colour model, fluid scales, layout vocabulary, elevation, shape
+  cascade, component tiers, do's and don'ts. Every section is rendered from your config, so
+  it cannot describe a system the other formats don't build. Point a coding agent, a Figma
+  import, or a designer at this one file when they don't have the toolchain; `vitops docs`
+  remains the richer reference for those who do.
+
+  It is emitted with `--out .` in mind: DESIGN.md conventionally lives at a repo root beside
+  `AGENTS.md`, not in a build directory.
+
+  Three things the spec cannot express, handled the same way every time and explained in the
+  emitted prose so the file is self-describing:
+  - **Fluid `clamp()` sizes** → the maximum (desktop) value, since a spec `Dimension` is a
+    bare number plus px/em/rem.
+  - **Dark mode** → light values only, with the automatic functional flip explained. Role
+    tokens are emitted as `{colors.<hue>-<step>}` references into the raw ramps rather than
+    flattened hexes, so the role → ramp lineage survives the export — flattening them is
+    exactly what breaks dark mode downstream.
+  - **A `50%` radius** → dropped from `rounded` (it is not a `Dimension`) and named in the
+    Shapes prose instead, so nothing is silently lost.
+
+  **New:** an optional `meta` key in `design-system.json` (`{ name, description }`) supplies
+  the brand name and the Overview paragraph. It affects no other format.
+
+  **New:** `StylesheetFormat` (`Exclude<Format, 'design'>`), exported from
+  `@getvitops/generator`. `@getvitops/astro`'s `css.format` now takes that narrower type —
+  `design` produces no stylesheet to inject, so passing it there is a type error rather than
+  a missing-file failure at build time. `vitops lint --format` is likewise restricted to the
+  three CSS formats. No change for anyone already passing `tailwind`, `css` or `bricks`.
+
+- bb92a14: Generate legal documents from your site config
+
+  `vitops legal` renders a privacy policy, terms of service and cookie notice from a site
+  config, in markdown, HTML or EmDash Portable Text:
+
+  ```sh
+  vitops legal --out ./content                 # every enabled document, as markdown
+  vitops legal --doc privacy --format html     # one document, as an HTML fragment
+  ```
+
+  The documents are **derived from your config**, not filled into a form. The analytics
+  provider they name is the one whose ID you set; the personal information they list is what
+  your configured forms actually collect; the countries they name come from the providers you
+  use. So a provider swap updates the policy on the next build, and the fix for a wrong policy
+  is a corrected config — hand-editing the output is overwritten.
+
+  Enable documents under `legal`, which gains the facts the prose asserts:
+
+  ```jsonc
+  {
+    "legal": {
+      "jurisdiction": "ca", // only 'ca' (PIPEDA) ships today
+      "privacyPolicy": {
+        "enabled": true,
+        "lastUpdated": "2026-08-01",
+        "retention": "24 months after our last contact with you",
+        // Third parties the config cannot imply. Analytics, Turnstile and your
+        // deploy platform are detected automatically — list only the rest.
+        "processors": [
+          {
+            "name": "Stripe",
+            "purpose": "payment processing",
+            "country": "the United States",
+          },
+        ],
+      },
+      "termsOfService": { "enabled": true },
+      "cookieConsent": {
+        "enabled": true,
+        "type": "opt-in",
+        "categories": ["Essential", "Analytics"],
+      },
+    },
+  }
+  ```
+
+  Delivery, by stack:
+  - **Any stack** — `vitops legal`. No integration code; prints to stdout without `--out`.
+  - **WordPress/Bricks** — `vitops generate --site <path>` also writes `dist/legal/*.html`, and
+    the theme loader now registers `[vitops_legal doc="privacy"]` to render one in a page. The
+    document updates on the next deploy with no action in WordPress.
+  - **Astro** — `getvitops({ legal: { input: 'site.json', out: 'src/content/legal' } })` writes
+    markdown into a content collection and re-renders when the site config changes. It needs a
+    `css` config (that is what registers the Vite plugin); without one, use the CLI.
+  - **EmDash** — `--format portable-text`, pasted into the admin.
+
+  Also new on the public API: `generateLegal()`, `renderMarkdown()`, `renderNodes()`,
+  `derivePolicyVars()`, `parseMarkdown()` / `toHtmlFragment()` / `toPortableText()`, and
+  `resolvePrivacyContact()`.
+
+  Two things to know before you publish anything this produces:
+  - **It is not legal advice.** Every document opens with a review banner saying so. The
+    bundled terms-of-service prose in particular is generic website boilerplate and
+    deliberately does not cover sales, refunds, subscriptions, accounts or user-generated
+    content — a site doing any of those needs clauses drafted for it.
+  - **It is only as true as your config.** A policy asserting things your site does not do is
+    worse than no policy. Check that the config describes reality before you ship the output.
+
+  `validateSite` now rejects a config that enables a privacy policy without a contact for
+  privacy requests or a `domains.canonical`, since both are interpolated into sentences that
+  would otherwise render blank.
+
+### Patch Changes
+
+- bb92a14: Docs: import the Astro integration as `vitops`, and document the fourth output format.
+
+  Every example now reads `import vitops from '@getvitops/astro'` and calls `vitops({ … })`,
+  including the scaffolded `emdash` template. The default export is unchanged, so this is a
+  naming convention in the docs rather than an API change — existing configs that bind it as
+  `getvitops` keep working.
+
+  The `@getvitops/generator` and `@getvitops/cli` docs also describe the `design` format, which
+  was shipped without a mention in either package's output table: `--format design` writes a
+  single `DESIGN.md` and no CSS, so a run that composes it with a stylesheet wants its own
+  `--out` (the brief conventionally sits at a repo root, the stylesheet does not).
+
+- Updated dependencies [bb92a14]
+- Updated dependencies [bb92a14]
+- Updated dependencies [bb92a14]
+- Updated dependencies [bb92a14]
+- Updated dependencies [eeb059f]
+  - @getvitops/generator@1.0.0
+  - @getvitops/vite@1.0.0
+  - @getvitops/utils@1.0.0
+  - @getvitops/core@1.0.0
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -15,11 +15,11 @@ npm i -D @getvitops/astro
 ```js
 // astro.config.mjs
 import { defineConfig } from 'astro/config';
-import getvitops from '@getvitops/astro';
+import vitops from '@getvitops/astro';
 
 export default defineConfig({
   integrations: [
-    getvitops({
+    vitops({
       css: { input: 'design-system.json', format: 'tailwind', out: 'src/styles' },
       favicon: { source: 'src/assets/logo.svg', name: 'My Site', themeColor: '#0b0b0c' },
     }),
@@ -56,11 +56,105 @@ Astro's module graph and Astro emits that link itself.
 | `css.inject`    | `true`               | inject the stylesheet into every SSR page                         |
 | `webComponents` | `true`               | copy + link the web-component bundles                             |
 | `favicon`       | off unless given     | `source`, `lowResSource`, `name`, `themeColor`, `backgroundColor` |
+| `sitemap`       | off unless given     | generate `sitemap-index.xml` via `@astrojs/sitemap`               |
+| `seo`           | off unless given     | site-level defaults for `<Seo />`                                 |
 
 Set `css.inject: false` when another integration adds routes that must not inherit the design system
 (e.g. EmDash's `/_emdash/admin`) — then import the generated file (`<out>/tailwind.css` or
 `<out>/styles.css`) from your own layout, so only your pages are styled.
 
+## Sitemap
+
+`sitemap: true` registers the official [`@astrojs/sitemap`](https://docs.astro.build/en/guides/integrations-guide/sitemap/)
+and links the result from `<Head />`. Pass an object to configure it (`filter`, `customPages`,
+`changefreq`, `priority`, `i18n`, `entryLimit`, `filenameBase`, `serialize`, …):
+
+```js
+vitops({ sitemap: { filter: (page) => !page.includes('/draft/') } });
+```
+
+Three things to know:
+
+- **It's an optional peer — install it yourself:** `pnpm add -D @astrojs/sitemap`. Without it the
+  build fails with a message telling you so, rather than silently emitting nothing.
+- **It needs the `site` astro.config option**, since a sitemap lists absolute URLs. Without it the
+  option warns and skips.
+- **It lists prerendered routes only.** On an `output: 'server'` site, mark the pages you want
+  indexed with `export const prerender = true`, or list them in `sitemap.customPages`.
+
+**On an EmDash site, leave it off.** EmDash serves its own `/sitemap.xml` from the database, which
+also covers on-demand pages a static sitemap can't; the option detects `emdash()` and skips with a
+warning. The two write different filenames and so don't actually collide — if you want both (DB
+content _and_ hand-authored `.astro` pages), add `sitemap()` to your own `integrations` array.
+vitops detects that too and leaves yours in charge, which is also how you reach the handful of
+`@astrojs/sitemap` options this integration doesn't mirror.
+
+## `<Seo />`
+
+Page metadata: `<title>`, description, canonical, Open Graph, Twitter cards, robots, `article:*`,
+`hreflang`, verification tokens. Site-level defaults go in the integration; pages pass what differs.
+
+```js
+// astro.config.mjs
+vitops({
+  seo: {
+    siteName: 'Acme',
+    titleTemplate: '%s · Acme',
+    defaultDescription: 'We make the thing.',
+    openGraph: {
+      locale: 'en_CA',
+      image: { url: '/og.png', alt: 'Acme', width: 1200, height: 630 },
+    },
+    twitter: { site: '@acme' },
+  },
+});
+```
+
+```astro
+---
+import Head from '@getvitops/astro/Head.astro';
+import Seo from '@getvitops/astro/Seo.astro';
+---
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <Seo title={title} description={description} image={cover} />
+  <Head />
+</head>
+```
+
+**It owns `<title>` and `<meta name="description">` — delete yours when you adopt it.** That isn't
+tidiness: it already computes the resolved title for `og:title`/`twitter:title`, and splitting the
+two is how they drift out of sync. `<Head />` is orthogonal (favicons, theme-color, the
+web-component runtime); use both.
+
+Behaviour worth knowing:
+
+- **`titleTemplate` is skipped when a page's title already equals `siteName`**, so a homepage titled
+  "Acme" emits `Acme`, not `Acme · Acme`. It never applies to `defaultTitle` either.
+- **Canonical needs the `site` astro.config option.** Without it, canonical, `og:url` and any
+  _relative_ `og:image` are omitted rather than derived from the request — a canonical built from a
+  dev or preview origin can de-index you. The integration warns at build time. Absolute image URLs
+  still work.
+- **`base` is handled for you.** `Astro.url.pathname` already includes it; don't prepend it yourself.
+  Under the default `trailingSlash: 'ignore'` dev and build can disagree on the trailing slash, so
+  pin `'always'` or `'never'` if you need a byte-stable canonical.
+- **`robots` is omitted unless it says something.** `index, follow` is what crawlers already assume.
+  Set `noindex`/`nofollow`/`noarchive`/`nocache`/`robotsExtras` per page, `robots` for a full
+  override, or `seo.robots` for a site-wide default.
+- **`twitter:card`** becomes `summary_large_image` whenever an image resolves.
+- **`hreflang` alternates are explicit only.** Pass `alternates={[{ hreflang, href }, …]}` including
+  the current page; nothing is inferred from a locale list, because only the page knows where its own
+  translations live.
+- **No JSON-LD.** The structured-data components in `./schemas/` take _entity_ data, `<Seo />` takes
+  _page_ data. Compose them: `<Seo … />` then `<Organization {...org} />`.
+
+**On an EmDash site, use `<EmDashHead>` instead** — it emits the same tags from the CMS. Rendering
+both duplicates every one of them; the integration warns if you configure `seo` alongside `emdash()`.
+
+The merge logic is a pure function, exported as `resolveSeo(defaults, props, ctx)` if you need to
+drive it yourself.
+
 ## Components
 
 Thin authoring helpers that emit the framework's HTML/CSS patterns — **none require runtime JS**:

package/dist/index.d.mts

@@ -1,7 +1,173 @@
-import { Format } from "@getvitops/generator";
+import { LegalOutput, StylesheetFormat } from "@getvitops/generator";
 import { AstroIntegration } from "astro";
 export * from "@getvitops/utils";
 
+//#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'`.
+   *
+   * 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;
+  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;
+  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. */
@@ -16,8 +182,13 @@ interface GetvitopsFaviconOptions {
 interface GetvitopsCssOptions {
   /** Path to design-system.json (default 'design-system.json'). */
   input?: string;
-  /** Output format (default 'tailwind'). */
-  format?: Format;
+  /**
+   * 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;
   /**
@@ -29,6 +200,79 @@ interface GetvitopsCssOptions {
    */
   inject?: boolean;
 }
+interface GetvitopsLegalOptions {
+  /** Path to the site config (JSON) the documents are rendered from. */
+  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 {
   favicon?: GetvitopsFaviconOptions;
   /** Copy + link the web-component bundles (default true). */
@@ -47,8 +291,44 @@ 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;
+  /**
+   * 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;
 }
 declare function getvitops(opts?: GetvitopsOptions): AstroIntegration;
 //#endregion
-export { type GetvitopsCssOptions, type GetvitopsFaviconOptions, type GetvitopsOptions, getvitops as default };
+export { type GetvitopsCssOptions, type GetvitopsFaviconOptions, type GetvitopsOptions, type GetvitopsSeoOptions, type GetvitopsSitemapChangeFreq, type GetvitopsSitemapEntry, type GetvitopsSitemapOptions, type ResolvedSeo, type SeoContext, type SeoNameTag, type SeoOgType, type SeoPropertyTag, type SeoProps, type SeoTwitterCard, getvitops as default, 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/seo.ts","../src/integration.ts"],"mappings":"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"}