@bendyline/squisq-formats 2.4.2 → 2.4.4

package/NOTICE.md

@@ -10,7 +10,7 @@ Third-party components remain under their respective license terms.
 | ---------------- | ------- | ----------------------- | ---------------------------------- |
 | @pdf-lib/fontkit | 1.1.1   | MIT                     | https://github.com/Hopding/fontkit |
 | @pdf-lib/upng    | 1.0.1   | MIT                     | https://github.com/Hopding/upng    |
-| @xmldom/xmldom   | 0.9.10  | MIT                     | https://github.com/xmldom/xmldom   |
+| @xmldom/xmldom   | 0.9.11  | MIT                     | https://github.com/xmldom/xmldom   |
 | jszip            | 3.10.1  | MIT OR GPL-3.0-or-later | https://github.com/Stuk/jszip      |
 | pdf-lib          | 1.17.1  | MIT                     | https://pdf-lib.js.org             |
 | pdfjs-dist       | 4.10.38 | Apache-2.0              | https://mozilla.github.io/pdf.js   |

package/dist/chunk-2P5HJAQL.js

@@ -0,0 +1,17 @@
+// src/registry/types.ts
+var BUILTIN_FORMAT_IDS = [
+  "md",
+  "docx",
+  "pdf",
+  "pptx",
+  "xlsx",
+  "csv",
+  "html",
+  "htmlzip",
+  "epub",
+  "dbk"
+];
+
+export {
+  BUILTIN_FORMAT_IDS
+};

package/dist/chunk-BVGJ54NV.js

@@ -0,0 +1,284 @@
+import {
+  convert,
+  defaultRegistry
+} from "./chunk-DNGNODJP.js";
+import {
+  ConversionError
+} from "./chunk-KXOZMWBS.js";
+
+// src/outside-in/index.ts
+import {
+  parseFrontmatter,
+  setFrontmatterValues,
+  splitFrontmatterBlock,
+  stringifyMarkdown
+} from "@bendyline/squisq/markdown";
+import { MemoryContentContainer } from "@bendyline/squisq/storage";
+var OUTSIDE_IN_FORMAT_IDS = ["html", "docx", "pdf", "pptx", "xlsx"];
+var OUTSIDE_IN_FORMAT_SET = new Set(OUTSIDE_IN_FORMAT_IDS);
+var OUTSIDE_IN_VERSION_KEY = "squisq-outside-in";
+var OUTSIDE_IN_OUTPUT_KEY = "squisq-output";
+var OUTSIDE_IN_FORMAT_KEY = "squisq-output-format";
+var OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY = "squisq-updatefrommarkdown";
+function normalizePath(path) {
+  const slash = path.replace(/\\/g, "/");
+  const leading = slash.startsWith("/") ? "/" : "";
+  const parts = slash.split("/").filter((part) => part !== "");
+  if (parts.some((part) => part === "." || part === "..")) {
+    throw new Error(`Outside-in paths must be canonical workspace paths: ${path}`);
+  }
+  return leading + parts.join("/");
+}
+function joinPath(parent, child) {
+  if (!parent || parent === "/") return parent === "/" ? `/${child}` : child;
+  return `${parent}/${child}`;
+}
+function dirname(path) {
+  const slash = path.lastIndexOf("/");
+  if (slash < 0) return "";
+  if (slash === 0) return "/";
+  return path.slice(0, slash);
+}
+function basename(path) {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+function slugStem(stem) {
+  const slug = stem.normalize("NFKD").replace(/\p{Mark}+/gu, "").toLocaleLowerCase("en-US").replace(/[^\p{Letter}\p{Number}]+/gu, "-").replace(/^-+|-+$/g, "");
+  return slug || "document";
+}
+function formatFromExtension(extension) {
+  const normalized = extension.toLowerCase();
+  if (normalized === "htm") return "html";
+  return OUTSIDE_IN_FORMAT_SET.has(normalized) ? normalized : null;
+}
+function resolveOutsideInLayout(targetPath) {
+  const normalized = normalizePath(targetPath);
+  const filename = basename(normalized);
+  const dot = filename.lastIndexOf(".");
+  if (dot <= 0 || dot === filename.length - 1) return null;
+  const format = formatFromExtension(filename.slice(dot + 1));
+  if (!format) return null;
+  const stem = filename.slice(0, dot);
+  const parentDirectory = dirname(normalized);
+  const companionName = `${stem}_files`;
+  const companionDirectory = joinPath(parentDirectory, companionName);
+  const markdownFilename = `${slugStem(stem)}.md`;
+  const backupDirectory = joinPath(companionDirectory, ".original");
+  const backupFilename = `original.${format}`;
+  return {
+    targetPath: normalized,
+    format,
+    parentDirectory,
+    stem,
+    companionName,
+    companionDirectory,
+    markdownFilename,
+    markdownPath: joinPath(companionDirectory, markdownFilename),
+    relativeTargetPath: `../${filename}`,
+    backupDirectory,
+    backupFilename,
+    backupPath: joinPath(backupDirectory, backupFilename)
+  };
+}
+function isOutsideInTargetPath(path) {
+  return resolveOutsideInLayout(path) !== null;
+}
+function chooseOutsideInMarkdownPath(layout, paths) {
+  const canonical = normalizePath(layout.markdownPath);
+  const normalized = paths.map(normalizePath);
+  const exact = normalized.find((path) => path === canonical);
+  if (exact) return exact;
+  const canonicalFolded = canonical.toLocaleLowerCase("en-US");
+  const folded = normalized.find((path) => path.toLocaleLowerCase("en-US") === canonicalFolded);
+  if (folded) return folded;
+  const prefix = `${normalizePath(layout.companionDirectory).replace(/\/$/, "")}/`;
+  const markdown = normalized.filter((path) => {
+    if (!path.toLocaleLowerCase("en-US").endsWith(".md")) return false;
+    if (!path.startsWith(prefix)) return false;
+    return !path.slice(prefix.length).includes("/");
+  });
+  return markdown.length === 1 ? markdown[0] : null;
+}
+function rawFrontmatter(source) {
+  const block = splitFrontmatterBlock(source).frontmatter;
+  if (!block) return null;
+  const firstBreak = block.indexOf("\n");
+  if (firstBreak < 0) return null;
+  const withoutOpening = block.slice(firstBreak + 1);
+  return withoutOpening.replace(/\r?\n---(?:\r?\n)?$/, "");
+}
+function readOutsideInMetadata(source) {
+  const yaml = rawFrontmatter(source);
+  const frontmatter = yaml === null ? null : parseFrontmatter(yaml);
+  if (!frontmatter) return null;
+  const version = frontmatter[OUTSIDE_IN_VERSION_KEY];
+  const target = frontmatter[OUTSIDE_IN_OUTPUT_KEY];
+  const format = frontmatter[OUTSIDE_IN_FORMAT_KEY];
+  if (version !== 1 || typeof target !== "string" || typeof format !== "string") return null;
+  if (!OUTSIDE_IN_FORMAT_SET.has(format)) return null;
+  return {
+    version: 1,
+    target,
+    format,
+    updateFromMarkdown: frontmatter[OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY] === true
+  };
+}
+function withOutsideInMetadata(source, layout) {
+  return setFrontmatterValues(source, {
+    [OUTSIDE_IN_VERSION_KEY]: 1,
+    [OUTSIDE_IN_OUTPUT_KEY]: layout.relativeTargetPath,
+    [OUTSIDE_IN_FORMAT_KEY]: layout.format
+  });
+}
+function isOutsideInMarkdownEditingEnabled(source) {
+  if (typeof source !== "string") {
+    return source.frontmatter?.[OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY] === true;
+  }
+  const yaml = rawFrontmatter(source);
+  const frontmatter = yaml === null ? null : parseFrontmatter(yaml);
+  return frontmatter?.[OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY] === true;
+}
+function withOutsideInMarkdownEditing(source, layout, enabled = true) {
+  return setFrontmatterValues(withOutsideInMetadata(source, layout), {
+    [OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY]: enabled
+  });
+}
+function requireLayout(targetPath) {
+  const layout = resolveOutsideInLayout(targetPath);
+  if (layout) return layout;
+  throw new ConversionError(
+    "unknown-format",
+    `Outside-in editing does not support the target "${targetPath}".`
+  );
+}
+function arrayBufferOf(data) {
+  if (data instanceof ArrayBuffer) return data;
+  return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+}
+async function importMarkdownDocument(data, layout, registry, options) {
+  const definition = registry.get(layout.format);
+  if (!definition || !definition.importContainer && !definition.importDoc) {
+    throw new ConversionError(
+      "unsupported-input",
+      `Format "${layout.format}" cannot be imported for outside-in editing.`,
+      { format: layout.format }
+    );
+  }
+  if (definition.importContainer) {
+    const container = await definition.importContainer(data, options);
+    const imported = await container.readDocument();
+    if (imported !== null) {
+      const { parseMarkdown } = await import("@bendyline/squisq/markdown");
+      return { markdownDoc: parseMarkdown(imported), container };
+    }
+    if (definition.importDoc) {
+      return { markdownDoc: await definition.importDoc(data, options), container };
+    }
+    throw new ConversionError("invalid-input", "Imported document did not contain Markdown.", {
+      format: layout.format
+    });
+  }
+  const markdownDoc = await definition.importDoc(data, options);
+  return { markdownDoc, container: new MemoryContentContainer() };
+}
+async function retainImportedOfficeTheme(data, layout, markdownDoc, options) {
+  if (layout.format !== "docx" && layout.format !== "xlsx") return [];
+  if (typeof markdownDoc.frontmatter?.["squisq-theme"] === "string") return [];
+  try {
+    const [{ inferThemeFromFile }, themeCodec] = await Promise.all([
+      import("./infer/index.js"),
+      import("@bendyline/squisq/doc")
+    ]);
+    const inferred = await inferThemeFromFile(data, {
+      format: layout.format,
+      nameHint: layout.stem,
+      signal: options.signal
+    });
+    const payload = themeCodec.writeCustomThemesToFrontmatter([inferred.theme]);
+    if (payload) {
+      markdownDoc.frontmatter = {
+        ...markdownDoc.frontmatter ?? {},
+        [themeCodec.FRONTMATTER_CUSTOM_THEMES_KEY]: payload,
+        "squisq-theme": inferred.theme.id
+      };
+    }
+    return inferred.warnings;
+  } catch (error) {
+    if (options.signal?.aborted) throw options.signal.reason ?? error;
+    return [
+      `The ${layout.format.toUpperCase()} content was imported, but its Office theme could not be retained: ${error instanceof Error ? error.message : String(error)}`
+    ];
+  }
+}
+async function importOutsideInDocument(source, options = {}) {
+  options.signal?.throwIfAborted();
+  const layout = requireLayout(source.targetPath);
+  const data = arrayBufferOf(source.data);
+  const registry = options.registry ?? defaultRegistry();
+  const imported = await importMarkdownDocument(data, layout, registry, {
+    ...options,
+    registry,
+    from: layout.format
+  });
+  const warnings = await retainImportedOfficeTheme(data, layout, imported.markdownDoc, options);
+  options.signal?.throwIfAborted();
+  const markdownOptions = options.formatOptions?.md;
+  const markdown = withOutsideInMetadata(
+    stringifyMarkdown(imported.markdownDoc, markdownOptions?.stringify),
+    layout
+  );
+  return { layout, markdown, container: imported.container, warnings };
+}
+async function renderOutsideInDocument(source, options = {}) {
+  const layout = requireLayout(source.targetPath);
+  if (!isOutsideInMarkdownEditingEnabled(source.markdown)) {
+    throw new ConversionError(
+      "invalid-input",
+      `Outside-in editing is read-only until ${OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY}: true is set.`,
+      { format: layout.format }
+    );
+  }
+  if (layout.format === "html" && !options.html?.playerScriptPath) {
+    throw new ConversionError(
+      "missing-dependency",
+      "Outside-in HTML export needs a shared Squisq player path.",
+      { format: "html" }
+    );
+  }
+  const formatOptions = { ...options.formatOptions ?? {} };
+  if (layout.format === "html" && options.html) {
+    formatOptions.html = {
+      ...formatOptions.html ?? {},
+      playerScriptPath: options.html.playerScriptPath,
+      basePath: options.html.basePath ?? layout.companionName
+    };
+  }
+  return convert(
+    {
+      kind: "markdown",
+      markdown: source.markdown,
+      container: source.container,
+      baseName: layout.stem
+    },
+    layout.format,
+    {
+      ...options,
+      title: options.title ?? layout.stem,
+      formatOptions
+    }
+  );
+}
+
+export {
+  OUTSIDE_IN_FORMAT_IDS,
+  OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY,
+  resolveOutsideInLayout,
+  isOutsideInTargetPath,
+  chooseOutsideInMarkdownPath,
+  readOutsideInMetadata,
+  withOutsideInMetadata,
+  isOutsideInMarkdownEditingEnabled,
+  withOutsideInMarkdownEditing,
+  importOutsideInDocument,
+  renderOutsideInDocument
+};

package/dist/{chunk-24VREWAZ.js → chunk-DNGNODJP.js}

@@ -7,20 +7,6 @@ import {
   resolveZipSafetyLimits
 } from "./chunk-7AWFHP5U.js";
 
-// src/registry/types.ts
-var BUILTIN_FORMAT_IDS = [
-  "md",
-  "docx",
-  "pdf",
-  "pptx",
-  "xlsx",
-  "csv",
-  "html",
-  "htmlzip",
-  "epub",
-  "dbk"
-];
-
 // src/registry/limits.ts
 var DEFAULT_CONVERSION_LIMITS = Object.freeze({
   maxInputBytes: 256 * 1024 * 1024,
@@ -481,9 +467,21 @@ function defaultFormats() {
     // importContainer omitted: HTML import already inlines images as data URIs,
     // so there is nothing to extract into a container this wave.
     async exportDoc(input, options) {
+      const raw = optionsFor(options, "html");
+      if (raw.playerScriptPath) {
+        const { generateExternalHtml } = await import("./html/index.js");
+        const htmlText2 = generateExternalHtml(input.doc, {
+          ...raw,
+          playerScriptPath: raw.playerScriptPath,
+          title: options.title ?? input.baseName,
+          mode: raw.mode ?? "static",
+          themeId: resolveThemeId(input, options),
+          themeRegistry: options.themeRegistry ?? raw.themeRegistry
+        });
+        return ok(new TextEncoder().encode(htmlText2), MIME.html);
+      }
       const playerScript = await requirePlayerScript(options, "html");
       const { docToHtml } = await import("./html/index.js");
-      const raw = optionsFor(options, "html");
       const containerImages = await collectContainerImages(input.container, options.signal);
       const images = new Map([...containerImages, ...raw.images ?? /* @__PURE__ */ new Map()]);
       const htmlText = docToHtml(input.doc, {
@@ -925,7 +923,6 @@ async function convert(source, to, options = {}) {
 }
 
 export {
-  BUILTIN_FORMAT_IDS,
   DEFAULT_CONVERSION_LIMITS,
   resolveConversionLimits,
   defaultFormats,

package/dist/{chunk-A5Y23TAF.js → chunk-N2ZN3MQN.js}

@@ -140,6 +140,7 @@ function buildInlineImageMaps(images) {
 function generateInlineHtml(doc, options) {
   const {
     playerScript,
+    basePath = ".",
     images,
     mode = "slideshow",
     title = "Squisq Document",
@@ -189,7 +190,7 @@ ${mode === "static" ? "#squisq-root{display:block}" : ""}
     autoPlay: ${JSON.stringify(autoPlay)},${captionStyle ? `
     captionStyle: ${JSON.stringify(captionStyle)},` : ""}
     showCodeCopyButton: ${JSON.stringify(showCodeCopyButton)},
-    basePath: "."
+    basePath: ${JSON.stringify(basePath)}
   });
 })();
 </script>
@@ -207,7 +208,8 @@ function generateExternalHtml(doc, options) {
     showCodeCopyButton = false,
     captionStyle,
     themeId,
-    themeRegistry
+    themeRegistry,
+    basePath = "."
   } = options;
   doc = applyThemeSelection(doc, themeId, themeRegistry);
   const docJson = escapeForScript(JSON.stringify(doc));
@@ -242,7 +244,7 @@ ${mode === "static" ? "#squisq-root{display:block}" : ""}
     autoPlay: ${JSON.stringify(autoPlay)},${captionStyle ? `
     captionStyle: ${JSON.stringify(captionStyle)},` : ""}
     showCodeCopyButton: ${JSON.stringify(showCodeCopyButton)},
-    basePath: "."
+    basePath: ${JSON.stringify(basePath)}
   });
 })();
 </script>

package/dist/html/index.d.ts

@@ -1,6 +1,6 @@
 import { Theme, ThemeRegistry, Doc } from '@bendyline/squisq/schemas';
-import { H as HtmlExportOptions } from '../import-BQFf0iEG.js';
-export { a as HtmlImportOptions, c as collectImagePaths, g as generateExternalHtml, h as htmlToMarkdown, b as htmlToMarkdownDoc, d as htmlToMarkdownDocSync } from '../import-BQFf0iEG.js';
+import { H as HtmlExportOptions } from '../import-B0gBYUmd.js';
+export { a as HtmlImportOptions, c as collectImagePaths, g as generateExternalHtml, h as htmlToMarkdown, b as htmlToMarkdownDoc, d as htmlToMarkdownDocSync } from '../import-B0gBYUmd.js';
 import { HtmlPolicy, MarkdownDocument } from '@bendyline/squisq/markdown';
 
 /**

package/dist/html/index.js

@@ -10,7 +10,7 @@ import {
   markdownDocToPlainHtml,
   markdownDocsToHtmlBundle,
   markdownDocsToPlainHtmlBundle
-} from "../chunk-A5Y23TAF.js";
+} from "../chunk-N2ZN3MQN.js";
 import {
   arrayBufferToBase64DataUrl,
   extractFilename,

package/dist/{import-BQFf0iEG.d.ts → import-B0gBYUmd.d.ts}

@@ -18,6 +18,17 @@ interface HtmlExportOptions {
     signal?: AbortSignal;
     /** The IIFE player bundle source code (from @bendyline/squisq-react/standalone-source) */
     playerScript: string;
+    /**
+     * Reference an existing standalone player instead of embedding
+     * {@link playerScript}. Used by outside-in documents that share one
+     * `_squisq/squisq-player.js` runtime across a folder hierarchy.
+     */
+    playerScriptPath?: string;
+    /**
+     * Base URL used to resolve relative document media. Defaults to `.`.
+     * Outside-in HTML points this at the document's companion `_files` folder.
+     */
+    basePath?: string;
     /**
      * Map of relative image paths (as they appear in the Doc) to binary image data.
      * For inline HTML export, these are converted to base64 data URIs.
@@ -67,7 +78,7 @@ declare function collectImagePaths(doc: Doc): Set<string>;
  * @param options - Export options (playerScript is not embedded, referenced via src)
  * @returns Complete HTML string
  */
-declare function generateExternalHtml(doc: Doc, options: Pick<HtmlExportOptions, 'mode' | 'title' | 'autoPlay' | 'showCodeCopyButton' | 'captionStyle' | 'themeId' | 'themeRegistry'> & {
+declare function generateExternalHtml(doc: Doc, options: Pick<HtmlExportOptions, 'mode' | 'title' | 'autoPlay' | 'showCodeCopyButton' | 'captionStyle' | 'themeId' | 'themeRegistry' | 'basePath'> & {
     /** Relative path to the player JS file (e.g., 'squisq-player.js') */
     playerScriptPath: string;
     /** Map of original image paths to their rewritten relative paths in the ZIP */

package/dist/index.d.ts

@@ -6,9 +6,11 @@ export { PdfExportOptions, PdfImportOptions, configurePdfWorker, docToPdf, markd
 export { HtmlZipExportOptions, docToHtml, docToHtmlZip } from './html/index.js';
 export { EpubExportOptions, docToEpub, markdownDocToEpub } from './epub/index.js';
 export { ExtractedFileTheme, InferSourceFormat, InferThemeOptions, InferredFileTheme, compileExtractedTheme, inferThemeFromFile } from './infer/index.js';
-export { BUILTIN_FORMAT_IDS, BuiltinFormatOptions, ConversionError, ConversionErrorCode, ConversionErrorOptions, ConversionLimits, ConversionResult, ConvertOptions, ConvertSource, DEFAULT_CONVERSION_LIMITS, DbkFormatOptions, FormatDefinition, FormatId, FormatRegistry, MarkdownFormatOptions, NormalizedInput, PreparedConversion, PreparedExportOptions, convert, createRegistry, defaultFormats, defaultRegistry, prepareConversion, resolveConversionLimits } from './registry/index.js';
+export { B as BUILTIN_FORMAT_IDS, a as BuiltinFormatOptions, C as ConversionLimits, b as ConversionResult, c as ConvertOptions, d as ConvertSource, D as DEFAULT_CONVERSION_LIMITS, e as DbkFormatOptions, F as FormatDefinition, f as FormatId, g as FormatRegistry, M as MarkdownFormatOptions, N as NormalizedInput, P as PreparedConversion, h as PreparedExportOptions, r as resolveConversionLimits } from './types-HDLauUoa.js';
+export { ConversionError, ConversionErrorCode, ConversionErrorOptions, convert, createRegistry, defaultFormats, defaultRegistry, prepareConversion } from './registry/index.js';
+export { ImportedOutsideInDocument, OUTSIDE_IN_FORMAT_IDS, OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY, OutsideInFormatId, OutsideInLayout, OutsideInMetadata, RenderOutsideInOptions, chooseOutsideInMarkdownPath, importOutsideInDocument, isOutsideInMarkdownEditingEnabled, isOutsideInTargetPath, readOutsideInMetadata, renderOutsideInDocument, resolveOutsideInLayout, withOutsideInMarkdownEditing, withOutsideInMetadata } from './outside-in/index.js';
 export { Z as ZipSafetyError, a as ZipSafetyErrorCode, b as ZipSafetyErrorOptions, c as ZipSafetyLimits } from './zipLimits-BOKCB7qk.js';
-export { H as HtmlExportOptions, a as HtmlImportOptions, c as collectImagePaths, h as htmlToMarkdown, b as htmlToMarkdownDoc, d as htmlToMarkdownDocSync } from './import-BQFf0iEG.js';
+export { H as HtmlExportOptions, a as HtmlImportOptions, c as collectImagePaths, h as htmlToMarkdown, b as htmlToMarkdownDoc, d as htmlToMarkdownDocSync } from './import-B0gBYUmd.js';
 export { P as PptxExportOptions, a as PptxImportOptions, d as docToPptx, m as markdownDocToPptx, p as pptxToMarkdownDoc } from './import-C16E8Y4X.js';
 export { X as XlsxExportOptions, a as XlsxImportOptions, d as docToXlsx, m as markdownDocToXlsx, x as xlsxToMarkdownDoc } from './export-D9msROJS.js';
 import '@bendyline/squisq/schemas';

package/dist/index.js

@@ -3,7 +3,25 @@ import {
   markdownDocToEpub
 } from "./chunk-KN62QJYK.js";
 import {
-  BUILTIN_FORMAT_IDS,
+  BUILTIN_FORMAT_IDS
+} from "./chunk-2P5HJAQL.js";
+import {
+  inferThemeFromFile
+} from "./chunk-KMBBO5H7.js";
+import {
+  OUTSIDE_IN_FORMAT_IDS,
+  OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY,
+  chooseOutsideInMarkdownPath,
+  importOutsideInDocument,
+  isOutsideInMarkdownEditingEnabled,
+  isOutsideInTargetPath,
+  readOutsideInMetadata,
+  renderOutsideInDocument,
+  resolveOutsideInLayout,
+  withOutsideInMarkdownEditing,
+  withOutsideInMetadata
+} from "./chunk-BVGJ54NV.js";
+import {
   DEFAULT_CONVERSION_LIMITS,
   convert,
   createRegistry,
@@ -11,10 +29,7 @@ import {
   defaultRegistry,
   prepareConversion,
   resolveConversionLimits
-} from "./chunk-24VREWAZ.js";
-import {
-  inferThemeFromFile
-} from "./chunk-KMBBO5H7.js";
+} from "./chunk-DNGNODJP.js";
 import {
   ConversionError
 } from "./chunk-KXOZMWBS.js";
@@ -33,7 +48,7 @@ import {
   markdownDocToPptx,
   pptxToDoc,
   pptxToMarkdownDoc
-} from "./chunk-RVGOYKVW.js";
+} from "./chunk-XCV242AO.js";
 import "./chunk-6N2J7C2B.js";
 import "./chunk-DWNNYO5H.js";
 import {
@@ -72,14 +87,17 @@ import {
   htmlToMarkdown,
   htmlToMarkdownDoc,
   htmlToMarkdownDocSync
-} from "./chunk-A5Y23TAF.js";
+} from "./chunk-N2ZN3MQN.js";
 import "./chunk-6RQOV3B3.js";
 import "./chunk-AONELFLA.js";
 export {
   BUILTIN_FORMAT_IDS,
   ConversionError,
   DEFAULT_CONVERSION_LIMITS,
+  OUTSIDE_IN_FORMAT_IDS,
+  OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY,
   ZipSafetyError,
+  chooseOutsideInMarkdownPath,
   collectImagePaths,
   compileExtractedTheme,
   configurePdfWorker,
@@ -101,7 +119,10 @@ export {
   htmlToMarkdown,
   htmlToMarkdownDoc,
   htmlToMarkdownDocSync,
+  importOutsideInDocument,
   inferThemeFromFile,
+  isOutsideInMarkdownEditingEnabled,
+  isOutsideInTargetPath,
   markdownDocToCsv,
   markdownDocToDocx,
   markdownDocToEpub,
@@ -114,7 +135,12 @@ export {
   pptxToDoc,
   pptxToMarkdownDoc,
   prepareConversion,
+  readOutsideInMetadata,
+  renderOutsideInDocument,
   resolveConversionLimits,
+  resolveOutsideInLayout,
+  withOutsideInMarkdownEditing,
+  withOutsideInMetadata,
   xlsxToDoc,
   xlsxToMarkdownDoc
 };

package/dist/outside-in/index.d.ts

@@ -0,0 +1,117 @@
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { c as ConvertOptions, b as ConversionResult } from '../types-HDLauUoa.js';
+import '@bendyline/squisq/schemas';
+import '@bendyline/squisq/transform';
+import '../docx/index.js';
+import '../reader-B_m1aKZC.js';
+import '../zipLimits-BOKCB7qk.js';
+import '../import-C16E8Y4X.js';
+import '../export-D9msROJS.js';
+import '../csv/index.js';
+import '../pdf/index.js';
+import '../import-B0gBYUmd.js';
+import '../epub/index.js';
+import '../container/index.js';
+
+/**
+ * Outside-in document editing.
+ *
+ * A rendered document remains the user-facing file while its editable
+ * Markdown source and media live in a hidden sibling companion directory:
+ *
+ *   Tucson.pptx
+ *   Tucson_files/
+ *     tucson.md
+ *     hero.png
+ *     .versions/
+ *
+ * Hosts own filesystem authority and transaction ordering. This module owns
+ * the portable path/frontmatter contract plus registry-backed import/export.
+ */
+
+declare const OUTSIDE_IN_FORMAT_IDS: readonly ["html", "docx", "pdf", "pptx", "xlsx"];
+type OutsideInFormatId = (typeof OUTSIDE_IN_FORMAT_IDS)[number];
+declare const OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY = "squisq-updatefrommarkdown";
+interface OutsideInLayout {
+    /** User-facing rendered file, relative to the host's workspace root. */
+    targetPath: string;
+    /** Registry format used to import and regenerate the target. */
+    format: OutsideInFormatId;
+    /** Parent directory of the rendered file. Empty at workspace root. */
+    parentDirectory: string;
+    /** Case-preserving rendered filename without its final extension. */
+    stem: string;
+    /** Case-preserving `<stem>_files` folder name. */
+    companionName: string;
+    /** Full workspace-relative companion directory. */
+    companionDirectory: string;
+    /** Slugged Markdown filename inside the companion directory. */
+    markdownFilename: string;
+    /** Full workspace-relative Markdown source path. */
+    markdownPath: string;
+    /** Rendered target path as stored relative to the Markdown source. */
+    relativeTargetPath: string;
+    /** Hidden directory containing the immutable pre-edit rendered file. */
+    backupDirectory: string;
+    /** Stable filename for the pre-edit rendered file. */
+    backupFilename: string;
+    /** Full workspace-relative path to the pre-edit rendered file. */
+    backupPath: string;
+}
+interface OutsideInMetadata {
+    version: 1;
+    format: OutsideInFormatId;
+    target: string;
+    /** Only an exact boolean true authorizes Markdown-driven regeneration. */
+    updateFromMarkdown: boolean;
+}
+interface ImportedOutsideInDocument {
+    layout: OutsideInLayout;
+    markdown: string;
+    /** Imported media container. Hosts copy its non-Markdown members into the companion folder. */
+    container: ContentContainer;
+    /** Non-fatal fidelity notes from theme/layout inference. */
+    warnings: string[];
+}
+interface RenderOutsideInOptions extends ConvertOptions {
+    /** Required for HTML targets, which intentionally reference a shared runtime. */
+    html?: {
+        /** URL from the rendered HTML file to `_squisq/squisq-player.js`. */
+        playerScriptPath: string;
+        /** URL from the rendered HTML file to its companion media folder. */
+        basePath?: string;
+    };
+}
+/** Resolve the canonical companion/source layout for a supported rendered file. */
+declare function resolveOutsideInLayout(targetPath: string): OutsideInLayout | null;
+declare function isOutsideInTargetPath(path: string): boolean;
+/**
+ * Pick an existing source inside the companion directory. Canonical slug wins;
+ * a sole root-level Markdown file is accepted for older/manual layouts.
+ */
+declare function chooseOutsideInMarkdownPath(layout: OutsideInLayout, paths: readonly string[]): string | null;
+/** Read outside-in metadata without interpreting the output path as authority. */
+declare function readOutsideInMetadata(source: string): OutsideInMetadata | null;
+/** Add or refresh the portable relationship while preserving unrelated frontmatter. */
+declare function withOutsideInMetadata(source: string, layout: OutsideInLayout): string;
+/** True only when the companion explicitly opts into rendered-file updates. */
+declare function isOutsideInMarkdownEditingEnabled(source: string | MarkdownDocument): boolean;
+/**
+ * Opt a companion into or out of Markdown-driven regeneration while keeping
+ * the portable target relationship current.
+ */
+declare function withOutsideInMarkdownEditing(source: string, layout: OutsideInLayout, enabled?: boolean): string;
+/** Import a rendered target into editable Markdown plus any extracted media. */
+declare function importOutsideInDocument(source: {
+    data: ArrayBuffer | Uint8Array;
+    targetPath: string;
+}, options?: ConvertOptions): Promise<ImportedOutsideInDocument>;
+/** Regenerate the user-facing target from its Markdown source. */
+declare function renderOutsideInDocument(source: {
+    markdown: string | MarkdownDocument;
+    targetPath: string;
+    container?: ContentContainer;
+}, options?: RenderOutsideInOptions): Promise<ConversionResult>;
+
+export { type ImportedOutsideInDocument, OUTSIDE_IN_FORMAT_IDS, OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY, type OutsideInFormatId, type OutsideInLayout, type OutsideInMetadata, type RenderOutsideInOptions, chooseOutsideInMarkdownPath, importOutsideInDocument, isOutsideInMarkdownEditingEnabled, isOutsideInTargetPath, readOutsideInMetadata, renderOutsideInDocument, resolveOutsideInLayout, withOutsideInMarkdownEditing, withOutsideInMetadata };

package/dist/outside-in/index.js

@@ -0,0 +1,29 @@
+import {
+  OUTSIDE_IN_FORMAT_IDS,
+  OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY,
+  chooseOutsideInMarkdownPath,
+  importOutsideInDocument,
+  isOutsideInMarkdownEditingEnabled,
+  isOutsideInTargetPath,
+  readOutsideInMetadata,
+  renderOutsideInDocument,
+  resolveOutsideInLayout,
+  withOutsideInMarkdownEditing,
+  withOutsideInMetadata
+} from "../chunk-BVGJ54NV.js";
+import "../chunk-DNGNODJP.js";
+import "../chunk-KXOZMWBS.js";
+import "../chunk-7AWFHP5U.js";
+export {
+  OUTSIDE_IN_FORMAT_IDS,
+  OUTSIDE_IN_UPDATE_FROM_MARKDOWN_KEY,
+  chooseOutsideInMarkdownPath,
+  importOutsideInDocument,
+  isOutsideInMarkdownEditingEnabled,
+  isOutsideInTargetPath,
+  readOutsideInMetadata,
+  renderOutsideInDocument,
+  resolveOutsideInLayout,
+  withOutsideInMarkdownEditing,
+  withOutsideInMetadata
+};

package/dist/pptx/index.js

@@ -4,7 +4,7 @@ import {
   pptxToContainer,
   pptxToDoc,
   pptxToMarkdownDoc
-} from "../chunk-RVGOYKVW.js";
+} from "../chunk-XCV242AO.js";
 import {
   analyzePptxLayouts,
   inspectPptxLayouts

package/dist/registry/index.d.ts

@@ -1,173 +1,19 @@
-import { Doc, ThemeRegistry } from '@bendyline/squisq/schemas';
-import { TransformStyleInput, TransformStyleRegistry } from '@bendyline/squisq/transform';
-import { ParseOptions, StringifyOptions, MarkdownDocument } from '@bendyline/squisq/markdown';
-import { ContentContainer } from '@bendyline/squisq/storage';
-import { DocxImportOptions, DocxExportOptions } from '../docx/index.js';
-import { a as PptxImportOptions, P as PptxExportOptions } from '../import-C16E8Y4X.js';
-import { a as XlsxImportOptions, X as XlsxExportOptions } from '../export-D9msROJS.js';
-import { CsvImportOptions, CsvExportOptions } from '../csv/index.js';
-import { PdfImportOptions, PdfExportOptions } from '../pdf/index.js';
-import { a as HtmlImportOptions, H as HtmlExportOptions } from '../import-BQFf0iEG.js';
-import { EpubExportOptions } from '../epub/index.js';
-import { ContainerToZipOptions } from '../container/index.js';
-import { c as ZipSafetyLimits } from '../zipLimits-BOKCB7qk.js';
+import { f as FormatId, g as FormatRegistry, F as FormatDefinition, d as ConvertSource, c as ConvertOptions, b as ConversionResult, P as PreparedConversion } from '../types-HDLauUoa.js';
+export { B as BUILTIN_FORMAT_IDS, a as BuiltinFormatOptions, C as ConversionLimits, D as DEFAULT_CONVERSION_LIMITS, e as DbkFormatOptions, M as MarkdownFormatOptions, N as NormalizedInput, h as PreparedExportOptions, r as resolveConversionLimits } from '../types-HDLauUoa.js';
+import '@bendyline/squisq/schemas';
+import '@bendyline/squisq/transform';
+import '@bendyline/squisq/markdown';
+import '@bendyline/squisq/storage';
+import '../docx/index.js';
 import '../reader-B_m1aKZC.js';
-
-interface ConversionLimits {
-    maxInputBytes: number;
-    maxMarkdownBytes: number;
-    maxMarkdownNodes: number;
-    maxMarkdownDepth: number;
-    maxTableCells: number;
-    maxBlocks: number;
-    maxBlockDepth: number;
-    maxDurationSeconds: number;
-    maxAudioSegments: number;
-}
-declare const DEFAULT_CONVERSION_LIMITS: Readonly<ConversionLimits>;
-declare function resolveConversionLimits(limits?: Partial<ConversionLimits>): ConversionLimits;
-
-/**
- * Format registry — shared types.
- *
- * The registry is the programmatic heart of `convert()`: it maps a small set of
- * format ids (`md`, `docx`, `pdf`, …) to `FormatDefinition`s, each of which
- * knows how to import to / export from squisq's markdown + Doc model. Every
- * converter module is loaded lazily via `import()` inside the definition
- * methods, so pulling in the registry never eagerly bundles heavy converters.
- */
-
-/** A format identifier (e.g. `'docx'`). Strings so hosts can register their own. */
-type FormatId = string;
-/** The built-in formats the default registry ships with. */
-declare const BUILTIN_FORMAT_IDS: readonly ["md", "docx", "pdf", "pptx", "xlsx", "csv", "html", "htmlzip", "epub", "dbk"];
-/** The bytes + metadata produced by a successful export. */
-interface ConversionResult {
-    /** Encoded output bytes. */
-    bytes: Uint8Array;
-    /** MIME type of the output. */
-    mimeType: string;
-    /** A sensible download filename (`<baseName>.<ext>`). */
-    suggestedFilename: string;
-    /** Non-fatal notes accumulated during conversion (may be empty). */
-    warnings: string[];
-}
-interface MarkdownFormatOptions {
-    parse?: ParseOptions;
-    stringify?: StringifyOptions;
-}
-/** Resource limits applied when importing a DBK/ZIP container. */
-type DbkFormatOptions = ZipSafetyLimits & ContainerToZipOptions;
-/**
- * Strongly typed option bags for built-in formats. Import and export options
- * share a bag because a single conversion may use the format on either side.
- * Custom registries may add arbitrary keys through the intersection used by
- * {@link ConvertOptions.formatOptions}.
- */
-interface BuiltinFormatOptions {
-    md: MarkdownFormatOptions;
-    docx: DocxImportOptions & DocxExportOptions;
-    pptx: PptxImportOptions & PptxExportOptions;
-    xlsx: XlsxImportOptions & XlsxExportOptions;
-    csv: CsvImportOptions & CsvExportOptions;
-    pdf: PdfImportOptions & PdfExportOptions;
-    html: HtmlImportOptions & Partial<Omit<HtmlExportOptions, 'playerScript'>>;
-    htmlzip: Partial<Omit<HtmlExportOptions, 'playerScript'>>;
-    epub: EpubExportOptions;
-    dbk: DbkFormatOptions;
-}
-/**
- * A source normalized into every shape an exporter might need. `doc` is always
- * present; `markdownDoc` is present when the source was markdown-shaped (an
- * exporter that wants markdown but finds none derives it from `doc`).
- */
-interface NormalizedInput {
-    doc: Doc;
-    markdownDoc?: MarkdownDocument;
-    container: ContentContainer;
-    baseName: string;
-}
-/** Options threaded through `convert()` and into every format method. */
-interface ConvertOptions {
-    /** Cancel normalization, transformation, or export at the next bounded work boundary. */
-    signal?: AbortSignal;
-    /** Cross-format safety limits. Pass false only for explicitly trusted input. */
-    limits?: Partial<ConversionLimits> | false;
-    /** Registry to resolve formats against. Defaults to `defaultRegistry()`. */
-    registry?: FormatRegistry;
-    /** Explicit source format id (skips extension/byte sniffing). */
-    from?: FormatId;
-    /** Theme id to apply to the exported document. */
-    themeId?: string;
-    /** Explicit caller-owned registry for non-document custom themes. */
-    themeRegistry?: ThemeRegistry;
-    /** Built-in/registry id or call-scoped style to apply before export. */
-    transformStyle?: TransformStyleInput;
-    /** Explicit caller-owned registry used to resolve transform style ids. */
-    transformRegistry?: TransformStyleRegistry;
-    /** Content-aware auto-templating when deriving a Doc from markdown. */
-    autoTemplates?: boolean;
-    /** Title hint for exporters that expose document metadata. */
-    title?: string;
-    /** Lazily resolve the standalone player IIFE bundle (required for HTML export). */
-    resolvePlayerScript?: () => Promise<string>;
-    /** Typed per-format options for built-ins; custom format ids remain extensible. */
-    formatOptions?: Partial<BuiltinFormatOptions> & Record<FormatId, unknown>;
-}
-/** Target-only options accepted after a source has already been normalized and transformed. */
-type PreparedExportOptions = Pick<ConvertOptions, 'signal' | 'title' | 'resolvePlayerScript' | 'formatOptions'>;
-/**
- * An opaque normalized conversion snapshot. The source and transform pipeline
- * has already completed; each call exports that same snapshot to one target.
- */
-interface PreparedConversion {
-    convert(to: FormatId, options?: PreparedExportOptions): Promise<ConversionResult>;
-}
-/**
- * How a format's exporter treats Squisq template annotations: `rendered`
- * materializes template visuals into the output, `preserved` keeps annotations
- * intact for round-tripping, and `ignored` flattens blocks to semantic content
- * so annotations have no effect on the exported result.
- */
-type TemplateAnnotationHandling = 'rendered' | 'preserved' | 'ignored';
-/** Describes how a single format imports to / exports from the squisq model. */
-interface FormatDefinition {
-    id: FormatId;
-    label: string;
-    mimeType: string;
-    extensions: readonly string[];
-    /** Exporter treatment of template annotations. Absent means unspecified. */
-    templateAnnotationHandling?: TemplateAnnotationHandling;
-    /** Import raw bytes to a MarkdownDocument. */
-    importDoc?(data: ArrayBuffer, options: ConvertOptions): Promise<MarkdownDocument>;
-    /** Import raw bytes to a ContentContainer (markdown + extracted media). */
-    importContainer?(data: ArrayBuffer, options: ConvertOptions): Promise<ContentContainer>;
-    /** Export a normalized input to bytes. */
-    exportDoc?(input: NormalizedInput, options: ConvertOptions): Promise<ConversionResult>;
-}
-/** A mutable collection of format definitions keyed by id. */
-interface FormatRegistry {
-    register(def: FormatDefinition): void;
-    get(id: FormatId): FormatDefinition | undefined;
-    byExtension(ext: string): FormatDefinition | undefined;
-    list(): FormatDefinition[];
-}
-/** The three shapes `convert()` accepts as a source. */
-type ConvertSource = {
-    kind: 'bytes';
-    data: ArrayBuffer | Uint8Array;
-    filename?: string;
-} | {
-    kind: 'markdown';
-    markdown: string | MarkdownDocument;
-    container?: ContentContainer;
-    baseName?: string;
-} | {
-    kind: 'doc';
-    doc: Doc;
-    container?: ContentContainer;
-    baseName?: string;
-};
+import '../zipLimits-BOKCB7qk.js';
+import '../import-C16E8Y4X.js';
+import '../export-D9msROJS.js';
+import '../csv/index.js';
+import '../pdf/index.js';
+import '../import-B0gBYUmd.js';
+import '../epub/index.js';
+import '../container/index.js';
 
 /**
  * Structured error for the format registry / `convert()` pipeline.
@@ -241,4 +87,4 @@ declare function prepareConversion(source: ConvertSource, options?: ConvertOptio
  */
 declare function convert(source: ConvertSource, to: FormatId, options?: ConvertOptions): Promise<ConversionResult>;
 
-export { BUILTIN_FORMAT_IDS, type BuiltinFormatOptions, ConversionError, type ConversionErrorCode, type ConversionErrorOptions, type ConversionLimits, type ConversionResult, type ConvertOptions, type ConvertSource, DEFAULT_CONVERSION_LIMITS, type DbkFormatOptions, type FormatDefinition, type FormatId, type FormatRegistry, type MarkdownFormatOptions, type NormalizedInput, type PreparedConversion, type PreparedExportOptions, convert, createRegistry, defaultFormats, defaultRegistry, prepareConversion, resolveConversionLimits };
+export { ConversionError, type ConversionErrorCode, type ConversionErrorOptions, ConversionResult, ConvertOptions, ConvertSource, FormatDefinition, FormatId, FormatRegistry, PreparedConversion, convert, createRegistry, defaultFormats, defaultRegistry, prepareConversion };

package/dist/registry/index.js

@@ -1,5 +1,7 @@
 import {
-  BUILTIN_FORMAT_IDS,
+  BUILTIN_FORMAT_IDS
+} from "../chunk-2P5HJAQL.js";
+import {
   DEFAULT_CONVERSION_LIMITS,
   convert,
   createRegistry,
@@ -7,7 +9,7 @@ import {
   defaultRegistry,
   prepareConversion,
   resolveConversionLimits
-} from "../chunk-24VREWAZ.js";
+} from "../chunk-DNGNODJP.js";
 import {
   ConversionError
 } from "../chunk-KXOZMWBS.js";

package/dist/types-HDLauUoa.d.ts

@@ -0,0 +1,171 @@
+import { Doc, ThemeRegistry } from '@bendyline/squisq/schemas';
+import { TransformStyleInput, TransformStyleRegistry } from '@bendyline/squisq/transform';
+import { ParseOptions, StringifyOptions, MarkdownDocument } from '@bendyline/squisq/markdown';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { DocxImportOptions, DocxExportOptions } from './docx/index.js';
+import { a as PptxImportOptions, P as PptxExportOptions } from './import-C16E8Y4X.js';
+import { a as XlsxImportOptions, X as XlsxExportOptions } from './export-D9msROJS.js';
+import { CsvImportOptions, CsvExportOptions } from './csv/index.js';
+import { PdfImportOptions, PdfExportOptions } from './pdf/index.js';
+import { a as HtmlImportOptions, H as HtmlExportOptions } from './import-B0gBYUmd.js';
+import { EpubExportOptions } from './epub/index.js';
+import { ContainerToZipOptions } from './container/index.js';
+import { c as ZipSafetyLimits } from './zipLimits-BOKCB7qk.js';
+
+interface ConversionLimits {
+    maxInputBytes: number;
+    maxMarkdownBytes: number;
+    maxMarkdownNodes: number;
+    maxMarkdownDepth: number;
+    maxTableCells: number;
+    maxBlocks: number;
+    maxBlockDepth: number;
+    maxDurationSeconds: number;
+    maxAudioSegments: number;
+}
+declare const DEFAULT_CONVERSION_LIMITS: Readonly<ConversionLimits>;
+declare function resolveConversionLimits(limits?: Partial<ConversionLimits>): ConversionLimits;
+
+/**
+ * Format registry — shared types.
+ *
+ * The registry is the programmatic heart of `convert()`: it maps a small set of
+ * format ids (`md`, `docx`, `pdf`, …) to `FormatDefinition`s, each of which
+ * knows how to import to / export from squisq's markdown + Doc model. Every
+ * converter module is loaded lazily via `import()` inside the definition
+ * methods, so pulling in the registry never eagerly bundles heavy converters.
+ */
+
+/** A format identifier (e.g. `'docx'`). Strings so hosts can register their own. */
+type FormatId = string;
+/** The built-in formats the default registry ships with. */
+declare const BUILTIN_FORMAT_IDS: readonly ["md", "docx", "pdf", "pptx", "xlsx", "csv", "html", "htmlzip", "epub", "dbk"];
+/** The bytes + metadata produced by a successful export. */
+interface ConversionResult {
+    /** Encoded output bytes. */
+    bytes: Uint8Array;
+    /** MIME type of the output. */
+    mimeType: string;
+    /** A sensible download filename (`<baseName>.<ext>`). */
+    suggestedFilename: string;
+    /** Non-fatal notes accumulated during conversion (may be empty). */
+    warnings: string[];
+}
+interface MarkdownFormatOptions {
+    parse?: ParseOptions;
+    stringify?: StringifyOptions;
+}
+/** Resource limits applied when importing a DBK/ZIP container. */
+type DbkFormatOptions = ZipSafetyLimits & ContainerToZipOptions;
+/**
+ * Strongly typed option bags for built-in formats. Import and export options
+ * share a bag because a single conversion may use the format on either side.
+ * Custom registries may add arbitrary keys through the intersection used by
+ * {@link ConvertOptions.formatOptions}.
+ */
+interface BuiltinFormatOptions {
+    md: MarkdownFormatOptions;
+    docx: DocxImportOptions & DocxExportOptions;
+    pptx: PptxImportOptions & PptxExportOptions;
+    xlsx: XlsxImportOptions & XlsxExportOptions;
+    csv: CsvImportOptions & CsvExportOptions;
+    pdf: PdfImportOptions & PdfExportOptions;
+    html: HtmlImportOptions & Partial<Omit<HtmlExportOptions, 'playerScript'>>;
+    htmlzip: Partial<Omit<HtmlExportOptions, 'playerScript'>>;
+    epub: EpubExportOptions;
+    dbk: DbkFormatOptions;
+}
+/**
+ * A source normalized into every shape an exporter might need. `doc` is always
+ * present; `markdownDoc` is present when the source was markdown-shaped (an
+ * exporter that wants markdown but finds none derives it from `doc`).
+ */
+interface NormalizedInput {
+    doc: Doc;
+    markdownDoc?: MarkdownDocument;
+    container: ContentContainer;
+    baseName: string;
+}
+/** Options threaded through `convert()` and into every format method. */
+interface ConvertOptions {
+    /** Cancel normalization, transformation, or export at the next bounded work boundary. */
+    signal?: AbortSignal;
+    /** Cross-format safety limits. Pass false only for explicitly trusted input. */
+    limits?: Partial<ConversionLimits> | false;
+    /** Registry to resolve formats against. Defaults to `defaultRegistry()`. */
+    registry?: FormatRegistry;
+    /** Explicit source format id (skips extension/byte sniffing). */
+    from?: FormatId;
+    /** Theme id to apply to the exported document. */
+    themeId?: string;
+    /** Explicit caller-owned registry for non-document custom themes. */
+    themeRegistry?: ThemeRegistry;
+    /** Built-in/registry id or call-scoped style to apply before export. */
+    transformStyle?: TransformStyleInput;
+    /** Explicit caller-owned registry used to resolve transform style ids. */
+    transformRegistry?: TransformStyleRegistry;
+    /** Content-aware auto-templating when deriving a Doc from markdown. */
+    autoTemplates?: boolean;
+    /** Title hint for exporters that expose document metadata. */
+    title?: string;
+    /** Lazily resolve the standalone player IIFE bundle (required for HTML export). */
+    resolvePlayerScript?: () => Promise<string>;
+    /** Typed per-format options for built-ins; custom format ids remain extensible. */
+    formatOptions?: Partial<BuiltinFormatOptions> & Record<FormatId, unknown>;
+}
+/** Target-only options accepted after a source has already been normalized and transformed. */
+type PreparedExportOptions = Pick<ConvertOptions, 'signal' | 'title' | 'resolvePlayerScript' | 'formatOptions'>;
+/**
+ * An opaque normalized conversion snapshot. The source and transform pipeline
+ * has already completed; each call exports that same snapshot to one target.
+ */
+interface PreparedConversion {
+    convert(to: FormatId, options?: PreparedExportOptions): Promise<ConversionResult>;
+}
+/**
+ * How a format's exporter treats Squisq template annotations: `rendered`
+ * materializes template visuals into the output, `preserved` keeps annotations
+ * intact for round-tripping, and `ignored` flattens blocks to semantic content
+ * so annotations have no effect on the exported result.
+ */
+type TemplateAnnotationHandling = 'rendered' | 'preserved' | 'ignored';
+/** Describes how a single format imports to / exports from the squisq model. */
+interface FormatDefinition {
+    id: FormatId;
+    label: string;
+    mimeType: string;
+    extensions: readonly string[];
+    /** Exporter treatment of template annotations. Absent means unspecified. */
+    templateAnnotationHandling?: TemplateAnnotationHandling;
+    /** Import raw bytes to a MarkdownDocument. */
+    importDoc?(data: ArrayBuffer, options: ConvertOptions): Promise<MarkdownDocument>;
+    /** Import raw bytes to a ContentContainer (markdown + extracted media). */
+    importContainer?(data: ArrayBuffer, options: ConvertOptions): Promise<ContentContainer>;
+    /** Export a normalized input to bytes. */
+    exportDoc?(input: NormalizedInput, options: ConvertOptions): Promise<ConversionResult>;
+}
+/** A mutable collection of format definitions keyed by id. */
+interface FormatRegistry {
+    register(def: FormatDefinition): void;
+    get(id: FormatId): FormatDefinition | undefined;
+    byExtension(ext: string): FormatDefinition | undefined;
+    list(): FormatDefinition[];
+}
+/** The three shapes `convert()` accepts as a source. */
+type ConvertSource = {
+    kind: 'bytes';
+    data: ArrayBuffer | Uint8Array;
+    filename?: string;
+} | {
+    kind: 'markdown';
+    markdown: string | MarkdownDocument;
+    container?: ContentContainer;
+    baseName?: string;
+} | {
+    kind: 'doc';
+    doc: Doc;
+    container?: ContentContainer;
+    baseName?: string;
+};
+
+export { BUILTIN_FORMAT_IDS as B, type ConversionLimits as C, DEFAULT_CONVERSION_LIMITS as D, type FormatDefinition as F, type MarkdownFormatOptions as M, type NormalizedInput as N, type PreparedConversion as P, type BuiltinFormatOptions as a, type ConversionResult as b, type ConvertOptions as c, type ConvertSource as d, type DbkFormatOptions as e, type FormatId as f, type FormatRegistry as g, type PreparedExportOptions as h, resolveConversionLimits as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-formats",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "description": "Document format converters — DOCX, PDF, OOXML import/export",
   "license": "MIT",
   "author": "Bendyline",
@@ -97,6 +97,11 @@
       "types": "./dist/infer/index.d.ts",
       "import": "./dist/infer/index.js",
       "default": "./dist/infer/index.js"
+    },
+    "./outside-in": {
+      "types": "./dist/outside-in/index.d.ts",
+      "import": "./dist/outside-in/index.js",
+      "default": "./dist/outside-in/index.js"
     }
   },
   "scripts": {
@@ -107,7 +112,7 @@
   "dependencies": {
     "@pdf-lib/fontkit": "1.1.1",
     "@pdf-lib/upng": "1.0.1",
-    "@xmldom/xmldom": "0.9.10",
+    "@xmldom/xmldom": "0.9.11",
     "@bendyline/squisq": "2.7.1",
     "jszip": "3.10.1",
     "pdf-lib": "1.17.1",