@sybilion/uilib 1.0.21 → 1.0.23

package/docs/private-npm-registry.md

@@ -0,0 +1,152 @@
+# Private npm registry (local + CI)
+
+This document describes a typical setup using **Verdaccio** as a lightweight private registry. Alternatives include **npm Enterprise**, **GitHub Packages**, **GitLab Package Registry**, **Azure Artifacts**, and **JFrog Artifactory**; the **auth and CI patterns** below apply to any registry that supports npm’s token-based login.
+
+## 1. Run a local private registry (Verdaccio)
+
+Install and start (no project required):
+
+```bash
+yarn global add verdaccio
+verdaccio
+```
+
+Default URL: `http://localhost:4873`. Open that URL in a browser to confirm the UI.
+
+- **Persistence**: config and storage live under `~/.config/verdaccio` by default (see [Verdaccio docs](https://verdaccio.org/docs/configuration) for `storage`, `auth`, and uplinks).
+- **Use the public registry for non-private packages**: Verdaccio usually **proxies** `https://registry.npmjs.org` for packages you did not publish locally, so `yarn install` can stay one command.
+
+## 2. Publish a package to the private registry
+
+One-off login (creates/updates auth in `~/.npmrc`):
+
+```bash
+npm adduser --registry http://localhost:4873
+```
+
+In the package you want to publish (`uilib` or another repo), set the registry for that scope or package. Examples.
+
+**Scoped package** (`@sybilion/uilib`):
+
+```ini
+# .npmrc next to package.json (or in user ~/.npmrc)
+@sybilion:registry=http://localhost:4873/
+```
+
+**Unscoped package**: either publish only to Verdaccio for that session:
+
+```bash
+npm publish --registry http://localhost:4873
+```
+
+or set `publishConfig.registry` in `package.json` for that package.
+
+Then:
+
+```bash
+yarn npm publish
+# or: npm publish
+```
+
+## 3. Install from the private registry on a developer machine
+
+In the **consumer** repo, point installs at the registry. Scoped example:
+
+```ini
+@sybilion:registry=http://localhost:4873/
+```
+
+If the registry requires auth to **read** (you enabled it in Verdaccio), add a token line as in section 4.
+
+For **local-only** workflows, some teams use **Verdaccio in Docker** or a **fixed hostname** (e.g. `registry.dev.sybilion.internal`) so URLs match between laptops and CI.
+
+## 4. Authentication tokens (needed for CI and locked-down reads)
+
+Registries use **bearer tokens**. After `npm login`, your user `.npmrc` often contains something like:
+
+```ini
+//localhost:4873/:_authToken="…"
+```
+
+For CI you should **not** commit tokens. Instead:
+
+1. Create a **read-only** user/token for install jobs and a **separate** publish token if needed.
+2. Store the token in the CI secret store (see below).
+3. At job start, write `.npmrc` or set env vars the tooling understands.
+
+**npm / Yarn (classic)** often respect:
+
+```bash
+export NODE_AUTH_TOKEN="…"
+```
+
+with an `.npmrc` in the repo or generated in CI:
+
+```ini
+@sybilion:registry=https://your-registry.example/
+//your-registry.example/:_authToken=${NODE_AUTH_TOKEN}
+always-auth=true
+```
+
+Exact host and path must match your registry URL. Verdaccio and cloud registries each document their token format.
+
+## 5. How organization CI works with a private registry
+
+High-level flow:
+
+1. **Registry URL** is fixed for the org (self-hosted Verdaccio behind HTTPS, or GitHub/GitLab/etc.).
+2. **Secrets**: store `NODE_AUTH_TOKEN` (or registry-specific secret) in:
+   - **GitHub Actions**: repository or organization secrets
+   - **GitLab CI**: CI/CD variables (masked/protected as appropriate)
+   - **Buildkite / CircleCI / Jenkins**: equivalent secret stores
+3. **Install step** runs after the token is available: `yarn install` / `npm ci` resolves scoped packages from the private registry; the rest still comes from the public npm proxy or npmjs.org.
+4. **Publishing** (if the pipeline publishes packages) uses a job with a **publish** token, often only on protected branches or tags.
+
+### GitHub Actions (illustrative)
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://npm.pkg.github.com'
+          # or your Verdaccio HTTPS URL — match .npmrc scope
+      - run: yarn install --frozen-lockfile
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: yarn test
+```
+
+Adjust `registry-url` and `.npmrc` to match **your** registry (GitHub Packages uses a specific host; self-hosted Verdaccio uses yours).
+
+### Caching
+
+CI can cache `node_modules` or Yarn’s cache **after** auth works; failed auth usually shows `401`/`403` during `yarn install`.
+
+### Lockfiles
+
+Commit **yarn.lock** / **package-lock.json** so CI installs deterministic versions. Private packages are referenced by version (or tarball URL) like public ones.
+
+## 6. Choosing local Verdaccio vs a hosted org registry
+
+| Approach                             | Good for                                               |
+| ------------------------------------ | ------------------------------------------------------ |
+| **Verdaccio on localhost**           | Quick feedback, testing publish/install before pushing |
+| **Verdaccio on a server / K8s**      | Single org registry, full control, air-gapped options  |
+| **GitHub Packages / GitLab / Azure** | Tight integration with repos, SSO, less ops            |
+
+CI for consuming repos is the same idea everywhere: **registry URL + secret token + lockfile**.
+
+## 7. GitHub Packages
+
+For GitHub-hosted npm packages (`npm.pkg.github.com`), scopes, tokens, Actions, and Docker secrets, see **[github-packages.md](./github-packages.md)**.
+
+## 8. References
+
+- [Verdaccio](https://verdaccio.org/)
+- [npm scope and `.npmrc`](https://docs.npmjs.com/cli/v10/using-npm/scope)
+- [GitHub Packages npm](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)

package/docs/workspace-mini-apps.md

@@ -0,0 +1,21 @@
+# Workspace mini-apps (Sybilion iframe)
+
+The Sybilion client embeds mini-apps in an **iframe** and syncs theme with `postMessage`. Use **`MiniAppRoot`** so this document’s `<html>` gets **`light` / `dark`** (uilib uses `.dark { … }` for tokens).
+
+1. Import **`@sybilion/uilib/mini-app-global.css`** (slim tokens + font imports; ships in this package).
+2. Wrap the React root:
+
+```tsx
+import { MiniAppRoot } from '@sybilion/uilib';
+import '@sybilion/uilib/mini-app-global.css';
+
+createRoot(document.getElementById('root')!).render(
+  <MiniAppRoot appId="my-mini-app">
+    <App />
+  </MiniAppRoot>,
+);
+```
+
+3. Optional: **`useMiniAppShellTheme()`** for **`{ theme: { mode, isDarkMode } }`** under the provider (object leaves room for more shell fields later).
+
+**Bridge:** `MiniAppRoot` handles `THEME_SYNC`, sends `READY` on mount/load, and checks `event.source === window.parent` plus `document.referrer` origin when present. If the referrer is missing (strict `Referrer-Policy`), `READY` may use `targetOrigin` `*` — document that for your host.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybilion/uilib",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",
@@ -29,9 +29,12 @@
       "import": "./src/index.ts",
       "default": "./src/index.ts"
     },
-    "./src/*": "./src/*"
+    "./src/*": "./src/*",
+    "./mini-app-global.css": "./assets/mini-app-global.css"
   },
   "files": [
+    "assets",
+    "docs",
     "src",
     "dist",
     "package.json"

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './mini-app';
 export * from './contexts/chat-context';
 export * from './types/chat-api.types';
 export * from './components/ui/AnalysesSelector';

package/src/mini-app/MiniAppRoot.tsx

@@ -0,0 +1,115 @@
+import type { ReactNode } from 'react';
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import {
+  type ThemeSyncPayload,
+  applyThemeToDocument,
+  buildReadyMessage,
+  parseThemeSyncMessage,
+  resolveParentOriginFromReferrer,
+} from './miniAppProtocol';
+
+const defaultTheme: ThemeSyncPayload = {
+  mode: 'light',
+  isDarkMode: false,
+};
+
+export type MiniAppShellContextValue = {
+  theme: ThemeSyncPayload;
+};
+
+const MiniAppShellContext = createContext<MiniAppShellContextValue | null>(
+  null,
+);
+
+export function useMiniAppShellTheme(): MiniAppShellContextValue {
+  const v = useContext(MiniAppShellContext);
+  if (!v) {
+    throw new Error('useMiniAppShellTheme must be used within MiniAppRoot');
+  }
+  return v;
+}
+
+/**
+ * Accept only messages that appear to come from the real embedding parent:
+ * - `source` must be `window.parent` (same as shell’s iframe target).
+ * - When `document.referrer` is present, `origin` must match it (Sybilion page that loaded this iframe).
+ *   If referrer was stripped (Referrer-Policy), we only rely on `source` matching `parent`.
+ */
+function isTrustedParentMessage(event: MessageEvent): boolean {
+  // Ignore messages from other windows (e.g. popups, other iframes).
+  if (event.source !== window.parent) return false;
+  const fromReferrer = resolveParentOriginFromReferrer();
+  // Tighten to embedder origin when the browser exposes it.
+  if (fromReferrer && event.origin !== fromReferrer) return false;
+  return true;
+}
+
+export type MiniAppRootProps = {
+  children: ReactNode;
+  /** Included in READY payload when set. */
+  appId?: string;
+  onThemeChange?: (theme: ThemeSyncPayload) => void;
+};
+
+export function MiniAppRoot({
+  children,
+  appId,
+  onThemeChange,
+}: MiniAppRootProps): React.ReactElement {
+  const [theme, setTheme] = useState<ThemeSyncPayload>(defaultTheme);
+  const onThemeChangeRef = useRef(onThemeChange);
+  onThemeChangeRef.current = onThemeChange;
+
+  const sendReady = useCallback(() => {
+    if (!window.parent || window.parent === window) return;
+    const payload = appId ? { appId } : {};
+    const msg = buildReadyMessage(payload);
+    const target = resolveParentOriginFromReferrer();
+
+    if (target) {
+      window.parent.postMessage(msg, target);
+    } else {
+      window.parent.postMessage(msg, '*');
+    }
+  }, [appId]);
+
+  useEffect(() => {
+    applyThemeToDocument(theme.mode);
+  }, [theme.mode]);
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      if (!isTrustedParentMessage(event)) return;
+      const parsed = parseThemeSyncMessage(event.data);
+      if (!parsed) return;
+      setTheme(parsed);
+      onThemeChangeRef.current?.(parsed);
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, []);
+
+  useEffect(() => {
+    sendReady();
+    if (document.readyState === 'complete') return;
+    window.addEventListener('load', sendReady);
+    return () => window.removeEventListener('load', sendReady);
+  }, [sendReady]);
+
+  const ctx = useMemo((): MiniAppShellContextValue => ({ theme }), [theme]);
+
+  return (
+    <MiniAppShellContext.Provider value={ctx}>
+      {children}
+    </MiniAppShellContext.Provider>
+  );
+}

package/src/mini-app/index.ts

@@ -0,0 +1,21 @@
+export {
+  applyThemeToDocument,
+  buildReadyMessage,
+  MINIAPP_CHANNEL,
+  MINIAPP_VERSION,
+  parseThemeSyncMessage,
+  resolveParentOriginFromReferrer,
+} from './miniAppProtocol';
+export type {
+  MiniAppMessageReady,
+  MiniAppMessageThemeSync,
+  ThemeSyncPayload,
+} from './miniAppProtocol';
+export {
+  MiniAppRoot,
+  useMiniAppShellTheme,
+} from './MiniAppRoot';
+export type {
+  MiniAppRootProps,
+  MiniAppShellContextValue,
+} from './MiniAppRoot';

package/src/mini-app/miniAppProtocol.ts

@@ -0,0 +1,79 @@
+/**
+ * postMessage protocol for Sybilion workspace mini-apps (iframe child).
+ * Keep in sync with sybilion-client `src/workspace/miniAppBridge.ts` (channel, version, payloads).
+ */
+
+export const MINIAPP_CHANNEL = 'sybilion.miniapp' as const;
+export const MINIAPP_VERSION = 1 as const;
+
+export type ThemeSyncPayload = {
+  mode: 'light' | 'dark';
+  isDarkMode: boolean;
+};
+
+export type MiniAppMessageReady = {
+  channel: typeof MINIAPP_CHANNEL;
+  version: typeof MINIAPP_VERSION;
+  type: 'READY';
+  payload: Record<string, unknown> | { appId?: string };
+};
+
+export type MiniAppMessageThemeSync = {
+  channel: typeof MINIAPP_CHANNEL;
+  version: typeof MINIAPP_VERSION;
+  type: 'THEME_SYNC';
+  payload: ThemeSyncPayload;
+};
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Parse parent → child THEME_SYNC (shell uses `buildThemeSyncMessage`). */
+export function parseThemeSyncMessage(data: unknown): ThemeSyncPayload | null {
+  if (!isRecord(data)) return null;
+  if (data.channel !== MINIAPP_CHANNEL) return null;
+  if (data.version !== MINIAPP_VERSION) return null;
+  if (data.type !== 'THEME_SYNC') return null;
+
+  const payload = data.payload;
+  if (!isRecord(payload)) return null;
+
+  const mode = payload.mode === 'dark' ? 'dark' : 'light';
+  const isDarkMode =
+    typeof payload.isDarkMode === 'boolean'
+      ? payload.isDarkMode
+      : mode === 'dark';
+
+  return { mode, isDarkMode };
+}
+
+/** Child → parent READY (optional `appId` for telemetry). */
+export function buildReadyMessage(
+  payload: Record<string, unknown> = {},
+): MiniAppMessageReady {
+  return {
+    channel: MINIAPP_CHANNEL,
+    version: MINIAPP_VERSION,
+    type: 'READY',
+    payload,
+  };
+}
+
+export function resolveParentOriginFromReferrer(): string | null {
+  try {
+    if (typeof document !== 'undefined' && document.referrer) {
+      return new URL(document.referrer).origin;
+    }
+  } catch {
+    /* invalid referrer */
+  }
+  return null;
+}
+
+export function applyThemeToDocument(mode: 'light' | 'dark'): void {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  root.classList.remove('light', 'dark');
+  root.classList.add(mode);
+}