@hiai-gg/docsmint 0.3.0

package/frontend/src/lib/components/editor/shared-document.ts

@@ -0,0 +1,237 @@
+export type ProseMirrorNode = {
+	type: string;
+	text?: string;
+	content?: ProseMirrorNode[];
+	attrs?: Record<string, unknown>;
+	marks?: Array<{ type: string; attrs?: Record<string, unknown> }>;
+};
+
+export type ProseMirrorDoc = ProseMirrorNode & {
+	content?: ProseMirrorNode[];
+};
+
+/** Object URLs created while hydrating protected share attachments. */
+export type SharedAttachmentObjectUrls = string[];
+
+const ATTACHMENT_PATH = /^\/api\/attachments\/[0-9a-f-]+\/raw$/i;
+const SAFE_LINK_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
+
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;");
+}
+
+function wrapMark(
+	mark: { type: string; attrs?: Record<string, unknown> },
+	html: string,
+): string {
+	switch (mark.type) {
+		case "bold":
+			return `<strong>${html}</strong>`;
+		case "italic":
+			return `<em>${html}</em>`;
+		case "strike":
+		case "strikethrough":
+			return `<s>${html}</s>`;
+		case "underline":
+			return `<u>${html}</u>`;
+		case "code":
+			return `<code>${html}</code>`;
+		case "link": {
+			const rawHref = (mark.attrs?.href as string) ?? "#";
+			const href = safeLinkHref(rawHref);
+			return `<a href="${escapeHtml(href)}" target="_blank" rel="noopener noreferrer">${html}</a>`;
+		}
+		case "highlight": {
+			const color = (mark.attrs?.color as string) ?? "#fde68a";
+			return `<mark style="background-color: ${escapeHtml(color)}">${html}</mark>`;
+		}
+		default:
+			return html;
+	}
+}
+
+function safeLinkHref(href: string): string {
+	if (href.startsWith("#") || href.startsWith("/") || href.startsWith("./")) {
+		return href;
+	}
+	try {
+		const url = new URL(href);
+		return SAFE_LINK_PROTOCOLS.has(url.protocol) ? href : "#";
+	} catch {
+		return "#";
+	}
+}
+
+function alignStyle(attrs?: Record<string, unknown>): string {
+	const align = attrs?.textAlign;
+	if (
+		align !== "left" &&
+		align !== "center" &&
+		align !== "right" &&
+		align !== "justify"
+	) {
+		return "";
+	}
+	return ` style="text-align: ${align}"`;
+}
+
+/**
+ * Render descendants as inline content. Older imported documents can contain
+ * a paragraph inside a heading. That is invalid ProseMirror/HTML, so emitting
+ * it verbatim makes browsers restructure the document unpredictably. Flatten
+ * block wrappers in inline-only parents while preserving their text/marks.
+ */
+function renderInline(node: ProseMirrorNode): string {
+	if (node.type === "text") {
+		let html = escapeHtml(node.text ?? "");
+		for (const mark of node.marks ?? []) html = wrapMark(mark, html);
+		return html;
+	}
+	return (node.content ?? []).map(renderInline).join("");
+}
+
+export function renderSharedDocument(doc: ProseMirrorDoc): string {
+	const renderNode = (node: ProseMirrorNode): string => {
+		if (node.type === "text") return renderInline(node);
+
+		const align = alignStyle(node.attrs);
+		const inner = (node.content ?? []).map(renderNode).join("");
+		switch (node.type) {
+			case "paragraph":
+				return `<p${align}>${inner}</p>`;
+			case "heading": {
+				const level = Math.min(Math.max(Number(node.attrs?.level ?? 1), 1), 6);
+				return `<h${level}${align}>${(node.content ?? []).map(renderInline).join("")}</h${level}>`;
+			}
+			case "bulletList":
+				return `<ul${align}>${inner}</ul>`;
+			case "orderedList": {
+				const rawStart = Number(node.attrs?.start ?? 1);
+				const start =
+					Number.isSafeInteger(rawStart) && rawStart > 1
+						? ` start="${rawStart}"`
+						: "";
+				return `<ol${start}${align}>${inner}</ol>`;
+			}
+			case "listItem":
+				return `<li${align}>${inner}</li>`;
+			case "taskList":
+				return `<ul data-type="taskList">${inner}</ul>`;
+			case "taskItem": {
+				const checked =
+					node.attrs?.checked === true || node.attrs?.checked === "true";
+				return `<li data-type="taskItem"${checked ? ' data-checked="true"' : ""}><label><input type="checkbox" disabled${checked ? " checked" : ""} /></label><div>${inner}</div></li>`;
+			}
+			case "blockquote":
+				return `<blockquote${align}>${inner}</blockquote>`;
+			case "table":
+				return `<table><tbody>${inner}</tbody></table>`;
+			case "tableRow":
+				return `<tr>${inner}</tr>`;
+			case "tableHeader":
+				return `<th${align}>${inner}</th>`;
+			case "tableCell":
+				return `<td${align}>${inner}</td>`;
+			case "codeBlock": {
+				const lang = (node.attrs?.language as string) ?? "";
+				return `<pre><code${lang ? ` class="language-${escapeHtml(lang)}"` : ""}>${inner}</code></pre>`;
+			}
+			case "horizontalRule":
+				return "<hr />";
+			case "hardBreak":
+				return "<br />";
+			case "image": {
+				const src = (node.attrs?.src as string) ?? "";
+				const alt = (node.attrs?.alt as string) ?? "";
+				const width = Number(node.attrs?.width);
+				const height = Number(node.attrs?.height);
+				const dimensions = `${Number.isFinite(width) && width > 0 ? ` width="${Math.round(width)}"` : ""}${Number.isFinite(height) && height > 0 ? ` height="${Math.round(height)}"` : ""}`;
+				if (ATTACHMENT_PATH.test(src)) {
+					return `<img data-shared-attachment-src="${escapeHtml(src)}" alt="${escapeHtml(alt)}"${dimensions} />`;
+				}
+				return `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}"${dimensions} />`;
+			}
+			default:
+				return inner;
+		}
+	};
+
+	return (doc.content ?? []).map(renderNode).join("");
+}
+
+/** Mark Markdown task items so print/PDF CSS can suppress the regular bullet. */
+export function markMarkdownTaskItems(html: string): string {
+	return html.replace(
+		/<li>(\s*<input\b[^>]*type=["']checkbox["'][^>]*>)/gi,
+		'<li class="task-list-item">$1',
+	);
+}
+
+export function sharedAttachmentHeaders(
+	token: string,
+	password = "",
+): HeadersInit {
+	return {
+		"x-share-token": token,
+		...(password ? { "x-share-password": password } : {}),
+	};
+}
+
+/** Replace protected attachment placeholders with authenticated blob URLs. */
+export async function hydrateSharedAttachmentImages(
+	root: ParentNode,
+	token: string,
+	password = "",
+): Promise<SharedAttachmentObjectUrls> {
+	const objectUrls: string[] = [];
+	const images = root.querySelectorAll<HTMLImageElement>(
+		"img[data-shared-attachment-src]",
+	);
+	await Promise.all(
+		Array.from(images, async (image) => {
+			const src = image.dataset.sharedAttachmentSrc;
+			if (!src) return;
+			try {
+				const response = await fetch(src, {
+					headers: sharedAttachmentHeaders(token, password),
+				});
+				if (!response.ok) {
+					image.dataset.sharedAttachmentError = String(response.status);
+					return;
+				}
+				const objectUrl = URL.createObjectURL(await response.blob());
+				objectUrls.push(objectUrl);
+				image.src = objectUrl;
+				image.removeAttribute("data-shared-attachment-src");
+			} catch {
+				image.dataset.sharedAttachmentError = "network";
+			}
+		}),
+	);
+	return objectUrls;
+}
+
+/** Wait until every image in a print/export subtree has finished loading. */
+export async function waitForSharedDocumentImages(
+	root: ParentNode,
+): Promise<void> {
+	const images = Array.from(root.querySelectorAll<HTMLImageElement>("img"));
+	await Promise.all(
+		images.map(async (image) => {
+			if (image.complete) return;
+			if (typeof image.decode === "function") {
+				await image.decode().catch(() => undefined);
+				return;
+			}
+			await new Promise<void>((resolve) => {
+				image.addEventListener("load", () => resolve(), { once: true });
+				image.addEventListener("error", () => resolve(), { once: true });
+			});
+		}),
+	);
+}

package/frontend/src/lib/extensions/context.ts

@@ -0,0 +1,60 @@
+import { createContext } from "svelte";
+import type { HiaiDocsFrontendExtensions } from "./types";
+
+/**
+ * Create a fresh manifest for one app/request.
+ *
+ * A new array is created for every category so an SSR request or HMR update
+ * cannot mutate another request's extension set.
+ */
+export function createFrontendExtensions(
+	initial: Partial<HiaiDocsFrontendExtensions> = {},
+): HiaiDocsFrontendExtensions {
+	return {
+		navigation: [...(initial.navigation ?? [])],
+		dashboardWidgets: [...(initial.dashboardWidgets ?? [])],
+		searchWidgets: [...(initial.searchWidgets ?? [])],
+		documentTabs: [...(initial.documentTabs ?? [])],
+		editorActions: [...(initial.editorActions ?? [])],
+		documentMenuActions: [...(initial.documentMenuActions ?? [])],
+		settingsSections: [...(initial.settingsSections ?? [])],
+		commandPaletteActions: [...(initial.commandPaletteActions ?? [])],
+		sharedDocumentHeaderActions: [
+			...(initial.sharedDocumentHeaderActions ?? []),
+		],
+		sharedDocumentTabs: [...(initial.sharedDocumentTabs ?? [])],
+		sharedDocumentNotesModes: [...(initial.sharedDocumentNotesModes ?? [])],
+		sharedDocumentEditorModes: [...(initial.sharedDocumentEditorModes ?? [])],
+	};
+}
+
+/**
+ * Svelte's context storage is scoped to a component tree, which makes this
+ * safe for concurrent SSR requests. Do not replace this with a module-level
+ * mutable registry.
+ */
+const [getProvidedFrontendExtensions, setFrontendExtensions] =
+	createContext<HiaiDocsFrontendExtensions>();
+
+export { setFrontendExtensions };
+
+/**
+ * Read the request-scoped manifest, defaulting to an empty manifest for the
+ * standalone open-source application. This keeps every host backward
+ * compatible when no extension provider is mounted above it.
+ */
+export function getFrontendExtensions(): HiaiDocsFrontendExtensions {
+	return getProvidedFrontendExtensions() ?? createFrontendExtensions();
+}
+
+/** Stable aliases for hosts that prefer the product name in their imports. */
+export const getHiaiDocsExtensions = getFrontendExtensions;
+export const setHiaiDocsExtensions = setFrontendExtensions;
+
+export function provideFrontendExtensions(
+	initial: Partial<HiaiDocsFrontendExtensions> = {},
+): HiaiDocsFrontendExtensions {
+	const extensions = createFrontendExtensions(initial);
+	setFrontendExtensions(extensions);
+	return extensions;
+}

package/frontend/src/lib/extensions/doc-tabs.ts

@@ -0,0 +1,18 @@
+import type { Component, ComponentType, SvelteComponent } from "svelte";
+
+export type DocTabIcon = ComponentType<SvelteComponent>;
+
+export interface DocTabPanelProps {
+	documentId: string;
+	content: string;
+	contentJson: object | undefined;
+}
+
+export interface DocTabDefinition {
+	id: string;
+	label: string;
+	component: Component<DocTabPanelProps>;
+	order?: number;
+	icon?: DocTabIcon;
+	disabled?: boolean;
+}

package/frontend/src/lib/extensions/resolve.ts

@@ -0,0 +1,48 @@
+import type { ExtensionVisibility, ExtensionVisibilityContext } from "./types";
+
+type OrderedExtension = {
+	id: string;
+	order?: number;
+	visible?: ExtensionVisibility;
+};
+
+/**
+ * Returns extensions in a deterministic order, omitting duplicate ids and
+ * extensions that are unavailable in the current host context.
+ *
+ * Extension manifests are an optional product boundary. A faulty visibility
+ * predicate must not prevent the stock HiAi-Docs UI from rendering, so a
+ * throwing predicate is treated as not visible.
+ */
+export function resolveExtensions<T extends OrderedExtension>(
+	extensions: readonly T[],
+	context: ExtensionVisibilityContext = {},
+): T[] {
+	const seen = new Set<string>();
+	const visible: T[] = [];
+
+	for (const extension of extensions) {
+		if (seen.has(extension.id) || !isVisible(extension.visible, context)) {
+			continue;
+		}
+		seen.add(extension.id);
+		visible.push(extension);
+	}
+
+	return visible.sort((a, b) => {
+		const orderDifference = (a.order ?? 0) - (b.order ?? 0);
+		return orderDifference !== 0 ? orderDifference : a.id.localeCompare(b.id);
+	});
+}
+
+function isVisible(
+	visible: ExtensionVisibility | undefined,
+	context: ExtensionVisibilityContext,
+): boolean {
+	if (!visible) return true;
+	try {
+		return visible(context);
+	} catch {
+		return false;
+	}
+}

package/frontend/src/lib/extensions/types.ts

@@ -0,0 +1,202 @@
+import type { Component } from "svelte";
+import type {
+	DocTabDefinition,
+	DocTabIcon,
+	DocTabPanelProps,
+} from "./doc-tabs";
+
+/**
+ * Runtime information supplied to extension visibility predicates.
+ *
+ * The object is intentionally data-only. Extensions can therefore be
+ * evaluated during SSR without reaching for browser globals or a module-level
+ * store.
+ */
+export interface ExtensionVisibilityContext {
+	userId?: string;
+	pathname?: string;
+	capabilities?: Readonly<Record<string, boolean>>;
+	permissions?: Readonly<Record<string, boolean>>;
+}
+
+export type ExtensionVisibility = (
+	context: ExtensionVisibilityContext,
+) => boolean;
+
+/** Icon shape shared with the existing document-tab contract. */
+export type ExtensionIcon = DocTabIcon;
+
+export interface NavigationExtension {
+	id: string;
+	label: string;
+	href?: string;
+	icon?: ExtensionIcon;
+	order?: number;
+	badge?: string | number;
+	disabled?: boolean;
+	visible?: ExtensionVisibility;
+}
+
+export interface DashboardWidgetProps {
+	userId?: string;
+}
+
+export interface DashboardWidgetExtension {
+	id: string;
+	title?: string;
+	component: Component<DashboardWidgetProps>;
+	order?: number;
+	colSpan?: 1 | 2 | 3 | 4 | 6 | 12;
+	visible?: ExtensionVisibility;
+}
+
+/**
+ * Read-only state supplied to a search extension.
+ *
+ * Search extensions deliberately receive result metadata only. They cannot
+ * alter retrieval, ranking, filters, or the authenticated API client.
+ */
+export interface SearchWidgetProps {
+	query: string;
+	loading: boolean;
+	total?: number;
+}
+
+export interface SearchWidgetExtension {
+	id: string;
+	title?: string;
+	component: Component<SearchWidgetProps>;
+	order?: number;
+	visible?: ExtensionVisibility;
+}
+
+export interface EditorActionContext {
+	documentId: string;
+	content: string;
+	contentJson: object | undefined;
+	selection?: unknown;
+	/** The host supplies an editor command facade; no editor implementation leaks into the contract. */
+	commands?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
+}
+
+export type ExtensionAction = (
+	context: EditorActionContext,
+) => void | Promise<void>;
+
+export interface EditorActionExtension {
+	id: string;
+	label: string;
+	icon?: ExtensionIcon;
+	order?: number;
+	disabled?: boolean | ((context: EditorActionContext) => boolean);
+	visible?: ExtensionVisibility;
+	run: ExtensionAction;
+}
+
+export interface DocumentMenuActionContext extends EditorActionContext {
+	title?: string;
+}
+
+export type DocumentMenuAction = (
+	context: DocumentMenuActionContext,
+) => void | Promise<void>;
+
+export interface DocumentMenuActionExtension {
+	id: string;
+	label: string;
+	icon?: ExtensionIcon;
+	order?: number;
+	destructive?: boolean;
+	disabled?: boolean | ((context: DocumentMenuActionContext) => boolean);
+	visible?: ExtensionVisibility;
+	run: DocumentMenuAction;
+}
+
+export interface SettingsSectionProps {
+	userId?: string;
+}
+
+export interface SettingsSectionExtension {
+	id: string;
+	label: string;
+	component: Component<SettingsSectionProps>;
+	order?: number;
+	description?: string;
+	visible?: ExtensionVisibility;
+}
+
+export interface CommandPaletteActionContext {
+	query?: string;
+}
+
+export type CommandPaletteAction = (
+	context: CommandPaletteActionContext,
+) => void | Promise<void>;
+
+export interface CommandPaletteActionExtension {
+	id: string;
+	label: string;
+	keywords?: readonly string[];
+	group?: string;
+	shortcut?: string;
+	icon?: ExtensionIcon;
+	order?: number;
+	disabled?: boolean;
+	visible?: ExtensionVisibility;
+	run: CommandPaletteAction;
+}
+
+/** Safe capability hints for a public shared-document extension. */
+export interface SharedDocumentExtensionContext {
+	shareToken: string;
+	documentId: string;
+	title: string;
+	content: string;
+	contentJson?: object;
+	role: "viewer" | "commenter" | "editor";
+	permissions: {
+		read: true;
+		annotate: boolean;
+		edit: boolean;
+		export: boolean;
+	};
+}
+
+export interface SharedDocumentExtension {
+	id: string;
+	label: string;
+	icon?: ExtensionIcon;
+	order?: number;
+	permission: "annotate" | "edit";
+	visible?: (context: SharedDocumentExtensionContext) => boolean;
+	component: Component<{ context: SharedDocumentExtensionContext }>;
+}
+
+/**
+ * Complete frontend extension manifest consumed by hiai-docs app-shell and
+ * page components. Arrays are readonly to keep registration request-scoped
+ * and to prevent extensions mutating one another during SSR.
+ */
+export interface DocsmintFrontendExtensions {
+	navigation: readonly NavigationExtension[];
+	dashboardWidgets: readonly DashboardWidgetExtension[];
+	searchWidgets: readonly SearchWidgetExtension[];
+	documentTabs: readonly DocTabDefinition[];
+	editorActions: readonly EditorActionExtension[];
+	documentMenuActions: readonly DocumentMenuActionExtension[];
+	settingsSections: readonly SettingsSectionExtension[];
+	commandPaletteActions: readonly CommandPaletteActionExtension[];
+	sharedDocumentHeaderActions: readonly SharedDocumentExtension[];
+	sharedDocumentTabs: readonly SharedDocumentExtension[];
+	sharedDocumentNotesModes: readonly SharedDocumentExtension[];
+	sharedDocumentEditorModes: readonly SharedDocumentExtension[];
+}
+
+/** @deprecated Use DocsmintFrontendExtensions. */
+export type HiaiDocsFrontendExtensions = DocsmintFrontendExtensions;
+
+/** Backwards-compatible, concise name for consumers defining a manifest. */
+export type FrontendExtensions = DocsmintFrontendExtensions;
+
+/** Props used by a document tab component in extension manifests. */
+export type { DocTabDefinition, DocTabPanelProps };

package/frontend/src/lib/hosts/DocsmintSharedDocumentHost.svelte

@@ -0,0 +1,65 @@
+<script lang="ts">
+import type { Snippet } from "svelte";
+import { getFrontendExtensions } from "../extensions/context";
+import type {
+	SharedDocumentExtension,
+	SharedDocumentExtensionContext,
+} from "../extensions/types";
+
+const {
+	context,
+	children,
+}: {
+	context: SharedDocumentExtensionContext;
+	children: Snippet;
+} = $props();
+
+const extensions = getFrontendExtensions();
+function permitted(extension: SharedDocumentExtension) {
+	return extension.permission === "annotate"
+		? context.permissions.annotate
+		: context.permissions.edit;
+}
+function visible(items: readonly SharedDocumentExtension[]) {
+	const seen = new Set<string>();
+	return items
+		.filter((extension) => {
+			if (seen.has(extension.id) || !permitted(extension)) return false;
+			seen.add(extension.id);
+			try {
+				return extension.visible?.(context) ?? true;
+			} catch {
+				return false;
+			}
+		})
+		.sort(
+			(a, b) => (a.order ?? 0) - (b.order ?? 0) || a.id.localeCompare(b.id),
+		);
+}
+</script>
+
+<div data-docsmint-shared-document-host>
+	<div data-extension-zone="shared-header-actions">
+		{#each visible(extensions.sharedDocumentHeaderActions) as extension (extension.id)}
+			<extension.component {context} />
+		{/each}
+	</div>
+	{@render children()}
+	<div data-extension-zone="shared-document-tabs">
+		{#each visible(extensions.sharedDocumentTabs) as extension (extension.id)}
+			<extension.component {context} />
+		{/each}
+	</div>
+	<div data-extension-zone="shared-document-notes">
+		{#each visible(extensions.sharedDocumentNotesModes) as extension (extension.id)}
+			<extension.component {context} />
+		{/each}
+	</div>
+	<div data-extension-zone="shared-document-editor">
+		{#if context.permissions.edit}
+			{#each visible(extensions.sharedDocumentEditorModes) as extension (extension.id)}
+				<extension.component {context} />
+			{/each}
+		{/if}
+	</div>
+</div>