# render.R — HTML rendering and display

# ── Internal: locate and read the bundled JS ───────────────────────────────────

.bundle_js <- function() {

  # Inlined into a page, the relative source-map URL would resolve against the

  # page and 404; the map is only served with the file-based dependency.

}

# ── Internal: accept either a raw rENA set, a pre-extracted ModelData list,

#             or a qe_plot object ────────────────────────────────────────────

#

# • ena.set objects  → qe_extract() with any forwarded args

# • qe_plot objects  → return the model slot directly

# • anything else    → assumed to be a ModelData list already

.to_model <- function(x, ...) {

}

# ── Internal: resolve graph_opts from a qe_plot object or plain list ──────────

# When x is a qe_plot, its stored opts are used as the base; the caller can

# still pass graph_opts to override individual keys.

.resolve_opts <- function(x, graph_opts = list()) {

}

# ── Internal: resolve title ───────────────────────────────────────────────────

.resolve_title <- function(x, title) {

}

# ── Internal: build the <qe-graph> element with child layer elements ──────────

#

# Each declarative child element maps directly to a rendering layer:

#   <qe-nodes>  — code nodes (emitted with an edge network, or via qe_nodes())

#   <qe-means>  — group mean markers + CI boxes  (omit to hide)

#   <qe-points> — unit scatter dots              (omit to hide)

#   <qe-edges>  — edge network                   (omit to hide)

#   <qe-trajectories> — ordered unit paths       (omit to hide)

#

# Presence of a child = the layer renders.

# Absence            = the layer is hidden.

# DOM order          = SVG render order (later children draw on top).

.build_graph_element <- function(opts) {

  # <qe-nodes> is emitted after <qe-edges> is decided (see .nodes_element()),

  # but placed first so DOM order is unchanged.

  # ── <qe-means> — show group means + optional CI boxes ────────────────────

  # Present by default so `qe_plot(set)` shows group means; omitted after

  # qe_group(show = FALSE).

  # ── <qe-points> — unit scatter dots (only when points = TRUE) ────────────

  }

  # Explicit point sets (qe_points(units =, points =)).

  }

  # ── <qe-edges> — edge network (omit when no primary target or suppressed) ─

  # Emitted only when at least one of group/unit is set (or compare/also are,

  # though those require a primary).  The R chain functions validate this.

    # Layer attributes (0.5): colors / threshold / name for the named network,

    # then one <qe-edges network="…"> per explicit layer.

    # Plot-wide settings ride on the first layer.

    }

    # Edge sizing (qe_edges(fixed_size =, self_size =)) applies to every layer.

    }

  }

  # ── <qe-trajectories> — ordered unit trajectories ───────────────────────

    )

    )

  }

  # ── <qe-axes> — axis lines + optional per-axis labels ───────────────────

    # TRUE → boolean attribute (label defaults to dimension name);

    # a string → attribute with that value; FALSE/NULL → no attribute.

  }

  # ── <qe-nodes> — draw code nodes (positions always come from the model) ──

  # "auto" draws them only with an edge network, as rENA does.

  }

  # Plot-wide attributes on <qe-graph> (values HTML-escaped).

}

# ── Internal: build the full HTML document string ─────────────────────────────

.build_html <- function(model_json, title = "qeviz", graph_opts = list()) {

}

# ── NULL-coalescing helper ─────────────────────────────────────────────────────

# ══ qe_plot object ════════════════════════════════════════════════════════════

#' Create a qeviz plot object

#'

#' Returns a `qe_plot` object that can be customised with chained `qe_*()`

#' functions and rendered by printing, [qe_export_html()], or [qe_html()].

#'

#' `width` and `height` set the plot dimensions and can be supplied here rather

#' than in a separate sizing call.

#'

#' @param x       Either a raw rENA / tma / ona set object **or** a `ModelData`

#'   list from [qe_model_data()] / [qe_extract()].

#' @param title   Plot title. When given it is drawn at the top of the plot

#'   (and included in SVG / PNG exports) and used as the page title; when

#'   `NULL` (default) nothing is drawn and the page title is "qeviz".

#' @param width   CSS width string. Default `"100%"`.

#' @param height  Plot height in pixels (numeric) or any CSS string. Default `440`.

#' @param range   Symmetric axis range, as rENA's `scale.to`: `"network"`

#'   (±max |node| × 1.2), `"points"` (±max |point| × 1.2) or a positive number.

#'   `NULL` (default) uses qeviz's fit (1.3 × the largest mark). Asymmetric

#'   ranges (rENA's `list(x =, y =)`) are not supported.

#' @param scale_points Rescale unit points and means so the outermost point

#'   meets the outermost code node (default `TRUE`); `FALSE` plots raw

#'   coordinates, as rENA does.

#' @param point_scale Multiply unit points and means by this factor instead

#'   (a positive number), overriding `scale_points`. `NULL` (default) keeps

#'   `scale_points`' behaviour. E.g. `1` for raw coordinates, or a factor

#'   matching another tool's plot.

#' @param center Where the view is centred: `"origin"` (default; (0, 0), the

#'   ENA convention, where the points' mean sits) or `"content"`, the middle of

#'   the nodes' and points' bounding box, so a network that sits off to one side

#'   of the origin fills the plot. With `"content"`, `range = "network"` is

#'   measured from that centre.

#' @param palette Group colours, assigned in order of appearance. Default:

#'   Paul Tol's colour-blind-safe "bright" scheme. See also [qe_colors()].

#' @param view_padding How far the view extends beyond `range`: the view shows

#'   ±range × `view_padding`. `NULL` (default) uses qeviz's 1.2; `1` makes the

#'   view match the range exactly, e.g. to frame the plot yourself.

#' @param ...     Additional arguments forwarded to [qe_extract()] when `x` is a

#'   raw set (e.g. `group_col = "Condition"`, `dims = c("SVD1", "SVD3")`).

#'   Directionality is detected automatically from the set class.

#'

#' @return An object of class `qe_plot`.

#'

#' @examples

#' \dontrun{

#' qe_plot(set)

#' qe_plot(set, height = 600) |> qe_group("FirstGame")

#' }

#'

#' @export

qe_plot <- function(x, title = NULL, width = "100%", height = 440,

                    range = NULL, scale_points = TRUE, point_scale = NULL,

                    center = c("origin", "content"), palette = NULL,

                    view_padding = NULL, ...) {

    ),

  )

}

#' Set group colours

#'

#' Pins groups to colours; each group's mean, unit points and networks use

#' it. Unlisted groups keep the palette colour.

#'

#' @param p   A `qe_plot` object.

#' @param ... Named colours: `FirstGame = "#E69F00"`, …

#' @return The modified `qe_plot` object.

#' @examples

#' \dontrun{

#' qe_plot(set) |> qe_colors(FirstGame = "#E69F00", SecondGame = "#56B4E9") |>

#'   qe_edges("FirstGame", compare = "SecondGame")

#' }

#' @export

qe_colors <- function(p, ...) {

}

# ══ Chain functions ════════════════════════════════════════════════════════════

#' Select which group means to display

#'

#' Controls which groups' mean markers and CI boxes appear in the plot.  This

#' is independent of edge rendering — use [qe_edges()] to select whose network

#' to draw.

#'

#' @param p         A `qe_plot` object.

#' @param ...       Group names to show means for.  Supply one or more strings,

#'   each matching a value in the model's group column.  Omit entirely to show

#'   means for **all** groups in the model (the default).

#' @param points    An arbitrary subset to average — a matrix, data frame or

#'   `ena.points` rows (as rENA's `ena.plot.group()` accepts). Its mean, t CI

#'   and (with `outlier`) fences are computed here and added as a group named

#'   `label`. Cannot be combined with group names.

#' @param label     Name for an explicit mean. Default `"mean 1"`, `"mean 2"`, ….

#' @param color     Colour of an explicit mean. Default: next palette colour.

#' @param shape     Marker shape for an explicit mean: `"square"` (default),

#'   `"circle"`, `"triangle"` or `"diamond"`.

#' @param by        The metadata column used for grouping (e.g. `"Condition"`).

#'   Optional — used to validate against the column baked into the model at

#'   extraction time.  An error is raised if the column name does not match.

#' @param intervals `"box"` (default), `"crosshairs"`, `"both"` (the box with

#'   the crosshairs through the mean) or `"none"`; `TRUE` /

#'   `FALSE` are accepted as `"box"` / `"none"`. rENA's default is `"none"`.

#' @param conf_level Confidence level of the t interval. Default 0.95.

#' @param outlier   Also draw the outlier interval (Q1 − 1.5·IQR … Q3 + 1.5·IQR

#'   per dimension). Default `FALSE`.

#' @param show      `FALSE` hides all group means (as rENA draws none unless

#'   asked). A later `qe_group()` call shows them again.

#' @param fixed_size Logical. When `TRUE`, group mean markers keep a constant

#'   on-screen pixel size regardless of data extent, container size, or zoom.

#'   Default `FALSE` (markers scale with the coordinate space).

#'

#' @return The modified `qe_plot` object.

#'

#' @examples

#' \dontrun{

#' # Show means for all groups (default)

#' qe_plot(set) |> qe_group()

#'

#' # Show means for specific groups only

#' qe_plot(set) |> qe_group("FirstGame", "SecondGame")

#'

#' # Explicit column name — validates against model

#' qe_plot(set) |> qe_group("FirstGame", by = "Condition")

#' }

#'

#' @export

qe_group <- function(p, ..., points = NULL, label = NULL, color = NULL, shape = NULL,

                     by = NULL, intervals = c("box", "crosshairs", "both", "none"),

                     conf_level = 0.95, outlier = FALSE, fixed_size = FALSE,

                     show = TRUE) {

  }

  # Validate `by` against the model's group_col

    }

  }

    # ── Explicit: the mean (+ t CI, outlier fences) of an arbitrary subset ───

    # Each explicit mean keeps its own intervals / outlier setting (rENA sets

    # them per ena.plot.group() call); they override the plot-wide ones.

  } else {

    # ── By name ─────────────────────────────────────────────────────────────

      }

    }

    # Non-default CI level / outlier fences: recompute the named groups' rows

    # from the unit points (explicit rows keep what they were computed with).

    }

  }

  # `groups` filter: named selection (all / some) plus explicit means. With

  # only explicit means, show just those (as rENA's ena.plot.group does).

}

#' Select which edge network to draw

#'

#' Controls edge rendering.  A network is chosen **by name** — a group

#' (`group`) or a unit (`unit`), optionally with `compare` / `also` — or given

#' **as data** with `weights` (any vector, matrix or data frame, as rENA's

#' `ena.plot.network()` accepts).  Name calls replace the plot's named network;

#' `weights` calls add a layer, so repeated calls overlay.  `qe_edges(show =

#' FALSE)` clears every network.

#'

#' Use [qe_units()] to inspect the unit IDs present in the model.

#'

#' @param p       A `qe_plot` object.

#' @param group   Name of the primary group whose **mean** edge network to draw.

#'   Must match a value in the model's group column.  Mutually exclusive with

#'   `unit`.

#' @param unit    ID of a single unit whose **individual** edge network to draw

#'   (e.g. `"FirstGame::steven z"`).  Mutually exclusive with `group`.

#'   `compare` and `also` are not supported when `unit` is supplied.

#' @param weights Explicit network data: a named numeric vector (names

#'   `"A & B"` or `"A.B"`; missing edges are 0), an unnamed vector in the

#'   model's edge-column order, a matrix / data frame of rows (column means;

#'   non-numeric columns are dropped, so `set$line.weights[...]` works), or a

#'   named list of any of those (one layer each). Signed: positive weights use

#'   `colors[1]`, negative `colors[2]`. Drawn on the model's scales — absolute

#'   width, and colour from the model-wide range (values beyond it clamp).

#'   Mutually exclusive with `group` / `unit`.

#' @param compare Name of a second group to subtract (`group − compare`), or —

#'   with `weights` — explicit data in any `weights` form, or a group name

#'   (`weights − that group's mean`). Positive differences use the primary

#'   colour; negative the secondary. Cannot be combined with `unit`.

#' @param also    Name of a second group to overlay alongside `group`.

#'   Cannot be combined with `unit`.

#' @param colors  `c(positive, negative)` colours for this network, or one

#'   colour (negatives then use its complement, as in rENA). Default: the

#'   group's palette colour(s); the first two palette colours for `weights`.

#' @param threshold `c(min, max)`, or `min` alone: edges with |weight| < `min`

#'   are not drawn and |weight| > `max` is capped at `max` (sign kept) — rENA's

#'   `threshold` semantics.

#' @param name    Label for this network layer, reported in edge events and

#'   tooltips. Default: the group / unit name, list element names, or

#'   `"network 1"`, `"network 2"`, ….

#' @param show    Logical.  `FALSE` clears all networks (named and explicit).

#'   Default `TRUE`.

#' @param color_scale How edge weights map to colour, using webENA's ramps

#'   (saturation 0.25–1, opacity 0.3–1). `"model"` (default) rescales from the

#'   smallest to the largest non-zero weight anywhere in the model, so separate

#'   plots of the same model (one group, another group, a unit, a subtraction)

#'   share one colour scale. `"plot"` rescales within this plot, as webENA

#'   does. `"absolute"` skips the ramps: saturation = opacity = |weight|.

#' @param edge_width Width of an edge of weight 1, as a fraction of the plot

#'   width. Width is absolute (raw weight × this), as in webENA, so equal

#'   weights draw equally wide in graphs of the same size; each node's

#'   diameter is the sum of its edges' widths. `NULL` uses qeviz's default

#'   (0.04).

#' @param magnify Multiply this plot's edge widths and node sizes (colour is

#'   unchanged), e.g. to make a faint subtraction readable. Whenever it is set

#'   — including `1` — the plot is labelled "(scaled N.Nx)", so exported plots

#'   state their scaling (webENA labels its side plots "(scaled 1.0x)" for the

#'   same reason). `NULL` (default) means no magnification and no label.

#' @param fixed_size Logical. `TRUE` keeps edge widths (lines, directed

#'   triangles, self-connection dots, hover targets) at their zoom-1 on-screen

#'   width when the plot is zoomed; `FALSE` lets them grow with the zoom (the

#'   default behaviour). Applies to every network of the plot. `NULL`

#'   (default) leaves the current setting unchanged.

#' @param self_size Size of ONA self-connection dots: `"node"` draws each at

#'   half its code node's radius (as webENA does), so the self weight only

#'   sets its colour; a positive number is that fraction of the node radius.

#'   Applies to every network of the plot. `NULL` (default) leaves the current

#'   setting unchanged (initially: sized by weight, like the edges).

#'

#' @return The modified `qe_plot` object.

#'

#' @examples

#' \dontrun{

#' # Two plots on the same scale (the default): SecondGame's lighter, thinner

#' # lines mean weaker connections, not a different scaling

#' qe_plot(set) |> qe_edges("FirstGame")

#' qe_plot(set) |> qe_edges("SecondGame")

#'

#' # Single group mean network, by name or from data

#' qe_plot(set) |> qe_edges("FirstGame")

#' m <- as.matrix(set$line.weights)

#' fg <- set$meta.data$Condition == "FirstGame"

#' sg <- set$meta.data$Condition == "SecondGame"

#' qe_plot(set) |> qe_edges(weights = m[fg, ])

#'

#' # Subtraction from data, with explicit colours

#' qe_plot(set) |> qe_edges(weights = m[fg, ], compare = m[sg, ], colors = c("blue", "red"))

#'

#' # A non-group subset, thresholded

#' qe_plot(set) |> qe_edges(weights = m[set$points$SVD1 > 0, ], threshold = 0.05,

#'                          name = "SVD1 > 0")

#'

#' # Individual unit network

#' qe_plot(set) |> qe_edges(unit = "FirstGame::steven z")

#'

#' # Individual unit + show all group means

#' qe_plot(set) |> qe_group() |> qe_edges(unit = "FirstGame::steven z")

#'

#' # Subtraction

#' qe_plot(set) |> qe_edges("FirstGame", compare = "SecondGame")

#'

#' # Overlay

#' qe_plot(set) |> qe_edges("FirstGame", also = "SecondGame")

#'

#' # No edges (means and/or points only)

#' qe_plot(set) |> qe_group() |> qe_edges(show = FALSE)

#' }

#'

#' @export

qe_edges <- function(p, group = NULL, unit = NULL, weights = NULL,

                     compare = NULL, also = NULL,

                     colors = NULL, threshold = NULL, name = NULL, show = TRUE,

                     color_scale = c("model", "plot", "absolute"), edge_width = NULL,

                     magnify = NULL, fixed_size = NULL, self_size = NULL) {

    # TypeScript reads getAttribute('edges') !== 'false', so we must emit the

    # string "false" — a logical FALSE would be omitted and edges would stay on.

  }

  # ── Explicit data: append one layer per network ────────────────────────────

      }

    }

  }

  # ── By name: replace the named network ─────────────────────────────────────

  # Validate group-based targets

    }

  }

  # Validate unit ID

  }

}

# ── Explicit-network helpers ────────────────────────────────────────────────

# Edge columns of the model: every "A.B" column of the edges frame whose parts

# are both node codes (ONA includes the self-connections "A.A").

.qe_edge_columns <- function(model) {

}

# Any rENA-style network input → a numeric vector named by `cols`.

.qe_resolve_weights <- function(x, cols, arg) {

  }

  }

}

# A group's mean network from the model's edges frame (for `compare = "B"`).

.qe_group_network <- function(p, group, cols) {

}

.qe_append_network <- function(frame, name, w) {

  }

}

.qe_layer_attrs <- function(colors, threshold) {

}

#' Show or hide unit points

#'

#' @param p    A `qe_plot` object.

#' @param show Logical. Default `TRUE`; `FALSE` clears all points and point sets.

#' @param units  Unit IDs to draw as a point set (a subset of the model's units).

#' @param points An arbitrary points matrix / data frame / `ena.points` rows

#'   (as rENA's `ena.plot.points()` accepts). IDs come from the model's id

#'   column when present; dimensions from the model's x / y columns, else the

#'   first two numeric columns.

#' @param color  One colour, or one per point. Default: each point's group

#'   colour, else a palette colour per set.

#' @param shape  `"circle"` (default), `"square"`, `"triangle"` or `"diamond"`;

#'   one or one per point. rENA's `"triangle-up"` is accepted.

#' @param labels Per-point label text (shown per the point label mode).

#' @param name   Point-set name; calls with `units` / `points` add a set, and a

#'   repeated name replaces it. Default `"points 1"`, `"points 2"`, ….

#' @param size Optional numeric dot size. Omit for the default (2.5).  Larger

#'   values draw bigger dots; the size is relative to the code-node size.

#' @param fixed_size Logical. When `TRUE`, unit dots keep a constant on-screen

#'   pixel size regardless of data extent, container size, or zoom. Default

#'   `FALSE` (dots scale with the coordinate space, like nodes and edges).

#' @return The modified `qe_plot` object.

#' @export

qe_points <- function(p, show = TRUE, units = NULL, points = NULL,

                      color = NULL, shape = NULL, labels = NULL, name = NULL,

                      size = NULL, fixed_size = FALSE) {

  }

    # All unit points, coloured by group (0.4 behaviour).

  }

  }

}

# ── Explicit point / group helpers ─────────────────────────────────────────

# A QEFrame back to a data.frame (rows may lack some columns).

.qe_frame_df <- function(frame) {

  }))

}

# Append rows to a QEFrame; rows whose `key` value (or `drop(row)`) matches

# are replaced. Columns are unioned (missing values → NA).

.qe_upsert_rows <- function(frame, rows, key, drop = NULL) {

  }

}

# Any rENA-style points input → data.frame with the model's id / x / y (and

# group, when present) columns. Dimensions: the model's x_col / y_col when the

# input has them, else its first two numeric columns (rENA's convention).

.qe_point_frame <- function(x, model) {

}

.qe_shape <- function(shape, fn) {

}

#' Show or hide the code nodes

#'

#' By default (`"auto"`) code nodes are drawn only when an edge network is

#' drawn, matching rENA, where nodes are part of `ena.plot.network()`: the

#' `<qe-nodes>` element is emitted only then.  Node positions always come from

#' the model and set the plot extent, so the scale does not change.

#'

#' Each node's diameter equals the summed widths of its drawn edges (for

#' directed / ONA models, only the edges directed at the node, plus its

#' self-connection), so node size is proportional to its accumulated

#' connection weight and comparable across plots of the same model.

#'

#' @param p    A `qe_plot` object.

#' @param show `"auto"` (default), `"always"`, or `"never"`.  `TRUE` / `FALSE`

#'   are accepted as `"always"` / `"never"`.

#' @param unconnected What to draw for nodes with no drawn edges: `"dot"`

#'   (default, a tiny dot that still marks the code's position) or `"hide"`

#'   (omit the node and its label).

#' @param positions Node positions for this plot, replacing the model's (as

#'   rENA's `ena.plot.network(node.positions =)`): a data frame / matrix /

#'   `rotation$nodes`-like table with a code column (the model's node id

#'   column, `code`, or row names) and two numeric columns (the model's x / y

#'   columns when present, else the first two numeric ones). A subset of codes

#'   moves only those nodes. Edges, node sizes, labels and the plot extent all

#'   follow the new positions.

#' @param labels Display text per code: a named character vector

#'   (`c(Technical.Constraints = "Tech. constraints")`). The code stays the

#'   node's identity (events, edges); only the drawn label changes. `""`

#'   draws no label for that code.

#' @param sizes Node diameters in CSS pixels at zoom 1, per code: a named

#'   numeric vector (`c(Data = 24)`), in place of the size from the node's

#'   edge weights. Codes not listed keep the computed size; unconnected nodes

#'   stay a tiny dot (or hidden).

#' @param fixed_size Logical. `TRUE` keeps node diameters at their zoom-1

#'   on-screen size when the plot is zoomed. Default `FALSE` (nodes grow with

#'   the zoom).

#' @return The modified `qe_plot` object.

#' @examples

#' \dontrun{

#' # Means only, but keep the code nodes for orientation

#' qe_plot(set) |> qe_group() |> qe_nodes("always")

#' }

#' @export

qe_nodes <- function(p, show = c("auto", "always", "never"),

                     unconnected = c("dot", "hide"), positions = NULL, labels = NULL,

                     sizes = NULL, fixed_size = FALSE) {

    }

    }

    }

    }

  }

}

#' Show or hide the axes

#'

#' Adds a `<qe-axes>` layer (the x/y axis cross) to the rendered graph.  Axis

#' labels are opt-in: each of `x` and `y` is `FALSE` (no label) by default;

#' `TRUE` uses the dimension name (e.g. `"SVD1"`) and a string sets custom text.

#'

#' @param p    A `qe_plot` object.

#' @param x    `TRUE` to label the x-axis with its dimension name, a string for

#'   custom text, or `FALSE` for no x-axis label.  Default `FALSE`.

#' @param y    Same as `x`, for the y-axis.  Default `FALSE`.

#' @param show Logical. `FALSE` suppresses the axes entirely.  Default `TRUE`.

#' @param fixed_size Logical. `TRUE` keeps the axis lines and labels at their

#'   zoom-1 on-screen size when the plot is zoomed. Default `FALSE`.

#' @return The modified `qe_plot` object.

#' @export

qe_axes <- function(p, x = FALSE, y = FALSE, show = TRUE, fixed_size = FALSE) {

  }

}

#' Show or hide trajectory paths

#'

#' Adds a `<qe-trajectories>` layer to the rendered graph.  QEviz only renders

#' supplied trajectory rows; accumulation, dooring, model selection, and

#' inference remain the caller's responsibility.

#'

#' @param p A `qe_plot` object.

#' @param units Optional character vector of unit IDs to show.  Omit to show all

#'   units present in the model's `trajectories` frame.

#' @param smooth Path treatment: `"none"` for observed steps or `"poly"` for

#'   polynomial smoothing.

#' @param max_degree Upper bound on polynomial degree when `smooth = "poly"`.

#'   With `degree_selection = "loocv_2d"` the actual degree is chosen in

#'   `1..max_degree`; with `"fixed"` this degree is always used.

#' @param degree_selection Degree selection when `smooth = "poly"`. `"loocv_2d"`

#'   (default) picks the degree by joint 2D leave-one-out cross-validation;

#'   `"fixed"` always uses `max_degree`. Near-origin points are excluded from the

#'   fit (still drawn), matching `ena.plot.trajectory()`.

#' @param points Logical. Show observed state dots.

#' @param tips Logical. Show the leading current-state marker.

#' @param playhead Optional numeric time value. Rows after this value are hidden.

#' @param line_style `"uniform"` or `"tapered"`.

#' @param stroke_width Uniform stroke width in display pixels.

#' @param stroke_width_range Numeric length-2 vector for tapered paths.

#' @param opacity_range Numeric length-2 vector for tapered paths.

#' @param show Logical. `FALSE` suppresses trajectory rendering.

#'

#' @return The modified `qe_plot` object.

#'

#' @export

qe_trajectories <- function(p, units = NULL, smooth = c("none", "poly"),

                            max_degree = 3L,

                            degree_selection = c("loocv_2d", "fixed"),

                            points = TRUE, tips = TRUE,

                            playhead = NULL,

                            line_style = c("uniform", "tapered"),

                            stroke_width = 2,

                            stroke_width_range = c(1, 6),

                            opacity_range = c(0.3, 1),

                            show = TRUE) {

  }

    }

  }

}

#' Control label visibility

#'

#' Only the arguments you supply change; the rest keep their current setting

#' (so `qe_labels(font_size = 12)` leaves the label modes alone).

#'

#' @param p      A `qe_plot` object.

#' @param nodes  Label mode for code nodes.  One of `"on"`, `"off"`,

#'   `"click"`, `"auto"`. Default `"on"`.

#' @param means  Label mode for group means. Default `"on"`.

#' @param points Label mode for unit points. Default `"auto"`.

#' @param font_size   Label font size in **pixels** (constant on screen, as in

#'   rENA). Default: scales with the plot. The title is drawn at 1.35×.

#' @param font_family Label (and title) font family, e.g. `"Georgia"`.

#' @param font_color  Label (and title) colour. Default: each label's own colour

#'   (group colours for means).

#' @param font_weight Label font weight, e.g. `"bold"` or `600`: one value for

#'   node, mean and point labels, or a named vector for some of them

#'   (`c(nodes = "bold")`). `NULL` clears it. Default: 500.

#' @return The modified `qe_plot` object.

#' @export

qe_labels <- function(p, nodes = "on", means = "on", points = "auto",

                      font_size = NULL, font_family = NULL, font_color = NULL,

                      font_weight = NULL) {

  # A bare qe_labels() still applies the defaults, as before.

    } else {

    }

  }

}

# ══ Output functions ═══════════════════════════════════════════════════════════

# All three accept a qe_plot object, a raw ena.set, or a plain ModelData list.

#' Return a qeviz plot as an HTML string

#'

#' @param x           A `qe_plot` object, a raw rENA / tma / ona set, or a

#'   `ModelData` list from [qe_model_data()] / [qe_extract()].

#' @param title       `<title>` text. Defaults to the title stored in the

#'   `qe_plot` object when one is supplied.

#' @param graph_opts  Named list of `<qe-graph>` attribute overrides.  When `x`

#'   is a `qe_plot` object the stored opts are used as the base; keys supplied

#'   here take precedence.

#' @param ...         Additional arguments forwarded to [qe_extract()] when `x`

#'   is a raw set.

#' @return A single character string containing a complete HTML document.

#' @examples

#' \dontrun{

#' writeLines(qe_html(set), "plot.html")

#' writeLines(qe_html(qe_plot(set) |> qe_group("FirstGame")), "plot.html")

#' }

#' @export

qe_html <- function(x, title = NULL, graph_opts = list(), ...) {

}

#' Write a self-contained qeviz HTML file

#'

#' @param x          A `qe_plot` object, a raw rENA / tma / ona set, or a

#'   `ModelData` list.

#' @param file       Output file path (should end in `.html`).

#' @param title      `<title>` text (defaults to stored title for `qe_plot` objects).

#' @param graph_opts Named list of `<qe-graph>` attribute overrides.

#' @param open       If `TRUE` (default when interactive), open after writing.

#' @param ...        Additional arguments forwarded to [qe_extract()] when `x`

#'   is a raw set.

#' @return The normalised `file` path, invisibly.

#' @examples

#' \dontrun{

#' qe_export_html(set, "ena_plot.html")

#' qe_export_html(qe_plot(set) |> qe_group("FirstGame"), "fg.html")

#' }

#' @export

qe_export_html <- function(x, file, title = NULL, graph_opts = list(),

                           open = interactive(), ...) {

}

#' Return a qeviz plot as an embeddable HTML fragment

#'

#' Returns a `<div>` with the inlined bundle and a `<qe-visual>` / `<qe-graph>`

#' pair — no `<html>` wrapper, suitable for R Markdown / Quarto via

#' `htmltools::HTML()`.

#'

#' @param x           A `qe_plot` object, a raw rENA / tma / ona set, or a

#'   `ModelData` list.

#' @param height      CSS height of the containing `<div>`. Default `"480px"`.

#' @param graph_opts  Named list of `<qe-graph>` attribute overrides.

#' @param ...         Additional arguments forwarded to [qe_extract()] when `x`

#'   is a raw set.

#' @return A character string of class `"html"`.

#' @examples

#' \dontrun{

#' htmltools::HTML(qe_fragment(set))

#' htmltools::HTML(qe_fragment(qe_plot(set) |> qe_group("FirstGame")))

#' }

#' @export

qe_fragment <- function(x, height = "480px", graph_opts = list(), ...) {

  )

}

# ── Internal: open a file in RStudio viewer or browser ────────────────────────

.open_viewer <- function(path) {

  } else {

  }

}

#' The default qeviz colour palette

#'

#' Paul Tol's "bright" scheme, the colours qeviz assigns to groups, points

#' and networks when none are given (the same list as the JavaScript

#' library's default). Pass a different vector to `qe_plot(palette =)`.

#'

#' @return A character vector of eight hex colours.

#' @examples

#' qe_palette()

#' @export

qe_palette <- function() {

}

#' Set the axis range of a plot

#'

#' Changes the symmetric axis range of an existing plot, as `qe_plot(range =)`

#' does at creation.

#'

#' @param p     A `qe_plot` object.

#' @param range `"network"` (the node extent × 1.2), `"points"` (the unit

#'   points' extent × 1.2), a positive number (the axes run from `-range` to

#'   `range`), or `NULL` for the default.

#' @return The modified `qe_plot` object.

#' @examples

#' \dontrun{

#' qe_plot(set) |> qe_range(2)

#' }

#' @export

qe_range <- function(p, range) {

}

.qe_check_range <- function(range, fn) {

}

# widget.R — htmlwidget, knitr and Shiny output

#' Render a qeviz plot as an htmlwidget

#'

#' Wraps a [qe_plot()] chain as an htmlwidget, so it renders in the RStudio

#' Viewer, R Markdown / Quarto and Shiny, and can be saved with

#' [htmlwidgets::saveWidget()]. Printing a `qe_plot` uses this.

#'

#' @param p         A `qe_plot` object, or a set / `ModelData` list (passed to

#'   [qe_plot()] with `...`).

#' @param width,height Widget size — a number (pixels) or a CSS length.

#'   Default: the `width` / `height` given to [qe_plot()].

#' @param elementId Optional element id.

#' @param ...       Passed to [qe_plot()] when `p` is not a `qe_plot`.

#' @return An `htmlwidget`.

#' @examples

#' \dontrun{

#' w <- qe_plot(set) |> qe_edges("FirstGame") |> qe_widget()

#' htmlwidgets::saveWidget(w, "plot.html")

#' }

#' @export

qe_widget <- function(p, width = NULL, height = NULL, elementId = NULL, ...) {

  )

    )

  )

}

#' Shiny bindings for qeviz

#'

#' `qeOutput()` places a plot in the UI; `renderQe()` fills it from an

#' expression returning a `qe_plot` or a [qe_widget()].

#'

#' @param outputId Shiny output id.

#' @param width,height CSS size of the output.

#' @param expr     Expression returning a `qe_plot` or `qe_widget()`.

#' @param env      Environment in which to evaluate `expr`.

#' @param quoted   Is `expr` already quoted?

#' @examples

#' \dontrun{

#' ui <- shiny::fluidPage(

#'   shiny::selectInput("g", "Group", c("FirstGame", "SecondGame")),

#'   qeOutput("plot")

#' )

#' server <- function(input, output) {

#'   output$plot <- renderQe(qe_plot(set) |> qe_edges(input$g) |> qe_group(input$g))

#' }

#' shiny::shinyApp(ui, server)

#' }

#' @export

qeOutput <- function(outputId, width = "100%", height = "440px") {

}

#' @rdname qeOutput

#' @export

renderQe <- function(expr, env = parent.frame(), quoted = FALSE) {

  # Accept a qe_plot as well as a widget.

  })

}

#' Render a qe_plot object in the viewer

#'

#' Called when a `qe_plot` is returned at the top level: shows it as a

#' [qe_widget()] in the RStudio Viewer or the browser.

#'

#' @param x A `qe_plot` object.

#' @param ... Ignored.

#' @export

print.qe_plot <- function(x, ...) {

}

# Registered in .onLoad so knitr stays a suggested package.

knit_print.qe_plot <- function(x, ..., options = NULL) {

}

.onLoad <- function(libname, pkgname) {

}

.qe_dependency <- function() {

  )

}

# "440" -> 440 (pixels); CSS lengths ("100%", "30em") pass through.

.qe_css_size <- function(v) {

}

# frames.R — low-level helpers for building QEFrame structures

#

# A QEFrame is the wire format qeviz expects for every data table:

#   { data: [ {col: val, ...}, ... ], types: { col: "character"|"numeric"|"integer"|"logical" } }

# ── Internal helpers ───────────────────────────────────────────────────────────

#' Convert a data.frame to a QEFrame list

#'

#' Serialises a data.frame into the `{ data, types }` structure expected by

#' qeviz's `ModelData` interface.  Factors are coerced to character.

#'

#' @param df A `data.frame` (or object coercible via `as.data.frame()`).