# gucci-on-fleek/lua-widow-control architecture

> Architecture diagram of the GitHub repository gucci-on-fleek/lua-widow-control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gucci-on-fleek/lua-widow-control
- Repository: https://github.com/gucci-on-fleek/lua-widow-control

## Overview

#### Purpose and entry points
`lua-widow-control` is a LuaTeX package for Plain TeX, LaTeX, ConTeXt, and OpTeX. It automatically removes widows and orphans by making affected paragraphs longer, rather than stretching glue or reducing page/column length. User-facing loaders are format-specific wrappers: `source/lua-widow-control.sty`, `source/t-lua-widow-control.mkxl`, `source/lua-widow-control.tex`, and `source/lua-widow-control.opm`.

#### Core Lua engine
The format-independent implementation is `source/lua-widow-control.lua`. It runs inside the LuaTeX/LuaMetaTeX node-processing and line-breaking environment, examines pagination outcomes, and alters paragraph-breaking behavior when a page or column would leave an orphan or widow. The TeX wrappers provide the engine with macro-level integration points rather than duplicating the algorithm.

#### Format adaptation boundary
Each supported macro format has its own entry module and installation location:
- LaTeX: `source/lua-widow-control.sty`, including compatibility release `source/lua-widow-control-2022-02-22.sty`
- ConTeXt: `source/t-lua-widow-control.mkxl`
- Plain TeX: `source/lua-widow-control.tex`
- OpTeX: `source/lua-widow-control.opm`

These files isolate format conventions, option/interface syntax, and callback setup from the shared Lua logic.

#### Runtime and distribution
The required runtime is LuaTeX-family engines; tests explicitly cover LuaMetaTeX variants. The installable TDS tree mirrors source files into TeX search paths: `texmf/tex/luatex/lua-widow-control/lua-widow-control.lua`, `texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty`, and `texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl`. The package is distributed through TeX Live/MiKTeX and external package channels referenced by the README (CTAN and ConTeXt Garden).

#### Build, documentation, and release artifacts
`build.lua` is the repository-level build entry point, producing package/distribution material. Source documentation includes the manual at `docs/manual/lwc-manual.tex` and background articles such as `docs/articles/tb133chernoff-widows.ltx`. Compiled deliverables are staged in the TDS doc tree, notably `texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf`.

#### Verification flow
The test suite compiles fixture documents through format-specific suites, validating output behavior across LaTeX, ConTeXt, Plain TeX, and OpTeX: `tests/latex/build.lua`, `tests/context/build.lua`, and `tests/plain/build.lua`. Cases cover normal documents plus structural pressure points—columns, headings, footnotes, grids, floats, and draft modes—where pagination intervention is consequential. Shared test configuration and transformation support reside in `tests/test-config.lua` and `tests/transform.xslt`.

#### Primary flow
A document loads a format wrapper, which loads/configures the Lua engine. During typesetting, the engine observes paragraph/page or column breaking through LuaTeX facilities, detects potential widow/orphan layouts, and requests an alternate paragraph length/breaking result. The resulting node list returns to the host TeX engine for normal page construction and PDF output. The main boundary is therefore TeX macro setup → Lua node/line-break control → TeX pagination.

Main entry points: [`source/lua-widow-control.lua`](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.lua) (Widow control engine), [`build.lua`](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/build.lua) (Build entry point), [`tests/test-config.lua`](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/test-config.lua) (Shared test support), [`source/lua-widow-control.sty`](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.sty) (LaTeX loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_formats["Format adapters"]
  node_latex_wrapper["LaTeX loader<br/>LaTeX adapter"]
  node_latex_compat["LaTeX compatibility loader<br/>LaTeX adapter"]
  node_context_wrapper["ConTeXt loader<br/>ConTeXt adapter"]
  node_plain_wrapper["Plain TeX loader<br/>Plain TeX adapter"]
  node_optex_wrapper["OpTeX loader<br/>OpTeX adapter"]
end

subgraph group_verification["Verification"]
  node_test_config["Shared test support<br/>test configuration<br/>[test-config.lua]"]
  node_latex_tests["LaTeX test suite<br/>fixture suite<br/>[build.lua]"]
  node_context_tests["ConTeXt test suite<br/>fixture suite<br/>[build.lua]"]
  node_plain_tests["Plain/OpTeX test suite<br/>fixture suite<br/>[build.lua]"]
end

subgraph group_distribution["Build and distribution"]
  node_build["Build entry point<br/>l3build script<br/>[build.lua]"]
  node_manual["Package manual<br/>TeX documentation<br/>[lwc-manual.tex]"]
  node_background_article["Background article<br/>TeX documentation"]
  node_tds_runtime[("Installed runtime tree<br/>TDS runtime files")]
  node_tds_latex["Installed LaTeX loader<br/>TDS file"]
  node_tds_context["Installed ConTeXt loader<br/>TDS file"]
  node_manual_pdf["Compiled manual<br/>PDF artifact"]
end

node_document["TeX document<br/>user input"]
node_lua_engine{{"Widow control engine<br/>Lua node processor"}}
node_tex_runtime(("LuaTeX-family runtime<br/>typesetting runtime"))
node_page_output["Paginated PDF output<br/>typeset output"]

node_document -->|"loads"| node_latex_wrapper
node_document -->|"loads"| node_context_wrapper
node_document -->|"loads"| node_plain_wrapper
node_document -->|"loads"| node_optex_wrapper
node_latex_compat -->|"configures"| node_lua_engine
node_latex_wrapper -->|"loads and configures"| node_lua_engine
node_context_wrapper -->|"loads and configures"| node_lua_engine
node_plain_wrapper -->|"loads and configures"| node_lua_engine
node_optex_wrapper -->|"loads and configures"| node_lua_engine
node_lua_engine -->|"controls node breaking"| node_tex_runtime
node_tex_runtime -->|"constructs pages"| node_page_output
node_build -->|"stages"| node_tds_runtime
node_build -->|"stages"| node_tds_latex
node_build -->|"stages"| node_tds_context
node_build -->|"produces"| node_manual_pdf
node_manual -->|"compiled into"| node_manual_pdf
node_test_config -->|"supports"| node_latex_tests
node_test_config -->|"supports"| node_context_tests
node_test_config -->|"supports"| node_plain_tests
node_latex_tests -.->|"compiles with"| node_tex_runtime
node_context_tests -.->|"compiles with"| node_tex_runtime
node_plain_tests -.->|"compiles with"| node_tex_runtime

click node_latex_wrapper "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.sty"
click node_latex_compat "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control-2022-02-22.sty"
click node_context_wrapper "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/t-lua-widow-control.mkxl"
click node_plain_wrapper "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.tex"
click node_optex_wrapper "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.opm"
click node_lua_engine "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.lua"
click node_build "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/build.lua"
click node_manual "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/docs/manual/lwc-manual.tex"
click node_background_article "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/docs/articles/tb133chernoff-widows.ltx"
click node_tds_runtime "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/tex/luatex/lua-widow-control/lua-widow-control.lua"
click node_tds_latex "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty"
click node_tds_context "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl"
click node_manual_pdf "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf"
click node_test_config "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/test-config.lua"
click node_latex_tests "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/latex/build.lua"
click node_context_tests "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/context/build.lua"
click node_plain_tests "https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/plain/build.lua"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_latex_wrapper,node_latex_compat,node_context_wrapper,node_plain_wrapper,node_optex_wrapper toneBlue
class node_test_config,node_latex_tests,node_context_tests,node_plain_tests toneAmber
class node_build,node_manual,node_background_article,node_tds_runtime,node_tds_latex,node_tds_context,node_manual_pdf toneMint
class node_document,node_lua_engine,node_tex_runtime,node_page_output toneNeutral
```

## Components

### Format adapters

Format-specific macro integration and callback setup.

- [LaTeX loader](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.sty): LaTeX adapter · `source/lua-widow-control.sty`
- [LaTeX compatibility loader](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control-2022-02-22.sty): LaTeX adapter · Compatibility release for older LaTeX environments. · `source/lua-widow-control-2022-02-22.sty`
- [ConTeXt loader](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/t-lua-widow-control.mkxl): ConTeXt adapter · `source/t-lua-widow-control.mkxl`
- [Plain TeX loader](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.tex): Plain TeX adapter · `source/lua-widow-control.tex`
- [OpTeX loader](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.opm): OpTeX adapter · `source/lua-widow-control.opm`

### Verification

Cross-format fixture compilation and output checks.

- [Shared test support](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/test-config.lua): test configuration · Shared test configuration and output transformation support. · `tests/test-config.lua`
- [LaTeX test suite](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/latex/build.lua): fixture suite · Exercises normal and pagination-pressure cases. · `tests/latex/build.lua`
- [ConTeXt test suite](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/context/build.lua): fixture suite · `tests/context/build.lua`
- [Plain/OpTeX test suite](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/tests/plain/build.lua): fixture suite · `tests/plain/build.lua`

### Build and distribution

Package assembly, documentation, and installable TDS artifacts.

- [Build entry point](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/build.lua): l3build script · Builds package and distribution material. · `build.lua`
- [Package manual](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/docs/manual/lwc-manual.tex): TeX documentation · `docs/manual/lwc-manual.tex`
- [Background article](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/docs/articles/tb133chernoff-widows.ltx): TeX documentation · `docs/articles/tb133chernoff-widows.ltx`
- [Installed runtime tree](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/tex/luatex/lua-widow-control/lua-widow-control.lua): TDS runtime files · Engine and format loaders installed in TeX search paths. · `texmf/tex/luatex/lua-widow-control/lua-widow-control.lua`
- [Installed LaTeX loader](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty): TDS file · `texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty`
- [Installed ConTeXt loader](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl): TDS file · `texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl`
- [Compiled manual](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf): PDF artifact · `texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf`

### Other components

- **TeX document**: user input
- [Widow control engine](https://github.com/gucci-on-fleek/lua-widow-control/blob/master/source/lua-widow-control.lua): Lua node processor · Detects widow/orphan outcomes and changes paragraph breaking. · `source/lua-widow-control.lua`
- **LuaTeX-family runtime**: typesetting runtime · LuaTeX/LuaMetaTeX node, line-breaking, and pagination facilities.
- **Paginated PDF output**: typeset output

## Connections

- TeX document → LaTeX loader: loads
- TeX document → ConTeXt loader: loads
- TeX document → Plain TeX loader: loads
- TeX document → OpTeX loader: loads
- LaTeX compatibility loader → Widow control engine: configures
- LaTeX loader → Widow control engine: loads and configures
- ConTeXt loader → Widow control engine: loads and configures
- Plain TeX loader → Widow control engine: loads and configures
- OpTeX loader → Widow control engine: loads and configures
- Widow control engine → LuaTeX-family runtime: controls node breaking
- LuaTeX-family runtime → Paginated PDF output: constructs pages
- Build entry point → Installed runtime tree: stages
- Build entry point → Installed LaTeX loader: stages
- Build entry point → Installed ConTeXt loader: stages
- Build entry point → Compiled manual: produces
- Package manual → Compiled manual: compiled into
- Shared test support → LaTeX test suite: supports
- Shared test support → ConTeXt test suite: supports
- Shared test support → Plain/OpTeX test suite: supports
- LaTeX test suite → LuaTeX-family runtime: compiles with
- ConTeXt test suite → LuaTeX-family runtime: compiles with
- Plain/OpTeX test suite → LuaTeX-family runtime: compiles with