@celljs/ta-web 0.0.0-stage → 4.6.1

package/src/browser/pwa/pwa.ts

@@ -0,0 +1,123 @@
+import { Component } from '@celljs/core';
+import { type PwaState, TaPwa } from './pwa-protocol';
+
+/** The event of `beforeinstallprompt`, which only Chromium browsers have. */
+interface InstallPromptEvent extends Event {
+    prompt(): Promise<void>;
+    readonly userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
+}
+
+/** The files of `public/`, relative to the page's `<base>`. */
+export const PWA_FILES = {
+    manifest: 'manifest.webmanifest',
+    serviceWorker: 'sw.js',
+    appleTouchIcon: 'icons/apple-touch-icon.png',
+};
+
+export namespace PwaUtil {
+    /** The URLs of the files of the app, for the page at `base` (document.baseURI). */
+    export function urls(base: string): typeof PWA_FILES {
+        return {
+            manifest: new URL(PWA_FILES.manifest, base).href,
+            serviceWorker: new URL(PWA_FILES.serviceWorker, base).href,
+            appleTouchIcon: new URL(PWA_FILES.appleTouchIcon, base).href,
+        };
+    }
+
+    /**
+     * Service workers run only in a secure context: HTTPS, or this machine (127.0.0.1, localhost). On
+     * plain HTTP to another host the page is a page.
+     */
+    export function canRegister(secure: boolean, hasServiceWorker: boolean): boolean {
+        return secure && hasServiceWorker;
+    }
+
+    /** `display-mode: standalone`, or Safari's own flag on iOS. */
+    export function standalone(matches: (query: string) => boolean, iosStandalone?: boolean): boolean {
+        return matches('(display-mode: standalone)') || matches('(display-mode: window-controls-overlay)') || iosStandalone === true;
+    }
+}
+
+@Component(TaPwa)
+export class TaPwaImpl implements TaPwa {
+    protected current: PwaState = { installable: false, standalone: false };
+    protected prompt?: InstallPromptEvent;
+    protected started = false;
+    protected readonly listeners = new Set<(state: PwaState) => void>();
+
+    get state(): PwaState {
+        return this.current;
+    }
+
+    subscribe(listener: (state: PwaState) => void): () => void {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    start(): void {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        const urls = PwaUtil.urls(document.baseURI);
+        this.link('manifest', urls.manifest);
+        this.link('apple-touch-icon', urls.appleTouchIcon);
+        this.meta('apple-mobile-web-app-capable', 'yes');
+        this.meta('apple-mobile-web-app-title', 'Ta');
+        this.meta('apple-mobile-web-app-status-bar-style', 'default');
+        const standalone = () => PwaUtil.standalone(query => matchMedia(query).matches, (navigator as { standalone?: boolean }).standalone);
+        this.update({ standalone: standalone() });
+        matchMedia('(display-mode: standalone)').addEventListener('change', () => this.update({ standalone: standalone() }));
+        window.addEventListener('beforeinstallprompt', event => {
+            // Shown from the account menu instead of the browser's own bar.
+            event.preventDefault();
+            this.prompt = event as InstallPromptEvent;
+            this.update({ installable: true });
+        });
+        window.addEventListener('appinstalled', () => {
+            this.prompt = undefined;
+            this.update({ installable: false });
+        });
+        if (PwaUtil.canRegister(isSecureContext, 'serviceWorker' in navigator)) {
+            navigator.serviceWorker.register(urls.serviceWorker, { scope: new URL('./', document.baseURI).pathname }).catch(error => {
+                console.warn('ta: the service worker did not register:', error);
+            });
+        }
+    }
+
+    async install(): Promise<boolean> {
+        const prompt = this.prompt;
+        if (!prompt) {
+            return false;
+        }
+        this.prompt = undefined;
+        this.update({ installable: false });
+        await prompt.prompt();
+        return (await prompt.userChoice).outcome === 'accepted';
+    }
+
+    protected link(rel: string, href: string): void {
+        if (!document.head.querySelector(`link[rel="${rel}"]`)) {
+            const link = document.createElement('link');
+            link.rel = rel;
+            link.href = href;
+            document.head.appendChild(link);
+        }
+    }
+
+    protected meta(name: string, content: string): void {
+        if (!document.head.querySelector(`meta[name="${name}"]`)) {
+            const meta = document.createElement('meta');
+            meta.name = name;
+            meta.content = content;
+            document.head.appendChild(meta);
+        }
+    }
+
+    protected update(change: Partial<PwaState>): void {
+        this.current = { ...this.current, ...change };
+        for (const listener of this.listeners) {
+            listener(this.current);
+        }
+    }
+}

package/src/browser/settings/agent-settings.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'bun:test';
+import { TA_SETTINGS, type TaSettingsSnapshot } from '@celljs/ta-protocol';
+import { EN_MESSAGES, ZH_MESSAGES } from '../i18n/messages';
+import { AGENT_SETTINGS_GROUPS, AgentSettingsUtil, ShortcutUtil } from './agent-settings';
+
+const snapshot: TaSettingsSnapshot = {
+    user: { 'retry.enabled': false, model: 'a/b' },
+    project: { model: 'c/d' },
+    cwd: '/p',
+    userFile: '/u/settings.json',
+    projectFile: '/p/.ta/settings.json',
+    projectTrusted: true,
+    models: [],
+};
+
+describe('AgentSettingsUtil', () => {
+    it('lists every setting of ta once, with words in both languages', () => {
+        const keys = AGENT_SETTINGS_GROUPS.flatMap(group => group.keys);
+        expect([...keys].sort()).toEqual(TA_SETTINGS.map(spec => spec.key).sort());
+        for (const key of keys) {
+            expect(EN_MESSAGES[AgentSettingsUtil.label(key)]).toBeString();
+            const hint = AgentSettingsUtil.hint(key);
+            if (hint) {
+                expect(ZH_MESSAGES[hint]).toBeString();
+            }
+        }
+    });
+
+    it('says where a value comes from: the file shown, the user under a project, or the default of pi', () => {
+        expect(AgentSettingsUtil.effective(snapshot, 'project', 'model')).toEqual({ value: 'c/d', source: 'scope' });
+        expect(AgentSettingsUtil.effective(snapshot, 'project', 'retry.enabled')).toEqual({ value: false, source: 'user' });
+        expect(AgentSettingsUtil.effective(snapshot, 'user', 'compaction.enabled')).toEqual({ value: true, source: 'default' });
+        expect(AgentSettingsUtil.effective(snapshot, 'user', 'shellPath')).toEqual({ value: undefined, source: 'none' });
+    });
+
+    it('names the values of a choice where it has words for them', () => {
+        expect(AgentSettingsUtil.valueLabel('defaultThinkingLevel', 'high')).toBe('ta.setting.defaultThinkingLevel.high');
+        expect(AgentSettingsUtil.valueLabel('transport', 'sse')).toBeUndefined();
+    });
+
+    it('finds a setting by every word of the query', () => {
+        expect(AgentSettingsUtil.matches('auto comp', 'Compact automatically')).toBe(true);
+        expect(AgentSettingsUtil.matches('auto shell', 'Compact automatically')).toBe(false);
+        expect(AgentSettingsUtil.matches('  ', 'anything')).toBe(true);
+    });
+});
+
+describe('ShortcutUtil', () => {
+    it('writes keys as the platform does', () => {
+        expect(ShortcutUtil.keys('Mod+B', true)).toEqual(['⌘', 'B']);
+        expect(ShortcutUtil.keys('Mod+,', false)).toEqual(['Ctrl', ',']);
+        expect(ShortcutUtil.keys('Alt+Enter', true)).toEqual(['⌥', 'Enter']);
+        expect(ShortcutUtil.isMac('MacIntel')).toBe(true);
+        expect(ShortcutUtil.isMac('Win32')).toBe(false);
+    });
+});

package/src/browser/settings/agent-settings.ts

@@ -0,0 +1,96 @@
+import { TA_SETTINGS, type TaSettingSpec, type TaSettingsScope, type TaSettingsSnapshot } from '@celljs/ta-protocol';
+import { EN_MESSAGES, type MessageId } from '../i18n/messages';
+
+/** A group of the settings of ta, as the settings view lists them. */
+export interface AgentSettingsGroup {
+    id: string;
+    title: MessageId;
+    keys: readonly string[];
+}
+
+export const AGENT_SETTINGS_GROUPS: readonly AgentSettingsGroup[] = [
+    { id: 'model', title: 'ta.settings.group.model', keys: ['model', 'defaultThinkingLevel', 'transport'] },
+    { id: 'conversation', title: 'ta.settings.group.conversation', keys: ['steeringMode', 'followUpMode'] },
+    {
+        id: 'context',
+        title: 'ta.settings.group.context',
+        keys: ['compaction.enabled', 'compaction.reserveTokens', 'compaction.keepRecentTokens', 'retry.enabled', 'retry.maxRetries'],
+    },
+    {
+        id: 'tools',
+        title: 'ta.settings.group.tools',
+        keys: ['codemode.mode', 'enableSkillCommands', 'shellPath', 'shellCommandPrefix', 'images.autoResize', 'images.blockImages'],
+    },
+];
+
+/** What a setting is in a scope, and where that comes from. */
+export interface EffectiveSetting {
+    value: unknown;
+    /** `scope`: the file of the scope shown sets it; `user`: a project follows the user; `default`: pi's. */
+    source: 'scope' | 'user' | 'default' | 'none';
+}
+
+export namespace AgentSettingsUtil {
+    export function spec(key: string): TaSettingSpec | undefined {
+        return TA_SETTINGS.find(candidate => candidate.key === key);
+    }
+
+    export function effective(snapshot: TaSettingsSnapshot, scope: TaSettingsScope, key: string): EffectiveSetting {
+        const own = snapshot[scope][key];
+        return own === undefined ? inherited(snapshot, scope, key) : { value: own, source: 'scope' };
+    }
+
+    /** What the setting is when the file of the scope does not set it. */
+    export function inherited(snapshot: TaSettingsSnapshot, scope: TaSettingsScope, key: string): EffectiveSetting {
+        if (scope === 'project' && snapshot.user[key] !== undefined) {
+            return { value: snapshot.user[key], source: 'user' };
+        }
+        const fallback = spec(key)?.default;
+        return fallback === undefined ? { value: undefined, source: 'none' } : { value: fallback, source: 'default' };
+    }
+
+    export function label(key: string): MessageId {
+        return `ta.setting.${key}` as MessageId;
+    }
+
+    /** Its description, when it has one. */
+    export function hint(key: string): MessageId | undefined {
+        const id = `ta.setting.${key}.hint`;
+        return id in EN_MESSAGES ? (id as MessageId) : undefined;
+    }
+
+    /** The words for a value of a choice, when there are some; else the value is shown as it is. */
+    export function valueLabel(key: string, value: string): MessageId | undefined {
+        const id = `ta.setting.${key}.${value}`;
+        return id in EN_MESSAGES ? (id as MessageId) : undefined;
+    }
+
+    /** Whether a query finds any of these words: every word of it, anywhere. */
+    export function matches(query: string, ...texts: (string | undefined)[]): boolean {
+        const words = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+        const haystack = texts.filter(Boolean).join(' ').toLowerCase();
+        return words.every(word => haystack.includes(word));
+    }
+}
+
+/** How a key is written on this machine: ⌘ on a Mac, Ctrl elsewhere. */
+export namespace ShortcutUtil {
+    export function isMac(platform = typeof navigator === 'undefined' ? '' : navigator.platform): boolean {
+        return /mac|iphone|ipad/i.test(platform);
+    }
+
+    export function keys(shortcut: string, mac = isMac()): string[] {
+        return shortcut.split('+').map(key => {
+            switch (key) {
+                case 'Mod':
+                    return mac ? '⌘' : 'Ctrl';
+                case 'Alt':
+                    return mac ? '⌥' : 'Alt';
+                case 'Shift':
+                    return mac ? '⇧' : 'Shift';
+                default:
+                    return key;
+            }
+        });
+    }
+}

package/src/browser/settings/settings-protocol.ts

@@ -0,0 +1,75 @@
+import type { StateSpec } from '../state/state-protocol';
+
+export const TaSettings = Symbol('TaSettings');
+
+export type ThemeSetting = 'system' | 'light' | 'dark';
+export type Theme = 'light' | 'dark';
+export type LanguageSetting = 'system' | Language;
+export type Language = 'zh-CN' | 'en-US';
+
+/** What the user chose; kept for the user, in every browser (TaState, `user`). */
+export interface Settings {
+    theme: ThemeSetting;
+    language: LanguageSetting;
+    /** Read the replies of ta aloud. */
+    speak: boolean;
+    reduceMotion: boolean;
+    /** The names of the built-in web extensions turned off; the others are on. */
+    builtinsOff: string[];
+    /**
+     * Hosts whose pages open outside of Ta without asking, as the trusted domains of VS Code:
+     * `github.com`, `*.github.com`, `localhost:3000`, or `*` for all. This machine always is.
+     */
+    trustedDomains: string[];
+}
+
+export interface SettingsState {
+    settings: Settings;
+    /** What `system` stands for now. */
+    theme: Theme;
+    language: Language;
+    /** Also when the system asks for it. */
+    reduceMotion: boolean;
+}
+
+export const DEFAULT_SETTINGS: Settings = { theme: 'system', language: 'system', speak: false, reduceMotion: false, builtinsOff: [], trustedDomains: [] };
+
+function strings(value: unknown): string[] {
+    return Array.isArray(value) ? value.filter((item: unknown): item is string => typeof item === 'string') : [];
+}
+
+export namespace SettingsUtil {
+    /** What was kept, with the defaults for what is missing; undefined for what is not settings. */
+    export function parse(value: unknown): Settings | undefined {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return undefined;
+        }
+        const kept = value as Record<string, unknown>;
+        return {
+            theme: ['system', 'light', 'dark'].includes(kept.theme as string) ? (kept.theme as ThemeSetting) : DEFAULT_SETTINGS.theme,
+            language: ['system', 'zh-CN', 'en-US'].includes(kept.language as string) ? (kept.language as LanguageSetting) : DEFAULT_SETTINGS.language,
+            speak: kept.speak === true,
+            reduceMotion: kept.reduceMotion === true,
+            builtinsOff: strings(kept.builtinsOff),
+            trustedDomains: strings(kept.trustedDomains),
+        };
+    }
+
+    export const STATE: StateSpec<Settings> = { key: 'settings', tier: 'user', initial: DEFAULT_SETTINGS, parse };
+
+    export function theme(setting: ThemeSetting, prefersDark: boolean): Theme {
+        return setting === 'system' ? (prefersDark ? 'dark' : 'light') : setting;
+    }
+
+    /** Chinese for any Chinese, English for the rest. */
+    export function language(setting: LanguageSetting, browserLanguage: string): Language {
+        return setting === 'system' ? (browserLanguage.toLowerCase().startsWith('zh') ? 'zh-CN' : 'en-US') : setting;
+    }
+}
+
+/** The settings of the web client: theme, language, voice, motion. They apply as soon as they change. */
+export interface TaSettings {
+    readonly state: SettingsState;
+    update(change: Partial<Settings>): void;
+    subscribe(listener: (state: SettingsState) => void): () => void;
+}

package/src/browser/settings/settings.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'bun:test';
+import { DEFAULT_SETTINGS, SettingsUtil } from './settings-protocol';
+
+describe('SettingsUtil', () => {
+    it('reads what was kept, with the defaults for the rest, and nothing from what is not settings', () => {
+        expect(SettingsUtil.parse({})).toEqual(DEFAULT_SETTINGS);
+        expect(SettingsUtil.parse({ theme: 'dark', language: 'fr', speak: true })).toEqual({ ...DEFAULT_SETTINGS, theme: 'dark', speak: true });
+        expect(SettingsUtil.parse(null)).toBeUndefined();
+        expect(SettingsUtil.parse('not json')).toBeUndefined();
+        expect(SettingsUtil.parse([])).toBeUndefined();
+        expect(SettingsUtil.STATE).toMatchObject({ key: 'settings', tier: 'user' });
+    });
+
+    it('keeps the built-ins on unless turned off', () => {
+        expect(DEFAULT_SETTINGS.builtinsOff).toEqual([]);
+        expect(SettingsUtil.parse({ builtinsOff: ['assistant', 1] })?.builtinsOff).toEqual(['assistant']);
+    });
+
+    it('trusts no domain until the user does', () => {
+        expect(DEFAULT_SETTINGS.trustedDomains).toEqual([]);
+        expect(SettingsUtil.parse({ trustedDomains: ['github.com', null] })?.trustedDomains).toEqual(['github.com']);
+    });
+
+    it('follows the system when asked to', () => {
+        expect(SettingsUtil.theme('system', true)).toBe('dark');
+        expect(SettingsUtil.theme('light', true)).toBe('light');
+        expect(SettingsUtil.language('system', 'zh-TW')).toBe('zh-CN');
+        expect(SettingsUtil.language('system', 'de-DE')).toBe('en-US');
+        expect(SettingsUtil.language('en-US', 'zh-CN')).toBe('en-US');
+    });
+});

package/src/browser/settings/settings.ts

@@ -0,0 +1,89 @@
+import { Autowired, Component, PostConstruct } from '@celljs/core';
+import { LocaleManager } from '@celljs/widget';
+import { TaState } from '../state/state-protocol';
+import { type Settings, type SettingsState, SettingsUtil, TaSettings } from './settings-protocol';
+
+/**
+ * The colours of the conversation (--ta-main) and of the side columns (--ta-side), for the bar of the
+ * browser and the title bar of the installed app.
+ */
+export const THEME_COLORS = { dark: { main: '#141416', side: '#1c1c1e' }, light: { main: '#ffffff', side: '#f5f5f7' } };
+
+@Component(TaSettings)
+export class TaSettingsImpl implements TaSettings {
+    @Autowired(LocaleManager)
+    protected readonly localeManager: LocaleManager;
+
+    @Autowired(TaState)
+    protected readonly persisted: TaState;
+
+    protected current: SettingsState;
+    protected readonly listeners = new Set<(state: SettingsState) => void>();
+    protected readonly dark = matchMedia('(prefers-color-scheme: dark)');
+    protected readonly calm = matchMedia('(prefers-reduced-motion: reduce)');
+
+    get state(): SettingsState {
+        return this.current;
+    }
+
+    @PostConstruct()
+    protected init(): void {
+        this.current = this.resolve(this.persisted.get(SettingsUtil.STATE));
+        // Changed in another browser: the server has it once this page is signed in.
+        this.persisted.subscribe(() => {
+            const settings = this.persisted.get(SettingsUtil.STATE);
+            if (settings !== this.current.settings) {
+                this.apply(settings);
+            }
+        });
+        this.dark.addEventListener('change', () => this.apply(this.current.settings));
+        this.calm.addEventListener('change', () => this.apply(this.current.settings));
+        this.apply(this.current.settings);
+    }
+
+    update(change: Partial<Settings>): void {
+        const settings = { ...this.current.settings, ...change };
+        this.apply(settings);
+        this.persisted.set(SettingsUtil.STATE, settings);
+    }
+
+    subscribe(listener: (state: SettingsState) => void): () => void {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    protected resolve(settings: Settings): SettingsState {
+        return {
+            settings,
+            theme: SettingsUtil.theme(settings.theme, this.dark.matches),
+            language: SettingsUtil.language(settings.language, navigator.language),
+            reduceMotion: settings.reduceMotion || this.calm.matches,
+        };
+    }
+
+    protected apply(settings: Settings): void {
+        const state = this.resolve(settings);
+        this.current = state;
+        const root = document.documentElement;
+        root.dataset.theme = state.theme;
+        root.style.colorScheme = state.theme;
+        root.lang = state.language;
+        root.toggleAttribute('data-reduce-motion', state.reduceMotion);
+        let meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
+        if (!meta) {
+            meta = document.createElement('meta');
+            meta.name = 'theme-color';
+            document.head.appendChild(meta);
+        }
+        meta.content = THEME_COLORS[state.theme].main;
+        void this.localeManager.get().then(locales => {
+            const locale = locales.find(candidate => candidate.lang === state.language);
+            if (locale && this.localeManager.current !== locale) {
+                this.localeManager.setCurrent(locale);
+            }
+        });
+        for (const listener of this.listeners) {
+            listener(state);
+        }
+    }
+}

package/src/browser/state/state-protocol.ts

@@ -0,0 +1,71 @@
+export const TaState = Symbol('TaState');
+
+/**
+ * Where a value of the page is kept, by who should find it again:
+ * - `tab`: this tab of the browser (sessionStorage), as the page it shows; two tabs show two things.
+ * - `device`: this browser (localStorage), as the widths of the columns, which follow its screen.
+ * - `user`: the user, on the server (the data of the package @celljs/ta-web), in every browser; this
+ *   browser keeps a copy, for the first frame and when the server cannot be reached.
+ *
+ * What belongs to one directory (the folders open in an explorer) is kept by the web extension that
+ * shows it, with `pi.storage.directory(cwd)`.
+ */
+export type StateTier = 'tab' | 'device' | 'user';
+
+/** One value of the page: where it is kept, and how it is read back. */
+export interface StateSpec<T> {
+    /** `chat.file`: `ta.chat.file` in the browser, the key of the data on the server. */
+    key: string;
+    tier: StateTier;
+    /** Until something is kept. */
+    initial: T;
+    /** The value read, or undefined when it is not one (kept by an older version, or by hand). */
+    parse(value: unknown): T | undefined;
+}
+
+/**
+ * The values of the page that outlive it, each at its tier. Values are JSON and replaced, never changed in
+ * place: the same value is the same object, for React. A value set here wins over one read from the
+ * server meanwhile; the last write wins between browsers.
+ */
+export interface TaState {
+    /** At once, what this browser has; for `user` it also asks the server, and tells the listeners if that differs. */
+    get<T>(spec: StateSpec<T>): T;
+    /** What the server has, when it can be asked; else what this browser has. */
+    load<T>(spec: StateSpec<T>): Promise<T>;
+    /** Kept here at once; on the server a moment later, or when it can be reached again. */
+    set<T>(spec: StateSpec<T>, value: T): void;
+    /** A value changed, here or from the server. */
+    subscribe(listener: () => void): () => void;
+    /** Writes to the server what waits, now: the page is going away. */
+    flush(): void;
+}
+
+export namespace StateUtil {
+    /** The name of ta's own data on the server (TaPackageServer.getExtensionData). */
+    export const DATA_NAME = '@celljs/ta-web';
+
+    export function string(value: unknown): string | undefined {
+        return typeof value === 'string' ? value : undefined;
+    }
+
+    export function boolean(value: unknown): boolean | undefined {
+        return typeof value === 'boolean' ? value : undefined;
+    }
+
+    /** What the browser has under the key: JSON, or the bare text older versions kept. */
+    export function decode(text: string | null): unknown {
+        if (text === null) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(text);
+        } catch {
+            return text;
+        }
+    }
+
+    export function same(a: unknown, b: unknown): boolean {
+        return a === b || JSON.stringify(a) === JSON.stringify(b);
+    }
+}