squiffy-runtime 6.0.0-alpha.1 → 6.0.0-alpha.3

package/dist/squiffy.runtime.d.ts

@@ -0,0 +1,45 @@
+interface SquiffyInitOptions {
+    element: HTMLElement;
+    story: Story;
+    scroll?: string;
+    persist?: boolean;
+    onSet?: (attribute: string, value: any) => void;
+}
+interface SquiffyApi {
+    restart: () => void;
+    get: (attribute: string) => any;
+    set: (attribute: string, value: any) => void;
+    clickLink: (link: HTMLElement) => void;
+}
+interface SquiffyJsFunctionApi {
+    get: (attribute: string) => any;
+    set: (attribute: string, value: any) => void;
+    ui: {
+        transition: (f: any) => void;
+    };
+    story: {
+        go: (section: string) => void;
+    };
+}
+interface Story {
+    js: ((squiffy: SquiffyJsFunctionApi, get: (attribute: string) => any, set: (attribute: string, value: any) => void) => void)[];
+    start: string;
+    id?: string | null;
+    sections: Record<string, Section>;
+}
+interface Section {
+    text?: string;
+    clear?: boolean;
+    attributes?: string[];
+    jsIndex?: number;
+    passages?: Record<string, Passage>;
+    passageCount?: number;
+}
+interface Passage {
+    text?: string;
+    clear?: boolean;
+    attributes?: string[];
+    jsIndex?: number;
+}
+export declare const init: (options: SquiffyInitOptions) => SquiffyApi;
+export {};

package/dist/squiffy.runtime.js

@@ -0,0 +1,603 @@
+export const init = (options) => {
+    let story;
+    let currentSection;
+    let currentSectionElement;
+    let scrollPosition = 0;
+    let outputElement;
+    let settings;
+    let storageFallback = {};
+    function set(attribute, value) {
+        if (typeof value === 'undefined')
+            value = true;
+        if (settings.persist && window.localStorage) {
+            localStorage[story.id + '-' + attribute] = JSON.stringify(value);
+        }
+        else {
+            storageFallback[attribute] = JSON.stringify(value);
+        }
+        settings.onSet(attribute, value);
+    }
+    function get(attribute) {
+        let result;
+        if (settings.persist && window.localStorage) {
+            result = localStorage[story.id + '-' + attribute];
+        }
+        else {
+            result = storageFallback[attribute];
+        }
+        if (!result)
+            return null;
+        return JSON.parse(result);
+    }
+    function handleLink(link) {
+        if (link.classList.contains('disabled'))
+            return;
+        let passage = link.getAttribute('data-passage');
+        let section = link.getAttribute('data-section');
+        const rotateAttr = link.getAttribute('data-rotate');
+        const sequenceAttr = link.getAttribute('data-sequence');
+        const rotateOrSequenceAttr = rotateAttr || sequenceAttr;
+        if (passage) {
+            disableLink(link);
+            set('_turncount', get('_turncount') + 1);
+            passage = processLink(passage);
+            if (passage) {
+                currentSectionElement?.appendChild(document.createElement('hr'));
+                showPassage(passage);
+            }
+            const turnPassage = '@' + get('_turncount');
+            if (currentSection.passages) {
+                if (turnPassage in currentSection.passages) {
+                    showPassage(turnPassage);
+                }
+                if ('@last' in currentSection.passages && get('_turncount') >= (currentSection.passageCount || 0)) {
+                    showPassage('@last');
+                }
+            }
+        }
+        else if (section) {
+            currentSectionElement?.appendChild(document.createElement('hr'));
+            disableLink(link);
+            section = processLink(section);
+            if (section) {
+                go(section);
+            }
+        }
+        else if (rotateOrSequenceAttr) {
+            const result = rotate(rotateOrSequenceAttr, rotateAttr ? link.innerText : '');
+            link.innerHTML = result[0].replace(/"/g, '"').replace(/'/g, '\'');
+            const dataAttribute = rotateAttr ? 'data-rotate' : 'data-sequence';
+            link.setAttribute(dataAttribute, result[1] || '');
+            if (!result[1]) {
+                disableLink(link);
+            }
+            const attribute = link.getAttribute('data-attribute');
+            if (attribute) {
+                set(attribute, result[0]);
+            }
+            save();
+        }
+    }
+    function handleClick(event) {
+        const target = event.target;
+        if (target.classList.contains('squiffy-link')) {
+            handleLink(target);
+        }
+    }
+    function disableLink(link) {
+        link.classList.add('disabled');
+        link.setAttribute('tabindex', '-1');
+    }
+    function disableLinks(links) {
+        links.forEach(disableLink);
+    }
+    function begin() {
+        if (!load()) {
+            go(story.start);
+        }
+    }
+    function processLink(link) {
+        const sections = link.split(',');
+        let first = true;
+        let target = null;
+        sections.forEach(function (section) {
+            section = section.trim();
+            if (startsWith(section, '@replace ')) {
+                replaceLabel(section.substring(9));
+            }
+            else {
+                if (first) {
+                    target = section;
+                }
+                else {
+                    setAttribute(section);
+                }
+            }
+            first = false;
+        });
+        return target;
+    }
+    function setAttribute(expr) {
+        expr = expr.replace(/^(\w*\s*):=(.*)$/, (_, name, value) => (name + "=" + ui.processText(value)));
+        const setRegex = /^([\w]*)\s*=\s*(.*)$/;
+        const setMatch = setRegex.exec(expr);
+        if (setMatch) {
+            const lhs = setMatch[1];
+            let rhs = setMatch[2];
+            if (isNaN(rhs)) {
+                if (startsWith(rhs, "@"))
+                    rhs = get(rhs.substring(1));
+                set(lhs, rhs);
+            }
+            else {
+                set(lhs, parseFloat(rhs));
+            }
+        }
+        else {
+            const incDecRegex = /^([\w]*)\s*([\+\-\*\/])=\s*(.*)$/;
+            const incDecMatch = incDecRegex.exec(expr);
+            if (incDecMatch) {
+                const lhs = incDecMatch[1];
+                const op = incDecMatch[2];
+                let rhs = incDecMatch[3];
+                if (startsWith(rhs, "@"))
+                    rhs = get(rhs.substring(1));
+                const rhsNumeric = parseFloat(rhs);
+                let value = get(lhs);
+                if (value === null)
+                    value = 0;
+                if (op == '+') {
+                    value += rhsNumeric;
+                }
+                if (op == '-') {
+                    value -= rhsNumeric;
+                }
+                if (op == '*') {
+                    value *= rhsNumeric;
+                }
+                if (op == '/') {
+                    value /= rhsNumeric;
+                }
+                set(lhs, value);
+            }
+            else {
+                let value = true;
+                if (startsWith(expr, 'not ')) {
+                    expr = expr.substring(4);
+                    value = false;
+                }
+                set(expr, value);
+            }
+        }
+    }
+    function replaceLabel(expr) {
+        const regex = /^([\w]*)\s*=\s*(.*)$/;
+        const match = regex.exec(expr);
+        if (!match)
+            return;
+        const label = match[1];
+        let text = match[2];
+        if (currentSection.passages && text in currentSection.passages) {
+            text = currentSection.passages[text].text || '';
+        }
+        else if (text in story.sections) {
+            text = story.sections[text].text || '';
+        }
+        const stripParags = /^<p>(.*)<\/p>$/;
+        const stripParagsMatch = stripParags.exec(text);
+        if (stripParagsMatch) {
+            text = stripParagsMatch[1];
+        }
+        const labelElement = outputElement.querySelector('.squiffy-label-' + label);
+        if (!labelElement)
+            return;
+        labelElement.addEventListener('transitionend', function () {
+            labelElement.innerHTML = ui.processText(text);
+            labelElement.addEventListener('transitionend', function () {
+                save();
+            }, { once: true });
+            labelElement.classList.remove('fade-out');
+            labelElement.classList.add('fade-in');
+        }, { once: true });
+        labelElement.classList.add('fade-out');
+    }
+    function go(section) {
+        set('_transition', null);
+        newSection();
+        currentSection = story.sections[section];
+        if (!currentSection)
+            return;
+        set('_section', section);
+        setSeen(section);
+        const master = story.sections[''];
+        if (master) {
+            run(master);
+            ui.write(master.text || '');
+        }
+        run(currentSection);
+        // The JS might have changed which section we're in
+        if (get('_section') == section) {
+            set('_turncount', 0);
+            ui.write(currentSection.text || '');
+            save();
+        }
+    }
+    function run(section) {
+        if (section.clear) {
+            ui.clearScreen();
+        }
+        if (section.attributes) {
+            processAttributes(section.attributes.map(line => line.replace(/^random\s*:\s*(\w+)\s*=\s*(.+)/i, (line, attr, options) => (options = options.split("|")) ? attr + " = " + options[Math.floor(Math.random() * options.length)] : line)));
+        }
+        if (section.jsIndex !== undefined) {
+            const squiffy = {
+                get: get,
+                set: set,
+                ui: {
+                    transition: ui.transition,
+                },
+                story: {
+                    go: go,
+                },
+            };
+            story.js[section.jsIndex](squiffy, get, set);
+        }
+    }
+    function showPassage(passageName) {
+        let passage = currentSection.passages && currentSection.passages[passageName];
+        const masterSection = story.sections[''];
+        if (!passage && masterSection && masterSection.passages)
+            passage = masterSection.passages[passageName];
+        if (!passage)
+            return;
+        setSeen(passageName);
+        if (masterSection && masterSection.passages) {
+            const masterPassage = masterSection.passages[''];
+            if (masterPassage) {
+                run(masterPassage);
+                ui.write(masterPassage.text || '');
+            }
+        }
+        const master = currentSection.passages && currentSection.passages[''];
+        if (master) {
+            run(master);
+            ui.write(master.text || '');
+        }
+        run(passage);
+        ui.write(passage.text || '');
+        save();
+    }
+    function processAttributes(attributes) {
+        attributes.forEach(function (attribute) {
+            if (startsWith(attribute, '@replace ')) {
+                replaceLabel(attribute.substring(9));
+            }
+            else {
+                setAttribute(attribute);
+            }
+        });
+    }
+    function restart() {
+        if (settings.persist && window.localStorage && story.id) {
+            const keys = Object.keys(localStorage);
+            for (const key of keys) {
+                if (startsWith(key, story.id)) {
+                    localStorage.removeItem(key);
+                }
+            }
+        }
+        else {
+            storageFallback = {};
+        }
+        if (settings.scroll === 'element') {
+            outputElement.innerHTML = '';
+            begin();
+        }
+        else {
+            location.reload();
+        }
+    }
+    function save() {
+        set('_output', outputElement.innerHTML);
+    }
+    function load() {
+        const output = get('_output');
+        if (!output)
+            return false;
+        outputElement.innerHTML = output;
+        const element = document.getElementById(get('_output-section'));
+        if (!element)
+            return false;
+        currentSectionElement = element;
+        currentSection = story.sections[get('_section')];
+        const transition = get('_transition');
+        if (transition) {
+            eval('(' + transition + ')()');
+        }
+        return true;
+    }
+    function setSeen(sectionName) {
+        let seenSections = get('_seen_sections');
+        if (!seenSections)
+            seenSections = [];
+        if (seenSections.indexOf(sectionName) == -1) {
+            seenSections.push(sectionName);
+            set('_seen_sections', seenSections);
+        }
+    }
+    function seen(sectionName) {
+        const seenSections = get('_seen_sections');
+        if (!seenSections)
+            return false;
+        return (seenSections.indexOf(sectionName) > -1);
+    }
+    function newSection() {
+        if (currentSectionElement) {
+            disableLinks(currentSectionElement.querySelectorAll('.squiffy-link'));
+            currentSectionElement.querySelectorAll('input').forEach(el => {
+                const attribute = el.getAttribute('data-attribute') || el.id;
+                if (attribute)
+                    set(attribute, el.value);
+                el.disabled = true;
+            });
+            currentSectionElement.querySelectorAll("[contenteditable]").forEach(el => {
+                const attribute = el.getAttribute('data-attribute') || el.id;
+                if (attribute)
+                    set(attribute, el.innerHTML);
+                el.contentEditable = 'false';
+            });
+            currentSectionElement.querySelectorAll('textarea').forEach(el => {
+                const attribute = el.getAttribute('data-attribute') || el.id;
+                if (attribute)
+                    set(attribute, el.value);
+                el.disabled = true;
+            });
+        }
+        const sectionCount = get('_section-count') + 1;
+        set('_section-count', sectionCount);
+        const id = 'squiffy-section-' + sectionCount;
+        currentSectionElement = document.createElement('div');
+        currentSectionElement.id = id;
+        outputElement.appendChild(currentSectionElement);
+        set('_output-section', id);
+    }
+    const ui = {
+        write: (text) => {
+            if (!currentSectionElement)
+                return;
+            scrollPosition = outputElement.scrollHeight;
+            const div = document.createElement('div');
+            currentSectionElement.appendChild(div);
+            div.innerHTML = ui.processText(text);
+            ui.scrollToEnd();
+        },
+        clearScreen: () => {
+            outputElement.innerHTML = '';
+            newSection();
+        },
+        scrollToEnd: () => {
+            if (settings.scroll === 'element') {
+                const scrollTo = outputElement.scrollHeight - outputElement.clientHeight;
+                const currentScrollTop = outputElement.scrollTop;
+                if (scrollTo > (currentScrollTop || 0)) {
+                    outputElement.scrollTo({ top: scrollTo, behavior: 'smooth' });
+                }
+            }
+            else {
+                let scrollTo = scrollPosition;
+                const currentScrollTop = Math.max(document.body.scrollTop, document.documentElement.scrollTop);
+                if (scrollTo > currentScrollTop) {
+                    const maxScrollTop = document.documentElement.scrollHeight - window.innerHeight;
+                    if (scrollTo > maxScrollTop)
+                        scrollTo = maxScrollTop;
+                    window.scrollTo({ top: scrollTo, behavior: 'smooth' });
+                }
+            }
+        },
+        processText: (text) => {
+            function process(text, data) {
+                let containsUnprocessedSection = false;
+                const open = text.indexOf('{');
+                let close;
+                if (open > -1) {
+                    let nestCount = 1;
+                    let searchStart = open + 1;
+                    let finished = false;
+                    while (!finished) {
+                        const nextOpen = text.indexOf('{', searchStart);
+                        const nextClose = text.indexOf('}', searchStart);
+                        if (nextClose > -1) {
+                            if (nextOpen > -1 && nextOpen < nextClose) {
+                                nestCount++;
+                                searchStart = nextOpen + 1;
+                            }
+                            else {
+                                nestCount--;
+                                searchStart = nextClose + 1;
+                                if (nestCount === 0) {
+                                    close = nextClose;
+                                    containsUnprocessedSection = true;
+                                    finished = true;
+                                }
+                            }
+                        }
+                        else {
+                            finished = true;
+                        }
+                    }
+                }
+                if (containsUnprocessedSection) {
+                    const section = text.substring(open + 1, close);
+                    const value = processTextCommand(section, data);
+                    text = text.substring(0, open) + value + process(text.substring(close + 1), data);
+                }
+                return (text);
+            }
+            function processTextCommand(text, data) {
+                if (startsWith(text, 'if ')) {
+                    return processTextCommand_If(text, data);
+                }
+                else if (startsWith(text, 'else:')) {
+                    return processTextCommand_Else(text, data);
+                }
+                else if (startsWith(text, 'label:')) {
+                    return processTextCommand_Label(text, data);
+                }
+                else if (/^rotate[: ]/.test(text)) {
+                    return processTextCommand_Rotate('rotate', text);
+                }
+                else if (/^sequence[: ]/.test(text)) {
+                    return processTextCommand_Rotate('sequence', text);
+                }
+                else if (currentSection.passages && text in currentSection.passages) {
+                    return process(currentSection.passages[text].text || '', data);
+                }
+                else if (text in story.sections) {
+                    return process(story.sections[text].text || '', data);
+                }
+                else if (startsWith(text, '@') && !startsWith(text, '@replace')) {
+                    processAttributes(text.substring(1).split(","));
+                    return "";
+                }
+                return get(text);
+            }
+            function processTextCommand_If(section, data) {
+                const command = section.substring(3);
+                const colon = command.indexOf(':');
+                if (colon == -1) {
+                    return ('{if ' + command + '}');
+                }
+                const text = command.substring(colon + 1);
+                let condition = command.substring(0, colon);
+                condition = condition.replace("<", "&lt;");
+                const operatorRegex = /([\w ]*)(=|&lt;=|&gt;=|&lt;&gt;|&lt;|&gt;)(.*)/;
+                const match = operatorRegex.exec(condition);
+                let result = false;
+                if (match) {
+                    const lhs = get(match[1]);
+                    const op = match[2];
+                    let rhs = match[3];
+                    if (startsWith(rhs, '@'))
+                        rhs = get(rhs.substring(1));
+                    if (op == '=' && lhs == rhs)
+                        result = true;
+                    if (op == '&lt;&gt;' && lhs != rhs)
+                        result = true;
+                    if (op == '&gt;' && lhs > rhs)
+                        result = true;
+                    if (op == '&lt;' && lhs < rhs)
+                        result = true;
+                    if (op == '&gt;=' && lhs >= rhs)
+                        result = true;
+                    if (op == '&lt;=' && lhs <= rhs)
+                        result = true;
+                }
+                else {
+                    let checkValue = true;
+                    if (startsWith(condition, 'not ')) {
+                        condition = condition.substring(4);
+                        checkValue = false;
+                    }
+                    if (startsWith(condition, 'seen ')) {
+                        result = (seen(condition.substring(5)) == checkValue);
+                    }
+                    else {
+                        let value = get(condition);
+                        if (value === null)
+                            value = false;
+                        result = (value == checkValue);
+                    }
+                }
+                const textResult = result ? process(text, data) : '';
+                data.lastIf = result;
+                return textResult;
+            }
+            function processTextCommand_Else(section, data) {
+                if (!('lastIf' in data) || data.lastIf)
+                    return '';
+                const text = section.substring(5);
+                return process(text, data);
+            }
+            function processTextCommand_Label(section, data) {
+                const command = section.substring(6);
+                const eq = command.indexOf('=');
+                if (eq == -1) {
+                    return ('{label:' + command + '}');
+                }
+                const text = command.substring(eq + 1);
+                const label = command.substring(0, eq);
+                return '<span class="squiffy-label-' + label + '">' + process(text, data) + '</span>';
+            }
+            function processTextCommand_Rotate(type, section) {
+                let options;
+                let attribute = '';
+                if (section.substring(type.length, type.length + 1) == ' ') {
+                    const colon = section.indexOf(':');
+                    if (colon == -1) {
+                        return '{' + section + '}';
+                    }
+                    options = section.substring(colon + 1);
+                    attribute = section.substring(type.length + 1, colon);
+                }
+                else {
+                    options = section.substring(type.length + 1);
+                }
+                // TODO: Check - previously there was no second parameter here
+                const rotation = rotate(options.replace(/"/g, '&quot;').replace(/'/g, '&#39;'), null);
+                if (attribute) {
+                    set(attribute, rotation[0]);
+                }
+                return '<a class="squiffy-link" data-' + type + '="' + rotation[1] + '" data-attribute="' + attribute + '" role="link">' + rotation[0] + '</a>';
+            }
+            const data = {
+                fulltext: text
+            };
+            return process(text, data);
+        },
+        transition: function (f) {
+            set('_transition', f.toString());
+            f();
+        },
+    };
+    function startsWith(string, prefix) {
+        return string.substring(0, prefix.length) === prefix;
+    }
+    function rotate(options, current) {
+        const colon = options.indexOf(':');
+        if (colon == -1) {
+            return [options, current];
+        }
+        const next = options.substring(0, colon);
+        let remaining = options.substring(colon + 1);
+        if (current)
+            remaining += ':' + current;
+        return [next, remaining];
+    }
+    outputElement = options.element;
+    story = options.story;
+    settings = {
+        scroll: options.scroll || 'body',
+        persist: (options.persist === undefined) ? true : options.persist,
+        onSet: options.onSet || (() => { })
+    };
+    if (options.persist === true && !story.id) {
+        console.warn("Persist is set to true in Squiffy runtime options, but no story id has been set. Persist will be disabled.");
+        settings.persist = false;
+    }
+    if (settings.scroll === 'element') {
+        outputElement.style.overflowY = 'auto';
+    }
+    document.addEventListener('click', handleClick);
+    document.addEventListener('keypress', function (event) {
+        if (event.key !== "Enter")
+            return;
+        handleClick(event);
+    });
+    begin();
+    return {
+        restart: restart,
+        get: get,
+        set: set,
+        clickLink: handleLink
+    };
+};

package/package.json

@@ -1,15 +1,26 @@
 {
   "name": "squiffy-runtime",
-  "version": "6.0.0-alpha.1",
-  "main": "squiffy.runtime.js",
+  "version": "6.0.0-alpha.3",
+  "main": "dist/squiffy.runtime.js",
+  "types": "dist/squiffy.runtime.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest",
     "build": "tsc"
   },
   "author": "Alex Warren",
+  "contributors": [
+    "CrisisSDK",
+    "mrangel",
+    "Luis Felipe Morales"
+  ],
   "license": "MIT",
   "description": "",
-  "dependencies": {
-    "typescript": "^5.6.2"
+  "devDependencies": {
+    "@types/jsdom": "^21.1.7",
+    "global-jsdom": "^25.0.0",
+    "jsdom": "^25.0.0",
+    "squiffy-compiler": "^6.0.0-alpha.2",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
   }
 }

package/src/__snapshots__/squiffy.runtime.test.ts.snap

@@ -0,0 +1,54 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`"Hello world" script should run 1`] = `
+"
+    <div id="squiffy-section-1"><div><p>Hello world</p></div></div>"
+`;
+
+exports[`Click a passage link 1`] = `
+"
+    <div id="squiffy-section-1"><div><h1>Squiffy Test</h1>
+<p>This is <a href="http://textadventures.co.uk">a website link</a>.</p>
+<p>This should be <a class="squiffy-link link-passage" data-passage="passage" role="link" tabindex="0">a link to a passage</a>. Here's <a class="squiffy-link link-passage" data-passage="passage2" role="link" tabindex="0">another one</a>.</p>
+<p>You don't need to specify a name - for example, this <a class="squiffy-link link-passage" data-passage="link" role="link" tabindex="0">link</a> and this <a class="squiffy-link link-section" data-section="section" role="link" tabindex="0">section</a>.</p>
+<p>And this goes to the <a class="squiffy-link link-section" data-section="section2" role="link" tabindex="0">next section</a>.</p>
+<p>This line has links to <a class="squiffy-link link-section" data-section="section 3" role="link" tabindex="0">section 3</a> and <a class="squiffy-link link-section" data-section="section four" role="link" tabindex="0">section 4</a>.</p>
+<p>This line has links to <a class="squiffy-link link-passage" data-passage="passage 3" role="link" tabindex="0">passage 3</a> and <a class="squiffy-link link-passage" data-passage="passage four" role="link" tabindex="0">passage 4</a>.</p>
+<p>Oh look - <a class="squiffy-link link-passage" data-passage="it's a passage with an apostrophe" role="link" tabindex="0">it's a passage with an apostrophe</a>.</p></div></div>"
+`;
+
+exports[`Click a passage link 2`] = `
+"
+    <div id="squiffy-section-1"><div><h1>Squiffy Test</h1>
+<p>This is <a href="http://textadventures.co.uk">a website link</a>.</p>
+<p>This should be <a class="squiffy-link link-passage disabled" data-passage="passage" role="link" tabindex="-1">a link to a passage</a>. Here's <a class="squiffy-link link-passage" data-passage="passage2" role="link" tabindex="0">another one</a>.</p>
+<p>You don't need to specify a name - for example, this <a class="squiffy-link link-passage" data-passage="link" role="link" tabindex="0">link</a> and this <a class="squiffy-link link-section" data-section="section" role="link" tabindex="0">section</a>.</p>
+<p>And this goes to the <a class="squiffy-link link-section" data-section="section2" role="link" tabindex="0">next section</a>.</p>
+<p>This line has links to <a class="squiffy-link link-section" data-section="section 3" role="link" tabindex="0">section 3</a> and <a class="squiffy-link link-section" data-section="section four" role="link" tabindex="0">section 4</a>.</p>
+<p>This line has links to <a class="squiffy-link link-passage" data-passage="passage 3" role="link" tabindex="0">passage 3</a> and <a class="squiffy-link link-passage" data-passage="passage four" role="link" tabindex="0">passage 4</a>.</p>
+<p>Oh look - <a class="squiffy-link link-passage" data-passage="it's a passage with an apostrophe" role="link" tabindex="0">it's a passage with an apostrophe</a>.</p></div><hr><div><p>Here's some text for the passage.</p></div></div>"
+`;
+
+exports[`Click a section link 1`] = `
+"
+    <div id="squiffy-section-1"><div><h1>Squiffy Test</h1>
+<p>This is <a href="http://textadventures.co.uk">a website link</a>.</p>
+<p>This should be <a class="squiffy-link link-passage" data-passage="passage" role="link" tabindex="0">a link to a passage</a>. Here's <a class="squiffy-link link-passage" data-passage="passage2" role="link" tabindex="0">another one</a>.</p>
+<p>You don't need to specify a name - for example, this <a class="squiffy-link link-passage" data-passage="link" role="link" tabindex="0">link</a> and this <a class="squiffy-link link-section" data-section="section" role="link" tabindex="0">section</a>.</p>
+<p>And this goes to the <a class="squiffy-link link-section" data-section="section2" role="link" tabindex="0">next section</a>.</p>
+<p>This line has links to <a class="squiffy-link link-section" data-section="section 3" role="link" tabindex="0">section 3</a> and <a class="squiffy-link link-section" data-section="section four" role="link" tabindex="0">section 4</a>.</p>
+<p>This line has links to <a class="squiffy-link link-passage" data-passage="passage 3" role="link" tabindex="0">passage 3</a> and <a class="squiffy-link link-passage" data-passage="passage four" role="link" tabindex="0">passage 4</a>.</p>
+<p>Oh look - <a class="squiffy-link link-passage" data-passage="it's a passage with an apostrophe" role="link" tabindex="0">it's a passage with an apostrophe</a>.</p></div></div>"
+`;
+
+exports[`Click a section link 2`] = `
+"
+    <div id="squiffy-section-1"><div><h1>Squiffy Test</h1>
+<p>This is <a href="http://textadventures.co.uk">a website link</a>.</p>
+<p>This should be <a class="squiffy-link link-passage disabled" data-passage="passage" role="link" tabindex="-1">a link to a passage</a>. Here's <a class="squiffy-link link-passage disabled" data-passage="passage2" role="link" tabindex="-1">another one</a>.</p>
+<p>You don't need to specify a name - for example, this <a class="squiffy-link link-passage disabled" data-passage="link" role="link" tabindex="-1">link</a> and this <a class="squiffy-link link-section disabled" data-section="section" role="link" tabindex="-1">section</a>.</p>
+<p>And this goes to the <a class="squiffy-link link-section disabled" data-section="section2" role="link" tabindex="-1">next section</a>.</p>
+<p>This line has links to <a class="squiffy-link link-section disabled" data-section="section 3" role="link" tabindex="-1">section 3</a> and <a class="squiffy-link link-section disabled" data-section="section four" role="link" tabindex="-1">section 4</a>.</p>
+<p>This line has links to <a class="squiffy-link link-passage disabled" data-passage="passage 3" role="link" tabindex="-1">passage 3</a> and <a class="squiffy-link link-passage disabled" data-passage="passage four" role="link" tabindex="-1">passage 4</a>.</p>
+<p>Oh look - <a class="squiffy-link link-passage disabled" data-passage="it's a passage with an apostrophe" role="link" tabindex="-1">it's a passage with an apostrophe</a>.</p></div><hr></div><div id="squiffy-section-2"><div><p>Another section is here.</p></div></div>"
+`;

package/src/squiffy.runtime.test.ts

@@ -0,0 +1,173 @@
+import { expect, test, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import globalJsdom from 'global-jsdom';
+import { init } from './squiffy.runtime.js';
+import { compile } from 'squiffy-compiler'; 
+
+const html = `
+<!DOCTYPE html>
+<html>
+<head>
+</head>
+<body>
+    <div id="squiffy">
+    </div>
+    <div id="test">
+    </div>
+</body>
+</html>
+`;
+
+const initScript = async (script: string) => {
+    globalJsdom(html);
+    const element = document.getElementById('squiffy');
+
+    if (!element) {
+        throw new Error('Element not found');
+    }
+
+    const compileResult = await compile({
+        scriptBaseFilename: "filename.squiffy", // TODO: This shouldn't be required
+        script: script,
+    });
+
+    if (!compileResult.success) {
+        throw new Error('Compile failed');
+    }
+
+    const story = compileResult.output.story;
+    const js = compileResult.output.js.map(jsLines => new Function('squiffy', 'get', 'set', jsLines.join('\n')));
+
+    const squiffyApi = init({
+        element: element,
+        story: {
+            js: js as any,
+            ...story,
+        },
+    });
+
+    return {
+        squiffyApi,
+        element
+    }
+};
+
+const findLink = (element: HTMLElement, linkType: string, linkText: string, onlyEnabled: boolean = false) => {
+    const links = element.querySelectorAll(`a.squiffy-link.link-${linkType}`);
+    return Array.from(links).find(link => link.textContent === linkText && (onlyEnabled ? !link.classList.contains("disabled") : true)) as HTMLElement;
+};
+
+const getTestOutput = () => {
+    const testElement = document.getElementById('test');
+    if (!testElement) {
+        throw new Error('Test element not found');
+    }
+    return testElement.innerText;
+}
+
+let cleanup: { (): void };
+
+beforeEach(() => {
+    cleanup = globalJsdom();
+});
+
+afterEach(() => {
+    cleanup();
+});
+
+test('"Hello world" script should run', async () => {
+    const { element } = await initScript("Hello world");
+    expect(element.innerHTML).toMatchSnapshot();
+});
+
+test('Click a section link', async () => {
+    const script = await fs.readFile('../examples/test/example.squiffy', 'utf-8');
+    const { squiffyApi, element } = await initScript(script);
+    expect(element.innerHTML).toMatchSnapshot();
+
+    expect(element.querySelectorAll('a.squiffy-link').length).toBe(10);
+    const linkToPassage = findLink(element, 'passage', 'a link to a passage');
+    const section3Link = findLink(element, 'section', 'section 3');
+
+    expect(linkToPassage).toBeDefined();
+    expect(section3Link).toBeDefined();
+    expect(linkToPassage.classList).not.toContain('disabled');
+    expect(section3Link.classList).not.toContain('disabled');
+
+    squiffyApi.clickLink(section3Link);
+
+    expect(linkToPassage.classList).toContain('disabled');
+    expect(section3Link.classList).toContain('disabled');
+    expect(element.innerHTML).toMatchSnapshot();
+});
+
+test('Click a passage link', async () => {
+    const script = await fs.readFile('../examples/test/example.squiffy', 'utf-8');
+    const { squiffyApi, element } = await initScript(script);
+    expect(element.innerHTML).toMatchSnapshot();
+
+    expect(element.querySelectorAll('a.squiffy-link').length).toBe(10);
+    const linkToPassage = findLink(element, 'passage', 'a link to a passage');
+    const section3Link = findLink(element, 'section', 'section 3');
+
+    expect(linkToPassage).toBeDefined();
+    expect(section3Link).toBeDefined();
+    expect(linkToPassage.classList).not.toContain('disabled');
+    expect(section3Link.classList).not.toContain('disabled');
+
+    squiffyApi.clickLink(linkToPassage);
+
+    expect(linkToPassage.classList).toContain('disabled');
+    expect(section3Link.classList).not.toContain('disabled');
+    expect(element.innerHTML).toMatchSnapshot();
+});
+
+test('Run JavaScript functions', async () => {
+    const script = `
+    document.getElementById('test').innerText = 'Initial JavaScript';
+@set some_string = some_value
+@set some_number = 5
+
++++Continue...
+    document.getElementById('test').innerText = "Value: " + get("some_number");
++++Continue...
+    document.getElementById('test').innerText = "Value: " + get("some_string");
+    set("some_number", 10);
++++Continue...
+    document.getElementById('test').innerText = "Value: " + get("some_number");
++++Continue...
+@inc some_number
++++Continue...
+    document.getElementById('test').innerText = "Value: " + get("some_number");
++++Continue...
+    squiffy.story.go("other section");
+[[other section]]:
+    document.getElementById('test').innerText = "In other section";
+`;
+
+    const clickContinue = () => {
+        const continueLink = findLink(element, 'section', 'Continue...', true);
+        expect(continueLink).toBeDefined();
+        squiffyApi.clickLink(continueLink);
+    };
+
+    const { squiffyApi, element } = await initScript(script);
+
+    expect(getTestOutput()).toBe('Initial JavaScript');
+    clickContinue();
+    
+    expect(getTestOutput()).toBe('Value: 5');
+    clickContinue();
+
+    expect(getTestOutput()).toBe('Value: some_value');
+    clickContinue();
+
+    expect(getTestOutput()).toBe('Value: 10');
+
+    clickContinue();
+    clickContinue();
+    expect(getTestOutput()).toBe('Value: 11');
+
+    clickContinue();
+    expect(getTestOutput()).toBe('In other section');
+});

package/src/squiffy.runtime.ts

@@ -16,10 +16,28 @@ interface SquiffyApi {
     restart: () => void;
     get: (attribute: string) => any;
     set: (attribute: string, value: any) => void;
+    clickLink: (link: HTMLElement) => void;
+}
+
+// Previous versions of Squiffy had "squiffy", "get" and "set" as globals - we now pass these directly into JS functions.
+// We may tidy up this API at some point, though that would be a breaking change.
+interface SquiffyJsFunctionApi {
+    get: (attribute: string) => any;
+    set: (attribute: string, value: any) => void;
+    ui: {
+        transition: (f: any) => void;
+    };
+    story: {
+        go: (section: string) => void;
+    };
 }
 
 interface Story {
-    js: (() => void)[];
+    js: ((
+            squiffy: SquiffyJsFunctionApi,
+            get: (attribute: string) => any,
+            set: (attribute: string, value: any) => void
+        ) => void)[];
     start: string;
     id?: string | null;
     sections: Record<string, Section>;
@@ -73,68 +91,60 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
         return JSON.parse(result);
     }
     
-    function initLinkHandler() {
-        function handleLink(link: HTMLElement) {
-            if (link.classList.contains('disabled')) return;
-            let passage = link.getAttribute('data-passage');
-            let section = link.getAttribute('data-section');
-            const rotateAttr = link.getAttribute('data-rotate');
-            const sequenceAttr = link.getAttribute('data-sequence');
-            const rotateOrSequenceAttr = rotateAttr || sequenceAttr;
+    function handleLink(link: HTMLElement) {
+        if (link.classList.contains('disabled')) return;
+        let passage = link.getAttribute('data-passage');
+        let section = link.getAttribute('data-section');
+        const rotateAttr = link.getAttribute('data-rotate');
+        const sequenceAttr = link.getAttribute('data-sequence');
+        const rotateOrSequenceAttr = rotateAttr || sequenceAttr;
+        if (passage) {
+            disableLink(link);
+            set('_turncount', get('_turncount') + 1);
+            passage = processLink(passage);
             if (passage) {
-                disableLink(link);
-                set('_turncount', get('_turncount') + 1);
-                passage = processLink(passage);
-                if (passage) {
-                    currentSectionElement?.appendChild(document.createElement('hr'));
-                    showPassage(passage);
-                }
-                const turnPassage = '@' + get('_turncount');
-                if (currentSection.passages) {
-                    if (turnPassage in currentSection.passages) {
-                        showPassage(turnPassage);
-                    }
-                    if ('@last' in currentSection.passages && get('_turncount') >= (currentSection.passageCount || 0)) {
-                        showPassage('@last');
-                    }
-                }
-            }
-            else if (section) {
                 currentSectionElement?.appendChild(document.createElement('hr'));
-                disableLink(link);
-                section = processLink(section);
-                if (section) {
-                    go(section);
-                }
+                showPassage(passage);
             }
-            else if (rotateOrSequenceAttr) {
-                const result = rotate(rotateOrSequenceAttr, rotateAttr ? link.innerText : '');
-                link.innerHTML = result[0]!.replace(/&quot;/g, '"').replace(/&#39;/g, '\'');
-                const dataAttribute = rotateAttr ? 'data-rotate' : 'data-sequence';
-                link.setAttribute(dataAttribute, result[1] || '');
-                if (!result[1]) {
-                    disableLink(link);
+            const turnPassage = '@' + get('_turncount');
+            if (currentSection.passages) {
+                if (turnPassage in currentSection.passages) {
+                    showPassage(turnPassage);
                 }
-                const attribute = link.getAttribute('data-attribute');
-                if (attribute) {
-                    set(attribute, result[0]);
+                if ('@last' in currentSection.passages && get('_turncount') >= (currentSection.passageCount || 0)) {
+                    showPassage('@last');
                 }
-                save();
             }
         }
-    
-        function handleClick(event: Event) {
-            const target = event.target as HTMLElement;
-            if (target.classList.contains('squiffy-link')) {
-                handleLink(target);
+        else if (section) {
+            currentSectionElement?.appendChild(document.createElement('hr'));
+            disableLink(link);
+            section = processLink(section);
+            if (section) {
+                go(section);
             }
         }
-    
-        document.addEventListener('click', handleClick);
-        document.addEventListener('keypress', function (event) {
-            if (event.key !== "Enter") return;
-            handleClick(event);
-        });
+        else if (rotateOrSequenceAttr) {
+            const result = rotate(rotateOrSequenceAttr, rotateAttr ? link.innerText : '');
+            link.innerHTML = result[0]!.replace(/&quot;/g, '"').replace(/&#39;/g, '\'');
+            const dataAttribute = rotateAttr ? 'data-rotate' : 'data-sequence';
+            link.setAttribute(dataAttribute, result[1] || '');
+            if (!result[1]) {
+                disableLink(link);
+            }
+            const attribute = link.getAttribute('data-attribute');
+            if (attribute) {
+                set(attribute, result[0]);
+            }
+            save();
+        }
+    }
+
+    function handleClick(event: Event) {
+        const target = event.target as HTMLElement;
+        if (target.classList.contains('squiffy-link')) {
+            handleLink(target);
+        }
     }
     
     function disableLink(link: Element) {
@@ -289,7 +299,17 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
             processAttributes(section.attributes.map(line => line.replace(/^random\s*:\s*(\w+)\s*=\s*(.+)/i, (line, attr, options) => (options = options.split("|")) ? attr + " = " + options[Math.floor(Math.random() * options.length)] : line)));
         }
         if (section.jsIndex !== undefined) {
-            story.js[section.jsIndex]();
+            const squiffy = {
+                get: get,
+                set: set,
+                ui: {
+                    transition: ui.transition,
+                },
+                story: {
+                    go: go,
+                },
+            };
+            story.js[section.jsIndex](squiffy, get, set);
         }
     }
     
@@ -659,12 +679,18 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
         outputElement.style.overflowY = 'auto';
     }
 
-    initLinkHandler();
+    document.addEventListener('click', handleClick);
+    document.addEventListener('keypress', function (event) {
+        if (event.key !== "Enter") return;
+        handleClick(event);
+    });
+    
     begin();
 
     return {
         restart: restart,
         get: get,
         set: set,
+        clickLink: handleLink
     };
 };

package/tsconfig.json

@@ -7,6 +7,7 @@
       "noFallthroughCasesInSwitch": true,
       "skipLibCheck": true,
       "outDir": "dist",
+      "declaration": true,
     },
     "include": ["src/squiffy.runtime.ts"]
 }