markwright 0.1.0__tar.gz → 0.3.0__tar.gz

markwright-0.3.0/.gitignore

@@ -0,0 +1,25 @@
+commit-msg.md
+goal.md
+.ai-sessions/implementation-notes.md
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# MkDocs build output
+site/
+
+# Coverage artifacts
+.coverage
+*.cover
+htmlcov/
+
+# Hypothesis example database
+.hypothesis/

markwright-0.3.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to markwright are recorded here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - 2026-10-11
+
+Two opt-in features (a config API for host tools and click-to-load embeds), one rule for every config list, a round of correctness fixes, and Python 3.15 support.
+With default settings, output is unchanged for documents 0.2.0 already rendered correctly; the differences are the fixes listed below.
+
+### Upgrading from 0.2.0
+
+- `enable = []` now runs no extensions, and `fence.allowed_environments = []` now allows no environments; both used to mean "everything".
+  Both now emit a `ConfigWarning`.
+  Omit the key to get the old behavior.
+- Config validation is stricter: an option key an extension does not take, a `load` value it does not support, or a non-list `fence.allowed_environments` is now a `ConfigError` (`mw` exits 2 with an `mw: error:` line) instead of being ignored.
+- Python API renames, if you call the stage functions directly: the `warnings` parameter of `apply_html` and `registry.run_post` is now `skip_reasons`, and `highlight.apply_html`'s first parameter is now `rendered_html`.
+- Removed APIs: `registry.select_extensions`, `registry.OPTION_CHECKS`, `registry.LOAD_MODES`, and the `*_SIGNATURE` constants (see Removed).
+- New runtime dependency `pydantic>=2.14.1`, and the `pymdown-extensions` floor rises to 11.0.1.
+
+### Added
+
+- A public config API for host tools: `config_from_mapping(table, source)` validates an already-parsed markwright table with the same rules as `markwright.toml`, `selected_extensions(config)` applies `enable` and `disable`, and `extension_configs(config, names)` builds the `extension_configs` argument for `markdown.Markdown`.
+  The package root re-exports these with `Config`, `ConfigError`, `ConfigWarning`, and `OptionError`.
+  `mw render` uses the same functions.
+- A `load` option on the `youtube`, `codepen`, `twitter`, and `instagram` embeds.
+  `eager` is the default and unchanged.
+  `click` emits a versioned click-to-load preview with the live markup inside a `<template>`, so nothing reaches the provider until a host script loads it.
+  `lazy` (YouTube only) adds `loading="lazy"` to the iframe.
+  Provider scripts are injected only when at least one embed of that kind on the page is eager.
+- A Click-to-Load docs page with the markup contract, the provider processor calls (checked against the providers' live scripts), and a sample host script.
+- `mw config` reports the resolved `load` for each embed and where it came from.
+- `markwright.ConfigWarning`, emitted when a setting turns a feature into a no-op (an empty selection or an empty `allowed_environments`).
+  It never raises unless you escalate it, for example with `warnings.simplefilter("error", ConfigWarning)`.
+  `mw` prints it as one `mw: warning:` line on stderr.
+- `markwright.OptionError`, a `ValueError` subclass raised for an invalid extension option value.
+- Config Rules in the configuration docs: omitting a key means its default, a list names exactly what it holds, a no-op setting warns, and every option is validated.
+- Python 3.15 support, tested in CI.
+
+### Changed
+
+- `enable = []` runs no extensions and `fence.allowed_environments = []` allows no environments, each with a `ConfigWarning`; both used to mean "everything" (#13).
+- Config validation runs each extension's own option checks and rejects option keys an extension does not take; an unknown key used to pass through and crash `mw render` with a `KeyError` traceback.
+- `mw` reports config problems as one `mw: error:` line with exit code 2, including a `ConfigWarning` escalated with `python -W error`, and prints only markwright's own warnings as `mw: warning:` lines.
+- A config value of null (a YAML key with no value) counts as omitted.
+- `apply_html` and `registry.run_post` take per-extension options, mirroring `expand_source` and `run_pre`, and name their skip-reason list `skip_reasons`.
+- The post stages read rendered HTML with the stdlib `html.parser` instead of regex and edit only the spans they change.
+- Fence directives and prose highlights find fenced code by CommonMark's rules, through one scanner shared by both pre stages.
+- `registry.REGISTRY` holds pydantic `StageSpec` models, and the embed flag settings are pydantic models.
+
+### Removed
+
+- `registry.select_extensions`; selection lives in `config.selected_extensions`.
+- `registry.OPTION_CHECKS` and `registry.LOAD_MODES`; each `StageSpec` carries its option checker, and `LOAD_MODES` stays on each embed module.
+- The `CODEPEN_SIGNATURE`, `TWITTER_SIGNATURE`, and `INSTAGRAM_SIGNATURE` constants, replaced by `*_EMBED_CLASS` (the bare class name).
+
+### Fixed
+
+- Fence directives apply to fences indented up to three spaces and to fences inside list items; they used to render as literal code text.
+- A fence marker whose JSON is valid but the wrong shape (`[1]`, `null`, a numeric `label`) is skipped with a warning instead of crashing the post stage with `AttributeError`.
+- Each fence marker styles only its own code block, so a marker with no block can no longer style the next marker's.
+- `fence.label_class` and `secondary_label_class` apply in `mw post`; the pipeline used to drop them while `mw render` honored them.
+- The fence extension reads its options when it registers, so a `setConfig` call after construction applies.
+- A highlight marker inside an HTML attribute (for example `title="&lt;^&gt;"`) is no longer wrapped in `<mark>`, which produced broken markup.
+- A `<^>` marker inside a fence nested in a longer fence is no longer highlighted by `mw pre`, and inline code spans of two or more backticks are skipped like single-backtick ones.
+- An unclosed fence is no longer treated as code by the pre stages, matching `pymdownx.superfences`.
+- An empty extension selection (from `enable = []`, a `disable` listing every extension, or `--exclude`) warns with its cause instead of passing input through silently.
+
+### Security
+
+- Requires `pymdown-extensions>=11.0.1` (was `>=10.5`), the first release without PYSEC-2026-3654.
+
+## [0.2.0] - 2026-09-23
+
+### Added
+
+- The config system: `markwright.toml` or `[tool.markwright]` discovery, `enable`/`disable`, per-extension options, `warn`, and the `mw config` command.
+
+### Removed
+
+- The `mw --use` flag; its allowlist lives in config as `enable`.
+
+## [0.1.0] - 2026-09-15
+
+### Added
+
+- First release: the highlight, fence, YouTube, CodePen, Twitter, Instagram, slideshow, and image compare extensions, and the `mw` pipeline CLI.
+
+[0.3.0]: https://github.com/MasonEgger/markwright/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/MasonEgger/markwright/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/MasonEgger/markwright/releases/tag/v0.1.0

{markwright-0.1.0 → markwright-0.3.0}/PKG-INFO

@@ -1,36 +1,36 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: markwright
-Version: 0.1.0
+Version: 0.3.0
 Summary: Python-Markdown extensions ported from DigitalOcean's do-markdownit
-Keywords: markdown,python-markdown,do-markdownit,mkdocs,hugo
-Author: Mason Egger
+Project-URL: Homepage, https://github.com/MasonEgger/markwright
+Project-URL: Repository, https://github.com/MasonEgger/markwright
+Project-URL: Documentation, https://masonegger.github.io/markwright/
 Author-email: Mason Egger <mason@masonegger.com>
 License-Expression: MIT
 License-File: LICENSE
 License-File: LICENSE-Apache-2.0
 License-File: NOTICE
-Classifier: License :: OSI Approved :: MIT License
+Keywords: do-markdownit,hugo,markdown,mkdocs,python-markdown
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Text Processing :: Markup :: Markdown
-Requires-Dist: markdown>=3.4
-Requires-Dist: pymdown-extensions>=10.5
 Requires-Python: >=3.11
-Project-URL: Homepage, https://github.com/MasonEgger/markwright
-Project-URL: Repository, https://github.com/MasonEgger/markwright
-Project-URL: Documentation, https://masonegger.github.io/markwright/
+Requires-Dist: markdown>=3.4
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: pymdown-extensions>=11.0.1
 Description-Content-Type: text/markdown
 
 # markwright
 
-A Python port of DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit) JavaScript library.
+markwright is a set of [Python-Markdown](https://python-markdown.github.io/) extensions plus a companion command-line tool, `mw`, for author-friendly markdown: highlighted text, labeled code fences, and a set of media embeds.
+Use the extensions in any tool built on Python-Markdown (including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script), or the `mw` pipeline in toolchains that are not, like Hugo.
 
-These are [Python-Markdown](https://python-markdown.github.io/) extensions that bring DigitalOcean's markdown syntax (highlighted text, labeled code fences, and a set of media embeds) to any tool built on Python-Markdown, including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script.
-The port maintains compatibility with the original `do-markdownit` HTML output, so rendered pages match what DigitalOcean produces.
-A bundled command-line tool, `mw`, runs the same extensions as pre and post filters around any renderer, so the syntax also works in toolchains that are not built on Python-Markdown, like Hugo.
+The author-facing syntax and HTML output are derived from DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit), so rendered pages match what DigitalOcean produces.
+markwright ports those extensions to Python-Markdown and adds its own pieces on top, most notably the `mw` CLI, which runs the same extensions as pre and post filters around any renderer.
 
 Full documentation and a live demo: https://masonegger.github.io/markwright/
 
@@ -47,6 +47,10 @@ Each extension is standalone and can be loaded on its own or alongside the other
 - **Slideshow** builds an image slideshow with navigation arrows.
 - **Image Compare** renders two images with a draggable before/after slider.
 
+The embeds that contact a third party (YouTube, CodePen, Twitter, Instagram) take a `load` option.
+`load = "click"` renders an inert preview so nothing reaches the provider until the reader asks; see [Click-to-Load](https://masonegger.github.io/markwright/click-to-load/).
+A host tool can validate a markwright config table from its own config file with `markwright.config_from_mapping`; see [Configuration](https://masonegger.github.io/markwright/config/).
+
 ## Installation
 
 ```bash
@@ -98,18 +102,20 @@ The extensions work with Python-Markdown directly, so you can use them in any Py
 ```python
 import markdown
 
-md = markdown.Markdown(extensions=[
-    "pymdownx.superfences",
-    "pymdownx.highlight",
-    "markwright.highlight",
-    "markwright.fence",
-    "markwright.youtube",
-    "markwright.codepen",
-    "markwright.twitter",
-    "markwright.instagram",
-    "markwright.slideshow",
-    "markwright.image_compare",
-])
+md = markdown.Markdown(
+    extensions=[
+        "pymdownx.superfences",
+        "pymdownx.highlight",
+        "markwright.highlight",
+        "markwright.fence",
+        "markwright.youtube",
+        "markwright.codepen",
+        "markwright.twitter",
+        "markwright.instagram",
+        "markwright.slideshow",
+        "markwright.image_compare",
+    ]
+)
 
 html = md.convert("This has a <^>highlighted word<^> in it.")
 print(html)
@@ -139,8 +145,12 @@ mw pre < in.md | your-renderer | mw post > out.html
 - `mw pre` expands the embeds and extracts fence directives into an `mw-fence` comment.
 - `mw post` applies the fence styling, resolves the highlights, and injects each embed script once.
 - `mw render` runs the full pipeline in one shot for callers without their own renderer.
+- `mw config` prints the resolved configuration and the source of each value.
 - `mw list` prints every extension and the stages it provides.
 
+Which extensions run, and how each is tuned, come from a `markwright.toml` (or a `[tool.markwright]` table in `pyproject.toml`) that the CLI discovers by walking up from the current directory.
+See the [configuration docs](https://masonegger.github.io/markwright/config/).
+
 Your renderer must pass raw HTML and HTML comments through.
 Hugo is a worked, tested example: see the [Hugo guide](https://masonegger.github.io/markwright/integrations/hugo/).
 The full command and flag reference is in the [CLI docs](https://masonegger.github.io/markwright/cli/).
@@ -174,17 +184,16 @@ See the [extension docs](https://masonegger.github.io/markwright/) for every fla
 This project uses [`uv`](https://docs.astral.sh/uv/) and [`just`](https://github.com/casey/just).
 
 ```bash
-just install           # uv sync
-just test              # unit tests, 100% line + branch coverage
-just test-integration  # end-to-end Hugo pipeline test (needs hugo)
-just lint              # ruff check + ruff format --check
-just typecheck         # mypy --strict
-just check             # test + lint + typecheck
+just check             # the gate: ruff check, ruff format --check, mypy strict, pytest
+just fmt               # format and auto-fix
+just test              # pytest (integration tests skip without hugo on PATH)
+just test-all          # pytest across Python 3.11 through 3.15
+just test-integration  # only the end-to-end Hugo and clean-install tests
 just docs-serve        # serve the docs site at localhost:8000
 ```
 
 `just check` must pass before a change is complete.
-The tooling bar is strict: `mypy --strict`, a clean `ruff`, and full test coverage.
+Coverage is reported on every run.
 
 ## License
 

{markwright-0.1.0 → markwright-0.3.0}/README.md

@@ -1,10 +1,10 @@
 # markwright
 
-A Python port of DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit) JavaScript library.
+markwright is a set of [Python-Markdown](https://python-markdown.github.io/) extensions plus a companion command-line tool, `mw`, for author-friendly markdown: highlighted text, labeled code fences, and a set of media embeds.
+Use the extensions in any tool built on Python-Markdown (including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script), or the `mw` pipeline in toolchains that are not, like Hugo.
 
-These are [Python-Markdown](https://python-markdown.github.io/) extensions that bring DigitalOcean's markdown syntax (highlighted text, labeled code fences, and a set of media embeds) to any tool built on Python-Markdown, including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script.
-The port maintains compatibility with the original `do-markdownit` HTML output, so rendered pages match what DigitalOcean produces.
-A bundled command-line tool, `mw`, runs the same extensions as pre and post filters around any renderer, so the syntax also works in toolchains that are not built on Python-Markdown, like Hugo.
+The author-facing syntax and HTML output are derived from DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit), so rendered pages match what DigitalOcean produces.
+markwright ports those extensions to Python-Markdown and adds its own pieces on top, most notably the `mw` CLI, which runs the same extensions as pre and post filters around any renderer.
 
 Full documentation and a live demo: https://masonegger.github.io/markwright/
 
@@ -21,6 +21,10 @@ Each extension is standalone and can be loaded on its own or alongside the other
 - **Slideshow** builds an image slideshow with navigation arrows.
 - **Image Compare** renders two images with a draggable before/after slider.
 
+The embeds that contact a third party (YouTube, CodePen, Twitter, Instagram) take a `load` option.
+`load = "click"` renders an inert preview so nothing reaches the provider until the reader asks; see [Click-to-Load](https://masonegger.github.io/markwright/click-to-load/).
+A host tool can validate a markwright config table from its own config file with `markwright.config_from_mapping`; see [Configuration](https://masonegger.github.io/markwright/config/).
+
 ## Installation
 
 ```bash
@@ -72,18 +76,20 @@ The extensions work with Python-Markdown directly, so you can use them in any Py
 ```python
 import markdown
 
-md = markdown.Markdown(extensions=[
-    "pymdownx.superfences",
-    "pymdownx.highlight",
-    "markwright.highlight",
-    "markwright.fence",
-    "markwright.youtube",
-    "markwright.codepen",
-    "markwright.twitter",
-    "markwright.instagram",
-    "markwright.slideshow",
-    "markwright.image_compare",
-])
+md = markdown.Markdown(
+    extensions=[
+        "pymdownx.superfences",
+        "pymdownx.highlight",
+        "markwright.highlight",
+        "markwright.fence",
+        "markwright.youtube",
+        "markwright.codepen",
+        "markwright.twitter",
+        "markwright.instagram",
+        "markwright.slideshow",
+        "markwright.image_compare",
+    ]
+)
 
 html = md.convert("This has a <^>highlighted word<^> in it.")
 print(html)
@@ -113,8 +119,12 @@ mw pre < in.md | your-renderer | mw post > out.html
 - `mw pre` expands the embeds and extracts fence directives into an `mw-fence` comment.
 - `mw post` applies the fence styling, resolves the highlights, and injects each embed script once.
 - `mw render` runs the full pipeline in one shot for callers without their own renderer.
+- `mw config` prints the resolved configuration and the source of each value.
 - `mw list` prints every extension and the stages it provides.
 
+Which extensions run, and how each is tuned, come from a `markwright.toml` (or a `[tool.markwright]` table in `pyproject.toml`) that the CLI discovers by walking up from the current directory.
+See the [configuration docs](https://masonegger.github.io/markwright/config/).
+
 Your renderer must pass raw HTML and HTML comments through.
 Hugo is a worked, tested example: see the [Hugo guide](https://masonegger.github.io/markwright/integrations/hugo/).
 The full command and flag reference is in the [CLI docs](https://masonegger.github.io/markwright/cli/).
@@ -148,17 +158,16 @@ See the [extension docs](https://masonegger.github.io/markwright/) for every fla
 This project uses [`uv`](https://docs.astral.sh/uv/) and [`just`](https://github.com/casey/just).
 
 ```bash
-just install           # uv sync
-just test              # unit tests, 100% line + branch coverage
-just test-integration  # end-to-end Hugo pipeline test (needs hugo)
-just lint              # ruff check + ruff format --check
-just typecheck         # mypy --strict
-just check             # test + lint + typecheck
+just check             # the gate: ruff check, ruff format --check, mypy strict, pytest
+just fmt               # format and auto-fix
+just test              # pytest (integration tests skip without hugo on PATH)
+just test-all          # pytest across Python 3.11 through 3.15
+just test-integration  # only the end-to-end Hugo and clean-install tests
 just docs-serve        # serve the docs site at localhost:8000
 ```
 
 `just check` must pass before a change is complete.
-The tooling bar is strict: `mypy --strict`, a clean `ruff`, and full test coverage.
+Coverage is reported on every run.
 
 ## License
 

markwright-0.1.0/pyproject.toml.orig → markwright-0.3.0/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "markwright"
-version = "0.1.0"
+version = "0.3.0"
 description = "Python-Markdown extensions ported from DigitalOcean's do-markdownit"
 readme = "README.md"
 authors = [
@@ -11,16 +11,17 @@ license = "MIT"
 license-files = ["LICENSE", "LICENSE-Apache-2.0", "NOTICE"]
 dependencies = [
     "markdown>=3.4",
-    "pymdown-extensions>=10.5",
+    "pydantic>=2.14.1",
+    "pymdown-extensions>=11.0.1",
 ]
 keywords = ["markdown", "python-markdown", "do-markdownit", "mkdocs", "hugo"]
 classifiers = [
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Text Processing :: Markup :: Markdown",
 ]
 
@@ -39,27 +40,31 @@ dev = [
     "mypy>=1.10",
     "pytest-cov>=7.0",
     "types-markdown>=3.10.2.20260211",
-    "mkdocs>=1.6,<2",
+    "mkdocs>=1.6",
     "mkdocs-material>=9.7.5",
+    "hypothesis>=6.169.0",
 ]
 
 [build-system]
-requires = ["uv_build>=0.9.17,<0.13.0"]
-build-backend = "uv_build"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Hatchling's default sdist is every git-tracked file; ship only the package, its tests, and what licenses it
+[tool.hatch.build.targets.sdist]
+include = ["src/markwright", "tests", "README.md", "CHANGELOG.md", "LICENSE", "LICENSE-Apache-2.0", "NOTICE"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+addopts = "--cov=markwright --cov-branch --cov-report=term-missing"
 markers = [
     "integration: end-to-end tests that require external tools such as Hugo",
 ]
 
 [tool.ruff]
-target-version = "py311"
 line-length = 120
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "SIM"]
+select = ["E", "W", "F", "I", "N", "UP", "B", "SIM", "C4", "TC"]
 
 [tool.mypy]
 strict = true
-python_version = "3.11"

markwright-0.3.0/src/markwright/__init__.py

@@ -0,0 +1,17 @@
+# ABOUTME: Package root for markwright; re-exports the public config API for host tools.
+# Extensions load by name (markwright.<name>) and need nothing from here.
+
+from __future__ import annotations
+
+from markwright._diagnostics import ConfigWarning, OptionError
+from markwright.config import Config, ConfigError, config_from_mapping, extension_configs, selected_extensions
+
+__all__ = [
+    "Config",
+    "ConfigError",
+    "ConfigWarning",
+    "OptionError",
+    "config_from_mapping",
+    "extension_configs",
+    "selected_extensions",
+]

markwright-0.3.0/src/markwright/_diagnostics.py

@@ -0,0 +1,20 @@
+# ABOUTME: Shared diagnostics: OptionError for invalid extension options, ConfigWarning for no-op settings.
+# A leaf module so config, the extensions, and the CLI can share them without an import cycle through the registry.
+
+from __future__ import annotations
+
+
+class ConfigWarning(UserWarning):
+    """Emitted when a setting makes a feature do nothing, for example ``enable = []``.
+
+    Such settings stay legal (they switch markwright off inside a tool chain) but are never silent.
+    A host can turn them into errors with ``warnings.simplefilter("error", ConfigWarning)``.
+    """
+
+
+class OptionError(ValueError):
+    """Raised when an extension option has an invalid value, for example ``load = "sometimes"``.
+
+    A ``ValueError`` subclass, so callers that catch ``ValueError`` from Python-Markdown keep working.
+    Config validation converts it to a :class:`~markwright.config.ConfigError` naming the source.
+    """

markwright-0.3.0/src/markwright/_embed_load.py

@@ -0,0 +1,82 @@
+# ABOUTME: The load option (eager, lazy, click) shared by the embeds that reach a third party.
+# Validates the option and wraps live markup in the versioned click-to-load preview.
+
+from __future__ import annotations
+
+import html
+from typing import TYPE_CHECKING
+
+from markwright._diagnostics import OptionError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+URL_SCHEME_WWW_PREFIX = r"(?:(?:https?:)?//)?(?:www\.)?"
+"""Regex fragment matching an optional ``scheme://`` and an optional ``www.``.
+
+Shared by the Twitter and Instagram embed grammars (upstream ``twitter.js`` and ``instagram.js``),
+which both accept a URL prefix ranging from nothing (a bare path) up to a full ``https://www.<host>``.
+"""
+
+LOAD_EAGER = "eager"
+LOAD_LAZY = "lazy"
+LOAD_CLICK = "click"
+
+# Version of the preview markup hosts code against; bump it on any breaking change to the contract.
+PREVIEW_VERSION = 1
+
+
+def load_mode(options: Mapping[str, object] | None, allowed: tuple[str, ...]) -> str:
+    """Read and validate the ``load`` option from an embed's option table.
+
+    :param options: The embed's option table (config table or extension configs), or ``None``.
+    :param allowed: The load values this embed supports.
+    :returns: The load value, ``"eager"`` when omitted or ``None``.
+    :raises OptionError: If ``load`` is not one of ``allowed``.
+    """
+    load = (options or {}).get("load")
+    if load is None:
+        return LOAD_EAGER
+    if not isinstance(load, str) or load not in allowed:
+        raise OptionError(f"'load' must be one of {', '.join(allowed)}; got {load!r}")
+    return load
+
+
+def wrap_preview(
+    *,
+    embed: str,
+    load: str,
+    content: str,
+    script_src: str | None,
+    provider: str,
+    action: str,
+    link_href: str,
+    link_text: str,
+) -> str:
+    """Wrap an embed's live markup in the click-to-load preview.
+
+    The live markup goes inside a ``<template>``, which browsers parse but never render or
+    fetch from, so nothing loads until a host script clones it into the page.
+
+    :param embed: The extension name, for ``data-mw-embed``.
+    :param load: The load value, for ``data-mw-load``.
+    :param content: The embed's eager markup, without any provider ``<script>``.
+    :param script_src: The provider script a host injects after cloning, or ``None``.
+    :param provider: Text naming what the embed is, for example ``"YouTube video"``.
+    :param action: The load button text, for example ``"Load video"``.
+    :param link_href: Direct URL of the original content, unescaped.
+    :param link_text: The direct link text.
+    :returns: The preview HTML.
+    """
+    script_attr = f' data-mw-script="{html.escape(script_src)}"' if script_src is not None else ""
+    return (
+        f'<div class="mw-embed" data-mw-version="{PREVIEW_VERSION}" data-mw-embed="{embed}"'
+        f' data-mw-load="{load}"{script_attr}>\n'
+        f'    <template class="mw-embed-content">{content}</template>\n'
+        f'    <div class="mw-embed-preview">\n'
+        f'        <p class="mw-embed-provider">{provider}</p>\n'
+        f'        <button type="button" class="mw-embed-load">{action}</button>\n'
+        f'        <a class="mw-embed-link" href="{html.escape(link_href)}">{link_text}</a>\n'
+        f"    </div>\n"
+        f"</div>"
+    )

markwright-0.3.0/src/markwright/_fences.py

@@ -0,0 +1,107 @@
+# ABOUTME: Shared scanner for fenced code blocks in Markdown source, following CommonMark's fence rules.
+# Used by the fence pre stage (directive extraction) and the highlight pre stage (skipping code) so both agree.
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict
+
+# An opening fence: indentation, then three or more backticks or tildes, then the info string
+_FENCE_OPEN_RE = re.compile(r"^(?P<indent>[ ]*)(?P<marker>`{3,}|~{3,})(?P<info>.*)$")
+# A list item's first line: indentation, a bullet or ordinal marker, then content
+_LIST_ITEM_RE = re.compile(r"^(?P<indent>[ ]*)(?:[-*+]|\d{1,9}[.)])[ ]+\S")
+
+
+class FencedBlock(BaseModel):
+    """A closed fenced code block found in Markdown source.
+
+    :ivar opening: Line index of the opening fence.
+    :ivar closing: Line index of the closing fence.
+    :ivar indent: The opening fence's indentation, repeated on lines the pre stage inserts.
+    :ivar marker: The opening fence run, for example ``\\`\\`\\``` or ``~~~~``.
+    :ivar info: The info string after the opening fence, unstripped.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    opening: int
+    closing: int
+    indent: str
+    marker: str
+    info: str
+
+
+def find_fenced_blocks(lines: list[str]) -> list[FencedBlock]:
+    """Find the closed fenced code blocks in Markdown source lines.
+
+    Follows CommonMark: an opening fence is indented up to three spaces (or sits inside a list
+    item, under the item's content), a backtick fence's info string holds no backtick, and the
+    closing fence uses the same character, is at least as long, and carries nothing else. An
+    unclosed fence is not a code block, matching ``pymdownx.superfences``.
+
+    :param lines: Source lines.
+    :returns: The fenced blocks in source order; nested fences inside a block are content.
+    """
+    blocks: list[FencedBlock] = []
+    line_index = 0
+    while line_index < len(lines):
+        open_match = _FENCE_OPEN_RE.match(lines[line_index])
+        if (
+            open_match is None
+            or (open_match["marker"][0] == "`" and "`" in open_match["info"])
+            or not _fence_can_open(lines, line_index, len(open_match["indent"]))
+        ):
+            line_index += 1
+            continue
+
+        # The closing fence: same character, at least as long, nothing after it
+        marker = open_match["marker"]
+        closing = next(
+            (
+                scan_index
+                for scan_index in range(line_index + 1, len(lines))
+                if (stripped := lines[scan_index].strip()).startswith(marker)
+                and set(stripped) == {marker[0]}
+                and len(lines[scan_index]) - len(lines[scan_index].lstrip(" ")) <= len(open_match["indent"]) + 3
+            ),
+            None,
+        )
+        if closing is None:
+            line_index += 1
+            continue
+
+        blocks.append(
+            FencedBlock(
+                opening=line_index,
+                closing=closing,
+                indent=open_match["indent"],
+                marker=marker,
+                info=open_match["info"],
+            )
+        )
+        line_index = closing + 1
+    return blocks
+
+
+def _fence_can_open(lines: list[str], line_index: int, indent_width: int) -> bool:
+    """Report whether a fence-shaped line at this indentation opens a fence or is indented code.
+
+    Up to three spaces always opens a fence. Four or more opens one only inside a list item: the
+    nearest earlier non-blank line indented less than the fence must be a list item, and the fence
+    must sit at or past that item's content.
+
+    :param lines: Source lines.
+    :param line_index: Index of the fence-shaped line.
+    :param indent_width: The line's indentation in spaces.
+    :returns: ``True`` if the line opens a fence.
+    """
+    if indent_width <= 3:
+        return True
+    for earlier_line in reversed(lines[:line_index]):
+        earlier_indent = len(earlier_line) - len(earlier_line.lstrip(" "))
+        if not earlier_line.strip() or earlier_indent >= indent_width:
+            continue
+        item_match = _LIST_ITEM_RE.match(earlier_line)
+        return item_match is not None and indent_width >= len(item_match["indent"]) + 2
+    return False