Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ dist/
/vendor/
/vendor-bin/*/vendor
webpack-stats.json
__pycache__/

# js folder, to be updated wth --force
/js
Expand Down
1 change: 1 addition & 0 deletions appinfo/routes.php
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@

return [
'routes' => [
['name' => 'Embedding#get', 'url' => '/embedding', 'verb' => 'GET'],
/** @see Controller\AttachmentController::getAttachmentList() */
['name' => 'Attachment#getAttachmentList', 'url' => '/attachments', 'verb' => 'POST'],
/** @see Controller\AttachmentController::insertAttachmentFile() */
Expand Down
2 changes: 2 additions & 0 deletions composer/composer/autoload_classmap.php
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
'OCA\\Text\\Context\\UnauthorizedFileContext' => $baseDir . '/../lib/Context/UnauthorizedFileContext.php',
'OCA\\Text\\Controller\\AiController' => $baseDir . '/../lib/Controller/AiController.php',
'OCA\\Text\\Controller\\AttachmentController' => $baseDir . '/../lib/Controller/AttachmentController.php',
'OCA\\Text\\Controller\\EmbeddingController' => $baseDir . '/../lib/Controller/EmbeddingController.php',
'OCA\\Text\\Controller\\ISessionAwareController' => $baseDir . '/../lib/Controller/ISessionAwareController.php',
'OCA\\Text\\Controller\\NavigationController' => $baseDir . '/../lib/Controller/NavigationController.php',
'OCA\\Text\\Controller\\PublicSessionController' => $baseDir . '/../lib/Controller/PublicSessionController.php',
Expand Down Expand Up @@ -96,6 +97,7 @@
'OCA\\Text\\Service\\InitialStateProvider' => $baseDir . '/../lib/Service/InitialStateProvider.php',
'OCA\\Text\\Service\\LockService' => $baseDir . '/../lib/Service/LockService.php',
'OCA\\Text\\Service\\NotificationService' => $baseDir . '/../lib/Service/NotificationService.php',
'OCA\\Text\\Service\\RuntimeManifest' => $baseDir . '/../lib/Service/RuntimeManifest.php',
'OCA\\Text\\Service\\SessionService' => $baseDir . '/../lib/Service/SessionService.php',
'OCA\\Text\\Service\\WorkspaceService' => $baseDir . '/../lib/Service/WorkspaceService.php',
'OCA\\Text\\TextFile' => $baseDir . '/../lib/TextFile.php',
Expand Down
2 changes: 2 additions & 0 deletions composer/composer/autoload_static.php
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ class ComposerStaticInitText
'OCA\\Text\\Context\\UnauthorizedFileContext' => __DIR__ . '/..' . '/../lib/Context/UnauthorizedFileContext.php',
'OCA\\Text\\Controller\\AiController' => __DIR__ . '/..' . '/../lib/Controller/AiController.php',
'OCA\\Text\\Controller\\AttachmentController' => __DIR__ . '/..' . '/../lib/Controller/AttachmentController.php',
'OCA\\Text\\Controller\\EmbeddingController' => __DIR__ . '/..' . '/../lib/Controller/EmbeddingController.php',
'OCA\\Text\\Controller\\ISessionAwareController' => __DIR__ . '/..' . '/../lib/Controller/ISessionAwareController.php',
'OCA\\Text\\Controller\\NavigationController' => __DIR__ . '/..' . '/../lib/Controller/NavigationController.php',
'OCA\\Text\\Controller\\PublicSessionController' => __DIR__ . '/..' . '/../lib/Controller/PublicSessionController.php',
Expand Down Expand Up @@ -111,6 +112,7 @@ class ComposerStaticInitText
'OCA\\Text\\Service\\InitialStateProvider' => __DIR__ . '/..' . '/../lib/Service/InitialStateProvider.php',
'OCA\\Text\\Service\\LockService' => __DIR__ . '/..' . '/../lib/Service/LockService.php',
'OCA\\Text\\Service\\NotificationService' => __DIR__ . '/..' . '/../lib/Service/NotificationService.php',
'OCA\\Text\\Service\\RuntimeManifest' => __DIR__ . '/..' . '/../lib/Service/RuntimeManifest.php',
'OCA\\Text\\Service\\SessionService' => __DIR__ . '/..' . '/../lib/Service/SessionService.php',
'OCA\\Text\\Service\\WorkspaceService' => __DIR__ . '/..' . '/../lib/Service/WorkspaceService.php',
'OCA\\Text\\TextFile' => __DIR__ . '/..' . '/../lib/TextFile.php',
Expand Down
86 changes: 86 additions & 0 deletions docs/native-embedding.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
<!--
SPDX-FileCopyrightText: 2026 Nextcloud contributors
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Experimental native embedding compatibility

This development branch provides compatibility metadata for a bundled native
Text client. It is not a supported public embedding API. The paired native
implementation lives on [the Collectives collaboration branch](https://github.com/juliusknorr/collectives-swiftui/tree/feat/text-collaboration).

After building Text and regenerating its Composer class map, generate metadata:

```sh
python3 tools/native-embedding.py --source-revision "$(git rev-parse HEAD)"
```

Archives without Git metadata must supply the full pinned commit explicitly.
The generated `js/native-embedding.json` is ignored and must be deployed
atomically alongside the corresponding code. Authenticated `GET /embedding`
returns its six fields: format, Text version, source revision, code digest,
session API and update encoding. Missing or invalid metadata, including a
mismatch with `appinfo/info.xml`, yields HTTP 503. Responses use `no-store`.

The digest fingerprints sorted paths and SHA-256 hashes of `.mjs`, `.css`, `.php`
and `.xml` files in `js`, `css`, `lib`, `appinfo` and `composer/composer`. JSON
metadata excludes itself. The native bundle must use exactly the same manifest.
This trusts a coherent server deployment; manually editing same-version code
without regenerating metadata invalidates that guarantee. It avoids hashing
roughly 14 MB of JavaScript on every request.

Session middleware optionally accepts `runtimeDigest`. A supplied incompatible
digest rejects create/sync/push/save with HTTP 412 before session handling. Native
clients always supply it. Browser clients without it retain their existing
behavior. Close remains available for cleanup after an upgrade and does not
prove that the document was saved.

Run the parser and generator tests without a server:

```sh
vendor/bin/phpunit --no-configuration --do-not-cache-result tests/unit/Service/RuntimeManifestTest.php
python3 -m unittest discover -s tests/native_embedding
```

The paired native WebKit smoke suite exercises the authenticated endpoint,
matching and incompatible session operations, collaboration, reconnect and save
confirmation against a real server. Transport injection and a durable editor
drain/save/close contract remain separate follow-up work.

## Small public editor seam

`createCollaborativeEditor({ el, context, sessionTransport })` accepts a per-editor
transport with the existing `openContext`, `sync`, `push`, `save` and `close`
shapes. The default browser transport is unchanged. Injected transports use
in-memory state instead of IndexedDB; the host owns account/file binding,
credentials, storage, request limits and timeouts. Public shares are not supported
by the injected transport yet. Browser sendBeacon never bypasses it.

Two wrapper methods expose the required editor state without component accessors:

```ts
const editor = await createCollaborativeEditor({ el, context, sessionTransport })
const checkpoint = editor.exportState()
const drained = await editor.drain()
```

The snapshot contains a full base64 Yjs update, state vector, Markdown, version,
context and collaboration base ETag, without session credentials. `drain()`
freezes user input, waits for queued/in-flight provider updates, and returns a
snapshot; failures reject. It does not persist, save, or close the session.
After session rejection, `exportState()` still returns recovery state with the
original base ETag; it does not require an active connection.

The existing `onUpdate({ markdown, local })` callback reports document changes,
including toolbar and programmatic edits. `local` distinguishes local edits
(including undo/redo) from remote updates and initial Yjs content.

The host must persist recovery state, control file-save requests, verify the saved
version, close through its own transport, and fetch canonical DAV Markdown/ETag
before releasing ownership and destroying the editor. Automatic save requests
still go through the injected transport and can be deferred by the host.

`playwright/e2e/embedding.spec.ts` uses the existing Text fixtures to test two
embedded clients, Unicode convergence, valid Yjs export and drain acknowledgements.
The larger demo and checkpoint/save/close coordinator live in the
[native app repository](https://github.com/juliusknorr/collectives-swiftui/tree/feat/text-collaboration/dev/text-collaboration/embedding).
Per-edit durability and cold-restart recovery remain host-side follow-up work.
33 changes: 33 additions & 0 deletions lib/Controller/EmbeddingController.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
<?php

declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2026 Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OCA\Text\Controller;

use OCA\Text\Service\RuntimeManifest;
use OCP\AppFramework\ApiController;
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
use OCP\AppFramework\Http\DataResponse;
use OCP\IRequest;

class EmbeddingController extends ApiController {
public function __construct(
string $appName,
IRequest $request,
private RuntimeManifest $manifest,
) {
parent::__construct($appName, $request);
}

#[NoAdminRequired]
public function get(): DataResponse {
$manifest = $this->manifest->get();
$response = new DataResponse($manifest ?? [], $manifest === null ? 503 : 200);
$response->addHeader('Cache-Control', 'no-store');
return $response;
}
}
6 changes: 6 additions & 0 deletions lib/Middleware/SessionMiddleware.php
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,12 @@ public function beforeController(Controller $controller, string $methodName): vo
return;
}

$runtimeDigest = $this->request->getParam('runtimeDigest');
if ($runtimeDigest !== null && $methodName !== 'close'
&& (!is_string($runtimeDigest) || !(new \OCA\Text\Service\RuntimeManifest())->matches($runtimeDigest))) {
throw new InvalidDocumentBaseVersionEtagException();
}

$reflectionMethod = new \ReflectionMethod($controller, $methodName);

if (!empty($reflectionMethod->getAttributes(RequireDocumentSessionOrUserOrShareToken::class))) {
Expand Down
52 changes: 52 additions & 0 deletions lib/Service/RuntimeManifest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
<?php

declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2026 Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OCA\Text\Service;

class RuntimeManifest {

public function __construct(
private string $manifestPath = __DIR__ . '/../../js/native-embedding.json',
private string $versionPath = __DIR__ . '/../../appinfo/info.xml',
) {
}

public function get(): ?array {
if (!is_file($this->manifestPath) || !is_file($this->versionPath)) {
return null;
}
try {
$manifest = json_decode(file_get_contents($this->manifestPath), true, 32, JSON_THROW_ON_ERROR);

Check failure on line 24 in lib/Service/RuntimeManifest.php

View workflow job for this annotation

GitHub Actions / static-psalm-analysis

PossiblyFalseArgument

lib/Service/RuntimeManifest.php:24:28: PossiblyFalseArgument: Argument 1 of json_decode cannot be false, possibly string value expected (see https://psalm.dev/104)
} catch (\JsonException) {
return null;
}
if (!is_array($manifest)
|| ($manifest['format'] ?? null) !== 1
|| ($manifest['sessionAPI'] ?? null) !== 'context-v1'
|| ($manifest['updateEncoding'] ?? null) !== 'yjs-sync-v1') {
return null;
}
foreach (['sourceRevision' => 40, 'codeDigest' => 64] as $key => $length) {
if (!is_string($manifest[$key] ?? null) || !preg_match('/^[a-f0-9]{' . $length . '}$/D', $manifest[$key])) {
return null;
}
}
$info = simplexml_load_string(file_get_contents($this->versionPath), options: LIBXML_NONET);

Check failure on line 39 in lib/Service/RuntimeManifest.php

View workflow job for this annotation

GitHub Actions / static-psalm-analysis

PossiblyFalseArgument

lib/Service/RuntimeManifest.php:39:33: PossiblyFalseArgument: Argument 1 of simplexml_load_string cannot be false, possibly string value expected (see https://psalm.dev/104)
if ($info === false || ($manifest['textVersion'] ?? null) !== (string)$info->version) {
return null;
}
return array_intersect_key($manifest, array_flip([
'format', 'textVersion', 'sourceRevision', 'codeDigest', 'sessionAPI', 'updateEncoding',
]));
}

public function matches(string $digest): bool {
$manifest = $this->get();
return $manifest !== null && hash_equals($manifest['codeDigest'], $digest);
}
}
107 changes: 107 additions & 0 deletions playwright/e2e/embedding.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
/**
* SPDX-FileCopyrightText: 2026 Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

import type { SessionTransport } from '../../src/services/SessionTransport.ts'
import type { TextEditorEmbed } from '../../src/TextEditorEmbed.ts'

import { expect } from '@playwright/test'
import { randomUUID } from 'node:crypto'
import * as Y from 'yjs'
import { test } from '../support/fixtures/upload-file.ts'

declare global {
interface Window {
embeddingInstances: TextEditorEmbed[]
embeddingHost: (peer: number, operation: string, data: object) => Promise<any>
}
}

test.use({ fileName: `embedding-seam-${randomUUID()}.md`, fileContent: '# Embedded Text\n\nShared text.\n' })

test('public transport joins two editors, exports Yjs state and acknowledges drain', async ({ page, file, baseURL }) => {
type Session = { documentId: string, sessionId: number, sessionToken: string, baseVersionEtag: string }
const sessions = new Map<number, Session>()
const operations = new Set<string>()
const sanitize = (value: unknown): unknown => {
if (Array.isArray(value)) {
return value.map(sanitize)
}
if (!value || typeof value !== 'object') {
return value
}
return Object.fromEntries(Object.entries(value).map(([key, data]) => [key, ['token', 'sessiontoken'].includes(key.toLowerCase()) ? 'host-owned' : sanitize(data)]))
}
await page.exposeBinding('embeddingHost', async ({ frame }, peer, operation, data) => {
expect(frame).toBe(page.mainFrame())
expect([0, 1]).toContain(peer)
expect(['create', 'sync', 'push', 'save', 'close']).toContain(operation)
operations.add(operation)
const session = sessions.get(peer)
const path = operation === 'create' ? `file/${file.id}/create` : `${session!.documentId}/${operation}`
const response = await page.request.fetch(new URL(`apps/text/session/${path}`, baseURL).href, {
method: operation === 'create' ? 'PUT' : 'POST',
data: { ...data, ...session },
})
expect(response.ok()).toBe(true)
const result = await response.json()
if (operation === 'create') {
sessions.set(peer, { documentId: result.document.id, sessionId: result.session.id, sessionToken: result.session.token, baseVersionEtag: result.document.baseVersionEtag })
}
return sanitize(result)
})
await page.goto('apps/files')
const root = await page.evaluate(() => (window as unknown as { OC: { appswebroots: { text: string } } }).OC.appswebroots.text)
await page.addScriptTag({ url: `${root}/js/text-editor.mjs`, type: 'module' })
await page.evaluate(async (id) => {
window.embeddingInstances = []
for (const peer of [0, 1]) {
const el = document.createElement('div')
el.id = `embedding-${peer}`
Object.assign(el.style, { position: 'fixed', top: '0', left: `${peer * 50}%`, width: '50%', height: '100%', zIndex: '10000', background: 'white' })
document.body.append(el)
const sessionTransport: SessionTransport = {
async openContext() {
const data = await window.embeddingHost(peer, 'create', {})
return { data, connection: { documentId: data.document.id, sessionId: data.session.id, sessionToken: data.session.token, baseVersionEtag: data.document.baseVersionEtag, filePath: '' } }
},
async sync(_connection, data) { return { data: await window.embeddingHost(peer, 'sync', data) } },
async push(_connection, data) { return { data: await window.embeddingHost(peer, 'push', data) } },
async save(_connection, data) { return { data: await window.embeddingHost(peer, 'save', data) } },
async close() { return window.embeddingHost(peer, 'close', {}) },
}
window.embeddingInstances.push(await window.OCA.Text.createCollaborativeEditor({
el,
context: { type: 'file', id },
autofocus: false,
sessionTransport,
}))
}
}, file.id)
try {
for (const peer of [0, 1]) {
const editor = page.locator(`#embedding-${peer} .ProseMirror[contenteditable=true]`)
await expect(editor).toContainText('Shared text.', { timeout: 15_000 })
await editor.click()
await editor.press('ControlOrMeta+End')
await editor.pressSequentially([' Client-α', ' Client-日本語'][peer])
}
await expect.poll(() => page.evaluate(() => window.embeddingInstances.every((editor) => {
const markdown = editor.exportState().markdown
return markdown.includes('Client-α') && markdown.includes('Client-日本語')
})), { timeout: 15_000 }).toBe(true)
const states = await page.evaluate(() => Promise.all(window.embeddingInstances.map((editor) => editor.drain())))
for (const state of states) {
const doc = new Y.Doc()
Y.applyUpdate(doc, Buffer.from(state.documentState, 'base64'))
expect([...Y.encodeStateVector(doc)]).toEqual([...Buffer.from(state.stateVector, 'base64')])
expect(state.markdown).toContain('Client-α')
doc.destroy()
}
await expect(page.locator('#embedding-0 .ProseMirror')).toHaveAttribute('contenteditable', 'false')
expect([...operations]).toEqual(expect.arrayContaining(['create', 'sync', 'push']))
} finally {
await page.evaluate(() => window.embeddingInstances.forEach((editor) => editor.destroy()))
}
})
17 changes: 17 additions & 0 deletions src/TextEditorEmbed.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import type { EventHandler } from '@nextcloud/event-bus'
import type { Editor } from '@tiptap/core'
import type { Node } from '@tiptap/pm/model'
import type { App, ComponentInstance, h, Reactive } from 'vue'
import type { EmbeddingState } from './types/EmbeddingState.ts'
import type CollaborativeEditorApp from './views/CollaborativeEditorApp.vue'
import type MarkdownContentEditorApp from './views/MarkdownContentEditorApp.vue'

Expand All @@ -17,6 +18,8 @@ interface EditorComponent {
editor: Editor
setContent: (content: string, options?: { addToHistory: boolean | undefined }) => void
save?: () => void
exportState?: () => EmbeddingState
drain?: () => Promise<EmbeddingState>
}

type DataType = Reactive<{
Expand Down Expand Up @@ -50,6 +53,20 @@ export class TextEditorEmbed {
this.#app.unmount()
}

exportState(): EmbeddingState {
if (!this.#editorComponent.exportState) {
throw new Error('A collaborative editor is required')
}
return this.#editorComponent.exportState()
}

drain(): Promise<EmbeddingState> {
if (!this.#editorComponent.drain) {
throw new Error('A collaborative editor is required')
}
return this.#editorComponent.drain()
}

setContent(content: string) {
// Update reactive prop for MarkdownContentEditor
this.#data.content = content
Expand Down
Loading
Loading