components/sync/protocol/shared_comment_specifics.proto

// Copyright 2025 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// If you change or add any fields in this file, update proto_visitors.h and
// potentially proto_enum_conversions.{h, cc}.

syntax = "proto2";

option java_multiple_files = true;
option java_package = "org.chromium.components.sync.protocol";

option optimize_for = LITE_RUNTIME;

package sync_pb;

// Represents the context of a URL shared within a group, including its various
// representations and metadata.
message SharedUrlContext {
  enum Source {
    // The source is not specified.
    SOURCE_UNSPECIFIED = 0;
    // The current URL shown in the Omnibox.
    OMNIBOX = 1;
    // The URL we received or sent through Chrome Sync.
    FROM_SYNC = 2;
    // The Canonical URL the client identified.
    CANONICAL_URL = 3;
  }

  // A specific representation of a URL from a particular source.
  message UrlRepresentation {
    // Where this URL representation was received from.
    optional Source source = 1;
    // The URL, hash, or other unique identifier for this representation.
    optional string value = 2;
    // An optional version string to differentiate representations over time.
    optional string version = 3;
  }

  // A list of all known representations for this URL. This allows different
  // clients to find a common representation for identifying the page.
  repeated UrlRepresentation representations = 1;

  // The title of the web page this SharedUrlContext refers to.
  optional string title = 2;
}

// Contains all the data for a user-authored comment, including its
// content, sorting key, and attribution.
message CommentData {
  // The user-authored comment string, which may contain rich text.
  optional string text = 1;

  // Describes what a comment is about, such as a reply to another comment or a
  // new comment on a specific target.
  message Attribution {
    // Identifies the target of a top-level comment.
    message CommentTarget {
      // The UUID of the `SharedUrlContext` specifics this comment is attached
      // to.
      optional string shared_url_context_uuid = 1;

      // A link to a specific text fragment within the page (i.e., a "deep
      // link").
      message FragmentLink {
        // The fragment part of the link, i.e. the #:~:text=... part of the
        // link.
        optional string fragment = 1;
        // A string representation of the selected text to be used in previews.
        optional string text_preview = 2;
      }
      // An optional link to a text fragment within the page.
      optional FragmentLink link_fragment = 2;
    }

    // Identifies the parent comment this comment is a reply to.
    message InReplyTo {
      // The UUID of the parent comment.
      optional string parent_id = 1;
    }

    // Defines whether the comment is a new thread or a reply.
    oneof kind {
      // The target if this is a new top-level comment.
      CommentTarget top_level = 1;
      // Metadata about the parent comment if this is a reply.
      InReplyTo parent = 2;
    }
  }

  // The attribution data for this comment, indicating what it refers to.
  optional Attribution attribution = 2;

  // Defines a key used for deterministically sorting comments in a distributed
  // system. This ensures that all clients render comments in the same stable
  // order, regardless of network timing or processing order. This is intended
  // to be used together with the creation time of an entity to provide a
  // strictly monotonically increasing ordering.
  message OrderKey {
    // A unique identifier for the device or client that authored the comment
    // (e.g., a GUID). This serves as the main tie-breaker for comments with
    // identical timestamps.
    optional string device_guid = 1;

    // A strictly monotonically increasing sequence number generated by the
    // source device. Any sequence number is guaranteed to not be reused for the
    // same source device.  This provides a final, definitive ordering for
    // comments created by the same source, even if they arrive out of order.
    optional int64 local_sequence = 2;
  }
  // A key for deterministically sorting entities.
  optional OrderKey order_key = 3;
}

// Represents a single entity in the commenting system, which can be either a
// user comment or a URL context object. This is the top-level message for a
// single comment-related sync entity.
message SharedCommentSpecifics {
  // A unique identifier (UUID) for this entity.
  optional string uuid = 1;

  // A stable, permanent identifier for the collaboration context this entity
  // belongs to. It serves as a permanent foreign key to group related data
  // types (e.g., comments, tab groups) that belong to the same logical
  // collaboration. This ID never changes, even if the underlying entity is
  // shared or unshared, thus preventing data from being orphaned.
  optional string context_id = 2;

  // The highest SharedCommentSpecifics version supported by the client that
  // wrote this entity.
  optional int64 proto_version = 3;

  // The main payload of this entity.
  oneof entity {
    // The content of a user-authored comment.
    CommentData comment = 4;
    // The context for a URL being commented on.
    SharedUrlContext shared_url_context = 5;
  }
}