pptd-utils 2026.10.2.dev3__tar.gz

pptd_utils-2026.10.2.dev3/.agents/reference/2026-09-19-implementation_plan.md

@@ -0,0 +1,140 @@
+# Implementation Plan — `/app` PPTD Viewer
+
+**Base:** mockup logic → Vite + React + TS. Deps: `js-yaml`, `echarts` (only). Every phase ends with the yu7 example deck rendering correctly.
+
+## Phase 1 — Skeleton + Loader + Shell
+**Deliverable:** upload folder → navigable deck.
+- `app/` Vite scaffold (`react-ts`), `/` = viewer
+- `src/load.ts` — port mockup loader: file map → `.pptd` parse → `pages[]` → blob URLs. Types for `Presentation/Page/ElementBase` in `src/types.ts`
+- `src/Viewer.tsx` — canvas, scale-to-fit, `fit()` on resize
+- `src/Shell.tsx` — toolbar (upload/drag-drop), thumb rail, ←/→, slide index
+- **Exit check:** yu7 deck: cover text + bg images render, all 8 thumbs, keyboard nav
+
+Implementation Handover Notes (Phase 1 — DONE):
+- Stack: Vite 8 + React 19 + TS, bun-installed. Deps: `js-yaml@5` ONLY (echarts deliberately not yet added — phase 5).
+- js-yaml v5 gotcha: **no default export in ESM build** — use `import { load as yamlLoad } from 'js-yaml'`. Cost ~20 min to find via a silent rolldown `MISSING_EXPORT`.
+- `app/src/types.ts` — minimal PPTD types (only what Phase 1 consumes). Extend per phase, don't spec-dump.
+- `app/src/load.ts` — `FileSource` abstraction (`read/url/list`) with 3 impls:
+  - `folderSource(File[])` — upload/drop; images become `URL.createObjectURL` blob URLs at source-construction time
+  - `httpSource(baseUrl)` — dev server; reads `manifest.json` (all relative paths) to find the root `.pptd`
+  - disk source only exists inside `app/test/smoke.test.ts` (not shipped)
+- Example decks over HTTP: `scripts/gen_example_manifest.py` emits `manifest.json` per example deck (run once; not part of npm test). Dev proxy: `/example/*` → `localhost:5174` = `python3 -m http.server 5174` rooted at `skills/cowork-ppt/example/` (see `app/vite.config.ts`). No 5174 server → "load example" fails; upload/drop still works.
+- `resolveSrc()` rewrites EVERY non-http `src` string recursively (backgrounds, image elements) — keyed relative to the `.pptd` dir. Page src refs are resolved at load; don't resolve again in renderers.
+- `stripRoot()` strips the picked-folder prefix from `webkitRelativePath`. Drop path uses `webkitGetAsEntry` recursion (readEntries ≤100/call, looped).
+- `Renderer.tsx` — Phase-1 element coverage: text (align/letterSpacing/lineHeight), shape rect+roundRect only (radius hardcoded 16 — replace in Phase 3 shapes), image (objectFit), chart = dashed placeholder. React style prop is a CSSProperties OBJECT — not a CSS string (tsc caught this).
+- z-order = JSX map order over `page.elements` (later = higher). Do NOT add z-index.
+- Tests: `cd app && bun test` — 5 tests, incl. real-deck load from disk + missing-page error path. `bunx tsc -b` clean; `vite build` passes (~85KB gzip).
+- Dev runbook: `cd app && bun run dev` (5173) + `python3 -m http.server 5174 -d skills/cowork-ppt/example`.
+- Known gaps → next phases: theme `$refs` unhandled (Phase 2 must resolve; yu7 uses them heavily), RichText escaped-only, line/icon/table unrendered (Phase 3/4), animations none (Phase 6).
+
+## Phase 2 — Primitives
+**Deliverable:** style engine, shared by all elements.
+- `src/theme.ts` — `$ref` resolution (colors/textStyles/tableStyles), priority chains, defaults table (spec §1)
+- `src/render/Fill.tsx` — solid / linear+radial gradient / image fill (background + element fills)
+- `src/render/Border.tsx` + `Shadow.tsx` — box-shadow mapping, per-side borders (BorderSpec in Phase 4)
+- `src/render/RichText.tsx` — `<p>/<span>/<strong>/<em>/<u>/<s>/<sup>/<sub>`, inline style attrs, `\n` paragraphs
+- **Exit check:** gradient overlay + `$coverTitle` + letterSpacing render pixel-close vs soffice PNG
+
+Implementation Handover Notes (Phase 2 — DONE):
+- New files: `src/theme.ts` (theme ctx + resolution), `src/render/Fill.tsx` (fill/border/shadow → CSS), `src/render/RichText.tsx` (parser + component). Renderer.tsx rewritten to consume them; Shell injects `customFonts` via `<link data-pptd-font>`.
+- Theme: `ThemeContext` carries `{colors, textStyles, tableStyles}`; `useTheme()` in each element component. `resolveColor('$x')` → hex, unknown ref → `#FF00FF` (visible miss). Priority chain (spec §1.1) implemented in `resolveTextStyle`: content fields > theme textStyle > defaults; spans/tags layer on top inside RichText.
+- **Gradient angle mapping: CSS deg = spec angle + 90** (spec 0 = left→right = CSS 90deg). Phase 1 had `90-angle` — wrong; test now pins both 0 and 90.
+- RichText parser: single-pass stack walker (`parseInline`), top-level `<p>` split with attr extraction, plain-text `\n` → paragraphs (spec shorthand). Segment CSS precedence: `tagCss` (semantic tags) > `spanCss` (inline decls); container carries base. Supported decls: color/background-color/font-size/font-family/font-weight (spans); text-align/line-height/margin-* (paragraphs). `<a>` → blue underline. LaTeX `\(...\)` NOT handled (no deck uses it; add KaTeX when needed).
+- Fast-refresh/oxlint: hooks can't live in lowercase helpers — element renderers are components (`TextBlock`, `ShapeBox`, `ImageBox`).
+- textStyle vertical align via flex column + justifyContent (top/middle/bottom). `distributed` → CSS `justify`.
+- MiSans not bundled: decks render in system fallback unless `customFonts` provides a Google-Fonts CSS. Bundling MiSans = later decision, needs font files.
+- Tests: 18 total (13 primitives incl. yu7's real stat-line markup, 5 loader). tsc + oxlint clean, build 86KB gzip.
+- Still rough (by design): shapes are boxes (radius 16 non-rect) until Phase 3 SVG; ImageFill.opacity only honored on page background, not shape fills; Border per-side arrays = Phase 4 tables.
+
+## Phase 3 — Elements (text/shape/line/image/icon)
+- `src/render/elements/Text.tsx` — align [h,v], lineHeightPx, auto overflow
+- `Shape.tsx` — top-30 `shapeName`s as SVG path defs + `adjustments`, custom `viewBox`+`path`, hollow winding rule, rotation/flip/opacity
+- `Line.tsx` — bezier SVG, `curve` modes, 4 arrow types
+- `Image.tsx` — crop→fit→cropShape pipeline
+- `Icon.tsx` — Font Awesome 7 free webfont (bundled CSS, `fas:/far:/fab:`)
+- **Exit check:** yu7 slides 1–5 visually match soffice exports
+
+Implementation Handover Notes (Phase 3 — DONE):
+- **Built:** `elements/{geometry.ts, Shape.tsx, Line.tsx, Image.tsx, Icon.tsx, Text.tsx, fx.ts}`; Renderer.tsx is now a thin dispatcher. `?deck=<name>` query param on `/` loads any example deck (QA harness uses this in phase 7).
+- **Geometry** (`geometry.ts`): `shapeGeom(shapeName, w, h, adjustments)` → SVG path d in bounds coords; 20 presets (common-shapes table + trivial polygons); unknown → rect + console.warn. Adjustments are OOXML [0,100000] fractions with spec defaults — PowerPoint formulas approximated for non-example shapes (donut ring = min×adj, roundRect radius = min×adj clamped ½, star inner = 2×adj ratio). `resolveShapeDef` handles `custom` (user viewBox + path, evenodd for hollow).
+- **SVG gotchas hit:** (1) CSS `background` doesn't paint SVG paths — fills must be `fill` attr; gradients need `<linearGradient/radialGradient>` defs (id = `fill-${elementId}`), CSS angle → bbox vectors via (sinθ, −cosθ), θ = spec+90. (2) Custom-shape path lives in the USER viewBox — svg viewBox must switch to `el.viewBox` when shapeName=custom (was bounds → giant blob). (3) Element wrapper divs need position/size from bounds — Phase-3 first cut had bare divs (size 0×0, svg collapsed).
+- **Lines:** `linePath(points, curve)` — 2 pts straight; sharp/round = polyline; smooth = Catmull-Rom→cubic (tension 1/6, endpoints duplicated). `vector-effect="non-scaling-stroke"` keeps 840×1 viewBox lines from smearing stroke. Arrows = SVG markers, 5×strokeWidth viewport with viewBox 0 0 10 10 content (10× was PowerPoint-huge); auto-start-reverse orients start arrows; dash/dot via strokeDasharray (dot needs linecap round).
+- **Image crop pipeline:** `cropFrame(crop)` → padded-frame % math (width = 1/cw etc.), object-fit on the padded frame gives cover/contain/fill of the sub-rect for free; negative insets pad transparent via offsets. cropShape → CSS `clip-path: path('…')`.
+- **Icon:** FA via jsDelivr CDN `<link data-pptd-fa>` injected on first icon (fas→fa-solid etc.). ponytail: swap to bundled @fortawesome/fontawesome-free if offline rendering matters.
+- **fx.ts:** rotation (CSS deg, clockwise ✓)/flip/opacity wrapper transform for shape/line/image/icon (spec: Text has none). fx on wrapper means rotation applies to border+shadow+clip together — correct.
+- **theme fix:** `resolveTextStyle` now returns `lineHeight` (multiple, default 1) AND `lineHeightPx` separately — Phase 2 mixed them (lineHeightPx=20 would render as 20× multiplier). textStyleProps emits `"33px"` when px set.
+- **Torture deck:** `skills/cowork-ppt/example/torture/` — 3 pages exercising every Phase-3 feature (shapes incl. custom hollow ring, all 4 arrow types + curve modes, crop/cropShape/fit/rotation on images, FA icons). Loaded via `/?deck=torture`. Keep as regression fixture. NOTE: spec's custom-path example uses degenerate single-arc circles (`A r,r 0 1 1 x±ε`) — Chromium picks the wrong center for the inner contour; write circles as two half-arcs.
+- Tests: 32 total (14 element/geometry, 13 primitives, 5 loader). tsc + oxlint clean; build 286KB (88.9 gzip).
+- **Exit check:** verified by screenshots — yu7 8 slides, animation deck 8, dji 18 (incl. wrap:false single-lines), torture 3. soffice pixel-diff = phase 7 harness.
+- Known gaps (deliberate): pie/arc/chord/bracePair geometry; image-fill on shapes (SVG pattern); hollow cropShapes (CSS path() has no fill-rule); gradient/image fills on icons. Add when a deck needs them.
+
+## Phase 4 — Table
+- `Table.tsx` — CSS grid, `rowSpan/colSpan` with omitted-cell rule, `columnWidths/rowHeights` ratios, cell fills/borders, `firstRow/lastRow/firstCol/lastCol` style overrides, `$tableStyles`
+- **Exit check:** spec's merged-cell example renders correct 3×3
+
+Implementation Handover Notes (Phase 4 — DONE):
+- **Built:** `render/elements/Table.tsx` (+ `CellStyle/TableStyleConfig/BorderSpec/Cell/TableElement` in types.ts; `Element` union extended). Absolute-positioned cells over ratio-computed col/row offsets — no CSS grid (grid+rowSpan conflicts with explicit ratio sizing; absolute needs no gap-collapse logic).
+- **Pure logic exported for tests:** `buildGrid` (omitted-cell walk, dji `content:{text,align}` normalization), `resolveCellStyle`/`resolveCellBorders` (chain mirrors `scripts/pptd_utils/tables.py` exactly: cell > textStyle-theme > category(rowOverColumn) > bodyStyles(cycled by data-row idx) > cellStyle; table fill only under cell fill; per-side border chain with explicit-null clears, UNSET sentinel distinguishes absent from null). 7 new tests; 39 total.
+- **Defaults:** fontSize 14, align center/middle, all four borders solid 1px black — matches converter CELL_DEFAULTS.
+- **Cell text = RichText** (rich tags work in cells); container flex column + justifyContent = align[1]; textAlign = align[0].
+- **Legacy quirks supported (ponytail: drop when dji deck regenerates on spec v2):** (1) `content:{text,align}` cell wrapper; (2) table style convenience keys `fontSize/bodyColor/headerBold/firstColumnColor/border` — mapped to cellStyle + firstRow(firstColumn) categories; headerBold only touches row 0, firstColumnColor only col 0; (3) 3-element BorderSpec `[t, lr, b]` (spec only defines 2/4 forms).
+- **Null-border semantics:** `null` side = no border (component skips); only fully-unspecified side defaults to solid 1px black.
+- **Torture page 4:** spec's `table-merged` example verbatim (2×2 merge, omitted cells) + a styled table (firstRow fill/bold/align, bodyStyles band, per-cell align override). Exit check verified in browser — merged region spans cols 0–1 rows 0–1, no phantom cells.
+- Verified: dji-pocket4 page 17 (real legacy table), all 4 decks zero page errors. tsc/oxlint clean, build 89.2 gzip.
+- Known gaps (deliberate): image fills in cells (needs object-fit layer); table shadow applies to wrapper only.
+
+## Phase 5 — Charts (biggest phase)
+- `src/render/elements/Chart.tsx` — ECharts wrapper, resize-aware
+- `src/render/charts/` — mappers: `bar line area scatter bubble candlestick pie radar waterfall heatmap treemap sunburst sankey`
+  - cartesian shared: `AxisConfig` (label/axisLine/gridLine `boolean|Config`), barWidth/barGap/categoryGap
+  - non-cartesian: radar→`SpokeAxisConfig`, heatmap→visualMap=`colorbar`, waterfall→stacked-transparent trick
+- `seriesDefaults` merge, per-series `dataLabel/marker/legend/title` styles
+- **Exit check:** one synthetic page per chart type renders w/ correct data, colors, labels
+
+Implementation Handover Notes (Phase 5 — DONE):
+- **Deps:** `echarts@6.1.0` installed (bun). Bundle: 999KB / 327KB gzip — tree-shaken via `echarts/core` + per-chart `echarts/charts` + `echarts/components`; chart modules registered once in `ensureRegistered()` (`echarts/core` `use` aliased to `registerEcharts` for lint compliance).
+- **Built:** `src/render/charts/map.ts` (pure `chartOption(el, theme)` PPTD→ECharts mapper, all 13 types) + `src/render/elements/Chart.tsx` (init/setOption(notMerge)/dispose, fixed bounds, frame fill/border/shadow). Renderer dispatches `'chart'` → `ChartBox`; placeholder removed. `ChartElement` chart frame/style fields added to `src/types.ts`.
+- **Mapper:** bar/line/area (area→line+areaStyle, stream stack), scatter, bubble→ECharts `scatter` (v6 has no `BubbleChart`; triples + sqrt/linear/log `symbolSize` + `sizeRange`), candlestick + MA overlay, waterfall transparent-base stack + cumulative totals, pie donut/start-angle mapping, radar indicators/spoke axis, heatmap + continuous visualMap, treemap/sunburst parent hierarchy, sankey node dedupe. Axis configs, secondary axes, label/legend/title priority, `seriesDefaults` one-level merge, theme `$ref` colors, gradients, supported number formats implemented.
+- **Regression fixes:** radar indicator metadata removed from series before `setOption`; `fmtNum` scientific precision corrected; scatter/bubble numeric axes inferred as `value`; theme lookup accepts both `$primary` and `primary` keys; no stale vite deps after cache clear.
+- **Fixture:** torture pages 05–08 cover all 13 chart types and key options; manifest regenerated. Playwright screenshots `/tmp/p5_pg4.png`–`/tmp/p5_pg7.png`: all chart pages render without runtime errors. Notable visual result: valid theme colors, bubble sizing, radar/heatmap/hierarchy/sankey, mixed secondary axis.
+- **Tests:** `app/test/charts.test.ts` added: `fmtNum`, defaults merge, bubble scaling/type, pie angle/radius, waterfall anchors, radar indicator. `45 pass / 0 fail / 116 expect() calls`; `tsc -b --force` clean; Vite build clean; oxlint only pre-existing warnings plus test import false positives, Chart hook lint fixed.
+- **Known simplifications:** bar pictographic `symbol` ignored; `stack: stream` uses value-stack approximation; HLC candlestick (missing open) approximated by converter-side data assumptions; diverging colorScale linearly interpolated through 3 colors; geometry/gradient edge cases remain ponytailed in prior notes.
+
+## Phase 6 — Animations
+- `src/anim.ts` — entrance/exit/emphasis effects → CSS keyframes/WAAPI
+- click-group state machine: `onClick/withPrevious/afterPrevious`, replay on slide enter
+- motion-path: SVG path → `offset-path`
+- **Exit check:** `xiaomi-yu7-ppt-animation` example plays groups in order
+
+Implementation Handover Notes (Phase 6 — DONE):
+- **Built:** `app/src/anim.ts` — animation model, default durations, trigger grouping, CSS animation styles, exit/entrance classification, motion-path support.
+- **Effects:** appear/fade/fly/zoom/wipe/float/peek/rise entrance+exit variants; pulse, grow-shrink, spin, teeter, fill-color, transparency, color-pulse, motion-path.
+- **Trigger state machine:** `onClick` starts a new group; `withPrevious` runs concurrently; `afterPrevious` runs sequentially. First group auto-plays when marked `withPrevious`/`afterPrevious`; page click advances one group at a time; page remount resets state.
+- **Renderer integration:** `PageView` computes visible elements and active animation steps; animation wrappers preserve element-local transforms; animations remain scoped per page.
+- **Motion paths:** CSS `offset-path: path(...)`; escaped quotes in path data. Fill/color effects use CSS custom properties.
+- **Tests:** `app/test/anim.test.ts` added. 47 tests pass; `tsc -b --force` and Vite build pass.
+- **Known simplifications:** transform-heavy effects use wrapper animation, so advanced simultaneous transform composition is not modeled; fill-color is CSS variable based and may not recolor complex SVG/image content; repeat semantics are numeric only. Upgrade during Phase 7 only if visual QA exposes a deck requirement.
+
+## Phase 7 — QA harness + polish
+- Dev-only route: side-by-side viewer vs `soffice` PNG (from existing `slides_image.py`), per-slide diff
+- Speaker notes panel, fullscreen/present mode, poster sizes, error toasts
+- README + npm scripts (`dev/build/test`)
+
+Implementation Handover Notes (Phase 7 — DONE):
+- **QA harness:** dev-only `?qa=<deck-folder>` route renders viewer vs soffice reference side by side (`.qa-split`), synced per slide (`←/→`/thumbs). References come from the existing converter CLI — `python3 -m pptd_utils png all <deck>.pptd` → `<stem>-png/slide_NN.png` inside the deck folder, served by the dev static server through the existing `/example` proxy. PNG dirs are gitignored. `LoadedProject.pptdPath` added so the viewer can derive the reference dir.
+- **Polish:** speaker-notes panel (toolbar toggle, plain-text `page.notes`), present mode (`f` key/toolbar: fullscreen + rail/bar hidden via `.presenting`), success/error status toasts (auto-dismiss vs persistent). Poster sizes need no code: scale-to-fit is aspect-agnostic (project.size honored verbatim).
+- **README:** rewritten (run, usage, animations, QA mode); `lint` npm script added.
+- **Fixture:** torture page 01 gained a `notes` field (smoke test for the panel).
+- **Regression caught by QA harness:** Phase 6 wrapper hid every non-animated element (`appear` treated as unstarted entrance). Fixed in `PageView`: only animated elements go through `animationStyle`; unanimated wrappers get no style. Also removed the `useEffect` state reset (React lint) in favor of keyed remount `useState` initializer.
+- **Verified in browser:** QA side-by-side loads + syncs reference images; notes panel renders; present hides chrome; `xiaomi-yu7-ppt-animation` sequences `afterPrevious` steps correctly (mid-flight opacity checks; pending steps hold opacity 0 via `animation-fill-mode: both`). 47 tests pass; `tsc -b --force` clean; Vite build clean; oxlint: only pre-existing Fast Refresh warnings (test duplicate-declaration errors fixed).
+
+---
+
+Progress Tracker
+- [x] Phase 1 — DONE (Vite+React scaffold, FileSource loader, upload/drop/example-deck, thumb rail, scale-to-fit canvas, 5 smoke tests green)
+- [x] Phase 2 — DONE (theme ctx + $ref resolution, Fill/Border/Shadow primitives, RichText parser+renderer, customFonts injection, 18 tests green, yu7 slides verified in browser)
+- [x] Phase 3 — DONE (Shape/Line/Image/Icon/Text element components, 20 shape presets + custom paths, arrows + curve lines, crop→fit→cropShape, FA icons via CDN, 32 tests, all example decks + torture deck verified in browser)
+- [x] Phase 4 — DONE (Table.tsx: omitted-cell grid walk, full style chain mirroring converter, per-side BorderSpec chain, dji legacy compat, 39 tests, spec merged-cell example + dji real table verified)
+- [x] Phase 5 — DONE (ECharts mapper/wrapper for all 13 chart types, synthetic torture pages 05–08, 45 tests green, browser screenshots verified)
+- [x] Phase 6 — DONE (CSS animation effects, trigger groups, page-entry replay, click advancement, motion-path, 47 tests)
+- [x] Phase 7 — DONE (dev QA side-by-side vs soffice reference, notes panel, present mode, toasts, README + lint script, wrapper-visibility regression fix)

pptd_utils-2026.10.2.dev3/.agents/reference/2026-09-22-canvas_editor_rewrite_plan.md

@@ -0,0 +1,122 @@
+# Canvas Editor Rewrite Plan
+
+**Goal:** in-app direct manipulation editing of a loaded PPTD deck (Figma-style), covering the full element surface of the PPTD v2 spec (text, shape, line, image, icon, table, chart) plus page-level ops. Spec: `skills/cowork-ppt/reference/pptd.md`.
+
+**What exists (keep):** immutable `patchProject` pipeline (Shell owns state), deck ctx (`tool/selectedId/editingId`), `DeckTool` palette, text in-place editing with spec-subset serializer, drag-move with live preview, selection/hover affordances in `PageView`, animation playback.
+
+**Rewrite drivers:**
+1. Editing logic is scattered across `PageView` (hover/drag/selection), `Stage` (gestures), `Canvas` (wiring) — adding resize/rotate/multi-select multiplies the tangle.
+2. Every edit feature re-plumbs props through `Renderer` → `DeckView` → `PageView`. One `EditorOverlay` component should own ALL pointer interaction; renderers stay dumb.
+3. Interaction math (screen↔canvas, scale, snap) needs one home.
+
+---
+
+## Architecture
+
+### Single interaction layer
+
+```
+DeckStage
+├─ DeckTool            (palette: V/T/R/… shortcuts)
+├─ DeckCanvas          (scaled #canvasWrap, renders DeckView + EditorOverlay)
+│   ├─ DeckView        (pure render: elements, animations, theme. NO pointer handlers beyond stopPropagation)
+│   ├─ EditorOverlay   (absolute inset-0, canvas-coordinate children; owns ALL editor pointer interaction)
+│   │   ├─ HoverBox / SelectionBox (outline, 8 resize handles, rotation handle)
+│   │   ├─ SnapGuides (smart guides while dragging/resizing)
+│   │   └─ TextEditor (existing contentEditable overlay, now a child of overlay)
+│   └─ (chart/table live edit popovers)
+└─ SlideList / StatusBar
+```
+
+- `DeckView` keeps only presentational props. Selection/hover/`onElementMove` props **deleted**; overlay handles hit-testing by computing element boxes itself (data already in ctx).
+- Overlay renders in the same scaled coordinate space as the canvas (`width/height` = page size, children positioned in canvas px; parent `#canvasWrap` already scales).
+
+### State
+
+```ts
+// ctx additions
+type Selection = { ids: string[] } | null        // multi-select foundation
+interface EditorState {
+  tool: Tool                                    // 'select' | 'text' | 'shape' | 'line' | 'pan'?
+  selection: string[]
+  editingId: string | null                       // in-place text edit
+  // history
+  undoStack: Patch[]                             // see Persistence
+  redoStack: Patch[]
+}
+```
+
+- One `EditorState` reducer in Root instead of scattered `useState`s. Commands dispatch intents (`SELECT`, `MOVE`, `RESIZE`, `PATCH_TEXT`, `ADD_ELEMENT`, `DELETE`, `REORDER`, `UNDO`…); reducers produce the immutable `patchProject` calls **and** history entries.
+
+### Persistence (new, do before properties panels)
+
+Currently edits are memory-only; refresh loses them.
+
+- `history.ts`: command pattern. Each command = `{ do: (p) => p, undo: (p) => p, label }`. Root keeps stacks; Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z.
+- Autosave: serialize project back to PPTD YAML (use existing types + `js-yaml` dump) → `File System Access API` (`showSaveFilePicker`) when available, else download as zip (folder structure: `.pptd` + `pages/*.page` + `media/`). `media/` for new uploads only; existing media URLs stay untouched.
+- Mark dirty state in Shell title/status bar.
+
+---
+
+## Phases
+
+### Phase E1 — Refactor onto EditorOverlay (pure move of existing behavior)
+- New `EditorOverlay` owns hover box, selection box, click-to-select, empty-click deselect, drag-move, double-click-to-edit dispatch. `PageView` loses all editor pointer props.
+- Selection state moves from `selectedId` to `selection: string[]`; every consumer updated.
+- Commands: `MOVE`, `SELECT`, `DESELECT`, `ADD_TEXT` via reducer + history stacks (undo wired from day one — every subsequent phase gets undo for free).
+- **Exit:** current behaviors identical; `bun test` + new reducer tests green; present mode & Pptd.tsx embed unaffected (overlay unmounted).
+
+### Phase E2 — Resize + rotate
+- 8 handles on SelectionBox (canvas-px aware, `dragScale` division stays). Corner = free resize with Shift = keep ratio; edges = single axis. Rotation handle above box (15° steps with Shift).
+- Bounds-only resize for `text/shape/image/icon/table/chart`; `line` scales `viewBox` proportionally (spec: keep `viewBoxW:H = bounds.w:h`).
+- Text resize does NOT auto-grow content (spec has no autofit); plain reflow.
+- Minimum sizes; drag from handle replaces selection-drag during resize.
+
+### Phase E3 — Element creation tools
+- Tool palette grows: rectangle/ellipse/roundRect/arrow/line (R, O, then a shape picker popover listing common `shapeName`s from shapes.md — start with ~12, full 177 later or searchable).
+- Drag on empty canvas → live preview box → pointer-up commits element (shape with default `fill` = theme primary; line with 2-point `viewBox`-normalized path).
+- Image tool: click → file picker (also paste + drag-drop onto canvas) → uploads into `media/` (blob URL → saved on export; filesystem writes when FSA available) → `Image` element with `fit: cover`.
+- Icon tool: search popover (iconify/FA7 free list) → places `Icon` element.
+- Double-click on empty canvas → create text at point (Figma behavior), in edit mode.
+
+### Phase E4 — Properties editing
+- Floating context panel (right side, or floating toolbar above selection — pick at implementation time based on space) shown when selection non-empty and not editing:
+  - text: fontSize, color, bold/italic/underline, align, lineHeight, fontFamily (fonts.md list), backgroundColor
+  - shape/line: fill (solid/gradient editor), border (style/width/color), shadow
+  - image: fit mode, crop, border, shadow, replace
+  - icon: iconName, fill
+  - chart/table: data editor (small grid editor; chart = series/data table editor per spec encode rules — biggest single item, can ship read-only first)
+  - common: opacity, rotation, layer order (front/back buttons), elementId display
+- Rich text: extend `textEdit.ts` serializer to full spec tag set already supported (`<ul>/<ol>/<li>` parsing, `<a href>`, list styles) + a mini inline format toolbar (B/I/U/S, color, font-size) driven by `document.execCommand` or manual `Selection` range surgery → serialize.
+- Page properties: background fill editor (solid/gradient/image), notes textarea (speaker notes), pageType label.
+
+### Phase E5 — Element/page management
+- Delete/Backspace = delete selection (when not editing text); Ctrl+D duplicate (offset +16,+16); layer reorder shortcuts (`]`/`[`).
+- Copy/paste (Ctrl+C/V) internal clipboard; paste external image from OS clipboard → new Image element.
+- Drag elements between pages via SlideList (drop on thumbnail).
+- Multi-select: Shift+click add/remove, marquee (drag on empty canvas with select tool = marquee, hold to distinguish from click), group move/resize (resize = shared delta only).
+
+### Phase E6 — Undo/history polish + snapping
+- Smart guides: while move/resize, align to other elements' edges/centers + page center; show magenta guides, snap within 6 canvas px.
+- Optional grid (10px) with toggle.
+- Arrow keys nudge 1px (Shift = 10px) when selection non-empty and not editing.
+- History UI: undo/redo buttons in toolbar with disabled states.
+
+---
+
+## Non-goals (explicit)
+
+- PPTX export/import — cowork-ppt CLI already does lossless conversion; the editor saves PPTD only.
+- Collaborative editing, comments, multiplayer.
+- Animation timeline editor (animations render/play; editing the `animations` array can come via a later YAML-ish side panel — not in these phases).
+- `distributed` align, LaTeX editing UI (renders fine; edit via text).
+
+## Testing strategy
+
+- Pure logic (reducer, command/undo, snapping math, serializer extensions, viewBox line math) → unit tests like existing `textEdit.test.ts`.
+- Interaction (pointer flows) → keep minimal; overlay hit-test box computation is pure → tested.
+- Every phase ends: `bun test`, `bunx tsc -b`, existing decks render unchanged in present + embed modes.
+
+## Order rationale
+
+Undo (E1) first so no phase ever ships destructive edits without escape. Resize before creation tools because resize is the highest-value single interaction after move. Creation before properties because empty-canvas → element flows unlock testing property panels on real elements. Chart/table data editors last (E4 tail) since they're the largest isolated chunk and can degrade to read-only.

pptd_utils-2026.10.2.dev3/.github/workflows/publish-pypi.yml

@@ -0,0 +1,66 @@
+name: Publish PyPI package
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PYTHONUNBUFFERED: "1"
+
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      tag: ${{ steps.release.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Set dated release version
+        id: release
+        run: python scripts/set_release_version.py
+      - run: python -m pip install --upgrade pip build
+      - run: python -m pip install .
+      - run: python -m build
+      - run: python -m pip install twine
+      - run: python -m twine check dist/*
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Set verified release version
+        env:
+          RELEASE_VERSION: ${{ needs.verify.outputs.version }}
+        run: python scripts/set_release_version.py
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*
+      - name: Tag published commit
+        env:
+          RELEASE_TAG: ${{ needs.verify.outputs.tag }}
+        run: |
+          git fetch origin --tags
+          if git show-ref --verify --quiet "refs/tags/$RELEASE_TAG"; then
+            test "$(git rev-list -n 1 "$RELEASE_TAG")" = "$GITHUB_SHA"
+          else
+            git tag "$RELEASE_TAG" "$GITHUB_SHA"
+            git push origin "refs/tags/$RELEASE_TAG"
+          fi

pptd_utils-2026.10.2.dev3/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+
+# macOS metadata
+.DS_Store
+
+# Packaged artifacts
+*.tgz
+*.zip
+
+# Local skill install metadata
+_user_meta.json
+
+# graft's local graph cache — regenerable, not committed (run `graft build`).
+/graft/
+
+# QA reference PNGs — regenerable via `python3 -m pptd_utils png all <deck>.pptd`
+skills/cowork-ppt/example/**/*-png/
+
+# Agent Harness Directory
+.pi

pptd_utils-2026.10.2.dev3/.ignore

@@ -0,0 +1,5 @@
+# graft's cards are gitignored but should stay greppable: ripgrep reads
+# .ignore before .gitignore, so this re-admits the tree to search only.
+!graft/
+graft/.cache/
+graft/.graph/

pptd_utils-2026.10.2.dev3/.npmignore

@@ -0,0 +1,15 @@
+# When .npmignore exists, npm ignores .gitignore for packing.
+# Keep packaging exclusions here even if they already appear in .gitignore.
+
+**/__pycache__/
+**/__pycache__/**
+*.py[cod]
+**/*.py[cod]
+*$py.class
+.pytest_cache/
+
+.DS_Store
+_user_meta.json
+
+*.tgz
+*.zip

pptd_utils-2026.10.2.dev3/AGENTS.md

@@ -0,0 +1,41 @@
+<!-- graft:start -->
+## Graft — repo context graph
+
+This repo is indexed in `graft/`: small linked markdown nodes that explain each
+system and carry exact file:line spans, kept in sync with the code through git.
+
+For ANY task here — understanding how something works, finding where code lives,
+or scoping a change — get context from the graph before grepping or opening
+source files. Re-ask freely (it's cheap) and reuse literal identifiers you
+already have (symbol, error string, file name) as the query. New to this repo?
+Run `graft map` first — a token-budgeted orientation (dir clusters, hubs,
+hotspots), no LLM, no key.
+
+- Run `graft ask "<your question>" --source` → ranked nodes with the relevant
+  code spans inlined (each hit's ≤8-line crux by default; `--full` for whole
+  definitions when the crux isn't enough). Match the tool to the task shape:
+  for understanding or editing, the top node IS the answer — cite its
+  `covers:` file:line spans and edit straight from `--source`. For
+  exhaustive tasks ("every occurrence / every caller of this pattern"), ranked
+  results are top-N, not complete — run `graft grep "<literal>"` instead
+  (exhaustive over indexed files, grouped by enclosing symbol), falling back
+  to raw `grep -rn` only for unindexed files.
+- `graft skeleton <file>` → every definition's signature + span, ~10× cheaper
+  than reading the file; use it to skim an API surface.
+- `graft callers <symbol>` gives precomputed, exact edges — who calls this.
+  Add `--direction out` for what it calls, or `--depth N` to walk
+  transitively for the full blast radius. For structural questions, skip
+  ranking and use this directly.
+- Or browse: `graft/INDEX.md` lists every node; follow the links.
+- Monorepos and folders of multiple repos rank fairly across sub-projects —
+  hits carry `[scope/]` labels naming which one they're from. Narrow with
+  `graft ask "<task>" --in <scope>/` once you know where you're working.
+
+If a returned span is truncated ("+N more lines"), open the file at that exact
+range before finalizing. Only open source files when a node genuinely lacks a
+needed detail, and then at the exact file:line the node points to — never
+re-read whole files.
+
+After big code changes, refresh the graph with `graft build` (deterministic,
+no API key, $0).
+<!-- graft:end -->

pptd_utils-2026.10.2.dev3/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: pptd-utils
+Version: 2026.10.2.dev3
+Summary: Offline PPTD v2 toolkit for converting editable presentations to PowerPoint
+Author: binaryify
+License: MIT
+Keywords: powerpoint,pptd,pptx,presentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Requires-Dist: lxml>=4.9
+Requires-Dist: pillow>=9
+Requires-Dist: python-pptx>=0.6.21
+Requires-Dist: pyyaml>=6
+Provides-Extra: fonts
+Requires-Dist: brotli>=1; extra == 'fonts'
+Requires-Dist: fonttools>=4; extra == 'fonts'
+Provides-Extra: math
+Requires-Dist: latex2mathml>=3; extra == 'math'
+Requires-Dist: mathml2omml>=0.0.2; extra == 'math'
+Description-Content-Type: text/markdown
+
+# pptd_utils
+
+Offline PPTD toolkit — full-spec `.pptd` → `.pptx` converter + slide image export (collage / single slide). Pure Python, no browser required.
+
+Built against the PPTD v2 spec (`skills/cowork-ppt/reference/pptd.md`, relative to the repo root).
+
+## Install / dependencies
+
+```
+pip install python-pptx Pillow PyYAML
+```
+
+Optional (graceful fallback if missing):
+
+| Package | Unlocks | Fallback |
+|---|---|---|
+| `latex2mathml` + `mathml2omml` | native equations (OMML) from `\( ... \)` | literal text |
+| `fontTools` | customFonts (Google Fonts woff2 → embedded TTF) | fonts skipped |
+
+Slide images additionally need **LibreOffice** (`soffice` on PATH).
+
+## CLI
+
+Install from PyPI:
+
+```bash
+python -m pip install pptd-utils
+```
+
+Commands write beside the input path. `all` is the default; selections accept comma-separated 1-based slide numbers.
+
+```bash
+pptd check deck.pptd
+pptd pptx deck.pptd
+pptd png deck.pptd                 # all slides -> deck-png/
+pptd png 1,2,3 deck.pptd           # selected slides -> deck-png/
+pptd png collage deck.pptd         # contact sheet -> deck-collage.png
+pptd pdf deck.pptd                 # all slides -> deck.pdf
+pptd pdf 1,2,3 deck.pptd            # selected slides -> deck.pdf
+```
+
+PNG and PDF export require LibreOffice (`soffice` on `PATH`).
+
+## Python API
+
+```python
+from pptd_utils import convert, build, verify
+from pptd_utils import slides_image
+
+convert("deck.pptd", "out.pptx")          # build + verify + print summary
+build("deck.pptd", "out.pptx")            # -> (n_slides, n_fonts)
+verify("deck.pptd", "out.pptx")           # structural self-check (asserts)
+
+slides_image.render_collage("deck.pptd", "collage.png",
+                            tile_w=480, gap=20, bg="#1F2430")
+slides_image.render_slide("deck.pptd", 3, "slide3.png")
+slides_image.render_slide_images("deck.pptd", "outdir/",
+                                 slides=[1, 3, 5])   # -> [(n, Path), ...]
+```
+
+## Supported features (PPTD v2)
+
+| Area | Coverage |
+|---|---|
+| text | full HTML tag set (strong/em/u/s/sup/sub/a/br/ul/ol/span style attrs), LaTeX runs, gradient + shadow text, letterSpacing, lineHeight / lineHeightPx, bullets/numbering, vertical text, hyperlinks, highlight |
+| shapes | all 130 preset shapeNames (adjustments), custom SVG paths (`M/L/H/V/C/S/Q/A/Z`, multi-subpath holes), rotation/flip/opacity, gradient/radial fills |
+| lines | sharp / smooth / round (fillet) curves, arrows (head/tail), dash styles |
+| images | fit cover/contain/fill, crop (inset + negative outset padding), cropShape (any preset or custom path), opacity, border, shadow |
+| icons | Font Awesome 6/7 free (fas/far/fab), solid + gradient fill, outline, shadow |
+| tables | rowSpan/colSpan merges, theme tableStyles + inline, per-cell style chains, BorderSpec (per-side / null-clear), gradient cell fills, fontSize auto-fit |
+| charts — native (editable) | bar (stacked/clustered/horizontal), line (smooth/dash/markers), area, scatter, bubble, pie/donut, radar, secondary axes, dataLabels + numberFormat, embedded workbooks |
+| charts — raster (Pillow PNG) | candlestick, waterfall, heatmap (linear/diverging + colorbar), treemap, sunburst, sankey, stream stacks, mixed scatter+cartesian |
+| animations | 21 effects (entrance/emphasis/exit incl. motion-path) → full `p:timing` tree, click/withPrevious/afterPrevious, repeat, easing |
+| transitions | fade |
+| fonts | customFonts embedding (see optional deps) |
+| misc | page backgrounds (solid/gradient/image), notes, themes ($refs), elementId → animation targeting |
+
+## How it works
+
+- `pptx` generation: python-pptx + hand-built DrawingML for fills/effects/ordering; charts created via real chart parts (editable in PowerPoint) then plot XML rewritten; unsupported chart types rasterized at 2× and placed as pictures.
+- images: each slide isolated into a one-slide pptx, rendered by LibreOffice headless, composed by Pillow.
+  (`ponytail:` one soffice run per slide — switch to single PDF + PyMuPDF for large decks.)
+
+## Test
+
+```bash
+python3 tests/run.py   # converts full-spec fixture + minimal + ml-smp, asserts structure
+```
+
+Fixture `tests/fixtures/full/` exercises every feature area — use it as a syntax reference for your own decks.
+
+## Notes
+
+- Downloads (FA fonts, URL images/fonts) cache under `~/.cache/pptd_utils/`.
+- Defaults follow the spec: MiSans font family, 18pt body, black text.

pptd_utils-2026.10.2.dev3/README.md

@@ -0,0 +1,76 @@
+# pptd
+
+Unofficial PPTD v2 toolkit for creating, editing, and exporting editable PowerPoint presentations. This is enhancement from [Open Kimi PPT Skills](https://github.com/acnlie/open-kimi-ppt-skill) with its reverse engineering, spec to presentation CLI.
+
+## Install the CLI
+
+```bash
+python -m pip install pptd-utils
+```
+
+The `pptd` and `pptd-utils` commands convert PPTD v2 projects offline. Slide image export additionally needs LibreOffice (`soffice`) on `PATH`.
+
+## CLI
+
+```bash
+pptd check deck/deck.pptd
+pptd pptx deck/deck.pptd
+pptd png deck/deck.pptd
+pptd png 1,2,3 deck/deck.pptd
+pptd png collage deck/deck.pptd
+pptd pdf deck/deck.pptd
+pptd pdf 1,2,3 deck/deck.pptd
+```
+
+`all` is the default. PNG/PDF export requires LibreOffice (`soffice`).
+
+The converter verifies slide count, fade transitions, supported content, and ZIP integrity.
+
+## Supported PPTD features
+
+- Editable text, shapes, images, icons, tables, and charts
+- Linear and radial gradients
+- Fill, shape, image, icon, and per-gradient-stop opacity
+- Borders, shadows, arrows, and dash styles
+- Native PowerPoint connectors for ordinary two-point lines
+- Custom SVG-path shapes
+- Embedded custom fonts
+- Fade slide transitions
+- Optional on-slide animations
+- PPTD-to-PPTX conversion without a browser
+
+PPTD reference:
+
+```text
+skills/cowork-ppt/reference/pptd.md
+```
+
+Toolkit documentation:
+
+```text
+pptd_utils/README.md
+```
+
+## Local development
+
+```bash
+npm install
+npm test
+npm run sync:pptd
+npm run pack:check
+```
+
+`pptd_utils/` is the source copy. `skills/cowork-ppt/scripts/pptd_utils/` is the synchronized packaged copy.
+
+## Project layout
+
+```text
+project/
+  deck.pptd
+  pages/
+  media/
+```
+
+## Scope
+
+This project is not an official cowork, Kimi, or Moonshot AI SDK. PowerPoint, WPS, and Keynote may render unsupported or advanced OOXML features differently.