@vouchington/utils 0.7.2 → 0.7.4

package/README.md

@@ -18,11 +18,32 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
 
 ## Subpaths
 
+- `ai-moderation`: moderation input building, flagged-category and prompt-injection checks that
+  return violations; the caller makes the provider call.
+- `bedrock-embeddings` and `bedrock-embedding-batches`: Nova `InvokeModel` input builders, response
+  parsing and dense-vector validation, and batch JSONL record and result codecs with opaque record
+  ids; the caller owns the AWS client.
 - `cache-tags`: canonical printable-ASCII wire encoding, one-segment URL decoding, validation,
   and escape-boundary truncation. Applications own family names, route recognition, and purge policy.
   Single-tag validation rejects spaces and comma separators; raw commas are percent-encoded.
 - `schema-growth`: `buildUnboundedUnpartitionedTables()` and `classifyTableGrowth()` map tables to
   caller-supplied growth reasons. Applications own every table name and reason.
+- `web-push`: push-subscription JSON validation with an injected endpoint policy, base64url and
+  VAPID public-key decoding, and bounded payload build/parse helpers. No sending or storage.
+- `web-push-vapid` (Node): VAPID key generation/matching and ES256 JWT/`Authorization` builders.
+  Applications own key storage, subject, and delivery.
+- `web-push-binding` (browser): service-worker binding-state guards, one MessageChannel
+  request/acknowledge round trip with an injected message type and acceptance check, and a named
+  Web Lock wrapper. Request actions, expected state transitions, and the bind/clear/reconcile
+  sequence stay in the application.
+- `json-ld`: schema.org JSON-LD builders (organization, website, navigation, collection, thing,
+  comparison, item list, breadcrumb, profile) and script-safe serialization. Callers inject the
+  absolute-URL resolver and site name; product schemas such as posts stay in the application.
+- `seo-metadata`: framework-agnostic page, root, and noindex metadata objects (structurally
+  compatible with Next.js `Metadata`), excerpts, and markdown-alternate paths. Callers inject site
+  config, image URLs, locale mapping, and alternate prefixes.
+- `speculation-rules`: prefetch speculation-rules builder and preconnect-origin parsing with
+  caller-supplied exclusions.
 - `sentry-envelope`: bounded UTF-8 envelope record scanning and safe item-type diagnostics.
   Callers choose the byte and type-list limits; DSN, tunnel, request, and logging policy stay local.
 - `scopes`: caller-owned scope catalog validation, prerequisite expansion, audience and surface

package/dist/ai-moderation.d.mts

@@ -0,0 +1,34 @@
+/** The text or image parts a moderation endpoint accepts. */
+export type ModerationInputPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+};
+/** The fields of a moderation result this module reads. */
+export type ModerationResultLike = {
+    flagged: boolean;
+    categories: Record<string, boolean>;
+};
+export type MessageSafetyViolation = {
+    code: 'PROMPT_INJECTION';
+} | {
+    code: 'MODERATION_VIOLATION';
+    categories: string[];
+};
+/** Text first, then images, in the order given. */
+export declare function buildModerationInput(texts: readonly string[], imageUrls?: readonly string[]): ModerationInputPart[];
+/** Names of the categories a result flagged. */
+export declare function getFlaggedCategories(result: ModerationResultLike): string[];
+/**
+ * A violation naming every category flagged by any result, else null. Results line up with the
+ * request's inputs, so a later flagged input is never masked by a clean earlier one.
+ */
+export declare function checkModerationResults(results: readonly ModerationResultLike[]): MessageSafetyViolation | null;
+/** Common instruction-override and chat-template markers. Callers may pass their own list. */
+export declare const DEFAULT_PROMPT_INJECTION_PATTERNS: readonly RegExp[];
+/** A `PROMPT_INJECTION` violation when any pattern matches the message, else null. */
+export declare function checkPromptInjection(message: string, patterns?: readonly RegExp[]): MessageSafetyViolation | null;

package/dist/ai-moderation.mjs

@@ -0,0 +1,54 @@
+/** Text first, then images, in the order given. */
+export function buildModerationInput(texts, imageUrls = []) {
+    return [
+        ...texts.map((text) => ({ type: 'text', text })),
+        ...imageUrls.map((url) => ({ type: 'image_url', image_url: { url } })),
+    ];
+}
+/** Names of the categories a result flagged. */
+export function getFlaggedCategories(result) {
+    return Object.entries(result.categories).flatMap(([category, flagged]) => flagged ? [category] : []);
+}
+/**
+ * A violation naming every category flagged by any result, else null. Results line up with the
+ * request's inputs, so a later flagged input is never masked by a clean earlier one.
+ */
+export function checkModerationResults(results) {
+    const flagged = results.filter((result) => result.flagged);
+    if (flagged.length === 0)
+        return null;
+    const categories = [...new Set(flagged.flatMap(getFlaggedCategories))];
+    return { code: 'MODERATION_VIOLATION', categories };
+}
+/** Common instruction-override and chat-template markers. Callers may pass their own list. */
+export const DEFAULT_PROMPT_INJECTION_PATTERNS = [
+    /ignore\s+(all\s+)?(previous|prior|earlier)\s+(instructions?|prompts?|rules?)/i,
+    /disregard\s+(all\s+)?(previous|prior|earlier)\s+(instructions?|prompts?|rules?)/i,
+    /forget\s+(all\s+)?(previous|prior|earlier)\s+(instructions?|prompts?|rules?)/i,
+    // A chat-template style role prefix at the start of a line, not "operating system: Linux".
+    /(?:^|\n)\s*system\s*:/i,
+    /<\|im_start\|>/i,
+    /<\|im_end\|>/i,
+    /\[INST\]/i,
+    /\[\/INST\]/i,
+    /<system>/i,
+    /<\/system>/i,
+    // Require "now" to avoid benign phrases like "you are a great help"
+    /you\s+are\s+now\s+(a|an)\s+/i,
+    // A heading-style "new instructions:" at the start of a line, not "new instructions for the cake".
+    /(?:^|\n)\s*new\s+instructions?\s*:/i,
+    /override\s+(previous|prior|all)\s+(instructions?|rules?)/i,
+];
+/** A `PROMPT_INJECTION` violation when any pattern matches the message, else null. */
+export function checkPromptInjection(message, patterns = DEFAULT_PROMPT_INJECTION_PATTERNS) {
+    const matched = patterns.some((pattern) => {
+        // Global and sticky patterns are stateful; test from the start, then leave the caller's regex
+        // as it was found.
+        const previous = pattern.lastIndex;
+        pattern.lastIndex = 0;
+        const result = pattern.test(message);
+        pattern.lastIndex = previous;
+        return result;
+    });
+    return matched ? { code: 'PROMPT_INJECTION' } : null;
+}

package/dist/bedrock-embedding-batches.d.mts

@@ -0,0 +1,53 @@
+import { type EmbeddingOptions } from './bedrock-embeddings.mts';
+/**
+ * Nova accepts inline media up to 25 MB after Base64 encoding; 18,000,000 raw bytes encode to
+ * 24,000,000, leaving room for framing; callers that enforce a smaller
+ * decoded bound (e.g. after converting images) pass it as `maxImageBytes`.
+ */
+export declare const DEFAULT_MAX_IMAGE_EMBEDDING_BYTES = 18000000;
+export type BatchSizeOptions = EmbeddingOptions & {
+    /** Decoded image bytes bound used to budget the worst-case record. */
+    maxImageBytes?: number;
+    /**
+     * Longest `recordId` in UTF-16 code units (default 128). Budgeted at JSON's worst case of six
+     * bytes per unit, since escapes can expand the encoded line.
+     */
+    maxRecordIdLength?: number;
+};
+/** One JSONL line of a batch input file. `recordId` is opaque and comes back on the result line. */
+export declare function createEmbeddingRecordLine(recordId: string, modelInput: Record<string, unknown>): string;
+export declare function createEmbeddingTextRecordLine(record: {
+    recordId: string;
+    content: string;
+}, options?: EmbeddingOptions): string;
+export declare function createEmbeddingImageRecordLine(record: {
+    recordId: string;
+    format: 'jpeg' | 'png' | 'webp' | 'gif';
+    bytes: string;
+}, options?: EmbeddingOptions): string;
+/** Lower bound on a batch file for `records` images: worst-case payload plus actual framing. */
+export declare function minimumImageBatchSizeMB(records: number, options?: BatchSizeOptions): number;
+/** Same for text; JSON control-character escapes cost up to six bytes per UTF-16 code unit. */
+export declare function minimumTextBatchSizeMB(records: number, options?: BatchSizeOptions): number;
+/** One line of a batch output file. */
+export type BatchResultLine = {
+    recordId: string;
+    error?: unknown;
+    modelOutput?: {
+        embedding?: number[];
+        embeddings?: Array<{
+            embedding: number[];
+        } | number[]>;
+        inputTokenCount?: number;
+    };
+};
+export type BatchEmbeddingResult = {
+    recordId: string;
+    embedding: number[];
+    inputTokenCount: number | null;
+};
+/**
+ * The vector of a result line, or null for errored lines and lines without one. Decoding the
+ * opaque `recordId` and validating the vector's dimension stay with the application.
+ */
+export declare function parseBatchResult(line: BatchResultLine): BatchEmbeddingResult | null;

package/dist/bedrock-embedding-batches.mjs

@@ -0,0 +1,51 @@
+import { buildEmbeddingModelInput, extractEmbedding, NOVA_EMBEDDING_DEFAULTS, } from './bedrock-embeddings.mjs';
+/**
+ * Nova accepts inline media up to 25 MB after Base64 encoding; 18,000,000 raw bytes encode to
+ * 24,000,000, leaving room for framing; callers that enforce a smaller
+ * decoded bound (e.g. after converting images) pass it as `maxImageBytes`.
+ */
+export const DEFAULT_MAX_IMAGE_EMBEDDING_BYTES = 18_000_000;
+const DEFAULT_MAX_RECORD_ID_LENGTH = 128;
+/** A control character JSON-escapes to six bytes (`\u0001`), the worst case per code unit. */
+const WORST_CASE_ID_UNIT = '\u0001';
+/** One JSONL line of a batch input file. `recordId` is opaque and comes back on the result line. */
+export function createEmbeddingRecordLine(recordId, modelInput) {
+    return JSON.stringify({ recordId, modelInput });
+}
+export function createEmbeddingTextRecordLine(record, options = {}) {
+    return createEmbeddingRecordLine(record.recordId, buildEmbeddingModelInput({ text: record.content }, options));
+}
+export function createEmbeddingImageRecordLine(record, options = {}) {
+    return createEmbeddingRecordLine(record.recordId, buildEmbeddingModelInput({ image: { format: record.format, bytes: record.bytes } }, options));
+}
+function framingBytes(line) {
+    return Buffer.byteLength(line) + 1;
+}
+/** Lower bound on a batch file for `records` images: worst-case payload plus actual framing. */
+export function minimumImageBatchSizeMB(records, options = {}) {
+    const recordId = WORST_CASE_ID_UNIT.repeat(options.maxRecordIdLength ?? DEFAULT_MAX_RECORD_ID_LENGTH);
+    const framing = framingBytes(createEmbeddingImageRecordLine({ recordId, format: 'jpeg', bytes: '' }, options));
+    const maxBytes = options.maxImageBytes ?? DEFAULT_MAX_IMAGE_EMBEDDING_BYTES;
+    return (records * (Math.ceil(maxBytes / 3) * 4 + framing)) / 1024 / 1024;
+}
+/** Same for text; JSON control-character escapes cost up to six bytes per UTF-16 code unit. */
+export function minimumTextBatchSizeMB(records, options = {}) {
+    const recordId = WORST_CASE_ID_UNIT.repeat(options.maxRecordIdLength ?? DEFAULT_MAX_RECORD_ID_LENGTH);
+    const maxTextLength = options.maxTextLength ?? NOVA_EMBEDDING_DEFAULTS.maxTextLength;
+    const framing = framingBytes(createEmbeddingTextRecordLine({ recordId, content: '' }, options));
+    return (records * (maxTextLength * 6 + framing)) / 1024 / 1024;
+}
+/**
+ * The vector of a result line, or null for errored lines and lines without one. Decoding the
+ * opaque `recordId` and validating the vector's dimension stay with the application.
+ */
+export function parseBatchResult(line) {
+    const embedding = line.error ? undefined : extractEmbedding(line.modelOutput);
+    if (!embedding)
+        return null;
+    return {
+        recordId: line.recordId,
+        embedding,
+        inputTokenCount: line.modelOutput?.inputTokenCount ?? null,
+    };
+}

package/dist/bedrock-embeddings.d.mts

@@ -0,0 +1,62 @@
+/** Defaults for Amazon Nova multimodal embeddings; every field can be overridden. */
+export declare const NOVA_EMBEDDING_DEFAULTS: {
+    readonly modelId: 'amazon.nova-2-multimodal-embeddings-v1:0';
+    readonly dimension: 1024;
+    /** Nova's inline `text.value` cap (UTF-16 code units). */
+    readonly maxTextLength: 8192;
+    /** Nova documents no input token count; this approximate estimate is for analytics only. */
+    readonly charactersPerToken: 4;
+};
+export type EmbeddingOptions = {
+    modelId?: string;
+    dimension?: number;
+    maxTextLength?: number;
+    /** `embeddingPurpose`: `GENERIC_INDEX` (default) for stored content, a retrieval purpose for queries. */
+    purpose?: string;
+    /** Nova image `detailLevel` (e.g. `STANDARD_IMAGE` or `DOCUMENT_IMAGE`); omitted by default. */
+    imageDetailLevel?: string;
+};
+/** The `InvokeModel` input; the app wraps it in its own command and client. */
+export type InvokeEmbeddingInput = {
+    modelId: string;
+    contentType: 'application/json';
+    accept: 'application/json';
+    body: string;
+};
+type EmbeddingEntry = {
+    embedding: number[];
+} | number[];
+type EmbeddingResponseBody = {
+    embedding?: number[];
+    embeddings?: EmbeddingEntry[];
+};
+export declare class InvalidEmbeddingError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Slices to the limit. When the cut falls inside a word, drops a trailing high surrogate and backs
+ * up to the last whitespace so the word is not cut; a cut that already ends a word is kept. Falls
+ * back to the hard slice when the head has no whitespace.
+ */
+export declare function truncateEmbeddingText(text: string, maxLength?: number): string;
+export declare function estimateEmbeddingTokens(text: string, charactersPerToken?: number): number;
+/** The model input for one text or image, shared by the single and batch record formats. */
+export declare function buildEmbeddingModelInput(content: {
+    text: string;
+} | {
+    image: {
+        format: 'jpeg' | 'png' | 'webp' | 'gif';
+        bytes: string;
+    };
+}, options?: EmbeddingOptions): Record<string, unknown>;
+export declare function buildInvokeEmbeddingInput(text: string, options?: EmbeddingOptions): InvokeEmbeddingInput;
+/** The first embedding of a response or batch `modelOutput`, in either documented shape. */
+export declare function extractEmbedding(body: EmbeddingResponseBody | undefined): number[] | undefined;
+/**
+ * Parses an `InvokeModel` response body into a dense vector of `dimension` finite numbers; throws
+ * `InvalidEmbeddingError` when the body is empty or holds no valid vector.
+ */
+export declare function parseEmbeddingResponseBody(body: Uint8Array | undefined, dimension?: number): number[];
+/** Narrows to a finite-number vector of exactly `dimension` entries or throws. */
+export declare function requireDenseEmbedding(value: unknown, dimension?: number): number[];
+export {};

package/dist/bedrock-embeddings.mjs

@@ -0,0 +1,106 @@
+/** Defaults for Amazon Nova multimodal embeddings; every field can be overridden. */
+export const NOVA_EMBEDDING_DEFAULTS = {
+    modelId: 'amazon.nova-2-multimodal-embeddings-v1:0',
+    dimension: 1024,
+    /** Nova's inline `text.value` cap (UTF-16 code units). */
+    maxTextLength: 8_192,
+    /** Nova documents no input token count; this approximate estimate is for analytics only. */
+    charactersPerToken: 4,
+};
+export class InvalidEmbeddingError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'InvalidEmbeddingError';
+    }
+}
+/**
+ * Slices to the limit. When the cut falls inside a word, drops a trailing high surrogate and backs
+ * up to the last whitespace so the word is not cut; a cut that already ends a word is kept. Falls
+ * back to the hard slice when the head has no whitespace.
+ */
+export function truncateEmbeddingText(text, maxLength = NOVA_EMBEDDING_DEFAULTS.maxTextLength) {
+    if (text.length <= maxLength)
+        return text;
+    let sliced = text.slice(0, maxLength);
+    if (/\s/.test(text.charAt(maxLength)))
+        return sliced;
+    const last = sliced.charCodeAt(sliced.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        sliced = sliced.slice(0, -1);
+    const lastWhitespace = sliced.search(/\s\S*$/);
+    return lastWhitespace > 0 ? sliced.slice(0, lastWhitespace) : sliced;
+}
+export function estimateEmbeddingTokens(text, charactersPerToken = NOVA_EMBEDDING_DEFAULTS.charactersPerToken) {
+    return Math.ceil(text.length / charactersPerToken);
+}
+/** The model input for one text or image, shared by the single and batch record formats. */
+export function buildEmbeddingModelInput(content, options = {}) {
+    const dimension = options.dimension ?? NOVA_EMBEDDING_DEFAULTS.dimension;
+    const common = {
+        embeddingPurpose: options.purpose ?? 'GENERIC_INDEX',
+        embeddingDimension: dimension,
+    };
+    return {
+        taskType: 'SINGLE_EMBEDDING',
+        singleEmbeddingParams: 'text' in content
+            ? {
+                ...common,
+                text: {
+                    truncationMode: 'END',
+                    value: truncateEmbeddingText(content.text, options.maxTextLength),
+                },
+            }
+            : {
+                ...common,
+                image: {
+                    format: content.image.format,
+                    source: { bytes: content.image.bytes },
+                    ...(options.imageDetailLevel ? { detailLevel: options.imageDetailLevel } : {}),
+                },
+            },
+    };
+}
+export function buildInvokeEmbeddingInput(text, options = {}) {
+    return {
+        modelId: options.modelId ?? NOVA_EMBEDDING_DEFAULTS.modelId,
+        contentType: 'application/json',
+        accept: 'application/json',
+        body: JSON.stringify(buildEmbeddingModelInput({ text }, options)),
+    };
+}
+/** The first embedding of a response or batch `modelOutput`, in either documented shape. */
+export function extractEmbedding(body) {
+    if (body?.embedding)
+        return body.embedding;
+    const first = body?.embeddings?.[0];
+    return Array.isArray(first) ? first : first?.embedding;
+}
+/**
+ * Parses an `InvokeModel` response body into a dense vector of `dimension` finite numbers; throws
+ * `InvalidEmbeddingError` when the body is empty or holds no valid vector.
+ */
+export function parseEmbeddingResponseBody(body, dimension = NOVA_EMBEDDING_DEFAULTS.dimension) {
+    if (!body)
+        throw new InvalidEmbeddingError('Bedrock embedding response body is empty');
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(body));
+    }
+    catch (err) {
+        throw new InvalidEmbeddingError('Bedrock embedding response is not valid JSON', { cause: err });
+    }
+    const embedding = extractEmbedding(parsed);
+    if (!embedding) {
+        throw new InvalidEmbeddingError('Bedrock embedding response did not include an embedding');
+    }
+    return requireDenseEmbedding(embedding, dimension);
+}
+/** Narrows to a finite-number vector of exactly `dimension` entries or throws. */
+export function requireDenseEmbedding(value, dimension = NOVA_EMBEDDING_DEFAULTS.dimension) {
+    if (!Array.isArray(value) ||
+        value.length !== dimension ||
+        value.some((element) => typeof element !== 'number' || !Number.isFinite(element))) {
+        throw new InvalidEmbeddingError('Bedrock embedding is not a dense vector');
+    }
+    return value;
+}

package/dist/json-ld-profile.d.mts

@@ -0,0 +1,12 @@
+import type { JsonLd, JsonLdContext } from './json-ld.mts';
+export declare function createProfilePageJsonLd(ctx: JsonLdContext, input: {
+    username: string;
+    displayName?: string | null;
+    path: string;
+    identifier: string;
+    imagePath?: string | null;
+    dateCreated?: string;
+    sameAs?: string[];
+}): JsonLd;
+/** Returns the first mapped schema.org type for the slugs, else `fallback`. */
+export declare function resolveSchemaOrgType(slugs: readonly string[], mapping: Readonly<Record<string, string>>, fallback?: string): string;

package/dist/json-ld-profile.mjs

@@ -0,0 +1,31 @@
+export function createProfilePageJsonLd(ctx, input) {
+    const mainEntity = {
+        '@type': 'Person',
+        name: input.displayName || input.username,
+        identifier: input.identifier,
+        url: ctx.absoluteUrl(input.path),
+    };
+    if (input.displayName && input.displayName !== input.username) {
+        mainEntity.alternateName = input.username;
+    }
+    if (input.imagePath)
+        mainEntity.image = ctx.absoluteUrl(input.imagePath);
+    if (input.sameAs?.length)
+        mainEntity.sameAs = input.sameAs;
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'ProfilePage',
+        url: ctx.absoluteUrl(input.path),
+        ...(input.dateCreated ? { dateCreated: input.dateCreated } : {}),
+        mainEntity,
+    };
+}
+/** Returns the first mapped schema.org type for the slugs, else `fallback`. */
+export function resolveSchemaOrgType(slugs, mapping, fallback = 'Thing') {
+    for (const slug of slugs) {
+        const type = Object.hasOwn(mapping, slug) ? mapping[slug] : undefined;
+        if (type)
+            return type;
+    }
+    return fallback;
+}

package/dist/json-ld.d.mts

@@ -0,0 +1,57 @@
+export type JsonLd = Record<string, unknown>;
+export interface JsonLdContext {
+    /** Resolves a site path to an absolute URL; injected so origin policy stays in the application. */
+    absoluteUrl: (path: string) => string;
+}
+export interface JsonLdSite extends JsonLdContext {
+    siteName: string;
+}
+export interface ItemListInput {
+    name: string;
+    url: string;
+    description?: string;
+    image?: string;
+}
+export declare const SCHEMA_ORG_CONTEXT = "https://schema.org";
+/** Escapes characters that could terminate an inline `<script>` or break JS parsing. */
+export declare function escapeInlineScriptJson(json: string): string;
+export declare function serializeJsonLd(data: JsonLd): string;
+export declare function createOrganizationJsonLd(site: JsonLdSite, logoPath: string): JsonLd;
+export declare function createWebSiteJsonLd(site: JsonLdSite): JsonLd;
+export declare function createSiteNavigationJsonLd(ctx: JsonLdContext, items: {
+    name: string;
+    path: string;
+}[], name?: string): JsonLd;
+export declare function createCollectionPageJsonLd(site: JsonLdSite, input: {
+    title: string;
+    description: string;
+    path: string;
+}): JsonLd;
+export declare function createThingJsonLd(ctx: JsonLdContext, input: {
+    name: string;
+    description?: string;
+    path: string;
+    schemaOrgType?: string;
+}): JsonLd;
+export declare function createWebPageJsonLd(site: JsonLdSite, input: {
+    name: string;
+    description?: string;
+    path: string;
+}): JsonLd;
+interface ComparedThing {
+    name: string;
+    path: string;
+    schemaOrgType?: string;
+}
+export declare function createComparisonPageJsonLd(site: JsonLdSite, input: {
+    a: ComparedThing;
+    b: ComparedThing;
+    path: string;
+}): JsonLd;
+export declare function createItemListJsonLd(ctx: JsonLdContext, items: ItemListInput[], listName: string): JsonLd;
+/** Breadcrumb names are resolved by the caller (translation stays in the application). */
+export declare function createBreadcrumbJsonLd(ctx: JsonLdContext, items: {
+    name: string;
+    path: string;
+}[]): JsonLd;
+export { createProfilePageJsonLd, resolveSchemaOrgType } from './json-ld-profile.mts';

package/dist/json-ld.mjs

@@ -0,0 +1,117 @@
+export const SCHEMA_ORG_CONTEXT = 'https://schema.org';
+const CONTEXT = SCHEMA_ORG_CONTEXT;
+/** Escapes characters that could terminate an inline `<script>` or break JS parsing. */
+export function escapeInlineScriptJson(json) {
+    return json
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(new RegExp('[\\u2028\\u2029]', 'g'), (char) => `\\u${char.charCodeAt(0).toString(16)}`);
+}
+export function serializeJsonLd(data) {
+    return escapeInlineScriptJson(JSON.stringify(data));
+}
+function webSiteRef(site) {
+    return { '@type': 'WebSite', name: site.siteName, url: site.absoluteUrl('/') };
+}
+function optional(key, value) {
+    return value ? { [key]: value } : {};
+}
+export function createOrganizationJsonLd(site, logoPath) {
+    return {
+        '@context': CONTEXT,
+        '@type': 'Organization',
+        name: site.siteName,
+        url: site.absoluteUrl('/'),
+        logo: site.absoluteUrl(logoPath),
+    };
+}
+export function createWebSiteJsonLd(site) {
+    return { '@context': CONTEXT, ...webSiteRef(site) };
+}
+export function createSiteNavigationJsonLd(ctx, items, name = 'Primary navigation') {
+    return {
+        '@context': CONTEXT,
+        '@type': 'SiteNavigationElement',
+        name,
+        hasPart: items.map((item) => ({
+            '@type': 'WebPage',
+            name: item.name,
+            url: ctx.absoluteUrl(item.path),
+        })),
+    };
+}
+export function createCollectionPageJsonLd(site, input) {
+    return {
+        '@context': CONTEXT,
+        '@type': 'CollectionPage',
+        name: input.title,
+        description: input.description,
+        url: site.absoluteUrl(input.path),
+        isPartOf: webSiteRef(site),
+    };
+}
+export function createThingJsonLd(ctx, input) {
+    return {
+        '@context': CONTEXT,
+        '@type': input.schemaOrgType ?? 'Thing',
+        name: input.name,
+        ...optional('description', input.description),
+        url: ctx.absoluteUrl(input.path),
+    };
+}
+export function createWebPageJsonLd(site, input) {
+    return {
+        '@context': CONTEXT,
+        '@type': 'WebPage',
+        name: input.name,
+        ...optional('description', input.description),
+        url: site.absoluteUrl(input.path),
+        isPartOf: webSiteRef(site),
+    };
+}
+export function createComparisonPageJsonLd(site, input) {
+    const about = (thing) => ({
+        '@type': thing.schemaOrgType ?? 'Thing',
+        name: thing.name,
+        url: site.absoluteUrl(thing.path),
+    });
+    return {
+        '@context': CONTEXT,
+        '@type': 'WebPage',
+        name: `${input.a.name} vs ${input.b.name}`,
+        url: site.absoluteUrl(input.path),
+        about: [about(input.a), about(input.b)],
+        isPartOf: webSiteRef(site),
+    };
+}
+export function createItemListJsonLd(ctx, items, listName) {
+    return {
+        '@context': CONTEXT,
+        '@type': 'ItemList',
+        name: listName,
+        numberOfItems: items.length,
+        itemListElement: items.map((item, index) => ({
+            '@type': 'ListItem',
+            position: index + 1,
+            name: item.name,
+            url: ctx.absoluteUrl(item.url),
+            ...optional('description', item.description),
+            ...(item.image ? { image: ctx.absoluteUrl(item.image) } : {}),
+        })),
+    };
+}
+/** Breadcrumb names are resolved by the caller (translation stays in the application). */
+export function createBreadcrumbJsonLd(ctx, items) {
+    return {
+        '@context': CONTEXT,
+        '@type': 'BreadcrumbList',
+        itemListElement: items.map((item, index) => ({
+            '@type': 'ListItem',
+            position: index + 1,
+            name: item.name,
+            item: ctx.absoluteUrl(item.path),
+        })),
+    };
+}
+export { createProfilePageJsonLd, resolveSchemaOrgType } from './json-ld-profile.mjs';

package/dist/seo-excerpt.d.mts

@@ -0,0 +1,2 @@
+/** Plain-text excerpt: strips HTML tags and light Markdown, decodes entities, truncates by code point. */
+export declare function createExcerpt(value: string, maxLength?: number): string;

package/dist/seo-excerpt.mjs

@@ -0,0 +1,33 @@
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+function decodeEntities(value) {
+    return value.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, body) => {
+        if (body[0] !== '#')
+            return NAMED_ENTITIES[body.toLowerCase()] ?? match;
+        const code = /^#x/i.test(body) ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+        return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
+    });
+}
+function stripMarkup(value) {
+    const withoutTags = value.replace(/<\/?[A-Za-z][^>]*>/g, ' ');
+    const withoutLinks = withoutTags.replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1');
+    const withoutSyntax = withoutLinks.replace(/^\s{0,3}(#{1,6}|>)\s+/gm, '').replace(/[*_`~]+/g, ' ');
+    return decodeEntities(withoutSyntax).replace(/\s+/g, ' ').trim();
+}
+/** Plain-text excerpt: strips HTML tags and light Markdown, decodes entities, truncates by code point. */
+export function createExcerpt(value, maxLength = 160) {
+    const plainText = stripMarkup(value);
+    const points = Array.from(plainText);
+    if (points.length <= maxLength)
+        return plainText;
+    return `${points
+        .slice(0, maxLength - 1)
+        .join('')
+        .trimEnd()}…`;
+}