V2: embed Humanly into arbitrary text inputs via browser extension

[ShenzheZhu]

Target branch

main when this is ready to leave backlog. This should likely start as a dedicated V2 integration branch, for example integration/browser-extension, because it spans extension UI, backend sessions/certificates, auth, and cross-site browser behavior.

Classification

type:feature / v2-backlog / cross-surface

Labels: enhancement, backlog.

Problem

Humanly currently works when users write inside the Humanly web app or an assigned task flow. Pedro proposed a Grammarly-style extension surface: Humanly should be embeddable into arbitrary website text inputs so a user can write in places like email compose boxes and optionally attach a Humanly-generated writing process proof when they send.

The desired product feel is:

• Humanly appears around normal text inputs, textareas, or rich-text compose boxes without forcing the user to open the Humanly editor first.
• The user can choose whether Humanly records the process for a particular field/session.
• When the user sends/submits the content, they can choose whether to attach or include a generated process artifact, such as a certificate/replay link or export.

This is explicitly not a near-term hotfix. It is a complex V2 feature requiring product design, privacy/security decisions, extension architecture, and backend support.

Expected behavior

For an MVP-worthy V2 slice:

1. A Chrome extension can detect standard web writing surfaces, at minimum:
   • textarea
   • text-like input fields where appropriate
   • common contenteditable compose boxes, with Gmail compose as a target fixture
2. The extension shows a small Humanly control near the active writing field with clear states:
   • Off / not recording
   • Ready to record
   • Recording
   • Proof ready / attach available
   • Error / unsupported field
3. Recording is opt-in per field/session unless the user has explicitly enabled a trusted-domain default.
4. The extension records Humanly-compatible provenance events for the external field:
   • keystrokes / text diffs
   • paste events
   • focus/blur and selection where feasible
   • AI usage only if routed through Humanly extension UI, not covertly inferred
5. On send/submit, the user gets a choice to include Humanly proof:
   • attach a generated certificate/export when the host page supports file attachment safely, or
   • insert a Humanly certificate/replay link/footer when attachment is not technically reliable, or
   • skip attaching anything.
6. The generated proof should connect to existing Humanly certificate/replay concepts instead of inventing a separate evidence format.
7. The extension must never record password fields, credit-card/payment fields, hidden fields, or browser/system UI. It must provide a domain allow/block mechanism and an obvious recording indicator.

Trigger / Product scenario

1. User installs the Humanly browser extension and signs into Humanly.
2. User opens Gmail and starts composing an email.
3. Humanly detects the compose area and shows a small opt-in control.
4. User enables recording for this compose session.
5. User writes, pastes, revises, and optionally uses Humanly-supported AI assistance.
6. User clicks Send.
7. Humanly asks whether to attach/include the writing process proof.
8. If accepted, the sent email includes a Humanly certificate/replay link or attachment; if declined, the email sends normally and the local/session data is handled according to the chosen retention policy.

Where the work likely lives

This likely needs a new browser-extension package plus changes to existing tracking/certificate surfaces:

• New package TBD, likely packages/browser-extension or apps/browser-extension
  • Chrome Manifest V3 setup
  • content scripts for field detection and event capture
  • background/service worker for auth/session coordination
  • extension popup/settings UI
• Existing tracker package
  • packages/tracker/src/tracker.ts
  • packages/tracker/src/types.ts
  • Reuse or adapt event normalization so external-field traces remain compatible with Humanly provenance logs.
• Backend session/certificate APIs
  • packages/backend/src/routes/document.routes.ts
  • packages/backend/src/routes/certificate.routes.ts
  • packages/backend/src/services/certificate.service.ts
  • May need a new external-writing-session resource so extension sessions are not forced into the normal Humanly document/task model.
• User portal certificate/replay UI
  • packages/frontend-user/src/app/certificates/[id]/page.tsx
  • packages/frontend-user/src/app/verify/[token]/page.tsx
  • The proof artifact should remain readable and verifiable for recipients.
• Shared types/config
  • packages/shared/src/types/*
  • May need shared event/session/proof metadata for extension-origin sessions.

Scope

Initial design and MVP scope:

• Chrome extension only. Other browsers are follow-up unless the architecture naturally supports them.
• Support standard inputs, textareas, and one rich-text fixture such as Gmail compose.
• Opt-in recording and visible recording status are mandatory.
• Certificate/replay link generation is in scope.
• Attachment insertion is in scope only where technically reliable; otherwise a link/footer fallback is acceptable.
• Backend retention policy and privacy copy must be decided before implementation.

Acceptance criteria

• Product spec defines the user flow, recording states, permission model, retention policy, and attach/link behavior.
• Technical design chooses the package location, Manifest V3 architecture, auth strategy, and backend session model.
• Extension can record a Humanly-compatible event stream from a normal textarea without breaking typing, paste, undo/redo, or IME input.
• Extension can record from at least one rich-text compose fixture, preferably Gmail compose.
• User can start/stop recording per field and see an unmistakable recording indicator.
• Password/payment/hidden fields are excluded by hard guardrails and covered by tests.
• Generated proof can be opened in the existing Humanly certificate/verification/replay surface or a clearly defined compatible variant.
• Send/submit interception offers attach/link/skip without blocking the host page if Humanly fails.
• Browser tests cover textarea, contenteditable, unsupported field, disabled domain, and send-with-proof fallback paths.
• Production QA includes at least Gmail compose and one generic textarea fixture before release.

Out of scope

• No implementation in the current task.
• No Firefox/Safari extension in the first pass unless explicitly reprioritized.
• No guarantee that every arbitrary website or custom editor works in V2 MVP.
• No automatic recording without user-visible consent.
• No attempt to infer external AI usage outside Humanly-controlled tools for this feature.
• No bypassing host-site security policies or private browser/system UI.

Open questions

• Should extension sessions be saved as normal Humanly documents, separate external-writing sessions, or ephemeral certificate-only records?
• Should users be allowed to generate proof without storing full text, storing only hashes plus events, or does the certificate need full content for verification?
• What is the default retention policy for email-like/private writing?
• How should proof be represented in email: PDF attachment, JSON attachment, certificate URL, footer text, or user-selectable options?
• How should domain-level defaults work for personal users versus admin/organization managed deployments?
• What is the minimum viable set of host pages for V2 launch: Gmail only, Gmail + generic textareas, or broader app set?

Reference

Conversation request from Pedro/user:

Pedro: it would be cool to embed Humanly into any text input box, like Grammarly.
User can choose whether to attach the generated writing process when sending.
Example: writing an email and attaching the Humanly process proof.

Related existing concepts:

• Humanly web editor provenance capture.
• Certificate and replay proof flow.
• Configurable AI access and traceability policy.