@getvitops/astro 0.9.0 → 2.0.0

package/src/components/Icon.astro

@@ -0,0 +1,94 @@
+---
+/**
+ * One icon, resolved through the site's semantic map.
+ *
+ * `name` is a semantic name ('menu', 'chevron-down') that resolves per the
+ * configured set, OR a fully-qualified `prefix:name` which passes straight
+ * through — that is the escape hatch for a glyph the map doesn't cover.
+ *
+ * **Why this doesn't use astro-icon.** It can't. astro-icon's `./components`
+ * entry is a TypeScript file that Vite has to transform, so it is only reachable
+ * through a statically-analysable import — and a *static* import is precisely
+ * what made the optional peer mandatory for anyone rendering Popover, Details or
+ * Drawer, which is the bug this component exists to fix. A dynamic
+ * `import(/* @vite-ignore *\/ …)` compiles nothing and hands Node raw TS, which
+ * fails silently and renders an empty box. So the glyph is read straight out of
+ * the `@iconify-json/*` collection instead — the same loader the sprite emitter
+ * uses, so both delivery paths draw the identical icon and neither needs a peer.
+ *
+ * Two other things worth knowing:
+ *
+ * - **An unresolvable name warns, it doesn't throw.** A missing glyph must never
+ *   500 an SSR page; the box renders empty and the build log says which name.
+ *   `vitops icons` is the place that fails hard.
+ * - **`.icon` already does the layout.** It's an inline-flex box sized in `em`
+ *   (`--icon-size`) that stretches its `<svg>` child and sets `fill:
+ *   currentColor`. So a start/end adornment on `.cta`/`.btn` — both already
+ *   `inline-flex` with a `gap` — is a matter of child order, not a new class.
+ *   Don't confuse this with `.icon-mask`, the CSS-only adornment path (see
+ *   `.link--icon::before` in anchor-link.css).
+ */
+import { loadIconSvg, spriteId } from '@getvitops/generator';
+import { resolveIcon } from '@getvitops/utils';
+import icons from 'virtual:getvitops/icons';
+
+interface Props {
+  /** Semantic name ('menu') or fully-qualified ('ph:list'). */
+  name: string;
+  /** Resolve against the brand set rather than the UI set. */
+  brand?: boolean;
+  /** Any CSS length; sets `--icon-size`. Defaults to the framework's 1.25em. */
+  size?: string;
+  /**
+   * Accessible name. Omit for decorative icons — the default — which are then
+   * `aria-hidden`. An icon that carries meaning on its own needs this.
+   */
+  label?: string;
+  class?: string;
+}
+
+const { name, brand = false, size, label, class: className } = Astro.props;
+
+const set = brand ? icons.brand : icons.ui;
+const aliased = icons.overrides[name] ?? name;
+
+let qualified: string | null = null;
+try {
+  qualified = resolveIcon(aliased, set, { weight: icons.weight ?? undefined });
+} catch {
+  // A bare name that isn't in the map is legitimate — a sprite id, or a local
+  // SVG — so fall through with what we were given rather than giving up.
+  qualified = aliased.includes(':') ? aliased : null;
+}
+
+let svg: { viewBox: string; body: string } | null = null;
+if (icons.engine === 'inline' && qualified) {
+  // resolveFrom is the project root, not process.cwd() — see IconsData.root.
+  svg = await loadIconSvg(qualified, { resolveFrom: icons.root });
+  if (!svg)
+    console.warn(
+      `[getvitops] <Icon name="${name}"> — "${qualified}" not found. Is ` +
+        `@iconify-json/${qualified.slice(0, qualified.indexOf(':'))} installed?`,
+    );
+} else if (icons.engine === 'none') {
+  console.warn(
+    `[getvitops] <Icon name="${name}"> rendered but icons are not configured. ` +
+      'Add `icons: true` to getvitops() in astro.config.',
+  );
+}
+
+const a11y = label ? { role: 'img', 'aria-label': label } : { 'aria-hidden': 'true' };
+const style = size ? `--icon-size:${size}` : undefined;
+---
+
+<span class:list={['icon', className]} style={style} {...a11y}>
+  {
+    svg ? (
+      <svg viewBox={svg.viewBox} set:html={svg.body} />
+    ) : icons.engine === 'sprite' && icons.sprite && qualified ? (
+      <svg>
+        <use href={`${icons.sprite}#${spriteId(qualified)}`} />
+      </svg>
+    ) : null
+  }
+</span>

package/src/components/Popover.astro

@@ -1,5 +1,5 @@
 ---
-import { Icon } from 'astro-icon/components';
+import Icon from './Icon.astro';
 
 interface Props {
   id: string;
@@ -14,8 +14,14 @@ interface Props {
   class?: string;
   anchorName?: string;
   positionArea?: string;
-  /** Resolve semantic icon names to fully-qualified astro-icon names.
-   *  Defaults to pass-through (expects already-qualified names like 'fa7-solid:bars'). */
+  /**
+   * Map a semantic name onto a fully-qualified one before rendering.
+   *
+   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * the site's set is configured once instead of threaded through every call
+   * site. Left in place because removing it would break consumers passing one;
+   * when omitted, `<Icon />` resolves through the site config.
+   */
   iconResolver?: (name: string) => string;
 }
 

package/src/components/Seo.astro

@@ -0,0 +1,68 @@
+---
+/**
+ * <Seo /> — the page's SEO <head> tags. Place inside your layout's <head>,
+ * alongside <Head /> (which owns favicons, theme-color and the web-component
+ * runtime — the two don't overlap).
+ *
+ * Site-level defaults come from `getvitops({ seo: … })` via the
+ * `virtual:getvitops/head` module; the props here override them per page.
+ *
+ * It owns <title> and <meta name="description">, so **remove them from your
+ * layout** when you adopt it. That is not tidiness: this component already
+ * computes the resolved title for `og:title`/`twitter:title`, and the previous
+ * version of it emitted those while leaving <title> to the layout — so the two
+ * drifted. Whoever computes the title emits it.
+ *
+ * It emits no JSON-LD. The structured-data components in `../schemas/` take
+ * entity data; this takes page data. Compose them:
+ *   <Seo title={title} description={description} />
+ *   <Organization {...org} />
+ *
+ * On an EmDash site use <EmDashHead> instead — it covers the same tags from the
+ * CMS. Using both double-emits every og:/twitter: tag.
+ */
+// @ts-ignore — virtual module provided by the getvitops() integration at build time
+import head from 'virtual:getvitops/head';
+import { resolveSeo, type SeoProps } from '../seo.ts';
+
+export type Props = SeoProps;
+
+// `Astro.site` is `URL | undefined`; `head.site` is the `config.site` string the
+// integration captured. Same value, different types — the fallback is there so a
+// render context without `Astro.site` still resolves absolute URLs.
+const site: URL | undefined = Astro.site ?? (head.site ? new URL(head.site) : undefined);
+
+/*
+ * `Astro.url.pathname` already includes `base`, and being an absolute path it
+ * replaces any path in `site` — so `site: 'https://x.com'` + `base: '/docs'`
+ * yields `https://x.com/docs/page/`. Do not prepend `base` by hand; that
+ * double-prefixes.
+ *
+ * The pathname follows whatever `trailingSlash`/`build.format` produced. Under
+ * the default `trailingSlash: 'ignore'` dev and build can disagree, so pin
+ * `'always'` or `'never'` if you need a byte-stable canonical. We deliberately
+ * don't normalise it here — rewriting the URL Astro actually serves is how you
+ * end up with a canonical that redirects.
+ */
+const seo = resolveSeo(head.seo ?? {}, Astro.props, {
+  site,
+  pathname: Astro.url.pathname,
+});
+---
+
+{seo.title && <title set:text={seo.title} />}
+{seo.description && <meta name="description" content={seo.description} />}
+{seo.canonical && <link rel="canonical" href={seo.canonical} />}
+{/* Omitted when it would only restate `index, follow`, which crawlers assume. */}
+{seo.robots && <meta name="robots" content={seo.robots} />}
+
+{seo.openGraph.map((t) => <meta property={t.property} content={t.content} />)}
+{seo.twitter.map((t) => <meta name={t.name} content={t.content} />)}
+
+{/*
+  Explicit only — see SeoProps.alternates. Nothing is inferred from a locale list,
+  because only the page knows where its own translations live.
+*/}
+{seo.alternates.map((a) => <link rel="alternate" hreflang={a.hreflang} href={a.href} />)}
+
+{seo.verification.map((t) => <meta name={t.name} content={t.content} />)}

package/src/seo.ts

@@ -0,0 +1,337 @@
+/**
+ * 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>. */
+export type SeoTwitterCard = 'summary' | 'summary_large_image' | 'app' | 'player';
+
+/** Open Graph object types this component knows how to describe. */
+export 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.
+ */
+export 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. */
+export 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`). */
+export interface SeoPropertyTag {
+  property: string;
+  content: string;
+}
+
+/** A `<meta name>` tag. */
+export interface SeoNameTag {
+  name: string;
+  content: string;
+}
+
+/** Everything `<Seo />` renders, already decided. `null` means "emit nothing". */
+export 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`. */
+export 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;
+}
+
+/** `en-CA` → `en_CA`; Open Graph wants the underscore form. */
+const ogLocale = (locale: string) => locale.replace('-', '_');
+
+/**
+ * Absolute URLs pass through; relative ones resolve against `site`, or are
+ * dropped when there is no `site` to resolve them against. A relative `og:image`
+ * or canonical is worse than none — crawlers resolve it against whatever origin
+ * served the page.
+ */
+function absolute(url: string | undefined, site: URL | undefined): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).href;
+  } catch {
+    return site ? new URL(url, site).href : null;
+  }
+}
+
+/** Composes the robots directive, or null when nothing meaningful was asked for. */
+function resolveRobots(props: SeoProps, defaults: GetvitopsSeoOptions): string | null {
+  if (props.robots) return props.robots;
+  const { noindex, nofollow, noarchive, nocache, robotsExtras } = props;
+  if (noindex || nofollow || noarchive || nocache || robotsExtras) {
+    return [
+      noindex ? 'noindex' : 'index',
+      nofollow ? 'nofollow' : 'follow',
+      ...(noarchive ? ['noarchive'] : []),
+      ...(nocache ? ['nocache'] : []),
+      ...(robotsExtras ? [robotsExtras] : []),
+    ].join(', ');
+  }
+  // No explicit default either: emit nothing. `index, follow` is what crawlers
+  // already assume, so stating it adds bytes and no meaning.
+  return defaults.robots ?? null;
+}
+
+/**
+ * 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.
+ */
+export function resolveSeo(
+  defaults: GetvitopsSeoOptions,
+  props: SeoProps,
+  ctx: SeoContext,
+): ResolvedSeo {
+  const { site } = ctx;
+  const siteName = props.siteName ?? defaults.siteName ?? null;
+
+  // The template applies to a page's own title only, and only when that title
+  // isn't already the site name. Two ways to get "Acme · Acme" otherwise: running
+  // it over `defaultTitle`, and a homepage whose own title happens to equal the
+  // site name — which is the common case, not an edge case.
+  const templated = props.title && defaults.titleTemplate && props.title !== siteName;
+  const fallbackTitle = defaults.defaultTitle ?? siteName;
+  const title = props.title
+    ? templated
+      ? String(defaults.titleTemplate).replaceAll('%s', props.title)
+      : props.title
+    : fallbackTitle;
+
+  /*
+   * `og:title`/`twitter:title` take the page's title *without* the template.
+   *
+   * The two are read in different places. `<title>` is navigational — a browser
+   * tab or a search result, competing with a dozen others, so it needs the brand
+   * suffix to disambiguate. A social card is self-contained and already shows
+   * `og:site_name` and the domain, so repeating the brand there is furniture:
+   * "Installation · Acme" sitting directly above "Acme".
+   *
+   * They still derive from one value, which is the part that matters — the
+   * component this replaces computed them in separate places and they drifted.
+   * Pass `ogTitle` when a page wants a genuinely different social headline.
+   */
+  const socialTitle = props.ogTitle ?? props.title ?? fallbackTitle;
+
+  const description = props.description ?? defaults.defaultDescription ?? null;
+
+  const canonical = props.canonical
+    ? absolute(props.canonical, site)
+    : site
+      ? new URL(ctx.pathname + (ctx.search ?? ''), site).href
+      : null;
+
+  const image = absolute(props.image, site) ?? absolute(defaults.openGraph?.image?.url, site);
+  // Only inherit the default image's metadata when the page didn't bring its own
+  // image — otherwise a page's image would carry the default's alt text.
+  const usingDefaultImage = !props.image;
+  const defaultImage = defaults.openGraph?.image;
+  const imageAlt = props.imageAlt ?? (usingDefaultImage ? defaultImage?.alt : undefined);
+  const imageWidth = props.imageWidth ?? (usingDefaultImage ? defaultImage?.width : undefined);
+  const imageHeight = props.imageHeight ?? (usingDefaultImage ? defaultImage?.height : undefined);
+  const imageType = props.imageType ?? (usingDefaultImage ? defaultImage?.type : undefined);
+
+  const type = props.type ?? defaults.openGraph?.type ?? 'website';
+  const locale = props.locale ?? defaults.openGraph?.locale;
+
+  const openGraph: SeoPropertyTag[] = [];
+  const og = (property: string, content: string | number | null | undefined) => {
+    if (content !== null && content !== undefined && content !== '')
+      openGraph.push({ property, content: String(content) });
+  };
+
+  og('og:type', type);
+  og('og:title', socialTitle);
+  og('og:description', description);
+  og('og:url', canonical);
+  og('og:site_name', siteName);
+  og('og:locale', locale ? ogLocale(locale) : null);
+  for (const alt of defaults.openGraph?.localeAlternates ?? [])
+    og('og:locale:alternate', ogLocale(alt));
+  og('og:image', image);
+  if (image) {
+    og('og:image:alt', imageAlt);
+    og('og:image:width', imageWidth);
+    og('og:image:height', imageHeight);
+    og('og:image:type', imageType);
+  }
+  if (type === 'article' && props.article) {
+    const a = props.article;
+    og('article:published_time', a.publishedTime);
+    og('article:modified_time', a.modifiedTime);
+    og('article:expiration_time', a.expirationTime);
+    for (const author of a.authors ?? []) og('article:author', author);
+    og('article:section', a.section);
+    for (const tag of a.tags ?? []) og('article:tag', tag);
+  }
+
+  const twitter: SeoNameTag[] = [];
+  const tw = (name: string, content: string | null | undefined) => {
+    if (content) twitter.push({ name, content });
+  };
+  // A card with a large image is only honoured if there *is* an image.
+  tw('twitter:card', image ? 'summary_large_image' : (defaults.twitter?.card ?? 'summary'));
+  tw('twitter:site', defaults.twitter?.site);
+  tw('twitter:creator', props.twitterCreator ?? defaults.twitter?.creator);
+  tw('twitter:title', socialTitle);
+  tw('twitter:description', description);
+  tw('twitter:image', image);
+  tw('twitter:image:alt', image ? imageAlt : null);
+
+  const verification: SeoNameTag[] = [];
+  if (defaults.googleSiteVerification)
+    verification.push({
+      name: 'google-site-verification',
+      content: defaults.googleSiteVerification,
+    });
+  if (defaults.bingSiteVerification)
+    verification.push({ name: 'msvalidate.01', content: defaults.bingSiteVerification });
+
+  return {
+    title,
+    socialTitle,
+    description,
+    canonical,
+    robots: resolveRobots(props, defaults),
+    openGraph,
+    twitter,
+    verification,
+    alternates: props.alternates ?? [],
+  };
+}

package/virtual.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Astro generates the real types for `astro:env/*` into a consumer's
+ * `.astro/` on `astro sync`, which never runs for this package — so the
+ * import typechecks nowhere but a consumer project. Declared here at the
+ * shape `plan-features.ts` actually uses; the runtime value comes from
+ * Astro's env schema, and this file cannot import it.
+ */
+declare module 'astro:env/server' {
+  export const SITE_PLAN: string | undefined;
+}
+
 /** Types for the virtual module the getvitops() integration provides to <Head />. */
 declare module 'virtual:getvitops/head' {
   interface FaviconLink {
@@ -6,13 +17,61 @@ declare module 'virtual:getvitops/head' {
     type?: string;
     sizes?: string;
   }
+  /** Mirrors `HeadFont` in src/fonts.ts. `preload` is Astro's `PreloadFilter`. */
+  interface HeadFont {
+    cssVariable: string;
+    preload: boolean | { weight?: string | number; style?: string }[];
+  }
+  // Keep these keys in step with `HeadData` in src/integration.ts — the two are
+  // hand-duplicated (an ambient `declare module` in a shipped .d.ts cannot import
+  // from src), and `head.test.ts` asserts the key sets match.
   interface HeadData {
     favicons: boolean;
     faviconLinks: FaviconLink[];
     themeColor: string | null;
     webComponents: boolean;
     wcBase: string;
+    editor: boolean;
+    sitemap: string | null;
+    /** Families registered by `getvitops({ fonts })`, for `<Font />`. */
+    fonts: HeadFont[];
+    site: string | null;
+    // Structurally `GetvitopsSeoOptions` (src/seo.ts). Left loose here because
+    // this file can't import from src, and <Seo /> re-types it on the way into
+    // `resolveSeo`, which is where the real contract is enforced.
+    seo: Record<string, unknown>;
+    // Likewise `GetvitopsAnalyticsOptions` (src/analytics.ts) — re-typed by
+    // <Analytics /> on the way into `resolveAnalytics`.
+    analytics: Record<string, unknown>;
+    consent: boolean;
+    consentCategories: string[];
+    consentPolicyUrl: string | null;
+    consentRuntime: boolean;
   }
   const data: HeadData;
   export default data;
 }
+
+/** Types for the virtual module the getvitops() integration provides to <Icon />. */
+declare module 'virtual:getvitops/icons' {
+  // Keep these keys in step with `IconsData` in src/integration.ts, for the same
+  // reason as HeadData above; `icons.test.ts` asserts the key sets match.
+  //
+  // Note what is NOT here: a resolver function. The module is JSON.stringify'd,
+  // so only data crosses. <Icon /> imports the pure `resolveIcon` from
+  // @getvitops/utils and feeds it these values.
+  interface IconsData {
+    engine: 'inline' | 'sprite' | 'none';
+    /** Absolute project root — where `@iconify-json/*` is resolved from. */
+    root: string;
+    ui: string;
+    brand: string;
+    weight: string | null;
+    /** Consumer aliases applied before the semantic map (legacy names, content values). */
+    overrides: Record<string, string>;
+    /** Public href of the sprite, or null when none is emitted. */
+    sprite: string | null;
+  }
+  const data: IconsData;
+  export default data;
+}