2.4.0: external Y.Doc/provider rejected as v1 API by the v2 constructor — no public collab config where save() can resolve (with #3876)

[buroa]

Summary

In superdoc@2.4.0, supplying an external Y.Doc + provider pair (the externally-typed collaboration surface) is rejected fail-closed by the v2 constructor before any editor becomes ready, with collaboration-v1-config-unsupported:

SuperDoc v2 cannot use modules.collaboration because it is the SuperDoc v1
collaboration API. SuperDoc did not attach the provider or change the document.
Configure Document.v2Collaboration with a v2 room instead.

Combined with #3876 (on the v2 path, save() never resolves because shell documents never receive a Y.Doc), this means 2.4.0 has no public collaboration configuration in which await superdoc.save() can complete:

• v2 collaboration: accepted, but save() hangs (v2 collaboration: SuperDoc.save() never resolves — shell documents get no Y.Doc on the v2 path (2.4.0) #3876).
• External Y.Doc/provider (modules.collaboration): rejected by the v2 constructor at startup.

The package still ships the external-provider types, and the bundle retains the external attachment path (dist/superdoc.es.js:43491-43503 is the only site that assigns a Y.Doc to shell documents), but the public constructor refuses the only configuration surface that supplies the pair.

Reproduction

1. Construct SuperDoc with an external HocuspocusProvider + Y.Doc passed through the document entry and modules.collaboration, pointed at a self-hosted Hocuspocus server.
2. The constructor fails closed with collaboration-v1-config-unsupported before the first editor is ready; the provider is never attached.

Questions

1. What is the supported configuration for self-hosted collaboration in 2.x where save() can resolve — is there a v2-compatible way to supply or reach the document's Y.Doc?
2. If external collaboration is intentionally retired for 2.x, could the constructor error and the retained external types/documentation be reconciled, and v2 collaboration: SuperDoc.save() never resolves — shell documents get no Y.Doc on the v2 path (2.4.0) #3876 be treated as the remaining blocker for self-hosted v2?

Environment

• superdoc@2.4.0 (npm latest at time of filing)
• Self-hosted Hocuspocus server, Chromium via Playwright harness

[jelkes1]

Thanks for the detailed report here. @mattConnHarbour and @caiopizzol have been digging into this and will follow up tomorrow with an update.

[linear-code]

SD-4170

[caio-pizzol]

Hey @buroa! Thanks for reporting this.

I was able to reproduce the issue: SuperDoc.save() does not resolve when using v2 collaboration in superdoc@2.4.0.

Collaboration updates still sync through the configured provider, but there is currently no supported way to request and wait for an immediate persistence flush. We’re working on a fix and will also clarify what save() guarantees.