feat: unified shell, diagnostics pack, native Office, sticky board

Make Surface remote debugging and classroom workflows viable: always-on
structured logs with one-click zip export, a single AppShell chrome,
OOXML PPTX/DOCX annotation without LibreOffice, and a first-class sticky
board. Also drop spike/legacy ink widgets and tighten pen feel
(predictor, PenInfoHistory, page-tile layer).

Co-authored-by: Cursor <cursoragent@cursor.com>

lib/services/pptx_service.dart

@@ -5,24 +5,83 @@ import 'package:path/path.dart' as p;
 import 'package:path_provider/path_provider.dart';
 import 'package:uuid/uuid.dart';
 
-/// Service for processing PPTX files: text extraction, image conversion, file picking.
+import 'office/office_document.dart';
+import 'office/pptx_parser.dart';
+
+/// Service for processing PPTX files: text extraction, structured slide parse,
+/// optional LibreOffice image conversion, and file picking.
 ///
-/// PPTX files are ZIP archives containing XML. We extract text from
-/// `ppt/slides/slide*.xml` `<a:t>` elements and convert slides to images
-/// using LibreOffice (headless) or generate placeholder images as fallback.
+/// **Native OOXML parsing is primary** ([PptxParser] via `package:archive` +
+/// `package:xml`). LibreOffice (`soffice`) is an optional fallback ONLY when
+/// the native path fails AND the binary is present on the machine.
 class PptxService {
   static const _uuid = Uuid();
 
+  final PptxParser _parser;
+
+  PptxService({PptxParser? parser}) : _parser = parser ?? PptxParser();
+
   /// Extract all text content from a PPTX file.
   ///
-  /// PPTX is a ZIP archive. Slide text lives in `ppt/slides/slide*.xml`
-  /// inside `<a:t>` (ASCII text) elements within `<a:r>` (run) or
-  /// `<a:p>` (paragraph) nodes.
+  /// Prefers the native [PptxParser]. Falls back to a legacy unzip+regex path
+  /// only if native parsing throws.
   Future<String> extractText(String pptxPath) async {
+    try {
+      final parsed = await _parser.parse(pptxPath);
+      return parsed.plainText;
+    } catch (_) {
+      return _extractTextLegacy(pptxPath);
+    }
+  }
+
+  /// Parse PPTX into structured slides (text runs with approximate positions,
+  /// embedded images extracted to a cache dir). Native-only — no LibreOffice.
+  Future<ParsedPptx> parseSlides(String pptxPath, {String? cacheDir}) {
+    return _parser.parse(pptxPath, cacheDirPath: cacheDir);
+  }
+
+  /// Convert PPTX slides to a list of image file paths (legacy PenSlideScreen).
+  ///
+  /// Prefer [parseSlides] for native text+image rendering. This method only
+  /// invokes LibreOffice when native parse fails AND `soffice` exists;
+  /// otherwise it emits placeholder PNGs from the native slide count.
+  Future<List<String>> convertToImages(String pptxPath) async {
+    try {
+      final parsed = await _parser.parse(pptxPath);
+      // Native succeeded — do NOT call LibreOffice; placeholders for callers
+      // that still expect image paths. OfficeDocumentScreen uses [parseSlides].
+      if (parsed.slides.isEmpty) return [];
+      return _generatePlaceholderImages(pptxPath);
+    } catch (_) {
+      // Native failed — LibreOffice fallback ONLY if soffice exists.
+      final soffice = await resolveSoffice();
+      if (soffice != null) {
+        final loImages = await _convertViaLibreOffice(pptxPath);
+        if (loImages.isNotEmpty) return loImages;
+      }
+      return _generatePlaceholderImages(pptxPath);
+    }
+  }
+
+  /// Open a file picker dialog and return the selected PPTX path, or null.
+  Future<String?> openPptxFile() async {
+    final result = await FilePicker.platform.pickFiles(
+      type: FileType.custom,
+      allowedExtensions: ['pptx', 'ppt'],
+    );
+    final files = result?.files;
+    if (files == null || files.isEmpty) return null;
+    return files.first.path;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Legacy / LibreOffice helpers
+  // ---------------------------------------------------------------------------
+
+  Future<String> _extractTextLegacy(String pptxPath) async {
     final tmpDir = await _makeTmpDir('pptx_text');
 
     try {
-      // Unzip the PPTX
       final unzipResult = await Process.run('unzip', [
         '-o',
         '-q',
@@ -35,7 +94,6 @@ class PptxService {
         return '';
       }
 
-      // Find all slide XML files
       final slidesDir = Directory(p.join(tmpDir.path, 'ppt', 'slides'));
       if (!await slidesDir.exists()) return '';
 
@@ -44,7 +102,6 @@ class PptxService {
           .where((f) => f.path.contains(RegExp(r'slide\d+\.xml$')))
           .toList();
 
-      // Sort by slide number
       slideFiles.sort((a, b) {
         final aNum = _extractSlideNumber(a.path);
         final bNum = _extractSlideNumber(b.path);
@@ -67,47 +124,14 @@ class PptxService {
     } catch (_) {
       return '';
     } finally {
-      // Cleanup
       try {
         await tmpDir.delete(recursive: true);
       } catch (_) {}
     }
   }
 
-  /// Convert PPTX slides to a list of image file paths.
-  ///
-  /// Attempts LibreOffice headless conversion first. Falls back to
-  /// generating placeholder slide images (colored rectangles with slide numbers).
-  Future<List<String>> convertToImages(String pptxPath) async {
-    // Try LibreOffice first
-    final loImages = await _convertViaLibreOffice(pptxPath);
-    if (loImages.isNotEmpty) return loImages;
-
-    // Fallback: generate placeholder images
-    return _generatePlaceholderImages(pptxPath);
-  }
-
-  /// Open a file picker dialog and return the selected PPTX path, or null.
-  ///
-  /// Uses the cross-platform file_picker package.
-  Future<String?> openPptxFile() async {
-    final result = await FilePicker.platform.pickFiles(
-      type: FileType.custom,
-      allowedExtensions: ['pptx', 'ppt'],
-    );
-    final files = result?.files;
-    if (files == null || files.isEmpty) return null;
-    return files.first.path;
-  }
-
-  // ---------------------------------------------------------------------------
-  // Implementation helpers
-  // ---------------------------------------------------------------------------
-
-  /// Extract text from PPTX slide XML by finding `<a:t>` content.
   String _extractTextFromXml(String xml) {
     final lines = <String>[];
-    // Match <a:t>...</a:t> — handles both <a:t>text</a:t> and <a:t xml:space="preserve">text</a:t>
     final regex = RegExp(r'<a:t[^>]*>(.*?)</a:t>', dotAll: true);
     for (final match in regex.allMatches(xml)) {
       final text = match.group(1) ?? '';
@@ -124,12 +148,10 @@ class PptxService {
     return 0;
   }
 
-  /// Try converting via LibreOffice headless.
+  /// LibreOffice fallback — only when native fails or caller wants PNGs and
+  /// soffice is installed.
   Future<List<String>> _convertViaLibreOffice(String pptxPath) async {
     try {
-      // Resolve the LibreOffice binary across platforms. On Windows the binary
-      // is `soffice.exe` (not on PATH for `which`, which is POSIX-only), so we
-      // probe the standard install locations as well — see resolveSoffice().
       final soffice = await resolveSoffice();
       if (soffice == null) return [];
 
@@ -146,7 +168,6 @@ class PptxService {
 
       if (result.exitCode != 0) return [];
 
-      // Collect generated PNGs, sorted by name
       final pngs = await outDir
           .list()
           .where((f) => f.path.endsWith('.png'))
@@ -155,7 +176,6 @@ class PptxService {
 
       pngs.sort();
 
-      // Move to a persistent temp location so outDir can be cleaned up
       final persistDir = await _makeTmpDir('pptx_slides');
       final persistentPaths = <String>[];
       for (var i = 0; i < pngs.length; i++) {
@@ -165,7 +185,6 @@ class PptxService {
         persistentPaths.add(dst);
       }
 
-      // Clean up the LibreOffice output dir
       try {
         await outDir.delete(recursive: true);
       } catch (_) {}
@@ -176,15 +195,7 @@ class PptxService {
     }
   }
 
-  /// Resolve the LibreOffice CLI binary for the current platform, or null when
-  /// it cannot be found.
-  ///
-  /// Order:
-  ///   1. Windows: `soffice.exe` at the standard install paths
-  ///      (`C:\Program Files\LibreOffice\program\soffice.exe`, and the 32-bit
-  ///      `Program Files (x86)` variant). The POSIX `which` can't find these.
-  ///   2. POSIX: `which libreoffice`, then `which soffice` (macOS/some distros).
-  ///   3. Otherwise null → callers fall back gracefully.
+  /// Resolve the LibreOffice CLI binary, or null when unavailable.
   static Future<String?> resolveSoffice() async {
     if (Platform.isWindows) {
       const candidates = [
@@ -194,7 +205,6 @@ class PptxService {
       for (final c in candidates) {
         if (await File(c).exists()) return c;
       }
-      // Last resort: maybe soffice is on PATH (e.g. a portable install).
       if (await _whichOk('soffice')) return 'soffice';
       return null;
     }
@@ -212,11 +222,8 @@ class PptxService {
     }
   }
 
-  /// Convert an arbitrary office document (e.g. DOCX) to PDF via LibreOffice
-  /// headless, writing the PDF NEXT TO [sourcePath] (same folder, same
-  /// basename + `.pdf`). Returns the PDF path on success, or null when
-  /// LibreOffice is unavailable or the conversion fails — callers MUST handle
-  /// null and surface a friendly message rather than crash.
+  /// Convert an arbitrary office document (e.g. DOCX) to PDF via LibreOffice.
+  /// Optional — native [DocxParser] is preferred for opening in BadNote.
   Future<String?> convertToPdf(String sourcePath) async {
     final soffice = await resolveSoffice();
     if (soffice == null) return null;
@@ -243,20 +250,13 @@ class PptxService {
     }
   }
 
-  /// Generate placeholder slide images when LibreOffice is not available.
-  ///
-  /// Uses ImageMagick `convert` to create PNG files with slide numbers.
-  /// If ImageMagick is not available, writes minimal 1x1 white PNGs as
-  /// last-resort placeholders.
   Future<List<String>> _generatePlaceholderImages(String pptxPath) async {
-    // Count slides by unzipping and counting slide XML files
-    final slideCount = await _countSlides(pptxPath);
+    final slideCount = await _countSlidesNative(pptxPath);
     if (slideCount == 0) return [];
 
     final outDir = await _makeTmpDir('pptx_placeholders');
     final paths = <String>[];
 
-    // Try ImageMagick
     final hasConvert = await _hasCommand('convert');
 
     for (var i = 1; i <= slideCount; i++) {
@@ -272,7 +272,16 @@ class PptxService {
     return paths;
   }
 
-  Future<int> _countSlides(String pptxPath) async {
+  Future<int> _countSlidesNative(String pptxPath) async {
+    try {
+      final parsed = await _parser.parse(pptxPath);
+      return parsed.slides.length;
+    } catch (_) {
+      return _countSlidesUnzip(pptxPath);
+    }
+  }
+
+  Future<int> _countSlidesUnzip(String pptxPath) async {
     final tmpDir = await _makeTmpDir('pptx_count');
     try {
       await Process.run('unzip', ['-o', '-q', pptxPath, '-d', tmpDir.path]);
@@ -306,8 +315,7 @@ class PptxService {
     int slideNum,
     int total,
   ) async {
-    // Light pastel background with slide number
-    final hue = ((slideNum - 1) * 137) % 360; // golden-angle spacing
+    final hue = ((slideNum - 1) * 137) % 360;
     await Process.run('convert', [
       '-size',
       '1920x1080',
@@ -325,30 +333,24 @@ class PptxService {
     ]);
   }
 
-  /// Write a minimal valid 1x1 white PNG as an absolute last resort.
-  /// This is a hand-crafted PNG (IHDR + single white pixel IDAT + IEND).
   Future<void> _writeMinimalPng(String path) async {
-    // Minimal valid 1x1 white PNG
     const pngBytes = <int>[
-      0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, // PNG signature
-      // IHDR chunk
-      0x00, 0x00, 0x00, 0x0D, // length = 13
-      0x49, 0x48, 0x44, 0x52, // "IHDR"
-      0x00, 0x00, 0x00, 0x01, // width = 1
-      0x00, 0x00, 0x00, 0x01, // height = 1
-      0x08, 0x02, // bit depth = 8, color type = 2 (RGB)
-      0x00, 0x00, 0x00, // compression, filter, interlace
-      0x90, 0x77, 0x53, 0xDE, // CRC
-      // IDAT chunk
-      0x00, 0x00, 0x00, 0x0C, // length = 12
-      0x49, 0x44, 0x41, 0x54, // "IDAT"
+      0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
+      0x00, 0x00, 0x00, 0x0D,
+      0x49, 0x48, 0x44, 0x52,
+      0x00, 0x00, 0x00, 0x01,
+      0x00, 0x00, 0x00, 0x01,
+      0x08, 0x02,
+      0x00, 0x00, 0x00,
+      0x90, 0x77, 0x53, 0xDE,
+      0x00, 0x00, 0x00, 0x0C,
+      0x49, 0x44, 0x41, 0x54,
       0x08, 0xD7, 0x63, 0xF8, 0xCF, 0xC0, 0x00, 0x00,
-      0x01, 0x01, 0x01, 0x00, // compressed data
-      0x18, 0xDD, 0x8D, 0xB4, // CRC
-      // IEND chunk
-      0x00, 0x00, 0x00, 0x00, // length = 0
-      0x49, 0x45, 0x4E, 0x44, // "IEND"
-      0xAE, 0x42, 0x60, 0x82, // CRC
+      0x01, 0x01, 0x01, 0x00,
+      0x18, 0xDD, 0x8D, 0xB4,
+      0x00, 0x00, 0x00, 0x00,
+      0x49, 0x45, 0x4E, 0x44,
+      0xAE, 0x42, 0x60, 0x82,
     ];
     await File(path).writeAsBytes(pngBytes);
   }