curriculum-project-hub/render/templates/README.md

Default export templates (ADR-0011, outline shape ADR-0036)

student.typ / teacher.typ are the framework default templates. In a real engineering file they live at exports/student.typ / exports/teacher.typ; the project-creation flow seeds copies there (out of scope here — see ADR-0011 Open Questions). They are kept here as the canonical, copyable defaults and for the offline smoke test below.

Each template:

1. reads the injected manifest: toml(sys.inputs.manifest);
2. loops manifest.outline (ADR-0036's depth-first rendering order — elements interleaved with section headings at their DFS-open position). For an type = "element" entry: include-ing each content field via a computed root-relative absolute path /<part.path>/<field>.typ, and reading scalar fields (example source) from /<part.path>/element.toml. For a type = "section" entry: passing its title/depth straight through — no content to load, it is a heading;
3. assembles an outline array of entry dicts and calls cph-render's render-lesson(...), passing the per-level heading numbering (presentation lives in the template).

Why the include loop is in the template, not in cph-render

typst resolves a dynamic include/toml path relative to the file the call lexically appears in, and a package (@local/cph-render) has its own virtual root. A dynamic include written inside the package resolves against the package dir — even an absolute /segments/x.typ — never the engineering --root. Verified empirically. The template lives under --root, so its /<part.path>/<field>.typ resolves against --root. Hence the template loads content and hands render-lesson an already-assembled outline array; render-lesson never includes anything.

Key path facts for the engine

• Template is the typst main file. Compile it directly.
• --root = engineering-file root. Content includes use absolute root-relative paths.
• Manifest is injected as a root-relative ABSOLUTE path: --input manifest=/manifest.toml. toml(sys.inputs.manifest) resolves relative to the template's location (exports/), so a bare manifest=manifest.toml would look in exports/. Pass the leading /.
• Optional content presence (lemma proof): typst has no file-exists primitive, so the template cannot probe disk. It reads a per-element fields array from the manifest listing the content fields present on disk. (OPEN: the exact manifest shape for this is for the Rust/manifest contract to pin.)
• Sections carry no content fields. A type = "section" outline entry (ADR-0036) has only kind/title/depth/path; the template passes it through untouched — no include, no element.toml read.

Offline smoke test

@local/cph-render is resolved from a local-packages dir (a symlink to the render package root — regenerable, test-only):

cd render
# one-time: make @local/cph-render resolvable offline
mkdir -p vendor/local-packages/local/cph-render
ln -sfn "$(pwd)" vendor/local-packages/local/cph-render/0.1.0

# compile a template against the smoke engineering file
typst compile --root examples/smoke-eng \
  --package-path ./vendor/local-packages \
  --package-cache-path ./vendor/typst-packages \
  --input manifest=/manifest.toml \
  examples/smoke-eng/exports/student.typ /tmp/cph-tmpl-student.pdf

(examples/smoke-eng/exports/{student,teacher}.typ are copies of the defaults here, mirroring how a real engineering file carries its own templates. The examples/smoke-eng/manifest.toml is hand-authored directly in the augmented [[outline]] shape that cph_typst::build_augmented_manifest would otherwise produce, since this smoke test bypasses the Rust engine entirely.)