RELEASE: v2.35.0

## Changelog:

* Fixed issues with nested `<svg>` tags.
* Fixed issues with comments within macro arguments.
* Added the `<<done>>` macro.  **NOTE:** This is compatible with Chapel's macro of the same name, so if you're using that you can, and should, remove it.
* Updated `<<numberbox>>` to more reliably show a numeric keypad on mobile devices.
* Updates to locale files:
	* Added `ar-EG.js` – العربية (مصر).
	* Added `it-IT.js` – Italiano (Italy).
	* Updated `de.js` – Deutsch.
* Various documentation updates.
* Various internal improvements.

Author: tmedwards

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2013-2020, Thomas Michael Edwards <thomasmedwards@gmail.com>.
+Copyright (c) 2013-2021, Thomas Michael Edwards <thomasmedwards@gmail.com>.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

dist/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2013-2020, Thomas Michael Edwards <thomasmedwards@gmail.com>.
+Copyright (c) 2013-2021, Thomas Michael Edwards <thomasmedwards@gmail.com>.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

dist/format.js

@@ -10,7 +10,7 @@
 Returns a deep copy of the given value.
 
 <p role="note"><b>Note:</b>
-Only the primitives, generic objects, some JavaScript natives (specifically: <code>Array</code>, <code>Date</code>, <code>Map</code>, <code>RegExp</code>, and <code>Set</code>), and DOM node objects are supported by default.  Unsupported object types, either native or custom, will need to implement <code>.clone()</code> method to be properly supported by the <code>cone()</code> function—when called on such an object, it will simply defer to the local method; see the <a href="#guide-tips-non-generic-object-types"><em>Non-generic object types (a.k.a. classes)</em> guide</a> for more information.
+Only the primitives, generic objects, some JavaScript natives (specifically: <code>Array</code>, <code>Date</code>, <code>Map</code>, <code>RegExp</code>, and <code>Set</code>), and DOM node objects are supported by default.  Unsupported object types, either native or custom, will need to implement <code>.clone()</code> method to be properly supported by the <code>clone()</code> function—when called on such an object, it will simply defer to the local method; see the <a href="#guide-tips-non-generic-object-types"><em>Non-generic object types (a.k.a. classes)</em> guide</a> for more information.
 </p>
 
 #### History:

docs/core/functions.md

@@ -1818,7 +1818,7 @@ The versions that forward to a specific passage are largely unnecessary, as you
 
 <span id="macros-dom-warning"></span>
 <p role="note" class="warning"><b>Warning:</b>
-All DOM macros require the elements to be manipulated to be on the page.  As a consequence, you cannot use them directly within a passage to modify elements within said passage, since the elements they are targeting are still rendering, thus not yet on the page.  You must, generally, use them with a interactive macro—e.g., <a href="#macros-macro-link"><code>&lt;&lt;link&gt;&gt;</code> macro</a>—or within the <a href="#special-passage-passagedone"><code>PassageDone</code> special passage</a>.  Elements that are already part of the page, on the other hand, present no issues.
+All DOM macros require the elements to be manipulated to be on the page.  As a consequence, you cannot use them directly within a passage to modify elements within said passage, since the elements they are targeting are still rendering, thus not yet on the page.  You must, generally, use them with an interactive macro—e.g., <a href="#macros-macro-link"><code>&lt;&lt;link&gt;&gt;</code> macro</a>—the <a href="#macros-macro-done"><code>&lt;&lt;done&gt;&gt;</code> macro</a>, or within the <a href="#special-passage-passagedone"><code>PassageDone</code> special passage</a>.  Elements that are already part of the page, on the other hand, present no issues.
 </p>
 
 <!-- *********************************************************************** -->
@@ -2728,6 +2728,32 @@ This macro has been deprecated and should no longer be used.  See the <a href="#
 
 <!-- *********************************************************************** -->
 
+### `<<done>> … <</done>>` {#macros-macro-done}
+
+Silently executes its contents when the incoming passage is done rendering and has been added to the page.  Generally, only really useful for running code that needs to manipulate elements from the incoming passage, since you must wait until they've been added to the page.
+
+<p role="note" class="tip"><b>Tip:</b>
+If you need to run the same code on multiple passages, consider using the <a href="#special-passage-passagedone"><code>PassageDone</code> special passage</a> or, for a JavaScript/TwineScript solution, a <a href="#events-navigation-event-passagedisplay"><code>:passagedisplay</code> event</a> instead.  They serve the same basic purpose as the <code>&lt;&lt;done&gt;&gt;</code> macro, but are run each time passage navigation occurs.
+</p>
+
+#### History:
+
+* `v2.35.0`: Introduced.
+
+#### Arguments: *none*
+
+#### Examples:
+
+```
+@@#spy;@@
+
+<<done>>
+	<<replace "#spy">>I spy with my little eye, a crab rangoon.<</replace>>
+<</done>>
+```
+
+<!-- *********************************************************************** -->
+
 ### `<<goto passageName>>`<br>`<<goto linkMarkup>>` {#macros-macro-goto}
 
 Immediately forwards the player to the passage with the given name.  May be called either with the passage name or with a link markup.
@@ -2736,6 +2762,10 @@ Immediately forwards the player to the passage with the given name.  May be call
 In most cases, you will not need to use <code>&lt;&lt;goto&gt;&gt;</code> as there are often better and easier ways to forward the player.  For example, a common use of <a href="#macros-macro-link"><code>&lt;&lt;link&gt;&gt;</code></a> is to perform various actions before forwarding the player to another passage.  In that case, unless you need to dynamically determine the destination passage within the <code>&lt;&lt;link&gt;&gt;</code> body, <code>&lt;&lt;goto&gt;&gt;</code> is unnecessary as <code>&lt;&lt;link&gt;&gt;</code> already includes the ability to forward the player.
 </p>
 
+<p role="note" class="warning"><b>Warning:</b>
+Using <code>&lt;&lt;goto&gt;&gt;</code> to automatically forward players from one passage to another with no input from them will both create junk moments within the story history and make it extremely difficult for players to navigate the history.  It is <strong><em>strongly</em></strong> recommended that you look into other methods to achieve your goals instead—e.g., <a href="#config-api-property-navigation-override"><code>Config.navigation.override</code></a>.
+</p>
+
 <p role="note" class="warning"><b>Warning:</b>
 <code>&lt;&lt;goto&gt;&gt;</code> <strong><em>does not</em></strong> terminate passage rendering in the passage where it was encountered, so care must be taken to ensure that no unwanted state modifications occur after its call.
 </p>

docs/core/macros.md

@@ -89,6 +89,15 @@ Any supported object type may itself contain any supported primitive or object t
 Neither ES5 property attributes—which includes getters/setters—nor symbol properties are directly supported in generic objects stored within story variables.  If you need such features, then you'll need to use a non-generic object (a.k.a. a class).
 </p>
 
+<div role="note" class="warning"><b>Warning:</b>
+<p>Functions, including non-instance methods, are not directly supported within story variables because of a few issues.</p>
+<ol>
+	<li>A function's scope <strong><em>cannot</em></strong> be restored.  Thus, if your function depends upon its scope, then it will not work properly when revived from sessions or saves.</li>
+	<li>Function behavior is immutable.  Thus, storing them within story variables is generally wasteful.</li>
+</ol>
+<p>Methods of class instances are not affected by either issue, as they're never actually stored within story variables, being on their classes' prototypes.</p>
+</div>
+
 Unsupported object types, either native or custom, can be made compatible by implementing `.clone()` and `.toJSON()` methods for them—see the [*Non-generic object types (a.k.a. classes)* guide](#guide-tips-non-generic-object-types) for more information.
 
 

docs/core/twinescript.md

@@ -86,7 +86,7 @@ Running that, you'll see `$x is 0` and `$y is 1`.  Now, load the saved story fro
 
 ## Refreshing and Restarting {#guide-state-sessions-and-saving-refreshing-and-restarting}
 
-Whenever your story is first started or, *for any reason*, restarted—e.g., the browser window/tab was refreshed/reloaded—it undergoes its startup sequence.  Several things occur **each and every time startup happens**, regardless of whether or not a playthrough session will be restored, an autosave loaded, a regular save loaded, or the starting passage run.  First, the CSS, JavaScript, and Widget sections are processed.  Next, the `StoryInit` special passage is processed.  Finally, one of three things happen (in order): the existing playthrough session is restored, if it exists, else the autosave is loaded, if it exists and is configured to do so, else the starting passage is run.
+Whenever your story is first started or, *for any reason*, restarted—e.g., the browser window/tab was refreshed/reloaded—it undergoes its startup sequence.  Several things occur **each and every time startup happens**, regardless of whether or not a playthrough session will be restored, an autosave loaded, or the starting passage run.  First, the CSS, JavaScript, and Widget sections are processed.  Next, the `StoryInit` special passage is processed.  Finally, one of three things happen (in order): the existing playthrough session is restored, if it exists, else the autosave is loaded, if it exists and is configured to do so, else the starting passage is run.
 
 Some users have the false impression that `StoryInit` is not run when the story is restarted when the playthrough session is restored or autosave is loaded.  Code like `<<set $y to 1>>` *seems* to have no effect because the startup state is replaced by the of the incoming state, **but they are still executed by the engine**.  You can see this effect by changing data *outside* the state.  For example, let's return to the example above and change it again:
 

docs/guides/guide-state-sessions-and-saving.md

@@ -56,7 +56,7 @@ To enable test mode from the story editor/map screen while starting at a specifi
 To enable test mode while starting at a specific passage, right-click on a passage and select the *Test Play From Here* context menu item.
 
 <p role="note"><b>Note:</b>
-Unfortunately, due to limitations in the current release of Twine&nbsp;1, the <em>Build</em> menu's <em>Test Play</em> menu item is not able to trigger test mode.  You may, however, simply use the <em>Test Play From Here</em> context menu item on the `Start` passage to achieve the same result.
+Unfortunately, due to limitations in the current release of Twine&nbsp;1, the <em>Build</em> menu's <em>Test Play</em> menu item is not able to trigger test mode.  You may, however, simply use the <em>Test Play From Here</em> context menu item on the <code>Start</code> passage to achieve the same result.
 </p>
 
 ### Manually

docs/guides/guide-test-mode.md

@@ -98,6 +98,7 @@
 	* [`<<removeplaylist>>`](#macros-macro-removeplaylist)
 	* [`<<waitforaudio>>`](#macros-macro-waitforaudio)
 * [Miscellaneous Macros](#macros-miscellaneous)
+	* [`<<done>>`](#macros-macro-done)
 	* [`<<goto>>`](#macros-macro-goto)
 	* [`<<repeat>>`](#macros-macro-repeat)
 		* [`<<stop>>`](#macros-macro-stop)

docs/table-of-contents.md

@@ -8,13 +8,15 @@ For the template that should be used as the basis of localizations, see the `l10
 
 ## Contributors
 
-* 简体中文 (`chs.js`) – Liyro Pen.
-* Deutsch (`de.js`) – Phil Strahl.
-* Español (Castellano) (`es-ES.js`) – Gerardo Galán.
-* Español (*UNKNOWN*) (`es-UNKNOWN.js`) – Raúl Castellano.
-* Français (`fr.js`) – Marc Cornette, Pierre Kessler.
-* Polski (`pl.js`) – ciupac.
-* Português (Brazil) (`pt-BR.js`) – Janos Biro.
-* Português (Portugal) (`pt-PT.js`) – Magma.
-* Ру́сский (`ru.js`) – Konstantin Kitmanov.
-* Türkçe (`tr.js`) – Guena Varia.
+* `ar-EG.js` – العربية (مصر), by: Mustafa Rawi.
+* `chs.js` – 简体中文, by: Liyro Pen.
+* `de.js` – Deutsch, by: Phil Strahl, Grausicht.
+* `es-ES.js` – Español (Castellano), by: Gerardo Galán.
+* `es-UNKNOWN.js` – Español (*UNKNOWN*), by: Raúl Castellano.
+* `fr.js` – Français, by: Marc Cornette, Pierre Kessler.
+* `it-IT.js` – Italiano (Italy), by: Karime Chehbouni.
+* `pl.js` – Polski, by: ciupac.
+* `pt-BR.js` – Português (Brazil), by: Janos Biro.
+* `pt-PT.js` – Português (Portugal), by: Magma.
+* `ru.js` – Ру́сский, by: Konstantin Kitmanov.
+* `tr.js` – Türkçe, by: Guena Varia.

locale/README.md

@@ -0,0 +1,100 @@
+/***********************************************************************************************************************
+
+	ar-EG.js – العربية (مصر)
+	Localization by: Mustafa Rawi
+
+	Copyright © 2021 Thomas Michael Edwards <thomasmedwards@gmail.com>. All rights reserved.
+	Use of this source code is governed by a BSD 2-clause "Simplified" License, which may be found in the LICENSE file.
+
+	For more information about the guidelines used to create this localization, see:
+		http://www.motoslave.net/sugarcube/2/docs/#guide-localization
+
+***********************************************************************************************************************/
+
+(function () {
+	/* General. */
+	l10nStrings.identity = 'لعبة';
+	l10nStrings.aborting = 'جاري الإلغاء';
+	l10nStrings.cancel   = 'إلغاء';
+	l10nStrings.close    = 'إغلاق';
+	l10nStrings.ok       = 'موافق';
+
+	/* Errors. */
+	l10nStrings.errorTitle              = 'خطأ';
+	l10nStrings.errorToggle             = 'تبديل عرض واجهة الأخطاء';
+	l10nStrings.errorNonexistentPassage = 'القطعة "{passage}" غير موجودة'; // NOTE: `passage` is supplied locally
+	l10nStrings.errorSaveMissingData    = 'خاصية الحفظ لم تجد بعض البيانات. إما أن الملف المحمل ليس ملفاً خاصة بالحفظ أو أن الملف متضرر';
+	l10nStrings.errorSaveIdMismatch     = 'ملف الحفظ من {identity} خاطئة';
+
+	/* Warnings. */
+	l10nStrings._warningIntroLacking  = 'متصفحك إما يفتقر إلى أو تم تعطيل ';
+	l10nStrings._warningOutroDegraded = ', لذا فهذه {identity} تعمل في وضع محدود. يمكنك المتابعة إلا أن بعض أجزاءها قد لا تعمل بشكل صحيح.';
+	l10nStrings.warningNoWebStorage   = '{_warningIntroLacking} واجهة برمجة تطبيقات ويب للحفظ{_warningOutroDegraded}';
+	l10nStrings.warningDegraded       = '{_warningIntroLacking} بعض الخصائص المطلوبة في {identity}{_warningOutroDegraded}';
+
+	/* Debug bar. */
+	l10nStrings.debugBarToggle      = 'تبديل عرض شريط استكشاف الأخطاء';
+	l10nStrings.debugBarNoWatches   = '\u2014 لم يتم تحديد مراقبين \u2014';
+	l10nStrings.debugBarAddWatch    = 'إضافة مراقب';
+	l10nStrings.debugBarDeleteWatch = 'حذف مراقب';
+	l10nStrings.debugBarWatchAll    = 'مراقبة الكل';
+	l10nStrings.debugBarWatchNone   = 'حذف الكل';
+	l10nStrings.debugBarLabelAdd    = 'إضافة';
+	l10nStrings.debugBarLabelWatch  = 'مراقبة';
+	l10nStrings.debugBarLabelTurn   = 'الدور'; // (noun) chance to act (in a game), moment, period
+	l10nStrings.debugBarLabelViews  = 'الواجهات';
+	l10nStrings.debugBarViewsToggle = 'تبديل عرض واجهات استكشاف الأخطاء';
+	l10nStrings.debugBarWatchToggle = 'تبديل عرض لوحة المراقبة';
+
+	/* UI bar. */
+	l10nStrings.uiBarToggle   = 'تبديل عرض شريط الواجهة';
+	l10nStrings.uiBarBackward = 'تراجع عبر تاريخ {identity}';
+	l10nStrings.uiBarForward  = 'تقدم عبر تاريخ  {identity}';
+	l10nStrings.uiBarJumpto   = 'قفز إلى نقطة معينة في تاريخ {identity}';
+
+	/* Jump To. */
+	l10nStrings.jumptoTitle       = 'قفز إلى';
+	l10nStrings.jumptoTurn        = 'دور'; // (noun) chance to act (in a game), moment, period
+	l10nStrings.jumptoUnavailable = 'لا توجد نقاط قفز متاحة حالياً\u2026';
+
+	/* Saves. */
+	l10nStrings.savesTitle       = 'الحفظ';
+	l10nStrings.savesDisallowed  = 'تم تعطيل خاصية الحفظ في هذه القطعة.';
+	l10nStrings.savesIncapable   = '{_warningIntroLacking} يفتقر إلى إمكانيات مطلوبة لدعم عملية الحفظ، لذا تم تعطيلها في هذه الجلسة.';
+	l10nStrings.savesLabelAuto   = 'الحفظ التلقائي';
+	l10nStrings.savesLabelDelete = 'حذف';
+	l10nStrings.savesLabelExport = 'حفظ إلى جهازك\u2026';
+	l10nStrings.savesLabelImport = 'تحميل من جهازك\u2026';
+	l10nStrings.savesLabelLoad   = 'تحميل';
+	l10nStrings.savesLabelClear  = 'حذف الكل';
+	l10nStrings.savesLabelSave   = 'حفظ';
+	l10nStrings.savesLabelSlot   = 'حاوية';
+	l10nStrings.savesUnavailable = 'لم يمكن العثور على حاويات حفظ\u2026';
+	l10nStrings.savesUnknownDate = 'غير معروف';
+
+	/* Settings. */
+	l10nStrings.settingsTitle = 'الإعدادات';
+	l10nStrings.settingsOff   = 'معطل';
+	l10nStrings.settingsOn    = 'مفعل';
+	l10nStrings.settingsReset = 'استرداد الافتراضيات';
+
+	/* Restart. */
+	l10nStrings.restartTitle  = 'إعادة تشغيل';
+	l10nStrings.restartPrompt = 'هل ترغب حقاً في إعادة التشغيل من البداية؟ ستفقد أي تقدم حققته ولم تحفظه.';
+
+	/* Share. */
+	l10nStrings.shareTitle = 'مشاركة';
+
+	/* Alert. */
+	l10nStrings.alertTitle = 'تنبيه';
+
+	/* Autoload. */
+	l10nStrings.autoloadTitle  = 'تحميل تلقائي';
+	l10nStrings.autoloadCancel = 'الذهاب للبداية';
+	l10nStrings.autoloadOk     = 'تحميل من الحفظ التلقائي';
+	l10nStrings.autoloadPrompt = 'تم العثور على حفظ تلقائي. هل ترغب في تحميله أم تريد الذهاب للبداية؟';
+
+	/* Macros. */
+	l10nStrings.macroBackText   = 'تراجع'; // (verb) rewind, revert
+	l10nStrings.macroReturnText = 'عودة'; // (verb) go/send back
+})();

locale/ar-EG.js

@@ -11,6 +11,7 @@
 		http://www.motoslave.net/sugarcube/2/docs/#guide-localization
 
 ***********************************************************************************************************************/
+
 (function () {
 	/* General. */
 	l10nStrings.identity = '游戏';

locale/chs.js

@@ -2,15 +2,16 @@
 
 	de.js – Deutsch
 
-	Localization by: Phil Strahl <phil@pixelprophecy.com>.
+	Localization by: Phil Strahl <phil@pixelprophecy.com>, Grausicht.
 
-	Copyright © 2017–2018 Thomas Michael Edwards <thomasmedwards@gmail.com>. All rights reserved.
+	Copyright © 2017–2021 Thomas Michael Edwards <thomasmedwards@gmail.com>. All rights reserved.
 	Use of this source code is governed by a BSD 2-clause "Simplified" License, which may be found in the LICENSE file.
 
 	For more information about the guidelines used to create this localization, see:
 		http://www.motoslave.net/sugarcube/2/docs/#guide-localization
 
 ***********************************************************************************************************************/
+
 (function () {
 	/* General. */
 	l10nStrings.identity = 'spiel';
@@ -86,10 +87,10 @@
 	l10nStrings.shareTitle = 'Teilen';
 
 	/* Autoload. */
-	l10nStrings.autoloadTitle  = 'Autmatisches Laden';
+	l10nStrings.autoloadTitle  = 'Automatisches Laden';
 	l10nStrings.autoloadCancel = 'Gehe zum Start';
 	l10nStrings.autoloadOk     = 'Auto-Speicherstand laden';
-	l10nStrings.autoloadPrompt = 'Ein Auto-Spiecherstand existiert bereits. Laden oder zurück an den Start?';
+	l10nStrings.autoloadPrompt = 'Ein Auto-Speicherstand existiert bereits. Laden oder zurück an den Start?';
 
 	/* Macros. */
 	l10nStrings.macroBackText   = 'Zurück';

locale/de.js

@@ -11,6 +11,7 @@
 		http://www.motoslave.net/sugarcube/2/docs/#guide-localization
 
 ***********************************************************************************************************************/
+
 (function () {
 	/* General. */
 	l10nStrings.identity = 'juego';

locale/es-ES.js

@@ -11,6 +11,7 @@
 		http://www.motoslave.net/sugarcube/2/docs/#guide-localization
 
 ***********************************************************************************************************************/
+
 (function () {
 	/* General. */
 	l10nStrings.identity = 'juego';

locale/es-UNKNOWN.js

@@ -11,6 +11,7 @@
 		http://www.motoslave.net/sugarcube/2/docs/#guide-localization
 
 ***********************************************************************************************************************/
+
 (function () {
 	/* General. */
 	l10nStrings.identity = 'aventure';