premonition 0.6.2 → 0.8.0

package/index.min.js

@@ -1,2 +1 @@
-/* premonition@0.6.2 · MIT · Francisco Presencia https://francisco.io/*/
-(function(a,b){'object'==typeof exports&&'undefined'!=typeof module?module.exports=b():'function'==typeof define&&define.amd?define(b):a.pre=b()})(this,function(){'use strict';async function a(a='a'){await new Promise(a=>'complete'===document.readyState?a():void document.addEventListener('DOMContentLoaded',a,!1)),this.cache.set(window.location.href,{href:window.location.href,html:i('html')[0].outerHTML}),i(`script[${this.attrs.once}]`).forEach(a=>this.loaded[a.src]=!0),i(a).forEach(a=>{a.host!==location.host||(a.addEventListener('mouseover',a=>this.load(a.currentTarget)),a.addEventListener('touchstart',a=>this.load(a.currentTarget)),a.addEventListener('click',a=>(a.preventDefault(),this.open(a.currentTarget))))})}async function b(a=''){let b=j(a.href||a,'pre.load():');return(b=b.split('#')[0],this.loader[b])?this.loader[b]:this.cache.get(b)?Promise.resolve(this.cache.get(b)):(this.loader[b]=fetch(b).then(a=>(a.ok||this.report(new Error(a.statusText)),a.text())).then(a=>(this.cache.set(b,{href:b,html:a}),delete this.loader[b],this.cache.get(b))),this.loader[b])}async function c(a,{history:b}={}){try{const c=j(a.href||a),d=c.split('#').slice(1).join('#'),e=await this.load(c);return await this.replace(e.href,e.html,{history:b}),this.init()}catch(a){this.report(a),location.href=href}}function d(a='a'){const b=Object.keys(this.cache.cache);i(a).forEach(a=>{if(b.includes(a.href))return a.getAttribute(this.attrs.cache)?void 0:a.setAttribute(this.attrs.cache,!0);a.getAttribute(this.attrs.cache)&&a.removeAttribute(this.attrs.cache)})}function e(a,b){let c=0;[...b.children].forEach(b=>{const d=b.cloneNode(!0),e=[...a.children],f=e.slice(c);if(l(f,d))return c+=f.findIndex(a=>k(d,a)),void e[c].setAttribute(this.attrs.keep,!0);const g=e[c];d.setAttribute(this.attrs.keep,!0),g.parentNode.insertBefore(d,g.nextSibling)}),[...a.children].forEach(b=>{b.getAttribute(this.attrs.keep)?b.removeAttribute(this.attrs.keep):a.removeChild(b)})}function f(a,b,{history:c=!0}={}){c&&window.history.pushState({href:a},'',a),window.scrollTo(0,0);const d=document.createElement('html');d.innerHTML=b;const e=document.body;e.innerHTML='',[...i('body',d)[0].childNodes].forEach(a=>e.appendChild(a)),this.head(document.head,d.querySelector('head'));const f=([a,...b])=>a?m(a,e,this.loaded).then(()=>f(b)):Promise.resolve();return f(i('script'))}var g='undefined'==typeof window?'undefined'==typeof global?'undefined'==typeof self?{}:self:global:window,h=function(a,b){return b={exports:{}},a(b,b.exports),b.exports}(function(a){function b(a,b){if(!(a instanceof b))throw new TypeError('Cannot call a class as a function')}var c=function(){function a(a,b){for(var c,d=0;d<b.length;d++)c=b[d],c.enumerable=c.enumerable||!1,c.configurable=!0,'value'in c&&(c.writable=!0),Object.defineProperty(a,c.key,c)}return function(b,c,d){return c&&a(b.prototype,c),d&&a(b,d),b}}();(function(){var d='undefined'==typeof process?function(a){return setTimeout(a,1)}:process.nextTick,e=function(){function a(c,d,e,f){return b(this,a),this.expire=f,this.max=c,this.notify=d,this.ttl=e,this.reset()}return c(a,[{key:'clear',value:function(){var a=!!(0<arguments.length&&void 0!==arguments[0])&&arguments[0];return this.reset(),!a&&this.notify&&d(this.onchange('clear',this.dump())),this}},{key:'clearTimer',value:function(a){var b=1<arguments.length&&void 0!==arguments[1]?arguments[1]:'timers';return this.has(a,b)&&(clearTimeout(this[b][a]),delete this[b][a]),this}},{key:'delete',value:function(a){var b=!!(1<arguments.length&&void 0!==arguments[1])&&arguments[1];return this.remove(a,b)}},{key:'dump',value:function(){var a=JSON.parse(JSON.stringify(this));return delete a.timers,JSON.stringify(a)}},{key:'evict',value:function(){return this.has(this.last)&&this.remove(this.last,!0),this.notify&&d(this.onchange('evict',this.dump())),this}},{key:'get',value:function(a){var b;return this.has(a)&&(b=this.cache[a].value,this.set(a,b),this.notify&&d(this.onchange('get',this.dump())),0<this.ttl&&this.clearTimer(a).setTimer(a)),b}},{key:'has',value:function(a){var b=1<arguments.length&&void 0!==arguments[1]?arguments[1]:'cache';return a in this[b]}},{key:'onchange',value:function(){}},{key:'remove',value:function(a){var b=!!(1<arguments.length&&void 0!==arguments[1])&&arguments[1],c='string'==typeof a?a:a.toString(),e=void 0;if(this.has(c)){var f=this.cache[c];delete this.cache[c],this.length--,0<this.ttl&&this.clearTimer(c),!1===b&&0<this.expire&&this.clearTimer(c,'expires'),this.has(f.previous)?(this.cache[f.previous].next=f.next,this.first===c&&(this.first=f.previous)):this.first===c&&(this.first=''),this.has(f.next)?(this.cache[f.next].previous=f.previous,this.last===c&&(this.last=f.next)):this.last===c&&(this.last=''),e=f}else this.first===c&&(this.first=''),this.last===c&&(this.last='');return!b&&this.notify&&d(this.onchange('remove',this.dump())),e}},{key:'reset',value:function(){var a=this;return void 0!==this.expires&&Object.keys(this.expires).forEach(function(b){return a.clearTimer(b,'expires')}),void 0!==this.timers&&Object.keys(this.timers).forEach(function(b){return a.clearTimer(b)}),this.cache={},this.expires={},this.first='',this.last='',this.length=0,this.timers={},this}},{key:'set',value:function(a,b){var c,e;return this.has(a)?(e=this.cache[a],e.value=b,e.next='',this.first!==a&&(e.previous=this.first),this.last===a&&''!==e.previous&&(this.last=e.previous)):(++this.length>this.max&&this.remove(this.last,!0),1===this.length&&(this.last=a),this.cache[a]={next:'',previous:this.first,value:b}),this.first!==a&&this.has(this.first)&&(c=this.cache[this.first],c.next=a,c.previous===a&&(c.previous='')),this.first=a,this.notify&&d(this.onchange('set',this.dump())),0<this.ttl&&this.clearTimer(a).setTimer(a),0<this.expire&&!1===this.has(a,'expires')&&this.setExpire(a),this}},{key:'setExpire',value:function(a){var b=this;this.expires[a]=setTimeout(function(){return b.clearTimer(a,'expires').clearTimer(a).remove(a)},this.expire)}},{key:'setTimer',value:function(a){var b=this;this.timers[a]=setTimeout(function(){return b.remove(a)},this.ttl)}},{key:'update',value:function(a){var b=this,c=JSON.parse(a);Object.keys(c).forEach(function(a){b[a]=c[a]})}}]),a}();a.exports=function(){var a=0<arguments.length&&arguments[0]!==void 0?arguments[0]:1e3,b=!!(1<arguments.length&&arguments[1]!==void 0)&&arguments[1],c=2<arguments.length&&arguments[2]!==void 0?arguments[2]:0,d=3<arguments.length&&arguments[3]!==void 0?arguments[3]:0;return new e(a,b,c,d)}})('undefined'==typeof window?g:window)}),i=(a,b=document)=>[...b.querySelectorAll(a)],j=(a,b='')=>{if(!a)throw new Error(`${b} the argument has to be an url or a <a> element`);if('A'===a.nodeName)throw new Error(`${b} argument element is missing the href="" or it is empty`);if(a.nodeName)throw new Error(`${b} expected an anchor <a> element, received "${a.nodeName}"`);if('string'!=typeof a)throw new Error(`${b} expected a string, received ${typeof a}`);return a};const k=(c,a)=>c.outerHTML===a.outerHTML,l=(a,b)=>!!a.find(a=>k(a,b));var m=(a,b,c)=>new Promise((d,e)=>{if(c[a.src])return d();const f=document.createElement('script');if(a.src)return f.addEventListener('load',d),f.addEventListener('error',e),f.src=a.src,void b.appendChild(f);const g=`(() => {${a.innerText}})();`;f.appendChild(document.createTextNode(g)),b.appendChild(f),d()});const n=function({attrs:g}={}){return this instanceof n?void(this.attrs=Object.assign({once:'data-pre-once',keep:'data-pre-keep',cache:'data-pre-cached'},g),this.loader={},this.loaded={},this.cache=h(100,!0,0,1e4),this.cache.onchange=()=>this.links(),this.init=a,this.load=b,this.preload=b,this.open=c,this.links=d,this.head=e,this.replace=f,this.report=a=>console.log('Error:',a),window.onpopstate=a=>{this.open(a.currentTarget.location.href,{history:!1})},this.init()):new n({attrs:g})};var o=new n;return o});
+(()=>{class l{max;ttl;onchange=()=>{};items=new Map;constructor(e=100,t=1e4){this.max=e,this.ttl=t}keys(){return[...this.items.keys()]}get(e){let t=this.items.get(e);if(!t)return;if(this.ttl&&t.expires<performance.now()){this.items.delete(e),this.onchange();return}return this.items.delete(e),this.items.set(e,t),t.value}set(e,t){if(this.items.delete(e),this.items.set(e,{value:t,expires:performance.now()+this.ttl}),this.items.size>this.max)this.items.delete(this.items.keys().next().value);this.onchange()}clear(){this.items.clear(),this.onchange()}}function f(e){if(e.hasAttribute(this.attrs.ignore))return!1;let t=e.getAttribute("href");if(!t)return!1;if(t[0]==="#")return!1;if(e.host!==location.host)return!1;let r=e.getAttribute("target");if(r&&r!=="_self")return!1;if(e.hasAttribute("download"))return!1;if(e.protocol&&!/^https?:$/.test(e.protocol))return!1;return!0}var y=(e,t)=>e.outerHTML===t.outerHTML,L=(e,t)=>e.some((r)=>y(r,t));function u(e,t){let r=0;[...t.children].forEach((o)=>{let i=o.cloneNode(!0),n=[...e.children],s=n.slice(r);if(L(s,i)){r+=s.findIndex((p)=>y(i,p)),n[r].setAttribute(this.attrs.keep,"true");return}i.setAttribute(this.attrs.keep,"true");let c=n[r];if(c)c.parentNode.insertBefore(i,c.nextSibling);else e.appendChild(i)}),[...e.children].forEach((o)=>{if(o.hasAttribute(this.attrs.keep))o.removeAttribute(this.attrs.keep);else e.removeChild(o)})}var a=(e,t=document)=>[...t.querySelectorAll(e)];async function g(e="a"){if(await new Promise((t)=>{if(document.readyState!=="loading")return t();document.addEventListener("DOMContentLoaded",()=>t(),!1)}),!this.started){this.started=!0;let t=location.href.split("#")[0];this.cache.set(t,{href:t,html:document.documentElement.outerHTML})}a(`script[${this.attrs.once}]`).forEach((t)=>{this.loaded[t.src]=!0}),a(e).forEach((t)=>{if(!this.follows(t))return;let r=(o)=>this.load(o.currentTarget).catch((i)=>this.report(i));t.addEventListener("mouseover",r),t.addEventListener("touchstart",r),t.addEventListener("click",(o)=>(o.preventDefault(),this.open(o.currentTarget)))})}function E(e="a"){let t=this.cache.keys();a(e).forEach((r)=>{let o=r.href.split("#")[0];if(t.includes(o)){if(!r.hasAttribute(this.attrs.cache))r.setAttribute(this.attrs.cache,"true")}else if(r.hasAttribute(this.attrs.cache))r.removeAttribute(this.attrs.cache)})}var d=(e,t="")=>{let r=e?.href||e;if(!r)throw Error(`${t} the argument has to be an url or a <a> element`);let o=r;if(o.nodeName==="A")throw Error(`${t} argument element is missing the href="" or it is empty`);if(o.nodeName)throw Error(`${t} expected an anchor <a> element, received "${o.nodeName}"`);if(typeof r!=="string")throw Error(`${t} expected a string, received ${typeof r}`);try{return new URL(r,location.href).href}catch{throw Error(`${t} expected a valid url, received "${r}"`)}};async function m(e=""){let t=d(e,"pre.load():").split("#")[0],r=this.loader[t];if(r)return r;let o=this.cache.get(t);if(o)return o;return this.loader[t]=fetch(t).then((i)=>{if(!i.ok)this.report(Error(i.statusText));return i.text()}).then((i)=>{let n={href:t,html:i};return this.cache.set(t,n),n}).finally(()=>delete this.loader[t]),this.loader[t]}async function x(e,{history:t}={}){let r;try{r=d(e,"pre.open():");let[o,...i]=r.split("#"),n=i.join("#");if(n&&o===location.href.split("#")[0]){location.hash=n;return}let s=await this.load(r);return await this.replace(r,s.html,{history:t}),this.init()}catch(o){if(this.report(o),r)location.href=r}}var P=(e,t,r)=>new Promise((o,i)=>{if(r[e.src])return o();let n=document.createElement("script");if(e.src){n.addEventListener("load",()=>o()),n.addEventListener("error",i),n.src=e.src,t.appendChild(n);return}n.appendChild(document.createTextNode(`(() => {${e.textContent}})();`)),t.appendChild(n),o()});function w(e,t,{history:r=!0}={}){if(r)window.history.pushState({href:e},"",e);let o=new DOMParser().parseFromString(t,"text/html"),i=document.body;i.replaceChildren(...o.body.childNodes),this.head(document.head,o.head);let n=e.split("#").slice(1).join("#"),s=n?document.getElementById(n):null;if(s)s.scrollIntoView();else window.scrollTo(0,0);let c=([h,...A])=>{if(!h)return Promise.resolve();return P(h,i,this.loaded).then(()=>c(A))},p=a("script").filter((h)=>!h.hasAttribute(this.attrs.ignore));return c(p)}class v{attrs;loader={};loaded={};started=!1;cache=new l(100,1e4);follows=f;init=g;load=m;preload=m;open=x;links=E;head=u;replace=w;report=(e)=>console.log("Error:",e);constructor({attrs:e}={}){this.attrs={once:"data-pre-once",ignore:"data-pre-ignore",keep:"data-pre-keep",cache:"data-pre-cached",...e},this.cache.onchange=()=>this.links(),window.addEventListener("popstate",()=>{this.open(location.href,{history:!1})}),this.init()}}var b=v;if(!window.pre)window.pre=new b;})();

package/package.json

@@ -1,37 +1,35 @@
 {
   "name": "premonition",
-  "version": "0.6.2",
-  "description": "Convert your website to a Progressive Web App with a single link. Or just make it faster, it's up to you. Include the script in your website to see it work:",
-  "main": "index.min.js",
-  "scripts": {
-    "build": "rollup -c",
-    "prepublishOnly": "npm run build && git add index.min.js && git commit -m \"Built package\"",
-    "test": "echo \"Error: no test so far\"",
-    "watch": "rollup -c --watch"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/franciscop/premonition.git"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.8.0",
+  "description": "Make your website load instantly by preloading links and swapping pages in place",
+  "repository": "github:franciscop/premonition",
+  "author": "Francisco Presencia <public@francisco.io> (https://francisco.io/)",
+  "funding": "https://www.paypal.me/franciscopresencia/19",
   "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/franciscop/premonition/issues"
+  "keywords": [
+    "spa",
+    "preload",
+    "prefetch",
+    "performance",
+    "navigation",
+    "browser"
+  ],
+  "scripts": {
+    "build": "bun build src/browser.ts --outfile=index.min.js --format=iife --minify",
+    "demo": "bun demo/server.ts",
+    "lint": "tsc",
+    "size": "echo $(gzip -c index.min.js | wc -c) bytes",
+    "start": "bun test --watch",
+    "test": "bun test"
   },
-  "homepage": "https://github.com/franciscop/premonition#readme",
+  "main": "index.min.js",
+  "type": "module",
+  "files": [
+    "index.min.js"
+  ],
   "devDependencies": {
-    "babel-core": "^6.26.3",
-    "babel-plugin-external-helpers": "^6.22.0",
-    "babel-preset-env": "^1.7.0",
-    "builtin-modules": "^3.0.0",
-    "picnic": "^6.5.0",
-    "rollup": "^0.62.0",
-    "rollup-plugin-babel": "^3.0.5",
-    "rollup-plugin-babel-minify": "^5.0.0",
-    "rollup-plugin-commonjs": "^9.1.3",
-    "rollup-plugin-node-resolve": "^3.3.0",
-    "rollup-plugin-uglify": "^4.0.0",
-    "tiny-lru": "^1.6.1"
+    "@happy-dom/global-registrator": "^20.9.0",
+    "@types/bun": "^1.3.0",
+    "typescript": "5.9"
   }
 }

package/readme.md

@@ -1,140 +1,156 @@
----
-title: premonition.js
-layout: home.hbs
----
+# premonition [![npm install premonition](https://img.shields.io/badge/npm%20install-premonition-blue.svg)](https://www.npmjs.com/package/premonition) [![test badge](https://github.com/franciscop/premonition/workflows/tests/badge.svg "test badge")](https://github.com/franciscop/premonition/actions) [![gzip size](https://img.badgesize.io/franciscop/premonition/master/index.min.js.svg?label=gzip&logo=&compression=gzip)](https://github.com/franciscop/premonition/blob/master/index.min.js) [![dependencies](https://img.shields.io/badge/dependencies-0-limegreen.svg)](https://github.com/franciscop/premonition/blob/master/package.json)
 
-# Preload App
+Make your website load instantly: links are fetched when the user hovers them, and opening one swaps the page in place instead of doing a full reload.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/premonition"></script>
+```
+
+That is the whole setup. Every same-site link on the page is now preloaded on hover and opened without a page reload.
 
 > **Early experiment**, use at your own [high] risk.
 
-Make your website load *very* fast. Converts your website to a Single Page Application. Or just make it faster, it's up to you. Include the script in your website to see it work:
+## Getting started
+
+Load it from a CDN, which needs no build step and no configuration:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/premonition" data-pre-once></script>
+<script src="https://cdn.jsdelivr.net/npm/premonition"></script>
 ```
 
-That's it, your website should be noticeably faster now. You can use the [Javascript API](#api) or configure it [with the options](#options). See [the troubleshooting guide](#troubleshooting) if you have any issue.
+Or install it and import it, which does the same setup and defines the same `pre` global:
 
-> **Experiment tip**: open [the CDN link](https://cdn.jsdelivr.net/npm/premonition), copy the JS and paste it into your website console for testing this project in a real env in ~10s. If there's any error you'll have to do this again.
+```bash
+npm install premonition
+```
 
+```js
+import 'premonition';
+```
 
+Either way there is nothing to call: premonition hooks up the page as soon as it loads.
 
-## API
+## Usage
 
-You now have this API available:
+Premonition attaches itself to every `<a>` on the page that points to the same site, and then:
 
-```js
-// Parse the full current website from scratch
-pre.init(MODE);   // Note: it is called onload
+1. On `mouseover` or `touchstart`, it fetches the target page and keeps the HTML in memory.
+2. On `click`, it swaps the current `<body>` and `<head>` for the new ones and pushes the URL to the history, so the back button keeps working.
 
-// Open the passed urls or link element
-pre.open(URL);
+It leaves these link types alone, because swapping the body would break things: other hosts, `target="_blank"`, `download`, schemes like `mailto:` or `tel:`, bare `#fragment` links, and anything marked with `data-pre-ignore`.
 
-// [pre]load a link into memory for later opening
-pre.load(URL);
+The cache holds the 100 most recent pages for 10 seconds each, in memory only: a real page reload clears it.
 
-// Replace the current page by a new url+html
-pre.replace('/hello', '<html>...</html>');
+Three attributes change what premonition does with a given element, and they are how you fix a script or a link that misbehaves across page swaps.
 
-// Cache instance. Using tiny-lru: https://www.npmjs.com/package/tiny-lru
-pre.cache = lru(100, false, 0, 100000);
-pre.cache.get(HREF);
-// cache.set is mostly internal; highly prefer pre.load(HREF)
-pre.cache.set(HREF, { href: HREF, html: HTML });
-pre.cache.expire = 1000;  // Maximum time of the page
-pre.cache.clear();        // Remove all items from cache (login/logout)
+### `once`
 
-// All events happen just BEFORE the actual name, so they can be prevented
-// NOTE: not available yet
-pre.on('ready', e => {});         // The DOM is ready to be used
-pre.on('init', e => {});          // The script initialization is called
-pre.on('load', e => {});          // A single URL is attempted to be preloaded
-pre.on('preload', e => {});       // Alias for 'load'
-pre.on('open', e => {});          // An HREF is going to be open (load+replace)
-pre.on('replace', e => {});       // The website content is going to be updated
-pre.on('fetch', e => {});         // A HREF is going to be fetched
-pre.on('error', e => {});         // There is an error somewhere
-pre.on('cache.get', e => {});     // When a link is read from cache
-pre.on('cache.set', e => {});     // Update the cache with more HREF+HTML
-pre.on('cache.remove', e => {});  // Some HTML is removed from the cache
+Evaluate a `<script>` only once, even when it is also in the new page:
+
+```html
+<script src="..." data-pre-once></script>
 ```
 
+If the script `src` is not in the old page but is in the new one, it runs. If it already ran, it is skipped.
 
+**Add this option** to libraries that only define a global API, since they should only run once:
 
-## Options
+- jQuery.js
+- moment.js
+- etc.
 
-There are global options and per-element options:
+**Do not add it** to scripts that run against the current HTML, since those need to run again with the new HTML:
 
-- Global options can be specified on the `<body>` element or when calling `pre.init({ OPTIONS })`.
-- Element options should be specified in the element (e.g., `<script>`) or when calling the specific method.
+- prism.js: it highlights the code snippets on the page, so it needs to run on every page load.
+- etc.
 
-When using HTML elements, they are always prefixed by `data-pre-NAME=""` (except `data-pre=""`, which is the mode).
+### `ignore`
 
-Examples:
+Premonition will completely ignore the element:
 
 ```html
-<body data-pre="pwa">
-<body data-pre="pwa" data-pre-expire="100s">
-<body data-pre="pwa" data-pre-expire="100s" data-pre-elements="100">
-<body data-pre="preload">
+<a href="/logout" data-pre-ignore>Log out</a>
+<script src="..." data-pre-ignore></script>
 ```
 
+Useful for links you do not want preloaded, and for scripts you do not want re-evaluated. Inline scripts that must only run on a real page load are the common case: we cannot stop them on a full refresh, but we can avoid re-running them here.
 
+For links that change state, we would recommend following the HTTP specification instead, so that links only make GET requests with no side effects, and side effects live in a `<form>`.
 
-### Mode `data-pre-mode`
+Comparing the three ways a script from the new page can be treated:
 
-There are several modes that you can tweak within the `<body>` tag:
+- `<script src="..."></script>`: run it after the new HTML is in place.
+- `<script src="..." data-pre-once></script>`: run it only if the `src` did not run before.
+- `<script src="..." data-pre-ignore></script>`: never run it.
 
-```html
-<body data-pre="pwa">...</body>
-<body data-pre="preload">...</body>
-<body data-pre="spa">...</body>
-<body data-pre="off">...</body>
-```
-
-These are useful depending on your type of website and desired performance boost:
+### `cached`
 
-- `pwa` (Progressive Web App): the most aggressive one, will load and cache all the internal pages linked from the current page for 24h. Note: still needs a `manifest.json` to actually become a PWA.
-- `preload`: will fetch the link when hovering a link for significantly faster loading. Cache the pages for 100 seconds.
-- `spa` (Single Page Application): will fetch the page onmousedown and load the new page in-body. Make the page seem slightly faster. Cache the pages for 10 seconds.
-- `off`: will not try to load or cache anything. You can now call the different methods to hook up specific link in specific situations.
+Premonition sets `data-pre-cached` on the links whose page is currently in the cache, and removes it when it is not. It is written by the library, not by you, and it is there so you can style preloaded links:
 
-**Default mode**: In normal web usage it will use `preload`, but if it detects it's installed in a device as a PWA it will trigger the `pwa` mode. If you want tight control specify the mode manually as shown above.
-
-> The cache is only in-memory; any page reload or the PWA getting closed will clear it.
+```css
+a[data-pre-cached] { border-bottom: 1px solid green; }
+```
 
-#### Picking a mode
+## Javascript API
 
-The mode will determine how aggressively the preload and cache is used and your users data consumption. Until you get used to the details, just don't pick a mode and let premonition.js choose for you.
+> **You do not need any of this.** The script tag sets everything up on its own.
+> The calls below are for the few things it cannot do for you: clearing the cache when
+> someone logs in or out, hooking up links that your own Javascript added after the
+> page loaded, and sending errors somewhere other than the console.
 
-Premonition *only* loads the html and scripts (see [skipping scripts](#load-once)). These normally are quite light and ~10-20 average HTML pages are the equivalent of a single image. So, if your site is fairly small, `pwa` is the recommended way to go.
+Loading it as a `<script>` exposes the instance as the `pre` global:
 
-If you are in the middle-ground, then `preload` is nice in that it will boost greatly page load speed while only preloading selectively those links that are hovered.
+```js
+// Parse the current page and hook up its links. Called automatically onload
+pre.init(SELECTOR); // default: 'a'
 
-If you want a very light experience without any wasted requests for the user but still slightly faster loads, then use the `spa` mode. It has slightly better performance in mobile (300ms).
+// Open a url or <a> element, loading it first if it is not cached yet
+pre.open(URL);
 
-Finally, turn it off if you want to manually and selectively load links in some situations. Use this to load links only when they become visible on scrolling for example.
+// Preload a url or <a> element into memory for a later .open()
+pre.load(URL);
+pre.preload(URL); // Alias for .load()
 
+// Replace the current page with a new url + html
+pre.replace('/hello', '<html>...</html>');
 
+// Update the data-pre-cached attributes. Called automatically on cache changes
+pre.links(SELECTOR); // default: 'a'
 
-### Load Once
+// Called with any error that happens along the way; overwrite it to report them
+pre.report = error => console.log('Error:', error);
+```
 
-Evaluate the script only once even if it's available in the new page:
+The cache is a small LRU store that you can read and clear directly:
 
-```html
-<script src="..." data-pre-once></script>
+```js
+pre.cache.get(HREF);      // Returns { href, html } or undefined
+pre.cache.set(HREF, { href: HREF, html: HTML });  // Prefer pre.load(HREF)
+pre.cache.keys();         // The hrefs currently cached
+pre.cache.clear();        // Remove all items from cache (login/logout)
+pre.cache.max = 100;      // Maximum number of pages kept
+pre.cache.ttl = 10000;    // Milliseconds before a page is considered stale
 ```
 
-This *does not work with inline scripts* since there's no way to identify those otherwise. If you want to ignore a script from one page in another page, you can set `data-pre-ignore` for anything:
+## Demo
 
-```html
-<script src="..." data-pre-ignore></script>
+There is a small site under `demo/` to try it by hand. Its pages are served with an
+artificial delay, so the difference between a cold click and a preloaded one is easy to see:
+
+```bash
+npm run build && npm run demo   # http://localhost:3200/demo/
 ```
 
+## FAQ
 
+### What about [InstantClick](http://instantclick.io/)?
 
+I love it, it was the main inspiration for Premonition. However it is ridden with bugs and [development seems to be stopped](https://github.com/dieulot/instantclick/), with [pull requests languishing](https://github.com/dieulot/instantclick/pulls). These were show-stoppers for me:
 
+- No cache: moving the mouse around fetches the same links again and again.
+- Important [race conditions](https://github.com/dieulot/instantclick/pull/85): you never know which script finishes first, which leads to bugs. Premonition loads the scripts sequentially.
+- Plug and play: I wanted to drop the script into a project and have it work by default, while InstantClick is more oriented towards using its API.
 
-## Troubleshooting
+### What about [Turbolinks](https://github.com/turbolinks/turbolinks)?
 
-**Very early experiment**, [contact me](https://francisco.io/) if you need any help.
+Another very nice project, with a smaller scope: it swaps pages on click, while Premonition also preloads them on hover.

package/.babelrc

@@ -1,11 +0,0 @@
-{
-  "presets": [
-    ["env", {
-      "modules": false,
-      "targets": { "uglify": true }
-    }]
-  ],
-  "plugins": [
-    "external-helpers"
-  ]
-}

package/demo/_post.hbs

@@ -1,30 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <title>{{title}}</title>
-  <link rel="stylesheet" href="/web/style.min.css">
-</head>
-<body>
-  <nav>
-    <a class="brand" href="/">premonition.js</a>
-    <div class="menu">
-      <a href="/demo">Demo</a>
-      <a href="https://github.com/franciscop/premonition">Github</a>
-    </div>
-  </nav>
-
-  <article>
-    <a href="/demo/">All Articles</a>
-    {{{body}}}
-    {{> readnext}}
-  </article>
-  Hello
-  <script src="/index.min.js" data-pre-once></script>
-  <script type="text/javascript">
-    console.log('NO PARSING NEEDED');
-  </script>
-</body>
-</html>

package/demo/_readnext.hbs

@@ -1,3 +0,0 @@
-<h2>Read Next</h2>
-
-Example of a partial to see how they work

package/demo/entry-a/index.html

@@ -1,35 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <title>Entry A</title>
-  <link rel="stylesheet" href="/web/style.min.css">
-</head>
-<body>
-  <nav>
-    <a class="brand" href="/">premonition.js</a>
-    <div class="menu">
-      <a href="/demo">Demo</a>
-      <a href="https://github.com/franciscop/premonition">Github</a>
-    </div>
-  </nav>
-
-  <article>
-    <a href="/demo/">All Articles</a>
-    <h1 id="entry-a">Entry A</h1>
-<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
-<p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
-
-    <h2>Read Next</h2>
-    
-    Example of a partial to see how they work
-  </article>
-  Hello
-  <script src="/index.min.js" data-pre-once></script>
-  <script type="text/javascript">
-    console.log('NO PARSING NEEDED');
-  </script>
-</body>
-</html>

package/demo/entry-a/readme.md

@@ -1,12 +0,0 @@
----
-layout: post.hbs
-title: Entry A
-date: 2018-06-19 20:00
-categories: jekyll mini clone
----
-
-# Entry A
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

package/demo/entry-b/index.html

@@ -1,35 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <title>Entry B</title>
-  <link rel="stylesheet" href="/web/style.min.css">
-</head>
-<body>
-  <nav>
-    <a class="brand" href="/">premonition.js</a>
-    <div class="menu">
-      <a href="/demo">Demo</a>
-      <a href="https://github.com/franciscop/premonition">Github</a>
-    </div>
-  </nav>
-
-  <article>
-    <a href="/demo/">All Articles</a>
-    <h1 id="entry-b">Entry B</h1>
-<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
-<p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
-
-    <h2>Read Next</h2>
-    
-    Example of a partial to see how they work
-  </article>
-  Hello
-  <script src="/index.min.js" data-pre-once></script>
-  <script type="text/javascript">
-    console.log('NO PARSING NEEDED');
-  </script>
-</body>
-</html>

package/demo/entry-b/readme.md

@@ -1,12 +0,0 @@
----
-layout: post.hbs
-title: Entry B
-date: 2018-06-19 20:00
-categories: jekyll mini clone
----
-
-# Entry B
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

package/demo/entry-c/index.html

@@ -1,35 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <title>Entry C</title>
-  <link rel="stylesheet" href="/web/style.min.css">
-</head>
-<body>
-  <nav>
-    <a class="brand" href="/">premonition.js</a>
-    <div class="menu">
-      <a href="/demo">Demo</a>
-      <a href="https://github.com/franciscop/premonition">Github</a>
-    </div>
-  </nav>
-
-  <article>
-    <a href="/demo/">All Articles</a>
-    <h1 id="entry-c">Entry C</h1>
-<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
-<p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
-
-    <h2>Read Next</h2>
-    
-    Example of a partial to see how they work
-  </article>
-  Hello
-  <script src="/index.min.js" data-pre-once></script>
-  <script type="text/javascript">
-    console.log('NO PARSING NEEDED');
-  </script>
-</body>
-</html>

package/demo/entry-c/readme.md

@@ -1,12 +0,0 @@
----
-layout: post.hbs
-title: Entry C
-date: 2018-06-19 20:00
-categories: jekyll mini clone
----
-
-# Entry C
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

package/demo/entry-d/index.html

@@ -1,35 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <title>Entry D</title>
-  <link rel="stylesheet" href="/web/style.min.css">
-</head>
-<body>
-  <nav>
-    <a class="brand" href="/">premonition.js</a>
-    <div class="menu">
-      <a href="/demo">Demo</a>
-      <a href="https://github.com/franciscop/premonition">Github</a>
-    </div>
-  </nav>
-
-  <article>
-    <a href="/demo/">All Articles</a>
-    <h1 id="entry-d">Entry D</h1>
-<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
-<p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
-
-    <h2>Read Next</h2>
-    
-    Example of a partial to see how they work
-  </article>
-  Hello
-  <script src="/index.min.js" data-pre-once></script>
-  <script type="text/javascript">
-    console.log('NO PARSING NEEDED');
-  </script>
-</body>
-</html>

package/demo/entry-d/readme.md

@@ -1,12 +0,0 @@
----
-layout: post.hbs
-title: Entry D
-date: 2018-06-19 20:00
-categories: jekyll mini clone
----
-
-# Entry D
-
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
-
-Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

package/demo/entry-e/index.html

@@ -1,35 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <title>Entry E</title>
-  <link rel="stylesheet" href="/web/style.min.css">
-</head>
-<body>
-  <nav>
-    <a class="brand" href="/">premonition.js</a>
-    <div class="menu">
-      <a href="/demo">Demo</a>
-      <a href="https://github.com/franciscop/premonition">Github</a>
-    </div>
-  </nav>
-
-  <article>
-    <a href="/demo/">All Articles</a>
-    <h1 id="entry-e">Entry E</h1>
-<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
-<p>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
-
-    <h2>Read Next</h2>
-    
-    Example of a partial to see how they work
-  </article>
-  Hello
-  <script src="/index.min.js" data-pre-once></script>
-  <script type="text/javascript">
-    console.log('NO PARSING NEEDED');
-  </script>
-</body>
-</html>