feat(csv)!: open a csv as a spreadsheet

A csv rendered as a line list, because it was a text file with no decoder. It
is a table, and the library already knows how to render tables — the whole job
is to expose one.

`CsvDocument` is a one-sheet spreadsheet. The generic renderer walks it, and
every binding gets table rendering without a line of format-specific code.

Cells are not elements. The registry pattern the root `AGENTS.md` prescribes
costs an entry per element, and a sheet has one per cell, so a large file would
pay for millions before any were looked at. `ElementIdentifier` is 64 bits, so
an id *is* the coordinate — kind, row, column packed in — and the adapter
decodes rather than looks up. The consequence to respect is that a sheet's
cells are not reachable by walking; they come from `sheet_cell(column, row)`,
which is how the renderer asks for them anyway.

Everything reaches the data through `cell` and `dimensions`, so the index and
window work in `PLAN.md` can move in behind them later without the adapter
noticing.

The sheet is rectangular even where the file is not: a short row pads, a long
one widens. That is the counterpart to detection having stopped rejecting
ragged files.

`FileCategory::text` becomes `document`, so `is_text_file()` is now false for a
csv and `is_document_file()` true. Reading one as text stays available by
opening it as `FileType::text_file`, which is also the escape hatch when
detection was wrong about it being a csv at all.

An encoding `internal/encoding` cannot decode has no document: cell text has to
be UTF-8 by the time a binding sees it. The text path stays open to those
files.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QSgWdLTSLCWDeFvbVwZDVU

Author: andiwand

CMakeLists.txt

@@ -130,6 +130,7 @@ set(ODR_SOURCE_FILES
         "src/odr/internal/crypto/crypto_argon2.cpp"
         "src/odr/internal/crypto/crypto_util.cpp"
 
+        "src/odr/internal/csv/csv_document.cpp"
         "src/odr/internal/csv/csv_file.cpp"
         "src/odr/internal/csv/csv_util.cpp"
 

output/odr-public/output/csv/file_example_ODS_5000.csv/meta.json

@@ -1,5 +1,6 @@
 {
-    "fileCategory": "text",
+    "documentType": "spreadsheet",
+    "fileCategory": "document",
     "fileType": "csv",
     "isEncrypted": false
 }

src/odr/file.cpp

@@ -315,6 +315,10 @@ CsvFile CsvFile::from_file(const File &file, const CsvOptions &options,
 CsvFile::CsvFile(std::shared_ptr<internal::abstract::CsvFile> impl)
     : DecodedFile(impl), m_impl{std::move(impl)} {}
 
+DocumentType CsvFile::document_type() const { return m_impl->document_type(); }
+
+Document CsvFile::document() const { return Document(m_impl->document()); }
+
 CsvOptions CsvFile::options() const { return m_impl->options(); }
 
 CsvFile CsvFile::with_options(const CsvOptions &options) const {

src/odr/file.hpp

@@ -441,6 +441,12 @@ class CsvFile final : public DecodedFile {
 
   explicit CsvFile(std::shared_ptr<internal::abstract::CsvFile>);
 
+  /// @brief Always @ref DocumentType::spreadsheet.
+  [[nodiscard]] DocumentType document_type() const;
+  /// @brief The csv as a one-sheet spreadsheet.
+  /// @throws UnsupportedTextEncoding if the encoding cannot be decoded.
+  [[nodiscard]] Document document() const;
+
   /// @brief The options in use, every field resolved.
   [[nodiscard]] CsvOptions options() const;
 

src/odr/internal/abstract/file.hpp

@@ -67,16 +67,6 @@ class TextFile : public DecodedFile {
   [[nodiscard]] virtual TextEncoding encoding() const noexcept = 0;
 };
 
-class CsvFile : public TextFile {
-public:
-  /// The options in use, every field resolved.
-  [[nodiscard]] virtual CsvOptions options() const = 0;
-
-  /// The same file read with @p options.
-  [[nodiscard]] virtual std::shared_ptr<CsvFile>
-  with_options(const CsvOptions &options) const = 0;
-};
-
 class ImageFile : public DecodedFile {
 public:
   [[nodiscard]] FileCategory file_category() const noexcept final {
@@ -106,6 +96,22 @@ class DocumentFile : public DecodedFile {
   [[nodiscard]] virtual std::shared_ptr<Document> document() const = 0;
 };
 
+/// A csv is a document, not a text file: it decodes to a one-sheet
+/// spreadsheet. Reading it as text is still available by opening it as
+/// @ref FileType::text_file.
+class CsvFile : public DocumentFile {
+public:
+  /// The encoding the bytes were decoded with.
+  [[nodiscard]] virtual TextEncoding encoding() const noexcept = 0;
+
+  /// The options in use, every field resolved.
+  [[nodiscard]] virtual CsvOptions options() const = 0;
+
+  /// The same file read with @p options.
+  [[nodiscard]] virtual std::shared_ptr<CsvFile>
+  with_options(const CsvOptions &options) const = 0;
+};
+
 class PdfFile : public DecodedFile {
 public:
   [[nodiscard]] FileType file_type() const noexcept final {

src/odr/internal/csv/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md — `internal/csv`
+
+Read the root [`AGENTS.md`](../../../../AGENTS.md) first. This file covers what
+csv does differently, and why. The staged plan is in [`PLAN.md`](PLAN.md).
+
+## Cells are not elements
+
+The root `AGENTS.md` prescribes an `ElementRegistry`: a flat `std::vector` of
+elements, id = index + 1. **Csv does not use one**, deliberately.
+
+A registry costs an entry per element. A sheet has one per *cell*, so a file
+with a million rows would cost millions of entries before a single one is
+looked at — and `spreadsheet_limit` means the renderer will ask for ten
+thousand rows of them at most.
+
+`ElementIdentifier` is a `std::uint64_t`, which is room to spare:
+
+```
+63..61  kind    root | sheet | cell | text
+60..24  row     37 bits
+23..0   column  24 bits
+```
+
+So an id *is* the coordinate, and the adapter decodes rather than looks up.
+`null_element_id` is zero, so no kind may be.
+
+The consequence to respect: **a sheet's cells are not reachable by walking**.
+`element_first_child` of a sheet is `null_element_id`; cells come from
+`SheetAdapter::sheet_cell(column, row)`, which is how the renderer asks for
+them anyway (`html/document_element.cpp:163`).
+
+## Everything goes through `cell` and `dimensions`
+
+`CsvDocument` holds the whole file decoded, and the adapter never touches that
+storage — it calls `cell(column, row)` and `dimensions()`. That is the seam for
+the streaming work in `PLAN.md`'s last stage: an index and a window can move in
+behind those two without the adapter noticing.
+
+## Detection rejects; the parser does not
+
+Two jobs, two places, and mixing them is the mistake this module already made
+once.
+
+- `probe` is detection. It scores a bounded sample and may say "not a csv".
+  Its rules — at least two columns, no dangling quote in a complete file — are
+  *heuristics for recognising an unknown file*, not statements about validity.
+- `RecordReader` is parsing. Given a separator it is total: ragged rows, one
+  column, an empty file and a truncated quoted field all read as some csv.
+
+So a one-column csv is perfectly legitimate and `CsvOptions{.separator = ','}`
+reads it. `NoCsvFile` is a detection failure only. An incoherent dialect — a
+separator equal to the quote, a line break as a separator — is
+`std::invalid_argument`, a caller mistake rather than bad input.
+
+## A csv is a document
+
+`FileCategory::document`, `DocumentType::spreadsheet` — so `is_text_file()` is
+false for a csv and `is_document_file()` is true. Reading one as text is still
+available by opening it as `FileType::text_file`, which is also the escape
+hatch when detection was wrong about it being a csv at all.
+
+Text has to be UTF-8 by the time it reaches a cell: `Text::content()` returns
+`std::string` and every binding treats it as UTF-8. That is why an encoding
+`internal/encoding` cannot decode has no document at all, while the *text*
+rendering path stays open to it.