Use the React package for imports and a small
rendering example. FormulaSheet displays supplied values; numerical evaluation
belongs to core verification.
| Input | Use | Authoritative code |
|---|---|---|
CalculationSourceObject |
Formulas, symbols, source context and ordered content | object schema, parser |
| Value-tree JSON | Compact adapter for mathematical rows | schema, conversion |
SheetDocument |
Direct mathematical sheet passed to FormulaSheet |
schema, row traversal |
PreparedDocument |
Ordered engineering document with prose, figures and retained evidence | document contract, preparation, renderer |
Parse unknown input with the public schema/parser for that contract. Use
safeParse when the caller handles validation failures. Read accepted fields
and defaults from the schemas, rather than maintaining another interface here.
Value trees carry a root, references and supplied results. Reference identities must resolve; glyphs are display labels, not reference keys. Repeated placement of one symbol retains its identity. A math-only sheet cannot establish complete preservation of a source containing figures or standalone text.
For Python export, use the core code generator. It orders assignments by dependency and generates Python without executing it.
Default HTML/PDF shows the engineering narrative: ordered inputs and formulas, substitutions, units, explanations, diagrams, assumptions, qualifications and results. Full source/audit data stays in machine-readable evidence. Internal records and historical reviews do not become an automatic printed appendix.
Context preparation selects which source fields have a presentation role. Preserve unmapped extensions, own-key identities, empty/falsy values and ordered metadata in evidence. Map visible content back to retained source data. Historical attribution never approves a new execution. See ADR 0002.
PreparedDocument version 2 carries selected context on the document, sections
and item placements. Symbol placements also carry context for active operands
that have no placement of their own. The renderer consumes these fields without
searching historical reviews, selecting metadata or traversing operand context.
Every displayed context value has a JSON pointer to retained current-source
data; the document schema checks that the pointer resolves to the same value.
This checks attribution within the document, not independent numerical agreement.
Current source and section metadata remain in sourceMetadata and section
metadata. Item contextSource retains authored placement metadata, nested
content metadata and unconsumed content fields. Historical records remain
separate retained evidence; changing their order does not change presentation.
Reprepare after changing source context, symbols or placements.
Version 1 prepared JSON is rejected. Regenerate saved documents with
prepareExecutionDocument from the captured execution and assets, or with
prepareLegacyDocument from the original CSO, asset manifest and captured assets.
Reattach historical reviews through the preparation options. Synthetic documents
constructed directly must provide context arrays and symbol operand arrays.
Update core and React together; source CSO and execution versions are unchanged.
The pure preparer receives captured data URLs and validates their binding to
the execution. The CLI owns file containment,
capture, media validation and image decoding. For imported documents, supply a
LegacyAssetManifest binding figure IDs and URLs to captured bytes, captions and
alt text. Authored widths remain preferred CSS pixel sizes constrained to the page.
Glyphs and units use the small ASCII parser.
Braces group subscripts, superscripts and fractions: A_{rect}, mm^{2},
{height+width}/{2}. Parentheses and brackets are literal text. Greek names
may be plain or backslash-prefixed, such as rho and \rho. Other command-like
words render as text; \frac and \sqrt are not glyph commands.
The alias table lists supported names. Parser tests and glyph tests show edge cases. Apply the authoring naming rules to new variables.
Formula structure comes from value-tree functions. Function specs define IDs and precedence; MathML renderers define layout. The numeric verifier supports a smaller arithmetic subset. When adding a function, update the owning implementations and their behavior tests; rendering support alone is not numerical support.
Import @viktar-b/cso-react/style.css once. Browser printFormulaSheet accepts
a sheet target and waits for cloned images. Its boolean result means the request
was accepted; onError reports deferred failures. See the print implementation
and browser tests.
Verified PDF generation runs through the CLI. Content retention tests, rendering success and every-page inspection are separate. Prepared-document tests check retained fields and engineering presentation using synthetic inputs. Extracted text or a page count cannot establish visual acceptance.