# @ethisyscore/host-ui-externals

Type contracts and mock implementations for the host-supplied gogo-ui externals
used by high-trust plugin UI tiers. A plugin depends on this package as a
**dev-dependency only**: at build time it provides the TypeScript types (and, via
`./mock`, runnable stand-ins for local/CI/Storybook), while production bundles
externalise the specifier so the plugin binds to the host's own runtime instance
rather than shipping a second copy.

> This keeps a plugin's UI type-safe against the host's gogo-ui surface without
> bundling — the same externalisation model PlatformReact uses for `react`,
> `@mui/material`, etc.

## Export surface

| Subpath | Key exports | Purpose |
|---|---|---|
| `.` | `GogoTheme`, `GogoMode`, `GogoThemeProviderProps`, `GogoChildren`, `GogoMenuItem`, `ComponentType`, `ReactNode`, `GOGO_EXTERNALS_SPECIFIER_MAP` | Type contracts for the host gogo-ui components (theme presets, mode, provider props, menu-item shape) plus the specifier map the host registry resolves against |
| `./mock` | `GogoThemeProvider`, `useGogoTheme`, and re-exported types | Mock implementations for local/CI/Storybook development — render semantic HTML with `data-testid` attributes so plugin UI can run and be tested without the real host |

## Typical usage

```ts
// Types compile against the host surface; production externalises the import.
import type { GogoTheme, GogoThemeProviderProps } from "@ethisyscore/host-ui-externals";
```

```tsx
// Local dev / tests substitute the mock provider.
import { GogoThemeProvider } from "@ethisyscore/host-ui-externals/mock";
```

## Build and test

```bash
npm ci && npm run build && npm test
```

> Last Updated: 2026-07-10