feat(icons): support imported inline SVG data

Author: dvcolomban

alias.ts

@@ -55,6 +55,7 @@ export const alias = {
   '@devframes/hub/node': r('hub/src/node/index.ts'),
   '@devframes/hub/types': r('hub/src/types/index.ts'),
   '@devframes/hub': r('hub/src/index.ts'),
+  '@devframes/hub-ui/icons': r('hub-ui/src/client/utils/icons.ts'),
   '@devframes/hub-ui': r('hub-ui/src/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
   '@devframes/nuxt/single': r('nuxt/src/single.ts'),

design/dock-icon.ts

@@ -1,45 +1,14 @@
-// Framework-neutral port of @antfu/design's `DisplayIconifyRemoteIcon`:
-// https://github.com/antfu/design/blob/main/packages/design/components/Display/DisplayIconifyRemoteIcon.vue
-//
-// Resolves a devframe dock `icon` (an Iconify `collection:icon` id, e.g.
-// `ph:git-branch-duotone`) to its live, sanitized SVG markup, fetched from the
-// public `api.iconify.design` CDN. Unlike a UnoCSS `preset-icons` class, this
-// needs no `@iconify-json/*` collection installed and no hand-maintained
-// id -> class table, since any Iconify id just works, at the cost of a network
-// round-trip on first render. We reuse @antfu/design's own fetcher, cache and
-// sanitizer (`utils/iconify.ts`) rather than reimplementing them; only the id
-// parsing and light/dark selection below are devframe-specific, mirroring the
-// upstream Vue component's own `icon` prop parsing. Vue surfaces should render
-// `DisplayIconifyRemoteIcon` directly instead of using this port.
-import { getIconifySvg } from '@antfu/design/utils/iconify'
+import type { DevframeIcon } from 'devframe/types'
+import { getIconSource, getIconSvg } from '../packages/hub-ui/src/client/utils/icons'
 
-// Mirrors DisplayIconifyRemoteIcon.vue's own `collection:icon` parse (with an
-// optional `i-` prefix tolerated so a UnoCSS-style id also works).
-const ICONIFY_ID = /^(?:i-)?([\w-]+):([\w-]+)$/
-
-/**
- * Resolve a dock icon (a `collection:icon` string, or a `{ light, dark }`
- * pair whose `light` variant is fetched) to its sanitized SVG markup.
- *
- * Returns `undefined` when the id doesn't parse or the fetch fails, so the
- * caller can fall back to a text initial.
- *
- * @example
- * await dockIconSvg('ph:git-branch-duotone') // → '<svg ...>...</svg>'
- */
-export async function dockIconSvg(name: string | { light: string, dark: string } | undefined): Promise<string | undefined> {
-  const id = typeof name === 'string' ? name : name?.light
-  if (!id)
-    return undefined
-  const match = id.match(ICONIFY_ID)
-  if (!match)
+/** Resolve the selected icon variant; failed remote requests leave the monogram fallback. */
+export async function dockIconSvg(icon: DevframeIcon | undefined, dark = false): Promise<string | undefined> {
+  if (!icon)
     return undefined
   try {
-    return await getIconifySvg(match[1]!, match[2]!)
+    return await getIconSvg(getIconSource(icon, dark))
   }
   catch {
-    // A failed fetch (offline / flaky CDN) degrades to the text-initial
-    // fallback, not a thrown error out of a render path.
     return undefined
   }
 }

docs/content/1.guide/16.hub.md

@@ -254,3 +254,25 @@ Two minimal hubs mount every built-in devframe behind an icon dock, plus a "Tabb
 ## Diagnostics
 
 Hub-side diagnostic codes live in the `DF8xxx` range; see the [error reference](/errors).
+
+## Inline icons
+
+Dock entries, commands, launcher entries, and terminal sessions accept named Iconify icons, image URLs, imported Iconify data, or raw SVG markup:
+
+```ts
+import terminal from '@iconify-icons/ph/terminal-window-duotone'
+
+const importedIcon = { icon: terminal }
+const localIcon = {
+  icon: { svg: '<svg viewBox="0 0 24 24"><path fill="currentColor" d="M4 4h16v16H4z"/></svg>' },
+}
+const themedIcon = { icon: { light: terminal, dark: localIcon.icon } }
+```
+
+Import only the icons you use from your icon package, or import a committed SVG as text through your build tool. These objects are JSON-serializable; no registration or runtime package lookup is required. The shared `DevframeIconSource` type describes one source, and `DevframeDockEntryIcon` also accepts a light/dark pair.
+
+The reference hub UI provider sanitizes imported markup and renders it inline. `currentColor` inherits the surrounding theme, hover, selected, and disabled styles. Image URLs and data URLs retain the `<img>` path and do not inherit text color. The JSON renderer's component catalog remains separate.
+
+The stock hub UI provider bundles a finite set of Phosphor icons used by its dock defaults, including Terminals, Messages, and Inspector. Other named icons continue to use the remote Iconify service. No complete icon collection is shipped to the browser.
+
+External custom hub UI providers must support the new object forms before using them. The browser-only `@devframes/hub-ui/icons` entry exports `getIconSource(icon, dark)`, `isIconImage(source)`, and `getIconSvg(source)` for custom renderers: select a variant, render image sources with `<img>`, and render resolved sanitized markup inline. Handle rejected remote requests and ignore results after the source changes or the view is removed.

examples/custom-hub-next/src/client/app/page.tsx

@@ -223,7 +223,7 @@ function pollDrawer(
 /** Fetches (and caches, for the component's lifetime) a dock icon's sanitized SVG. */
 function useDockIconSvg(icon: DevframeDockEntry['icon']): string | undefined {
   const [svg, setSvg] = useState<string | undefined>(undefined)
-  const key = typeof icon === 'string' ? icon : icon?.light
+  const key = JSON.stringify(icon)
 
   useEffect(() => {
     let cancelled = false

examples/custom-hub-vite/src/client/main.ts

@@ -77,10 +77,6 @@ function renderList<T>(host: HTMLElement, items: readonly T[], row: (item: T) =>
     : '<li class="rounded-lg border border-base bg-base border-dashed px2.5 py1.5 text-xs font-mono op-mute">empty</li>'
 }
 
-function iconName(icon: DevframeDockEntry['icon']): string | undefined {
-  return typeof icon === 'string' ? icon : icon?.light
-}
-
 // One dock-rail button: a monogram placeholder for the icon (patched with the
 // real SVG once `paintDockIcons` resolves it), the title, and an optional badge.
 function dockButton(entry: DevframeDockEntry, selectedId: string | null): string {
@@ -103,7 +99,7 @@ function dockButton(entry: DevframeDockEntry, selectedId: string | null): string
 // keeps the monogram.
 function paintDockIcons(list: readonly DevframeDockEntry[]): void {
   for (const entry of list) {
-    if (!iconName(entry.icon))
+    if (!entry.icon)
       continue
     void dockIconSvg(entry.icon).then((svg) => {
       const slot = el.docks.querySelector<HTMLElement>(`[data-dock-icon="${entry.id}"]`)

package.json

@@ -37,7 +37,7 @@
     "release": "bumpp -r",
     "typecheck": "pnpm run verify:typecheck-coverage && turbo run typecheck",
     "verify:typecheck-coverage": "tsx scripts/verify-typecheck-coverage.ts",
-    "postinstall": "npx simple-git-hooks && skills-npm && pnpm run build:css"
+    "postinstall": "npx simple-git-hooks && skills-npm && pnpm run build:css && pnpm --filter @devframes/hub-ui run build:icons"
   },
   "devDependencies": {
     "@antfu/design": "catalog:frontend",

packages/devframe/package.json

@@ -94,6 +94,7 @@
     }
   },
   "dependencies": {
+    "@iconify/types": "catalog:types",
     "@modelcontextprotocol/server": "catalog:deps",
     "@standard-schema/spec": "catalog:deps",
     "birpc": "catalog:deps",

packages/devframe/src/types/devframe.ts

@@ -2,6 +2,7 @@ import type { CAC } from 'cac'
 import type { CliFlagsSchema } from '../adapters/flags'
 import type { DevframeAuthHandler } from '../node/auth/handler'
 import type { DevframeNodeContext } from './context'
+import type { DevframeIcon } from './icons'
 import type { StaticAssetsSource } from './remote-assets'
 import type { DevframeServiceInput } from './services'
 
@@ -295,7 +296,7 @@ export interface DevframeDockDefaults {
   /** Dock entry title. Defaults to the definition's `name`. */
   title?: string
   /** Dock entry icon. Defaults to the definition's `icon`. */
-  icon?: string | { light: string, dark: string }
+  icon?: DevframeIcon
   /**
    * Sort weight within the dock; higher sorts earlier.
    * @default 0
@@ -383,7 +384,7 @@ export interface DevframeDefinition {
   homepage: string
   /** One-line summary of what the tool does. */
   description: string
-  icon?: string | { light: string, dark: string }
+  icon?: DevframeIcon
   /**
    * Default dock attributes applied when a hub mounts this devframe as an
    * iframe dock entry. Consulted only by the hub install path (`ctx.install`),

packages/devframe/src/types/icons.ts

@@ -0,0 +1,7 @@
+import type { IconifyIcon } from '@iconify/types'
+
+/** Iconify name, image URL, or inline icon data supplied by a devframe. */
+export type DevframeIconSource = string | IconifyIcon | { svg: string }
+
+/** An icon shared across themes, or separate light and dark sources. */
+export type DevframeIcon = DevframeIconSource | { light: DevframeIconSource, dark: DevframeIconSource }

packages/devframe/src/types/index.ts

@@ -4,6 +4,7 @@ export * from './devframe'
 export * from './diagnostics'
 export * from './events'
 export * from './host'
+export * from './icons'
 export * from './remote-assets'
 export * from './rpc'
 export * from './rpc-augments'