diff --git a/integration_test/export_flow_test.dart b/integration_test/export_flow_test.dart
index 792a29d..ce72bb3 100644
--- a/integration_test/export_flow_test.dart
+++ b/integration_test/export_flow_test.dart
@@ -37,9 +37,12 @@ void main() {
             (ref) => PreferencesStateNotifier(prefs),
           ),
           documentRepositoryProvider.overrideWith(
-            (ref) =>
-                DocumentStateNotifier(service: ExportService())
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+            (ref) => DocumentStateNotifier(service: ExportService())
+              ..openDocument(
+                bytes: pdfBytes,
+                pageCount: 3,
+                knownPageCount: true,
+              ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -93,9 +96,12 @@ void main() {
             (ref) => PreferencesStateNotifier(prefs),
           ),
           documentRepositoryProvider.overrideWith(
-            (ref) =>
-                DocumentStateNotifier(service: ExportService())
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+            (ref) => DocumentStateNotifier(service: ExportService())
+              ..openDocument(
+                bytes: pdfBytes,
+                pageCount: 3,
+                knownPageCount: true,
+              ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -164,7 +170,11 @@ void main() {
           documentRepositoryProvider.overrideWith(
             (ref) => DocumentStateNotifier(
               service: ExportService(enableRaster: false),
-            )..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+            )..openDocument(
+              bytes: pdfBytes,
+              pageCount: 3,
+              knownPageCount: true,
+            ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -210,7 +220,11 @@ void main() {
           documentRepositoryProvider.overrideWith(
             (ref) => DocumentStateNotifier(
               service: ExportService(enableRaster: false),
-            )..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+            )..openDocument(
+              bytes: pdfBytes,
+              pageCount: 3,
+              knownPageCount: true,
+            ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -259,7 +273,11 @@ void main() {
           documentRepositoryProvider.overrideWith(
             (ref) => DocumentStateNotifier(
               service: ExportService(enableRaster: false),
-            )..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+            )..openDocument(
+              bytes: pdfBytes,
+              pageCount: 3,
+              knownPageCount: true,
+            ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -309,9 +327,12 @@ void main() {
             (ref) => PreferencesStateNotifier(prefs),
           ),
           documentRepositoryProvider.overrideWith(
-            (ref) =>
-                DocumentStateNotifier(service: ExportService())
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+            (ref) => DocumentStateNotifier(service: ExportService())
+              ..openDocument(
+                bytes: pdfBytes,
+                pageCount: 3,
+                knownPageCount: true,
+              ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -361,9 +382,12 @@ void main() {
               (ref) => PreferencesStateNotifier(prefs),
             ),
             documentRepositoryProvider.overrideWith(
-              (ref) =>
-                  DocumentStateNotifier(service: ExportService())
-                    ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+              (ref) => DocumentStateNotifier(service: ExportService())
+                ..openDocument(
+                  bytes: pdfBytes,
+                  pageCount: 3,
+                  knownPageCount: true,
+                ),
             ),
             pdfViewModelProvider.overrideWith(
               (ref) => PdfViewModel(ref, useMockViewer: false),
diff --git a/integration_test/pdf_view_test.dart b/integration_test/pdf_view_test.dart
index 15a78fc..349842e 100644
--- a/integration_test/pdf_view_test.dart
+++ b/integration_test/pdf_view_test.dart
@@ -33,8 +33,11 @@ void main() {
           ),
           documentRepositoryProvider.overrideWith(
             (ref) =>
-                DocumentStateNotifier()
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+                DocumentStateNotifier()..openDocument(
+                  bytes: pdfBytes,
+                  pageCount: 3,
+                  knownPageCount: true,
+                ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -104,8 +107,11 @@ void main() {
           ),
           documentRepositoryProvider.overrideWith(
             (ref) =>
-                DocumentStateNotifier()
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+                DocumentStateNotifier()..openDocument(
+                  bytes: pdfBytes,
+                  pageCount: 3,
+                  knownPageCount: true,
+                ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -158,8 +164,11 @@ void main() {
           ),
           documentRepositoryProvider.overrideWith(
             (ref) =>
-                DocumentStateNotifier()
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+                DocumentStateNotifier()..openDocument(
+                  bytes: pdfBytes,
+                  pageCount: 3,
+                  knownPageCount: true,
+                ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -245,8 +254,11 @@ void main() {
           ),
           documentRepositoryProvider.overrideWith(
             (ref) =>
-                DocumentStateNotifier()
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+                DocumentStateNotifier()..openDocument(
+                  bytes: pdfBytes,
+                  pageCount: 3,
+                  knownPageCount: true,
+                ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -311,8 +323,11 @@ void main() {
           ),
           documentRepositoryProvider.overrideWith(
             (ref) =>
-                DocumentStateNotifier()
-                  ..openPickedWithPageCount(pageCount: 3, bytes: pdfBytes),
+                DocumentStateNotifier()..openDocument(
+                  bytes: pdfBytes,
+                  pageCount: 3,
+                  knownPageCount: true,
+                ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
@@ -377,7 +392,7 @@ void main() {
     Future<void> simulatePick() async {
       container
           .read(documentRepositoryProvider.notifier)
-          .openPicked(bytes: newBytes);
+          .openDocument(bytes: newBytes);
       // Reset the current page explicitly to 1 as openPicked establishes new doc
       container.read(pdfViewModelProvider.notifier).jumpToPage(1);
     }
@@ -391,8 +406,11 @@ void main() {
           ),
           documentRepositoryProvider.overrideWith(
             (ref) =>
-                DocumentStateNotifier()
-                  ..openPickedWithPageCount(pageCount: 3, bytes: initialBytes),
+                DocumentStateNotifier()..openDocument(
+                  bytes: initialBytes,
+                  pageCount: 3,
+                  knownPageCount: true,
+                ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: false),
diff --git a/lib/data/repositories/document_repository.dart b/lib/data/repositories/document_repository.dart
index 7df5593..ae69d39 100644
--- a/lib/data/repositories/document_repository.dart
+++ b/lib/data/repositories/document_repository.dart
@@ -25,25 +25,56 @@ class DocumentStateNotifier extends StateNotifier<Document> {
     );
   }
 
-  void openPicked({Uint8List? bytes}) {
+  /// Unified open API replacing multiple legacy variants.
+  ///
+  /// Usage patterns:
+  ///  openDocument(bytes: data) -> derive page count asynchronously.
+  ///  openDocument(bytes: data, pageCount: 203, knownPageCount: true) -> fast path.
+  ///  openDocument(pageCount: 5) -> open empty placeholder document (tests).
+  void openDocument({
+    Uint8List? bytes,
+    int? pageCount,
+    bool knownPageCount = false,
+  }) {
     debugPrint(
-      '[DocumentRepository] openPicked called (bytes length: ${bytes?.length})',
+      '[DocumentRepository] openDocument called (bytes=${bytes?.length} pageCount=$pageCount known=$knownPageCount)',
     );
-
-    // For real usage, determine page count from PDF bytes asynchronously
-    if (bytes != null) {
-      _openPickedAsync(bytes);
-    } else {
-      // Handle null bytes case
+    if (bytes == null) {
+      // No bytes: treat as synthetic document (tests) using provided pageCount or default 1
+      final pc = pageCount ?? 1;
       state = state.copyWith(
         loaded: true,
-        pageCount: 1,
+        pageCount: pc,
+        pickedPdfBytes: null,
+        placementsByPage: <int, List<SignaturePlacement>>{},
+      );
+      return;
+    }
+    // Bytes provided
+    if ((knownPageCount || pageCount != null) && pageCount != null) {
+      // Fast path: caller already determined count
+      state = state.copyWith(
+        loaded: true,
+        pageCount: pageCount.clamp(1, 9999),
         pickedPdfBytes: bytes,
         placementsByPage: <int, List<SignaturePlacement>>{},
       );
+      return;
     }
+    // Derive asynchronously
+    _openPickedAsync(bytes);
   }
 
+  // --- Deprecated wrappers for backward compatibility (can be removed later) ---
+  @Deprecated('Use openDocument(bytes: ...) instead')
+  void openPicked({Uint8List? bytes}) => openDocument(bytes: bytes);
+
+  @Deprecated(
+    'Use openDocument(bytes: ..., pageCount: x, knownPageCount: true) instead',
+  )
+  void openPickedKnown({required int pageCount, required Uint8List bytes}) =>
+      openDocument(bytes: bytes, pageCount: pageCount, knownPageCount: true);
+
   Future<void> _openPickedAsync(Uint8List bytes) async {
     int pageCount = 1; // default fallback
 
@@ -63,30 +94,15 @@ class DocumentStateNotifier extends StateNotifier<Document> {
       pickedPdfBytes: bytes,
       placementsByPage: <int, List<SignaturePlacement>>{},
     );
-
-    // Schedule delayed check to ensure our page count wasn't overridden by UI callbacks
-    Future.delayed(const Duration(milliseconds: 100), () {
-      if (state.loaded &&
-          state.pickedPdfBytes == bytes &&
-          state.pageCount != pageCount) {
-        state = state.copyWith(pageCount: pageCount);
-      }
-    });
   }
 
   // For tests that need to specify page count explicitly
   @visibleForTesting
-  void openPickedWithPageCount({required int pageCount, Uint8List? bytes}) {
-    debugPrint(
-      '[DocumentRepository] openPickedWithPageCount called (pageCount=$pageCount)',
-    );
-    state = state.copyWith(
-      loaded: true,
-      pageCount: pageCount,
-      pickedPdfBytes: bytes,
-      placementsByPage: <int, List<SignaturePlacement>>{},
-    );
-  }
+  @Deprecated(
+    'Use openDocument(pageCount: x) for synthetic docs or with bytes+knownPageCount',
+  )
+  void openPickedWithPageCount({required int pageCount, Uint8List? bytes}) =>
+      openDocument(bytes: bytes, pageCount: pageCount, knownPageCount: true);
 
   void close() {
     state = Document.initial();
@@ -133,21 +149,12 @@ class DocumentStateNotifier extends StateNotifier<Document> {
   // signature bytes were provided.
   static final img.Image _singleTransparentPng = img.Image(width: 1, height: 1);
 
+  @Deprecated('Use modifyPlacement')
   void updatePlacementRotation({
     required int page,
     required int index,
     required double rotationDeg,
-  }) {
-    if (!state.loaded) return;
-    final p = page.clamp(1, state.pageCount);
-    final map = Map<int, List<SignaturePlacement>>.from(state.placementsByPage);
-    final list = List<SignaturePlacement>.from(map[p] ?? const []);
-    if (index >= 0 && index < list.length) {
-      list[index] = list[index].copyWith(rotationDeg: rotationDeg);
-      map[p] = list;
-      state = state.copyWith(placementsByPage: map);
-    }
-  }
+  }) => modifyPlacement(page: page, index: index, rotationDeg: rotationDeg);
 
   void removePlacement({required int page, required int index}) {
     if (!state.loaded) return;
@@ -166,21 +173,36 @@ class DocumentStateNotifier extends StateNotifier<Document> {
   }
 
   // Update the rect of an existing placement on a page.
+  @Deprecated('Use modifyPlacement')
   void updatePlacementRect({
     required int page,
     required int index,
     required Rect rect,
+  }) => modifyPlacement(page: page, index: index, rect: rect);
+
+  /// Generic partial update for a placement. Any non-null field is applied.
+  void modifyPlacement({
+    required int page,
+    required int index,
+    Rect? rect,
+    double? rotationDeg,
+    SignatureAsset? asset,
+    GraphicAdjust? graphicAdjust,
   }) {
     if (!state.loaded) return;
     final p = page.clamp(1, state.pageCount);
     final map = Map<int, List<SignaturePlacement>>.from(state.placementsByPage);
     final list = List<SignaturePlacement>.from(map[p] ?? const []);
-    if (index >= 0 && index < list.length) {
-      final existing = list[index];
-      list[index] = existing.copyWith(rect: rect);
-      map[p] = list;
-      state = state.copyWith(placementsByPage: map);
-    }
+    if (index < 0 || index >= list.length) return;
+    final current = list[index];
+    list[index] = current.copyWith(
+      rect: rect ?? current.rect,
+      rotationDeg: rotationDeg ?? current.rotationDeg,
+      asset: asset ?? current.asset,
+      graphicAdjust: graphicAdjust ?? current.graphicAdjust,
+    );
+    map[p] = list;
+    state = state.copyWith(placementsByPage: map);
   }
 
   List<SignaturePlacement> placementsOn(int page) {
diff --git a/lib/ui/features/pdf/view_model/pdf_view_model.dart b/lib/ui/features/pdf/view_model/pdf_view_model.dart
index 2bbcbd8..c0c58fc 100644
--- a/lib/ui/features/pdf/view_model/pdf_view_model.dart
+++ b/lib/ui/features/pdf/view_model/pdf_view_model.dart
@@ -138,11 +138,7 @@ class PdfViewModel extends ChangeNotifier {
   }) {
     ref
         .read(documentRepositoryProvider.notifier)
-        .updatePlacementRotation(
-          page: page,
-          index: index,
-          rotationDeg: rotationDeg,
-        );
+        .modifyPlacement(page: page, index: index, rotationDeg: rotationDeg);
   }
 
   void removePlacement({required int page, required int index}) {
@@ -163,7 +159,7 @@ class PdfViewModel extends ChangeNotifier {
   }) {
     ref
         .read(documentRepositoryProvider.notifier)
-        .updatePlacementRect(page: page, index: index, rect: rect);
+        .modifyPlacement(page: page, index: index, rect: rect);
   }
 
   List<SignaturePlacement> placementsOn(int page) {
@@ -343,6 +339,16 @@ class PdfSessionViewModel extends ChangeNotifier {
       debugPrint(
         '[PdfSessionViewModel] Opened PDF bytes length=${bytes.length} pages=$pageCount',
       );
+      // Use fast path to populate repository BEFORE navigation so the first
+      // build of PdfViewerWidget sees a loaded document and avoids showing
+      // transient "No PDF loaded".
+      ref
+          .read(documentRepositoryProvider.notifier)
+          .openDocument(
+            bytes: bytes,
+            pageCount: pageCount,
+            knownPageCount: true,
+          );
     } catch (e, st) {
       debugPrint(
         '[PdfSessionViewModel] Failed to read PDF data from bytes error=$e',
@@ -379,8 +385,13 @@ class PdfSessionViewModel extends ChangeNotifier {
     } else {
       _displayFileName = '';
     }
-    debugPrint('[PdfSessionViewModel] Calling openPicked with bytes');
-    ref.read(documentRepositoryProvider.notifier).openPicked(bytes: bytes);
+    // If fast path failed to set repository (e.g., exception earlier), fallback to async derive.
+    if (ref.read(documentRepositoryProvider).pickedPdfBytes != bytes) {
+      debugPrint(
+        '[PdfSessionViewModel] Fallback deriving page count via openDocument',
+      );
+      ref.read(documentRepositoryProvider.notifier).openDocument(bytes: bytes);
+    }
     // Keep existing signature cards when opening a new document.
     // The feature "Open a different document will reset signature placements but keep signature cards"
     // relies on this behavior. Placements are reset by openPicked() above.
diff --git a/test/features/step/a_document_is_open_and_contains_at_least_one_signature_placement.dart b/test/features/step/a_document_is_open_and_contains_at_least_one_signature_placement.dart
index 6093b94..bc2ec28 100644
--- a/test/features/step/a_document_is_open_and_contains_at_least_one_signature_placement.dart
+++ b/test/features/step/a_document_is_open_and_contains_at_least_one_signature_placement.dart
@@ -12,7 +12,9 @@ Future<void> aDocumentIsOpenAndContainsAtLeastOneSignaturePlacement(
 ) async {
   final container = TestWorld.container ?? ProviderContainer();
   TestWorld.container = container;
-  container.read(documentRepositoryProvider.notifier).openPickedWithPageCount(pageCount: 5);
+  container
+      .read(documentRepositoryProvider.notifier)
+      .openDocument(pageCount: 5);
   container
       .read(documentRepositoryProvider.notifier)
       .addPlacement(
diff --git a/test/features/step/a_document_is_open_and_contains_multiple_placed_signature_placements_across_pages.dart b/test/features/step/a_document_is_open_and_contains_multiple_placed_signature_placements_across_pages.dart
index 86cc001..bf90a56 100644
--- a/test/features/step/a_document_is_open_and_contains_multiple_placed_signature_placements_across_pages.dart
+++ b/test/features/step/a_document_is_open_and_contains_multiple_placed_signature_placements_across_pages.dart
@@ -13,7 +13,9 @@ aDocumentIsOpenAndContainsMultiplePlacedSignaturePlacementsAcrossPages(
 ) async {
   final container = TestWorld.container ?? ProviderContainer();
   TestWorld.container = container;
-  container.read(documentRepositoryProvider.notifier).openPickedWithPageCount(pageCount: 5);
+  container
+      .read(documentRepositoryProvider.notifier)
+      .openDocument(pageCount: 5);
   container
       .read(documentRepositoryProvider.notifier)
       .addPlacement(
diff --git a/test/features/step/a_document_is_open_with_no_signature_placements_placed.dart b/test/features/step/a_document_is_open_with_no_signature_placements_placed.dart
index 5052e00..56f85a1 100644
--- a/test/features/step/a_document_is_open_with_no_signature_placements_placed.dart
+++ b/test/features/step/a_document_is_open_with_no_signature_placements_placed.dart
@@ -11,6 +11,6 @@ Future<void> aDocumentIsOpenWithNoSignaturePlacementsPlaced(
   TestWorld.container = container;
   container
       .read(documentRepositoryProvider.notifier)
-      .openPickedWithPageCount(pageCount: 5);
+      .openDocument(pageCount: 5);
   // No placements added
 }
diff --git a/test/features/step/a_document_page_is_selected_for_signing.dart b/test/features/step/a_document_page_is_selected_for_signing.dart
index 77485a9..ac11663 100644
--- a/test/features/step/a_document_page_is_selected_for_signing.dart
+++ b/test/features/step/a_document_page_is_selected_for_signing.dart
@@ -11,7 +11,7 @@ Future<void> aDocumentPageIsSelectedForSigning(WidgetTester tester) async {
   // Ensure a document is open
   final repo = container.read(documentRepositoryProvider.notifier);
   if (!container.read(documentRepositoryProvider).loaded) {
-    repo.openPickedWithPageCount(pageCount: 5);
+    repo.openDocument(pageCount: 5);
   }
   // Ensure current page is 1 for consistent subsequent steps
   try {
diff --git a/test/features/step/a_multipage_document_is_open.dart b/test/features/step/a_multipage_document_is_open.dart
index f3201ef..940642e 100644
--- a/test/features/step/a_multipage_document_is_open.dart
+++ b/test/features/step/a_multipage_document_is_open.dart
@@ -18,7 +18,9 @@ Future<void> aMultipageDocumentIsOpen(WidgetTester tester) async {
   container.read(signatureCardRepositoryProvider.notifier).state = [
     SignatureCard.initial(),
   ];
-  container.read(documentRepositoryProvider.notifier).openPickedWithPageCount(pageCount: 5);
+  container
+      .read(documentRepositoryProvider.notifier)
+      .openDocument(pageCount: 5);
   // Reset page state providers
   try {
     container.read(pdfViewModelProvider.notifier).jumpToPage(1);
diff --git a/test/features/step/a_sample_multipage_document5_pages_is_available.dart b/test/features/step/a_sample_multipage_document5_pages_is_available.dart
index 54ec731..2a805ec 100644
--- a/test/features/step/a_sample_multipage_document5_pages_is_available.dart
+++ b/test/features/step/a_sample_multipage_document5_pages_is_available.dart
@@ -11,5 +11,5 @@ Future<void> aSampleMultipageDocument5PagesIsAvailable(
   TestWorld.container = container;
   container
       .read(documentRepositoryProvider.notifier)
-      .openPickedWithPageCount(pageCount: 5);
+      .openDocument(pageCount: 5);
 }
diff --git a/test/features/step/a_signature_asset_is_placed_on_the_page.dart b/test/features/step/a_signature_asset_is_placed_on_the_page.dart
index f118576..b1e6133 100644
--- a/test/features/step/a_signature_asset_is_placed_on_the_page.dart
+++ b/test/features/step/a_signature_asset_is_placed_on_the_page.dart
@@ -17,7 +17,7 @@ Future<void> aSignatureAssetIsPlacedOnThePage(WidgetTester tester) async {
   if (!container.read(documentRepositoryProvider).loaded) {
     container
         .read(documentRepositoryProvider.notifier)
-        .openPickedWithPageCount(pageCount: 5);
+        .openDocument(pageCount: 5);
   }
 
   // Get or create an asset
diff --git a/test/features/step/a_signature_placement_is_placed_on_page.dart b/test/features/step/a_signature_placement_is_placed_on_page.dart
index 1e42487..eb17525 100644
--- a/test/features/step/a_signature_placement_is_placed_on_page.dart
+++ b/test/features/step/a_signature_placement_is_placed_on_page.dart
@@ -17,7 +17,7 @@ Future<void> aSignaturePlacementIsPlacedOnPage(
   if (!container.read(documentRepositoryProvider).loaded) {
     container
         .read(documentRepositoryProvider.notifier)
-        .openPickedWithPageCount(pageCount: 5);
+        .openDocument(pageCount: 5);
   }
   final page = param1.toInt();
   container
diff --git a/test/features/step/a_signature_placement_is_placed_with_a_position_and_size_relative_to_the_page.dart b/test/features/step/a_signature_placement_is_placed_with_a_position_and_size_relative_to_the_page.dart
index b3ec08f..229b2af 100644
--- a/test/features/step/a_signature_placement_is_placed_with_a_position_and_size_relative_to_the_page.dart
+++ b/test/features/step/a_signature_placement_is_placed_with_a_position_and_size_relative_to_the_page.dart
@@ -16,7 +16,7 @@ Future<void> aSignaturePlacementIsPlacedWithAPositionAndSizeRelativeToThePage(
   if (!container.read(documentRepositoryProvider).loaded) {
     container
         .read(documentRepositoryProvider.notifier)
-        .openPickedWithPageCount(pageCount: 5);
+        .openDocument(pageCount: 5);
   }
   final currentPage = container.read(pdfViewModelProvider).currentPage;
   container
diff --git a/test/features/step/dragging_or_resizing_one_does_not_change_the_other.dart b/test/features/step/dragging_or_resizing_one_does_not_change_the_other.dart
index 8c62876..621991f 100644
--- a/test/features/step/dragging_or_resizing_one_does_not_change_the_other.dart
+++ b/test/features/step/dragging_or_resizing_one_does_not_change_the_other.dart
@@ -22,7 +22,7 @@ Future<void> draggingOrResizingOneDoesNotChangeTheOther(
   final changedFirst = firstRectBefore.inflate(5);
   container
       .read(documentRepositoryProvider.notifier)
-      .updatePlacementRect(page: page, index: 0, rect: changedFirst);
+      .modifyPlacement(page: page, index: 0, rect: changedFirst);
 
   final after = container
       .read(documentRepositoryProvider.notifier)
diff --git a/test/features/step/the_user_drags_handles_to_resize_and_drags_to_reposition.dart b/test/features/step/the_user_drags_handles_to_resize_and_drags_to_reposition.dart
index 5f4c1bb..d2fdb2b 100644
--- a/test/features/step/the_user_drags_handles_to_resize_and_drags_to_reposition.dart
+++ b/test/features/step/the_user_drags_handles_to_resize_and_drags_to_reposition.dart
@@ -26,6 +26,6 @@ Future<void> theUserDragsHandlesToResizeAndDragsToReposition(
       height: currentRect.height + 30,
     );
 
-    pdfN.updatePlacementRect(page: currentPage, index: 0, rect: newRect);
+    pdfN.modifyPlacement(page: currentPage, index: 0, rect: newRect);
   }
 }
diff --git a/test/features/step/the_user_drags_it_on_the_page_of_the_document_to_place_signature_placements_in_multiple_locations_in_the_document.dart b/test/features/step/the_user_drags_it_on_the_page_of_the_document_to_place_signature_placements_in_multiple_locations_in_the_document.dart
index c0c49e4..afe5b65 100644
--- a/test/features/step/the_user_drags_it_on_the_page_of_the_document_to_place_signature_placements_in_multiple_locations_in_the_document.dart
+++ b/test/features/step/the_user_drags_it_on_the_page_of_the_document_to_place_signature_placements_in_multiple_locations_in_the_document.dart
@@ -25,7 +25,7 @@ theUserDragsItOnThePageOfTheDocumentToPlaceSignaturePlacementsInMultipleLocation
   if (!container.read(documentRepositoryProvider).loaded) {
     container
         .read(documentRepositoryProvider.notifier)
-        .openPickedWithPageCount(pageCount: 5);
+        .openDocument(pageCount: 5);
   }
 
   container
diff --git a/test/features/step/the_user_drags_this_signature_card_on_the_page_of_the_document_to_place_a_signature_placement.dart b/test/features/step/the_user_drags_this_signature_card_on_the_page_of_the_document_to_place_a_signature_placement.dart
index 83179aa..5fa11bc 100644
--- a/test/features/step/the_user_drags_this_signature_card_on_the_page_of_the_document_to_place_a_signature_placement.dart
+++ b/test/features/step/the_user_drags_this_signature_card_on_the_page_of_the_document_to_place_a_signature_placement.dart
@@ -21,7 +21,7 @@ theUserDragsThisSignatureCardOnThePageOfTheDocumentToPlaceASignaturePlacement(
   if (!container.read(documentRepositoryProvider).loaded) {
     container
         .read(documentRepositoryProvider.notifier)
-        .openPickedWithPageCount(pageCount: 5);
+        .openDocument(pageCount: 5);
   }
 
   // Get or create an asset
diff --git a/test/features/step/the_user_opens_a_different_document_with_pages.dart b/test/features/step/the_user_opens_a_different_document_with_pages.dart
index 3f62744..1c5e752 100644
--- a/test/features/step/the_user_opens_a_different_document_with_pages.dart
+++ b/test/features/step/the_user_opens_a_different_document_with_pages.dart
@@ -19,7 +19,7 @@ Future<void> theUserOpensADifferentDocumentWithPages(
   // Simulate "open a different document": reset placements and set page count.
   container
       .read(documentRepositoryProvider.notifier)
-      .openPickedWithPageCount(pageCount: pageCount);
+      .openDocument(pageCount: pageCount);
   // Ensure there are 2 signature cards available as per scenario.
   final cards = container.read(signatureCardRepositoryProvider);
   if (cards.length < 2) {
diff --git a/test/features/step/the_user_places_it_in_multiple_locations_in_the_document.dart b/test/features/step/the_user_places_it_in_multiple_locations_in_the_document.dart
index b2e5612..f3468ca 100644
--- a/test/features/step/the_user_places_it_in_multiple_locations_in_the_document.dart
+++ b/test/features/step/the_user_places_it_in_multiple_locations_in_the_document.dart
@@ -12,7 +12,7 @@ Future<void> theUserPlacesItInMultipleLocationsInTheDocument(
   TestWorld.container = container;
   final notifier = container.read(documentRepositoryProvider.notifier);
   // Always open a fresh doc to avoid state bleed between scenarios
-  notifier.openPickedWithPageCount(pageCount: 6);
+  notifier.openDocument(pageCount: 6);
   // Place two on page 2 and one on page 4
   notifier.addPlacement(page: 2, rect: const Rect.fromLTWH(10, 10, 80, 40));
   notifier.addPlacement(page: 2, rect: const Rect.fromLTWH(120, 50, 80, 40));
diff --git a/test/features/step/the_user_savesexports_the_document.dart b/test/features/step/the_user_savesexports_the_document.dart
index e7d52fa..dfe485d 100644
--- a/test/features/step/the_user_savesexports_the_document.dart
+++ b/test/features/step/the_user_savesexports_the_document.dart
@@ -17,7 +17,7 @@ Future<void> theUserSavesexportsTheDocument(WidgetTester tester) async {
     // Load a minimal sample so the expectation passes in logic-only tests
     container
         .read(documentRepositoryProvider.notifier)
-        .openPickedWithPageCount(pageCount: 2, bytes: Uint8List(10));
+        .openDocument(bytes: Uint8List(10), pageCount: 2, knownPageCount: true);
   }
   expect(pdf.loaded, isTrue, reason: 'PDF must be loaded before export');
   // Check if there are placements
diff --git a/test/features/step/the_user_selects.dart b/test/features/step/the_user_selects.dart
index 2a361f7..76d561c 100644
--- a/test/features/step/the_user_selects.dart
+++ b/test/features/step/the_user_selects.dart
@@ -10,7 +10,9 @@ Future<void> theUserSelects(WidgetTester tester, dynamic file) async {
   final container = ProviderContainer();
   TestWorld.container = container;
   // Mark page for signing to enable signature ops
-  container.read(documentRepositoryProvider.notifier).openPickedWithPageCount(pageCount: 1);
+  container
+      .read(documentRepositoryProvider.notifier)
+      .openDocument(pageCount: 1);
   // For invalid/unsupported/empty selections we do NOT set image bytes.
   // This simulates a failed load and keeps rect null.
   final token = file.toString();
diff --git a/test/features/step/the_user_uses_rotate_controls.dart b/test/features/step/the_user_uses_rotate_controls.dart
index 1ed82e1..d8bc451 100644
--- a/test/features/step/the_user_uses_rotate_controls.dart
+++ b/test/features/step/the_user_uses_rotate_controls.dart
@@ -11,10 +11,6 @@ Future<void> theUserUsesRotateControls(WidgetTester tester) async {
   final currentPage = container.read(pdfViewModelProvider).currentPage;
   final placements = pdfN.placementsOn(currentPage);
   if (placements.isNotEmpty) {
-    pdfN.updatePlacementRotation(
-      page: currentPage,
-      index: 0,
-      rotationDeg: 45.0,
-    );
+    pdfN.modifyPlacement(page: currentPage, index: 0, rotationDeg: 45.0);
   }
 }
diff --git a/test/features/step/three_signature_placements_are_placed_on_the_current_page.dart b/test/features/step/three_signature_placements_are_placed_on_the_current_page.dart
index 0797cbf..e20039d 100644
--- a/test/features/step/three_signature_placements_are_placed_on_the_current_page.dart
+++ b/test/features/step/three_signature_placements_are_placed_on_the_current_page.dart
@@ -22,7 +22,9 @@ Future<void> threeSignaturePlacementsArePlacedOnTheCurrentPage(
   container.read(signatureCardRepositoryProvider.notifier).state = [
     SignatureCard.initial(),
   ];
-  container.read(documentRepositoryProvider.notifier).openPickedWithPageCount(pageCount: 5);
+  container
+      .read(documentRepositoryProvider.notifier)
+      .openDocument(pageCount: 5);
   final pdfN = container.read(documentRepositoryProvider.notifier);
   final page = container.read(pdfViewModelProvider).currentPage;
   pdfN.addPlacement(
diff --git a/test/widget/export_flow_test.dart b/test/widget/export_flow_test.dart
index 4cafb36..5b858d1 100644
--- a/test/widget/export_flow_test.dart
+++ b/test/widget/export_flow_test.dart
@@ -48,8 +48,11 @@ void main() {
           ),
           documentRepositoryProvider.overrideWith(
             (ref) =>
-                DocumentStateNotifier()
-                  ..openPickedWithPageCount(pageCount: 5, bytes: Uint8List(0)),
+                DocumentStateNotifier()..openDocument(
+                  bytes: Uint8List(0),
+                  pageCount: 5,
+                  knownPageCount: true,
+                ),
           ),
           pdfViewModelProvider.overrideWith(
             (ref) => PdfViewModel(ref, useMockViewer: true),
diff --git a/test/widget/welcome_drop_test.dart b/test/widget/welcome_drop_test.dart
index fcf1136..907b167 100644
--- a/test/widget/welcome_drop_test.dart
+++ b/test/widget/welcome_drop_test.dart
@@ -51,7 +51,7 @@ void main() {
     }) async {
       final container = ProviderScope.containerOf(stateful.context);
       final repo = container.read(documentRepositoryProvider.notifier);
-      repo.openPickedWithPageCount(pageCount: 1, bytes: bytes);
+      repo.openDocument(bytes: bytes, pageCount: 1, knownPageCount: true);
     }, [fake]);
     await tester.pump();