@univerjs-pro/engine-shape 1.0.0-alpha.7 → 1.0.0-beta.0

package/lib/types/facade/f-connector-shape.d.ts

@@ -20,7 +20,7 @@ import { FShape } from './f-shape';
  * const fConnectorShape = fDocument.insertShape({
  *   shapeType: univerAPI.Enum.ShapeTypeEnum.StraightConnector1,
  *   placement: {
- *     wrappingStyle: univerAPI.Enum.DocsShapeWrappingStyle.WRAP_SQUARE,
+ *     wrappingStyle: univerAPI.Enum.TextWrappingStyle.WRAP_SQUARE,
  *     anchor: {
  *       paragraphId: paragraph.getId(),
  *       segmentId: paragraph.getSegmentId(),

package/lib/types/facade/f-shape-text.d.ts

@@ -20,6 +20,9 @@ export interface IShapeTextImageFillOptions {
 /**
  * A live text facade for a Shape in any supported host.
  *
+ * Sheet, Doc, Slide, and Board Shapes share this rich-text effect path. Glow and outer shadow support here does not
+ * imply that a host's standalone document text UI exposes the same authoring controls.
+ *
  * @example Sheet
  * ```ts
  * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -35,7 +38,7 @@ export interface IShapeTextImageFillOptions {
  * const fShape = fDocument.insertShape({
  *   shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  *   placement: {
- *     wrappingStyle: univerAPI.Enum.DocsShapeWrappingStyle.INLINE,
+ *     wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,
  *     anchor: {
  *       paragraphId: paragraph.getId(),
  *       segmentId: paragraph.getSegmentId(),
@@ -123,7 +126,18 @@ export declare class FShapeText {
      * @returns {FShapeText} This Shape text facade for chaining.
      * @example
      * ```ts
-     * fShapeText.setTextStyle({ ff: 'Inter', fs: 18 });
+     * fShapeText.setTextStyle({
+     *   ff: 'Inter',
+     *   fs: 18,
+     *   glow: { color: '#f97316', radius: 6 },
+     *   outerShadow: {
+     *     color: '#000000',
+     *     opacity: 0.35,
+     *     blurRadius: 4,
+     *     distance: 3,
+     *     direction: 45,
+     *   },
+     * });
      * ```
      */
     setTextStyle(style: ITextStyle): this;

package/lib/types/facade/f-shape.d.ts

@@ -1,6 +1,7 @@
-import type { IBasicShapeData, ImageSourceTypeEnum, IPresetShapeConfig, IShapeData, IShapeHostAdapter, IShapeLineStyle, IShapePointWithAdjName, IShapeRef, IShapeRelationItem, IShapeSnapshot, IShapeTransform, IShapeUpdateInput, ShapeGradientTypeEnum, ShapeHostType, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeTypeEnum } from '@univerjs-pro/engine-shape';
+import type { IBasicShapeData, ImageSourceTypeEnum, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeData, IShapeHostAdapter, IShapeLineStyle, IShapePath, IShapeRef, IShapeRelationItem, IShapeSnapshot, IShapeTransform, IShapeUpdateInput, ShapeGradientTypeEnum, ShapeHostType, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeTypeEnum } from '@univerjs-pro/engine-shape';
 import type { Injector } from '@univerjs/core';
-import { ShapeLineTypeEnum } from '@univerjs-pro/engine-shape';
+import { IShapeHostAdapterRegistry, ShapeLineTypeEnum } from '@univerjs-pro/engine-shape';
+import { ICommandService } from '@univerjs/core';
 import { FBase } from '@univerjs/core/facade';
 import { FShapeText } from './f-shape-text';
 type ShapeFill = NonNullable<IBasicShapeData['fill']>;
@@ -23,6 +24,25 @@ export interface IShapeConnectionSite {
     /** Outward site angle in OOXML angle units (1/60000 degree). */
     ang: number;
 }
+/**
+ * A single SVG path accepted by `FShape.setCustomGeometryFromSvgPath()`.
+ *
+ * `pathData` is the value of an SVG `<path d="...">` attribute, not complete SVG markup or a data
+ * URL. Fill and stroke colors remain Shape styles; `fill` and `stroke` only control whether this
+ * geometry path participates in filling and stroking.
+ */
+export interface IShapeSvgPathGeometryOptions {
+    /** SVG `<path>` `d` attribute value. */
+    pathData: string;
+    /** Optional virtual SVG coordinate-space width. The path scales to the Shape width when set. */
+    width?: number;
+    /** Optional virtual SVG coordinate-space height. The path scales to the Shape height when set. */
+    height?: number;
+    /** Optional geometry fill mode. Use `'none'` for an open or stroke-only path. */
+    fill?: IShapePath['fill'];
+    /** Whether the Shape stroke is applied to this geometry path. */
+    stroke?: boolean;
+}
 /** Optional image-fill properties accepted by `FShape.setImageFill()`. */
 export type IShapeImageFillOptions = Pick<ShapeFill, 'imageFillMode' | 'imageOpacity' | 'imageRotateWithShape' | 'stretchFillRect' | 'srcRect' | 'imageTile'>;
 /**
@@ -44,7 +64,7 @@ export type IShapeImageFillOptions = Pick<ShapeFill, 'imageFillMode' | 'imageOpa
  * const fShape = fDocument.insertShape({
  *   shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  *   placement: {
- *     wrappingStyle: univerAPI.Enum.DocsShapeWrappingStyle.INLINE,
+ *     wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,
  *     anchor: {
  *       paragraphId: paragraph.getId(),
  *       segmentId: paragraph.getSegmentId(),
@@ -94,7 +114,9 @@ export type IShapeImageFillOptions = Pick<ShapeFill, 'imageFillMode' | 'imageOpa
 export declare class FShape extends FBase {
     protected readonly _shapeRef: IShapeRef;
     protected readonly _injector: Injector;
-    constructor(_shapeRef: IShapeRef, _injector: Injector);
+    protected readonly _shapeHostAdapterRegistry: IShapeHostAdapterRegistry;
+    protected readonly _commandService: Pick<ICommandService, 'syncExecuteCommand'>;
+    constructor(_shapeRef: IShapeRef, _injector: Injector, _shapeHostAdapterRegistry: IShapeHostAdapterRegistry, _commandService: Pick<ICommandService, 'syncExecuteCommand'>);
     /**
      * Whether this Shape is a Connector preset type.
      * @returns {boolean} Whether this Shape is a Connector preset type.
@@ -389,6 +411,59 @@ export declare class FShape extends FBase {
      * ```
      */
     setCustomGeometry(customGeometry: IPresetShapeConfig): this;
+    /**
+     * Replaces this Shape's geometry with one SVG path.
+     *
+     * Use this method when the source is an SVG `<path>` `d` attribute. Do not pass complete
+     * `<svg>`/`<path>` markup, a data URL, CSS, transforms, fill colors, or stroke colors in
+     * `options.pathData`. Configure visual styles with Shape facade methods such as
+     * `setSolidFill()`, `setNoneFill()`, and `setStroke()`.
+     *
+     * All standard SVG path commands are supported: `M/m`, `L/l`, `H/h`, `V/v`, `C/c`, `S/s`,
+     * `Q/q`, `T/t`, `A/a`, and `Z/z`. Relative commands and repeated coordinate groups are
+     * converted to absolute engine-shape commands. SVG arcs are converted to cubic Bézier segments
+     * instead of being misinterpreted as engine-shape's semantically different OOXML `A` command.
+     *
+     * Parsing finishes before the host Shape is updated. Invalid or unsupported path data throws a
+     * `SyntaxError` and leaves the existing Shape geometry unchanged.
+     *
+     * @param {IShapeSvgPathGeometryOptions} options SVG path geometry and optional virtual bounds.
+     * @returns {FShape} This Shape facade for chaining.
+     *
+     * @example Board — executable with `univer execute`
+     * ```ts
+     * const board = univerAPI.getActiveBoard();
+     * if (!board) throw new Error('No active board');
+     *
+     * const shape = board.insertShape({
+     *   shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
+     *   transform: { left: 300, top: 100, width: 160, height: 200 },
+     * });
+     * if (!shape) throw new Error('Cannot insert shape');
+     *
+     * shape
+     *   .setCustomGeometryFromSvgPath({
+     *     // This is only the value of <path d="...">.
+     *     pathData: 'M 50,10 C 34,20 24,64 22,92 L 78,92 C 76,64 66,20 50,10 Z',
+     *     width: 100,
+     *     height: 100,
+     *     fill: 'none',
+     *     stroke: true,
+     *   })
+     *   .setNoneFill()
+     *   .setStroke({
+     *     lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,
+     *     color: '#F0509B',
+     *     width: 3,
+     *   });
+     *
+     * return {
+     *   id: shape.getId(),
+     *   pathCount: shape.getCustomGeometry()?.pathLst?.length ?? 0,
+     * };
+     * ```
+     */
+    setCustomGeometryFromSvgPath(options: IShapeSvgPathGeometryOptions): this;
     /**
      * Returns the sites where Connector endpoints can attach to this Shape.
      * Coordinates are local to the unrotated Shape bounds. Shapes without
@@ -401,17 +476,6 @@ export declare class FShape extends FBase {
      * ```
      */
     getConnectionSites(): IShapeConnectionSite[];
-    /**
-     * Returns the geometry adjustment handles exposed by this Shape preset.
-     * Coordinates are local to the unrotated Shape bounds and `adjName` identifies
-     * the corresponding entry in `shapeData.adjustValues`.
-     * @returns {IShapePointWithAdjName[]} The geometry adjustment handles exposed by this Shape preset.
-     * @example
-     * ```ts
-     * console.log(fShape.getAdjustPoints());
-     * ```
-     */
-    getAdjustPoints(): IShapePointWithAdjName[];
     /**
      * Returns the Shape and connection-site index bound to a Connector's start point, or `null` when unbound.
      * @returns {IShapeRelationItem | null} The Shape and connection-site index bound to a Connector's start point, or `null` when unbound.
@@ -430,6 +494,51 @@ export declare class FShape extends FBase {
      * ```
      */
     getEndConnectInfo(): IShapeRelationItem | null;
+    /**
+     * Returns complete information for every adjustment handle exposed by this Shape.
+     * @returns {IShapeAdjustItemResolved[]} Detached resolved adjustment handles in preset order.
+     * @example
+     * ```ts
+     * fShape.setShapeType(univerAPI.Enum.ShapeTypeEnum.BlockArc);
+     *
+     * const handle = fShape.getAdjustHandles().find(({ gdRefR }) => gdRefR === 'adj3');
+     * console.log(handle?.type); // 'ahPolar'
+     * console.log(handle?.gdRefAng, handle?.gdRefR); // 'adj2', 'adj3'
+     * console.log(handle?.currentAdjustValues); // { adj2: 0, adj3: 25000 }
+     * console.log(handle?.resolvedMinR, handle?.resolvedMaxR); // 0, 50000
+     * ```
+     */
+    getAdjustHandles(): IShapeAdjustItemResolved[];
+    /**
+     * Updates only the supplied Shape adjustment values and clamps them to their handle ranges.
+     * @param {Record<string, number>} adjustValues Adjustment names and values to update.
+     * @returns {FShape} This Shape facade for chaining.
+     * @example
+     * ```ts
+     * fShape
+     *   .setShapeType(univerAPI.Enum.ShapeTypeEnum.RoundRect)
+     *   .setAdjustValues({ adj: 75000 });
+     *
+     * const [handle] = fShape.getAdjustHandles();
+     * console.log(handle.currentAdjustValues.adj); // 50000
+     * ```
+     */
+    setAdjustValues(adjustValues: Record<string, number>): this;
+    /**
+     * Removes all Shape adjustment overrides and restores preset defaults.
+     * @returns {FShape} This Shape facade for chaining.
+     * @example
+     * ```ts
+     * fShape
+     *   .setShapeType(univerAPI.Enum.ShapeTypeEnum.RoundRect)
+     *   .setAdjustValues({ adj: 40000 });
+     * fShape.resetAdjustValues();
+     *
+     * const [handle] = fShape.getAdjustHandles();
+     * console.log(handle.currentAdjustValues.adj); // 16667
+     * ```
+     */
+    resetAdjustValues(): this;
     /**
      * Replaces the current fill with a solid color and optional opacity.
      * @param {string} color The new fill color.
@@ -627,6 +736,6 @@ export declare class FShape extends FBase {
     private _patchStroke;
     private _getSnapshot;
     private _getGeometryModel;
-    private _mutate;
+    protected _mutate(operation: string, callback: (adapter: IShapeHostAdapter) => boolean): boolean;
 }
 export {};

package/lib/types/facade/index.d.ts

@@ -1,6 +1,6 @@
 import './f-enum';
 export { FConnectorShape } from './f-connector-shape';
 export { FShape } from './f-shape';
-export type { IShapeConnectionSite, IShapeGradientStop, IShapeImageFillOptions } from './f-shape';
+export type { IShapeConnectionSite, IShapeGradientStop, IShapeImageFillOptions, IShapeSvgPathGeometryOptions, } from './f-shape';
 export { FShapeText } from './f-shape-text';
 export type { IShapeTextImageFillOptions } from './f-shape-text';

package/lib/types/index.d.ts

@@ -1,10 +1,8 @@
 export { BasicShapeModel as ShapeModel } from '../src/models/shape-model';
 export { BaseShapeRenderModel } from '../src/render-engine/shape-render-model';
 export { ImageFillModeEnum, ImageSourceTypeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapePresetShadowValEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum, } from '../src/shape-enum';
-export type { IBasicShapeData, IConnectorLayoutResult, IConnectPointInfo, ICustomShapeTextData, ICxnShapeData, IDrawingRect, IGdContext, ILineType, IPathCommand, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeData, IShapeFormulaBinding, IShapeJSONData, IShapeLineStyle, IShapePath, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeShadowEffect, IShapeText, IShapeTextBodyBehavior, IShapeTextBoxOptions, IShapeTextData, IShapeTextDataModel, IShapeTextRectPadding, ShapeShadowAlignment, ShapeTextHorizontalAnchor, } from '../src/shape-type';
+export type { IBasicShapeData, IConnectorLayoutResult, IConnectPointInfo, ICustomShapeTextData, ICxnShapeData, IDrawingRect, IGdContext, ILineType, IPathCommand, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeData, IShapeFormulaBinding, IShapeJSONData, IShapeLineStyle, IShapePath, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeText, IShapeTextBodyBehavior, IShapeTextBoxOptions, IShapeTextData, IShapeTextDataModel, IShapeTextRectPadding, ShapeTextHorizontalAnchor, } from '../src/shape-type';
 export { ShapeTextAutoFitType, ShapeTextDirection, ShapeTextWrapType } from '../src/shape-type';
-export type { IResolvedShapeShadow } from '../src/utils/shape-shadow.util';
-export { resolveShapeShadow } from '../src/utils/shape-shadow.util';
 export { applyShapeTextBoxOptions, resolveShapeTextBodyBehavior, resolveShapeTextBoxOptions, shouldUseFullShapeTextRectForAutoFit, } from '../src/utils/shape-text-behavior.util';
 export type { IResolvedShapeTextBoxOptions } from '../src/utils/shape-text-behavior.util';
 export { UniverShapePlugin } from './plugin';
@@ -12,8 +10,8 @@ export { computeConnectorRouteLayout, getBasicShapeRotateBound, routeConnectorLi
 export { ConnectorShapeHostAdapter } from './services/connector-shape-host-adapter';
 export { IConnectorShapeHostAdapter } from './services/connector-shape-host-adapter.service';
 export type { IConnectorArrow, IConnectorEndpoint, IConnectorShapeSnapshot, } from './services/connector-shape-host-adapter.service';
-export { IShapeHostAdapterRegistry, isShapeHostType, ShapeHostAdapterRegistry, } from './services/shape-host-adapter.service';
-export type { IShapeCreateInput, IShapeHostAdapter, IShapeRef, IShapeScope, IShapeSnapshot, IShapeTransform, IShapeUpdateInput, ShapeHostType, } from './services/shape-host-adapter.service';
+export { canApplyShapeFormulaLastValue, IShapeHostAdapterRegistry, isShapeHostType, ShapeHostAdapterRegistry, } from './services/shape-host-adapter.service';
+export type { IShapeCreateInput, IShapeFormulaLastValueGuard, IShapeHostAdapter, IShapeHostChange, IShapeHostChangeStream, IShapeRef, IShapeScope, IShapeSnapshot, IShapeTransform, IShapeUpdateInput, ShapeHostType, } from './services/shape-host-adapter.service';
 export { ShapeDefaultConfig } from './shape-default';
 export { resolveShapeDefaultInsertSize } from './shape-default-size';
 export { ConnectorCoordinateTransform } from './util/connector-transform';
@@ -22,3 +20,4 @@ export { isConnectorShape, isCurvedConnectorShape, } from './util/shape-util';
 export { buildConnectorEndpointUpdate, buildConnectorRoutePointsUpdate, createFreeConnectorPointInfo, resolveConnectorRoutePoints, resolveShapeConnectionPoint, } from './utils/connector.util';
 export { applyDocumentToShapeText, applyRichTextToShapeText, applyShapeTextAlignment, applyShapeTextStyle, applyTextToShapeText, normalizeShapeTextData, shapeTextToRichTextValue, } from './utils/shape-text-converter';
 export type { IShapeTextAlignmentOptions } from './utils/shape-text-converter';
+export { parseSvgPathData } from './utils/svg-path-data';

package/lib/types/models/shape-model.d.ts

@@ -1,3 +1,4 @@
+import type { IBoundRectNoAngle } from '@univerjs/engine-render';
 import type { ShapeTypeEnum } from '../shape-enum';
 import type { IGdContext, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeContextOptions, IShapeData, IShapeJSONData, IShapeModel, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeRenderParameters, IShapeTextData } from '../shape-type';
 import { BasicShapeEnum } from '../shape-enum';
@@ -68,6 +69,7 @@ export declare class BasicShapeModel implements IShapeModel {
     getAdjustInfoByName(adjName: string): IShapeAdjustItemResolved | undefined;
     getAdjustInfo(index: number): IShapeAdjustItemResolved | undefined;
     private _getAdjustIndexByName;
+    private _getAdjustNames;
     private _getAdjScope;
     private _setAdjustValue;
     clearAdjustValue(): void;
@@ -111,6 +113,7 @@ export declare class BasicShapeModel implements IShapeModel {
      */
     isHitLine(pointX: number, pointY: number, width: number, height: number, tolerance?: number): boolean;
     render(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, renderOption: IShapeRenderParameters): void;
+    getDrawingEffectBounds(rect: IShapeRect): IBoundRectNoAngle | undefined;
     /**
      * Build the shape outline path on the canvas context and clip.
      * This only builds paths and clips — no fill or stroke is applied.
@@ -119,7 +122,13 @@ export declare class BasicShapeModel implements IShapeModel {
      */
     buildClipPath(canvasContext: CanvasRenderingContext2D, rect: IShapeRect): IShapeRect | false;
     getDrawingPoints(): IShapePointWithAdjName[];
-    calcAdjValue(rect: IShapeRect, point: IShapePoint, adjustInfo: IShapeAdjustItemResolved, _isFlipH: boolean, _isFlipV: boolean): number;
+    calcAdjValues(rect: IShapeRect, point: IShapePoint, info: IShapeAdjustItemResolved, _isFlipH: boolean, _isFlipV: boolean): Record<string, number>;
+    private _getAdjustRefs;
+    private _seedAngleAdjustValue;
+    private _evaluateAdjustPosition;
+    private _calcAdjustDerivative;
+    private _solveAdjustDelta;
+    private _clamp;
     dispose(): void;
     private _getSnapshotAdjustValues;
     private _cloneShapeDataWithSnapshotAdjustValues;

package/lib/types/render-engine/shape-render-model.d.ts

@@ -4,8 +4,8 @@ export declare abstract class BaseShapeRenderModel {
     protected _isLineShape: boolean;
     abstract readonly name: string;
     abstract readonly presetShapeConfig: IPresetShapeConfig;
-    private _inverseCache;
     isLineShape(): boolean;
+    protected _isStrokeVisible(shapeData: IShapeData): boolean;
     getConnectorLinePoints(): IShapeGdContextKeyPoint[];
     /**
      * This method tests whether a point (pointX, pointY) hits any interactive parts of the shape,
@@ -152,29 +152,6 @@ export declare abstract class BaseShapeRenderModel {
      * Apply coordinate scaling to resolved path points in-place.
      */
     private _scalePathPoints;
-    /**
-     * Check if the adjust handle at the given index has an inverse relationship.
-     * Uses cache to avoid recalculating.
-     * @param index The index of the adjust handle in ahLst
-     * @returns true if inverse relationship exists
-     */
-    isInverse(index: number): boolean;
-    /**
-     * Detect if there's an inverse relationship between adj value and position.
-     * Analyzes the gd formula chain to find subtract patterns like "r - adj*k" or "b - adj*k".
-     * @param adjustInfo The adjust handle info
-     * @returns true if inverse relationship is detected
-     */
-    private _detectInverseRelationship;
-    /**
-     * Recursively analyze gd formula to detect inverse relationship.
-     * Looking for patterns like: pos = r - f(adj) or pos = b - f(adj)
-     */
-    private _analyzeFormulaForInverse;
-    /**
-     * Check if a gd variable depends on (is derived from) adjName
-     */
-    private _dependsOnAdj;
     getGdValue(key: number | IGdContextKey, gdRecord: Partial<IGdContext>): number;
     private _renderAdjustHandles;
 }

package/lib/types/services/shape-host-adapter.service.d.ts

@@ -1,6 +1,8 @@
-import type { IDisposable, UniverInstanceType } from '@univerjs/core';
+import type { IFormulaLastValue } from '@univerjs-pro/engine-formula';
+import type { IAccessor, IDisposable, IMutationInfo } from '@univerjs/core';
 import type { ShapeTypeEnum } from '../shape-enum';
 import type { IShapeData } from '../shape-type';
+import { UniverInstanceType } from '@univerjs/core';
 export type ShapeHostType = UniverInstanceType.UNIVER_SHEET | UniverInstanceType.UNIVER_DOC | UniverInstanceType.UNIVER_SLIDE | UniverInstanceType.UNIVER_BOARD;
 export declare function isShapeHostType(type: UniverInstanceType): type is ShapeHostType;
 export interface IShapeScope {
@@ -15,6 +17,15 @@ export interface IShapeRef extends IShapeScope {
     /** Stable Shape identifier within the host subunit. */
     shapeId: string;
 }
+export interface IShapeHostChange {
+    /** Host unit whose persisted Shape projection may have changed. */
+    unitId: string;
+}
+export interface IShapeHostChangeStream {
+    subscribe(listener: (change: IShapeHostChange) => void): {
+        unsubscribe(): void;
+    };
+}
 export interface IShapeTransform {
     /** Horizontal position in host coordinates. */
     left: number;
@@ -79,12 +90,44 @@ export interface IShapeUpdateInput {
     /** Canvas selectability to update. Omit to preserve the current value. */
     selectable?: boolean;
 }
+/**
+ * Ephemeral compare-and-set guard carried by a derived Formula last-value mutation.
+ *
+ * The guard is deliberately excluded from persisted Shape data. It prevents an
+ * asynchronous result calculated from an older formula or External Reference
+ * binding from overwriting a newer user edit.
+ */
+export interface IShapeFormulaLastValueGuard {
+    expectedFormula: string;
+    expectedReferenceRevision: number;
+}
+/** Revalidates a Formula Shape result immediately before its Host mutation writes. */
+export declare function canApplyShapeFormulaLastValue(accessor: IAccessor, ref: IShapeRef, currentFormula: string | undefined, guard: IShapeFormulaLastValueGuard | undefined): boolean;
 export interface IShapeHostAdapter {
     readonly hostType: ShapeHostType;
+    /** Emits after a Shape mutation has changed this host's persisted Shape data. */
+    readonly shapeChanged$?: IShapeHostChangeStream;
     getShape(ref: IShapeRef): IShapeSnapshot | null;
     listShapes(scope: IShapeScope): IShapeSnapshot[];
+    /**
+     * Lists Shapes from every subunit owned by one host Unit.
+     * Core consumers use this optional hook to rebuild runtime projections from persisted snapshots.
+     */
+    listShapesInUnit?(unitId: string): IShapeSnapshot[];
     createShape(scope: IShapeScope, input: IShapeCreateInput): IShapeSnapshot | null;
+    /**
+     * Creates Shapes atomically and returns snapshots in input order.
+     * Implementations must return `null` without retaining partial changes when any input or the host command fails.
+     */
+    createShapes?(scope: IShapeScope, inputs: IShapeCreateInput[]): IShapeSnapshot[] | null;
     updateShape(ref: IShapeRef, input: IShapeUpdateInput): boolean;
+    /**
+     * Builds the Host's existing Shape mutation for a successful Formula result.
+     *
+     * Implementations must include `guard` in the mutation params and validate it
+     * in the mutation handler before replacing `formulaBinding.lastValue`.
+     */
+    createFormulaLastValueMutation?(ref: IShapeRef, guard: IShapeFormulaLastValueGuard, lastValue: IFormulaLastValue): IMutationInfo | null;
     removeShape(ref: IShapeRef): boolean;
     bringToFront(ref: IShapeRef): boolean;
     bringForward(ref: IShapeRef): boolean;

package/lib/types/shape-enum.d.ts

@@ -81,7 +81,7 @@ export declare enum ShapePresetShadowValEnum {
 }
 /**
  * Shape fill type enum
- * Currently, PatternFill and PictureFill are not supported, but we define them for future use, if will be treat as Nofill currently.
+ * Shape fill types supported by the renderer.
  */
 export declare enum ShapeFillEnum {
     NoFill = 1,

package/lib/types/shape-type.d.ts

@@ -1,5 +1,6 @@
-import type { HorizontalAlign, IDocumentData, VerticalAlign } from '@univerjs/core';
-import type { BasicShapeEnum, ImageFillModeEnum, ImageSourceTypeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapePresetShadowValEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from './shape-enum';
+import type { IFormulaLastValue } from '@univerjs-pro/engine-formula';
+import type { HorizontalAlign, IDocumentData, IGlowEffect, IShadowEffect, VerticalAlign } from '@univerjs/core';
+import type { BasicShapeEnum, ImageFillModeEnum, ImageSourceTypeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from './shape-enum';
 /**
  * GdContext 用来计算 OOXML Shape 的 Geometry Definitions (gd)
  * 包含：
@@ -575,7 +576,6 @@ export declare enum ShapeTextWrapType {
     /** Wrap text inside the shape text box. */
     Square = "square"
 }
-export type ShapeShadowAlignment = 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
 export declare enum ShapeTextAutoFitType {
     /** Do not automatically adjust overflowing text. */
     NoAutoFit = "noAutoFit",
@@ -665,39 +665,17 @@ export interface ICustomShapeTextData extends IShapeTextAlign, IShapeTextBodyBeh
     dataModel?: IShapeTextDataModel;
 }
 export type IShapeTextData = IShapeText | ICustomShapeTextData;
-/**
- * A shape outer-shadow effect. Distances and blur radius use slide drawing
- * units; direction is in degrees where 0 points right and 90 points down.
- */
-export interface IShapeShadowEffect {
-    /** Shadow color as a CSS color string. */
-    color: string;
-    /** OOXML preset shadow value, when the shadow originated from `<a:prstShdw>`. */
-    preset?: ShapePresetShadowValEnum;
-    /** Shadow opacity, from 0 (transparent) to 1 (opaque). */
-    opacity?: number;
-    /** Blur radius in slide drawing units. */
-    blurRadius?: number;
-    /** Direction angle in degrees, with 0 pointing right and 90 pointing down. */
-    direction?: number;
-    /** Offset distance from the shape in slide drawing units. */
-    distance?: number;
-    /** Horizontal shadow scale factor; 1 means 100%. */
-    sx?: number;
-    /** Vertical shadow scale factor; 1 means 100%. */
-    sy?: number;
-    /** Horizontal shadow skew angle in degrees. */
-    skewX?: number;
-    /** Vertical shadow skew angle in degrees. */
-    skewY?: number;
-    /** Alignment point used while scaling or skewing the shadow. */
-    alignment?: ShapeShadowAlignment;
-    /** Whether the shadow rotates together with the shape. */
-    rotateWithShape?: boolean;
-}
 /** Formula data persisted by a formula-backed text-box shape. */
 export interface IShapeFormulaBinding {
-    /** The complete formula string, including the leading equals sign. */
+    /**
+     * The complete formula string, including the leading equals sign.
+     *
+     * Every reference must include its worksheet or table name; unqualified references
+     * such as `=A1` are unsupported. For a Shape hosted by a Document, Slide, or Board,
+     * every reference must also include the workbook or Base name. Examples:
+     * `=Sheet1!A1`, `=Orders[Amount]`, `='[Sales Workbook]Sheet1'!A1`, and
+     * `=[Sales Base]!Orders[Amount]`.
+     */
     formula: string;
     /** Whether value changes should be animated. Defaults to true. */
     animationEnabled?: boolean;
@@ -705,6 +683,8 @@ export interface IShapeFormulaBinding {
     numberFormat?: {
         pattern: string;
     };
+    /** Last successful scalar value persisted with the Shape for stale-first reload rendering. */
+    lastValue?: IFormulaLastValue;
 }
 /**
  * This interface defines the shape data structure , and this part will save in json
@@ -774,8 +754,10 @@ export interface IBasicShapeData {
     adjustValues?: Record<string, number>;
     isCustom?: boolean;
     customGeometry?: IPresetShapeConfig;
-    /** Basic outer shadow effect applied while rendering the shape path. */
-    outerShadow?: IShapeShadowEffect;
+    /** Outer shadow applied while rendering the shape path. */
+    outerShadow?: IShadowEffect;
+    /** Glow applied around the rendered shape path. */
+    glow?: IGlowEffect;
     shapeText?: IShapeTextData;
     /**
      * Text box inset used to calculate the editable/rendered text rect.
@@ -844,9 +826,9 @@ export interface IPresetShapeConfig {
         /** Angle in degrees (cd4 = 90°, cd2 = 180°, 3cd4 = 270°) */
         ang: string | number;
         /** X coordinate */
-        x?: string | number;
+        x: string | number;
         /** Y coordinate */
-        y?: string | number;
+        y: string | number;
     }>;
     /** Text rectangle definition */
     rect?: {
@@ -934,14 +916,8 @@ export interface IShapeAdjustItemResolved extends IShapeAdjustItem {
         x: number;
         y: number;
     };
-    /** Current value of the adj parameter being controlled */
-    currentAdjValue?: number;
-    /**
-     * Indicates inverse relationship between adj value and position.
-     * Calculated at runtime by analyzing gd formulas.
-     * When true, increasing adj value will decrease the position value.
-     */
-    inverse?: boolean;
+    /** Current values of all adjustment parameters controlled by this handle. */
+    currentAdjustValues: Record<string, number>;
 }
 export interface IShapeRenderParameters {
     renderMode?: ShapeRenderModeEnum;

package/lib/types/utils/svg-path-data.d.ts

@@ -0,0 +1,48 @@
+import type { IPathCommand } from '../shape-type';
+/**
+ * Parses an SVG `<path>` element's `d` attribute into engine-shape path commands.
+ *
+ * This helper parses path geometry only. It does not accept complete `<svg>` or `<path>` markup,
+ * data URLs, transforms, fill colors, or stroke styles. Configure those properties separately on
+ * the Shape.
+ *
+ * Supported SVG commands:
+ *
+ * - `M` / `m` — move to
+ * - `L` / `l` — line to
+ * - `H` / `h` — horizontal line to
+ * - `V` / `v` — vertical line to
+ * - `C` / `c` — cubic Bézier curve
+ * - `S` / `s` — smooth cubic Bézier curve
+ * - `Q` / `q` — quadratic Bézier curve
+ * - `T` / `t` — smooth quadratic Bézier curve
+ * - `A` / `a` — elliptical arc
+ * - `Z` / `z` — close path
+ *
+ * Repeated coordinate groups and relative commands are normalized to absolute `IPathCommand`
+ * values. `H` and `V` become `L`, smooth commands expand their reflected control points, and SVG
+ * arcs become one or more cubic `C` segments. SVG arcs are never forwarded as engine-shape `A`
+ * commands because that command follows different OOXML arc semantics.
+ *
+ * @param data The value of an SVG `<path d="...">` attribute.
+ * @returns Parsed, absolute engine-shape path commands.
+ * @throws {SyntaxError} When the path is empty, malformed, starts without `M`/`m`, or uses an
+ * unsupported SVG command.
+ *
+ * @example
+ * ```ts
+ * const commands = parseSvgPathData(
+ *   'M 50,10 C 34,20 24,64 22,92 L 78,92 C 76,64 66,20 50,10 Z'
+ * );
+ *
+ * console.log(commands);
+ * // [
+ * //   { command: 'M', points: [50, 10] },
+ * //   { command: 'C', points: [34, 20, 24, 64, 22, 92] },
+ * //   { command: 'L', points: [78, 92] },
+ * //   { command: 'C', points: [76, 64, 66, 20, 50, 10] },
+ * //   { command: 'z', points: [] },
+ * // ]
+ * ```
+ */
+export declare function parseSvgPathData(data: string): IPathCommand[];