premonition 0.7.0 → 0.8.0

package/index.min.js

@@ -1,2 +1 @@
-/* premonition@0.7.0 · 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.7.0",
-  "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,194 +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
-
-> **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:
+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" 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.
-
-> **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.
-
-
-
-## API
-
-You now have this API available:
+That is the whole setup. Every same-site link on the page is now preloaded on hover and opened without a page reload.
 
-```js
-// Parse the full current website from scratch
-pre.init(OPTS);   // Note: it is called onload
-
-// Open the passed urls or link element
-pre.open(URL);
-
-// [pre]load a link into memory for later opening
-pre.load(URL);
-
-// Replace the current page by a new url+html
-pre.replace('/hello', '<html>...</html>');
-
-// 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)
-
-// 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
-```
-
-
-
-## Options
-
-There are global options and per-element options:
-
-- 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.
+> **Early experiment**, use at your own [high] risk.
 
-When using HTML elements, they are always prefixed by `data-pre-NAME=""` (except `data-pre=""`, which is the mode).
+## Getting started
 
-Examples:
+Load it from a CDN, which needs no build step and no configuration:
 
 ```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">
+<script src="https://cdn.jsdelivr.net/npm/premonition"></script>
 ```
 
+Or install it and import it, which does the same setup and defines the same `pre` global:
 
-
-### `mode`
-
-There are several modes that you can tweak within the `<body>` tag:
-
-```html
-<body data-pre="pwa">...</body>
-<body data-pre="preload">...</body>
-<body data-pre="spa">...</body>
-<body data-pre="off">...</body>
+```bash
+npm install premonition
 ```
 
-These are useful depending on your type of website and desired performance boost:
-
-- `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.
-
-**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.
-
-#### Picking a mode
+```js
+import 'premonition';
+```
 
-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.
+Either way there is nothing to call: premonition hooks up the page as soon as it loads.
 
-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.
+## Usage
 
-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.
+Premonition attaches itself to every `<a>` on the page that points to the same site, and then:
 
-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).
+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.
 
-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.
+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`.
 
+The cache holds the 100 most recent pages for 10 seconds each, in memory only: a real page reload clears it.
 
+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.
 
 ### `once`
 
-Evaluate a `<script>` only once ever even if it's in the new page:
+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 target does not exist in the old page but exists in the new page, it will be run. If it already exists in the old page, it will be skipped.
+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:
 
-**Add this option** for these kind of libraries since they *only define a global API* so we only want them to run once:
 - jQuery.js
 - moment.js
 - etc.
 
-**Do not add** to scripts that run some code against the current HTML since those will very likely need to run it with the new HTML:
-- Inline scripts (will be ignored). To avoid re-rendering inline scripts, see [the option ignore](#ignore).
-- prism.js: this will automatically highlight the page code snippets, so it needs to be run on every pageload.
+**Do not add it** to scripts that run against the current HTML, since those need to run again with the new HTML:
+
+- prism.js: it highlights the code snippets on the page, so it needs to run on every page load.
 - etc.
 
-Compare the options for loading a script from the new page:
+### `ignore`
 
-- `<script src="..."></script>`: run the full script after the HTML has loaded.
-- `<script src="..." data-pre-once></script>`: run the script only if the `src` is not in the previous page(s).
-- `<script src="..." data-pre-ignore></script>`: completely ignore the script. Will not be run at all in any case.
+Premonition will completely ignore the element:
 
+```html
+<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.
 
-### `ignore`
+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>`.
 
-Premonition will completely ignore a script, link, etc. with this option:
+Comparing the three ways a script from the new page can be treated:
 
-```html
-<a href="/logout" data-pre-ignore></script>
-<script src="..." data-pre-ignore></script>
+- `<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.
+
+### `cached`
+
+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:
+
+```css
+a[data-pre-cached] { border-bottom: 1px solid green; }
 ```
 
-This is useful for some links that you do not want preloaded or scripts that you do not want re-evaluated. Examples:
+## Javascript API
 
-- Inline scripts that must be run only onload. We cannot prevent those from running on a full page refresh, but we can avoid re-running those.
-- Links that are making a request that changes some state. We would recommend in this situation to follow the `HTTP` specification, so links only do GET requests which have no side effects. Leave side effects for `<form>`.
+> **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.
 
-Compare the options for loading a script from the new page:
+Loading it as a `<script>` exposes the instance as the `pre` global:
 
-- `<script src="..."></script>`: run the full script after the HTML has loaded.
-- `<script src="..." data-pre-once></script>`: run the script only if the `src` is not in the previous page(s).
-- `<script src="..." data-pre-ignore></script>`: completely ignore the script. Will not be run at all in any case.
+```js
+// Parse the current page and hook up its links. Called automatically onload
+pre.init(SELECTOR); // default: 'a'
 
+// Open a url or <a> element, loading it first if it is not cached yet
+pre.open(URL);
 
+// Preload a url or <a> element into memory for a later .open()
+pre.load(URL);
+pre.preload(URL); // Alias for .load()
 
-## Troubleshooting
+// Replace the current page with a new url + html
+pre.replace('/hello', '<html>...</html>');
 
-**Very early experiment**, [please open an issue](https://github.com/franciscop/premonition) if you need any help.
+// Update the data-pre-cached attributes. Called automatically on cache changes
+pre.links(SELECTOR); // default: 'a'
 
+// Called with any error that happens along the way; overwrite it to report them
+pre.report = error => console.log('Error:', error);
+```
 
+The cache is a small LRU store that you can read and clear directly:
 
-## FAQ, credit and alternatives
+```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
+```
 
-### What about [Instant Click](http://instantclick.io/)?
+## Demo
 
-I love it! It was the main inspiration for Premonition.js. 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 bugs/lack of features were show-stoppers for me:
+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:
 
-- No cache. This means that if you move your mouse around, the links will be fetched again and again.
-- Important [race conditions](https://github.com/dieulot/instantclick/pull/85): you never know which script will finish first, which will definitely lead to bugs. I fixed this by loading the scripts sequentially.
-- Plug-n-play: I would like to just drop the script into some of my projects, so I worked very hard to make this work by default. Instantclick seems to be more oriented to using the API.
+```bash
+npm run build && npm run demo   # http://localhost:3200/demo/
+```
 
+## FAQ
 
-### What about [Turbolinks](https://github.com/turbolinks/turbolinks)?
+### What about [InstantClick](http://instantclick.io/)?
 
-Another very awesome project. However, its scope seems to be a lot smaller. The similar feature with Premonition is `mode: spa`. Use Turbolinks if you want a very well tested and documented library, use Premonition if you want faster pages.
+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.
 
-### Why do you use [Tiny-LRU](https://github.com/avoidwork/tiny-lru)?
+### What about [Turbolinks](https://github.com/turbolinks/turbolinks)?
 
-Because it is awesome! The LRU algorithm ensures that only the most recent URLs are cached, improving the memory usage and reducing the cache misses.
+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>