preview.proto reference

Generated page. It is built from the comments in core/proto/preview.proto, the one schema that joins parsers, viewers and the hosts (package poka.preview). Change a comment in the proto and run python3 scripts/gen-proto-reference.py; never edit this page by hand. The canonical copy is in poka-interfaces; poka-parsers and poka-viewers vendor it byte for byte.

The schema has 63 messages and 6 enums.

How the messages fit together

• A host sends a PreviewRequest on a module's stdin.
• A monolithic module answers with a PreviewResponse.
• A composed parser answers with one *Ast message instead. The host pipes it to the shared viewer named in the parser's manifest, takes the viewer's HTML and wraps it in an HtmlPreview. Parser and viewer never call each other.

Which viewer takes which AST

poka-3d-viewer is never run by the host: both hosts decode Scene3DAst themselves and hand the meshes to the frontend Three.js viewer.

Messages

PreviewRequest

The request a host writes to a module's stdin, read to EOF and decoded. A monolithic module or a composed parser receives it. A shared viewer does not: it receives the parser's *Ast instead.

FileFacts

Per-format facts for the file-information panel (#182): what a parser knows about the file it just read, as a short list of key/value pairs shown beside the preview. The keys are the parser's own ("Units", "Entities", "Sheets"); hint is an optional qualifier or unit ("mm", "1-based"). One entry shape serves both the format-specific facts a parser adds and the file's own facts the host gathers (name, size, extension, dates, the previewing handler, the parse time) — the host fills those itself and asks no parser.

Additive and open-ended: a parser adds only the entries its format genuinely knows, and omits the rest. No entry is ever invented; an empty FileFacts is correct for a parser that cannot fill it.

FactEntry

One fact. value is already stringified for reading.

IntegrityCheck

One structural check a parser made against the file's own declarations (#354). Strictly about the FILE, never about the preview: the truncated flags on TableAst / TextAst / TreeAst mean "the preview was capped" and must not be reported here. A parser that reads only a prefix of a large file (a read cap) must not report what lies past the cap as missing. Only what the file itself states is compared: a header's record count, an entry's offset and size, a declared element count.

ImagePreview

A decoded raster image that the frontend shows directly.

TextPreview

Plain or syntax-highlighted text.

SvgPreview

Inline SVG markup, shown in an isolated frame.

HtmlPreview

HTML shown in a sandboxed frame. When a parser is paired with a viewer, the host wraps the viewer's HTML output in this message.

PdfPreview

A PDF document.

ModelPreview

A 3D model for the frontend viewer: either the file on disk or bytes the module generated.

DwgEntity

A parsed 2D/3D CAD vector entity. Despite the Dwg* naming (kept for historical reasons), this shape describes any structured CAD drawing — both .dwg (poka-dwg) and .dxf (poka-dxf) emit it, and the same Three.js viewer in the host renders both.

nums is a flat, kind-specific coordinate list:

Line:        [x1, y1, z1, x2, y2, z2]
Circle:      [cx, cy, cz, r]
Arc:         [cx, cy, cz, r, start_angle_rad, end_angle_rad]
LwPolyline:  [x1, y1, x2, y2, ...]           (planar, z = 0)
Polyline3D:  [x1, y1, z1, x2, y2, z2, ...]
Point:       [x, y, z]
Ellipse:     [cx, cy, cz, ax, ay, az, ratio, start_param, end_param]
Solid:       [x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4]
Ray / XLine: [bx, by, bz, dx, dy, dz]

Keeping it flat avoids a oneof-per-shape explosion and matches the JSON-ish shape the Three.js viewer wants to walk.

DwgDrawing

A CAD drawing for the host's Three.js CAD viewer, as a list of DwgEntity.

ProgressUpdate

A progress report (TYPE_PROGRESS). No host or module in the four repositories sets or reads it today.

DataChunk

One piece of a result returned in several parts (TYPE_CHUNK). No host or module in the four repositories sets or reads it today.

ErrorResponse

A module's failure. The host reports it as an ExtensionError result with the same code, message and recoverable flag.

PreviewResponse

What a monolithic module writes to its stdout: exactly one arm of response, with type saying which. A composed parser answers with an *Ast instead, except to ask for tabs, when it sends this message with type TYPE_MULTIVIEW.

MultiView

A file that has several distinct representations (e.g. an InstalSystem .isproj → 3D model / 2D plan / project data) emits this; the frontend renders a tab bar and dispatches each view through its normal renderer.

MultiViewItem

One tab of a MultiView: a title and one view.

TableAst

Format-agnostic tabular data: shared by CSV, DBF, SQLite, Avro records, etc. Cells are pre-stringified at the parser; type hints (Numeric, Date, …) are optional per-column and inform viewer styling but never parsing.

Decoded by poka-table-viewer.

TableColumn

A column header with an optional type hint.

TableRow

One row, already stringified.

WorkbookAst

A spreadsheet document with more than one sheet: Apple Numbers, and any future format where one file holds several named grids. TableAst stays the single-grid shape that CSV, DBF, parquet and the rest emit; a workbook is its own message so those parsers and viewers are untouched.

preview_image carries the document's own rendered thumbnail when it has one (Numbers packages ship a preview.jpg of the first sheet). The viewer shows it beside the sheet tabs; it is not a substitute for the grids.

Decoded by poka-workbook-viewer.

WorkbookSheet

One named sheet, holding one or more tables.

TableLook

A spreadsheet's own formatting: a palette of cell styles, the cells that wear one or carry a note (the formula behind a computed value), column widths and merged ranges. Rows and columns index the TableAst's rows and cells, from 0.

CellLook

The style and note of one cell.

CellRange

A rectangle of cells.

CellStyle

How one cell is drawn: font, colours, alignment and borders.

CellBorder

One edge of a cell.

SlideDeckAst

A slide deck: Keynote today. Each slide carries the text on it, with the title kept apart so a viewer can lay a slide out as a slide rather than as a paragraph of everything at once.

Slides do not carry their own rendered image — an iWork package ships one thumbnail for the document, in preview_image, and nothing per slide. x/y/width/height on a text block are fractions of the slide, and are all zero when the parser could not resolve a shape's geometry; a viewer treats that as "lay it out yourself".

Decoded by poka-slide-viewer.

DeckSlide

One slide.

SlideText

A block of text on a slide, with its position.

TextAst

Long-form text: shared by BSP entity dumps, future code/log previews, CFG/INI files that don't fit a tree, anything where the content is one piece of formatted text rather than rows or a hierarchy.

Decoded by poka-text-viewer, poka-code-viewer.

TreeNode

Hierarchical data: directory trees (zip / 7z / tar / iso / cfb), XML hierarchies (vtk, gpx, kml, ipynb cells), Blender scene graphs, anything where nesting carries meaning.

TreeNode is recursive — proto3 allows this; prost generates Vec<TreeNode> for children. Cycles are not supported (it's a tree, not a graph).

TreeAst

A hierarchy of TreeNode, with an optional thumbnail and summary card.

Decoded by poka-tree-viewer.

Drawing2DAst

Pure 2D vector geometry: shared by map-shaped formats (gpx, kml, geojson) and any future extension whose primary preview is a flat drawing.

Not the same as DwgDrawing — that targets the host's Three.js CAD viewer (layers, ACI palette, 3D Polyline3D, real-unit pan/zoom). Drawing2DAst targets poka-vector-viewer, which renders inline SVG. Pick Drawing2DAst when the drawing is flat geometry; pick DwgDrawing when the drawing is CAD entities that benefit from the CAD viewer chrome.

Decoded by poka-vector-viewer.

Vector2DEntity

One drawing primitive. kind selects how the coordinate fields are read:

"point":    nums = [x, y]
"polyline": nums = [x1, y1, x2, y2, ...]
"circle":   nums = [cx, cy, r]
"polygon":  rings carry the outer boundary plus any holes; nums unused
"text":     nums = [x, y] anchor point; `text` carries the string
"image":    nums = [x0, y0, x1, y1] corners; `image_data` carries the raster

Style fields are optional; the viewer applies a default per kind if a field is empty/zero. stroke_width is in screen pixels, not source units.

PolygonRing

One closed boundary of a polygon: its outer edge, or a hole.

Scene3DAst

3D scene geometry: meshes of indexed triangles. Consumed by poka-3d-viewer which software-rasterises a single auto-framed view and returns it as PNG-in-HTML. Format-specific parsers (poka-stl, poka-obj, poka-ply, ...) emit this AST instead of carrying their own renderer.

Coordinate system: right-handed, Y-up. Vertices in source units; the viewer auto-fits the camera from min_*/max_* so absolute scale is irrelevant. Triangle winding is CCW (front-facing).

Materials, textures and named cameras are optional (fields 11-13, and Mesh3D 8-9): a parser that sets none of them gets the v1 behaviour — flat color_rgba, auto-framed camera. Still not carried: animations, lights, scene-graph transforms.

Decoded by poka-3d-viewer.

Light3D

A light source, in the scene's coordinates. No direction is carried: a spot or area light is placed, not aimed.

Material3D

A surface appearance, metallic-roughness PBR. Scalars are optional so "not recorded" (viewer default) is distinct from 0 (mirror-smooth, non-metal).

Texture3D

An embedded image in a format a browser decodes natively.

Camera3D

A named viewpoint, in the scene's coordinates (right-handed, Y-up).

Mesh3D

One mesh = packed positions + indices into them. Per-vertex normals are optional; the viewer computes flat per-triangle normals when missing. Positions are [x0, y0, z0, x1, y1, z1, ...] — flat for proto efficiency (avoids the per-vertex message overhead of a repeated Vec3 shape).

HexAst

---------- Hex dump: universal fallback for unrecognised binaries ----------

poka-hex-viewer renders these as a classic 16-byte-per-row dump with an address gutter and ASCII sidebar. content is a leading slice of the file; the parser is responsible for capping it (memory_mb in the manifest is the upper bound).

Decoded by poka-hex-viewer.

MetadataSection

---------- Metadata card / spec sheet ----------

Ordered key/value pairs grouped into sections. For formats whose primary preview value is structured metadata, not row/tree/text data (SQLite headers, KTX properties, font tables, EXIF, ICC profiles).

MetadataSection / MetadataEntry are intentionally reused by ImageWithMetaAst below — a single rendering of the metadata side panel works for both viewers.

MetadataEntry

One key/value pair of a metadata section.

MetadataCardAst

A spec sheet of titled key/value sections, optionally with a description and an audio or video player.

Decoded by poka-metadata-card-viewer.

ImageWithMetaAst

---------- Image + structured metadata side panel ----------

For formats where the visual preview matters AND the metadata is rich enough to warrant its own column: DICOM, NIfTI, RAW, PSD, FITS, and the PNG, JPEG, GIF and WebP previews. image_data is the image the module decoded: raw RGBA pixels (image_format "rgba"), which the viewer draws on a canvas so no browser codec is involved (poka-parsers#451), or, for the parsers not yet moved to that, a PNG, JPEG or WebP the module wrote.

Decoded by poka-image-with-meta-viewer.

Reserved field numbers: 15, 16, 17.

ImagePagesAst

Several pages of one image file (a multi-page TIFF; poka-parsers#242), each an ImageWithMetaAst, shown by poka-image-with-meta-viewer as tabs, or the frames of an animation, which it plays. The field numbers are 15 to 17, which ImageWithMetaAst reserves, so a viewer can take either message: bytes of a plain ImageWithMetaAst decode here as no pages, and bytes of this message never set an ImageWithMetaAst field. Page 1 carries the file's own sections (structure, page count); later pages carry only their own.

Decoded by poka-image-with-meta-viewer.

PdfPageAst

---------- PDF page ----------

One page of a PDF, rendered in wasm by poka-pdf (poka-parsers#450), or the module's request for the document's open password. Only the page asked for is rendered: the viewer posts {type:'poka:pdf:render', page, scale} or {type:'poka:pdf:password', password, page} to the host, which runs the parser again with PreviewRequest.params "page" (1-based), "scale" (pixels per PDF point) and "password". The host keeps a password in memory for the open file only; the module never writes it out, logs it or echoes it back.

It reuses two existing shapes: the pixels and the document's metadata are an ImageWithMetaAst, and each text run is a SlideText whose box is in fractions of the page.

Decoded by poka-pdf-viewer.

PdfPasswordRequest

The module's request for a PDF's open password (a password-protected file, poka-parsers#450). The viewer shows a prompt and answers with {type:'poka:pdf:password'}.

SvgAst

---------- SVG document (poka-parsers#452) ----------

One SVG drawn by the wasm module three ways, which the viewer switches between. Each way reuses an existing message as it is:

vector: the flattened picture as a Drawing2DAst of filled "polygon"
        entities (curves flattened, strokes outlined, even-odd fills and
        clip paths resolved to non-zero polygons), plus "image" entities
        for embedded rasters; y down, paint_in_order, bounds = the
        picture's width and height.
image:  pixels rendered in wasm at the size the request asked for
        (max_width × max_height, keeping the picture's aspect), as PNG.
source: the file's text, decoded to UTF-8.

A way the module could not produce is left unset and notes says why; notes also lists what a way leaves out (text with no bundled font, gradients drawn flat in vector mode).

Decoded by poka-svg-viewer.

DiffLine

---------- Unified diff ----------

One AST covers single-file and multi-file diffs (patches across many files). Hunks carry their original @@ -A,B +C,D @@ coordinates plus the contextual section header git emits.

DiffHunk

One hunk of a diff, with its original @@ coordinates.

DiffFile

The changes to one file.

DiffAst

A unified diff or patch: one or more files, each with hunks.

Decoded by poka-diff-viewer.

EbookChapter

---------- E-book preview ----------

Shape shared by mobi / epub / azw3 / fb2 / similar long-form-text container formats. Carries a cover image (parsers do the bytes → PNG/JPEG hop), structured bibliographic metadata, and one or more chapter excerpts as plain text (parsers strip the underlying XHTML).

Reuses MetadataSection / MetadataEntry from the metadata-card viewer so any structured extra fields (ISBN, publisher, language, dates, rights, subjects, etc.) render with the same grid layout the user already recognises.

EbookAst

An e-book: cover, bibliographic data and chapter excerpts.

Decoded by poka-ebook-viewer.

ChartAst

---------- Charts ----------

Numeric series over time, for simulation results (.eso) and weather (.epw, .wea). poka-chart-viewer draws each chart as inline SVG, so the preview needs no script. A chart file usually has more to it than its series, so the card and the table it would otherwise show ride along: sections is drawn above the charts as a metadata card and table below them, each only when set.

A separate message rather than series inside TableAst: TableAst is built as a struct literal by a hundred-odd parsers, and a new field there would touch every one of them.

The parser owns the point budget. A long series (8,760 hourly values or more) is cut into a fixed number of buckets, and each point is then a bucket: y is its mean and y_min/y_max its extremes, which the viewer draws as a band. source_points says how many values went in.

Decoded by poka-chart-viewer.

Chart

One chart: a titled set of line series, or a heat map.

ChartSeries

One line (or band) of a line chart.

ChartHeatmap

A rows × cols grid of values, e.g. hour of day × day of year. Row 0 is drawn at the top; the chart's x axis runs along the columns (its x_ticks values are column indices) and its y axis down the rows. NaN is a cell with no value. y_unit on the chart is the unit of the values.

AxisTick

A labelled mark on an axis.

Enums

IntegrityKind

IntegritySeverity

INFO is the zero value on purpose: a check that forgets its severity informs, it never warns. Trailing data is INFO, never WARNING (many formats legitimately append after their logical end, e.g. the data descriptor that ends a streamed ZIP entry).

ResponseType

LightKind

PrimitiveKind

ChartKind