Summary

Add four annotation types for inline text styling: TextColor (existing), BackgroundColor (existing, renamed), TextSize (new), TextFamily (new). Formalize the distinction between additive and exclusive annotations, and rename attributes.color → attributes.value for consistency across all exclusive types.

Enforcement applies to both documents and comments, on both web and desktop.

Annotation Categories

This distinction already exists in practice — TextColor uses its color value in the identity key (unicode.ts:57-73) but has never been formalized or enforced.

Type Definitions

All exclusive annotations share the same structure via exclusiveAnnotationProperties:

const exclusiveAnnotationProperties = {
  ...baseAnnotationProperties,
  attributes: z.object({ value: z.string() }).optional(),
}

export const TextColorAnnotationSchema = z.object({
  type: z.literal('TextColor'),
  ...exclusiveAnnotationProperties,
}).strict()

export const BackgroundColorAnnotationSchema = z.object({
  type: z.literal('BackgroundColor'),
  ...exclusiveAnnotationProperties,
}).strict()

export const TextSizeAnnotationSchema = z.object({
  type: z.literal('TextSize'),
  ...exclusiveAnnotationProperties,
}).strict()

export const TextFamilyAnnotationSchema = z.object({
  type: z.literal('TextFamily'),
  ...exclusiveAnnotationProperties,
}).strict()

Value Constraints

Concrete value constraints are enforced with .enum() in the schemas, but the base uses z.string() for extensibility without schema migration.

Data Examples

{
  "type": "TextColor",
  "starts": [0, 12],
  "ends": [5, 18],
  "attributes": { "value": "seed-blue" }
}

{
  "type": "TextFamily",
  "starts": [0],
  "ends": [25],
  "attributes": { "value": "seed-serif" }
}

Comment Publishing Type

The HMPublishableAnnotation union (used when publishing comments) is extended:

export type HMPublishableAnnotation =
  | { type: 'Bold' | 'Italic' | 'Underline' | 'Strike' | 'Code'; starts: number[]; ends: number[] }
  | { type: 'Link' | 'Embed'; starts: number[]; ends: number[]; link: string }
  | { type: 'TextColor' | 'BackgroundColor' | 'TextSize' | 'TextFamily'; starts: number[]; ends: number[]; attributes: { value: string } }

Identity Model

The AnnotationSet._annotationId function in unicode.ts determines how annotations are deduplicated:

_annotationId(type: string, attributes: {[key: string]: string} | null) {
  if (attributes) {
    if (attributes.link) return `${type}-${attributes.link}`
    if (attributes.href) return `${type}-${attributes.href}`
    if (attributes.value) return `${type}-${attributes.value}`  // was attributes.color
  }
  return type
}

This means:

TextFamily-seed-serif and TextFamily-seed-sans-serif are separate annotation objects with separate spans

Bold has no attributes, so all bolds merge into one annotation with multiple spans

Identity keys determine deduplication — they do NOT enforce non-overlap

Overlap Enforcement (three layers)

Layer 1: Editor UI (primary enforcement)

When applying an exclusive annotation to a selection, the editor first removes any existing annotation of the same type with a different value from that range. This is the UX guarantee — the user can't accidentally create overlapping exclusive annotations.

Layer 2: Publish boundary (gate)

Before any publish operation (document or comment), a validation function checks the annotation array:

const EXCLUSIVE_TYPES = ['TextColor', 'BackgroundColor', 'TextSize', 'TextFamily']

export function validateExclusiveAnnotations(annotations: HMAnnotation[]): void {
  for (const type of EXCLUSIVE_TYPES) {
    const ofType = annotations.filter(a => a.type === type)
    for (let i = 0; i < ofType.length; i++) {
      for (let j = i + 1; j < ofType.length; j++) {
        const aVal = (ofType[i].attributes as any)?.value
        const bVal = (ofType[j].attributes as any)?.value
        if (aVal && bVal && aVal === bVal) continue  // same value = fine
        if (spansOverlap(ofType[i], ofType[j])) {
          throw new Error(`${type} annotations with different values overlap`)
        }
      }
    }
  }
}

Document path: Called in publishDocument() before PrepareDocumentChange.

Comment path: Called inside annotationsToPublishable() in comment.ts — covers both createComment() and updateComment().

Backend path: Also validated server-side in applyChanges as a safety net.

Layer 3: Zod refinement (defense-in-depth)

Optional .refine() on HMAnnotationsSchema to reject invalid arrays at deserialization time.

Rendering Pipeline

Slate → HM (`editorblock-to-hmblock.ts`)

if (leaf.styles?.textColor) {
  annotations.addSpan('TextColor', {value: leaf.styles.textColor}, start, end)
}
if (leaf.styles?.backgroundColor) {
  annotations.addSpan('BackgroundColor', {value: leaf.styles.backgroundColor}, start, end)
}
if (leaf.styles?.textSize) {
  annotations.addSpan('TextSize', {value: leaf.styles.textSize}, start, end)
}
if (leaf.styles?.textFamily) {
  annotations.addSpan('TextFamily', {value: leaf.styles.textFamily}, start, end)
}

HM → Slate (`hmblock-to-editorblock.ts`)

if (annotationData.type === 'TextColor') {
  leaf.styles.textColor = attributes?.value
}
if (annotationData.type === 'BackgroundColor') {
  leaf.styles.backgroundColor = attributes?.value
}
if (annotationData.type === 'TextSize') {
  leaf.styles.textSize = attributes?.value
}
if (annotationData.type === 'TextFamily') {
  leaf.styles.textFamily = attributes?.value
}

SSR Renderer (`ssr-render.ts`)

case 'TextColor': {
  html = `<span data-text-color="${esc(value)}">${html}</span>`
  break
}
case 'BackgroundColor': {
  html = `<span data-background-color="${esc(value)}">${html}</span>`
  break
}
case 'TextSize': {
  html = `<span data-text-size="${esc(value)}">${html}</span>`
  break
}
case 'TextFamily': {
  html = `<span data-text-family="${esc(value)}">${html}</span>`
  break
}

Data Migration

Existing documents with TextColor/BackgroundColor annotations using attributes: { color: "..." } need handling.

Recommendation: lazy migration. Read attributes.value ?? (attributes as any).color as a fallback in the renderer and identity key. Add a deprecation comment on the color path. Remove the fallback after 6 months when all active documents have been re-saved with the new format.