mirror of
https://github.com/tiddly-gittly/TidGi-Desktop.git
synced 2026-03-11 01:10:23 -07:00
b677088a48
Make TidGi IPC service proxies available inside the TiddlyWiki sandbox and provide typings for plugin authors. Added docs (docs/TidGiServiceAPI.md), bumped tidgi-shared to 0.1.2, and introduced shared type files (packages/tidgi-shared/src/{global.d.ts,tidgiGlobal.ts}) and tsconfig include for .d.ts files. Preload now exposes service via contextBridge and attaches it to $tw.tidgi.service (with DOMContentLoaded retry). Updated various wiki plugin files to use $tw.tidgi.service instead of window.service, adjusted worker-side service exports (no automatic global attach), and updated startNodeJSWiki to safely inject service into the wiki sandbox with proper typing. Added runtime TiddlyWiki type augmentations (src/types/tidgi-tw.d.ts). These changes ensure plugins running in the VM can reliably access typed service proxies.
46 lines
1.6 KiB
Markdown
46 lines
1.6 KiB
Markdown
# TidGi Service API Usage
|
||
|
||
This document explains how TW plugins can call TidGi services and how the API is exposed across front-end and back-end.
|
||
|
||
## Where services are exposed
|
||
|
||
TidGi exposes the same service proxies in two places:
|
||
|
||
- Plugin runtime (TW sandbox): `$tw.tidgi.service`
|
||
- Frontend runtime (renderer): `window.service`
|
||
|
||
## Usage in plugins (TiddlyWiki route modules)
|
||
|
||
Route modules run inside TiddlyWiki’s VM sandbox, so `globalThis` is not the worker’s real global. Use `$tw.tidgi.service`.
|
||
|
||
Example:
|
||
|
||
```ts
|
||
import type { ITidGiGlobalService } from 'tidgi-shared';
|
||
|
||
const tidgiService = ($tw as typeof $tw & { tidgi?: { service?: ITidGiGlobalService } }).tidgi?.service;
|
||
```
|
||
|
||
## Usage in renderer / WebView
|
||
|
||
Frontend UI code should keep using `window.service`.
|
||
|
||
```ts
|
||
await window.service.workspace.getActiveWorkspace();
|
||
```
|
||
|
||
## How the API is wired
|
||
|
||
- Service proxies are created in the wiki worker and preload using `electron-ipc-cat`.
|
||
- Renderer (WebView): `src/preload/common/exportServices.ts` exposes proxies via `contextBridge`, assigns `window.service`, and attaches `$tw.tidgi.service` after `$tw` is ready.
|
||
- Wiki worker: `startNodeJSWiki.ts` attaches the same proxies to `$tw.tidgi.service` before TiddlyWiki boot, so route modules can access them inside the sandbox.
|
||
|
||
## Types for plugins
|
||
|
||
Use `tidgi-shared` for type-safe access. It also augments the global `$tw` shape so editors can resolve `$tw.tidgi.service`:
|
||
|
||
```ts
|
||
import type { IWorkspaceService } from 'tidgi-shared';
|
||
```
|
||
|
||
This package re-exports all service interfaces and IPC descriptors used by TidGi.
|