ocs_doc_api: Phase 4 (paper-space viewports)

- Operation::CreateViewport(ViewportSpec) appended to the wire enum (append-only).
- backend add_viewport (center/width/height/view_target/view_height).
- Viewport bounds (center +- w/2,h/2), transform (moves center), ensure_transformable.
- facade EntityCollection::create_viewport; spec Viewport family; api_reference +
  binding_schema regenerated; mocks updated.
- Test phase4_create_viewport_bounds_transform -> 600 host lib green.
- IMPLEMENTATION.md: Phase 4 done (set_view/view-query remaining).

crates/ocs_doc_api/src/backend.rs

@@ -39,6 +39,9 @@ pub trait DocApiBackend {
     /// the fresh `ObjectId`. `Validation` if the block is unknown.
     fn add_insert(&mut self, spec: &crate::ops::InsertSpec) -> ApiResult<ObjectId>;
 
+    /// Add a paper-space `VIEWPORT`; returns the fresh `ObjectId`.
+    fn add_viewport(&mut self, spec: &crate::ops::ViewportSpec) -> ApiResult<ObjectId>;
+
     /// Remove any first-level entity by id. Returns `false` if absent; returns
     /// `Err` if the entity exists but cannot be removed (e.g. locked layer).
     fn remove_entity(&mut self, id: ObjectId) -> ApiResult<bool>;

crates/ocs_doc_api/src/executor.rs

@@ -183,6 +183,12 @@ pub fn apply_op<B: DocApiBackend>(b: &mut B, op: Operation) -> ApiResult<Receipt
             b.finalize_op();
             OpOutcome::NewId(id)
         }
+        Operation::CreateViewport(spec) => {
+            b.push_undo(name);
+            let id = b.add_viewport(spec)?;
+            b.finalize_op();
+            OpOutcome::NewId(id)
+        }
     };
     Ok(Receipt {
         outcome: Some(outcome),

crates/ocs_doc_api/src/facade.rs

@@ -464,6 +464,19 @@ pub struct EntityCollection {
 }
 
 impl EntityCollection {
+    /// Create a paper-space `VIEWPORT` (a `width`×`height` viewport at `center`
+    /// looking at `view_target` with `view_height` zoom).
+    pub fn create_viewport(&self, center: [f64; 3], width: f64, height: f64, view_target: [f64; 3], view_height: f64) -> ApiResult<Entity> {
+        let receipt = self.session.apply_op(Operation::CreateViewport(crate::ops::ViewportSpec {
+            center, width, height, view_target, view_height,
+        }))?;
+        let id = receipt
+            .outcome
+            .and_then(|o| o.new_id())
+            .ok_or_else(|| ApiError::Transport("create_viewport returned no id".into()))?;
+        Ok(Entity::new(self.session.clone(), id))
+    }
+
     /// Place a block reference (`INSERT`) for `block_name` (must exist).
     pub fn create_insert(&self, block_name: &str, insert_point: [f64; 3], scale: f64, rotation: f64) -> ApiResult<Entity> {
         let receipt = self.session.apply_op(Operation::CreateInsert(crate::ops::InsertSpec {

crates/ocs_doc_api/src/gen/api_reference.md

@@ -95,6 +95,14 @@ Block reference. Place an existing BlockRecord by name; transform moves its inse
 
 - **create_insert**(`block_name: &str, insert_point: [f64; 3], scale: f64, rotation: f64`) -> `Entity`
 
+## `Entity` (acadrust `Viewport`, collection `entities`)
+
+Paper-space viewport: a width×height window at center looking at view_target with view_height zoom. bounds = center ± w/2,h/2; transform moves center.
+
+### Constructors (`doc.entities()`)
+
+- **create_viewport**(`center: [f64; 3], width: f64, height: f64, view_target: [f64; 3], view_height: f64`) -> `Entity`
+
 ## Generic methods (every handle)
 
 Every typed handle (`Solid`, `Line`, `Circle`, `Polyline`, `Point`, `Entity`) is a

crates/ocs_doc_api/src/gen/binding_schema.json

@@ -194,6 +194,13 @@
       "handle": "Entity",
       "methods": [],
       "name": "Insert"
+    },
+    {
+      "acadrust_variant": "Viewport",
+      "collection": "entities",
+      "handle": "Entity",
+      "methods": [],
+      "name": "Viewport"
     }
   ],
   "layouts": {

crates/ocs_doc_api/src/gen/ops_gen.rs

@@ -6,7 +6,7 @@
 use serde::{Deserialize, Serialize};
 
 use crate::id::ObjectId;
-use crate::ops::{BoolOp, Curve2Spec, EntitySpec, InsertSpec, PlacementSpec, SolidPrimitive};
+use crate::ops::{BoolOp, Curve2Spec, EntitySpec, InsertSpec, PlacementSpec, SolidPrimitive, ViewportSpec};
 
 /// A typed write operation (plan §5). Each variant is ONE atomic host call = one
 /// undo step. Append new variants at the END only.
@@ -29,4 +29,6 @@ pub enum Operation {
     DeleteMany(Vec<ObjectId>),
     // containers
     CreateInsert(InsertSpec),
+    // paper-space
+    CreateViewport(ViewportSpec),
 }

crates/ocs_doc_api/src/ops.rs

@@ -67,6 +67,18 @@ pub struct InsertSpec {
     pub rotation: f64,
 }
 
+/// Construction spec for a paper-space `VIEWPORT`: a `width`×`height` viewport
+/// centered at `center` (paper space), looking at `view_target` (model space,
+/// WCS) with `view_height` (model-space height visible; the viewport's zoom).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ViewportSpec {
+    pub center: [f64; 3],
+    pub width: f64,
+    pub height: f64,
+    pub view_target: [f64; 3],
+    pub view_height: f64,
+}
+
 /// A rigid similarity (rotation + translation + optional uniform scale/reflection)
 /// as a plain-data mirror of `cadkernel::brep::transform`'s `Placement`
 /// (non-serde). Columns are the new basis axes; `origin` is the translation.
@@ -115,6 +127,7 @@ impl crate::gen::Operation {
             TransformMany { .. } => "TransformMany",
             DeleteMany(_) => "DeleteMany",
             CreateInsert(_) => "CreateInsert",
+            CreateViewport(_) => "CreateViewport",
         }
     }
 }