# pskumaresh06/lua-widow-control architecture

> Architecture diagram of the GitHub repository pskumaresh06/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/pskumaresh06/lua-widow-control
- Repository: https://github.com/pskumaresh06/lua-widow-control

## Overview

#### Purpose and Entry Points
lua-widow-control is a LuaTeX package for automatically eliminating widows and orphans in Plain TeX, LaTeX, ConTeXt, and OpTeX. Rather than changing page dimensions or glue, it adjusts paragraph line breaking so affected paragraphs occupy an additional line.

Format-specific user entry points load a shared Lua implementation:
- LaTeX: `source/lua-widow-control.sty`
- Plain TeX: `source/lua-widow-control.tex`
- ConTeXt: `source/t-lua-widow-control.mkxl`
- OpTeX: `source/lua-widow-control.opm`

#### Core Layout Engine
The package’s architectural center is `source/lua-widow-control.lua`. It operates inside the LuaTeX/LuaMetaTeX typesetting runtime, inspecting and manipulating the engine’s paragraph/page-building behavior to detect potential widow/orphan breaks and re-break the relevant paragraph longer. The Lua layer is format-agnostic; macro wrappers establish the integration contract and expose it to each macro package.

The legacy/compatibility LaTeX wrapper is retained at `source/lua-widow-control-2022-02-22.sty`.

#### Format Integration Boundary
Each macro frontend maps its host format’s loading and callback conventions to the shared engine:
- LaTeX package interface: `source/lua-widow-control.sty`
- Plain TeX input interface: `source/lua-widow-control.tex`
- ConTeXt module interfaces: `source/t-lua-widow-control.mkxl`, `source/t-lua-widow-control.mkiv`
- OpTeX module interface: `source/lua-widow-control.opm`

This isolates format-specific macro syntax from Lua node-list and line-breaking logic. LuaTeX is the material execution dependency; tests also explicitly cover LuaMetaTeX variants.

#### Source-to-Distribution Packaging
`source/` is the authoritative editable package source. `texmf/` is the installable TDS-style distribution tree, mirroring runtime files by target format:
- shared Lua/Plain assets: `texmf/tex/luatex/lua-widow-control/lua-widow-control.lua`, `texmf/tex/luatex/lua-widow-control/lua-widow-control.tex`
- LaTeX assets: `texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty`
- ConTeXt assets: `texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl`
- OpTeX asset: `texmf/tex/optex/lua-widow-control/lua-widow-control.opm`

`build.lua` is the top-level build/package orchestration entry point.

#### Validation Matrix
Regression testing is split by host macro package, reflecting the key integration boundary rather than merely unit-level behavior:
- LaTeX: `tests/latex/build.lua`, `tests/latex/footnotes.tltext`
- ConTeXt: `tests/context/build.lua`, `tests/context/grid.tltext`
- Plain TeX: `tests/plain/build.lua`, `tests/plain/node-count.lvt`
- OpTeX: `tests/optex/build.lua`, `tests/optex/basic.tltext`

Shared test settings and fixtures are in `tests/test-config.lua` and `tests/common/basic.tex`. Coverage includes ordinary paragraphs, columns, headings, footnotes, grids, draft modes, and LuaMetaTeX-specific expected output.

#### Documentation and Release Artifacts
Manual and article sources live under `docs/`, while compiled distributable documentation is installed under `texmf/doc/luatex/lua-widow-control/`. Key documentation sources are `docs/manual/lwc-manual.tex` and `docs/articles/tb133chernoff-widows.ltx`; their packaged PDFs include `texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf`.

The package is distributed through TeX ecosystem channels (TeX Live, MiKTeX, CTAN, and ConTeXt Garden); no network service is required at runtime.

Main entry points: [`source/lua-widow-control.lua`](https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.lua) (Widow-control engine), [`build.lua`](https://github.com/pskumaresh06/lua-widow-control/blob/master/build.lua) (Build orchestration), [`tests/test-config.lua`](https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/test-config.lua) (Shared test configuration), [`tests/latex/build.lua`](https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/latex/build.lua) (LaTeX regression suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["Format Frontends"]
  node_latex["LaTeX interface<br/>macro package"]
  node_plain["Plain TeX interface<br/>macro input"]
  node_context["ConTeXt interfaces<br/>macro modules"]
  node_optex["OpTeX interface<br/>macro module"]
  node_legacy_latex["Legacy LaTeX wrapper<br/>compatibility package"]
end

subgraph group_source["Authoritative Source"]
  node_lua_engine{{"Widow-control engine<br/>Lua layout engine"}}
  node_luatex(("LuaTeX / LuaMetaTeX<br/>typesetting runtime"))
  node_build["Build orchestration<br/>package build<br/>[build.lua]"]
  node_docs_source["Manual and article sources<br/>TeX documentation<br/>[lwc-manual.tex]"]
end

subgraph group_distribution["TDS Distribution"]
  node_tds_lua_plain["Lua and Plain assets<br/>TDS runtime files"]
  node_tds_latex["LaTeX asset<br/>TDS package"]
  node_tds_context["ConTeXt asset<br/>TDS module"]
  node_tds_optex["OpTeX asset<br/>TDS module"]
  node_docs_pdf["Packaged documentation<br/>PDF artifact"]
end

subgraph group_validation["Regression Matrix"]
  node_test_config["Shared test configuration<br/>test settings<br/>[test-config.lua]"]
  node_latex_tests["LaTeX regression suite<br/>integration tests<br/>[build.lua]"]
  node_context_tests["ConTeXt regression suite<br/>integration tests<br/>[build.lua]"]
  node_plain_tests["Plain TeX regression suite<br/>integration tests<br/>[build.lua]"]
  node_optex_tests["OpTeX regression suite<br/>integration tests<br/>[build.lua]"]
end

node_latex -->|"loads shared Lua"| node_lua_engine
node_plain -->|"loads shared Lua"| node_lua_engine
node_context -->|"loads shared Lua"| node_lua_engine
node_optex -->|"loads shared Lua"| node_lua_engine
node_legacy_latex -->|"compatibility integration"| node_lua_engine
node_lua_engine -->|"inspects nodes and re-breaks"| node_luatex
node_build -->|"packages"| node_tds_lua_plain
node_build -->|"packages"| node_tds_latex
node_build -->|"packages"| node_tds_context
node_build -->|"packages"| node_tds_optex
node_build -->|"installs documentation"| node_docs_pdf
node_docs_source -->|"compiled for distribution"| node_docs_pdf
node_test_config -.->|"shared settings"| node_latex_tests
node_test_config -.->|"shared settings"| node_context_tests
node_test_config -.->|"shared settings"| node_plain_tests
node_test_config -.->|"shared settings"| node_optex_tests
node_latex_tests -->|"validates integration"| node_latex
node_context_tests -->|"validates integration"| node_context
node_plain_tests -->|"validates integration"| node_plain
node_optex_tests -->|"validates integration"| node_optex
node_latex_tests -.->|"covers runtime variants"| node_luatex
node_context_tests -.->|"covers LuaMetaTeX"| node_luatex

click node_latex "https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.sty"
click node_plain "https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.tex"
click node_context "https://github.com/pskumaresh06/lua-widow-control/blob/master/source/t-lua-widow-control.mkxl"
click node_optex "https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.opm"
click node_legacy_latex "https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control-2022-02-22.sty"
click node_lua_engine "https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.lua"
click node_build "https://github.com/pskumaresh06/lua-widow-control/blob/master/build.lua"
click node_tds_lua_plain "https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/luatex/lua-widow-control/lua-widow-control.lua"
click node_tds_latex "https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty"
click node_tds_context "https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl"
click node_tds_optex "https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/optex/lua-widow-control/lua-widow-control.opm"
click node_docs_source "https://github.com/pskumaresh06/lua-widow-control/blob/master/docs/manual/lwc-manual.tex"
click node_docs_pdf "https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/doc/luatex/lua-widow-control/lua-widow-control.pdf"
click node_test_config "https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/test-config.lua"
click node_latex_tests "https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/latex/build.lua"
click node_context_tests "https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/context/build.lua"
click node_plain_tests "https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/plain/build.lua"
click node_optex_tests "https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/optex/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,node_plain,node_context,node_optex,node_legacy_latex toneBlue
class node_lua_engine,node_luatex,node_build,node_docs_source toneAmber
class node_tds_lua_plain,node_tds_latex,node_tds_context,node_tds_optex,node_docs_pdf toneMint
class node_test_config,node_latex_tests,node_context_tests,node_plain_tests,node_optex_tests toneRose
```

## Components

### Format Frontends

Macro wrappers adapt host formats to the shared Lua layer.

- [LaTeX interface](https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.sty): macro package · `source/lua-widow-control.sty`
- [Plain TeX interface](https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.tex): macro input · `source/lua-widow-control.tex`
- [ConTeXt interfaces](https://github.com/pskumaresh06/lua-widow-control/blob/master/source/t-lua-widow-control.mkxl): macro modules · `source/t-lua-widow-control.mkxl`
- [OpTeX interface](https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.opm): macro module · `source/lua-widow-control.opm`
- [Legacy LaTeX wrapper](https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control-2022-02-22.sty): compatibility package · `source/lua-widow-control-2022-02-22.sty`

### Authoritative Source

Editable package implementation and build entry point.

- [Widow-control engine](https://github.com/pskumaresh06/lua-widow-control/blob/master/source/lua-widow-control.lua): Lua layout engine · Detects page-break widows/orphans and re-breaks paragraphs longer. · `source/lua-widow-control.lua`
- **LuaTeX / LuaMetaTeX**: typesetting runtime · Provides node-list, paragraph-breaking, and page-building behavior.
- [Build orchestration](https://github.com/pskumaresh06/lua-widow-control/blob/master/build.lua): package build · `build.lua`
- [Manual and article sources](https://github.com/pskumaresh06/lua-widow-control/blob/master/docs/manual/lwc-manual.tex): TeX documentation · `docs/manual/lwc-manual.tex`

### TDS Distribution

Installable runtime and documentation tree.

- [Lua and Plain assets](https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/luatex/lua-widow-control/lua-widow-control.lua): TDS runtime files · `texmf/tex/luatex/lua-widow-control/lua-widow-control.lua`
- [LaTeX asset](https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty): TDS package · `texmf/tex/lualatex/lua-widow-control/lua-widow-control.sty`
- [ConTeXt asset](https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl): TDS module · `texmf/tex/context/third/lua-widow-control/t-lua-widow-control.mkxl`
- [OpTeX asset](https://github.com/pskumaresh06/lua-widow-control/blob/master/texmf/tex/optex/lua-widow-control/lua-widow-control.opm): TDS module · `texmf/tex/optex/lua-widow-control/lua-widow-control.opm`
- [Packaged documentation](https://github.com/pskumaresh06/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`

### Regression Matrix

Format-specific regression suites share fixtures and settings.

- [Shared test configuration](https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/test-config.lua): test settings · `tests/test-config.lua`
- [LaTeX regression suite](https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/latex/build.lua): integration tests · `tests/latex/build.lua`
- [ConTeXt regression suite](https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/context/build.lua): integration tests · `tests/context/build.lua`
- [Plain TeX regression suite](https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/plain/build.lua): integration tests · `tests/plain/build.lua`
- [OpTeX regression suite](https://github.com/pskumaresh06/lua-widow-control/blob/master/tests/optex/build.lua): integration tests · `tests/optex/build.lua`

## Connections

- LaTeX interface → Widow-control engine: loads shared Lua
- Plain TeX interface → Widow-control engine: loads shared Lua
- ConTeXt interfaces → Widow-control engine: loads shared Lua
- OpTeX interface → Widow-control engine: loads shared Lua
- Legacy LaTeX wrapper → Widow-control engine: compatibility integration
- Widow-control engine → LuaTeX / LuaMetaTeX: inspects nodes and re-breaks
- Build orchestration → Lua and Plain assets: packages
- Build orchestration → LaTeX asset: packages
- Build orchestration → ConTeXt asset: packages
- Build orchestration → OpTeX asset: packages
- Build orchestration → Packaged documentation: installs documentation
- Manual and article sources → Packaged documentation: compiled for distribution
- Shared test configuration → LaTeX regression suite: shared settings
- Shared test configuration → ConTeXt regression suite: shared settings
- Shared test configuration → Plain TeX regression suite: shared settings
- Shared test configuration → OpTeX regression suite: shared settings
- LaTeX regression suite → LaTeX interface: validates integration
- ConTeXt regression suite → ConTeXt interfaces: validates integration
- Plain TeX regression suite → Plain TeX interface: validates integration
- OpTeX regression suite → OpTeX interface: validates integration
- LaTeX regression suite → LuaTeX / LuaMetaTeX: covers runtime variants
- ConTeXt regression suite → LuaTeX / LuaMetaTeX: covers LuaMetaTeX