API reference

aster_blueprint::editor

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Experimental graph editor transaction engine.

The editor owns authored graph state for one local authoring session. It is not an application snapshot, a backend authority, a persisted document or a renderer receipt. Every graph edit is rebuilt into a candidate source and compiled before it is adopted; a refused edit leaves the source, the plan and the revision untouched. Editor coordinates are separate presentation state and never enter the runtime source, so dragging a box does not recompile the graph.

GraphSource has no Clone implementation. Candidates are therefore reconstructed through the public model API: authoring NodeKey values are preserved, while the adopted source carries a new process-local stamp.

Reusable asset library mode (opt-in)

Editor::open and Editor::new are the default mode: the authored source is compiled directly. Editor::open_with_library opts one session into reusable-asset-library mode. That mode keeps three distinct Arcs per state:

  • the authored source the caller passed, which is what [Editor::source] returns and what [Change] edits operate on; its authoring node keys are never rewritten;
  • the compiled expansion: the authored source is flattened through the immutable session [ArcAssetLibrary] and the environment's resource types, then materialized into a fresh source graph;
  • the plan compiled from exactly that expanded source.

Every accepted transaction re-expands the authored candidate, materializes it with the session expansion [Limits], and compiles the result, so [Plan::matches] holds for the expanded source at all times. A refused expansion or compile leaves the accepted authored/compiled/plan Arcs, the revision, the history and the presentation positions untouched. The library

(documentation continues in the source)

Structs

structaster_blueprint::editor::Edit

pub struct Edit { /* see fields */ }

One edit authored against a specific editor revision.

Public fields

fieldtype
expected_revisionu64
changeChange

Methods

  • fn new(expected_revision: u64, change: Change) -> Self

Trait implementations: Clone, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::editor::EditOutcome

pub struct EditOutcome { /* see fields */ }

Result of an adopted transaction. Refusals return no outcome at all.

Public fields

fieldtype
revisionu64
sourcesuper::model::SourceStamp
plansuper::compiler::PlanId

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

structaster_blueprint::editor::EditPreview

pub struct EditPreview<'a> { /* see fields */ }

Read-only view of the compiled candidate handed to the admission callback. It privately borrows the candidate state, which is not yet adopted: the editor's own accessors still return the previous state during the call.

Methods

  • fn source(&self) -> &'a Arc<GraphSource> — Authored candidate source (macro instances intact in library mode).
  • fn compiled_source(&self) -> &'a Arc<GraphSource> — Source that was actually compiled; the authored Arc in default mode.
  • fn plan(&self) -> &'a Arc<Plan>
  • fn expansion(&self) -> Option<&'a Arc<ExpandedAsset>> — Expansion provenance in library mode, None in default mode.
  • fn revision(&self) -> u64 — The revision the editor will report if the candidate is adopted.

structaster_blueprint::editor::Editor

pub struct Editor { /* see fields */ }

Transactional graph editor over an authored source and its compiled plan.

Methods

  • fn open(source: Arc<GraphSource>, catalog: Arc<Catalog>, env: Environment, limits: CompileLimits) -> Result<Self, EditorError> — Compile a source and open it for editing in default mode.
  • fn new(source: Arc<GraphSource>, plan: Arc<Plan>, catalog: Arc<Catalog>, env: Environment, limits: CompileLimits) -> Result<Self, EditorError> — Open an already compiled source/plan pair in default mode. The plan must have been compiled from exactly this source.
  • fn open_with_library(authored: Arc<GraphSource>, library: ArcAssetLibrary, catalog: Arc<Catalog>, env: Environment, limits: CompileLimits, expansion_limits: Limits) -> Result<Self, EditorError> — Opt this session into reusable-asset-library mode.
  • fn with_history_limit(self, limit: usize) -> Self — Bound the retained undo depth (a state count, not a byte budget). Retained authored literal bytes are bounded only by the state count times the per-source payload; older states are dropped, never the adopted state.
  • fn source(&self) -> &Arc<GraphSource> — The authored source the caller passed and edits. In library mode this still contains the macro instance nodes; the expansion is not substituted here.
  • fn compiled_source(&self) -> &Arc<GraphSource> — The source graph that was actually compiled for the current state.
  • fn plan(&self) -> &Arc<Plan>
  • fn expansion(&self) -> Option<&Arc<ExpandedAsset>> — Expansion provenance for the adopted state, or None in default mode.
  • fn revision(&self) -> u64 — Monotonic editor revision. Undo and redo also advance it, so an edit authored against an older revision stays refused.
  • fn can_undo(&self) -> bool
  • fn can_redo(&self) -> bool
  • fn apply(&mut self, edit: Edit) -> Result<EditOutcome, EditorError> — Apply one typed edit as a transaction: rebuild a candidate source, compile it, and adopt it only when the compile succeeds.
  • fn apply_batch(&mut self, expected_revision: u64, changes: &[Change]) -> Result<EditOutcome, EditorError> — Compile and adopt a bounded group of changes as one undoable edit.
  • fn apply_batch_with<R, E>(&mut self, expected_revision: u64, changes: &[Change], admit: impl FnOnce(&EditPreview<'_>) -> Result<R, E>) -> Result<(EditOutcome, R), ApplyWithError<E>> — Compile a batch and let admit veto the candidate before adoption.
  • fn undo(&mut self) -> Result<EditOutcome, EditorError> — Restore the previous retained state, including its authored source, compiled expansion source, plan and expansion provenance.
  • fn undo_with<R, E>(&mut self, admit: impl FnOnce(&EditPreview<'_>) -> Result<R, E>) -> Result<(EditOutcome, R), ApplyWithError<E>> — Undo with admission. The previous retained state is previewed through [EditPreview] and adopted only if admit returns Ok.
  • fn redo_with<R, E>(&mut self, admit: impl FnOnce(&EditPreview<'_>) -> Result<R, E>) -> Result<(EditOutcome, R), ApplyWithError<E>> — Redo with admission; the mirror of [Editor::undo_with]. The history stack is reserved before admit, and NothingToRedo never calls it. The push honors the configured history limit (an infallible front pop after admit). Legacy [Editor::redo] is unchanged and does not trim.
  • fn redo(&mut self) -> Result<EditOutcome, EditorError> — Re-adopt the state that was most recently undone.
  • fn set_position(&mut self, node: NodeKey, x: f64, y: f64) -> Result<EditorPosition, EditorError> — Move an editor box. This is presentation state only: the source stamp, the plan and the revision are untouched, so no recompile happens.
  • fn position(&self, node: NodeKey) -> Option<EditorPosition>
  • fn positions(&self) -> &BTreeMap<NodeKey, EditorPosition>
  • fn history_stats(&self) -> HistoryStats — Counted history accounting. Retained bytes are authored literal payload bytes of retained states, never an estimate of process memory and never an enforced byte budget.

Trait implementations: Debug

structaster_blueprint::editor::EditorPosition

pub struct EditorPosition { /* see fields */ }

Editor-only coordinates. They are never compiled and never serialized.

Public fields

fieldtype
xf64
yf64

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::editor::HistoryStats

pub struct HistoryStats { /* see fields */ }

Honest history accounting: the count bound on retained undo states and the authored literal payload bytes those retained states currently hold. There is no independent byte budget: limit bounds the retained undo state count, so the retained bytes are bounded by the distinct retained states times the per-source authored literal payload, not by a custom byte limit. This is not process memory and not total resident size.

Public fields

fieldtype
limitusize
undo_entriesusize
redo_entriesusize
retained_statesusizeDistinct retained states, including the adopted current state.
retained_literal_bytesusizeAuthored literal payload bytes retained by those states.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

Enums

enumaster_blueprint::editor::ApplyWithError

pub enum ApplyWithError<E> { Editor, Allocation, Admit }

Refusals from [Editor::apply_batch_with], kept in distinct categories so a caller can tell an editor/compile refusal from a failed admission.

Variants

  • Editor — Input, revision, expansion or compile refusal. The admission callback was never called.
  • Allocation — The history reserve for the adopting push failed. This is the only allocation that can fail and it happens before the callback.
  • Admit — The callback refused the candidate. Nothing was adopted.

Trait implementations: Clone, Debug, Display, Eq, Error, From<ApplyWithError<RetargetError>>, PartialEq, StructuralPartialEq

enumaster_blueprint::editor::Change

pub enum Change { SetBinding, SetOutput, RemoveOutput, SetLiteral, Connect, AddNode, RemoveNode, SetParameter, AddParameter, RemoveParameter }

A typed, bounded graph change. Each variant is applied as one transaction.

Variants

  • SetBinding — Replace any ordinary authored input binding, including resources and parameters. Compilation still validates the exact declared port type.
  • SetOutput — Add or replace a declared output by name.
  • RemoveOutput — Remove a declared output by name.
  • SetLiteral — Bind an authored input port to a literal value.
  • Connect — Bind an authored input port to another node's output port.
  • AddNode — Add a node with an explicit authoring key.
  • RemoveNode — Remove a node. Connection bindings that referenced it are dropped too; a dependent input without a default then refuses the edit.
  • SetParameter — Replace a declared parameter default, or make it required.
  • AddParameter — Declare a new parameter. A duplicate name is refused with the model's own duplicate-interface error; the declared type and default are validated by the public model when the candidate source is rebuilt.
  • RemoveParameter — Remove a declared parameter by name. Bindings that referenced it are not rewritten or deleted: the removal only compiles once every dependent binding has been rebound in the same transaction.

Trait implementations: Clone, Debug, PartialEq, StructuralPartialEq

enumaster_blueprint::editor::EditorError

pub enum EditorError { EmptyTransaction, TransactionLimit, UnknownOutput, Stale, UnknownNode, UnknownParameter, Model, Compile, Expand, NothingToUndo, NothingToRedo, InvalidPosition, RevisionExhausted, PlanMismatch }

Refusals produced by the editor itself. Compile refusals are reported with the compiler's own typed error so a cycle or a bad port is never guessed at.

Variants

  • EmptyTransaction
  • TransactionLimit
  • UnknownOutput
  • Stale — The edit was authored against an older revision and is out of order.
  • UnknownNode
  • UnknownParameter
  • Model
  • Compile
  • Expand — A reusable-asset expansion or materialization refusal in library mode. The library's own typed error is preserved rather than flattened.
  • NothingToUndo
  • NothingToRedo
  • InvalidPosition
  • RevisionExhausted
  • PlanMismatch

Trait implementations: Clone, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

Type aliases

typeaster_blueprint::editor::ArcAssetLibrary

pub type ArcAssetLibrary = std::sync::Arc<super::asset::AssetLibrary>;

A shared, immutable handle to the reusable asset library for one editor session. The editor neither mutates nor re-reads it, so every expansion sees exactly these assets.

Constants

constaster_blueprint::editor::DEFAULT_HISTORY_LIMIT

pub const DEFAULT_HISTORY_LIMIT: usize

Bounded number of retained undo states by default.

constaster_blueprint::editor::MAX_TRANSACTION_CHANGES

pub const MAX_TRANSACTION_CHANGES: usize

Maximum number of authored changes in one atomic editor transaction.