Skip to content

cetz skill: correct the anchor gotcha's mechanism, and add four more - #598

Open
lmoresi wants to merge 1 commit into
developmentfrom
docs/cetz-cheatsheet-gotchas
Open

cetz skill: correct the anchor gotcha's mechanism, and add four more#598
lmoresi wants to merge 1 commit into
developmentfrom
docs/cetz-cheatsheet-gotchas

Conversation

@lmoresi

@lmoresi lmoresi commented Aug 17, 2026

Copy link
Copy Markdown
Member

All six entries cost a compile failure during the rotated-boundary-conditions figure, so they are diagnosed rather than recalled.

The existing entry had the wrong mechanism

The skill said cetz "treats anchor: specially". It does not. The cause is the import cetz.draw: * that a drawing helper needs in its own body — it runs inside the function after the parameters are bound, and shadows any parameter sharing a name with a cetz.draw export.

Isolated: the same helper without the inner import compiles fine. That is what identifies the import rather than the parameter name.

This matters because it converts a one-name warning into a rule. A parameter named fill fails the same way, with an error that is much harder to read:

error: expected color, gradient, tiling, or none, found function
  ┌─ @preview/cetz:0.3.4/src/canvas.typ:145:16

— reported inside cetz's own source, nowhere near the helper. And it gives the second fix: if the helper does not actually draw, drop the inner import instead of renaming.

Four new entries

  • let h(x) = ... shadows Typst's h(). A figure defining a surface height as h(x) breaks every #h(0.4em) used for spacing in a label, failing with "cannot add length and float" — an error naming neither the function nor the label.
  • A multi-line expression in a let ends at the first newline unless parenthesised, reported as unknown variable: x, which sends you looking at the wrong line.
  • content() anchored "west" centres a multi-line block vertically, so a caption that wraps grows upwards into the heading above it. Nothing errors — it only shows up in the PNG.
  • Joining nodes by a distance threshold is not a triangulation. It silently omits nodes near the domain edge and in sparse regions, and the result looks almost right. Plus the two follow-ons on a geophysical domain: Delaunay fills the convex hull, so a domain under topography needs triangles culled by centroid; and a perfect lattice produces degenerate slivers, so stagger alternate rows.

Documentation only — no code paths touched.

Underworld development team with AI support from Claude Code

The skill said cetz 'treats anchor: specially'. It does not. The cause is the
import cetz.draw: * that a drawing helper needs in its own body: it runs inside
the function after the parameters are bound and shadows any parameter sharing a
name with a cetz.draw export. Isolated by removing the inner import from an
otherwise identical helper, which compiles.

That turns a one-name warning into a rule, and covers fill and stroke as well —
a parameter named fill fails with 'expected color, gradient, tiling, or none,
found function' reported inside cetz's canvas.typ, nowhere near the helper.

Four more, each one compile failure during the rotated-BC figure:

- let h(x) shadows Typst's horizontal-spacing h(), so a figure defining a
  surface height breaks every #h(0.4em) in a label, with an error naming
  neither;
- a multi-line arithmetic expression in a let ends at the first newline unless
  parenthesised, reported as 'unknown variable: x';
- content() anchored west centres a multi-line block vertically, so a caption
  that wraps grows upwards into the heading above it — nothing errors, it just
  overlaps;
- joining nodes by a distance threshold is not a triangulation and silently
  omits nodes, plus the two follow-ons for a non-convex domain: Delaunay fills
  the convex hull so cull by centroid, and a perfect lattice gives degenerate
  triangles so stagger the rows.

Underworld development team with AI support from Claude Code
Copilot AI lite review requested due to automatic review settings August 17, 2026 09:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants