fix: better type narrowing escape hatches for custom rel/type (#735)

* feat(unhead): add defineLink and defineScript helpers for custom rel/type

The `satisfies GenericLink` / `satisfies GenericScript` pattern the v3
docstrings and migration guide recommended did not actually type-check
against useHead, because `GenericLink` / `GenericScript` are intentionally
excluded from the `Link` / `Script` unions to prevent silent absorption
of known `rel` / `type` values.

Introduce `defineLink` and `defineScript` helpers that keep known-value
strictness (e.g. `rel: 'preload'` still requires `as`, `type: 'module'`
still requires `src` or inline content) while accepting custom values
via `GenericLink` / `GenericScript`. Update docstrings, migration guide,
release notes, and the useHead API reference accordingly.

* feat(unhead): add standard link rels (me, webmention, privacy-policy, etc.)

Several standard `<link>` rel keywords were missing from `KnownLinkRel`
and the `Link` union, making them look like "custom" rels that needed
`defineLink`. Add dedicated interfaces and union members for: `me`,
`webmention`, `privacy-policy`, `terms-of-service`, `expect`,
`compression-dictionary`, and `alternate stylesheet`.

`alternate stylesheet` requires `title` per spec; `expect` carries an
optional `blocking: 'render'`. Update `defineLink` examples and docs to
use genuinely non-standard rels (`openid2.provider`, `EditURI`) instead
of rels that are now directly supported.

* test: update exports snapshot for defineLink/defineScript

* fix(unhead): require textContent or innerHTML on data scripts

DataScriptTextContent used optional textContent/innerHTML in both union
branches, allowing empty data scripts like `{ type: 'application/ld+json' }`
to type-check with no content at all. Make each branch require its
respective content field so JsonLdScript, SpeculationRulesScript, and
ApplicationJsonScript enforce non-empty payloads at the type level.

Add type tests covering empty-payload rejection for ld+json, speculation
rules, application/json, and importmap. Rename two script test titles
from `rel="..."` to `type="..."` per review feedback.

Author: harlan-zw

docs/6.migration-guide/1.v3.md

@@ -406,7 +406,7 @@ The SSR hooks (`ssr:beforeRender`, `ssr:render`, `ssr:rendered`) are now synchro
 
 🚦 Impact Level: **Medium**
 
-The `Link` and `Script` types are now strict discriminated unions. Known `rel` and `type` values enforce per-tag required properties at the type level. `GenericLink` and `GenericScript` are still exported for custom values.
+The `Link` and `Script` types are now strict discriminated unions. Known `rel` and `type` values enforce per-tag required properties at the type level. Use the new `defineLink` and `defineScript` helpers to declare custom values without losing strictness on known ones.
 
 ### Link Tags
 
@@ -423,28 +423,28 @@ useHead({
 })
 ```
 
-For custom `rel` values not in the known set, use `satisfies GenericLink`:
+For non-standard `rel` values not covered by `KnownLinkRel` (e.g. OpenID endpoints, RSD links), use `defineLink`:
 
 ```ts
-import type { GenericLink } from 'unhead/types'
+import { defineLink, useHead } from 'unhead'
 
 useHead({
   link: [
-    { rel: 'me', href: 'https://mastodon.social/@me' } satisfies GenericLink,
+    defineLink({ rel: 'openid2.provider', href: 'https://example.com/openid' }),
   ]
 })
 ```
 
 ### Script Tags
 
-Inline scripts must have `textContent` or `innerHTML` and cannot include `src`, `async`, or `defer`. For custom `type` values, use `satisfies GenericScript`:
+Inline scripts must have `textContent` or `innerHTML` and cannot include `src`, `async`, or `defer`. For custom `type` values, use `defineScript`:
 
 ```ts
-import type { GenericScript } from 'unhead/types'
+import { defineScript, useHead } from 'unhead'
 
 useHead({
   script: [
-    { type: 'text/plain', textContent: '...' } satisfies GenericScript,
+    defineScript({ type: 'text/plain', textContent: '...' }),
   ]
 })
 ```
@@ -460,14 +460,14 @@ Meta `content` is now required on name, property, and http-equiv meta tags. Use
 
 ### String Variables
 
-When `rel` or `type` comes from a variable typed as `string`, TypeScript cannot narrow the union. Use `as const` or `satisfies`:
+When `rel` or `type` comes from a variable typed as `string`, TypeScript cannot narrow the union. Wrap it with `defineLink` / `defineScript` or use `as const` for literals:
 
 ```ts
-import type { GenericLink } from 'unhead/types'
+import { defineLink, useHead } from 'unhead'
 
 const rel = getRelFromConfig() // string, not a literal
 useHead({
-  link: [{ rel, href: '/path' } satisfies GenericLink]
+  link: [defineLink({ rel, href: '/path' })]
 })
 
 // or use as const for literals

docs/7.releases/1.v3.md

@@ -213,4 +213,4 @@ For the full migration guide, see [Migrate to v3](/docs/migration-guide/v3).
 - `TemplateParamsPlugin` and `AliasSortingPlugin` are no longer included by default
 - `init`, `dom:renderTag`, `dom:rendered` hooks removed; `dom:beforeRender` is now synchronous
 - `@unhead/addons` renamed to `@unhead/bundler`; framework Vite plugins now use a named `Unhead` export instead of a default export
-- `Link` / `Script` unions are strict: custom `rel` / `type` values need `satisfies GenericLink` / `GenericScript`, and meta `content` is now required (use `content: null` to remove)
+- `Link` / `Script` unions are strict: use the new `defineLink` / `defineScript` helpers for custom `rel` / `type` values, and meta `content` is now required (use `content: null` to remove)

docs/head/7.api/composables/0.use-head.md

@@ -362,28 +362,29 @@ declare module '@unhead/schema' {
 
 ### Type Narrowing
 
-`Link` and `Script` use discriminated unions keyed on `rel` and `type`. Known values enforce per-tag required properties at the type level. For custom or non-standard values, use `satisfies` with the generic fallback types:
+`Link` and `Script` use discriminated unions keyed on `rel` and `type`. Known values enforce per-tag required properties at the type level. For non-standard values not covered by the built-in union, use the `defineLink` and `defineScript` helpers, which preserve strict narrowing on known values and fall through to `GenericLink` / `GenericScript` for anything else:
 
 ::code-group
 
-```ts [Custom Link rel]
-import type { GenericLink } from '@unhead/dynamic-import/types'
+```ts [Non-standard Link rel]
+import { defineLink, useHead } from '@unhead/dynamic-import'
 
 useHead({
   link: [
     { rel: 'canonical', href: 'https://example.com' }, // known rel, works directly
-    { rel: 'webmention', href: 'https://...' } satisfies GenericLink, // custom rel
+    { rel: 'me', href: 'https://mastodon.social/@me' }, // known rel, works directly
+    defineLink({ rel: 'openid2.provider', href: 'https://example.com/openid' }), // non-standard rel
   ]
 })
 ```
 
 ```ts [Custom Script type]
-import type { GenericScript } from '@unhead/dynamic-import/types'
+import { defineScript, useHead } from '@unhead/dynamic-import'
 
 useHead({
   script: [
     { src: 'https://example.com/app.js' }, // external script, works directly
-    { type: 'text/plain', textContent: '...' } satisfies GenericScript, // custom type
+    defineScript({ type: 'text/plain', textContent: '...' }), // custom type
   ]
 })
 ```

packages/unhead/src/define.ts

@@ -0,0 +1,53 @@
+import type { InferLink, InferScript, Link, Script } from './types'
+
+/**
+ * Typed helper for declaring a `<link>` element inside {@link useHead}.
+ *
+ * Known `rel` values stay strict: `rel: 'preload'` still requires `as`,
+ * preload fonts still require `crossorigin`, `rel: 'mask-icon'` still requires
+ * `color`, etc. Non-standard `rel` values not covered by `KnownLinkRel` (e.g.
+ * OpenID endpoints, custom protocol discovery links) are accepted via
+ * `GenericLink` without losing strictness on the rest of the union.
+ *
+ * Standard rels like `'me'`, `'webmention'`, `'privacy-policy'`, and
+ * `'terms-of-service'` are already in the `Link` union, so they work with
+ * `useHead` directly without this helper.
+ *
+ * @example
+ * ```ts
+ * import { defineLink, useHead } from 'unhead'
+ *
+ * useHead({
+ *   link: [
+ *     defineLink({ rel: 'openid2.provider', href: 'https://example.com/openid' }),
+ *     defineLink({ rel: 'EditURI', href: '/rsd.xml', type: 'application/rsd+xml' }),
+ *   ],
+ * })
+ * ```
+ */
+export function defineLink<const T extends { rel: string }>(link: T & InferLink<T>): Link {
+  return link as unknown as Link
+}
+
+/**
+ * Typed helper for declaring a `<script>` element inside {@link useHead}.
+ *
+ * Known `type` values stay strict: `type: 'module'` still requires `src` or inline
+ * content, `type: 'application/ld+json'` still requires `textContent`, etc. Custom
+ * or non-standard `type` values (e.g. `'text/plain'`, `'text/html'`) are accepted
+ * via {@link GenericScript} without losing strictness on the rest of the union.
+ *
+ * @example
+ * ```ts
+ * import { defineScript, useHead } from 'unhead'
+ *
+ * useHead({
+ *   script: [
+ *     defineScript({ type: 'text/plain', textContent: 'debug-token' }),
+ *   ],
+ * })
+ * ```
+ */
+export function defineScript<const T extends object>(script: T & InferScript<T>): Script {
+  return script as unknown as Script
+}

packages/unhead/src/index.ts

@@ -1,2 +1,3 @@
 export { useHead, useHeadSafe, useScript, useSeoMeta } from './composables'
+export { defineLink, defineScript } from './define'
 export { createUnhead } from './unhead'

packages/unhead/src/types/schema/head.ts

@@ -9,22 +9,27 @@ import type {
   AlternateLanguageLink,
   AlternateLink,
   AlternateMediaLink,
+  AlternateStylesheetLink,
   AppleTouchIconLink,
   AuthorLink,
   BareAlternateLink,
   CanonicalLink,
+  CompressionDictionaryLink,
   DnsPrefetchLink,
+  ExpectLink,
   FaviconLink,
   GenericLink,
   HelpLink,
   IconLink,
+  InferLink,
   KnownLinkRel,
   LicenseLink,
   Link,
   LinkBase,
   LinkHttpEvents,
   ManifestLink,
   MaskIconLink,
+  MeLink,
   ModulepreloadLink,
   NextLink,
   PingbackLink,
@@ -39,9 +44,12 @@ import type {
   PreloadStyleLink,
   PrerenderLink,
   PrevLink,
+  PrivacyPolicyLink,
   SearchLink,
   // Narrowed link types for re-export
   StylesheetLink,
+  TermsOfServiceLink,
+  WebmentionLink,
 } from './link'
 import type {
   CharsetMeta,
@@ -62,9 +70,11 @@ import type {
   GenericScript,
   ImportMapConfig,
   ImportMapScript,
+  InferScript,
   InlineModuleScript,
   InlineScript,
   JsonLdScript,
+  KnownScriptType,
   ModuleScript,
   Script,
   ScriptBase,
@@ -264,22 +274,27 @@ export type {
   AlternateLanguageLink,
   AlternateLink,
   AlternateMediaLink,
+  AlternateStylesheetLink,
   AppleTouchIconLink,
   AuthorLink,
   BareAlternateLink,
   CanonicalLink,
+  CompressionDictionaryLink,
   DnsPrefetchLink,
+  ExpectLink,
   FaviconLink,
   GenericLink,
   HelpLink,
   IconLink,
+  InferLink,
   KnownLinkRel,
   LicenseLink,
   Link,
   LinkBase,
   LinkHttpEvents,
   ManifestLink,
   MaskIconLink,
+  MeLink,
   ModulepreloadLink,
   NextLink,
   PingbackLink,
@@ -294,8 +309,11 @@ export type {
   PreloadStyleLink,
   PrerenderLink,
   PrevLink,
+  PrivacyPolicyLink,
   SearchLink,
   StylesheetLink,
+  TermsOfServiceLink,
+  WebmentionLink,
 }
 
 // Script types (narrowed)
@@ -305,9 +323,11 @@ export type {
   GenericScript,
   ImportMapConfig,
   ImportMapScript,
+  InferScript,
   InlineModuleScript,
   InlineScript,
   JsonLdScript,
+  KnownScriptType,
   ModuleScript,
   Script,
   ScriptBase,