feat(pptx): template-faithful serialization, instantiable layouts, connectors (#86)

Fixes for branded-template -> AI deck generation, plus new authoring primitives:

- fix(pptx): replay slide background/layout by Slide.sourceSlideIndex, not output position
- fix(pptx): deep-copy preserved charts (workbook, colors/style, rels, content types)
- fix(pptx): drive output slide size from non-16:9 source; preserve chrome; invert fit
- feat(pptx): expose master layouts (Deck.layouts) + addSlideFromLayout()
- feat(chart): export buildChartOption/defaultPaletteColor/makeValueFormatter
- feat(pptx): first-class connector element (renderer + <p:cxnSp> writer)

Author: karthikmudunuri

.changeset/template-fidelity-and-authoring.md

@@ -0,0 +1,12 @@
+---
+"@textcortex/slidewise": minor
+---
+
+Template-faithful serialization fixes and new authoring primitives for AI deck generation:
+
+- **Per-slide source mapping** — `Slide.sourceSlideIndex` lets a host that clones / reorders / subsets imported slides declare which source slide each output slide replays its background and layout from, instead of mapping by output position (fixes blank/white-on-white slides on reordered decks).
+- **Deep chart preservation** — preserved charts now carry their full dependency tree (embedded workbook, colors/style parts, rels, content types), so they no longer trigger a PowerPoint repair and keep "Edit Data" + custom styling.
+- **Non-16:9 templates** — a source's real slide size now drives the output (4:3, 16:10, custom), preserving its masters / layouts / theme / fonts and inverting the authoring-canvas fit for emitted elements, instead of silently falling back to a generic 16:9 deck.
+- **Instantiable layouts** — `parsePptx` exposes master layouts on `Deck.layouts`, and the new `addSlideFromLayout(deck, layoutId, opts)` mints a fresh slide bound to a layout with its text placeholders ready to fill.
+- **Chart-option helpers** — `buildChartOption`, `defaultPaletteColor`, and `makeValueFormatter` are exported so hosts can build the exact ECharts options Slidewise renders (e.g. for server-side previews).
+- **Connector primitive** — a first-class `connector` element (straight / bent / curved, arrowheads, flips) with renderer + `<p:cxnSp>` writer support.

packages/slidewise/src/components/editor/ElementView.tsx

@@ -11,11 +11,13 @@ import type {
   IconElement,
   EmbedElement,
   ChartElement,
+  ConnectorElement,
   GroupElement,
   UnknownElement,
   ShadowSpec,
   GlowSpec,
 } from "@/lib/types";
+import { buildChartOption } from "@/lib/chart/chartOption";
 
 export function ElementView({
   el,
@@ -43,6 +45,8 @@ export function ElementView({
       return <EmbedView el={el} />;
     case "chart":
       return <ChartView el={el} />;
+    case "connector":
+      return <ConnectorView el={el} />;
     case "group":
       return <GroupView el={el} editing={editing} onTextCommit={onTextCommit} />;
     case "unknown":
@@ -1014,6 +1018,92 @@ function LineView({ el }: { el: LineElement }) {
   );
 }
 
+/**
+ * Render a connector — a first-class line between two anchor corners of its
+ * bounding box. `flipH`/`flipV` pick the diagonal; `kind` selects straight /
+ * bent (elbow) / curved geometry; `startArrow`/`endArrow` add arrowheads.
+ * Mirrors the `<p:cxnSp>` the writer emits so the editor preview matches save.
+ */
+function ConnectorView({ el }: { el: ConnectorElement }) {
+  const uid = useId().replace(/[^a-zA-Z0-9_-]/g, "");
+  const w = Math.abs(el.w) || 1;
+  const h = Math.abs(el.h) || 1;
+  const sx = el.flipH ? w : 0;
+  const sy = el.flipV ? h : 0;
+  const ex = el.flipH ? 0 : w;
+  const ey = el.flipV ? 0 : h;
+
+  let d: string;
+  if (el.kind === "bent") {
+    const mx = (sx + ex) / 2;
+    d = `M ${sx} ${sy} L ${mx} ${sy} L ${mx} ${ey} L ${ex} ${ey}`;
+  } else if (el.kind === "curved") {
+    const mx = (sx + ex) / 2;
+    d = `M ${sx} ${sy} C ${mx} ${sy} ${mx} ${ey} ${ex} ${ey}`;
+  } else {
+    d = `M ${sx} ${sy} L ${ex} ${ey}`;
+  }
+
+  const startId = `cxn-s-${uid}`;
+  const endId = `cxn-e-${uid}`;
+  const hasStart = el.startArrow && el.startArrow !== "none";
+  const hasEnd = el.endArrow && el.endArrow !== "none";
+
+  return (
+    <svg
+      viewBox={`0 0 ${w} ${h}`}
+      preserveAspectRatio="none"
+      width="100%"
+      height="100%"
+      style={{ overflow: "visible", ...effectStyle(el.shadow, el.glow, "filter") }}
+    >
+      <defs>
+        {hasStart && <ArrowMarker id={startId} color={el.stroke} orient="auto-start-reverse" />}
+        {hasEnd && <ArrowMarker id={endId} color={el.stroke} orient="auto" />}
+      </defs>
+      <path
+        d={d}
+        fill="none"
+        stroke={el.stroke}
+        strokeWidth={el.strokeWidth}
+        strokeDasharray={dashStyleFor(el.dashType, el.strokeWidth).dasharray}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        vectorEffect="non-scaling-stroke"
+        markerStart={hasStart ? `url(#${startId})` : undefined}
+        markerEnd={hasEnd ? `url(#${endId})` : undefined}
+      />
+    </svg>
+  );
+}
+
+/** A reusable triangular arrowhead marker. The PPTX writer encodes the exact
+ *  arrowhead family; the preview uses a single triangular glyph. */
+function ArrowMarker({
+  id,
+  color,
+  orient,
+}: {
+  id: string;
+  color: string;
+  orient: string;
+}) {
+  return (
+    <marker
+      id={id}
+      viewBox="0 0 10 10"
+      refX="9"
+      refY="5"
+      markerWidth="7"
+      markerHeight="7"
+      orient={orient}
+      markerUnits="strokeWidth"
+    >
+      <path d="M 0 0 L 10 5 L 0 10 z" fill={color} />
+    </marker>
+  );
+}
+
 function TableView({ el }: { el: TableElement }) {
   const cols = el.rows[0]?.length ?? 1;
   const rowCount = el.rows.length;
@@ -1315,110 +1405,6 @@ function ChartView({ el }: { el: ChartElement }) {
   return <div ref={ref} style={{ width: "100%", height: "100%" }} />;
 }
 
-/**
- * Translate a Slidewise ChartElement into an ECharts option object. Handles
- * bar / column / line / area / pie / doughnut, including stacked + percent
- * stacked variants. Value labels are surfaced when the source deck had
- * `<c:showVal val="1"/>` on at least one series.
- */
-function buildChartOption(el: ChartElement) {
-  const palette = el.series.map((s, i) => s.color ?? defaultPaletteColor(i));
-  const isPercent = el.grouping === "percentStacked";
-  const valueFormatter = makeValueFormatter(el.valueFormat, isPercent);
-
-  if (el.kind === "pie" || el.kind === "doughnut") {
-    const data = el.categories.map((cat, i) => ({
-      name: cat || `Slice ${i + 1}`,
-      value: el.series[0]?.values[i] ?? 0,
-    }));
-    return {
-      color: palette,
-      title: el.title ? { text: el.title, left: "center", top: 4 } : undefined,
-      tooltip: { trigger: "item", valueFormatter },
-      legend: { bottom: 4 },
-      series: [
-        {
-          type: "pie",
-          radius: el.kind === "doughnut" ? ["45%", "75%"] : "70%",
-          data,
-          label: el.showDataLabels
-            ? { formatter: (p: { value: number }) => valueFormatter(p.value) }
-            : { show: false },
-        },
-      ],
-    };
-  }
-
-  const isHorizontal = el.kind === "bar"; // "column" + everything else: vertical
-  const xAxis = isHorizontal
-    ? { type: "value", axisLabel: { formatter: valueFormatter } }
-    : { type: "category", data: el.categories };
-  const yAxis = isHorizontal
-    ? { type: "category", data: el.categories }
-    : { type: "value", axisLabel: { formatter: valueFormatter } };
-
-  const stackKey =
-    el.grouping === "stacked" || el.grouping === "percentStacked"
-      ? "total"
-      : undefined;
-
-  const series = el.series.map((s, i) => {
-    const color = s.color ?? defaultPaletteColor(i);
-    const base = {
-      name: s.name,
-      type: el.kind === "line" ? "line" : el.kind === "area" ? "line" : "bar",
-      data: s.values.map((v) => (v === null ? 0 : v)),
-      // Pin the colour explicitly so ECharts can't reassign via palette
-      // cycling when multiple series share the same `name` (PowerPoint
-      // decks routinely do this — same label, distinct colour fills).
-      itemStyle: { color },
-      ...(el.kind === "area" ? { areaStyle: { color } } : {}),
-      ...(el.kind === "line"
-        ? { lineStyle: { color }, symbol: "circle", symbolSize: 6 }
-        : {}),
-      ...(stackKey ? { stack: stackKey } : {}),
-      label: el.showDataLabels
-        ? {
-            show: true,
-            position: stackKey ? "inside" : "top",
-            formatter: (p: { value: number }) => valueFormatter(p.value),
-            fontSize: 11,
-            color: stackKey ? "#FFFFFF" : "#111111",
-          }
-        : { show: false },
-    };
-    return base;
-  });
-
-  return {
-    color: palette,
-    title: el.title ? { text: el.title, left: "center", top: 4 } : undefined,
-    tooltip: { trigger: "axis", valueFormatter },
-    legend: { bottom: 4, type: "scroll" },
-    grid: { left: 56, right: 24, top: el.title ? 36 : 16, bottom: 56 },
-    xAxis,
-    yAxis,
-    series,
-  };
-}
-
-function defaultPaletteColor(i: number): string {
-  // Office-ish accent rotation, used when a series omits explicit fill.
-  const palette = ["#4F81BD", "#C0504D", "#9BBB59", "#8064A2", "#4BACC6", "#F79646"];
-  return palette[i % palette.length];
-}
-
-function makeValueFormatter(formatCode: string | undefined, percent: boolean) {
-  return (value: number) => {
-    if (typeof value !== "number" || !Number.isFinite(value)) return "";
-    if (percent) return `${Math.round(value * 100)}%`;
-    if (formatCode && formatCode.includes("$")) {
-      const decimals = (formatCode.match(/0\.(0+)/)?.[1] ?? "").length;
-      return `$${value.toLocaleString(undefined, {
-        minimumFractionDigits: decimals,
-        maximumFractionDigits: decimals,
-      })}`;
-    }
-    return value.toLocaleString();
-  };
-}
+// Chart-option construction (buildChartOption / defaultPaletteColor /
+// makeValueFormatter) lives in @/lib/chart/chartOption so it can be shared with
+// hosts via the public API for server-side previews. ChartView imports it.

packages/slidewise/src/components/editor/__tests__/connector-render.test.tsx

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ElementView } from "../ElementView";
+import type { ConnectorElement } from "@/lib/types";
+
+/**
+ * F3 renderer: the connector element renders to an SVG path with arrowhead
+ * markers, so it shows up in the editor canvas and the host's static
+ * renderToString preview (not as an empty box).
+ */
+
+const connector: ConnectorElement = {
+  id: "c1",
+  type: "connector",
+  x: 0,
+  y: 0,
+  w: 200,
+  h: 120,
+  rotation: 0,
+  z: 1,
+  kind: "curved",
+  stroke: "#3366CC",
+  strokeWidth: 2,
+  endArrow: "triangle",
+};
+
+describe("F3: connector renderer", () => {
+  it("renders an SVG path with an end arrowhead marker", () => {
+    const html = renderToStaticMarkup(<ElementView el={connector} />);
+    expect(html).toContain("<svg");
+    expect(html).toContain("<path");
+    // Curved kind → a cubic bezier command in the path data.
+    expect(html).toContain(" C ");
+    // End arrow → a marker definition + markerEnd reference.
+    expect(html).toContain("<marker");
+    expect(html).toContain("marker-end");
+    expect(html).toContain("#3366CC");
+  });
+
+  it("omits arrowheads when none are set", () => {
+    const html = renderToStaticMarkup(
+      <ElementView el={{ ...connector, kind: "straight", endArrow: "none" }} />
+    );
+    expect(html).toContain("<path");
+    expect(html).not.toContain("<marker");
+  });
+});

packages/slidewise/src/index.ts

@@ -94,6 +94,28 @@ export type { ParseDiagnostics, ParseResult } from "./lib/pptx/types";
 export { migrate, CURRENT_DECK_VERSION } from "./lib/schema/migrate";
 export { resolveJsonDeck } from "./lib/schema/json";
 
+/**
+ * Instantiate a fresh slide from one of the deck's master layouts
+ * (`Deck.layouts`, populated by `parsePptx`). The unlock for generating decks
+ * with more slides than the template hand-authored, using the template's own
+ * layout variety.
+ */
+export {
+  addSlideFromLayout,
+  type AddSlideFromLayoutOptions,
+} from "./lib/layouts";
+
+/**
+ * Chart-option helpers. Build the exact ECharts option Slidewise renders a
+ * `ChartElement` with — for host-side previews / server-side render-to-image —
+ * without re-implementing (and drifting from) the package's translation.
+ */
+export {
+  buildChartOption,
+  defaultPaletteColor,
+  makeValueFormatter,
+} from "./lib/chart/chartOption";
+
 export type {
   Deck,
   Slide,
@@ -115,8 +137,13 @@ export type {
   ChartKind,
   ChartGrouping,
   ChartSeries,
+  ConnectorElement,
+  ConnectorKind,
+  ArrowheadKind,
   GroupElement,
   UnknownElement,
+  DeckLayout,
+  LayoutPlaceholder,
   ElementDraft,
   ShadowSpec,
   GlowSpec,