@yuriai/web 0.2.31 → 0.2.32-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (201) hide show
  1. package/README.md +19 -0
  2. package/dist/assets/{AgentAvatar-DLAQkFQe.js → AgentAvatar-DLzcNrQ0.js} +1 -1
  3. package/dist/assets/AssistantContactStatus-Bf1yg0yx.js +3 -0
  4. package/dist/assets/{AssistantUnreadBadge-BynxNQMk.js → AssistantUnreadBadge-BUFyxUrT.js} +1 -1
  5. package/dist/assets/{AssistantView-CDZyA9ft.js → AssistantView-CELFybSr.js} +1 -1
  6. package/dist/assets/{DiagramView-DdVFGHQQ.js → DiagramView-DV4P3-Wg.js} +1 -1
  7. package/dist/assets/{FadeInOnReveal-C9a7XnAh.js → FadeInOnReveal-BRrU2ivL.js} +1 -1
  8. package/dist/assets/{GuiPluginSurface-v8r-Hex5.js → GuiPluginSurface-NOHaJGy2.js} +1 -1
  9. package/dist/assets/{GuiPluginWindow-Ba1HfrjQ.js → GuiPluginWindow-BykPaQeY.js} +1 -1
  10. package/dist/assets/Icon-OJf0qBKf.js +1 -0
  11. package/dist/assets/{ImageLoadingPlaceholder-Dcy5lc7F.js → ImageLoadingPlaceholder-DlQbo9CM.js} +1 -1
  12. package/dist/assets/{LoadingImage-BxjJ_Xyj.js → LoadingImage-sZ5omN5L.js} +1 -1
  13. package/dist/assets/MarkdownRenderer-BFR9FWQL.js +2 -0
  14. package/dist/assets/MarkdownRendererImpl-iZFUMI3M.js +10 -0
  15. package/dist/assets/{MarkstreamRendererImpl-EpBnVy9J.css → MarkstreamRendererImpl-C6aiJnjl.css} +1 -1
  16. package/dist/assets/MarkstreamRendererImpl-DjC_Y4LS.js +3 -0
  17. package/dist/assets/{MobileDetailNavigation-o54juFXD.js → MobileDetailNavigation-BOZpHdI2.js} +1 -1
  18. package/dist/assets/{MobileResizableSheet-sV9XR-0k.js → MobileResizableSheet-DuAi_epR.js} +1 -1
  19. package/dist/assets/{MobileShareBridge-oqBZ_f6M.js → MobileShareBridge-D1DrqLWf.js} +1 -1
  20. package/dist/assets/MobileTabPageHeader-BT9gWugr.js +2 -0
  21. package/dist/assets/{MultiRunWindow-7W_86vL6.js → MultiRunWindow-C0GYNaUU.js} +1 -1
  22. package/dist/assets/{OnboardingScreen-CnkijSLE.js → OnboardingScreen-CqsI0632.js} +1 -1
  23. package/dist/assets/{OverlayScrollbar-CCtBTJQj.js → OverlayScrollbar-CZD1yU06.js} +1 -1
  24. package/dist/assets/SettingsView-BYO8LY5A.js +29 -0
  25. package/dist/assets/{SettingsWindow-C0HiNvXh.js → SettingsWindow-CM0Ph9WD.js} +1 -1
  26. package/dist/assets/SetupTourDialog-BYlSBPKZ.js +1 -0
  27. package/dist/assets/SetupTourDialog-DrL_4ODI.css +1 -0
  28. package/dist/assets/{TerminalView-y36H_fIe.js → TerminalView-DnyEAShU.js} +1 -1
  29. package/dist/assets/{ToolOutputDialog-BfjBeqGS.js → ToolOutputDialog-BWONfWze.js} +1 -1
  30. package/dist/assets/{VoiceSettings-BONwzGgR.js → VoiceSettings-Ru_0ySgM.js} +2 -2
  31. package/dist/assets/{YuriLogo-BA5FWp-g.js → YuriLogo-CMUoGUHc.js} +1 -1
  32. package/dist/assets/YuriWordmark-DHYo0FlR.js +1 -0
  33. package/dist/assets/{appThemeRegistry-BsLMp3bc.js → appThemeRegistry-BMlAlm0m.js} +1 -1
  34. package/dist/assets/{button-CBjOhOI0.js → button-C-gRcs_2.js} +1 -1
  35. package/dist/assets/{capgoAdapter-DjlyVxy_.js → capgoAdapter-GdNfjwXs.js} +1 -1
  36. package/dist/assets/checkbox-BrJBzET8.js +1 -0
  37. package/dist/assets/{collapsible-B0j5IQ0T.js → collapsible-B7esGYLd.js} +1 -1
  38. package/dist/assets/{context-menu-C4e_bpls.js → context-menu-DWn1nSZC.js} +1 -1
  39. package/dist/assets/desktopHosts-BLU1tGSX.js +1 -0
  40. package/dist/assets/{desktopRelayRestore-AE3_TnQz.js → desktopRelayRestore-2BIIs8mZ.js} +1 -1
  41. package/dist/assets/{diagram-WPmk0Qh6.js → diagram-Bnra5_6g.js} +1 -1
  42. package/dist/assets/{dialog-Dx3IT7dQ.js → dialog-3UseH0hM.js} +1 -1
  43. package/dist/assets/{es-JU--16Gd.js → es-J7a_sZ1u.js} +2 -2
  44. package/dist/assets/{fileMentionTouchSelection-Bizsisaj.js → fileMentionTouchSelection-ByaQJcTS.js} +1 -1
  45. package/dist/assets/{fr-BUZcRuMk.js → fr-BYxUMKWp.js} +2 -2
  46. package/dist/assets/{gitApi-CNgEj6X5.js → gitApi-BdwvoQFb.js} +1 -1
  47. package/dist/assets/historyImportQueries-C8VK9R5_.js +1 -0
  48. package/dist/assets/host-z9PU8q1e.js +1 -0
  49. package/dist/assets/{input-CEJGM-TS.js → input-CmLlZdeD.js} +1 -1
  50. package/dist/assets/insertionBoundaries-BpQ6nLjP.js +1 -0
  51. package/dist/assets/{ja-BwtVLTXD.js → ja-DCdBiJmD.js} +2 -2
  52. package/dist/assets/{ko--sLsRFpA.js → ko-D-Nb_RJY.js} +2 -2
  53. package/dist/assets/main-Dosy2jXg.js +2 -0
  54. package/dist/assets/main-oBh-dk5-.js +169 -0
  55. package/dist/assets/{markdownHeightCache-D6iSNJG2.js → markdownHeightCache-xNkQdlqi.js} +1 -1
  56. package/dist/assets/{mcpQueries-DVSsZeuk.js → mcpQueries-C8zsTQqJ.js} +1 -1
  57. package/dist/assets/miniChat-CI8ryDGT.js +2 -0
  58. package/dist/assets/mobile-e_mTK3dh.js +2 -0
  59. package/dist/assets/{mobileBackNavigation-Dmbf0kw1.js → mobileBackNavigation-sB7c0Pi4.js} +1 -1
  60. package/dist/assets/multirun-DbmgWrsY.js +3 -0
  61. package/dist/assets/{native-config-BaRHaY4y.js → native-config-C_mwkFzh.js} +1 -1
  62. package/dist/assets/{pl-C4_4J5yA.js → pl-AmU4w3aM.js} +2 -2
  63. package/dist/assets/{projectMeta-rrpZdm8D.js → projectMeta-1iUbVl_M.js} +1 -1
  64. package/dist/assets/{pt-BR-DvNC5K1q.js → pt-BR-BI4ft-Fj.js} +2 -2
  65. package/dist/assets/pwa-BdUAGhLt.js +2 -0
  66. package/dist/assets/{queue-abort-optimistic-CSkERbr4.js → queue-abort-optimistic-BwDsaym5.js} +1 -1
  67. package/dist/assets/react-a6PrrNTm.js +1 -0
  68. package/dist/assets/{readiness-BnO7IaZV.js → readiness-D2N0DtZF.js} +1 -1
  69. package/dist/assets/{renderElectronMiniChatApp-Bq3iNKtr.js → renderElectronMiniChatApp-DV0cNt_O.js} +2 -2
  70. package/dist/assets/{renderMobileApp-DiNeMgwp.js → renderMobileApp-b7--jT5z.js} +7 -7
  71. package/dist/assets/{runtimeConfig-BHOiBANF.js → runtimeConfig-DxmJLWUO.js} +1 -1
  72. package/dist/assets/runtimeEndpointReset-jYAYa3Rh.js +149 -0
  73. package/dist/assets/{select-bKMw5JE8.js → select-J8r9SxHt.js} +1 -1
  74. package/dist/assets/sessionLookup-CUQqj2N4.js +1 -0
  75. package/dist/assets/{sortable-tabs-strip-3sKiA7T1.js → sortable-tabs-strip-CiP6RIQa.js} +1 -1
  76. package/dist/assets/{speechSettingsQueries-BDDxw8LP.js → speechSettingsQueries-B3ziGQvb.js} +1 -1
  77. package/dist/assets/src-GtPQ8f4o.css +2 -0
  78. package/dist/assets/{store-X3lU0obe.js → store-OjrIiXCx.js} +5 -5
  79. package/dist/assets/{textarea-EsaDD051.js → textarea-BHgcxJdC.js} +1 -1
  80. package/dist/assets/{tooltip-LLDL5nIZ.js → tooltip-Degmpxnd.js} +1 -1
  81. package/dist/assets/tour-DDI0Zg7l.js +1 -0
  82. package/dist/assets/types-QETHY-S7.js +2 -0
  83. package/dist/assets/{uk-Dvj0JjiC.js → uk-CbdByxxj.js} +2 -2
  84. package/dist/assets/{useAppFontEffects-wIWWE59b.js → useAppFontEffects-LADr3Zl1.js} +53 -53
  85. package/dist/assets/useDesktopWindowControlsLayout-BVNnRHtc.js +1 -0
  86. package/dist/assets/{useDictation-DlEHSN6P.js → useDictation-DFVJpRbm.js} +1 -1
  87. package/dist/assets/{useEffectiveDirectory-DzqpWUC3.js → useEffectiveDirectory-8tqfGdV5.js} +1 -1
  88. package/dist/assets/{useMobileNavigationStore-BWLhXqci.js → useMobileNavigationStore-CLUFv-TZ.js} +13 -13
  89. package/dist/assets/usePluginsStore-B_SIDwsK.js +1 -0
  90. package/dist/assets/useStreamingTextThrottle-VhgGU_te.js +1 -0
  91. package/dist/assets/{useWorkerHighlightedLines-DMS69wKa.js → useWorkerHighlightedLines-jlxakDGs.js} +1 -1
  92. package/dist/assets/{vendor-markstream-react-DfLaSG3W.js → vendor-markstream-react-6zxyQLCD.js} +1 -1
  93. package/dist/assets/{zh-CN-2Y6u8t24.js → zh-CN-ufEVDbXp.js} +2 -2
  94. package/dist/assets/{zh-TW-Z5wVv4Fb.js → zh-TW-DTBlZ4YC.js} +2 -2
  95. package/dist/index.html +8 -8
  96. package/dist/mini-chat.html +8 -8
  97. package/dist/mobile.html +8 -8
  98. package/package.json +1 -1
  99. package/server/index.js +3 -0
  100. package/server/lib/client-auth/pairing.js +2 -0
  101. package/server/lib/client-auth/pairing.test.js +29 -0
  102. package/server/lib/config-sync/DOCUMENTATION.md +8 -4
  103. package/server/lib/config-sync/index.js +1 -1
  104. package/server/lib/config-sync/magpie-auth.js +10 -4
  105. package/server/lib/config-sync/magpie-auth.test.js +4 -0
  106. package/server/lib/config-sync/magpie.js +28 -22
  107. package/server/lib/config-sync/magpie.test.js +127 -2
  108. package/server/lib/config-sync/plugins.js +44 -0
  109. package/server/lib/config-sync/plugins.test.js +64 -0
  110. package/server/lib/config-sync/tar.js +61 -1
  111. package/server/lib/content-search/DOCUMENTATION.md +9 -0
  112. package/server/lib/content-search/routes.js +18 -1
  113. package/server/lib/content-search/routes.test.js +21 -0
  114. package/server/lib/content-search/runtime.js +7 -3
  115. package/server/lib/content-search/runtime.test.js +26 -0
  116. package/server/lib/gui-customization/DOCUMENTATION.md +21 -1
  117. package/server/lib/gui-customization/session-skill.js +2 -2
  118. package/server/lib/gui-customization/session-skill.test.js +3 -1
  119. package/server/lib/gui-customization/skill/SKILL.md +5 -1
  120. package/server/lib/gui-customization/skill/references/global-pages.md +1 -1
  121. package/server/lib/gui-customization/skill/references/gui-api.md +4 -1
  122. package/server/lib/gui-customization/skill/references/icons.md +134 -0
  123. package/server/lib/gui-customization/skill/references/plugin-styles.md +112 -0
  124. package/server/lib/gui-customization/skill/references/ui-surfaces.md +2 -0
  125. package/server/lib/gui-customization/skill/references/work-status.md +110 -0
  126. package/server/lib/history-import/AGENT_CONNECT_LICENSE +21 -0
  127. package/server/lib/history-import/DOCUMENTATION.md +223 -0
  128. package/server/lib/history-import/dev-proxy.integration.test.js +56 -0
  129. package/server/lib/history-import/events.js +322 -0
  130. package/server/lib/history-import/events.test.js +110 -0
  131. package/server/lib/history-import/installations.js +39 -0
  132. package/server/lib/history-import/installations.test.js +24 -0
  133. package/server/lib/history-import/native.js +49 -0
  134. package/server/lib/history-import/native.test.js +42 -0
  135. package/server/lib/history-import/routes.js +48 -0
  136. package/server/lib/history-import/routes.test.js +55 -0
  137. package/server/lib/history-import/service.js +374 -0
  138. package/server/lib/history-import/service.test.js +538 -0
  139. package/server/lib/history-import/settings.js +146 -0
  140. package/server/lib/history-import/settings.test.js +88 -0
  141. package/server/lib/history-import/sources.js +184 -0
  142. package/server/lib/history-import/sources.test.js +190 -0
  143. package/server/lib/history-import/sqlite.js +187 -0
  144. package/server/lib/history-import/store.js +58 -0
  145. package/server/lib/history-import/store.test.js +84 -0
  146. package/server/lib/history-import/targets.js +24 -0
  147. package/server/lib/host-update/DOCUMENTATION.md +6 -0
  148. package/server/lib/host-update/routes.test.js +1 -1
  149. package/server/lib/notifications/native-stream.relay.test.js +1 -0
  150. package/server/lib/opencode/DOCUMENTATION.md +14 -0
  151. package/server/lib/opencode/core-routes.js +1 -0
  152. package/server/lib/opencode/feature-routes-runtime.js +11 -1
  153. package/server/lib/opencode/plugin-routes.test.js +1 -0
  154. package/server/lib/opencode/plugins.js +1 -1
  155. package/server/lib/opencode/plugins.test.js +3 -2
  156. package/server/lib/opencode/proxy.js +29 -4
  157. package/server/lib/opencode/proxy.test.js +85 -1
  158. package/server/lib/opencode/server-utils-runtime.js +2 -0
  159. package/server/lib/opencode/settings-runtime.js +8 -6
  160. package/server/lib/opencode/settings-runtime.test.js +44 -0
  161. package/server/lib/opencode/yuri-routes.js +1 -1
  162. package/server/lib/relay/DOCUMENTATION.md +1 -1
  163. package/server/lib/relay/host-client.js +3 -1
  164. package/server/lib/relay/host-client.test.js +1 -0
  165. package/server/lib/relay/reasoning-projection.e2e.test.ts +1 -0
  166. package/server/lib/relay/relay-server.e2e.test.ts +32 -17
  167. package/server/lib/relay/service.js +2 -0
  168. package/server/lib/relay/tunnel-host.js +26 -1
  169. package/server/lib/relay/tunnel-host.test.js +27 -3
  170. package/server/lib/remote-desktop/runtime.test.js +2 -2
  171. package/server/lib/ui-auth/DOCUMENTATION.md +3 -0
  172. package/server/lib/ui-auth/ui-auth.js +27 -0
  173. package/server/lib/ui-auth/ui-auth.test.js +42 -1
  174. package/server/plugin-gui-proxy.test.js +1 -1
  175. package/dist/assets/AssistantContactStatus-DZGGspw4.js +0 -3
  176. package/dist/assets/Icon-Bh3TaKoN.js +0 -1
  177. package/dist/assets/MarkdownRenderer-CS6Pia5D.js +0 -2
  178. package/dist/assets/MarkdownRendererImpl-Bdwe3qUr.js +0 -10
  179. package/dist/assets/MarkstreamRendererImpl-CCQj9IkL.js +0 -3
  180. package/dist/assets/MobileTabPageHeader-CptcDWNS.js +0 -2
  181. package/dist/assets/SettingsView-CkJpYIMe.js +0 -29
  182. package/dist/assets/SetupTourDialog-BcEbaEO3.js +0 -1
  183. package/dist/assets/SetupTourDialog-CUzqT2sw.css +0 -1
  184. package/dist/assets/YuriWordmark-Cr1vkcue.js +0 -1
  185. package/dist/assets/desktopHosts-CMglnUdS.js +0 -1
  186. package/dist/assets/host-CBfSyi4l.js +0 -1
  187. package/dist/assets/insertionBoundaries-CgYf6gys.js +0 -1
  188. package/dist/assets/main-B8FcBwPM.js +0 -169
  189. package/dist/assets/main-DrqtyqDc.js +0 -2
  190. package/dist/assets/miniChat-CgeCl4RY.js +0 -2
  191. package/dist/assets/mobile-DAhJKHUq.js +0 -2
  192. package/dist/assets/multirun-BbWnHeaY.js +0 -3
  193. package/dist/assets/pwa-Dm_DJEr9.js +0 -2
  194. package/dist/assets/react-Bwr5-XPi.js +0 -1
  195. package/dist/assets/runtimeEndpointReset-DGxT24oE.js +0 -149
  196. package/dist/assets/sessionLookup-DGNxfDsP.js +0 -1
  197. package/dist/assets/src-PTWgTO6W.css +0 -2
  198. package/dist/assets/tour-Db44qwfs.js +0 -1
  199. package/dist/assets/types-Cl7nTpsb.js +0 -2
  200. package/dist/assets/useDesktopWindowControlsLayout-CdUr9mCZ.js +0 -1
  201. package/dist/assets/usePluginsStore-aZl0WTK8.js +0 -1
@@ -0,0 +1,44 @@
1
+ import { applyEdits, createScanner, getNodeValue, parseTree, SyntaxKind } from 'jsonc-parser';
2
+ import { isPathSpec, parseNpmSpec } from '../opencode/plugin-spec.js';
3
+
4
+ const isNpmPlugin = (entry) => {
5
+ const value = Array.isArray(entry) ? entry[0] : (typeof entry === 'object' && entry !== null ? entry.package : entry);
6
+ if (typeof value !== 'string') return false;
7
+ const spec = value.trim();
8
+ if (isPathSpec(spec)) return false;
9
+ const parsed = parseNpmSpec(spec);
10
+ if (parsed.malformed || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i.test(parsed.name)) return false;
11
+ return parsed.version === null || /^[\w.*+~^<>=| -]+$/.test(parsed.version);
12
+ };
13
+
14
+ /** Keep portable registry declarations without rewriting unrelated JSONC content. */
15
+ export const filterSyncedPluginConfig = (content) => {
16
+ const bom = content.startsWith('\uFEFF') ? '\uFEFF' : '';
17
+ const text = content.slice(bom.length);
18
+ const errors = [];
19
+ const tree = parseTree(text, errors, { allowTrailingComma: true, allowEmptyContent: true });
20
+ const invalid = () => new Error('Cannot sync plugins: invalid OpenCode JSONC configuration');
21
+ if (errors.length || (tree && tree.type !== 'object')) throw invalid();
22
+ const seen = new Set();
23
+ const edits = [];
24
+ for (const property of tree?.children || []) {
25
+ const [keyNode, valueNode] = property.children;
26
+ const key = keyNode.value;
27
+ if (key !== 'plugins' && key !== 'plugin') continue;
28
+ if (seen.has(key) || valueNode.type !== 'array') throw invalid();
29
+ seen.add(key);
30
+ const entries = valueNode.children || [];
31
+ const keep = entries.map((entry) => isNpmPlugin(getNodeValue(entry)));
32
+ if (keep.every(Boolean)) continue;
33
+ const lastKept = keep.lastIndexOf(true);
34
+ const scanner = createScanner(text, true);
35
+ for (const [index, entry] of entries.entries()) {
36
+ if (!keep[index]) edits.push({ offset: entry.offset, length: entry.length, content: '' });
37
+ scanner.setPosition(entry.offset + entry.length);
38
+ if (scanner.scan() === SyntaxKind.CommaToken && (!keep[index] || index >= lastKept)) {
39
+ edits.push({ offset: scanner.getTokenOffset(), length: scanner.getTokenLength(), content: '' });
40
+ }
41
+ }
42
+ }
43
+ return bom + applyEdits(text, edits);
44
+ };
@@ -0,0 +1,64 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import { parse } from 'jsonc-parser';
3
+ import { filterSyncedPluginConfig } from './plugins.js';
4
+
5
+ describe('portable plugin declarations', () => {
6
+ it.each([
7
+ 'file:///home/user/plugin', 'file:../plugin', '/opt/plugins/local', '//server/share/plugin',
8
+ './plugins/local', '../local', '~/plugins/local', 'C:\\plugins\\local', '\\\\server\\share\\local',
9
+ 'plugins/local', '.\\plugins\\local', 'link:../plugin', 'workspace:*',
10
+ 'https://example.com/plugin.tgz', 'git+https://example.com/plugin.git', 'github:org/plugin',
11
+ 'plugin@file:../local', 'plugin@/opt/local', '@scope/plugin@link:../local',
12
+ ])('excludes %s in string, tuple and object declarations', (spec) => {
13
+ const content = JSON.stringify({
14
+ plugin: [spec, [spec, { enabled: true }], 'registry-plugin@^1.2.0'],
15
+ plugins: [spec, { package: spec, options: { enabled: true } }, '@scope/registry@beta'],
16
+ });
17
+ expect(JSON.parse(filterSyncedPluginConfig(content))).toEqual({
18
+ plugin: ['registry-plugin@^1.2.0'], plugins: ['@scope/registry@beta'],
19
+ });
20
+ });
21
+
22
+ it('preserves registry versions, scopes, ordering, tuple options and V2 object fields', () => {
23
+ const config = {
24
+ plugin: [['existing@1.2.3', { mode: 'safe', path: '/keep-option' }]],
25
+ plugins: ['bare', '@scope/bare', 'range@>=1.0.0 <2.0.0', 'tag@latest',
26
+ { package: '@scope/plugin@2.0.0-beta.1+build.3', options: { nested: [1, true] }, disabled: true }],
27
+ };
28
+ const content = JSON.stringify(config, null, 2);
29
+ expect(filterSyncedPluginConfig(content)).toBe(content);
30
+ });
31
+
32
+ it('filters both keys while retaining BOM, comments, trailing commas and unrelated content', () => {
33
+ const content = '\uFEFF{\r\n // Keep provider configuration.\r\n "provider": { "example": { "options": { "baseURL": "http://localhost:3000" } } },\r\n "plugins": [\r\n "file:///opt/local",\r\n // Registry options stay intact.\r\n { "package": "@scope/plugin@^2", "options": { "mode": "safe" } },\r\n "./local",\r\n ],\r\n "plugin": [["../legacy", {}], ["legacy@1", { "flag": true }]],\r\n}\r\n';
34
+ const filtered = filterSyncedPluginConfig(content);
35
+ const config = parse(filtered.slice(1));
36
+ expect(config.plugins).toEqual([{ package: '@scope/plugin@^2', options: { mode: 'safe' } }]);
37
+ expect(config.plugin).toEqual([['legacy@1', { flag: true }]]);
38
+ expect(filtered.startsWith('\uFEFF')).toBe(true);
39
+ expect(filtered).toContain('// Keep provider configuration.\r\n "provider": { "example": { "options": { "baseURL": "http://localhost:3000" } } },');
40
+ expect(filtered).toContain('// Registry options stay intact.');
41
+ expect(filterSyncedPluginConfig(filtered)).toBe(filtered);
42
+ });
43
+
44
+ it.each(['{}\n', '// Empty configuration.\n', '', '{ "plugins": [], "plugin": [] }'])('leaves unchanged config byte-identical: %j', (content) => {
45
+ expect(filterSyncedPluginConfig(content)).toBe(content);
46
+ });
47
+
48
+ it('retains empty plugin arrays when every declaration is local', () => {
49
+ expect(JSON.parse(filterSyncedPluginConfig('{"plugins":["/local"],"plugin":[["file:../local",{}]]}')))
50
+ .toEqual({ plugins: [], plugin: [] });
51
+ });
52
+
53
+ it('keeps strict JSON valid for every combination of leading, adjacent and trailing removals', () => {
54
+ for (let mask = 0; mask < 32; mask += 1) {
55
+ const plugins = Array.from({ length: 5 }, (_, index) => mask & (1 << index) ? `registry-${index}@latest` : `/local/${index}`);
56
+ const filtered = filterSyncedPluginConfig(JSON.stringify({ plugins, model: 'unchanged' }));
57
+ expect(JSON.parse(filtered)).toEqual({ plugins: plugins.filter((entry) => !entry.startsWith('/')), model: 'unchanged' });
58
+ }
59
+ });
60
+
61
+ it.each(['{broken', 'null', '[]', '{"plugins":"/local"}', '{"plugin":{}}', '{"plugins":[],"plugins":["/local"]}'])('fails closed for invalid or ambiguous configuration: %s', (content) => {
62
+ expect(() => filterSyncedPluginConfig(content)).toThrow('invalid OpenCode JSONC configuration');
63
+ });
64
+ });
@@ -1,5 +1,10 @@
1
1
  import { spawn } from 'node:child_process';
2
- import { OPENCODE_CONFIG_SYNC_TAR_EXCLUDES } from './constants.js';
2
+ import fs from 'node:fs/promises';
3
+ import os from 'node:os';
4
+ import path from 'node:path';
5
+ import { OPENCODE_CONFIG_SYNC_ALLOWLIST, OPENCODE_CONFIG_SYNC_TAR_EXCLUDES } from './constants.js';
6
+ import { extractTarGzBuffer } from './local-backup.js';
7
+ import { filterSyncedPluginConfig } from './plugins.js';
3
8
 
4
9
  /**
5
10
  * Collect stdout from a local `tar …` into a Buffer.
@@ -34,3 +39,58 @@ export const collectLocalTarBuffer = (tarArgs, spawnOptions = {}) => new Promise
34
39
  resolve(Buffer.concat(chunks));
35
40
  });
36
41
  });
42
+
43
+ /** Filter only a private archive copy; source and destination files stay untouched on failure. */
44
+ export const filterConfigSyncArchive = async (buffer) => {
45
+ if (!buffer.length) return buffer;
46
+ const staging = await fs.mkdtemp(path.join(os.tmpdir(), 'yuri-config-sync-'));
47
+ try {
48
+ await extractTarGzBuffer(buffer, staging);
49
+ let changed = false;
50
+ for (const name of OPENCODE_CONFIG_SYNC_ALLOWLIST.fileGroups.flat()) {
51
+ const file = path.join(staging, name);
52
+ let content;
53
+ try {
54
+ if (!(await fs.lstat(file)).isFile()) throw new Error('Cannot sync plugins: configuration must be a regular file');
55
+ content = await fs.readFile(file, 'utf8');
56
+ } catch (error) {
57
+ if (error.code === 'ENOENT') continue;
58
+ throw error;
59
+ }
60
+ const filtered = filterSyncedPluginConfig(content);
61
+ if (filtered === content) continue;
62
+ await fs.writeFile(file, filtered);
63
+ changed = true;
64
+ }
65
+ if (!changed) return buffer;
66
+ const entries = await fs.readdir(staging);
67
+ return await collectLocalTarBuffer(['-czf', '-', '-C', staging, ...entries], {
68
+ windowsHide: process.platform === 'win32',
69
+ });
70
+ } finally {
71
+ await fs.rm(staging, { recursive: true, force: true });
72
+ }
73
+ };
74
+
75
+ /** SSH collector for the engine's `-C root ...entries` contract; only config files are staged. */
76
+ export const collectSshConfigTarBuffer = async (tarArgs, options = {}) => {
77
+ const rootIndex = tarArgs.indexOf('-C') + 1;
78
+ const root = tarArgs[rootIndex];
79
+ const entries = tarArgs.slice(rootIndex + 1);
80
+ const configs = entries.filter((entry) => OPENCODE_CONFIG_SYNC_ALLOWLIST.fileGroups.flat().includes(entry));
81
+ if (!configs.length) return collectLocalTarBuffer(tarArgs, options);
82
+ const staging = await fs.mkdtemp(path.join(os.tmpdir(), 'yuri-config-sync-'));
83
+ try {
84
+ for (const name of configs) {
85
+ const content = await fs.readFile(path.join(root, name), 'utf8');
86
+ await fs.writeFile(path.join(staging, name), filterSyncedPluginConfig(content), { mode: 0o600 });
87
+ }
88
+ const remaining = entries.filter((entry) => !configs.includes(entry));
89
+ return await collectLocalTarBuffer([
90
+ ...tarArgs.slice(0, rootIndex - 1), '-C', staging, ...configs,
91
+ ...(remaining.length ? ['-C', root, ...remaining] : []),
92
+ ], options);
93
+ } finally {
94
+ await fs.rm(staging, { recursive: true, force: true });
95
+ }
96
+ };
@@ -1,5 +1,14 @@
1
1
  # Global conversation content search
2
2
 
3
+ `POST /api/yuri/content-search/resume` authenticates Host UI/client access without
4
+ URL/preview tokens, rejects cross-origin cookie requests, and returns 202 with the
5
+ current index status. It invokes the existing `sync({ resume: true })` in the
6
+ background; concurrent retries share its flight. Explicit recovery reports
7
+ `indexing` even for an already-initialized index. Successful durable session
8
+ checkpoints and existing search hits are retained; unchanged successful sessions
9
+ are skipped and failed/dirty sessions are retried. Failure remains `partial` or
10
+ `error`, never an authoritative empty index. There is no destructive rebuild.
11
+
3
12
  The Host owns `content-search.sqlite` alongside the session index. This index is
4
13
  independent of browser transcript caches and includes all projects exposed by the
5
14
  active OpenCode runtime. `session.list` is called without a project/directory
@@ -1,6 +1,23 @@
1
1
  import { hasPreviewProxyCredential } from '../opencode/core-routes.js';
2
2
 
3
- export function registerContentSearchRoutes(app, { contentSearch } = {}) {
3
+ export function registerContentSearchRoutes(app, { contentSearch, uiAuthController } = {}) {
4
+ app.post('/api/yuri/content-search/resume', async (req, res) => {
5
+ res.setHeader('Cache-Control', 'no-store');
6
+ if (hasPreviewProxyCredential(req)) return res.status(403).json({ error: 'Forbidden' });
7
+ try {
8
+ const bearer = /^Bearer\s+\S+$/i.test(req.headers.authorization ?? '');
9
+ const authRequest = bearer ? Object.assign(Object.create(req), { headers: { ...req.headers, cookie: undefined } }) : req;
10
+ const context = await uiAuthController?.resolveAuthContext(authRequest, res, { allowClientAuth: true, allowUrlToken: false });
11
+ if (!context || context.type === 'client' && !context.clientId) return res.status(401).json({ error: 'authentication_required' });
12
+ const origin = req.headers.origin;
13
+ if (context.type !== 'client' && (req.headers['sec-fetch-site'] === 'cross-site' || origin && origin !== `${req.protocol}://${req.get('host')}`)) {
14
+ return res.status(403).json({ error: 'origin_forbidden' });
15
+ }
16
+ if (!contentSearch) return res.status(503).json({ error: 'Global content index unavailable' });
17
+ void contentSearch.runtime.sync({ resume: true }).catch(() => {});
18
+ return res.status(202).json({ index: contentSearch.runtime.status() });
19
+ } catch { return res.status(500).json({ error: 'index_resume_failed' }); }
20
+ });
4
21
  app.get('/api/yuri/content-search', (req, res) => {
5
22
  if (hasPreviewProxyCredential(req)) return res.status(403).json({ error: 'Forbidden' });
6
23
  if (!contentSearch) return res.status(503).json({ error: 'Global content index unavailable' });
@@ -40,3 +40,24 @@ test('global route returns coverage and preserves hit directories without a sele
40
40
  search.mockImplementation(() => { throw new Error('database unavailable'); });
41
41
  expect((await request(app).get('/api/yuri/content-search').query({ q: 'needle' })).status).toBe(500);
42
42
  });
43
+
44
+ test('resume requires real auth and same-origin browser intent, rejects preview credentials, and starts background work', async () => {
45
+ const app = express(); let context = null;
46
+ const resolveAuthContext = vi.fn(async () => context);
47
+ const sync = vi.fn(() => new Promise(() => {}));
48
+ registerContentSearchRoutes(app, { uiAuthController: { resolveAuthContext }, contentSearch: {
49
+ runtime: { sync, status: () => ({ phase: 'indexing', completed: 79, total: 357 }) },
50
+ } });
51
+ const route = '/api/yuri/content-search/resume';
52
+ expect((await request(app).post(route)).status).toBe(401);
53
+ context = { type: 'session' };
54
+ expect((await request(app).post(route).set('Origin', 'https://other.example')).status).toBe(403);
55
+ expect((await request(app).post(`${route}?yuri_preview_token=preview`)).status).toBe(403);
56
+ expect(sync).not.toHaveBeenCalled();
57
+ const accepted = await request(app).post(route);
58
+ expect(accepted.status).toBe(202);
59
+ expect(accepted.headers['cache-control']).toBe('no-store');
60
+ expect(accepted.body.index).toMatchObject({ phase: 'indexing', completed: 79 });
61
+ expect(sync).toHaveBeenCalledExactlyOnceWith({ resume: true });
62
+ expect(resolveAuthContext.mock.calls[0][2]).toEqual({ allowClientAuth: true, allowUrlToken: false });
63
+ });
@@ -21,16 +21,20 @@ export function createContentSearchRuntime({ service, getRuntimeKey, getEventRun
21
21
  return { ...(state.runtime === runtime ? state : { runtime, phase: 'pending', since: now() - RETENTION, total: 0, completed: 0, failed: 0, updatedAt: null }),
22
22
  ...coverage, initializationRequired: coverage.indexCompletedAt === null, ...service.stats(runtime) };
23
23
  };
24
- const sync = ({ incremental = false } = {}) => {
24
+ const sync = ({ incremental = false, resume = false } = {}) => {
25
25
  if (stopped) return Promise.resolve();
26
- if (flight) return flight;
26
+ if (flight) {
27
+ if (resume) state.phase = 'indexing';
28
+ return flight;
29
+ }
27
30
  const runtime = getRuntimeKey();
28
31
  controller = new AbortController();
29
32
  const signal = controller.signal;
30
33
  const current = () => !stopped && runtime === getRuntimeKey() && !signal.aborted;
31
34
  if (state.runtime !== runtime) { dirty.clear(); deleted.clear(); }
32
35
  const previous = state.runtime === runtime ? state.updatedAt : null;
33
- state = { runtime, phase: previous ? 'ready' : 'indexing', since: now() - RETENTION, total: state.total, completed: 0, failed: 0, updatedAt: previous };
36
+ const showProgress = resume || !previous || ['partial', 'error', 'pending'].includes(state.phase);
37
+ state = { runtime, phase: showProgress ? 'indexing' : 'ready', since: now() - RETENTION, total: state.total, completed: 0, failed: 0, updatedAt: previous };
34
38
  flight = (async () => {
35
39
  if (service.coverage(runtime).indexCompletedAt === null) service.beginInitialization(runtime, now());
36
40
  const revisions = new Map(service.pending(runtime).map(({ id, revision }) => [id, revision]));
@@ -171,6 +171,32 @@ test('persists initialization times only after all thirty-day history is covered
171
171
  await runtime.stop(); service.close();
172
172
  });
173
173
 
174
+ test('explicit resume reports active indexing, merges duplicate flights and skips successful checkpoints', async () => {
175
+ const service = createContentSearchService({ dbPath: ':memory:' });
176
+ let release; let block = false; let fail = true; const reads = [];
177
+ const runtime = createContentSearchRuntime({ service, getRuntimeKey: () => 'host', now: () => 1000,
178
+ listSessions: async () => ({ data: ['a', 'b'].map((id) => ({ id, time: { updated: 999 } })) }),
179
+ listMessages: async ({ sessionID }) => {
180
+ reads.push(sessionID);
181
+ if (block) await new Promise((resolve) => { release = resolve; });
182
+ if (sessionID === 'b' && fail) throw new Error('offline');
183
+ return { data: [] };
184
+ },
185
+ });
186
+ try {
187
+ await runtime.sync();
188
+ expect(runtime.status().phase).toBe('partial');
189
+ block = true; fail = false;
190
+ const first = runtime.sync({ resume: true });
191
+ expect(runtime.sync({ resume: true })).toBe(first);
192
+ expect(runtime.status().phase).toBe('indexing');
193
+ for (let attempt = 0; attempt < 10 && !release; attempt++) await Promise.resolve();
194
+ expect(reads).toEqual(['a', 'b', 'b']);
195
+ release(); await first;
196
+ expect(runtime.status()).toMatchObject({ phase: 'ready', completed: 2, failed: 0 });
197
+ } finally { await runtime.stop(); service.close(); }
198
+ });
199
+
174
200
  test('completed initialization survives incremental refresh, failure, restart and dirty events', async () => {
175
201
  const service = createContentSearchService({ dbPath: ':memory:' });
176
202
  let clock = 1000;
@@ -7,12 +7,26 @@ short discovery pointer enters `session.instructions.entry` under
7
7
  no global OpenCode config, installed user skills, project files or old sessions
8
8
  are modified.
9
9
 
10
- References are organized by capability: window APIs, appearance, UI surfaces, global pages,
10
+ References are organized by capability: window APIs, appearance, UI surfaces, plugin styles, global pages, work-status widgets, icons,
11
11
  file parsing/previews, preview actions/exports, and package workflow. Host contracts
12
12
  and verification criteria are separate from illustrative templates and case
13
13
  studies. Runmark and Eficy remain integration references; their service protocols,
14
14
  renderers and compatibility choices are not requirements for unrelated plugins.
15
15
 
16
+ `references/plugin-styles.md` inventories existing host CSS variables for plugin-owned
17
+ Solid/DOM content, including colors, typography, geometry, controls and optional
18
+ theme config. The workflow routes every plugin view through this reference. Visual
19
+ consistency is authoring guidance through scoped CSS and SVG, not a React/Solid
20
+ component bridge or a host-provided UI component library. The host's `ctx.ui` remains
21
+ unsupported; plugin markup, layout and behavior remain plugin-owned.
22
+
23
+ `references/icons.md` distinguishes the upstream generated `IconName` union from
24
+ Yuri's actual titlebar/sidebar renderer, lists their verified shared names and
25
+ aliases, and separates entry icons from Settings artwork, file icons and branding.
26
+ It also documents same-document SVG symbol references, common sprite keys and the
27
+ current DOM/version boundary without exposing the React Icon component. Update its
28
+ shared-name list when the renderer or supported SDK catalog changes.
29
+
16
30
  `references/ui-surfaces.md` is the shipped structural/style map for plugin authors
17
31
  without a source checkout. It covers shell, sidebar, header, transcript, composer,
18
32
  preview, Settings, overlays, tokens/cascade and native transparency boundaries.
@@ -24,6 +38,12 @@ The authoring workflow defaults to directly written `gui-experimental.cjs` with
24
38
  host-provided modules and inline assets. Local edits use the existing revision
25
39
  watcher; compilation is only an optional path for typed/JSX or bundled sources.
26
40
 
41
+ `references/work-status.md` documents `yuri.work-status`, its displayed-session
42
+ context, registration order, mount cancellation, desktop placements and Git
43
+ snapshot limitations. Its complete CJS example uses the existing Solid runtime,
44
+ CSS variables and SVG symbols; `skill-examples.test.ts` executes it against the
45
+ real host. The reference is included in the immutable staged resource inventory.
46
+
27
47
  ## Admission ownership
28
48
 
29
49
  - Shared-service sessions: the existing scheduled-task admission route installs
@@ -2,7 +2,7 @@ import { readFile, mkdir, writeFile, rename, rm } from 'node:fs/promises';
2
2
  import { createHash, randomUUID } from 'node:crypto';
3
3
  import path from 'node:path';
4
4
 
5
- const files = ['SKILL.md', 'references/appearance.md', 'references/ui-surfaces.md', 'references/gui-api.md', 'references/workflow.md', 'references/global-pages.md', 'references/file-previews.md', 'references/preview-exports.md'];
5
+ const files = ['SKILL.md', 'references/appearance.md', 'references/ui-surfaces.md', 'references/plugin-styles.md', 'references/gui-api.md', 'references/workflow.md', 'references/global-pages.md', 'references/work-status.md', 'references/icons.md', 'references/file-previews.md', 'references/preview-exports.md'];
6
6
 
7
7
  /** Stage immutable, shipped instructions; never edit the user's global skills/config. */
8
8
  export function createCustomizationSkillInstaller({ yuriDataDir }) {
@@ -26,7 +26,7 @@ export function createCustomizationSkillInstaller({ yuriDataDir }) {
26
26
  return async (client, sessionID) => {
27
27
  const file = await prepare();
28
28
  await client.session.instructions.entry.put({ sessionID, key: 'yuri.customization',
29
- value: `Yuri customization: for appearance (themes, CSS/layout, Logo, macOS Dock), global pages/tabs, custom file parsing/previews, preview exports, or GUI panels/commands/settings, read ${JSON.stringify(file)} before choosing a plugin API. Its UI structure/style reference maps built-in blocks, selectors, tokens and transparency layers; capability references cover contracts and runtime limits. Use its workflow for building, installation and rollback. Install or apply changes only when requested.`,
29
+ value: `Yuri customization: for appearance (themes, CSS/layout, Logo, macOS Dock), work-status widgets, global pages/tabs, custom file parsing/previews, preview exports, or GUI panels/commands/settings, read ${JSON.stringify(file)} before choosing a plugin API. Its style/icon references guide plugin-owned content; UI structure maps built-in blocks, selectors and transparency layers; capability references cover contracts and runtime limits. Use its workflow for building, installation and rollback. Install or apply changes only when requested.`,
30
30
  });
31
31
  };
32
32
  }
@@ -23,7 +23,9 @@ describe('built-in customization instructions', () => {
23
23
  expect(entry.value.length).toBeLessThan(1500);
24
24
  const file = JSON.parse(entry.value.match(/read (".*?") before/)[1]);
25
25
  expect(await fs.readFile(file, 'utf8')).toContain('name: yuri-customization');
26
- for (const name of ['appearance', 'ui-surfaces', 'gui-api', 'workflow', 'global-pages', 'file-previews', 'preview-exports']) expect((await fs.readFile(path.join(path.dirname(file), 'references', `${name}.md`), 'utf8')).length).toBeGreaterThan(500);
26
+ for (const name of ['appearance', 'ui-surfaces', 'plugin-styles', 'gui-api', 'workflow', 'global-pages', 'work-status', 'icons', 'file-previews', 'preview-exports']) expect((await fs.readFile(path.join(path.dirname(file), 'references', `${name}.md`), 'utf8')).length).toBeGreaterThan(500);
27
+ expect(await fs.readFile(file, 'utf8')).toContain('(references/icons.md)');
28
+ expect(await fs.readFile(path.join(path.dirname(file), 'references', 'global-pages.md'), 'utf8')).toContain('(icons.md)');
27
29
  expect(await fs.readFile(path.join(path.dirname(file), 'references', 'appearance.md'), 'utf8')).toContain('yuri.branding');
28
30
  expect(put.mock.calls[1][0].value).toBe(entry.value);
29
31
  });
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: yuri-customization
3
- description: Customize Yuri through GUI plugins for appearance, global pages, custom file previews, export actions, panels, commands, and settings.
3
+ description: Customize Yuri through GUI plugins for appearance, work-status widgets, global pages, custom file previews, export actions, panels, commands, and settings.
4
4
  ---
5
5
 
6
6
  # Yuri customization
@@ -11,14 +11,18 @@ Use a standard OpenCode GUI plugin to change the running Yuri UI without modifyi
11
11
 
12
12
  1. Identify the requested change and target client: Web, Electron, VS Code, hosted mobile, or Capacitor. Separate visual changes from backend behavior. Inspect the user's existing plugin/config before changing it. An explanation request does not authorize installation.
13
13
  2. Choose the extension point by the requested capability and read its reference:
14
+ - Every plugin-owned view: [CSS variables and styling](references/plugin-styles.md); use the host's existing tokens in plugin-owned CSS to follow Yuri's appearance.
14
15
  - Existing UI blocks, backgrounds/transparency, selectors, spacing and built-in style tokens: [UI structure and styles](references/ui-surfaces.md). Start here for CSS changes before inspecting application bundles.
15
16
  - Themes, CSS, logos, Dock icons: [appearance](references/appearance.md).
16
17
  - Global main-content tabs and titlebar entries: [global pages](references/global-pages.md).
18
+ - Widgets under Changes in the conversation's status column: [work-status widgets](references/work-status.md).
19
+ - Entry/tab icons or icons inside plugin content: [icons](references/icons.md), including supported names, same-document SVG usage and artwork boundaries.
17
20
  - Custom file suffixes, parsers, inline/mobile previews and file icons: [file previews](references/file-previews.md).
18
21
  - Preview toolbar placement, PDF/PNG/HTML export and iframe snapshot boundaries: [preview actions and exports](references/preview-exports.md).
19
22
  - Panels, commands, settings, files, RPC, lifecycle, runtime support: [GUI API](references/gui-api.md).
20
23
  - Every implementation: [direct-CJS package, installation, updates and rollback](references/workflow.md); compilation is an optional branch.
21
24
  3. Default to `package.json` plus a directly authored `gui-experimental.cjs`, using host-provided modules and inline CSS/assets. This needs no dependency install or compilation. Implement only the requested capabilities; use the optional build branch when TS/TSX or dependency bundling is actually needed.
25
+ Yuri's React shell owns the container; the plugin owns its Solid/DOM content. Share visual style through CSS variables and icon references, not host React components or a host-provided Solid component library.
22
26
  4. Syntax-check the exported CJS file and install within the requested scope, preserving unrelated global OpenCode configuration. A local CJS edit reloads through the existing watcher; project-only configuration does not provide window GUI inventory.
23
27
  5. Verify each requested capability in the target client, including its failure and cleanup behavior; use the matching reference's verification criteria. Finish with the plugin directory, changed settings, verified behavior, known limits, and how to undo it.
24
28
 
@@ -74,7 +74,7 @@ Those message names, header and navigation rules form Runmark's service protocol
74
74
 
75
75
  ## Entry icon versus content branding
76
76
 
77
- The top-level plugin `package.json` `icon` supplies Yuri's plugin-entry artwork when available (validated image/data resource; monochrome SVG can follow `currentColor` through the host mask). `TitlebarItem.icon` is a name from the official icon catalog. Neither replaces the application's Logo; use `yuri.branding` for that. Keep existing official product artwork instead of inventing a substitute.
77
+ Choose `TitlebarItem.icon` from the supported catalog names in [plugin entry icons](icons.md), which covers upstream `IconName`, Yuri's compatible names/aliases and fallback behavior. Set it on the entry itself; `yuri.page.icon` does not configure that entry. Top-level `package.json.icon` supplies artwork in Settings plugin details, not the global navigation entry. Application Logo/Dock branding uses `yuri.branding`; see [appearance](appearance.md).
78
78
 
79
79
  ## Verification
80
80
 
@@ -5,7 +5,7 @@ The supported contract is OpenCode GUI SDK **2.2.0**. Consult current official d
5
5
  ## Window APIs
6
6
 
7
7
  - `Command`: command palette and plugin management execution; hidden commands can be called by `ctx.commands.run`. No GUI shortcut registration or slash autocomplete yet.
8
- - `TitlebarItem`: global action/status, independent of a session; reactive label/title/icon/busy/pressed.
8
+ - `TitlebarItem`: global action/status, independent of a session; reactive label/title/icon/busy/pressed. Supported icon names and upstream/Yuri differences: [icons](icons.md).
9
9
  - `Panel`: Solid `list/render`, reactive session/tab getters; file panels mount in existing file previews. An independent panel uses a dialog/mobile sheet, not upstream's full draggable workspace layout.
10
10
  - `LinkHandler`: match, exists and open file/custom links. Use `ctx.links.open({ href, base, session })` for navigation. Preserve workspace-relative identity; never resolve against a different session's directory.
11
11
  - `SettingsPage`: independent plugin settings pages; host `page/section` injection is unsupported.
@@ -20,11 +20,14 @@ The supported contract is OpenCode GUI SDK **2.2.0**. Consult current official d
20
20
 
21
21
  Unsupported registries include upstream `Server`, `ComposerPill`, `Slot`, `FileViewer`, native menu/embeds. Unsupported APIs reject rather than succeeding silently.
22
22
 
23
+ Plugin renderers own their Solid/DOM content. Yuri does not implement upstream `ctx.ui` or expose its React components to plugins; follow [CSS variables and styling](plugin-styles.md) and [icons](icons.md) for visual consistency.
24
+
23
25
  ## Yuri supplemental registries and contracts
24
26
 
25
27
  - `yuri.theme`, `yuri.branding`: see [appearance](appearance.md).
26
28
  - `yuri.file-icon`: `{ id, extensions: string[], svg, lightSvg? }`; static SVG resources for file extensions, not app/Dock icons.
27
29
  - `yuri.page` / `yuri.pages`: global main-content Solid pages, desktop layouts/VS Code only. Exact types, entry points and optional web-app embedding: [global pages](global-pages.md).
30
+ - `yuri.work-status`: inline/popup widgets below Changes in the desktop conversation status column; read-only displayed-session/project/Git context and mount-scoped cancellation. See [work-status widgets](work-status.md).
28
31
  - Custom suffix parsing, normalized file identities, `PanelTab.file` and mobile sheets: [file previews](file-previews.md).
29
32
  - `yuri.exportPDF`, `yuri.exportLongImage`, `yuri.previewActions`: separate host contracts for client-owned export/preview actions. Exact types, registration lifetime, capture protocol and runtime matrix: [preview actions and exports](preview-exports.md).
30
33
 
@@ -0,0 +1,134 @@
1
+ # Plugin icons
2
+
3
+ Use this reference when choosing an entry icon or rendering icons inside plugin-owned Solid/DOM content. Icon names, package artwork, file icons and application branding are separate contracts. Use [plugin styles](plugin-styles.md) for the surrounding text and colors.
4
+
5
+ ## Upstream contract
6
+
7
+ OpenCode's `TitlebarItem.icon` is an optional `IconName`, imported as a **type** from `@opencode/plugin/gui`. Its value is a catalog name such as `globe`, not an SVG string, image URL, CSS class or component. The type is erased at runtime; it is not an exported array or an icon renderer.
8
+
9
+ Upstream generates the SDK union from the application's icon catalog:
10
+
11
+ - [`packages/plugin/src/gui/icon-name.ts`](https://github.com/anomalyco/opencode/blob/dev/packages/plugin/src/gui/icon-name.ts): accepted SDK names; editor completion comes from this union.
12
+ - [`packages/ui/src/icons/catalog.ts`](https://github.com/anomalyco/opencode/blob/dev/packages/ui/src/icons/catalog.ts): upstream artwork and catalog.
13
+ - [`packages/plugin/script/icon-name.ts`](https://github.com/anomalyco/opencode/blob/dev/packages/plugin/script/icon-name.ts): generator; the SDK carries the names without requiring `@opencode/ui` in plugin bundles.
14
+ - [Official GUI reference](https://opencode.ai/v2/docs/build/plugins/gui#titlebar-items): contribution syntax.
15
+
16
+ Use the installed SDK's declaration for its exact version. The links above follow upstream development; a name accepted by a newer SDK is not proof that Yuri renders it.
17
+
18
+ ## Names supported by both hosts
19
+
20
+ For a plugin targeting OpenCode and Yuri, choose from this verified intersection of the upstream SDK catalog and Yuri's current **TitlebarItem** renderer (including aliases):
21
+
22
+ ```text
23
+ archive arrow-left arrow-right arrow-up brain check circle-check circle-x
24
+ close code download edit eye flask folder github globe graduation-cap
25
+ keyboard layout-left layout-right lock refresh server shield stop task
26
+ terminal window-analytics
27
+ ```
28
+
29
+ Common choices:
30
+
31
+ | Purpose | `icon` |
32
+ | --- | --- |
33
+ | Web/service page | `globe` |
34
+ | Dashboard/analytics | `window-analytics` |
35
+ | Server/connection | `server` |
36
+ | Files/workspace | `folder` |
37
+ | Code/development | `code` or `terminal` |
38
+ | Tasks | `task` |
39
+ | Experiments | `flask` |
40
+ | Success/failure | `circle-check` / `circle-x` |
41
+
42
+ For the direct-CJS workflow, put the name in the contribution; no icon import or dependency is needed:
43
+
44
+ ```js
45
+ const { Plugin, TitlebarItem } = require('@opencode/plugin/gui')
46
+
47
+ module.exports = Plugin.define({
48
+ setup(ctx) {
49
+ ctx.add(TitlebarItem, {
50
+ id: 'website', label: 'Studio', icon: 'globe',
51
+ run: () => ctx.system.openExternal('https://example.com'),
52
+ })
53
+ },
54
+ })
55
+ ```
56
+
57
+ For typed reactive contributions, annotate the return type as in the [global-page example](global-pages.md); otherwise TypeScript can widen `icon` to `string`.
58
+
59
+ ## Yuri resolution and fallback
60
+
61
+ Yuri resolves `TitlebarItem.icon` through these aliases first, then an exact key in its own sprite:
62
+
63
+ | SDK name | Yuri sprite key |
64
+ | --- | --- |
65
+ | `globe` | `global` |
66
+ | `server` | `server` |
67
+ | `circle-check` | `checkbox-circle` |
68
+ | `circle-x` | `close-circle` |
69
+ | `window-analytics` | `bar-chart-box` |
70
+
71
+ Yuri's sprite contains additional names, but those are not automatically valid upstream `IconName` values. Use the shared names above for portable SDK contributions rather than casting a Yuri-only name into the SDK type. For an unlisted name, check the installed SDK and target Yuri version before relying on it.
72
+
73
+ - Missing or unknown name: Yuri keeps the entry label. Sidebar placement reserves an empty icon slot; titlebar placement renders text instead of an icon. It does not substitute package artwork or the upstream default download arrow.
74
+ - `busy: true`: a loading spinner replaces the icon and disables an actionable entry.
75
+ - Valid icon: titlebar placement shows the icon with a hover label; sidebar placement shows icon and text. Host styles control size and color.
76
+ - Registering `yuri.page.icon` alone does not create or configure its navigation entry. Register `TitlebarItem` and set its `icon` separately, as in [global pages](global-pages.md).
77
+
78
+ Source owners, matched to the target Yuri tag when available:
79
+
80
+ - [`GuiPluginTitlebarItems.tsx`](https://github.com/yee94/yuri/blob/main/packages/ui/src/components/gui-plugins/GuiPluginTitlebarItems.tsx): aliases, placement and fallback.
81
+ - [`sprite.ts`](https://github.com/yee94/yuri/blob/main/packages/ui/src/components/icon/sprite.ts): complete Yuri runtime catalog (the keys of `iconSpriteData`), not the upstream SDK union.
82
+
83
+ ## Icons inside plugin content
84
+
85
+ For same-document content, Yuri's React `Icon` mounts a hidden SVG sprite with id `yuri-icon-sprite-v2`; its symbols use `yuri-<sprite-key>`. A plugin can reference an existing symbol with ordinary SVG, without importing the React component or a Solid wrapper:
86
+
87
+ ```html
88
+ <svg viewBox="0 0 24 24" width="16" height="16" fill="none"
89
+ stroke="currentColor" stroke-width="1.5" stroke-linecap="round"
90
+ stroke-linejoin="round" aria-hidden="true" focusable="false"
91
+ style="flex-shrink: 0; --yuri-icon-stroke: 1.5">
92
+ <use href="#yuri-folder"></use>
93
+ </svg>
94
+ ```
95
+
96
+ The same markup works in Solid; direct CJS can create `svg` and `use` with `document.createElementNS('http://www.w3.org/2000/svg', ...)`. Inherit `currentColor` from the surrounding text. Common host sizes are 14px for dense status rows and 16px for controls; the normal stroke is 1.5, with `--yuri-icon-stroke: 2` for stronger small icons. Put accessible text on the containing button when the SVG is decorative.
97
+
98
+ Common **sprite keys**, verified against Yuri's current catalog:
99
+
100
+ | Purpose | Sprite keys |
101
+ | --- | --- |
102
+ | Project / branch / worktree / changes | `folder`, `git-branch`, `node-tree`, `changes` |
103
+ | Expand / collapse | `arrow-right-s`, `arrow-down-s` |
104
+ | Success / failure / information | `check`, `checkbox-circle`, `close-circle`, `alert`, `information` |
105
+ | Actions | `file-copy`, `download`, `refresh`, `settings-2`, `external-link`, `close` |
106
+ | Loading | `loader-4` (the symbol itself is static; animation belongs to the plugin) |
107
+ | Web / analytics | `global`, `bar-chart-box` |
108
+
109
+ `<use>` needs the exact sprite key: the entry aliases above do not apply (`global`, not `globe`; `checkbox-circle`, not `circle-check`). The complete source catalog is the linked `sprite.ts`. To inspect an installed host's available names once:
110
+
111
+ ```js
112
+ Array.from(
113
+ document.querySelectorAll('#yuri-icon-sprite-v2 symbol[id^="yuri-"]'),
114
+ symbol => symbol.id.slice('yuri-'.length),
115
+ )
116
+ ```
117
+
118
+ These symbol IDs are current DOM implementation hooks, not an SDK icon-renderer API. The sprite is inserted when a host icon renders; check that the chosen symbol exists in the target document. A missing symbol renders no artwork: retain a text label or use plugin-owned inline SVG. Iframes cannot reference the parent document's symbols. The host owns sprite insertion and replacement; plugins only reference it. Standalone artwork should use a 24×24 viewBox, `currentColor` and matching stroke conventions where appropriate.
119
+
120
+ ## Artwork boundaries
121
+
122
+ | Surface | Contract |
123
+ | --- | --- |
124
+ | Global plugin page/tab navigation entry | `TitlebarItem.icon`: supported catalog name |
125
+ | Plugin artwork in Settings plugin details | Top-level `package.json.icon`: validated image/data resource; not used by the global entry renderer |
126
+ | Custom file extension icon | `yuri.file-icon`: SVG resource; see [file previews](file-previews.md) |
127
+ | Application Logo / running macOS Dock icon | `yuri.branding`; see [appearance](appearance.md) |
128
+ | Artwork inside plugin-owned page content | Render it in the page's own Solid/DOM content |
129
+
130
+ The current entry contract has no custom-SVG/image field. Supplying an image URL as `TitlebarItem.icon`, or setting `package.json.icon`, does not add one.
131
+
132
+ ## Verification
133
+
134
+ Check the actual entry in each target placement: selected artwork, visible/hover label, `busy` spinner, missing-name fallback, and withdrawal when the plugin is disabled. SDK typechecking alone does not prove Yuri runtime support.