contentitem/images/drawing.proto

§Raw schema

syntax = "proto3";

package eddocu.drawing.v3;

enum DrawingFamily {
  DRAWING_FAMILY_UNSPECIFIED = 0;
  DRAWING_FAMILY_VML = 1;
  DRAWING_FAMILY_DRAWINGML = 2;
}

enum DrawingRoute {
  DRAWING_ROUTE_UNSPECIFIED = 0;
  DRAWING_ROUTE_NATIVE_SVG = 1;
  DRAWING_ROUTE_NATIVE_IMAGE = 2;
  DRAWING_ROUTE_NATIVE_EDITABLE_TEXT = 3;
  DRAWING_ROUTE_GENERATED_RASTER = 4;
  DRAWING_ROUTE_EXACT_RASTER = 5;
  DRAWING_ROUTE_UNSUPPORTED_NO_SOURCE = 6;
}

enum DrawingNodeKind {
  DRAWING_NODE_KIND_UNSPECIFIED = 0;
  DRAWING_NODE_KIND_SHAPE = 1;
  DRAWING_NODE_KIND_CONNECTOR = 2;
  DRAWING_NODE_KIND_GROUP = 3;
  DRAWING_NODE_KIND_PICTURE = 4;
  DRAWING_NODE_KIND_GRAPHIC_FRAME = 5;
  DRAWING_NODE_KIND_CONTENT_PART = 6;
  DRAWING_NODE_KIND_ALTERNATE_CONTENT = 7;
  DRAWING_NODE_KIND_UNKNOWN = 8;
}

enum DrawingSourceScope {
  DRAWING_SOURCE_SCOPE_UNSPECIFIED = 0;
  DRAWING_SOURCE_SCOPE_SINGLE_AUTHORED_NODE = 1;
  DRAWING_SOURCE_SCOPE_SUBTREE_CROP = 2;
  DRAWING_SOURCE_SCOPE_GENERATED_SMARTART_DRAWING_CHILD = 3;
  DRAWING_SOURCE_SCOPE_GRAPHIC_FRAME_OVERLAY = 4;
  DRAWING_SOURCE_SCOPE_UNKNOWN_GRAPHICDATA_CROP = 5;
}

enum DrawingVisualRole {
  DRAWING_VISUAL_ROLE_UNSPECIFIED = 0;
  DRAWING_VISUAL_ROLE_SHAPE_BACKING = 1;
  DRAWING_VISUAL_ROLE_EXACT_CROP = 2;
  DRAWING_VISUAL_ROLE_GROUP_RASTER = 3;
  DRAWING_VISUAL_ROLE_GENERATED_RASTER = 4;
  DRAWING_VISUAL_ROLE_AUTHORED_PREVIEW = 5;
  DRAWING_VISUAL_ROLE_FRAME_SUBTREE = 6;
}

message DrawingSource {
  DrawingFamily family = 1;
  string part = 2;
  string xml_tag = 3;
  string xml_id = 4;
  string template_id = 5;
}

message DrawingTransform {
  // Packed [x, y, width, height] in milli-pixels in the authored node's local
  // transform space. Exact-crop page placement remains in page.pb.
  repeated int32 local_bounds = 1 [packed = true];
  int32 rotation_cdeg = 2;
  uint32 flip_flags = 3;
}

message DrawingTextSource {
  uint32 version = 1;
  string plain_text = 2;
  // Optional packed [x, y, width, height] local text rectangle in milli-pixels.
  repeated int32 local_text_rect = 3 [packed = true];
  // Compact bodyPr/autofit/wrap/text-warp flags. Raw text XML intentionally
  // stays out of this sidecar.
  uint32 body_flags = 4;
  string text_warp = 5;
}

message DrawingSourceOpRef {
  uint64 source_op_id = 1;
  optional int32 page_op_seq = 2;
  optional uint32 draw_op_index = 3;
  optional uint32 scene_kind = 4;
  // Packed [a, b, c, d, e, f] CTM captured at the contributing draw op.
  repeated float ctm = 5 [packed = true];
}

message DrawingRasterSource {
  optional uint32 rasterization_type = 1;
  // Packed [x0, y0, x1, y1] in milli-pixels in page/output coordinates.
  repeated int32 output_bbox = 2 [packed = true];
  // Packed [a, b, c, d, e, f] output placement transform when available.
  repeated float output_ctm = 3 [packed = true];
  repeated DrawingSourceOpRef source_ops = 4;
  optional uint32 effect_key_id = 5;
  optional uint32 clip_id = 6;
  optional uint32 clip_depth = 7;
  optional uint32 frame_scope_id = 8;
  optional uint32 owner_kind = 9;
  optional int32 owner_id = 10;
  optional int32 z = 11;
  // Stable debug/route tokens for tooling. Consumers must not depend on
  // document names, page numbers, or asset paths to interpret the route.
  repeated string route_debug_tags = 12;
  optional uint32 source_op_ledger_version = 13;
  optional uint32 placement_id = 14;
  optional uint32 placement_contract_version = 15;
}

message DrawingObject {
  uint32 id = 1;
  uint32 slide_index = 2;
  DrawingRoute route = 3;
  uint32 fallback_reason = 4;
  DrawingSource source = 5;
  repeated string flags = 6;
  string text = 7;
  // Compact source metadata hints for editor/export workflows.
  // Bitmask, VML currently uses:
  // 0x001 lock, 0x002 wrap, 0x004 anchorlock, 0x008 ClientData,
  // 0x010 textdata, 0x020 iscomment, 0x040 signatureline,
  // 0x080 OLE/control marker, 0x100 ink, 0x200 inherited template metadata,
  // 0x400 edit handles.
  uint32 metadata_flags = 8;
  // Rare editable-geometry handles, currently VML h records. Compact tokens
  // are source-prefixed and keep only authored handle attrs, e.g.
  // "template;position=#0,#1;xrange=0,21600".
  repeated string edit_handles = 9;
  // Owning page ContentItem id. The visible item stays in page.pb; this
  // sidecar carries cold source/route data for that item.
  optional uint32 content_item_id = 10;
  optional uint32 drawing_node_id = 11;
  // Versioned additive payload for dense DrawingML diagnostics/source tracing.
  // t4.pb remains a serialized DrawingObject; older clients ignore these fields.
  uint32 payload_version = 12;
  DrawingNodeKind node_kind = 13;
  DrawingSourceScope source_scope = 14;
  DrawingVisualRole visual_role = 15;
  DrawingTransform transform = 16;
  string geometry_token = 17;
  uint32 effect_flags = 18;
  DrawingTextSource text_source = 19;
  DrawingRasterSource raster_source = 20;
  optional uint32 placement_id = 21;
}

message DrawingCollection {
  repeated DrawingObject objects = 1;
}

// 007 — V2 source-ref sidecar.
//
// Multi-owner cold sources without overloading the primary
// rasterization_type. The visible page item still carries one primary
// rasterization_type; SourceRef adds secondary owners (semantic/visual
// split, generated children, hash-ambiguous source bytes, diagnostic
// raw-source payloads). Existing clients keep reading the one primary
// type; v2-aware consumers walk SourceRefBundle for the rest.
enum SourceRefRole {
  SOURCE_REF_ROLE_UNSPECIFIED = 0;
  // Mirrors the primary rasterization_type owner. Emitted when an item
  // has both a primary owner and at least one secondary, so consumers
  // can treat the bundle as the single source of truth without joining
  // back to ContentItem.rasterization_type.
  SOURCE_REF_ROLE_PRIMARY = 1;
  // Authored, semantically meaningful owner (e.g. SmartArt diagram XML
  // for a generated drawing child).
  SOURCE_REF_ROLE_SEMANTIC_OWNER = 2;
  // The exact bytes that produced the visible pixels (e.g. drawing
  // child of a SmartArt subtree, or rasterization payload).
  SOURCE_REF_ROLE_VISUAL_OWNER = 3;
  // Authored fallback preview the editor / export path can fall back to.
  SOURCE_REF_ROLE_PREVIEW_SOURCE = 4;
  // Editable shape source for non-destructive round-trip.
  SOURCE_REF_ROLE_EDIT_SOURCE = 5;
  // Diagnostic raw payload, consumed only by debug tooling.
  SOURCE_REF_ROLE_DIAGNOSTIC = 6;
  // Pixel oracle: the secondary source supplies the visible pixels for a
  // primary owner that cannot pixel-prove its lowering yet (e.g. an
  // mc:AlternateContent Fallback PNG painting a Choice's chart/contentPart
  // when the JS renderer or vector route can't match Office's bitmap).
  // Distinct from VISUAL_OWNER: the primary still owns the typed source,
  // the oracle is "pretty pixels until we can prove our own".
  SOURCE_REF_ROLE_VISUAL_ORACLE = 7;
}

enum SourceRefFamily {
  SOURCE_REF_FAMILY_UNSPECIFIED = 0;
  SOURCE_REF_FAMILY_TEXT = 1;
  SOURCE_REF_FAMILY_CHART = 2;
  SOURCE_REF_FAMILY_SMARTART = 3;
  SOURCE_REF_FAMILY_DRAWING = 4;
  SOURCE_REF_FAMILY_MEDIA = 5;
  SOURCE_REF_FAMILY_OLE = 6;
  SOURCE_REF_FAMILY_INK = 7;
}

message SourceRef {
  // Page index plus visible ContentItem id form the join key against
  // page.pb. slide_index defaults to 0 when target_kind is global.
  uint32 slide_index = 1;
  uint32 content_item_id = 2;
  SourceRefRole role = 3;
  SourceRefFamily family = 4;
  // BLAKE3-128 hash of the typed sidecar payload, when one exists.
  bytes source_hash = 5;
  // Optional explicit path inside the output package, used when the
  // typed sidecar is not addressable by hash (rare, mostly diagnostic).
  string explicit_payload_path = 6;
  // The semantic owner's per-collection id (e.g. SmartArt diagram index,
  // chart id, drawing id) when applicable.
  uint32 object_id = 7;
  // Optional human-readable note for diagnostic refs. Consumers must
  // not rely on this for routing; it is for trace / proof tooling.
  string note = 8;
}

message SourceRefBundle {
  uint32 schema_version = 1;
  repeated SourceRef refs = 2;
}