Merge main into stable

.github/workflows/ci-catalog.yml

@@ -0,0 +1,111 @@
+name: CI Catalog
+
+# Metadata-only gate for the demo and example catalog. Fast by design: it
+# validates manifests and the published-slug baseline without building or
+# browser-testing anything, so a naming mistake fails in under a minute.
+#
+# AIDEV-NOTE: this runs on every pull request rather than filtering with
+# `on.paths`, because it is a required check. A path-filtered workflow never
+# reports on an unrelated change, and a required check that never reports
+# blocks the pull request forever. `detect` decides whether the real work is
+# needed and `validate` reports either way, matching ci-examples.
+
+on:
+  pull_request:
+  merge_group:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-catalog-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      catalog: ${{ steps.set.outputs.catalog }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        id: filter
+        if: github.event_name == 'pull_request'
+        with:
+          filters: |
+            catalog:
+              - '.github/workflows/ci-catalog.yml'
+              - 'demos/manifest.json'
+              - 'examples/manifest.json'
+              # The published-slug baseline is half of the permanence check.
+              # Without it here, a pull request editing only the baseline runs
+              # no validation, and a later one could drop the matching manifest
+              # slug against an already weakened baseline.
+              - 'go-links/published-slugs.json'
+              - 'scripts/validate-examples-demos.ts'
+              - 'scripts/__tests__/validate-examples-demos-slug.test.mjs'
+
+      - id: set
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            echo "catalog=${{ steps.filter.outputs.catalog }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "catalog=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  catalog:
+    needs: detect
+    if: needs.detect.outputs.catalog == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: package.json
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.13
+
+      # No dependency install. Both commands below import only node: builtins,
+      # verified by running them with node_modules absent. Installing would add
+      # the only network step in this job for no gain, and the local lane skips
+      # it too, so the two cannot drift.
+
+      - name: Validate demo and example metadata
+        run: pnpm run check:examples-demos
+
+      - name: Test the metadata validator
+        run: pnpm run check:examples-demos:tests
+
+  validate:
+    name: CI Catalog / validate
+    if: always()
+    needs: [detect, catalog]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check results
+        run: |
+          if [[ "${{ needs.detect.result }}" != "success" ]]; then
+            echo "Detect job did not succeed (result: ${{ needs.detect.result }})."
+            exit 1
+          fi
+          if [[ "${{ needs.detect.outputs.catalog }}" != "true" ]]; then
+            echo "Catalog CI skipped: no relevant paths changed."
+            exit 0
+          fi
+          if [[ "${{ needs.catalog.result }}" != "success" ]]; then
+            echo "Catalog validation did not succeed (result: ${{ needs.catalog.result }})."
+            exit 1
+          fi

.github/workflows/deploy-go-links.yml

@@ -0,0 +1,79 @@
+name: Deploy Go Links
+
+# Publishes go.superdoc.dev, the permanent URL for every demo and example
+# carrying a `slug` in the manifests.
+#
+# The redirect table is built by linkkeeper, pinned to an exact version, from
+# the two manifests in this repository. Everything it needs is here, so there is
+# no second repository to keep in sync and no cross-repository dispatch that
+# could silently fail to fire.
+#
+# This lives here rather than in Orbit's export workflow on purpose: the export
+# pushes directly to this repository's `main`, so by the time this runs the
+# manifests are already public and `github.sha` is the exported commit. Orbit's
+# export is proof-gated and fail-closed; it should not also own deployments
+# downstream of it.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.github/workflows/deploy-go-links.yml'
+      - 'demos/manifest.json'
+      - 'examples/manifest.json'
+      - 'go-links/**'
+  schedule:
+    # 06:17 UTC. Off the hour on purpose: scheduled jobs at :00 queue behind
+    # everyone else's.
+    - cron: '17 6 * * *'
+  workflow_dispatch:
+
+# Read-only. Deploy credentials reach this job through secrets, which are not
+# available to pull_request_target and must never be exposed to one.
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-go-links
+  cancel-in-progress: false
+
+env:
+  # Pinned deliberately. An unpinned tool could change the published redirect
+  # table without anything in this repository changing, which is a strange
+  # property for a service whose promise is that URLs do not move.
+  LINKKEEPER_VERSION: 0.1.0
+
+jobs:
+  deploy:
+    # Fail-closed on the ref. `workflow_dispatch` lets a caller pick any branch,
+    # and this job holds the credentials that publish go.superdoc.dev, so an
+    # unmerged branch must not be able to deploy redirects.
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: go-links
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      # A published link that 404s reads as a deleted example, which is worse
+      # than never having published it. Manifests drift, so every destination is
+      # resolved for real before anything goes live.
+      - name: Check every destination resolves
+        run: npx --yes "linkkeeper@${LINKKEEPER_VERSION}" check --commit "${GITHUB_SHA}"
+
+      - name: Build the redirect table
+        run: npx --yes "linkkeeper@${LINKKEEPER_VERSION}" build --commit "${GITHUB_SHA}"
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: go-links
+          command: pages deploy ./dist --project-name=linkkeeper --branch=main

apps/docs/document-api/features/content-controls.mdx

@@ -68,7 +68,7 @@ for (const control of items) {
 
 Or keep clauses **single-use and governed**: a clause is either in the contract or available to add from a library, and it appears once. Track inclusion by querying `contentControls.list` for the `sectionId` instead of comparing versions, and lock each placed clause (`contentLocked`) so its prose is fixed. A clause can also carry nested smart fields - inline controls inside the block - that fill from one place.
 
-The [`demos/contract-templates`](https://github.com/superdoc/docx-editor/tree/main/demos/contract-templates) runtime composes the single-use approach: a clause library that inserts locked block clauses (some with nested fields), each filled by tag from a form.
+The [`demos/contract-templates`](https://go.superdoc.dev/contract-templates) runtime composes the single-use approach: a clause library that inserts locked block clauses (some with nested fields), each filled by tag from a form.
 
 ## Why `tag`, not `nodeId`
 
@@ -159,7 +159,7 @@ For runtime synchronization with backing data, drive the control directly with `
   <Card title="Tagged inline text example" icon="text-cursor-input" href="https://github.com/superdoc/docx-editor/tree/main/examples/document-api/content-controls/tagged-inline-text">
     The smallest content-control workflow. `create.contentControl` + `selectByTag` + `text.setValue`.
   </Card>
-  <Card title="Contract templates demo" icon="file-text" href="https://github.com/superdoc/docx-editor/tree/main/demos/contract-templates">
+  <Card title="Contract templates demo" icon="file-text" href="https://go.superdoc.dev/contract-templates">
     Smart fields and versioned sections composed into one runtime app.
   </Card>
   <Card title="Template Builder" icon="layout-template" href="/solutions/template-builder/introduction">

apps/docs/editor/built-in-ui/comments.mdx

@@ -746,7 +746,7 @@ onCommentsUpdate: ({ type, comment, meta }) => {
 <Card
   title="Comments Example"
   icon="github"
-  href="https://github.com/superdoc/docx-editor/tree/main/examples/editor/built-in-ui/comments"
+  href="https://go.superdoc.dev/comments"
 >
   Runnable example: threaded comments with resolve workflow and event log
 </Card>

apps/docs/editor/built-in-ui/toolbar.mdx

@@ -611,7 +611,7 @@ const superdoc = new SuperDoc({
 <Card
   title="Custom Toolbar Example"
   icon="external-link"
-  href="https://github.com/superdoc/docx-editor/tree/main/examples/editor/built-in-ui/toolbar"
+  href="https://go.superdoc.dev/toolbar"
 >
   Runnable example: custom button groups, excluded items, and a custom clear-formatting button
 </Card>

apps/docs/editor/built-in-ui/track-changes.mdx

@@ -482,7 +482,7 @@ superdoc.activeEditor.commands.toggleTrackChangesShowFinal();
 <Card
   title="Track Changes Example"
   icon="git-compare"
-  href="https://github.com/superdoc/docx-editor/tree/main/examples/editor/built-in-ui/track-changes"
+  href="https://go.superdoc.dev/track-changes"
 >
   Runnable example: mode switching, accept and reject, comments sidebar, DOCX import and export.
 </Card>

apps/docs/editor/custom-ui/content-controls.mdx

@@ -95,6 +95,6 @@ Putting it together into a fillable template, the way the contract-templates dem
 
 ## See also
 
-- [Contract templates demo](https://github.com/superdoc/docx-editor/tree/main/demos/contract-templates) - a full custom contract-template UI: a field + clause library, custom SDT styling, locks, form-driven values, events, insert, and export.
+- [Contract templates demo](https://go.superdoc.dev/contract-templates) - a full custom contract-template UI: a field + clause library, custom SDT styling, locks, form-driven values, events, insert, and export.
 - [Configuration](/editor/superdoc/configuration) - the `modules.contentControls.chrome` option.
 - [Document API: content controls](/document-api/features/content-controls) - read and change controls.

apps/docs/editor/custom-ui/controller-setup.mdx

@@ -18,7 +18,7 @@ The controller exposes the same surface the React hooks consume. Domain handles,
 ## Install
 
 ```bash
-pnpm add superdoc
+pnpm add superdoc@1
 ```
 
 ## Create the controller

apps/docs/editor/custom-ui/react-setup.mdx

@@ -12,7 +12,7 @@ Not using React? See [Controller setup](/editor/custom-ui/controller-setup) for
 ## Install
 
 ```bash
-pnpm add superdoc @superdoc-dev/react
+pnpm add superdoc@1 @superdoc-dev/react@1
 ```
 
 ## Wire the provider

apps/docs/editor/react/overview.mdx

@@ -11,7 +11,7 @@ Building your own toolbar, comments sidebar, or review panel? Pair `<SuperDocEdi
 ## Installation
 
 ```bash
-npm install @superdoc-dev/react
+npm install superdoc@1 @superdoc-dev/react@1
 ```
 
 <Note>

apps/docs/editor/superdoc/configuration.mdx

@@ -112,7 +112,7 @@ new SuperDoc({
     - `viewing` - Read-only display
     - `suggesting` - Track changes enabled
   </Expandable>
-  <Info>See the [Track Changes module](/editor/built-in-ui/track-changes) for accept/reject commands, the Document API, and configuration. The [runnable example](https://github.com/superdoc/docx-editor/tree/main/examples/editor/built-in-ui/track-changes) shows a complete workflow.</Info>
+  <Info>See the [Track Changes module](/editor/built-in-ui/track-changes) for accept/reject commands, the Document API, and configuration. The [runnable example](https://go.superdoc.dev/track-changes) shows a complete workflow.</Info>
 </ParamField>
 
 <ParamField path="comments" type="Object">

apps/docs/getting-started/fonts.mdx

@@ -76,7 +76,7 @@ Use `fonts.resolveAssetUrl` instead for signed or versioned URLs.
 The `superdoc` CDN build ships no fonts: by default the toolbar shows the baseline and documents render with system fonts. To load the reviewed pack, add the `@superdoc-dev/fonts` browser build and pass the `SuperDocFonts` global.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/superdoc@1/dist/superdoc.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/@superdoc-dev/fonts/dist/superdoc-fonts.min.js"></script>
 <script>
   new SuperDoc({

apps/docs/getting-started/frameworks/angular.mdx

@@ -11,7 +11,7 @@ Requires Angular 17.2+. `viewChild()` and `input()` are stable from Angular 19;
 ## Install
 
 ```bash
-npm install superdoc @superdoc-dev/fonts
+npm install superdoc@1 @superdoc-dev/fonts
 ```
 
 ## Basic setup
@@ -137,4 +137,4 @@ export class UploadEditorComponent {
 
 - [Configuration](/editor/superdoc/configuration) - Full configuration options
 - [Methods](/editor/superdoc/methods) - All available methods
-- [Angular Example](https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/angular) - Working example on GitHub
+- [Angular Example](https://go.superdoc.dev/angular) - Working example on GitHub

apps/docs/getting-started/frameworks/laravel.mdx

@@ -11,7 +11,7 @@ SuperDoc works with Laravel + Blade + Vite. Laravel serves the Blade template wi
 ```bash
 composer install
 npm install
-npm install superdoc @superdoc-dev/fonts
+npm install superdoc@1 @superdoc-dev/fonts
 ```
 
 ## Vite config
@@ -130,7 +130,7 @@ This runs `php artisan serve` (port 8000) and Vite's dev server together. Open [
 <Card title="Configuration" icon="cog" href="/editor/superdoc/configuration">
   All configuration options
 </Card>
-<Card title="Laravel Example" icon="github" href="https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/laravel">
+<Card title="Laravel Example" icon="github" href="https://go.superdoc.dev/laravel">
   Working Laravel example on GitHub
 </Card>
 <Card title="Collaboration" icon="users" href="/editor/collaboration/overview">

apps/docs/getting-started/frameworks/nextjs.mdx

@@ -10,7 +10,7 @@ SuperDoc works seamlessly with Next.js. The recommended approach is using `@supe
 The React wrapper is the simplest way to integrate SuperDoc with Next.js:
 
 ```bash
-npm install @superdoc-dev/react @superdoc-dev/fonts
+npm install superdoc@1 @superdoc-dev/react@1 @superdoc-dev/fonts
 ```
 
 ### App Router (Next.js 13+)
@@ -91,10 +91,10 @@ export default function RootLayout({ children }) {
 <Card title="Collaboration" icon="users" href="/editor/collaboration/overview">
   Real-time collaboration
 </Card>
-<Card title="React Example" icon="github" href="https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/react">
+<Card title="React Example" icon="github" href="https://go.superdoc.dev/react">
   React + TypeScript example
 </Card>
-<Card title="Next.js Example" icon="github" href="https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/nextjs">
+<Card title="Next.js Example" icon="github" href="https://go.superdoc.dev/nextjs">
   Next.js SSR integration
 </Card>
 </CardGroup>

apps/docs/getting-started/frameworks/nuxt.mdx

@@ -9,7 +9,7 @@ SuperDoc works with Nuxt 4+ as a client-side Vue component. Set `ssr: false` in
 ## Install
 
 ```bash
-npm install superdoc @superdoc-dev/fonts
+npm install superdoc@1 @superdoc-dev/fonts
 ```
 
 ## Configure Nuxt
@@ -158,7 +158,7 @@ const handleFile = (e: Event) => {
 <Card title="Configuration" icon="cog" href="/editor/superdoc/configuration">
   All configuration options
 </Card>
-<Card title="Nuxt Example" icon="github" href="https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/nuxt">
+<Card title="Nuxt Example" icon="github" href="https://go.superdoc.dev/nuxt">
   Working Nuxt example on GitHub
 </Card>
 <Card title="Collaboration" icon="users" href="/editor/collaboration/overview">

apps/docs/getting-started/frameworks/react.mdx

@@ -9,7 +9,7 @@ SuperDoc provides `@superdoc-dev/react`: a first-party wrapper with lifecycle ma
 ## Install
 
 ```bash
-npm install @superdoc-dev/react @superdoc-dev/fonts
+npm install superdoc@1 @superdoc-dev/react@1 @superdoc-dev/fonts
 ```
 
 <Note>
@@ -122,10 +122,10 @@ function FileEditor() {
 <Card title="Collaboration" icon="users" href="/editor/collaboration/overview">
   Real-time collaboration setup
 </Card>
-<Card title="React Example" icon="github" href="https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/react">
+<Card title="React Example" icon="github" href="https://go.superdoc.dev/react">
   React + TypeScript example
 </Card>
-<Card title="Next.js Example" icon="github" href="https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/nextjs">
+<Card title="Next.js Example" icon="github" href="https://go.superdoc.dev/nextjs">
   Next.js SSR integration
 </Card>
 </CardGroup>

apps/docs/getting-started/frameworks/solid.mdx

@@ -13,7 +13,7 @@ SuperDoc does not ship a first-party Solid wrapper. Use the core `superdoc` pack
 ## Install
 
 ```bash
-npm install superdoc @superdoc-dev/fonts
+npm install superdoc@1 @superdoc-dev/fonts
 ```
 
 ## Quick start
@@ -126,4 +126,4 @@ function FileEditor() {
 
 - [React Integration](/getting-started/frameworks/react) - React setup
 - [API Reference](/editor/superdoc/configuration) - Configuration options
-- [Examples](https://github.com/superdoc/docx-editor/tree/main/examples/getting-started/solid) - Working examples
+- [Examples](https://go.superdoc.dev/solid) - Working examples