Skip to content

docs(reference): align meme section with implementation#2

Merged
jona62 merged 1 commit intojona62:mainfrom
mac-studio-meme:docs-align-with-implementation
Apr 19, 2026
Merged

docs(reference): align meme section with implementation#2
jona62 merged 1 commit intojona62:mainfrom
mac-studio-meme:docs-align-with-implementation

Conversation

@jona62
Copy link
Copy Markdown
Owner

@jona62 jona62 commented Apr 19, 2026

Walking the reference section end-to-end against the built runtime turned up several documented features that either don't exist or crash when invoked as shown. This commit corrects the inaccurate claims and adds features that are implemented but undocumented.

Fiction removed:

  • docs/reference/src/meme/styles.md previously listed 'built-in style keywords' (impact, cinematic, shout, whisper, panic). None of these exist in the codebase; the parser rejects them. Replaced with an accurate inline-style section that also documents the dimensions-required rule for block form.
  • docs/reference/src/meme/effects.md called blur 'Gaussian' but the implementation is a box blur.
  • docs/reference/src/meme/effects.md advertised tint(hexColor) taking a string; the implementation requires a numeric parameter, hardcodes alpha at 0.5, and has no 0x-literal syntax to pass a hex int. Replaced the row with a warning note until the effect is fixed.
  • docs/reference/src/meme/gif.md listed 'bounce' as an easing option, and CLAUDE.md also listed it. The parser accepts it but MacTimeline::applyEasing silently falls through to linear. Removed from both places until wired up.
  • docs/reference/src/meme/gif.md's day/night example piped through tint("#000044AA") which aborts the interpreter. Replaced with vignette |> brightness(0.5).
  • docs/reference/src/meme/gif.md's animate example used animate(frames, 500) which aborts with std::bad_variant_access (AnimateFunction expects a Duration instance). Corrected to animate(frames, Duration(500)) and expanded into a proper 'Programmatic GIFs' section with a reduce(Gif()) alternative for per-frame durations.
  • CLAUDE.md stated the GIF frame cap was 200 in two places. The actual cap (GifLimits.h MAX_GIF_FRAMES) is 500. Corrected.

Features added to the reference:

  • docs/reference/src/meme/meme_literal.md expanded the 'With Positioned Text' section to show multiple entries, fontSize with numeric and tier forms, and the shared-style caveat.
  • docs/reference/src/meme/meme_literal.md added a new 'Meme Assets' section listing all nine @meme. assets. Previously undocumented.
  • docs/reference/src/meme/grid.md added 'Spread from an Array' covering 'grid 2x2 { ...arr }' and bare 'grid arr' forms.
  • docs/reference/src/meme/grid.md added 'Programmatic Composition' covering beside(a, b), stack(a, b), and toGrid(arr, cols, rows) -- all previously undocumented despite being in the public registry.
  • docs/reference/src/meme/gif.md added an 'Operational Limits' section documenting the 500-frame cap, the 15 fps internal transition rate (so agents stop using 200ms transitions and wondering why they look stepped), and the 4096x4096 dimension clamp.

All code examples in the changed docs were run end-to-end against the built interpreter. No runtime code changed; all 91 existing tests pass. Relative links within meme/*.md were checked and resolve cleanly.

Walking the reference section end-to-end against the built runtime
turned up several documented features that either don't exist or crash
when invoked as shown. This commit corrects the inaccurate claims and
adds features that are implemented but undocumented.

Fiction removed:
- docs/reference/src/meme/styles.md previously listed 'built-in style
  keywords' (impact, cinematic, shout, whisper, panic). None of these
  exist in the codebase; the parser rejects them. Replaced with an
  accurate inline-style section that also documents the
  dimensions-required rule for block form.
- docs/reference/src/meme/effects.md called blur 'Gaussian' but the
  implementation is a box blur.
- docs/reference/src/meme/effects.md advertised tint(hexColor) taking
  a string; the implementation requires a numeric parameter, hardcodes
  alpha at 0.5, and has no 0x-literal syntax to pass a hex int.
  Replaced the row with a warning note until the effect is fixed.
- docs/reference/src/meme/gif.md listed 'bounce' as an easing option,
  and CLAUDE.md also listed it. The parser accepts it but
  MacTimeline::applyEasing silently falls through to linear. Removed
  from both places until wired up.
- docs/reference/src/meme/gif.md's day/night example piped through
  tint("#000044AA") which aborts the interpreter. Replaced with
  vignette |> brightness(0.5).
- docs/reference/src/meme/gif.md's animate example used
  animate(frames, 500) which aborts with std::bad_variant_access
  (AnimateFunction expects a Duration instance). Corrected to
  animate(frames, Duration(500)) and expanded into a proper
  'Programmatic GIFs' section with a reduce(Gif()) alternative for
  per-frame durations.
- CLAUDE.md stated the GIF frame cap was 200 in two places. The actual
  cap (GifLimits.h MAX_GIF_FRAMES) is 500. Corrected.

Features added to the reference:
- docs/reference/src/meme/meme_literal.md expanded the 'With Positioned
  Text' section to show multiple entries, fontSize with numeric and
  tier forms, and the shared-style caveat.
- docs/reference/src/meme/meme_literal.md added a new 'Meme Assets'
  section listing all nine @meme.<name> assets. Previously undocumented.
- docs/reference/src/meme/grid.md added 'Spread from an Array' covering
  'grid 2x2 { ...arr }' and bare 'grid arr' forms.
- docs/reference/src/meme/grid.md added 'Programmatic Composition'
  covering beside(a, b), stack(a, b), and toGrid(arr, cols, rows) --
  all previously undocumented despite being in the public registry.
- docs/reference/src/meme/gif.md added an 'Operational Limits' section
  documenting the 500-frame cap, the 15 fps internal transition rate
  (so agents stop using 200ms transitions and wondering why they look
  stepped), and the 4096x4096 dimension clamp.

All code examples in the changed docs were run end-to-end against the
built interpreter. No runtime code changed; all 91 existing tests pass.
Relative links within meme/*.md were checked and resolve cleanly.
@jona62 jona62 merged commit e45d1f6 into jona62:main Apr 19, 2026
7 checks passed
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.

1 participant