emdash 0.11.1 → 0.13.0

package/src/cli/wxr/parser.ts

@@ -75,7 +75,202 @@ export interface WxrPost {
 	tags: string[];
 	/** Custom taxonomy assignments beyond categories/tags */
 	customTaxonomies?: Map<string, string[]>;
+	/**
+	 * Display labels for per-item category/tag/custom-taxonomy assignments,
+	 * captured from `<category domain="..." nicename="...">Label</category>`
+	 * text content. Used by the importer to back-fill term labels when a
+	 * `<wp:category>` or `<wp:tag>` block wasn't present at the top of the
+	 * WXR (older / hand-edited exports). Keyed by
+	 * `${normalisedTaxonomy}\u0000${slug}` so categories and tags don't
+	 * collide.
+	 */
+	taxonomyLabels?: Map<string, string>;
 	meta: Map<string, string>;
+	/**
+	 * BCP 47 locale code extracted from a detected multilingual plugin
+	 * (WPML's `_icl_lang_code` or Polylang's per-post language taxonomy).
+	 * Absent when no per-post locale could be determined.
+	 */
+	locale?: string;
+	/**
+	 * Source-side translation group ID extracted from a detected multilingual
+	 * plugin (WPML's `trid` / `_icl_translation_id`, or a synthesized id derived
+	 * from Polylang's `_translations` meta). Posts sharing a `translationGroup`
+	 * are translations of one another. The string is opaque -- consumers use it
+	 * only as a key to link posts.
+	 */
+	translationGroup?: string;
+}
+
+/**
+ * WPML stores per-post language in postmeta as `_icl_lang_code`. The shared
+ * translation id is `trid` (this is the group ID -- every translation of the
+ * same content shares it). `_icl_translation_id` exists on some exports too
+ * but is a per-translation row id from `wp_icl_translations`, NOT the group
+ * id, so it must NOT be used as the group key. We accept it only when `trid`
+ * is absent and trust the export to be internally consistent (the only case
+ * where that's reasonable is single-post exports with no real grouping).
+ *
+ * See `wpml_element_trid` in the WPML hook docs: "the ID of the translation
+ * group".
+ */
+const WPML_LOCALE_META_KEYS = ["_icl_lang_code"] as const;
+const WPML_TRID_META_KEYS = ["trid", "_icl_translation_id"] as const;
+
+/**
+ * Polylang stores per-post language in postmeta as `_locale` on newer
+ * exports. The actual language taxonomy assignment lives on
+ * `customTaxonomies.language`, which we use as a fallback. Translation
+ * grouping is encoded in `_translations` as a serialized PHP map of
+ * `{ lang_code => post_id }`; we synthesize a stable group key from the
+ * sorted IDs so every member of the group resolves to the same string.
+ */
+const POLYLANG_LOCALE_META_KEY = "_locale";
+const POLYLANG_TRANSLATIONS_META_KEY = "_translations";
+const POLYLANG_LANG_TAXONOMY = "language";
+
+/**
+ * Extract a list of post-IDs from Polylang's `_translations` PHP-serialized
+ * value. The format we care about is roughly:
+ *
+ *   a:2:{s:2:"en";i:1;s:2:"ar";i:7;}
+ *
+ * We don't need to round-trip the PHP value -- we just need a stable group
+ * key shared by every translation of the same content. Concatenating the
+ * sorted IDs gives us exactly that: every post in the group derives the
+ * same key from its own copy of `_translations`.
+ *
+ * Naïve `/i:(\d+);/g` would also match `i:N;` literals embedded INSIDE
+ * string values (e.g. `s:11:"i:42;hello";`), which would silently corrupt
+ * the group key. We walk the serialized blob token-by-token instead.
+ *
+ * PHP serializes `s:LEN:"..."` with LEN counted in BYTES, not characters
+ * (UTF-8 byte length). JS string positions are UTF-16 code units, so we
+ * encode to bytes via `TextEncoder` and walk byte offsets. Single-byte-only
+ * inputs (the common case for Polylang's `_translations` which only stores
+ * ASCII locale codes) take the same path; the encoder is cheap.
+ */
+function polylangTranslationGroupFromMeta(serialized: string): string | undefined {
+	// Operate on the UTF-8 byte view so `s:LEN:` advances the right number
+	// of bytes when the payload contains multibyte characters.
+	const encoder = new TextEncoder();
+	const bytes = encoder.encode(serialized);
+	const decoder = new TextDecoder("utf-8");
+
+	const ids: number[] = [];
+	let i = 0;
+	const n = bytes.length;
+	const CHAR_S = 0x73; // 's'
+	const CHAR_I = 0x69; // 'i'
+	const CHAR_COLON = 0x3a; // ':'
+	const CHAR_SEMI = 0x3b; // ';'
+	const CHAR_QUOTE = 0x22; // '"'
+
+	const indexOf = (byte: number, from: number): number => {
+		for (let k = from; k < n; k++) {
+			if (bytes[k] === byte) return k;
+		}
+		return -1;
+	};
+
+	while (i < n) {
+		const ch = bytes[i];
+		if (ch === CHAR_S && bytes[i + 1] === CHAR_COLON) {
+			// s:LEN:"...";  — skip the entire string value: the LEN digits,
+			// the opening quote, the payload of exactly LEN bytes, the
+			// closing quote, and the trailing semicolon.
+			const lenStart = i + 2;
+			const lenEnd = indexOf(CHAR_COLON, lenStart);
+			if (lenEnd === -1) break;
+			const lenText = decoder.decode(bytes.slice(lenStart, lenEnd));
+			const len = Number.parseInt(lenText, 10);
+			if (!Number.isFinite(len) || len < 0) {
+				i = lenEnd + 1;
+				continue;
+			}
+			// lenEnd+1 should be `"`. Defensively check before advancing
+			// over the payload -- a malformed input shouldn't crash the
+			// import; just skip past this token.
+			if (bytes[lenEnd + 1] !== CHAR_QUOTE) {
+				i = lenEnd + 1;
+				continue;
+			}
+			const payloadStart = lenEnd + 2;
+			const afterPayload = payloadStart + len;
+			// afterPayload should point at the closing `"`; +2 past `";`.
+			i = afterPayload + 2;
+			continue;
+		}
+		if (ch === CHAR_I && bytes[i + 1] === CHAR_COLON) {
+			const valStart = i + 2;
+			const valEnd = indexOf(CHAR_SEMI, valStart);
+			if (valEnd === -1) break;
+			const idText = decoder.decode(bytes.slice(valStart, valEnd));
+			const id = Number.parseInt(idText, 10);
+			if (Number.isFinite(id)) ids.push(id);
+			i = valEnd + 1;
+			continue;
+		}
+		// Any other token (a:LEN:{...}, b:0;, N;, {, }, :, ;, etc.) -- just
+		// advance one byte. We only care about integer literals; everything
+		// else is structural.
+		i++;
+	}
+	if (ids.length === 0) return undefined;
+	const sorted = [...new Set(ids)].toSorted((a, b) => a - b);
+	return `pll:${sorted.join(",")}`;
+}
+
+/**
+ * Promote multilingual-plugin metadata from `post.meta` and
+ * `post.customTaxonomies` into `post.locale` / `post.translationGroup`.
+ *
+ * Called once per `<item>` after all of its `<wp:postmeta>` and per-item
+ * `<category>` entries have been parsed. Safe to call on posts that have no
+ * multilingual metadata -- it's a no-op in that case.
+ *
+ * WPML wins over Polylang when both are present (they shouldn't co-exist on
+ * the same site, but defensive precedence avoids ambiguity).
+ */
+function promoteI18nMetadata(post: WxrPost): void {
+	// WPML
+	for (const key of WPML_LOCALE_META_KEYS) {
+		const value = post.meta.get(key);
+		if (value) {
+			post.locale = value;
+			break;
+		}
+	}
+	for (const key of WPML_TRID_META_KEYS) {
+		const value = post.meta.get(key);
+		if (value) {
+			post.translationGroup = `wpml:${value}`;
+			break;
+		}
+	}
+
+	// Polylang fallbacks (only fill what WPML didn't already provide)
+	if (!post.locale) {
+		const pllLocale = post.meta.get(POLYLANG_LOCALE_META_KEY);
+		if (pllLocale) {
+			post.locale = pllLocale;
+		} else {
+			// Polylang's primary language signal is a taxonomy assignment
+			// on the `language` custom taxonomy. The nicename is the locale
+			// code (e.g. "en", "ar").
+			const langTaxonomy = post.customTaxonomies?.get(POLYLANG_LANG_TAXONOMY);
+			const firstLang = langTaxonomy?.[0];
+			if (firstLang) post.locale = firstLang;
+		}
+	}
+
+	if (!post.translationGroup) {
+		const pllTranslations = post.meta.get(POLYLANG_TRANSLATIONS_META_KEY);
+		if (pllTranslations) {
+			const group = polylangTranslationGroupFromMeta(pllTranslations);
+			if (group) post.translationGroup = group;
+		}
+	}
 }
 
 export interface WxrAttachment {
@@ -156,6 +351,32 @@ function attrStr(attr: string | { value: string } | undefined): string {
 	return "";
 }
 
+/**
+ * Normalise a `<category domain="...">` value to the matching EmDash
+ * taxonomy name so per-item label captures can be retrieved later using
+ * the same key.
+ */
+function normaliseDomain(domain: string): string {
+	if (domain === "post_tag") return "tag";
+	return domain;
+}
+
+/**
+ * Persist the human label of a `<category>` text body keyed by the
+ * normalised `(taxonomy, slug)` pair. Skips trivial labels that equal the
+ * slug (no information vs. just storing the slug).
+ */
+function captureItemCategoryLabel(
+	item: WxrPost,
+	pair: { domain: string; nicename: string },
+	label: string,
+): void {
+	if (!label || label === pair.nicename) return;
+	if (!item.taxonomyLabels) item.taxonomyLabels = new Map();
+	const key = `${normaliseDomain(pair.domain)}\u0000${pair.nicename}`;
+	if (!item.taxonomyLabels.has(key)) item.taxonomyLabels.set(key, label);
+}
+
 /** Type guard for complete WxrTerm (all required fields present) */
 function isCompleteWxrTerm(term: Partial<WxrTerm>): term is WxrTerm {
 	return (
@@ -194,6 +415,11 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 		let currentAuthor: WxrAuthor | null = null;
 		let currentTerm: Partial<WxrTerm> | null = null;
 		let currentMetaKey = "";
+		// Per-item category element currently open. Captured at opentag so
+		// we can pair the text body (the human label) with the slug when
+		// closetag fires. WXR per-item category elements look like:
+		//   <category domain="category" nicename="hello-world">Hello World</category>
+		let pendingItemCategory: { domain: string; nicename: string } | null = null;
 
 		// Track nav_menu_item posts for post-processing
 		const navMenuItemPosts: WxrPost[] = [];
@@ -229,8 +455,10 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 				const nicename = attrStr(node.attributes.nicename);
 				if (domain === "category" && nicename) {
 					currentItem.categories.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain === "post_tag" && nicename) {
 					currentItem.tags.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain && nicename && domain !== "category" && domain !== "post_tag") {
 					// Custom taxonomy (including nav_menu)
 					if (!currentItem.customTaxonomies) {
@@ -239,6 +467,7 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 					const existing = currentItem.customTaxonomies.get(domain) || [];
 					existing.push(nicename);
 					currentItem.customTaxonomies.set(domain, existing);
+					pendingItemCategory = { domain, nicename };
 				}
 			}
 		});
@@ -369,6 +598,18 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 							};
 						}
 						break;
+					case "category":
+						// Per-item category text body = the human label for
+						// the term (`<category nicename="hello-world">Hello
+						// World</category>`). Backfilling from per-item
+						// elements (older / hand-edited exports without top-
+						// level `<wp:category>` blocks) lands the right label
+						// instead of slug-cased nonsense.
+						if (pendingItemCategory && text) {
+							captureItemCategoryLabel(currentItem, pendingItemCategory, text);
+						}
+						pendingItemCategory = null;
+						break;
 					case "item":
 						// End of item - categorize and store
 						if (currentAttachment) {
@@ -379,6 +620,10 @@ export function parseWxr(stream: Readable): Promise<WxrData> {
 							navMenuItemPosts.push(currentItem);
 							data.posts.push(currentItem);
 						} else if (currentItem.postType !== "attachment") {
+							// Promote multilingual plugin metadata before storing.
+							// All postmeta and per-item categories are parsed by the time
+							// the closing </item> tag fires, so it's safe to inspect them.
+							promoteI18nMetadata(currentItem);
 							// Store all non-attachment post types (posts, pages, custom post types)
 							data.posts.push(currentItem);
 						}
@@ -551,6 +796,9 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 		let currentAuthor: WxrAuthor | null = null;
 		let currentTerm: Partial<WxrTerm> | null = null;
 		let currentMetaKey = "";
+		// Per-item category element currently open (see streaming-parser
+		// counterpart above for rationale).
+		let pendingItemCategory: { domain: string; nicename: string } | null = null;
 
 		// Track nav_menu_item posts for post-processing
 		const navMenuItemPosts: WxrPost[] = [];
@@ -586,8 +834,10 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 				const nicename = attrStr(node.attributes.nicename);
 				if (domain === "category" && nicename) {
 					currentItem.categories.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain === "post_tag" && nicename) {
 					currentItem.tags.push(nicename);
+					pendingItemCategory = { domain, nicename };
 				} else if (domain && nicename && domain !== "category" && domain !== "post_tag") {
 					// Custom taxonomy (including nav_menu)
 					if (!currentItem.customTaxonomies) {
@@ -596,6 +846,7 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 					const existing = currentItem.customTaxonomies.get(domain) || [];
 					existing.push(nicename);
 					currentItem.customTaxonomies.set(domain, existing);
+					pendingItemCategory = { domain, nicename };
 				}
 			}
 		};
@@ -728,6 +979,14 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 							currentItem.meta.set(currentMetaKey, text);
 						}
 						break;
+					case "category":
+						// Per-item category text body = human label. See
+						// streaming-parser counterpart for rationale.
+						if (pendingItemCategory && text) {
+							captureItemCategoryLabel(currentItem, pendingItemCategory, text);
+						}
+						pendingItemCategory = null;
+						break;
 					case "item":
 						// End of item - categorize and store
 						if (currentAttachment) {
@@ -738,6 +997,10 @@ export function parseWxrString(xml: string): Promise<WxrData> {
 							navMenuItemPosts.push(currentItem);
 							data.posts.push(currentItem);
 						} else if (currentItem.postType !== "attachment") {
+							// Promote multilingual plugin metadata before storing.
+							// All postmeta and per-item categories are parsed by the time
+							// the closing </item> tag fires, so it's safe to inspect them.
+							promoteI18nMetadata(currentItem);
 							data.posts.push(currentItem);
 						}
 						currentItem = null;

package/src/client/index.ts

@@ -737,10 +737,11 @@ export class EmDashClient {
 		if (options?.cursor) params.set("cursor", options.cursor);
 
 		const qs = params.toString();
-		return this.request<ListResult<Term>>(
+		const data = await this.request<{ terms: Term[] }>(
 			"GET",
 			`/taxonomies/${encodeURIComponent(taxonomy)}/terms${qs ? `?${qs}` : ""}`,
 		);
+		return { items: data.terms };
 	}
 
 	/** Create a taxonomy term */

package/src/components/EmDashHead.astro

@@ -3,8 +3,11 @@
  * Renders base SEO metadata, plugin-contributed metadata, and trusted head fragments.
  *
  * Base SEO metadata (meta tags, OG, Twitter Card, canonical, JSON-LD) is generated
- * from the page context's seo/articleMeta/siteName fields. Plugin contributions
- * come after, so they can override base tags via first-wins dedup in resolvePageMetadata().
+ * from the page context's seo/articleMeta/siteName fields. Contributions are
+ * composed in the order `[...plugin, ...site, ...base]` and resolved by
+ * `resolvePageMetadata()` with first-wins dedup. Plugins sit at the front of
+ * the array, so for any given key plugin contributions override site-level
+ * ones, which override base ones.
  *
  * Usage:
  * ```astro
@@ -23,6 +26,7 @@ import {
 import { renderSiteIdentity } from "../page/site-identity.js";
 import { getPageRuntime } from "../page/index.js";
 import { getSiteSettings } from "../settings/index.js";
+import { absolutizeMediaUrl } from "../page/absolute-url.js";
 
 interface Props {
 	page: PublicPageContext;
@@ -31,9 +35,6 @@ interface Props {
 const { page } = Astro.props;
 const runtime = getPageRuntime(Astro.locals as Record<string, unknown>);
 
-// Base SEO contributions from page context (always generated)
-const baseContributions: PageMetadataContribution[] = generateBaseSeoContributions(page);
-
 let metadataHtml = "";
 let siteIdentityHtml = "";
 let fragmentsHtml = "";
@@ -56,6 +57,25 @@ if (runtime) {
 		runtime.collectPageFragments(page),
 	]);
 
+	// Site-level default OG image: applied per-page in base contributions
+	// rather than emitted unconditionally, so per-content images still win.
+	// `resolveMediaReference` populates `.url` on read; only the mediaId is
+	// stored, so an empty/orphaned reference safely yields undefined here.
+	//
+	// Absolutize so `og:image` / `twitter:image` / JSON-LD `image` carry a
+	// fully-qualified URL: many social-card scrapers (Slack, LinkedIn) refuse
+	// to follow relative paths even when the rest of the page provides
+	// canonical context.
+	const defaultOgImage = absolutizeMediaUrl(
+		siteSettings.seo?.defaultOgImage?.url,
+		siteSettings.url,
+		page,
+	);
+	const baseContributions: PageMetadataContribution[] = generateBaseSeoContributions(
+		page,
+		defaultOgImage,
+	);
+
 	const siteContributions = generateSiteSeoContributions(siteSettings.seo);
 	const allContributions = [...pluginContributions, ...siteContributions, ...baseContributions];
 	const resolved = resolvePageMetadata(allContributions);
@@ -64,6 +84,7 @@ if (runtime) {
 	fragmentsHtml = renderFragments(fragments, "head");
 } else {
 	// No runtime (EmDash not initialized) — still render base SEO
+	const baseContributions: PageMetadataContribution[] = generateBaseSeoContributions(page);
 	const resolved = resolvePageMetadata(baseContributions);
 	metadataHtml = renderPageMetadata(resolved);
 }