Fixes for image services (v4)

stephenwf · stephenwf · commit a1722c515adb · 2026-02-15T18:33:59.000Z
diff --git a/__tests__/presentation-4-parser/service-profile-retention.test.ts b/__tests__/presentation-4-parser/service-profile-retention.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'vitest';
+import { normalize, serialize, serializeConfigPresentation3, serializeConfigPresentation4 } from '../../src/presentation-4';
+
+function createManifestWithImageService() {
+  return {
+    '@context': 'http://iiif.io/api/presentation/4/context.json',
+    id: 'https://example.org/manifest/service-profile',
+    type: 'Manifest',
+    label: { en: ['service profile retention'] },
+    items: [
+      {
+        id: 'https://example.org/canvas/1',
+        type: 'Canvas',
+        width: 1000,
+        height: 1000,
+        items: [
+          {
+            id: 'https://example.org/canvas/1/page/1',
+            type: 'AnnotationPage',
+            items: [
+              {
+                id: 'https://example.org/canvas/1/annotation/1',
+                type: 'Annotation',
+                motivation: ['painting'],
+                body: [
+                  {
+                    id: 'https://example.org/image/1/full/max/0/default.jpg',
+                    type: 'Image',
+                    format: 'image/jpeg',
+                    service: [
+                      {
+                        id: 'https://example.org/image/1',
+                        type: 'ImageService3',
+                        profile: 'level1',
+                      },
+                    ],
+                  },
+                ],
+                target: ['https://example.org/canvas/1'],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+describe('presentation-4 service profile retention', () => {
+  test('keeps service profile when serializing to presentation-4', () => {
+    const normalized = normalize(createManifestWithImageService() as any);
+    const storedService = normalized.entities.Service['https://example.org/image/1'] as any;
+    expect(storedService.profile).toBe('level1');
+
+    const serialized = serialize<any>(
+      {
+        entities: normalized.entities as any,
+        mapping: normalized.mapping as any,
+        requests: {},
+      },
+      normalized.resource,
+      serializeConfigPresentation4
+    );
+
+    const serializedService = serialized.items[0].items[0].items[0].body[0].service[0];
+    expect(serializedService.id).toBe('https://example.org/image/1');
+    expect(serializedService.type).toBe('ImageService3');
+    expect(serializedService.profile).toBe('level1');
+  });
+
+  test('keeps service profile when downgrading to presentation-3', () => {
+    const normalized = normalize(createManifestWithImageService() as any);
+
+    const serialized = serialize<any>(
+      {
+        entities: normalized.entities as any,
+        mapping: normalized.mapping as any,
+        requests: {},
+      },
+      normalized.resource,
+      serializeConfigPresentation3
+    );
+
+    const body = serialized.items[0].items[0].items[0].body;
+    const serializedBody = Array.isArray(body) ? body[0] : body;
+    const serializedService = serializedBody.service[0];
+    expect(serializedService.id).toBe('https://example.org/image/1');
+    expect(serializedService.type).toBe('ImageService3');
+    expect(serializedService.profile).toBe('level1');
+  });
+});
diff --git a/__tests__/presentation-4-parser/specific-resource-parity.test.ts b/__tests__/presentation-4-parser/specific-resource-parity.test.ts
@@ -1,35 +1,35 @@
-import { describe, expect, test } from "vitest";
-import { normalize } from "../../src/presentation-4";
+import { describe, expect, test } from 'vitest';
+import { normalize, serialize, serializeConfigPresentation4 } from '../../src/presentation-4';
 
-describe("presentation-4 specific resource parity", () => {
-  test("coerces start, range items, and annotation target for v3 input and keeps selectors", () => {
+describe('presentation-4 specific resource parity', () => {
+  test('coerces start, range items, and annotation target for v3 input and keeps selectors', () => {
     const manifest = {
-      "@context": "http://iiif.io/api/presentation/3/context.json",
-      id: "https://example.org/manifest/p3-upgrade",
-      type: "Manifest",
-      label: { en: ["p3 specific resource parity"] },
-      start: "https://example.org/canvas/1#t=5,15",
+      '@context': 'http://iiif.io/api/presentation/3/context.json',
+      id: 'https://example.org/manifest/p3-upgrade',
+      type: 'Manifest',
+      label: { en: ['p3 specific resource parity'] },
+      start: 'https://example.org/canvas/1#t=5,15',
       items: [
         {
-          id: "https://example.org/canvas/1",
-          type: "Canvas",
+          id: 'https://example.org/canvas/1',
+          type: 'Canvas',
           width: 1000,
           height: 1000,
           items: [
             {
-              id: "https://example.org/canvas/1/page/1",
-              type: "AnnotationPage",
+              id: 'https://example.org/canvas/1/page/1',
+              type: 'AnnotationPage',
               items: [
                 {
-                  id: "https://example.org/canvas/1/annotation/1",
-                  type: "Annotation",
-                  motivation: "painting",
+                  id: 'https://example.org/canvas/1/annotation/1',
+                  type: 'Annotation',
+                  motivation: 'painting',
                   body: {
-                    id: "https://example.org/image/1.jpg",
-                    type: "Image",
-                    format: "image/jpeg",
+                    id: 'https://example.org/image/1.jpg',
+                    type: 'Image',
+                    format: 'image/jpeg',
                   },
-                  target: "https://example.org/canvas/1#xywh=10,20,30,40",
+                  target: 'https://example.org/canvas/1#xywh=10,20,30,40',
                 },
               ],
             },
@@ -38,17 +38,17 @@ describe("presentation-4 specific resource parity", () => {
       ],
       structures: [
         {
-          id: "https://example.org/range/1",
-          type: "Range",
-          items: ["https://example.org/canvas/1#t=0,10"],
+          id: 'https://example.org/range/1',
+          type: 'Range',
+          items: ['https://example.org/canvas/1#t=0,10'],
         },
       ],
     };
 
     const result = normalize(manifest as any);
-    const normalizedManifest = result.entities.Manifest["https://example.org/manifest/p3-upgrade"] as any;
-    const normalizedRange = result.entities.Range["https://example.org/range/1"] as any;
-    const normalizedAnnotation = result.entities.Annotation["https://example.org/canvas/1/annotation/1"] as any;
+    const normalizedManifest = result.entities.Manifest['https://example.org/manifest/p3-upgrade'] as any;
+    const normalizedRange = result.entities.Range['https://example.org/range/1'] as any;
+    const normalizedAnnotation = result.entities.Annotation['https://example.org/canvas/1/annotation/1'] as any;
     const startSelector = Array.isArray(normalizedManifest.start.selector)
       ? normalizedManifest.start.selector[0]
       : normalizedManifest.start.selector;
@@ -59,24 +59,91 @@ describe("presentation-4 specific resource parity", () => {
       ? normalizedAnnotation.target[0].selector[0]
       : normalizedAnnotation.target[0].selector;
 
-    expect(normalizedManifest.start.type).toBe("SpecificResource");
-    expect(normalizedManifest.start.source.id).toBe("https://example.org/canvas/1");
-    expect(startSelector.type).toBe("FragmentSelector");
-    expect(startSelector.value).toBe("t=5,15");
+    expect(normalizedManifest.start.type).toBe('SpecificResource');
+    expect(normalizedManifest.start.source.id).toBe('https://example.org/canvas/1');
+    expect(startSelector.type).toBe('FragmentSelector');
+    expect(startSelector.value).toBe('t=5,15');
 
-    expect(normalizedRange.items[0].type).toBe("SpecificResource");
-    expect(normalizedRange.items[0].source.id).toBe("https://example.org/canvas/1");
-    expect(rangeSelector.type).toBe("FragmentSelector");
-    expect(rangeSelector.value).toBe("t=0,10");
+    expect(normalizedRange.items[0].type).toBe('SpecificResource');
+    expect(normalizedRange.items[0].source.id).toBe('https://example.org/canvas/1');
+    expect(rangeSelector.type).toBe('FragmentSelector');
+    expect(rangeSelector.value).toBe('t=0,10');
 
-    expect(normalizedAnnotation.target[0].type).toBe("SpecificResource");
-    expect(normalizedAnnotation.target[0].source.id).toBe("https://example.org/canvas/1");
-    expect(targetSelector.type).toBe("FragmentSelector");
-    expect(targetSelector.value).toBe("xywh=10,20,30,40");
+    expect(normalizedAnnotation.target[0].type).toBe('SpecificResource');
+    expect(normalizedAnnotation.target[0].source.id).toBe('https://example.org/canvas/1');
+    expect(targetSelector.type).toBe('FragmentSelector');
+    expect(targetSelector.value).toBe('xywh=10,20,30,40');
 
     const selectorId = targetSelector.id;
     expect(selectorId).toBeTruthy();
     expect(result.entities.Selector[selectorId]).toBeTruthy();
-    expect(result.mapping[selectorId]).toBe("Selector");
+    expect(result.mapping[selectorId]).toBe('Selector');
+  });
+
+  test('preserves selector through normalize and serialize for native p4 fragment targets', () => {
+    const manifest = {
+      '@context': 'http://iiif.io/api/presentation/4/context.json',
+      id: 'https://example.org/manifest/p4-fragment-target',
+      type: 'Manifest',
+      label: { en: ['native p4 selector parity'] },
+      items: [
+        {
+          id: 'https://example.org/canvas/1',
+          type: 'Canvas',
+          width: 1000,
+          height: 1000,
+          items: [
+            {
+              id: 'https://example.org/canvas/1/page/1',
+              type: 'AnnotationPage',
+              items: [
+                {
+                  id: 'https://example.org/canvas/1/annotation/1',
+                  type: 'Annotation',
+                  motivation: ['commenting'],
+                  body: [
+                    {
+                      type: 'Text',
+                      id: 'https://example.org/body/1',
+                      format: 'text/plain',
+                    },
+                  ],
+                  target: ['https://example.org/canvas/1#xywh=11,22,33,44'],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const normalized = normalize(manifest as any);
+    const annotation = normalized.entities.Annotation['https://example.org/canvas/1/annotation/1'] as any;
+    const target = annotation.target[0];
+    const targetSelector = Array.isArray(target.selector) ? target.selector[0] : target.selector;
+
+    expect(target.type).toBe('SpecificResource');
+    expect(target.source.id).toBe('https://example.org/canvas/1');
+    expect(targetSelector.type).toBe('FragmentSelector');
+    expect(targetSelector.value).toBe('xywh=11,22,33,44');
+
+    const serialized = serialize<any>(
+      {
+        entities: normalized.entities as any,
+        mapping: normalized.mapping as any,
+        requests: {},
+      },
+      normalized.resource,
+      serializeConfigPresentation4
+    );
+    const serializedTarget = serialized.items[0].items[0].items[0].target[0];
+    const serializedSelector = Array.isArray(serializedTarget.selector)
+      ? serializedTarget.selector[0]
+      : serializedTarget.selector;
+
+    expect(serializedTarget.type).toBe('SpecificResource');
+    expect(serializedTarget.source.id).toBe('https://example.org/canvas/1');
+    expect(serializedSelector.type).toBe('FragmentSelector');
+    expect(serializedSelector.value).toBe('xywh=11,22,33,44');
   });
 });
diff --git a/__tests__/presentation-4-parser/traverse.test.ts b/__tests__/presentation-4-parser/traverse.test.ts
@@ -43,4 +43,36 @@ describe("presentation-4 traverse", () => {
     expect(seen.selector).toBeGreaterThan(0);
     expect(seen.contentResource).toBeGreaterThan(0);
   });
+
+  test("traverses selector on implicit specific resource annotation target", () => {
+    let selectorCount = 0;
+    const traverse = new Traverse({
+      selector: [() => void (selectorCount += 1)],
+    });
+
+    const annotation = {
+      id: "https://example.org/anno/1",
+      type: "Annotation",
+      motivation: ["painting"],
+      target: [
+        {
+          source: {
+            id: "https://example.org/canvas/1",
+            type: "Canvas",
+          },
+          selector: {
+            type: "FragmentSelector",
+            value: "xywh=10,20,30,40",
+          },
+        },
+      ],
+    };
+
+    const traversed = traverse.traverseAnnotation(annotation, undefined, "$.annotation");
+    const target = traversed.target[0];
+
+    expect(target.type).toBe("SpecificResource");
+    expect(target.selector[0].type).toBe("FragmentSelector");
+    expect(selectorCount).toBe(1);
+  });
 });
diff --git a/src/presentation-4/serialize-presentation-3.ts b/src/presentation-4/serialize-presentation-3.ts
@@ -1,5 +1,5 @@
+import { type SerializeConfig, UNSET } from "./serialize";
 import { PRESENTATION_3_CONTEXT, sceneComponentTypes } from "./utilities";
-import { SerializeConfig } from "./serialize";
 
 const unsupportedSelectorTypes = new Set(["PointSelector", "WktSelector", "AnimationSelector"]);
 const unsupportedContainerTypes = new Set(["Scene"]);
@@ -20,12 +20,12 @@ function unsupported(message: string): never {
   throw new Error(`Presentation 4 -> 3 downgrade unsupported: ${message}`);
 }
 
-function filterList<T>(value: T[] | T | undefined): T[] | undefined {
-  if (!value) {
+function filterList<T>(value: T[] | T | typeof UNSET | undefined): T[] | undefined {
+  if (!value || value === UNSET) {
     return undefined;
   }
   const list = Array.isArray(value) ? value : [value];
-  const filtered = list.filter(Boolean);
+  const filtered = list.filter((item) => item !== UNSET && Boolean(item));
   return filtered.length ? filtered : undefined;
 }
 
@@ -103,8 +103,8 @@ function* linkedProperties(entity: any): Generator<any, any, any> {
     ["thumbnail", filterList(yield entity.thumbnail)],
     ["provider", filterList(yield entity.provider)],
     ["seeAlso", filterList(yield entity.seeAlso)],
-    ["service", filterList(entity.service || [])],
-    ["services", filterList(entity.services || [])],
+    ["service", filterList(yield entity.service)],
+    ["services", filterList(yield entity.services)],
     ["homepage", filterList(yield entity.homepage)],
     ["rendering", filterList(yield entity.rendering)],
     ["partOf", filterList(yield entity.partOf)],
diff --git a/src/presentation-4/serialize-presentation-4.ts b/src/presentation-4/serialize-presentation-4.ts
@@ -1,5 +1,5 @@
+import { type SerializeConfig, UNSET } from "./serialize";
 import { PRESENTATION_4_CONTEXT } from "./utilities";
-import { SerializeConfig, UNSET } from "./serialize";
 
 function filterList<T>(value: T[] | typeof UNSET): T[] | undefined {
   if (value === UNSET) {
@@ -59,8 +59,8 @@ function* withLinkedProperties(entity: any): Generator<any, Array<[string, any]>
     ["thumbnail", filterList(yield entity.thumbnail)],
     ["provider", filterList(yield entity.provider)],
     ["seeAlso", filterList(yield entity.seeAlso)],
-    ["service", filterList(entity.service || [])],
-    ["services", filterList(entity.services || [])],
+    ["service", filterList(yield entity.service)],
+    ["services", filterList(yield entity.services)],
     ["homepage", filterList(yield entity.homepage)],
     ["rendering", filterList(yield entity.rendering)],
     ["partOf", filterList(yield entity.partOf)],
diff --git a/src/presentation-4/serialize.ts b/src/presentation-4/serialize.ts
@@ -59,7 +59,9 @@ function resolveResource(
   }
 
   const id = value.id || value["@id"];
-  const type = value.type || value["@type"] || state.mapping[id];
+  const explicitType = value.type || value["@type"];
+  const mappedType = id ? state.mapping[id] : undefined;
+  const type = explicitType && state.entities[explicitType] ? explicitType : mappedType || explicitType;
   const store = type ? state.entities[type] : undefined;
   if (!id || !type || !store) {
     return [undefined, undefined];
@@ -102,12 +104,17 @@ export function serialize<Return>(
       throw new Error(`Circular reference at ${sub.type}(${sub.id})`);
     }
 
-    const generator = config[sub.type];
+    const mappedType = sub.id ? state.mapping[sub.id] : undefined;
+    const serializerType = config[sub.type] ? sub.type : mappedType && config[mappedType] ? mappedType : sub.type;
+    const generator = config[serializerType];
     if (!generator) {
       return UNSET;
     }
 
-    const [resource, full] = resolveResource(state, sub);
+    const [resource, full] = resolveResource(
+      state,
+      serializerType === sub.type ? sub : { ...sub, type: serializerType }
+    );
     if (!resource) {
       return UNSET;
     }
diff --git a/src/presentation-4/traverse.ts b/src/presentation-4/traverse.ts
