page_extra.proto

§Raw schema

syntax = "proto3";

package eddocu.page.extra.v3;

import "css_enums.proto";

// Cold, optional page data. A renderer can paint page.proto without this file.
// Fetch this sidecar only for slideshow/runtime interactions, rich hover
// behavior, sound cues, or edit workflows that need source metadata not needed
// at first paint.

enum TargetKind {
  TARGET_KIND_UNSPECIFIED = 0;
  TARGET_KIND_ELEMENT = 1;
  TARGET_KIND_TEXT_RUN = 2;
  TARGET_KIND_ZONE = 3;
  TARGET_KIND_PAGE = 4;
}

message TargetRef {
  TargetKind kind = 1;

  // Page element id from page.proto. For text runs this is the owning TextBox id.
  optional uint32 element_id = 2;

  // Sparse structural address inside a TextBox. Kept out of page.proto so runs
  // do not need stable ids unless they actually have cold metadata.
  optional uint32 paragraph_index = 3;
  optional uint32 run_index = 4;

  // Packed hit zone: [left, top, width, height, z] in page milli-pixels.
  // Used only for link/hover zones that do not correspond to a visual element.
  repeated sint32 b = 5 [packed = true];
}

enum TriggerKind {
  TRIGGER_KIND_UNSPECIFIED = 0;
  TRIGGER_KIND_CLICK = 1;
  TRIGGER_KIND_HOVER_IN = 2;
  TRIGGER_KIND_HOVER_OUT = 3;
  TRIGGER_KIND_FOCUS = 4;
  TRIGGER_KIND_LOAD = 5;
}

message NavigationAction {
  optional string href = 1;
  optional eddocu.page.v3.LinkType link_type = 2;

  // Compact decoded source action such as "show:next", "slide:3",
  // "macro:RunMe", or "ppaction://hlinkshowjump?jump=nextslide".
  optional string action = 3;
}

message TooltipAction {
  string text = 1;
}

message SoundAction {
  optional string src = 1;
  optional bytes hash = 2;
  optional int32 volume_milli = 3; // 1000 = authored/default volume.
}

message StylePatchAction {
  // Deliberately cold and CSS-oriented. Renderers may ignore unsupported
  // declarations without affecting first paint.
  optional string css_text = 1;
  optional uint32 class_id = 2;
}

message InteractionAction {
  oneof action {
    NavigationAction navigation = 1;
    TooltipAction tooltip = 2;
    SoundAction sound = 3;
    StylePatchAction style_patch = 4;
  }
}

message Interaction {
  TargetRef target = 1;
  TriggerKind trigger = 2;
  repeated InteractionAction actions = 3;

  // Runtime/editor hints:
  // 0x01 = stop propagation
  // 0x02 = prevent default browser behavior
  // 0x04 = initially disabled
  optional uint32 flags = 4;
}

message FieldBinding {
  TargetRef target = 1;

  // Canonical metadata for dynamic text fields. page.proto keeps the authored
  // snapshot text in the run itself; this cold metadata is only needed for live
  // substitution, editing, or export.
  optional string field_id = 2;
  optional string field_type = 3;
  optional string field_kind = 4;
  optional string field_format = 5;
}

message ExtraBlobRef {
  // Family-specific cold payload. For example, animation table, source XML,
  // audit/diagnostic payload, or a future typed editor model.
  uint32 type = 1;
  bytes hash = 2;
}

message PageExtra {
  // Binds this sidecar to the exact core page bytes. Use BLAKE3-128.
  optional bytes page_hash = 1;

  repeated Interaction interactions = 10;
  repeated FieldBinding field_bindings = 11;
  repeated ExtraBlobRef blobs = 20;
}