@univerjs-pro/engine-shape 1.0.0-alpha.6 → 1.0.0-alpha.8

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

@@ -16,11 +16,18 @@ import { FShape } from './f-shape';
  * @example Doc
  * ```ts
  * const fDocument = univerAPI.getActiveDocument();
+ * const paragraph = fDocument.getParagraphs()[0];
  * const fConnectorShape = fDocument.insertShape({
  *   shapeType: univerAPI.Enum.ShapeTypeEnum.StraightConnector1,
- *   textRange: { startOffset: 0, endOffset: 0, collapsed: true },
- *   wrappingStyle: univerAPI.Enum.DocsShapeWrappingStyle.WRAP_SQUARE,
- *   transform: { left: 80, top: 80, width: 240, height: 120 },
+ *   placement: {
+ *     wrappingStyle: univerAPI.Enum.DocsShapeWrappingStyle.WRAP_SQUARE,
+ *     anchor: {
+ *       paragraphId: paragraph.getId(),
+ *       segmentId: paragraph.getSegmentId(),
+ *     },
+ *     position: { horizontalOffset: 80, verticalOffset: 80 },
+ *   },
+ *   transform: { width: 240, height: 120 },
  * });
  * ```
  *

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();
@@ -31,9 +34,16 @@ export interface IShapeTextImageFillOptions {
  * @example Doc
  * ```ts
  * const fDocument = univerAPI.getActiveDocument();
+ * const paragraph = fDocument.getParagraphs()[0];
  * const fShape = fDocument.insertShape({
  *   shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
- *   textRange: { startOffset: 0, endOffset: 0, collapsed: true },
+ *   placement: {
+ *     wrappingStyle: univerAPI.Enum.DocsShapeWrappingStyle.INLINE,
+ *     anchor: {
+ *       paragraphId: paragraph.getId(),
+ *       segmentId: paragraph.getSegmentId(),
+ *     },
+ *   },
  * });
  * const fShapeText = fShape?.getText();
  * ```
@@ -116,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, 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']>;
@@ -40,9 +41,16 @@ export type IShapeImageFillOptions = Pick<ShapeFill, 'imageFillMode' | 'imageOpa
  * @example Doc
  * ```ts
  * const fDocument = univerAPI.getActiveDocument();
+ * const paragraph = fDocument.getParagraphs()[0];
  * const fShape = fDocument.insertShape({
  *   shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
- *   textRange: { startOffset: 0, endOffset: 0, collapsed: true },
+ *   placement: {
+ *     wrappingStyle: univerAPI.Enum.DocsShapeWrappingStyle.INLINE,
+ *     anchor: {
+ *       paragraphId: paragraph.getId(),
+ *       segmentId: paragraph.getSegmentId(),
+ *     },
+ *   },
  * });
  * ```
  *
@@ -87,7 +95,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.
@@ -394,17 +404,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.
@@ -423,6 +422,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.
@@ -620,6 +664,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/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, 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';

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,7 +4,6 @@ export declare abstract class BaseShapeRenderModel {
     protected _isLineShape: boolean;
     abstract readonly name: string;
     abstract readonly presetShapeConfig: IPresetShapeConfig;
-    private _inverseCache;
     isLineShape(): boolean;
     getConnectorLinePoints(): IShapeGdContextKeyPoint[];
     /**
@@ -78,6 +77,7 @@ export declare abstract class BaseShapeRenderModel {
      * 而 Canvas ellipse() 使用参数角度：point = (rx·cos(t), ry·sin(t))。
      * 对于非正圆的椭圆，两者不同。OOXML 中 cat2/sat2 公式正是执行此转换来定位
      * moveTo 点和调节手柄，因此传给 Canvas 时必须做同样的转换。
+     * 半径必须使用 path 的逻辑坐标值；最终画布的非等比缩放不应再次改变参数角。
      */
     private _ooxmlAngleToParametric;
     /**
@@ -151,29 +151,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,39 @@ 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;
     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-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,35 +665,26 @@ 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.
+     *
+     * 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;
+    /** Optional display format chosen for this shape. */
+    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
@@ -763,14 +754,18 @@ 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.
      * Values use the same drawing units as the shape rect.
      */
     textRectPadding?: IShapeTextRectPadding;
+    /** Presence of this field identifies a formula shape. */
+    formulaBinding?: IShapeFormulaBinding;
 }
 export interface ICxnShapeData extends IBasicShapeData {
     points?: Array<{
@@ -817,6 +812,8 @@ export interface IShapeHitTestResult {
     hitType: ShapeHitTestHitTypeEnum;
 }
 export interface IPresetShapeConfig {
+    /** Arc angles are visual by default; guide-derived presets may already provide Canvas-compatible parametric angles. */
+    arcAngleMode?: 'visual' | 'parametric';
     /** Adjustment values for shape parameters, each value typically ranges from 0 to 100000 */
     adjustValues?: Record<string, ShapeOperatorValue>;
     /** Guide definitions - formulas for calculating shape geometry */
@@ -829,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?: {
@@ -919,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/shapes/oval-callout1-shape.d.ts

@@ -1,5 +1,6 @@
 import type { IPresetShapeConfig } from '../shape-type';
 import { BaseShapeRenderModel } from '../render-engine/shape-render-model';
+/** Legacy name for Excel's oval callout preset. */
 export declare class OvalCallout1Shape extends BaseShapeRenderModel {
     readonly name: string;
     readonly presetShapeConfig: IPresetShapeConfig;