@yuriai/web 0.2.29-beta.7 → 0.2.29-beta.9

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 (118) hide show
  1. package/dist/assets/{AgentAvatar-BNk56-Uq.js → AgentAvatar-BtFNGIgH.js} +1 -1
  2. package/dist/assets/AssistantContactStatus-CxBF6Ay6.js +3 -0
  3. package/dist/assets/{AssistantUnreadBadge-doY0Hft6.js → AssistantUnreadBadge--5NJVTuh.js} +1 -1
  4. package/dist/assets/{AssistantView-B4mEblYi.js → AssistantView-BmpLCQuw.js} +1 -1
  5. package/dist/assets/{DiagramView-Diyf4LSt.js → DiagramView-CRam7PmL.js} +1 -1
  6. package/dist/assets/{FadeInOnReveal-l6XCssmS.js → FadeInOnReveal-CuOJu25b.js} +1 -1
  7. package/dist/assets/{GuiPluginSurface-rMZtD1SR.js → GuiPluginSurface-Cf4hIlkP.js} +1 -1
  8. package/dist/assets/{GuiPluginWindow-DXfru2tW.js → GuiPluginWindow-CIVNyw4s.js} +1 -1
  9. package/dist/assets/{Icon-p_czvEI7.js → Icon-BQczEnxm.js} +1 -1
  10. package/dist/assets/{ImageLoadingPlaceholder-Dg_CU5VT.js → ImageLoadingPlaceholder-KksxJaKp.js} +1 -1
  11. package/dist/assets/{LoadingImage-CcML4X1d.js → LoadingImage-Ch5MyA20.js} +1 -1
  12. package/dist/assets/MarkdownRenderer-D3744fNd.js +2 -0
  13. package/dist/assets/{MarkdownRendererImpl-CzpxCCAo.js → MarkdownRendererImpl-DShGc2YZ.js} +1 -1
  14. package/dist/assets/{MarkstreamRendererImpl-BRsSpYVn.js → MarkstreamRendererImpl-DYmFf07T.js} +1 -1
  15. package/dist/assets/{MobileDetailNavigation-D_fj0utf.js → MobileDetailNavigation-CjoghpoB.js} +1 -1
  16. package/dist/assets/{MobileResizableSheet-B2GU_fkU.js → MobileResizableSheet-Bk3z4g6T.js} +1 -1
  17. package/dist/assets/{MobileShareBridge-Cr4nh-gT.js → MobileShareBridge-Bii25Pjf.js} +1 -1
  18. package/dist/assets/MobileTabPageHeader-C6AI58D-.js +2 -0
  19. package/dist/assets/{MultiRunWindow-D22yagDA.js → MultiRunWindow-xrwgbnRZ.js} +1 -1
  20. package/dist/assets/{OnboardingScreen-BYD95kJF.js → OnboardingScreen-CgQGvlEs.js} +1 -1
  21. package/dist/assets/{OverlayScrollbar-CvwSam3X.js → OverlayScrollbar-C9Ac564a.js} +1 -1
  22. package/dist/assets/SettingsView-BHBG7CFA.js +29 -0
  23. package/dist/assets/{SettingsWindow-B_pQHcHp.js → SettingsWindow-D8hn7Jjd.js} +1 -1
  24. package/dist/assets/SetupTourDialog-B2crxm_w.js +1 -0
  25. package/dist/assets/SetupTourDialog-CUzqT2sw.css +1 -0
  26. package/dist/assets/{TerminalView-C8T2MbNS.js → TerminalView-5ki5iNXt.js} +1 -1
  27. package/dist/assets/{ToolOutputDialog-CwOZ2rK4.js → ToolOutputDialog-CMhix20T.js} +1 -1
  28. package/dist/assets/VoiceSettings-DawvV46L.js +2 -0
  29. package/dist/assets/{YuriLogo-Bw8_KAED.js → YuriLogo-CpccdHvS.js} +1 -1
  30. package/dist/assets/YuriWordmark-hZ6K7Smk.js +1 -0
  31. package/dist/assets/{appThemeRegistry-CAryUA-D.js → appThemeRegistry-D25YM694.js} +1 -1
  32. package/dist/assets/{button-DC4BhJtL.js → button-Cjciq1yh.js} +1 -1
  33. package/dist/assets/{capgoAdapter-n0GPI3Ea.js → capgoAdapter-Bas1D6ds.js} +1 -1
  34. package/dist/assets/{collapsible-D87ZOJIG.js → collapsible-BzCn4-sd.js} +1 -1
  35. package/dist/assets/{context-menu-CD5IEDb5.js → context-menu-BIjCIXOg.js} +1 -1
  36. package/dist/assets/{diagram-BzzPtmNA.js → diagram--zTR0vWJ.js} +1 -1
  37. package/dist/assets/{dialog-BCMKa538.js → dialog-rVkj8VgE.js} +1 -1
  38. package/dist/assets/dropdown-menu.styles-BDla58Rm.js +1 -0
  39. package/dist/assets/{es-C1m4Kl9P.js → es-B8dNq0Lv.js} +3 -3
  40. package/dist/assets/{fileMentionTouchSelection-PLpnmqHg.js → fileMentionTouchSelection-CmdNi_d0.js} +1 -1
  41. package/dist/assets/{fr-CnTFShIJ.js → fr-DbzWoYOD.js} +3 -3
  42. package/dist/assets/{gitApi-CP5napwr.js → gitApi-Cs08jIjA.js} +1 -1
  43. package/dist/assets/{input-BuAMQD1i.js → input-GVRUiwuQ.js} +1 -1
  44. package/dist/assets/insertionBoundaries-BoEG12_x.js +1 -0
  45. package/dist/assets/{ja-C975DGmU.js → ja-BGk5BIrz.js} +3 -3
  46. package/dist/assets/{ko-Donv-MLw.js → ko-Broo5A8H.js} +3 -3
  47. package/dist/assets/main-BGYY-hd1.js +2 -0
  48. package/dist/assets/{main-CSNJQF6u.js → main-D00Zz44O.js} +21 -21
  49. package/dist/assets/{markdownHeightCache-gGCb2TW0.js → markdownHeightCache-C7UOJdkN.js} +1 -1
  50. package/dist/assets/{mcpQueries-BbNEHTru.js → mcpQueries-4__hFxuf.js} +1 -1
  51. package/dist/assets/miniChat-DJrq4mIe.js +2 -0
  52. package/dist/assets/mobile-BOrcaJMH.js +2 -0
  53. package/dist/assets/{mobileBackNavigation-BFnxHmcJ.js → mobileBackNavigation-DfKlarxw.js} +1 -1
  54. package/dist/assets/multirun-D35HrOK1.js +3 -0
  55. package/dist/assets/{native-config-CxrxYHct.js → native-config-DF7bq4tk.js} +1 -1
  56. package/dist/assets/{pl-D22JxKm-.js → pl-not4wEra.js} +3 -3
  57. package/dist/assets/projectMeta-Bu5flvhx.js +1 -0
  58. package/dist/assets/{pt-BR-D6NkqDFy.js → pt-BR-3OzFQDGv.js} +3 -3
  59. package/dist/assets/pwa-CWEsl2Ow.js +2 -0
  60. package/dist/assets/{queue-abort-optimistic-Bix-IUrI.js → queue-abort-optimistic-DZc2cRj7.js} +1 -1
  61. package/dist/assets/{readiness-Bo2P-IXf.js → readiness-Dl790DNB.js} +1 -1
  62. package/dist/assets/renderElectronMiniChatApp-MI4k81uX.js +2 -0
  63. package/dist/assets/renderMobileApp-ClCiFay4.js +28 -0
  64. package/dist/assets/{runtimeConfig-DmZoakxE.js → runtimeConfig-BuChFCqQ.js} +1 -1
  65. package/dist/assets/runtimeEndpointReset-BHOxCpwZ.js +149 -0
  66. package/dist/assets/select-DeP9bukP.js +1 -0
  67. package/dist/assets/sessionLookup-K6ZLigY7.js +1 -0
  68. package/dist/assets/{sortable-tabs-strip-2alRozPo.js → sortable-tabs-strip-BloEQRck.js} +1 -1
  69. package/dist/assets/speechSettingsQueries-DusLRL2i.js +3 -0
  70. package/dist/assets/{store-XWRveCM0.js → store-CKIMMlXR.js} +4 -3
  71. package/dist/assets/{textarea-Cj7oz4TZ.js → textarea-B4mWtnN5.js} +1 -1
  72. package/dist/assets/{tooltip-BUDeDvMc.js → tooltip-BuZ86ipm.js} +1 -1
  73. package/dist/assets/tour-Db44qwfs.js +1 -0
  74. package/dist/assets/{types-D7m_3iXu.js → types-O8iYyCQi.js} +1 -1
  75. package/dist/assets/{uk-DEV7vjeo.js → uk-DyZ2SwUJ.js} +3 -3
  76. package/dist/assets/{useAppFontEffects-DupRRD7K.js → useAppFontEffects-BTwyFf_W.js} +31 -31
  77. package/dist/assets/useDesktopWindowControlsLayout-GQRvPTBq.js +1 -0
  78. package/dist/assets/{dropdown-menu.styles-DEOmf_B_.js → useDictation-CwX05CAo.js} +1 -1
  79. package/dist/assets/{useEffectiveDirectory-DB5tS-o5.js → useEffectiveDirectory-n0L_esHA.js} +1 -1
  80. package/dist/assets/{useMobileNavigationStore-BsWXpW7G.js → useMobileNavigationStore-CN9JDH7h.js} +7 -7
  81. package/dist/assets/usePluginsStore-D96HwGZy.js +1 -0
  82. package/dist/assets/{useWorkerHighlightedLines-B76dqB8T.js → useWorkerHighlightedLines-Bs1Z-yjv.js} +1 -1
  83. package/dist/assets/{zh-CN-6GRNLBLK.js → zh-CN-aNIWxYun.js} +3 -3
  84. package/dist/assets/{zh-TW-7oorZFq9.js → zh-TW-B1IdCz5g.js} +3 -3
  85. package/dist/index.html +5 -5
  86. package/dist/mini-chat.html +5 -5
  87. package/dist/mobile.html +5 -5
  88. package/package.json +1 -1
  89. package/server/lib/gui-customization/DOCUMENTATION.md +13 -2
  90. package/server/lib/gui-customization/session-skill.js +2 -2
  91. package/server/lib/gui-customization/session-skill.test.js +1 -1
  92. package/server/lib/gui-customization/skill/SKILL.md +8 -3
  93. package/server/lib/gui-customization/skill/references/appearance.md +6 -6
  94. package/server/lib/gui-customization/skill/references/file-previews.md +1 -1
  95. package/server/lib/gui-customization/skill/references/global-pages.md +1 -1
  96. package/server/lib/gui-customization/skill/references/ui-surfaces.md +228 -0
  97. package/server/lib/gui-customization/skill/references/workflow.md +31 -32
  98. package/server/lib/opencode/DOCUMENTATION.md +7 -0
  99. package/server/lib/opencode/npm-registry.js +9 -2
  100. package/server/lib/opencode/npm-registry.test.js +22 -1
  101. package/server/lib/opencode/plugin-routes.js +1 -0
  102. package/dist/assets/AssistantContactStatus-D0cP0UOu.js +0 -3
  103. package/dist/assets/MarkdownRenderer-DVKRLcN5.js +0 -2
  104. package/dist/assets/MobileTabPageHeader-l9R9cIsn.js +0 -2
  105. package/dist/assets/SettingsView-wm-g9vvT.js +0 -30
  106. package/dist/assets/insertionBoundaries-DxuIUK0X.js +0 -1
  107. package/dist/assets/main-CKdt6zYu.js +0 -2
  108. package/dist/assets/miniChat-Qg-TMzPz.js +0 -2
  109. package/dist/assets/mobile-LXYsDpBs.js +0 -2
  110. package/dist/assets/multirun-B1BNFN80.js +0 -3
  111. package/dist/assets/projectMeta-D4-hBAf0.js +0 -1
  112. package/dist/assets/renderElectronMiniChatApp-C1vzQUQn.js +0 -2
  113. package/dist/assets/renderMobileApp-Bxlepbqn.js +0 -28
  114. package/dist/assets/runtimeEndpointReset-CGWAfy_Y.js +0 -149
  115. package/dist/assets/sessionLookup-CgL50yRb.js +0 -1
  116. package/dist/assets/speechSettingsQueries-BHjkhNvX.js +0 -4
  117. package/dist/assets/useDesktopWindowControlsLayout-DBGiDEmg.js +0 -1
  118. /package/dist/assets/{SettingsView-C0HSdVvS.css → VoiceSettings-C0HSdVvS.css} +0 -0
package/dist/index.html CHANGED
@@ -560,7 +560,7 @@
560
560
  opacity: 0.72;
561
561
  }
562
562
  </style>
563
- <script type="module" crossorigin src="/assets/main-CKdt6zYu.js"></script>
563
+ <script type="module" crossorigin src="/assets/main-BGYY-hd1.js"></script>
564
564
  <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
565
565
  <link rel="modulepreload" crossorigin href="/assets/runtime-auth-DBn9yahL.js">
566
566
  <link rel="modulepreload" crossorigin href="/assets/runtime-switch-DEZ1K7qW.js">
@@ -592,10 +592,10 @@
592
592
  <link rel="modulepreload" crossorigin href="/assets/terminalApi-ChZhb60_.js">
593
593
  <link rel="modulepreload" crossorigin href="/assets/runtime-file-download-D6bwc3Kj.js">
594
594
  <link rel="modulepreload" crossorigin href="/assets/platform-DFJEtBlo.js">
595
- <link rel="modulepreload" crossorigin href="/assets/types-D7m_3iXu.js">
596
- <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-n0GPI3Ea.js">
597
- <link rel="modulepreload" crossorigin href="/assets/native-config-CxrxYHct.js">
598
- <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-DmZoakxE.js">
595
+ <link rel="modulepreload" crossorigin href="/assets/types-O8iYyCQi.js">
596
+ <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-Bas1D6ds.js">
597
+ <link rel="modulepreload" crossorigin href="/assets/native-config-DF7bq4tk.js">
598
+ <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BuChFCqQ.js">
599
599
  <link rel="stylesheet" crossorigin href="/assets/src-EZMbcCtg.css">
600
600
  </head>
601
601
  <body class="h-full bg-background text-foreground">
@@ -77,7 +77,7 @@
77
77
  .dark #initial-loading img { filter: invert(1); }
78
78
  </style>
79
79
 
80
- <script type="module" crossorigin src="/assets/miniChat-Qg-TMzPz.js"></script>
80
+ <script type="module" crossorigin src="/assets/miniChat-DJrq4mIe.js"></script>
81
81
  <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
82
82
  <link rel="modulepreload" crossorigin href="/assets/runtime-auth-DBn9yahL.js">
83
83
  <link rel="modulepreload" crossorigin href="/assets/runtime-switch-DEZ1K7qW.js">
@@ -109,10 +109,10 @@
109
109
  <link rel="modulepreload" crossorigin href="/assets/terminalApi-ChZhb60_.js">
110
110
  <link rel="modulepreload" crossorigin href="/assets/runtime-file-download-D6bwc3Kj.js">
111
111
  <link rel="modulepreload" crossorigin href="/assets/platform-DFJEtBlo.js">
112
- <link rel="modulepreload" crossorigin href="/assets/types-D7m_3iXu.js">
113
- <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-n0GPI3Ea.js">
114
- <link rel="modulepreload" crossorigin href="/assets/native-config-CxrxYHct.js">
115
- <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-DmZoakxE.js">
112
+ <link rel="modulepreload" crossorigin href="/assets/types-O8iYyCQi.js">
113
+ <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-Bas1D6ds.js">
114
+ <link rel="modulepreload" crossorigin href="/assets/native-config-DF7bq4tk.js">
115
+ <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BuChFCqQ.js">
116
116
  <link rel="stylesheet" crossorigin href="/assets/src-EZMbcCtg.css">
117
117
  </head>
118
118
  <body class="h-full bg-background text-foreground">
package/dist/mobile.html CHANGED
@@ -64,7 +64,7 @@
64
64
  </script>
65
65
 
66
66
  <style>.dark #mobile-startup-logo img { filter: invert(1); }</style>
67
- <script type="module" crossorigin src="/assets/mobile-LXYsDpBs.js"></script>
67
+ <script type="module" crossorigin src="/assets/mobile-BOrcaJMH.js"></script>
68
68
  <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
69
69
  <link rel="modulepreload" crossorigin href="/assets/runtime-auth-DBn9yahL.js">
70
70
  <link rel="modulepreload" crossorigin href="/assets/runtime-switch-DEZ1K7qW.js">
@@ -96,10 +96,10 @@
96
96
  <link rel="modulepreload" crossorigin href="/assets/terminalApi-ChZhb60_.js">
97
97
  <link rel="modulepreload" crossorigin href="/assets/runtime-file-download-D6bwc3Kj.js">
98
98
  <link rel="modulepreload" crossorigin href="/assets/platform-DFJEtBlo.js">
99
- <link rel="modulepreload" crossorigin href="/assets/types-D7m_3iXu.js">
100
- <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-n0GPI3Ea.js">
101
- <link rel="modulepreload" crossorigin href="/assets/native-config-CxrxYHct.js">
102
- <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-DmZoakxE.js">
99
+ <link rel="modulepreload" crossorigin href="/assets/types-O8iYyCQi.js">
100
+ <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-Bas1D6ds.js">
101
+ <link rel="modulepreload" crossorigin href="/assets/native-config-DF7bq4tk.js">
102
+ <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-BuChFCqQ.js">
103
103
  <link rel="stylesheet" crossorigin href="/assets/src-EZMbcCtg.css">
104
104
  </head>
105
105
  <body class="h-full bg-background text-foreground">
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yuriai/web",
3
- "version": "0.2.29-beta.7",
3
+ "version": "0.2.29-beta.9",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "main": "./server/index.js",
@@ -1,18 +1,29 @@
1
1
  # Built-in Yuri customization skill
2
2
 
3
- `session-skill.js` stages the shipped `skill/SKILL.md` and its six references in
3
+ `session-skill.js` stages the shipped `skill/SKILL.md` and its references in
4
4
  an application-owned, content-fingerprinted `session-skills` directory. Only a
5
5
  short discovery pointer enters `session.instructions.entry` under
6
6
  `yuri.customization`. Agents load the skill and matching references on demand;
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, global pages,
10
+ References are organized by capability: window APIs, appearance, UI surfaces, global pages,
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/ui-surfaces.md` is the shipped structural/style map for plugin authors
17
+ without a source checkout. It covers shell, sidebar, header, transcript, composer,
18
+ preview, Settings, overlays, tokens/cascade and native transparency boundaries.
19
+ The entry and appearance reference route existing-block CSS work there first.
20
+ DOM hooks are version-sensitive implementation guidance, not new public APIs.
21
+ When these owners change, update their map and recipes alongside the owning docs.
22
+
23
+ The authoring workflow defaults to directly written `gui-experimental.cjs` with
24
+ host-provided modules and inline assets. Local edits use the existing revision
25
+ watcher; compilation is only an optional path for typed/JSX or bundled sources.
26
+
16
27
  ## Admission ownership
17
28
 
18
29
  - 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/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/gui-api.md', 'references/workflow.md', 'references/global-pages.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. Use its capability references for supported contracts and runtime limits, and 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), 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.`,
30
30
  });
31
31
  };
32
32
  }
@@ -23,7 +23,7 @@ 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', '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', '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);
27
27
  expect(await fs.readFile(path.join(path.dirname(file), 'references', 'appearance.md'), 'utf8')).toContain('yuri.branding');
28
28
  expect(put.mock.calls[1][0].value).toBe(entry.value);
29
29
  });
@@ -11,18 +11,23 @@ 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
+ - 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.
14
15
  - Themes, CSS, logos, Dock icons: [appearance](references/appearance.md).
15
16
  - Global main-content tabs and titlebar entries: [global pages](references/global-pages.md).
16
17
  - Custom file suffixes, parsers, inline/mobile previews and file icons: [file previews](references/file-previews.md).
17
18
  - Preview toolbar placement, PDF/PNG/HTML export and iframe snapshot boundaries: [preview actions and exports](references/preview-exports.md).
18
19
  - Panels, commands, settings, files, RPC, lifecycle, runtime support: [GUI API](references/gui-api.md).
19
- - Every implementation: [package, build, install, verification and rollback](references/workflow.md).
20
- 3. Build only the requested capabilities in a user-approved plugin directory. Use declarative registries for appearance, window APIs for GUI behavior, and a server or native part only when the required capability needs it. Keep dependencies aligned with the supported SDK contract and emit the GUI as one prebuilt CommonJS file.
21
- 4. Build and inspect the actual artifact. Preserve unrelated global OpenCode configuration. Install only when asked, using the plugin package's global config entry; project-only configuration does not provide window GUI inventory.
20
+ - Every implementation: [direct-CJS package, installation, updates and rollback](references/workflow.md); compilation is an optional branch.
21
+ 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.
22
+ 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.
22
23
  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.
23
24
 
24
25
  References distinguish host contracts from illustrative templates and case studies. Choose rendering, authentication and file formats for the current requirement; case-study protocols and dependencies belong to those integrations.
25
26
 
27
+ ## Source fallback
28
+
29
+ If the references and target UI leave the relevant selector, style owner or extension behavior unclear, inspect the implementation at https://github.com/yee94/yuri. Prefer the tag matching the installed Yuri version; use `main` for development builds. Start from the source-owner paths in [UI structure and styles](references/ui-surfaces.md) or the matching capability reference, and read the owning component/style/host module to resolve the specific uncertainty. Repository source is a lookup fallback; customization still goes in the plugin.
30
+
26
31
  ## Boundaries
27
32
 
28
33
  - `Style` can affect the whole document. A GUI plugin is trusted JavaScript, not a sandbox. Prefer tokens and narrow, stable selectors; arbitrary CSS can hide controls or trigger network requests.
@@ -1,6 +1,6 @@
1
1
  # Appearance contracts
2
2
 
3
- Use `Plugin`, `Registry`, and `Style` from `@opencode/plugin/gui`. The package build/install instructions are in [workflow](workflow.md).
3
+ Use `Plugin`, `Registry`, and `Style` from `@opencode/plugin/gui`. Start with the [direct-CJS package](workflow.md); the TypeScript below documents shapes, not a compilation requirement.
4
4
 
5
5
  ## Activation and priority
6
6
 
@@ -43,12 +43,12 @@ The host owns a collision-free theme ID `gui:` + `JSON.stringify([pluginId, id])
43
43
 
44
44
  ## CSS: official `Style`
45
45
 
46
- ```ts
47
- import css from './skin.css?inline'
48
- ctx.add(Style, css)
46
+ ```js
47
+ const { Style } = require('@opencode/plugin/gui')
48
+ ctx.add(Style, `[data-yuri-logo] { border-radius: 12%; }`)
49
49
  ```
50
50
 
51
- CSS is active immediately while the plugin is enabled. Host base theme variables stay before plugin styles, including after theme switches. Ordinary CSS specificity and source order still apply; the declarative resource priority above does not reorder style elements. Base light tokens include `:root:not(.dark)` (two class-level selectors), so a plain `:root` override has lower specificity; use `html[data-theme="light"]` / `html[data-theme="dark"]` or matching specificity. Tailwind aliases such as `--background` / `--primary` are important declarations and require an important override if you deliberately bypass a registered theme. Common semantic tokens: `--surface-background`, `--surface-foreground`, `--surface-muted-foreground`, `--primary-base`, `--interactive-selection`, and `--font-mono`. Inspect actual current DOM/tokens before targeting a specific layout; generated Tailwind classes are not a stable plugin API. `[data-yuri-logo]` identifies the shared application logo. CSS does not cross iframe or native-window boundaries.
51
+ CSS is active immediately while the plugin is enabled. Declarative resource priority does not reorder style elements; normal cascade rules still apply. For existing blocks, read [UI structure and styles](ui-surfaces.md): it maps material owners, selectors, theme aliases, specificity, scoped recipes and native transparency boundaries. It also explains why changing a semantic variable alone may leave its generated alias unchanged.
52
52
 
53
53
  ## Branding: `yuri.branding`
54
54
 
@@ -69,7 +69,7 @@ ctx.add(Branding, {
69
69
  At least one of `logo` / `dockIcon` is required. `svg` / `png` are the dark/default resource; the `light*` resource is optional. Logo and Dock are resolved independently, so a Logo-only plugin does not suppress another plugin's Dock icon. Branding does not rename the app or replace its wordmark text.
70
70
 
71
71
  - Logos: inline complete SVG text with SVG namespace; maximum 16 KiB UTF-8 each. Static geometry, groups, gradients, defs, clipPath, mask and local `#id` references are allowed. Scripts, event handlers, embedded HTML, stylesheets, inline style, external references, DTD and processing instructions are rejected. Resources render as images, never injected SVG markup.
72
- - Dock: inline `data:image/png;base64,...`, at most 2 MiB of URL text, valid PNG, dimensions 1–1024 per side. Import with `?inline` as text only when it really yields a PNG data URL, or generate the data URL at build time. No filesystem path or remote image URL. Requires trusted local macOS Electron; no plugin `main` needed. Preview builds or older shells may reject the capability. Other runtimes still support the logo.
72
+ - Dock: inline `data:image/png;base64,...`, at most 2 MiB of URL text, valid PNG, dimensions 1–1024 per side. Encode the chosen image once and embed the data URL in the CJS file. No filesystem path or remote image URL. Requires trusted local macOS Electron; no plugin `main` needed. Preview builds or older shells may reject the capability. Other runtimes still support the logo.
73
73
  - Maximum 8 branding entries/plugin, 64/window; combined serialized appearance contributions 8 MiB/plugin, 16 MiB/window. IDs/titles are nonempty strings up to 128 characters; IDs are unique within each registry/plugin.
74
74
  - Unregister, disable, reload, failure and runtime switch withdraw resources. If several local windows apply a Dock icon, the newest active window update wins; closing/releasing it restores the previous window's icon or Yuri default. System appearance changes cannot overwrite an active plugin icon.
75
75
  - Invalid appearance contributions or a failed Dock application fail the owning plugin and clean its contributions; unrelated plugins remain active. Diagnostics appear in plugin settings. These contracts do not grant a JS sandbox.
@@ -4,7 +4,7 @@ A file parser/viewer uses official `LinkHandler` + `Panel` + `PanelTab.file`, op
4
4
 
5
5
  ## Complete JSON-format viewer
6
6
 
7
- This working entry recognizes `.report.json`, parses JSON into formatted text, retains its DOM on background updates, and localizes errors. Use the package/build config in [workflow](workflow.md). A real visual report renderer replaces only the parsing/rendering part.
7
+ This typed entry recognizes `.report.json`, parses JSON into formatted text, retains its DOM on background updates, and localizes errors. For the default direct-CJS package in [workflow](workflow.md), use `require`/`module.exports` and omit type annotations; the example uses no JSX. The optional build branch supports retaining TypeScript. A visual report renderer replaces the parsing/rendering part.
8
8
 
9
9
  ```ts
10
10
  import { bindPlugin, createKeyed, LinkHandler, Panel, Plugin, usePlugin, type PanelProps, type PanelTab } from '@opencode/plugin/gui'
@@ -4,7 +4,7 @@ Yuri provides a global **main-content placement**, not a new renderer. `yuri.pag
4
4
 
5
5
  ## Complete window entry
6
6
 
7
- Use the package and Vite config from [workflow](workflow.md), replacing `src/gui.tsx` with:
7
+ This typed example shows the page contract. For the default direct-CJS package in [workflow](workflow.md), replace imports/exports with `require`/`module.exports` and omit type annotations; it uses no JSX. Retain TypeScript through the optional build branch only when needed.
8
8
 
9
9
  ```ts
10
10
  import { Command, Contract, Plugin, Registry, TitlebarItem, usePlugin, type IconName, type TitlebarItem as TitlebarContribution } from '@opencode/plugin/gui'
@@ -0,0 +1,228 @@
1
+ # Built-in UI structure and styles
2
+
3
+ Read this for changes to existing Yuri blocks: backgrounds, sidebar, header, chat, composer, preview, Settings or overlays. For contribution schemas and activation, use [appearance](appearance.md). This map travels with Yuri so plugin authors can start without a source checkout or unpacking the application.
4
+
5
+ ## Fast path
6
+
7
+ 1. Locate the requested block in the table below. Prefer a theme contribution for coordinated colors, or a scoped `Style` rule for one block's material/geometry.
8
+ 2. Inspect only that block's computed styles and ancestors in the target client. Installed plugins may already override the built-in styles; the live result is not necessarily the default.
9
+ 3. Apply the smallest override, then check the changed block in light/dark and its relevant interaction states. A missing selector means a different view/version or an unmounted block, not permission to broaden the selector to the whole app.
10
+
11
+ `yuri.*` registries are contracts. DOM attributes and named classes below are current implementation hooks: prefer them over utility-class strings, translated labels, `nth-child` or generated IDs, and check their presence on the installed version. Preserve scroll ownership, resize handles and input layout while changing materials.
12
+
13
+ ## Layout map
14
+
15
+ Desktop session view, simplified ownership (wrappers omitted; not a selector chain):
16
+
17
+ ```text
18
+ html → body → #root → .main-content-safe-area
19
+ aside.yuri-vibrancy-surface → .yuri-session-sidebar
20
+ [data-chat-area]
21
+ main[data-primary-chat]
22
+ header.header-safe-area
23
+ [data-primary-chat-content]
24
+ transcript [data-scrollbar="chat"] → .yuri-chat-scroll-content
25
+ [data-message-id] → .chat-message-column → message content
26
+ .chat-input-column → composer surface
27
+ aside[data-context-panel] → [data-context-layout] → preview / file rail
28
+ body → portalled dialogs / menus / tooltips
29
+ ```
30
+
31
+ Settings and global plugin pages can replace the session view. Mobile uses page/sheet/composer-foot surfaces rather than this full desktop split. Mini Chat and VS Code have different outer shells; shared composer/message hooks still need their enclosing scope checked.
32
+
33
+ | Block | Locate | Built-in material / useful knobs |
34
+ | --- | --- | --- |
35
+ | App canvas | `body`, `#root`, `.main-content-safe-area` | `--background`; several nested wrappers also paint `bg-background`. Clearing only `body` does not clear its children. |
36
+ | Left sidebar | `aside.yuri-vibrancy-surface`; contents `.yuri-session-sidebar` | `--sidebar`, `--sidebar-vibrancy-overlay`; native vibrancy rules described below. Dark sidebar text has local overrides. |
37
+ | Header | `header.header-safe-area` | `--background`; native Windows chrome can use `--surface-background`. Preserve `.app-region-no-drag` controls and titlebar drag geometry. |
38
+ | Primary chat | `[data-primary-chat]`, `[data-primary-chat-content]` | Main and inner ChatContainer wrappers paint `--background`. Chat workspace and preview are siblings. |
39
+ | Transcript | `[data-scrollbar="chat"]`, `.yuri-chat-scroll-content` | Scroll viewport and content, respectively. `.chat-column` / `.chat-message-column` own reading width. Message roots carry `data-message-id`; IDs are runtime data, not style keys. |
40
+ | Composer column | `.chat-input-column` | Shares `--yuri-chat-column-max` and `--yuri-chat-column-max-wide` with transcript. Also used by draft headings/presets, so not itself the input card. |
41
+ | Composer card | `.chat-input-column div:has(> [data-composer-content="true"])` | `ChatComposerSurface`: light background/border/shadow; dark foreground mix (8%, hover/focus 11%). Radius is inline `var(--radius-xl)`. This structural selector is version-sensitive. |
42
+ | Composer content | `[data-composer-content="true"]` → `[data-composer-input-shell="true"]` → `textarea[data-chat-input="true"]` | Content/layout owner, highlight/input stack, then transparent native textarea. The textarea is not the card's material owner. Footer: `[data-chat-input-footer="true"]`; actions: `[data-composer-send]`, `[data-composer-stop]`. |
43
+ | Preview | `[data-context-panel="true"]`, `[data-context-layout="single"]` / `[data-context-layout="split"]` | Outer panel is transparent; editors, web previews and file rails can paint their own backgrounds. CSS in the host does not style an iframe's document or a native webview. |
44
+ | Settings | `.yuri-settings-workspace`, `.yuri-settings-sidebar` | Workspace owns local form tokens. Group structure: `.yuri-settings-group` → label + `.yuri-settings-group-card` → `.yuri-settings-group-row`. |
45
+ | Settings card | `.yuri-settings-group-card` | `--yuri-settings-group-background`, `--yuri-settings-group-border`, `--yuri-settings-group-radius`; row padding/dividers are separate tokens. |
46
+ | Form controls | `[data-slot="input"]`, `[data-slot="textarea"]`, `[data-slot="select-trigger"]` | `--form-control-*`; Settings adds `--yuri-settings-control-*`. Compound textarea material lives on its wrapper; simple textarea mode puts the slot on the textarea. |
47
+ | Dialogs | `[data-slot="dialog-content"]`, `[data-slot="dialog-overlay"]` | Ordinary dialog content uses `--background`; scrim is separate. Picker dialogs use `.yuri-picker-dialog` and glass material. Settings has its own dialog surface, not necessarily `dialog-content`. |
48
+ | Anchored menus / selects | `[data-slot="dropdown-menu-content"]`, `[data-slot="dropdown-menu-sub-content"]`, `[data-slot="select-content"]`, `.yuri-popup-surface` | Shared glass uses `--yuri-popup-fill` (an elevated-color mix), `--yuri-popup-edge`, `--yuri-popup-shadow`, `--yuri-popup-divider`. Changing `--popover` alone does not reach every popup. |
49
+ | Logo | `[data-yuri-logo]` | May be built-in `svg` or plugin `img`. Replace artwork with `yuri.branding`, not an SVG-path CSS selector. Does not include the wordmark, agent avatars, provider logos or startup splash. |
50
+ | Mobile / glass materials | `.yuri-mobile-composer-surface`, `.yuri-mobile-overlay-surface` | Additional glass, pseudo-element and keyboard/safe-area layers. The overlay class is also used on desktop. Inspect `::before` / `::after` as well as background; retain positioning and viewport insets. |
51
+
52
+ ### Chat paint layers
53
+
54
+ `ChatWorkspace` exposes the outer boundaries. Inside `[data-primary-chat-content]`, the active `ChatContainerContent` has its own full-height `bg-background` root. It is separate from the transparent workspace boundary. The normal conversation branch contains:
55
+
56
+ ```text
57
+ [data-primary-chat-content] transparent boundary
58
+ … session-host wrappers …
59
+ div.relative.flex.flex-col.h-full.bg-background ChatContainerContent root
60
+ div.relative.min-h-0.flex-1 ChatViewport allocation
61
+ div.absolute.inset-0 viewport positioner
62
+ [data-scrollbar="chat"].chat-scroll actual ScrollShadow viewport
63
+ .yuri-chat-scroll-content scroll content
64
+ … MessageList / turn / virtualizer wrappers …
65
+ [data-message-id] message root
66
+ .chat-message-column reading-width wrapper
67
+ [data-user-message-bubble="true"] user bubble, nested in layout/animation wrappers
68
+ div.relative.z-10.bg-background composer foot (viewport sibling)
69
+ div[aria-hidden="true"] desktop edge-fade gradient
70
+ … .chat-input-column …
71
+ div:has(> [data-composer-content="true"]) composer card
72
+ [data-composer-content="true"]
73
+ … [data-composer-input-shell="true"] …
74
+ [data-composer-highlight="true"] optional highlight layer
75
+ … textarea[data-chat-input="true"]
76
+ [data-chat-input-footer="true"] stacked-layout footer
77
+ ```
78
+
79
+ The class-only root, positioner, desktop composer foot and edge fade have **no dedicated data selector**. Their utility classes describe the current structure, not unique identifiers. The desktop fade is an absolute `bottom-full` element with a background-image gradient from `--surface-background` to transparent; it is not the scroll viewport's background color. Mobile composer feet use `.yuri-mobile-composer-foot`, optionally `.yuri-mobile-composer-foot--overlay`.
80
+
81
+ | State / content | Actual selector or structure | Paint ownership |
82
+ | --- | --- | --- |
83
+ | Normal conversation | `[data-scrollbar="chat"]` inside the ChatContainer root | Viewport/content wrappers normally have no background fill; root and composer foot independently use `--background`. |
84
+ | Session hydration | `.chat-scroll` inside the ChatContainer root; no `data-scrollbar="chat"` on this branch | Skeleton scroll viewport additionally has `bg-background`. |
85
+ | Session loading placeholder | `[data-session-view-loading="true"]` | Own `bg-background`; no transcript viewport yet. |
86
+ | Draft / empty conversation | `.yuri-draft-center` when compact draft layout is active; otherwise unnamed layout wrappers | Root and composer placement wrappers use `bg-background`; a transcript selector need not exist. |
87
+ | User message | `[data-message-id] [data-user-message-bubble="true"]` | Inline `background-color: var(--chat-user-message-bg)`; inline radius `--radius-xl`, bottom-right `--radius-sm`. The message root and `.chat-message-column` are not the bubble. |
88
+ | User shell output | `[data-shell-result="true"]` | Replaces the ordinary user-bubble branch; no user-bubble fill/radius from `ChatMessage`. |
89
+ | Assistant message | `[data-message-id].yuri-message-hover-scope` → `.chat-message-column` → content | Ordinary assistant wrapper is transparent, not a symmetric user bubble. Code, tools and other cards own their materials. `--chat-assistant-message-bg` exists as a token but is not applied to this outer wrapper. |
90
+ | Composer card | `.chat-input-column div:has(> [data-composer-content="true"])` | Own fill, border, shadow and inline radius; its parent foot is a separate painted layer. |
91
+ | Composer send / stop glyph | `[data-composer-send]`, `[data-composer-stop]` contain the circular icon | Inner icon uses `bg-foreground text-background`: `--foreground` paints the disk, `--background` paints the glyph via `currentColor`. |
92
+
93
+ Source owners: `ChatWorkspace.tsx`, `ChatContainer.tsx`, `ChatMessage.tsx`, `ChatPromptComposer.tsx`, `ChatComposerSurface.tsx`, and `components/icons/StopIcon.tsx` under `packages/ui/src` (layout/chat subdirectories as listed below).
94
+
95
+ ## Token map and cascade
96
+
97
+ Theme values are CSS colors, not HSL channel tuples: use `var(--background)`, not `hsl(var(--background))`.
98
+
99
+ | Theme field | Semantic variable | Generated alias / common consumer |
100
+ | --- | --- | --- |
101
+ | `surface.background` | `--surface-background` | `--background` → `bg-background`, app/chat/header |
102
+ | `surface.foreground` | `--surface-foreground` | `--foreground` → ordinary text |
103
+ | `surface.muted` | `--surface-muted` | `--muted`, `--secondary`, `--sidebar-base` → `--sidebar` |
104
+ | `surface.mutedForeground` | `--surface-muted-foreground` | `--muted-foreground`, `--sidebar-foreground` |
105
+ | `surface.elevated` | `--surface-elevated` | `--card`, `--popover` |
106
+ | `surface.elevatedForeground` | `--surface-elevated-foreground` | `--card-foreground`, `--popover-foreground` |
107
+ | `surface.subtle` | `--surface-subtle` | `--accent`, `--sidebar-accent-base` → `--sidebar-accent` |
108
+ | `primary.base` | `--primary-base` | `--primary`; default action buttons instead use neutral surfaces |
109
+ | `interactive.border` | `--interactive-border` | `--border`, `--input` (border, not input fill) |
110
+ | `interactive.hover` / `selection` / `focusRing` | `--interactive-hover`, `--interactive-selection`, `--interactive-focus-ring` | Interaction fills and focus; `--ring` aliases focusRing |
111
+
112
+ The generator writes semantic variables and aliases as **separate values**. Changing only `--surface-background` does not update `--background`. A `yuri.theme` contribution keeps them coordinated automatically. For CSS-only overrides, change the variables actually consumed by the target.
113
+
114
+ Variables are shared by consumers, not exclusively by visual regions. `--background` also supplies inverse foregrounds (`text-background`), while `--surface-background` supplies composer fills and edge gradients. `--chat-user-message-bg` comes from `chat.userMessageBackground`, falling back to `surface.elevated`; `--chat-assistant-message-bg` comes from `chat.assistantMessageBackground`, falling back to `surface.muted`. An element's `background` property affects that element's paint; changing an inherited variable affects all descendant consumers, including text and nested cards.
115
+
116
+ Base variables live in `style#opencode-theme-variables`; plugin styles in `style[data-yuri-plugin-style]` follow that block. Light variables use `:root:not(.dark)` (specificity 0,2,0); dark uses `:root` and `.dark`. Aliases such as `--background`, `--sidebar` and `--popover` are `!important`. Later position alone cannot beat specificity or importance. Neither `html:root` nor `html[data-theme="light"]` beats `:root:not(.dark)` at equal importance. Use `:root:root` for a mode-independent equal-specificity rule, or `:root[data-theme="light"]` / `:root[data-theme="dark"]` for a mode-specific one, with `!important` only for important declarations you intend to override.
117
+
118
+ `data-theme="light|dark"` describes the effective mode; `.light` / `.dark` also exist. `.desktop-runtime` means the native desktop runtime; `.device-desktop` is layout/device classification and also occurs in a desktop browser. A plugin's `Style` participates in the CSS cascade; declarative appearance contribution priority is a separate mechanism.
119
+
120
+ In light mode, the generated selection fill derives from foreground/background, rather than copying `interactive.selection` directly. Inspect `--interactive-selection` when styling selected states.
121
+
122
+ ### Geometry and text
123
+
124
+ - Reading/input width: `--yuri-chat-column-max`, `--yuri-chat-column-max-wide`; `.wide-chat-layout` selects the latter. Change both only when both modes are requested.
125
+ - Typography: `--font-sans`, `--font-mono`, `--text-markdown`, `--text-code`, `--text-ui-header`, `--text-ui-label`, `--text-meta`, `--text-micro`; corresponding `.typography-*` classes consume the size tokens.
126
+ - Settings: `--yuri-settings-group-radius`, `--yuri-settings-row-min-height`, `--yuri-settings-row-block-padding`, `--yuri-settings-row-inset`, `--yuri-settings-section-stack-gap`. Put overrides on `.yuri-settings-workspace`, where defaults are declared, rather than on an ancestor that would be shadowed.
127
+ - Controls: `--form-control-height`, `--form-control-radius`, `--form-control-background`, `--form-control-border`. Settings can override these through its local material tokens.
128
+
129
+ ## Scoped recipes
130
+
131
+ Register these through official `Style`; choose the relevant recipe rather than applying all of them. Colors and dimensions below are illustrative.
132
+
133
+ ### Coordinate canvas tokens
134
+
135
+ ```css
136
+ :root[data-theme="light"] {
137
+ --surface-background: #f5f7fa;
138
+ --background: #f5f7fa !important;
139
+ }
140
+ :root[data-theme="dark"] {
141
+ --surface-background: #171b22;
142
+ --background: #171b22 !important;
143
+ }
144
+ ```
145
+
146
+ This changes all consumers of these canvas tokens, including the composer base and ordinary dialogs. For a single block, set that block's `background-color` instead. `--card`, `--popover`, sidebar, glass-popup and syntax surfaces remain independently owned. When another enabled plugin already overrides a semantic token with `!important`, resolve that conflict explicitly; these examples target the built-in styles.
147
+
148
+ ### Composer material
149
+
150
+ ```css
151
+ .chat-input-column div:has(> [data-composer-content="true"]) {
152
+ background: var(--surface-elevated);
153
+ border-color: var(--interactive-border);
154
+ box-shadow: none;
155
+ border-radius: 18px !important;
156
+ }
157
+ ```
158
+
159
+ The radius override is important because this component writes radius inline. Input and highlight layers must keep identical typography, padding and line wrapping. Scope the selector under `[data-primary-chat]` when only the primary session composer should change; shared composers can also appear in Bot and mini-chat surfaces.
160
+
161
+ ### Settings card and row spacing
162
+
163
+ ```css
164
+ .yuri-settings-workspace {
165
+ --yuri-settings-group-radius: 12px;
166
+ --yuri-settings-row-block-padding: 0.75rem;
167
+ --yuri-settings-group-background: var(--surface-elevated);
168
+ }
169
+ ```
170
+
171
+ Applies to standard group cards. Specialized list surfaces can deliberately replace the material (for example, `.yuri-provider-collection-card` stays transparent and square); inspect that block's owning rule when it is the requested target.
172
+
173
+ ### Reading width
174
+
175
+ ```css
176
+ :root:root {
177
+ --yuri-chat-column-max: 54rem;
178
+ --yuri-chat-column-max-wide: 68rem;
179
+ }
180
+ ```
181
+
182
+ This keeps transcript, input and column-aligned controls on the same width system rather than stretching only the textarea.
183
+
184
+ ## Transparency and glass
185
+
186
+ Distinguish three layers: **CSS paint**, **browser canvas**, **native window material**. `background: transparent` removes only that element's paint; descendants, ancestors, pseudo-elements, gradients and native material may still be visible. `opacity` affects text and controls too, so it is not a substitute for background alpha.
187
+
188
+ - For a translucent block, change its material and preserve foreground/hover/focus contrast. Inspect all painted layers in the block before broadening the override.
189
+ - Canvas wrappers, message bubbles, composer cards and popups are separate paint owners. Their shared color variables also serve foregrounds and gradients; the ownership table above identifies element backgrounds separately from those tokens.
190
+ - Native macOS vibrancy uses `data-yuri-vibrancy`, `data-yuri-vibrancy-ready` and `.yuri-vibrancy-surface`. The sidebar paints `--sidebar` until ready, then `--sidebar-vibrancy-overlay`. Suppressed/native-browser-visible states and reduced-transparency preferences restore opacity. These are host state signals; CSS must not manufacture them to enable native behavior.
191
+ - CSS `backdrop-filter` and native vibrancy are different layers. Removing CSS blur does not remove native blur. GUI appearance contracts expose Logo/Dock resources and CSS, not a general transparent-window/vibrancy control. A web preview cannot prove desktop see-through behavior.
192
+ - Host CSS stops at iframe/native-webview boundaries; use the embedded content's own theming contract where available.
193
+
194
+ ## Bounded inspection
195
+
196
+ Run in the target page's browser evaluation context. Replace the selector list with only the affected blocks; this reads geometry/materials without dumping conversation text or configuration.
197
+
198
+ ```js
199
+ const selectors = ['[data-primary-chat]', '.header-safe-area', '.yuri-vibrancy-surface'];
200
+ selectors.map(selector => ({
201
+ selector,
202
+ count: document.querySelectorAll(selector).length,
203
+ samples: [...document.querySelectorAll(selector)].slice(0, 2).map(element => {
204
+ const style = getComputedStyle(element);
205
+ return {
206
+ background: style.backgroundColor,
207
+ image: style.backgroundImage,
208
+ backdrop: style.backdropFilter,
209
+ before: getComputedStyle(element, '::before').backgroundColor,
210
+ after: getComputedStyle(element, '::after').backgroundColor,
211
+ canvas: style.getPropertyValue('--background').trim(),
212
+ surface: style.getPropertyValue('--surface-background').trim(),
213
+ };
214
+ }),
215
+ }));
216
+ ```
217
+
218
+ If an override loses, inspect the matching rule in `opencode-theme-variables`, the target's inline style and the relevant plugin style. Resolve that cascade conflict before scanning unrelated source or application bundles. Verify the requested block, relevant hover/focus/disabled states, mode switch, and removal of the plugin override.
219
+
220
+ ## Source owners (when a checkout is available)
221
+
222
+ Paths are relative to the Yuri repository; installed-plugin work does not require these files.
223
+
224
+ - Shell: `packages/ui/src/components/layout/{MainLayout,Sidebar,Header,ChatWorkspace,ContextPanel}.tsx`.
225
+ - Composer: `packages/ui/src/components/chat/{ChatComposerSurface,ChatPromptComposer,ChatInput}.tsx`; transcript: `ChatContainer.tsx`, `ChatMessage.tsx` in the same directory.
226
+ - Theme variables: `packages/ui/src/lib/theme/cssGenerator.ts`; base materials/native transparency: `packages/ui/src/index.css`, `packages/ui/src/styles/design-system.css`.
227
+ - Width/type: `packages/ui/src/styles/typography.css`; Settings: `packages/ui/src/styles/settings.css`; mobile materials: `packages/ui/src/styles/mobile.css`.
228
+ - Primitives and Logo: `packages/ui/src/components/ui/`; native window material: `packages/electron/main.mjs`.
@@ -1,8 +1,8 @@
1
- # Package, build, install, verify
1
+ # Package, install, update
2
2
 
3
3
  ## Complete minimal appearance plugin
4
4
 
5
- Use a separate plugin directory, not Yuri's source tree. These three files illustrate a complete theme + logo + CSS package. For pages, file viewers or other capabilities, keep the package/build structure and use the matching reference's GUI entry. A Dock contribution is needed only when requested.
5
+ Default to a directly authored CommonJS file in a separate plugin directory. These two files are a complete theme + logo + CSS plugin: no dependency installation, compiler or dev server is needed. Include only the contributions requested by the user.
6
6
 
7
7
  `package.json`:
8
8
 
@@ -11,37 +11,20 @@ Use a separate plugin directory, not Yuri's source tree. These three files illus
11
11
  "name": "yuri-studio-skin",
12
12
  "version": "0.1.0",
13
13
  "private": true,
14
- "type": "module",
15
- "exports": { "./gui-experimental": "./dist/gui-experimental.cjs" },
16
- "files": ["dist"],
17
- "scripts": { "build": "vite build", "dev": "vite build --watch" },
18
- "dependencies": { "@opencode/plugin": "2.2.0" },
19
- "devDependencies": { "vite": "^7.0.0", "vite-plugin-solid": "^2.11.0", "solid-js": "^1.9.0" }
14
+ "exports": { "./gui-experimental": "./gui-experimental.cjs" },
15
+ "files": ["gui-experimental.cjs"]
20
16
  }
21
17
  ```
22
18
 
23
- `vite.config.ts`:
19
+ `gui-experimental.cjs`:
24
20
 
25
- ```ts
26
- import { defineConfig } from 'vite'
27
- import { gui } from '@opencode/plugin/gui/vite'
28
- export default defineConfig({ plugins: [gui()] })
29
- ```
21
+ ```js
22
+ const { Plugin, Registry, Style } = require('@opencode/plugin/gui')
30
23
 
31
- `src/gui.tsx`:
24
+ const Theme = Registry.define('yuri.theme')
25
+ const Branding = Registry.define('yuri.branding')
32
26
 
33
- ```tsx
34
- import { Plugin, Registry, Style } from '@opencode/plugin/gui'
35
-
36
- const Theme = Registry.define<{
37
- id: string; title: string; variant: 'dark' | 'light';
38
- colors?: { primary?: { base?: string }; surface?: { background?: string } }
39
- }>('yuri.theme')
40
- const Branding = Registry.define<{
41
- id: string; title: string; logo?: { svg: string; lightSvg?: string }
42
- }>('yuri.branding')
43
-
44
- export default Plugin.define({
27
+ module.exports = Plugin.define({
45
28
  setup(ctx) {
46
29
  ctx.add(Theme, {
47
30
  id: 'studio-dark', title: 'Studio Dark', variant: 'dark',
@@ -59,23 +42,39 @@ export default Plugin.define({
59
42
  })
60
43
  ```
61
44
 
62
- This package has no server entry and no `main`; its package name becomes its plugin ID. For a mixed server/GUI plugin, use the server part's `Plugin.define` ID consistently. No separate Yuri entrypoint is needed. The official Vite preset compiles Solid, inlines dynamic imports/dependencies, and emits one CJS file. Shared SDK/Solid/Effect modules must remain host-provided, not bundled duplicates.
45
+ This package has no server entry and no `main`; its package name becomes its plugin ID. For a mixed server/GUI plugin, use the server part's `Plugin.define` ID consistently. The host supplies the SDK through `require`; a standalone Node `require` is not the plugin runtime. Use `node --check gui-experimental.cjs` for a quick syntax check.
46
+
47
+ Keep CSS/SVG as strings and Dock PNGs as data URLs in this file. Window DOM APIs and host-provided Solid helpers work without JSX. The host resolves only its shared modules, not relative `require('./style.css')`, sibling source files, or arbitrary installed dependencies. TypeScript snippets in other references describe contracts; direct CJS uses plain JavaScript, `require` and `module.exports` without type annotations.
63
48
 
64
49
  ## Installation and updates
65
50
 
66
- 1. Ask permission before installing dependencies or changing config. Use the user's selected package manager to install this standalone package's declared dependencies and run `build`. Verify `dist/gui-experimental.cjs` exists and exports a definition; do not point the host at TSX or an ES module.
51
+ 1. Write the two files above and syntax-check the `.cjs`. Installation follows the user's requested scope; a direct-CJS plugin needs no package-manager step. The GUI entry is executable CommonJS JavaScript, not TS/TSX or ESM source.
67
52
  2. Inspect the user's **global** `opencode.json(c)` and preserve unrelated configuration/comments. Add the absolute plugin directory to `plugins`, or use the documented OpenCode plugin installation command after checking that CLI's current help/docs. Do not invent CLI flags. For example:
68
53
 
69
54
  ```jsonc
70
55
  { "plugins": ["/absolute/path/to/yuri-studio-skin"] }
71
56
  ```
72
57
 
73
- 3. Yuri loads GUI entries from the connected service's global inventory. A project-only plugin entry will not supply a window GUI. Local path changes rebuilt by Vite are revision updates, not new npm versions. Confirm the plugin appears active in plugin settings; explicit refresh can retry a failed instance. The GUI enable switch is separate from server plugin loading.
58
+ 3. Yuri loads GUI entries from the connected service's global inventory. A project-only plugin entry will not supply a window GUI. Save changes directly to the exported `.cjs`; the local-file watcher updates the GUI revision and reloads the plugin. No build, version bump or application restart is needed for this edit loop. Confirm the plugin appears active in plugin settings; explicit refresh can retry a failed instance. The GUI enable switch is separate from server plugin loading.
74
59
  4. Verify appearance contributions apply when the GUI is enabled, using [appearance](appearance.md) for priority and fallback. For other capabilities, verify their registered entry points.
75
- 5. For publication, remove `private` only when requested, build first, and publish the package with its CJS artifact. Use a new npm version for updates. No publishing is implied by a local customization request.
60
+ 5. For publication, remove `private` only when requested and include the exported CJS file in the package. Use a new npm version for published updates. No publishing is implied by a local customization request.
61
+
62
+ ## Optional: compiled source
63
+
64
+ Use a build only when the implementation needs TS/TSX, JSX, bundled dependencies or split source/assets, or when maintaining an existing compiled plugin. The GUI host still receives one CommonJS file; OpenCode's ability to load server-side TypeScript does not extend to the GUI entry.
65
+
66
+ For this branch, put the source in `src/gui.tsx`, point `./gui-experimental` at `./dist/gui-experimental.cjs`, and include `dist` in `files`. Use `@opencode/plugin` 2.2.0 with compatible `vite`, `vite-plugin-solid` and `solid-js` development dependencies and these scripts: `build: vite build`, `dev: vite build --watch`. Install dependencies only within the authorized plugin scope.
67
+
68
+ ```ts
69
+ import { defineConfig } from 'vite'
70
+ import { gui } from '@opencode/plugin/gui/vite'
71
+ export default defineConfig({ plugins: [gui()] })
72
+ ```
73
+
74
+ The official preset compiles Solid JSX and emits one CJS file, inlining dynamic imports and non-shared dependencies. SDK/Solid/Effect shared modules remain host-provided. Here, saving source requires a rebuild (or `vite build --watch`) before the exported file changes and reloads.
76
75
 
77
76
  ## Verification and rollback
78
77
 
79
- Verify each implemented capability in the target client, not only the bundler. Check its normal, failed and unavailable states, cleanup on disable/rebuild, and isolation from unrelated plugins. Capability-specific checks belong to the matching reference. Report checks not performed rather than inferring cross-platform success.
78
+ Verify each implemented capability in the target client. Check its normal, failed and unavailable states, cleanup on disable/reload, and isolation from unrelated plugins. Capability-specific checks belong to the matching reference. Report checks not performed rather than inferring cross-platform success.
80
79
 
81
80
  Rollback: disable this GUI plugin or remove only its config entry. Disabling cleans contributions and native leases; appearance falls back according to its resource priority. Preserve unrelated plugins, user data and Yuri app resources.
@@ -83,6 +83,13 @@ encoding, not removed V1 endpoints.
83
83
  - `packages/web/server/lib/opencode/proxy.js`: OpenCode API/SSE forwarding and readiness-gate route registration.
84
84
  - `npm-registry.js`: plugin package lookup used by `GET /api/config/plugins/registry`. It asks the user's own `npm view` first (run in the project directory, so scope registries, auth tokens and mirrors from `.npmrc` apply as they do for `npm install`) and falls back to a direct request to the public registry only when the CLI is unavailable; a CLI 404 is final. Results are cached per name and directory. The latest release's top-level package.json `icon` is returned as `icon` only when it is an `https://` URL or `data:image/` URI of at most ~1.5 MB; nested icon fields are not read or used as fallbacks.
85
85
  - `plugin-icon.js` owns the shared icon sanitizer and optional local package metadata read for Web/Electron/mobile and VS Code. Registry `path-ok` includes the nearest package manifest's top-level `icon` for directories or built entry files. Search stops at the first manifest, root or 32 parents; malformed, unreadable or >2 MiB manifests omit artwork without changing path status. No server-side image fetch occurs. Settings → Plugins renders package artwork directly; GUI sidebar/titlebar entries use official `IconName` without package-image substitution.
86
+
87
+ Registry callers can opt into `details=true` for the latest developer-provided
88
+ `description` and package `readme`. npm CLI and HTTP lookups retain these fields
89
+ (bounded to 4,096 and 131,072 characters); ordinary version-check responses omit
90
+ them. The three-step setup tour uses the same authenticated batch route and icon
91
+ sanitizer, never a separate browser registry client. README Markdown is untrusted
92
+ display content, not instructions executed by the host.
86
93
  - `plugin-gui-response.js`: shared Web/Electron/VS Code code-only revision response owner for exact `GET /api/plugin/gui?id=…` (one nonempty id). The installed GUI client alias is official `@opencode/client@2.2.0`: HTTP returns `{ location, data: { code, revision, options } }`. Every call still reads the complete current upstream response through the existing auth/readiness/abort boundary; there is no Host bundle cache.
87
94
  - Request `X-Yuri-Gui-Revision: <lowercase SHA-256 hex of UTF-8 revision>` opts into code reuse. This header and HTTP condition/range headers are stripped before upstream so Yuri always requests a complete representation. Other query and request headers retain proxy semantics.
88
95
  - A valid upstream 200 JSON bundle (`code` string, nonempty `revision` string, `options` object) receives `X-Yuri-Gui-Revision` and `Cache-Control: private, no-store`. Matching tokens additionally receive `X-Yuri-Gui-Code: cached` and only `data.code` becomes `''`; current `options`, `revision`, location and other fields remain. Unmatched/ordinary calls preserve original body bytes. No 304 or Yuri ETag is generated. Upstream failure statuses/bodies remain failures; malformed successful bodies remain unchanged without a revision receipt.