@fatagnus/dink-ui-core 2.32.0

package/README.md

@@ -0,0 +1,93 @@
+# @fatagnus/dink-ui-core
+
+Adaptive shell, workspace/room manager, and Mantine theme for Dink apps. Provides the layout infrastructure that sits between the semantic layer and your application components.
+
+## Install
+
+```bash
+npm install @fatagnus/dink-ui-core
+```
+
+Peer dependencies: `@fatagnus/dink-semantic`, `@fatagnus/dink-web`, `react`, `react-dom`.
+
+## Quick Start
+
+```tsx
+import { MantineProvider } from '@mantine/core';
+import { SemRoot } from '@fatagnus/dink-semantic';
+import { createDinkTheme, SurfaceProvider, WorkspaceProvider, WorkspaceShell, Room } from '@fatagnus/dink-ui-core';
+
+const theme = createDinkTheme();
+
+function App() {
+  return (
+    <MantineProvider theme={theme} defaultColorScheme="dark">
+      <SemRoot app="my-app" version="1.0.0">
+        <SurfaceProvider>
+          <WorkspaceProvider>
+            <WorkspaceShell>
+              <Room id="alerts" label="Alerts">
+                <AlertsPage />
+              </Room>
+            </WorkspaceShell>
+          </WorkspaceProvider>
+        </SurfaceProvider>
+      </SemRoot>
+    </MantineProvider>
+  );
+}
+```
+
+## Key Exports
+
+### Theme (`./theme`)
+
+| Export | Description |
+|---|---|
+| `createDinkTheme()` | Returns a Mantine v7 theme with Dink color palette and defaults |
+| `dinkColors` / `dinkSurfaceColors` | Raw color tokens |
+
+### Adaptive Surface
+
+| Export | Description |
+|---|---|
+| `SurfaceProvider` | Detects current surface (desktop/tablet/mobile) and provides context |
+| `useSurface()` | Access current `SurfaceInfo` |
+| `defineAdaptivePage(config)` | Declare a page component with per-surface layouts |
+| `AdaptivePage` | Renders the correct layout for the current surface |
+
+### Workspace & Rooms
+
+| Export | Description |
+|---|---|
+| `WorkspaceProvider` | MobX-backed workspace state (rooms, layout, navigation) |
+| `WorkspaceShell` | AppShell wrapper with sidebar, header, room tabs |
+| `Room` | Declares a navigable room within the workspace |
+| `PluginSlot` | Mounting point for third-party plugin content |
+| `useWorkspace()` / `useRoom()` | Access workspace and room state |
+| `WorkspaceStore` | MobX store class for direct access |
+
+### Auth (`./auth`)
+
+| Export | Description |
+|---|---|
+| `useAuth()` | Current user identity and session from Dink backend |
+| `useCan(permission)` | Permission check hook |
+
+### Connection (`./connection`)
+
+| Export | Description |
+|---|---|
+| `useConnectionState()` | NATS/WebSocket connection status |
+| `ConnectionBanner` | Auto-show banner on disconnect/reconnect |
+
+## Subpath Exports
+
+- `.` -- Everything
+- `./theme` -- Theme only
+- `./auth` -- Auth hooks only
+- `./connection` -- Connection hooks and banner
+
+## Design Spec
+
+[docs/superpowers/specs/2026-03-16-dink-frontend-framework-design.md](../../docs/superpowers/specs/2026-03-16-dink-frontend-framework-design.md)

package/dist/__stubs__/dink-web-auth-react.d.ts

@@ -0,0 +1,5 @@
+export declare function useDinkAuth(): {
+    user: null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+};

package/dist/__stubs__/dink-web-auth-react.js

@@ -0,0 +1,9 @@
+// Stub for @fatagnus/dink-web/dink-auth-react
+// Real implementation is provided by dink-web; tests mock this module.
+export function useDinkAuth() {
+    return {
+        user: null,
+        isAuthenticated: false,
+        isLoading: true,
+    };
+}

package/dist/__stubs__/dink-web-authz-react.d.ts

@@ -0,0 +1,3 @@
+export declare function useDinkAuthZ(): {
+    can: () => boolean;
+};

package/dist/__stubs__/dink-web-authz-react.js

@@ -0,0 +1,7 @@
+// Stub for @fatagnus/dink-web/dink-authz-react
+// Real implementation is provided by dink-web; tests mock this module.
+export function useDinkAuthZ() {
+    return {
+        can: () => true,
+    };
+}

package/dist/__stubs__/dink-web-react.d.ts

@@ -0,0 +1,6 @@
+export declare function useDinkWeb(): {
+    client: null;
+    status: "connected";
+    stats: {};
+    error: null;
+};

package/dist/__stubs__/dink-web-react.js

@@ -0,0 +1,10 @@
+// Stub for @fatagnus/dink-web/react
+// Real implementation is provided by dink-web; tests mock this module.
+export function useDinkWeb() {
+    return {
+        client: null,
+        status: 'connected',
+        stats: {},
+        error: null,
+    };
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,12 @@
+export { useAuth } from './use-auth.js';
+export type { AuthInfo, AuthUser } from './use-auth.js';
+export { useCan } from './use-can.js';
+export type { CanResult } from './use-can.js';
+export { useCapabilityToken } from './use-capability-token.js';
+export type { UseCapabilityTokenOptions, UseCapabilityTokenResult, CapabilityTokenClaims } from './use-capability-token.js';
+export { usePermissionCheck } from './use-permission-check.js';
+export type { UsePermissionCheckOptions, UsePermissionCheckResult } from './use-permission-check.js';
+export { withPermission } from './with-permission.js';
+export { checkPermission } from './permission-check.js';
+export type { PermissionClaims, PermissionResult } from './permission-check.js';
+export { TokenRefreshManager } from './token-refresh.js';

package/dist/auth/index.js

@@ -0,0 +1,7 @@
+export { useAuth } from './use-auth.js';
+export { useCan } from './use-can.js';
+export { useCapabilityToken } from './use-capability-token.js';
+export { usePermissionCheck } from './use-permission-check.js';
+export { withPermission } from './with-permission.js';
+export { checkPermission } from './permission-check.js';
+export { TokenRefreshManager } from './token-refresh.js';

package/dist/auth/permission-check.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure permission check function.
+ * Evaluates whether a JWT's claims grant a specific scope on a resource.
+ */
+export interface PermissionClaims {
+    sub: string;
+    iss: string;
+    aud: string;
+    exp: number;
+    iat: number;
+    scopes?: string[];
+    resources?: string[];
+}
+export interface PermissionResult {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Check whether claims grant the requested scope on the given resource.
+ *
+ * Scope matching:
+ * - Wildcard `*` in scopes matches any scope
+ * - `scope:kind` pattern (e.g. `read:tasks`) matches if scope matches
+ *   the requested scope and kind matches the resource scheme
+ *
+ * Resource matching:
+ * - Wildcard `*` in resources matches any resource
+ * - `scheme://*` pattern matches any resource with that scheme
+ * - Exact match on full URI
+ */
+export declare function checkPermission(claims: PermissionClaims, scope: string, resource: string): PermissionResult;

package/dist/auth/permission-check.js

@@ -0,0 +1,79 @@
+/**
+ * Pure permission check function.
+ * Evaluates whether a JWT's claims grant a specific scope on a resource.
+ */
+/**
+ * Check whether claims grant the requested scope on the given resource.
+ *
+ * Scope matching:
+ * - Wildcard `*` in scopes matches any scope
+ * - `scope:kind` pattern (e.g. `read:tasks`) matches if scope matches
+ *   the requested scope and kind matches the resource scheme
+ *
+ * Resource matching:
+ * - Wildcard `*` in resources matches any resource
+ * - `scheme://*` pattern matches any resource with that scheme
+ * - Exact match on full URI
+ */
+export function checkPermission(claims, scope, resource) {
+    // Check token expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (claims.exp <= now) {
+        return { allowed: false, reason: 'Token expired' };
+    }
+    const claimScopes = claims.scopes ?? [];
+    const claimResources = claims.resources ?? [];
+    // Check scope match
+    const scopeMatched = matchScope(claimScopes, scope, resource);
+    if (!scopeMatched) {
+        return { allowed: false, reason: `Scope '${scope}' not granted` };
+    }
+    // Check resource match
+    const resourceMatched = matchResource(claimResources, resource);
+    if (!resourceMatched) {
+        return { allowed: false, reason: `Resource '${resource}' not granted` };
+    }
+    return { allowed: true };
+}
+function matchScope(claimScopes, requestedScope, resource) {
+    for (const s of claimScopes) {
+        if (s === '*')
+            return true;
+        // Pattern: `scope:kind` e.g. `read:tasks`
+        const colonIdx = s.indexOf(':');
+        if (colonIdx !== -1) {
+            const scopePart = s.substring(0, colonIdx);
+            const kindPart = s.substring(colonIdx + 1);
+            // scope matches if the scope part matches the requested scope
+            // and the kind matches the resource scheme prefix
+            if (scopePart === requestedScope || scopePart === '*') {
+                const resourceScheme = resource.split('://')[0];
+                if (kindPart === '*' || kindPart === resourceScheme || resource.startsWith(kindPart)) {
+                    return true;
+                }
+            }
+        }
+        else {
+            // Exact scope match
+            if (s === requestedScope)
+                return true;
+        }
+    }
+    return false;
+}
+function matchResource(claimResources, requestedResource) {
+    for (const r of claimResources) {
+        if (r === '*')
+            return true;
+        // Pattern: `scheme://*` — wildcard for all resources under that scheme
+        if (r.endsWith('://*')) {
+            const scheme = r.slice(0, -4); // remove `://*`
+            if (requestedResource.startsWith(scheme + '://'))
+                return true;
+        }
+        // Exact match
+        if (r === requestedResource)
+            return true;
+    }
+    return false;
+}

package/dist/auth/token-refresh.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TokenRefreshManager — schedules token refresh callbacks before expiry.
+ *
+ * Decodes the JWT exp claim and fires a callback at 80% of TTL.
+ */
+export declare class TokenRefreshManager {
+    private timers;
+    /**
+     * Monitor a JWT token and call `onRefresh` at 80% of its TTL.
+     * Returns an unsubscribe function that cancels the scheduled callback.
+     */
+    monitor(token: string, onRefresh: () => void): () => void;
+    /** Clear all scheduled refresh timers. */
+    destroy(): void;
+}
+/**
+ * Decode JWT claims from a token string (base64url decode of second segment).
+ * Returns null if the token is malformed.
+ */
+export declare function decodeJwtClaims(token: string): Record<string, unknown> | null;

package/dist/auth/token-refresh.js

@@ -0,0 +1,62 @@
+/**
+ * TokenRefreshManager — schedules token refresh callbacks before expiry.
+ *
+ * Decodes the JWT exp claim and fires a callback at 80% of TTL.
+ */
+export class TokenRefreshManager {
+    timers = new Set();
+    /**
+     * Monitor a JWT token and call `onRefresh` at 80% of its TTL.
+     * Returns an unsubscribe function that cancels the scheduled callback.
+     */
+    monitor(token, onRefresh) {
+        const claims = decodeJwtClaims(token);
+        if (!claims || typeof claims.exp !== 'number') {
+            return () => { };
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const ttl = claims.exp - now;
+        if (ttl <= 0) {
+            // Already expired, fire immediately
+            onRefresh();
+            return () => { };
+        }
+        // Schedule refresh at 80% of TTL
+        const refreshAt = Math.floor(ttl * 0.8) * 1000;
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            onRefresh();
+        }, refreshAt);
+        this.timers.add(timer);
+        return () => {
+            clearTimeout(timer);
+            this.timers.delete(timer);
+        };
+    }
+    /** Clear all scheduled refresh timers. */
+    destroy() {
+        for (const timer of this.timers) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+    }
+}
+/**
+ * Decode JWT claims from a token string (base64url decode of second segment).
+ * Returns null if the token is malformed.
+ */
+export function decodeJwtClaims(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return null;
+        const payload = parts[1];
+        // Handle base64url encoding
+        const padded = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const decoded = atob(padded);
+        return JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/auth/use-auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Unified auth hook wrapping dink-web's auth context.
+ *
+ * This is a thin wrapper that re-surfaces the existing auth
+ * in a convenient shape for shell components.
+ */
+export interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+    role?: string;
+}
+export interface AuthInfo {
+    user: AuthUser | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+}
+/**
+ * Returns the current auth state from the underlying DinkAuth context.
+ */
+export declare function useAuth(): AuthInfo;

package/dist/auth/use-auth.js

@@ -0,0 +1,20 @@
+/**
+ * Unified auth hook wrapping dink-web's auth context.
+ *
+ * This is a thin wrapper that re-surfaces the existing auth
+ * in a convenient shape for shell components.
+ */
+// We use dynamic import resolution -- the mock in tests will replace this module.
+// In production, @fatagnus/dink-web/dink-auth-react provides useDinkAuth.
+import { useDinkAuth } from '@fatagnus/dink-web/dink-auth-react';
+/**
+ * Returns the current auth state from the underlying DinkAuth context.
+ */
+export function useAuth() {
+    const auth = useDinkAuth();
+    return {
+        user: auth.user,
+        isAuthenticated: auth.isAuthenticated,
+        isLoading: auth.isLoading,
+    };
+}

package/dist/auth/use-can.d.ts

@@ -0,0 +1,11 @@
+export interface CanResult {
+    allowed: boolean;
+}
+/**
+ * Evaluates a permission check and returns whether the action is allowed.
+ *
+ * @example
+ * const { allowed } = useCan('write', 'tasks');
+ * <Button disabled={!allowed}>Create Task</Button>
+ */
+export declare function useCan(scope: string, resource: string): CanResult;

package/dist/auth/use-can.js

@@ -0,0 +1,25 @@
+/**
+ * Permission-gating hook for Dink UI components.
+ *
+ * Wraps the underlying authz context. Uses the authz client's
+ * simulate() method to check permissions.
+ */
+import { useDinkAuthZ } from '@fatagnus/dink-web/dink-authz-react';
+/**
+ * Evaluates a permission check and returns whether the action is allowed.
+ *
+ * @example
+ * const { allowed } = useCan('write', 'tasks');
+ * <Button disabled={!allowed}>Create Task</Button>
+ */
+export function useCan(scope, resource) {
+    const authz = useDinkAuthZ();
+    // The authz context provides a `can` method when available,
+    // falling back to always-allowed when no authz is configured.
+    const can = authz.can;
+    if (typeof can === 'function') {
+        return { allowed: can(scope, resource) };
+    }
+    // Default: allowed (no authz configured)
+    return { allowed: true };
+}

package/dist/auth/use-capability-token.d.ts

@@ -0,0 +1,38 @@
+/**
+ * useCapabilityToken() — React hook for token lifecycle management.
+ *
+ * Acquires a capability token, decodes JWT claims, tracks expiry,
+ * auto-refreshes via TokenRefreshManager, and provides manual refresh/revoke.
+ */
+export interface CapabilityTokenClaims {
+    sub: string;
+    iss: string;
+    aud: string;
+    exp: number;
+    iat: number;
+    scopes?: string[];
+    resources?: string[];
+}
+export interface UseCapabilityTokenOptions {
+    scopes: string[];
+    resources: string[];
+    autoRefresh?: boolean;
+    ttlSeconds?: number;
+    onRefresh?: (token: string) => void;
+    onRefreshError?: (error: Error) => void;
+}
+export interface UseCapabilityTokenResult {
+    token: string | null;
+    state: 'loading' | 'valid' | 'expired' | 'refreshing' | 'error';
+    expiresIn: number | null;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    revoke: () => Promise<void>;
+    claims: CapabilityTokenClaims | null;
+}
+type GetTokenFn = (options: {
+    scopes: string[];
+    resources: string[];
+}) => Promise<string>;
+export declare function useCapabilityToken(options: UseCapabilityTokenOptions, getToken: GetTokenFn): UseCapabilityTokenResult;
+export {};

package/dist/auth/use-capability-token.js

@@ -0,0 +1,134 @@
+/**
+ * useCapabilityToken() — React hook for token lifecycle management.
+ *
+ * Acquires a capability token, decodes JWT claims, tracks expiry,
+ * auto-refreshes via TokenRefreshManager, and provides manual refresh/revoke.
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { TokenRefreshManager, decodeJwtClaims } from './token-refresh.js';
+export function useCapabilityToken(options, getToken) {
+    const [token, setToken] = useState(null);
+    const [state, setState] = useState('loading');
+    const [error, setError] = useState(null);
+    const [claims, setClaims] = useState(null);
+    const [expiresIn, setExpiresIn] = useState(null);
+    const managerRef = useRef(null);
+    const intervalRef = useRef(null);
+    const unsubRef = useRef(null);
+    // Stable refs for callback parameters to avoid dependency loops
+    const getTokenRef = useRef(getToken);
+    getTokenRef.current = getToken;
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const autoRefresh = options.autoRefresh ?? true;
+    const processToken = useCallback((raw) => {
+        const decoded = decodeJwtClaims(raw);
+        if (!decoded) {
+            setError(new Error('Failed to decode token'));
+            setState('error');
+            return;
+        }
+        const tokenClaims = {
+            sub: decoded.sub,
+            iss: decoded.iss,
+            aud: decoded.aud,
+            exp: decoded.exp,
+            iat: decoded.iat,
+            scopes: decoded.scopes,
+            resources: decoded.resources,
+        };
+        setToken(raw);
+        setClaims(tokenClaims);
+        setState('valid');
+        setError(null);
+        // Update expiresIn immediately
+        const now = Math.floor(Date.now() / 1000);
+        setExpiresIn(Math.max(0, tokenClaims.exp - now));
+    }, []);
+    const acquire = useCallback(async () => {
+        const opts = optionsRef.current;
+        const getFn = getTokenRef.current;
+        try {
+            const raw = await getFn({ scopes: opts.scopes, resources: opts.resources });
+            processToken(raw);
+            return raw;
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            setState('error');
+            opts.onRefreshError?.(e);
+            return null;
+        }
+    }, [processToken]);
+    // Initial acquisition — runs once
+    useEffect(() => {
+        setState('loading');
+        acquire();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Expiry countdown
+    useEffect(() => {
+        if (claims?.exp == null)
+            return;
+        intervalRef.current = setInterval(() => {
+            const now = Math.floor(Date.now() / 1000);
+            const remaining = Math.max(0, claims.exp - now);
+            setExpiresIn(remaining);
+            if (remaining === 0) {
+                setState('expired');
+            }
+        }, 1000);
+        return () => {
+            if (intervalRef.current)
+                clearInterval(intervalRef.current);
+        };
+    }, [claims?.exp]);
+    // Auto-refresh via TokenRefreshManager
+    useEffect(() => {
+        if (!autoRefresh || !token)
+            return;
+        if (!managerRef.current) {
+            managerRef.current = new TokenRefreshManager();
+        }
+        unsubRef.current = managerRef.current.monitor(token, async () => {
+            setState('refreshing');
+            const newToken = await acquire();
+            if (newToken) {
+                optionsRef.current.onRefresh?.(newToken);
+            }
+        });
+        return () => {
+            unsubRef.current?.();
+        };
+    }, [autoRefresh, token, acquire]);
+    // Cleanup
+    useEffect(() => {
+        return () => {
+            managerRef.current?.destroy();
+        };
+    }, []);
+    const refresh = useCallback(async () => {
+        setState('refreshing');
+        const newToken = await acquire();
+        if (newToken) {
+            optionsRef.current.onRefresh?.(newToken);
+        }
+    }, [acquire]);
+    const revoke = useCallback(async () => {
+        setToken(null);
+        setClaims(null);
+        setExpiresIn(null);
+        setState('loading');
+        unsubRef.current?.();
+    }, []);
+    return {
+        token,
+        state,
+        expiresIn,
+        error,
+        refresh,
+        revoke,
+        claims,
+    };
+}

package/dist/auth/use-permission-check.d.ts

@@ -0,0 +1,19 @@
+/**
+ * usePermissionCheck() — React hook for evaluating permissions against JWT claims.
+ *
+ * Decodes JWT claims from a token string, calls checkPermission(),
+ * and provides cached permission results.
+ */
+export interface UsePermissionCheckOptions {
+    token: string | null;
+    scope: string;
+    resource: string;
+    cacheTtl?: number;
+}
+export interface UsePermissionCheckResult {
+    allowed: boolean;
+    isLoading: boolean;
+    reason?: string;
+    recheck: () => void;
+}
+export declare function usePermissionCheck(options: UsePermissionCheckOptions): UsePermissionCheckResult;