% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paintr-server.R
\name{ptr_init_state}
\alias{ptr_init_state}
\title{Construct the ggpaintr runtime state container}
\usage{
ptr_init_state(
  formula,
  envir = parent.frame(),
  ui_text = NULL,
  expr_check = TRUE,
  safe_to_remove = character(),
  shared = list(),
  draw_trigger = NULL,
  producer_debounce_ms = NULL,
  ns = shiny::NS(NULL),
  server_ns = ns,
  auto_bind_shared = FALSE,
  shared_resolutions = list(),
  shared_stage_enabled = list(),
  panel_sources = list(),
  plots = NULL
)
}
\arguments{
\item{formula}{A single formula string with \code{ggpaintr} placeholders.}

\item{envir}{Environment used to resolve local data objects.}

\item{ui_text}{Optional named list of copy overrides; see \code{\link[=ptr_ui_text]{ptr_ui_text()}}
for the full schema and current defaults.}

\item{expr_check}{Controls formula-level \code{ppExpr} validation: \code{TRUE}
(default) applies the built-in denylist + AST walker; \code{FALSE} disables
formula-level validation; a \code{list} with \code{deny_list}/\code{allow_list} entries
customises the formula-level policy. Runtime-typed \code{ppExpr} input is
always screened against the built-in denylist regardless. See the
safety chapter of the ggpaintr book (development-version docs):
\url{https://willju-wangqian.github.io/ggpaintr-book/safety.html}.}

\item{safe_to_remove}{Character vector of additional function names whose
zero-argument calls should be dropped after substitution.}

\item{shared}{Named list of reactives (one per shared key) supplied by an
outer wrapper such as \code{\link[=ptr_app_grid]{ptr_app_grid()}}. Defaults to \code{list()}.}

\item{draw_trigger}{Optional reactive carrying a click counter — a numeric
scalar that is \verb{>= 1} once its button has been clicked (e.g. the grid
app's "Draw all" \code{input$...} value). A redraw fires only when the
carried value looks clicked; a reactive carrying any other value (a
data frame, a timestamp) invalidates the runtime observer but never
triggers a draw. To redraw on arbitrary reactive changes (e.g. a
reactive pipeline head in the formula), use \code{ptr_options(gate_draw = FALSE)} live mode instead. Defaults to \code{NULL}.}

\item{producer_debounce_ms}{Optional. Controls the debounce window applied
to producer-style placeholder inputs (\code{ppText}, \code{ppNum}, \code{ppExpr}) before they
invalidate downstream consumer caches. \code{NULL} (default) enables auto
mode: window starts at 0 ms and the runtime flips to 300 ms after three
consecutive upstream resolutions exceed 150 ms (and back to 0 after five
consecutive resolutions under 80 ms). Pass \code{0} to force off forever, or a
positive integer to pin a manual window.}

\item{ns}{A namespace function used for rendered ids (UI side).}

\item{server_ns}{A namespace function used for server-side input lookups.
Defaults to \code{ns}.}

\item{auto_bind_shared}{If \code{TRUE}, the host (single-plot \code{ptr_app()}
or \code{ptr_app_grid()} auto-render path) binds shared widgets at host
scope. Relaxes the "missing-from-bindings" check in
\code{ptr_validate_shared_bindings()} (the host auto-binds instead).}

\item{shared_resolutions}{Named list (keyed by raw shared key) of
host-computed resolutions for shared data-consumer (\code{ppVar}) widgets,
as returned by \code{ptr_resolve_shared_consumers()}. When an entry is
present, the runtime validates that key's selection against the
host-resolved upstream (the same data the host picker was built
from) instead of the per-layer \code{node$upstream}, so a value valid in
the host picker is never rejected by one layer's narrower upstream.
Defaults to \code{list()} (no host resolutions; per-layer behaviour).}

\item{shared_stage_enabled}{Named list (keyed by raw shared key) of
reactives, each returning a logical, that toggle the orphan pipeline
stages owned by that shared key (as carried in a
\code{\link[=ptr_shared_server]{ptr_shared_server()}} bundle). A missing or unset entry leaves the
stage enabled. Defaults to \code{list()}.}

\item{panel_sources}{Named list (keyed by source-node id) of reactives,
each returning the host-loaded data for a panel-owned shared source
(ADR 0023). Populated by the host's \code{ptr_setup_panel_sources()} and
threaded through a \code{\link[=ptr_shared_server]{ptr_shared_server()}} bundle so per-instance binders
read the host's primed data (\code{state$panel_sources[[node$id]]}) instead
of re-wiring their own source UI. Defaults to \code{list()} (single-plot /
per-instance context — no panel-owned sources).}

\item{plots}{Optional list of formula strings for grid contexts. When
supplied (typically by \code{\link[=ptr_app_grid]{ptr_app_grid()}}), the validator for \code{shared}
bindings cross-checks shared-key references against every plot's
placeholder set, so a \code{shared = "..."} annotation that exists in
plot 2 but not plot 1 still validates. Defaults to \code{NULL} (single-
plot context — only \code{formula} is checked).}
}
\value{
A \code{ptr_state} list (S3 class \code{c("ptr_state", "list")}).
}
\description{
Builds the \code{ptr_state} object — the translated typed AST (as a
\code{reactiveVal}), the runtime result, the per-layer resolved-data caches,
the eval environment, the input-snapshot machinery, and the shared
bindings / draw trigger — used by \code{\link[=ptr_server]{ptr_server()}} and the advanced-embedder
accessors (\code{\link[=ptr_extract_plot]{ptr_extract_plot()}} / \code{\link[=ptr_extract_error]{ptr_extract_error()}} /
\code{\link[=ptr_extract_code]{ptr_extract_code()}}, \code{\link[=ptr_gg_extra]{ptr_gg_extra()}}).
}
\details{
This is a \emph{state container}, not a from-scratch reactive-app builder: it
allocates the reactives but does not attach the pipeline / runtime
observers (those live in internal \verb{ptr_setup_*} helpers wired by
\code{\link[=ptr_server]{ptr_server()}}). Reach for \code{ptr_init_state()} directly when you want to
drive the typed tree programmatically or exercise ggpaintr under
\code{\link[shiny:testServer]{shiny::testServer()}}; for a fully wired app use \code{\link[=ptr_server]{ptr_server()}}.
}
\examples{
shiny::isolate({
  state <- ptr_init_state(
    "ggplot(mtcars, aes(x = ppVar, y = ppVar)) + geom_point()"
  )
  is.list(state)
})
}
