If you just want to enjoy TFHoP2 and DO NOT CARE about the technical details of how I got it working, head to the Steam guide on how to patch it below.

Steam guide: Fix Broken Web Content [Windows] [2026]

Intro

Picture this: there’s a puzzle game you really like. You have over 100 hours of playtime, even though the story takes only 10.5 hours to beat and the whole game takes about 22.5 hours to complete. You like it so much that you spend hours playing co-op with friends and competing for the fastest times in Challenge Mode.

That’s me with Portal 2.

Then you find out there’s an interactive e-book covering the entire development process, with all kinds of interesting stuff inside. It costs only €0.63. Of course you buy it.

…and quickly realize that, unlike the main game, which still receives security patches and bug fixes, the e-book isn’t really maintained. Though Adobe AIR is still kinda maintained by Wipro, the e-book installs a version from 2011.

And that wouldn’t even be a huge problem if the book worked properly. Let’s take a look at the various broken things I found.

And I don’t want to read a book with the constant fear that the next page will be broken :(

Why broken?

Most of the e-book’s broken features depended on external web services.

For music, bundling the songs with the e-book would have made licensing more difficult.

And for polls, using the web was basically the only option.

Unfortunately, services get refactored over time, breaking legacy endpoints that nobody cares about. Sometimes an owner forgets to renew a domain, so someone else buys it and fills it with something completely unrelated. Other times, the service simply breaks through lack of maintenance. This e-book contains examples of all three.

The panorama viewers are the exception. Their assets are stored locally, but they fail on newer versions of Windows despite using the same version of Adobe AIR. I’ll come back to those later.

Now let’s figure out exactly what’s broken, starting by inspecting the e-book’s files:

SWF files. As established earlier, the e-book uses Adobe Flash, so I needed to decompile them somehow. Having no experience with this at all, I turned to Google:

It sent me to the finest of software, JPEXS Free Flash Decompiler:

I searched the main SWF file and the five additional SWFs to compile a list of every online dependency. Here’s how I recovered each one:

Videos

The application uses YouTube’s ancient ActionScript 3 Player API, which was discontinued more than a decade ago.

The original API worked by loading a player SWF executable from YouTube. The e-book then controlled that SWF using methods such as loadVideoById(), playVideo(), and pauseVideo() while listening for playback events.

Since I can’t write Flash stuff, I used GPT-5.6-Sol to help write a replacement ActionScript player and compiled it into a SWF. It recreates the part of YouTube’s API that the e-book expects, but instead of using YouTube, it translates those calls into playback of local MP4 files.

But YouTube does not directly serve MP4 files, and some of the videos are no longer accessible. The e-book contains nine YouTube videos:

• Chapter 3, page 10: https://www.youtube.com/watch?v=j7LFbmTHY78
• Chapter 3, page 10: https://www.youtube.com/watch?v=CkoMbxHQmuM
• Chapter 6, page 4: https://www.youtube.com/watch?v=DnMdBnLWvpg
• Chapter 7, page 3: https://www.youtube.com/watch?v=0Zzfdlxjx4Y
• Chapter 7, page 5: https://www.youtube.com/watch?v=JpFNKyeckZc
• Chapter 11, page 2: https://www.youtube.com/watch?v=VLqw5JW8OLY
• Chapter 12, page 2: https://www.youtube.com/watch?v=GOMI0BxB0yA
• Chapter 12, page 3: https://www.youtube.com/watch?v=Im6yRpQrsaY
• Chapter 12, page 3: https://www.youtube.com/watch?v=pZaY1jV96jI

I used yt-dlp to download each one. Only two needed extra work:

• One was age-restricted, but I was able to download it by passing my cookies to yt-dlp.
• The other was private. After pasting its video ID into Google and doing some digging, I found its title: “She’s Too Good For Everyone.” Searching YouTube for that title led me to a reupload.

3D and games

The e-book contains three 3D visualizations and one interactive minigame, all four of which relied on dead URLs:

• Chapter 3, page 7 — Portal minigame: http://www.thefinalhoursofportal2.com/TFHoP2_assets/howto/diagram.html
• Chapter 7, page 8 — Wheatley 3D: http://www.thefinalhoursofportal2.com/TFHoP2_assets/interactive/index.html
• Chapter 9, page 1 — The Odd Couple 3D: http://www.thefinalhoursofportal2.com/TFHoP2_assets/oddcouple/
• Chapter 13, page 1 — Companion Cube 3D: http://www.thefinalhoursofportal2.com/TFHoP2_assets/companioncube/

At first I was sad. None of those URLs were archived, and the domain had been registered by someone else hosting slop :(

After about an hour of searching, I still couldn’t find archived copies. Recreating them seemed like my best option, so I started with the Portal minigame and got pretty close:

I think it’s pretty good, especially since I was working from only a 10-second video. At that point, I was satisfied.

At one point I discovered that there was a native iOS version of the e-book. Not expecting anything in particular, I decided to try it out.

After digging around, I found its IPA file inside a 173.7 GB Archive.org collection titled “Missing IPAs.” Its description was simply “Some stuff,” and it contained more than 10,000 IPAs.

Here is a direct download link for anyone who might need it:

https://archive.org/download/missing-ipas/com.joezeffdesign.finalhoursofportaltwo%20-%20Geoff.Keighley.Presents.The.Final.Hours.of.Portal.2.v1.7.iPad-Lz0PDA.ipa

Since the App Store launched with iPhone OS 2, downloaded apps have been distributed in encrypted form. An authorized device decrypts an app’s executable pages as they are loaded into memory. Because those pages must exist in decrypted form for the processor to execute them, they can be extracted from memory on a jailbroken device.

Luckily, someone had done exactly that with the IPA I found, meaning I could install it on my iPad without owning the original app.

And I discovered something interesting:

All four visualizations worked!

That is because unlike the PC version, the mobile app bundles all of the visualizations’ code and assets locally.

I renamed the .ipa file to .zip and found the assets inside. Because they were standard HTML files, I could simply copy them to my PC!

Music

The e-book loads eight songs from mzstatic.com domains.

Seven come from a playlist in chapter 5:

• East Bound and Down: http://a5.mzstatic.com/us/r1000/050/Music/89/1f/6d/mzm.hmsvmlsc.aac.p.m4a
• Queen of Denmark: http://a4.mzstatic.com/us/r1000/013/Music/9f/da/c0/mzi.dviddoso.aac.p.m4a
• Polaroids and Red Wine: http://a1.mzstatic.com/us/r30/Music/2c/81/ca/mzi.wxxicnqc.aac.p.m4a
• My Violent Heart (Pirate Robot Midget): http://a1.mzstatic.com/us/r1000/013/Music/90/2a/b7/mzm.ojhmmnlb.aac.p.m4a
• Bang Bang Bang: http://a5.mzstatic.com/us/r1000/022/Music/24/12/e8/mzi.bukbidcp.aac.p.m4a
• Bridges and Balloons: http://a4.mzstatic.com/us/r1000/026/Music/e4/6f/19/mzm.hcizchvw.aac.p.m4a
• Bilar: http://a2.mzstatic.com/us/r1000/036/Music/d7/5e/9b/mzi.eyucogyw.aac.p.m4a

The eighth appears in chapter 3, page 10 — Still Alive: http://a5.mzstatic.com/us/r30/Music/3e/c7/48/mzm.cxiybvxa.aac.p.m4a

The base domain, mzstatic.com, redirects to apple.com, and the e-book notes that the audio samples are provided by iTunes.

I found all eight songs on music.apple.com. The web version of Apple Music also serves previews without requiring authentication.

I found each song’s ID by copying its Apple Music link and taking the final number:

https://music.apple.com/us/song/still-alive/270749989

I then used the API to retrieve its 30-second preview:

I repeated the process to download a preview of every song.

Polls

These are the polls’ original URLs:

• Chapter 1, page 5 — Poll 1: http://www.gameslice.com/p2polls/poll1.php5
• Chapter 5, page 6 — Poll 6: http://www.gameslice.com/p2polls/poll6.php5
• Chapter 9, page 6 — Poll 3: http://www.gameslice.com/p2polls/poll3.php5
• Chapter 12, page 6 — Poll 4: http://ww.gameslice.com/p2polls/poll4.php5
• Chapter 13, page 3 — Poll 5: http://www.gameslice.com/p2polls/poll5.php5
• Chapter 14, page 5 — Poll 20: http://geoffkeighley.com/p2polls/poll.php5?id=20
• Chapter 14, page 8 — Poll 21: http://geoffkeighley.com/p2polls/poll.php5?id=21

Every link is dead.

Funnily enough, I don’t think they intentionally took the polls down. My guess is that a backend update broke them without anyone noticing. That is because most of the URLs return 500 Internal Server Error rather than 404 Not Found:

After entering http://www.gameslice.com/p2 into the Wayback Machine and going to its URLs section, I found that one poll had been fully archived, including its font and style:

That was great because even one surviving poll gave me enough to reproduce the original style and layout.

I then needed the rest of the contents. I found a PDF version containing the rest of the questions through chapter 13, so I noted them all down.

And here’s the problem: chapter 14, which was added in a later update, contains two polls. As far as I know, neither question has been archived anywhere. I spent about two hours searching and found nothing. Every PDF, review, and recording I found, including the iPad version, only covered content through chapter 13.

I even found an edition of the book distributed through Amazon. Surprisingly, it included chapter 14, but because it was a text-only offline e-book, it had no polls.

If you have any old recordings, screenshots, or anything else that could help me recover those two polls, please, please, please contact me.

While I’m at it, there’s one more thing from chapter 14 that I couldn’t recover, which appears to be a subscription form:

• Chapter 14, page 10 — Subscription form: http://geoffkeighley.com/p2polls/subscribe/index.php5

Feedback form

At the end of the book is a feedback form. It’s the only online feature that still loads as intended:

But submitting a new comment leaves it stuck in a review queue.

As with the polls, I could copy the original HTML and CSS. But then what about all the old comments? What would happen to them after this last working part inevitably shuts down?

I decided to take care of that too. A Python script fetched every paginated feedback page from the old Gameslice server, parsed each comment’s author, text, and timestamp, and saved the results to a CSV for import into the replacement server. In total, I backed up 2,662 comments.

A local exception: panoramas

The panoramas are different from the other broken features because their assets are local, so nothing needs to be rehosted.

Despite that, all three panorama viewers have stopped working on current versions of Windows 11. Interestingly, they still work on an older Windows 10 build, even when both installs are running the same version of Adobe AIR.

I could consistently reproduce two errors on the newer, broken system:

• Error #3207 appeared around the existing Security.allowDomain("*") calls.
• Error #3226 appeared while loading compiled code from a nested SWF without allowCodeImport.

I don’t know exactly what changed between those Windows builds to make the same AIR code hit these errors. My best guess is that newer sandbox behavior interferes with the way HTMLLoader embeds the nested SWF.

What I do know is the fix, which is replacing HTMLLoader with a native Loader and explicitly allowing code imports. That makes all three panoramas work again. I again used GPT-5.6-Sol to figure that out since I have no knowledge about Flash.

What now?

My initial server

I had recovered the external content and figured out how to repair the local panoramas. But how could I actually put everything back?

My first goal was to stitch together a server that rehosted everything, just to see whether the concept would work.

I chose Python and FastAPI for the stack because that’s what I’m familiar with.

To redirect the original requests to my computer, I used the hosts file, which tells the system where to find each domain. I modified it so every domain contacted by the e-book pointed to my own computer. That included youtube.com, thefinalhoursofportal2.com, and more.

I then mounted all the static assets at their original paths, including the custom YouTube recreation, and started the server.

I also needed somewhere to store comments and poll data, so I used a basic SQLite database to make everything persistent.

After some troubleshooting, I got everything working!

And this was the result:

The public server

The finished server is available at github.com/nikolan123/TFHoP2-server for anyone to download and self-host.

The next problem was distribution. I couldn’t bundle 600 MB of video and a collection of copyrighted songs. Doing so would make the open-source server much harder to distribute and create obvious legal problems.

The fix was simple enough. Instead of serving the audio myself, I redirected the client to the original preview URLs.

For the YouTube videos, I uploaded them to Archive.org and redirected the client to the reuploaded MP4 files rather than serving them myself.

The server is available for anyone to self-host, including as a Docker image.

Streamlining the patching process

Redirecting requests through the hosts file is a messy solution. Among other problems, it also breaks YouTube.

A better approach was to change the SWF files themselves to use the custom URL.

The patcher locates the three SWF files that need modification, backs them up, decompresses them, and reads the URL strings stored in their compiled ActionScript. It changes only a specific list of retired services, then rebuilds and verifies the SWFs before replacing the originals with the patched versions.

Patching the panoramas was more complicated because the fix required actual ActionScript changes, not just replacing URL strings. To keep the process simple and fast, I generated a diff between the original SWF and my recompiled, patched version. The patcher applies that diff to the user’s copy.

It’s open source at github.com/nikolan123/TFHoP2-patcher, with builds available here.

It consists of two Python files and a few assets. The Python files have no external dependencies, so you can use the patcher by simply running python patcher.py. No extra installation is required.

That’s basically it. You can try it all for yourself with the Steam guide below:

Steam guide: Fix Broken Web Content [Windows] [2026]

Now I can finally go read the book!

This is only my fourth blog post, and I still feel like I’m bad at this. If you have any feedback, questions, or know anything about the two polls or subscription form from chapter 14, please, please, please get in touch through one of the links below.

Also feel free to leave a comment or reaction using the new comment system I just added :3

What is a now page?

While I was researching various options for blog software, I stumbled upon Herman’s Blog, from the creator of Bear. What immediately caught my attention was a button in the header that I hadn’t seen before: now.

It’s a page that is actively updated and shows what someone is currently into or doing. The first thing I asked myself was “why don’t I have this yet?”. In the past, I’ve thought about how the information I put on my website and blog gets outdated too quickly because what I do changes so often. I’ve even thought of a now page as a solution, but always figured the idea was too dumb to actually do.

I was surprised to see that it’s actually a pretty popular thing. There is even a website just for it: nownownow.com, which also has a FAQ page explaining the idea in detail. It has a big listing of now pages, including 8 from Bulgaria. I will soon be the 9th!

My Implementation

After seeing that, I knew I had to make one for myself.

My blog is based on Hugo and automatically builds on every commit using workflows.

Making a new page on my blog is very easy. The problem is the update flow. When I’m writing a blog post, I usually start in Apple Notes, then when it’s a bit more mature I transfer it to a draft version of my blog and eventually publish it. Even though I won’t have to write a big blog post every time I update my now page, it would still take time, effort, and a computer to open VSCode, find the file, update it, and commit.

I decided to use Apple Shortcuts to make a shortcut to quickly update my now page. It’s an app that lets you make small scripts using blocks, and those blocks are surprisingly capable. Shortcuts supports variables, HTTP requests, working with JSON, and App Intents, which are actions that installed apps can expose to Siri/Shortcuts. It also integrates well with the Apple ecosystem and is already installed on both my phone and laptop. If you’re an Apple user and haven’t tried it yet, you definitely should.

In about 15 minutes, I managed to make a simple shortcut that pushes a file called now.txt to my blog’s GitHub repo.

I can run that from a Home Screen shortcut on my phone or Spotlight on my Mac. With this setup it takes about 3-5 seconds to start it.

But pushing a single text file doesn’t automatically update my blog. To fix that, I updated my existing build script to read the text file and generate a JSON file with the status itself, when it was last updated, and how many times it changed in the last month.

By placing generated JSON like this in Hugo’s data/ directory:

{
  "content": "new page testing",
  "updatedAt": "2026-06-27T20:54:16.000Z",
  "updatedDate": "Saturday 27th, June 2026",
  "updateCount": 2
}

I can access that data from any template like this:

{{ hugo.Data.now.content }}
{{ hugo.Data.now.updatedAt }}
{{ hugo.Data.now.updateCount }}

And that’s basically all. I have a now page now. You can find it at /now and the blog’s homepage.

This post is on the shorter side, but I’ll hopefully have some longer and more interesting ones up soon.

If you just want to use widgets on modern macOS and don’t care about the rest, the Widget Porting app is available to download at widgets.nikolan.net. This blog post goes over how they work and how I ported them.

Introduction

What are Dashboard Widgets?

I think the original author can describe them better than anyone else. Here’s a video of Steve Jobs introducing Dashboard in OS X Tiger at WWDC 2004:

Now onto my part:

Porting

File Structure

Before explaining how I got these to work, let’s first look at their file structure. At the base, they’re just web apps with some extras.

Just like macOS apps, widgets are packaged in what is called a bundle - essentially a folder meant to look like a file. Apps use the .app extension, while widgets use .wdgt. The widgets’ structure is actually pretty simple.

niko@Nikos-MacBook-Air:~$ tree
.
├── Default.png
├── Info.plist
├── version.plist
├── English.lproj
│   ├── InfoPlist.strings
│   └── localizedStrings.js
├── Images
│   ├── backside.png
│   ├── blue.png
│   ├── pink.png
│   ├── ...
│   └── yellow.png
├── Icon.png
├── Stickies.html
├── Stickies.css
└── Stickies.js

This is the structure of the Stickies widget. Now let’s go over all of the files and what they do:

Default.png

This image is shown while the widget is loading. After that, the widget overlays HTML elements on top of the image. Yes, most widgets overlay HTML elements on top of images instead of building from the ground up with HTML.

niko@Nikos-MacBook-Air:~$ open Default.png

Info.plist

A plist (short for property list) is basically the file format that Apple uses to store metadata and configuration for apps, widgets, system stuff, and others.

Unlike generic XML, plists have a standardized schema. They also are easier for the system to parse and can be read natively by APIs in Swift and Objective-C, which is why Apple uses them instead of XML.

This specific plist has the widget’s metadata. It can contain information like the widget’s name, author, identifier, window size, permissions, addons, entry HTML file and more.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>CFBundleIdentifier</key>
        <string>com.apple.widget.stickies</string>
        <key>CFBundleName</key>
        <string>Stickies</string>
        <key>CFBundleDisplayName</key>
        <string>Stickies</string>
        <key>CFBundleDevelopmentRegion</key>
        <string>English</string>
        <key>CFBundleShortVersionString</key>
        <string>2.0.0</string>
        <key>CFBundleVersion</key>
        <string>2.0.0</string>
        <key>Height</key>
        <integer>206</integer>
        <key>MainHTML</key>
        <string>Stickies.html</string>
        <key>Width</key>
        <integer>225</integer>
        <key>CloseBoxInsetX</key>
        <integer>11</integer>
        <key>CloseBoxInsetY</key>
        <integer>6</integer>
</dict>
</plist>

version.plist

I couldn’t find much about this file, but it seems to be information about the widget’s version.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>BuildVersion</key>
        <string>5</string>
        <key>CFBundleShortVersionString</key>
        <string>2.0.0</string>
        <key>CFBundleVersion</key>
        <string>2.0.0</string>
        <key>ProjectName</key>
        <string>StickiesWidget</string>
        <key>SourceVersion</key>
        <string>180100</string>
</dict>
</plist>

*.lproj

These are folders which contain a bunch of localized strings in the language that is the folder’s name.

var localizedStrings = new Array();

localizedStrings['Paper Color:'] = 'Paper Color:';
localizedStrings['Font:'] = 'Font:';
localizedStrings['Done'] = 'Done';
localizedStrings['Auto'] = 'Auto';

var localizedStrings = new Array();

localizedStrings['WidgetDisplayName:'] = 'adhésif :';

localizedStrings['Paper Color:'] = 'Couleur du papier :';
localizedStrings['Font:'] = 'Police :';
localizedStrings['Done'] = 'Terminé';
localizedStrings['Auto'] = 'Auto';
localizedStrings['FontSize'] = 'Taille de la police'; // for aria-label of secondary select

Icon.png

The icon of the widget - as far as I know this is only shown in the pane where you add/remove widgets to your dashboard.

Icons of all Widgets bundled with OS X 10.5

The Images folder contains images for use by the widget, and the rest of the files in the root directory are generally the widget’s code.

Trying to load them in a browser

If widgets are just webapps, then you should be able to just open them in a web browser, right? Let’s try it with the Calculator widget.

The calculator widget works perfectly! Out of all of the built-in widgets, only the calculator works without any modifications. Now let’s try Stickies.

Not allowed to load local resource: file:///System/Library/WidgetResources/AppleClasses/AppleAnimator.js ?

These widgets use some shared resources, which are stored at /System/Library/WidgetResources. Modern macOS versions have strict sandboxing, so the web browser isn’t able to access that directory. Even then, those files don’t exist anymore in modern versions of macOS.

Even with all those errors, the base functionality of the widget is still barely there! I can still type normally, although refreshing the webpage resets all contents and none of the other functions work.

I tried to make the widget a little more functional by copying over a real WidgetResources folder from an OS X 10.5 installation.

That WidgetResources folder includes shared resources for things like:

• Logic for switching to the back side (widget settings and stuff)
• UI for buttons, scrollbars, and other elements
• Parsers for some specific widgets (will go into detail later)

After setting up an OS X 10.5 VM in UTM, I copied the WidgetResources folder to my host.

Inside the MainHTML file, the widget tries to load several system scripts:

<script type="text/javascript" src="file:///System/Library/WidgetResources/AppleClasses/AppleAnimator.js" charset="utf-8"></script>
<script type="text/javascript" src="file:///System/Library/WidgetResources/AppleClasses/AppleButton.js" charset="utf-8"></script>
<script type="text/javascript" src="file:///System/Library/WidgetResources/AppleClasses/AppleInfoButton.js" charset="utf-8"></script>

I’m going to remove the file:///System/Library/ part from each line and move the WidgetResources into the .wdgt folder.

It looks about the same, but if you look closely there’s a little square that appears when you hover over the widget. Following the Width and Height elements from Info.plist, that button would be in the bottom right corner of the widget.

Clicking it flips the widget to its backside. The backside lets you change the color of the paper, font family, and size. Some functionality has been successfully restored :D

Windowing Them

Now let’s make this system a bit better and try some more widgets.

First off, let’s fix the square button and make it an “i” like it’s supposed to be. The console shows: Not allowed to load local resource: file:///System/Library/WidgetResources/ibutton/black_i.png.

Even though I modified the code to point to the local WidgetResources folder, this error was actually coming from a file within the folder itself. Those files also use absolute paths to refer to their own resources. Using find and replace to remove all instances of file:///System/Library/ fixed it, and the i button appears instead of a square now!

Now let’s address the window size. Unfortunately, Safari doesn’t let you make the window as small as it should be, so I decided to try a basic WebKit wrapper with custom size controls.

import SwiftUI
import WebKit

struct WebView: NSViewRepresentable {
    let url: URL

    func makeNSView(context: Context) -> WKWebView {
        let config = WKWebViewConfiguration()
        config.preferences.setValue(true, forKey: "developerExtrasEnabled") // enable devtools
        let webView = WKWebView(frame: .zero, configuration: config)
        webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
        return webView
    }
    
    func updateNSView(_ nsView: WKWebView, context: Context) {}
}

struct WebWindow: View {
    let url: URL

    var body: some View {
        WebView(url: url)
    }
}

@main
struct WidgetTestApp: App {
    @State private var path: String = ""
    @State private var width: String = "800"
    @State private var height: String = "600"

    var body: some Scene {
        WindowGroup {
            VStack(spacing: 12) {
                TextField("Path to .html file", text: $path)
                    .textFieldStyle(RoundedBorderTextFieldStyle())
                    .padding(.horizontal)
                HStack {
                    TextField("Width", text: $width)
                        .frame(width: 80)
                    TextField("Height", text: $height)
                        .frame(width: 80)
                }
                Button("Open Window") {
                    openWindow()
                }
            }
            .padding()
            .frame(width: 400, height: 200)
        }
    }
    
    private func openWindow() {
        guard let url = URL(string: "file://\(path)") else { return }
        let w = Int(width) ?? 800
        let h = Int(height) ?? 600
        
        let window = NSWindow(
            contentRect: NSRect(x: 0, y: 0, width: w, height: h),
            styleMask: [.titled, .resizable, .miniaturizable],
            backing: .buffered, defer: false
        )
        window.title = url.lastPathComponent
        window.center()
        window.contentView = NSHostingView(rootView: WebWindow(url: url))
        window.makeKeyAndOrderFront(nil)
    }
}

After pointing the wrapper to the MainHTML file and entering the correct window dimensions, the Stickies widget is fully functional too!

Restoring Dashboard APIs

There is also the Google widget - it originally redirected you to Google search in your default browser. It displays correctly with the same modifications as the previous widget, but does not actually work. Let’s see its code.

In Google.js:

function search (input)
{
  var value = input.value;
  if (value.length > 0)
  {
    value = encodeURIComponent (value);
    var url = "http://www.google.com/search?q=" + value + "&ie=UTF-8&oe=UTF-8";
    if (window.widget)
      widget.openURL (url);
  }
}

The key line here is widget.openURL(url);. That method isn’t a standard JavaScript thing - it is one of the Dashboard’s API functions that help widgets interact with the system.

While it is pretty self-explanatory, its documentation can also be found in Apple’s Dashboard Reference:

Opens the specified URL in the user’s preferred browser.

widget.openURL(url)

This method opens the specified URL and dismisses the Dashboard layer. This method does not permit the opening of URLs that use the file:scheme unless the AllowFileAccessOutsideOfWidgetkey is set in the widget’s information property list file.

However, since we’re not in the original Dashboard environment, it needs to be rewritten to work again. Luckily, WKWebView, which is what I used in the windowed example above, lets me inject my own JavaScript code into the widget.

We can inject our own function that sends the URL back to the host using this code:

let userContentController = WKUserContentController()

let scriptSource = """
window.widget = window.widget || {};
window.widget.openURL = function(url) {
    window.webkit.messageHandlers.openInBrowser.postMessage(url);
};
"""

let userScript = WKUserScript(
    source: scriptSource,
    injectionTime: .atDocumentStart,
    forMainFrameOnly: true
)
userContentController.addUserScript(userScript)
config.userContentController = userContentController

However, that is pointless if we don’t have a way to actually receive what was sent from the widget. Swift’s WKScriptMessageHandler comes in clutch here. It allows receiving messages from JavaScript code running in a webpage.

However, WKScriptMessageHandler by itself isn’t enough - it defines what method must exist, not where that logic should live. In setups such as our own, that logic is typically placed inside a coordinator.

A coordinator is a separate object that acts as a bridge between the WebKit view and the rest of the Swift code. It exists because SwiftUI views are structs and can’t easily conform to Objective-C-based delegate protocols like WKScriptMessageHandler. The coordinator, being a class, can.

class Coordinator: NSObject, WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        if message.name == "openInBrowser", let urlString = message.body as? String,
            let url = URL(string: urlString) {
            NSWorkspace.shared.open(url) // open in browser
        }
    }
}

Instead of creating an instance of the coordinator ourselves, Swift can automatically manage it. We just need to tell it how to make one:

func makeCoordinator() -> Coordinator {
    Coordinator()
}

With that, it automatically creates an instance when the custom WebView is initiated. We can use it as context.coordinator.

Then, right under userContentController.addUserScript(userScript) from our previous code, we register the coordinator as the message handler for openInBrowser: userContentController.add(context.coordinator, name: "openInBrowser").

So the full flow is:

1. SwiftUI starts the custom WebView.
2. The custom JavaScript is injected, including the widget.openURL function.
3. SwiftUI calls makeCoordinator() automatically and creates the coordinator instance.
4. The coordinator is registered with the WebView via userContentController.add(context.coordinator, name: "openInBrowser").
5. The user types a search or triggers an action in the widget.
6. The widget calls window.widget.openURL(url), which posts a message to the openInBrowser handler.
7. The WebView forwards the message to the coordinator.
8. The coordinator receives the message in userContentController(_:didReceive:).
9. The coordinator opens the URL in the default browser using NSWorkspace.shared.open(url).

Now the Google widget is fully functional!

Going back to the Calculator widget, it is now broken. Why did emulating the openURL function break a widget that used to work perfectly?

Looking at the JS console shows: TypeError: undefined is not an object (evaluating 'calc.evaluateExpression'). Looking closer at the code reveals:

if (window.widget)
  result = widget.calculator.evaluateExpression (str, (directInput ? 16 : 8));
else
  result = eval(str);

That snippet checks if the widget is running in Dashboard. Since we recreated the widget object, it thinks it is, so it tries to use another function to calculate the expression. Why did Apple do this? Idk.

The fix is pretty easy:

widget.calculator.evaluateExpression = function(expr, mode) {
    try {
        if (expr === "decimal_string") return ".";
        if (expr === "thousands_separator") return ",";
        return eval(expr);
    } catch (e) {
        return "ERROR";
    }
};

There’s a few more similar undocumented functions. Kludgets has them all, even though I implemented most of them before I discovered that.

My final app has all functions, both documented and undocumented, recreated to the best of my abilities. Here are some notable ones:

• widget.system - Allows the widget to run shell commands. I added a basic permissions system for that too.
• widget.preferenceForKey - Preference system that allows widgets to store persistent data.
• widget.performTransition - Fancy animation for flipping to the back side.
• widget.resizeTo - Resizes the widget as sometimes the back side is a different size.

Here’s 3 resources that also really helped me with that:

1. Apple’s Dashboard Reference - this contains documentation about most of the widget.* functions
2. kludgets’ /resources/scripts/ directory - I discovered this way too late but it was still very helpful, it contained most of the stuff that wasn’t in Apple’s documentation
3. “Find” function in a folder with a bunch of widgets to see what other functions there are and how they’re called

My App

With all of that knowledge, I made an app with a simple interface to help you run widgets on macOS 12.0 or later.

The app automatically handles everything I talked about above - it recreates the Dashboard API, fixes all the path issues, windows the widgets with the correct size, and a bunch more.

Using it is pretty simple - just drag a .wdgt bundle into the app and it’ll handle the rest.

When you drop a widget in, the app copies it to a temp folder and does all the preprocessing automatically - replacing hardcoded system paths, fixing broken script tags, and injecting the JavaScript that makes the Dashboard API work again. Each widget gets its own settings too, so you can tweak things like window size or whether to use native shadows.

Oh, and I recreated the old fullscreen Dashboard UI too!

The whole thing is built with SwiftUI and WebKit, so it’s native and pretty lightweight. Works on macOS 12.0 or later, both Intel and Apple Silicon.

Links:

• Download
• Project Website
• Source Code

Getting the device

Yesterday when I was at my local flea market looking for fun stuff to mess with, this thing caught my eye. It seems to be a Takeaway/Just Eat/Grub Hub/Lieferando payment terminal. More specifically, T-Connect Terminal V2.

This was definitely not the first time I’ve seen one of those, both here and in restaurants, but I remember recently seeing a blog post by Marcel on it, so I decided to get it.

The device has a 7" screen on the front and 2x USB ports, Ethernet port, antenna screw and a DC jack on the back.

Once I got home, I first tried to power it with a 5v TP-Link power adapter. When I plugged it in, the device showed the Takeaway logo, but the backlight started glitching and it shut off.

I suspected this was a power issue, and I was right. Unfortunately, that 5v power adapter was the only one I had that fits. I did not know how many volts the thing needs, it wasn’t written on the label and I could not find that info with a simple Google search, so I asked ChatGPT. It told me it needs 12v, so as my only source I decided to trust that.

I cut the cable of another 12v power adapter I had for an STB and connected those together, resulting in a janky 12v power adapter that fits in the device. To my amazement, it somehow worked.

Hacking the device

Disclaimer: I am dumb. I did not discover most of my stuff myself.

The device booted into some app and seemed to be registered to some doner place. Not wanting to mess with the previous owner’s stuff and potentially get in trouble, I decided to reset it. I couldn’t find a clear way to reset it, so I decided to do some googling. I found a discussion at XDA about it, people found that pressing the bottom left corner 5 times asks for a pin code. 59074 opens an app launcher and 14611 opens a diagnostic menu. Another way to get into another app is via an NFC tag, but this way is easier.

From there I opened settings and did a hard reset. After a few minutes, I was greeted by a welcome screen asking me to activate my device.

I couldn’t do anything from there other than open the Wi-Fi selector, so I decided to use the same menu again. I then tried to do what Marcel did on his device and used a USB to install a few apps, including a new launcher. The Cyanogen file browser could not see the external storage, and I could not open the USB drive through the notifications panel because mine didn’t work for some reason. I thought I was stuck, but it turned out I could browse the drive from the settings app and copy the APKs to the internal storage, then use the Cyanogen file browser to install them.

I then installed some APKs, more specifically AIDA64, Firefox, Niagara launcher, Power Menu (since there are no physical buttons), RD Client, Minecraft PE and Xash3D.

I set the default launcher to Niagara and uninstalled the terminal client app. Now it’s basically just a cut-down android tablet.

Misusing the device

AIDA64 reported the device having a Snapdragon 210, 1GB RAM and 4GB of usable space. It runs Android 6. My next goal was to get Minecraft and Half-Life running.

Minecraft was easy. I just copied over an old APK from archive.org, and installed it. It worked great, ran at about 40 FPS and I was able to control it with my USB keyboard and mouse.

YouTube demonstration

(the screen recorder puts additional load on the poor thing, the game performs worse than usual in the recording)

For Half-Life, I decided to use Xash3D. Even though that version is deprecated, I still decided to use it. I installed Half-Life on my laptop, then copied the valve folder from the installation directory onto my USB stick as well as the Xash3D APK File.

I then made a folder called .halflife in the internal storage and copied the valve folder from the USB stick there. After opening Xash3D, I pressed start without touching a single setting. To my surprise, it worked flawlessly, and even ran at above 60 FPS most of the times.

YouTube demonstration

(the screen recorder puts additional load on the poor thing, the game performs worse than usual in the recording)

Thank you for reading this to the end. This is my first ever blog post, if you have any questions or feedback, feel free to contact me.