script.pub

Format registry

ScriptPub tooling is a text-library manager first: a library may hold works in any format the registry knows — not just .spub.* files. The format registry is one machine-readable table describing every such format and what the tooling can do with it. Everything that decides by file type keys off it: the library scan defaults, import pickers, the open-a-work dispatch, export menus, and the round-trip guard when editing a foreign file.

The entry shape

FormatEntry = {
  id: string,             // "md", "epub", … — for text syntaxes, the adapter id
  label: string,          // "Markdown", "EPUB" — pickers and library badges
  extensions: string[],   // most specific first; the first is the write default
  mediaType: string,
  encoding: "text" | "binary",
  read:  "adapter" | "codec" | "view",
  write: "adapter" | "codec" | "none",
  embedsConfig: boolean,  // can carry an embedded config
  needsConfig: boolean,   // parsing needs a companion / default config
}

Three read tiers:

  • adapter — a synchronous text syntax adapter (parse/serialize against the canonical model). These formats round-trip.
  • codec — an asynchronous binary decode into the model (EPUB, DOCX). The decoders live outside the format engine; the registry only declares the capability.
  • view — no model conversion at all: the file renders as itself (PDF, through the browser’s own viewer).

write is the round-trip guard: editing a work whose source of truth is a foreign file serializes back through its adapter (write: "adapter"); a format that can’t round-trip ("codec" / "none") prompts to convert to SPub before editing.

The registry

id Extensions Encoding Read Write Embeds config Needs config
html .spub.html, .html text adapter adapter yes no
json .spub.json, .json text adapter adapter yes (is it) no
md .md text adapter adapter frontmatter yes
fountain .fountain text adapter adapter no yes
fdx .fdx text adapter adapter no yes
txt .txt text adapter adapter no yes
epub .epub binary codec codec no no
docx .docx binary codec none no no
pdf .pdf binary view none no no

A path resolves to its format by longest extension match (formatForPath) — Work.spub.html is the html entry via .spub.html, and the .spub.* spelling is what marks a file as canonical SPub (isSpubPath); a plain .md or .epub is a foreign work the library still lists, reads, and can convert.

Consequences

  • Library scanning. The default scan include derives from this table — every registry format lists as a work, so a folder of Markdown chapters or DRM-free EPUBs behaves as a library with no configuration. Plain .html/.json stay opt-in (a library’s own index.html must not list as a work).
  • Reading a foreign work parses it under its companion config when one sits beside the file, else a per-syntax default preset (screenplay for fountain/fdx, prose for md/txt).
  • Converting to SPub is always available and never required: in place, as a sibling .spub.html, as a companion .spub.json (the file stays untouched), or by embedding a config into the host file (formats with embedsConfig).