diff --git a/AGENTS.md b/AGENTS.md index 3a29083be5..cc02b5afed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,9 +78,10 @@ Do not hand-edit `COMMAND_CATALOG`, `OPERATION_MEMBER_PATH_MAP`, `OPERATION_REFE - `pnpm test` - unit tests - `pnpm dev` - dev server from `examples/` - `pnpm check:types` - raw TS compile across all referenced projects (`tsc -b tsconfig.references.json`). Does NOT run the public-interface chain. Legacy alias: `pnpm run type-check`. -- `pnpm check:public` - **canonical pre-merge command for typed public surfaces.** Validates both `superdoc` (tier discipline + jsdoc ratchet + ts-jsdoc hygiene + public-method fixture coverage + vite build + postbuild chain + consumer typecheck matrix + deep-type audit + package-shape + snapshots + classification closure) and Document API (contract parity + output staleness + examples + overview). ~5 min. Non-mutating. Combines `check:public:superdoc` + `check:public:docapi`. -- `pnpm check:public:superdoc` - SuperDoc public package surface only. Wraps twelve stages in cheap-to-expensive order: `contract-tiers-test`, `contract-tiers`, `jsdoc-ratchet`, `jsdoc-hygiene-ts-test`, `jsdoc-hygiene-ts`, `public-method-coverage`, `build`, `consumer-typecheck-matrix`, `deep-type-audit-supported-root`, `package-shape`, `export-snapshots`, `root-classification-closure`. Legacy alias: `pnpm run check:public-contract`. +- `pnpm check:public` - **canonical pre-merge command for typed public surfaces.** Validates both `superdoc` (tier discipline + jsdoc ratchet + ts-jsdoc hygiene + public-method fixture coverage + bundled font license gate + vite build + postbuild chain + consumer typecheck matrix + deep-type audit + package-shape + snapshots + classification closure + docs snippet typecheck) and Document API (contract parity + output staleness + examples + overview). ~5 min. Non-mutating. Combines `check:public:superdoc` + `check:public:docapi`. +- `pnpm check:public:superdoc` - SuperDoc public package surface only. Wraps fourteen stages in cheap-to-expensive order: `contract-tiers-test`, `contract-tiers`, `jsdoc-ratchet`, `jsdoc-hygiene-ts-test`, `jsdoc-hygiene-ts`, `public-method-coverage`, `font-license-gate`, `build`, `consumer-typecheck-matrix`, `deep-type-audit-supported-root`, `package-shape`, `export-snapshots`, `root-classification-closure`, `docs-snippet-typecheck`. Legacy alias: `pnpm run check:public-contract`. - `pnpm check:public:docapi` - Document API public surface only. Wraps four stages: `contract-parity`, `contract-outputs`, `examples`, `overview-alignment`. Clean-checkout safe: gitignored generated artifacts are built in memory; tracked outputs (reference docs, overview block) are compared byte-for-byte. No mutation. Legacy alias: `pnpm run docapi:check`. +- `pnpm check:font-licenses` - validate bundled font legal metadata: every `shared/font-system/assets/*.woff2` has a manifest row, stable hash, matching runtime bundled-manifest entry, and required notices. Also runs inside `check:public:superdoc`. - `pnpm generate:docapi` - regenerate Document API outputs after editing the contract (alias of `docapi:sync`). Writes gitignored Document API generated artifacts. Run only when you need the artifacts materialized locally (SDK builds, publishing); `check:public:docapi` does not require it. - `pnpm generate:all` - regenerate schemas, SDK clients, tool catalogs, reference docs. - `pnpm report:public:superdoc` - print public-contract tier metadata (supported / legacy / legacy-raw / asset / deprecated). Read-only, not a gate. Use `check:public:superdoc` (or its `contract-tiers` stage) to enforce. Source of truth: `packages/superdoc/scripts/type-surface.config.cjs`. diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md index ea41944e0b..49a769b7a2 100644 --- a/THIRD_PARTY_LICENSES.md +++ b/THIRD_PARTY_LICENSES.md @@ -1,6 +1,65 @@ -# Third Party Licenses +# Third-Party Licenses -This project includes code from third-party libraries. Their licenses are listed below. +This file lists third-party components redistributed in SuperDoc and the license +terms that govern them. + +--- + +## Bundled fonts + +SuperDoc bundles open, metric-compatible substitute fonts so that documents +referencing a non-embedded Microsoft core font still render with correct line +breaks and pagination. + +### Scope - applies to all delivery models + +These font notices apply wherever SuperDoc distributes or serves the fonts: + +- embedded or bundled within SuperDoc and its published packages; +- served to browsers as web fonts from a SuperDoc- or customer-operated host; and +- redistributed by a customer that embeds SuperDoc. + +Web-font delivery is distribution under the SIL Open Font License, so these terms +are written to the broadest redistribution case and cover lighter delivery +models too. The authoritative per-family record and the full license texts ship +alongside the fonts at `shared/font-system/assets/` (`LICENSES.md`, `OFL.txt`, +`Apache-2.0.txt`). Distribute that notice set together with the font files. + +SPDX license expression for this bundled font set: `OFL-1.1 AND Apache-2.0`. + +### Components + +| Family | Replaces | License | Reserved Font Name | Version | +| --- | --- | --- | --- | --- | +| Carlito | Calibri | OFL-1.1 | "Carlito" | 1.103 | +| Caladea | Cambria | Apache-2.0 | none | 1.002 | +| Liberation Sans | Arial | OFL-1.1 | none declared | 2.1.5 | +| Liberation Serif | Times New Roman | OFL-1.1 | none declared | 2.1.5 | +| Liberation Mono | Courier New | OFL-1.1 | none declared | 2.1.5 | + +### Copyright & trademark notices from the font `name` tables + +- **Carlito** (OFL-1.1): `Copyright (c) 2010-2013 by tyPoland Lukasz Dziedzic with Reserved Font Name "Carlito". Licensed under the SIL Open Font License, Version 1.1.` Carlito is a trademark of tyPoland Lukasz Dziedzic. +- **Caladea** (Apache-2.0): `Copyright (c) 2012 Huerta Tipografia`. Caladea is a trademark of Huerta Tipografia. No Reserved Font Name. No upstream `NOTICE` file. +- **Liberation Sans / Serif / Mono** (OFL-1.1): `Digitized data copyright (c) 2010 Google Corporation.` / `Copyright (c) 2012 Red Hat, Inc.` "Liberation" is a registered Red Hat trademark. The v2.1.5 files declare no OFL Reserved Font Name. SuperDoc names the unmodified fonts. + +### Format conversion + +The bundled faces are format-only TrueType-to-WOFF2 conversions (`fontTools`, +`flavor="woff2"`, Brotli; no subsetting; WOFF2 metadata omitted). No design, +metric, glyph, `cmap`, or `name`-table change. Verified for this ship set: +20 / 20 faces have a WOFF2 `name` table byte-identical to their source TTF with +identical glyph count and `cmap`, and all metrics are preserved. Under OFL FAQ +2.2.1 these are not Modified Versions and retain the original font names. For +Caladea, this also serves as the Apache-2.0 section 4(b) notice. + +### License texts + +- OFL-1.1: `shared/font-system/assets/OFL.txt`, with per-font copyright notices stacked at top. +- Apache-2.0: `shared/font-system/assets/Apache-2.0.txt`. + +The fonts remain under their own OFL-1.1 / Apache-2.0 terms and are not +relicensed under SuperDoc's terms (AGPLv3 community build or commercial). --- @@ -12,7 +71,7 @@ This project includes code from third-party libraries. Their licenses are listed **License:** MIT -``` +```text The MIT License (MIT) Copyright (c) 2015 Thomas Bluemel diff --git a/apps/docs/advanced/headless-toolbar.mdx b/apps/docs/advanced/headless-toolbar.mdx index 0be39ee79a..2ccfd7670b 100644 --- a/apps/docs/advanced/headless-toolbar.mdx +++ b/apps/docs/advanced/headless-toolbar.mdx @@ -313,6 +313,7 @@ Snapshot values match the format you pass to `execute()`. What you read is what | `redo` | — | — | | `ruler` | — | — | | `zoom` | number (e.g. `125`) | number | +| `zoom-fit-width` | none | none | | `document-mode` | `'editing'` \| `'suggesting'` \| `'viewing'` | mode string | ### Track changes diff --git a/apps/docs/editor/custom-ui/api-reference.mdx b/apps/docs/editor/custom-ui/api-reference.mdx index b77ad697c4..b17a6bd77b 100644 --- a/apps/docs/editor/custom-ui/api-reference.mdx +++ b/apps/docs/editor/custom-ui/api-reference.mdx @@ -187,6 +187,19 @@ await ui.document.export({ exportType: ['docx'], commentsType: 'external', trigg await ui.document.replaceFile(file); ``` +### `ui.zoom` + +Zoom state, viewport metrics, and the two mutations. The snapshot updates on value changes, mode-only transitions, and viewport metric updates. + +```ts +ui.zoom.getSnapshot(); // { mode, value, fitZoom, min, max, metrics } +ui.zoom.observe((snapshot) => {}); +ui.zoom.set(125); // numeric zoom; switches the host to manual mode +ui.zoom.setMode('fit-width'); // continuous fit to the available width +``` + +In React, `useSuperDocZoom()` returns the same snapshot plus bound `set` / `setMode` actions. The toolbar registry also exposes a `zoom-fit-width` toggle command for custom toolbars. + ### `ui.selection` Live slice, capture, restore, painted geometry. diff --git a/apps/docs/editor/custom-ui/toolbar-and-commands.mdx b/apps/docs/editor/custom-ui/toolbar-and-commands.mdx index 4c307f97dc..113f37fc09 100644 --- a/apps/docs/editor/custom-ui/toolbar-and-commands.mdx +++ b/apps/docs/editor/custom-ui/toolbar-and-commands.mdx @@ -117,7 +117,7 @@ Common ids you'll wire to buttons: | Style | `linked-style`, `clear-formatting`, `copy-format` | | History | `undo`, `redo` | | Tracked changes | `track-changes-accept-selection`, `track-changes-reject-selection` | -| View | `ruler`, `zoom`, `document-mode` | +| View | `ruler`, `zoom`, `zoom-fit-width`, `document-mode` | | Tables | `table-insert`, `table-add-row-before`, `table-add-row-after`, `table-delete-row`, `table-add-column-before`, `table-add-column-after`, `table-delete-column`, `table-merge-cells`, `table-split-cell`, `table-delete` | | Insert | `image` | diff --git a/apps/docs/editor/superdoc/configuration.mdx b/apps/docs/editor/superdoc/configuration.mdx index 51848528aa..23c2143fc3 100644 --- a/apps/docs/editor/superdoc/configuration.mdx +++ b/apps/docs/editor/superdoc/configuration.mdx @@ -561,6 +561,76 @@ new SuperDoc({ + + Zoom behavior for the document. Use `mode: 'fit-width'` to keep DOCX and PDF documents fitted to the available container width. Calling `setZoom()` switches back to manual zoom. + + + + Initial zoom level as a percentage. In `fit-width` mode, this is the paint zoom until the first fit computes. + + + Starting zoom mode. `'manual'` holds the current value. `'fit-width'` keeps the document fitted to the container. + + + Bounds and padding for the applied fit-width zoom. + + + Lower bound for the applied zoom percentage. + + + Upper bound for the applied zoom percentage. The default never enlarges the document past its natural size; raise it to let wide containers scale the page up. + + + Horizontal padding in pixels reserved inside the available width before computing the fit. + + + + + + For custom behavior, listen to [`viewport-change`](/editor/superdoc/events#viewport-change) and call `setZoom()` yourself. + + + + ```javascript Usage + const superdoc = new SuperDoc({ + selector: '#editor', + document: file, + zoom: { + mode: 'fit-width', + fitWidth: { min: 35, max: 100, padding: 24 }, + }, + }); + ``` + + ```javascript Full Example + import { SuperDoc } from 'superdoc'; + import 'superdoc/style.css'; + + const superdoc = new SuperDoc({ + selector: '#editor', + document: yourFile, + zoom: { + initial: 100, + mode: 'fit-width', + fitWidth: { min: 35, max: 100, padding: 24 }, + }, + onZoomChange: ({ zoom, mode }) => { + console.log(`Zoom is now ${zoom}% (${mode})`); + }, + }); + ``` + + + + + Minimal React example for fit-width zoom with current zoom and viewport metrics. + + + **Removed in v1.0**: Use `viewOptions.layout` instead. `'paginated'` → `'print'`, `'responsive'` → `'web'`. @@ -684,6 +754,26 @@ All handlers are optional functions in the configuration: ``` + + Called when zoom changes from `setZoom()`, the toolbar zoom control, or `fit-width` mode. + + ```javascript + onZoomChange: ({ zoom, mode }) => { + setZoomIndicator(zoom, mode); + } + ``` + + + + Called when the fit-width calculation changes. Pixel-level width jitter is deduped. `getViewportMetrics()` always reads the latest measurements. + + ```javascript + onViewportChange: ({ availableWidth, documentWidth, fitZoom }) => { + updateFitIndicator({ availableWidth, documentWidth, fitZoom }); + } + ``` + + Custom handler for accepting tracked changes from comment bubbles. Replaces default accept behavior when provided. diff --git a/apps/docs/editor/superdoc/events.mdx b/apps/docs/editor/superdoc/events.mdx index 3cffc4de66..1a9416a6a0 100644 --- a/apps/docs/editor/superdoc/events.mdx +++ b/apps/docs/editor/superdoc/events.mdx @@ -440,12 +440,12 @@ superdoc.on('pagination-update', ({ totalPages, superdoc }) => { ### `zoomChange` -When the zoom level changes via `setZoom()`. +When the zoom level changes, from any source: `setZoom()`, the toolbar zoom control, or [`fit-width` mode](/editor/superdoc/configuration#param-zoom). The payload carries the value and the mode that produced it. Also available as the `onZoomChange` config callback. ```javascript Usage -superdoc.on('zoomChange', ({ zoom }) => { - console.log(`Zoom: ${zoom}%`); +superdoc.on('zoomChange', ({ zoom, mode }) => { + console.log(`Zoom: ${zoom}% (${mode})`); }); ``` @@ -458,8 +458,41 @@ const superdoc = new SuperDoc({ document: yourFile, }); -superdoc.on('zoomChange', ({ zoom }) => { - console.log(`Zoom: ${zoom}%`); +superdoc.on('zoomChange', ({ zoom, mode }) => { + console.log(`Zoom: ${zoom}% (${mode})`); +}); +``` + + +### `viewport-change` + +When the fit-width calculation changes. Pixel-level width changes that do not affect the rounded fit are deduped. `getViewportMetrics()` always reads the latest measurements. + +- `availableWidth` - container width in pixels, minus the comments sidebar when visible +- `documentWidth` - the widest document page width in pixels at 100% zoom (zoom-independent; DOCX from laid-out pages with page-styles fallback, PDF from rendered pages) +- `fitZoom` - the unclamped zoom percentage that fits the page into the available width + +HTML documents reflow to the container, so an HTML-only instance reports no metrics. + +For most use cases, prefer [`zoom.mode: 'fit-width'`](/editor/superdoc/configuration#param-zoom). Subscribe to this event only when you want to apply custom zoom behavior. + + +```javascript Usage +superdoc.on('viewport-change', ({ fitZoom }) => { + superdoc.setZoom(Math.min(100, Math.max(35, fitZoom))); +}); +``` + +```javascript Full Example +import { SuperDoc } from 'superdoc'; +import 'superdoc/style.css'; + +const superdoc = new SuperDoc({ + selector: '#editor', + document: yourFile, + onViewportChange: ({ availableWidth, documentWidth, fitZoom }) => { + console.log(`Need ${fitZoom}% to fit ${documentWidth}px into ${availableWidth}px`); + }, }); ``` diff --git a/apps/docs/editor/superdoc/methods.mdx b/apps/docs/editor/superdoc/methods.mdx index 3e807a5000..202f3ce838 100644 --- a/apps/docs/editor/superdoc/methods.mdx +++ b/apps/docs/editor/superdoc/methods.mdx @@ -538,7 +538,7 @@ const superdoc = new SuperDoc({ ### `setZoom` -Set the zoom level for all documents. Propagates to all presentation editors, PDF viewers, and whiteboard layers. +Set an explicit zoom level and switch zoom mode to `manual`. Use `setZoomMode('fit-width')` to turn automatic fitting back on. Zoom level as a percentage (e.g., `100`, `150`, `200`). Must be a positive finite number. @@ -560,8 +560,8 @@ const superdoc = new SuperDoc({ onReady: ({ superdoc }) => { superdoc.setZoom(150); - superdoc.on('zoomChange', ({ zoom }) => { - console.log(`Zoom changed to ${zoom}%`); + superdoc.on('zoomChange', ({ zoom, mode }) => { + console.log(`Zoom changed to ${zoom}% (${mode})`); }); }, }); @@ -569,6 +569,97 @@ const superdoc = new SuperDoc({ +### `setZoomMode` + +Switch between manual zoom and automatic fit-width zoom. `'fit-width'` keeps DOCX and PDF documents fitted to the available container width, using the bounds from [`zoom.fitWidth`](/editor/superdoc/configuration#param-zoom). Calling `setZoom()` switches back to `'manual'`. + + + The zoom mode to switch to. + + + + +```javascript Usage +superdoc.setZoomMode('fit-width'); +``` + +```javascript Full Example +import { SuperDoc } from 'superdoc'; +import 'superdoc/style.css'; + +const superdoc = new SuperDoc({ + selector: '#editor', + document: yourFile, + onReady: ({ superdoc }) => { + superdoc.setZoomMode('fit-width'); + + superdoc.on('zoomChange', ({ zoom, mode }) => { + console.log(`Zoom: ${zoom}% (${mode})`); + }); + }, +}); +``` + + + +### `getZoomState` + +Get the current zoom mode, value, latest fit calculation, and effective fit bounds. + +**Returns:** `SuperDocZoomState` - `{ mode, value, fitZoom, min, max }`. `fitZoom` is `null` before the first viewport measurement. + + + +```javascript Usage +const { mode, value, fitZoom } = superdoc.getZoomState(); +``` + +```javascript Full Example +import { SuperDoc } from 'superdoc'; +import 'superdoc/style.css'; + +const superdoc = new SuperDoc({ + selector: '#editor', + document: yourFile, + onReady: ({ superdoc }) => { + const state = superdoc.getZoomState(); + console.log(`Mode: ${state.mode}, value: ${state.value}%`); + }, +}); +``` + + + +### `getViewportMetrics` + +Get the latest fit-width measurements. Use this when you need custom zoom behavior instead of `zoom.mode: 'fit-width'`. + +**Returns:** `SuperDocViewportMetrics | null` - `{ availableWidth, documentWidth, fitZoom }`, or `null` until the first measurement (editors still mounting). + + + +```javascript Usage +const metrics = superdoc.getViewportMetrics(); +``` + +```javascript Full Example +import { SuperDoc } from 'superdoc'; +import 'superdoc/style.css'; + +const superdoc = new SuperDoc({ + selector: '#editor', + document: yourFile, + onReady: ({ superdoc }) => { + const metrics = superdoc.getViewportMetrics(); + if (metrics) { + superdoc.setZoom(Math.min(100, metrics.fitZoom)); + } + }, +}); +``` + + + ### `focus` Focus the active editor or first available. diff --git a/apps/docs/getting-started/frameworks/react.mdx b/apps/docs/getting-started/frameworks/react.mdx index 594e4805e5..4bb434a797 100644 --- a/apps/docs/getting-started/frameworks/react.mdx +++ b/apps/docs/getting-started/frameworks/react.mdx @@ -59,6 +59,23 @@ function App() { ``` +### Responsive zoom + +Pass `zoom` with `mode: 'fit-width'` to keep the document fitted to its container as it resizes. SuperDoc observes the container for you; no resize listeners needed. Calling `setZoom()` (or the user picking a percentage in the toolbar) switches back to manual mode. + +```jsx + console.log(`Zoom: ${zoom}% (${mode})`)} +/> +``` + +For custom behavior, listen to `onViewportChange` instead and apply your own zoom with `getInstance().setZoom()`. See [zoom configuration](/editor/superdoc/configuration#param-zoom). + ## Handle file uploads ```jsx diff --git a/examples/README.md b/examples/README.md index 525e241510..96fc1d9c1a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -51,6 +51,7 @@ Patterns for the browser editor surface. | [comments](./editor/built-in-ui/comments) | [docs](https://docs.superdoc.dev/editor/built-in-ui/comments) | | [track-changes](./editor/built-in-ui/track-changes) | [docs](https://docs.superdoc.dev/editor/built-in-ui/track-changes) | | [toolbar](./editor/built-in-ui/toolbar) | [docs](https://docs.superdoc.dev/editor/built-in-ui/toolbar) | +| [responsive-zoom](./editor/built-in-ui/responsive-zoom) | [docs](https://docs.superdoc.dev/editor/superdoc/configuration#param-zoom) | ### Custom UI diff --git a/examples/editor/built-in-ui/responsive-zoom/README.md b/examples/editor/built-in-ui/responsive-zoom/README.md new file mode 100644 index 0000000000..32a4a34f67 --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/README.md @@ -0,0 +1,43 @@ +# Responsive zoom + +Minimal React example for `zoom.mode: 'fit-width'`. The editor starts in fit-width mode, updates as its container changes, and exposes the current zoom and viewport metrics through callbacks. + +## What it shows + +- Configure automatic fit-width zoom with `SuperDocEditor`. +- Read applied zoom with `onZoomChange`. +- Read the latest fit target with `onViewportChange`. +- Return to fit-width mode after a manual zoom change. + +## Run it + +```bash +cd examples/editor/built-in-ui/responsive-zoom +pnpm install +pnpm build +pnpm dev +``` + +## Core pattern + +```tsx + { + console.log({ zoom, mode }); + }} + onViewportChange={({ fitZoom }) => { + console.log({ fitZoom }); + }} +/> +``` + +## Related docs + +- [SuperDoc configuration](https://docs.superdoc.dev/editor/superdoc/configuration#param-zoom) +- [SuperDoc methods](https://docs.superdoc.dev/editor/superdoc/methods#setzoommode) +- [SuperDoc events](https://docs.superdoc.dev/editor/superdoc/events#viewport-change) diff --git a/examples/editor/built-in-ui/responsive-zoom/index.html b/examples/editor/built-in-ui/responsive-zoom/index.html new file mode 100644 index 0000000000..23b929d2e1 --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/index.html @@ -0,0 +1,13 @@ + + + + + + + SuperDoc responsive zoom + + +
+ + + diff --git a/examples/editor/built-in-ui/responsive-zoom/package.json b/examples/editor/built-in-ui/responsive-zoom/package.json new file mode 100644 index 0000000000..9cce3120fd --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/package.json @@ -0,0 +1,23 @@ +{ + "name": "@superdoc-examples/responsive-zoom", + "private": true, + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc --noEmit && vite build", + "preview": "vite preview" + }, + "dependencies": { + "@superdoc-dev/react": "workspace:*", + "react": "catalog:", + "react-dom": "catalog:", + "superdoc": "workspace:*" + }, + "devDependencies": { + "@types/react": "catalog:", + "@types/react-dom": "catalog:", + "@vitejs/plugin-react": "catalog:", + "typescript": "catalog:", + "vite": "catalog:" + } +} diff --git a/examples/editor/built-in-ui/responsive-zoom/public/test_file.docx b/examples/editor/built-in-ui/responsive-zoom/public/test_file.docx new file mode 100644 index 0000000000..ab62888526 Binary files /dev/null and b/examples/editor/built-in-ui/responsive-zoom/public/test_file.docx differ diff --git a/examples/editor/built-in-ui/responsive-zoom/src/App.tsx b/examples/editor/built-in-ui/responsive-zoom/src/App.tsx new file mode 100644 index 0000000000..5638df8386 --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/src/App.tsx @@ -0,0 +1,120 @@ +import { useMemo, useRef, useState } from 'react'; +import { SuperDocEditor } from '@superdoc-dev/react'; +import type { ChangeEvent } from 'react'; +import type { + SuperDocRef, + SuperDocViewportChangeEvent, + SuperDocZoomChangeEvent, +} from '@superdoc-dev/react'; +import '@superdoc-dev/react/style.css'; + +const SAMPLE_DOCUMENT = '/test_file.docx'; +const TOOLBAR_MODULES = { + toolbar: { + groups: { + left: ['zoom'], + }, + }, +}; +const FIT_WIDTH_ZOOM = { + mode: 'fit-width' as const, + fitWidth: { + min: 50, + max: 100, + padding: 32, + }, +}; + +type DocumentSource = string | File; + +export default function App() { + const editorRef = useRef(null); + const fileInputRef = useRef(null); + const [document, setDocument] = useState(SAMPLE_DOCUMENT); + const [documentName, setDocumentName] = useState('Sample document'); + const [zoom, setZoom] = useState({ zoom: 100, mode: 'fit-width' }); + const [metrics, setMetrics] = useState(null); + + const fitLabel = useMemo(() => { + if (!metrics) return 'Measuring'; + return `${Math.round(metrics.fitZoom)}% fit`; + }, [metrics]); + + const openFilePicker = () => fileInputRef.current?.click(); + + const handleFileChange = (event: ChangeEvent) => { + const file = event.target.files?.[0]; + if (!file) return; + setDocument(file); + setDocumentName(file.name); + setMetrics(null); + }; + + const restoreFitWidth = () => { + editorRef.current?.getInstance()?.setZoomMode('fit-width'); + }; + + const resetSample = () => { + setDocument(SAMPLE_DOCUMENT); + setDocumentName('Sample document'); + setMetrics(null); + if (fileInputRef.current) fileInputRef.current.value = ''; + }; + + return ( +
+
+
+

Responsive zoom

+

{documentName}

+
+ +
+ + + + +
+
+ +
+ + Zoom {Math.round(zoom.zoom)}% + + + Mode {zoom.mode} + + + Target {fitLabel} + + {metrics ? ( + + Width {Math.round(metrics.availableWidth)}px + + ) : null} +
+ +
+ +
+
+ ); +} diff --git a/examples/editor/built-in-ui/responsive-zoom/src/main.tsx b/examples/editor/built-in-ui/responsive-zoom/src/main.tsx new file mode 100644 index 0000000000..7fabfa80ec --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/src/main.tsx @@ -0,0 +1,10 @@ +import { StrictMode } from 'react'; +import { createRoot } from 'react-dom/client'; +import App from './App'; +import './style.css'; + +createRoot(document.getElementById('root')!).render( + + + , +); diff --git a/examples/editor/built-in-ui/responsive-zoom/src/style.css b/examples/editor/built-in-ui/responsive-zoom/src/style.css new file mode 100644 index 0000000000..5fe6aa0bbe --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/src/style.css @@ -0,0 +1,156 @@ +:root { + color: var(--sd-ui-text, #1f2937); + background: var(--sd-color-gray-100, #f3f4f6); + font-family: + Inter, + ui-sans-serif, + system-ui, + -apple-system, + BlinkMacSystemFont, + 'Segoe UI', + sans-serif; +} + +* { + box-sizing: border-box; +} + +body { + margin: 0; +} + +button { + font: inherit; +} + +.app-shell { + display: grid; + grid-template-rows: auto auto minmax(0, 1fr); + height: 100vh; + min-height: 0; + background: var(--sd-color-gray-100, #f3f4f6); +} + +.topbar { + display: flex; + align-items: center; + justify-content: space-between; + gap: 16px; + min-height: 64px; + padding: 12px 16px; + background: var(--sd-ui-surface-bg, #fff); + border-bottom: 1px solid var(--sd-ui-border, #d1d5db); +} + +.title-group { + min-width: 0; +} + +.title-group h1 { + margin: 0; + font-size: 16px; + font-weight: 650; + line-height: 1.3; +} + +.title-group p { + margin: 2px 0 0; + overflow: hidden; + color: var(--sd-color-gray-600, #4b5563); + font-size: 13px; + line-height: 1.3; + text-overflow: ellipsis; + white-space: nowrap; +} + +.controls { + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: flex-end; + gap: 8px; +} + +.button { + min-height: 32px; + padding: 6px 12px; + border-radius: 6px; + border: 1px solid var(--sd-ui-border, #d1d5db); + cursor: pointer; + font-size: 13px; + font-weight: 600; +} + +.button.primary { + border-color: var(--sd-ui-action, #2563eb); + background: var(--sd-ui-action, #2563eb); + color: var(--sd-ui-action-text, #fff); +} + +.button.secondary { + background: var(--sd-ui-surface-bg, #fff); + color: var(--sd-ui-text, #1f2937); +} + +.button:hover { + filter: brightness(0.98); +} + +.status-bar { + display: flex; + flex-wrap: wrap; + gap: 6px; + padding: 8px 16px; + background: var(--sd-color-gray-50, #f9fafb); + border-bottom: 1px solid var(--sd-ui-border, #d1d5db); + color: var(--sd-color-gray-600, #4b5563); + font-size: 12px; +} + +.status-bar span { + display: inline-flex; + align-items: center; + gap: 4px; + min-height: 24px; + padding: 3px 8px; + border: 1px solid var(--sd-ui-border, #d1d5db); + border-radius: 6px; + background: var(--sd-ui-surface-bg, #fff); +} + +.status-bar strong { + color: var(--sd-ui-text, #1f2937); + font-weight: 650; +} + +.workspace { + min-height: 0; + padding: 12px; +} + +.responsive-editor { + overflow: hidden; + border: 1px solid var(--sd-ui-border, #d1d5db); + border-radius: 6px; + background: var(--sd-ui-surface-bg, #fff); +} + +@media (max-width: 640px) { + .topbar { + align-items: flex-start; + flex-direction: column; + } + + .controls { + justify-content: flex-start; + width: 100%; + } + + .button { + flex: 1 1 120px; + } + + .workspace { + padding: 8px; + } +} diff --git a/examples/editor/built-in-ui/responsive-zoom/tsconfig.json b/examples/editor/built-in-ui/responsive-zoom/tsconfig.json new file mode 100644 index 0000000000..36197f5db2 --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/tsconfig.json @@ -0,0 +1,21 @@ +{ + "compilerOptions": { + "target": "ES2020", + "useDefineForClassFields": true, + "lib": ["DOM", "DOM.Iterable", "ES2020"], + "allowJs": false, + "skipLibCheck": true, + "esModuleInterop": true, + "allowSyntheticDefaultImports": true, + "strict": true, + "forceConsistentCasingInFileNames": true, + "module": "ESNext", + "moduleResolution": "bundler", + "resolveJsonModule": true, + "isolatedModules": true, + "noEmit": true, + "jsx": "react-jsx" + }, + "include": ["src"], + "references": [] +} diff --git a/examples/editor/built-in-ui/responsive-zoom/vite.config.ts b/examples/editor/built-in-ui/responsive-zoom/vite.config.ts new file mode 100644 index 0000000000..fabde1a8f5 --- /dev/null +++ b/examples/editor/built-in-ui/responsive-zoom/vite.config.ts @@ -0,0 +1,6 @@ +import react from '@vitejs/plugin-react'; +import { defineConfig } from 'vite'; + +export default defineConfig({ + plugins: [react()], +}); diff --git a/examples/manifest.json b/examples/manifest.json index a064a902e0..e99c8e2fd6 100644 --- a/examples/manifest.json +++ b/examples/manifest.json @@ -179,6 +179,21 @@ "docs": "https://docs.superdoc.dev/editor/built-in-ui/toolbar", "ci": true }, + { + "id": "editor-built-in-responsive-zoom", + "section": "editor", + "subsection": "built-in-ui", + "kind": "minimal-example", + "status": "active", + "sourceKind": "local", + "title": "Responsive zoom", + "category": "Editor", + "surface": "Built-in UI", + "sourceRepo": "superdoc-dev/superdoc", + "sourcePath": "examples/editor/built-in-ui/responsive-zoom", + "docs": "https://docs.superdoc.dev/editor/superdoc/configuration#param-zoom", + "ci": true + }, { "id": "editor-custom-ui-selection-capture", "section": "editor", diff --git a/package.json b/package.json index 3243b24b45..92e25ff3c9 100644 --- a/package.json +++ b/package.json @@ -83,6 +83,7 @@ "docapi:check": "pnpm run check:public:docapi", "docapi:sync:check": "pnpm run generate:docapi && pnpm run check:public:docapi", "check:types": "tsc -b tsconfig.references.json", + "check:font-licenses": "node shared/font-system/scripts/check-bundled-font-licenses.mjs", "check:public:superdoc": "node scripts/check-public-contract.mjs", "check:public:docapi": "node scripts/check-public-docapi.mjs", "check:public": "pnpm run check:public:superdoc && pnpm run check:public:docapi", diff --git a/packages/layout-engine/layout-engine/src/index.test.ts b/packages/layout-engine/layout-engine/src/index.test.ts index bde926ca2f..8468d1d76f 100644 --- a/packages/layout-engine/layout-engine/src/index.test.ts +++ b/packages/layout-engine/layout-engine/src/index.test.ts @@ -4628,9 +4628,7 @@ describe('requirePageBoundary edge cases', () => { const layout = layoutDocument(blocks, measures, options); const page = layout.pages[0]; - const contentWidth = options.pageSize!.w - options.margins!.left - options.margins!.right; - const totalGap = 48 * 2; - const expectedSecondColumnX = 50 + (100 * (contentWidth - totalGap)) / (100 + 100 + 300) + 48; + const expectedSecondColumnX = 50 + 100 + 48; const p2 = page.fragments.find((f) => f.blockId === 'p2') as ParaFragment; const p3 = page.fragments.find((f) => f.blockId === 'p3') as ParaFragment; diff --git a/packages/react/src/SuperDocEditor.test.tsx b/packages/react/src/SuperDocEditor.test.tsx index d40ff03b64..94d697d35f 100644 --- a/packages/react/src/SuperDocEditor.test.tsx +++ b/packages/react/src/SuperDocEditor.test.tsx @@ -162,6 +162,72 @@ describe('SuperDocEditor', () => { }, SUPERDOC_READY_TEST_TIMEOUT, ); + + it( + 'should call onZoomChange when zoom changes through the core wiring', + async () => { + const ref = createRef(); + const onReady = vi.fn(); + const onZoomChange = vi.fn(); + + render(); + + await waitFor(() => expect(onReady).toHaveBeenCalled(), { timeout: SUPERDOC_READY_WAIT_TIMEOUT }); + + const instance = ref.current?.getInstance(); + expect(instance).toBeTruthy(); + + instance?.setZoom(150); + + expect(onZoomChange).toHaveBeenCalledWith({ zoom: 150, mode: 'manual' }); + expect(instance?.getZoom()).toBe(150); + expect(instance?.getZoomState().mode).toBe('manual'); + }, + SUPERDOC_READY_TEST_TIMEOUT, + ); + + it( + 'should route onZoomChange through the latest callback after rerender', + async () => { + const ref = createRef(); + const onReady = vi.fn(); + const firstOnZoomChange = vi.fn(); + const secondOnZoomChange = vi.fn(); + + const { rerender } = render(); + + await waitFor(() => expect(onReady).toHaveBeenCalled(), { timeout: SUPERDOC_READY_WAIT_TIMEOUT }); + + const instance = ref.current?.getInstance(); + expect(instance).toBeTruthy(); + + rerender(); + + // Same instance (callback identity changes must not rebuild) and the + // fresh callback receives the event. + expect(ref.current?.getInstance()).toBe(instance); + instance?.setZoom(80); + + expect(firstOnZoomChange).not.toHaveBeenCalled(); + expect(secondOnZoomChange).toHaveBeenCalledWith({ zoom: 80, mode: 'manual' }); + }, + SUPERDOC_READY_TEST_TIMEOUT, + ); + + it( + 'should apply zoom.initial through config passthrough', + async () => { + const ref = createRef(); + const onReady = vi.fn(); + + render(); + + await waitFor(() => expect(onReady).toHaveBeenCalled(), { timeout: SUPERDOC_READY_WAIT_TIMEOUT }); + + expect(ref.current?.getInstance()?.getZoom()).toBe(50); + }, + SUPERDOC_READY_TEST_TIMEOUT, + ); }); describe('onEditorDestroy', () => { diff --git a/packages/react/src/SuperDocEditor.tsx b/packages/react/src/SuperDocEditor.tsx index b022552456..5ebe4c9f1d 100644 --- a/packages/react/src/SuperDocEditor.tsx +++ b/packages/react/src/SuperDocEditor.tsx @@ -20,6 +20,8 @@ import type { SuperDocTransactionEvent, SuperDocContentErrorEvent, SuperDocExceptionEvent, + SuperDocZoomChangeEvent, + SuperDocViewportChangeEvent, } from './types'; /** @@ -50,6 +52,8 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef(null); @@ -211,6 +229,16 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef { + if (!destroyed) { + callbacksRef.current.onZoomChange?.(event); + } + }, + onViewportChange: (event: SuperDocViewportChangeEvent) => { + if (!destroyed) { + callbacksRef.current.onViewportChange?.(event); + } + }, }; instance = new SuperDoc(superdocConfig) as SuperDocInstance; diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts index eba3573a70..d62c9b0933 100644 --- a/packages/react/src/index.ts +++ b/packages/react/src/index.ts @@ -27,4 +27,6 @@ export type { SuperDocTransactionEvent, SuperDocContentErrorEvent, SuperDocExceptionEvent, + SuperDocZoomChangeEvent, + SuperDocViewportChangeEvent, } from './types'; diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts index a0a378cd24..ccf299f802 100644 --- a/packages/react/src/types.ts +++ b/packages/react/src/types.ts @@ -104,6 +104,20 @@ export type SuperDocContentErrorEvent = Parameters>[0]; + +/** + * Event passed to onViewportChange callback. Re-derived from the core + * `Config.onViewportChange` parameter so the React wrapper cannot + * drift from the core contract. + */ +export type SuperDocViewportChangeEvent = Parameters>[0]; + // ============================================================================= // React Component Types // ============================================================================= @@ -131,7 +145,9 @@ type ExplicitCallbackProps = | 'onEditorUpdate' | 'onTransaction' | 'onContentError' - | 'onException'; + | 'onException' + | 'onZoomChange' + | 'onViewportChange'; /** * Explicitly typed callback props to ensure proper TypeScript inference. @@ -158,6 +174,12 @@ export interface CallbackProps { /** Callback when an exception is thrown */ onException?: (event: SuperDocExceptionEvent) => void; + + /** Callback when the zoom level changes (setZoom, toolbar, or fit-width mode) */ + onZoomChange?: (event: SuperDocZoomChangeEvent) => void; + + /** Callback when the implied fit changes (rounded fit zoom or base page width); see the core viewport-change event */ + onViewportChange?: (event: SuperDocViewportChangeEvent) => void; } /** diff --git a/packages/super-editor/package.json b/packages/super-editor/package.json index 22e1b658d2..8c082ab52f 100644 --- a/packages/super-editor/package.json +++ b/packages/super-editor/package.json @@ -178,7 +178,6 @@ "@types/mdast": "catalog:", "@types/react": "catalog:", "@types/react-dom": "catalog:", - "@types/uuid": "catalog:", "@vitejs/plugin-vue": "catalog:", "@vue/test-utils": "catalog:", "canvas": "catalog:", diff --git a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.js b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.js index cb7339e376..888ffc46ba 100644 --- a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.js +++ b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.js @@ -104,12 +104,18 @@ function decode(params) { return null; } - // ECMA-376 renames w:t → w:delText inside . Other inline content — - // w:noBreakHyphen, w:tab, w:br, etc. — stays as-is; the deletion is - // conveyed by the wrapper alone. Guard the rename so non-text - // atoms inside don't crash. - const textNode = translatedTextNode.elements.find((n) => n.name === 'w:t'); - if (textNode) textNode.name = 'w:delText'; + // ECMA-376 (17.3.3.7) requires w:delText for ALL text runs inside . A + // single run can now hold multiple siblings, because the newline export + // safety net splits text around (e.g. AlphaBeta), + // so rename every direct w:t, not just the first; a leftover inside + // would not be treated as deleted. Other inline content + // (w:noBreakHyphen, w:tab, w:br, etc.) stays as-is; the wrapper alone + // conveys the deletion. + (translatedTextNode.elements || []) + .filter((n) => n.name === 'w:t') + .forEach((n) => { + n.name = 'w:delText'; + }); return { name: 'w:del', diff --git a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.test.js b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.test.js index 4aceb41c3d..643fc19441 100644 --- a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.test.js +++ b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/del/del-translator.test.js @@ -177,6 +177,37 @@ describe('w:del translator', () => { expect(result.elements[0].elements[0].name).toBe('w:delText'); }); + it('renames every in a multi-segment run to (newline split)', () => { + const mockTrackedMark = { + type: 'trackDelete', + attrs: { + id: '789', + sourceId: '', + author: 'Test', + authorEmail: 'test@example.com', + date: '2025-10-09T12:00:00Z', + }, + }; + + // The newline export safety net produces one run with interleaved w:t/w:br; + // every w:t inside must become w:delText, not just the first. + exportSchemaToJson.mockReturnValue({ + name: 'w:r', + elements: [ + { name: 'w:t', elements: [{ text: 'Alpha', type: 'text' }] }, + { name: 'w:br' }, + { name: 'w:t', elements: [{ text: 'Beta', type: 'text' }] }, + ], + }); + + const node = { type: 'text', text: 'Alpha\nBeta', marks: [mockTrackedMark] }; + const result = config.decode({ node }); + + const run = result.elements[0]; + expect(run.elements.map((n) => n.name)).toEqual(['w:delText', 'w:br', 'w:delText']); + expect(run.elements.some((n) => n.name === 'w:t')).toBe(false); + }); + it('writes sourceId to w:id for round-trip fidelity', () => { const mockTrackedMark = { type: 'trackDelete', diff --git a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.js b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.js index e9eee7aca8..0586bc1b6c 100644 --- a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.js +++ b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.js @@ -44,11 +44,38 @@ export function getTextNodeForExport(text, marks, params) { partPath: resolveExportPartPath(params), }); - textNodes.push({ - name: 'w:t', - elements: [{ text, type: 'text' }], - attributes: nodeAttrs, - }); + const textValue = typeof text === 'string' ? text : ''; + // Normalize CRLF/CR to LF so Windows line endings export Word-native breaks + // too, rather than leaving a stray carriage return inside . + const normalizedText = textValue.includes('\r') ? textValue.replace(/\r\n?/g, '\n') : textValue; + if (normalizedText.includes('\n')) { + // Export safety net: a raw newline inside is whitespace that Word + // collapses on open (it is not the OOXML representation of a line break), + // while SuperDoc still renders it as a break: the SD-3278 + // divergence. Emit a Word-native between + // segments instead. Everything stays inside this single run so the + // surrounding / wrappers keep wrapping exactly one run. + const segments = normalizedText.split('\n'); + segments.forEach((segment, index) => { + if (segment.length > 0) { + const segmentNeedsSpace = /^\s|\s$/.test(segment); + textNodes.push({ + name: 'w:t', + elements: [{ text: segment, type: 'text' }], + attributes: segmentNeedsSpace ? { 'xml:space': 'preserve' } : null, + }); + } + if (index < segments.length - 1) { + textNodes.push({ name: 'w:br' }); + } + }); + } else { + textNodes.push({ + name: 'w:t', + elements: [{ text: normalizedText, type: 'text' }], + attributes: nodeAttrs, + }); + } // For custom mark export, we need to add a bookmark start and end tag // And store attributes in the bookmark name diff --git a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.test.js b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.test.js index 75f0a66550..979c3b9b37 100644 --- a/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.test.js +++ b/packages/super-editor/src/editors/v1/core/super-converter/v3/handlers/w/t/helpers/translate-text-node.test.js @@ -134,4 +134,80 @@ describe('getTextNodeForExport', () => { const runPropertiesChange = runProperties.elements.find((element) => element.name === 'w:rPrChange'); expect(runPropertiesChange.attributes['w:id']).toBe('7'); }); + + // SD-3278 export safety net: a raw newline left inside a PM text + // node (e.g. from an imported .docx that stored breaks as literal '\n') must + // export as a Word-native , not a collapsed newline inside . + describe('raw newline export safety net', () => { + const contentElements = (result) => result.elements.filter((el) => el.name === 'w:t' || el.name === 'w:br'); + + it('exports a single newline as // within one run', () => { + const result = getTextNodeForExport('Alpha\nBeta', [], buildParams()); + expect(result.name).toBe('w:r'); + const content = contentElements(result); + expect(content.map((el) => el.name)).toEqual(['w:t', 'w:br', 'w:t']); + expect(content[0].elements[0].text).toBe('Alpha'); + expect(content[2].elements[0].text).toBe('Beta'); + }); + + it('never leaves a raw newline inside a ', () => { + const result = getTextNodeForExport('Alpha\nBeta', [], buildParams()); + const texts = result.elements.filter((el) => el.name === 'w:t'); + expect(texts.some((el) => el.elements[0].text.includes('\n'))).toBe(false); + }); + + it('emits a soft break (no w:type="page") for the ', () => { + const result = getTextNodeForExport('Alpha\nBeta', [], buildParams()); + const br = result.elements.find((el) => el.name === 'w:br'); + expect(br).toBeDefined(); + expect(br.attributes?.['w:type']).toBeUndefined(); + }); + + it('leaves newline-free text as a single (unchanged)', () => { + const result = getTextNodeForExport('hello world', [], buildParams()); + const content = contentElements(result); + expect(content).toHaveLength(1); + expect(content[0].name).toBe('w:t'); + expect(content[0].elements[0].text).toBe('hello world'); + }); + + it('emits a for each newline including leading, trailing, and consecutive newlines', () => { + const result = getTextNodeForExport('\nA\n\nB\n', [], buildParams()); + const content = contentElements(result); + expect(content.map((el) => el.name)).toEqual(['w:br', 'w:t', 'w:br', 'w:br', 'w:t', 'w:br']); + const texts = content.filter((el) => el.name === 'w:t').map((el) => el.elements[0].text); + expect(texts).toEqual(['A', 'B']); + }); + + it('sets xml:space="preserve" only on segments with edge whitespace', () => { + const result = getTextNodeForExport('Alpha \n Beta', [], buildParams()); + const texts = result.elements.filter((el) => el.name === 'w:t'); + expect(texts[0].elements[0].text).toBe('Alpha '); + expect(texts[0].attributes).toEqual({ 'xml:space': 'preserve' }); + expect(texts[1].elements[0].text).toBe(' Beta'); + expect(texts[1].attributes).toEqual({ 'xml:space': 'preserve' }); + }); + + it('does not set xml:space on segments without edge whitespace', () => { + const result = getTextNodeForExport('Alpha\nBeta', [], buildParams()); + const texts = result.elements.filter((el) => el.name === 'w:t'); + expect(texts[0].attributes).toBeNull(); + expect(texts[1].attributes).toBeNull(); + }); + + it('normalizes CRLF to a on export', () => { + const content = contentElements(getTextNodeForExport('Alpha\r\nBeta', [], buildParams())); + expect(content.map((el) => el.name)).toEqual(['w:t', 'w:br', 'w:t']); + expect(content[0].elements[0].text).toBe('Alpha'); + expect(content[2].elements[0].text).toBe('Beta'); + }); + + it('normalizes a bare CR to a without leaving a stray carriage return in ', () => { + const result = getTextNodeForExport('Alpha\rBeta', [], buildParams()); + const content = contentElements(result); + expect(content.map((el) => el.name)).toEqual(['w:t', 'w:br', 'w:t']); + const texts = result.elements.filter((el) => el.name === 'w:t'); + expect(texts.some((el) => el.elements[0].text.includes('\r'))).toBe(false); + }); + }); }); diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.test.ts b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.test.ts index eb1374ccc8..1ab66b302b 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.test.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.test.ts @@ -9,6 +9,7 @@ import { type NodeOptions = { text?: string; marks?: Array<{ type: { name: string } }>; + leafText?: (node: ProseMirrorNode) => string; isInline?: boolean; isBlock?: boolean; isLeaf?: boolean; @@ -28,7 +29,7 @@ function createNode(typeName: string, children: ProseMirrorNode[] = [], options: const nodeSize = isText ? text.length : options.nodeSize != null ? options.nodeSize : isLeaf ? 1 : contentSize + 2; return { - type: { name: typeName }, + type: { name: typeName, spec: options.leafText ? { leafText: options.leafText } : {} }, text: isText ? text : undefined, nodeSize, isText, @@ -138,6 +139,25 @@ describe('resolveTextRangeInBlock', () => { expect(result).toEqual({ from: 6, to: 7 }); }); + + it('maps visible offsets across tracked deleted leaf nodes without counting them', () => { + const textA = createNode('text', [], { text: 'A' }); + const deletedBreak = createNode('lineBreak', [], { + isInline: true, + isLeaf: true, + marks: [{ type: { name: 'trackDelete' } }], + leafText: () => '\n', + }); + const textB = createNode('text', [], { text: 'B' }); + const paragraph = createNode('paragraph', [textA, deletedBreak, textB], { + isBlock: true, + inlineContent: true, + }); + + const result = resolveTextRangeInBlock(paragraph, 0, { start: 1, end: 2 }, { textModel: 'visible' }); + + expect(result).toEqual({ from: 3, to: 4 }); + }); }); describe('computeTextContentLength', () => { @@ -204,6 +224,26 @@ describe('computeTextContentLength', () => { expect(computeTextContentLength(paragraph, { textModel: 'visible' })).toBe(2); expect(textContentInBlock(paragraph, { textModel: 'visible' })).toBe('AB'); }); + + it('excludes tracked deleted leaf nodes in the visible text model', () => { + const textA = createNode('text', [], { text: 'A' }); + const deletedBreak = createNode('lineBreak', [], { + isInline: true, + isLeaf: true, + marks: [{ type: { name: 'trackDelete' } }], + leafText: () => '\n', + }); + const textB = createNode('text', [], { text: 'B' }); + const paragraph = createNode('paragraph', [textA, deletedBreak, textB], { + isBlock: true, + inlineContent: true, + }); + + expect(computeTextContentLength(paragraph)).toBe(3); + expect(computeTextContentLength(paragraph, { textModel: 'visible' })).toBe(2); + expect(textContentInBlock(paragraph)).toBe('A\nB'); + expect(textContentInBlock(paragraph, { textModel: 'visible' })).toBe('AB'); + }); }); describe('pmPositionToTextOffset', () => { @@ -268,4 +308,23 @@ describe('pmPositionToTextOffset', () => { expect(pmPositionToTextOffset(paragraph, 0, 6, { textModel: 'visible' })).toBe(1); expect(pmPositionToTextOffset(paragraph, 0, 7, { textModel: 'visible' })).toBe(2); }); + + it('keeps PM positions inside tracked deleted leaf nodes at the surrounding visible offset', () => { + const textA = createNode('text', [], { text: 'A' }); + const deletedBreak = createNode('lineBreak', [], { + isInline: true, + isLeaf: true, + marks: [{ type: { name: 'trackDelete' } }], + leafText: () => '\n', + }); + const textB = createNode('text', [], { text: 'B' }); + const paragraph = createNode('paragraph', [textA, deletedBreak, textB], { + isBlock: true, + inlineContent: true, + }); + + expect(pmPositionToTextOffset(paragraph, 0, 2, { textModel: 'visible' })).toBe(1); + expect(pmPositionToTextOffset(paragraph, 0, 3, { textModel: 'visible' })).toBe(1); + expect(pmPositionToTextOffset(paragraph, 0, 4, { textModel: 'visible' })).toBe(2); + }); }); diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.ts b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.ts index 5395f05ce1..17e95eb01d 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-offset-resolver.ts @@ -29,6 +29,10 @@ function shouldSkipTextNode(node: ProseMirrorNode, options?: TextOffsetOptions): return isVisibleTextModel(options) && hasTrackDeleteMark(node); } +function shouldSkipLeafNode(node: ProseMirrorNode, options?: TextOffsetOptions): boolean { + return isVisibleTextModel(options) && hasTrackDeleteMark(node); +} + function resolveSegmentPosition( targetOffset: number, segmentStart: number, @@ -87,6 +91,10 @@ export function pmPositionToTextOffset( if (node.isLeaf) { const endPos = docPos + node.nodeSize; + if (shouldSkipLeafNode(node, options)) { + if (pmPos < endPos) done = true; + return; + } if (pmPos >= endPos) { offset += 1; } else { @@ -141,6 +149,7 @@ export function computeTextContentLength(blockNode: ProseMirrorNode, options?: T return; } if (node.isLeaf) { + if (shouldSkipLeafNode(node, options)) return; length += 1; return; } @@ -229,6 +238,7 @@ export function resolveTextRangeInBlock( } if (node.isLeaf) { + if (shouldSkipLeafNode(node, options)) return; advanceSegment(1, docPos, docPos + node.nodeSize); return; } @@ -262,7 +272,14 @@ export function textContentInBlock(blockNode: ProseMirrorNode, options?: TextOff } if (node.isLeaf) { - text += '\ufffc'; + if (shouldSkipLeafNode(node, options)) return; + // Honor a leaf's declared visible text (e.g. lineBreak -> '\n', + // noBreakHyphen -> U+2011) so this content model agrees with the visible + // document and with the offset model. All leafText values are one + // character, matching the 1-per-leaf length used by the offset helpers + // above; other leaves fall back to the U+FFFC placeholder. + const leafText = (node.type?.spec as { leafText?: (n: ProseMirrorNode) => string } | undefined)?.leafText; + text += typeof leafText === 'function' ? leafText(node) : '\ufffc'; return; } diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.test.ts b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.test.ts index 8f5c99b9a8..a63576cf03 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.test.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.test.ts @@ -2,7 +2,9 @@ import { describe, expect, it, vi } from 'vitest'; import { Fragment, Schema } from 'prosemirror-model'; import { buildTextWithTabs, parentAllowsNodeAt, textBetweenWithTabs } from './text-with-tabs.js'; -function makeRealSchema(options: { hasTab?: boolean; hasNoBreakHyphen?: boolean; hasGenericLeaf?: boolean } = {}) { +function makeRealSchema( + options: { hasTab?: boolean; hasLineBreak?: boolean; hasNoBreakHyphen?: boolean; hasGenericLeaf?: boolean } = {}, +) { const nodes: Record = { doc: { content: 'paragraph+' }, paragraph: { group: 'block', content: 'inline*' }, @@ -13,6 +15,11 @@ function makeRealSchema(options: { hasTab?: boolean; hasNoBreakHyphen?: boolean; // Tab is non-leaf, which is why `textBetweenWithTabs` (not PM's built-in textBetween) is needed. nodes.tab = { group: 'inline', inline: true, atom: true, content: 'inline*' }; } + if (options.hasLineBreak) { + // Mirrors the real extensions/line-break/line-break.js shape: inline atom + // that disallows marks (`marks: ''`) and renders to
/ exports to . + nodes.lineBreak = { group: 'inline', inline: true, atom: true, marks: '' }; + } if (options.hasNoBreakHyphen) { // Mirrors the real extensions/no-break-hyphen schema: inline leaf atom with leafText. nodes.noBreakHyphen = { group: 'inline', inline: true, atom: true, leafText: () => '‑' }; @@ -93,12 +100,114 @@ describe('buildTextWithTabs', () => { expect(result.child(0).text).toBe('x'); expect(result.child(0).marks.some((m: any) => m.type.name === 'bold')).toBe(true); expect(result.child(1).type.name).toBe('tab'); - // Tab carries the run's marks — the OOXML exporter reads node.marks on tab + // Tab carries the run's marks. The OOXML exporter reads node.marks on tab // nodes (tab-translator.js:53) to emit matching around . expect(result.child(1).marks.some((m: any) => m.type.name === 'bold')).toBe(true); expect(result.child(2).text).toBe('y'); expect(result.child(2).marks.some((m: any) => m.type.name === 'bold')).toBe(true); }); + + // SD-3278: a literal '\n' inside a text node exports as raw newline + // inside , which Word collapses. It must become a `lineBreak` node so the + // exporter emits a Word-native . + it('splits text around a single newline into text + lineBreak + text', () => { + const schema = makeRealSchema({ hasLineBreak: true }); + const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined); + expect(result).toBeInstanceOf(Fragment); + const fragment = result as Fragment; + expect(fragment.childCount).toBe(3); + expect(fragment.child(0).text).toBe('Alpha'); + expect(fragment.child(1).type.name).toBe('lineBreak'); + expect(fragment.child(2).text).toBe('Beta'); + }); + + it('emits a lineBreak node even when the schema has no tab node type', () => { + const schema = makeRealSchema({ hasLineBreak: true }); + const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined) as Fragment; + expect(result).toBeInstanceOf(Fragment); + expect(result.childCount).toBe(3); + expect(result.child(1).type.name).toBe('lineBreak'); + }); + + it('keeps the raw newline in a single text node when the schema has no lineBreak node type', () => { + const schema = makeRealSchema({ hasTab: true }); + const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined); + expect((result as any).isText).toBe(true); + expect((result as any).text).toBe('Alpha\nBeta'); + }); + + it('creates the lineBreak node bare in the creation path', () => { + const schema = makeRealSchema({ hasLineBreak: true }); + const boldMark = schema.marks.bold.create(); + const result = buildTextWithTabs(schema, 'Alpha\nBeta', [boldMark]) as Fragment; + expect(result.child(0).marks.some((m: any) => m.type.name === 'bold')).toBe(true); + expect(result.child(1).type.name).toBe('lineBreak'); + expect(result.child(1).marks.length).toBe(0); + expect(result.child(2).marks.some((m: any) => m.type.name === 'bold')).toBe(true); + }); + + it('omits empty segments around leading, trailing, and consecutive newlines', () => { + const schema = makeRealSchema({ hasLineBreak: true }); + const lead = buildTextWithTabs(schema, '\nfoo', undefined) as Fragment; + expect(lead.childCount).toBe(2); + expect(lead.child(0).type.name).toBe('lineBreak'); + expect(lead.child(1).text).toBe('foo'); + + const doubled = buildTextWithTabs(schema, 'a\n\nb', undefined) as Fragment; + expect(doubled.childCount).toBe(4); + expect(doubled.child(0).text).toBe('a'); + expect(doubled.child(1).type.name).toBe('lineBreak'); + expect(doubled.child(2).type.name).toBe('lineBreak'); + expect(doubled.child(3).text).toBe('b'); + }); + + it('interleaves tab and lineBreak nodes when both control characters are present', () => { + const schema = makeRealSchema({ hasTab: true, hasLineBreak: true }); + const result = buildTextWithTabs(schema, 'a\tb\nc', undefined) as Fragment; + expect(result.childCount).toBe(5); + expect(result.child(0).text).toBe('a'); + expect(result.child(1).type.name).toBe('tab'); + expect(result.child(2).text).toBe('b'); + expect(result.child(3).type.name).toBe('lineBreak'); + expect(result.child(4).text).toBe('c'); + }); + + it('keeps the raw tab literal but still splits the newline when tabs are disallowed', () => { + const schema = makeRealSchema({ hasTab: true, hasLineBreak: true }); + const result = buildTextWithTabs(schema, 'a\tb\nc', undefined, { parentAllowsTab: false }) as Fragment; + expect(result.childCount).toBe(3); + expect(result.child(0).text).toBe('a\tb'); + expect(result.child(1).type.name).toBe('lineBreak'); + expect(result.child(2).text).toBe('c'); + }); + + // Generated/SDK text often uses CRLF; normalize CRLF and bare CR to + // line breaks so no stray carriage return survives in a text segment. + it('normalizes CRLF to a lineBreak node', () => { + const schema = makeRealSchema({ hasLineBreak: true }); + const result = buildTextWithTabs(schema, 'Alpha\r\nBeta', undefined) as Fragment; + expect(result.childCount).toBe(3); + expect(result.child(0).text).toBe('Alpha'); + expect(result.child(1).type.name).toBe('lineBreak'); + expect(result.child(2).text).toBe('Beta'); + }); + + it('normalizes a bare CR to a lineBreak node without leaving a stray carriage return', () => { + const schema = makeRealSchema({ hasLineBreak: true }); + const result = buildTextWithTabs(schema, 'Alpha\rBeta', undefined) as Fragment; + expect(result.childCount).toBe(3); + expect(result.child(0).text).toBe('Alpha'); + expect(result.child(1).type.name).toBe('lineBreak'); + expect(result.child(2).text).toBe('Beta'); + }); + + // A `text*`-only parent (e.g. total-page-number) rejects lineBreak. + it('keeps the raw newline in a single text node when parentAllowsLineBreak is false', () => { + const schema = makeRealSchema({ hasLineBreak: true }); + const result = buildTextWithTabs(schema, 'Alpha\nBeta', undefined, { parentAllowsLineBreak: false }); + expect((result as any).isText).toBe(true); + expect((result as any).text).toBe('Alpha\nBeta'); + }); }); describe('parentAllowsNodeAt', () => { diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.ts b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.ts index 3a44a8582f..82e9bbf64f 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/helpers/text-with-tabs.ts @@ -10,38 +10,77 @@ import type { Transaction } from 'prosemirror-state'; import { TrackDeleteMarkName } from '../../extensions/track-changes/constants.js'; /** - * Build a text-or-fragment suitable for insertion, splitting on '\t' and - * inserting schema `tab` nodes at each split. + * Build a text-or-fragment suitable for insertion, splitting on '\t' and '\n' + * and inserting schema `tab` / `lineBreak` nodes at each split. * - * Returns a plain text node when the schema has no `tab` node type, when the - * parent disallows tab nodes (see {@link parentAllowsTabAt}), or when the text - * contains no tab characters. The raw '\t' is preserved inside the text node - * so exporters and readers still see the character. + * A tab split produces a `tab` node; a newline split produces a `lineBreak` + * node. Each is only performed when the schema exposes the matching node type + * (and, for tabs, when the parent admits them; see {@link parentAllowsNodeAt}). + * A control character that cannot be materialized stays literal inside the + * surrounding text node so exporters and readers still see it. * - * Callers are responsible for ensuring `text` is non-empty (ProseMirror's - * `schema.text` throws on empty input). + * Newlines must become `lineBreak` nodes (not raw '\n' inside a text node): + * a literal newline inside `` is whitespace that Word collapses on open + * (it is not the OOXML representation of a line break), so it would drop the + * visible break while SuperDoc still renders it. The `lineBreak` node + * round-trips to a Word-native ``. See SD-3278. + * + * Returns a plain text node when the text contains no splittable control + * character (the common case). Callers are responsible for ensuring `text` is + * non-empty (ProseMirror's `schema.text` throws on empty input). */ export function buildTextWithTabs( schema: Schema, text: string, marks: readonly ProseMirrorMark[] | undefined, - opts: { parentAllowsTab?: boolean } = {}, + opts: { parentAllowsTab?: boolean; parentAllowsLineBreak?: boolean } = {}, ): ProseMirrorNode | ProseMirrorFragment { - // Check the cheapest/most selective predicate first — most calls carry no '\t'. - if (!text.includes('\t')) return schema.text(text, marks); + // Normalize CRLF/CR to LF up front so Windows line endings (common in + // generated/SDK text) are treated as line breaks too. Only allocate when a + // carriage return is actually present. + const normalized = text.includes('\r') ? text.replace(/\r\n?/g, '\n') : text; + + // Check the cheapest/most selective predicate first; most calls carry neither. + const hasTab = normalized.includes('\t'); + const hasNewline = normalized.includes('\n'); + if (!hasTab && !hasNewline) return schema.text(normalized, marks); + + // `lineBreak` is a normal inline node, but some textblocks restrict their + // content to `text*` (e.g. total-page-number) and reject it. Gate on parent + // admission the same way tabs do: callers that target restrictive parents + // pass the probe result; others default to allowed. When disallowed or absent + // we fall back to literal text, and the export safety net still converts any + // raw newline to `` on export. + const tabNodeType = hasTab && opts.parentAllowsTab !== false ? schema.nodes?.tab : undefined; + const lineBreakNodeType = hasNewline && opts.parentAllowsLineBreak !== false ? schema.nodes?.lineBreak : undefined; + if (!tabNodeType && !lineBreakNodeType) return schema.text(normalized, marks); - const tabNodeType = schema.nodes?.tab; - if (!tabNodeType || opts.parentAllowsTab === false) return schema.text(text, marks); + // `NodeType.create` takes `readonly Mark[] | undefined` (not null) for marks. + const tabMarks: readonly ProseMirrorMark[] | undefined = marks ?? undefined; + + // Split only on the control characters we can replace with a node; any other + // control character stays literal inside the surrounding text segments. + const splitPattern = [tabNodeType ? '\\t' : null, lineBreakNodeType ? '\\n' : null].filter(Boolean).join('|'); + const parts = normalized.split(new RegExp(`(${splitPattern})`)); - const tabMarks = (marks ?? null) as ProseMirrorMark[] | null; - const parts = text.split('\t'); const nodes: ProseMirrorNode[] = []; - for (let i = 0; i < parts.length; i++) { - if (parts[i]) nodes.push(schema.text(parts[i], marks)); - // Carry the surrounding marks onto the tab node so the OOXML exporter - // wraps `` in a matching `` — keeps formatting unbroken - // across the tab (bold-run | tab | bold-run rather than bold | plain | bold). - if (i < parts.length - 1) nodes.push(tabNodeType.create(null, null, tabMarks)); + for (const part of parts) { + if (part === '') continue; // schema.text throws on empty input + if (part === '\t' && tabNodeType) { + // Carry the surrounding marks onto the tab node so the OOXML exporter + // wraps `` in a matching ``, keeping formatting unbroken + // across the tab (bold-run | tab | bold-run rather than bold | plain | bold). + nodes.push(tabNodeType.create(null, null, tabMarks)); + } else if (part === '\n' && lineBreakNodeType) { + // Create the break bare: a soft line break carries no run formatting. + // (Tracking an inserted break so it exports inside is a separate + // concern: br-translator does not yet route node.marks the way + // noBreakHyphen's translator does; see SD-3371. It is not a schema limit: + // a leaf atom can carry marks, governed by the parent run/paragraph.) + nodes.push(lineBreakNodeType.create()); + } else { + nodes.push(schema.text(part, marks)); + } } return Fragment.from(nodes); } @@ -128,8 +167,14 @@ export function textBetweenWithTabs( } if (node.isLeaf) { if (node.isInline) { + if ( + options.textModel === 'visible' && + node.marks?.some((mark: ProseMirrorMark) => mark.type.name === TrackDeleteMarkName) + ) { + return false; + } // Honor PM's `leafText` NodeSpec contract: an inline leaf can declare - // its visible text representation (e.g. noBreakHyphen → U+2011) so + // its visible text representation (e.g. noBreakHyphen -> U+2011) so // flattened reads match the rendered glyph instead of producing the // generic placeholder. Falls back to `leafFallback` when undefined. const leafTextFn = node.type?.spec?.leafText; diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/content-controls-wrappers.ts b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/content-controls-wrappers.ts index 82ab9e11ff..4deabd771e 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/content-controls-wrappers.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/content-controls-wrappers.ts @@ -997,7 +997,10 @@ function insertTextAroundSdt( const { tr } = editor.state; const tabType = editor.schema.nodes?.tab; const parentAllowsTab = tabType && content.includes('\t') ? parentAllowsNodeAt(tr, pos, tabType) : false; - tr.insert(pos, buildTextWithTabs(editor.schema, content, undefined, { parentAllowsTab })); + const lineBreakType = editor.schema.nodes?.lineBreak; + const parentAllowsLineBreak = + lineBreakType && /[\r\n]/.test(content) ? parentAllowsNodeAt(tr, pos, lineBreakType) : false; + tr.insert(pos, buildTextWithTabs(editor.schema, content, undefined, { parentAllowsTab, parentAllowsLineBreak })); dispatchTransaction(editor, tr); return true; } diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts index cf2c46d86b..0ec53f6615 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts @@ -886,6 +886,16 @@ export function executeTextRewrite( const replacementText = getReplacementText(step.args.replacement); const marks = resolveMarksForRange(editor, target, step); + // A rewrite range can start in a normal parent (a run) and span into a + // `text*`-only inline container (e.g. total-page-number) that rejects + // lineBreak. The edits below land at remapped positions whose parent may + // differ from `absFrom`, so probe admission at each actual edit position + // rather than once at the range start: a newline that lands in a restrictive + // parent falls back to literal text (the export safety net still emits + // ). Probe on the current `tr` so prior in-loop steps are reflected. + const lineBreakNodeType = editor.state.schema.nodes?.lineBreak; + const parentAllowsLineBreakAt = (pos: number): boolean => + lineBreakNodeType ? parentAllowsNodeAt(tr, pos, lineBreakNodeType) : false; const structuralRewrite = resolveStructuralRangeRewrite(tr.doc, absFrom, absTo, step); if (structuralRewrite) { @@ -935,7 +945,9 @@ export function executeTextRewrite( tr.delete(absFrom, absTo); return { changed: target.text.length > 0 }; } - const content = buildTextWithTabs(editor.state.schema, replacementText, asProseMirrorMarks(marks)); + const content = buildTextWithTabs(editor.state.schema, replacementText, asProseMirrorMarks(marks), { + parentAllowsLineBreak: parentAllowsLineBreakAt(absFrom), + }); tr.replaceWith(absFrom, absTo, content); return { changed: replacementText !== target.text }; } @@ -991,10 +1003,14 @@ export function executeTextRewrite( if (change.type === 'delete') { tr.delete(remap(change.docFrom), remap(change.docTo)); } else if (change.type === 'insert') { - const content = buildTextWithTabs(editor.state.schema, change.newText, asProseMirrorMarks(marks)); + const content = buildTextWithTabs(editor.state.schema, change.newText, asProseMirrorMarks(marks), { + parentAllowsLineBreak: parentAllowsLineBreakAt(remap(change.docPos)), + }); tr.insert(remap(change.docPos), content); } else { - const content = buildTextWithTabs(editor.state.schema, change.newText, asProseMirrorMarks(marks)); + const content = buildTextWithTabs(editor.state.schema, change.newText, asProseMirrorMarks(marks), { + parentAllowsLineBreak: parentAllowsLineBreakAt(remap(change.docFrom)), + }); tr.replaceWith(remap(change.docFrom), remap(change.docTo), content); } } @@ -1002,12 +1018,15 @@ export function executeTextRewrite( // Pure deletion after trimming: a non-empty replacement whose new text is // fully contained in the old text's common prefix + suffix collapses to an // empty delta (e.g. "best endeavours to:" → "endeavours to:" leaves - // trimmedNew === ""). Delete the removed range rather than building - // schema.text('') — ProseMirror rejects empty text nodes. + // trimmedNew === ""). This also covers removing a lineBreak, now that + // lineBreak counts as "\n" in the diff. Delete the removed range rather than + // building schema.text(''), which ProseMirror rejects for empty text. tr.delete(trimmedFrom, trimmedTo); } else { // 0 or 1 word change: replace just the trimmed range. - const content = buildTextWithTabs(editor.state.schema, trimmedNew, asProseMirrorMarks(marks)); + const content = buildTextWithTabs(editor.state.schema, trimmedNew, asProseMirrorMarks(marks), { + parentAllowsLineBreak: parentAllowsLineBreakAt(trimmedFrom), + }); tr.replaceWith(trimmedFrom, trimmedTo, content); } @@ -1138,7 +1157,12 @@ export function executeTextInsert( const tabNodeType = editor.state.schema.nodes?.tab; const parentAllowsTab = tabNodeType && text.includes('\t') ? parentAllowsNodeAt(tr, absPos, tabNodeType) : false; - tr.insert(absPos, buildTextWithTabs(editor.state.schema, text, marks, { parentAllowsTab })); + // Restrictive parents like total-page-number are `text*` and reject lineBreak; + // probe admission so newline-bearing inserts fall back to literal text there. + const lineBreakNodeType = editor.state.schema.nodes?.lineBreak; + const parentAllowsLineBreak = + lineBreakNodeType && /[\r\n]/.test(text) ? parentAllowsNodeAt(tr, absPos, lineBreakNodeType) : false; + tr.insert(absPos, buildTextWithTabs(editor.state.schema, text, marks, { parentAllowsTab, parentAllowsLineBreak })); return { changed: true }; } @@ -1323,7 +1347,13 @@ export function executeSpanTextRewrite( // For single replacement block, use flat replacement into the span if (replacementBlocks.length === 1) { const marks = resolveSpanMarks(editor, target, policy, step.id); - const content = buildTextWithTabs(editor.state.schema, replacementBlocks[0], asProseMirrorMarks(marks)); + // Probe parent admission so a newline replacement into a `text*`-only span + // parent falls back to literal text (the export safety net handles the rest). + const lineBreakNodeType = editor.state.schema.nodes?.lineBreak; + const parentAllowsLineBreak = lineBreakNodeType ? parentAllowsNodeAt(tr, absFrom, lineBreakNodeType) : false; + const content = buildTextWithTabs(editor.state.schema, replacementBlocks[0], asProseMirrorMarks(marks), { + parentAllowsLineBreak, + }); tr.replaceWith(absFrom, absTo, content); return { changed: true }; } diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/newline-handling.integration.test.ts b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/newline-handling.integration.test.ts new file mode 100644 index 0000000000..3d69098ae7 --- /dev/null +++ b/packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/newline-handling.integration.test.ts @@ -0,0 +1,548 @@ +import { afterEach, beforeAll, describe, expect, it } from 'vitest'; +import { initTestEditor, loadTestDataForEditorTests } from '@tests/helpers/helpers.js'; +import { executeSpanTextRewrite, executeTextInsert, executeTextRewrite } from './executor.ts'; + +/** + * SD-3278: multi-line text forwarded into text-mode mutations (e.g. + * an agentic SDK workflow) must export Word-native line breaks, not a raw '\n' + * inside one that Word collapses. + * + * Two paths are covered: + * - Creation path: doc.replace / text.rewrite with a single '\n' must build a + * `lineBreak` PM node (not a literal '\n' in a text node). + * - Export safety net: a text node that already holds a raw '\n' (e.g. from an + * imported .docx that stored breaks as literal newlines) must still export a + * Word-native . + */ + +function makeSchemaEditor(paragraphs: string[] = ['hello world']) { + return initTestEditor({ + loadFromSchema: true, + content: { + type: 'doc', + content: paragraphs.map((text) => ({ + type: 'paragraph', + attrs: {}, + content: [{ type: 'run', attrs: {}, content: [{ type: 'text', text }] }], + })), + }, + user: { name: 'Integration User', email: 'integration@example.com' }, + }).editor; +} + +function getFirstMatchRef(editor: any, pattern: string): string { + const match = editor.doc.query.match({ select: { type: 'text', pattern }, require: 'first' }); + const ref = match?.items?.[0]?.handle?.ref; + if (!ref) throw new Error(`Could not resolve ref for pattern "${pattern}"`); + return ref; +} + +function hasNodeOfType(editor: any, name: string): boolean { + let found = false; + editor.state.doc.descendants((node: any) => { + if (found) return false; + if (node.type.name === name) { + found = true; + return false; + } + return true; + }); + return found; +} + +function paragraphCount(editor: any): number { + let count = 0; + editor.state.doc.forEach((node: any) => { + if (node.type.name === 'paragraph') count += 1; + }); + return count; +} + +function countNodeType(editor: any, name: string): number { + let count = 0; + editor.state.doc.descendants((node: any) => { + if (node.type.name === name) count += 1; + }); + return count; +} + +describe('text-mode mutations: single newline handling (SD-3278)', () => { + let editor: any | undefined; + + afterEach(() => { + editor?.destroy(); + editor = undefined; + }); + + it('direct doc.replace with a single newline builds a lineBreak node inside one paragraph', () => { + editor = makeSchemaEditor(['hello world']); + + const receipt = editor.doc.replace( + { ref: getFirstMatchRef(editor, 'hello world'), text: 'Alpha\nBeta' }, + { changeMode: 'direct' }, + ); + + expect(receipt.success).toBe(true); + // A single '\n' stays within the paragraph (only '\n\n+' splits paragraphs). + expect(paragraphCount(editor)).toBe(1); + expect(hasNodeOfType(editor, 'lineBreak')).toBe(true); + // It must NOT become a page break. + expect(hasNodeOfType(editor, 'hardBreak')).toBe(false); + }); + + it('tracked doc.replace with a single newline builds a lineBreak node', () => { + editor = makeSchemaEditor(['hello world']); + + const receipt = editor.doc.replace( + { ref: getFirstMatchRef(editor, 'hello world'), text: 'Alpha\nBeta' }, + { changeMode: 'tracked' }, + ); + + expect(receipt.success).toBe(true); + expect(hasNodeOfType(editor, 'lineBreak')).toBe(true); + expect(hasNodeOfType(editor, 'hardBreak')).toBe(false); + }); + + // Read-model consistency (SD-3278): a lineBreak created on the write side must + // read back as '\n' on the diff/search paths, or query.match cannot find + // break-bearing content and an identical rewrite duplicates the break. + it('finds break-bearing content by \\n and is idempotent under an identical rewrite (no duplicate break)', () => { + editor = makeSchemaEditor(['hello world']); + editor.doc.replace({ ref: getFirstMatchRef(editor, 'hello world'), text: 'Alpha\nBeta' }, { changeMode: 'direct' }); + expect(countNodeType(editor, 'lineBreak')).toBe(1); + + // query.match must see the break as '\n' to resolve a ref to the content. + const ref = getFirstMatchRef(editor, 'Alpha\nBeta'); + editor.doc.replace({ ref, text: 'Alpha\nBeta' }, { changeMode: 'direct' }); + // The identical rewrite is a no-op: still exactly one break, not two. + expect(countNodeType(editor, 'lineBreak')).toBe(1); + }); + + it('rewriting break-bearing content to single-line text removes the break', () => { + editor = makeSchemaEditor(['hello world']); + editor.doc.replace({ ref: getFirstMatchRef(editor, 'hello world'), text: 'Alpha\nBeta' }, { changeMode: 'direct' }); + expect(countNodeType(editor, 'lineBreak')).toBe(1); + + const ref = getFirstMatchRef(editor, 'Alpha\nBeta'); + editor.doc.replace({ ref, text: 'AlphaBeta' }, { changeMode: 'direct' }); + expect(countNodeType(editor, 'lineBreak')).toBe(0); + expect(editor.state.doc.firstChild?.textContent).toBe('AlphaBeta'); + }); + + // Proves the bot P1 (rewrite char-diff counts the break) DIRECTLY, without + // query.match: rewriting `AlphaBeta` to the same visible text must + // be a no-op (the diff reads the break as '\n' via leafText), so it neither + // duplicates nor strands the break. + it('an identical rewrite over an existing lineBreak node is a no-op (direct target)', () => { + // paragraph > run > [ text 'Alpha', lineBreak, text 'Beta' ] + editor = initTestEditor({ + loadFromSchema: true, + content: { + type: 'doc', + content: [ + { + type: 'paragraph', + attrs: {}, + content: [ + { + type: 'run', + attrs: {}, + content: [{ type: 'text', text: 'Alpha' }, { type: 'lineBreak' }, { type: 'text', text: 'Beta' }], + }, + ], + }, + ], + }, + user: { name: 'Integration User', email: 'integration@example.com' }, + }).editor; + expect(countNodeType(editor, 'lineBreak')).toBe(1); + + // Span the inline content: first text/lineBreak start .. last node end. + let absFrom = -1; + let absTo = -1; + editor.state.doc.descendants((node: any, pos: number) => { + if (node.isText || node.type.name === 'lineBreak') { + if (absFrom === -1) absFrom = pos; + absTo = pos + node.nodeSize; + } + }); + + const tr = editor.state.tr; + const target = { + kind: 'range', + stepId: 'idem', + op: 'text.rewrite', + blockId: '__selection__', + from: 0, + to: 0, + absFrom, + absTo, + text: 'Alpha\nBeta', + capturedStyle: undefined, + } as any; + const step = { + id: 'idem-rewrite', + op: 'text.rewrite', + where: { by: 'ref', ref: 'ignored' }, + args: { replacement: { text: 'Alpha\nBeta' }, style: { inline: { mode: 'preserve' } } }, + } as any; + + executeTextRewrite(editor, tr, target, step, { map: (pos: number) => pos } as any); + editor.dispatch(tr); + + // Still exactly one break: not duplicated (the bot P1 regression) and not removed. + expect(countNodeType(editor, 'lineBreak')).toBe(1); + expect(editor.state.doc.firstChild?.textContent).toBe('Alpha\nBeta'); + }); +}); + +// lineBreak must not be forced into a parent that rejects it. The +// total-page-number node is `content: 'text*'`, so a newline insert there must +// fall back to literal text rather than throwing (mirrors the tab guard). +describe('newline insert into a restrictive (text*) parent', () => { + let editor: any | undefined; + + afterEach(() => { + editor?.destroy(); + editor = undefined; + }); + + function makeEditorWithTotalPageCount() { + return initTestEditor({ + loadFromSchema: true, + content: { + type: 'doc', + content: [ + { + type: 'paragraph', + attrs: {}, + content: [ + { + type: 'run', + attrs: {}, + content: [{ type: 'total-page-number', attrs: {}, content: [{ type: 'text', text: '7' }] }], + }, + ], + }, + ], + }, + user: { name: 'Integration User', email: 'integration@example.com' }, + }).editor; + } + + function findTotalPageNumberPos(ed: any): number { + let pos: number | undefined; + ed.state.doc.descendants((node: any, nodePos: number) => { + if (pos !== undefined) return false; + if (node.type.name === 'total-page-number') { + pos = nodePos; + return false; + } + return true; + }); + if (pos === undefined) throw new Error('total-page-number node not found'); + return pos; + } + + it('inserts a\\nb into total-page-number without throwing and without creating a lineBreak node', () => { + editor = makeEditorWithTotalPageCount(); + const nodePos = findTotalPageNumberPos(editor); + const innerPos = nodePos + 1; // inside the total-page-number, before its '7' + + const tr = editor.state.tr; + const target = { + kind: 'range', + stepId: 'step-1', + op: 'text.insert', + blockId: 'total-page-number-1', + from: 0, + to: 0, + absFrom: innerPos, + absTo: innerPos, + text: '', + marks: [], + } as any; + const step = { + id: 'insert-newline-into-total-page-number', + op: 'text.insert', + where: { by: 'ref', ref: 'ignored' }, + args: { position: 'before', content: { text: 'a\nb' } }, + } as any; + + expect(() => executeTextInsert(editor, tr, target, step, { map: (pos: number) => pos } as any)).not.toThrow(); + editor.dispatch(tr); + + const totalPageNumber = editor.state.doc.nodeAt(nodePos); + expect(totalPageNumber?.type.name).toBe('total-page-number'); + expect(totalPageNumber?.textContent).toBe('a\nb7'); + expect(hasNodeOfType(editor, 'lineBreak')).toBe(false); + }); + + // The fix also threads the parent-admission probe into the rewrite path + // (executeTextRewrite / executeSpanTextRewrite), not just text.insert. Rewriting + // text INSIDE a text*-only parent with a newline must not throw or inject a + // lineBreak; it falls back to literal text because the field is `text*` only. + it('rewrites text inside total-page-number with a\\nb without throwing or creating a lineBreak node', () => { + editor = makeEditorWithTotalPageCount(); + const nodePos = findTotalPageNumberPos(editor); + const innerPos = nodePos + 1; // the '7' text node sits at [innerPos, innerPos + 1] + + const tr = editor.state.tr; + const target = { + kind: 'range', + stepId: 'rewrite-step', + op: 'text.rewrite', + // '__selection__' makes resolveMarksForRange skip style capture (no block). + blockId: '__selection__', + from: 0, + to: 1, + absFrom: innerPos, + absTo: innerPos + 1, + text: '7', + capturedStyle: undefined, + } as any; + const step = { + id: 'rewrite-newline-into-total-page-number', + op: 'text.rewrite', + where: { by: 'ref', ref: 'ignored' }, + args: { replacement: { text: 'a\nb' }, style: { inline: { mode: 'preserve' } } }, + } as any; + + expect(() => executeTextRewrite(editor, tr, target, step, { map: (pos: number) => pos } as any)).not.toThrow(); + editor.dispatch(tr); + + const totalPageNumber = editor.state.doc.nodeAt(nodePos); + expect(totalPageNumber?.type.name).toBe('total-page-number'); + // No lineBreak node was forced into the text*-only parent. + expect(hasNodeOfType(editor, 'lineBreak')).toBe(false); + }); + + // The probe must be taken at the actual edit position, not once at the range + // start: a rewrite can start in a normal run (which allows lineBreak) and the + // newline edit can land inside a total-page-number (text*-only). A single + // probe at the start would mint a lineBreak that the field parent rejects. + it('does not force a lineBreak into total-page-number when a spanning rewrite lands the newline inside the field', () => { + // paragraph > run > [ text 'AB', total-page-number > text '7' ] + editor = initTestEditor({ + loadFromSchema: true, + content: { + type: 'doc', + content: [ + { + type: 'paragraph', + attrs: {}, + content: [ + { + type: 'run', + attrs: {}, + content: [ + { type: 'text', text: 'AB' }, + { type: 'total-page-number', attrs: {}, content: [{ type: 'text', text: '7' }] }, + ], + }, + ], + }, + ], + }, + user: { name: 'Integration User', email: 'integration@example.com' }, + }).editor; + + const nodePos = findTotalPageNumberPos(editor); // total-page-number opens here; 'B' is at nodePos-1 + const tr = editor.state.tr; + // Range 'B7' starts in the run ('B') and spans into the field's text ('7'). + // The replacement appends '\n', whose edit lands at the end of the field's + // text (a text*-only parent). + const target = { + kind: 'range', + stepId: 'span-rewrite', + op: 'text.rewrite', + blockId: '__selection__', + from: 0, + to: 0, + absFrom: nodePos - 1, // 'B' in the run + absTo: nodePos + 2, // just after '7' inside the field + text: 'B7', + capturedStyle: undefined, + } as any; + const step = { + id: 'span-rewrite-into-field', + op: 'text.rewrite', + where: { by: 'ref', ref: 'ignored' }, + args: { replacement: { text: 'B7\n' }, style: { inline: { mode: 'preserve' } } }, + } as any; + + expect(() => executeTextRewrite(editor, tr, target, step, { map: (pos: number) => pos } as any)).not.toThrow(); + editor.dispatch(tr); + + expect(editor.state.doc.nodeAt(nodePos)?.type.name).toBe('total-page-number'); + // The newline landed in the text*-only field, so it falls back to literal + // text rather than forcing a (schema-invalid) lineBreak there. + expect(hasNodeOfType(editor, 'lineBreak')).toBe(false); + }); + + // executeSpanTextRewrite has its own single-block replacement path with a + // separate parentAllowsLineBreak probe. The rewrite/insert paths above cover + // their probes, but the span path's was unexercised even though its source + // comment claims it is covered. A single inline '\n' stays in one replacement + // block (split is on \n{2,}), so it reaches this single-block path. + it('span rewrite with a single newline builds one lineBreak in a normal parent', () => { + editor = makeSchemaEditor(['hello world']); // paragraph > run > text 'hello world' + const tr = editor.state.tr; + + // A real two-segment span over the run text ('hello' + ' world'). The run + // admits a lineBreak, so the single '\n' must mint exactly one. + const target = { + kind: 'span', + stepId: 'span-newline-normal', + op: 'text.rewrite', + matchId: 'm:span-normal', + segments: [ + { blockId: 'p1', from: 0, to: 5, absFrom: 2, absTo: 7 }, + { blockId: 'p1', from: 5, to: 11, absFrom: 7, absTo: 13 }, + ], + text: 'hello world', + marks: [], + capturedStyleBySegment: [], + } as any; + const step = { + id: 'span-newline-normal', + op: 'text.rewrite', + where: { by: 'ref', ref: 'ignored' }, + args: { replacement: { text: 'Alpha\nBeta' }, style: { inline: { mode: 'preserve' } } }, + } as any; + + expect(() => executeSpanTextRewrite(editor, tr, target, step, { map: (pos: number) => pos } as any)).not.toThrow(); + editor.dispatch(tr); + + expect(countNodeType(editor, 'lineBreak')).toBe(1); + expect(hasNodeOfType(editor, 'hardBreak')).toBe(false); + + // The break is a real node, never a raw '\n' baked into a text node. + let rawNewlineText = false; + editor.state.doc.descendants((node: any) => { + if (node.isText && typeof node.text === 'string' && node.text.includes('\n')) rawNewlineText = true; + }); + expect(rawNewlineText).toBe(false); + }); + + it('span rewrite with a newline into total-page-number falls back to literal text, no lineBreak', () => { + editor = makeEditorWithTotalPageCount(); // paragraph > run > total-page-number > text '7' + const nodePos = findTotalPageNumberPos(editor); + const tr = editor.state.tr; + + // The span sits entirely inside the field's text ('7' at [nodePos+1, nodePos+2]). + // total-page-number is text*-only, so the probe at the edit position rejects a + // lineBreak and the replacement falls back to literal text (the export safety + // net turns it into a later). + const target = { + kind: 'span', + stepId: 'span-newline-field', + op: 'text.rewrite', + matchId: 'm:span-field', + segments: [{ blockId: 'p1', from: 0, to: 1, absFrom: nodePos + 1, absTo: nodePos + 2 }], + text: '7', + marks: [], + capturedStyleBySegment: [], + } as any; + const step = { + id: 'span-newline-field', + op: 'text.rewrite', + where: { by: 'ref', ref: 'ignored' }, + args: { replacement: { text: 'Alpha\nBeta' }, style: { inline: { mode: 'preserve' } } }, + } as any; + + expect(() => executeSpanTextRewrite(editor, tr, target, step, { map: (pos: number) => pos } as any)).not.toThrow(); + editor.dispatch(tr); + + expect(editor.state.doc.nodeAt(nodePos)?.type.name).toBe('total-page-number'); + expect(hasNodeOfType(editor, 'lineBreak')).toBe(false); + }); +}); + +describe('docx export: newline becomes (SD-3278)', () => { + let docData: Awaited>; + let editor: any | undefined; + + beforeAll(async () => { + docData = await loadTestDataForEditorTests('blank-doc.docx'); + }); + + const makeBlankDocEditor = () => + initTestEditor({ + content: docData.docx, + media: docData.media, + mediaFiles: docData.mediaFiles, + fonts: docData.fonts, + // Tracked mutations require an author/user on the editor instance. + user: { name: 'Integration User', email: 'integration@example.com' }, + }).editor; + + afterEach(() => { + editor?.destroy(); + editor = undefined; + }); + + it('exports a Word-native for a text node that already holds a raw newline', async () => { + editor = makeBlankDocEditor(); + + // Seed a raw '\n' directly via the core command (tr.insertText keeps the + // literal newline) to reproduce an imported .docx whose held a raw + // newline (this exercises the export safety net, not the creation path). + editor.dispatch(editor.state.tr.insertText('Alpha\nBeta', 1)); + expect(editor.state.doc.textContent).toContain('Alpha\nBeta'); + expect(hasNodeOfType(editor, 'lineBreak')).toBe(false); + + const xml = await editor.exportDocx({ exportXmlOnly: true }); + expect(xml).toContain(' around (no leftover )', async () => { + editor = makeBlankDocEditor(); + + // Seed "Alpha\nBeta" as one text node, then mark the whole range as a tracked + // deletion. On export the run is split around ; every segment must + // become inside , never a stray . + editor.dispatch(editor.state.tr.insertText('Alpha\nBeta', 1)); + const delMark = editor.schema.marks.trackDelete.create({ + id: 'del-1', + author: 'Reviewer', + authorEmail: 'reviewer@example.com', + date: '2026-01-01T00:00:00.000Z', + }); + editor.dispatch(editor.state.tr.addMark(1, 1 + 'Alpha\nBeta'.length, delMark)); + + const xml = await editor.exportDocx({ exportXmlOnly: true }); + expect(xml).toContain(' survives inside the deletion (it would be ignored by Word). + expect(/]*>[\s\S]*?<\/w:del>/.test(xml)).toBe(false); + }); + + it('tracked doc.replace with a newline exports valid tracked OOXML (inserted text in , break preserved as )', async () => { + editor = makeBlankDocEditor(); + + // Seed text to target, then tracked-replace it with multi-line content. + editor.dispatch(editor.state.tr.insertText('hello world', 1)); + const match = editor.doc.query.match({ select: { type: 'text', pattern: 'hello world' }, require: 'first' }); + const ref = match?.items?.[0]?.handle?.ref; + expect(ref).toBeTruthy(); + + editor.doc.replace({ ref, text: 'Alpha\nBeta' }, { changeMode: 'tracked' }); + + const xml = await editor.exportDocx({ exportXmlOnly: true }); + // Inserted text is tracked and the newline survives as a Word-native break. + expect(xml).toContain('/ the way noBreakHyphen's translator does, so the break + // exports as its own run rather than inside . The output is valid + // OOXML; on reject the orphan break remains. This is an export-routing gap, + // not a schema limit (a leaf atom can carry marks). Tracked deletes of an + // existing raw-newline node keep the break inside via the single-run + // path above. + }); +}); diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/node-materializer.ts b/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/node-materializer.ts index 6b038a2210..1d1af2b13b 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/node-materializer.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/node-materializer.ts @@ -917,7 +917,15 @@ function materializeTab(schema: Schema): ProseMirrorNode { } function materializeLineBreak(schema: Schema): ProseMirrorNode { - const nodeType = schema.nodes.hardBreak ?? schema.nodes.lineBreak; + // A `kind: 'lineBreak'` item is a soft break and must materialize to `lineBreak` + // (exports ``), not `hardBreak` (exports ``, a page + // break). Block-level page breaks use the distinct `kind: 'break'` path. + // KNOWN AMBIGUITY: structural projection (sd-projection) maps BOTH hardBreak + // and lineBreak to `kind: 'lineBreak'` with no discriminator, so a structural + // read/write echo of an *inline* page break is demoted to a soft break here. + // That projection ambiguity predates this change and needs a discriminator to + // round-trip inline page breaks (separate follow-up). + const nodeType = schema.nodes.lineBreak ?? schema.nodes.hardBreak; if (!nodeType) return schema.text('\n'); return nodeType.create(); } diff --git a/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/structural-write-engine.test.ts b/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/structural-write-engine.test.ts index 6559632baa..d3e3085c80 100644 --- a/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/structural-write-engine.test.ts +++ b/packages/super-editor/src/editors/v1/document-api-adapters/structural-write-engine/structural-write-engine.test.ts @@ -895,6 +895,74 @@ describe('materializeFragment — capability gates', () => { // Extension nodes bypass capability gates — should fall through to fallback materializer expect(() => materializeFragment(editor.state.schema, fragment, new Set(), 'insert')).not.toThrow(); }); + + // SD-3278: a `kind: 'lineBreak'` inline must become a soft `lineBreak` + // node (exports to ), NOT a `hardBreak` node (exports to a page break). + // This is the bug that made the structural.replace workaround fail. + it('materializes a structural lineBreak as a soft lineBreak node, not a hardBreak', () => { + const fragment: SDFragment = { + kind: 'paragraph', + paragraph: { + inlines: [ + { kind: 'run', run: { text: 'Alpha' } }, + { kind: 'lineBreak' }, + { kind: 'run', run: { text: 'Beta' } }, + ], + }, + } as any; + + const materialized = materializeFragment(editor.state.schema, fragment, new Set(), 'insert'); + const roots = Array.isArray(materialized) ? materialized : [materialized]; + const typeNames = new Set(); + roots.forEach((root: any) => root.descendants((node: any) => typeNames.add(node.type.name))); + + expect(typeNames.has('lineBreak')).toBe(true); + expect(typeNames.has('hardBreak')).toBe(false); + }); + + // SD-3278: a structural run whose text carries a raw newline (a natural shape + // for SDK/agent-built `structural.replace` content) must split into lineBreak + // nodes, not keep the literal '\n' in a text node. + it('splits a newline inside structural run text into a lineBreak node, not raw text', () => { + const fragment: SDFragment = { + kind: 'paragraph', + paragraph: { + inlines: [{ kind: 'run', run: { text: 'left\nright' } }], + }, + } as any; + + const materialized = materializeFragment(editor.state.schema, fragment, new Set(), 'insert'); + const roots = Array.isArray(materialized) ? materialized : [materialized]; + const typeCounts: Record = {}; + let text = ''; + roots.forEach((root: any) => + root.descendants((node: any) => { + typeCounts[node.type.name] = (typeCounts[node.type.name] ?? 0) + 1; + if (node.isText) text += node.text ?? ''; + }), + ); + + expect(typeCounts.lineBreak).toBe(1); + expect(typeCounts.hardBreak ?? 0).toBe(0); + // No raw newline survives inside a text node. + expect(text.includes('\n')).toBe(false); + expect(text).toContain('left'); + expect(text).toContain('right'); + // The break reads back as '\n' via leafText, so structural reads that + // flatten PM content preserve it on round-trip (SD-3278). + const readableText = roots + .map((root: any) => { + if (typeof root.textBetween !== 'function') return root.textContent ?? ''; + const leafText = (node: any) => { + const specLeafText = node?.type?.spec?.leafText; + return typeof specLeafText === 'function' ? specLeafText(node) : ''; + }; + const size = root.content?.size ?? root.size ?? 0; + return root.textBetween(0, size, '', leafText); + }) + .join(''); + expect(readableText).toBe('left\nright'); + }); }); // --------------------------------------------------------------------------- diff --git a/packages/super-editor/src/editors/v1/extensions/line-break/line-break.js b/packages/super-editor/src/editors/v1/extensions/line-break/line-break.js index 4fbc2a148c..e141dcc41f 100644 --- a/packages/super-editor/src/editors/v1/extensions/line-break/line-break.js +++ b/packages/super-editor/src/editors/v1/extensions/line-break/line-break.js @@ -32,6 +32,17 @@ export const LineBreak = Node.create({ content: '', atom: true, + // The visible text representation of this leaf. Without it, flattening APIs + // see the break as nothing or a U+FFFC placeholder, so the rewrite char-diff + // and the doc-api text model (query.match, structural projection) disagree + // with the visible document. For example, an idempotent text.rewrite over + // `Alpha\nBeta` would duplicate the break, and query.match could not find it. + // Read by PM's built-in `Node.textBetween` (so `node.textContent` too), + // SuperDoc's `textBetweenWithTabs` / `charOffsetToDocPos`, SearchIndex, and + // `text-offset-resolver`. Mirrors the `noBreakHyphen` leaf (U+2011). See + // SD-3278. + leafText: () => '\n', + addOptions() { return {}; }, diff --git a/packages/super-editor/src/editors/v1/extensions/paragraph/paragraph.js b/packages/super-editor/src/editors/v1/extensions/paragraph/paragraph.js index 593f599a5f..94a02b611c 100644 --- a/packages/super-editor/src/editors/v1/extensions/paragraph/paragraph.js +++ b/packages/super-editor/src/editors/v1/extensions/paragraph/paragraph.js @@ -386,14 +386,16 @@ export const Paragraph = OxmlNode.create({ // We avoid `findParentNode(isList)` here because `isList` depends on // `getResolvedParagraphProperties`, a WeakMap cache keyed by node // identity. After the numbering plugin's `appendTransaction` sets - // `listRendering`, the paragraph node object is replaced, leaving - // the new node uncached — causing `isList` to return false. + // `listRendering`, the paragraph node object is replaced, so the + // new node is uncached and `isList` can return false. const { $from } = selection; let paragraph = null; + let paragraphDepth = null; for (let d = $from.depth; d >= 0; d--) { const node = $from.node(d); if (node.type.name === 'paragraph') { paragraph = node; + paragraphDepth = d; break; } } @@ -404,7 +406,18 @@ export const Paragraph = OxmlNode.create({ if (!isListParagraph) return false; if (!isVisuallyEmptyParagraph(paragraph) && !hasOnlyBreakContent(paragraph)) return false; - const tr = state.tr.insertText(event.data); + let tr = state.tr; + if (hasOnlyBreakContent(paragraph) && paragraphDepth != null) { + const contentStart = $from.start(paragraphDepth); + const contentEnd = $from.end(paragraphDepth); + tr = tr.delete(contentStart, contentEnd).insertText(event.data, contentStart); + // insertText at an explicit position leaves the caret before the inserted + // text, so subsequent native keystrokes prepend instead of append (typing + // "abcdef" lands as "bcdefa"). Place the caret after the inserted text. + tr = tr.setSelection(TextSelection.create(tr.doc, contentStart + event.data.length)); + } else { + tr = tr.insertText(event.data); + } view.dispatch(tr); event.preventDefault(); return true; diff --git a/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.js b/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.js index a830c3d298..162d6e5289 100644 --- a/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.js +++ b/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.js @@ -28,6 +28,12 @@ const DELETION_BARRIER = '\u0000'; const DEFAULT_SEARCH_MODEL = 'raw'; const hasTrackDeleteMark = (node) => node?.marks?.some((mark) => mark?.type?.name === 'trackDelete') ?? false; +const readLeafText = (node) => { + const leafText = node?.type?.spec?.leafText; + if (typeof leafText === 'function') return leafText(node); + if (typeof leafText === 'string') return leafText; + return ATOM_PLACEHOLDER; +}; /** * SearchIndex provides a lazily-built, cached index for searching across @@ -69,7 +75,7 @@ export class SearchIndex { this.#buildVisible(doc); } else { // Get the flattened text using ProseMirror's optimized textBetween - this.text = doc.textBetween(0, doc.content.size, BLOCK_SEPARATOR, ATOM_PLACEHOLDER); + this.text = doc.textBetween(0, doc.content.size, BLOCK_SEPARATOR, readLeafText); } this.segments = []; @@ -141,7 +147,12 @@ export class SearchIndex { } if (node.isLeaf) { - parts.push(ATOM_PLACEHOLDER); + if (hasTrackDeleteMark(node)) { + appendDeletionBarrier(); + return; + } + + parts.push(readLeafText(node)); emittedDeletionBarrier = false; return; } @@ -240,29 +251,48 @@ export class SearchIndex { } if (node.isLeaf) { + if (searchModel === 'visible' && hasTrackDeleteMark(node)) { + if (context?.deletionBarrierActive) { + return offset; + } + addSegment({ + offsetStart: offset, + offsetEnd: offset + 1, + docFrom: docPos, + docTo: docPos + node.nodeSize, + kind: 'atom', + }); + if (context) { + context.deletionBarrierActive = true; + } + return offset + 1; + } + if (context && searchModel === 'visible') { context.deletionBarrierActive = false; } + const leafText = readLeafText(node); + if (leafText.length === 0) return offset; // Leaf node (atom): check if it's a hard_break or other atom if (node.type.name === 'hard_break') { addSegment({ offsetStart: offset, - offsetEnd: offset + 1, + offsetEnd: offset + leafText.length, docFrom: docPos, docTo: docPos + node.nodeSize, kind: 'hardBreak', }); - return offset + 1; + return offset + leafText.length; } - // Other atoms get the replacement character + // Other atoms use their declared leaf text or the replacement character. addSegment({ offsetStart: offset, - offsetEnd: offset + 1, + offsetEnd: offset + leafText.length, docFrom: docPos, docTo: docPos + node.nodeSize, kind: 'atom', }); - return offset + 1; + return offset + leafText.length; } // For non-leaf nodes, recurse into content @@ -310,6 +340,14 @@ export class SearchIndex { */ offsetRangeToDocRanges(start, end) { const ranges = []; + // A single search hit is gapless in offset space, so consecutive segments + // (text and inline-leaf atoms like lineBreak) belong to one contiguous + // match. Coalesce them into one doc range — otherwise a hit spanning + // `text + lineBreak + text` yields discontiguous text ranges that the + // downstream D5 contiguity guard rejects (SD-3278). A block separator is a + // real split between blocks and ends the current range. The D5 guard still + // catches genuinely separate edits, which are not offset-contiguous. + let current = null; for (const segment of this.segments) { // Skip segments entirely before our range @@ -317,25 +355,49 @@ export class SearchIndex { // Stop if we're past our range if (segment.offsetStart >= end) break; - // Only include text segments in the result - if (segment.kind !== 'text') continue; + // Block separators split blocks; never coalesce across them. + if (segment.kind === 'blockSep') { + if (current) { + ranges.push({ from: current.from, to: current.to }); + current = null; + } + continue; + } - // Calculate the overlap const overlapStart = Math.max(start, segment.offsetStart); const overlapEnd = Math.min(end, segment.offsetEnd); + if (overlapStart >= overlapEnd) continue; + + let from; + let to; + if (segment.kind === 'text') { + from = segment.docFrom + (overlapStart - segment.offsetStart); + to = segment.docFrom + (overlapEnd - segment.offsetStart); + } else { + // Inline leaf atom (lineBreak, hardBreak, image, ...): occupies its + // whole node span and is part of the contiguous match, not a gap. + from = segment.docFrom; + to = segment.docTo; + } - if (overlapStart < overlapEnd) { - // Map the overlap back to document positions - const startInSegment = overlapStart - segment.offsetStart; - const endInSegment = overlapEnd - segment.offsetStart; - - ranges.push({ - from: segment.docFrom + startInSegment, - to: segment.docFrom + endInSegment, - }); + // Coalesce only when the next segment is BOTH offset-contiguous (same + // search hit) AND PM-contiguous (`from === current.to`, i.e. immediately + // adjacent in the document). This merges `text + lineBreak + text` within + // one run into a single range, but never bridges a document gap — a + // skipped/tracked-deleted leaf, a run boundary, or any content the match + // does not actually cover. A non-coalesced segment becomes its own range; + // since it stays offset-contiguous, the downstream block coalescing still + // sees no gap, while the D5 guard keeps rejecting genuinely separate edits. + if (current && segment.offsetStart === current.offsetEnd && from === current.to) { + current.to = to; + current.offsetEnd = overlapEnd; + } else { + if (current) ranges.push({ from: current.from, to: current.to }); + current = { from, to, offsetEnd: overlapEnd }; } } + if (current) ranges.push({ from: current.from, to: current.to }); return ranges; } diff --git a/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.test.js b/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.test.js index bde782ccf8..6b92f0f791 100644 --- a/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.test.js +++ b/packages/super-editor/src/editors/v1/extensions/search/SearchIndex.test.js @@ -1,5 +1,6 @@ // @ts-nocheck import { describe, it, expect } from 'vitest'; +import { Schema } from 'prosemirror-model'; import { SearchIndex } from './SearchIndex.js'; describe('SearchIndex.stripDiacritics', () => { @@ -142,6 +143,66 @@ describe('SearchIndex.searchIgnoringDiacritics', () => { }); }); +describe('SearchIndex lineBreak leaf text', () => { + const schema = new Schema({ + nodes: { + doc: { content: 'paragraph+' }, + paragraph: { group: 'block', content: 'inline*' }, + text: { group: 'inline' }, + lineBreak: { + group: 'inline', + inline: true, + atom: true, + leafText: () => '\n', + }, + }, + marks: {}, + }); + + function buildLineBreakDoc() { + return schema.nodes.doc.create(null, [ + schema.nodes.paragraph.create(null, [schema.text('Alpha'), schema.nodes.lineBreak.create(), schema.text('Beta')]), + ]); + } + + it('indexes lineBreak using its declared leafText', () => { + const index = new SearchIndex(); + + index.ensureValid(buildLineBreakDoc()); + + expect(index.text).toBe('Alpha\nBeta'); + expect(index.search('Alpha\nBeta')).toHaveLength(1); + }); + + it('coalesces a hit spanning text + lineBreak + text into one contiguous doc range', () => { + const index = new SearchIndex(); + index.ensureValid(buildLineBreakDoc()); + + // The full 'Alpha\nBeta' span (text + lineBreak + text, all PM-adjacent in + // one block) must map to a single contiguous range, not discontiguous text + // ranges that the downstream D5 contiguity guard would reject. + const ranges = index.offsetRangeToDocRanges(0, index.text.length); + expect(ranges).toHaveLength(1); + }); + + it('does NOT coalesce across a block separator (negative)', () => { + const index = new SearchIndex(); + index.ensureValid( + schema.nodes.doc.create(null, [ + schema.nodes.paragraph.create(null, [schema.text('Alpha')]), + schema.nodes.paragraph.create(null, [schema.text('Beta')]), + ]), + ); + + // 'Alpha\nBeta' here is two paragraphs joined by a block separator, not an + // inline break. The separator is a real split: the span must stay two ranges + // (one per block), never a single editable text range. + expect(index.text).toBe('Alpha\nBeta'); + const ranges = index.offsetRangeToDocRanges(0, index.text.length); + expect(ranges).toHaveLength(2); + }); +}); + describe('SearchIndex searchModel: visible', () => { function textNode(text, { deleted = false } = {}) { return { @@ -155,6 +216,19 @@ describe('SearchIndex searchModel: visible', () => { }; } + function leafNode(typeName, { deleted = false, leafText = undefined } = {}) { + return { + isText: false, + isLeaf: true, + isInline: true, + isBlock: false, + type: { name: typeName, spec: leafText ? { leafText } : {} }, + nodeSize: 1, + marks: deleted ? [{ type: { name: 'trackDelete' } }] : [], + forEach: () => {}, + }; + } + function containerNode(children, { isBlock = false, textBetween = '' } = {}) { return { isText: false, @@ -204,6 +278,23 @@ describe('SearchIndex searchModel: visible', () => { return { doc }; } + function buildDocWithTrackedDeletedLineBreak() { + const paragraph = containerNode( + [textNode('before'), leafNode('lineBreak', { deleted: true, leafText: () => '\n' }), textNode('after')], + { + isBlock: true, + textBetween: 'before\nafter', + }, + ); + + const doc = containerNode([paragraph], { + isBlock: false, + textBetween: 'before\nafter', + }); + + return { doc }; + } + it('excludes pending tracked deletions in visible model', () => { const { doc } = buildDocWithTrackedDeletion(); const index = new SearchIndex(); @@ -250,4 +341,14 @@ describe('SearchIndex searchModel: visible', () => { expect(ranges[0].to - ranges[0].from).toBe('after'.length); expect(ranges[0]).toEqual({ from: 13, to: 18 }); }); + + it('excludes pending tracked deletions on leaf nodes in visible model', () => { + const { doc } = buildDocWithTrackedDeletedLineBreak(); + const index = new SearchIndex(); + + index.ensureValid(doc, { searchModel: 'visible' }); + + expect(index.search('\n')).toHaveLength(0); + expect(index.search('beforeafter')).toHaveLength(0); + }); }); diff --git a/packages/super-editor/src/editors/v1/extensions/search/search.js b/packages/super-editor/src/editors/v1/extensions/search/search.js index 8679aa08e3..e3fcbb196b 100644 --- a/packages/super-editor/src/editors/v1/extensions/search/search.js +++ b/packages/super-editor/src/editors/v1/extensions/search/search.js @@ -49,11 +49,12 @@ const mapIndexMatchesToDocMatches = ({ searchIndex, indexMatches, doc, positionT if (ranges.length === 0) continue; const matchTexts = ranges.map((r) => doc.textBetween(r.from, r.to)); + const matchText = typeof indexMatch.text === 'string' ? indexMatch.text : matchTexts.join(''); const match = { from: ranges[0].from, to: ranges[ranges.length - 1].to, - text: matchTexts.join(''), + text: matchText, id: uuidv4(), ranges, trackerIds: [], diff --git a/packages/super-editor/src/headless-toolbar/helpers/document.ts b/packages/super-editor/src/headless-toolbar/helpers/document.ts index 958f90e669..ff0023a1d0 100644 --- a/packages/super-editor/src/headless-toolbar/helpers/document.ts +++ b/packages/super-editor/src/headless-toolbar/helpers/document.ts @@ -144,6 +144,16 @@ export const createZoomStateDeriver = }; }; +export const createZoomFitWidthStateDeriver = + () => + ({ context, superdoc }: { context: ToolbarContext | null; superdoc: Record }): ToolbarCommandState => { + const mode = typeof superdoc?.getZoomState === 'function' ? superdoc.getZoomState()?.mode : undefined; + return { + active: mode === 'fit-width', + disabled: !context || typeof superdoc?.setZoomMode !== 'function', + }; + }; + export const createDocumentModeStateDeriver = () => ({ context, superdoc }: { context: ToolbarContext | null; superdoc: Record }): ToolbarCommandState => { @@ -182,6 +192,18 @@ export const createZoomExecute = return true; }; +// Toggle fit-width mode. A second activation returns to manual at the +// current value, matching toolbar toggle conventions; numeric zoom stays +// on the separate `zoom` command. +export const createZoomFitWidthExecute = + () => + ({ superdoc }: { context: ToolbarContext | null; superdoc: Record; payload?: unknown }) => { + if (typeof superdoc?.setZoomMode !== 'function') return false; + const mode = typeof superdoc.getZoomState === 'function' ? superdoc.getZoomState()?.mode : undefined; + superdoc.setZoomMode(mode === 'fit-width' ? 'manual' : 'fit-width'); + return true; + }; + export const createDocumentModeExecute = () => ({ superdoc, payload }: { context: ToolbarContext | null; superdoc: Record; payload?: unknown }) => { diff --git a/packages/super-editor/src/headless-toolbar/toolbar-registry.test.ts b/packages/super-editor/src/headless-toolbar/toolbar-registry.test.ts index 541e886596..dedc6fe3b2 100644 --- a/packages/super-editor/src/headless-toolbar/toolbar-registry.test.ts +++ b/packages/super-editor/src/headless-toolbar/toolbar-registry.test.ts @@ -986,6 +986,75 @@ describe('createToolbarRegistry', () => { }); }); + it('derives zoom-fit-width active state from the host zoom mode', () => { + const registry = createToolbarRegistry(); + + const fitActive = registry['zoom-fit-width']?.state({ + context: createContext(), + superdoc: { + getZoomState: vi.fn(() => ({ mode: 'fit-width', value: 84, fitZoom: 84, min: 10, max: 100 })), + setZoomMode: vi.fn(), + }, + }); + expect(fitActive).toEqual({ active: true, disabled: false }); + + const manual = registry['zoom-fit-width']?.state({ + context: createContext(), + superdoc: { + getZoomState: vi.fn(() => ({ mode: 'manual', value: 100, fitZoom: null, min: 10, max: 100 })), + setZoomMode: vi.fn(), + }, + }); + expect(manual).toEqual({ active: false, disabled: false }); + }); + + it('disables zoom-fit-width without a context or a setZoomMode host bridge', () => { + const registry = createToolbarRegistry(); + + const noContext = registry['zoom-fit-width']?.state({ + context: null, + superdoc: { setZoomMode: vi.fn(), getZoomState: vi.fn(() => ({ mode: 'manual' })) }, + }); + expect(noContext?.disabled).toBe(true); + + const noBridge = registry['zoom-fit-width']?.state({ + context: createContext(), + superdoc: {}, + }); + expect(noBridge?.disabled).toBe(true); + }); + + it('zoom-fit-width execute toggles between fit-width and manual', () => { + const registry = createToolbarRegistry(); + + const setZoomMode = vi.fn(); + const fromManual = registry['zoom-fit-width']?.execute?.({ + context: createContext(), + superdoc: { + setZoomMode, + getZoomState: vi.fn(() => ({ mode: 'manual', value: 100, fitZoom: null, min: 10, max: 100 })), + }, + }); + expect(fromManual).toBe(true); + expect(setZoomMode).toHaveBeenCalledWith('fit-width'); + + const setZoomModeBack = vi.fn(); + registry['zoom-fit-width']?.execute?.({ + context: createContext(), + superdoc: { + setZoomMode: setZoomModeBack, + getZoomState: vi.fn(() => ({ mode: 'fit-width', value: 84, fitZoom: 84, min: 10, max: 100 })), + }, + }); + expect(setZoomModeBack).toHaveBeenCalledWith('manual'); + + const noBridge = registry['zoom-fit-width']?.execute?.({ + context: createContext(), + superdoc: {}, + }); + expect(noBridge).toBe(false); + }); + it('enables track-changes accept-selection when selection contains tracked changes and action is allowed', () => { collectTrackedChangesMock.mockReturnValueOnce([{ id: 'tc-1' }]); isTrackedChangeActionAllowedMock.mockReturnValueOnce(true); diff --git a/packages/super-editor/src/headless-toolbar/toolbar-registry.ts b/packages/super-editor/src/headless-toolbar/toolbar-registry.ts index 3ea56a72d4..bd96c6a229 100644 --- a/packages/super-editor/src/headless-toolbar/toolbar-registry.ts +++ b/packages/super-editor/src/headless-toolbar/toolbar-registry.ts @@ -8,6 +8,8 @@ import { createRulerExecute, createRulerStateDeriver, createZoomExecute, + createZoomFitWidthExecute, + createZoomFitWidthStateDeriver, createZoomStateDeriver, } from './helpers/document.js'; import { @@ -187,6 +189,11 @@ export const createToolbarRegistry = (): Partial { expect(ok).toHaveBeenCalledTimes(2); }); }); + +describe('ui.zoom', () => { + let teardown: Array<() => void> = []; + + afterEach(() => { + teardown.forEach((fn) => fn()); + teardown = []; + }); + + const attachZoomSurface = (superdoc: ReturnType) => { + const zoomHost = { + state: { + mode: 'manual' as 'manual' | 'fit-width', + value: 100, + fitZoom: null as number | null, + min: 10, + max: 100, + }, + metrics: null as { availableWidth: number; documentWidth: number; fitZoom: number } | null, + setZoom: vi.fn(), + setZoomMode: vi.fn(), + }; + superdoc.getZoomState = vi.fn(() => ({ ...zoomHost.state })); + superdoc.getViewportMetrics = vi.fn(() => zoomHost.metrics); + superdoc.setZoom = zoomHost.setZoom; + superdoc.setZoomMode = zoomHost.setZoomMode; + return zoomHost; + }; + + it('degrades to a static manual/100 snapshot when the host lacks the zoom surface', () => { + const superdoc = makeSuperdocStub(); + const ui = createSuperDocUI({ superdoc }); + teardown.push(() => ui.destroy()); + + expect(ui.zoom.getSnapshot()).toEqual({ + mode: 'manual', + value: 100, + fitZoom: null, + min: 10, + max: 100, + metrics: null, + }); + // Mutations are no-ops, not crashes. + expect(() => ui.zoom.set(150)).not.toThrow(); + expect(() => ui.zoom.setMode('fit-width')).not.toThrow(); + }); + + it('snapshots the host zoom state and metrics', () => { + const superdoc = makeSuperdocStub(); + const zoomHost = attachZoomSurface(superdoc); + zoomHost.state = { mode: 'fit-width', value: 84, fitZoom: 84, min: 25, max: 100 }; + zoomHost.metrics = { availableWidth: 685, documentWidth: 816, fitZoom: 84 }; + + const ui = createSuperDocUI({ superdoc }); + teardown.push(() => ui.destroy()); + + expect(ui.zoom.getSnapshot()).toEqual({ + mode: 'fit-width', + value: 84, + fitZoom: 84, + min: 25, + max: 100, + metrics: { availableWidth: 685, documentWidth: 816, fitZoom: 84 }, + }); + }); + + it('observes mode-only transitions via zoomChange', async () => { + const superdoc = makeSuperdocStub(); + const zoomHost = attachZoomSurface(superdoc); + + const ui = createSuperDocUI({ superdoc }); + teardown.push(() => ui.destroy()); + + const cb = vi.fn(); + teardown.push(ui.zoom.observe(cb)); + expect(cb).toHaveBeenCalledTimes(1); + expect(cb.mock.calls[0][0].mode).toBe('manual'); + + zoomHost.state = { ...zoomHost.state, mode: 'fit-width' }; + superdoc.fireSuperdoc('zoomChange', { zoom: 100, mode: 'fit-width' }); + await flushMicrotasks(); + + expect(cb).toHaveBeenCalledTimes(2); + expect(cb.mock.calls[1][0].mode).toBe('fit-width'); + expect(cb.mock.calls[1][0].value).toBe(100); + }); + + it('observes viewport metric updates via viewport-change', async () => { + const superdoc = makeSuperdocStub(); + const zoomHost = attachZoomSurface(superdoc); + + const ui = createSuperDocUI({ superdoc }); + teardown.push(() => ui.destroy()); + + const cb = vi.fn(); + teardown.push(ui.zoom.observe(cb)); + expect(cb).toHaveBeenCalledTimes(1); + + zoomHost.state = { ...zoomHost.state, fitZoom: 74 }; + zoomHost.metrics = { availableWidth: 600, documentWidth: 816, fitZoom: 74 }; + superdoc.fireSuperdoc('viewport-change', zoomHost.metrics); + await flushMicrotasks(); + + expect(cb).toHaveBeenCalledTimes(2); + expect(cb.mock.calls[1][0].fitZoom).toBe(74); + expect(cb.mock.calls[1][0].metrics).toEqual({ availableWidth: 600, documentWidth: 816, fitZoom: 74 }); + }); + + it('does not re-fire observers when zoom state is unchanged', async () => { + const superdoc = makeSuperdocStub(); + attachZoomSurface(superdoc); + + const ui = createSuperDocUI({ superdoc }); + teardown.push(() => ui.destroy()); + + const cb = vi.fn(); + teardown.push(ui.zoom.observe(cb)); + expect(cb).toHaveBeenCalledTimes(1); + + // Unrelated recompute trigger with identical zoom state. + superdoc.fireSuperdoc('document-mode-change', { documentMode: 'viewing' }); + await flushMicrotasks(); + + expect(cb).toHaveBeenCalledTimes(1); + }); + + it('routes set and setMode to the host zoom surface', () => { + const superdoc = makeSuperdocStub(); + const zoomHost = attachZoomSurface(superdoc); + + const ui = createSuperDocUI({ superdoc }); + teardown.push(() => ui.destroy()); + + ui.zoom.set(125); + expect(zoomHost.setZoom).toHaveBeenCalledWith(125); + + ui.zoom.setMode('fit-width'); + expect(zoomHost.setZoomMode).toHaveBeenCalledWith('fit-width'); + }); +}); diff --git a/packages/super-editor/src/ui/create-super-doc-ui.ts b/packages/super-editor/src/ui/create-super-doc-ui.ts index e577285f62..84e46a51b1 100644 --- a/packages/super-editor/src/ui/create-super-doc-ui.ts +++ b/packages/super-editor/src/ui/create-super-doc-ui.ts @@ -72,6 +72,9 @@ import type { ContentControlFocusResult, ViewportRect, ViewportRectResult, + ZoomHandle, + ZoomMode, + ZoomSlice, } from './types.js'; /** @@ -110,7 +113,7 @@ const EDITOR_EVENTS = [ */ const LIST_REFRESH_EVENTS = ['commentsUpdate', 'commentsLoaded', 'tracked-changes-changed'] as const; -const SUPERDOC_EVENTS = ['editorCreate', 'document-mode-change', 'zoomChange'] as const; +const SUPERDOC_EVENTS = ['editorCreate', 'document-mode-change', 'zoomChange', 'viewport-change'] as const; /** * Presentation-editor events the controller listens to. These signal @@ -701,6 +704,64 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI { * either field, but they do trigger computeState rebuilds). */ let documentMemo: { slice: DocumentSlice } | null = null; + let zoomMemo: { slice: ZoomSlice } | null = null; + + // Static fallback for hosts without the zoom surface (older builds, + // minimal stubs): manual mode at 100% with no metrics. + const FALLBACK_ZOOM_SLICE: ZoomSlice = Object.freeze({ + mode: 'manual', + value: 100, + fitZoom: null, + min: 10, + max: 100, + metrics: null, + }); + + // Read the host zoom state + metrics into one slice. Memoized on the + // field values. Metrics compare by reference, which is equivalent to a + // field-wise compare because the host's viewport-fit store replaces the + // (frozen) metrics object only when a field actually changed; if that + // invariant moves, switch this to field-wise. `shallowEqual` on + // `state.zoom` then short-circuits `ui.zoom.observe` while nothing + // zoom-related changes. + const computeZoomSlice = (): ZoomSlice => { + if (typeof superdoc.getZoomState !== 'function') return FALLBACK_ZOOM_SLICE; + let state: ReturnType> | null = null; + try { + state = superdoc.getZoomState(); + } catch { + state = null; + } + if (!state) return FALLBACK_ZOOM_SLICE; + let metrics: ZoomSlice['metrics'] = null; + try { + metrics = superdoc.getViewportMetrics?.() ?? null; + } catch { + metrics = null; + } + const prev = zoomMemo?.slice; + if ( + prev && + prev.mode === state.mode && + prev.value === state.value && + prev.fitZoom === state.fitZoom && + prev.min === state.min && + prev.max === state.max && + prev.metrics === metrics + ) { + return prev; + } + const slice: ZoomSlice = { + mode: state.mode, + value: state.value, + fitZoom: state.fitZoom, + min: state.min, + max: state.max, + metrics, + }; + zoomMemo = { slice }; + return slice; + }; /** * Internal dirty flag. Flipped to `true` by any editor transaction @@ -937,6 +998,7 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI { documentMode, document: documentSlice, selection: selectionSlice, + zoom: computeZoomSlice(), toolbar: { context: toolbarSnapshot.context, commands: builtInCommands } as ToolbarSnapshotSlice, comments: { total: commentsListCache.total, @@ -1034,7 +1096,21 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI { }; // zoomChange fires *before* the re-render, so notifying then would hand // consumers stale rects. Tag the next post-paint layout flush as 'zoom'. - const onGeometryZoom = () => { + // Only a changed VALUE schedules a repaint; mode-only transitions + // (setZoomMode with an unchanged value) would latch a tag no flush ever + // consumes, mis-labeling the next unrelated layout notification. + let lastGeometryZoomValue: number | null = (() => { + try { + return superdoc.getZoomState?.().value ?? null; + } catch { + return null; + } + })(); + const onGeometryZoom = (...args: unknown[]) => { + const payload = args[0] as { zoom?: number } | undefined; + const nextZoom = typeof payload?.zoom === 'number' ? payload.zoom : null; + if (nextZoom !== null && nextZoom === lastGeometryZoomValue) return; + lastGeometryZoomValue = nextZoom; zoomPending = true; }; const onGeometryLayout = () => { @@ -2328,6 +2404,42 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI { }, }; + // ---- ui.zoom ----------------------------------------------------------- + // One slice for zoom UIs (mode, value, fit zoom, bounds, metrics) plus + // the two mutations. Recomputes on the host's zoomChange (which now + // includes mode-only transitions) and viewport-change events; both are + // in SUPERDOC_EVENTS. + const zoom: ZoomHandle = { + getSnapshot: () => computeState().zoom, + observe(listener) { + return select((state) => state.zoom, shallowEqual).subscribe((snapshot) => { + try { + listener(snapshot); + } catch { + // see scheduleNotify + } + }); + }, + set(percent: number) { + const setter = superdoc.setZoom; + if (typeof setter !== 'function') return; + try { + setter.call(superdoc, percent); + } catch (err) { + console.error('[superdoc/ui] ui.zoom.set failed:', err); + } + }, + setMode(mode: ZoomMode) { + const setter = superdoc.setZoomMode; + if (typeof setter !== 'function') return; + try { + setter.call(superdoc, mode); + } catch (err) { + console.error('[superdoc/ui] ui.zoom.setMode failed:', err); + } + }, + }; + // Live scopes created via `ui.createScope()`. The controller's // `destroy()` cascades into every entry before tearing down its own // resources, so consumers do not need to call `scope.destroy()` @@ -2597,6 +2709,7 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI { selection, viewport, document, + zoom, createScope: createScopeFn, destroy, }; diff --git a/packages/super-editor/src/ui/index.ts b/packages/super-editor/src/ui/index.ts index 68e778013e..e3594e6773 100644 --- a/packages/super-editor/src/ui/index.ts +++ b/packages/super-editor/src/ui/index.ts @@ -148,4 +148,8 @@ export type { DocumentExportInput, DocumentHandle, DocumentSlice, + ZoomHandle, + ZoomMode, + ZoomSlice, + ZoomViewportMetrics, } from './types.js'; diff --git a/packages/super-editor/src/ui/react/hooks.ts b/packages/super-editor/src/ui/react/hooks.ts index 7beba5ca28..aa92e0d9fd 100644 --- a/packages/super-editor/src/ui/react/hooks.ts +++ b/packages/super-editor/src/ui/react/hooks.ts @@ -1,4 +1,4 @@ -import { useEffect, useState } from 'react'; +import { useCallback, useEffect, useMemo, useState } from 'react'; import { shallowEqual } from '../equality.js'; import type { CommentsSlice, @@ -8,6 +8,8 @@ import type { SelectionSlice, ToolbarSnapshotSlice, UIToolbarCommandState, + ZoomMode, + ZoomSlice, } from '../types.js'; import { useSuperDocSlice, useSuperDocUI } from './provider.js'; @@ -87,6 +89,61 @@ export function useSuperDocDocument(): DocumentSlice { return useSuperDocSlice((ui) => ui.select((state) => state.document, shallowEqual), EMPTY_DOCUMENT); } +const EMPTY_ZOOM: ZoomSlice = { + mode: 'manual', + value: 100, + fitZoom: null, + min: 10, + max: 100, + metrics: null, +}; + +/** + * Zoom state + actions for custom zoom UIs. The snapshot updates on + * value changes, mode-only transitions, and viewport metric updates; + * `set(percent)` switches the host to manual mode by contract, + * `setMode('fit-width')` re-enters automatic fitting. + * + * ```tsx + * const zoom = useSuperDocZoom(); + * return ( + * <> + * {zoom.value}% + * + * + * ); + * ``` + */ +export function useSuperDocZoom(): ZoomSlice & { + set: (percent: number) => void; + setMode: (mode: ZoomMode) => void; +} { + const ui = useSuperDocUI(); + const slice = useSuperDocSlice((controller) => controller.select((state) => state.zoom, shallowEqual), EMPTY_ZOOM); + const set = useCallback( + (percent: number) => { + ui?.zoom.set(percent); + }, + [ui], + ); + const setMode = useCallback( + (mode: ZoomMode) => { + ui?.zoom.setMode(mode); + }, + [ui], + ); + // Memoized so the returned object keeps its identity while the slice and + // actions are unchanged; the controller-side slice memo makes `slice` + // reference-stable, and effects keyed on this hook's result must not + // re-run on unrelated parent renders. + return useMemo(() => ({ ...slice, set, setMode }), [slice, set, setMode]); +} + const FALLBACK_COMMAND_STATE: UIToolbarCommandState = { active: false, disabled: true, diff --git a/packages/super-editor/src/ui/react/index.ts b/packages/super-editor/src/ui/react/index.ts index a285bb6c15..3f0ea99465 100644 --- a/packages/super-editor/src/ui/react/index.ts +++ b/packages/super-editor/src/ui/react/index.ts @@ -38,4 +38,5 @@ export { useSuperDocToolbar, useSuperDocCommand, useSuperDocDocument, + useSuperDocZoom, } from './hooks.js'; diff --git a/packages/super-editor/src/ui/types.ts b/packages/super-editor/src/ui/types.ts index 2169b66ef9..16e7077842 100644 --- a/packages/super-editor/src/ui/types.ts +++ b/packages/super-editor/src/ui/types.ts @@ -36,12 +36,12 @@ export interface Subscribable { /** * Event names the UI controller (`createSuperDocUI`) subscribes to on - * a SuperDoc-like host. Narrower than - * `HeadlessToolbarSuperdocHostEvent` (which adds - * `formatting-marks-change`); a custom UI host stub only has to - * support the three events the UI controller actually consumes. + * a SuperDoc-like host. Differs from `HeadlessToolbarSuperdocHostEvent` + * (which adds `formatting-marks-change` but not `viewport-change`); a + * custom UI host stub only has to support the four events the UI + * controller actually consumes. */ -export type SuperDocUIHostEvent = 'editorCreate' | 'document-mode-change' | 'zoomChange'; +export type SuperDocUIHostEvent = 'editorCreate' | 'document-mode-change' | 'zoomChange' | 'viewport-change'; /** * Structural typing for the SuperDoc instance. Keeps the UI controller @@ -82,6 +82,42 @@ export interface SuperDocLike { * browser test stubs stay valid without a host implementation. */ export?(options?: DocumentExportInput): Promise; + /** + * Optional zoom bridge consumed by `ui.zoom`. Mirrors the superdoc + * package's zoom surface (`setZoom` switches the mode to manual, + * `setZoomMode` toggles fitting, the getters snapshot state and + * viewport metrics). All optional so stubs and older hosts stay + * valid; `ui.zoom` degrades to a static manual/100 snapshot. + */ + setZoom?(percent: number): unknown; + setZoomMode?(mode: ZoomMode): unknown; + getZoomState?(): { + mode: ZoomMode; + value: number; + fitZoom: number | null; + min: number; + max: number; + }; + getViewportMetrics?(): ZoomViewportMetrics | null; +} + +/** + * Zoom mode mirrored from the superdoc package: `manual` holds the + * last-set value, `fit-width` continuously re-fits to the container. + */ +export type ZoomMode = 'manual' | 'fit-width'; + +/** + * Pure viewport measurements mirrored from the superdoc package's + * `viewport-change` payload / `getViewportMetrics()`. + */ +export interface ZoomViewportMetrics { + /** Width available to the document in pixels (container minus the comments sidebar). */ + availableWidth: number; + /** Widest document page width in pixels at 100% zoom. */ + documentWidth: number; + /** Unclamped zoom percentage that fits the document in the available width. */ + fitZoom: number; } export interface SuperDocEditorLike { @@ -309,6 +345,33 @@ export interface SuperDocUIState { * document transactions; `activeIds` derives from the selection. */ contentControls: ContentControlsSlice; + /** + * Zoom slice. Sourced from the host's `getZoomState()` / + * `getViewportMetrics()` and recomputed on `zoomChange` / + * `viewport-change`. Hosts without the zoom surface yield a static + * manual/100 snapshot. + */ + zoom: ZoomSlice; +} + +/** + * Zoom snapshot exposed on `state.zoom` and through `ui.zoom`. Combines + * the host's zoom state (mode, value, fit bounds) with the latest + * viewport metrics so a zoom UI renders from one slice. + */ +export interface ZoomSlice { + /** Current zoom mode. */ + mode: ZoomMode; + /** Current zoom value as a percentage. */ + value: number; + /** Latest unclamped fit zoom, or `null` before the first viewport measurement. */ + fitZoom: number | null; + /** Effective lower bound of the fit-width policy. */ + min: number; + /** Effective upper bound of the fit-width policy. */ + max: number; + /** Latest viewport measurements, or `null` before editors mount. */ + metrics: ZoomViewportMetrics | null; } /** @@ -811,6 +874,17 @@ export interface SuperDocUI { */ document: DocumentHandle; + /** + * Zoom domain. One slice for zoom UIs (mode, value, fit zoom, + * bounds, viewport metrics) plus the two mutations: `set(percent)` + * (numeric zoom, switches the host to manual mode) and + * `setMode('fit-width' | 'manual')`. Sugar over `state.zoom` and + * passthroughs to the host's `setZoom` / `setZoomMode`; the slice + * recomputes on the host's `zoomChange` and `viewport-change` + * events, including mode-only transitions. + */ + zoom: ZoomHandle; + /** * Create a {@link SuperDocUIScope} for collecting subscriptions, * custom-command registrations, and DOM listeners under one @@ -1048,6 +1122,36 @@ export interface DocumentHandle { replaceFile(file: File): Promise; } +/** + * Zoom domain handle (`ui.zoom`). Read / observe the {@link ZoomSlice} + * and mutate through the host's zoom surface. Hosts without zoom + * methods (older builds, minimal stubs) degrade gracefully: the slice + * is a static manual/100 snapshot and the mutations are no-ops. + */ +export interface ZoomHandle { + /** Current zoom snapshot. */ + getSnapshot(): ZoomSlice; + /** + * Subscribe to zoom snapshots. Fires on value changes, mode-only + * transitions, and fit-relevant viewport metric updates (the host's + * deduped `viewport-change`); `getSnapshot()` always reads the + * latest stored metrics. Returns the unsubscribe function; pair + * with `scope.add(...)` for lifecycle handling. + */ + observe(listener: (snapshot: ZoomSlice) => void): () => void; + /** + * Set a numeric zoom percentage. Routes through `superdoc.setZoom`, + * which switches the mode to `manual` by contract. + */ + set(percent: number): void; + /** + * Switch the zoom mode. Routes through `superdoc.setZoomMode`; + * `'fit-width'` applies the fit immediately when viewport metrics + * are available. + */ + setMode(mode: ZoomMode): void; +} + /** * Selection domain handle exposed on `ui.selection`. Same shape as * `CommentsHandle` / `TrackChangesHandle`: snapshot + subscription. Mirrors diff --git a/packages/superdoc/package.json b/packages/superdoc/package.json index 0484dc8387..5c2648d27f 100644 --- a/packages/superdoc/package.json +++ b/packages/superdoc/package.json @@ -193,7 +193,6 @@ "@hocuspocus/provider": "catalog:", "@hocuspocus/server": "catalog:", "@superdoc-dev/superdoc-yjs-collaboration": "workspace:*", - "@types/uuid": "catalog:", "@superdoc/common": "workspace:*", "@superdoc/contracts": "workspace:*", "@superdoc/super-editor": "workspace:*", diff --git a/packages/superdoc/scripts/README.md b/packages/superdoc/scripts/README.md index 446c9a5758..c54ca5a41e 100644 --- a/packages/superdoc/scripts/README.md +++ b/packages/superdoc/scripts/README.md @@ -54,6 +54,7 @@ but have separate script chains because the validation needs differ. | `check:public` | `check:public:superdoc` + `check:public:docapi` | Both public interfaces. The umbrella to run before merging. | | `check:public:superdoc` | `check:public-contract` (legacy alias) | SuperDoc package: vite build + postbuild chain, consumer typecheck matrix, deep-type audit. | | `check:public:docapi` | `docapi:check` (legacy alias) | Document API: contract parity, generated outputs are not stale, examples compile, overview alignment. Clean-checkout safe: gitignored outputs (`packages/document-api/generated/`) are built in memory; tracked outputs (`apps/docs/document-api/reference/`, overview block) are still compared byte-for-byte. | +| `check:font-licenses` | `node shared/font-system/scripts/check-bundled-font-licenses.mjs` | Bundled font compliance: every shipped WOFF2 has legal metadata, stable hash, notices, and a runtime manifest entry. Also runs inside `check:public:superdoc`. | | `report:public:superdoc` | `report:public-contract` (legacy alias) | Read-only tier metadata (supported / legacy / legacy-raw / asset / deprecated). Not a gate. | ### TypeScript compiler @@ -152,7 +153,9 @@ what an actual consumer would see — not the workspace source. Seven of these run as wrapper stages of `check:public:superdoc`. `public-method-coverage` runs alongside the cheap policy gates (`contract-tiers-test`, `contract-tiers`, `jsdoc-ratchet`, -`jsdoc-hygiene-ts-test`, `jsdoc-hygiene-ts`) before `build`. The other +`jsdoc-hygiene-ts-test`, `jsdoc-hygiene-ts`). `font-license-gate` +runs after those cheap gates and before `build`, so a new bundled font +without a legal manifest row or notices fails before packaging. The other six run after `build`: `consumer-typecheck-matrix`, `deep-type-audit-supported-root`, `package-shape`, `export-snapshots`, `root-classification-closure`, diff --git a/packages/superdoc/src/SuperDoc.test.js b/packages/superdoc/src/SuperDoc.test.js index 700a1aa1c2..dd72c75a1d 100644 --- a/packages/superdoc/src/SuperDoc.test.js +++ b/packages/superdoc/src/SuperDoc.test.js @@ -1,7 +1,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import { mount } from '@vue/test-utils'; import { h, defineComponent, ref, shallowRef, reactive, nextTick } from 'vue'; -import { DOCX } from '@superdoc/common'; +import { DOCX, PDF } from '@superdoc/common'; import { Schema } from 'prosemirror-model'; import { EditorState, TextSelection } from 'prosemirror-state'; import { Mapping, StepMap } from 'prosemirror-transform'; @@ -104,6 +104,15 @@ const CommentsLayerStub = stubComponent('CommentsLayer'); const HrbrFieldsLayerStub = stubComponent('HrbrFieldsLayer'); const AiLayerStub = stubComponent('AiLayer'); const HtmlViewerStub = stubComponent('HtmlViewer'); +const PdfViewerStub = defineComponent({ + name: 'PdfViewer', + props: ['file', 'fileId', 'config', 'initialScale'], + emits: ['page-rendered', 'document-ready', 'selection-raw', 'bypass-selection'], + setup(_props, { expose }) { + expose({ updateScale: vi.fn() }); + return () => h('div', { class: 'sd-pdf-viewer' }); + }, +}); const createTrackedChangeIndexStub = () => ({ subscribe: vi.fn(() => () => {}), @@ -145,6 +154,16 @@ vi.mock('./components/HtmlViewer/HtmlViewer.vue', () => ({ default: HtmlViewerStub, })); +vi.mock('./components/PdfViewer/PdfViewer.vue', () => ({ + // SuperDoc.vue loads PdfViewer through defineAsyncComponent, so Vue + // receives this module namespace and interop-probes it (__isTeleport + // etc.); vitest's strict mock proxy throws on undeclared exports. The + // __esModule flag makes Vue's resolver take `default` immediately, + // before any probing. + __esModule: true, + default: PdfViewerStub, +})); + vi.mock('@superdoc/components/CommentsLayer/CommentDialog.vue', () => ({ default: CommentDialogStub, })); @@ -189,6 +208,8 @@ const buildSuperdocStore = () => { selectionPosition: ref(null), activeSelection: ref(null), activeZoom: ref(100), + zoomMode: ref('manual'), + viewportMetrics: ref(null), modules: reactive({ comments: { readOnly: false }, ai: {}, 'hrbr-fields': [] }), handlePageReady: vi.fn(), user: { name: 'Ada', email: 'ada@example.com' }, @@ -338,6 +359,7 @@ const mountComponent = async ( const createSuperdocStub = () => { const toolbar = { config: { aiApiKey: 'abc' }, setActiveEditor: vi.fn(), updateToolbarState: vi.fn() }; const runtimeMap = new Map(); + const eventHandlers = new Map(); return { config: { modules: { comments: {}, ai: {}, toolbar: {}, pdf: {} }, @@ -365,8 +387,24 @@ const createSuperdocStub = () => { getActiveRuntime: vi.fn(() => null), activateRuntimeFromEventTarget: vi.fn(() => false), lockSuperdoc: vi.fn(), - emit: vi.fn(), - listeners: vi.fn(), + on: vi.fn((eventName, handler) => { + const handlers = eventHandlers.get(eventName) ?? new Set(); + handlers.add(handler); + eventHandlers.set(eventName, handlers); + return undefined; + }), + off: vi.fn((eventName, handler) => { + eventHandlers.get(eventName)?.delete(handler); + return undefined; + }), + emit: vi.fn((eventName, payload) => { + const handlers = eventHandlers.get(eventName); + if (handlers) { + for (const handler of [...handlers]) handler(payload); + } + return true; + }), + listeners: vi.fn((eventName) => [...(eventHandlers.get(eventName) ?? [])]), captureLayoutPipelineEvent: vi.fn(), canPerformPermission: vi.fn(() => true), }; @@ -2914,4 +2952,462 @@ describe('SuperDoc.vue', () => { const styleVars = wrapper.vm.superdocStyleVars; expect(styleVars['--sd-comments-highlight-hover']).toBe('#abcdef88'); }); + + describe('viewport-change + fit-to-container', () => { + // Letter page: 8.5in * 96 = 816px base width through the page-styles path. + const stubPageStylesEditor = (superdocStub) => { + superdocStub.activeEditor = { + getPageStyles: vi.fn(() => ({ pageSize: { width: 8.5, height: 11 } })), + }; + }; + + const setContainerWidth = (wrapper, width) => { + const rootEl = wrapper.find('.superdoc').element; + const parentEl = rootEl.parentElement; + Object.defineProperty(rootEl, 'clientWidth', { configurable: true, value: width }); + if (parentEl) Object.defineProperty(parentEl, 'clientWidth', { configurable: true, value: width }); + }; + + const viewportChangeCalls = (superdocStub) => + superdocStub.emit.mock.calls.filter(([name]) => name === 'viewport-change'); + + it('does not emit viewport-change before isReady', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + + const wrapper = await mountComponent(superdocStub); + superdocStoreStub.isReady.value = false; + await nextTick(); + + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + await nextTick(); + + expect(viewportChangeCalls(superdocStub).length).toBe(0); + }); + + it('emits viewport-change with page-styles-derived widths when ready', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + expect(calls[0][1]).toEqual({ + availableWidth: 1200, + documentWidth: 816, + fitZoom: 147, + }); + }); + + it('keeps documentWidth zoom-independent (page styles win over scaled DOM)', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + + const wrapper = await mountComponent(superdocStub); + // A zoom applied before the first measurement must not corrupt the base. + superdocStoreStub.activeZoom.value = 50; + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + expect(calls[0][1].documentWidth).toBe(816); + expect(calls[0][1].fitZoom).toBe(147); + }); + + it('falls back to page styles when laid-out pages are unavailable', async () => { + const superdocStub = createSuperdocStub(); + superdocStub.activeEditor = { + getPages: vi.fn(() => { + throw new Error('layout not ready'); + }), + getPageStyles: vi.fn(() => ({ pageSize: { width: 8.5, height: 11 } })), + }; + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + expect(calls[0][1]).toEqual({ + availableWidth: 1200, + documentWidth: 816, + fitZoom: 147, + }); + }); + + it('dedupes width changes that round to the same fit', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + // 1199 / 816 rounds to the same fitZoom (147) as 1200 / 816. + setContainerWidth(wrapper, 1199); + wrapper.vm.recalculateCompactCommentsMode(); + await nextTick(); + await nextTick(); + + expect(viewportChangeCalls(superdocStub).length).toBe(1); + // The event dedupes, but stored metrics stay latest: reads must see + // the 1199 measurement the deduped event skipped. + expect(superdocStoreStub.viewportMetrics.value.availableWidth).toBe(1199); + + // A materially different width emits again. + setContainerWidth(wrapper, 600); + wrapper.vm.recalculateCompactCommentsMode(); + await nextTick(); + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(2); + expect(calls[1][1].fitZoom).toBe(74); + }); + + it('skips emission entirely while no document width is measurable', async () => { + const superdocStub = createSuperdocStub(); + // No activeEditor and no laid-out DOM: base width unresolvable. + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + expect(viewportChangeCalls(superdocStub).length).toBe(0); + }); + + it('does not scan PDF page DOM for DOCX-only documents', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + + const wrapper = await mountComponent(superdocStub); + const rootEl = wrapper.find('.superdoc').element; + const querySelectorAllSpy = vi.spyOn(rootEl, 'querySelectorAll'); + + const pageEl = document.createElement('div'); + pageEl.className = 'sd-pdf-viewer-page'; + rootEl.appendChild(pageEl); + + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + expect(querySelectorAllSpy).not.toHaveBeenCalledWith('.sd-pdf-viewer-page'); + expect(viewportChangeCalls(superdocStub)[0][1].documentWidth).toBe(816); + }); + + const zoomChangeCalls = (superdocStub) => superdocStub.emit.mock.calls.filter(([name]) => name === 'zoomChange'); + + it('stores the latest metrics for getViewportMetrics()', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + expect(superdocStoreStub.viewportMetrics.value).toEqual({ + availableWidth: 1200, + documentWidth: 816, + fitZoom: 147, + }); + }); + + it('fit-width mode applies the fit with default clamping (max 100)', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + superdocStub.config.zoom = { mode: 'fit-width' }; + + const wrapper = await mountComponent(superdocStub); + superdocStoreStub.zoomMode.value = 'fit-width'; + setContainerWidth(wrapper, 600); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + // fitZoom = 600 / 816 = 74; within [10, 100] so applied as-is. The + // fit writes the store directly (setZoom would flip mode to manual). + expect(superdocStoreStub.activeZoom.value).toBe(74); + expect(zoomChangeCalls(superdocStub)).toEqual([['zoomChange', { zoom: 74, mode: 'fit-width' }]]); + expect(viewportChangeCalls(superdocStub)[0][1].fitZoom).toBe(74); + }); + + it('clamps the applied fit but emits the raw fitZoom', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + superdocStub.config.zoom = { mode: 'fit-width', fitWidth: { min: 80 } }; + + const wrapper = await mountComponent(superdocStub); + superdocStoreStub.zoomMode.value = 'fit-width'; + setContainerWidth(wrapper, 408); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + // Raw fit is 50 (408 / 816); applied value clamps to min 80. + expect(viewportChangeCalls(superdocStub)[0][1].fitZoom).toBe(50); + expect(superdocStoreStub.activeZoom.value).toBe(80); + }); + + it('padding shapes the applied fit only, never the metrics', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + superdocStub.config.zoom = { mode: 'fit-width', fitWidth: { padding: 96 } }; + + const wrapper = await mountComponent(superdocStub); + superdocStoreStub.zoomMode.value = 'fit-width'; + superdocStoreStub.activeZoom.value = 50; + setContainerWidth(wrapper, 912); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + // Metrics are policy-free: availableWidth stays 912 and fitZoom is + // the raw ratio. The applied fit reserves the padding: (912 - 96) / + // 816 = 100. + expect(viewportChangeCalls(superdocStub)[0][1]).toEqual({ + availableWidth: 912, + documentWidth: 816, + fitZoom: 112, + }); + expect(superdocStoreStub.activeZoom.value).toBe(100); + }); + + it('subtracts the comments sidebar width through the owned template ref', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + + const wrapper = await mountComponent(superdocStub); + commentsStoreStub.pendingComment.value = { commentId: 'pending-1', selection: { selectionBounds: {} } }; + await nextTick(); + + const sidebarEl = wrapper.find('.superdoc__right-sidebar').element; + Object.defineProperty(sidebarEl, 'offsetWidth', { configurable: true, value: 240 }); + + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + expect(calls[0][1]).toEqual({ + availableWidth: 960, + documentWidth: 816, + fitZoom: 118, + }); + }); + + it('does not re-apply zoom when the target equals the current zoom', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + superdocStub.config.zoom = { mode: 'fit-width' }; + + const wrapper = await mountComponent(superdocStub); + superdocStoreStub.zoomMode.value = 'fit-width'; + superdocStoreStub.activeZoom.value = 74; + setContainerWidth(wrapper, 600); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + // Same-value guard: target 74 equals current zoom, so no write and + // no zoomChange, while the viewport-change event still emits. + expect(superdocStoreStub.activeZoom.value).toBe(74); + expect(zoomChangeCalls(superdocStub).length).toBe(0); + expect(viewportChangeCalls(superdocStub).length).toBe(1); + }); + + it('manual mode never applies the fit (metrics still emit)', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + superdocStub.config.zoom = { fitWidth: { min: 25 } }; + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 600); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + expect(viewportChangeCalls(superdocStub).length).toBe(1); + expect(superdocStoreStub.activeZoom.value).toBe(100); + expect(zoomChangeCalls(superdocStub).length).toBe(0); + }); + + it('switching zoomMode to fit-width applies the fit immediately', async () => { + const superdocStub = createSuperdocStub(); + stubPageStylesEditor(superdocStub); + superdocStub.config.zoom = {}; + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 600); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + expect(superdocStoreStub.activeZoom.value).toBe(100); + + superdocStoreStub.zoomMode.value = 'fit-width'; + await nextTick(); + + expect(superdocStoreStub.activeZoom.value).toBe(74); + expect(zoomChangeCalls(superdocStub)).toEqual([['zoomChange', { zoom: 74, mode: 'fit-width' }]]); + }); + + it('resolves documentWidth as the widest page across documents', async () => { + const superdocStub = createSuperdocStub(); + + const wrapper = await mountComponent(superdocStub); + // Two DOCX documents: portrait letter (8.5in) and landscape (11in). + // Zoom is global, so the fit must target the widest page. + superdocStoreStub.documents.value = [ + { + id: 'doc-portrait', + type: DOCX, + editorMountNonce: ref(0), + getEditor: vi.fn(() => ({ getPageStyles: () => ({ pageSize: { width: 8.5, height: 11 } }) })), + setEditor: vi.fn(), + }, + { + id: 'doc-landscape', + type: DOCX, + editorMountNonce: ref(0), + getEditor: vi.fn(() => ({ getPageStyles: () => ({ pageSize: { width: 11, height: 8.5 } }) })), + setEditor: vi.fn(), + }, + ]; + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + // 11in * 96 = 1056: the widest page wins over 816. + expect(calls[0][1].documentWidth).toBe(1056); + expect(calls[0][1].fitZoom).toBe(114); + }); + + it('prefers the widest laid-out page over body page styles (landscape sections)', async () => { + const superdocStub = createSuperdocStub(); + // Portrait body section (8.5in) but a laid-out interior landscape + // page: the fit must target what the renderer paints (getPages max), + // exactly like SuperEditor's own container sizing. + superdocStub.activeEditor = { + getPages: vi.fn(() => [{ size: { w: 816 } }, { size: { w: 1056 } }]), + getPageStyles: vi.fn(() => ({ pageSize: { width: 8.5, height: 11 } })), + }; + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + expect(calls[0][1].documentWidth).toBe(1056); + expect(calls[0][1].fitZoom).toBe(114); + }); + + it('re-evaluates document width after pagination updates', async () => { + const superdocStub = createSuperdocStub(); + let pages = [{ size: { w: 816 } }]; + superdocStub.activeEditor = { + getPages: vi.fn(() => pages), + getPageStyles: vi.fn(() => ({ pageSize: { width: 8.5, height: 11 } })), + }; + + const wrapper = await mountComponent(superdocStub); + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + expect(viewportChangeCalls(superdocStub)[0][1].documentWidth).toBe(816); + + pages = [{ size: { w: 816 } }, { size: { w: 1056 } }]; + superdocStub.emit.mockClear(); + superdocStub.emit('pagination-update', { totalPages: 2, superdoc: superdocStub }); + + expect(viewportChangeCalls(superdocStub).length).toBe(0); + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + expect(calls[0][1]).toEqual({ + availableWidth: 1200, + documentWidth: 1056, + fitZoom: 114, + }); + }); + + it('resolves PDF page width scale-relatively (zoom-sync state cannot corrupt the base)', async () => { + const superdocStub = createSuperdocStub(); + + const wrapper = await mountComponent(superdocStub); + superdocStoreStub.documents.value = [ + { + id: 'pdf-1', + type: PDF, + data: { name: 'doc.pdf' }, + editorMountNonce: ref(0), + setEditor: vi.fn(), + getEditor: vi.fn(() => null), + }, + ]; + await nextTick(); + + // A rendered 612pt PDF page at 50% viewer zoom measures 408px with + // --scale-factor 2/3 (zoom * 96/72). The store zoom claims 100% (a + // seeded zoom the viewer has not applied yet); the resolver must + // trust the page's actual scale factor and report 816 regardless. + const pageEl = document.createElement('div'); + pageEl.className = 'sd-pdf-viewer-page'; + Object.defineProperty(pageEl, 'clientWidth', { configurable: true, value: 408 }); + wrapper.find('.superdoc').element.appendChild(pageEl); + + const originalGetComputedStyle = window.getComputedStyle.bind(window); + const computedStyleSpy = vi.spyOn(window, 'getComputedStyle').mockImplementation((el, pseudo) => { + if (el === pageEl) { + return { getPropertyValue: (prop) => (prop === '--scale-factor' ? `${2 / 3}` : '') }; + } + return originalGetComputedStyle(el, pseudo); + }); + + try { + setContainerWidth(wrapper, 1200); + wrapper.vm.recalculateCompactCommentsMode(); + superdocStoreStub.isReady.value = true; + await nextTick(); + + const calls = viewportChangeCalls(superdocStub); + expect(calls.length).toBe(1); + expect(calls[0][1].documentWidth).toBeCloseTo(816, 6); + expect(calls[0][1].fitZoom).toBe(147); + } finally { + computedStyleSpy.mockRestore(); + } + }); + }); }); diff --git a/packages/superdoc/src/SuperDoc.vue b/packages/superdoc/src/SuperDoc.vue index 0328040cf2..33262f0dbe 100644 --- a/packages/superdoc/src/SuperDoc.vue +++ b/packages/superdoc/src/SuperDoc.vue @@ -50,6 +50,7 @@ import { useAi } from './composables/use-ai'; import { useHighContrastMode } from './composables/use-high-contrast-mode'; import { useCommentSmallScreen } from './composables/use-comment-small-screen.js'; import { useCompactCommentPopover } from './composables/use-compact-comment-popover.js'; +import { useViewportFit } from './composables/use-viewport-fit.js'; import { getVisibleThreadAnchorClientY } from './helpers/comment-focus.js'; import { useUiFontFamily } from './composables/useUiFontFamily.js'; import { usePasswordPrompt } from './composables/use-password-prompt.js'; @@ -81,6 +82,8 @@ const { selectionPosition, activeSelection, activeZoom, + zoomMode, + viewportMetrics, } = storeToRefs(superdocStore); const { handlePageReady, modules, user, getDocument } = superdocStore; @@ -221,6 +224,7 @@ const superdocStyleVars = computed(() => { // Refs const superdocRoot = ref(null); const layers = ref(null); +const rightSidebarRef = ref(null); const pdfViewerRef = ref(null); const pendingReplayTrackedChangeSync = ref(false); const toolsMenuPosition = reactive({ top: null, right: '-25px', zIndex: 101 }); @@ -349,6 +353,7 @@ const handleDocumentReady = (documentId, container) => { if (!proxy.$superdoc.config.collaboration) isReady.value = true; } + ensureInitialFallbackZoom(); isFloatingCommentsReady.value = true; hasInitializedLocations.value = true; proxy.$superdoc.broadcastPdfDocumentReady(); @@ -495,6 +500,9 @@ const onEditorCreate = ({ editor }) => { * @param {PresentationEditor} payload.presentationEditor - The PresentationEditor wrapper */ const onEditorReady = ({ editor, presentationEditor }) => { + // Legacy (non-layout-engine) editors return early below; the seeded + // initial zoom for their CSS-fallback transform must apply first. + ensureInitialFallbackZoom(); if (!presentationEditor) return; // Store presentationEditor reference for mode changes @@ -1432,6 +1440,21 @@ watch(showCommentsSidebar, (value) => { proxy.$superdoc.broadcastSidebarToggle(value); }); +// Viewport fit tracking: maintains viewport metrics, emits `viewport-change`, +// and applies the fit-width zoom policy. See composables/use-viewport-fit.js. +useViewportFit({ + getSuperdoc: () => proxy.$superdoc, + superdocContainerWidth, + isReady, + activeZoom, + zoomMode, + viewportMetrics, + showCommentsSidebar, + rightSidebarRef, + superdocRoot, + documents, +}); + /** * Scroll the page to a given commentId * @@ -1760,6 +1783,43 @@ const handlePdfSelectionRaw = ({ selectionBounds, documentId, page }) => { handleSelectionChange(selection); }; +// Web layout without layout engine - apply CSS transform directly +// to non-PDF sub-document containers so zoom works for PM fallback rendering. +// PDF documents are excluded because pdfViewer.updateScale() handles their zoom +// separately; applying both would result in double-zoom. +const applyFallbackZoomStyles = (zoomFactor) => { + const subDocs = layers.value?.querySelectorAll('.superdoc__sub-document'); + subDocs?.forEach((el) => { + if (el.querySelector('.sd-pdf-viewer')) return; + if (zoomFactor === 1) { + el.style.transformOrigin = ''; + el.style.transform = ''; + el.style.width = ''; + } else { + el.style.transformOrigin = 'top left'; + el.style.transform = `scale(${zoomFactor})`; + el.style.width = `${100 / zoomFactor}%`; + } + }); +}; + +// One-time initial application for surfaces that only consume zoom +// imperatively. A seeded `zoom.initial` never fires the activeZoom watcher +// (the ref starts at the seeded value), and the fallback transform targets +// elements that do not exist until documents render - so apply once from +// the per-document ready hooks. PresentationEditor and PdfViewer take +// their initial value at creation (layoutEngineOptions.zoom / +// :initial-scale) and need nothing here. +let initialFallbackZoomApplied = false; +const ensureInitialFallbackZoom = () => { + if (initialFallbackZoomApplied) return; + if (proxy.$superdoc.config.useLayoutEngine !== false) return; + const zoomFactor = (activeZoom.value ?? 100) / 100; + if (zoomFactor === 1) return; + initialFallbackZoomApplied = true; + nextTick(() => applyFallbackZoomStyles(zoomFactor)); +}; + watch( () => activeZoom.value, (zoom) => { @@ -1768,23 +1828,8 @@ watch( if (proxy.$superdoc.config.useLayoutEngine !== false) { PresentationEditor.setGlobalZoom(zoomFactor); } else { - // Web layout without layout engine — apply CSS transform directly - // to non-PDF sub-document containers so zoom works for PM fallback rendering. - // PDF documents are excluded because pdfViewer.updateScale() handles their zoom - // separately below; applying both would result in double-zoom. - const subDocs = layers.value?.querySelectorAll('.superdoc__sub-document'); - subDocs?.forEach((el) => { - if (el.querySelector('.sd-pdf-viewer')) return; - if (zoomFactor === 1) { - el.style.transformOrigin = ''; - el.style.transform = ''; - el.style.width = ''; - } else { - el.style.transformOrigin = 'top left'; - el.style.transform = `scale(${zoomFactor})`; - el.style.width = `${100 / zoomFactor}%`; - } - }); + initialFallbackZoomApplied = true; + applyFallbackZoomStyles(zoomFactor); } const pdfViewer = getPDFViewer(); @@ -1926,6 +1971,7 @@ const getPDFViewer = () => { v-if="doc.type === PDF" :file="doc.data" :file-id="doc.id" + :initial-scale="(activeZoom ?? 100) / 100" :config="pdfConfig" @selection-raw="handlePdfSelectionRaw" @bypass-selection="handlePdfClick" @@ -1956,7 +2002,7 @@ const getPDFViewer = () => { -
+
0 + ? floor(props.initialScale, 2) + : 1, +); const totalPages = ref(0); const renderedPages = ref(0); diff --git a/packages/superdoc/src/composables/use-viewport-fit.js b/packages/superdoc/src/composables/use-viewport-fit.js new file mode 100644 index 0000000000..4926b5d965 --- /dev/null +++ b/packages/superdoc/src/composables/use-viewport-fit.js @@ -0,0 +1,337 @@ +import { onBeforeUnmount, nextTick, watch } from 'vue'; +import { DOCX, PDF } from '@superdoc/common'; +import { PDF_TO_CSS_UNITS } from '@superdoc/core/pdf/helpers/constants.js'; + +const CSS_PX_PER_INCH = 96; +const SIDEBAR_SELECTOR = '.superdoc__right-sidebar'; +const PDF_PAGE_SELECTOR = '.sd-pdf-viewer-page'; + +export const FIT_WIDTH_DEFAULTS = Object.freeze({ + min: 10, + max: 100, + padding: 0, +}); + +// Normalize `config.zoom.fitWidth` into a complete options object. The mode +// (`config.zoom.mode` / `setZoomMode`) decides whether the policy applies; +// these are only its bounds. Invalid field values fall back to defaults; +// min/max are reordered if swapped. +export const resolveFitWidthOptions = (rawFitConfig) => { + const raw = rawFitConfig && typeof rawFitConfig === 'object' ? rawFitConfig : {}; + const positiveOr = (value, fallback) => + typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback; + const min = positiveOr(raw.min, FIT_WIDTH_DEFAULTS.min); + const max = positiveOr(raw.max, FIT_WIDTH_DEFAULTS.max); + const padding = + typeof raw.padding === 'number' && Number.isFinite(raw.padding) && raw.padding >= 0 + ? raw.padding + : FIT_WIDTH_DEFAULTS.padding; + + return { + min: Math.min(min, max), + max: Math.max(min, max), + padding, + }; +}; + +// Unclamped zoom percentage that fits `documentWidth` into `availableWidth`. +export const computeFitZoom = (availableWidth, documentWidth) => { + if (!(availableWidth > 0) || !(documentWidth > 0)) return null; + return Math.round((availableWidth / documentWidth) * 100); +}; + +// Applied zoom for the fit-width policy: padding reserved, then clamped. +// Floored at 1: fractional bounds (e.g. a factor-style min of 0.4) plus a +// degenerate container could otherwise round to 0, which the presentation +// engine rejects with a throw. +export const computeAppliedFitZoom = (availableWidth, documentWidth, options) => { + const padded = computeFitZoom(availableWidth - options.padding, documentWidth); + if (padded === null) return null; + return Math.max(1, Math.round(Math.min(options.max, Math.max(options.min, padded)))); +}; + +// One measured PDF page width back to CSS px at 100% zoom. PDF pages size +// via `calc(var(--scale-factor) * px)` where the scale factor is the +// viewer zoom times PDF_TO_CSS_UNITS (the same constant PdfViewerPage uses +// to write that variable), so dividing by the page's actual scale factor +// yields PDF points regardless of zoom-sync state, and multiplying by +// PDF_TO_CSS_UNITS converts back to CSS px at 100% zoom (verified live: a +// 612pt letter page renders 816 CSS px at 100%). Without a readable scale +// factor, fall back to dividing out the assumed zoom. +export const normalizePdfPageMeasurement = (measured, scaleFactor, zoomFactor) => { + if (!(measured > 0)) return null; + if (Number.isFinite(scaleFactor) && scaleFactor > 0) { + return (measured / scaleFactor) * PDF_TO_CSS_UNITS; + } + return zoomFactor > 0 ? measured / zoomFactor : measured; +}; + +/** + * Viewport fit tracking. Maintains pure viewport metrics (available width, + * document base width, fit zoom), stores them for `getViewportMetrics()`, + * emits `viewport-change` when the fit they imply changes, and applies the + * `fit-width` policy while `zoomMode` is `'fit-width'`. + * + * Metrics are policy-free measurements: `availableWidth` is the container + * width minus the comments sidebar when visible; `fitZoom` is the raw + * available/document ratio. The fit policy (and only the policy) accounts + * for `config.zoom.fitWidth` padding and clamping. + * + * The base page width is re-resolved on every evaluation (never latched): + * DOCX uses the widest laid-out page with page-styles fallback, PDF uses + * rendered pages normalized by their actual scale factor, and HTML reflows + * so it contributes no fixed width. A zoom-normalized DOM measurement is + * the last-resort fallback for a DOCX editor without page geometry. + * + * The fit application writes the zoom state directly instead of calling + * `setZoom()`, which by contract switches the mode to `manual`. + * + * Must be called inside a component `setup()` (registers watchers and an + * unmount hook). + */ +export function useViewportFit({ + getSuperdoc, + superdocContainerWidth, + isReady, + activeZoom, + zoomMode, + viewportMetrics, + showCommentsSidebar, + rightSidebarRef, + superdocRoot, + documents, +}) { + // Page width in CSS px at 100% zoom for one DOCX editor. Same two-tier + // source the renderer's own container sizing uses (SuperEditor.vue): + // the widest laid-out page first, so interior landscape or custom-width + // sections fit correctly, then the body section's page styles before + // pagination has produced pages. Both are zoom-independent. Like the + // renderer, the value converges as wider sections first render; the + // pagination-update hook re-evaluates on exactly that signal. + const resolveEditorPageWidth = (editor) => { + if (!editor) return null; + + let widestPage = 0; + try { + const pages = editor.getPages?.(); + if (Array.isArray(pages)) { + for (const page of pages) { + const width = page?.size?.w; + if (typeof width === 'number' && Number.isFinite(width) && width > widestPage) { + widestPage = width; + } + } + } + } catch { + widestPage = 0; + } + if (widestPage > 0) return widestPage; + + let pageStyles = null; + try { + pageStyles = editor.getPageStyles?.() ?? null; + } catch { + pageStyles = null; + } + const pageWidthInches = pageStyles?.pageSize?.width; + if (typeof pageWidthInches === 'number' && Number.isFinite(pageWidthInches) && pageWidthInches > 0) { + return pageWidthInches * CSS_PX_PER_INCH; + } + return null; + }; + + // Widest rendered PDF page in CSS px at 100% zoom. See + // `normalizePdfPageMeasurement` for the unit handling. Skipped entirely + // when no PDF document is loaded: the query plus per-page computed-style + // reads would otherwise run on every repagination of DOCX-only docs. + const resolvePdfPageWidth = () => { + const docs = documents?.value ?? []; + if (!docs.some((doc) => doc?.type === PDF)) return null; + const root = superdocRoot.value; + if (!root?.querySelectorAll) return null; + let widest = 0; + for (const page of root.querySelectorAll(PDF_PAGE_SELECTOR)) { + const measured = Number(page.clientWidth) || Number(page.getBoundingClientRect?.().width) || 0; + let scaleFactor = NaN; + if (typeof window !== 'undefined' && typeof window.getComputedStyle === 'function') { + scaleFactor = Number.parseFloat(window.getComputedStyle(page).getPropertyValue('--scale-factor')); + } + const zoomFactor = (activeZoom.value ?? 100) / 100; + const normalized = normalizePdfPageMeasurement(measured, scaleFactor, zoomFactor); + if (normalized !== null && normalized > widest) widest = normalized; + } + return widest > 0 ? widest : null; + }; + + // Widest measurable document width at 100% zoom across all loaded + // documents. Zoom is global, so the fit must target the widest page: + // otherwise one landscape or PDF document overflows while another fits. + // HTML documents reflow to the container and contribute no fixed width. + const resolveBaseDocumentWidth = () => { + const superdoc = getSuperdoc(); + if (!superdoc) return null; + const widths = []; + + const docs = documents?.value ?? []; + for (const doc of docs) { + if (doc?.type !== DOCX) continue; + const width = resolveEditorPageWidth(doc.getEditor?.()); + if (width !== null) widths.push(width); + } + // Store shims in tests (and transitional states) may not expose + // per-document editors; fall back to the active editor's page styles. + if (widths.length === 0) { + const width = resolveEditorPageWidth(superdoc.activeEditor); + if (width !== null) widths.push(width); + } + + const pdfWidth = resolvePdfPageWidth(); + if (pdfWidth !== null) widths.push(pdfWidth); + + if (widths.length > 0) return Math.max(...widths); + + // Last resort for a DOCX editor without page styles: the rendered + // document element, normalized by zoom. Gated on an editor existing; + // before editor mount the element is shell scaffolding whose width is + // container-derived, which would produce a garbage base. + if (superdoc.activeEditor) { + const docEl = superdocRoot.value?.querySelector?.('.superdoc__document'); + const measured = Number(docEl?.clientWidth) || Number(docEl?.getBoundingClientRect?.().width) || 0; + if (measured > 0) { + const zoomFactor = (activeZoom.value ?? 100) / 100; + return zoomFactor > 0 ? measured / zoomFactor : measured; + } + } + + return null; + }; + + // Width the comments sidebar takes from the container when visible. + // Template ref first (owned by SuperDoc.vue, rename-proof); selector + // only as a fallback for hosts that pass no ref. + const resolveSidebarWidth = () => { + if (!showCommentsSidebar?.value) return 0; + const sidebarEl = rightSidebarRef?.value ?? superdocRoot.value?.querySelector?.(SIDEBAR_SELECTOR); + const measured = Number(sidebarEl?.offsetWidth) || Number(sidebarEl?.getBoundingClientRect?.().width) || 0; + return measured > 0 ? measured : 0; + }; + + const applyFitWidth = (superdoc, metrics) => { + const options = resolveFitWidthOptions(superdoc.config?.zoom?.fitWidth); + const target = computeAppliedFitZoom(metrics.availableWidth, metrics.documentWidth, options); + if (target === null) return; + // Same-value guard: applying the fit re-triggers viewport evaluation + // through the render pipeline; skipping no-op zooms is what terminates + // that cycle (the base width is zoom-independent, so the recomputed + // target is stable). + if (target === activeZoom.value) return; + // Write the zoom state directly: setZoom() would flip the mode to + // manual. The activeZoom watcher in SuperDoc.vue propagates the value + // to all presentation surfaces exactly as setZoom() does. + activeZoom.value = target; + superdoc.emit('zoomChange', { zoom: target, mode: 'fit-width' }); + }; + + const evaluateViewport = () => { + const superdoc = getSuperdoc(); + if (!superdoc) return; + + const containerWidth = superdocContainerWidth.value; + if (!(containerWidth > 0)) return; + if (!isReady.value) return; + + const documentWidth = resolveBaseDocumentWidth(); + // No measurable document yet (editors still mounting): skip instead of + // storing a guessed width; the editorCreate/pagination hooks re-run this. + if (documentWidth === null) return; + + const availableWidth = containerWidth - resolveSidebarWidth(); + const fitZoom = computeFitZoom(availableWidth, documentWidth); + if (fitZoom === null) return; + + // Frozen so the event payload, the stored metrics, and the + // getViewportMetrics() return value (all the same object) cannot be + // mutated by one consumer to corrupt the others. + const metrics = Object.freeze({ availableWidth, documentWidth, fitZoom }); + + // Two freshness tiers, deliberately distinct: + // - Stored metrics (getViewportMetrics() / ui.zoom reads) are always + // latest: refreshed whenever any field changes, including px-level + // availableWidth movement. + // - The viewport-change EVENT is deduped to fit-relevant changes + // (rounded fitZoom, rounded base width): px jitter during a window + // drag cannot change any fit decision and would only spam consumers. + const previous = viewportMetrics.value; + const fieldsChanged = + !previous || + previous.availableWidth !== availableWidth || + previous.documentWidth !== documentWidth || + previous.fitZoom !== fitZoom; + if (fieldsChanged) { + viewportMetrics.value = metrics; + } + + const fitChanged = + !previous || previous.fitZoom !== fitZoom || Math.round(previous.documentWidth) !== Math.round(documentWidth); + if (fitChanged) { + superdoc.emit('viewport-change', metrics); + } + + // The fit policy re-applies on every evaluation while in fit-width mode. + // That is safe: leaving the mode requires setZoom()/setZoomMode(), and + // the same-value guard makes repeat applications no-ops. + if (zoomMode.value === 'fit-width') { + applyFitWidth(superdoc, metrics); + } + }; + + // Deferred a tick: the container width can change in the same flush that + // flips compact-comments mode (the sidebar's v-if has not patched yet) or + // mid render pass; evaluating post-flush sees the settled DOM and avoids + // a one-frame fit bounce. + watch(superdocContainerWidth, () => { + nextTick(() => evaluateViewport()); + }); + watch(isReady, (ready) => { + if (ready) evaluateViewport(); + }); + // Entering fit-width applies the fit immediately; the sidebar changes the + // available width without resizing the observed container, so re-measure + // after it mounts/unmounts. + watch(zoomMode, (mode) => { + if (mode === 'fit-width') evaluateViewport(); + }); + if (showCommentsSidebar) { + watch(showCommentsSidebar, () => { + nextTick(() => evaluateViewport()); + }); + } + + // Editors mount after store readiness, and page geometry can change + // without a container resize (orientation, margins, document swap). + // Re-evaluate on the editor lifecycle signals that change the base width. + const handleEditorCreate = () => { + nextTick(() => evaluateViewport()); + }; + const handlePaginationUpdate = () => { + // paginationUpdate is emitted mid render pass; defer like the other + // hooks so measurement never forces a layout flush against the + // freshly mutated tree. + nextTick(() => evaluateViewport()); + }; + const handlePdfDocumentReady = () => { + nextTick(() => evaluateViewport()); + }; + + const superdocAtSetup = getSuperdoc(); + superdocAtSetup?.on?.('editorCreate', handleEditorCreate); + superdocAtSetup?.on?.('pagination-update', handlePaginationUpdate); + superdocAtSetup?.on?.('pdf:document-ready', handlePdfDocumentReady); + onBeforeUnmount(() => { + superdocAtSetup?.off?.('editorCreate', handleEditorCreate); + superdocAtSetup?.off?.('pagination-update', handlePaginationUpdate); + superdocAtSetup?.off?.('pdf:document-ready', handlePdfDocumentReady); + }); + + return { evaluateViewport }; +} diff --git a/packages/superdoc/src/composables/use-viewport-fit.test.js b/packages/superdoc/src/composables/use-viewport-fit.test.js new file mode 100644 index 0000000000..521cbf75c9 --- /dev/null +++ b/packages/superdoc/src/composables/use-viewport-fit.test.js @@ -0,0 +1,123 @@ +import { describe, it, expect } from 'vitest'; +import { + FIT_WIDTH_DEFAULTS, + resolveFitWidthOptions, + computeFitZoom, + computeAppliedFitZoom, + normalizePdfPageMeasurement, +} from './use-viewport-fit.js'; + +// Full wiring (watchers, metric storage, emit dedup, mode-driven fit +// application) is covered through the component in src/SuperDoc.test.js; +// these tests lock the pure helpers. + +describe('resolveFitWidthOptions', () => { + it('returns defaults when options are absent or not an object', () => { + const defaults = { + min: FIT_WIDTH_DEFAULTS.min, + max: FIT_WIDTH_DEFAULTS.max, + padding: FIT_WIDTH_DEFAULTS.padding, + }; + expect(resolveFitWidthOptions(undefined)).toEqual(defaults); + expect(resolveFitWidthOptions(null)).toEqual(defaults); + expect(resolveFitWidthOptions('fit')).toEqual(defaults); + }); + + it('accepts explicit bounds and padding', () => { + expect(resolveFitWidthOptions({ min: 35, max: 150, padding: 24 })).toEqual({ + min: 35, + max: 150, + padding: 24, + }); + }); + + it('reorders swapped min/max', () => { + const options = resolveFitWidthOptions({ min: 150, max: 35 }); + expect(options.min).toBe(35); + expect(options.max).toBe(150); + }); + + it('falls back to defaults for invalid field values', () => { + expect(resolveFitWidthOptions({ min: -5, max: NaN, padding: -1 })).toEqual({ + min: FIT_WIDTH_DEFAULTS.min, + max: FIT_WIDTH_DEFAULTS.max, + padding: FIT_WIDTH_DEFAULTS.padding, + }); + expect(resolveFitWidthOptions({ min: '50', padding: '10' })).toEqual({ + min: FIT_WIDTH_DEFAULTS.min, + max: FIT_WIDTH_DEFAULTS.max, + padding: FIT_WIDTH_DEFAULTS.padding, + }); + }); + + it('accepts zero padding', () => { + expect(resolveFitWidthOptions({ padding: 0 }).padding).toBe(0); + }); +}); + +describe('computeFitZoom', () => { + it('computes the rounded percentage that fits the document', () => { + expect(computeFitZoom(816, 816)).toBe(100); + expect(computeFitZoom(600, 816)).toBe(74); + expect(computeFitZoom(1200, 816)).toBe(147); + }); + + it('returns null for non-positive inputs', () => { + expect(computeFitZoom(0, 816)).toBeNull(); + expect(computeFitZoom(-10, 816)).toBeNull(); + expect(computeFitZoom(600, 0)).toBeNull(); + expect(computeFitZoom(NaN, 816)).toBeNull(); + }); +}); + +describe('computeAppliedFitZoom', () => { + const options = { min: 35, max: 100, padding: 0 }; + + it('passes through values inside the bounds', () => { + expect(computeAppliedFitZoom(600, 816, options)).toBe(74); + }); + + it('clamps below min and above max', () => { + expect(computeAppliedFitZoom(200, 816, options)).toBe(35); + expect(computeAppliedFitZoom(1200, 816, options)).toBe(100); + }); + + it('reserves padding before computing the fit', () => { + expect(computeAppliedFitZoom(912, 816, { ...options, padding: 96 })).toBe(100); + }); + + it('returns null when padding consumes the available width', () => { + expect(computeAppliedFitZoom(90, 816, { ...options, padding: 96 })).toBeNull(); + }); + + it('never rounds the applied fit to zero (engine rejects non-positive zoom)', () => { + // Fractional factor-style min plus a degenerate container: clamp lifts + // the raw fit to 0.4, which must floor to 1, not round to 0. + expect(computeAppliedFitZoom(3, 816, { min: 0.4, max: 100, padding: 0 })).toBe(1); + }); +}); + +describe('normalizePdfPageMeasurement', () => { + const PT_TO_PX = 96 / 72; + + it('converts a rendered page back to CSS px at 100% zoom via the scale factor', () => { + // 612pt letter page at 100% zoom renders 816 CSS px (scale factor 4/3). + expect(normalizePdfPageMeasurement(816, PT_TO_PX, 1)).toBeCloseTo(816, 6); + // Same page at 50% zoom renders 408 px with scale factor 2/3. + expect(normalizePdfPageMeasurement(408, (2 / 3) * 1, 0.5)).toBeCloseTo(816, 6); + // Zoom-sync state is irrelevant when the scale factor is readable: + // a seeded zoom the viewer has not applied yet cannot corrupt the base. + expect(normalizePdfPageMeasurement(816, PT_TO_PX, 0.5)).toBeCloseTo(816, 6); + }); + + it('falls back to dividing out the assumed zoom without a scale factor', () => { + expect(normalizePdfPageMeasurement(408, NaN, 0.5)).toBeCloseTo(816, 6); + expect(normalizePdfPageMeasurement(816, 0, 1)).toBeCloseTo(816, 6); + }); + + it('returns null for unmeasurable pages', () => { + expect(normalizePdfPageMeasurement(0, PT_TO_PX, 1)).toBeNull(); + expect(normalizePdfPageMeasurement(-5, PT_TO_PX, 1)).toBeNull(); + expect(normalizePdfPageMeasurement(NaN, PT_TO_PX, 1)).toBeNull(); + }); +}); diff --git a/packages/superdoc/src/core/SuperDoc.test.js b/packages/superdoc/src/core/SuperDoc.test.js index 437608957d..874aad903f 100644 --- a/packages/superdoc/src/core/SuperDoc.test.js +++ b/packages/superdoc/src/core/SuperDoc.test.js @@ -146,6 +146,8 @@ const createAppHarness = () => { reset: vi.fn(), setExceptionHandler: vi.fn(), activeZoom: 100, + zoomMode: 'manual', + viewportMetrics: null, }; const commentsStore = { @@ -2396,7 +2398,185 @@ describe('SuperDoc core', () => { instance.setZoom(200); - expect(zoomChangeSpy).toHaveBeenCalledWith({ zoom: 200 }); + expect(zoomChangeSpy).toHaveBeenCalledWith({ zoom: 200, mode: 'manual' }); + }); + + it('setZoom switches zoom mode to manual', async () => { + const { superdocStore } = createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + }); + await flushMicrotasks(); + + superdocStore.zoomMode = 'fit-width'; + instance.setZoom(125); + + expect(superdocStore.zoomMode).toBe('manual'); + expect(instance.getZoomState().mode).toBe('manual'); + }); + + it('setZoomMode switches between manual and fit-width and rejects invalid values', async () => { + const { superdocStore } = createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + }); + await flushMicrotasks(); + + instance.setZoomMode('fit-width'); + expect(superdocStore.zoomMode).toBe('fit-width'); + + instance.setZoomMode('manual'); + expect(superdocStore.zoomMode).toBe('manual'); + + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + instance.setZoomMode('fit-page'); + expect(superdocStore.zoomMode).toBe('manual'); + expect(warn).toHaveBeenCalled(); + warn.mockRestore(); + }); + + it('setZoom and setZoomMode before initialization warn and emit nothing', async () => { + createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + }); + // No flushMicrotasks: async #init has not attached superdocStore yet. + const zoomChangeSpy = vi.fn(); + instance.on('zoomChange', zoomChangeSpy); + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + + instance.setZoom(150); + instance.setZoomMode('fit-width'); + + // Neither call may advertise a change that was never persisted. + expect(zoomChangeSpy).not.toHaveBeenCalled(); + expect(warn).toHaveBeenCalledTimes(2); + warn.mockRestore(); + + await flushMicrotasks(); + expect(instance.getZoom()).toBe(100); + expect(instance.getZoomState().mode).toBe('manual'); + }); + + it('setZoomMode emits zoomChange for mode-only transitions and no-ops on the same mode', async () => { + createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + }); + await flushMicrotasks(); + + const zoomChangeSpy = vi.fn(); + instance.on('zoomChange', zoomChangeSpy); + + // Mode change with an unchanged value is observable. + instance.setZoomMode('fit-width'); + expect(zoomChangeSpy).toHaveBeenCalledWith({ zoom: 100, mode: 'fit-width' }); + expect(zoomChangeSpy).toHaveBeenCalledTimes(1); + + // Same-mode call is a no-op: no state churn, no event. + instance.setZoomMode('fit-width'); + expect(zoomChangeSpy).toHaveBeenCalledTimes(1); + + instance.setZoomMode('manual'); + expect(zoomChangeSpy).toHaveBeenCalledWith({ zoom: 100, mode: 'manual' }); + expect(zoomChangeSpy).toHaveBeenCalledTimes(2); + }); + + it('getZoomState reports mode, value, fitZoom, and effective bounds', async () => { + const { superdocStore } = createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + zoom: { fitWidth: { min: 35, max: 150 } }, + }); + await flushMicrotasks(); + + expect(instance.getZoomState()).toEqual({ + mode: 'manual', + value: 100, + fitZoom: null, + min: 35, + max: 150, + }); + + superdocStore.zoomMode = 'fit-width'; + superdocStore.activeZoom = 74; + superdocStore.viewportMetrics = { availableWidth: 600, documentWidth: 816, fitZoom: 74 }; + + expect(instance.getZoomState()).toEqual({ + mode: 'fit-width', + value: 74, + fitZoom: 74, + min: 35, + max: 150, + }); + }); + + it('getZoomState falls back to default bounds and reorders swapped min/max', async () => { + createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + zoom: { fitWidth: { min: 150, max: 35 } }, + }); + await flushMicrotasks(); + + const state = instance.getZoomState(); + expect(state.min).toBe(35); + expect(state.max).toBe(150); + + const defaultsInstance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + }); + await flushMicrotasks(); + + const defaults = defaultsInstance.getZoomState(); + expect(defaults.min).toBe(10); + expect(defaults.max).toBe(100); + }); + + it('getZoomState uses default bounds for invalid fit-width fields', async () => { + createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + zoom: { fitWidth: { min: 'narrow', max: -1, padding: 'wide' } }, + }); + await flushMicrotasks(); + + expect(instance.getZoomState()).toMatchObject({ + min: 10, + max: 100, + }); + }); + + it('getViewportMetrics returns null before the first measurement, then the stored metrics', async () => { + const { superdocStore } = createAppHarness(); + + const instance = new SuperDoc({ + selector: '#host', + document: 'https://example.com/doc.docx', + }); + await flushMicrotasks(); + + expect(instance.getViewportMetrics()).toBeNull(); + + const metrics = { availableWidth: 935, documentWidth: 816, fitZoom: 115 }; + superdocStore.viewportMetrics = metrics; + + expect(instance.getViewportMetrics()).toEqual(metrics); }); it('getZoom reflects value set by setZoom', async () => { diff --git a/packages/superdoc/src/core/SuperDoc.ts b/packages/superdoc/src/core/SuperDoc.ts index 90ee8df683..d4c8579b77 100644 --- a/packages/superdoc/src/core/SuperDoc.ts +++ b/packages/superdoc/src/core/SuperDoc.ts @@ -8,6 +8,7 @@ import { HocuspocusProviderWebsocket } from '@hocuspocus/provider'; import { DOCX, PDF, HTML, getActorIdentityKey, normalizeActorEmail } from '@superdoc/common'; import { SuperToolbar, createZip, seedEditorStateToYDoc, onCollaborationProviderSynced } from '@superdoc/super-editor'; import { SuperComments } from '../components/CommentsLayer/commentsList/super-comments-list.js'; +import { resolveFitWidthOptions } from '../composables/use-viewport-fit.js'; import { createSuperdocVueApp } from './create-app.js'; import { shuffleArray } from '@superdoc/common/collaboration/awareness'; import { createDownload, cleanName } from './helpers/export.js'; @@ -85,10 +86,15 @@ import type { SuperDocEditorPayload, SuperDocExceptionPayload, SuperDocExceptionStorePayload, + SuperDocFontsApi, SuperDocLockedPayload, SuperDocReadyPayload, SuperDocState, - SuperDocFontsApi, + SuperDocViewportChangePayload, + SuperDocViewportMetrics, + SuperDocZoomMode, + SuperDocZoomPayload, + SuperDocZoomState, SurfaceHandle, SurfaceRequest, UpgradeToCollaborationOptions, @@ -118,9 +124,6 @@ type ActiveEditor = Editor & { interface SuperDocWhiteboardPayload { whiteboard: Whiteboard; } -interface SuperDocZoomPayload { - zoom: number; -} interface SuperDocFormattingMarksPayload { showFormattingMarks: boolean; superdoc: SuperDoc; @@ -171,6 +174,7 @@ interface SuperDocEventMap { 'whiteboard:enabled': [boolean]; 'whiteboard:tool': [string]; exception: [SuperDocExceptionPayload]; + 'viewport-change': [SuperDocViewportChangePayload]; } // Notes on the event map above: // @@ -921,6 +925,8 @@ export class SuperDoc extends EventEmitter { this.#onConfig('pagination-update', this.config.onPaginationUpdate); this.#onConfig('fonts-resolved', this.config.onFontsResolved); this.#onConfig('fonts-changed', this.config.onFontsChanged); + this.#onConfig('zoomChange', this.config.onZoomChange); + this.#onConfig('viewport-change', this.config.onViewportChange); } /** @@ -2367,12 +2373,14 @@ export class SuperDoc extends EventEmitter { } /** - * Set the zoom level for all documents. + * Set the zoom level for all documents and switch the zoom mode to + * `manual` (an explicit numeric zoom expresses intent to leave + * `fit-width`; use `setZoomMode('fit-width')` to re-enter fitting). * Updates the centralized activeZoom state, which propagates to all * presentation editors, PDF viewers, and whiteboard layers via the Vue watcher. * @param percent - The zoom level as a percentage (e.g., 100, 150, 200) * @example - * superdoc.setZoom(150); // Set zoom to 150% + * superdoc.setZoom(150); // Set zoom to 150%, mode becomes 'manual' * superdoc.setZoom(50); // Set zoom to 50% */ setZoom(percent: number) { @@ -2380,14 +2388,86 @@ export class SuperDoc extends EventEmitter { console.warn('[SuperDoc] setZoom expects a positive number representing percentage'); return; } + // Before async init attaches the store there is nothing to write, and + // emitting anyway would tell listeners about a zoom that never + // happened. Use config.zoom.initial for pre-init zoom instead. + if (!this.superdocStore) { + console.warn('[SuperDoc] setZoom called before initialization; use config.zoom.initial for the starting zoom'); + return; + } // Update store — SuperDoc.vue's activeZoom watcher propagates the zoom // to all PresentationEditor instances via PresentationEditor.setGlobalZoom(). - if (this.superdocStore) { - this.superdocStore.activeZoom = percent; + this.superdocStore.activeZoom = percent; + this.superdocStore.zoomMode = 'manual'; + + this.emit('zoomChange', { zoom: percent, mode: 'manual' }); + } + + /** + * Switch the zoom mode. `fit-width` continuously re-fits the + * document to the available container width (clamped by + * `config.zoom.fitWidth`); `manual` holds the current value. + * Switching to `fit-width` applies the fit immediately when + * viewport metrics are available. Emits `zoomChange` (with the + * current value) so zoom UIs observe mode-only transitions; a + * same-mode call is a no-op. + * @param mode - The zoom mode: `'manual'` or `'fit-width'` + * @example + * superdoc.setZoomMode('fit-width'); // start fitting to the container + * superdoc.setZoomMode('manual'); // hold the current zoom value + */ + setZoomMode(mode: SuperDocZoomMode) { + if (mode !== 'manual' && mode !== 'fit-width') { + console.warn("[SuperDoc] setZoomMode expects 'manual' or 'fit-width'"); + return; } + // Before async init attaches the store the mode cannot persist, and + // emitting anyway would advertise a mode change that never happened. + // Use config.zoom.mode for the starting mode instead. + if (!this.superdocStore) { + console.warn('[SuperDoc] setZoomMode called before initialization; use config.zoom.mode for the starting mode'); + return; + } + if (this.superdocStore.zoomMode === mode) return; + this.superdocStore.zoomMode = mode; + this.emit('zoomChange', { zoom: this.getZoom(), mode }); + } - this.emit('zoomChange', { zoom: percent }); + /** + * Get a snapshot of the current zoom state: mode, value, the latest + * computed fit zoom (null before the first viewport measurement), + * and the effective fit bounds. + * @returns The current zoom state snapshot + * @example + * const { mode, value, fitZoom } = superdoc.getZoomState(); + */ + getZoomState(): SuperDocZoomState { + // Same resolver the fit policy applies, so the reported bounds cannot + // drift from the clamping behavior. + const fit = resolveFitWidthOptions(this.config.zoom?.fitWidth); + return { + mode: this.superdocStore?.zoomMode ?? 'manual', + value: this.superdocStore?.activeZoom ?? 100, + fitZoom: this.superdocStore?.viewportMetrics?.fitZoom ?? null, + min: fit.min, + max: fit.max, + }; + } + + /** + * Get the latest viewport measurements: the width available to the + * document, the document's base page width at 100% zoom, and the + * unclamped fit zoom. Returns `null` until the first measurement + * (editors still mounting). Subscribe to `viewport-change` (or pass + * `Config.onViewportChange`) for updates. + * @returns The latest viewport metrics, or `null` before the first measurement + * @example + * const metrics = superdoc.getViewportMetrics(); + * if (metrics) superdoc.setZoom(Math.min(100, metrics.fitZoom)); + */ + getViewportMetrics(): SuperDocViewportMetrics | null { + return this.superdocStore?.viewportMetrics ?? null; } /** diff --git a/packages/superdoc/src/core/types/index.ts b/packages/superdoc/src/core/types/index.ts index 7e7ca18db6..15a4ea8df5 100644 --- a/packages/superdoc/src/core/types/index.ts +++ b/packages/superdoc/src/core/types/index.ts @@ -1705,6 +1705,121 @@ export type SuperDocExceptionPayload = | SuperDocExceptionRestorePayload | SuperDocExceptionEditorPayload; +/** + * Zoom mode. `manual` holds whatever value was last set; `fit-width` + * continuously recomputes the zoom that fits the page width into the + * available container width. Calling `setZoom()` switches to + * `manual`; `setZoomMode('fit-width')` re-enters fitting. + */ +export type SuperDocZoomMode = 'manual' | 'fit-width'; + +/** + * Payload emitted with the `zoomChange` event and passed to + * `Config.onZoomChange`. Fires for every zoom source: `setZoom()`, + * the toolbar zoom control, and fit-width adjustments. + */ +export interface SuperDocZoomPayload { + /** The zoom level as a percentage (e.g. 100, 150). */ + zoom: number; + /** The zoom mode that produced this value. */ + mode: SuperDocZoomMode; +} + +/** + * Payload emitted with the `viewport-change` event and passed to + * `Config.onViewportChange`. The event fires when the implied fit + * changes: the rounded `fitZoom` or the rounded base page width. + * Pixel-level `availableWidth` movement that cannot change any fit + * decision does not emit; read `getViewportMetrics()` for the + * always-latest measurements. These are pure measurements: + * `zoom.fitWidth` policy options (`min`, `max`, `padding`) do not + * affect them. For the common case, prefer `zoom.mode: 'fit-width'`, + * which applies a clamped fit automatically. + */ +export interface SuperDocViewportChangePayload { + /** + * Width available to the document in pixels: the measured container + * width minus the comments sidebar when it is visible. + */ + availableWidth: number; + /** Widest document page width in pixels at 100% zoom. */ + documentWidth: number; + /** Zoom percentage that fits the document in the available width (unclamped, padding-free). Clamp before applying. */ + fitZoom: number; +} + +/** + * Latest viewport measurements, readable at any time via + * `superdoc.getViewportMetrics()`. Same shape as the + * `viewport-change` payload and refreshed on every measurement + * (including pixel-level changes the deduped event skips); `null` + * until the first measurement (editors still mounting). + */ +export type SuperDocViewportMetrics = SuperDocViewportChangePayload; + +/** + * Options for the `fit-width` zoom mode. `min`/`max` clamp the + * applied zoom percentage; `padding` reserves horizontal space + * inside the available width before computing the applied fit. + * These shape the applied policy only, never the reported metrics. + */ +export interface SuperDocFitWidthOptions { + /** Lower bound for the applied zoom percentage (default: 10). */ + min?: number; + /** + * Upper bound for the applied zoom percentage (default: 100, so + * fitting never enlarges the document past its natural size; raise + * it to let wide containers scale the page up). + */ + max?: number; + /** Horizontal padding in pixels reserved inside the available width before computing the fit (default: 0). */ + padding?: number; +} + +/** + * Snapshot of the current zoom state, readable via + * `superdoc.getZoomState()`. + */ +export interface SuperDocZoomState { + /** Current zoom mode. */ + mode: SuperDocZoomMode; + /** Current zoom value as a percentage. */ + value: number; + /** Latest computed fit zoom (unclamped), or `null` before the first viewport measurement. */ + fitZoom: number | null; + /** Effective lower bound the fit policy applies (config or default). */ + min: number; + /** Effective upper bound the fit policy applies (config or default). */ + max: number; +} + +/** + * Options for `Config.zoom`: the initial zoom level, the starting + * mode, and the fit-width policy bounds. Runtime control stays on + * the instance: `setZoom()` (switches to manual), `setZoomMode()`, + * `getZoomState()`, `getViewportMetrics()`, and the `zoomChange` / + * `viewport-change` events. + */ +export interface SuperDocZoomConfig { + /** + * Initial zoom level as a percentage (default: 100). Applied before + * the first paint, so the document renders directly at this zoom + * with no visible jump. In `fit-width` mode this is the paint zoom + * until the first fit computes. Invalid values (non-finite or <= 0) + * are ignored with a console warning. + */ + initial?: number; + /** + * Starting zoom mode (default: `'manual'`). In `'fit-width'` the + * document continuously re-fits to the available container width; + * the fit is applied through the normal zoom pipeline, so + * `zoomChange` fires for every adjustment. + */ + mode?: SuperDocZoomMode; + /** Bounds and padding for the `fit-width` policy. */ + fitWidth?: SuperDocFitWidthOptions; +} + export interface Config { /** The ID of the SuperDoc. */ superdocId?: string; @@ -1843,6 +1958,19 @@ export interface Config { onPaginationUpdate?: (params: { totalPages: number; superdoc: SuperDoc }) => void; /** Callback when the list definitions change. */ onListDefinitionsChange?: (params: ListDefinitionsPayload) => void; + /** + * Callback when the zoom level changes. Fires for every zoom source: + * `setZoom()`, the toolbar zoom control, and fit-width + * adjustments. + */ + onZoomChange?: (params: SuperDocZoomPayload) => void; + /** + * Callback when the implied fit changes (rounded fit zoom or base + * page width); pixel-level width jitter does not fire it, and + * `getViewportMetrics()` always reads latest. Registered before the + * first emit. + */ + onViewportChange?: (params: SuperDocViewportChangePayload) => void; /** The format of the document (docx, pdf, html). */ format?: string; /** The extensions to load for the editor. */ @@ -1923,6 +2051,11 @@ export interface Config { * path in that case. */ useLayoutEngine?: boolean; + /** + * Zoom behavior: the initial zoom level and optional fit-width + * policy. See `SuperDocZoomConfig`. + */ + zoom?: SuperDocZoomConfig; /** * Callback fired after the editor reports `fonts-resolved`. The payload * contains `documentFonts` and `unsupportedFonts` arrays so hosts can fall diff --git a/packages/superdoc/src/dev/components/SuperdocDev.vue b/packages/superdoc/src/dev/components/SuperdocDev.vue index b963af241b..c1d67e8a37 100644 --- a/packages/superdoc/src/dev/components/SuperdocDev.vue +++ b/packages/superdoc/src/dev/components/SuperdocDev.vue @@ -924,6 +924,12 @@ const init = async () => { currentZoom.value = zoom; }); + superdoc.value?.on('viewport-change', ({ availableWidth, documentWidth, fitZoom }) => { + // Passive demo: custom consumers clamp and apply fitZoom themselves via + // setZoom(). For automatic behavior, configure `zoom: { mode: 'fit-width' }`. + console.log('[viewport-change]', { availableWidth, documentWidth, fitZoom }); + }); + window.superdoc = superdoc.value; // const ydoc = superdoc.value.ydoc; diff --git a/packages/superdoc/src/public/index.ts b/packages/superdoc/src/public/index.ts index f693d8b84e..e954dff67b 100644 --- a/packages/superdoc/src/public/index.ts +++ b/packages/superdoc/src/public/index.ts @@ -105,12 +105,19 @@ export type { SuperDocExceptionEditorPayload } from '../core/types/index.js'; export type { SuperDocExceptionPayload } from '../core/types/index.js'; export type { SuperDocExceptionRestorePayload } from '../core/types/index.js'; export type { SuperDocExceptionStorePayload } from '../core/types/index.js'; +export type { SuperDocFitWidthOptions } from '../core/types/index.js'; export type { SuperDocFontsApi, SuperDocFontFamily, SuperDocFontFace } from '../core/types/index.js'; export type { SuperDocLayoutEngineOptions } from '../core/types/index.js'; export type { SuperDocLockedPayload } from '../core/types/index.js'; export type { SuperDocReadyPayload } from '../core/types/index.js'; export type { SuperDocState } from '../core/types/index.js'; export type { SuperDocTelemetryConfig } from '../core/types/index.js'; +export type { SuperDocViewportChangePayload } from '../core/types/index.js'; +export type { SuperDocViewportMetrics } from '../core/types/index.js'; +export type { SuperDocZoomConfig } from '../core/types/index.js'; +export type { SuperDocZoomMode } from '../core/types/index.js'; +export type { SuperDocZoomPayload } from '../core/types/index.js'; +export type { SuperDocZoomState } from '../core/types/index.js'; export type { SurfaceComponentProps } from '../core/types/index.js'; export type { SurfaceFloatingPlacement } from '../core/types/index.js'; export type { SurfaceHandle } from '../core/types/index.js'; diff --git a/packages/superdoc/src/public/ui-react.test.ts b/packages/superdoc/src/public/ui-react.test.ts index 8b30fcb3e1..0fb7179e83 100644 --- a/packages/superdoc/src/public/ui-react.test.ts +++ b/packages/superdoc/src/public/ui-react.test.ts @@ -4,6 +4,7 @@ import { useSuperDocUI, useSuperDocSelection, useSuperDocComments, + useSuperDocZoom, useSetSuperDoc, } from './ui-react.js'; @@ -25,6 +26,7 @@ describe('public facade (ui-react)', () => { it('re-exports domain hooks as functions', () => { expect(typeof useSuperDocSelection).toBe('function'); expect(typeof useSuperDocComments).toBe('function'); + expect(typeof useSuperDocZoom).toBe('function'); expect(typeof useSetSuperDoc).toBe('function'); }); }); diff --git a/packages/superdoc/src/public/ui-react.ts b/packages/superdoc/src/public/ui-react.ts index a3a0e1fd81..08866fd3bc 100644 --- a/packages/superdoc/src/public/ui-react.ts +++ b/packages/superdoc/src/public/ui-react.ts @@ -36,6 +36,7 @@ export { useSuperDocToolbar, useSuperDocCommand, useSuperDocDocument, + useSuperDocZoom, } from '@superdoc/super-editor/ui/react'; export type { SuperDocHost } from '@superdoc/super-editor/ui/react'; diff --git a/packages/superdoc/src/public/ui.ts b/packages/superdoc/src/public/ui.ts index f7ed92b0d1..25ad9f1917 100644 --- a/packages/superdoc/src/public/ui.ts +++ b/packages/superdoc/src/public/ui.ts @@ -113,4 +113,8 @@ export type { ViewportPositionHit, ViewportRect, ViewportRectResult, + ZoomHandle, + ZoomMode, + ZoomSlice, + ZoomViewportMetrics, } from '@superdoc/super-editor/ui'; diff --git a/packages/superdoc/src/stores/superdoc-store.js b/packages/superdoc/src/stores/superdoc-store.js index bc788aec1e..f05f560d52 100644 --- a/packages/superdoc/src/stores/superdoc-store.js +++ b/packages/superdoc/src/stores/superdoc-store.js @@ -17,6 +17,12 @@ export const useSuperdocStore = defineStore('superdoc', () => { const pages = reactive({}); const documentUsers = ref([]); const activeZoom = ref(100); + /** @type {import('vue').Ref} */ + const zoomMode = ref('manual'); + // Latest viewport measurements (availableWidth / documentWidth / fitZoom), + // written by the viewport-fit composable; null until editors mount. + /** @type {import('vue').Ref} */ + const viewportMetrics = ref(null); const isReady = ref(false); const isInternal = ref(false); @@ -63,6 +69,28 @@ export const useSuperdocStore = defineStore('superdoc', () => { const init = async (config) => { reset(); currentConfig.value = config; + + // Seed the initial zoom before documents initialize so editor creation + // reads it (SuperDoc.vue passes activeZoom into layoutEngineOptions) and + // the first paint renders directly at the configured zoom. + if (config.zoom?.initial !== undefined) { + const initialZoom = config.zoom.initial; + if (typeof initialZoom === 'number' && Number.isFinite(initialZoom) && initialZoom > 0) { + activeZoom.value = initialZoom; + } else { + console.warn('[SuperDoc] zoom.initial expects a positive number representing percentage'); + } + } + + if (config.zoom?.mode !== undefined) { + const mode = config.zoom.mode; + if (mode === 'manual' || mode === 'fit-width') { + zoomMode.value = mode; + } else { + console.warn("[SuperDoc] zoom.mode expects 'manual' or 'fit-width'"); + } + } + const { documents: configDocs, modules: configModules, user: configUser, users: configUsers } = config; documentUsers.value = configUsers || []; @@ -261,6 +289,8 @@ export const useSuperdocStore = defineStore('superdoc', () => { documentUsers, users, activeZoom, + zoomMode, + viewportMetrics, documentScroll, isInternal, diff --git a/packages/superdoc/src/stores/superdoc-store.test.js b/packages/superdoc/src/stores/superdoc-store.test.js index b57db88c7b..46817307fb 100644 --- a/packages/superdoc/src/stores/superdoc-store.test.js +++ b/packages/superdoc/src/stores/superdoc-store.test.js @@ -232,3 +232,84 @@ describe('SuperDoc Store - Blob Support', () => { }); }); }); + +describe('SuperDoc Store - zoom.initial seeding', () => { + let store; + + beforeEach(() => { + setActivePinia(createPinia()); + store = useSuperdocStore(); + }); + + const configWithZoom = (zoom) => + createTestConfig([{ data: new File(['x'], 'test.docx', { type: DOCX }), name: 'test.docx', type: DOCX }], { + zoom, + }); + + it('defaults activeZoom to 100 when zoom.initial is absent', async () => { + await store.init(configWithZoom(undefined)); + expect(store.activeZoom).toBe(100); + }); + + it('seeds activeZoom from zoom.initial before documents initialize', async () => { + await store.init(configWithZoom({ initial: 50 })); + expect(store.activeZoom).toBe(50); + }); + + it('ignores invalid zoom.initial values with a warning', async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + + await store.init(configWithZoom({ initial: 0 })); + expect(store.activeZoom).toBe(100); + + await store.init(configWithZoom({ initial: -25 })); + expect(store.activeZoom).toBe(100); + + await store.init(configWithZoom({ initial: Number.NaN })); + expect(store.activeZoom).toBe(100); + + await store.init(configWithZoom({ initial: '75' })); + expect(store.activeZoom).toBe(100); + + expect(warn).toHaveBeenCalledTimes(4); + warn.mockRestore(); + }); +}); + +describe('SuperDoc Store - zoom.mode seeding', () => { + let store; + + beforeEach(() => { + setActivePinia(createPinia()); + store = useSuperdocStore(); + }); + + const configWithZoom = (zoom) => + createTestConfig([{ data: new File(['x'], 'test.docx', { type: DOCX }), name: 'test.docx', type: DOCX }], { + zoom, + }); + + it('defaults zoomMode to manual', async () => { + await store.init(configWithZoom(undefined)); + expect(store.zoomMode).toBe('manual'); + }); + + it('seeds zoomMode from zoom.mode', async () => { + await store.init(configWithZoom({ mode: 'fit-width' })); + expect(store.zoomMode).toBe('fit-width'); + }); + + it('ignores invalid zoom.mode values with a warning', async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + + await store.init(configWithZoom({ mode: 'fit-page' })); + expect(store.zoomMode).toBe('manual'); + expect(warn).toHaveBeenCalledTimes(1); + warn.mockRestore(); + }); + + it('starts with null viewport metrics', async () => { + await store.init(configWithZoom(undefined)); + expect(store.viewportMetrics).toBeNull(); + }); +}); diff --git a/packages/superdoc/src/ui-react.d.ts b/packages/superdoc/src/ui-react.d.ts index 0b7e46d222..99c112b9ca 100644 --- a/packages/superdoc/src/ui-react.d.ts +++ b/packages/superdoc/src/ui-react.d.ts @@ -11,5 +11,6 @@ export { useSuperDocToolbar, useSuperDocCommand, useSuperDocDocument, + useSuperDocZoom, type SuperDocHost, } from '@superdoc/super-editor/ui/react'; diff --git a/packages/superdoc/src/ui-react.js b/packages/superdoc/src/ui-react.js index dfa5258963..ce343acade 100644 --- a/packages/superdoc/src/ui-react.js +++ b/packages/superdoc/src/ui-react.js @@ -18,4 +18,5 @@ export { useSuperDocToolbar, useSuperDocCommand, useSuperDocDocument, + useSuperDocZoom, } from '@superdoc/super-editor/ui/react'; diff --git a/packages/superdoc/src/ui.d.ts b/packages/superdoc/src/ui.d.ts index 4f6faca482..8613d2525e 100644 --- a/packages/superdoc/src/ui.d.ts +++ b/packages/superdoc/src/ui.d.ts @@ -70,4 +70,8 @@ export { type ViewportPositionHit, type ViewportRect, type ViewportRectResult, + type ZoomHandle, + type ZoomMode, + type ZoomSlice, + type ZoomViewportMetrics, } from '@superdoc/super-editor/ui'; diff --git a/packages/superdoc/vite-plugin-bundled-fonts.mjs b/packages/superdoc/vite-plugin-bundled-fonts.mjs index f27c7520f2..00c53fd139 100644 --- a/packages/superdoc/vite-plugin-bundled-fonts.mjs +++ b/packages/superdoc/vite-plugin-bundled-fonts.mjs @@ -9,10 +9,12 @@ import { fileURLToPath } from 'node:url'; // budget). The provider registers `url(/fonts/)` faces against this same path. const here = path.dirname(fileURLToPath(import.meta.url)); const ASSETS_DIR = path.resolve(here, '../../shared/font-system/assets'); +const THIRD_PARTY_LICENSES_PATH = path.resolve(here, '../../THIRD_PARTY_LICENSES.md'); const URL_PREFIX = '/fonts/'; const contentType = (file) => { if (file.endsWith('.woff2')) return 'font/woff2'; + if (file.endsWith('.json')) return 'application/json; charset=utf-8'; if (file.endsWith('.md')) return 'text/markdown; charset=utf-8'; return 'text/plain; charset=utf-8'; }; @@ -56,6 +58,13 @@ export default function bundledFontsPlugin() { if (!fs.statSync(full).isFile()) continue; this.emitFile({ type: 'asset', fileName: `fonts/${name}`, source: fs.readFileSync(full) }); } + if (fs.existsSync(THIRD_PARTY_LICENSES_PATH)) { + this.emitFile({ + type: 'asset', + fileName: 'THIRD_PARTY_LICENSES.md', + source: fs.readFileSync(THIRD_PARTY_LICENSES_PATH), + }); + } }, }; } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 62389d16b9..6fa2288de0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -66,9 +66,6 @@ catalogs: '@types/react-dom': specifier: ^19.2.3 version: 19.2.3 - '@types/uuid': - specifier: ^9.0.8 - version: 9.0.8 '@types/ws': specifier: ^8.18.1 version: 8.18.1 @@ -274,8 +271,8 @@ catalogs: specifier: ^4.1.0 version: 4.1.0 uuid: - specifier: ^9.0.1 - version: 9.0.1 + specifier: ^11.1.1 + version: 11.1.1 verdaccio: specifier: ^6.1.6 version: 6.3.2 @@ -555,7 +552,7 @@ importers: version: 14.0.3 mintlify: specifier: 4.2.531 - version: 4.2.531(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@25.6.0)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) + version: 4.2.531(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@22.19.2)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) remark-mdx: specifier: ^3.1.1 version: 3.1.1 @@ -1830,6 +1827,37 @@ importers: specifier: npm:rolldown-vite@7.3.1 version: rolldown-vite@7.3.1(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)(@types/node@25.6.0)(esbuild@0.27.7)(jiti@2.6.1)(less@4.4.2)(sass@1.97.3)(terser@5.46.1)(tsx@4.21.0)(yaml@2.8.3) + examples/editor/built-in-ui/responsive-zoom: + dependencies: + '@superdoc-dev/react': + specifier: workspace:* + version: link:../../../../packages/react + react: + specifier: 'catalog:' + version: 19.2.4 + react-dom: + specifier: 'catalog:' + version: 19.2.4(react@19.2.4) + superdoc: + specifier: workspace:* + version: link:../../../../packages/superdoc + devDependencies: + '@types/react': + specifier: 'catalog:' + version: 19.2.14 + '@types/react-dom': + specifier: 'catalog:' + version: 19.2.3(@types/react@19.2.14) + '@vitejs/plugin-react': + specifier: 'catalog:' + version: 5.2.0(rolldown-vite@7.3.1(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)(@types/node@25.6.0)(esbuild@0.27.7)(jiti@2.6.1)(less@4.4.2)(sass@1.97.3)(terser@5.46.1)(tsx@4.21.0)(yaml@2.8.3)) + typescript: + specifier: 'catalog:' + version: 5.9.3 + vite: + specifier: npm:rolldown-vite@7.3.1 + version: rolldown-vite@7.3.1(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)(@types/node@25.6.0)(esbuild@0.27.7)(jiti@2.6.1)(less@4.4.2)(sass@1.97.3)(terser@5.46.1)(tsx@4.21.0)(yaml@2.8.3) + examples/editor/built-in-ui/toolbar: dependencies: react: @@ -2975,7 +3003,7 @@ importers: version: 4.1.0 uuid: specifier: 'catalog:' - version: 9.0.1 + version: 11.1.1 vue: specifier: 3.5.32 version: 3.5.32(typescript@5.9.3) @@ -3007,9 +3035,6 @@ importers: '@types/react-dom': specifier: 'catalog:' version: 19.2.3(@types/react@19.2.14) - '@types/uuid': - specifier: 'catalog:' - version: 9.0.8 '@vitejs/plugin-vue': specifier: 'catalog:' version: 6.0.2(rolldown-vite@7.3.1(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)(@types/node@25.6.0)(esbuild@0.27.7)(jiti@2.6.1)(less@4.4.2)(sass@1.97.3)(terser@5.46.1)(tsx@4.21.0)(yaml@2.8.3))(vue@3.5.32(typescript@5.9.3)) @@ -3093,7 +3118,7 @@ importers: version: 3.5.0 uuid: specifier: 'catalog:' - version: 9.0.1 + version: 11.1.1 vue: specifier: 3.5.32 version: 3.5.32(typescript@5.9.3) @@ -3125,9 +3150,6 @@ importers: '@superdoc/super-editor': specifier: workspace:* version: link:../super-editor - '@types/uuid': - specifier: 'catalog:' - version: 9.0.8 '@vitejs/plugin-vue': specifier: 'catalog:' version: 6.0.2(rolldown-vite@7.3.1(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)(@types/node@25.6.0)(esbuild@0.27.7)(jiti@2.6.1)(less@4.4.2)(sass@1.97.3)(terser@5.46.1)(tsx@4.21.0)(yaml@2.8.3))(vue@3.5.32(typescript@5.9.3)) @@ -3303,6 +3325,10 @@ importers: version: 3.5.32(typescript@5.9.3) shared/font-system: + dependencies: + '@docfonts/fallbacks': + specifier: 0.4.0 + version: 0.4.0 devDependencies: '@types/node': specifier: 'catalog:' @@ -4797,6 +4823,9 @@ packages: resolution: {integrity: sha512-4B4OijXeVNOPZlYA2oEwWOTkzyltLao+xbotHQeqN++Rv27Y6s818+n2Qkp8q+Fxhn0t/5lA5X1Mxktud8eayQ==} engines: {node: '>=14.17.0'} + '@docfonts/fallbacks@0.4.0': + resolution: {integrity: sha512-445WsZfyAe7ENv2R0z7SIl6pYCSCDSmjSPSfgB3m/L4Cfsm5eLJkgp3+IivcEJmF+HopIVOBQR6VdJt6fyYo/g==} + '@dxup/nuxt@0.4.0': resolution: {integrity: sha512-28LDotpr9G2knUse3cQYsOo6NJq5yhABv4ByRVRYJUmzf9Q31DI7rpRek4POlKy1aAcYyKgu5J2616pyqLohYg==} peerDependencies: @@ -6543,6 +6572,7 @@ packages: '@microsoft/teamsapp-cli@3.0.2': resolution: {integrity: sha512-AowuJwrrUxeF9Bq/frxuy9YZjK/ECk3pi0UBXl3CQLZ4XNWfgWatiFi/UWpyHDLccFs+0Za3nNYATFvgsxEFwQ==} engines: {node: '>=12'} + deprecated: This package is deprecated and supported Node.js version is 18-22. Please use @microsoft/m365agentstoolkit-cli instead. hasBin: true '@microsoft/teamsfx-api@0.23.1': @@ -10897,9 +10927,6 @@ packages: '@types/urijs@1.19.26': resolution: {integrity: sha512-wkXrVzX5yoqLnndOwFsieJA7oKM8cNkOKJtf/3vVGSUFkWDKZvFHpIl9Pvqb/T9UsawBBFMTTD8xu7sK5MWuvg==} - '@types/uuid@9.0.8': - resolution: {integrity: sha512-jg+97EGIcY9AGHJJRaaPVgetKDsrTgbRjQ5Msgjh/DQKEFl0DtyRr/VCOyD1T2R1MNeWPK/u7JoGhlDZnKBAfA==} - '@types/vscode@1.110.0': resolution: {integrity: sha512-AGuxUEpU4F4mfuQjxPPaQVyuOMhs+VT/xRok1jiHVBubHK7lBRvCuOMZG0LKUwxncrPorJ5qq/uil3IdZBd5lA==} @@ -22248,6 +22275,10 @@ packages: resolution: {integrity: sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==} hasBin: true + uuid@11.1.1: + resolution: {integrity: sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==} + hasBin: true + uuid@13.0.0: resolution: {integrity: sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w==} hasBin: true @@ -25618,6 +25649,8 @@ snapshots: '@discoveryjs/json-ext@0.6.3': {} + '@docfonts/fallbacks@0.4.0': {} + '@dxup/nuxt@0.4.0(magicast@0.5.2)(typescript@5.9.3)': dependencies: '@dxup/unimport': 0.1.2 @@ -26590,6 +26623,16 @@ snapshots: chalk: 4.1.2 figures: 3.2.0 + '@inquirer/checkbox@4.3.2(@types/node@22.19.2)': + dependencies: + '@inquirer/ansi': 1.0.2 + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/figures': 1.0.15 + '@inquirer/type': 3.0.10(@types/node@22.19.2) + yoctocolors-cjs: 2.1.3 + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/checkbox@4.3.2(@types/node@25.6.0)': dependencies: '@inquirer/ansi': 1.0.2 @@ -26615,6 +26658,13 @@ snapshots: '@inquirer/type': 1.5.5 chalk: 4.1.2 + '@inquirer/confirm@5.1.21(@types/node@22.19.2)': + dependencies: + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/confirm@5.1.21(@types/node@25.6.0)': dependencies: '@inquirer/core': 10.3.2(@types/node@25.6.0) @@ -26629,6 +26679,19 @@ snapshots: optionalDependencies: '@types/node': 18.19.130 + '@inquirer/core@10.3.2(@types/node@22.19.2)': + dependencies: + '@inquirer/ansi': 1.0.2 + '@inquirer/figures': 1.0.15 + '@inquirer/type': 3.0.10(@types/node@22.19.2) + cli-width: 4.1.0 + mute-stream: 2.0.0 + signal-exit: 4.1.0 + wrap-ansi: 6.2.0 + yoctocolors-cjs: 2.1.3 + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/core@10.3.2(@types/node@25.6.0)': dependencies: '@inquirer/ansi': 1.0.2 @@ -26695,6 +26758,14 @@ snapshots: chalk: 4.1.2 external-editor: 3.1.0 + '@inquirer/editor@4.2.23(@types/node@22.19.2)': + dependencies: + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/external-editor': 1.0.3(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/editor@4.2.23(@types/node@25.6.0)': dependencies: '@inquirer/core': 10.3.2(@types/node@25.6.0) @@ -26718,6 +26789,14 @@ snapshots: chalk: 4.1.2 figures: 3.2.0 + '@inquirer/expand@4.0.23(@types/node@22.19.2)': + dependencies: + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + yoctocolors-cjs: 2.1.3 + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/expand@4.0.23(@types/node@25.6.0)': dependencies: '@inquirer/core': 10.3.2(@types/node@25.6.0) @@ -26726,6 +26805,13 @@ snapshots: optionalDependencies: '@types/node': 25.6.0 + '@inquirer/external-editor@1.0.3(@types/node@22.19.2)': + dependencies: + chardet: 2.1.1 + iconv-lite: 0.7.2 + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/external-editor@1.0.3(@types/node@25.6.0)': dependencies: chardet: 2.1.1 @@ -26750,6 +26836,13 @@ snapshots: '@inquirer/type': 1.5.5 chalk: 4.1.2 + '@inquirer/input@4.3.1(@types/node@22.19.2)': + dependencies: + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/input@4.3.1(@types/node@25.6.0)': dependencies: '@inquirer/core': 10.3.2(@types/node@25.6.0) @@ -26764,6 +26857,13 @@ snapshots: optionalDependencies: '@types/node': 18.19.130 + '@inquirer/number@3.0.23(@types/node@22.19.2)': + dependencies: + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/number@3.0.23(@types/node@25.6.0)': dependencies: '@inquirer/core': 10.3.2(@types/node@25.6.0) @@ -26778,6 +26878,14 @@ snapshots: ansi-escapes: 4.3.2 chalk: 4.1.2 + '@inquirer/password@4.0.23(@types/node@22.19.2)': + dependencies: + '@inquirer/ansi': 1.0.2 + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/password@4.0.23(@types/node@25.6.0)': dependencies: '@inquirer/ansi': 1.0.2 @@ -26798,6 +26906,21 @@ snapshots: '@inquirer/rawlist': 1.2.16 '@inquirer/select': 1.3.3 + '@inquirer/prompts@7.10.1(@types/node@22.19.2)': + dependencies: + '@inquirer/checkbox': 4.3.2(@types/node@22.19.2) + '@inquirer/confirm': 5.1.21(@types/node@22.19.2) + '@inquirer/editor': 4.2.23(@types/node@22.19.2) + '@inquirer/expand': 4.0.23(@types/node@22.19.2) + '@inquirer/input': 4.3.1(@types/node@22.19.2) + '@inquirer/number': 3.0.23(@types/node@22.19.2) + '@inquirer/password': 4.0.23(@types/node@22.19.2) + '@inquirer/rawlist': 4.1.11(@types/node@22.19.2) + '@inquirer/search': 3.2.2(@types/node@22.19.2) + '@inquirer/select': 4.4.2(@types/node@22.19.2) + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/prompts@7.10.1(@types/node@25.6.0)': dependencies: '@inquirer/checkbox': 4.3.2(@types/node@25.6.0) @@ -26813,20 +26936,20 @@ snapshots: optionalDependencies: '@types/node': 25.6.0 - '@inquirer/prompts@7.9.0(@types/node@25.6.0)': + '@inquirer/prompts@7.9.0(@types/node@22.19.2)': dependencies: - '@inquirer/checkbox': 4.3.2(@types/node@25.6.0) - '@inquirer/confirm': 5.1.21(@types/node@25.6.0) - '@inquirer/editor': 4.2.23(@types/node@25.6.0) - '@inquirer/expand': 4.0.23(@types/node@25.6.0) - '@inquirer/input': 4.3.1(@types/node@25.6.0) - '@inquirer/number': 3.0.23(@types/node@25.6.0) - '@inquirer/password': 4.0.23(@types/node@25.6.0) - '@inquirer/rawlist': 4.1.11(@types/node@25.6.0) - '@inquirer/search': 3.2.2(@types/node@25.6.0) - '@inquirer/select': 4.4.2(@types/node@25.6.0) + '@inquirer/checkbox': 4.3.2(@types/node@22.19.2) + '@inquirer/confirm': 5.1.21(@types/node@22.19.2) + '@inquirer/editor': 4.2.23(@types/node@22.19.2) + '@inquirer/expand': 4.0.23(@types/node@22.19.2) + '@inquirer/input': 4.3.1(@types/node@22.19.2) + '@inquirer/number': 3.0.23(@types/node@22.19.2) + '@inquirer/password': 4.0.23(@types/node@22.19.2) + '@inquirer/rawlist': 4.1.11(@types/node@22.19.2) + '@inquirer/search': 3.2.2(@types/node@22.19.2) + '@inquirer/select': 4.4.2(@types/node@22.19.2) optionalDependencies: - '@types/node': 25.6.0 + '@types/node': 22.19.2 '@inquirer/rawlist@1.2.16': dependencies: @@ -26834,6 +26957,14 @@ snapshots: '@inquirer/type': 1.5.5 chalk: 4.1.2 + '@inquirer/rawlist@4.1.11(@types/node@22.19.2)': + dependencies: + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + yoctocolors-cjs: 2.1.3 + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/rawlist@4.1.11(@types/node@25.6.0)': dependencies: '@inquirer/core': 10.3.2(@types/node@25.6.0) @@ -26842,6 +26973,15 @@ snapshots: optionalDependencies: '@types/node': 25.6.0 + '@inquirer/search@3.2.2(@types/node@22.19.2)': + dependencies: + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/figures': 1.0.15 + '@inquirer/type': 3.0.10(@types/node@22.19.2) + yoctocolors-cjs: 2.1.3 + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/search@3.2.2(@types/node@25.6.0)': dependencies: '@inquirer/core': 10.3.2(@types/node@25.6.0) @@ -26859,6 +26999,16 @@ snapshots: chalk: 4.1.2 figures: 3.2.0 + '@inquirer/select@4.4.2(@types/node@22.19.2)': + dependencies: + '@inquirer/ansi': 1.0.2 + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/figures': 1.0.15 + '@inquirer/type': 3.0.10(@types/node@22.19.2) + yoctocolors-cjs: 2.1.3 + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/select@4.4.2(@types/node@25.6.0)': dependencies: '@inquirer/ansi': 1.0.2 @@ -26882,6 +27032,10 @@ snapshots: dependencies: mute-stream: 1.0.0 + '@inquirer/type@3.0.10(@types/node@22.19.2)': + optionalDependencies: + '@types/node': 22.19.2 + '@inquirer/type@3.0.10(@types/node@25.6.0)': optionalDependencies: '@types/node': 25.6.0 @@ -27446,11 +27600,11 @@ snapshots: '@microsoft/tsdoc@0.16.0': {} - '@mintlify/cli@4.0.1134(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@25.6.0)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3)': + '@mintlify/cli@4.0.1134(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@22.19.2)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3)': dependencies: - '@inquirer/prompts': 7.9.0(@types/node@25.6.0) + '@inquirer/prompts': 7.9.0(@types/node@22.19.2) '@mintlify/common': 1.0.865(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) - '@mintlify/link-rot': 3.0.1043(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) + '@mintlify/link-rot': 3.0.1043(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) '@mintlify/prebuild': 1.0.1008(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) '@mintlify/previewing': 4.0.1069(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) '@mintlify/validation': 0.1.676(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(typescript@5.9.3) @@ -27461,7 +27615,7 @@ snapshots: front-matter: 4.0.2 fs-extra: 11.2.0 ink: 6.3.0(@types/react@19.2.14)(react@19.2.3) - inquirer: 12.3.0(@types/node@25.6.0) + inquirer: 12.3.0(@types/node@22.19.2) js-yaml: 4.1.0 mdast-util-mdx-jsx: 3.2.0 open: 8.4.2 @@ -27493,7 +27647,7 @@ snapshots: - utf-8-validate - yaml - '@mintlify/common@1.0.661(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(typescript@5.9.3)': + '@mintlify/common@1.0.661(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(typescript@5.9.3)': dependencies: '@asyncapi/parser': 3.4.0 '@mintlify/mdx': 3.0.4(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(typescript@5.9.3) @@ -27533,7 +27687,7 @@ snapshots: remark-parse: 11.0.0 remark-rehype: 11.1.1 remark-stringify: 11.0.0 - tailwindcss: 3.4.4(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3)) + tailwindcss: 3.4.4(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3)) unified: 11.0.5 unist-builder: 4.0.0 unist-util-map: 4.0.0 @@ -27617,13 +27771,13 @@ snapshots: - typescript - yaml - '@mintlify/link-rot@3.0.1043(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3)': + '@mintlify/link-rot@3.0.1043(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3)': dependencies: '@mintlify/common': 1.0.865(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) '@mintlify/models': 0.0.296 '@mintlify/prebuild': 1.0.1008(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) '@mintlify/previewing': 4.0.1069(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) - '@mintlify/scraping': 4.0.522(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(typescript@5.9.3) + '@mintlify/scraping': 4.0.522(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(typescript@5.9.3) '@mintlify/validation': 0.1.676(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(typescript@5.9.3) fs-extra: 11.1.0 unist-util-visit: 4.1.2 @@ -27768,9 +27922,9 @@ snapshots: - utf-8-validate - yaml - '@mintlify/scraping@4.0.522(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(typescript@5.9.3)': + '@mintlify/scraping@4.0.522(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(typescript@5.9.3)': dependencies: - '@mintlify/common': 1.0.661(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(typescript@5.9.3) + '@mintlify/common': 1.0.661(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(typescript@5.9.3) '@mintlify/openapi-parser': 0.0.8 fs-extra: 11.1.1 hast-util-to-mdast: 10.1.0 @@ -32891,8 +33045,6 @@ snapshots: '@types/urijs@1.19.26': {} - '@types/uuid@9.0.8': {} - '@types/vscode@1.110.0': {} '@types/webidl-conversions@7.0.3': @@ -39198,12 +39350,12 @@ snapshots: react: 18.2.0 react-dom: 18.2.0(react@18.2.0) - inquirer@12.3.0(@types/node@25.6.0): + inquirer@12.3.0(@types/node@22.19.2): dependencies: - '@inquirer/core': 10.3.2(@types/node@25.6.0) - '@inquirer/prompts': 7.10.1(@types/node@25.6.0) - '@inquirer/type': 3.0.10(@types/node@25.6.0) - '@types/node': 25.6.0 + '@inquirer/core': 10.3.2(@types/node@22.19.2) + '@inquirer/prompts': 7.10.1(@types/node@22.19.2) + '@inquirer/type': 3.0.10(@types/node@22.19.2) + '@types/node': 22.19.2 ansi-escapes: 4.3.2 mute-stream: 2.0.0 run-async: 3.0.0 @@ -41579,9 +41731,9 @@ snapshots: dependencies: minipass: 7.1.3 - mintlify@4.2.531(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@25.6.0)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3): + mintlify@4.2.531(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@22.19.2)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3): dependencies: - '@mintlify/cli': 4.0.1134(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@25.6.0)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) + '@mintlify/cli': 4.0.1134(@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(react@19.2.3))(@types/node@22.19.2)(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.3))(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3))(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.3) transitivePeerDependencies: - '@radix-ui/react-popover' - '@types/node' @@ -43542,13 +43694,13 @@ snapshots: camelcase-css: 2.0.1 postcss: 8.5.8 - postcss-load-config@4.0.2(postcss@8.5.10)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3)): + postcss-load-config@4.0.2(postcss@8.5.10)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3)): dependencies: lilconfig: 3.1.3 yaml: 2.8.3 optionalDependencies: postcss: 8.5.10 - ts-node: 10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3) + ts-node: 10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3) postcss-load-config@6.0.1(jiti@1.21.7)(postcss@8.5.8)(tsx@4.21.0)(yaml@2.8.3): dependencies: @@ -46719,7 +46871,7 @@ snapshots: - tsx - yaml - tailwindcss@3.4.4(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3)): + tailwindcss@3.4.4(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3)): dependencies: '@alloc/quick-lru': 5.2.0 arg: 5.0.2 @@ -46738,7 +46890,7 @@ snapshots: postcss: 8.5.10 postcss-import: 15.1.0(postcss@8.5.10) postcss-js: 4.1.0(postcss@8.5.10) - postcss-load-config: 4.0.2(postcss@8.5.10)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3)) + postcss-load-config: 4.0.2(postcss@8.5.10)(ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3)) postcss-nested: 6.2.0(postcss@8.5.10) postcss-selector-parser: 6.1.2 resolve: 1.22.11 @@ -47104,14 +47256,14 @@ snapshots: '@swc/core': 1.15.21 optional: true - ts-node@10.9.2(@swc/core@1.15.21)(@types/node@25.6.0)(typescript@5.9.3): + ts-node@10.9.2(@swc/core@1.15.21)(@types/node@22.19.2)(typescript@5.9.3): dependencies: '@cspotcode/source-map-support': 0.8.1 '@tsconfig/node10': 1.0.12 '@tsconfig/node12': 1.0.11 '@tsconfig/node14': 1.0.3 '@tsconfig/node16': 1.0.4 - '@types/node': 25.6.0 + '@types/node': 22.19.2 acorn: 8.16.0 acorn-walk: 8.3.5 arg: 4.1.3 @@ -47826,6 +47978,8 @@ snapshots: uuid@11.1.0: {} + uuid@11.1.1: {} + uuid@13.0.0: optional: true diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index c690d51fb5..ecbac9d045 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -43,7 +43,6 @@ catalog: '@types/node': 22.19.2 '@types/react': ^19.2.6 '@types/react-dom': ^19.2.3 - '@types/uuid': ^9.0.8 '@types/ws': ^8.18.1 '@typescript-eslint/eslint-plugin': ^8.49.0 '@typescript-eslint/parser': ^8.49.0 @@ -121,7 +120,7 @@ catalog: typescript-eslint: ^8.49.0 unified: 11.0.5 utif2: ^4.1.0 - uuid: ^9.0.1 + uuid: ^11.1.1 verdaccio: ^6.1.6 vite: ^7.2.7 vite-plugin-dts: ~4.5.4 diff --git a/scripts/check-public-contract.mjs b/scripts/check-public-contract.mjs index 90e53369f2..16d401ab29 100755 --- a/scripts/check-public-contract.mjs +++ b/scripts/check-public-contract.mjs @@ -62,7 +62,12 @@ * returns obligations on their own * — that's why `search(text: string)` * shipped under v1 of this gate. - * 7. build - vite build + the postbuild + * 7. font-license-gate - verifies every bundled WOFF2 has a + * legal manifest row, license notice, + * stable hash, and runtime manifest entry. + * Fails before the package build if a + * new bundled font lacks notices. + * 8. build - vite build + the postbuild * validator chain * (check-tsconfig-type-surface, * ensure-types, audit-bundle, @@ -73,22 +78,22 @@ * Skipped when `--skip-build` is * passed (CI calls `pnpm run build` * separately in its own step). - * 8. consumer-typecheck-matrix - packs superdoc + installs the + * 9. consumer-typecheck-matrix - packs superdoc + installs the * tarball into * tests/consumer-typecheck/ * node_modules/, then runs every * consumer scenario. - * 9. deep-type-audit-supported-root - strict gate on the supported- + * 10. deep-type-audit-supported-root - strict gate on the supported- * root public surface; fails on any * `any` leak. Reuses the install * from stage 8. - * 10. package-shape - publint + attw against the packed + * 11. package-shape - publint + attw against the packed * manifest. Reuses the tarball * from stage 8. - * 11. export-snapshots - super-editor / legacy / root + * 12. export-snapshots - super-editor / legacy / root * no-growth export snapshots. * Reuses the install. - * 12. root-classification-closure - no supported-root or legacy-root + * 13. root-classification-closure - no supported-root or legacy-root * export references an internal- * candidate type in its public * declared shape (SD-3212 A1b). @@ -196,6 +201,17 @@ const stages = [ 'members. Call sites do NOT satisfy parameters/returns on their own ' + '(this is why search(text: string) shipped).', }, + { + name: 'font-license-gate', + cwd: REPO_ROOT, + cmd: 'pnpm', + args: ['run', 'check:font-licenses'], + blurb: + 'Bundled font compliance gate: every .woff2 under shared/font-system/assets ' + + 'must have an asset/legal manifest row, stable hash, matching runtime manifest ' + + 'entry, and required license notices. Fails before build if a new bundled font ' + + 'ships without legal metadata.', + }, { name: 'build', cwd: REPO_ROOT, @@ -212,9 +228,7 @@ const stages = [ cwd: resolve(REPO_ROOT, 'tests/consumer-typecheck'), cmd: 'node', args: ['typecheck-matrix.mjs'], - blurb: - 'Packs superdoc + installs the tarball into the consumer fixture, ' + - 'then runs every typecheck scenario.', + blurb: 'Packs superdoc + installs the tarball into the consumer fixture, ' + 'then runs every typecheck scenario.', }, { name: 'deep-type-audit-supported-root', diff --git a/scripts/corpus/README.md b/scripts/corpus/README.md index 0ff102f4b5..d8cf6ac0ae 100644 --- a/scripts/corpus/README.md +++ b/scripts/corpus/README.md @@ -18,12 +18,13 @@ pnpm corpus:push -- --path rendering/sd-1234-example.docx /path/to/file.docx # Skip automatic Word baseline generation/upload for this push pnpm corpus:push -- --no-word-baseline --path rendering/sd-1234-example.docx /path/to/file.docx -# Reconcile registry.json in R2 by removing entries for missing object keys +# Reconcile registry.json in R2 against live .docx keys pnpm corpus:update-registry ``` `pnpm corpus:pull` now tolerates missing keys and prunes stale `registry.json` entries automatically. `pnpm corpus:pull` does not remove local files that no longer exist in R2; use `pnpm corpus:delete` when you want the shared corpus and local copy removed together. +`pnpm corpus:update-registry` performs a full live reconciliation of `registry.json` against bucket `.docx` keys: it removes stale entries and adds bucket docs that were missing from the registry. ### Worktrees: seeding from the primary repo diff --git a/scripts/corpus/update-registry.mjs b/scripts/corpus/update-registry.mjs index ce8d9480c1..6f08645db6 100644 --- a/scripts/corpus/update-registry.mjs +++ b/scripts/corpus/update-registry.mjs @@ -4,35 +4,55 @@ import process from 'node:process'; import { REGISTRY_KEY, buildDocRelativePath, + coerceDocEntryFromRelativePath, createCorpusR2Client, loadRegistryOrNull, normalizePath, printCorpusEnvHint, saveRegistry, + sha256Buffer, sortRegistryDocs, } from './shared.mjs'; function printHelp() { console.log(` Usage: - node scripts/corpus/update-registry.mjs + node scripts/corpus/update-registry.mjs [--dry-run] Description: - Reconciles registry.json against existing R2 object keys and removes missing doc entries. + Reconciles registry.json against live R2 .docx keys by removing stale entries + and adding bucket docs that are missing from the registry. `); } function parseArgs(argv) { + const args = { + dryRun: false, + }; + for (const arg of argv) { if (arg === '--help' || arg === '-h') { printHelp(); process.exit(0); } + if (arg === '--dry-run') { + args.dryRun = true; + } } + + return args; +} + +async function buildRegistryDocFromBucket(client, relativePath) { + const buffer = await client.getObjectBuffer(relativePath); + return { + ...coerceDocEntryFromRelativePath(relativePath), + doc_rev: sha256Buffer(buffer), + }; } async function main() { - parseArgs(process.argv.slice(2)); + const args = parseArgs(process.argv.slice(2)); const client = await createCorpusR2Client(); try { @@ -43,44 +63,74 @@ async function main() { const docs = Array.isArray(registry.docs) ? registry.docs : []; const allObjectKeys = await client.listObjects(''); - const objectKeySet = new Set(allObjectKeys.map((key) => normalizePath(key).toLowerCase())); + const bucketDocPaths = allObjectKeys + .map((key) => normalizePath(key)) + .filter((key) => key.toLowerCase().endsWith('.docx')); + const bucketDocPathSet = new Set(bucketDocPaths.map((key) => key.toLowerCase())); - const missingPaths = []; + const registryDocPathSet = new Set(); + const stalePaths = []; const nextDocs = []; + for (const doc of docs) { const docPath = normalizePath(buildDocRelativePath(doc)); - if (!docPath.toLowerCase().endsWith('.docx') || objectKeySet.has(docPath.toLowerCase())) { + if (!docPath.toLowerCase().endsWith('.docx')) { nextDocs.push(doc); - } else { - missingPaths.push(docPath); + continue; } + + registryDocPathSet.add(docPath.toLowerCase()); + if (bucketDocPathSet.has(docPath.toLowerCase())) nextDocs.push(doc); + else stalePaths.push(docPath); } + const missingRegistryPaths = bucketDocPaths + .filter((docPath) => !registryDocPathSet.has(docPath.toLowerCase())) + .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' })); + console.log(`[corpus] Mode: ${client.mode}`); console.log(`[corpus] Account: ${client.accountId}`); console.log(`[corpus] Bucket: ${client.bucketName}`); console.log(`[corpus] Source: ${REGISTRY_KEY}`); console.log(`[corpus] Registry docs: ${docs.length}`); console.log(`[corpus] Bucket objects: ${allObjectKeys.length}`); - console.log(`[corpus] Missing registry entries: ${missingPaths.length}`); + console.log(`[corpus] Bucket .docx docs: ${bucketDocPaths.length}`); + console.log(`[corpus] Registry-only stale docs: ${stalePaths.length}`); + console.log(`[corpus] Bucket docs missing from registry: ${missingRegistryPaths.length}`); - if (missingPaths.length === 0) { + if (stalePaths.length === 0 && missingRegistryPaths.length === 0) { console.log('[corpus] Registry already in sync.'); return; } - for (const missingPath of missingPaths) { - console.log(`[corpus] Removed from registry: ${missingPath}`); + for (const stalePath of stalePaths) { + console.log(`[corpus] Removed from registry: ${stalePath}`); + } + + const addedDocs = []; + for (const missingPath of missingRegistryPaths) { + const nextDoc = await buildRegistryDocFromBucket(client, missingPath); + addedDocs.push(nextDoc); + console.log(`[corpus] Added to registry: ${missingPath}`); } const nextRegistry = { ...registry, updated_at: new Date().toISOString(), - docs: sortRegistryDocs(nextDocs), + docs: sortRegistryDocs([...nextDocs, ...addedDocs]), }; + if (args.dryRun) { + console.log( + `[corpus] Dry run complete. Would add ${addedDocs.length} doc(s) and remove ${stalePaths.length} stale doc(s).`, + ); + return; + } + await saveRegistry(client, nextRegistry); - console.log(`[corpus] registry.json updated. Removed ${missingPaths.length} stale entries.`); + console.log( + `[corpus] registry.json updated. Added ${addedDocs.length} doc(s), removed ${stalePaths.length} stale doc(s).`, + ); } finally { client.destroy(); } diff --git a/shared/font-system/assets/LICENSES.md b/shared/font-system/assets/LICENSES.md index 651ec0786c..da88e47f0d 100644 --- a/shared/font-system/assets/LICENSES.md +++ b/shared/font-system/assets/LICENSES.md @@ -1,22 +1,97 @@ -# Bundled substitute fonts - licenses & provenance - -SuperDoc bundles these open, metric-compatible substitute fonts for proprietary Word -fonts. Copyright + Reserved Font Name statements are below; the full license texts are -`OFL.txt` (SIL Open Font License 1.1) and `Apache-2.0.txt` (Apache License 2.0) in this -directory. The `.woff2` files are lossless conversions of the LibreOffice `.ttf` sources -(advance widths + OS/2 metrics verified identical). - -| Font (substitutes) | License | Copyright / Reserved Font Name | -|---|---|---| -| **Carlito** (Calibri) | OFL-1.1 → `OFL.txt` | (c) 2010-2013 tyPoland Lukasz Dziedzic, with Reserved Font Name "Carlito". | -| **Caladea** (Cambria) | Apache-2.0 → `Apache-2.0.txt` | (c) 2012 Huerta Tipografia. | -| **Liberation Sans** (Arial) | OFL-1.1 → `OFL.txt` | Digitized data (c) 2010 Google Corporation; (c) 2012 Red Hat, Inc., with Reserved Font Name "Liberation". | -| **Liberation Serif** (Times New Roman) | OFL-1.1 → `OFL.txt` | Digitized data (c) 2010 Google Corporation; (c) 2012 Red Hat, Inc., with Reserved Font Name "Liberation". | -| **Liberation Mono** (Courier New) | OFL-1.1 → `OFL.txt` | Digitized data (c) 2010 Google Corporation; (c) 2012 Red Hat, Inc., with Reserved Font Name "Liberation". | - -No proprietary Microsoft font is bundled - only the open substitutes above. The OFL and -Apache licenses both permit bundling/redistribution with software when the license texts -accompany the fonts (done here). **A legal sign-off on this exact ship set is still -required before public release** (tracked as the clone-pack legal gate); the license texts -were retrieved from the canonical sources (openfontlicense.org, apache.org) and should be -confirmed verbatim at that sign-off. +# Bundled Fonts - License & Attribution Record + +_Location: `shared/font-system/assets/LICENSES.md`. This file ships in the same +directory as the font files, `OFL.txt`, and `Apache-2.0.txt`, and travels with +them in every distribution. All strings below were taken verbatim from the +shipped fonts' `name` tables on 2026-06-03._ + +## Scope (read first) + +This record applies to the font software listed below **in every form in which +SuperDoc distributes or serves it**: embedded or bundled within SuperDoc and +its packages, served to browsers as web fonts from a SuperDoc- or +customer-operated host, or redistributed by a customer that embeds SuperDoc. +Web-font delivery counts as distribution under the SIL Open Font License, so the +obligations below are stated to the broadest redistribution case. Lighter +delivery models are covered too. **No edit to this file is required if the +delivery model changes.** + +These notices, `OFL.txt`, and `Apache-2.0.txt` are a single unit. Distribute +them together with the font files wherever the fonts go. + +SPDX license expression for this bundled font set: `OFL-1.1 AND Apache-2.0`. +Machine-readable asset metadata: `font-assets.manifest.json`. + +## Families + +| Family | Replaces | License | Reserved Font Name | Version | Upstream source | +| --- | --- | --- | --- | --- | --- | +| Carlito | Calibri | OFL-1.1 | "Carlito" | 1.103 | github.com/googlefonts/carlito | +| Caladea | Cambria | Apache-2.0 | none | 1.002 | Google *crosextra* (via LibreOffice resources) | +| Liberation Sans | Arial | OFL-1.1 | none declared* | 2.1.5 | github.com/liberationfonts/liberation-fonts 2.1.5 | +| Liberation Serif | Times New Roman | OFL-1.1 | none declared* | 2.1.5 | github.com/liberationfonts/liberation-fonts 2.1.5 | +| Liberation Mono | Courier New | OFL-1.1 | none declared* | 2.1.5 | github.com/liberationfonts/liberation-fonts 2.1.5 | + +\* The Liberation v2.1.5 files carry no OFL Reserved Font Name. "Liberation" is a +registered Red Hat trademark, which is separate from an OFL RFN. SuperDoc names +the unmodified fonts, which is customary nominative use. + +## Verbatim copyright & trademark notices from the font `name` tables + +**Carlito** - OFL-1.1 + +```text +Copyright (c) 2010-2013 by tyPoland Lukasz Dziedzic with Reserved Font Name "Carlito". Licensed under the SIL Open Font License, Version 1.1. +Trademark: Carlito is a trademark of tyPoland Lukasz Dziedzic. +``` + +**Caladea** - Apache-2.0 + +```text +Copyright (c) 2012 Huerta Tipografia +Trademark: Caladea is a trademark of Huerta Tipografia +``` + +**Liberation Sans / Liberation Serif / Liberation Mono** - OFL-1.1 + +```text +Digitized data copyright (c) 2010 Google Corporation. +Copyright (c) 2012 Red Hat, Inc. +Trademark: Liberation is a trademark of Red Hat, Inc. registered in U.S. Patent and Trademark Office and certain other jurisdictions. +``` + +No OFL Reserved Font Name is declared in these files. Each file's description +field notes the Arimo / Tinos / Cousine design lineage (Steve Matteson, +Ascender). Those names are not declared as Reserved Font Names here. + +## Conversion notice (covers OFL section 1 / FAQ 2.2.1 and Apache-2.0 section 4(b)) + +The WOFF2 faces in this distribution are **format-only conversions** of the +TrueType sources, produced with `fontTools` (`flavor="woff2"`, Brotli) with **no +subsetting** and the WOFF2 **metadata block omitted**. No glyph outlines, +advance widths, vertical metrics, `cmap`, or `name`-table notices were changed. + +Because the font data is unchanged except for WOFF2 compression and the metadata +block is omitted, the conversions are **not "Modified Versions"** under OFL-1.1 +(OFL FAQ 2.2.1) and lawfully retain the original font names, including the +Carlito Reserved Font Name. For Caladea, the same statement satisfies the +Apache-2.0 section 4(b) "modified files" notice. Caladea carries **no upstream +`NOTICE` file**, so Apache-2.0 section 4(d) adds nothing. + +## Verification evidence (this ship set, 2026-06-03) + +- **20 / 20 WOFF2 faces:** WOFF2 flavor, WOFF2 metadata block omitted, `name` + table byte-identical to the source TTF, identical glyph count and `cmap`. +- **Metrics:** `unitsPerEm`, `hhea` ascent/descent, OS/2 win/typo ascent/descent, + and every glyph advance width compared source-vs-WOFF2: + `ALL METRICS PRESERVED` (`evidence/metric-verification-output.txt`). + +## Full license texts + +- OFL-1.1 (Carlito, Liberation): `OFL.txt` in this directory. The copyright + notices above are also stacked at the top of that file. +- Apache-2.0 (Caladea): `Apache-2.0.txt` in this directory. + +SuperDoc does not relicense these fonts. They remain under their own OFL-1.1 / +Apache-2.0 terms regardless of the license under which SuperDoc itself is offered +(AGPLv3 community build or commercial). diff --git a/shared/font-system/assets/OFL.txt b/shared/font-system/assets/OFL.txt index 51ff4e3d50..ff67188c11 100644 --- a/shared/font-system/assets/OFL.txt +++ b/shared/font-system/assets/OFL.txt @@ -1,9 +1,26 @@ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 This is the license text covering the OFL-1.1 fonts bundled in this directory -(Carlito, Liberation Sans, Liberation Serif, Liberation Mono). Per-font copyright -and Reserved Font Name statements are in LICENSES.md. Official text: -https://openfontlicense.org/open-font-license-official-text/ +(Carlito, Liberation Sans, Liberation Serif, Liberation Mono). The copyright and +Reserved Font Name statements for those fonts are reproduced verbatim below, +taken from the fonts' own name tables, so they travel with this license text. +LICENSES.md restates them for convenience. +Official OFL text: https://openfontlicense.org/open-font-license-official-text/ + +----------------------------------------------------------- +COPYRIGHT NOTICES (the "above copyright notice" required by condition 2) + +Carlito: + Copyright (c) 2010-2013 by tyPoland Lukasz Dziedzic + (http://www.typoland.com/) with Reserved Font Name "Carlito". + Licensed under the SIL Open Font License, Version 1.1. + +Liberation Sans, Liberation Serif, Liberation Mono: + Digitized data copyright (c) 2010 Google Corporation. + Copyright (c) 2012 Red Hat, Inc. + Licensed under the SIL Open Font License, Version 1.1. + ("Liberation" is a registered trademark of Red Hat, Inc.; these v2.1.5 + files declare no OFL Reserved Font Name.) ----------------------------------------------------------- PREAMBLE diff --git a/shared/font-system/assets/font-assets.manifest.json b/shared/font-system/assets/font-assets.manifest.json new file mode 100644 index 0000000000..669d98a20b --- /dev/null +++ b/shared/font-system/assets/font-assets.manifest.json @@ -0,0 +1,193 @@ +{ + "schemaVersion": 1, + "spdxExpression": "OFL-1.1 AND Apache-2.0", + "generatedFrom": "Bundled font legal review, 2026-06-03", + "families": [ + { + "family": "Carlito", + "replaces": ["Calibri"], + "license": "OFL-1.1", + "licenseFiles": ["OFL.txt"], + "version": "1.103", + "upstreamSource": "github.com/googlefonts/carlito", + "reservedFontName": "Carlito", + "copyrightNotice": "Copyright (c) 2010-2013 by tyPoland Lukasz Dziedzic with Reserved Font Name \"Carlito\". Licensed under the SIL Open Font License, Version 1.1.", + "trademarkNotice": "Carlito is a trademark of tyPoland Lukasz Dziedzic.", + "faces": [ + { + "file": "Carlito-Regular.woff2", + "weight": "normal", + "style": "normal", + "sha256": "7d76ec686e1e4b4eb24be79a7b97bc5359860876c63aaf7142cdb6d0c8bc031b" + }, + { + "file": "Carlito-Bold.woff2", + "weight": "bold", + "style": "normal", + "sha256": "9850d2d48b11067c4b9a8e09e94e9c9df25a41a68017e0e3ed8a011017cc55a6" + }, + { + "file": "Carlito-Italic.woff2", + "weight": "normal", + "style": "italic", + "sha256": "5016317d757a507cda505b15bda5b44114d18ff8db260af71ce9021529639fb2" + }, + { + "file": "Carlito-BoldItalic.woff2", + "weight": "bold", + "style": "italic", + "sha256": "d841c947dda8330f7dc55f1f3ceef5b22ca5f695ff41f18a23bcaedb876ae2b2" + } + ] + }, + { + "family": "Caladea", + "replaces": ["Cambria"], + "license": "Apache-2.0", + "licenseFiles": ["Apache-2.0.txt"], + "version": "1.002", + "upstreamSource": "Google crosextra (via LibreOffice resources)", + "reservedFontName": null, + "copyrightNotice": "Copyright (c) 2012 Huerta Tipografia", + "trademarkNotice": "Caladea is a trademark of Huerta Tipografia", + "noticeFile": null, + "faces": [ + { + "file": "Caladea-Regular.woff2", + "weight": "normal", + "style": "normal", + "sha256": "bc550d757aa2f91667c89fe99c576dd2592bb6aa4c03def6ee9d3b7278f8f503" + }, + { + "file": "Caladea-Bold.woff2", + "weight": "bold", + "style": "normal", + "sha256": "750be3bdefd9c13b1a8c7227208387a01aad02c21c348698a43dbc908f5b5778" + }, + { + "file": "Caladea-Italic.woff2", + "weight": "normal", + "style": "italic", + "sha256": "0b93e9951744c59a56895c98286e2ea546d04635d41992b1bb32770a1fe8aa15" + }, + { + "file": "Caladea-BoldItalic.woff2", + "weight": "bold", + "style": "italic", + "sha256": "cd6f404e1e64c1c9ee40f0399fa9bd5be906131345a17325e3d28823289778bb" + } + ] + }, + { + "family": "Liberation Sans", + "replaces": ["Arial", "Helvetica"], + "license": "OFL-1.1", + "licenseFiles": ["OFL.txt"], + "version": "2.1.5", + "upstreamSource": "github.com/liberationfonts/liberation-fonts 2.1.5", + "reservedFontName": null, + "copyrightNotice": "Digitized data copyright (c) 2010 Google Corporation. Copyright (c) 2012 Red Hat, Inc.", + "trademarkNotice": "Liberation is a trademark of Red Hat, Inc. registered in U.S. Patent and Trademark Office and certain other jurisdictions.", + "faces": [ + { + "file": "LiberationSans-Regular.woff2", + "weight": "normal", + "style": "normal", + "sha256": "49cbcd4158fb720bf5dd65e6c37db02c58b22d0549d02c4224d8f44b66508c1a" + }, + { + "file": "LiberationSans-Bold.woff2", + "weight": "bold", + "style": "normal", + "sha256": "abe2e50e207d9c74d078e0f5a1ec721169ccc7ce6151557ad79dfc8ba1404cdb" + }, + { + "file": "LiberationSans-Italic.woff2", + "weight": "normal", + "style": "italic", + "sha256": "56db278b6106cca24670971c20575bdd1ab8e6a645d3608bad3bb02c9f651d9d" + }, + { + "file": "LiberationSans-BoldItalic.woff2", + "weight": "bold", + "style": "italic", + "sha256": "75c36ae5502129079654a3f4670973facf496c65e20c010d74f7fbf33c6406ac" + } + ] + }, + { + "family": "Liberation Serif", + "replaces": ["Times New Roman"], + "license": "OFL-1.1", + "licenseFiles": ["OFL.txt"], + "version": "2.1.5", + "upstreamSource": "github.com/liberationfonts/liberation-fonts 2.1.5", + "reservedFontName": null, + "copyrightNotice": "Digitized data copyright (c) 2010 Google Corporation. Copyright (c) 2012 Red Hat, Inc.", + "trademarkNotice": "Liberation is a trademark of Red Hat, Inc. registered in U.S. Patent and Trademark Office and certain other jurisdictions.", + "faces": [ + { + "file": "LiberationSerif-Regular.woff2", + "weight": "normal", + "style": "normal", + "sha256": "95beb0058c4568d11a5752186b1de80325345dbdc09be665040a70229c4f7781" + }, + { + "file": "LiberationSerif-Bold.woff2", + "weight": "bold", + "style": "normal", + "sha256": "d845a3481af5a79039ea6b02c346da8458538a7f0faa793ff2ab366a2fd34a09" + }, + { + "file": "LiberationSerif-Italic.woff2", + "weight": "normal", + "style": "italic", + "sha256": "1ca64658f7f531e4f575c538e119b387ed67efd9663594d199282da1cda8b58c" + }, + { + "file": "LiberationSerif-BoldItalic.woff2", + "weight": "bold", + "style": "italic", + "sha256": "55da32addec0a25f680ddf8a621ae79475dff5cb44c5699c05e7ff29ef591b1a" + } + ] + }, + { + "family": "Liberation Mono", + "replaces": ["Courier New"], + "license": "OFL-1.1", + "licenseFiles": ["OFL.txt"], + "version": "2.1.5", + "upstreamSource": "github.com/liberationfonts/liberation-fonts 2.1.5", + "reservedFontName": null, + "copyrightNotice": "Digitized data copyright (c) 2010 Google Corporation. Copyright (c) 2012 Red Hat, Inc.", + "trademarkNotice": "Liberation is a trademark of Red Hat, Inc. registered in U.S. Patent and Trademark Office and certain other jurisdictions.", + "faces": [ + { + "file": "LiberationMono-Regular.woff2", + "weight": "normal", + "style": "normal", + "sha256": "fcbbe76483956358837f9d76b88e7c05718b72ab51a44bc621691e6439884b4a" + }, + { + "file": "LiberationMono-Bold.woff2", + "weight": "bold", + "style": "normal", + "sha256": "916ddb6c31087f916c10a298b8934e0cc9db0e99541ab20543a7996c0bf5f91a" + }, + { + "file": "LiberationMono-Italic.woff2", + "weight": "normal", + "style": "italic", + "sha256": "42dfd49060760af285e0230846849394dd2f311299ec1a694c1cb34bf9be46fa" + }, + { + "file": "LiberationMono-BoldItalic.woff2", + "weight": "bold", + "style": "italic", + "sha256": "0fce31aa9a25eb896122b309d86ebfd5541a12d917f2b94669b0e166302e29b9" + } + ] + } + ] +} diff --git a/shared/font-system/package.json b/shared/font-system/package.json index a3c2be2397..5606908d8c 100644 --- a/shared/font-system/package.json +++ b/shared/font-system/package.json @@ -31,5 +31,8 @@ "@types/node": "catalog:", "typescript": "catalog:", "vitest": "catalog:" + }, + "dependencies": { + "@docfonts/fallbacks": "0.4.0" } } diff --git a/shared/font-system/scripts/check-bundled-font-licenses.mjs b/shared/font-system/scripts/check-bundled-font-licenses.mjs new file mode 100644 index 0000000000..7f8913d78a --- /dev/null +++ b/shared/font-system/scripts/check-bundled-font-licenses.mjs @@ -0,0 +1,221 @@ +#!/usr/bin/env node + +import { createHash } from 'node:crypto'; +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const here = path.dirname(fileURLToPath(import.meta.url)); +const fontSystemRoot = path.resolve(here, '..'); +const repoRoot = path.resolve(fontSystemRoot, '../..'); +const assetsDir = path.join(fontSystemRoot, 'assets'); +const manifestPath = path.join(assetsDir, 'font-assets.manifest.json'); +const runtimeManifestPath = path.join(fontSystemRoot, 'src/bundled-manifest.ts'); +const notices = { + licenses: path.join(assetsDir, 'LICENSES.md'), + ofl: path.join(assetsDir, 'OFL.txt'), + apache: path.join(assetsDir, 'Apache-2.0.txt'), + thirdParty: path.join(repoRoot, 'THIRD_PARTY_LICENSES.md'), + superdocPlugin: path.join(repoRoot, 'packages/superdoc/vite-plugin-bundled-fonts.mjs'), +}; + +const VALID_LICENSES = new Set(['OFL-1.1', 'Apache-2.0']); +const VALID_WEIGHTS = new Set(['normal', 'bold']); +const VALID_STYLES = new Set(['normal', 'italic']); +const FOUR_FACE_SUFFIXES = ['Regular', 'Bold', 'Italic', 'BoldItalic']; + +const errors = []; + +function fail(message) { + errors.push(message); +} + +function readText(file) { + return fs.readFileSync(file, 'utf8'); +} + +function normalizeText(text) { + return text.replace(/\s+/g, ' ').trim(); +} + +function includesNormalized(haystack, needle) { + return normalizeText(haystack).includes(normalizeText(needle)); +} + +function oflNoticeFragments(family) { + const fragments = []; + const [ownerNotice] = family.copyrightNotice.split(' with Reserved Font Name '); + if (ownerNotice) fragments.push(ownerNotice); + if (family.reservedFontName) fragments.push(`Reserved Font Name "${family.reservedFontName}"`); + if (family.copyrightNotice.includes('Copyright (c) 2012 Red Hat, Inc.')) { + fragments.push('Copyright (c) 2012 Red Hat, Inc.'); + } + fragments.push('Licensed under the SIL Open Font License, Version 1.1'); + return fragments; +} + +function sha256(file) { + return createHash('sha256').update(fs.readFileSync(file)).digest('hex'); +} + +function readJson(file) { + return JSON.parse(readText(file)); +} + +function sorted(values) { + return [...values].sort((a, b) => a.localeCompare(b)); +} + +function parseRuntimeManifest() { + const source = readText(runtimeManifestPath); + const rows = []; + const pattern = /family\('([^']+)'\s*,\s*'([^']+)'\s*,\s*'([^']+)'\)/g; + let match; + while ((match = pattern.exec(source)) !== null) { + const [, family, filePrefix, license] = match; + rows.push({ + family, + license, + files: FOUR_FACE_SUFFIXES.map((suffix) => `${filePrefix}-${suffix}.woff2`), + }); + } + return rows; +} + +function compareSets(label, actual, expected) { + const actualSorted = sorted(actual); + const expectedSorted = sorted(expected); + const missing = expectedSorted.filter((value) => !actual.has(value)); + const extra = actualSorted.filter((value) => !expected.has(value)); + if (missing.length) fail(`${label}: missing ${missing.join(', ')}`); + if (extra.length) fail(`${label}: extra ${extra.join(', ')}`); +} + +for (const file of [manifestPath, runtimeManifestPath, ...Object.values(notices)]) { + if (!fs.existsSync(file)) fail(`required file missing: ${path.relative(repoRoot, file)}`); +} + +if (errors.length === 0) { + const manifest = readJson(manifestPath); + const assetFiles = new Set(fs.readdirSync(assetsDir).filter((name) => name.endsWith('.woff2'))); + const manifestFamilies = new Set(); + const manifestFiles = new Set(); + const manifestFamilyRows = new Map(); + + if (manifest.schemaVersion !== 1) fail('font-assets.manifest.json schemaVersion must be 1'); + if (manifest.spdxExpression !== 'OFL-1.1 AND Apache-2.0') { + fail('font-assets.manifest.json spdxExpression must be "OFL-1.1 AND Apache-2.0"'); + } + if (!Array.isArray(manifest.families) || manifest.families.length === 0) { + fail('font-assets.manifest.json must contain at least one family'); + } + + for (const family of manifest.families ?? []) { + const familyName = family.family; + if (!familyName) { + fail('manifest family row is missing family'); + continue; + } + if (manifestFamilies.has(familyName)) fail(`duplicate family in manifest: ${familyName}`); + manifestFamilies.add(familyName); + manifestFamilyRows.set(familyName, family); + + if (!VALID_LICENSES.has(family.license)) fail(`${familyName}: unsupported license ${family.license}`); + if (!family.version) fail(`${familyName}: missing version`); + if (!family.upstreamSource) fail(`${familyName}: missing upstreamSource`); + if (!family.copyrightNotice) fail(`${familyName}: missing copyrightNotice`); + if (!Array.isArray(family.licenseFiles) || family.licenseFiles.length === 0) { + fail(`${familyName}: missing licenseFiles`); + } + for (const licenseFile of family.licenseFiles ?? []) { + if (!fs.existsSync(path.join(assetsDir, licenseFile))) + fail(`${familyName}: license file missing: ${licenseFile}`); + } + if (family.license === 'OFL-1.1' && !family.licenseFiles?.includes('OFL.txt')) { + fail(`${familyName}: OFL-1.1 row must list OFL.txt`); + } + if (family.license === 'Apache-2.0' && !family.licenseFiles?.includes('Apache-2.0.txt')) { + fail(`${familyName}: Apache-2.0 row must list Apache-2.0.txt`); + } + + if (!Array.isArray(family.faces) || family.faces.length === 0) { + fail(`${familyName}: missing faces`); + continue; + } + for (const face of family.faces) { + if (!face.file) { + fail(`${familyName}: face missing file`); + continue; + } + if (manifestFiles.has(face.file)) fail(`duplicate face file in manifest: ${face.file}`); + manifestFiles.add(face.file); + + const facePath = path.join(assetsDir, face.file); + if (!fs.existsSync(facePath)) { + fail(`${familyName}: missing face file ${face.file}`); + } else if (sha256(facePath) !== face.sha256) { + fail(`${face.file}: sha256 mismatch`); + } + if (!VALID_WEIGHTS.has(face.weight)) fail(`${face.file}: invalid weight ${face.weight}`); + if (!VALID_STYLES.has(face.style)) fail(`${face.file}: invalid style ${face.style}`); + if (!/^[a-f0-9]{64}$/.test(face.sha256 ?? '')) fail(`${face.file}: sha256 must be 64 lowercase hex chars`); + } + } + + compareSets('asset directory vs font-assets.manifest.json', assetFiles, manifestFiles); + + const runtimeRows = parseRuntimeManifest(); + if (runtimeRows.length === 0) fail('could not parse bundled runtime manifest rows'); + const runtimeFamilies = new Set(runtimeRows.map((row) => row.family)); + compareSets('runtime BUNDLED_MANIFEST vs legal manifest families', runtimeFamilies, manifestFamilies); + for (const runtime of runtimeRows) { + const legal = manifestFamilyRows.get(runtime.family); + if (!legal) continue; + if (legal.license !== runtime.license) { + fail(`${runtime.family}: runtime license ${runtime.license} does not match legal manifest ${legal.license}`); + } + compareSets( + `${runtime.family}: runtime files vs legal manifest files`, + new Set(runtime.files), + new Set((legal.faces ?? []).map((face) => face.file)), + ); + } + + const licensesText = readText(notices.licenses); + const oflText = readText(notices.ofl); + const thirdPartyText = readText(notices.thirdParty); + const superdocPluginText = readText(notices.superdocPlugin); + + if (!licensesText.includes(manifest.spdxExpression)) fail('LICENSES.md missing bundled font SPDX expression'); + if (!thirdPartyText.includes(manifest.spdxExpression)) { + fail('THIRD_PARTY_LICENSES.md missing bundled font SPDX expression'); + } + if (!superdocPluginText.includes('THIRD_PARTY_LICENSES.md')) { + fail('SuperDoc bundled-fonts plugin must emit THIRD_PARTY_LICENSES.md into dist'); + } + + for (const family of manifest.families ?? []) { + if (!licensesText.includes(family.family)) fail(`LICENSES.md missing family ${family.family}`); + if (!thirdPartyText.includes(family.family)) fail(`THIRD_PARTY_LICENSES.md missing family ${family.family}`); + if (!includesNormalized(licensesText, family.copyrightNotice)) { + fail(`LICENSES.md missing copyright notice for ${family.family}`); + } + if (family.trademarkNotice && !includesNormalized(licensesText, family.trademarkNotice)) { + fail(`LICENSES.md missing trademark notice for ${family.family}`); + } + if (family.license === 'OFL-1.1') { + if (!oflText.includes(family.family)) fail(`OFL.txt missing family ${family.family}`); + for (const fragment of oflNoticeFragments(family)) { + if (!includesNormalized(oflText, fragment)) fail(`OFL.txt missing copyright notice for ${family.family}`); + } + } + } +} + +if (errors.length) { + console.error('[font-license-check] FAIL'); + for (const error of errors) console.error(`- ${error}`); + process.exit(1); +} + +console.log('[font-license-check] OK'); diff --git a/shared/font-system/src/report.test.ts b/shared/font-system/src/report.test.ts index b91f135fa3..46676f12bc 100644 --- a/shared/font-system/src/report.test.ts +++ b/shared/font-system/src/report.test.ts @@ -30,6 +30,12 @@ describe('buildFontReport', () => { loadStatus: 'loaded', exportFamily: 'Calibri', missing: false, + evidence: { + evidenceId: 'calibri', + policyAction: 'substitute', + verdict: 'metric_safe', + lineBreakSafe: true, + }, }, ]); }); @@ -263,3 +269,99 @@ describe('buildFaceReport (face-level)', () => { expect(rows[0]?.missing).toBe(true); }); }); + +describe('verdict-aware evidence (rendered substitutes only)', () => { + it('Calibri: metric_safe substitute, line-break safe', () => { + const reg = new FakeRegistry(); + reg.statuses.set('Carlito', 'loaded'); + expect(buildFontReport(['Calibri'], reg.asRegistry())[0].evidence).toEqual({ + evidenceId: 'calibri', + policyAction: 'substitute', + verdict: 'metric_safe', + lineBreakSafe: true, + }); + }); + + it('Calibri Light: category_fallback, visual_only, NOT line-break safe', () => { + const reg = new FakeRegistry(); + reg.statuses.set('Carlito', 'loaded'); + expect(buildFontReport(['Calibri Light'], reg.asRegistry())[0].evidence).toEqual({ + evidenceId: 'calibri-light', + policyAction: 'category_fallback', + verdict: 'visual_only', + lineBreakSafe: false, + }); + }); + + it('Cambria family: top-level worst-face verdict (visual_only), all glyph exceptions', () => { + const reg = new FakeRegistry(); + reg.statuses.set('Caladea', 'loaded'); + const ev = buildFontReport(['Cambria'], reg.asRegistry())[0].evidence; + expect(ev?.verdict).toBe('visual_only'); // NOT a clean clone, despite reason bundled_substitute + expect(ev?.lineBreakSafe).toBe(false); + expect(ev?.glyphExceptions).toMatchObject([{ slot: 'boldItalic', codepoint: 0x60 }]); + }); + + it('Cambria Regular face: per-face metric_safe, and NO unrelated (Bold Italic) glyph exception', () => { + const reg = new FaceRegistry(); + reg.setFace('Caladea', '400', 'normal', 'loaded'); + const [row] = buildFaceReport( + [{ logicalFamily: 'Cambria', weight: '400', style: 'normal' }], + reg.asRegistry(), + ); + expect(row.reason).toBe('bundled_substitute'); + expect(row.evidence).toEqual({ + evidenceId: 'cambria', + policyAction: 'substitute', + verdict: 'metric_safe', + lineBreakSafe: true, + }); + }); + + it('Cambria Bold Italic face: per-face visual_only, includes its grave-accent exception', () => { + const reg = new FaceRegistry(); + reg.setFace('Caladea', '700', 'italic', 'loaded'); + const [row] = buildFaceReport( + [{ logicalFamily: 'Cambria', weight: '700', style: 'italic' }], + reg.asRegistry(), + ); + expect(row.reason).toBe('bundled_substitute'); + expect(row.evidence?.verdict).toBe('visual_only'); + expect(row.evidence?.lineBreakSafe).toBe(false); + expect(row.evidence?.glyphExceptions).toMatchObject([{ slot: 'boldItalic', codepoint: 0x60 }]); + }); + + it('attaches NO evidence for as_requested / custom_mapping / registered_face / fallback_face_absent', () => { + // as_requested: Aptos has no substitute. + const fam = new FakeRegistry(); + fam.statuses.set('Aptos', 'loaded'); + expect(buildFontReport(['Aptos'], fam.asRegistry())[0].evidence).toBeUndefined(); + + // custom_mapping (Regular) + fallback_face_absent (Bold) via a single-face custom map. + const face = new FaceRegistry(); + face.setFace('Gelasio', '400', 'normal', 'loaded'); + face.setAwaitedFaceStatus('Georgia', '700', 'normal', 'fallback_used'); + const resolver = createFontResolver(); + resolver.map('Georgia', 'Gelasio'); + const rows = buildFaceReport( + [ + { logicalFamily: 'Georgia', weight: '400', style: 'normal' }, + { logicalFamily: 'Georgia', weight: '700', style: 'normal' }, + ], + face.asRegistry(), + resolver, + ); + expect(rows.find((r) => r.reason === 'custom_mapping')?.evidence).toBeUndefined(); + expect(rows.find((r) => r.reason === 'fallback_face_absent')?.evidence).toBeUndefined(); + + // registered_face: a real Calibri face registered for the logical family. + const reg2 = new FaceRegistry(); + reg2.setFace('Calibri', '400', 'normal', 'loaded'); + const [calRow] = buildFaceReport( + [{ logicalFamily: 'Calibri', weight: '400', style: 'normal' }], + reg2.asRegistry(), + ); + expect(calRow.reason).toBe('registered_face'); + expect(calRow.evidence).toBeUndefined(); + }); +}); diff --git a/shared/font-system/src/report.ts b/shared/font-system/src/report.ts index caa043723a..63512a7780 100644 --- a/shared/font-system/src/report.ts +++ b/shared/font-system/src/report.ts @@ -1,7 +1,73 @@ import { resolveFontFamily, resolveFace, type FaceKey, type FontResolutionReason, type FontResolver } from './resolver'; import type { FontRegistry } from './registry'; +import { getRenderableFallback, getRenderableFallbackForFace } from '@docfonts/fallbacks'; +import type { + FaceSlot, + GlyphException, + SubstituteVerdict, + SubstitutePolicyAction, +} from './substitution-evidence'; import { isSettled, type FontLoadStatus } from './types'; +/** + * docfonts fidelity evidence for a row where SuperDoc rendered the recommended substitute. Local types + * only (no `@docfonts/fallbacks` in the emitted `.d.ts`). `verdict` describes THIS row: the worst-face + * top-level verdict on family rows, the per-face verdict on face rows - so a consumer never reads + * `reason: 'bundled_substitute'` as a clean clone (Cambria -> Caladea is `visual_only` overall but + * `metric_safe` at Regular). + */ +export interface ResolvedFontEvidence { + /** docfonts evidence id, e.g. "cambria". */ + evidenceId: string; + /** renderer-neutral action behind the substitution. */ + policyAction: SubstitutePolicyAction; + /** fidelity verdict for this row (per-face on face rows; worst-face top-level on family rows). */ + verdict: SubstituteVerdict; + /** advances preserve line breaks: metric_safe, near_metric, or monospace cell_width_only. */ + lineBreakSafe: boolean; + /** named glyph-level divergences qualifying this row's face(s); omitted when none apply. */ + glyphExceptions?: readonly GlyphException[]; +} + +/** Map a runtime weight/style face to its RIBBI slot, for the face-aware docfonts lookup. */ +const faceSlotFor = ({ weight, style }: FaceKey): FaceSlot => { + const bold = weight === '700'; + const italic = style === 'italic'; + if (bold && italic) return 'boldItalic'; + if (bold) return 'bold'; + if (italic) return 'italic'; + return 'regular'; +}; + +/** Whether a resolution reason means SuperDoc rendered the docfonts-recommended substitute. */ +const isRenderedSubstitute = (reason: FontResolutionReason): boolean => + reason === 'bundled_substitute' || reason === 'category_fallback'; + +/** + * The resolver already asset-gated against the bundle, so the report only needs docfonts' verdict + * projection for what rendered - query with everything renderable. + */ +const RENDER_ALL = { canRenderFamily: (): boolean => true }; + +/** + * Project a docfonts fallback - already verdict-/exception-scoped by `@docfonts/fallbacks` (top-level + * for a family lookup, per-face for {@link getRenderableFallbackForFace}) - onto SuperDoc's LOCAL + * {@link ResolvedFontEvidence}. Copies only the report-safe fields, so the package's types never enter + * the emitted `.d.ts`. A null fallback (none renderable) becomes undefined. + */ +function toEvidence( + fallback: ReturnType, +): ResolvedFontEvidence | undefined { + if (!fallback) return undefined; + return { + evidenceId: fallback.evidenceId, + policyAction: fallback.policyAction, + verdict: fallback.verdict, + lineBreakSafe: fallback.lineBreakSafe, + ...(fallback.glyphExceptions ? { glyphExceptions: fallback.glyphExceptions } : {}), + }; +} + /** * One row of the font report: what the document asked for, what SuperDoc actually * renders, why, whether it was ready before measurement, and what export preserves. @@ -42,6 +108,13 @@ export interface FontResolutionRecord { * same family may substitute. Optional + additive, so existing consumers are unaffected. */ face?: { weight: '400' | '700'; style: 'normal' | 'italic' }; + /** + * docfonts fidelity evidence, present ONLY when SuperDoc rendered the recommended substitute + * (`reason` `bundled_substitute` or `category_fallback`). Lets a consumer distinguish a clean clone + * (Calibri -> Carlito, `metric_safe`) from a qualified one (Cambria -> Caladea, `visual_only`) + * instead of treating every `bundled_substitute` alike. Optional + additive. See {@link ResolvedFontEvidence}. + */ + evidence?: ResolvedFontEvidence; } /** @@ -67,6 +140,9 @@ export function buildFontReport( // `fonts.map`; fall back to the shared bundled map for callers without a context. const { physicalFamily, reason } = resolver ? resolver.resolveFontFamily(logical) : resolveFontFamily(logical); const loadStatus = registry.getStatus(physicalFamily); + const evidence = isRenderedSubstitute(reason) + ? toEvidence(getRenderableFallback(logical, RENDER_ALL)) + : undefined; report.push({ logicalFamily: logical, physicalFamily, @@ -76,6 +152,8 @@ export function buildFontReport( // `category_fallback` is a non-metric substitute (reflows / wrong weight), so it lacks a faithful // render the same way `fallback_face_absent` does, regardless of whether the family loaded. missing: reason === 'category_fallback' || (isSettled(loadStatus) && loadStatus !== 'loaded'), + // docfonts verdict for the rendered substitute (family-level: top-level worst-face verdict). + ...(evidence ? { evidence } : {}), }); } return report; @@ -133,6 +211,9 @@ export function buildFaceReport( reason === 'fallback_face_absent' || reason === 'category_fallback' || (isSettled(loadStatus) && loadStatus !== 'loaded'); + const evidence = isRenderedSubstitute(reason) + ? toEvidence(getRenderableFallbackForFace(logicalFamily, faceSlotFor(face), RENDER_ALL)) + : undefined; report.push({ logicalFamily, // For an embedded font, the resolved physical is a document-unique INTERNAL alias @@ -146,6 +227,9 @@ export function buildFaceReport( exportFamily: logicalFamily, missing, face, + // docfonts verdict for the rendered substitute, scoped to THIS face (per-face verdict + only this + // slot's glyph exceptions, so Cambria Regular never shows the Bold Italic exception). + ...(evidence ? { evidence } : {}), }); } return report; diff --git a/shared/font-system/src/resolver.ts b/shared/font-system/src/resolver.ts index af199b4945..a0b212d3a5 100644 --- a/shared/font-system/src/resolver.ts +++ b/shared/font-system/src/resolver.ts @@ -23,6 +23,9 @@ * default instance for callers that have no document context (and for backward compatibility). */ +import { getRenderableFallback } from '@docfonts/fallbacks'; + +import { BUNDLED_MANIFEST } from './bundled-manifest'; import { SUBSTITUTION_EVIDENCE } from './substitution-evidence'; export type FontResolutionReason = @@ -91,23 +94,33 @@ function sortPairs(pairs: Array<[string, string]>): Array<[string, string]> { } /** - * Logical (normalized) -> physical family, DERIVED from the substitution evidence registry - * ({@link ./substitution-evidence}): every row docfonts marks `policyAction: 'substitute'` with a - * physical target. The evidence file is the single source of truth; this is its resolver projection - * (lowercased, quote-stripped keys). + * Asset gate: a docfonts fallback activates only when SuperDoc actually ships its physical clone. The + * evidence registry carries more substitutes than the bundled pack covers (e.g. Georgia -> Gelasio), so + * `canRenderFamily` keeps an un-shipped candidate OUT of the resolver until its `.woff2` lands. The + * predicate checks the SUBSTITUTE (physical) family against `bundled-manifest`, matching the package's + * `getRenderableFallback` contract. + */ +const bundledFamilies: ReadonlySet = new Set(BUNDLED_MANIFEST.map((f) => f.family)); +const canRenderFamily = (family: string): boolean => bundledFamilies.has(family); + +/** + * Logical (normalized) -> physical family, DERIVED from the docfonts substitution registry: every row + * whose ASSET-GATED fallback (`getRenderableFallback`) is a renderable `substitute`. docfonts owns the + * decision (evidence + policy + asset-safety); SuperDoc keeps key normalization (`normalizeFamilyKey`) + * authoritative so resolver lookups land on the same keys. * * The inclusion predicate is policyAction, NOT verdict: a QUALIFIED substitute - e.g. Cambria -> * Caladea, top-level `visual_only` because Bold Italic's U+0060 advance reflows - is still the * recommended substitute and stays mapped. Verdict drives how fidelity is REPORTED (a later pass), * never whether SuperDoc substitutes. Gate status (e.g. Helvetica's stale `ship: fail`) is diagnostic, - * never an inclusion input. Each physical target MUST be a family the bundled pack supplies - * (see `bundled-manifest.ts`); `substitution-evidence.test.ts` enforces that. + * never an inclusion input. The asset gate guarantees every mapped physical ships in the bundled pack. */ function deriveBundledSubstitutes(): Readonly> { const substitutes: Record = {}; for (const row of SUBSTITUTION_EVIDENCE) { - if (row.policyAction === 'substitute' && row.physicalFamily) { - substitutes[normalizeFamilyKey(row.logicalFamily)] = row.physicalFamily; + const fallback = getRenderableFallback(row.logicalFamily, { canRenderFamily }); + if (fallback?.policyAction === 'substitute') { + substitutes[normalizeFamilyKey(row.logicalFamily)] = fallback.substituteFamily; } } return Object.freeze(substitutes); @@ -116,18 +129,20 @@ function deriveBundledSubstitutes(): Readonly> { const BUNDLED_SUBSTITUTES: Readonly> = deriveBundledSubstitutes(); /** - * Logical (normalized) -> non-metric family fallback, DERIVED from the evidence rows docfonts marks - * `policyAction: 'category_fallback'`. These carry the right letterforms but are NOT metric clones - * (they reflow and/or differ in weight, e.g. Calibri Light -> Carlito), so they resolve with reason + * Logical (normalized) -> non-metric family fallback, DERIVED from the docfonts rows whose asset-gated + * fallback is a `category_fallback`. These carry the right letterforms but are NOT metric clones (they + * reflow and/or differ in weight, e.g. Calibri Light -> Carlito), so they resolve with reason * `category_fallback`, never `bundled_substitute`. A SEPARATE map and reason keep a lower-fidelity - * fallback from being mistaken for a clean clone. Same source of truth as - * {@link deriveBundledSubstitutes}; the two partition the evidence by `policyAction`. + * fallback from being mistaken for a clean clone. Same asset gate as {@link deriveBundledSubstitutes}; + * the two partition the renderable fallbacks by `policyAction` (an un-bundled category target, e.g. + * Consolas -> Inconsolata SemiExpanded, stays inert). */ function deriveCategoryFallbacks(): Readonly> { const fallbacks: Record = {}; for (const row of SUBSTITUTION_EVIDENCE) { - if (row.policyAction === 'category_fallback' && row.physicalFamily) { - fallbacks[normalizeFamilyKey(row.logicalFamily)] = row.physicalFamily; + const fallback = getRenderableFallback(row.logicalFamily, { canRenderFamily }); + if (fallback?.policyAction === 'category_fallback') { + fallbacks[normalizeFamilyKey(row.logicalFamily)] = fallback.substituteFamily; } } return Object.freeze(fallbacks); diff --git a/shared/font-system/src/substitution-evidence.test.ts b/shared/font-system/src/substitution-evidence.test.ts index 9a441faea0..d9e6c09533 100644 --- a/shared/font-system/src/substitution-evidence.test.ts +++ b/shared/font-system/src/substitution-evidence.test.ts @@ -23,13 +23,17 @@ describe('substitution evidence -> resolver derivation', () => { for (const [logical, physical] of EXPECTED_SUBSTITUTES) { expect(resolver.resolvePrimaryPhysicalFamily(logical)).toBe(physical); } - // The derivation input is exactly six rows: policyAction 'substitute' with a physical target. - const substituteRows = SUBSTITUTION_EVIDENCE.filter((r) => r.policyAction === 'substitute' && r.physicalFamily); - expect(substituteRows).toHaveLength(EXPECTED_SUBSTITUTES.length); + // Asset-gated input: the registry carries more substitute rows than SuperDoc ships, so count only + // the ones whose clone is bundled (the resolver's actual input). That set is exactly the six pairs. + const bundled = new Set(BUNDLED_MANIFEST.map((f) => f.family)); + const activeSubstitutes = SUBSTITUTION_EVIDENCE.filter( + (r) => r.policyAction === 'substitute' && r.physicalFamily && bundled.has(r.physicalFamily), + ); + expect(activeSubstitutes).toHaveLength(EXPECTED_SUBSTITUTES.length); }); it('does not substitute a family with no evidence row (the map did not grow)', () => { - // Aptos is not in the snapshot (no clean open substitute), so it must pass through unchanged. + // Aptos has a registry row but no open substitute (customer_supplied), so it passes through unchanged. expect(resolveFontFamily('Aptos')).toEqual({ logicalFamily: 'Aptos', physicalFamily: 'Aptos', @@ -50,12 +54,23 @@ describe('substitution evidence -> resolver derivation', () => { }); }); - it('every substitute target is a family the bundled pack ships (asset-availability invariant)', () => { - const bundledFamilies = new Set(BUNDLED_MANIFEST.map((f) => f.family)); - for (const row of SUBSTITUTION_EVIDENCE) { - if (row.policyAction === 'substitute' && row.physicalFamily) { - expect(bundledFamilies.has(row.physicalFamily)).toBe(true); - } + it('every substitute the resolver activates ships in the bundled pack (asset-availability invariant)', () => { + const bundled = new Set(BUNDLED_MANIFEST.map((f) => f.family)); + for (const [, physical] of EXPECTED_SUBSTITUTES) { + expect(bundled.has(physical)).toBe(true); + } + }); + + it('keeps an un-bundled substitute inert until its asset ships (the asset gate, not just the policy)', () => { + // The registry recommends substitutes SuperDoc has not shipped a clone for (e.g. Georgia -> Gelasio). + // canRenderFamily must keep every such row OUT of the resolver: it resolves as_requested, not mapped. + const bundled = new Set(BUNDLED_MANIFEST.map((f) => f.family)); + const unbundled = SUBSTITUTION_EVIDENCE.filter( + (r) => r.policyAction === 'substitute' && r.physicalFamily && !bundled.has(r.physicalFamily), + ); + expect(unbundled.length).toBeGreaterThan(0); // the registry really does carry some (e.g. Georgia) + for (const row of unbundled) { + expect(resolveFontFamily(row.logicalFamily).reason).toBe('as_requested'); } }); diff --git a/shared/font-system/src/substitution-evidence.ts b/shared/font-system/src/substitution-evidence.ts index 449d524543..c592ed9173 100644 --- a/shared/font-system/src/substitution-evidence.ts +++ b/shared/font-system/src/substitution-evidence.ts @@ -1,26 +1,18 @@ /** - * Substitution EVIDENCE: per logical font, the measured docfonts verdict behind SuperDoc's - * logical -> physical substitution. Pure data, no imports. The resolver derives its substitute map - * from this (see `resolver.ts`), so this file is the single source of truth for WHICH logical family - * maps to WHICH physical substitute and HOW faithful that substitution is. + * Substitution EVIDENCE for SuperDoc's logical -> physical font substitution: the measured docfonts + * verdict behind each row. The DATA is sourced from `@docfonts/fallbacks` (one upstream, measured, + * PR-reviewed registry); the TYPE shapes are SuperDoc's own, kept LOCAL so the public facade stays + * self-contained - re-exporting the package's types would leave `@docfonts/fallbacks` in superdoc's + * emitted `.d.ts`, which a consumer (who does not install that package) cannot resolve. * - * Distinct from {@link ./bundled-manifest} (the PHYSICAL pack: which `.woff2` files ship). That is the - * asset layer; this is the EVIDENCE layer - which proprietary font each substitute stands in for, the - * docfonts verdict, per-face verdicts, and the worst-case advance delta that gates layout fidelity. - * - * VENDORED SNAPSHOT. docfonts (`@docfonts/core` + `@docfonts/registry`) is the upstream source of - * truth: a measured, reviewed registry kept in a separate repo, not yet a build dependency of - * SuperDoc. These rows are a hand-reviewed copy of the docfonts EvidenceRecords for the families - * SuperDoc currently substitutes; `evidenceId` + `measurementRefs` point back to the source record. A - * generator/import is deferred until docfonts is a dependency CI can reproduce - until then this is - * reviewed evidence (committed, PR-reviewed), never an unsupervised generated truth source. - * - * Scope note: this is the DATA plus the resolver derivation only. Reports do NOT yet branch on - * `verdict` - Cambria still resolves to Caladea and reports `bundled_substitute`; verdict-aware - * diagnostics are a later pass. The richer fields ride along as data so that pass needs no reshape. + * The const assignment at the bottom pins the package's rows to SuperDoc's {@link SubstitutionEvidence} + * contract: if the registry's shape stops matching, this file fails to compile - a build-time drift + * guard. docfonts owns the evidence; SuperDoc owns WHICH rows activate (asset-gated in `resolver.ts` + * against `bundled-manifest`) and how they load, render, and report. */ +import { SUBSTITUTION_EVIDENCE as DOCFONTS_EVIDENCE } from '@docfonts/fallbacks'; -/** docfonts fidelity verdict, best to worst. Vendored from `@docfonts/core` `Verdict`. */ +/** docfonts fidelity verdict, best to worst. */ export type SubstituteVerdict = | 'metric_safe' // advances within the DIRECT threshold (weighted-mean <= 0.5%, worst-case <= 1%) | 'near_metric' // LIKELY band: weighted-mean <= 1%, worst-case <= 2.5% - near-exact, a few glyphs drift @@ -30,7 +22,7 @@ export type SubstituteVerdict = | 'preserve_only' // keep the original name, do not substitute (e.g. math / symbol fonts) | 'no_substitute'; // no open candidate qualifies -/** docfonts renderer-neutral resolution action. Vendored from `@docfonts/core` `PolicyAction`. */ +/** docfonts renderer-neutral resolution action. */ export type SubstitutePolicyAction = | 'substitute' // render the named physical candidate in place of the logical font | 'category_fallback' // no clean candidate; fall back to a generic category (serif / sans / mono) @@ -87,7 +79,8 @@ export interface GlyphException { /** * One logical font's substitution evidence. Mirrors the renderer-relevant fields of a docfonts * EvidenceRecord and omits its prose (`notes`, `confidence`, measured dates): SuperDoc decides from - * structured data, not free text. + * structured data, not free text. The {@link SUBSTITUTION_EVIDENCE} assignment enforces that the + * package's rows conform to this shape. */ export interface SubstitutionEvidence { /** docfonts EvidenceRecord id - the provenance pointer back to the source record, e.g. "cambria". */ @@ -120,127 +113,9 @@ export interface SubstitutionEvidence { } /** - * The substitution evidence for every family SuperDoc currently substitutes - six rows, vendored from - * docfonts. The resolver maps the rows whose `policyAction` is `substitute`; the verdict / per-face / - * glyph-exception fields are carried for the later verdict-aware reporting pass and are not yet read. + * The reviewed substitution evidence, sourced from `@docfonts/fallbacks` and pinned to SuperDoc's + * {@link SubstitutionEvidence} contract (the assignment is the drift guard - see the file header). The + * resolver activates the rows it can render (asset-gated); the verdict / per-face / glyph-exception + * fields ride along for the later verdict-aware reporting pass and are not read for inclusion. */ -export const SUBSTITUTION_EVIDENCE: readonly SubstitutionEvidence[] = Object.freeze([ - { - evidenceId: 'calibri', - logicalFamily: 'Calibri', - physicalFamily: 'Carlito', - verdict: 'metric_safe', - faces: { regular: true, bold: true, italic: true, boldItalic: true }, - advance: { meanDelta: 0, maxDelta: 0 }, - gates: { static: 'pass', metric: 'pass', layout: 'pass', ship: 'pass' }, - policyAction: 'substitute', - measurementRefs: ['calibri__carlito#analytic_advance#2026-06-03', 'calibri__carlito#face_aggregate#2026-06-03'], - candidateLicense: 'OFL-1.1', - exportRule: 'preserve_original_name', - }, - { - // The QUALIFIED case. Regular/bold/italic are metric_safe, but Caladea's Bold Italic grave accent - // (U+0060) advance diverges ~23%, so a line containing it reflows. The worst face rolls the - // top-level verdict to `visual_only`; policyAction stays `substitute` (Caladea IS the recommended - // substitute), which is why the resolver still maps Cambria. faceVerdicts is authoritative. - evidenceId: 'cambria', - logicalFamily: 'Cambria', - physicalFamily: 'Caladea', - verdict: 'visual_only', - faceVerdicts: { regular: 'metric_safe', bold: 'metric_safe', italic: 'metric_safe', boldItalic: 'visual_only' }, - glyphExceptions: [ - { - slot: 'boldItalic', - codepoint: 0x60, - advanceDelta: 0.231, - note: 'Caladea Bold Italic grave accent (U+0060) advance diverges ~23% from Cambria; lines containing it reflow.', - }, - ], - faces: { regular: true, bold: true, italic: true, boldItalic: true }, - advance: { meanDelta: 0.0002378, maxDelta: 0.2310758 }, - gates: { static: 'pass', metric: 'pass', layout: 'not_run', ship: 'pass' }, - policyAction: 'substitute', - measurementRefs: [ - 'cambria_regular__caladea#regular#w400#d2f6cad3#analytic_advance#2026-06-04', - 'cambria_bold__caladea#bold#w700#74eda4fc#analytic_advance#2026-06-04', - 'cambria_italic__caladea#italic#w400#9c968bf6#analytic_advance#2026-06-04', - 'cambria_boldItalic__caladea#boldItalic#w700#f47a35ad#analytic_advance#2026-06-04', - ], - candidateLicense: 'Apache-2.0', - exportRule: 'preserve_original_name', - }, - { - evidenceId: 'arial', - logicalFamily: 'Arial', - physicalFamily: 'Liberation Sans', - verdict: 'metric_safe', - faces: { regular: true, bold: true, italic: true, boldItalic: true }, - advance: { meanDelta: 0, maxDelta: 0 }, - gates: { static: 'pass', metric: 'pass', layout: 'not_run', ship: 'pass' }, - policyAction: 'substitute', - measurementRefs: ['arial__liberation-sans#analytic_advance#2026-06-03'], - candidateLicense: 'OFL-1.1', - exportRule: 'preserve_original_name', - }, - { - evidenceId: 'times-new-roman', - logicalFamily: 'Times New Roman', - physicalFamily: 'Liberation Serif', - verdict: 'metric_safe', - faces: { regular: true, bold: true, italic: true, boldItalic: true }, - advance: { meanDelta: 0, maxDelta: 0 }, - gates: { static: 'pass', metric: 'pass', layout: 'not_run', ship: 'pass' }, - policyAction: 'substitute', - measurementRefs: ['times-new-roman__liberation-serif#analytic_advance#2026-06-03'], - candidateLicense: 'OFL-1.1', - exportRule: 'preserve_original_name', - }, - { - evidenceId: 'courier-new', - logicalFamily: 'Courier New', - physicalFamily: 'Liberation Mono', - verdict: 'metric_safe', - faces: { regular: true, bold: true, italic: true, boldItalic: true }, - advance: { meanDelta: 0, maxDelta: 0 }, - gates: { static: 'pass', metric: 'pass', layout: 'not_run', ship: 'pass' }, - policyAction: 'substitute', - measurementRefs: ['courier-new__liberation-mono#analytic_advance#2026-06-03'], - candidateLicense: 'OFL-1.1', - exportRule: 'preserve_original_name', - }, - { - // Same candidate and metric verdict as Arial. metric_safe from one Apple/macOS Helvetica - // analytic-advance measurement (0.000% delta). Its static + layout gates are `not_run`, and ship - // was `fail` in docfonts only because SuperDoc had not consumed the alias yet - a stale-until- - // shipped gate, NOT a fidelity signal, so it never gates inclusion here (policyAction does). - evidenceId: 'helvetica', - logicalFamily: 'Helvetica', - physicalFamily: 'Liberation Sans', - verdict: 'metric_safe', - faces: { regular: true, bold: true, italic: true, boldItalic: true }, - advance: { meanDelta: 0, maxDelta: 0 }, - gates: { static: 'not_run', metric: 'pass', layout: 'not_run', ship: 'fail' }, - policyAction: 'substitute', - measurementRefs: ['helvetica__liberation-sans#analytic_advance#2026-06-03'], - candidateLicense: 'OFL-1.1', - exportRule: 'preserve_original_name', - }, - { - // No open Calibri Light clone: Carlito carries the Calibri letterforms but has no Light face, so it - // renders at Regular (weight 400 vs Light 300) and reflows up to 6.6%. `category_fallback` (a family - // fallback, NOT a metric clone), verdict `visual_only`, metric gate fails. `faces` are all false: - // Carlito faithfully supplies none of Calibri Light's own faces - the runtime still renders Carlito - // Regular where it is loadable, but reports it non-metric. - evidenceId: 'calibri-light', - logicalFamily: 'Calibri Light', - physicalFamily: 'Carlito', - verdict: 'visual_only', - faces: { regular: false, bold: false, italic: false, boldItalic: false }, - advance: { meanDelta: 0.0148, maxDelta: 0.066 }, - gates: { static: 'not_run', metric: 'fail', layout: 'not_run', ship: 'fail' }, - policyAction: 'category_fallback', - measurementRefs: ['calibri-light__carlito#analytic_advance#2026-06-05'], - candidateLicense: 'OFL-1.1', - exportRule: 'preserve_original_name', - }, -]); +export const SUBSTITUTION_EVIDENCE: readonly SubstitutionEvidence[] = DOCFONTS_EVIDENCE; diff --git a/tests/consumer-typecheck/snapshots/superdoc-root-classification.json b/tests/consumer-typecheck/snapshots/superdoc-root-classification.json index 329a5f9243..71f165f60f 100644 --- a/tests/consumer-typecheck/snapshots/superdoc-root-classification.json +++ b/tests/consumer-typecheck/snapshots/superdoc-root-classification.json @@ -1,14 +1,14 @@ { "generatedAt": "2026-05-19T11:33:50.546Z", "summary": { - "total": 226, + "total": 233, "byBucket": { "legacy-root": 60, "internal-candidate": 8, - "supported-root": 158 + "supported-root": 165 }, "byConfidence": { - "high": 123, + "high": 130, "medium": 101, "low": 2 } @@ -1840,6 +1840,17 @@ "inEsm": false, "inCjs": false }, + { + "name": "SuperDocFitWidthOptions", + "rationale": "Bounds and padding for the fit-width zoom policy (Config.zoom.fitWidth); named so consumers can type fit policies outside the inline config literal.", + "bucket": "supported-root", + "confidence": "high", + "source": "core", + "inDts": true, + "inDcts": true, + "inEsm": false, + "inCjs": false + }, { "name": "SuperDocFontFace", "bucket": "supported-root", @@ -1928,6 +1939,72 @@ "inEsm": false, "inCjs": false }, + { + "name": "SuperDocViewportChangePayload", + "bucket": "supported-root", + "rationale": "Payload emitted with the viewport-change event and passed to Config.onViewportChange; named so custom fit-to-width consumers can type handlers.", + "confidence": "high", + "source": "core", + "inDts": true, + "inDcts": true, + "inEsm": false, + "inCjs": false + }, + { + "name": "SuperDocViewportMetrics", + "rationale": "Return type of getViewportMetrics(); alias of the viewport-change payload so reads and events share one shape.", + "bucket": "supported-root", + "confidence": "high", + "source": "core", + "inDts": true, + "inDcts": true, + "inEsm": false, + "inCjs": false + }, + { + "name": "SuperDocZoomConfig", + "bucket": "supported-root", + "rationale": "Config.zoom domain object (initial + fitToContainer); named so consumers can build zoom configuration values with a public type.", + "confidence": "high", + "source": "core", + "inDts": true, + "inDcts": true, + "inEsm": false, + "inCjs": false + }, + { + "name": "SuperDocZoomMode", + "rationale": "Closed zoom mode union (manual | fit-width) used by Config.zoom.mode, setZoomMode, and the zoomChange payload.", + "bucket": "supported-root", + "confidence": "high", + "source": "core", + "inDts": true, + "inDcts": true, + "inEsm": false, + "inCjs": false + }, + { + "name": "SuperDocZoomPayload", + "bucket": "supported-root", + "rationale": "Payload emitted with the zoomChange event and passed to Config.onZoomChange; promoted from an internal interface when the config callback made it consumer-facing.", + "confidence": "high", + "source": "core", + "inDts": true, + "inDcts": true, + "inEsm": false, + "inCjs": false + }, + { + "name": "SuperDocZoomState", + "rationale": "Return type of getZoomState(); snapshot of mode, value, fit zoom, and effective bounds for zoom UI.", + "bucket": "supported-root", + "confidence": "high", + "source": "core", + "inDts": true, + "inDcts": true, + "inEsm": false, + "inCjs": false + }, { "name": "SuperEditor", "bucket": "legacy-root", diff --git a/tests/consumer-typecheck/snapshots/superdoc-root-exports.json b/tests/consumer-typecheck/snapshots/superdoc-root-exports.json index 791d719abc..b55d8d7dae 100644 --- a/tests/consumer-typecheck/snapshots/superdoc-root-exports.json +++ b/tests/consumer-typecheck/snapshots/superdoc-root-exports.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-06-02T20:51:59.655Z", + "generatedAt": "2026-06-05T18:14:02.432Z", "ticket": "SD-3212 PR A0", "package": "superdoc", "rootExport": { @@ -183,6 +183,7 @@ "SuperDocExceptionPayload", "SuperDocExceptionRestorePayload", "SuperDocExceptionStorePayload", + "SuperDocFitWidthOptions", "SuperDocFontFace", "SuperDocFontFamily", "SuperDocFontsApi", @@ -191,6 +192,12 @@ "SuperDocReadyPayload", "SuperDocState", "SuperDocTelemetryConfig", + "SuperDocViewportChangePayload", + "SuperDocViewportMetrics", + "SuperDocZoomConfig", + "SuperDocZoomMode", + "SuperDocZoomPayload", + "SuperDocZoomState", "SuperEditor", "SuperInput", "SuperToolbar", @@ -418,6 +425,7 @@ "SuperDocExceptionPayload", "SuperDocExceptionRestorePayload", "SuperDocExceptionStorePayload", + "SuperDocFitWidthOptions", "SuperDocFontFace", "SuperDocFontFamily", "SuperDocFontsApi", @@ -426,6 +434,12 @@ "SuperDocReadyPayload", "SuperDocState", "SuperDocTelemetryConfig", + "SuperDocViewportChangePayload", + "SuperDocViewportMetrics", + "SuperDocZoomConfig", + "SuperDocZoomMode", + "SuperDocZoomPayload", + "SuperDocZoomState", "SuperEditor", "SuperInput", "SuperToolbar", @@ -577,11 +591,11 @@ } }, "counts": { - "types.import": 229, - "types.require": 229, + "types.import": 236, + "types.require": 236, "import": 41, "require": 41, - "union": 229 + "union": 236 }, "divergences": { "typesImportVsRequire": { @@ -747,6 +761,7 @@ "SuperDocExceptionPayload", "SuperDocExceptionRestorePayload", "SuperDocExceptionStorePayload", + "SuperDocFitWidthOptions", "SuperDocFontFace", "SuperDocFontFamily", "SuperDocFontsApi", @@ -755,6 +770,12 @@ "SuperDocReadyPayload", "SuperDocState", "SuperDocTelemetryConfig", + "SuperDocViewportChangePayload", + "SuperDocViewportMetrics", + "SuperDocZoomConfig", + "SuperDocZoomMode", + "SuperDocZoomPayload", + "SuperDocZoomState", "SurfaceComponentProps", "SurfaceFloatingPlacement", "SurfaceHandle", diff --git a/tests/consumer-typecheck/snapshots/superdoc-root-exports.md b/tests/consumer-typecheck/snapshots/superdoc-root-exports.md index 515952b933..01ec7ff81a 100644 --- a/tests/consumer-typecheck/snapshots/superdoc-root-exports.md +++ b/tests/consumer-typecheck/snapshots/superdoc-root-exports.md @@ -1,17 +1,17 @@ # superdoc root export inventory (SD-3212 PR A0) -Generated: 2026-06-02T20:51:59.655Z +Generated: 2026-06-05T18:14:02.432Z Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` ## Counts | Source | Path | Count | |---|---|---| -| types.import | `./dist/superdoc/src/public/index.d.ts` | 229 | -| types.require | `./dist/superdoc/src/public/index.d.cts` | 229 | +| types.import | `./dist/superdoc/src/public/index.d.ts` | 236 | +| types.require | `./dist/superdoc/src/public/index.d.cts` | 236 | | import | `./dist/superdoc.es.js` | 41 | | require | `./dist/superdoc.cjs` | 41 | -| **union** | | **229** | +| **union** | | **236** | ## Divergences @@ -19,7 +19,7 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` - types.require only (not in types.import): 0 - ESM only (not in CJS): 0 - CJS only (not in ESM): 0 -- typed but no runtime export (phantom risk): 188 +- typed but no runtime export (phantom risk): 195 - runtime export but not typed (silent shadow on root): 0 ### Type-only names (no runtime) @@ -177,6 +177,7 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` - `SuperDocExceptionPayload` - `SuperDocExceptionRestorePayload` - `SuperDocExceptionStorePayload` +- `SuperDocFitWidthOptions` - `SuperDocFontFace` - `SuperDocFontFamily` - `SuperDocFontsApi` @@ -185,6 +186,12 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` - `SuperDocReadyPayload` - `SuperDocState` - `SuperDocTelemetryConfig` +- `SuperDocViewportChangePayload` +- `SuperDocViewportMetrics` +- `SuperDocZoomConfig` +- `SuperDocZoomMode` +- `SuperDocZoomPayload` +- `SuperDocZoomState` - `SurfaceComponentProps` - `SurfaceFloatingPlacement` - `SurfaceHandle` @@ -217,16 +224,16 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | Name | dts | dcts | esm | cjs | fixtures | jsdoc | docs | examples | demos | boundaries | |---|---|---|---|---|---|---|---|---|---|---| -| `AIWriter` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 4 | 4 | | -| `AnnotatorHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 1 | 1 | | +| `AIWriter` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 4 | | +| `AnnotatorHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 1 | | | `AwarenessState` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `AwarenessUser` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | | `BinaryData` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `BlankDOCX` | ✓ | ✓ | ✓ | ✓ | 0 | | 0 | 1 | 1 | | +| `BlankDOCX` | ✓ | ✓ | ✓ | ✓ | 0 | | 0 | 0 | 1 | | | `BlockNavigationAddress` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | -| `BlocksListResult` | ✓ | ✓ | | | 2 | ✓ | 1 | 1 | 1 | ✓ | -| `BookmarkAddress` | ✓ | ✓ | | | 1 | ✓ | 0 | 1 | 1 | | -| `BookmarkInfo` | ✓ | ✓ | | | 2 | ✓ | 1 | 1 | 1 | ✓ | +| `BlocksListResult` | ✓ | ✓ | | | 2 | ✓ | 1 | 0 | 1 | ✓ | +| `BookmarkAddress` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 1 | | +| `BookmarkInfo` | ✓ | ✓ | | | 2 | ✓ | 1 | 0 | 1 | ✓ | | `BoundingRect` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `CanObject` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | ✓ | | `CanPerformPermissionParams` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | @@ -234,53 +241,53 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | `ChainedCommand` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | ✓ | | `CollaborationConfig` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `CollaborationProvider` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `Command` | ✓ | ✓ | | | 3 | ✓ | 78 | 1 | 8 | ✓ | +| `Command` | ✓ | ✓ | | | 3 | ✓ | 78 | 0 | 8 | ✓ | | `CommandProps` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | ✓ | -| `Comment` | ✓ | ✓ | | | 5 | ✓ | 29 | 48 | 45 | | -| `CommentAddress` | ✓ | ✓ | | | 1 | ✓ | 4 | 3 | 3 | | +| `Comment` | ✓ | ✓ | | | 5 | ✓ | 29 | 3 | 45 | | +| `CommentAddress` | ✓ | ✓ | | | 1 | ✓ | 4 | 0 | 3 | | | `CommentConfig` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `CommentElement` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `CommentLocationsPayload` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `CommentsPayload` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | -| `CommentsPluginKey` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 1 | 1 | ✓ | +| `CommentsPluginKey` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 1 | ✓ | | `CommentsType` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `Config` | ✓ | ✓ | | | 8 | ✓ | 2 | 1 | 2 | ✓ | | `ContentControlActiveChangePayload` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | | `ContentControlClickPayload` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | -| `ContextMenu` | ✓ | ✓ | ✓ | ✓ | 1 | | 7 | 23 | 31 | | +| `ContextMenu` | ✓ | ✓ | ✓ | ✓ | 1 | | 7 | 0 | 31 | | | `ContextMenuConfig` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `ContextMenuContext` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `ContextMenuItem` | ✓ | ✓ | | | 2 | ✓ | 4 | 0 | 5 | | | `ContextMenuSection` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `CoreCommandMap` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | ✓ | -| `DOCX` | ✓ | ✓ | ✓ | ✓ | 2 | | 151 | 32 | 55 | ✓ | +| `DOCX` | ✓ | ✓ | ✓ | ✓ | 2 | | 157 | 24 | 55 | ✓ | | `DirectSurfaceRequest` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `DocRange` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | -| `Document` | ✓ | ✓ | | | 2 | | 290 | 98 | 110 | ✓ | +| `Document` | ✓ | ✓ | | | 2 | | 291 | 56 | 110 | ✓ | | `DocumentApi` | ✓ | ✓ | | | 3 | ✓ | 0 | 11 | 4 | ✓ | -| `DocumentMode` | ✓ | ✓ | | | 3 | ✓ | 2 | 17 | 3 | | -| `DocumentProtectionState` | ✓ | ✓ | | | 1 | ✓ | 1 | 1 | 1 | | +| `DocumentMode` | ✓ | ✓ | | | 3 | ✓ | 2 | 16 | 3 | | +| `DocumentProtectionState` | ✓ | ✓ | | | 1 | ✓ | 1 | 0 | 1 | | | `DocxFileEntry` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `DocxZipper` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 1 | 1 | ✓ | -| `Editor` | ✓ | ✓ | ✓ | ✓ | 8 | | 195 | 38 | 69 | ✓ | +| `DocxZipper` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 1 | ✓ | +| `Editor` | ✓ | ✓ | ✓ | ✓ | 8 | | 195 | 20 | 69 | ✓ | | `EditorCommands` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | ✓ | | `EditorEventMap` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `EditorExtension` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `EditorLifecycleState` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `EditorOptions` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 2 | | -| `EditorState` | ✓ | ✓ | | | 4 | ✓ | 7 | 1 | 1 | ✓ | +| `EditorState` | ✓ | ✓ | | | 4 | ✓ | 7 | 0 | 1 | ✓ | | `EditorSurface` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `EditorTransactionEvent` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `EditorUpdateEvent` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `EditorView` | ✓ | ✓ | | | 4 | ✓ | 2 | 0 | 0 | ✓ | -| `EntityAddress` | ✓ | ✓ | | | 2 | ✓ | 276 | 11 | 8 | | +| `EntityAddress` | ✓ | ✓ | | | 2 | ✓ | 276 | 0 | 8 | | | `ExportDocxParams` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `ExportFormat` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `ExportOptions` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `ExportParams` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `ExportType` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `ExtensionCommandMap` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | ✓ | -| `Extensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 14 | 7 | 3 | ✓ | +| `Extensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 14 | 6 | 3 | ✓ | | `ExternalPopoverRenderContext` | ✓ | ✓ | | | 1 | ✓ | 1 | 0 | 0 | | | `ExternalSurfaceRenderContext` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `FieldValue` | ✓ | ✓ | | | 1 | ✓ | 7 | 0 | 0 | | @@ -291,20 +298,20 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | `FindReplaceResolution` | ✓ | ✓ | | | 1 | ✓ | 1 | 0 | 0 | | | `FlowBlock` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | ✓ | | `FlowMode` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `FontAssetUrlContext` | ✓ | ✓ | | | 0 | | 0 | 0 | 0 | | -| `FontAssetUrlResolver` | ✓ | ✓ | | | 0 | | 0 | 0 | 0 | | +| `FontAssetUrlContext` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | +| `FontAssetUrlResolver` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | | `FontConfig` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `FontFaceConfig` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `FontFamilyConfig` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | -| `FontResolutionRecord` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | -| `FontsChangedPayload` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | -| `FontsConfig` | ✓ | ✓ | | | 0 | | 0 | 0 | 0 | | +| `FontResolutionRecord` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | +| `FontsChangedPayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | +| `FontsConfig` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | | `FontsResolvedPayload` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | -| `HTML` | ✓ | ✓ | ✓ | ✓ | 2 | | 85 | 157 | 202 | | +| `HTML` | ✓ | ✓ | ✓ | ✓ | 2 | | 87 | 12 | 202 | | | `ImageDeselectedEvent` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `ImageSelectedEvent` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `IntentSurfaceRequest` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | -| `Layout` | ✓ | ✓ | | | 3 | ✓ | 9 | 22 | 22 | ✓ | +| `Layout` | ✓ | ✓ | | | 3 | ✓ | 9 | 0 | 22 | ✓ | | `LayoutEngineOptions` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `LayoutError` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `LayoutFragment` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | @@ -317,11 +324,11 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | `LinkPopoverResolution` | ✓ | ✓ | | | 1 | ✓ | 1 | 0 | 0 | | | `LinkPopoverResolver` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `ListDefinitionsPayload` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | -| `Measure` | ✓ | ✓ | | | 3 | ✓ | 0 | 1 | 1 | | +| `Measure` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 1 | | | `Modules` | ✓ | ✓ | | | 2 | ✓ | 4 | 0 | 0 | | | `NavigableAddress` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `OpenOptions` | ✓ | ✓ | | | 3 | ✓ | 1 | 0 | 0 | | -| `PDF` | ✓ | ✓ | ✓ | ✓ | 2 | | 35 | 1 | 1 | ✓ | +| `PDF` | ✓ | ✓ | ✓ | ✓ | 2 | | 37 | 0 | 1 | ✓ | | `PageMargins` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `PageSize` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `PageStyles` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | @@ -340,7 +347,7 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | `PermissionResolverParams` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `PositionHit` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `PresenceOptions` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `PresentationEditor` | ✓ | ✓ | ✓ | ✓ | 3 | | 0 | 44 | 40 | ✓ | +| `PresentationEditor` | ✓ | ✓ | ✓ | ✓ | 3 | | 0 | 0 | 40 | ✓ | | `PresentationEditorOptions` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `ProofingCapabilities` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `ProofingCheckRequest` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | @@ -359,26 +366,26 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | `RemoteCursorState` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `RemoteCursorsRenderPayload` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `RemoteUserInfo` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `ResolveRangeOutput` | ✓ | ✓ | | | 3 | ✓ | 1 | 1 | 1 | | +| `ResolveRangeOutput` | ✓ | ✓ | | | 3 | ✓ | 1 | 0 | 1 | | | `ResolvedFindReplaceTexts` | ✓ | ✓ | | | 1 | ✓ | 2 | 0 | 0 | | | `ResolvedPasswordPromptTexts` | ✓ | ✓ | | | 1 | ✓ | 1 | 0 | 0 | | | `SaveOptions` | ✓ | ✓ | | | 4 | ✓ | 1 | 0 | 0 | | -| `Schema` | ✓ | ✓ | | | 4 | ✓ | 5 | 4 | 4 | ✓ | +| `Schema` | ✓ | ✓ | | | 4 | ✓ | 5 | 0 | 4 | ✓ | | `ScrollIntoViewInput` | ✓ | ✓ | | | 2 | ✓ | 1 | 0 | 0 | | | `ScrollIntoViewOutput` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `SdtRef` | ✓ | ✓ | | | 0 | | 6 | 0 | 0 | | | `SearchMatch` | ✓ | ✓ | | | 2 | ✓ | 3 | 0 | 0 | | -| `SectionHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 1 | 1 | | +| `SectionHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 1 | | | `SectionMetadata` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `SelectionApi` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `SelectionCommandContext` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `SelectionCurrentInput` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `SelectionHandle` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `SelectionInfo` | ✓ | ✓ | | | 2 | ✓ | 6 | 2 | 1 | | -| `SlashMenu` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 1 | 1 | | -| `StoryLocator` | ✓ | ✓ | | | 1 | ✓ | 123 | 10 | 3 | | -| `SuperConverter` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 1 | 3 | ✓ | -| `SuperDoc` | ✓ | ✓ | ✓ | ✓ | 22 | | 1034 | 233 | 249 | ✓ | +| `SelectionInfo` | ✓ | ✓ | | | 2 | ✓ | 6 | 0 | 1 | | +| `SlashMenu` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 1 | | +| `StoryLocator` | ✓ | ✓ | | | 1 | ✓ | 123 | 0 | 3 | | +| `SuperConverter` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 3 | ✓ | +| `SuperDoc` | ✓ | ✓ | ✓ | ✓ | 22 | | 1046 | 187 | 250 | ✓ | | `SuperDocAwarenessUpdatePayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `SuperDocCommentsUpdatePayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `SuperDocEditorPayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | @@ -386,17 +393,24 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | `SuperDocExceptionPayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `SuperDocExceptionRestorePayload` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | | `SuperDocExceptionStorePayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | +| `SuperDocFitWidthOptions` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | | `SuperDocFontFace` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `SuperDocFontFamily` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | -| `SuperDocFontsApi` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | +| `SuperDocFontsApi` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `SuperDocLayoutEngineOptions` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | | `SuperDocLockedPayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `SuperDocReadyPayload` | ✓ | ✓ | | | 2 | | 2 | 0 | 0 | | | `SuperDocState` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | | `SuperDocTelemetryConfig` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | -| `SuperEditor` | ✓ | ✓ | ✓ | ✓ | 1 | | 16 | 3 | 5 | | -| `SuperInput` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 2 | 2 | | -| `SuperToolbar` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 1 | 4 | ✓ | +| `SuperDocViewportChangePayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | +| `SuperDocViewportMetrics` | ✓ | ✓ | | | 2 | | 1 | 0 | 0 | | +| `SuperDocZoomConfig` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | +| `SuperDocZoomMode` | ✓ | ✓ | | | 1 | | 0 | 0 | 0 | | +| `SuperDocZoomPayload` | ✓ | ✓ | | | 2 | | 0 | 0 | 0 | | +| `SuperDocZoomState` | ✓ | ✓ | | | 2 | | 1 | 0 | 0 | | +| `SuperEditor` | ✓ | ✓ | ✓ | ✓ | 1 | | 16 | 0 | 5 | | +| `SuperInput` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 2 | | +| `SuperToolbar` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 4 | ✓ | | `SurfaceComponentProps` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `SurfaceFloatingPlacement` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `SurfaceHandle` | ✓ | ✓ | | | 2 | ✓ | 2 | 0 | 0 | | @@ -407,42 +421,42 @@ Source: packed and installed `tests/consumer-typecheck/node_modules/superdoc` | `SurfaceResolver` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `SurfacesModuleConfig` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `TelemetryEvent` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `TextAddress` | ✓ | ✓ | | | 3 | ✓ | 404 | 10 | 7 | | -| `TextSegment` | ✓ | ✓ | | | 3 | ✓ | 8 | 2 | 4 | | -| `TextTarget` | ✓ | ✓ | | | 3 | ✓ | 45 | 8 | 10 | | -| `Toolbar` | ✓ | ✓ | ✓ | ✓ | 1 | | 35 | 12 | 15 | | +| `TextAddress` | ✓ | ✓ | | | 3 | ✓ | 404 | 0 | 7 | | +| `TextSegment` | ✓ | ✓ | | | 3 | ✓ | 8 | 0 | 4 | | +| `TextTarget` | ✓ | ✓ | | | 3 | ✓ | 45 | 0 | 10 | | +| `Toolbar` | ✓ | ✓ | ✓ | ✓ | 1 | | 35 | 7 | 15 | | | `TrackChangeAuthor` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `TrackChangesAuthorColorsConfig` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | -| `TrackChangesBasePluginKey` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 1 | 1 | ✓ | +| `TrackChangesBasePluginKey` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 1 | ✓ | | `TrackChangesModuleConfig` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | -| `TrackedChangeAddress` | ✓ | ✓ | | | 1 | ✓ | 13 | 3 | 3 | | +| `TrackedChangeAddress` | ✓ | ✓ | | | 1 | ✓ | 13 | 0 | 3 | | | `TrackedChangesMode` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `TrackedChangesOverrides` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `Transaction` | ✓ | ✓ | | | 3 | ✓ | 5 | 0 | 0 | ✓ | | `UnsupportedContentItem` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | | `UpgradeToCollaborationOptions` | ✓ | ✓ | | | 2 | ✓ | 0 | 0 | 0 | | -| `User` | ✓ | ✓ | | | 7 | ✓ | 52 | 9 | 30 | | +| `User` | ✓ | ✓ | | | 7 | ✓ | 52 | 8 | 30 | | | `ViewLayout` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `ViewOptions` | ✓ | ✓ | | | 1 | ✓ | 2 | 0 | 0 | | | `ViewingVisibilityConfig` | ✓ | ✓ | | | 1 | ✓ | 0 | 0 | 0 | | | `VirtualizationOptions` | ✓ | ✓ | | | 3 | ✓ | 0 | 0 | 0 | | -| `assertNodeType` | ✓ | ✓ | ✓ | ✓ | 1 | | 2 | 1 | 1 | ✓ | -| `buildTheme` | ✓ | ✓ | ✓ | ✓ | 1 | | 4 | 1 | 1 | | -| `compareVersions` | ✓ | ✓ | ✓ | ✓ | 0 | | 0 | 1 | 1 | | -| `createTheme` | ✓ | ✓ | ✓ | ✓ | 1 | | 21 | 9 | 1 | | -| `createZip` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 1 | 1 | ✓ | -| `defineMark` | ✓ | ✓ | ✓ | ✓ | 2 | | 3 | 1 | 1 | ✓ | -| `defineNode` | ✓ | ✓ | ✓ | ✓ | 2 | | 4 | 1 | 1 | ✓ | -| `fieldAnnotationHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 2 | 1 | 3 | | -| `getActiveFormatting` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 2 | 2 | | -| `getAllowedImageDimensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 1 | 1 | | -| `getFileObject` | ✓ | ✓ | ✓ | ✓ | 0 | | 0 | 1 | 7 | | -| `getMarksFromSelection` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 2 | 2 | | -| `getRichTextExtensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 1 | 1 | 1 | ✓ | -| `getSchemaIntrospection` | ✓ | ✓ | ✓ | ✓ | 0 | | 3 | 1 | 1 | | -| `getStarterExtensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 8 | 3 | 5 | ✓ | -| `isMarkType` | ✓ | ✓ | ✓ | ✓ | 2 | | 2 | 1 | 1 | ✓ | -| `isNodeType` | ✓ | ✓ | ✓ | ✓ | 2 | | 2 | 1 | 1 | ✓ | -| `registeredHandlers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 1 | 1 | | -| `superEditorHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 1 | 1 | | -| `trackChangesHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 1 | 1 | | +| `assertNodeType` | ✓ | ✓ | ✓ | ✓ | 1 | | 2 | 0 | 1 | ✓ | +| `buildTheme` | ✓ | ✓ | ✓ | ✓ | 1 | | 4 | 0 | 1 | | +| `compareVersions` | ✓ | ✓ | ✓ | ✓ | 0 | | 0 | 0 | 1 | | +| `createTheme` | ✓ | ✓ | ✓ | ✓ | 1 | | 21 | 8 | 1 | | +| `createZip` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 1 | ✓ | +| `defineMark` | ✓ | ✓ | ✓ | ✓ | 2 | | 3 | 0 | 1 | ✓ | +| `defineNode` | ✓ | ✓ | ✓ | ✓ | 2 | | 4 | 0 | 1 | ✓ | +| `fieldAnnotationHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 2 | 0 | 3 | | +| `getActiveFormatting` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 2 | | +| `getAllowedImageDimensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 1 | | +| `getFileObject` | ✓ | ✓ | ✓ | ✓ | 0 | | 0 | 0 | 7 | | +| `getMarksFromSelection` | ✓ | ✓ | ✓ | ✓ | 2 | | 0 | 0 | 2 | | +| `getRichTextExtensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 1 | 0 | 1 | ✓ | +| `getSchemaIntrospection` | ✓ | ✓ | ✓ | ✓ | 0 | | 3 | 0 | 1 | | +| `getStarterExtensions` | ✓ | ✓ | ✓ | ✓ | 2 | | 8 | 2 | 5 | ✓ | +| `isMarkType` | ✓ | ✓ | ✓ | ✓ | 2 | | 2 | 0 | 1 | ✓ | +| `isNodeType` | ✓ | ✓ | ✓ | ✓ | 2 | | 2 | 0 | 1 | ✓ | +| `registeredHandlers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 1 | | +| `superEditorHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 1 | | +| `trackChangesHelpers` | ✓ | ✓ | ✓ | ✓ | 1 | | 0 | 0 | 1 | | diff --git a/tests/consumer-typecheck/src/all-public-types.ts b/tests/consumer-typecheck/src/all-public-types.ts index 0cf5758c11..0e26fed209 100644 --- a/tests/consumer-typecheck/src/all-public-types.ts +++ b/tests/consumer-typecheck/src/all-public-types.ts @@ -174,6 +174,7 @@ import type { SuperDocExceptionPayload, SuperDocExceptionRestorePayload, SuperDocExceptionStorePayload, + SuperDocFitWidthOptions, SuperDocFontFace, SuperDocFontFamily, SuperDocFontsApi, @@ -182,6 +183,12 @@ import type { SuperDocReadyPayload, SuperDocState, SuperDocTelemetryConfig, + SuperDocViewportChangePayload, + SuperDocViewportMetrics, + SuperDocZoomConfig, + SuperDocZoomMode, + SuperDocZoomPayload, + SuperDocZoomState, SurfaceComponentProps, SurfaceFloatingPlacement, SurfaceHandle, @@ -368,6 +375,7 @@ const _real_SuperDocExceptionEditorPayload: AssertNotAny = true; const _real_SuperDocExceptionRestorePayload: AssertNotAny = true; const _real_SuperDocExceptionStorePayload: AssertNotAny = true; +const _real_SuperDocFitWidthOptions: AssertNotAny = true; const _real_SuperDocFontFace: AssertNotAny = true; const _real_SuperDocFontFamily: AssertNotAny = true; const _real_SuperDocFontsApi: AssertNotAny = true; @@ -376,6 +384,12 @@ const _real_SuperDocLockedPayload: AssertNotAny = true; const _real_SuperDocReadyPayload: AssertNotAny = true; const _real_SuperDocState: AssertNotAny = true; const _real_SuperDocTelemetryConfig: AssertNotAny = true; +const _real_SuperDocViewportChangePayload: AssertNotAny = true; +const _real_SuperDocViewportMetrics: AssertNotAny = true; +const _real_SuperDocZoomConfig: AssertNotAny = true; +const _real_SuperDocZoomMode: AssertNotAny = true; +const _real_SuperDocZoomPayload: AssertNotAny = true; +const _real_SuperDocZoomState: AssertNotAny = true; const _real_SurfaceComponentProps: AssertNotAny = true; const _real_SurfaceFloatingPlacement: AssertNotAny = true; const _real_SurfaceHandle: AssertNotAny = true; diff --git a/tests/consumer-typecheck/src/config-callback-payloads.ts b/tests/consumer-typecheck/src/config-callback-payloads.ts index 111b4e3044..2702003db8 100644 --- a/tests/consumer-typecheck/src/config-callback-payloads.ts +++ b/tests/consumer-typecheck/src/config-callback-payloads.ts @@ -46,6 +46,8 @@ import type { SuperDocEditorPayload, SuperDocLockedPayload, SuperDocReadyPayload, + SuperDocViewportChangePayload, + SuperDocZoomPayload, } from 'superdoc'; type Equal = (() => T extends A ? 1 : 2) extends () => T extends B ? 1 : 2 ? true : false; @@ -103,6 +105,14 @@ const _onListDefinitionsChangeOk: AssertEqual< // (runtime payload builder always sets them, defaulting to null). const _onEditorUpdateOk: AssertEqual, EditorUpdateEvent> = true; +// ─── onZoomChange ─────────────────────────────────────────────────── +// Fires for every zoom source: setZoom(), toolbar, fit-width mode. +const _onZoomChangeOk: AssertEqual, SuperDocZoomPayload> = true; + +// ─── onViewportChange ─────────────────────────────────────────────── +// Pure measurements: fit policy options (min/max/padding) never affect them. +const _onViewportChangeOk: AssertEqual, SuperDocViewportChangePayload> = true; + void [ _onReadyOk, _onEditorBeforeCreateOk, @@ -113,4 +123,6 @@ void [ _onAwarenessUpdateOk, _onListDefinitionsChangeOk, _onEditorUpdateOk, + _onZoomChangeOk, + _onViewportChangeOk, ]; diff --git a/tests/consumer-typecheck/src/imports-ui-react.ts b/tests/consumer-typecheck/src/imports-ui-react.ts index 3ae928fb51..5f6d00fd18 100644 --- a/tests/consumer-typecheck/src/imports-ui-react.ts +++ b/tests/consumer-typecheck/src/imports-ui-react.ts @@ -21,6 +21,7 @@ import { useSuperDocToolbar, useSuperDocCommand, useSuperDocDocument, + useSuperDocZoom, } from 'superdoc/ui/react'; import type { SuperDocHost } from 'superdoc/ui/react'; @@ -38,6 +39,7 @@ const _real_useSuperDocTrackChanges: AssertNotAny = true; const _real_useSuperDocCommand: AssertNotAny = true; const _real_useSuperDocDocument: AssertNotAny = true; +const _real_useSuperDocZoom: AssertNotAny = true; const _real_SuperDocHost: AssertNotAny = true; @@ -52,4 +54,5 @@ void _real_useSuperDocTrackChanges; void _real_useSuperDocToolbar; void _real_useSuperDocCommand; void _real_useSuperDocDocument; +void _real_useSuperDocZoom; void _real_SuperDocHost; diff --git a/tests/consumer-typecheck/src/imports-ui.ts b/tests/consumer-typecheck/src/imports-ui.ts index 08e6022d19..39f737080a 100644 --- a/tests/consumer-typecheck/src/imports-ui.ts +++ b/tests/consumer-typecheck/src/imports-ui.ts @@ -33,6 +33,8 @@ import type { ViewportHandle, ViewportRect, DocumentHandle, + ZoomHandle, + ZoomSlice, DocumentSlice, // Document API shapes re-exported through ui CommentInfo, @@ -74,6 +76,8 @@ const _real_ViewportEntityAddress: AssertNotAny = true; const _real_ViewportHandle: AssertNotAny = true; const _real_ViewportRect: AssertNotAny = true; const _real_DocumentHandle: AssertNotAny = true; +const _real_ZoomHandle: AssertNotAny = true; +const _real_ZoomSlice: AssertNotAny = true; const _real_DocumentSlice: AssertNotAny = true; const _real_CommentInfo: AssertNotAny = true; @@ -109,6 +113,8 @@ void _real_ViewportEntityAddress; void _real_ViewportHandle; void _real_ViewportRect; void _real_DocumentHandle; +void _real_ZoomHandle; +void _real_ZoomSlice; void _real_DocumentSlice; void _real_CommentInfo; void _real_CommentsListResult; diff --git a/tests/consumer-typecheck/src/read-and-navigation-apis.ts b/tests/consumer-typecheck/src/read-and-navigation-apis.ts index 85566c8957..392309e960 100644 --- a/tests/consumer-typecheck/src/read-and-navigation-apis.ts +++ b/tests/consumer-typecheck/src/read-and-navigation-apis.ts @@ -17,7 +17,7 @@ * `goToSearchResult.parameters` is already locked in `search-match.ts`; * this file adds the `returns` assertion for the same method. */ -import type { NavigableAddress, SuperDoc } from 'superdoc'; +import type { NavigableAddress, SuperDoc, SuperDocViewportMetrics, SuperDocZoomState } from 'superdoc'; type Equal = (() => T extends A ? 1 : 2) extends () => T extends B ? 1 : 2 ? true : false; type AssertEqual = Equal extends true ? true : never; @@ -41,6 +41,30 @@ const _htmlValueWithOpts: string[] = sd.getHTML({ unflattenLists: true }); const _zoomReturnOk: AssertEqual, number> = true; const _zoomValue: number = sd.getZoom(); +// ─── getZoomState ──────────────────────────────────────────────────── +// Snapshot of mode/value/fitZoom and the effective fit bounds. fitZoom +// is null until the first viewport measurement. +const _zoomStateReturnOk: AssertEqual, SuperDocZoomState> = true; +const _zoomState = sd.getZoomState(); +const _zoomStateMode: 'manual' | 'fit-width' = _zoomState.mode; +const _zoomStateFit: number | null = _zoomState.fitZoom; +void _zoomStateMode; +void _zoomStateFit; + +// ─── getViewportMetrics ────────────────────────────────────────────── +// Latest pure measurements, or null before editors mount. +const _viewportMetricsReturnOk: AssertEqual< + ReturnType, + SuperDocViewportMetrics | null +> = true; +const _viewportMetrics = sd.getViewportMetrics(); +if (_viewportMetrics) { + const _availableWidth: number = _viewportMetrics.availableWidth; + const _documentWidth: number = _viewportMetrics.documentWidth; + const _fitZoom: number = _viewportMetrics.fitZoom; + void [_availableWidth, _documentWidth, _fitZoom]; +} + // ─── navigateTo ────────────────────────────────────────────────────── // Async navigation to a stable address (bookmark, block, comment, // tracked change). Resolves true iff the address was found and diff --git a/tests/consumer-typecheck/src/superdoc-events.ts b/tests/consumer-typecheck/src/superdoc-events.ts index be611fa4f7..8b1ad8fa32 100644 --- a/tests/consumer-typecheck/src/superdoc-events.ts +++ b/tests/consumer-typecheck/src/superdoc-events.ts @@ -59,9 +59,21 @@ superdoc.on('sidebar-toggle', (isOpened) => { void flag; }); -superdoc.on('zoomChange', ({ zoom }) => { +superdoc.on('zoomChange', ({ zoom, mode }) => { const value: number = zoom; + // `mode` narrows to the closed manual/fit-width union. + const zoomMode: 'manual' | 'fit-width' = mode; void value; + void zoomMode; +}); + +superdoc.on('viewport-change', ({ availableWidth, documentWidth, fitZoom }) => { + const available: number = availableWidth; + const docWidth: number = documentWidth; + const fit: number = fitZoom; + void available; + void docWidth; + void fit; }); superdoc.on('formatting-marks-change', ({ showFormattingMarks, superdoc: instance }) => { @@ -258,16 +270,23 @@ import { createSuperDocUI } from 'superdoc/ui'; void createHeadlessToolbar({ superdoc }); void createSuperDocUI({ superdoc }); -// Custom UI host stub typed precisely to the 3 events the UI +// Custom UI host stub typed precisely to the 4 events the UI // controller subscribes to must satisfy `SuperDocLike`. Pinning this // so a future widening of `SuperDocUIHostEvent` (e.g. re-adding // `formatting-marks-change`) doesn't silently regress this stub // shape: such a change would fail this assertion under strict // (property-syntax) variance, and would still be a precision loss -// even under TS method bivariance. +// even under TS method bivariance. `viewport-change` joined the set +// when `ui.zoom` started observing viewport metrics (SD-3294). declare const customUIHost: { - on?(event: 'editorCreate' | 'document-mode-change' | 'zoomChange', handler: (...args: unknown[]) => void): unknown; - off?(event: 'editorCreate' | 'document-mode-change' | 'zoomChange', handler: (...args: unknown[]) => void): unknown; + on?( + event: 'editorCreate' | 'document-mode-change' | 'zoomChange' | 'viewport-change', + handler: (...args: unknown[]) => void, + ): unknown; + off?( + event: 'editorCreate' | 'document-mode-change' | 'zoomChange' | 'viewport-change', + handler: (...args: unknown[]) => void, + ): unknown; }; void createSuperDocUI({ superdoc: customUIHost }); diff --git a/tests/consumer-typecheck/src/ui-state-control-apis.ts b/tests/consumer-typecheck/src/ui-state-control-apis.ts index 6b01d3a53e..7b40021576 100644 --- a/tests/consumer-typecheck/src/ui-state-control-apis.ts +++ b/tests/consumer-typecheck/src/ui-state-control-apis.ts @@ -56,6 +56,16 @@ const _setZoomParamsOk: AssertEqual, [percent: n const _setZoomReturnOk: AssertEqual, void> = true; sd.setZoom(150); +// ─── setZoomMode ──────────────────────────────────────────────────── +// Switches between manual and fit-width zoom. Closed union parameter; +// invalid strings must be rejected at compile time. +const _setZoomModeParamsOk: AssertEqual, [mode: 'manual' | 'fit-width']> = true; +const _setZoomModeReturnOk: AssertEqual, void> = true; +sd.setZoomMode('fit-width'); +sd.setZoomMode('manual'); +// @ts-expect-error zoom mode is a closed union; only manual/fit-width. +sd.setZoomMode('fit-page'); + // ─── setHighContrastMode ──────────────────────────────────────────── // Forwards to `activeEditor.setHighContrastMode` and writes to the // highContrastModeStore. No-op until the active editor exists.