@bubblydoo/uxp-toolkit 0.0.2

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@bubblydoo/uxp-toolkit",
+  "version": "0.0.2",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "error-stack-parser": "^2.1.4",
+    "source-map-js": "^1.2.1",
+    "xmlbuilder2": "^4.0.3"
+  },
+  "devDependencies": {
+    "@adobe-uxp-types/uxp": "^0.0.9",
+    "@types/chai": "^5.2.3",
+    "@types/node": "^20.8.7",
+    "@types/photoshop": "^25.0.2",
+    "chai": "^6.2.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.3",
+    "zod": "^4.3.6",
+    "@bubblydoo/uxp-test-framework": "0.0.2",
+    "@bubblydoo/tsconfig": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "uxp-tests:build": "create-uxp-test-plugin build",
+    "uxp-tests:dev": "create-uxp-test-plugin dev"
+  }
+}

package/src/commands-library/getLayerProperties.ts

@@ -0,0 +1,32 @@
+import type { Document } from "photoshop/dom/Document";
+import { z } from "zod";
+import { batchPlayCommand, createCommand } from "../core/command";
+
+// get layer properties like name and layerID for all layers in the document (by index)
+export const getLayerProperties = async (document: Document) => {
+  const command = createCommand({
+    modifying: false,
+    descriptor: {
+      _obj: "multiGet",
+      _target: { _ref: [{ _ref: "document", _id: document.id }] },
+      extendedReference: [
+        ["name", "layerID", "visible"],
+        { _obj: "layer", index: 1, count: -1 },
+      ],
+    },
+    schema: z.object({
+      list: z.array(
+        z.object({
+          name: z.string(),
+          layerID: z.number(),
+          visible: z.boolean().optional(),
+        })
+      )
+    })
+  });
+  
+  const result = await batchPlayCommand(command);
+
+  // Reverse to get bottom-up order
+  return [...result.list].reverse();
+};

package/src/commands-library/renameLayer.ts

@@ -0,0 +1,15 @@
+import { createCommand } from "../core/command";
+import type { PsLayerRef } from "../ut-tree/psLayerRef";
+import { z } from "zod";
+
+export function createRenameLayerCommand(layerRef: PsLayerRef, newName: string) {
+  return createCommand({
+    modifying: true,
+    descriptor: {
+      _obj: "set",
+      _target: [{ _ref: "layer", _id: layerRef.id }, { _ref: "document", _id: layerRef.docId }],
+      to: { _obj: "layer", name: newName },
+    },
+    schema: z.unknown(),
+  });
+}

package/src/commands-library/renameLayer.uxp-test.ts

@@ -0,0 +1,32 @@
+import { executeAsModal } from "../core/executeAsModal";
+import { openFileByPath } from "../filesystem/openFileByPath";
+import { getLayerProperties } from "../ut-tree/getLayerProperties";
+import type { Test } from "@bubblydoo/uxp-test-framework";
+import { expect } from "chai";
+import { app } from "photoshop";
+import { createRenameLayerCommand } from "./renameLayer";
+
+async function getFirstLayer() {
+  const allLayers = await getLayerProperties(app.activeDocument.id);
+  return {
+    ref: {
+      id: allLayers[0]!.layerID,
+      docId: app.activeDocument.id,
+    },
+    name: allLayers[0]!.name,
+  };
+} 
+
+export const renameLayerTest: Test = {
+  name: "Rename Layer",
+  async run() {
+    await openFileByPath("plugin:/fixtures/one-layer.psd");
+    const layer = await getFirstLayer();
+    expect(layer.name).to.equal("Layer 1");
+    await executeAsModal("Rename Layer", async (ctx) => {
+      await ctx.batchPlayCommand(createRenameLayerCommand(layer.ref, "New Name"));
+    });
+    const layer2 = await getFirstLayer();
+    expect(layer2.name).to.equal("New Name");
+  },
+};

package/src/core/batchPlay.ts

@@ -0,0 +1,16 @@
+import { action } from "photoshop";
+
+type P = Parameters<typeof action.batchPlay>;
+
+export type CorrectBatchPlayOptions = P[1] & {
+  immediateRedraw?: boolean;
+};
+
+export async function batchPlay(actions: P[0], options?: CorrectBatchPlayOptions) {
+  return action.batchPlay(actions, {
+    ...options,
+    modalBehavior: "execute",
+    dialogOptions: "silent",
+    synchronousExecution: false,
+  });
+}

package/src/core/command.ts

@@ -0,0 +1,130 @@
+import type { ActionDescriptor } from "photoshop/dom/CoreModules";
+import { z } from "zod";
+import { batchPlay } from "./batchPlay";
+import { executeAsModal } from "./executeAsModal";
+import type { CorrectExecutionContext } from "./executeAsModal";
+import { action } from "photoshop";
+
+export interface UTCommandBase<T extends any> {
+  descriptor: ActionDescriptor;
+  schema: z.ZodSchema<T>;
+}
+
+export interface UTCommandModifying<T extends any> extends UTCommandBase<T> {
+  modifying: true;
+}
+
+export interface UTCommandNonModifying<T extends any> extends UTCommandBase<T> {
+  modifying: false;
+}
+
+export function createCommand<TReturn extends any, TModifying extends boolean>(
+  obj: {
+    descriptor: ActionDescriptor,
+    schema: z.ZodSchema<TReturn>,
+    modifying: TModifying,
+  }
+): TModifying extends true ? UTCommandModifying<TReturn> : UTCommandNonModifying<TReturn> {
+  return {
+    modifying: obj.modifying,
+    descriptor: obj.descriptor,
+    schema: obj.schema,
+  } as any;
+}
+
+export type UTCommandResult<C> = C extends UTCommandBase<infer T> ? T : never;
+
+type BatchPlayOptions = Parameters<typeof batchPlay>[1];
+
+async function batchPlayCommandBase<T extends any>(command: UTCommandBase<T>, options?: BatchPlayOptions) {
+  const [result] = await batchPlay([command.descriptor], options);
+  if (result?._obj === "error") {
+    throw new Error("Batch play command failed", { cause: result });
+  }
+  return command.schema.parse(result);
+}
+
+async function batchPlayCommandsBase<TCommands extends Array<UTCommandBase<any>>>(
+  commands: readonly [...TCommands],
+  options?: BatchPlayOptions
+): Promise<{
+  [K in keyof TCommands]: UTCommandResult<TCommands[K]>;
+}> {
+  const results = await batchPlay(commands.map(command => command.descriptor), options);
+  if (results[0]?._obj === "error") {
+    throw new Error("Batch play command failed", { cause: results[0] });
+  }
+  return commands.map((command, index) => command.schema.parse(results[index])) as any;
+}
+
+export function batchPlayCommand<T extends any>(command: UTCommandNonModifying<T>, options?: BatchPlayOptions) {
+  return batchPlayCommandBase(command, options);
+}
+
+export function batchPlayCommands<TCommands extends Array<UTCommandNonModifying<any>>>(commands: readonly [...TCommands], options?: BatchPlayOptions) {
+  return batchPlayCommandsBase(commands, options);
+}
+
+export function createModifyingBatchPlayContext() {
+  return {
+    batchPlayCommand: batchPlayCommandBase,
+    batchPlayCommands: batchPlayCommandsBase,
+  }
+}
+// some examples:
+
+// const x = await batchPlay([{
+//   _obj: "get",
+//   _target: [
+//     { _ref: "layer", _id: 1 },
+//   ],
+// }])
+
+// const command = createCommand({
+//   modifying: true,
+//   descriptor: {
+//     _obj: "get",
+//     _target: [
+//       { _ref: "layer", _id: 1 },
+//     ],
+//   },
+//   schema: z.unknown()
+// })
+
+// const result = await batchPlayCommand(command);
+
+// executeAsModal(async (ctx) => {
+//   await ctx.batchPlayCommand(command);
+// }, {
+//   commandName: "test"
+// })
+
+// const x = await batchPlayCommands([
+//   {
+//     modifying: false,
+//     descriptor: {
+//       _obj: "get"
+//     },
+//     schema: z.object({
+//       name: z.string(),
+//     })
+//   },
+//   {
+//     modifying: false,
+//     descriptor: {
+//       _obj: "put"
+//     },
+//     schema: z.object({
+//       value: z.string(),
+//     })
+//   }
+// ])
+
+// const y = createCommand({
+//   descriptor: {
+//     _obj: "get"
+//   },
+//   schema: z.object({
+//     name: z.string(),
+//   })
+// })

package/src/core/executeAsModal.ts

@@ -0,0 +1,101 @@
+import { core } from "photoshop";
+import { createModifyingBatchPlayContext } from "./command";
+
+// copied from devtools:
+// hostControl: {suspendHistory: ƒ, resumeHistory: ƒ, registerAutoCloseDocument: ƒ, unregisterAutoCloseDocument: ƒ}
+// mode: "action"
+// uiMode: "never"
+// finalizeArguments: ƒ ()
+// isCancelled: undefined
+// onCancel: undefined
+// reject: ƒ ()
+// reportProgress: ƒ ()
+// resolve: ƒ ()
+
+export type CorrectExecutionContext = {
+  /**
+   * True if user has cancelled the modal interaction.
+   *
+   * User can cancel by hitting the Escape key, or by pressing the "Cancel" button in the progress bar.
+   */
+  isCancelled: boolean;
+  /**
+   * If assigned a method, it will be called when user cancels the modal interaction.
+   */
+  onCancel: () => void;
+  /**
+   * Call this to customize the progress bar.
+   */
+  reportProgress: (info: {
+    value: number;
+    commandName?: string;
+  }) => void;
+  /**
+   * Use the methods in here to control Photoshop state
+   */
+  hostControl: {
+    /**
+     * Call to suspend history on a target document, returns the suspension ID which can be used for resumeHistory
+     */
+    suspendHistory: (info: {
+      documentID: number,
+      name: string,
+    }) => Promise<number>;
+    /**
+     * Call to resume history on a target document
+     */
+    resumeHistory: (suspensionID: number, commit: boolean) => Promise<void>;
+    /** Register a document to be closed when the modal scope exits. See below for details. */
+    registerAutoCloseDocument: (documentID: number) => Promise<void>;
+    /** Unregister a document from being closed when the modal scope exits */
+    unregisterAutoCloseDocument: (documentID: number) => Promise<void>;
+  };
+}
+
+export type CorrectExecuteAsModalOptions = {
+  commandName: string;
+  interactive?: boolean;
+  timeOut?: number;
+}
+
+export type ExtendedExecutionContext = Omit<CorrectExecutionContext, "onCancel"> & ReturnType<typeof createModifyingBatchPlayContext> & {
+  signal: AbortSignal;
+};
+
+const originalExecuteAsModal: <T>(fn: (executionContext: CorrectExecutionContext) => Promise<void>, opts: CorrectExecuteAsModalOptions) => Promise<T> = core.executeAsModal as any;
+
+type OptionsWithoutCommandName = Omit<CorrectExecuteAsModalOptions, "commandName">;
+
+export async function executeAsModal<T>(commandName: string, fn: (executionContext: ExtendedExecutionContext) => Promise<T>, opts?: OptionsWithoutCommandName): Promise<T> {
+  let error: unknown;
+  let result: T;
+  await originalExecuteAsModal(async (executionContext) => {
+    const abortController = new AbortController();
+    executionContext.onCancel = () => {
+      abortController.abort();
+    };
+    // we cannot do a spread here, because not all properties are enumerable
+    const extendedExecutionContext: ExtendedExecutionContext = {
+      isCancelled: executionContext.isCancelled,
+      reportProgress: executionContext.reportProgress,
+      hostControl: executionContext.hostControl,
+      signal: abortController.signal,
+      ...createModifyingBatchPlayContext(),
+    };
+    try {
+      result = await fn(extendedExecutionContext);
+    } catch (e) {
+      console.error("error in executeAsModal");
+      console.error(e);
+      error = e;
+    }
+  }, {
+    commandName,
+    ...opts,
+  });
+  if (error) {
+    throw error;
+  } else {
+    return result!;
+  }
+}

package/src/core/suspendHistory.ts

@@ -0,0 +1,15 @@
+import type { Document } from "photoshop/dom/Document";
+
+// The Adobe provided type is wrong
+export type SuspendHistoryContext = {};
+export async function suspendHistory<T>(
+  document: Document,
+  historyStateName: string,
+  fn: (context: SuspendHistoryContext) => Promise<T>
+): Promise<T> {
+  let result: T | undefined;
+  await document.suspendHistory(async (context) => {
+    result = await fn(context);
+  }, historyStateName);
+  return result!;
+}

package/src/core/suspendHistory.uxp-test.ts

@@ -0,0 +1,18 @@
+import type { Test } from "@bubblydoo/uxp-test-framework";
+import { expect } from "chai";
+import { suspendHistory } from "./suspendHistory";
+import { app } from "photoshop";
+
+export const suspendHistoryTest: Test = {
+  name: "core/suspendHistory should return correctly",
+  async run() {
+    const document = app.activeDocument;
+    if (!document) {
+      throw new Error("No active document");
+    }
+    const result = await suspendHistory(document, "Test", async (context) => {
+      return 'test';
+    });
+    expect(result).to.equal('test');
+  },
+};

package/src/core-wrappers/executeAsModalAndSuspendHistory.ts

@@ -0,0 +1,11 @@
+import type { Document } from "photoshop/dom/Document";
+import { suspendHistory, type SuspendHistoryContext } from "../core/suspendHistory";
+import { executeAsModal, type ExtendedExecutionContext } from "../core/executeAsModal";
+
+type CombinedFn<T> = (executionContext: ExtendedExecutionContext, suspendHistoryContext: SuspendHistoryContext) => Promise<T>;
+
+export const executeAsModalAndSuspendHistory = async <T>(commandName: string, document: Document, fn: CombinedFn<T>): Promise<T> => {
+  return await executeAsModal(commandName, async (ctx) => {
+    return await suspendHistory(document, commandName, (suspendHistoryContext) => fn(ctx, suspendHistoryContext));
+  });
+};

package/src/dom/getFlattenedDomLayersList.ts

@@ -0,0 +1,43 @@
+import { constants } from "photoshop";
+import type { Layer as DomLayer } from "photoshop/dom/Layer";
+
+// get all layers (including nested in groups)
+// TODO: I would rename this to getAllDOMLayers to avoid confusion with UXPToolkitLayer
+export const getFlattenedDomLayersList = (
+  layers: DomLayer[],
+): DomLayer[] => {
+  const allLayers: DomLayer[] = [];
+
+  // Use a stack to avoid maximal call stack size (recursion) errors efficiently
+  const stack: DomLayer[] = [];
+
+  // Initialize stack with input layers in reverse order so the first layer is popped first.
+  // We use a manual loop because 'layers' can be a Photoshop 'Layers' collection object
+  // or an Array, and this covers both efficiently.
+  for (let i = layers.length - 1; i >= 0; i--) {
+    stack.push(layers[i]!);
+  }
+
+  while (stack.length > 0) {
+    const layer = stack.pop();
+    if (!layer) continue;
+
+    allLayers.push(layer);
+
+    // Check for group
+    if (layer.kind === constants.LayerKind.GROUP) {
+      // PERF: Accessing '.layers' on a DOM object is an expensive IPC call.
+      // We must cache it in a variable ensuring we only access it ONCE per group.
+      const children = layer.layers;
+
+      if (children && children.length > 0) {
+        // Push children in reverse to maintain depth-first standard order
+        for (let i = children.length - 1; i >= 0; i--) {
+          stack.push(children[i]!);
+        }
+      }
+    }
+  }
+
+  return allLayers;
+};

package/src/dom/photoshopDomLayersToTree.ts

@@ -0,0 +1,18 @@
+import type { Layer as DomLayer } from "photoshop/dom/Layer";
+import type { Tree } from "../general-tree/treeTypes";
+
+// get layers recursively
+export const photoshopDomLayersToTree = (layers: DomLayer[]): Tree<DomLayer> => {
+  // Get top-level layers
+  const filteredLayers = layers.filter((layer) => layer.parent === null);
+
+  const generateTree = (layers: DomLayer[]): Tree<DomLayer> => {
+    return layers.map((layer: DomLayer) => ({
+      ref: layer,
+      name: layer.name,
+      ...(layer.layers && { children: generateTree(layer.layers) }),
+    }));
+  };
+
+  return generateTree(filteredLayers);
+};

package/src/error-sourcemaps/sourcemaps.ts

@@ -0,0 +1,100 @@
+import ErrorStackParser from "error-stack-parser";
+import { SourceMapConsumer } from "source-map-js";
+import { storage } from "uxp";
+import { pathResolve } from "../node-compat/path/resolvePath";
+import { UTError } from "../errors/ut-error";
+
+export type BasicStackFrame = Pick<
+  ErrorStackParser.StackFrame,
+  "functionName" | "fileName" | "lineNumber" | "columnNumber"
+>;
+
+export async function parseUxpErrorSourcemaps(error: Error, opts: { unsourcemappedHeaderLines?: number } = {}) {
+  const parsedError = parseErrorIntoBasicStackFrames(error);
+
+  const unsourcemappedHeaderLines = opts.unsourcemappedHeaderLines ?? 0;
+
+  const loadedFilesCache: Record<string, storage.File> = {};
+
+  const fs = (storage as any).localFileSystem;
+  const parsedMappedError: BasicStackFrame[] = [];
+  for (const frame of parsedError) {
+    if (!frame.fileName || !frame.lineNumber || !frame.columnNumber) {
+      parsedMappedError.push(frame);
+      continue;
+    }
+    const entryPath = "plugin:" + frame.fileName;
+    const file =
+      loadedFilesCache[entryPath] ??
+      ((await fs.getEntryWithUrl(entryPath)) as storage.File);
+    loadedFilesCache[entryPath] = file;
+    if (!file.isFile) {
+      parsedMappedError.push(frame);
+      continue;
+    }
+    const sourcemapFileEntryPath = entryPath + ".map";
+    const sourcemapFile =
+      loadedFilesCache[sourcemapFileEntryPath] ??
+      ((await fs.getEntryWithUrl(sourcemapFileEntryPath)) as storage.File);
+    loadedFilesCache[sourcemapFileEntryPath] = sourcemapFile;
+    if (!sourcemapFile.isFile) {
+      parsedMappedError.push(frame);
+      continue;
+    }
+    const sourcemapContents = (await sourcemapFile.read({})) as string;
+    const sourcemap = JSON.parse(sourcemapContents);
+    const smc = new SourceMapConsumer(sourcemap);
+    const mappedFrame = smc.originalPositionFor({
+      line: frame.lineNumber - unsourcemappedHeaderLines,
+      column: frame.columnNumber,
+    });
+    if (mappedFrame.source && mappedFrame.line && mappedFrame.column) {
+      parsedMappedError.push({
+        ...frame,
+        fileName: mappedFrame.source,
+        lineNumber: mappedFrame.line,
+        columnNumber: mappedFrame.column,
+      } as ErrorStackParser.StackFrame);
+    } else {
+      parsedMappedError.push(frame);
+    }
+  }
+
+  return parsedMappedError;
+}
+
+function parseErrorIntoBasicStackFrames(error: Error): BasicStackFrame[] {
+  try {
+    const frames = ErrorStackParser.parse(error);
+    return frames.map((frame) => {
+      return {
+        functionName: frame.functionName,
+        fileName: frame.fileName,
+        lineNumber: frame.lineNumber,
+        columnNumber: frame.columnNumber,
+      };
+    });
+  } catch (e) {
+    throw new UTStacktraceParsingError("Failed to parse error stack trace", { cause: e });
+  }
+}
+
+export async function getBasicStackFrameAbsoluteFilePath(frame: BasicStackFrame): Promise<string> {
+  const pluginFolder = await (
+    storage as any
+  ).localFileSystem.getPluginFolder();
+  const absoluteFileName = pathResolve(
+    pluginFolder.nativePath,
+    "index.js",
+    frame.fileName!,
+  ).replace(/^plugin:/, "");
+  return `${absoluteFileName}:${frame.lineNumber}:${frame.columnNumber}`;
+}
+
+export class UTStacktraceParsingError extends UTError {
+  public override readonly name = "UTStacktraceParsingError";
+
+  constructor(message: string, opts: ErrorOptions = {}) {
+    super(message, opts);
+  }
+}

package/src/error-sourcemaps/sourcemaps.uxp-test.ts

@@ -0,0 +1,24 @@
+import type { Test } from "@bubblydoo/uxp-test-framework";
+import { parseUxpErrorSourcemaps } from "./sourcemaps";
+import { expect } from "chai";
+
+function throwError() {
+  throw new Error("Uncaught error"); // this error should stay exactly here in the source code, see below
+}
+
+export const sourcemapsTest: Test = {
+  name: "sourcemaps: should parse error sourcemaps",
+  async run() {
+    let error: Error;
+    try {
+      throwError();
+    } catch (e) {
+      error = e as Error;
+    }
+    const parsedError = await parseUxpErrorSourcemaps(error!);
+    console.log(parsedError);
+    expect(parsedError[0]!.fileName).to.include("sourcemaps.uxp-test.ts");
+    expect(parsedError[0]!.lineNumber).to.eq(6);
+    expect(parsedError[0]!.columnNumber).to.eq(8);
+  },
+};

package/src/errors/ut-error.ts

@@ -0,0 +1,6 @@
+export class UTError extends Error {
+  constructor(message: string, opts: ErrorOptions = {}) {
+    super(message, opts);
+    this.name = "UTError";
+  }
+}

package/src/filesystem/openFileByPath.ts

@@ -0,0 +1,10 @@
+import { app } from "photoshop";
+import { storage } from "uxp";
+import { executeAsModal } from "../core/executeAsModal";
+
+export async function openFileByPath(path: string) {
+  const fs = (storage as any).localFileSystem;
+  const file = (await fs.getEntryWithUrl(path)) as storage.File;
+  const doc = await executeAsModal("Open file", () => app.open(file as any));
+  return doc;
+}

package/src/general-tree/flattenTree.ts

@@ -0,0 +1,12 @@
+import type { Tree } from "./treeTypes";
+
+export function flattenTree<T>(tree: Tree<T>): Tree<T>[0][] {
+  const result: Tree<T>[0][] = [];
+  for (const node of tree) {
+    result.push(node);
+    if (node.children) {
+      result.push(...flattenTree(node.children));
+    }
+  }
+  return result;
+}

package/src/general-tree/layerRef.ts

@@ -0,0 +1,4 @@
+export type LayerRef = {
+  id: number;
+  docId: number;
+};

package/src/general-tree/mapTree.ts

@@ -0,0 +1,11 @@
+import type { Tree } from "./treeTypes";
+
+export function mapTree<TRef, TMappedRef>(tree: Tree<TRef>, mapFn: (node: TRef) => TMappedRef): Tree<TMappedRef> {
+  return tree.map((node) => {
+    return {
+      ...node,
+      ref: mapFn(node.ref),
+      children: node.children ? mapTree(node.children, mapFn) : undefined,
+    };
+  });
+}

package/src/general-tree/mapTreeRef.ts

@@ -0,0 +1,11 @@
+import type { Tree } from "./treeTypes";
+
+export function mapTreeRef<TRef, TMappedRef>(tree: Tree<TRef>, mapFn: (node: TRef) => TMappedRef): Tree<TMappedRef> {
+  return tree.map((node) => {
+    return {
+      ...node,
+      ref: mapFn(node.ref),
+      children: node.children ? mapTreeRef(node.children, mapFn) : undefined,
+    };
+  });
+}