Frontend iframe renderer framework: 3D models, OpenAPI

eslint.config.ts

@@ -924,6 +924,7 @@ export default defineConfig([
   {
     ...playwright.configs['flat/recommended'],
     files: ['tests/e2e/**/*.test.ts'],
+    languageOptions: {globals: {...globals.nodeBuiltin, ...globals.browser}},
     rules: {
       ...playwright.configs['flat/recommended'].rules,
       'playwright/expect-expect': [0],

models/renderhelper/repo_file.go

@@ -50,8 +50,8 @@ type RepoFileOptions struct {
 	DeprecatedRepoName  string // it is only a patch for the non-standard "markup" api
 	DeprecatedOwnerName string // it is only a patch for the non-standard "markup" api
 
-	CurrentRefPath  string // eg: "branch/main"
-	CurrentTreePath string // eg: "path/to/file" in the repo
+	CurrentRefPath  string // eg: "branch/main", it is a sub URL path escaped by callers, TODO: rename to CurrentRefSubURL
+	CurrentTreePath string // eg: "path/to/file" in the repo, it is the tree path without URL path escaping
 }
 
 func NewRenderContextRepoFile(ctx context.Context, repo *repo_model.Repository, opts ...RepoFileOptions) *markup.RenderContext {
@@ -70,6 +70,10 @@ func NewRenderContextRepoFile(ctx context.Context, repo *repo_model.Repository,
 			"repo": helper.opts.DeprecatedRepoName,
 		})
 	}
+	// External render's iframe needs this to generate correct links
+	// TODO: maybe need to make it access "CurrentRefPath" directly (but impossible at the moment due to cycle-import)
+	// CurrentRefPath is already path-escaped by callers
+	rctx.RenderOptions.Metas["RefTypeNameSubURL"] = helper.opts.CurrentRefPath
 	rctx = rctx.WithHelper(helper).WithEnableHeadingIDGeneration(true)
 	return rctx
 }

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/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

routers/web/repo/render.go

@@ -43,7 +43,8 @@ func RenderFile(ctx *context.Context) {
 		CurrentRefPath:  ctx.Repo.RefTypeNameSubURL(),
 		CurrentTreePath: path.Dir(ctx.Repo.TreePath),
 	}).WithRelativePath(ctx.Repo.TreePath).WithStandalonePage(markup.StandalonePageOptions{
-		CurrentWebTheme: ctx.TemplateContext.CurrentWebTheme(),
+		CurrentWebTheme:   ctx.TemplateContext.CurrentWebTheme(),
+		RenderQueryString: ctx.Req.URL.RawQuery,
 	})
 	renderer, rendererInput, err := rctx.DetectMarkupRendererByReader(blobReader)
 	if err != nil {

routers/web/repo/view_file.go

@@ -21,6 +21,7 @@ import (
 	"code.gitea.io/gitea/modules/git/attribute"
 	"code.gitea.io/gitea/modules/highlight"
 	"code.gitea.io/gitea/modules/log"
+	"code.gitea.io/gitea/modules/markup"
 	"code.gitea.io/gitea/modules/setting"
 	"code.gitea.io/gitea/modules/util"
 	"code.gitea.io/gitea/services/context"
@@ -76,14 +77,17 @@ func handleFileViewRenderMarkup(ctx *context.Context, prefetchBuf []byte, utf8Re
 		return false
 	}
 
-	ctx.Data["MarkupType"] = rctx.RenderOptions.MarkupType
-
 	var err error
 	ctx.Data["EscapeStatus"], ctx.Data["FileContent"], err = markupRenderToHTML(ctx, rctx, renderer, utf8Reader)
 	if err != nil {
 		ctx.ServerError("Render", err)
 		return true
 	}
+
+	opts, ok := markup.GetExternalRendererOptions(renderer)
+	usingIframe := ok && opts.DisplayInIframe
+	ctx.Data["MarkupType"] = rctx.RenderOptions.MarkupType
+	ctx.Data["RenderAsMarkup"] = util.Iif(usingIframe, "markup-iframe", "markup-inplace")
 	return true
 }
 
@@ -235,8 +239,6 @@ func prepareFileView(ctx *context.Context, entry *git.TreeEntry) {
 	case fInfo.blobOrLfsSize >= setting.UI.MaxDisplayFileSize:
 		ctx.Data["IsFileTooLarge"] = true
 	case handleFileViewRenderMarkup(ctx, buf, contentReader):
-		// it also sets ctx.Data["FileContent"] and more
-		ctx.Data["IsMarkup"] = true
 	case handleFileViewRenderSource(ctx, attrs, fInfo, contentReader):
 		// it also sets ctx.Data["FileContent"] and more
 		ctx.Data["IsDisplayingSource"] = true