mozilla / chromeless

DEPRECATED - Build desktop applications with web technologies.

Welcome To Chromeless!

The 'chromeless' project is an experiment into making it possible to build a web browser using only web technologies, like HTML, JavaScript, and CSS.

The project is based on addon-sdk (aka, "jetpack"), and xulrunner.

Current State

This project is highly experimental, rapidly changing, and probably insecure. As the project matures, this notice will change.

Design Overview

Chromeless can be used to created desktop applications using HTML, and related web technologies. In version 0.1, the original goal was a focus towards authoring a browser-like applications in HTML. That is still valid, however, now you can also use Chromeless to create all sorts of apps that can be executed like a native application, but where all of the look and feel, and many of the behaviors are defined by HTML, CSS, and javascript provided by the developer.

This "main app HTML" is basically a normal webpage, but with several important differences:

• The HTML file has access to a 'window.require()' function that it can use to access new APIs that give it increased priviledges.

• (untrusted) Web content can be rendered inside iframes which are children of the top level "main app HTML". This content cannot tell its rendered inside an iframe, and has no special access to the main app context.

• Several new events and conventions are introduced. For instance, the title of the top level browser HTML is the name of the running process (not yet implemented), new, non-standard events are available to the top level browser HTML which give it a priviledged view (and control) over embedded web content.

Prerequisites

• OSX 10.5 and later, Windows XP and later, or probably a modern versions of linux (32 or 64 bit).
• Python 2.5 - 2.7 (3 is not supported); Python 2.6 or 2.7 are recommended (testing isn't as thorough with 2.5).

Getting Started

The top level chromeless python script is capable of several things:

• running a browser when provided a path to 'browser HTML'
• packaging a browser as a xulrunner package, or a standalone exectuable (not yet implemented)
• running unit tests (not yet implemented)
• generating static documentation for all current APIs (not yet implemented)

To get started, you should clone this repository (or download a versioned snapshot) and run:

(win32) C:\xxx\chromeless> chromeless
(osx)   $ ./chromeless

By default, the HTML files in examples/first_browser will be executed, and you'll see a very simple browser based on them. You may also specify an alternate browser HTML on the command line:

(win32) C:\xxx\chromeless> chromeless examples\webgl
(osx)   $ ./chromeless examples/webgl

From here, you can inspect the implementation of any of these samples, copy, modify and explore.

For deployment or to share your application, you can use chromeless to generate a standalone application folder, that anyone on a supported platform can run. Output will be placed in the build/ directory:

(win32) C:\xxx\chromeless> chromeless appify examples\webgl
(osx)   $ ./chromeless appify examples/webgl

Finally, it's possible to generate a "XULRunner application", which is a folder that is much smaller than a standalone application, but can be run under (a specific version of) xulrunner. Again, the output will be placed in the build/ directory:

(win32) C:\xxx\chromeless> chromeless  package examples\webgl
(osx)   $ ./chromeless package examples/webgl 

Documentation and Additional Information

To generate a local API documentation, use:

(win32) C:\xxx\chromeless> chromeless docs
(osx)   $ ./chromeless docs

You may also check the Chromeless documentation online, plus inline examples can also be helpful. You can always find us on irc in #labs at irc.mozilla.org, or get help or discuss this project on our mailing list: [email protected]

Sub-projects for Tests

A Tests application is provided along wth Chromeless and can execute tests for all the apps under tests/ directory that have the test-app.js file in it:

(win32) C:\xxx\chromeless> chromeless tests
(osx)   $ ./chromeless tests

Gallery

An early version of a developer's gallery is now part of this git repository using git sub-modules. You may use Chromeless to launch or package these examples that provided in the gallery/ directory. In order to pull the projects from the gallery/ , you will need to initialize and update using git submodule. Example:

(linux) git submodule init ./gallery/simple-text-editor
(win32) git submodule init .\gallery\simple-text-editor

(linux) git submodule update ./gallery/simple-text-editor
(win32) git submodule update .\gallery\simple-text-editor

(win32) C:\xxx\chromeless> chromeless .\gallery\simple-text-editor
(osx)   $ ./chromeless ./gallery/simple-text-editor

Notes and Known Issues

• You need to pass a relative path to your application when you invoke chromeless script
• This version only packages your files that are under your main application directory. So if you use, for example, jquery in a sub-directory, it will not be bundled. Make sure you have all your files in the same directory.
• With Mac OSX, if you launch the application for tests ( not passing package option ), the keyboard output will show in the console and not in the browser screen. For Mac OSX, you may need to use the "package" argument and install in your machine.
• It works with some specific versions of XULRunner. And to help out developers, the chromeless script will fetch a XULRunner SDK.

LICENSE

All files that are part of this project are covered by the following license, except where explicitly noted.

Version: MPL 1.1/GPL 2.0/LGPL 2.1

The contents of this file are subject to the Mozilla Public License Version
1.1 (the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
for the specific language governing rights and limitations under the
License.

The Original Code is chromeless.

The Initial Developer of the Original Code is the Mozilla Foundation.

Portions created by the Initial Developer are Copyright (C) 2010
the Initial Developer. All Rights Reserved.

Contributor(s):

Alternatively, the contents of this file may be used under the terms of
either the GNU General Public License Version 2 or later (the "GPL"), or
the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
in which case the provisions of the GPL or the LGPL are applicable instead
of those above. If you wish to allow use of your version of this file only
under the terms of either the GPL or the LGPL, and not to allow others to
use your version of this file under the terms of the MPL, indicate your
decision by deleting the provisions above and replace them with the notice
and other provisions required by the GPL or the LGPL. If you do not delete
the provisions above, a recipient may use your version of this file under
the terms of any one of the MPL, the GPL or the LGPL.

chromeless's Issues

API - require("console")

HTML developer wants to dump messages to the console.

inline markup is shown in iframe

Before I could only see this with gmail, but now I also see in the standard google search results page, at the very end. Our iframes are showing inline markup. Any ideas please help.

API: require('file') - write a demo of file system interaction and add a 'onchange' event

the jetpack 'file' module should just work in chromeless, we should write a small demonstration of its functioning, and add a single feature (requested by a partner):
an onchange callback so that when a file changes on disk the page can be notified. Simple polling of modify date might be a fine initial implementation

API - require("session-store")

This is the session-store initial API. We want to be able to get some information for a given browser, and to be able to save in the user's profile sessionstore.js, following the same approach developed in Firefox. However, we are not using the SessionStore component in Firefox. So this version here, at this stage, is very simple.

For now, we save the page title, but we want to at least save URI for all the pages in a given browser session. From this work, we want to engage an extended discussion to think about how this API could be used, from the developer's HTML browser app, to engage the user in a private browsing session, and, to recover the previously saved session comprised of one or more browsers.

API: Running script prior to launching first visible window

We currently have a main.js file under packages/chromeless. This is the initial script that is executed. When it runs, it opens a window, then it loads the initial developer's code, the browser path HTML file that is passed as a static argument.

We may want to revisit this and let, or engage the developer, to launch code before the first visible window is active. One approach is to encourage them to write in the main.js ( or call another script from there ). So then, it would up to a developer to launch their other HTML files. The use case is for applications that may want to launch various windows based on preferences, or some other windowless apps.

Another approach is to think that a very first HTML is can be a hidden window ( depending on prefs or JSON ). Then it would give the developer a chance to do things before launching additional visible windows.

Preferences in ./template/defaults directory is not installed in installable XULRunner ZIP

We have a ./template/default directory with a preferences JavaScript file in it. This is currently being ignored by the cfx/build system. If you check in ./impl/cuddlefish/runner.py:

class XulrunnerAppProfile(mozrunner.Profile):
    preferences = {'browser.dom.window.dump.enabled': True,
                   'javascript.options.strict': True}

The above are the only preferences installed. I think the best here is simply to use the preferences.js file in the ./template/defaults/preferences/prefs.js

NSPlugin Viewer Warning

To reproduce:

./run ui/session/index.html

Enter techcrunch.com or mashable.com in the address bar and the following error appears in the console.

*** NSPlugin Viewer *** WARNING: unhandled variable 18 () in NPN_GetValue()

Environment details:
Mozilla XULRunner 1.9.2.12 - 20101027183423
Ubuntu 10.10
If my browser version matters, Firefox 3.6.12

Support transparent applications

Moving existing bugs in Etherpad to this project here.

The module, chromeless-window, is used from the main.js chromeless app. It is the initial startpoint to the application and loads the main application HTML. We need to simplify that module and allow to launch initial window in transparent mode.

We should generate final output app for XulRunner

This is related to this:

http://github.com/mozilla/chromeless/commit/2cbedb6f7aab3f9c24051df379f579804675af44
cfx can generate xpi, we need to adjust to generate a xulrunner app. The instruction has information on how to do that manually. We have to check this with Atul and make it part of cfx too or make a decision and totally keep things separated.

Need a system for exposing documentation

We should invest time up front in a good system for exposing documentation. I think it would be very interesting to write a little tiny skin for chromeless that can display static overview documentation, as well as per module docs in the way that the jetpack SDK does. Rather than binding a local port though, why don't we try implementing it as a "custom browser" of sorts?

window.close()

Please correct me if this is already implemented or there's some reason why it shouldn't be, but I think window.close(); should close the browser.

UX Browser Sample / We need a WebGL sample

OS Sourced Drag and Drop

A lot is possible with HTML5, but we should write a little demonstration of drag-out and drag-in of file content to demonstrate how it could be done and to determine if there are any hooks we need to add.

Main browser HTML onload event attribute is not being fired

Take one of the samples, add the onload="alert(1)" to the body tag. It won't fire the alert.

Need a way to get the favicon for a loaded web site

It would be nice to have a helper function to get the favicon for a resource being loaded inside an iFrame.

If there's already a way to achieve this then please do let me know!

embedded web content should have no chrome priviledges

content embedded inside an iframe inside the HTML entry point should not be able to invoke xpcom components, nor should it be able to access window.require() which is available only to the top level window.

Desktop notifications

there is some support for notifications in both addon-kit and gecko, we should wrap and expose a simple way for apps to throw toast.

chromeless-kit package / canvas-proxy module implementation

The canvas-proxy module, which is exposed to the HTML browser page, so far allows capture of a contentWindow ( iframe window for example ) to a canvas. We should make this implementation offer more options to developers, and also to pass events to the referenced browser.

• Take screenshots in different sizes and aspect ratio
• Send click events to the referenced browser
• Send keyboard events to the referenced browser

A reference work here is in Fennec code

X-Frame-Options - Pages with X-Frame-Options are not rendered in the imediate iframe due

The problem is:

• http://mail.google.com does not work

The investigation:

This relates to the content policy and how iframe works. I added my investigation here:

http://gecko.mgalli.com/x-frame-options-discussion-follow-up

The proposal, patch, is to let the main toplevel window, be a 'system' priviledge window. But to do this we need to make sure all the inner iframes are not priviledged. The above link shows various tests and so far it's all good. The patch proposal is in a project fork:

https://github.com/taboca/chromeless

I am willing to get a review opinion from Lloyd about this. The patch basically replaces the direct access: file:// with a protocol-based access, which then loads from the file://, but it runs the toplevel with system priviledges. Since this impacts toplevel security the HTML browser page will be able to do things like access to toDataURL(), canvas's drawWindow from any piece of the window, resize to smaller sizes, using DOM.

Need a way to access the current title of loaded web content

API for explicit access of title could be similar to other iframe controls (as discussed in Issue #34). We might also augment events emitted which convey iframe load percentage so clients can get at the title immediately as it changes.

Keyboard focus is outside window with XULRunner 1.9.2 and +

How to reproduce:

Edit the run script, or call the app with cfx using -a xulrunner -b path_to_xulrunner-bin. Use the "thumbnails/index.html". Put the cursor caret in the textfield ( urlbar ) at the top. Type in something and you will notice the focus is still in the terminal console instead the window.

how to launch with XULrunner:

./impl/bin/cfx -a xulrunner -b ../../xulrunner-sdk/xulrunner-sdk/bin/xulrunner-bin -t ./template/app-extension --static-args {"browser":"thumbnails/index.html"} -p "impl/package/chromeless" run

API: require('app-menu') an API to interact with the application's menu

browser_code should be able to specify the hierarchy of the app menu and get notifications when items are selected. We need to think about platform differences a bit here.

API - require("history")

API so HTML browser developer can traverse a browser's history.

doesn't work on latest xulrunner from trunk

We should understand and fix whatever is preventing code from working on latest xulrunner nightlies.

Main window controls

In the developer's HTML, main browser element, when width and height is set, we need to reset the window. We also need to allow resizing.

API - 'process' (was: Need a way to execute files from the filesystem)

I saw that you can read and write files.
I wish to be able to execute other files to reuse existing applications from within chromeless

automatically log exceptions that bubble up to the top level

as a convenience to developers, it would be useful if exceptions that bubble to the top level were automatically logged to the console, as well as html syntax errors.

there must be a way to hook into gecko at a low level and get our code running when these events occur...

automatically log exceptions that bubble up to the top level

as a convenience to developers, it would be useful if exceptions that bubble to the top level were automatically logged to the console, as well as html syntax errors.

there must be a way to hook into gecko at a low level and get our code running when these events occur...

API - require("canvas-proxy")

HTML developer needs API to take snapshot of page thumbnails. We have this in place but we need a review to be able to control various parameters, such as width, height, aspect ratio, and scale.

Need a way to stop loading content in an iframe

This could be accomplished in the vein of the iframe as browser approach:

require("iframe-controls").stop(Node);

or we could inject functions accessible to browser code on the iframe

document.getElementId('myContentIFrame').stop();

The latter might be slightly more difficult. Thoughts on API?

provide a way to specify application icon

the developer should be able to include a png file, and specify that file as the application icon in appinfo.json. We should automatically embed this file in the application bundle, and perhaps into the exe.

move documentation into javascript source

An initial experiment with yuidoc suggests to me that we could use the yuidoc_parse.py module with very few modifications to extract documentation from javascript source and build up a json datastructure.

This would afford some clear (in my mind) benefits:

• move documentation next to implementation to give it a better chance of staying up to date
• provide a structured and thought through mechanism to document methods, parameters, and events
• give us a clean way to implement a full api search within the documentation (I personally find this to be a pretty important discovery tool)

I think we could also leave markdown formatted comments inside javascript files and use showdown to render them.

wanted to capture the idea here, as right now the documentation feels very browse oriented and disparate from source...

we should automatically acquire a specific version of xulrunner

by locking to a specific version of xulrunner and acquiring it as a pre-build step, we remove the requirement that chromeless code must run on older versions of xulrunner, which reduces maintenance cost and test matrix.

At the same time, if it's a recent version this frees up platform users to use the latest and greatest features from gecko + spidermonkey in constructing their browsers.

we need to figure out how the prebuild step will work, and implement it. This can (and probably should) be related to how we track a specific version of the jetpack sdk sources

should allow a user to specify any file path to run script

currently we're creating a custom protocol for the data directory of the chromeless package inside main.js

This prevents us from being able to invoke run from the command line like so:

$ run ../mybrowser/

This also would make it difficult for us to handle breaking interface files into examples/ and tests/.

What would the downsides be of skipping the resource creation step and using file urls inside main.js? this would let us get rid of the wierd symlinking we do in the run script?

reorganize documentation

Currently the organization of documentation doesn't really make any sense. There are six high level packages under which docs are grouped:

• api-utils: usually stuff we pulled from jetpack
• chromeless-kit: usually stuff marcio and chromeless contribs have written
• chromeless: internal implementation details of chromeless
• development-mode: an uninteresting thing we inherited from jetpack
• nsjetpack: a binary component that only seems to be used by the existing test-harness
• test-harness: a (currently non-working) set of tools for unit testing of modules

Key problems with this organization are that it offers no value to a developer working on top of chromeless, because more than half of the packages are probably not interesting. Another issue is that while there are three distinct developer audiences that these packages/modules might be interesting to, this is not in any way leveraged in the documentation structure.

So here's the proposal. First, its driven by the idea that there's three distinct audiences:

• application authors - those building apps on top of chromeless
• module developers - those writing new modules for use by application authors or other mod devs
• platform implementors - those working on core features of the platform that are interested in all the implementation details

I think this also lists who we should target our documentation at in priority order, based on how many of each of these classes there are. Given this, I propose all existing modules are mashed into a 2 level hierarchy, with the following top level:

• 'internal/' -- tools that are internal to the platform, implementation details like chromeless/main.js
• 'lang/' -- language tools like publicConstructor that are generally interesting during module development. timer.js also fits here. chrome.js goes here.
• 'types/' -- basic types that are used throughout the rest of the apis in the platform. List, text-streams, byte-streams, etc.
• 'os/' -- anything that interacts with the underlying os, file system manipulation goes here, as does process management, etc for now, app-paths would probably go here too.
• 'web/' -- tools related to inspecting or manipulating web resources: favicon.js, iframe utilities, etc.
• 'net/' -- I don't know if this should be folded into web/, but things like xhr.js would go here
• 'ui/' -- interaction with windows, menus, notifications, etc.

I know these buckets aren't right, but I feel like they're close and can get us started. thoughts?

Gdk XID collision

Procedure to reproduce:

./run ui/first_browser/index.html

enter engadget.com in the address bar. And the following error appears repeatedly in the console:

(npviewer.bin:21388): Gdk-WARNING **: XID collision, trouble ahead

Environment details:
Mozilla XULRunner 1.9.2.12 - 20101027183423
Ubuntu 10.10
If my browser version matters, Firefox 3.6.12

HTML and iframe vs browser

The escape project [1], from Myk, uses a XUL:browser element inserted in an XHTML document. Here in the chromeless, so far, and for the purposes of initial use case samples, we have used iframes, simply to make a point to web developers and to use a reference implementation and language.

Now it's time for us to run the analysis on all the undesired behaviors of using an iframes, and check against advantages and disadvantages of using an inserted XUL:brower element against other options, such as modifying iframe behavior -- sort of connected with a note from Lloyd ( in the ui/first_browser/index.html sample ) where he added an attribute to the iframe as a means to illustrate a need to protect the parent browser page.

Felipe Moura, Moz Brasil contributor,says " Mas me diz uma ciosa, o fato de usar iframes para carregar as páginas, caso uma página tenha algum target para o top, ou mesmo use algo no javascript alterando o top.location, lá se foi o browser! Como seria esse tratamento? "

Which is basically a question on what happens if iframe content has target ="top". I believe this could be the problem I got when Pascal asked me to do the NY times screenshot, the inner frame took over the whole browser window :).

[1] https://hg.mozilla.org/users/myk_mozilla.com/escape/

find a better way to include startup javascript

currently we have a main.xul file whose only job is to include some javascript (harness.js). This xul file specifies a top level window, which is more that what we want. Ideally we would replace this file with the minimal amount of work required to get our bootstrap javascript executed.

The core issue here is that unlike other xulrunner applications, we want to control app startup programatically (via js), rather than declaratively (via xul).

Browser API: ability to stop page load

This is from the groups thread, from a developer Mr. Ben Francis:

https://groups.google.com/d/msg/mozilla-labs/2T6stq1IZYA/RFPW3HuVTiQJ

"P.S. Can I have a browser stop button and page title helper functions in Chromeless please?"

API: Ability to Open Window

HTML/JS developer needs an API that allows a script to open/launch a new window. We may also think and test what is the current behavior when a JavaScript attempts to launch a window, if it works or not, and how another script ( extension perhaps ) would be able to intercept - popup blocking function.

API - require("browser-controls")

HTML developer needs API control back, forward, reload and top. This relates to the discussion about the use of iframe or other browser implementaion that is available in the HTML, we need to make sure, in case of using iframes, we can go further to do things such as preventing a page load.

Way to bypass XULRunner fetch install mode

In some systems we may have an existing XULRunner runtime. If a XULRunner runtime is provided, or a bypass option is used as a parameter, our ./chromeless test script should simply use the existing runtime.

This case is also supported by the idea that if a local repository / fetch fails, existing XULRunner frameworks, or Firefox, could be used instead. A problem I had is:

Fetching xulrunner, 371 bytes from ftp.mozilla.org
| 0%                                                               100% |
|***********************************************************************| 
Traceback (most recent call last):
 File "./chromeless", line 72, in <module>
   f.run()
 File "/Users/marciogalli/Desktop/chromeless/mozilla/repository/chromeless- nov16/chromeless/impl/mozfetcher/_fetcher.py", line 142, in run
   self._fetch(descriptor)
 File "/Users/marciogalli/Desktop/chromeless/mozilla/repository/chromeless-nov16/chromeless/impl/mozfetcher/_fetcher.py", line 111, in _fetch
   raise RuntimeError("download failure!  md5 mismatch!")
RuntimeError: download failure!  md5 mismatch!

But I do have 3 XULRunners installed.

Inner browsers should not access top level or parent window

Right now we are using iframes as the inner-browsers. If the inner content should not access the parent browser. The use case, testcase , that should fail is the framebuster example from Lloyd:

http://github.com/mozilla/chromeless/commit/b5ae774aa258f0ab2a597ff25595c2e0e9db3048

Generated XULRunner app fails due to full path in staticArgs argument

We so far pass a file path to the main.js. This uses the full path of the harddisk and works fine for tests ( using cfx ). But if we consider generating the output application i.e., xulrunner --install-app, it will fail to launch the application because of the full path.

We need to use a path that is relative to the app, this could be a reason to use resource:// protocol instead.

Here is how the harness-options.json looks like, the line in evidence, if you use cfx with the "xpi" instead the "run" option.

"staticArgs": "{"browser": "/Users/marciogalli/Desktop/chromeless/mozilla/repository/chromeless-nov10a/chromeless/examples/first_browser/index.html"}",

must track better remote jetpack sources

currently we have a divergent copy of jetpack sources inside our tree. we need a better way of tracking jetpack sources. blog post with proposal forthcoming...

windows support

we should test/fix chromeless on win32 - and update all documentation to deal with users on different platforms.

ui/session sample error

./run ui/session/index.html

When the 'go' button is clicked on a popup with the following javascript error is shown:
"TypeError: document.getElementById("content").addTab is not a function"

Environment details:
Mozilla XULRunner 1.9.2.12 - 20101027183423
Ubuntu 10.10
If my browser version matters, Firefox 3.6.12

Move the chromeless-kit outside fro the chromeless application

We have now the chromeless-kit modules inside the packages directory of the chromeless app. Chromeless Jetpack application should simply import this package just like it may use any other package from Jetpack.

This should allow developers to hack the main.js and not bother with a whole structure under it.

should be able to specify resizable in appinfo.json

Certain initial app parameters can be controlled in appinfo.json, whether the initial window is resizable should be one of them.

jQuery document ready does not evaluate properly

There is something wrong with the jQuery ready function state in the developer's HTML browser. If you want to reproduce this, check some of the samples in the ui directory and use the jQuery document ready function to set an alert(1) when the page is loaded. The alert won't display. But if you put a setTimeout("alert(1)",1); then it works.