- plugin-architecture.md: new "Entity class display labels (API v10)"
section documenting the split (stable identity keys in XDATA, display
labels in the plugin declaration), the live-loaded-plugin gating (missing,
disabled, cap-excluded, failed, removed, or dead → bare native type), the
"<Label> (<Native>)" display rule, that raw schema fields (`type`,
`dxf_name`, `record_type`) and LIST are unchanged, and that the label is
display-only. `plugin.toml` deliberately does not carry the table: it is
the pre-load discovery file and labels must activate on live manifests.
- Template v2 demonstrates the whole convention: declares
`SURVEY-CLASS:POINT -> "Survey Point"` and stamps the identity key in
MARK_FIRST_SURVEY_POINT, so marked points show as "Survey Point (Point)"
while the plugin is loaded. plugin.toml's api_version is bumped to 10 (keep
in sync with ApiVersion::CURRENT) with a NOTE on where the class table
lives. DESIGN.md documents the flow.
- Template v2's stale `acadrust` pin (8a28c21, predating the host's codec
bump to 278c49a) is realigned with the host's pin: without it the template
no longer compiles on main — its `acadrust::EntityType` and the host
re-exports are distinct types when the revisions disagree (verified the
same four type errors occur before and after this feature's template edit).
- changelogs/unreleased.md entry (Plugins section).
Resolve entities' XDATA class-identity keys through the live plugin manager
(new `src/plugin/entity_labels.rs`) and qualify display types as
"<Label> (<Native>)" wherever the bare native type is shown today.
- The single-entity Properties panel title (and the node graph, which shares
the same computation) becomes e.g. "Linear Element (Line)". Host-owned
classifications (xref, dynamic constraints, underlays, surfaces) keep the
native parenthesized part, so nothing they tell the user is lost.
- The records API's `entities` collection: `display_type` carries the
qualified label; the raw `type` / `record_type` fields stay native so
existing scripts, type filters, and by-type grouping keep working.
- The automation entity summary gains a `display_type` field with the same
semantics; `type` stays raw. Exposed by `query`, `user_select` sessions,
and `get_selection`.
Semantics: the identity (a stable class KEY like "CVIFC-CLASS:LINE") lives
in the entity's XDATA and round-trips the drawing; the display LABELS live
in the declaring plugin's manifest. Keys only — no display text is ever
written to the file, and the label never governs behavior (display-only: it
does not affect snapping, selection, filtering, or grouping). Gating rides
live manager state at query time, so without a loaded declaring plugin every
surface here is byte-identical to today, immediately after any reopen, with
no re-assert pass. The command-line LIST output deliberately stays on the raw
dxf name. An app id claimed by more than one loaded plugin resolves through
the first-loaded declaration and debug-logs the ignored duplicate; a
prefix-only value, an unknown key, or an empty label mapping fall back to
the native type.
Tests: resolver core (known key, foreign app ignored, record without an
identity value ignored, prefix-only / unknown key / empty label fallback,
duplicate app id first-wins), the empty-manager gating end-to-end through
`with_manager`, the "<Label> (<Native>)" form, and the byte-identical
fallbacks asserted at the panel, records, and query layers for entities
stamped with a perfect identity record.
Plugins can now declare the entity classes they identify via XDATA, and the
host resolves them to display-only type labels while the declaring plugin is
loaded.
- Append `BuiltinPlugin::entity_classes()` (a guarded trailing vtable slot,
the same additive pattern as `on_load` in v5) returning a &'static
`EntityClasses { app_id, class_prefix, labels }`. The static
`PluginManifest` struct is deliberately untouched: older cdylibs share it
by pointer and its layout is frozen ABI since v1, so adding a field would
read past their allocation.
- `OwnedEntityClasses` travels on the registered manifest as
`OwnedPluginManifest.entity_classes` with `#[serde(default)]`, so manifests
serialized before the field keep decoding (older runners tolerate it
both ways).
- The runner folds the declaration into the GetManifest registration only
when the loaded cdylib's exported `ocs_plugin_api_version` symbol reports
>= 10 — an older binary's vtable predates the slot, so it is never called;
its entities simply keep their native type names.
- `PluginManager::entity_class_declarations` exposes the live set, filtered
to alive, non-disabled plugins in load order. The registered manifests are
the only source and nothing is cached: not installed, disabled,
cap-excluded (`OCS_PLUGIN_MAX_API_VERSION`), failed at load, removed, or a
dead process all contribute nothing.
- Embedded version info `api_version` follows the bump to 10;
`API_VERSION_MIN_SUPPORTED` stays 3.
Tests: runner fold (v10 folds, pre-v10 skipped, `entity_classes()` panic is
contained and reported), manager filtering (disabled / dead / undeclaring
skipped; declarations disappear once the process dies — verified with a real
killed child), bincode registration round-trip, and older-manifest serde
default.
Close the no-load-callback gap: on_notification was a dead dispatch sink —
a plugin had no way to learn that the active document changed, the selection
changed, or that a document opened, so runtime designations could not be
re-seeded after a load.
Dispatch the existing plain variants at the fingerprint-guarded boundaries
the v4 bridge already uses: DocumentChanged (the active tab's settled
geometry epoch) and SelectionChanged (the selection set) leave through
BuiltinPlugin::on_notification at the post-message boundary — after the
mutation settles and pending history scopes closed, never mid-undo or
mid-pick — and at the automation post-op boundary. Plugin-initiated writes
publish immediately after settling, like the drawing-changed event; the
boundary fingerprint guard deduplicates.
Add the additive HostNotification::DocumentOpened { tab_id } variant
(discriminant 10, the counterpart of DocumentTabClosed): fired exactly once
per whole-document install — file open, template new, system open — keyed on
a new per-tab document generation, so an edit can never repeat it and a
reload fires it once. The API version stays v9 (the bump is unreleased).
Write semantics for handlers, tested and documented: a handler may call
HostApi write methods through the same session (set_reference_only at
minimum); its write bumps the epoch, the next boundary notifies once more,
and because re-marking already-designated geometry is a documented no-op —
no epoch bump, no undo step, no publish — the loop terminates. History
(undo/redo) replay itself emits nothing; the boundary is the only channel.
No Python mapping, like the rest of this increment.
Per the upstream review of the XDATA-based storage: the host no longer writes
its own state into the saved file. The marker record under the host-owned OCS
APPID, the on-first-use APPID registration and the verbatim-EED rewrite
handling are removed; the single source of truth is a scene-scoped in-memory
set of entity handles (Scene::reference_only) that dies with the drawing tab,
so a reopened file starts undesignated and the owning plugin re-marks on the
document-opened notification.
All behaviour sites are unchanged, driven by the set: the wire stamp moves
from an XDATA read to a set lookup threaded through the tessellation
pipelines (tessellate_entity and the dimension text path take the handle set
as a plain parameter), and the pick filters, selection retains and
update/erase refusals read Scene::is_reference_only.
Undo keeps the entity-write contract: set mutations are recorded as explicit
first-touch before/after values on each history delta (the parametric-
constraints channel pattern). A designation inside a plugin push_undo scope
joins it, a scope-less change is one step of its own, an idempotent re-mark
records nothing, erasing a designated entity drops the set entry with the
entity, and undo/redo restores entity and designation together.
The round-trip test is inverted: reference_only_designation_is_not_written_
to_dwg_or_dxf now asserts the marker appears in neither format's bytes, that
no OCS APPID or marker record survives a reload, and that the designation
stays live in memory.
Adds a 'Usage from a plugin' subsection to the v9 section: build + designate
inside one push_undo scope; refresh in place via clone -> edit -> replace
(the designation travels with the entity); refusal and idempotency rules;
and the snapshot-path note that out-of-process plugins resolve entities by
iterating document().entities() (a received DocumentSnapshot does not serve
get_entity lookups).
Document the designation in the host-model capability table and its own
section, and record the increment in the completion-plan ledger with the
storage decision, the behaviour split and the test evidence.
Host side of HostApi::set_reference_only: plugin-owned display geometry that
renders and snaps normally but must not be edited or picked by the person at
the screen, while the owning plugin keeps full write access through the host.
- Storage: a human-readable marker value in an XDATA record under the
host-owned OCS APPID (registered on first use; foreign values survive
verbatim; stale verbatim DWG EED is dropped on rewrite), so the flag
round-trips DWG and DXF with the entity and cannot collide with plugin
APPID namespaces.
- Grips: refresh_selected_grips yields none for a reference-only entity and
an active grip edit on a newly designated target is cancelled like a
locked-layer one.
- Picking: a reference-only wire flag extends the snap_only skips in every
hit test, so a click passes through to the editable entity underneath, and
box, window, lasso, fence and select-all gathers skip the designation;
fills, solids and instanced meshes are excluded through the shared
candidate handle set.
- Write policy: built-in user paths treat a reference-only entity like a
locked-layer one (Scene::update_entity / update_entities refuse,
erase_entities skips), while the plugin-owned variants
(update_entity_plugin / erase_entities_plugin, mirroring the
remove_entities editor split) and the whole HostSession surface write
through. The MCP entities read exposes a top-level reference_only boolean
and set_properties refuses with the reference_only failure code.
- Undo: the entity-write contract - a change joins a plugin-opened push_undo
scope, a scope-less change is one undo step of its own, refusals and
idempotent re-marks record nothing.
- Known limit: entities nested inside block instances (the block cache
rebuilds instance wires without the flag).
Evidence: marking_flags_and_unmarking_clears,
foreign_values_under_the_host_app_id_survive, other_apps_are_untouched,
reference_only_refusals_record_no_undo_step,
reference_only_designation_composes_undo_like_entity_writes,
reference_only_survives_dxf_and_dwg_round_trips,
user_paths_refuse_and_plugin_paths_write_reference_only_entities,
select_all_visible_skips_reference_only_entities,
clicks_pass_through_reference_only_wires,
box_selections_skip_reference_only_wires,
entities_records_expose_the_reference_only_designation.
The HostApi gains set_reference_only(handle, reference_only): a plugin can
designate display geometry it owns and refreshes. The entity renders like any
other, but the built-in edit paths treat it like an entity on a locked layer,
while the owning plugin keeps full write access (update, erase, XDATA).
- Appended at the trait tail with a refusing default so plugins keep compiling
against older hosts; the loader gate range is untouched.
- IPC: SetReferenceOnly / SetReferenceOnlyResult round-trip through the
shared dispatch, the V3 client and the V4 client, with the shared document
cache invalidated on success.
- build.rs version_info and manifest API_VERSION bumped to 9 in lockstep.
- Evidence: reference_only_request_and_response_roundtrip (bincode round-trip
of the request and both response payloads).
HostSession::update_entity, update_entities_transaction and remove_entity mutate entities and republish the document view, but never rebuild the app-side selection caches the way the built-in edit paths do. A selected entity updated by a plugin kept its cached grip markers at their pre-edit positions until the next real selection event; regen did not help and HostApi::set_selection cannot work around it (it bypasses the grip cache).
Refresh the grip cache for the session tab after a successful update_entity / update_entities_transaction / remove_entity, mirroring the built-in ERASE path and the other editors, so a plugin-driven edit keeps the cached grips on the refreshed geometry. A session targeting a background tab leaves the active tab cache untouched (found by the civil plugin manual QA, 2026-10-12).
The informational clippy job fails on two pre-existing literals
(also failing on main, surfaced on this PR's merge): the trim
tangency test's angle list used 3.14 where pi was meant — use the
constant; the point-cloud light-direction fixture in render.rs uses
a hand-tuned 0.318 component that only looks like 1/pi — keep the
tuned value and allow the lint on that statement.
The internal per-call push_undo fractured plugin-composed operations:
history has no nested scopes, so each push finished the plugin's
still-pending scope and opened its own — an operation of several
writes became several undo steps and the plugin's label was lost
(measured: 3 creates + update + delete in one scope = 5 steps).
Follow the entity-write contract instead: a mutation inside a
plugin-opened push_undo scope joins it, so the whole operation is a
single undo step under the plugin's label; a scope-less mutation opens
and finishes its own scope, keeping one undo step per call; refusals
record no undo step in either regime. Document the contract on the
trait methods and the host docs; the composition experiment becomes
the permanent xrecord_writes_join_a_plugin_initiated_undo_scope test.
Add create/read/update/delete/list for XRecord objects under
named-object-dictionary paths to the plugin HostApi, with five additive
PluginRequest/PluginResponse variants, dispatch through the shared
handler, in-process HostSession methods and both out-of-process proxies.
- dictionary paths walk from the NOD root; create seeds missing
dictionaries (ensure_image_dictionary bootstrap) and refuses existing
names; update refuses missing ones; refusals precede the undo step
- entry group codes validated (1..=369, never 5/105); payload content is
the plugin's own
- each mutating call is one undo step: the pending history snapshot
restores the objects map byte-exactly, auto-created dictionaries
included (tested)
- typed entries survive DWG and DXF write/reload round-trips (tested);
update drops verbatim raw bytes so saves emit the new content
- bump API_VERSION 7 -> 8 with the build.rs version_info in lockstep,
mirroring the v7 addition; MIN_SUPPORTED stays 3
- Drop crates/ocs_doc_api from workspace and host dependency.
- Remove src/app/doc_api.rs and its module declaration.
- Strip DocApi v2 undo/dispatch plumbing from HostSession.
- Remove HostApi::doc_api_dispatch default method.
- Remove PluginRequest::DocApiRequest / PluginResponse::DocApiResponse.
- Revert plugin API version from 6 back to 5.
Delete the thin re-export file; src/app/doc_api.rs now uses ocs_doc_api::convert
directly (use ocs_doc_api::convert + convert::* call sites). Remove the
mod doc_api_convert registration from src/app/mod.rs.
The conversion logic already lives in the crate (src/convert.rs) from the prior
move; the shim was redundant. 623 host lib + 38 doc_api tests green.
Move the 503-line host-independent entity-conversion module (acadrust EntityType
<-> DTO conversions, transform_entity_geometry, entity_to_profile_curves,
bulge_arc_segment, entity_bounds, entity_kind_name, points_aabb) from
src/app/doc_api_convert.rs into crates/ocs_doc_api/src/convert.rs (host feature).
The host file is now a thin re-export (pub use ocs_doc_api::convert::*) so all
existing crate::app::doc_api_convert::* paths keep working unchanged. Zero
coupling risk (the module only touches acadrust + crate DTOs).
623 host lib + 8 crate + 3 consistency green.
Replace the mermaid flowchart (hard to read raw) with a clean ASCII/text diagram
tracing the same flow from the single source of truth (spec/entities.toml +
layouts.json) through codegen, facade, wire, transport, executor, and the host
backend/Scene, plus a layer-by-layer legend.
- layouts.json: append the 6 missing ops (CreateDimensionRadius/Diameter/Angular,
CreateAttributeDefinition, CreateTable, CreateDimensionAngular2Ln); regenerate
binding_schema.json + api_reference.md wire vocabulary (all 28 ops).
- Helix bounds: bound the evaluated spline control polygon (was a degenerate
single-start-point AABB).
- points_aabb: empty -> Geometry::Empty('entity has no points to bound'), not
UnknownId (the entity exists; don't misclassify as stale/deleted).
- mass_properties: accuracy-first fine tessellation + graceful degradation to the
approximate meshes.metrics value when the cold-tess budget is exhausted (large
distinct-solid batches no longer hard-fail).
- IMPLEMENTATION.md: Volume/Centroid rows + accuracy paragraph + test count (618)
consistent with the final design.
- 618 host lib + 8 crate + 3 consistency green.
- mass_properties: query path now uses fine mesh_body(0.1, 1e-4) for near-analytic
volume/centroid; the render-mesh metrics cache (coarse display LOD) no longer
shadows query accuracy. Memoized per (handle, epoch); cold-tess budget kept.
- IMPLEMENTATION.md: accuracy item done.
- Test accurate_volume_centroid_sphere_and_cube (sphere within 0.5% of 4/3*pi*r^3,
centroid at centre, cube exact) -> 617 host lib green.
The loft/attributes/viewport mock methods were appended after the impl block's
closing brace, orphaning add_vertex..finalize_op and leaving a duplicate brace.
Move the impl close to the true end in both tests/mock_backend.rs and
examples/common/mod.rs. Crate tests (8) + examples compile green again.
Add tests/spec_wire_consistency.rs: (a) every op/query name in spec/entities.toml
maps to an existing Operation/Query variant; (b) both enums are append-only
relative to a recorded variant-order baseline (bincode discriminant stability).
Adds toml to dev-dependencies. 3 tests green.
Add Arc/Ellipse/Spline/Ray/XLine arms to the test + example mock add_curve
kind matching and the example curve_bounds, so the crate's unit tests and
examples compile against the Phase 2 curve families.
Tightens the rustc compatibility gate so that whitespace-normalised
version strings are compared token-by-token. This prevents a corner case
where 'rustc 1.98.0' and 'rustc1.98.0' would be considered equal.
OpenCADStudio/plugins#901 (comment)
- Add BuiltinPlugin::on_load(&mut self, host: &mut dyn HostApi) with a default
no-op implementation so existing plugins remain source-compatible.
- Invoke on_load once for V4 plugins immediately after the runner connects
and before entering the request loop, giving plugins a HostApi surface to
cache plugin_request_sender() or set up worker threads before any dispatch.
- V2/V3 plugins are unchanged: HostApi is only available during dispatch.
OpenCADStudio/plugins#901 (comment)
- Add HostApi::document_path(tab_id) returning Option<PathBuf>.
- Add PluginRequest::DocumentPath and PluginResponse::DocumentPath for
out-of-process plugins.
- Implement the request in the IPC server and in both V3/V4 plugin-side
HostApi proxies.
- Implement HostSession::document_path by looking up the tab by id and
returning its current_path.
OpenCADStudio/plugins#901
- Record the host's rustc --version output in the embedded version_info.json.
- Add rustc_version/rustc_declared/rustc_compatible to plugin manifests and
release metadata, mirroring the existing acadrust gate.
- Reject API v4+ plugins whose declared rustc differs from the host, with a
clear one-line error message.
- Propagate the rustc gate through the marketplace, install flow, and UI.
- Update plugin architecture docs to describe the new ABI metadata.
The out-of-process plugin design proposal in REPORT.md has been
implemented and evolved to API v4. The current architecture is
documented in ARCHITECTURE.md. REPORT.md is unreferenced and no
longer needed; its content remains in git history for reference.
- Add HostNotification::SelectionChangedV4 { tab_id, handles } with discriminant 7
- Broadcast active-tab selection changes at update() and automation_op boundaries
- Use stable order-independent signature to avoid spurious hover notifications
- Clear Scene selection in automation new/open to avoid stale handles
- Add crates/ocs_plugin_api/ARCHITECTURE.md and module-level rustdoc
- Cross-link README.md and docs/plugin-architecture.md
- Fix test env race with shared ENV_LOCK and EnvVarGuard helpers
- API v2/v3 plugins bypass the acadrust gate entirely, preserving backwards compatibility.
- Marketplace repo-level policy only affects undeclared v4+ releases.
- Local load_at_startup only enforces the gate for v4+ plugins.
- Add host_acadrust_source and source-hash comparison helpers to ocs_plugin_api.
- Track acadrust_source and acadrust_declared in ExternalPlugin/ReleaseInfo.
- Apply repo-level policy: if any release in a repo declares acadrust_source, undeclared v4+ releases from that repo are incompatible.
- Preserve API v2/v3 backwards compatibility: legacy undeclared releases stay installable.
- Update Plugin Manager UI to only offer compatible releases and show 'acadrust mismatch' status.
- Drop acadrust_version from gate logic; only acadrust_source is required.
PluginManager::broadcast_notification was fanning out host notifications to every loaded plugin. Only V4 plugin processes can receive host->plugin notifications; V2/V3 plugins correctly rejected them with notify_plugin requires V4 protocol.
Add PluginProcess::is_v4() and skip non-V4 plugins in broadcast_notification so V4 document snapshot notifications only go to V4-capable plugins. Fixes repeated console errors for Example, Land Survey and V2 Compat.
- Run Plugin Manager release fetches on OS threads so they execute in
parallel instead of serialising on the async executor.
- Reduce V4Connection shutdown poll from 3s to 100ms; the runner is killed
and reaped without blocking host shutdown.
- Add PluginManager::remove and PluginProcess::shutdown_and_wait so
uninstall can stop the runner before deleting files, fixing Windows
access-denied errors on plugin removal.
- Rebuild ribbon immediately after uninstall so the tab disappears.
Sebastian