feat(pptx): applyEdits — lossless surgical-edit API (#95)

Add applyEdits(source, plan, options?): a patch on the original .pptx bytes
rather than a full re-serialize. Everything not named by an edit comes out
byte-identical to the source (masters, layouts, theme, fonts, tags, notes,
embeddings, untouched elements); the result opens in PowerPoint with no repair.

- New elementLocationRegistry in the parser (getElementLocation) maps every
  element id -> its verbatim source XML block, with no placeholder filtering.
- Ops: setText/clearText, setChartData (in-place chart fill keeping type/colour
  + a regenerated, consistent embedded xlsx so Edit-Data works), setTableData,
  setImage, removeElement, addChart, addDiagram, per-slide background, title.
- Slide subset/reorder/repeat from the template; repeats deep-clone from a
  pristine view so edits never bleed across copies.
- Removed slides + their exclusive parts reclaimed by a reachability sweep,
  then reconcileDanglingRels + content-type pruning.
- Unresolved ids / unsupported layout-instantiation surface via onWarning.

Tests on a synthetic 4-slide template incl. the acceptance test (untouched
slide byte-identical, chart workbook updated, zero dangling rels).

Author: karthikmudunuri

.changeset/applyedits-lossless-surgical-edits.md

@@ -0,0 +1,26 @@
+---
+"@textcortex/slidewise": minor
+---
+
+feat(pptx): `applyEdits` — lossless surgical-edit API
+
+Add `applyEdits(source, plan, options?)`: a patch on the original `.pptx` bytes
+rather than a full re-serialize. The create flow can now emit an `EditPlan`
+(subset/reorder/repeat of template slides, each with edits) and get back a valid
+package where everything not named by an edit is byte-identical to the source —
+masters, layouts, theme, embedded fonts, `ppt/tags/*`, notes, embeddings, and
+any untouched element. This removes the lossy round-trip that produced the
+`custGeom`/SVG-fallback/dangling-rel fidelity bugs and lets hosts drop their
+defensive cleanup. `serializeDeck` stays for the live editor / from-scratch decks.
+
+Edits address elements by the same stable ids `parsePptx` returns; slides by
+1-based template index. Supported ops: `setText`/`clearText` (preserve the
+template box + run styling, or rebuild from supplied runs), `setChartData`
+(repopulate a native chart in place — type/colours kept, caches **and** the
+embedded `xlsx` workbook updated so Edit-Data still works), `setTableData`,
+`setImage`, `removeElement`, `addChart`, `addDiagram`, plus per-slide
+`background` and deck `title`. Removed slides and any parts that become
+exclusive to them are reclaimed by a package-wide reachability sweep, then
+dangling relationships and content-types are reconciled. Unresolved element ids
+and unsupported layout-instantiation are surfaced via `onWarning` instead of
+throwing.

README.md

@@ -114,6 +114,57 @@ editor only sees current-shape decks. It throws if the input was written by a
 newer Slidewise than the host has installed — pin the version range you can
 support.
 
+### Lossless surgical edits with `applyEdits`
+
+When you start from a branded template and only need to change a few things
+(swap some text, fill a chart, drop a sample element), a full
+`serializeDeck` round-trip is overkill — and re-rendering unedited elements is
+where fidelity bugs come from. `applyEdits(source, plan)` instead **patches the
+original bytes**: everything not named by an edit comes out byte-identical to
+the source (masters, layouts, theme, embedded fonts, `ppt/tags/*`, notes,
+embeddings, and any untouched element), and the result opens in PowerPoint with
+no repair.
+
+```ts
+import { parsePptx, applyEdits, type EditPlan } from "@textcortex/slidewise";
+
+const deck = await parsePptx(source); // address elements by deck ids
+const plan: EditPlan = {
+  title: "Q3 Results",
+  // Output order = this list. Slides are the source's 1-based template index;
+  // a source slide may repeat for controlled reuse.
+  slides: [
+    {
+      source: { slideIndex: 1 },
+      edits: [{ op: "setText", elementId: titleId, text: "Q3 Results" }],
+    },
+    {
+      source: { slideIndex: 3 },
+      edits: [
+        // Repopulate a native chart in place — type/colours and the embedded
+        // workbook are preserved, so PowerPoint's Edit-Data still works.
+        { op: "setChartData", elementId: chartId, categories: ["Jan", "Feb", "Mar"], series: [{ name: "Revenue", values: [10, 20, 30] }] },
+        { op: "removeElement", elementId: sampleChartId },
+      ],
+    },
+    { source: { slideIndex: 4 }, edits: [] }, // kept byte-identical
+  ],
+};
+
+const out: Uint8Array = await applyEdits(source, plan, {
+  onWarning: (w) => notifyHost(w.message), // unresolved id / unsupported op
+});
+```
+
+Ops: `setText` / `clearText`, `setChartData`, `setTableData`, `setImage`,
+`removeElement`, `addChart`, `addDiagram`, plus per-slide `background` and the
+deck `title`. Elements are addressed by the same stable ids `parsePptx` returns,
+so call `applyEdits` in the same process as the `parsePptx` that produced the
+plan. Removed slides and any parts exclusive to them are reclaimed
+automatically. `serializeDeck` remains the path for the live editor and
+from-scratch decks; `applyEdits` is the lossless path for template-derived
+output.
+
 ### Generating slides from the template's layouts
 
 `parsePptx` exposes the source template's master layouts on `deck.layouts`.

packages/slidewise/src/index.ts

@@ -88,11 +88,18 @@ export {
   type SlideRailItemContextValue,
 } from "./compound";
 
-export { parsePptx, isPptxTemplate, serializeDeck } from "./lib/pptx";
+export { parsePptx, isPptxTemplate, serializeDeck, applyEdits } from "./lib/pptx";
 export type {
   SerializeOptions,
   SerializeWarning,
   SvgRasterizer,
+  EditPlan,
+  PlannedSlide,
+  Edit,
+  Run,
+  Series,
+  Rect,
+  ApplyEditsOptions,
 } from "./lib/pptx";
 export type { ParseDiagnostics, ParseResult } from "./lib/pptx/types";