COS v0.2 Draft ChaptersSingle pageJSON Schema

Context Object Specification (COS)

Version: 0.2
Chapter: 210 — Selection
Status: Normative
Category: Core Model

1. Purpose

This chapter defines the abstract concept of Selection within the Context Object Specification (COS).

Selection is the primary input signal of the protocol and serves as the origin point for Context Object generation.

This chapter redefines Selection as a protocol-level concept, independent of any browser or UI implementation.

2. Conceptual Shift

In traditional browser environments, Selection refers to a DOM-based API:

window.getSelection()

Within COS, this interpretation is insufficient.

The protocol redefines Selection as:

A structured representation of an explicit focus signal within a content environment.

This shift separates Selection from any specific runtime implementation.

3. Definition

A Selection is an explicit, source-bounded focus region that serves as the input anchor for Context Object generation.

A Selection represents intentional focus, not just raw text extraction.

4. Selection vs Raw Text

A Selection is NOT equivalent to extracted text.

Raw text only represents character data:

"useEffect"

A Selection includes additional conceptual attributes:

The protocol distinguishes between:

Concept Meaning
Raw Text Character sequence
Selection Structured input signal

5. Selection Characteristics

A valid Selection MUST satisfy the following properties:

5.1 Bounded

A Selection MUST have clearly defined start and end boundaries within a content source.

5.2 Explicit

A Selection MUST represent an explicit focus signal exposed by the source environment or deliberately supplied by a Producer.

A Producer MUST NOT create a Selection by inferring focus from content alone. Human text selection, an explicit programmatic focus request, and an explicitly identified AI-generated text focus MAY qualify when their non-empty text, boundaries, and source are known. A collapsed cursor with no selected text is not a COS v0.2 Selection.

5.3 Source-Linked

A Selection MUST be associated with the Context Object’s top-level source.

Selection itself SHOULD NOT duplicate source details.

6. Selection Scope (v0.2)

In version 0.2 of COS:

The Selection concept is scoped to:

Supported environments include:

Unsupported (future extensions):

7. Selection Structure (Conceptual Model)

A Selection is conceptually defined as:

interface Selection {
  text: string;
  range?: SelectionRange;
}

This structure is conceptual and may be adapted by different Producers.

8. Selection Range

A Selection Range defines the boundaries of the selection.

interface SelectionRange {
  startOffset: number;
  endOffset: number;
  startNodeId?: string;
  endNodeId?: string;
  direction?: "forward" | "backward" | "unknown";
}

Range is defined relative to logical content nodes, not visual rendering.

Offsets MUST count UTF-16 code units in the referenced logical node’s text, matching DOM Range offsets for text nodes. Adapters for sources with different native coordinate systems MUST convert their offsets or preserve native coordinates in an Extension.

Producers SHOULD include range when the source supports stable range extraction.

When range is omitted, Consumers can still read selection.text and context.segments, but they may not be able to precisely locate the original selection inside the source.

For single-node selections, startNodeId and endNodeId MAY be identical or omitted when the source context makes the node unambiguous.

For cross-node selections, startNodeId and endNodeId MUST identify the logical content nodes that contain the start and end offsets.

When both offsets refer to the same logical node, endOffset MUST be greater than or equal to startOffset.

Cross-node range ordering MUST follow a deterministic logical source order defined by the Producer. Implementing or serializing the supporting Document Hierarchy model is not required.

9. Source Separation

Selection MUST NOT duplicate full source metadata in COS v0.2 lean core.

The origin of the Selection is represented by the top-level source field of the Context Object.

Selection range node identifiers MAY reference context segment identifiers.

10. Selection Metadata

Selection-specific metadata is not part of the lean core Selection object.

If a Producer needs to preserve interaction metadata, it SHOULD place it in meta or an Extension.

Examples:

Metadata MUST NOT alter the meaning of Selection.

11. Selection Lifecycle

A Selection exists at the moment an explicit focus signal is established:

Explicit Focus Signal
    ↓
Selection Created
    ↓
Context Pipeline Starts
    ↓
Selection Transformed into Context Object

Selection is not persistent in the protocol layer.

Only Context Objects are persisted and transported.

12. Relationship to Context Object

Selection is the input primitive of the Context Object.

Transformation rule:

Selection → Context Enrichment Pipeline → Context Object

A Context Object cannot exist without an originating Selection (within v0.2 scope).

13. Design Constraints

A Selection MUST NOT:

These responsibilities belong to later pipeline stages.

14. Implementation Independence

Although Selection is inspired by browser APIs, the protocol does NOT depend on:

Any system capable of producing equivalent structured input MAY implement Selection.

15. Example (Informative)

{
  "text": "useEffect",
  "range": {
    "startOffset": 120,
    "endOffset": 129,
    "startNodeId": "code-1",
    "endNodeId": "code-1",
    "direction": "forward"
  }
}

Source information belongs to the containing Context Object’s top-level source. Interaction-specific data belongs in meta when it fits the lean model, or in an Extension.

16. Summary

Selection is the minimal input primitive of the Context Object Specification.

It represents an explicit, source-bounded focus within a content environment.

It is deliberately kept minimal to ensure that all semantic understanding is deferred to the Context Object Pipeline.

Selection exists only as an input signal.

Context Object is where meaning begins.