py-visactor-katex 0.1.0__tar.gz

py_visactor_katex-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 — 2026-11-06
+
+First stable release of the native Python static mathematics renderer, based on
+the pinned KaTeX 0.18.11 core.
+
+- TeX parsing, scoped and persistent macros, display settings and diagnostics.
+- Fractions, radicals, scripts, stretchy delimiters, accents and decorations.
+- Arrays, AMS/CD environments, equation tags and numbering.
+- Twenty bundled math fonts and original metrics; explicit offline resources.
+- Static HTML style adaptation and accurate painted bounds.
+- Native PNG, JPEG, WebP, SVG and PDF output using public py-skia-canvas APIs.
+- `py-katex` command-line entry point and independent library APIs.
+
+The core-static acceptance covers 973 test methods, 684 registration/macro
+contexts, 1,909 upstream functional inputs, 217 equivalence pairs and 275
+standalone/integration cases on CPU, auto and GPU in the recorded Windows
+environment. Those records describe the original accepted development candidate;
+release installation and artifact checks are recorded separately.
+
+HTML/MathML serialization, arbitrary browser CSS, browser interactions and
+independent contrib plugins (including mhchem) are outside this release's core
+static scope. Non-math Unicode fonts can be supplied explicitly; platform fonts
+are not a universal offline font collection.

py_visactor_katex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 py-VisActor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_visactor_katex-0.1.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE THIRD_PARTY_NOTICES.md README.md CHANGELOG.md pyproject.toml
+include references/upstream.lock.json references/full-core-inventory.json
+include references/full-runtime-registry.json references/full-verification-summary.json
+recursive-include references/licenses *
+recursive-include src/py_katex *.py *.json *.ttf py.typed
+recursive-include tests *.py *.json *.png *.svg *.ttf
+recursive-include tools *.py *.cjs *.mjs *.html *.json *.md
+recursive-include docs *.md *.json
+global-exclude __pycache__ *.py[cod]
+prune .local
+prune .github
+prune test-runs
+prune reports
+prune build
+prune dist

py_visactor_katex-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: py-visactor-katex
+Version: 0.1.0
+Summary: Native Python TeX math layout and static rendering with bundled KaTeX fonts
+License-Expression: MIT
+Project-URL: Repository, https://github.com/py-VisActor/py-katex
+Project-URL: Documentation, https://github.com/py-VisActor/py-katex/blob/main/README.md
+Project-URL: Issues, https://github.com/py-VisActor/py-katex/issues
+Project-URL: Changelog, https://github.com/py-VisActor/py-katex/blob/main/CHANGELOG.md
+Keywords: tex,latex,math,katex,rendering,svg,pdf
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: <3.14,>=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: references/licenses/katex-LICENSE
+Requires-Dist: py-skia-canvas==0.1.0a18
+Dynamic: license-file
+
+# py-katex
+
+PyPI 发行名为 **`py-visactor-katex`**；Python 导入名为 `py_katex`，命令行为 `py-katex`。
+
+Python TeX 数学公式解析、二维排版与静态绘制，基于固定 **KaTeX 0.18.11** 核心移植。
+数学字体和原始度量随包提供，通过 `py-skia-canvas` 公开 API 输出 PNG、JPEG、WebP、SVG 和 PDF。
+生产运行不需要 Node、浏览器、JavaScript 引擎或联网字体。
+
+## 安装
+
+```shell
+python -m pip install py-visactor-katex==0.1.0
+```
+
+需要 CPython **3.13**。原生依赖固定为 `py-skia-canvas==0.1.0a18`，其发行 wheel 支持
+Windows AMD64 和 Linux glibc 2.28+ x86_64。其他 ABI、架构和 macOS 不在当前发行依赖范围内。
+默认 `auto` 保留 Canvas 设备策略；`cpu` 禁用 GPU，`gpu` 要求实际 GPU，不能创建时明确失败。
+
+## Python API
+
+```python
+from pathlib import Path
+from py_katex import Options, render, typeset
+
+formula = r"x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}"
+result = render(formula, font_size=28, display_mode=True,
+                backend="cpu", format="svg", background="white")
+Path("formula.svg").write_bytes(result.data)
+box = typeset(formula, options=Options(font_size=28, display_mode=True))
+print(box.width, box.height, box.depth)
+```
+
+`parse` 返回数学 AST，`layout`/`typeset` 返回不可变数学盒，`render` 返回编码字节、尺寸、
+实际后端和数学盒。`draw(context, box, x, y)` 可绘制到调用方的 Canvas；原点是左侧基线，y 向下。
+Canvas、Context 和字体对象属于调用线程，跨线程只传纯数据和 bytes。
+
+```python
+from py_katex import MacroState, render, typeset
+
+state = MacroState()
+typeset(r"\def\MyReals{\mathbb{R}}", macro_state=state, global_group=True)
+result = render(r"x\in\MyReals\tag{A}", macro_state=state,
+                display_mode=True, leqno=True, content_width=400, backend="cpu")
+```
+
+默认请求隔离，不修改调用方宏字典。宏支持字符串、`Macro`、声明字典和显式 Python 回调；
+`strict`/`trust` 可使用显式 Python 回调，不执行源字符串。`content_width` 是静态容器逻辑宽度，
+`equation_counter` 指定自动编号起点。
+
+## 离线资源
+
+```python
+from py_katex import ResourceBundle, image_resource_from_file, render
+
+resources = ResourceBundle((image_resource_from_file("logo", "logo.png"),))
+result = render(r"\includegraphics[width=2em]{logo}",
+                resources=resources, trust=True, backend="cpu")
+```
+
+图片仅来自显式资源或 data URI，公式 URL 不会自动访问网络或文件。
+可通过 `FontResource` 注入 Unicode 字体；系统回退不等于完整离线字库，缺字会明确报错。
+`html_styles` 将类名映射为有限的静态样式声明；不支持的可见属性明确诊断。
+
+## 命令行
+
+```shell
+py-katex "x^2+y^2=z^2" --display --backend cpu -o formula.png
+python -m py_katex "x^2+y^2=z^2" --display --backend cpu -o formula.pdf
+```
+
+输出格式由扩展名决定。另有 `--macro`、`--strict`、`--no-throw`、`--image KEY=PATH`、
+`--font FAMILY=PATH`、`--html-style CLASS=DECLARATIONS` 等选项。
+
+## 范围和错误
+
+核心静态能力包括符号与字体、分式/根式、脚标/极限、积分/求和、伸缩括号/箭头/重音、
+矩阵与 AMS/CD、tag/编号、作用域宏、尺寸/断行、颜色/装饰、可信任静态图片与样式。
+20 个数学 TTF 与固定源度量随包提供。Python 原生位置使用 codepoint，解析错误另附 UTF-16 对应位置。
+
+`throw_on_error=False` 绘制可见错误提示；必须检查 `result.box.diagnostics`，不能将错误图当作成功公式。
+默认遇到错误抛出 `ParseError`。独立资源预算与解析预算限制异常输入。
+
+HTML/MathML 输出、任意浏览器宿主 CSS、交互和独立 contrib 插件（如 mhchem）不属于核心静态范围。
+字体栅格、留白和自然尺寸不作跨 DOM/Canvas 逐像素等价承诺。
+py-mermaid 的数学标签可使用此模块；宿主预处理和混排规则由 py-mermaid 负责。
+
+## 来源与验收
+
+来源固定 KaTeX 0.18.11 / `d5bed9f38a8d747b9c4a12e18897a514707e1c26`。
+开发候选验收覆盖 973 个测试方法、684 个注册/宏上下文、1,909 个来源功能输入、217 组等价关系与
+275 个数学/集成案例三后端。发行安装验证单独记录；历史报告保留其实际候选与版本。
+
+- [完整静态验收](https://github.com/py-VisActor/py-katex/blob/main/docs/FULL_STATIC_ACCEPTANCE.md)
+- [发行状态](https://github.com/py-VisActor/py-katex/blob/main/docs/RELEASE_STATUS.md)
+- [更新记录](https://github.com/py-VisActor/py-katex/blob/main/CHANGELOG.md)
+- [日志与报告复用](https://github.com/py-VisActor/py-katex/blob/main/docs/FULL_RUNS_AND_REPORTS.md)
+- [第三方声明](https://github.com/py-VisActor/py-katex/blob/main/THIRD_PARTY_NOTICES.md)
+
+MIT License。保留 KaTeX 的 MIT 许可证和来源声明。

py_visactor_katex-0.1.0/README.md

@@ -0,0 +1,99 @@
+# py-katex
+
+PyPI 发行名为 **`py-visactor-katex`**；Python 导入名为 `py_katex`，命令行为 `py-katex`。
+
+Python TeX 数学公式解析、二维排版与静态绘制，基于固定 **KaTeX 0.18.11** 核心移植。
+数学字体和原始度量随包提供，通过 `py-skia-canvas` 公开 API 输出 PNG、JPEG、WebP、SVG 和 PDF。
+生产运行不需要 Node、浏览器、JavaScript 引擎或联网字体。
+
+## 安装
+
+```shell
+python -m pip install py-visactor-katex==0.1.0
+```
+
+需要 CPython **3.13**。原生依赖固定为 `py-skia-canvas==0.1.0a18`，其发行 wheel 支持
+Windows AMD64 和 Linux glibc 2.28+ x86_64。其他 ABI、架构和 macOS 不在当前发行依赖范围内。
+默认 `auto` 保留 Canvas 设备策略；`cpu` 禁用 GPU，`gpu` 要求实际 GPU，不能创建时明确失败。
+
+## Python API
+
+```python
+from pathlib import Path
+from py_katex import Options, render, typeset
+
+formula = r"x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}"
+result = render(formula, font_size=28, display_mode=True,
+                backend="cpu", format="svg", background="white")
+Path("formula.svg").write_bytes(result.data)
+box = typeset(formula, options=Options(font_size=28, display_mode=True))
+print(box.width, box.height, box.depth)
+```
+
+`parse` 返回数学 AST，`layout`/`typeset` 返回不可变数学盒，`render` 返回编码字节、尺寸、
+实际后端和数学盒。`draw(context, box, x, y)` 可绘制到调用方的 Canvas；原点是左侧基线，y 向下。
+Canvas、Context 和字体对象属于调用线程，跨线程只传纯数据和 bytes。
+
+```python
+from py_katex import MacroState, render, typeset
+
+state = MacroState()
+typeset(r"\def\MyReals{\mathbb{R}}", macro_state=state, global_group=True)
+result = render(r"x\in\MyReals\tag{A}", macro_state=state,
+                display_mode=True, leqno=True, content_width=400, backend="cpu")
+```
+
+默认请求隔离，不修改调用方宏字典。宏支持字符串、`Macro`、声明字典和显式 Python 回调；
+`strict`/`trust` 可使用显式 Python 回调，不执行源字符串。`content_width` 是静态容器逻辑宽度，
+`equation_counter` 指定自动编号起点。
+
+## 离线资源
+
+```python
+from py_katex import ResourceBundle, image_resource_from_file, render
+
+resources = ResourceBundle((image_resource_from_file("logo", "logo.png"),))
+result = render(r"\includegraphics[width=2em]{logo}",
+                resources=resources, trust=True, backend="cpu")
+```
+
+图片仅来自显式资源或 data URI，公式 URL 不会自动访问网络或文件。
+可通过 `FontResource` 注入 Unicode 字体；系统回退不等于完整离线字库，缺字会明确报错。
+`html_styles` 将类名映射为有限的静态样式声明；不支持的可见属性明确诊断。
+
+## 命令行
+
+```shell
+py-katex "x^2+y^2=z^2" --display --backend cpu -o formula.png
+python -m py_katex "x^2+y^2=z^2" --display --backend cpu -o formula.pdf
+```
+
+输出格式由扩展名决定。另有 `--macro`、`--strict`、`--no-throw`、`--image KEY=PATH`、
+`--font FAMILY=PATH`、`--html-style CLASS=DECLARATIONS` 等选项。
+
+## 范围和错误
+
+核心静态能力包括符号与字体、分式/根式、脚标/极限、积分/求和、伸缩括号/箭头/重音、
+矩阵与 AMS/CD、tag/编号、作用域宏、尺寸/断行、颜色/装饰、可信任静态图片与样式。
+20 个数学 TTF 与固定源度量随包提供。Python 原生位置使用 codepoint，解析错误另附 UTF-16 对应位置。
+
+`throw_on_error=False` 绘制可见错误提示；必须检查 `result.box.diagnostics`，不能将错误图当作成功公式。
+默认遇到错误抛出 `ParseError`。独立资源预算与解析预算限制异常输入。
+
+HTML/MathML 输出、任意浏览器宿主 CSS、交互和独立 contrib 插件（如 mhchem）不属于核心静态范围。
+字体栅格、留白和自然尺寸不作跨 DOM/Canvas 逐像素等价承诺。
+py-mermaid 的数学标签可使用此模块；宿主预处理和混排规则由 py-mermaid 负责。
+
+## 来源与验收
+
+来源固定 KaTeX 0.18.11 / `d5bed9f38a8d747b9c4a12e18897a514707e1c26`。
+开发候选验收覆盖 973 个测试方法、684 个注册/宏上下文、1,909 个来源功能输入、217 组等价关系与
+275 个数学/集成案例三后端。发行安装验证单独记录；历史报告保留其实际候选与版本。
+
+- [完整静态验收](https://github.com/py-VisActor/py-katex/blob/main/docs/FULL_STATIC_ACCEPTANCE.md)
+- [发行状态](https://github.com/py-VisActor/py-katex/blob/main/docs/RELEASE_STATUS.md)
+- [更新记录](https://github.com/py-VisActor/py-katex/blob/main/CHANGELOG.md)
+- [日志与报告复用](https://github.com/py-VisActor/py-katex/blob/main/docs/FULL_RUNS_AND_REPORTS.md)
+- [第三方声明](https://github.com/py-VisActor/py-katex/blob/main/THIRD_PARTY_NOTICES.md)
+
+MIT License。保留 KaTeX 的 MIT 许可证和来源声明。

py_visactor_katex-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# Third-party notices
+
+KaTeX 0.18.11 (MIT, Copyright 2013–2020 Khan Academy and other contributors) supplies the mathematical algorithms, symbol definitions, generated TeX metrics, SVG path constants and 20 bundled fonts used in this Python implementation. The preserved license is references/licenses/katex-LICENSE. The source release, commit and npm integrity are locked in references/upstream.lock.json. The upstream README identifies KaTeX as MIT licensed.
+
+py-skia-canvas 0.1.0a18 provides all native font, drawing and encoding operations through its public Python API. Its dependencies remain owned by that distribution; this project does not copy their native implementation.
+
+Official KaTeX JavaScript, Node and browser tools are development-only reference/oracle inputs, never runtime dependencies or rendering fallbacks.

py_visactor_katex-0.1.0/docs/ACCEPTANCE.md

@@ -0,0 +1,47 @@
+> 2026-11-06 **固定 KaTeX 0.18.11 核心静态迁移已完成本地验收**：973 方法、684 上下文、1909 功能输入/217 等价关系、275 案例三后端与 297 历史流程图三后端通过。当前入口为 [完整验收](FULL_STATIC_ACCEPTANCE.md)。安装验证暂缓，未提交推送发布；下方旧 alpha/未实现状态仅作历史。
+
+# py-katex 本地验收（2026-11-05）
+
+已在 `C:/code/py-visactor/py-katex` 完成 Python 数学解析、TeX 盒模型排版、Canvas 原生静态绘制，并接入相邻 `py-mermaid` 的流程图标签。远端仓库原已存在，本轮克隆并实现本地源码；版本 `0.1.0a0`，尚未提交、推送或发布。本记录验收原生静态 alpha 范围，不声明完整 KaTeX 兼容。
+
+## 能力与接口
+
+公开 `parse`、`layout`、`typeset`、`draw`、`render` 与 CLI；支持分数、根式、上下标、积分/求和及 limits、伸缩括号、重音与伸缩箭头、矩阵/array/cases/aligned、数学字体/颜色/文本、作用域宏、规则线、phantom/smash/lap/盒子等功能族。实际命令、语义分支和拒绝项以 `references/parser-sources.json`、`function-inventory.json` 与源测试为准，功能族名称不表示全部组合已经兼容。
+
+运行时是 Python AST → TeX boxes → glyph/rule/path → `py-skia-canvas==0.1.0a18`；不调用 Node、浏览器或 JS。20 份上游 TTF 随包提供，使用源字体度量；离线生成 PNG/JPG/WebP/SVG/PDF。固定源 KaTeX `0.18.11` / `d5bed9f38a8d747b9c4a12e18897a514707e1c26`，MIT 声明及逐文件指纹保存在 `references/upstream.lock.json` 和第三方许可中。
+
+Mermaid `htmlLabels=true` 的节点、边和分组标签支持 `$$...$$` 及文本混排，使用原生公式盒测量和绘制。`htmlLabels=false` 依照固定源行为保留字面公式；配置名不意味着生产运行时使用 DOM。保护公式后再做 Markdown/HTML 清洗，保留 TeX 反斜杠、`<`、`&` 和矩阵分行。
+
+## 实际验证
+
+- 同候选 712 个测试方法通过：676 产品、36 工具；含历史 486 个方法与新增数学/集成方法。
+- 61 个独立公式、8 张流程图，CPU/auto/GPU 共 207 个视图通过；每种后端另验 7 个数学负例。
+- 历史 F01.1/F01.2/F01.3/F01.4 共 297 个正例 × 3 后端通过，保留原负例、源缺陷与范围排除分母。两个历史延后数学案例显式提升为真实公式绘制断言，并未删除跳过。
+- 五种格式均产生真实文件；HTML 的 207 个视图、五个下载、桌面/移动布局、零外部请求通过自动 QA；布局与集成人工检查已记录原图路径。
+
+[打开 HTML 对比报告](http://127.0.0.1:8765/MATH-batch-20261105T122804Z-878bf5d4/index.html)。HTML SHA256：`9f7ef845b1a8f495d66824f48208da6206f6b3235d3b9e3f5b7a20bf493e88ee`。证据和各组方法数见 [verification-summary.json](../references/verification-summary.json)。
+
+最终数学源码 SHA256：`6e11f0a8f9f88c78fb387faf4429cfea72781a4e961328bf53299625bea2cb80`；Mermaid：`6e37306deb59a5eb21a2bcceedd66c128a2367f392b094854e2e9bdb3e0e4088`。完整源快照为 `test-runs/MATH-batch-20261105T121812Z-73861ed7/artifacts/joint-source.zip`。测试、报告与原图使用同一联合候选，文档收口未改变产品源码。
+
+## 明确差异与边界
+
+- `math-flow-metadata`：官方 Mermaid 元数据预处理将反斜杠 n 破坏为换行，A 图显示残缺的字面公式；本实现保留 TeX 并绘制 ν<y，属于明确修正源异常，不能声称与该异常图相同。
+
+- `math-flow-group`：官方 MathML 宿主显示斜体 Unicode Group；原生 TeX 使用 Main-Bold 正体粗体。
+
+- `math-flow-mixed`：官方 flex/MathML 合并公式边界空格；原生保留 Area πr² units 的边界空格。
+
+- 不是完整 KaTeX 兼容实现；注册项与功能族映射不等于逐分支覆盖率。
+- 自动公式编号/tag、CD、部分宏展开边界尚未实现；明确拒绝未支持语法。
+- Parser 不暴露 displayMode/strict/leqno/fleqn 全部源选项；Options.display_mode 用于视觉样式。
+- HTML class/id/style/data、includegraphics 拒绝；href/url 仅保留静态文本，无交互。
+- 部分 Unicode 缺少源字体度量时明确报错，不用系统字体伪造数学度量。
+- pmb 保留偏移副本，未复刻原实现 0.04px 模糊。
+- 本轮验证 Windows 本地环境；安装、构建、Linux/no-loader 验证未执行。
+- 版本 0.1.0a0 未发布；Mermaid 声明依赖版本，开发验证使用两个源码目录 PYTHONPATH，安装解析需后续发布或本地安装阶段验证。
+
+17 个未支持注册名称及 3 个动态宏的清单保留在机器摘要与源映射中；334 个注册名不是覆盖率。未支持输入必须抛出明确错误，不返回空图或把普通字符串当作成功公式。
+
+## 过程与交接
+
+P0 来源与接口 → P1 源码 → P2 源断言 → P3 首次失败与批量修复 → P4 同候选验证及原图 QA → P5 文档本地交付已完成。首轮失败、后续修复、错误的早期报告、最终报告均保留独立日志。下一阶段应针对清单补足命令和边界，再独立验证发布/安装；不将其它 Mermaid 图种自动视为已验收。标准命令见 [RUNS_AND_REPORTS.md](RUNS_AND_REPORTS.md)。

py_visactor_katex-0.1.0/docs/AST.md

@@ -0,0 +1,164 @@
+# Native math AST v1
+
+Source: KaTeX 0.18.11 (`d5bed9f38a8d747b9c4a12e18897a514707e1c26`),
+Lexer.ts, MacroExpander.ts, Namespace.ts, Parser.ts and functions/environments.
+This is a pure-value layout contract; it does not recreate HTML/MathML nodes.
+`Node(kind, value='', children=(), attrs=(), position=0)` is frozen.
+`position` is the original Python codepoint offset; expansion tokens inherit
+the macro invocation offset, while substituted arguments retain their locations.
+The root is always `group`. No source or Canvas object is stored in the tree.
+
+All command values below omit the leading backslash. Dimensions are immutable
+`(number, unit)` pairs. Units are em/ex/mu/pt/mm/cm/in/bp/pc/dd/cc/nd/nc/sp/px.
+Atoms are mord/mop/mbin/mrel/mopen/mclose/mpunct/minner.
+
+| kind | value | children | attrs |
+|---|---|---|---|
+| group | empty | ordered body | none |
+| symbol | actual Unicode glyph | none | atom, mode math/text, font source main/ams, original source token (preserves mathematical alphabet font identity) |
+| atom | mathord/mathbin/mathrel/mathopen/mathclose/mathpunct/mathinner | body group | atom |
+| scripts | empty | base, superscript group, subscript group | limits None/True/False; missing scripts are empty groups |
+| frac | empty | numerator, denominator | bar bool, style auto/display/text/script/scriptscript, left/right delimiters, optional thickness dimension/None, align l/r/None, infix bool optional, continued bool for cfrac |
+| sqrt | empty | radicand, index group | missing index is an empty group |
+| operator | literal name or actual large-operator Unicode | optional body group | limits bool, symbol bool, command source identity, small bool for smallint, roman bool for operatorname versus mathop |
+| delimiters | empty | successive body segment groups | left/right actual glyph or `.`, middle tuple, exactly one delimiter between adjacent children |
+| sized_delimiter | actual delimiter | none | size 1/2/3/4, atom |
+| font | source font command (mathrm/mathnormal/mathbf/mathit/mathbb/mathcal/mathscr/mathfrak/mathsf/mathsfit/mathtt/boldsymbol/bm) | body group | none |
+| text | text/mbox/hbox/textnormal/textrm/textbf/textmd/textit/textup/textsf/texttt | body group | text mode preserved in contained symbols; embedded `$...$` is math |
+| style | display/text/script/scriptscript | body group | cramped may be supplied by future source commands; layout derives normal fraction/script/root styles |
+| size | tiny/sixptsize/scriptsize/footnotesize/small/normalsize/large/Large/LARGE/huge/Huge | body group | none |
+| mathchoice | empty | display, text, script, scriptscript groups | layout selects using its current style |
+| color | validated color string | body group | optional duplicated color attr |
+| space | source command name | none | width in em |
+| kern | empty | none | width dimension (negative permitted) |
+| linebreak | empty | none | gap dimension/None; top-level source cr, separate from array row splitting |
+| accent | source accent command | body group or symbol | normal/wide/stretchy source identity retained |
+| line | overline/underline | body group | none |
+| overunder | overbrace/underbrace/overset/underset/stackrel/stackbin | body, annotation group | over/underbrace annotation initially empty; outer scripts carry source annotation |
+| xarrow | source extensible arrow command | above group, below group | missing below is empty group |
+| phantom | phantom/hphantom/vphantom | body group | none |
+| smash | empty | body group | smash_height, smash_depth bool |
+| lap | llap/rlap/clap | body group | none |
+| rule | empty | none | width, height, shift dimensions |
+| raise | empty | body group | dy dimension |
+| vcenter | empty | body group | layout centers total box on math axis |
+| reflect | empty | body group | horizontal reflection; reflectbox is text mode and mathreflectbox is math mode |
+| pmb | empty | body group | source static text-shadow offset 0.02em/0.01em with 0.04px blur |
+| enclose | boxed/fbox/colorbox/fcolorbox/cancel/bcancel/xcancel/sout/phase/angl | body group | color=background and border_color=border optional |
+| array | empty | row nodes | environment, cols tuple, left/right delimiter or empty, row_gaps tuple of dimension/None, hlines tuple of (row index,hline/hdashline), tag Node/None, arraystretch float/None |
+| row | empty | cell group nodes | none |
+
+For `array.cols`, l/c/r alignments and `|`/`:` rules retain order. A single
+alignment repeats for matrix columns; aligned/align/gather/cases spacing is
+chosen from environment identity by layout. Row gaps belong after each row.
+`tag` is reserved for a measured annotation, not an interactive anchor; explicit tag macros remain unsupported in P1. `arraystretch` is an explicit current macro override, otherwise None lets layout use source environment defaults.
+
+## Expansion, scope and safety
+
+Lazy expansion uses a request-local macro namespace. Group braces, explicit
+begingroup/endgroup and environments push scopes; def/newcommand/let are local,
+gdef/xdef/global definitions replace all shadowing definitions within that request.
+No macro survives a parse call. Replacement references use numbered parameters
+1 through 9; def requires sequential parameter declarations, while newcommand
+can consume more arguments (the fixed source explicitly tests ten). def also
+records literal parameter delimiters. edef/xdef
+expand the replacement before storing it. Source newcommand does not support
+optional default arguments, and this parser does not invent them.
+
+The packaged source-derived 315 literal macros are loaded as data. Context macros
+are individually implemented or explicitly listed unsupported in the source map.
+Unknown controls/environments fail with ParseError, never a literal-text formula.
+Expansion count, queued token count, AST node count and recursive nesting have
+explicit budgets. Trust does not enable URLs, HTML hosts, resource fetches or code.
+href retains only its static label; url retains a literal typewriter label.
+Terminal message/errmessage/show consume source arguments without host logging.
+html@mathml selects the source visual branch as pure AST; it creates no HTML host.
+
+## Compatibility boundaries
+
+This contract is a substantive native math slice, not a claim of every KaTeX
+command or option. Complete fixed-source command/environment inventories and
+each unsupported branch are recorded in references/parser-sources.json.
+The alpha P3 evidence is historical. The MATH-FULL additions below are P1 source
+only until a new frozen candidate completes its own independent verification.
+
+## MATH-FULL contract v2 (current)
+
+Authority is the mechanically imported fixed-source runtime registry:
+`references/full-runtime-registry.json`: 312 functions, 33 environments,
+319 literal macros and 20 dynamic context macros. The former 334-name static
+inventory omitted dynamic sizing names; it is not the current denominator.
+All entries have native parser dispatch or a documented internal projection.
+This statement is source completeness, not a behavioral compatibility score.
+
+The parse keyword arguments now include `display_mode=False`, `strict='warn'`,
+`color_is_text_color=False`, `global_group=False`, `error_color='#cc0000'`,
+`macro_state=None`, `leqno=False`, and `throw_on_error=True`. `max_expand` accepts
+numeric fractional thresholds and positive infinity; negative values clamp to
+zero per the source Settings processor. Native node/depth/token budgets remain
+independent. NaN and nonnumeric expansion thresholds are rejected.
+
+`strict` supports bool, ignore/warn/error strings, or a Python callback receiving
+(code, message, Token). Warnings use MathWarning. Source report=False branches
+return strict behavior instead of throwing; callback failures there mean strict.
+`trust` supports bool or a Python callback receiving the source command context
+and validated protocol. Source strings are never executed as code.
+
+| kind / extension | Native contract |
+|---|---|
+| tag | children=(body group, tag group); root remains group containing one tag; leqno bool |
+| unsupported | value=original command, attrs color/rejected/code/message; visible source red command and warning diagnostic, never an empty successful formula |
+| html | value=htmlClass/htmlId/htmlStyle/htmlData; children=(body group,); attributes tuple(name,value), for the native CSS provider |
+| image | value=src; attrs src,alt,width,height,totalheight; dimensions are (number,unit), resource resolution is outside parser |
+| cdarrow | value=> / < / A / V / = / pipe / dot; children=(first label,second label), reused inside array(environment=CD) |
+| cdlabel | value=left/right; children=(label,); source internal vertical-arrow label layout |
+| group | explicit=True for braces, semisimple=True for begingroup; reset_font/no_break for hbox; cd_parent=True for the internal CD wrapper |
+| style | reset_font=True when source styling requests it |
+| space | break_kind=allowbreak/nobreak, retained as static line-break opportunities |
+| operator | always_handle_supsub and suppress_base_shift source flags; operatorname starred identity is separate from explicit limits |
+| sqrt | index_provided distinguishes absent index from an explicitly empty optional index |
+| xarrow | below_provided distinguishes absent and explicitly empty labels |
+| text | verb=True requests source verb textstyle sizing rather than ordinary texttt sizing |
+| delimiters | right_color preserves the scoped current color at right delimiter |
+
+Arrays additionally expose `tags=None|tuple[Node|bool]`, `col_specs`, `add_jot`,
+`hskip_before_after`, `col_separation`, `cell_style`, `leqno`. A col_spec is
+('align', l/c/r, pregap dimension/None, postgap dimension/None), or
+('separator', pipe/colon). True/False tag values are the source automatic-number
+flags, not invented equation counters. Existing cols/row_gaps/hlines remain.
+Each cell has its own macro scope; AMS row tags and nonumber use global TeX flags.
+CD intentionally preserves the fixed source's terminal empty row.
+
+Ordinary function arguments first consume raw balanced token arguments and then
+parse an isolated expression. Primitive/script arguments parse one ordinary group
+and enforce allowedInArgument. Optional arguments use unexpanded '[' lookahead.
+Size extraction preserves the fixed source's unanchored measurement regex;
+mandatory empty size groups mean 0pt, while empty optional sizes are invalid.
+The fixed source cfrac has no [l]/[r] argument and is not extended to accept one.
+
+MacroState is an explicit caller-owned mutable TeX namespace. Only that explicit
+state object persists global definitions across parse calls. Ordinary macros
+mappings remain unmodified. global_group=True also persists top-level definitions
+to the state; otherwise a top-level TeX scope is closed while global defs survive.
+Color and tag implementation flags are cleaned at the request boundary.
+
+User macro values can be strings, Macro, source-style dictionaries, or Python
+callbacks. Macro.body is in forward order; source dictionaries' tokens are in
+reverse stack order, with numArgs/delimiters/unexpandable fields. Token preserves
+native codepoint positions. Callback results are validated and budgeted and must
+be a string, Macro, or expansion dictionary, not arbitrary code or another callback.
+
+Callbacks receive Expander with the documented source aliases consumeArg,
+consumeArgs, popToken, future, consumeSpaces, expandOnce, expandAfterFuture,
+expandNextToken, expandTokens, expandMacro, expandMacroAsText, isDefined,
+isExpandable, and a macros namespace facade. Source aliases retain reverse-stack
+argument conventions; native argument/push/next methods use forward order.
+The native namespace facade's current property is an inspection snapshot;
+mutations go through its set method or the explicitly shared MacroState.
+
+Unknown command handling under throw_on_error=False preserves the rest of the
+formula and emits an unsupported node; true syntax failures still raise ParseError.
+Native error.position stays codepoint-based; utf16_position is filled at parse exit
+for comparison to the fixed JavaScript source. HTML/MathML serialization and
+browser interactions are not native backends; their retained static content,
+style, resources, semantics and security decisions are native responsibilities.

py_visactor_katex-0.1.0/docs/EXECUTION_PLAN.md

@@ -0,0 +1,15 @@
+> 2026-11-06 **固定 KaTeX 0.18.11 核心静态迁移已完成本地验收**：973 方法、684 上下文、1909 功能输入/217 等价关系、275 案例三后端与 297 历史流程图三后端通过。当前入口为 [完整验收](FULL_STATIC_ACCEPTANCE.md)。安装验证暂缓，未提交推送发布；下方旧 alpha/未实现状态仅作历史。
+
+> 2026-11-05 用户要求一次完成剩余核心静态 KaTeX 迁移，当前执行 [完整收口计划](FULL_STATIC_MIGRATION.md)。旧 alpha 验收仅是历史起点，不能用于新候选。安装验证仍暂缓。
+
+> 2026-11-05 本轮原生静态 alpha 已完成本地验收：712 个方法、69 个数学/集成案例 × 3 后端、297 个历史案例 × 3 后端通过。详见 [验收记录](ACCEPTANCE.md)。完整 KaTeX 兼容仍有明确待补项；安装验证暂缓，未提交推送发布。下文阶段安排保留为历史。
+
+# Python 数学绘制与 Mermaid 接线
+
+用户要求新建/下载 py-VisActor/py-katex，在当前工作目录实现 Python 数学公式绘制并接入 py-mermaid。远端仓库已存在，已克隆到 C:/code/py-visactor/py-katex，起始提交 e49a9355a1e8e14a93c593388b7ce1c1b8640e8b。
+
+来源：KaTeX 0.18.11，commit d5bed9f38a8d747b9c4a12e18897a514707e1c26，与固定 Mermaid 12.2.0 的 pnpm-lock 一致；原 npm tarball 经 SHA512 验证，原实现只用于溯源与开发 oracle。运行时 Python parser/macro → TeX box → glyph/rule/path → py-skia-canvas，不依赖 JS/浏览器。
+
+P0 保存两个仓库起点与来源、冻结纯值接口；P1 一次编写解析/宏、字体/度量、分式/根式/上下标/运算符/定界符/矩阵等排版、静态绘制与 Mermaid 标签接线；P2 从固定源码/spec 独立设计语法、数学几何、实际绘制、安全、CPU/GPU/导出与集成测试；P3 分组首跑并保存失败、根因批修；P4 同候选完整测试、官方 A/原生 B 图像、人工 QA、HTML 对比报告；P5 实际能力/限制与许可证文档。
+
+不能以纯 Unicode 拼接、普通字符串或成功白图代替二维公式；字体与度量随包离线携带。未支持命令/环境明确诊断，来源清单不删。完整 KaTeX 兼容与本轮实际绘制能力分开报告。安装验证仍按用户要求暂缓，提交/推送/发布未在本次要求中执行。

py_visactor_katex-0.1.0/docs/FULL_RUNS_AND_REPORTS.md

@@ -0,0 +1,28 @@
+# 核心静态迁移：日志与报告复用
+
+本工作流不安装、构建、发布包。固定来源与分母见 `references/upstream.lock.json`、`full-core-inventory.json`。当前验收入口为 [FULL_STATIC_ACCEPTANCE.md](FULL_STATIC_ACCEPTANCE.md)；历史 alpha 记录保持原样。
+
+在已具备依赖的环境下，从 py-katex 根目录执行：
+
+```powershell
+C:/venvs/pymmd-20261102/Scripts/python.exe tools/workflow.py batch --scope MATH-FULL --plan tools/plans/full-repair.json --keep-going
+```
+
+此计划依次保存两个仓库的源码和验证输入快照，运行锁定上游注册 oracle、核心功能输入采集、官方 A 图、新旧全部单元测试、功能输入及等价关系验证、CPU 静态图检查。`--keep-going` 用于保留首轮完整失败分布，失败组不算通过。核心语料采集不等于执行原 Jest 的全部 matcher、HTML/MathML 或 snapshot 断言。
+
+取得成功的 unit run 后，修改 `tools/plans/full-matrix.json` 中固定 A 图来源到该 run，运行：
+
+```powershell
+C:/venvs/pymmd-20261102/Scripts/python.exe tools/workflow.py batch --scope MATH-FULL --plan tools/plans/full-matrix.json --keep-going
+C:/venvs/pymmd-20261102/Scripts/python.exe tools/workflow.py batch --scope MATH-FULL --plan tools/plans/math-legacy-visual.json --keep-going
+```
+
+矩阵计划验证全部独立公式和真实 Mermaid 集成图的 CPU/auto/必需 GPU，以及 PNG/JPG/WebP/SVG/PDF 五种真实导出。历史计划保留 297 个流程图正例，以及源错误、负例、范围分类；曾归入数学排除的两个 ID 保留并明确提升为数学绘制断言。固定 A 仅在输入与原始图像指纹一致时复用，禁止重写或美化原图。
+
+运行 `tools/report_full.py --unit <unit-run> --visual <matrix-run> --legacy <legacy-run> --manual-receipt <layout-review.json> --manual-receipt <canvas-review.json> --out <new-report-directory>` 生成报告；三个 run 必须全部成功、源码未变且联合候选与当前一致。人工回执也必须通过且对应同一联合候选，否则拒绝生成。生成器只读保存的图像与指标，报告不触发重新绘图。
+
+所有命令应由 `workflow.py record` 或版本化 batch plan 执行，统一保存 argv、环境、stdout/stderr、输入和输出 SHA256、退出码及源码变化。已关闭的 run 不修改；修复后新建 run。`joint-source.zip` 保存产品源码，`joint-verification-inputs.zip` 保存当时测试、工具、文档与引用的完整字节，便于复现曾经失败的输入。
+
+报告目录放在相邻 `py-mermaid/reports/<report-run-id>/`；使用已有 `127.0.0.1:8765` 服务，或启动 `py-mermaid/tools/serve_reports.py`。用记录命令执行 `node tools/qa_report.cjs --url <url> --out <new-qa-directory>`，逐一检查案例与三种后端，校验全部嵌入原图、五种下载、桌面/手机宽度和零外部请求。最后执行 `tools/full_delivery_audit.py --out <new-audit-directory>`，核对文档、闭合 run、HTTP 字节、联合源码并归档交付资料。
+
+像素差只用于诊断；验收断言覆盖内容、结构、字体轴、数学几何、颜色、资源实际像素、溢出边界和真实后端。可见错误图保留诊断；源拒绝输入不得算作成功公式。已知 Mermaid 宿主差异必须在报告逐例标注。

py_visactor_katex-0.1.0/docs/FULL_STATIC_ACCEPTANCE.md

@@ -0,0 +1,47 @@
+> 2026-11-06：正式发行任务另见 [发行状态](RELEASE_STATUS.md)。以下验收保持原始开发候选与 0.1.0a0 的历史口径，发行安装验证单独记录。
+
+# KaTeX 核心静态迁移验收
+
+2026-11-06：完成固定 KaTeX **0.18.11** 核心保留静态能力的本地迁移与 Mermaid 接入。版本仍为未发布的 `0.1.0a0`，版本号不表示本轮工作未验收。
+
+## 本轮补齐
+
+完整宏展开与作用域/持久状态、动态宏和回调、严格/信任/错误配置；AMS/CD、矩阵与数组、tag/自动编号、leqno/fleqn、尺寸限制与断行；字体轴、Unicode 回退、伸缩/重音/装饰、PMB；显式离线图片及 HTML 静态样式；真实墨迹边界、PNG/JPG/WebP/SVG/PDF 导出。Mermaid 节点、边、组标签通过独立 Python 模块绘制数学。
+
+生产仅使用 Python 与公开 Canvas API，不依赖 Node、浏览器、JS 解释器或 DOM。20 个数学字体与源度量随包提供；其它 Unicode 字体可显式注入，系统回退不等于完整离线字库。
+
+## 同候选验收
+
+| 验证层 | 实际结果 |
+| --- | --- |
+| 新旧单元测试 | 973 个方法全部通过，无跳过 |
+| 核心注册与宏 | 312 函数 + 33 环境 = 345 注册入口；339 宏；684 个合法/错误语义上下文 |
+| 固定上游功能语料 | 1245 个来源测试条目中的 1909 个功能输入全部通过 |
+| 正向等价关系 | 217 组全部通过 |
+| 独立数学静态图 | 267 例 × CPU/auto/必需 GPU |
+| Mermaid 数学集成 | 8 例 × 三后端；合计 825 份结果 |
+| 历史流程图 | F01.1–F01.4 共 297 正例 × 三后端；负例、源错误与范围类别均保留 |
+| 实际静态导出 | PNG、JPG、WebP、SVG、PDF 五种 |
+| HTML 报告 | 825 视图、5 种下载、桌面/手机宽度通过；无外部请求 |
+
+注册分母来自真实锁定源码注册，不是旧静态扫描的 334。孤立 `\]` 按源仅报错，其余内部入口通过真实消费上下文验证。功能语料检查接受/拒绝、诊断、决策回调及可见等价关系；**不声称执行或移植了原 Jest 全部私有树/HTML/MathML/snapshot 断言**。图像检查含实际像素、内容、字体轴、几何关系、资源和画布边界；跨 DOM/Canvas 像素不要求逐点一致。
+
+## 可复核交付
+
+[打开 HTML 对比报告](http://127.0.0.1:8765/MATH-FULL-batch-20261105T172308Z-e0e12af6/index.html)，包含固定官方 A 与 Python B 的原始 PNG、源输入、三后端筛选、原图及五格式下载。人工复核记录见机器摘要的 manual run；报告不会改写 A 图。
+
+- 单元/语料：`test-runs/MATH-FULL-batch-20261105T171602Z-0d9b6942`
+- 三后端/导出：`test-runs/MATH-FULL-batch-20261105T171857Z-5071cad7`
+- 历史回归：`test-runs/MATH-FULL-batch-20261105T171629Z-8b5ef28e`
+- 报告/浏览器 QA：`test-runs/MATH-FULL-batch-20261105T172308Z-e0e12af6`、`test-runs/MATH-FULL-batch-20261105T172348Z-4daa587b`
+- 联合源码 SHA256：math `334c412c34ef675dbc223405622c8d4e19eb56b1ff3700c251cb663d4afdd445`；Mermaid `6094d419ff3c50d2c64fdd00051af2be087b25a7a239cb1dae0e9e09209fdff1`。
+
+全部闭合 run 校验原始字节和源码未变；产品源码、验证输入、首轮全部失败与后续修复均保留。曾经自动全通过但人工发现字体轴、SVG 比例和样式框问题的候选被明确拒收，记录见 [人工拒收候选](../references/full-manual-rejected-candidate.json)。最初失败输入已按原日志 SHA256 重建，保存在新的恢复 run，未修改旧 run。最终文档审计入口为 `test-runs/MATH-FULL-batch-20261105T172451Z-dcedc8c2`。机器摘要见 [full-verification-summary.json](../references/full-verification-summary.json)，复用步骤见 [FULL_RUNS_AND_REPORTS.md](FULL_RUNS_AND_REPORTS.md)。
+
+## 明确范围与差异
+
+核心静态目标已验收；HTML/MathML 输出后端、任意浏览器宿主 CSS 引擎、交互/无障碍 DOM 行为，以及独立 contrib 插件分别分类，未计作原生通过。`mhchem` 是独立扩展，未移植；auto-render/copy-tex/mathtex-script 的浏览器集成不在静态目标。静态样式通过有限的原生属性适配，不支持的可见属性明确诊断。
+
+固定 Mermaid 的元数据反斜线损坏、MathML 组标题字体和边界空格差异在报告逐例说明；不把对损坏源的修正写成与异常画面等价。相同源的 fleqn/leqno 标号重叠也保留来源说明。字体栅格、留白和自然尺寸差异允许，遗漏内容与错误关系不得通过。
+
+安装/构建验证按用户要求暂缓；本机 Windows 证据不能证明 Linux/no-loader 环境。源码与报告均未提交、推送或发布。历史 alpha 验收仍保留，但不能证明当前候选。