@litfamily/litclaude 1.0.10 → 1.0.13

package/plugins/litclaude/skills/lit-pptx/scripts/learn_template.py

@@ -0,0 +1,446 @@
+#!/usr/bin/env python3
+"""
+learn_template.py — Template learning: ingest a user's existing .pptx and emit
+an enrolled template (template.yaml + capabilities.yaml + layout-mapping.yaml)
+that this toolkit can render with.
+
+Philosophy (brand-docs "off-brand by construction"): the generated template only
+references fonts / colors / assets that actually exist in the source .pptx, and a
+closed-set verification step asserts this before the template is accepted.
+
+Usage:
+    python3 scripts/learn_template.py <source.pptx> --name <TEMPLATE-NAME> [--out .lit-pptx/templates]
+
+The default output directory is .lit-pptx/templates under the working directory,
+which compile-deck.js searches before the bundled templates. Never write into the
+installed skill directory.
+"""
+
+import os as _os
+import sys as _sys
+
+_sys.dont_write_bytecode = True  # the installed skill directory stays read-only
+_sys.path.insert(0, _os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "..", "..", "..", "lib"))
+from office_runtime_bootstrap import ensure_runtime  # noqa: E402
+
+ensure_runtime(["defusedxml"])
+
+import argparse
+import sys
+import zipfile
+from pathlib import Path
+
+from defusedxml import ElementTree as DET  # XXE / billion-laughs safe
+
+A = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+P = "{http://schemas.openxmlformats.org/presentationml/2006/main}"
+EMU = 914400.0
+
+# ── security limits for untrusted input ──────────────────────────────────────
+MAX_FILES = 5000
+MAX_UNCOMPRESSED = 500 * 1024 * 1024  # 500 MB
+MAX_RATIO = 200  # per-file compression ratio guard (zip-bomb)
+
+
+class LearnError(Exception):
+    pass
+
+
+def _safe_open_zip(path: Path) -> zipfile.ZipFile:
+    if path.suffix.lower() != ".pptx":
+        raise LearnError(f"not a .pptx file: {path.name}")
+    if not path.is_file():
+        raise LearnError(f"file not found: {path}")
+    try:
+        zf = zipfile.ZipFile(path)
+    except zipfile.BadZipFile as e:
+        raise LearnError(f"malformed/not a zip: {e}")
+    infos = zf.infolist()
+    if len(infos) > MAX_FILES:
+        raise LearnError(f"zip-bomb guard: too many entries ({len(infos)} > {MAX_FILES})")
+    total = 0
+    for i in infos:
+        total += i.file_size
+        if total > MAX_UNCOMPRESSED:
+            raise LearnError(f"zip-bomb guard: uncompressed size exceeds {MAX_UNCOMPRESSED} bytes")
+        if i.compress_size > 0 and (i.file_size / i.compress_size) > MAX_RATIO:
+            raise LearnError(f"zip-bomb guard: entry {i.filename!r} ratio > {MAX_RATIO}")
+    # must look like a pptx
+    names = set(zf.namelist())
+    if "ppt/presentation.xml" not in names:
+        raise LearnError("not a PowerPoint package (no ppt/presentation.xml)")
+    return zf
+
+
+def _xml(zf, name):
+    if name not in zf.namelist():
+        return None
+    return DET.fromstring(zf.read(name))
+
+
+def _hex_from_clr(el):
+    """Return 6-char hex from an a:srgbClr/a:sysClr child element, or None."""
+    if el is None:
+        return None
+    s = el.find(f"{A}srgbClr")
+    if s is not None and s.get("val"):
+        return s.get("val").upper()
+    sysc = el.find(f"{A}sysClr")
+    if sysc is not None and sysc.get("lastClr"):
+        return sysc.get("lastClr").upper()
+    return None
+
+
+def extract(zf):
+    """Return a dict of discovered brand facts."""
+    facts = {"dimensions": {}, "palette": {}, "fonts": {}, "used_fonts": set(),
+             "assets": [], "regions": {}}
+
+    # dimensions
+    pres = _xml(zf, "ppt/presentation.xml")
+    if pres is not None:
+        sldsz = pres.find(f"{P}sldSz")
+        if sldsz is not None:
+            cx = int(sldsz.get("cx", 0)) / EMU
+            cy = int(sldsz.get("cy", 0)) / EMU
+            facts["dimensions"] = {"width": round(cx, 3), "height": round(cy, 3),
+                                   "unit": "inches",
+                                   "format": "16:9" if abs(cx / cy - 16 / 9) < 0.05 else
+                                             ("4:3" if abs(cx / cy - 4 / 3) < 0.05 else "custom")}
+
+    # theme: palette + font scheme
+    theme = _xml(zf, "ppt/theme/theme1.xml")
+    if theme is not None:
+        clr = theme.find(f".//{A}clrScheme")
+        if clr is not None:
+            name_map = {"dk1": "ink", "lt1": "paper", "dk2": "ink_alt", "lt2": "paper_alt",
+                        "accent1": "accent1", "accent2": "accent2", "accent3": "accent3",
+                        "accent4": "accent4", "accent5": "accent5", "accent6": "accent6",
+                        "hlink": "link", "folHlink": "link_visited"}
+            for child in clr:
+                tag = child.tag.replace(A, "")
+                key = name_map.get(tag)
+                hx = _hex_from_clr(child)
+                if key and hx:
+                    facts["palette"][key] = f"#{hx}"
+        fs = theme.find(f".//{A}fontScheme")
+        if fs is not None:
+            def font_of(which):
+                el = fs.find(f"{A}{which}")
+                if el is None:
+                    return {}
+                out = {}
+                latin = el.find(f"{A}latin")
+                ea = el.find(f"{A}ea")
+                if latin is not None and latin.get("typeface"):
+                    out["latin"] = latin.get("typeface")
+                if ea is not None and ea.get("typeface"):
+                    out["ea"] = ea.get("typeface")
+                return out
+            facts["fonts"]["major"] = font_of("majorFont")
+            facts["fonts"]["minor"] = font_of("minorFont")
+
+    # fonts actually used in slides (authoritative for closed-set)
+    for n in zf.namelist():
+        if n.startswith("ppt/slides/slide") and n.endswith(".xml"):
+            try:
+                root = DET.fromstring(zf.read(n))
+            except Exception:
+                continue
+            for el in root.iter():
+                tf = el.get("typeface") if el.tag.endswith("}latin") or el.tag.endswith("}ea") else None
+                if tf:
+                    facts["used_fonts"].add(tf)
+
+    # media assets
+    for n in zf.namelist():
+        if n.startswith("ppt/media/"):
+            facts["assets"].append(Path(n).name)
+
+    return facts
+
+
+def _resolve_fonts(facts):
+    """Pick title/body/light family names from discovered fonts (closed-set)."""
+    used = facts["used_fonts"]
+    major = (facts["fonts"].get("major") or {})
+    minor = (facts["fonts"].get("minor") or {})
+    # Prefer an actually-used font; else theme scheme; else a safe sans fallback.
+    title = major.get("ea") or major.get("latin")
+    body = minor.get("ea") or minor.get("latin")
+    if used:
+        # if the theme font isn't actually used, fall back to a used one
+        if title not in used:
+            title = sorted(used)[0]
+        if body not in used:
+            body = sorted(used)[0]
+    title = title or "Arial"
+    body = body or title
+    return {"title": title, "body": body, "light": body}
+
+
+def _palette(facts):
+    p = dict(facts["palette"])
+    ink = p.get("ink", "#000000")
+    paper = p.get("paper", "#FFFFFF")
+    return {
+        "ink": ink, "paper": paper,
+        "ink_muted": p.get("ink", "#444444"),
+        "line": p.get("paper_alt", "#CCCCCC"),
+        "header_fill": p.get("paper_alt", "#EEEEEE"),
+        "accent_red": p.get("accent2", "#CC0000"),
+        "accent_green": p.get("accent6", "#2E7D32"),
+        "accent_amber": p.get("accent4", "#D79921"),
+        "metric": p.get("accent1", ink),
+        "source_blue": p.get("link", "#1155CC"),
+    }
+
+
+def _regions(facts):
+    """Best-fit region geometry from dimensions (placeholder-aware fallback)."""
+    w = facts["dimensions"].get("width", 10.0)
+    h = facts["dimensions"].get("height", 7.5)
+    mx = round(w * 0.06, 3)            # side margin ~6%
+    cw = round(w - 2 * mx, 3)          # content width
+    title_y = round(h * 0.06, 3)
+    body_y = round(h * 0.18, 3)
+    return {
+        "cover": {"title": (mx, round(h * 0.40, 3), cw, 1.0),
+                  "metadata": (mx, round(h * 0.56, 3), cw, 0.5),
+                  "date_line": (mx, round(h * 0.66, 3), cw, 0.4)},
+        "body": {"title": (mx, title_y, cw, 0.56),
+                 "body": (mx, body_y, cw, None),
+                 "image": (round(w * 0.54, 3), round(h * 0.18, 3), round(w * 0.40, 3), round(h * 0.42, 3))},
+        "closing": {"title": (0.0, round(h * 0.43, 3), w, 0.95)},
+    }
+
+
+# ── YAML emit (matches the toolkit's minimal parser style) ───────────────────
+def _yaml(obj, indent=0):
+    pad = "  " * indent
+    out = []
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            if isinstance(v, dict):
+                if not v:
+                    out.append(f"{pad}{k}: {{}}")
+                else:
+                    out.append(f"{pad}{k}:")
+                    out.append(_yaml(v, indent + 1))
+            elif isinstance(v, list):
+                if not v:
+                    out.append(f"{pad}{k}: []")
+                else:
+                    out.append(f"{pad}{k}:")
+                    for item in v:
+                        out.append(f"{pad}  - {_scalar(item)}")
+            else:
+                out.append(f"{pad}{k}: {_scalar(v)}")
+    return "\n".join(out)
+
+
+def _scalar(v):
+    if isinstance(v, str):
+        # quote hex colors, font names with spaces, and anything risky
+        if v.startswith("#") or " " in v or v == "":
+            return f'"{v}"'
+        return v
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v)
+
+
+def _font_role(font, size, color, align="left", bold=False, **extra):
+    r = {"font": font, "size": size, "char_spacing": -0.3, "align": align,
+         "bold": bold, "color": color}
+    r.update(extra)
+    return r
+
+
+def build_template(facts, name):
+    fonts = _resolve_fonts(facts)
+    pal = _palette(facts)
+    dims = facts["dimensions"] or {"width": 10.0, "height": 7.5, "unit": "inches", "format": "4:3"}
+    ink = pal["ink"]
+
+    template = {
+        "name": name,
+        "version": "1.0.0",
+        "label": f"Learned from source ({name})",
+        "description": f"Auto-generated enrolled template learned from a source .pptx. Fonts/colors are closed-set (only what the source contains).",
+        "fonts": fonts,
+        "dimensions": dims,
+        "palette": pal,
+        "decoration_assets": {},
+        "global_typography": {
+            "char_spacing": -0.3,
+            "bold_rule": "Learned template — title font used for emphasis.",
+            "bullet_font": fonts["body"],
+            "bullet_char": "•",
+            "bullet_color": ink.lstrip("#"),
+            "section_accent": ink.lstrip("#"),
+        },
+    }
+
+    fr = {
+        "cover_title": _font_role(fonts["title"], 36, ink, "center", False, line_spacing=1.15),
+        "cover_metadata": _font_role(fonts["body"], 13, pal["ink_muted"], "center"),
+        "cover_date": _font_role(fonts["body"], 10, pal["ink_muted"], "center"),
+        "section_title": _font_role(fonts["title"], 24, ink, "left"),
+        "section_header": _font_role(fonts["title"], 15, ink, "left", False,
+                                     space_after=6, bullet_type="bullet", bullet_char="•",
+                                     bullet_font=fonts["body"], marL=0.25, indent=-0.25),
+        "body_text": _font_role(fonts["body"], 12, ink, "left", False, line_spacing=1.3),
+        "body_text_toc": _font_role(fonts["body"], 20, ink, "left", False, space_after=8),
+        "numbered_item": _font_role(fonts["body"], 12, ink, "left", False,
+                                    space_after=4, bullet_type="number",
+                                    number_type="arabicParenBoth", marL=0.5, indent=-0.3125),
+        "table_header": _font_role(fonts["title"], 11, ink, "left", False, fill=pal["header_fill"]),
+        "table_data": _font_role(fonts["body"], 11, ink, "left"),
+        "closing_title": _font_role(fonts["title"], 36, ink, "center", False, line_spacing=1.0),
+        "disclaimer": _font_role(fonts["light"], 8, pal["ink_muted"], "left"),
+        "kpi_value": _font_role(fonts["title"], 28, pal["metric"], "left"),
+        "kpi_label": _font_role(fonts["body"], 9, pal["ink_muted"], "left"),
+        "figure_caption": _font_role(fonts["body"], 9, pal["source_blue"], "center"),
+        "table_caption": _font_role(fonts["body"], 9, pal["source_blue"], "center"),
+    }
+
+    capabilities = {
+        "supported_layouts": ["cover", "content", "main", "summary", "closing"],
+        "supported_blocks": {
+            "cover": ["title"],
+            "content": ["title", "body", "image", "notes", "kpi-table", "figure-caption", "table-caption"],
+            "main": ["title", "body", "main-box", "kpi-table", "image", "figure-caption", "table-caption"],
+            "summary": ["title", "summary-group", "image", "kpi-table", "figure-caption", "table-caption"],
+            "closing": ["title"],
+        },
+        "supported_body_items": ["bullet", "numbered", "section"],
+        "font_roles": fr,
+        "constraints": {"max_columns_per_table": 6, "body_text_stays_black": False,
+                        "no_bold_on_bold_fonts": False},
+    }
+
+    reg = _regions(facts)
+    cov, body, clo = reg["cover"], reg["body"], reg["closing"]
+
+    def box(t, role=None, **extra):
+        x, y, w, hh = t
+        d = {"x": x, "y": y, "w": w}
+        if hh is not None:
+            d["h"] = hh
+        if role:
+            d["font_role"] = role
+        d.update(extra)
+        return d
+
+    content_regions = {
+        "title": box(body["title"], "section_title", valign="middle", autofit="none"),
+        "body": box(body["body"], "body_text", autofit="resize"),
+        "table": {"x": body["body"][0], "y": body["body"][1], "w": body["body"][2],
+                  "font_role_header": "table_header", "font_role_data": "table_data"},
+        "image": box(body["image"]),
+        "figure_caption": box((body["image"][0], round(body["image"][1] + body["image"][3] + 0.1, 3),
+                               body["image"][2], 0.42), "figure_caption", align="center"),
+    }
+    main_regions = dict(content_regions)
+    main_regions["main_box"] = {"x": body["title"][0], "y": round(dims["height"] * 0.78, 3),
+                                "w": body["body"][2], "h": 0.95, "border": {"width": 1}}
+    summary_regions = {
+        "title": box(body["title"], "section_title", valign="middle", autofit="shrink"),
+        "group_top": {"x": body["title"][0], "y": body["body"][1], "w": round(body["body"][2] * 0.47, 3),
+                      "h": 2.5, "heading_role": "section_header", "sub_item_role": "numbered_item",
+                      "autofit": "resize"},
+        "group_bottom": {"x": body["title"][0], "y": round(body["body"][1] + 2.8, 3),
+                         "w": round(body["body"][2] * 0.47, 3), "h": 2.5,
+                         "heading_role": "section_header", "sub_item_role": "numbered_item",
+                         "autofit": "resize"},
+        "image": box(body["image"]),
+    }
+
+    mapping = {
+        "layouts": {
+            "cover": {"layout_source": "none", "decorations": "cover", "regions": {
+                "title": box(cov["title"], "cover_title", valign="middle", autofit="none"),
+                "metadata": box(cov["metadata"], "cover_metadata", valign="middle", autofit="resize"),
+                "date_line": box(cov["date_line"], "cover_date", valign="middle", autofit="none"),
+            }},
+            "content": {"layout_source": "none", "decorations": "body", "regions": content_regions},
+            "main": {"layout_source": "none", "decorations": "body", "regions": main_regions},
+            "summary": {"layout_source": "none", "decorations": "body", "regions": summary_regions},
+            "closing": {"layout_source": "none", "decorations": "closing", "regions": {
+                "title": box(clo["title"], "closing_title", align="center", valign="middle", autofit="shrink"),
+            }},
+        },
+        "decorations": {"cover": {"elements": []}, "body": {"elements": []}, "closing": {"elements": []}},
+    }
+    return template, capabilities, mapping
+
+
+def closed_set_verify(facts, template, capabilities):
+    """Assert generated fonts/colors only reference what the source contains."""
+    problems = []
+    source_fonts = set(facts["used_fonts"])
+    for m in (facts["fonts"].get("major") or {}).values():
+        source_fonts.add(m)
+    for m in (facts["fonts"].get("minor") or {}).values():
+        source_fonts.add(m)
+    # allow the generic fallback only when the source had no fonts at all
+    fallback_ok = not facts["used_fonts"]
+    for role, d in capabilities["font_roles"].items():
+        f = d["font"]
+        if f not in source_fonts and not (fallback_ok and f in ("Arial",)):
+            problems.append(f"font '{f}' (role {role}) not in source font set")
+    source_colors = {v.upper() for v in facts["palette"].values()}
+    # palette is derived from source theme; flag any non-source, non-neutral hex
+    neutral = {"#000000", "#FFFFFF", "#444444", "#CCCCCC", "#EEEEEE"}
+    for k, v in template["palette"].items():
+        if v.upper() not in source_colors and v.upper() not in neutral:
+            problems.append(f"palette '{k}'={v} not in source theme colors")
+    return problems
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Learn an enrolled template from a source .pptx")
+    ap.add_argument("source")
+    ap.add_argument("--name", required=True)
+    ap.add_argument("--out", default=".lit-pptx/templates")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+
+    src = Path(args.source)
+    try:
+        zf = _safe_open_zip(src)
+    except LearnError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    facts = extract(zf)
+    template, capabilities, mapping = build_template(facts, args.name)
+
+    problems = closed_set_verify(facts, template, capabilities)
+    if problems:
+        print("CLOSED-SET VERIFICATION FAILED:", file=sys.stderr)
+        for p in problems:
+            print(f"  - {p}", file=sys.stderr)
+        sys.exit(3)
+
+    out_dir = Path(args.out) / args.name
+    out_dir.mkdir(parents=True, exist_ok=True)
+    (out_dir / "template.yaml").write_text(_yaml(template) + "\n", encoding="utf-8")
+    (out_dir / "capabilities.yaml").write_text(_yaml(capabilities) + "\n", encoding="utf-8")
+    (out_dir / "layout-mapping.yaml").write_text(_yaml(mapping) + "\n", encoding="utf-8")
+
+    if not args.quiet:
+        d = facts["dimensions"]
+        print(f"Learned template '{args.name}' -> {out_dir}")
+        print(f"  dimensions: {d.get('width')}x{d.get('height')} {d.get('unit')} ({d.get('format')})")
+        print(f"  fonts: title={template['fonts']['title']!r} body={template['fonts']['body']!r}")
+        print(f"  palette: ink={template['palette']['ink']} paper={template['palette']['paper']} "
+              f"accent_red={template['palette']['accent_red']}")
+        print(f"  source fonts used: {sorted(facts['used_fonts']) or '(none)'}")
+        print(f"  assets in source: {len(facts['assets'])}")
+        print("  closed-set verification: PASS")
+
+
+if __name__ == "__main__":
+    main()

package/plugins/litclaude/skills/lit-pptx/scripts/lib/derive-palette.js

@@ -0,0 +1,176 @@
+"use strict";
+
+/**
+ * derive-palette.js — turn any brand ACCENT hex into a harmonious, WCAG-safe
+ * azure-style palette (same token set as templates/enrolled/AZURE-PRO).
+ *
+ * Strategy: work in HSL, keep the accent's hue, and set each token's lightness
+ * to the role it must play — darkening `primary`/`primary_deep` by *relative
+ * luminance* until white text clears the WCAG floor (works for any hue, incl.
+ * bright yellows/greens which must go darker than a blue would).
+ */
+
+// ── color math ──────────────────────────────────────────────────────────────
+function hexToRgb(hex) {
+  const v = String(hex).replace("#", "").trim();
+  return [parseInt(v.slice(0, 2), 16), parseInt(v.slice(2, 4), 16), parseInt(v.slice(4, 6), 16)];
+}
+function rgbToHex([r, g, b]) {
+  const c = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+  return `#${c(r)}${c(g)}${c(b)}`.toUpperCase();
+}
+function rgbToHsl([r, g, b]) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  let h = 0, s = 0; const l = (max + min) / 2;
+  const d = max - min;
+  if (d !== 0) {
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0));
+    else if (max === g) h = (b - r) / d + 2;
+    else h = (r - g) / d + 4;
+    h /= 6;
+  }
+  return [h * 360, s, l];
+}
+function hslToRgb([h, s, l]) {
+  h = ((h % 360) + 360) % 360 / 360;
+  if (s === 0) { const v = l * 255; return [v, v, v]; }
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const t2c = (t) => {
+    if (t < 0) t += 1; if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  return [t2c(h + 1 / 3) * 255, t2c(h) * 255, t2c(h - 1 / 3) * 255];
+}
+function relLuminance([r, g, b]) {
+  const ch = (c) => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+  const [R, G, B] = [ch(r), ch(g), ch(b)];
+  return 0.2126 * R + 0.7152 * G + 0.0722 * B;
+}
+/** WCAG contrast ratio between two colors. */
+function contrast(a, b) {
+  const l1 = relLuminance(a), l2 = relLuminance(b);
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+/** Contrast of white text on a given color (color is the darker one). */
+function whiteContrast(rgb) { return 1.05 / (relLuminance(rgb) + 0.05); }
+/** Contrast of a (dark) color as text on white — same ratio as white-on-color. */
+function onWhiteContrast(rgb) { return contrast([255, 255, 255], rgb); }
+
+function hsl(h, s, l) { return rgbToHex(hslToRgb([h, s, l])); }
+
+/** Lighten an HSL color (raise L) until it reaches `floor` contrast on `bgRgb`. */
+function lightenForContrastOn(bgRgb, h, s, lStart, floor = 4.5) {
+  let L = lStart;
+  for (let i = 0; i < 60; i++) {
+    if (contrast(hslToRgb([h, s, L]), bgRgb) >= floor) break;
+    L += 0.012;
+    if (L >= 0.98) { L = 0.98; break; }
+  }
+  return L;
+}
+
+/** Darken an HSL color (lower L) until white text reaches `floor`. */
+function darkenForWhite(h, s, l, floor = 4.5) {
+  let L = l;
+  for (let i = 0; i < 60; i++) {
+    if (whiteContrast(hslToRgb([h, s, L])) >= floor) break;
+    L -= 0.015;
+    if (L <= 0.04) { L = 0.04; break; }
+  }
+  return L;
+}
+/** Darken until the color (as text) reaches `floor` on white. */
+function darkenForOnWhite(h, s, l, floor = 4.5) {
+  let L = l;
+  for (let i = 0; i < 60; i++) {
+    if (onWhiteContrast(hslToRgb([h, s, L])) >= floor) break;
+    L -= 0.015;
+    if (L <= 0.04) { L = 0.04; break; }
+  }
+  return L;
+}
+
+// ── palette derivation ──────────────────────────────────────────────────────
+/**
+ * @param {string} accentHex e.g. "#7C3AED"
+ * @returns full azure-style palette + a `gradient:[c1,c2]` pair and meta ratios.
+ */
+function derivePalette(accentHex) {
+  const [h, s0] = rgbToHsl(hexToRgb(accentHex));
+  const s = Math.max(0.55, Math.min(0.9, s0 || 0.7)); // ensure a rich, branded chroma
+
+  // primary: the accent, darkened (by luminance) until white text passes 4.5:1
+  const pL = darkenForWhite(h, s, 0.48, 4.5);
+  const primary = hsl(h, s, pL);
+  const primaryRgb = hslToRgb([h, s, pL]);
+  const primary_deep = hsl(h, Math.min(0.7, s + 0.05), darkenForWhite(h, s + 0.05, 0.22, 7.0));
+  // azure is decorative (rings/dots/large "+") — keep it bright but ensure the
+  // large "+" still clears the 3:1 large-text floor on white for any hue.
+  let azureL = Math.min(0.62, pL + 0.14);
+  while (azureL > 0.2 && onWhiteContrast(hslToRgb([h, s, azureL])) < 3.0) azureL -= 0.015;
+  const azure = hsl(h, s, azureL);
+  const azure_soft = hsl(h, Math.max(0.5, s - 0.1), 0.78);
+  const tint = hsl(h, 0.55, 0.965);
+  const tint_2 = hsl(h, 0.55, 0.92);
+  const line = hsl(h, 0.25, 0.86);
+  const ink = hsl(h, 0.45, 0.12);                 // near-black with a hue hint
+  // ink_muted is body/secondary text shown on BOTH white and tint cards — darken
+  // until it clears 4.5:1 on the tint (the lighter-text's harder background).
+  const tintRgb = hexToRgb(tint);
+  let imL = 0.42;
+  while (imL > 0.18 && contrast(hslToRgb([h, 0.22, imL]), tintRgb) < 4.6) imL -= 0.012;
+  const ink_muted = hsl(h, 0.22, imL);
+  // light text used on primary / primary_deep filled cards — lighten until it
+  // clears 4.5:1 on the *lighter* of the two (primary), so both pass.
+  const emphasis_text = hsl(h, 0.4, lightenForContrastOn(primaryRgb, h, 0.4, 0.86, 4.5));
+  // gradient: vivid accent → hue-shifted indigo-equivalent (both mid-dark)
+  const g1 = hsl(h, Math.min(0.85, s + 0.05), 0.53);
+  const g2 = hsl(h + 25, Math.min(0.8, s), 0.55);
+
+  return {
+    ground: "#FFFFFF",
+    paper: hsl(h, 0.5, 0.985),
+    ink, ink_muted,
+    primary, primary_deep, azure, azure_soft,
+    tint, tint_2, line,
+    metric: ink,
+    bullet_color: primary.replace("#", ""),
+    section_accent: primary.replace("#", ""),
+    emphasis_text,
+    gradient: [g1, g2],
+    _ratios: {
+      whiteOnPrimary: +whiteContrast(hexToRgb(primary)).toFixed(2),
+      whiteOnPrimaryDeep: +whiteContrast(hexToRgb(primary_deep)).toFixed(2),
+      inkMutedOnWhite: +onWhiteContrast(hexToRgb(ink_muted)).toFixed(2),
+    },
+  };
+}
+
+/** Map AZURE-PRO's default decoration hexes → the derived palette equivalents,
+ * so hardcoded decoration colors (rings/dots/panels/pills) recolor coherently. */
+function defaultToDerivedMap(p) {
+  const norm = (x) => "#" + String(x).replace("#", "").toUpperCase();
+  return new Map([
+    ["#1D4ED8", norm(p.primary)],
+    ["#0B2E6F", norm(p.primary_deep)],
+    ["#3B82F6", norm(p.azure)],
+    ["#93C5FD", norm(p.azure_soft)],
+    ["#EEF4FF", norm(p.tint)],
+    ["#DCE9FF", norm(p.tint_2)],
+    ["#D5DEEC", norm(p.line)],
+    ["#0E1B2C", norm(p.ink)],
+  ]);
+}
+
+module.exports = {
+  derivePalette,
+  defaultToDerivedMap,
+  hexToRgb, rgbToHex, rgbToHsl, hslToRgb,
+  whiteContrast, onWhiteContrast, contrast,
+};