@univerjs/docs 1.0.0-alpha.7 → 1.0.0-beta.0

package/lib/cjs/facade.js

@@ -107,8 +107,9 @@ function stripBlockTokens(text) {
 * that insert or remove content before it.
 * @hideconstructor
 */
-var FDocumentTextRange = class {
+var FDocumentTextRange = class extends _univerjs_core_facade.FBaseInitialable {
 	constructor(_document, _startOffset, _endOffset, _segmentId, _injector) {
+		super(_injector);
 		this._document = _document;
 		this._startOffset = _startOffset;
 		this._endOffset = _endOffset;
@@ -156,18 +157,11 @@ var FDocumentTextRange = class {
 	*/
 	getExplicitTextStyleRuns() {
 		const { textRuns = [] } = this._document.getBody(this._segmentId);
-		return textRuns.filter((run) => run.st < this._endOffset && run.ed > this._startOffset).map((run) => {
-			var _run$ts;
-			return {
-				startOffset: Math.max(run.st, this._startOffset),
-				endOffset: Math.min(run.ed, this._endOffset),
-				textStyle: _univerjs_core.Tools.deepClone((_run$ts = run.ts) !== null && _run$ts !== void 0 ? _run$ts : {})
-			};
-		});
-	}
-	/** @deprecated Use `getExplicitTextStyleRuns()` to distinguish stored styles from effective styles. */
-	getTextStyleRuns() {
-		return this.getExplicitTextStyleRuns();
+		return textRuns.filter((run) => run.st < this._endOffset && run.ed > this._startOffset).map((run) => ({
+			startOffset: Math.max(run.st, this._startOffset),
+			endOffset: Math.min(run.ed, this._endOffset),
+			textStyle: _univerjs_core.Tools.deepClone(run.ts ?? {})
+		}));
 	}
 	/**
 	* Returns top-level style properties that have the same explicit value
@@ -186,10 +180,6 @@ var FDocumentTextRange = class {
 		for (const key of Object.keys(common)) if (rest.some((run) => !isDeepEqual(run.textStyle[key], common[key]))) delete common[key];
 		return common;
 	}
-	/** @deprecated Use `getCommonExplicitTextStyle()` to distinguish stored styles from effective styles. */
-	getCommonTextStyle() {
-		return this.getCommonExplicitTextStyle();
-	}
 	/**
 	* Returns a serializable summary suitable for an agent/tool response.
 	* @example
@@ -207,9 +197,7 @@ var FDocumentTextRange = class {
 			text: this.getText(),
 			length: this._endOffset - this._startOffset,
 			explicitTextStyleRuns,
-			commonExplicitTextStyle,
-			textStyleRuns: explicitTextStyleRuns,
-			commonTextStyle: commonExplicitTextStyle
+			commonExplicitTextStyle
 		};
 	}
 	/**
@@ -276,23 +264,33 @@ function isDeepEqual(left, right) {
 	return JSON.stringify(left) === JSON.stringify(right);
 }
 
+//#endregion
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
 //#endregion
 //#region src/facade/f-document-paragraph.ts
-/**
-* A paragraph facade wrapper.
-*
-* Paragraph identity is backed by the persisted `paragraphId`. The id is
-* re-resolved before each method call, so insertions before this paragraph do
-* not break the wrapper.
-*
-* @hideconstructor
-*/
-var FDocumentParagraph = class {
-	constructor(_document, _paragraphId, _segmentId = "", _injector) {
+let FDocumentParagraph = class FDocumentParagraph extends _univerjs_core_facade.FBaseInitialable {
+	constructor(_document, _paragraphId, _segmentId = "", _injector, _commandService) {
+		super(_injector);
 		this._document = _document;
 		this._paragraphId = _paragraphId;
 		this._segmentId = _segmentId;
 		this._injector = _injector;
+		this._commandService = _commandService;
 	}
 	/**
 	* Get the persisted paragraph id.
@@ -383,6 +381,71 @@ var FDocumentParagraph = class {
 		return this._injector.createInstance(FDocumentTextRange, this._document, startOffset, endOffset, this._segmentId, this._injector);
 	}
 	/**
+	* Finds one literal text occurrence inside this paragraph.
+	*
+	* The returned text range is fixed when it is created. Resolve a new range
+	* after edits that insert or remove content before the match.
+	*
+	* @param {string} text Literal text to find. It must not be empty.
+	* @param {IFDocumentFindTextOptions} [options] Case sensitivity and zero-based occurrence.
+	* @returns {FDocumentTextRange | null} The matching fixed text range, or `null` when no such occurrence exists.
+	* @example
+	* ```ts
+	* const univerAPI = FUniver.newAPI(univer);
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) throw new Error('No active document');
+	*
+	* const paragraph = document.findParagraphByText('Launch formula');
+	* if (!paragraph) throw new Error('Target paragraph not found');
+	*
+	* const range = paragraph.findText('formula');
+	* if (!range) throw new Error('Target text not found');
+	*
+	* console.log(range.describe());
+	* ```
+	*/
+	findText(text, options = {}) {
+		const occurrence = options.occurrence ?? 0;
+		if (!Number.isInteger(occurrence) || occurrence < 0) throw new RangeError("Text occurrence must be a non-negative integer.");
+		return this.findAllText(text, options)[occurrence] ?? null;
+	}
+	/**
+	* Finds every non-overlapping literal text occurrence inside this paragraph.
+	*
+	* Results are ordered from the start of the paragraph. The returned ranges
+	* are fixed when created; use them immediately and resolve new ranges after
+	* edits that change earlier document content.
+	*
+	* @param {string} text Literal text to find. It must not be empty.
+	* @param {Omit<IFDocumentFindTextOptions, 'occurrence'>} [options] Case-sensitivity option.
+	* @returns {FDocumentTextRange[]} All matching fixed text ranges, or an empty array when no matches exist.
+	* @example
+	* ```ts
+	* const univerAPI = FUniver.newAPI(univer);
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) throw new Error('No active document');
+	*
+	* const paragraph = document.findParagraphByText('x plus x');
+	* if (!paragraph) throw new Error('Target paragraph not found');
+	*
+	* const matches = paragraph.findAllText('x');
+	* console.log(matches.map((range) => range.describe()));
+	* ```
+	*/
+	findAllText(text, options = {}) {
+		if (text.length === 0) throw new TypeError("Text to find must not be empty.");
+		const matchCase = options.matchCase ?? true;
+		const paragraphText = this.getText();
+		const matcher = _univerjs_core.regexp.createLiteralRegExp(text, matchCase ? "gu" : "giu");
+		const { startOffset } = this.getInfo();
+		const matches = [];
+		for (const match of paragraphText.matchAll(matcher)) {
+			const matchStartOffset = startOffset + match.index;
+			matches.push(this._injector.createInstance(FDocumentTextRange, this._document, matchStartOffset, matchStartOffset + match[0].length, this._segmentId, this._injector));
+		}
+		return matches;
+	}
+	/**
 	* Get this paragraph's plain text.
 	* @returns {string} The paragraph text without the trailing paragraph break.
 	* @example
@@ -434,59 +497,65 @@ var FDocumentParagraph = class {
 		return this._document.insertText(endOffset, text, this._segmentId);
 	}
 	/**
-	* Apply paragraph style to a paragraph handle or text range.
+	* Applies a paragraph and optional text-style patch through one document command.
+	*
+	* Pagination values use `BooleanNumber.TRUE` or `BooleanNumber.FALSE`; explicit
+	* false is preserved and overrides inherited true. The paragraph and text-style
+	* changes share one undo/redo item. A stale paragraph handle returns `false`
+	* without applying a partial update.
+	*
+	* The Traditional renderer applies these Word-compatible pagination rules:
+	* use `pageBreakBefore` for a hard chapter-page boundary, `keepLines` for a
+	* short paragraph that should stay intact, `keepNext` for a heading or caption
+	* that should accompany the next paragraph, and `widowControl` for natural
+	* multi-line body text. Do not enable every rule on every paragraph. Modern
+	* and Unspecified Docs preserve the values in the model but do not apply them
+	* to physical pages.
+	*
 	* `style.textStyle.fs` is a font size in points (pt), not CSS pixels.
 	* @param {IParagraphStyle} style The Univer paragraph style patch.
-	* @returns {boolean} `true` if the style was applied.
+	* @returns {boolean} `true` when the complete patch was applied; otherwise `false`.
 	* @example
 	* ```ts
-	* const fDocument = univerAPI.getActiveDocument();
-	* const paragraph = fDocument.getParagraphs()[0];
-	* paragraph?.setText('Styled text');
-	* paragraph?.setStyle({
-	*   textStyle: {
-	*     cl: {
-	*       rgb: '#FF0000',
-	*     },
-	*     fs: 14,
-	*   },
-	*   horizontalAlign: 2,
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) {
+	*   throw new Error('No active document');
+	* }
+	* if (!document.isTraditional()) {
+	*   throw new Error('Traditional document pagination is required');
+	* }
+	* const heading = document.findParagraphByText('Appendix');
+	* const following = document.findParagraphByText('Supporting details');
+	* if (!heading || !following) {
+	*   throw new Error('Expected paragraphs were not found');
+	* }
+	*
+	* const headingUpdated = heading.setStyle({
+	*   pageBreakBefore: univerAPI.Enum.BooleanNumber.TRUE,
+	*   keepLines: univerAPI.Enum.BooleanNumber.TRUE,
+	*   keepNext: univerAPI.Enum.BooleanNumber.TRUE,
+	* });
+	* const followingUpdated = following.setStyle({
+	*   // Explicit FALSE terminates this authored keepNext chain even if a named
+	*   // style or document default enables it.
+	*   keepNext: univerAPI.Enum.BooleanNumber.FALSE,
+	*   widowControl: univerAPI.Enum.BooleanNumber.TRUE,
 	* });
-	* console.log(paragraph?.getInfo().paragraph.paragraphStyle);
+	* if (!headingUpdated || !followingUpdated) {
+	*   throw new Error('Failed to update paragraph pagination');
+	* }
 	* ```
 	*/
 	setStyle(style) {
-		const { paragraph, startOffset, endOffset } = this.getInfo();
-		let result = true;
-		if (style.textStyle && startOffset < endOffset) result = retainBodyRange({
+		const { startOffset, endOffset } = this.getInfo();
+		return this._commandService.syncExecuteCommand(_univerjs_docs.UpdateDocumentParagraphStyleCommand.id, {
+			unitId: this._document.getId(),
+			segmentId: this._segmentId,
+			paragraphId: this._paragraphId,
 			startOffset,
 			endOffset,
-			segmentId: this._segmentId
-		}, {
-			dataStream: "",
-			textRuns: [{
-				st: 0,
-				ed: endOffset - startOffset,
-				ts: style.textStyle
-			}]
-		}, _univerjs_core.UpdateDocsAttributeType.COVER, this._document.getDocumentDataModel(), this._injector);
-		const updateBody = {
-			dataStream: "",
-			paragraphs: [{
-				...paragraph,
-				startIndex: 0,
-				paragraphStyle: {
-					...paragraph.paragraphStyle,
-					...style
-				}
-			}]
-		};
-		this._preserveExplicitParagraphIds(updateBody);
-		return retainBodyRange({
-			startOffset: endOffset,
-			endOffset: endOffset + 1,
-			segmentId: this._segmentId
-		}, updateBody, _univerjs_core.UpdateDocsAttributeType.REPLACE, this._document.getDocumentDataModel(), this._injector) && result;
+			style
+		});
 	}
 	/**
 	* Check whether this paragraph is a bullet, ordered, or checklist item.
@@ -578,6 +647,7 @@ var FDocumentParagraph = class {
 		body[_univerjs_core.RESTORE_INSERTED_PARAGRAPH_IDS] = true;
 	}
 };
+FDocumentParagraph = __decorate([__decorateParam(4, _univerjs_core.ICommandService)], FDocumentParagraph);
 function isParagraphFacade(value) {
 	if (typeof value !== "object" || value === null) return false;
 	return typeof value.getId === "function" && typeof value.getSegmentId === "function" && typeof value.getInfo === "function" && typeof value.getRange === "function";
@@ -585,29 +655,30 @@ function isParagraphFacade(value) {
 
 //#endregion
 //#region src/facade/f-document-section.ts
-/** Error thrown when traditional section APIs are used to mutate a modern document. */
+function validatePageSetup(pageSetup) {
+	const { pageNumberStart, pageSize, pageOrient, marginTop, marginBottom, marginLeft, marginRight } = pageSetup;
+	if (pageNumberStart != null && (!Number.isInteger(pageNumberStart) || pageNumberStart < 1)) throw new RangeError("Section page number start must be a positive integer.");
+	if (pageSize && [pageSize.width, pageSize.height].some((size) => size != null && (!Number.isFinite(size) || size <= 0))) throw new RangeError("Section page size must be finite and positive.");
+	if (pageOrient != null && !Object.values(_univerjs_core.PageOrientType).includes(pageOrient)) throw new RangeError("Invalid section page orientation.");
+	if ([
+		marginTop,
+		marginBottom,
+		marginLeft,
+		marginRight
+	].some((margin) => margin != null && (!Number.isFinite(margin) || margin < 0))) throw new RangeError("Section page margins must be finite and non-negative.");
+}
+/** Error thrown when a Traditional-only section API is used with another document flavor. */
 var DocsSectionUnsupportedDocumentFlavorError = class extends Error {
 	constructor() {
-		super("Section column APIs are supported only in traditional documents. Use ColumnGroup APIs for modern documents.");
+		super("Section column APIs are supported only in traditional documents. Use ColumnGroup APIs for modern documents, or resolve an unspecified document flavor first.");
 		this.name = "DocsSectionUnsupportedDocumentFlavorError";
 	}
 };
-/**
-* Facade wrapper for an OOXML-compatible traditional document section.
-* Modern documents use ColumnGroup APIs and cannot mutate this facade.
-* @example
-* ```ts
-* const fDocument = univerAPI.getActiveDocument();
-* if (fDocument && !fDocument.isModern()) {
-*   console.log(fDocument.getSection(0)?.describe());
-* }
-* ```
-*/
-var FDocumentSection = class {
-	constructor(_document, _sectionId, _injector) {
+let FDocumentSection = class FDocumentSection {
+	constructor(_document, _sectionId, _commandService) {
 		this._document = _document;
 		this._sectionId = _sectionId;
-		this._injector = _injector;
+		this._commandService = _commandService;
 	}
 	/**
 	* Returns the persisted section id.
@@ -640,8 +711,7 @@ var FDocumentSection = class {
 	* ```
 	*/
 	getConfig() {
-		const { sectionBreak } = this._resolve();
-		return _univerjs_core.Tools.deepClone(sectionBreak);
+		return this._getConfigSnapshot();
 	}
 	/**
 	* Returns the section content range, excluding its terminating section-break token.
@@ -652,17 +722,11 @@ var FDocumentSection = class {
 	* ```
 	*/
 	getRange() {
-		const sectionBreaks = (0, _univerjs_docs.getTopLevelSectionBreaks)(this._document.getBody());
-		const { index, sectionBreak } = this._resolve();
-		return {
-			startOffset: index === 0 ? 0 : sectionBreaks[index - 1].startIndex + 1,
-			endOffset: sectionBreak.startIndex,
-			segmentId: ""
-		};
+		return this._getRange(this._resolve().index);
 	}
 	/**
 	* Returns the explicit columns. An empty array means the normal single-column layout.
-	* Column widths and trailing spaces are in points (pt).
+	* Column widths and trailing spaces are in 96-DPI layout pixels.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -670,8 +734,7 @@ var FDocumentSection = class {
 	* ```
 	*/
 	getColumns() {
-		var _this$getConfig$colum;
-		return _univerjs_core.Tools.deepClone((_this$getConfig$colum = this.getConfig().columnProperties) !== null && _this$getConfig$colum !== void 0 ? _this$getConfig$colum : []);
+		return _univerjs_core.Tools.deepClone(this._getConfigSnapshot().columnProperties ?? []);
 	}
 	/**
 	* Returns a compact serializable section summary.
@@ -682,9 +745,9 @@ var FDocumentSection = class {
 	* ```
 	*/
 	describe() {
-		var _config$columnPropert, _config$columnSeparat, _config$sectionType;
-		const config = this.getConfig();
-		const columns = (_config$columnPropert = config.columnProperties) !== null && _config$columnPropert !== void 0 ? _config$columnPropert : [];
+		const { index } = this._resolve();
+		const config = this._getConfigSnapshot();
+		const columns = config.columnProperties ?? [];
 		const headerFooter = {
 			defaultHeader: this._describeHeaderFooterReference("header", "default"),
 			defaultFooter: this._describeHeaderFooterReference("footer", "default"),
@@ -695,12 +758,12 @@ var FDocumentSection = class {
 		};
 		return {
 			sectionId: this._sectionId,
-			index: this.getIndex(),
-			range: this.getRange(),
+			index,
+			range: this._getRange(index),
 			columnCount: columns.length || 1,
 			columns: _univerjs_core.Tools.deepClone(columns),
-			columnSeparatorType: (_config$columnSeparat = config.columnSeparatorType) !== null && _config$columnSeparat !== void 0 ? _config$columnSeparat : _univerjs_core.ColumnSeparatorType.NONE,
-			sectionType: (_config$sectionType = config.sectionType) !== null && _config$sectionType !== void 0 ? _config$sectionType : _univerjs_core.SectionType.SECTION_TYPE_UNSPECIFIED,
+			columnSeparatorType: config.columnSeparatorType ?? _univerjs_core.ColumnSeparatorType.NONE,
+			sectionType: config.sectionType ?? _univerjs_core.SectionType.SECTION_TYPE_UNSPECIFIED,
 			headerFooter,
 			config
 		};
@@ -708,36 +771,36 @@ var FDocumentSection = class {
 	/**
 	* Sets equal or explicitly sized columns for this traditional section.
 	* Use `columnCount = 1` to restore normal single-column layout.
-	* `gap` and `widths` are in points (pt).
+	* `gap` and `widths` are in 96-DPI layout pixels.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   fDocument.getSection(0)?.setColumns(2, { gap: 18, separator: true });
 	* }
 	* ```
 	*/
 	setColumns(columnCount, options = {}) {
-		var _options$gap, _options$separator;
 		this._assertTraditionalDocument();
 		if (!Number.isInteger(columnCount) || columnCount < 1) throw new RangeError("Section column count must be a positive integer.");
 		if (options.widths && options.widths.length !== columnCount) throw new RangeError("Section column widths must match the column count.");
-		const gap = Math.max(0, (_options$gap = options.gap) !== null && _options$gap !== void 0 ? _options$gap : 18);
-		const config = this.getConfig();
+		if (options.gap != null && (!Number.isFinite(options.gap) || options.gap < 0)) throw new RangeError("Section column gap must be finite and non-negative.");
+		const gap = Math.max(0, options.gap ?? 18);
+		const config = this._getConfigSnapshot();
 		const columns = (0, _univerjs_docs.createSectionColumnProperties)(this._document.getDocumentDataModel().getSnapshot().documentStyle, config, columnCount, gap, options.widths);
-		const separator = typeof options.separator === "boolean" ? options.separator ? _univerjs_core.ColumnSeparatorType.BETWEEN_EACH_COLUMN : _univerjs_core.ColumnSeparatorType.NONE : (_options$separator = options.separator) !== null && _options$separator !== void 0 ? _options$separator : _univerjs_core.ColumnSeparatorType.NONE;
+		const separator = typeof options.separator === "boolean" ? options.separator ? _univerjs_core.ColumnSeparatorType.BETWEEN_EACH_COLUMN : _univerjs_core.ColumnSeparatorType.NONE : options.separator ?? _univerjs_core.ColumnSeparatorType.NONE;
+		if (!Object.values(_univerjs_core.ColumnSeparatorType).includes(separator)) throw new RangeError("Invalid section column separator type.");
 		return this._update({
 			columnProperties: columns,
-			columnSeparatorType: separator,
-			...options.sectionType == null ? {} : { sectionType: options.sectionType }
+			columnSeparatorType: separator
 		});
 	}
 	/**
-	* Sets explicit OOXML-compatible column width and trailing-space values in points (pt).
+	* Sets explicit OOXML-compatible column width and trailing-space values in 96-DPI layout pixels.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   fDocument.getSection(0)?.setColumnProperties([
 	*     { width: 240, paddingEnd: 18 },
 	*     { width: 240, paddingEnd: 0 },
@@ -747,32 +810,163 @@ var FDocumentSection = class {
 	*/
 	setColumnProperties(columns, separator = _univerjs_core.ColumnSeparatorType.NONE) {
 		this._assertTraditionalDocument();
-		if (columns.some(({ width, paddingEnd }) => width < 0 || paddingEnd < 0)) throw new RangeError("Section column widths and padding must be non-negative.");
+		if (!Object.values(_univerjs_core.ColumnSeparatorType).includes(separator)) throw new RangeError("Invalid section column separator type.");
+		if (columns.some(({ width, paddingEnd }) => !Number.isFinite(width) || !Number.isFinite(paddingEnd) || width < 0 || paddingEnd < 0)) throw new RangeError("Section column widths and padding must be finite and non-negative.");
+		const contentWidth = (0, _univerjs_docs.getSectionContentWidth)(this._document.getDocumentDataModel().getSnapshot().documentStyle, this._getConfigSnapshot());
+		if (columns.reduce((sum, { width, paddingEnd }) => sum + width + paddingEnd, 0) > contentWidth) throw new RangeError("Section columns exceed the available page content width.");
 		return this._update({
 			columnProperties: _univerjs_core.Tools.deepClone(columns),
 			columnSeparatorType: separator
 		});
 	}
 	/**
-	* Sets how the next section begins.
+	* Sets how this section begins relative to the previous section.
+	*
+	* The first section has no preceding boundary, so setting its type does not
+	* create an initial blank page. Prefer `FDocument.insertSectionBreak` with
+	* `nextSectionType` when creating a new boundary; use this method when
+	* updating an existing section after resolving it again from the document.
+	*
+	* @param {SectionType} sectionType How this section begins.
+	* @returns {boolean} `true` when the section command was applied.
 	* @example
 	* ```ts
-	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
-	*   fDocument.getSection(0)?.setSectionType(univerAPI.Enum.SectionType.NEXT_PAGE);
+	* const document = univerAPI.getActiveDocument();
+	* if (!document?.isTraditional()) {
+	*   throw new Error('A Traditional document is required');
+	* }
+	*
+	* const secondSection = document.getSection(1);
+	* if (!secondSection) {
+	*   throw new Error('The second section does not exist');
+	* }
+	* if (!secondSection.setSectionType(univerAPI.Enum.SectionType.NEXT_PAGE)) {
+	*   throw new Error('Failed to update the second section');
 	* }
 	* ```
 	*/
 	setSectionType(sectionType) {
 		this._assertTraditionalDocument();
+		if (!Object.values(_univerjs_core.SectionType).includes(sectionType)) throw new RangeError("Invalid section type.");
 		return this._update({ sectionType });
 	}
 	/**
+	* Returns this section's explicit page setup overrides.
+	* Missing values inherit from the document style. Geometry values use 96-DPI layout pixels.
+	*
+	* Use `getEffectivePageSetup()` when an agent needs resolved page and content
+	* dimensions rather than only the overrides stored on this section.
+	*
+	* @returns {FDocumentSectionPageSetup} A cloned object containing only explicit section overrides.
+	* @example
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* const section = document?.getSection(0);
+	* console.log(section?.getPageSetup());
+	* ```
+	*/
+	getPageSetup() {
+		const { pageNumberStart, pageSize, pageOrient, marginTop, marginBottom, marginLeft, marginRight } = this._getConfigSnapshot();
+		return _univerjs_core.Tools.deepClone({
+			pageNumberStart,
+			pageSize,
+			pageOrient,
+			marginTop,
+			marginBottom,
+			marginLeft,
+			marginRight
+		});
+	}
+	/**
+	* Returns nominal page geometry after resolving this section's overrides
+	* against document defaults. All geometry values use 96-DPI layout pixels.
+	*
+	* This synchronous model-only API works without `engine-render`. It does not
+	* report physical page count, remaining page space, or final coordinates.
+	*
+	* @returns {IEffectiveSectionPageSetup} A cloned, serializable page setup.
+	* @example
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) {
+	*   throw new Error('No active document');
+	* }
+	* if (!document.isTraditional()) {
+	*   throw new Error('Traditional document sections are required');
+	* }
+	*
+	* const section = document.getSection(0);
+	* if (!section) {
+	*   throw new Error('The document has no traditional section');
+	* }
+	*
+	* const layout = section.getEffectivePageSetup();
+	* console.log({
+	*   pageWidth: layout.pageSize.width,
+	*   pageHeight: layout.pageSize.height,
+	*   contentWidth: layout.contentSize.width,
+	*   contentHeight: layout.contentSize.height,
+	*   margins: layout.margins,
+	* });
+	* ```
+	*/
+	getEffectivePageSetup() {
+		this._assertTraditionalDocument();
+		const documentStyle = this._document.getDocumentDataModel().getSnapshot().documentStyle;
+		return _univerjs_core.Tools.deepClone((0, _univerjs_docs.getEffectiveSectionPageSetup)(documentStyle, this._getConfigSnapshot()));
+	}
+	/**
+	* Updates this section's page setup through the document section command.
+	* Geometry values use 96-DPI layout pixels.
+	*
+	* This method changes static page geometry; it does not choose where the
+	* section begins. Use `setSectionType()` for an existing boundary, or
+	* `insertSectionBreak(..., { nextSectionType })` while creating one.
+	*
+	* @param {FDocumentSectionPageSetup} pageSetup Explicit section overrides to patch.
+	* @returns {boolean} `true` when the section command was applied.
+	* @example
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* if (!document?.isTraditional()) {
+	*   throw new Error('A Traditional document is required');
+	* }
+	*
+	* const section = document.getSection(1);
+	* if (!section) {
+	*   throw new Error('The second section does not exist');
+	* }
+	* const updated = section.setPageSetup({
+	*   pageSize: { width: 816, height: 1056 },
+	*   marginTop: 96,
+	*   marginBottom: 96,
+	*   marginLeft: 96,
+	*   marginRight: 96,
+	* });
+	* if (!updated) {
+	*   throw new Error('Failed to update section page setup');
+	* }
+	* console.log(section.getEffectivePageSetup());
+	* ```
+	*/
+	setPageSetup(pageSetup) {
+		this._assertTraditionalDocument();
+		validatePageSetup(pageSetup);
+		const definedPageSetup = _univerjs_core.Tools.deepClone(pageSetup);
+		_univerjs_core.Tools.removeNull(definedPageSetup);
+		const documentStyle = this._document.getDocumentDataModel().getSnapshot().documentStyle;
+		(0, _univerjs_docs.getEffectiveSectionPageSetup)(documentStyle, {
+			...this._getConfigSnapshot(),
+			...definedPageSetup
+		});
+		return this._update(definedPageSetup);
+	}
+	/**
 	* Ensures a header segment linked specifically to this section.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   const segmentId = fDocument.getSection(0)?.ensureHeader();
 	*   if (segmentId) {
 	*     fDocument.insertText(0, 'Quarterly report', segmentId);
@@ -788,7 +982,7 @@ var FDocumentSection = class {
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   const segmentId = fDocument.getSection(0)?.ensureFooter('first');
 	*   if (segmentId) {
 	*     fDocument.insertText(0, 'Confidential', segmentId);
@@ -808,8 +1002,7 @@ var FDocumentSection = class {
 	* ```
 	*/
 	getHeaderId(variant = "default") {
-		var _this$_getHeaderFoote;
-		return (_this$_getHeaderFoote = this._getHeaderFooterReference("header", variant).segmentId) !== null && _this$_getHeaderFoote !== void 0 ? _this$_getHeaderFoote : null;
+		return this._getHeaderFooterReference("header", variant).segmentId ?? null;
 	}
 	/**
 	* Returns the effective footer id after resolving links to previous sections.
@@ -820,8 +1013,7 @@ var FDocumentSection = class {
 	* ```
 	*/
 	getFooterId(variant = "default") {
-		var _this$_getHeaderFoote2;
-		return (_this$_getHeaderFoote2 = this._getHeaderFooterReference("footer", variant).segmentId) !== null && _this$_getHeaderFoote2 !== void 0 ? _this$_getHeaderFoote2 : null;
+		return this._getHeaderFooterReference("footer", variant).segmentId ?? null;
 	}
 	/**
 	* Whether this header variant inherits the previous section's reference.
@@ -850,7 +1042,7 @@ var FDocumentSection = class {
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   fDocument.getSection(1)?.setHeaderLinkedToPrevious(false, 'default');
 	* }
 	* ```
@@ -863,7 +1055,7 @@ var FDocumentSection = class {
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   fDocument.getSection(1)?.setFooterLinkedToPrevious(true, 'even');
 	* }
 	* ```
@@ -873,11 +1065,11 @@ var FDocumentSection = class {
 	}
 	/**
 	* Updates header/footer switches and margins on this section break.
-	* `marginHeader` and `marginFooter` are in points (pt).
+	* `marginHeader` and `marginFooter` are in 96-DPI layout pixels.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   fDocument.getSection(0)?.setHeaderFooterOptions({
 	*     marginHeader: 36,
 	*     marginFooter: 36,
@@ -895,7 +1087,7 @@ var FDocumentSection = class {
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   const sections = fDocument.getSections();
 	*   if (sections.length > 1) {
 	*     sections[0].remove();
@@ -905,14 +1097,14 @@ var FDocumentSection = class {
 	*/
 	remove() {
 		this._assertTraditionalDocument();
-		return this._injector.get(_univerjs_core.ICommandService).syncExecuteCommand(_univerjs_docs.DeleteDocumentSectionBreakCommand.id, {
+		return this._commandService.syncExecuteCommand(_univerjs_docs.DeleteDocumentSectionBreakCommand.id, {
 			unitId: this._document.getId(),
 			sectionId: this._sectionId
 		});
 	}
 	_update(patch) {
 		const { sectionId: _sectionId, startIndex: _startIndex, ...config } = patch;
-		return this._injector.get(_univerjs_core.ICommandService).syncExecuteCommand(_univerjs_docs.UpdateDocumentSectionCommand.id, {
+		return this._commandService.syncExecuteCommand(_univerjs_docs.UpdateDocumentSectionCommand.id, {
 			unitId: this._document.getId(),
 			updates: [{
 				sectionId: this._sectionId,
@@ -923,11 +1115,11 @@ var FDocumentSection = class {
 	_ensureHeaderFooter(kind, variant) {
 		this._assertTraditionalDocument();
 		const { index } = this._resolve();
-		const existing = this.getConfig()[(0, _univerjs_core.getSectionHeaderFooterReferenceKey)(kind, variant)];
+		const existing = this._getConfigSnapshot()[(0, _univerjs_core.getSectionHeaderFooterReferenceKey)(kind, variant)];
 		if (typeof existing === "string" && existing) return existing;
 		if (index > 0) {
 			const segmentId = (0, _univerjs_core.generateRandomId)(6);
-			if (!this._injector.get(_univerjs_core.ICommandService).syncExecuteCommand(_univerjs_docs.SetSectionHeaderFooterLinkCommand.id, {
+			if (!this._commandService.syncExecuteCommand(_univerjs_docs.SetSectionHeaderFooterLinkCommand.id, {
 				unitId: this._document.getId(),
 				sectionId: this._sectionId,
 				kind,
@@ -943,7 +1135,7 @@ var FDocumentSection = class {
 			even: kind === "header" ? _univerjs_docs.HeaderFooterType.EVEN_PAGE_HEADER : _univerjs_docs.HeaderFooterType.EVEN_PAGE_FOOTER
 		};
 		const segmentId = (0, _univerjs_core.generateRandomId)(6);
-		if (!this._injector.get(_univerjs_core.ICommandService).syncExecuteCommand(_univerjs_docs.CreateHeaderFooterCommand.id, {
+		if (!this._commandService.syncExecuteCommand(_univerjs_docs.CreateHeaderFooterCommand.id, {
 			unitId: this._document.getId(),
 			segmentId,
 			createType: types[variant],
@@ -956,16 +1148,15 @@ var FDocumentSection = class {
 		return (0, _univerjs_core.resolveSectionHeaderFooterReference)(this._document.getDocumentDataModel().getSnapshot().documentStyle, (0, _univerjs_docs.getTopLevelSectionBreaks)(this._document.getBody()), index, (0, _univerjs_core.getSectionHeaderFooterReferenceKey)(kind, variant));
 	}
 	_describeHeaderFooterReference(kind, variant) {
-		var _reference$segmentId;
 		const reference = this._getHeaderFooterReference(kind, variant);
 		return {
-			segmentId: (_reference$segmentId = reference.segmentId) !== null && _reference$segmentId !== void 0 ? _reference$segmentId : null,
+			segmentId: reference.segmentId ?? null,
 			linkedToPrevious: reference.linkedToPrevious
 		};
 	}
 	_setHeaderFooterLinkedToPrevious(kind, variant, linkedToPrevious) {
 		this._assertTraditionalDocument();
-		return this._injector.get(_univerjs_core.ICommandService).syncExecuteCommand(_univerjs_docs.SetSectionHeaderFooterLinkCommand.id, {
+		return this._commandService.syncExecuteCommand(_univerjs_docs.SetSectionHeaderFooterLinkCommand.id, {
 			unitId: this._document.getId(),
 			sectionId: this._sectionId,
 			kind,
@@ -977,6 +1168,17 @@ var FDocumentSection = class {
 	_assertTraditionalDocument() {
 		if (this._document.getDocumentDataModel().getSnapshot().documentStyle.documentFlavor !== _univerjs_core.DocumentFlavor.TRADITIONAL) throw new DocsSectionUnsupportedDocumentFlavorError();
 	}
+	_getConfigSnapshot() {
+		return _univerjs_core.Tools.deepClone(this._resolve().sectionBreak);
+	}
+	_getRange(index) {
+		const sectionBreaks = (0, _univerjs_docs.getTopLevelSectionBreaks)(this._document.getBody());
+		return {
+			startOffset: index === 0 ? 0 : sectionBreaks[index - 1].startIndex + 1,
+			endOffset: sectionBreaks[index].startIndex,
+			segmentId: ""
+		};
+	}
 	_resolve() {
 		this._assertTraditionalDocument();
 		const sectionBreaks = (0, _univerjs_docs.getTopLevelSectionBreaks)(this._document.getBody());
@@ -988,9 +1190,10 @@ var FDocumentSection = class {
 		};
 	}
 };
+FDocumentSection = __decorate([__decorateParam(2, _univerjs_core.ICommandService)], FDocumentSection);
 
 //#endregion
-//#region \0@oxc-project+runtime@0.137.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -1001,7 +1204,7 @@ function _typeof(o) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.137.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -1014,14 +1217,14 @@ function toPrimitive(t, r) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.137.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.137.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -1031,23 +1234,6 @@ function _defineProperty(e, r, t) {
 	}) : e[r] = t, e;
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.137.0/helpers/esm/decorateParam.js
-function __decorateParam(paramIndex, decorator) {
-	return function(target, key) {
-		decorator(target, key, paramIndex);
-	};
-}
-
-//#endregion
-//#region \0@oxc-project+runtime@0.137.0/helpers/esm/decorate.js
-function __decorate(decorators, target, key, desc) {
-	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-	return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-
 //#endregion
 //#region src/facade/f-document.ts
 let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
@@ -1080,6 +1266,28 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 		return documentDataModel;
 	}
 	/**
+	* Returns the document's custom blocks in stable model order.
+	*
+	* This method is available in Node/headless environments and does not
+	* perform font measurement, line wrapping, pagination, or rendering.
+	*
+	* @returns {IDocumentCustomBlockLayout} Custom block identifiers and model positions.
+	* @example
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* const layout = document?.getCustomBlockLayout();
+	* console.log(layout?.blocks);
+	* ```
+	*/
+	getCustomBlockLayout() {
+		var _this$_documentDataMo;
+		return { blocks: (((_this$_documentDataMo = this._documentDataModel.getBody()) === null || _this$_documentDataMo === void 0 ? void 0 : _this$_documentDataMo.customBlocks) ?? []).map(({ blockId, startIndex }, index) => ({
+			blockId,
+			startIndex,
+			index
+		})) };
+	}
+	/**
 	* Get the document body or header/footer body by the segment id.
 	* The main body has an empty segment id.
 	* The header and footer body have their respective segment ids.
@@ -1095,8 +1303,8 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 	* ```
 	*/
 	getBody(segmentId = "") {
-		var _this$_documentDataMo;
-		const body = (_this$_documentDataMo = this._documentDataModel.getSelfOrHeaderFooterModel(segmentId)) === null || _this$_documentDataMo === void 0 ? void 0 : _this$_documentDataMo.getBody();
+		var _this$_documentDataMo2;
+		const body = (_this$_documentDataMo2 = this._documentDataModel.getSelfOrHeaderFooterModel(segmentId)) === null || _this$_documentDataMo2 === void 0 ? void 0 : _this$_documentDataMo2.getBody();
 		if (!body) throw new Error(segmentId === "" ? "Body is not found in the document." : `Body is not found in the segment: ${segmentId}`);
 		return body;
 	}
@@ -1128,16 +1336,72 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 		return this._documentDataModel.getTitle() || "";
 	}
 	/**
-	* Whether the document is a modern document or not.
-	* @returns {boolean} `true` if the document is a modern document, or `false` if it is not.
+	* Returns the document's explicit layout flavor.
+	*
+	* Use this method when all three states matter. Do not infer a Traditional
+	* document from `!isModern()`: that expression is also true for
+	* `DocumentFlavor.UNSPECIFIED`.
+	*
+	* @returns {DocumentFlavor} `TRADITIONAL`, `MODERN`, or `UNSPECIFIED`.
+	* @example
+	* ```typescript
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) {
+	*   throw new Error('No active document');
+	* }
+	*
+	* switch (document.getDocumentFlavor()) {
+	*   case univerAPI.Enum.DocumentFlavor.TRADITIONAL:
+	*     console.log('Word-compatible physical pagination is available');
+	*     break;
+	*   case univerAPI.Enum.DocumentFlavor.MODERN:
+	*     console.log('Use Modern Doc layout APIs such as ColumnGroup');
+	*     break;
+	*   default:
+	*     console.log('Resolve the unspecified flavor before using flavor-specific APIs');
+	* }
+	* ```
+	*/
+	getDocumentFlavor() {
+		return this._resolveDocumentFlavor();
+	}
+	/**
+	* Whether this is a Traditional document with Word-compatible physical pagination.
+	*
+	* Prefer this positive guard before calling section, column-break, page-setup,
+	* or paragraph-pagination APIs.
+	*
+	* @returns {boolean} `true` only for `DocumentFlavor.TRADITIONAL`.
+	* @example
+	* ```typescript
+	* const document = univerAPI.getActiveDocument();
+	* if (document?.isTraditional()) {
+	*   console.log(document.getSection(0)?.getEffectivePageSetup());
+	* }
+	* ```
+	*/
+	isTraditional() {
+		return this._resolveDocumentFlavor() === _univerjs_core.DocumentFlavor.TRADITIONAL;
+	}
+	/**
+	* Whether this is a Modern document.
+	*
+	* A `false` result can mean either Traditional or Unspecified. Use
+	* `isTraditional()` before Traditional-only APIs, or `getDocumentFlavor()`
+	* when all three states matter.
+	*
+	* @returns {boolean} `true` only for `DocumentFlavor.MODERN`.
 	* @example
 	* ```typescript
 	* const fDocument = univerAPI.getActiveDocument();
-	* console.log(fDocument.isModern());
+	* console.log(fDocument?.isModern());
 	* ```
 	*/
 	isModern() {
-		return this._documentDataModel.getSnapshot().documentStyle.documentFlavor === _univerjs_core.DocumentFlavor.MODERN;
+		return this._resolveDocumentFlavor() === _univerjs_core.DocumentFlavor.MODERN;
+	}
+	_resolveDocumentFlavor() {
+		return this._documentDataModel.getSnapshot().documentStyle.documentFlavor ?? _univerjs_core.DocumentFlavor.UNSPECIFIED;
 	}
 	/**
 	* Save the document snapshot data, including the document content and resource data, etc.
@@ -1231,7 +1495,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 		}, buildPlainTextInsertBody(text), this._documentDataModel, this._injector);
 	}
 	/**
-	* Returns document-level header/footer switches and margins. Margin values are in points (pt).
+	* Returns document-level header/footer switches and margins. Margin values use 96-DPI layout pixels.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1248,12 +1512,18 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 		};
 	}
 	/**
-	* Updates document-level header/footer switches and margins in a traditional document.
-	* `marginHeader` and `marginFooter` are in points (pt).
+	* Updates document-level header/footer switches and margins.
+	*
+	* Traditional and Unspecified documents keep the legacy header/footer
+	* behavior. Modern documents reject this API. `marginHeader` and
+	* `marginFooter` use 96-DPI layout pixels.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (
+	*   fDocument &&
+	*   fDocument.getDocumentFlavor() !== univerAPI.Enum.DocumentFlavor.MODERN
+	* ) {
 	*   fDocument.setHeaderFooterOptions({ marginHeader: 36, marginFooter: 36 });
 	* }
 	* ```
@@ -1294,7 +1564,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 	*/
 	getSections() {
 		if (this._documentDataModel.getSnapshot().documentStyle.documentFlavor !== _univerjs_core.DocumentFlavor.TRADITIONAL) return [];
-		return (0, _univerjs_docs.getTopLevelSectionBreaks)(this.getBody()).map((sectionBreak) => this._injector.createInstance(FDocumentSection, this, sectionBreak.sectionId, this._injector));
+		return (0, _univerjs_docs.getTopLevelSectionBreaks)(this.getBody()).map((sectionBreak) => this._injector.createInstance(FDocumentSection, this, sectionBreak.sectionId));
 	}
 	/**
 	* Returns a traditional section by zero-based index, or `null` in modern documents.
@@ -1306,8 +1576,7 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 	* ```
 	*/
 	getSection(index) {
-		var _this$getSections$ind;
-		return (_this$getSections$ind = this.getSections()[index]) !== null && _this$getSections$ind !== void 0 ? _this$getSections$ind : null;
+		return this.getSections()[index] ?? null;
 	}
 	/**
 	* Returns the traditional section containing a data-stream offset, or `null` in modern documents.
@@ -1321,45 +1590,84 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 	* ```
 	*/
 	getSectionAt(offset) {
-		var _this$getSections$fin;
-		return (_this$getSections$fin = this.getSections().find((section) => {
+		return this.getSections().find((section) => {
 			const range = section.getRange();
-			return offset >= range.startOffset && offset <= range.endOffset;
-		})) !== null && _this$getSections$fin !== void 0 ? _this$getSections$fin : null;
+			return offset >= range.startOffset && offset < range.endOffset;
+		}) ?? null;
 	}
 	/**
 	* Inserts a traditional document section break and returns its stable facade.
-	* Modern documents must use ColumnGroup and throw `DocsSectionUnsupportedDocumentFlavorError`.
-	* Numeric layout values in `config` are in points (pt).
+	*
+	* `options` configures the section created before the inserted break.
+	* Set `options.nextSectionType` to control how the existing section after the
+	* break begins. For example, use `SectionType.NEXT_PAGE` to start a chapter on
+	* a new physical page. Both changes are executed by one command and are
+	* undone or redone together.
+	*
+	* The offset must be a top-level document position. To insert a break before
+	* a table or block such as a callout, use that object's start offset instead
+	* of an offset inside the object.
+	*
+	* Modern documents must use ColumnGroup. Unspecified documents must resolve
+	* their flavor first. Both throw `DocsSectionUnsupportedDocumentFlavorError`.
+	* Numeric layout values in `options` are in 96-DPI layout pixels.
+	*
+	* @param {number} offset Top-level data-stream offset where the section break is inserted.
+	* @param {IFDocumentInsertSectionBreakOptions} [options] Section properties and the optional type of the following section.
+	* @returns {FDocumentSection | null} The section created before the break, or `null` when the command rejects the insertion.
 	* @example
 	* ```ts
-	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
-	*   const paragraph = fDocument.findParagraphByText('Appendix');
-	*   const offset = paragraph?.getInfo().startOffset;
-	*   const section = offset == null ? null : fDocument.insertSectionBreak(offset);
-	*   console.log(section?.getId());
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) {
+	*   throw new Error('No active document');
+	* }
+	* if (!document.isTraditional()) {
+	*   throw new Error('Traditional document sections are required');
+	* }
+	*
+	* const chapter = document.findParagraphByText('Chapter 2');
+	* if (!chapter) {
+	*   throw new Error('Chapter heading not found');
+	* }
+	*
+	* // Insert the boundary immediately before the chapter heading. The command
+	* // also marks the following section as NEXT_PAGE, so the two model changes
+	* // share one undo/redo step.
+	* const sectionBeforeChapter = document.insertSectionBreak(
+	*   chapter.getInfo().startOffset,
+	*   { nextSectionType: univerAPI.Enum.SectionType.NEXT_PAGE }
+	* );
+	* if (!sectionBeforeChapter) {
+	*   throw new Error('The chapter heading is not at a valid top-level offset');
 	* }
+	*
+	* console.log({
+	*   insertedSection: sectionBeforeChapter.describe(),
+	*   chapterSection: document.getSectionAt(chapter.getInfo().startOffset)?.describe(),
+	* });
 	* ```
 	*/
-	insertSectionBreak(offset, config = {}) {
-		var _this$getBody$section;
+	insertSectionBreak(offset, options = {}) {
 		if (this._documentDataModel.getSnapshot().documentStyle.documentFlavor !== _univerjs_core.DocumentFlavor.TRADITIONAL) throw new DocsSectionUnsupportedDocumentFlavorError();
-		const sectionId = (0, _univerjs_core.createSectionId)(new Set(((_this$getBody$section = this.getBody().sectionBreaks) !== null && _this$getBody$section !== void 0 ? _this$getBody$section : []).map((section) => section.sectionId)));
+		const { nextSectionType, ...config } = options;
+		const sectionId = (0, _univerjs_core.createSectionId)(new Set((this.getBody().sectionBreaks ?? []).map((section) => section.sectionId)));
 		return this._commandService.syncExecuteCommand(_univerjs_docs.InsertDocumentSectionBreakCommand.id, {
 			unitId: this.getId(),
 			offset,
 			sectionId,
-			config
-		}) ? this._injector.createInstance(FDocumentSection, this, sectionId, this._injector) : null;
+			config,
+			nextSectionType
+		}) ? this._injector.createInstance(FDocumentSection, this, sectionId) : null;
 	}
 	/**
 	* Inserts a column-break token in a traditional document.
-	* Modern documents must use ColumnGroup and throw `DocsSectionUnsupportedDocumentFlavorError`.
+	* In a single-column section, the traditional renderer advances to the next physical page.
+	* Modern documents must use ColumnGroup. Unspecified documents must resolve
+	* their flavor first. Both throw `DocsSectionUnsupportedDocumentFlavorError`.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
-	* if (fDocument && !fDocument.isModern()) {
+	* if (fDocument?.isTraditional()) {
 	*   const paragraph = fDocument.findParagraphByText('Continue in next column');
 	*   const offset = paragraph?.getInfo().startOffset;
 	*   if (offset != null) {
@@ -1370,7 +1678,10 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 	*/
 	insertColumnBreak(offset) {
 		if (this._documentDataModel.getSnapshot().documentStyle.documentFlavor !== _univerjs_core.DocumentFlavor.TRADITIONAL) throw new DocsSectionUnsupportedDocumentFlavorError();
-		return this.insertText(offset, _univerjs_core.DataStreamTreeTokenType.COLUMN_BREAK);
+		return this._commandService.syncExecuteCommand(_univerjs_docs.InsertDocumentColumnBreakCommand.id, {
+			unitId: this.getId(),
+			offset
+		});
 	}
 	/**
 	* Inserts a horizontal rule using the existing paragraph `borderBottom` mechanism.
@@ -1593,36 +1904,29 @@ let FDocument = class FDocument extends _univerjs_core_facade.FBaseInitialable {
 		return segmentId;
 	}
 	_getHeaderFooterCreateInfo(kind, pageIndex) {
-		var _documentStyle$defaul, _documentStyle$defaul2;
 		const { documentStyle } = this._documentDataModel.getSnapshot();
 		const isFirstPage = pageIndex === 0;
 		const isEvenPage = (pageIndex + 1) % 2 === 0;
-		if (isFirstPage && documentStyle.useFirstPageHeaderFooter === _univerjs_core.BooleanNumber.TRUE) {
-			var _documentStyle$firstP, _documentStyle$firstP2;
-			return kind === "header" ? {
-				createType: _univerjs_docs.HeaderFooterType.FIRST_PAGE_HEADER,
-				segmentId: (_documentStyle$firstP = documentStyle.firstPageHeaderId) !== null && _documentStyle$firstP !== void 0 ? _documentStyle$firstP : ""
-			} : {
-				createType: _univerjs_docs.HeaderFooterType.FIRST_PAGE_FOOTER,
-				segmentId: (_documentStyle$firstP2 = documentStyle.firstPageFooterId) !== null && _documentStyle$firstP2 !== void 0 ? _documentStyle$firstP2 : ""
-			};
-		}
-		if (isEvenPage && documentStyle.evenAndOddHeaders === _univerjs_core.BooleanNumber.TRUE) {
-			var _documentStyle$evenPa, _documentStyle$evenPa2;
-			return kind === "header" ? {
-				createType: _univerjs_docs.HeaderFooterType.EVEN_PAGE_HEADER,
-				segmentId: (_documentStyle$evenPa = documentStyle.evenPageHeaderId) !== null && _documentStyle$evenPa !== void 0 ? _documentStyle$evenPa : ""
-			} : {
-				createType: _univerjs_docs.HeaderFooterType.EVEN_PAGE_FOOTER,
-				segmentId: (_documentStyle$evenPa2 = documentStyle.evenPageFooterId) !== null && _documentStyle$evenPa2 !== void 0 ? _documentStyle$evenPa2 : ""
-			};
-		}
+		if (isFirstPage && documentStyle.useFirstPageHeaderFooter === _univerjs_core.BooleanNumber.TRUE) return kind === "header" ? {
+			createType: _univerjs_docs.HeaderFooterType.FIRST_PAGE_HEADER,
+			segmentId: documentStyle.firstPageHeaderId ?? ""
+		} : {
+			createType: _univerjs_docs.HeaderFooterType.FIRST_PAGE_FOOTER,
+			segmentId: documentStyle.firstPageFooterId ?? ""
+		};
+		if (isEvenPage && documentStyle.evenAndOddHeaders === _univerjs_core.BooleanNumber.TRUE) return kind === "header" ? {
+			createType: _univerjs_docs.HeaderFooterType.EVEN_PAGE_HEADER,
+			segmentId: documentStyle.evenPageHeaderId ?? ""
+		} : {
+			createType: _univerjs_docs.HeaderFooterType.EVEN_PAGE_FOOTER,
+			segmentId: documentStyle.evenPageFooterId ?? ""
+		};
 		return kind === "header" ? {
 			createType: _univerjs_docs.HeaderFooterType.DEFAULT_HEADER,
-			segmentId: (_documentStyle$defaul = documentStyle.defaultHeaderId) !== null && _documentStyle$defaul !== void 0 ? _documentStyle$defaul : ""
+			segmentId: documentStyle.defaultHeaderId ?? ""
 		} : {
 			createType: _univerjs_docs.HeaderFooterType.DEFAULT_FOOTER,
-			segmentId: (_documentStyle$defaul2 = documentStyle.defaultFooterId) !== null && _documentStyle$defaul2 !== void 0 ? _documentStyle$defaul2 : ""
+			segmentId: documentStyle.defaultFooterId ?? ""
 		};
 	}
 };
@@ -1671,6 +1975,9 @@ _univerjs_core_facade.FUniver.extend(FUniverDocsMixin);
 * limitations under the License.
 */
 var FDocsEnumMixin = class extends _univerjs_core_facade.FEnum {
+	get DocumentFlavor() {
+		return _univerjs_core.DocumentFlavor;
+	}
 	get SectionType() {
 		return _univerjs_core.SectionType;
 	}
@@ -1689,8 +1996,18 @@ Object.defineProperty(exports, 'FDocument', {
     return FDocument;
   }
 });
-exports.FDocumentParagraph = FDocumentParagraph;
-exports.FDocumentSection = FDocumentSection;
+Object.defineProperty(exports, 'FDocumentParagraph', {
+  enumerable: true,
+  get: function () {
+    return FDocumentParagraph;
+  }
+});
+Object.defineProperty(exports, 'FDocumentSection', {
+  enumerable: true,
+  get: function () {
+    return FDocumentSection;
+  }
+});
 exports.FDocumentTextRange = FDocumentTextRange;
 exports.isParagraphFacade = isParagraphFacade;
 exports.stripBlockTokens = stripBlockTokens;