@changfenhuang/dsh-genui 0.11.4 → 0.12.0

package/src/client/artifact/ExportableGenuiBlock.tsx

@@ -13,6 +13,17 @@ interface ArtifactExportMenuProps {
   getArtifact: () => ReturnType<typeof createGenuiArtifact>
 }
 
+/** 导出入口的图标字形：托盘 + 下箭头（“导出为文件”），14px 描边、随文字取色。 */
+function ExportGlyph() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
+      <path d="M8 2.2v7.1" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" />
+      <path d="M5 6.4 8 9.4l3-3" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M2.9 10.9v1.5a1 1 0 0 0 1 1h8.2a1 1 0 0 0 1-1v-1.5" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" />
+    </svg>
+  )
+}
+
 /** 提供 JSON 和 HTML 的本地化导出菜单。 */
 function ArtifactExportMenu({ getArtifact }: ArtifactExportMenuProps) {
   const t = useT()
@@ -65,8 +76,18 @@ function ArtifactExportMenu({ getArtifact }: ArtifactExportMenuProps) {
     <div className={css.chrome} ref={rootRef} data-genui-export>
       {report.externalMedia.length > 0 && <span className={css.notice}>{t('artifact.externalMediaNotice')}</span>}
       {errorMessage !== '' && <span className={css.statusError} aria-live="polite">{errorMessage}</span>}
-      <button type="button" className={css.trigger} aria-haspopup="menu" aria-expanded={open} onClick={() => setOpen(value => !value)}>
-        {t('artifact.export')}
+      {/* 无边框图标入口：完成态内容不再多出一个描边按钮。图标按钮的 aria-label
+          + title 组合与项目里的 panelTpl / panelToggle 一致。 */}
+      <button
+        type="button"
+        className={css.trigger}
+        aria-label={t('artifact.export')}
+        title={t('artifact.export')}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen(value => !value)}
+      >
+        <ExportGlyph />
       </button>
       {open && (
         <div className={css.menu} role="menu">

package/src/client/blocks/charts.tsx

@@ -345,7 +345,7 @@ export const TableNode = memo(function TableNode({ node, renderDetail, filterVal
           .join(' ') || undefined}
       >
         {type === 'badge'
-          ? <span className={css.cellBadge}>{renderInline(String(cell), false)}</span>
+          ? <span className={css.cellBadge}>{renderInline(String(cell), 'file')}</span>
           : type === 'bar'
             ? <CellBar cell={cell} />
             : type === 'spark'
@@ -356,8 +356,8 @@ export const TableNode = memo(function TableNode({ node, renderDetail, filterVal
                   ? <span className={css.cellIndex}>{rowIndex + 1}</span>
                   : tone === null
                     // Format displayed text without changing sorting or exported data.
-                    ? renderInline(String(cell), false)
-                    : <span className={`${css.tdDelta} ${tone === 'up' ? css.tdDeltaUp : css.tdDeltaDown}`}>{renderInline(String(cell), false)}</span>}
+                    ? renderInline(String(cell), 'file')
+                    : <span className={`${css.tdDelta} ${tone === 'up' ? css.tdDeltaUp : css.tdDeltaDown}`}>{renderInline(String(cell), 'file')}</span>}
       </td>
     )
   }
@@ -396,13 +396,21 @@ export const TableNode = memo(function TableNode({ node, renderDetail, filterVal
                       <button
                         type="button"
                         className={css.groupToggle}
+                        aria-label={tr(isCollapsed ? 'block.table.expandGroup' : 'block.table.collapseGroup', {
+                          label: String(section.header.row[0]).replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'),
+                        })}
                         aria-expanded={!isCollapsed}
                         onClick={() => toggleSection(headerIndex)}
                       >
                         <span className={css.groupChevron} aria-hidden>{isCollapsed ? '▸' : '▾'}</span>
-                        {renderInline(String(section.header.row[0]), false)}
-                        <span className={css.groupCount}>{section.children.length}</span>
                       </button>
+                      <span className={css.groupLabel} onClick={event => {
+                        if (event.target instanceof Element && event.target.closest('button')) return
+                        toggleSection(headerIndex)
+                      }}>
+                        {renderInline(String(section.header.row[0]), 'file')}
+                        <span className={css.groupCount}>{section.children.length}</span>
+                      </span>
                     </td>
                   </tr>
                 )}
@@ -419,12 +427,20 @@ export const TableNode = memo(function TableNode({ node, renderDetail, filterVal
                                 <button
                                   type="button"
                                   className={css.detailToggle}
+                                  aria-label={tr(open ? 'block.table.collapseDetails' : 'block.table.expandDetails', {
+                                    label: String(cell).replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'),
+                                  })}
                                   aria-expanded={open}
                                   onClick={() => toggleDetail(child.index)}
                                 >
                                   <span className={css.detailChevron} data-open={open} aria-hidden>▸</span>
-                                  {renderInline(String(cell), false)}
                                 </button>
+                                <span className={css.detailContent} onClick={event => {
+                                  if (event.target instanceof Element && event.target.closest('button')) return
+                                  toggleDetail(child.index)
+                                }}>
+                                  {renderInline(String(cell), 'file')}
+                                </span>
                               </td>
                             )
                             : renderCell(cell, j, child.index)

package/src/client/blocks/render-node.tsx

@@ -9,6 +9,8 @@ import * as primitives from '../primitive-adapter.ts'
 import css from '../GenuiBlock.module.css'
 import { GENUI_LIMITS } from '../genui-runtime/index.ts'
 import { renderInline } from '../inline.ts'
+import { classifyLinkTarget } from '../file-link.ts'
+import { FileLink } from '../file-link-context.tsx'
 import { t } from '../i18n/index.ts'
 import type { GenuiList, GenuiNode } from '../spec.ts'
 import type { AnswersState, GenuiBlockProps } from './state.ts'
@@ -283,13 +285,14 @@ export function renderNode(
     case 'select': return <SelectNode key={key} node={node} onAction={onAction} answers={answers} />
     case 'checkbox': return <CheckboxNode key={key} node={node} onAction={onAction} answers={answers} />
     case 'link': {
-      // Honest affordance: with a whitelisted href this is a REAL anchor;
-      // without one it is plain styled text (a dead clickable-looking button
-      // was the same complaint class as the disabled-button fix).
-      const href = node.href
-      return href !== undefined
-        ? <a key={key} className={css.link} href={href} target="_blank" rel="noopener noreferrer">{renderInline(node.label, false)}</a>
-        : <span key={key} className={css.linkText}>{renderInline(node.label, false)}</span>
+      const target = classifyLinkTarget(node.href)
+      if (target.type === 'external') {
+        return <a key={key} className={css.link} href={target.href} target="_blank" rel="noopener noreferrer">{renderInline(node.label, false)}</a>
+      }
+      if (target.type === 'file') {
+        return <FileLink key={key} path={target.file.path} label={node.label} {...(target.file.line === undefined ? {} : { line: target.file.line })}>{renderInline(node.label, false)}</FileLink>
+      }
+      return <span key={key} className={css.linkText}>{renderInline(node.label, false)}</span>
     }
     case 'image': return <ImageNode key={`${key}:${node.src}`} node={node} />
     case 'audio': return <AudioNode key={`${key}:${node.src}`} node={node} />

package/src/client/dom-fence.tsx

@@ -58,6 +58,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ChatNode, ChatSnapshot } from '@deepseek-ai/dsh-client-ui-chat/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { GenuiActionContext, type GenuiActionHandler } from './action-context.ts'
+import { withFileLinkContext, type FileLinkAvailability, type FileLinkCordisContext } from './file-link-context.tsx'
 import css from './GenuiBlock.module.css'
 import { renderSvgFence } from './svg-fence.tsx'
 import { repairFenceJson, trimToBalancedRoot } from '../shared/fence-repair.ts'
@@ -68,13 +69,27 @@ import { diagnoseUnknownGenuiFields } from './genui-runtime/diagnostics.ts'
 import { normalizeGenuiSpec } from './genui-runtime/normalize.ts'
 import { sourceFencesOfAssistant, sourceLanguageAt } from './source-fence.ts'
 
-/** Fence surfaces the channel can take over, newest host first: the shared
- * CodeBlock surface every rc.6+ markdown fence renders through
- * (`.md-code-block`) and the deepsuite-style surfaces some host builds
- * render instead (`.code-block` / `.code-block-small`). Surfaces with an
- * unlisted class are still found by the structural backstop (label + `<pre>`),
- * so this list is an optimization, not a hard contract. */
+/** 优先用宿主代码块内容的语义标记定位包装节点；隐藏语言或改变类名不能阻断
+ * 原始消息的围栏识别。类名也用于仍以这些表面呈现的代码块。 */
 const CODE_BLOCK_SELECTORS = '.md-code-block, .code-block, .code-block-small'
+
+/** 在同一处收集代码块包装节点，供候选扫描和原始围栏序号共用。 */
+function codeBlockSurfaces(scope: ParentNode): HTMLElement[] {
+  const surfaces = new Set(scope.querySelectorAll<HTMLElement>(CODE_BLOCK_SELECTORS))
+  for (const content of scope.querySelectorAll<HTMLElement>('[data-code-block-content]')) {
+    if (content.parentElement !== null) surfaces.add(content.parentElement)
+  }
+  return [...surfaces].sort((left, right) => left.compareDocumentPosition(right) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1)
+}
+
+/** 返回拥有代码内容语义节点、或已知代码块类名的最近包装节点。 */
+function closestCodeBlockSurface(element: Element | null): Element | null {
+  for (let current = element; current !== null; current = current.parentElement) {
+    if (current.matches(CODE_BLOCK_SELECTORS)
+      || [...current.children].some(child => child.hasAttribute('data-code-block-content'))) return current
+  }
+  return null
+}
 /** Marker attribute set on blocks this channel has taken over. */
 const PROCESSED = 'data-genui-rendered'
 /** The settled marker on AssistantMarkdown (absent = settled). */
@@ -86,6 +101,10 @@ const DIAGNOSTIC_CLASS = 'genui-dom-fence-diagnostic'
 /** Slow sweep interval: the observer catches everything, this is the 1s
  * belt-and-braces pass (history loads, missed attribute batches). */
 const SWEEP_MS = 1000
+const NO_FILE_LINK_AVAILABILITY: FileLinkAvailability = {
+  subscribe: () => () => {},
+  getSnapshot: () => false,
+}
 
 /** Max ancestors walked from a `<pre>` to its fence surface root (banner +
  * pre holder). Most hosts put the pre directly under the surface; some wrap
@@ -196,7 +215,7 @@ function infostringOf(block: Element): 'dsh-ui' | 'svg' | null {
     // surface's banner, not `block`'s own banner. Only accept labels whose
     // nearest known surface is `block` itself (or none — unknown surfaces
     // stay supported by the structural backstop).
-    const owner = el.closest(CODE_BLOCK_SELECTORS)
+    const owner = closestCodeBlockSurface(el)
     if (owner !== null && owner !== block) continue
     return lang
   }
@@ -350,11 +369,11 @@ function implausibleLabeledAncestorOf(pre: HTMLElement, scope: ParentNode = docu
 function findFenceCandidates(scope: ParentNode = document): HTMLElement[] {
   const seen = new Set<HTMLElement>()
   const out: HTMLElement[] = []
-  for (const el of scope.querySelectorAll<HTMLElement>(CODE_BLOCK_SELECTORS)) {
+  for (const el of codeBlockSurfaces(scope)) {
     // Modifier classes can sit inside a surface (e.g. a `code-block-small`
     // child of `code-block`): only the outermost matching element is a
     // candidate, so a fence is never double-counted or taken over twice.
-    if (el.parentElement !== null && el.parentElement.closest(CODE_BLOCK_SELECTORS) !== null) continue
+    if (closestCodeBlockSurface(el.parentElement) !== null) continue
     if (el.closest(`.${CONTAINER_CLASS}, .${DIAGNOSTIC_CLASS}, [data-genui-svg-fence]`) !== null) continue
     if (seen.has(el)) continue
     // Message-level containers that happen to carry a surface class must
@@ -373,7 +392,8 @@ function findFenceCandidates(scope: ParentNode = document): HTMLElement[] {
     // markdown root holding both a dsh-ui fence and a python block — and
     // the backstop would mislabel that whole container as a fence, hiding
     // every other code block with it (issue #13).
-    if (pre.closest(`${CODE_BLOCK_SELECTORS}, .${CONTAINER_CLASS}, .${DIAGNOSTIC_CLASS}, [data-genui-svg-fence]`) !== null) continue
+    if (closestCodeBlockSurface(pre) !== null
+      || pre.closest(`.${CONTAINER_CLASS}, .${DIAGNOSTIC_CLASS}, [data-genui-svg-fence]`) !== null) continue
     const surface = surfaceOf(pre, scope)
     if (surface === null) {
       // Diagnose the issue #19 guard: a labeled ancestor that is NOT a code
@@ -394,7 +414,8 @@ function findFenceCandidates(scope: ParentNode = document): HTMLElement[] {
     seen.add(surface)
   }
   for (const span of scope.querySelectorAll<HTMLElement>('span')) {
-    if (span.closest(`.${CONTAINER_CLASS}, .${DIAGNOSTIC_CLASS}, ${CODE_BLOCK_SELECTORS}, [data-chat-group-part="reasoning"], [data-tool], [data-sidebar-chat], [data-sidebar-right-session], [data-sidebar-right-panel], [data-panel-conversation], [data-plugin-panel]`) !== null) continue
+    if (closestCodeBlockSurface(span) !== null
+      || span.closest(`.${CONTAINER_CLASS}, .${DIAGNOSTIC_CLASS}, [data-chat-group-part="reasoning"], [data-tool], [data-sidebar-chat], [data-sidebar-right-session], [data-sidebar-right-panel], [data-panel-conversation], [data-plugin-panel]`) !== null) continue
     if (tagTextBodyOf(span) === null) continue
     out.push(span)
   }
@@ -476,8 +497,8 @@ function fenceIndexOf(ctx: Context, row: Element, block: Element, sourceLanguage
 
 /** Return outer host Markdown code surfaces in one assistant row's DOM order. */
 function hostFenceBlocksOf(row: Element): HTMLElement[] {
-  return [...row.querySelectorAll<HTMLElement>(CODE_BLOCK_SELECTORS)].filter(candidate => {
-    if (candidate.parentElement?.closest(CODE_BLOCK_SELECTORS) !== null) return false
+  return codeBlockSurfaces(row).filter(candidate => {
+    if (closestCodeBlockSurface(candidate.parentElement) !== null) return false
     if (candidate.closest(`.${CONTAINER_CLASS}, .${DIAGNOSTIC_CLASS}, [data-genui], [data-genui-svg-fence]`) !== null) return false
     if (candidate.closest('[data-chat-group-part="reasoning"], [data-tool], [data-sidebar-chat], [data-sidebar-right-session], [data-sidebar-right-panel], [data-panel-conversation], [data-plugin-panel]') !== null) return false
     if (candidate.closest(ASSISTANT_FLOW_ROW) !== row) return false
@@ -504,13 +525,18 @@ export function sourceLanguageOf(ctx: Context, block: Element): string | null |
 }
 
 /** Cache each row's Markdown parse for one sweep and retain confirmed opening-line languages per host block. */
-function createSourceLanguageResolver(ctx: Context): { beginSweep: () => void; get: (block: Element) => string | null | undefined } {
+function createSourceLanguageResolver(ctx: Context): {
+  beginSweep: () => void
+  get: (block: Element) => string | null | undefined
+  isSessionUnavailable: () => boolean
+} {
   const stableLanguages = new WeakMap<Element, { sessionId: SessionId; nodeKey: string; language: string | null }>()
   let sweepLanguages = new Map<Element, string | null | undefined>()
   let parsedNodes = new Map<string, ReturnType<typeof sourceFencesOfAssistant>>()
   let sessionId: SessionId | undefined
   let chat: ChatSnapshot | undefined
   let chatRead = false
+  let sessionUnavailable = false
 
   return {
     beginSweep() {
@@ -519,13 +545,23 @@ function createSourceLanguageResolver(ctx: Context): { beginSweep: () => void; g
       sessionId = undefined
       chat = undefined
       chatRead = false
+      sessionUnavailable = false
+    },
+    isSessionUnavailable() {
+      return sessionUnavailable
     },
     get(block) {
       if (sweepLanguages.has(block)) return sweepLanguages.get(block)
       const row = block.closest<HTMLElement>(`${ASSISTANT_FLOW_ROW}[data-chat-node-key]`)
       if (row === null || row.dataset.chatGroupPart === 'reasoning') return undefined
       const nodeKey = row.dataset.chatNodeKey
-      const activeSessionId = sessionIdOfForSource(ctx)
+      const sourceSession = sourceSessionOf(ctx)
+      if (!sourceSession.available) {
+        sessionUnavailable = true
+        sweepLanguages.set(block, undefined)
+        return undefined
+      }
+      const activeSessionId = sourceSession.sessionId
       if (!nodeKey || activeSessionId === undefined) return undefined
 
       const stable = stableLanguages.get(block)
@@ -570,9 +606,19 @@ export function hostFenceIndexOf(row: Element, block: Element): number {
   return hostFenceBlocksOf(row).indexOf(block as HTMLElement)
 }
 
+/** Read the viewed session and report when Cordis rejects access to its Context. */
+function sourceSessionOf(ctx: Context): { available: true; sessionId: SessionId | undefined } | { available: false } {
+  try {
+    return { available: true, sessionId: resolveViewedSessionId(ctx.sessions.list.getSnapshot()) }
+  } catch {
+    return { available: false }
+  }
+}
+
 /** Read the currently viewed session for source Markdown lookup. */
 function sessionIdOfForSource(ctx: Context): SessionId | undefined {
-  return resolveViewedSessionId(ctx.sessions.list.getSnapshot())
+  const sourceSession = sourceSessionOf(ctx)
+  return sourceSession.available ? sourceSession.sessionId : undefined
 }
 
 /** Read uiConversation as an optional service so Cordis does not require a hard inject. */
@@ -650,6 +696,7 @@ function anchorSeqOf(row: Element): number {
 export function installDomFenceRenderer(
   ctx: Context,
   sendAction: (sessionId: SessionId, action: string, payload: Record<string, unknown>) => void,
+  fileLinkAvailability: FileLinkAvailability = NO_FILE_LINK_AVAILABILITY,
 ): () => void {
   if (typeof document === 'undefined') return () => {}
   driftWarned = false
@@ -665,12 +712,27 @@ export function installDomFenceRenderer(
   let unsubscribeChat: (() => void) | undefined
   const sourceLanguages = createSourceLanguageResolver(ctx)
 
-  const sessionIdOf = (): SessionId | undefined => {
-    try {
-      return resolveViewedSessionId(ctx.sessions.list.getSnapshot())
-    } catch {
-      return undefined
-    }
+  /** Apply both plugin contexts to every actual GenUI root render. */
+  function wrapFenceNode(node: ReactNode, context: GenuiFenceContext, handler: GenuiActionHandler, streaming: boolean): ReactNode {
+    const actionTree = <GenuiActionContext.Provider value={handler}>{node}</GenuiActionContext.Provider>
+    return withFileLinkContext(
+      ctx as unknown as FileLinkCordisContext,
+      fileLinkAvailability,
+      context.sessionId,
+      streaming,
+      actionTree,
+    )
+  }
+
+  const sessionIdOf = (): SessionId | undefined => sessionIdOfForSource(ctx)
+  let lastAvailableSessionId = sessionIdOf()
+
+  /** Keep a mounted fence's React identity stable while Cordis temporarily denies session access. */
+  function sessionIdForRender(preserveWhenUnavailable: boolean): SessionId | undefined {
+    const sourceSession = sourceSessionOf(ctx)
+    if (!sourceSession.available) return preserveWhenUnavailable ? lastAvailableSessionId : undefined
+    lastAvailableSessionId = sourceSession.sessionId
+    return sourceSession.sessionId
   }
 
   /** Retry ChatSnapshot subscription while the active session binding is unavailable. */
@@ -688,7 +750,7 @@ export function installDomFenceRenderer(
   /** Render context for a block: session always; the stable source identity
    * only once settled — streaming renders are identity-less (no panel
    * publish, no durable state), mirroring the registry channel. */
-  function contextOf(row: Element, block: Element, settled: boolean): { key: Key; context: GenuiFenceContext } {
+  function contextOf(row: Element, block: Element, settled: boolean, preserveSessionIdentity = false): { key: Key; context: GenuiFenceContext } {
     if (settled && row.getAttribute('data-chat-anchor-key') === null) {
       // Safari / fallback render path: the host omitted the row anchor (the
       // attribute is a React key that React drops when undefined). Fences
@@ -699,7 +761,7 @@ export function installDomFenceRenderer(
     const fenceIndex = fenceIndexOf(ctx, row, block, sourceLanguages.get)
     const anchorKey = row.getAttribute('data-chat-anchor-key') ?? 'unknown'
     const key = `dom:${anchorKey}:${fenceIndex}` as Key
-    const sessionId = sessionIdOf()
+    const sessionId = sessionIdForRender(preserveSessionIdentity)
     const context: GenuiFenceContext = {
       ...(sessionId === undefined ? {} : { sessionId }),
       ...(settled ? { source: { id: key as string, order: [anchorSeqOf(row), 0, fenceIndex] as const } } : {}),
@@ -868,7 +930,7 @@ export function installDomFenceRenderer(
     }
     try {
       const handler: GenuiActionHandler = (action, payload) => sendActionForBlock(block, action, payload)
-      root.render(<GenuiActionContext.Provider value={handler}>{payload}</GenuiActionContext.Provider>)
+      root.render(wrapFenceNode(payload, context, handler, !settled))
     } catch (error) {
       try {
         root.unmount()
@@ -941,7 +1003,9 @@ export function installDomFenceRenderer(
   function sweep(): void {
     if (disposed) return
     sourceLanguages.beginSweep()
-    const sessionId = sessionIdOf()
+    const sourceSession = sourceSessionOf(ctx)
+    const sessionId = sourceSession.available ? sourceSession.sessionId : undefined
+    if (sourceSession.available) lastAvailableSessionId = sourceSession.sessionId
     syncChatSubscription(sessionId)
     for (const [block, mount] of mounts) {
       if (!block.isConnected) {
@@ -953,13 +1017,15 @@ export function installDomFenceRenderer(
       const domLanguage = tagTextBodyOf(block) !== null ? 'dsh-ui' : domLanguageOf(block)
       const sourceLanguage = domLanguage === null ? sourceLanguages.get(block) : undefined
       const language = domLanguage ?? sourceLanguage
+      const sourceUnavailable = domLanguage === null
+        && (!sourceSession.available || sourceLanguages.isSessionUnavailable())
       const validGenui = language === 'dsh-ui'
         || (language === undefined && settled && isGenericGenuiFence(block, raw))
       if (mount.language === 'svg' && language !== 'svg') {
         unmountBlock(block)
         continue
       }
-      if (mount.language === 'dsh-ui' && !validGenui) {
+      if (mount.language === 'dsh-ui' && !validGenui && !sourceUnavailable) {
         unmountBlock(block)
         continue
       }
@@ -970,7 +1036,7 @@ export function installDomFenceRenderer(
       const contentWiped = !isPanelRoot(mount.lastNode) && mount.container.childElementCount === 0
       if (mount.lastRaw !== raw || mount.lastSettled !== settled || contentWiped) {
         const anchor = rowOf(block)
-        const { key, context } = contextOf(anchor, block, settled)
+        const { key, context } = contextOf(anchor, block, settled, true)
         const node = mount.language === 'svg' ? renderSvgFence(raw, key) : renderResolvedFenceNode(raw, key, context)
         if (node === null) {
           if (mount.skeleton && !settled) {
@@ -1002,7 +1068,7 @@ export function installDomFenceRenderer(
           try {
             const freshRoot = domRootFactory(fresh)
             const handler: GenuiActionHandler = (action, payload) => sendActionForBlock(block, action, payload)
-            freshRoot.render(<GenuiActionContext.Provider value={handler}>{node}</GenuiActionContext.Provider>)
+            freshRoot.render(wrapFenceNode(node, context, handler, !settled))
             mount.root = freshRoot
             mount.container = fresh
           } catch (error) {
@@ -1017,7 +1083,8 @@ export function installDomFenceRenderer(
           }
         } else {
           try {
-            mount.root.render(<GenuiActionContext.Provider value={(action, payload) => sendActionForBlock(block, action, payload)}>{node}</GenuiActionContext.Provider>)
+            const handler: GenuiActionHandler = (action, payload) => sendActionForBlock(block, action, payload)
+            mount.root.render(wrapFenceNode(node, context, handler, !settled))
           } catch (error) {
             // Never leave the stock block hidden behind a broken root: restore
             // the raw code block and drop the mount (issue #19).

package/src/client/file-address.ts

@@ -0,0 +1,37 @@
+const FILE_ADDRESS_PREFIX = 'dsh-resource://file/'
+
+/** Encode one address segment while keeping a Windows drive colon readable. */
+function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/%3A/gi, ':')
+}
+
+/** Encode each path segment independently so separators retain their structure. */
+function encodePath(path: string): string {
+  return path.split('/').map(encodeSegment).join('/')
+}
+
+/** Check whether a path uses a Windows drive or UNC spelling. */
+function isWindowsStylePath(value: string): boolean {
+  return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith('\\\\')
+}
+
+/** Check whether a path is absolute in a spelling accepted by the host. */
+function isAbsoluteWorkspacePath(path: string): boolean {
+  return path.startsWith('/') || isWindowsStylePath(path)
+}
+
+/** Build a session resource address while preserving encoded path segments. */
+export function sessionFileAddress(sessionId: string, path: string): string {
+  const normalized = path.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '')
+  return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(normalized)}`
+}
+
+/** Resolve workspace absolute paths to session-relative resource addresses. */
+export function fileAddressFor(sessionId: string, cwd: string | undefined, path: string): string {
+  const normalized = path.replace(/\\/g, '/')
+  if (!isAbsoluteWorkspacePath(normalized)) return sessionFileAddress(sessionId, normalized)
+  const root = cwd === undefined ? '' : cwd.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (root !== '' && normalized === root) return sessionFileAddress(sessionId, '')
+  if (root !== '' && normalized.startsWith(`${root}/`)) return sessionFileAddress(sessionId, normalized.slice(root.length + 1))
+  return sessionFileAddress(sessionId, normalized)
+}

package/src/client/file-link-context.tsx

@@ -0,0 +1,114 @@
+import { createContext, createElement, useContext, useMemo, useSyncExternalStore, type MouseEvent as ReactMouseEvent, type ReactNode } from 'react'
+import { fileAddressFor } from './file-address.ts'
+import { resolveViewedSessionId } from './session-resolver.ts'
+import css from './GenuiBlock.module.css'
+
+interface SidebarRightService {
+  openResource(address: string, options?: { params: { line: number } }): void
+}
+
+interface FileLinkHostContext {
+  get(name: 'sidebarRight', strict?: false): SidebarRightService | undefined
+  sessions: {
+    list: { getSnapshot(): unknown }
+  }
+}
+
+interface FileLinkScope {
+  get(name: 'sidebarRight'): SidebarRightService | undefined
+  effect(callback: () => void | (() => void), name?: string): unknown
+}
+
+export interface FileLinkCordisContext extends FileLinkHostContext {
+  inject(services: ['sidebarRight'], callback: (scope: FileLinkScope) => void): unknown
+}
+
+export interface FileLinkAvailability {
+  subscribe(listener: () => void): () => void
+  getSnapshot(): boolean
+}
+
+const FileLinkOpenContext = createContext<((path: string, line?: number) => void) | undefined>(undefined)
+
+/** Track an optional host service through arrival, removal, and plugin unload. */
+export function createFileLinkAvailability(ctx: FileLinkCordisContext): FileLinkAvailability {
+  let available = ctx.get('sidebarRight', false)?.openResource !== undefined
+  const listeners = new Set<() => void>()
+  const notify = (): void => {
+    for (const listener of listeners) listener()
+  }
+  const setAvailable = (next: boolean): void => {
+    if (available === next) return
+    available = next
+    notify()
+  }
+
+  ctx.inject(['sidebarRight'], (scope) => {
+    scope.effect(() => {
+      setAvailable(scope.get('sidebarRight')?.openResource !== undefined)
+      return () => setAvailable(false)
+    }, 'genui: file-link sidebarRight')
+  })
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    getSnapshot: () => available,
+  }
+}
+
+/** Provide one fence's session-scoped file opener to descendant components. */
+function FileLinkProvider({ ctx, availability, sessionId, streaming, children }: {
+  ctx: FileLinkHostContext
+  availability: FileLinkAvailability
+  sessionId: string | undefined
+  streaming: boolean
+  children?: ReactNode
+}) {
+  const available = useSyncExternalStore(availability.subscribe, availability.getSnapshot, () => false)
+  const open = useMemo(() => {
+    if (!available || streaming || sessionId === undefined) return undefined
+    return (path: string, line?: number): void => {
+      const snapshot = ctx.sessions.list.getSnapshot()
+      if (resolveViewedSessionId(snapshot) !== sessionId) return
+      const sessions = snapshot as { byId?: Record<string, { cwd?: string } | undefined> }
+      const cwd = sessions.byId?.[sessionId]?.cwd
+      const address = fileAddressFor(sessionId, cwd, path)
+      const sidebar = ctx.get('sidebarRight', false)
+      if (sidebar?.openResource === undefined) return
+      if (line === undefined) sidebar.openResource(address)
+      else sidebar.openResource(address, { params: { line } })
+    }
+  }, [available, ctx, sessionId, streaming])
+
+  return createElement(FileLinkOpenContext.Provider, { value: open }, children)
+}
+
+/** Render a file link as an accessible host navigation button when available. */
+export function FileLink({ path, line, label, children }: { path: string; line?: number; label: string; children?: ReactNode }) {
+  const open = useContext(FileLinkOpenContext)
+  if (open === undefined) return createElement('span', { title: path }, children)
+  return createElement('button', {
+    type: 'button',
+    className: css.inlineFileLink,
+    title: path,
+    'aria-label': `${label} (${path})`,
+    onClick: (event: ReactMouseEvent<HTMLButtonElement>) => {
+      event.stopPropagation()
+      open(path, line)
+    },
+  }, children)
+}
+
+/** Add session-scoped file navigation to one fence render tree. */
+export function withFileLinkContext(
+  ctx: FileLinkHostContext,
+  availability: FileLinkAvailability,
+  sessionId: string | undefined,
+  streaming: boolean,
+  children: ReactNode,
+): ReactNode {
+  return createElement(FileLinkProvider, { ctx, availability, sessionId, streaming, children })
+}

package/src/client/file-link.ts

@@ -0,0 +1,46 @@
+import { safeHref } from './genui-runtime/value-utils.ts'
+
+export interface ParsedFileLink {
+  path: string
+  line?: number
+}
+
+export type LinkTarget =
+  | { type: 'external'; href: string }
+  | { type: 'file'; file: ParsedFileLink }
+  | { type: 'invalid' }
+
+/** Decode a local file destination and its optional first line fragment. */
+export function parseFileLink(value: string): ParsedFileLink | undefined {
+  if (value.length > 2048) return undefined
+  const hash = value.indexOf('#')
+  const destination = hash < 0 ? value : value.slice(0, hash)
+  if (destination.includes('?')) return undefined
+
+  let path: string
+  try {
+    path = decodeURIComponent(destination)
+  } catch {
+    return undefined
+  }
+
+  if (path === '' || /[\u0000-\u001f\u007f]/.test(path) || /^[\\/]{2}/.test(path)
+    || (/^[a-z][a-z\d+.-]*:/i.test(path) && !/^[a-z]:[\\/]/i.test(path))) return undefined
+  if (hash < 0) return { path }
+
+  const match = /^L([1-9]\d*)(?:-L([1-9]\d*))?$/.exec(value.slice(hash + 1))
+  if (match === null) return undefined
+  const line = Number(match[1])
+  const end = match[2] === undefined ? line : Number(match[2])
+  if (!Number.isSafeInteger(line) || !Number.isSafeInteger(end) || end < line) return undefined
+  return { path, line }
+}
+
+/** Classify a link destination while preserving the existing external URL policy. */
+export function classifyLinkTarget(value: unknown): LinkTarget {
+  const external = safeHref(value)
+  if (external !== undefined) return { type: 'external', href: external }
+  if (typeof value !== 'string') return { type: 'invalid' }
+  const file = parseFileLink(value.trim())
+  return file === undefined ? { type: 'invalid' } : { type: 'file', file }
+}

package/src/client/guard.ts

@@ -33,7 +33,8 @@ import type { GenuiDiagnostic } from './genui-runtime/diagnostics.ts'
 import { GENUI_LIMITS } from './genui-runtime/limits.ts'
 import { analyzeSubmissionRegistry } from './submission-registry.ts'
 import { isTableDetailReachable, prepareTableRows, tableRowsForDetails } from './table-details.ts'
-import { color, enu, int, num, obj, opt, safeHref, safeMediaSrc, str } from './genui-runtime/value-utils.ts'
+import { color, enu, int, num, obj, opt, safeMediaSrc, str } from './genui-runtime/value-utils.ts'
+import { classifyLinkTarget } from './file-link.ts'
 
 /** Result of `validateGenuiSpec`. */
 export interface GenuiValidation {
@@ -336,7 +337,9 @@ function repairNodeFields(value: unknown, ctx: RepairCtx, depth: number): GenuiN
     case 'link': {
       const label = str(v.label, GENUI_LIMITS.maxString)
       if (label === undefined) return null
-      return { type: 'link', label, ...opt('href', safeHref(v.href)) }
+      const target = classifyLinkTarget(v.href)
+      const href = target.type === 'external' ? target.href : target.type === 'file' ? String(v.href).trim() : undefined
+      return { type: 'link', label, ...opt('href', href) }
     }
     case 'image': {
       const src = safeMediaSrc(v.src)