feat(render): export templates + render-lesson entry; template owns include loop (WU-C', ADR-0011)

Replace the display(parts) entry (which a generated driver called) with the template model: real editable templates (render/templates/{student,teacher}.typ, the framework defaults copied into an engineering file's exports/) read the manifest via toml(sys.inputs.manifest) and assemble parts themselves. Key finding (drives the engine): a dynamic `include` inside a package resolves against the PACKAGE root, never --root — so the include loop must live in the TEMPLATE (which sits under --root): `include "/" + part.path + "/" + field + ".typ"` (root-relative absolute, runtime-computed — legal per ADR-0011's verified fact). cph-render exposes render-lesson(info, target, parts, heading-numbering) (content-in, never includes) + part-fields (kind→fields) + default-heading-numbering. Numbering (numbly per-level) is set in the template, editable per engineering file. Surfaced OPEN point closed by the engine (WU-D'): typst has no file-exists primitive, so optional content (lemma proof) presence comes from a per-part `fields` array the engine computes from disk. Manifest injected as root-relative absolute (--input manifest=/...). numbly stays vendored/offline. display removed. local-packages symlink (test-only @local resolution) gitignored — regenerable, self-referential; the embedded engine mounts cph-render directly. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-22 09:57:51 +08:00
parent d5bce1bede
commit 7e15cf34f6
27 changed files with 506 additions and 137 deletions
@@ -0,0 +1,63 @@
+# Default export templates (ADR-0011)
+
+`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.parts`, `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`;
+3. assembles a `parts` array 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 `parts` 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 `include`s 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-part `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.)*
+
+## Offline smoke test
+
+`@local/cph-render` is resolved from a local-packages dir (a symlink to the
+render package root — regenerable, test-only):
+
+```sh
+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.)
@@ -0,0 +1,79 @@
+// DEFAULT STUDENT TEMPLATE (framework default; ADR-0011).
+//
+// This is a *real, editable* file that lives in an engineering file at
+// `exports/student.typ`. The framework compiles it AS THE MAIN FILE with the
+// manifest injected:
+//   typst compile --root <eng-root> --input manifest=<path-rel-to-root> exports/student.typ <out>
+//
+// It is intentionally self-contained (no shared helper import) so it can be
+// copied verbatim into a new engineering file's `exports/`. Presentation —
+// heading numbering — lives HERE (editable per engineering file), not in the
+// manifest and not hardcoded in the cph-render package.
+//
+// WHY THE INCLUDE LOOP IS HERE AND NOT IN cph-render: typst resolves a dynamic
+// `include` path relative to the file it lexically appears in, and a package has
+// its own virtual root — an include inside cph-render would resolve against the
+// PACKAGE, not the engineering root. A `/<part.path>/<field>.typ` written HERE
+// (this template lives under `--root`) resolves against `--root`. So the
+// template loads content and hands cph-render an already-assembled `parts` array.
+//
+// OPEN CONTRACT POINT — optional-content presence. typst has no "does this file
+// exist" primitive (a missing `include` is a hard compile error). So the
+// template CANNOT probe disk the way the old Rust driver did for lemma `proof`.
+// It relies on the manifest declaring which optional content fields are present,
+// via a per-part `fields` array listing the content fields that exist on disk
+// (the engine knows this — it walks the part dir). Required fields are loaded
+// unconditionally; optional fields load only if listed in `fields`. If a part
+// omits `fields`, optional content is skipped (conservative). The exact shape of
+// this declaration is for the manifest/Rust contract to pin.
+
+#import "@local/cph-render:0.1.0": render-lesson, part-fields, default-heading-numbering
+
+// This template IS the student build, so the target is fixed.
+#let target = "student"
+
+// Read the injected manifest (a path string relative to typst --root).
+#let manifest = toml(sys.inputs.manifest)
+#let info = manifest.at("info", default: (:))
+#let raw-parts = manifest.at("parts", default: ())
+
+// Assemble each part: include its content fields (computed absolute paths,
+// resolved against --root) and read scalar fields from <path>/element.toml.
+// `part-fields` (from cph-render) is the single source of truth for kind->fields.
+#let parts = raw-parts.map(raw => {
+  let kind = raw.at("kind", default: none)
+  let path = raw.at("path", default: none)
+  let spec = part-fields.at(kind, default: (content: (), optional-content: (), scalars: ()))
+  // Which optional content fields are present on disk (manifest-declared).
+  let present = raw.at("fields", default: ())
+  let part = (kind: kind)
+
+  // Required content fields: <path>/<field>.typ (absolute, root-relative).
+  for field in spec.content {
+    part.insert(field, include "/" + path + "/" + field + ".typ")
+  }
+  // Optional content fields: only when the manifest says the file exists.
+  for field in spec.optional-content {
+    if field in present {
+      part.insert(field, include "/" + path + "/" + field + ".typ")
+    }
+  }
+  // Scalar fields come from <path>/element.toml.
+  if spec.scalars.len() > 0 {
+    let element = toml("/" + path + "/element.toml")
+    for field in spec.scalars {
+      let v = element.at(field, default: none)
+      if v != none and v != "" { part.insert(field, v) }
+    }
+  }
+  part
+})
+
+// Presentation: per-level heading numbering. Default (一、 / 1.1 / 1.1.1) comes
+// from cph-render; override here per engineering file if desired.
+#render-lesson(
+  info: info,
+  target: target,
+  parts: parts,
+  heading-numbering: default-heading-numbering,
+)
@@ -0,0 +1,62 @@
+// DEFAULT TEACHER TEMPLATE (framework default; ADR-0011).
+//
+// Lives in an engineering file at `exports/teacher.typ`. Compiled AS MAIN with
+// the manifest injected:
+//   typst compile --root <eng-root> --input manifest=<path-rel-to-root> exports/teacher.typ <out>
+//
+// Self-contained (copyable into an engineering file). Identical to student.typ
+// except the fixed target is "teacher" (so the (kind x target) render matrix in
+// cph-render shows solutions and proofs). See student.typ for the full notes on
+// why the include loop lives here (package virtual-root resolution) and on the
+// OPEN optional-content (`fields`) contract point.
+
+#import "@local/cph-render:0.1.0": render-lesson, part-fields, default-heading-numbering
+
+// This template IS the teacher build, so the target is fixed.
+#let target = "teacher"
+
+// Read the injected manifest (a path string relative to typst --root).
+#let manifest = toml(sys.inputs.manifest)
+#let info = manifest.at("info", default: (:))
+#let raw-parts = manifest.at("parts", default: ())
+
+// Assemble each part: include its content fields (computed absolute paths,
+// resolved against --root) and read scalar fields from <path>/element.toml.
+// `part-fields` (from cph-render) is the single source of truth for kind->fields.
+#let parts = raw-parts.map(raw => {
+  let kind = raw.at("kind", default: none)
+  let path = raw.at("path", default: none)
+  let spec = part-fields.at(kind, default: (content: (), optional-content: (), scalars: ()))
+  // Which optional content fields are present on disk (manifest-declared).
+  let present = raw.at("fields", default: ())
+  let part = (kind: kind)
+
+  // Required content fields: <path>/<field>.typ (absolute, root-relative).
+  for field in spec.content {
+    part.insert(field, include "/" + path + "/" + field + ".typ")
+  }
+  // Optional content fields: only when the manifest says the file exists.
+  for field in spec.optional-content {
+    if field in present {
+      part.insert(field, include "/" + path + "/" + field + ".typ")
+    }
+  }
+  // Scalar fields come from <path>/element.toml.
+  if spec.scalars.len() > 0 {
+    let element = toml("/" + path + "/element.toml")
+    for field in spec.scalars {
+      let v = element.at(field, default: none)
+      if v != none and v != "" { part.insert(field, v) }
+    }
+  }
+  part
+})
+
+// Presentation: per-level heading numbering. Default (一、 / 1.1 / 1.1.1) comes
+// from cph-render; override here per engineering file if desired.
+#render-lesson(
+  info: info,
+  target: target,
+  parts: parts,
+  heading-numbering: default-heading-numbering,
+)