fix(document-api): add minProperties, type export, shared alignment constant

Author: tupizz

packages/document-api/src/contract/schemas.ts

@@ -4869,24 +4869,27 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
         id: { type: 'string' },
         op: { const: 'format.apply', type: 'string' },
         where: stepWhereSchema,
-        args: objectSchema(
-          {
-            inline: buildInlineRunPatchSchema(),
-            alignment: {
-              type: 'string',
-              enum: ['left', 'center', 'right', 'justify'],
-              description:
-                'Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step.',
-            },
-            scope: {
-              type: 'string',
-              enum: ['match', 'block'],
-              description:
-                'When "block", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use "block" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: "match".',
+        args: {
+          ...objectSchema(
+            {
+              inline: buildInlineRunPatchSchema(),
+              alignment: {
+                type: 'string',
+                enum: ['left', 'center', 'right', 'justify'],
+                description:
+                  'Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step.',
+              },
+              scope: {
+                type: 'string',
+                enum: ['match', 'block'],
+                description:
+                  'When "block", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use "block" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: "match".',
+              },
             },
-          },
-          [], // No individual field is required — at least one must be present
-        ),
+            [],
+          ),
+          minProperties: 1,
+        },
       },
       ['id', 'op', 'where', 'args'],
     );

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

@@ -3,7 +3,8 @@ import type { SelectionTarget, TargetLocator, SDMutationReceipt } from '../types
 import type { SDInsertInput } from '../types/structural-input.js';
 import type { SDFragment } from '../types/fragment.js';
 import type { StoryLocator } from '../types/story.types.js';
-import { PLACEMENT_VALUES } from '../types/placement.js';
+import { type BlockNodeAddress } from '../types/base.js';
+import { PLACEMENT_VALUES, type Placement } from '../types/placement.js';
 import { DocumentApiValidationError } from '../errors.js';
 import {
   isRecord,
@@ -40,6 +41,20 @@ export type TextInsertInput = OptionalInsertLocator & {
   in?: StoryLocator;
 };
 
+/**
+ * Type-safe input for markdown/html inserts with block-level positioning.
+ * Accepts BlockNodeAddress targets and placement (routed through the structural insert path).
+ * Standalone export — not part of the InsertInput union to avoid type narrowing issues in the runtime.
+ */
+export type RichContentInsertInput = {
+  target?: SelectionTarget | BlockNodeAddress;
+  ref?: string;
+  value: string;
+  type: 'markdown' | 'html';
+  placement?: Placement;
+  in?: StoryLocator;
+};
+
 /** @deprecated Use {@link TextInsertInput} instead. */
 export type LegacyInsertInput = TextInsertInput;
 

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts

@@ -39,6 +39,7 @@ import type {
 } from './executor-registry.types.js';
 import { getStepExecutor } from './executor-registry.js';
 import { planError } from './errors.js';
+import { ALIGNMENT_TO_JUSTIFICATION } from './paragraphs-wrappers.js';
 import { closeHistory } from 'prosemirror-history';
 import { yUndoPluginKey } from 'y-prosemirror';
 import { checkRevision, getRevision } from './revision-tracker.js';
@@ -804,21 +805,15 @@ export function executeTextDelete(
   return { changed: true };
 }
 
-/** Alignment API value → OOXML justification value */
-const ALIGNMENT_TO_JUSTIFICATION: Record<string, string> = {
-  left: 'left',
-  center: 'center',
-  right: 'right',
-  justify: 'both',
-};
+// ALIGNMENT_TO_JUSTIFICATION imported from paragraphs-wrappers.js
 
 /**
  * Applies alignment to the paragraph node(s) that contain the given range.
  * Uses the same mechanism as paragraphsSetAlignmentWrapper: updates
  * paragraphProperties.justification via tr.setNodeMarkup.
  */
 function applyAlignmentToRange(tr: Transaction, absFrom: number, absTo: number, alignment: string): boolean {
-  const justification = ALIGNMENT_TO_JUSTIFICATION[alignment];
+  const justification = ALIGNMENT_TO_JUSTIFICATION[alignment as keyof typeof ALIGNMENT_TO_JUSTIFICATION];
   if (!justification) return false;
 
   let changed = false;

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/paragraphs-wrappers.ts

@@ -238,7 +238,7 @@ function mutateParagraphProperties(
 // Alignment mapping — external API → OOXML justification value
 // ---------------------------------------------------------------------------
 
-const ALIGNMENT_TO_JUSTIFICATION: Record<ParagraphAlignment, string> = {
+export const ALIGNMENT_TO_JUSTIFICATION: Record<ParagraphAlignment, string> = {
   left: 'left',
   center: 'center',
   right: 'right',