feat(document-api): allow placement and BlockNodeAddress target for markdown inserts

Author: tupizz

examples/collaboration/ai-node-sdk/Makefile

@@ -111,13 +111,9 @@ restore-npm-sdk: ## Restore SDK from npm if currently symlinked
 
 link-local-sdk: ## Build and link local SuperDoc SDK + CLI
 	@echo "Linking local SuperDoc SDK ($(CLI_TARGET))..."
-	@# 1. Build CLI native binary if not already built
-	@if [ ! -f $(CLI_ARTIFACT) ]; then \
-		echo "  Building CLI binary..."; \
-		cd $(ROOT) && $(PNPM) --filter @superdoc-dev/cli run build:native:host; \
-	else \
-		echo "  CLI binary found"; \
-	fi
+	@# 1. Always rebuild CLI binary to pick up latest source changes
+	@echo "  Building CLI binary..."
+	@cd $(ROOT) && $(PNPM) --filter @superdoc-dev/cli run build:native:host
 	@# 2. Ensure server node_modules exists
 	@if [ ! -d server/node_modules ]; then \
 		echo "  Installing server deps first..."; \

packages/document-api/src/index.test.ts

@@ -1454,10 +1454,23 @@ describe('createDocumentApi', () => {
       );
     });
 
-    it('rejects legacy insert with structural "placement" field', () => {
+    it('rejects plain text insert with structural "placement" field', () => {
       const api = makeApi();
       expect(() => api.insert({ value: 'hi', placement: 'before' } as any)).toThrow(
-        /"placement" is only valid with structural/,
+        /"placement" is only valid with structural content input or markdown\/html/,
+      );
+    });
+
+    it('accepts placement for markdown insert', () => {
+      const api = makeApi();
+      // Should not throw — markdown inserts route through the structural path
+      expect(() => api.insert({ value: '# Hello', type: 'markdown', placement: 'insideEnd' } as any)).not.toThrow();
+    });
+
+    it('rejects invalid placement value for markdown insert', () => {
+      const api = makeApi();
+      expect(() => api.insert({ value: '# Hello', type: 'markdown', placement: 'end' } as any)).toThrow(
+        /placement must be one of/,
       );
     });
 

packages/document-api/src/insert/insert.ts

@@ -59,7 +59,7 @@ export type InsertInput = TextInsertInput | SDInsertInput;
 // Allowlists for strict field validation
 // ---------------------------------------------------------------------------
 
-const TEXT_INSERT_ALLOWED_KEYS = new Set(['value', 'type', 'target', 'ref', 'in']);
+const TEXT_INSERT_ALLOWED_KEYS = new Set(['value', 'type', 'target', 'ref', 'in', 'placement']);
 const STRUCTURAL_INSERT_ALLOWED_KEYS = new Set(['content', 'target', 'placement', 'nestingPolicy', 'in']);
 const VALID_INSERT_TYPES: ReadonlySet<string> = new Set(['text', 'markdown', 'html']);
 
@@ -121,11 +121,15 @@ function validateInsertInput(input: unknown): asserts input is InsertInput {
 
 /** Validates the text-based insert input shape. */
 function validateTextInsertInput(input: Record<string, unknown>): void {
+  const contentType = typeof input.type === 'string' ? input.type : 'text';
+  const isRichContent = contentType === 'markdown' || contentType === 'html';
+
   // Union conflict rule 4: structural-only fields with text shape
-  if ('placement' in input && input.placement !== undefined) {
+  // placement is allowed for markdown/html since they route through the structural path
+  if ('placement' in input && input.placement !== undefined && !isRichContent) {
     throw new DocumentApiValidationError(
       'INVALID_INPUT',
-      '"placement" is only valid with structural content input, not with "value".',
+      '"placement" is only valid with structural content input or markdown/html inserts, not with plain "value".',
       { field: 'placement' },
     );
   }
@@ -139,6 +143,17 @@ function validateTextInsertInput(input: Record<string, unknown>): void {
 
   assertNoUnknownFields(input, TEXT_INSERT_ALLOWED_KEYS, 'insert');
 
+  // Validate placement value when provided for markdown/html
+  if (isRichContent && 'placement' in input && input.placement !== undefined) {
+    if (typeof input.placement !== 'string' || !PLACEMENT_VALUES.has(input.placement)) {
+      throw new DocumentApiValidationError(
+        'INVALID_INPUT',
+        `placement must be one of: before, after, insideStart, insideEnd. Got "${String(input.placement)}".`,
+        { field: 'placement', value: input.placement },
+      );
+    }
+  }
+
   const { target, ref, value, type } = input;
 
   // Mutual exclusivity: target and ref
@@ -150,11 +165,23 @@ function validateTextInsertInput(input: Record<string, unknown>): void {
     );
   }
 
-  if (target !== undefined && !isSelectionTarget(target)) {
-    throw new DocumentApiValidationError('INVALID_TARGET', 'target must be a SelectionTarget object.', {
-      field: 'target',
-      value: target,
-    });
+  if (target !== undefined) {
+    // Markdown/html inserts accept BlockNodeAddress targets (with optional placement)
+    // since they route through the structural insert path and produce block-level content.
+    if (isRichContent) {
+      if (!isSelectionTarget(target) && !isBlockNodeAddress(target)) {
+        throw new DocumentApiValidationError(
+          'INVALID_TARGET',
+          'target must be a SelectionTarget or BlockNodeAddress for markdown/html inserts.',
+          { field: 'target', value: target },
+        );
+      }
+    } else if (!isSelectionTarget(target)) {
+      throw new DocumentApiValidationError('INVALID_TARGET', 'target must be a SelectionTarget object.', {
+        field: 'target',
+        value: target,
+      });
+    }
   }
 
   if (ref !== undefined && (typeof ref !== 'string' || ref === '')) {