@ai-gui/plugin-citation 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @ai-gui/plugin-citation
+
+## 0.4.0
+
+### Minor Changes
+
+- Add plugin authoring helpers, secure source citation blocks, revisioned artifacts, bounded declarative AI-generated UI trees, molecular structures, and interactive maps.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ai-gui/core@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- Add a dependency-free `sources` fenced JSON plugin with strict validation, secure URL policy, synchronous framework-neutral rendering, prompt guidance, CSS, and serialization helpers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Li
+
+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

@@ -0,0 +1,60 @@
+# @ai-gui/plugin-citation
+
+Dependency-free, framework-neutral source citations for AIGUI. The plugin claims a complete `sources` fenced JSON block, validates it strictly, and renders a safe element descriptor.
+
+## Install
+
+```sh
+pnpm add @ai-gui/core @ai-gui/plugin-citation
+```
+
+## Usage
+
+```ts
+import { citation } from "@ai-gui/plugin-citation"
+
+const plugins = [citation()]
+```
+
+The default URL policy permits HTTPS only:
+
+````markdown
+```sources
+{
+  "sources": [
+    {
+      "id": "spec-1",
+      "title": "AIGUI specification",
+      "url": "https://example.com/spec",
+      "citedText": "Optional exact supporting text"
+    }
+  ]
+}
+```
+````
+
+Development HTTP origins can be allowlisted by host. A hostname permits any port; `host:port` permits only that exact port.
+
+```ts
+citation({ allowedHttpHosts: ["localhost", "dev.example.test:4317"] })
+```
+
+## Security
+
+- Closed-fence and renderer-level completion gating.
+- Strict JSON schema with unknown-key rejection.
+- Maximum 64 KiB UTF-8 input, 100 sources, and bounded field lengths.
+- Unique IDs restricted to letters, numbers, underscores, and hyphens, starting with a letter.
+- HTTPS-only by default; HTTP requires an exact allowlist match.
+- URL credentials, relative URLs, model HTML, and model actions are not supported.
+- Invalid input renders one generic fallback without reflecting source data or validation details.
+- Output is synchronous and framework-neutral.
+
+## Exports
+
+- `citation(options?)`
+- `citationPromptSpec()`
+- `parseSourcesDefinition(source, options?)`
+- `serializeSourcesFence(definition, options?)`
+- `citationCss`
+- `CitationOptions`, `CitationSource`, `SourcesDefinition`, and `SourcesParseResult`

package/dist/index.cjs

@@ -0,0 +1,246 @@
+"use strict";
+
+//#region src/index.ts
+const MAX_SOURCE_BYTES = 64 * 1024;
+const MAX_SOURCES = 100;
+const MAX_ID_LENGTH = 128;
+const MAX_TITLE_LENGTH = 256;
+const MAX_URL_LENGTH = 2048;
+const MAX_CITED_TEXT_LENGTH = 4096;
+const DEFINITION_KEYS = new Set(["sources"]);
+const SOURCE_KEYS = new Set([
+	"id",
+	"title",
+	"url",
+	"citedText"
+]);
+const SAFE_ID = /^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
+const citationCss = [
+	"[data-aigui-citations]{margin:1rem 0;padding:1rem;border:1px solid color-mix(in srgb,currentColor 18%,transparent);border-radius:.75rem}",
+	"[data-aigui-citations] h2{margin:0 0 .75rem;font-size:1rem}",
+	"[data-aigui-citations] ol{margin:0;padding-inline-start:1.5rem}",
+	"[data-aigui-citations] li+li{margin-top:.75rem}",
+	"[data-aigui-citations] blockquote{margin:.35rem 0 0;color:color-mix(in srgb,currentColor 72%,transparent)}",
+	"[data-aigui-citations-invalid]{margin:1rem 0;color:color-mix(in srgb,currentColor 72%,transparent)}"
+].join("\n");
+function citationPromptSpec() {
+	return [
+		"Sources (fenced JSON): ```sources {\"sources\":[{\"id\":\"safe-id\",\"title\":\"Source title\",\"url\":\"https://example.com/page\",\"citedText\":\"Optional exact supporting text\"}]} ```.",
+		"Use 1-100 sources. IDs must be unique and contain only letters, numbers, underscores, or hyphens, starting with a letter.",
+		"Use HTTPS URLs unless the application explicitly permits an HTTP host. Never emit HTML, actions, scripts, handlers, credentials, or extra fields."
+	].join("\n");
+}
+function citation(options = {}) {
+	const policy = normalizePolicy(options);
+	const render = (node) => {
+		if (node.complete !== true) return loadingOutput();
+		const parsed = parseWithPolicy(node.content ?? "", policy);
+		return parsed.valid ? renderSources(parsed.data) : invalidOutput();
+	};
+	return {
+		name: "citation",
+		nodeRenderers: { sources: render },
+		css: citationCss,
+		promptSpec: citationPromptSpec()
+	};
+}
+function parseSourcesDefinition(source, options = {}) {
+	return parseWithPolicy(source, normalizePolicy(options));
+}
+function serializeSourcesFence(definition, options = {}) {
+	let source;
+	try {
+		source = JSON.stringify(definition);
+	} catch {
+		throw new TypeError("Sources definition must be JSON-serializable.");
+	}
+	if (source === void 0) throw new TypeError("Sources definition must be JSON-serializable.");
+	const parsed = parseSourcesDefinition(source, options);
+	if (!parsed.valid) throw new TypeError("Invalid sources definition.");
+	return `\`\`\`sources\n${JSON.stringify(parsed.data, null, 2)}\n\`\`\``;
+}
+function normalizePolicy(options) {
+	if (!isPlainObject(options)) throw new TypeError("Citation options must be an object.");
+	for (const key of Object.keys(options)) if (key !== "allowedHttpHosts") throw new TypeError(`Unknown citation option: ${key}`);
+	if (options.allowedHttpHosts !== void 0 && !Array.isArray(options.allowedHttpHosts)) throw new TypeError("allowedHttpHosts must be an array.");
+	const anyPortHosts = new Set();
+	const exactEndpoints = new Set();
+	for (const entry of options.allowedHttpHosts ?? []) {
+		if (typeof entry !== "string" || entry.length === 0 || entry.trim() !== entry || /[/?#@]/.test(entry)) throw new TypeError("Each allowed HTTP host must be a hostname or hostname:port.");
+		let parsed;
+		try {
+			parsed = new URL(`http://${entry}`);
+		} catch {
+			throw new TypeError("Each allowed HTTP host must be a hostname or hostname:port.");
+		}
+		if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash || !parsed.hostname) throw new TypeError("Each allowed HTTP host must be a hostname or hostname:port.");
+		const explicitPort = readExplicitPort(entry);
+		if (explicitPort) exactEndpoints.add(`${parsed.hostname.toLowerCase()}:${explicitPort}`);
+		else anyPortHosts.add(parsed.hostname.toLowerCase());
+	}
+	return {
+		anyPortHosts,
+		exactEndpoints
+	};
+}
+function parseWithPolicy(source, policy) {
+	if (utf8Length(source) > MAX_SOURCE_BYTES) return invalid("Sources definition is too large.");
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		return invalid("Sources definition must be valid JSON.");
+	}
+	if (!isPlainObject(value)) return invalid("Sources definition must be an object.");
+	const issues = [];
+	rejectUnknownKeys(value, DEFINITION_KEYS, "$", issues);
+	if (!Array.isArray(value.sources)) {
+		issues.push("$.sources must be an array.");
+		return {
+			valid: false,
+			issues
+		};
+	}
+	if (value.sources.length === 0 || value.sources.length > MAX_SOURCES) issues.push(`$.sources must contain between 1 and ${MAX_SOURCES} sources.`);
+	const ids = new Set();
+	const sources = [];
+	value.sources.forEach((candidate, index) => {
+		const path = `$.sources[${index}]`;
+		if (!isPlainObject(candidate)) {
+			issues.push(`${path} must be an object.`);
+			return;
+		}
+		rejectUnknownKeys(candidate, SOURCE_KEYS, path, issues);
+		const id = readRequiredString(candidate.id, `${path}.id`, MAX_ID_LENGTH, issues);
+		const title = readRequiredString(candidate.title, `${path}.title`, MAX_TITLE_LENGTH, issues);
+		const rawUrl = readRequiredString(candidate.url, `${path}.url`, MAX_URL_LENGTH, issues);
+		const citedText = candidate.citedText === void 0 ? void 0 : readRequiredString(candidate.citedText, `${path}.citedText`, MAX_CITED_TEXT_LENGTH, issues);
+		if (id !== void 0) {
+			if (!SAFE_ID.test(id)) issues.push(`${path}.id is not a safe ID.`);
+			if (ids.has(id)) issues.push(`${path}.id must be unique.`);
+			ids.add(id);
+		}
+		const url = rawUrl === void 0 ? void 0 : normalizeUrl(rawUrl, path, policy, issues);
+		if (id !== void 0 && title !== void 0 && url !== void 0 && (candidate.citedText === void 0 || citedText !== void 0)) sources.push({
+			id,
+			title,
+			url,
+			...citedText === void 0 ? {} : { citedText }
+		});
+	});
+	return issues.length === 0 ? {
+		valid: true,
+		data: { sources }
+	} : {
+		valid: false,
+		issues
+	};
+}
+function normalizeUrl(raw, path, policy, issues) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		issues.push(`${path}.url must be an absolute URL.`);
+		return void 0;
+	}
+	if (url.username || url.password) {
+		issues.push(`${path}.url must not contain credentials.`);
+		return void 0;
+	}
+	const protocol = url.protocol.toLowerCase();
+	const endpoint = `${url.hostname.toLowerCase()}:${url.port || (protocol === "http:" ? "80" : "443")}`;
+	const httpAllowed = protocol === "http:" && (policy.anyPortHosts.has(url.hostname.toLowerCase()) || policy.exactEndpoints.has(endpoint));
+	if (protocol !== "https:" && !httpAllowed) {
+		issues.push(`${path}.url must use HTTPS or an allowed HTTP host.`);
+		return void 0;
+	}
+	const normalized = url.toString();
+	if (normalized.length > MAX_URL_LENGTH) {
+		issues.push(`${path}.url must contain at most ${MAX_URL_LENGTH} characters.`);
+		return void 0;
+	}
+	return normalized;
+}
+function renderSources(definition) {
+	return element("section", {
+		"data-aigui-citations": "",
+		"aria-label": "Sources"
+	}, [element("h2", void 0, [text("Sources")]), element("ol", void 0, definition.sources.map((source) => element("li", { "data-source-id": source.id }, [element("a", {
+		href: source.url,
+		target: "_blank",
+		rel: "noopener noreferrer nofollow"
+	}, [text(source.title)]), ...source.citedText === void 0 ? [] : [element("blockquote", void 0, [text(source.citedText)])]])))]);
+}
+function loadingOutput() {
+	return element("div", {
+		"data-aigui-block-loading": "",
+		"data-block-type": "sources"
+	}, []);
+}
+function invalidOutput() {
+	return element("div", {
+		"data-aigui-citations-invalid": "",
+		role: "status"
+	}, [text("Sources unavailable.")]);
+}
+function element(tag, props, children) {
+	return {
+		kind: "element",
+		tag,
+		props,
+		children
+	};
+}
+function text(value) {
+	return {
+		kind: "html",
+		html: escapeHtml(value)
+	};
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function readRequiredString(value, path, maxLength, issues) {
+	if (typeof value !== "string") {
+		issues.push(`${path} must be a string.`);
+		return void 0;
+	}
+	if (value.length === 0 || value.length > maxLength) {
+		issues.push(`${path} must contain between 1 and ${maxLength} characters.`);
+		return void 0;
+	}
+	return value;
+}
+function rejectUnknownKeys(value, allowed, path, issues) {
+	for (const key of Object.keys(value)) if (!allowed.has(key)) issues.push(`${path}.${key} is not supported.`);
+}
+function invalid(issue) {
+	return {
+		valid: false,
+		issues: [issue]
+	};
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function utf8Length(value) {
+	return new TextEncoder().encode(value).byteLength;
+}
+function readExplicitPort(host) {
+	if (host.startsWith("[")) {
+		const match$1 = host.match(/^\[[^\]]+\]:(\d+)$/);
+		return match$1?.[1];
+	}
+	const match = host.match(/:(\d+)$/);
+	return match?.[1];
+}
+
+//#endregion
+exports.citation = citation
+exports.citationCss = citationCss
+exports.citationPromptSpec = citationPromptSpec
+exports.parseSourcesDefinition = parseSourcesDefinition
+exports.serializeSourcesFence = serializeSourcesFence

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+interface CitationSource {
+  id: string;
+  title: string;
+  url: string;
+  citedText?: string;
+}
+interface SourcesDefinition {
+  sources: CitationSource[];
+}
+interface CitationOptions {
+  /** HTTP hosts allowed in addition to HTTPS. A hostname allows any port; host:port allows only that port. */
+  allowedHttpHosts?: readonly string[];
+}
+type SourcesParseResult = {
+  valid: true;
+  data: SourcesDefinition;
+} | {
+  valid: false;
+  issues: string[];
+};
+declare const citationCss: string;
+declare function citationPromptSpec(): string;
+declare function citation(options?: CitationOptions): AIGuiPlugin;
+declare function parseSourcesDefinition(source: string, options?: CitationOptions): SourcesParseResult;
+declare function serializeSourcesFence(definition: unknown, options?: CitationOptions): string; //#endregion
+export { CitationOptions, CitationSource, SourcesDefinition, SourcesParseResult, citation, citationCss, citationPromptSpec, parseSourcesDefinition, serializeSourcesFence };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+
+//#region src/index.d.ts
+interface CitationSource {
+  id: string;
+  title: string;
+  url: string;
+  citedText?: string;
+}
+interface SourcesDefinition {
+  sources: CitationSource[];
+}
+interface CitationOptions {
+  /** HTTP hosts allowed in addition to HTTPS. A hostname allows any port; host:port allows only that port. */
+  allowedHttpHosts?: readonly string[];
+}
+type SourcesParseResult = {
+  valid: true;
+  data: SourcesDefinition;
+} | {
+  valid: false;
+  issues: string[];
+};
+declare const citationCss: string;
+declare function citationPromptSpec(): string;
+declare function citation(options?: CitationOptions): AIGuiPlugin;
+declare function parseSourcesDefinition(source: string, options?: CitationOptions): SourcesParseResult;
+declare function serializeSourcesFence(definition: unknown, options?: CitationOptions): string; //#endregion
+export { CitationOptions, CitationSource, SourcesDefinition, SourcesParseResult, citation, citationCss, citationPromptSpec, parseSourcesDefinition, serializeSourcesFence };

package/dist/index.js

@@ -0,0 +1,240 @@
+//#region src/index.ts
+const MAX_SOURCE_BYTES = 64 * 1024;
+const MAX_SOURCES = 100;
+const MAX_ID_LENGTH = 128;
+const MAX_TITLE_LENGTH = 256;
+const MAX_URL_LENGTH = 2048;
+const MAX_CITED_TEXT_LENGTH = 4096;
+const DEFINITION_KEYS = new Set(["sources"]);
+const SOURCE_KEYS = new Set([
+	"id",
+	"title",
+	"url",
+	"citedText"
+]);
+const SAFE_ID = /^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
+const citationCss = [
+	"[data-aigui-citations]{margin:1rem 0;padding:1rem;border:1px solid color-mix(in srgb,currentColor 18%,transparent);border-radius:.75rem}",
+	"[data-aigui-citations] h2{margin:0 0 .75rem;font-size:1rem}",
+	"[data-aigui-citations] ol{margin:0;padding-inline-start:1.5rem}",
+	"[data-aigui-citations] li+li{margin-top:.75rem}",
+	"[data-aigui-citations] blockquote{margin:.35rem 0 0;color:color-mix(in srgb,currentColor 72%,transparent)}",
+	"[data-aigui-citations-invalid]{margin:1rem 0;color:color-mix(in srgb,currentColor 72%,transparent)}"
+].join("\n");
+function citationPromptSpec() {
+	return [
+		"Sources (fenced JSON): ```sources {\"sources\":[{\"id\":\"safe-id\",\"title\":\"Source title\",\"url\":\"https://example.com/page\",\"citedText\":\"Optional exact supporting text\"}]} ```.",
+		"Use 1-100 sources. IDs must be unique and contain only letters, numbers, underscores, or hyphens, starting with a letter.",
+		"Use HTTPS URLs unless the application explicitly permits an HTTP host. Never emit HTML, actions, scripts, handlers, credentials, or extra fields."
+	].join("\n");
+}
+function citation(options = {}) {
+	const policy = normalizePolicy(options);
+	const render = (node) => {
+		if (node.complete !== true) return loadingOutput();
+		const parsed = parseWithPolicy(node.content ?? "", policy);
+		return parsed.valid ? renderSources(parsed.data) : invalidOutput();
+	};
+	return {
+		name: "citation",
+		nodeRenderers: { sources: render },
+		css: citationCss,
+		promptSpec: citationPromptSpec()
+	};
+}
+function parseSourcesDefinition(source, options = {}) {
+	return parseWithPolicy(source, normalizePolicy(options));
+}
+function serializeSourcesFence(definition, options = {}) {
+	let source;
+	try {
+		source = JSON.stringify(definition);
+	} catch {
+		throw new TypeError("Sources definition must be JSON-serializable.");
+	}
+	if (source === void 0) throw new TypeError("Sources definition must be JSON-serializable.");
+	const parsed = parseSourcesDefinition(source, options);
+	if (!parsed.valid) throw new TypeError("Invalid sources definition.");
+	return `\`\`\`sources\n${JSON.stringify(parsed.data, null, 2)}\n\`\`\``;
+}
+function normalizePolicy(options) {
+	if (!isPlainObject(options)) throw new TypeError("Citation options must be an object.");
+	for (const key of Object.keys(options)) if (key !== "allowedHttpHosts") throw new TypeError(`Unknown citation option: ${key}`);
+	if (options.allowedHttpHosts !== void 0 && !Array.isArray(options.allowedHttpHosts)) throw new TypeError("allowedHttpHosts must be an array.");
+	const anyPortHosts = new Set();
+	const exactEndpoints = new Set();
+	for (const entry of options.allowedHttpHosts ?? []) {
+		if (typeof entry !== "string" || entry.length === 0 || entry.trim() !== entry || /[/?#@]/.test(entry)) throw new TypeError("Each allowed HTTP host must be a hostname or hostname:port.");
+		let parsed;
+		try {
+			parsed = new URL(`http://${entry}`);
+		} catch {
+			throw new TypeError("Each allowed HTTP host must be a hostname or hostname:port.");
+		}
+		if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash || !parsed.hostname) throw new TypeError("Each allowed HTTP host must be a hostname or hostname:port.");
+		const explicitPort = readExplicitPort(entry);
+		if (explicitPort) exactEndpoints.add(`${parsed.hostname.toLowerCase()}:${explicitPort}`);
+		else anyPortHosts.add(parsed.hostname.toLowerCase());
+	}
+	return {
+		anyPortHosts,
+		exactEndpoints
+	};
+}
+function parseWithPolicy(source, policy) {
+	if (utf8Length(source) > MAX_SOURCE_BYTES) return invalid("Sources definition is too large.");
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		return invalid("Sources definition must be valid JSON.");
+	}
+	if (!isPlainObject(value)) return invalid("Sources definition must be an object.");
+	const issues = [];
+	rejectUnknownKeys(value, DEFINITION_KEYS, "$", issues);
+	if (!Array.isArray(value.sources)) {
+		issues.push("$.sources must be an array.");
+		return {
+			valid: false,
+			issues
+		};
+	}
+	if (value.sources.length === 0 || value.sources.length > MAX_SOURCES) issues.push(`$.sources must contain between 1 and ${MAX_SOURCES} sources.`);
+	const ids = new Set();
+	const sources = [];
+	value.sources.forEach((candidate, index) => {
+		const path = `$.sources[${index}]`;
+		if (!isPlainObject(candidate)) {
+			issues.push(`${path} must be an object.`);
+			return;
+		}
+		rejectUnknownKeys(candidate, SOURCE_KEYS, path, issues);
+		const id = readRequiredString(candidate.id, `${path}.id`, MAX_ID_LENGTH, issues);
+		const title = readRequiredString(candidate.title, `${path}.title`, MAX_TITLE_LENGTH, issues);
+		const rawUrl = readRequiredString(candidate.url, `${path}.url`, MAX_URL_LENGTH, issues);
+		const citedText = candidate.citedText === void 0 ? void 0 : readRequiredString(candidate.citedText, `${path}.citedText`, MAX_CITED_TEXT_LENGTH, issues);
+		if (id !== void 0) {
+			if (!SAFE_ID.test(id)) issues.push(`${path}.id is not a safe ID.`);
+			if (ids.has(id)) issues.push(`${path}.id must be unique.`);
+			ids.add(id);
+		}
+		const url = rawUrl === void 0 ? void 0 : normalizeUrl(rawUrl, path, policy, issues);
+		if (id !== void 0 && title !== void 0 && url !== void 0 && (candidate.citedText === void 0 || citedText !== void 0)) sources.push({
+			id,
+			title,
+			url,
+			...citedText === void 0 ? {} : { citedText }
+		});
+	});
+	return issues.length === 0 ? {
+		valid: true,
+		data: { sources }
+	} : {
+		valid: false,
+		issues
+	};
+}
+function normalizeUrl(raw, path, policy, issues) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		issues.push(`${path}.url must be an absolute URL.`);
+		return void 0;
+	}
+	if (url.username || url.password) {
+		issues.push(`${path}.url must not contain credentials.`);
+		return void 0;
+	}
+	const protocol = url.protocol.toLowerCase();
+	const endpoint = `${url.hostname.toLowerCase()}:${url.port || (protocol === "http:" ? "80" : "443")}`;
+	const httpAllowed = protocol === "http:" && (policy.anyPortHosts.has(url.hostname.toLowerCase()) || policy.exactEndpoints.has(endpoint));
+	if (protocol !== "https:" && !httpAllowed) {
+		issues.push(`${path}.url must use HTTPS or an allowed HTTP host.`);
+		return void 0;
+	}
+	const normalized = url.toString();
+	if (normalized.length > MAX_URL_LENGTH) {
+		issues.push(`${path}.url must contain at most ${MAX_URL_LENGTH} characters.`);
+		return void 0;
+	}
+	return normalized;
+}
+function renderSources(definition) {
+	return element("section", {
+		"data-aigui-citations": "",
+		"aria-label": "Sources"
+	}, [element("h2", void 0, [text("Sources")]), element("ol", void 0, definition.sources.map((source) => element("li", { "data-source-id": source.id }, [element("a", {
+		href: source.url,
+		target: "_blank",
+		rel: "noopener noreferrer nofollow"
+	}, [text(source.title)]), ...source.citedText === void 0 ? [] : [element("blockquote", void 0, [text(source.citedText)])]])))]);
+}
+function loadingOutput() {
+	return element("div", {
+		"data-aigui-block-loading": "",
+		"data-block-type": "sources"
+	}, []);
+}
+function invalidOutput() {
+	return element("div", {
+		"data-aigui-citations-invalid": "",
+		role: "status"
+	}, [text("Sources unavailable.")]);
+}
+function element(tag, props, children) {
+	return {
+		kind: "element",
+		tag,
+		props,
+		children
+	};
+}
+function text(value) {
+	return {
+		kind: "html",
+		html: escapeHtml(value)
+	};
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function readRequiredString(value, path, maxLength, issues) {
+	if (typeof value !== "string") {
+		issues.push(`${path} must be a string.`);
+		return void 0;
+	}
+	if (value.length === 0 || value.length > maxLength) {
+		issues.push(`${path} must contain between 1 and ${maxLength} characters.`);
+		return void 0;
+	}
+	return value;
+}
+function rejectUnknownKeys(value, allowed, path, issues) {
+	for (const key of Object.keys(value)) if (!allowed.has(key)) issues.push(`${path}.${key} is not supported.`);
+}
+function invalid(issue) {
+	return {
+		valid: false,
+		issues: [issue]
+	};
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function utf8Length(value) {
+	return new TextEncoder().encode(value).byteLength;
+}
+function readExplicitPort(host) {
+	if (host.startsWith("[")) {
+		const match$1 = host.match(/^\[[^\]]+\]:(\d+)$/);
+		return match$1?.[1];
+	}
+	const match = host.match(/:(\d+)$/);
+	return match?.[1];
+}
+
+//#endregion
+export { citation, citationCss, citationPromptSpec, parseSourcesDefinition, serializeSourcesFence };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ai-gui/plugin-citation",
+  "version": "0.4.0",
+  "description": "Secure framework-neutral source citation fences for AIGUI.",
+  "keywords": [
+    "llm",
+    "ai",
+    "citations",
+    "sources",
+    "markdown",
+    "plugin",
+    "aigui"
+  ],
+  "license": "MIT",
+  "author": "Liang Li <ll_faw@hotmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liliang-cn/aigui.git",
+    "directory": "packages/plugin-citation"
+  },
+  "homepage": "https://github.com/liliang-cn/aigui#readme",
+  "bugs": "https://github.com/liliang-cn/aigui/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-gui/core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "pnpm --dir ../.. exec vitest run --project plugin-citation",
+    "typecheck": "tsc --noEmit"
+  }
+}