reftable.proto

§Raw schema

syntax = "proto3";

package eddocu.reftable.v3;

// ============================================================================
// REFTABLE SCHEMA - SEPARATION OF CONCERNS
// ============================================================================
//
// This schema separates font descriptors (what fonts ARE) from text styling
// (how text USES fonts). This is critical for PDF extraction where we need
// to preserve exact shaping behavior while maintaining clean abstractions.
//
// THREE LAYERS:
//
// 1. FONT FACE DESCRIPTORS (@font-face level)
//    - FontFace: Identifies the font file (weight, style, URL, unicode ranges)
//    - These are immutable properties of the font program itself
//    - Used for font face selection and loading
//
// 2. FONT FAMILY METADATA (family-level capabilities)
//    - FontFamilyRef: What the font family CAN do (features, axes, metrics)
//    - Capabilities: variable axes, OpenType features, color support
//    - Language support, font metrics (UPM, ascender, descender, etc.)
//
// 3. TEXT STYLING (per-span/textbox level)
//    - TextShaping: How specific text USES the font
//    - Kerning, ligatures, number styles, OpenType features
//    - Variable font axis values, optical sizing
//    - This is where PDF→HTML conversion decisions live
//
// PDF EXTRACTION MAPPING:
//
// PDF Concept              → Proto Message
// Font program identity    → FontFace
// Font metrics/capabilities→ FontFamilyRef
// Text rendering matrix    → TextShaping
// Glyph positioning        → letter_spacing, word_spacing
// OpenType shaping         → TextShaping.opentype_features
//
// ============================================================================

message ColorValue {
  oneof value {
    uint32 rgba = 1;
    string css_string = 2;
  }
}

message ColorRef {
  uint32 id = 1;
  ColorValue value = 2;
}

enum FontCategory {
  FONT_CATEGORY_UNSPECIFIED = 0;
  FONT_CATEGORY_SANS_SERIF = 1;
  FONT_CATEGORY_SERIF = 2;
  FONT_CATEGORY_MONOSPACE = 3;
  FONT_CATEGORY_CURSIVE = 4;
  FONT_CATEGORY_FANTASY = 5;
}

enum FontStyle {
  FONT_STYLE_UNSPECIFIED = 0;
  FONT_STYLE_NORMAL = 1;
  FONT_STYLE_ITALIC = 2;
  FONT_STYLE_OBLIQUE = 3;
}

enum ColorFontFormat {
  COLOR_FONT_FORMAT_UNSPECIFIED = 0;
  COLOR_FONT_FORMAT_COLR_CPAL = 1;
  COLOR_FONT_FORMAT_SVG = 2;
  COLOR_FONT_FORMAT_CBDT_CBLC = 3;
  COLOR_FONT_FORMAT_SBIX = 4;
}

enum FontSourceType {
  FONT_SOURCE_RELATIVE = 0;
  FONT_SOURCE_PUBLIC = 1;
  FONT_SOURCE_PRIVATE = 2;
}

enum LigatureMode {
  LIGATURE_MODE_UNSPECIFIED = 0;
  LIGATURE_MODE_NORMAL = 1;
  LIGATURE_MODE_NONE = 2;
  LIGATURE_MODE_COMMON = 3;
  LIGATURE_MODE_DISCRETIONARY = 4;
  LIGATURE_MODE_HISTORICAL = 5;
  LIGATURE_MODE_CONTEXTUAL = 6;
}

enum NumberStyle {
  NUMBER_STYLE_UNSPECIFIED = 0;
  NUMBER_STYLE_LINING = 1;
  NUMBER_STYLE_OLDSTYLE = 2;
  NUMBER_STYLE_PROPORTIONAL = 3;
  NUMBER_STYLE_TABULAR = 4;
}

enum KerningMode {
  KERNING_MODE_UNSPECIFIED = 0;
  KERNING_MODE_AUTO = 1;
  KERNING_MODE_NORMAL = 2;
  KERNING_MODE_NONE = 3;
}

message VariableFontAxisValue {
  string tag = 1;
  float value = 2;
}

message OpenTypeFeatureValue {
  string tag = 1;
  optional int32 value = 2;
}

message TextShaping {
  optional KerningMode kerning = 1;
  optional LigatureMode ligatures = 2;
  optional NumberStyle number_style = 3;
  optional bool contextual_alternates = 4;
  optional bool optical_sizing = 5;
  
  repeated VariableFontAxisValue variable_axes = 6;
  repeated OpenTypeFeatureValue opentype_features = 7;
}

message FontVariationAxis {
  string tag = 1;
  float min_value = 2;
  float max_value = 3;
  float default_value = 4;
  optional string name = 5;
}

message FontFeature {
  string tag = 1;
  optional string name = 2;
  optional bool default_on = 3;
}

message UnicodeRange {
  uint32 start = 1;
  uint32 end = 2;
}

message FontPreview {
  optional bytes hash = 1;
  optional string url = 3;
}

message FontFace {
  optional bytes hash = 1;
  uint32 weight = 3;
  FontStyle style = 4;
  optional string url = 5;
  optional FontSourceType source_type = 6;
  repeated UnicodeRange unicode_ranges = 7;
  optional FontPreview preview = 8;
}

message FontFamilyRef {
  uint32 id = 1;
  string family = 2;
  optional FontCategory category = 3;
  repeated FontFace faces = 4;
  
  // Font Family Flags Bitmask:
  // 0x01: is_variable
  // 0x02: has_color
  // 0x04: has_kerning
  // 0x08: has_ligatures
  // 0x10: has_small_caps
  // 0x20: has_contextual_alternates
  // 0x40: has_space_glyph
  optional uint32 flags = 5;

  repeated FontVariationAxis axes = 6;
  optional ColorFontFormat color_format = 8;
  repeated FontFeature features = 9;
  
  repeated string supported_scripts = 14;
  repeated string supported_languages = 15;
  
  optional int32 units_per_em = 16;
  optional int32 ascender = 17;
  optional int32 descender = 18;
  optional int32 line_gap = 19;
  optional int32 x_height = 20;
  optional int32 cap_height = 21;
}

message FontSizeRef {
  uint32 id = 1;
  int32 size = 2;
}

message LineHeightRef {
  uint32 id = 1;
  int32 line_height = 2;
}

message LetterSpacingRef {
  uint32 id = 1;
  int32 letter_spacing = 2;
}

message WordSpacingRef {
  uint32 id = 1;
  int32 word_spacing = 2;
}

message WidthRef {
  uint32 id = 1;
  int32 width = 2;
}

message HeightRef {
  uint32 id = 1;
  int32 height = 2;
}

message StringRef {
  uint32 id = 1;
  string value = 2;
}

message RefTable {
  repeated ColorRef color_refs = 1;
  repeated FontFamilyRef font_family_refs = 2;
  repeated FontSizeRef font_size_refs = 3;
  repeated LineHeightRef line_height_refs = 4;
  repeated LetterSpacingRef letter_spacing_refs = 5;
  repeated WordSpacingRef word_spacing_refs = 6;
  repeated WidthRef width_refs = 7;
  repeated HeightRef height_refs = 8;
  
  repeated StringRef string_refs = 20;
}