@swiftuijs/twill-runtime 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saiya and twill contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,23 @@
-# Temporary Holding Version
+# <img src="https://twill.evecalm.com/logo.png" alt="Twill hummingbird" align="right" width="40" height="40" /> Twill runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Optional, zero-dependency helpers for Twill, a TypeScript-based language with Swift-inspired syntax. Available in 0.2.0 for explicitly selected external cleanup helpers.
+
+The compiler defaults to self-contained inline code. External mode shares dynamic synchronous `defer` draining across modules:
+
+```sh
+pnpm add @swiftuijs/twill-runtime
+```
+
+```json
+{
+  "runtime": "external"
+}
+```
+
+Put that option in `twill.config.json`, or use `twill({ runtime: 'external' })` in a build adapter. Install the runtime as a production dependency of applications and published libraries whose compiled code imports it. Inline-only output needs no runtime installation.
+
+The compiler emits a hygienic named import from `@swiftuijs/twill-runtime/helpers/v1`. That subpath is a versioned compiler/helper ABI; applications normally use Twill syntax instead of calling helpers directly. ABI v1 preserves reverse cleanup order, runs every callback after failures and rethrows the last cleanup failure, including `undefined`. It is synchronous and ignores callback return values.
+
+Single directly registered cleanup retains its native fast path. Explicit async or mixed cleanup stays inline to preserve scheduling. Guards, arrows, enum factories/matching and ordinary component output gain no runtime import. Only modules needing the helper import it; exports have no side effects, and bundlers can tree-shake unused helpers. There is no compiler, TypeScript engine, UI framework or Node-only API in the runtime.
+
+Sharing reduces repeated uncompressed code but retains cleanup callback and array allocation. It is not a general speedup promise; gzip may already compress repeated inline code. See [performance](https://twill.evecalm.com/performance), [Twill documentation](https://twill.evecalm.com/) and [RFC 0032](https://github.com/swiftuijs/twill/blob/main/docs/rfcs/0032-optional-runtime-helpers.md). Twill's sibling UI project is [SwiftUI.js](https://swiftuijs.evecalm.com/).

package/dist/helpers/v1.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compiler helper ABI v1. Synchronous cleanup uses native finally replacement
+ * semantics: every reached cleanup runs, and the last cleanup failure wins.
+ * Return values (including promises) are deliberately not awaited.
+ * @param {Array<() => unknown> | undefined} stack
+ * @returns {void}
+ */
+export function runDefers(stack: Array<() => unknown> | undefined): void;
+//# sourceMappingURL=v1.d.ts.map

package/dist/helpers/v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.d.ts","sourceRoot":"","sources":["../../src/helpers/v1.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,iCAHW,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS,GAC9B,IAAI,CAiBhB"}

package/dist/helpers/v1.js

@@ -0,0 +1,25 @@
+/**
+ * Compiler helper ABI v1. Synchronous cleanup uses native finally replacement
+ * semantics: every reached cleanup runs, and the last cleanup failure wins.
+ * Return values (including promises) are deliberately not awaited.
+ * @param {Array<() => unknown> | undefined} stack
+ * @returns {void}
+ */
+export function runDefers(stack) {
+    let failed = false, failure;
+    while (stack?.length) {
+        const cleanup = stack.pop();
+        if (cleanup) {
+            try {
+                cleanup();
+            }
+            catch (error) {
+                failed = true;
+                failure = error;
+            }
+        }
+    }
+    if (failed)
+        throw failure;
+}
+//# sourceMappingURL=v1.js.map

package/dist/helpers/v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.js","sourceRoot":"","sources":["../../src/helpers/v1.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,KAAK;IAC7B,IAAI,MAAM,GAAG,KAAK,EAChB,OAAO,CAAC;IACV,OAAO,KAAK,EAAE,MAAM,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC5B,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,OAAO,EAAE,CAAC;YACZ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,GAAG,IAAI,CAAC;gBACd,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,MAAM;QAAE,MAAM,OAAO,CAAC;AAC5B,CAAC"}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@swiftuijs/twill-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Optional, zero-dependency runtime helpers for compiled Twill programs.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swiftuijs/twill.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://twill.evecalm.com/",
+  "bugs": {
+    "url": "https://github.com/swiftuijs/twill/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./helpers/v1": {
+      "types": "./dist/helpers/v1.d.ts",
+      "import": "./dist/helpers/v1.js",
+      "default": "./dist/helpers/v1.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "^26.6.4",
+    "vitest": "^5.0.3",
+    "@vitest/coverage-v8": "^5.0.3"
+  },
+  "author": {
+    "name": "forth.ink",
+    "url": "https://forth.ink"
+  },
+  "keywords": [
+    "twill",
+    "runtime",
+    "typescript",
+    "defer",
+    "cleanup"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:unit": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:package": "node tests/consumer.mjs"
+  }
 }

package/src/helpers/v1.js

@@ -0,0 +1,23 @@
+/**
+ * Compiler helper ABI v1. Synchronous cleanup uses native finally replacement
+ * semantics: every reached cleanup runs, and the last cleanup failure wins.
+ * Return values (including promises) are deliberately not awaited.
+ * @param {Array<() => unknown> | undefined} stack
+ * @returns {void}
+ */
+export function runDefers(stack) {
+  let failed = false,
+    failure;
+  while (stack?.length) {
+    const cleanup = stack.pop();
+    if (cleanup) {
+      try {
+        cleanup();
+      } catch (error) {
+        failed = true;
+        failure = error;
+      }
+    }
+  }
+  if (failed) throw failure;
+}