@textcortex/slidewise 1.0.0

package/src/lib/pptx/types.ts

@@ -0,0 +1,17 @@
+import type { SlideElement } from "@/lib/types";
+
+/**
+ * Result of parsing a PPTX archive. Surfaced to the caller so they can
+ * decide whether to warn about lossy fields (animations, transitions,
+ * unknown elements that fell into UnknownElement).
+ */
+export interface ParseDiagnostics {
+  unknownElementCount: number;
+  droppedAnimations: number;
+  warnings: string[];
+}
+
+export interface ParseResult {
+  diagnostics: ParseDiagnostics;
+  elements: SlideElement[];
+}

package/src/lib/pptx/units.ts

@@ -0,0 +1,32 @@
+/**
+ * Unit conversions between Slidewise pixels and PPTX EMU/inches/points.
+ *
+ * Slidewise authors at a fixed 1920×1080 px canvas. PPTX widescreen layout is
+ * 13.333 × 7.5 inches (12,192,000 × 6,858,000 EMU). The mapping is linear:
+ *   1920 px ↔ 12,192,000 EMU ↔ 13.333 in
+ *   1080 px ↔  6,858,000 EMU ↔  7.5 in
+ *
+ * That gives 6350 EMU per pixel (and 144 px per inch, 0.5 pt per px).
+ */
+
+import { SLIDE_W, SLIDE_H } from "@/lib/types";
+
+export const EMU_PER_INCH = 914400;
+export const EMU_PER_POINT = 12700;
+export const PX_PER_INCH = 144;
+export const EMU_PER_PX = EMU_PER_INCH / PX_PER_INCH; // 6350
+export const POINTS_PER_PX = 0.5;
+
+export const PPTX_SLIDE_W_INCHES = SLIDE_W / PX_PER_INCH; // 13.333…
+export const PPTX_SLIDE_H_INCHES = SLIDE_H / PX_PER_INCH; // 7.5
+export const PPTX_SLIDE_W_EMU = SLIDE_W * EMU_PER_PX; // 12,192,000
+export const PPTX_SLIDE_H_EMU = SLIDE_H * EMU_PER_PX; //  6,858,000
+
+export const pxToEmu = (px: number): number => Math.round(px * EMU_PER_PX);
+export const emuToPx = (emu: number): number => emu / EMU_PER_PX;
+
+export const pxToInches = (px: number): number => px / PX_PER_INCH;
+export const inchesToPx = (inches: number): number => inches * PX_PER_INCH;
+
+export const pxToPoints = (px: number): number => px * POINTS_PER_PX;
+export const pointsToPx = (pt: number): number => pt / POINTS_PER_PX;

package/src/lib/schema/__tests__/migrate.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+import { migrate, CURRENT_DECK_VERSION } from "../migrate";
+
+describe("schema/migrate", () => {
+  it("stamps the current version on an unversioned (v0) deck", () => {
+    const v0 = {
+      title: "Pre-versioning deck",
+      slides: [{ id: "s1", background: "#FFFFFF", elements: [] }],
+    };
+    const out = migrate(v0);
+    expect(out.version).toBe(CURRENT_DECK_VERSION);
+    expect(out.title).toBe("Pre-versioning deck");
+    expect(out.slides).toHaveLength(1);
+  });
+
+  it("passes a current-version deck through unchanged in shape", () => {
+    const current = {
+      version: CURRENT_DECK_VERSION,
+      title: "Current",
+      slides: [{ id: "s1", background: "#FFFFFF", elements: [] }],
+    };
+    const out = migrate(current);
+    expect(out.version).toBe(CURRENT_DECK_VERSION);
+    expect(out.title).toBe("Current");
+    expect(out.slides[0].id).toBe("s1");
+  });
+
+  it("throws on a deck written by a newer Slidewise", () => {
+    const future = {
+      version: CURRENT_DECK_VERSION + 5,
+      title: "From the future",
+      slides: [],
+    };
+    expect(() => migrate(future)).toThrow(/newer than this build/);
+  });
+
+  it("rejects non-object input", () => {
+    expect(() => migrate(null)).toThrow();
+    expect(() => migrate("not a deck")).toThrow();
+    expect(() => migrate(42)).toThrow();
+  });
+
+  it("rejects a deck whose slides is not an array", () => {
+    expect(() => migrate({ title: "x", slides: "nope" })).toThrow(
+      /slides is not an array/
+    );
+  });
+
+  it("rejects a deck with an invalid version field", () => {
+    expect(() =>
+      migrate({ version: -1, title: "x", slides: [] })
+    ).toThrow(/non-negative integer/);
+    expect(() =>
+      migrate({ version: 1.5, title: "x", slides: [] })
+    ).toThrow(/non-negative integer/);
+    expect(() =>
+      migrate({ version: "1", title: "x", slides: [] })
+    ).toThrow(/non-negative integer/);
+  });
+
+  it("does not mutate the input deck", () => {
+    const v0 = {
+      title: "Original",
+      slides: [{ id: "s1", background: "#FFFFFF", elements: [] }],
+    };
+    const before = JSON.stringify(v0);
+    migrate(v0);
+    expect(JSON.stringify(v0)).toBe(before);
+  });
+});

package/src/lib/schema/migrate.ts

@@ -0,0 +1,102 @@
+import type { Deck } from "@/lib/types";
+
+/**
+ * Slidewise deck schema version. Bump this whenever the persisted shape of a
+ * Deck changes in a way old hosts cannot read transparently — adding a new
+ * required field, renaming a key, restructuring an element type, etc.
+ *
+ * Bumping always pairs with a migrator at `MIGRATIONS[oldVersion]` that takes
+ * a deck shaped at the previous version and returns one shaped at this one.
+ * Migrations are run forward in order, so a v0 deck becomes v1 then v2 etc.
+ *
+ * Never delete an old migrator — published decks in the wild may still be at
+ * any historical version, and they all need a path forward.
+ */
+export const CURRENT_DECK_VERSION = 1;
+
+/**
+ * One forward migration. Receives a deck shaped at version `from` and returns
+ * a deck shaped at version `from + 1`. Inputs are typed as `any` because the
+ * old shape is not the current `Deck` type — that is the whole point of the
+ * migration.
+ */
+type Migrator = (deck: any) => any;
+
+/**
+ * Map of migrations keyed by the version they migrate _from_. To migrate a
+ * v3 deck to current, we run MIGRATIONS[3] then MIGRATIONS[4] etc. until we
+ * reach CURRENT_DECK_VERSION.
+ */
+const MIGRATIONS: Record<number, Migrator> = {
+  // v0 → v1: pre-versioning decks (no `version` field). Same structural
+  // shape as v1, so the migrator is identity — the version stamp happens
+  // at the end of `migrate()`.
+  0: (deck) => deck,
+  // Future entries look like:
+  //   1: (deck) => ({ ...deck, slides: deck.slides.map(addNewField) }),
+};
+
+/**
+ * Normalise an external deck (from PPTX import, JSON import, localStorage,
+ * a host prop, etc.) to the current schema. Stamps the current version on
+ * its way out so downstream code can rely on `deck.version`.
+ *
+ * Throws if the input is missing the basic shape, or if its `version` is
+ * higher than `CURRENT_DECK_VERSION` — that means the deck was written by
+ * a newer Slidewise and the host should upgrade rather than silently render
+ * a degraded version.
+ */
+export function migrate(input: unknown): Deck {
+  if (!isObject(input)) {
+    throw new Error("[slidewise] migrate: input is not an object");
+  }
+  if (!Array.isArray((input as { slides?: unknown }).slides)) {
+    throw new Error("[slidewise] migrate: deck.slides is not an array");
+  }
+
+  // Decks written before versioning existed have no `version` field; treat
+  // them as v0. Anything else must be a finite non-negative integer.
+  const rawVersion = (input as { version?: unknown }).version;
+  let version: number;
+  if (rawVersion === undefined) {
+    version = 0;
+  } else if (
+    typeof rawVersion === "number" &&
+    Number.isInteger(rawVersion) &&
+    rawVersion >= 0
+  ) {
+    version = rawVersion;
+  } else {
+    throw new Error(
+      `[slidewise] migrate: deck.version is not a non-negative integer (got ${String(
+        rawVersion
+      )})`
+    );
+  }
+
+  if (version > CURRENT_DECK_VERSION) {
+    throw new Error(
+      `[slidewise] migrate: deck version ${version} is newer than this build supports (max ${CURRENT_DECK_VERSION}). Upgrade Slidewise.`
+    );
+  }
+
+  let working: any = input;
+  while (version < CURRENT_DECK_VERSION) {
+    const step = MIGRATIONS[version];
+    if (!step) {
+      throw new Error(
+        `[slidewise] migrate: no migrator registered for version ${version} → ${
+          version + 1
+        }`
+      );
+    }
+    working = step(working);
+    version += 1;
+  }
+
+  return { ...working, version: CURRENT_DECK_VERSION } as Deck;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}