lib/zen/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

  1 //! Technical document compilation, static site rendering, and staged publication.
  2 //! Markdown parsing evaluates syntax depth limits and derives memory bounds
  3 //! upfront via explicit planning passes.
  4 //!
  5 //! Clean site publication renders pages into an isolated staging directory,
  6 //! allowing validation checks to run before promoting changes. If rendering or
  7 //! validation fails, publication aborts and the prior live site remains
  8 //! untouched. Directory promotion swaps the staging path into place via a
  9 //! filesystem rename, which requires both directories to reside on the same
 10 //! filesystem device.
 11 
 12 /// Declarative diagrams, bounded JSONL documents, and ASCII rendering.
 13 pub const diagram = @import("diagram/root.zig");
 14 /// Code-fence metadata, syntax highlighting, and HTML rendering.
 15 pub const code = @import("code.zig");
 16 /// Fixed-capacity source-local failure detail.
 17 pub const diagnostic = @import("diagnostic.zig");
 18 /// Bounded heading plans, storage, and borrowed document views.
 19 pub const document = @import("document/root.zig");
 20 /// Bounded Markdown footnote planning and parsing.
 21 pub const footnote = @import("footnote/root.zig");
 22 /// Bounded YAML-like page metadata planning and parsing.
 23 pub const frontmatter = @import("frontmatter/root.zig");
 24 /// HTML text and attribute escaping helpers.
 25 pub const html = @import("html.zig");
 26 /// Markdown inspection and owned HTML rendering.
 27 pub const markdown = @import("markdown.zig");
 28 /// TeX-like expression parsing and MathML rendering.
 29 pub const math = @import("math/root.zig");
 30 /// Bounded interactive and recall quiz parsing.
 31 pub const quiz = @import("quiz/root.zig");
 32 /// Atomic static-site publication and bounded site working storage.
 33 pub const site = @import("site/root.zig");
 34 const site_catalog = site.catalog;
 35 const site_page = site.page;
 36 const site_path = site.path;
 37 /// Slide-deck rendering and print support.
 38 pub const slides = @import("slides/root.zig");
 39 /// Page templates, source theme loading, and bounded page rendering.
 40 pub const theme = @import("theme/root.zig");
 41 
 42 /// Owned parsed diagram model; release it through its `deinit` method.
 43 pub const DiagramDocument = diagram.Document;
 44 /// Bounds JSON line scratch and retained diagram-document bytes.
 45 pub const DiagramDocumentLimits = diagram.DocumentLimits;
 46 /// Exact diagram-document demand measured before storage acquisition.
 47 pub const DiagramDocumentPlan = diagram.DocumentPlan;
 48 /// Checked byte layout derived from `DiagramDocumentLimits`.
 49 pub const DiagramDocumentCapacity = diagram.DocumentCapacity;
 50 /// Reports arithmetic overflow while deriving diagram-document capacity.
 51 pub const DiagramDocumentCapacityError = diagram.DocumentCapacityError;
 52 /// Reusable caller-allocated storage for one parsed JSONL diagram.
 53 pub const DiagramDocumentStorage = diagram.DocumentStorage;
 54 /// Reports active and high-water use of diagram-document storage.
 55 pub const DiagramDocumentStorageStatus = diagram.DocumentStatus;
 56 /// Identifies the diagram-document resource that rejected an input.
 57 pub const DiagramDocumentStorageExhaustion = diagram.DocumentExhaustion;
 58 /// Diagram parsing failures, storage exhaustion, and host-size overflow.
 59 pub const DiagramDocumentError = diagram.DocumentError;
 60 /// Parses JSONL into active storage; reset after the borrowed document's last use.
 61 pub const parseDiagram = diagram.parse;
 62 /// Requested ASCII dimensions, clamped to 24...200 columns and 8...80 rows.
 63 pub const AsciiDiagramOptions = diagram.AsciiOptions;
 64 /// Bounds categories, stack totals, canvas bytes, and output bytes.
 65 pub const AsciiRenderLimits = diagram.AsciiRenderLimits;
 66 /// Exact, clamped ASCII demand for one document and option set.
 67 pub const AsciiRenderPlan = diagram.AsciiRenderPlan;
 68 /// Checked one-region byte layout derived from `AsciiRenderLimits`.
 69 pub const AsciiRenderCapacity = diagram.AsciiRenderCapacity;
 70 /// Reusable caller-allocated storage for bounded ASCII rendering.
 71 pub const AsciiRenderStorage = diagram.AsciiRenderStorage;
 72 /// Reports active, high-water, and rejected ASCII render demand.
 73 pub const AsciiRenderStatus = diagram.AsciiRenderStatus;
 74 /// Identifies the exhausted ASCII region or an already active output.
 75 pub const AsciiRenderExhaustion = diagram.AsciiRenderExhaustion;
 76 /// ASCII exhaustion, invalid scales, and capacity overflow.
 77 pub const AsciiRenderError = diagram.AsciiRenderError;
 78 /// Owns ASCII output and storage; release it with `deinit` and the same allocator.
 79 pub const AsciiRendered = diagram.AsciiRendered;
 80 /// Parses JSONL and returns an owned ASCII render.
 81 pub const renderAscii = diagram.renderAscii;
 82 /// Returns an owned ASCII render of an existing diagram document.
 83 pub const renderAsciiOwned = diagram.renderAsciiOwned;
 84 /// Renders into active storage; output borrows it until `reset`.
 85 pub const renderAsciiDocument = diagram.renderAsciiDocument;
 86 
 87 /// Borrowed page metadata with named accessors for standard fields.
 88 pub const Metadata = frontmatter.Metadata;
 89 /// One borrowed frontmatter key and value.
 90 pub const Pair = frontmatter.Pair;
 91 /// Borrowed metadata plus the Markdown body after the frontmatter block.
 92 pub const Parsed = frontmatter.Parsed;
 93 /// Bounds frontmatter pair count and joined continuation bytes.
 94 pub const FrontmatterLimits = frontmatter.Limits;
 95 /// Exact frontmatter demand and common-field projection measured without allocation.
 96 pub const FrontmatterPlan = frontmatter.Plan;
 97 /// Checked one-region byte layout derived from `FrontmatterLimits`.
 98 pub const FrontmatterCapacity = frontmatter.Capacity;
 99 /// Reports arithmetic overflow while deriving frontmatter capacity.
100 pub const FrontmatterCapacityError = frontmatter.CapacityError;
101 /// Reusable caller-allocated storage for one parsed frontmatter block.
102 pub const FrontmatterStorage = frontmatter.Storage;
103 /// Reports phase, active use, and admitted frontmatter capacity.
104 pub const FrontmatterStorageStatus = frontmatter.Status;
105 /// Identifies exceeded frontmatter storage or an already active result.
106 pub const FrontmatterStorageExhaustion = frontmatter.Exhaustion;
107 /// Frontmatter syntax, exhaustion, and checked-capacity failures.
108 pub const FrontmatterError = frontmatter.Error;
109 /// Parses into active storage; the result borrows it until `reset`.
110 pub const parseFrontmatter = frontmatter.parse;
111 
112 /// One footnote definition with assigned display and reference counts.
113 pub const FootnoteDefinition = footnote.Definition;
114 /// Borrowed footnote set that assigns numbers in reference order.
115 pub const FootnoteSet = footnote.Set;
116 /// Bounds definition count and copied continuation-text bytes.
117 pub const FootnoteLimits = footnote.Limits;
118 /// General-purpose limits for Markdown footnotes.
119 pub const default_footnote_limits = footnote.default_limits;
120 /// Exact footnote storage demand measured before allocation.
121 pub const FootnotePlan = footnote.Plan;
122 /// Checked one-region byte layout derived from `FootnoteLimits`.
123 pub const FootnoteCapacity = footnote.Capacity;
124 /// Capacity derived from `default_footnote_limits`.
125 pub const default_footnote_capacity = footnote.default_capacity;
126 /// Reports arithmetic overflow while deriving footnote capacity.
127 pub const FootnoteCapacityError = footnote.CapacityError;
128 /// Reusable caller-allocated storage for one parsed footnote set.
129 pub const FootnoteStorage = footnote.Storage;
130 /// Reports active, high-water, and rejected footnote demand.
131 pub const FootnoteStorageStatus = footnote.Status;
132 /// Identifies exceeded footnote storage or an already active result.
133 pub const FootnoteStorageExhaustion = footnote.Exhaustion;
134 /// Footnote exhaustion and checked-capacity failures.
135 pub const FootnoteError = footnote.Error;
136 /// Parses into active storage; the set borrows it until `reset`.
137 pub const parseFootnotes = footnote.parse;
138 
139 /// One borrowed quiz answer option and whether it is correct.
140 pub const QuizOption = quiz.Option;
141 /// One borrowed quiz prompt, answer options, and explanation.
142 pub const QuizQuestion = quiz.Question;
143 /// Borrowed collection of parsed quiz questions.
144 pub const Quiz = quiz.Quiz;
145 /// Bounds question count, option count, and joined text bytes.
146 pub const QuizLimits = quiz.Limits;
147 /// General-purpose limits for one quiz fence.
148 pub const default_quiz_limits = quiz.default_limits;
149 /// Exact quiz storage demand measured before allocation.
150 pub const QuizPlan = quiz.Plan;
151 /// Checked one-region byte layout derived from `QuizLimits`.
152 pub const QuizCapacity = quiz.Capacity;
153 /// Capacity derived from `default_quiz_limits`.
154 pub const default_quiz_capacity = quiz.default_capacity;
155 /// Reports arithmetic overflow while deriving quiz capacity.
156 pub const QuizCapacityError = quiz.CapacityError;
157 /// Reusable caller-allocated storage for one parsed quiz.
158 pub const QuizStorage = quiz.Storage;
159 /// Reports active, high-water, and rejected quiz demand.
160 pub const QuizStorageStatus = quiz.Status;
161 /// Identifies exceeded quiz storage or an already active result.
162 pub const QuizStorageExhaustion = quiz.Exhaustion;
163 /// Invalid quiz syntax, exhaustion, and checked-capacity failures.
164 pub const QuizError = quiz.Error;
165 /// Parses into active storage; the quiz borrows it until `reset`.
166 pub const parseQuiz = quiz.parse;
167 
168 /// Borrowed language and title parsed from a code-fence info string.
169 pub const CodeInfo = code.Info;
170 /// Controls highlighting, numbering, titles, labels, and wrapping.
171 pub const CodeOptions = code.Options;
172 /// Splits a code-fence info string into language and title without allocation.
173 pub const parseCodeInfo = code.parseInfo;
174 /// Appends escaped, optionally highlighted code-block HTML to caller-owned output.
175 pub const renderCode = code.render;
176 
177 /// Borrowed heading view held by active `HeadingStorage`.
178 pub const Document = document.Document;
179 /// One copied heading with level, visible text, stable ID, and source offset.
180 pub const Heading = document.Heading;
181 /// Bounds heading count plus copied heading-text and identifier bytes.
182 pub const HeadingLimits = document.Limits;
183 /// General-purpose heading limits used by `MarkdownOptions`.
184 pub const default_heading_limits = document.default_limits;
185 /// Exact heading storage demand measured without allocation.
186 pub const HeadingPlan = document.Plan;
187 /// Checked one-region byte layout derived from `HeadingLimits`.
188 pub const HeadingCapacity = document.Capacity;
189 /// General-purpose heading capacity derived from `default_heading_limits`.
190 pub const default_heading_capacity = document.default_capacity;
191 /// Reports arithmetic overflow while deriving heading capacity.
192 pub const HeadingCapacityError = document.CapacityError;
193 /// Reusable caller-allocated storage for one inspected Markdown document.
194 pub const HeadingStorage = document.Storage;
195 /// Reports active, high-water, and rejected heading demand.
196 pub const HeadingStorageStatus = document.Status;
197 /// Identifies the exceeded heading region or an already active document.
198 pub const HeadingStorageExhaustion = document.Exhaustion;
199 /// Heading exhaustion, `InvalidHeadingAnchor`, `DuplicateHeadingAnchor`, and overflow.
200 pub const HeadingError = document.Error;
201 
202 pub const MarkdownOptions = markdown.Options;
203 pub const MarkdownMode = markdown.Mode;
204 pub const RenderedMarkdown = markdown.Rendered;
205 pub const RenderedMarkdownLink = markdown.RenderedLink;
206 pub const MarkdownLinkReport = markdown.LinkReport;
207 /// Maximum backtick runs in one inline fragment before rendering rejects it.
208 pub const max_markdown_inline_delimiters = markdown.max_inline_delimiters;
209 /// Maximum nested link/emphasis, label brackets, or target parentheses.
210 pub const max_markdown_inline_nesting = markdown.max_inline_nesting;
211 /// Measures exact heading storage demand without allocating.
212 pub const planMarkdownHeadings = markdown.plan;
213 /// Fills active `HeadingStorage`; the document borrows it until `reset`.
214 pub const inspectMarkdown = markdown.inspect;
215 /// Renders Markdown into an owned result; release it with the same allocator.
216 ///
217 /// Malformed link targets return `InvalidInlineLink`. Inline input beyond
218 /// `max_markdown_inline_delimiters` or `max_markdown_inline_nesting` returns the
219 /// corresponding capacity error with source-local `Diagnostic` repair detail.
220 /// The nesting cap covers recursive links/emphasis, label brackets, and target
221 /// parentheses.
222 pub const renderMarkdown = markdown.render;
223 /// Controls slide CSS classes, ID prefix, badge, and browser runtime emission.
224 pub const SlidesOptions = slides.Options;
225 
226 /// Borrowed site title, language, layout, stylesheet, and include fragments.
227 pub const Theme = theme.Theme;
228 /// Theme loading and template rendering failures.
229 pub const ThemeError = theme.Error;
230 /// Selects bounded theme files relative to a site source root.
231 pub const ThemeFiles = theme.Files;
232 /// Named raw HTML fragment available to a theme placeholder.
233 pub const ThemeInclude = theme.Include;
234 /// Owns any theme file bytes loaded over a borrowed base; release with `deinit`.
235 pub const LoadedTheme = theme.Loaded;
236 /// Borrowed title, description, content, path, and metadata for one page.
237 pub const Page = theme.Page;
238 /// Loads optional source theme files over a borrowed base theme.
239 pub const loadTheme = theme.load;
240 /// Bounds the rendered byte length of one themed page.
241 pub const ThemeRenderLimits = theme.RenderLimits;
242 /// General-purpose output limits for theme rendering.
243 pub const default_theme_render_limits = theme.default_render_limits;
244 /// Exact themed-page byte demand measured before storage acquisition.
245 pub const ThemeRenderPlan = theme.RenderPlan;
246 /// Checked output-byte capacity derived from `ThemeRenderLimits`.
247 pub const ThemeRenderCapacity = theme.RenderCapacity;
248 /// Capacity derived from `default_theme_render_limits`.
249 pub const default_theme_render_capacity = theme.default_render_capacity;
250 /// Reusable caller-allocated storage for one rendered themed page.
251 pub const ThemeRenderStorage = theme.RenderStorage;
252 /// Reports active, high-water, and rejected theme output demand.
253 pub const ThemeRenderStatus = theme.RenderStatus;
254 /// Identifies exceeded theme output or an already active result.
255 pub const ThemeRenderExhaustion = theme.RenderExhaustion;
256 /// Invalid templates, exhaustion, and checked-capacity failures.
257 pub const ThemeRenderError = theme.RenderError;
258 /// Renders into active storage; returned HTML borrows it until `reset`.
259 pub const renderPage = theme.renderPage;
260 
261 /// Bounds and controls one source-tree to static-site publication.
262 pub const BuildOptions = site.BuildOptions;
263 /// Optional check over complete staging output before publication.
264 pub const BeforePublish = site.BeforePublish;
265 /// Counts published pages and assets, skipped drafts and slop, and transferred bytes.
266 pub const BuildResult = site.BuildResult;
267 /// One retained public page record in a sealed site catalog.
268 pub const SiteCatalogEntry = site_catalog.Entry;
269 /// Selects the document editor or presentation workbench for an authored route.
270 pub const SiteCatalogDispatch = site_catalog.Dispatch;
271 /// Borrowed values copied when appending one site catalog entry.
272 pub const SiteCatalogEntryInput = site_catalog.EntryInput;
273 /// Borrowed sorted catalog produced by sealed `SiteCatalogStorage`.
274 pub const SiteCatalog = site_catalog.Catalog;
275 /// Bounds retained page count and copied catalog text bytes.
276 pub const SiteCatalogLimits = site_catalog.Limits;
277 /// General-purpose site catalog limits.
278 pub const default_site_catalog_limits = site_catalog.default_limits;
279 /// Byte demand contributed by one site catalog entry.
280 pub const SiteCatalogDemand = site_catalog.Demand;
281 /// Accumulates exact site catalog demand before storage acquisition.
282 pub const SiteCatalogPlan = site_catalog.Plan;
283 /// Checked one-region layout derived from `SiteCatalogLimits`.
284 pub const SiteCatalogCapacity = site_catalog.Capacity;
285 /// Reports arithmetic overflow while deriving site catalog capacity.
286 pub const SiteCatalogCapacityError = site_catalog.CapacityError;
287 /// Append-only storage whose `seal` result borrows its sorted entries and text.
288 pub const SiteCatalogStorage = site_catalog.Storage;
289 /// Reports retained catalog demand, rejection count, and seal state.
290 pub const SiteCatalogStorageStatus = site_catalog.Status;
291 /// Identifies exceeded catalog pages or text bytes.
292 pub const SiteCatalogStorageExhaustion = site_catalog.Exhaustion;
293 /// Site catalog exhaustion and checked-capacity failures.
294 pub const SiteCatalogError = site_catalog.Error;
295 /// Hidden opt-in authored route manifest published inside a rendered site.
296 pub const authored_route_manifest_path = site.authored_route_manifest_path;
297 /// Schema version stored in `authored_route_manifest_path`.
298 pub const authored_route_manifest_version = site.authored_route_manifest_version;
299 /// Bounds the largest reusable Markdown page input buffer.
300 pub const SitePageLimits = site_page.Limits;
301 /// General-purpose per-page input limits.
302 pub const default_site_page_limits = site_page.default_limits;
303 /// Accumulates the largest admitted Markdown page size.
304 pub const SitePagePlan = site_page.Plan;
305 /// Checked page-buffer capacity derived from `SitePageLimits`.
306 pub const SitePageCapacity = site_page.Capacity;
307 /// Capacity derived from `default_site_page_limits`.
308 pub const default_site_page_capacity = site_page.default_capacity;
309 /// Reports arithmetic overflow while deriving page-buffer capacity.
310 pub const SitePageCapacityError = site_page.CapacityError;
311 /// Reusable caller-allocated buffer for one surveyed Markdown page.
312 pub const SitePageStorage = site_page.Storage;
313 /// Reports active, high-water, and rejected page byte demand.
314 pub const SitePageStorageStatus = site_page.Status;
315 /// Identifies an oversized page or an already active page buffer.
316 pub const SitePageStorageExhaustion = site_page.Exhaustion;
317 /// Site page exhaustion and checked-capacity failures.
318 pub const SitePageError = site_page.Error;
319 /// Bounds transformed target-path and public-URL bytes.
320 pub const SitePathLimits = site_path.Limits;
321 /// General-purpose site path limits.
322 pub const default_site_path_limits = site_path.default_limits;
323 /// Exact transformed site-path demand measured before storage acquisition.
324 pub const SitePathPlan = site_path.Plan;
325 /// Checked path-buffer capacity derived from `SitePathLimits`.
326 pub const SitePathCapacity = site_path.Capacity;
327 /// Capacity derived from `default_site_path_limits`.
328 pub const default_site_path_capacity = site_path.default_capacity;
329 /// Reports arithmetic overflow while deriving site path capacity.
330 pub const SitePathCapacityError = site_path.CapacityError;
331 /// Reusable caller-allocated target-path and public-URL storage.
332 pub const SitePathStorage = site_path.Storage;
333 /// Reports active, high-water, and rejected path byte demand.
334 pub const SitePathStorageStatus = site_path.Status;
335 /// Identifies exceeded path storage or an already active path view.
336 pub const SitePathStorageExhaustion = site_path.Exhaustion;
337 /// Site path exhaustion and checked-capacity failures.
338 pub const SitePathError = site_path.Error;
339 /// Fixed-capacity source-local detail for rendering and publication failures.
340 pub const Diagnostic = diagnostic.Diagnostic;
341 /// Publishes through staging; render and hook failures preserve prior output.
342 pub const buildSite = site.buildSite;