Skip to content

feat(overlay): add manual overlay initialization and support for Capacitor apps #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
erkamyaman wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

feat(overlay): add manual overlay initialization and support for Capacitor apps #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0a8d4b4
feat(overlay): add manual overlay initialization and support for Capa…
erkamyaman Sep 25, 2026
1d50686
WIP merge main into feat/capacitor-support
erkamyaman Oct 7, 2026
035c4c4
Merge remote-tracking branch 'upstream/main' into pr21-update
erkamyaman Oct 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The package is published on npm as [`@pangular-inspector/devtools`](https://www.
npm install @pangular-inspector/devtools devframe
```

Then follow the [installation guide](./apps/docs/src/content/getting-started/installation.md) for your setup: Angular CLI with Express, Vite and Analog, the standalone CLI, or [Angular Native](./apps/docs/src/content/guides/angular-native.md). For a coding agent, run `npx @pangular-inspector/devtools mcp`.
Then follow the [installation guide](./apps/docs/src/content/getting-started/installation.md) for your setup: Angular CLI with Express, Vite and Analog, the standalone CLI, [Angular Native](./apps/docs/src/content/guides/angular-native.md), or [Capacitor](./apps/docs/src/content/guides/capacitor.md). For a coding agent, run `npx @pangular-inspector/devtools mcp`.

## Documentation

Expand Down
41 changes: 22 additions & 19 deletions app/src/app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,24 +80,6 @@ const VIEW_TABS: Partial<Record<View, Tab[]>> = {
'angular-native': ['components', 'signals', 'injectors', 'store', 'pipes'],
};

const COMING_SOON: Partial<Record<View, ComingSoonInfo>> = {
capacitor: {
id: 'capacitor',
name: 'Capacitor',
badge: 'Coming Soon',
heading: 'Capacitor Support',
summary: 'Connect Ionic and Capacitor apps running in a device WebView back to these tools.',
color: '#119eff',
plans: [
'Manual overlay start for apps that load from capacitor:// or a device',
'Connection settings passed in, no cross-origin probing',
'Setup guides for the Android emulator and iOS simulator',
],
pr: 21,
author: { name: 'Erkam Yaman', login: 'erkamyaman' },
},
};

const NATIVESCRIPT_SETUP: ComingSoonInfo = {
id: 'nativescript',
name: 'NativeScript',
Expand All @@ -118,6 +100,26 @@ const NATIVESCRIPT_SETUP: ComingSoonInfo = {
},
};

const CAPACITOR_SETUP: ComingSoonInfo = {
id: 'capacitor',
name: 'Capacitor',
badge: 'Available',
heading: 'Inspect Capacitor apps',
summary:
'An Ionic or Capacitor app runs the browser overlay in its WebView and reports to this server, so it shows up in the Angular dock like any other page.',
color: '#119eff',
plansTitle: 'Set up an app',
plans: [
'Install @pangular-inspector/devtools in the app',
'Call initOverlay() from @pangular-inspector/devtools/overlay-manual with this server and its connectionMeta',
'Run npx pangular dev --no-auth in the app, then open the Angular dock',
],
link: {
label: 'Capacitor setup guide',
href: 'https://pangular-inspector.dev/guides/capacitor/',
},
};

const NOT_ANALOG: ComingSoonInfo = {
id: 'analog',
name: 'Analog',
Expand Down Expand Up @@ -803,10 +805,11 @@ export class App implements OnInit, OnDestroy {
const view = this.view();
if (view === 'analog') return this.analogKnown() && !this.analog() ? NOT_ANALOG : undefined;
if (view === 'nativescript') return NATIVESCRIPT_SETUP;
if (view === 'capacitor') return CAPACITOR_SETUP;
if (view === 'angular-native') {
return this.nativeKnown() && !this.nativePageId() ? NO_ANGULAR_NATIVE : undefined;
}
return view ? COMING_SOON[view] : undefined;
return undefined;
});
readonly config = computed(() => panelConfig(this.rpc()));
protected readonly tabEnabled = tabEnabled;
Expand Down
10 changes: 2 additions & 8 deletions apps/docs/src/app/pages/index.page.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -988,21 +988,15 @@ claude mcp add pangular -- \\
logo: '/logos/angular-native.svg',
size: 17,
},
{name: 'Capacitor', url: '/guides/capacitor', logo: '/logos/capacitor.svg', size: 16},
];

readonly maintainers = [
{name: 'Erkam Yaman', login: 'erkamyaman', role: 'Lead maintainer'},
{name: 'Santosh Yadav', login: 'santoshyadavdev', role: 'Maintainer'},
];

readonly comingSoon: StackItem[] = [
{
name: 'Capacitor',
url: 'https://github.com/pangular-inspector/devtools/pull/21',
logo: '/logos/capacitor.svg',
size: 16,
},
];
readonly comingSoon: StackItem[] = [];

readonly reasons: {
icon: LucideIconInput;
Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/content/contributing/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ packages/
devtools/ # Publishable npm package
src/devframe.ts # defineDevframe(): the tool definition
src/overlay.ts # Client script running in the user's page
src/overlay-auto.ts # Starts the overlay and the floating button on import
src/rpc/ # Node-side RPC functions and agent tools
extension/ # Chrome DevTools extension
examples/analog/ # Analog demo app
Expand Down
21 changes: 11 additions & 10 deletions apps/docs/src/content/contributing/publishing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,17 @@ The devtools ship as one npm package, `@pangular-inspector/devtools`, from `pack

The package publishes `dist/` and `bin.mjs`. On publish, `publishConfig.exports` points every entry point at the built files:

| Import | Published file |
| --------------------------------------- | ------------------- |
| `@pangular-inspector/devtools` | `dist/devframe.mjs` |
| `@pangular-inspector/devtools/devframe` | `dist/devframe.mjs` |
| `@pangular-inspector/devtools/config` | `dist/config.mjs` |
| `@pangular-inspector/devtools/overlay` | `dist/overlay.mjs` |
| `@pangular-inspector/devtools/popup` | `dist/popup.mjs` |
| `@pangular-inspector/devtools/http` | `dist/http.mjs` |
| `@pangular-inspector/devtools/hub` | `dist/hub.mjs` |
| `@pangular-inspector/devtools/vite` | `dist/vite.mjs` |
| Import | Published file |
| --------------------------------------------- | ----------------------- |
| `@pangular-inspector/devtools` | `dist/devframe.mjs` |
| `@pangular-inspector/devtools/devframe` | `dist/devframe.mjs` |
| `@pangular-inspector/devtools/config` | `dist/config.mjs` |
| `@pangular-inspector/devtools/overlay` | `dist/overlay-auto.mjs` |
| `@pangular-inspector/devtools/overlay-manual` | `dist/overlay.mjs` |
| `@pangular-inspector/devtools/popup` | `dist/popup.mjs` |
| `@pangular-inspector/devtools/http` | `dist/http.mjs` |
| `@pangular-inspector/devtools/hub` | `dist/hub.mjs` |
| `@pangular-inspector/devtools/vite` | `dist/vite.mjs` |

The `pangular` binary is `bin.mjs`. In the workspace, the exports point at the TypeScript sources instead.

Expand Down
2 changes: 1 addition & 1 deletion apps/docs/src/content/getting-started/express.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ A floating button appears on your page. It opens the devtools with one dock entr
| Analog | File routes, server calls, render modes and lint (a notice in non-Analog apps) |
| Angular Native | Components, signals, injectors and store of a connected [Angular Native](./angular-native.md) app |
| NativeScript | Setup steps for [NativeScript apps](../guides/nativescript.md) |
| Capacitor | A **Coming Soon** placeholder |
| Capacitor | Setup steps for [Capacitor and Ionic apps](../guides/capacitor.md) |

[Popup and hub](./popup-and-hub.md) covers the panel, its dock modes and deep links.

Expand Down
23 changes: 12 additions & 11 deletions apps/docs/src/content/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,17 +65,18 @@ MCP agent support (`@devframes/agentic`) is included. You don't install it separ

### Entry points

| Import | Use it for |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `@pangular-inspector/devtools/hub` | `initPangularHub()`, the server middleware for an Express app. |
| `@pangular-inspector/devtools/vite` | The Vite plugin for Analog apps. |
| `@pangular-inspector/devtools/overlay` | The browser script that collects live data from your page. |
| `@pangular-inspector/devtools/overlay-angular-native` | The overlay for an Angular Native app. See [Angular Native](./angular-native.md). |
| `@pangular-inspector/devtools/overlay-nativescript` | The overlay for a NativeScript Angular app. See [NativeScript](./nativescript.md). |
| `@pangular-inspector/devtools/popup` | The floating button and panel on your page. |
| `@pangular-inspector/devtools/http` | The HTTP interceptor and hydration hooks for the SSR & HTTP tab. |
| `@pangular-inspector/devtools/config` | The `PangularConfig` type and its defaults. See [Configuration](./configuration.md). |
| `@pangular-inspector/devtools/devframe` | The devframe definition, for custom hosts. |
| Import | Use it for |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `@pangular-inspector/devtools/hub` | `initPangularHub()`, the server middleware for an Express app. |
| `@pangular-inspector/devtools/vite` | The Vite plugin for Analog apps. |
| `@pangular-inspector/devtools/overlay` | The browser script that collects live data from your page. |
| `@pangular-inspector/devtools/overlay-manual` | The same overlay, started only when you call `initOverlay`. See [Capacitor](../guides/capacitor.md). |
| `@pangular-inspector/devtools/overlay-angular-native` | The overlay for an Angular Native app. See [Angular Native](./angular-native.md). |
| `@pangular-inspector/devtools/overlay-nativescript` | The overlay for a NativeScript Angular app. See [NativeScript](./nativescript.md). |
| `@pangular-inspector/devtools/popup` | The floating button and panel on your page. |
| `@pangular-inspector/devtools/http` | The HTTP interceptor and hydration hooks for the SSR & HTTP tab. |
| `@pangular-inspector/devtools/config` | The `PangularConfig` type and its defaults. See [Configuration](./configuration.md). |
| `@pangular-inspector/devtools/devframe` | The devframe definition, for custom hosts. |

### The CLI binary

Expand Down
33 changes: 33 additions & 0 deletions apps/docs/src/content/getting-started/overlay.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,39 @@ Only one overlay runs on a page. Importing the module already starts one on the

An overlay that was stopped or replaced before it connected does not report its connection error.

### Start it yourself

`@pangular-inspector/devtools/overlay-manual` exports the same functions and starts nothing on import. Nothing connects and no floating button appears until you call `initOverlay`:

```ts
// src/main.ts
import {bootstrapApplication} from '@angular/platform-browser';
import {App} from './app/app';
import {appConfig} from './app/app.config';

bootstrapApplication(App, appConfig).then(async () => {
if (typeof ngDevMode === 'undefined' || ngDevMode) {
const {initOverlay} = await import('@pangular-inspector/devtools/overlay-manual');
await initOverlay({baseURL: '/__my-devtools/'});
}
});
```

### Pass the connection info

`initOverlay` first fetches `__connection.json` from `baseURL` to learn the server's transport. A page on another origin, such as an app in a [Capacitor WebView](../guides/capacitor.md), cannot read that file. Pass its content as `connectionMeta` and the overlay skips the fetch:

```ts
// src/main.ts
const {initOverlay} = await import('@pangular-inspector/devtools/overlay-manual');
await initOverlay({
baseURL: 'http://localhost:9999/',
connectionMeta: {backend: 'websocket', websocket: {path: '__ws'}},
});
```

The overlay takes its inspectors, redaction and limits from `connectionMeta.configs`. Without `configs`, it uses the defaults.

## Stop the overlay

Call `disposeOverlay` to turn the overlay off:
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/src/content/getting-started/popup-and-hub.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ When the page's server mounts the hub (`/__devframes/`), the button opens the wh
| Analog | The Analog tab, or a notice in apps that do not use Analog |
| Angular Native | Components, Signals, Injectors and Store for a connected [Angular Native](./angular-native.md) app, or a setup notice when none is connected |
| NativeScript | Setup steps for [NativeScript apps](../guides/nativescript.md) |
| Capacitor | A **Coming Soon** placeholder |
| Capacitor | Setup steps for [Capacitor and Ionic apps](../guides/capacitor.md) |

### Full-page viewer

Expand Down
Loading
Loading