✨🧑‍💻 - Specify a cross browser GitHub extension usability features MVP and Action integration #694

Is there an existing issue or feature request for this?

• I have searched the existing issues and feature requests.

What area does this improvement affect?

New Feature

What actions does this improvement affect?

Issue, Pull Request, Commit

Description of the idea or improvement

Specify an original github.com extension: standalone usability, optional Action integration, three-browser MVP and roadmap. SDD/catalog/schema work only. Use the verified Action-owned branch, add complete companions and open its PR. Runtime, stores and feature deployment remain future work.

Resolved decisions and initial publication

These six maintainer-authorized decisions remain resolved on a newer base.

1. Standalone DOM/URL features need no Action, backend or credential. Connected mode is explicit per repository; public reads may be anonymous. Private reads use an optional user-owned fine-grained PAT for selected repositories with read-only Metadata, Contents, Issues, Pull requests and Actions as needed. Respect organization approval/SSO and endpoint restrictions. No client secret, bot/workflow PAT, session-cookie scraping, classic-token fallback, write scope, telemetry or hosted authentication prerequisite. Credentials and private evidence stay only in protected extension storage.session; reconnect after browser restart. Never expose them to content-script messages, page DOM, synchronized/exported preferences, URLs or diagnostics. Denied or unsupported access yields unavailable/read-only connected UI while standalone features continue.
2. The Action adds a bounded, versioned snapshot to its existing durable current-status publication. The extension background reader validates the snapshot and allowlisted canonical GitHub reads. A reviewed .copilot/browser-extension.json at a pinned observed default-branch commit declares numeric producer ID, permitted workflow paths and capabilities. Validate author, repository, conversation, run/attempt/workflow, head/base/policy/configuration identity, collection fences, observation time, freshness, pagination/completeness and source links. Source pointers are locators, not authority. Hidden live policy cannot be certified: describe it as assessed at source time. Missing evidence never means zero findings or green readiness. Keep durable lifecycle, transient activity and human waiting distinct.
3. K3 prepares status/analyze only in the supported issue/PR conversation; fix/dismiss only in a verified current same-repository finding's supported native PR review-thread reply, with a verified viewer write hint. Unknown authority/target gives read-only or copy-only guidance. Preserve existing drafts: append/keep/cancel, with replacement only by explicit user choice. The person reviews and submits; the Action then authorizes actor, target, event and exact revision. No foreign-fork correction or implement/sync/release/deploy drafts in MVP. Page opening, navigation and rendering never submit a comment, mutate repository state, trigger an Action or run an agent.
4. API compatibility floors: Chrome 140; Firefox 140 including ESR 140 compatibility; Safari 18.2 on macOS 15.2+. Chrome/Firefox desktop Windows 11, macOS 15.2+ and Ubuntu 24.04. Record exact floor/current/previous-stable and currently supported ESR evidence; API compatibility floors do not imply vendor security support. Chrome MV3 service worker; Firefox/Safari nonpersistent background scripts. Shared portable core with browser adapters and reviewed manifest/build differences. Integrated page panel uses no vendor-only sidebar dependency. Real Safari extension tests are mandatory; generic WebKit is insufficient. Mobile and GitHub Enterprise are later phases, with graceful non-support; future hosts require optional exact-host permissions and per-host credentials.
5. Maintainers' Safari release owner provisions Apple Developer/App Store Connect roles, bundle IDs, signing custody, containing-app packaging, privacy/support/store assets, review, update and rollback. Default delivery: App Store Connect Web Extension Packager -> TestFlight -> macOS App Store containing app; Xcode development/fallback remains available. Actual Mac/Safari acceptance is required. Those accounts, signing and store operations are future delivery prerequisites, not actions authorized by this specification issue.
6. Private extension/ pnpm workspace, original TypeScript domain/application/semantic ports/adapters/composition/presentation, locked Vite/Vitest, real browser-loaded acceptance and preserved root overrides/quality gates. Share only the pure src/domain/browser_extension_contract/index.ts boundary; no Node-only imports, credentials or mutating Action entrypoints in browser bundles. Initial Action publication creates/catalogues only specs/github-browser-extension.md. Contributor commits after branch readiness add the integration/platform companions and JSON evidence under the same proposed capability. Existing Action source/test/docs paths establish integration baseline only, not implemented extension behavior.

Initial new-capability catalog record (lastVerified is the specification review date):

{"id":"github-browser-extension","title":"GitHub browser extension and Action-connected usability","status":"proposed","scope":"Specify standalone usability and optional Action context in Chrome, Firefox and Safari; runtime is future work","owner":"Copilot maintainers","lastVerified":"2026-10-25","specs":["specs/github-browser-extension.md"],"workflows":[],"entrypoints":["src/actions/github_action.ts"],"code":["src/application/usecases/read_copilot_status_workflow.ts"],"tests":["src/application/usecases/__tests__/read_copilot_status_workflow.test.ts"],"documentation":["docs/development/specifications.mdx"]}

Product scope and feature inventory

Standalone usability plus opt-in connected context, beside native GitHub content with settings/toolbar support. Installation grants no Action authority.

Each feature records problem, surface/example, DOM/API source, permission/freshness, browser/default, conflicts, accessibility/performance risk, acceptance and phase. Inventory navigation/code/diffs, issue/PR conversations/lists, checks/runs, notifications, releases/tags and preferences. Beyond MVP assess whitespace/indent readability, bot-noise filters, remembered collapse, workflow/PR and CI links, notification triage, release comparisons and authoritative merged-work/release links. Never guess ambiguous targets; show hidden counts/restore and preserve blockers/native checks/reviews.

Roadmap: richer notification triage, cross-repository views, additional code/release helpers, explicitly authorized API writes, Enterprise and mobile. Record dependencies and acceptance; all three desktop browsers stay in MVP. Original design and implementation only: inspect public extension repositories for modular activation, navigation, teardown, deduplication, settings migration, optional permissions, caching, failure isolation and diagnosis; copy no source, selectors, CSS, assets, prose or branding. External product names belong only in technical research provenance, not the proposed UI/product narrative.

Integration, architecture and operational contract

Audit/link existing status, SDD/PR readiness, findings, lifecycle, publication, locale and command-authorization SDDs. The Action owns authority; markers/labels/check names/stale runs alone prove nothing. Specify minimal producer changes, schema/capability compatibility, packaging and positive/negative fixtures.

Decision 2 owns identity/provenance. Specify authoritative links, incomplete findings, unavailable/pending/blocked/stale/partial/not-applicable/verified-complete states; contradictions, head/base fences, multiple PRs, forks, tabs and late responses. Bound GET concurrency, conditional reads/cache, refresh/foreground polling/background silence and 401/403/private-404/offline/rate-limit recovery. Process globals cannot be sole durable state.

Decision 6 owns layers: define pure invariants, immutable use cases, semantic ports, typed adapter errors, entrypoints/view models and state/schema/migration ownership. Enforce dependency/cycle/Node-import, shared-API, schema/manifest/permission/package rules. Add component and sequence/state diagrams with text equivalents.

Each feature has stable identity, predicates, capabilities, default, init/refresh/teardown, owned DOM/listeners/observers and isolated errors. Handle idempotent mount/unmount, soft navigation, partial React/Turbo refresh, back/forward, virtualized lists, abort/generation fencing and extension updates with tabs open. Unsupported pages/missing anchors disable only affected controls. Avoid unbounded observers/full scans; dispose all resources. Detect native/other-extension equivalents and retire redundant helpers. Define reproducible startup/DOM/memory/API budgets and benchmark environment, clearly separated from actual measurements.

UX, configuration, security and browser delivery

Concrete pending, action-required, failed/blocked, partial, complete, unavailable/incompatible and stale wireframes answer: current state -> completed facts -> next transition -> actor/action -> impact -> inspectable source links -> expandable diagnostics. Keep native facts inspectable. Include deterministic headings/labels/markers, idempotent updates and bounded comment/notification noise where Action output changes. Provide keyboard/focus restoration, screen-reader announcements, zoom/narrow layouts, high contrast/reduced motion and light/dark support. English/Spanish catalogs have explicit language ownership and atomic fallback; personal extension locale and Action publication locale can differ.

For every setting give name/type, bounded allowed values/default, validation and cross-field rules, global/repository scope and precedence, persistence, migration, absent/retired/future behavior, reset/import/export. Provide recommended and meaningful alternative examples. Repository pause wins; evidence/authorization rules cannot be weakened. No arbitrary executable config or remotely loaded executable patches.

Treat DOM/comments/Markdown/URLs/messages as untrusted. Define sanitization, safe URL allowlists, sender/tab/origin and message-schema validation, confused-deputy protection, protected login/authorization/settings routes, session isolation/logout/revocation/uninstall cleanup. No history/private-code collection or telemetry by default. Missing permission/evidence cannot silently expand access or imply success. Cover suspension/restart, stale tabs, partial reads, migration, broken anchors, offline and rollback/restoring native GitHub.

Expand decisions 4/5 into a browser matrix covering APIs/CSP/permissions, clipboard, development installs, signing/review/updates and rollback. Distinguish automated builds from actual browser/manual accessibility/store evidence; name delivery-gate owners and prerequisites.

Specification deliverables and documentation

Use specs/_template.md and all applicable concerns of specs/README.md. Primary specs/github-browser-extension.md owns product, catalog, MVP/roadmap, journeys, UX and settings. Companions specs/github-browser-extension-action-integration.md and specs/github-browser-extension-platforms-and-delivery.md own integration contracts and browser/architecture/operations details. Add bounded JSON schemas and representative positive/negative fixtures, decisions/risk/dependency log, requirement-to-code/test/docs traceability and sequenced implementation slices. Register one proposed capability without fake future runtime/test evidence; generate specs/CATALOG.md. Mark unresolved material decisions Draft until product/security/architecture/browser acceptance is resolved.

Name documentation for users, setup/permissions, full configuration, privacy, operations/troubleshooting/replay/cleanup, upgrade/migration/compatibility/deprecation/rollback and architecture/contributors, including routes/navigation/examples/link/validation ownership. Lead with normal path and one useful visual; describe future behavior as planned. Proposed new files use create in the Path/Change table; existing immutable-base files use update/reference. Include the selected primary SDD itself as create. Directory trees belong in fenced examples, not assertions of existing paths. Decision 6 governs initial catalog evidence.

Exact repository-path classification for the initial SDD

Section 15 includes this table. Create means a proposed file, not implementation authorization. Other future trees belong in fenced examples. Avoid slash-separated non-path values in inline code (command pairs, locales, MIME types, browser names): the parser treats them as paths. Separate command names in prose. No invented existing paths.

Risk-derived test inventory and publication format

The following inventory fixes 96 distinct future implementation scenarios. These are not executed tests. Matrix executions do not add distinct cases. Areas: F=12 feature/configuration, N=14 navigation/lifecycle/races, A=12 adapters/provider errors, I=16 integration/schema/provenance/freshness, V=14 presentation/accessibility/localization/drafts, S=16 security/manifests/permissions/credentials, E=12 packaging/cross-browser/migration/rollback/performance. Preserve scenario intent; explain any justified refinement without reducing coverage. Repository quality thresholds remain; require full branch coverage for new pure evidence/authorization policies, deterministic clocks/fakes, replay/race tests, semantic golden assertions beyond snapshots, structural workflow/schema checks and manual UX evidence that automation cannot establish.

Section 4 has exactly the following requirement groups. Each behavior includes all detailed issue constraints in that group:

The rows below are the actual proposed section-14 inventory, with literal plain IDs and Requirements cells. Use unique fully qualified IDs, never shorthand or ranges. Raw generation places {{SDD_CASE_BUDGET}} once on a visible standalone line in section 14 and {{SDD_REQUIREMENT_CASES}} once in section 17. Trusted assembly derives budget and reverse mappings from this inventory; do not independently duplicate those two derived tables. The final document has all five canonical consistency tables and no slots. Keep section headings exactly canonical, even if surrounding prose is localized.

Current limitations or challenges

Actions cannot add personal on-page controls.

Expected impact

Reviewable SDDs with all 96 traceable cases. Run specification generation/validation, schema fixtures and docs checks. Browser/store evidence remains future work.

Alternatives considered

Dashboards lose native context; Action-only output lacks personal controls.

Version of copilot

Prospective capability; repository baseline as of 2026-10-25.

Additional context or comments

Use existing catalogued SDDs as baseline and verify dated Chrome/Mozilla/Apple primary references. Mechanics only, no copying: https://github.com/refined-github/refined-github .