Known limitations

These are documented, accepted trade-offs — not bugs waiting to be fixed. Each stems directly from a deliberate scope decision (see Architecture).

Limitation	Why
Merge is a planning tool with a scope-limited real export	The beta .pptx export carries over text/tables/background/notes/transitions, but drops images/charts/SmartArt/media — only a content hash was ever kept for those. A full lossless OOXML round-trip writer is out of scope. See Three-way merge.
Transition preview is a simplified crossfade	Not a literal PowerPoint transition engine — clearly labeled as such in the UI. See Rendering fidelity.
Master/layout thumbnails are schematic, not pixel-perfect	The renderer library (@aiden0z/pptx-renderer) renders slides, not raw layout/master parts, so these fall back to dashed placeholder rectangles.
"Shareable link" is a data: URL, not a hosted short link	There's no backend server to host a real short link on — see Architecture.
Notion and Confluence live push usually fail from a static page	Neither service exposes a browser-origin-enabled write API; both are caught gracefully with a fallback pointer to the working file-based export. Slack is the one live-push integration reasonably likely to succeed client-side. See Exports & live push.
Chart/SmartArt/media parts may render as "Schematic," not "Rendered"	A graceful fallback for parts the renderer library can't fully parse — expected behavior, not a parsing failure.
Review state is local to one browser	localStorage-backed, not a shared/synced database. Use the JSON report export/import round-trip to hand a review session to someone else.
Diff engine coverage isn't exhaustive	Theme-color (schemeClr) resolution covers only the common slots (tx1/dk1/tx2/dk2/bg1/lt1/accent1) — other scheme colors fall back to the shape's literal color instead of resolving through the theme. Table-cell-formatting diffs cap at 20 shown differences (+N more). Animation diffs compare a single effect-sequence signature — they detect that something changed, not exact timing/motion-path parameters. No diffing for OLE objects, 3D models, or ink/drawing annotations. See Diff engine.
Deck-alignment thresholds are fixed, not user-configurable	The LCS match threshold (0.18) and move-detection threshold (0.55) were tuned against this project's own sample deck, not validated against a real large deck with many near-duplicate template slides. See Deck-level comparison.
Batch filename-similarity pairing uses an untuned threshold	The bigram Dice-coefficient cutoff (0.3) for filename-based pairing hasn't been validated against real-world messy filename patterns, and isn't user-adjustable. See Batch mode.
On-disk sample fixtures don't cover everything the in-browser sample does	docs/assets/sample_*.pptx (generated by pptxgenjs) don't exercise SmartArt/diagrams, slide transitions, embedded fonts, or real video/audio media — pptxgenjs has no API surface for any of these. The in-browser "Reset to sample" deck still covers all four, for its own narrower purpose (feeding this app's own parser/renderer, never downloaded as a real file).
English-only UI, no full accessibility audit	aria-labels exist on the highest-value icon-only controls and toasts are screen-reader-friendly, but there's no localization and no full keyboard-navigation/focus-ring audit.
The npm CLI opens a browser tab, not a native app window	No dock/taskbar icon, no standalone app process — bin/cli.js is a static file server, not an Electron/Tauri wrapper. See CLI reference.
Offline vendoring has two known gaps	pdfjs-dist (an optional peer dependency of the rendering library, used only for embedded-PDF-object rendering) isn't vendored — this was never functional even before the app went offline-capable. The vendored Spectral font ships only its latin subset (matching the English-only UI); non-Latin text falls back to the browser's default font. See Architecture.
PPTXDIFF_LITE_MODE is all 5 dependencies at once	No way to mix vendored and CDN sourcing per-dependency (e.g. vendored React with CDN pptx-renderer) without hand-editing the source. See CLI reference.
The headless CLI/API aren't published, and batch/report/merge aren't built yet	pptxdiff-cli/@pptxdiff/server are source-only (file: dependencies on their monorepo siblings) — install from a checkout, not npm install. diff/checksum/git integration (textconv/difftool/install-git-integration) ship; batch/report/merge and server authentication for a non-loopback bind are designed but not built. Every invocation currently pays a real headless-browser boot cost (no native, browser-free engine yet). See Headless CLI & Web API.
textconv only extracts shape/placeholder text and speaker notes	Table cell text, chart data labels, and SmartArt text aren't included — narrower than the app's own GUI diff engine, which does cover those. A git diff on a .pptx won't show a change that's only inside a table cell or chart data point.
install-git-integration only writes a repo-local .gitattributes, never a global one	--global sets the git config driver definition machine-wide, but the *.pptx diff=pptxdiff association itself still needs a per-repo .gitattributes (or manually configuring core.attributesFile yourself) — there's no fully zero-per-repo-setup mode yet.
The Homebrew formula isn't in a real tap yet	brew install pptxdiff doesn't work — only brew install --formula <path-or-URL> does, until a dedicated sugatoray/homebrew-pptxdiff tap repo and a cross-repo CI credential are created (both deliberate manual steps, not automated). A CI workflow already keeps the formula's version pin current and, once the tap exists, will push it there automatically. See Homebrew formula.
The Homebrew formula hasn't been verified against real brew locally	brew refuses to run as root, and running it as an unprivileged user in this project's development sandbox hits a blocked host needed for Homebrew's own Ruby runtime — a genuine environment wall, not a formula defect. A CI job runs real brew audit/brew install/brew test on a macOS GitHub Actions runner instead; check its logs the first time it fires.

Headless CLI/API Notes

@pptxdiff/cli and @pptxdiff/server are source-only packages today. CLI diff/checksum, Git integration (textconv/difftool/ install-git-integration), Web API diff/checksum/health, and API discovery (/openapi.json//docs) ship; batch, non-JSON report outputs, merge, non-loopback server authentication, and browser-free @pptxdiff/core engine extraction are still future work.

@pptxdiff/server serves /openapi.json locally, but /docs loads Swagger UI assets from a CDN. The interactive docs page therefore needs network access unless those assets are vendored or replaced by a local renderer later.

Not currently accepting contributions

The project is not open to external contributions at this time. Bug reports and feature requests are still welcome via GitHub issues.