[feat] export annotation set [Round 2] #2704

panaC · 2024-12-11T09:16:22Z

This PR allows :

to import/export a ReadiumAnnotationSet
TextPositionSelector / TextQuoteSelector
use apache-annotator and fork this commit apache/incubator-annotator@cb534ed

For the CFI Selector : vivliostyle-cfi doesn't support CFI Range with the comma separator cf (only position supported)

This PR is on a blocking state as long as the CFI library issue is not resolved.

We leave the choice to use CFI for the moment
for the benefice to use a CssSelector refined by TextPositionSelector

Cf the spec made by Laurent : https://github.com/readium/annotations

I reintroduced the ProgressionSelector to keep this information across export/import in thorium annotation format. Progression is generated from the r2-navigator to chrome ui and not from the ui to the r2-navigator.

…ously used to import from main process without virtualDom

…the state root level. Now not specific to the search, search rely on this resourceCache just like import/export annotations routine

TODO: dispatch annotationQueue shift action across reader

main-process and broadcasted to every other browserWindow opened ANNOTATION_SHIFT_FROM_ANNOTATION_IMPORT_QUEUE need this mechanism

…our advice about this !

danielweck · 2024-12-18T10:34:38Z

yes I would also use the HTML body as the DOM tree root to compute text position and quote.
though interestingly, in principle anyway, the head could be omitted and the body in CFI and other indexed node path notations would be shifted ... which of course is not an issue in real world EPUB publications where the head pretty much exists all the time, especially as that's where the reading system injects stylesheets etc. :)

src/renderer/reader/redux/sagas/resourceCache.ts

panaC · 2024-12-18T14:22:35Z

Hello @danielweck, I let you review this PR for the import/export annotationSet part

CssSelector)

makeRefinable from apache-annotator TODO: need to define an heuristic of selector priority/importance

…note and do not create a duplicate note to the list

danielweck · 2025-01-29T20:19:58Z

So, I have been running a bunch of tests and I found this bug when attempting to import 4 saved annotations in the same document, after deleting 2 of the original ones:

importAnnotationSet TypeError: Cannot read properties of undefined (reading 'type')
at http://localhost:8191/index_reader.js:13477:16
at createMatcherWithRefinement (http://localhost:8191/index_reader.js:22351:21)
at convertSelectorTargetToLocatorExtended (http://localhost:8191/index_reader.js:13496:22)

tests.annotation:

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "urn:uuid:f53528cd-31fa-42b7-8f51-99afe1a4fae2",
  "type": "AnnotationSet",
  "generator": {
    "id": "https://github.com/edrlab/thorium-reader/releases/tag/v3.1.0-alpha.1",
    "type": "Software",
    "name": "Thorium 3.1.0-alpha.1",
    "homepage": "https://thorium.edrlab.org"
  },
  "generated": "2025-01-29T20:13:46.805Z",
  "title": "tests",
  "about": {
    "dc:identifier": [
      "urn:thorium:5e8bad02-6ac3-4ebd-a8d7-a68b7359eed2",
      "978-1-135-30619-9"
    ],
    "dc:format": "application/epub+zip",
    "dc:title": "LEARNING DISABILITIES",
    "dc:publisher": [
      "Routledge"
    ],
    "dc:creator": [
      "Bryant J.Cratty and Richard L.Goldman"
    ],
    "dc:date": ""
  },
  "items": [
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:de5c7924-82ac-4fba-abd4-113570d2c191",
      "created": "2025-01-29T20:12:06.393Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test4",
        "format": "text/plain",
        "color": "#D4C4FB",
        "tag": "test2",
        "highlight": "outline"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "OPS/xhtml/03_Title01.xhtml",
        "meta": {
          "headings": [],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": "body",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 243,
              "end": 245
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 243,
            "end": 245
          },
          {
            "type": "ProgressionSelector",
            "value": 0.544386877457405
          }
        ]
      }
    },
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:5fbb5eb5-d8de-4418-8c0a-7e4bda864b4e",
      "created": "2025-01-29T20:11:29.752Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test3",
        "format": "text/plain",
        "color": "#C1EAC5",
        "tag": "test1",
        "highlight": "strikethrough"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "OPS/xhtml/03_Title01.xhtml",
        "meta": {
          "headings": [],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": "body",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 135,
              "end": 154
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 135,
            "end": 154
          },
          {
            "type": "ProgressionSelector",
            "value": 0.32963016055045874
          }
        ]
      }
    },
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:061e66d7-0201-4572-9bdf-9e89efc932e4",
      "created": "2025-01-29T20:10:57.738Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test2",
        "format": "text/plain",
        "color": "#FEF3BD",
        "tag": "test2",
        "highlight": "underline"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "OPS/xhtml/03_Title01.xhtml",
        "meta": {
          "headings": [],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": "body",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 73,
              "end": 132
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 73,
            "end": 132
          },
          {
            "type": "ProgressionSelector",
            "value": 0.20932994757536041
          }
        ]
      }
    },
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:1d195e51-b3af-49d5-9ff8-21fc0262b9d2",
      "created": "2025-01-29T20:10:39.507Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test1",
        "format": "text/plain",
        "color": "#EB9694",
        "tag": "test1",
        "highlight": "solid"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "OPS/xhtml/03_Title01.xhtml",
        "meta": {
          "headings": [],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": ".title1a > i",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 1,
              "end": 8
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 48,
            "end": 55
          },
          {
            "type": "ProgressionSelector",
            "value": 0.12891136959370905
          }
        ]
      }
    }
  ]
}

danielweck · 2025-01-29T20:27:01Z

Note that I successfully ran the same scenario in a different publication (4 annotations in a single document, obviously with different DOM Ranges):

test.annotation

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "urn:uuid:9f6178bd-b016-4c18-a8a2-bc9f58f3a70f",
  "type": "AnnotationSet",
  "generator": {
    "id": "https://github.com/edrlab/thorium-reader/releases/tag/v3.1.0-alpha.1",
    "type": "Software",
    "name": "Thorium 3.1.0-alpha.1",
    "homepage": "https://thorium.edrlab.org"
  },
  "generated": "2025-01-29T20:23:48.671Z",
  "title": "daniel",
  "about": {
    "dc:identifier": [
      "urn:thorium:839a4c73-4fdf-4437-99fb-599e6b97a5af",
      "urn:isbn:9781449328030"
    ],
    "dc:format": "application/epub+zip",
    "dc:title": "Accessible EPUB 3",
    "dc:publisher": [
      "O’Reilly Media, Inc."
    ],
    "dc:creator": [
      "Matt Garrish"
    ],
    "dc:date": "2012-02-20T00:00:00.000Z"
  },
  "items": [
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:5d67dcc9-6cd6-487e-bb32-c96e40f252a0",
      "created": "2025-01-29T20:23:23.274Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test4",
        "format": "text/plain",
        "color": "#FEF3BD",
        "tag": "test1",
        "highlight": "strikethrough"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "EPUB/index.xhtml",
        "meta": {
          "headings": [
            {
              "txt": "Accessible EPUB 3",
              "level": 1
            }
          ],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": "#id2602563 > p:nth-child(2)",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 227,
              "end": 234
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 986,
            "end": 993
          },
          {
            "type": "TextQuoteSelector",
            "exact": "rademar",
            "prefix": "a t",
            "suffix": "k claim,"
          },
          {
            "type": "ProgressionSelector",
            "value": 0.5571244266055045
          }
        ]
      }
    },
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:f6d61ee6-dab0-466d-b346-f4785c9e9ef2",
      "created": "2025-01-29T20:22:56.067Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test3",
        "format": "text/plain",
        "color": "#D4C4FB",
        "tag": "test2",
        "highlight": "outline"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "EPUB/index.xhtml",
        "meta": {
          "headings": [
            {
              "txt": "Accessible EPUB 3",
              "level": 1
            }
          ],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": "#I_book_d1e1",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 1356,
              "end": 1431
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 1359,
            "end": 1434
          },
          {
            "type": "TextQuoteSelector",
            "exact": "O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol CA 95472\n\t\t\t",
            "prefix": "",
            "suffix": ""
          },
          {
            "type": "ProgressionSelector",
            "value": 0.7799393840104849
          }
        ]
      }
    },
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:437b65f3-e5c6-4b09-a776-cd6625ebdf53",
      "created": "2025-01-29T20:22:35.483Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test2",
        "format": "text/plain",
        "color": "#C1EAC5",
        "tag": "test2",
        "highlight": "underline"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "EPUB/index.xhtml",
        "meta": {
          "headings": [
            {
              "txt": "Accessible EPUB 3",
              "level": 1
            }
          ],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": "#I_book_d1e1",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 492,
              "end": 518
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 495,
            "end": 521
          },
          {
            "type": "TextQuoteSelector",
            "exact": ".\n\t\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\tN",
            "prefix": "[email protected]",
            "suffix": "utshell"
          },
          {
            "type": "ProgressionSelector",
            "value": 0.46238122542595017
          }
        ]
      }
    },
    {
      "@context": "http://www.w3.org/ns/anno.jsonld",
      "id": "urn:uuid:d81e21a5-8128-4e6c-8f2f-6d9c2b8167f1",
      "created": "2025-01-29T20:22:13.499Z",
      "type": "Annotation",
      "body": {
        "type": "TextualBody",
        "value": "test1",
        "format": "text/plain",
        "color": "#EB9694",
        "tag": "test1",
        "highlight": "solid"
      },
      "creator": {
        "id": "urn:uuid:395b3760-e3c6-4ea5-b9c5-35dae31e0d19",
        "type": "Organization",
        "name": ""
      },
      "target": {
        "source": "EPUB/index.xhtml",
        "meta": {
          "headings": [
            {
              "txt": "Accessible EPUB 3",
              "level": 1
            }
          ],
          "page": ""
        },
        "selector": [
          {
            "type": "CssSelector",
            "value": ".copyright",
            "refinedBy": {
              "type": "TextPositionSelector",
              "start": 9,
              "end": 17
            }
          },
          {
            "type": "TextPositionSelector",
            "start": 131,
            "end": 139
          },
          {
            "type": "TextQuoteSelector",
            "exact": " © 2012 ",
            "prefix": "Copyright",
            "suffix": "O’Reilly"
          },
          {
            "type": "ProgressionSelector",
            "value": 0.30229153014416776
          }
        ]
      }
    }
  ]
}

danielweck · 2025-01-29T20:32:38Z

The EPUB which causes the problem is protected by LCP, and I notice that the annotation set does not contain annotations with selector TextQuoteSelector ... whereas the non-DRM EPUB does. @panaC does this ring a bell?

… import (LCP protected EPUB?), also added DOM Range normalisation prior to convertRange() to guard against ranges created outside the navigator

danielweck · 2025-01-29T20:59:58Z

Adding if (textQuoteSelector) { seems to have fixed the import bug, but @panaC could you please confirm that this is because with LCP publications, this particular selector is intentionally left out?

EDIT: I found if (!isLcp) { ... now we just have to make sure that there are no other places where textQuoteSelector is used without guarding against undefined/null. Can you help @panaC ?

…daries, also fixed the collapsed range checks

… ... basic normalisation from user selection that can be reversed => same selected text can yield different annotations

danielweck · 2025-01-31T12:54:34Z

I found bugs in "creator" filtering, this affected export as well because of hidden / not-shown annotations in the list. I will merge this PR as-is and we can fix this later.

danielweck · 2025-01-31T13:11:56Z

Well done @panaC great work as usual! :)
I will now file a bug report in the issue tracker regarding the broken creator filtering

danielweck · 2025-01-31T13:17:02Z

Follow-up issue #2758

update readium annotation set model [skip ci]

403a942

panaC self-assigned this Dec 11, 2024

panaC added 12 commits December 12, 2024 12:16

annotation import FIFO queue from main to reader process

bf63fe5

update json schema selector

0429d08

apache-annotator

fff4963

lint and revert unused addAnnotationToReaderPublicatrion action previ…

6fed198

…ously used to import from main process without virtualDom

fix seachCachePublicationResources from search to ReaderRootState at …

effd92e

…the state root level. Now not specific to the search, search rely on this resourceCache just like import/export annotations routine

lint and type fixes on the third-party apache-annotator lib

c06ae34

[skip ci]

05e582d

set resourceCache to a dedicated file

c993d56

apache-annotator remove .js extension and fix type linting

e4268a0

export annotation [skip ci]

0304776

import annotation

1c85520

add textQuote in import process [skip ci]

cef265c

panaC mentioned this pull request Dec 17, 2024

feat: a reading window acquires the lock when multiple windows are opened with the same publication ID #2706

Merged

panaC added 6 commits December 17, 2024 15:22

Merge branch 'develop' into feat/export-annotation-2

e6990c0

add reader lock protection for importAnnotationSet function

87bdedc

TODO: dispatch annotationQueue shift action across reader

fix: add actionAcrossRenderer to dispatch action from renderer to

4245dc7

main-process and broadcasted to every other browserWindow opened ANNOTATION_SHIFT_FROM_ANNOTATION_IMPORT_QUEUE need this mechanism

fixes importQueue shift first elem immutability

c284410

remove unused addAnnotationToReaderPublication action

6a7bc53

lint and change xmlDom xhtml root to document.body @danielweck need y…

69f4c91

…our advice about this !

panaC commented Dec 18, 2024

View reviewed changes

src/renderer/reader/redux/sagas/resourceCache.ts Show resolved Hide resolved

panaC requested a review from danielweck December 18, 2024 14:21

panaC and others added 3 commits December 18, 2024 15:38

when annotation import add locatorExtended.locations info (rangeInfo and

cd89bf0

CssSelector)

Merge branch 'develop' into feat/export-annotation-2

a3fa129

fix: add cssSelector and progressionSelector, and apply it to

7cf31fa

makeRefinable from apache-annotator TODO: need to define an heuristic of selector priority/importance

panaC requested review from gautierchomel and arthur-lemeur December 20, 2024 16:44

panaC added 2 commits December 30, 2024 13:48

fix: old annotation imported from updated annotation, now update the …

7738eab

…note and do not create a duplicate note to the list

fix: import dialog labels

b3a39cd

panaC marked this pull request as ready for review December 30, 2024 12:53

panaC and others added 6 commits December 30, 2024 14:12

fixes en/fr i18n annotation dialog

c9184f7

up: origin label annotation import modal

8e9bb59

Merge branch 'develop' into feat/export-annotation-2

c4b4516

Merge branch 'develop' into feat/export-annotation-2

29d0b52

Merge branch 'develop' into feat/export-annotation-2

8271ae4

Merge branch 'develop' into feat/export-annotation-2

a1de16a

fix: guard against undefined/null TextQuoteSelector during annotation…

fee85e7

… import (LCP protected EPUB?), also added DOM Range normalisation prior to convertRange() to guard against ranges created outside the navigator

danielweck added 5 commits January 29, 2025 21:17

removed range normalisation as this can modify the original text boun…

71874f3

…daries, also fixed the collapsed range checks

added code comments about DOM Range document order (start/end points)…

d4a413f

… ... basic normalisation from user selection that can be reversed => same selected text can yield different annotations

[skip ci] added code comments about DOM Range document order contract

ea00f54

Merge branch 'develop' into feat/export-annotation-2

8aa456b

Merge branch 'develop' into feat/export-annotation-2

72132fd

English localisation improvements

3abeaf0

danielweck merged commit b9afc76 into develop Jan 31, 2025
8 checks passed

danielweck deleted the feat/export-annotation-2 branch January 31, 2025 13:12

danielweck mentioned this pull request Jan 31, 2025

bug in annotations filtering with creator #2758

Open

danielweck mentioned this pull request Jan 31, 2025

[Annotations import/export]: support of the annotation selectors from w3c annotation spec #2625

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[feat] export annotation set [Round 2] #2704

[feat] export annotation set [Round 2] #2704

panaC commented Dec 11, 2024 •

edited

Loading

danielweck commented Dec 18, 2024

panaC commented Dec 18, 2024

danielweck commented Jan 29, 2025

danielweck commented Jan 29, 2025

danielweck commented Jan 29, 2025

danielweck commented Jan 29, 2025 •

edited

Loading

danielweck commented Jan 31, 2025

danielweck commented Jan 31, 2025

danielweck commented Jan 31, 2025

[feat] export annotation set [Round 2] #2704

[feat] export annotation set [Round 2] #2704

Conversation

panaC commented Dec 11, 2024 • edited Loading

danielweck commented Dec 18, 2024

panaC commented Dec 18, 2024

danielweck commented Jan 29, 2025

danielweck commented Jan 29, 2025

danielweck commented Jan 29, 2025

danielweck commented Jan 29, 2025 • edited Loading

danielweck commented Jan 31, 2025

danielweck commented Jan 31, 2025

danielweck commented Jan 31, 2025

panaC commented Dec 11, 2024 •

edited

Loading

danielweck commented Jan 29, 2025 •

edited

Loading