feat(context): optional current-page awareness for embedded webchat

Start with docs/http-contract.md and the request path in packages/dewee-webchat/src/widget/element.ts, src/widget/api-client.ts, src/server/handler.ts and src/server/gateway-client.ts to see how a chat turn is sent today. The issue is a multi-part design spanning the widget, both server implementations and the Gateway, so a newcomer should first ask a maintainer to split it into a smaller, agreed first step. Done means that step is agreed and its scope is written down in the issue.

Mục tiêu

Khi khách truy cập mở <dewee-chat> trên website đã bật tính năng, Dewee agent có thể hiểu nội dung trang hiện tại (bài viết, tài liệu, trang sản phẩm, mục hỗ trợ...) và trả lời câu hỏi như "trang này nói gì?" mà khách không phải dán URL hoặc copy nội dung.

Khác Chrome Extension: widget là script nhúng trên website, không có quyền đọc các tab/browser khác và không cần activeTab hay host permissions. Quyền truy cập context do site owner cấu hình + visitor kiểm soát; mặc định không tự động gửi nội dung trang tới backend/LLM.

Hiện trạng được kiểm tra (main @ 6f0083da8387)

• packages/dewee-webchat/src/widget/element.ts là web component dùng Shadow DOM, DeweeChatConfig chưa có page-context setting; send(text) chỉ gọi API với message/agent/conversationId.
• src/widget/api-client.ts chỉ gửi các trường chat đó đến POST /api/dewee/chat; src/server/handler.ts forward message đến streamChat; src/server/gateway-client.ts gọi Gateway WS chat.send với message/agentId/sessionKey/stream. Chưa có per-turn context attachment.
• docs/http-contract.md là hợp đồng dùng chung cho Node/Workers và php/dewee-webchat.php; phải cập nhật parity của cả hai server implementation + các framework wrappers/CDN/build docs. Không nhúng raw page vào user message bằng string concatenation.
• Server giữ gateway token; visitor dùng signed session, origin allowlist và rate limits. Bảo toàn những biên an toàn này.

Thiết kế đề xuất

1. Host-controlled configuration + visitor UI

• pageContext?: 'off' | 'metadata' | 'content', default 'off' để tránh vô tình chia sẻ dữ liệu của visitor khi upgrade SDK; site owner chủ động enable. Khi content được bật, widget chuẩn bị local ephemeral snapshot lúc mở, hiển thị Current page: title • preview • remove/disable; chỉ chuyển nội dung lên backend khi người dùng gửi tin nhắn và chọn chia sẻ ngữ cảnh theo chính sách consent rõ ràng.
• Metadata mode gồm title/sanitized URL/description; content mode ưu tiên visible main content + selected text; nên hỗ trợ contextSelector / excludeSelectors / contextProvider?: () => Promise<PageContext> tùy biến do site owner cung cấp. Không cho widget ăn toàn bộ document.body.innerText một cách mù quáng.
• SDK APIs/web component attributes hợp lý (đảm bảo SSR-safe): page-context="content", configure({pageContext:'content'}); React/Vue/Astro wrappers truyền config; sự kiện privacy-aware dewee:context-ready, dewee:context-error không chứa page text trong telemetry.
• Không tự gọi LLM, không tự gửi nội dung trang khi widget chỉ load, không persist raw context vào localStorage/sessionStorage/history. Chat/persist session hiện tại giữ nguyên.

2. Shared versioned context envelope

Đồng bộ schema logic với issue Page Context trong nextlevelbuilder/dewee-chrome-ext:

{
  "page_context": {
    "version": 1,
    "source": "embedded_webchat",
    "url": "https://example.com/docs/article",
    "title": "Article",
    "captured_at": "2026-10-15T00:00:00Z",
    "content": { "format": "markdown", "text": "# Article\n...", "truncated": false },
    "trust_level": "untrusted_external"
  }
}

• Client sanitize URL (strip credentials, fragments and secret-looking query keys); bound document size and use modest token budget (initial target 2k–4k, tune after eval).
• Server validates schema, enforces max size/length + visitor rate limits; assigns canonical source/trust server-side, not trusted from payload. Content is untrusted webpage text and must never become high-privilege instruction.
• Propagate attachment widget → POST /api/dewee/chat → server handler (Workers/Node + PHP parity) → Dewee Gateway chat.send/agent loop only after backend support exists; do not silently fall back to interpolating raw context into user-authored message if feature not supported.
• Per-turn context not injected into durable system prompt, public logs, traces, saved chat history, memory; preserve ownership and visitor isolation. Document backend dependency in nextlevelbuilder/dewee.

3. Extraction, performance and security

• Extract only readable/visible content, headings, lists, code and tables with Readability-like filter; site-owner selectors override safely; never read form values, passwords, OTPs, payment fields, editable drafts, script/style/hidden DOM, cross-origin frames.
• Context keyed to current navigation/location/content hash; SPA route changes and updates invalidate snapshot; discard stale async results. No periodic background scraping; collect on open/explicit refresh + refresh on Send when stale.
• Host page can be malicious or contain prompt injection, so treat page as data only, not instructions. No origin bypass, token exfiltration or tool permission escalation.
• Inline use on site owner page, avoid cross-frame access; for iframe embedding, only expose explicitly approved context via a secure, exact-origin postMessage handshake if required later. Do not implement wildcard messaging or trust arbitrary event.data.
• No breaking change to existing <dewee-chat> embeds. If disabled or context fails, normal chat still works. Keep browser bundle light and lazy-load extractor.

Implementation hotspots

• packages/dewee-webchat/src/widget/element.ts (config + lifecycle + chip UI)
• packages/dewee-webchat/src/widget/api-client.ts
• packages/dewee-webchat/src/protocol.ts (shared type)
• packages/dewee-webchat/src/widget/page-context.ts (new extractor)
• packages/dewee-webchat/src/server/handler.ts & src/server/gateway-client.ts
• php/dewee-webchat.php, docs/http-contract.md, packages/dewee-webchat/README.md
• Examples and framework wrappers + tests.

Acceptance criteria

• Host enabling page-context allows question about actual current page without copying text; default existing embeds remain private and unchanged.
• Context status/chip preview/removal and visitor control work; no send until explicit chat submission + consent rule.
• Metadata/content/excluded selectors/custom provider behave consistently across HTML/React/Vue/Astro.
• Navigation/SPAs update context, no stale snapshot or cross-page bleed, selected text can be prioritized.
• No secrets, hidden data, form values, credentials, cookies, localStorage or cross-origin iframe content are captured.
• Node/Workers/PHP handlers all validate and propagate typed schema identically; Gateway receives untrusted per-turn context, not fake user/system instructions.
• Oversized/malformed content fails safely without breaking normal chat, no unbounded token costs, no page content persisted/logged.
• Unit/integration tests cover privacy, custom selectors, XSS/prompt injection, SPA, SSR import, parallel chats, history, visitor isolation, backend incompatibility and request limits.

Related

• Companion feature: nextlevelbuilder/dewee-chrome-ext Page Context Provider (link issue once published).
• Backend contract/dependency: nextlevelbuilder/dewee typed untrusted ephemeral context for chat runtimes. Share conceptual schema/parser semantics where practical, without force-coupling webchat widget code to Chrome APIs.