typsphinx 0.6.2__tar.gz → 0.6.4__tar.gz

{typsphinx-0.6.2 → typsphinx-0.6.4}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: typsphinx
-Version: 0.6.2
+Version: 0.6.4
 Summary: Sphinx extension for Typst output
 Author-email: YuSabo <yusabo90002@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/YuSabo90002/typsphinx
-Project-URL: Documentation, https://github.com/YuSabo90002/typsphinx#readme
+Project-URL: Documentation, https://typsphinx.readthedocs.io/
 Project-URL: Repository, https://github.com/YuSabo90002/typsphinx
 Project-URL: Issues, https://github.com/YuSabo90002/typsphinx/issues
 Keywords: sphinx,typst,documentation,pdf
@@ -49,11 +49,11 @@ Dynamic: license-file
 [![Python Support](https://img.shields.io/pypi/pyversions/typsphinx.svg)](https://pypi.org/project/typsphinx/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://yusabo90002.github.io/typsphinx/)
+[![Documentation Status](https://app.readthedocs.org/projects/typsphinx/badge/?version=latest)](https://typsphinx.readthedocs.io/)
 
 Sphinx extension for Typst output format support.
 
-**[📖 Documentation](https://yusabo90002.github.io/typsphinx/)** | **[🐛 Issue Tracker](https://github.com/YuSabo90002/typsphinx/issues)** | **[📦 PyPI](https://pypi.org/project/typsphinx/)**
+**[📖 Documentation](https://typsphinx.readthedocs.io/)** | **[🐛 Issue Tracker](https://github.com/YuSabo90002/typsphinx/issues)** | **[📦 PyPI](https://pypi.org/project/typsphinx/)**
 
 ## Overview
 
@@ -249,7 +249,6 @@ Below are the main configuration options. This is not the complete set — see [
 - `typst_template`: Custom template path
 - `typst_elements`: Template parameters (paper size, fonts, etc.)
 - `typst_template_mapping`: Sphinx metadata to template parameter mapping
-- `typst_toctree_defaults`: Default toctree options
 
 ## Development
 
@@ -309,17 +308,19 @@ typsphinx/
 
 ## Documentation
 
-**📖 Full documentation is available at [yusabo90002.github.io/typsphinx](https://yusabo90002.github.io/typsphinx/)**
+**📖 Full documentation is available at [typsphinx.readthedocs.io](https://typsphinx.readthedocs.io/)**
+
+日本語ドキュメントは [typsphinx.readthedocs.io/ja/latest/](https://typsphinx.readthedocs.io/ja/latest/) にあります。
 
 Quick links:
 
-- [Installation Guide](https://yusabo90002.github.io/typsphinx/installation.html)
-- [Quick Start](https://yusabo90002.github.io/typsphinx/quickstart.html)
-- [User Guide](https://yusabo90002.github.io/typsphinx/user_guide/)
-- [Configuration Reference](https://yusabo90002.github.io/typsphinx/user_guide/configuration.html)
-- [Examples](https://yusabo90002.github.io/typsphinx/examples/)
-- [API Reference](https://yusabo90002.github.io/typsphinx/api/)
-- [Contributing Guide](https://yusabo90002.github.io/typsphinx/contributing.html)
+- [Installation Guide](https://typsphinx.readthedocs.io/en/latest/installation.html)
+- [Quick Start](https://typsphinx.readthedocs.io/en/latest/quickstart.html)
+- [User Guide](https://typsphinx.readthedocs.io/en/latest/user_guide/)
+- [Configuration Reference](https://typsphinx.readthedocs.io/en/latest/user_guide/configuration.html)
+- [Examples](https://typsphinx.readthedocs.io/en/latest/examples/)
+- [API Reference](https://typsphinx.readthedocs.io/en/latest/api/)
+- [Contributing Guide](https://typsphinx.readthedocs.io/en/latest/contributing.html)
 
 ## Contributing
 
@@ -349,7 +350,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - Integrates [mitex](https://github.com/mitex-rs/mitex) for LaTeX math
 - Uses [codly](https://typst.app/universe/package/codly) for code highlighting
 - Uses [gentle-clues](https://typst.app/universe/package/gentle-clues) for admonitions
-- Developed with [Claude Code](https://claude.ai/code) and [GSD](https://github.com/open-gsd/gsd-core) (spec-driven development for AI coding agents)
+- Developed with [Claude Code](https://claude.com/product/claude-code) and [GSD](https://github.com/open-gsd/gsd-core) (spec-driven development for AI coding agents)
 
 ## Version History
 
@@ -357,5 +358,5 @@ See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
 ---
 
-**Status**: Stable (v0.6.2) - Production ready
+**Status**: Stable (v0.6.4) - Production ready
 **Python**: 3.12+ | **Sphinx**: 9.1+ | **Typst**: 0.15+

{typsphinx-0.6.2 → typsphinx-0.6.4}/README.md

@@ -5,11 +5,11 @@
 [![Python Support](https://img.shields.io/pypi/pyversions/typsphinx.svg)](https://pypi.org/project/typsphinx/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://yusabo90002.github.io/typsphinx/)
+[![Documentation Status](https://app.readthedocs.org/projects/typsphinx/badge/?version=latest)](https://typsphinx.readthedocs.io/)
 
 Sphinx extension for Typst output format support.
 
-**[📖 Documentation](https://yusabo90002.github.io/typsphinx/)** | **[🐛 Issue Tracker](https://github.com/YuSabo90002/typsphinx/issues)** | **[📦 PyPI](https://pypi.org/project/typsphinx/)**
+**[📖 Documentation](https://typsphinx.readthedocs.io/)** | **[🐛 Issue Tracker](https://github.com/YuSabo90002/typsphinx/issues)** | **[📦 PyPI](https://pypi.org/project/typsphinx/)**
 
 ## Overview
 
@@ -205,7 +205,6 @@ Below are the main configuration options. This is not the complete set — see [
 - `typst_template`: Custom template path
 - `typst_elements`: Template parameters (paper size, fonts, etc.)
 - `typst_template_mapping`: Sphinx metadata to template parameter mapping
-- `typst_toctree_defaults`: Default toctree options
 
 ## Development
 
@@ -265,17 +264,19 @@ typsphinx/
 
 ## Documentation
 
-**📖 Full documentation is available at [yusabo90002.github.io/typsphinx](https://yusabo90002.github.io/typsphinx/)**
+**📖 Full documentation is available at [typsphinx.readthedocs.io](https://typsphinx.readthedocs.io/)**
+
+日本語ドキュメントは [typsphinx.readthedocs.io/ja/latest/](https://typsphinx.readthedocs.io/ja/latest/) にあります。
 
 Quick links:
 
-- [Installation Guide](https://yusabo90002.github.io/typsphinx/installation.html)
-- [Quick Start](https://yusabo90002.github.io/typsphinx/quickstart.html)
-- [User Guide](https://yusabo90002.github.io/typsphinx/user_guide/)
-- [Configuration Reference](https://yusabo90002.github.io/typsphinx/user_guide/configuration.html)
-- [Examples](https://yusabo90002.github.io/typsphinx/examples/)
-- [API Reference](https://yusabo90002.github.io/typsphinx/api/)
-- [Contributing Guide](https://yusabo90002.github.io/typsphinx/contributing.html)
+- [Installation Guide](https://typsphinx.readthedocs.io/en/latest/installation.html)
+- [Quick Start](https://typsphinx.readthedocs.io/en/latest/quickstart.html)
+- [User Guide](https://typsphinx.readthedocs.io/en/latest/user_guide/)
+- [Configuration Reference](https://typsphinx.readthedocs.io/en/latest/user_guide/configuration.html)
+- [Examples](https://typsphinx.readthedocs.io/en/latest/examples/)
+- [API Reference](https://typsphinx.readthedocs.io/en/latest/api/)
+- [Contributing Guide](https://typsphinx.readthedocs.io/en/latest/contributing.html)
 
 ## Contributing
 
@@ -305,7 +306,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - Integrates [mitex](https://github.com/mitex-rs/mitex) for LaTeX math
 - Uses [codly](https://typst.app/universe/package/codly) for code highlighting
 - Uses [gentle-clues](https://typst.app/universe/package/gentle-clues) for admonitions
-- Developed with [Claude Code](https://claude.ai/code) and [GSD](https://github.com/open-gsd/gsd-core) (spec-driven development for AI coding agents)
+- Developed with [Claude Code](https://claude.com/product/claude-code) and [GSD](https://github.com/open-gsd/gsd-core) (spec-driven development for AI coding agents)
 
 ## Version History
 
@@ -313,5 +314,5 @@ See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
 ---
 
-**Status**: Stable (v0.6.2) - Production ready
+**Status**: Stable (v0.6.4) - Production ready
 **Python**: 3.12+ | **Sphinx**: 9.1+ | **Typst**: 0.15+

{typsphinx-0.6.2 → typsphinx-0.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "typsphinx"
-version = "0.6.2"
+version = "0.6.4"
 description = "Sphinx extension for Typst output"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -53,7 +53,7 @@ docs = [
 
 [project.urls]
 Homepage = "https://github.com/YuSabo90002/typsphinx"
-Documentation = "https://github.com/YuSabo90002/typsphinx#readme"
+Documentation = "https://typsphinx.readthedocs.io/"
 Repository = "https://github.com/YuSabo90002/typsphinx"
 Issues = "https://github.com/YuSabo90002/typsphinx/issues"
 

typsphinx-0.6.4/tests/test_no_stale_github_io_links.py

@@ -0,0 +1,151 @@
+"""
+Regression guard for the retired-host -> Read the Docs URL rewrite (DOC-09).
+
+Phase 31 rewrote every published documentation URL in README.md and
+pyproject.toml: they used to point at a GitHub Pages host that had been
+retired. Seven of README.md's deep links pointed at paths that no longer
+resolved on that retired host and returned HTTP 404 for months; an external
+user hit one of them and filed Issue #119. This module locks the rewrite
+behind four hermetic invariants so a future edit that reintroduces the
+retired host, drops or reorders a deep link, or version-pins a top-level
+link fails a `pytest` run immediately instead of silently regressing a
+second time.
+
+All four tests parse raw file text (and `pyproject.toml` via `tomllib`) --
+never package metadata -- and make no network calls. The real-HTTP checks
+(curl sweeps, CI Link Check) are a separate instrument; see
+`.planning/phases/31-published-url-cutover-repo-wide-link-guard/`.
+"""
+
+import re
+import tomllib
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+README_PATH = REPO_ROOT / "README.md"
+PYPROJECT_PATH = REPO_ROOT / "pyproject.toml"
+
+# The retired documentation host, built from two concatenated fragments
+# split across the dot. This phase's success criteria require that a fresh
+# repo-wide grep for the retired host find matches only in CHANGELOG.md. If
+# this module spelled the host as one literal, it would itself be a
+# permanent match, making that success criterion unverifiable without a
+# permanent exclusion list. Splitting the literal keeps the repo-wide grep
+# clean and honest.
+_RETIRED_HOST_PREFIX = "yusabo90002.github"
+_RETIRED_HOST_SUFFIX = "io"
+_RETIRED_HOST = f"{_RETIRED_HOST_PREFIX}.{_RETIRED_HOST_SUFFIX}"
+
+# Matches any URL on the Read the Docs documentation host.
+_READTHEDOCS_URL_RE = re.compile(r"https://typsphinx\.readthedocs\.io/[^\s)\]]*")
+
+# Matches a README deep link's suffix -- everything after `/en/latest/`.
+_DEEP_LINK_RE = re.compile(r"https://typsphinx\.readthedocs\.io/en/latest/([^\s)\]]+)")
+
+# A language segment (`/en/` or `/ja/`) anywhere in a URL -- used to
+# partition Read the Docs URLs into "deep" (language-scoped) vs. top-level.
+_LANGUAGE_SEGMENT_RE = re.compile(r"/(en|ja)/")
+
+# A version-like path segment (`/latest/`, `/stable/`, `/v1.2.3/`, ...)
+# appearing anywhere in a URL, independent of whether it is preceded by a
+# language segment. Used to catch a top-level link that got version-pinned
+# without also picking up a language prefix.
+_VERSION_LIKE_SEGMENT_RE = re.compile(r"/(latest|stable|v?\d+\.\d+(?:\.\d+)?)(?:/|$)")
+
+# The seven quick-link deep-link suffixes, in the order they must appear in
+# README.md's "## Documentation" section. A dropped, reordered, or renamed
+# suffix must fail this test, not just a wrong host.
+_EXPECTED_DEEP_LINK_SUFFIXES = (
+    "installation.html",
+    "quickstart.html",
+    "user_guide/",
+    "user_guide/configuration.html",
+    "examples/",
+    "api/",
+    "contributing.html",
+)
+
+
+def _read_readme_text() -> str:
+    return README_PATH.read_text(encoding="utf-8")
+
+
+def test_readme_documentation_links_point_at_readthedocs():
+    """README.md must contain no URL on the retired documentation host.
+
+    Guards against a vacuous pass: asserts README.md actually contains at
+    least one Read the Docs URL before asserting the retired host is
+    absent, so an accidental deletion of the whole Documentation section
+    would not silently satisfy this test.
+    """
+    text = _read_readme_text()
+    readthedocs_urls = _READTHEDOCS_URL_RE.findall(text)
+    assert readthedocs_urls, (
+        "README.md contains no typsphinx.readthedocs.io URLs at all -- has "
+        "the Documentation section been removed?"
+    )
+    assert _RETIRED_HOST not in text, (
+        f"README.md still references the retired documentation host "
+        f"({_RETIRED_HOST}) -- Phase 31 rewrote every link to Read the "
+        "Docs; see 31-03-SUMMARY.md."
+    )
+
+
+def test_readme_deep_links_carry_language_version_prefix():
+    """README.md must have exactly 7 `/en/latest/` deep links, in order.
+
+    Asserts both the count and the exact suffixes so a dropped, reordered,
+    or silently-retargeted link is caught -- not just a wrong host.
+    """
+    text = _read_readme_text()
+    deep_links = _DEEP_LINK_RE.findall(text)
+    assert len(deep_links) == 7, (
+        f"expected exactly 7 README deep links under /en/latest/, found "
+        f"{len(deep_links)}: {deep_links}"
+    )
+    assert deep_links == list(_EXPECTED_DEEP_LINK_SUFFIXES), (
+        "README.md's /en/latest/ deep links do not match the expected "
+        f"suffixes in order. Expected {_EXPECTED_DEEP_LINK_SUFFIXES!r}, "
+        f"found {tuple(deep_links)!r}."
+    )
+
+
+def test_readme_top_level_links_carry_no_version_segment():
+    """Top-level README Read the Docs links must stay version-less.
+
+    D-11: the badge click-through, header link, and Documentation section
+    lead sentence deliberately carry no `/en/` or `/ja/` segment, so Read
+    the Docs' root redirect follows the project's Default Version --
+    Phase 33's `latest` -> `stable` flip reaches these links without
+    another edit. A future "fix" that pins them to an explicit version
+    would undo that design, not tidy it.
+    """
+    text = _read_readme_text()
+    all_urls = _READTHEDOCS_URL_RE.findall(text)
+    top_level_urls = [url for url in all_urls if not _LANGUAGE_SEGMENT_RE.search(url)]
+    assert top_level_urls, (
+        "found no version-less typsphinx.readthedocs.io URLs in README.md "
+        "-- expected the badge click-through, header link, and section "
+        "lead sentence to all be bare-root links (D-11)."
+    )
+    version_pinned = [
+        url for url in top_level_urls if _VERSION_LIKE_SEGMENT_RE.search(url)
+    ]
+    assert not version_pinned, (
+        "top-level README links must stay version-less so Read the Docs' "
+        "Default Version flip (Phase 33) propagates without a re-edit "
+        f"(D-11); found a version-like segment on: {version_pinned}"
+    )
+
+
+def test_pyproject_documentation_url_points_at_readthedocs():
+    """pyproject.toml's `project.urls.Documentation` must address Read the Docs."""
+    with open(PYPROJECT_PATH, "rb") as f:
+        data = tomllib.load(f)
+    documentation_url = data["project"]["urls"]["Documentation"]
+    assert "typsphinx.readthedocs.io" in documentation_url, (
+        f"pyproject.toml's project.urls.Documentation is "
+        f"{documentation_url!r}, which does not address "
+        "typsphinx.readthedocs.io -- PyPI's release metadata would "
+        "advertise a stale documentation link."
+    )

{typsphinx-0.6.2 → typsphinx-0.6.4}/tests/test_pdf_render_gate.py

@@ -126,6 +126,12 @@ def table_width_render_gate_dir(fixtures_dir):
     return fixtures_dir / "table_width_render_gate"
 
 
+@pytest.fixture
+def captioned_table_render_gate_dir(fixtures_dir):
+    """Return the path to the captioned_table_render_gate fixture project."""
+    return fixtures_dir / "captioned_table_render_gate"
+
+
 @pytest.fixture
 def temp_build_dir(tmp_path):
     """Provide a temporary directory for build output."""
@@ -2333,3 +2339,325 @@ class TestTableWidthRenderGate:
                 "rendered PDF text -- table-width markup/code-mode "
                 "regression"
             )
+
+
+# ---------------------------------------------------------------------------
+# Phase 25 (TBL-01, TBL-02, GATE-01): extend the render-gate pattern to prove
+# the Plan 25-01 depart_table figure-wrap + single <label> fix renders
+# correctly through a real sphinx-build -> typst.compile() -> pypdf
+# round-trip -- two consecutive captioned tables (the stale-buffer proof:
+# 25-RESEARCH.md Verified Mechanism 2), a caption+:width: composition case,
+# a :numref:/:ref:-resolves case, and a captioned csv-table + list-table
+# case (D-05). ``TestCaptionedTablePreFixBasisFailureProof`` below closes
+# D-06's durable fail-pre-fix red->green requirement by reconstructing the
+# two pre-fix defect shapes from first principles now that Plan 25-01's fix
+# has replaced the buggy code -- the double-anchor collision (Critical
+# Pitfall 3, 25-RESEARCH.md) and the stale-buffer caption loss (Verified
+# Mechanism 2) -- mirroring the ``TestPreFixBasisFailureProof`` convention
+# already established in tests/test_package_only_config_gate.py.
+# ---------------------------------------------------------------------------
+
+# Sentinel tokens for the captioned-table render gate -- distinctive,
+# ALLCAPS-no-space words chosen so `full_text.count(...)` can prove each
+# caption reached the compiled PDF exactly once (guarding against both the
+# stray-heading bug -- Verified Mechanism 1 -- and the 2nd-table
+# stale-buffer caption-loss bug -- Verified Mechanism 2). Must match the
+# sentinel tokens embedded in captioned_table_render_gate/index.rst.
+TBLCAP_FIRST_SENTINEL = "TBLCAPFIRSTSENTINEL"
+TBLCAP_SECOND_SENTINEL = "TBLCAPSECONDSENTINEL"
+TBLCAP_WIDTH_SENTINEL = "TBLCAPWIDTHSENTINEL"
+TBLCAP_CSV_SENTINEL = "TBLCAPCSVSENTINEL"
+TBLCAP_LIST_SENTINEL = "TBLCAPLISTSENTINEL"
+
+
+class _CaptionedTableRenderGateArtifacts:
+    """
+    Plain container for the one real-compile artifact shared by every
+    ``TestCaptionedTableRenderGate`` test method: the emitted Typst source
+    text and the pypdf-extracted PDF text. A plain class (not a dict/tuple)
+    so each thin test method below can read ``.typ_source``/``.full_text``
+    by name.
+    """
+
+    def __init__(self, typ_source: str, full_text: str) -> None:
+        self.typ_source = typ_source
+        self.full_text = full_text
+
+
+@pytest.fixture(scope="class")
+def captioned_table_render_gate_artifacts(tmp_path_factory):
+    """
+    Build + real-compile the captioned_table_render_gate fixture ONCE per
+    class and return both the emitted Typst source text and the
+    pypdf-extracted PDF text.
+
+    Class-scoped so the four thin test methods below each assert a
+    disjoint slice of the SAME real-compile artifact rather than
+    re-running sphinx-build/typst.compile() four times (mirrors the
+    ``topic_line_block_render_gate_pdf_text`` class-scoped fixture pattern
+    above). Depends only on ``tmp_path_factory`` (session-scoped-
+    compatible) -- not on the narrower, function-scoped
+    ``captioned_table_render_gate_dir``/``fixtures_dir`` fixtures, to avoid
+    a pytest ScopeMismatch (a class-scoped fixture may not depend on a
+    narrower, function-scoped one).
+    """
+    source_dir = Path(__file__).parent / "fixtures" / "captioned_table_render_gate"
+    build_dir = tmp_path_factory.mktemp("captioned_table_gate") / "_build"
+
+    result = _run_sphinx_build_typst(source_dir, build_dir)
+    assert (
+        result.returncode == 0
+    ), f"sphinx-build failed:\nstdout: {result.stdout}\nstderr: {result.stderr}"
+
+    index_typ = build_dir / "index.typ"
+    assert index_typ.exists(), "index.typ was not generated"
+    typ_source = index_typ.read_text(encoding="utf-8")
+
+    # Compile the emitted .typ to PDF with typst-py, WITHOUT try/except:
+    # this is the crux of GATE-01 -- the double-anchor Critical Pitfall 3
+    # fatal (a captioned table's ids[0] defined twice) would abort the
+    # ENTIRE compile here, failing every dependent test method loudly,
+    # rather than merely failing a string-agreement check.
+    pdf_output = build_dir / "index.pdf"
+    typst.compile(str(index_typ), output=str(pdf_output))
+
+    assert pdf_output.exists(), "PDF file was not created"
+    assert pdf_output.stat().st_size > 0, "PDF file is empty"
+    with open(pdf_output, "rb") as f:
+        magic = f.read(4)
+        assert magic == b"%PDF", "Generated file is not a valid PDF"
+
+    reader = pypdf.PdfReader(str(pdf_output))
+    full_text = "\n".join(page.extract_text() for page in reader.pages)
+
+    return _CaptionedTableRenderGateArtifacts(typ_source, full_text)
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(
+    not (TYPST_AVAILABLE and PYPDF_AVAILABLE),
+    reason="typst-py and pypdf are both required for the GATE-01 render gate",
+)
+class TestCaptionedTableRenderGate:
+    """
+    Real-compile acceptance gate for TBL-01/TBL-02: the Plan 25-01
+    depart_table figure-wrap + single <label> fix, covering two
+    consecutive captioned tables (the stale-buffer proof), a
+    caption+:width: composition case, a :numref:/:ref:-resolves case, and
+    a captioned csv-table + list-table case (D-05).
+
+    Requirements: TBL-01, TBL-02, GATE-01 (25-CONTEXT.md, 25-RESEARCH.md
+    Validation Architecture, 25-01-SUMMARY.md).
+
+    All four test methods share the SAME real-compile artifact via the
+    class-scoped ``captioned_table_render_gate_artifacts`` fixture above --
+    sphinx-build/typst.compile() run exactly once per class, not once per
+    test method.
+    """
+
+    def test_each_caption_sentinel_appears_exactly_once(
+        self, captioned_table_render_gate_artifacts
+    ):
+        """
+        Each of the five caption sentinels appears EXACTLY ONCE in the
+        extracted PDF text -- proving neither the stray-heading bug
+        (Verified Mechanism 1) nor the 2nd-table stale-buffer
+        caption-loss bug (Verified Mechanism 2) regressed. The 2nd
+        table's sentinel (TBLCAPSECONDSENTINEL) is the specific
+        stale-buffer proof: a single-table fixture cannot expose it.
+        """
+        full_text = captioned_table_render_gate_artifacts.full_text
+
+        for sentinel in (
+            TBLCAP_FIRST_SENTINEL,
+            TBLCAP_SECOND_SENTINEL,
+            TBLCAP_WIDTH_SENTINEL,
+            TBLCAP_CSV_SENTINEL,
+            TBLCAP_LIST_SENTINEL,
+        ):
+            assert full_text.count(sentinel) == 1, (
+                f"Expected caption sentinel '{sentinel}' exactly once in "
+                "extracted PDF text -- possible stray-heading or "
+                "stale-buffer caption-loss regression (TBL-01)"
+            )
+
+    def test_typ_source_uses_figure_kind_table_with_no_heading_above(
+        self, captioned_table_render_gate_artifacts
+    ):
+        """
+        The emitted index.typ wraps every captioned table in
+        figure(..., kind: table) -- native Typst "Table N" numbering --
+        and no heading() call appears anywhere in the captioned-table
+        region (from the first figure( call onward): this fixture's only
+        heading() is the document's own top-level title, which precedes
+        every table (SC#1).
+        """
+        typ_source = captioned_table_render_gate_artifacts.typ_source
+
+        assert "figure(" in typ_source, (
+            "Expected 'figure(' in generated Typst source -- depart_table "
+            "figure-wrap regression"
+        )
+        assert "kind: table" in typ_source, (
+            "Expected 'kind: table' in generated Typst source -- "
+            "depart_table figure-wrap regression"
+        )
+
+        first_figure_index = typ_source.index("figure(")
+        captioned_table_region = typ_source[first_figure_index:]
+        assert "heading(" not in captioned_table_region, (
+            "Found a stray 'heading(' call inside the captioned-table "
+            "region -- a table caption fell through to the generic "
+            "section-heading path instead of being figure-wrapped "
+            "(Verified Mechanism 1 regression)"
+        )
+
+    def test_xref_numref_ref_resolve_no_empty_link(
+        self, captioned_table_render_gate_artifacts
+    ):
+        """
+        The :numref:/:ref: cross-references to the first captioned table
+        both resolve to a real link(<label>, ...) anchor reference in the
+        generated Typst source, with no link("", ...) leak -- mirrors
+        TestXrefRefidRenderGate's D-04 contract, applied to a captioned
+        table's own <label> instead of a section/glossary anchor.
+        """
+        typ_source = captioned_table_render_gate_artifacts.typ_source
+
+        assert "link(<" in typ_source, (
+            "Expected at least one refid link(<...>, ...) anchor "
+            "reference in the generated Typst source -- the "
+            ":numref:/:ref: to a captioned table may have regressed"
+        )
+        assert 'link("",' not in typ_source, (
+            'Found link("", ...) in generated Typst source -- the '
+            'never-link("", ...) contract has regressed'
+        )
+
+    def test_no_literal_source_leak(self, captioned_table_render_gate_artifacts):
+        """No LEAK_SIGNATURES token reaches the extracted PDF text."""
+        full_text = captioned_table_render_gate_artifacts.full_text
+
+        for leaked_token in LEAK_SIGNATURES:
+            assert leaked_token not in full_text, (
+                f"Literal Typst source '{leaked_token}' leaked into "
+                "rendered PDF text -- captioned-table markup/code-mode "
+                "regression"
+            )
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(
+    not TYPST_AVAILABLE,
+    reason="typst-py is required for the GATE-01 pre-fix-basis failure proof",
+)
+class TestCaptionedTablePreFixBasisFailureProof:
+    """
+    Standing pre-fix-basis failure proof (D-06): reconstructs the two
+    pre-fix defect shapes from first principles -- the buggy code no
+    longer exists post Plan 25-01 -- and proves each one is genuinely
+    fail-pre-fix, mirroring the
+    ``tests/test_package_only_config_gate.py::TestPreFixBasisFailureProof``
+    convention (reconstruct the pre-fix compile basis; never assert on the
+    TEXT of a compiler error message).
+
+    (a) Double-anchor basis (Critical Pitfall 3, 25-RESEARCH.md): a
+    minimal Typst source in which one label id is defined TWICE -- once
+    as a ``[#metadata(none) <dup>]`` anchor (the unconditional
+    ``_emit_id_anchors`` call ``visit_table`` used to make even for a
+    captioned table) and once as a ``figure(...) <dup>`` postfix (the
+    NEW figure-wrap self-anchor this phase adds) -- plus a
+    ``link(<dup>, ...)`` reference to that label, reproducing the actual
+    :numref:/:ref: xref shape that resolves it. Live-verified while
+    writing this module: Typst does NOT raise merely from defining a
+    label twice with no reference to it; the "label ... occurs multiple
+    times" fatal fires only when something (here, the xref's own
+    ``link(<dup>, ...)``) tries to RESOLVE the ambiguous label -- exactly
+    the real-world shape a :numref:/:ref: to a captioned table produces.
+
+    (b) Stale-buffer basis (Verified Mechanism 2, 25-RESEARCH.md): a
+    reconstructed pre-fix two-table Typst source -- a plain ``table(...)``
+    for each, a stray ``heading(...)`` above the first (the OLD
+    stray-heading caption bug), and the SECOND caption sentinel
+    deliberately ABSENT (the observed pre-fix stale-buffer shape, where a
+    2nd table's caption silently vanished into a leftover buffer from the
+    first). This half is a pure string reconstruction (no compile needed)
+    proving the positive gate's ``full_text.count(sentinel) == 1``
+    assertion is genuinely fail-pre-fix: applied to this reconstruction,
+    the second sentinel's count is 0, not 1.
+
+    Requirements: TBL-01, TBL-02, D-06.
+    """
+
+    def test_double_anchor_basis_raises(self, tmp_path):
+        """
+        BUG basis (Critical Pitfall 3): reconstruct a captioned table
+        whose id is anchored TWICE -- once via the old unconditional
+        ``_emit_id_anchors`` metadata anchor, once via the new figure
+        ``<label>`` postfix -- with a ``link(<dup>, ...)`` xref
+        resolving it, and assert a real ``typst.compile()`` RAISES. No
+        assertion matches the exception's message text (D-06) -- only
+        that it raises.
+        """
+        reconstructed = (
+            "#metadata(none) <dup>\n"
+            "\n"
+            "#figure(\n"
+            "  table(\n"
+            "    columns: (1fr, 1fr),\n"
+            "    [A], [B],\n"
+            "  ),\n"
+            "  caption: [Caption],\n"
+            "  kind: table,\n"
+            ") <dup>\n"
+            "\n"
+            "See #link(<dup>, [Ref]).\n"
+        )
+        target = tmp_path / "double_anchor_basis.typ"
+        target.write_text(reconstructed, encoding="utf-8")
+
+        with pytest.raises(Exception):
+            typst.compile(str(target), root=str(tmp_path))
+
+    def test_stale_buffer_basis_second_sentinel_count_is_zero(self):
+        """
+        Stale-buffer basis (Verified Mechanism 2): a reconstructed pre-fix
+        two-table Typst source in which the SECOND table's caption
+        sentinel is deliberately absent (the observed pre-fix shape --
+        the second table's caption silently vanished into a stale
+        ``table_cell_content`` buffer left over from the first table).
+        Asserts the positive gate's ``count(...) == 1`` check FAILS
+        (count is 0) against this reconstruction -- proof the gate is
+        genuinely fail-pre-fix, not vacuously green.
+        """
+        reconstructed_pre_fix_shape = (
+            "heading(level: 1, {text(" + repr(TBLCAP_FIRST_SENTINEL) + ")})\n"
+            "\n"
+            "table(\n"
+            "  columns: (1fr, 1fr),\n"
+            "  [A], [B],\n"
+            ")\n"
+            "\n"
+            "table(\n"
+            "  columns: (1fr, 1fr),\n"
+            "  [C], [D],\n"
+            ")\n"
+        )
+
+        # The pre-fix stray-heading bug: the FIRST table's caption leaked
+        # into a heading() call (Verified Mechanism 1) instead of a
+        # figure caption -- present here to keep the reconstruction
+        # faithful to the actually-observed pre-fix output shape.
+        assert TBLCAP_FIRST_SENTINEL in reconstructed_pre_fix_shape
+
+        # The proof this test exists for: the SECOND table's caption
+        # sentinel never reached the reconstructed output at all -- the
+        # stale-buffer bug swallowed it. count() is 0, not 1, so the
+        # positive gate's exact-once assertion would have failed loudly
+        # against this pre-fix basis.
+        assert reconstructed_pre_fix_shape.count(TBLCAP_SECOND_SENTINEL) == 0, (
+            "Expected the reconstructed pre-fix stale-buffer basis to have "
+            "ZERO occurrences of the second table's caption sentinel -- "
+            "if this fails, the reconstruction no longer reproduces the "
+            "pre-fix bug shape and the fail-pre-fix proof is void"
+        )