@yannelli/paseo-linear-plugin 1.1.0-beta.1 → 1.1.0-beta.2

package/OVERVIEW.md

@@ -31,6 +31,10 @@ Open **Linear Live** from the Linear pill in an agent's composer. It shows the i
 
 On agents not started from an issue, the Linear pill searches Linear and sends an issue to the agent.
 
+## Plugin icon
+
+In **Settings → Plugins → Linear → Icon**, choose an SVG file or paste SVG markup. Composer pills, the Linear sidebar row, the timeline card, and the Linear screens use it. Paseo menus and panel tabs keep the built-in icon. Keep the original colors, or paint the icon with the theme color, the theme accent, Linear indigo, or a custom color. **Solid** fills outline shapes. The plugin refuses SVGs with scripts, event handlers, or links to other files. The iOS and Android apps show the built-in icon in the chosen color.
+
 ## Update Linear from todos
 
 Turn on **Update Linear from agent todos** in the Live settings. After each turn, a todo that starts with a sub-issue key, such as `ENG-124: add the queue`, moves that sub-issue to In Progress, and then to Done when all its todos are done. The parent moves to In Review when every sub-issue is done, never to Done. Statuses only move forward.

package/README.md

@@ -179,6 +179,15 @@ For implement agents on an issue with sub-issues, the prompt asks the agent to s
 
 Each agent's composer has a **Linear** pill. On an agent started from an issue, the pill shows the issue key. It opens the issue status, each sub-issue with its todo progress, and buttons for Linear Live, the issue, and **Sync now**. On other agents, the pill searches Linear and sends the issue text to the agent as a message.
 
+### Plugin icon
+
+In **Settings → Plugins → Linear → Icon**, choose an SVG file or paste SVG markup. Composer pills, the Linear sidebar row on Paseo 0.11 and newer, the issue card in the timeline, and the Linear screens then use it. Paseo menus, panel tabs, and settings take only built-in icon names, so they keep the Linear board icon. The plugin accepts SVG only. It refuses scripts, event handlers, HTML content, entities, and links to other files or bitmap images. The SVG needs a viewBox, or a width and height in pixels.
+
+- **Color:** **Original colors** keeps the SVG as drawn, and `currentColor` takes the color Paseo gives the icon. **Theme color**, **Theme accent**, **Linear indigo**, and **Custom color** paint the whole icon one color and keep its transparency. These choices also apply to the built-in icon.
+- **Solid:** fills shapes that only have an outline, with their stroke color, so a line icon shows as a solid shape.
+
+The preview shows each change before you save. The iOS and Android apps cannot draw SVG images from plugins, so they show the built-in icon in the chosen color.
+
 ### Update Linear from agent todos
 
 Turn on **Update Linear from agent todos** in the Live settings. After each turn of an implement agent, the daemon reads the agent's todos:
@@ -203,6 +212,7 @@ In **Settings → Plugins → Linear → Projects**, select **Start** under **Se
 - **Linear tools for agents:** the daemon runs the `linear` MCP server on `127.0.0.1` only, and only after an agent gets it. Each agent gets its own random token, and its tools reach only its issue and that issue's sub-issues. Edits use the Linear key of the project that loaded the issue. Requests from a web page are refused. `agent-tools.json` beside the key file keeps the port and a hash of each token, so agents keep their tools after a restart. The token itself is in the agent's Paseo config.
 - **Claude hooks:** when an **Agent guidance** switch is on for a Claude agent, the daemon writes a Claude Code plugin to `claude-hooks/` beside the key file, one folder for each issue and set of hooks. It holds the issue key and title and the sub-issue keys and titles. The agent starts with `--plugin-dir` set to that folder. The hooks print that text and run no other command. The daemon does not write hooks on Windows hosts.
 - **Todo sync:** when it is on, the daemon changes issue statuses in Linear with the key of the project that loaded the issue.
+- **Plugin icon:** the SVG is saved in the plugin settings on the daemon host. The app draws it as an image, which does not run scripts or load other files.
 - **Cached results:** the daemon keeps up to 300 recent Linear responses in memory for up to 24 hours. It groups them by a hash of the key, so two keys never share results. The app shows saved results at once with **Showing saved results. Updating…** while it gets new data. An edit clears the cached lists and issues for that key. Saving or removing a key clears the whole cache. The cache is not written to disk, and a daemon restart clears it.
 
 Linear errors, such as a rejected key or a rate limit, show in the panel or as a message.
@@ -211,7 +221,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 
 | File | Runtime | Role |
 | --- | --- | --- |
-| `index.client.tsx` | App | Registers the Linear screen, the workspace panel, the Linear Live panel, the Account, Prompts, Live, and Projects settings, the command center items, the `/linear` command, the timeline card, the composer attachment, and the Linear pill |
+| `index.client.tsx` | App | Registers the Linear screen, the workspace panel, the Linear Live panel, the Account, Prompts, Live, Icon, and Projects settings, the command center items, the `/linear` command, the timeline card, the composer attachment, and the Linear pill |
 | `index.server.ts` | Daemon | Registers the settings, the RPC handlers, and the todo sync hook |
 | `client/browser.tsx` | App | Screen and panel: picks the key, then shows the list, the issue, or the agent setup page |
 | `client/issue-list.tsx`, `client/issue-row.tsx`, `client/issue-tree.ts` | App | Search, filters, sort, rows, status groups, and sub-issue nesting |
@@ -220,6 +230,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `client/markdown.tsx` | App | Renders Markdown |
 | `client/launch.tsx`, `client/launch-fields.tsx`, `client/launch-guidance.tsx`, `client/launch-choices.ts`, `client/launch-plan.ts`, `client/agent-options.ts` | App | Agent setup page, Run in options, agent guidance, and agent start |
 | `client/model-browser.tsx`, `client/provider-icon.tsx` | App | Model picker and provider icons |
+| `client/plugin-icon.tsx`, `client/settings-icon.tsx`, `shared/custom-icon.ts` | App, Both | The plugin icon, its settings screen, and the SVG checks, colors, and fill |
 | `client/create-issue.tsx`, `client/pickers.tsx` | App | New issue form and option pickers |
 | `client/connect.tsx`, `client/settings-*.tsx` | App | Key form and settings screens |
 | `client/queries.ts`, `client/store.ts`, `client/key-scope.tsx` | App | Data hooks with saved results, browser state, and the key in use |
@@ -227,7 +238,7 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `client/timeline-card.tsx`, `client/ui.tsx`, `client/glyphs.tsx` | App | Timeline card, shared controls, and icons |
 | `client/live-panel.tsx`, `client/live-header.tsx`, `client/live-issues.tsx`, `client/live-feed.tsx`, `client/live-timeline.ts` | App | Linear Live panel, header, sub-issues, activity, and the agent timeline feed |
 | `client/live-map.tsx`, `client/live-graph.tsx`, `client/graph-labels.ts`, `client/graph-camera.tsx`, `client/live-cursor.tsx`, `client/live-agents.tsx` | App | File map, file graph with its labels and camera, agent cursors, and the agents list |
-| `client/tool-buttons.tsx`, `client/web.ts` | App | Icon buttons for the map and graph, and the wheel listener on the web |
+| `client/tool-buttons.tsx`, `client/web.ts` | App | Icon buttons for the map and graph, and the wheel listener and file picker on the web |
 | `client/pill.tsx` | App | Linear pill in each agent's composer |
 | `client/project-init.tsx` | App | Project setup proposal in the Projects settings |
 | `shared/linear.ts` | Both | RPC contracts and issue schemas |
@@ -263,7 +274,7 @@ npm run check
 paseo plugin add "$PWD"
 ```
 
-After you edit the source, run `paseo plugin reload paseo-linear-plugin`. `npm run check` runs the typecheck and the tests. The tests cover the Linear client, the key file, the cache, the handlers, sub-issue nesting, the Markdown parser and task list toggle, the description autosave, the agent options, the prompt guidance and its hooks, the MCP server and its tools, the links between files in many languages, the graph layout and camera, and the release scripts. They use a local GraphQL server and do not call Linear.
+After you edit the source, run `paseo plugin reload paseo-linear-plugin`. `npm run check` runs the typecheck and the tests. The tests cover the Linear client, the key file, the cache, the handlers, sub-issue nesting, the Markdown parser and task list toggle, the description autosave, the agent options, the prompt guidance and its hooks, the MCP server and its tools, the links between files in many languages, the graph layout and camera, the SVG icon checks and colors, and the release scripts. They use a local GraphQL server and do not call Linear.
 
 ## Graphics
 

package/client/access.tsx

@@ -1,6 +1,7 @@
 import { type PluginAgentPanelProps, useSettings, useWorkspace } from "@getpaseo/plugin/client";
 import { type ComponentType, type ReactNode, useEffect } from "react";
 import { linearSettings, type ProjectAccess, projectEnabled } from "../shared/settings";
+import { PluginIcon } from "./plugin-icon";
 import { EmptyState, type Theme } from "./ui";
 
 // Composer pills live outside React, so components that read settings share the project
@@ -44,7 +45,7 @@ export function ProjectGate(props: {
   return (
     <EmptyState
       theme={props.theme}
-      icon="SquareKanban"
+      icon={PluginIcon}
       title="Linear is off for this project"
       detail="Turn it on in Linear settings, under Projects."
     />

package/client/compat.ts

@@ -1,6 +1,6 @@
 import type { PluginClientContext, PluginSurfaceProps } from "@getpaseo/plugin/client";
 import * as hostUi from "@getpaseo/plugin/client/ui";
-import { type ComponentType, createElement } from "react";
+import { type ComponentType, createContext, createElement, useContext } from "react";
 
 // Paseo 0.11 replaced surfaces with screens and sidebar header items. 0.10 only has
 // addSurface/addSidebarItem; later releases drop those aliases. Detect once, register once.
@@ -13,6 +13,7 @@ interface ScreenRef {
 interface SidebarItemProps {
   currentScreen: ScreenRef | null;
   openScreen(input: ScreenRef): void;
+  theme?: PluginSurfaceProps["theme"];
 }
 
 interface ScreenClient {
@@ -33,8 +34,13 @@ interface SurfaceClient {
   addSidebarItem(input: { id: string; title: string; icon: string; surface: string }): Cleanup;
 }
 
+interface RowIconProps {
+  size: number;
+  color: string;
+}
+
 type SidebarRowComponent = ComponentType<{
-  icon?: string;
+  icon?: string | ComponentType<RowIconProps>;
   label?: string;
   active?: boolean;
   onPress(): void;
@@ -48,9 +54,14 @@ export interface ScreenRegistration {
   id: string;
   title: string;
   icon: string;
+  /** Drawn in the sidebar row where the host accepts icon components; else `icon`. */
+  RowIcon?: ComponentType<RowIconProps & { theme: PluginSurfaceProps["theme"] | null }>;
   Component: ComponentType<PluginSurfaceProps>;
 }
 
+// The row draws its icon with a size and a color only, so the item passes its theme down.
+const RowTheme = createContext<PluginSurfaceProps["theme"] | null>(null);
+
 export function registerScreen(client: PluginClientContext, screen: ScreenRegistration): Cleanup {
   const SidebarRow = (hostUi as Record<string, unknown>).SidebarRow as
     | SidebarRowComponent
@@ -61,12 +72,19 @@ export function registerScreen(client: PluginClientContext, screen: ScreenRegist
       title: screen.title,
       Component: screen.Component,
     });
-    function SidebarItem({ currentScreen, openScreen }: SidebarItemProps) {
-      return createElement(SidebarRow as SidebarRowComponent, {
-        icon: screen.icon,
+    const { RowIcon } = screen;
+    const ThemedIcon = RowIcon
+      ? function ThemedIcon(props: RowIconProps) {
+          return createElement(RowIcon, { ...props, theme: useContext(RowTheme) });
+        }
+      : null;
+    function SidebarItem({ currentScreen, openScreen, theme }: SidebarItemProps) {
+      const row = createElement(SidebarRow as SidebarRowComponent, {
+        icon: ThemedIcon ?? screen.icon,
         active: currentScreen?.screenId === screen.id,
         onPress: () => openScreen({ screenId: screen.id }),
       });
+      return createElement(RowTheme.Provider, { value: theme ?? null }, row);
     }
     const removeItem = client.addSidebarHeaderItem({
       id: screen.id,

package/client/connect.tsx

@@ -1,10 +1,11 @@
 import { useRpc } from "@getpaseo/plugin/client";
-import { Icon, TextInput, useToast } from "@getpaseo/plugin/client/react-native";
+import { TextInput, useToast } from "@getpaseo/plugin/client/react-native";
 import { ExternalLink } from "@getpaseo/plugin/client/ui";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useMemo, useState } from "react";
 import { Text, View } from "react-native";
 import { authSaveRpc } from "../shared/linear";
+import { PluginIcon } from "./plugin-icon";
 import { Button, errorMessage, type Theme } from "./ui";
 
 export const LINEAR_KEY_SETTINGS_URL = "https://linear.app/settings/account/security";
@@ -121,7 +122,7 @@ export function ConnectCard({ theme, compact }: { theme: Theme; compact: boolean
     <View style={styles.root}>
       <View style={styles.card}>
         <View style={styles.header}>
-          <Icon name="SquareKanban" size={22} color={colors.foreground} />
+          <PluginIcon size={22} color={colors.foreground} theme={theme} />
           <Text style={styles.title}>Connect Linear</Text>
         </View>
         <Text style={styles.body}>

package/client/pill.tsx

@@ -17,6 +17,7 @@ import { progressByKey } from "../shared/todo-sync";
 import { currentAccess, onAccessChange, publishAccess } from "./access";
 import { KeyScopeProvider } from "./key-scope";
 import { MONO } from "./live-issues";
+import { PluginIcon } from "./plugin-icon";
 import { useIssue } from "./queries";
 import { focusIssue, panelScope } from "./store";
 import { Button, errorMessage, StateIcon, type Theme } from "./ui";
@@ -144,7 +145,7 @@ function LinkedIssue(props: ContentProps & { open: Open }) {
         <Button
           theme={theme}
           size="xs"
-          icon="SquareKanban"
+          icon={PluginIcon}
           label="Open issue"
           onPress={() => {
             focusIssue(panelScope(workspaceId), identifier);
@@ -337,13 +338,13 @@ export function contributeComposerPills(client: PluginClientContext) {
       button: identifier
         ? {
             title: `Linear issue ${identifier}`,
-            icon: "SquareKanban",
+            icon: PluginIcon,
             label: identifier,
             behavior: { kind: "popover", Content: Linked },
           }
         : {
             title: "Send a Linear issue to this agent",
-            icon: "SquareKanban",
+            icon: PluginIcon,
             label: "Linear",
             behavior: { kind: "popover", Content: Search },
           },

package/client/plugin-icon.tsx

@@ -0,0 +1,43 @@
+import { useSettings } from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useMemo } from "react";
+import { Image, Platform } from "react-native";
+import { type IconSettings, iconMarkup, paintColor } from "../shared/custom-icon";
+import { linearSettings } from "../shared/settings";
+import { svgDataUri } from "./provider-icon";
+import type { Theme } from "./ui";
+
+// The plugin's icon in pills, the sidebar, and plugin screens. Native apps cannot draw SVG
+// images from plugins, so they show the built-in icon in the chosen color.
+
+export const BUILT_IN_ICON = "SquareKanban";
+
+export interface PluginIconProps {
+  size: number;
+  /** The color Paseo gives the icon in this place. */
+  color: string;
+  theme?: Theme | null;
+}
+
+/** Draws icon settings, saved or not yet saved. */
+export function IconGlyph(props: PluginIconProps & { icon: IconSettings | null }) {
+  const { icon, size, color } = props;
+  const accent = props.theme?.colors.accent ?? color;
+  const paint = icon ? paintColor(icon, { ink: color, accent }) : null;
+  const svg = Platform.OS === "web" ? (icon?.svg ?? "") : "";
+  const solid = icon?.solid === true;
+  const source = useMemo(() => {
+    const markup = svg ? iconMarkup(svg, { ink: color, paint, solid }) : null;
+    return markup ? { uri: svgDataUri(markup, color) } : null;
+  }, [svg, color, paint, solid]);
+  const style = useMemo(() => ({ width: size, height: size }), [size]);
+  if (!source) return <Icon name={BUILT_IN_ICON} size={size} color={paint ?? color} />;
+  return <Image source={source} style={style} resizeMode="contain" accessibilityIgnoresInvertColors />;
+}
+
+/** The plugin icon from the saved settings. The built-in icon shows while they load. */
+export function PluginIcon(props: PluginIconProps) {
+  const settings = useSettings(linearSettings);
+  const icon = settings.status === "ready" ? settings.values.icon : null;
+  return <IconGlyph {...props} icon={icon} />;
+}

package/client/settings-fields.tsx

@@ -5,6 +5,7 @@ import { type ReactNode, useCallback, useMemo, useState } from "react";
 import { Text, View } from "react-native";
 import { TEMPLATE_VARIABLES } from "../shared/prompts";
 import type { LinearSettings, linearSettings } from "../shared/settings";
+import { MONO } from "./live-issues";
 import type { Theme } from "./ui";
 
 export type ReadySettings = Extract<
@@ -19,10 +20,14 @@ export function MultilineField(props: {
   value: string;
   placeholder?: string;
   minHeight?: number;
+  error?: string | null;
+  /** Markup, not prose: a monospace font and no autocorrect. */
+  code?: boolean;
   onChange(value: string): void;
 }) {
   const { colors } = props.theme;
   const minHeight = props.minHeight ?? 96;
+  const { code } = props;
   const style = useMemo(
     () => ({
       marginTop: 8,
@@ -36,11 +41,12 @@ export function MultilineField(props: {
       fontSize: 13,
       lineHeight: 19,
       textAlignVertical: "top" as const,
+      ...(code ? { fontFamily: MONO, fontSize: 12 } : {}),
     }),
-    [colors, minHeight],
+    [colors, minHeight, code],
   );
   return (
-    <SettingsRow label={props.label} hint={props.hint}>
+    <SettingsRow label={props.label} hint={props.hint} error={props.error}>
       <TextInput
         value={props.value}
         onChangeText={props.onChange}
@@ -48,7 +54,9 @@ export function MultilineField(props: {
         placeholder={props.placeholder}
         placeholderTextColor={colors.foregroundMuted}
         accessibilityLabel={props.label}
-        autoCapitalize="sentences"
+        autoCapitalize={code ? "none" : "sentences"}
+        autoCorrect={!code}
+        spellCheck={!code}
         style={style}
       />
     </SettingsRow>

package/client/settings-icon.tsx

@@ -0,0 +1,228 @@
+import { type PluginSurfaceProps, useSettings } from "@getpaseo/plugin/client";
+import {
+  SettingsAction,
+  SettingsCard,
+  SettingsInput,
+  SettingsRow,
+  SettingsSection,
+  SettingsSelect,
+  SettingsSwitch,
+} from "@getpaseo/plugin/client/ui";
+import { useCallback, useMemo, useState } from "react";
+import { Platform, Text, View } from "react-native";
+import {
+  HEX_COLOR,
+  type IconPaint,
+  type IconSettings,
+  MAX_SVG_LENGTH,
+  parseIconSvg,
+} from "../shared/custom-icon";
+import { linearSettings } from "../shared/settings";
+import { IconGlyph } from "./plugin-icon";
+import { MultilineField, type ReadySettings, SaveBar, SettingsGate, useSettingsDraft } from "./settings-fields";
+import type { Theme } from "./ui";
+import { canPickFiles, pickTextFile } from "./web";
+
+const PAINT_OPTIONS: readonly { label: string; value: IconPaint }[] = [
+  { label: "Original colors", value: "original" },
+  { label: "Theme color, like Paseo's icons", value: "theme" },
+  { label: "Theme accent", value: "accent" },
+  { label: "Linear indigo, the plugin color", value: "linear" },
+  { label: "Custom color", value: "custom" },
+];
+const PREVIEW_SIZES = [14, 16, 22, 28] as const;
+const SVG_FILES = ".svg,image/svg+xml";
+/** Exports often carry comments and metadata, so the file may be larger than the saved SVG. */
+const MAX_FILE_BYTES = MAX_SVG_LENGTH * 4;
+
+export function IconSettingsScreen({ theme }: PluginSurfaceProps) {
+  const settings = useSettings(linearSettings);
+  const render = useCallback(
+    (ready: ReadySettings) => <IconEditor theme={theme} settings={ready} />,
+    [theme],
+  );
+  return (
+    <SettingsGate theme={theme} title="Icon" settings={settings}>
+      {render}
+    </SettingsGate>
+  );
+}
+
+function IconPreview({ theme, icon }: { theme: Theme; icon: IconSettings }) {
+  const { colors } = theme;
+  const styles = useMemo(
+    () => ({
+      row: { flexDirection: "row" as const, flexWrap: "wrap" as const, alignItems: "center" as const, gap: 14, paddingTop: 8 },
+      pill: {
+        flexDirection: "row" as const,
+        alignItems: "center" as const,
+        gap: 6,
+        height: 26,
+        paddingHorizontal: 10,
+        borderRadius: 13,
+        borderWidth: 1,
+        borderColor: colors.border,
+        backgroundColor: colors.surface1,
+      },
+      label: { color: colors.foreground, fontSize: 12 },
+    }),
+    [colors],
+  );
+  return (
+    <View style={styles.row}>
+      {PREVIEW_SIZES.map((size) => (
+        <IconGlyph key={size} icon={icon} size={size} color={colors.foregroundMuted} theme={theme} />
+      ))}
+      <View style={styles.pill}>
+        <IconGlyph icon={icon} size={14} color={colors.foregroundMuted} theme={theme} />
+        <Text style={styles.label}>ENG-123</Text>
+      </View>
+      <View style={styles.pill}>
+        <IconGlyph icon={icon} size={14} color={colors.foreground} theme={theme} />
+        <Text style={styles.label}>Linear</Text>
+      </View>
+    </View>
+  );
+}
+
+function IconEditor({ theme, settings }: { theme: Theme; settings: ReadySettings }) {
+  const { values, dirty, edit, save, discard } = useSettingsDraft(settings);
+  const icon = values.icon;
+  const [markup, setMarkup] = useState(icon.svg);
+  const [markupError, setMarkupError] = useState<string | null>(null);
+  const [colorError, setColorError] = useState<string | null>(null);
+  const [fileName, setFileName] = useState<string | null>(null);
+  const change = useCallback(
+    (patch: Partial<IconSettings>) => edit((current) => ({ ...current, icon: { ...current.icon, ...patch } })),
+    [edit],
+  );
+  // The draft keeps the last SVG that passed the checks, so the preview never breaks.
+  const applyMarkup = useCallback(
+    (text: string) => {
+      setMarkup(text);
+      if (!text.trim()) {
+        setMarkupError(null);
+        change({ svg: "" });
+        return;
+      }
+      const parsed = parseIconSvg(text);
+      setMarkupError("error" in parsed ? parsed.error : null);
+      if ("svg" in parsed) change({ svg: parsed.svg });
+    },
+    [change],
+  );
+  const choose = useCallback(
+    () =>
+      pickTextFile(SVG_FILES, MAX_FILE_BYTES, (file) => {
+        if ("error" in file) {
+          setMarkupError(file.error);
+          return;
+        }
+        setFileName(file.name);
+        applyMarkup(file.text);
+      }),
+    [applyMarkup],
+  );
+  const useBuiltIn = useCallback(() => {
+    setFileName(null);
+    applyMarkup("");
+  }, [applyMarkup]);
+  const changeColor = useCallback(
+    (text: string) => {
+      const color = text.trim();
+      const valid = HEX_COLOR.test(color);
+      setColorError(valid ? null : "Use a hex color, such as #5E6AD2.");
+      if (valid) change({ color });
+    },
+    [change],
+  );
+  const reset = useCallback(() => {
+    discard();
+    setMarkup(settings.values.icon.svg);
+    setMarkupError(null);
+    setColorError(null);
+    setFileName(null);
+  }, [discard, settings.values.icon.svg]);
+  const native = Platform.OS !== "web";
+  const custom = icon.svg !== "";
+
+  return (
+    <View>
+      <SettingsSection title="Plugin icon">
+        <SettingsCard>
+          <SettingsRow
+            label="Preview"
+            hint={
+              native
+                ? "The iOS and Android apps cannot draw plugin SVG images, so they show the built-in icon in the color you choose."
+                : "Composer pills, the Linear sidebar row, and Linear screens use this icon. Paseo menus and panel tabs keep the built-in icon."
+            }
+          >
+            <IconPreview theme={theme} icon={icon} />
+          </SettingsRow>
+          {canPickFiles ? (
+            <SettingsAction
+              label="SVG file"
+              hint={fileName ? `Loaded ${fileName}. Save to use it.` : "Choose an .svg file. The plugin saves a copy in its settings."}
+              actionLabel="Choose file"
+              onPress={choose}
+            />
+          ) : null}
+          <MultilineField
+            theme={theme}
+            label="SVG markup"
+            hint="Paste SVG markup, or edit it here. Scripts, links to other files, and bitmap images are not allowed. Clear it to use the built-in icon."
+            value={markup}
+            placeholder={'<svg viewBox="0 0 24 24">…</svg>'}
+            error={markupError}
+            code
+            onChange={applyMarkup}
+          />
+          <SettingsAction
+            label="Built-in icon"
+            hint="Remove your SVG and use the Linear board icon."
+            actionLabel="Use built-in"
+            disabled={!custom && markup === ""}
+            onPress={useBuiltIn}
+          />
+        </SettingsCard>
+      </SettingsSection>
+      <SettingsSection title="Color and fill">
+        <SettingsCard>
+          <SettingsSelect
+            label="Color"
+            hint="Original colors keep the SVG as drawn, and currentColor follows Paseo. The other choices paint the whole icon one color."
+            value={icon.paint}
+            options={PAINT_OPTIONS}
+            onValueChange={(paint) => change({ paint })}
+          />
+          {icon.paint === "custom" ? (
+            <SettingsInput
+              label="Custom color"
+              hint="A hex color, such as #5E6AD2 or #5E6AD2CC with transparency."
+              initialValue={icon.color}
+              placeholder="#5E6AD2"
+              error={colorError}
+              onChangeText={changeColor}
+            />
+          ) : null}
+          <SettingsSwitch
+            label="Solid"
+            hint={custom ? "Fill shapes that only have an outline, so line icons show as solid shapes." : "Add your SVG to use this. The built-in icon stays as drawn."}
+            value={icon.solid}
+            disabled={!custom}
+            onValueChange={(solid) => change({ solid })}
+          />
+        </SettingsCard>
+      </SettingsSection>
+      <SaveBar
+        theme={theme}
+        dirty={dirty}
+        saving={settings.saving}
+        error={settings.saveError}
+        onSave={() => void save()}
+        onDiscard={reset}
+      />
+    </View>
+  );
+}

package/client/timeline-card.tsx

@@ -4,6 +4,7 @@ import { useCallback, useMemo } from "react";
 import { Pressable, Text, View } from "react-native";
 import type { IssueCard } from "../shared/linear";
 import { ACTION_LABELS } from "../shared/prompts";
+import { PluginIcon } from "./plugin-icon";
 import { usePressableStyle } from "./ui";
 
 export function IssueCardRow({ item, theme }: PluginTimelineItemProps<IssueCard>) {
@@ -44,7 +45,7 @@ export function IssueCardRow({ item, theme }: PluginTimelineItemProps<IssueCard>
       onPress={open}
       style={style}
     >
-      <Icon name="SquareKanban" size={16} color={colors.foregroundMuted} />
+      <PluginIcon size={16} color={colors.foregroundMuted} theme={theme} />
       <View style={styles.body}>
         <Text numberOfLines={1} style={styles.title}>
           <Text style={styles.identifier}>{`${card.identifier}  `}</Text>

package/client/ui.tsx

@@ -1,6 +1,6 @@
 import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
 import { Icon } from "@getpaseo/plugin/client/react-native";
-import { type ReactNode, useCallback, useMemo } from "react";
+import { type ComponentType, type ReactNode, useCallback, useMemo } from "react";
 import {
   ActivityIndicator,
   Pressable,
@@ -15,6 +15,15 @@ export { Avatar, LabelPill, PriorityIcon, priorityMeta, StateIcon } from "./glyp
 
 export type Theme = PluginSurfaceProps["theme"];
 
+/** A Lucide icon name, or a component such as the plugin icon. */
+export type Glyph = string | ComponentType<{ size: number; color: string; theme: Theme }>;
+
+export function GlyphIcon(props: { glyph: Glyph; size: number; color: string; theme: Theme }) {
+  const { glyph: Custom, size, color, theme } = props;
+  if (typeof Custom === "string") return <Icon name={Custom} size={size} color={color} />;
+  return <Custom size={size} color={color} theme={theme} />;
+}
+
 type InteractionState = PressableStateCallbackType & { hovered?: boolean };
 
 export function interactive(state: PressableStateCallbackType): boolean {
@@ -43,7 +52,7 @@ function buttonFill(variant: ButtonVariant, colors: Theme["colors"]): string {
 export interface ButtonProps {
   theme: Theme;
   label: string;
-  icon?: string;
+  icon?: Glyph;
   variant?: ButtonVariant;
   size?: keyof typeof HEIGHT;
   disabled?: boolean;
@@ -52,10 +61,10 @@ export interface ButtonProps {
   onPress(): void;
 }
 
-function ButtonGlyph(props: { busy: boolean; icon?: string; size: number; color: string }) {
+function ButtonGlyph(props: { busy: boolean; icon?: Glyph; size: number; color: string; theme: Theme }) {
   if (props.busy) return <ActivityIndicator size="small" color={props.color} />;
   if (!props.icon) return null;
-  return <Icon name={props.icon} size={props.size} color={props.color} />;
+  return <GlyphIcon glyph={props.icon} size={props.size} color={props.color} theme={props.theme} />;
 }
 
 export function Button({
@@ -103,7 +112,7 @@ export function Button({
       onPress={onPress}
       style={pressStyle}
     >
-      <ButtonGlyph busy={busy === true} icon={icon} size={size === "xs" ? 14 : 16} color={ink} />
+      <ButtonGlyph busy={busy === true} icon={icon} size={size === "xs" ? 14 : 16} color={ink} theme={theme} />
       <Text numberOfLines={1} style={styles.label}>
         {label}
       </Text>
@@ -276,7 +285,7 @@ export function OptionRow(props: {
 
 export function EmptyState(props: {
   theme: Theme;
-  icon: string;
+  icon: Glyph;
   title: string;
   detail?: string;
   tone?: "default" | "danger";
@@ -309,7 +318,7 @@ export function EmptyState(props: {
   );
   return (
     <View style={styles.root}>
-      <Icon name={props.icon} size={28} color={colors.foregroundMuted} />
+      <GlyphIcon glyph={props.icon} size={28} color={colors.foregroundMuted} theme={props.theme} />
       <Text style={styles.title}>{props.title}</Text>
       {props.detail ? <Text style={styles.detail}>{props.detail}</Text> : null}
       {props.children}

package/client/web.ts

@@ -2,6 +2,7 @@ import { Platform } from "react-native";
 
 // The only module that uses the DOM. React wheel listeners are passive, so they cannot keep
 // the page from scrolling while the wheel zooms the graph. Off the web each export does nothing.
+// The file picker is a hidden file input, because plugins cannot use native document pickers.
 
 interface WheelEventLike {
   deltaY: number;
@@ -43,3 +44,48 @@ export function listenWheel(
   node.addEventListener("wheel", listener, { passive: false });
   return () => node.removeEventListener("wheel", listener);
 }
+
+interface FileLike {
+  name: string;
+  size: number;
+  text(): Promise<string>;
+}
+
+interface FileInputLike {
+  type: string;
+  accept: string;
+  files: ArrayLike<FileLike> | null;
+  onchange: (() => void) | null;
+  click(): void;
+}
+
+interface DocumentLike {
+  createElement(tag: "input"): FileInputLike;
+}
+
+/** True where pickTextFile can open a file picker. */
+export const canPickFiles = Platform.OS === "web";
+
+export type PickedFile = { name: string; text: string } | { error: string };
+
+/** Opens the browser file picker and calls onPick with the chosen file. Nothing on cancel. */
+export function pickTextFile(accept: string, maxBytes: number, onPick: (file: PickedFile) => void): void {
+  const document = (globalThis as { document?: DocumentLike }).document;
+  if (!canPickFiles || !document) return;
+  const input = document.createElement("input");
+  input.type = "file";
+  input.accept = accept;
+  input.onchange = () => {
+    const file = input.files?.[0];
+    if (!file) return;
+    if (file.size > maxBytes) {
+      onPick({ error: `${file.name} is too large. Use a file under ${Math.round(maxBytes / 1000)} KB.` });
+      return;
+    }
+    file.text().then(
+      (text) => onPick({ name: file.name, text }),
+      () => onPick({ error: `Paseo could not read ${file.name}.` }),
+    );
+  };
+  input.click();
+}

package/index.client.tsx

@@ -4,7 +4,9 @@ import { openPluginScreen, registerScreen } from "./client/compat";
 import { gateAgentPanel } from "./client/access";
 import { LivePanel } from "./client/live-panel";
 import { contributeComposerPills } from "./client/pill";
+import { PluginIcon } from "./client/plugin-icon";
 import { ConnectionSettings } from "./client/settings-connection";
+import { IconSettingsScreen } from "./client/settings-icon";
 import { LiveSettings } from "./client/settings-live";
 import { ProjectSettings } from "./client/settings-projects";
 import { PromptSettings } from "./client/settings-prompts";
@@ -23,6 +25,7 @@ export default function contribute(client: PluginClientContext) {
     id: SCREEN_ID,
     title: "Linear",
     icon: "SquareKanban",
+    RowIcon: PluginIcon,
     Component: LinearScreen,
   });
   client.addWorkspacePanel({
@@ -58,6 +61,12 @@ export default function contribute(client: PluginClientContext) {
     icon: "Radar",
     Component: LiveSettings,
   });
+  client.addSettingsScreen({
+    id: "icon",
+    title: "Icon",
+    icon: "Shapes",
+    Component: IconSettingsScreen,
+  });
   client.addSettingsScreen({
     id: "projects",
     title: "Projects",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yannelli/paseo-linear-plugin",
-  "version": "1.1.0-beta.1",
+  "version": "1.1.0-beta.2",
   "description": "Browse and triage Linear issues in Paseo and start agents from them",
   "license": "Apache-2.0",
   "type": "module",

package/shared/custom-icon.ts

@@ -0,0 +1,148 @@
+import { z } from "zod";
+
+// The user's own plugin icon. The web app draws it as an image, which never runs scripts or
+// loads files; the checks below also refuse such content. Paint recolors every visible pixel,
+// and Solid fills shapes that only have an outline.
+
+export const ICON_PAINTS = ["original", "theme", "accent", "linear", "custom"] as const;
+export type IconPaint = (typeof ICON_PAINTS)[number];
+
+/** Linear's brand indigo, the plugin's own color. */
+export const LINEAR_INDIGO = "#5E6AD2";
+export const MAX_SVG_LENGTH = 64_000;
+export const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+export const IconSettingsSchema = z.object({
+  /** Checked SVG markup. Empty uses the built-in icon. */
+  svg: z.string().max(MAX_SVG_LENGTH).default(""),
+  paint: z.enum(ICON_PAINTS).default("original"),
+  /** The color of the custom paint. */
+  color: z.string().regex(HEX_COLOR).default(LINEAR_INDIGO),
+  /** Fill shapes that only have an outline. */
+  solid: z.boolean().default(false),
+});
+export type IconSettings = z.infer<typeof IconSettingsSchema>;
+
+const BLOCKED: readonly (readonly [RegExp, string])[] = [
+  [/<!DOCTYPE|<!ENTITY/i, "The SVG has a DOCTYPE or entities. Export it again without them."],
+  [/<script[\s>/]/i, "The SVG has a script. Use an SVG with shapes only."],
+  [/<foreignObject[\s>/]/i, "The SVG has HTML content. Use an SVG with shapes only."],
+  [/<[^>]*\son[a-z]+\s*=/i, "The SVG has event handlers. Use an SVG with shapes only."],
+  [/[\s:]href\s*=\s*["']\s*(?!#)/i, "The SVG links to other files or images. Use an SVG that has all its shapes inside."],
+  [/url\(\s*["']?\s*(?!#)/i, "The SVG uses files outside it. Use an SVG that has all its shapes inside."],
+  [/@import/i, "The SVG imports styles from another file."],
+];
+
+const ROOT_TAG = /^<svg\b[^>]*>/i;
+const NUMBER = String.raw`(-?[\d.]+(?:e[-+]?\d+)?)`;
+const VIEW_BOX = new RegExp(String.raw`\sviewBox\s*=\s*["']\s*${NUMBER}[\s,]+${NUMBER}[\s,]+${NUMBER}[\s,]+${NUMBER}\s*["']`, "i");
+
+const attribute = (tag: string, name: string) =>
+  new RegExp(String.raw`\s${name}\s*=\s*["']([^"']*)["']`, "i").exec(tag)?.[1]?.trim() ?? null;
+const withoutAttribute = (tag: string, name: string) =>
+  tag.replace(new RegExp(String.raw`\s${name}\s*=\s*(?:"[^"]*"|'[^']*')`, "gi"), "");
+
+/** The root's viewBox as x, y, width, and height, or null without a usable one. */
+export function viewBoxOf(svg: string): [number, number, number, number] | null {
+  const root = ROOT_TAG.exec(svg)?.[0] ?? "";
+  const box = VIEW_BOX.exec(root)?.slice(1, 5).map(Number);
+  if (!box || box.some((value) => !Number.isFinite(value))) return null;
+  const [x = 0, y = 0, width = 0, height = 0] = box;
+  return width > 0 && height > 0 ? [x, y, width, height] : null;
+}
+
+/** Checks pasted or uploaded SVG and returns it ready to save, or why it cannot be used. */
+export function parseIconSvg(text: string): { svg: string } | { error: string } {
+  const svg = text
+    .replace(/^\uFEFF/, "")
+    .replace(/<\?[\s\S]*?\?>/g, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .trim();
+  if (!svg) return { error: "Paste SVG markup or choose an SVG file." };
+  if (svg.length > MAX_SVG_LENGTH) {
+    return { error: `The SVG is too large. Use one under ${Math.round(MAX_SVG_LENGTH / 1000)} KB.` };
+  }
+  if (!/^<svg[\s>]/i.test(svg) || !/<\/svg>$/i.test(svg)) {
+    return { error: "This is not an SVG. It must start with <svg and end with </svg>." };
+  }
+  for (const [pattern, error] of BLOCKED) if (pattern.test(svg)) return { error };
+  const root = ROOT_TAG.exec(svg)?.[0] ?? "";
+  let next = root;
+  if (!viewBoxOf(svg)) {
+    const width = Number(/^([\d.]+)(?:px)?$/.exec(attribute(root, "width") ?? "")?.[1]);
+    const height = Number(/^([\d.]+)(?:px)?$/.exec(attribute(root, "height") ?? "")?.[1]);
+    if (!(width > 0 && height > 0)) return { error: "The SVG needs a viewBox, or a width and height in pixels." };
+    next = withoutAttribute(next, "viewBox").replace(/^<svg/i, `<svg viewBox="0 0 ${width} ${height}"`);
+  }
+  // The image scales to its box from the viewBox, so a fixed size would only crop it.
+  next = withoutAttribute(withoutAttribute(next, "width"), "height");
+  if (!/\sxmlns\s*=/.test(next)) next = next.replace(/^<svg/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+  return { svg: next + svg.slice(root.length) };
+}
+
+/** Keeps a color inside an attribute value; anything else becomes gray. */
+export function safeColor(color: string): string {
+  return /^[#a-z0-9(),.%\s-]+$/i.test(color) ? color.trim() : "#888888";
+}
+
+const FILL_NONE = /(?<![\w-])(fill\s*:\s*)none\b/gi;
+
+/** Fills shapes that only have an outline, with their stroke color or the icon color. */
+export function fillOutlines(svg: string): string {
+  const tags = svg.replace(/<([a-z][\w:.-]*)(\s[^>]*?)?(\/?)>/gi, (tag, name: string, attrs: string | undefined, close: string) => {
+    if (!attrs) return tag;
+    const stroke = attribute(attrs, "stroke") ?? /(?<![\w-])stroke\s*:\s*([^;"']+)/i.exec(attrs)?.[1]?.trim();
+    const fill = stroke && stroke !== "none" ? stroke : "currentColor";
+    const next = attrs.replace(/(\sfill\s*=\s*["'])\s*none\s*(["'])/gi, `$1${fill}$2`).replace(FILL_NONE, `$1${fill}`);
+    return `<${name}${next}${close}>`;
+  });
+  return tags.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (_all, open: string, css: string, end: string) =>
+    `${open}${css.replace(FILL_NONE, "$1currentColor")}${end}`,
+  );
+}
+
+const TINT_ID = "paseo-linear-tint";
+
+/** Paints every visible pixel one color and keeps its transparency. */
+export function tint(svg: string, color: string): string {
+  const [x, y, width, height] = viewBoxOf(svg) ?? [0, 0, 24, 24];
+  const filter =
+    `<filter id="${TINT_ID}" filterUnits="userSpaceOnUse" x="${x - width}" y="${y - height}" width="${width * 3}" height="${height * 3}" color-interpolation-filters="sRGB">` +
+    `<feFlood flood-color="${safeColor(color)}"/><feComposite in2="SourceAlpha" operator="in"/></filter>`;
+  return svg
+    .replace(ROOT_TAG, (root) => `${root}<defs>${filter}</defs><g filter="url(#${TINT_ID})">`)
+    .replace(/<\/svg>$/i, "</g></svg>");
+}
+
+export interface IconLook {
+  /** The color `currentColor` takes: the color Paseo gives the icon. */
+  ink: string;
+  /** One color for the whole icon, or null to keep its colors. */
+  paint: string | null;
+  solid: boolean;
+}
+
+/** The SVG to draw for saved markup, or null when it no longer passes the checks. */
+export function iconMarkup(saved: string, look: IconLook): string | null {
+  const parsed = parseIconSvg(saved);
+  if ("error" in parsed) return null;
+  const filled = look.solid ? fillOutlines(parsed.svg) : parsed.svg;
+  const inked = filled.replace(/currentColor/gi, safeColor(look.ink));
+  return look.paint ? tint(inked, look.paint) : inked;
+}
+
+/** The one color a paint gives, or null for the icon's own colors. */
+export function paintColor(icon: IconSettings, colors: { ink: string; accent: string }): string | null {
+  switch (icon.paint) {
+    case "original":
+      return null;
+    case "theme":
+      return colors.ink;
+    case "accent":
+      return colors.accent;
+    case "linear":
+      return LINEAR_INDIGO;
+    case "custom":
+      return icon.color;
+  }
+}

package/shared/settings.ts

@@ -1,5 +1,6 @@
 import { defineRpc, defineSettings } from "@getpaseo/plugin";
 import { z } from "zod";
+import { IconSettingsSchema } from "./custom-icon";
 
 export const AGENT_ACTIONS = ["implement", "review"] as const;
 export type AgentAction = (typeof AGENT_ACTIONS)[number];
@@ -101,6 +102,8 @@ export const linearSettings = defineSettings({
       })
       .prefault({}),
     projects: z.array(ProjectConfigSchema).default([]),
+    /** The icon of pills and other plugin places: built-in or the user's SVG. */
+    icon: IconSettingsSchema.prefault({}),
   }),
 });