Formatted text sections

Use different sizes and colors inside one label while preserving shared layout and collision bounds

A matching development SDK with commonLineSymbols also supports shared planar line symbols, including true per-glyph curved geometry, target ownership, joint icon/text groups and shared budgets. Earlier point-only scope and pending line-symbol notes below are superseded for this bounded subset. Complex shaping, tilted/globe/terrain placement and complete road stitching remain pending.

Shared point labels support format text sections. A section's font-scale multiplies the root text-size; text-color overrides the root color and is still multiplied by root text-opacity. Sections retain their actual glyph sizes and colors while sharing wrapping, justification, anchor, rotation, collision and query bounds.

map.addSource('labels', {
  type: 'geojson',
  data: {
    type: 'Feature', id: 7,
    properties: {name: 'AA', detail: 'BB'},
    geometry: {type: 'Point', coordinates: [0, 0]}
  }
});
map.addLayer({
  id: 'formatted', type: 'symbol', source: 'labels',
  layout: {
    'text-size': 24,
    'text-field': ['format',
      ['get', 'name'], {'font-scale': 1.5, 'text-color': '#ff0000'},
      ['get', 'detail'], {'font-scale': 0.5, 'text-color': '#0000ff'}
    ]
  }
});
await map.sqs.flush({render: true});

Section options may be omitted, inheriting the root size and color. Section text, scale and color can use shared expressions. case, match, coalesce and let/var can return formatted values or plain strings; layout expressions retain integer zoom evaluation. vertical-align: 'top' | 'center' | 'bottom' is supported, defaulting to bottom; see section alignment. A scale of zero emits no glyphs. Different sizes share a baseline with default bottom; other alignments move sections within their row font-size box. A transparent root color does not hide glyphs with an opaque section color.

The commonFormattedText capability covers these text sections. A formatted value may contain at most 32 sections and 256 characters / 4096 bytes in total. The complete expression is limited to 32 levels / 1024 nodes. Scale must be between 0 and 16, and the resulting section size must not exceed 256 CSS pixels. Over-budget updates fail explicitly. Existing atlas, glyph-count and display budgets remain in force; failed updates preserve the previous data and image.

Per-section font stacks now use the existing PBF service; Registered RGBA image sections are available; SDF image sections reject explicitly. Variables and branches now support let/var, match and actual null fallback. Other unknown formatted operations, complex shaping, line placement and 3D combinations remain unfinished. Plain strings retain their existing behavior. The syntax follows MapLibre's format specification; this does not claim complete formatted-value or platform compatibility.

The portable script and complete HTML fixture exercise ten behaviors and verify actual large red AA and small blue BB glyph pixels.