TL;DR

They’re using the history API to initially replace your state then push the original unaltered state back so it looks like you went nowhere. Clicking back takes you to that special state which then does a location.replace to your new back state, because that’s how you win readers. See demo below for simplified version.

history.replaceState(null, document.title, location.pathname+"#!/stealingyourhistory");
history.pushState(null, document.title, location.pathname);

window.addEventListener("popstate", function() {
  if(location.hash === "#!/stealingyourhistory") {
	history.replaceState(null, document.title, location.pathname);
	setTimeout(function(){
	  location.replace("http://www.thecssninja.com/");
	},0);
  }
}, false);

Very simplified version they also cover non history API supporting browsers by doing hashchange and polling failing that. But I only have eyes for history API.

history.replaceState(null, document.title, location.pathname+"#!/stealingyourhistory");
history.pushState(null, document.title, location.pathname);

Upon loading the demo I replace the current URL with a #!/stealingyourhistory then sneakily push a new state on top for the original unaltered domain.

window.addEventListener("popstate", function() {
  if(location.hash === "#!/stealingyourhistory") {
	setTimeout(function(){
	  location.replace("http://www.thecssninja.com/");
	},0);
  }
}, false);

Attaching to the “popstate” event so we know when the user is going back I check the location.hash for our dodgy one and then replace the location to whatever dodgy website I want you to go back too.

The zero setTimeout is so we’ll be placed to run at the end of the browser event loop.

It’s more noticeable in some browsers

Thankfully Firefox and Chrome pause for a moment after a popstate so you can see the dodgy inserted hash url before the page redirects to your new history state. Opera and Safari will do it instantaneously :S.

However we can “improve” their script by doing another sneaky line of code.

history.replaceState(null, document.title, location.pathname);

All we’ve done is once again use a replaceState to restore the url to the clean unaltered state so all that happens is a slight pause in Chrome and Firefox and no URL change to the user.

Don’t do this!

Short URL: http://cssn.in/ja/047

How do I test a service that depends on $location?

This was the very question I had trouble finding an answer. I have a service that injects $location so I can determine the environment my web app is running on.

App.factory('urlRoot', ['$location', function($location) {
     var url = 'https://api.example.com.au',
          host = $location.host(),
          suffix = /\.[\w\-]+$/.exec(host),
          filter = /\.(nz|au)/;

     suffix = (!suffix || filter.test(suffix)) ? '' : suffix[0];

     return [url, suffix, '/v1/'].join('');
}]);

Pretty simple service that injects $location inspects the host and extracts the environment e.g. .dev, .staging etc. It then returns the correct API URL to call in that environment.

In the test I needed to be able to mock the Angulars $location object so I could test different scenarios, thankfully $location depends on $browser and in tests $browser is mocked in the angular-mocks.js file allowing us to “change” the URL so $location can be tested with different values. This way $location is the real service and $browser is altering what $location sees as the current URL.

describe('Service: urlRoot', function () {

  var envs = [
    'http://example.com.au.dev',
    'http://example.com.au.staging',
    'http://example.co.nz.staging',
    'http://example.co.nz'
  ],
  count = 0;

  // load the service's module
  beforeEach(module('App'));

  it('urlRoot should exist', inject(function (urlRoot) {
    expect(!!urlRoot).toBe(true);
  }));
  it('urlRoot should default to production endpoint', inject(function (urlRoot) {
    expect(urlRoot).toEqual('https://api.example.com.au/v1/');
  }));

  describe('Service: urlRoot specific environments', function() {
    beforeEach(inject(function($browser){
      $browser.url(envs[count++]);
    }));

    it('urlRoot should have ".dev" environment suffix', inject(function(urlRoot) {
      expect(urlRoot).toEqual('https://api.example.com.au.dev/v1/');
    }));

    it('urlRoot should have ".staging" environment suffix', inject(function(urlRoot) {
      expect(urlRoot).toEqual('https://api.example.com.au.staging/v1/');
    }));

    it('urlRoot should be agnostic of .co.nz domains', inject(function(urlRoot) {
      expect(urlRoot).toEqual('https://api.example.com.au.staging/v1/');
    }));

    it('urlRoot should ignore the last suffix if it\'s .nz or .au', inject(function(urlRoot) {
      expect(urlRoot).toEqual('https://api.example.com.au/v1/');
    }));
  });

});

From the code I have an array of fake environment URLs I want to test against. I use beforeEach to inject $browser, set the URL to one of the environments and using a counter variable increment it for each test. You’ll notice that I’m also injecting urlRoot for every test, this is so the beforeEach method can inject $browser and update the URL before the urlRoot service is injected and $location will then be aware of the new URL as it’s initialised after the URL has been changed.

I would love feedback from fellow Angular devs if this approach is the best way to handle a scenario like this.

Short URL: http://cssn.in/ja/046

Check out the following demonstration showing multi-level source maps for TypeScript and Coffeescript. If you haven’t enabled source maps you can do so in Chrome and WebKit Nightly by opening the dev tools > clicking the cog in the lower right corner > general > enable source maps.

Multi-level what?

Now in code, let’s say CoffeeScript(CS), you can compile to JavaScript and generate a source map using the new redux compiler. You take that generated source map and at the minifying stage, with UglifyJS2, specify --in-source-map option to reference the first level source map, CS > JS, this will map the minified JavaScript directly back to the CS and not the compiled JavaScript output!

This sounds like a lot of work but if you have a build process involved it’s a matter of kicking of a simple cli command to do the work for you and it gives you the kick-arse ability of having the multi-level mappings.

Here are a few snippets on how you can get this going in CoffeeScript or TypeScript. For more info on source map generation check out the TypeScript and CoffeeScript blog posts.

CoffeeScript

$> coffee --js -i test.coffee
$> coffee --source-map -i test.coffee > test.js.map

The first line will compile your CoffeeScript to JS the second line will then generate the source map file.

$> uglifyjs2 test.js \
   -o test.min.js \
   --source-map test.min.js.map \
   --in-source-map test.js.map \
   -m -c

Uglify has a few more options the most important being the --in-source-map which will reference that source map when taking into account the file information and what it’ll output for the second stage source map.

TypeScript

$> tsc greeter.ts -sourcemap

The TypeScript compiler outputs greeter.js and greeter.js.map

$> uglifyjs2 greeter.js \
   -o greeter.min.js \
   --source-map greeter.min.js.map \
   --in-source-map greeter.js.map \
   -m -c

This command is exactly the same as the CoffeeScript example but with the file names changed.

This will work for any other language that compiles to JavaScript that can generate a source map. Check out the source maps wiki for more info.

Source maps only work in Chrome and WebKit nightly but is coming very soon to Firefox Nightly.

Short URL: http://cssn.in/ja/045

If you open the test case in iOS6 Safari!, select a few locations and scroll those selections out of view then scroll back it will randomly select/unselect other items you never touched. It will also happen if you unselect a few items then dismiss the select and reopen it, some of the old ones you unselected will be re-selected again. Check out the video below to see the bug in action.

Optgroups seem to be the culprit

On our search box we have a few multi selects but the difference between them and the locations one is that location has a series of optgroups. Optgroups are what causes this weird behaviour to happen, if I strip them out this bug goes away. Check out the third select in the test case to see the fix.

<select multiple="multiple">
    <optgroup label="Options">
        <option value="1">Option 1</option>
        <option value="2">Option 2</option>
        <option value="3">Option 3</option>
        <option value="4">Option 4</option>
    </optgroup>
</select>

The above HTML will cause the issue as long as you can scroll some of the items out of view or (un)select some items dismiss then open.

Solution

The only solution I could come up with is to avoid optgroups and use a disabled option to create the section titles. This isn’t the most ideal solution but works in the meantime.

<select multiple="multiple">
    <option value="1" disabled>Options</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <option value="3">Option 3</option>
    <option value="4">Option 4</option>
</select>

If you know of a better one please let me know. I’ve filed a bug with Apple and have put it in the Open Radar tracker so people can see it.

Short URL: http://cssn.in/ja/044

Why does this work?

This got me curious as to why this is the case and thankfully a Mozillian, @heycam, pointed me to the source code of Firefox that shows classes are stored in 8bit strings and if you’re familiar with binary an 8bit string can only hold a maximum value of 255. You guessed it 256 tips this over the edge and overflows it into the ID count giving the classes higher specificity than the ID itself.

@ryanseddon From hg.mozilla.org/mozilla-centra… Gecko overflows the count of classes into the count of IDs, each of which holds 8 bits.

— Cameron McCormack (@heycam) August 16, 2012

What does Opera do differently?

According to an Opera employee, @patrick_h_lauke, they store specificity in 16bit strings, so you would need specify 65536 classes names to override an id and show the same behaviour other vendors do. I would be interested in know if using 16bit over 8bit actually impacts the selector engine.

@ryanseddon and to close the loop: yes, opera uses 16 bits instead of 8. bring on 65536 classes…

— patrick h. lauke (@patrick_h_lauke) August 16, 2012

mark: WONTFIX

While this is considered an implementation bug it won’t be fixed because it’s such a wildly ridiculous edge case. Another reason why is it could potentially slow down a browser selector engine speed and nobody wants that for crazy edges cases.

An interesting exercise that lets you dig into internals of how browsers work.

Short URL: http://cssn.in/ja/043

Pseudo elements and fixed positioning

The effect is actually deceptively simple and doesn’t require a whole lot of CSS, my effect doesn’t require any extra markup thanks to some use of pseudo-elements (:after/:before). This is the CSS taken from the above demo.

body {
     padding-bottom: 600px;
}
body:after {
    content: "";
    height: 1800px;
    position: fixed;
    left: 0;
    right: 0;
    bottom: 0;
    background: #000 url(assets/css-ninja.svg) 50% 0 no-repeat;
    background-size: auto 280px;
    z-index: 1;
}

That’s it to get the section to sit where I want using fixed position at the bottom and setting right and left properties to make the element expand the full width. I re-use my SVG logo that appears in the header and adjust the background-size to make it appear bigger so only the top half of the head appears.

To get the reveal effect All I need to do to my content is make sure it has a higher stacking context than my pseudo-element.

.curtain {
    height: 1200px;
    position: relative;
    z-index: 2;
}

Because my demo has no content I have set a height so you can see the effect happen this wouldn’t be needed if you have content. In the pseudo element I also set a height 600px higher than curtain overlay that’s so I can reveal a total of 600px of content when the user scroll down.

A real world case?

The effect on my site was just for fun but perhaps a more clever way of doing it would be to reveal a get in contact or buy my product upon the user scrolling through why they should use your service/product.

This demo uses the footer as the reveal element so the section element has a bottom margin that is equivalent to the height of the footer and the stacking context of the section and header elements are higher than the footer so it will only be “revealed” when the user scrolls to the bottom of the page.

section {
    margin-bottom: 350px;
    position: relative;
    z-index: 2;
}
footer {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    height: 350px;
    z-index: 1;
}

Browser support

The browser support for this is very good the first demo uses pseudo-elements, multiple backgrounds, svg and gradients so it has IE10+ support (With graceful degradation this could easily work IE8+) and the second demo has support IE7+ with just the HTML5 shiv included but wouldn’t require it if you were using divs.

iOS has some issues with fixed positioning

Who am I kidding iOS5 has a crazy amount of weird edge case issues with fixed positioning that will hopefully be addressed in iOS6. In the case of this demo the below screen shot of an iOS5 you’ll see the stacking context gets confused when the user is scrolling it will also flicker quite a lot and be quite jarring.

A simple yet cool looking effect, but avoid on iOS mobile devices for now.

Short URL: http://cssn.in/ja/042

The codestream video can take a while to load sometimes, be patient.

If you want to get stuck in go check out Bunyip on github and see the readme for instructions on getting up and running. It’s really easy I promise.

Bunyip

At Web Directions Code conference in Melbourne this past May I demonstrated this tool on stage in my talk “Debugging secrets of a lazy developer”. I started thinking about a tool like this when I joined the Modernizr team and how annoying, but important, it was to utilise the powerful test suite we have. Opening all the browsers and visually checking the test suite results is time consuming, thankfully a series of open source tools and a powerful API made this idea become a reality.

On the backs of great projects

The first tool that got Bunyip into a usable state is Yeti an incredibly powerful tool from Yahoo that allows to push out a html file to any connected browsers from the command line. It launches a little server on your machine that browsers on the same network can connect to. The downside initially was that it required you to use the YUI testing framework, but this tool was way too awesome to ignore it on that factor. So I dug in and discovered how it was sending back the results to the cli and wrote some adaptors for QUnit and jasmine to work with Yeti. If you use another framework feel free to do a pull request!

In the Yeti docs they suggest enabling mobile support by using a service called localtunnel which allows you to create an SSH tunnel into your local server so you can access it from outside your local network. I found localtunnel to be slow and sporadic with Yeti especially when the test suite was quite large. I settled on another service called pagekite which gives you 2.5GB of data for free and the ability to register a subdomain after that it’s pretty cheap. You can also check out showoff.io.

Next is a great service called BrowserStack. BrowserStack lets you test web sites in a whole bunch of browsers but more importantly they offer an API so you can spin up a browser and pass it a url. Exactly what I needed to make bunyip amazing. When I started building this tool the API only had support for desktop browsers, just before I did my talk they rolled out v2 which included mac and mobile browsers! Since I’m building this as a node module I’m using the very awesome node-browserstack module by Scott Gonzales to make using the API very easy.

How it works

As mentioned previously this is reliant on a lot of great OSS. To get into the deeper level on how this works you can comb through the code on github or read on for a high level look.

Local server

When you run this command bunyip -f test/index.html -b "firefox:win/12.0|ie:win/8.0|safari:mac/5.1|iPhone 4S:ios/5.0" in bunyip the first thing it does is hand off the -f test/index.html call to Yeti to spin up a local server that will have an intermediate page that will accessible via localhost:9000. Yeti uses socket.io to notify the cli when a slave connects and vice versa to control when a test should begin.

SSH tunnel and BrowserStack

Once Yeti is up and running bunyip will then grab the tunnel service config values from the file you would of setup. In my case it will run the pagekite.py script passing in my port 9000 and my subdomain I want it accessible via bunyip.pagekite.me.

We now have our tunnel up and running. Next we can parse the -b "firefox:win/12.0|ie:win/8.0|safari:mac/5.1|iPhone 4S:ios/5.0" flag into a usable JSON string we can send off to the BrowserStack API. It looks like this:

[
    {
        "browser": "ie",
        "os": "win",
        "version": "8.0",
        "url": "http://bunyip.pagekite.me/",
        "timeout": 480
    }
]

We authenticate with the API by passing in our credentials from the config.js file and instructing it to load up the workers we specified, in our case Firefox, IE, Safari and an iPhone 4S. When the Yeti waiting page loads it will emit an event that will trigger the cli to display a message letting us know that the browser/device has connected and is waiting for our test suite.

Pushing out the test suite

When all devices have connected we push enter to kick off running it through our connected browsers, Yeti will serve the page specified in our -f flag by emitting an event to all connected browser, using socket.io, telling them to redirect to our test suite. On page load Yeti injects a script called inject.js this is for any test suites written in YUI test if you’re not using YUI test then you would have included one of my yeti adaptors for either QUnit or jasmine this captures the test results as JSON in the format Yeti expects and emits an event back to the global $yetify object which sends off the results to the cli to handle what to display back to the user.

You can help make this awesome

Find any issues or want a new feature or think something can be improved. Then please by all means contribute in any way you can. I want this tool to be a community effort.

Other tools

Of course bunyip isn’t the first tool out there to try and do something like this so I’m going to list of some other tools that might be of interest.

• JSTestDriver
• Sauce Labs
• Buster.js
• TestSwarm
• Testling

What’s next?

Getting this battle tested inside some more real projects, especially people with jasmine test suites (I haven’t done a lot of testing with the adaptor I wrote for Yeti when using jasmine test suites).

Reid Burke (Yeti dude) is keen to get the Yeti adaptors into Yeti core so it’ll work with other test frameworks straight out of the box.

I need help making the config.js process less painful see issue #1.

See roadmap / wanted features wiki for what I want to add.

Client-side unit testing shouldn’t be hard and it shouldn’t get in your way. Hopefully bunyip can alleviate the pain and get people writing unit tests for the first time or more often.

Short URL: http://cssn.in/ja/041

Frost went down the route of physical devices, what you should test and their breakdown in prices. This post will be a list of services I have come across for testing on a vast array mobile devices without having to purchase said devices.

DeviceAnywhere

DeviceAnywhere Test Center is a device lab chock full of common and not so common devices that you can access remotely though their application. It gives you remote access to real devices, not emulators, and the ability to do almost anything to them. In my case I would only access the browser apps on each phone but you have full access to the phone and its capabilities.

Pros:

• Record video and image capture
• Invite other users to a watch or participate in testing
• Huge amount of devices including tablets.
• Good support for emulating touch and gestures.
• Relatively cheap.

Cons:

• Laggy and not super responsive (Latency from Australia most likely faster in USA and UK).
• Automation and scripting is part of their enterprise product which is very pricey.

Price: ~$16USD/hr for general access to the device lab. Packages and bulk hours equals cheaper prices.

Perfecto Mobile

PerfectoMobile MobileCloud is very similar to DeviceAnywhere both offer a huge array of real devices you can remotely access. PerfectoMobile uses a flash based web app for accessing and testing on devices.

Pros:

• Record video and image capture
• Invite other users to a watch or participate in testing
• Huge amount of devices including tablets.
• Have dedicated handset options: Blackberry and Nokia

Cons:

• Laggy and not super responsive (Latency from Australia most likely faster in USA and UK).
• Automation and scripting is part of their enterprise product which is very pricey.
• Touch and gestures aren’t that easy to accomplish.
• Pricey, even for entry level access.

Price: ~$170USD/10hrs per month. Blackberry $4USD/hr, Nokia $14USD/hr.

BrowserStack

BrowserStack recently launched remote access to an array of Mobile and tablet emulators with real device configurations. All in browser access.

Pros:

• Good cheap pricing
• Can test localhost remotely¹
• Automation! BrowserStack has an API for spinning up an emulator and scripting interaction. Huge.

Cons:

• Not real devices, but when it’s for browser testing that’s less of an issue.
• Smaller, but growing, list of mobile browsers. But really they cover 99% of the most used ones already.

Price: $19USD/Month for an individual. Gives you access to Mobile and desktop browsers.

¹ Note: BrowserStack provides their own implementation of a localtunnel like service. You can of course use localtunnel or similar on your own machine for testing your localhost with other services.

Nokia Remote Device Access

Nokia RDA is a device lab of, you guessed it, Nokia devices where you can remotely access an array of Nokia phones.

Pros:

• It’s free! You just need to sign up for Nokia dev account.
• Huge list of Nokia phones available.
• Record and screen capture.
• Pretty responsive.

Cons:

• Pretty lame con but it’s free and therefore could disappear.

Price: FREE!

AppThwack

AppThwack is a device lab of Android devices, iOS soon, that will let you run your app or mobile site through a series of tests and provide feedback and screenshots.

Pros:

• Huge list of Android phones available.
• Screen capture.

Cons:

• Free signup only allows testing of apk files, can’t run url tests.
• Android only at the moment.

Price: starts at $29USD/month

MITE

MITE is another product from Keynote that focuses on mobile website testing.

Pros:

• Test automation, can record a session and re-run
• Waterfall charts
• A web inspector

Cons:

• Windows only.
• It’s a native app and not a web app. Is this 1999?
• Don’t think it really tests on emulators, but has a common WebKit engine and skins the phones.¹
• WebKit monoculture.

Price: FREE!

¹ Note: From what I could gather on their website.

So that’s it. If you know of any other services that I may have missed let me know. I think a combination of real devices and remote access is the killer setup for any mobile development shop or individual.

Short URL: http://cssn.in/ja/040

Basically it’s a way to map a combined/minified file back to an unbuilt state. When you build for production, along with minifying and combining your JavaScript files, you generate a source map which holds information about your original files. When you query a certain line and column number in your generated JavaScript you can do a lookup in the source map which returns the original location. Developer tools (currently WebKit nightly builds, or Google Chrome Canary) can parse the source map automatically and make it appear as though you’re running unminified and uncombined files. As of writing Firefox has a blocked status for Source Map support. See MozillaWiki Source Map entry for more details.

The above demo allows you to right click anywhere in the textarea containing the generated source. Select “Get original location” will query the source map by passing in the generated line and column number, and return the position in the original code. Make sure your console is open so you can see the output.

Real world

Before you view the following real world implementation of Source Maps make sure you’ve enabled the source maps feature in either Chrome Canary or WebKit nightly by clicking the settings cog in the dev tools panel and checking the “Enable source maps” option. See screenshot below.

So… That Source Map query demo is cool and all but what about a real world use case? Take a look at the special build of font dragr at dev.fontdragr.com in Chrome Canary or WebKit nightly, with source mapping enabled, and you’ll notice that the JavaScript isn’t compiled and you can see all the individual JavaScript files it references. This is using source mapping, but behind the scenes actually running the compiled code. Any errors, logs and breakpoints will map to the dev code for awesome debugging! So in effect it gives you the illusion that you’re running a dev site in production.

Why should I care about source maps?

Right now source mapping is only working between uncompressed/combined JavaScript to compressed/uncombined JavaScript, but the future is looking bright with talks of compiled-to-JavaScript languages such as CoffeeScript and even the possibility of adding support for CSS preprocessors like SASS or LESS.

In the future we could easily use almost any language as though it were supported natively in the browser with source maps:

• CoffeeScript
• ECMAScript 6 and beyond
• SASS/LESS and others
• Pretty much any language that compiles to JavaScript

Take a look at this screencast of CoffeeScript being debugged in an experimental build of the Firefox console:

The Google Web Toolkit (GWT) has recently added support for Source Maps and Ray Cromwell of the GWT team did an awesome screencast showing source map support in action.

Another example I’ve put together uses Google’s Traceur library which allows you to write ES6 (ECMAScript 6 or Next) and compile it to ES3 compatible code. The Traceur compiler also generates a source map. Take a look at this demo of ES6 traits and classes being used like they’re supported natively in the browser, thanks to the source map. The textarea in the demo also allows you to write ES6 which will be compiled on the fly and generate a source map plus the equivalent ES3 code.

How does the source map work?

The only JavaScript compiler/minifier that has support, at the moment, for source map generation is the Closure compiler. (I’ll explain how to use it later.) Once you’ve combined and minified your JavaScript, alongside it will exist a sourcemap file. Currently, the Closure compiler doesn’t add the special comment at the end that is required to signify to WebKit and Chrome Canary dev tools that a source map is available:

//@ sourceMappingURL=/path/to/file.js.map

This enables developer tools to map calls back to their location in original source files. If you don’t like the idea of the weird comment you can alternatively set a special header on your compiled JavaScript file:

X-SourceMap: /path/to/file.js.map

Like the comment this will tell your source map consumer where to look for the source map associated with a JavaScript file. This header also gets around the issue of referencing source maps in languages that don’t support single-line comments.

The source map file will only be downloaded if you have source maps enabled and your dev tools open. You’ll also need to upload your original files so the dev tools can reference and display them when necessary.

How do I generate a source map?

Like I mentioned above you’ll need to use the Closure compiler to minify, concat and generate a source map for your JavaScript files. The command is as follows:

java -jar compiler.jar \ 
     --js script.js \
     --create_source_map ./script-min.js.map \
     --source_map_format=V3 \
     --js_output_file script-min.js

The two important command flags are --create_source_map and --source_map_format. This is required as the default version is V2 and we only want to work with V3.

The anatomy of a source map

In order to better understand a source map we’ll take a small example of a source map file that would be generated by the Closure compiler and dive into more detail on how the “mappings” section works. The following example is a slight variation from the V3 spec example.

{
    version : 3,
    file: "out.js",
    sourceRoot : "",
    sources: ["foo.js", "bar.js"],
    names: ["src", "maps", "are", "fun"],
    mappings: "AAgBC,SAAQ,CAAEA"
}

Above you can see that a source map is an object literal containing lots of juicy info:

• Version number that the source map is based off
• The file name of the generated code (Your minifed/combined production file)
• sourceRoot allows you to prepend the sources with a folder structure – this is also a space saving technique
• sources contains all the file names that were combined
• names contains all variable/method names that appear throughout your code.
• Lastly the mappings property is where the magic happens using Base64 VLQ values. The real space saving is done here.

Base64 VLQ and keeping the source map small

Originally the source map spec had a very verbose output of all the mappings and resulted in the sourcemap being about 10 times the size of the generated code. Version two reduced that by around 50% and version three reduced it again by another 50%, so for a 133kB file you end up with a ~300kB source map. So how did they reduce the size while still maintaining the complex mappings?

VLQ (Variable Length Quantity) is used along with encoding the value into a Base64 value. The mappings property is a super big string. Within this string are semicolons (;) that represent a line number within the generated file. Within each line there are commas (,) that represent each segment within that line. Each of these segments is either 1, 4 or 5 in variable length fields. Some may appear longer but these contain continuation bits. Each segment builds upon the previous, which helps reduce the file size as each bit is relative to its previous segments.

Like I mentioned above each segment can be 1, 4 or 5 in variable length. This diagram is considered a variable length of four with one continuation bit (g). We’ll break down this segment and show you how the source map works out the original location. The values shown above are purely the Base64 decoded values, there is some more processing to get their true values. Each segment usually works out five things:

• Generated column
• Original file this appeared in
• Original line number
• Original column
• And if available original name.

Not every segment has a name, method name or argument, so segments throughout will switch between four and five variable length. The g value in the segment diagram above is what’s called a continuation bit this allows for further optimisation in the Base64 VLQ decoding stage. A continuation bit allows you to build on a segment value so you can store big numbers without having to store a big number, a very clever space saving technique that has its roots in the midi format.

The above diagram AAgBC once processed further would return 0, 0, 32, 16, 1 – the 32 being the continuation bit that helps build the following value of 16. B purely decoded in Base64 is 1. So the important values that are used are 0, 0, 16, 1. This then lets us know that line 1 (lines are kept count by the semi colons) column 0 of the generated file maps to file 0 (array of files 0 is foo.js), line 16 at column 1.

To show how the segments get decoded I will be referencing Mozilla’s Source Map JavaScript library. You can also look at the WebKit dev tools source mapping code, also written in JavaScript.

In order to properly understand how we get the value 16 from B we need to have a basic understanding of bitwise operators and how the spec works for source mapping. The preceding digit, g, gets flagged as a continuation bit by comparing the digit (32) and the VLQ_CONTINUATION_BIT (binary 100000 or 32) by using the bitwise AND (&) operator.

32 & 32 = 32
// or
100000
|
|
V
100000

This returns a 1 in each bit position where both have it appear. So a Base64 decoded value of 33 & 32 would return 32 as they only share the 32 bit location as you can see in the above diagram. This then increases the the bit shift value by 5 for each preceding continuation bit. In the above case its only shifted by 5 once, so left shifting 1 (B) by 5.

1 << 5 // 32

// Shift the bit by 5 spots
______
|    |
V    V
100001 = 100000 = 32

That value is then converted from a VLQ signed value by right shifting the number (32) one spot.

32 >> 1 // 16
//or
100000
|
 | 
 V
010000 = 16

So there we have it: that is how you turn 1 into 16. This may seem an over complicated process, but once the numbers start getting bigger it makes more sense.

Potential XSSI issues

The spec mentions cross site script inclusion issues that could arise from the consumption of a source map. To mitigate this it’s recommended that you prepend the first line of your source map with “)]}” to deliberately invalidate JavaScript so a syntax error will be thrown. The WebKit dev tools can handle this already.

if (response.slice(0, 3) === ")]}") {
    response = response.substring(response.indexOf('\n'));
}

As shown above, the first three characters are sliced to check if they match the syntax error in the spec and if so removes all characters leading up to the first new line entity (\n).

@sourceURL and displayName in action: Eval and anonymous functions

While not part of the source map spec the following two conventions allow you to make development much easier when working with evals and anonymous functions.

The first helper looks very similar to the //@ sourceMappingURL property and is actually mentioned in the source map V3 spec. By including the following special comment in your code, which will be evaled, you can name evals so they appear as more logical names in your dev tools. Check out a simple demo using the CoffeeScript compiler.

//@ sourceURL=sqrt.coffee

The other helper allows you to name anonymous functions by using the displayName property available on the current context of the anonymous function. Profile the following demo to see the displayName property in action.

btns[0].addEventListener("click", function(e) {
    var fn = function() {
        console.log("You clicked button number: 1");
    };

    fn.displayName = "Anonymous function of button 1";

    return fn();
}, false);

When profiling your code within the dev tools the displayName property will be shown rather than something like (anonymous). However displayName is pretty much dead in the water and won’t be making it into Chrome. But all hope isn’t lost and a much better proposal has been suggested called debugName.

As of writing the eval naming is only available in Firefox and WebKit browsers. The displayName property is only in WebKit nightlies.

Let’s rally together

Currently there is very lengthy discussion on source map support being added to CoffeeScript. Go check out the issue and add your support for getting source map generation added to the CoffeeScript compiler. This will be a huge win for CoffeeScript and its devoted followers.

UglifyJS also has a source map issue you should take a look at too.

The more tools available to us that can generate a source maps the better off we’ll be, so go forth and ask or add source map support to your favourite open source project.

It’s not perfect

One thing Source Maps doesn’t cater for right now is watch expressions. The problem is that trying to inspect an argument or variable name within the current execution context won’t return anything as it doesn’t really exist. This would require some sort of reverse mapping to lookup the real name of the argument/variable you wish to inspect compared to the actual argument/variable name in your compiled JavaScript.

This of course is a solvable problem and with more attention on source maps we can start seeing some amazing features and better stability.

Tools and resource

Here’s some further resources and tools you should check out:

• Nick Fitzgerald has a fork of UglifyJS with source map support
• Paul Irish has a handy little demo showing off source maps
• Check out the WebKit changeset of when this dropped
• The changeset also included a layout test which got this whole article started
• Mozilla has a bug you should follow on the status of source maps in the built-in console
• Conrad Irwin has written a super useful source map gem for all you Ruby users
• Some further reading on eval naming and the displayName property
• You can check out the Closure Compilers source for creating source maps
• There are some screenshots and talk of support for GWT source maps
• Mozilla has a wiki entry on CSS Source Maps

Source maps are a very powerful utility in a developer’s tool set. It’s super useful to be able to keep your web app lean but easily debuggable. It’s also a very powerful learning tool for newer developers to see how experienced devs structure and write their apps without having to wade through unreadable minified code. What are you waiting for? Start generating source maps for all projects now!

Short URL: http://cssn.in/ja/039

Go check it out! As a thank you for reading I will give away some free passes to the first 10 people who can answer this question correctly: Promotion has now ended, thanks!

“Who created the Modernizr project?”

Mention me on twitter, @ryanseddon, with your answer to the question.

I will let the winners know via twitter.

If you don’t answer in time, don’t fret! It’s super cheap to get access to my course and many others at learnable.com, 2012 is the year of upskilling so get onto it!

Short URL: http://cssn.in/ja/038