Struct By 

pub struct By {
    pub kind: String,
    pub data: Value,
}

Producer identity for a SourceInfo::Generated node.

kind is a short, kebab-case identifier describing which transform produced the node (“filter”, “shortcode”, “sectionize”, …). Third parties should namespace as ext/<extension>/<kind>.

data is per-kind configuration that is not a source-info pointer. Source-side anchors live in the parent Generated.from list, not here. Null for kinds that don’t carry per-instance data.

Fields

kind: String

Short kind tag, kebab-case. Examples: “filter”, “shortcode”, “sectionize”, “user-edit”, “title-block”. Third-party kinds should namespace: “ext/my-extension/foo”.

data: Value

Per-kind configuration that is NOT a source-info pointer. Anchors live in Generated.from, not here. Null for kinds that don’t carry per-instance data.

Implementations

impl By

pub fn filter(filter_path: impl Into<String>, line: usize) -> Self

Producer kind for a node constructed by a Lua filter (e.g. pandoc.Str("decoration") inside a filter callback).

filter_path is the path the Lua engine reported via debug.getinfo(...).source (with the leading “@” stripped); line is the line number inside that file where the constructor ran. Until Lua-file-registration lands (bd-36fr9), (filter_path, line) lives in by.data; afterwards it migrates to a Dispatch anchor and by.data shrinks to {}.

pub fn sectionize() -> Self

Producer kind for the SectionizeTransform’s synthesized section Divs. Children remain editable; the wrapper itself is structural.

pub fn user_edit() -> Self

Producer kind for React-constructed (user-typed) content reaching the AST through the q2-preview client.

pub fn shortcode(name: impl Into<String>) -> Self

Producer kind for shortcode resolutions.

Invariant. Every Generated { by: shortcode(...), .. } must carry at least one Invocation anchor in from pointing at the source token’s byte range. Use only inside a Generated whose anchor list is populated; constructing the bare shape with empty from is rejected by Plan 6’s audit-completion test and trips Plan 7’s writer debug_assert!.

pub fn include() -> Self

Producer kind for IncludeStage’s expansion wrapper. Note that most include-related synthesized content keeps its Original source_info (inherited from the include-line Paragraph) — this kind is only used where a Generated is explicitly required.

pub fn title_block() -> Self

Producer kind for the title-block stage’s synthesized title h1.

pub fn footnotes() -> Self

Producer kind for the footnotes stage’s container Div.

pub fn revealjs() -> Self

Producer kind for RevealSlidesTransform’s synthesized slide structure — title-slide Div, section wrappers, speaker-notes Div, and any other chrome built from the slide-level heading tree. Non-atomic: the slide container is structural chrome; the content inside (headings, paragraphs) retains its own source_info.

pub fn appendix() -> Self

Producer kind for the appendix-structure stage’s wrapper Div.

pub fn tree_sitter_postprocess() -> Self

Producer kind for parser-side synthetic Spaces inserted by the tree-sitter post-processing pass.

pub fn unknown() -> Self

“We don’t know” placeholder used by json::read_completing_source_info when a node arrives without an s: field from outside the q2 source-tracking world (qmd-syntax-helper Pandoc subprocess, CLI --from json, external filter binaries, Lua AST handoff).

Non-atomic by design — nodes carrying By::unknown() remain editable in the preview; user edits re-stamp them as user_edit on save. See Plan 7f Phase 4’s per-caller table for placement guidance.

pub fn test_scaffold() -> Self

Producer kind for test scaffolding. Non-atomic; appears only in test code where source_info is required by a constructor but has no real provenance to record. Paired with SourceInfo::for_test.

pub fn citeproc() -> Self

Producer kind for citeproc-rendered content (citation Str replacements, bibliography Divs, #refs wrappers). The bytes come from CSL processing of bibliographic metadata, not from user-written source.

Atomic — citeproc output is generated content the user can’t edit through the preview; changes go through the CSL pipeline, not through inline editing.

pub fn jupyter_output() -> Self

Producer kind for content synthesized from execution-engine output (Jupyter cell stdout / stderr, rich-display MIME bundles, kernel error tracebacks). The bytes come from kernel execution, not from user-written source.

Atomic — execution outputs are regenerated on every re-run; editing them through the preview would be a UX bug.

pub fn callout() -> Self

Producer kind for callout-decoration synthesis: default-title injection (Note, Warning, etc. when the user omits a title and appearance="default") and the screen-reader-only type announcement span.

Non-atomic — the wrapper Div is structural, and its children (the user’s actual callout body) remain editable through the preview. The synthesized title text itself has no preimage but regenerates from the callout type when the user changes it, so atomicity at the wrapper level would be incorrect.

pub fn config_default() -> Self

Empty-Map sentinel ConfigValue used during metadata merging when no value is present. Non-atomic. The bytes don’t exist — the node is structural. See By::is_programmatic_sentinel.

pub fn programmatic_config() -> Self

Programmatic construction of ConfigValue (e.g. ConfigValue::from_path, intermediate maps created during insert_path). No source bytes exist for these nodes. See By::is_programmatic_sentinel.

pub fn is_programmatic_sentinel(&self) -> bool

True for kinds whose source bytes don’t exist — config-default, programmatic-config, unknown. Used by code that needs to distinguish “no real source” sentinels from a genuine Original{FileId(0), …} pointing at a real document.

pub fn raw(kind: impl Into<String>, data: Value) -> Self

Escape-hatch constructor for any kind string — including built-in names and extension-defined kinds (ext/<extension>/<kind>).

Forgery (an extension calling By::raw("shortcode", …) without the required Invocation anchor) is caught downstream by Plan 6’s audit-completion test and Plan 7’s debug_assert!. The convention for third-party kinds is ext/<extension>/<kind>.

pub fn is_atomic_kind(&self) -> bool

True if a Generated { by: <self>, .. } node should be treated as atomic by the incremental writer.

Atomic nodes are produced by the pipeline and represent content the user shouldn’t edit through React (filter constructions, shortcode resolutions, synthesized title h1, tree-sitter-inserted spaces). Atomicity is determined by kind alone — orthogonal to anchor-presence.

Extensions that contribute new by.kind values are not atomic by default in v1.

pub fn is_kind(&self, kind: &str) -> bool

True if this By’s kind equals kind.

pub fn as_filter(&self) -> Option<(&str, usize)>

If self.kind == "filter", return (filter_path, line).

Returns None for any other kind, or when the data payload is malformed (missing or non-string filter_path, missing or non-integer line).

Trait Implementations

impl Clone for By

fn clone(&self) -> By

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for By

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for By

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for By

fn eq(&self, other: &By) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for By

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for By