Overview

Photoshop Design Space is an HTML5 application that runs in a custom browser environment provided by a native Photoshop plugin. This plugin, called the Spaces plugin, is based on the Chromium Embedded Framework (an embeddable version of Chromium, the open-source basis of Google's Chrome web browser), and provides direct access to the Photoshop scripting API via additional native JavaScript functions. This document describes how to configure Photoshop and the Spaces plugin to load either the Design Spaces HTML5 sources hosted at this repository or (for the highly adventurous) your own HTML5 sources.

Configuring Photoshop and the Spaces plugin

The Spaces plugin first shipped in Photoshop CC 2015 version 16.0 in June 2015 as a technology preview. Now Design Space is in preview mode with the Photoshop CC 2015.1 release. To use Design Space and the Spaces plug-in, look under the workspace dropdown in the top right corner:

As noted in the Design Space (Preview) description above, the Spaces plugin requires either Mac OS 10.10 Yosemite or Windows 8.1 (64bit) to run.

After switching into Design Space, the Spaces plugin will be loaded and the Design Space HTML5 application will be immediately loaded. The HTML5 sources loaded are those that are shipped with the Spaces plugin, which resides at .../Required/Plug-ins/Spaces, along with other default Photoshop plug-ins. On Mac, this directory structure is within the app bundle, and on Windows it is next to the executable.

With Design Space loaded, you can return to standard Photoshop using the menu command Window > Return to Standard Photoshop, and in standard Photoshop you can load Design Space with the menu command Window > Design Space (Preview). When Photoshop starts up, it will load whichever environment was running during the previous shutdown.

Along with the native Photoshop plug-in, the Spaces plug-in directory also contains:

1. A www/ directory, which contains a manifest.json file and a src/ subdirectory. A compiled version of the Design Space HTML5 sources are found within the src/ subdirectory, and the manifest.json file describes the basic structure of that subdirectory so that the Spaces plugin can load the application.
2. A settings.json file, which controls some basic parameters of the Spaces plugin.
3. A SpacesExtension.js file, which documents the native JavaScript functions available at runtime to access the Photoshop scripting API and other plug-in functionality.

To change the Design Space application, it is possible to edit or replace the default plug-in sources referenced above, but it is strongly preferable to instead override the default sources using an "outer" Plug-Ins/ directory structure that does not require modifying files shipped with Photoshop CC 2015. This "outer" Plug-Ins/ directory is not created when Photoshop itself is installed, but the following paths can be created, and updated HTML5 sources placed into it to be loaded by the internal Spaces plug-in. To do so, in the Photoshop application root directory,

(Win) C:\Program Files\Adobe\Adobe Photoshop CC 2015\
(Mac) /Applications/Adobe/Adobe Photoshop CC 2015/

create a Plug-Ins/ folder, and then a Spaces/ folder within that. When the Spaces plugin next loads, it will look for a settings.json file first in this outer directory before falling back to the internal settings.json file, and try to load content first from the outer www/ subdirectory before falling back to the internal HTML5 sources. Note that the www/ subdirectory may also be a symlink to an actual source directory, which is typically more convenient than working directly inside of Required/Plug-Ins/Spaces/www/.

Loading Design Space sources from Github

To load and debug the the Design Space sources from Github, first download and install the following prerequisite applications:

1. Git (or GitBash on Windows)
2. NodeJS

The former is used to download and work with the HTML5 sources hosted on Github, while the latter is needed to download external dependencies and for development tasks.

Next, clone the sources from the spaces-design Github repository into a convenient place on your local filesystem. You can name your filesystem however you please, we will refer to ours as 'Source':

$ cd ~/Source
$ git clone https://github.com/adobe-photoshop/spaces-design.git
  Cloning into 'spaces-design'...
  remote: Counting objects: 17053, done.
  remote: Compressing objects: 100% (3728/3728), done.
  remote: Total 17053 (delta 13127), reused 17028 (delta 13105), pack-reused 0
  Receiving objects: 100% (17053/17053), 11.16 MiB | 6.40 MiB/s, done.
  Resolving deltas: 100% (13127/13127), done.
  Checking connectivity... done.

The directory ~/Source/spaces-design now contains a local git repository with the Design Space filesystem. Now, create a directory within the Photoshop directory and create a symlink from this directory to your local repository, as follows:

$ mkdir -p /Applications/Adobe\ Photoshop\ CC\ 2015/Plug-Ins/Spaces
$ ln -sf  ~/Sources/spaces-design /Applications/Adobe\ Photoshop\ CC\ 2015/Plug-Ins/Spaces/www

Inside the spaces-design folder, you'll find a package.json file that describes Design Space external runtime dependencies and a src/ subdirectory that contains the HTML5 sources. To install the dependencies, we'll use the NodeJS package manager, npm, which is installed along with NodeJS.

We can now install the third-party dependencies:

$ npm install

  [email protected] node_modules/json-loader

  [email protected] node_modules/expose-loader

  ... <Rest of the third party dependencies/versions and where they're installed>

Note that if the npm install command above fails, the mostly likely culprit is a firewall. See here for instructions about how to work around the problem.

Once you npm install completely successfully, there should be a new node_modules subdirectory with third-party libraries:

$ ls -1 node_modules/
  bluebird
  classnames
  d3
  <...additional third-party libraries...>

Note in particular the spaces-adapter external dependency. This library contains a library of commands for driving and inspecting Photoshop, as well as a wrapper around the low-level API for interacting with Photoshop. For more information, see the spaces-adapter Github repository.

Source compatibility with Photoshop CC 2015 version 16.0

At this point, your local Design Spaces sources are ready to be loaded by the Photoshop Spaces plug-in. This is an important step because depending on which copy of Photoshop you have access to, the tag you check out in the git repository will differ. This is in order to ensure the HTML5 sources are compatible with your specific build of Photoshop, since the most-recent version of the HTML5 sources are no longer compatible with Photoshop 16.0.

• If you have access to nightly builds of Photoshop, you do not need to check out any tag in the git repository. Ensure you are up to date with master.

• If you have access to the Photoshop 16.0, you can use the ps-16.0 tag in the git repository:

$ git checkout ps-16.0
$ git status
  HEAD detached at ps-16.0
  nothing to commit, working directory clean

• If you have have access to pre-release version of Photoshop, then you can use the 'sprint-26.4' tag in the git repository:

$ git checkout sprint-26.4
$ git status
  HEAD detached at sprint-26.4
  nothing to commit, working directory clean

Next, we need to update the external dependencies so they match this earlier version:

$ npm update

The Design Space team is interested in helping developers stay up-to-date with the development of Design Space and the Spaces plug-in. Soon, we'll make it possible for interested developers to sign up for a Spaces pre-release program, in which we'll provide frequent access to in-development versions of Photoshop and the Spaces plugin under a non-disclosure agreement. This will make it possible for third-party developers to stay up-to-date with Design Space development or to develop their own HTML5 applications using the most recent features provided by the Spaces plug-in. We'll make an announcement soon about this pre-release program. If you're interested, please follow @psdesign on Twitter!

Once a compatible commit has been checked out in the local repository, the sources are ready to be loaded in Photoshop with the Spaces plugin. This can be done by first returning to standard Photoshop if Design Space is running (with Window > Return to Standard Photoshop), and then re-launching Design Space (with Window > Design Space (Preview)). If Design Space loads successfully, it will be using the local sources from your git repository.

Hacking Design Space

Now that your local Design Space HTML5 sources are running in Photoshop, you're ready to edit, debug, and live-reload the sources. To debug the running Design Space application, navigate to http://localhost:9234 with your locally installed version of Google Chrome (or any other Chromium-based browser). This page should list the "Inspectable WebContents", of which there will be one: Design Space. Clicking that link takes you to a remote version of Chromium DevTools that is connected to the Spaces plug-in running in Photoshop. You should see something like this:

With this interface, it is possible to inspect and manipulate the HTML5 application's DOM structure, set JavaScript breakpoints, profile the application's runtime performance, etc. Once you've edited your local sources to create some changes in the behavior or appearance of the Design Space application, the "Reload" keyboard shortcut (Command-R on Mac, Control-R on Windows) will reload the application in the Spaces plug-in. To learn more about using DevTools to debug HTML5 applications, see the official documentation.

Caveat Debugger: Compatibility between Spaces DevTools and Chromium

As of Photoshop version 16.0, the Spaces plug-in is based on Chromium version 39, while the most recent version of Google Chrome are based on at least Chromium version 43. Some incompatibilities have cropped up between the older DevTools application and newer browsers which in some cases makes it difficult to interact with the DevTools UI. We hope to upgrade the Chromium instance embedded in the Spaces plug-in soon, but in the meantime one workaround is to use a browser based on Chromium 39 to debug the Spaces plug-in.