The problem shape determines the extension shape

Extension systems get over-engineered when teams copy the design of one trust model into another. The key variable is: who writes extensions, and who runs them?

yyzTools' SDK targets the third row: a developer wants a small tool — "quick-open the ticket system", "calculate quotes" — for themselves or their team. The deployment unit is "copy a folder to your own machine". That context frees the design from nearly all the security machinery, and what remains can be genuinely minimal.

Piece one: the declarative host

The scariest part of desktop development for a web developer isn't logic — it's windows. Message loops, DPI, taskbar, hotkeys. The SDK's move is to reduce the entire host to a data file:

{
    "id": "my_tool",
    "type": "web",
    "name": { "en": "My Tool", "zh_cn": "我的工具" },
    "icon": "fas fa-wrench",
    "url": "MyTool/index.html",
    "width": 760,
    "height": 540,
    "layoutType": 34
}

The host application scans module files at startup and creates a native window with an embedded WebView for each type: "web" entry. Window size, icon, the multilingual name, load path — all declared, none coded. (That's the real sample file trimmed, not an idealized sketch — the shipped sample carries all twelve language names.)

What makes this more than a config file trick is that the module inherits the host's integration surface: command palette search (localized across all 12 UI languages), global hotkey binding, dock mounting, theme variables (--zen-* CSS custom properties injected by the host). The extension author writes a feature; the host absorbs the decade of Win32 plumbing.

The generalizable principle: when your extension format can express "what the host should do for me" declaratively, integration cost drops from per-extension work to per-host work.

Piece two: the JS bridge with a disciplined wrapper

The webpage talks to the system through a window.Zen bridge, but — critically — the official guidance is that nobody calls the bridge raw. Everything goes through a shipped ZenAPI wrapper class.

Why the hard rule? Because native bridges have type semantics that leak — and because those semantics change as the host matures. The case study is instructive in both directions. Early on, the C++ side had two JSON serialization paths (hand-rolled strings and property trees) whose error and boolean conventions disagreed, and the wrapper's isOk() was the one place normalizing them. Later, the host unified serialization into a typed tree — error codes became real numbers, booleans became real booleans — and because every module consumed the bridge exclusively through the wrapper, that migration touched one file's semantics instead of every extension ever written. (One deliberate exception survives, documented rather than hidden: configuration values stay strings, because the front end has always written them that way.)

The lesson for anyone designing a JS bridge: the wrapper layer is where your serialization model gets paid down — once, centrally — instead of being paid forever by every extension author. Skimp on it and a type-system cleanup becomes an ecosystem-wide breaking change.

Another bridge detail worth stealing: async interfaces implement a slot mechanism — a new request displaces the in-flight one instead of queueing. For interactive search, only the latest request is meaningful; queueing would make the background thread execute a series of immediately-obsolete full-index scans. In human-interface contexts, the correct concurrency semantic for bursts is overwrite, not queue.

Piece three: designed-in degradation

Here's the detail I most want you to take away. The sample module's page, opened directly in a browser (no host, no window.Zen), still works — layout, styles, debounce, rendering. The wrapper detects the missing bridge and takes the exception path, returning error: -1.

This isn't an accident; it's a designed degradation boundary. The consequence: UI iteration happens in a normal browser with normal devtools, at browser speed. Only native-integration testing requires the host. Compare this to extension systems where the only debug target is the host itself, and the value becomes obvious.

Design rule: every bridge-dependent page should have a defined behavior in a bridge-less environment, and that behavior should be "run everything that doesn't need the bridge".

Piece four: the honest trust model

The SDK's native API opens the host's full system capability to modules — file deletion, process creation, window control — with no permission prompts, no sandbox, no undo.

For the personal/team trust model, this is correct rather than reckless: if an attacker can write to your modules directory, they can already drop an executable; a .zenmod disguise adds nothing. And every sandbox layer you don't need is a permission negotiation you'd impose on every module author, in a context where the author and runner are the same person.

The design debt is acknowledged in the docs: a security notice states plainly that module authors must validate inputs and treat irreversible operations with care. And the boundary is explicit — if the project ever builds a public module store, the trust model changes and this design must be rebuilt. Match security to the trust model, not to a checklist.

The whole system in one table

If you want to poke at it

All of this is live: the docs (a quick start plus the full API reference, in English and Chinese — other UI languages fall back to English) and a build-free sample project — a full-disk file search tool, which happens to exercise the suite's new homegrown MFT engine — are at yyztools.com/sdk.html. The sample is four vanilla-JS files and reads in about an hour, including the debounce/out-of-order-discard handling that most search UIs get wrong.

If you're designing an extension system for a tool whose users are its developers, this end of the spectrum deserves a seat at the table next to the heavyweight sandboxes.

Windows tweaks are the dark matter of PC utility software. Every "optimize your PC" tool ships hundreds of them — disable telemetry, clean the right-click menu, kill startup delays — and they all share one property: nobody can audit hundreds of registry edits, so nobody does. You click "Fix All", cross your fingers, and hope the tool's authors were more careful than the average Regedit forum post.

We shipped a System Optimizer in 1.0.8 and gave it 331 tweaks across eight categories. The interesting part is not the number. It's the constraint we imposed on ourselves: every single change must be reversible, from a snapshot, without trusting the tool's own memory of what it did.

Every rule carries a Safe or Caution badge and declares up front whether it needs admin rights or a reboot; the detail view shows the registry key with its current value next to the optimized one, so "what exactly will this change?" is answered before you tick the box.

The rule model

Each tweak is a rule with one of five operation types:

• reg — write a registry value

• keydel — delete a registry key

• svc — change a Windows service

• task — change a scheduled task

• cmd — run a command

The categories map to how people actually want to tune a machine: 73 system rules, 66 privacy, 57 Explorer, 56 shell (this is where right-click-menu cleanup lives — those CLSID entries that accumulate from every app you've ever installed), 36 performance, 20 security, 14 gaming, 9 accessibility.

A health check scans all 331 and reports which ones are not in the "optimized" state. You fix what you want, individually or in bulk. Nothing runs on a schedule behind your back.

Snapshots, not memories

Here's the part worth stealing for your own tool, whatever it edits.

Before applying a fix, the optimizer reads the current value and writes it to a local backup folder (%LOCALAPPDATA%\yyzTools\Backup\). Rollback restores from that snapshot. The critical detail: if the original value cannot be read, the fix refuses to run. A rule that can't snapshot can't apply. That one check eliminates the entire class of "I changed something and now I can't remember what" failures, because you literally cannot make an unrecorded change.

The nastiest operation type is keydel — deleting a registry key. Deleting is the one operation that can't be reconstructed from a single value, so it's doubly constrained:

1. It's only allowed on shell-extension keys (the context-menu handlers — a bounded, well-understood namespace).

2. Before deleting anything, the whole key is dumped to the backup as a snapshot, so rollback re-creates it rather than guessing at it.

There are three protection lists — generated at build time and enforced again at run time — that mark keys which are off-limits no matter what a rule says. And because some rules genuinely need elevation (service changes, HKLM writes), the tool re-launches itself with UAC only for the operations that require it, instead of running elevated from the start.

The rollback flow

The whole lifecycle:

In practice, rollback gets used exactly once per user — usually right after they discover that disabling every animation and service made Windows feel like a spreadsheet instead of making it faster. That's fine. An optimizer people can experiment with is more useful than an optimizer people are afraid of.

The uncomfortable economics of tweaks

One honest note, because the "PC optimizer" category has earned its skepticism: most tweaks don't make a modern machine measurably faster. A registry tweak that trims a menu animation saves milliseconds. The real value of a tweaks tool is closer to configuration — turning off telemetry you didn't consent to, removing context-menu entries from apps you uninstalled years ago, stopping OEM services you'll never use. That's why the health check reports state, not "score". There's no optimization percentage, no big green number that goes up. You see the list, you decide, every change is snapshotted.

That's the product stance in one sentence: a tweaks tool shouldn't promise speed; it should promise that nothing it does is a one-way door.

The System Optimizer ships in yyzTools 1.0.8 alongside a Lightning File Scan & Clean, a Lightning Disk Space Analyzer, and a Lightning Memory Cleaner — free, 12 languages, everything local. If you've written tooling that edits system state, I'd genuinely like to hear what your rollback story looks like; the comment section is open.

The naive version of "live wallpaper" — a borderless fullscreen window playing a video — fails three ways: your icons vanish behind it, clicks hit the video instead of the icons, and the desktop right-click menu dies. Everything interesting about a wallpaper engine is solving for "pixels behind, input through."

The desktop is a window tree

Progman ("Program Manager") is the desktop's root window. Under it lives the icon view (a SHELLDLL_DefView hosting a SysListView32), and the static wallpaper is just Progman's background. To render behind the icons, you need a window that sits in the z-order below the icon view. The shell doesn't hand you one — unless you ask correctly.

The 0x052C handshake

There's an undocumented message — 0x052C, often named WM_SHELLPARENTCHANGING — that you can send to Progman. The shell responds by spawning a WorkerW window for you. The resulting tree gives you a slot below the icons that the shell itself maintains:

Progman
 ├─ WorkerW                ← you SetParent() your window here
 └─ SHELLDLL_DefView       ← the desktop icons stay in front
     └─ SysListView32

Your window becomes a child of that WorkerW: visible on the desktop, behind the icons, and outside the icon view's hit-testing. This is the same trick the classic wallpaper engines use. It is unsupported and undocumented — and has worked for over a decade of Windows versions. The usual caveat applies: it's the shell's window tree, not a public API, so you build recovery paths around it (below).

The 24H2 plot twist

The WorkerW layout is not stable across Windows builds, and this cost me an evening:

• Windows 11 24H2 and newer: the WorkerW you want is a direct child of Progman — one FindWindowEx call under Progman finds it.

• Older builds: WorkerW windows are top-level — you have to enumerate them and take the one whose parent is Progman.

Same goal, different tree shape. Branch on the OS build, or your wallpaper works on your machine and black-screens for your colleagues.

And the spawn is asynchronous: after sending 0x052C you go looking for the WorkerW, and if it isn't there yet, you send and look again — a bounded retry loop, because SendMessage returns before the shell has finished rearranging its windows.

The web part: WebView2 in composition mode

yyzTools' wallpaper content is a WebView2, so web pages, HTML files, and local videos all work as wallpaper. But WebView2 doesn't hand you a child HWND to SetParent. The composition route: create a desktop window target on your host window (ICompositorDesktopInterop::CreateDesktopWindowTarget), then give the WebView2's composition controller a root visual target (ICoreWebView2CompositionController::put_RootVisualTarget). The browser renders into your visual tree; your window is the host that gets re-parented under the WorkerW.

Input: click-through by default, interactive on demand

The host window carries WS_EX_TRANSPARENT, so desktop clicks, rubber-band selection, and the right-click context menu all fall through to the icons. But interactive wallpapers need mouse events. So:

• A Raw Input listener receives mouse events globally without installing any hook — faster, and no hook-chain conflicts with other software.

• A hit-test decides whether the event actually landed on the desktop — the window under the cursor is the icon layer (or the wallpaper's own window). Events aimed at normal applications are ignored; your wallpaper must never eat a click meant for a fullscreen app.

• Desktop events are forwarded into the composition controller (SendMouseInput) with client coordinates, which makes the page interactive.

Be a good citizen: sleep when covered, die cleanly, restore

A wallpaper that renders 24/7 is a space heater. The engine watches for coverage — fullscreen apps (the OS notification state reports D3D fullscreen or presentation mode) or the work area fully occluded by normal windows, checked on a coarse grid — and suspends the WebView2 whenever nobody can see the desktop, resuming on reveal. "Game mode" is exactly this machinery with a manual switch.

Explorer restarts destroy the WorkerW, and your window gets silently re-parented into limbo. A health check (is my ancestor still the WorkerW?) detects it; the wallpaper process exits on its own, and a watchdog relaunches it and re-embeds it in the fresh tree. On exit, the engine restores the static system wallpaper, so users are never left staring at a black desktop.

Two footnotes from the field. First, only one engine can own the WorkerW slot — embedding politely terminates whatever other processes have parked there (if you've ever run two wallpaper apps at once, you know why). Second, WebView2's renderer process creates its own fullscreen helper window that occasionally sits too high in the z-order and eats clicks; the fix is force-adding WS_EX_TRANSPARENT to it, and both the wallpaper process and the main app carry that patch, belt and suspenders.

That's the party-trick module — one of 40+ in yyzTools, free at yyztools.com. The wallpaper engine ships with web, video, and HTML wallpapers, slideshows, and a countdown widget pinned above it all.

The constraint

No store, no silent channel. Users download from the website or GitHub Releases, sometimes through third-party mirrors that proxy GitHub and cache aggressively. An update that says "re-download the installer" is an update users don't install — and an asset replaced in place is an asset whose cached copies now lie to people.

Split by what changes

The install isn't one blob. It's nine packages, cut along the lines of what actually changes together:

The web package is the hero of this story. UI fixes, copy changes, new feature pages — the most frequent kind of release — touch exactly one small package.

Two version numbers, two jobs

Every release has a release number — the identity. The GitHub tag, the installer filename, everything user-facing derives from it, and it increments on every release.

Every package has its own content version, which increments only when that package's contents actually change. Fixed a CSS bug? web bumps; ffmpeg doesn't. The rule that took longest to internalize: never bump an unchanged package "for the release." Bumping main because you shipped v1.0.5 re-downloads an identical binary for everyone — the content version is a promise that the bytes changed.

The manifest resolves each package to its own version

The update manifest points every package at its own versioned URL:

web      → /v1.0.5/web.7z
ffmpeg   → /v1.0.2/ffmpeg.7z       ← unchanged since v1.0.2
rapidocr → /v1.0.3/rapidocr.7z
...

An unchanged package resolves to the identical file it resolved to last release. The updater compares versions, downloads only the minority that moved, and the user's delta is proportional to the change — not to the app's size.

Releases are immutable

A release, once published, is never overwritten: the uploader checks whether the release already exists and skips. This isn't politeness; it's cache hygiene. Mirror proxies cache by URL. Replace an asset in place and you split the world into users-with-old-bytes and users-with-new-bytes under the same URL — undebuggable. Immutable releases mean every URL in history serves the same bytes forever, so caches can be as aggressive as they like.

The build side leans on the same property: a package whose version directory already exists in the build output is skipped, not re-packed. Packing is effectively content-addressed.

Two invariants (both learned the hard way)

1. A changed package's version must equal the release number. Otherwise it gets packed under its own version directory while the uploader looks under the release directory — the package exists in the build, misses the upload, and users receive an update that 404s.

2. An unchanged package's version must correspond to some past release. Since it will be fetched from a historical URL, that URL has to exist. A brand-new package aligns its first version with the release that introduces it.

Both are preflight checks now, because "the build succeeded" and "the upload contains everything" are different claims.

What it feels like

A typo fix in a settings label: the web package, a few hundred KB. An FFmpeg bump for a new codec: one package. Refreshing OCR models: one package. The full 150 MB only crosses the wire on first install — where it belongs.

The cost of all this is bookkeeping: a version map, a packer, an uploader, and checks to keep them honest. For an indie-scale app it's the difference between shipping a fix the same day and batching it for weeks because a release "isn't worth a full download."

yyzTools is a free download at yyztools.com — and thanks to the above, keeping it current is cheap.

The problem with "just search the disk"

The obvious approach to file search is what FindFirstFile/FindNextFile recursion gives you: walk every directory, look at every file. On a drive with a million-plus files, that's minutes of disk thrashing — and it has to happen per query.

Everything-class search is fast for one reason: it doesn't search the disk. It searches an in-memory index, and it has clever ways to keep that index built and fresh. The three mechanisms:

1. $MFT — how you enumerate the entire volume in one sequential read
2. The USN journal — how you track changes after the initial build
3. A compact in-memory index — how it all fits in a few MB instead of a few hundred

Let's take them one at a time.

1. The $MFT: NTFS's census book

NTFS keeps a table called the Master File Table. Every file and directory on the volume — every one, including NTFS's own metadata files — has exactly one record in it. Each record is a fixed 1024 bytes and holds the file's names (yes, plural — hard links mean multiple), size, and timestamps.

Two consequences fall out of this design:

Enumerating the whole volume = reading one file sequentially. $MFT is just a file. Read it start to finish and you've seen every file on the disk — no directory traversal, no permission checks, no per-file syscalls. One pass of sequential IO. That's the "secret" behind sub-second full enumeration, and it's exactly the channel Everything and WizFile use.

You need the file's identity, not its path. Each record has a File Reference Number (FRN): a 64-bit value that is sequence_number << 48 | record_index. The sequence number increments when a record is reused — which is why you must keep the full 64 bits. Truncating to 32 bits works right up until NTFS reuses a record and your index confidently conflates a deleted file with a new one.

Fun trap for the implementer: there's a documented API that seems made for this — FSCTL_ENUM_USN_DATA. It hands you FRNs file by file. Tempting, but wrong-shaped for a full build: USN records carry no size or timestamps, so you end up issuing a FSCTL_GET_NTFS_FILE_RECORD call per file to fill in the gaps. In the yyzTools implementation, 1.34 million files took 120 seconds that way. Direct $MFT scanning does the same job in seconds. The lesson generalizes: when you need bulk data, find the channel where that data is already laid out contiguously.

2. The USN journal: NTFS's append-only changelog

You can't rebuild your index from scratch every boot. NTFS provides the Update Sequence Number journal — an append-only log of filesystem changes (creates, deletes, renames, data writes). Each record has a monotonically increasing USN, and the journal as a whole has an ID.

The standard architecture:

1. Build the full index by scanning $MFT. Record an anchor: the journal's ID plus the NextUsn at a known moment.
2. Periodically read the journal from the anchor forward, applying each change to your index.
3. Update the anchor.

Two failure modes you must design for:

The enumeration-window bug. Your full scan takes seconds. Files change during the scan. If your anchor is the USN you read after the scan finishes, changes from mid-scan fall in a dead zone: the scan may have missed them (they weren't on disk when it passed), but the journal replay starts after them. They're gone from your index — silently, forever. The fix is counterintuitive but strict: take the anchor before you start enumerating. You'll replay a few changes redundantly; that's idempotent and harmless. Missing is not.

Journal death. The journal is a fixed-size circular buffer — old records get overwritten — and admins can delete and recreate it (the ID changes). So the anchor must store the JournalId, and on mismatch you throw away incremental catch-up and do a full rebuild. Boring, correct, and non-negotiable.

3. Fitting it in memory: the columnar trick

Here's the part I find most elegant, because it's not really an algorithm win — it's a layout win.

A million files, each with a name, size, and mtime. The obvious representation is a list of objects: {name: string, size: u64, mtime: i64}. For C++ and JS developers alike, that means per-object overhead: string headers, heap allocations, padding, pointer-chasing on every scan. That layout costs a hundred-plus MB for a 1.34M-file volume.

The alternative is columnar: one tight array per attribute.

frns:     [ u64, u64, u64, ... ]
sizes:    [ u64, u64, u64, ... ]
mtimes:   [ u32, u32, u32, ... ]   // Unix seconds: 1970–2106 fits fine
nameOffs: [ u32, u32, u32, ... ]   // offset into the blob
nameLens: [ u32, u32, u32, ... ]
nameBlob: "package.json新建文件夹index.js..."   // interned, deduplicated

No per-row overhead. Sequential scans touch pure contiguous memory. And the name pool deduplicates — "New folder" and "package.json" each exist once for the whole disk, with every row referencing them by an 8-byte offset+length slice.

Frontend folks will recognize this instantly: it's AoS-to-SoA, the same move as replacing an array of objects with one TypedArray per column in a hot loop.

From there, the compounding tricks:

• Time collapses to u32 — Unix seconds, domain clamped to 1970–2106. Half the bytes, zero practical loss.
• Lowercase names often don't exist. Case-insensitive search wants folded names, but if a filename is already all-lowercase (most are), a per-row flag bit makes the lowercase view read the original blob. Saves an entire duplicate name pool.
• Derived data isn't stored at all. Need the parent directory? Derivable from a row-number tree at query time, so it's absent from the snapshot.
• Persistence via mmap. Snapshot the columns to a file; on boot, map it and point your column pointers at the mapped pages. Zero-copy, O(1) open — and the query acceleration structures (e.g., an ASCII bigram inverted index, delta-compressed) get materialized into the same snapshot so nothing rebuilds at startup.

Net result in the yyzTools engine: the full-disk index holds a few MB of resident memory, versus the hundreds of MB a separate indexing service costs.

Putting it together

None of these pieces is exotic. The craft is in the composition — and in the dozen unglamorous edge cases (hard links, record fixups, mapped-file replacement semantics, page-fault prefetching) that each get to cost you a week if you skip them.

Try it

All of this shipped in yyzTools 1.0.5 — a free, local-first Windows suite where the command palette's f prefix gives you this engine, with Everything-compatible syntax (ext:pdf size:>100mb dm:today). If you're curious about any layer in more depth — the query AST, the delta-overlay merge, or the parallel scan pool — ask in the comments and I'll write the follow-up.

The list: English, Simplified and Traditional Chinese, Japanese, Korean, French, German, Spanish, Russian, Arabic, Portuguese, Italian. Arabic means right-to-left. Traditional Chinese is not a feature-flag away from Simplified. And the installer, the website, and the app must agree on what things are called — or users conclude the product is sloppy in a language they read better than you do.

Load only the locale you need

Every feature page is its own bundle, and locales are lazy: on launch, a page loads the active locale and one fallback — nothing else. Each language is a separate chunk, fetched on first switch and cached afterwards. The consequence: the app's startup weight is identical at 2 languages or 12. Adding a language costs its own chunk and never anyone else's bundle.

A three-tier fallback that makes legacy free

Module and config text resolves like this:

current language → English → whatever string is literally there

That last tier is the one I'm proudest of, because of what it buys: any entry can still be written as a plain string — {"name": "关于"} — and it just works, in every language, forever. Old data files, quick internal tools, a contributor who speaks one language: none of them ever see a validation error about missing keys. Backward compatibility isn't maintained here; it's structural.

Store IDs, not words

My favorite rule in the whole system: the config file stores IDs; words are derived at runtime.

A dock entry or a hotkey binding records an appId — never the display name, never the icon. Display text comes from i18n at render time. The presence of a name field means exactly one thing: the user typed it themselves, so show it verbatim and stop translating.

The alternative — snapshotting names and icons into config — feels harmless until a user switches language and their dock shows two-week-old English labels next to fresh Japanese ones. IDs are language-independent, so usage statistics keyed by ID survive a language switch too: your "most-launched apps" chart doesn't reset when you move countries and change languages.

First-run language is detected from the system UI language and mapped to the nearest supported locale — Simplified vs. Traditional Chinese decided by the system's regional subtype. The installer deliberately writes no language preference: the app figures it out on first launch, so a German user who installs through an English-language session still ends up with a German interface.

Right-to-left without a second stylesheet

The website fully renders Arabic, and the discipline that makes it cheap is CSS logical properties everywhere: margin-inline-end, padding-inline-start, border-inline-start, text-align: start. Direction comes from the document; layout mirrors itself. The site's stylesheet carries exactly one [dir=rtl] special case — a single absolutely-positioned dropdown that couldn't be expressed logically. One. If you find yourself writing a mirrored stylesheet, you've almost certainly missed a logical property.

The boring 20%: keeping 12 files honest

Twelve locale files drift. A key renamed in the base, a {{count}} placeholder typo'd in Portuguese, an array that grew in Japanese — any of these ships a broken page in one language while the other eleven look fine and you never happen to open the broken one.

So it's scripted: a check compares every locale against the base on three axes — key trees identical, {{placeholders}} identical per key, array lengths identical — and it runs in CI, not in hope. The same discipline keeps the three surfaces (app, installer, website) aligned: one language list, defined once, referenced everywhere.

Is it perfectly DRY? No — twelve files must each be fully written; translation work doesn't compress. But the failure modes compress to zero, which is what actually matters at 3 a.m.

If you use yyzTools in a language I've mangled, the GitHub tracker linked from yyztools.com takes corrections gladly — and the download, as always, is free.