broapp 0.1.0 → 0.2.0

package/src/ai/react/AiSettings.tsx

@@ -0,0 +1,222 @@
+/**
+ * The settings panel.
+ *
+ * Two things here are deliberate and worth keeping. The key input is
+ * write-only — it starts empty, is never filled in from the host, and is
+ * cleared after a save — because a key that can be read back out of the
+ * interface is a key that can be read by anything that can reach the
+ * interface. And the data notice is always visible once a provider is chosen,
+ * because "where do my notes go" is not a question a user should have to open
+ * a menu to answer.
+ */
+import * as React from 'react';
+
+import { useAiModels } from './use-ai-models.ts';
+import { useAiSettings, type ConnectionResult } from './use-ai-settings.ts';
+
+/** Shown while nothing is chosen. */
+const NOT_SET_UP = 'Not set up';
+
+export function AiSettings(): React.ReactElement {
+  const { settings, providers, pending, error, update, test } = useAiSettings();
+  const models = useAiModels();
+  const [key, setKey] = React.useState('');
+  const [baseUrl, setBaseUrl] = React.useState<string | null>(null);
+  const [result, setResult] = React.useState<ConnectionResult | null>(null);
+
+  const provider = providers.find((entry) => entry.id === settings?.provider) ?? null;
+  // The input tracks the saved value until the user types, at which point
+  // their draft wins until it is saved on blur.
+  const urlValue = baseUrl ?? settings?.baseUrl ?? '';
+
+  const onProvider = async (id: string): Promise<void> => {
+    setResult(null);
+    setBaseUrl(null);
+    setKey('');
+    await update(id === '' ? { provider: undefined } : { provider: id });
+  };
+
+  const onSaveKey = async (): Promise<void> => {
+    if (key === '') return;
+    await update({ apiKey: key });
+    setKey('');
+  };
+
+  return (
+    <section className="card ai-settings" aria-labelledby="ai-settings-title">
+      <h2 className="card__title" id="ai-settings-title">
+        AI
+      </h2>
+
+      {error !== null ? (
+        <p className="message message--error" role="alert">
+          {error.message}
+        </p>
+      ) : null}
+
+      <div className="form__row">
+        <label className="form__label" htmlFor="ai-provider">
+          Provider
+        </label>
+        <select
+          className="input input--select"
+          id="ai-provider"
+          disabled={pending}
+          value={settings?.provider ?? ''}
+          onChange={(event) => void onProvider(event.target.value)}
+        >
+          <option value="">{NOT_SET_UP}</option>
+          {providers.map((entry) => (
+            <option key={entry.id} value={entry.id}>
+              {entry.label}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {provider === null ? null : (
+        <>
+          {provider.needs.baseUrl === 'none' ? null : (
+            <div className="form__row">
+              <label className="form__label" htmlFor="ai-base-url">
+                Server address{provider.needs.baseUrl === 'required' ? ' (required)' : ''}
+              </label>
+              <input
+                className="input"
+                id="ai-base-url"
+                type="url"
+                autoComplete="off"
+                spellCheck={false}
+                disabled={pending}
+                placeholder={provider.defaultBaseUrl ?? 'http://127.0.0.1:11434/v1'}
+                value={urlValue}
+                onChange={(event) => setBaseUrl(event.target.value)}
+                onBlur={() => {
+                  if (baseUrl === null) return;
+                  const next = baseUrl.trim();
+                  setBaseUrl(null);
+                  void update({ baseUrl: next === '' ? null : next });
+                }}
+              />
+            </div>
+          )}
+
+          {!provider.needs.apiKey ? null : (
+            <div className="form__row">
+              <label className="form__label" htmlFor="ai-key">
+                API key
+              </label>
+              <div className="ai-settings__key">
+                <input
+                  className="input"
+                  id="ai-key"
+                  type="password"
+                  autoComplete="off"
+                  spellCheck={false}
+                  disabled={pending}
+                  placeholder={settings?.hasKey === true ? 'Replace the saved key' : 'Paste the key'}
+                  value={key}
+                  onChange={(event) => setKey(event.target.value)}
+                  onBlur={() => void onSaveKey()}
+                />
+                <button
+                  className="button button--primary"
+                  type="button"
+                  disabled={pending || key === ''}
+                  onClick={() => void onSaveKey()}
+                >
+                  Save key
+                </button>
+              </div>
+              {settings?.hasKey === true ? (
+                <p className="form__hint">
+                  A key ending in {settings.keyHint ?? '…'} is saved.{' '}
+                  <button
+                    className="button"
+                    type="button"
+                    disabled={pending}
+                    onClick={() => void update({ apiKey: null })}
+                  >
+                    Remove key
+                  </button>
+                </p>
+              ) : null}
+              <label className="form__label ai-settings__remember" htmlFor="ai-remember">
+                <input
+                  id="ai-remember"
+                  type="checkbox"
+                  disabled={pending}
+                  checked={settings?.remember ?? true}
+                  onChange={(event) => void update({ remember: event.target.checked })}
+                />
+                Remember key on this computer
+              </label>
+              <p className="form__hint">
+                Stored in this application&rsquo;s data folder, readable by your user account. Turn
+                off to keep it only until the app closes.
+              </p>
+            </div>
+          )}
+
+          <div className="form__row">
+            <label className="form__label" htmlFor="ai-model">
+              Model
+            </label>
+            <div className="ai-settings__key">
+              <select
+                className="input input--select"
+                id="ai-model"
+                disabled={pending || models.pending}
+                value={settings?.modelId ?? ''}
+                onChange={(event) => void update({ modelId: event.target.value })}
+              >
+                <option value="">{models.pending ? 'Loading…' : 'Choose a model'}</option>
+                {models.models.map((model) => (
+                  <option key={model.modelId} value={model.modelId}>
+                    {model.label}
+                  </option>
+                ))}
+              </select>
+              <button
+                className="button"
+                type="button"
+                disabled={models.pending}
+                onClick={() => void models.refresh()}
+              >
+                Refresh
+              </button>
+            </div>
+            {models.error === null ? null : (
+              <p className="message message--error" role="alert">
+                {models.error.message}
+              </p>
+            )}
+          </div>
+
+          <p className="ai-settings__notice" role="status">
+            {provider.local
+              ? 'Runs on this computer. Nothing is sent over the internet.'
+              : `Messages, the documents you are viewing, and search results are sent to ${provider.label} to generate answers.`}
+          </p>
+
+          <div className="form__row">
+            <button
+              className="button button--primary"
+              type="button"
+              disabled={pending}
+              onClick={() => void test().then(setResult)}
+            >
+              Test connection
+            </button>
+            {result === null ? null : (
+              <p className={`message ${result.ok ? 'message--ok' : 'message--error'}`} role="status">
+                {result.message}
+                {result.ok ? ` (${String(result.latencyMs)} ms)` : ''}
+              </p>
+            )}
+          </div>
+        </>
+      )}
+    </section>
+  );
+}

package/src/ai/react/ai.css

@@ -0,0 +1,152 @@
+/*
+ * Styles for the AI panels.
+ *
+ * Ordinary CSS, no framework, no web font, no `@import` and no `url()`: a
+ * Broapp page loads nothing from off-origin, and `broapp build` fails the
+ * build if it finds anything that would. The custom properties are the ones an
+ * application already defines for its own interface, so these panels take on
+ * its colours rather than imposing their own; the fallbacks are there so the
+ * components are still legible in an application that defines none.
+ */
+
+.ai-settings__key {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+}
+
+.ai-settings__key .input {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.ai-settings__remember {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  margin-top: 0.75rem;
+  font-weight: 400;
+}
+
+/*
+ * Always visible once a provider is chosen. "Where do my notes go" is not a
+ * question a user should have to open a menu to answer.
+ */
+.ai-settings__notice {
+  margin: 0.75rem 0;
+  padding: 0.6rem 0.75rem;
+  border: 1px solid var(--border, #e3e2df);
+  border-radius: var(--radius, 10px);
+  color: var(--text-muted, #6b6862);
+  font-size: 0.9rem;
+}
+
+.ai-chat__messages {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  max-height: 24rem;
+  overflow-y: auto;
+  padding: 0.25rem;
+}
+
+.ai-chat__message {
+  padding: 0.6rem 0.75rem;
+  border-radius: var(--radius, 10px);
+  max-width: 90%;
+}
+
+.ai-chat__message--user {
+  align-self: flex-end;
+  background: var(--accent, #1f5f4f);
+  color: var(--accent-contrast, #ffffff);
+}
+
+.ai-chat__message--assistant {
+  align-self: flex-start;
+  background: var(--surface, #ffffff);
+  border: 1px solid var(--border, #e3e2df);
+  color: var(--text, #1b1a18);
+}
+
+/*
+ * A `<pre>` rather than a markdown renderer. The text was written by a model
+ * that has just been shown documents from this machine; turning parts of it
+ * into markup would be a way for a document to reach the page.
+ */
+.ai-chat__text {
+  margin: 0;
+  font: inherit;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.ai-chat__tool {
+  margin-bottom: 0.5rem;
+  font-size: 0.9rem;
+  color: var(--text-muted, #6b6862);
+}
+
+.ai-chat__json {
+  margin: 0.4rem 0 0;
+  padding: 0.5rem;
+  border-radius: var(--radius, 10px);
+  background: var(--bg, #fbfbfa);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.8rem;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.ai-chat__confirm {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  margin-top: 0.4rem;
+  padding: 0.5rem;
+  border: 1px solid var(--pending, #8a6a12);
+  border-radius: var(--radius, 10px);
+  color: var(--text, #1b1a18);
+}
+
+.ai-chat__typing {
+  display: inline-block;
+  margin-left: 0.25rem;
+  color: var(--text-muted, #6b6862);
+  animation: ai-chat-pulse 1.2s ease-in-out infinite;
+}
+
+@keyframes ai-chat-pulse {
+  0%,
+  100% {
+    opacity: 0.35;
+  }
+  50% {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ai-chat__typing {
+    animation: none;
+  }
+}
+
+.ai-chat__usage {
+  margin: 0.5rem 0 0;
+}
+
+.ai-chat__composer {
+  margin-top: 0.75rem;
+}
+
+.ai-chat__input {
+  width: 100%;
+  resize: vertical;
+}
+
+.ai-chat__actions {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+}

package/src/ai/react/index.tsx

@@ -0,0 +1,35 @@
+/**
+ * `broapp/ai/react` — the AI layer's interface.
+ *
+ * Shared code: nothing here imports the AI SDK, and a browser bundle that
+ * follows these imports gets the contract and the components and nothing else.
+ * Pair it with `ai.css`, or write your own using the class names these
+ * components emit.
+ */
+export { AiProvider, useAiContext } from './provider.tsx';
+export type { AiClient } from './provider.tsx';
+
+export { useAiSettings } from './use-ai-settings.ts';
+export type { AiSettingsHook, ConnectionResult, UpdatePatch } from './use-ai-settings.ts';
+
+export { useAiModels } from './use-ai-models.ts';
+export type { AiModelsHook } from './use-ai-models.ts';
+
+export { useAiChat } from './use-ai-chat.ts';
+export type { AiChatHook, AiChatOptions, ChatMessage, ToolCallState } from './use-ai-chat.ts';
+
+export { AiSettings } from './AiSettings.tsx';
+export { AiChat } from './AiChat.tsx';
+export type { AiChatProps } from './AiChat.tsx';
+
+// Re-exported so an application needs one import to install the extension.
+export { aiContract } from '../shared/index.ts';
+export type {
+  AiContract,
+  AiSettings as AiSettingsValue,
+  BroappModel,
+  ChatEvent,
+  ChatTurn,
+  ProviderInfo,
+  ToolPermission,
+} from '../shared/index.ts';

package/src/ai/react/provider.tsx

@@ -0,0 +1,97 @@
+/**
+ * Shared AI state for everything below it.
+ *
+ * The settings panel and the chat panel both need to know whether AI is
+ * configured, and they must not disagree — a chat that says "not set up" next
+ * to a panel that just saved a key is worse than either alone. So the settings
+ * are fetched once, here, and both read them from the same place.
+ */
+import * as React from 'react';
+
+import type { BroappClient } from '../../client/client.ts';
+import { BroappError } from '../../shared/errors.ts';
+import { useBroapp, useBroappContract, useBroappReady, useConnection } from '../../react/hooks.tsx';
+import type { AiContract } from '../shared/contract.ts';
+import type { AiSettings } from '../shared/types.ts';
+
+/** The AI client: the same connection, typed against the AI contract. */
+export type AiClient = BroappClient<AiContract>;
+
+interface AiContextValue {
+  readonly settings: AiSettings | null;
+  readonly error: BroappError | null;
+  readonly loading: boolean;
+  refresh(): Promise<void>;
+  /** Write the settings other hooks just fetched, so one round trip serves all. */
+  put(settings: AiSettings): void;
+  client(): Promise<AiClient>;
+}
+
+const AiContext = React.createContext<AiContextValue | null>(null);
+
+/** The route every installation of the AI contract has. */
+const PROBE_ROUTE = 'ai.settingsGet';
+
+const MISSING_CONTRACT =
+  'AiProvider needs the AI contract: <BroappProvider contract={contract} extensions={[aiContract]}>';
+
+/** Owns the AI settings for the components below it. */
+export function AiProvider({ children }: { children: React.ReactNode }): React.ReactElement {
+  const contract = useBroappContract();
+  if (!Object.prototype.hasOwnProperty.call(contract.operations, PROBE_ROUTE)) {
+    // Thrown at render rather than at the first call: the mistake is in the
+    // provider setup, and that is where a developer should be sent.
+    throw new Error(MISSING_CONTRACT);
+  }
+
+  const broapp = useBroapp<AiContract>();
+  const ready = useBroappReady<AiContract>();
+  const connection = useConnection();
+  const [settings, setSettings] = React.useState<AiSettings | null>(null);
+  const [error, setError] = React.useState<BroappError | null>(null);
+  const [loading, setLoading] = React.useState(false);
+
+  const client = React.useCallback(
+    async (): Promise<AiClient> => broapp ?? (await ready),
+    [broapp, ready],
+  );
+
+  const refresh = React.useCallback(async (): Promise<void> => {
+    setLoading(true);
+    try {
+      const connected = await client();
+      setSettings(await connected.call('ai.settingsGet', undefined));
+      setError(null);
+    } catch (cause) {
+      setError(
+        cause instanceof BroappError
+          ? cause
+          : new BroappError('internal', 'The AI settings could not be read.', cause),
+      );
+    } finally {
+      setLoading(false);
+    }
+  }, [client]);
+
+  // Once, when there is something to talk to. A settings read before the
+  // connection settles would only fail and have to be retried.
+  const fetched = React.useRef(false);
+  React.useEffect(() => {
+    if (connection.phase !== 'ready' || fetched.current) return;
+    fetched.current = true;
+    void refresh();
+  }, [connection.phase, refresh]);
+
+  const value = React.useMemo<AiContextValue>(
+    () => ({ settings, error, loading, refresh, put: setSettings, client }),
+    [settings, error, loading, refresh, client],
+  );
+  return <AiContext.Provider value={value}>{children}</AiContext.Provider>;
+}
+
+/** The shared AI state. Throws outside {@link AiProvider}. */
+export function useAiContext(): AiContextValue {
+  const value = React.useContext(AiContext);
+  if (value === null) throw new Error('This hook must be used inside <AiProvider>');
+  return value;
+}