squiffy-runtime 6.0.0-alpha.15 → 6.0.0-alpha.17

package/src/squiffy.runtime.ts

@@ -1,158 +1,129 @@
-import { SquiffyApi, SquiffyInitOptions, SquiffySettings, Story, Section } from './types.js';
-import { startsWith, rotate } from "./utils.js";
-import { TextProcessor } from './textProcessor.js';
-import { Emitter, SquiffyEventMap } from './events.js';
+import { SquiffyApi, SquiffyInitOptions, Story, Section, Passage } from "./types.js";
+import { TextProcessor } from "./textProcessor.js";
+import { Emitter, SquiffyEventMap } from "./events.js";
+import { State } from "./state.js";
+import { updateStory } from "./updater.js";
+import { PluginManager } from "./pluginManager.js";
+import { Plugins } from "./plugins/index.js";
+import { LinkHandler } from "./linkHandler.js";
+import { Animation } from "./animation.js";
+import { imports } from "./import.js";
 
-export type { SquiffyApi } from "./types.js"
+export type { SquiffyApi } from "./types.js";
 
-export const init = (options: SquiffyInitOptions): SquiffyApi => {
+export const init = async (options: SquiffyInitOptions): Promise<SquiffyApi> => {
     let story: Story;
     let currentSection: Section;
     let currentSectionElement: HTMLElement;
+    let currentPassageElement: HTMLElement;
     let currentBlockOutputElement: HTMLElement;
     let scrollPosition = 0;
-    let outputElement: HTMLElement;
-    let settings: SquiffySettings;
-    let storageFallback: Record<string, string> = {};
-    let textProcessor: TextProcessor;
     const emitter = new Emitter<SquiffyEventMap>();
+    const transitions: (() => Promise<void>)[] = [];
+    let runningTransitions = false;
     
-    function set(attribute: string, value: any) {
-        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: string): any {
-        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: HTMLElement): boolean {
-        const outputSection = link.closest('.squiffy-output-section');
+    async function handleLink(link: HTMLElement): Promise<boolean> {
+        if (runningTransitions) return false;
+        const outputSection = link.closest(".squiffy-output-section");
         if (outputSection !== currentSectionElement) return false;
 
-        if (link.classList.contains('disabled')) return false;
+        if (link.classList.contains("disabled")) return false;
+
+        const passage = link.getAttribute("data-passage");
+        const section = link.getAttribute("data-section");
 
-        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) {
+        if (passage !== null) {
             disableLink(link);
-            set('_turncount', get('_turncount') + 1);
-            passage = processLink(passage);
+            set("_turncount", get("_turncount") + 1);
+            await processLink(link);
             if (passage) {
-                newBlockOutputElement();
-                showPassage(passage);
+                currentBlockOutputElement = null;
+                await showPassage(passage);
             }
-            const turnPassage = '@' + get('_turncount');
+            const turnPassage = "@" + get("_turncount");
             if (currentSection.passages) {
                 if (turnPassage in currentSection.passages) {
-                    showPassage(turnPassage);
+                    await showPassage(turnPassage);
                 }
-                if ('@last' in currentSection.passages && get('_turncount') >= (currentSection.passageCount || 0)) {
-                    showPassage('@last');
+                if ("@last" in currentSection.passages && get("_turncount") >= (currentSection.passageCount || 0)) {
+                    await showPassage("@last");
                 }
             }
 
-            emitter.emit('linkClick', { linkType: 'passage' });
+            emitter.emit("linkClick", { linkType: "passage" });
             return true;
         }
         
-        if (section) {
-            section = processLink(section);
+        if (section !== null) {
+            await processLink(link);
             if (section) {
-                go(section);
+                await go(section);
             }
 
-            emitter.emit('linkClick', { linkType: 'section' });
+            emitter.emit("linkClick", { linkType: "section" });
             return true;
         }
+
+        const [handled, type, result] = linkHandler.handleLink(link);
         
-        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]) {
+        if (handled) {
+            if (result?.disableLink) {
                 disableLink(link);
             }
-            const attribute = link.getAttribute('data-attribute');
-            if (attribute) {
-                set(attribute, result[0]);
-            }
+
             save();
 
-            emitter.emit('linkClick', { linkType: rotateAttr ? 'rotate' : 'sequence' });
+            emitter.emit("linkClick", { linkType: type });
             return true;
         }
 
         return false;
     }
 
-    function handleClick(event: Event) {
+    async function handleClick(event: Event) {
         const target = event.target as HTMLElement;
-        if (target.classList.contains('squiffy-link')) {
-            handleLink(target);
+        if (target.classList.contains("squiffy-link")) {
+            await handleLink(target);
         }
     }
     
     function disableLink(link: Element) {
-        link.classList.add('disabled');
-        link.setAttribute('tabindex', '-1');
+        link.classList.add("disabled");
+        link.setAttribute("tabindex", "-1");
+    }
+
+    function enableLink(link: Element) {
+        link.classList.remove("disabled");
+        link.removeAttribute("tabindex");
     }
     
-    function begin() {
+    async function begin() {
         if (!load()) {
-            go(story.start);
+            await go(story.start);
         }
     }
     
-    function processLink(link: string): string | null {
-        const sections = link.split(',');
-        let first = true;
-        let target: string | null = null;
-        sections.forEach(function (section) {
-            section = section.trim();
-            if (startsWith(section, '@replace ')) {
-                replaceLabel(section.substring(9));
-            }
-            else {
-                if (first) {
-                    target = section;
-                }
-                else {
-                    setAttribute(section);
-                }
+    async function processLink(link: HTMLElement) {
+        animation.runLinkAnimation(link);
+        await runTransitions();
+        const settersJson = link.getAttribute("data-set");
+        if (settersJson) {
+            const setters = JSON.parse(settersJson) as string[];
+            for (const attribute of setters) {
+                setAttribute(attribute);
             }
-            first = false;
-        });
-        return target;
+        }
     }
     
     function setAttribute(expr: string) {
-        expr = expr.replace(/^(\w*\s*):=(.*)$/, (_, name, value) => (name + "=" + ui.processText(value)));
+        expr = expr.replace(/^(\w*\s*):=(.*)$/, (_, name, value) => (name + "=" + ui.processText(value, true)));
         const setRegex = /^([\w]*)\s*=\s*(.*)$/;
         const setMatch = setRegex.exec(expr);
         if (setMatch) {
             const lhs = setMatch[1];
             let rhs = setMatch[2];
             if (isNaN(rhs as any)) {
-                if (startsWith(rhs, "@")) rhs = get(rhs.substring(1));
+                if (rhs.startsWith("@")) rhs = get(rhs.substring(1));
                 set(lhs, rhs);
             }
             else {
@@ -160,33 +131,33 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
             }
         }
         else {
-            const incDecRegex = /^([\w]*)\s*([\+\-\*\/])=\s*(.*)$/;
+            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));
+                if (rhs.startsWith("@")) rhs = get(rhs.substring(1));
                 const rhsNumeric = parseFloat(rhs);
                 let value = get(lhs);
                 if (value === null) value = 0;
-                if (op == '+') {
+                if (op == "+") {
                     value += rhsNumeric;
                 }
-                if (op == '-') {
+                if (op == "-") {
                     value -= rhsNumeric;
                 }
-                if (op == '*') {
+                if (op == "*") {
                     value *= rhsNumeric;
                 }
-                if (op == '/') {
+                if (op == "/") {
                     value /= rhsNumeric;
                 }
                 set(lhs, value);
             }
             else {
                 let value = true;
-                if (startsWith(expr, 'not ')) {
+                if (expr.startsWith("not ")) {
                     expr = expr.substring(4);
                     value = false;
                 }
@@ -194,135 +165,143 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
             }
         }
     }
-    
-    function replaceLabel(expr: string) {
-        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(sectionName: string) {
-        set('_transition', null);
+
+    async function go(sectionName: string) {
+        const oldCanGoBack = canGoBack();
         newSection(sectionName);
         currentSection = story.sections[sectionName];
         if (!currentSection) return;
-        set('_section', sectionName);
-        setSeen(sectionName);
-        const master = story.sections[''];
+        set("_section", sectionName);
+        state.setSeen(sectionName);
+        const master = story.sections[""];
+        if (master?.clear || currentSection.clear) {
+            clearScreen();
+        }
         if (master) {
-            run(master);
-            ui.write(master.text || '', "[[]]");
+            await run(master, "[[]]");
         }
-        run(currentSection);
+        await run(currentSection, `[[${sectionName}]]`);
         // The JS might have changed which section we're in
-        if (get('_section') == sectionName) {
-            set('_turncount', 0);
-            ui.write(currentSection.text || '', `[[${sectionName}]]`);
+        if (get("_section") == sectionName) {
+            set("_turncount", 0);
+            writeUndoLog();
             save();
         }
+        const newCanGoBack = canGoBack();
+        if (newCanGoBack != oldCanGoBack) {
+            emitter.emit("canGoBackChanged", { canGoBack: newCanGoBack });
+        }
+    }
+
+    function runJs(index: number, extra: any = null) {
+        const squiffy = {
+            get: get,
+            set: set,
+            ui: {
+                transition: addTransition,
+                write: ui.write,
+                scrollToEnd: ui.scrollToEnd,
+            },
+            story: {
+                go: go,
+            },
+            element: outputElementContainer,
+            import: imports,
+            ...extra
+        };
+        story.js[index](squiffy, get, set);
     }
     
-    function run(section: Section) {
-        if (section.clear) {
-            ui.clearScreen();
-        }
+    async function run(section: Section, source: string) {
         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)));
+            await processAttributes(section.attributes);
         }
         if (section.jsIndex !== undefined) {
-            const squiffy = {
-                get: get,
-                set: set,
-                ui: {
-                    transition: ui.transition,
-                },
-                story: {
-                    go: go,
-                },
-            };
-            story.js[section.jsIndex](squiffy, get, set);
+            runJs(section.jsIndex);
         }
+
+        ui.write(section.text || "", source);
+
+        await runTransitions();
+    }
+
+    async function runTransitions() {
+        runningTransitions = true;
+        currentSectionElement.classList.add("links-disabled");
+        for (const transition of transitions) {
+            await transition();
+        }
+        transitions.length = 0;
+        runningTransitions = false;
+        currentSectionElement.classList.remove("links-disabled");
     }
     
-    function showPassage(passageName: string) {
+    async function showPassage(passageName: string) {
+        const oldCanGoBack = canGoBack();
         let passage = currentSection.passages && currentSection.passages[passageName];
-        const masterSection = story.sections[''];
+        const masterSection = story.sections[""];
         if (!passage && masterSection && masterSection.passages) passage = masterSection.passages[passageName];
         if (!passage) {
             throw `No passage named ${passageName} in the current section or master section`;
         }
-        setSeen(passageName);
+        state.setSeen(passageName);
+
+        const passages: Passage[] = [];
+        const runFns: (() => Promise<void>)[] = [];
+
         if (masterSection && masterSection.passages) {
-            const masterPassage = masterSection.passages[''];
+            const masterPassage = masterSection.passages[""];
             if (masterPassage) {
-                run(masterPassage);
-                ui.write(masterPassage.text || '', `[[]][]`);
+                passages.push(masterPassage);
+                runFns.push(() => run(masterPassage, "[[]][]"));
             }
         }
-        const master = currentSection.passages && currentSection.passages[''];
+
+        const master = currentSection.passages && currentSection.passages[""];
         if (master) {
-            run(master);
-            ui.write(master.text || '', `[[${get("_section")}]][]`);
+            passages.push(master);
+            runFns.push(() => run(master, `[[${get("_section")}]][]`));
+        }
+
+        passages.push(passage);
+        runFns.push(() => run(passage, `[[${get("_section")}]][${passageName}]`));
+
+        if (passages.some(p => p.clear)) {
+            clearScreen();
+            createSectionElement();
+        }
+
+        currentPassageElement = document.createElement("div");
+        currentPassageElement.classList.add("squiffy-output-passage");
+        currentPassageElement.setAttribute("data-passage", `${passageName}`);
+
+        currentSectionElement.appendChild(currentPassageElement);
+        currentBlockOutputElement = null;
+
+        for (const fn of runFns) {
+            await fn();
         }
-        run(passage);
-        ui.write(passage.text || '', `[[${get("_section")}]][${passageName}]`);
+
+        writeUndoLog();
         save();
+        const newCanGoBack = canGoBack();
+        if (newCanGoBack != oldCanGoBack) {
+            emitter.emit("canGoBackChanged", { canGoBack: newCanGoBack });
+        }
     }
     
-    function processAttributes(attributes: string[]) {
-        attributes.forEach(function (attribute) {
-            if (startsWith(attribute, '@replace ')) {
-                replaceLabel(attribute.substring(9));
-            }
-            else {
-                setAttribute(attribute);
-            }
-        });
+    async function processAttributes(attributes: string[]) {
+        for (const attribute of attributes) {
+            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 = '';
+        state.reset();
+        // TODO: This feels like the wrong way of triggering location.reload()
+        // - should be a separate setting to the scroll setting.
+        if (settings.scroll === "element" || settings.scroll === "none") {
+            outputElement.innerHTML = "";
             begin();
         }
         else {
@@ -331,106 +310,162 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
     }
     
     function save() {
-        set('_output', outputElement.innerHTML);
+        // TODO: Queue up all attribute changes and save them only when this is called
+        set("_output", outputElement.innerHTML);
     }
     
     function load() {
-        const output = get('_output');
-        if (!output) return false;
+        const runUiJs = () => {
+            if (story.uiJsIndex !== undefined) {
+                runJs(story.uiJsIndex, {
+                    registerAnimation: animation.registerAnimation.bind(animation),
+                });
+            }
+        };
+
+        state.load();
+        const output = get("_output");
+        if (!output) {
+            runUiJs();
+            return false;
+        }
+
         outputElement.innerHTML = output;
 
-        currentSectionElement = outputElement.querySelector('.squiffy-output-section:last-child');
-        currentBlockOutputElement = outputElement.querySelector('.squiffy-output-block:last-child');
+        setCurrentSectionElement();
+        setCurrentPassageElement();
+        currentBlockOutputElement = outputElement.querySelector(".squiffy-output-block:last-child");
 
-        currentSection = story.sections[get('_section')];
-        const transition = get('_transition');
-        if (transition) {
-            eval('(' + transition + ')()');
-        }
+        currentSection = story.sections[get("_section")];
+        runUiJs();
+        pluginManager.onLoad();
         return true;
     }
-    
-    function setSeen(sectionName: string) {
-        let seenSections = get('_seen_sections');
-        if (!seenSections) seenSections = [];
-        if (seenSections.indexOf(sectionName) == -1) {
-            seenSections.push(sectionName);
-            set('_seen_sections', seenSections);
-        }
-    }
-    
-    function seen(sectionName: string) {
-        const seenSections = get('_seen_sections');
-        if (!seenSections) return false;
-        return (seenSections.indexOf(sectionName) > -1);
-    }
 
     function newBlockOutputElement() {
-        currentBlockOutputElement = document.createElement('div');
-        currentBlockOutputElement.classList.add('squiffy-output-block');
-        currentSectionElement?.appendChild(currentBlockOutputElement);
+        currentBlockOutputElement = document.createElement("div");
+        currentBlockOutputElement.classList.add("squiffy-output-block");
+        (currentPassageElement || currentSectionElement)?.appendChild(currentBlockOutputElement);
     }
     
-    function newSection(sectionName: string | null) {
+    function newSection(sectionName?: string) {
         if (currentSectionElement) {
-            currentSectionElement.querySelectorAll('input').forEach(el => {
-                const attribute = el.getAttribute('data-attribute') || el.id;
+            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;
+                const attribute = el.getAttribute("data-attribute") || el.id;
                 if (attribute) set(attribute, el.innerHTML);
-                (el as HTMLElement).contentEditable = 'false';
+                (el as HTMLElement).contentEditable = "false";
             });
     
-            currentSectionElement.querySelectorAll('textarea').forEach(el => {
-                const attribute = el.getAttribute('data-attribute') || el.id;
+            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.classList.add('squiffy-output-section');
-        currentSectionElement.id = id;
-        if (sectionName) {
-            currentSectionElement.setAttribute('data-section', `${sectionName}`);
+
+        currentPassageElement = null;
+        createSectionElement(sectionName);
+        newBlockOutputElement();
+    }
+
+    function createSectionElement(sectionName?: string) {
+        currentSectionElement = document.createElement("div");
+        currentSectionElement.classList.add("squiffy-output-section");
+        currentSectionElement.setAttribute("data-section", sectionName ?? get("_section"));
+        if (!sectionName) {
+            currentSectionElement.setAttribute("data-clear", "true");
         }
         outputElement.appendChild(currentSectionElement);
-        newBlockOutputElement();
+    }
+
+    function getClearStack() {
+        return outputElement.querySelector<HTMLElement>(".squiffy-clear-stack");
+    }
+
+    function clearScreen() {
+        // Callers should call createSectionElement() after calling this function, so there's a place for new
+        // output to go. We don't call this automatically within this function, in case we're just about to create
+        // a new section anyway.
+        let clearStack = getClearStack();
+        if (!clearStack) {
+            clearStack = document.createElement("div");
+            clearStack.classList.add("squiffy-clear-stack");
+            clearStack.style.display = "none";
+            outputElement.prepend(clearStack);
+        }
+
+        const clearStackItem = document.createElement("div");
+        clearStack.appendChild(clearStackItem);
+
+        // Move everything in the outputElement (except the clearStack itself) into the new clearStackItem
+        for (const child of [...outputElement.children]) {
+            if (child !== clearStack) {
+                clearStackItem.appendChild(child);
+            }
+        }
+
+        // NOTE: If we offer an option to disable the "back" feature, all of the above can be replaced with:
+        //    outputElement.innerHTML = '';
+    }
+
+    function unClearScreen() {
+        const clearStack = getClearStack();
+        for (const child of [...outputElement.children]) {
+            if (child !== clearStack) {
+                child.remove();
+            }
+        }
+
+        const clearStackItem = clearStack.children[clearStack.children.length - 1];
+        for (const child of [...clearStackItem.children]) {
+            outputElement.appendChild(child);
+        }
+        clearStackItem.remove();
     }
     
     const ui = {
         write: (text: string, source: string) => {
-            if (!currentBlockOutputElement) return;
             scrollPosition = outputElement.scrollHeight;
-    
-            const div = document.createElement('div');
+
+            const html = ui.processText(text, false).trim();
+
+            // Previously, we skipped the rest of this if "html" came back as an empty string.
+            // But, we _do_ always want the block to be created, in the editor at least - as the
+            // author might be in the middle of an edit. When they start writing text for this
+            // source (section or passage), we want it to appear in the right place.
+            // TODO: What if this comes from a master section/passage though, and there's no
+            // text (just a script)? Or if there's conditional text that doesn't display?
+
+            if (!currentBlockOutputElement) {
+                newBlockOutputElement();
+            }
+
+            const div = document.createElement("div");
             if (source) {
-                div.setAttribute('data-source', source);
+                div.setAttribute("data-source", source);
             }
+
+            div.innerHTML = html;
+            pluginManager.onWrite(div);
             currentBlockOutputElement.appendChild(div);
-            div.innerHTML = ui.processText(text);
-    
             ui.scrollToEnd();
         },
         clearScreen: () => {
-            outputElement.innerHTML = '';
-            newSection(null);
+            clearScreen();
+            createSectionElement();
         },
         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' });
-                }
+            if (settings.scroll === "none") {
+                // do nothing
+            }
+            else if (settings.scroll === "element") {
+                outputElement.lastElementChild.scrollIntoView({ block: "end", inline: "nearest", behavior: "smooth" });
             }
             else {
                 let scrollTo = scrollPosition;
@@ -438,103 +473,139 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
                 if (scrollTo > currentScrollTop) {
                     const maxScrollTop = document.documentElement.scrollHeight - window.innerHeight;
                     if (scrollTo > maxScrollTop) scrollTo = maxScrollTop;
-                    window.scrollTo({ top: scrollTo, behavior: 'smooth' });
+                    window.scrollTo({ top: scrollTo, behavior: "smooth" });
                 }
             }
         },
-        processText: (text: string) => {
-            const data = {
-                fulltext: text
-            };
-            return textProcessor.process(text, data);
-        },
-        transition: function (f: any) {
-            set('_transition', f.toString());
-            f();
+        processText: (text: string, inline: boolean) => {
+            return textProcessor.process(text, inline);
         },
     };
 
-    function safeQuerySelector(name: string) {
-        return name.replace(/'/g, "\\'");
-    }
+    function update(newStory: Story) {
+        if (newStory.start != story.start) {
+            story = newStory;
+            state.reset();
+            outputElement.innerHTML = "";
+            go(story.start);
+            return;
+        }
+
+        updateStory(story, newStory, outputElement, ui, disableLink);
+
+        story = newStory;
 
-    function getSectionContent(section: string) {
-        return outputElement.querySelectorAll(`[data-source='[[${safeQuerySelector(section)}]]']`);
+        setCurrentSectionElement();
+        setCurrentPassageElement();
     }
 
-    function getPassageContent(section: string, passage: string) {
-        return outputElement.querySelectorAll(`[data-source='[[${safeQuerySelector(section)}]][${safeQuerySelector(passage)}]']`);
+    function setCurrentSectionElement() {
+        // Multiple .squiffy-output-section elements may be "last-child" if some have been moved to the clear-stack,
+        // so we want the very last one
+        const allSectionElements = outputElement.querySelectorAll<HTMLElement>(".squiffy-output-section:last-child");
+        currentSectionElement = allSectionElements[allSectionElements.length - 1];
+        const sectionName = currentSectionElement.getAttribute("data-section");
+        currentSection = story.sections[sectionName];
     }
 
-    function updateElementTextPreservingDisabledPassageLinks(element: Element, text: string) {
-        // Record which passage links are disabled
-        const disabledPassages = Array.from(element
-            .querySelectorAll("a.link-passage.disabled"))
-            .map((el: HTMLElement) => el.getAttribute("data-passage"));
+    function setCurrentPassageElement() {
+        currentPassageElement = currentSectionElement.querySelector(".squiffy-output-passage:last-child");
+    }
 
-        element.innerHTML = text;
+    function getHistoryCount() {
+        const clearStack = getClearStack();
+        const sectionPassageCount = outputElement.querySelectorAll(".squiffy-output-section").length
+            + outputElement.querySelectorAll(".squiffy-output-passage").length;
 
-        // Re-disable links that were disabled before the update
-        for (const passage of disabledPassages) {
-            const link = element.querySelector(`a.link-passage[data-passage="${passage}"]`);
-            if (link) disableLink(link);
+        if (!clearStack) {
+            return sectionPassageCount;
         }
+
+        return sectionPassageCount + clearStack.children.length;
     }
 
-    function update(newStory: Story) {
-        for (const existingSection of Object.keys(story.sections)) {
-            const elements = getSectionContent(existingSection);
-            if (elements.length) {
-                const newSection = newStory.sections[existingSection];
-                if (!newSection) {
-                    // section has been deleted
-                    for (const element of elements) {
-                        const parentOutputSection = element.closest('.squiffy-output-section');
-                        parentOutputSection.remove();
-                    }
+    function canGoBack() {
+        return getHistoryCount() > 1;
+    }
+
+    function goBack() {
+        if (!canGoBack()) {
+            return;
+        }
+
+        const clearStack = getClearStack();
+
+        if (currentPassageElement) {
+            const currentPassage = currentPassageElement.getAttribute("data-passage");
+            doUndo(currentPassageElement.getAttribute("data-undo"));
+            currentPassageElement.remove();
+
+            // If there's nothing left in the outputElement except for an empty section element that
+            // was created when the screen was cleared, pop the clear-stack.
+
+            let hasEmptySection = false;
+            let hasOtherElements = false;
+            for (const child of outputElement.children) {
+                if (child === clearStack) {
+                    continue;
                 }
-                else if (newSection.text && newSection.text != story.sections[existingSection].text) {
-                    // section has been updated
-                    for (const element of elements) {
-                        updateElementTextPreservingDisabledPassageLinks(element, ui.processText(newSection.text));
-                    }
+                if (child.getAttribute("data-clear") == "true" && child.children.length == 0) {
+                    hasEmptySection = true;
+                    continue;
                 }
+                hasOtherElements = true;
+                break;
             }
 
-            if (!story.sections[existingSection].passages) continue;
-
-            for (const existingPassage of Object.keys(story.sections[existingSection].passages)) {
-                const elements = getPassageContent(existingSection, existingPassage);
-                if (!elements.length) continue;
+            if (hasEmptySection && !hasOtherElements) {
+                unClearScreen();
+                setCurrentSectionElement();
+            }
 
-                const newPassage = newStory.sections[existingSection]?.passages && newStory.sections[existingSection]?.passages[existingPassage];
-                if (!newPassage) {
-                    // passage has been deleted
-                    for (const element of elements) {
-                        const parentOutputBlock = element.closest('.squiffy-output-block');
-                        parentOutputBlock.remove();
-                    }
+            for (const link of currentSectionElement.querySelectorAll("a.squiffy-link[data-passage]")) {
+                if (link.getAttribute("data-passage") == currentPassage) {
+                    enableLink(link);
                 }
-                else if (newPassage.text && newPassage.text != story.sections[existingSection].passages[existingPassage].text) {
-                    // passage has been updated
-                    for (const element of elements) {
-                        updateElementTextPreservingDisabledPassageLinks(element, ui.processText(newPassage.text));
-                    }
+            }
+
+            setCurrentPassageElement();
+        }
+        else {
+            doUndo(currentSectionElement.getAttribute("data-undo"));
+            currentSectionElement.remove();
+
+            // If there's nothing left in the outputElement except for the clear-stack, pop it
+            let hasOtherElements = false;
+            for (const child of [...outputElement.children]) {
+                if (child === clearStack) {
+                    continue;
                 }
+                hasOtherElements = true;
+                break;
+            }
+
+            if (!hasOtherElements) {
+                unClearScreen();
             }
+
+            setCurrentSectionElement();
+            setCurrentPassageElement();
         }
 
-        story = newStory;
-        currentSectionElement = outputElement.querySelector('.squiffy-output-section:last-child');
-        const sectionName = currentSectionElement.getAttribute('data-section');
-        currentSection = story.sections[sectionName];
+        if (!canGoBack()) {
+            emitter.emit("canGoBackChanged", { canGoBack: false });
+        }
     }
 
-    outputElement = options.element;
+    // We create a separate div inside the passed-in element. This allows us to clear the text output, but
+    // without affecting any overlays that may have been added to the container (for transitions).
+    const outputElementContainer = options.element;
+    const outputElement = document.createElement("div");
+    outputElementContainer.appendChild(outputElement);
     story = options.story;
 
-    settings = {
-        scroll: options.scroll || 'body',
+    const settings = {
+        scroll: options.scroll || "body",
         persist: (options.persist === undefined) ? true : options.persist,
         onSet: options.onSet || (() => {})
     };
@@ -544,26 +615,83 @@ export const init = (options: SquiffyInitOptions): SquiffyApi => {
         settings.persist = false;
     }
 
-    if (settings.scroll === 'element') {
-        outputElement.style.overflowY = 'auto';
+    if (settings.scroll === "element") {
+        outputElement.style.overflowY = "auto";
     }
 
-    outputElement.addEventListener('click', handleClick);
-    outputElement.addEventListener('keypress', function (event) {
+    outputElement.addEventListener("click", handleClick);
+    outputElement.addEventListener("keypress", async function (event) {
         if (event.key !== "Enter") return;
-        handleClick(event);
+        await handleClick(event);
     });
 
-    textProcessor = new TextProcessor(get, set, story, () => currentSection, seen, processAttributes);
-    
-    begin();
+    let undoLog: Record<string, any> = {};
+
+    const onSet = function(attribute: string, oldValue: any) {
+        if (attribute == "_output") return;
+        if (attribute in undoLog) return;
+        undoLog[attribute] = oldValue;
+    };
+
+    const writeUndoLog = function() {
+        (currentPassageElement ?? currentSectionElement).setAttribute("data-undo", JSON.stringify(undoLog));
+        undoLog = {};
+    };
+
+    const doUndo = function(undosJson: string | null) {
+        if (!undosJson) return;
+        const undos = JSON.parse(undosJson) as Record<string, any>;
+        if (!undos) return;
+        for (const attribute of Object.keys(undos)) {
+            state.setInternal(attribute, undos[attribute], false);
+        }
+    };
+
+    const state = new State(settings.persist, story.id || "", settings.onSet, emitter, onSet);
+    const get = state.get.bind(state);
+    const set = state.set.bind(state);
+
+    const textProcessor = new TextProcessor(story, state, () => currentSection);
+    const linkHandler = new LinkHandler();
+
+    const getSectionText = (sectionName: string) => {
+        if (sectionName in story.sections) {
+            return story.sections[sectionName].text || null;
+        }
+        return null;
+    };
+
+    const getPassageText = (name: string) => {
+        if (currentSection.passages && name in currentSection.passages) {
+            return currentSection.passages[name].text || null;
+        } else if ("passages" in story.sections[""] && story.sections[""].passages && name in story.sections[""].passages) {
+            return story.sections[""].passages![name].text || null;
+        }
+        return null;
+    };
+
+    const addTransition = (fn: () => Promise<void>) => {
+        transitions.push(fn);
+    };
+
+    const animation = new Animation();
+
+    const pluginManager = new PluginManager(outputElement, textProcessor, state, linkHandler,
+        getSectionText, getPassageText, ui.processText, addTransition, animation, emitter);
+    pluginManager.add(Plugins.ReplaceLabel());
+    pluginManager.add(Plugins.RotateSequencePlugin());
+    pluginManager.add(Plugins.RandomPlugin());
+    pluginManager.add(Plugins.LivePlugin());
+    pluginManager.add(Plugins.AnimatePlugin());
 
     return {
+        begin: begin,
         restart: restart,
         get: get,
         set: set,
         clickLink: handleLink,
         update: update,
+        goBack: goBack,
         on: (e, h) => emitter.on(e, h),
         off: (e, h) => emitter.off(e, h),
         once: (e, h) => emitter.once(e, h),