@cj-tech-master/excelts 9.5.9 → 9.6.0

package/dist/types/modules/excel/stream/workbook-writer.browser.d.ts

@@ -186,6 +186,23 @@ export declare abstract class WorkbookWriterBase<TWorksheetWriter extends Worksh
     private _commitWorksheets;
     commit(): Promise<void>;
     get nextId(): number;
+    /**
+     * Register an image with the workbook and return its numeric id.
+     *
+     * Supply `buffer`/`base64`/`filename` to **embed** the bytes, or only `link`
+     * (a URL or local file path) to reference it **externally** — in which case
+     * no bytes are written into the package and the relationship is emitted with
+     * `TargetMode="External"`. If both are provided, embedding wins.
+     *
+     * Linked images work with cell pictures and overlay watermarks; worksheet
+     * background images and header/footer (VML) watermarks cannot be linked.
+     *
+     * @example
+     * ```typescript
+     * const id = wb.addImage({ extension: "png", link: "https://example.com/logo.png" });
+     * ws.addImage(id, "B2:D6");
+     * ```
+     */
     addImage(image: ImageData): number;
     getImage(id: number): Medium | undefined;
     /**

package/dist/types/modules/excel/stream/worksheet-writer.d.ts

@@ -179,6 +179,12 @@ declare class WorksheetWriter {
     /**
      * Add a watermark to the worksheet using an image from `WorkbookWriter.addImage()`.
      * Supports overlay mode (DrawingML with transparency) and header mode (VML behind content).
+     *
+     * `mode: "overlay"` supports external (linked) images; `mode: "header"` does
+     * not — VML header/footer images require embedded media, so a linked image
+     * with `mode: "header"` throws an `ImageError`.
+     *
+     * @throws {ImageError} If `mode: "header"` is used with an external (linked) image.
      */
     addWatermark(options: WatermarkOptions): void;
     /**

package/dist/types/modules/excel/types.d.ts

@@ -480,6 +480,23 @@ export interface ImageData {
     base64?: string;
     filename?: string;
     buffer?: Buffer;
+    /**
+     * Reference the image as an **external link** instead of embedding its bytes.
+     *
+     * When set (and `buffer`/`base64`/`filename` are all omitted), the image is
+     * written as a linked DrawingML picture (`<a:blip r:link>`) whose relationship
+     * uses `TargetMode="External"`. No bytes are stored in the `.xlsx` package, so
+     * the file size stays small. The value may be either:
+     *
+     * - an absolute/relative URL (e.g. `"https://example.com/logo.png"`), or
+     * - a local file path (e.g. `"file:///C:/images/logo.png"` or `"images/logo.png"`).
+     *
+     * Note: Excel treats linked images as volatile — a moved/missing target shows a
+     * broken-image placeholder, and modern Excel may not auto-load remote URLs for
+     * security reasons. Use embedding (`buffer`/`base64`) when self-contained files
+     * are required.
+     */
+    link?: string;
 }
 export interface ImagePosition {
     tl: {

package/dist/types/modules/excel/utils/drawing-utils.d.ts

@@ -14,6 +14,11 @@ export interface DrawingAnchor {
         };
         /** Alpha modulation for transparency (OOXML percentage, e.g. 15000 = 15%). */
         alphaModFix?: number;
+        /**
+         * When true, the picture references an external linked image
+         * (`<a:blip r:link>`) instead of an embedded one (`<a:blip r:embed>`).
+         */
+        external?: boolean;
     };
     range: any;
 }
@@ -37,6 +42,19 @@ interface ImageMedium {
     /** Opacity 0-1 for watermark overlay mode. */
     opacity?: number;
 }
+/**
+ * Minimal shape of a book-level media entry needed by the embed-vs-link
+ * decision and image-rel construction. Carries the optional link target plus
+ * the three mutually-exclusive embedded byte sources.
+ */
+export interface MediaLike {
+    name?: string;
+    extension?: string;
+    link?: string;
+    buffer?: unknown;
+    base64?: unknown;
+    filename?: unknown;
+}
 /**
  * Resolves a media filename into the drawing-level relative target path.
  *
@@ -50,13 +68,37 @@ export declare function resolveMediaTarget(medium: {
     name?: string;
     extension?: string;
 }): string;
+/**
+ * Determine whether a media entry is an **external (linked) image** rather than
+ * an embedded one. An external image carries a `link` target and supplies no
+ * embedded bytes (`buffer`/`base64`/`filename`). Embedding always takes
+ * precedence: if any byte source is present the image is embedded even if a
+ * `link` was also provided.
+ */
+export declare function isExternalImage(medium: MediaLike): boolean;
+/**
+ * Best-effort image extension inference from an external link's path.
+ *
+ * Normalises to the extension vocabulary used by `ImageData`
+ * (`"jpeg" | "png" | "gif"`); unknown extensions fall back to `"png"`.
+ * The extension is advisory only for linked images — the relationship
+ * Target carries the real reference — but keeping it within the documented
+ * set avoids surprising consumers that branch on `medium.extension`.
+ */
+export declare function inferExternalImageExtension(link: string): "jpeg" | "png" | "gif";
+/**
+ * Build an image relationship for the given rId, choosing between an embedded
+ * package target (`../media/imageN.ext`) and an external link target
+ * (`TargetMode="External"`) based on whether the image is external.
+ *
+ * Shared by the drawing, background, and watermark write paths so the
+ * embed-vs-link decision lives in exactly one place.
+ */
+export declare function buildImageRel(rId: string, bookImage: MediaLike): DrawingRel;
 /** Options for {@link buildDrawingAnchorsAndRels}. */
 interface BuildDrawingOptions {
     /** Look up a book-level image by its id. Return `undefined` if not found. */
-    getBookImage: (imageId: string | number) => {
-        name?: string;
-        extension?: string;
-    } | undefined;
+    getBookImage: (imageId: string | number) => MediaLike | undefined;
     /** Generate the next unique rId string for the drawing rels. */
     nextRId: (rels: DrawingRel[]) => string;
 }

package/dist/types/modules/excel/workbook.browser.d.ts

@@ -32,6 +32,8 @@ export interface WorkbookMedia {
     buffer?: ExcelBuffer | Uint8Array;
     base64?: string;
     name?: string;
+    /** External link target — when set, the image is referenced, not embedded. */
+    link?: string;
 }
 /** Internal model type for serialization */
 export interface WorkbookModel {
@@ -782,7 +784,42 @@ declare class Workbook {
     unregisterFunction(name: string): boolean;
     clearThemes(): void;
     /**
-     * Add Image to Workbook and return the id
+     * Register an image with the workbook and return its numeric id. Pass the id
+     * to {@link Worksheet.addImage}, {@link Worksheet.addBackgroundImage}, or
+     * {@link Worksheet.addWatermark} to place it.
+     *
+     * The image is either **embedded** or **linked (external)**:
+     *
+     * - **Embedded** — supply `buffer`, `base64`, or `filename`. The bytes are
+     *   written into the `.xlsx` package (`xl/media/imageN.ext`). Self-contained,
+     *   but inflates file size.
+     * - **Linked (external)** — supply only `link` (a URL or local file path).
+     *   No bytes are stored; the package keeps a relationship with
+     *   `TargetMode="External"` and the picture is rendered via `<a:blip r:link>`.
+     *   Keeps the file small, but the image is resolved by Excel at open time.
+     *
+     * If both bytes and a `link` are provided, **embedding wins**.
+     *
+     * Linked images work with **cell pictures** ({@link Worksheet.addImage}) and
+     * **overlay watermarks** ({@link Worksheet.addWatermark} with `mode:
+     * "overlay"`). Worksheet background images and header/footer (VML) watermarks
+     * cannot be linked — they require an embedded image.
+     *
+     * Note: Excel treats linked images as volatile — a moved/missing target
+     * shows a broken-image placeholder, and modern Excel may not auto-load
+     * remote URLs for security reasons. Prefer embedding for self-contained files.
+     *
+     * @example Embedded image
+     * ```typescript
+     * const id = workbook.addImage({ buffer: pngBytes, extension: "png" });
+     * worksheet.addImage(id, "B2:D6");
+     * ```
+     *
+     * @example Linked (external) image — no bytes stored
+     * ```typescript
+     * const id = workbook.addImage({ extension: "png", link: "https://example.com/logo.png" });
+     * worksheet.addImage(id, "B2:D6");
+     * ```
      */
     addImage(image: ImageData): number;
     getImage(id: number | string): WorkbookMedia | undefined;

package/dist/types/modules/excel/worksheet.d.ts

@@ -467,7 +467,12 @@ declare class Worksheet {
      */
     removeSparklineGroup(groupOrIndex: SparklineGroup | number): boolean;
     /**
-     * Using the image id from `Workbook.addImage`, set the background to the worksheet
+     * Using the image id from `Workbook.addImage`, set the background to the worksheet.
+     *
+     * The image must be **embedded** (`buffer`/`base64`/`filename`). Worksheet
+     * background pictures (`<picture r:id>`) do not support external (linked)
+     * images — Excel silently drops a background whose relationship uses
+     * `TargetMode="External"`, so this rejects linked images up front.
      */
     addBackgroundImage(imageId: string | number): void;
     getBackgroundImageId(): string | undefined;
@@ -483,7 +488,14 @@ declare class Worksheet {
      *   Visible in Page Layout view and when printed. Renders behind cell content.
      *   Transparency must be baked into the image (PNG with alpha channel).
      *
+     * **External (linked) images:** `mode: "overlay"` supports external images
+     * (registered via `workbook.addImage({ link })`). `mode: "header"` does
+     * **not** — VML header/footer images require embedded media, so passing a
+     * linked image with `mode: "header"` throws an `ImageError`. Use an embedded
+     * image (`buffer`/`base64`/`filename`) or switch to `mode: "overlay"`.
+     *
      * @param options - Watermark configuration
+     * @throws {ImageError} If `mode: "header"` is used with an external (linked) image.
      *
      * @example Overlay watermark with transparency:
      * ```typescript

package/dist/types/modules/excel/xlsx/xform/drawing/base-cell-anchor-xform.d.ts

@@ -9,5 +9,11 @@ declare abstract class BaseCellAnchorXform extends BaseXform {
     parseOpen(node: any): boolean;
     parseText(text: string): void;
     reconcilePicture(model: any, options: any): any;
+    /**
+     * Resolve (or create) the media entry for an external linked image. The
+     * synthesized entry is appended to `options.media` and indexed by its link
+     * so repeated references to the same external image share one entry.
+     */
+    private reconcileExternalPicture;
 }
 export { BaseCellAnchorXform };

package/dist/types/modules/excel/xlsx/xform/drawing/blip-xform.d.ts

@@ -3,6 +3,11 @@ interface BlipModel {
     rId: string;
     /** Alpha modulation (opacity) as OOXML percentage (e.g. 15000 = 15%). */
     alphaModFix?: number;
+    /**
+     * When true, the blip references an external linked image via `r:link`
+     * instead of an embedded one via `r:embed`.
+     */
+    external?: boolean;
 }
 declare class BlipXform extends BaseXform<BlipModel> {
     constructor();

package/dist/types/modules/excel/xlsx/xform/drawing/pic-xform.d.ts

@@ -4,6 +4,8 @@ interface PicModel {
     rId?: string;
     /** Alpha modulation for transparency (OOXML percentage, e.g. 15000 = 15%). */
     alphaModFix?: number;
+    /** When true, render the picture as an external linked image (`r:link`). */
+    external?: boolean;
     [key: string]: any;
 }
 declare class PicXform extends BaseXform {

package/dist/types/modules/excel/xlsx/xlsx.browser.d.ts

@@ -187,6 +187,8 @@ export interface WorkbookMediaLike {
     filename?: string;
     buffer?: Uint8Array;
     base64?: string;
+    /** External link target — when set, the image is referenced, not embedded. */
+    link?: string;
 }
 export interface MediaModel {
     media: WorkbookMediaLike[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "9.5.9",
+  "version": "9.6.0",
   "description": "Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.",
   "keywords": [
     "archive",
@@ -300,23 +300,23 @@
     "access": "public"
   },
   "devDependencies": {
-    "@rspack/core": "^2.0.4",
+    "@rspack/core": "^2.0.5",
     "@types/node": "^25.9.1",
-    "@typescript/native-preview": "^7.0.0-dev.20260521.1",
+    "@typescript/native-preview": "^7.0.0-dev.20260527.2",
     "@vitest/browser": "^4.1.7",
     "@vitest/browser-playwright": "^4.1.7",
     "@vitest/ui": "^4.1.7",
-    "concurrently": "^9.2.1",
+    "concurrently": "^10.0.0",
     "cross-env": "^10.1.0",
     "esbuild": "^0.28.0",
     "fast-xml-parser": "^5.8.0",
     "husky": "^9.1.7",
-    "oxfmt": "^0.51.0",
-    "oxlint": "^1.66.0",
+    "oxfmt": "^0.52.0",
+    "oxlint": "^1.67.0",
     "oxlint-tsgolint": "latest",
     "playwright": "^1.60.0",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.0.2",
+    "rolldown": "^1.0.3",
     "rollup-plugin-visualizer": "^7.0.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7"