superdoc 2.20.1-next.11 → 2.20.1-next.12

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.20.1-next.11",
+	superdocVersion: "2.20.1-next.12",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.20.1-next.11",
+	superdocVersion: "2.20.1-next.12",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/types/create.types.d.ts

@@ -1,5 +1,6 @@
 import { TextAddress } from './address.js';
 import { BlockNodeAddress } from './base.js';
+import { ResolvedHandle } from './discovery.js';
 import { ReceiptFailure, ReceiptInsert } from './receipt.js';
 import { StoryLocator } from './story.types.js';
 export type ParagraphCreateLocation = {
@@ -18,13 +19,57 @@ export interface CreateParagraphInput {
     in?: StoryLocator;
     at?: ParagraphCreateLocation;
     text?: string;
+    /**
+     * Explicit paragraph style id (e.g. `'BodyText'`) to apply instead of the
+     * document's default paragraph style. Neighboring styles and direct
+     * formatting are not inherited. An unknown style id fails
+     * with `INVALID_INPUT` and does not mutate the document.
+     */
+    styleId?: string;
 }
 export interface CreateParagraphSuccessResult {
     success: true;
     paragraph: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];
-    /** Stable ref handle for the created block. Pass directly to superdoc_format or superdoc_edit without searching. */
+    /**
+     * Mutation-ready handle for the created paragraph. `handle.ref` is an
+     * opaque, self-contained ref (the same shape `ranges.resolve` produces) —
+     * pass it directly to `format.apply`'s `ref` without needing to also pass
+     * `in`/story context, even for a header/footer paragraph. It is pinned to
+     * `evaluatedRevision` (`refStability: 'ephemeral'`), so it is valid for
+     * the immediate next mutation call only; chaining a second one after that
+     * needs a fresh ref from a discovery read (e.g. `blocks.list`,
+     * `query.match`). `paragraph.nodeId` remains stable across revisions for
+     * non-ref addressing (e.g. `{ target: { kind: 'block', nodeType, nodeId } }`).
+     *
+     * With `options.dryRun: true`, nothing was committed, so there is no real
+     * block to reference: `handle.ref` is the literal placeholder `'(dry-run)'`
+     * and `paragraph.nodeId`/`insertionPoint.blockId` are too. Do not pass a
+     * dry-run `handle.ref` to `format.apply` or any other mutation — it does
+     * not resolve and the call fails with `INVALID_TARGET`.
+     *
+     * With no `text` (an empty paragraph), `handle.ref` spans a zero-length
+     * range. This is not specific to create — `format.apply`'s "inline" action
+     * cannot format zero-length text in general (there are no characters to
+     * carry run properties), so chaining `handle.ref` into it fails with
+     * `INVALID_TARGET` for an empty create the same way it would for any other
+     * zero-length selection. Use paragraph-level actions with `paragraph` (its
+     * `nodeId`) instead, e.g. `styles.paragraph.setStyle` or
+     * `format.paragraph.setIndentation`, which target the whole block and do
+     * not need a non-empty text range.
+     */
+    handle: ResolvedHandle;
+    /**
+     * Document revision immediately after this create committed. Pass as
+     * `expectedRevision` on the immediate next mutation call to chain without
+     * a `REVISION_MISMATCH` (SD-4886).
+     */
+    evaluatedRevision: string;
+    /**
+     * @deprecated Use `handle.ref` instead. Kept as an alias of `handle.ref`
+     * for backward compatibility with existing callers of this field.
+     */
     ref?: string;
 }
 export interface CreateParagraphFailureResult {
@@ -40,13 +85,57 @@ export interface CreateHeadingInput {
     level: HeadingLevel;
     at?: HeadingCreateLocation;
     text?: string;
+    /**
+     * Explicit paragraph style id to apply instead of the `Heading{level}`
+     * style normally derived from `level`. `level` still controls numbering
+     * suppression regardless of this override. An unknown style id fails with
+     * `INVALID_INPUT` and does not mutate the document.
+     */
+    styleId?: string;
 }
 export interface CreateHeadingSuccessResult {
     success: true;
     heading: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];
-    /** Stable ref handle for the created block. Pass directly to superdoc_format or superdoc_edit without searching. */
+    /**
+     * Mutation-ready handle for the created heading. `handle.ref` is an
+     * opaque, self-contained ref (the same shape `ranges.resolve` produces) —
+     * pass it directly to `format.apply`'s `ref` without needing to also pass
+     * `in`/story context, even for a header/footer heading. It is pinned to
+     * `evaluatedRevision` (`refStability: 'ephemeral'`), so it is valid for
+     * the immediate next mutation call only; chaining a second one after that
+     * needs a fresh ref from a discovery read (e.g. `blocks.list`,
+     * `query.match`). `heading.nodeId` remains stable across revisions for
+     * non-ref addressing (e.g. `{ target: { kind: 'block', nodeType, nodeId } }`).
+     *
+     * With `options.dryRun: true`, nothing was committed, so there is no real
+     * block to reference: `handle.ref` is the literal placeholder `'(dry-run)'`
+     * and `heading.nodeId`/`insertionPoint.blockId` are too. Do not pass a
+     * dry-run `handle.ref` to `format.apply` or any other mutation — it does
+     * not resolve and the call fails with `INVALID_TARGET`.
+     *
+     * With no `text` (an empty heading), `handle.ref` spans a zero-length
+     * range. This is not specific to create — `format.apply`'s "inline" action
+     * cannot format zero-length text in general (there are no characters to
+     * carry run properties), so chaining `handle.ref` into it fails with
+     * `INVALID_TARGET` for an empty create the same way it would for any other
+     * zero-length selection. Use paragraph-level actions with `heading` (its
+     * `nodeId`) instead, e.g. `styles.paragraph.setStyle` or
+     * `format.paragraph.setIndentation`, which target the whole block and do
+     * not need a non-empty text range.
+     */
+    handle: ResolvedHandle;
+    /**
+     * Document revision immediately after this create committed. Pass as
+     * `expectedRevision` on the immediate next mutation call to chain without
+     * a `REVISION_MISMATCH` (SD-4886).
+     */
+    evaluatedRevision: string;
+    /**
+     * @deprecated Use `handle.ref` instead. Kept as an alias of `handle.ref`
+     * for backward compatibility with existing callers of this field.
+     */
     ref?: string;
 }
 export interface CreateHeadingFailureResult {

package/dist/superdoc.cjs

@@ -316,7 +316,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.20.1-next.11";
+		return "2.20.1-next.12";
 	} catch {
 		return "unknown";
 	}
@@ -46358,7 +46358,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.20.1-next.11";
+		this.version = "2.20.1-next.12";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];

package/dist/superdoc.es.js

@@ -314,7 +314,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.20.1-next.11";
+		return "2.20.1-next.12";
 	} catch {
 		return "unknown";
 	}
@@ -46287,7 +46287,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.20.1-next.11";
+		this.version = "2.20.1-next.12";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];