Struct History 

pub struct History { /* private fields */ }

The engine-owned mutable history.

Implementations

impl History

pub fn from_request_json(json: &str) -> Result<Self, String>

Load a whole history document (a saved part file parses as one). Rolls to the last feature. Ensures a features array exists.

pub fn lock(&mut self, reason: impl Into<String>)

Refuse every change to the saved document until Self::unlock: Self::request_json stays byte for byte what it is now, whatever is called. reason is the sentence a host shows (“released”, “checked out by grace”, “not checked out”). Rolling (Self::set_rollback) is view state and stays free, and so does reading.

The three writes that do not pass Self::document_mut — the parts library, the feature counter and the undo/redo stacks — check the lock themselves; a_locked_history_keeps_its_saved_bytes calls every mutator and pins the invariant.

pub fn unlock(&mut self)

Allow changes again (a checkout took the lock).

pub fn locked(&self) -> Option<&str>

Why the document may not change, or None when it may.

pub fn refused_edits(&self) -> u64

Mutations refused while locked, counted since this history was built. A host compares it frame to frame to tell the user an edit was refused.

pub fn refused_user_edits(&self) -> u64

Refused mutations that were a user’s edit: every one that takes an undo checkpoint, an undo, redo or retract, a feature id minted, a parts-library edit. A kernel write-back (a solver fold, a pin settle, a parts-library heal) is refused just the same but not counted here: it is nobody’s edit, so a host tells the user about THIS count, not Self::refused_edits.

pub fn revision(&self) -> u64

A monotonic counter of mutation opportunities on the document — the cache key for anything derived from it that would otherwise be rebuilt every frame (see the __brepParams blob in BREP_app).

pub fn edit_serial(&self) -> u64

Moves on every user edit of the model and on every undo and redo, and on nothing else: not on a run’s write-back, not on rolling. What a transient view of the model (the family-row preview) keys on to know that the user changed the model under it.

pub fn features(&self) -> &[Value]

The features slice (empty if none).

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn rollback(&self) -> usize

The rolled-to index, clamped to a valid feature (0 when empty).

pub fn set_rollback(&mut self, index: usize)

pub fn feature_type(&self, index: usize) -> Option<String>

pub fn feature_id(&self, index: usize) -> Option<String>

pub fn index_of(&self, id: &str) -> Option<usize>

pub fn feature_params(&self, index: usize) -> Option<Value>

The inputParams document of the feature at index (for the dialog).

pub fn fold_param_no_undo(&mut self, id: &str, key: &str, value: Value) -> bool

SOLVER write-back fold (the assembly pose-authority contract): set ONE inputParams key of the feature whose inputParams.id == id, WITHOUT an undo checkpoint and WITHOUT breaking edit coalescing — a solve write-back is the kernel adopting its own result, not a user edit, so it must never mint an undo entry (undoing a user action then re-running re-solves and re-folds anyway). Returns whether a feature matched.

pub fn set_feature_params(&mut self, index: usize, params: Value)

pub fn set_many_feature_params(&mut self, edits: &[(usize, Value)])

Replace the inputParams of MANY features as ONE mutation — Self::set_feature_params’s batch sibling, and the reason it exists: a packed BOM row rolls up N occurrences, so editing one cell writes N features. A set_feature_params loop would mint N undo entries (each keyed param:{index}, so none of them coalesce with each other), and the user would have to press undo N times to take back ONE edit.

Exactly ONE checkpoint covers the whole batch. The coalesce key names the SET of indices, so a run of edits to the SAME set (typing into one packed cell) still merges into a single entry, while switching to a different set starts a new one — the param:{index} rule, lifted to a group. Out-of-range indices are skipped; an empty batch is a no-op (no checkpoint, so a fan-out that matched nothing leaves no empty entry).

pub fn push_feature(&mut self, feature: Value)

pub fn push_features(&mut self, features: Vec<Value>)

Append MANY features as ONE mutation — the batch an import lane needs (EngineState::add_features). Distinct from a push_feature loop in the two ways that matter: exactly ONE undo checkpoint (an N-instance assembly import undoes in one step, not N), and the caller re-runs once instead of once per feature. No-op for an empty batch (no checkpoint, so an import that produced nothing leaves no empty undo entry).

pub fn remove_feature(&mut self, index: usize)

pub fn swap(&mut self, a: usize, b: usize)

pub fn next_feature_id(&mut self, base: &str) -> String

Mint the id for a NEW feature: {base}{N} where base is the feature’s shortName and N is this history’s persistent GLOBAL counter, bumped by one on every mint (P.CU → P.CU7, S → S8). GLOBAL across all feature types, MONOTONIC, and NEVER reused — a delete does not free a number and undo does not rewind the counter — and it persists across save/load, so two features can never receive the same id over the document’s whole lifetime.

pub fn prefix_request(&self) -> Value

The stopAtId-truncated request that stops AFTER the rolled-to feature — the roll-to-step request the pipeline runs. Empty history → empty request.

pub fn request_before(&self, index: usize) -> Option<Value>

The request that stops BEFORE feature index — the scene that feature resolves its references against, wherever the model is rolled to. None when there is no feature at index.

pub fn listing_json(&self) -> String

The tree listing for the UI: { step, features: [{index, type, id}] }.

pub fn request_json(&self) -> String

The whole request document (for persistence / debugging), with the persistent global feature counter folded back in under "featureCounter" so it round-trips through save/load (the twin of Self::from_request_json, which lifts it back out). Written only when non-zero, so a document that has never minted a feature persists byte-for-byte as before (mirrors the metadata field’s “un-annotated model persists unchanged” convention).

pub fn request_value(&self) -> Value

Self::request_json as a value, for a caller that edits it: the same document, never printed and parsed back (an assembly’s library is megabytes).

pub fn request_json_without_parts_library(&self) -> String

The document WITHOUT the parts-library block — for the kernel round trips that never read it. The assembly pose fold (assembly_apply_document_json) only rewrites the assembly block and per-feature inputParams, so handing it the library would serialize, parse and re-serialize megabytes of part payload on every edit for nothing. Self::request_json is the SAVE door and still carries it.

pub fn can_undo(&self) -> bool

Whether an undo step is available (for enabling the toolbar button).

pub fn can_redo(&self) -> bool

Whether a redo step is available.

pub fn undo(&mut self) -> bool

Undo the last model mutation: push the current state onto the redo stack and restore the previous document + rolled-to step. Returns whether it changed anything (false when the undo stack is empty).

pub fn redo(&mut self) -> bool

Redo the last undone model mutation (symmetric with Self::undo).

impl History

pub fn adopt_document(&mut self, document_json: &str) -> Result<(), String>

ADOPT a whole replacement document — the assembly FOLD’s write-back lane (assembly_apply_document_json returns the document with the solved assembly block + poses/isFixed folded into the features; the engine adopts it before persisting or re-running — the pose-authority contract).

checkpoint chooses the undo semantics: a USER constraint mutation records an undo snapshot (so constraint edits stay undoable like any model edit); the silent post-run pose fold passes false (solver write-back is not a user edit — undoing the user’s LAST edit must not strand an extra fold step in between).

A stray featureCounter in the adopted document is stripped (the in-memory counter stays authoritative — request_json re-folds it on serialize, exactly like from_request_json lifts it on load). The rollback index is preserved (the fold never changes the feature count).

pub fn adopt_document_value(&mut self, document: Value) -> Result<(), String>

Self::adopt_document for a caller that already holds the parsed document: an assembly’s parts library is megabytes, and printing it only to parse it back was most of an Update Components commit at 500 parts.

pub fn adopt_document_checkpointed( &mut self, document_json: &str, ) -> Result<(), String>

Same adoption with an undo snapshot recorded FIRST (never coalesced) — the user-mutation twin of Self::adopt_document.

pub fn adopt_document_value_checkpointed( &mut self, document: Value, ) -> Result<(), String>

Self::adopt_document_checkpointed for an already parsed document.

pub fn set_parts_library(&mut self, library: Value)

Replace the document’s partsLibrary block (the assemblies parts library) — the caller feeds brep_kernel::parts_library_json() here (never an echo of a loaded block), so SAVE serializes the kernel store with its heals and GC. An empty map clears the field, so a non-assembly document serializes byte-identically to before.

The block is held in the parts_library FIELD rather than on self.document; Self::request_json folds it back into the saved document. The on-disk shape is unchanged.

pub fn set_parts_library_edited( &mut self, library: Value, coalesce_key: Option<&str>, )

Replace the partsLibrary block as a USER EDIT: one undo checkpoint, and the mirror flag CLEARED so the next run ships the block to the runner instead of assuming the kernel store already agrees.

Self::set_parts_library is the other door and means the opposite — “this block came OUT of the kernel store” — so it must not be reused here: a part-attribute edit is authored on this side and the runner has never seen it. coalesce_key follows the param:{index} rule so a run of keystrokes into one attribute is one undo entry.

pub fn parts_library(&self) -> &Value

The partsLibrary block (Value::Null when the document has none).

pub fn undo_top_block(&self, key: &str) -> Option<&Value>

Top-level block key of the document as it stood before the NEWEST undoable edit (None with nothing to undo, or when that document had no such block): what a caller reads to tell whether the newest step is the one it means to take back.

pub fn undo_parts_libraries(&self) -> impl Iterator<Item = &Value> + '_

The partsLibrary block as it stood before each undoable edit, newest first: where a caller finds a library entry as it was when it appeared.

pub fn assembly_block(&self) -> Option<&Value>

The document’s assembly block ({constraints, idCounter}), if any.

pub fn set_assembly_block(&mut self, block: Value, checkpoint: bool)

Replace the assembly block ({constraints, idCounter}) — the STATE half of the assembly write-back, which the engine folds from the run’s reply after every run and from the live session after a constraint mutation. checkpoint = true makes it an undoable USER edit (a mutation); false writes it silently, because a solver adopting its own result is not a user edit and must never mint an undo entry — undoing a user action then re-running re-solves and re-folds anyway.

pub fn wire_harness_block(&self) -> Option<&Value>

The document’s wireHarness block ({connections, idCounter, buildBundles}), if any.

pub fn set_wire_harness_block(&mut self, block: Option<Value>)

Replace (or, with None, remove) the wireHarness block. A USER edit: snapshotted for undo, never coalesced — each add / edit / remove of a connection is its own undo step, like a feature add or delete.

impl History

pub fn pmi_block(&self) -> Option<&Value>

The document’s pmi block ({views, idCounter}), if any.

pub fn set_pmi_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the pmi block as a USER edit: snapshotted for undo. coalesce_key groups a run of rapid same-target edits (a label drag: pmi:label:{id}) into ONE undo entry; None makes the edit its own step (a view capture, an annotation add / edit / delete).

pub fn set_pmi_block_no_undo(&mut self, block: Option<Value>)

Replace the pmi block WITHOUT an undo checkpoint — for a write that belongs to the checkpoint just taken (an import lifting a file’s PMI beside the feature it added, so one undo removes both).

pub fn break_coalescing(&mut self)

End a coalescing run (a label drag released): the next edit with the same key starts a fresh undo entry.

impl History

pub fn cam_block(&self) -> Option<&Value>

The document’s cam block ({setups, tools, operations, ncPrograms, idCounter}), if any.

pub fn set_cam_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the cam block as a USER edit: snapshotted for undo. coalesce_key groups a run of rapid same-target edits (typing in one field of one operation: cam:op:{id}:{field}) into ONE undo entry; None makes the edit its own step (a setup, tool or operation add / delete, a pick committed).

pub fn set_cam_block_no_undo(&mut self, block: Option<Value>)

Replace the cam block WITHOUT an undo checkpoint — for a write that belongs to the checkpoint just taken (an import lifting a file’s CAM data beside the feature it added, so one undo removes both).

impl History

pub fn sheets_block(&self) -> Option<&Value>

The document’s sheets block ({sheets, idCounter}), if any.

pub fn set_sheets_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the sheets block as a USER edit: snapshotted for undo. coalesce_key groups a run of rapid same-target edits (dragging a placed view: sheet:view:{id}) into ONE undo entry, exactly as the PMI label drag’s does.

impl History

pub fn part_attributes_block(&self) -> Option<&Value>

The document’s own partAttributes record, if any.

pub fn set_part_attributes_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the document’s own partAttributes record as a USER edit: snapshotted for undo. coalesce_key groups a run of edits to ONE field (a typing run in the Properties dialog) into a single undo entry, exactly as the PMI block’s does.

impl History

pub fn expressions(&self) -> String

The history document’s expressions source string (empty when absent or stored as null). The panel’s editor binds to this.

pub fn set_expressions(&mut self, expressions: &str)

Replace the expressions source string. Snapshotted for undo, coalescing a run of keystroke edits into ONE undo entry (like a slider drag) via the shared "expressions" coalesce key, so a distinct add/edit/roll starts a fresh entry. A no-op re-set (same text) still records under the same key.

pub fn configurator(&self) -> Value

The configurator object (typed named inputs), or {} when absent — read-only for the panel’s display (deeper configurator editing deferred).

impl History

pub fn feature_persistent_data(&self, index: usize) -> Option<Value>

The persistentData document of the feature at index (None if the feature or the field is absent) — the read twin of Self::feature_params.

pub fn set_feature_persistent_field( &mut self, index: usize, key: &str, value: Value, )

Set a single key inside the feature-at-index’s persistentData object, creating (or replacing a non-object) persistentData as needed. Snapshotted for undo (a structural edit — never coalesced), like an add/delete.

pub fn set_feature_persistent_field_coalesced( &mut self, index: usize, key: &str, value: Value, coalesce_key: Option<&str>, )

Self::set_feature_persistent_field with an optional COALESCE key: a run of same-key writes (a gizmo drag moving a spline anchor, frame after frame) records ONE undo entry, exactly as a slider drag on a param does.

pub fn set_feature_persistent_fields( &mut self, index: usize, fields: Vec<(&str, Value)>, ) -> bool

Write several persistentData fields of the feature at index as ONE user edit: one undo checkpoint covers them all, and there is none when every field already holds its value, so an action that changed nothing leaves no undo step that does nothing. Returns whether anything changed.

Leaving a sketch writes its geometry, its dimension label offsets and its external references this way. Written one field at a time they were three undo steps, and only the third Ctrl+Z took the drawing back.

pub fn undo_top(&self) -> Option<u64>

The undo step on top of the stack right now, as a token for Self::retract and Self::set_feature_persistent_fields_in_step; None when there is nothing to undo.

pub fn retract(&mut self, step: u64) -> bool

Take back undo step step as though its edit had never been made: restore the state it holds and DROP it, leaving no redo entry. Only while step is still the newest step; otherwise nothing happens and this returns false, and the caller undoes the ordinary way.

Cancelling a sketch created in the same session uses it, so the cancel leaves no undo step behind: two presses, one of which brought the cancelled sketch back, before. It cannot restore a redo stack the step’s own edit cleared when it was taken. Neither could the cancel it replaces.

pub fn set_feature_persistent_fields_in_step( &mut self, index: usize, fields: Vec<(&str, Value)>, step: u64, ) -> bool

Self::set_feature_persistent_fields as part of undo step step, with no checkpoint of its own, while step is still the newest step; otherwise an ordinary write with its own step. Finishing a sketch created in the same session writes this way, so creating, drawing and finishing it is one undo step.

impl History

pub fn diagram_block(&self) -> Option<&Value>

The document’s diagram block, if any.

pub fn pcb_block(&self) -> Option<&Value>

The document’s pcb block, if any.

pub fn symbol_block(&self) -> Option<&Value>

The document’s symbol block, if any.

pub fn pads_block(&self) -> Option<&Value>

The document’s pads block, if any.

pub fn ports_block(&self) -> Option<&Value>

The document’s ports block (its declared connection points), if any.

pub fn declared_points(&self) -> Vec<DeclaredPoint>

The part’s declared connection points, in block order.

pub fn pin_labels(&self) -> Option<Vec<String>>

The symbol’s pin labels in pin order, or None without a symbol.

pub fn pins(&self) -> Option<Vec<DeclaredPin>>

The symbol’s pins with the UNIT each belongs to, in pin order, or None without a symbol. Self::pin_labels with the unit kept, for a caller that must say WHICH group a pin binds into.

pub fn port_group_for_unit(&self, unit: u32) -> Option<String>

The port group the pins of symbol unit unit bind into, when one is mapped. The unit map’s rule is the kernel’s (brep_kernel::unit_groups).

pub fn set_diagram_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the diagram block as a USER edit. See Self::set_ecad_block for coalesce_key.

pub fn set_pcb_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the pcb block as a USER edit. See Self::set_ecad_block for coalesce_key.

pub fn set_symbol_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the symbol block as a USER edit, and follow it to the part’s ports in the same undo step (see Self::follow_pins). See Self::set_ecad_block for coalesce_key.

pub fn set_pads_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the pads block as a USER edit. See Self::set_ecad_block for coalesce_key.

pub fn set_symbol_block_no_undo(&mut self, block: Option<Value>)

Write the symbol block WITHOUT an undo checkpoint, for a write that belongs to the checkpoint just taken: a KiCad import adds its Import 3D feature (one checkpoint) and writes the symbol and pads it read beside it, so one undo removes the whole import. The PMI import’s Self::set_pmi_block_no_undo is the precedent.

Skipping the checkpoint is deliberate, and costs the tab nothing: the write still goes through document_mut, which moves the revision the unsaved dot and the autosave key on.

pub fn set_pads_block_no_undo(&mut self, block: Option<Value>)

The pads twin of Self::set_symbol_block_no_undo.

pub fn set_ports_block( &mut self, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) the ports block as a USER edit, and follow it to the part’s pins in the same undo step (see Self::follow_ports).

pub fn set_ports_block_no_undo(&mut self, block: Option<Value>)

The ports twin of Self::set_symbol_block_no_undo — for a write that belongs to the checkpoint just taken (the KiCad import).

impl History

pub fn pin_port_hold(&self) -> Option<&str>

Why the latest pin or port edit was not followed to the other side, in words that name the label (two pins are labelled '1'), or None.

pub fn pin_point_report(&self) -> Option<PinPointReport>

Everything about this part’s pins and connection points that does not pair, by name; None for a document without a symbol.

pub fn ports_follow_pending(&self) -> bool

Whether the next crate::engine_state::EngineState::pump will re-run for a moved point, without clearing it — so the app can hand a document that is not in front its own parts library before that run is submitted.

impl History

pub fn document_block(&self, key: &str) -> Option<&Value>

The document’s top-level block key, if present.

pub fn set_document_block( &mut self, key: &str, block: Option<Value>, coalesce_key: Option<&str>, )

Replace (or, with None, remove) top-level block key as a USER edit: snapshotted for undo. coalesce_key groups a typing run into one step, namespaced by the block so a run in one never swallows another’s.

pub fn set_document_block_no_undo(&mut self, key: &str, block: Option<Value>)

Self::set_document_block with no undo step.

Trait Implementations

impl Clone for History

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for History

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

Formats the value using the given formatter.

impl Default for History

fn default() -> Self

Returns the “default value” for a type.