Merge pull request #8 from smcllns/codex/css-theme-tokens

yolo-sam · web-flow · commit f5d7a7107acf · 2026-05-14T17:16:00.000-07:00
feat: Inject Obsidian theme tokens into HTML docs
diff --git a/.agents/plans/2026-05-14-css-theme-tokens.md b/.agents/plans/2026-05-14-css-theme-tokens.md
@@ -0,0 +1,15 @@
+# CSS Theme Tokens
+
+Status: ready for review
+
+Scope:
+- [x] Merge docs PR #6 and sync `main`
+- [x] Add failing E2E coverage for injected Obsidian theme tokens
+- [x] Inject a one-way `:root` theme-token snapshot into HTML iframes
+- [x] Apply to tab, markdown embed, and Canvas embed renders
+- [x] Re-render open HTML views/embeds when Obsidian theme classes change
+- [x] Document the supported `--obsidian-*` CSS contract
+- [x] Run release checks and prepare PR
+
+Unresolved questions:
+- None.
diff --git a/README.md b/README.md
@@ -72,6 +72,18 @@ Embed HTML docs like other Obsidian embeds. Embeds default to about 600px tall;
 ![[doc.html|600x400]]
 ```
 
+Each iframe receives a one-way snapshot of Obsidian theme styles. HTML docs can use these CSS variables to match light/dark mode, theme colors, and fonts without giving the iframe permission to read Obsidian or the vault. Use fallbacks so files still work outside Obsidian:
+
+```css
+:root {
+  color-scheme: var(--obsidian-color-scheme, light dark);
+  --bg: var(--obsidian-bg, light-dark(#fff, #0e1014));
+  --text: var(--obsidian-text, light-dark(#16161a, #e7e9ec));
+}
+```
+
+Available CSS variables: `--obsidian-color-scheme`, `--obsidian-bg`, `--obsidian-bg-2`, `--obsidian-text`, `--obsidian-text-muted`, `--obsidian-accent`, `--obsidian-border`, `--obsidian-font`, `--obsidian-font-mono`.
+
 ## Obsidian Plugin Docs
 
 * Developer docs: [docs.obsidian.md](https://docs.obsidian.md)
@@ -85,7 +97,7 @@ That keeps HTML documents isolated from your notes and Obsidian internals, with
 * **Wikilinks to HTML docs need the explicit extension (`[[doc.html]]`).** Extensionless non-Markdown links are not first-class in Obsidian's link index, and click-only plugin handling would leave backlinks and unresolved-link state inconsistent.
 * **Links from HTML to Obsidian docs should use Obsidian URI links plus `target="_blank"`.** They hand off to Obsidian without letting the iframe navigate the parent window directly; direct same-tab navigation would require top-navigation sandbox permissions and weaken the boundary.
 * **Cookies, `localStorage`, `sessionStorage`, and `IndexedDB` are intentionally unavailable.** Enabling them would require same-origin privileges, which would also let HTML share origin with Obsidian instead of staying isolated.
-* **Context must be passed into the iframe, the iframe cannot reach out and pull in.** HTML can load browser-allowed network resources, but it cannot inspect Obsidian, other notes, or local vault files. So for example, the HTML page cannot access Obsidian themes, snippets, vault-relative asset paths, unless they are explicitly passed into the iframe context. Use inline CSS/assets, `data:` URLs, or browser-allowed HTTPS URLs instead.
+* **Context must be passed into the iframe, the iframe cannot reach out and pull in.** HTML receives curated theme tokens, but cannot inspect Obsidian, other notes, snippets, or local vault files. Use inline CSS/assets, `data:` URLs, or browser-allowed HTTPS URLs instead of vault-relative asset paths.
 
 ## Feedback / Support
 
diff --git a/docs/handoffs/css-theme-tokens.md b/docs/handoffs/css-theme-tokens.md
@@ -0,0 +1,18 @@
+# CSS Theme Tokens Handoff
+
+Issue: https://github.com/smcllns/obsidian-plugin-html-docs/issues/5
+
+Implemented shape:
+- HTML Docs appends a one-way `<style data-html-docs-theme>` block to each rendered HTML blob's `<head>`.
+- The iframe sandbox stays unchanged: `allow-scripts allow-popups allow-forms`, no `allow-same-origin`.
+- The stable public CSS contract is:
+  `--obsidian-color-scheme`, `--obsidian-bg`, `--obsidian-bg-2`, `--obsidian-text`, `--obsidian-text-muted`,
+  `--obsidian-accent`, `--obsidian-border`, `--obsidian-font`, `--obsidian-font-mono`.
+- Source values are read from Obsidian's computed styles and resolved through a temporary parent-side probe so iframe values do not depend on parent-only `var(...)` references.
+- Open HTML tabs and embeds re-render when the parent `body` theme class changes or Obsidian emits `css-change`.
+- Injection uses `DOMParser` instead of regex so `<head>` text inside comments/scripts is not treated as document structure.
+
+Validation notes:
+- `npm test` covers token injection in tab, markdown embed, and Canvas embed modes while preserving cross-origin iframe isolation.
+- `npm test` also flips parent `theme-light`/`theme-dark` classes and verifies the open HTML tab re-renders with the opposite injected `color-scheme`.
+- A live `obsidian-cli` probe also verified the real Obsidian theme toggle path: injected `color-scheme` changed from `light` to `dark`, then the original light theme was restored.
diff --git a/main.ts b/main.ts
@@ -34,19 +34,94 @@ interface RenderOptions {
 	heightPx?: number | null;
 }
 
+interface ThemeToken {
+	target: string;
+	source: string;
+	probeProperty?: string;
+	fallback?: (styles: CSSStyleDeclaration) => string;
+}
+
 type OpenLinkText = (
 	linktext: string,
 	sourcePath: string,
 	newLeaf?: PaneType | boolean,
 	openViewState?: OpenViewState,
 ) => Promise<void>;
 
+const OBSIDIAN_THEME_TOKENS: ThemeToken[] = [
+	{ target: "--obsidian-bg", source: "--background-primary", probeProperty: "background-color" },
+	{ target: "--obsidian-bg-2", source: "--background-secondary", probeProperty: "background-color" },
+	{ target: "--obsidian-text", source: "--text-normal", probeProperty: "color" },
+	{ target: "--obsidian-text-muted", source: "--text-muted", probeProperty: "color" },
+	{ target: "--obsidian-accent", source: "--interactive-accent", probeProperty: "background-color" },
+	{ target: "--obsidian-border", source: "--background-modifier-border", probeProperty: "border-top-color" },
+	{ target: "--obsidian-font", source: "--font-text", probeProperty: "font-family", fallback: (styles) => styles.fontFamily },
+	{ target: "--obsidian-font-mono", source: "--font-monospace", probeProperty: "font-family" },
+];
+
 function parseDimension(value: string | null): number | null {
 	if (!value) return null;
 	const parsed = Number.parseInt(value, 10);
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
 }
 
+function getColorScheme(doc: Document): "light" | "dark" {
+	if (doc.body.classList.contains("theme-dark")) return "dark";
+	if (doc.body.classList.contains("theme-light")) return "light";
+	return doc.defaultView?.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function sanitizeCssValue(value: string): string {
+	const trimmed = value.trim();
+	if (!trimmed || /[{};]/.test(trimmed) || /<\/style/i.test(trimmed)) return "";
+	return trimmed.replace(/\s+/g, " ");
+}
+
+function resolveThemeToken(doc: Document, styles: CSSStyleDeclaration, token: ThemeToken): string {
+	const sourceValue = styles.getPropertyValue(token.source).trim();
+	if (!sourceValue) return sanitizeCssValue(token.fallback?.(styles) ?? "");
+	if (!token.probeProperty) return sanitizeCssValue(sourceValue);
+
+	const probe = doc.createElement("div");
+	probe.style.setProperty(token.probeProperty, `var(${token.source})`);
+	doc.body.appendChild(probe);
+	const resolved = doc.defaultView?.getComputedStyle(probe).getPropertyValue(token.probeProperty) ?? "";
+	probe.remove();
+	return sanitizeCssValue(resolved || sourceValue);
+}
+
+function buildThemeStyle(doc: Document): string {
+	const styles = doc.defaultView?.getComputedStyle(doc.body);
+	if (!styles) throw new Error("HTML Docs: unable to read Obsidian theme styles.");
+
+	const colorScheme = getColorScheme(doc);
+	const declarations = [`color-scheme: ${colorScheme};`, `--obsidian-color-scheme: ${colorScheme};`];
+	for (const token of OBSIDIAN_THEME_TOKENS) {
+		const value = resolveThemeToken(doc, styles, token);
+		if (value) declarations.push(`${token.target}: ${value};`);
+	}
+
+	return `:root {\n\t${declarations.join("\n\t")}\n}`;
+}
+
+function serializeDoctype(doctype: DocumentType | null): string {
+	if (!doctype) return "";
+	let serialized = `<!doctype ${doctype.name}`;
+	if (doctype.publicId) serialized += ` PUBLIC "${doctype.publicId}"`;
+	if (doctype.systemId) serialized += `${doctype.publicId ? "" : " SYSTEM"} "${doctype.systemId}"`;
+	return `${serialized}>`;
+}
+
+function injectThemeStyle(html: string, themeStyle: string): string {
+	const parsed = new DOMParser().parseFromString(html, "text/html");
+	const style = parsed.createElement("style");
+	style.setAttribute("data-html-docs-theme", "");
+	style.textContent = themeStyle;
+	parsed.head.appendChild(style);
+	const doctype = serializeDoctype(parsed.doctype);
+	return `${doctype ? `${doctype}\n` : ""}${parsed.documentElement.outerHTML}`;
+}
+
 function renderSandboxedHtml(contentEl: HTMLElement, html: string, options: RenderOptions): () => void {
 	contentEl.empty();
 	contentEl.addClass("html-docs-container");
@@ -61,7 +136,8 @@ function renderSandboxedHtml(contentEl: HTMLElement, html: string, options: Rend
 	// the page. The sandbox attribute still gives the document an
 	// opaque origin regardless of URL scheme, so isolation from
 	// Obsidian and the vault is preserved.
-	const blobUrl = URL.createObjectURL(new Blob([html], { type: "text/html" }));
+	const htmlWithTheme = injectThemeStyle(html, buildThemeStyle(contentEl.ownerDocument));
+	const blobUrl = URL.createObjectURL(new Blob([htmlWithTheme], { type: "text/html" }));
 
 	// Build the iframe fully detached so the browser never observes it
 	// without the sandbox attribute. Inserting first, then setting
@@ -90,6 +166,7 @@ function renderSandboxedHtml(contentEl: HTMLElement, html: string, options: Rend
 
 class HtmlView extends FileView {
 	private cleanupHtml: (() => void) | null = null;
+	private renderVersion = 0;
 
 	getViewType(): string {
 		return VIEW_TYPE_HTML;
@@ -104,15 +181,27 @@ class HtmlView extends FileView {
 	}
 
 	async onLoadFile(file: TFile): Promise<void> {
-		const content = await this.app.vault.cachedRead(file);
-		this.render(content);
+		await this.readAndRender(file);
 	}
 
 	async onUnloadFile(_file: TFile): Promise<void> {
+		this.renderVersion++;
 		this.cleanupHtml?.();
 		this.cleanupHtml = null;
 	}
 
+	async refreshTheme(): Promise<void> {
+		if (!this.file) return;
+		await this.readAndRender(this.file);
+	}
+
+	private async readAndRender(file: TFile): Promise<void> {
+		const version = ++this.renderVersion;
+		const content = await this.app.vault.cachedRead(file);
+		if (version !== this.renderVersion || this.file !== file || !this.contentEl.isConnected) return;
+		this.render(content);
+	}
+
 	private render(html: string): void {
 		this.cleanupHtml?.();
 		this.cleanupHtml = renderSandboxedHtml(this.contentEl, html, { mode: "view" });
@@ -121,6 +210,8 @@ class HtmlView extends FileView {
 
 class HtmlEmbed extends Component {
 	private cleanupHtml: (() => void) | null = null;
+	private renderVersion = 0;
+	private unloaded = false;
 
 	constructor(
 		private contentEl: HTMLElement,
@@ -131,7 +222,11 @@ class HtmlEmbed extends Component {
 	}
 
 	async loadFile(): Promise<void> {
+		if (this.unloaded) return;
+		this.plugin.trackHtmlEmbed(this);
+		const version = ++this.renderVersion;
 		const content = await this.plugin.app.vault.cachedRead(this.file);
+		if (this.unloaded || version !== this.renderVersion) return;
 		this.cleanupHtml?.();
 		this.cleanupHtml = renderSandboxedHtml(this.contentEl, content, {
 			mode: "embed",
@@ -140,20 +235,32 @@ class HtmlEmbed extends Component {
 		});
 	}
 
+	async refreshTheme(): Promise<void> {
+		await this.loadFile();
+	}
+
 	onunload(): void {
+		this.unloaded = true;
+		this.renderVersion++;
+		this.plugin.untrackHtmlEmbed(this);
 		this.cleanupHtml?.();
 		this.cleanupHtml = null;
 	}
 }
 
 export default class HtmlDocsPlugin extends Plugin {
+	private readonly htmlEmbeds = new Set<HtmlEmbed>();
+	private currentColorScheme: "light" | "dark" | null = null;
+	private themeRefreshTimeout: number | null = null;
+
 	async onload(): Promise<void> {
 		this.registerView(
 			VIEW_TYPE_HTML,
 			(leaf: WorkspaceLeaf) => new HtmlView(leaf),
 		);
 		this.registerExtensions(["html"], VIEW_TYPE_HTML);
 		this.registerExistingHtmlTabNavigation();
+		this.registerThemeRefresh();
 
 		const embedRegistry = (this.app as unknown as AppWithEmbedRegistry).embedRegistry;
 		if (!embedRegistry) {
@@ -175,6 +282,53 @@ export default class HtmlDocsPlugin extends Plugin {
 		}
 	}
 
+	trackHtmlEmbed(embed: HtmlEmbed): void {
+		this.htmlEmbeds.add(embed);
+	}
+
+	untrackHtmlEmbed(embed: HtmlEmbed): void {
+		this.htmlEmbeds.delete(embed);
+	}
+
+	private registerThemeRefresh(): void {
+		const doc = this.app.workspace.containerEl.ownerDocument;
+		this.currentColorScheme = getColorScheme(doc);
+		const refreshIfColorSchemeChanged = () => {
+			const nextColorScheme = getColorScheme(doc);
+			if (nextColorScheme === this.currentColorScheme) return;
+			this.currentColorScheme = nextColorScheme;
+			this.scheduleThemeRefresh();
+		};
+
+		const observer = new MutationObserver(refreshIfColorSchemeChanged);
+		observer.observe(doc.body, {
+			attributes: true,
+			attributeFilter: ["class"],
+		});
+		this.registerEvent(this.app.workspace.on("css-change", () => this.scheduleThemeRefresh()));
+		this.register(() => {
+			observer.disconnect();
+			if (this.themeRefreshTimeout !== null) window.clearTimeout(this.themeRefreshTimeout);
+		});
+	}
+
+	private scheduleThemeRefresh(): void {
+		if (this.themeRefreshTimeout !== null) window.clearTimeout(this.themeRefreshTimeout);
+		this.themeRefreshTimeout = window.setTimeout(() => {
+			this.themeRefreshTimeout = null;
+			void this.refreshOpenHtmlDocuments();
+		}, 50);
+	}
+
+	private async refreshOpenHtmlDocuments(): Promise<void> {
+		const refreshes: Promise<void>[] = [];
+		this.app.workspace.iterateAllLeaves((leaf) => {
+			if (leaf.view instanceof HtmlView) refreshes.push(leaf.view.refreshTheme());
+		});
+		for (const embed of this.htmlEmbeds) refreshes.push(embed.refreshTheme());
+		await Promise.all(refreshes);
+	}
+
 	private registerExistingHtmlTabNavigation(): void {
 		const workspace = this.app.workspace;
 		const openLinkText = workspace.openLinkText.bind(workspace) as OpenLinkText;
diff --git a/test/fixture.html b/test/fixture.html
@@ -195,6 +195,27 @@ <h2>Known not to work (by design)</h2>
     d.style.cssText = 'height:36px;background:linear-gradient(90deg,#6366f1,#22d3ee,#22c55e);border-radius:6px';
     card('render', 'CSS gradients', 'pass', '', d);
   })();
+  (function () {
+    const root = getComputedStyle(document.documentElement);
+    const required = ['--obsidian-color-scheme', '--obsidian-bg', '--obsidian-text', '--obsidian-accent', '--obsidian-font'];
+    const themeStyle = document.querySelector('style[data-html-docs-theme]');
+    const themeStyleText = themeStyle ? themeStyle.textContent || '' : '';
+    const missing = required.filter((name) => !root.getPropertyValue(name).trim());
+    const unresolved = required.filter((name) => root.getPropertyValue(name).includes('var('));
+    const colorScheme = root.colorScheme.trim();
+    const demo = document.createElement('div');
+    demo.style.cssText = 'padding:10px;border:1px solid var(--obsidian-border);background:var(--obsidian-bg);color:var(--obsidian-text);font-family:var(--obsidian-font);border-radius:6px';
+    demo.textContent = 'Obsidian theme token sample';
+    const hasInjectedScheme = /color-scheme:\s*(light|dark);/.test(themeStyleText);
+    const ok = !!themeStyle && missing.length === 0 && unresolved.length === 0 && hasInjectedScheme;
+    card(
+      'render',
+      'Obsidian theme tokens',
+      ok ? 'pass' : 'fail',
+      ok ? 'color-scheme: ' + colorScheme : 'missing/unresolved: ' + ([...missing, ...unresolved].join(', ') || 'color-scheme'),
+      demo,
+    );
+  })();
   (function () {
     const d = document.createElement('div');
     d.style.cssText = 'display:flex;gap:8px;align-items:center';
diff --git a/test/test.sh b/test/test.sh
