Filesystem

currently only one scene is opened at a time. A scene is like a "project." It can be a single YAML file (the simplest root case), but this file can refer to external resources (via fully qualified URLs) or local resources (using relative paths). To make it easier to handle multiple resources Tangram supports loading a bundle that is a ZIP file, whose internal root contains a single YAML file (of any name) and all other local resources are contained in subdirectories relative to this root YAML file.

Tangram Play must know what each file is and where it is originally located.

• External URLs. Fully-qualified resources, e.g. https://mapzen.com/carto/bubble-wrap-style/bubble-wrap.yaml. Tangram Play assumes it does not have write access to any external URL. For the purpose of presentation to the user, references to external URLs do not change. If the content of an external resource changes as a result of user action in Tangram Play, it becomes a "in-memory" copy of the external URL but is referred to by its original source URL. When this content is saved, it must be "forked" and references to this external URL is updated. (TBD how this happens)
• Local, relative files. Relative files are located relative to the root YAML file but can exist on a remote server or on the local filesystem, e.g. ./blocks/albers.yaml. Tangram Play may have write access to these, but usually not directly. (If wrapped in Electron, Tangram Play may have direct write access to the file system. If hosted on mapzen.com, Tangram Play only has access to files in subdirectories of the root YAML via the Mapzen user account API. URLs that resolves outside of the user account resource folder, though it may be retrievable by Tangram, might not be writable, e.g. if someone tries to import like this: ../../../carto/bubble-wrap-style/bubble-wrap.yaml. This is a bad idea and guidance should be provided to users not to do this because it decreases portability of the scene. Tangram Play may not make any effort to correct this error on behalf of users.)
• "In-memory" files. These are files that do not have a canonical, physical source, e.g. someone creates a new blank file which has never been saved to a location. Technically all files are "in-memory" and the record of its location is optional.