Playwright-assisted extension architecture

Purpose

Extend forge-lcdl with Playwright-assisted, read-only modules. An already-authorized user browser/session is attached through playwright. LCDL exposes deterministic Python APIs that read and normalize enterprise UI state into a source-neutral item model — without private Graph/Workday/SharePoint REST calls and without harvesting session secrets.

This extension is not a replacement for governed LLM tasks (run_task, TASK_REGISTRY_V1). It is a parallel capability for structured reads from attached sessions.

Design principles

Placement in forge-lcdl

  Consumer / host app
      │ attach authorized playwright session
      ▼
  forge_lcdl.playwright          ← new package (subsequent steps)
      │ PlaywrightSession Protocol
      │ policy + normalize
      │ sources/* (outlook, teams, workday, …)
      ▼
  UnifiedItem[]                 ← source-neutral model

  Optional later:
      ├── forge_lcdl.tasks.*    ← governed LLM wrappers if needed
      └── forge_lcdl.mcp_client ← optional MCP/Playwright backend hook only

Unchanged in v1 architecture (do not refactor):

• src/forge_lcdl/runner.py — run_task / TaskRunner
• src/forge_lcdl/tasks/catalog_v1.py — TASK_REGISTRY_V1
• src/forge_lcdl/generic/ — OpenAI-compat transport
• src/forge_lcdl/mcp_client/ — optional MCP client (related, not identical to playwright)

Module boundaries (planned)

Target tree under src/forge_lcdl/playwright/ (created in later steps):

Public API (later): export minimal types and attach_session from forge_lcdl.playwright. Do not add to top-level forge_lcdl.__init__ __all__ until the surface stabilizes.

Unified item model

Every source maps into one shape (implementation in playwright/types.py):

Optional governed tasks may add JSON Schema sidecars under contracts/playwright_*/v1/ in a later step if reads are wrapped by run_task.

Deterministic call flows

1. Attach (consumer or runtime)

Host obtains authorized playwright session (outside LCDL)
    → PlaywrightSession.attach(session_handle)
    → Result[None, PlaywrightError]

LCDL does not perform login, MFA, or credential prompts.

2. Read a source (core pattern)

Caller: read_outlook_inbox(session, options)
    → policy.check_navigation(url)           # domain allowlist
    → session.navigate(approved_url)
    → session.snapshot()                     # DOM / accessibility tree / text
    → sources.outlook.normalize(snapshot)    # pure function on snapshot bytes
    → Result[list[UnifiedItem], PlaywrightError]

Normalization is pure given snapshot input so unit tests do not need a browser.

3. Read-only file extraction

Caller: read_file_bytes(session, file_ref)
    → policy permits readonly download
    → session.download_readonly(file_ref)    # local bytes only; no upload path
    → sources.files.extract_text(bytes, mime)
    → Result[UnifiedItem, PlaywrightError]

Office/PDF parsers may be optional extras (playwright-files); core documents the hook even if parsers ship later.

4. Error envelope

All facade entrypoints return Result[T, PlaywrightError], consistent with McpError usage in the MCP client.

Source systems (v1 scope)

Tenant-specific DOM variance is handled in normalizers with tolerant parsing and fixture-backed tests — not brittle single-selector assumptions in the session layer.

Relationship to MCP and runtime

Testing architecture

Default pytest in pyproject.toml continues to exclude granite and must not require network or attached playwright.

SharePoint atoms vs consumer orchestration

LCDL exposes product-agnostic SharePoint read atoms (normalize, probe, REST list, scroll/viewport/columns, list-item fields, binary download). The host attaches an authorized browser session (PlaywrightPageSession.from_page(page)), registers routes, and invokes connectors or governed tasks. LCDL never imports consumer repos and must not know deck IDs, corpus paths, job phases, or M365 Copilot menus.

See SHAREPOINT-CONSUMER-BOUNDARY.md for the atomic catalog and consumer rules.

Outlook / Teams messaging atoms vs consumer orchestration

LCDL exposes product-agnostic Outlook and Teams read atoms (health probe, chunked list harvest, conversation/thread read). The host attaches Edge/CDP, registers session_ref, and composes tasks into ingest flows (caps, checkpoints, unified_message). On attach, LCDL applies CDP focus emulation by default so Microsoft virtualized lists render without stealing OS focus (FORGE_LCDL_CDP_BRING_TO_FRONT=0). LCDL must not import consumer repos or know Cockpit sync UI steps.

See MESSAGING-CONSUMER-BOUNDARY.md, OUTLOOK-EML-EXPORT-DUAL-ARCHITECTURE.md, OUTLOOK-READ-STRATEGIES.md, and TEAMS-READ-STRATEGIES.md.

Outlook People / CRM atoms vs consumer orchestration

LCDL exposes product-agnostic Outlook People and Dynamics CRM read atoms. (The former Org Explorer Delve-iframe crawl surface has been removed; the Outlook People Organization tab is now the sole org-structure source.) The host attaches Edge/CDP, registers session_ref, and maps wire output to SQLCipher / on-disk folders. Selective CDP attach enables the same focus emulation policy as messaging ingest so background tabs stay harvestable. LCDL must not import consumer repos or know crawl depth policies, enrich tier planners, or portfolio board swimlanes.

Security and compliance posture

• No cookie, storage-state, header, or token export — enforced in policy and types (see READONLY_POLICY.md).
• No Microsoft Graph, SharePoint REST, or Workday REST in v1.
• Provenance and logs must remain redactable; tests will assert banned fields stay absent.

Enterprise data-handling expectations align with Data handling: LCDL core does not introduce durable mailbox storage; consumers own retention.

PDCA handoff

Deferred to later steps: playwright/ package implementation, pytest markers, source modules, optional MCP bridge, handbook nav in docs/index.md, live testing guide.

References

• Product boundary
• Runtime boundary
• MCP client
• mcp_client/policy.py — readmostly_playwright()
• .cursor/rules/lcdl-playwright-pdca.mdc — implementation guardrails