Merge branch 'main' into patch-1

Author: computerscienceiscool

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -4,6 +4,14 @@ labels:
   - "stage: triage"
   - "type: bug"
 body:
+  - type: markdown
+    attributes:
+      value: |
+        Community contributions start with issues. Pull requests are limited to repository collaborators.
+        [Read why and how to contribute](https://github.com/superdoc/docx-editor/blob/main/CONTRIBUTING.md).
+        Report suspected security vulnerabilities privately through [GitHub Security Advisories](https://github.com/superdoc/docx-editor/security/advisories/new), not in a public issue.
+        Remove confidential information from any files, screenshots, or logs you share.
+
   - type: textarea
     id: description
     attributes:
@@ -19,7 +27,7 @@ body:
     id: reproduction
     attributes:
       label: Steps to reproduce
-      description: How can we reproduce this? Include a sample .docx file if possible.
+      description: How can we reproduce this? Include a small reproduction or synthetic .docx file if possible.
       placeholder: |
         1. Open the attached .docx file
         2. Scroll to page 2
@@ -55,3 +63,11 @@ body:
     attributes:
       label: Additional context
       description: Screenshots, error messages, browser console output, or anything else that helps.
+
+  - type: textarea
+    id: investigation
+    attributes:
+      label: Investigation or proposed fix
+      description: If you’ve already investigated, share your findings, test results, or a link to a patch. You don’t need to write a fix to report a bug.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,11 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/superdoc/docx-editor/security/advisories/new
+    about: Report suspected vulnerabilities privately. Do not include vulnerability details in public issues.
   - name: Questions & Discussion
     url: https://discord.com/invite/b9UuaZRyaB
     about: Ask questions or chat with the community on Discord
   - name: Want to contribute?
     url: https://github.com/superdoc/docx-editor/blob/main/CONTRIBUTING.md
-    about: Check out our contributing guide to get started
+    about: Community contributions start with issues. Read why and how to help.

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -4,6 +4,14 @@ labels:
   - "stage: triage"
   - "type: feature"
 body:
+  - type: markdown
+    attributes:
+      value: |
+        Community contributions start with issues. Pull requests are limited to repository collaborators.
+        [Read why and how to contribute](https://github.com/superdoc/docx-editor/blob/main/CONTRIBUTING.md).
+        Report suspected security vulnerabilities privately through [GitHub Security Advisories](https://github.com/superdoc/docx-editor/security/advisories/new), not in a public issue.
+        Remove confidential information from any files, screenshots, or logs you share.
+
   - type: textarea
     id: problem
     attributes:

.github/workflows/examples.yml

@@ -42,6 +42,7 @@ jobs:
               - 'packages/document-api/**'
               - 'packages/react/**'
               - 'packages/superdoc/**'
+              - 'packages/sdk/**'
               - 'scripts/check-examples.mjs'
               - 'scripts/__tests__/check-examples.test.mjs'
               - 'scripts/check-go-links.mjs'
@@ -95,6 +96,10 @@ jobs:
         if: needs.detect.outputs.examples == 'true'
         run: pnpm --filter @superdoc/react run build
 
+      - name: Build SDK example dependencies
+        if: needs.detect.outputs.examples == 'true'
+        run: pnpm run generate:all && pnpm --filter @superdoc/sdk run build
+
       - name: Install Chromium
         if: needs.detect.outputs.examples == 'true'
         run: pnpm --filter @superdoc-examples/vanilla exec playwright install --with-deps chromium

.github/workflows/notify-orbit.yml

@@ -1,27 +1,42 @@
 # Contributing to SuperDoc
 
-Thanks for helping out. Bug reports, docs, examples, tests, and code are all
-welcome.
+Community contributions start with an issue. Pull requests are limited to
+repository collaborators.
+
+We’ve found that reviewing and integrating external PRs often takes more time
+than implementing a fix from a clear report. Even a small change can affect
+other editor behavior that requires broader context to verify. We want to
+explain this upfront so you don’t spend time on a PR we can’t accept.
 
 ## Ways to contribute
 
-**Report a rendering bug.** Open a `.docx` in SuperDoc, compare it with
-Microsoft Word, and if they differ,
-[file an issue](https://github.com/superdoc/docx-editor/issues/new?template=bug-report.yml)
-with the file attached. A reproduction document is the single most useful thing
-you can send.
+Report suspected security vulnerabilities privately through
+[GitHub Security Advisories](https://github.com/superdoc/docx-editor/security/advisories/new),
+as described in our [security policy](SECURITY.md). Do not include vulnerability
+details in public issues.
 
-**Improve the docs.** They live in `apps/docs/` and ship to
-[docs.superdoc.dev](https://docs.superdoc.dev). Run `pnpm run dev:docs` to
-preview your changes.
+Bug reports, feature requests, documentation feedback, and technical
+investigations are welcome. Search [open issues](https://github.com/superdoc/docx-editor/issues)
+first, then [open an issue](https://github.com/superdoc/docx-editor/issues/new/choose)
+with what you’re trying to do, what happened, and what you expected.
+
+For bugs, include your SuperDoc version and a small reproduction if possible.
+For rendering differences, include a sample `.docx` and screenshots showing
+SuperDoc and Microsoft Word. Use synthetic or redacted documents without
+confidential information.
 
-**Add an example.** Keep it runnable and focused on one documented outcome. All examples live in `examples/`.
+Already investigated or written a fix? Include your findings, test results, or
+a link to the patch in the issue. That context helps us understand the problem
+and develop a solution. You don’t need to write code to contribute.
 
-**Fix a bug or add a feature.** Start with
-[good first issues](https://github.com/superdoc/docx-editor/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-or [help wanted](https://github.com/superdoc/docx-editor/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
-For anything large, open an issue first so we can agree on the approach before
-you write code.
+## Working on the code
+
+The instructions below cover local development and PRs for repository
+collaborators. You can also use them to reproduce a problem locally.
+
+Documentation lives in `apps/docs/` and ships to
+[docs.superdoc.dev](https://docs.superdoc.dev). Run `pnpm run dev:docs` to
+preview it. Runnable examples live in `examples/`.
 
 ## Choose a branch
 
@@ -129,6 +144,16 @@ message, since the release version is derived from it:
 
 A local Git hook checks the message format before the commit lands.
 
+### Peer dependency changes
+
+Peer dependencies are a compatibility contract with applications that install a published SuperDoc package. Any authored change to that contract requires manual review. CI compares the effective packed ranges, including `catalog:` and `workspace:` resolutions, with the pull request base and leaves a review comment when they differ.
+
+Use a `feat:` title for a backward-compatible expansion such as widening a tested range, adding an optional peer, or making a required peer optional. Use a breaking `!` title for a change that removes accepted versions, adds a required peer, makes an optional peer required, or removes or replaces a peer contract. The protected check fails when the configured release planner would produce less than the required release impact; a breaking peer change cannot merge until the release path can produce the required major release.
+
+The existing exact `superdoc` dependency and peer in `@superdoc/react` are a release-managed exception: the version stamper moves both pins only as part of the coordinated React and SuperDoc release train after protected PR checks. Changing the pin form, optionality, or compatibility policy is still an authored contract change and follows the rules above.
+
+Read the [package compatibility policy](https://docs.superdoc.dev/resources/package-compatibility) before changing `peerDependencies`, `peerDependenciesMeta`, or a catalog entry used by a peer.
+
 Before you open the PR:
 
 - [ ] `pnpm test` passes

CONTRIBUTING.md

@@ -85,9 +85,14 @@ package state through one collaboration model.
 
 ## Contributing
 
-Read the [contributing guide](https://github.com/superdoc/docx-editor/blob/main/CONTRIBUTING.md),
-browse [open issues](https://github.com/superdoc/docx-editor/issues), or join
-[Discord](https://discord.com/invite/b9UuaZRyaB).
+Community contributions start with an
+[issue](https://github.com/superdoc/docx-editor/issues/new/choose). Bug reports,
+feature requests, and technical investigations are welcome. Pull requests are
+limited to repository collaborators. Read the
+[contributing guide](https://github.com/superdoc/docx-editor/blob/main/CONTRIBUTING.md)
+for why and how to help, or join [Discord](https://discord.com/invite/b9UuaZRyaB)
+for questions. Report suspected security vulnerabilities privately through
+[GitHub Security Advisories](https://github.com/superdoc/docx-editor/security/advisories/new).
 
 ## Contributors
 

README.md

@@ -0,0 +1,53 @@
+# Collaboration demo
+
+The docs own a staging-only Durable Object service in [collaboration-server](./collaboration-server/README.md).
+It uses the pinned SuperDoc runtime and Yjs WebSockets. Rooms expire after 15 minutes; only use sample text.
+The local Hocuspocus tutorial and access-control demo remain separate. Builds without a server URL show the illustration and local walkthrough.
+
+## Local Hocuspocus server
+
+From `superdoc/public`, start the server:
+
+```bash
+VITE_SUPERDOC_EXAMPLE_PORT_OFFSET=100 pnpm --dir examples/collaboration exec tsx server.ts
+```
+
+In another terminal, start docs on an available port:
+
+```bash
+NEXT_PUBLIC_COLLABORATION_DEMO_URL=ws://127.0.0.1:1334 pnpm --filter @superdoc/docs exec next dev --port 3015
+```
+
+Open `/editor/collaboration/connect-two-editors`. The demo connects automatically and starts collapsed. Expand it, edit either pane, and check the other. Alex's cursor is blue; Sam's is green.
+Restart asks before discarding edits and creates a new room. Unmount destroys both editor instances.
+
+## Access checks
+
+Start the separate localhost-only access server:
+
+```bash
+pnpm --dir examples/collaboration exec tsx docs-access-server.ts
+```
+
+Add `NEXT_PUBLIC_COLLABORATION_ACCESS_DEMO_URL=ws://127.0.0.1:1335` to the docs command and restart it.
+Open `/editor/collaboration/control-room-access`. Alex opens automatically; Sam may join, Taylor may not.
+The credentials are public fixtures, not a login system. Rooms stay in memory.
+
+The pinned runtime reports rejected authentication as a generic connection error. This demo's `/access-result`
+endpoint confirms actual server rejections using a random connection-attempt ID, not the selected name.
+Results expire after one minute and the server retains at most 256. An unavailable result stays a connection error.
+This endpoint is demo infrastructure, not a SuperDoc API or a production authorization pattern.
+
+## Browser checks
+
+Run the focused browser tests against that page:
+
+```bash
+DOCS_COLLABORATION_TEST_URL=http://127.0.0.1:3015/editor/collaboration/connect-two-editors VITE_SUPERDOC_EXAMPLE_PORT_OFFSET=200 pnpm --dir examples/collaboration test tests/docs-embed.spec.ts
+```
+
+The test harness's own example servers use the offset of 200; the embedded demo connects to 1334.
+
+Before hosting, add server-enforced expiration, room-scoped access, connection and payload limits, and abuse protection.
+Do not publish a build containing a localhost URL. No continuous connection-health indicator is claimed: initial readiness
+is not ongoing connectivity. After startup errors the sample stays visible; only explicit restart discards edits.

apps/docs/COLLABORATION-DEMO.md

@@ -79,7 +79,7 @@
   --color-fd-secondary-foreground: var(--sd-text-primary);
 }
 
-.dark {
+:root.dark {
   --sd-gradient-from: #60a5fa;
   --sd-gradient-to: #c084fc;
   --sd-background: #0b0c10;

apps/docs/app/global.css

@@ -0,0 +1,2 @@
+.wrangler/
+.dev.vars*