mosaic

README

README

About

This is the tapestry GUI. It uses Wails to provide a native webbrowser in a window managed by go.

Details

The app supports three modes: ext, dev, and production. The first two rely on Vite to serve assets.

Ext : Use your local web browser to interact with the app. For simplicity's sake, while built into the application, Wails isn't used. The app can be built and run with no special tags.

Dev : Uses wails' "embedded" browser to interact with the app. The app must be built with the "dev" tag. ( ie. go build -tags dev ) Wails normally has its own web server in this mode, but it's disabled so everything can route through the same code used by "web".

Production : Uses wail's browser to interact with pre-built content. all assets get built into the go app, except for story files which are read/written to by the app. The "production" and "desktop" tags are required, as are several linker options. ( -w -s -H windowsgui ). Wails would normally serve the embedded assets, however Tapestry routes everything through the same multiplexer used for web and dev returning the embedded assets manually.

Tapestry doesn't currently expose a javascript api for the wails window.

running web and dev

after building the app, in the www directory:

npm run dev

building production

in the www directory:

npm run build

in the cmd/tap directory, either:

go build -tags desktop,production -ldflags "-w -s -H windowsgui"

or

wails build -s -noPackage

( ^ requires the wails build system to be installed: ex. go install github.com/wailsapp/wails/v2/cmd/wails@v2.4.0 )

Compiler options

build tags : control which version of the source code gets built:

• "dev": activates the wails browser and launches its dev server.
• "debug": activates the console for production builds.
• "bindings": appears to create an app capable of building the go <-> js bindings.
• "production": switches off the wails and tapestry servers; embeds wails and tapestry assets.
• "desktop": embeds a prebuilt, minified version of the wails runtime for logging, events, native window controls, etc.

gcflags : controls the go compiler. the specified options make debugging with delve ( ex. in visual studio code ) easier:

• all: apply the options to all packages.
• -l: no inlined functions.
• -N: disable optimizations.

ldflags : controls the linker.

• -w: Omit the DWARF symbol table.
• -s: Omit the symbol table and debug information.
• -H windowsgui writes a "GUI binary" ( instead of a 'console binary' )

Overview

================================== DEV MODE ===============================================

USER +-> [wails webkit](http://wails.localhost)
               +
               |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ WEB & DEV MODES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
               +
               |
USER +-> [tapestry server](http://localhost:8080)
               |
             <mux> +--> (unknown url?) +--> npm+vite:3000 +--------->+
               |                                                     |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ALL MODES  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
               +                                                     +
               |                                                     |
     { tapestry backend }                                  { tapestry frontend  }
    ............................................    ....................................
    .  /stories/ ----> [ Documents: .if/db ]   .    .   /www/index.html                .
    .  /ramble/  ----> take turns              .    .   /www/mosaic/.vue, .js, .css    .
    .  /blocks/  ----> blocks from .if file    .    .   /www/ramble/.vue, .js, .css    .
    .  /shapes/  ----> blockly definitions     .    .   /www/assets/.png, .etc         .
    ............................................    ....................................
               |                                                     |
               +                                                     +
================================== PRODUCTION MODE ========================================
               |                                                     |
             <mux> +-----> (unknown url?) +----->        package tapestry/www
               |                                    embedded assets built by vite cli
               +                                          served by http.FileServer
          AssetsHandler
               |
               +
            Assets +------>❌ wails treats all requests as files, then falls back to AssetsHandler if unhandled.
               |                Tapestry always returns "file not found" to delegate everything to the handler.
               +
USER +->  [wails webkit](http://wails.localhost)

==========================================================================================

Documentation

Overview

Package mosaic transforms http requests into tapestry actions. For example: loading, displaying, editing, or playing a story file.

Index

• Constants
• Variables
• func ActionsApi(opt *Config, ws *Workspace) web.Resource
• func BoxesApi(*Config) web.Resource
• func FilesApi(cfg *Config) web.Resource
• func HandleCommands(cfg *Config) http.HandlerFunc
• func ShapesApi(*Config) web.Resource
• type Config
  • func Configure(cmdDir, dataDir string) *Config
  • func (cfg *Config) Cmd(which string) string
  • func (cfg *Config) PathTo(parts ...string) string
  • func (cfg *Config) Scratch(parts ...string) string
  • func (cfg *Config) Stories() string
• type ErrFS
  • func (f ErrFS) Open(name string) (fs.File, error)
  • func (f ErrFS) Stat(name string) (ret fs.FileInfo, err error)
• type Folder
  • func (f Folder) GetFolder() (ret string, err error)
  • func (f *Folder) Set(s string) (err error)
  • func (f Folder) String() (ret string)
• type Workspace
  • func (ws *Workspace) Startup(ctx context.Context)

Constants

const (
	// expects the npm vite server in the www directory is running.
	Web buildConfig = iota
	// expects the npm vite server in the www directory is running.
	Dev
	// expects the www assets have (already) been built into the www/dist directory.
	Prod
)

const BuildConfig = Web

Variables

var Frontend fs.FS

In prod, this points to the www/dist directory; otherwise its nil.

Functions

func ActionsApi

func ActionsApi(opt *Config, ws *Workspace) web.Resource

func BoxesApi

func BoxesApi(*Config) web.Resource

return the blockly toolbox specs on GET

func FilesApi

func FilesApi(cfg *Config) web.Resource

func HandleCommands

func HandleCommands(cfg *Config) http.HandlerFunc

allows posts to / of specific predetermined commands ( in json )

func ShapesApi

func ShapesApi(*Config) web.Resource

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config contains paths to the standalone console utils.

func Configure

func Configure(cmdDir, dataDir string) *Config

Configure creates a reasonable(?) config based on the developer go path.

func (*Config) Cmd

func (cfg *Config) Cmd(which string) string

Rather than creating one big app, for now, tapestry is split into a bunch of separate commands.

func (*Config) PathTo

func (cfg *Config) PathTo(parts ...string) string

func (*Config) Scratch

func (cfg *Config) Scratch(parts ...string) string

func (*Config) Stories

func (cfg *Config) Stories() string

type ErrFS

type ErrFS struct{}

wails serves urls *after* it serves files which is the opposite order than makese sense for tapestry. [ we know the url endpoints we want, and that's a *much* smaller set than actual assets ]

func (ErrFS) Open

func (f ErrFS) Open(name string) (fs.File, error)

func (ErrFS) Stat

func (f ErrFS) Stat(name string) (ret fs.FileInfo, err error)

wails uses Stat as part of NewAssetHandler's search to find an index.html it starts by just trying to stat it, and if that fails then uses walks using ReadDir and SubFS to pin that as the root. we cut it out as early as we can.

type Folder

type Folder string

implements the flag.Value interface for locating the author's stories.

func (Folder) GetFolder

func (f Folder) GetFolder() (ret string, err error)

turn the requested directory into the real thing if nothing specified, try the user's documents folder

func (*Folder) Set

func (f *Folder) Set(s string) (err error)

func (Folder) String

func (f Folder) String() (ret string)

type Workspace

type Workspace struct {
	Context context.Context
	// contains filtered or unexported fields
}

to open dialogs wails needs its own context: it doesn't really follow the standard golang context usag,: its a map of storage for various wails values. ( the per request context is derived from it. ) by copying it -- we might miss some later things added to it; but mostly its going to be okay. note: its not valid until startup has happened.

func (*Workspace) Startup

func (ws *Workspace) Startup(ctx context.Context)

callback from wails