@bubblydoo/uxp-toolkit 0.0.3 → 0.0.5

package/src/commands-library/getDocument.txt

@@ -0,0 +1,62 @@
+// Object
+// EXIF: "EXIF tag 100274 Normal\rEXIF tag 100282 72.0\rEXIF tag 100283 72.0\rEXIF tag 100296 Inches\rEXIF tag 100305 Adobe Photoshop 27.3 (20251221.m.3348 0256c3c)  (Macintosh)\rEXIF tag 100306 2026:01:30 11:20:57\rEXIF tag 140961 Uncalibrated\rEXIF tag 140962 100\rEXIF tag 140963 100\r"
+// XMPMetadataAsUTF8: "<?xpacket begin=\"\" id=\"W5M0MpCehiHzreSzNTczkc
+// backgroundSaveInfo: {isPendingNormalSave: false}
+// bigNudgeH: 655360
+// bigNudgeV: 655360
+// center: {_obj: "paint", horizontal: {…}, vertical: {…}}
+// clippingPathInfo: {_obj: "clippingInfo", clippingPathIndex: -1, clippingPathFlatness: 0}
+// contentCredentialsEnabled: false
+// copyright: false
+// count: 3
+// depth: 8
+// documentID: 101
+// duotoneInk: 0
+// extension: (3) ["PSD", "PDD", "PSDT"]
+// fileInfo: {_obj: "fileInfo"}
+// fileReference: {_path: "/Users/otto/Code/projects/bubbly/uxp-toolkit/packa…t/uxp-tests-plugin/fixtures/one-layer-with-bg.psd", _kind: "local"}
+// format: "Photoshop"
+// genTechModelsUsed: []
+// generatorSettings: {_obj: "generatorSettings"}
+// guidesVisibility: true
+// hasBackgroundLayer: true
+// height: {_unit: "distanceUnit", _value: 100}
+// histogram: (256) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1698, 19, 5, 10, 3, 11, 6, 7, 4, 1, 2, 2, 4, 2, 3, 0, 2, 4, 2, 0, 4, 1, 4, 1, 3, 4, 0, …]
+// isCloudDoc: false
+// isDirty: false
+// isUsingGenTech: false
+// itemIndex: 2
+// manage: {_enum: "manage", _value: "none"}
+// measurementScale: {_obj: "measurementScale", _target: Array(2), to: {…}}
+// mimeType: "application/vnd.adobe.photoshop"
+// mode: {_enum: "colorSpace", _value: "RGBColor"}
+// numberOfChannels: 3
+// numberOfLayers: 1
+// numberOfPaths: 0
+// patternPreviewMode: false
+// pixelScaleFactor: {_unit: "noneUnit", _value: 1}
+// printColorHandling: {_enum: "printColorHandling", _value: "printerManaged"}
+// printCopies: 1
+// printCurrentPrinter: "EPSON ET-8500 Series"
+// printOutput: {_obj: "printOutput", postScriptColor: true, intent: {…}, printSixteenBit: false, printerName: "", …}
+// printOutputOptions: {_obj: "printOutputOptions", caption: false, calibrationBars: false, registrationMarks: false, cornerCropMarks: false, …}
+// printerList: ["Brother MFC-L3750CDW series"]
+// quickMask: false
+// resolution: {_unit: "densityUnit", _value: 72}
+// rulerOriginH: 0
+// rulerOriginV: 0
+// rulersVisibility: true
+// selectionEdgesVisible: false
+// slices: {bounds: {…}, slices: Array(1)}
+// smartGuidesVisibility: true
+// targetLayers: [{…}]
+// targetLayersIDs: [{…}]
+// targetLayersIndexes: [{…}]
+// targetPathIndex: -1
+// targetPathVisibility: true
+// title: "one-layer-with-bg.psd"
+// visible: true
+// watermark: false
+// width: {_unit: "distanceUnit", _value: 100}
+// workPathIndex: -1
+// zoom: {_unit: "percentUnit", _value: 30.830188679245282}

package/src/commands-library/getLayer.ts

@@ -0,0 +1,56 @@
+import z from "zod";
+import { createCommand } from "../core/command";
+import type { PsLayerRef } from "../ut-tree/psLayerRef";
+
+const layerSchema = z.object({
+  name: z.string(),
+  visible: z.boolean(),
+  group: z.boolean(),
+  layerSection: z.object({
+    _value: z.enum([
+      "layerSectionStart",
+      "layerSectionEnd",
+      "layerSectionContent",
+    ]),
+    _enum: z.literal("layerSectionType"),
+  }),
+  layerKind: z.number(),
+  itemIndex: z.number(),
+  background: z.boolean(),
+  mode: z.object({
+    _enum: z.literal("blendMode"),
+    _value: z.string(),
+  }),
+  layerID: z.number(),
+  layerEffects: z.record(z.string(), z.object({
+    // "scale" does not have an "enabled" property, that's why it's optional
+    enabled: z.boolean().optional(),
+  }).or(z.array(z.object({
+    enabled: z.boolean(),
+  })))).optional(),
+});
+
+export function createGetLayerCommand(layerRef: PsLayerRef) {
+  return createCommand({
+    modifying: false,
+    descriptor: {
+      _obj: "get",
+      _target: [
+        { _ref: "layer", _id: layerRef.id },
+        { _ref: "document", _id: layerRef.docId },
+      ],
+    },
+    schema: layerSchema,
+  });
+}
+
+export function createGetBackgroundLayerCommand(docId: number) {
+  return createCommand({
+    modifying: false,
+    descriptor: {
+      _obj: "get",
+      _target: { _ref: [{ _ref: "layer", "_property": "background" }, { _ref: "document", _id: docId }] },
+    },
+    schema: layerSchema,
+  });
+}

package/src/commands-library/getLayer.txt

@@ -0,0 +1,186 @@
+{
+    "layerID": 1,
+    "group": false,
+    "name": "Background",
+    "color": {
+        "_enum": "color",
+        "_value": "none"
+    },
+    "visible": true,
+    "mode": {
+        "_enum": "blendMode",
+        "_value": "normal"
+    },
+    "opacity": 255,
+    "itemIndex": 1,
+    "count": 2,
+    "preserveTransparency": true,
+    "layerFXVisible": false,
+    "globalAngle": 90,
+    "background": true,
+    "layerSection": {
+        "_enum": "layerSectionType",
+        "_value": "layerSectionContent"
+    },
+    "layerLocking": {
+        "_obj": "layerLocking",
+        "protectTransparency": true,
+        "protectComposite": false,
+        "protectPosition": true,
+        "protectArtboardAutonest": true,
+        "protectAll": false
+    },
+    "targetChannels": [
+        {
+            "_ref": "channel",
+            "_index": 1
+        },
+        {
+            "_ref": "channel",
+            "_index": 2
+        },
+        {
+            "_ref": "channel",
+            "_index": 3
+        }
+    ],
+    "visibleChannels": [
+        {
+            "_ref": "channel",
+            "_index": 1
+        },
+        {
+            "_ref": "channel",
+            "_index": 2
+        },
+        {
+            "_ref": "channel",
+            "_index": 3
+        }
+    ],
+    "channelRestrictions": [
+        {
+            "_enum": "channel",
+            "_value": "red"
+        },
+        {
+            "_enum": "channel",
+            "_value": "grain"
+        },
+        {
+            "_enum": "channel",
+            "_value": "blue"
+        }
+    ],
+    "fillOpacity": 255,
+    "hasUserMask": false,
+    "hasVectorMask": false,
+    "proportionalScaling": false,
+    "layerKind": 1,
+    "hasFilterMask": false,
+    "userMaskDensity": 255,
+    "userMaskFeather": 0,
+    "vectorMaskDensity": 255,
+    "vectorMaskFeather": 0,
+    "filterMaskDensity": 255,
+    "filterMaskFeather": 0,
+    "bounds": {
+        "_obj": "rectangle",
+        "top": {
+            "_unit": "pixelsUnit",
+            "_value": 0
+        },
+        "left": {
+            "_unit": "pixelsUnit",
+            "_value": 0
+        },
+        "bottom": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "right": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "width": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "height": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        }
+    },
+    "boundsNoEffects": {
+        "_obj": "rectangle",
+        "top": {
+            "_unit": "pixelsUnit",
+            "_value": 0
+        },
+        "left": {
+            "_unit": "pixelsUnit",
+            "_value": 0
+        },
+        "bottom": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "right": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "width": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "height": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        }
+    },
+    "boundsNoMask": {
+        "_obj": "rectangle",
+        "top": {
+            "_unit": "pixelsUnit",
+            "_value": 0
+        },
+        "left": {
+            "_unit": "pixelsUnit",
+            "_value": 0
+        },
+        "bottom": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "right": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "width": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        },
+        "height": {
+            "_unit": "pixelsUnit",
+            "_value": 100
+        }
+    },
+    "useAlignedRendering": false,
+    "generatorSettings": {
+        "_obj": "generatorSettings"
+    },
+    "keyOriginType": [],
+    "fillEnabled": false,
+    "animationProtection": {
+        "_obj": "animationProtection",
+        "animationUnifyPosition": false,
+        "animationUnifyEffects": false,
+        "animationUnifyVisibility": false,
+        "animationPropagate": true
+    },
+    "isSyntheticFill": false,
+    "artboardEnabled": false,
+    "vectorMaskEmpty": true,
+    "textWarningLevel": 0,
+    "parentLayerID": -1
+}

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

@@ -1,13 +1,13 @@
 import { executeAsModal } from "../core/executeAsModal";
 import { openFileByPath } from "../filesystem/openFileByPath";
-import { getLayerProperties } from "../ut-tree/getLayerProperties";
+import { getDocumentLayerDescriptors } 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);
+  const allLayers = await getDocumentLayerDescriptors(app.activeDocument.id);
   return {
     ref: {
       id: allLayers[0]!.layerID,
@@ -15,7 +15,7 @@ async function getFirstLayer() {
     },
     name: allLayers[0]!.name,
   };
-} 
+}
 
 export const renameLayerTest: Test = {
   name: "Rename Layer",
@@ -29,4 +29,4 @@ export const renameLayerTest: Test = {
     const layer2 = await getFirstLayer();
     expect(layer2.name).to.equal("New Name");
   },
-};
+};

package/src/core/command.test-d.ts

@@ -0,0 +1,25 @@
+import { describe, expectTypeOf, test } from "vitest";
+import { z } from "zod";
+import {
+  createCommand,
+  type UTCommandResult,
+} from "./command";
+
+describe("UTCommandResult type tests", () => {
+  test("extracts result type from non-modifying command", () => {
+    const command = createCommand({
+      descriptor: { _obj: "get" },
+      schema: z.object({
+        name: z.string(),
+        count: z.number(),
+      }),
+      modifying: false,
+    });
+
+    type Result = UTCommandResult<typeof command>;
+
+    expectTypeOf<Result>().toEqualTypeOf<{
+      name: string;
+      count: number;
+    }>();
+  });});

package/src/index.ts

@@ -18,14 +18,18 @@ export {
   type CorrectExecuteAsModalOptions,
   type ExtendedExecutionContext,
 } from "./core/executeAsModal";
-export { suspendHistory, type SuspendHistoryContext } from "./core/suspendHistory";
+export {
+  suspendHistory,
+  type SuspendHistoryContext,
+} from "./core/suspendHistory";
 
 // Core wrappers
 export { executeAsModalAndSuspendHistory } from "./core-wrappers/executeAsModalAndSuspendHistory";
 
 // Commands library
-export { getLayerProperties } from "./commands-library/getLayerProperties";
 export { createRenameLayerCommand } from "./commands-library/renameLayer";
+export { createGetDocumentCommand, createGetDocumentHasBackgroundLayerCommand } from "./commands-library/getDocument";
+export { createGetBackgroundLayerCommand } from "./commands-library/getLayer";
 
 // DOM – layers
 export { getFlattenedDomLayersList } from "./dom/getFlattenedDomLayersList";
@@ -47,27 +51,28 @@ export { copyToClipboard, readFromClipboard } from "./other/clipboard";
 export { uxpEntrypointsSchema } from "./other/uxpEntrypoints";
 
 // UT tree – layer descriptors & Photoshop tree
-export {
-  getFlattenedLayerDescriptorsList,
-  type LayerDescriptor,
-} from "./ut-tree/getFlattenedLayerDescriptorsList";
 export {
   createGetLayerPropertiesCommand,
-  getLayerProperties as getLayerPropertiesFromUtTree,
+  getDocumentLayerDescriptors as getLayerPropertiesFromUtTree,
 } from "./ut-tree/getLayerProperties";
-export {
-  createGetLayerCommand as createGetLayerEffectsCommand,
-  getLayerEffects,
-} from "./ut-tree/getLayerEffects";
-export {
-  photoshopLayerDescriptorsToUTLayers,
-  type UTLayer,
-} from "./ut-tree/photoshopLayerDescriptorsToUTLayers";
+export { getLayerEffects } from "./ut-tree/getLayerEffects";
+export { type UTLayer } from "./ut-tree/photoshopLayerDescriptorsToUTLayers";
 export { type PsLayerRef } from "./ut-tree/psLayerRef";
-export { utLayersToTree, type UTLayerWithoutChildren } from "./ut-tree/utLayersToTree";
+export {
+  utLayersToTree,
+  type UTLayerWithoutChildren,
+} from "./ut-tree/utLayersToTree";
+
+// UT tree – text
+export { utLayersToText as utTreeToText } from "./ut-tree/utLayersToText";
 
 // Util
 export { utLayerToDomLayer, utLayersToDomLayers } from "./util/utLayerToLayer";
+export { type UTLayerPickKeys } from "./util/utLayerPickKeysType";
 
 // Error sourcemaps
-export { parseUxpErrorSourcemaps, getBasicStackFrameAbsoluteFilePath, type BasicStackFrame } from "./error-sourcemaps/sourcemaps";
+export {
+  parseUxpErrorSourcemaps,
+  getBasicStackFrameAbsoluteFilePath,
+  type BasicStackFrame,
+} from "./error-sourcemaps/sourcemaps";

package/src/ut-tree/getLayerEffects.ts

@@ -1,36 +1,13 @@
 
 import { type PsLayerRef } from "./psLayerRef";
-import { batchPlayCommand, createCommand } from "../core/command";
-import { z } from "zod";
-
-export function createGetLayerCommand(layerRef: PsLayerRef) {
-  return createCommand({
-    modifying: false,
-    descriptor: {
-      _obj: "get",
-      _target: [
-        { _ref: "layer", _id: layerRef.id },
-        { _ref: "document", _id: layerRef.docId },
-      ],
-    },
-    schema: z.object({
-      layerID: z.number(),
-      group: z.boolean().optional(),
-      layerEffects: z.record(z.string(), z.object({
-        // "scale" does not have an "enabled" property, that's why it's optional
-        enabled: z.boolean().optional(),
-      }).or(z.array(z.object({
-        enabled: z.boolean(),
-      })))).optional(),
-    }),
-  });
-}
+import { batchPlayCommand } from "../core/command";
+import { createGetLayerCommand } from "../commands-library/getLayer";
 
 export async function getLayerEffects(layerRef: PsLayerRef) {
   const result = await batchPlayCommand(createGetLayerCommand(layerRef));
 
   const data = result.layerEffects || {};
-  
+
   const effects: Record<string, boolean> = {};
 
   for (const effect in data) {

package/src/ut-tree/getLayerProperties.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
-import { batchPlayCommand, createCommand } from "../core/command";
+import { batchPlayCommand, batchPlayCommands, createCommand } from "../core/command";
+import { createGetDocumentHasBackgroundLayerCommand } from "../commands-library/getDocument";
+import { createGetBackgroundLayerCommand } from "../commands-library/getLayer";
 
 export function createGetLayerPropertiesCommand(docId: number) {
   return createCommand({
@@ -8,7 +10,7 @@ export function createGetLayerPropertiesCommand(docId: number) {
       _obj: "multiGet",
       _target: { _ref: [{ _ref: "document", _id: docId }] },
       extendedReference: [
-        ["name", "layerID", "visible"],
+        ["name", "layerID", "visible", "group", "layerSection", "layerKind", "itemIndex", "background", "mode", "layerEffects"],
         { _obj: "layer", index: 1, count: -1 },
       ],
     },
@@ -17,7 +19,29 @@ export function createGetLayerPropertiesCommand(docId: number) {
         z.object({
           name: z.string(),
           layerID: z.number(),
-          visible: z.boolean().optional(),
+          visible: z.boolean(),
+          group: z.boolean(),
+          layerSection: z.object({
+            _value: z.enum([
+              "layerSectionStart",
+              "layerSectionEnd",
+              "layerSectionContent",
+            ]),
+            _enum: z.literal("layerSectionType"),
+          }),
+          layerKind: z.number(),
+          itemIndex: z.number(),
+          background: z.boolean(),
+          mode: z.object({
+            _enum: z.literal("blendMode"),
+            _value: z.string(),
+          }),
+          layerEffects: z.record(z.string(), z.object({
+            // "scale" does not have an "enabled" property, that's why it's optional
+            enabled: z.boolean().optional(),
+          }).or(z.array(z.object({
+            enabled: z.boolean(),
+          })))).optional(),
         })
       )
     })
@@ -25,11 +49,26 @@ export function createGetLayerPropertiesCommand(docId: number) {
 }
 
 // get layer properties like name and layerID for all layers in the document (by index)
-export const getLayerProperties = async (documentId: number) => {
-  const command = createGetLayerPropertiesCommand(documentId);
+export const getDocumentLayerDescriptors = async (documentId: number) => {
+  const [layersResult, documentHasBackgroundLayerResult] = await batchPlayCommands([
+    createGetLayerPropertiesCommand(documentId),
+    createGetDocumentHasBackgroundLayerCommand(documentId),
+  ]);
 
-  const result = await batchPlayCommand(command);
+  const backgroundLayerResult = documentHasBackgroundLayerResult.hasBackgroundLayer ? await batchPlayCommand(createGetBackgroundLayerCommand(documentId)) : null;
+
+  const list = [...layersResult.list].reverse();
+  if (backgroundLayerResult) {
+    list.push(backgroundLayerResult);
+  }
 
   // Reverse to get bottom-up order
-  return [...result.list].reverse();
+  return list.map((layerProp) => {
+    return {
+      ...layerProp,
+      docId: documentId,
+    };
+  });
 };
+
+export type LayerDescriptor = Awaited<ReturnType<typeof getDocumentLayerDescriptors>>[number];

package/src/ut-tree/hasBackgroundLayer.uxp-test.ts

@@ -0,0 +1,42 @@
+import { app } from "photoshop";
+import { openFileByPath } from "../filesystem/openFileByPath";
+import { batchPlayCommand } from "../core/command";
+import { expect } from "chai";
+import { createGetDocumentHasBackgroundLayerCommand } from "../commands-library/getDocument";
+import type { Test } from "@bubblydoo/uxp-test-framework";
+import { createGetBackgroundLayerCommand } from "../commands-library/getLayer";
+import { executeAsModal } from "../core/executeAsModal";
+
+export const backgroundLayerTest: Test = {
+  name: "Has/Get Background Layer",
+  async run() {
+    const doc = await openFileByPath("plugin:/fixtures/one-layer-with-bg.psd");
+    const hasBackgroundLayer = await batchPlayCommand(
+      createGetDocumentHasBackgroundLayerCommand(doc.id)
+    )
+    expect(hasBackgroundLayer.hasBackgroundLayer).to.be.true;
+    const layer = await batchPlayCommand(
+      createGetBackgroundLayerCommand(app.activeDocument.id)
+    )
+    expect(layer.name).to.equal("Background");
+    await executeAsModal("Close Document", async () => await doc.close(0));
+
+    const doc2 = await openFileByPath("plugin:/fixtures/one-layer.psd");
+
+    const hasBackgroundLayer2 = await batchPlayCommand(
+      createGetDocumentHasBackgroundLayerCommand(doc2.id)
+    )
+    expect(hasBackgroundLayer2.hasBackgroundLayer).to.be.false;
+    let rejected = false;
+    try {
+      await batchPlayCommand(
+        createGetBackgroundLayerCommand(doc2.id)
+      )
+    } catch (e) {
+      rejected = true;
+    }
+    expect(rejected).to.be.true;
+
+    await executeAsModal("Close Document", async () => await doc2.close(0));
+  },
+};