@bendyline/docblocks-react 1.1.0 → 1.1.2

package/src/Export/ExportDialog.tsx

@@ -4,9 +4,9 @@
 
 import { useState, useCallback, useEffect, useRef } from 'react';
 import { getThemeSummaries } from '@bendyline/squisq/schemas';
-import { getTransformStyleSummaries } from '@bendyline/squisq/transform';
-import type { ExportFormat, ExportOptions } from './export-options.js';
+import type { ExportFormat, ExportOptions, HtmlBundle, HtmlStyle } from './export-options.js';
 import { FORMAT_LABELS, saveExportOptions } from './export-options.js';
+import { loadTransformStyleSummaries, type ExportSummaryOption } from './transform-summaries.js';
 
 export interface ExportDialogProps {
   /** Initial options (pre-populated from last export). */
@@ -21,25 +21,167 @@ export interface ExportDialogProps {
 
 const FORMATS: ExportFormat[] = ['pdf', 'docx', 'pptx', 'html', 'md'];
 
+/** Short labels for the Format chip row. The fuller `FORMAT_LABELS` list
+ *  is still used as a tooltip so users can confirm the file extension. */
+const FORMAT_CHIP_LABELS: Record<ExportFormat, string> = {
+  pdf: 'PDF',
+  docx: 'Word',
+  pptx: 'PowerPoint',
+  html: 'HTML',
+  md: 'Markdown',
+};
+
+const HTML_STYLE_CHIPS: { key: HtmlStyle; label: string; hint: string }[] = [
+  {
+    key: 'plain',
+    label: 'Plain',
+    hint: 'A lightweight static HTML document.',
+  },
+  {
+    key: 'rendered',
+    label: 'Rendered',
+    hint: 'Renders via SquisqPlayer with themes and playback support.',
+  },
+];
+
+const HTML_BUNDLE_CHIPS: { key: HtmlBundle; label: string; hint: string }[] = [
+  {
+    key: 'single',
+    label: 'Single file',
+    hint: 'One .html file with images embedded as base64 data URIs.',
+  },
+  {
+    key: 'zip',
+    label: 'ZIP archive',
+    hint: 'A .zip with index.html plus separate image (and JS) files.',
+  },
+];
+
+interface ChipOption<T extends string> {
+  key: T;
+  label: string;
+  title?: string;
+}
+
+function ChipRadioGroup<T extends string>({
+  name,
+  value,
+  options,
+  onChange,
+}: {
+  name: string;
+  value: T;
+  options: ChipOption<T>[];
+  onChange: (next: T) => void;
+}) {
+  return (
+    <div className="db-export-chips" role="radiogroup" aria-label={name}>
+      {options.map((opt) => {
+        const active = opt.key === value;
+        return (
+          <button
+            key={opt.key}
+            type="button"
+            role="radio"
+            aria-checked={active}
+            className={`db-export-chip${active ? ' db-export-chip--active' : ''}`}
+            onClick={() => onChange(opt.key)}
+            title={opt.title}
+          >
+            {opt.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
 export function ExportDialog({ initial, exporting, onExport, onClose }: ExportDialogProps) {
   const [format, setFormat] = useState<ExportFormat>(initial.format);
   const [themeId, setThemeId] = useState(initial.themeId);
   const [transformStyle, setTransformStyle] = useState(initial.transformStyle);
   const [pageSize, setPageSize] = useState(initial.pageSize);
+  const [htmlStyle, setHtmlStyle] = useState<HtmlStyle>(initial.htmlStyle);
+  const [htmlBundle, setHtmlBundle] = useState<HtmlBundle>(initial.htmlBundle);
+  const [includeLinkedDocs, setIncludeLinkedDocs] = useState<boolean>(initial.includeLinkedDocs);
+  const [entryAsIndex, setEntryAsIndex] = useState<boolean>(initial.entryAsIndex);
+  const [transforms, setTransforms] = useState<ExportSummaryOption[]>([]);
   const dialogRef = useRef<HTMLDivElement>(null);
 
   const themes = getThemeSummaries();
-  const transforms = getTransformStyleSummaries();
 
-  const showTheme = format === 'docx' || format === 'pdf' || format === 'pptx';
+  // Both HTML styles honor themes now: rendered HTML through the
+  // SquisqPlayer's theme system, plain HTML through squisq's
+  // `markdownDocToPlainHtml` which emits theme-driven CSS variables
+  // and Google Fonts links. Show the dropdown for any export format
+  // whose pipeline actually applies the picked theme.
+  const showTheme = format === 'docx' || format === 'pdf' || format === 'pptx' || format === 'html';
   const showTransform = format === 'pptx';
   const showPageSize = format === 'pdf';
+  const showHtmlOptions = format === 'html';
+  // Both HTML styles now have a recursive bundle: plain via
+  // `markdownDocsToPlainHtmlBundle`, rendered via
+  // `markdownDocsToHtmlBundle` (which rewrites Doc-tree links to
+  // `.html` before SquisqPlayer serialization). So the option applies
+  // to any HTML export.
+  const showIncludeLinked = format === 'html';
+  // Multi-doc output is inherently a directory tree, so when recursion
+  // is on the Bundle row would only confuse — ZIP is the only valid
+  // packaging. Hide the chip row and surface the implication in a hint.
+  const showHtmlBundle = showHtmlOptions && !includeLinkedDocs;
+  // `entryAsIndex` is only honored in pipelines where we control the
+  // output filename ourselves:
+  //   • single-file HTML downloads → renames `<doc>.html` → `index.html`
+  //   • recursive bundles → passed through to squisq's bundle helpers
+  // In the single-doc ZIP path, squisq's `docToHtmlZip` and our plain-
+  // HTML zip writer always emit `index.html` inside the archive, so the
+  // checkbox has no observable effect — hide it to avoid surfacing an
+  // inert control.
+  const showEntryAsIndex = showHtmlOptions && (htmlBundle === 'single' || includeLinkedDocs);
+
+  useEffect(() => {
+    if (!showTransform) return;
+    let cancelled = false;
+
+    loadTransformStyleSummaries()
+      .then((nextTransforms) => {
+        if (!cancelled) setTransforms(nextTransforms);
+      })
+      .catch(() => {
+        if (!cancelled) setTransforms([]);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [showTransform]);
 
   const handleExport = useCallback(() => {
-    const opts: ExportOptions = { format, themeId, transformStyle, pageSize };
+    const opts: ExportOptions = {
+      format,
+      themeId,
+      transformStyle,
+      pageSize,
+      htmlStyle,
+      htmlBundle,
+      includeLinkedDocs: showIncludeLinked && includeLinkedDocs,
+      entryAsIndex: showEntryAsIndex && entryAsIndex,
+    };
     saveExportOptions(opts);
     onExport(opts);
-  }, [format, themeId, transformStyle, pageSize, onExport]);
+  }, [
+    format,
+    themeId,
+    transformStyle,
+    pageSize,
+    htmlStyle,
+    htmlBundle,
+    includeLinkedDocs,
+    entryAsIndex,
+    showIncludeLinked,
+    showEntryAsIndex,
+    onExport,
+  ]);
 
   // Close on Escape
   useEffect(() => {
@@ -69,25 +211,89 @@ export function ExportDialog({ initial, exporting, onExport, onClose }: ExportDi
         </div>
 
         <div className="db-dialog-body">
-          {/* Format */}
+          {/* Format — chip radio row for fast switching */}
           <div className="db-export-field">
-            <label className="db-export-label" htmlFor="db-export-format">
-              Format
-            </label>
-            <select
-              id="db-export-format"
-              className="db-export-select"
+            <span className="db-export-label">Format</span>
+            <ChipRadioGroup
+              name="Format"
               value={format}
-              onChange={(e) => setFormat(e.target.value as ExportFormat)}
-            >
-              {FORMATS.map((f) => (
-                <option key={f} value={f}>
-                  {FORMAT_LABELS[f]}
-                </option>
-              ))}
-            </select>
+              options={FORMATS.map((f) => ({
+                key: f,
+                label: FORMAT_CHIP_LABELS[f],
+                title: FORMAT_LABELS[f],
+              }))}
+              onChange={setFormat}
+            />
           </div>
 
+          {/* HTML style + bundle (HTML only) — also chip rows */}
+          {showHtmlOptions && (
+            <>
+              <div className="db-export-field">
+                <span className="db-export-label">Style</span>
+                <ChipRadioGroup
+                  name="Style"
+                  value={htmlStyle}
+                  options={HTML_STYLE_CHIPS}
+                  onChange={setHtmlStyle}
+                />
+                <span className="db-export-hint">
+                  {HTML_STYLE_CHIPS.find((c) => c.key === htmlStyle)?.hint}
+                </span>
+              </div>
+              {showHtmlBundle && (
+                <div className="db-export-field">
+                  <span className="db-export-label">Bundle</span>
+                  <ChipRadioGroup
+                    name="Bundle"
+                    value={htmlBundle}
+                    options={HTML_BUNDLE_CHIPS}
+                    onChange={setHtmlBundle}
+                  />
+                  <span className="db-export-hint">
+                    {HTML_BUNDLE_CHIPS.find((c) => c.key === htmlBundle)?.hint}
+                  </span>
+                </div>
+              )}
+              {showIncludeLinked && (
+                <div className="db-export-field">
+                  <label className="db-export-checkbox">
+                    <input
+                      type="checkbox"
+                      checked={includeLinkedDocs}
+                      onChange={(e) => setIncludeLinkedDocs(e.target.checked)}
+                    />
+                    <span>Include linked-to documents</span>
+                  </label>
+                  <span className="db-export-hint">
+                    {includeLinkedDocs
+                      ? 'Follows relative .md links from this page and bundles every reachable document as its own .html in a ZIP. Cross-doc links rewrite from .md to .html.'
+                      : 'Only this document is exported.'}
+                  </span>
+                </div>
+              )}
+              {showEntryAsIndex && (
+                <div className="db-export-field">
+                  <label className="db-export-checkbox">
+                    <input
+                      type="checkbox"
+                      checked={entryAsIndex}
+                      onChange={(e) => setEntryAsIndex(e.target.checked)}
+                    />
+                    <span>Name entry page index.html</span>
+                  </label>
+                  <span className="db-export-hint">
+                    {entryAsIndex
+                      ? includeLinkedDocs
+                        ? 'Renames this page to index.html in the ZIP and rewrites any cross-doc links pointing back at it. Drops straight into a static-site host.'
+                        : 'Downloads as index.html instead of the document name. Drops straight into a static-site host.'
+                      : 'Exports under the document name.'}
+                  </span>
+                </div>
+              )}
+            </>
+          )}
+
           {/* Theme */}
           {showTheme && (
             <div className="db-export-field">
@@ -124,11 +330,15 @@ export function ExportDialog({ initial, exporting, onExport, onClose }: ExportDi
                 value={transformStyle}
                 onChange={(e) => setTransformStyle(e.target.value)}
               >
-                {transforms.map((t) => (
-                  <option key={t.id} value={t.id}>
-                    {t.name}
-                  </option>
-                ))}
+                {transforms.length === 0 ? (
+                  <option value={transformStyle}>Loading...</option>
+                ) : (
+                  transforms.map((t) => (
+                    <option key={t.id} value={t.id}>
+                      {t.name}
+                    </option>
+                  ))
+                )}
               </select>
               <span className="db-export-hint">
                 {transforms.find((t) => t.id === transformStyle)?.description}

package/src/Export/ExportToolbarControls.tsx

@@ -7,15 +7,12 @@
  * Must be rendered inside <EditorProvider> so useEditorContext() works.
  */
 
-import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
+import { useState, useCallback, useEffect, useRef, useMemo, type ComponentType } from 'react';
 import { useEditorContext } from '@bendyline/squisq-editor-react';
 import { getThemeSummaries } from '@bendyline/squisq/schemas';
-import { getTransformStyleSummaries } from '@bendyline/squisq/transform';
 import { parseMarkdown } from '@bendyline/squisq/markdown';
-import { markdownToDoc } from '@bendyline/squisq/doc';
-import { VideoExportModal } from '@bendyline/squisq-video-react';
-import { PLAYER_BUNDLE } from '@bendyline/squisq-react/standalone-source';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { VideoExportModalProps } from '@bendyline/squisq-video-react';
 import type { ExportOptions } from './export-options.js';
 import {
   DEFAULT_OPTIONS,
@@ -25,6 +22,7 @@ import {
 } from './export-options.js';
 import { ExportDialog } from './ExportDialog.js';
 import { runExport } from './run-export.js';
+import { loadTransformStyleSummaries, type ExportSummaryOption } from './transform-summaries.js';
 
 export interface ExportToolbarControlsProps {
   /** Currently selected file path — used to derive the download filename. */
@@ -33,17 +31,55 @@ export interface ExportToolbarControlsProps {
   mediaContainer?: ContentContainer | null;
 }
 
+type ParsedMarkdown = ReturnType<typeof parseMarkdown>;
+
+interface VideoExportModules {
+  Modal: ComponentType<VideoExportModalProps>;
+  markdownToDoc: (doc: ParsedMarkdown) => VideoExportModalProps['doc'];
+  playerScript: string;
+}
+
+let videoExportModulesPromise: Promise<VideoExportModules> | null = null;
+
+function loadVideoExportModules(): Promise<VideoExportModules> {
+  videoExportModulesPromise ??= Promise.all([
+    import('@bendyline/squisq/doc'),
+    import('@bendyline/squisq-video-react'),
+    import('@bendyline/squisq-react/standalone-source'),
+  ]).then(([docModule, videoModule, playerModule]) => ({
+    Modal: videoModule.VideoExportModal,
+    markdownToDoc: docModule.markdownToDoc,
+    playerScript: playerModule.PLAYER_BUNDLE,
+  }));
+  return videoExportModulesPromise;
+}
+
 /** Build the quick-export label from saved options. */
-function quickLabel(opts: ExportOptions): string {
-  const ext = FORMAT_EXTENSIONS[opts.format].toUpperCase().replace('.', '');
+function quickLabel(opts: ExportOptions, transformSummaries: ExportSummaryOption[]): string {
+  const baseExt = FORMAT_EXTENSIONS[opts.format].toUpperCase().replace('.', '');
+  // Recursive HTML always emits a ZIP (multi-doc tree), regardless of
+  // the saved `htmlBundle` value. Applies to both plain and rendered
+  // styles since both now ship recursive bundle helpers.
+  const isRecursiveHtml = opts.format === 'html' && opts.includeLinkedDocs;
+  const ext =
+    opts.format === 'html' && (opts.htmlBundle === 'zip' || isRecursiveHtml) ? 'ZIP' : baseExt;
   const parts: string[] = [];
 
+  if (opts.format === 'html' && opts.htmlStyle === 'rendered') {
+    parts.push('rendered');
+  }
+  if (isRecursiveHtml) {
+    parts.push('linked docs');
+  }
+  // Plain HTML also applies themes now (squisq's `markdownDocToPlainHtml`
+  // emits theme-driven CSS), so include the theme name in the quick-
+  // export label for every HTML style — not just rendered.
   if (opts.themeId !== 'standard') {
     const theme = getThemeSummaries().find((t) => t.id === opts.themeId);
     if (theme) parts.push(theme.name);
   }
   if (opts.format === 'pptx' && opts.transformStyle) {
-    const transform = getTransformStyleSummaries().find((t) => t.id === opts.transformStyle);
+    const transform = transformSummaries.find((t) => t.id === opts.transformStyle);
     if (transform) parts.push(transform.name);
   }
 
@@ -57,21 +93,46 @@ export function ExportToolbarControls({
   selectedFile,
   mediaContainer,
 }: ExportToolbarControlsProps) {
-  const { markdownSource } = useEditorContext();
+  const { markdownSource, markdownDoc } = useEditorContext();
   const [menuOpen, setMenuOpen] = useState(false);
   const [dialogOpen, setDialogOpen] = useState(false);
   const [videoModalOpen, setVideoModalOpen] = useState(false);
+  const [videoLoading, setVideoLoading] = useState(false);
+  const [videoLoadError, setVideoLoadError] = useState<string | null>(null);
+  const [videoModules, setVideoModules] = useState<VideoExportModules | null>(null);
+  const [videoDoc, setVideoDoc] = useState<VideoExportModalProps['doc'] | null>(null);
+  const [transformSummaries, setTransformSummaries] = useState<ExportSummaryOption[]>([]);
   const [exporting, setExporting] = useState(false);
   const menuRef = useRef<HTMLDivElement>(null);
 
   const lastOptions = loadLastExportOptions();
 
-  /** Build a Doc from the current markdown for video export. */
-  const doc = useMemo(() => {
-    if (!videoModalOpen) return null;
-    const mdDoc = parseMarkdown(markdownSource);
-    return markdownToDoc(mdDoc);
-  }, [videoModalOpen, markdownSource]);
+  /** Doc's currently-set squisq theme, pulled from the markdown
+   *  frontmatter. The Document Settings dialog and Theme Customizer
+   *  write the theme under `squisq-theme` (canonical) or `theme`
+   *  (legacy); some older docs persist it as `themeId`. We honor all
+   *  three so an author who set their theme anywhere upstream sees it
+   *  pre-selected in the export dialog. */
+  const docThemeId = useMemo(() => {
+    const fm = markdownDoc?.frontmatter as Record<string, unknown> | undefined;
+    if (!fm) return null;
+    const candidates = [fm['squisq-theme'], fm['theme'], fm['themeId']];
+    for (const v of candidates) {
+      if (typeof v === 'string' && v.trim()) return v.trim();
+    }
+    return null;
+  }, [markdownDoc]);
+
+  /** Options used to populate the export dialog. Layered: built-in
+   *  defaults → user's last-chosen export options (if any) → doc's
+   *  current frontmatter theme (wins). The frontmatter override
+   *  guarantees that "set theme in the editor, then export" pre-selects
+   *  the right theme instead of resurrecting whatever the user picked
+   *  for some unrelated previous doc. */
+  const dialogInitial = useMemo(() => {
+    const base = lastOptions ?? DEFAULT_OPTIONS;
+    return docThemeId ? { ...base, themeId: docThemeId } : base;
+  }, [lastOptions, docThemeId]);
 
   // Close menu on outside click
   useEffect(() => {
@@ -85,6 +146,30 @@ export function ExportToolbarControls({
     return () => document.removeEventListener('pointerdown', onPointerDown);
   }, [menuOpen]);
 
+  useEffect(() => {
+    if (
+      !menuOpen ||
+      lastOptions?.format !== 'pptx' ||
+      !lastOptions.transformStyle ||
+      transformSummaries.length > 0
+    ) {
+      return;
+    }
+
+    let cancelled = false;
+    loadTransformStyleSummaries()
+      .then((nextSummaries) => {
+        if (!cancelled) setTransformSummaries(nextSummaries);
+      })
+      .catch(() => {
+        if (!cancelled) setTransformSummaries([]);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [lastOptions?.format, lastOptions?.transformStyle, menuOpen, transformSummaries.length]);
+
   const handleToggleMenu = useCallback(() => {
     setMenuOpen((prev) => !prev);
   }, []);
@@ -98,13 +183,27 @@ export function ExportToolbarControls({
     setDialogOpen(false);
   }, []);
 
-  const handleOpenVideoModal = useCallback(() => {
+  const handleOpenVideoModal = useCallback(async () => {
     setMenuOpen(false);
     setVideoModalOpen(true);
-  }, []);
+    setVideoLoading(true);
+    setVideoLoadError(null);
+
+    try {
+      const modules = videoModules ?? (await loadVideoExportModules());
+      setVideoModules(modules);
+      setVideoDoc(modules.markdownToDoc(parseMarkdown(markdownSource)));
+    } catch {
+      setVideoLoadError('Video export could not be loaded.');
+    } finally {
+      setVideoLoading(false);
+    }
+  }, [markdownSource, videoModules]);
 
   const handleCloseVideoModal = useCallback(() => {
     setVideoModalOpen(false);
+    setVideoDoc(null);
+    setVideoLoadError(null);
   }, []);
 
   const handleExport = useCallback(
@@ -132,6 +231,8 @@ export function ExportToolbarControls({
     }
   }, [lastOptions, markdownSource, selectedFile, mediaContainer]);
 
+  const LoadedVideoExportModal = videoModules?.Modal;
+
   return (
     <>
       <div className="db-toolbar-menu" ref={menuRef}>
@@ -152,7 +253,7 @@ export function ExportToolbarControls({
                 onClick={handleQuickExport}
                 disabled={exporting}
               >
-                {quickLabel(lastOptions)}
+                {quickLabel(lastOptions, transformSummaries)}
               </button>
             )}
             <button className="db-toolbar-menu-item" onClick={handleOpenDialog}>
@@ -168,16 +269,45 @@ export function ExportToolbarControls({
 
       {dialogOpen && (
         <ExportDialog
-          initial={lastOptions ?? DEFAULT_OPTIONS}
+          initial={dialogInitial}
           exporting={exporting}
           onExport={handleExport}
           onClose={handleCloseDialog}
         />
       )}
 
-      {videoModalOpen && doc && (
-        <VideoExportModal doc={doc} playerScript={PLAYER_BUNDLE} onClose={handleCloseVideoModal} />
+      {videoModalOpen && (videoLoading || videoLoadError) && (
+        <div className="db-dialog-overlay">
+          <div className="db-dialog">
+            <div className="db-dialog-header">
+              <h2 className="db-dialog-title">Export Video</h2>
+              <button
+                className="db-dialog-close"
+                onClick={handleCloseVideoModal}
+                aria-label="Close"
+              >
+                &times;
+              </button>
+            </div>
+            <div className="db-dialog-body">
+              <p className="db-export-hint">{videoLoadError ?? 'Loading...'}</p>
+            </div>
+          </div>
+        </div>
       )}
+
+      {videoModalOpen &&
+        videoModules &&
+        LoadedVideoExportModal &&
+        videoDoc &&
+        !videoLoading &&
+        !videoLoadError && (
+          <LoadedVideoExportModal
+            doc={videoDoc}
+            playerScript={videoModules.playerScript}
+            onClose={handleCloseVideoModal}
+          />
+        )}
     </>
   );
 }

package/src/Export/export-options.ts

@@ -4,6 +4,20 @@
 
 export type ExportFormat = 'docx' | 'pdf' | 'pptx' | 'md' | 'html';
 
+/** Visual style for HTML export. */
+export type HtmlStyle =
+  /** Render via SquisqPlayer (themed, embeds player bundle). */
+  | 'rendered'
+  /** Plain semantic HTML — small, no JS, no playback. */
+  | 'plain';
+
+/** Packaging for HTML export. */
+export type HtmlBundle =
+  /** Single self-contained .html file (images base64-embedded). */
+  | 'single'
+  /** ZIP containing index.html + asset files. */
+  | 'zip';
+
 export interface ExportOptions {
   format: ExportFormat;
   themeId: string;
@@ -11,6 +25,29 @@ export interface ExportOptions {
   transformStyle: string;
   /** Only applies to PDF */
   pageSize: 'letter' | 'a4';
+  /** HTML rendering style. Only applies to format=html. */
+  htmlStyle: HtmlStyle;
+  /** HTML bundle layout. Only applies to format=html. */
+  htmlBundle: HtmlBundle;
+  /**
+   * Recursive HTML bundle: walk relative `.md` links from the entry
+   * document, render every reachable sibling/child page, and rewrite
+   * cross-doc links from `.md` → `.html`. The output is a ZIP
+   * regardless of `htmlBundle` because multi-doc output needs a
+   * directory tree. Supported for both plain (`markdownDocsToPlainHtmlBundle`)
+   * and rendered (`markdownDocsToHtmlBundle`) HTML styles. Only
+   * meaningful when `format === 'html'`.
+   */
+  includeLinkedDocs: boolean;
+  /**
+   * Rename the entry page from `<basename>.html` to `index.html` so the
+   * export drops straight into a static-site host that expects an
+   * `index.html` landing page. For recursive bundles, cross-doc links
+   * targeting the entry also rewrite to `index.html` so siblings don't
+   * 404. For a single-doc HTML download, this just renames the file.
+   * Only meaningful when `format === 'html'`.
+   */
+  entryAsIndex: boolean;
 }
 
 export const FORMAT_LABELS: Record<ExportFormat, string> = {
@@ -36,13 +73,18 @@ export const DEFAULT_OPTIONS: ExportOptions = {
   themeId: 'standard',
   transformStyle: 'documentary',
   pageSize: 'letter',
+  htmlStyle: 'plain',
+  htmlBundle: 'single',
+  includeLinkedDocs: false,
+  entryAsIndex: false,
 };
 
 export function loadLastExportOptions(): ExportOptions | null {
   try {
     const raw = localStorage.getItem(STORAGE_KEY);
     if (!raw) return null;
-    return JSON.parse(raw) as ExportOptions;
+    const parsed = JSON.parse(raw) as Partial<ExportOptions>;
+    return { ...DEFAULT_OPTIONS, ...parsed };
   } catch {
     return null;
   }