create-cs-object 0.1.1 → 0.1.3

package/README.md

@@ -9,6 +9,43 @@ cd my-report
 npm run dev
 ```
 
+In PowerShell 5.1 or 7, select Python 3.11+ and run the setup steps explicitly:
+
+```powershell
+$env:PYTHON = Get-Command python -CommandType Application | Select-Object -First 1 -ExpandProperty Source
+& $env:PYTHON --version
+```
+
+<!-- docs:project-create:start -->
+```powershell
+npm.cmd create cs-object my-report -- --skip-install
+if ($LASTEXITCODE -ne 0) { throw 'Project creation failed.' }
+Set-Location my-report
+```
+<!-- docs:project-create:end -->
+
+<!-- docs:project-setup:start -->
+```powershell
+npm.cmd run setup
+if ($LASTEXITCODE -ne 0) { throw 'Project setup failed.' }
+```
+<!-- docs:project-setup:end -->
+
+<!-- docs:project-dev:start -->
+```powershell
+npm.cmd run dev -- --port 4173
+if ($LASTEXITCODE -ne 0) { throw 'The development server failed.' }
+```
+<!-- docs:project-dev:end -->
+
+Use an absolute Python executable path for `PYTHON` if the interpreter is not
+on PATH. A launcher-only installation can supply that path with
+`$env:PYTHON = py -3.11 -c 'import json, sys; print(json.dumps(sys.executable))' | ConvertFrom-Json`.
+The JSON capture preserves Unicode executable paths under legacy console encodings.
+`PYTHON` is an executable path, not a command such as `py -3.11`.
+The project uses its own `.venv`; activation and execution-policy changes are
+unnecessary. See the generated project's `README.md` for browser and API usage.
+
 The initializer creates an owned project template, installs its exact CLI
 dependency, prepares `.venv`, and installs Chromium. It preserves generated
 files after setup failure; run `npm run setup` in the project to retry.
@@ -16,8 +53,16 @@ Existing destinations are never overwritten.
 
 Use `--skip-install` to create files without installing dependencies.
 The generated project contains a synthetic rectangle calculation, an editable
-brief, reference storage, and agent-neutral authoring guidance. The CLI serves
-the browser and report API. The initializer contains no server implementation.
+brief, reference storage, and agent-neutral authoring guidance. Its editable
+React and TypeScript page uses Vite, Tailwind and the selected shadcn preset.
+`npm run dev` starts that page and the CLI calculation and report API on localhost.
+The initializer contains no calculation server implementation.
+The page's navbar report menu reads `reports.json`; each configured report runs
+through its own local CLI process.
 
 Package tests execute a real npm archive in a temporary consumer. Full runtime
 acceptance belongs to the repository's installed integration checks.
+Before a registry release, use the repository's
+[local archive workflow](../../docs/development.md#local-package-consumers).
+An initializer archive alone still installs the dependency versions named by
+its template; it does not select sibling archives automatically.

package/dist/cli.js

@@ -37,9 +37,36 @@ try {
           engines: { node: ">=24" },
           scripts: {
             setup: "npm install && node scripts/setup.ts",
-            dev: "node scripts/dev.ts"
+            dev: "node scripts/dev.ts",
+            build: "tsc -b && vite build",
+            typecheck: "tsc -b --pretty false"
           },
-          dependencies: { "@cs-object/cli": "0.1.0" }
+          dependencies: {
+            "@cs-object/cli": "0.1.1",
+            "@cs-object/core": "0.1.0",
+            "@base-ui/react": "^1.8.0",
+            "@fontsource-variable/geist-mono": "^5.3.0",
+            "@fontsource-variable/raleway": "^5.3.0",
+            "@hugeicons/core-free-icons": "^4.3.5",
+            "@hugeicons/react": "^1.1.10",
+            "@tailwindcss/vite": "^4",
+            "class-variance-authority": "^0.7.1",
+            cn: "^0.4.0",
+            react: "^19.2.8",
+            "react-dom": "^19.2.8",
+            shadcn: "^4.21.0",
+            tailwindcss: "^4",
+            "tw-animate-css": "^1.4.0",
+            vite: "^8",
+            zod: "^4.6.5"
+          },
+          devDependencies: {
+            "@types/node": "^24",
+            "@types/react": "^19",
+            "@types/react-dom": "^19",
+            "@vitejs/plugin-react": "^6",
+            typescript: "^5"
+          }
         },
         null,
         2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cs-object",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Create a local CalculationSourceObject report project.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,9 +30,12 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
+    "@cs-object/core": "0.1.0",
     "@types/node": "^26",
     "tsup": "^8.5.1",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vite": "^8.3.1",
+    "zod": "^4.6.5"
   },
   "repository": {
     "type": "git",

package/template/.gitattributes

@@ -0,0 +1,2 @@
+*.py text eol=lf
+*.pyi text eol=lf

package/template/AGENTS.md

@@ -6,12 +6,21 @@ the result, units, load case, or acceptance criteria. Record the agreed scope
 in the brief and cite the source of each engineering requirement.
 
 Edit formulas in `calculations/report.cso.py`; the browser edits numeric inputs.
+Edit page layout in `src/App.tsx`, theme tokens in `src/index.css`, and shared UI
+components in `src/components/ui/`. Keep numeric input names and validation
+derived from the Python definition. Add shadcn components with
+`npx shadcn@latest add <component>`.
+Add each runnable report to `reports.json` with a unique ID, title, source path
+and entry function. Restart the local server to update the report menu.
 Read [authoring.md](authoring.md) before changing source or notation. Keep inputs,
 units, assumptions, intermediate steps, references, and outputs inspectable.
 
-Run the calculation with representative inputs and review its rendered report.
+For verification commands and completion criteria, follow
+[Check the result](authoring.md#check-the-result). Run the calculation with
+representative inputs and review its rendered report.
 Report source-to-document consistency, independent numerical agreement, and
 human engineering approval separately. Establish expected reference values
-independently of the execution under test. Inspect every PDF page before delivery.
+independently of the execution under test. When delivering a PDF, inspect every
+page before delivery.
 
 This project runs on localhost. Deployment is outside its calculation workflow.

package/template/README.md

@@ -7,12 +7,56 @@ Node dependencies, creates a private `.venv`, and installs Chromium for PDF outp
 npm run dev
 ```
 
+In PowerShell 5.1 or 7, use `npm.cmd run dev`. Commands that invoke the installed
+CLI directly use `.\node_modules\.bin\cso.cmd`; see
+[Check the result](authoring.md#check-the-result).
+
 Open the localhost address printed in the terminal. Edit numeric inputs in the
-browser, calculate, review the report, and download its PDF. Change formulas in
-`calculations/report.cso.py`, then calculate again. If you change the declared
+browser, calculate, and review the report. Download its PDF when needed. Change
+formulas in `calculations/report.cso.py`, then calculate again. If you change the declared
 inputs, reload the browser page to rebuild its form. Existing report downloads
 remain tied to their captured run until that run expires or the server stops.
 
+Customize the page in `src/App.tsx` and its theme in `src/index.css`. The
+components in `src/components/ui/` are owned by this project. To add another
+shadcn component, run `npx shadcn@latest add <component>` and edit the page to
+use it. `components.json` records the chosen Vite, Base UI and Lyra preset.
+The input fields still come from the Python definition; page edits do not change
+the calculation or API validation. `npm run build` checks and builds the Vite
+frontend, but the local API and PDF routes still require `npm run dev`.
+
+The navbar menu lists runnable reports from [reports.json](reports.json).
+To add one, put its `.cso.py` source under `calculations/` and add an entry with
+a unique URL-safe `id`, a display `title`, the relative `source` path and its
+entry `function`. Add `reference` when the report has an independent numerical
+reference file. Restart `npm run dev` after editing the list. Each entry gets
+its own verified local API at `/api/reports/<id>/`; the menu switches between
+them without changing the input or report UI code.
+
+For the starter, send inputs to the frontend's `/api/reports/rectangle-area/calculate`
+route. Replace the origin with the address printed by `npm run dev`:
+
+```sh
+curl --fail-with-body http://127.0.0.1:5173/api/reports/rectangle-area/calculate \
+  -H 'Content-Type: application/json' \
+  -d '{"inputs":{"width":2,"height":3}}'
+```
+
+The result is `{"area":6}`. Use the report ID from `reports.json` in place of
+`rectangle-area` after replacing the starter. `POST /api/reports/<id>/runs`
+accepts the same body and returns a captured run with report and download links.
+Wait for the initial report to load before testing input edits in the browser.
+
+In PowerShell 5.1 or 7, the equivalent request avoids native-shell JSON quoting:
+
+```powershell
+$request = @{ inputs = @{ width = 2; height = 3 } } | ConvertTo-Json
+Invoke-RestMethod -Uri 'http://127.0.0.1:5173/api/reports/rectangle-area/calculate' -Method Post -ContentType 'application/json; charset=utf-8' -Body $request
+```
+
+Use the port printed by your development server, such as `4173` when you select
+that port explicitly. The response's `area` property is `6`.
+
 To choose a port, run `npm run dev -- --port 4173`. Use port `0` to select an
 available port. Stop the server with Ctrl+C and use the same command to restart.
 
@@ -20,6 +64,20 @@ If setup failed or you used `--skip-install`, run `npm run setup`.
 Set `PYTHON` to a Python executable if automatic detection cannot find Python
 3.11 or newer. Setup can be run again without replacing calculation files.
 
+In PowerShell, retry with `npm.cmd run setup`. `PYTHON` accepts one absolute
+executable path, including a path with spaces. Use
+`& $env:PYTHON --version` to inspect it. Setup creates `.venv\Scripts\python.exe`.
+You do not need to activate the environment or change an execution policy.
+
+Build the frontend from PowerShell with:
+
+<!-- docs:project-build:start -->
+```powershell
+npm.cmd run build
+if ($LASTEXITCODE -ne 0) { throw 'The frontend build failed.' }
+```
+<!-- docs:project-build:end -->
+
 Before replacing the starter, update [the brief](brief.md), collect
 [references](references/README.md), and read [the authoring notes](authoring.md).
 Source-to-document consistency checks that the documented formulas agree with

package/template/authoring.md

@@ -1,18 +1,247 @@
-# Write scalar calculations
-
-Use constrained Python in `calculations/report.cso.py`. Declare documented inputs
-and assignments with `Annotated[float, symbol(...)]` or
-`Annotated[int, symbol(...)]`. A plain `float` or `int` parameter needs a separate
-documented `given()` assignment.
-Use descriptive names and qualified glyphs such as `A_{rect}`. Define units and
-explain each glyph qualifier. Return a dictionary that selects documented values.
-
-Use finite scalar numbers and arithmetic `+`, `-`, `*`, `/`, and `**`.
-Python booleans are not numeric inputs. Declare `float` for fractional results.
-Exact integers must fit within ±(2**53 - 1). Keep assumptions and references in
-literal `text(id=..., content=...)` calls so they appear in the report.
-
-The [maintained authoring guide](https://github.com/viktar-b/CalculationSourceObject/blob/main/docs/authoring.md)
-describes supported functions, composition, and document content. Unsupported
-Python constructs must be replaced with supported scalar expressions before
-the calculation can pass verification.
+# Author calculations
+
+This guide ships with the generated project. Write constrained Python in
+`calculations/*.cso.py`; the installed `cs-object` package captures the same
+source for numerical execution and the report. Start with
+[`calculations/report.cso.py`](calculations/report.cso.py), then replace the
+rectangle example with the calculation in [brief.md](brief.md). Keep the
+brief, sources and reviewable report consistent.
+
+## Before writing formulas
+
+State the purpose, input ranges, units, assumptions, required outputs and
+acceptance cases in [brief.md](brief.md). Keep source documents or links under
+[`references/`](references/README.md), with the edition, page or clause and the
+assumption each supports. Ask for a decision when a missing assumption would
+change the result. Establish expected numerical values independently of the
+calculation being checked; formula agreement alone does not establish
+engineering correctness.
+
+## Define a report
+
+The starter shows the full pattern:
+
+```python
+from typing import Annotated
+from cso_python import calculation, section, symbol, text
+
+
+@calculation(id="rectangle-area", title="Rectangle area")
+@section(title="Rectangle", root=True)
+def calculate(
+    width: Annotated[float, symbol(glyph="w_{rect}", description="Rectangle width", unit="m")] = 2.0,
+    height: Annotated[float, symbol(glyph="h_{rect}", description="Rectangle height", unit="m")] = 3.0,
+):
+    text(id="assumptions", content="Assume perpendicular sides and positive dimensions. The qualifier rect means rectangle.")
+    text(id="reference", content="Area equals width multiplied by height; see brief.md for the project scope.")
+    area: Annotated[float, symbol(glyph="A_{rect}", description="Rectangle area", unit="m^2")] = width * height
+    return {"area": area}
+```
+
+Each runnable function needs `@calculation`, `@section`, documented numeric
+parameters and a final dictionary of public results. Put arithmetic in
+annotated assignments before the return. The return selects existing
+quantities; it does not replace their documented formula rows. Source order
+sets report order, while return order sets the public output order. Intermediate
+annotated quantities remain in the report even when they are not returned.
+
+Use descriptive Python names such as `total_area`, not one-letter identifiers.
+Give every quantity a glyph, description and unit. Qualify variable glyphs,
+including diagram labels: `A_{rect}`, `w_{pan}` and `\rho_{mat}` distinguish
+their meanings. Explain qualifiers in the report. Standard unit symbols such as
+`m` and `kg` need no qualifier. Use raw strings for backslash Greek names,
+for example `r"\rho_{mat}"`. The notation parser is not a LaTeX engine:
+`\mathrm` and `\frac` are unsupported. When reproducing an identified
+external calculation, its original glyphs may be retained with a recorded
+source URL and explanation of any repeated notation.
+
+Signature metadata creates an input row, including when the parameter is not
+used in a formula. A plain `float` or `int` parameter instead needs one
+annotated `given(parameter)` assignment; do not document the same parameter
+both ways. Give inputs finite literal defaults. Declare `float` when division
+or another operation can produce a fractional value. An `int` declaration
+requires an actual Python integer; a `float` declaration accepts finite
+Python integers and floats. Exact integers must fit within ±(2**53 - 1);
+finite Python floats may use the binary64 range. Booleans are not numeric
+inputs or results. Execution preserves the actual numeric kind and does not
+coerce values to satisfy an annotation.
+
+Numeric input validation checks types and finite values. Documented physical
+ranges, such as positive lengths or a maximum temperature, are assumptions;
+declaring them in the brief does not enforce them in the API or browser.
+Test valid boundary cases and report any physical limits that remain unenforced.
+Record required range enforcement in the brief as an implementation requirement.
+
+## Supported formulas and content
+
+Supported expressions include finite numeric literals, earlier documented
+quantities, unary minus, `+`, `-`, `*`, `/`, `**`, `sqrt`, `math.pi`, `ceil`,
+`floor`, `exp`, `log`, `abs`, `min`, `max`, `round`, trigonometric functions,
+`atan2` and `hypot`. Import math functions from `math` or call them through
+`math`. Trigonometric functions use radians; declare angle units explicitly.
+`log(value)` is natural logarithm. `round` follows Python's ties-to-even
+behavior for represented binary64 values. Invalid domains and non-finite
+results fail verification.
+
+Numeric conditional expressions can use `<`, `<=`, `>`, `>=`, `==`, `!=`,
+comparison chains and `and` / `or` between comparisons. Only the chosen
+numeric branch executes. Bare numeric conditions, boolean quantities,
+`value or fallback`, iterable or keyword forms of `min` / `max` / `hypot`,
+and arbitrary Python statements are outside the supported source subset.
+Run the calculation to detect unsupported syntax; a valid Python expression
+is not necessarily a supported documented formula. This is trusted local
+authoring, not a sandbox for untrusted Python.
+
+Place literal `text(id=..., content=...)` calls beside the formulas they
+explain. Document assumptions, limits and reference clauses in the report,
+not only in comments. `figure(...)` accepts a module-relative PNG, JPEG or
+SVG path, caption and alt text. Keep the asset inside the calculation
+directory, for example `calculations/assets/section.svg`:
+
+```python
+from cso_python import figure
+
+figure(
+    id="section-diagram",
+    path="assets/section.svg",
+    media_type="image/svg+xml",
+    caption="Section dimensions and axes",
+    alt="Dimensioned section with x and y axes",
+)
+```
+
+Missing or invalid assets fail instead of silently disappearing. A
+`with document_section(id="...", title="..."):` block can group one level
+of symbols, text and figures. Nested groups, calculation calls and returns
+do not belong inside that block.
+
+## Reuse calculations
+
+Keep common `Annotated` metadata or `TypeAlias` declarations in a local
+Python module, then use the same alias for a quantity passed between
+calculations. Generate typed handles before importing another `.cso.py`
+function:
+
+```sh
+./.venv/bin/python -m cso_python bindings calculations
+./.venv/bin/python -m cso_python bindings calculations --check
+```
+
+In PowerShell 5.1 or 7, use the project's interpreter directly:
+
+<!-- docs:project-bindings:start -->
+```powershell
+$env:PYTHON = Join-Path $PWD '.venv\Scripts\python.exe'
+& $env:PYTHON -I -X utf8 -m cso_python bindings calculations
+if ($LASTEXITCODE -ne 0) { throw 'Binding generation failed.' }
+& $env:PYTHON -I -X utf8 -m cso_python bindings calculations --check
+if ($LASTEXITCODE -ne 0) { throw 'Bindings are stale.' }
+```
+<!-- docs:project-bindings:end -->
+
+For a file `calculations/geometry.cso.py` with a public function
+`rectangle`, a parent in that directory can import and call it:
+
+```python
+from _cso_bindings.geometry import rectangle
+
+first_panel = rectangle(width=width, height=first_panel_height)
+second_panel = rectangle(width=width, height=second_panel_height)
+total_area: TotalPanelArea = first_panel["area"] + second_panel["area"]
+```
+
+`TotalPanelArea` must be declared in the shared metadata module. Calls take
+named arguments. Each call adds a child section at its source location;
+documented intermediate results stay visible even if the child does not
+select them as public outputs. Forwarded quantities retain their identity,
+description, glyph and unit. Callee units must match exactly; write an
+explicit annotated conversion when needed. Equal numeric values do not make
+two quantities identical.
+
+Generate bindings from a directory containing the parent and its local
+dependencies. Source paths below it must use Python identifiers, such as
+`steel_sections/calculate.cso.py`. Imports follow those paths. The generated
+`_cso_bindings/` directory must exist at runtime; do not edit its files.
+Regenerate after changing parameters, numeric declarations, defaults,
+metadata or public output selections. Formula-only edits may leave the
+interface current. Generation validates definitions but does not execute
+formulas. A missing or stale handle will not regenerate itself.
+
+Save authored Python as UTF-8 with LF line endings. The project's `.gitattributes`
+keeps Python and stub files at LF on Git checkout. Generated bindings already
+use UTF-8/LF. Source hashes cover exact bytes, so an editor's encoding or newline
+change can invalidate a reference even when the formula is unchanged.
+
+Each distinct quantity needs distinct displayed notation. Repeated child
+calls qualify child glyphs using their call names. When a reference
+deliberately reuses a glyph in separate contexts, set a meaningful
+`notation_scope` in `symbol(...)` and explain that scope in a description or
+section title. Collisions within one scope fail.
+
+## Check the result
+
+Add each top-level runnable function to [reports.json](reports.json) with its
+ID, title, source path and function name, then restart `npm run dev`. The
+browser derives editable inputs from the Python definition and calls the
+verified local API. Recalculate with representative and boundary inputs.
+Review every input, unit, intermediate formula, explanation, figure and
+returned result in the report. Check that the displayed substitutions and
+outputs match the intended engineering method.
+
+From the project root, verify one execution and generate checked HTML with the
+project's Python interpreter. In a POSIX shell:
+
+```sh
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso verify calculations/report.cso.py \
+  --function calculate --format json
+mkdir -p output
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso html calculations/report.cso.py \
+  --function calculate --out output/report.html --check-layout --format json
+```
+
+For the unchanged rectangle starter, these PowerShell 5.1 and 7 commands verify
+width 2 and height 3, then write checked HTML and a PDF:
+
+<!-- docs:project-report:start -->
+```powershell
+$env:PYTHON = Join-Path $PWD '.venv\Scripts\python.exe'
+$cso = Join-Path $PWD 'node_modules\.bin\cso.cmd'
+$source = Join-Path $PWD 'calculations\report.cso.py'
+& $cso verify $source --function calculate --input width=2 --input height=3 --format json
+if ($LASTEXITCODE -ne 0) { throw 'Calculation verification failed.' }
+New-Item -ItemType Directory -Force (Join-Path $PWD 'output') | Out-Null
+& $cso html $source --function calculate --input width=2 --input height=3 --out (Join-Path $PWD 'output\report.html') --check-layout --format json
+if ($LASTEXITCODE -ne 0) { throw 'Checked HTML generation failed.' }
+& $cso pdf $source --function calculate --input width=2 --input height=3 --out (Join-Path $PWD 'output\report.pdf') --format json
+if ($LASTEXITCODE -ne 0) { throw 'PDF generation failed.' }
+```
+<!-- docs:project-report:end -->
+
+Use `&` when invoking an executable stored in a variable. These commands use the
+project's installed CLI and managed interpreter, including when the project
+path contains spaces. Setup installs the matching Chromium used by both report
+commands. The [reference recipe](references/README.md#bind-an-independent-case)
+shows how to save structured JSON as UTF-8 without a BOM in either PowerShell.
+
+Repeat verification with `--input name=value` for representative and boundary
+cases. Check each command's exit status and report diagnostics. Open the HTML
+and inspect its content; automated layout checks leave visual inspection pending.
+Use `npm run dev` to test browser input edits and `npm run build` to check the
+frontend. A frontend build alone does not verify the calculation.
+
+Keep three judgments separate: source-to-document consistency, agreement
+with independently established numerical cases, and human engineering
+approval. A pending reference check is not a passing reference check.
+For a bound reference file and browser registration, follow the
+[worked reference recipe](references/README.md#bind-an-independent-case).
+Formula or text edits change captured source identity and can invalidate
+reference bindings; review and explicitly rebind them while preserving
+independently established expected values. Never obtain expected values by
+copying the execution being tested.
+
+When delivering a PDF, download and inspect every page at normal size for
+missing steps, unreadable notation, clipped content and pagination. The browser
+and PDF need the same run and inputs. HTML-only work can finish with checked
+HTML and visual inspection. Report what passed, failed or was not checked;
+successful generation does not establish human engineering approval.
+See [README.md](README.md) for local setup, report registration and UI customization.

package/template/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-lyra",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "taupe",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "hugeicons",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default-translucent",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/template/gitignore

@@ -1,4 +1,5 @@
 node_modules/
+dist/
 .venv/
 __pycache__/
 _cso_bindings/

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Calculation report</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>