feat(gnoweb): built-in playground(2)

gno.land/adr/pr5421_integrated_playground.md

@@ -0,0 +1,125 @@
+# ADR: Integrated Playground, Eval, and Fork Views in gnoweb
+
+## Context
+
+gno.land previously had no interactive code evaluation in gnoweb. Users who
+wanted to call realm functions or experiment with Gno code had to use external
+tools (gnokey CLI, a separate gnostudio/studio app, or copy-paste workflows).
+
+The key problems:
+
+1. **Friction for exploration.** Reading a realm's `Render` output or calling
+   a view function required setting up a local environment or using CLI tools.
+2. **No in-browser eval.** Users could not quickly test expressions against a
+   deployed package from the web UI.
+3. **No code scratch pad.** There was nowhere in gnoweb to write and share
+   short Gno snippets.
+4. **Separate studio dependency.** The only interactive option required running
+   a separate application, breaking the single-binary model.
+
+## Decision
+
+Add three interactive features to gnoweb as Go-native, single-binary
+extensions with no additional runtime dependencies:
+
+### 1. `/_/play` — Playground scratch pad
+
+A multi-file code editor backed by a plain `<textarea>` (no CodeMirror yet).
+Supports:
+- URL sharing via `?code=` query parameter (base64-encoded)
+- Multi-file mode via `// --- filename.gno ---` separators
+- Fork-from-package via `?from=` query parameter
+- Tab addition/switching, keyboard shortcuts (Ctrl+Enter to run, Tab for indent)
+
+The "Run" button currently provides useful output for packages with `Render`
+by calling `/_/api/eval`. For scratch-pad code that has no on-chain package,
+it prints CLI instructions instead. This is intentional: the playground is a
+first step, not a full REPL.
+
+### 2. `?eval` on realm/package pages — Expression Evaluator
+
+Adds an "Eval" tab to the existing realm/package navigation. Renders:
+- A text input for arbitrary Gno expressions
+- A result pane updated via `POST /_/api/eval`
+- Quick-call buttons for exported, non-crossing, non-method functions
+- An expression history with re-run support
+
+The evaluator is read-only by design: only non-crossing functions are shown in
+Quick Call, and arbitrary expressions are limited to what `vm/qeval` allows
+(no state mutation).
+
+### 3. `?fork` on package/realm pages — Fork to Playground
+
+Loads all `.gno` source files from a package via the existing `ListFiles` +
+`File` client methods, concatenates them with `// --- filename.gno ---`
+separators, and redirects to the playground view pre-filled with that code.
+
+### API endpoints
+
+Two new JSON endpoints behind `/_/api/`:
+
+- `POST /_/api/eval` — Evaluates a `pkg_path` + `expression` pair via
+  `vm/qeval` ABCI query. Returns `{result}` or `{error}`.
+- `GET /_/api/funcs?path=...` — Returns exported, non-crossing functions for a
+  package using the existing `Doc()` client method. Used by the eval quick-call
+  buttons and (in future) playground-aware tooling.
+
+### Frontend approach
+
+Vanilla TypeScript compiled to plain JS (no React, no npm at runtime). Each
+feature is a standalone controller function loaded dynamically by the existing
+`data-controller` dispatch mechanism in `index.ts`. No new build tooling;
+compiled output is committed to `public/js/`.
+
+Cache busting is handled by extracting the `?v=` version suffix from
+`index.js`'s own `<script src>` URL and forwarding it to dynamic controller
+imports.
+
+### CSP update
+
+`connect-src` in the Content Security Policy was extended from just the remote
+ABCI endpoint to also include `'self'`, enabling the JS to call `/_/api/eval`
+and `/_/api/funcs` without CSP violations.
+
+## Alternatives Considered
+
+- **WebSocket REPL:** More interactive but much more complex server state.
+  Deferred to a later iteration.
+- **Server-side gno run / gno test:** Would require sandboxing, resource
+  limits, and execution isolation. Out of scope for this PR; instructions are
+  printed instead.
+- **CodeMirror editor:** Better UX but adds a non-trivial JS dependency.
+  Deferred; the `<textarea>` approach is functional and upgradeable in place.
+- **Separate gnostudio service:** Breaks the single-binary model. The goal is
+  to keep gnoweb self-contained.
+- **Stimulus.js or other controller framework:** The codebase already has a
+  minimal controller dispatch in `index.ts`. Keeping new controllers as
+  standalone functions avoids framework coupling.
+
+## Consequences
+
+- **Positive:** Users can evaluate read-only realm expressions from the
+  browser without any local tooling.
+- **Positive:** Developers can fork any package's source into the playground
+  with one click.
+- **Positive:** Zero new runtime dependencies; gnoweb stays a single binary.
+- **Positive:** The `/_/api/eval` and `/_/api/funcs` endpoints form a stable
+  base for future tooling (IDE integrations, CLI helpers, etc.).
+- **Trade-off:** The playground cannot execute scratch-pad code that isn't
+  deployed on-chain. This is acceptable for an initial iteration; the UI
+  prints CLI instructions to bridge the gap.
+- **Trade-off:** No rate-limiting or sandboxing on `/_/api/eval`. Acceptable
+  for a dev/exploration tool; should be addressed before exposing this to
+  mainnet at scale.
+- **Trade-off:** Compiled JS is committed to the repo. This is consistent with
+  the existing gnoweb frontend approach.
+
+## Not Yet Implemented
+
+- CodeMirror syntax highlighting and editor features
+- Server-side `gno run` / `gno test` execution with sandboxing
+- WebSocket REPL
+- Wallet integration (signing transactions from playground)
+- gnodev hot-reload integration
+- Rate limiting / abuse prevention on eval API
+- Full test coverage for playground handler (current patch coverage ~16%)

gno.land/cmd/gnoweb/main.go

@@ -92,7 +92,8 @@ Environment variables:
 			}
 
 			return run()
-		})
+		},
+	)
 
 	cmd.Execute(context.Background(), os.Args[1:])
 }

gno.land/cmd/gnoweb/main_test.go

@@ -107,10 +107,9 @@ func TestSecureHeadersMiddlewareStrict(t *testing.T) {
 	if !strings.Contains(csp, "https://assets.gnoteam.com") {
 		t.Errorf("Expected Content-Security-Policy to contain 'https://assets.gnoteam.com', got '%s'", csp)
 	}
-	// The search dropdown fetches the same-origin /search.json, so connect-src
-	// must allow 'self' in addition to the RPC node.
-	if !strings.Contains(csp, "connect-src 'self' http://example.com/abci_query") {
-		t.Errorf("Expected Content-Security-Policy connect-src to contain 'self' and the RPC node, got '%s'", csp)
+	// The search dropdown fetches the same-origin /search.json, so connect-src must allow 'self'.
+	if !strings.Contains(csp, "connect-src 'self'") {
+		t.Errorf("Expected Content-Security-Policy connect-src to contain 'self', got '%s'", csp)
 	}
 	if res.Header.Get("Strict-Transport-Security") != "max-age=31536000" {
 		t.Errorf("Expected Strict-Transport-Security 'max-age=31536000', got '%s'", res.Header.Get("Strict-Transport-Security"))

gno.land/pkg/gnoweb/Makefile

@@ -21,8 +21,8 @@ biome := $(node_modules)/.bin/biome
 css_config_path := frontend/css/main.css
 
 # main css config — includes per-feature CSS pulled into the Cube CSS Block
-# layer via @import from frontend/css/06-blocks.css (postcss-import resolves
-# at compile time, so the final bundle and layer order are unchanged).
+# layer via @import from frontend/css/main.css (postcss-import resolves at
+# compile time, so the final bundle and layer order are unchanged).
 main_css_files := $(shell find frontend/css feature -name '*.css' 2>/dev/null)
 output_maincss := $(PUBLIC_DIR)/main.css
 
@@ -53,10 +53,16 @@ shared_js := $(src_dir_js)/controller.ts
 controller_js := $(filter-out $(shared_js),$(input_js))
 # Flatten: any .ts (legacy or feature) → $(out_dir_js)/<basename>.js.
 output_js := $(addprefix $(out_dir_js)/,$(patsubst %.ts,%.js,$(notdir $(input_js))))
-# Tell make where to look for .ts sources so the %.js pattern rule
-# below resolves both legacy and feature-local controllers.
+# Tell make where to look for .ts sources so the %.js pattern rule below
+# resolves both legacy and feature-local controllers.
 vpath %.ts $(src_dir_js) $(shell find feature -path 'feature/*/frontend' -type d 2>/dev/null)
 
+# Alias so controllers outside frontend/js/ (per-feature controllers under
+# feature/<name>/frontend/) can import shared modules as @gnoweb/js/... instead
+# of brittle ../../../frontend/js/ relative paths. Resolved relative to esbuild's
+# working directory (this Makefile's dir).
+esbuild_alias := --alias:@gnoweb/js=./frontend/js
+
 # cache
 cache_dir := .cache
 
@@ -106,7 +112,7 @@ node_path := $(node_modules)
 ts: $(esbuild) $(output_js)
 # Build shared chunk first (always loaded)
 $(out_dir_js)/controller.js: $(shared_js) $(esbuild)
-	NODE_ENV=production NODE_PATH=$(node_path) $(esbuild) $< --log-level=error --bundle --outfile=$@ --format=esm --minify
+	NODE_ENV=production NODE_PATH=$(node_path) $(esbuild) $< --log-level=error --bundle --outfile=$@ --format=esm --minify $(esbuild_alias)
 
 # sa-bootstrap is loaded as a synchronous classic <script src=...> so it blocks
 # parsing until executed and guarantees window.sa_metadata is set before SA's
@@ -118,7 +124,7 @@ $(out_dir_js)/sa-bootstrap.js: $(src_dir_js)/sa-bootstrap.ts $(esbuild)
 # prerequisite lets `vpath` resolve sources from frontend/js/ OR from
 # feature/<name>/frontend/ (set above). $< is the path Make found.
 $(out_dir_js)/%.js: %.ts $(out_dir_js)/controller.js
-	NODE_ENV=production NODE_PATH=$(node_path) $(esbuild) $< --log-level=error --bundle --outdir=$(out_dir_js) --format=esm --define:process.env.NODE_ENV="\"production\"" --minify --external:./controller.js
+	NODE_ENV=production NODE_PATH=$(node_path) $(esbuild) $< --log-level=error --bundle --outdir=$(out_dir_js) --format=esm --define:process.env.NODE_ENV="\"production\"" --minify --external:./controller.js $(esbuild_alias)
 
 # Rule to copy static files while preserving directory structure
 static: $(output_static)
@@ -152,7 +158,7 @@ dev.maincss: generate | $(PUBLIC_DIR)
 
 # TS in development mode
 dev.ts: $(esbuild) generate | $(PUBLIC_DIR)
-	NODE_ENV=development NODE_PATH=$(node_path) $(esbuild) $(input_js) --bundle --outdir=$(out_dir_js) --sourcemap --format=esm --watch \
+	NODE_ENV=development NODE_PATH=$(node_path) $(esbuild) $(input_js) --bundle --outdir=$(out_dir_js) --sourcemap --format=esm --watch $(esbuild_alias) \
 		2>&1 | $(logname) esbuild
 
 # Install node modules deps located in ./tools

gno.land/pkg/gnoweb/app.go

@@ -203,6 +203,10 @@ func NewRouter(logger *slog.Logger, cfg *AppConfig) (http.Handler, error) {
 	assetsHandler := cacheAssetHandler(AssetHandler())
 	mux.Handle(assetsBase, http.StripPrefix(assetsBase, assetsHandler))
 
+	// Handle playground API endpoints
+	mux.Handle("/_/api/eval", httphandler.Playground.EvalHandler())
+	mux.Handle("/_/api/funcs", httphandler.Playground.FuncsHandler())
+
 	// Handle status page
 	mux.Handle("/status.json", handlerStatusJSON(logger, rpcclient))
 

gno.land/pkg/gnoweb/client.go

@@ -92,6 +92,10 @@ type ClientAdapter interface {
 	// any positive value pins the query to that historical height.
 	Doc(ctx context.Context, path string, height int64) (*doc.JSONDocumentation, error)
 
+	// Eval evaluates a Gno expression via vm/qeval query.
+	// The data string should be in the format "gno.land/r/pkg.Expression(args)".
+	Eval(ctx context.Context, data string) ([]byte, error)
+
 	// StatePkg retrieves the root state tree for a package. `height
 	// = 0` queries the latest block; positive values are forwarded
 	// to ABCI as-is.
@@ -233,6 +237,12 @@ func (c *rpcClient) Doc(ctx context.Context, pkgPath string, height int64) (*doc
 	return jdoc, nil
 }
 
+// Eval evaluates a Gno expression via the vm/qeval ABCI query.
+func (c *rpcClient) Eval(ctx context.Context, data string) ([]byte, error) {
+	const qpath = "vm/qeval"
+	return c.query(ctx, qpath, []byte(data), 0)
+}
+
 // StatePkg retrieves root state tree for a package via vm/qpkg_json.
 // `height = 0` queries the latest block.
 func (c *rpcClient) StatePkg(ctx context.Context, path string, height int64) ([]byte, error) {

gno.land/pkg/gnoweb/client_mock.go

@@ -14,6 +14,8 @@ import (
 type MockPackage struct {
 	Path      string
 	Domain    string
+	Remote    string
+	ChainId   string
 	Files     map[string]string // filename -> body
 	Functions []*doc.JSONFunc
 }
@@ -138,6 +140,11 @@ func (m *MockClient) Doc(ctx context.Context, path string, _ int64) (*doc.JSONDo
 	return &doc.JSONDocumentation{Funcs: pkg.Functions}, nil
 }
 
+// Eval evaluates a Gno expression (mock implementation).
+func (m *MockClient) Eval(_ context.Context, data string) ([]byte, error) {
+	return []byte("(mock eval: " + data + ")"), nil
+}
+
 // StatePkg returns mock package state data for testing.
 func (m *MockClient) StatePkg(_ context.Context, path string, _ int64) ([]byte, error) {
 	_, exists := m.Packages[path]

gno.land/pkg/gnoweb/components/layout_header.go

@@ -42,10 +42,12 @@ func StaticHeaderGeneralLinks() []HeaderLink {
 }
 
 func StaticHeaderDevLinks(u weburl.GnoURL, mode ViewMode, static bool) []HeaderLink {
-	contentURL, sourceURL, helpURL, stateURL := u, u, u, u
+	contentURL, sourceURL, helpURL, forkURL, runURL, stateURL := u, u, u, u, u, u
 	contentURL.WebQuery = url.Values{}
 	sourceURL.WebQuery = url.Values{"source": {""}}
 	helpURL.WebQuery = url.Values{"help": {""}}
+	forkURL.WebQuery = url.Values{"fork": {""}}
+	runURL.WebQuery = url.Values{"run": {""}}
 	stateURL.WebQuery = url.Values{"state": {""}}
 
 	contentLink := HeaderLink{
@@ -69,6 +71,20 @@ func StaticHeaderDevLinks(u weburl.GnoURL, mode ViewMode, static bool) []HeaderL
 		IsActive: isActive(u.WebQuery, "Actions"),
 	}
 
+	forkLink := HeaderLink{
+		Label:    "Fork",
+		URL:      forkURL.EncodeWebURL(),
+		Icon:     "ico-link",
+		IsActive: isActive(u.WebQuery, "Fork"),
+	}
+
+	runLink := HeaderLink{
+		Label:    "Run",
+		URL:      runURL.EncodeWebURL(),
+		Icon:     "ico-tx-link",
+		IsActive: isActive(u.WebQuery, "Run"),
+	}
+
 	stateLink := HeaderLink{
 		Label:    "State",
 		URL:      stateURL.EncodeWebURL(),
@@ -84,9 +100,11 @@ func StaticHeaderDevLinks(u weburl.GnoURL, mode ViewMode, static bool) []HeaderL
 	case mode == ViewModeUser:
 		return []HeaderLink{contentLink}
 	case mode == ViewModePackage:
-		return []HeaderLink{contentLink, sourceLink}
+		return []HeaderLink{contentLink, sourceLink, forkLink}
+	case mode == ViewModePlayground:
+		return []HeaderLink{}
 	default:
-		return []HeaderLink{contentLink, stateLink, sourceLink, actionsLink}
+		return []HeaderLink{contentLink, stateLink, sourceLink, actionsLink, forkLink, runLink}
 	}
 }
 
@@ -105,13 +123,17 @@ func EnrichHeaderData(data HeaderData, mode ViewMode) HeaderData {
 func isActive(webQuery url.Values, label string) bool {
 	switch label {
 	case "Content":
-		return !webQuery.Has("source") && !webQuery.Has("help") && !webQuery.Has("state")
+		return !webQuery.Has("source") && !webQuery.Has("help") && !webQuery.Has("fork") && !webQuery.Has("run") && !webQuery.Has("state")
 	case "State":
 		return webQuery.Has("state")
 	case "Source":
 		return webQuery.Has("source")
 	case "Actions":
 		return webQuery.Has("help")
+	case "Fork":
+		return webQuery.Has("fork")
+	case "Run":
+		return webQuery.Has("run")
 	default:
 		return false
 	}

gno.land/pkg/gnoweb/components/layout_index.go

@@ -17,19 +17,21 @@ import (
 type ViewMode int
 
 const (
-	ViewModeExplorer ViewMode = iota // For exploring packages and paths
-	ViewModeRealm                    // For realm content display
-	ViewModePackage                  // For package content display
-	ViewModeHome                     // For home page display
-	ViewModeUser                     // For user page display
+	ViewModeExplorer   ViewMode = iota // For exploring packages and paths
+	ViewModeRealm                      // For realm content display
+	ViewModePackage                    // For package content display
+	ViewModeHome                       // For home page display
+	ViewModeUser                       // For user page display
+	ViewModePlayground                 // For playground display
 )
 
 // View mode predicates
-func (m ViewMode) IsExplorer() bool { return m == ViewModeExplorer }
-func (m ViewMode) IsRealm() bool    { return m == ViewModeRealm }
-func (m ViewMode) IsPackage() bool  { return m == ViewModePackage }
-func (m ViewMode) IsUser() bool     { return m == ViewModeUser }
-func (m ViewMode) IsHome() bool     { return m == ViewModeHome }
+func (m ViewMode) IsExplorer() bool   { return m == ViewModeExplorer }
+func (m ViewMode) IsRealm() bool      { return m == ViewModeRealm }
+func (m ViewMode) IsPackage() bool    { return m == ViewModePackage }
+func (m ViewMode) IsUser() bool       { return m == ViewModeUser }
+func (m ViewMode) IsHome() bool       { return m == ViewModeHome }
+func (m ViewMode) IsPlayground() bool { return m == ViewModePlayground }
 
 // ShouldShowDevTools returns whether dev tools should be shown for this mode
 func (m ViewMode) ShouldShowDevTools() bool {
@@ -196,7 +198,7 @@ func IndexLayout(data IndexData) Component {
 
 	// Set dev mode based on view type and mode
 	switch data.BodyView.Type {
-	case HelpViewType, SourceViewType, DirectoryViewType, StatusViewType, StateViewType:
+	case HelpViewType, SourceViewType, DirectoryViewType, StatusViewType, StateViewType, PlaygroundViewType, RunViewType:
 		dataLayout.IsDevmodView = true
 	}