Plugin API¶

def asset_filename(digest: str, suffix: str) -> str:
    """Return the deterministic filename for a snippet artefact."""
    return f"{_SNIPPET_PREFIX}{digest}{suffix}"

def build_snippet_block(
    raw_content: str,
    *,
    language: str | None,
    attributes: Mapping[str, Any] | None = None,
    meta: Mapping[str, str] | None = None,
    host_path: Path | None = None,
) -> SnippetBlock | None:
    """Parse a snippet fence into a :class:`SnippetBlock`; the pure half of the fence handling.

    ``raw_content`` is the fence body, ``language`` its info-string language,
    ``attributes`` the :data:`FENCE_ATTRIBUTES` the host element carried
    (``caption``, ``label``, ``width``, ``layout``, ``config``) and ``meta``
    the parsed ``data-meta`` tokens of the HTML reader. The HTML path
    (:func:`_extract_snippet_block`) and the tmark ``snippet`` pass both end
    here. ``None`` when the fence has neither inline content nor sources.

    The body is taken without its trailing newlines, so that the readers
    agree on one text and therefore on one digest: the IR gives a fence body
    that stops at the closing fence, while the HTML of the same fence ends
    with the newline the renderer put before ``</code>``, and a file spliced
    into a fence by ``include=`` ends with its own.
    """
    raw_content = raw_content.rstrip("\n")
    attrs = dict(attributes or {})
    meta_attrs = dict(meta or {})
    caption = coerce_attribute(attrs.get("caption")) or None
    label = coerce_attribute(attrs.get("label")) or None
    figure_width = coerce_attribute(attrs.get("width")) or None
    layout_literal: Any = coerce_attribute(attrs.get("layout")) or None
    config_literal = coerce_attribute(attrs.get("config")) or None

    config_from_file: dict[str, Any] = {}
    if config_literal:
        config_path = Path(config_literal)
        if not config_path.is_absolute():
            if host_path is None:
                raise InvalidNodeError("Relative snippet configuration requires a host document.")
            config_path = (host_path.parent / config_path).resolve()
        try:
            config_payload = config_path.read_text(encoding="utf-8")
        except OSError as exc:
            raise InvalidNodeError(
                f"Unable to read snippet configuration '{config_path}': {exc}"
            ) from exc
        config_from_file = _load_yaml_mapping(config_payload)

    config_from_body: dict[str, Any] = {}
    inline_content: str | None = None
    if language in {"yaml", "yml"}:
        config_from_body = _load_yaml_mapping(raw_content)
    else:
        metadata, body = split_front_matter(raw_content)
        config_from_body = dict(metadata or {})
        if body.strip():
            inline_content = body
        if not config_from_body and inline_content is not None:
            # Fallback: accept pure-YAML snippet bodies even when the language class is missing.
            try:
                parsed_yaml = _load_yaml_mapping(raw_content)
            except InvalidNodeError:
                parsed_yaml = None
            if isinstance(parsed_yaml, dict) and parsed_yaml:
                config_from_body = parsed_yaml
                inline_content = None

    merged_config: dict[str, Any] = {**config_from_file, **config_from_body}
    figure_width = (
        coerce_attribute(merged_config.pop("width", figure_width))
        or coerce_attribute(meta_attrs.get("width"))
        or figure_width
    )
    caption = coerce_attribute(merged_config.pop("caption", caption)) or caption
    label = coerce_attribute(merged_config.pop("label", label)) or label
    layout_literal = merged_config.pop("layout", layout_literal) or layout_literal
    template_id_raw = merged_config.pop("template", None)
    template_id = coerce_attribute(template_id_raw) or None
    cwd_value = merged_config.pop("cwd", None)
    drop_title_value = _coerce_bool_option(merged_config.pop("drop_title", False), False)
    promote_title_value = _coerce_bool_option(
        merged_config.pop("promote_title", None),
        True,
    )
    suppress_title_value = _coerce_bool_option(
        merged_config.pop("suppress_title_metadata", merged_config.pop("suppress_title", None)),
        False,
    )

    base_dir = _resolve_base_dir_value(cwd_value, host_path)
    sources = _resolve_sources(merged_config.pop("sources", None), base_dir)
    bibliography_files = [
        path for path in sources if path.suffix.lower() in {".bib", ".bibtex", ".ris"}
    ]
    if inline_content is None and not sources:
        return None

    fragments = merged_config.pop("fragments", None)
    press_overrides = merged_config.pop("press", None)
    press_template: str | None = None
    template_overrides: dict[str, Any] = dict(merged_config)
    if press_overrides is not None:
        if not isinstance(press_overrides, Mapping):
            raise InvalidNodeError("The 'press' section must be a mapping.")
        press_payload = dict(press_overrides)
        press_template = coerce_attribute(press_payload.pop("template", None)) or None
        template_overrides["press"] = press_payload
    _merge_press_section(template_overrides, fragments)
    template_overrides.setdefault("glossary_inline", True)

    document_front_matter = (
        _document_front_matter(merged_config, press_overrides) if inline_content is not None else {}
    )

    layout = _resolve_layout_value(layout_literal)
    preview_dogear = _frame_dogear_enabled(template_overrides)
    if template_id is None and press_template:
        template_id = press_template
    if inline_content is not None and not sources and template_id is None:
        template_id = "snippet"
        preview_dogear = True
    elif inline_content is None and sources and template_id is None:
        template_id = "article"
    digest = _hash_payload(
        inline_content or "",
        template_overrides,
        cwd=str(base_dir) if base_dir else None,
        template_id=template_id,
        layout=layout,
        sources=sources,
        promote_title=promote_title_value,
        drop_title=drop_title_value,
        suppress_title=suppress_title_value,
        transparent_corner=preview_dogear,
        front_matter=document_front_matter,
    )

    return SnippetBlock(
        content=inline_content,
        front_matter=document_front_matter,
        sources=sources,
        layout=layout,
        preview_dogear=preview_dogear,
        template_id=template_id,
        cwd=base_dir,
        caption=caption,
        label=label,
        figure_width=figure_width,
        template_overrides=template_overrides,
        digest=digest,
        bibliography_files=bibliography_files,
        promote_title=promote_title_value,
        drop_title=drop_title_value,
        suppress_title_metadata=suppress_title_value,
    )

def ensure_snippet_assets(
    block: SnippetBlock,
    *,
    output_dir: Path,
    source_path: Path | str | None = None,
    emitter: DiagnosticEmitter | None = None,
) -> SnippetAssets:
    """Render snippet assets into the provided directory when missing."""
    destination = Path(output_dir).resolve()
    destination.mkdir(parents=True, exist_ok=True)
    pdf_path = destination / asset_filename(block.digest, ".pdf")
    png_path = destination / asset_filename(block.digest, ".png")

    host_path = Path(source_path) if source_path is not None else destination / "snippet.md"
    host_dir = _resolve_base_dir(block, host_path)
    host_name = host_path.stem or "snippet"

    active_emitter = ensure_emitter(emitter)
    documents: list[Document] = []
    inline_document = _build_document(
        block, host_dir=host_dir, host_name=host_name, emitter=active_emitter
    )
    if inline_document is not None:
        documents.append(inline_document)

    bibliography_files = list(block.bibliography_files)
    document_sources: list[Path] = []
    for path in block.sources:
        suffix = path.suffix.lower()
        if suffix in {".bib", ".bibtex", ".ris"}:
            if path not in bibliography_files:
                bibliography_files.append(path)
            continue
        document_sources.append(path)

    if document_sources:
        documents.extend(
            _build_documents_from_sources(
                document_sources,
                promote_title=block.promote_title,
                drop_title=block.drop_title,
                suppress_title=block.suppress_title_metadata,
                emitter=active_emitter,
            )
        )

    if not documents:
        raise InvalidNodeError("Snippet block is empty; provide inline content or sources.")

    runtime = _resolve_template_runtime(block, documents, host_dir)
    merged_overrides = _merge_fragment_defaults(block.template_overrides, runtime)
    merged_overrides.setdefault("glossary_inline", True)
    dogear_enabled = _frame_dogear_enabled(merged_overrides) or block.preview_dogear
    caches = _resolve_caches()
    template_version = None
    if caches:
        info = getattr(runtime.instance, "info", None)
        if info is not None:
            version = getattr(info, "version", None)
            template_version = str(version) if version is not None else None

    pdf_missing = not pdf_path.exists()
    png_missing = not png_path.exists()
    assets = SnippetAssets(pdf=pdf_path, png=png_path)

    def _flush_caches() -> None:
        for cache in caches:
            cache.flush()

    def _store_in_caches() -> None:
        if not caches:
            return
        for cache in caches:
            cache.store(
                block.digest,
                pdf_path,
                png_path,
                template_version=template_version,
                block=block,
                source_path=Path(source_path) if source_path is not None else None,
            )
        _flush_caches()

    if not pdf_missing and not png_missing:
        _store_in_caches()
        return assets

    if caches and (pdf_missing or png_missing):
        for cache in caches:
            cached_assets = cache.lookup(block.digest, template_version=template_version)
            if cached_assets is None:
                continue
            try:
                if pdf_missing:
                    shutil.copy2(cached_assets.pdf, pdf_path)
                    pdf_missing = False
                if png_missing:
                    shutil.copy2(cached_assets.png, png_path)
                    png_missing = False
            except OSError:
                cache.discard(block.digest)
                continue
            if not pdf_missing and not png_missing:
                _store_in_caches()
                return assets
        _flush_caches()

    if not pdf_missing and png_missing:
        _pdf_to_png_grid(
            pdf_path,
            png_path,
            layout=block.layout,
            transparent_corner=dogear_enabled,
            spacing=None if block.layout else 0,
        )
        png_missing = False
        _store_in_caches()
        return assets

    _announce_build(block, source_path, emitter)

    settings = ConversionRequest(
        copy_assets=True,
        convert_assets=False,
        hash_assets=False,
        manifest=False,
    )
    session = TemplateSession(runtime=runtime, settings=settings, emitter=emitter)
    for document in documents:
        session.add_document(document)
    if bibliography_files:
        session.add_bibliography(*bibliography_files)
    if merged_overrides:
        session.update_options(merged_overrides)

    work_dir = destination / f".build-{block.digest}"
    shutil.rmtree(work_dir, ignore_errors=True)
    work_dir.mkdir(parents=True, exist_ok=True)

    debug_dir: Path | None = None
    try:
        render_result = session.render(work_dir)
        compiled_pdf = _compile_pdf(render_result)
        shutil.copy2(compiled_pdf, pdf_path)
    except Exception as exc:
        # Preserve the work directory for post-mortem inspection when compilation fails.
        try:
            cache_root = _resolve_cache_root() or Path(tempfile.gettempdir()) / "texsmith"
            debug_dir = (cache_root / "snippet-fail" / block.digest).resolve()
            if debug_dir.exists():
                shutil.rmtree(debug_dir, ignore_errors=True)
            shutil.copytree(work_dir, debug_dir, dirs_exist_ok=True)
        except Exception:
            debug_dir = None
        if debug_dir is not None:
            raise exc.__class__(f"{exc} (debug: {debug_dir})") from exc
        raise
    else:
        dump_dir = _resolve_snippet_dump_dir()
        if dump_dir is not None:
            target_dir = dump_dir / block.asset_basename
            if target_dir.exists():
                shutil.rmtree(target_dir, ignore_errors=True)
            shutil.copytree(work_dir, target_dir, dirs_exist_ok=True)
        shutil.rmtree(work_dir, ignore_errors=True)

    total_cells = 1
    if block.layout:
        cols, rows = block.layout
        total_cells = max(cols, 1) * max(rows, 1)
    _pdf_to_png_grid(
        pdf_path,
        png_path,
        layout=block.layout,
        transparent_corner=dogear_enabled,
        spacing=None if total_cells > 1 else 0,
        decorate_page=None,
    )

    _store_in_caches()
    return assets

def rewrite_html_snippets(
    html: str,
    resolver: Callable[[SnippetBlock], tuple[str, str]],
    *,
    source_path: Path | str | None = None,
) -> str:
    """Replace snippet fences in an HTML fragment with linked previews."""
    if "snippet" not in html:
        return html
    host_path = Path(source_path) if source_path is not None else None

    soup = BeautifulSoup(html, "html.parser")
    mutated = False
    for element in soup.find_all(["div", "pre"]):
        block = _extract_snippet_block(element, host_path=host_path)
        if block is None:
            continue
        pdf_url, png_url = resolver(block)
        anchor = soup.new_tag(
            "a",
            href=pdf_url,
            target="_blank",
            rel="noopener noreferrer",
        )
        image_attrs = {"src": png_url, "alt": block.caption or "Snippet", "class": ["ts-snippet"]}
        if block.figure_width:
            image_attrs["width"] = block.figure_width
        image = soup.new_tag("img", **image_attrs)
        anchor.append(image)
        element.replace_with(anchor)
        mutated = True

    return str(soup) if mutated else html