Merge pull request #80 from mf4633/feature/plugin-host

Add plugin host (Phase 1)

src/app/cmd_result.rs

@@ -251,6 +251,11 @@ impl OpenCADStudio {
             }
             CmdResult::ReplaceMany(replacements, additions) => {
                 let label = self.history_label_from_active_cmd(i, "FILLET");
+                let was_catchment = self
+                    .tabs[i]
+                    .active_cmd
+                    .as_ref()
+                    .is_some_and(|c| c.name() == "SS_CATCHMENT");
                 self.push_undo_snapshot(i, label);
                 for (handle, entities) in replacements {
                     self.tabs[i].scene.erase_entities(&[handle]);
@@ -265,6 +270,10 @@ impl OpenCADStudio {
                 self.tabs[i].scene.clear_preview_wire();
                 self.tabs[i].active_cmd = None;
                 self.tabs[i].snap_result = None;
+                if was_catchment {
+                    self.command_line
+                        .push_info("Catchment tagged successfully.");
+                }
                 self.refresh_properties();
             }
             CmdResult::ReplaceEntity(handle, new_entities) => {

src/app/commands.rs

@@ -28,6 +28,10 @@ impl OpenCADStudio {
             return Task::done(Message::OpenPathPicked(Some((path, size))));
         }
 
+        if crate::plugin::try_dispatch(self, i, cmd) {
+            return Task::none();
+        }
+
         match cmd {
             "NEW" => return Task::done(Message::TabNew),
             "OPEN" => return Task::done(Message::OpenFile),

src/app/document.rs

@@ -9,6 +9,8 @@ use crate::ui::{LayerPanel, PropertiesPanel};
 use acadrust::tables::Ucs;
 use acadrust::{CadDocument, Handle};
 use iced;
+use std::any::{Any, TypeId};
+use std::collections::HashMap;
 use std::path::PathBuf;
 
 // ── Dynamic input ──────────────────────────────────────────────────────────
@@ -100,6 +102,8 @@ pub(super) struct DocumentTab {
     /// of the model-space shader. The scene is still constructed so the
     /// rest of the code can treat it as a normal tab when reading.
     pub(super) is_start: bool,
+    /// Per-plugin document state (`plugin::BuiltinPlugin` manifest id → state).
+    pub(super) plugin_state: HashMap<&'static str, Box<dyn Any + Send + Sync>>,
 }
 
 impl DocumentTab {
@@ -146,9 +150,41 @@ impl DocumentTab {
             active_mleader_style: "Standard".to_string(),
             last_synced_camera_gen: 0,
             is_start: false,
+            plugin_state: HashMap::new(),
         }
     }
 
+    pub(super) fn plugin_state<T: Any + Send + Sync + 'static>(
+        &self,
+        plugin_id: &'static str,
+        _type_id: TypeId,
+    ) -> Option<&T> {
+        self.plugin_state.get(plugin_id)?.downcast_ref::<T>()
+    }
+
+    pub(super) fn plugin_state_mut<T: Any + Send + Sync + 'static>(
+        &mut self,
+        plugin_id: &'static str,
+        _type_id: TypeId,
+    ) -> Option<&mut T> {
+        self.plugin_state.get_mut(plugin_id)?.downcast_mut::<T>()
+    }
+
+    pub(super) fn ensure_plugin_state<T: Any + Send + Sync + 'static>(
+        &mut self,
+        plugin_id: &'static str,
+        init: impl FnOnce() -> T,
+    ) -> &mut T {
+        if !self.plugin_state.contains_key(plugin_id) {
+            self.plugin_state.insert(plugin_id, Box::new(init()));
+        }
+        self.plugin_state
+            .get_mut(plugin_id)
+            .expect("just inserted")
+            .downcast_mut::<T>()
+            .expect("plugin_id type mismatch")
+    }
+
     /// Welcome / Start tab. Carries a dummy Scene so the rest of the app
     /// can read tab state uniformly; the viewport renderer detects
     /// `is_start` and shows a welcome page instead.

src/app/mod.rs

@@ -1,5 +1,6 @@
 mod cmd_result;
 mod commands;
+pub mod plugin_host;
 mod document;
 mod expr_eval;
 mod helpers;
@@ -1493,6 +1494,22 @@ impl OpenCADStudio {
         app
     }
 
+    #[cfg(test)]
+    pub(crate) fn new_for_test() -> Self {
+        Self::new()
+    }
+
+    #[cfg(test)]
+    pub(crate) fn command_history_info(&self) -> Vec<String> {
+        use crate::ui::command_line::EntryKind;
+        self.command_line
+            .history
+            .iter()
+            .filter(|e| e.kind == EntryKind::Info)
+            .map(|e| e.text.clone())
+            .collect()
+    }
+
     /// Boot function for `iced::daemon`: returns initial state plus a task that
     /// opens the primary application window.
     fn boot() -> (Self, Task<Message>) {

src/app/plugin_host.rs

@@ -0,0 +1,94 @@
+// HostSession — plugin-facing API implemented inside `app` (private field access).
+
+use std::any::{Any, TypeId};
+
+use acadrust::{CadDocument, EntityType, Handle};
+
+use super::OpenCADStudio;
+use crate::command::CadCommand;
+
+/// Session adapter: one active document tab, command line, undo.
+pub(crate) struct HostSession<'a> {
+    app: &'a mut OpenCADStudio,
+    tab: usize,
+}
+
+impl<'a> HostSession<'a> {
+    pub(crate) fn new(app: &'a mut OpenCADStudio, tab: usize) -> Self {
+        Self { app, tab }
+    }
+
+    pub fn tab_index(&self) -> usize {
+        self.tab
+    }
+
+    pub fn document(&self) -> &CadDocument {
+        &self.app.tabs[self.tab].scene.document
+    }
+
+    pub fn document_mut(&mut self) -> &mut CadDocument {
+        &mut self.app.tabs[self.tab].scene.document
+    }
+
+    pub fn entities(&self) -> impl Iterator<Item = &EntityType> {
+        self.document().entities()
+    }
+
+    pub fn entities_mut(&mut self) -> impl Iterator<Item = &mut EntityType> {
+        self.document_mut().entities_mut()
+    }
+
+    pub fn add_entity(&mut self, entity: EntityType) -> Handle {
+        self.app.tabs[self.tab].scene.add_entity(entity)
+    }
+
+    pub fn bump_geometry(&mut self) {
+        self.app.tabs[self.tab].scene.bump_geometry();
+    }
+
+    pub fn push_undo(&mut self, label: &str) {
+        self.app.push_undo_snapshot(self.tab, label);
+    }
+
+    pub fn set_dirty(&mut self) {
+        self.app.tabs[self.tab].dirty = true;
+    }
+
+    pub fn push_info(&mut self, msg: &str) {
+        self.app.command_line.push_info(msg);
+    }
+
+    pub fn push_output(&mut self, msg: &str) {
+        self.app.command_line.push_output(msg);
+    }
+
+    pub fn push_error(&mut self, msg: &str) {
+        self.app.command_line.push_error(msg);
+    }
+
+    pub fn set_active_command(&mut self, cmd: Box<dyn CadCommand>) {
+        self.app.tabs[self.tab].active_cmd = Some(cmd);
+    }
+
+    pub fn plugin_state<T: Any + Send + Sync + 'static>(
+        &self,
+        plugin_id: &'static str,
+    ) -> Option<&T> {
+        self.app.tabs[self.tab].plugin_state(plugin_id, TypeId::of::<T>())
+    }
+
+    pub fn plugin_state_mut<T: Any + Send + Sync + 'static>(
+        &mut self,
+        plugin_id: &'static str,
+    ) -> Option<&mut T> {
+        self.app.tabs[self.tab].plugin_state_mut(plugin_id, TypeId::of::<T>())
+    }
+
+    pub fn ensure_plugin_state<T: Any + Send + Sync + 'static>(
+        &mut self,
+        plugin_id: &'static str,
+        init: impl FnOnce() -> T,
+    ) -> &mut T {
+        self.app.tabs[self.tab].ensure_plugin_state(plugin_id, init)
+    }
+}

src/app/update.rs

@@ -2386,6 +2386,11 @@ impl OpenCADStudio {
                         .as_ref()
                         .map(|c| c.needs_entity_pick())
                         .unwrap_or(false);
+                    let needs_structure = self.tabs[i]
+                        .active_cmd
+                        .as_ref()
+                        .map(|c| c.needs_structure_point_pick())
+                        .unwrap_or(false);
                     let is_gathering = self.tabs[i]
                         .active_cmd
                         .as_ref()
@@ -2396,7 +2401,7 @@ impl OpenCADStudio {
                         .as_ref()
                         .map(|c| c.needs_tangent_pick())
                         .unwrap_or(false);
-                    self.tabs[i].snap_result = if needs_entity || is_gathering {
+                    self.tabs[i].snap_result = if needs_entity || is_gathering || needs_structure {
                         None
                     } else if needs_tan {
                         self.snapper.snap_tangent_only(
@@ -2468,6 +2473,39 @@ impl OpenCADStudio {
                     };
                     self.tabs[i].last_cursor_world = effective;
                     self.tabs[i].last_cursor_screen = p_full;
+
+                    // C3D-style orange object snap (plugin commands implement resolve_object_pick).
+                    if needs_structure {
+                        use crate::snap::{SnapResult, SnapType};
+                        let pick = self.tabs[i].active_cmd.as_ref().and_then(|c| {
+                            c.resolve_object_pick(
+                                &self.tabs[i].scene,
+                                effective.x as f64,
+                                effective.y as f64,
+                            )
+                        });
+                        if let Some(pick) = pick {
+                            let world =
+                                glam::Vec3::new(pick.x as f32, pick.y as f32, effective.z);
+                            let ndc = view_proj.project_point3(world);
+                            let screen = iced::Point::new(
+                                (ndc.x + 1.0) * 0.5 * bounds.width,
+                                (1.0 - ndc.y) * 0.5 * bounds.height,
+                            );
+                            self.tabs[i].snap_result = Some(SnapResult {
+                                world,
+                                screen,
+                                snap_type: SnapType::ObjectPick,
+                                tangent_obj: None,
+                            });
+                            if let Some(cmd) = self.tabs[i].active_cmd.as_mut() {
+                                cmd.set_acquisition_hint(Some(pick.label));
+                            }
+                        } else if let Some(cmd) = self.tabs[i].active_cmd.as_mut() {
+                            cmd.set_acquisition_hint(None);
+                        }
+                    }
+
                     // Snap glyph is positioned in canvas space; shift the
                     // tile-local snap screen point back to the full canvas.
                     if let Some(s) = self.tabs[i].snap_result.as_mut() {
@@ -2475,16 +2513,42 @@ impl OpenCADStudio {
                         s.screen.y += tile_b.y;
                     }
 
-                    let mut previews = if needs_entity {
+                    let mut previews = if needs_structure {
+                        let mut p = self.tabs[i]
+                            .active_cmd
+                            .as_ref()
+                            .map(|c| c.object_pick_hover_previews(&self.tabs[i].scene, effective))
+                            .unwrap_or_default();
+                        if let Some(cmd) = self.tabs[i].active_cmd.as_mut() {
+                            p.extend(cmd.on_preview_wires(effective));
+                        }
+                        p
+                    } else if needs_entity {
                         let hover_handle =
                             scene::hit_test::click_hit(p, &all_wires[..], view_proj, bounds)
                                 .and_then(|s| Scene::handle_from_wire_name(s))
                                 .unwrap_or(acadrust::Handle::NULL);
-                        self.tabs[i]
+                        let mut p = self.tabs[i]
                             .active_cmd
                             .as_mut()
                             .map(|c| c.on_hover_entity(hover_handle, effective))
-                            .unwrap_or_default()
+                            .unwrap_or_default();
+                        if !hover_handle.is_null() {
+                            if let Some(cmd) = self.tabs[i].active_cmd.as_ref() {
+                                p.extend(cmd.entity_pick_acquire_previews(
+                                    &self.tabs[i].scene,
+                                    hover_handle,
+                                ));
+                            }
+                            if let Some(cmd) = self.tabs[i].active_cmd.as_mut() {
+                                if let Some(hint) =
+                                    cmd.entity_pick_acquire_hint(hover_handle)
+                                {
+                                    cmd.set_acquisition_hint(Some(hint));
+                                }
+                            }
+                        }
+                        p
                     } else {
                         self.tabs[i]
                             .active_cmd
@@ -2946,6 +3010,36 @@ impl OpenCADStudio {
                     };
 
                     let result = if self.tabs[i]
+                        .active_cmd
+                        .as_ref()
+                        .map(|c| c.needs_structure_point_pick())
+                        .unwrap_or(false)
+                    {
+                        let pick = self.tabs[i].active_cmd.as_ref().and_then(|c| {
+                            c.resolve_object_pick(
+                                &self.tabs[i].scene,
+                                world_pt.x as f64,
+                                world_pt.y as f64,
+                            )
+                        });
+                        if let Some(pick) = pick {
+                            let center = glam::Vec3::new(pick.x as f32, pick.y as f32, world_pt.z);
+                            let result = self.tabs[i].active_cmd.as_mut().map(|c| {
+                                c.on_structure_pick(pick.handle, center)
+                            });
+                            self.command_line
+                                .push_info(&format!("{} acquired.", pick.label));
+                            result
+                        } else {
+                            let msg = self.tabs[i]
+                                .active_cmd
+                                .as_ref()
+                                .map(|c| c.object_pick_miss_message())
+                                .unwrap_or("No object near click.");
+                            self.command_line.push_error(msg);
+                            None
+                        }
+                    } else if self.tabs[i]
                         .active_cmd
                         .as_ref()
                         .map(|c| c.needs_entity_pick())
@@ -2956,6 +3050,23 @@ impl OpenCADStudio {
                         let hit = scene::hit_test::click_hit(p, &all_wires2[..], vp_mat2, bounds)
                             .and_then(|s| Scene::handle_from_wire_name(s));
                         if let Some(handle) = hit {
+                            // Some commands (e.g. SS_CATCHMENT) need the entity
+                            // body before `on_entity_pick` can advance.
+                            let inject_first = self.tabs[i]
+                                .active_cmd
+                                .as_ref()
+                                .map(|c| c.inject_before_entity_pick())
+                                .unwrap_or(false);
+                            if inject_first {
+                                if let Some(entity) =
+                                    self.tabs[i].scene.document.get_entity(handle).cloned()
+                                {
+                                    if let Some(cmd) = self.tabs[i].active_cmd.as_mut() {
+                                        cmd.inject_picked_entity(entity);
+                                    }
+                                }
+                            }
+
                             let result = self.tabs[i]
                                 .active_cmd
                                 .as_mut()

src/command/mod.rs

@@ -7,9 +7,19 @@
 
 use crate::scene::hatch_model::HatchModel;
 use crate::scene::wire_model::WireModel;
+use crate::scene::Scene;
 use acadrust::{EntityType, Handle};
 use glam::Vec3;
 
+/// Domain object resolved under the cursor for C3D-style ObjectPick snapping.
+#[derive(Clone, Copy, Debug)]
+pub struct ObjectPickHit {
+    pub handle: Handle,
+    pub x: f64,
+    pub y: f64,
+    pub label: &'static str,
+}
+
 // ── Transform ─────────────────────────────────────────────────────────────
 
 /// A geometric transformation applied to existing entities.
@@ -271,6 +281,44 @@ pub trait CadCommand: Send {
         CmdResult::Cancel
     }
 
+    /// Point-click pick of domain objects (wire hit-test often misses small markers).
+    fn needs_structure_point_pick(&self) -> bool {
+        false
+    }
+
+    /// Resolve a domain object near `(x, y)` while `needs_structure_point_pick()` is active.
+    fn resolve_object_pick(&self, _scene: &Scene, _x: f64, _y: f64) -> Option<ObjectPickHit> {
+        None
+    }
+
+    /// Preview wires while hovering during object-point pick.
+    fn object_pick_hover_previews(&self, _scene: &Scene, _cursor: Vec3) -> Vec<WireModel> {
+        vec![]
+    }
+
+    /// Message when `resolve_object_pick` returns none on click.
+    fn object_pick_miss_message(&self) -> &'static str {
+        "No object near click."
+    }
+
+    /// Called when `needs_structure_point_pick()` is true and a structure is found near the click.
+    fn on_structure_pick(&mut self, _handle: Handle, _pt: Vec3) -> CmdResult {
+        CmdResult::Cancel
+    }
+
+    /// Extra acquisition previews during entity pick (besides `on_hover_entity`).
+    fn entity_pick_acquire_previews(&self, _scene: &Scene, _handle: Handle) -> Vec<WireModel> {
+        vec![]
+    }
+
+    /// Acquisition hint label during entity pick hover.
+    fn entity_pick_acquire_hint(&self, _handle: Handle) -> Option<&'static str> {
+        None
+    }
+
+    /// Hover label for C3D-style object acquisition (e.g. "Inlet" under cursor).
+    fn set_acquisition_hint(&mut self, _hint: Option<&str>) {}
+
     /// Called after `CmdResult::ReplaceEntity` is applied to the document.
     /// `old` is the erased handle; `new_handles` are the handles assigned to the replacement entities.
     /// Commands that stay active across replaces should update their internal snapshots here.
@@ -371,7 +419,13 @@ pub trait CadCommand: Send {
         self.on_point(hit)
     }
 
-    /// Called by update.rs after `on_entity_pick` to inject the cloned entity into commands
+    /// When true, `update.rs` injects the picked entity before calling
+    /// `on_entity_pick` (required when the pick handler reads injected state).
+    fn inject_before_entity_pick(&self) -> bool {
+        false
+    }
+
+    /// Called by update.rs to inject the cloned entity into commands
     /// that need to read/modify it (e.g. DIMTEDIT, MLEADERADD, MLEADERREMOVE).
     /// Default: no-op.
     fn inject_picked_entity(&mut self, _entity: acadrust::EntityType) {}

src/lib.rs

@@ -6,6 +6,7 @@ pub mod entities;
 pub mod io;
 pub mod linetypes;
 pub mod modules;
+pub mod plugin;
 pub mod patterns;
 pub mod scene;
 pub mod snap;

src/main.rs

@@ -10,6 +10,7 @@ mod entities;
 mod io;
 mod linetypes;
 mod modules;
+mod plugin;
 mod patterns;
 mod scene;
 mod snap;

src/modules/demo_plugin/dispatch.rs

@@ -0,0 +1,11 @@
+use crate::plugin::host::HostSession;
+
+pub fn handle(host: &mut HostSession<'_>, cmd: &str) -> bool {
+    match cmd {
+        "DP_HELLO" => {
+            host.push_info("Hello from demo_plugin (plugin host OK).");
+            true
+        }
+        _ => false,
+    }
+}

src/modules/demo_plugin/manifest.rs

@@ -0,0 +1,14 @@
+use crate::plugin::manifest::{ApiVersion, PluginManifest};
+
+pub const PLUGIN_ID: &str = "opencad.demo_plugin";
+
+pub static MANIFEST: PluginManifest = PluginManifest {
+    id: PLUGIN_ID,
+    name: "Demo Plugin",
+    version: "0.1.0",
+    description: "Minimal add-on for plugin-host integration tests",
+    api_version: ApiVersion::CURRENT,
+    ribbon_order: 99,
+    xdata_apps: &[],
+    command_prefixes: &["DP_"],
+};

src/modules/demo_plugin/mod.rs

@@ -0,0 +1,47 @@
+// Minimal in-tree add-on — validates plugin host on `feature/plugin-host`.
+
+pub mod dispatch;
+pub mod manifest;
+pub mod plugin;
+pub mod register;
+
+use crate::modules::{CadModule, IconKind, ModuleEvent, RibbonGroup, RibbonItem, ToolDef};
+
+inventory::submit!(crate::command::CommandRegistration {
+    names: &["DP_HELLO"]
+});
+
+pub struct DemoPluginModule;
+
+impl CadModule for DemoPluginModule {
+    fn id(&self) -> &'static str {
+        "demo_plugin"
+    }
+
+    fn title(&self) -> &'static str {
+        "Demo Plugin"
+    }
+
+    fn ribbon_groups(&self) -> Vec<RibbonGroup> {
+        vec![RibbonGroup {
+            title: "Smoke",
+            tools: vec![RibbonItem::LargeTool(ToolDef {
+                id: "DP_HELLO",
+                label: "Hello",
+                icon: IconKind::Glyph("★"),
+                event: ModuleEvent::Command("DP_HELLO".to_string()),
+            })],
+        }]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::plugin::all_ribbon_modules;
+
+    #[test]
+    fn ribbon_tab_is_registered() {
+        let titles: Vec<&str> = all_ribbon_modules().iter().map(|m| m.title()).collect();
+        assert!(titles.contains(&"Demo Plugin"), "tabs: {titles:?}");
+    }
+}

src/modules/demo_plugin/plugin.rs

@@ -0,0 +1,21 @@
+use crate::plugin::host::{BuiltinPlugin, HostSession};
+use crate::plugin::manifest::PluginManifest;
+
+use super::dispatch;
+use super::manifest;
+
+pub struct DemoPlugin;
+
+impl BuiltinPlugin for DemoPlugin {
+    fn manifest(&self) -> &'static PluginManifest {
+        &manifest::MANIFEST
+    }
+
+    fn ribbon(&self) -> Box<dyn crate::modules::CadModule> {
+        Box::new(super::DemoPluginModule)
+    }
+
+    fn dispatch(&self, host: &mut HostSession<'_>, cmd: &str) -> bool {
+        dispatch::handle(host, cmd)
+    }
+}

src/modules/demo_plugin/plugin.toml

@@ -0,0 +1,13 @@
+[plugin]
+id = "opencad.demo_plugin"
+name = "Demo Plugin"
+version = "0.1.0"
+description = "Minimal add-on for plugin-host integration tests"
+author = "Open CAD Studio contributors"
+license = "GPL-3.0-only"
+
+[opencad]
+api_version = 1
+ribbon_order = 99
+command_prefixes = ["DP_"]
+xdata_apps = []

src/modules/demo_plugin/register.rs

@@ -0,0 +1,7 @@
+use super::plugin::DemoPlugin;
+
+inventory::submit! {
+    crate::plugin::registry::PluginRegistration {
+        construct: || Box::new(DemoPlugin),
+    }
+}

src/modules/mod.rs

@@ -1,10 +1,13 @@
 // Module system — CadModule, ToolDef, RibbonGroup.
 //
-// To add a new module:
-//   1. Create `src/modules/my_name/` directory
+// To add a **core** ribbon tab (Home, View, …):
+//   1. Create `src/modules/my_name/` directory (no `plugin.toml`)
 //   2. Add `src/modules/my_name/mod.rs` implementing `CadModule` as `MyNameModule`
 //   3. Add `pub mod my_name;` below
-//   4. `cargo build` — module appears in the ribbon automatically
+//   4. `cargo build` — tab appears via build.rs registry
+//
+// To add an **add-on plugin** (Storm Sewer, …):
+//   See `docs/plugin-architecture.md` and copy `docs/plugin-template/`.
 //
 // Each module folder contains:
 //   - mod.rs       : module definition (ribbon groups + tool layout)
@@ -136,6 +139,7 @@ pub mod home;
 pub mod insert;
 pub mod model;
 pub mod layout;
+pub mod demo_plugin;
 pub mod manage;
 pub mod view;
 

src/plugin/host.rs

@@ -0,0 +1,17 @@
+// Plugin traits — HostSession lives in `app::plugin_host` (same-crate field access).
+
+pub(crate) use crate::app::plugin_host::HostSession;
+
+use crate::modules::CadModule;
+
+use super::manifest::PluginManifest;
+
+/// Add-on package entry point (phase 1: in-tree, in-process).
+///
+/// One `PluginRegistration` per package — ribbon tab, manifest, and command
+/// dispatch are owned here. See `docs/plugin-architecture.md`.
+pub trait BuiltinPlugin: Send + Sync {
+    fn manifest(&self) -> &'static PluginManifest;
+    fn ribbon(&self) -> Box<dyn CadModule>;
+    fn dispatch(&self, host: &mut HostSession<'_>, cmd: &str) -> bool;
+}

src/plugin/manifest.rs

@@ -0,0 +1,32 @@
+// Plugin identity and capability declaration.
+
+/// Host plugin API version. Bump when HostApi breaks compatibility.
+pub const API_VERSION: u32 = 1;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ApiVersion {
+    pub major: u32,
+}
+
+impl ApiVersion {
+    pub const CURRENT: Self = Self { major: API_VERSION };
+
+    pub fn is_compatible_with(host: ApiVersion) -> bool {
+        Self::CURRENT.major == host.major
+    }
+}
+
+/// Static metadata every plugin supplies at registration time.
+/// Keep fields in sync with `plugin.toml` beside the package.
+#[derive(Clone, Copy, Debug)]
+pub struct PluginManifest {
+    pub id: &'static str,
+    pub name: &'static str,
+    pub version: &'static str,
+    pub description: &'static str,
+    pub api_version: ApiVersion,
+    /// Sort key for add-on ribbon tabs (lower = further left among plugins).
+    pub ribbon_order: i32,
+    pub xdata_apps: &'static [&'static str],
+    pub command_prefixes: &'static [&'static str],
+}

src/plugin/mod.rs

@@ -0,0 +1,13 @@
+// Open CAD Studio plugin runtime (phase 1: built-in, in-process).
+//
+// Generic host only — no domain logic. See `docs/plugin-architecture.md`.
+// Domain plugins (e.g. storm_sewer) live under `src/modules/<name>/` and
+// register here via `inventory::submit!(PluginRegistration { … })`.
+
+pub mod host;
+pub mod manifest;
+pub mod registry;
+
+pub use registry::all_ribbon_modules;
+pub(crate) use host::BuiltinPlugin;
+pub(crate) use registry::try_dispatch;

src/plugin/registry.rs

@@ -0,0 +1,88 @@
+// Compile-time plugin registry via `inventory`.
+
+use super::host::{BuiltinPlugin, HostSession};
+use crate::app::OpenCADStudio;
+use crate::modules::{registry as core_registry, CadModule};
+
+pub struct PluginRegistration {
+    pub construct: fn() -> Box<dyn BuiltinPlugin>,
+}
+
+inventory::collect!(PluginRegistration);
+
+/// Construct every registered built-in plugin (once per process).
+pub fn all_plugins() -> Vec<Box<dyn BuiltinPlugin>> {
+    inventory::iter::<PluginRegistration>
+        .into_iter()
+        .map(|r| (r.construct)())
+        .collect()
+}
+
+/// Core ribbon tabs plus add-on tabs (sorted by `manifest.ribbon_order`).
+pub fn all_ribbon_modules() -> Vec<Box<dyn CadModule>> {
+    let mut core = core_registry::all_modules();
+    let mut addons: Vec<(i32, Box<dyn CadModule>)> = all_plugins()
+        .into_iter()
+        .map(|p| (p.manifest().ribbon_order, p.ribbon()))
+        .collect();
+    addons.sort_by_key(|(order, _)| *order);
+    core.extend(addons.into_iter().map(|(_, ribbon)| ribbon));
+    core
+}
+
+/// Try each plugin until one handles `cmd`. Returns true if handled.
+pub(crate) fn try_dispatch(app: &mut OpenCADStudio, tab: usize, cmd: &str) -> bool {
+    let mut host = HostSession::new(app, tab);
+    for plugin in all_plugins() {
+        if plugin.dispatch(&mut host, cmd) {
+            return true;
+        }
+    }
+    false
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::app::OpenCADStudio;
+    #[test]
+    fn discovers_registered_plugins() {
+        let plugins = all_plugins();
+        assert!(
+            !plugins.is_empty(),
+            "expected at least one PluginRegistration (demo_plugin)"
+        );
+        assert!(
+            plugins
+                .iter()
+                .any(|p| p.manifest().id == "opencad.demo_plugin"),
+            "demo_plugin missing; ids: {:?}",
+            plugins.iter().map(|p| p.manifest().id).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn addon_ribbon_tabs_merge_after_core() {
+        let titles: Vec<&str> = all_ribbon_modules().iter().map(|m| m.title()).collect();
+        assert!(titles.contains(&"Demo Plugin"), "ribbon tabs: {titles:?}");
+        let core = core_registry::all_modules();
+        assert_eq!(titles.len(), core.len() + all_plugins().len());
+    }
+
+    #[test]
+    fn try_dispatch_routes_demo_command() {
+        let mut app = OpenCADStudio::new_for_test();
+        assert!(try_dispatch(&mut app, 0, "DP_HELLO"));
+        let info = app.command_history_info();
+        assert!(
+            info.iter().any(|t| t.contains("demo_plugin") && t.contains("plugin host OK")),
+            "info history: {info:?}"
+        );
+    }
+
+    #[test]
+    fn unknown_plugin_command_falls_through() {
+        let mut app = OpenCADStudio::new_for_test();
+        assert!(!try_dispatch(&mut app, 0, "DP_NOPE"));
+    }
+}

src/scene/wire_model.rs

@@ -79,6 +79,9 @@ impl WireModel {
     pub const WHITE: [f32; 4] = [1.00, 1.00, 1.00, 1.0];
     pub const CYAN: [f32; 4] = [0.25, 0.85, 1.00, 1.0];
     pub const SELECTED: [f32; 4] = [0.15, 0.55, 1.00, 1.0];
+    /// Civil 3D-style object acquisition highlight (structure / catchment hover).
+    pub const PICK_HIGHLIGHT: [f32; 4] = [0.95, 0.50, 0.08, 1.0];
+    pub const PICK_HIGHLIGHT_DIM: [f32; 4] = [0.95, 0.50, 0.08, 0.45];
     /// Sentinel AABB that never rejects any snap query.
     pub const UNBOUNDED_AABB: [f32; 4] = [
         f32::NEG_INFINITY,

src/snap/mod.rs

@@ -30,6 +30,8 @@ pub enum SnapType {
     ApparentIntersection,
     Parallel,
     Grid,
+    /// C3D-style object acquisition (storm structure / network pick) — orange marker.
+    ObjectPick,
 }
 
 /// Ordered list used by the popup and snap engine.

src/ui/command_line.rs

@@ -56,7 +56,7 @@ pub struct HistoryEntry {
     pub pinned: bool,
 }
 
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub enum EntryKind {
     Command,
     Output,

src/ui/overlay.rs

@@ -500,18 +500,37 @@ impl canvas::Program<Message> for SelectionCanvas {
 
         // ── Snap marker ───────────────────────────────────────────────────
         if let Some((sp, snap_type)) = self.snap {
-            let yellow = Color {
-                r: 1.0,
-                g: 0.9,
-                b: 0.1,
-                a: 1.0,
+            let (r, g, b) = if snap_type == SnapType::ObjectPick {
+                (0.95_f32, 0.50, 0.08) // C3D-style orange object snap
+            } else {
+                (1.0, 0.9, 0.1) // classic yellow OSNAP
             };
+            let marker = Color { r, g, b, a: 1.0 };
             let stroke = canvas::Stroke {
-                width: 1.5,
-                style: canvas::Style::Solid(yellow),
+                width: if snap_type == SnapType::ObjectPick { 2.0 } else { 1.5 },
+                style: canvas::Style::Solid(marker),
                 ..Default::default()
             };
             match snap_type {
+                SnapType::ObjectPick => {
+                    // Target box + center dot (Civil 3D acquisition glyph).
+                    let h = 7.0_f32;
+                    let rect = canvas::Path::rectangle(
+                        Point::new(sp.x - h, sp.y - h),
+                        Size::new(h * 2.0, h * 2.0),
+                    );
+                    frame.stroke(&rect, stroke.clone());
+                    let r = 3.0_f32;
+                    frame.fill(
+                        &canvas::Path::circle(sp, r),
+                        Color {
+                            r: 0.95,
+                            g: 0.50,
+                            b: 0.08,
+                            a: 0.85,
+                        },
+                    );
+                }
                 SnapType::Endpoint => {
                     let h = 5.0_f32;
                     let rect = canvas::Path::rectangle(
@@ -655,7 +674,7 @@ impl canvas::Program<Message> for SelectionCanvas {
                     let r = 1.4_f32;
                     for k in [-7.0_f32, 0.0, 7.0] {
                         let dot = canvas::Path::circle(Point::new(sp.x + k, sp.y), r);
-                        frame.fill(&dot, yellow);
+                        frame.fill(&dot, marker);
                     }
                 }
                 SnapType::Parallel => {

src/ui/ribbon/mod.rs

@@ -13,8 +13,8 @@ use iced::widget::{button, column, container, mouse_area, row, scrollable, svg,
 use iced::{Background, Border, Color, Element, Fill, Length, Padding, Theme};
 
 use crate::app::Message;
-use crate::modules::registry;
 use crate::modules::{CadModule, IconKind, RibbonItem};
+use crate::plugin::all_ribbon_modules;
 use crate::ui::properties::{color_picker_dropdown, lw_options, LinetypeItem};
 
 mod widgets;
@@ -67,7 +67,7 @@ pub struct LayerInfo {
 impl Ribbon {
     pub fn new() -> Self {
         Self {
-            modules: registry::all_modules(),
+            modules: all_ribbon_modules(),
             active: 0,
             active_tool: None,
             wireframe: false,