npm - @octanejs/seo - Versions diffs - 0.0.2 - Mend

@octanejs/seo 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/LICENSE +21 -0
package/README.md +194 -0
package/package.json +42 -0
package/src/components.tsrx +217 -0
package/src/components.tsrx.d.ts +17 -0
package/src/context.ts +4 -0
package/src/descriptors.ts +323 -0
package/src/expand.ts +262 -0
package/src/index.ts +31 -0
package/src/registry.ts +125 -0
package/src/useRegister.ts +55 -0
package/src/useStrayOwnerDiagnostic.ts +42 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Dominic Gannaway
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,194 @@
+# `@octanejs/seo`
+Declarative document metadata for Octane: server-rendered into `<head>`, adopted
+on hydration, and merged so the most specific declaration wins.
+```tsx
+import { Head, Link, Meta, Script, Title } from '@octanejs/seo';
+function App() @{
+	<Head>
+		<Head>
+			<Title text="Acme" />
+			<Meta name="description" content="Widgets for everyone" />
+		</Head>
+		<Router />
+	</Head>
+}
+function ProductPage(props: { product: Product }) @{
+	<>
+		<Head>
+			<Title text={props.product.name} />
+			<Meta name="description" content={props.product.blurb} />
+			<Link rel="canonical" href={'/p/' + props.product.slug} />
+			<Script type="application/ld+json" json={{ '@type': 'Product', name: props.product.name }} />
+		</Head>
+		<main>…</main>
+	</>
+}
+```
+The product page's title and description replace the app-level ones. Everything
+else the app declared stays.
+## Why a merge exists
+The platform resolves duplicates by taking the **first** in tree order:
+`document.title` is defined as the first `<title>` element in the document, and
+a crawler reads the first `meta[name="description"]`. Authoring order runs the
+other way, with app defaults written before page specifics, so simply emitting
+both would let the generic value win every time. Registrations are therefore
+keyed by identity and the **last** one wins.
+Identity is what the tag names, not the tag type. `meta[name]`,
+`meta[property]`, and `meta[http-equiv]` are separate channels. JSON-LD is keyed
+by `@type` (plus `@id`), so an `Article` replaces an `Article` while a
+`BreadcrumbList` sits alongside it.
+`<link>` needs three rules, because `href` is sometimes the value being set and
+sometimes the thing being identified:
+| rel | identity | effect |
+| --- | --- | --- |
+| `canonical`, `manifest`, `author`, `license`, `prev`, `next` | `rel` alone | one per document |
+| `alternate` (`hreflang`/`type`/`media`/`title`), `icon` and `apple-touch-icon` (`sizes`/`type`), `mask-icon`, `search` | the named slot, **not** `href` | a page moving the German alternate or the 32×32 icon replaces it |
+| everything else, including `preload`, `prefetch`, `preconnect`, `modulepreload`, `stylesheet`, and any rel not listed above | the target URL | two font preloads or two stylesheets coexist |
+Unknown rels fall in the last group deliberately: emitting two tags is a smaller
+mistake than silently dropping one.
+## `<Head>`, and where to put it
+Wrap the app in one:
+```tsx
+<Head>
+	<App />
+</Head>
+```
+Then use `<Head>` again wherever metadata belongs. **Position carries no
+meaning.** Two blocks merge whether one contains the other or they sit in
+unrelated components, and precedence never depends on nesting depth: the last
+registration of a given identity wins, so a page overrides a layout simply by
+rendering later. Tags written bare under the outer `<Head>`, with no block around
+them, behave identically.
+The outermost `<Head>` is what makes that true. The merge has to see every
+registration before it emits anything, and a string renderer emits in document
+order, so blocks that owned their own metadata would each emit a set and the
+platform's first-wins rule would hand the page to whichever rendered first. This
+would then quietly break:
+```tsx
+function Page() @{
+	<>
+		<Head><Title text="Listing" /></Head>
+		<Detail />                    {/* its own <Head> is a SIBLING */}
+	</>
+}
+```
+With an outer `<Head>` around the app, `<Detail>` wins as written. A tag with no
+`<Head>` above it throws, and two `<Head>` elements where neither contains the
+other are reported in development.
+## Components
+| Component | Purpose |
+| --- | --- |
+| `<Title text="…" />` | Document title |
+| `<Meta name/property/http-equiv … />` | Any meta tag |
+| `<Link rel="…" href="…" />` | canonical, alternate, icon, manifest |
+| `<Script type json / text />` | JSON-LD and other head scripts |
+| `<Seo … />` | The whole metadata object at once |
+`<Title>` takes its text as a **prop**, not JSX children. Element children
+compile to a children block (a function), and coercing one to a string would put
+source code in the document title, so that case throws instead.
+`<Seo>` is the object form and expands to the tags above:
+```tsx
+<Seo
+	title="Post title"
+	description="Post summary"
+	canonical="/blog/post"
+	site="https://example.com"
+	titleTemplate="%s · Example"
+	openGraph={{ type: 'article', images: [{ url: '/og.png', alt: 'Post', width: 1200, height: 630 }] }}
+	twitter={{ card: 'summary_large_image', site: '@example' }}
+	languages={{ de: '/de/blog/post', 'x-default': '/blog/post' }}
+	robots={{ index: true, follow: true, maxImagePreview: 'large' }}
+	jsonLd={{ '@type': 'Article', headline: 'Post title' }}
+/>
+```
+## App-level settings
+Three things are declared once and apply everywhere, because the component that
+knows them is rarely the one that renders a page:
+- **`site`** absolute-ises the URLs a consumer reads without a base: `canonical`,
+  `link rel="alternate"` hreflang addresses, `og:url`, `og:image`, and
+  `twitter:image`. It deliberately does **not** touch subresources the browser
+  fetches, so `preload`, `prefetch`, `modulepreload`, `stylesheet`, `icon`, and
+  `manifest` keep resolving against the document actually serving the response.
+  Rewriting those would make a preview deploy carrying the production `site` pull
+  fonts, CSS, and modules from production.
+- **`titleTemplate`** wraps each page's title, so `%s · Acme` applies to a page
+  that only sets `title: 'Pricing'`.
+- **The Open Graph and Twitter shell.** Declare `openGraph`/`twitter` once and
+  `og:title`, `og:description`, `og:url`, `twitter:title`, and
+  `twitter:description` are mirrored from whatever page renders, unless that page
+  names them itself. Only families you actually declared are filled, so an app
+  that never asked for Open Graph never emits it.
+```tsx
+// once, near the root
+<Seo
+	site="https://example.com"
+	titleTemplate="%s · Example"
+	openGraph={{ type: 'website', siteName: 'Example' }}
+	twitter={{ card: 'summary_large_image' }}
+/>
+// and in a page, anywhere below
+<Seo title="Pricing" description="Plans and limits." canonical="/pricing" />
+```
+All three are applied after the merge, once the whole tree has registered. The
+social mirror uses the raw title rather than the templated one, since
+`og:site_name` already carries what a template adds.
+## Server rendering
+Metadata registered during render reaches `<head>` in the served HTML, which is
+the point: an effect-based approach never runs on the server, so crawlers would
+see nothing. Under `@octanejs/vite-plugin` this works with no configuration.
+For a custom server, render with `headChannel: 'separate'` and splice the
+returned metadata into your template's `<head>`:
+```ts
+const { html, css, head } = await prerender(App, props, { headChannel: 'separate' });
+```
+Streaming uses `onHeadReady(head)`, which fires before the shell is written. See
+`docs/ssr.md`.
+Two caveats worth knowing:
+- **Remove any static `<title>` from `index.html`.** The hoisted metadata is
+  spliced at `<!--ssr-head-->`, after it, so a template title would win.
+- **Metadata that depends on suspended data does not reach a streamed shell.**
+  The shell flushes before the data settles. Derive metadata from data you
+  already have, or use the buffered renderer for those routes.
+## Hydration and navigation
+The client adopts the server's elements instead of appending its own, updates
+them in place rather than replacing them (a swapped `<link>` would re-fetch its
+resource), and removes what it owns when a page unmounts, so navigating between
+routes never accumulates stale canonicals or `og:image` tags.

package/package.json ADDED Viewed

@@ -0,0 +1,42 @@
+{
+  "name": "@octanejs/seo",
+  "version": "0.0.2",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "SEO metadata for Octane, declarative <Title>/<Meta>/<Link>/<JsonLd> with last-wins merging, server-rendered into <head> and adopted on hydration.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/seo"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "octane": "0.1.17"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "octane": "0.1.17"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/components.tsrx ADDED Viewed

@@ -0,0 +1,217 @@
+import { useContext, useRef, useSyncExternalStore } from 'octane';
+import type { OctaneNode } from 'octane';
+import { SeoContext } from './context.ts';
+import { createSeoRegistry, type SeoRegistry } from './registry.ts';
+import { linkKey, metaKey, type MetaAttributes, type SeoDescriptor } from './descriptors.ts';
+import { expandSeo, jsonLdDescriptor, type SeoInput } from './expand.ts';
+import { useRegisterSeo } from './useRegister.ts';
+import { useStrayOwnerDiagnostic } from './useStrayOwnerDiagnostic.ts';
+// Shared so a dropped descriptor registers a stable empty set rather than a new
+// array each render, which would invalidate the merge every time.
+const EMPTY: readonly SeoDescriptor[] = [];
+/**
+ * One rendered head element.
+ *
+ * `<title>`/`<meta>`/`<link>` are hoisted by the compiler into the render's head
+ * channel, so they reach the real `<head>` and are adopted on hydration rather
+ * than recreated. `<script type="application/ld+json">` is NOT hoistable and
+ * stays where it renders, which is valid: JSON-LD is explicitly supported in the
+ * body. Its content goes through `dangerouslySetInnerHTML` because `<script>` is
+ * a raw-text element; the renderer escapes inline script content itself.
+ */
+function SeoTag(props: { descriptor: SeoDescriptor }) @{
+	@switch (props.descriptor.tag) {
+		@case 'title': {
+			<title>{(props.descriptor.text ?? '') as string}</title>
+		}
+		@case 'meta': {
+			<meta {...props.descriptor.attrs} />
+		}
+		@case 'link': {
+			<link {...props.descriptor.attrs} />
+		}
+		@default: {
+			<script
+				{...props.descriptor.attrs}
+				dangerouslySetInnerHTML={{ __html: props.descriptor.text ?? '' }}
+			/>
+		}
+	}
+}
+/**
+ * Emits the merged metadata. An owning `<Head>` renders this AFTER its children,
+ * so every descendant registration is already in the registry by the time this
+ * reads it, that ordering is what makes an inner page's title beat an outer
+ * layout's, which the platform's own first-wins rule would otherwise invert.
+ */
+function SeoOutlet() @{
+	const registry = useContext(SeoContext);
+	if (registry === null) {
+		throw new Error('[@octanejs/seo] internal: <SeoOutlet> rendered with no registry.');
+	}
+	const descriptors = useSyncExternalStore(
+		registry.subscribe,
+		registry.getSnapshot,
+		registry.getSnapshot,
+	);
+	<>
+		@for (const descriptor of descriptors; key descriptor.key) {
+			<SeoTag descriptor={descriptor} />
+		}
+	</>
+}
+/**
+ * `<Title text="Page name" />`, the innermost one rendered wins.
+ *
+ * The text is a prop, not JSX children, and deliberately so: the compiler turns
+ * element children into a children block (a function), and coercing one to a
+ * string would silently put source code in the document title. `children` is
+ * accepted in its string prop form for convenience; anything else is rejected
+ * loudly rather than serialized.
+ */
+export function Title(props: { text?: string; children?: string }) {
+	useRegisterSeo([
+		{ tag: 'title', key: 'title', attrs: {}, text: titleText(props) },
+	]);
+	return null;
+}
+function titleText(props: { text?: string; children?: string }): string {
+	const value = props.text ?? props.children;
+	if (typeof value === 'string') return value;
+	if (typeof value === 'number') return String(value);
+	if (value === undefined || value === null) return '';
+	throw new Error('[@octanejs/seo] <Title> needs a string: use <Title text="…" /> or <Seo title="…" />. ' +
+		'JSX children compile to a children block, which is not a string.');
+}
+/** `<Meta name="description" content="…" />` / `<Meta property="og:title" … />`. */
+export function Meta(props: MetaAttributes & { seoKey?: string }) {
+	const { seoKey, ...attrs } = props;
+	useRegisterSeo([
+		{ tag: 'meta', key: seoKey ?? metaKey(attrs), attrs },
+	]);
+	return null;
+}
+/** `<Link rel="canonical" href="…" />`. */
+export function Link(props: MetaAttributes & { seoKey?: string }) {
+	const { seoKey, ...attrs } = props;
+	useRegisterSeo([
+		{ tag: 'link', key: seoKey ?? linkKey(attrs), attrs },
+	]);
+	return null;
+}
+/**
+ * The one component. Wrap the app in it once, then use it again wherever
+ * metadata belongs:
+ *
+ * ```tsx
+ * <Head>
+ *   <App />
+ * </Head>
+ *
+ * // …anywhere below, in any component
+ * <Head>
+ *   <Title text="Post title" />
+ *   <Meta name="description" content="…" />
+ *   <Link rel="canonical" href="/post" />
+ *   <Script type="application/ld+json" json={article} />
+ * </Head>
+ * ```
+ *
+ * The OUTERMOST one owns the metadata: it holds the registry and renders the
+ * merged tags after its children. Every `<Head>` below it is grouping only, and
+ * where those blocks sit carries no meaning. Two of them merge whether one
+ * contains the other or they are siblings in unrelated components, and
+ * precedence does not depend on nesting depth: the LAST registration of a given
+ * identity wins, so a page overrides a layout simply by rendering later.
+ *
+ * That is why the outer one has to exist. The merge must see every registration
+ * before it emits anything, and a string renderer emits in document order, so
+ * blocks that owned their own metadata would each emit a set and the platform's
+ * first-wins rule would hand the page to whichever rendered first.
+ *
+ * The registry lives here rather than in module scope, so concurrent server
+ * renders cannot see each other's metadata.
+ */
+export function Head(props: { children?: OctaneNode }) @{
+	const outer = useContext(SeoContext);
+	const registryRef = useRef<SeoRegistry | null>(null);
+	if (outer === null && registryRef.current === null) registryRef.current = createSeoRegistry();
+	useStrayOwnerDiagnostic(outer === null);
+	@if (outer === null) {
+		<SeoContext.Provider value={registryRef.current}>
+			{props.children}
+			<SeoOutlet />
+		</SeoContext.Provider>
+	} @else {
+		<>
+			{props.children}
+		</>
+	}
+}
+/**
+ * A head script, typically JSON-LD.
+ *
+ * Pass `json` for structured data (serialized for you) or `text` for a raw body.
+ * Unlike `<title>`/`<meta>`/`<link>`, a `<script>` is not hoisted into `<head>`
+ * and renders where the outlet sits, which is valid: JSON-LD is explicitly
+ * supported in the body. The renderer escapes inline script content.
+ */
+export function Script(props: {
+	type?: string;
+	json?: unknown;
+	text?: string;
+	seoKey?: string;
+	[attr: string]: unknown;
+}) {
+	const { json, text, seoKey, ...attrs } = props;
+	const type =
+		typeof attrs.type === 'string' ? attrs.type : 'application/ld+json';
+	// ONE registration call site. Hooks are keyed by call site, so branching into
+	// two `useRegisterSeo` calls would give a `<Script>` that switches between
+	// `json` and `text` a second slot, and the abandoned branch's source would
+	// stay registered, a stale script no unmount ever removes.
+	const descriptor: SeoDescriptor | null =
+		json !== undefined
+			? jsonLdDescriptor(json, seoKey)
+			: {
+					tag: 'script',
+					key: 'script:' + (seoKey ?? type),
+					attrs: { ...attrs as MetaAttributes, type },
+					text: text ?? '',
+				};
+	useRegisterSeo(descriptor === null ? EMPTY : [descriptor]);
+	return null;
+}
+/** Structured data. Identity is `@type` (plus `@id`) unless `seoKey` is given. */
+export function JsonLd(props: { data: unknown; seoKey?: string }) {
+	const descriptor = jsonLdDescriptor(props.data, props.seoKey);
+	useRegisterSeo(descriptor === null ? EMPTY : [descriptor]);
+	return null;
+}
+/**
+ * The whole metadata object in one element; expands to the tags above.
+ *
+ * `site` and `titleTemplate` are app-level: they merge last-wins like everything
+ * else and apply to every page's title and URLs, so setting them once near the
+ * root is enough. A page that names its own still overrides them.
+ */
+export function Seo(props: SeoInput) {
+	useRegisterSeo(expandSeo(props), {
+		site: props.site,
+		titleTemplate: props.titleTemplate,
+		declaredOpenGraph: props.openGraph !== undefined,
+		declaredTwitter: props.twitter !== undefined,
+	});
+	return null;
+}

package/src/components.tsrx.d.ts ADDED Viewed

@@ -0,0 +1,17 @@
+import type { ComponentBody, OctaneNode } from 'octane';
+import type { MetaAttributes } from './descriptors.js';
+import type { SeoInput } from './expand.js';
+export declare const Head: ComponentBody<{ children?: OctaneNode }>;
+export declare const Title: ComponentBody<{ text?: string; children?: string }>;
+export declare const Meta: ComponentBody<MetaAttributes & { seoKey?: string }>;
+export declare const Link: ComponentBody<MetaAttributes & { seoKey?: string }>;
+export declare const Script: ComponentBody<{
+	type?: string;
+	json?: unknown;
+	text?: string;
+	seoKey?: string;
+	[attr: string]: unknown;
+}>;
+export declare const JsonLd: ComponentBody<{ data: unknown; seoKey?: string }>;
+export declare const Seo: ComponentBody<SeoInput>;

package/src/context.ts ADDED Viewed

@@ -0,0 +1,4 @@
+import { createContext } from 'octane';
+import type { SeoRegistry } from './registry.js';
+export const SeoContext = createContext<SeoRegistry | null>(null);

package/src/descriptors.ts ADDED Viewed

@@ -0,0 +1,323 @@
+/**
+ * Metadata descriptors and the merge that decides precedence.
+ *
+ * Renderer-free on purpose: server and client both merge with this exact code,
+ * so the two emit the identical set and hydration adopts instead of duplicating.
+ *
+ * WHY A MERGE EXISTS AT ALL. The platform resolves duplicates by taking the
+ * FIRST occurrence in tree order, `document.title` is defined as the first
+ * `<title>` element in the document, and a crawler reads the first
+ * `<meta name="description">`. Authoring order runs the other way: defaults come
+ * from the outer layout and the specific value from the inner page, so appending
+ * both would let the generic one win every time. Registrations are therefore
+ * keyed by identity and the LAST one wins, which is the precedence every SEO
+ * system uses and the one authors expect.
+ */
+export type MetaAttributes = Record<string, string | number | boolean | null | undefined>;
+/** One head element to render, plus the identity that decides what it replaces. */
+export interface SeoDescriptor {
+	tag: 'title' | 'meta' | 'link' | 'script';
+	/** Identity key: a later descriptor with the same key replaces this one. */
+	key: string;
+	attrs: MetaAttributes;
+	/** Text content, for `<title>` and for script bodies. */
+	text?: string;
+}
+/**
+ * Settings that belong to the app rather than to one declaration. They are
+ * registered like any other metadata and merged last-wins, so setting them once
+ * near the root applies them to every page's title and URLs.
+ */
+export interface SeoConfig {
+	/** Origin used to absolute-ise canonical, og:url, and image URLs. */
+	site?: string;
+	/** `%s` is replaced by the page title, e.g. `'%s · Acme'`. */
+	titleTemplate?: string;
+	/**
+	 * Whether an `openGraph`/`twitter` block was declared. Opting in is about
+	 * having asked for the family, not about which tags that produced:
+	 * `openGraph: { publishedTime }` emits only `article:published_time`, which no
+	 * `og:` prefix scan would recognise.
+	 */
+	declaredOpenGraph?: boolean;
+	declaredTwitter?: boolean;
+}
+/**
+ * `<link>` rels whose `href` is an ADDRESS rather than a subresource, so it
+ * belongs to the canonical site and must be absolute.
+ *
+ * Everything else a `<link>` can point at, resource hints, stylesheets, icons,
+ * the manifest, is fetched by the browser and has to resolve against the
+ * document actually serving the response. Rewriting those to `site` would make a
+ * preview or staging deploy pull fonts, CSS, and modules from production.
+ */
+const SITE_ABSOLUTE_LINK_RELS = new Set(['canonical', 'alternate']);
+/**
+ * The attribute holding a URL that a consumer will not resolve relative to the
+ * page, so it is absolute-ised against the configured origin at emit time, once
+ * the whole tree's config is known. Scrapers fetch `og:image` and read `og:url`
+ * without a base, and crawlers expect absolute canonical and hreflang addresses.
+ */
+function urlAttribute(descriptor: SeoDescriptor): string | null {
+	if (descriptor.tag === 'link') {
+		const rel = descriptor.attrs.rel;
+		return typeof rel === 'string' && SITE_ABSOLUTE_LINK_RELS.has(rel) ? 'href' : null;
+	}
+	if (descriptor.tag !== 'meta') return null;
+	const property = descriptor.attrs.property;
+	if (property === 'og:url' || property === 'og:image') return 'content';
+	if (descriptor.attrs.name === 'twitter:image') return 'content';
+	return null;
+}
+/**
+ * Social tags that mirror a page value when the author has opted into that
+ * family but has not named them. `og:type` without `og:title` produces a useless
+ * card, and the page that owns the title is usually not the component that
+ * declared the Open Graph shell.
+ */
+const SOCIAL_FILL: readonly {
+	readonly key: string;
+	readonly family: 'og' | 'twitter';
+	readonly attrs: (value: string) => MetaAttributes;
+	readonly source: 'title' | 'description' | 'canonical';
+}[] = [
+	{
+		key: 'meta:property=og:title',
+		family: 'og',
+		attrs: (content) => ({ property: 'og:title', content }),
+		source: 'title',
+	},
+	{
+		key: 'meta:property=og:description',
+		family: 'og',
+		attrs: (content) => ({ property: 'og:description', content }),
+		source: 'description',
+	},
+	{
+		key: 'meta:property=og:url',
+		family: 'og',
+		attrs: (content) => ({ property: 'og:url', content }),
+		source: 'canonical',
+	},
+	{
+		key: 'meta:name=twitter:title',
+		family: 'twitter',
+		attrs: (content) => ({ name: 'twitter:title', content }),
+		source: 'title',
+	},
+	{
+		key: 'meta:name=twitter:description',
+		family: 'twitter',
+		attrs: (content) => ({ name: 'twitter:description', content }),
+		source: 'description',
+	},
+];
+/**
+ * Finish the merged set: mirror page values into the social families the author
+ * opted into, apply the title template, and absolute-ise URLs.
+ *
+ * All three are deferred to emit time for the same reason: a page registers its
+ * title, description, and canonical without ever seeing the root's `site`,
+ * `titleTemplate`, or Open Graph shell, and the root registers its shell without
+ * seeing which page will render.
+ *
+ * Order matters, and this is the ONLY place the template is applied. The social
+ * fill reads the title before that happens, because `og:site_name` already
+ * carries the suffix a template adds; templating anywhere earlier would leak the
+ * suffix into `og:title`. URL resolution runs last so an `og:url` mirrored from
+ * the canonical is absolute-ised too.
+ */
+export function applyConfig(
+	descriptors: readonly SeoDescriptor[],
+	config: SeoConfig,
+): SeoDescriptor[] {
+	const { site, titleTemplate } = config;
+	const present = new Set(descriptors.map((descriptor) => descriptor.key));
+	const sources = {
+		title: descriptors.find((d) => d.tag === 'title')?.text,
+		description: stringAttr(descriptors, 'meta:name=description', 'content'),
+		canonical: stringAttr(descriptors, 'link:canonical', 'href'),
+	};
+	// Opted in either by declaring the block through `<Seo>` or by hand-writing a
+	// tag of that family. Nobody who never asked for Open Graph starts emitting it.
+	const optedIn = {
+		og: config.declaredOpenGraph === true,
+		twitter: config.declaredTwitter === true,
+	};
+	for (const descriptor of descriptors) {
+		if (descriptor.key.startsWith('meta:property=og:')) optedIn.og = true;
+		else if (descriptor.key.startsWith('meta:name=twitter:')) optedIn.twitter = true;
+	}
+	const filled: SeoDescriptor[] = [...descriptors];
+	for (const entry of SOCIAL_FILL) {
+		if (!optedIn[entry.family] || present.has(entry.key)) continue;
+		const value = sources[entry.source];
+		if (value === undefined || value === '') continue;
+		filled.push({ tag: 'meta', key: entry.key, attrs: entry.attrs(value) });
+	}
+	if (site === undefined && titleTemplate === undefined) return filled;
+	return filled.map((descriptor) => {
+		if (
+			titleTemplate !== undefined &&
+			descriptor.tag === 'title' &&
+			descriptor.text !== undefined &&
+			descriptor.text !== ''
+		) {
+			// Function replacement: the title is data, so its dollar patterns must not
+			// expand against the `%s` match.
+			return {
+				...descriptor,
+				text: titleTemplate.replace('%s', () => descriptor.text as string),
+			};
+		}
+		const attr = site === undefined ? null : urlAttribute(descriptor);
+		if (attr !== null) {
+			const value = descriptor.attrs[attr];
+			if (typeof value === 'string') {
+				const resolved = resolveUrl(value, site);
+				if (resolved !== value) {
+					return { ...descriptor, attrs: { ...descriptor.attrs, [attr]: resolved } };
+				}
+			}
+		}
+		return descriptor;
+	});
+}
+function stringAttr(
+	descriptors: readonly SeoDescriptor[],
+	key: string,
+	attr: string,
+): string | undefined {
+	const value = descriptors.find((descriptor) => descriptor.key === key)?.attrs[attr];
+	return typeof value === 'string' ? value : undefined;
+}
+/**
+ * How a `<link>`'s identity is derived. It has to differ by `rel`, because
+ * `href` is sometimes the value being set and sometimes the thing being
+ * identified, and getting that backwards breaks overrides in one direction or
+ * drops tags in the other.
+ *
+ * - **Singleton**: one per document, so `rel` alone is the identity.
+ * - **Slot-keyed**: the listed attributes name a slot and `href` is its value.
+ *   A page replacing a layout's German alternate, or the same-sized icon, must
+ *   win, so `href` is deliberately NOT part of the key.
+ * - **URL-keyed** (everything else): the target IS the identity, so two font
+ *   preloads or two stylesheets coexist. Unknown rels default here on purpose,
+ *   since dropping someone's tag is worse than emitting two.
+ */
+const SINGLETON_LINK_RELS = new Set(['canonical', 'manifest', 'author', 'license', 'prev', 'next']);
+const SLOT_KEYED_LINK_RELS = new Map<string, readonly string[]>([
+	['alternate', ['hreflang', 'type', 'media', 'title']],
+	['icon', ['sizes', 'type', 'media']],
+	['shortcut icon', ['sizes', 'type']],
+	['apple-touch-icon', ['sizes', 'type']],
+	['apple-touch-icon-precomposed', ['sizes', 'type']],
+	['mask-icon', ['color']],
+	['search', ['type', 'title']],
+]);
+const URL_KEYED_LINK_ATTRS = ['href', 'as', 'media', 'type', 'hreflang', 'sizes'] as const;
+/**
+ * Escape a value before it becomes part of an identity key. Keys join
+ * author-controlled values with `|` and `=`, so an unescaped value containing
+ * those could forge another tag's key and one of the two would be silently
+ * dropped from the document. Data stays data.
+ */
+function keyPart(value: string): string {
+	return value.replace(/[\\|=#]/g, (character) => '\\' + character);
+}
+function attrString(attrs: MetaAttributes, name: string): string | null {
+	const value = attrs[name];
+	if (value === null || value === undefined || value === false) return null;
+	return String(value);
+}
+/**
+ * Identity for a `<meta>`: whichever naming attribute it uses. Open Graph uses
+ * `property`, most others use `name`, and `http-equiv` is its own namespace, so
+ * `og:title` and a `name="og:title"` never collide by accident.
+ */
+export function metaKey(attrs: MetaAttributes): string {
+	if (attrs.charSet !== undefined || attrs.charset !== undefined) return 'meta:charset';
+	for (const naming of ['name', 'property', 'http-equiv', 'httpEquiv', 'itemprop']) {
+		const value = attrString(attrs, naming);
+		if (value !== null) {
+			const channel = naming === 'httpEquiv' ? 'http-equiv' : naming;
+			return 'meta:' + channel + '=' + keyPart(value);
+		}
+	}
+	// No naming attribute: keep every such tag by giving it a content-derived
+	// identity rather than silently collapsing unrelated tags together.
+	return 'meta:raw=' + JSON.stringify(attrs);
+}
+export function linkKey(attrs: MetaAttributes): string {
+	const rel = attrString(attrs, 'rel') ?? '';
+	if (SINGLETON_LINK_RELS.has(rel)) return 'link:' + rel;
+	const slotAttrs = SLOT_KEYED_LINK_RELS.get(rel);
+	let key = 'link:' + rel;
+	if (slotAttrs !== undefined) {
+		let named = false;
+		for (const name of slotAttrs) {
+			const value = attrString(attrs, name);
+			if (value !== null) {
+				key += '|' + name + '=' + keyPart(value);
+				named = true;
+			}
+		}
+		// A slot-keyed rel carrying none of its discriminators names no slot, so
+		// fall through to the URL rather than collapsing unrelated tags together.
+		if (named) return key;
+	}
+	for (const name of URL_KEYED_LINK_ATTRS) {
+		const value = attrString(attrs, name);
+		if (value !== null) key += '|' + name + '=' + keyPart(value);
+	}
+	return key;
+}
+/**
+ * Merge registrations into the set to render, last-wins per identity.
+ *
+ * Insertion order is preserved for keys that survive: replacing a descriptor
+ * updates it in place rather than moving it to the end, so server and client
+ * produce the same order and hydration adoption stays positional. That also
+ * makes the merge idempotent across SSR suspense passes, where the same
+ * component re-registers the same key on every pass.
+ */
+export function mergeDescriptors(registrations: readonly SeoDescriptor[]): SeoDescriptor[] {
+	const byKey = new Map<string, number>();
+	const out: SeoDescriptor[] = [];
+	for (const descriptor of registrations) {
+		const at = byKey.get(descriptor.key);
+		if (at === undefined) {
+			byKey.set(descriptor.key, out.length);
+			out.push(descriptor);
+		} else {
+			out[at] = descriptor;
+		}
+	}
+	return out;
+}
+/** Absolute-ise a canonical/og:url style value against the configured site origin. */
+export function resolveUrl(value: string, site: string | undefined): string {
+	if (site === undefined || /^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith('//')) {
+		return value;
+	}
+	return site.replace(/\/+$/, '') + (value.startsWith('/') ? value : '/' + value);
+}

package/src/expand.ts ADDED Viewed

@@ -0,0 +1,262 @@
+/**
+ * Expand the ergonomic `<Seo …>` object into the flat descriptor list the merge
+ * engine works on. Kept renderer-free and pure so precedence, URL resolution,
+ * and title templating are unit-testable without a render.
+ */
+import { linkKey, metaKey, type SeoDescriptor } from './descriptors.js';
+export interface OpenGraphImage {
+	url: string;
+	alt?: string;
+	width?: number | string;
+	height?: number | string;
+	type?: string;
+}
+export interface OpenGraphInput {
+	title?: string;
+	description?: string;
+	type?: string;
+	url?: string;
+	siteName?: string;
+	locale?: string;
+	images?: string | OpenGraphImage | Array<string | OpenGraphImage>;
+	publishedTime?: string;
+	modifiedTime?: string;
+}
+export interface TwitterInput {
+	card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+	site?: string;
+	creator?: string;
+	title?: string;
+	description?: string;
+	image?: string;
+	imageAlt?: string;
+}
+export interface RobotsInput {
+	index?: boolean;
+	follow?: boolean;
+	noarchive?: boolean;
+	nosnippet?: boolean;
+	maxSnippet?: number;
+	maxImagePreview?: 'none' | 'standard' | 'large';
+}
+export interface SeoInput {
+	title?: string;
+	/**
+	 * `%s` is replaced by the page title. App-level: declaring it once applies it
+	 * to whichever page renders, and it is applied after the merge, so social tags
+	 * still mirror the untemplated title.
+	 */
+	titleTemplate?: string;
+	description?: string;
+	canonical?: string;
+	/** Origin used to absolute-ise canonical, og:url, and image URLs. */
+	site?: string;
+	robots?: string | RobotsInput;
+	openGraph?: OpenGraphInput;
+	twitter?: TwitterInput;
+	/** `hreflang` alternates: language tag to URL. */
+	languages?: Record<string, string>;
+	jsonLd?: unknown;
+}
+/**
+ * Escape a key component so a `@type` containing `#` cannot forge the key of a
+ * different graph and silently replace it.
+ */
+function jsonLdKeyPart(value: string): string {
+	return value.replace(/[\\#]/g, (character) => '\\' + character);
+}
+function meta(attrs: Record<string, string>): SeoDescriptor {
+	return { tag: 'meta', key: metaKey(attrs), attrs };
+}
+function link(attrs: Record<string, string>): SeoDescriptor {
+	return { tag: 'link', key: linkKey(attrs), attrs };
+}
+export function formatRobots(robots: string | RobotsInput): string {
+	if (typeof robots === 'string') return robots;
+	const parts: string[] = [];
+	parts.push(robots.index === false ? 'noindex' : 'index');
+	parts.push(robots.follow === false ? 'nofollow' : 'follow');
+	if (robots.noarchive) parts.push('noarchive');
+	if (robots.nosnippet) parts.push('nosnippet');
+	if (robots.maxSnippet !== undefined) parts.push('max-snippet:' + robots.maxSnippet);
+	if (robots.maxImagePreview !== undefined) {
+		parts.push('max-image-preview:' + robots.maxImagePreview);
+	}
+	return parts.join(', ');
+}
+function normalizeImages(images: OpenGraphInput['images']): OpenGraphImage[] {
+	if (images === undefined) return [];
+	const list = Array.isArray(images) ? images : [images];
+	return list.map((image) => (typeof image === 'string' ? { url: image } : image));
+}
+export function expandSeo(input: SeoInput): SeoDescriptor[] {
+	const out: SeoDescriptor[] = [];
+	// The RAW title. `titleTemplate` is app-level config applied after the merge,
+	// so the social mirror always sees the untemplated value regardless of which
+	// `<Seo>` declared the template.
+	if (input.title !== undefined) {
+		out.push({ tag: 'title', key: 'title', attrs: {}, text: input.title });
+	}
+	if (input.description !== undefined) {
+		out.push(meta({ name: 'description', content: input.description }));
+	}
+	if (input.robots !== undefined) {
+		out.push(meta({ name: 'robots', content: formatRobots(input.robots) }));
+	}
+	if (input.canonical !== undefined) {
+		out.push(link({ rel: 'canonical', href: input.canonical }));
+	}
+	const og = input.openGraph;
+	if (og !== undefined) {
+		// Open Graph falls back to the page title/description so the common case
+		// needs no duplication, while an explicit og value still overrides.
+		const ogTitle = og.title ?? input.title;
+		const ogDescription = og.description ?? input.description;
+		const ogUrl = og.url ?? input.canonical;
+		if (og.type !== undefined) out.push(meta({ property: 'og:type', content: og.type }));
+		if (og.siteName !== undefined) {
+			out.push(meta({ property: 'og:site_name', content: og.siteName }));
+		}
+		if (ogTitle !== undefined) out.push(meta({ property: 'og:title', content: ogTitle }));
+		if (ogDescription !== undefined) {
+			out.push(meta({ property: 'og:description', content: ogDescription }));
+		}
+		if (ogUrl !== undefined) {
+			out.push(meta({ property: 'og:url', content: ogUrl }));
+		}
+		if (og.locale !== undefined) out.push(meta({ property: 'og:locale', content: og.locale }));
+		if (og.publishedTime !== undefined) {
+			out.push(meta({ property: 'article:published_time', content: og.publishedTime }));
+		}
+		if (og.modifiedTime !== undefined) {
+			out.push(meta({ property: 'article:modified_time', content: og.modifiedTime }));
+		}
+		// URLs stay as authored here. `applyConfig` absolute-ises them after the
+		// merge, so one place decides which origin applies.
+		const images = normalizeImages(og.images);
+		for (let i = 0; i < images.length; i++) {
+			const image = images[i];
+			const url = image.url;
+			// Repeated og:image tags are legitimate, so each gets its own identity.
+			out.push({
+				tag: 'meta',
+				key: 'meta:property=og:image[' + i + ']',
+				attrs: { property: 'og:image', content: url },
+			});
+			if (image.alt !== undefined) {
+				out.push({
+					tag: 'meta',
+					key: 'meta:property=og:image:alt[' + i + ']',
+					attrs: { property: 'og:image:alt', content: image.alt },
+				});
+			}
+			if (image.width !== undefined) {
+				out.push({
+					tag: 'meta',
+					key: 'meta:property=og:image:width[' + i + ']',
+					attrs: { property: 'og:image:width', content: String(image.width) },
+				});
+			}
+			if (image.height !== undefined) {
+				out.push({
+					tag: 'meta',
+					key: 'meta:property=og:image:height[' + i + ']',
+					attrs: { property: 'og:image:height', content: String(image.height) },
+				});
+			}
+			if (image.type !== undefined) {
+				out.push({
+					tag: 'meta',
+					key: 'meta:property=og:image:type[' + i + ']',
+					attrs: { property: 'og:image:type', content: image.type },
+				});
+			}
+		}
+	}
+	const twitter = input.twitter;
+	if (twitter !== undefined) {
+		if (twitter.card !== undefined) out.push(meta({ name: 'twitter:card', content: twitter.card }));
+		if (twitter.site !== undefined) out.push(meta({ name: 'twitter:site', content: twitter.site }));
+		if (twitter.creator !== undefined) {
+			out.push(meta({ name: 'twitter:creator', content: twitter.creator }));
+		}
+		const twitterTitle = twitter.title ?? input.title;
+		const twitterDescription = twitter.description ?? input.description;
+		if (twitterTitle !== undefined) {
+			out.push(meta({ name: 'twitter:title', content: twitterTitle }));
+		}
+		if (twitterDescription !== undefined) {
+			out.push(meta({ name: 'twitter:description', content: twitterDescription }));
+		}
+		if (twitter.image !== undefined) {
+			out.push(meta({ name: 'twitter:image', content: twitter.image }));
+		}
+		if (twitter.imageAlt !== undefined) {
+			out.push(meta({ name: 'twitter:image:alt', content: twitter.imageAlt }));
+		}
+	}
+	if (input.languages !== undefined) {
+		for (const [hreflang, href] of Object.entries(input.languages)) {
+			out.push(link({ rel: 'alternate', hreflang, href }));
+		}
+	}
+	if (input.jsonLd !== undefined) {
+		const descriptor = jsonLdDescriptor(input.jsonLd);
+		if (descriptor !== null) out.push(descriptor);
+	}
+	return out;
+}
+/**
+ * JSON-LD identity is its `@type` (plus `@id` when present), so a page-level
+ * Article replaces a layout-level Article but coexists with a BreadcrumbList.
+ */
+export function jsonLdDescriptor(data: unknown, explicitKey?: string): SeoDescriptor | null {
+	// Serialization is the one place author data can take the whole render down:
+	// a cyclic graph or a BigInt makes JSON.stringify throw, and that would 500 a
+	// page over one structured-data object. Degrade instead, loudly. A graph that
+	// cannot serialize cannot be valid structured data either, so emitting nothing
+	// is better than emitting something broken.
+	let text: string;
+	try {
+		text = JSON.stringify(data);
+	} catch (error) {
+		console.error(
+			'[@octanejs/seo] Could not serialize JSON-LD, so no structured data was ' +
+				'emitted for it. Values such as cycles and BigInt cannot be represented: ' +
+				(error instanceof Error ? error.message : String(error)),
+		);
+		return null;
+	}
+	if (text === undefined) return null;
+	let key = explicitKey;
+	if (key === undefined) {
+		const record = (data ?? {}) as Record<string, unknown>;
+		const type = typeof record['@type'] === 'string' ? (record['@type'] as string) : 'graph';
+		const id = typeof record['@id'] === 'string' ? (record['@id'] as string) : '';
+		key = jsonLdKeyPart(type) + '#' + jsonLdKeyPart(id);
+	}
+	return {
+		tag: 'script',
+		key: 'jsonLd:' + key,
+		attrs: { type: 'application/ld+json' },
+		text,
+	};
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,31 @@
+/**
+ * `@octanejs/seo`, declarative document metadata for Octane.
+ *
+ * `<Head>` is the only component to learn. Wrap the app in one, then use it
+ * again wherever metadata belongs, filled with `<Title>`, `<Meta>`, `<Link>`,
+ * `<Script>`, `<JsonLd>`, or the all-in-one `<Seo>`. Blocks merge wherever they
+ * sit, siblings included, last-wins per identity, so a page overrides a layout
+ * simply by rendering later. Metadata is server-rendered into `<head>` and
+ * adopted on hydration rather than duplicated.
+ *
+ * Why the merge matters: the platform takes the FIRST duplicate in tree order
+ * (`document.title` is the first `<title>` in the document, and a crawler reads
+ * the first `meta[name=description]`), while authoring order puts layout
+ * defaults before page specifics. Appending both would let the generic value
+ * win every time, so identity-keyed last-wins is applied before anything is
+ * emitted.
+ */
+export { Head, Title, Meta, Link, Script, JsonLd, Seo } from './components.tsrx';
+export { applyConfig, mergeDescriptors, metaKey, linkKey, resolveUrl } from './descriptors.js';
+export type { SeoConfig, SeoDescriptor, MetaAttributes } from './descriptors.js';
+export { expandSeo, formatRobots, jsonLdDescriptor } from './expand.js';
+export type {
+	SeoInput,
+	OpenGraphInput,
+	OpenGraphImage,
+	TwitterInput,
+	RobotsInput,
+} from './expand.js';
+export { createSeoRegistry } from './registry.js';
+export type { SeoRegistry } from './registry.js';
+export { SeoContext } from './context.js';

package/src/registry.ts ADDED Viewed

@@ -0,0 +1,125 @@
+/**
+ * The per-tree registry every `<Title>`/`<Meta>`/`<Link>`/`<JsonLd>` writes into
+ * and `<SeoOutlet>` reads back.
+ *
+ * The registry is created by `<SeoProvider>` and passed through context, never
+ * held in module scope: concurrent SSR requests each get their own, so one
+ * request can never observe another's metadata.
+ *
+ * Registrations are grouped by SOURCE (one per component instance) rather than
+ * flattened on write, so a source that re-renders with a different key replaces
+ * its previous entry instead of leaving the stale one behind, and a source that
+ * unmounts takes its metadata with it. Source order is insertion order, which is
+ * render order, which is why the outlet emits the same sequence on the server
+ * and the client and hydration adoption stays positional.
+ */
+import {
+	applyConfig,
+	mergeDescriptors,
+	type SeoConfig,
+	type SeoDescriptor,
+} from './descriptors.js';
+export interface SeoRegistry {
+	/** Record (or replace) one source's descriptors. Called during render. */
+	register(sourceId: number, descriptors: readonly SeoDescriptor[]): void;
+	/** Record app-level settings from one source; merged last-wins like metadata. */
+	configure(sourceId: number, config: SeoConfig): void;
+	remove(sourceId: number): void;
+	/** Allocate a stable id for a component instance. */
+	nextSourceId(): number;
+	/** Merged, last-wins descriptor list. Referentially stable between changes. */
+	getSnapshot(): readonly SeoDescriptor[];
+	subscribe(listener: () => void): () => void;
+	/** Notify subscribers if anything changed since the last flush. */
+	flush(): void;
+}
+function sameDescriptors(a: readonly SeoDescriptor[], b: readonly SeoDescriptor[]): boolean {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		const x = a[i];
+		const y = b[i];
+		if (x.key !== y.key || x.tag !== y.tag || x.text !== y.text) return false;
+		const xa = x.attrs;
+		const ya = y.attrs;
+		const xk = Object.keys(xa);
+		if (xk.length !== Object.keys(ya).length) return false;
+		for (const k of xk) if (xa[k] !== ya[k]) return false;
+	}
+	return true;
+}
+function sameConfig(a: SeoConfig, b: SeoConfig): boolean {
+	const keys = new Set([...Object.keys(a), ...Object.keys(b)]) as Set<keyof SeoConfig>;
+	for (const key of keys) if (a[key] !== b[key]) return false;
+	return true;
+}
+export function createSeoRegistry(): SeoRegistry {
+	const sources = new Map<number, readonly SeoDescriptor[]>();
+	const configs = new Map<number, SeoConfig>();
+	const listeners = new Set<() => void>();
+	let nextId = 1;
+	let snapshot: readonly SeoDescriptor[] | null = null;
+	let dirty = false;
+	function invalidate(): void {
+		snapshot = null;
+		dirty = true;
+	}
+	return {
+		nextSourceId() {
+			return nextId++;
+		},
+		register(sourceId, descriptors) {
+			const previous = sources.get(sourceId);
+			// Re-registering identical descriptors is the common case on an SSR
+			// suspense re-pass and on any parent re-render; treating it as a no-op
+			// keeps the snapshot reference stable so the outlet does not re-render.
+			if (previous !== undefined && sameDescriptors(previous, descriptors)) return;
+			sources.set(sourceId, descriptors);
+			invalidate();
+		},
+		configure(sourceId, config) {
+			const previous = configs.get(sourceId);
+			// Compared field-by-field over the union of keys, so adding a SeoConfig
+			// field cannot silently escape this check and stop invalidating.
+			if (previous !== undefined && sameConfig(previous, config)) return;
+			configs.set(sourceId, config);
+			invalidate();
+		},
+		remove(sourceId) {
+			const had = sources.delete(sourceId);
+			if (configs.delete(sourceId) || had) invalidate();
+		},
+		getSnapshot() {
+			if (snapshot === null) {
+				const flat: SeoDescriptor[] = [];
+				for (const descriptors of sources.values()) flat.push(...descriptors);
+				const effective: SeoConfig = {};
+				for (const config of configs.values()) {
+					if (config.site !== undefined) effective.site = config.site;
+					if (config.titleTemplate !== undefined) effective.titleTemplate = config.titleTemplate;
+					// Declaring a social family anywhere opts the whole tree in.
+					if (config.declaredOpenGraph === true) effective.declaredOpenGraph = true;
+					if (config.declaredTwitter === true) effective.declaredTwitter = true;
+				}
+				snapshot = applyConfig(mergeDescriptors(flat), effective);
+			}
+			return snapshot;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		flush() {
+			if (!dirty) return;
+			dirty = false;
+			for (const listener of listeners) listener();
+		},
+	};
+}

package/src/useRegister.ts ADDED Viewed

@@ -0,0 +1,55 @@
+/**
+ * Register one component instance's descriptors with the enclosing registry.
+ *
+ * Registration happens DURING RENDER, not in an effect: effects never run on the
+ * server, so an effect-based registration would leave the server-rendered
+ * `<head>` empty and hand crawlers nothing. That is precisely the failure this
+ * package exists to remove.
+ *
+ * The effect below exists only for the client half of the lifecycle: it notifies
+ * the outlet after a commit that changed something, and removes the source on
+ * unmount so a navigated-away page stops contributing. Document metadata does
+ * not affect layout, so it does not need to block paint.
+ */
+import { useContext, useEffect, useRef } from 'octane';
+import { SeoContext } from './context.js';
+import type { SeoConfig, SeoDescriptor } from './descriptors.js';
+export function useRegisterSeo(descriptors: readonly SeoDescriptor[], config?: SeoConfig): void {
+	const registry = useContext(SeoContext);
+	if (registry === null) {
+		throw new Error(
+			'[@octanejs/seo] <Title>/<Meta>/<Link>/<Script>/<JsonLd>/<Seo> must render inside a <Head>.',
+		);
+	}
+	const idRef = useRef<number>(0);
+	if (idRef.current === 0) idRef.current = registry.nextSourceId();
+	registry.register(idRef.current, descriptors);
+	if (config !== undefined) registry.configure(idRef.current, config);
+	// Two effects, and they must stay separate.
+	//
+	// Publish re-registers the committed descriptors and notifies the outlet. The
+	// dependency array is left to the compiler on purpose: `descriptors` is read
+	// here, so inference keys the effect on it and re-runs exactly when the
+	// metadata this component contributes may have changed. Both calls are
+	// idempotent, re-registering an equal set is a no-op and `flush()` does
+	// nothing unless something actually changed.
+	useEffect(() => {
+		registry.register(idRef.current, descriptors);
+		if (config !== undefined) registry.configure(idRef.current, config);
+		registry.flush();
+	});
+	// Teardown is mount/unmount ONLY. It cannot ride the effect above: that one
+	// re-runs, and a cleanup running before each re-run would make a component
+	// delete its own registration merely by re-rendering, letting an outer
+	// default win. This closure reads nothing that changes, so inference gives it
+	// mount/unmount semantics on its own.
+	useEffect(() => {
+		return () => {
+			registry.remove(idRef.current);
+			registry.flush();
+		};
+	});
+}

package/src/useStrayOwnerDiagnostic.ts ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * Development check for the one arrangement that produces wrong metadata: two
+ * OUTERMOST `<Head>` elements, neither containing the other.
+ *
+ * Each owns a registry and emits its own merged set, so the document ends up
+ * with two `<title>` elements and the platform keeps the first. Whichever
+ * component happened to render first wins, which is silent and arbitrary. The
+ * fix is always the same, wrap the app in one `<Head>` so every other block
+ * resolves to it.
+ *
+ * Reported with `console.error`, not `warn`: this is a correctness bug in the
+ * page's metadata, not a style note.
+ *
+ * Client-only by construction. It counts in an effect, and effects never run on
+ * the server, so concurrent SSR requests cannot inflate a shared counter.
+ */
+import { useEffect } from 'octane';
+let liveOwners = 0;
+let reported = false;
+export function useStrayOwnerDiagnostic(owns: boolean): void {
+	if (process.env.NODE_ENV === 'production') return;
+	useEffect(() => {
+		if (!owns) return;
+		liveOwners++;
+		if (liveOwners > 1 && !reported) {
+			reported = true;
+			console.error(
+				'[@octanejs/seo] Two <Head> elements are mounted with neither containing the ' +
+					'other, so each emits its own merged set: the document will carry duplicate ' +
+					'tags and the FIRST in document order will win, which makes the other ' +
+					"component's metadata silently ineffective. Wrap the app in a single " +
+					'<Head> so every other <Head> block merges into it.',
+			);
+		}
+		return () => {
+			liveOwners--;
+			if (liveOwners <= 1) reported = false;
+		};
+	});
+}