@pure-ds/core 0.6.10 → 0.6.11

package/src/js/pds-live-manager/tailwind-conversion-rules.json

@@ -0,0 +1,383 @@
+{
+  "version": "tw2pds-layout-v4",
+  "summary": "Deterministic Tailwind→PDS conversion rules focused on layout intent, semantic primitive mapping, and richer import-* fallback coverage.",
+  "governance": [
+    {
+      "id": "layout.utilities.grid",
+      "controls": ["grid", "grid-cols-*", "grid-auto-*"],
+      "note": "When false, grid mappings are skipped."
+    },
+    {
+      "id": "layout.utilities.flex",
+      "controls": ["flex", "flex-*", "items-*", "justify-*", "grow"],
+      "note": "When false, flex mappings are skipped."
+    },
+    {
+      "id": "layout.utilities.spacing",
+      "controls": ["gap-*", "stack-*"],
+      "note": "When false, spacing mappings are skipped."
+    },
+    {
+      "id": "layout.utilities.container",
+      "controls": ["container", "max-w-*"],
+      "note": "When false, container mappings are skipped."
+    }
+  ],
+  "nonPdsClassPatterns": ["^group(?:[/:].*)?$", "^layout-container$"],
+  "neverFallbackTags": ["table", "thead", "tbody", "tfoot", "tr", "th", "td", "caption", "colgroup", "col"],
+  "directMappings": [
+    { "id": "layout.flex.base", "tw": "flex", "pds": ["flex"], "gate": "flex" },
+    { "id": "layout.flex.inline", "tw": "inline-flex", "pds": ["flex"], "gate": "flex" },
+    { "id": "layout.flex.row", "tw": "flex-row", "pds": ["flex-row"], "gate": "flex" },
+    { "id": "layout.flex.col", "tw": "flex-col", "pds": ["flex-col"], "gate": "flex" },
+    { "id": "layout.flex.wrap", "tw": "flex-wrap", "pds": ["flex-wrap"], "gate": "flex" },
+    { "id": "layout.flex.grow", "tw": "grow", "pds": ["grow"], "gate": "flex" },
+    { "id": "layout.flex.grow.tw", "tw": "flex-grow", "pds": ["grow"], "gate": "flex" },
+    { "id": "layout.flex.grow1", "tw": "flex-1", "pds": ["grow"], "gate": "flex" },
+    { "id": "layout.items.start", "tw": "items-start", "pds": ["items-start"], "gate": "flex" },
+    { "id": "layout.items.center", "tw": "items-center", "pds": ["items-center"], "gate": "flex" },
+    { "id": "layout.items.end", "tw": "items-end", "pds": ["items-end"], "gate": "flex" },
+    { "id": "layout.items.stretch", "tw": "items-stretch", "pds": ["items-stretch"], "gate": "flex" },
+    { "id": "layout.items.baseline", "tw": "items-baseline", "pds": ["items-baseline"], "gate": "flex" },
+    { "id": "layout.justify.start", "tw": "justify-start", "pds": ["justify-start"], "gate": "flex" },
+    { "id": "layout.justify.center", "tw": "justify-center", "pds": ["justify-center"], "gate": "flex" },
+    { "id": "layout.justify.end", "tw": "justify-end", "pds": ["justify-end"], "gate": "flex" },
+    { "id": "layout.justify.between", "tw": "justify-between", "pds": ["justify-between"], "gate": "flex" },
+    { "id": "layout.justify.around", "tw": "justify-around", "pds": ["justify-around"], "gate": "flex" },
+    { "id": "layout.justify.evenly", "tw": "justify-evenly", "pds": ["justify-evenly"], "gate": "flex" },
+    { "id": "layout.grid.base", "tw": "grid", "pds": ["grid"], "gate": "grid" },
+    { "id": "layout.grid.cols.1", "tw": "grid-cols-1", "pds": ["grid-cols-1"], "gate": "grid" },
+    { "id": "layout.grid.cols.2", "tw": "grid-cols-2", "pds": ["grid-cols-2"], "gate": "grid" },
+    { "id": "layout.grid.cols.3", "tw": "grid-cols-3", "pds": ["grid-cols-3"], "gate": "grid" },
+    { "id": "layout.grid.cols.4", "tw": "grid-cols-4", "pds": ["grid-cols-4"], "gate": "grid" },
+    { "id": "layout.grid.cols.6", "tw": "grid-cols-6", "pds": ["grid-cols-6"], "gate": "grid" },
+    { "id": "layout.container", "tw": "container", "pds": ["container"], "gate": "container" },
+    { "id": "intent.surface.shadow", "tw": "shadow", "pds": ["surface-elevated"] },
+    { "id": "intent.surface.shadow-md", "tw": "shadow-md", "pds": ["surface-elevated"] },
+    { "id": "intent.surface.shadow-lg", "tw": "shadow-lg", "pds": ["surface-elevated"] },
+    { "id": "intent.surface.base", "tw": "bg-white", "pds": ["surface-base"] },
+    { "id": "typography.align.center", "tw": "text-center", "pds": ["text-center"] },
+    { "id": "typography.align.left", "tw": "text-left", "pds": ["text-left"] },
+    { "id": "typography.align.right", "tw": "text-right", "pds": ["text-right"] },
+    { "id": "typography.text.muted.gray500", "tw": "text-gray-500", "pds": ["text-muted"] },
+    { "id": "typography.text.muted.slate500", "tw": "text-slate-500", "pds": ["text-muted"] }
+  ],
+  "ignoredPatterns": [
+    {
+      "id": "style.color",
+      "pattern": "^(?:text|from|to|via|decoration|accent|caret)-|^bg-(?!cover$|center$|no-repeat$)",
+      "reason": "Visual style token skipped in favor of semantic PDS styling."
+    },
+    {
+      "id": "style.radius-border-shadow",
+      "pattern": "^(?:rounded|ring|border|shadow|outline)-?",
+      "reason": "Surface/shape inferred at primitive level."
+    },
+    {
+      "id": "style.typography",
+      "pattern": "^(?:font|leading|tracking|uppercase|lowercase|capitalize)-?",
+      "reason": "Typography atomic utilities are skipped."
+    },
+    {
+      "id": "style.effects",
+      "pattern": "^(?:opacity|blur|backdrop|drop-shadow|mix-blend|filter)-",
+      "reason": "Visual effects skipped unless mapped to a PDS utility."
+    },
+    {
+      "id": "style.transitions",
+      "pattern": "^(?:transition|duration|ease|delay|animate)-",
+      "reason": "Motion is system-defined in PDS."
+    },
+    {
+      "id": "style.spacing.atomic",
+      "pattern": "^(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr)-",
+      "reason": "Atomic spacing skipped; structural spacing intent is mapped."
+    },
+    {
+      "id": "style.positioning.atomic",
+      "pattern": "^(?:absolute|relative|fixed|sticky|inset(?:-[xy])?|top|right|bottom|left|z|translate(?:-[xy])?|-translate-[xy])(?:-|$)",
+      "reason": "Atomic positioning/offset utilities are skipped so PDS primitives and layout utilities control placement."
+    }
+  ],
+  "intentRules": [
+    {
+      "id": "intent.layout.responsive-grid-to-auto",
+      "summary": "Collapse responsive grid-cols patterns (including base+md two-step patterns) to best-fit grid-auto-*"
+    },
+    {
+      "id": "intent.layout.mobile-stack",
+      "summary": "Map flex-col + md/lg:flex-row to mobile-stack"
+    },
+    {
+      "id": "intent.component.card",
+      "summary": "Infer card/surface classes from rounded+shadow+surface signals"
+    },
+    {
+      "id": "intent.component.card.normalize",
+      "summary": "Detect Tailwind card utility clusters and normalize them to PDS card and surface variants."
+    },
+    {
+      "id": "intent.component.button",
+      "summary": "Infer btn-primary / btn-outline / icon-only from CTA patterns"
+    },
+    {
+      "id": "intent.component.button.normalize",
+      "summary": "Prevents import-* style classes on button-like elements and applies PDS button variants/sizes."
+    },
+    {
+      "id": "intent.component.button.layout-grow",
+      "summary": "Preserve CTA row width intent on button-like elements by mapping w-full/flex-1 to grow."
+    },
+    {
+      "id": "intent.icon.color-preserve",
+      "summary": "Preserve icon color intent by mapping Tailwind text color utilities on icon-like elements to tokenized import-* classes."
+    },
+    {
+      "id": "intent.component.badge.normalize",
+      "summary": "Detects Tailwind badge/pill utility clusters and normalizes them to PDS badge primitives/variants."
+    },
+    {
+      "id": "intent.typography.heading-semantic",
+      "summary": "Removes Tailwind heading typography/color utilities so heading semantics and PDS defaults control typography."
+    },
+    {
+      "id": "intent.surface.footer-inverse",
+      "summary": "Use surface-inverse for footers with explicit background intent"
+    },
+    {
+      "id": "intent.typography.link-treatment",
+      "summary": "Apply minimal link treatment for hover/transition-tailwind anchors"
+    },
+    {
+      "id": "intent.typography.link-active-preserve",
+      "summary": "Preserve anchor text color intent (including active menu states) by mapping Tailwind text utilities to tokenized import-* classes."
+    },
+    {
+      "id": "intent.typography.metric-paragraph-to-div",
+      "summary": "Normalize metric display lines from paragraph tags to div tags to avoid default paragraph margins in compact stat layouts."
+    },
+    {
+      "id": "intent.typography.metric-pair-no-stack",
+      "summary": "When a compact metric container has two consecutive typography lines, remove stack-sm so spacing follows Tailwind preflight no-margin assumptions."
+    },
+    {
+      "id": "intent.typography.semantic-heading-from-scale",
+      "summary": "Map large bold typography scales (text-2xl/text-3xl/text-4xl) to semantic heading tags when possible."
+    },
+    {
+      "id": "intent.typography.bold-to-strong",
+      "summary": "Prefer semantic strong tags for bold inline text intent instead of utility-only font-weight classes."
+    },
+    {
+      "id": "intent.preflight.tailwind-runtime-detected",
+      "summary": "Detect Tailwind runtime CSS injection and translate key preflight intent"
+    },
+    {
+      "id": "intent.preflight.list-reset",
+      "summary": "Preserve Tailwind list-reset preflight behavior via scoped fallback class"
+    },
+    {
+      "id": "intent.preflight.anchor-reset",
+      "summary": "Preserve Tailwind anchor reset preflight behavior via scoped fallback class"
+    },
+    {
+      "id": "table.strict-tags.no-classes",
+      "summary": "Never emit classes for semantic table tags (table/thead/tbody/tfoot/tr/th/td/caption/colgroup/col)"
+    },
+    {
+      "id": "intent.form.nested-label",
+      "summary": "Convert sibling label+control pairs into nested labels"
+    },
+    {
+      "id": "fallback.import-style",
+      "summary": "Generate import-* classes + local style block for unmapped utility styles"
+    }
+  ],
+  "gapScaleMap": {
+    "gap-0": "gap-0",
+    "gap-1": "gap-xs",
+    "gap-2": "gap-sm",
+    "gap-3": "gap-sm",
+    "gap-4": "gap-md",
+    "gap-5": "gap-md",
+    "gap-6": "gap-lg",
+    "gap-7": "gap-lg",
+    "gap-8": "gap-xl",
+    "gap-10": "gap-xl",
+    "gap-12": "gap-xl"
+  },
+  "maxWidthMap": {
+    "max-w-xs": "max-w-sm",
+    "max-w-sm": "max-w-sm",
+    "max-w-md": "max-w-md",
+    "max-w-lg": "max-w-lg",
+    "max-w-xl": "max-w-xl",
+    "max-w-2xl": "max-w-xl",
+    "max-w-3xl": "max-w-xl",
+    "max-w-4xl": "max-w-xl",
+    "max-w-5xl": "max-w-xl",
+    "max-w-6xl": "max-w-xl",
+    "max-w-7xl": "max-w-xl"
+  },
+  "tailwindSizeScale": {
+    "0": "var(--spacing-0)",
+    "0.5": "0.125rem",
+    "1": "var(--spacing-1)",
+    "1.5": "0.375rem",
+    "2": "var(--spacing-2)",
+    "2.5": "0.625rem",
+    "3": "var(--spacing-3)",
+    "3.5": "0.875rem",
+    "4": "var(--spacing-4)",
+    "5": "var(--spacing-5)",
+    "6": "var(--spacing-6)",
+    "7": "var(--spacing-7)",
+    "8": "var(--spacing-8)",
+    "9": "var(--spacing-9)",
+    "10": "var(--spacing-10)",
+    "11": "var(--spacing-11)",
+    "12": "var(--spacing-12)",
+    "14": "3.5rem",
+    "16": "4rem",
+    "20": "5rem",
+    "24": "6rem",
+    "28": "7rem",
+    "32": "8rem",
+    "36": "9rem",
+    "40": "10rem",
+    "48": "12rem"
+  },
+  "tailwindShadeScale": ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900"],
+  "defaultTailwindShade": "500",
+  "importStyleRules": {
+    "mx-auto": "margin-left:auto;margin-right:auto",
+    "ml-auto": "margin-left:auto",
+    "mr-auto": "margin-right:auto",
+    "w-full": "width:100%",
+    "w-auto": "width:auto",
+    "h-full": "height:100%",
+    "h-48": "height:12rem",
+    "h-2.5": "height:0.625rem",
+    "h-10": "height:var(--spacing-10)",
+    "h-2": "height:var(--spacing-2)",
+    "w-2": "width:var(--spacing-2)",
+    "size-8": "width:var(--spacing-8);height:var(--spacing-8)",
+    "size-10": "width:var(--spacing-10);height:var(--spacing-10)",
+    "size-full": "width:100%;height:100%",
+    "min-h-screen": "min-height:100vh",
+    "overflow-hidden": "overflow:hidden",
+    "overflow-x-hidden": "overflow-x:hidden",
+    "overflow-x-auto": "overflow-x:auto",
+    "whitespace-nowrap": "white-space:nowrap",
+    "hidden": "display:none",
+    "block": "display:block",
+    "truncate": "overflow:hidden;text-overflow:ellipsis;white-space:nowrap",
+    "justify-items-center": "justify-items:center",
+    "justify-items-start": "justify-items:start",
+    "justify-items-end": "justify-items:end",
+    "justify-items-stretch": "justify-items:stretch",
+    "grid-flow-col": "grid-auto-flow:column",
+    "aspect-square": "aspect-ratio:1 / 1",
+    "bg-center": "background-position:center",
+    "bg-cover": "background-size:cover",
+    "bg-no-repeat": "background-repeat:no-repeat",
+    "transition-colors": "transition-property:color,background-color,border-color,text-decoration-color,fill,stroke;transition-duration:150ms"
+  },
+  "importStyleDynamicRules": [
+    {
+      "id": "fallback.import-style.gap-scale",
+      "pattern": "^gap-(\\d+)$",
+      "summary": "Converts gap scale utilities (including responsive variants like md:gap-6) to generated import-* fallback classes."
+    },
+    {
+      "id": "fallback.import-style.min-width-arbitrary",
+      "pattern": "^min-w-\\[[^\\]]+\\]$",
+      "summary": "Converts arbitrary min-width utilities (e.g. min-w-[600px]) to generated import-* fallback classes."
+    },
+    {
+      "id": "fallback.import-style.max-width-arbitrary",
+      "pattern": "^max-w-\\[[^\\]]+\\]$",
+      "summary": "Converts arbitrary max-width utilities (e.g. max-w-[480px]) to generated import-* fallback classes."
+    },
+    {
+      "id": "fallback.import-style.min-height-arbitrary",
+      "pattern": "^min-h-\\[[^\\]]+\\]$",
+      "summary": "Converts arbitrary min-height utilities (e.g. min-h-[180px]) to generated import-* fallback classes."
+    },
+    {
+      "id": "fallback.import-style.grid-rows-arbitrary",
+      "pattern": "^grid-rows-\\[[^\\]]+\\]$",
+      "summary": "Converts arbitrary grid template row utilities (e.g. grid-rows-[1fr_auto]) to generated import-* fallback classes."
+    },
+    {
+      "id": "fallback.import-style.size-scale",
+      "pattern": "^size-(\\[[^\\]]+\\]|[0-9.]+)$",
+      "summary": "Converts size scale/arbitrary utilities into width+height fallback declarations."
+    },
+    {
+      "id": "fallback.import-style.width-height-scale",
+      "pattern": "^[wh]-(\\[[^\\]]+\\]|[0-9.]+)$",
+      "summary": "Converts width/height scale and arbitrary utilities to import-* classes."
+    },
+    {
+      "id": "fallback.import-style.spacing",
+      "pattern": "^-?(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr)-(.+)$",
+      "summary": "Converts spacing utilities to directional padding/margin fallback declarations, including responsive variants."
+    },
+    {
+      "id": "fallback.import-style.text-size",
+      "pattern": "^text-(xs|sm|base|lg|xl|2xl|3xl|4xl)$",
+      "summary": "Converts common text size utilities to import-* font-size declarations."
+    },
+    {
+      "id": "fallback.import-style.font-weight",
+      "pattern": "^font-(normal|medium|semibold|bold|extrabold|black)$",
+      "summary": "Converts common font weight utilities to import-* font-weight declarations."
+    },
+    {
+      "id": "fallback.import-style.leading-tracking",
+      "pattern": "^(leading|tracking)-(none|tight|snug|normal|relaxed|loose|tighter|wide|wider|widest)$",
+      "summary": "Converts line-height and letter-spacing utilities to import-* declarations for typography fidelity."
+    },
+    {
+      "id": "fallback.import-style.bg-tokenized",
+      "pattern": "^bg-([a-z]+)-(\\d{2,3})$",
+      "summary": "Safeguards Tailwind background color utilities by mapping families like blue/purple/green/red to PDS semantic tokens."
+    },
+    {
+      "id": "fallback.import-style.bg-semantic",
+      "pattern": "^bg-(primary|secondary|accent)$",
+      "summary": "Safeguards semantic background utilities by mapping bg-primary/bg-secondary/bg-accent to PDS color tokens."
+    },
+    {
+      "id": "fallback.import-style.text-tokenized",
+      "pattern": "^text-([a-z]+)-(\\d{2,3})$",
+      "summary": "Safeguards Tailwind text color utilities by mapping common families to PDS semantic tokens."
+    },
+    {
+      "id": "fallback.import-style.rounded",
+      "pattern": "^rounded(?:-[trbl]{1,2})?(?:-(none|xs|sm|md|lg|xl|2xl|3xl|full))?$",
+      "summary": "Safeguards rounded utilities (including rounded-t-sm) by mapping to PDS radius tokens."
+    },
+    {
+      "id": "fallback.import-style.overlay-alpha",
+      "pattern": "^bg-black\\/(\\d{1,3})$",
+      "summary": "Converts alpha black overlay classes (e.g. bg-black/50) to tokenized color-mix background overlays."
+    },
+    {
+      "id": "fallback.import-style.text-inverse",
+      "pattern": "^text-white$",
+      "summary": "Preserves white foreground intent for text-on-image use cases using inverse-compatible tokens."
+    },
+    {
+      "id": "fallback.import-style.bg-arbitrary",
+      "pattern": "^bg-\\[[^\\]]+\\]$",
+      "summary": "Converts arbitrary background colors to import-* fallback classes when values are CSS-safe."
+    },
+    {
+      "id": "fallback.import-style.text-arbitrary",
+      "pattern": "^text-\\[[^\\]]+\\]$",
+      "summary": "Converts arbitrary text colors to import-* fallback classes when values are CSS-safe."
+    }
+  ]
+}

package/src/js/pds-live-manager/template-service.js

@@ -0,0 +1,170 @@
+import { createImportResult } from "./import-contract.js";
+
+const CATALOG_RELATIVE_URL = "../templates/templates.json";
+const CATALOG_ABSOLUTE_URL = "/assets/pds/templates/templates.json";
+const NODE_CWD_CATALOG = ["public", "assets", "pds", "templates", "templates.json"];
+const NODE_PACKAGE_CATALOG_RELATIVE = ["..", "..", "..", "public", "assets", "pds", "templates", "templates.json"];
+
+let catalogCache = null;
+
+function isNodeRuntime() {
+  return Boolean(typeof process !== "undefined" && process?.versions?.node);
+}
+
+function normalizeTemplateMeta(template = {}) {
+  return {
+    id: String(template.id || "").trim(),
+    name: String(template.name || template.id || "Template").trim(),
+    description: String(template.description || "").trim(),
+    icon: String(template.icon || "layout").trim(),
+    file: String(template.file || "").trim(),
+    tags: Array.isArray(template.tags) ? template.tags.map((item) => String(item)) : [],
+  };
+}
+
+function normalizeCatalog(catalog = {}, sourceInfo = {}) {
+  const templatesRaw = Array.isArray(catalog)
+    ? catalog
+    : Array.isArray(catalog?.templates)
+      ? catalog.templates
+      : [];
+
+  const templates = templatesRaw
+    .map(normalizeTemplateMeta)
+    .filter((item) => item.id && item.file);
+
+  return {
+    version: catalog?.version || "1",
+    templates,
+    __catalogURL: sourceInfo.catalogURL || null,
+    __catalogFilePath: sourceInfo.catalogFilePath || null,
+  };
+}
+
+async function loadCatalogFromBrowser(options = {}) {
+  const configuredUrl = options.catalogURL || globalThis?.PDS?.currentConfig?.templateCatalogURL;
+  const candidates = [configuredUrl, CATALOG_RELATIVE_URL, CATALOG_ABSOLUTE_URL].filter(Boolean);
+
+  for (const candidate of candidates) {
+    try {
+      const url = new URL(candidate, import.meta.url).href;
+      const response = await fetch(url, { credentials: "same-origin" });
+      if (!response.ok) continue;
+      const json = await response.json();
+      return normalizeCatalog(json, { catalogURL: url });
+    } catch (error) {}
+  }
+
+  return normalizeCatalog({ templates: [] });
+}
+
+async function loadCatalogFromNode(options = {}) {
+  const fsSpecifier = "node:fs/promises";
+  const pathSpecifier = "node:path";
+  const urlSpecifier = "node:url";
+  const [{ readFile }, path, { fileURLToPath }] = await Promise.all([
+    import(fsSpecifier),
+    import(pathSpecifier),
+    import(urlSpecifier),
+  ]);
+
+  const candidates = [];
+  if (options.catalogPath) {
+    candidates.push(path.resolve(options.catalogPath));
+  }
+
+  candidates.push(path.resolve(process.cwd(), ...NODE_CWD_CATALOG));
+
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  candidates.push(path.resolve(moduleDir, ...NODE_PACKAGE_CATALOG_RELATIVE));
+
+  for (const candidate of candidates) {
+    try {
+      const raw = await readFile(candidate, "utf8");
+      const json = JSON.parse(raw);
+      return normalizeCatalog(json, { catalogFilePath: candidate });
+    } catch (error) {}
+  }
+
+  return normalizeCatalog({ templates: [] });
+}
+
+async function readTemplateHtml(template, catalog) {
+  if (!template?.file) return "";
+
+  if (!isNodeRuntime()) {
+    const baseUrl = catalog?.__catalogURL || CATALOG_ABSOLUTE_URL;
+    const templateUrl = new URL(template.file, baseUrl).href;
+    const response = await fetch(templateUrl, { credentials: "same-origin" });
+    if (!response.ok) {
+      throw new Error(`Template file not found: ${template.file}`);
+    }
+    return (await response.text()).trim();
+  }
+
+  const fsSpecifier = "node:fs/promises";
+  const pathSpecifier = "node:path";
+  const [{ readFile }, path] = await Promise.all([
+    import(fsSpecifier),
+    import(pathSpecifier),
+  ]);
+  const baseDir = catalog?.__catalogFilePath ? path.dirname(catalog.__catalogFilePath) : path.resolve(process.cwd(), "public", "assets", "pds", "templates");
+  const templatePath = path.resolve(baseDir, template.file);
+  return (await readFile(templatePath, "utf8")).trim();
+}
+
+export async function loadLiveTemplateCatalog(options = {}) {
+  if (catalogCache && !options.forceReload) return catalogCache;
+
+  catalogCache = isNodeRuntime()
+    ? await loadCatalogFromNode(options)
+    : await loadCatalogFromBrowser(options);
+
+  return catalogCache;
+}
+
+export async function listLiveTemplates(options = {}) {
+  const catalog = await loadLiveTemplateCatalog(options);
+  return catalog.templates.map(({ id, name, description, icon, file, tags }) => ({
+    id,
+    name,
+    description,
+    icon,
+    file,
+    tags,
+  }));
+}
+
+export async function getLiveTemplateById(templateId, options = {}) {
+  const catalog = await loadLiveTemplateCatalog(options);
+  const template = catalog.templates.find((item) => item.id === templateId) || null;
+  if (!template) return null;
+
+  const html = await readTemplateHtml(template, catalog);
+  return { ...template, html };
+}
+
+export async function buildTemplateImportResult(templateId, options = {}) {
+  const template = await getLiveTemplateById(templateId, options);
+  if (!template) {
+    return createImportResult({
+      source: "template",
+      type: "template",
+      confidence: 0,
+      issues: [{ severity: "error", message: `Unknown template: ${templateId}` }],
+    });
+  }
+
+  return createImportResult({
+    source: "template",
+    type: "template",
+    confidence: 1,
+    template: {
+      id: template.id,
+      name: template.name,
+      html: template.html,
+      icon: template.icon,
+      description: template.description,
+    },
+  });
+}

package/src/js/pds.d.ts

@@ -152,6 +152,7 @@ export interface PDSEventMap {
   'pds:ready': CustomEvent<{ mode: 'live' | 'static'; generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
   'pds:error': CustomEvent<{ error: any }>;
   'pds:theme:changed': CustomEvent<{ theme: string; requested?: string; source: 'system' | 'programmatic' }>;
+  'pds:config-changed': CustomEvent<{ at: number; mode?: 'live' | 'static'; source?: string; preset?: string }>;
   'pds:design:updated': CustomEvent<{ config: any; designer?: any }>;
   'pds:design:field:changed': CustomEvent<{ field: string; config: any }>;
   'pds:inspector:mode:changed': CustomEvent<{ active: boolean }>;

package/src/js/pds.js

@@ -180,6 +180,36 @@ function __emitPDSReady(detail) {
   }
 }
 
+function __emitPDSConfigChanged(detail = {}) {
+  const hasCustomEvent = typeof CustomEvent === "function";
+  const payload = {
+    at: Date.now(),
+    ...detail,
+  };
+
+  try {
+    const changedEvent = hasCustomEvent
+      ? new CustomEvent("pds:config-changed", { detail: payload })
+      : new Event("pds:config-changed");
+    PDS.dispatchEvent(changedEvent);
+  } catch (e) {}
+
+  if (typeof document !== "undefined") {
+    if (hasCustomEvent) {
+      const eventOptions = { detail: payload, bubbles: true, composed: true };
+      try {
+        document.dispatchEvent(
+          new CustomEvent("pds:config-changed", eventOptions)
+        );
+      } catch (e) {}
+    } else {
+      try {
+        document.dispatchEvent(new Event("pds:config-changed"));
+      } catch (e) {}
+    }
+  }
+}
+
 if (typeof window !== "undefined") {
   // @ts-ignore
   window.PDS = PDS;
@@ -382,6 +412,7 @@ async function start(config) {
   const { startLive } = await import(managerUrl);
   return startLive(PDS, rest, {
     emitReady: __emitPDSReady,
+    emitConfigChanged: __emitPDSConfigChanged,
     applyResolvedTheme: __applyResolvedTheme,
     setupSystemListenerIfNeeded: __setupSystemListenerIfNeeded,
   });
@@ -490,6 +521,10 @@ async function staticInit(config) {
             (s) => s._pds !== true
           );
           document.adoptedStyleSheets = [...others, stylesSheet];
+          __emitPDSConfigChanged({
+            mode: "static",
+            source: "static:styles-applied",
+          });
         }
       } catch (e) {
         __defaultLog.call(PDS, "warn", "Failed to apply static styles:", e);