Cheatsheet

A one-page index. Each row names the chapter that teaches it — this page is a map, not a tutorial.

The five built-in placeholders (3 The Built-in Placeholders)

Keyword	Widget	Role	Folds back as
`ppVar`	column picker (data-aware)	consumer	a column symbol
`ppText`	text input	value	a string
`ppNum`	numeric input	value	a number
`ppExpr`	code box (validated, 18 Writing Safe Formulas)	value	a parsed expression
`ppUpload`	file picker + dataset-name box	source	a data frame

Seeding: one positional argument is the boot value — ppVar("wt"), ppNum(3), ppExpr(mpg > 15) (2 Getting Started). Read literally, never evaluated.

Structural keywords (4 The Formula Language)

Form	Effect
`ppLayerOff(layer_expr, hide)`	`hide = TRUE` boots the layer unchecked; legal plain R too.
`ppVerbSwitch(.data, verb_expr, switch_on, label)`	Toggleable pipeline stage; `switch_on = FALSE` boots it disabled. First-position-data verbs only.
`keyword(shared = "<key>")`	One widget drives every occurrence of the key (11 Shared Placeholders).
`spec = list(<widget_id> = <value>)`	Per-run boot override, wins over formula-side defaults.

Entry points by level (1 Introduction)

Level	Call	Chapter
L1	`ptr_app(formula, envir, ui_text, expr_check, safe_to_remove, css, spec)`	1 Introduction
L2	`ptr_ui(formula, id)` + `ptr_server(formula, id)`	9 Embedding with the Default Layout, 10 Multi-Plot Apps
L2 (linked plots)	`ptr_shared(formulas)` → `ptr_shared_panel(obj)` + `ptr_shared_server(obj)` → `ptr_server(..., shared_state = )`	11 Shared Placeholders
L3 (bare pieces)	`ptr_ui_page()`, `ptr_ui_header()`, `ptr_ui_controls()`, `ptr_ui_plot()`, `ptr_ui_error()`, `ptr_ui_code()`, `ptr_ui_shared_panel()`, `ptr_ui_assets()`	12 Embedding with Bare Pieces
L3 (combinators)	`ptr_ui_inline_error(plot, error)`, `ptr_ui_toggle_code(plotish, code)`	12 Embedding with Bare Pieces

Reading a running app’s state (13 Custom Rendering)

Context	Call
Inside `renderX({...})`	`state$runtime()` → `$ok`, `$plot`, `$code_text`, `$error`
Outside reactive contexts	`ptr_extract_plot(state)`, `ptr_extract_code(state)`, `ptr_extract_error(state)`
Inject layers programmatically	`ptr_gg_extra(state, ...)`

state is the return value of ptr_server().

Extending (6 Your First Custom Placeholder)

Constructor	Role
`ptr_define_placeholder_value()`	self-contained value
`ptr_define_placeholder_consumer()`	needs upstream columns (`build_ui` gains `cols`, `data`)
`ptr_define_placeholder_source()`	produces the data (`resolve_data` required; `shortcut = TRUE` for the name box)

Argument validators: ptr_arg_string(), ptr_arg_numeric(), ptr_arg_symbol(), ptr_arg_symbol_or_string(), ptr_arg_expression() — all but ptr_arg_expression() (which takes no arguments) accept vector = TRUE; ptr_arg_numeric() also takes length =. Plain-R meaning helpers: embellish_identity(), embellish_symbol_to_string(). Housekeeping: ptr_clear_placeholder().

Customizing (15 Customization, 17 UI Text and Copy, 16 Theming and Wrappers)

Surface	Call
Copy / labels	`ptr_ui_text(list(shell = , upload = , layer_checkbox = , defaults = , params = , layers = ))`
Low-level copy lookup	`ptr_resolve_ui_text()`
Stylesheet injection	`css =` on `ptr_app()` / `ptr_ui()` / `ptr_shared_panel()` / `ptr_ui_page()`; escape hatch `ptr_ui_assets(css)`
Package options	`ptr_options()`

Safety knobs (18 Writing Safe Formulas)

expr_check = TRUE (curated denylist + AST walker, the default) / FALSE (never on a shared app) / list(allow_list = ) (strict allowlist — only the listed call heads pass; the curated floor for bare names stays active) / list(deny_list = ) (replaces the curated list).

LLM helpers (19 Using ggpaintr from an LLM)

ptr_llm_primer() (system prompt), ptr_llm_register(chat) (the ggpaintr_docs tool), ptr_llm_topics() / ptr_llm_topic(topic) (inspect the payloads).

Utilities

ptr_normalize_column_names(data) — make local data ppVar-safe (2 Getting Started). ptr_extract_code(state) — the script behind the code window (5 The Generated Code and Plot).