@ultimat3/seo 27.16.1 → 29.0.0

package/CLAUDE.md

@@ -141,11 +141,15 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
   `Math.max(...times)`: a spread is one argument per item and the engine's limit is the caller's
   stack depth, not the feed's size. "Now" arrives through `BuildFeedOptions.clock`; nothing in
   `rss.ts` reads a clock of its own.
-- **A document that is not indexed carries no social card.** `renderMeta` emits `og:*`, `article:*`
-  and `twitter:*` only when `meta.robots?.index !== false` — declared or derived, one rule and no
-  `social: false` beside it. The tags were unconditional, so every admin screen, every 4xx/5xx
-  (`defineRoute` marks them `noindex`) and every draft published its title and description to
-  whoever pasted the URL into a chat. `follow: false` alone withdraws nothing. `meta.test.ts`.
+- **A document that is not indexed carries no social card — unless the route asks for one.**
+  `renderMeta` emits `og:*`, `article:*` and `twitter:*` unless `meta.robots?.index === false`, and
+  a route declaring `socialCard: true` gets the card anyway: exactly the card an indexable
+  document gets, declared values winning and the derived ones coming with it. That field is the
+  ONE switch — the robots line is never touched by it, so the route stays noindex, and a route
+  without it keeps today's suppression. The tags were unconditional, so every admin screen, every
+  4xx/5xx (`defineRoute` marks them `noindex`) and every draft published its title and description
+  to whoever pasted the URL into a chat. `follow: false` alone withdraws nothing.
+  `meta-social.test.ts`.
 - Only `site/` routes are SEO-checked — `app/` is behind auth and crawlers never authenticate.
 
 ## Files

package/README.md

@@ -45,7 +45,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | File | Owns |
 |---|---|
-| `meta.ts` | the metadata model, `renderMeta()` → head tags: title template, canonical, robots, `og:*`, `twitter:*`, hreflang + `x-default`, `theme-color` per colour scheme. **`robots: { index: false }` withdraws every `og:*`, `article:*` and `twitter:*` tag** — declared or derived; there is no `social` switch |
+| `meta.ts` | the metadata model, `renderMeta()` → head tags: title template, canonical, robots, `og:*`, `twitter:*`, hreflang + `x-default`, `theme-color` per colour scheme. **`robots: { index: false }` withdraws every `og:*`, `article:*` and `twitter:*` tag** — declared or derived; the one opt-in is `socialCard: true` |
 | `validate.ts` | the build gate — `validateMeta()` (`--json`-shaped) and `assertMeta()` |
 | `ld.ts` | typed JSON-LD builders; required fields are required in the **input type** |
 | `sitemap.ts` | `buildSitemap()` from the route table + each route's `prerender()`, per-locale alternates. One urlset at `/sitemap.xml`; past a cap (`SITEMAP_MAX_URLS` 50,000, `SITEMAP_MAX_BYTES` 50 MB) the index stays `/sitemap.xml` and the parts are `/sitemaps/<n>.xml` (`SITEMAP_PARTS_DIR`). With `sections` it is always an index of `/sitemaps/<name>-<n>.xml` — see below |
@@ -68,6 +68,16 @@ ld.Article({ headline: 'Ship it', author: { name: 'Ada' } });
 A missing `datePublished` is a compile error, not a Search Console warning three
 weeks later.
 
+## Social card
+
+A document that may not be indexed carries no `og:*`, `article:*` or `twitter:*` tag — declared or
+derived. One opt-in, declared by the route:
+
+| Rule | |
+|---|---|
+| `socialCard: true` | the card is emitted exactly as for an indexable page — declared values win, the derived ones come with it |
+| the robots directives | never changed by the opt-in — the route stays noindex |
+
 ## Sitemap: pages, sections, caps
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/seo",
-  "version": "27.16.1",
+  "version": "29.0.0",
   "description": "Enforced SEO: typed meta, JSON-LD, sitemap, robots, feeds, responsive images, perf budgets",
   "license": "MIT",
   "type": "module",
@@ -25,14 +25,14 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.2"
+    "bun": ">=1.4.4"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.16.1",
-    "@ultimat3/schema": "27.16.1"
+    "@ultimat3/core": "29.0.0",
+    "@ultimat3/schema": "29.0.0"
   }
 }

package/src/meta.ts

@@ -74,6 +74,13 @@ export interface RouteMeta {
   description?: string;
   canonical?: string;
   robots?: RobotsDirectives;
+  /**
+   * The social card opt-in for a document that may NOT be indexed. `robots: { index: false }`
+   * withdraws every `og:*`, `article:*` and `twitter:*` tag; a route declaring `socialCard: true`
+   * gets the card anyway — emitted exactly as an indexable document's, declared values winning and
+   * the derived ones coming with it. The robots directives are never touched by this field.
+   */
+  socialCard?: boolean;
   og?: OpenGraph;
   twitter?: TwitterCard;
   /** One entry per locale. `x-default` is added automatically when absent. */
@@ -222,10 +229,12 @@ export function hreflangSet(
 /**
  * The card a link preview is built from: `og:*`, `article:*`, `twitter:*`.
  *
- * Emitted only for a document that may be INDEXED. `robots: { index: false }` withdraws the whole
- * set, declared or derived — one rule, no second switch: a page its author keeps out of a search
- * result is a page behind sign-in, an error, or a draft, and a card for it publishes the title and
- * description the `noindex` was hiding. Every admin document carried one until 2026-10.
+ * Withdrawn from a document that may not be INDEXED: `robots: { index: false }` is a page its
+ * author keeps out of a search result — behind sign-in, an error, or a draft — and a card for it
+ * publishes the title and description the `noindex` was hiding. A route that wants the card anyway
+ * says so ONCE, with `socialCard: true`, and then gets exactly the card an indexable document
+ * gets: declared values win, the derived ones come with it. That field never touches the robots
+ * directives, so the route stays noindex.
  */
 function socialTags(
   meta: RouteMeta,
@@ -233,7 +242,7 @@ function socialTags(
   canonicalHref: string | undefined,
   abs: (value: string) => string,
 ): readonly HeadTag[] {
-  if (meta.robots?.index === false) return [];
+  if (meta.robots?.index === false && meta.socialCard !== true) return [];
   const tags: HeadTag[] = [];
   const og = meta.og ?? {};
   const ogLocale =