@ubean/seo 0.1.13 → 0.2.0

package/dist/conventions.d.ts

@@ -0,0 +1,77 @@
+//#region src/conventions.d.ts
+/**
+ * 约定文件类型标识。每个标识映射到 srcDir 下的一个固定文件名和输出 URL。
+ */
+type SeoConventionKind = 'sitemap' | 'robots' | 'manifest' | 'opengraph-image' | 'icon' | 'apple-icon';
+interface SeoConventionDescriptor {
+  kind: SeoConventionKind;
+  /** srcDir 下的相对文件名(不含扩展名后缀,会尝试 .ts/.js/.mjs/.mts) */
+  fileName: string;
+  /** 注册的 GET 路由路径 */
+  routePath: string;
+  /** 默认 `Content-Type`(可被 handler 返回的 Response 覆盖) */
+  contentType: string;
+  /** 默认 `Cache-Control` */
+  cacheControl: string;
+}
+declare const SEO_CONVENTIONS: readonly SeoConventionDescriptor[];
+/**
+ * 注册约定文件所需的最小 app 接口。`UbeanApp` 满足此接口,
+ * 但为避免 `@ubean/seo` → `@ubean/app` 的硬依赖(后者已经依赖前者的兄弟包),
+ * 此处用结构类型解耦。
+ */
+interface SeoConventionApp {
+  get(path: string, ...handlers: Array<(c: SeoConventionContext) => unknown>): unknown;
+}
+interface SeoConventionContext {
+  req: {
+    method: string;
+    path: string;
+    url: string;
+  };
+}
+interface RegisterSeoConventionsOptions {
+  /**
+   * 项目 srcDir 绝对路径或相对 cwd 的路径。约定文件会在该目录根下查找。
+   */
+  srcDir: string;
+  /**
+   * 显式启用/禁用子集。未指定时启用全部约定。
+   */
+  enabled?: SeoConventionKind[];
+  /**
+   * 显式禁用子集(优先级高于 `enabled`)。
+   */
+  disabled?: SeoConventionKind[];
+  /**
+   * 文件扩展名候选(默认 `.ts/.js/.mjs/.mts/.cjs`)。第一个存在的扩展名胜出。
+   */
+  extensions?: string[];
+}
+interface LoadedConvention {
+  descriptor: SeoConventionDescriptor;
+  filePath: string;
+  handler: (c?: SeoConventionContext) => unknown;
+}
+/**
+ * 在 srcDir 下查找约定文件。返回已加载的 `{ descriptor, filePath, handler }` 列表;
+ * 不存在的文件被静默跳过。
+ */
+declare function discoverSeoConventions(options: RegisterSeoConventionsOptions): Promise<LoadedConvention[]>;
+/**
+ * 扫描 srcDir 下的 SEO 约定文件,为每个发现的文件注册 GET 路由。
+ *
+ * 调用方应在 `app.init()` *之前* 调用此函数,这样约定路由会和其它路由
+ * 一起在 `init()` 中被纳入。如果调用方在 `init()` 之后调用,需要确保
+ * app 实例支持动态添加路由(`UbeanApp` 支持)。
+ *
+ * @returns 已注册的约定 kind 列表(便于日志/调试)
+ */
+declare function registerSeoConventions(app: SeoConventionApp, options: RegisterSeoConventionsOptions): Promise<SeoConventionKind[]>;
+/**
+ * 列出 srcDir 下存在的约定文件 kind(不加载)。用于在不启动 app 的情况下
+ * 检测项目使用了哪些约定(例如 CLI 信息展示)。
+ */
+declare function listSeoConventions(options: Pick<RegisterSeoConventionsOptions, 'srcDir' | 'extensions'>): SeoConventionKind[];
+//#endregion
+export { RegisterSeoConventionsOptions, SEO_CONVENTIONS, SeoConventionApp, SeoConventionContext, SeoConventionDescriptor, SeoConventionKind, discoverSeoConventions, listSeoConventions, registerSeoConventions };

package/dist/conventions.js

@@ -0,0 +1,177 @@
+import { createManifestResponse, createRobotsResponse, createSitemapResponse } from "./index.js";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "pathe";
+//#region src/conventions.ts
+/**
+* P9-05 文件约定 SEO
+*
+* 在 `src/` 根目录扫描以下约定文件(对齐 Next.js `app/` 文件约定):
+*
+* | 文件                          | 输出路径                  | 默认导出形状                                                            |
+* | ----------------------------- | ------------------------- | ----------------------------------------------------------------------- |
+* | `src/sitemap.ts`              | `GET /sitemap.xml`        | `() => SitemapUrl[] \| Promise<SitemapUrl[]>`                           |
+* | `src/robots.ts`               | `GET /robots.txt`         | `() => RobotsOptions \| RobotsOptions[]`                                |
+* | `src/manifest.ts`             | `GET /manifest.webmanifest` | `() => WebAppManifest`                                                |
+* | `src/opengraph-image.ts`      | `GET /opengraph-image`    | `() => Response \| Promise<Response>` (通常是 PNG)                      |
+* | `src/icon.ts`                 | `GET /icon`               | `() => Response \| Promise<Response>`                                   |
+* | `src/apple-icon.ts`           | `GET /apple-icon`         | `() => Response \| Promise<Response>`                                   |
+*
+* 设计要点:
+* - 纯运行时实现(无 Vite 插件依赖):用 `fs.access` 检测文件存在,`import()` 加载。
+* - 不强依赖 `@ubean/app` —— 通过最小化的 `SeoConventionApp` 结构类型避免循环依赖。
+* - 调用方负责在 `defineServer({ onAppCreate })` 或 `app.init()` 前调用
+*   `registerSeoConventions(app, { srcDir })`。`@ubean/app` 的 `UbeanAppOptions.seoConventions`
+*   字段会自动调用此函数(参见 `@ubean/app` 的 `app.ts`)。
+* - 文件不存在时静默跳过(不报错),允许项目按需采用约定。
+* - 已注册的路由(用户在 `routes/` 显式定义)优先级不变 —— 约定文件在 `init()` 中
+*   于用户路由 *之后* 注册,因此 Hono 路由匹配时显式路由优先。
+*/
+const SEO_CONVENTIONS = [
+	{
+		kind: "sitemap",
+		fileName: "sitemap",
+		routePath: "/sitemap.xml",
+		contentType: "application/xml; charset=utf-8",
+		cacheControl: "public, max-age=3600"
+	},
+	{
+		kind: "robots",
+		fileName: "robots",
+		routePath: "/robots.txt",
+		contentType: "text/plain; charset=utf-8",
+		cacheControl: "public, max-age=3600"
+	},
+	{
+		kind: "manifest",
+		fileName: "manifest",
+		routePath: "/manifest.webmanifest",
+		contentType: "application/manifest+json; charset=utf-8",
+		cacheControl: "public, max-age=86400"
+	},
+	{
+		kind: "opengraph-image",
+		fileName: "opengraph-image",
+		routePath: "/opengraph-image",
+		contentType: "image/png",
+		cacheControl: "public, max-age=86400"
+	},
+	{
+		kind: "icon",
+		fileName: "icon",
+		routePath: "/icon",
+		contentType: "image/png",
+		cacheControl: "public, max-age=86400"
+	},
+	{
+		kind: "apple-icon",
+		fileName: "apple-icon",
+		routePath: "/apple-icon",
+		contentType: "image/png",
+		cacheControl: "public, max-age=86400"
+	}
+];
+const DEFAULT_EXTENSIONS = [
+	".ts",
+	".js",
+	".mjs",
+	".mts",
+	".cjs"
+];
+/**
+* 在 srcDir 下查找约定文件。返回已加载的 `{ descriptor, filePath, handler }` 列表;
+* 不存在的文件被静默跳过。
+*/
+async function discoverSeoConventions(options) {
+	const srcDir = isAbsolute(options.srcDir) ? options.srcDir : resolve(process.cwd(), options.srcDir);
+	const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+	const disabled = new Set(options.disabled ?? []);
+	const enabledSet = options.enabled ? new Set(options.enabled) : null;
+	const loaded = [];
+	for (const descriptor of SEO_CONVENTIONS) {
+		if (disabled.has(descriptor.kind)) continue;
+		if (enabledSet && !enabledSet.has(descriptor.kind)) continue;
+		let filePath = null;
+		for (const ext of extensions) {
+			const candidate = join(srcDir, `${descriptor.fileName}${ext}`);
+			if (existsSync(candidate)) {
+				filePath = candidate;
+				break;
+			}
+		}
+		if (!filePath) continue;
+		try {
+			const handler = (await import(
+				/* @vite-ignore */
+				filePath
+)).default;
+			if (typeof handler !== "function") continue;
+			loaded.push({
+				descriptor,
+				filePath,
+				handler
+			});
+		} catch {}
+	}
+	return loaded;
+}
+/**
+* 把单个约定文件的 default export 转换为 Hono GET handler。
+*
+* - `sitemap` / `robots` / `manifest`:调用 handler 拿到数据,用 `create*Response` 包装
+* - 其它(`opengraph-image` / `icon` / `apple-icon`):handler 直接返回 `Response`
+*/
+async function toResponse(descriptor, handler, c) {
+	const result = await handler(c);
+	if (descriptor.kind === "sitemap") return createSitemapResponse(result);
+	if (descriptor.kind === "robots") return createRobotsResponse(result);
+	if (descriptor.kind === "manifest") return createManifestResponse(result);
+	if (result instanceof Response) {
+		if (!result.headers.get("Cache-Control")) {
+			const cloned = result.clone();
+			cloned.headers.set("Cache-Control", descriptor.cacheControl);
+			return cloned;
+		}
+		return result;
+	}
+	return new Response(`SEO convention "${descriptor.kind}" handler must return a Response (got ${typeof result})`, {
+		status: 500,
+		headers: { "Content-Type": "text/plain; charset=utf-8" }
+	});
+}
+/**
+* 扫描 srcDir 下的 SEO 约定文件,为每个发现的文件注册 GET 路由。
+*
+* 调用方应在 `app.init()` *之前* 调用此函数,这样约定路由会和其它路由
+* 一起在 `init()` 中被纳入。如果调用方在 `init()` 之后调用,需要确保
+* app 实例支持动态添加路由(`UbeanApp` 支持)。
+*
+* @returns 已注册的约定 kind 列表(便于日志/调试)
+*/
+async function registerSeoConventions(app, options) {
+	const loaded = await discoverSeoConventions(options);
+	const registered = [];
+	for (const { descriptor, handler } of loaded) {
+		const routePath = descriptor.routePath;
+		app.get(routePath, async (c) => {
+			return await toResponse(descriptor, handler, c);
+		});
+		registered.push(descriptor.kind);
+	}
+	return registered;
+}
+/**
+* 列出 srcDir 下存在的约定文件 kind(不加载)。用于在不启动 app 的情况下
+* 检测项目使用了哪些约定(例如 CLI 信息展示)。
+*/
+function listSeoConventions(options) {
+	const srcDir = isAbsolute(options.srcDir) ? options.srcDir : resolve(process.cwd(), options.srcDir);
+	const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+	const found = [];
+	for (const descriptor of SEO_CONVENTIONS) for (const ext of extensions) if (existsSync(join(srcDir, `${descriptor.fileName}${ext}`))) {
+		found.push(descriptor.kind);
+		break;
+	}
+	return found;
+}
+//#endregion
+export { SEO_CONVENTIONS, discoverSeoConventions, listSeoConventions, registerSeoConventions };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { JsonLdInput, JsonLdSchema, defineJsonLd, mergeJsonLd, renderJsonLdScript, renderJsonLdScripts, schemaOrg, useSchemaOrg } from "./json-ld.js";
 import { UseSeoMetaInput } from "@unhead/vue";
 //#region src/index.d.ts
 interface RobotsOptions {
@@ -92,7 +93,27 @@ interface WebAppManifest {
   dir?: 'ltr' | 'rtl' | 'auto';
 }
 declare function useSeoMeta<T extends Record<string, any>>(meta: T): T;
+/**
+ * 对 meta tag 数组去重(后定义覆盖先定义)。
+ * 同 `name` 或同 `property` 的 tag 仅保留最后一个;无 name/property 的保留全部。
+ * 不修改入参数组,返回新数组。
+ */
+declare function dedupeMetaTags(tags: MetaTag[]): MetaTag[];
+/**
+ * 对 link tag 数组去重(后定义覆盖先定义)。
+ * 同 `rel`(+hreflang+type+sizes)的 link 仅保留最后一个;无 rel 的保留全部。
+ * 不修改入参数组,返回新数组。
+ */
+declare function dedupeLinkTags(tags: LinkTag[]): LinkTag[];
 declare function mergeMetadata(...metadatas: (SeoMetadata | undefined | null)[]): SeoMetadata;
+/**
+ * 按"全局 → 布局 → 页面"优先级合并 SEO metadata(Task 8)。
+ * 页面级覆盖布局级,布局级覆盖全局级;`meta`/`link` 数组自动去重(last-wins)。
+ *
+ * 与 `mergeMetadata` 的关系:`mergeSeoLayers(g, l, p)` 等价于
+ * `mergeMetadata(g, l, p)`,仅以命名参数显式表达三层优先级,便于阅读。
+ */
+declare function mergeSeoLayers(global?: SeoMetadata | null, layout?: SeoMetadata | null, page?: SeoMetadata | null): SeoMetadata;
 declare function buildMetaTags(meta: SeoMetadata): MetaTag[];
 declare function buildLinkTags(meta: SeoMetadata): LinkTag[];
 declare function buildTitle(meta: SeoMetadata, fallbackTitle?: string): string;
@@ -107,4 +128,4 @@ declare function createSitemapResponse(urls: SitemapUrl[]): Response;
 declare function defineRobotsConfig(config: RobotsOptions[] | RobotsOptions): RobotsOptions[] | RobotsOptions;
 declare function defineSitemapConfig(urls: SitemapUrl[] | (() => SitemapUrl[] | Promise<SitemapUrl[]>)): SitemapUrl[] | (() => SitemapUrl[] | Promise<SitemapUrl[]>);
 //#endregion
-export { LinkTag, ManifestIcon, MetaTag, OGImage, OpenGraphMeta, RobotsOptions, SeoMetadata, SitemapUrl, TwitterMeta, type UseSeoMetaInput, WebAppManifest, buildLinkTags, buildMetaTags, buildTitle, createManifestResponse, createRobotsResponse, createSitemapResponse, defineManifest, defineRobotsConfig, defineSitemapConfig, escapeXml, formatRobotsTxt, formatSitemapXml, mergeMetadata, renderHeadTags, useSeoMeta };
+export { JsonLdInput, JsonLdSchema, LinkTag, ManifestIcon, MetaTag, OGImage, OpenGraphMeta, RobotsOptions, SeoMetadata, SitemapUrl, TwitterMeta, type UseSeoMetaInput, WebAppManifest, buildLinkTags, buildMetaTags, buildTitle, createManifestResponse, createRobotsResponse, createSitemapResponse, dedupeLinkTags, dedupeMetaTags, defineJsonLd, defineManifest, defineRobotsConfig, defineSitemapConfig, escapeXml, formatRobotsTxt, formatSitemapXml, mergeJsonLd, mergeMetadata, mergeSeoLayers, renderHeadTags, renderJsonLdScript, renderJsonLdScripts, schemaOrg, useSchemaOrg, useSeoMeta };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { defineJsonLd, mergeJsonLd, renderJsonLdScript, renderJsonLdScripts, schemaOrg, useSchemaOrg } from "./json-ld.js";
 import { useSeoMeta as useSeoMeta$1 } from "@unhead/vue";
 //#region src/index.ts
 function useSeoMeta(meta) {
@@ -6,6 +7,76 @@ function useSeoMeta(meta) {
 	} catch {}
 	return meta;
 }
+/**
+* 计算 meta tag 的去重 key。
+* - 优先用 `name` 属性(如 description / keywords / robots / twitter:*)
+* - 其次用 `property` 属性(如 og:title / og:description)
+* - 两者都没有时不参与去重(保留全部)
+*/
+function metaTagKey(tag) {
+	if (tag.name) return `name:${tag.name}`;
+	if (tag.property) return `property:${tag.property}`;
+	return null;
+}
+/**
+* 计算 link tag 的去重 key。
+* 基于 rel + 可选的 hreflang / type / sizes 组合,后定义覆盖先定义:
+* - canonical:仅 rel 去重(页面级 canonical 覆盖布局级)
+* - alternate:rel + hreflang 去重(不同 hreflang 共存)
+* - icon:rel + sizes(+type)去重(不同尺寸/类型共存)
+*/
+function linkTagKey(tag) {
+	if (!tag.rel) return null;
+	const parts = [`rel:${tag.rel}`];
+	if (tag.hreflang) parts.push(`hreflang:${tag.hreflang}`);
+	if (tag.type) parts.push(`type:${tag.type}`);
+	if (tag.sizes) parts.push(`sizes:${tag.sizes}`);
+	return parts.join("|");
+}
+/**
+* 对 meta tag 数组去重(后定义覆盖先定义)。
+* 同 `name` 或同 `property` 的 tag 仅保留最后一个;无 name/property 的保留全部。
+* 不修改入参数组,返回新数组。
+*/
+function dedupeMetaTags(tags) {
+	const result = [];
+	const seen = /* @__PURE__ */ new Map();
+	for (const tag of tags) {
+		const key = metaTagKey(tag);
+		if (key === null) {
+			result.push(tag);
+			continue;
+		}
+		const existingIdx = seen.get(key);
+		if (existingIdx === void 0) {
+			seen.set(key, result.length);
+			result.push(tag);
+		} else result[existingIdx] = tag;
+	}
+	return result;
+}
+/**
+* 对 link tag 数组去重(后定义覆盖先定义)。
+* 同 `rel`(+hreflang+type+sizes)的 link 仅保留最后一个;无 rel 的保留全部。
+* 不修改入参数组,返回新数组。
+*/
+function dedupeLinkTags(tags) {
+	const result = [];
+	const seen = /* @__PURE__ */ new Map();
+	for (const tag of tags) {
+		const key = linkTagKey(tag);
+		if (key === null) {
+			result.push(tag);
+			continue;
+		}
+		const existingIdx = seen.get(key);
+		if (existingIdx === void 0) {
+			seen.set(key, result.length);
+			result.push(tag);
+		} else result[existingIdx] = tag;
+	}
+	return result;
+}
 function mergeMetadata(...metadatas) {
 	const result = {};
 	for (const meta of metadatas) {
@@ -36,8 +107,20 @@ function mergeMetadata(...metadatas) {
 		if (meta.meta) result.meta = [...result.meta || [], ...meta.meta];
 		if (meta.link) result.link = [...result.link || [], ...meta.link];
 	}
+	if (result.meta) result.meta = dedupeMetaTags(result.meta);
+	if (result.link) result.link = dedupeLinkTags(result.link);
 	return result;
 }
+/**
+* 按"全局 → 布局 → 页面"优先级合并 SEO metadata(Task 8)。
+* 页面级覆盖布局级,布局级覆盖全局级;`meta`/`link` 数组自动去重(last-wins)。
+*
+* 与 `mergeMetadata` 的关系:`mergeSeoLayers(g, l, p)` 等价于
+* `mergeMetadata(g, l, p)`,仅以命名参数显式表达三层优先级,便于阅读。
+*/
+function mergeSeoLayers(global, layout, page) {
+	return mergeMetadata(global, layout, page);
+}
 function buildMetaTags(meta) {
 	const tags = [];
 	if (meta.description) tags.push({
@@ -99,31 +182,33 @@ function buildMetaTags(meta) {
 			property: "og:locale:alternate",
 			content: loc
 		});
-		if (og.image) if (typeof og.image === "string") tags.push({
-			property: "og:image",
-			content: og.image
-		});
-		else {
-			tags.push({
+		if (og.image) {
+			if (typeof og.image === "string") tags.push({
 				property: "og:image",
-				content: og.image.url
-			});
-			if (og.image.width) tags.push({
-				property: "og:image:width",
-				content: String(og.image.width)
-			});
-			if (og.image.height) tags.push({
-				property: "og:image:height",
-				content: String(og.image.height)
-			});
-			if (og.image.alt) tags.push({
-				property: "og:image:alt",
-				content: og.image.alt
-			});
-			if (og.image.type) tags.push({
-				property: "og:image:type",
-				content: og.image.type
+				content: og.image
 			});
+			else {
+				tags.push({
+					property: "og:image",
+					content: og.image.url
+				});
+				if (og.image.width) tags.push({
+					property: "og:image:width",
+					content: String(og.image.width)
+				});
+				if (og.image.height) tags.push({
+					property: "og:image:height",
+					content: String(og.image.height)
+				});
+				if (og.image.alt) tags.push({
+					property: "og:image:alt",
+					content: og.image.alt
+				});
+				if (og.image.type) tags.push({
+					property: "og:image:type",
+					content: og.image.type
+				});
+			}
 		}
 	}
 	if (meta.twitter) {
@@ -167,8 +252,10 @@ function buildLinkTags(meta) {
 }
 function buildTitle(meta, fallbackTitle) {
 	let title = meta.title || fallbackTitle || "";
-	if (meta.titleTemplate && title) if (typeof meta.titleTemplate === "function") title = meta.titleTemplate(title);
-	else title = meta.titleTemplate.replace("%s", title);
+	if (meta.titleTemplate && title) {
+		if (typeof meta.titleTemplate === "function") title = meta.titleTemplate(title);
+		else title = meta.titleTemplate.replace("%s", title);
+	}
 	return title;
 }
 function renderHeadTags(meta, fallbackTitle) {
@@ -269,4 +356,4 @@ function defineSitemapConfig(urls) {
 	return urls;
 }
 //#endregion
-export { buildLinkTags, buildMetaTags, buildTitle, createManifestResponse, createRobotsResponse, createSitemapResponse, defineManifest, defineRobotsConfig, defineSitemapConfig, escapeXml, formatRobotsTxt, formatSitemapXml, mergeMetadata, renderHeadTags, useSeoMeta };
+export { buildLinkTags, buildMetaTags, buildTitle, createManifestResponse, createRobotsResponse, createSitemapResponse, dedupeLinkTags, dedupeMetaTags, defineJsonLd, defineManifest, defineRobotsConfig, defineSitemapConfig, escapeXml, formatRobotsTxt, formatSitemapXml, mergeJsonLd, mergeMetadata, mergeSeoLayers, renderHeadTags, renderJsonLdScript, renderJsonLdScripts, schemaOrg, useSchemaOrg, useSeoMeta };

package/dist/json-ld.d.ts

@@ -0,0 +1,122 @@
+//#region src/json-ld.d.ts
+/**
+ * P9-07 JSON-LD / Schema.org 结构化数据
+ *
+ * 提供 `defineJsonLd()` / `useSchemaOrg()` 两个 API,对齐 Nuxt `nuxt-schema.org` 的
+ * 用户体验,但实现保持零依赖(无 schema-dts 强约束),允许任意 JSON-LD 对象。
+ *
+ * 设计要点:
+ * - `defineJsonLd(schema)` 是纯函数:接收 Schema.org JSON-LD 对象(或返回它的函数),
+ *   返回标准的 `<script type="application/ld+json">` 标签字符串。
+ * - `useSchemaOrg(schema)` 是 Vue composable 版本,内部通过 `useHead` 注入到 head。
+ *   在非 Vue 上下文中静默降级(返回字符串)。
+ * - `renderJsonLdScript(schema)` 序列化为 HTML 字符串,自动转义 `</script>`、
+ *   U+2028/U+2029(避免 JSON 中断 JS 解析)。
+ * - 支持 graph 数组(`@graph`)和多 schema 合并。
+ *
+ * 对齐:Nuxt `nuxt-schema.org`(基于 `schema-dts` 类型);Astro 手动注入。
+ */
+/**
+ * 任意 JSON-LD 节点。必须是可序列化对象,通常包含 `@context` 和 `@type`。
+ */
+type JsonLdSchema = Record<string, unknown>;
+/**
+ * JSON-LD schema 输入:可以是对象、对象数组,或返回对象/数组的函数。
+ */
+type JsonLdInput = JsonLdSchema | JsonLdSchema[] | (() => JsonLdSchema | JsonLdSchema[] | Promise<JsonLdSchema | JsonLdSchema[]>);
+/**
+ * 渲染为 `<script type="application/ld+json">` HTML 字符串。
+ *
+ * 安全性:
+ * - `</script>` 拆分为 `<\/script>` 防止提前结束 script 标签
+ * - U+2028 / U+2029 替换为 Unicode 转义(防止 JS 解析器在 JSON 中断行)
+ *
+ * @example
+ * ```ts
+ * renderJsonLdScript({ '@context': 'https://schema.org', '@type': 'Organization', name: 'ubean' })
+ * // => <script type="application/ld+json">{"@context":"https://schema.org","@type":"Organization","name":"ubean"}</script>
+ * ```
+ */
+declare function renderJsonLdScript(schema: JsonLdSchema | JsonLdSchema[]): string;
+/**
+ * 把多个 JSON-LD schema 合并为 `@graph` 数组(对齐 schema.org 推荐做法)。
+ *
+ * 若输入只有一个 schema,直接返回(避免不必要的 @graph 包装)。
+ */
+declare function mergeJsonLd(schemas: JsonLdSchema[]): JsonLdSchema | JsonLdSchema[];
+/**
+ * 定义一个 JSON-LD schema(纯函数,无副作用)。
+ *
+ * @example
+ * ```ts
+ * const org = defineJsonLd({
+ *   '@context': 'https://schema.org',
+ *   '@type': 'Organization',
+ *   name: 'ubean',
+ *   url: 'https://ubean.dev'
+ * });
+ * // 在 SSR 中注入到 head:
+ * renderJsonLdScript(org)
+ * ```
+ */
+declare function defineJsonLd(schema: JsonLdInput): JsonLdInput;
+/**
+ * Vue composable:把 JSON-LD schema 注入到 head(通过 `useHead`)。
+ *
+ * 在非 Vue setup 上下文中静默降级(返回 schema 本身),不抛错。
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * useSchemaOrg({
+ *   '@context': 'https://schema.org',
+ *   '@type': 'Article',
+ *   headline: 'My Article',
+ *   author: { '@type': 'Person', name: 'John' }
+ * });
+ * </script>
+ * ```
+ */
+declare function useSchemaOrg(schema: JsonLdInput): JsonLdInput;
+/**
+ * 把多个 JSON-LD schema 渲染为 `<script>` 标签数组(SSR 用)。
+ */
+declare function renderJsonLdScripts(schemas: JsonLdSchema[]): string;
+/**
+ * 常见 Schema.org 类型的便捷工厂函数(覆盖 80% 用例)。
+ */
+declare const schemaOrg: {
+  organization(options: {
+    name: string;
+    url?: string;
+    logo?: string;
+    sameAs?: string[];
+  }): JsonLdSchema;
+  website(options: {
+    name: string;
+    url: string;
+    description?: string;
+  }): JsonLdSchema;
+  article(options: {
+    headline: string;
+    author: string;
+    datePublished: string;
+    image?: string;
+    publisher?: string;
+  }): JsonLdSchema;
+  breadcrumb(items: Array<{
+    name: string;
+    url: string;
+  }>): JsonLdSchema;
+  product(options: {
+    name: string;
+    description?: string;
+    brand?: string;
+    sku?: string;
+    price?: string;
+    priceCurrency?: string;
+    availability?: "InStock" | "OutOfStock" | "PreOrder";
+  }): JsonLdSchema;
+};
+//#endregion
+export { JsonLdInput, JsonLdSchema, defineJsonLd, mergeJsonLd, renderJsonLdScript, renderJsonLdScripts, schemaOrg, useSchemaOrg };