texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/templates/letter/manifest.toml

@@ -0,0 +1,197 @@
+[compat]
+texsmith = ">=0.6,<1.0"
+
+[latex.template]
+name = "formal-letter"
+version = "0.1.0"
+entrypoint = "template/template.tex"
+engine = "xelatex"
+shell_escape = false
+texlive_year = 2023
+tlmgr_packages = [
+    "babel",
+    "fontspec",
+    "microtype",
+    "koma-script",
+]
+description = """
+Formal letter template based on KOMA-Script with configurable
+sender/recipient and standards."""
+
+fragments = [
+    "ts-fonts",
+    "ts-extra",
+    "ts-keystrokes",
+    "ts-callouts",
+    "ts-code",
+    "ts-glossary",
+    "ts-bibliography",
+    "ts-todolist",
+]
+
+[latex.template.attributes.cursive]
+default = false
+type = "boolean"
+sources = ["cursive"]
+description = "Toggle cursive signature font."
+
+[latex.template.attributes.language]
+default = "en-UK"
+type = "string"
+allow_empty = false
+sources = ["language"]
+description = "Language for babel."
+
+[latex.template.attributes.standard]
+default = ""
+type = "string"
+sources = ["standard", "format"]
+description = "Letter standard/format (e.g., sn, nf)."
+
+[latex.template.attributes.date]
+default = ""
+type = "string"
+escape = "latex"
+allow_empty = true
+sources = ["date"]
+
+[latex.template.attributes.object]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["object"]
+description = "Subject line."
+
+[latex.template.attributes.from_name]
+default = ""
+type = "string"
+escape = "latex"
+allow_empty = false
+required = true
+sources = ["from_name"]
+description = "Sender full name."
+
+[latex.template.attributes.from_address]
+default = []
+type = "list"
+sources = ["from_address"]
+
+[latex.template.attributes.back_address]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["back_address"]
+
+[latex.template.attributes.from_location]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["from_location"]
+
+[latex.template.attributes.to_name]
+default = ""
+type = "string"
+escape = "latex"
+allow_empty = false
+required = true
+sources = ["to_name"]
+description = "Recipient full name."
+
+[latex.template.attributes.to_address]
+default = []
+type = "list"
+sources = ["to_address"]
+
+[latex.template.attributes.closing]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["closing"]
+description = "Closing phrase."
+
+[latex.template.attributes.opening]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["opening"]
+description = "Opening phrase."
+
+[latex.template.attributes.signature]
+default = ""
+type = "any"
+sources = ["signature"]
+description = "Signature block (text or raw LaTeX)."
+
+[latex.template.attributes.source_dir]
+default = ""
+type = "string"
+allow_empty = true
+sources = ["source_dir"]
+
+[latex.template.attributes.output_dir]
+default = ""
+type = "string"
+allow_empty = true
+format = "raw"
+sources = ["output_dir"]
+
+[latex.template.attributes.signature_align]
+default = "left"
+type = "string"
+sources = ["signature_align"]
+
+[latex.template.attributes.reference]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["reference"]
+description = "Reference field content."
+
+[latex.template.attributes.reference_fields]
+default = false
+type = "boolean"
+sources = ["reference_fields"]
+description = "Whether to render reference fields block."
+
+[latex.template.attributes.postscript]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["postscript"]
+description = "Postscript paragraph."
+
+[latex.template.attributes.fold_marks]
+default = false
+type = "boolean"
+sources = ["fold_marks"]
+description = "Toggle fold marks."
+
+[latex.template.attributes.margin]
+default = "default"
+type = "string"
+normaliser = "margin_style"
+sources = ["margin"]
+description = "Margin style (default, wide, narrow)."
+
+[latex.template.attributes.preamble]
+default = ""
+type = "string"
+allow_empty = true
+sources = ["preamble"]
+
+[latex.template.attributes.page_numbers]
+default = false
+type = "boolean"
+sources = ["page_numbers"]
+description = "Enable page numbers."
+
+[latex.template.slots.mainmatter]
+default = true
+base_level = 10
+strip_heading = true
+
+[latex.template.slots.backmatter]
+strip_heading = true
+
+[latex.template.assets]
+"fonts/modernline.otf" = { source = "fonts/modernline.otf" }

texsmith/templates/letter/template/callouts.jinja.sty

@@ -0,0 +1,290 @@
+% callouts.sty — Callout boxes with tcolorbox + FontAwesome
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{callouts}[2025/10/27 Callout boxes with tcolorbox + FontAwesome]
+
+% --- Required packages ---
+\RequirePackage{xcolor}
+\RequirePackage{tcolorbox}
+\tcbuselibrary{breakable,skins}
+\RequirePackage{fontawesome5}
+
+% --- Shared color palette ---
+\definecolor{calloutNoteBg}{HTML}{ECF3FF}
+\definecolor{calloutNoteFrame}{HTML}{448AFF}
+\definecolor{calloutAbstractBg}{HTML}{E5F7FF}
+\definecolor{calloutAbstractFrame}{HTML}{00B0FF}
+\definecolor{calloutInfoBg}{HTML}{E5F8FB}
+\definecolor{calloutInfoFrame}{HTML}{00B8D4}
+\definecolor{calloutTipBg}{HTML}{E5F8F6}
+\definecolor{calloutTipFrame}{HTML}{00BFA5}
+\definecolor{calloutSuccessBg}{HTML}{E5F9ED}
+\definecolor{calloutSuccessFrame}{HTML}{00C853}
+\definecolor{calloutQuestionBg}{HTML}{EFFCE7}
+\definecolor{calloutQuestionFrame}{HTML}{64DD17}
+\definecolor{calloutWarningBg}{HTML}{FFF1D6}
+\definecolor{calloutWarningFrame}{HTML}{FFB200}
+\definecolor{calloutCautionBg}{HTML}{FFF8E1}
+\definecolor{calloutCautionFrame}{HTML}{FF9100}
+\definecolor{calloutFailureBg}{HTML}{FFEDED}
+\definecolor{calloutFailureFrame}{HTML}{FF5252}
+\definecolor{calloutDangerBg}{HTML}{FFE2E7}
+\definecolor{calloutDangerFrame}{HTML}{C62828}
+\definecolor{calloutImportantBg}{HTML}{FFE0F0}
+\definecolor{calloutImportantFrame}{HTML}{D81B60}
+\definecolor{calloutBugBg}{HTML}{FEE5EE}
+\definecolor{calloutBugFrame}{HTML}{F50057}
+\definecolor{calloutExampleBg}{HTML}{F2EDFF}
+\definecolor{calloutExampleFrame}{HTML}{7C4DFF}
+\definecolor{calloutQuoteBg}{HTML}{F5F5F5}
+\definecolor{calloutQuoteFrame}{HTML}{9E9E9E}
+\definecolor{calloutExerciseBg}{HTML}{F5F5F5}
+\definecolor{calloutExerciseFrame}{HTML}{202020}
+\definecolor{calloutDefaultBg}{HTML}{F0F0F0}
+\definecolor{calloutDefaultFrame}{HTML}{808080}
+
+\BLOCK{ set style = callout_style | default("fancy") }
+
+\BLOCK{ if style == "classic" }
+% --- Classic (black & white) style ---
+\newfontfamily\texsmithCalloutIconFont{Noto Emoji}[Renderer=Harfbuzz]
+\newcommand{\texsmithCalloutIcon}[1]{%
+  \ifdefined\texsmithCalloutIconFont
+    {\texsmithCalloutIconFont #1}%
+  \else
+    #1%
+  \fi
+}
+\tcbset{callout base/.style={
+  breakable,
+  enhanced,
+  title filled=false,
+  arc=0mm,
+  boxrule=0mm,
+  titlerule=0mm,
+  lefttitle=0mm,
+  leftupper=1mm,
+  left=2mm,
+  colback=white,
+  colbacktitle=white,
+  colframe=black!80,
+  coltitle=black!80,
+  parbox=false,
+  frame hidden,
+  borderline west={1mm}{0mm}{black!60},
+}}
+\tcbset{
+  callout note/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{📝}}}},
+  callout abstract/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{📄}}}},
+  callout summary/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{📋}}}},
+  callout info/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{ℹ}}}},
+  callout tip/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{⭐}}}},
+  callout success/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{✅}}}},
+  callout warning/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{⚠}}}},
+  callout caution/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{⚠}}}},
+  callout failure/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{❗}}}},
+  callout important/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{❗}}}},
+  callout hint/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{💡}}}},
+  callout danger/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{🔥}}}},
+  callout bug/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{🐞}}}},
+  callout example/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{🧪}}}},
+  callout quote/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{❝}}}},
+  callout question/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{❓}}}},
+  callout solution/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{💬}}}},
+  callout default/.style={callout base,title={\makebox[1.6em][c]{\texsmithCalloutIcon{ℹ}}}},
+}
+\newcommand{\texsmithCalloutTitleFormat}[1]{~#1}
+\newtcolorbox{callout}[2][]{%
+  callout base,
+  #1,
+  after title={\texsmithCalloutTitleFormat{#2}}%
+}
+
+\BLOCK{ elif style == "minimal" }
+% --- Minimal (bordered, no icons) style ---
+\tcbset{callout base/.style={
+  breakable,
+  enhanced,
+  title filled=false,
+  arc=0.7mm,
+  boxrule=0.3mm,
+  titlerule=0mm,
+  lefttitle=0mm,
+  leftupper=1mm,
+  colback=white,
+  colframe=black,
+  parbox=false,
+}}
+\tcbset{
+  callout note/.style={callout base},
+  callout abstract/.style={callout base},
+  callout summary/.style={callout base},
+  callout info/.style={callout base},
+  callout tip/.style={callout base},
+  callout success/.style={callout base},
+  callout warning/.style={callout base},
+  callout caution/.style={callout base},
+  callout failure/.style={callout base},
+  callout important/.style={callout base},
+  callout hint/.style={callout base},
+  callout danger/.style={callout base},
+  callout bug/.style={callout base},
+  callout example/.style={callout base},
+  callout quote/.style={callout base},
+  callout question/.style={callout base},
+  callout solution/.style={callout base},
+  callout default/.style={callout base},
+}
+\newtcolorbox{callout}[2][]{%
+  callout base,
+  before upper={\textbf{#2}\par\smallskip},
+  #1,
+}
+
+\BLOCK{ else }
+% --- Fancy (colored) style ---
+\newcommand{\texsmithCalloutTitleFormat}[1]{~#1}
+\tcbset{callout base/.style={
+  breakable,
+  enhanced,
+  title filled,
+  arc=0mm,
+  boxrule=0mm,
+  titlerule=0mm,
+  lefttitle=1mm,
+  leftupper=1mm,
+  colback=white,
+  parbox=false,
+  frame hidden,
+  borderline west={0.3mm}{0mm}{black!70},
+}}
+\tcbset{
+  callout note/.style={
+    colbacktitle=calloutNoteBg,
+    colframe=calloutNoteFrame,
+    coltitle=calloutNoteFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutNoteFrame},
+    title={\makebox[1.3em][c]{\faBookmark}},
+  },
+  callout abstract/.style={
+    colbacktitle=calloutAbstractBg,
+    colframe=calloutAbstractFrame,
+    coltitle=calloutAbstractFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutAbstractFrame},
+    title={\makebox[1.3em][c]{\faLaptopCode}},
+  },
+  callout summary/.style={
+    colbacktitle=calloutAbstractBg,
+    colframe=calloutAbstractFrame,
+    coltitle=calloutAbstractFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutAbstractFrame},
+    title={\makebox[1.3em][c]{\faList}},
+  },
+  callout info/.style={
+    colbacktitle=calloutInfoBg,
+    colframe=calloutInfoFrame,
+    coltitle=calloutInfoFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutInfoFrame},
+    title={\makebox[1.3em][c]{\faComment}},
+  },
+  callout tip/.style={
+    colbacktitle=calloutTipBg,
+    colframe=calloutTipFrame,
+    coltitle=calloutTipFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutTipFrame},
+    title={\makebox[1.3em][c]{\faStar}},
+  },
+  callout success/.style={
+    colbacktitle=calloutSuccessBg,
+    colframe=calloutSuccessFrame,
+    coltitle=calloutSuccessFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutSuccessFrame},
+    title={\makebox[1.3em][c]{\faCheck}},
+  },
+  callout warning/.style={
+    colbacktitle=calloutWarningBg,
+    colframe=calloutWarningFrame,
+    coltitle=calloutWarningFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutWarningFrame},
+    title={\makebox[1.3em][c]{\faBolt}},
+  },
+  callout caution/.style={
+    colbacktitle=calloutCautionBg,
+    colframe=calloutCautionFrame,
+    coltitle=calloutCautionFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutCautionFrame},
+    title={\makebox[1.3em][c]{\faExclamationTriangle}},
+  },
+  callout failure/.style={
+    colbacktitle=calloutFailureBg,
+    colframe=calloutFailureFrame,
+    coltitle=calloutFailureFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutFailureFrame},
+    title={\makebox[1.3em][c]{\faExclamationTriangle}},
+  },
+  callout important/.style={
+    colbacktitle=calloutImportantBg,
+    colframe=calloutImportantFrame,
+    coltitle=calloutImportantFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutImportantFrame},
+    title={\makebox[1.3em][c]{\faExclamationTriangle}},
+  },
+  callout hint/.style={
+    colbacktitle=calloutTipBg,
+    colframe=calloutTipFrame,
+    coltitle=calloutTipFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutTipFrame},
+    title={\makebox[1.3em][c]{\faLightbulb}},
+  },
+  callout danger/.style={
+    colbacktitle=calloutDangerBg,
+    colframe=calloutDangerFrame,
+    coltitle=calloutDangerFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutDangerFrame},
+    title={\makebox[1.3em][c]{\faFire}},
+  },
+  callout bug/.style={
+    colbacktitle=calloutBugBg,
+    colframe=calloutBugFrame,
+    coltitle=calloutBugFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutBugFrame},
+    title={\makebox[1.3em][c]{\faBomb}},
+  },
+  callout example/.style={
+    colbacktitle=calloutExampleBg,
+    colframe=calloutExampleFrame,
+    coltitle=calloutExampleFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutExampleFrame},
+    title={\makebox[1.3em][c]{\faFlask}},
+  },
+  callout quote/.style={
+    colbacktitle=calloutQuoteBg,
+    colframe=calloutQuoteFrame,
+    coltitle=calloutQuoteFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutQuoteFrame},
+    title={\makebox[1.3em][c]{\faQuestionCircle}},
+  },
+  callout question/.style={
+    colbacktitle=calloutQuestionBg,
+    colframe=calloutQuestionFrame,
+    coltitle=calloutQuestionFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutQuestionFrame},
+    title={\makebox[1.3em][c]{\faQuestionCircle}},
+  },
+  callout solution/.style={
+    colbacktitle=gray!40!white,
+    title={\textcolor{black}{\makebox[1.3em][l]{\faComment}}},
+  },
+  callout default/.style={
+    colbacktitle=calloutDefaultBg,
+    colframe=calloutDefaultFrame,
+    coltitle=calloutDefaultFrame!80!black,
+    borderline west={0.3mm}{0mm}{calloutDefaultFrame},
+    title={\textcolor{black}{\makebox[1.3em][l]{\faComment}}},
+  },
+}
+\newtcolorbox{callout}[2][]{%
+  callout base,
+  #1,
+  after title={\texsmithCalloutTitleFormat{#2}}%
+}
+\BLOCK{ endif }

texsmith/templates/letter/template/template.tex

@@ -0,0 +1,123 @@
+\documentclass[
+  paper=a4,
+  parskip=half,
+  firstfoot=false,
+  enlargefirstpage=true,
+]{scrlttr2}
+\usepackage{xcolor}
+\definecolor{texsmithLinkColor}{HTML}{0B3D91}
+\VAR{extra_packages}
+\usepackage{graphicx}
+\usepackage[\VAR{babel_language|default('english')}]{babel}
+\usepackage[
+    colorlinks=true,
+    linkcolor=texsmithLinkColor,
+    urlcolor=texsmithLinkColor,
+    citecolor=texsmithLinkColor]{hyperref}
+\LoadLetterOption{\VAR{letter_standard_option}}
+\KOMAoptions{foldmarks=\VAR{foldmarks_option}}
+\BLOCK{ set margin_style = margin|default('default')|lower }
+\BLOCK{ set margin_literal = margin_style not in ["narrow", "default", "wide"] }
+\BLOCK{ if margin_style == "narrow" }
+\KOMAoptions{fromalign=left, backaddress=false}
+\setlength{\oddsidemargin}{1cm}
+\BLOCK{ elif margin_style == "wide" }
+\KOMAoptions{fromalign=left, backaddress=false}
+\setlength{\oddsidemargin}{2cm}
+\BLOCK{ elif margin_literal }
+\KOMAoptions{fromalign=left, backaddress=false}
+\setlength{\oddsidemargin}{0cm}
+\addtolength{\textwidth}{-\VAR{margin}}
+\BLOCK{ endif }
+\BLOCK{ if use_cursive_signature }
+\setmainfont[Path=fonts/,Extension=.otf,Ligatures=Common,Mapping=]{modernline}
+\newcommand{\TexsmithLetterEndash}{\kern0.05em-\kern0.05em}
+\newcommand{\TexsmithLetterEmdash}{\kern0.05em-\kern0.05em-\kern0.05em}
+\catcode"2013=\active
+\catcode"2014=\active
+\begingroup\lccode`~="2013\lowercase{\endgroup\protected\def~}{\TexsmithLetterEndash}
+\begingroup\lccode`~="2014\lowercase{\endgroup\protected\def~}{\TexsmithLetterEmdash}
+\BLOCK{ endif }
+
+\BLOCK{ if preamble }
+% Custom document preamble injected from overrides.
+\VAR{preamble}
+
+\BLOCK{ endif }
+
+\BLOCK{ if use_cursive_signature }
+\newfontfamily\SignatureFont[Path=fonts/,Extension=.otf]{modernline}
+\newcommand{\SignatureText}[1]{{\SignatureFont #1}}
+\BLOCK{ else }
+\newcommand{\SignatureText}[1]{#1}
+\BLOCK{ endif }
+
+\newcommand{\SignatureBlock}{%
+\BLOCK{ if has_signature_image }
+  \includegraphics[height=1.6cm]{\VAR{signature_image_path}}
+  \\[-0.25\baselineskip]%
+\BLOCK{ endif }
+  \SignatureText{\VAR{signature_text}}%
+}
+
+\setkomavar{fromname}{\VAR{from_name}}
+\setkomavar{fromaddress}{%
+\BLOCK{ if has_sender_address }
+  \VAR{from_address_lines|join('\\\\\n')}
+\BLOCK{ endif }
+}
+\BLOCK{ if from_location_value -}
+\setkomavar{location}{\VAR{from_location_value}}\BLOCK{ endif }
+\BLOCK{ set effective_date = date_value|default('')|trim }
+\setkomavar{date}{\BLOCK{ if effective_date -}
+\VAR{date_value}\BLOCK{ else }\today\BLOCK{ endif }}
+\BLOCK{ if has_subject }
+\setkomavar{subject}{\VAR{object_value}}
+\setkomavar*{subject}{\VAR{subject_prefix}}
+\BLOCK{ endif }
+\setkomavar{signature}{\SignatureBlock}
+\BLOCK{ if has_back_address }
+\setkomavar{backaddress}{%
+  \VAR{back_address_lines|join('\\\\\n')}
+}
+\BLOCK{ endif }
+\BLOCK{ if reference_value }
+\setkomavar{myref}{\VAR{reference_value}}
+\BLOCK{ endif }
+\BLOCK{ if not reference_fields_enabled }
+\removereffields
+\BLOCK{ endif }
+\renewcommand*{\raggedsignature}{\VAR{signature_alignment_command}}
+
+\begin{document}
+
+\begin{letter}{%
+\BLOCK{ if has_recipient_address }
+  \VAR{to_address_lines|join('\\\\\n  ')}
+\BLOCK{ else }
+  \VAR{to_name}
+\BLOCK{ endif }
+}
+
+\opening{\VAR{opening_text}}
+
+\VAR{mainmatter}
+
+\VAR{backmatter}
+\VAR{fragment_backmatter}
+
+\BLOCK{ if has_closing }
+\closing{\VAR{closing_text}}
+\BLOCK{ endif }
+\BLOCK{ if has_postscript }
+\ps{PS: \VAR{postscript_text}}
+\BLOCK{ endif }
+
+\end{letter}
+\BLOCK{ if not page_numbers }
+\pagenumbering{gobble}
+\thispagestyle{empty}
+\pagestyle{empty}
+\BLOCK{ endif }
+
+\end{document}

texsmith/templates/snippet/README.md

@@ -0,0 +1,21 @@
+# TeXSmith Snippet Template
+
+The built-in `snippet` template renders Markdown fragments inside a decorated
+`tikzpicture`, perfect for standalone notes, stickers, or screenshot-friendly
+callouts. It reuses TeXSmith’s article preamble (fonts, callouts, keystrokes,
+progress bars) so Markdown extensions behave the same way, but swaps the
+document class for `standalone` and constrains the body to a configurable
+minipage.
+
+```bash
+texsmith snippet.md --template snippet \
+  --attribute width=11cm \
+  --attribute margin=7mm \
+  --attribute dogear=12mm \
+  --attribute dogear_enabled=false
+```
+
+Override attributes via front matter or CLI `--attribute` flags to tweak the
+inner width, padding, dog-ear size, or border visibility. Because the template
+includes the shared callout definitions, admonitions look identical to the
+`article` template inside the snippet frame.

texsmith/templates/snippet/__init__.py

@@ -0,0 +1,80 @@
+"""Snippet template integration for TeXSmith."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, ClassVar
+
+from texsmith.core.templates import TemplateError, WrappableTemplate
+
+
+_PACKAGE_ROOT = Path(__file__).parent.resolve()
+
+
+class Template(WrappableTemplate):
+    """Expose the snippet template as a wrappable template instance."""
+
+    _CALLOUT_STYLES: ClassVar[set[str]] = {"fancy", "classic", "minimal"}
+    _EMOJI_MODES: ClassVar[set[str]] = {"artifact", "symbola", "color", "black", "twemoji"}
+
+    def __init__(self) -> None:
+        try:
+            super().__init__(_PACKAGE_ROOT)
+        except TemplateError as exc:  # pragma: no cover - file system safeguard
+            raise TemplateError(f"Failed to initialise snippet template: {exc}") from exc
+
+    def prepare_context(
+        self,
+        latex_body: str,
+        *,
+        overrides: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        context = super().prepare_context(latex_body, overrides=overrides)
+        context["ts_extra_disable_hyperref"] = True
+
+        context["language"] = self._normalise_string(context.get("language"), "english")
+        context["width"] = self._normalise_dimension(context.get("width"), "12cm")
+        context["margin"] = self._normalise_dimension(context.get("margin"), "6mm")
+        context["dogear"] = self._normalise_dimension(context.get("dogear"), "10mm")
+        context["border"] = bool(context.get("border", True))
+        context["dogear_enabled"] = bool(context.get("dogear_enabled", True))
+        candidate_emoji = context.get("emoji")
+        if not candidate_emoji:
+            fonts_cfg = context.get("fonts")
+            if isinstance(fonts_cfg, Mapping):
+                candidate_emoji = fonts_cfg.get("emoji")
+        if not candidate_emoji:
+            press_cfg = context.get("press")
+            if isinstance(press_cfg, Mapping):
+                press_fonts = press_cfg.get("fonts")
+                if isinstance(press_fonts, Mapping):
+                    candidate_emoji = press_fonts.get("emoji")
+        context["emoji"] = self._normalise_emoji_mode(candidate_emoji)
+        context.setdefault("preamble", "")
+        context.setdefault("latex_engine", "lualatex")
+        return context
+
+    def _normalise_string(self, value: Any, default: str) -> str:
+        if value is None:
+            return default
+        candidate = str(value).strip()
+        return candidate or default
+
+    def _normalise_dimension(self, value: Any, default: str) -> str:
+        if value is None:
+            return default
+        candidate = str(value).strip()
+        return candidate or default
+
+    def _normalise_emoji_mode(self, value: Any) -> str:
+        candidate = str(value).strip() if value is not None else ""
+        if not candidate:
+            return "black"
+        lowered = candidate.lower()
+        if lowered in self._EMOJI_MODES:
+            return lowered
+        return candidate
+
+
+__all__ = ["Template"]