Frontend iframe renderer framework: 3D models, OpenAPI (#37233)

Introduces a frontend external-render framework that runs renderer
plugins inside an `iframe` (loaded via `srcdoc` to keep the CSP
`sandbox` directive working without origin-related console noise), and
migrates the 3D viewer and OpenAPI/Swagger renderers onto it. PDF and
asciicast paths are refactored to share the same `data-render-name`
mechanism.

Adds e2e coverage for 3D, PDF, asciicast and OpenAPI render paths, plus
a regression for the `RefTypeNameSubURL` double-escape on non-ASCII
branch names.

Signed-off-by: silverwind <me@silverwind.io>
Co-authored-by: Claude (Opus 4.6) <noreply@anthropic.com>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

modules/markup/external/external.go

@@ -21,7 +21,33 @@ import (
 
 // RegisterRenderers registers all supported third part renderers according settings
 func RegisterRenderers() {
-	markup.RegisterRenderer(&openAPIRenderer{})
+	markup.RegisterRenderer(&frontendRenderer{
+		name: "openapi-swagger",
+		patterns: []string{
+			"openapi.yaml",
+			"openapi.yml",
+			"openapi.json",
+			"swagger.yaml",
+			"swagger.yml",
+			"swagger.json",
+		},
+	})
+
+	markup.RegisterRenderer(&frontendRenderer{
+		name: "viewer-3d",
+		patterns: []string{
+			// It needs more logic to make it overall right (render a text 3D model automatically):
+			// we need to distinguish the ambiguous filename extensions.
+			// For example: "*.amf, *.obj, *.off, *.step" might be or not be a 3D model file.
+			// So when it is a text file, we can't assume that "we only render it by 3D plugin",
+			// otherwise the end users would be impossible to view its real content when the file is not a 3D model.
+			"*.3dm", "*.3ds", "*.3mf", "*.amf", "*.bim", "*.brep",
+			"*.dae", "*.fbx", "*.fcstd", "*.glb", "*.gltf",
+			"*.ifc", "*.igs", "*.iges", "*.stp", "*.step",
+			"*.stl", "*.obj", "*.off", "*.ply", "*.wrl",
+		},
+	})
+
 	for _, renderer := range setting.ExternalMarkupRenderers {
 		markup.RegisterRenderer(&Renderer{renderer})
 	}

modules/markup/external/frontend.go

@@ -0,0 +1,95 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package external
+
+import (
+	"encoding/base64"
+	"io"
+	"unicode/utf8"
+
+	"code.gitea.io/gitea/modules/htmlutil"
+	"code.gitea.io/gitea/modules/markup"
+	"code.gitea.io/gitea/modules/public"
+	"code.gitea.io/gitea/modules/setting"
+	"code.gitea.io/gitea/modules/util"
+)
+
+type frontendRenderer struct {
+	name     string
+	patterns []string
+}
+
+var (
+	_ markup.PostProcessRenderer = (*frontendRenderer)(nil)
+	_ markup.ExternalRenderer    = (*frontendRenderer)(nil)
+)
+
+func (p *frontendRenderer) Name() string {
+	return p.name
+}
+
+func (p *frontendRenderer) NeedPostProcess() bool {
+	return false
+}
+
+func (p *frontendRenderer) FileNamePatterns() []string {
+	// TODO: the file extensions are ambiguous, even if the file name matches, it doesn't mean that the file is a 3D model
+	// There are some approaches to make it more accurate, but they are all complicated:
+	// A. Make backend know everything (detect a file is a 3D model or not)
+	// B. Let frontend renders to try render one by one
+	//
+	// If there would be more frontend renders in the future, we need to implement the "frontend" approach:
+	// 1. Make backend or parent window collect the supported extensions of frontend renders (done: backend external render framework)
+	// 2. If the current file matches any extension, start the general iframe embedded render (done: this renderer)
+	// 3. The iframe window calls the frontend renders one by one (done: frontend external render)
+	// 4. Report the render result to parent by postMessage (TODO: when needed)
+	return p.patterns
+}
+
+func (p *frontendRenderer) SanitizerRules() []setting.MarkupSanitizerRule {
+	return nil
+}
+
+func (p *frontendRenderer) GetExternalRendererOptions() (ret markup.ExternalRendererOptions) {
+	ret.SanitizerDisabled = true
+	ret.DisplayInIframe = true
+	ret.ContentSandbox = "allow-scripts allow-forms allow-modals allow-popups allow-downloads"
+	return ret
+}
+
+func (p *frontendRenderer) Render(ctx *markup.RenderContext, input io.Reader, output io.Writer) error {
+	if ctx.RenderOptions.StandalonePageOptions == nil {
+		opts := p.GetExternalRendererOptions()
+		return markup.RenderIFrame(ctx, &opts, output)
+	}
+
+	content, err := util.ReadWithLimit(input, int(setting.UI.MaxDisplayFileSize))
+	if err != nil {
+		return err
+	}
+
+	contentEncoding, contentString := "text", util.UnsafeBytesToString(content)
+	if !utf8.Valid(content) {
+		contentEncoding = "base64"
+		contentString = base64.StdEncoding.EncodeToString(content)
+	}
+
+	_, err = htmlutil.HTMLPrintf(output,
+		`<!DOCTYPE html>
+<html>
+<head>
+	<!-- external-render-helper will be injected here by the markup render -->
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+</head>
+<body>
+	<div id="frontend-render-viewer" data-frontend-renders="%s" data-file-tree-path="%s"></div>
+	<textarea id="frontend-render-data" data-content-encoding="%s" hidden>%s</textarea>
+	<script nonce type="module" src="%s"></script>
+</body>
+</html>`,
+		p.name, ctx.RenderOptions.RelativePath,
+		contentEncoding, contentString,
+		public.AssetURI("js/external-render-frontend.js"))
+	return err
+}

modules/markup/external/openapi.go

@@ -1,84 +0,0 @@
-// Copyright 2026 The Gitea Authors. All rights reserved.
-// SPDX-License-Identifier: MIT
-
-package external
-
-import (
-	"fmt"
-	"html"
-	"io"
-
-	"code.gitea.io/gitea/modules/markup"
-	"code.gitea.io/gitea/modules/public"
-	"code.gitea.io/gitea/modules/setting"
-	"code.gitea.io/gitea/modules/util"
-)
-
-type openAPIRenderer struct{}
-
-var (
-	_ markup.PostProcessRenderer = (*openAPIRenderer)(nil)
-	_ markup.ExternalRenderer    = (*openAPIRenderer)(nil)
-)
-
-func (p *openAPIRenderer) Name() string {
-	return "openapi"
-}
-
-func (p *openAPIRenderer) NeedPostProcess() bool {
-	return false
-}
-
-func (p *openAPIRenderer) FileNamePatterns() []string {
-	return []string{
-		"openapi.yaml",
-		"openapi.yml",
-		"openapi.json",
-		"swagger.yaml",
-		"swagger.yml",
-		"swagger.json",
-	}
-}
-
-func (p *openAPIRenderer) SanitizerRules() []setting.MarkupSanitizerRule {
-	return nil
-}
-
-func (p *openAPIRenderer) GetExternalRendererOptions() (ret markup.ExternalRendererOptions) {
-	ret.SanitizerDisabled = true
-	ret.DisplayInIframe = true
-	ret.ContentSandbox = "allow-scripts allow-forms allow-modals allow-popups allow-downloads"
-	return ret
-}
-
-func (p *openAPIRenderer) Render(ctx *markup.RenderContext, input io.Reader, output io.Writer) error {
-	if ctx.RenderOptions.StandalonePageOptions == nil {
-		opts := p.GetExternalRendererOptions()
-		return markup.RenderIFrame(ctx, &opts, output)
-	}
-
-	content, err := util.ReadWithLimit(input, int(setting.UI.MaxDisplayFileSize))
-	if err != nil {
-		return err
-	}
-
-	// HINT: SWAGGER-OPENAPI-VIEWER: another place "templates/swagger/openapi-viewer.tmpl"
-	_, err = io.WriteString(output, fmt.Sprintf(
-		`<!DOCTYPE html>
-<html>
-<head>
-	<meta name="viewport" content="width=device-width, initial-scale=1">
-	<link rel="stylesheet" href="%s">
-</head>
-<body>
-	<div id="swagger-ui"><textarea class="swagger-spec-content" data-spec-filename="%s">%s</textarea></div>
-	<script nonce type="module" src="%s"></script>
-</body>
-</html>`,
-		public.AssetURI("css/swagger.css"),
-		html.EscapeString(ctx.RenderOptions.RelativePath),
-		html.EscapeString(util.UnsafeBytesToString(content)),
-		public.AssetURI("js/swagger.js"),
-	))
-	return err
-}

modules/markup/render.go

@@ -6,6 +6,7 @@ package markup
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"html/template"
 	"io"
@@ -43,7 +44,8 @@ type WebThemeInterface interface {
 }
 
 type StandalonePageOptions struct {
-	CurrentWebTheme WebThemeInterface
+	CurrentWebTheme   WebThemeInterface
+	RenderQueryString string
 }
 
 type RenderOptions struct {
@@ -206,17 +208,23 @@ func RenderString(ctx *RenderContext, content string) (string, error) {
 }
 
 func RenderIFrame(ctx *RenderContext, opts *ExternalRendererOptions, output io.Writer) error {
+	ownerName, repoName := ctx.RenderOptions.Metas["user"], ctx.RenderOptions.Metas["repo"]
+	refSubURL := ctx.RenderOptions.Metas["RefTypeNameSubURL"]
+	if ownerName == "" || repoName == "" || refSubURL == "" {
+		setting.PanicInDevOrTesting("RenderIFrame requires user, repo and RefTypeNameSubURL metas")
+		return errors.New("RenderIFrame requires user, repo and RefTypeNameSubURL metas")
+	}
 	src := fmt.Sprintf("%s/%s/%s/render/%s/%s", setting.AppSubURL,
-		url.PathEscape(ctx.RenderOptions.Metas["user"]),
-		url.PathEscape(ctx.RenderOptions.Metas["repo"]),
-		util.PathEscapeSegments(ctx.RenderOptions.Metas["RefTypeNameSubURL"]),
+		url.PathEscape(ownerName),
+		url.PathEscape(repoName),
+		ctx.RenderOptions.Metas["RefTypeNameSubURL"],
 		util.PathEscapeSegments(ctx.RenderOptions.RelativePath),
 	)
 	var extraAttrs template.HTML
 	if opts.ContentSandbox != "" {
 		extraAttrs = htmlutil.HTMLFormat(` sandbox="%s"`, opts.ContentSandbox)
 	}
-	_, err := htmlutil.HTMLPrintf(output, `<iframe data-src="%s" class="external-render-iframe"%s></iframe>`, src, extraAttrs)
+	_, err := htmlutil.HTMLPrintf(output, `<iframe data-src="%s" data-global-init="initExternalRenderIframe" class="external-render-iframe"%s></iframe>`, src, extraAttrs)
 	return err
 }
 
@@ -228,7 +236,7 @@ func pipes() (io.ReadCloser, io.WriteCloser, func()) {
 	}
 }
 
-func getExternalRendererOptions(renderer Renderer) (ret ExternalRendererOptions, _ bool) {
+func GetExternalRendererOptions(renderer Renderer) (ret ExternalRendererOptions, _ bool) {
 	if externalRender, ok := renderer.(ExternalRenderer); ok {
 		return externalRender.GetExternalRendererOptions(), true
 	}
@@ -237,7 +245,7 @@ func getExternalRendererOptions(renderer Renderer) (ret ExternalRendererOptions,
 
 func RenderWithRenderer(ctx *RenderContext, renderer Renderer, input io.Reader, output io.Writer) error {
 	var extraHeadHTML template.HTML
-	if extOpts, ok := getExternalRendererOptions(renderer); ok && extOpts.DisplayInIframe {
+	if extOpts, ok := GetExternalRendererOptions(renderer); ok && extOpts.DisplayInIframe {
 		if ctx.RenderOptions.StandalonePageOptions == nil {
 			// for an external "DisplayInIFrame" render, it could only output its content in a standalone page
 			// otherwise, a <iframe> should be outputted to embed the external rendered page
@@ -248,7 +256,12 @@ func RenderWithRenderer(ctx *RenderContext, renderer Renderer, input io.Reader,
 		extraLinkHref := ctx.RenderOptions.StandalonePageOptions.CurrentWebTheme.PublicAssetURI()
 		// "<script>" must go before "<link>", to make Golang's http.DetectContentType() can still recognize the content as "text/html"
 		// DO NOT use "type=module", the script must run as early as possible, to set up the environment in the iframe
-		extraHeadHTML = htmlutil.HTMLFormat(`<script nonce crossorigin src="%s"></script><link rel="stylesheet" href="%s">`, extraScriptSrc, extraLinkHref)
+		extraHeadHTML = htmlutil.HTMLFormat(
+			`<script nonce crossorigin src="%s" id="gitea-external-render-helper" data-render-query-string="%s"></script>`+
+				`<link rel="stylesheet" href="%s">`,
+			extraScriptSrc, ctx.RenderOptions.StandalonePageOptions.RenderQueryString,
+			extraLinkHref,
+		)
 	}
 
 	ctx.usedByRender = true

modules/markup/render_test.go

@@ -24,8 +24,8 @@ func TestRenderIFrame(t *testing.T) {
 
 	// the value is read from config RENDER_CONTENT_SANDBOX, empty means "disabled"
 	ret := render(ctx, ExternalRendererOptions{ContentSandbox: ""})
-	assert.Equal(t, `<iframe data-src="/test-owner/test-repo/render/src/branch/master/tree-path" class="external-render-iframe"></iframe>`, ret)
+	assert.Equal(t, `<iframe data-src="/test-owner/test-repo/render/src/branch/master/tree-path" data-global-init="initExternalRenderIframe" class="external-render-iframe"></iframe>`, ret)
 
 	ret = render(ctx, ExternalRendererOptions{ContentSandbox: "allow"})
-	assert.Equal(t, `<iframe data-src="/test-owner/test-repo/render/src/branch/master/tree-path" class="external-render-iframe" sandbox="allow"></iframe>`, ret)
+	assert.Equal(t, `<iframe data-src="/test-owner/test-repo/render/src/branch/master/tree-path" data-global-init="initExternalRenderIframe" class="external-render-iframe" sandbox="allow"></iframe>`, ret)
 }

modules/public/manifest.go

@@ -56,6 +56,8 @@ func parseManifest(data []byte) (map[string]string, map[string]string) {
 		paths[key] = entry.File
 		names[entry.File] = entry.Name
 		// Map associated CSS files, e.g. "css/index.css" -> "css/index.B3zrQPqD.css"
+		// FIXME: INCORRECT-VITE-MANIFEST-PARSER: the logic is wrong, Vite manifest doesn't work this way
+		// It just happens to be correct for the current modules dependencies
 		for _, css := range entry.CSS {
 			cssKey := path.Dir(css) + "/" + entry.Name + path.Ext(css)
 			paths[cssKey] = css