@thomasfosterau/components 0.0.0-stage → 0.1.0

package/dist/search/CommandPalette.svelte.d.ts

@@ -0,0 +1,59 @@
+import type { Snippet } from 'svelte';
+import { type CommandGroup, type CommandItem } from './types.ts';
+interface Props {
+    /**
+     * Whether the palette is shown. Bindable. Two-way bound to the hotkey
+     * registry's `paletteOpen` when a registry is mounted above.
+     */
+    open?: boolean | undefined;
+    /**
+     * Names the command menu, and titles the dialog.
+     * @defaultValue `'Command palette'`
+     */
+    label?: string | undefined;
+    /**
+     * Placeholder in the search field.
+     * @defaultValue `'Type a command or search…'`
+     */
+    placeholder?: string | undefined;
+    /**
+     * Announced while an `onSearch` request is in flight.
+     * @defaultValue `'Searching…'`
+     */
+    loadingLabel?: string | undefined;
+    /**
+     * Shown when a settled query matched nothing.
+     * @defaultValue `'No results'`
+     */
+    emptyLabel?: string | undefined;
+    /**
+     * Accessible name of the dialog's close button.
+     * @defaultValue `'Close'`
+     */
+    closeLabel?: string | undefined;
+    /**
+     * The sections, in render order. Rows name one by `id`.
+     * @defaultValue the exported `defaultCommandGroups`
+     */
+    groups?: readonly CommandGroup[] | undefined;
+    /** Rows that are always available, registry or no registry. */
+    items?: readonly CommandItem[] | undefined;
+    /**
+     * Fetch rows for a query. Debounced by `debounceMs`; `signal` aborts when
+     * a newer query supersedes this one, so pass it to `fetch`.
+     */
+    onSearch?: ((query: string, signal: AbortSignal) => Promise<readonly CommandItem[]>) | undefined;
+    /**
+     * Quiet period before a search starts, in milliseconds.
+     * @defaultValue `150`
+     */
+    debounceMs?: number | undefined;
+    /** Called when a row is activated, before its own `run` / `href`. */
+    onSelect?: ((item: CommandItem) => void) | undefined;
+    /** Replace a row's contents. */
+    item?: Snippet<[CommandItem]> | undefined;
+}
+/** The ⌘K / Ctrl+K command palette: bits-ui’s `Command` inside this library’s `Dialog`. */
+declare const CommandPalette: import("svelte").Component<Props, {}, "open">;
+type CommandPalette = ReturnType<typeof CommandPalette>;
+export default CommandPalette;

package/dist/search/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * search — the command palette.
+ *
+ * One component, because a palette is one thing: a dialog, a query box, and
+ * rows from wherever the app has them. It composes `feedback/Dialog` and
+ * bits-ui's `Command`, lists the hotkey registry's palette actions when a
+ * registry is mounted, and works from `items` / `onSearch` alone when none
+ * is.
+ *
+ * @module
+ */
+export { default as CommandPalette } from './CommandPalette.svelte';
+export { defaultCommandGroups, type CommandGroup, type CommandItem } from './types.ts';

package/dist/search/index.js

@@ -0,0 +1,13 @@
+/**
+ * search — the command palette.
+ *
+ * One component, because a palette is one thing: a dialog, a query box, and
+ * rows from wherever the app has them. It composes `feedback/Dialog` and
+ * bits-ui's `Command`, lists the hotkey registry's palette actions when a
+ * registry is mounted, and works from `items` / `onSearch` alone when none
+ * is.
+ *
+ * @module
+ */
+export { default as CommandPalette } from './CommandPalette.svelte';
+export { defaultCommandGroups } from "./types.js";

package/dist/search/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The row and section shapes the command palette renders.
+ *
+ * A {@link CommandItem} is deliberately not a `CommandAction`: registry
+ * actions always run something, whereas a palette row can just as well be a
+ * search result that navigates, or a row whose whole behaviour is the
+ * caller's `onSelect`. The palette projects registry actions into this shape
+ * internally, so one row renderer serves both sources.
+ *
+ * @module
+ */
+export interface CommandItem {
+    /** Stable id. Unique within its group; it is what bits-ui ranks and selects on. */
+    id: string;
+    /** The row's text — what the reader searches for and what is announced. */
+    label: string;
+    /** Which {@link CommandGroup} the row belongs in, by `id`. */
+    group: string;
+    /** Muted trailing text: a path, a date, a parent name. */
+    hint?: string | undefined;
+    /** A short chip on the right — a type, a status. */
+    badge?: string | undefined;
+    /** What activating the row does. Runs after the palette closes. */
+    run?: (() => void | Promise<void>) | undefined;
+    /** Where activating the row goes. Resolved through the components context. */
+    href?: string | undefined;
+}
+/** A palette section: an id rows point at, and the heading it renders. */
+export interface CommandGroup {
+    id: string;
+    label: string;
+}
+/**
+ * The sections a palette shows when given none: the two group ids the hotkey
+ * registry uses (`actions`, `navigation`), then whatever `onSearch` returns.
+ */
+export declare const defaultCommandGroups: readonly CommandGroup[];

package/dist/search/types.js

@@ -0,0 +1,20 @@
+/**
+ * The row and section shapes the command palette renders.
+ *
+ * A {@link CommandItem} is deliberately not a `CommandAction`: registry
+ * actions always run something, whereas a palette row can just as well be a
+ * search result that navigates, or a row whose whole behaviour is the
+ * caller's `onSelect`. The palette projects registry actions into this shape
+ * internally, so one row renderer serves both sources.
+ *
+ * @module
+ */
+/**
+ * The sections a palette shows when given none: the two group ids the hotkey
+ * registry uses (`actions`, `navigation`), then whatever `onSearch` returns.
+ */
+export const defaultCommandGroups = [
+    { id: 'actions', label: 'Actions' },
+    { id: 'navigation', label: 'Go to' },
+    { id: 'results', label: 'Results' },
+];

package/dist/seo/Head.svelte

@@ -0,0 +1,190 @@
+<!-- @component
+Per-page `<head>` metadata: title, description, canonical URL, `hreflang` alternates, Open Graph and Twitter / X tags, `article:*` and pagination links.
+-->
+<script lang="ts">/**
+* Per-page `<head>` metadata: the title (with an optional site-name
+* suffix), description, keywords, robots directive, canonical URL,
+* `hreflang` alternates, an optional feed link, Open Graph and Twitter / X
+* card tags, the `article:*` family, and `prev` / `next` pagination links.
+*
+* **Canonical on the production origin.** The explicit `canonical` wins;
+* otherwise the page self-references `pathname` resolved through
+* `canonicalHref` (the query is never part of it), so canonical and
+* `og:url` are never empty and a preview host never becomes canonical.
+* `canonicalHref` defaults to the components context's `href` — an app
+* whose `href` returns relative paths passes its own absolute resolver
+* here. `pathname` defaults to `window.location.pathname`, which does not
+* exist during SSR: a SvelteKit app passes `pathname={page.url.pathname}`.
+*
+* **Share image, in precedence order:** an explicit `image`, then a
+* per-page card built from `shareCard` by {@link ogImageUrl}, then
+* `defaultImage` — so every share renders a card when a default is set.
+*
+* **`og:type`** is derived from the Schema.org `type` when `openGraphType`
+* is not given, and the `article:*` tags are emitted only for `article`.
+* **`og:locale`** comes from `ogLocale`, else the context locale with `-`
+* replaced by `_` (`en-AU` → `en_AU`).
+*
+* Every string is a prop: `siteName` has no default (a library cannot know
+* the site), `feed.title` defaults to `'Latest changes'`, and the share
+* card's alt text defaults to `"<title> — <siteName>"` (the title alone without a `siteName`) via `shareCardAlt`.
+*
+* Renders only into `<svelte:head>`; there is no markup in the body.
+*/
+import { getComponentsContext } from "../context.svelte.js";
+import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH, ogImageUrl } from "./og-image.js";
+let { title, siteName = undefined, titleSeparator = " | ", description = undefined, keywords = undefined, type = undefined, openGraphType = undefined, canonical = undefined, pathname = undefined, canonicalHref = undefined, alternates = undefined, locales = undefined, ogLocale = undefined, feed = undefined, robots = undefined, image = undefined, shareCard = undefined, shareCardPath = undefined, shareCardAlt = undefined, defaultImage = undefined, published = undefined, modified = undefined, section = undefined, tags = undefined, twitterCard = "summary_large_image", twitterSite = undefined, twitterCreator = undefined, prevUrl = undefined, nextUrl = undefined } = $props();
+const context = getComponentsContext();
+/** Schema.org type → Open Graph type, so `og:type` is never empty. */
+const schemaToOpenGraph = {
+	WebPage: "website",
+	WebSite: "website",
+	CollectionPage: "website",
+	Article: "article",
+	BlogPosting: "article",
+	ProfilePage: "profile"
+};
+const resolveHref = $derived(canonicalHref ?? context.href);
+const resolvedTitle = $derived.by(() => {
+	const trimmed = title.trim();
+	if (trimmed === "") return siteName ?? "";
+	return siteName === undefined || siteName === "" ? trimmed : `${trimmed}${titleSeparator}${siteName}`;
+});
+const resolvedDescription = $derived(description === null || description === undefined || description.trim() === "" ? undefined : description);
+const resolvedCanonical = $derived.by(() => {
+	if (canonical !== undefined) return canonical;
+	const path = pathname ?? (typeof window === "undefined" ? undefined : window.location.pathname);
+	return path === undefined ? undefined : resolveHref(path);
+});
+const resolvedAlternates = $derived.by(() => {
+	if (alternates !== undefined) return alternates;
+	if (resolvedCanonical === undefined || locales === undefined || locales.length === 0) return [];
+	const href = resolvedCanonical;
+	return [...locales, "x-default"].map((lang) => ({
+		href,
+		lang
+	}));
+});
+const resolvedOgType = $derived(openGraphType ?? (type === undefined ? "website" : schemaToOpenGraph[type]));
+const resolvedOgLocale = $derived.by(() => {
+	if (ogLocale !== undefined) return ogLocale;
+	const locale = context.locale();
+	const first = typeof locale === "string" ? locale : locale?.[0];
+	return first === undefined ? undefined : first.replace(/-/g, "_");
+});
+const cardImage = $derived.by(() => {
+	if (image !== undefined || shareCard === undefined) return undefined;
+	const url = ogImageUrl(shareCard, {
+		href: resolveHref,
+		basePath: shareCardPath
+	});
+	if (url === undefined) return undefined;
+	const alt = shareCardAlt?.(shareCard) ?? (siteName === undefined || siteName === "" ? shareCard.title.trim() : `${shareCard.title.trim()} — ${siteName}`);
+	return {
+		url,
+		alt,
+		width: OG_IMAGE_WIDTH,
+		height: OG_IMAGE_HEIGHT,
+		type: "image/png"
+	};
+});
+const resolvedImage = $derived(image ?? cardImage ?? defaultImage);
+const robotsContent = $derived(`${robots?.index ?? true ? "index" : "noindex"}, ${robots?.follow ?? true ? "follow" : "nofollow"}`);
+const resolvedSection = $derived(section?.trim() === "" ? undefined : section);
+</script>
+
+{#snippet articleMeta()}
+  {#if published !== undefined}
+    <meta property="article:published_time" content={published.toISOString()} />
+  {/if}
+  {#if modified !== undefined}
+    <meta property="article:modified_time" content={modified.toISOString()} />
+  {/if}
+  {#if resolvedSection !== undefined}
+    <meta property="article:section" content={resolvedSection} />
+  {/if}
+  {#each tags ?? [] as tag}
+    <meta property="article:tag" content={tag} />
+  {/each}
+{/snippet}
+
+<svelte:head>
+  <title>{resolvedTitle}</title>
+  {#if resolvedDescription !== undefined}
+    <meta name="description" content={resolvedDescription} />
+  {/if}
+  {#if keywords !== undefined && keywords.length > 0}
+    <meta name="keywords" content={keywords.join(', ')} />
+  {/if}
+  {#if resolvedCanonical !== undefined}
+    <link rel="canonical" href={resolvedCanonical} />
+  {/if}
+  {#if feed !== undefined}
+    <link
+      rel="alternate"
+      type={feed.type ?? 'application/feed+json'}
+      href={resolveHref(feed.path)}
+      title={feed.title ?? 'Latest changes'}
+    />
+  {/if}
+  <meta name="robots" content={robotsContent} />
+
+  <meta property="og:title" content={resolvedTitle} />
+  {#if resolvedCanonical !== undefined}
+    <meta property="og:url" content={resolvedCanonical} />
+  {/if}
+  {#if siteName !== undefined && siteName !== ''}
+    <meta property="og:site_name" content={siteName} />
+  {/if}
+  <meta property="og:type" content={resolvedOgType} />
+  {#if resolvedOgLocale !== undefined}
+    <meta property="og:locale" content={resolvedOgLocale} />
+  {/if}
+  {#if resolvedDescription !== undefined}
+    <meta property="og:description" content={resolvedDescription} />
+  {/if}
+
+  <meta name="twitter:card" content={twitterCard} />
+  {#if twitterSite !== undefined}
+    <meta name="twitter:site" content={twitterSite} />
+  {/if}
+  {#if twitterCreator !== undefined}
+    <meta name="twitter:creator" content={twitterCreator} />
+  {/if}
+  <meta name="twitter:title" content={resolvedTitle} />
+  {#if resolvedDescription !== undefined}
+    <meta name="twitter:description" content={resolvedDescription} />
+  {/if}
+
+  {#if resolvedImage !== undefined}
+    <meta property="og:image" content={resolvedImage.url} />
+    <meta name="twitter:image" content={resolvedImage.url} />
+    {#if resolvedImage.alt !== undefined && resolvedImage.alt !== ''}
+      <meta property="og:image:alt" content={resolvedImage.alt} />
+      <meta name="twitter:image:alt" content={resolvedImage.alt} />
+    {/if}
+    {#if resolvedImage.width !== undefined}
+      <meta property="og:image:width" content={String(resolvedImage.width)} />
+    {/if}
+    {#if resolvedImage.height !== undefined}
+      <meta property="og:image:height" content={String(resolvedImage.height)} />
+    {/if}
+    {#if resolvedImage.type !== undefined}
+      <meta property="og:image:type" content={resolvedImage.type} />
+    {/if}
+  {/if}
+
+  {#if resolvedOgType === 'article'}
+    {@render articleMeta()}
+  {/if}
+
+  {#each resolvedAlternates as alternate}
+    <link rel="alternate" href={alternate.href} hreflang={alternate.lang} />
+  {/each}
+  {#if prevUrl !== undefined}
+    <link rel="prev" href={prevUrl} />
+  {/if}
+  {#if nextUrl !== undefined}
+    <link rel="next" href={nextUrl} />
+  {/if}
+</svelte:head>

package/dist/seo/Head.svelte.d.ts

@@ -0,0 +1,86 @@
+import { type OgImageCard } from './og-image.ts';
+import type { AlternateLink, FeedLink, HeadImage, OpenGraphType, Robots, SchemaPageType, TwitterCard } from './types.ts';
+interface Props {
+    /** The page title. Blank renders `siteName` alone. */
+    title: string;
+    /** Appended to every title as `"<title><titleSeparator><siteName>"`, and emitted as `og:site_name`. */
+    siteName?: string | undefined;
+    /**
+     * Between the title and `siteName`.
+     * @defaultValue `' | '`
+     */
+    titleSeparator?: string | undefined;
+    /** Meta and Open Graph description. */
+    description?: string | null | undefined;
+    /** Meta keywords. */
+    keywords?: readonly string[] | undefined;
+    /** The Schema.org page type — only used to derive `og:type`. */
+    type?: SchemaPageType | undefined;
+    /** An explicit `og:type`; wins over the one derived from `type`. */
+    openGraphType?: OpenGraphType | undefined;
+    /** An explicit canonical URL. Wins over `pathname`. */
+    canonical?: string | undefined;
+    /** The current path, resolved through `canonicalHref` into the canonical URL. */
+    pathname?: string | undefined;
+    /**
+     * Resolves an app-relative path to an absolute URL on the production origin.
+     * @defaultValue the components context’s `href`
+     */
+    canonicalHref?: ((path: string) => string) | undefined;
+    /** Explicit `hreflang` alternates. Wins over `locales`. */
+    alternates?: readonly AlternateLink[] | undefined;
+    /**
+     * The site's locales. Each, plus `x-default`, becomes an `hreflang`
+     * alternate pointing at the canonical URL — the right signal for a site
+     * whose UI chrome is localised but whose URLs are not. A site with
+     * per-locale URLs passes `alternates` instead.
+     */
+    locales?: readonly string[] | undefined;
+    /** `og:locale`, in Open Graph's `language_TERRITORY` form. */
+    ogLocale?: string | undefined;
+    /** An RSS, Atom or JSON Feed link. */
+    feed?: FeedLink | undefined;
+    /** The robots directive. */
+    robots?: Robots | undefined;
+    /** An explicit share image. Wins over `shareCard` and `defaultImage`. */
+    image?: HeadImage | undefined;
+    /** Build a per-page share card URL with {@link ogImageUrl}. */
+    shareCard?: OgImageCard | undefined;
+    /**
+     * Where the share-card renderer is mounted.
+     * @defaultValue `/og`
+     */
+    shareCardPath?: string | undefined;
+    /**
+     * The share card's alt text.
+     * @defaultValue `"<card title> — <siteName>"`, or the card title alone when `siteName` is unset or empty
+     */
+    shareCardAlt?: ((card: OgImageCard) => string) | undefined;
+    /** The share image when neither `image` nor `shareCard` gives one. */
+    defaultImage?: HeadImage | undefined;
+    /** `article:published_time`. */
+    published?: Date | undefined;
+    /** `article:modified_time`. */
+    modified?: Date | undefined;
+    /** `article:section`. Blank is treated as absent. */
+    section?: string | undefined;
+    /** `article:tag`, one per entry. */
+    tags?: readonly string[] | undefined;
+    /**
+     * The Twitter / X card type.
+     * @defaultValue `'summary_large_image'`
+     */
+    twitterCard?: TwitterCard | undefined;
+    /** The site’s Twitter / X handle. */
+    twitterSite?: string | undefined;
+    /** The author’s Twitter / X handle. */
+    twitterCreator?: string | undefined;
+    /** The previous page in a paginated series (`rel="prev"`). */
+    prevUrl?: string | undefined;
+    /** The next page in a paginated series (`rel="next"`). */
+    nextUrl?: string | undefined;
+}
+/** Per-page `<head>` metadata: title, description, canonical URL, `hreflang` alternates, Open Graph and Twitter / X tags, `article:*` and pagination links. */
+declare const Head: import("svelte").Component<Props, {}, "">;
+type Head = ReturnType<typeof Head>;
+export default Head;

package/dist/seo/JsonLd.svelte

@@ -0,0 +1,30 @@
+<!-- @component
+One Schema.org JSON-LD node as an XSS-safe `<script type="application/ld+json">` block in `<svelte:head>`.
+-->
+<script lang="ts">/**
+* Emits one Schema.org JSON-LD graph node as a
+* `<script type="application/ld+json">` block in `<svelte:head>`.
+*
+* The JSON goes through {@link serializeJsonLd}, which escapes `<`, `>`,
+* `&`, U+2028 and U+2029, so authored content can neither close the script
+* element nor open an HTML comment inside it and inject markup. `data` of
+* `null` / `undefined` renders nothing, so a builder that
+* may have nothing to emit (a degenerate breadcrumb trail) can be wired
+* without a call-site `{#if}`.
+*/
+import { serializeJsonLd } from "./json-ld.js";
+let { data } = $props();
+// The closing tag is split so neither the Svelte compiler nor an HTML
+// parser reading this file sees it as the end of the component's own
+// `<script>`.
+const open = "<script type=\"application/ld+json\">";
+const close = "<" + "/script>";
+const block = $derived(data === null || data === undefined ? undefined : open + serializeJsonLd(data) + close);
+</script>
+
+<svelte:head>
+  {#if block !== undefined}
+    <!-- Escaped by serializeJsonLd: `<`, `>` and `&` cannot appear unescaped. -->
+    {@html block}
+  {/if}
+</svelte:head>

package/dist/seo/JsonLd.svelte.d.ts

@@ -0,0 +1,20 @@
+/**
+   * Emits one Schema.org JSON-LD graph node as a
+   * `<script type="application/ld+json">` block in `<svelte:head>`.
+   *
+   * The JSON goes through {@link serializeJsonLd}, which escapes `<`, `>`,
+   * `&`, U+2028 and U+2029, so authored content can neither close the script
+   * element nor open an HTML comment inside it and inject markup. `data` of
+   * `null` / `undefined` renders nothing, so a builder that
+   * may have nothing to emit (a degenerate breadcrumb trail) can be wired
+   * without a call-site `{#if}`.
+   */
+import { type JsonLdObject } from './json-ld.ts';
+interface Props {
+    /** The node to serialise; nothing is emitted for `null` or `undefined`. */
+    data: JsonLdObject | null | undefined;
+}
+/** One Schema.org JSON-LD node as an XSS-safe `<script type="application/ld+json">` block in `<svelte:head>`. */
+declare const JsonLd: import("svelte").Component<Props, {}, "">;
+type JsonLd = ReturnType<typeof JsonLd>;
+export default JsonLd;

package/dist/seo/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@thomasfosterau/components/seo` — per-page `<head>` metadata and
+ * structured data. A separate entry point: it renders only into
+ * `<svelte:head>`, and a consumer that manages its own head never loads it.
+ *
+ * `<Head>` emits the title, canonical, `hreflang`, Open Graph and Twitter /
+ * X tags; `<JsonLd>` emits one XSS-safe JSON-LD block; `serializeJsonLd` is
+ * the escaping serialiser underneath it; `ogImageUrl` builds the
+ * content-addressed share-card URL `<Head>` emits, with the param names and
+ * caps a card renderer reads back.
+ *
+ * @module
+ */
+export { default as Head } from './Head.svelte';
+export { default as JsonLd } from './JsonLd.svelte';
+export { serializeJsonLd, type JsonLdObject } from './json-ld.ts';
+export { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH, OG_SUBTITLE_MAX_LENGTH, OG_SUBTITLE_PARAM, OG_TITLE_MAX_LENGTH, OG_TITLE_PARAM, OG_VERSION_PARAM, ogImageUrl, type OgImageCard, type OgImageUrlOptions, } from './og-image.ts';
+export type { AlternateLink, FeedLink, HeadImage, OpenGraphType, Robots, SchemaPageType, TwitterCard, } from './types.ts';

package/dist/seo/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@thomasfosterau/components/seo` — per-page `<head>` metadata and
+ * structured data. A separate entry point: it renders only into
+ * `<svelte:head>`, and a consumer that manages its own head never loads it.
+ *
+ * `<Head>` emits the title, canonical, `hreflang`, Open Graph and Twitter /
+ * X tags; `<JsonLd>` emits one XSS-safe JSON-LD block; `serializeJsonLd` is
+ * the escaping serialiser underneath it; `ogImageUrl` builds the
+ * content-addressed share-card URL `<Head>` emits, with the param names and
+ * caps a card renderer reads back.
+ *
+ * @module
+ */
+export { default as Head } from './Head.svelte';
+export { default as JsonLd } from './JsonLd.svelte';
+export { serializeJsonLd } from "./json-ld.js";
+export { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH, OG_SUBTITLE_MAX_LENGTH, OG_SUBTITLE_PARAM, OG_TITLE_MAX_LENGTH, OG_TITLE_PARAM, OG_VERSION_PARAM, ogImageUrl, } from "./og-image.js";

package/dist/seo/json-ld.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Serialising Schema.org JSON-LD for a `<script type="application/ld+json">`
+ * block.
+ *
+ * `JSON.stringify` already escapes `"` inside strings. What it leaves is the
+ * HTML parser: an authored title containing `</script>` would close the
+ * embedding script element and inject whatever follows. `<`, `>` and `&` are
+ * therefore replaced with their `\u` escapes — JSON parsers read them
+ * identically, so the structured-data consumer sees the original text — and so
+ * are U+2028 / U+2029, which are legal in JSON strings but line terminators in
+ * JavaScript (OWASP / Google's JSON-in-HTML guidance).
+ *
+ * @module
+ */
+/**
+ * A JSON-LD graph node with its top-level `@context`.
+ *
+ * Deliberately loose: the library does not take `schema-dts` (or any
+ * vocabulary) as a dependency. `WithContext<Thing>` from `schema-dts` (a type
+ * alias, so it satisfies the index signature) is assignable to it, so an app
+ * that type-checks its builders against the real vocabulary can hand the
+ * result straight to {@link serializeJsonLd} or `<JsonLd>`.
+ */
+export type JsonLdObject = {
+    readonly '@context': unknown;
+    readonly [property: string]: unknown;
+};
+/**
+ * Serialise a JSON-LD object to a string safe to embed in a
+ * `<script type="application/ld+json">` block. The output is valid JSON that
+ * round-trips through `JSON.parse` to the input.
+ */
+export declare function serializeJsonLd(data: JsonLdObject): string;

package/dist/seo/json-ld.js

@@ -0,0 +1,29 @@
+/**
+ * Serialising Schema.org JSON-LD for a `<script type="application/ld+json">`
+ * block.
+ *
+ * `JSON.stringify` already escapes `"` inside strings. What it leaves is the
+ * HTML parser: an authored title containing `</script>` would close the
+ * embedding script element and inject whatever follows. `<`, `>` and `&` are
+ * therefore replaced with their `\u` escapes — JSON parsers read them
+ * identically, so the structured-data consumer sees the original text — and so
+ * are U+2028 / U+2029, which are legal in JSON strings but line terminators in
+ * JavaScript (OWASP / Google's JSON-in-HTML guidance).
+ *
+ * @module
+ */
+const LINE_SEPARATOR = new RegExp(String.fromCharCode(0x2028), 'g');
+const PARAGRAPH_SEPARATOR = new RegExp(String.fromCharCode(0x2029), 'g');
+/**
+ * Serialise a JSON-LD object to a string safe to embed in a
+ * `<script type="application/ld+json">` block. The output is valid JSON that
+ * round-trips through `JSON.parse` to the input.
+ */
+export function serializeJsonLd(data) {
+    return JSON.stringify(data)
+        .replace(/</g, '\\u003C')
+        .replace(/>/g, '\\u003E')
+        .replace(/&/g, '\\u0026')
+        .replace(LINE_SEPARATOR, '\\u2028')
+        .replace(PARAGRAPH_SEPARATOR, '\\u2029');
+}

package/dist/seo/og-image.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The content-addressed Open Graph share-image URL builder.
+ *
+ * Shared by `<Head>` (which emits the URL as `og:image`) and whatever renders
+ * the card (an app route or Worker reading the same query params), so the
+ * producer and the consumer of the URL can never disagree on the param names
+ * or the length caps — import the constants below on both sides.
+ *
+ * The URL is **content-addressed**: the title and description ride in the
+ * query, and a `v` token derived from the content's last-modified instant
+ * changes the whole URL whenever the content changes. A new URL is how the
+ * image cache-busts — link-preview scrapers (Facebook, LinkedIn, federated
+ * servers) cache aggressively and only re-fetch a URL they have not seen, so
+ * the version token is load-bearing, not cosmetic.
+ *
+ * @module
+ */
+/** Query param carrying the card title. */
+export declare const OG_TITLE_PARAM = "t";
+/** Query param carrying the card's second line (the page description). */
+export declare const OG_SUBTITLE_PARAM = "d";
+/** Query param carrying the cache-busting version token. */
+export declare const OG_VERSION_PARAM = "v";
+/**
+ * Length caps on the title / description carried in the URL. A renderer
+ * should re-apply them defensively; here they keep the emitted URL short.
+ */
+export declare const OG_TITLE_MAX_LENGTH = 120;
+/** Longest description, in characters, carried in a share-card URL; see `OG_TITLE_MAX_LENGTH`. */
+export declare const OG_SUBTITLE_MAX_LENGTH = 200;
+/** The rendered card's size — the 1.91:1 Open Graph standard. */
+export declare const OG_IMAGE_WIDTH = 1200;
+/** Share-card height in pixels; see `OG_IMAGE_WIDTH`. */
+export declare const OG_IMAGE_HEIGHT = 630;
+/** What a per-page share card is built from. */
+export interface OgImageCard {
+    /** The page title — the card headline. A blank title builds no URL. */
+    readonly title: string;
+    /** Optional second line (the page description). */
+    readonly description?: string | null | undefined;
+    /**
+     * A stable, opaque identity for the page (a content UUID, a slug), used only
+     * to build the readable `<slug>.png` path segment. Never rendered.
+     */
+    readonly id: string;
+    /**
+     * The content's last-modified instant, or anything that changes when the
+     * card should. Drives the version token; absent or unparseable, the URL is
+     * keyed by title + description alone.
+     */
+    readonly updatedAt?: Date | string | number | null | undefined;
+}
+/** How `ogImageUrl` turns a card into an absolute URL: the href resolver and the renderer's mount path. */
+export interface OgImageUrlOptions {
+    /**
+     * Resolves the card's path to the href emitted — the production origin, so
+     * the URL is absolute (`og:image` must be). `<Head>` passes its
+     * `canonicalHref`, which defaults to the components context's `href`.
+     * Defaults to the identity.
+     */
+    readonly href?: ((path: string) => string) | undefined;
+    /** The path the card renderer is mounted at. Default `/og`. */
+    readonly basePath?: string | undefined;
+}
+/**
+ * Build the `og:image` URL for a page's share card: `<basePath>/<slug>.png`
+ * resolved through `href`, with the title, description and version token in
+ * the query. Returns `undefined` for a blank title, so the caller falls back
+ * to its default share image.
+ */
+export declare function ogImageUrl(card: OgImageCard, options?: OgImageUrlOptions): string | undefined;