Anchor 6 — Viewport context payload shape

"Lesson 6 가 ChromeEmbed 의 모든 부분 흐르는 JSON object zoom in: host-context payload. 모든 field 정당화, 모든 field 가 panel iframe 이 의존하는 계약."

Full shape

Content script 의 extractContext() 가 반환:

{
  type: 'pippa:host-context',
  payload: {
    host_kind: 'web-page',
    snapshot_at: '2026-05-16T01:23:45.000Z',
    host_id: chrome.runtime.id,
    source: location.href,
    human_label: document.title || location.hostname,
    favicon: faviconHref(),
    selection,
    viewportText,
    readableText: viewportText, // compat alias
    wordCount,
    viewport: { width, height, scrollX, scrollY, devicePixelRatio },
    scrollPosition: { y: scrollY, ofPageHeight: pageHeight },
    language: document.documentElement?.lang || navigator.language || '',
    frameUrl: location.href,
    isTopFrame: window.top === window
  }
}

Identity field

• host_kind — ChromeEmbed 엔 항상 'web-page'. PIPPA-EMBEDS framework 가 이거 기대; Adobe-embed 가 'adobe-app', Calendar 가 'gcal-event' 등. Downstream 렌더링 위한 discriminator.
• host_id — extension 의 runtime id. cwkPippa 가 다른 installed instance (multi-Chrome-profile setup) 의 메시지 구별하게.
• source — user 가 있는 canonical URL. cwkPippa 가 이걸 'capturing from example.com/article' 로 surface.
• human_label — fallback-chained title. Chat thread label 로 사용.
• favicon — UI affordance 위해.

Content field

• selection — 현재 highlighted 텍스트 (또는 최대 5 분 전의 cached selection).
• viewportText — user 의 현재 viewport 안 텍스트, walker-추출 spatially sorted (Lesson 3).
• readableText — viewportText 의 alias. 옛 cwkPippa 코드 경로가 'readableText' read; alias 가 ChromeEmbed 가 그것들 안 깨뜨림. 계획: cwkPippa 가 'viewportText' 로 완전 migrate 할 때 deprecate.
• wordCount — cwkPippa UI 위한 quick metric ('1,247 words in view').

Viewport field

• viewport: { width, height, scrollX, scrollY, devicePixelRatio } — user window 의 physical-pixel 측정. cwkPippa 가 작은 viewport 나 hi-DPI display 에 UI 적응 가능.
• scrollPosition: { y, ofPageHeight } — user 가 page 의 어디 수직 위치, plus 총 page height. cwkPippa 가 'you are 60% through this article' 표시 가능.

Metadata

• snapshot_at — ISO timestamp. cwkPippa 가 'context from 5 seconds ago' 표시 가능.
• language — cwkPippa 가 매칭 locale 로 응답 format 에 유용.
• frameUrl, isTopFrame — SW (Lesson 2) 의 merge logic 위해. Sub-frame push 가 이거 carry, SW 가 top-frame snapshot override 할지 결정 가능.

왜 schema, '그냥 DOM 보내기' 아님

Fixed payload shape 의 규율이 이럴 때 payback:

• 다른 embed 가 compose. PIPPA-EMBEDS framework 가 모든 embed (Chrome, Adobe, Mail, Calendar) 가 같은 field 이름의 host-context 생산 기대. cwkPippa 가 uniformly 렌더.
• Versioning. Payload v1 → v2 bump 필요하면, 오늘 version: 1 field 추가하고 내일 확인.
• Compatibility. readableText alias 가 정확히 fixed schema 가 enable 하는 종류의 migration aid. Schema 없이는 모든 consumer 가 추측해야.
• Observability. cwkPippa 의 log 가 context payload 보일 때, 어떤 field 존재하는지 추측 안 하고 structured record 처럼 read 가능.

Payload 에 없는 것

일부러 부재:

• Full document HTML — 훨씬 너무 크고 viewport semantic 잃음.
• Screenshot — storage 비용, screenshot crop 이 future field 가능.
• Tab history — ChromeEmbed 의 scope 밖; cwkPippa 가 이미 자체 conversation history 가짐.
• User identity — Pippa 가 cwkPippa session 에서 누군지 앎, extension context 에서 아님.

Field 추가가 feature 로 정당화될 때 저렴; speculatively 추가는 schema 시끄럽고 bridge 느리게 만듬.