cortico 0.1.0

package/src/web/client/theme/palette.ts

@@ -0,0 +1,109 @@
+/** 将主题 token 写为 documentElement 的 CSS 变量，并更新明暗标记与 theme-color。 */
+
+import {
+  THEME_TOKENS,
+  type ThemeAppearance,
+  type ThemePalette,
+} from './registry.ts';
+
+export interface ApplyPaletteOptions {
+  /** 解析之后的明暗，落到 `data-color-mode` 与 `color-scheme`（表单控件、滚动条随之变）。 */
+  appearance: ThemeAppearance;
+  /** 当前方案 id，落到 `data-theme-scheme`；给 CSS 留一个"某方案单独微调"的口子。 */
+  schemeId?: string;
+}
+
+/** 按 token 词表顺序映射 CSS 变量，仅包含词表中的键。 */
+export function paletteVars(palette: ThemePalette): Array<[string, string]> {
+  const out: Array<[string, string]> = [];
+  for (const token of THEME_TOKENS) {
+    const value = palette[token.key];
+    if (typeof value === 'string' && value !== '') out.push(['--' + token.key, value]);
+  }
+  return out;
+}
+
+/**
+ * `<meta name="theme-color">` —— 移动端浏览器的地址栏底色。
+ * 没有就建一个；页面里已有（`index.html` 静态写的那一个）就改它的 `content`。
+ */
+function applyThemeColorMeta(doc: Document, color: string | undefined): void {
+  const head = doc.head;
+  if (!head || !color) return;
+  let meta = doc.querySelector('meta[name="theme-color"]') as HTMLMetaElement | null;
+  if (!meta) {
+    meta = doc.createElement('meta');
+    meta.name = 'theme-color';
+    head.appendChild(meta);
+  }
+  meta.content = color;
+}
+
+/** 把一份调色板刷到文档根上。**同步、幂等**，重复调用只是把同样的值再写一遍。 */
+export function applyPalette(
+  doc: Document,
+  palette: ThemePalette,
+  opts: ApplyPaletteOptions,
+): void {
+  const root = doc.documentElement;
+  if (!root) return;
+  for (const [name, value] of paletteVars(palette)) root.style.setProperty(name, value);
+  root.dataset.colorMode = opts.appearance;
+  if (opts.schemeId) root.dataset.themeScheme = opts.schemeId;
+  root.style.colorScheme = opts.appearance;
+  applyThemeColorMeta(doc, palette.paper);
+}
+
+/** 读取语义色的计算值；缺少合法颜色时回退到 --ink-dim。 */
+export function readThemeColor(doc: Document, key: string): string {
+  const root = doc.documentElement;
+  const view = doc.defaultView;
+  if (!root || !view) return '';
+  const read = (k: string): string => view.getComputedStyle(root).getPropertyValue('--' + k).trim();
+  const value = read(key);
+  return /^#[0-9a-f]{6}$/i.test(value) ? value : read('ink-dim');
+}
+
+// ---------------------------------------------------------------------------
+// 颜色换算
+// ---------------------------------------------------------------------------
+
+export interface Hsl {
+  /** 0–360 */
+  h: number;
+  /** 0–100 */
+  s: number;
+  /** 0–100 */
+  l: number;
+}
+
+/** 将 #rrggbb 或 #rgb 转为 HSL。 */
+export function hexToHsl(hex: string): Hsl {
+  let x = String(hex).replace('#', '');
+  if (x.length === 3) x = x.split('').map((c) => c + c).join('');
+  const r = parseInt(x.slice(0, 2), 16) / 255;
+  const g = parseInt(x.slice(2, 4), 16) / 255;
+  const b = parseInt(x.slice(4, 6), 16) / 255;
+  const mx = Math.max(r, g, b);
+  const mn = Math.min(r, g, b);
+  let h = 0;
+  let s = 0;
+  const l = (mx + mn) / 2;
+  if (mx !== mn) {
+    const d = mx - mn;
+    s = l > 0.5 ? d / (2 - mx - mn) : d / (mx + mn);
+    h = mx === r ? (g - b) / d + (g < b ? 6 : 0) : mx === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    h *= 60;
+  }
+  return { h, s: s * 100, l: l * 100 };
+}
+
+/** HSL → `hsl(210,12%,40%)`。三个分量都取整——CSS 不需要那么多小数。 */
+export function hslCss(hsl: Hsl): string {
+  return `hsl(${Math.round(hsl.h)},${Math.round(hsl.s)}%,${Math.round(hsl.l)}%)`;
+}
+
+/** 夹到区间。深浅派生时防止某一族滑到纯黑或纯白（那时候颜色就没有区分度了）。 */
+export function clampNumber(value: number, lo: number, hi: number): number {
+  return value < lo ? lo : value > hi ? hi : value;
+}

package/src/web/client/theme/registry.ts

@@ -0,0 +1,130 @@
+/** 主题的界面文案：方案名、token 标签与分组。数据与纯函数在 web/shared/theme.ts。 */
+
+import {
+  BUILTIN_PALETTES,
+  BUILTIN_SCHEME_IDS,
+  THEME_TOKEN_GROUPS,
+  cloneScheme,
+  type ThemeAppearance,
+  type ThemeMode,
+  type ThemeScheme,
+} from '../../shared/theme.ts';
+import { S } from './strings.ts';
+
+export {
+  BUILTIN_PALETTES,
+  BUILTIN_SCHEME_IDS,
+  DEFAULT_SCHEME_ID,
+  THEME_MODES,
+  THEME_TOKEN_KEYS,
+  clonePalette,
+  cloneScheme,
+  defaultStoredTheme,
+  fallbackPalette,
+  isHexColor,
+  normalizeHex,
+  normalizePalette,
+  normalizeStoredTheme,
+  parseStoredTheme,
+  resolvePalette,
+  schemeSwatches,
+} from '../../shared/theme.ts';
+export type {
+  InjectedTheme,
+  StoredTheme,
+  ThemeAppearance,
+  ThemeMode,
+  ThemePalette,
+  ThemeScheme,
+} from '../../shared/theme.ts';
+
+export interface ThemeToken {
+  /** 编辑器里的分组标题 */
+  readonly group: string;
+  /** CSS 变量名去掉 `--` 前缀，如 `paper` → `--paper` */
+  readonly key: string;
+  /** 编辑器里的中文标签 */
+  readonly label: string;
+}
+
+/** 明暗模式的中文挡位名。分段选择器与提示语共用一套措辞。 */
+export const THEME_MODE_LABELS: Readonly<Record<ThemeMode, string>> = {
+  light: S.modeLight,
+  dark: S.modeDark,
+  system: S.modeSystem,
+};
+
+/** 提示语里的"当前变体"。`light`/`dark` 两个词全站只在这儿定义一次。 */
+export const THEME_APPEARANCE_LABELS: Readonly<Record<ThemeAppearance, string>> = {
+  light: S.appearanceLight,
+  dark: S.appearanceDark,
+};
+
+const GROUP_TITLES: Readonly<Record<string, string>> = {
+  paper: S.groupPaper,
+  ink: S.groupInk,
+  state: S.groupState,
+  timeline: S.groupTimeline,
+  chart: S.groupChart,
+};
+
+const SCHEME_TEXT: Readonly<Record<string, { name: string; note: string }>> = {
+  mint: { name: S.schemeMint, note: S.schemeMintNote },
+  navigator: { name: S.schemeNavigator, note: S.schemeNavigatorNote },
+  'crab-daisy': { name: S.schemeCrabDaisy, note: S.schemeCrabDaisyNote },
+};
+
+export const THEME_TOKENS: readonly ThemeToken[] = THEME_TOKEN_GROUPS.flatMap((group) =>
+  group.keys.map((key): ThemeToken => ({ group: GROUP_TITLES[group.id], key, label: S.token[key] })),
+);
+
+/** 内置方案，贴上界面语言的名称与说明。 */
+export const BUILTIN_SCHEMES: readonly ThemeScheme[] = BUILTIN_SCHEME_IDS.map((id) => ({
+  id,
+  name: SCHEME_TEXT[id].name,
+  note: SCHEME_TEXT[id].note,
+  palettes: BUILTIN_PALETTES[id],
+  builtin: true,
+}));
+
+/** 方案名与说明：自定义方案没填名字时用通用称呼。 */
+export function schemeText(scheme: ThemeScheme): { name: string; note: string } {
+  return {
+    name: scheme.name || SCHEME_TEXT[scheme.id]?.name || S.customScheme,
+    note: scheme.note || SCHEME_TEXT[scheme.id]?.note || S.customNote,
+  };
+}
+
+/** 全部内置方案的副本。主题记录里没有它们，每次现取。 */
+export function builtinSchemes(): ThemeScheme[] {
+  return BUILTIN_SCHEMES.map((scheme) => ({ ...cloneScheme(scheme), builtin: true }));
+}
+
+/** 部署记录给的方案 id；不是内置方案就落到框架默认方案。 */
+export function resolveDefaultSchemeId(value: unknown): string {
+  const id = String(value ?? '');
+  return BUILTIN_SCHEME_IDS.includes(id) ? id : BUILTIN_SCHEME_IDS[0];
+}
+
+/**
+ * 词表按 `group` 归并，**保持 `THEME_TOKENS` 里的出现顺序**。
+ *
+ * 编辑器要的就是这个形状；单独拿出来是因为"分组"是这一页唯一有分量的纯逻辑，
+ * 而它写在渲染函数里就只能靠看 DOM 来验。
+ */
+export function groupedThemeTokens(
+  tokens: readonly ThemeToken[] = THEME_TOKENS,
+): Array<{ group: string; tokens: ThemeToken[] }> {
+  const out: Array<{ group: string; tokens: ThemeToken[] }> = [];
+  const index = new Map<string, { group: string; tokens: ThemeToken[] }>();
+  for (const token of tokens) {
+    let bucket = index.get(token.group);
+    if (!bucket) {
+      bucket = { group: token.group, tokens: [] };
+      index.set(token.group, bucket);
+      out.push(bucket);
+    }
+    bucket.tokens.push(token);
+  }
+  return out;
+}

package/src/web/client/theme/storage.ts

@@ -0,0 +1,72 @@
+/**
+ * 主题记录归部署所有：首屏从服务端注入的 JSON 读，改动回写 `/api/theme`。
+ * 这台机器的 localStorage 只在部署还没有记录时读一次，把旧记录交上去。
+ */
+
+import { post } from '../core/api.ts';
+import {
+  DEFAULT_SCHEME_ID,
+  THEME_SCRIPT_ID,
+  normalizeStoredTheme,
+  type InjectedTheme,
+  type StoredTheme,
+} from '../../shared/theme.ts';
+
+export { THEME_SCRIPT_ID };
+
+/** 搬进部署目录之前，主题记录存在这台机器上的两个键；新的在前。 */
+export const LEGACY_THEME_STORAGE_KEYS: readonly string[] = [
+  'cortico.theme.v1',
+  'xuewu.theme-studio.v1',
+];
+
+/** 首页里那段 JSON。`theme` 为 null = 这份部署还没保存过，此时才谈得上迁移本机旧记录。 */
+export function readInjectedTheme(doc: Document): InjectedTheme {
+  const fallback: InjectedTheme = { defaultScheme: DEFAULT_SCHEME_ID, theme: null };
+  const raw = doc.getElementById(THEME_SCRIPT_ID)?.textContent;
+  if (raw == null || raw.trim() === '') return fallback;
+  try {
+    const value = JSON.parse(raw) as Partial<InjectedTheme> | null;
+    if (!value || typeof value !== 'object') return fallback;
+    return {
+      defaultScheme: typeof value.defaultScheme === 'string' && value.defaultScheme !== ''
+        ? value.defaultScheme
+        : DEFAULT_SCHEME_ID,
+      theme: value.theme == null ? null : normalizeStoredTheme(value.theme),
+    };
+  } catch {
+    return fallback;
+  }
+}
+
+/** 这台机器上的旧记录。两个键都没有内容时给 `null`；旧记录读完不删。 */
+export function readLegacyLocalTheme(doc: Document): StoredTheme | null {
+  let storage: Pick<Storage, 'getItem'> | null = null;
+  try {
+    storage = doc.defaultView?.localStorage ?? null;
+  } catch {
+    // 沙箱 iframe 与无痕模式下访问会被拒。
+    return null;
+  }
+  if (!storage) return null;
+  for (const key of LEGACY_THEME_STORAGE_KEYS) {
+    let raw: string | null = null;
+    try {
+      raw = storage.getItem(key);
+    } catch {
+      return null;
+    }
+    if (raw == null || raw === '') continue;
+    try {
+      return normalizeStoredTheme(JSON.parse(raw) as unknown);
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/** 回写部署的主题记录。失败由调用方呈现，不吞。 */
+export async function saveDeploymentTheme(state: StoredTheme): Promise<void> {
+  await post('/api/theme', state);
+}

package/src/web/client/theme/strings.ts

@@ -0,0 +1,123 @@
+import { pick } from '../core/language.ts';
+
+const zh = {
+  modeLight: '☀ 浅色',
+  modeDark: '◐ 黑夜',
+  modeSystem: '◒ 跟随系统',
+  appearanceLight: '浅色',
+  appearanceDark: '黑夜',
+  groupPaper: "背景层级",
+  groupInk: '文字与边界',
+  groupState: '交互与状态',
+  groupTimeline: '终端时间线',
+  groupChart: '图表系列',
+  token: {
+    paper: '页面背景',
+    'paper-2': '侧栏背景',
+    sheet: '主卡片背景',
+    'sheet-2': '次级卡片背景',
+    'sheet-3': '压低底色',
+    ink: '主要文字',
+    'ink-soft': '次级文字',
+    'ink-dim': '弱化文字',
+    line: '细边界',
+    'line-2': '常规边界',
+    'line-strong': '强调边界',
+    accent: '主强调',
+    'accent-2': '次强调',
+    'on-accent': '强调色上文字',
+    ok: '成功 / 在线',
+    warn: '提醒 / 系统',
+    danger: '危险 / 失败',
+    'ink-blue': 'Agent 标记',
+    violet: '思考标记',
+    'agent-surface': 'Agent 卡片底色',
+    'world-bg': '世界事件底色',
+    'world-ink': '世界事件文字',
+    'bubble-bg': '发送气泡底色',
+    'bubble-ink': '发送气泡文字',
+    'tool-result': '工具结果文字',
+    'chart-hit': '缓存命中',
+    'chart-miss': '未命中输入',
+    'chart-output': '模型输出',
+    'chart-1': '系列 1',
+    'chart-2': '系列 2',
+    'chart-3': '系列 3',
+    'chart-4': '系列 4',
+    'chart-5': '系列 5',
+    'chart-6': '系列 6',
+    'chart-7': '系列 7',
+    'chart-8': '系列 8',
+  },
+  schemeMint: '脑皮质薄荷',
+  schemeMintNote: 'Logo 的薄荷绿、同色系层次与中性灰背景',
+  schemeNavigator: '未来领航员',
+  schemeNavigatorNote: '可缇 Corti 人设图的海军蓝、天蓝、白与淡粉',
+  schemeCrabDaisy: '螃蟹和雏菊',
+  schemeCrabDaisyNote: '赤陶、灰玫瑰与 Claude 网页灰阶',
+  customScheme: '自定义方案',
+  customNote: '自定义配色',
+  copyOf: (name: string) => `${name} 副本`,
+};
+
+const en: typeof zh = {
+  modeLight: '☀ Light',
+  modeDark: '◐ Dark',
+  modeSystem: '◒ System',
+  appearanceLight: 'Light',
+  appearanceDark: 'Dark',
+  groupPaper: "Background layers",
+  groupInk: 'Text & borders',
+  groupState: 'Interaction & state',
+  groupTimeline: 'Terminal timeline',
+  groupChart: 'Chart series',
+  token: {
+    paper: 'Page background',
+    'paper-2': 'Sidebar background',
+    sheet: 'Main card',
+    'sheet-2': 'Secondary card',
+    'sheet-3': 'Recessed ground',
+    ink: 'Primary text',
+    'ink-soft': 'Secondary text',
+    'ink-dim': 'Muted text',
+    line: 'Hairline border',
+    'line-2': 'Regular border',
+    'line-strong': 'Strong border',
+    accent: 'Primary accent',
+    'accent-2': 'Secondary accent',
+    'on-accent': 'Text on accent',
+    ok: 'Success / online',
+    warn: 'Notice / system',
+    danger: 'Danger / failure',
+    'ink-blue': 'Agent marker',
+    violet: 'Reasoning marker',
+    'agent-surface': 'Agent card ground',
+    'world-bg': 'World event ground',
+    'world-ink': 'World event text',
+    'bubble-bg': 'Sent bubble ground',
+    'bubble-ink': 'Sent bubble text',
+    'tool-result': 'Tool result text',
+    'chart-hit': 'Cache hit',
+    'chart-miss': 'Uncached input',
+    'chart-output': 'Model output',
+    'chart-1': 'Series 1',
+    'chart-2': 'Series 2',
+    'chart-3': 'Series 3',
+    'chart-4': 'Series 4',
+    'chart-5': 'Series 5',
+    'chart-6': 'Series 6',
+    'chart-7': 'Series 7',
+    'chart-8': 'Series 8',
+  },
+  schemeMint: 'Cortex Mint',
+  schemeMintNote: 'Logo mint and tonal greens over neutral grey',
+  schemeNavigator: 'Future Navigator',
+  schemeNavigatorNote: 'Navy, sky blue, white and blush from Corti\'s character sheet',
+  schemeCrabDaisy: 'Crab & Daisy',
+  schemeCrabDaisyNote: 'Terracotta and dusty rose over Claude web greys',
+  customScheme: 'Custom scheme',
+  customNote: 'Custom palette',
+  copyOf: (name: string) => `${name} copy`,
+};
+
+export const S = pick({ zh, en });