unhead 3.0.0 → 3.0.2

package/dist/shared/{unhead.Dyr7L2Ht.d.mts → unhead.BJTN1X0i.d.mts}

@@ -16,6 +16,14 @@ type _ResolvablePropertiesRaw<T> = {
 };
 type ResolvableProperties<T> = Prettify<_ResolvablePropertiesRaw<T>>;
 type ResolvableUnion<T> = T extends string | number | boolean ? ResolvableValue<T> : T extends object ? DeepResolvableProperties<T> : ResolvableValue<T>;
+/**
+ * Recursively marks all properties and arrays as readonly.
+ * Applied to `InferScript`/`InferLink` return types so that
+ * `defineScript`/`defineLink` accept both mutable and `as const` inputs.
+ */
+type DeepReadonly<T> = T extends (...a: any[]) => any ? T : T extends ReadonlyArray<infer U> ? readonly DeepReadonly<U>[] : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
 type DeepResolvableProperties<T> = {
     [K in keyof T]?: T[K] extends string | object ? T[K] extends string ? ResolvableUnion<T[K]> : T[K] extends object ? DeepResolvableProperties<T[K]> : ResolvableUnion<T[K]> : ResolvableUnion<T[K]>;
 };
@@ -878,20 +886,97 @@ interface PingbackLink extends LinkBase {
     rel: 'pingback';
     href: string;
 }
+/**
+ * Me link. Identifies the resource as representing the current user
+ * (IndieWeb / rel-me verification, Mastodon profile verification).
+ *
+ * @see https://html.spec.whatwg.org/multipage/links.html#link-type-me
+ */
+interface MeLink extends LinkBase {
+    rel: 'me';
+    href: string;
+}
+/**
+ * Privacy policy link.
+ *
+ * @see https://html.spec.whatwg.org/multipage/links.html#link-type-privacy-policy
+ */
+interface PrivacyPolicyLink extends LinkBase {
+    rel: 'privacy-policy';
+    href: string;
+}
+/**
+ * Terms of service link.
+ *
+ * @see https://html.spec.whatwg.org/multipage/links.html#link-type-terms-of-service
+ */
+interface TermsOfServiceLink extends LinkBase {
+    rel: 'terms-of-service';
+    href: string;
+}
+/**
+ * Expect link. Blocks rendering until a named element is present and ready.
+ *
+ * @see https://html.spec.whatwg.org/multipage/links.html#link-type-expect
+ */
+interface ExpectLink extends LinkBase {
+    rel: 'expect';
+    href: string;
+    blocking?: 'render';
+}
+/**
+ * Webmention endpoint link (IndieWeb).
+ *
+ * @see https://www.w3.org/TR/webmention/
+ */
+interface WebmentionLink extends LinkBase {
+    rel: 'webmention';
+    href: string;
+}
+/**
+ * Compression dictionary link (experimental).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/link#compression-dictionary
+ */
+interface CompressionDictionaryLink extends LinkBase {
+    rel: 'compression-dictionary';
+    href: string;
+}
+/**
+ * Alternate stylesheet link. User-selectable alternate stylesheet.
+ * Requires a `title` to appear in the browser's stylesheet picker.
+ *
+ * @see https://html.spec.whatwg.org/multipage/semantics.html#rel-alternate-stylesheet
+ */
+interface AlternateStylesheetLink extends LinkBase, LinkHttpEvents {
+    rel: 'alternate stylesheet';
+    href: string;
+    title: string;
+    media?: string;
+    crossorigin?: '' | 'anonymous' | 'use-credentials';
+    integrity?: string;
+    type?: 'text/css' | (string & Record<never, never>);
+    disabled?: boolean;
+}
 /**
  * Union of all `rel` values that have narrowed link type definitions.
  * Useful for building type guards or conditional logic based on `rel` values.
  */
-type KnownLinkRel = 'stylesheet' | 'preload' | 'modulepreload' | 'prefetch' | 'icon' | 'shortcut icon' | 'apple-touch-icon' | 'mask-icon' | 'manifest' | 'canonical' | 'dns-prefetch' | 'preconnect' | 'prerender' | 'alternate' | 'author' | 'license' | 'help' | 'search' | 'prev' | 'next' | 'pingback';
+type KnownLinkRel = 'stylesheet' | 'alternate stylesheet' | 'preload' | 'modulepreload' | 'prefetch' | 'icon' | 'shortcut icon' | 'apple-touch-icon' | 'mask-icon' | 'manifest' | 'canonical' | 'dns-prefetch' | 'preconnect' | 'prerender' | 'alternate' | 'author' | 'license' | 'help' | 'search' | 'prev' | 'next' | 'pingback' | 'me' | 'webmention' | 'privacy-policy' | 'terms-of-service' | 'expect' | 'compression-dictionary';
 /**
  * Fallback for custom or unknown `rel` types.
  *
- * Not included in the {@link Link} union to prevent silent absorption of known `rel` values.
- * Use this type explicitly when you need a non-standard `rel` value:
+ * Not included in the {@link Link} union to prevent silent absorption of known
+ * `rel` values (e.g. so `rel: 'preload'` without `as` stays an error instead of
+ * collapsing into this permissive shape).
+ *
+ * For non-standard `rel` values not covered by {@link KnownLinkRel}, prefer
+ * {@link defineLink}, which enforces strict narrowing on known rels while
+ * accepting `GenericLink` for anything else:
  *
  * ```ts
- * import type { GenericLink } from 'unhead/types'
- * useHead({ link: [{ rel: 'me', href: '...' } satisfies GenericLink] })
+ * import { defineLink } from 'unhead'
+ * useHead({ link: [defineLink({ rel: 'openid2.provider', href: 'https://...' })] })
  * ```
  */
 interface GenericLink extends LinkBase {
@@ -918,15 +1003,33 @@ interface GenericLink extends LinkBase {
  * attributes. For example, `rel="preload"` requires the `as` attribute (see {@link PreloadLink}),
  * and `rel="mask-icon"` requires `color` (see {@link MaskIconLink}).
  *
- * For custom or non-standard `rel` values, use {@link GenericLink} directly:
+ * For non-standard `rel` values not covered by {@link KnownLinkRel}, use {@link defineLink}:
  * ```ts
- * import type { GenericLink } from 'unhead/types'
- * useHead({ link: [{ rel: 'me', href: '...' } satisfies GenericLink] })
+ * import { defineLink } from 'unhead'
+ * useHead({ link: [defineLink({ rel: 'openid2.provider', href: 'https://...' })] })
  * ```
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel
  */
-type Link = StylesheetLink | PreloadLink | ModulepreloadLink | PrefetchLink | FaviconLink | AppleTouchIconLink | MaskIconLink | ManifestLink | CanonicalLink | DnsPrefetchLink | PreconnectLink | PrerenderLink | AlternateLanguageLink | AlternateFeedLink | AlternateMediaLink | BareAlternateLink | AuthorLink | LicenseLink | HelpLink | SearchLink | PrevLink | NextLink | PingbackLink;
+type Link = StylesheetLink | AlternateStylesheetLink | PreloadLink | ModulepreloadLink | PrefetchLink | FaviconLink | AppleTouchIconLink | MaskIconLink | ManifestLink | CanonicalLink | DnsPrefetchLink | PreconnectLink | PrerenderLink | AlternateLanguageLink | AlternateFeedLink | AlternateMediaLink | BareAlternateLink | AuthorLink | LicenseLink | HelpLink | SearchLink | PrevLink | NextLink | PingbackLink | MeLink | WebmentionLink | PrivacyPolicyLink | TermsOfServiceLink | ExpectLink | CompressionDictionaryLink;
+/**
+ * Pick {@link Link} union members whose `rel` accepts `R`.
+ *
+ * Unlike `Extract<Link, { rel: R }>`, this handles members whose `rel` is itself
+ * a union (e.g. {@link FaviconLink}'s `'icon' | 'shortcut icon'`).
+ */
+type MatchLinkByRel<R> = Link extends infer M ? M extends {
+    rel: infer MR;
+} ? R extends MR ? M : never : never : never;
+/**
+ * Resolve a single link input to either its strict {@link Link} variant (when
+ * `rel` is a {@link KnownLinkRel}) or {@link GenericLink} (for custom rels).
+ */
+type InferLink<T> = T extends {
+    rel: infer R;
+} ? R extends KnownLinkRel ? DeepReadonly<MatchLinkByRel<R>> : R extends string ? DeepReadonly<GenericLink> & {
+    rel: R;
+} : never : never;
 
 /**
  * Known meta name values
@@ -1039,7 +1142,7 @@ interface MetaFlatArticle {
      * Writers of the article.
      * @example ['https://example.com/some.html', 'https://example.com/one.html']
      */
-    articleAuthor?: string[];
+    articleAuthor?: readonly string[];
     /**
      * When the article is out of date after.
      * @example '1970-01-01T00:00:00.000Z'
@@ -1064,14 +1167,14 @@ interface MetaFlatArticle {
      * Tag words associated with this article.
      * @example ['Apple', 'Steve Jobs']
      */
-    articleTag?: string[];
+    articleTag?: readonly string[];
 }
 interface MetaFlatBook {
     /**
      * Who wrote this book.
      * @example ['https://example.com/some.html', 'https://example.com/one.html']
      */
-    bookAuthor?: string[];
+    bookAuthor?: readonly string[];
     /**
      * The ISBN.
      * @example '978-3-16-148410-0'
@@ -1086,7 +1189,7 @@ interface MetaFlatBook {
      * Tag words associated with this book.
      * @example ['Apple', 'Steve Jobs']
      */
-    bookTag?: string[];
+    bookTag?: readonly string[];
 }
 interface MetaFlatProfile {
     /**
@@ -2030,8 +2133,8 @@ type NoscriptContent = {
 type Noscript = Pick<GlobalAttributes, 'id' | 'class' | 'style'> & NoscriptContent;
 
 interface SpeculationRules {
-    prefetch?: (SpeculationRuleList | SpeculationRuleDocument)[];
-    prerender?: (SpeculationRuleList | SpeculationRuleDocument)[];
+    prefetch?: readonly (SpeculationRuleList | SpeculationRuleDocument)[];
+    prerender?: readonly (SpeculationRuleList | SpeculationRuleDocument)[];
 }
 interface SpeculationRuleBase {
     /**
@@ -2051,7 +2154,7 @@ interface SpeculationRuleBase {
      *
      * @see https://github.com/WICG/nav-speculation/blob/main/triggers.md#requirements
      */
-    requires?: 'anonymous-client-ip-when-cross-origin'[];
+    requires?: readonly 'anonymous-client-ip-when-cross-origin'[];
     /**
      * Indicating where the page expects the prerendered content to be activated.
      *
@@ -2067,10 +2170,10 @@ interface SpeculationRuleBase {
 }
 interface SpeculationRuleList extends SpeculationRuleBase {
     source: 'list';
-    urls: string[];
+    urls: readonly string[];
 }
 type SpeculationRuleFn = 'and' | 'or' | 'href_matches' | 'selector_matches' | 'not';
-type SpeculationRuleWhere = Partial<Record<SpeculationRuleFn, Partial<(Record<SpeculationRuleFn, (Partial<Record<SpeculationRuleFn, string>>) | string>)>[]>>;
+type SpeculationRuleWhere = Partial<Record<SpeculationRuleFn, readonly Partial<(Record<SpeculationRuleFn, (Partial<Record<SpeculationRuleFn, string>>) | string>)>[]>>;
 interface SpeculationRuleDocument extends SpeculationRuleBase {
     source: 'document';
     where: SpeculationRuleWhere;
@@ -2109,14 +2212,16 @@ interface NoLoadableScriptProps {
     nomodule?: never;
 }
 /**
- * Content for data scripts - either textContent or innerHTML, not both
+ * Content for data scripts — requires exactly one of `textContent` or
+ * `innerHTML`. Data scripts (JSON-LD, speculation rules, application/json) must
+ * carry inline content; an empty payload is invalid.
  */
 type DataScriptTextContent<T = string | Record<string, unknown>> = {
     /**
      * Sets the textContent of an element. Safer for XSS.
      * Can be a string or an object that will be serialized to JSON.
      */
-    textContent?: T;
+    textContent: T;
     innerHTML?: never;
 } | {
     textContent?: never;
@@ -2124,7 +2229,7 @@ type DataScriptTextContent<T = string | Record<string, unknown>> = {
      * Sets the innerHTML of an element.
      * Can be a string or an object that will be serialized to JSON.
      */
-    innerHTML?: T;
+    innerHTML: T;
 };
 /**
  * External JavaScript (fires events)
@@ -2307,7 +2412,7 @@ interface ImportMapConfig {
     scopes?: Record<string, Record<string, string>>;
 }
 /**
- * Import map
+ * Import map. Requires either `textContent` (recommended) or `innerHTML`.
  */
 type ImportMapScript = ScriptBase & NoLoadableScriptProps & {
     /**
@@ -2317,13 +2422,15 @@ type ImportMapScript = ScriptBase & NoLoadableScriptProps & {
      * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-type
      */
     type: 'importmap';
-    /**
-     * Sets the textContent of an element.
-     * Can be a string or an ImportMapConfig object that will be serialized to JSON.
-     */
+} & ({
+    /** Import map content as a string or ImportMapConfig object (auto-serialized). */
     textContent: string | ImportMapConfig;
     innerHTML?: never;
-};
+} | {
+    textContent?: never;
+    /** Import map content as a string or ImportMapConfig object (auto-serialized). */
+    innerHTML: string | ImportMapConfig;
+});
 /**
  * Application JSON script (generic JSON data)
  */
@@ -2339,12 +2446,16 @@ type ApplicationJsonScript = ScriptBase & NoLoadableScriptProps & DataScriptText
 /**
  * Fallback for custom or unknown `type` values.
  *
- * Not included in the {@link Script} union to prevent silent absorption of known `type` values.
- * Use this type explicitly when you need a non-standard `type` value:
+ * Not included in the {@link Script} union to prevent silent absorption of known
+ * `type` values (e.g. so `type: 'module'` without `src` or inline content stays
+ * an error instead of collapsing into this permissive shape).
+ *
+ * For custom `type` values, prefer {@link defineScript}, which enforces strict
+ * narrowing on known types while accepting `GenericScript` for anything else:
  *
  * ```ts
- * import type { GenericScript } from 'unhead/types'
- * useHead({ script: [{ type: 'text/plain', textContent: '...' } satisfies GenericScript] })
+ * import { defineScript } from 'unhead'
+ * useHead({ script: [defineScript({ type: 'text/plain', textContent: '...' })] })
  * ```
  */
 interface GenericScript extends ScriptBase, ScriptHttpEvents {
@@ -2420,13 +2531,38 @@ interface GenericScript extends ScriptBase, ScriptHttpEvents {
  * Each `type` value maps to a specific interface that enforces per-type constraints.
  * For example, inline scripts require `textContent` and forbid `src`/`async`/`defer`.
  *
- * For custom or non-standard `type` values, use {@link GenericScript} directly:
+ * For custom or non-standard `type` values, use {@link defineScript}:
  * ```ts
- * import type { GenericScript } from 'unhead/types'
- * useHead({ script: [{ type: 'text/plain', textContent: '...' } satisfies GenericScript] })
+ * import { defineScript } from 'unhead'
+ * useHead({ script: [defineScript({ type: 'text/plain', textContent: '...' })] })
  * ```
  */
 type Script = ExternalScript | ModuleScript | InlineScript | InlineModuleScript | JsonLdScript | SpeculationRulesScript | ImportMapScript | ApplicationJsonScript;
+/**
+ * Union of all `type` values that have narrowed script type definitions.
+ */
+type KnownScriptType = '' | 'text/javascript' | 'module' | 'application/ld+json' | 'speculationrules' | 'importmap' | 'application/json';
+/**
+ * Pick {@link Script} union members whose `type` accepts `U`.
+ *
+ * Handles members whose `type` is itself a union (e.g. {@link ExternalScript}'s
+ * `'' | 'text/javascript'`), and members where `type` is optional.
+ */
+type MatchScriptByType<U> = Script extends infer M ? M extends {
+    type?: infer MT;
+} ? U extends MT ? M : never : never : never;
+/**
+ * Resolve a single script input to either its strict {@link Script} variant (when
+ * `type` is a {@link KnownScriptType}) or {@link GenericScript} (for custom types).
+ *
+ * When no `type` field is present, or `type` is non-string, the full {@link Script}
+ * union is returned so discriminators like `src` vs `textContent` still apply.
+ */
+type InferScript<T> = T extends {
+    type: infer U;
+} ? U extends string ? U extends KnownScriptType ? DeepReadonly<MatchScriptByType<U>> : DeepReadonly<GenericScript> & {
+    type: U;
+} : DeepReadonly<Script> : DeepReadonly<Script>;
 
 interface Style extends Pick<GlobalAttributes, 'nonce' | 'id'>, Blocking {
     /**
@@ -2745,4 +2881,4 @@ interface HeadTag extends TagPriority, TagPosition, ResolvesDuplicates, HasTempl
 }
 type HeadTagKeys = (keyof HeadTag)[];
 
-export type { ModulepreloadLink as $, AlternateFeedLink as A, Booleanable as B, CanonicalLink as C, DataKeys as D, ExternalScript as E, FaviconLink as F, GenericLink as G, HasTemplateParams as H, IconLink as I, InternalTagKey as J, JsonLdScript as K, KnownLinkRel as L, LicenseLink as M, Link as N, LinkBase as O, LinkHttpEvents as P, ManifestLink as Q, MaskIconLink as R, MaybeArray as S, MaybeEventFnHandlers as T, Meta as U, MetaBase as V, MetaFlat as W, MetaGeneric as X, MetaNames as Y, MetaProperties as Z, ModuleScript as _, AlternateLanguageLink as a, NameMeta as a0, Never as a1, NextLink as a2, PingbackLink as a3, PreconnectLink as a4, PrefetchLink as a5, PreloadFontLink as a6, PreloadImageLink as a7, PreloadLink as a8, PreloadLinkBase as a9, ScriptBase as aA, ScriptHttpEvents as aB, SearchLink as aC, SerializableHead as aD, SpeculationRules as aE, SpeculationRulesScript as aF, StringInnerContent as aG, Stringable as aH, StylesheetLink as aI, TagKey as aJ, TagPosition as aK, TagPriority as aL, TagUserProperties as aM, TemplateParams as aN, TemplateParamsAugmentations as aO, UnheadBodyAttributesWithoutEvents as aP, UnheadHtmlAttributes as aQ, UnheadMeta as aR, UseHeadInput as aS, UseSeoMetaInput as aT, ValidTagPositions as aU, PreloadOtherLink as aa, PreloadScriptLink as ab, PreloadStyleLink as ac, PrerenderLink as ad, PrevLink as ae, ProcessesTemplateParams as af, PropertyMeta as ag, RawInput as ah, ResolvableBase as ai, ResolvableBodyAttributes as aj, ResolvableHead as ak, ResolvableHtmlAttributes as al, ResolvableLink as am, ResolvableMeta as an, ResolvableNoscript as ao, ResolvableProperties as ap, ResolvableScript as aq, ResolvableStyle as ar, ResolvableTemplateParams as as, ResolvableTitle as at, ResolvableTitleTemplate as au, ResolvableUnion as av, ResolvableValue as aw, ResolvesDuplicates as ax, SchemaAugmentations as ay, Script as az, AlternateLink as b, AlternateMediaLink as c, AppleTouchIconLink as d, ApplicationJsonScript as e, Arrayable as f, AuthorLink as g, BareAlternateLink as h, BodyAttributesWithoutEvents as i, BodyEvents as j, CharsetMeta as k, DeepResolvableProperties as l, DnsPrefetchLink as m, GenericScript as n, GlobalAttributes as o, HeadTag as p, HeadTagKeys as q, HelpLink as r, HttpEquivMeta as s, HttpEventAttributes as t, ImportMapConfig as u, ImportMapScript as v, InlineModuleScript as w, InlineScript as x, InnerContent as y, InnerContentVal as z };
+export type { MeLink as $, AlternateFeedLink as A, Booleanable as B, CanonicalLink as C, DataKeys as D, ExpectLink as E, FaviconLink as F, GenericLink as G, HasTemplateParams as H, IconLink as I, InferLink as J, InferScript as K, InlineModuleScript as L, InlineScript as M, InnerContent as N, InnerContentVal as O, InternalTagKey as P, JsonLdScript as Q, KnownLinkRel as R, KnownScriptType as S, LicenseLink as T, Link as U, LinkBase as V, LinkHttpEvents as W, ManifestLink as X, MaskIconLink as Y, MaybeArray as Z, MaybeEventFnHandlers as _, AlternateLanguageLink as a, UnheadMeta as a$, Meta as a0, MetaBase as a1, MetaFlat as a2, MetaGeneric as a3, MetaNames as a4, MetaProperties as a5, ModuleScript as a6, ModulepreloadLink as a7, NameMeta as a8, Never as a9, ResolvableStyle as aA, ResolvableTemplateParams as aB, ResolvableTitle as aC, ResolvableTitleTemplate as aD, ResolvableUnion as aE, ResolvableValue as aF, ResolvesDuplicates as aG, SchemaAugmentations as aH, Script as aI, ScriptBase as aJ, ScriptHttpEvents as aK, SearchLink as aL, SerializableHead as aM, SpeculationRules as aN, SpeculationRulesScript as aO, StringInnerContent as aP, Stringable as aQ, StylesheetLink as aR, TagKey as aS, TagPosition as aT, TagPriority as aU, TagUserProperties as aV, TemplateParams as aW, TemplateParamsAugmentations as aX, TermsOfServiceLink as aY, UnheadBodyAttributesWithoutEvents as aZ, UnheadHtmlAttributes as a_, NextLink as aa, PingbackLink as ab, PreconnectLink as ac, PrefetchLink as ad, PreloadFontLink as ae, PreloadImageLink as af, PreloadLink as ag, PreloadLinkBase as ah, PreloadOtherLink as ai, PreloadScriptLink as aj, PreloadStyleLink as ak, PrerenderLink as al, PrevLink as am, PrivacyPolicyLink as an, ProcessesTemplateParams as ao, PropertyMeta as ap, RawInput as aq, ResolvableBase as ar, ResolvableBodyAttributes as as, ResolvableHead as at, ResolvableHtmlAttributes as au, ResolvableLink as av, ResolvableMeta as aw, ResolvableNoscript as ax, ResolvableProperties as ay, ResolvableScript as az, AlternateLink as b, UseHeadInput as b0, UseSeoMetaInput as b1, ValidTagPositions as b2, WebmentionLink as b3, AlternateMediaLink as c, AlternateStylesheetLink as d, AppleTouchIconLink as e, ApplicationJsonScript as f, Arrayable as g, AuthorLink as h, BareAlternateLink as i, BodyAttributesWithoutEvents as j, BodyEvents as k, CharsetMeta as l, CompressionDictionaryLink as m, DeepReadonly as n, DeepResolvableProperties as o, DnsPrefetchLink as p, ExternalScript as q, GenericScript as r, GlobalAttributes as s, HeadTag as t, HeadTagKeys as u, HelpLink as v, HttpEquivMeta as w, HttpEventAttributes as x, ImportMapConfig as y, ImportMapScript as z };