├── .gitignore
├── .flowconfig
├── .babelrc
├── .github
    └── workflows
    │   └── test.yml
├── src
    ├── backend
    │   ├── httpGet.js
    │   ├── local.js
    │   ├── index.js
    │   └── gist.js
    ├── parse.js
    ├── cache.js
    ├── components.js
    ├── basic.js
    └── index.js
├── test
    ├── parse.test.js
    └── index.test.js
├── .eslintrc.js
├── dist
    ├── index.html
    └── style.css
├── webpack.config.js
├── CONTRIBUTING.md
├── LICENSE
├── package.json
├── README.md
└── jest.config.js


/.gitignore:
--------------------------------------------------------------------------------
1 | /node_modules
2 | /dist/main.js*
3 | /dist/dev
4 | 


--------------------------------------------------------------------------------
/.flowconfig:
--------------------------------------------------------------------------------
1 | [strict]
2 | nonstrict-import
3 | unclear-type
4 | unsafe-getters-setters
5 | untyped-import
6 | untyped-type-import


--------------------------------------------------------------------------------
/.babelrc:
--------------------------------------------------------------------------------
 1 | {
 2 |   "presets": [
 3 |     [
 4 |       "@babel/preset-env",
 5 |       {
 6 |         "useBuiltIns": "usage"
 7 |       }
 8 |     ],
 9 |     "@babel/preset-flow"
10 |   ]
11 | }


--------------------------------------------------------------------------------
/.github/workflows/test.yml:
--------------------------------------------------------------------------------
 1 | name: Test, lint, and type check
 2 | on: [push, pull_request]
 3 | jobs:
 4 |   build:
 5 |     runs-on: ubuntu-latest
 6 |     steps:
 7 |       - uses: actions/checkout@v2
 8 |       - name: Use Node.js
 9 |         uses: actions/setup-node@v1
10 |         with:
11 |           node-version: 14.x
12 |       - run: npm install
13 |       - run: npm run lint
14 |       - run: npm run flow
15 |       - run: npm test


--------------------------------------------------------------------------------
/src/backend/httpGet.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | //
 4 | // Sends a HTTP GET request to `url`.
 5 | //
 6 | export default function (url: string): Promise<string> {
 7 |   return new Promise((resolve, reject) => {
 8 |     const xhr = new XMLHttpRequest()
 9 |     xhr.open("GET", url)
10 |     xhr.onload = () => {
11 |       if (xhr.status >= 200 && xhr.status < 300) {
12 |         resolve(xhr.responseText)
13 |       } else {
14 |         reject(xhr.statusText)
15 |       }
16 |     }
17 |     xhr.send()
18 |   })
19 | }
20 | 


--------------------------------------------------------------------------------
/test/parse.test.js:
--------------------------------------------------------------------------------
 1 | import parse from "../src/parse"
 2 | 
 3 | describe("parse", () => {
 4 |   test("parses the gist id", () => {
 5 |     expect(parse("#gist-id")).toContain("gist-id")
 6 |   })
 7 | 
 8 |   test("returns 'index' as the default scene", () => {
 9 |     expect(parse("#gist-id")).toContain("index")
10 |   })
11 | 
12 |   test("returns 'index' as the root scene", () => {
13 |     expect(parse("#gist-id/")).toContain("index")
14 |   })
15 | 
16 |   test("returns the correct scene", () => {
17 |     expect(parse("#gist-id/foo")).toContain("foo")
18 |   })
19 | 
20 |   test("returns the correct sub-scene", () => {
21 |     expect(parse("#gist-id/foo/bar")).toContain("foo/bar")
22 |   })
23 | })
24 | 


--------------------------------------------------------------------------------
/.eslintrc.js:
--------------------------------------------------------------------------------
 1 | module.exports = {
 2 |   "env": {
 3 |     "node": true,
 4 |     "browser": true,
 5 |     "es6": true
 6 |   },
 7 |   "plugins": [
 8 |     "jest",
 9 |     "flowtype"
10 |   ],
11 |   "extends": [
12 |     "eslint:recommended",
13 |     "plugin:jest/recommended",
14 |     "plugin:flowtype/recommended"
15 |   ],
16 |   "parser": "babel-eslint",
17 |   "parserOptions": {
18 |     "ecmaVersion": 2015,
19 |     "sourceType": "module"
20 |   },
21 |   "rules": {
22 |     "indent": [
23 |       "error",
24 |       2,
25 |       { "SwitchCase": 1 }
26 |     ],
27 |     "linebreak-style": [
28 |       "error",
29 |       "unix"
30 |     ],
31 |     "quotes": [
32 |       "error",
33 |       "double"
34 |     ],
35 |     "semi": [
36 |       "error",
37 |       "never"
38 |     ]
39 |   }
40 | }
41 | 


--------------------------------------------------------------------------------
/dist/index.html:
--------------------------------------------------------------------------------
 1 | <!DOCTYPE html>
 2 | <head>
 3 |   <title>gist-txt</title>
 4 |   <meta charset="utf-8">
 5 |   <meta name="viewport" content="width=device-width, initial-scale=1">
 6 |   <meta name="apple-mobile-web-app-capable" content="yes">
 7 |   <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
 8 |   <link rel="stylesheet" type="text/css" href="style.css">
 9 | </head>
10 | <body>
11 |   <div id="error"></div>
12 |   <div id="loading">Loading...</div>
13 |   <div id="content"></div>
14 | 
15 |   <footer style="display: none">
16 |     Source: <a id="source"></a>
17 |     <br>
18 |     Created with <a href="https://github.com/potomak/gist-txt">gist-txt</a>
19 |     by <a rel="author">Anonymous</a>
20 |     <br>
21 |     <a href="text-adventures.html">More text adventures</a>
22 |   </footer>
23 | 
24 |   <script src="main.js"></script>
25 | </body>
26 | 


--------------------------------------------------------------------------------
/src/backend/local.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | //
 4 | // Local backend
 5 | //
 6 | 
 7 | export type Config = { storage: "local", path: string }
 8 | 
 9 | var path: string
10 | 
11 | //
12 | // Initializes the backend using the input configuration.
13 | //
14 | // The initialization of the local storage backend consists just of storing the
15 | // the value of the `path` configuration property, that is the path in the local
16 | // development server from where content should be served.
17 | //
18 | function init(config: Config): Promise<void> {
19 |   path = config.path
20 |   return Promise.resolve()
21 | }
22 | 
23 | //
24 | // Returns the URL of the file referenced by `filename`.
25 | //
26 | // The URL is a path to the file served from a local development server.
27 | //
28 | function fileURL(filename: string): Promise<string> {
29 |   return Promise.resolve(`${path}/${filename}`)
30 | }
31 | 
32 | export default {
33 |   init,
34 |   fileURL
35 | }
36 | 


--------------------------------------------------------------------------------
/webpack.config.js:
--------------------------------------------------------------------------------
 1 | var path = require('path');
 2 | var webpack = require('webpack');
 3 | 
 4 | module.exports = {
 5 |   entry: './src/index.js',
 6 |   output: {
 7 |     filename: 'main.js',
 8 |     path: path.resolve(__dirname, 'dist')
 9 |   },
10 |   module: {
11 |     rules: [
12 |       {
13 |         test: /\.js$/,
14 |         exclude: /node_modules/,
15 |         use: {
16 |           loader: 'babel-loader',
17 |           options: {
18 |             presets: ['@babel/preset-env']
19 |           }
20 |         }
21 |       }
22 |     ]
23 |   },
24 |   // Fixes "Error: Can't resolve 'buffer'" in js-yaml
25 |   // Can be removed after upgrading to js-yaml >= 4.1
26 |   // See https://github.com/nodeca/js-yaml/commit/c15d424448108771708eb942515b06020ecfe84c
27 |   // See also https://github.com/webpack/changelog-v5/issues/10
28 |   plugins: [
29 |     new webpack.ProvidePlugin({
30 |       Buffer: ["buffer", "Buffer"],
31 |       process: "process",
32 |     }),
33 |   ],
34 |   devtool: 'source-map'
35 | };
36 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | # Contributing
 2 | 
 3 | Fork, then clone the repo:
 4 | 
 5 | ```sh
 6 | git clone git@github.com:your-username/gist-txt.git
 7 | ```
 8 | 
 9 | Install npm dependencies:
10 | 
11 | ```sh
12 | npm install
13 | ```
14 | 
15 | Continuously build a development version of the bundle:
16 | 
17 | ```sh
18 | npm run-script watch
19 | ```
20 | 
21 | Run a local HTTP server:
22 | 
23 | ```sh
24 | npm run-script serve
25 | ```
26 | 
27 | Once you're finished with your work, push to your fork and [submit a pull
28 | request](https://github.com/potomak/gist-txt/compare/).
29 | 
30 | At this point you're waiting on us. We like to at least comment on pull requests
31 | within three business days (and, typically, one business day). We may suggest
32 | some changes or improvements or alternatives.
33 | 
34 | Some things that will increase the chance that your pull request is accepted:
35 | 
36 | * write tests
37 | * be consistent
38 | * write a [good commit
39 |   message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
40 | 


--------------------------------------------------------------------------------
/src/parse.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | //
 4 | // A gist-txt location hash has the form:
 5 | //
 6 | //     #<gist-id>/<scene>
 7 | //
 8 | // To parse the hash:
 9 | //
10 | // 1. remove the '#' refix
11 | // 2. split the remaining string by '/'
12 | // 3. assign the first *segment* to the global variable `gistId`
13 | // 4. join the remaining segments with '/'
14 | //
15 | // Note: gists' files can't include the '/' character in the name so, even if
16 | // the remaining portion of the segments array is joined by '/', that array
17 | // should always contain at most one element.
18 | //
19 | // If the scene name is blank return 'index', the default name of the main
20 | // scene, otherwise return the scene name found.
21 | //
22 | export default function (hash: string): [string, string] {
23 |   const path = hash.slice(1)
24 |   const segments = path.split("/")
25 |   const gistId = segments.shift()
26 |   let scene = segments.join("/")
27 | 
28 |   if (scene === "") {
29 |     scene = "index"
30 |   }
31 | 
32 |   return [gistId, scene]
33 | }
34 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2015 Giovanni Cappellotto
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 
23 | 


--------------------------------------------------------------------------------
/src/cache.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | //
 4 | // Cache
 5 | //
 6 | // For now the cache is implemented as a simple JavaScript object.
 7 | //
 8 | 
 9 | // $FlowFixMe - Unclear type
10 | var data: { [string]: any } = {}
11 | 
12 | //
13 | // Returns a promise that resolves with the content indexed by `key` in the
14 | // cache or rejects in case the `key` is invalid.
15 | //
16 | // $FlowFixMe - Unclear type
17 | function get(key: string): Promise<any> {
18 |   if (data[key] === undefined) {
19 |     return Promise.reject("Cache miss")
20 |   }
21 | 
22 |   return Promise.resolve(data[key])
23 | }
24 | 
25 | //
26 | // Adds a reference `key` to `value` in the cache and returns a promise that
27 | // trivially resolves with `value`.
28 | //
29 | // $FlowFixMe - Unclear type
30 | function set(key: string, value: any): Promise<any> {
31 |   data[key] = value
32 | 
33 |   return Promise.resolve(value)
34 | }
35 | 
36 | //
37 | // It invalidates the whole cache.
38 | //
39 | // This function is useful for resetting the cache while testing the game
40 | // engine.
41 | //
42 | function invalidate() {
43 |   data = {}
44 | }
45 | 
46 | export default {
47 |   get,
48 |   set,
49 |   invalidate
50 | }
51 | 


--------------------------------------------------------------------------------
/dist/style.css:
--------------------------------------------------------------------------------
 1 | body {
 2 |   font-family: Georgia, serif;
 3 |   margin: 1em auto 4em auto;
 4 |   width: 720px;
 5 |   color: #222;
 6 | }
 7 | 
 8 | h1, h2, h3, h4 {
 9 |   font-family: Helvetica, sans-serif;
10 | }
11 | 
12 | footer {
13 |   margin-top: 8em;
14 | }
15 | 
16 | p {
17 |   line-height: 1.5em;
18 | }
19 | 
20 | blockquote, footer {
21 |   color: #444;
22 | }
23 | 
24 | a {
25 |   color: #00ccff;
26 | }
27 | 
28 | a:not(:hover) {
29 |   text-decoration: none;
30 | }
31 | 
32 | pre, code {
33 |   font-family: monospace;
34 |   line-height: normal;
35 | }
36 | 
37 | pre {
38 |   border-left: solid 2px #ccc;
39 |   padding-left: 18px;
40 |   margin: 2em 0 2em -20px;
41 |   overflow-x: auto;
42 | }
43 | 
44 | @media screen and (max-width:825px) {
45 |   body {
46 |     margin: 1em 20px 4em 20px;
47 |     width: auto;
48 |   }
49 | 
50 |   pre {
51 |     margin-left: 0;
52 |   }
53 | 
54 |   img, video, canvas {
55 |     max-width: 100%;
56 |   }
57 | }
58 | 
59 | #loading,
60 | #error {
61 |   width: 100%;
62 |   height: 100%;
63 |   position: absolute;
64 |   top: 0;
65 |   left: 0;
66 |   text-align: center;
67 |   padding-top: 10em;
68 |   background-color: rgba(255, 255, 255, 0.8);
69 | }
70 | 
71 | #error {
72 |   display: none;
73 | }
74 | 


--------------------------------------------------------------------------------
/src/components.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | function requireElement(element: ?HTMLElement): HTMLElement {
 4 |   if (element == null) {
 5 |     throw new Error("Missing required element")
 6 |   }
 7 |   return element
 8 | }
 9 | 
10 | function requireAnchor(element: ?HTMLElement): HTMLAnchorElement {
11 |   if (element instanceof HTMLAnchorElement) {
12 |     return element
13 |   }
14 |   throw new Error("Element is not an anchor")
15 | }
16 | 
17 | function error(): HTMLElement {
18 |   return requireElement(document.getElementById("error"))
19 | }
20 | 
21 | function loading(): HTMLElement {
22 |   return requireElement(document.getElementById("loading"))
23 | }
24 | 
25 | function footer(): HTMLElement {
26 |   return requireElement(document.querySelector("footer"))
27 | }
28 | 
29 | function content(): HTMLElement {
30 |   return requireElement(document.getElementById("content"))
31 | }
32 | 
33 | function sourceLink(): HTMLAnchorElement {
34 |   return requireAnchor(document.querySelector("a#source"))
35 | }
36 | 
37 | function creditsLink(): HTMLAnchorElement {
38 |   return requireAnchor(document.querySelector("a[rel='author']"))
39 | }
40 | 
41 | export default {
42 |   error,
43 |   loading,
44 |   footer,
45 |   content,
46 |   sourceLink,
47 |   creditsLink
48 | }
49 | 


--------------------------------------------------------------------------------
/src/backend/index.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | //
 4 | // Backend
 5 | //
 6 | 
 7 | import type { Config as GistConfig } from "./gist"
 8 | import type { Config as LocalConfig } from "./local"
 9 | 
10 | type Client = {
11 |   fileURL: (string) => Promise<string>,
12 | }
13 | 
14 | type Config = GistConfig | LocalConfig
15 | 
16 | var client: Client
17 | 
18 | import gist from "./gist"
19 | import local from "./local"
20 | import httpGet from "./httpGet"
21 | 
22 | //
23 | // Initializes the backend using the input configuration.
24 | //
25 | // The backend client is selected depending on the storage type defined in the
26 | // `storage` configuration property.
27 | //
28 | function init(config: Config): Promise<void> {
29 |   switch (config.storage) {
30 |     case "local":
31 |       client = local
32 |       return local.init(config)
33 |     case "gist":
34 |       client = gist
35 |       return gist.init(config)
36 |   }
37 | }
38 | 
39 | //
40 | // Returns the URL of the file referenced by `filename`.
41 | //
42 | function fileURL(filename: string): Promise<string> {
43 |   return client.fileURL(filename)
44 | }
45 | 
46 | //
47 | // Sends a GET request to get the content of the file referenced by `filename`.
48 | //
49 | function fetchFileContent(filename: string): Promise<string> {
50 |   return client.fileURL(filename).then(url => httpGet(url))
51 | }
52 | 
53 | export default {
54 |   init,
55 |   fileURL,
56 |   fetchFileContent
57 | }
58 | 


--------------------------------------------------------------------------------
/src/backend/gist.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | //
 4 | // Gist backend
 5 | //
 6 | 
 7 | export type Config = { storage: "gist", gistId: string }
 8 | 
 9 | type File = { raw_url: string, ... }
10 | type Gist = { files: { [string]: File }, ... }
11 | 
12 | var files: { [string]: File }
13 | 
14 | import httpGet from "./httpGet"
15 | 
16 | //
17 | // Initializes the backend using the input configuration.
18 | //
19 | // For initializing the gist backend a request is made to the Gist API for
20 | // fetching the content of the gist referenced by the `gistId` configuration
21 | // property.
22 | //
23 | // The result is a list of files that are part of the gist, that is basically
24 | // a git repo. The list of file objects is stored in a dictionary indexed by
25 | // file name.
26 | //
27 | function init(config: Config): Promise<void> {
28 |   return httpGet(`https://api.github.com/gists/${config.gistId}`)
29 |     .then(JSON.parse)
30 |     .then((gist: Gist) => { files = gist.files })
31 | }
32 | 
33 | //
34 | // Returns the `raw_url` property of the file referenced by `filename`.
35 | //
36 | function fileURL(filename: string): Promise<string> {
37 |   return file(filename).then(file => file.raw_url)
38 | }
39 | 
40 | //
41 | // Returns true if a file exists in the selected gist.
42 | //
43 | function fileExists(filename: string): boolean {
44 |   return files[filename] !== undefined
45 | }
46 | 
47 | //
48 | // Returns a promise that resolves with a `file` object if the file exists or
49 | // rejects otherwise.
50 | //
51 | function file(filename: string): Promise<File> {
52 |   if (fileExists(filename)) {
53 |     return Promise.resolve(files[filename])
54 |   }
55 | 
56 |   return Promise.reject("File not found")
57 | }
58 | 
59 | export default {
60 |   init,
61 |   fileURL
62 | }
63 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "gist-txt",
 3 |   "version": "2.3.5",
 4 |   "description": "A minimal text adventure engine",
 5 |   "browser": "dist/main.js",
 6 |   "scripts": {
 7 |     "test": "jest",
 8 |     "doc": "docco src/index.js",
 9 |     "lint": "eslint 'src/**/*.js' 'test/**/*.js'",
10 |     "build": "webpack --mode production",
11 |     "watch": "webpack --mode development --watch",
12 |     "serve": "http-server dist -c-1",
13 |     "flow": "flow"
14 |   },
15 |   "repository": {
16 |     "type": "git",
17 |     "url": "git://github.com/potomak/gist-txt.git"
18 |   },
19 |   "keywords": [
20 |     "adventure",
21 |     "engine",
22 |     "game",
23 |     "gist",
24 |     "Git",
25 |     "github",
26 |     "text adventure",
27 |     "text",
28 |     "interactive",
29 |     "fiction",
30 |     "interactive fiction",
31 |     "tool",
32 |     "Twine"
33 |   ],
34 |   "author": "Giovanni Cappellotto",
35 |   "license": "MIT",
36 |   "bugs": {
37 |     "url": "https://github.com/potomak/gist-txt/issues"
38 |   },
39 |   "homepage": "https://github.com/potomak/gist-txt",
40 |   "devDependencies": {
41 |     "@babel/cli": "^7.13.16",
42 |     "@babel/core": "^7.13.16",
43 |     "@babel/preset-env": "^7.1.0",
44 |     "@babel/preset-flow": "^7.13.13",
45 |     "babel-eslint": "^10.1.0",
46 |     "babel-loader": "^8.0.4",
47 |     "docco": "^0.8.0",
48 |     "eslint": "^7.1.0",
49 |     "eslint-plugin-flowtype": "^5.7.2",
50 |     "eslint-plugin-jest": "^21.24.1",
51 |     "flow-bin": "^0.149.0",
52 |     "http-server": "^0.12.3",
53 |     "jest": "^26.6.3",
54 |     "webpack": "^5.35.1",
55 |     "webpack-cli": "^4.6.0"
56 |   },
57 |   "dependencies": {
58 |     "@babel/polyfill": "^7.0.0",
59 |     "buffer": "^6.0.3",
60 |     "gray-matter": "^4.0.1",
61 |     "js-yaml": "^3.14.1",
62 |     "marked": ">=0.7.0",
63 |     "mustache": "^3.0.0"
64 |   }
65 | }
66 | 


--------------------------------------------------------------------------------
/src/basic.js:
--------------------------------------------------------------------------------
 1 | // @flow strict
 2 | 
 3 | function show(element: HTMLElement) {
 4 |   element.style.display = "block"
 5 | }
 6 | 
 7 | function hide(element: HTMLElement) {
 8 |   element.style.display = "none"
 9 | }
10 | 
11 | function enable(element: HTMLStyleElement) {
12 |   element.disabled = false
13 | }
14 | 
15 | function disable(element: HTMLStyleElement) {
16 |   element.disabled = true
17 | }
18 | 
19 | function scrollTop() {
20 |   if (document.body == null) {
21 |     return
22 |   }
23 |   document.body.scrollTop = 0
24 |   if (document.documentElement == null) {
25 |     return
26 |   }
27 |   document.documentElement.scrollTop = 0
28 | }
29 | 
30 | //
31 | // Appends a `<style>` element with `content` to the DOM's `<head>`.
32 | //
33 | function appendStyle(content: string, attributes: { [string]: string }) {
34 |   const style = document.createElement("style")
35 |   for (const name in attributes) {
36 |     if (Object.prototype.hasOwnProperty.call(attributes, name)) {
37 |       style.setAttribute(name, attributes[name])
38 |     }
39 |   }
40 |   style.setAttribute("type", "text/css")
41 |   style.innerHTML = content
42 |   const head = document.querySelector("head")
43 |   if (head == null) {
44 |     return
45 |   }
46 |   head.append(style)
47 | }
48 | 
49 | //
50 | // Extends object a with properties from object b, recursively.
51 | //
52 | // $FlowFixMe - Unclear type
53 | function extend(a: { [string]: any }, b: { [string]: any }) {
54 |   for (const key in b) {
55 |     if (Object.prototype.hasOwnProperty.call(b, key)) {
56 |       if (typeof a[key] === "object" && typeof b[key] === "object") {
57 |         extend(a[key], b[key])
58 |       } else {
59 |         a[key] = b[key]
60 |       }
61 |     }
62 |   }
63 | }
64 | 
65 | export default {
66 |   show,
67 |   hide,
68 |   enable,
69 |   disable,
70 |   scrollTop,
71 |   appendStyle,
72 |   extend
73 | }
74 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # gist-txt
  2 | 
  3 | A minimal text adventure engine.
  4 | 
  5 | ![Build Status](https://github.com/potomak/gist-txt/actions/workflows/test.yml/badge.svg)
  6 | 
  7 | ## Usage
  8 | 
  9 | Create a new public gist at https://gist.github.com/.
 10 | 
 11 | The gist should contain at least an `index.markdown` file used as a starting
 12 | point for your text adventure, also called the *main scene*.
 13 | 
 14 | See more about markdown syntax at
 15 | http://daringfireball.net/projects/markdown/syntax.
 16 | 
 17 | ### Scenes
 18 | 
 19 | Every new `*.markdown` file is a *scene*.
 20 | 
 21 | Example: the file `city.markdown` is the *city* scene.
 22 | 
 23 | ### Links
 24 | 
 25 | Links between scenes are relative links to the scene name.
 26 | 
 27 | Example: to make the string "go to the city" a link to the *city* scene add the
 28 | markdown code:
 29 | 
 30 | ```markdown
 31 | [go to the city](city)
 32 | ```
 33 | 
 34 | You can make links to the *main scene* using the `index` name, example:
 35 | 
 36 | ```markdown
 37 | [Restart the game](index)
 38 | ```
 39 | 
 40 | ### Story state and Mustache tags
 41 | 
 42 | The story has a global state that could be set using YAML Front Matter blocks.
 43 | 
 44 | YAML Front Matter blocks are blocks of YAML at the top of each scene file. You
 45 | can alter story's state by adding an object associated to the `state` property.
 46 | 
 47 | Story's state can be used to change the behavior of the scene by adding Mustache
 48 | tags.
 49 | 
 50 | For example the scene:
 51 | 
 52 | ```markdown
 53 | ---
 54 | state:
 55 |   name: John
 56 | ---
 57 | 
 58 | Hi {{name}}!
 59 | ```
 60 | 
 61 | compiles to the following HTML:
 62 | 
 63 | ```html
 64 | <p>Hi John!</p>
 65 | ```
 66 | 
 67 | You can learn more about Mustache tags and syntax at
 68 | https://github.com/janl/mustache.js.
 69 | 
 70 | ### Custom styles
 71 | 
 72 | The global stylesheet is determined by the existence on the gist of a file
 73 | named `style.css`. Rules in this file get applied during the initialization of
 74 | the story before the first scene is rendered.
 75 | 
 76 | Scene's stylesheet are associated to the `style` property of the YAML Front
 77 | Matter of every scene. The stylesheet is enabled when the scene is active and
 78 | disabled when the scene is not active.
 79 | 
 80 | ### Scene initialization
 81 | 
 82 | You can run JavaScript code at every new visit of a scene by implementing a
 83 | function associated to YAML Front Matter's `init` property.
 84 | 
 85 | ## Hosting
 86 | 
 87 | Your text adventures are already hosted by default at GitHub Gist.
 88 | 
 89 | You can share your games by sharing a link with the format
 90 | `http://potomak.github.io/gist-txt/#<your-gist-id>`.
 91 | 
 92 | An example text adventure is stored in the gist `acebd8fe14942fab4e8e`
 93 | (https://gist.github.com/potomak/acebd8fe14942fab4e8e) and could be shared with
 94 | a link to http://potomak.github.io/gist-txt/#acebd8fe14942fab4e8e
 95 | 
 96 | ## Documentation
 97 | 
 98 | You can find the documentation at
 99 | http://potomak.github.io/gist-txt/docs/gist-txt.html.
100 | 
101 | Generate documentation for the project by running:
102 | 
103 | ```sh
104 | npm run doc
105 | ```
106 | 
107 | ## Testing
108 | 
109 | There is a suite of tests you can execute by running:
110 | 
111 | ```sh
112 | npm test
113 | ```
114 | 
115 | ## Type checker
116 | 
117 | This project uses Flow for type checking the JS source code.
118 | 
119 | You can run:
120 | 
121 | ```sh
122 | npm run flow
123 | ```
124 | 
125 | to verify that types check.
126 | 
127 | ## Linting
128 | 
129 | Run:
130 | 
131 | ```
132 | npm run lint
133 | ```
134 | 
135 | ## Building the bundle
136 | 
137 | Run:
138 | 
139 | ```sh
140 | npm run build
141 | ```
142 | 
143 | to build a minimized bundle that contains the game engine all its dependencies.
144 | 
145 | ### Development
146 | 
147 | During development you want to be able to debug your code and continuously
148 | rebuild the bundle after any change to your code.
149 | 
150 | Run:
151 | 
152 | ```sh
153 | npm run watch
154 | ```
155 | 
156 | to build a development version of the bundle that includes source maps and to
157 | automatically rebuild the bundle on code changes.
158 | 
159 | #### HTTP server
160 | 
161 | Run the HTTP server:
162 | 
163 | ```sh
164 | npm run serve
165 | ```
166 | 
167 | and open http://localhost:8080.
168 | 
169 | ## Story development environment
170 | 
171 | If you want to develop your text adventure locally, you can use the special
172 | `DEV` gist id to tell the tool to search for project files inside the
173 | `/dist/dev` directory instead of making external HTTP requests.
174 | 
175 | ## Acknowledgements
176 | 
177 | This project has been inspired by [Twine](http://twinery.org/) and
178 | [bl.ocks.org](http://bl.ocks.org/).
179 | 


--------------------------------------------------------------------------------
/jest.config.js:
--------------------------------------------------------------------------------
  1 | // For a detailed explanation regarding each configuration property, visit:
  2 | // https://jestjs.io/docs/en/configuration.html
  3 | 
  4 | module.exports = {
  5 |   // All imported modules in your tests should be mocked automatically
  6 |   // automock: false,
  7 | 
  8 |   // Stop running tests after the first failure
  9 |   // bail: false,
 10 | 
 11 |   // Respect "browser" field in package.json when resolving modules
 12 |   // browser: false,
 13 | 
 14 |   // The directory where Jest should store its cached dependency information
 15 |   // cacheDirectory: "/run/user/1001/jest_rt",
 16 | 
 17 |   // Automatically clear mock calls and instances between every test
 18 |   clearMocks: true,
 19 | 
 20 |   // Indicates whether the coverage information should be collected while executing the test
 21 |   // collectCoverage: false,
 22 | 
 23 |   // An array of glob patterns indicating a set of files for which coverage information should be collected
 24 |   // collectCoverageFrom: null,
 25 | 
 26 |   // The directory where Jest should output its coverage files
 27 |   coverageDirectory: "coverage",
 28 | 
 29 |   // An array of regexp pattern strings used to skip coverage collection
 30 |   // coveragePathIgnorePatterns: [
 31 |   //   "/node_modules/"
 32 |   // ],
 33 | 
 34 |   // A list of reporter names that Jest uses when writing coverage reports
 35 |   // coverageReporters: [
 36 |   //   "json",
 37 |   //   "text",
 38 |   //   "lcov",
 39 |   //   "clover"
 40 |   // ],
 41 | 
 42 |   // An object that configures minimum threshold enforcement for coverage results
 43 |   // coverageThreshold: null,
 44 | 
 45 |   // Make calling deprecated APIs throw helpful error messages
 46 |   // errorOnDeprecated: false,
 47 | 
 48 |   // Force coverage collection from ignored files usin a array of glob patterns
 49 |   // forceCoverageMatch: [],
 50 | 
 51 |   // A path to a module which exports an async function that is triggered once before all test suites
 52 |   // globalSetup: null,
 53 | 
 54 |   // A path to a module which exports an async function that is triggered once after all test suites
 55 |   // globalTeardown: null,
 56 | 
 57 |   // A set of global variables that need to be available in all test environments
 58 |   // globals: {},
 59 | 
 60 |   // An array of directory names to be searched recursively up from the requiring module's location
 61 |   // moduleDirectories: [
 62 |   //   "node_modules"
 63 |   // ],
 64 | 
 65 |   // An array of file extensions your modules use
 66 |   // moduleFileExtensions: [
 67 |   //   "js",
 68 |   //   "json",
 69 |   //   "jsx",
 70 |   //   "node"
 71 |   // ],
 72 | 
 73 |   // A map from regular expressions to module names that allow to stub out resources with a single module
 74 |   // moduleNameMapper: {},
 75 | 
 76 |   // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
 77 |   // modulePathIgnorePatterns: [],
 78 | 
 79 |   // Activates notifications for test results
 80 |   // notify: false,
 81 | 
 82 |   // An enum that specifies notification mode. Requires { notify: true }
 83 |   // notifyMode: "always",
 84 | 
 85 |   // A preset that is used as a base for Jest's configuration
 86 |   // preset: null,
 87 | 
 88 |   // Run tests from one or more projects
 89 |   // projects: null,
 90 | 
 91 |   // Use this configuration option to add custom reporters to Jest
 92 |   // reporters: undefined,
 93 | 
 94 |   // Automatically reset mock state between every test
 95 |   // resetMocks: false,
 96 | 
 97 |   // Reset the module registry before running each individual test
 98 |   // resetModules: false,
 99 | 
100 |   // A path to a custom resolver
101 |   // resolver: null,
102 | 
103 |   // Automatically restore mock state between every test
104 |   // restoreMocks: false,
105 | 
106 |   // The root directory that Jest should scan for tests and modules within
107 |   // rootDir: null,
108 | 
109 |   // A list of paths to directories that Jest should use to search for files in
110 |   // roots: [
111 |   //   "<rootDir>"
112 |   // ],
113 | 
114 |   // Allows you to use a custom runner instead of Jest's default test runner
115 |   // runner: "jest-runner",
116 | 
117 |   // The paths to modules that run some code to configure or set up the testing environment before each test
118 |   // setupFiles: [],
119 | 
120 |   // The path to a module that runs some code to configure or set up the testing framework before each test
121 |   // setupTestFrameworkScriptFile: null,
122 | 
123 |   // A list of paths to snapshot serializer modules Jest should use for snapshot testing
124 |   // snapshotSerializers: [],
125 | 
126 |   // The test environment that will be used for testing
127 |   // testEnvironment: "jest-environment-jsdom",
128 | 
129 |   // Options that will be passed to the testEnvironment
130 |   // testEnvironmentOptions: {},
131 | 
132 |   // Adds a location field to test results
133 |   // testLocationInResults: false,
134 | 
135 |   // The glob patterns Jest uses to detect test files
136 |   // testMatch: [
137 |   //   "**/__tests__/**/*.js?(x)",
138 |   //   "**/?(*.)+(spec|test).js?(x)"
139 |   // ],
140 | 
141 |   // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
142 |   // testPathIgnorePatterns: [
143 |   //   "/node_modules/"
144 |   // ],
145 | 
146 |   // The regexp pattern Jest uses to detect test files
147 |   // testRegex: "",
148 | 
149 |   // This option allows the use of a custom results processor
150 |   // testResultsProcessor: null,
151 | 
152 |   // This option allows use of a custom test runner
153 |   // testRunner: "jasmine2",
154 | 
155 |   // This option sets the URL for the jsdom environment. It is reflected in properties such as location.href
156 |   // testURL: "http://localhost",
157 | 
158 |   // Setting this value to "fake" allows the use of fake timers for functions such as "setTimeout"
159 |   // timers: "real",
160 | 
161 |   // A map from regular expressions to paths to transformers
162 |   // transform: null,
163 | 
164 |   // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
165 |   // transformIgnorePatterns: [
166 |   //   "/node_modules/"
167 |   // ],
168 | 
169 |   // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
170 |   // unmockedModulePathPatterns: undefined,
171 | 
172 |   // Indicates whether each individual test should be reported during the run
173 |   // verbose: null,
174 | 
175 |   // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
176 |   // watchPathIgnorePatterns: [],
177 | 
178 |   // Whether to use watchman for file crawling
179 |   // watchman: true,
180 | };
181 | 


--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
  1 | // @flow strict
  2 | 
  3 | type SceneMetadata = {
  4 |   init: ?() => void,
  5 |   track: ?string,
  6 |   author: ?string,
  7 |   // $FlowFixMe - Unclear type
  8 |   state: ?{ [string]: any },
  9 |   style: ?string
 10 | }
 11 | 
 12 | type SceneData = {
 13 |   content: string,
 14 |   data: SceneMetadata
 15 | }
 16 | 
 17 | //
 18 | // Gist-txt is a minimal game engine for creating text adventures and
 19 | // interactive fiction. Games created with gist-txt are stored as GitHub gists
 20 | // and hosted as HTML pages.
 21 | //
 22 | // To create a new text adventure create a new public gist at
 23 | // https://gist.github.com/ with at least one markdown file named
 24 | // `index.markdown`. This will be the game *main scene*: the starting point of
 25 | // your adventure.
 26 | //
 27 | // More info at https://github.com/potomak/gist-txt.
 28 | //
 29 | var gistId: string
 30 | var currentScene: string
 31 | var currentTrack: ?Audio
 32 | var initialized: boolean = false
 33 | window.state = {}
 34 | 
 35 | // $FlowFixMe - Untyped module
 36 | import mustache from "mustache"
 37 | // $FlowFixMe - Untyped module
 38 | import marked from "marked"
 39 | // $FlowFixMe - Untyped module
 40 | import yaml from "js-yaml"
 41 | // $FlowFixMe - Untyped module
 42 | import matter from "gray-matter"
 43 | 
 44 | import cache from "./cache"
 45 | import backend from "./backend/index"
 46 | import basic from "./basic"
 47 | import components from "./components"
 48 | import parse from "./parse"
 49 | 
 50 | //
 51 | // ## Initialization
 52 | //
 53 | // During the initialization stage the fragment identifier, also called *hash*
 54 | // in the source code, in the URL is parsed to extract two pieces of
 55 | // information:
 56 | //
 57 | // 1. gist id
 58 | // 2. scene name
 59 | //
 60 | // The gist id is used to make a GET request to
 61 | // https://developer.github.com/v3/gists/#get-a-single-gist to get gist's data.
 62 | //
 63 | // When gist id is set to `DEV`, that is a conventional gist id used while
 64 | // developing adventure games, requests are sent to `/dev`, that is a path in
 65 | // the local development server that maps to the the `./dev` directory in the
 66 | // local file system.
 67 | //
 68 | // A successful response triggers the loading and rendering of the selected
 69 | // scene.
 70 | //
 71 | function init(): Promise<void> {
 72 |   initialized = true
 73 |   const [gId, scene] = parse(document.location.hash)
 74 |   gistId = gId
 75 | 
 76 |   cache.invalidate()
 77 | 
 78 |   const config = isDev()
 79 |     ? { storage: "local", path: "/dev" }
 80 |     : { storage: "gist", gistId }
 81 | 
 82 |   return backend.init(config)
 83 |     .then(() => {
 84 |       return initUI(scene)
 85 |     })
 86 |     .catch((error: Error) => {
 87 |       components.error().innerHTML = `Error: ${error.toString()}`
 88 |       basic.show(components.error())
 89 |     })
 90 |     .finally(() => basic.hide(components.loading()))
 91 | }
 92 | 
 93 | //
 94 | // UI initialization consists of three steps:
 95 | //
 96 | // 1. global stylesheet application
 97 | // 2. loading and rendering of the selected scene
 98 | // 3. compilation and display of site footer
 99 | //
100 | function initUI(scene: string): Promise<void> {
101 |   return applyStylesheet()
102 |     .then(loadAndRender.bind(this, scene))
103 |     .then(compileAndDisplayFooter)
104 | }
105 | 
106 | //
107 | // If gist's files include `style.css` its content is applied as the global CSS
108 | // for the story.
109 | //
110 | // The method returns a promise that is always resolved (the stylesheet is
111 | // optional).
112 | //
113 | function applyStylesheet() {
114 |   return backend.fetchFileContent("style.css")
115 |     .then(content => basic.appendStyle(content, {}))
116 |     .catch(() => true)
117 | }
118 | 
119 | //
120 | // ## Loading and rendering scenes
121 | //
122 | // Every scene is associated with a Markdown file called:
123 | //
124 | //     `${scene}.markdown`
125 | //
126 | // where `scene` is the name of the scene.
127 | //
128 | // A `cache` stores scene files that have been already fetched and compiled. If
129 | // the cache doesn't contain the requested scene the *load and render* process
130 | // includes:
131 | //
132 | // 1. getting the raw content of the file by sending a GET request to file's
133 | //   `raw_url`
134 | // 2. extracting YAML Front Matter and storing scene state in the `state` object
135 | // 3. storing a copy of the Markdown content in `cache`
136 | // 4. running a custom `init` function to initialize scene if present
137 | // 5. rendering the Mustache content
138 | // 6. rendering the Markdown content
139 | // 7. writing the rendered content as the `div#content` element's inner HTML
140 | //
141 | // Click event listeners are added to anchors elements in the content that link
142 | // to local resources. These custom listeners handle navigation between scenes.
143 | //
144 | // If everything goes well the current scene name is stored in the global
145 | // variable `currentScene`, the previous scene's stylesheet is disabled, and the
146 | // current scene's stylesheet is enabled.
147 | //
148 | function loadAndRender(scene: string) {
149 |   basic.hide(components.error())
150 |   basic.show(components.loading())
151 | 
152 |   return getScene(scene)
153 |     .then(parsed => {
154 |       runSceneInit(parsed)
155 |       playTrack(parsed)
156 |       updateGameState(parsed)
157 |       return parsed.content
158 |     })
159 |     .then(renderMustache)
160 |     .then(renderMarkdown)
161 |     .then(outputContent)
162 |     .then(handleInternalLinks)
163 |     .then(basic.scrollTop)
164 |     .then(() => {
165 |       const currentSceneStyle = document.getElementById(sceneStyleId(currentScene))
166 |       if (currentSceneStyle instanceof HTMLStyleElement) {
167 |         basic.disable(currentSceneStyle)
168 |       }
169 | 
170 |       const sceneStyle = document.getElementById(sceneStyleId(scene))
171 |       if (sceneStyle instanceof HTMLStyleElement) {
172 |         basic.enable(sceneStyle)
173 |       }
174 | 
175 |       currentScene = scene
176 |     })
177 |     .catch((error: Error) => {
178 |       components.error().innerHTML = `Error: ${error.toString()}`
179 |       basic.show(components.error())
180 |     })
181 |     .finally(() => basic.hide(components.loading()))
182 | }
183 | 
184 | //
185 | // If the gist response is successful the footer will be displayed.
186 | //
187 | // The footer includes these information:
188 | //
189 | // * a link to the original gist
190 | // * a link to the credits page
191 | //
192 | function compileAndDisplayFooter(): void {
193 |   const source = components.sourceLink()
194 |   source.setAttribute("href", `https://gist.github.com/${gistId}`)
195 |   source.innerHTML = gistId
196 | 
197 |   creditsLink()
198 | 
199 |   basic.show(components.footer())
200 | }
201 | 
202 | //
203 | // The credits page contains information about the authors of the text
204 | // adventure.
205 | //
206 | // Data for the credits page is stored in a the conventional `credits.markdown`
207 | // file. If the `author` property is present in the file's data header it will
208 | // be used as the content of the link in the footer.
209 | //
210 | function creditsLink() {
211 |   getScene("credits")
212 |     .then(({ data: { author } }) => {
213 |       const credits = components.creditsLink()
214 |       credits.setAttribute("href", "credits")
215 |       credits.addEventListener("click", sceneLinkClickListener.bind(this, "credits"))
216 |       if (author != null) {
217 |         credits.innerHTML = author
218 |       }
219 |     })
220 |     .catch(() => true)
221 | }
222 | 
223 | //
224 | // The YAML Front Matter is extracted from the original content. The resulting
225 | // data is used to extend the global `state`.
226 | //
227 | // If data's `style` property is defined, a `<style>` tag with the content of
228 | // the property is injected in the page HTML. A scene's `style` can be used to
229 | // override global stylesheet rules.
230 | //
231 | function extractYFM(scene, content) {
232 |   const parsed: SceneData = matter(content, {
233 |     engines: { yaml: yaml.load.bind(yaml) }
234 |   })
235 |   if (parsed.data.style != null) {
236 |     basic.appendStyle(parsed.data.style, { id: sceneStyleId(scene) })
237 |   }
238 |   return parsed
239 | }
240 | 
241 | //
242 | // A scene's stylesheet `<style>` element has an `id` with the form:
243 | //
244 | //     `${scene}-style`
245 | //
246 | function sceneStyleId(scene) {
247 |   return `${scene}-style`
248 | }
249 | 
250 | //
251 | // Play an audio track associated to the current scene.
252 | //
253 | // If an audio track is already playing it fades its volume out and starts
254 | // playing the current one's.
255 | //
256 | // TODO: https://github.com/potomak/gist-txt/issues/33
257 | // Fade between tracks without jQuery (previously done using $.animate)
258 | //
259 | // Audio files should be included in two formats: ogg and mp3.
260 | //
261 | // To play a track in a scene add the `track` property to the scene's YAML Front
262 | // Matter data and set its value to the name of the audio file without the
263 | // extension.
264 | //
265 | function playTrack({ data: { track } }): void {
266 |   if (track == null) {
267 |     return
268 |   }
269 | 
270 |   if (currentTrack != null && !currentTrack.paused) {
271 |     currentTrack.pause()
272 |   } else {
273 |     playSceneTrack(track)
274 |   }
275 | }
276 | 
277 | //
278 | // A helper function that creates a new `Audio` element with the `autoplay`
279 | // and `loop` attributes set to `true` and loads an audio file based on the
280 | // browser's audio capabilities.
281 | //
282 | function playSceneTrack(track: string): void {
283 |   // TODO: https://github.com/potomak/gist-txt/issues/34
284 |   // Check audio support during initialization
285 |   const ext = (new Audio().canPlayType("audio/ogg; codecs=vorbis")) ? "ogg" : "mp3"
286 |   const filename = `${track}.${ext}`
287 | 
288 |   // TODO: https://github.com/potomak/gist-txt/issues/35
289 |   // Fix autoplay. It doesn't work without user interaction.
290 |   backend.fileURL(filename).then(url => {
291 |     const audio = new Audio()
292 |     audio.autoplay = true
293 |     audio.loop = true
294 |     audio.src = url
295 |     currentTrack = audio
296 |   })
297 | }
298 | 
299 | //
300 | // Mustache content is rendered using game's global state (`window.state`) as
301 | // its view object.
302 | //
303 | function renderMustache(content: string): string {
304 |   return mustache.render(content, window.state)
305 | }
306 | 
307 | //
308 | // Markdown content is rendered.
309 | //
310 | function renderMarkdown(content: string): string {
311 |   return marked(content)
312 | }
313 | 
314 | //
315 | // The HTML rendered content is the main content of the scene. It replaces the
316 | // content of the `#content` element in the DOM.
317 | //
318 | function outputContent(content) {
319 |   components.content().innerHTML = content
320 | }
321 | 
322 | //
323 | // A cache layer that stores scene content optimizes network traffic usage.
324 | //
325 | // The cache contains gist's files parsed content indexed by scene name.
326 | //
327 | function getScene(scene): Promise<SceneData> {
328 |   return cache.get(scene)
329 |     .catch(() =>
330 |       backend.fetchFileContent(`${scene}.markdown`)
331 |         .then(extractYFM.bind(this, scene))
332 |         .then(parsed => cache.set(scene, parsed))
333 |     )
334 | }
335 | 
336 | //
337 | // ## Scene navigation
338 | //
339 | // Internal links click events are overridden to handle navigation between
340 | // scenes in the text adventure.
341 | //
342 | // `<a>` elements' `href` attribute is used to rewrite location's hash in the
343 | // form:
344 | //
345 | //     `#${gistId}/${href}`
346 | //
347 | // At every internal link click event a new state is pushed in the
348 | // `window.history` object to allow navigation using back and forward buttons.
349 | //
350 | function handleInternalLinks() {
351 |   components.content().querySelectorAll("a").forEach(anchor => {
352 |     const href = anchor.getAttribute("href")
353 |     if (href == null || isExternal(href) || isAbsolute(href)) {
354 |       return
355 |     }
356 | 
357 |     anchor.addEventListener("click", (event: MouseEvent) =>
358 |       sceneLinkClickListener(href, event)
359 |     )
360 |   })
361 | }
362 | 
363 | function sceneLinkClickListener(scene: string, event: MouseEvent) {
364 |   event.preventDefault()
365 |   const hash = `#${gistId}/${scene}`
366 |   runScene(hash)
367 |   window.history.pushState(null, null, document.location.pathname + hash)
368 | }
369 | 
370 | function isExternal(href: string): boolean {
371 |   return href.indexOf("://") > -1
372 | }
373 | 
374 | function isAbsolute(href: string): boolean {
375 |   return href.startsWith("/")
376 | }
377 | 
378 | //
379 | // Extends game state with current scene's state.
380 | //
381 | function updateGameState({ data: { state } }) {
382 |   if (state == null) {
383 |     return
384 |   }
385 |   basic.extend(window.state, state)
386 | }
387 | 
388 | //
389 | // Runs a scene initialization function.
390 | //
391 | function runSceneInit({ data: { init } }) {
392 |   if (init == null) {
393 |     return
394 |   }
395 |   init()
396 | }
397 | 
398 | //
399 | // A `popstate` event is dispatched to the window every time the active history
400 | // entry changes between two history entries for the same document.
401 | //
402 | // If the `files` array is undefined we need to initialize the text adventure,
403 | // otherwise we can just render the current scene.
404 | //
405 | window.onpopstate = () => {
406 |   if (!initialized) {
407 |     return init()
408 |   }
409 | 
410 |   runScene(document.location.hash)
411 | }
412 | 
413 | //
414 | // ## Parsing location hash and running a scene
415 | //
416 | // Running a scene includes:
417 | //
418 | // 1. parsing location's hash to get the scene name
419 | // 2. loading and rendering the selected scene
420 | //
421 | function runScene(hash) {
422 |   const [gId, scene] = parse(hash)
423 |   gistId = gId
424 |   loadAndRender(scene)
425 | }
426 | 
427 | //
428 | // During development you can use `DEV` as special gist id.
429 | //
430 | // When the development environment is used, requests will be sent to the `/dev`
431 | // path that is served by the local development server, instead of the public
432 | // Gist API.
433 | //
434 | function isDev() {
435 |   return gistId === "DEV"
436 | }
437 | 
438 | //
439 | // ## It's time to play
440 | //
441 | // Let's play by starting the engine as soon as the document content has been
442 | // loaded.
443 | //
444 | document.addEventListener("DOMContentLoaded", init)
445 | 


--------------------------------------------------------------------------------
/test/index.test.js:
--------------------------------------------------------------------------------
  1 | jest.mock("../src/backend/httpGet")
  2 | 
  3 | // Register init to DOMContentLoaded event
  4 | require("../src/index")
  5 | 
  6 | const resetEnv = () => {
  7 |   // Set up our document head
  8 |   document.head.innerHTML = ""
  9 |   // Set up our document body
 10 |   document.body.innerHTML =
 11 |     "<div id=\"error\"></div>\n" +
 12 |     "<div id=\"loading\">Loading...</div>\n" +
 13 |     "<div id=\"content\"></div>\n" +
 14 |     "<footer style=\"display: none\">\n" +
 15 |     "  Source: <a id=\"source\"></a>\n" +
 16 |     "  by <a rel=\"author\"></a>\n" +
 17 |     "</footer>"
 18 | 
 19 |   // Reset document.location.hash
 20 |   document.location.hash = ""
 21 | 
 22 |   // Reset game state
 23 |   window.state = {}
 24 | }
 25 | 
 26 | describe("init", () => {
 27 |   beforeEach(resetEnv)
 28 | 
 29 |   test("displays an error if the gist request fails", () => {
 30 |     const httpGet = require("../src/backend/httpGet")
 31 |     httpGet.default.mockImplementation(() => Promise.reject("Test error"))
 32 | 
 33 |     // Dispatch the DOMContentLoaded event
 34 |     document.dispatchEvent(new Event("DOMContentLoaded"))
 35 | 
 36 |     return new Promise(process.nextTick).then(() => {
 37 |       expect(document.getElementById("error").innerHTML).toEqual("Error: Test error")
 38 |       expect(document.getElementById("error").style.display).toEqual("block")
 39 |       expect(document.getElementById("loading").style.display).toEqual("none")
 40 |     })
 41 |   })
 42 | 
 43 |   test("displays the index scene content", () => {
 44 |     const gistContent = JSON.stringify({
 45 |       files: {
 46 |         "index.markdown": { raw_url: "http://gists/index.markdown" }
 47 |       }
 48 |     })
 49 |     const indexContent = "Once upon a time..."
 50 |     const httpGet = require("../src/backend/httpGet")
 51 |     httpGet.default.mockImplementation((url) => {
 52 |       switch (url) {
 53 |         case "http://gists/index.markdown":
 54 |           return Promise.resolve(indexContent)
 55 |       }
 56 |       return Promise.resolve(gistContent)
 57 |     })
 58 | 
 59 |     // Dispatch the DOMContentLoaded event
 60 |     document.dispatchEvent(new Event("DOMContentLoaded"))
 61 | 
 62 |     return new Promise(process.nextTick).then(() => {
 63 |       expect(document.getElementById("error").style.display).toEqual("none")
 64 |       expect(document.getElementById("loading").style.display).toEqual("none")
 65 |       expect(document.getElementById("content").innerHTML).toContain("<p>Once upon a time...</p>")
 66 |     })
 67 |   })
 68 | 
 69 |   test("applies the default stylesheet when style.css is present", () => {
 70 |     const gistContent = JSON.stringify({
 71 |       files: {
 72 |         "index.markdown": { raw_url: "http://gists/index.markdown" },
 73 |         "style.css": { raw_url: "http://gists/style.css" }
 74 |       }
 75 |     })
 76 |     const indexContent = "Once upon a time..."
 77 |     const styleContent = "body { background-color: black; }"
 78 |     const httpGet = require("../src/backend/httpGet")
 79 |     httpGet.default.mockImplementation((url) => {
 80 |       switch (url) {
 81 |         case "http://gists/index.markdown":
 82 |           return Promise.resolve(indexContent)
 83 |         case "http://gists/style.css":
 84 |           return Promise.resolve(styleContent)
 85 |       }
 86 |       return Promise.resolve(gistContent)
 87 |     })
 88 | 
 89 |     // Dispatch the DOMContentLoaded event
 90 |     document.dispatchEvent(new Event("DOMContentLoaded"))
 91 | 
 92 |     return new Promise(process.nextTick).then(() => {
 93 |       expect(document.getElementsByTagName("style")[0].innerHTML).toContain(styleContent)
 94 |     })
 95 |   })
 96 | 
 97 |   test("applies the scene stylesheet when the 'style' attribute is present", () => {
 98 |     const gistContent = JSON.stringify({
 99 |       files: {
100 |         "index.markdown": { raw_url: "http://gists/index.markdown" }
101 |       }
102 |     })
103 |     const styleContent = "body { background-color: black; }"
104 |     const indexContent =
105 |       "---\n" +
106 |       "style: '" + styleContent + "'\n" +
107 |       "---\n\n" +
108 |       "Once upon a time..."
109 |     const httpGet = require("../src/backend/httpGet")
110 |     httpGet.default.mockImplementation((url) => {
111 |       switch (url) {
112 |         case "http://gists/index.markdown":
113 |           return Promise.resolve(indexContent)
114 |       }
115 |       return Promise.resolve(gistContent)
116 |     })
117 | 
118 |     // Dispatch the DOMContentLoaded event
119 |     document.dispatchEvent(new Event("DOMContentLoaded"))
120 | 
121 |     return new Promise(process.nextTick).then(() => {
122 |       expect(document.querySelector("style").innerHTML).toContain(styleContent)
123 |       expect(document.querySelector("style").id).toEqual("index-style")
124 |     })
125 |   })
126 | 
127 |   test("renders mustache tags", () => {
128 |     const gistContent = JSON.stringify({
129 |       files: {
130 |         "index.markdown": { raw_url: "http://gists/index.markdown" }
131 |       }
132 |     })
133 |     const indexContent =
134 |       "---\n" +
135 |       "state:\n" +
136 |       "  hero: Bob\n" +
137 |       "---\n\n" +
138 |       "Once upon a time {{hero}}..."
139 |     const httpGet = require("../src/backend/httpGet")
140 |     httpGet.default.mockImplementation((url) => {
141 |       switch (url) {
142 |         case "http://gists/index.markdown":
143 |           return Promise.resolve(indexContent)
144 |       }
145 |       return Promise.resolve(gistContent)
146 |     })
147 | 
148 |     // Dispatch the DOMContentLoaded event
149 |     document.dispatchEvent(new Event("DOMContentLoaded"))
150 | 
151 |     return new Promise(process.nextTick).then(() => {
152 |       expect(document.getElementById("content").innerHTML).toContain("<p>Once upon a time Bob...</p>")
153 |     })
154 |   })
155 | 
156 |   test("doesn't prevent default behavior of external and absolute links", () => {
157 |     const gistContent = JSON.stringify({
158 |       files: {
159 |         "index.markdown": { raw_url: "http://gists/index.markdown" }
160 |       }
161 |     })
162 |     const indexContent =
163 |       "Once upon a time... " +
164 |       "[external link](http://example.com) " +
165 |       "[absolute link](/path)"
166 |     const httpGet = require("../src/backend/httpGet")
167 |     httpGet.default.mockImplementation((url) => {
168 |       switch (url) {
169 |         case "http://gists/index.markdown":
170 |           return Promise.resolve(indexContent)
171 |       }
172 |       return Promise.resolve(gistContent)
173 |     })
174 | 
175 |     // Dispatch the DOMContentLoaded event
176 |     document.dispatchEvent(new Event("DOMContentLoaded"))
177 | 
178 |     return new Promise(process.nextTick).then(() => {
179 |       expect(document.getElementById("content").innerHTML).toContain("Once upon a time...")
180 | 
181 |       const originalHref = document.location.href
182 |       // Browse to an external page
183 |       document.querySelector("a[href='http://example.com']").click()
184 |       // Note: document.location.href doesn't change when a link is clicked, but
185 |       // it changes when a click listener has been added to the anchor
186 |       expect(document.location.href).toEqual(originalHref)
187 | 
188 |       // Follow absolute link
189 |       document.querySelector("a[href='/path']").click()
190 |       expect(document.location.href).toEqual(originalHref)
191 |     })
192 |   })
193 | 
194 |   test("displays a link to the credits page if credits.markdown is present", () => {
195 |     const gistContent = JSON.stringify({
196 |       files: {
197 |         "index.markdown": { raw_url: "http://gists/index.markdown" },
198 |         "credits.markdown": { raw_url: "http://gists/credits.markdown" }
199 |       }
200 |     })
201 |     const indexContent = "Once upon a time..."
202 |     const creditsContent =
203 |       "---\n" +
204 |       "author: John Doe\n" +
205 |       "---\n\n" +
206 |       "Created by John Doe"
207 |     const httpGet = require("../src/backend/httpGet")
208 |     httpGet.default.mockImplementation((url) => {
209 |       switch (url) {
210 |         case "http://gists/index.markdown":
211 |           return Promise.resolve(indexContent)
212 |         case "http://gists/credits.markdown":
213 |           return Promise.resolve(creditsContent)
214 |       }
215 |       return Promise.resolve(gistContent)
216 |     })
217 | 
218 |     // Dispatch the DOMContentLoaded event
219 |     document.dispatchEvent(new Event("DOMContentLoaded"))
220 | 
221 |     return new Promise(process.nextTick).then(() => {
222 |       expect(document.getElementsByTagName("footer")[0].innerHTML)
223 |         .toContain("<a rel=\"author\" href=\"credits\">John Doe</a>")
224 | 
225 |       // Open credits page
226 |       document.querySelector("a[rel=author]").click()
227 |     }).then(() => new Promise(process.nextTick)).then(() => {
228 |       expect(document.getElementById("content").innerHTML)
229 |         .toContain("Created by John Doe")
230 |     })
231 |   })
232 | })
233 | 
234 | describe("scene transition", () => {
235 |   beforeEach(resetEnv)
236 | 
237 |   test("displays the scene content", () => {
238 |     const gistContent = JSON.stringify({
239 |       files: {
240 |         "index.markdown": { raw_url: "http://gists/index.markdown" },
241 |         "end.markdown": { raw_url: "http://gists/end.markdown" }
242 |       }
243 |     })
244 |     const indexContent = "Once upon a time... [continue...](end)"
245 |     const endContent = "The end"
246 |     const httpGet = require("../src/backend/httpGet")
247 |     httpGet.default.mockImplementation((url) => {
248 |       switch (url) {
249 |         case "http://gists/index.markdown":
250 |           return Promise.resolve(indexContent)
251 |         case "http://gists/end.markdown":
252 |           return Promise.resolve(endContent)
253 |       }
254 |       return Promise.resolve(gistContent)
255 |     })
256 | 
257 |     // Dispatch the DOMContentLoaded event
258 |     document.dispatchEvent(new Event("DOMContentLoaded"))
259 | 
260 |     return new Promise(process.nextTick).then(() => {
261 |       expect(document.getElementById("content").innerHTML).toContain("Once upon a time...")
262 | 
263 |       // Dispatch scene transition
264 |       document.querySelector("a[href=end]").click()
265 |     }).then(() => new Promise(process.nextTick)).then(() => {
266 |       expect(document.getElementById("content").innerHTML).toContain("The end")
267 |     })
268 |   })
269 | 
270 |   test("doesn't load the same scene twice (cached content)", () => {
271 |     const gistContent = JSON.stringify({
272 |       files: {
273 |         "index.markdown": { raw_url: "http://gists/index.markdown" },
274 |         "end.markdown": { raw_url: "http://gists/end.markdown" }
275 |       }
276 |     })
277 |     const indexContent = "Once upon a time... [continue...](end)"
278 |     const endContent = "The end... [or not?](index)"
279 |     const httpGet = require("../src/backend/httpGet")
280 |     httpGet.default.mockImplementation((url) => {
281 |       switch (url) {
282 |         case "http://gists/index.markdown":
283 |           return Promise.resolve(indexContent)
284 |         case "http://gists/end.markdown":
285 |           return Promise.resolve(endContent)
286 |       }
287 |       return Promise.resolve(gistContent)
288 |     })
289 | 
290 |     // Dispatch the DOMContentLoaded event
291 |     document.dispatchEvent(new Event("DOMContentLoaded"))
292 | 
293 |     return new Promise(process.nextTick).then(() => {
294 |       expect(document.getElementById("content").innerHTML).toContain("Once upon a time...")
295 |       expect(httpGet.default.mock.calls[httpGet.default.mock.calls.length - 1]).toEqual(["http://gists/index.markdown"])
296 | 
297 |       // Dispatch scene transition
298 |       document.querySelector("a[href=end]").click()
299 |     }).then(() => new Promise(process.nextTick)).then(() => {
300 |       expect(document.getElementById("content").innerHTML).toContain("The end")
301 |       expect(httpGet.default.mock.calls[httpGet.default.mock.calls.length - 1]).toEqual(["http://gists/end.markdown"])
302 | 
303 |       // Dispatch scene transition
304 |       document.querySelector("a[href=index]").click()
305 |     }).then(() => new Promise(process.nextTick)).then(() => {
306 |       expect(document.getElementById("content").innerHTML).toContain("Once upon a time...")
307 |       expect(httpGet.default.mock.calls[httpGet.default.mock.calls.length - 1]).toEqual(["http://gists/end.markdown"])
308 |     })
309 |   })
310 | 
311 |   test("enables and disables the correct scene styles", () => {
312 |     const gistContent = JSON.stringify({
313 |       files: {
314 |         "index.markdown": { raw_url: "http://gists/index.markdown" },
315 |         "end.markdown": { raw_url: "http://gists/end.markdown" }
316 |       }
317 |     })
318 |     const indexContent =
319 |       "---\n" +
320 |       "style: 'body { background-color: black; }'\n" +
321 |       "---\n\n" +
322 |       "Once upon a time... [continue...](end)"
323 |     const endContent =
324 |       "---\n" +
325 |       "style: 'body { background-color: green; }'\n" +
326 |       "---\n\n" +
327 |       "The end... [or not?](index)"
328 |     const httpGet = require("../src/backend/httpGet")
329 |     httpGet.default.mockImplementation((url) => {
330 |       switch (url) {
331 |         case "http://gists/index.markdown":
332 |           return Promise.resolve(indexContent)
333 |         case "http://gists/end.markdown":
334 |           return Promise.resolve(endContent)
335 |       }
336 |       return Promise.resolve(gistContent)
337 |     })
338 | 
339 |     // Dispatch the DOMContentLoaded event
340 |     document.dispatchEvent(new Event("DOMContentLoaded"))
341 | 
342 |     return new Promise(process.nextTick).then(() => {
343 |       expect(document.getElementById("content").innerHTML).toContain("Once upon a time...")
344 |       expect(document.getElementById("end-style")).toBeNull()
345 |       expect(document.getElementById("index-style").innerHTML).toContain("background-color: black")
346 |       expect(document.getElementById("index-style").disabled).toEqual(false)
347 | 
348 |       // Dispatch scene transition
349 |       document.querySelector("a[href=end]").click()
350 |     }).then(() => new Promise(process.nextTick)).then(() => {
351 |       expect(document.getElementById("content").innerHTML).toContain("The end")
352 |       expect(document.getElementById("end-style").innerHTML).toContain("background-color: green")
353 |       expect(document.getElementById("end-style").disabled).toEqual(false)
354 |       expect(document.getElementById("index-style").disabled).toEqual(true)
355 | 
356 |       // Dispatch scene transition
357 |       document.querySelector("a[href=index]").click()
358 |     }).then(() => new Promise(process.nextTick)).then(() => {
359 |       expect(document.getElementById("content").innerHTML).toContain("Once upon a time...")
360 |       expect(document.getElementById("index-style").disabled).toEqual(false)
361 |       expect(document.getElementById("end-style").disabled).toEqual(true)
362 |     })
363 |   })
364 | 
365 |   test("updates the game state", () => {
366 |     const gistContent = JSON.stringify({
367 |       files: {
368 |         "index.markdown": { raw_url: "http://gists/index.markdown" },
369 |         "brave-knight.markdown": { raw_url: "http://gists/brave-knight.markdown" },
370 |         "evil-king.markdown": { raw_url: "http://gists/evil-king.markdown" },
371 |         "end.markdown": { raw_url: "http://gists/end.markdown" }
372 |       }
373 |     })
374 |     const indexContent = "Once upon a time [a brave knight](brave-knight) fought an [evil king](evil-king)..."
375 |     const knightContent =
376 |       "---\n" +
377 |       "state:\n" +
378 |       "  brave: true\n" +
379 |       "---\n\n" +
380 |       "You're so brave! [continue...](end)"
381 |     const kingContent =
382 |       "---\n" +
383 |       "state:\n" +
384 |       "  evil: true\n" +
385 |       "---\n\n" +
386 |       "You're so evil! [continue...](end)"
387 |     const endContent =
388 |       "{{#brave}}Everyone lived happily ever after.{{/brave}}\n" +
389 |       "{{#evil}}No one lived happily ever after.{{/evil}}"
390 |     const httpGet = require("../src/backend/httpGet")
391 |     httpGet.default.mockImplementation((url) => {
392 |       switch (url) {
393 |         case "http://gists/index.markdown":
394 |           return Promise.resolve(indexContent)
395 |         case "http://gists/brave-knight.markdown":
396 |           return Promise.resolve(knightContent)
397 |         case "http://gists/evil-king.markdown":
398 |           return Promise.resolve(kingContent)
399 |         case "http://gists/end.markdown":
400 |           return Promise.resolve(endContent)
401 |       }
402 |       return Promise.resolve(gistContent)
403 |     })
404 | 
405 |     // Dispatch the DOMContentLoaded event
406 |     document.dispatchEvent(new Event("DOMContentLoaded"))
407 | 
408 |     return new Promise(process.nextTick).then(() => {
409 |       expect(document.getElementById("content").innerHTML).toContain("Once upon a time")
410 |       expect(window.state).toEqual({})
411 | 
412 |       // Dispatch scene transition
413 |       document.querySelector("a[href=brave-knight]").click()
414 |     }).then(() => new Promise(process.nextTick)).then(() => {
415 |       expect(document.getElementById("content").innerHTML).toContain("You're so brave!")
416 |       expect(window.state).toEqual({ brave: true })
417 | 
418 |       // Dispatch scene transition
419 |       document.querySelector("a[href=end]").click()
420 |     }).then(() => new Promise(process.nextTick)).then(() => {
421 |       expect(document.getElementById("content").innerHTML).toContain("Everyone lived happily ever after")
422 |       expect(document.getElementById("content").innerHTML).not.toContain("No one lived happily ever after")
423 |     })
424 |   })
425 | })
426 | 


--------------------------------------------------------------------------------