chore(deps): update dependency vue to v3.5.42

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

.github/workflows/build-test.yml

@@ -0,0 +1,42 @@
+name: Build Test
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install Server
+        uses: ./action-server-install
+        with:
+          install-php: 'false'
+          install-node: 'true'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+
+      - name: Checkout Pull Request
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: server/modules/documents_manager
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: server/modules/documents_manager
+
+      - name: Build
+        run: npm run build
+        working-directory: server/modules/documents_manager

.github/workflows/js-unit-tests.yml

@@ -0,0 +1,42 @@
+name: JS Unit Tests
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install Server
+        uses: ./action-server-install
+        with:
+          install-php: 'false'
+          install-node: 'true'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+
+      - name: Checkout Pull Request
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: server/modules/documents_manager
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: server/modules/documents_manager
+
+      - name: Run tests
+        run: npm run test:unit
+        working-directory: server/modules/documents_manager

.github/workflows/php-integration-tests.yml

@@ -0,0 +1,59 @@
+name: PHP Integration Tests
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    services:
+      mongo:
+        image: mongo:8
+        options: >-
+          --health-cmd "mongosh --quiet --eval \"db.adminCommand('ping')\""
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install server
+        uses: ./action-server-install
+        with:
+          install-php: 'true'
+          php-version: '8.5'
+          server-path: './server'
+          database-uri: 'mongodb://mongo:27017/?tls=false'
+          database-name: 'ktrix_ci'
+          app-environment: 'test'
+
+      - name: Checkout module under test
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          path: server/modules/documents_manager
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install module dependencies
+        run: composer install --prefer-dist --no-progress
+        working-directory: server/modules/documents_manager
+
+      - name: Install and enable module
+        working-directory: server
+        run: |
+          php bin/console module:install documents_manager
+          php bin/console module:enable documents_manager
+
+      - name: Run integration tests
+        working-directory: server/modules/documents_manager
+        run: composer test:integration

.github/workflows/php-unit-tests.yml

@@ -0,0 +1,42 @@
+name: PHP Unit Tests
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install Server
+        uses: ./action-server-install
+        with:
+          install-php: 'true'
+          install-node: 'false'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+
+      - name: Checkout Pull Request
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: server/modules/documents_manager
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress
+        working-directory: server/modules/documents_manager
+
+      - name: Run tests
+        run: composer test:unit
+        working-directory: server/modules/documents_manager

.github/workflows/renovate.yml

@@ -25,11 +25,17 @@ jobs:
           tools: composer:v2
 
       - name: Install Renovate
-        run: npm install -g renovate
+        run: |
+          npm install --global --no-audit --fund=false \
+            --prefix "${{ runner.temp }}/renovate-npm" \
+            --cache "${{ runner.temp }}/renovate-npm-cache" \
+            renovate
+          "${{ runner.temp }}/renovate-npm/bin/renovate" --version
 
       - name: Run Renovate
         env:
           RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}
           RENOVATE_PLATFORM: gitea
           RENOVATE_ENDPOINT: https://git.ktrix.dev/api/v1
-        run: renovate ${{ gitea.repository }}
+        run: |
+          "${{ runner.temp }}/renovate-npm/bin/renovate" ${{ gitea.repository }}

.gitignore

@@ -12,12 +12,10 @@ node_modules/
 /static/
 
 # Backend development
+/vendor/
 /lib/vendor/
 coverage/
-phpunit.xml.cache
+*.cache
-.phpunit.result.cache
-.php-cs-fixer.cache
-.phpstan.cache
 .phpactor/
 
 # Editors

composer.json

@@ -10,17 +10,29 @@
   "config": {
     "optimize-autoloader": true,
     "platform": {
-      "php": "8.2"
+      "php": "8.3"
     },
     "autoloader-suffix": "DocumentsManager",
     "vendor-dir": "lib/vendor"
   },
   "require": {
-    "php": ">=8.2 <=8.5"
+    "php": ">=8.3 <=8.5"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^12.0"
   },
   "autoload": {
     "psr-4": {
       "KTXM\\DocumentsManager\\": "lib/"
     }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "KTXT\\DocumentsManager\\Tests\\": "tests/php/"
+    }
+  },
+  "scripts": {
+    "test:unit": "phpunit --configuration tests/php/phpunit.xml --testsuite \"Unit Tests\" --colors=always --testdox",
+    "test:integration": "phpunit --configuration tests/php/phpunit.xml --testsuite \"Integration Tests\" --colors=always --testdox"
   }
 }

lib/Controllers/TransferController.php

@@ -12,9 +12,14 @@ namespace KTXM\DocumentsManager\Controllers;
 use KTXC\Http\Response\JsonResponse;
 use KTXC\Http\Response\Response;
 use KTXC\Http\Response\StreamedResponse;
-use KTXC\SessionIdentity;
+use KTXC\Context\IdentityContextInterface;
-use KTXC\SessionTenant;
+use KTXC\Context\TenantContextInterface;
 use KTXF\Controller\ControllerAbstract;
+use KTXF\Documents\Collection\CollectionBaseInterface;
+use KTXF\Documents\Entity\EntityBaseInterface;
+use KTXF\Resource\Identifier\CollectionIdentifier;
+use KTXF\Resource\Identifier\EntityIdentifier;
+use KTXF\Resource\Identifier\ResourceIdentifiers;
 use KTXF\Routing\Attributes\AuthenticatedRoute;
 use KTXM\DocumentsManager\Manager;
 use KTXM\DocumentsManager\Transfer\StreamingZip;
@@ -34,8 +39,8 @@ use Throwable;
 class TransferController extends ControllerAbstract
 {
     public function __construct(
-        private readonly SessionTenant $tenantIdentity,
+        private readonly TenantContextInterface $tenantContext,
-        private readonly SessionIdentity $userIdentity,
+        private readonly IdentityContextInterface $identityContext,
         private readonly Manager $manager,
         private readonly LoggerInterface $logger
     ) {}
@@ -45,44 +50,29 @@ class TransferController extends ControllerAbstract
      *
      * GET /download/entity/{provider}/{service}/{collection}/{identifier}
      */
-    #[AuthenticatedRoute(
+    #[AuthenticatedRoute('/download/entity/{provider}/{service}/{collection}/{identifier}', name: 'document_manager.download.entity', methods: ['GET'])]
-        '/download/entity/{provider}/{service}/{collection}/{identifier}',
-        name: 'document_manager.download.entity',
-        methods: ['GET']
-    )]
     public function downloadEntity(string $provider, string $service, string $collection, string $identifier): Response {
-        $tenantId = $this->tenantIdentity->identifier();
+        $tenantId = $this->tenantContext->identifier();
-        $userId = $this->userIdentity->identifier();
+        $userId = $this->identityContext->identifier();
 
         try {
-            // Fetch entity metadata
+            $target = new EntityIdentifier($provider, $service, $collection, $identifier);
-            $entities = $this->manager->entityFetch(
-                $tenantId,
-                $userId,
-                $provider,
-                $service,
-                $collection,
-                [$identifier]
-            );
 
-            if (empty($entities) || !isset($entities[$identifier])) {
+            // Fetch entity metadata
+            /** @var EntityBaseInterface[] $entities */
+            $entities = $this->manager->entityFetchBulk($tenantId, $userId, $target);
+
+            if (!isset($entities[(string) $target])) {
                 return new JsonResponse([
                     'status' => 'error',
                     'error' => ['code' => 404, 'message' => 'File not found']
                 ], Response::HTTP_NOT_FOUND);
             }
 
-            $entity = $entities[$identifier];
+            $entity = $entities[(string) $target];
 
             // Get the stream
-            $stream = $this->manager->entityReadStream(
+            $stream = $this->manager->entityReadStream($tenantId, $userId, $target);
-                $tenantId,
-                $userId,
-                $provider,
-                $service,
-                $collection,
-                $identifier
-            );
 
             if ($stream === null) {
                 return new JsonResponse([
@@ -130,19 +120,44 @@ class TransferController extends ControllerAbstract
         }
     }
 
+    #[AuthenticatedRoute('/preview/entity/{provider}/{service}/{collection}/{identifier}', name: 'document_manager.preview.entity', methods: ['GET'])]
+    public function previewEntity(string $provider, string $service, string $collection, string $identifier, string $variant = 'inline'): Response {
+        try {
+            $preview = $this->manager->entityPreview(
+                $this->tenantContext->identifier(),
+                $this->identityContext->identifier(),
+                new EntityIdentifier($provider, $service, $collection, $identifier),
+                $variant,
+            );
+            if ($preview === null) {
+                return new Response('', Response::HTTP_NO_CONTENT);
+            }
+
+            $response = new StreamedResponse($preview->resource->stream());
+            $response->headers->set('Content-Type', $preview->resource->mimeType());
+            $response->headers->set('Content-Length', (string) $preview->size);
+            $response->headers->set('ETag', '"' . trim($preview->etag, '"') . '"');
+            $response->headers->set('Cache-Control', 'private, max-age=3600');
+            $response->headers->set('X-Content-Type-Options', 'nosniff');
+            return $response;
+        } catch (Throwable $throwable) {
+            $this->logger->error('Document preview failed', ['exception' => $throwable]);
+            return new JsonResponse([
+                'status' => 'error',
+                'error' => ['code' => 500, 'message' => 'Preview unavailable'],
+            ], Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+    }
+
     /**
      * Download multiple files as a ZIP archive
      *
      * GET /download/archive?provider=...&service=...&ids[]=...&ids[]=...
      */
-    #[AuthenticatedRoute(
+    #[AuthenticatedRoute('/download/archive', name: 'manager.download.archive', methods: ['GET'])]
-        '/download/archive',
-        name: 'manager.download.archive',
-        methods: ['GET']
-    )]
     public function downloadArchive(string $provider, string $service, array $ids = [], ?string $collection = null, string $name = 'download'): Response {
-        $tenantId = $this->tenantIdentity->identifier();
+        $tenantId = $this->tenantContext->identifier();
-        $userId = $this->userIdentity->identifier();
+        $userId = $this->identityContext->identifier();
 
         if (empty($ids)) {
             return new JsonResponse([
@@ -179,10 +194,7 @@ class TransferController extends ControllerAbstract
                     $stream = $this->manager->entityReadStream(
                         $tenantId,
                         $userId,
-                        $provider,
+                        new EntityIdentifier($provider, $service, (string)$file['collection'], (string)$file['id'])
-                        $service,
-                        $file['collection'],
-                        $file['id']
                     );
 
                     if ($stream !== null) {
@@ -224,14 +236,10 @@ class TransferController extends ControllerAbstract
      *
      * GET /download/collection/{provider}/{service}/{identifier}
      */
-    #[AuthenticatedRoute(
+    #[AuthenticatedRoute('/download/collection/{provider}/{service}/{identifier}', name: 'manager.download.collection', methods: ['GET'])]
-        '/download/collection/{provider}/{service}/{identifier}',
-        name: 'manager.download.collection',
-        methods: ['GET']
-    )]
     public function downloadCollection(string $provider, string $service, string $identifier): Response {
-        $tenantId = $this->tenantIdentity->identifier();
+        $tenantId = $this->tenantContext->identifier();
-        $userId = $this->userIdentity->identifier();
+        $userId = $this->identityContext->identifier();
 
         try {
             // Fetch collection metadata
@@ -239,9 +247,7 @@ class TransferController extends ControllerAbstract
             $collection = $this->manager->collectionFetch(
                 $tenantId,
                 $userId,
-                $provider,
+                new CollectionIdentifier($provider, $service, $identifier)
-                $service,
-                $identifier
             );
 
             if ($collection === null) {
@@ -251,7 +257,7 @@ class TransferController extends ControllerAbstract
                 ], Response::HTTP_NOT_FOUND);
             }
 
-            $folderName = $collection->getLabel() ?? 'folder';
+            $folderName = $collection->getProperties()->getLabel() ?? 'folder';
             $archiveName = $this->sanitizeFilename($folderName) . '.zip';
 
             // Build recursive file list
@@ -275,10 +281,7 @@ class TransferController extends ControllerAbstract
                         $stream = $this->manager->entityReadStream(
                             $tenantId,
                             $userId,
-                            $provider,
+                            new EntityIdentifier($provider, $service, (string)$file['collection'], (string)$file['id'])
-                            $service,
-                            $file['collection'],
-                            $file['id']
                         );
 
                         if ($stream !== null) {
@@ -324,24 +327,22 @@ class TransferController extends ControllerAbstract
         foreach ($ids as $id) {
             // Try as entity first
             if ($collection !== null) {
+                $target = new EntityIdentifier($provider, $service, $collection, (string) $id);
                 /** @var EntityBaseInterface[] $entities */
-                $entities = $this->manager->entityFetch(
+                $entities = $this->manager->entityFetchBulk(
                     $tenantId,
                     $userId,
-                    $provider,
+                    $target
-                    $service,
-                    $collection,
-                    [$id]
                 );
 
-                if (!empty($entities) && isset($entities[$id])) {
+                if (isset($entities[(string) $target])) {
-                    $entity = $entities[$id];
+                    $entity = $entities[(string) $target];
                     $files[] = [
                         'type' => 'file',
                         'id' => $id,
                         'collection' => $collection,
-                        'path' => $entity->getLabel() ?? $id,
+                        'path' => $entity->getProperties()->getLabel() ?? $id,
-                        'modTime' => $entity->modifiedOn()?->getTimestamp(),
+                        'modTime' => $entity->modified()?->getTimestamp(),
                     ];
                     continue;
                 }
@@ -352,19 +353,17 @@ class TransferController extends ControllerAbstract
             $collectionNode = $this->manager->collectionFetch(
                 $tenantId,
                 $userId,
-                $provider,
+                new CollectionIdentifier($provider, $service, (string)$id)
-                $service,
-                $id
             );
 
             if ($collectionNode !== null) {
-                $folderName = $collectionNode->getLabel() ?? $id;
+                $folderName = $collectionNode->getProperties()->getLabel() ?? $id;
                 $subFiles = $this->resolveCollectionContents(
                     $tenantId,
                     $userId,
                     $provider,
                     $service,
-                    $id,
+                    (string)$id,
                     $folderName
                 );
                 $files = array_merge($files, $subFiles);
@@ -407,17 +406,13 @@ class TransferController extends ControllerAbstract
             ];
         }
 
-        // Get all nodes in this collection using nodeList with recursive=false
+        // List immediate child collections and entities of this collection;
-        // We handle recursion ourselves to build proper paths
+        // recursion is handled here to build proper archive paths
+        $sources = new ResourceIdentifiers();
+        $sources->add(new CollectionIdentifier($provider, $service, $collectionId));
         try {
-            $nodes = $this->manager->nodeList(
+            $collections = $this->manager->collectionList($tenantId, $userId, $sources)[$provider][$service] ?? [];
-                $tenantId,
+            $entities = $this->manager->entityListBulk($tenantId, $userId, $sources)[$provider][$service][$collectionId] ?? [];
-                $userId,
-                $provider,
-                $service,
-                $collectionId,
-                false // Not recursive - we handle it ourselves
-            );
         } catch (Throwable $e) {
             $this->logger->warning('Failed to list collection contents', [
                 'collection' => $collectionId,
@@ -426,34 +421,35 @@ class TransferController extends ControllerAbstract
             return $files;
         }
 
-        foreach ($nodes as $node) {
+        /** @var CollectionBaseInterface $node */
-            $nodeName = $node->getLabel() ?? (string) $node->id();
+        foreach ($collections as $node) {
+            $nodeName = $node->getProperties()->getLabel() ?? (string) $node->identifier();
             $nodePath = $basePath !== '' ? $basePath . '/' . $nodeName : $nodeName;
+            // Recursively get contents of sub-collection
+            $subFiles = $this->resolveCollectionContents(
+                $tenantId,
+                $userId,
+                $provider,
+                $service,
+                (string) $node->identifier(),
+                $nodePath,
+                $depth + 1,
+                $maxDepth
+            );
+            $files = array_merge($files, $subFiles);
+        }
 
-            if ($node->isCollection()) {
+        /** @var EntityBaseInterface $node */
-                // Recursively get contents of sub-collection
+        foreach ($entities as $node) {
-                $subFiles = $this->resolveCollectionContents(
+            $nodeName = $node->getProperties()->getLabel() ?? (string) $node->identifier();
-                    $tenantId,
+            $nodePath = $basePath !== '' ? $basePath . '/' . $nodeName : $nodeName;
-                    $userId,
+            $files[] = [
-                    $provider,
+                'type' => 'file',
-                    $service,
+                'id' => (string) $node->identifier(),
-                    (string) $node->id(),
+                'collection' => $collectionId,
-                    $nodePath,
+                'path' => $nodePath,
-                    $depth + 1,
+                'modTime' => $node->modified()?->getTimestamp(),
-                    $maxDepth
+            ];
-                );
-                $files = array_merge($files, $subFiles);
-            } else {
-                // It's an entity (file)
-                /** @var INodeEntityBase $node */
-                $files[] = [
-                    'type' => 'file',
-                    'id' => (string) $node->id(),
-                    'collection' => $collectionId,
-                    'path' => $nodePath,
-                    'modTime' => $node->modifiedOn()?->getTimestamp(),
-                ];
-            }
         }
 
         return $files;

lib/Module.php

@@ -2,13 +2,14 @@
 
 namespace KTXM\DocumentsManager;
 
-use KTXF\Module\ModuleBrowserInterface;
+use KTXF\Module\Configuration\BrowserModuleContextInterface;
+use KTXF\Module\Configuration\ModuleContextInterface;
 use KTXF\Module\ModuleInstanceAbstract;
 
 /**
  * File Manager Module
  */
-class Module extends ModuleInstanceAbstract implements ModuleBrowserInterface
+class Module extends ModuleInstanceAbstract
 {
 
     public function __construct()
@@ -50,16 +51,11 @@ class Module extends ModuleInstanceAbstract implements ModuleBrowserInterface
         ];
     }
     
-    public function registerBI(): array {
+    public function configure(ModuleContextInterface $context): void
-        return [
+    {
-            'handle' => $this->handle(),
+        if ($context instanceof BrowserModuleContextInterface) {
-            'namespace' => 'DocumentsManager',
+            $context->registerModule($this, 'DocumentsManager', 'static/module.mjs');
-            'version' => $this->version(),
+        }
-            'label' => $this->label(),
-            'author' => $this->author(),
-            'description' => $this->description(),
-            'boot' => 'static/module.mjs',
-        ];
     }
 
 }

lib/Stream/ExpectedTotal.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\DocumentsManager\Stream;
+
+/**
+ * Implemented by a stream event that declares, up front, how many data frames
+ * are expected to follow. When such an event leads a stream generator, the
+ * envelope writer folds its value into the `control:start` frame's `total`
+ * (the progress denominator) instead of emitting it as a `data` frame.
+ */
+interface ExpectedTotal {
+    public function expectedTotal(): int;
+}

package.json

@@ -7,17 +7,27 @@
     "build": "vite build --mode production --config vite.config.ts",
     "dev": "vite build --mode development --config vite.config.ts",
     "watch": "vite build --mode development --watch --config vite.config.ts",
-    "typecheck": "vue-tsc --noEmit"
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run --config tests/js/vitest.config.ts",
+    "test:unit": "vitest run --config tests/js/vitest.config.ts",
+    "test:watch": "vitest watch --config tests/js/vitest.config.ts",
+    "test:coverage": "vitest run --coverage --config tests/js/vitest.config.ts"
   },
   "dependencies": {
-    "pinia": "^2.3.0",
+    "pinia": "^4.0.0",
-    "vue": "^3.5.13"
+    "vue": "^3.5.13",
+    "vuetify": "^4.0.0"
   },
   "devDependencies": {
-    "@tsconfig/node22": "^22.0.0",
+    "@tsconfig/node24": "^24.0.0",
-    "@types/node": "^22.10.1",
+    "@types/node": "^24.0.0",
-    "@vue/tsconfig": "^0.8.0",
+    "@vitejs/plugin-vue": "^6.0.1",
-    "typescript": "~5.7.2",
+    "@vue/tsconfig": "^0.9.0",
-    "vite": "^6.0.3"
+    "typescript": "~6.0.0",
+    "vite": "^8.0.0",
+    "vue-tsc": "^3.0.5",
+    "@vitest/coverage-v8": "^4.1.6",
+    "jsdom": "^29.1.1",
+    "vitest": "^4.1.6"
   }
 }

src/components/DocumentSelectorDialog.vue

@@ -0,0 +1,228 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { useDocumentManager, useDocumentSelection } from '@/composables'
+import { CollectionObject } from '@/models/collection'
+import { EntityObject } from '@/models/entity'
+import { formatSize, getFileIcon } from '@/utils/fileHelpers'
+
+export interface DocumentSelection {
+  kind: 'entity' | 'collection'
+  identifier: string
+  name: string
+  mimeType?: string
+  size?: number
+}
+
+const PROVIDER_ID = 'default'
+const SERVICE_ID = 'personal'
+const LARGE_FILE_WARNING_BYTES = 25 * 1024 * 1024
+
+const props = withDefaults(defineProps<{
+  modelValue: boolean
+  selectable?: ('entity' | 'collection')[]
+}>(), {
+  selectable: () => ['entity'],
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  select: [items: DocumentSelection[]]
+}>()
+
+const allowEntities = computed(() => props.selectable.includes('entity'))
+const allowCollections = computed(() => props.selectable.includes('collection'))
+
+const documentManager = useDocumentManager({
+  providerId: PROVIDER_ID,
+  serviceId: SERVICE_ID,
+})
+
+const selection = useDocumentSelection({
+  multiple: true,
+  allowFolders: allowCollections.value,
+  allowFiles: allowEntities.value,
+})
+
+const initialized = ref(false)
+
+watch(() => props.modelValue, async (isOpen) => {
+  if (!isOpen) {
+    return
+  }
+
+  selection.clear()
+
+  if (!initialized.value) {
+    await documentManager.initialize()
+    initialized.value = true
+  }
+
+  await documentManager.navigateToRoot()
+})
+
+function nodeId(node: CollectionObject | EntityObject): string {
+  return String(node.identifier ?? '')
+}
+
+function nodeLabel(node: CollectionObject | EntityObject): string {
+  return node.properties.label || nodeId(node)
+}
+
+const breadcrumbs = computed(() => [
+  { id: documentManager.ROOT_ID, label: 'Home' },
+  ...documentManager.breadcrumbs.value.map(node => ({ id: nodeId(node), label: nodeLabel(node) })),
+])
+
+async function navigateToBreadcrumb(id: string) {
+  selection.clear()
+  await documentManager.navigateTo(id === documentManager.ROOT_ID ? null : id)
+}
+
+async function openFolder(folder: CollectionObject) {
+  selection.clear()
+  await documentManager.navigateTo(nodeId(folder))
+}
+
+function toggleFolderSelection(folder: CollectionObject, event: Event) {
+  event.stopPropagation()
+  selection.toggle(folder)
+}
+
+function toggleEntity(entity: EntityObject) {
+  selection.toggle(entity)
+}
+
+const hasLargeSelection = computed(() =>
+  selection.selectedEntities.value.some(entity => entity.properties.size > LARGE_FILE_WARNING_BYTES),
+)
+
+function entityIdentifier(entity: EntityObject): string {
+  return `${entity.provider}:${entity.service}:${entity.collection}:${entity.identifier}`
+}
+
+function collectionIdentifier(collection: CollectionObject): string {
+  return `${collection.provider}:${collection.service}:${collection.identifier}`
+}
+
+function toSelection(node: CollectionObject | EntityObject): DocumentSelection {
+  if (node instanceof EntityObject) {
+    return {
+      kind: 'entity',
+      identifier: entityIdentifier(node),
+      name: nodeLabel(node),
+      mimeType: node.properties.mime || 'application/octet-stream',
+      size: node.properties.size,
+    }
+  }
+
+  return {
+    kind: 'collection',
+    identifier: collectionIdentifier(node),
+    name: nodeLabel(node),
+  }
+}
+
+function handleClose() {
+  emit('update:modelValue', false)
+}
+
+function handleConfirm() {
+  const items = selection.selectedNodeArray.value.map(toSelection)
+  if (items.length === 0) {
+    return
+  }
+  emit('select', items)
+  selection.clear()
+  emit('update:modelValue', false)
+}
+</script>
+
+<template>
+  <v-dialog :model-value="modelValue" @update:model-value="emit('update:modelValue', $event)" max-width="560">
+    <v-card>
+      <v-card-title class="d-flex align-center">
+        <v-icon class="mr-2">mdi-folder-search-outline</v-icon>
+        Select Documents
+      </v-card-title>
+
+      <v-card-text>
+        <v-breadcrumbs :items="breadcrumbs" density="compact" class="px-0 mb-2">
+          <template #item="{ item }">
+            <v-breadcrumbs-item :disabled="item.id === breadcrumbs[breadcrumbs.length - 1]?.id" @click="navigateToBreadcrumb(item.id)">
+              {{ item.label }}
+            </v-breadcrumbs-item>
+          </template>
+        </v-breadcrumbs>
+
+        <v-progress-linear v-if="documentManager.isLoading.value" indeterminate color="primary" class="mb-2" />
+
+        <div class="selector-list">
+          <v-list v-if="documentManager.currentCollections.value.length > 0 || documentManager.currentEntities.value.length > 0" density="compact">
+            <v-list-item
+              v-for="folder in documentManager.currentCollections.value"
+              :key="nodeId(folder)"
+              :title="nodeLabel(folder)"
+              @click="openFolder(folder)"
+            >
+              <template #prepend>
+                <v-checkbox-btn
+                  v-if="allowCollections"
+                  :model-value="selection.isSelected(nodeId(folder))"
+                  class="mr-2"
+                  @click="toggleFolderSelection(folder, $event)"
+                />
+                <v-icon>mdi-folder</v-icon>
+              </template>
+              <template #append>
+                <v-icon size="small">mdi-chevron-right</v-icon>
+              </template>
+            </v-list-item>
+
+            <v-list-item
+              v-for="entity in documentManager.currentEntities.value"
+              :key="nodeId(entity)"
+              :title="nodeLabel(entity)"
+              :subtitle="formatSize(entity.properties.size)"
+              :disabled="!allowEntities"
+              @click="allowEntities && toggleEntity(entity)"
+            >
+              <template #prepend>
+                <v-checkbox-btn v-if="allowEntities" :model-value="selection.isSelected(nodeId(entity))" class="mr-2" />
+                <v-icon>{{ getFileIcon(entity) }}</v-icon>
+              </template>
+            </v-list-item>
+          </v-list>
+
+          <div v-else-if="!documentManager.isLoading.value" class="text-center py-8 text-medium-emphasis">
+            <v-icon size="40" class="mb-2">mdi-folder-open-outline</v-icon>
+            <div>This folder is empty</div>
+          </div>
+        </div>
+
+        <v-alert v-if="hasLargeSelection" type="warning" variant="tonal" density="compact" class="mt-3">
+          One or more selected files are larger than 25 MB and may take a moment to process.
+        </v-alert>
+      </v-card-text>
+
+      <v-card-actions>
+        <span class="text-caption text-medium-emphasis ml-2">
+          {{ selection.count.value }} selected
+        </span>
+        <v-spacer />
+        <v-btn variant="text" @click="handleClose">Cancel</v-btn>
+        <v-btn color="primary" variant="elevated" :disabled="!selection.hasSelection.value" @click="handleConfirm">
+          Select
+        </v-btn>
+      </v-card-actions>
+    </v-card>
+  </v-dialog>
+</template>
+
+<style scoped>
+.selector-list {
+  max-height: 360px;
+  overflow-y: auto;
+  border: 1px solid rgb(var(--v-border-color));
+  border-radius: 8px;
+}
+</style>

src/composables/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Central export point for Documents Manager composables
+ */
+
+export { useDocumentManager } from './useDocumentManager'
+export { useDocumentSelection } from './useDocumentSelection'
+
+export type { UseDocumentManagerOptions } from './useDocumentManager'
+export type { UseDocumentSelectionOptions } from './useDocumentSelection'

src/composables/useDocumentManager.ts

@@ -0,0 +1,349 @@
+/**
+ * File Manager composable for convenient file/folder operations
+ * Provides reactive access to file manager state and actions
+ */
+
+import { computed, ref, unref } from 'vue'
+import type { Ref, ComputedRef } from 'vue'
+import { useProvidersStore } from '@/stores/providersStore'
+import { useServicesStore } from '@/stores/servicesStore'
+import { useNodesStore, ROOT_ID } from '@/stores/nodesStore'
+import type { ListFilter, ListSort, ListRange, ServiceIdentifier, CollectionIdentifier } from '@/types/common'
+import type { DocumentInterface } from '@/types/document'
+import { CollectionObject } from '@/models/collection'
+import { EntityObject } from '@/models/entity'
+
+// Base URL for file manager transfer endpoints
+const TRANSFER_BASE_URL = '/m/documents_manager'
+
+// Number of collections+entities requested per page
+const DEFAULT_PAGE_TALLY = 64
+
+export interface UseDocumentManagerOptions {
+  providerId: string | Ref<string> | ComputedRef<string>
+  serviceId: string | Ref<string> | ComputedRef<string>
+  autoFetch?: boolean
+}
+
+export function useDocumentManager(options: UseDocumentManagerOptions) {
+  const providersStore = useProvidersStore()
+  const servicesStore = useServicesStore()
+  const nodesStore = useNodesStore()
+
+  const { providerId, serviceId, autoFetch = false } = options
+
+  const currentProviderId = () => unref(providerId)
+  const currentServiceId = () => unref(serviceId)
+
+  const currentSources = (): (ServiceIdentifier | CollectionIdentifier)[] => [
+    currentLocation.value === ROOT_ID
+      ? `${currentProviderId()}:${currentServiceId()}`
+      : `${currentProviderId()}:${currentServiceId()}:${currentLocation.value}`,
+  ]
+
+  // Current location (folder being viewed)
+  const currentLocation: Ref<string> = ref(ROOT_ID)
+
+  // Loading/error state
+  const isLoading = computed(() => nodesStore.transceiving)
+  const error = computed(() => nodesStore.error)
+
+  // Pagination state for the current location + filter + sort
+  const currentFilter: Ref<ListFilter | undefined> = ref(undefined)
+  const currentSort: Ref<ListSort | undefined> = ref(undefined)
+  const loadedCount = ref(0)
+  const hasMore = ref(false)
+  const isLoadingMore = ref(false)
+
+  // Provider and service
+  const provider = computed(() => providersStore.provider(currentProviderId()))
+  const service = computed(() => servicesStore.service(currentProviderId(), currentServiceId()))
+  const rootId = computed(() => ROOT_ID)
+
+  // Current children
+  const currentChildren = computed(() =>
+    nodesStore.getChildren(currentProviderId(), currentServiceId(), currentLocation.value)
+  )
+
+  const currentCollections: ComputedRef<CollectionObject[]> = computed(() =>
+    nodesStore.getChildCollections(currentProviderId(), currentServiceId(), currentLocation.value)
+  )
+
+  const currentEntities: ComputedRef<EntityObject[]> = computed(() =>
+    nodesStore.getChildEntities(currentProviderId(), currentServiceId(), currentLocation.value)
+  )
+
+  // Breadcrumb path
+  const breadcrumbs = computed(() => {
+    if (currentLocation.value === ROOT_ID) {
+      return []
+    }
+    return nodesStore.getPath(currentProviderId(), currentServiceId(), currentLocation.value)
+  })
+
+  // Is at root?
+  const isAtRoot = computed(() => currentLocation.value === ROOT_ID)
+
+  // Navigate to a folder
+  const navigateTo = async (collectionId: string | null) => {
+    currentLocation.value = collectionId || ROOT_ID
+    await resetAndLoad(currentFilter.value, currentSort.value)
+  }
+
+  // Navigate up one level
+  const navigateUp = async () => {
+    if (currentLocation.value === ROOT_ID) {
+      return
+    }
+    const currentNode = nodesStore.getNode(currentProviderId(), currentServiceId(), currentLocation.value)
+    if (currentNode) {
+      await navigateTo(currentNode.collection ? String(currentNode.collection) : ROOT_ID)
+    }
+  }
+
+  // Navigate to root
+  const navigateToRoot = async () => {
+    await navigateTo(ROOT_ID)
+  }
+
+  // Reset the current location's loaded items and (re)fetch the first page,
+  // optionally with a new filter/sort (e.g. search query or sort field change)
+  const resetAndLoad = async (filter?: ListFilter, sort?: ListSort) => {
+    currentFilter.value = filter
+    currentSort.value = sort
+    loadedCount.value = 0
+    hasMore.value = false
+
+    const range: ListRange = { type: 'tally', anchor: 'absolute', position: 0, tally: DEFAULT_PAGE_TALLY }
+    const result = await nodesStore.fetchNodes(
+      currentSources(),
+      filter,
+      sort,
+      range,
+      'reset'
+    )
+
+    loadedCount.value = result.collections.length + result.entities.length
+    hasMore.value = !result.isLastPage
+  }
+
+  // Fetch the next page of the current location (infinite scroll "load more")
+  const loadMore = async () => {
+    if (!hasMore.value || isLoadingMore.value) {
+      return
+    }
+
+    isLoadingMore.value = true
+    try {
+      const range: ListRange = { type: 'tally', anchor: 'absolute', position: loadedCount.value, tally: DEFAULT_PAGE_TALLY }
+      const result = await nodesStore.fetchNodes(
+        currentSources(),
+        currentFilter.value,
+        currentSort.value,
+        range,
+        'append'
+      )
+
+      loadedCount.value += result.collections.length + result.entities.length
+      hasMore.value = !result.isLastPage
+    } finally {
+      isLoadingMore.value = false
+    }
+  }
+
+  // Create a new folder
+  const createFolder = async (label: string): Promise<CollectionObject> => {
+    return await nodesStore.createCollection(
+      `${currentProviderId()}:${currentServiceId()}:${currentLocation.value}`,
+      { label, owner: '' }
+    )
+  }
+
+  // Create a new file
+  const createFile = async (
+    label: string,
+    mime: string = 'application/octet-stream'
+  ): Promise<EntityObject> => {
+    const properties: DocumentInterface = {
+      '@type': 'documents.properties',
+      urid: null,
+      size: 0,
+      label,
+      mime,
+      format: null,
+      encoding: null,
+    }
+
+    return await nodesStore.createEntity(
+      `${currentProviderId()}:${currentServiceId()}:${currentLocation.value}`,
+      properties
+    )
+  }
+
+  // Rename a node
+  const renameNode = async (nodeId: string, newLabel: string) => {
+    const node = nodesStore.getNode(currentProviderId(), currentServiceId(), nodeId)
+    if (!node) {
+      throw new Error('Node not found')
+    }
+
+    if (node instanceof CollectionObject) {
+      return await nodesStore.updateCollection(`${node.provider}:${node.service}:${nodeId}`, {
+        label: newLabel,
+        owner: node.properties.owner,
+      })
+    } else {
+      const properties: DocumentInterface = {
+        '@type': 'documents.properties',
+        urid: node.properties.urid,
+        size: node.properties.size,
+        label: newLabel,
+        mime: node.properties.mime,
+        format: node.properties.format,
+        encoding: node.properties.encoding,
+      }
+      return await nodesStore.updateEntity(`${node.provider}:${node.service}:${node.collection || ROOT_ID}:${nodeId}`, properties)
+    }
+  }
+
+  // Delete a node
+  const deleteNode = async (nodeId: string): Promise<boolean> => {
+    const node = nodesStore.getNode(currentProviderId(), currentServiceId(), nodeId)
+    if (!node) {
+      throw new Error('Node not found')
+    }
+
+    if (node instanceof CollectionObject) {
+      return await nodesStore.deleteCollection(`${node.provider}:${node.service}:${nodeId}`)
+    } else {
+      return await nodesStore.deleteEntity(`${node.provider}:${node.service}:${node.collection || ROOT_ID}:${nodeId}`)
+    }
+  }
+
+  // Read file content
+  const readFile = async (entityId: string): Promise<string | null> => {
+    const node = nodesStore.getNode(currentProviderId(), currentServiceId(), entityId)
+    if (!node || !(node instanceof EntityObject)) {
+      throw new Error('Entity not found')
+    }
+    return await nodesStore.readEntity(`${node.provider}:${node.service}:${node.collection || ROOT_ID}:${entityId}`)
+  }
+
+  // Write file content
+  const writeFile = async (entityId: string, content: string): Promise<number> => {
+    const node = nodesStore.getNode(currentProviderId(), currentServiceId(), entityId)
+    if (!node || !(node instanceof EntityObject)) {
+      throw new Error('Entity not found')
+    }
+    return await nodesStore.writeEntity(`${node.provider}:${node.service}:${node.collection || ROOT_ID}:${entityId}`, content)
+  }
+
+  // Get a URL suitable for inline viewing (img src / video src)
+  const getEntityUrl = (entityId: string, collectionId?: string | null): string => {
+    const collection = collectionId ?? currentLocation.value
+    return `${TRANSFER_BASE_URL}/download/entity/${encodeURIComponent(currentProviderId())}/${encodeURIComponent(currentServiceId())}/${encodeURIComponent(collection)}/${encodeURIComponent(entityId)}`
+  }
+
+  const getEntityPreviewUrl = (
+    entityId: string,
+    collectionId?: string | null,
+    variant: 'thumbnail' | 'inline' | 'fullscreen' = 'inline',
+  ): string => {
+    const collection = collectionId ?? currentLocation.value
+    return `${TRANSFER_BASE_URL}/preview/entity/${encodeURIComponent(currentProviderId())}/${encodeURIComponent(currentServiceId())}/${encodeURIComponent(collection)}/${encodeURIComponent(entityId)}?variant=${variant}`
+  }
+
+  // Download a single file
+  const downloadEntity = (entityId: string, collectionId?: string | null): void => {
+    const collection = collectionId ?? currentLocation.value
+    // Use path parameters: /download/entity/{provider}/{service}/{collection}/{identifier}
+    const url = `${TRANSFER_BASE_URL}/download/entity/${encodeURIComponent(currentProviderId())}/${encodeURIComponent(currentServiceId())}/${encodeURIComponent(collection)}/${encodeURIComponent(entityId)}`
+
+    // Trigger download by opening URL (browser handles it)
+    window.open(url, '_blank')
+  }
+
+  const downloadCollection = (collectionId: string): void => {
+    // Use path parameters: /download/collection/{provider}/{service}/{identifier}
+    const url = `${TRANSFER_BASE_URL}/download/collection/${encodeURIComponent(currentProviderId())}/${encodeURIComponent(currentServiceId())}/${encodeURIComponent(collectionId)}`
+
+    window.open(url, '_blank')
+  }
+
+  const downloadArchive = (ids: string[], name: string = 'download', collectionId?: string | null): void => {
+    const collection = collectionId ?? currentLocation.value
+    const params = new URLSearchParams({
+      provider: currentProviderId(),
+      service: currentServiceId(),
+    })
+    ids.forEach(id => params.append('ids[]', id))
+    if (name) {
+      params.append('name', name)
+    }
+    if (collection && collection !== ROOT_ID) {
+      params.append('collection', collection)
+    }
+
+    const url = `${TRANSFER_BASE_URL}/download/archive?${params.toString()}`
+
+    window.open(url, '_blank')
+  }
+
+  // Initialize - fetch providers, services, and initial nodes if autoFetch
+  const initialize = async () => {
+    await providersStore.list([currentProviderId()])
+    await servicesStore.list()
+    if (autoFetch) {
+      await resetAndLoad()
+    }
+  }
+
+  return {
+    // State
+    currentLocation,
+    isLoading,
+    error,
+    hasMore,
+    isLoadingMore,
+
+    // Provider/Service
+    provider,
+    service,
+    rootId,
+
+    // Current view
+    currentChildren,
+    currentCollections,
+    currentEntities,
+    breadcrumbs,
+    isAtRoot,
+
+    // Navigation
+    navigateTo,
+    navigateUp,
+    navigateToRoot,
+    resetAndLoad,
+    loadMore,
+
+    // Operations
+    createFolder,
+    createFile,
+    renameNode,
+    deleteNode,
+    readFile,
+    writeFile,
+    getEntityUrl,
+    getEntityPreviewUrl,
+    downloadEntity,
+    downloadCollection,
+    downloadArchive,
+
+    // Initialize
+    initialize,
+
+    // Constants
+    ROOT_ID,
+  }
+}
+
+export default useDocumentManager

src/composables/useDocumentSelection.ts

@@ -0,0 +1,135 @@
+/**
+ * File selection composable
+ * Provides reactive selection management for file manager
+ */
+
+import { ref, computed } from 'vue'
+import type { Ref, ComputedRef } from 'vue'
+import { CollectionObject } from '@/models/collection'
+import { EntityObject } from '@/models/entity'
+
+type NodeRecord = CollectionObject | EntityObject
+
+export interface UseDocumentSelectionOptions {
+  multiple?: boolean
+  allowFolders?: boolean
+  allowFiles?: boolean
+}
+
+export function useDocumentSelection(options: UseDocumentSelectionOptions = {}) {
+  const {
+    multiple = true,
+    allowFolders = true,
+    allowFiles = true,
+  } = options
+
+  const selectedIds: Ref<Set<string>> = ref(new Set())
+  const selectedNodes: Ref<Map<string, NodeRecord>> = ref(new Map())
+
+  const count: ComputedRef<number> = computed(() => selectedIds.value.size)
+  const hasSelection: ComputedRef<boolean> = computed(() => selectedIds.value.size > 0)
+
+  const selectedIdArray: ComputedRef<string[]> = computed(() => Array.from(selectedIds.value))
+  const selectedNodeArray: ComputedRef<NodeRecord[]> = computed(() => Array.from(selectedNodes.value.values()))
+
+  const selectedCollections: ComputedRef<CollectionObject[]> = computed(() =>
+    selectedNodeArray.value.filter((node): node is CollectionObject => node instanceof CollectionObject),
+  )
+
+  const selectedEntities: ComputedRef<EntityObject[]> = computed(() =>
+    selectedNodeArray.value.filter((node): node is EntityObject => node instanceof EntityObject),
+  )
+
+  const isSelected = (nodeId: string): boolean => selectedIds.value.has(nodeId)
+
+  const isTypeAllowed = (node: NodeRecord): boolean => {
+    if (node instanceof CollectionObject && !allowFolders) return false
+    if (node instanceof EntityObject && !allowFiles) return false
+    return true
+  }
+
+  const select = (node: NodeRecord) => {
+    if (!isTypeAllowed(node)) return
+
+    if (!multiple) {
+      selectedIds.value.clear()
+      selectedNodes.value.clear()
+    }
+
+    const nodeId = String(node.identifier)
+    selectedIds.value.add(nodeId)
+    selectedNodes.value.set(nodeId, node)
+  }
+
+  const deselect = (nodeId: string) => {
+    selectedIds.value.delete(nodeId)
+    selectedNodes.value.delete(nodeId)
+  }
+
+  const toggle = (node: NodeRecord) => {
+    const nodeId = String(node.identifier)
+    if (isSelected(nodeId)) {
+      deselect(nodeId)
+      return
+    }
+    select(node)
+  }
+
+  const selectMultiple = (nodes: NodeRecord[]) => {
+    if (!multiple) {
+      const lastNode = nodes[nodes.length - 1]
+      if (lastNode && isTypeAllowed(lastNode)) {
+        selectedIds.value.clear()
+        selectedNodes.value.clear()
+        const nodeId = String(lastNode.identifier)
+        selectedIds.value.add(nodeId)
+        selectedNodes.value.set(nodeId, lastNode)
+      }
+      return
+    }
+
+    for (const node of nodes) {
+      if (isTypeAllowed(node)) {
+        const nodeId = String(node.identifier)
+        selectedIds.value.add(nodeId)
+        selectedNodes.value.set(nodeId, node)
+      }
+    }
+  }
+
+  const selectAll = (nodes: NodeRecord[]) => {
+    if (!multiple) return
+    selectMultiple(nodes)
+  }
+
+  const clear = () => {
+    selectedIds.value.clear()
+    selectedNodes.value.clear()
+  }
+
+  const setSelection = (nodes: NodeRecord[]) => {
+    clear()
+    selectMultiple(nodes)
+  }
+
+  return {
+    selectedIds,
+    selectedNodes,
+    count,
+    hasSelection,
+    selectedIdArray,
+    selectedNodeArray,
+    selectedCollections,
+    selectedEntities,
+    isSelected,
+    select,
+    deselect,
+    toggle,
+    selectMultiple,
+    selectAll,
+    clear,
+    setSelection,
+  }
+}
+
+export default useDocumentSelection

src/integrations.ts

@@ -0,0 +1,14 @@
+import type { ModuleIntegrations } from "@KTXC/types/moduleTypes";
+
+const integrations: ModuleIntegrations = {
+  documents_selector: [
+    {
+      id: 'dialog',
+      label: 'Document Selector Dialog',
+      priority: 10,
+      component: () => import('./components/DocumentSelectorDialog.vue'),
+    },
+  ],
+};
+
+export default integrations;

src/main.ts

@@ -2,14 +2,20 @@
  * Documents Manager Module Boot
  */
 
+import integrations from '@/integrations'
+
 console.log('[Documents Manager] Booting module...')
 
 console.log('[Documents Manager] Module booted successfully...')
 
-// CSS will be injected by build process
+// CSS filename is injected by the vite plugin at build time
-//export const css = ['__CSS_FILENAME_PLACEHOLDER__']
+export const css = ['__CSS_FILENAME_PLACEHOLDER__']
+
+export { integrations }
 
 // Export services, stores and models for external use
 export * from '@/services'
 export * from '@/stores'
 export * from '@/models'
+export * from '@/composables'
+export * from '@/utils/fileHelpers'

src/models/collection.ts

@@ -4,6 +4,19 @@
 
 import type { CollectionContentTypes, CollectionInterface, CollectionModelInterface, CollectionPropertiesInterface } from "@/types/collection";
 
+/**
+ * Reduce a serialized resource identifier ("provider:service:collection")
+ * to its own (last) segment; plain values pass through unchanged
+ */
+function plainIdentifier(value: string | number | null | undefined): string | number | null {
+    if (value === null || value === undefined || value === '') {
+        return value ?? null;
+    }
+    const text = String(value);
+    const index = text.lastIndexOf(':');
+    return index >= 0 ? text.slice(index + 1) : value;
+}
+
 export class CollectionObject implements CollectionModelInterface {
 
     _data!: CollectionInterface;
@@ -24,7 +37,14 @@ export class CollectionObject implements CollectionModelInterface {
     }
 
     fromJson(data: CollectionInterface): CollectionObject {
-        this._data = data;
+        // the wire format carries full resource identifiers (provider:service:collection);
+        // reduce them to plain ids, which is what the stores and UI operate on
+        this._data = {
+            ...data,
+            service: plainIdentifier(data.service) ?? '',
+            collection: plainIdentifier(data.collection),
+            identifier: plainIdentifier(data.identifier) ?? '',
+        };
         if (data.properties) {
             this._data.properties = new CollectionPropertiesObject().fromJson(data.properties as CollectionPropertiesInterface);
         }

src/models/entity.ts

@@ -5,6 +5,19 @@ import type { EntityInterface, EntityModelInterface } from "@/types/entity";
 import type { DocumentInterface, DocumentModelInterface } from "@/types/document";
 import { DocumentObject } from "./document";
 
+/**
+ * Reduce a serialized resource identifier ("provider:service:collection:entity")
+ * to its own (last) segment; plain values pass through unchanged
+ */
+function plainIdentifier(value: string | number | null | undefined): string | number | null {
+    if (value === null || value === undefined || value === '') {
+        return value ?? null;
+    }
+    const text = String(value);
+    const index = text.lastIndexOf(':');
+    return index >= 0 ? text.slice(index + 1) : value;
+}
+
 export class EntityObject implements EntityModelInterface {
 
     _data!: EntityInterface<DocumentInterface|DocumentModelInterface>;
@@ -25,7 +38,14 @@ export class EntityObject implements EntityModelInterface {
     }
 
     fromJson(data: EntityInterface): EntityObject {
-        this._data = data
+        // the wire format carries full resource identifiers (provider:service:collection:entity);
+        // reduce them to plain ids, which is what the stores and UI operate on
+        this._data = {
+            ...data,
+            service: String(plainIdentifier(data.service) ?? ''),
+            collection: plainIdentifier(data.collection) ?? '',
+            identifier: plainIdentifier(data.identifier) ?? '',
+        }
         if (data.properties) {
             this._data.properties = new DocumentObject().fromJson(data.properties as DocumentInterface);
         }

src/services/collectionService.ts

@@ -16,28 +16,20 @@ import type {
   CollectionUpdateRequest,
   CollectionDeleteResponse,
   CollectionDeleteRequest,
+  CollectionCopyRequest,
+  CollectionCopyResponse,
+  CollectionMoveRequest,
+  CollectionMoveResponse,
   CollectionInterface,
 } from '../types/collection';
 import { useIntegrationStore } from '@KTXC/stores/integrationStore';
 import { CollectionObject, CollectionPropertiesObject } from '../models/collection';
 
-function isCollectionPayload(value: unknown): value is CollectionInterface {
-  if (!value || typeof value !== 'object') {
-    return false;
-  }
-
-  const candidate = value as Record<string, unknown>;
-  return (
-    ('identifier' in candidate || 'provider' in candidate || 'service' in candidate)
-    && 'properties' in candidate
-  );
-}
-
 /**
  * Helper to create the right collection model class based on provider identifier
  * Uses provider-specific factory if available, otherwise returns base CollectionObject
  */
-function createCollectionObject(data: CollectionInterface): CollectionObject {
+export function createCollectionObject(data: CollectionInterface): CollectionObject {
   const integrationStore = useIntegrationStore();
   const factoryItem = integrationStore.getItemById('documents_collection_factory', data.provider) as any;
   const factory = factoryItem?.factory;
@@ -64,19 +56,8 @@ export const collectionService = {
       const serviceList: Record<string, Record<string, CollectionObject>> = {};
       Object.entries(providerServices).forEach(([serviceId, serviceCollections]) => {
         const collectionList: Record<string, CollectionObject> = {};
-        Object.entries(serviceCollections as Record<string, unknown>).forEach(([collectionId, collectionData]) => {
+        Object.entries(serviceCollections).forEach(([collectionId, collectionData]) => {
-          if (isCollectionPayload(collectionData)) {
+          collectionList[collectionId] = createCollectionObject(collectionData);
-            collectionList[collectionId] = createCollectionObject(collectionData);
-            return;
-          }
-
-          if (collectionData && typeof collectionData === 'object') {
-            Object.entries(collectionData as Record<string, unknown>).forEach(([nestedCollectionId, nestedCollectionData]) => {
-              if (isCollectionPayload(nestedCollectionData)) {
-                collectionList[nestedCollectionId] = createCollectionObject(nestedCollectionData);
-              }
-            });
-          }
         });
         serviceList[serviceId] = collectionList;
       });
@@ -87,15 +68,15 @@ export const collectionService = {
   },
 
   /**
-   * Retrieve a specific collection by provider and identifier
+   * Retrieve collections by resource identifier
    * 
    * @param request - fetch request parameters
    * 
-   * @returns Promise with collection object
+   * @returns Promise with collections keyed by resource identifier
    */
-  async fetch(request: CollectionFetchRequest): Promise<CollectionObject> {
+  async fetch(request: CollectionFetchRequest): Promise<Record<string, CollectionObject>> {
     const response = await transceivePost<CollectionFetchRequest, CollectionFetchResponse>('collection.fetch', request);
-    return createCollectionObject(response);
+    return Object.fromEntries(Object.entries(response).map(([target, data]) => [target, createCollectionObject(data)]));
   },
 
   /**
@@ -150,6 +131,30 @@ export const collectionService = {
     return await transceivePost<CollectionDeleteRequest, CollectionDeleteResponse>('collection.delete', request);
   },
 
+  /**
+   * Copy a collection to a new parent
+   *
+   * @param request - copy request parameters
+   *
+   * @returns Promise with copied collection object
+   */
+  async copy(request: CollectionCopyRequest): Promise<CollectionObject> {
+    const response = await transceivePost<CollectionCopyRequest, CollectionCopyResponse>('collection.copy', request);
+    return createCollectionObject(response);
+  },
+
+  /**
+   * Move a collection to a new parent
+   *
+   * @param request - move request parameters
+   *
+   * @returns Promise with moved collection object
+   */
+  async move(request: CollectionMoveRequest): Promise<CollectionObject> {
+    const response = await transceivePost<CollectionMoveRequest, CollectionMoveResponse>('collection.move', request);
+    return createCollectionObject(response);
+  },
+
 };
 
 export default collectionService;

src/services/entityService.ts

@@ -2,7 +2,7 @@
  * Entity management service
  */
 
-import { transceivePost } from './transceive';
+import { transceivePost, transceiveStream } from './transceive';
 import type {
   EntityListRequest,
   EntityListResponse,
@@ -18,6 +18,10 @@ import type {
   EntityDeleteResponse,
   EntityDeltaRequest,
   EntityDeltaResponse,
+  EntityCopyRequest,
+  EntityCopyResponse,
+  EntityMoveRequest,
+  EntityMoveResponse,
   EntityReadRequest,
   EntityReadResponse,
   EntityWriteRequest,
@@ -31,7 +35,7 @@ import { EntityObject } from '../models';
  * Helper to create the right entity model class based on provider identifier
  * Uses provider-specific factory if available, otherwise returns base EntityObject
  */
-function createEntityObject(data: EntityInterface): EntityObject {
+export function createEntityObject(data: EntityInterface): EntityObject {
   const integrationStore = useIntegrationStore();
   const factoryItem = integrationStore.getItemById('documents_entity_factory', data.provider) as any;
   const factory = factoryItem?.factory;
@@ -43,14 +47,14 @@ function createEntityObject(data: EntityInterface): EntityObject {
 export const entityService = {
 
   /**
-   * Retrieve list of entities, optionally filtered by source selector
+   * Retrieve list of entities, optionally filtered by source identifiers
    *
    * @param request - list request parameters
    *
    * @returns Promise with entity object list grouped by provider, service, collection, and entity identifier
    */
-  async list(request: EntityListRequest = {}): Promise<Record<string, Record<string, Record<string, Record<string, EntityObject>>>>> {
+  async listBulk(request: EntityListRequest = {}): Promise<Record<string, Record<string, Record<string, Record<string, EntityObject>>>>> {
-    const response = await transceivePost<EntityListRequest, EntityListResponse>('entity.list', request);
+    const response = await transceivePost<EntityListRequest, EntityListResponse>('entity.listBulk', request);
     
     // Convert nested response to EntityObject instances
     const providerList: Record<string, Record<string, Record<string, Record<string, EntityObject>>>> = {};
@@ -73,6 +77,20 @@ export const entityService = {
     return providerList;
   },
 
+  /**
+   * Stream entities one by one, invoking the callback for each entity
+   *
+   * @param request - list request parameters
+   * @param onEntity - callback invoked for each streamed entity
+   *
+   * @returns Promise with the total number of streamed entities
+   */
+  async listStream(request: EntityListRequest, onEntity: (entity: EntityObject) => void): Promise<{ total: number }> {
+    return await transceiveStream<EntityListRequest, EntityInterface>('entity.listStream', request, (entityData) => {
+      onEntity(createEntityObject(entityData));
+    });
+  },
+
   /**
    * Retrieve a specific entity by provider and identifier
    *
@@ -128,16 +146,38 @@ export const entityService = {
   },
 
   /**
-   * Delete an entity
+   * Delete entities
    *
    * @param request - delete request parameters
    *
-   * @returns Promise with deletion result
+   * @returns Promise with per-entity disposition results
    */
   async delete(request: EntityDeleteRequest): Promise<EntityDeleteResponse> {
     return await transceivePost<EntityDeleteRequest, EntityDeleteResponse>('entity.delete', request);
   },
 
+  /**
+   * Copy entities to another collection
+   *
+   * @param request - copy request parameters
+   *
+   * @returns Promise with per-entity disposition results
+   */
+  async copy(request: EntityCopyRequest): Promise<EntityCopyResponse> {
+    return await transceivePost<EntityCopyRequest, EntityCopyResponse>('entity.copy', request);
+  },
+
+  /**
+   * Move entities to another collection
+   *
+   * @param request - move request parameters
+   *
+   * @returns Promise with per-entity disposition results
+   */
+  async move(request: EntityMoveRequest): Promise<EntityMoveResponse> {
+    return await transceivePost<EntityMoveRequest, EntityMoveResponse>('entity.move', request);
+  },
+
   /**
    * Retrieve delta changes for entities
    * 

src/services/index.ts

@@ -6,4 +6,3 @@ export { providerService } from './providerService';
 export { serviceService } from './serviceService';
 export { collectionService } from './collectionService';
 export { entityService } from './entityService';
-export { nodeService } from './nodeService';

src/services/nodeService.ts

@@ -1,68 +1,34 @@
-/**
+import { transceiveStream } from './transceive';
- * Node (unified collection/entity) management service
+import type { NodeListRequest, NodeInterface } from '../types/node';
- */
+import { createCollectionObject } from './collectionService';
+import { createEntityObject } from './entityService';
+import type { CollectionObject } from '../models/collection';
+import type { EntityObject } from '../models/entity';
 
-import { transceivePost } from './transceive'
+export type NodeListResult = (CollectionObject | EntityObject)[];
-import type { ListFilter, ListSort, ListRange } from '../types/common'
-import type { CollectionInterface } from '../types/collection'
-import type { EntityInterface } from '../types/entity'
-
-export type NodeItem = CollectionInterface | EntityInterface
-
-export interface NodeListRequest {
-  provider: string
-  service: string | number
-  location?: string | number | null
-  recursive?: boolean
-  filter?: ListFilter | null
-  sort?: ListSort | null
-  range?: ListRange | null
-}
-
-export type NodeListResponse = Record<string, NodeItem>
-
-export interface NodeDeltaRequest {
-  provider: string
-  service: string | number
-  location?: string | number | null
-  signature: string
-  recursive?: boolean
-  detail?: 'ids' | 'full'
-}
-
-export interface NodeDeltaResult {
-  added: Array<string | number | NodeItem>
-  modified: Array<string | number | NodeItem>
-  removed: Array<string | number>
-  signature: string
-}
 
 export const nodeService = {
-
+  /** Hydrate a mixed page in the exact order returned by the provider. */
-  async list(request: NodeListRequest): Promise<NodeItem[]> {
+  async list(request: NodeListRequest = {}): Promise<NodeListResult> {
-    const response = await transceivePost<NodeListRequest, NodeListResponse>('node.list', {
+    const nodes: NodeListResult = [];
-      provider: request.provider,
+    const { total } = await transceiveStream<NodeListRequest, NodeInterface>('node.list', request, node => {
-      service: request.service,
+      switch (node['@type']) {
-      location: request.location ?? null,
+        case 'document:collection':
-      recursive: request.recursive ?? false,
+          nodes.push(createCollectionObject(node));
-      filter: request.filter ?? null,
+          break;
-      sort: request.sort ?? null,
+        case 'document:entity':
-      range: request.range ?? null,
+          nodes.push(createEntityObject(node));
-    })
+          break;
-
+        default:
-    return Object.values(response)
+          throw new Error('Unsupported node type in node.list response');
+      }
+    }, { requireEnd: true });
+    if (total !== nodes.length) {
+      throw new Error('Incomplete node.list stream');
+    }
+    // Publish only complete pages so a retry uses the same offset after failure.
+    return nodes;
   },
+};
 
-  async delta(request: NodeDeltaRequest): Promise<NodeDeltaResult> {
+export default nodeService;
-    return await transceivePost<NodeDeltaRequest, NodeDeltaResult>('node.delta', {
-      provider: request.provider,
-      service: request.service,
-      location: request.location ?? null,
-      signature: request.signature,
-      recursive: request.recursive ?? false,
-      detail: request.detail ?? 'ids',
-    })
-  },
-}
-
-export default nodeService

src/services/transceive.ts

@@ -4,7 +4,7 @@
  */
 
 import { createFetchWrapper } from '@KTXC';
-import type { ApiRequest, ApiResponse } from '../types/common';
+import type { ApiRequest, ApiResponse, ApiStreamResponse } from '../types/common';
 
 const fetchWrapper = createFetchWrapper();
 const API_URL = '/m/documents_manager/v1';
@@ -48,3 +48,88 @@ export async function transceivePost<TRequest, TResponse>(
 
   return response.data;
 }
+
+/**
+ * Stream an NDJSON API response, unwrapping data frames for the caller.
+ *
+ * @param operation - Operation name, e.g. 'entity.listStream'
+ * @param data      - Operation-specific request data
+ * @param onData    - Synchronous callback invoked for every unwrapped data payload.
+ * @param options   - Optional `user` override and an `onStart` hook.
+ * @returns Promise resolving to the final stream total from the control/end frame
+ */
+export async function transceiveStream<TRequest, TData>(
+  operation: string,
+  data: TRequest,
+  onData: (data: TData) => void,
+  options?: { user?: string; onStart?: (expected?: number) => void; requireEnd?: boolean }
+): Promise<{ total: number }> {
+  const request: ApiRequest<TRequest> = {
+    version: API_VERSION,
+    transaction: generateTransactionId(),
+    operation,
+    data,
+    user: options?.user,
+  };
+
+  let total = 0;
+  let ended = false;
+
+  const dispatch = (line: string): void => {
+    const message = JSON.parse(line) as ApiStreamResponse<TData>;
+
+    if (message.type === 'control') {
+      if (message.status === 'start') {
+        options?.onStart?.(message.total);
+      } else if (message.status === 'end') {
+        total = message.total;
+        ended = true;
+      }
+      return;
+    }
+
+    if (message.type === 'error') {
+      throw new Error(`[${operation}] ${message.message}`);
+    }
+
+    onData(message.data);
+  };
+
+  await fetchWrapper.post(API_URL, request, {
+    headers: { 'Accept': 'application/json' },
+    onStream: async (response: Response) => {
+      if (!response.body) {
+        throw new Error(`[${operation}] Response body is not readable`);
+      }
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split('\n');
+          buffer = lines.pop()!;
+
+          for (const line of lines) {
+            if (line.trim()) dispatch(line);
+          }
+        }
+
+        buffer += decoder.decode();
+        if (buffer.trim()) dispatch(buffer);
+      } finally {
+        reader.releaseLock();
+      }
+    },
+  });
+
+  if (options?.requireEnd && !ended) {
+    throw new Error(`[${operation}] Stream ended without a completion frame`);
+  }
+  return { total };
+}

src/stores/collectionsStore.ts

@@ -6,11 +6,11 @@ import { ref, computed, readonly } from 'vue'
 import { defineStore } from 'pinia'
 import { collectionService } from '../services/collectionService'
 import type {
-  SourceSelector,
+  CollectionIdentifier,
+  ServiceIdentifier,
   ListFilter,
   ListSort,
   CollectionMutableProperties,
-  CollectionDeleteResponse,
 } from '../types'
 import { CollectionObject } from '../models/collection'
 
@@ -40,25 +40,25 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
     return `${provider}:${service ?? ''}:${identifier ?? ''}`
   }
 
-  function collection(provider: string, service: string | number, identifier: string | number, retrieve: boolean = false): CollectionObject | null {
+  function collection(target: CollectionIdentifier, retrieve: boolean = false): CollectionObject | null {
-    const key = identifierKey(provider, service, identifier)
+    const key = target
     if (retrieve === true && !_collections.value[key]) {
       console.debug(`[Documents Manager][Store] - Force fetching collection "${key}"`)
-      fetch(provider, service, identifier)
+      void fetch([target])
     }
 
     return _collections.value[key] || null
   }
 
-  function collectionsForService(provider: string, service: string | number): CollectionObject[] {
+  function collectionsForService(target: ServiceIdentifier): CollectionObject[] {
-    const serviceKeyPrefix = `${provider}:${service}:`
+    const serviceKeyPrefix = `${target}:`
     return Object.entries(_collections.value)
       .filter(([key]) => key.startsWith(serviceKeyPrefix))
       .map(([_, collectionObj]) => collectionObj)
   }
 
-  function clearService(provider: string, service: string | number): void {
+  function clearService(target: ServiceIdentifier): void {
-    const serviceKeyPrefix = `${provider}:${service}:`
+    const serviceKeyPrefix = `${target}:`
     Object.keys(_collections.value)
       .filter((key) => key.startsWith(serviceKeyPrefix))
       .forEach((key) => {
@@ -70,8 +70,29 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
     _collections.value = {}
   }
 
+  /**
+   * Merge externally-hydrated collections into the store (used by paginated node fetches)
+   */
+  function mergeMany(collections: CollectionObject[]): void {
+    const hydrated: Record<string, CollectionObject> = {}
+    collections.forEach((collectionObj) => {
+      const key = identifierKey(collectionObj.provider, collectionObj.service, collectionObj.identifier)
+      hydrated[key] = collectionObj
+    })
+    _collections.value = { ..._collections.value, ...hydrated }
+  }
+
+  /**
+   * Remove specific collections by their own identifiers (used to evict a stale page before a reset)
+   */
+  function removeMany(targets: CollectionIdentifier[]): void {
+    targets.forEach((target) => {
+      delete _collections.value[target]
+    })
+  }
+
   // Actions
-  async function list(sources?: SourceSelector, filter?: ListFilter, sort?: ListSort): Promise<Record<string, CollectionObject>> {
+  async function list(sources?: (ServiceIdentifier | CollectionIdentifier)[], filter?: ListFilter, sort?: ListSort): Promise<Record<string, CollectionObject>> {
     transceiving.value = true
     try {
       const response = await collectionService.list({ sources, filter, sort })
@@ -98,14 +119,11 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
     }
   }
 
-  async function fetch(provider: string, service: string | number, identifier: string | number): Promise<CollectionObject> {
+  async function fetch(targets: CollectionIdentifier[]): Promise<Record<string, CollectionObject>> {
     transceiving.value = true
     try {
-      const response = await collectionService.fetch({ provider, service, collection: identifier })
+      const response = await collectionService.fetch({ targets })
-      const key = identifierKey(response.provider, response.service, response.identifier)
+      _collections.value = { ..._collections.value, ...response }
-      _collections.value[key] = response
-
-      console.debug('[Documents Manager][Store] - Successfully fetched collection:', key)
       return response
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to fetch collection:', error)
@@ -115,10 +133,10 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
     }
   }
 
-  async function extant(sources: SourceSelector) {
+  async function extant(targets: CollectionIdentifier[]) {
     transceiving.value = true
     try {
-      const response = await collectionService.extant({ sources })
+      const response = await collectionService.extant({ targets })
       console.debug('[Documents Manager][Store] - Successfully checked collection availability')
       return response
     } catch (error: any) {
@@ -130,14 +148,12 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
   }
 
   async function create(
-    provider: string,
+    target: ServiceIdentifier | CollectionIdentifier,
-    service: string | number,
-    collection: string | number | null,
     properties: CollectionMutableProperties,
   ): Promise<CollectionObject> {
     transceiving.value = true
     try {
-      const response = await collectionService.create({ provider, service, collection, properties })
+      const response = await collectionService.create({ target, properties })
       const key = identifierKey(response.provider, response.service, response.identifier)
       _collections.value[key] = response
 
@@ -152,14 +168,12 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
   }
 
   async function update(
-    provider: string,
+    target: CollectionIdentifier,
-    service: string | number,
-    identifier: string | number,
     properties: CollectionMutableProperties,
   ): Promise<CollectionObject> {
     transceiving.value = true
     try {
-      const response = await collectionService.update({ provider, service, identifier, properties })
+      const response = await collectionService.update({ target, properties })
       const key = identifierKey(response.provider, response.service, response.identifier)
       _collections.value[key] = response
 
@@ -173,17 +187,17 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
     }
   }
 
-  async function remove(provider: string, service: string | number, identifier: string | number): Promise<CollectionDeleteResponse> {
+  async function remove(target: CollectionIdentifier): Promise<{ success: boolean }> {
     transceiving.value = true
     try {
-      const response = await collectionService.delete({ provider, service, identifier })
+      const response = await collectionService.delete({ target })
-      if (response.success) {
+      const success = response.disposition === 'deleted' || response.disposition === 'moved'
-        const key = identifierKey(provider, service, identifier)
+      if (success) {
-        delete _collections.value[key]
+        delete _collections.value[target]
       }
 
-      console.debug('[Documents Manager][Store] - Successfully deleted collection:', `${provider}:${service}:${identifier}`)
+      console.debug('[Documents Manager][Store] - Successfully deleted collection:', target)
-      return response
+      return { success }
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to delete collection:', error)
       throw error
@@ -202,6 +216,8 @@ export const useCollectionsStore = defineStore('documentsCollectionsStore', () =
     collectionsForService,
     clearService,
     clearAll,
+    mergeMany,
+    removeMany,
     list,
     fetch,
     extant,

src/stores/entitiesStore.ts

@@ -7,12 +7,13 @@ import { defineStore } from 'pinia'
 import { entityService } from '../services/entityService'
 import { EntityObject } from '../models'
 import type {
-  SourceSelector,
+  CollectionIdentifier,
+  EntityIdentifier,
+  ServiceIdentifier,
   ListFilter,
   ListSort,
   ListRange,
   DocumentInterface,
-  EntityDeleteResponse,
   EntityDeltaResponse,
 } from '../types'
 
@@ -48,37 +49,34 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
   }
 
   function entity(
-    provider: string,
+    target: EntityIdentifier,
-    service: string | number,
-    collection: string | number,
-    identifier: string | number,
     retrieve: boolean = false,
   ): EntityObject | null {
-    const key = identifierKey(provider, service, collection, identifier)
+    const key = target
     if (retrieve === true && !_entities.value[key]) {
       console.debug(`[Documents Manager][Store] - Force fetching entity "${key}"`)
-      fetch(provider, service, collection, [identifier])
+      void fetch([target])
     }
 
     return _entities.value[key] || null
   }
 
-  function entitiesForService(provider: string, service: string | number): EntityObject[] {
+  function entitiesForService(target: ServiceIdentifier): EntityObject[] {
-    const serviceKeyPrefix = `${provider}:${service}:`
+    const serviceKeyPrefix = `${target}:`
     return Object.entries(_entities.value)
       .filter(([key]) => key.startsWith(serviceKeyPrefix))
       .map(([_, entityObj]) => entityObj)
   }
 
-  function entitiesForCollection(provider: string, service: string | number, collection: string | number): EntityObject[] {
+  function entitiesForCollection(target: CollectionIdentifier): EntityObject[] {
-    const collectionKeyPrefix = `${provider}:${service}:${collection}:`
+    const collectionKeyPrefix = `${target}:`
     return Object.entries(_entities.value)
       .filter(([key]) => key.startsWith(collectionKeyPrefix))
       .map(([_, entityObj]) => entityObj)
   }
 
-  function clearService(provider: string, service: string | number): void {
+  function clearService(target: ServiceIdentifier): void {
-    const serviceKeyPrefix = `${provider}:${service}:`
+    const serviceKeyPrefix = `${target}:`
     Object.keys(_entities.value)
       .filter((key) => key.startsWith(serviceKeyPrefix))
       .forEach((key) => {
@@ -86,8 +84,8 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
       })
   }
 
-  function clearCollection(provider: string, service: string | number, collection: string | number): void {
+  function clearCollection(target: CollectionIdentifier): void {
-    const collectionKeyPrefix = `${provider}:${service}:${collection}:`
+    const collectionKeyPrefix = `${target}:`
     Object.keys(_entities.value)
       .filter((key) => key.startsWith(collectionKeyPrefix))
       .forEach((key) => {
@@ -99,11 +97,23 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
     _entities.value = {}
   }
 
+  /**
+   * Merge externally-hydrated entities into the store (used by paginated node fetches)
+   */
+  function mergeMany(entities: EntityObject[]): void {
+    const hydrated: Record<string, EntityObject> = {}
+    entities.forEach((entityObj) => {
+      const key = identifierKey(entityObj.provider, entityObj.service, entityObj.collection, entityObj.identifier)
+      hydrated[key] = entityObj
+    })
+    _entities.value = { ..._entities.value, ...hydrated }
+  }
+
   // Actions
-  async function list(sources?: SourceSelector, filter?: ListFilter, sort?: ListSort, range?: ListRange): Promise<Record<string, EntityObject>> {
+  async function list(sources?: (ServiceIdentifier | CollectionIdentifier)[], filter?: ListFilter, sort?: ListSort, range?: ListRange): Promise<Record<string, EntityObject>> {
     transceiving.value = true
     try {
-      const response = await entityService.list({ sources, filter, sort, range })
+      const response = await entityService.listBulk({ sources, filter, sort, range })
 
       const hydrated: Record<string, EntityObject> = {}
       Object.entries(response).forEach(([providerId, providerServices]) => {
@@ -130,24 +140,13 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
   }
 
   async function fetch(
-    provider: string,
+    targets: EntityIdentifier[],
-    service: string | number,
-    collection: string | number,
-    identifiers: (string | number)[],
   ): Promise<Record<string, EntityObject>> {
     transceiving.value = true
     try {
-      const response = await entityService.fetch({ provider, service, collection, identifiers })
+      const response = await entityService.fetch({ targets })
-
+      _entities.value = { ..._entities.value, ...response }
-      const hydrated: Record<string, EntityObject> = {}
+      return response
-      Object.entries(response).forEach(([identifier, entityObj]) => {
-        const key = identifierKey(provider, service, collection, identifier)
-        hydrated[key] = entityObj
-        _entities.value[key] = entityObj
-      })
-
-      console.debug('[Documents Manager][Store] - Successfully fetched', Object.keys(hydrated).length, 'entities')
-      return hydrated
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to fetch entities:', error)
       throw error
@@ -156,10 +155,10 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
     }
   }
 
-  async function extant(sources: SourceSelector) {
+  async function extant(targets: (CollectionIdentifier | EntityIdentifier)[]) {
     transceiving.value = true
     try {
-      const response = await entityService.extant({ sources })
+      const response = await entityService.extant({ targets })
       console.debug('[Documents Manager][Store] - Successfully checked entity availability')
       return response
     } catch (error: any) {
@@ -171,15 +170,13 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
   }
 
   async function create(
-    provider: string,
+    target: CollectionIdentifier,
-    service: string | number,
-    collection: string | number,
     properties: DocumentInterface,
     options?: Record<string, unknown>,
   ): Promise<EntityObject> {
     transceiving.value = true
     try {
-      const response = await entityService.create({ provider, service, collection, properties, options })
+      const response = await entityService.create({ target, properties, options })
       const key = identifierKey(response.provider, response.service, response.collection, response.identifier)
       _entities.value[key] = response
 
@@ -194,15 +191,12 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
   }
 
   async function update(
-    provider: string,
+    target: EntityIdentifier,
-    service: string | number,
-    collection: string | number,
-    identifier: string | number,
     properties: DocumentInterface,
   ): Promise<EntityObject> {
     transceiving.value = true
     try {
-      const response = await entityService.update({ provider, service, collection, identifier, properties })
+      const response = await entityService.update({ target, properties })
       const key = identifierKey(response.provider, response.service, response.collection, response.identifier)
       _entities.value[key] = response
 
@@ -217,21 +211,22 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
   }
 
   async function remove(
-    provider: string,
+    targets: EntityIdentifier[],
-    service: string | number,
+  ): Promise<{ successes: EntityIdentifier[]; failures: EntityIdentifier[] }> {
-    collection: string | number,
-    identifier: string | number,
-  ): Promise<EntityDeleteResponse> {
     transceiving.value = true
     try {
-      const response = await entityService.delete({ provider, service, collection, identifier })
+      const response = await entityService.delete({ targets })
-      if (response.success) {
+      const successes: EntityIdentifier[] = []
-        const key = identifierKey(provider, service, collection, identifier)
+      const failures: EntityIdentifier[] = []
-        delete _entities.value[key]
+      for (const target of targets) {
+        if (response[target]?.disposition === 'deleted') {
+          delete _entities.value[target]
+          successes.push(target)
+        } else {
+          failures.push(target)
+        }
       }
-
+      return { successes, failures }
-      console.debug('[Documents Manager][Store] - Successfully deleted entity:', `${provider}:${service}:${collection}:${identifier}`)
-      return response
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to delete entity:', error)
       throw error
@@ -240,10 +235,10 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
     }
   }
 
-  async function delta(sources: SourceSelector): Promise<EntityDeltaResponse> {
+  async function delta(targets: (CollectionIdentifier | EntityIdentifier)[]): Promise<EntityDeltaResponse> {
     transceiving.value = true
     try {
-      const response = await entityService.delta({ sources })
+      const response = await entityService.delta({ targets })
 
       Object.entries(response).forEach(([provider, providerData]) => {
         if (providerData === false) return
@@ -273,14 +268,11 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
   }
 
   async function read(
-    provider: string,
+    target: EntityIdentifier,
-    service: string | number,
-    collection: string | number,
-    identifier: string | number,
   ): Promise<string | null> {
     transceiving.value = true
     try {
-      const response = await entityService.read({ provider, service, collection, identifier })
+      const response = await entityService.read({ target })
       return response.content
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to read entity:', error)
@@ -291,15 +283,12 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
   }
 
   async function write(
-    provider: string,
+    target: EntityIdentifier,
-    service: string | number,
-    collection: string | number,
-    identifier: string | number,
     content: string,
   ): Promise<number> {
     transceiving.value = true
     try {
-      const response = await entityService.write({ provider, service, collection, identifier, content, encoding: 'base64' })
+      const response = await entityService.write({ target, content, encoding: 'base64' })
       return response.bytesWritten
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to write entity:', error)
@@ -321,6 +310,7 @@ export const useEntitiesStore = defineStore('documentsEntitiesStore', () => {
     clearService,
     clearCollection,
     clearAll,
+    mergeMany,
     list,
     fetch,
     extant,

src/stores/nodesStore.ts

@@ -5,7 +5,9 @@
 import { computed, ref, readonly } from 'vue'
 import { defineStore } from 'pinia'
 import type {
-  SourceSelector,
+  CollectionIdentifier,
+  EntityIdentifier,
+  ServiceIdentifier,
   ListFilter,
   ListSort,
   ListRange,
@@ -15,6 +17,7 @@ import type {
 import { CollectionObject, EntityObject } from '../models'
 import { useCollectionsStore } from './collectionsStore'
 import { useEntitiesStore } from './entitiesStore'
+import { nodeService } from '../services/nodeService'
 
 export const ROOT_ID = '00000000-0000-0000-0000-000000000000'
 
@@ -45,8 +48,8 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
 
   function getServiceNodes(providerId: string, serviceId: string | number): NodeRecord[] {
     return [
-      ...collectionsStore.collectionsForService(providerId, serviceId),
+      ...collectionsStore.collectionsForService(`${providerId}:${serviceId}`),
-      ...entitiesStore.entitiesForService(providerId, serviceId),
+      ...entitiesStore.entitiesForService(`${providerId}:${serviceId}`),
     ]
   }
 
@@ -104,24 +107,13 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function fetchCollections(
-    providerId: string,
+    sources?: (ServiceIdentifier | CollectionIdentifier)[],
-    serviceId: string | number,
-    collectionId: string | number | null,
     filter?: ListFilter,
     sort?: ListSort,
   ): Promise<CollectionObject[]> {
     error.value = null
     try {
-      const sources: SourceSelector = {
+      return Object.values(await collectionsStore.list(sources, filter, sort))
-        [providerId]: {
-          [String(serviceId)]: collectionId === null
-            ? true
-            : { [String(collectionId)]: true },
-        },
-      }
-
-      await collectionsStore.list(sources, filter, sort)
-      return collectionsStore.collectionsForService(providerId, serviceId)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to fetch collections'
       throw e
@@ -129,47 +121,76 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function fetchEntities(
-    providerId: string,
+    sources?: (ServiceIdentifier | CollectionIdentifier)[],
-    serviceId: string | number,
-    collectionId: string | number | null,
     filter?: ListFilter,
     sort?: ListSort,
     range?: ListRange,
   ): Promise<EntityObject[]> {
     error.value = null
     try {
-      const sources: SourceSelector = {
+      return Object.values(await entitiesStore.list(sources, filter, sort, range))
-        [providerId]: {
-          [String(serviceId)]: collectionId === null
-            ? true
-            : { [String(collectionId)]: true },
-        },
-      }
-
-      await entitiesStore.list(sources, filter, sort, range)
-      return entitiesStore.entitiesForCollection(providerId, serviceId, collectionId)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to fetch entities'
       throw e
     }
   }
 
+  /**
+   * Fetch a unified node listing, optionally limited to a page by range.
+   */
   async function fetchNodes(
-    providerId: string,
+    sources?: (ServiceIdentifier | CollectionIdentifier)[],
-    serviceId: string | number,
-    parentId: string | number | null = ROOT_ID,
     filter?: ListFilter,
     sort?: ListSort,
     range?: ListRange,
-  ): Promise<NodeRecord[]> {
+    mode: 'reset' | 'append' = 'reset',
+  ): Promise<{ collections: CollectionObject[]; entities: EntityObject[]; isLastPage: boolean }> {
     error.value = null
     try {
-      await Promise.all([
+      const result = await nodeService.list({ sources, filter, sort, range })
-        fetchCollections(providerId, serviceId, parentId, filter, sort),
-        fetchEntities(providerId, serviceId, parentId, filter, sort, range),
-      ])
 
-      return getChildren(providerId, serviceId, parentId)
+      // Service selectors list the root; collection selectors list that folder.
+      // Omitted sources list roots across services, not every cached descendant.
+      const locations = new Map<string, { provider: string; service: string; parent: string }>()
+      if (sources?.length) {
+        for (const source of sources) {
+          const [provider, service, parent] = source.split(':')
+          const location = { provider: provider!, service: service!, parent: isRoot(parent) ? ROOT_ID : parent! }
+          locations.set(`${location.provider}:${location.service}:${location.parent}`, location)
+        }
+      } else {
+        for (const node of [...nodeList.value, ...result]) {
+          const location = { provider: node.provider, service: String(node.service), parent: ROOT_ID }
+          locations.set(`${location.provider}:${location.service}:${ROOT_ID}`, location)
+        }
+      }
+
+      // Replace only the selected locations, and only after the stream succeeds.
+      if (mode === 'reset') {
+        for (const { provider, service, parent } of locations.values()) {
+          const staleIds = getChildCollections(provider, service, parent)
+            .map((node): CollectionIdentifier => `${node.provider}:${node.service}:${node.identifier}`)
+          collectionsStore.removeMany(staleIds)
+          entitiesStore.clearCollection(`${provider}:${service}:${parent}`)
+        }
+      }
+
+      const pageCollections = result.filter((node): node is CollectionObject => node instanceof CollectionObject)
+      const pageEntities = result.filter((node): node is EntityObject => node instanceof EntityObject)
+
+      collectionsStore.mergeMany(pageCollections)
+      entitiesStore.mergeMany(pageEntities)
+
+      // The backend applies the range independently to each selected location.
+      const counts = new Map<string, number>()
+      for (const node of result) {
+        const parent = isRoot(node.collection) ? ROOT_ID : String(node.collection)
+        const key = `${node.provider}:${node.service}:${parent}`
+        counts.set(key, (counts.get(key) ?? 0) + 1)
+      }
+      const isLastPage = range === undefined || [...counts.values()].every(count => count < range.tally)
+
+      return { collections: pageCollections, entities: pageEntities, isLastPage }
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to fetch nodes'
       throw e
@@ -177,14 +198,12 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function createCollection(
-    providerId: string,
+    target: ServiceIdentifier | CollectionIdentifier,
-    serviceId: string | number,
-    parentCollectionId: string | number | null,
     properties: CollectionMutableProperties,
   ): Promise<CollectionObject> {
     error.value = null
     try {
-      return await collectionsStore.create(providerId, serviceId, parentCollectionId, properties)
+      return await collectionsStore.create(target, properties)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to create collection'
       throw e
@@ -192,14 +211,12 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function updateCollection(
-    providerId: string,
+    target: CollectionIdentifier,
-    serviceId: string | number,
-    identifier: string | number,
     properties: CollectionMutableProperties,
   ): Promise<CollectionObject> {
     error.value = null
     try {
-      return await collectionsStore.update(providerId, serviceId, identifier, properties)
+      return await collectionsStore.update(target, properties)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to update collection'
       throw e
@@ -207,13 +224,11 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function deleteCollection(
-    providerId: string,
+    target: CollectionIdentifier,
-    serviceId: string | number,
-    identifier: string | number,
   ): Promise<boolean> {
     error.value = null
     try {
-      const response = await collectionsStore.delete(providerId, serviceId, identifier)
+      const response = await collectionsStore.delete(target)
       return response.success
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to delete collection'
@@ -222,15 +237,13 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function createEntity(
-    providerId: string,
+    target: CollectionIdentifier,
-    serviceId: string | number,
-    collectionId: string | number,
     properties: DocumentInterface,
     options?: Record<string, unknown>,
   ): Promise<EntityObject> {
     error.value = null
     try {
-      return await entitiesStore.create(providerId, serviceId, collectionId, properties, options)
+      return await entitiesStore.create(target, properties, options)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to create entity'
       throw e
@@ -238,15 +251,12 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function updateEntity(
-    providerId: string,
+    target: EntityIdentifier,
-    serviceId: string | number,
-    collectionId: string | number,
-    identifier: string | number,
     properties: DocumentInterface,
   ): Promise<EntityObject> {
     error.value = null
     try {
-      return await entitiesStore.update(providerId, serviceId, collectionId, identifier, properties)
+      return await entitiesStore.update(target, properties)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to update entity'
       throw e
@@ -254,15 +264,12 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function deleteEntity(
-    providerId: string,
+    target: EntityIdentifier,
-    serviceId: string | number,
-    collectionId: string | number,
-    identifier: string | number,
   ): Promise<boolean> {
     error.value = null
     try {
-      const response = await entitiesStore.delete(providerId, serviceId, collectionId, identifier)
+      const response = await entitiesStore.delete([target])
-      return response.success
+      return response.successes.includes(target)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to delete entity'
       throw e
@@ -270,14 +277,11 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function readEntity(
-    providerId: string,
+    target: EntityIdentifier,
-    serviceId: string | number,
-    collectionId: string | number,
-    identifier: string | number,
   ): Promise<string | null> {
     error.value = null
     try {
-      return await entitiesStore.read(providerId, serviceId, collectionId, identifier)
+      return await entitiesStore.read(target)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to read entity'
       throw e
@@ -285,15 +289,12 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   async function writeEntity(
-    providerId: string,
+    target: EntityIdentifier,
-    serviceId: string | number,
-    collectionId: string | number,
-    identifier: string | number,
     content: string,
   ): Promise<number> {
     error.value = null
     try {
-      return await entitiesStore.write(providerId, serviceId, collectionId, identifier, content)
+      return await entitiesStore.write(target, content)
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to write entity'
       throw e
@@ -301,8 +302,8 @@ export const useNodesStore = defineStore('documentsNodesStore', () => {
   }
 
   function clearServiceNodes(providerId: string, serviceId: string | number): void {
-    collectionsStore.clearService(providerId, serviceId)
+    collectionsStore.clearService(`${providerId}:${serviceId}`)
-    entitiesStore.clearService(providerId, serviceId)
+    entitiesStore.clearService(`${providerId}:${serviceId}`)
   }
 
   function clearNodes(): void {

src/stores/providersStore.ts

@@ -6,7 +6,7 @@ import { ref, computed, readonly } from 'vue'
 import { defineStore } from 'pinia'
 import { providerService } from '../services'
 import { ProviderObject } from '../models/provider'
-import type { SourceSelector } from '../types'
+import type { ProviderIdentifier } from '../types'
 
 export const useProvidersStore = defineStore('documentsProvidersStore', () => {
   // State
@@ -54,10 +54,10 @@ export const useProvidersStore = defineStore('documentsProvidersStore', () => {
    * 
    * @returns Promise with provider object list keyed by provider identifier
    */
-  async function list(sources?: SourceSelector): Promise<Record<string, ProviderObject>> {
+  async function list(targets?: ProviderIdentifier[]): Promise<Record<string, ProviderObject>> {
     transceiving.value = true
     try {
-      const providers = await providerService.list({ sources })
+      const providers = await providerService.list({ targets })
 
       // Merge retrieved providers into state
       _providers.value = { ..._providers.value, ...providers }
@@ -82,7 +82,7 @@ export const useProvidersStore = defineStore('documentsProvidersStore', () => {
   async function fetch(identifier: string): Promise<ProviderObject> {
     transceiving.value = true
     try {
-      const provider = await providerService.fetch({ identifier })
+      const provider = await providerService.fetch({ target: identifier })
 
       // Merge fetched provider into state
       _providers.value[provider.identifier] = provider
@@ -100,14 +100,14 @@ export const useProvidersStore = defineStore('documentsProvidersStore', () => {
   /**
    * Retrieve provider availability status for a given source selector
    * 
-   * @param sources - source selector to check availability for
+   * @param targets - provider identifiers to check availability for
    * 
    * @returns Promise with provider availability status
    */
-  async function extant(sources: SourceSelector) {
+  async function extant(targets: ProviderIdentifier[]) {
     transceiving.value = true
     try {
-      const response = await providerService.extant({ sources })
+      const response = await providerService.extant({ targets })
 
       Object.entries(response).forEach(([providerId, providerStatus]) => {
         if (providerStatus === false) {
@@ -115,7 +115,7 @@ export const useProvidersStore = defineStore('documentsProvidersStore', () => {
         }
       })
 
-      console.debug('[Documents Manager][Store] - Successfully checked', sources ? Object.keys(sources).length : 0, 'providers')
+      console.debug('[Documents Manager][Store] - Successfully checked', targets ? targets.length : 0, 'providers')
       return response
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to check providers:', error)

src/stores/servicesStore.ts

@@ -7,7 +7,7 @@ import { defineStore } from 'pinia'
 import { serviceService } from '../services'
 import { ServiceObject } from '../models/service'
 import type {
-  SourceSelector,
+  ServiceIdentifier,
   ServiceInterface,
 } from '../types'
 
@@ -76,14 +76,14 @@ export const useServicesStore = defineStore('documentsServicesStore', () => {
   /**
    * Retrieve all or specific services, optionally filtered by source selector
    * 
-   * @param sources - optional source selector
+   * @param targets - optional service identifiers
    * 
    * @returns Promise with service object list keyed by provider and service identifier
    */
-  async function list(sources?: SourceSelector): Promise<Record<string, ServiceObject>> {
+  async function list(targets?: ServiceIdentifier[]): Promise<Record<string, ServiceObject>> {
     transceiving.value = true
     try {
-      const response = await serviceService.list({ sources })
+      const response = await serviceService.list({ targets })
 
       // Flatten nested structure: provider-id: { service-id: object } -> "provider-id:service-id": object
       const services: Record<string, ServiceObject> = {}
@@ -137,16 +137,16 @@ export const useServicesStore = defineStore('documentsServicesStore', () => {
   /**
    * Retrieve service availability status for a given source selector
    * 
-   * @param sources - source selector to check availability for
+   * @param targets - service identifiers to check availability for
    * 
    * @returns Promise with service availability status
    */
-  async function extant(sources: SourceSelector) {
+  async function extant(targets: ServiceIdentifier[]) {
     transceiving.value = true
     try {
-      const response = await serviceService.extant({ sources })
+      const response = await serviceService.extant({ targets })
       
-      console.debug('[Documents Manager][Store] - Successfully checked', sources ? Object.keys(sources).length : 0, 'services')
+      console.debug('[Documents Manager][Store] - Successfully checked', targets ? targets.length : 0, 'services')
       return response
     } catch (error: any) {
       console.error('[Documents Manager][Store] - Failed to check services:', error)

src/types/collection.ts

@@ -1,7 +1,7 @@
 /**
  * Collection type definitions
  */
-import type { ListFilter, ListSort, SourceSelector } from './common';
+import type { CollectionIdentifier, ListFilter, ListSort, ServiceIdentifier } from './common';
 
 
 export interface CollectionModelInterface extends Omit<CollectionInterface, '@type' | 'created' | 'modified'> {
@@ -46,7 +46,7 @@ export interface CollectionPropertiesInterface extends CollectionMutableProperti
  * Collection list
  */
 export interface CollectionListRequest {
-  sources?: SourceSelector;
+  sources?: (ServiceIdentifier | CollectionIdentifier)[];
   filter?: ListFilter;
   sort?: ListSort;
 }
@@ -63,18 +63,16 @@ export interface CollectionListResponse {
  * Collection fetch
  */
 export interface CollectionFetchRequest {
-  provider: string;
+  targets: CollectionIdentifier[];
-  service: string | number;
-  collection: string | number;
 }
 
-export interface CollectionFetchResponse extends CollectionInterface {}
+export type CollectionFetchResponse = Record<CollectionIdentifier, CollectionInterface>;
 
 /**
  * Collection extant
  */
 export interface CollectionExtantRequest {
-  sources: SourceSelector;
+  targets: CollectionIdentifier[];
 }
 
 export interface CollectionExtantResponse {
@@ -89,10 +87,9 @@ export interface CollectionExtantResponse {
  * Collection create
  */
 export interface CollectionCreateRequest {
-  provider: string;
+  target: ServiceIdentifier | CollectionIdentifier; // Service root or parent collection
-  service: string | number;
-  collection?: string | number | null; // Parent Collection Identifier
   properties: CollectionMutableProperties;
+  options?: Record<string, unknown>;
 }
 
 export interface CollectionCreateResponse extends CollectionInterface {}
@@ -101,9 +98,7 @@ export interface CollectionCreateResponse extends CollectionInterface {}
  * Collection modify
  */
 export interface CollectionUpdateRequest {
-  provider: string;
+  target: CollectionIdentifier;
-  service: string | number;
-  identifier: string | number;
   properties: CollectionMutableProperties;
 }
 
@@ -113,26 +108,23 @@ export interface CollectionUpdateResponse extends CollectionInterface {}
  * Collection delete
  */
 export interface CollectionDeleteRequest {
-  provider: string;
+  target: CollectionIdentifier;
-  service: string | number;
-  identifier: string | number;
   options?: {
     force?: boolean; // Whether to force delete even if collection is not empty
   };
 }
 
 export interface CollectionDeleteResponse {
-  success: boolean;
+  disposition: 'deleted' | 'moved';
+  mutation?: CollectionInterface;
 }
 
 /**
  * Collection copy
  */
 export interface CollectionCopyRequest {
-  provider: string;
+  source: CollectionIdentifier;
-  service: string;
+  target?: CollectionIdentifier | null; // Destination parent (absent for root)
-  identifier: string;
-  location?: string | null;
 }
 
 export interface CollectionCopyResponse extends CollectionInterface {}
@@ -141,10 +133,8 @@ export interface CollectionCopyResponse extends CollectionInterface {}
  * Collection move
  */
 export interface CollectionMoveRequest {
-  provider: string;
+  source: CollectionIdentifier;
-  service: string;
+  target?: CollectionIdentifier | null; // Destination parent (absent for root)
-  identifier: string;
-  location?: string | null;
 }
 
 export interface CollectionMoveResponse extends CollectionInterface {}

src/types/common.ts

@@ -44,33 +44,57 @@ export interface ApiErrorResponse {
 export type ApiResponse<T = any> = ApiSuccessResponse<T> | ApiErrorResponse;
 
 /**
- * Selector for targeting specific providers, services, collections, or entities in list or extant operations.
+ * Stream control start line.
- * 
- * Example usage:
- * {
- *   "provider1": true, // Select all services/collections/entities under provider1
- *   "provider2": {
- *     "serviceA": true, // Select all collections/entities under serviceA of provider2
- *     "serviceB": {
- *       "collectionX": true, // Select all entities under collectionX of serviceB of provider2
- *       "collectionY": [1, 2, 3] // Select entities with identifiers 1, 2, and 3 under collectionY of serviceB of provider2
- *     }
- *   }
- * }
  */
-export type SourceSelector = {
+export interface ApiStreamStartResponse {
-  [provider: string]: boolean | ServiceSelector;
+  type: 'control';
-};
+  status: 'start';
+  version: number;
+  transaction: string;
+  total?: number;
+}
 
-export type ServiceSelector = {
+/**
-  [service: string]: boolean | CollectionSelector;
+ * Stream control end line
-};
+ */
+export interface ApiStreamEndResponse {
+  type: 'control';
+  status: 'end';
+  total: number;
+}
 
-export type CollectionSelector = {
+/**
-  [collection: string | number]: boolean | EntitySelector;
+ * Stream error line
-};
+ */
+export interface ApiStreamErrorResponse {
+  type: 'error';
+  message: string;
+}
 
-export type EntitySelector = (string | number)[];
+export interface ApiStreamDataResponse<T = any> {
+  type: 'data';
+  data: T;
+}
+
+/**
+ * Shared stream control lines
+ */
+export type ApiStreamResponse<T = any> =
+  | ApiStreamStartResponse
+  | ApiStreamEndResponse
+  | ApiStreamErrorResponse
+  | ApiStreamDataResponse<T>;
+
+/**
+ * Identifiers for targeting specific providers, services, collections, or entities in list or extant operations.
+ *
+ * Operations accept flat arrays of colon-separated identifier strings, e.g.
+ * ["default:personal:00000000-0000-0000-0000-000000000000", "default:personal:folder1:file1"].
+ */
+export type ProviderIdentifier = `${string}`;
+export type ServiceIdentifier = `${string}:${string}`;
+export type CollectionIdentifier = `${string}:${string}:${string | number}`;
+export type EntityIdentifier = `${string}:${string}:${string}:${string | number}`;
 
 
 /**

src/types/entity.ts

@@ -1,7 +1,7 @@
 /**
  * Entity type definitions
  */
-import type { ListFilter, ListRange, ListSort, SourceSelector } from './common';
+import type { CollectionIdentifier, EntityIdentifier, ListFilter, ListRange, ListSort, ServiceIdentifier } from './common';
 import type { DocumentInterface, DocumentModelInterface } from './document';
 
 /**
@@ -25,11 +25,21 @@ export interface EntityInterface<T = DocumentInterface> {
   properties: T;
 }
 
+/**
+ * Entity mutation result (delete/move/copy operations)
+ */
+export interface EntityMutationResult {
+  disposition: 'deleted' | 'moved' | 'copied' | 'error';
+  destination?: CollectionIdentifier | null;
+  mutation?: EntityIdentifier;
+  error?: string;
+}
+
 /**
  * Entity list
  */
 export interface EntityListRequest {
-  sources?: SourceSelector;
+  sources?: (ServiceIdentifier | CollectionIdentifier)[];
   filter?: ListFilter;
   sort?: ListSort;
   range?: ListRange;
@@ -49,10 +59,7 @@ export interface EntityListResponse {
  * Entity fetch
  */
 export interface EntityFetchRequest {
-  provider: string;
+  targets: EntityIdentifier[];
-  service: string | number;
-  collection: string | number;
-  identifiers: (string | number)[];
 }
 
 export interface EntityFetchResponse {
@@ -63,7 +70,7 @@ export interface EntityFetchResponse {
  * Entity extant
  */
 export interface EntityExtantRequest {
-  sources: SourceSelector;
+  targets: (CollectionIdentifier | EntityIdentifier)[];
 }
 
 export interface EntityExtantResponse {
@@ -80,9 +87,7 @@ export interface EntityExtantResponse {
  * Entity create
  */
 export interface EntityCreateRequest<T = DocumentInterface> {
-  provider: string;
+  target: CollectionIdentifier;
-  service: string | number;
-  collection: string | number;
   properties: T;
   options?: Record<string, unknown>;
 }
@@ -93,10 +98,7 @@ export interface EntityCreateResponse<T = DocumentInterface> extends EntityInter
  * Entity update
  */
 export interface EntityUpdateRequest<T = DocumentInterface> {
-  provider: string;
+  target: EntityIdentifier;
-  service: string | number;
-  collection: string | number;
-  identifier: string | number;
   properties: T;
 }
 
@@ -106,21 +108,18 @@ export interface EntityUpdateResponse<T = DocumentInterface> extends EntityInter
  * Entity delete
  */
 export interface EntityDeleteRequest {
-  provider: string;
+  targets: EntityIdentifier[];
-  service: string | number;
-  collection: string | number;
-  identifier: string | number;
 }
 
 export interface EntityDeleteResponse {
-  success: boolean;
+  [identifier: string]: EntityMutationResult;
 }
 
 /**
  * Entity delta
  */
 export interface EntityDeltaRequest {
-  sources: SourceSelector;
+  targets: (CollectionIdentifier | EntityIdentifier)[];
 }
 
 export interface EntityDeltaResponse {
@@ -140,36 +139,31 @@ export interface EntityDeltaResponse {
  * Entity copy
  */
 export interface EntityCopyRequest {
-  provider: string;
+  target: CollectionIdentifier;
-  service: string | number;
+  sources: EntityIdentifier[];
-  collection: string | number;
-  identifier: string | number;
-  destination?: string | null;
 }
 
-export interface EntityCopyResponse<T = DocumentInterface> extends EntityInterface<T> {}
+export interface EntityCopyResponse {
+  [identifier: string]: EntityMutationResult;
+}
 
 /**
  * Entity move
  */
 export interface EntityMoveRequest {
-  provider: string;
+  target: CollectionIdentifier;
-  service: string | number;
+  sources: EntityIdentifier[];
-  collection: string | number;
-  identifier: string | number;
-  destination?: string | null;
 }
 
-export interface EntityMoveResponse<T = DocumentInterface> extends EntityInterface<T> {}
+export interface EntityMoveResponse {
+  [identifier: string]: EntityMutationResult;
+}
 
 /**
  * Entity read content
  */
 export interface EntityReadRequest {
-  provider: string;
+  target: EntityIdentifier;
-  service: string | number;
-  collection: string | number;
-  identifier: string | number;
 }
 
 export interface EntityReadResult {
@@ -183,10 +177,7 @@ export type EntityReadResponse = EntityReadResult;
  * Entity write content
  */
 export interface EntityWriteRequest {
-  provider: string;
+  target: EntityIdentifier;
-  service: string | number;
-  collection: string | number;
-  identifier: string | number;
   content: string;
   encoding?: 'base64';
 }

src/types/index.ts

@@ -3,5 +3,5 @@ export type * from './provider';
 export type * from './service';
 export type * from './collection';
 export type * from './entity';
-export type * from './document';
 export type * from './node';
+export type * from './document';

src/types/node.ts

@@ -1,37 +1,23 @@
 /**
- * Node types for combined operations
+ * Node (unified collections + entities) type definitions
  */
+import type { CollectionIdentifier, ListFilter, ListRange, ListSort, ServiceIdentifier } from './common';
+import type { CollectionInterface } from './collection';
+import type { EntityInterface } from './entity';
 
-import type { CollectionInterface } from "./collection";
+/**
-import type { ApiResponse, ListFilterCondition, ListRange, ListSort } from "./common";
+ * Node list
-import type { EntityInterface } from "./entity";
+ */
-
 export interface NodeListRequest {
-  provider: string;
+  sources?: (ServiceIdentifier | CollectionIdentifier)[];
-  service: string;
+  filter?: ListFilter;
-  location?: string | null;
+  sort?: ListSort;
-  recursive?: boolean;
+  range?: ListRange;
-  filter?: ListFilterCondition | null;
-  sort?: ListSort | null;
-  range?: ListRange | null;
 }
 
-export type NodeListResponse = ApiResponse<CollectionInterface | EntityInterface>;
+export type NodeInterface =
+  | (Omit<CollectionInterface, '@type'> & { '@type': 'document:collection' })
+  | (Omit<EntityInterface, '@type'> & { '@type': 'document:entity' });
 
-export interface NodeDeltaRequest {
+/** Payload of each data frame in the node.list NDJSON stream. */
-  provider: string;
+export type NodeListResponse = NodeInterface;
-  service: string;
-  location?: string | null;
-  signature: string;
-  recursive?: boolean;
-  detail?: 'ids' | 'full';
-}
-
-export interface NodeDeltaResult {
-  added: string[];
-  modified: string[];
-  removed: string[];
-  signature: string;
-}
-
-export type NodeDeltaResponse = ApiResponse<NodeDeltaResult>;

src/types/provider.ts

@@ -1,7 +1,7 @@
 /**
  * Provider type definitions
  */
-import type { SourceSelector } from "./common";
+import type { ProviderIdentifier } from "./common";
 
 /**
  * Provider capabilities
@@ -32,7 +32,7 @@ export interface ProviderInterface {
  * Provider list
  */
 export interface ProviderListRequest {
-  sources?: SourceSelector;
+  targets?: ProviderIdentifier[];
 }
 
 export interface ProviderListResponse {
@@ -43,7 +43,7 @@ export interface ProviderListResponse {
  * Provider fetch
  */
 export interface ProviderFetchRequest {
-  identifier: string;
+  target: ProviderIdentifier;
 }
 
 export interface ProviderFetchResponse extends ProviderInterface {}
@@ -52,7 +52,7 @@ export interface ProviderFetchResponse extends ProviderInterface {}
  * Provider extant
  */
 export interface ProviderExtantRequest {
-  sources: SourceSelector;
+  targets: ProviderIdentifier[];
 }
 
 export interface ProviderExtantResponse {

src/types/service.ts

@@ -1,7 +1,7 @@
 /**
  * Service type definitions
  */
-import type { SourceSelector, ListFilterComparisonOperator } from './common';
+import type { ServiceIdentifier as ServiceIdentifierString, ListFilterComparisonOperator } from './common';
 
 /**
  * Service capabilities
@@ -66,7 +66,7 @@ export interface ServiceInterface {
  * Service list
  */
 export interface ServiceListRequest {
-  sources?: SourceSelector;
+  targets?: ServiceIdentifierString[];
 }
 
 export interface ServiceListResponse {
@@ -89,7 +89,7 @@ export interface ServiceFetchResponse extends ServiceInterface {}
  * Service extant
  */
 export interface ServiceExtantRequest {
-  sources: SourceSelector;
+  targets: ServiceIdentifierString[];
 }
 
 export interface ServiceExtantResponse {

src/utils/fileHelpers.ts

@@ -0,0 +1,71 @@
+import { EntityObject } from '@/models/entity'
+
+/**
+ * Get the appropriate icon for a file based on its MIME type
+ */
+export function getFileIcon(entity: EntityObject): string {
+  const mime = entity.properties.mime || ''
+  if (!mime) return 'mdi-file'
+  if (mime.startsWith('image/')) return 'mdi-file-image'
+  if (mime.startsWith('video/')) return 'mdi-file-video'
+  if (mime.startsWith('audio/')) return 'mdi-file-music'
+  if (mime.startsWith('text/')) return 'mdi-file-document'
+  if (mime === 'application/pdf') return 'mdi-file-pdf-box'
+  if (mime.includes('zip') || mime.includes('tar') || mime.includes('compressed')) return 'mdi-folder-zip'
+  if (mime.includes('word') || mime.includes('document')) return 'mdi-file-word'
+  if (mime.includes('excel') || mime.includes('spreadsheet')) return 'mdi-file-excel'
+  if (mime.includes('powerpoint') || mime.includes('presentation')) return 'mdi-file-powerpoint'
+  return 'mdi-file'
+}
+
+/**
+ * Format file size in human readable format
+ */
+export function formatSize(bytes: number): string {
+  const safeBytes = Number.isFinite(bytes) ? bytes : 0
+  if (safeBytes === 0) return '0 B'
+  const k = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
+  const i = Math.floor(Math.log(safeBytes) / Math.log(k))
+  return parseFloat((safeBytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
+}
+
+/**
+ * Format date string to localized format
+ */
+export function formatDate(value: Date | string | null | undefined): string {
+  if (!value) return '—'
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) return '—'
+  return date.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  })
+}
+
+/**
+ * Get upload status icon
+ */
+export function getUploadStatusIcon(status: string): string {
+  switch (status) {
+    case 'pending': return 'mdi-clock-outline'
+    case 'uploading': return 'mdi-loading mdi-spin'
+    case 'completed': return 'mdi-check-circle'
+    case 'error': return 'mdi-alert-circle'
+    default: return 'mdi-file'
+  }
+}
+
+/**
+ * Get upload status color
+ */
+export function getUploadStatusColor(status: string): string {
+  switch (status) {
+    case 'pending': return 'grey'
+    case 'uploading': return 'primary'
+    case 'completed': return 'success'
+    case 'error': return 'error'
+    default: return 'grey'
+  }
+}

tests/js/unit/base.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+
+describe('Basic Tests', () => {
+  it('should perform basic assertion', () => {
+    expect(true).toBe(true)
+  })
+
+  it('should test array operations', () => {
+    const array = ['foo', 'bar', 'baz']
+
+    expect(array).toHaveLength(3)
+    expect(array).toContain('bar')
+    expect(array[0]).toBe('foo')
+  })
+
+  it('should test string operations', () => {
+    const string = 'Hello, World!'
+
+    expect(string).toContain('World')
+    expect(string.length).toBe(13)
+  })
+
+  it('should test object operations', () => {
+    const obj = { foo: 'bar', count: 42 }
+
+    expect(obj).toHaveProperty('foo')
+    expect(obj.foo).toBe('bar')
+    expect(obj.count).toBeGreaterThan(40)
+  })
+})

tests/js/vitest.config.ts

@@ -0,0 +1,31 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig, configDefaults } from 'vitest/config'
+import path from 'path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, '../../src'),
+      '@KTXC': path.resolve(__dirname, '../../../../core/src'),
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    exclude: [...configDefaults.exclude, 'e2e/**'],
+    root: fileURLToPath(new URL('../../', import.meta.url)),
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'tests/',
+        '**/*.d.ts',
+        '**/*.config.*',
+        '**/dist/**',
+      ],
+    },
+  },
+})

tests/php/Integration/BaseTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace KTXT\DocumentsManager\Tests\Integration;
+
+use PHPUnit\Framework\TestCase;
+
+class BaseTest extends TestCase
+{
+    public function testBasicAssertion(): void
+    {
+        $this->assertTrue(true);
+    }
+
+    public function testArrayOperations(): void
+    {
+        $array = ['foo' => 'bar'];
+
+        $this->assertArrayHasKey('foo', $array);
+        $this->assertEquals('bar', $array['foo']);
+    }
+
+    public function testStringOperations(): void
+    {
+        $string = 'Hello, World!';
+
+        $this->assertStringContainsString('World', $string);
+        $this->assertEquals(13, strlen($string));
+    }
+}

tests/php/Unit/BaseTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace KTXT\DocumentsManager\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+
+class BaseTest extends TestCase
+{
+    public function testBasicAssertion(): void
+    {
+        $this->assertTrue(true);
+    }
+
+    public function testArrayOperations(): void
+    {
+        $array = ['foo' => 'bar'];
+
+        $this->assertArrayHasKey('foo', $array);
+        $this->assertEquals('bar', $array['foo']);
+    }
+
+    public function testStringOperations(): void
+    {
+        $string = 'Hello, World!';
+
+        $this->assertStringContainsString('World', $string);
+        $this->assertEquals(13, strlen($string));
+    }
+}

tests/php/bootstrap.php

@@ -0,0 +1,17 @@
+<?php
+
+require dirname(__DIR__, 2).'/lib/vendor/autoload.php';
+
+// When this module is checked out inside a full server (server/modules/<handle>,
+// as it is in CI and in this monorepo checkout), also load the server's own
+// core/shared autoloader so tests can reference framework (KTXC/KTXF) types.
+// Standalone module checkouts without a server alongside them skip this.
+define('SERVER_ROOT', dirname(__DIR__, 4));
+$serverAutoload = SERVER_ROOT . '/vendor/autoload.php';
+if (is_file($serverAutoload)) {
+    require $serverAutoload;
+}
+
+if (isset($_SERVER['APP_DEBUG']) && $_SERVER['APP_DEBUG']) {
+    umask(0000);
+}

tests/php/phpunit.xml

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- https://phpunit.readthedocs.io/en/latest/configuration.html -->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../lib/vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         failOnDeprecation="true"
+         failOnNotice="true"
+         failOnWarning="true"
+         bootstrap="bootstrap.php"
+         cacheDirectory="../../.phpunit.cache"
+>
+    <php>
+        <ini name="display_errors" value="1" />
+        <ini name="error_reporting" value="-1" />
+        <server name="APP_ENV" value="test" force="true" />
+        <server name="SHELL_VERBOSITY" value="-1" />
+    </php>
+
+    <testsuites>
+        <testsuite name="Unit Tests">
+            <directory>Unit</directory>
+        </testsuite>
+        <testsuite name="Integration Tests">
+            <directory>Integration</directory>
+        </testsuite>
+    </testsuites>
+
+    <source ignoreSuppressionOfDeprecations="true"
+            ignoreIndirectDeprecations="true"
+            restrictNotices="true"
+            restrictWarnings="true"
+    >
+        <include>
+            <directory>../../lib</directory>
+        </include>
+    </source>
+
+    <extensions>
+    </extensions>
+</phpunit>

tsconfig.app.json

@@ -15,5 +15,5 @@
       "@KTXC/*": ["../../core/src/*"]
     }
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx"]
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
 }