@univerjs/docs 1.0.0-insiders.20260813-7c9aa50 → 1.0.0

package/lib/es/facade.js

@@ -1,7 +1,219 @@
-import { BooleanNumber, ColumnSeparatorType, DashStyleType, DataStreamTreeTokenType, DocumentFlavor, ICommandService, IResourceLoaderService, IUniverInstanceService, Inject, Injector, JSONX, PageOrientType, PresetListType, RESTORE_INSERTED_PARAGRAPH_IDS, RedoCommand, SectionType, TextX, TextXActionType, Tools, UndoCommand, UniverInstanceType, UpdateDocsAttributeType, createParagraphId, createSectionId, generateRandomId, getParagraphContentStartOffset, getRichTextEditPath, getSectionHeaderFooterReferenceKey, regexp, resolveSectionHeaderFooterReference } from "@univerjs/core";
+import { BooleanNumber, ColumnSeparatorType, DashStyleType, DataStreamTreeTokenType, DocumentFlavor, ICommandService, IPermissionService, IResourceLoaderService, IUniverInstanceService, Inject, Injector, JSONX, PageOrientType, PresetListType, RESTORE_INSERTED_PARAGRAPH_IDS, RedoCommand, SectionType, TextX, TextXActionType, Tools, UndoCommand, UniverInstanceType, UpdateDocsAttributeType, createParagraphId, createSectionId, generateRandomId, getParagraphContentStartOffset, getRichTextEditPath, getSectionHeaderFooterReferenceKey, regexp, resolveSectionHeaderFooterReference } from "@univerjs/core";
 import { FBaseInitialable, FEnum, FUniver } from "@univerjs/core/facade";
-import { CreateHeaderFooterCommand, DeleteDocumentSectionBreakCommand, HeaderFooterType, InsertDocumentColumnBreakCommand, InsertDocumentSectionBreakCommand, RichTextEditingMutation, SetDocumentNameCommand, SetSectionHeaderFooterLinkCommand, UpdateDocumentParagraphStyleCommand, UpdateDocumentSectionCommand, createSectionColumnProperties, generateParagraphs, getEffectiveSectionPageSetup, getSectionContentWidth, getTopLevelSectionBreaks } from "@univerjs/docs";
+import { CreateHeaderFooterCommand, DeleteDocumentSectionBreakCommand, HeaderFooterType, InsertDocumentColumnBreakCommand, InsertDocumentSectionBreakCommand, InsertTextCommand, RichTextEditingMutation, SetDocumentNameCommand, SetDocumentPermissionCommand, SetDocumentPermissionsCommand, SetSectionHeaderFooterLinkCommand, UpdateDocumentParagraphStyleCommand, UpdateDocumentSectionCommand, canEditDocumentTargets, createSectionColumnProperties, generateParagraphs, getDocumentEntityParentPermissionObjectIds, getDocumentEntityPermissionObjectId, getDocumentParagraphParentPermissionObjectIds, getDocumentParagraphPermissionObjectId, getDocumentPermissionValue, getDocumentSectionPermissionObjectId, getEffectiveSectionPageSetup, getSectionContentWidth, getTopLevelSectionBreaks } from "@univerjs/docs";
+import { UnitAction } from "@univerjs/protocol";
 
+//#region src/facade/f-document-permission.ts
+/**
+* Command-backed permissions for one Document unit.
+* @hideconstructor
+*/
+var FDocumentPermission = class {
+	constructor(_unitId, _commandService, _permissionService) {
+		this._unitId = _unitId;
+		this._commandService = _commandService;
+		this._permissionService = _permissionService;
+	}
+	/**
+	* Creates or updates child-object edit policies in this unit; policy: null removes protection and restores inheritance.
+	*
+	* Requires Authz support and objectPermissionTypes configured for every target type. File and parent restrictions
+	* still apply. Use the exported permission object ID helpers, not raw object IDs or server permission IDs.
+	* The batch must be nonempty, contain distinct objects, and belong to this unit; file-wide policies are excluded.
+	* Other targets use getDocumentSectionPermissionObjectId and getDocumentEntityPermissionObjectId.
+	*
+	* edit: 'all' allows Unit editors, 'owner' restricts editing to the object owner, and 'members' selects existing
+	* Unit collaborators. Pass their collaborator records from the member service; this does not invite new users.
+	* Use strategies: [] for the default Edit strategy; child-object strategies support only UnitAction.Edit.
+	*
+	* Authz writes execute per object and can partially succeed. Inspect failed before retrying only those objects.
+	* refreshError means writes finished but permission readback failed; do not retry succeeded objects for that error.
+	* Successful binding changes share one undo entry; existing remote policy edits are not undoable.
+	* @param {IObjectPermissionChange[]} changes Permission object IDs and policies to apply.
+	* @returns {Promise<IObjectPermissionBatchResult>} Successful object IDs, per-object failures, and optional readback error.
+	* @throws {Error} Invalid batches or unsupported object types are rejected before Authz writes.
+	* @example Set owner/member editing and remove protection in one batch
+	* ```ts
+	* import type { ICollaborator } from '@univerjs/protocol';
+	* import { getDocumentParagraphPermissionObjectId } from '@univerjs/docs';
+	*
+	* // selectedMembers comes from the existing Unit collaborator picker/service.
+	* async function applyPermissions(selectedMembers: ICollaborator[]) {
+	*     if (!selectedMembers.length) throw new Error('Select at least one Unit collaborator.');
+	*     const document = univerAPI.getActiveDocument();
+	*     if (!document) throw new Error('No active document.');
+	*     const objects = document.getParagraphs().slice(0, 3);
+	*     const objectIds = objects.map((paragraph) =>
+	*         getDocumentParagraphPermissionObjectId(paragraph.getSegmentId(), paragraph.getId()));
+	*     if (objectIds.length < 3) throw new Error('This example requires three paragraphs.');
+	*     const result = await document.getPermission().setObjectPermissions([
+	*         { objectId: objectIds[0], policy: { edit: 'owner', collaborators: [], strategies: [] } },
+	*         { objectId: objectIds[1], policy: { edit: 'members', collaborators: selectedMembers, strategies: [] } },
+	*         { objectId: objectIds[2], policy: null },
+	*     ]);
+	*     // A policy creates protection if absent, or updates the existing policy when already configured.
+	*     for (const failure of result.failed) {
+	*         console.error(failure.objectId, failure.error);
+	*     }
+	*     if (result.refreshError) {
+	*         console.error(result.refreshError);
+	*     }
+	*     return result;
+	* }
+	* ```
+	*/
+	async setObjectPermissions(changes) {
+		return this._commandService.executeCommand(SetDocumentPermissionsCommand.id, {
+			unitId: this._unitId,
+			changes
+		});
+	}
+	/**
+	* Sets one Document unit permission through the command system.
+	*
+	* Supported actions are Edit, Copy, Print, Export, and Comment. Await the returned promise
+	* before reading the new value or performing an action that depends on it.
+	*
+	* @param {DocumentUnitPermissionAction} action Unit permission action to update.
+	* @param {boolean} value Whether the action is allowed.
+	* @returns {Promise<void>} Resolves after the permission command finishes.
+	* @example Disable copying while keeping the Document editable
+	* ```ts
+	* import { UnitAction } from '@univerjs/protocol';
+	*
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) throw new Error('No active Document.');
+	* await document.getPermission().setPoint(UnitAction.Copy, false);
+	* ```
+	*/
+	async setPoint(action, value) {
+		await this._commandService.executeCommand(SetDocumentPermissionCommand.id, {
+			unitId: this._unitId,
+			objectId: this._unitId,
+			action,
+			value
+		});
+	}
+	/**
+	* Returns the current value of one Document unit permission.
+	* @param {DocumentUnitPermissionAction} action Unit permission action to query.
+	* @returns {boolean} Whether the action is currently allowed.
+	* @example
+	* ```ts
+	* import { UnitAction } from '@univerjs/protocol';
+	*
+	* const document = univerAPI.getActiveDocument();
+	* const canPrint = document?.getPermission().getPoint(UnitAction.Print) ?? false;
+	* console.log(canPrint);
+	* ```
+	*/
+	getPoint(action) {
+		return getDocumentPermissionValue(this._permissionService, this._unitId, this._unitId, action);
+	}
+	/**
+	* Enables or disables editing for the whole Document.
+	* @param {boolean} [editable] Whether editing is allowed. Defaults to true.
+	* @returns {Promise<void>} Resolves after the permission command finishes.
+	*/
+	async setEditable(editable = true) {
+		await this._commandService.executeCommand(SetDocumentPermissionCommand.id, {
+			unitId: this._unitId,
+			objectId: this._unitId,
+			action: UnitAction.Edit,
+			value: editable
+		});
+	}
+	/**
+	* Makes the whole Document read-only.
+	* @returns {Promise<void>} Resolves after the permission command finishes.
+	* @example
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) throw new Error('No active Document.');
+	* await document.getPermission().setReadOnly();
+	* ```
+	*/
+	async setReadOnly() {
+		await this._commandService.executeCommand(SetDocumentPermissionCommand.id, {
+			unitId: this._unitId,
+			objectId: this._unitId,
+			action: UnitAction.Edit,
+			value: false
+		});
+	}
+	/**
+	* Returns whether the whole Document is currently editable.
+	* @returns {boolean} Whether Document editing is allowed.
+	*/
+	canEdit() {
+		return getDocumentPermissionValue(this._permissionService, this._unitId, this._unitId, UnitAction.Edit);
+	}
+};
+/**
+* Command-backed Edit permission for one stable Document object.
+* @hideconstructor
+*/
+var FDocumentObjectPermission = class {
+	constructor(_unitId, _objectId, _commandService, _permissionService, _getParentObjectIds = () => []) {
+		this._unitId = _unitId;
+		this._objectId = _objectId;
+		this._commandService = _commandService;
+		this._permissionService = _permissionService;
+		this._getParentObjectIds = _getParentObjectIds;
+	}
+	/**
+	* Enables or disables editing for this stable Document object.
+	*
+	* This changes only the object's Edit point. `canEdit()` also applies the Document unit and
+	* parent Section or Paragraph ceilings.
+	*
+	* @param {boolean} [editable] Whether object editing is allowed. Defaults to true.
+	* @returns {Promise<void>} Resolves after the permission command finishes.
+	* @example Restore editing for a paragraph
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* const paragraph = document?.getParagraphs()[0];
+	* if (!paragraph) throw new Error('Paragraph not found.');
+	* await paragraph.getPermission().setEditable();
+	* ```
+	*/
+	async setEditable(editable = true) {
+		await this._commandService.executeCommand(SetDocumentPermissionCommand.id, {
+			unitId: this._unitId,
+			objectId: this._objectId,
+			action: UnitAction.Edit,
+			value: editable
+		});
+	}
+	/**
+	* Makes this stable Document object read-only.
+	* @returns {Promise<void>} Resolves after the permission command finishes.
+	* @example
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* const section = document?.getSection(0);
+	* if (!section) throw new Error('Section not found.');
+	* await section.getPermission().setReadOnly();
+	* ```
+	*/
+	async setReadOnly() {
+		await this._commandService.executeCommand(SetDocumentPermissionCommand.id, {
+			unitId: this._unitId,
+			objectId: this._objectId,
+			action: UnitAction.Edit,
+			value: false
+		});
+	}
+	/**
+	* Returns the effective Edit result after applying the Document, parent, and object permissions.
+	* @returns {boolean} Whether the object is currently editable.
+	*/
+	canEdit() {
+		return canEditDocumentTargets(this._permissionService, this._unitId, [...this._getParentObjectIds(), this._objectId]);
+	}
+};
+
+//#endregion
 //#region src/facade/utils.ts
 function cloneParagraphStyle(paragraphStyle) {
 	return paragraphStyle == null ? paragraphStyle : JSON.parse(JSON.stringify(paragraphStyle));
@@ -32,31 +244,24 @@ function buildPlainTextInsertBody(dataStream, options = {}) {
 	if (paragraphs.length > 0) body.paragraphs = paragraphs;
 	return body;
 }
-function replaceBodyRange(range, insertBody, docDataModel, injector) {
+function replaceBodyRange(range, insertBody, docDataModel, commandService) {
 	const { startOffset, endOffset, segmentId } = range;
-	const textX = new TextX();
-	if (startOffset > 0) textX.push({
-		t: TextXActionType.RETAIN,
-		len: startOffset
-	});
-	if (endOffset > startOffset) textX.push({
-		t: TextXActionType.DELETE,
-		len: endOffset - startOffset
-	});
-	if (insertBody.dataStream.length > 0) textX.push({
-		t: TextXActionType.INSERT,
-		body: insertBody,
-		len: insertBody.dataStream.length
-	});
-	const actions = JSONX.getInstance().editOp(textX.serialize(), getRichTextEditPath(docDataModel, segmentId));
-	const result = injector.get(ICommandService).syncExecuteCommand(RichTextEditingMutation.id, {
+	const result = commandService.syncExecuteCommand(InsertTextCommand.id, {
 		unitId: docDataModel.getUnitId(),
+		body: insertBody,
+		range: {
+			startOffset,
+			endOffset,
+			collapsed: startOffset === endOffset,
+			segmentId
+		},
 		segmentId,
-		actions,
+		debounce: false,
 		textRanges: [],
+		noNeedSetTextRange: true,
 		isEditing: false
 	});
-	return Boolean((result === null || result === void 0 ? void 0 : result.actions) && result.actions.length > 0);
+	return Boolean(result);
 }
 function retainBodyRange(range, updateBody, coverType, docDataModel, injector) {
 	var _updateBody$textRuns, _docDataModel$getSelf;
@@ -97,23 +302,34 @@ function stripBlockTokens(text) {
 	return Array.from(text).map((char) => char === DataStreamTreeTokenType.PARAGRAPH ? "\n" : char).filter((char) => char !== DataStreamTreeTokenType.BLOCK_START && char !== DataStreamTreeTokenType.BLOCK_END && char !== DataStreamTreeTokenType.SECTION_BREAK).join("").replace(/\n$/, "");
 }
 
+//#endregion
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.149.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-text-range.ts
-/**
-* Facade wrapper for reading and styling a fixed document text range.
-*
-* Offsets are fixed when the wrapper is created. Create a new range after edits
-* that insert or remove content before it.
-* @hideconstructor
-*/
-var FDocumentTextRange = class extends FBaseInitialable {
-	constructor(_document, _startOffset, _endOffset, _segmentId, _injector) {
+let FDocumentTextRange = class FDocumentTextRange extends FBaseInitialable {
+	constructor(_document, _startOffset, _endOffset, _segmentId, _injector, _commandService) {
 		super(_injector);
 		this._document = _document;
 		this._startOffset = _startOffset;
 		this._endOffset = _endOffset;
 		this._segmentId = _segmentId;
 		this._injector = _injector;
+		this._commandService = _commandService;
 		this._validateRange();
 	}
 	/**
@@ -204,6 +420,8 @@ var FDocumentTextRange = class extends FBaseInitialable {
 	* Existing text-run splitting, merging, and normalization are handled by
 	* the document mutation pipeline.
 	* `style.fs` is a font size in points (pt), not CSS pixels.
+	* @param {ITextStyle} style Text-style properties to merge into the range.
+	* @returns {boolean} Whether the style update succeeded; `false` for an empty range.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -224,6 +442,8 @@ var FDocumentTextRange = class extends FBaseInitialable {
 	}
 	/**
 	* Replaces the range with plain text while preserving document mutation semantics.
+	* @param {string} text Replacement plain text. An empty string deletes the range.
+	* @returns {boolean} Whether the replacement succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -232,7 +452,7 @@ var FDocumentTextRange = class extends FBaseInitialable {
 	* ```
 	*/
 	setText(text) {
-		return replaceBodyRange(this.getRange(), buildPlainTextInsertBody(text), this._document.getDocumentDataModel(), this._injector);
+		return replaceBodyRange(this.getRange(), buildPlainTextInsertBody(text), this._document.getDocumentDataModel(), this._commandService);
 	}
 	_validateRange() {
 		const bodyLength = this._document.getBody(this._segmentId).dataStream.length;
@@ -259,37 +479,22 @@ var FDocumentTextRange = class extends FBaseInitialable {
 		return segments;
 	}
 };
+FDocumentTextRange = __decorate([__decorateParam(5, ICommandService)], FDocumentTextRange);
 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
 let FDocumentParagraph = class FDocumentParagraph extends FBaseInitialable {
-	constructor(_document, _paragraphId, _segmentId = "", _injector, _commandService) {
+	constructor(_document, _paragraphId, _segmentId = "", _injector, _commandService, _permissionService) {
 		super(_injector);
 		this._document = _document;
 		this._paragraphId = _paragraphId;
 		this._segmentId = _segmentId;
 		this._injector = _injector;
 		this._commandService = _commandService;
+		this._permissionService = _permissionService;
 	}
 	/**
 	* Get the persisted paragraph id.
@@ -320,6 +525,19 @@ let FDocumentParagraph = class FDocumentParagraph extends FBaseInitialable {
 		return this._segmentId;
 	}
 	/**
+	* Returns this Paragraph's permission facade.
+	* @returns {FDocumentObjectPermission} Permission facade combining Document, Section, and Paragraph Edit points.
+	* @example
+	* ```ts
+	* const paragraph = univerAPI.getActiveDocument()?.getParagraphs()[0];
+	* if (!paragraph) throw new Error('Paragraph not found.');
+	* await paragraph.getPermission().setReadOnly();
+	* ```
+	*/
+	getPermission() {
+		return new FDocumentObjectPermission(this._document.getId(), getDocumentParagraphPermissionObjectId(this._segmentId, this._paragraphId), this._commandService, this._permissionService, () => getDocumentParagraphParentPermissionObjectIds(this._document.getDocumentDataModel(), this._segmentId, this._paragraphId));
+	}
+	/**
 	* Get this paragraph's metadata.
 	* @returns {IFDocumentParagraphInfo} The paragraph info.
 	* @example
@@ -477,7 +695,7 @@ let FDocumentParagraph = class FDocumentParagraph extends FBaseInitialable {
 			startOffset,
 			endOffset,
 			segmentId: this._segmentId
-		}, buildPlainTextInsertBody(text), this._document.getDocumentDataModel(), this._injector);
+		}, buildPlainTextInsertBody(text), this._document.getDocumentDataModel(), this._commandService);
 	}
 	/**
 	* Append plain text before this paragraph's trailing paragraph break.
@@ -646,7 +864,7 @@ let FDocumentParagraph = class FDocumentParagraph extends FBaseInitialable {
 		body[RESTORE_INSERTED_PARAGRAPH_IDS] = true;
 	}
 };
-FDocumentParagraph = __decorate([__decorateParam(4, ICommandService)], FDocumentParagraph);
+FDocumentParagraph = __decorate([__decorateParam(4, ICommandService), __decorateParam(5, IPermissionService)], 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";
@@ -674,10 +892,11 @@ var DocsSectionUnsupportedDocumentFlavorError = class extends Error {
 	}
 };
 let FDocumentSection = class FDocumentSection {
-	constructor(_document, _sectionId, _commandService) {
+	constructor(_document, _sectionId, _commandService, _permissionService) {
 		this._document = _document;
 		this._sectionId = _sectionId;
 		this._commandService = _commandService;
+		this._permissionService = _permissionService;
 	}
 	/**
 	* Returns the persisted section id.
@@ -691,6 +910,19 @@ let FDocumentSection = class FDocumentSection {
 		return this._sectionId;
 	}
 	/**
+	* Returns this Section's permission facade.
+	* @returns {FDocumentObjectPermission} Permission facade combining Document and Section Edit points.
+	* @example
+	* ```ts
+	* const section = univerAPI.getActiveDocument()?.getSection(0);
+	* if (!section) throw new Error('Section not found.');
+	* await section.getPermission().setReadOnly();
+	* ```
+	*/
+	getPermission() {
+		return new FDocumentObjectPermission(this._document.getId(), getDocumentSectionPermissionObjectId("", this._sectionId), this._commandService, this._permissionService);
+	}
+	/**
 	* Returns the current zero-based section index.
 	* @example
 	* ```ts
@@ -771,6 +1003,10 @@ let FDocumentSection = class FDocumentSection {
 	* Sets equal or explicitly sized columns for this traditional section.
 	* Use `columnCount = 1` to restore normal single-column layout.
 	* `gap` and `widths` are in 96-DPI layout pixels.
+	* @param {number} columnCount Positive integer column count.
+	* @param {IFDocumentSectionColumnOptions} [options] Column widths, gap (default 18 pixels), and separator (default none).
+	* @returns {boolean} Whether the section update succeeded.
+	* @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -796,6 +1032,10 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Sets explicit OOXML-compatible column width and trailing-space values in 96-DPI layout pixels.
+	* @param {ISectionColumnProperties[]} columns Explicit widths and trailing spaces; an empty array restores a single column.
+	* @param {ColumnSeparatorType} [separator] Column separator style. Defaults to `ColumnSeparatorType.NONE`.
+	* @returns {boolean} Whether the section update succeeded.
+	* @throws {RangeError} If column dimensions or the separator are invalid, or columns exceed the available width.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -962,6 +1202,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Ensures a header segment linked specifically to this section.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string} The existing or newly created section-specific segment ID.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -978,6 +1220,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Ensures a footer segment linked specifically to this section.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string} The existing or newly created section-specific segment ID.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -994,6 +1238,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Returns the effective header id after resolving links to previous sections.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string | null} The effective segment ID, or `null` if no segment is available.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1005,6 +1251,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Returns the effective footer id after resolving links to previous sections.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {string | null} The effective segment ID, or `null` if no segment is available.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1016,6 +1264,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Whether this header variant inherits the previous section's reference.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether this variant inherits from the previous section.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1027,6 +1277,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Whether this footer variant inherits the previous section's reference.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether this variant inherits from the previous section.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1038,6 +1290,9 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Links or unlinks this header variant. Unlinking clones the inherited header.
+	* @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether the link update succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1051,6 +1306,9 @@ let FDocumentSection = class FDocumentSection {
 	}
 	/**
 	* Links or unlinks this footer variant. Unlinking clones the inherited footer.
+	* @param {boolean} linkedToPrevious Whether to inherit the previous section's header/footer.
+	* @param {SectionHeaderFooterVariant} [variant] The `'default'`, `'first'`, or `'even'` variant. Defaults to `'default'`.
+	* @returns {boolean} Whether the link update succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1065,6 +1323,8 @@ let FDocumentSection = class FDocumentSection {
 	/**
 	* Updates header/footer switches and margins on this section break.
 	* `marginHeader` and `marginFooter` are in 96-DPI layout pixels.
+	* @param {IHeaderFooterProps} options Header/footer switches and margins to update. Omitted properties are preserved.
+	* @returns {boolean} Whether the update command succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1144,7 +1404,8 @@ let FDocumentSection = class FDocumentSection {
 	}
 	_getHeaderFooterReference(kind, variant) {
 		const { index } = this._resolve();
-		return resolveSectionHeaderFooterReference(this._document.getDocumentDataModel().getSnapshot().documentStyle, getTopLevelSectionBreaks(this._document.getBody()), index, getSectionHeaderFooterReferenceKey(kind, variant));
+		const snapshot = this._document.getDocumentDataModel().getSnapshot();
+		return resolveSectionHeaderFooterReference(snapshot.documentStyle, getTopLevelSectionBreaks(this._document.getBody()), index, getSectionHeaderFooterReferenceKey(kind, variant));
 	}
 	_describeHeaderFooterReference(kind, variant) {
 		const reference = this._getHeaderFooterReference(kind, variant);
@@ -1189,10 +1450,10 @@ let FDocumentSection = class FDocumentSection {
 		};
 	}
 };
-FDocumentSection = __decorate([__decorateParam(2, ICommandService)], FDocumentSection);
+FDocumentSection = __decorate([__decorateParam(2, ICommandService), __decorateParam(3, IPermissionService)], FDocumentSection);
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -1203,7 +1464,7 @@ function _typeof(o) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -1216,14 +1477,14 @@ function toPrimitive(t, r) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.149.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.140.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -1236,19 +1497,20 @@ function _defineProperty(e, r, t) {
 //#endregion
 //#region src/facade/f-document.ts
 let FDocument = class FDocument extends FBaseInitialable {
-	constructor(_documentDataModel, _injector, _univerInstanceService, _resourceLoaderService, _commandService) {
+	constructor(_documentDataModel, _injector, _univerInstanceService, _resourceLoaderService, _commandService, _permissionService) {
 		super(_injector);
 		this._documentDataModel = _documentDataModel;
 		this._injector = _injector;
 		this._univerInstanceService = _univerInstanceService;
 		this._resourceLoaderService = _resourceLoaderService;
 		this._commandService = _commandService;
+		this._permissionService = _permissionService;
 		_defineProperty(this, "id", void 0);
 		this.id = this._documentDataModel.getUnitId();
 	}
 	/**
 	* Get the document data model of the document.
-	* @param {string} segmentId The segment id used to get the header/footer data model. Defaults to an empty string for the document data model of the document.
+	* @param {string} [segmentId] The segment id used to get the header/footer data model. Defaults to an empty string for the document data model of the document.
 	* @returns {DocumentDataModel} The document data model.
 	* @example
 	* ```typescript
@@ -1290,7 +1552,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* 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.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {IDocumentBody} The document body.
 	* @example
 	* ```typescript
@@ -1307,6 +1569,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 		if (!body) throw new Error(segmentId === "" ? "Body is not found in the document." : `Body is not found in the segment: ${segmentId}`);
 		return body;
 	}
+	/** Releases this facade's resources. Use `univerAPI.disposeUnit()` to unload the owning unit. */
 	dispose() {
 		super.dispose();
 	}
@@ -1323,6 +1586,40 @@ let FDocument = class FDocument extends FBaseInitialable {
 		return this.id;
 	}
 	/**
+	* Returns the Document unit permission facade.
+	* @returns {FDocumentPermission} Permission facade for Edit, Copy, Print, Export, and Comment.
+	* @example
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) throw new Error('No active Document.');
+	* await document.getPermission().setReadOnly();
+	* ```
+	*/
+	getPermission() {
+		return new FDocumentPermission(this.id, this._commandService, this._permissionService);
+	}
+	/**
+	* Returns the permission facade for an entity with a stable id, such as a Table, Drawing, or Custom Block.
+	*
+	* Parent Section and Paragraph permission ceilings are resolved from the current Document model.
+	* @param {string} segmentId Segment id, or an empty string for the main body.
+	* @param {string} entityType Stable entity type used by the owning Doc feature.
+	* @param {string} entityId Stable entity id.
+	* @returns {FDocumentObjectPermission} Effective permission facade for the entity.
+	* @example Make one drawing read-only
+	* ```ts
+	* const document = univerAPI.getActiveDocument();
+	* if (!document) throw new Error('No active Document.');
+	* const snapshot = document.getDocumentDataModel().getSnapshot();
+	* const drawingId = snapshot.drawingsOrder?.[0];
+	* if (!drawingId) throw new Error('Drawing not found.');
+	* await document.getEntityPermission('', 'drawing', drawingId).setReadOnly();
+	* ```
+	*/
+	getEntityPermission(segmentId, entityType, entityId) {
+		return new FDocumentObjectPermission(this.id, getDocumentEntityPermissionObjectId(segmentId, entityType, entityId), this._commandService, this._permissionService, () => getDocumentEntityParentPermissionObjectIds(this._documentDataModel, segmentId, entityType, entityId));
+	}
+	/**
 	* Get the document name.
 	* @returns {string} The document name.
 	* @example
@@ -1463,7 +1760,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Ensure the page header segment exists and return its segment id.
-	* @param {number} pageIndex The zero-based page index. Defaults to the first page.
+	* @param {number} [pageIndex] The zero-based page index. Defaults to the first page.
 	* @returns {string} The header segment id.
 	* @example
 	* ```ts
@@ -1477,7 +1774,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Ensure the page footer segment exists and return its segment id.
-	* @param {number} pageIndex The zero-based page index. Defaults to the first page.
+	* @param {number} [pageIndex] The zero-based page index. Defaults to the first page.
 	* @returns {string} The footer segment id.
 	* @example
 	* ```ts
@@ -1493,7 +1790,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* Insert plain text at a document body offset.
 	* @param {number} index The zero-based insertion offset.
 	* @param {string} text The plain text to insert.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {boolean} `true` if the edit was applied.
 	* @example
 	* ```ts
@@ -1509,7 +1806,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 			startOffset: index,
 			endOffset: index,
 			segmentId
-		}, buildPlainTextInsertBody(text), this._documentDataModel, this._injector);
+		}, buildPlainTextInsertBody(text), this._documentDataModel, this._commandService);
 	}
 	/**
 	* Returns document-level header/footer switches and margins. Margin values use 96-DPI layout pixels.
@@ -1534,6 +1831,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* Traditional and Unspecified documents keep the legacy header/footer
 	* behavior. Modern documents reject this API. `marginHeader` and
 	* `marginFooter` use 96-DPI layout pixels.
+	* @param {IHeaderFooterProps} options Header/footer switches and margins to update. Omitted properties are preserved.
+	* @returns {boolean} Whether the update command succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1557,7 +1856,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* The end offset is exclusive, and offsets are scoped to the selected body segment.
 	* @param {number} startOffset The inclusive start offset.
 	* @param {number} endOffset The exclusive end offset.
-	* @param {string} segmentId The header/footer segment id, or an empty string for the main body.
+	* @param {string} [segmentId] The header/footer segment id, or an empty string for the main body.
 	* @returns {FDocumentTextRange} A fixed text-range facade.
 	* @example
 	* ```ts
@@ -1585,6 +1884,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Returns a traditional section by zero-based index, or `null` in modern documents.
+	* @param {number} index Zero-based section index.
+	* @returns {FDocumentSection | null} The matching section, or `null` if none exists or the document is not Traditional.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1597,6 +1898,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Returns the traditional section containing a data-stream offset, or `null` in modern documents.
+	* @param {number} offset Zero-based data-stream offset in the main document body.
+	* @returns {FDocumentSection | null} The matching section, or `null` if none exists or the document is not Traditional.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1681,6 +1984,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* 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`.
+	* @param {number} offset Zero-based data-stream offset at which to insert the column break.
+	* @returns {boolean} Whether the insertion succeeded.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1704,6 +2009,10 @@ let FDocument = class FDocument extends FBaseInitialable {
 	* Inserts a horizontal rule using the existing paragraph `borderBottom` mechanism.
 	* The returned paragraph can be inspected or removed with normal paragraph APIs.
 	* Border width and padding are in points (pt).
+	* @param {number} offset Zero-based insertion offset in the selected body segment.
+	* @param {IParagraphBorder} [border] Bottom border appearance. Defaults to a solid gray 1 pt line with 5 pt padding.
+	* @param {string} [segmentId] Header/footer segment ID, or an empty string for the main body (default).
+	* @returns {FDocumentParagraph | null} The inserted paragraph, or `null` if insertion fails.
 	* @example
 	* ```ts
 	* const fDocument = univerAPI.getActiveDocument();
@@ -1730,11 +2039,11 @@ let FDocument = class FDocument extends FBaseInitialable {
 		}, {
 			dataStream: DataStreamTreeTokenType.PARAGRAPH,
 			paragraphs
-		}, this._documentDataModel, this._injector) ? this.getParagraph(paragraphId, segmentId) : null;
+		}, this._documentDataModel, this._commandService) ? this.getParagraph(paragraphId, segmentId) : null;
 	}
 	/**
 	* Get all paragraphs in the document body or header/footer body by the segment id.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph[]} An array of paragraph facade instances.
 	* @example
 	* ```ts
@@ -1754,7 +2063,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	/**
 	* Get a paragraph by its paragraph id and segment id.
 	* @param {string} paragraphId The paragraph id.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph | null} The paragraph facade instance, or `null` if the paragraph is not found.
 	* @example
 	* ```ts
@@ -1775,7 +2084,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	/**
 	* Find a paragraph by its text content and segment id.
 	* @param {string} text The text content to search for.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph | null} The paragraph facade instance, or `null` if the paragraph is not found.
 	* @example
 	* ```ts
@@ -1823,8 +2132,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	/**
 	* Insert a plain-text paragraph before the paragraph at the given paragraph index.
 	* @param {number} index The zero-based paragraph insertion index.
-	* @param {string} text The paragraph text. Defaults to an empty paragraph.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [text] The paragraph text. Defaults to an empty paragraph.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph} The inserted paragraph facade instance.
 	* @example
 	* ```ts
@@ -1843,7 +2152,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 			startOffset: offset,
 			endOffset: offset,
 			segmentId
-		}, buildPlainTextInsertBody(`${text}\r`), this._documentDataModel, this._injector)) throw new Error("Failed to insert paragraph.");
+		}, buildPlainTextInsertBody(`${text}\r`), this._documentDataModel, this._commandService)) throw new Error("Failed to insert paragraph.");
 		const { paragraphs = [] } = this.getBody(segmentId);
 		const paragraph = paragraphs[index];
 		if (!paragraph) throw new Error("Failed to insert paragraph.");
@@ -1851,8 +2160,8 @@ let FDocument = class FDocument extends FBaseInitialable {
 	}
 	/**
 	* Append a plain-text paragraph at the end of the body.
-	* @param {string} text The paragraph text. Defaults to an empty paragraph.
-	* @param {string} segmentId The segment id of the body. Defaults to an empty string for the main body.
+	* @param {string} [text] The paragraph text. Defaults to an empty paragraph.
+	* @param {string} [segmentId] The segment id of the body. Defaults to an empty string for the main body.
 	* @returns {FDocumentParagraph} The appended paragraph wrapper.
 	* @example
 	* ```ts
@@ -1885,7 +2194,7 @@ let FDocument = class FDocument extends FBaseInitialable {
 	deleteRange(range) {
 		const normalizedRange = this._normalizeDeleteRange(range);
 		if (normalizedRange.startOffset >= normalizedRange.endOffset) return false;
-		return replaceBodyRange(normalizedRange, { dataStream: "" }, this._documentDataModel, this._injector);
+		return replaceBodyRange(normalizedRange, { dataStream: "" }, this._documentDataModel, this._commandService);
 	}
 	_createFDocumentParagraph(paragraphId, segmentId = "") {
 		return this._injector.createInstance(FDocumentParagraph, this, paragraphId, segmentId, this._injector);
@@ -1951,14 +2260,15 @@ FDocument = __decorate([
 	__decorateParam(1, Inject(Injector)),
 	__decorateParam(2, IUniverInstanceService),
 	__decorateParam(3, Inject(IResourceLoaderService)),
-	__decorateParam(4, ICommandService)
+	__decorateParam(4, ICommandService),
+	__decorateParam(5, IPermissionService)
 ], FDocument);
 
 //#endregion
 //#region src/facade/f-univer.ts
 var FUniverDocsMixin = class extends FUniver {
-	createDocument(data) {
-		const document = this._injector.get(IUniverInstanceService).createUnit(UniverInstanceType.UNIVER_DOC, data);
+	createDocument(data, options) {
+		const document = this._injector.get(IUniverInstanceService).createUnit(UniverInstanceType.UNIVER_DOC, data, options);
 		return this._injector.createInstance(FDocument, document);
 	}
 	getActiveDocument() {
@@ -2005,4 +2315,4 @@ var FDocsEnumMixin = class extends FEnum {
 FEnum.extend(FDocsEnumMixin);
 
 //#endregion
-export { DocsSectionUnsupportedDocumentFlavorError, FDocsEnumMixin, FDocument, FDocumentParagraph, FDocumentSection, FDocumentTextRange, isParagraphFacade, stripBlockTokens };
+export { DocsSectionUnsupportedDocumentFlavorError, FDocsEnumMixin, FDocument, FDocumentObjectPermission, FDocumentParagraph, FDocumentPermission, FDocumentSection, FDocumentTextRange, isParagraphFacade, stripBlockTokens };